crewly 1.6.4 → 1.7.0

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

@@ -14,6 +14,25 @@ import { LoggerService } from '../core/logger.service.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
 // ---------------------------------------------------------------------------
@@ -52,6 +71,26 @@ export class TaskPoolService {
      * 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
@@ -76,6 +115,22 @@ export class TaskPoolService {
     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.
@@ -139,6 +194,25 @@ 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
@@ -146,6 +220,40 @@ export class TaskPoolService {
         // 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
@@ -311,6 +419,63 @@ export class TaskPoolService {
             });
         }
     }
+    /**
+     * 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.
      *
@@ -329,12 +494,31 @@ export class TaskPoolService {
             // 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', {
+                // Issue #513 — Steve 2026-05-15. Previously this returned
+                // null, which the controller mapped to 404 "No available
+                // WorkItem matching filters". That was misleading: the caller
+                // DOES have a WorkItem (the one they already claimed), they
+                // just couldn't see it without grepping pool.json. Return the
+                // held claim + its WorkItem with `alreadyHeld: true` so the
+                // skill / agent can recognize the situation.
+                this.logger.info('Agent already has an active claim — returning existing', {
                     agentId,
                     existingClaimId: existingClaim.id,
                     existingWorkItemId: existingClaim.workItemId,
                 });
-                return null;
+                const heldWorkItem = await this.storage.findWorkItem(existingClaim.workItemId);
+                if (!heldWorkItem) {
+                    // Held claim exists but WI is missing — orphan state. Best we
+                    // can do is fall through to the empty-pool null so the agent
+                    // doesn't think they own a phantom item. Log so we notice.
+                    this.logger.warn('Orphan claim — claim exists but WorkItem missing', {
+                        agentId,
+                        existingClaimId: existingClaim.id,
+                        existingWorkItemId: existingClaim.workItemId,
+                    });
+                    return null;
+                }
+                return { workItem: heldWorkItem, claim: existingClaim, alreadyHeld: true };
             }
             const workItems = await this.storage.getWorkItems();
             const claims = await this.storage.getClaims();
@@ -342,9 +526,24 @@ export class TaskPoolService {
             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
+            // 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) {
@@ -356,8 +555,17 @@ export class TaskPoolService {
             // 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) => {
-                wi.target = agentId;
+                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 });
@@ -403,13 +611,32 @@ export class TaskPoolService {
             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) => {
-                wi.target = agentId;
+                if (!wi.target) {
+                    wi.target = agentId;
+                }
             });
             if (!claimedItem)
                 return null;
@@ -587,6 +814,47 @@ export class TaskPoolService {
             if (result)
                 wi.result = result;
         });
+        // Steve 2026-05-15 dogfood: TL Verify WIs were completing (status=done)
+        // but the SOURCE work item they were verifying stayed stuck in
+        // `done_by_worker` forever. `resolveBlockedDependents` only treats
+        // `done|verified` as terminal-success, so blocked dependents of the
+        // SOURCE (e.g. an Execute waiting on a Plan in a Plan/Execute/Review
+        // chain) were never unblocked.
+        //
+        // Concrete repro: WI 12d7e988 (Plan) — done_by_worker; verify WI
+        // 12d7e988:verify:12d7e988 — done; Execute 722da42f — blocked for 41+
+        // min waiting on the Plan that was already verified.
+        //
+        // When a verify WI completes (metadata.verifyOf points at its source),
+        // propagate the verdict to the source via verifyItem so the source
+        // moves done_by_worker → verified AND its own dependents unblock. Use
+        // the 'system' actor — this is automatic propagation, not a fresh
+        // TL action (the TL action was completing this verify WI).
+        const verifyOf = updated?.metadata && typeof updated.metadata.verifyOf === 'string'
+            ? updated.metadata.verifyOf
+            : undefined;
+        if (verifyOf) {
+            try {
+                const source = await this.storage.findWorkItem(verifyOf);
+                if (source && source.status === 'done_by_worker') {
+                    await this.verifyItem(verifyOf, 'system', 'verified');
+                    this.logger.info('Verify WI complete → propagated to source', {
+                        verifyWorkItemId: workItemId,
+                        sourceWorkItemId: verifyOf,
+                        verdict: 'verified',
+                    });
+                }
+            }
+            catch (err) {
+                // Propagation is best-effort — a failed propagate must NOT roll
+                // back the verify WI's own completion.
+                this.logger.warn('Verify-to-source propagation failed (non-fatal)', {
+                    verifyWorkItemId: workItemId,
+                    sourceWorkItemId: verifyOf,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
         // Promote any blocked dependents whose deps are now all satisfied.
         await this.resolveBlockedDependents(workItemId);
         await this.storage.flush();
@@ -891,6 +1159,88 @@ export class TaskPoolService {
     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.
@@ -900,6 +1250,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.
@@ -932,12 +1339,36 @@ export class TaskPoolService {
      * @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, actorRole = 'system') {
+    async updateItemStatus(workItemId, newStatus, actorRole = 'system', 
+    /**
+     * Optional human-readable reason. Persisted on:
+     *   - `WorkItem.cancelReason` when `newStatus === 'cancelled'`
+     *   - `WorkItem.blockedReason` when `newStatus === 'blocked'` (Steve
+     *     2026-05-15 dogfood — UI showed Blocked badge with no
+     *     explanation)
+     *   - Ignored for other status transitions.
+     */
+    reason) {
         const items = await this.storage.getWorkItems();
         const item = items.find((wi) => wi.id === workItemId);
         if (!item) {
             throw new Error(`WorkItem not found: ${workItemId}`);
         }
+        // Idempotent same-state no-op: the reconciler's stale-pickup rule
+        // and the SLA close path can both race to apply the same terminal
+        // status. Silently no-op here instead of throwing or logging a
+        // misleading "transitioned cancelled → cancelled" entry. (Steve
+        // 2026-05-15 dogfood — see the duplicate "Work item status
+        // updated from cancelled to cancelled" rows in
+        // crewly-2026-05-15.log around 15:48:56 / 16:05:55.)
+        if (item.status === newStatus) {
+            this.logger.debug('Skipped idempotent same-state status update', {
+                workItemId,
+                status: newStatus,
+                actorRole,
+            });
+            return;
+        }
         if (!isValidWorkItemTransition(item.status, newStatus)) {
             throw new Error(`Invalid status transition for WorkItem ${workItemId}: ${item.status} → ${newStatus}`);
         }
@@ -946,22 +1377,63 @@ export class TaskPoolService {
             throw new Error(`Forbidden transition for WorkItem ${workItemId}: actor='${actorRole}' ` +
                 `not permitted to perform ${item.status} → ${newStatus}.`);
         }
+        // Capture pre-write status. See transitionStatus's identical block
+        // for the writeup — storage.updateWorkItem mutates in place, so
+        // reading item.status after the write yields newStatus and the
+        // "Work item status updated" log reads like "X → X" for every
+        // valid transition.
+        const fromStatus = item.status;
         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;
+            }
+            // Persist the cancellation reason atomically with the status
+            // flip so the activity timeline always has the explanation
+            // alongside the terminal state. Only set on transitions INTO
+            // cancelled — leaving the field untouched on non-cancel paths
+            // preserves any earlier value (e.g. requeued after a manual
+            // cancel-then-revive flow).
+            if (newStatus === 'cancelled' && typeof reason === 'string' && reason.length > 0) {
+                wi.cancelReason = reason;
+            }
+            // Mirror for blocked transitions (Steve 2026-05-15 dogfood): the
+            // UI showed `Blocked` badge with an empty activity timeline.
+            // Sources include reconciler agent-inactive correction, mission
+            // executor dependency-blocked creation (not via this path),
+            // explicit blockItem.
+            if (newStatus === 'blocked' && typeof reason === 'string' && reason.length > 0) {
+                wi.blockedReason = reason;
+            }
         });
         this.logger.info('Work item status updated', {
             workItemId,
-            from: item.status,
+            from: fromStatus,
             to: newStatus,
             actorRole,
+            ...(newStatus === 'cancelled' && reason ? { reason } : {}),
+            ...(newStatus === 'blocked' && reason ? { reason } : {}),
         });
