@sema-agent/core 7.16.0 → 7.17.1

package/dist/core/permission-rule-model.js

@@ -4,6 +4,7 @@ import { compileReadDeny } from "../tools/fs/read-deny.js";
 import { carriesShellRedirection, parseLeadingCommandName, splitShellCompoundSegments } from "../tools/fs/bash-readonly-classifier.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { pathTargetOf } from "./tool-registry.js";
+import { carriesDotSegment, isAbsoluteForFamily, isIdentityDir, isPathIdentity, isShellRootedSpellingUnmapped, isUncIdentity, pathFamilyOf, pathIdentityOf } from "../tools/fs/safety.js";
 import { readShellCommand } from "./shell-lexer.js";
 export const RULE_BEHAVIORS = ["deny", "ask", "allow"];
 const RULE_BEHAVIOR_SET = new Set(RULE_BEHAVIORS);
@@ -364,12 +365,18 @@ function baseValueOf(base, bases) {
     }
 }
 function resolvePathPattern(pattern, bases, behavior) {
-    if (pattern.startsWith("//"))
-        return { resolved: "/" + pattern.slice(2) };
+    const family = pathFamilyOf(bases);
+    const tree = bases.root ?? bases.cwd;
+    if (pattern.startsWith("//")) {
+        const abs = pathIdentityOf("/" + pattern.slice(2), family, tree);
+        return abs.ok ? { resolved: abs.identity } : { missingBase: "root" };
+    }
     const needed = ruleBasesNeeded({ match: "path", command: pattern })[0];
-    const normal = lexicalNormalAbsolutePathOf(baseValueOf(needed, bases) ?? "");
-    if (normal === undefined)
+    const baseValue = baseValueOf(needed, bases);
+    const base = baseValue !== undefined && isAbsoluteForFamily(family, baseValue) ? pathIdentityOf(baseValue, family, tree) : undefined;
+    if (base === undefined || !base.ok)
         return { missingBase: needed };
+    const normal = base.identity;
     const rest = pattern.startsWith("~/") ? pattern.slice(2) : pattern.startsWith("/") ? pattern.slice(1) : pattern.startsWith("./") ? pattern.slice(2) : pattern;
     const peeled = rest.endsWith("/**") ? rest.slice(0, -3) : rest;
     const bare = needed === "cwd" && peeled !== "" && !peeled.includes("/");
@@ -377,8 +384,8 @@ function resolvePathPattern(pattern, bases, behavior) {
     const body = anyDepth ? "**/" + peeled : rest;
     return { resolved: (normal === "/" ? "" : normal) + "/" + body };
 }
-export function isUsablePathBase(base) {
-    return base !== undefined && lexicalNormalAbsolutePathOf(base) !== undefined;
+export function isUsablePathBase(base, family) {
+    return base !== undefined && isAbsoluteForFamily(family, base) && pathIdentityOf(base, family, base).ok;
 }
 function segmentGlobMatches(glob, segment) {
     if (!glob.includes("*"))
@@ -422,15 +429,18 @@ function globSegmentsReach(globs, target) {
 }
 export function pathRuleReachOf(rule, target, bases) {
     if (rule.match === "subpath")
-        return directoryRuleAdmits(rule, target) ? REACHED : NOT_REACHED;
+        return directoryRuleAdmits(rule, target, bases) ? REACHED : NOT_REACHED;
     if (rule.match !== "path")
         return NOT_REACHED;
-    if (!isLexicalNormalAbsoluteDir(target) && target !== "/")
+    const family = pathFamilyOf(bases);
+    if (!isPathIdentity(target, family))
         return NOT_REACHED;
     const r = resolvePathPattern(rule.command, bases, rule.behavior);
     if ("missingBase" in r) {
-        return { reach: "unreadable", reason: `the rule is relative to ${PATH_RULE_BASE_LABEL[r.missingBase]} and this call supplies no absolute \`${r.missingBase}\` base to resolve it against` };
+        return { reach: "unreadable", reason: `the rule is relative to ${PATH_RULE_BASE_LABEL[r.missingBase]} and this call supplies no absolute \`${r.missingBase}\` base of this tree's family to resolve it against` };
     }
+    if (isUncIdentity(r.resolved) !== isUncIdentity(target))
+        return NOT_REACHED;
     const globs = r.resolved.split("/").filter((sg) => sg !== "");
     const segments = target.split("/").filter((sg) => sg !== "");
     return globSegmentsReach(globs, segments) ? REACHED : NOT_REACHED;
@@ -587,21 +597,9 @@ export function pathWithinRoot(path, root) {
     const base = root.endsWith("/") ? root : root + "/";
     return path.startsWith(base);
 }
-export function lexicalNormalAbsolutePathOf(path) {
-    if (typeof path !== "string" || !path.startsWith("/"))
-        return undefined;
-    const out = [];
-    for (const seg of path.split("/")) {
-        if (seg === "" || seg === ".")
-            continue;
-        if (seg === "..") {
-            if (out.length > 0)
-                out.pop();
-            continue;
-        }
-        out.push(seg);
-    }
-    return out.length === 0 ? "/" : "/" + out.join("/");
+export function lexicalNormalAbsolutePathOf(path, family, anchor) {
+    const r = pathIdentityOf(path, family, anchor);
+    return r.ok ? r.identity : undefined;
 }
 function isLexicalNormalAbsoluteDir(path) {
     if (typeof path !== "string" || !path.startsWith("/") || path.startsWith("//"))
@@ -609,14 +607,22 @@ function isLexicalNormalAbsoluteDir(path) {
     const segments = path.split("/").slice(1);
     return segments.length > 0 && segments.every((s) => s !== "" && s !== "." && s !== "..");
 }
-export function directoryRuleAdmits(rule, path) {
+export function directoryRuleAdmits(rule, path, bases) {
     if (rule.match !== "subpath")
         return false;
-    if (!isLexicalNormalAbsoluteDir(rule.command))
+    const family = pathFamilyOf(bases);
+    if (carriesDotSegment(rule.command, family))
+        return false;
+    const dir = pathIdentityOf(rule.command, family, bases.root ?? bases.cwd);
+    if (!dir.ok || !isIdentityDir(dir.identity, family))
         return false;
-    if (!isLexicalNormalAbsoluteDir(path))
+    if (!isPathIdentity(path, family) || !isIdentityDir(path, family))
         return false;
-    return pathWithinRoot(path, rule.command);
+    return pathWithinRoot(path, dir.identity);
+}
+export function directoryIdentityOf(spelling, bases) {
+    const r = pathIdentityOf(spelling, pathFamilyOf(bases), bases.root ?? bases.cwd);
+    return r.ok ? r.identity : undefined;
 }
 const CD_TARGET_REJECT_CHARS = /[*?[\]{}$`\\'"<>\n\r]/;
 function cdSegmentDirectoryOf(segment, opts) {
@@ -711,7 +717,8 @@ function resolveCdSegmentDirectories(segments, cwd) {
         const dir = cdSegmentDirectoryOf(segment, { cwd, priorCd });
         if (!priorCd && movesShellCursor(segment))
             priorCd = true;
-        return dir;
+        const bases = basesOfCwd(cwd);
+        return dir === undefined || isShellRootedSpellingUnmapped(pathFamilyOf(bases), dir) ? undefined : directoryIdentityOf(dir, bases);
     });
 }
 export function scopeCoversCwd(scope, cwd, sessionId) {
@@ -767,11 +774,14 @@ function firstEligibleDirectoryRule(rules, directory, call) {
     for (const rule of rules) {
         if (!eligiblePersisted(rule, { tool: "Read", cwd: call.cwd, sessionId: call.sessionId }, "allow"))
             continue;
-        if (directoryRuleAdmits(rule, directory))
+        if (directoryRuleAdmits(rule, directory, basesOfCwd(call.execCwd ?? call.cwd)))
             return rule;
     }
     return undefined;
 }
+function basesOfCwd(cwd) {
+    return cwd === undefined ? {} : { root: cwd };
+}
 export function adjudicatePersistedRules(rules, call) {
     for (const behavior of RULE_BEHAVIORS_BY_PRECEDENCE) {
         if (behavior === "allow") {
@@ -798,23 +808,29 @@ export function adjudicatePersistedRules(rules, call) {
 export function adjudicatePersistedPathRules(rules, call, targets, bases) {
     for (const behavior of RULE_BEHAVIORS_BY_PRECEDENCE) {
         if (behavior === "allow") {
-            if (targets.allow === undefined || call.tool !== READ_RULE_TOOL)
+            if (targets.allow?.kind !== "path" || call.tool !== READ_RULE_TOOL)
                 continue;
             for (const rule of rules) {
                 if (!eligiblePersisted(rule, call, behavior))
                     continue;
-                if (directoryRuleAdmits(rule, targets.allow))
+                if (directoryRuleAdmits(rule, targets.allow.identity, bases))
                     return { behavior, rules: [rule] };
             }
             continue;
         }
-        if (targets.tighten === undefined)
+        const tighten = targets.tighten;
+        if (tighten === undefined || tighten.kind === "refused")
             continue;
         let unreadable;
         for (const rule of rules) {
             if (!eligiblePersisted(rule, call, behavior))
                 continue;
-            const outcome = pathRuleReachOf(rule, targets.tighten, bases);
+            if (tighten.kind === "unreadable") {
+                if (rule.match === "path" || rule.match === "subpath")
+                    unreadable ??= { behavior: "ask", rules: [rule], unreadable: tighten.reason };
+                continue;
+            }
+            const outcome = pathRuleReachOf(rule, tighten.identity, bases);
             if (outcome.reach === "reached")
                 return { behavior, rules: [rule] };
             if (outcome.reach === "unreadable")
@@ -843,7 +859,7 @@ export function segmentCoverageOf(command, rules, call) {
                 proposed.some((p) => p.rule.tool === "Read"
                     ? dir !== undefined &&
                         eligibleContext({ tool: p.rule.tool, scope: p.scope }, { tool: "Read", cwd: call.cwd, sessionId: call.sessionId }) &&
-                        directoryRuleAdmits(p.rule, dir)
+                        directoryRuleAdmits(p.rule, dir, basesOfCwd(call.execCwd ?? call.cwd))
                     : eligibleContext({ tool: p.rule.tool, scope: p.scope }, call) && ruleAdmitsCommand(p.rule, segment)),
         };
     });
@@ -889,7 +905,7 @@ export function suggestRulesForCommand(command, ctx) {
         const parsed = parseRuleText(formatRuleText(directory, "subpath", READ_RULE_TOOL), "allow");
         if (!("rule" in parsed) || parsed.rule.match !== "subpath")
             return undefined;
-        if (!directoryRuleAdmits(parsed.rule, directory))
+        if (!directoryRuleAdmits(parsed.rule, directory, basesOfCwd(ctx?.execCwd ?? ctx?.cwd)))
             return undefined;
         return { kind: "directoryRead", rule: parsed.rule.rule, directory: parsed.rule.command, segment };
     };
@@ -963,7 +979,7 @@ export function suggestRulesForCommand(command, ctx) {
             if (parsedBatch.some((p) => p.tool !== "Read" && ruleAdmitsCommand(p, segment)))
                 continue;
             const dir = cdDirs[i];
-            if (dir !== undefined && parsedBatch.some((p) => directoryRuleAdmits(p, dir)))
+            if (dir !== undefined && parsedBatch.some((p) => directoryRuleAdmits(p, dir, basesOfCwd(ctx?.execCwd ?? ctx?.cwd))))
                 continue;
             const reason = carriesShellRedirection(segment) ? "redirection" : mintSegmentRule(segment) === undefined ? "no_rule_form" : "cap_overflow";
             uncoveredDetail.push({ segment, reason });

package/dist/core/permission-rules.js

@@ -2,6 +2,7 @@ import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
 import { catalogRuleFaceOf, pathTargetOf } from "./tool-registry.js";
 import { indexOfUnescaped, lastIndexOfUnescaped, parsePermissionRule } from "./permission-rule-syntax.js";
 import { PATH_RULE_BASE_LABEL, isUsablePathBase, parseRuleText, pathRuleReachOf, programRunReachOf, ruleBasesNeeded } from "./permission-rule-model.js";
+import { pathFamilyOf } from "../tools/fs/safety.js";
 import { effectivePathTargetOf } from "./effective-path-target.js";
 import { protectivePathTargetOf } from "./tool-registry.js";
 export { parsePermissionRule };
@@ -188,7 +189,7 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
                 }
                 for (const base of ruleBasesNeeded(parsedPath.rule)) {
                     const value = base === "cwd" ? (pathBases.cwd ?? pathBases.root) : pathBases[base];
-                    if (!isUsablePathBase(value)) {
+                    if (!isUsablePathBase(value, pathFamilyOf(pathBases))) {
                         bad(text, "unsupported.path_base", `"${text}" is relative to ${PATH_RULE_BASE_LABEL[base]}, and this policy was given no absolute \`pathBases.${base}\`${base === "cwd" ? " (or `root`)" : ""} to resolve it against — the rule could not be judged on any call`);
                     }
                 }
@@ -321,9 +322,13 @@ export function createPermissionRulePolicy(rules, opts) {
         let unreadable;
         for (const r of lane) {
             if (r.parsed.match === "subpath" || r.parsed.match === "path") {
-                if (target === undefined)
+                if (target === undefined || target.kind === "refused")
                     continue;
-                const outcome = pathRuleReachOf(r.parsed, target, pathBases);
+                if (target.kind === "unreadable") {
+                    unreadable ??= { rule: r, unreadable: target.reason };
+                    continue;
+                }
+                const outcome = pathRuleReachOf(r.parsed, target.identity, pathBases);
                 if (outcome.reach === "reached")
                     return { rule: r };
                 if (outcome.reach === "unreadable")

package/dist/core/physical-path.d.ts

@@ -0,0 +1,37 @@
+/**
+ * THE physical path of a path — one spelling for the whole tree.
+ *
+ * A physical path is what `realpath(3)` answers: every symlink resolved and, on a case-insensitive
+ * volume, the directory entry's ON-DISK spelling. That last half is the reason this module exists.
+ * Node has two realpaths and they disagree exactly there (measured on macOS): `realpathSync.native`
+ * and `fsPromises.realpath` are the libuv call and return the disk case, while the JS `fs.realpathSync`
+ * resolves the links but PRESERVES the caller's casing. A tree that used both minted two spellings for
+ * one directory, so a key minted on one face could not be found on the other — a memory write root
+ * spelled `…/Proj` by configuration was keyed `…/Proj` by the engine's gates and resolved to `…/proj`
+ * by the execution env's fence, and the advertised-writable-directory seat had to refuse the hole its
+ * own instruction taught.
+ *
+ * Case FOLDING is not part of a path's identity and is not done here: folding a filesystem PATH names a
+ * different directory on a case-sensitive volume. A store whose in-memory KEY must fold (see
+ * `canonicalStoreKey`) folds this answer at its own call site.
+ */
+export declare function physicalPathOf(p: string): string;
+/** The spelling the memory layout keyed by BEFORE this mint — links resolved, the caller's casing kept (the JS
+ *  `fs.realpathSync`, which differs from the native call exactly there). Migration probes only: never an identity. */
+export declare function priorCallerCasedPathOf(p: string): string;
+/** The async door onto the same rule (`fsPromises.realpath` is the libuv call `realpathSync.native`
+ *  makes). The `ExecutionEnv` faces take this one: a sync realpath against a hung network mount blocks
+ *  the event loop for the mount timeout, and every pending abort with it. */
+export declare function physicalPathOfAsync(p: string): Promise<string>;
+/**
+ * {@link physicalPathOf} for a path that need not exist yet: the deepest ancestor that resolves,
+ * canonicalized, with the missing tail rejoined — so a not-yet-created target is still judged against
+ * roots that are physical paths, and a symlinked PARENT still cannot carry a write past them (the
+ * parent is exactly what gets resolved before the tail is rejoined).
+ *
+ * Total, by construction rather than by swallowing: a path with no resolvable ancestor at all has no
+ * physical form to answer with, and the absolute lexical form is that answer. Callers that must
+ * distinguish "unresolvable" from "does not exist yet" call {@link physicalPathOf} and handle the throw
+ * beside their own contract.
+ */
+export declare function physicalPathOfExisting(p: string): string;

package/dist/core/physical-path.js

@@ -0,0 +1,30 @@
+import { realpathSync } from "node:fs";
+import { realpath } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+export function physicalPathOf(p) {
+    return realpathSync.native(p);
+}
+export function priorCallerCasedPathOf(p) {
+    return realpathSync(p);
+}
+export async function physicalPathOfAsync(p) {
+    return await realpath(p);
+}
+export function physicalPathOfExisting(p) {
+    const abs = resolve(p);
+    const missingTail = [];
+    let cur = abs;
+    for (;;) {
+        try {
+            const real = physicalPathOf(cur);
+            return missingTail.length === 0 ? real : join(real, ...[...missingTail].reverse());
+        }
+        catch {
+            const parent = dirname(cur);
+            if (parent === cur)
+                return abs;
+            missingTail.push(basename(cur));
+            cur = parent;
+        }
+    }
+}

package/dist/core/protocol-naming.d.ts

@@ -18,13 +18,13 @@ export declare const MINTED_TOOL_SEGMENT_MIN_CHARS = 16;
  * live domain key here (the refresh splice). That case is decided by
  * {@link findNamespacePrefixCollision} and refused at the mount, loudly; the mint stays total.
  *
- * RB-83 (2026-07-25, red probe): the pattern this enforces is `{1,64}`, and only the charset half was
+ * The pattern this enforces is `{1,64}`, and only the charset half was
  * enforced. Both other halves matter for the same reason the charset does — an over-long or empty segment
  * produces a name the provider rejects, which 400s the WHOLE model request, the exact failure the intake
  * gate exists to contain ("a single misconfigured server never bricks the whole task").
  */
 export declare function normalizeNameSegment(name: string): string;
-/** RB-83: force a normalized segment into `{1,max}`, keeping long names distinct via a stable digest. */
+/** Force a normalized segment into `{1,max}`, keeping long names distinct via a stable digest. */
 export declare function clampNameSegment(seg: string, max?: number): string;
 /**
  * The registered-name prefix for `peer` in `ns` — i.e. the set `name.startsWith(prefix)` that a consumer

package/dist/core/remote-env.d.ts

@@ -508,7 +508,7 @@ export declare function missingRestoreSurface(env: ExecutionEnv): readonly ("res
  * A composite type guard (structural AND capability) so a `suspendVM` call site narrowed by THIS predicate
  * gets the {@link RemoteExecutionEnv} type without a cast — `true` always implies the structural check too.
  *
- * RB-439-b: it also requires the RESTORE surface ({@link missingRestoreSurface}). A suspend is only durable
+ * It also requires the RESTORE surface ({@link missingRestoreSurface}). A suspend is only durable
  * if something can undo it; an adapter that offers `suspendVM` but no `resumeVM` used to pass this guard,
  * take a real snapshot, commit a real checkpoint — and then blow up on the resume leg with an untyped
  * TypeError. "Suspendable" now means the whole round trip, so a half-adapter is rejected at the suspend site

package/dist/core/retired-keys.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ONE presence rule for a RETIRED key on a caller-supplied bag (a deps object, an options object): the key is
+ * PRESENT iff ordinary property lookup answers a defined value — prototype and non-enumerable members included,
+ * exactly what the former direct read of the seat honored; an explicit `undefined` reads as absence, as every
+ * optional seat reads. Every retired-key door reads through here so no door grows its own idea of "present";
+ * each composes its own refusal from the answer. A table row is `{ key: replacement }` — the sentence that says
+ * what replaced the seat, quoted in the refusal.
+ */
+/** The first retired key present on `bag`, in table order, or undefined when none is. */
+export declare function retiredKeyOf(bag: object, table: Readonly<Record<string, string>>): {
+    key: string;
+    replacement: string;
+} | undefined;
+/**
+ * The deps-bag door: a retired seat still wired by a deployment is refused BY NAME (`config.deps_retired_key`)
+ * instead of vanishing silently — a seat that is silently dropped reads to the deployment as wired. `owner` is
+ * the bag's type name for the sentence (`RunnerDeps`, `RunWorkflowToolDeps`).
+ */
+export declare function assertNoRetiredKeys(bag: object, table: Readonly<Record<string, string>>, owner: string): void;

package/dist/core/retired-keys.js

@@ -0,0 +1,15 @@
+export function retiredKeyOf(bag, table) {
+    for (const [key, replacement] of Object.entries(table)) {
+        if (Reflect.get(bag, key) !== undefined)
+            return { key, replacement };
+    }
+    return undefined;
+}
+export function assertNoRetiredKeys(bag, table, owner) {
+    const hit = retiredKeyOf(bag, table);
+    if (hit === undefined)
+        return;
+    const e = new Error(`${owner}.${hit.key} is retired and is not read by this engine — ${hit.replacement}. Refused rather than ignored: a seat that is silently dropped reads to the deployment as wired.`);
+    e.code = "config.deps_retired_key";
+    throw e;
+}

package/dist/core/runner/active-skill-scope.js

@@ -1,4 +1,4 @@
-import { canonicalizeTarget } from "../../tools/fs/safety.js";
+import { canonicalizeTarget, pathFamilyOf } from "../../tools/fs/safety.js";
 import { pathTargetValue } from "../tool-registry.js";
 import { pathTargetBaseOf } from "../effective-path-target.js";
 import { PATH_WRITE_TOOLS, isWithin } from "./session-rule-policy.js";
@@ -100,7 +100,7 @@ export function createActiveSkillScopePolicy(opts) {
                             decisionReason: "safety",
                         };
                     }
-                    const canon = await canonicalizeTarget(env, path, signal, pathTargetBaseOf(declaredTarget, { root: rootPath, cwd: req.cwd }));
+                    const canon = await canonicalizeTarget(env, path, signal, pathFamilyOf({ root: rootPath, cwd: req.cwd ?? env.cwd }), pathTargetBaseOf(declaredTarget, { root: rootPath, cwd: req.cwd }));
                     if (!canon.ok) {
                         return {
                             action: "deny",
@@ -111,7 +111,7 @@ export function createActiveSkillScopePolicy(opts) {
                     for (const m of constraining) {
                         const roots = [];
                         for (const raw of m.allowPaths ?? []) {
-                            const r = await canonicalizeTarget(env, raw, signal, rootPath);
+                            const r = await canonicalizeTarget(env, raw, signal, pathFamilyOf({ root: rootPath ?? env.cwd }), rootPath);
                             if (r.ok)
                                 roots.push(r.key);
                         }

package/dist/core/runner/assemble-result.d.ts

@@ -1,5 +1,6 @@
 import type { AssistantMessage } from "../../internal/llm.js";
 import type { NestedUsage, PausedCause, TaskResult, TaskSpec, TerminalCause } from "../types.js";
+import type { HaltConsumption } from "../../internal/harness.js";
 /** Per-task usage/cost accumulator (filled across the run loop, surfaced as `TaskResult.stats`). */
 export interface Stats {
     turns: number;
@@ -134,15 +135,14 @@ export interface ResultFlags {
      *  path the terminal is `completed`, and this is what tells that completion apart from a natural
      *  one — the model did not finish; the person stopped it and the run awaits their direction). */
     haltedOnUserRejection?: boolean;
-    /** A `TaskStream.halt` (the bare user interrupt, CC Esc form) was accepted
-     *  while the run was live; echoed on `TaskResult.haltedByUser`. Pure pass-through on every
-     *  terminal (the sibling `haltedOnUserRejection` law: the fact is about the leg that ran) PLUS
-     *  one status decision it owns (slot 9.7 below): a run whose ONLY stop was this halt reads
-     *  `"completed"`, never the `!final` failure and never the aborted terminal — whether the halt
-     *  landed before the model said anything (empty result) or cut a turn whose partial text the
-     *  brain kept (that text IS the result). The person stopped the run, which is the verb working,
-     *  not a defect. A REAL abort/limit that also fired still owns the terminal above it. */
-    userHalted?: boolean;
+    /** the harness's STATEMENT of what the run's halt did (see `HaltConsumption`):
+     *  the loop's report that the halt's cut settled the final turn, and/or the boundary consult that
+     *  stopped the loop for the halt's request. This is the ONLY input to `TaskResult.haltedByUser`
+     *  (`haltConsumed`, halt-attribution.ts) and to slot 9.7 — the assembly never infers causation from the
+     *  final's shape or from the verb's acceptance. A halt that was accepted but consumed nothing (the run
+     *  ended for its own reason first) leaves this empty: the original terminal stands and the seat is
+     *  NOT signed (the settle lane mints `task.halt_unconsumed` for it). */
+    haltConsumption?: HaltConsumption;
     /** Call ids of answered-but-never-collected questions, echoed on
      *  `TaskResult.strandedHumanAnswers`. Pure pass-through; empty/absent ⇒ the field is omitted. The
      *  optional `onError` alert is NOT the disclosure — this mandatory result face is. */
@@ -298,13 +298,15 @@ export declare function terminalCauseOf(final: AssistantMessage | undefined, sta
  *   9. `abortedLive` | stopReason aborted → `"limits.max_walltime_exceeded"` | `"limits.max_turns_exceeded"` | undefined
  *       (audit A-1: hoisted ABOVE no-final — the loop exits cleanly on abort, so `final` may be a
  *       normal message or absent; a plain user interrupt carries NO errorCode — switch on `status`),
- *       EXCEPT when the aborted `final` is the bare halt's OWN cut artifact (`haltOwnsAbortedFinal`),
+ *       EXCEPT when the aborted `final` is the bare halt's OWN cut artifact (`haltOwnsAbortedFinal`: the
+ *       loop reported the halt's cut settled the final turn — never shape inference),
  *       and EXCEPT when the answer had already settled (`answerSettled`: a clean `"stop"` final, not
  *       partial) — a stop landing on the run's tail cuts no work, so the run falls through to 12
  *       (`completed`, the answer as `result`, no `limits.*` code for the axis; three axes, one law)
- *   9.7 `userHalted` + (no `final` | the halt's own aborted `final`) → status `"completed"` (a
- *       bare user halt — the verb working, not a defect; below the aborts on purpose, a real
- *       abort/limit that also fired owns the terminal and the halt rides as the pass-through seat)
+ *   9.7 halt CONSUMED (`haltConsumed(flags.haltConsumption)`) + (no `final` | the halt's own aborted
+ *       `final`) → status `"completed"` (a bare user halt — the verb working, not a defect; below the
+ *       aborts on purpose, a real abort/limit that also fired owns the terminal and the halt rides as
+ *       the pass-through seat; an accepted-but-unconsumed halt never reaches this slot)
  *  10. no `final`        → status `"failed"`
  *  11. stopReason error  → brain `[code]` prefix (or `"conflict"` from the storage-layer flag)
  *  12. else              → `"completed"`

package/dist/core/runner/assemble-result.js

@@ -1,6 +1,7 @@
 import { isDegenerateCutMessage } from "../../brain/terminal-cause.js";
 import { extractErrorCode, stripErrorCodePrefix } from "../../brain/errors.js";
 import { terminalProjection } from "./terminal-projection.js";
+import { haltConsumed } from "./halt-attribution.js";
 const SALVAGE_ELIGIBLE_TERMINALS = new Set([
     "output.degenerate",
     "limits.max_tokens_exceeded",
@@ -47,7 +48,7 @@ export function answerSettled(final, continuationCut = false) {
 export function terminalCauseOf(final, stats, flags) {
     let terminal;
     let apiFailure;
-    const haltOwnsAbortedFinal = flags.userHalted === true &&
+    const haltOwnsAbortedFinal = flags.haltConsumption?.turnCut === "halt" &&
         final?.stopReason === "aborted" &&
         !flags.abortedLive &&
         flags.abortedForTimeout !== true &&
@@ -103,7 +104,7 @@ export function terminalCauseOf(final, stats, flags) {
         const code = flags.abortedForTimeout ? "limits.max_walltime_exceeded" : flags.abortedForTurns ? "limits.max_turns_exceeded" : undefined;
         terminal = { kind: "failed", ...(code !== undefined ? { code } : {}), message: final?.errorMessage ?? (flags.abortedForTurns ? "max turns exceeded" : "run aborted") };
     }
-    else if (flags.userHalted === true && (!final || haltOwnsAbortedFinal)) {
+    else if (haltConsumed(flags.haltConsumption) && (!final || haltOwnsAbortedFinal)) {
         terminal = { kind: "completed" };
     }
     else if (!final) {
@@ -155,7 +156,7 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     const result = text;
     let salvagedOutput;
     const { terminal, apiFailure } = terminalCauseOf(final, stats, flags);
-    const { status, errorCode } = terminalProjection(terminal);
+    const { errorCode } = terminalProjection(terminal);
     if (errorCode !== undefined && SALVAGE_ELIGIBLE_TERMINALS.has(errorCode)) {
         salvagedOutput = text.trim() || undefined;
     }
@@ -164,6 +165,6 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     void _internalCompaction;
     if (flags.unpricedSpend)
         delete publicStats.costMicroUsd;
-    const stampHaltedByUser = flags.userHalted === true && status !== "suspended" && status !== "needs_review";
+    const stampHaltedByUser = haltConsumed(flags.haltConsumption);
     return { taskId, ...(flags.runId !== undefined ? { runId: flags.runId } : {}), sessionId, terminal, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, ...(apiFailure !== undefined ? { apiFailure } : {}), ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.editedFiles !== undefined && flags.editedFiles.length > 0 ? { editedFiles: flags.editedFiles } : {}), ...(flags.haltedOnUserRejection === true ? { haltedOnUserRejection: true } : {}), ...(stampHaltedByUser ? { haltedByUser: true } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: [...flags.remoteEnvFailures] } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), ...(flags.effectiveReasoning !== undefined ? { effectiveReasoning: flags.effectiveReasoning } : {}), stats: publicStats };
 }

package/dist/core/runner/compaction-call-options.d.ts

@@ -30,96 +30,32 @@ import type { Prepared } from "./contracts.js";
  */
 export declare function buildWorkingFileAttachments(spec: TaskSpec, prepared: Prepared): MaybeCompactOptions["workingFileAttachments"];
 /**
- * `MaybeCompactOptions.contextInstructionFiles`: the seat that delivers the deployment's own
- * instruction-file content (the CLAUDE.md family) to the SUMMARIZER, assembled once here and spread
- * on all three lanes. Without it the compaction boundary is the one place a long task loses the
- * standing instructions every other turn has been reading — and it loses them exactly where the
- * summary REPLACES the transcript that carried them, so the loss is durable.
+ * `MaybeCompactOptions.contextInstructionFiles`: the deployment's instruction-file content (the CLAUDE.md
+ * family) delivered to the SUMMARIZER, assembled once here and spread on all three lanes — the compaction
+ * boundary is where the summary REPLACES the transcript that carried those instructions.
  *
- * WHICH BYTES, and why the neighbours are not candidates. `Prepared.projectInstructionContent` =
- * the RAW loader text (`ProjectMemoryLoad.content`, exactly the string prepare-task feeds
- * `composeMemoryBlock(projectMem, "project")`), captured beside the existing `instructionSources`
- * capture under the SAME non-blank predicate that composes the project layer:
- *   · the assembled `memoryBlock` is NOT a candidate. It is the memory ENGINE's composed layers —
- *     bytes the model itself authored in-band this session through the memory tools — with the
- *     project layer appended at the tail. The seat's contract is host/systemPrompt tier and says in
- *     terms: never from tool output, model text, or any other in-band channel. Handing
- *     model-authored bytes an envelope whose preamble tells the summarizer they may instruct it is
- *     the laundering shape, not a purity nit. (Mechanically moot too — `memoryBlock` is a
- *     prepare-task local and never reaches `Prepared`.)
- *   · the COMPOSED project block is not it either, and this one is checkable rather than a
- *     judgement: `contextInstructionFilesSection` neutralizes the whole authority family
- *     (ENGINE_AUTHORITY_ENVELOPE_TAGS) over its payload, and `user_memory`/`scope` ARE in that
- *     family — so feeding a composed block would have the engine rewrite the tags of its own
- *     composition. Raw text in, one fence at the mint.
- *   · `prepared.instructionSources` carries path + contentHash only, by design (core never learns a
- *     file-name policy), so it cannot serve this seat at all.
- *
- * PROVENANCE, stated plainly because "the host supplies it" is the easy half of the truth. On this
- * engine the value is REPOSITORY-CONTROLLED text: the loading block one file over calls a CLAUDE.md
- * of unknown authorship untrusted in so many words, the MAIN lane's own framing tells the model it is
- * "repository-controlled DATA, not instructions to obey", and this seat hands the same bytes to the
- * summarizer with instruction standing for the summarization task. Delivery THROUGH a host callback
- * is not host AUTHORSHIP: a prior agent, or anyone who can land a commit, can write a
- * "## Compact Instructions" section, and the mint's neutralization stops tag breakout — not a
- * sentence asking for a fact to be left out of the summary that replaces the transcript.
- * Why it is nevertheless this value: the seat's own contract names this path ("hosts pass the same
- * instruction-file content their prompt assembly mounts... on the runner path"), the parity form this
- * channel exists to reach reads the user's and the project's instruction files at every boundary with
- * exactly this standing, and the two alternatives are worse for reasons above rather than better.
- * The standing is also narrower than the framing gap suggests — the section's preamble scopes it to
- * guidance about HOW to summarize and classifies the rest as background — and a deployment that does
- * not want it has two exits that need no code: do not wire the loader, or return content it vouches
- * for. Recorded as an open design candidate rather than built here, because it is a contract change
- * and not a wiring one: a SEPARATE deployment-vouched summarization-instructions seat, leaving
- * repository-derived context at data tier.
- *
- * RULING ① — BOTH summary forms, no per-form split. Fork eligibility is decided per pass INSIDE
- * maybeCompact (main-model-only, recorded-request-present, not lossy), so a call site cannot say
- * "independent form only"; the closest approximation — pass the seat only when `prepared.compModel`
- * is set, since an independent compaction model has no main prefix to fork — leaves the hole the
- * wrong way round: the configuration it does NOT cover (no compaction model) is precisely the one
- * where a fork degrades mid-pass to the independent form, which would then run WITHOUT the files.
- * Feeding both forms closes that case by construction, and the library face already handles the fork
- * half (the section rides the APPENDED instruction message, never the cached prefix, so the fork's
- * whole economic point is untouched).
- *
- * RULING ② — no new size knob. The bound is the library's own `fitContextInstructionFilesSection`
- * (independent form: cap against the compaction model's window, disclosed elision, and a complete
- * yield when not even the framing fits). Its three KNOWN LIMITS are accepted here KNOWINGLY, as the
- * pre-condition of this wiring rather than something it discovered: a token-dense payload (CJK,
- * emoji) can pass a chars-domain fit and still overflow the gateway's tokenizer; an unknown
- * `contextWindow` leaves the section unbounded (the conversation clamp declines to guess there too);
- * and the FORK form cannot fit at all — its bound is a prompt-too-long that degrades ONCE to the
- * independent form, which the engine's own note records as real but NOT total (an oversize rejection
- * the classifier cannot read as prompt-too-long returns terminally instead).
- *
- * HOW BIG THAT ACCEPTANCE ACTUALLY IS — measured, because the sentence above is easy to read more
- * comfortably than it deserves. The fitted form is NOT the default path: when a fork is eligible and
- * the model answers in its envelope, the fork IS the pass, and its section is delivered WHOLE at any
- * size. The independent form — the only one that fits — runs when there is no fork to take or the
- * fork's answer did not conform. Both facts are pinned in the REF-A2 suite (a 55 KB payload: whole on
- * the fork, elided on the independent fallback). And when a limit does bite, the failure is not a
- * quiet degradation: the section is a FIXED part of the request, the reactive retry loop may drop
- * only CONVERSATION groups, so a request the SECTION overflowed cannot converge and the boundary
- * fails — the task loses that compaction (or that prompt-too-long recovery, or its end-of-task
- * summary) rather than sending a shorter one. The exposure is what the wiring widened: this was
- * previously reachable only by hosts calling the library directly, and is now reachable by every
- * deployment that wires `loadProjectMemory` with a large instruction file and an unknown or small
- * window. Making the section participate in the retry loop is the structural answer; it is a change
- * to that loop's contract, tracked at the library face, and a runner-side knob would only move the
- * decision to a place with less information.
- *
- * WHAT IT COSTS, measured rather than rounded: every deployment that wires `loadProjectMemory` now
- * sends its instruction-file content plus EXACTLY 716 chars of framing (the preamble and the fence)
- * on EVERY summarization request, both forms, once per pass — where a real project instruction file
- * in this family runs to tens of KB, so the payload, not the framing, is the bill. The number is
- * pinned in the REF-A2 suite against the engine's own renderer, so a preamble edit shows up as a
- * changed assertion rather than as prose drifting away from the code it describes.
- * Deployments that never wired the loader pay nothing: the key is absent, not
- * `undefined`, so their requests are byte-identical to the pre-wiring shape on the independent and
- * UPDATE passes (the FORK form appends its ~860-char authority clause with or without the seat, and
- * always did).
+ * Contract:
+ *  - Bytes = `Prepared.projectInstructionContent`, the RAW loader text captured under the same non-blank
+ *    predicate that composes the project layer. Not the assembled `memoryBlock` (model-authored in-band
+ *    bytes would gain an instructing envelope), not the COMPOSED project block (`contextInstructionFilesSection`
+ *    neutralizes the whole authority family, `user_memory`/`scope` included), not `instructionSources`
+ *    (path + hash only). Raw text in, one fence at the mint.
+ *  - Provenance: REPOSITORY-CONTROLLED text delivered through a host callback — delivery is not authorship;
+ *    the mint's neutralization stops tag breakout, not a sentence asking for an omission. Two no-code exits
+ *    for a deployment that does not want it: do not wire the loader, or return vouched content. A separate
+ *    deployment-vouched summarization-instructions seat is an open design candidate, not built here.
+ *  - Both summary forms, no per-form split: fork eligibility is decided per pass inside maybeCompact, and the
+ *    form NOT covered by a `compModel`-gated split is exactly the fork that degrades mid-pass to the
+ *    independent form; the section rides the APPENDED instruction message, never the cached prefix.
+ *  - No new size knob: the bound is `fitContextInstructionFilesSection` (independent form only). Its three
+ *    known limits are accepted knowingly: a token-dense payload can pass a chars-domain fit and still overflow;
+ *    an unknown `contextWindow` leaves the section unbounded; the FORK form cannot fit and degrades ONCE. When
+ *    a limit bites the boundary FAILS (the section is a fixed request part the retry loop cannot drop) — the
+ *    task loses that compaction rather than sending a shorter one; making the section participate in the
+ *    retry loop is a library-face contract change, tracked there.
+ *  - Cost: instruction-file content + exactly 716 chars of framing on every summarization request, both
+ *    forms, once per pass (pinned in the REF-A2 suite). Deployments that never wired the loader pay nothing:
+ *    the key is ABSENT, so their requests are byte-identical to the pre-wiring shape.
  */
 export declare function contextInstructionFilesOption(prepared: Prepared): Partial<Pick<MaybeCompactOptions, "contextInstructionFiles">>;
 /**