@sema-agent/core 7.48.0 → 7.49.0

package/dist/stores/file/index.js

@@ -13,7 +13,6 @@ import { FileUsageWindowStore } from "./usage-window-store.js";
 import { FileBackgroundAgentStore } from "./background-agent-store.js";
 import { FileMailboxStore } from "./mailbox-store.js";
 import { FileRosterStore } from "../../agents/roster-store.js";
-import { FileStrategyStore } from "./strategy-store.js";
 import { FileFileHistoryStore } from "./file-history-store.js";
 export { FileCheckpointStore } from "./checkpoint-store.js";
 export { FileMemoryStore } from "./memory-store.js";
@@ -23,7 +22,6 @@ export { FileSessionPolicyStore } from "./session-policy-store.js";
 export { FileFileHistoryStore } from "./file-history-store.js";
 export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "./workflow-journal-store.js";
 export { FileUsageWindowStore } from "./usage-window-store.js";
-export { FileStrategyStore } from "./strategy-store.js";
 export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
 export { FileStoreLockError } from "./fs-atomic.js";
 export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
@@ -41,7 +39,6 @@ export class FileStorageBackend {
     usageWindowStore;
     backgroundAgentStore;
     mailboxStore;
-    strategyStore;
     rosterStore;
     fileHistoryStore;
     consolidationLock;
@@ -84,15 +81,6 @@ export class FileStorageBackend {
             built.push(() => this.fileMailbox.close());
             this.mailboxStore = this.fileMailbox;
             this.rosterStore = new FileRosterStore(join(this.root, "roster.json"), corruptRead ?? {});
-            const strategiesRoot = join(this.root, "strategies");
-            this.strategyStore = new FileStrategyStore({
-                root: strategiesRoot,
-                ...(opts.onCorruptRead !== undefined
-                    ? {
-                        onIncident: (i) => opts.onCorruptRead?.({ kind: "file", path: i.path ?? strategiesRoot, reason: `strategy ${i.op}: ${i.error}` }),
-                    }
-                    : {}),
-            });
             this.fileHistoryStore = new FileFileHistoryStore(this.root, { ...(opts.fileHistory ?? {}), ...(corruptRead ?? {}) });
             this.consolidationLock = createFileConsolidationLock(join(this.root, "consolidation-locks"));
         }

package/dist/stores/file/session-store.d.ts

@@ -72,6 +72,9 @@ export declare class FileSessionRepo implements SessionRepo {
         olderThanMs?: number;
         scope?: string;
     }): Promise<PlacedSessionRow[]>;
+    /** The row as it stands before a file-replacing write: `undefined` ⇔ there is no row (no file); a row
+     *  whose header cannot be read answers an empty header (it exists, its cells are unknown). */
+    private priorHeader;
     /** Cheap placement probe for one id (the TtlSessionStore's cold-cache release consults it so the
      *  placed real-deletion obligation holds after a restart). `undefined` = missing file OR unplaced. */
     placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;

package/dist/stores/file/session-store.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { BaseSessionStorage, StoredSession, SessionError, getEntriesToFork, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
+import { BaseSessionStorage, StoredSession, SessionError, assertForkTarget, forkRowCells, getEntriesToFork, incarnationCell, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
 import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizePathComponent } from "./fs-atomic.js";
 import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
@@ -102,10 +102,25 @@ export class FileSessionRepo {
         if (meta === undefined) {
             throw new SessionError("corrupt_session", `Session ${id} is unreadable: its log has no meta header (${tally?.dropped ?? 0} of ${tally?.total ?? lines.length} records skipped as corrupt)`);
         }
-        const { createdAt, forkedFrom, placement } = meta;
-        return { createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}), ...(placement !== undefined ? { placement } : {}), entries };
+        const { createdAt, forkedFrom, placement, incarnation, forkedFromIncarnation } = meta;
+        for (const [key, token] of [["incarnation", incarnation], ["forkedFromIncarnation", forkedFromIncarnation]]) {
+            if (token !== undefined && typeof token !== "string")
+                this.disclose(path, `session header carries a non-string ${key} (${typeof token}) — read as an UNKNOWN occupant`, id);
+        }
+        return {
+            meta: {
+                id,
+                createdAt,
+                ...(forkedFrom !== undefined ? { forkedFrom } : {}),
+                ...(placement !== undefined ? { placement } : {}),
+                ...(typeof incarnation === "string" ? { incarnation } : {}),
+                ...(typeof forkedFromIncarnation === "string" ? { forkedFromIncarnation } : {}),
+            },
+            entries,
+        };
     }
