@sema-agent/server 7.122.0 → 7.124.0

package/dist/tool-approval.js

@@ -11,6 +11,7 @@ import { recordFailOpen } from "./observability/fail-open.js";
 import { deriveAskId, deriveAskScopedBatchId, deriveBatchId, MAX_DECISION_NOTE_CHARS } from "./approval-ask-machine.js";
 import { ApprovalCardEnvelopeSchema, MAX_RULE_OFFERS, buildApprovalCard, buildApprovalCardEnvelope, buildApprovalRequestFrame, buildRevokeFrame, readDenialLimitFallback, readProbeCause, readProbeReason, readReadRootCandidate, readRuleEvidence, readAllowRuleShadowed, readRuleOffersAbsence, readRuleOffersAbsenceSeat, readParkRowTrueSeat, readAskClassPair, readClosedWordSeat, RuleOfferRawSchema, backfillLegacyBatchMemberKind, screenUncoveredDetailSeat, } from "./approval-card.js";
 import { POLICY_REFUSAL_DECISION, projectAskTerminalClaimTruth } from "./plugins/approval-ask-store-sql.js";
+import { APPROVAL_ENDING_CAUSES, SETTLE_OUTCOME, causeOfAskRow } from "./approval-deny-reasons.js";
 import { settleByPolicy } from "./approval-policy-settlement.js";
 import { governanceAskMarksFor, runWithGovernanceAskScope } from "./governance-ask-marks.js";
 import { governanceOriginOf } from "./runtime-governance.js";
@@ -31,7 +32,6 @@ const SUSPENDED_POLL_BUDGET_MS = 5_000;
 const EDITED_DECISION_MARK_CAP_MS = 10_000;
 const DEFAULT_WINDOW_MARGIN_MS = 10_000;
 const SHUTDOWN_DRAIN_POLL_MS = 50;
-const SHUTDOWN_BEFORE_PARK = "shutdown_before_park";
 const MAX_ALLOW_SESSIONS = 4096;
 const DEFAULT_ADMIT_MAX_PER_TASK = 32;
 const DEFAULT_ADMIT_MAX_PER_OWNER = 256;
@@ -59,6 +59,7 @@ function durableRuleMaterial(material) {
     }
     return { ruleCommand: material.command, ruleScopeRoot: material.scopeRoot ?? null };
 }
+export const NOT_PENDING_UNKNOWN_CAUSE = "unknown_or_other_replica";
 export const ASK_DECISION_CONSUMER_ABSENT = "absent";
 const MAX_INFLIGHT_TERMINAL_CLAIMS = 2;
 const DURABLE_CONVERGE_BACKOFF_MS = [50, 100, 200, 400, 800, 1600];
@@ -366,6 +367,14 @@ function settleArgsOfDecided(outcome) {
         ...(outcome.settledBy !== undefined ? { settledBy: outcome.settledBy } : {}),
     };
 }
+function verdictOfDecided(args) {
+    return {
+        by: "human",
+        allowed: args.allowed,
+        ...(args.updatedInput !== undefined ? { updatedInput: args.updatedInput } : {}),
+        ...(args.settledBy !== undefined ? { hostSettledBy: args.settledBy } : {}),
+    };
+}
 function settleArgsOf(outcome) {
     return outcome === "unavailable" ? "unavailable" : settleArgsOfDecided(outcome);
 }
