crewly 1.12.1 → 1.13.1

package/dist/backend/backend/src/services/task-pool/task-pool.service.d.ts

@@ -11,6 +11,7 @@
 import { PoolStorage } from './pool-storage.js';
 import { ClaimService, type HeartbeatResult, type ExtendLeaseResult, type ExpiredClaimsSummary } from './claim.service.js';
 import type { WorkItem, WorkItemStatus, WorkItemType, WorkItemOwner } from '../../types/v2/work-item.types.js';
+import type { WorkItemDisposition } from '../../types/v2/work-item.types.js';
 import { type TaskClaim } from '../../types/v2/claim.types.js';
 import type { EventBusService } from '../event-bus/event-bus.service.js';
 /**
@@ -134,6 +135,21 @@ export interface ClaimResult {
  * }
  * ```
  */
+/**
+ * Options for {@link TaskPoolService.releaseBack}.
+ */
+export interface ReleaseBackOptions {
+    /**
+     * When true, clear the item's `target` as well, returning it to the
+     * unassigned pool.
+     *
+     * Defaults to false: a release ends an attempt, it does not revoke an
+     * assignment. This must be requested BY NAME so that un-assignment is
+     * always a deliberate act by a caller who means it, never a silent
+     * side effect of a lease expiring.
+     */
+    unassign?: boolean;
+}
 export declare class TaskPoolService {
     private static instance;
     private readonly storage;
@@ -379,11 +395,55 @@ export declare class TaskPoolService {
      *
      * The item's status reverts to 'queued' and the claim is marked 'released'.
      *
+     * A release is an ADMINISTRATIVE event, not a failure. Two invariants
+     * follow, and both were violated before 2026-08-21:
+     *
+     * 1. **`target` is preserved.** A release says "this attempt ended", not
+     *    "this work no longer belongs to that agent". Clearing it silently
+     *    destroyed a deliberate assignment — and because the wake gate admits
+     *    a worker only when a queued/blocked WI carries `target === their
+     *    session`, it also made the assigned worker unwakeable for their own
+     *    work (`wake_gate_no_pool_work`). The sibling failure path,
+     *    {@link requeueAfterFailure}, already keeps `target` on the far
+     *    stronger grounds of an actual failure; there is no coherent reading
+     *    in which a lease lapse un-assigns work that a failure would not.
+     *    Genuine un-assignment is still possible, but it must be asked for by
+     *    name via `options.unassign` — never inferred from a lease expiring.
+     *
+     *    One carve-out, and it is not an exception to the rule so much as a
+     *    sharpening of it: `claimFromPool` stamps `target` on a *broadcast*
+     *    item to record who picked it up. That stamp is not an assignment,
+     *    and it is dropped on release (`targetSource === 'claim'`) so the
+     *    item returns to the broadcast pool. Preserving it would let one
+     *    claim permanently bind unassigned work to a single agent — and if
+     *    that agent died, only a dead session could ever re-claim it.
+     *
+     * 2. **`retryCount` is untouched.** That counter means failures only (see
+     *    {@link WorkItem.retryCount}); consumers branch on
+     *    `retryCount < maxRetries` to decide retry-in-place vs terminal-and-
+     *    escalate. Charging a retry for lease churn drove live work to 3/3
+     *    with zero failures. Release churn is counted separately in
+     *    {@link WorkItem.releaseCount}, which nothing branches on.
+     *
      * @param workItemId - ID of the work item to release
      * @param reason - Why the item is being released
-     * @throws Error if work item not found or not currently claimed
+     * @param options - Release options
+     * @param options.unassign - When true, ALSO clear `target`, returning the
+     *   item to the unassigned pool. Opt-in only, for the case where a caller
+     *   genuinely means "someone else should take this". Defaults to false.
+     * @throws Error if work item not found, or its status is not
+     *   'running' or 'blocked'
+     *
+     * @example
+     * ```typescript
+     * // Lease lapsed / claim revoked — the owner keeps the work.
+     * await pool.releaseBack(id, 'claim revoked: grace exceeded');
+     *
+     * // Deliberate hand-back — anyone may pick this up.
+     * await pool.releaseBack(id, 'agent declined', { unassign: true });
+     * ```
      */
-    releaseBack(workItemId: string, reason: string): Promise<void>;
+    releaseBack(workItemId: string, reason: string, options?: ReleaseBackOptions): Promise<void>;
     /**
      * Decide whether a WorkItem requires TL verification before reaching a
      * terminal-success status.
@@ -406,15 +466,32 @@ export declare class TaskPoolService {
      */
     private requiresVerification;
     /**
-     * Internal: release the active claim on a WorkItem (if any). Shared by
-     * `completeSimpleItem` and `submitForVerification` because both
+     * Release the active claim on a WorkItem, if it has one.
+     *
+     * Shared by `completeSimpleItem` and `submitForVerification` because both
      * represent the worker handing the item back to the system.
      *
+     * Also public for callers that must drive a terminal transition
+     * themselves rather than through {@link failItem}. The SLA orphan-close
+     * path is the live example: it targets `cancelled`, `failed` OR
+     * `rejected` depending on the origin status, so `failItem` — which always
+     * transitions to `failed` — cannot serve it. Such callers MUST call this,
+     * otherwise the claim stays `active` against a terminal WorkItem and
+     * quietly wedges the claiming agent. The mechanism is not an error, which
+     * is what makes it hard to spot: {@link claimFromPool} checks
+     * `findActiveClaimByAgent` BEFORE it scans the pool, and short-circuits by
+     * returning the held claim with `alreadyHeld: true` (issue #513). So the
+     * agent is handed the same terminal item on every poll and never sees the
+     * queued work waiting for them, until the lease/grace ladder revokes it.
+     *
+     * Idempotent: a no-op when no active claim exists.
+     *
      * @param workItemId - WorkItem whose claim should be released
-     * @param endReason - Reason recorded on the claim (`completed` /
-     *   `submitted_for_verification`) for auditability
+     * @param endReason - Reason recorded on the claim (`completed`,
+     *   `submitted_for_verification`, `sla escalation timeout ...`) for
+     *   auditability
      */
-    private releaseClaim;
+    releaseClaim(workItemId: string, endReason: string): Promise<void>;
     /**
      * Worker reports a delegated WorkItem as done and submits it for TL
      * verification.
@@ -559,6 +636,74 @@ export declare class TaskPoolService {
      * @throws if the WI doesn't exist or isn't in `failed` status
      */
     requeueAfterFailure(workItemId: string, reason: string): Promise<void>;
+    /**
+     * Decide and record how a stranded WorkItem is dealt with — the single
+     * funnel every `rejected`/`failed` writer must route through.
+     *
+     * `rejected` and `failed` are the only two statuses that are neither
+     * terminal nor able to reach a terminal state: their sole outbound edge is
+     * `→ queued`. An item parked in either is finished as far as every consumer
+     * is concerned (see `SLA_TERMINAL_WORK_ITEM_STATUSES`) and unfinished as far
+     * as the state machine is concerned, and until this funnel existed nothing
+     * owned closing that gap. Items written there by a path that did not itself
+     * arrange a successor simply stopped, permanently and — since PR #733
+     * correctly stopped the pruning rules emitting illegal corrections for them
+     * — silently.
+     *
+     * Exactly one of three things happens, and the choice is recorded rather
+     * than left to be re-derived later by scanning other WorkItems:
+     *
+     * 1. **retried in place** — `failed` with retry budget left. The item goes
+     *    back on the queue via {@link requeueAfterFailure}, which bumps
+     *    `retryCount`. Deliberately NOT stamped: the item has left the stranding
+     *    statuses under its own power, and a stamp would be a claim about a
+     *    failure that is no longer the current one.
+     * 2. **succeeded by another item** — the caller already created a successor
+     *    (the `EventToWorkItemBridge` retry/escalation WorkItem). Stamped with
+     *    its id.
+     * 3. **terminal** — budget spent, or a status with no retry path. Stamped,
+     *    and escalated so a human or the orchestrator renders the verdict. This
+     *    is the "deliberate terminal state with an audit record" case: the item
+     *    stays in `rejected`/`failed` by design, because the alternative —
+     *    adding `→ cancelled` edges — would re-open the illegal-correction
+     *    surface #733 closed and turn a deliberate decision into a 24h default.
+     *
+     * Idempotent and re-entrant: an already-disposed item is returned unchanged,
+     * so concurrent reconciler passes converge and the safety-net rule cannot
+     * fire twice on the same strand. Terminating: the only branch that repeats
+     * is (1), and it bumps `retryCount`, so it can run at most `maxRetries`
+     * times before (3) becomes the only reachable outcome.
+     *
+     * @param workItemId - The stranded WorkItem.
+     * @param options    - `reason` is carried into the audit record and the
+     *                     escalation. `actor` defaults to `'system'`.
+     *                     `successorWorkItemId` selects outcome (2) when the
+     *                     caller owns a real successor.
+     * @returns The recorded disposition, or `null` when there was nothing to do
+     *          (item missing, or not in a stranding status).
+     *
+     * @example
+     * ```typescript
+     * await pool.disposeFailedWorkItem(wi.id, { reason: 'SLA escalation timeout' });
+     * ```
+     */
+    disposeFailedWorkItem(workItemId: string, options: {
+        reason: string;
+        actor?: WorkItemOwner;
+        successorWorkItemId?: string;
+    }): Promise<WorkItemDisposition | null>;
+    /**
+     * Persist a disposition record onto a WorkItem's metadata.
+     *
+     * Writes metadata only — no status transition — so it is safe to call on an
+     * item whose status has no legal outbound edge, which is precisely the
+     * situation a `terminal` disposition describes.
+     *
+     * @param workItemId  - WorkItem to stamp.
+     * @param disposition - The record to write.
+     * @returns The disposition as written.
+     */
+    private stampDisposition;
     /**
      * Processes a heartbeat from an agent for their active claim.
      *

package/dist/backend/backend/src/services/task-pool/task-pool.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-pool.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/task-pool/task-pool.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"task-pool.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/task-pool/task-pool.service.ts"],"names":[],"mappings":"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"}

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

@@ -12,7 +12,7 @@ import { PoolStorage } from './pool-storage.js';
 import { ClaimService } from './claim.service.js';
 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 { isWorkItem, isValidWorkItemTransition, isTransitionPermitted, LAST_REQUEUED_AT_METADATA_KEY, DISPOSITION_METADATA_KEY, DISPOSITION_REQUIRED_STATUSES, getWorkItemDisposition, } from '../../types/v2/work-item.types.js';
 import { createTaskClaim, } from '../../types/v2/claim.types.js';
 /**
  * Structured error thrown by {@link TaskPoolService.removeFromPool}
@@ -33,30 +33,6 @@ export class WorkItemClaimedError extends Error {
         Object.setPrototypeOf(this, WorkItemClaimedError.prototype);
     }
 }
-// ---------------------------------------------------------------------------
-// Service
-// ---------------------------------------------------------------------------
-/**
- * TaskPoolService manages the lifecycle of execution-ready WorkItems.
- *
- * Core operations:
- * - {@link addToPool} — enqueue an execution-ready WorkItem
- * - {@link claimFromPool} — agent claims the next available item
- * - {@link releaseBack} — release a claimed item back to the pool
- * - {@link getPoolStatus} — snapshot of pool statistics
- *
- * @example
- * ```typescript
- * const pool = TaskPoolService.getInstance();
- * pool.addToPool(workItem);
- * const result = pool.claimFromPool('agent-leo', { types: ['delegate'] });
- * if (result) {
- *   // agent works on result.workItem
- *   // when done:
- *   pool.completeItem(result.workItem.id);
- * }
- * ```
- */
 export class TaskPoolService {
     static instance = null;
     storage;
@@ -613,7 +589,12 @@ export class TaskPoolService {
             // refuse to overwrite a non-matching existing target.
             const claimedItem = await this.transitionStatus(selected.id, 'running', 'system', (wi) => {
                 if (!wi.target) {
+                    // Broadcast claim: record that this target is an incidental
+                    // claim stamp, not a deliberate assignment, so releaseBack
+                    // returns the item to the broadcast pool instead of binding
+                    // it to this agent forever.
                     wi.target = agentId;
+                    wi.targetSource = 'claim';
                 }
                 // else: target already === agentId per the filter; leave as-is.
             });
@@ -696,7 +677,10 @@ export class TaskPoolService {
             // undefined; never overwrite an existing target.
             const claimedItem = await this.transitionStatus(workItemId, 'running', 'system', (wi) => {
                 if (!wi.target) {
+                    // Broadcast claim — see claimFromPool: this is a claim stamp,
+                    // not an assignment.
                     wi.target = agentId;
+                    wi.targetSource = 'claim';
                 }
             });
             if (!claimedItem)
@@ -714,11 +698,55 @@ export class TaskPoolService {
      *
      * The item's status reverts to 'queued' and the claim is marked 'released'.
      *
+     * A release is an ADMINISTRATIVE event, not a failure. Two invariants
+     * follow, and both were violated before 2026-08-21:
+     *
+     * 1. **`target` is preserved.** A release says "this attempt ended", not
+     *    "this work no longer belongs to that agent". Clearing it silently
+     *    destroyed a deliberate assignment — and because the wake gate admits
+     *    a worker only when a queued/blocked WI carries `target === their
+     *    session`, it also made the assigned worker unwakeable for their own
+     *    work (`wake_gate_no_pool_work`). The sibling failure path,
+     *    {@link requeueAfterFailure}, already keeps `target` on the far
+     *    stronger grounds of an actual failure; there is no coherent reading
+     *    in which a lease lapse un-assigns work that a failure would not.
+     *    Genuine un-assignment is still possible, but it must be asked for by
+     *    name via `options.unassign` — never inferred from a lease expiring.
+     *
+     *    One carve-out, and it is not an exception to the rule so much as a
+     *    sharpening of it: `claimFromPool` stamps `target` on a *broadcast*
+     *    item to record who picked it up. That stamp is not an assignment,
+     *    and it is dropped on release (`targetSource === 'claim'`) so the
+     *    item returns to the broadcast pool. Preserving it would let one
+     *    claim permanently bind unassigned work to a single agent — and if
+     *    that agent died, only a dead session could ever re-claim it.
+     *
+     * 2. **`retryCount` is untouched.** That counter means failures only (see
+     *    {@link WorkItem.retryCount}); consumers branch on
+     *    `retryCount < maxRetries` to decide retry-in-place vs terminal-and-
+     *    escalate. Charging a retry for lease churn drove live work to 3/3
+     *    with zero failures. Release churn is counted separately in
+     *    {@link WorkItem.releaseCount}, which nothing branches on.
+     *
      * @param workItemId - ID of the work item to release
      * @param reason - Why the item is being released
-     * @throws Error if work item not found or not currently claimed
+     * @param options - Release options
+     * @param options.unassign - When true, ALSO clear `target`, returning the
+     *   item to the unassigned pool. Opt-in only, for the case where a caller
+     *   genuinely means "someone else should take this". Defaults to false.
+     * @throws Error if work item not found, or its status is not
+     *   'running' or 'blocked'
+     *
+     * @example
+     * ```typescript
+     * // Lease lapsed / claim revoked — the owner keeps the work.
+     * await pool.releaseBack(id, 'claim revoked: grace exceeded');
+     *
+     * // Deliberate hand-back — anyone may pick this up.
+     * await pool.releaseBack(id, 'agent declined', { unassign: true });
+     * ```
      */
-    async releaseBack(workItemId, reason) {
+    async releaseBack(workItemId, reason, options = {}) {
         const workItem = await this.storage.findWorkItem(workItemId);
         if (!workItem) {
             throw new Error(`WorkItem not found: ${workItemId}`);
@@ -739,21 +767,31 @@ export class TaskPoolService {
         // 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';
+        // Side-effect mutations (startedAt clear, opt-in target clear,
+        // releaseCount bump) move into the atomic mutator.
+        //
+        // `target` survives every release; only an explicit `unassign` clears
+        // it. `retryCount` is NOT touched here — a release is not a failure —
+        // and release churn is recorded in `releaseCount` instead.
+        const unassign = options.unassign === true;
         await this.transitionStatus(workItemId, 'queued', 'system', (wi) => {
             wi.startedAt = undefined;
-            if (!wasBlocked) {
+            // Drop the target only when the caller explicitly asked, or when the
+            // target was never an assignment in the first place — a broadcast
+            // item stamped by whoever happened to claim it belongs back in the
+            // broadcast pool, not bound to that agent.
+            if (unassign || wi.targetSource === 'claim') {
                 wi.target = undefined;
+                wi.targetSource = undefined;
             }
-            wi.retryCount += 1;
+            wi.releaseCount = (wi.releaseCount ?? 0) + 1;
         });
         await this.storage.flush();
         this.logger.info('WorkItem released back to pool', {
             workItemId,
             reason,
             claimId: claim?.id,
+            unassigned: unassign,
         });
     }
     /**
@@ -785,13 +823,30 @@ export class TaskPoolService {
         return wi.type === 'delegate';
     }
     /**
-     * Internal: release the active claim on a WorkItem (if any). Shared by
-     * `completeSimpleItem` and `submitForVerification` because both
+     * Release the active claim on a WorkItem, if it has one.
+     *
+     * Shared by `completeSimpleItem` and `submitForVerification` because both
      * represent the worker handing the item back to the system.
      *
+     * Also public for callers that must drive a terminal transition
+     * themselves rather than through {@link failItem}. The SLA orphan-close
+     * path is the live example: it targets `cancelled`, `failed` OR
+     * `rejected` depending on the origin status, so `failItem` — which always
+     * transitions to `failed` — cannot serve it. Such callers MUST call this,
+     * otherwise the claim stays `active` against a terminal WorkItem and
+     * quietly wedges the claiming agent. The mechanism is not an error, which
+     * is what makes it hard to spot: {@link claimFromPool} checks
+     * `findActiveClaimByAgent` BEFORE it scans the pool, and short-circuits by
+     * returning the held claim with `alreadyHeld: true` (issue #513). So the
+     * agent is handed the same terminal item on every poll and never sees the
+     * queued work waiting for them, until the lease/grace ladder revokes it.
+     *
+     * Idempotent: a no-op when no active claim exists.
+     *
      * @param workItemId - WorkItem whose claim should be released
-     * @param endReason - Reason recorded on the claim (`completed` /
-     *   `submitted_for_verification`) for auditability
+     * @param endReason - Reason recorded on the claim (`completed`,
+     *   `submitted_for_verification`, `sla escalation timeout ...`) for
+     *   auditability
      */
     async releaseClaim(workItemId, endReason) {
         const claim = await this.storage.findActiveClaimByWorkItem(workItemId);
@@ -1158,7 +1213,20 @@ export class TaskPoolService {
                 lastFailureReason: reason,
                 lastFailureAt: now,
                 retryAttempt: wi.retryCount,
+                // TTL anchor (see getTtlAnchorAt). The age-based expiry rules must
+                // measure this retry's window from HERE, not from the original
+                // `createdAt` — otherwise a WorkItem that failed after the 24h TTL is
+                // TTL-cancelled on the next reconciler pass, silently destroying the
+                // retry we just granted. `createdAt` is deliberately left untouched so
+                // it keeps meaning "when this work was first asked for".
+                [LAST_REQUEUED_AT_METADATA_KEY]: now,
             };
+            // A disposition describes how a PAST failure was dealt with. This item
+            // is back in play, so any existing stamp is history and must not be
+            // allowed to outlive the failure it described — otherwise the
+            // safety-net rule would read a stale stamp and skip the item the next
+            // time it strands. See DISPOSITION_METADATA_KEY.
+            delete wi.metadata[DISPOSITION_METADATA_KEY];
             // Clear the error field so a successful retry doesn't surface a
             // stale error message; the metadata above keeps the history.
             wi.error = undefined;
@@ -1171,6 +1239,167 @@ export class TaskPoolService {
             reason,
         });
     }
+    /**
+     * Decide and record how a stranded WorkItem is dealt with — the single
+     * funnel every `rejected`/`failed` writer must route through.
+     *
+     * `rejected` and `failed` are the only two statuses that are neither
+     * terminal nor able to reach a terminal state: their sole outbound edge is
+     * `→ queued`. An item parked in either is finished as far as every consumer
+     * is concerned (see `SLA_TERMINAL_WORK_ITEM_STATUSES`) and unfinished as far
+     * as the state machine is concerned, and until this funnel existed nothing
+     * owned closing that gap. Items written there by a path that did not itself
+     * arrange a successor simply stopped, permanently and — since PR #733
+     * correctly stopped the pruning rules emitting illegal corrections for them
+     * — silently.
+     *
+     * Exactly one of three things happens, and the choice is recorded rather
+     * than left to be re-derived later by scanning other WorkItems:
+     *
+     * 1. **retried in place** — `failed` with retry budget left. The item goes
+     *    back on the queue via {@link requeueAfterFailure}, which bumps
+     *    `retryCount`. Deliberately NOT stamped: the item has left the stranding
+     *    statuses under its own power, and a stamp would be a claim about a
+     *    failure that is no longer the current one.
+     * 2. **succeeded by another item** — the caller already created a successor
+     *    (the `EventToWorkItemBridge` retry/escalation WorkItem). Stamped with
+     *    its id.
+     * 3. **terminal** — budget spent, or a status with no retry path. Stamped,
+     *    and escalated so a human or the orchestrator renders the verdict. This
+     *    is the "deliberate terminal state with an audit record" case: the item
+     *    stays in `rejected`/`failed` by design, because the alternative —
+     *    adding `→ cancelled` edges — would re-open the illegal-correction
+     *    surface #733 closed and turn a deliberate decision into a 24h default.
+     *
+     * Idempotent and re-entrant: an already-disposed item is returned unchanged,
+     * so concurrent reconciler passes converge and the safety-net rule cannot
+     * fire twice on the same strand. Terminating: the only branch that repeats
+     * is (1), and it bumps `retryCount`, so it can run at most `maxRetries`
+     * times before (3) becomes the only reachable outcome.
+     *
+     * @param workItemId - The stranded WorkItem.
+     * @param options    - `reason` is carried into the audit record and the
+     *                     escalation. `actor` defaults to `'system'`.
+     *                     `successorWorkItemId` selects outcome (2) when the
+     *                     caller owns a real successor.
+     * @returns The recorded disposition, or `null` when there was nothing to do
+     *          (item missing, or not in a stranding status).
+     *
+     * @example
+     * ```typescript
+     * await pool.disposeFailedWorkItem(wi.id, { reason: 'SLA escalation timeout' });
+     * ```
+     */
+    async disposeFailedWorkItem(workItemId, options) {
+        const { reason, actor = 'system', successorWorkItemId } = options;
+        const workItem = await this.storage.findWorkItem(workItemId);
+        if (!workItem)
+            return null;
+        // Only the stranding statuses need a disposition. Anything else is either
+        // still in play or already strictly terminal.
+        if (!DISPOSITION_REQUIRED_STATUSES.has(workItem.status))
+            return null;
+        // Idempotency: the stamp IS the key. Two passes converge here.
+        const existing = getWorkItemDisposition(workItem);
+        if (existing)
+            return existing;
+        const now = new Date().toISOString();
+        // (2) The caller owns a real successor — record it and stop.
+        if (successorWorkItemId) {
+            return this.stampDisposition(workItemId, {
+                kind: 'succeeded_by',
+                at: now,
+                by: actor,
+                reason,
+                successorWorkItemId,
+            });
+        }
+        // (1) Retry in place. Only `failed` has a retry path — `rejected` reaches
+        // `queued` too, but re-running work a reviewer rejected without a fresh
+        // verdict would re-execute exactly what was turned down.
+        // `retryCount` is FAILURES ONLY — this branch is load-bearing on that
+        // semantic, not incidentally coupled to it. Reading a churn-inflated count
+        // here would send work that never failed straight to `terminal`.
+        //
+        // That is an invariant rather than an assumption as of #739: `releaseBack`
+        // used to bump `retryCount` on every lease lapse, so a worker who simply
+        // stopped heartbeating was charged a failure. Release churn now goes to
+        // {@link WorkItem.releaseCount}, which nothing branches on. Keep it that
+        // way — if a future change makes anything other than a failure move
+        // `retryCount`, this branch silently starts terminating live work, and a
+        // second counter here would hide that rather than surface it.
+        if (workItem.status === 'failed' && workItem.retryCount < workItem.maxRetries) {
+            await this.requeueAfterFailure(workItemId, reason);
+            this.logger.info('Stranded WorkItem retried in place', {
+                workItemId,
+                retryCount: workItem.retryCount + 1,
+                maxRetries: workItem.maxRetries,
+                reason,
+            });
+            // Not stamped — see the doc comment. The item is queued again, and the
+            // requeue itself is the audit record (metadata.failureHistory).
+            return {
+                kind: 'retried_in_place',
+                at: now,
+                by: actor,
+                reason,
+            };
+        }
+        // (3) Terminal. Escalate for the verdict, then stamp — in that order, so a
+        // failed escalation cannot leave a stamp claiming an escalation happened.
+        let escalationId;
+        try {
+            const { EscalationRouterService } = await import('../v3/escalation-router.service.js');
+            escalationId =
+                (await EscalationRouterService.getInstance().escalateFailedWorkItem(workItem, reason)) ?? undefined;
+        }
+        catch (err) {
+            // Best-effort, matching every other escalation call site: a messaging
+            // blip must not leave the item stranded a second time. The stamp is
+            // still written, without an escalationId, so the gap is visible in the
+            // audit record rather than hidden by a retry loop.
+            this.logger.warn('escalateFailedWorkItem threw during disposition (non-fatal)', {
+                workItemId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        return this.stampDisposition(workItemId, {
+            kind: 'terminal',
+            at: now,
+            by: actor,
+            reason,
+            escalationId,
+        });
+    }
+    /**
+     * Persist a disposition record onto a WorkItem's metadata.
+     *
+     * Writes metadata only — no status transition — so it is safe to call on an
+     * item whose status has no legal outbound edge, which is precisely the
+     * situation a `terminal` disposition describes.
+     *
+     * @param workItemId  - WorkItem to stamp.
+     * @param disposition - The record to write.
+     * @returns The disposition as written.
+     */
+    async stampDisposition(workItemId, disposition) {
+        const workItem = await this.storage.findWorkItem(workItemId);
+        if (workItem) {
+            workItem.metadata = {
+                ...(workItem.metadata ?? {}),
+                [DISPOSITION_METADATA_KEY]: disposition,
+            };
+            await this.storage.flush();
+        }
+        this.logger.info('WorkItem disposition recorded', {
+            workItemId,
+            kind: disposition.kind,
+            successorWorkItemId: disposition.successorWorkItemId,
+            escalationId: disposition.escalationId,
+            reason: disposition.reason,
+        });
+        return disposition;
+    }
     // -----------------------------------------------------------------------
     // Claim Lifecycle (delegated to ClaimService)
     // -----------------------------------------------------------------------
@@ -1394,6 +1623,9 @@ export class TaskPoolService {
         const handoffNote = `[HANDOFF] ${fromAgent} → ${newTarget}: ${reason || '(no reason)'}`;
         await this.storage.updateWorkItem(workItemId, (item) => {
             item.target = newTarget;
+            // An explicit handoff is a deliberate assignment: it must survive a
+            // later release.
+            item.targetSource = 'assigned';
             const existing = (item.metadata && typeof item.metadata === 'object' ? item.metadata : {});
             const notes = Array.isArray(existing.notes) ? existing.notes : [];
             notes.push(`${new Date().toISOString()} ${handoffNote}`);