+        // 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, fromStatus);
+        }
     }
     /**
      * Public guarded transition helper — TRANS-1's canonical entrypoint.
@@ -1005,11 +1477,35 @@ export class TaskPoolService {
      * });
      * ```
      */
-    async transitionStatus(workItemId, newStatus, actorRole, mutator) {
+    async transitionStatus(workItemId, newStatus, actorRole, mutator, 
+    /**
+     * Optional human-readable reason. Routed by target status:
+     *   - `cancelled` → persisted on `WorkItem.cancelReason`
+     *   - `blocked`   → persisted on `WorkItem.blockedReason`
+     *     (Steve 2026-05-15 dogfood)
+     *   - other       → ignored
+     * Applied BEFORE the caller's mutator runs so the mutator may
+     * override if needed. Surfaces in the activity timeline so the
+     * Blocked/Cancelled badges aren't opaque ("WorkItem was X.").
+     * Parameter name retained as `cancelReason` for source compat;
+     * effectively a generic transition reason.
+     */
+    cancelReason) {
         const item = await this.storage.findWorkItem(workItemId);
         if (!item) {
             throw new Error(`WorkItem not found: ${workItemId}`);
         }
+        // Idempotent same-state no-op (matches updateItemStatus behavior).
+        // Return the current item so callers chaining on the result don't
+        // see a spurious null. Steve 2026-05-15.
+        if (item.status === newStatus) {
+            this.logger.debug('Skipped idempotent same-state transition', {
+                workItemId,
+                status: newStatus,
+                actorRole,
+            });
+            return item;
+        }
         if (!isValidWorkItemTransition(item.status, newStatus)) {
             throw new Error(`Invalid status transition for WorkItem ${workItemId}: ${item.status} → ${newStatus}`);
         }
@@ -1017,12 +1513,38 @@ export class TaskPoolService {
             throw new Error(`Forbidden transition for WorkItem ${workItemId}: actor='${actorRole}' ` +
                 `not permitted to perform ${item.status} → ${newStatus}.`);
         }
+        // Capture the pre-write status into a local. `storage.updateWorkItem`
+        // mutates the same in-memory object that `findWorkItem` returned, so
+        // reading `item.status` AFTER the write yields the new value — which
+        // makes the "transitioned X → Y" log read like "Y → Y" and hides the
+        // real `previousValue` on the task:cancelled EventBus payload.
+        // (Steve 2026-05-15 dogfood: `from:cancelled, to:cancelled` showing
+        // for transitions that were actually `queued → cancelled`.)
+        const fromStatus = item.status;
         const ok = await this.storage.updateWorkItem(workItemId, (wi) => {
             wi.status = newStatus;
-            // Standard timestamp side-effects mirror updateItemStatus so callers
-            // get consistent metadata regardless of which API they used.
+            // 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' ||
@@ -1031,6 +1553,25 @@ export class TaskPoolService {
                 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;
+            }
+            // Apply cancelReason BEFORE the user-supplied mutator so the
+            // mutator wins if the caller wants to override (rare). The
+            // parameter is named `cancelReason` for source-compat but is
+            // routed to cancelReason OR blockedReason based on newStatus
+            // (Steve 2026-05-15).
+            if (newStatus === 'cancelled' && typeof cancelReason === 'string' && cancelReason.length > 0) {
+                wi.cancelReason = cancelReason;
+            }
+            if (newStatus === 'blocked' && typeof cancelReason === 'string' && cancelReason.length > 0) {
+                wi.blockedReason = cancelReason;
+            }
             if (mutator)
                 mutator(wi);
         });
@@ -1042,7 +1583,7 @@ export class TaskPoolService {
         }
         this.logger.info('WorkItem transitioned', {
             workItemId,
-            from: item.status,
+            from: fromStatus,
             to: newStatus,
             actorRole,
         });
@@ -1050,7 +1591,14 @@ export class TaskPoolService {
         // resolved value rather than re-fetching. Coerce `undefined` (item
         // removed during the race window) to `null` to match the declared
         // return type.
-        return (await this.storage.findWorkItem(workItemId)) ?? null;
+        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, fromStatus);
+        }
+        return post;
     }
     /**
      * Update token usage and cost on a WorkItem.