@sema-agent/core 7.8.0 → 7.9.1

package/dist/core/runner/permission-rule-lanes.d.ts

@@ -9,13 +9,15 @@
  *
  * ## One read per adjudicated call
  *
- * The gate consults the org lane (`orgRules.adjudicate`) on every decision and the personal lane
- * (`persistedRules.admits`) only on a surviving ask, in that order. The org lane's read is therefore
+ * The gate consults the org lane (`orgRules.adjudicate`) and then the personal lane
+ * (`persistedRules.adjudicate`) on every decision, in that order (the personal lane's deny/ask rows must
+ * be able to tighten an allow, so it can no longer wait for a surviving ask). The org lane's read is
  * HANDED to the personal lane by `toolCallId` (taken once, then forgotten), so a governed deployment pays
  * one store query — one org-source fetch — per call, exactly as it did with two seams. An entry the
- * personal lane never claims (an allow, a deny) is evicted first-in-first-out past a small bound; an
- * evicted or never-handed entry simply costs the personal lane its own read. The handoff is a cost
- * device, not a semantic one: both lanes judge one snapshot, which is the honest shape for one decision.
+ * personal lane never claims (a call on a tool it does not speak for) is evicted first-in-first-out past
+ * a small bound; an evicted or never-handed entry simply costs the personal lane its own read. The
+ * handoff is a cost device, not a semantic one: both lanes judge one snapshot, which is the honest shape
+ * for one decision.
  *
  * ## Where the lanes do NOT go
  *
@@ -24,15 +26,13 @@
  * silence the ungated-write warning for deployments that wired no policy at all.
  */
 import type { AskRuleEvidence, ToolCallRequest } from "../tool-policy.js";
-import { persistedRuleMandateOf, type OrgGateVerdict, type PersistedRuleAnswer, type PersistedRuleHit } from "../hooks.js";
-import type { PersistedAllowRule, RuleOffer, SegmentCoverage } from "../permission-rule-model.js";
+import { persistedRuleMandateOf, type OrgGateVerdict, type PersistedRuleAnswer, type PersistedRuleHit, type PersistedRuleUnreadable } from "../hooks.js";
+import type { PersistedRule, PersistedRuleVerdict, RuleOffer, SegmentCoverage } from "../permission-rule-model.js";
 import { type OrgRuleResolution } from "../permission-rule-org.js";
 import type { PermissionRuleStoreProvider } from "../permission-rule-provider.js";
-/** The one SHELL tool the persisted-rule lane speaks for. */
+/** The one SHELL tool the persisted-rule lane's COMMAND grammar speaks for (the rule-offer face mints for
+ *  it alone). The PATH grammar's tools are derived from the catalog (`ruleToolGrammarOf`). */
 export declare const PERSISTED_RULE_TOOL = "Bash";
-/** design/382 §2.5 — the READ tool the directory-rule family speaks for (its one other admission
- *  point, the cd-segment notch, lives inside the model's own conjunction/coverage arms). */
-export declare const DIRECTORY_RULE_TOOL = "Read";
 /**
  * design/252 G-2 — the evidence an INHERITED-lane ask carries.
  *
@@ -67,28 +67,43 @@ export declare function orgRevisionEvidenceOf(resolution: OrgRuleResolution, onD
     revision?: number;
 };
 /**
- * design/252 G-2 / design/375 — project the admitting COVERAGE SET onto the gate's rule-lane answer:
- * each member's canonical text plus its own add DOTS. A single rule admitting the whole command is a
- * one-element set; a compound admitted by the per-segment conjunction is the set of covering rules in
- * segment order (the model's own reporting-order contract).
+ * design/252 G-2 / design/375 — project the model's verdict onto the gate's rule-lane answer: the
+ * behavior that spoke, and each member's canonical text plus its own add DOTS. For an allow the set is
+ * the admitting COVERAGE SET (a single rule admitting the whole command is a one-element set; a compound
+ * admitted by the per-segment conjunction is the set of covering rules in segment order — the model's
+ * own reporting-order contract); for a deny/ask it is the one reaching rule the precedence walk chose.
  *
  * `adds` on a listed rule are the LIVE adds — the store's read already dropped tombstoned dots — so
- * this is the set that actually admitted the call, which is the identity a later audit reconciles a
+ * this is the set that actually decided the call, which is the identity a later audit reconciles a
  * shadowed ask against. The sanitized display text deliberately is not one. Copied rather than
  * aliased: the evidence must not change under a store that reuses its row objects.
  */
