@sema-agent/core 7.16.0 → 7.17.1

package/dist/core/trace.d.ts

@@ -58,7 +58,7 @@ export type TraceEvent = {
     kind: "task.start";
     version: 1;
     taskId: string;
-    /** #499 (additive) — the ENGINE-minted identity of THIS run (`TaskResult.runId`). `taskId` is
+    /** The ENGINE-minted identity of THIS run (`TaskResult.runId`). `taskId` is
      *  `spec.taskId ?? sessionId`, so two runs of one session that declare no host task id emit two
      *  task.start frames under ONE id and a consumer pairing start↔end has no way to say which end
      *  closes which start. Present on every `task.start` (the frame is emitted after prepare, which
@@ -264,7 +264,7 @@ export type TraceEvent = {
     kind: "task.end";
     version: 1;
     taskId: string;
-    /** #499 (additive) — the run this terminal closes; pairs with the `task.start` frame's `runId`
+    /** The run this terminal closes; pairs with the `task.start` frame's `runId`
      *  (see that field for why `taskId` cannot carry the pairing, and for the ASYMMETRY: this frame
      *  is also emitted on the prepare-throw backstop, where no `task.start` exists — it still names
      *  its run, because the id is minted at prepare's first statement and prepare-time disclosures
@@ -290,7 +290,7 @@ export type TraceEvent = {
      *  loop breathes, so lateness this size means the environment starved the process (run89: an
      *  abandoned compile group froze the loop 646s; the 1200s hard abort landed 683s late). */
     timerLatenessMs?: number;
-    /** RB-20 (TB b-form): the run was stopped by the SYNCHRONOUS turn-boundary walltime
+    /** The run was stopped by the SYNCHRONOUS turn-boundary walltime
      *  backstop, not the hard-abort timer — i.e. the deadline had passed but the setTimeout leg
      *  had not fired yet (starved event loop). Pairs with `timerLatenessMs` for attribution. */
     walltimeSyncBackstop?: boolean;
@@ -308,7 +308,7 @@ export type TraceEvent = {
     model: string;
     provider?: string;
     /**
-     * RB-410 — 1-based index of the turn this provider call served, same numbering as `turn.end` and as
+     * 1-based index of the turn this provider call served, same numbering as `turn.end` and as
      * `tool.call.turn`. Lets a bridge put a `chat` span and the `execute_tool` spans of the tools that
      * call requested under one parent without re-deriving turn boundaries from event order.
      *
@@ -316,10 +316,10 @@ export type TraceEvent = {
      * is not a loop turn, so any number here would be a different measurement wearing the same name.
      */
     turn?: number;
-    /** RB-457-a: normalized prompt tokens that MISSED the cache (Anthropic-protocol `input_tokens`
+    /** Normalized prompt tokens that MISSED the cache (Anthropic-protocol `input_tokens`
      *  shape) — disjoint from `cacheRead`/`cacheWrite`. Carried the cache-inclusive total up to 2.13.x. */
     promptTokens: number;
-    /** RB-457-a: the cache-INCLUSIVE prompt total for this call (`promptTokens + cacheRead +
+    /** The cache-INCLUSIVE prompt total for this call (`promptTokens + cacheRead +
      *  cacheWrite`) — the figure `costMicroUsd` is computed from. */
     totalInputTokens: number;
     completionTokens: number;
@@ -349,7 +349,7 @@ export type TraceEvent = {
     taskId: string;
     name: string;
     /**
-     * RB-410 — the resolved call's id: the SAME value the wire's `tool_start`/`tool_end` `TaskEvent`
+     * The resolved call's id: the SAME value the wire's `tool_start`/`tool_end` `TaskEvent`
      * carries for this call. OTel GenAI names it `gen_ai.tool.call.id` on the `execute_tool` span.
      *
      * Why it matters: without it the trace face and the event face could only be paired by tool NAME
@@ -358,7 +358,7 @@ export type TraceEvent = {
      */
     toolCallId?: string;
     /**
-     * RB-410 — 1-based index of the turn this call ran in, on the same numbering `turn.end` reports
+     * 1-based index of the turn this call ran in, on the same numbering `turn.end` reports
      * (a `tool.call` is emitted BEFORE the `turn.end` that closes its turn, so the two agree without
      * look-ahead). No GenAI attribute corresponds; it is the PARENT-span correlation key a bridge
      * needs to nest an `execute_tool` span under the `chat` call that requested the tool.
@@ -427,7 +427,7 @@ export type TraceEvent = {
     ts: number;
 } | {
     /**
-     * #619 — the READ-ONLY reader cleared a shell call, so no person and no classifier was asked: the
+     * The READ-ONLY reader cleared a shell call, so no person and no classifier was asked: the
      * allow layer's second attribution channel beside `permission.persisted_rule_allowed`. `command` is
      * the FINAL command the gate judged (a policy rewrite included) — model-authored text, carried
      * verbatim as the audit fact this frame exists for (a consumer rendering it applies its own
@@ -802,12 +802,9 @@ export type TraceEvent = {
      *  = the proactive request-build pass (anchored estimate crossed the edit budget),
      *  `"refusal"` = the MC-R rejection-recovery arm (provider said input-too-long), `"blocking"`
      *  = the slice-3 guard-chain arm A (the machine's one pre-guard shot when the frontier pass
-     *  is off, `microCompact.machine: "off"`). SCOPE (X1): emitted only by the cc machine — the
-     *  `"frontier"` arm requires `microCompact.machine: "cc"` (the default since the slice-3
-     *  flip), the `"refusal"` arm requires `microCompact.clearOnRejection` (also default-on);
-     *  the legacy OPT-OUT machine clears silently exactly as pre-374 (its clears are ledger-less
-     *  and re-fire per request, so a frame there would re-count the same occurrences and break
-     *  this frame's cardinality clause). Cardinality: exactly ONE frame per firing pass — a retry
+     *  is off, `microCompact.machine: "off"`). The `"frontier"` arm requires
+     *  `microCompact.machine: "cc"` (the default), the `"refusal"` arm requires
+     *  `microCompact.clearOnRejection` (also default-on). Cardinality: exactly ONE frame per firing pass — a retry
      *  chain re-sending an already-cleared view emits none. A `"refusal"` frame also marks one
      *  attempt of the shared prompt-too-long recovery budget spent (the MC-R arm's retry rides
      *  the same per-chain account the forced-compaction arm draws on — the knob doc on

package/dist/core/untrusted-text.d.ts

@@ -394,7 +394,7 @@ export declare function defuseControlChars(text: string): string;
  * Defense-in-depth, NOT a guarantee (same posture as the rest of this module).
  */
 export declare function inlineUntrusted(text: string, maxLen?: number): string;
-/** backlog #239: the per-ENTRY ceiling inside a `ProbeCause` operand family (checkpoint-store's
+/** The per-ENTRY ceiling inside a `ProbeCause` operand family (checkpoint-store's
  *  structured probe account), sized like the descriptor's own `touchedPaths` entries (the same thing
  *  on the same card). Per entry, not per cause: that is the whole point of the structured shape —
  *  one pathological path costs only itself, where a single joined string let it consume every other

package/dist/core/wiring-manifest.d.ts

@@ -46,7 +46,8 @@ export type AskEffective = "human_reachable" | "auto_allow" | "auto_deny" | "par
  * The content-question channel, three-valued (design/173 §8.2 — a derived enum, not a bare
  * boolean): `"wired"` (a resolved `onQuestion` face exists), `"absent"` (none), or
  * `"stripped_bg_lane"` — the ENGINE deliberately stripped the spawn turn's per-request face from a
- * long-lived background/retained leg (correct design, not a configuration lie; the flag is minted
+ * leg that outlives the request: a session-scoped background/retained leg, or an agent the Workflow tool
+ * spawned (submit-and-return) — correct design, not a configuration lie; the flag is minted
  * ONLY by the engine's strip sites, pair-produced with the strip itself — never inferred from spec
  * shape).
  */
@@ -58,7 +59,7 @@ export type SeamProvenance = "spec" | "deps";
 /** Machine-readable reason codes for a park lane that is not (or not provably) effective. */
 export type ParkLaneReason = "no_checkpoint_store" | "no_durable_approval_opt_in" | "no_force_durable_gate" | "no_armed_safety_vocabulary" | "await_runtime_caps" | "await_tool_vocabulary";
 /**
- * #529 — the closed set of auto-mode ARMING outcomes a leg's manifest reports
+ * The closed set of auto-mode ARMING outcomes a leg's manifest reports
  * ({@link WiringManifest.autoMode}). Minted from the arming predicate's own three-arm read, as the
  * FIRST failing arm in predicate order:
  *  - `no_intent`      — no `TaskSpec.autoModeRequested` seat and no intent inherited on the chain /
@@ -244,7 +245,7 @@ export interface WiringManifest {
         restore: string;
     };
     /**
-     * #529 — EFFECTIVE half only, and ALWAYS present on an engine-minted effective manifest (unlike
+     * EFFECTIVE half only, and ALWAYS present on an engine-minted effective manifest (unlike
      * `modelGate`, which is present only when a trim happened: auto mode has an answer on every leg,
      * so absence here means an older mint or an external derivation, never "not applicable"). The
      * per-leg READ face of the auto-mode arming decision: `armed` ⇔ `reason === "armed"` (the

package/dist/core/workflow-journal-store.d.ts

@@ -15,7 +15,7 @@ export type WorkflowJournalEntry = {
     callKey: string;
     result?: never;
     /**
-     * #642 — the ordinal's leg is PARKED at a durable approval gate: the child's own paused `TaskResult`
+     * The ordinal's leg is PARKED at a durable approval gate: the child's own paused `TaskResult`
      * (its `terminal` carries the checkpoint token + gate, its `sessionId` the pinned session). A resume
      * reaching this ordinal with a matching call key does NOT run the call live (the parked child's
      * session is pinned under a pending checkpoint; a fresh spawn would duplicate it) — it drives the
@@ -73,7 +73,7 @@ export interface WorkflowJournalStore {
      *  line teaches only the TaskOutput route (which is always live). Engine-facing string, never parsed. */
     locator?(runId: string, scope: string): string | undefined;
     /**
-     * RB-242 (ruled 2026-07-30) — ADMISSION for a resume, so two concurrent
+     * ADMISSION for a resume, so two concurrent
      * `resumeFromRunId` legs off ONE source run cannot fork its execution.
      *
      * Why a store seam at all: the engine's own mutex is in-process only (`startWorkflow` refuses a duplicate
@@ -84,7 +84,7 @@ export interface WorkflowJournalStore {
      * shared durable layer, i.e. here.
      *
      * OPTIONAL, and absence is a first-class state: a store that does NOT implement this has NO STORE-LEVEL lease
-     * semantics. RB-367 (dual-process probe): a store without the hook is no longer completely
+     * semantics. A store without the hook is no longer completely
      * unguarded, though — `runWorkflow`'s engine falls back to a process-local admission table for exactly this
      * shape, so a same-process double `resumeFromRunId` off one source is still refused even against a store
      * that never implements this member. That fallback cannot see a SECOND process, which is the one thing a
@@ -132,7 +132,7 @@ export interface WorkflowJournalStore {
         holder?: string;
     }>;
     /**
-     * RB-242 — release the claim {@link resumeClaim} granted to `newRunId` on `(sourceRunId, scope)`.
+     * Release the claim {@link resumeClaim} granted to `newRunId` on `(sourceRunId, scope)`.
      * Called by the engine at the resuming run's TERMINAL boundary (in a `finally`, so abort/error/abandon are
      * covered), and ONLY when the matching claim was actually granted.
      *
@@ -143,7 +143,7 @@ export interface WorkflowJournalStore {
      * A throw here is swallowed by the engine — a release failure must never replace the run's real outcome, and
      * the store's TTL is the standing backstop for the row it left behind.
      *
-     * RB-355: the engine's terminal boundary now BOUNDS this call (and its wait on
+     * The engine's terminal boundary now BOUNDS this call (and its wait on
      * the {@link resumeClaim} verdict) by a timeout — a store that hangs would otherwise keep the run's `done`
      * promise pending forever, after the outcome is already decided. A release that outlives that bound is
      * treated exactly like one that throws: swallowed, with the TTL as the backstop. Implementations should not
@@ -158,7 +158,7 @@ export declare const MAX_JOURNAL_RESULT_BYTES: number;
 /** True when a serialized journal result is too large to store (UTF-8 byte length over {@link MAX_JOURNAL_RESULT_BYTES}). */
 export declare function oversizeJournalResult(serialized: string): boolean;
 export declare function callKeyOrdinal(callKey: string): number;
-/** RB-243: the errorCode a journal OVERSIZE TOMBSTONE carries — the resume path recognizes it to
+/** The errorCode a journal OVERSIZE TOMBSTONE carries — the resume path recognizes it to
  *  say WHY an ordinal never replays. `failed` + this code lands on the T2A-4 no-replay arm, so replay
  *  behavior is identical to the entry simply being absent (the pre-tombstone shape). */
 export declare const JOURNAL_OVERSIZE_ERROR_CODE = "workflow.journal_oversize";
@@ -192,7 +192,7 @@ export declare class WorkflowJournalOversizeError extends Error {
  * answer is the rule, the engine's tombstone the one place that pre-empts it.
  */
 export declare function assertJournalEntryFits(entry: WorkflowJournalEntry): void;
-/** RB-243: mint the tiny FAILED entry the ENGINE journals in place of an oversize result. The
+/** Mint the tiny FAILED entry the ENGINE journals in place of an oversize result. The
  *  tombstone is minted in the engine, NOT in a store — a store REFUSES an oversize entry
  *  ({@link assertJournalEntryFits}) and never invents one; the engine measures the durable copy first, so
  *  the store sees the tombstone, not the payload. Never copies `result.result`/`structuredOutput` (the
@@ -200,7 +200,7 @@ export declare function assertJournalEntryFits(entry: WorkflowJournalEntry): voi
  *  and the paid spend. Its own serialization is a few hundred bytes — always under the cap (pinned). */
 export declare function journalOversizeTombstone(result: TaskResult, bytes: number): TaskResult;
 /**
- * RB-367 (dual-process probe, core-side judgment) — the TTL a resume claim {@link
+ * The TTL a resume claim {@link
  * InMemoryWorkflowJournalStore} grants survives WITHOUT an engine release: the backstop for an engine that
  * abandoned a granted claim without ever reaching the terminal `finally` that releases it (a bug, not the
  * normal path — the normal path releases promptly). Same VALUE as the file store's `RESUME_CLAIM_TTL_MS`
@@ -214,7 +214,7 @@ export declare const IN_MEMORY_RESUME_CLAIM_TTL_MS: number;
  *  service's Postgres store (SVC-2). Records each run's `scope` and enforces it on load (CORE-9 audit BLOCKER:
  *  a cross-scope resumeFromRunId resolves to an empty journal — no cross-tenant disclosure).
  *
- *  RB-367: also carries a REAL {@link WorkflowJournalStore.resumeClaim}/{@link
+ *  Also carries a REAL {@link WorkflowJournalStore.resumeClaim}/{@link
  *  WorkflowJournalStore.releaseResumeClaim} implementation (this store used to be the canonical example of a
  *  store WITHOUT the seam — its own header said so). Left unimplemented, the DEFAULT deployment (no
  *  `journalStore` supplied, or this store supplied explicitly) had NO protection against two same-process
@@ -231,7 +231,7 @@ export declare class InMemoryWorkflowJournalStore implements WorkflowJournalStor
      *  collide across the boundary between the two fields. */
     private readonly resumeClaims;
     private claimsForScope;
-    /** RB-367 — contract parity with the file store: keyed by `(sourceRunId, scope)`; idempotent re-grant to the
+    /** Contract parity with the file store: keyed by `(sourceRunId, scope)`; idempotent re-grant to the
      *  SAME holder; an unexpired claim held by someone else refuses (naming the holder); an expired or absent
      *  claim is free to take. Acquisition is a single synchronous Map read-then-write with no `await` between
      *  the check and the publish — there is no window (matching the atomicity RB-354 requires of a durable
@@ -240,7 +240,7 @@ export declare class InMemoryWorkflowJournalStore implements WorkflowJournalStor
         granted: boolean;
         holder?: string;
     }>;
-    /** RB-367 — release ONLY a claim `newRunId` still holds (a missing/foreign/already-taken-over claim is a
+    /** Release ONLY a claim `newRunId` still holds (a missing/foreign/already-taken-over claim is a
      *  no-op, never an error — matches the file store's contract). */
     releaseResumeClaim(input: ResumeClaimArgs): Promise<void>;
     load(runId: string, scope: string): Promise<WorkflowJournalEntry[]>;

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -79,8 +79,9 @@ export declare function openSpoolPair(base: string): {
 };
 export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCapability, SchedulerCapability {
     cwd: string;
-    /** #644 — this adapter runs on the engine host, so the host's home IS the environment's (`ExecutionEnv.homeDir`). */
-    readonly homeDir: string;
+    /** `ExecutionEnv.homeDir` = the `HOME` the shell child receives (its `~`/`$HOME`/`${HOME}` all expand to it), read LIVE off the same `shellEnv`-over-`inheritEnv` merge each exec gets; ABSENT when the
+     *  child gets none (an allowlist that withholds it: `~` then falls back to passwd while `$HOME` is empty — two values, no single home, home-relative operands stay fail-closed). Residual: a per-exec `env.HOME` override. */
+    get homeDir(): string | undefined;
     private shellPath?;
     private shellEnv?;
     private inheritEnv;

package/dist/engine/execution-env/node-execution-env.js

@@ -1,13 +1,14 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { closeSync, constants, createReadStream, mkdtempSync, openSync, readSync, statSync, truncateSync, unlinkSync } from "node:fs";
-import { access, appendFile, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, realpath, rename, rm, unlink, writeFile, } from "node:fs/promises";
-import { homedir, tmpdir } from "node:os";
+import { access, appendFile, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rename, rm, unlink, writeFile, } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { ExecutionError, err, FileError, ok, toError, } from "../harness/types.js";
 import { killProcessTree, shutdownDebug } from "./kill-tree.js";
 import { scrubSecretEnv } from "../../core/secret-env.js";
+import { physicalPathOfAsync } from "../../core/physical-path.js";
 import { RollingTailBuffer, markTruncated, newStreamCursorState, sliceStreamIncrement, } from "../../core/exec-output-tail.js";
 import { BackgroundShellError } from "../../core/background-shell.js";
 import { SchedulerError } from "../../core/scheduler.js";
@@ -284,7 +285,9 @@ export function openSpoolPair(base) {
 }
 export class NodeExecutionEnv {
     cwd;
-    homeDir = homedir();
+    get homeDir() {
+        return getShellEnv(this.inheritEnv, this.shellEnv, undefined, () => { }).HOME;
+    }
     shellPath;
     shellEnv;
     inheritEnv;
@@ -800,7 +803,7 @@ export class NodeExecutionEnv {
                 let hop;
                 try {
                     const link = await readlink(resolved);
-                    const parentReal = await realpath(resolve(resolved, "..")).catch(() => resolve(resolved, ".."));
+                    const parentReal = await physicalPathOfAsync(resolve(resolved, "..")).catch(() => resolve(resolved, ".."));
                     hop = isAbsolute(link) ? link : resolve(parentReal, link);
                 }
                 catch {
@@ -1002,7 +1005,7 @@ export class NodeExecutionEnv {
     async canonicalPath(path) {
         const resolved = resolvePath(this.cwd, path);
         try {
-            return ok(await realpath(resolved));
+            return ok(await physicalPathOfAsync(resolved));
         }
         catch (error) {
             return err(toFileError(error, resolved));

package/dist/engine/harness/agent-harness.d.ts

@@ -6,6 +6,24 @@ import type { AbortResult, AgentHarnessEvent, AgentHarnessEventResultMap, AgentH
  *  mints (see the field docs on {@link UserMessage}). Threaded from `prompt`/`steer`/`followUp`/
  *  `nextTurn` options into the persisted message so derived views (auto-mode window, compaction
  *  serializer) work from METADATA, never from reminder-shape guessing. */
+/** Who aborted a turn seat: the bare user halt or the steer-now accelerator. A run-level abort reaches the seat
+ *  through the loop's composition listener and stamps nothing. */
+export type SeatCutSource = "halt" | "steer";
+/** Who asked the clean-stop latch to end the run: the bare user halt, or a soft stop ({@link AgentHarness.requestStopAfterTurn}). */
+export type StopRequestSource = "halt" | "soft";
+/** The harness's STATEMENT of what a run's halt (and its stop siblings) did — the result assembly reads this in
+ *  place of any inference from message shape: `haltedByUser` ⇔ `turnCut === "halt"` ∨ `"halt" ∈ boundaryStop.sources`.
+ *  Per prompt: every seat is cleared at the next `prompt()`, so a read after the prompt settled describes that run. */
+export interface HaltConsumption {
+    /** The loop's interrupt settlement consumed the cut of the LAST-published seat, stamped with its aborter. Absent: no
+     *  seat cut was consumed on the final turn (never cut / a later seat cleared it / a run abort owned the ending / no stamp). */
+    readonly turnCut?: SeatCutSource;
+    /** The first boundary consult that stopped a non-unwinding loop, with the latch's sources at that instant. */
+    readonly boundaryStop?: {
+        readonly face: "pre_turn" | "post_turn";
+        readonly sources: ReadonlyArray<StopRequestSource>;
+    };
+}
 export interface UserMessageProvenance {
     /** Exact char length of the engine-prepended prefix on `text` (first-frame reminders etc.).
      *  Sugar for the single segment `[0, chars)` — when `engineSegments` is also supplied, segments win. */
@@ -106,10 +124,19 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     readonly env: ExecutionEnv;
     private session;
     private phase;
-    /** design/74 R3-A: a one-way soft-stop flag. When set, `shouldStopAfterTurn` returns true at the next turn
-     *  boundary so the loop exits CLEANLY (emit `agent_end` + return) WITHOUT an abort/interrupt — the path a
-     *  resource-slice suspend needs (an abort would trip the orphan-[INTERRUPTED] reconcile = corrupt resume). */
-    private _stopAfterTurn;
+    /** design/74 R3-A: the one-way clean-stop latch — SET iff this set is non-empty. When set, the boundary consults
+     *  answer true so the loop exits CLEANLY (emit `agent_end` + return) WITHOUT an abort/interrupt — the path a
+     *  resource-slice suspend needs (an abort would trip the orphan-[INTERRUPTED] reconcile = corrupt resume). It is
+     *  the SET of its requesters (`halt()` adds `"halt"`, `requestStopAfterTurn()` adds `"soft"`; both may be present,
+     *  no first-writer arbitration) so the consumption record can say WHOSE stop the loop stopped for. */
+    private readonly stopRequestSources;
+    private get stopRequested();
+    private boundaryStopConsumed?;
+    /** The seat the loop published LAST — retract does not clear it, only the next publish replaces it (a fresh controller
+     *  per turn, so identity carries the generation); the loop's cut-consumption report is accepted for THIS seat only. */
+    private lastPublishedSeat?;
+    private readonly seatCutSources;
+    private turnCutConsumed?;
     /** backlog #389 — one-way latch set by {@link abort}. Read by `drainQueuedMessages`: no boundary may
      *  hand a queued frame to the model once the run is unwinding, and — crucially — none may SPLICE one
      *  out of the queue either (that would delete the terminal undrained account the abort path owes it). */
@@ -390,6 +417,22 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
         turnCut: boolean;
         accepted: boolean;
     };
+    /** The ONE seat-cut dispatch behind both verbs: stamp the aborter FIRST (a seat is never aborted twice), then abort.
+     *  A run abort fired INSIDE this dispatch (a listener on the cut signal tearing the run down) was fired BY the cut —
+     *  the loop takes the run-terminal path and never reports that settlement, so the consumption is recorded here, the
+     *  only point that can see the causation (synchronous, single-threaded). A LATER abort is the run's own ending. */
+    private cutSeat;
+    /** The harness's statement of what this run's halt (and its stop siblings) did — {@link HaltConsumption}. Readable
+     *  during the run and after `prompt()` settled (cleared by the NEXT prompt). */
+    haltConsumption(): HaltConsumption;
+    /** The ONE consult behind both boundary faces: a set latch answers true, and the FIRST true answer on a run that is
+     *  NOT unwinding is the consumption (the loop exits on it), recorded with the latch's sources at that instant. The run
+     *  signal always wins (the loop's cut arms' rule): an unwinding run ends FOR its abort — the latch's true answer is
+     *  incidental (the next turn's abort guard would have exited anyway), so the attribution is withheld, not the exit. */
+    private consultStopLatch;
+    /** The loop's report that a seat's cut settled its turn (the loop-config seam). Identity is checked against the
+     *  LAST-published seat, never the live one (the arms report around retraction); any other seat is refused loudly. */
+    private noteTurnCutConsumed;
     /**
      * design/373 §3.3 (the final-commit-point double check) — how many queued injection frames a
      * boundary drain could deliver RIGHT NOW: both lanes, minus frames the current state refuses to

package/dist/engine/harness/agent-harness.js

@@ -187,7 +187,14 @@ export class AgentHarness {
     env;
     session;
     phase = "idle";
-    _stopAfterTurn = false;
+    stopRequestSources = new Set();
+    get stopRequested() {
+        return this.stopRequestSources.size > 0;
+    }
+    boundaryStopConsumed;
+    lastPublishedSeat;
+    seatCutSources = new WeakMap();
+    turnCutConsumed;
     aborting = false;
     drainedPendingInjection = [];
     runAbortController;
@@ -586,8 +593,8 @@ export class AgentHarness {
                 ? { streamingToolExecution: true }
                 : {}),
             convertToLlm: (messages) => stripEngineMetadata(convertToLlm(messages)),
-            shouldStopAfterTurn: () => this._stopAfterTurn,
-            shouldHaltBeforeTurn: () => this._stopAfterTurn,
+            shouldStopAfterTurn: () => this.consultStopLatch("post_turn"),
+            shouldHaltBeforeTurn: () => this.consultStopLatch("pre_turn"),
             transformContext: async (messages, signal) => {
                 const result = await this.emitHook({ type: "context", messages: [...messages], ...(signal !== undefined ? { signal } : {}) });
                 if (result?.adoptSessionRebuild !== true) {
@@ -642,8 +649,13 @@ export class AgentHarness {
             },
             getSteeringMessages: async () => this.drainQueuedMessages(this.steerQueue, this.steeringQueueMode),
             publishTurnInterruptSeat: (seat) => {
+                if (seat !== undefined) {
+                    this.lastPublishedSeat = seat;
+                    this.turnCutConsumed = undefined;
+                }
                 this.turnInterruptSeat = seat;
             },
+            noteTurnCutConsumed: (seat) => this.noteTurnCutConsumed(seat),
             recheckImmediateInjections: async (pending) => this.absorbImmediateSteering(pending),
             pendingInjectionCount: () => this.pendingInjectionCount(),
             getFollowUpMessages: async () => {
@@ -875,7 +887,7 @@ export class AgentHarness {
                     return mergeTruncatedOutputChain(newMessages, i);
                 }
             }
-            if (this._stopAfterTurn)
+            if (this.stopRequested)
                 return undefined;
             throw new AgentHarnessError("invalid_state", "AgentHarness prompt completed without an assistant message");
         }
@@ -892,7 +904,10 @@ export class AgentHarness {
         if (this.phase !== "idle") {
             throw new AgentHarnessError("busy", "AgentHarness is busy");
         }
-        this._stopAfterTurn = false;
+        this.stopRequestSources.clear();
+        this.boundaryStopConsumed = undefined;
+        this.turnCutConsumed = undefined;
+        this.lastPublishedSeat = undefined;
         this.aborting = false;
         if (this.drainedPendingInjection.length > 0) {
             const stranded = this.drainedPendingInjection;
@@ -1009,7 +1024,7 @@ export class AgentHarness {
         const seat = this.turnInterruptSeat;
         if (seat === undefined || seat.signal.aborted)
             return false;
-        seat.abort();
+        this.cutSeat(seat, "steer");
         return true;
     }
     halt() {
@@ -1018,13 +1033,41 @@ export class AgentHarness {
         }
         if (this.aborting)
             return { turnCut: false, accepted: false };
-        this._stopAfterTurn = true;
+        this.stopRequestSources.add("halt");
         const seat = this.turnInterruptSeat;
         if (seat === undefined || seat.signal.aborted)
             return { turnCut: false, accepted: true };
-        seat.abort();
+        this.cutSeat(seat, "halt");
         return { turnCut: true, accepted: true };
     }
+    cutSeat(seat, source) {
+        this.seatCutSources.set(seat, source);
+        const runQuietBefore = this.runAbortController?.signal.aborted !== true;
+        seat.abort();
+        if (runQuietBefore && this.runAbortController?.signal.aborted === true)
+            this.turnCutConsumed = { source };
+    }
+    haltConsumption() {
+        const turnCut = this.turnCutConsumed?.source;
+        return {
+            ...(turnCut !== undefined ? { turnCut } : {}),
+            ...(this.boundaryStopConsumed !== undefined ? { boundaryStop: this.boundaryStopConsumed } : {}),
+        };
+    }
+    consultStopLatch(face) {
+        if (!this.stopRequested)
+            return false;
+        if (this.runAbortController?.signal.aborted !== true) {
+            this.boundaryStopConsumed ??= { face, sources: [...this.stopRequestSources] };
+        }
+        return true;
+    }
+    noteTurnCutConsumed(seat) {
+        if (seat !== this.lastPublishedSeat) {
+            throw new AgentHarnessError("invalid_state", "turn-cut consumption reported for a seat the harness did not publish last");
+        }
+        this.turnCutConsumed = { source: this.seatCutSources.get(seat) };
+    }
     pendingInjectionCount() {
         if (this.aborting)
             return 0;
@@ -1195,7 +1238,7 @@ export class AgentHarness {
         }
     }
     requestStopAfterTurn() {
-        this._stopAfterTurn = true;
+        this.stopRequestSources.add("soft");
     }
     async flushQueuedSessionWrites() {
         try {

package/dist/engine/loop/agent-loop.js

@@ -257,8 +257,9 @@ async function runTurnPhases(state, signal, turnController, publishSeat, retract
     const withholdEnabled = ptl !== undefined && (ptl.withholdErrorEvents ?? true);
     let withhold = withholdEnabled ? createPtlWithholdBuffer(emit, ptlDetect) : undefined;
     let message;
+    let cutAtFinalSettle = false;
     try {
-        message = await streamAssistantResponse(state.context, state.config, turnController.signal, withhold?.sink ?? emit, streamFn, runtime, executor, staticReasoningCutDowngrade);
+        ({ message, cutAtSettle: cutAtFinalSettle } = await streamAssistantResponse(state.context, state.config, turnController.signal, withhold?.sink ?? emit, streamFn, runtime, executor, staticReasoningCutDowngrade));
     }
     finally {
         await executor.settle();
@@ -308,7 +309,7 @@ async function runTurnPhases(state, signal, turnController, publishSeat, retract
                 trace?.({ kind: "continue", reason: "reactive_compact_retry" });
                 executor = new StreamToolExecutor(state.context, state.config, turnController.signal, emit);
                 try {
-                    message = await streamAssistantResponse(state.context, state.config, turnController.signal, withhold?.sink ?? emit, streamFn, runtime, executor, staticReasoningCutDowngrade);
+                    ({ message, cutAtSettle: cutAtFinalSettle } = await streamAssistantResponse(state.context, state.config, turnController.signal, withhold?.sink ?? emit, streamFn, runtime, executor, staticReasoningCutDowngrade));
                 }
                 finally {
                     await executor.settle();
@@ -322,9 +323,11 @@ async function runTurnPhases(state, signal, turnController, publishSeat, retract
         ptlDetect(message) &&
         isBlankFailureContent(message) &&
         executor.admittedCount === 0;
-    const interruptOwnsTurn = (message.stopReason === "aborted" || interruptedInRecovery || unrecoveredPtlFailureUnderInterrupt) &&
-        turnController.signal.aborted &&
+    const cutAtPtlLaneExit = turnController.signal.aborted;
+    const interruptOwnsTurn = ((message.stopReason === "aborted" && cutAtFinalSettle) || (unrecoveredPtlFailureUnderInterrupt && cutAtPtlLaneExit) || interruptedInRecovery) &&
         !signal?.aborted;
+    if (interruptOwnsTurn)
+        state.config.noteTurnCutConsumed?.(turnController);
     if (interruptOwnsTurn && message.stopReason === "error")
         withhold?.discard();
     await withhold?.flush();
@@ -379,8 +382,10 @@ async function runTurnPhases(state, signal, turnController, publishSeat, retract
             await closeOrphanedStreamEntry(orphan, emit);
         }
     }
+    const cutAtBatchSettle = turnController.signal.aborted;
     retractSeat();
-    if (toolCalls.length > 0 && turnController.signal.aborted && !signal?.aborted) {
+    if (toolCalls.length > 0 && cutAtBatchSettle && !signal?.aborted) {
+        state.config.noteTurnCutConsumed?.(turnController);
         return await settleInterruptedTurn(state, message, executor, toolResults, signal, emit);
     }
     await emit({ type: "turn_end", message, toolResults });
@@ -603,7 +608,7 @@ async function streamAssistantResponse(context, config, signal, emit, streamFn,
         context.messages.push(abortedBeforeDispatch);
         await emit({ type: "message_start", message: { ...abortedBeforeDispatch } });
         await emit({ type: "message_end", message: abortedBeforeDispatch });
-        return abortedBeforeDispatch;
+        return { message: abortedBeforeDispatch, cutAtSettle: true };
     }
     const response = await streamFunction(config.model, llmContext, {
         ...config,
@@ -651,6 +656,7 @@ async function streamAssistantResponse(context, config, signal, emit, streamFn,
             case "done":
             case "error": {
                 const finalMessage = await response.result();
+                const cutAtSettle = signal?.aborted === true;
                 if (executor && (finalMessage.stopReason === "error" || finalMessage.stopReason === "aborted")) {
                     mergeBackAdmittedCalls(finalMessage, executor);
                 }
@@ -664,11 +670,12 @@ async function streamAssistantResponse(context, config, signal, emit, streamFn,
                     await emit({ type: "message_start", message: { ...finalMessage } });
                 }
                 await emit({ type: "message_end", message: finalMessage });
-                return finalMessage;
+                return { message: finalMessage, cutAtSettle };
             }
         }
     }
     const finalMessage = await response.result();
+    const cutAtSettle = signal?.aborted === true;
     if (executor && (finalMessage.stopReason === "error" || finalMessage.stopReason === "aborted")) {
         mergeBackAdmittedCalls(finalMessage, executor);
     }
@@ -680,7 +687,7 @@ async function streamAssistantResponse(context, config, signal, emit, streamFn,
         await emit({ type: "message_start", message: { ...finalMessage } });
     }
     await emit({ type: "message_end", message: finalMessage });
-    return finalMessage;
+    return { message: finalMessage, cutAtSettle };
 }
 async function executeToolCalls(currentContext, assistantMessage, config, signal, emit, executor) {
     const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");

package/dist/engine/loop/types.d.ts

@@ -493,6 +493,11 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * wins: when both fire, the loop takes the run-terminal path.
      */
     publishTurnInterruptSeat?: (seat: AbortController | undefined) => void;
+    /** The loop's REPORT that the published seat's cut settled its turn (stream / batch / recovery arms), called
+     *  SYNCHRONOUSLY at the judgment point (before any settlement await, retracted or not) with the very controller
+     *  {@link publishTurnInterruptSeat} published (checked against the host's LAST-published seat). Never for a
+     *  run-level abort (the run signal wins) nor a normal ending. */
+    noteTurnCutConsumed?: (seat: AbortController) => void;
     /**
      * design/373 S1 — the pre-request re-check (the level half of the immediate-class contract):
      * called once per turn, after the interrupt seat above is published and before the provider