@sema-agent/core 5.40.0 → 5.41.0

package/CHANGELOG.md

@@ -1,10 +1,61 @@
 # Changelog
 
-## 5.40.0 — 2026-08-18
+## 5.41.0 — 2026-08-18
 
-No BREAKING changes. Two behavioral narrowings disclosed below (the requestedCwd × workspace-restore
+No BREAKING changes. Three behavioral narrowings disclosed below (garbage values on the three
+tool-face seats now refuse loudly; the strict sidecar family's journal read and lock fence both
+join the fail-closed law).
+
+### Added
+
+- backlog #259 — user steers stranded at agent_end are ANNOUNCED, never silently dropped behind
+  their "queued" receipts: the terminal sweep hands ENGINE notes back for per-session redelivery,
+  but USER inputs have no redelivery semantics (a steer aimed at a finished run must not fire at
+  the next one) — their remnant counts now ride a dedicated harness sink, the `settled` frame
+  (additive `undrainedSteerCount`/`undrainedFollowUpCount`), and a new `EngineNotice` family
+  `task.user_steer_undrained`. The stranding window is a narrow race past the loop's final queue
+  check, which is exactly why it gets a loud terminal account.
+- backlog #251 — the mixed-version window of the design/186 ledger v2 is machine-detected:
+  recovering a v1-format journal over a v2 disk ledger (a shape only a pre-v2 process mints)
+  announces the old-writer-alive warning on the external-findings channel; recovery is unchanged.
+
+### Fixed
+
+- backlog #297 (ruled: narrow) — the three tool-face seats (`excludeTools` / `deferTools` /
+  `alwaysLoadTools`) get the fourth seat's value door: a garbage value (a bare string, a truthy
+  non-iterable, a non-string entry) refuses `config.tool_face_control` instead of stringifying
+  into a never-matching list, throwing an uncoded TypeError, or a falsy value silently reading as
+  absent. **Narrowing**: a deployment whose misspelled seat previously "worked" now hears it.
+- backlog #299 (ruled: fix alone) — the auto-mode classifier's action block bounds tool args at
+  48,000 chars (its own subject-level cap, deliberately above the delegation-review lanes'
+  12,000-per-field sampled payloads so their coverage notes ride through uncut): it was the one
+  unbounded string in the classifier's prompt, so a single long tool argument (a SendMessage body
+  needs nothing crafted, just length) could blow the classifier's context and trip the session
+  breaker out of auto mode.
+- backlog #307 (also filed as #256) — the journal-aware strict sidecar read joins the ENOENT-only
+  absence law: an EACCES/EIO journal read refused `ControlPlaneCorruptError` instead of silently
+  serving the pre-transaction state while a committed next state sat unreadable beside it — the
+  one fail-open left in the strict-read family. **Narrowing**: a deployment whose journal reads
+  were failing now hears it instead of silently reading stale.
+- backlog #255 — the sidecar lock's commit fence splits by family: the fail-closed LEDGER family
+  (challenge/lineage locked updates and the rebuild path) aborts on an UNPROVABLE owner
+  (absent/unreadable owner file) — "cannot disprove a steal" is not a fence; the calibration
+  family keeps its documented pre-token leniency, and a FOREIGN token aborts both as before.
+  **Narrowing**: within the ledger family only.
+- CHANGELOG erratum for 5.40.0 (recorded in that entry): the header counts THREE narrowings
+  (the defer alignment was the missing third) and the release date corrects to 08-17.
+
+## 5.40.0 — 2026-08-17
+
+No BREAKING changes. Three behavioral narrowings disclosed below (the requestedCwd × workspace-restore
 combination now refuses loudly; Grep's ripgrep leg withholds alias-spelled deny-listed paths it
-previously returned).
+previously returned; `deferMode: "auto"` never sweeps engine built-ins — a small-window deployment
+whose built-ins were previously deferred now carries their schemas inline, trading context bytes for
+the first-use activation error the sweep caused).
+
+<!-- Post-release erratum (2026-08-17, server review [4351]): the header originally said "Two
+behavioral narrowings" and dated the entry 2026-08-18 (pre-written); the defer narrowing was listed
+under Fixed but missing from this header, and the release actually shipped late on 08-17. -->
 
 ### Added
 

package/dist/core/auto-mode-prompt.js

@@ -102,5 +102,5 @@ export function renderAutoModeWindow(messages, options) {
 export function renderAutoModeAction(input) {
     const ask = input.askMessage ? `\npermission gate: ${input.askMessage}` : "";
     return (`\n## New action to classify (the agent's most recent action — evaluate THIS)\n\n` +
-        `[tool_call] ${input.req.toolName} ${JSON.stringify(input.req.args ?? {})}${ask}\n`);
+        `[tool_call] ${input.req.toolName} ${excerpt(JSON.stringify(input.req.args ?? {}), 48_000)}${ask}\n`);
 }