-    storage(id, createdAt, entries, forkedFrom, placement) {
+    storage(meta, entries) {
+        const { id } = meta;
         const canonical = canonicalStoreKey(this.pathFor(id));
         const live = sharedSessionStorages.get(canonical)?.deref();
         if (live !== undefined) {
@@ -114,7 +129,7 @@ export class FileSessionRepo {
             return live;
         }
         const log = new AppendLog(this.pathFor(id));
-        const created = new FileSessionStorage(log, { id, createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}), ...(placement !== undefined ? { placement } : {}) }, entries, canonical);
+        const created = new FileSessionStorage(log, meta, entries, canonical);
         sharedSessionStorages.set(canonical, new WeakRef(created));
         created.addHolder(this);
         this.joined.set(canonical, new WeakRef(created));
@@ -140,15 +155,16 @@ export class FileSessionRepo {
         if (!existsSync(path)) {
             evictSharedSessionStorage(canonicalStoreKey(path));
             const placement = options.placement !== undefined ? { ...options.placement, placedAt: options.placement.placedAt ?? Date.now() } : undefined;
-            atomicWriteFile(this.tmpDir, path, `${JSON.stringify({ kind: "meta", id, createdAt, ...(placement !== undefined ? { placement } : {}) })}\n`);
-            return new StoredSession(this.storage(id, createdAt, [], undefined, placement));
+            const meta = { id, createdAt, ...(placement !== undefined ? { placement } : {}), ...incarnationCell(undefined) };
+            atomicWriteFile(this.tmpDir, path, `${JSON.stringify({ kind: "meta", ...meta })}\n`);
+            return new StoredSession(this.storage(meta, []));
         }
-        const { createdAt: existingCreatedAt, forkedFrom, placement, entries } = this.read(id);
-        return new StoredSession(this.storage(id, existingCreatedAt || createdAt, entries, forkedFrom, placement));
+        const { meta, entries } = this.read(id);
+        return new StoredSession(this.storage({ ...meta, createdAt: meta.createdAt || createdAt }, entries));
     }
     async open(metadata) {
-        const { createdAt, forkedFrom, placement, entries } = this.read(metadata.id);
-        return new StoredSession(this.storage(metadata.id, createdAt, entries, forkedFrom, placement));
+        const { meta, entries } = this.read(metadata.id);
+        return new StoredSession(this.storage(meta, entries));
     }
     async list() {
         let names;
@@ -167,7 +183,7 @@ export class FileSessionRepo {
                 continue;
             const id = name.slice(0, -SUFFIX.length);
             try {
-                const { createdAt, forkedFrom, placement } = this.read(id);
+                const { createdAt, forkedFrom, placement } = this.read(id).meta;
                 if (placement !== undefined)
                     continue;
                 out.push({ id, createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}) });
@@ -199,7 +215,7 @@ export class FileSessionRepo {
             const id = name.slice(0, -SUFFIX.length);
             let placement;
             try {
-                placement = this.read(id).placement;
+                placement = this.read(id).meta.placement;
             }
             catch (err) {
                 if (!(err instanceof SessionError && err.code === "not_found")) {
@@ -227,9 +243,17 @@ export class FileSessionRepo {
         }
         return out;
     }
+    priorHeader(id) {
+        try {
+            return this.read(id).meta;
+        }
+        catch (err) {
+            return err instanceof SessionError && err.code === "not_found" ? undefined : {};
+        }
+    }
     async placementOf(sessionId) {
         try {
-            return this.read(sessionId).placement;
+            return this.read(sessionId).meta.placement;
         }
         catch {
             return undefined;
@@ -245,20 +269,20 @@ export class FileSessionRepo {
         }
     }
     async fork(sourceMetadata, options = {}) {
+        assertForkTarget(sourceMetadata.id, options.id);
         const source = await this.open(sourceMetadata);
         const forked = await getEntriesToFork(source.getStorage(), options);
         const id = options.id ?? uuidv7();
         const createdAt = new Date().toISOString();
         const path = this.pathFor(id);
-        const lines = [
-            JSON.stringify({ kind: "meta", id, createdAt, forkedFrom: sourceMetadata.id }),
-        ];
+        const meta = { id, createdAt, ...forkRowCells(await source.getMetadata()) };
+        const lines = [JSON.stringify({ kind: "meta", ...meta })];
         for (const entry of forked) {
             lines.push(JSON.stringify({ kind: "entry", entry }));
         }
         evictSharedSessionStorage(canonicalStoreKey(path));
         atomicWriteFile(this.tmpDir, path, `${lines.join("\n")}\n`);
-        return new StoredSession(this.storage(id, createdAt, [...forked], sourceMetadata.id));
+        return new StoredSession(this.storage(meta, [...forked]));
     }
     async exportEntries(sessionId) {
         return this.read(sessionId).entries;
@@ -266,9 +290,10 @@ export class FileSessionRepo {
     async importEntries(sessionId, owner, entries, options) {
         void owner;
         const validated = validateEntriesForImport(entries, options);
+        const prior = this.priorHeader(sessionId);
         evictSharedSessionStorage(canonicalStoreKey(this.pathFor(sessionId)));
         const createdAt = new Date().toISOString();
-        const lines = [JSON.stringify({ kind: "meta", id: sessionId, createdAt })];
+        const lines = [JSON.stringify({ kind: "meta", id: sessionId, createdAt, ...incarnationCell(prior) })];
         for (const entry of validated) {
             lines.push(JSON.stringify({ kind: "entry", entry }));
         }

package/dist/tools/artifact/artifact-tool.js

@@ -5,6 +5,7 @@ import { Type } from "typebox";
 import { ARTIFACT_ACTION_CONCURRENCY_SAFE, ARTIFACT_COMMIT_THROW_OUTCOME, ARTIFACT_FAILURE_RESULT_CODE, ARTIFACT_HOST_ERROR_CODE, ARTIFACT_LIST_SCOPES, ARTIFACT_PLANE_CONTENT_ORIGIN, ARTIFACT_PUBLISH_CONTEXTS, } from "../../core/artifact-host.js";
 import { ARTIFACT_TOOL_NAME, toolFace } from "../../core/tool-catalog-entries.js";
 import { resolveAsk } from "../../core/tool-policy.js";
+import { approvalCardOf } from "../../core/tool-roster.js";
 import { errorResult } from "../../core/tools.js";
 import { inlineUntrusted } from "../../core/untrusted-text.js";
 import { actionDescription, artifactDescription, PARAM_TEXT, urlDescription } from "./artifact-text.js";
@@ -343,6 +344,7 @@ export function createArtifactTool(opts) {
                 args: { action: "read", url },
                 message: `Read a shared artifact: ${inlineUntrusted(url, 300)}${title}${version} — an artifact another person shared with this user; approving covers re-reads of it for the rest of this run.`,
                 requiresRealApproval: true,
+                approvalCard: approvalCardOf({ toolName: ARTIFACT_TOOL_NAME }, toolFace("artifact").renderHints?.approvalCard),
             }, onAsk, ctx.signal);
             if (resolved.action !== "allow")
                 return { ok: false, reason: resolved.message ?? "not approved" };

package/dist/tools/fs/bash-program-position.d.ts

@@ -16,9 +16,8 @@ export declare const NOT_AUTO_ALLOWED = "\u2014 not auto-allowed";
 export declare function programBasename(word: string): string;
 /**
  * The `NAME=` / `NAME+=` prefix as WRITTEN in a whitespace-split token. This is NOT the position reader's grammar
- * — the reader reads the lexer's {@link LexedWord.assignment} fact — but the two readers that still walk the
- * command TEXT rather than its words (the unverifiable-delete policy and the activity summary) read it, and
- * they read it here so that they read one spelling. It retires with them.
+ * — the reader reads the lexer's {@link LexedWord.assignment} fact — but the one reader that still walks the
+ * command TEXT rather than its words (the activity summary) reads it here. It retires with it.
  */
 export declare const ASSIGNMENT_PREFIX: RegExp;
 /** The prefix a whitespace-split token BEGINS with, or `undefined` — the text readers' view of
@@ -30,6 +29,10 @@ export declare function writtenAssignmentPrefix(token: string): {
     readonly appends: boolean;
     readonly settlesWholeName: boolean;
 } | undefined;
+/** The names a segment's COMMAND ENVIRONMENT sets for the program it starts: the assignment words in front of the
+ *  program (the lexer's {@link LexedWord.assignment} fact, a launcher's `NAME=value` operand included) — or `all` where
+ *  a launcher in front of it may set, clear or replace the environment (`env -u` / `-i`, `sudo`, `su`, …). */
+export declare function commandEnvironmentNames(argv: readonly LexedWord[]): ReadonlySet<string> | "all";
 export { SHELL_CONTROL_PREFIXES };
 /** A control word is a keyword only when bash sees it BARE: `'if'` / `"do"` / `\\!` are command names (a program
  *  looked up on PATH, whose failure changes nothing), so a quoted or escaped spelling never counts as one. */
@@ -99,6 +102,10 @@ export interface ProgramPosition {
     } | undefined;
     /** Why no program could be read; `undefined` beside `program: undefined` means the chain simply names none. */
     readonly refusal: ProgramPositionRefusal | undefined;
+    /** A launcher of the chain moves the directory or the root the program runs in, or where its word is looked up
+     *  (`env -C <dir>`, `sudo -R <dir>`, `env -P <dirs>`): the program is still the word it names, but where its path
+     *  operands resolve is not the command line's working directory — each consumer reads that as it must. */
+    readonly launcherMovesBase: boolean;
 }
 /**
  * Read the program position of one segment's argv words.

package/dist/tools/fs/bash-program-position.js

@@ -1,5 +1,6 @@
 import { SHELL_CONTROL_PREFIXES } from "../../shell/lex.js";
-import { BLOCK_WORD_NAMES, LAUNCHER_NAMES, feedsArgvFromStdin, launcherOptionStep, launcherRunsShell, programRow, selectedOptions, streamDefaultProgram } from "./program-read-model.js";
+import { shellWordsOf } from "../../shell/shell-words.js";
+import { BLOCK_WORD_NAMES, LAUNCHER_NAMES, feedsArgvFromStdin, launcherOptionMovesBase, launcherOptionStep, launcherRunsShell, programRow, selectedOptions, streamDefaultProgram } from "./program-read-model.js";
 export const NOT_AUTO_ALLOWED = "— not auto-allowed";
 export function programBasename(word) {
     return word.includes("/") ? (word.split("/").pop() ?? word) : word;
@@ -14,6 +15,13 @@ export function writtenAssignmentPrefix(token) {
     const bracket = written.indexOf("[");
     return { prefix, name: bracket < 0 ? written : written.slice(0, bracket), appends, settlesWholeName: !appends && bracket < 0 };
 }
+const ENVIRONMENT_KEEPING_LAUNCHERS = new Set(["nice", "nohup", "time", "timeout", "stdbuf", "ionice", "chrt", "taskset", "command", "builtin", "caffeinate"]);
+export function commandEnvironmentNames(argv) {
+    const pos = readProgramPosition(argv);
+    if (pos.launchers.some((l) => !ENVIRONMENT_KEEPING_LAUNCHERS.has(l.name)))
+        return "all";
+    return new Set(argv.slice(0, pos.program?.index ?? argv.length).flatMap((w) => (w.assignment?.bare === true ? [w.assignment.name] : [])));
+}
 export { SHELL_CONTROL_PREFIXES };
 export function isBareControlWord(words, i, set) {
     return isShellSyntaxWord(words[i], set);
@@ -21,7 +29,7 @@ export function isBareControlWord(words, i, set) {
 export function isShellSyntaxWord(w, set) {
     return w !== undefined && w.atCommandPosition && w.raw === w.folded && set.has(w.folded);
 }
-export const LOOP_LIST_HEADS = new Set(["for", "select"]);
+export const LOOP_LIST_HEADS = shellWordsOf("loop_list_head");
 export function isLeadingAssignmentWord(words, i) {
     const w = words[i];
     return w !== undefined && w.assignment !== undefined && w.assignment.bare && w.atCommandPosition;
@@ -30,7 +38,7 @@ function launcherRowOf(name) {
     const row = programRow(name);
     return row?.launcher !== undefined ? row : undefined;
 }
-function pastLauncherOptions(launcher, folded, i) {
+function pastLauncherOptions(launcher, folded, i, moved) {
     const row = launcherRowOf(launcher);
     if (row === undefined)
         return i;
@@ -47,6 +55,8 @@ function pastLauncherOptions(launcher, folded, i) {
             return i;
         if (step === 2 && folded[i + 1] === undefined)
             return i;
+        if (launcherOptionMovesBase(row, tok))
+            moved?.();
         i += step;
     }
 }
@@ -60,7 +70,7 @@ export function readProgramPosition(words) {
         controlWords.push(i);
         i = pastLauncherOptions(controlWord, folded, i + 1);
     }
-    const none = (written, assignments, refusal) => ({ controlWords, written, assignments, launchers: [], argvFromStdin: false, runsDefaultProgram: false, program: undefined, refusal });
+    const none = (written, assignments, refusal) => ({ controlWords, written, assignments, launchers: [], argvFromStdin: false, runsDefaultProgram: false, program: undefined, refusal, launcherMovesBase: false });
     if (i >= folded.length)
         return none(undefined, []);
     const written = i;
@@ -78,25 +88,27 @@ export function readProgramPosition(words) {
         return none(written, assignments, { kind: "option_at_program_position", owner, option: head });
     }
     if (!LAUNCHER_NAMES.has(basename)) {
-        return { controlWords, written, assignments, launchers: [], argvFromStdin: false, runsDefaultProgram: false, program: { index: i, name: head, basename }, refusal: undefined };
+        return { controlWords, written, assignments, launchers: [], argvFromStdin: false, runsDefaultProgram: false, program: { index: i, name: head, basename }, refusal: undefined, launcherMovesBase: false };
     }
     const launchers = [{ index: i, name: basename }];
     const owner = head;
     const shellRefusal = (launcher, from) => ({ kind: "control_syntax_at_program_position", owner, word: "sh", runsShell: { launcher, from } });
     let lastRow = launcherRowOf(basename)?.launcher;
     let owedOperands = lastRow?.requiredOperands ?? 0;
-    const chain0 = (program, refusal) => ({ controlWords, written, assignments, launchers, argvFromStdin: false, runsDefaultProgram: false, program, refusal });
+    const chain0 = (program, refusal) => ({ controlWords, written, assignments, launchers, argvFromStdin: false, runsDefaultProgram: false, program, refusal, launcherMovesBase: false });
     if (launcherRunsShell(launcherRowOf(basename), folded.slice(i + 1)))
         return chain0(undefined, shellRefusal(i, i + 1));
     let argvFromStdin = feedsArgvFromStdin(basename);
     let lastReentry = argvFromStdin ? i : -1;
     let reentryDefault = argvFromStdin ? streamDefaultProgram(basename) : undefined;
+    let launcherMovesBase = false;
+    const moved = () => { launcherMovesBase = true; };
     const chain = (program, refusal) => {
         const runsDefaultProgram = lastReentry === folded.length - 1;
-        return { controlWords, written, assignments, launchers, argvFromStdin, runsDefaultProgram, ...(runsDefaultProgram && reentryDefault !== undefined ? { defaultProgram: reentryDefault } : {}), program, refusal };
+        return { controlWords, written, assignments, launchers, argvFromStdin, runsDefaultProgram, ...(runsDefaultProgram && reentryDefault !== undefined ? { defaultProgram: reentryDefault } : {}), program, refusal, launcherMovesBase };
     };
     const selectsShell = (l, end) => selectedOptions(launcherRowOf(l.name), folded.slice(l.index + 1, end)).some((o) => o.mode === "interactive");
-    for (let j = pastLauncherOptions(basename, folded, i + 1); j < folded.length; j++) {
+    for (let j = pastLauncherOptions(basename, folded, i + 1, moved); j < folded.length; j++) {
         const t = folded[j];
         if (owedOperands > 0 && !t.startsWith("-")) {
             owedOperands -= 1;
@@ -121,7 +133,7 @@ export function readProgramPosition(words) {
             if (launcherRunsShell(launcherRowOf(wordBasename), folded.slice(j + 1)))
                 return chain(undefined, shellRefusal(j, j + 1));
             owedOperands = lastRow?.requiredOperands ?? 0;
-            j = pastLauncherOptions(wordBasename, folded, j + 1) - 1;
+            j = pastLauncherOptions(wordBasename, folded, j + 1, moved) - 1;
             continue;
         }
         if (t.startsWith("-"))

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -361,7 +361,7 @@ export declare function formatOutOfRootReadApprovalOption(directory: string): st
  *     resolved to nothing, was dropped, and the verdict was empty, i.e. a read outside every root
  *     AUTO-ALLOWED on the one face whose doctrine is hard refusal in exactly that direction.
  *  The second fact is why the lane split in
- *  {@link collectSegmentBoundaryFindings} tests {@link isAbsolutePathForm} BESIDE this predicate,
+ *  {@link collectSegmentBoundaryFindings} tests {@link isAbsoluteForFamily} (an address's own family) BESIDE this predicate,
  *  which is what the option-payload arm always did; the two now read one rule rather than two. */
 export declare function isPathShapedToken(tok: string): boolean;
 /** Resolve one operand against the boundary's base, WITHOUT touching the filesystem. Returns undefined

package/dist/tools/fs/bash-readonly-classifier.js

@@ -1,5 +1,6 @@
-import { isAbsoluteForFamily, isAbsolutePathForm, isBlockedDevicePath, isShellRootedSpellingUnmapped, joinForFamily, nativeUncSpellingOf, normalizeAbsPathLexically, win32NamespaceScreen, pathFamilyOf } from "./safety.js";
+import { anchorSpelling, isAbsoluteForFamily, isBlockedDevicePath, isShellRootedSpellingUnmapped, nativeUncSpellingOf, normalizeAbsPathLexically, win32NamespaceScreen, pathFamilyOf } from "./safety.js";
 import { PARSE_FAILURE_SENTENCE, UNRESOLVED_SENTENCE, argvOf, lexShell, literalTildeSpelling, } from "../../shell/lex.js";
+import { shellWordsOf } from "../../shell/shell-words.js";
 import { textBindsHome } from "./shell-read-bindings.js";
 import { NOT_AUTO_ALLOWED, argvReentryUnjudged, isBareControlWord, programPositionRefusalSentence, readProgramPosition, } from "./bash-program-position.js";
 import { BLOCK_WORD_NAMES, attachedStdinFile, declaresOption, firstOperandSlot, opensNoOperand, programDelivery, programRow, programTextReadings, readArgRoles, readArgs, readProgramTextLanguage, runsShellText, selectedOptions, slotValueCandidates, suppliesFirstOperandSlot, takesSeparatedDatum, valuesAreLiteral, writeReadings, writesPath, } from "./program-read-model.js";
@@ -171,7 +172,7 @@ const PARENT_SEGMENT_RE = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
 export function resolveOperandSpellings(base, operand, homeDir) {
     let raw = operand;
     if (raw === "~" || raw.startsWith("~/")) {
-        if (homeDir === undefined || !isAbsolutePathForm(homeDir))
+        if (homeDir === undefined || !isAbsoluteForFamily("own", homeDir))
             return undefined;
         raw = raw === "~" ? homeDir : `${homeDir.replace(/[/\\]+$/, "")}/${raw.slice(2)}`;
     }
@@ -181,13 +182,13 @@ export function resolveOperandSpellings(base, operand, homeDir) {
     const family = base === undefined ? undefined : pathFamilyOf({ root: base });
     if (!win32NamespaceScreen(raw, family).ok)
         return undefined;
-    if (isAbsoluteForFamily(family, raw))
+    if (isAbsoluteForFamily(family ?? "own", raw))
         return spellingsOf(nativeUncSpellingOf(family, raw));
     if (base === undefined || family === undefined || !isAbsoluteForFamily(family, base))
         return undefined;
     if (isShellRootedSpellingUnmapped(family, raw))
         return undefined;
-    return spellingsOf(joinForFamily(family, base, raw));
+    return spellingsOf(anchorSpelling(family, base, raw));
 }
 function spellingsOf(absolute) {
     const folded = normalizeAbsPathLexically(absolute);
@@ -660,7 +661,7 @@ export function attachedOptionPayloads(tok) {
         return out;
     }
     const whole = literal(tok.slice(1));
-    if (whole.length > 0 && (isPathShapedToken(whole) || isAbsolutePathForm(whole)))
+    if (whole.length > 0 && (isPathShapedToken(whole) || isAbsoluteForFamily("own", whole)))
         out.push(whole);
     for (let k = 2; k <= tok.length; k++) {
         if (![...tok.slice(1, k)].every((ch) => CLUSTER_OPTION_CHAR.test(ch)))
@@ -744,7 +745,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
         const written = folded[from];
         if (written === undefined)
             return { reason: "empty command" };
-        if (written === "coproc")
+        if (shellWordsOf("background").has(written))
             return { reason: "`coproc` backgrounds a command — a backgrounded process outlives the command" };
         if (isBareControlWord(words, from, BLOCK_WORD_NAMES)) {
             unlistedSegments.add(si);
@@ -777,7 +778,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
         if (runsShellText(name))
             return { reason: unjudgedProgramTextRefusal(parsed.name, "runs its argument as shell text") };
         if (pos.launchers.length > 0) {
-            const listed = program !== undefined && (allow.has(program.basename) || program.basename === "cd");
+            const listed = program !== undefined && allow.has(program.basename);
             if (program !== undefined && !listed && runsShellText(program.basename)) {
                 return { reason: `"${written}" runs "${program.basename}", which runs its argument as shell text this classifier does not read ${NOT_AUTO_ALLOWED}` };
             }

package/dist/tools/fs/containment-face.d.ts

@@ -3,6 +3,10 @@
  *  type gates all still run). One type for both seats: the two faces differ in WHICH band consults
  *  them, never in what the word means. */
 export type ContainmentFace = "open" | "roots";
+/** Does a face state skip the roots-containment step? The ONE reading of a face seat a containment judgment takes — the
+ *  structured tools' path check and the shell station's write face alike: `"open"` skips it; `"roots"` and an ABSENT
+ *  state run it (absent ⇒ roots, the historical fence). */
+export declare function skipsRootsContainment(face: ContainmentFace | undefined): boolean;
 /** Which band a face governs. Selects the seat spellings and the error codes below — never the
  *  resolution ORDER, which is one body shared by both. */
 export type ContainmentFaceKind = "read" | "write";

package/dist/tools/fs/containment-face.js

@@ -1,4 +1,7 @@
 import { describeRejectedValue } from "../../core/tool-search-setting.js";
+export function skipsRootsContainment(face) {
+    return face === "open";
+}
 const FACE_DIALECT = {
     read: {
         key: "readFace",

package/dist/tools/fs/fs-shared.d.ts

@@ -253,6 +253,16 @@ export declare function bashMaxOutputChars(): number;
 export declare const FILE_PATH_PARAMS: {
     file_path: Type.TString;
 };
+/**
+ * Write's pre-validation argument repair — CC 2.1.296 `orr` (the Write tool's `coerceInput`, cli296.js:247143),
+ * the two rules that matter under a non-strict schema: `path` is read as `file_path` when `file_path` is absent
+ * and `path` is a string; exactly one of `file_text` / `file_content` is read as `content` when `content` is
+ * absent and the value is a string. Anything else — both content aliases, a present `file_path`, a non-string
+ * value — is left to the schema, which refuses it by naming the parameter. The repaired key REPLACES the alias
+ * (it is deleted), so no second spelling rides on into the gates. Idempotent, and the very same object for a
+ * call that needs no repair (the loop's "prepared arguments changed" test is a reference test).
+ */
+export declare function coerceWriteArguments(args: unknown): unknown;
 /** Honest head+tail truncation to {@link bashMaxOutputChars}: the middle is dropped with a real-total
  *  marker, because the head AND tail both matter for a shell. Kept as the inline shape even beside the
  *  file-backed recovery below — unlike a background task's poll-for-the-latest-tail interaction, a

package/dist/tools/fs/fs-shared.js

@@ -185,6 +185,24 @@ export function bashMaxOutputChars() {
 export const FILE_PATH_PARAMS = {
     file_path: Type.String({ description: "File path (within the configured root)." }),
 };
+const WRITE_CONTENT_ALIASES = ["file_text", "file_content"];
+export function coerceWriteArguments(args) {
+    if (args === null || typeof args !== "object" || Array.isArray(args))
+        return args;
+    const a = args;
+    let repaired;
+    if (!Object.hasOwn(a, "file_path") && typeof a["path"] === "string") {
+        repaired = { ...a, file_path: a["path"] };
+        delete repaired["path"];
+    }
+    const spelled = WRITE_CONTENT_ALIASES.filter((k) => Object.hasOwn(a, k));
+    const alias = spelled[0];
+    if (alias !== undefined && spelled.length === 1 && !Object.hasOwn(a, "content") && typeof a[alias] === "string") {
+        repaired = { ...(repaired ?? a), content: a[alias] };
+        delete repaired[alias];
+    }
+    return repaired ?? args;
+}
 export function clipShellOutput(s) {
     return clipWithFilePointer(s, bashMaxOutputChars());
 }

package/dist/tools/fs/fs-write.js

@@ -3,7 +3,7 @@ import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
 import { sha256, resolveKey, violationText, violationDetails, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, READ_REFUSED_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
-import { MAX_EDIT_BYTES, decodeEditBytes, tooLargeToEditMessage, truncatedUtf16BodyMessage, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, ipynbRedirect, countLines, applyRecordedEdit, } from "./fs-shared.js";
+import { MAX_EDIT_BYTES, decodeEditBytes, tooLargeToEditMessage, truncatedUtf16BodyMessage, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, coerceWriteArguments, ipynbRedirect, countLines, applyRecordedEdit, } from "./fs-shared.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
 import { thrownText } from "../../core/thrown-value.js";
 async function envFinalWrite(env, key, content, signal, opts) {
@@ -326,7 +326,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
     });
 }
 export function createWriteFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace, writeDeny) {
-    return defineTool({
+    const write = defineTool({
         name: "Write",
         ...toolFace("write"),
         description: "Writes a file to the local filesystem, overwriting if one exists.\n" +
@@ -420,6 +420,8 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             };
         },
     });
+    write.prepareArguments = coerceWriteArguments;
+    return write;
 }
 const notebookNotIpynbMessage = (notebookPath) => `Error (NotebookEdit): "${notebookPath}" is not a .ipynb file; use Edit for other file types.`;
 const NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE = `Error (NotebookEdit): Cell type is required when using edit_mode=insert.`;

package/dist/tools/fs/index.d.ts

@@ -188,7 +188,7 @@ export interface HandsToolkitOptions {
      *  same list as {@link import("./shell-read-check.js").ShellReadJudgeInput.readDenyHomes}. */
     readDenyHomes?: readonly string[];
     /** Where each home-anchored row's literal head leads beyond the home's spellings, and each rooted row's (`/…`) beyond its own
-     *  spelling ({@link import("./read-deny-home.js").readDenyHomeLinksOf} / {@link import("./read-deny-home.js").readDenyRootLinksOf},
+     *  spelling ({@link import("./read-deny-home.js").readDenyLinksOf},
      *  keyed by the row's pattern) — the Runner passes the
      *  locations its own judge was compiled with, so the band and the gate judge one placement.
      *  Unless a mount carries both, the band resolves the placement itself the way the Runner does (the homes it carries

package/dist/tools/fs/program-read-model.d.ts

@@ -1,3 +1,24 @@
+/**
+ * The PROGRAM READ MODEL — one table that answers "what does this program do with its k-th word", and the readers
+ * every shell face reads it through.
+ *
+ * A row is one program (the basename bash runs; a versioned spelling of an interpreter is its row), carrying every
+ * argument fact the shell faces need: its option grammar (one per implementation where implementations disagree),
+ * the ROLE each option value and each operand plays, whether a form walks a tree, how an interpreter receives the
+ * program it runs, what a launcher steps over before the program it runs, which words a builtin keeps as shell text
+ * to run later. The rows live in `program-read-model.rows.ts`; this module is the schema and the readers.
+ *
+ * Every reader below is a PROJECTION of the same row: the option-slot reading the candidate extraction walks
+ * (`readArgs`), the traversal reading, the program-delivery reading, the launcher step, the program-text reading of a
+ * language the station parses, the message slots, the code bodies. A reader never carries a table of its own; a fact
+ * one reader needs and the row does not state is added to the row, where every other reader sees it too.
+ *
+ * Rows are checked against the real binaries by `test/program-read-model.binary-gate.test.ts`: each declared option
+ * of each row is run, per implementation, on fixtures whose every word is a FIFO, and the words the binary OPENED are
+ * compared with the words the row predicts it opens. A row whose opener cannot be witnessed locally (a daemon, an
+ * object store, a shell builtin) says so in its `witness`, with the reason.
+ */
+import { type WordPiece } from "../../shell/lex.js";
 /** What a datum names: never a file. */
 export declare const DATUM_FORMS: readonly ["count", "pattern", "name-pattern", "label", "message", "delimiter"];
 export type DatumForm = (typeof DATUM_FORMS)[number];
@@ -339,11 +360,9 @@ export interface ProgramRow {
     /** What a declaration builtin does to every name it binds with no switch selected ({@link OptionSpec.assigns}):
      *  `readonly` makes them read-only, as `declare -r` does. */
     readonly assigns?: DeclaredAttribute;
-    /** It moves the working directory in a way the station does not follow (`pushd`). */
-    readonly movesBase?: "unfollowed";
-    /** What it writes to its standard output, read off its operands ({@link printedText}): `words` = its operands joined
-     *  by a space (`echo`), `format` = its one operand as a format (`printf`). */
-    readonly prints?: "words" | "format";
+    /** It moves the working directory through the directory stack (`pushd` / `popd`): the working-directory thread reads
+     *  how (`shell-read-workdir.ts`). */
+    readonly movesBase?: "stack";
     /** A shell block word at the program position: it names no command of its own. */
     readonly syntax?: "block";
     /** Git-style subcommands: the word after the program's own options names one, and the words after it are read by
@@ -383,7 +402,7 @@ export declare function isDeclarationBuiltin(name: string): boolean;
 export declare function declaredAttributes(row: ProgramRow | undefined, args: readonly string[]): ReadonlySet<DeclaredAttribute>;
 /** Opens no file, starts no program and evaluates nothing (a declaration builtin: only bare — its caller checks). */
 export declare function isInertBuiltin(name: string): boolean;
-export declare function movesBaseUnfollowed(name: string): boolean;
+export declare function movesBaseByStack(name: string): boolean;
 /** The LONG-OPTION name carried by a token (`--file=p` → `file`, `--reg` → `reg`); `undefined` for anything that is
  *  not a long option with a non-empty name (`--`, `--=x`, a short option). */
 export declare function longOptionNameOf(tok: string): string | undefined;
@@ -668,14 +687,6 @@ export declare function programDelivery(row: ProgramRow | undefined, args: reado
 /** The language of the program an interpreter row runs: the language of its program operand, or of the first option that
  *  delivers program text or a program file. `undefined` for a row that runs no program text. */
 export declare function programLanguageOf(row: ProgramRow | undefined): string | undefined;
-/**
- * The text a printer row ({@link ProgramRow.prints}) writes to its standard output, read off its argv (the program word
- * excluded; `undefined` = a word whose value the command does not spell). `undefined` wherever the words do not spell the
- * text: such a word, an option the row does not explain, an escape the program may interpret (a backslash: `echo -e`, an
- * `echo` that reads escapes by default, every `printf` format), a format with a directive (`%`) or values to fill it, or a
- * row that prints nothing it is handed.
- */
-export declare function printedText(row: ProgramRow | undefined, args: readonly (string | undefined)[]): string | undefined;
 /**
  * The argv indices some implementation of the row reads as a path it OPENS (an ordinary operand, a value or operand of a
  * reading path role, a program file) while another reads them as something else (program text, a backup suffix, a
@@ -701,6 +712,11 @@ export declare function launcherOptionArity(row: ProgramRow, tok: string): 0 | 1
 export declare function launcherOptionPathRole(row: ProgramRow, tok: string): Extract<ArgRole, {
     kind: "path";
 }> | undefined;
+/** Does this launcher option word move the base its program runs in — the directory, the root, or where its word is looked
+ *  up (an option whose value's role is a path with a `base`) — read off the option itself, whether or not its value is
+ *  written (`nsenter -w` bare takes the target process's directory)? In a cluster, a letter up to the first that takes a
+ *  value. `false` for any word the walk does not step. */
+export declare function launcherOptionMovesBase(row: ProgramRow, tok: string): boolean;
 /** How many words one launcher option occupies ({@link readLauncherOption}), or `undefined` where the row does not
  *  explain it. */
 export declare function launcherOptionStep(row: ProgramRow, tok: string): 1 | 2 | undefined;
@@ -754,13 +770,18 @@ export declare function subcommandOf(row: ProgramRow | undefined, words: readonl
     readonly relocated: boolean;
 } | undefined;
 /**
- * The indices of the SETTLED words a row's subcommand reads as message text: the value of its message option attached
- * or as the next word, by its own grammar. The global options are read exactly ({@link subcommandOf}); in the subcommand
- * an unknown long option takes no value, an unknown short letter or an unsettled word takes the next word (which is
- * then never a message).
+ * The indices of the words a row's subcommand reads as message text: the value of its message option attached or as the
+ * next word, by its own grammar. The global options are read exactly ({@link subcommandOf}); in the subcommand an unknown
+ * long option takes no value, an unknown short letter or an unsettled word takes the next word (which is then never a
+ * message). The option word itself is settled; its separate value is a message whether the text settles it or the shell
+ * computes it as ONE argument — every expansion in it a command substitution in double quotes, whose output is one field
+ * (a parameter is not taken so: `"$@"` and `"${a[@]}"` are several).
  */
 export declare function messageWords(program: string, words: readonly {
     readonly folded: string;
     readonly expands: unknown;
+    readonly word?: {
+        readonly expansions: readonly WordPiece[];
+    };
 }[], programIndex: number): Set<number>;
 export {};