@@ -499,16 +508,16 @@ export class ToolApprovalCoordinator {
             return outcome;
         const dispatch = (res, where) => {
             if (res.claimed) {
-                this.settleSameAskIdParkRoute(row.askId);
+                this.settleSameAskIdParkRoute(row.askId, APPROVAL_ENDING_CAUSES.UNDELIVERABLE);
                 return undefined;
             }
             const read = this.classifyClaimLoss(row.askId, res.current, where);
-            this.dispatchClaimTruth(row.askId, read);
+            this.dispatchClaimTruth(row.askId, read, APPROVAL_ENDING_CAUSES.UNDELIVERABLE);
             return read;
         };
         let res;
         try {
-            res = await this.withStoreDeadline(settleByPolicy(store, row, this.unattendedPolicy), "claimTerminal(unattended-fallback)", DURABLE_CALL_TIMEOUT_MS, (late) => {
+            res = await this.withStoreDeadline(settleByPolicy(store, row, this.unattendedPolicy, APPROVAL_ENDING_CAUSES.UNDELIVERABLE), "claimTerminal(unattended-fallback)", DURABLE_CALL_TIMEOUT_MS, (late) => {
                 dispatch(late, "late:unattended-fallback");
             });
         }
@@ -707,7 +716,7 @@ export class ToolApprovalCoordinator {
         let n = 0;
         for (const e of this.pending.values()) {
             if (e.ctxTaskId === wireTaskId && e.settledOutcome === undefined) {
-                e.forceParkNow();
+                e.forceParkNow(APPROVAL_ENDING_CAUSES.STREAM_DISCONNECTED);
                 n++;
             }
         }
@@ -717,7 +726,7 @@ export class ToolApprovalCoordinator {
         this.shutdownDraining = true;
         for (const e of [...this.pending.values()])
             if (e.settledOutcome === undefined)
-                e.forceParkNow();
+                e.forceParkNow(APPROVAL_ENDING_CAUSES.SHUTDOWN_BEFORE_PARK);
     }
     async drainForShutdown(deadlineMs) {
         this.beginDrain();
@@ -789,13 +798,13 @@ export class ToolApprovalCoordinator {
     storeErrorCount() {
         return this.storeErrorTally;
     }
-    settleVoidedSiblings(askIds) {
+    settleVoidedSiblings(askIds, cause) {
         for (const askId of askIds) {
             const entries = this.pendingByAskId.get(askId);
             if (!entries)
                 continue;
             for (const entry of [...entries])
-                entry.settle(false, "expired");
+                entry.settle({ by: "system", cause });
         }
     }
     governanceForcedOf(origin, req) {
@@ -884,9 +893,13 @@ export class ToolApprovalCoordinator {
     classifyClaimLoss(askId, current, _where) {
         if (current.state === "absent")
             return { kind: "absent" };
+        const rowCause = current.cause;
+        if (rowCause?.kind === "ending")
+            return { kind: "ended", cause: rowCause.cause };
         const replayedOutcome = replayTerminalAskRow(current);
-        if (replayedOutcome === "unavailable")
-            return { kind: "parked" };
+        if (replayedOutcome === "unavailable") {
+            return rowCause?.kind === "park_trigger" ? { kind: "parked", cause: rowCause.cause } : { kind: "parked" };
+        }
         const replayed = settleArgsOfDecided(replayedOutcome);
         if (!replayed.allowed)
             return { kind: "decided", outcome: replayedOutcome };
@@ -905,20 +918,23 @@ export class ToolApprovalCoordinator {
         }
         return false;
     }
-    settleSameAskIdParkRoute(askId) {
+    settleSameAskIdParkRoute(askId, cause) {
         const entries = this.pendingByAskId.get(askId);
         if (!entries)
             return;
         for (const entry of [...entries])
-            entry.settleParkRoute();
+            entry.settleParkRoute(cause);
     }
-    dispatchClaimTruth(askId, read) {
+    dispatchClaimTruth(askId, read, parkedCause) {
         switch (read.kind) {
             case "decided":
                 this.notifyExternalDecision(askId, read.outcome);
                 return;
+            case "ended":
+                this.settleVoidedSiblings([askId], read.cause);
+                return;
             case "parked":
-                this.settleSameAskIdParkRoute(askId);
+                this.settleSameAskIdParkRoute(askId, read.cause ?? parkedCause);
                 return;
             case "absent":
             case "edit-in-flight":
@@ -1006,7 +1022,7 @@ export class ToolApprovalCoordinator {
         const args = settleArgsOfDecided(outcome);
         let settled = 0;
         for (const entry of [...entries]) {
-            entry.settle(args.allowed, args.allowed ? "allowed" : "denied", args.updatedInput, args.settledBy);
+            entry.settle(verdictOfDecided(args));
             settled += 1;
         }
         return { settled };
@@ -1058,7 +1074,7 @@ export class ToolApprovalCoordinator {
                     this.streams.delete(key);
                 for (const [, p] of [...this.pending]) {
                     if (p.targetCtxs?.has(ctx))
-                        p.onTargetGone?.(ctx);
+                        p.onTargetGone?.(ctx, APPROVAL_ENDING_CAUSES.RUN_EXITED);
                 }
                 this.settleParksAwaitingCommit((p) => p.carrierLeg === ctx, "leg-closed");
                 this.askAudit?.noteLegClosed(ctx.taskId);
@@ -1240,7 +1256,7 @@ export class ToolApprovalCoordinator {
                 }), "ensureAsk", DURABLE_CALL_TIMEOUT_MS, (late) => {
                     if (late.row.state !== "STREAM_PENDING") {
                         lateTerminalRow = late.row;
-                        this.dispatchClaimTruth(late.row.askId, this.classifyClaimLoss(late.row.askId, projectAskTerminalClaimTruth(late.row), "late:ensureAsk"));
+                        this.dispatchClaimTruth(late.row.askId, this.classifyClaimLoss(late.row.askId, projectAskTerminalClaimTruth(late.row), "late:ensureAsk"), APPROVAL_ENDING_CAUSES.UNDELIVERABLE);
                         return;
                     }
                     lateEnsuredRow = late.inserted ? { askId: late.row.askId, batchId: late.row.batchId } : undefined;
@@ -1351,7 +1367,8 @@ export class ToolApprovalCoordinator {
         let timer;
         let resolveAllowed;
         const allowedP = new Promise((resolve) => { resolveAllowed = resolve; });
-        let lastOutcome = "expired";
+        let lastOutcome = SETTLE_OUTCOME.EXPIRED;
+        let lastCause;
         const abortListeners = [];
         let selfEntry;
         let hostSettled;
@@ -1383,12 +1400,17 @@ export class ToolApprovalCoordinator {
             }
             return shapeDeny(false);
         };
-        const settle = (allowed, outcome, updatedInput, hostSettledBy, denyReason, readRootGrant) => {
+        const settle = (verdict) => {
             if (done)
                 return;
             done = true;
+            const allowed = verdict.by === "human" && verdict.allowed;
+            const outcome = verdict.by === "system" ? SETTLE_OUTCOME.EXPIRED : verdict.allowed ? SETTLE_OUTCOME.ALLOWED : SETTLE_OUTCOME.DENIED;
+            const hostSettledBy = verdict.hostSettledBy;
+            const updatedInput = verdict.by === "human" ? verdict.updatedInput : undefined;
+            const readRootGrant = verdict.by === "human" ? verdict.readRootGrant : undefined;
             hostSettled = hostSettledBy;
-            denyReasonSettled = allowed ? undefined : denyReason;
+            denyReasonSettled = verdict.by === "human" && !verdict.allowed ? verdict.denyReason : undefined;
             if (timer)
                 clearTimeout(timer);
             for (const [sig, fn] of abortListeners)
@@ -1407,19 +1429,23 @@ export class ToolApprovalCoordinator {
                 }
             }
             lastOutcome = outcome;
+            lastCause = verdict.by === "system" ? verdict.cause : undefined;
             releaseAdmission();
             if (selfEntry)
                 selfEntry.settledOutcome = outcome;
-            const shutdownEnded = this.shutdownDraining && outcome === "expired";
-            const settleRecord = () => ({
-                approvalId: wireApprovalId,
-                outcome,
-                ...(windowRouteUnavailable ? { parkRouted: true } : {}),
-                ...(hostSettledBy !== undefined ? { settledBy: hostSettledBy } : {}),
-                ...(shutdownEnded ? { cause: SHUTDOWN_BEFORE_PARK } : {}),
-                settledAtMs: Date.now(),
-            });
-            if (shutdownEnded && windowRouteUnavailable && this.unattendedRoutesToPark && this.parkCommits !== undefined) {
+            const endedWhileDraining = this.shutdownDraining && verdict.by === "system";
+            const settleRecord = () => {
+                const common = {
+                    approvalId: wireApprovalId,
+                    ...(windowRouteUnavailable ? { parkRouted: true } : {}),
+                    ...(hostSettledBy !== undefined ? { settledBy: hostSettledBy } : {}),
+                    settledAtMs: Date.now(),
+                };
+                return verdict.by === "system"
+                    ? { ...common, outcome: SETTLE_OUTCOME.EXPIRED, cause: verdict.cause }
+                    : { ...common, outcome: verdict.allowed ? SETTLE_OUTCOME.ALLOWED : SETTLE_OUTCOME.DENIED };
+            };
+            if (endedWhileDraining && windowRouteUnavailable && this.unattendedRoutesToPark && this.parkCommits !== undefined) {
                 this.parksAwaitingCommit.add({
                     approvalId: wireApprovalId,
                     taskId: origin.taskId,
@@ -1434,23 +1460,26 @@ export class ToolApprovalCoordinator {
             }
             resolveAllowed({ allowed, ...(allowed && updatedInput !== undefined ? { updatedInput } : {}), ...(allowed && readRootGrant !== undefined ? { readRootGrant } : {}) });
         };
-        const broadcastClaimTruth = (read) => {
+        const broadcastClaimTruth = (read, armCause) => {
             if (askId === undefined)
                 return;
-            this.dispatchClaimTruth(askId, read);
+            this.dispatchClaimTruth(askId, read, armCause);
         };
-        const settleFromClaimLoss = (read) => {
+        const settleFromClaimLoss = (read, armCause) => {
             switch (read.kind) {
                 case "decided": {
-                    const args = settleArgsOfDecided(read.outcome);
-                    settle(args.allowed, args.allowed ? "allowed" : "denied", args.updatedInput, args.settledBy);
-                    broadcastClaimTruth(read);
+                    settle(verdictOfDecided(settleArgsOfDecided(read.outcome)));
+                    broadcastClaimTruth(read, armCause);
                     return true;
                 }
+                case "ended":
+                    settle({ by: "system", cause: read.cause });
+                    broadcastClaimTruth(read, armCause);
+                    return true;
                 case "parked":
                     windowRouteUnavailable = true;
-                    settle(false, "expired");
-                    broadcastClaimTruth(read);
+                    settle({ by: "system", cause: read.cause ?? armCause });
+                    broadcastClaimTruth(read, armCause);
                     return true;
                 case "absent":
                 case "edit-in-flight":
@@ -1461,15 +1490,15 @@ export class ToolApprovalCoordinator {
                 }
             }
         };
-        const lateClaimLossSettle = (current, intent) => {
+        const lateClaimLossSettle = (current, intent, armCause) => {
             if (askId === undefined)
                 return;
             const read = this.classifyClaimLoss(askId, current, `late:${intent}`);
             if (done) {
-                broadcastClaimTruth(read);
+                broadcastClaimTruth(read, armCause);
                 return;
             }
-            settleFromClaimLoss(read);
+            settleFromClaimLoss(read, armCause);
         };
         const boundedClaim = (mk, label, timeoutMs, late) => {
             const release = this.admitTerminalClaim(askId ?? wireApprovalId);
@@ -1510,7 +1539,7 @@ export class ToolApprovalCoordinator {
                     }
                     if (probed.kind === "row") {
                         const read = this.classifyClaimLoss(pinnedAskId, probed.current, `yield-probe:${arm.intent}`);
-                        if (settleFromClaimLoss(read))
+                        if (settleFromClaimLoss(read, arm.cause))
                             return;
                         if (read.kind === "edit-in-flight")
                             lastLoss = probed.current;
@@ -1547,10 +1576,10 @@ export class ToolApprovalCoordinator {
                 arm.onLostTruth?.(outcome.current);
                 const read = this.classifyClaimLoss(pinnedAskId, outcome.current, `claim:${arm.intent}`);
                 if (done) {
-                    broadcastClaimTruth(read);
+                    broadcastClaimTruth(read, arm.cause);
                     return;
                 }
-                if (settleFromClaimLoss(read))
+                if (settleFromClaimLoss(read, arm.cause))
                     return;
                 if (read.kind === "absent") {
                     arm.settleByIntent();
@@ -1564,24 +1593,24 @@ export class ToolApprovalCoordinator {
                 return;
             if (this.editedDecisionInFlight(pinnedAskId)) {
                 windowRouteUnavailable = true;
-                settle(false, "expired");
+                settle({ by: "system", cause: arm.cause });
                 return;
             }
-            if (lastLoss !== undefined && settleFromClaimLoss(this.classifyClaimLoss(pinnedAskId, lastLoss, `claim-tail:${arm.intent}`)))
+            if (lastLoss !== undefined && settleFromClaimLoss(this.classifyClaimLoss(pinnedAskId, lastLoss, `claim-tail:${arm.intent}`), arm.cause))
                 return;
             recordFailOpen(ambiguousCasFailOpenTag(arm.intent), `askId=${pinnedAskId} attempts=${attempt} claims=${claimsIssued} rejects=${rejects} elapsedMs=${Date.now() - ladderStartedAt}`);
             arm.settleByIntent();
         };
-        const settleParkRouteIfUnsettled = (hostSettledBy) => {
+        const settleParkRouteIfUnsettled = (hostSettledBy, cause) => {
             if (done)
                 return;
             windowRouteUnavailable = true;
-            settle(false, "expired", undefined, hostSettledBy);
+            settle({ by: "system", cause, ...(hostSettledBy !== undefined ? { hostSettledBy } : {}) });
         };
-        const windowExpired = (hostSelfReport) => {
+        const windowExpired = (hostSelfReport, cause) => {
             void (async () => {
                 if (!this.askStore || askId === undefined || batchId === undefined) {
-                    settleParkRouteIfUnsettled(hostSelfReport);
+                    settleParkRouteIfUnsettled(hostSelfReport, cause);
                     return;
                 }
                 const store = this.askStore;
@@ -1589,45 +1618,46 @@ export class ToolApprovalCoordinator {
                 const pinnedBatchId = batchId;
                 await resolveLocalOutcome({
                     intent: "expire",
+                    cause,
                     storeLabel: "claimTerminal(window)",
-                    claim: (timeoutMs) => boundedClaim(() => settleByPolicy(store, { askId: pinnedAskId, batchId: pinnedBatchId }, this.unattendedPolicy), "claimTerminal(window)", timeoutMs, (late) => {
+                    claim: (timeoutMs) => boundedClaim(() => settleByPolicy(store, { askId: pinnedAskId, batchId: pinnedBatchId }, this.unattendedPolicy, cause), "claimTerminal(window)", timeoutMs, (late) => {
                         if (!late.claimed) {
-                            lateClaimLossSettle(late.current, "expire");
+                            lateClaimLossSettle(late.current, "expire", cause);
                             return;
                         }
-                        this.settleSameAskIdParkRoute(pinnedAskId);
-                        this.settleVoidedSiblings(late.voidedSiblings);
+                        this.settleSameAskIdParkRoute(pinnedAskId, cause);
+                        this.settleVoidedSiblings(late.voidedSiblings, APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN);
                         this.emitRevokeTo(aliveCtxs, buildRevokeFrame(pinnedBatchId, late.voidedSiblings, "superseded_by_park", Date.now(), origin.taskId));
                     }),
                     onWon: (res) => {
                         windowRouteUnavailable = true;
-                        settle(false, "expired");
-                        this.settleSameAskIdParkRoute(pinnedAskId);
-                        this.settleVoidedSiblings(res.voidedSiblings);
+                        settle({ by: "system", cause });
+                        this.settleSameAskIdParkRoute(pinnedAskId, cause);
+                        this.settleVoidedSiblings(res.voidedSiblings, APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN);
                         this.emitRevokeTo(aliveCtxs, buildRevokeFrame(pinnedBatchId, res.voidedSiblings, "superseded_by_park", Date.now(), origin.taskId));
                     },
-                    settleByIntent: () => settleParkRouteIfUnsettled(hostSelfReport),
+                    settleByIntent: () => settleParkRouteIfUnsettled(hostSelfReport, cause),
                 });
             })();
         };
-        const forceParkNow = () => {
+        const forceParkNow = (cause) => {
             if (done)
                 return;
             if (!this.askStore || askId === undefined || batchId === undefined) {
-                settleParkRouteIfUnsettled(undefined);
+                settleParkRouteIfUnsettled(undefined, cause);
                 return;
             }
-            windowExpired(undefined);
+            windowExpired(undefined, cause);
         };
-        timer = setTimeout(() => windowExpired("timeout"), this.askStore ? Math.max(0, persistedExpiresAtMs - Date.now()) : effectiveWindowMs);
+        timer = setTimeout(() => windowExpired("timeout", APPROVAL_ENDING_CAUSES.TTL_EXPIRED), this.askStore ? Math.max(0, persistedExpiresAtMs - Date.now()) : effectiveWindowMs);
         timer.unref?.();
-        const runCancel = async () => {
+        const runCancel = async (cause) => {
             if (!this.askStore || askId === undefined || batchId === undefined) {
-                settle(false, "expired");
+                settle({ by: "system", cause });
                 return;
             }
             if (this.hasOtherSuspendedOwner(askId, selfEntry)) {
-                settle(false, "expired");
+                settle({ by: "system", cause });
                 return;
             }
             const store = this.askStore;
@@ -1640,52 +1670,53 @@ export class ToolApprovalCoordinator {
             };
             await resolveLocalOutcome({
                 intent: "cancel",
+                cause,
                 storeLabel: "claimTerminal(cancel)",
-                claim: (timeoutMs) => boundedClaim(() => store.claimTerminal(pinnedAskId, pinnedBatchId, "cancel"), "claimTerminal(cancel)", timeoutMs, (late) => {
+                claim: (timeoutMs) => boundedClaim(() => store.claimTerminal(pinnedAskId, pinnedBatchId, "cancel", { cause }), "claimTerminal(cancel)", timeoutMs, (late) => {
                     if (!late.claimed) {
                         cancelLostTruth(late.current);
-                        lateClaimLossSettle(late.current, "cancel");
+                        lateClaimLossSettle(late.current, "cancel", cause);
                         return;
                     }
-                    this.settleVoidedSiblings([pinnedAskId]);
+                    this.settleVoidedSiblings([pinnedAskId], cause);
                     this.recordParkTombstone(wireApprovalId, { kind: "voidBridge", askId: pinnedAskId, batchId: pinnedBatchId, owner: origin.owner, parkedAtMs: Date.now() });
                     this.emitRevokeTo(aliveCtxs, buildRevokeFrame(pinnedBatchId, [pinnedAskId], "aborted", Date.now(), origin.taskId));
                 }),
                 onWon: () => {
-                    settle(false, "expired");
-                    this.settleVoidedSiblings([pinnedAskId]);
+                    settle({ by: "system", cause });
+                    this.settleVoidedSiblings([pinnedAskId], cause);
                     this.recordParkTombstone(wireApprovalId, { kind: "voidBridge", askId: pinnedAskId, batchId: pinnedBatchId, owner: origin.owner, parkedAtMs: Date.now() });
                     this.emitRevokeTo(aliveCtxs, buildRevokeFrame(pinnedBatchId, [pinnedAskId], "aborted", Date.now(), origin.taskId));
                 },
                 onLostTruth: cancelLostTruth,
-                settleByIntent: () => settle(false, "expired"),
+                settleByIntent: () => settle({ by: "system", cause }),
             });
         };
         if (signal) {
-            const onTaskAbort = () => void runCancel();
+            const onTaskAbort = () => void runCancel(APPROVAL_ENDING_CAUSES.RUN_CANCELLED);
             signal.addEventListener("abort", onTaskAbort, { once: true });
             abortListeners.push([signal, onTaskAbort]);
         }
         let liveConnections = aliveCtxs.length;
         const goneCtxs = new Set();
-        const onTargetGone = (c) => {
+        const onTargetGone = (c, cause) => {
             if (goneCtxs.has(c))
                 return;
             goneCtxs.add(c);
             liveConnections--;
             if (liveConnections <= 0)
-                void runCancel();
+                void runCancel(cause);
         };
         for (const c of aliveCtxs) {
             if (!c.abortSignal)
                 continue;
-            const onCtxAbort = () => onTargetGone(c);
+            const onCtxAbort = () => onTargetGone(c, APPROVAL_ENDING_CAUSES.RUN_CANCELLED);
             c.abortSignal.addEventListener("abort", onCtxAbort, { once: true });
             abortListeners.push([c.abortSignal, onCtxAbort]);
         }
         const earlyAbortDuringEnsure = signal?.aborted === true || aliveCtxs.some((c) => c.abortSignal?.aborted === true);
         if (earlyAbortDuringEnsure) {
-            await runCancel();
+            await runCancel(APPROVAL_ENDING_CAUSES.RUN_CANCELLED);
             if (done) {
                 return shapeOutcome(await allowedP);
             }
@@ -1712,7 +1743,7 @@ export class ToolApprovalCoordinator {
         const pendingEntry = {
             settle,
             forceParkNow,
-            settleParkRoute: () => settleParkRouteIfUnsettled(),
+            settleParkRoute: (cause) => settleParkRouteIfUnsettled(undefined, cause),
             owner: origin.owner,
             ...(primary ? { ctxTaskId: primary.taskId, originCtx: primary } : {}),
             ...(reachability === "unreached" ? { suspended: true } : {}),
@@ -1756,7 +1787,7 @@ export class ToolApprovalCoordinator {
             mintedAtMs: Date.now(),
         });
         if (this.shutdownDraining)
-            forceParkNow();
+            forceParkNow(APPROVAL_ENDING_CAUSES.SHUTDOWN_BEFORE_PARK);
         const cardFrame = askId !== undefined && cardForFrame !== undefined
             ? buildApprovalRequestFrame({ askId, taskId: origin.taskId, approvalId: wireApprovalId, card: cardForFrame, expiresAtMs: persistedExpiresAtMs, nowMs: Date.now() })
             : undefined;
@@ -1799,30 +1830,31 @@ export class ToolApprovalCoordinator {
                         if (done)
                             return;
                         emitFailed = true;
-                        settle(false, "expired");
+                        settle({ by: "system", cause: APPROVAL_ENDING_CAUSES.BROADCAST_LOST });
                     };
                     await resolveLocalOutcome({
                         intent: "unreachable",
+                        cause: APPROVAL_ENDING_CAUSES.BROADCAST_LOST,
                         storeLabel: "claimTerminal(emit-failed)",
-                        claim: (timeoutMs) => boundedClaim(() => settleByPolicy(store, { askId: pinnedAskId, batchId: pinnedBatchId }, this.unattendedPolicy), "claimTerminal(emit-failed)", timeoutMs, (late) => {
+                        claim: (timeoutMs) => boundedClaim(() => settleByPolicy(store, { askId: pinnedAskId, batchId: pinnedBatchId }, this.unattendedPolicy, APPROVAL_ENDING_CAUSES.BROADCAST_LOST), "claimTerminal(emit-failed)", timeoutMs, (late) => {
                             if (!late.claimed) {
-                                lateClaimLossSettle(late.current, "unreachable");
+                                lateClaimLossSettle(late.current, "unreachable", APPROVAL_ENDING_CAUSES.BROADCAST_LOST);
                                 return;
                             }
-                            this.settleSameAskIdParkRoute(pinnedAskId);
-                            this.settleVoidedSiblings(late.voidedSiblings);
+                            this.settleSameAskIdParkRoute(pinnedAskId, APPROVAL_ENDING_CAUSES.BROADCAST_LOST);
+                            this.settleVoidedSiblings(late.voidedSiblings, APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN);
                         }),
                         onWon: (res) => {
                             settleUnreachable();
-                            this.settleSameAskIdParkRoute(pinnedAskId);
-                            this.settleVoidedSiblings(res.voidedSiblings);
+                            this.settleSameAskIdParkRoute(pinnedAskId, APPROVAL_ENDING_CAUSES.BROADCAST_LOST);
+                            this.settleVoidedSiblings(res.voidedSiblings, APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN);
                         },
                         settleByIntent: settleUnreachable,
                     });
                 }
                 else if (!done) {
                     emitFailed = true;
-                    settle(false, "expired");
+                    settle({ by: "system", cause: APPROVAL_ENDING_CAUSES.BROADCAST_LOST });
                 }
             }
         })();
@@ -1836,6 +1868,7 @@ export class ToolApprovalCoordinator {
                     type: "tool_approval_complete",
                     approvalId: wireApprovalId,
                     outcome: lastOutcome,
+                    ...(lastCause !== undefined ? { cause: lastCause } : {}),
                     ...(parkRouted ? { parked: true } : {}),
                 })
                 : undefined)
@@ -1845,7 +1878,7 @@ export class ToolApprovalCoordinator {
             return this.unattendedOutcome({ arm: "emit_failed", taskId: origin.taskId, ...(origin.owner !== null ? { owner: origin.owner } : {}), toolName: req.toolName, reachability });
         if (windowRouteUnavailable)
             return shapeOutcome(settled);
-        if (!emitSettled && lastOutcome === "expired")
+        if (!emitSettled && lastOutcome === SETTLE_OUTCOME.EXPIRED)
             return this.unattendedOutcome({ arm: "emit_unsettled", taskId: origin.taskId, ...(origin.owner !== null ? { owner: origin.owner } : {}), toolName: req.toolName, reachability });
         return shapeOutcome(settled);
     }
@@ -1941,7 +1974,7 @@ export class ToolApprovalCoordinator {
             return this.notPending();
         const tomb = this.lookupParkTombstone(id);
         if (tomb === undefined || (tomb.owner !== null && tomb.owner !== principal)) {
-            return this.notPending("unknown_or_other_replica");
+            return this.notPending(NOT_PENDING_UNKNOWN_CAUSE);
         }
         return this.dispatchLateByRow(store, tomb, id, parsed, httpReq, principal);
     }
@@ -1952,13 +1985,13 @@ export class ToolApprovalCoordinator {
         }
         catch (err) {
             this.noteStoreError(err, "getAsk(respond-late)");
-            return this.notPending("unknown_or_other_replica");
+            return this.notPending(NOT_PENDING_UNKNOWN_CAUSE);
         }
         if (row === null)
-            return this.notPending("unknown_or_other_replica");
+            return this.notPending(NOT_PENDING_UNKNOWN_CAUSE);
         if (row.owner !== null && row.owner !== principal) {
             defaultLogger.warn("tool approval late decision rejected: the ask row changed owner since it parked", { askId: row.askId });
-            return this.notPending("unknown_or_other_replica");
+            return this.notPending(NOT_PENDING_UNKNOWN_CAUSE);
         }
         if (tomb.redeemed !== undefined)
             return this.replayRedeemReceipt(id, tomb, row, tomb.redeemed, parsed);
@@ -1985,11 +2018,12 @@ export class ToolApprovalCoordinator {
                 };
             }
             case "DENIED":
-                return this.notPending("denied");
-            case "VOID":
-                return this.notPending("voided");
+            case "VOID": {
+                const rowCause = causeOfAskRow(row);
+                return this.notPending(rowCause?.kind === "ending" ? rowCause.cause : undefined);
+            }
             case "STREAM_PENDING":
-                return this.notPending("unknown_or_other_replica");
+                return this.notPending(NOT_PENDING_UNKNOWN_CAUSE);
             default: {
                 const unhandled = row.state;
                 defaultLogger.error("tool approval respond hit an unknown ask state", { askId: tomb.askId, state: unhandled });
@@ -2326,7 +2360,7 @@ export class ToolApprovalCoordinator {
         if (this.pending.get(id) !== entry) {
             if (winnerRow !== undefined)
                 this.notifyExternalDecision(askId, outcomeOfDecidedRow(winnerRow));
-            const converged = decidedWon && entry.settledOutcome === (wantAllowed ? "allowed" : "denied");
+            const converged = decidedWon && entry.settledOutcome === (wantAllowed ? SETTLE_OUTCOME.ALLOWED : SETTLE_OUTCOME.DENIED);
             if (!converged) {
                 return this.notPending();
             }
@@ -2373,7 +2407,14 @@ export class ToolApprovalCoordinator {
         const allowed = parsed.value !== "deny";
         const settleArgs = opts?.settleOutcome !== undefined ? settleArgsOfDecided(opts.settleOutcome) : { allowed, updatedInput: parsed.updatedInput, settledBy: liveSettledBy(parsed.decidedBy) };
         const readRootGrant = opts?.settleOutcome === undefined || opts.settleOutcomeIsThisRequest === true ? parsed.readRootGrant : undefined;
-        entry.settle(settleArgs.allowed, settleArgs.allowed ? "allowed" : "denied", settleArgs.updatedInput, settleArgs.settledBy, settleArgs.allowed ? undefined : parsed.note, readRootGrant);
+        entry.settle({
+            by: "human",
+            allowed: settleArgs.allowed,
+            updatedInput: settleArgs.updatedInput,
+            ...(settleArgs.settledBy !== undefined ? { hostSettledBy: settleArgs.settledBy } : {}),
+            ...(!settleArgs.allowed && parsed.note !== undefined ? { denyReason: parsed.note } : {}),
+            ...(readRootGrant !== undefined ? { readRootGrant } : {}),
+        });
         const updatedInputDelivered = opts?.updatedInputDelivered ?? true;
         const noteRecorded = opts?.noteRecorded ?? false;
         return {
@@ -2456,10 +2497,18 @@ export class ToolApprovalCoordinator {
                 continue;
             if (this.editedDecisionInFlight(askId))
                 continue;
+            const rowCause = causeOfAskRow(row);
+            if (rowCause?.kind === "ending") {
+                const before = this.pendingByAskId.get(askId)?.size ?? 0;
+                this.settleVoidedSiblings([askId], rowCause.cause);
+                settled += before;
+                continue;
+            }
             const outcome = replayTerminalAskRow(row);
             if (outcome === "unavailable") {
                 const before = this.pendingByAskId.get(askId)?.size ?? 0;
-                this.settleSameAskIdParkRoute(askId);
+                const parkCause = (rowCause?.kind === "park_trigger" ? rowCause.cause : undefined) ?? (Date.now() >= row.expiresAtMs ? APPROVAL_ENDING_CAUSES.TTL_EXPIRED : APPROVAL_ENDING_CAUSES.SHUTDOWN_BEFORE_PARK);
+                this.settleSameAskIdParkRoute(askId, parkCause);
                 settled += before;
                 continue;
             }

package/dist/trace/core-keyset-guard.d.ts

@@ -47,7 +47,7 @@ type AskProjected = "toolName" | "toolCallId" | "args" | "message" | "sourceTask
 type AskExcluded = "preview" | "principal" | "riskAxes" | "boundInputHash" | "isDelegatedChild" | "hasBidiControls" | "previewWithheld" | "execCwd" | "authoredBy";
 type _GuardAsk = AssertAllKeysHandled<Exclude<keyof AskRequest, AskProjected | AskExcluded>>;
 type _GuardAskReverse = AssertAllKeysHandled<Exclude<AskProjected | AskExcluded, keyof AskRequest>>;
-type AskFrameServerMinted = "type" | "approvalId" | "argsOmitted" | "outcome" | "governanceForced" | "expiresAtMs" | "expiresInMs" | "serverNowMs" | "parked" | "inputHasBidi" | "rememberRefused";
+type AskFrameServerMinted = "type" | "approvalId" | "argsOmitted" | "outcome" | "governanceForced" | "expiresAtMs" | "expiresInMs" | "serverNowMs" | "parked" | "cause" | "inputHasBidi" | "rememberRefused";
 type _GuardAskFrame = AssertAllKeysHandled<Exclude<keyof ToolApprovalFrame, AskProjected | AskFrameServerMinted>>;
 type _GuardAskFrameReverse = AssertAllKeysHandled<Exclude<AskProjected | AskFrameServerMinted, keyof ToolApprovalFrame>>;
 type TaskEventHandled = "text_delta" | "reasoning_delta" | "tool_start" | "tool_end" | "turn_end" | "compacted" | "diagnostics" | "message_committed" | "status" | "task_notification" | "task_progress" | "steering_injected" | "workspace_changed" | "done" | "context_usage" | "compaction_outcome" | "human_input" | "wiring_manifest" | "text_end" | "tool_roster_delta" | "tool_progress" | "tool_disclosure";

package/dist/trace/project.d.ts

@@ -1,8 +1,8 @@
 /**
- * Task Trace projection (S1): the durable run event log → sema-registry's `TraceTurn[]` contract.
+ * Task Trace projection (S1): the durable run event log → web-admin's `TraceTurn[]` contract.
  *
  * The event log (src/runs.ts) is a flat per-task seq stream: reasoning / text / tool_start / tool_end /
- * turn_end / compacted / done / suspended / failed. sema-registry renders an ORDERED `blocks[]` transcript
+ * turn_end / compacted / done / suspended / failed. web-admin renders an ORDERED `blocks[]` transcript
  * (CC-style thinking↔tool interleave), grouped into turns. This is pure presentation/projection = the
  * SERVICE layer (core [R57] cross-review: do NOT push this shape into core — different consumer, different shape).
  *
@@ -1031,7 +1031,7 @@ export declare function taskSummary(run: RunRecord, latestEventType?: string): T
  *  🔴 刻意**只**认这一个键,不做成映射表:帧名归一是历史包袱的一次性偿还,不是一条可以长胖的兼容层。
  *  再有第二个名字对不齐,应当在源头修,而不是往这里加一行。 */
 export declare function normalizeRunEventType(type: string): string;
-/** Map one durable event → a sema-registry SSE trace event (contract 2.3). null = not a client event. The
+/** Map one durable event → a web-admin SSE trace event (contract 2.3). null = not a client event. The
  *  durable log is block-grained, so each block ships as one "delta" the client appends (stream mode = "delta"). */
 export declare function mapTraceEvent(type: string, seq: number, data: Record<string, unknown>): {
     event: string;