crewly 1.6.4 → 1.6.5

package/dist/cli/backend/src/services/task-pool/task-pool.service.js

@@ -11,8 +11,28 @@
 import { PoolStorage } from './pool-storage.js';
 import { ClaimService } from './claim.service.js';
 import { LoggerService } from '../core/logger.service.js';
-import { isWorkItem, isValidWorkItemTransition } from '../../types/v2/work-item.types.js';
-import { createTaskClaim, PROJECT_TASK_LEASE_DURATION_MS, } from '../../types/v2/claim.types.js';
+import { formatError } from '../../utils/format-error.js';
+import { isWorkItem, isValidWorkItemTransition, isTransitionPermitted } from '../../types/v2/work-item.types.js';
+import { createTaskClaim, } from '../../types/v2/claim.types.js';
+/**
+ * Structured error thrown by {@link TaskPoolService.removeFromPool}
+ * when an active claim exists and `force: true` was not passed.
+ */
+export class WorkItemClaimedError extends Error {
+    workItemId;
+    claimId;
+    claimedBy;
+    constructor(args) {
+        super(`WorkItem '${args.workItemId}' has an active claim ` +
+            `(claimId='${args.claimId}', claimedBy='${args.claimedBy}'). ` +
+            `Pass { force: true } to delete anyway (will revoke the claim).`);
+        this.name = 'WorkItemClaimedError';
+        this.workItemId = args.workItemId;
+        this.claimId = args.claimId;
+        this.claimedBy = args.claimedBy;
+        Object.setPrototypeOf(this, WorkItemClaimedError.prototype);
+    }
+}
 // ---------------------------------------------------------------------------
 // Service
 // ---------------------------------------------------------------------------