-export declare function persistedRuleHitOf(admitting: readonly PersistedAllowRule[] | undefined): PersistedRuleHit | undefined;
+export declare function persistedRuleHitOf(verdict: PersistedRuleVerdict | undefined): PersistedRuleHit | undefined;
+/** The COMMAND arm's projection of a verdict: a call the lexer could not read against a standing deny/ask
+ *  row is the lane's UNREADABLE answer — the same fail-closed shape an unreadable store takes (a
+ *  real-approval ask no automatic lane clears), with the lexer's reason in place of the store's — never a
+ *  matched ask rule, which would let a blanket `onAsk: "allow"` clear a question nobody can answer. Every
+ *  other verdict is {@link persistedRuleHitOf}'s hit. */
+export declare function persistedRuleAnswerOf(verdict: PersistedRuleVerdict | undefined): PersistedRuleHit | PersistedRuleUnreadable | undefined;
 /**
- * design/382 §2.5-1 — the persisted-rule lane's READ arm: the call's target path in the SAME lexical
- * identity the rule family is defined over — absolute as spelled, relative resolved against the LIVE
- * tracked working directory (the very base the Read tool itself resolves against; task root when no
- * tracker moved), then normalized lexically, zero IO. One admission predicate
- * ({@link directoryRuleAdmits}), the one eligibility predicate for scope/liveness, first table-order hit
- * reported. Everything this lane does NOT do is structural: it clears ASKS only — the read fences
- * (workspace containment, the sensitive-read deny face) judge inside the tool exactly as they would with
- * no rule anywhere, and an unresolvable path is simply no admission (fail toward asking).
+ * design/382 §2.5-1, widened to every path-targeting tool — the persisted-rule lane's PATH arm: the call's
+ * target path in the SAME lexical identity the rule family is defined over, resolved by the ONE reader every
+ * fence and every tool goes through (`effectivePathTargetOf`), so the lane judges the path the tool will
+ * really open. The tool's own declaration decides which base a relative spelling takes and what an ABSENT
+ * slot means — the lane no longer guesses `liveCwd ?? root` for every tool, which was wrong for the two
+ * search tools in three separate shapes (see effective-path-target.ts). Still zero IO.
+ *
+ * TWO readings of the call's path slot, one per direction (design/388 B6/B17): the tightening arms judge
+ * the PROTECTIVE target (the object face's declaration, the catalog's for the name as the floor — reading
+ * the catalog for an undeclared same-name tool can only tighten a deny); the allow arm judges the DECLARED
+ * target (the face's OWN declaration only — a same-name tool that declares no path target is unconfirmable
+ * and no grant admits it). The precedence walk, the admission predicates and the Read-only allow are the
+ * model's (`adjudicatePersistedPathRules`). An ALLOW here clears ASKS only — the read fences (workspace
+ * containment, the sensitive-read deny face) judge inside the tool exactly as they would with no rule
+ * anywhere — and an unresolvable path is simply no verdict (fail toward asking on the allow side, no
+ * refusal on the tightening side: a rule about a path speaks about no other shape).
  */