package/dist/core/memory-engine/file-backend.js

@@ -1166,6 +1166,17 @@ export class FileMemoryEngineBackend {
                         throw new ControlPlaneCorruptError(`transaction journal v1 ledger snapshot entry ${JSON.stringify(id)} is not a string: ${jp}`);
                     snapshotRows[id] = { rev };
                 }
+                try {
+                    const diskRaw = readControlFileOrAbsent(join(this.controlPlaneRoot, LEDGER_FILE), "committed-rev ledger");
+                    const diskParsed = diskRaw !== undefined ? JSON.parse(diskRaw) : undefined;
+                    if (diskParsed !== null && typeof diskParsed === "object" && "v" in diskParsed && diskParsed.v === LEDGER_SCHEMA_VERSION) {
+                        this.enqueueExternalItems([
+                            "memory ledger: recovering a v1-format journal over a v2 ledger — a pre-v2 process wrote AFTER this store migrated (mixed-version deployment window). Retire old readers/writers before further writes; see the v2 rollback runbook.",
+                        ]);
+                    }
+                }
+                catch {
+                }
             }
             for (const op of journal.ops) {
                 const invalid = journalOpInvalid(op, this.directoryRoot);

package/dist/core/memory-engine/layout.d.ts

@@ -248,6 +248,16 @@ export interface SidecarLockOptions {
  *  volume, revoked permission) makes mkdir fail forever while the lock dir it would stat never
  *  exists — spun this synchronous loop at full speed and never reached its own cap. */
 export declare function acquireSidecarLock(lockDir: string, opts?: SidecarLockOptions): string;
+/** 证伪式复审 L2-analog: re-verify the owner token at the COMMIT POINT — a stolen-from holder
+ *  aborts instead of writing over the stealer. A FOREIGN token always aborts (positive proof the
+ *  lock is someone else's now). What an ABSENT/UNREADABLE owner file means splits by caller family
+ *  (backlog #255): the fail-closed LEDGER family (`"strict"` — challenges/lineage via
+ *  lockedStrictUpdate) treats unprovable ownership as lost — those sidecars promise their commit
+ *  point is fenced, and "cannot disprove" is not a fence; the fail-open calibration family
+ *  (`"lenient"`, the pre-#255 shape — e.g. the scope registry, whose sidecars self-heal at the next
+ *  locked update) keeps the leniency, because its token writes are best-effort and an absent owner
+ *  file there is the documented pre-token degraded shape, not evidence of a steal. */
+export declare function assertSidecarLockOwnership(lockDir: string, token: string, what: string, mode?: "strict" | "lenient"): void;
 interface AnnouncementsRecord {
     /** How many announcements were dropped by the bounded-queue fold (disclosed at render). */
     folded: number;

package/dist/core/memory-engine/layout.js

@@ -598,12 +598,15 @@ function lockedJournaledUpdate(controlDir, fileName, mutate) {
         releaseSidecarLock(lock, token);
     }
 }
-function assertSidecarLockOwnership(lockDir, token, what) {
+export function assertSidecarLockOwnership(lockDir, token, what, mode = "lenient") {
     let held;
     try {
         held = readFileSync(join(lockDir, "owner"), "utf8");
     }
-    catch {
+    catch (err) {
+        if (mode === "strict" && err.code !== undefined) {
+            throw new ControlPlaneCorruptError(`${what}: sidecar lock ownership UNPROVABLE at commit (owner file ${err.code === "ENOENT" ? "absent" : `unreadable: ${err.code}`}) — a fail-closed ledger must not commit on a fence it cannot prove; update aborted`, { cause: err });
+        }
         return;
     }
     if (held !== token) {
@@ -897,7 +900,7 @@ function lockedStrictUpdate(controlDir, fileName, what, coerce, fn) {
         const { next, result } = fn(current);
         if (next !== undefined) {
             const data = `${JSON.stringify(next, null, 2)}\n`;
-            assertSidecarLockOwnership(lock, token, what);
+            assertSidecarLockOwnership(lock, token, what, "strict");
             atomicWriteFileSync(journal, data);
             atomicWriteFileSync(file, data);
             rmSync(journal, { force: true });
@@ -932,7 +935,10 @@ function readStrictSidecar(controlDir, fileName, what) {
     try {
         journalRaw = readFileSync(journal, "utf8");
     }
-    catch {
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw new ControlPlaneCorruptError(`control-plane journal unreadable ((${err.code ?? "io error"})) — a committed next state may exist that cannot be proven; repair the read fault rather than serving the pre-transaction state: ${journal}`, { cause: err });
+        }
         journalRaw = undefined;
     }
     if (journalRaw !== undefined) {
@@ -1421,7 +1427,7 @@ export function rebuildStrictControlPlaneLedger(controlDir, ledger, now) {
         }
         const at = now();
         const quarantinedTo = [];
-        assertSidecarLockOwnership(lock, token, what);
+        assertSidecarLockOwnership(lock, token, what, "strict");
         for (const path of [file, journal]) {
             if (!existsSync(path))
                 continue;
@@ -1439,7 +1445,7 @@ export function rebuildStrictControlPlaneLedger(controlDir, ledger, now) {
             }
             quarantinedTo.push(dest);
         }
-        assertSidecarLockOwnership(lock, token, what);
+        assertSidecarLockOwnership(lock, token, what, "strict");
         atomicWriteFileSync(file, `${JSON.stringify(empty, null, 2)}\n`);
         rmSync(journal, { force: true });
         return { ledger, quarantinedTo, at };

package/dist/core/runner/prepare-config-doors.js

@@ -87,6 +87,26 @@ export function prepareConfigDoors(input) {
     const { deps, sessions, resume, internals } = input;
     let spec = input.spec;
     assertRestoreGatedToolsValue(spec.restoreGatedTools);
+    const assertToolNameListValue = (value, seat) => {
+        if (value === undefined)
+            return;
+        if (!Array.isArray(value)) {
+            const e = new Error(`TaskSpec.${seat} must be an array of tool names or absent (got ${value === null ? "null" : typeof value}) — a garbage list must refuse loudly, never be read as "no ${seat}".`);
+            e.code = "config.tool_face_control";
+            throw e;
+        }
+        const entries = value;
+        for (const entry of entries) {
+            if (typeof entry !== "string") {
+                const e = new Error(`TaskSpec.${seat} entries must be strings (got ${entry === null ? "null" : typeof entry}).`);
+                e.code = "config.tool_face_control";
+                throw e;
+            }
+        }
+    };
+    assertToolNameListValue(spec.excludeTools, "excludeTools");
+    assertToolNameListValue(spec.deferTools, "deferTools");
+    assertToolNameListValue(spec.alwaysLoadTools, "alwaysLoadTools");
     const toolFaceSnapshot = {
         exclude: spec.excludeTools ? Object.freeze([...spec.excludeTools]) : undefined,
         defer: spec.deferTools ? Object.freeze([...spec.deferTools]) : undefined,

package/dist/core/runner/runtask.js

@@ -1,6 +1,6 @@
 import { persistedReadDenyEntryProblem } from "../../tools/fs/read-deny.js";
 import { createSafeNotifier, observeThenableRejection } from "../safe-notify.js";
-import { deliverDelegationLifecycle } from "../types.js";
+import { deliverDelegationLifecycle, deliverEngineNotice } from "../types.js";
 import { AgentHarness, DEFAULT_COMPACTION_SETTINGS, uuidv7 } from "../../internal/harness.js";
 import { snapshotActorAssertion } from "../../internal/llm.js";
 import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, F012_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, LEGACY_PENDING_STEER_INPUT_ID, MAX_STEER_INPUT_ID_CHARS, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
@@ -2068,6 +2068,14 @@ export class Runner {
             for (const p of payloads)
                 this.pendingSessionNotifications.pend(notificationSessionId, p);
         };
+        prepared.harness.onUndrainedUserInputs = (counts) => {
+            deliverEngineNotice(this.deps.onNotice, {
+                code: "task.user_steer_undrained",
+                message: `${counts.steer + counts.followUp} user input(s) accepted as "queued" were never consumed — the run ended first ` +
+                    `(${counts.steer} steer, ${counts.followUp} follow-up). They are NOT redelivered; re-send against a live run if still wanted.`,
+                detail: { steer: counts.steer, followUp: counts.followUp, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}) },
+            });
+        };
         prepared.harness.onEngineNoteConsumed = (p) => {
             const peer = p?.peer;
             if (peer !== undefined && Array.isArray(peer.hopChain))

package/dist/core/types.d.ts

@@ -4669,6 +4669,13 @@ export interface EngineNotice {
      *    value IS in force the prepare refuses with the same code as `TaskResult.errorCode` (one
      *    fact, one code, two loudness dialects); `detail: { raw }`.
      *
+     *  - `"task.user_steer_undrained"` (#259) — user steers/follow-ups whose receipts said "queued"
+     *    were still in the queues at agent_end: the run ended before any turn could drain them. They
+     *    are NOT redelivered (a steer aimed at a finished run must not fire at the next one — unlike
+     *    ENGINE notes, which pend per session); the notice is the loud half of the #257 contract's
+     *    "accepted = enqueued, not consumed" sentence; `detail: { steer, followUp, taskId? }`.
+     *    Per-run, at most once (the terminal sweep is a single site).
+     *
      *  Deliberately NOT a notice family: brain retry/reconnect liveness (a rate limit, a 5xx, a
      *  transient network failure being retried). Those are per-attempt liveness frames with their own
      *  frequency semantics and ride the wire `status` channel ({@link BrainStatus}), whose sink the

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

@@ -80,6 +80,16 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private thinkingLevel;
     /** RB-30 terminal fix — runner-set sink for engine-note payloads left undrained at agent_end. */
     onUndrainedEngineNotes?: (payloads: unknown[]) => void;
+    /** backlog #259 — USER-authored queue remnants at agent_end: steers/follow-ups whose receipts said
+     *  "queued" but that no turn will ever drain (the run ended first). The engine-note sweep above
+     *  hands ENGINE payloads back for redelivery; user inputs have no redelivery semantics (a steer
+     *  aimed at a finished run must not silently fire at the next one), so their loss is ANNOUNCED
+     *  instead — the runner surfaces it as an operator notice, closing the "accepted then silently
+     *  dropped" window the #257 contract could only document. */
+    onUndrainedUserInputs?: (counts: {
+        steer: number;
+        followUp: number;
+    }) => void;
     /** design/176 — runner-set sink fired at the CONSUMPTION boundary, once per engine-note payload,
      *  in consumption order (steer/followUp drain and the turn-open nextTurn splice — the two points
      *  where a queued frame actually enters the model's input). The runner uses it to record the
@@ -99,6 +109,13 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
      *  so a double call is a no-op. */
     recoverUndrainedEngineNotes(): void;
     private sweepUndrainedEngineNotes;
+    /** backlog #259 — what remains in the steer/follow-up queues AFTER the engine-note sweep is USER
+     *  input that was accepted ("queued") and will never be consumed: the run reached agent_end first.
+     *  User inputs have no redelivery semantics (unlike engine notes — a steer aimed at a finished run
+     *  must not fire at the next one), so the loss is ANNOUNCED, never silent. The window is a narrow
+     *  race (an injection landing after the loop's final queue check), which is exactly why it needs a
+     *  loud terminal account rather than an e2e reproduction. Returns the counts for the settled frame. */
+    private announceUndrainedUserInputs;
     private systemPrompt;
     /** S4: physical system blocks (static per leg, additive — see AgentHarnessOptions.systemBlocks). */
     private systemBlocks;

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

@@ -158,6 +158,7 @@ export class AgentHarness {
     model;
     thinkingLevel;
     onUndrainedEngineNotes;
+    onUndrainedUserInputs;
     onEngineNoteConsumed;
     recoverUndrainedEngineNotes() {
         this.sweepUndrainedEngineNotes([this.nextTurnQueue, this.steerQueue, this.followUpQueue]);
@@ -182,6 +183,17 @@ export class AgentHarness {
             }
         }
     }
+    announceUndrainedUserInputs() {
+        const counts = { steer: this.steerQueue.length, followUp: this.followUpQueue.length };
+        if ((counts.steer > 0 || counts.followUp > 0) && this.onUndrainedUserInputs) {
+            try {
+                this.onUndrainedUserInputs(counts);
+            }
+            catch {
+            }
+        }
+        return counts;
+    }
     systemPrompt;
     systemBlocks;
     streamOptions;
@@ -620,9 +632,15 @@ export class AgentHarness {
         if (event.type === "agent_end") {
             await this.flushPendingSessionWrites();
             this.sweepUndrainedEngineNotes([this.nextTurnQueue, this.steerQueue, this.followUpQueue]);
+            const undrainedUser = this.announceUndrainedUserInputs();
             this.phase = "idle";
             await this.emitAny(event, signal);
-            await this.emitOwn({ type: "settled", nextTurnCount: this.nextTurnQueue.length }, signal);
+            await this.emitOwn({
+                type: "settled",
+                nextTurnCount: this.nextTurnQueue.length,
+                ...(undrainedUser.steer > 0 ? { undrainedSteerCount: undrainedUser.steer } : {}),
+                ...(undrainedUser.followUp > 0 ? { undrainedFollowUpCount: undrainedUser.followUp } : {}),
+            }, signal);
             return;
         }
         await this.emitAny(event, signal);

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

@@ -815,6 +815,11 @@ export interface AbortEvent {
 export interface SettledEvent {
     type: "settled";
     nextTurnCount: number;
+    /** backlog #259 (additive) — USER steers accepted ("queued") but never drained before agent_end.
+     *  Present only when > 0; their loss is announced through `onUndrainedUserInputs` too. */
+    undrainedSteerCount?: number;
+    /** backlog #259 (additive) — same for the follow-up queue. */
+    undrainedFollowUpCount?: number;
 }
 export interface BeforeAgentStartEvent<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate> {
     type: "before_agent_start";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.40.0",
+  "version": "5.41.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",