@@ -42,11 +62,87 @@ export class TaskPoolService {
     storage;
     claimService;
     logger;
+    /**
+     * Optional EventBus reference — wired via {@link setEventBusService} from
+     * the boot path. When set, {@link addToPool} publishes a `workitem:queued`
+     * event so subscribers (notably {@link RequestSlaSubscriber}) can react to
+     * queue mutations. Optional because singleton callers (tests, CLI) bring
+     * up the pool before the bus exists; missing bus is treated as a no-op
+     * publish at warn level.
+     */
+    eventBus = null;
+    /**
+     * Optional Request-linker reference — wired via {@link setRequestService}
+     * from the boot path. When set, {@link addToPool} pushes the new WI's id
+     * into the parent `Request.workItemIds[]` immediately after the storage
+     * flush, independent of any downstream subscriber.
+     *
+     * P1 Bug B (Pool umbrella WI 72ca743a) intrinsic-link contract:
+     *  - The pre-fix path relied on `workitem:queued` / `task:delegated`
+     *    subscribers (request-sla.subscriber, V3DataService) to backfill
+     *    `Request.workItemIds[]`. Manual / programmatic / cron callers that
+     *    bypass the standard event chain left Requests with
+     *    `workItemIds=[]` even though their WIs were in the pool.
+     *  - The intrinsic path here is the source-of-truth link and runs on
+     *    every `addToPool`. Subscriber-driven linking remains as
+     *    belt-and-suspenders (idempotent — see request.service.ts:328
+     *    short-circuit on duplicate id).
+     *  - Optional because singleton callers (tests, CLI) bring up the pool
+     *    before RequestService exists; missing linker is a no-op debug log.
+     */
+    requestService = null;
+    /**
+     * Serializes claim operations to prevent the race where two concurrent
+     * claimFromPool / claimSpecificItem calls both select the same queued
+     * WorkItem between their read and write phases. In-process only — does
+     * not protect against cross-process races, but the backend runs as a
+     * single process today.
+     */
+    claimMutex = Promise.resolve();
     constructor(storage) {
         this.storage = storage ?? new PoolStorage();
         this.claimService = new ClaimService(this.storage);
         this.logger = LoggerService.getInstance().createComponentLogger('TaskPoolService');
     }
+    /**
+     * Wire the EventBus reference used by {@link addToPool} to publish
+     * `workitem:queued` events (INBOUND-1.f1). Called from the backend boot
+     * path after both services have been constructed. Idempotent and may be
+     * called with `null` to disable publishing (testing).
+     *
+     * @param bus - The EventBus instance, or null to clear
+     */
+    setEventBusService(bus) {
+        this.eventBus = bus;
+    }
+    /**
+     * Wire the Request-linker reference used by {@link addToPool} to
+     * intrinsically link the new WI into its parent `Request.workItemIds[]`
+     * (P1 Bug B — Pool umbrella WI 72ca743a).
+     *
+     * Called from the backend boot path after both services exist.
+     * Idempotent and may be called with `null` to disable intrinsic
+     * linking (testing). Mirrors the {@link setEventBusService} setter
+     * pattern so the dependency wiring stays uniform and grep-able.
+     *
+     * @param svc - The RequestService instance (or any object satisfying
+     *   {@link IRequestWorkItemLinker}), or null to clear.
+     */
+    setRequestService(svc) {
+        this.requestService = svc;
+    }
+    /**
+     * Chains the given critical section after any in-flight claim operation.
+     * Guarantees FIFO ordering even under concurrent invocation.
+     */
+    withClaimLock(fn) {
+        const prev = this.claimMutex;
+        let release;
+        this.claimMutex = new Promise((r) => {
+            release = r;
+        });
+        return prev.then(fn).finally(() => release());
+    }
     /**
      * Get singleton instance of TaskPoolService.
      *
@@ -70,18 +166,20 @@ export class TaskPoolService {
     /**
      * Adds an execution-ready WorkItem to the pool.
      *
-     * The item must have status 'queued' to be added. Items with other
-     * statuses are rejected.
+     * Accepted statuses:
+     * - `queued`  — ready to run
+     * - `blocked` — waiting on unresolved dependsOn; the resolver will promote
+     *               it to `queued` when every upstream dep reaches terminal success.
      *
      * @param workItem - The work item to add
-     * @throws Error if workItem is not valid or not in 'queued' status
+     * @throws Error if workItem is invalid or in an ineligible status
      */
     async addToPool(workItem) {
         if (!isWorkItem(workItem)) {
             throw new Error('Invalid WorkItem: does not conform to WorkItem interface');
         }
-        if (workItem.status !== 'queued') {
-            throw new Error(`Cannot add WorkItem to pool: status must be 'queued', got '${workItem.status}'`);
+        if (workItem.status !== 'queued' && workItem.status !== 'blocked') {
+            throw new Error(`Cannot add WorkItem to pool: status must be 'queued' or 'blocked', got '${workItem.status}'`);
         }
         // Check for duplicates
         const existing = await this.storage.findWorkItem(workItem.id);
@@ -96,6 +194,287 @@ export class TaskPoolService {
             type: workItem.type,
             title: workItem.title,
         });
+        // P1 Bug B (Pool umbrella WI 72ca743a): intrinsically link the new
+        // WI into its parent `Request.workItemIds[]` if a linker is wired
+        // and the WI carries a requestId. This is the SOURCE-OF-TRUTH link
+        // and runs unconditionally on every successful addToPool, fixing
+        // the bug where manual / programmatic / cron / orchestrator-script
+        // callers that bypass the standard event chain left Requests with
+        // empty `workItemIds[]`.
+        //
+        // Subscriber-driven linking (request-sla.subscriber.ts on
+        // workitem:queued, V3DataService.onTaskDelegated on task:delegated)
+        // continues to run as belt-and-suspenders — `linkWorkItem` is
+        // idempotent (request.service.ts:328 short-circuits on duplicate id),
+        // so double-link is safe.
+        //
+        // Failure isolation: pool mutation is the source of truth. Link
+        // failures are warn-logged and swallowed; subscriber path remains
+        // as a backup, and a future addToPool of the same WI is a no-op
+        // (storage dedup) so retry comes via natural traffic.
+        await this.linkWorkItemToRequest(workItem);
+        // INBOUND-1.f1: announce the queue mutation so subscribers (notably the
+        // RequestSlaSubscriber) can react. We publish AFTER the storage flush
+        // so any subscriber that re-reads via taskPool.findWorkItem sees the
+        // committed item. Publish failures are logged-but-isolated — the pool
+        // mutation is the source of truth, the event is informational.
+        this.publishWorkItemQueued(workItem);
+    }
+    /**
+     * P1 Bug B helper: intrinsically link a freshly-added WI into its
+     * parent `Request.workItemIds[]`.
+     *
+     * Stays a separate method (vs inlining) so:
+     *   1. The dependency on RequestService stays explicit and grep-able,
+     *      mirroring {@link publishWorkItemQueued}.
+     *   2. Future enqueue paths (e.g. a batch addAll) can route through
+     *      the same linker for consistent behaviour.
+     *   3. Error handling stays in one place — a thrown linker must NOT
+     *      back out the pool mutation (the storage write already committed).
+     *
+     * @param workItem - The WI just persisted into the pool.
+     */
+    async linkWorkItemToRequest(workItem) {
+        if (!workItem.requestId) {
+            // No parent Request — nothing to link.
+            return;
+        }
+        if (!this.requestService) {
+            this.logger.debug('No RequestService wired — skipping intrinsic Request link', { workItemId: workItem.id, requestId: workItem.requestId });
+            return;
+        }
+        try {
+            await this.requestService.linkWorkItem(workItem.requestId, workItem.id);
+        }
+        catch (linkError) {
+            this.logger.warn('Bug B intrinsic link failed (subscriber path remains as fallback)', {
+                requestId: workItem.requestId,
+                workItemId: workItem.id,
+                error: formatError(linkError),
+            });
+        }
+    }
+    /**
+     * INBOUND-1.f1 helper: publish a `workitem:queued` event with correlation
+     * ids the SLA subscriber needs (`requestId`, `missionId`, plus the new
+     * `workItemId`). Called by {@link addToPool} after the storage flush.
+     *
+     * Stays a separate method (vs inlining) so:
+     *   1. The dependency on EventBus stays explicit and grep-able.
+     *   2. A future caller adding an alternate enqueue path (e.g. a batch
+     *      addAll) can route through the same publisher for consistent
+     *      observability.
+     *   3. Error handling stays in one place — a thrown publisher must NOT
+     *      back out the pool mutation (the storage write already committed).
+     */
+    publishWorkItemQueued(workItem) {
+        if (!this.eventBus) {
+            this.logger.debug('No EventBus wired — skipping workitem:queued publish', {
+                workItemId: workItem.id,
+            });
+            return;
+        }
+        try {
+            this.eventBus.publish({
+                // Deterministic event id keyed on the WI id so a redelivered storage
+                // path (theoretical) collapses through the bus's per-(type,session)
+                // debounce window without firing the SLA handler twice.
+                id: `workitem:queued:${workItem.id}`,
+                type: 'workitem:queued',
+                timestamp: new Date().toISOString(),
+                teamId: '',
+                teamName: '',
+                memberId: '',
+                memberName: '',
+                // sessionName is empty — `workitem:queued` is a system-level event
+                // not attributable to a specific agent session. The bus's dedup key
+                // is `${type}:${sessionName}` so a unique sessionName per WI would
+                // defeat the dedup; an empty sessionName scoped per-id is fine since
+                // the event id already encodes the WI uniquely.
+                sessionName: '',
+                previousValue: '',
+                newValue: workItem.status,
+                changedField: 'taskStatus',
+                // INBOUND-1.f1 correlation fields. Mandatory: workItemId. Optional:
+                // requestId, missionId — populated when the WI carries them. The SLA
+                // subscriber no-ops when requestId is undefined (per spec), so we
+                // don't need a fallback chain here.
+                workItemId: workItem.id,
+                requestId: workItem.requestId,
+                missionId: workItem.missionId,
+            });
+        }
+        catch (err) {
+            this.logger.warn('workitem:queued publish threw', {
+                workItemId: workItem.id,
+                error: formatError(err),
+            });
+        }
+    }
+    /**
+     * F1-BRIDGE-1 helper: publish `task:done_by_worker` after a successful
+     * `submitForVerification` transition. The {@link EventToWorkItemBridge}
+     * subscribes to this event and creates a verification WorkItem for the
+     * resolved team-lead session.
+     *
+     * Stays a separate method (mirrors {@link publishWorkItemQueued}) so:
+     *   1. The dependency on EventBus stays explicit and grep-able — Arch's
+     *      grep guard checks both the type declaration AND a publish call
+     *      site for `task:done_by_worker`.
+     *   2. Error handling is uniform with the other publishers — a thrown
+     *      bus must NOT back out the verified state transition; the storage
+     *      flush has already committed.
+     *   3. A future caller adding an alternate verification-submission path
+     *      (e.g. an admin endpoint or a CLI) routes through the same publisher.
+     *
+     * The deterministic event id (`task:done_by_worker:${workItemId}`) keys
+     * dedup so a redelivered submitForVerification (theoretical) collapses
+     * through the bus without firing the bridge handler twice.
+     */
+    publishTaskDoneByWorker(workItem) {
+        if (!this.eventBus) {
+            this.logger.debug('No EventBus wired — skipping task:done_by_worker publish', {
+                workItemId: workItem.id,
+            });
+            return;
+        }
+        try {
+            this.eventBus.publish({
+                id: `task:done_by_worker:${workItem.id}`,
+                type: 'task:done_by_worker',
+                timestamp: new Date().toISOString(),
+                teamId: '',
+                teamName: '',
+                memberId: '',
+                memberName: '',
+                // sessionName is empty — `task:done_by_worker` is published from the
+                // pool layer which doesn't carry the worker's PTY session. The bridge
+                // uses `workItemId` (and falls back to `taskId`) to resolve the
+                // source WI; sessionName is informational. Empty matches the
+                // workitem:queued publish convention.
+                sessionName: '',
+                // The state machine just landed at done_by_worker. Carry both ends
+                // so any subscriber filtering on (previousValue, newValue) sees
+                // the canonical transition.
+                previousValue: 'running',
+                newValue: 'done_by_worker',
+                changedField: 'taskStatus',
+                // BRIDGE-1.1 hybrid extension. `workItemId` is mandatory for the
+                // bridge handler; the `taskId` fallback path is unused here because
+                // WorkItem itself does not carry a taskId (the bridge resolves the
+                // source WI by id alone via taskPool.findWorkItem).
+                workItemId: workItem.id,
+                missionId: workItem.missionId,
+                requestId: workItem.requestId,
+            });
+        }
+        catch (err) {
+            this.logger.warn('task:done_by_worker publish threw', {
+                workItemId: workItem.id,
+                error: formatError(err),
+            });
+        }
+    }
+    /**
+     * F1-BRIDGE-1 helper: publish `task:rejected` after a successful
+     * `verifyItem` transition with verdict='rejected'. The
+     * {@link EventToWorkItemBridge} subscribes and either creates a retry
+     * WI (`retryCount < maxRetries`) or escalates to a TL review WI with
+     * `reviewReason='max_retries_exceeded'` at the cap.
+     *
+     * Mirrors {@link publishTaskDoneByWorker} for symmetry. Only the
+     * verdict='rejected' branch reaches this publisher — `verdict='verified'`
+     * does NOT publish (terminal-success path goes through
+     * {@link resolveBlockedDependents}, which is not a bridge trigger).
+     */
+    publishTaskRejected(workItem) {
+        if (!this.eventBus) {
+            this.logger.debug('No EventBus wired — skipping task:rejected publish', {
+                workItemId: workItem.id,
+            });
+            return;
+        }
+        try {
+            this.eventBus.publish({
+                id: `task:rejected:${workItem.id}`,
+                type: 'task:rejected',
+                timestamp: new Date().toISOString(),
+                teamId: '',
+                teamName: '',
+                memberId: '',
+                memberName: '',
+                sessionName: '',
+                previousValue: 'done_by_worker',
+                newValue: 'rejected',
+                changedField: 'taskStatus',
+                workItemId: workItem.id,
+                missionId: workItem.missionId,
+                requestId: workItem.requestId,
+            });
+        }
+        catch (err) {
+            this.logger.warn('task:rejected publish threw', {
+                workItemId: workItem.id,
+                error: formatError(err),
+            });
+        }
+    }
+    /**
+     * Publish `task:cancelled` whenever a WorkItem transitions to the
+     * cancelled status via {@link updateItemStatus} or {@link transitionStatus}.
+     *
+     * **Why this exists.** 2026-05-09 dogfood: 4 child WIs of a Slack-
+     * originated Request all landed in `cancelled` (orc-not-in-health-map
+     * loop, fixed in #531) but the Request stayed in `ready` for hours.
+     * `cascadeRequestStatus` only fires from V3DataService's task
+     * handlers, which are wired to the retired `v3:task_*` events
+     * (`mission-executor.service.ts:152` v1-cleanup comment) — so out-of-
+     * band cancellations never reached cascade. The heartbeat sweep
+     * eventually caught it (#533), but with up-to-30-min latency that
+     * showed up as a misleading "0/4 in every bucket" ping in the user's
+     * Slack thread.
+     *
+     * Publishing `task:cancelled` lets `RequestCascadeSubscriber` close
+     * the Request within seconds of the last child cancelling, instead
+     * of waiting for the heartbeat catch.
+     *
+     * Mirrors {@link publishTaskDoneByWorker} / {@link publishTaskRejected}
+     * so the EventBus surface stays uniform.
+     *
+     * @param workItem - The WI snapshot AFTER the cancelled transition committed
+     * @param previousStatus - The status it transitioned from (for the event payload)
+     */
+    publishTaskCancelled(workItem, previousStatus) {
+        if (!this.eventBus) {
+            this.logger.debug('No EventBus wired — skipping task:cancelled publish', {
+                workItemId: workItem.id,
+            });
+            return;
+        }
+        try {
+            this.eventBus.publish({
+                id: `task:cancelled:${workItem.id}`,
+                type: 'task:cancelled',
+                timestamp: new Date().toISOString(),
+                teamId: '',
+                teamName: '',
+                memberId: '',
+                memberName: '',
+                sessionName: '',
+                previousValue: previousStatus,
+                newValue: 'cancelled',
+                changedField: 'taskStatus',
+                workItemId: workItem.id,
+                missionId: workItem.missionId,
+                requestId: workItem.requestId,
+            });
+        }
+        catch (err) {
+            this.logger.warn('task:cancelled publish threw', {
+                workItemId: workItem.id,
+                error: formatError(err),
+            });
+        }
     }
     /**
      * Claims the next available WorkItem from the pool for an agent.
@@ -111,62 +490,87 @@ export class TaskPoolService {
         if (!agentId || typeof agentId !== 'string') {
             throw new Error('agentId is required and must be a non-empty string');
         }
-        // Check if agent already has an active claim
-        const existingClaim = await this.storage.findActiveClaimByAgent(agentId);
-        if (existingClaim) {
-            this.logger.warn('Agent already has an active claim', {
+        return this.withClaimLock(async () => {
+            // Check if agent already has an active claim
+            const existingClaim = await this.storage.findActiveClaimByAgent(agentId);
+            if (existingClaim) {
+                this.logger.warn('Agent already has an active claim', {
+                    agentId,
+                    existingClaimId: existingClaim.id,
+                    existingWorkItemId: existingClaim.workItemId,
+                });
+                return null;
+            }
+            const workItems = await this.storage.getWorkItems();
+            const claims = await this.storage.getClaims();
+            // Set of work item IDs that have active claims
+            const claimedIds = new Set(claims
+                .filter((c) => c.status === 'active')
+                .map((c) => c.workItemId));
+            // Hygiene #3 — target-respect gate. Before this filter, claimFromPool
+            // would FIFO-pick the oldest queued+unclaimed item regardless of
+            // its existing `target` field, then unconditionally rewrite
+            // `wi.target = agentId` in the transitionStatus mutator. That
+            // produced the target-rotation bug observed in the 5/9 wave (WIs
+            // rotating through Quinn → Sam, Leo → Quinn, etc.).
+            //
+            // After this filter:
+            //   - WIs with an explicit target are claimable ONLY by that target.
+            //   - WIs with no target (broadcast pool) remain claimable by any agent.
+            // The defensive identity check in the transitionStatus mutator
+            // below ensures we never accidentally overwrite an existing target
+            // even if a future code path bypasses this filter.
+            const targetRespectingCandidates = workItems
+                .filter((wi) => wi.status === 'queued' && !claimedIds.has(wi.id))
+                .filter((wi) => !wi.target || wi.target === agentId);
+            // Find first matching unclaimed queued item (FIFO by createdAt)
+            const candidates = targetRespectingCandidates
+                .filter((wi) => matchesFilters(wi, filters))
+                .sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
+            if (candidates.length === 0) {
+                return null;
+            }
+            const selected = candidates[0];
+            // TRANS-2: route the queued → running flip through the guarded
+            // transitionStatus helper so internal callers are subject to the
+            // same V3 actor-role + state-machine gates as external callers.
+            // `startedAt` is set automatically by transitionStatus when
+            // newStatus === 'running'; the mutator carries the agent target.
+            //
+            // Hygiene #3 — target-respect (defensive). The candidate filter
+            // above already excludes WIs whose target ≠ agentId, so the only
+            // remaining cases here are (a) wi.target === agentId (no-op assign)
+            // and (b) wi.target === undefined (broadcast claim). Either way we
+            // refuse to overwrite a non-matching existing target.
+            const claimedItem = await this.transitionStatus(selected.id, 'running', 'system', (wi) => {
+                if (!wi.target) {
+                    wi.target = agentId;
+                }
+                // else: target already === agentId per the filter; leave as-is.
+            });
+            if (!claimedItem) {
+                this.logger.warn('Failed to update WorkItem during claim', { workItemId: selected.id });
+                return null;
+            }
+            // Create the claim
+            const claimInput = {
+                workItemId: selected.id,
+                agentId,
+            };
+            const claim = createTaskClaim(claimInput);
+            await this.storage.addClaim(claim);
+            await this.storage.flush();
+            this.logger.info('WorkItem claimed', {
+                workItemId: selected.id,
                 agentId,
-                existingClaimId: existingClaim.id,
-                existingWorkItemId: existingClaim.workItemId,
+                claimId: claim.id,
+                title: selected.title,
             });
-            return null;
-        }
-        const workItems = await this.storage.getWorkItems();
-        const claims = await this.storage.getClaims();
-        // Set of work item IDs that have active claims
-        const claimedIds = new Set(claims
-            .filter((c) => c.status === 'active')
-            .map((c) => c.workItemId));
-        // Find first matching unclaimed queued item (FIFO by createdAt)
-        const candidates = workItems
-            .filter((wi) => wi.status === 'queued' && !claimedIds.has(wi.id))
-            .filter((wi) => matchesFilters(wi, filters))
-            .sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
-        if (candidates.length === 0) {
-            return null;
-        }
-        const selected = candidates[0];
-        // Transition item to 'running'
-        const updated = await this.storage.updateWorkItem(selected.id, (wi) => {
-            wi.status = 'running';
-            wi.startedAt = new Date().toISOString();
-            wi.target = agentId;
-        });
-        if (!updated) {
-            this.logger.warn('Failed to update WorkItem during claim', { workItemId: selected.id });
-            return null;
-        }
-        // Create the claim (project_task gets extended lease to avoid premature revocation)
-        const claimInput = {
-            workItemId: selected.id,
-            agentId,
-            ...(selected.type === 'project_task' ? { leaseDurationMs: PROJECT_TASK_LEASE_DURATION_MS } : {}),
-        };
-        const claim = createTaskClaim(claimInput);
-        await this.storage.addClaim(claim);
-        await this.storage.flush();
-        this.logger.info('WorkItem claimed', {
-            workItemId: selected.id,
-            agentId,
-            claimId: claim.id,
-            title: selected.title,
+            return {
+                workItem: claimedItem,
+                claim,
+            };
         });
-        // Return the updated item
-        const claimedItem = await this.storage.findWorkItem(selected.id);
-        return {
-            workItem: claimedItem,
-            claim,
-        };
     }
     /**
      * Claims a specific WorkItem by ID for an agent.
@@ -181,33 +585,49 @@ export class TaskPoolService {
         if (!agentId || typeof agentId !== 'string') {
             throw new Error('agentId is required and must be a non-empty string');
         }
-        const existingClaim = await this.storage.findActiveClaimByAgent(agentId);
-        if (existingClaim)
-            return null;
-        const workItem = await this.storage.findWorkItem(workItemId);
-        if (!workItem || workItem.status !== 'queued')
-            return null;
-        const claims = await this.storage.getClaims();
-        if (claims.some((c) => c.workItemId === workItemId && c.status === 'active'))
-            return null;
-        const updated = await this.storage.updateWorkItem(workItemId, (wi) => {
-            wi.status = 'running';
-            wi.startedAt = new Date().toISOString();
-            wi.target = agentId;
+        return this.withClaimLock(async () => {
+            const existingClaim = await this.storage.findActiveClaimByAgent(agentId);
+            if (existingClaim)
+                return null;
+            const workItem = await this.storage.findWorkItem(workItemId);
+            if (!workItem || workItem.status !== 'queued')
+                return null;
+            // Hygiene #3 — target-respect gate. Refuse to claim a WI whose
+            // existing target is set to a different agent. This prevents the
+            // claimSpecificItem path (used by AgentAutoClaimService for
+            // score-based selection) from rotating target onto an idle agent
+            // when another agent is the actual target. Same rule as
+            // claimFromPool: target=undefined (broadcast) is claimable by any
+            // agent; target=agentId is claimable only by that agent.
+            if (workItem.target && workItem.target !== agentId) {
+                this.logger.debug('claimSpecificItem refused — target mismatch', {
+                    workItemId,
+                    existingTarget: workItem.target,
+                    requestingAgent: agentId,
+                });
+                return null;
+            }
+            const claims = await this.storage.getClaims();
+            if (claims.some((c) => c.workItemId === workItemId && c.status === 'active'))
+                return null;
+            // TRANS-2: route the queued → running flip through transitionStatus
+            // (mirrors claimFromPool — same V3 + state-machine gates).
+            // Hygiene #3 defensive: only assign target when it's currently
+            // undefined; never overwrite an existing target.
+            const claimedItem = await this.transitionStatus(workItemId, 'running', 'system', (wi) => {
+                if (!wi.target) {
+                    wi.target = agentId;
+                }
+            });
+            if (!claimedItem)
+                return null;
+            const claimInput = { workItemId, agentId };
+            const claim = createTaskClaim(claimInput);
+            await this.storage.addClaim(claim);
+            await this.storage.flush();
+            this.logger.info('WorkItem claimed (specific)', { workItemId, agentId, claimId: claim.id });
+            return { workItem: claimedItem, claim };
         });
-        if (!updated)
-            return null;
-        const claimInput = {
-            workItemId,
-            agentId,
-            ...(workItem.type === 'project_task' ? { leaseDurationMs: PROJECT_TASK_LEASE_DURATION_MS } : {}),
-        };
-        const claim = createTaskClaim(claimInput);
-        await this.storage.addClaim(claim);
-        await this.storage.flush();
-        this.logger.info('WorkItem claimed (specific)', { workItemId, agentId, claimId: claim.id });
-        const claimedItem = await this.storage.findWorkItem(workItemId);
-        return claimedItem ? { workItem: claimedItem, claim } : null;
     }
     /**
      * Releases a claimed WorkItem back to the pool.
@@ -235,11 +655,14 @@ export class TaskPoolService {
                 c.endReason = reason;
             });
         }
-        // Revert item to queued. Preserve target when unblocking so the
-        // same agent can re-claim via target filter.
+        // TRANS-2: route the (running|blocked) → queued flip through the
+        // guarded transitionStatus helper. The state-machine entry for
+        // `running → queued` is a TRANS-2 addition, gated to system/TL/orc;
+        // `blocked → queued` was already TL/orc/system-gated by TRANS-1.
+        // Side-effect mutations (startedAt clear, target preservation when
+        // unblocking, retryCount bump) move into the atomic mutator.
         const wasBlocked = workItem.status === 'blocked';
-        await this.storage.updateWorkItem(workItemId, (wi) => {
-            wi.status = 'queued';
+        await this.transitionStatus(workItemId, 'queued', 'system', (wi) => {
             wi.startedAt = undefined;
             if (!wasBlocked) {
                 wi.target = undefined;
@@ -254,38 +677,239 @@ export class TaskPoolService {
         });
     }
     /**
-     * Marks a work item as completed ('done').
+     * Decide whether a WorkItem requires TL verification before reaching a
+     * terminal-success status.
      *
-     * @param workItemId - ID of the work item
-     * @param result - Optional result data
-     * @throws Error if work item not found or not in 'running' status
+     * Default policy (VERIF-1):
+     *   - `delegate` items default to *requires verification* — a worker
+     *     marking their own delegated work as "done" should produce
+     *     `done_by_worker` and wake the TL for sign-off.
+     *   - All other types (`cron_run`, `notify`, `reconcile`, `check`,
+     *     `confirm`, `review`, ...) default to simple completion (`done`).
+     *
+     * The default is overridable via `wi.metadata.requiresVerification`:
+     *   - `true`  — force verification path even for non-delegate types
+     *   - `false` — skip verification even for delegate types (this is the
+     *     F-H affordance REVIEW-1 needs: review WIs are themselves the
+     *     verification step, so they must NOT loop back to TL self-verify)
+     *
+     * @param wi - The WorkItem under inspection
+     * @returns true when the verification path should fire
+     */
+    requiresVerification(wi) {
+        const metaFlag = wi.metadata?.requiresVerification;
+        if (metaFlag === true)
+            return true;
+        if (metaFlag === false)
+            return false;
+        return wi.type === 'delegate';
+    }
+    /**
+     * Internal: release the active claim on a WorkItem (if any). Shared by
+     * `completeSimpleItem` and `submitForVerification` because both
+     * represent the worker handing the item back to the system.
+     *
+     * @param workItemId - WorkItem whose claim should be released
+     * @param endReason - Reason recorded on the claim (`completed` /
+     *   `submitted_for_verification`) for auditability
+     */
+    async releaseClaim(workItemId, endReason) {
+        const claim = await this.storage.findActiveClaimByWorkItem(workItemId);
+        if (!claim)
+            return;
+        await this.storage.updateClaim(claim.id, (c) => {
+            c.status = 'released';
+            c.endedAt = new Date().toISOString();
+            c.endReason = endReason;
+        });
+    }
+    /**
+     * Worker reports a delegated WorkItem as done and submits it for TL
+     * verification.
+     *
+     * Transitions `running → done_by_worker` via {@link transitionStatus},
+     * which enforces the V3 actor-role gate (`'agent'` is allowed; any
+     * other role throws). The active claim is released as
+     * `submitted_for_verification` so the TL queue is the only thing
+     * blocking forward progress.
+     *
+     * Used by the `completeItem` facade for `delegate`-type items and any
+     * item whose `metadata.requiresVerification === true`.
+     *
+     * @param workItemId - WorkItem id
+     * @param actorRole - Role of the caller (`'agent'` for normal worker
+     *   submissions; passed through to `isTransitionPermitted`)
+     * @param result - Optional result payload to attach to the WorkItem
+     * @returns The updated WorkItem, or `null` if the WI was deleted
+     *   between the find and the update (race window)
+     * @throws When the WorkItem is missing, the transition is invalid, or
+     *   the actor is not permitted to perform `running → done_by_worker`.
+     */
+    async submitForVerification(workItemId, actorRole, result) {
+        await this.releaseClaim(workItemId, 'submitted_for_verification');
+        const updated = await this.transitionStatus(workItemId, 'done_by_worker', actorRole, (wi) => {
+            if (result)
+                wi.result = result;
+        });
+        await this.storage.flush();
+        this.logger.info('WorkItem submitted for verification', {
+            workItemId,
+            actorRole,
+            // BRIDGE-1 turns this into a real `task:done_by_worker` event below
+            // (F1-BRIDGE-1). The log line is preserved as a wake signal for any
+            // tail-based TL-watching subscriber that still greps it.
+            tlWakeRequested: true,
+        });
+        // F1-BRIDGE-1: publish AFTER the storage flush so any subscriber that
+        // re-reads via taskPool.findWorkItem sees the committed `done_by_worker`
+        // status. `updated` is null only on race-window deletion — skip the
+        // publish in that case (no source WI for the bridge to resolve).
+        if (updated) {
+            this.publishTaskDoneByWorker(updated);
+        }
+        return updated;
+    }
+    /**
+     * Worker (or system) marks a non-delegated WorkItem as fully done.
+     *
+     * Transitions `running → done` via {@link transitionStatus}. Used by
+     * the `completeItem` facade for `cron_run`, `notify`, `reconcile`,
+     * `check`, `confirm`, `review` types — anything whose lifecycle does
+     * NOT include a TL verification step.
+     *
+     * The Reconciler service is the only system-actor caller and uses
+     * `actorRole='system'`, which bypasses the actor check while still
+     * respecting the state-machine legality check.
+     *
+     * @param workItemId - WorkItem id
+     * @param actorRole - Role of the caller (`'agent'`, `'system'`, etc.)
+     * @param result - Optional result payload to attach
+     * @returns The updated WorkItem, or `null` if the WI was deleted
+     *   between the find and the update (race window)
+     * @throws When the WorkItem is missing, the transition is invalid, or
+     *   the actor is not permitted to perform `running → done`.
+     */
+    async completeSimpleItem(workItemId, actorRole, result) {
+        await this.releaseClaim(workItemId, 'completed');
+        const updated = await this.transitionStatus(workItemId, 'done', actorRole, (wi) => {
+            if (result)
+                wi.result = result;
+        });
+        // Promote any blocked dependents whose deps are now all satisfied.
+        await this.resolveBlockedDependents(workItemId);
+        await this.storage.flush();
+        this.logger.info('WorkItem completed', { workItemId, actorRole });
+        return updated;
+    }
+    /**
+     * TL records a verdict on a WorkItem in `done_by_worker` status.
+     *
+     * `verified` advances to terminal success and unblocks dependents;
+     * `rejected` parks the item until the TL re-queues it (which TRANS-1
+     * gates to TL/orchestrator/system actors). Worker-actor calls throw
+     * automatically via {@link transitionStatus}'s permission gate — we
+     * do NOT need to add an explicit role check here, the matrix in
+     * `TRANSITION_PERMISSIONS` handles it.
+     *
+     * @param workItemId - WorkItem id (must currently be `done_by_worker`)
+     * @param actorRole - Role of the caller (`'team_lead'` or `'orchestrator'`
+     *   for verify/reject; worker calls throw)
+     * @param verdict - `'verified'` or `'rejected'`
+     * @param comment - Optional reviewer comment recorded in `wi.error`
+     *   (the field is reused — the WorkItem schema does not yet have a
+     *   dedicated `verifierComment` slot; keeping this on `error` lets
+     *   downstream UIs render TL feedback alongside failure causes)
+     * @returns The updated WorkItem, or `null` on race-window deletion
+     * @throws When the WorkItem is missing, the verdict is invalid, the
+     *   transition is illegal, or the actor is not permitted to verify.
+     */
+    async verifyItem(workItemId, actorRole, verdict, comment) {
+        if (verdict !== 'verified' && verdict !== 'rejected') {
+            throw new Error(`Invalid verdict: "${verdict}". Must be "verified" or "rejected".`);
+        }
+        const updated = await this.transitionStatus(workItemId, verdict, actorRole, (wi) => {
+            if (comment)
+                wi.error = comment;
+        });
+        if (verdict === 'verified') {
+            await this.resolveBlockedDependents(workItemId);
+        }
+        await this.storage.flush();
+        this.logger.info('WorkItem verdict recorded', { workItemId, verdict, actorRole });
+        // F1-BRIDGE-1: only the `rejected` branch publishes. The bridge's
+        // task:rejected handler creates the retry-or-escalate WI; the `verified`
+        // branch is terminal-success and unblocks dependents above without any
+        // bridge involvement. Skip the publish on race-window deletion.
+        if (verdict === 'rejected' && updated) {
+            this.publishTaskRejected(updated);
+        }
+        return updated;
+    }
+    /**
+     * Legacy facade — picks the verification path for the caller.
+     *
+     * Existing call sites (REST controller, task-management controllers,
+     * V3 data service) invoke `completeItem(id, result)` without an
+     * explicit actor role. The facade reads the WorkItem, applies the
+     * {@link requiresVerification} policy, and dispatches to either
+     * {@link submitForVerification} (delegate items / explicit opt-in)
+     * or {@link completeSimpleItem} (everything else).
+     *
+     * The legacy actor role for these implicit callers is `'agent'`.
+     * Migrations to explicit-actor calls can land in follow-up tickets
+     * without touching the five call sites in this PR.
+     *
+     * @param workItemId - WorkItem id
+     * @param result - Optional result payload
+     * @throws When the WorkItem is missing or the underlying transition
+     *   is rejected (invalid state, forbidden actor).
      */
     async completeItem(workItemId, result) {
         const workItem = await this.storage.findWorkItem(workItemId);
         if (!workItem) {
             throw new Error(`WorkItem not found: ${workItemId}`);
         }
-        if (workItem.status !== 'running') {
-            throw new Error(`Cannot complete WorkItem: status must be 'running', got '${workItem.status}'`);
+        if (this.requiresVerification(workItem)) {
+            await this.submitForVerification(workItemId, 'agent', result);
         }
-        // Release the claim
-        const claim = await this.storage.findActiveClaimByWorkItem(workItemId);
-        if (claim) {
-            await this.storage.updateClaim(claim.id, (c) => {
-                c.status = 'released';
-                c.endedAt = new Date().toISOString();
-                c.endReason = 'completed';
-            });
+        else {
+            await this.completeSimpleItem(workItemId, 'agent', result);
         }
-        // Mark item done
-        await this.storage.updateWorkItem(workItemId, (wi) => {
-            wi.status = 'done';
-            wi.completedAt = new Date().toISOString();
-            if (result)
-                wi.result = result;
+    }
+    /**
+     * Scans blocked WorkItems that list `completedId` in their `dependsOn` and
+     * promotes each to `queued` if every one of their deps has reached terminal
+     * success (`done` or `verified`). Idempotent and safe to call on any terminal
+     * success transition.
+     *
+     * Serialized via the claim mutex — a concurrent claimFromPool call must not
+     * observe a half-promoted item.
+     */
+    async resolveBlockedDependents(completedId) {
+        await this.withClaimLock(async () => {
+            const items = await this.storage.getWorkItems();
+            const terminalSuccess = new Set(items
+                .filter((wi) => wi.status === 'done' || wi.status === 'verified')
+                .map((wi) => wi.id));
+            const candidates = items.filter((wi) => wi.status === 'blocked' &&
+                Array.isArray(wi.dependsOn) &&
+                wi.dependsOn.includes(completedId));
+            for (const candidate of candidates) {
+                const allSatisfied = (candidate.dependsOn ?? []).every((depId) => terminalSuccess.has(depId));
+                if (!allSatisfied)
+                    continue;
+                // TRANS-2: route the blocked → queued promotion through
+                // transitionStatus. The 'system' actor matches both the V3
+                // permission gate (blocked→queued requires TL/orc/system) and
+                // the existing intent — dependency resolution is server-side
+                // bookkeeping, not a user-initiated action.
+                await this.transitionStatus(candidate.id, 'queued', 'system');
+                this.logger.info('WorkItem unblocked — all deps satisfied', {
+                    workItemId: candidate.id,
+                    via: completedId,
+                });
+            }
         });
-        await this.storage.flush();
-        this.logger.info('WorkItem completed', { workItemId });
     }
     /**
      * Marks a work item as failed.
@@ -311,10 +935,10 @@ export class TaskPoolService {
                 c.endReason = `failed: ${error}`;
             });
         }
-        // Mark item failed
-        await this.storage.updateWorkItem(workItemId, (wi) => {
-            wi.status = 'failed';
-            wi.completedAt = new Date().toISOString();
+        // TRANS-2: route the running → failed flip through transitionStatus.
+        // `completedAt` is set automatically when newStatus === 'failed'; the
+        // mutator only needs to attach the error description.
+        await this.transitionStatus(workItemId, 'failed', 'system', (wi) => {
             wi.error = error;
         });
         await this.storage.flush();
@@ -459,6 +1083,104 @@ export class TaskPoolService {
     async getAllItems() {
         return this.storage.getWorkItems();
     }
+    /**
+     * Find a WorkItem by id without mutating it.
+     *
+     * Public read accessor used by callers that need to inspect a
+     * specific item — for example REVIEW-1's reentrancy lock checks the
+     * status of a Mission's `pendingReviewWorkItemId` to decide whether
+     * to clear the lock. Returns `null` (not `undefined`) so callers can
+     * use a uniform null-fallthrough idiom shared with
+     * `getWorkItemSnapshot` and `transitionStatus`.
+     *
+     * @param workItemId - WorkItem id to look up
+     * @returns The WorkItem, or `null` if no item has that id
+     */
+    async findWorkItem(workItemId) {
+        return (await this.storage.findWorkItem(workItemId)) ?? null;
+    }
+    /**
+     * Stores worker-supplied structured output on a WorkItem.
+     *
+     * Replaces the v1 `<taskId>.output.json` filesystem store with an
+     * in-pool field (see {@link WorkItem.output}). Used by the worker
+     * `complete-task` flow and read back by the TL `verify-output` skill.
+     *
+     * @param workItemId - WorkItem id to attach output to
+     * @param output - Arbitrary task-specific output object
+     * @returns The updated WorkItem, or null if not found
+     */
+    async setOutput(workItemId, output) {
+        const ok = await this.storage.updateWorkItem(workItemId, (wi) => {
+            wi.output = output;
+        });
+        if (!ok)
+            return null;
+        return (await this.storage.findWorkItem(workItemId)) ?? null;
+    }
+    /**
+     * Reassigns a WorkItem to a different target agent.
+     *
+     * Replaces the v1 `/task-management/handoff` filesystem reassign with a
+     * direct `target` field update on the WorkItem.
+     *
+     * Allowed transitions:
+     *   - `target` must be a non-empty string
+     *   - WI must not be in a terminal state (done/cancelled/failed-final)
+     *
+     * @param workItemId - WorkItem to reassign
+     * @param newTarget  - Session name of the new target agent
+     * @param fromAgent  - Session name of the agent handing off (for audit)
+     * @param reason     - Human-readable reason recorded as a working-note
+     * @returns The updated WorkItem, or null if not found
+     */
+    async handoff(workItemId, newTarget, fromAgent, reason) {
+        if (!newTarget || newTarget.trim() === '') {
+            throw new Error('handoff: newTarget is required');
+        }
+        const wi = await this.storage.findWorkItem(workItemId);
+        if (!wi)
+            return null;
+        if (wi.status === 'done' || wi.status === 'cancelled') {
+            throw new Error(`handoff refused: WorkItem ${workItemId} is in terminal state '${wi.status}'`);
+        }
+        const handoffNote = `[HANDOFF] ${fromAgent} → ${newTarget}: ${reason || '(no reason)'}`;
+        await this.storage.updateWorkItem(workItemId, (item) => {
+            item.target = newTarget;
+            const existing = (item.metadata && typeof item.metadata === 'object' ? item.metadata : {});
+            const notes = Array.isArray(existing.notes) ? existing.notes : [];
+            notes.push(`${new Date().toISOString()} ${handoffNote}`);
+            item.metadata = { ...existing, notes };
+        });
+        this.logger.info('WorkItem handoff', { workItemId, fromAgent, newTarget });
+        return (await this.storage.findWorkItem(workItemId)) ?? null;
+    }
+    /**
+     * Appends a working-state note to a WorkItem's metadata.notes array.
+     *
+     * Replaces v1 `/task-management/sync` and `/task-management/save-working-notes`,
+     * both of which appended progress notes to the `.md` task body. With v1
+     * retired, notes live on the WorkItem itself under `metadata.notes[]`.
+     *
+     * @param workItemId - WorkItem id
+     * @param author - Session name of note author
+     * @param note - Note content (free-form)
+     * @returns The updated WorkItem, or null if not found
+     */
+    async appendNote(workItemId, author, note) {
+        if (!note || note.trim() === '') {
+            throw new Error('appendNote: note is required');
+        }
+        const ok = await this.storage.updateWorkItem(workItemId, (wi) => {
+            const existing = (wi.metadata && typeof wi.metadata === 'object' ? wi.metadata : {});
+            const notes = Array.isArray(existing.notes) ? existing.notes : [];
+            notes.push(`${new Date().toISOString()} [${author}] ${note}`);
+            wi.metadata = { ...existing, notes };
+        });
+        if (!ok)
+            return null;
+        return (await this.storage.findWorkItem(workItemId)) ?? null;
+    }
     /**
      * Removes a WorkItem from the pool entirely.
      * Used for purging old completed/cancelled items.
@@ -468,6 +1190,63 @@ export class TaskPoolService {
     async removeItem(workItemId) {
         await this.storage.removeWorkItem(workItemId);
     }
+    // -------------------------------------------------------------------------
+    // P1 1ffffb84(a) — Bulk-DELETE stale WorkItems
+    // -------------------------------------------------------------------------
+    /**
+     * Public delete API used by the bulk-cleanup script and the new
+     * `DELETE /api/task-pool/:id` HTTP endpoint (P1 umbrella WI 1ffffb84
+     * component a, Steve directive 2026-05-06: just-DELETE-not-backfill).
+     *
+     * Three guarantees over {@link removeItem}:
+     *   1. Idempotent — `not_found` is a no-op return, not a throw.
+     *   2. Claim-safety — refuses claimed delete unless `opts.force`.
+     *   3. Audit log — single info-level log per removal.
+     *
+     * Force path also revokes the orphaned claim (status='revoked',
+     * endedAt, endReason).
+     */
+    async removeFromPool(workItemId, opts = {}) {
+        const wi = await this.storage.findWorkItem(workItemId);
+        if (!wi) {
+            this.logger.debug('removeFromPool: item not found (idempotent)', { workItemId });
+            return { removed: false, reason: 'not_found' };
+        }
+        const activeClaim = await this.storage.findActiveClaimByWorkItem(workItemId);
+        const hadActiveClaim = !!activeClaim;
+        if (hadActiveClaim && activeClaim && !opts.force) {
+            this.logger.warn('removeFromPool refused: active claim exists', {
+                workItemId,
+                claimId: activeClaim.id,
+                claimedBy: activeClaim.agentId,
+            });
+            throw new WorkItemClaimedError({
+                workItemId,
+                claimId: activeClaim.id,
+                claimedBy: activeClaim.agentId,
+            });
+        }
+        const removed = await this.storage.removeWorkItem(workItemId);
+        if (hadActiveClaim && activeClaim) {
+            await this.storage.updateClaim(activeClaim.id, (c) => {
+                c.status = 'revoked';
+                c.endedAt = new Date().toISOString();
+                c.endReason = `WorkItem deleted via removeFromPool (force=${opts.force === true})`;
+            });
+        }
+        this.logger.info('removeFromPool: WorkItem removed', {
+            workItemId,
+            status: wi.status,
+            target: wi.target,
+            force: opts.force === true,
+            hadActiveClaim,
+        });
+        return {
+            removed: removed === true,
+            workItem: wi,
+            hadActiveClaim,
+        };
+    }
     /**
      * Forces an immediate flush of pool data to disk.
      * Called during graceful shutdown to prevent data loss.
@@ -488,41 +1267,186 @@ export class TaskPoolService {
      * Updates a work item's status directly.
      * Used by the Reconciler for corrections (e.g., stuck → blocked).
      *
+     * Reconciler invocations pass through `actorRole='system'` (default) which
+     * bypasses the per-role gate at {@link isTransitionPermitted} but still
+     * enforces the state-machine via {@link isValidWorkItemTransition}. Other
+     * callers MUST supply the actor's role so TRANS-1 V3 enforcement applies.
+     *
      * @param workItemId - The work item ID
      * @param newStatus - The target status
-     * @throws Error if work item not found or transition is invalid
+     * @param actorRole - Role of the caller (defaults to `'system'` for Reconciler)
+     * @throws Error if work item not found
+     * @throws Error if transition is invalid (state machine — see WORK_ITEM_TRANSITIONS)
+     * @throws Error if actor is not permitted (role check — see TRANSITION_PERMISSIONS)
      */
-    async updateItemStatus(workItemId, newStatus) {
+    async updateItemStatus(workItemId, newStatus, actorRole = 'system') {
         const items = await this.storage.getWorkItems();
         const item = items.find((wi) => wi.id === workItemId);
         if (!item) {
             throw new Error(`WorkItem not found: ${workItemId}`);
         }
-        if (item.status === newStatus) {
-            this.logger.debug('Work item status update is a no-op, skipping', {
-                workItemId,
-                status: newStatus,
-            });
-            return;
-        }
         if (!isValidWorkItemTransition(item.status, newStatus)) {
             throw new Error(`Invalid status transition for WorkItem ${workItemId}: ${item.status} → ${newStatus}`);
         }
+        // TRANS-1 V3: enforce per-role permissions. system role always passes.
+        if (!isTransitionPermitted(item.status, newStatus, actorRole)) {
+            throw new Error(`Forbidden transition for WorkItem ${workItemId}: actor='${actorRole}' ` +
+                `not permitted to perform ${item.status} → ${newStatus}.`);
+        }
         await this.storage.updateWorkItem(workItemId, (wi) => {
             wi.status = newStatus;
-            // Use startedAt for running, completedAt for done/failed
+            // P1 1ffffb84 component (b): mirror the transitionStatus
+            // atomic-timestamp contract so the older updateItemStatus path
+            // never produces a status↔completedAt mismatch either. See
+            // transitionStatus below for the full root-cause writeup
+            // (b7840fe8 partial-write bug).
             if (newStatus === 'running') {
                 wi.startedAt = new Date().toISOString();
+                wi.completedAt = undefined;
             }
             else if (newStatus === 'done' || newStatus === 'failed') {
                 wi.completedAt = new Date().toISOString();
             }
+            else {
+                wi.completedAt = undefined;
+            }
         });
         this.logger.info('Work item status updated', {
             workItemId,
             from: item.status,
             to: newStatus,
+            actorRole,
         });
+        // Cascade signal — let RequestCascadeSubscriber close the parent
+        // Request without waiting for the heartbeat catch. See
+        // {@link publishTaskCancelled} for the full bug writeup.
+        if (newStatus === 'cancelled') {
+            const post = await this.storage.findWorkItem(workItemId);
+            if (post)
+                this.publishTaskCancelled(post, item.status);
+        }
+    }
+    /**
+     * Public guarded transition helper — TRANS-1's canonical entrypoint.
+     *
+     * Routes any externally-initiated WorkItem status change through the
+     * combined state-machine + actor-role gates. Designed as the public API
+     * VERIF-1 will call from `submitForVerification` / `verifyItem`, and as
+     * the recommended path for any future caller that previously reached
+     * for `storage.updateWorkItem` to flip status.
+     *
+     * Differences vs {@link updateItemStatus}:
+     *   - Requires `actorRole` explicitly (no default) — forces the caller to
+     *     decide the trust posture rather than silently inheriting `'system'`.
+     *   - Accepts an optional `mutator` so callers can carry additional field
+     *     updates (e.g. `result`, `error`, `completedAt`) atomically with the
+     *     status flip — preventing races between status update and metadata
+     *     attachment that direct `storage.updateWorkItem` callers risked.
+     *
+     * @param workItemId - The work item ID
+     * @param newStatus - The target status
+     * @param actorRole - Role of the caller (REQUIRED; pass `'system'` for trusted server-internal paths)
+     * @param mutator - Optional additional WorkItem field updates applied atomically with the status change
+     * @returns The updated WorkItem after the transition
+     * @throws Error if work item not found
+     * @throws Error if transition is invalid (state machine)
+     * @throws Error if actor is not permitted (role check)
+     *
+     * @example
+     * ```typescript
+     * // VERIF-1 worker submitting for verification
+     * await pool.transitionStatus(wiId, 'done_by_worker', 'agent', (wi) => {
+     *   wi.result = output;
+     * });
+     *
+     * // VERIF-1 TL verifying
+     * await pool.transitionStatus(wiId, 'verified', 'team_lead');
+     *
+     * // VERIF-1 TL rejecting (allowed for TL only)
+     * await pool.transitionStatus(wiId, 'rejected', 'team_lead', (wi) => {
+     *   wi.error = 'Did not meet acceptance criteria';
+     * });
+     * ```
+     */
+    async transitionStatus(workItemId, newStatus, actorRole, mutator) {
+        const item = await this.storage.findWorkItem(workItemId);
+        if (!item) {
+            throw new Error(`WorkItem not found: ${workItemId}`);
+        }
+        if (!isValidWorkItemTransition(item.status, newStatus)) {
+            throw new Error(`Invalid status transition for WorkItem ${workItemId}: ${item.status} → ${newStatus}`);
+        }
+        if (!isTransitionPermitted(item.status, newStatus, actorRole)) {
+            throw new Error(`Forbidden transition for WorkItem ${workItemId}: actor='${actorRole}' ` +
+                `not permitted to perform ${item.status} → ${newStatus}.`);
+        }
+        const ok = await this.storage.updateWorkItem(workItemId, (wi) => {
+            wi.status = newStatus;
+            // Atomic timestamp side-effects enforce the invariant
+            // `completedAt is set IFF status ∈ {done, failed, verified,
+            // done_by_worker, rejected}`.
+            //
+            // P1 1ffffb84 component (b): the prior code only SET completedAt
+            // on terminal transitions; non-terminal landings (queued, running,
+            // blocked, scheduled, proposed, accepted, escalated, cancelled)
+            // inherited a stale completedAt from a prior terminal trip via
+            //   - `rejected → queued` (TL re-queue)
+            //   - `failed → queued`  (BRIDGE-1 retry)
+            //   - `running → queued` (releaseBack abandon path)
+            // WorkItem b7840fe8 reproduced the bug — status=queued AND
+            // completedAt=2026-05-06T00:47:59Z AND retryCount=1 AND no
+            // startedAt/target, which is the exact fingerprint of a
+            // `failed → queued` retry leaving stale completedAt. The else
+            // branch below closes the gap atomically with the status flip.
+            if (newStatus === 'running') {
+                wi.startedAt = new Date().toISOString();
+                // Resuming work — clear stale completedAt from a prior failed/
+                // rejected attempt so a re-claim never carries forward a
+                // completion timestamp from an earlier terminal trip.
+                wi.completedAt = undefined;
+            }
+            else if (newStatus === 'done' ||
+                newStatus === 'failed' ||
+                newStatus === 'verified' ||
+                newStatus === 'done_by_worker' ||
+                newStatus === 'rejected') {
+                wi.completedAt = new Date().toISOString();
+            }
+            else {
+                // Non-terminal-with-result landings: clear completedAt so the
+                // invariant holds. (`cancelled` is technically terminal but
+                // historically never carried completedAt — preserving that
+                // shape here to keep the change minimal; the `cancelled`
+                // semantics are out of scope.)
+                wi.completedAt = undefined;
+            }
+            if (mutator)
+                mutator(wi);
+        });
+        if (!ok) {
+            // Race window: someone else removed the WorkItem between findWorkItem
+            // and updateWorkItem. Surface as null so callers can distinguish from
+            // a thrown invalid-transition / forbidden-transition error.
+            return null;
+        }
+        this.logger.info('WorkItem transitioned', {
+            workItemId,
+            from: item.status,
+            to: newStatus,
+            actorRole,
+        });
+        // Return the post-update WorkItem snapshot so callers can chain on the
+        // resolved value rather than re-fetching. Coerce `undefined` (item
+        // removed during the race window) to `null` to match the declared
+        // return type.
+        const post = (await this.storage.findWorkItem(workItemId)) ?? null;
+        // Cascade signal — let RequestCascadeSubscriber close the parent
+        // Request without waiting for the heartbeat catch. See
+        // {@link publishTaskCancelled} for the full bug writeup.
+        if (newStatus === 'cancelled' && post) {
+            this.publishTaskCancelled(post, item.status);
+        }
+        return post;
     }
     /**
      * Update token usage and cost on a WorkItem.