Implementation review: PB-044, PR 689

Field	Value
Backlog item	PB-044 Agent queue pruning and dead-job requeue (feature FEAT-ORC-02)
Pull request	#689, merged as b6b9408f
Package	pr-ready/PB-044.md
Reviewer	Engineering quality review thread. It gave #689 its quality verdict but didn't write it.
Date	2026-10-26
Environment	Linux container, main b5ca9711, Python venv for the engine. No tenant, no Windows, no long-running agent.

Outcome#

Accepted with Documented Limitations (recommended).

All three backlog criteria and the package's test list are met, with tests that fail on the code before #689. The package's manual check (section 13: a job that fails three times, requeued, seen running again with agent status) hasn't been run, and the agent itself has never run against a live tenant (FEAT-ORC-02).

Recommended by: Engineering quality review. Decided by (product owner): Chris, "I accept all 4" on 2026-10-26 (project message cmsg_018T4o2pQdpbLBNhHpgVNNGpREfN9JPWyocAdUEQR2tzj9), which took this outcome.

Acceptance criteria#

#	Criterion (copied from the backlog item)	Result	Evidence
1	Finished jobs older than the retention are removed on start	Met	`test_agent_prunes_at_start_and_then_daily` (sidecar/tests/test_agent.py): the agent prunes when it starts and again a day later (`agent.prune_queue`). `test_prune_removes_old_finished_jobs_and_keeps_the_rest`: old succeeded, failed and cancelled jobs go; queued, running, dead and recent jobs stay; a dry run deletes nothing.
2	fabric-desktop agent requeue <id> moves a dead job back to queued	Met	`test_requeue_puts_a_dead_job_back_with_its_attempts_reset` (attempts back to 0, `requeued_by` set) and `test_cli_requeue_and_prune` (the CLI command and `agent prune --days --dry-run`).
3	Tests cover both	Met	8 new tests; `pytest tests/test_agent.py`: 38 passed on main. Swapping in the pre-#689 `jobqueue.py`, `agent.py`, `agent_config.py` and `cli.py`: all 8 fail, the 30 older tests pass.

Checks#

Check	Result	Evidence or note
Scope matches the item and package	Met	Package section 11 also asks that requeue of a running job is refused: `test_requeue_refuses_jobs_that_are_not_dead_or_failed` covers queued, running and succeeded. #689 also refuses a `pipeline:` dedupe job and a job with a newer queued or running run (`test_requeue_refuses_a_pipeline_job_and_one_with_a_newer_run`); docs/agent.md says why.
New tests fail without the change, pass with it	Met	As criterion 3.
Full suites pass (pytest, UI, cargo)	Partly	test_agent.py passes here (38). #689 changes no UI or Rust; cargo isn't buildable in this container (no gdk-3.0).
Reachable where docs say; Preview behavior right; packaged into the engine	Met	`fabric-desktop agent requeue` and `agent prune` (docs/agent.md queue section); `queue_retention_days` in deploy/agent.example.toml. Engine-only change.
OneLake data safety	Met	Prune deletes local SQLite queue rows only, in one transaction; dead jobs are kept for a person to requeue or inspect. Nothing reaches OneLake.
Authentication and distribution	Met	No new scope or sign-in. Both commands write an audit row.
No unproven local-equals-Fabric claim; Preview tags kept where untested	Met	FEAT-ORC-02 keeps "Never run against a live tenant".
Docs match the code; linked; strict docs build passes	Met	docs/agent.md and docs/user-guide.md match `jobqueue.requeue` and `prune`; `queue_retention_days` minimum 1, default 30 (`test_config_checks_queue_retention_days`). zensical build --strict clean.
Accessibility of new controls	n/a	CLI only.
Inventory and backlog updated; `product_data.py` consistent	Partly	#689 updated FEAT-ORC-02 in FEATURE_INVENTORY.md only, not in FEATURE_INVENTORY.json, so the next render (merge of #720) put back "Queue never pruned" and "No command to revive a dead job". This review's branch restores it in the JSON. PRODUCT_BACKLOG.md still lists PB-044 as Proposed (line 442).

Findings#

#	Severity (blocking / should fix / note)	Finding	Where	Status
1	should fix	FEAT-ORC-02's update from #689 was lost on main: it was made in the generated Markdown, and the JSON source kept the old text. #685 (FEAT-FAB-06) and #721 (FEAT-GOV-04) had the same problem.	docs/product/FEATURE_INVENTORY.json	Fixed on this review's branch (JSON updated, tables rendered)
2	should fix	`product_data.py check` doesn't compare the generated tables with what `render` would write, so a hand edit inside the generated markers passes the check and is lost on the next render.	docs/product/tools/product_data.py	Open: proposed to the product data owner
3	note	PB-044's backlog state is still Proposed although #689 implemented it.	docs/product/PRODUCT_BACKLOG.md line 442	Open: set it with the product owner's decision

Documented limitations (only for Accepted with Documented Limitations)#

Limitation	Where users are told	Backlog item that tracks it
The package's manual check (requeue a dead job and watch it run with `agent status`) hasn't been run on a running agent.	FEAT-ORC-02 known limitations ("Never run against a live tenant")	The tenant smoke test (FD-101, readiness gate G1), FEAT-ORC-02's next action

Inventory and backlog changes#

Features changed: FEAT-ORC-02: limitation, next action and #689 restored in FEATURE_INVENTORY.json and rendered.
Backlog item state: PB-044 Proposed → Accepted, on the product owner's decision.