-export declare function directoryRuleLaneAnswer(table: readonly PersistedAllowRule[], args: unknown, ctx: {
+export declare function pathRuleLaneAnswer(table: readonly PersistedRule[], req: Pick<ToolCallRequest, "toolName" | "args" | "face">, ctx: {
     root: string | undefined;
     sessionId: string | undefined;
     liveCwd: string | undefined;
@@ -97,7 +112,7 @@ export declare function directoryRuleLaneAnswer(table: readonly PersistedAllowRu
  *  a deployment without one keeps a decision path byte-identical to a build without the feature. */
 export interface PermissionRuleLanes {
     personal: {
-        admits: (req: ToolCallRequest) => Promise<PersistedRuleAnswer>;
+        adjudicate: (req: ToolCallRequest) => Promise<PersistedRuleAnswer>;
     } | undefined;
     org: {
         adjudicate: (req: ToolCallRequest) => Promise<OrgGateVerdict>;

package/dist/core/runner/permission-rule-lanes.js

@@ -1,8 +1,9 @@
 import { persistedRuleMandateOf } from "../hooks.js";
-import { directoryRuleAdmits, eligiblePersisted, findAdmittingRule, lexicalNormalAbsolutePathOf, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
+import { adjudicatePersistedPathRules, adjudicatePersistedRules, ruleToolGrammarOf, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
+import { effectivePathTargetOf } from "../effective-path-target.js";
+import { declaredPathTargetOf, protectivePathTargetOf } from "../tool-registry.js";
 import { orgRuleVerdictFor } from "../permission-rule-org.js";
 export const PERSISTED_RULE_TOOL = "Bash";
-export const DIRECTORY_RULE_TOOL = "Read";
 const HANDOFF_BOUND = 256;
 export function inheritedAskRuleEvidence(provider) {
     const org = provider?.partitions.org === true ? "not_adjudicated" : "not_wired";
@@ -19,21 +20,23 @@ export function orgRevisionEvidenceOf(resolution, onDefect) {
         `the adjudication stands, but the ask carries no revision evidence for this call`);
     return {};
 }
-export function persistedRuleHitOf(admitting) {
-    return admitting === undefined
+export function persistedRuleHitOf(verdict) {
+    return verdict === undefined
         ? undefined
-        : { rules: admitting.map((r) => ({ rule: r.rule, dots: r.adds.map((a) => ({ actor: a.dot.actor, counter: a.dot.counter })) })) };
+        : { behavior: verdict.behavior, rules: verdict.rules.map((r) => ({ rule: r.rule, dots: r.adds.map((a) => ({ actor: a.dot.actor, counter: a.dot.counter })) })) };
 }
-export function directoryRuleLaneAnswer(table, args, ctx) {
-    const filePath = args?.file_path;
-    if (typeof filePath !== "string" || filePath === "")
-        return undefined;
-    const spelled = filePath.startsWith("/") ? filePath : `${(ctx.liveCwd ?? ctx.root ?? "").replace(/\/+$/, "")}/${filePath}`;
-    const target = lexicalNormalAbsolutePathOf(spelled);
-    if (target === undefined)
+export function persistedRuleAnswerOf(verdict) {
+    if (verdict?.unreadable !== undefined)
+        return { unreadable: true, reason: verdict.unreadable };
+    return persistedRuleHitOf(verdict);
+}
+export function pathRuleLaneAnswer(table, req, ctx) {
+    const bases = { ...(ctx.root !== undefined ? { root: ctx.root } : {}), ...(ctx.liveCwd !== undefined ? { cwd: ctx.liveCwd } : {}) };
+    const tighten = effectivePathTargetOf(req, protectivePathTargetOf(req), bases);
+    const allow = effectivePathTargetOf(req, declaredPathTargetOf(req), bases);
+    if (tighten === undefined && allow === undefined)
         return undefined;
-    const hit = table.find((r) => eligiblePersisted(r, { tool: DIRECTORY_RULE_TOOL, cwd: ctx.root, sessionId: ctx.sessionId }) && directoryRuleAdmits(r, target));
-    return hit !== undefined ? persistedRuleHitOf([hit]) : undefined;
+    return persistedRuleHitOf(adjudicatePersistedPathRules(table, { tool: req.toolName, cwd: ctx.root, sessionId: ctx.sessionId }, { ...(tighten !== undefined ? { tighten } : {}), ...(allow !== undefined ? { allow } : {}) }, bases));
 }
 export function createPermissionRuleLanes(cfg) {
     const provider = cfg.provider;
@@ -103,10 +106,11 @@ export function createPermissionRuleLanes(cfg) {
         : undefined;
     const personal = provider.partitions.durable
         ? {
-            admits: async (req) => {
+            adjudicate: async (req) => {
                 if (anonymous && !cfg.localOwnerDeclared)
                     return undefined;
-                if (req.toolName !== PERSISTED_RULE_TOOL && req.toolName !== DIRECTORY_RULE_TOOL)
+                const grammar = ruleToolGrammarOf(req.toolName);
+                if (grammar === undefined)
                     return undefined;
                 let view;
                 try {
@@ -122,16 +126,16 @@ export function createPermissionRuleLanes(cfg) {
                 }
                 const table = view.rules;
                 const liveCwd = cfg.liveCwd();
-                if (req.toolName === DIRECTORY_RULE_TOOL) {
-                    return directoryRuleLaneAnswer(table, req.args, { root: cfg.root, sessionId: cfg.sessionId, liveCwd });
+                if (grammar === "path") {
+                    return pathRuleLaneAnswer(table, req, { root: cfg.root, sessionId: cfg.sessionId, liveCwd });
                 }
                 const command = req.args?.command;
                 if (typeof command !== "string")
                     return undefined;
                 const execCwd = liveCwd !== undefined ? { execCwd: liveCwd } : {};
-                const admitting = findAdmittingRule(table, { tool: req.toolName, command, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
-                if (admitting !== undefined)
-                    return persistedRuleHitOf(admitting);
+                const verdict = adjudicatePersistedRules(table, { tool: req.toolName, command, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
+                if (verdict !== undefined)
+                    return persistedRuleAnswerOf(verdict);
                 const coverage = segmentCoverageOf(command, { persisted: table }, { tool: req.toolName, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
                 return coverage !== undefined ? { segmentCoverage: coverage } : undefined;
             },

package/dist/core/runner/prepare-gate-stations.js

@@ -123,7 +123,7 @@ export function prepareGateStations(input) {
                         ...(permissionRuleLane
                             ? {
                                 persistedRules: {
-                                    admits: permissionRuleLane.admits,
+                                    adjudicate: permissionRuleLane.adjudicate,
                                     onResolved: (info) => emitTrace(deps.tracer, () => ({
                                         kind: "permission.persisted_rule_allowed",
                                         version: 2,

package/dist/core/runner/prepare-safety-scan.js

@@ -1,7 +1,7 @@
 import { NAMESPACED_NAME_SHAPES } from "../protocol-table.js";
-import { handBandEffects } from "../tool-registry.js";
+import { engineCardTypes, handBandEffects } from "../tool-registry.js";
 import { TOOL_CONTRACT_MAX_CHARS, TOOL_WIRE_NAME_MAX_CHARS } from "../tool-face.js";
-import { schemaKeyBoundProblem } from "../tool-roster.js";
+import { callerCardIdOf, offendingResultCard, schemaKeyBoundProblem } from "../tool-roster.js";
 import { toolFaceProblem } from "./tool-face-overlay.js";
 import { OFFLOAD_TOOL_NAME } from "../tool-result-store.js";
 import { PRESENT_PLAN_TOOL_NAME, ENTER_PLAN_MODE_TOOL_NAME } from "../present-plan-tool.js";
@@ -52,6 +52,12 @@ export function prepareSafetyScan(input) {
                 e.code = "config.tool_face_invalid";
                 throw e;
             }
+            const foreignCard = offendingResultCard(t.renderHints, callerCardIdOf(t), engineCardTypes());
+            if (foreignCard !== undefined) {
+                const e = new Error(`Tool "${t.name}" declares a result card outside its own namespace: ${JSON.stringify(foreignCard)} (a caller card is "${callerCardIdOf(t)}/<card>"; engine cards and other contracts' namespaces are reserved).`);
+                e.code = "config.tool_face_invalid";
+                throw e;
+            }
         }
         if (t.name.includes("__")) {
             const e = new Error(`Tool name "${t.name}" is invalid: "__" is reserved for the engine's protocol tool namespaces (${NAMESPACED_NAME_SHAPES}) and must not appear in a caller tool name.`);

package/dist/core/runner/prepare-task.js

@@ -686,7 +686,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const preparedHolder = {};
         const { cacheBreakDetector, cacheFingerprint, promptOverheadTokens, readTaskFile, normalizeAttachmentPath, isDedupStubResult, recentlyReadFiles, onCompactionApplied, detectExternalChanges, listBackgroundTasks, centerCompactionCandidate, effectiveReadFaceObserved, effectiveReadDenyObserved } = prepareTurnWiring({ deps, systemPromptSeat, harnessTools, fpRef, model, epochArtifactDigestForSnapshot, promptProfile, fableMitigations, systemBlocks, thinking, spec, sessionId, turnSnapshotRef, promptManifest, charsPerToken, handsEnabled, executionEnv, attachmentRootCanonical, additionalRootsCanonical, additionalReadRootsCanonical, readDenyMatcher, resolvedReadFace, handsCwdRef, readFileStateForCheckpoint, denyNarrowingPolicy, abortController, hostTaskId, taskScope, buildAssembleInputs, centerAdoptionRef, harnessRef, epochDeclaredSections, carrierReadFace, readDenyAdditionsNormalized, preparedHolder });
         await onceLedger.settle(session, announcedListingsRef);
-        const buildPrepared = () => ({ harness, session, sessionId, runId, reminderMark, reminderDisclosureCounts, editedFilesSnapshot, taskRootPath: taskRootFinal, model, thinking, compModel: effectiveCompModel, mcp, ...(a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, gateOutcomes, batchHaltRef, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(fileHistoryBoundary !== undefined ? { fileHistoryBoundary } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), effectiveMemoryScopes: memoryEffectiveScopes, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), ...(sealReadStateSeat !== undefined ? { sealReadStateSeat } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, pausedRef, suspendProgressRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, gateStopRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolRoster, toolRosterDeltas: rosterSeat, structuredProjector, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, microCompact, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, stopRequestedRef, announcedSnapshotRecovered: onceLedger.recovered, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(projectInstructionContent !== undefined ? { projectInstructionContent } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, gitStatusRef, listBackgroundTasks, hookIdentity, hookTimeoutMs, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, runId, reminderMark, reminderDisclosureCounts, editedFilesSnapshot, taskRootPath: taskRootFinal, model, thinking, compModel: effectiveCompModel, mcp, ...(a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, gateOutcomes, batchHaltRef, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(fileHistoryBoundary !== undefined ? { fileHistoryBoundary } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), effectiveMemoryScopes: memoryEffectiveScopes, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), ...(sealReadStateSeat !== undefined ? { sealReadStateSeat } : {}), denyNarrowingPolicy, ...(permissionRuleLane !== undefined ? { persistedRuleLane: permissionRuleLane } : {}), ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, pausedRef, suspendProgressRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, gateStopRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolRoster, toolRosterDeltas: rosterSeat, structuredProjector, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, microCompact, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, stopRequestedRef, announcedSnapshotRecovered: onceLedger.recovered, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(projectInstructionContent !== undefined ? { projectInstructionContent } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, gitStatusRef, listBackgroundTasks, hookIdentity, hookTimeoutMs, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         rollback.commit();
         const prepared = buildPrepared();
         preparedHolder.current = prepared;

package/dist/core/runner/resume-admission.d.ts

@@ -0,0 +1,53 @@
+/**
+ * design/393 S3 — the resume ladder's ADMISSION rung (E1) and the wake's shaping (E2), verbatim from
+ * `Runner.resumeStream`: the outcome container's domain, the one-read snapshots of the caller's config and
+ * the trusted internals bag, the store resolution, the row read and its terminal-status confirm, the
+ * same-process parent-constraint re-supply, then the wake pre-ladder (gate purity, pendingAction purity,
+ * the message's persist-time validation) and the one read of the outcome discriminant and the signal slot.
+ *
+ * Async (two store reads); every refusal throws a typed `CheckpointError` pre-CAS. It ends by handing what it
+ * admitted to the rung after it (`next`) in its LAST continuation — no suspension point between the
+ * registry read and the wake pre-ladder's first read of the row — and returns what that rung returns.
+ * The same seat shape the tool gate's fold uses to enter its lanes (gate-fold.ts `afterFold`).
+ */
+import { type Checkpoint, type CheckpointStore, type CheckpointToken, type PendingSteerEntry, type ResumeOutcome } from "../checkpoint-store.js";
+import type { InheritedGate, ResumeTaskConfig, RunInternals, RunnerDepsSeat } from "./contracts.js";
+/** What the admission rung was called with. */
+export interface ResumeAdmissionInput<R> {
+    /** borrowed-readonly — the checkpoint token the caller is redeeming. */
+    token: CheckpointToken;
+    /** borrowed-readonly — the caller's outcome object, read exactly where the driver read it (the container test,
+     *  the discriminant once, the wake message once); never stored, never handed on as itself. */
+    outcome: ResumeOutcome;
+    /** borrowed-readonly — the caller's config bag; snapshotted ONCE here (own enumerable fields), the snapshot is what
+     *  every later rung and the resumed leg read. */
+    taskConfig: ResumeTaskConfig;
+    /** borrowed-readonly — the trusted run-internals bag as the caller supplied it; shallow-snapshotted here, the
+     *  snapshot (with the parked chain re-supplied when the registry holds it) is what the ladder reads. */
+    internals: RunInternals | undefined;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE through the Runner (the store resolution reads `checkpointStore`); the one home of why it is a
+     *  seat and not a captured object is {@link RunnerDepsSeat}. */
+    runner: RunnerDepsSeat;
+    /** borrowed-readonly — the Runner's same-process parked-constraint registry; read for this token (never written here). */
+    parentConstraintRegistry: ReadonlyMap<CheckpointToken, NonNullable<InheritedGate["parentConstraints"]>>;
+    /** borrowed-readonly — the rung after admission, entered in this rung's last continuation with what it admitted. */
+    next: (admitted: ResumeAdmissionResult) => Promise<R>;
+}
+/** What admission established — the constants every later rung reads. */
+export interface ResumeAdmissionResult {
+    /** The caller's config, snapshotted once (own enumerable fields). */
+    config: ResumeTaskConfig;
+    /** The trusted internals snapshot, with the parked parent chain re-supplied when this Runner spawned the leg. */
+    internals: RunInternals | undefined;
+    /** The checkpoint store the row lives in. */
+    store: CheckpointStore;
+    /** The pending row, read once; a non-pending snapshot was refused before this result existed. */
+    cp: Checkpoint;
+    /** The ONE read of the outcome's discriminant. */
+    outcomeGate: ResumeOutcome["gate"];
+    /** The ONE read of the config's signal slot (`.aborted` stays a live read on this object). */
+    resumeSignal: AbortSignal | undefined;
+    /** The validated wake message (wake outcomes that carried one), never the caller's object. */
+    wakeMessage: Omit<PendingSteerEntry, "seq"> | undefined;
+}
+export declare function resumeAdmission<R>(input: ResumeAdmissionInput<R>): Promise<R>;

package/dist/core/runner/resume-admission.js

@@ -0,0 +1,83 @@
+import { CheckpointError, readPendingSteerQueue, resolveCheckpointStore, validatePendingSteer } from "../checkpoint-store.js";
+import { describeSuppliedValue } from "./decide-continuation.js";
+export async function resumeAdmission(input) {
+    const { token, outcome, taskConfig, runner, parentConstraintRegistry } = input;
+    let internals = input.internals;
+    if (outcome === null || typeof outcome !== "object") {
+        throw new CheckpointError("checkpoint.invalid_outcome", `resume outcome must be an object naming its gate (got ${outcome === null ? "null" : typeof outcome})`);
+    }
+    const config = typeof taskConfig === "object" && taskConfig !== null ? { ...taskConfig } : taskConfig;
+    internals = internals !== undefined ? { ...internals } : undefined;
+    const store = resolveCheckpointStore(config, runner.deps);
+    if (!store) {
+        throw new CheckpointError("checkpoint.not_found", "no CheckpointStore wired — cannot resume (set RunnerDeps.checkpointStore or taskConfig.checkpointStore)");
+    }
+    let cp = await store.get(token);
+    if (!cp) {
+        throw new CheckpointError("checkpoint.not_found", "no checkpoint found for the supplied token");
+    }
+    if (cp.status !== "pending") {
+        const live = await store.get(token);
+        if (live?.status === "pending") {
+            throw new CheckpointError("checkpoint.reopened_concurrently", "checkpoint changed concurrently (a resolve/reopen cycle landed between this resume's read of the row and its state check) — nothing was validated or executed; re-resume against the current state");
+        }
+        throw new CheckpointError("checkpoint.already_resolved", `checkpoint is ${describeSuppliedValue(live?.status ?? cp.status)} — the token is consumed, so this resume was neither validated nor executed (idempotent); a different outcome cannot redeem it`);
+    }
+    if ((internals?.inheritedGate?.parentConstraints?.length ?? 0) === 0) {
+        const parked = parentConstraintRegistry.get(token);
+        if (parked !== undefined) {
+            internals = {
+                ...(internals ?? {}),
+                inheritedGate: { ...(internals?.inheritedGate ?? {}), parentConstraints: parked },
+            };
+        }
+    }
+    let wakeMessage;
+    const outcomeGate = outcome.gate;
+    const resumeSignal = config.signal;
+    let suppliedMessage;
+    if (outcomeGate === "wake") {
+        suppliedMessage = outcome.message;
+        const gk = cp.gate.kind;
+        const decideEntry = gk === "human" || gk === "irreversible_ask"
+            ? 'a `policy_ask` outcome (decision allow/deny bound to the pending tool call)'
+            : gk === "needs_review"
+                ? 'a `dry_run_review` outcome (decision approve/reject)'
+                : gk === "plan_review"
+                    ? 'a `plan_review` outcome (decision approve/edit/reject)'
+                    : gk === "resource_limit"
+                        ? 'a `resource_limit` outcome (decision "continue")'
+                        : undefined;
+        if (gk !== "task_done") {
+            throw new CheckpointError("wake.gate_pending", `cannot wake: this checkpoint awaits a pending gate decision (gate "${gk}") — wake is not a decision ` +
+                `channel; resume it with ${decideEntry ?? "its own gate outcome"} instead`);
+        }
+        const pa = cp.pendingAction;
+        switch (pa.kind) {
+            case "task_done":
+                break;
+            case "tool_approval":
+            case "resource_limit":
+            case "review":
+            case "plan_review": {
+                throw new CheckpointError("wake.gate_pending", `cannot wake: this checkpoint still carries a pending gate-typed action (pendingAction "${pa.kind}" ` +
+                    `on a "${gk}" gate — inconsistent row) — wake is not a decision channel; resolve it through its ` +
+                    `own decide entry instead`);
+            }
+            default: {
+                const _exhaustive = pa;
+                void _exhaustive;
+                throw new CheckpointError("wake.gate_pending", `cannot wake: this checkpoint carries an unrecognized pendingAction kind "${pa.kind}" ` +
+                    `(newer-version row?) — fail-closed: wake only serves a pure park (pendingAction "task_done")`);
+            }
+        }
+        if (suppliedMessage !== undefined) {
+            wakeMessage = validatePendingSteer(suppliedMessage);
+        }
+        else if (readPendingSteerQueue(cp.state).length === 0) {
+            throw new CheckpointError("wake.nothing_to_deliver", "cannot wake: no message was supplied and the checkpoint holds no parked pendingSteer — an empty " +
+                "wake would burn the checkpoint on a blank continuation; supply `message` or park a steer first");
+        }
+    }
+    return await input.next({ config, internals, store, cp, outcomeGate, resumeSignal, wakeMessage });
+}

package/dist/core/runner/resume-apply.d.ts

@@ -0,0 +1,50 @@
+import { type Checkpoint, type PendingSteerEntry, type ResumeOutcome } from "../checkpoint-store.js";
+import type { ResumeRun, ResumeTaskConfig, RunInternals, RunnerDepsSeat } from "./contracts.js";
+export interface ResumeApplyInput<R> {
+    /** borrowed-readonly — the pending row (session id, pending call, inherited chain, ledger, hands cwd). */
+    cp: Checkpoint;
+    /** borrowed-readonly — the config snapshot (`hooks`, `taskId`, `signal`, the policy seats). */
+    config: ResumeTaskConfig;
+    /** borrowed-readonly — the internals snapshot (delegation identity facts for the screen's envelope). */
+    internals: RunInternals | undefined;
+    /** borrowed-readonly — the ONE read of the outcome discriminant. */
+    outcomeGate: ResumeOutcome["gate"];
+    /** borrowed-readonly — the validated wake message the screen judges. */
+    wakeMessage: Omit<PendingSteerEntry, "seq"> | undefined;
+    /** borrowed-readonly — the ONE signal read from admission; the screen and the edit legs are bounded by it. */
+    resumeSignal: AbortSignal | undefined;
+    /** borrowed-readonly — the window verdict to re-assert after the screen's await (undefined when unarmed). */
+    recheckGovernanceWindow: (() => Promise<void>) | undefined;
+    /** borrowed-readonly — the approval lane's twin (its edit is what the rechecks judge; the settlement is minted onto a copy). */
+    plainPolicyOutcome: Extract<ResumeOutcome, {
+        gate: "policy_ask";
+    }> | undefined;
+    /** borrowed-readonly — the review lane's twin. */
+    plainReviewOutcome: Extract<ResumeOutcome, {
+        gate: "plan_review" | "dry_run_review";
+    }> | undefined;
+    /** borrowed-readonly — the tool-less park lanes' twin. */
+    plainParkOutcome: Extract<ResumeOutcome, {
+        gate: "wake" | "resource_limit";
+    }> | undefined;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE through the Runner (reads `hooks`, `onError`, `lockedConfig`, `basePolicyForResumeEdit`, `toolPolicy` — the last three AFTER this rung's awaits); the one home of why it is a
+     *  seat and not a captured object is {@link RunnerDepsSeat}. */
+    runner: RunnerDepsSeat;
+    /** borrowed-readonly — the orchestrator's delegation-facts fold (a lane may not name the orchestrator; the driver hands it in). */
+    effectiveDelegationFacts: (internals: Pick<RunInternals, "isDelegatedChild" | "insideFork"> | undefined, seedIsDelegatedChild: boolean | undefined) => {
+        isDelegatedChild: boolean;
+    };
+    /** borrowed-readonly — the rung after apply, entered in this rung's last continuation. */
+    next: (applied: ResumeApplyResult) => Promise<R>;
+}
+export interface ResumeApplyResult {
+    /** The screen's `additionalContext` for the wake message, when a screen ran and supplied one. */
+    wakeHookContext: string | undefined;
+    /** The approval lane's twin WITH its minted settlement record (undefined on every other lane). */
+    plainPolicyOutcome: Extract<ResumeOutcome, {
+        gate: "policy_ask";
+    }> | undefined;
+    /** The twin the store persists and the resumed leg reads — exactly one lane captured it. */
+    outcomeForStore: ResumeRun["outcome"];
+}
+export declare function resumeApply<R>(input: ResumeApplyInput<R>): Promise<R>;