@sema-agent/core 7.48.0 → 7.49.1

package/dist/tools/fs/shell-read-workdir.d.ts

@@ -0,0 +1,156 @@
+/**
+ * THE WORKING-DIRECTORY THREAD — where a command stands at each of its segments, and what `PWD` / `OLDPWD` hold there.
+ * ONE walk (`shell-read-plan.ts` drives it, segment by segment, beside the binding thread) over a CLOSED word set that
+ * moves the base ({@link BaseShift}): `cd` in its forms — a bare relative target searched through `CDPATH` first, `cd -`
+ * going to `OLDPWD`, a bare `cd` to `HOME`, `-P` / `set -P` leaving `PWD` a spelling the text does not hold — `pushd` /
+ * `popd` with the stack the text pushed, and a literal `eval` text read as the text it is, in this shell. Any other text
+ * that may move the base where the plan cannot follow it (`source`, a non-literal `eval`, a computed program word, a
+ * call into a function body or a code body that may move, an option the stack reading does not follow) LOSES it: what
+ * stands after it cannot be placed. A move inside a subshell, a pipeline member or a function body nobody called is read
+ * as a move too — a candidate SET, more places, never fewer (a move may also fail: the unmoved place stays a candidate
+ * unless an `&&` run proves the move ran).
+ */
+import type { Bare } from "./shell-read-argv.js";
+import type { BindingTable, WorkingDirectoryState } from "./shell-read-bindings.js";
+import type { Read } from "./shell-read-word.js";
+import { type LexedWord } from "../../shell/lex.js";
+import { type FunctionCall } from "./shell-read-functions.js";
+/** A working directory the shell could be standing in, with the latest move this candidate assumes did NOT run
+ *  (`skippedCd`), and what the shell holds there: `pwd` — what `PWD` spells (absent: not the base's spelling — a physical
+ *  move, or a start the plan does not place), `old` — what `OLDPWD` holds (absent: what the shell inherited, unknown),
+ *  `stack` — the directories the text pushed and has not popped, top first (absent: the text changed the stack in a way
+ *  this walk does not follow; what lies below the text's own entries is the shell's, unknown). */
+export interface BaseCandidate {
+    readonly base: string;
+    readonly skippedCd: number;
+    readonly pwd?: string;
+    readonly old?: string;
+    readonly dirStack?: readonly string[];
+}
+/** How one segment moves the base — the closed word set. `cd`: a `cd` (`push`: a `pushd DIR`) to a target, the
+ *  declared-home spelling of an unsettled target for the deny floor; `swap`: `pushd` with no directory; `pop`: `popd`;
+ *  `stack`: the stack changes and the base does not (`pushd -n`, `popd -n`, `dirs -c`); `eval`: a literal `eval` text;
+ *  `lost`: a move this walk does not follow. */
+export type BaseShift = {
+    readonly kind: "cd";
+    readonly target: Bare | "home" | "previous";
+    readonly physical: boolean;
+    readonly push?: true;
+} | {
+    readonly kind: "swap" | "pop" | "stack" | "lost";
+} | {
+    readonly kind: "eval";
+    readonly text: string;
+};
+/** What the walk asks of the plan around it: the declared home (a `~` target), whether the text binds a name anywhere
+ *  (`OLDPWD` — then `cd -` reads the table's value; `PWD` — then a move's `OLDPWD` is not the base the candidate stood
+ *  in), and where a literal `eval` text started at a candidate ends ({@link WorkdirThread.end}). */
+export interface WorkdirContext {
+    readonly homeDir?: string;
+    readonly textBinds: (name: string) => boolean;
+    readonly evalEnd: (text: string, from: BaseCandidate, table: BindingTable) => {
+        readonly end: readonly BaseCandidate[] | "unmodelled";
+        readonly physical: boolean;
+    };
+}
+/** One segment's move as the walk applies it: the shift, whether an `&&` run proves it ran, the first segment of the
+ *  reader's `&&` run, the names there, and whether `cdable_vars` may be on (a bare name may be a variable's value). */
+export interface ShiftAt {
+    readonly shift: BaseShift;
+    readonly provable: boolean;
+    readonly andRunStart: number;
+    readonly table: CommandTable;
+    readonly cdable: boolean;
+}
+/** The names at a `cd` segment with the command's own prefix assignments in force (`HOME=/ cd`), and which names those are. */
+export interface CommandTable extends BindingTable {
+    readonly commandSets: ReadonlySet<string>;
+}
+export declare class WorkdirThread {
+    /** The start is where the shell stands (not a placeholder a nested plan is re-based from): `PWD` reads it. */
+    private readonly readable;
+    private candidates;
+    private lostAt;
+    /** The reachable bases at the moment the walk lost track — the deny floor of a word it cannot place. */
+    private floors;
+    /** `set -P` (or `-o physical`) may be on — a text it began in, an `eval` text that set it — : a later move leaves `PWD` a physical
+     *  spelling the text does not hold, and a `..` in a target resolves links the plan cannot see. */
+    private physical;
+    /** The last segment whose move was applied or lost track ({@link WorkingDirectoryState.movedAt}). */
+    private movedAt;
+    constructor(start: readonly BaseCandidate[] | readonly string[] | "unmodelled", 
+    /** The start is where the shell stands (not a placeholder a nested plan is re-based from): `PWD` reads it. */
+    readable: boolean, 
+    /** The physical mode may already be on where the text starts (an `eval` text run in a shell that set it). */
+    startsPhysical?: boolean);
+    get lost(): boolean;
+    get floorBases(): readonly string[] | undefined;
+    /** The candidates a reader whose `&&` run starts at `andRunStart` may stand in. */
+    reachable(andRunStart: number): readonly BaseCandidate[];
+    /** Where the text ends: every candidate, or `unmodelled`. */
+    end(): readonly BaseCandidate[] | "unmodelled";
+    /** What `PWD` / `OLDPWD` hold for a reader whose `&&` run starts at `andRunStart`. */
+    where(andRunStart: number): WorkingDirectoryState;
+    /** `set -P` / `set -o physical`: from here on a move's `PWD` is a physical spelling. */
+    setPhysical(): void;
+    /** Where the text ends the physical mode may be on (an `eval` text hands it back to the shell that ran it). */
+    get mayBePhysical(): boolean;
+    /** Stop placing anything from segment `at` on: the reachable bases (and a target's floor spellings) become the deny floor. */
+    lose(at: number, reachable: readonly BaseCandidate[], floorTargets?: readonly string[]): void;
+    /** Apply segment `si`'s move. */
+    shift(si: number, at: ShiftAt, ctx: WorkdirContext): void;
+    /** Where one candidate goes: the places (the CDPATH entries a bare target is searched through, then the target itself),
+     *  each with the `PWD`, `OLDPWD` and stack the move leaves — or `lost`. */
+    private movedFrom;
+}
+/** Does bash search `CDPATH` for this `cd` target: not an absolute one, not `.` / `..`, not one starting `./` / `../`? */
+export declare function searchesCdPath(dir: string): boolean;
+/** The base shift of a `cd` / `pushd` / `popd` / `dirs` segment, read off its arguments as the program receives them (and
+ *  the move the plan reports for it: a `cd` target, or `unmodelled` for a stack move it cannot name), or `undefined` for
+ *  another program. `targetOf` turns the target word into its candidate (and records it as a read where the caller does). */
+export declare function baseShiftOf(program: string, args: readonly Read[], targetOf: (r: Read) => Bare): {
+    shift: BaseShift;
+    reported?: Bare | "home" | "previous" | "unmodelled";
+} | undefined;
+/** May this text move the base of the shell that runs it: a program of the closed set or one running text in this shell,
+ *  a computed program word, a call into one of `functions` — or text the lexer cannot read? */
+export declare function textMayMove(text: string, functions: ReadonlySet<string>): boolean;
+/** Does this text turn the physical mode on in the shell that runs it? An `eval` text that does is no text to skip. */
+export declare function textSetsPhysical(text: string): boolean;
+/** The table a `cd` / `pushd` reads `HOME`, `CDPATH` and `OLDPWD` from: the segment's own, with each prefix assignment in
+ *  front of the builtin (`HOME=/ cd`, `CDPATH=/ cd usr`) holding its value there — it is in the builtin's environment. A
+ *  prefix value naming an earlier prefix's name (`HOME=/ CDPATH=$HOME cd usr`) reads it as bash 5 does (the earlier
+ *  assignment applied) and as bash 3.2 does (the value before the command): both. */
+export declare function withCommandEnvironment(table: BindingTable, argv: readonly LexedWord[]): CommandTable;
+/** Does this text call one of `functions` (a program word naming one) — or is it text the lexer cannot read? */
+export declare function textCalls(text: string, functions: ReadonlySet<string>): boolean;
+/** May a segment with these words move the base ({@link textMayMove})? */
+export declare function segmentMayMove(argv: readonly LexedWord[], functions: ReadonlySet<string>): boolean;
+/** What the walk reads of a whole text before it walks it: the text's functions (the names a program word can be one of;
+ *  whether it IS one at a segment is the binding thread's answer, `callAt`); per segment whether it may move the base
+ *  ({@link segmentMayMove}), may call a function, runs code bodies later (`trap`, `alias`, …), turns on the physical mode
+ *  (`set -P`, `set -o physical`); whether a function body may move the base; where `cdable_vars` goes on. */
+export interface TextMoves {
+    readonly functions: ReadonlySet<string>;
+    /** The names whose bodies the plan has not read (an `eval` text defined them). */
+    readonly unread: ReadonlySet<string>;
+    readonly mayMove: readonly boolean[];
+    /** Segment `si` may call a function (read before the walk, to bound where bodies run). */
+    readonly mayCallAt: readonly boolean[];
+    /** Segment `si` may run a function body: it may call one, hands a code body to run later, or runs text the plan does not read. */
+    readonly runsBodyAt: readonly boolean[];
+    readonly bodiesAt: readonly (readonly string[])[];
+    readonly physicalAt: readonly boolean[];
+    readonly cdableFrom: number;
+    readonly bodyMoves: boolean;
+    /** The function segment `si`'s program word names where the walk stands (`table`) — {@link functionCallOf}. */
+    callAt(si: number, table: BindingTable): FunctionCall | undefined;
+    /** The segment may call a function a literal `eval` text defined: its body is not read — it may move the base and bind any name. */
+    callsUnread(si: number, table: BindingTable): boolean;
+    /** The segment runs a body that may move the base where the walk cannot follow it: a call when a body may move or whose body is not read, a code body that may move or call one. */
+    losesBaseAt(si: number, table: BindingTable): boolean;
+}
+export declare function textMovesOf(defined: ReadonlySet<string>, argvs: readonly (readonly LexedWord[])[], inFunctionBody: (si: number) => boolean, inherited?: {
+    readonly functions: ReadonlySet<string>;
+    readonly unread: ReadonlySet<string>;
+}): TextMoves;

package/dist/tools/fs/shell-read-workdir.js

@@ -0,0 +1,281 @@
+import { argvOf, lexShell } from "../../shell/lex.js";
+import { shellWordsOf } from "../../shell/shell-words.js";
+import { resolveOperandLexically } from "./bash-readonly-classifier.js";
+import { readProgramPosition } from "./bash-program-position.js";
+import { valueOf } from "./shell-read-bindings.js";
+import { evalDefinedFunctions, functionCallOf } from "./shell-read-functions.js";
+import { codeBodies } from "./shell-reentry-text.js";
+import { isAbsoluteForFamily } from "./safety.js";
+const TEXT_RUNNING_PROGRAMS = new Set(["eval", "source", "."]);
+const BASE_CANDIDATE_MAX = 256;
+const tableSays = (name, at, ctx) => ctx.textBinds(name) || at.table.commandSets.has(name);
+export class WorkdirThread {
+    readable;
+    candidates;
+    lostAt = false;
+    floors;
+    physical;
+    movedAt = -1;
+    constructor(start, readable, startsPhysical = false) {
+        this.readable = readable;
+        this.physical = startsPhysical;
+        this.lostAt = start === "unmodelled";
+        this.candidates = start === "unmodelled" ? [] : start.map((c) => (typeof c === "string" ? { base: c, skippedCd: -1, ...(readable && isAbsoluteForFamily("own", c) ? { pwd: c } : {}), dirStack: [] } : { ...c, skippedCd: -1 }));
+    }
+    get lost() {
+        return this.lostAt;
+    }
+    get floorBases() {
+        return this.floors;
+    }
+    reachable(andRunStart) {
+        return this.candidates.filter((c) => c.skippedCd < andRunStart);
+    }
+    end() {
+        return this.lostAt ? "unmodelled" : this.candidates;
+    }
+    where(andRunStart) {
+        if (this.lostAt || !this.readable)
+            return { PWD: "unknown", OLDPWD: "unknown", movedAt: this.movedAt };
+        const reachable = this.reachable(andRunStart);
+        const values = (pick) => {
+            const out = new Set();
+            for (const c of reachable) {
+                const v = pick(c);
+                if (v === undefined)
+                    return "unknown";
+                out.add(v);
+            }
+            return [...out].map((spelled) => ({ spelled }));
+        };
+        return { PWD: values((c) => c.pwd), OLDPWD: values((c) => c.old), movedAt: this.movedAt };
+    }
+    setPhysical() {
+        this.physical = true;
+    }
+    get mayBePhysical() {
+        return this.physical;
+    }
+    lose(at, reachable, floorTargets = []) {
+        this.movedAt = Math.max(this.movedAt, at);
+        this.lostAt = true;
+        this.floors ??= [...new Set([...reachable.map((c) => c.base), ...floorTargets])];
+    }
+    shift(si, at, ctx) {
+        if (this.lostAt) {
+            if (this.floors !== undefined && this.floors.length > 0)
+                this.floors = [...new Set([...this.floors, ...floorOf(at.shift, this.reachable(at.andRunStart), ctx)])];
+            return;
+        }
+        this.movedAt = si;
+        const reachable = this.reachable(at.andRunStart);
+        const s = at.shift;
+        if (s.kind === "lost")
+            return this.lose(si, reachable);
+        if (s.kind === "stack") {
+            this.candidates = this.candidates.map(({ dirStack: _, ...c }) => c);
+            return;
+        }
+        const branched = [];
+        for (const c of this.candidates) {
+            if (c.skippedCd < at.andRunStart) {
+                const moved = this.movedFrom(c, at, ctx);
+                if (moved === "lost")
+                    return this.lose(si, reachable, floorOf(s, reachable, ctx));
+                for (const m of moved)
+                    branched.push({ ...m, skippedCd: c.skippedCd });
+            }
+            branched.push({ ...c, skippedCd: at.provable ? si : c.skippedCd });
+        }
+        const byKey = new Map();
+        for (const c of branched) {
+            const key = JSON.stringify([c.base, c.pwd, c.old, c.dirStack]);
+            const prior = byKey.get(key);
+            if (prior === undefined || c.skippedCd < prior.skippedCd)
+                byKey.set(key, c);
+        }
+        const next = [...byKey.values()];
+        if (next.length > BASE_CANDIDATE_MAX)
+            this.lose(si, reachable);
+        else
+            this.candidates = next;
+    }
+    movedFrom(c, at, ctx) {
+        const s = at.shift;
+        if (s.kind === "eval") {
+            const ran = ctx.evalEnd(s.text, c, at.table);
+            if (ran.physical)
+                this.physical = true;
+            return ran.end === "unmodelled" ? "lost" : ran.end.map((e) => (this.physical ? withoutPwd(e) : e));
+        }
+        const old = tableSays("PWD", at, ctx) ? {} : c.pwd !== undefined ? { old: c.pwd } : {};
+        const land = (base, physical, stack) => ({ base, skippedCd: c.skippedCd, ...(physical || this.physical || !this.readable ? {} : { pwd: base }), ...old, ...(stack !== undefined ? { dirStack: stack } : {}) });
+        if (s.kind === "swap" || s.kind === "pop") {
+            const top = c.dirStack?.[0];
+            if (top === undefined)
+                return "lost";
+            return [land(top, false, s.kind === "swap" ? [c.base, ...c.dirStack.slice(1)] : c.dirStack.slice(1))];
+        }
+        if (s.kind !== "cd")
+            return "lost";
+        const stack = s.push === true ? (c.dirStack === undefined ? undefined : [c.base, ...c.dirStack]) : c.dirStack;
+        const targets = targetsOf(s.target, c, at, ctx);
+        if (targets === "lost")
+            return "lost";
+        const out = [];
+        for (const t of targets) {
+            if ((s.physical || this.physical || c.pwd === undefined) && t.split("/").includes(".."))
+                return "lost";
+            const moved = resolveOperandLexically(c.base, t, ctx.homeDir);
+            if (moved === undefined)
+                return "lost";
+            out.push(land(moved, s.physical, stack));
+        }
+        return out;
+    }
+}
+const withoutPwd = ({ pwd: _, ...c }) => c;
+function floorOf(s, reachable, ctx) {
+    if (s.kind !== "cd")
+        return [];
+    if (s.target === "home")
+        return ctx.homeDir !== undefined ? [ctx.homeDir] : [];
+    if (typeof s.target === "string")
+        return [];
+    const target = s.target;
+    return [...(target.floorSpelled !== undefined ? [target.floorSpelled] : []), ...(target.expands === false ? reachable.flatMap((c) => resolveOperandLexically(c.base, target.spelled, ctx.homeDir) ?? []) : [])];
+}
+function targetsOf(target, c, at, ctx) {
+    if (target === "home")
+        return settledValues(at.table.stateOf("HOME"));
+    if (target === "previous")
+        return tableSays("OLDPWD", at, ctx) ? settledValues(at.table.stateOf("OLDPWD")) : c.old === undefined ? "lost" : [c.old];
+    if (target.expands !== false)
+        return "lost";
+    const dir = target.spelled;
+    if (!searchesCdPath(dir))
+        return [dir];
+    if (at.cdable && /^[A-Za-z_][A-Za-z0-9_]*$/.test(dir))
+        return "lost";
+    const cdPath = settledValues(at.table.stateOf("CDPATH"));
+    if (cdPath === "lost")
+        return "lost";
+    const entries = cdPath.flatMap((v) => (v === "" ? [] : v.split(":")));
+    return [...new Set([...entries.map((e) => (e === "" ? dir : `${e.replace(/\/+$/, "")}/${dir}`)), dir])];
+}
+export function searchesCdPath(dir) {
+    return dir !== "" && !isAbsoluteForFamily("own", dir) && !/^\.\.?(?:\/|$)/.test(dir) && !dir.startsWith("~");
+}
+function settledValues(state) {
+    if (state === "unknown" || state.some((v) => v.glob === true))
+        return "lost";
+    return state.map((v) => v.spelled);
+}
+export function baseShiftOf(program, args, targetOf) {
+    if (program === "cd") {
+        let physical = false;
+        let at = 0;
+        for (; at < args.length; at++) {
+            const w = args[at].folded;
+            if (w === "--") {
+                at++;
+                break;
+            }
+            if (!w.startsWith("-") || w === "-")
+                break;
+            for (const letter of w.slice(1)) {
+                if (letter === "P")
+                    physical = true;
+                else if (letter === "L")
+                    physical = false;
+                else if (letter !== "e" && letter !== "@")
+                    return { shift: { kind: "lost" }, reported: "unmodelled" };
+            }
+        }
+        if (at >= args.length)
+            return { shift: { kind: "cd", target: "home", physical }, reported: "home" };
+        if (args[at].folded === "-")
+            return { shift: { kind: "cd", target: "previous", physical }, reported: "previous" };
+        const target = targetOf(args[at]);
+        return { shift: { kind: "cd", target, physical }, reported: target };
+    }
+    if (shellWordsOf("stack_mover").has(program)) {
+        const words = args.map((a) => a.folded);
+        if (words.some((w) => w === "-n"))
+            return { shift: { kind: "stack" }, reported: "unmodelled" };
+        if (words.some((w) => /^[+-]\d+$/.test(w)) || words.some((w) => w.startsWith("-") && w !== "--"))
+            return { shift: { kind: "lost" }, reported: "unmodelled" };
+        const operand = args.find((a) => a.folded !== "--");
+        if (program === "popd")
+            return { shift: operand === undefined ? { kind: "pop" } : { kind: "lost" }, reported: "unmodelled" };
+        if (operand === undefined)
+            return { shift: { kind: "swap" }, reported: "unmodelled" };
+        return { shift: { kind: "cd", target: targetOf(operand), physical: false, push: true }, reported: targetOf(operand) };
+    }
+    if (shellWordsOf("stack_editor").has(program) && args.some((a) => a.folded.startsWith("-") || a.folded.startsWith("+")))
+        return { shift: { kind: "stack" } };
+    return undefined;
+}
+export function textMayMove(text, functions) {
+    const lexed = lexShell(text);
+    if ("parseFailure" in lexed)
+        return true;
+    return lexed.segments.some((s) => segmentMayMove(argvOf(s), functions));
+}
+const programOf = (argv) => {
+    const pos = readProgramPosition(argv);
+    return pos.program === undefined ? undefined : { name: pos.program.basename, args: argv.slice(pos.program.index + 1).map((w) => w.folded) };
+};
+const setsPhysical = (p) => p?.name === "set" && p.args.some((a, k) => /^-[A-Za-z]*P/.test(a) || (a === "-o" && p.args[k + 1] === "physical"));
+export function textSetsPhysical(text) {
+    const lexed = lexShell(text);
+    return !("parseFailure" in lexed) && lexed.segments.some((s) => setsPhysical(programOf(argvOf(s))));
+}
+export function withCommandEnvironment(table, argv) {
+    const overlay = new Map();
+    const overlaid = () => ({ ...table, stateOf: (name) => overlay.get(name) ?? table.stateOf(name) });
+    for (const k of readProgramPosition(argv).assignments) {
+        const a = argv[k].assignment;
+        if (a === undefined)
+            continue;
+        if (a.op !== "=" || a.subscript !== undefined || a.form !== "scalar" || a.value.unresolved !== undefined) {
+            overlay.set(a.name, "unknown");
+            continue;
+        }
+        const before = valueOf({ pieces: a.value.pieces }, table, true);
+        const ordered = valueOf({ pieces: a.value.pieces }, overlaid(), true);
+        overlay.set(a.name, before === "unknown" || ordered === "unknown" ? "unknown" : [...before, ...ordered.filter((v) => !before.some((b) => b.spelled === v.spelled))]);
+    }
+    return { ...overlaid(), commandSets: new Set(overlay.keys()) };
+}
+export function textCalls(text, functions) {
+    const lexed = lexShell(text);
+    if ("parseFailure" in lexed)
+        return true;
+    return lexed.segments.some((s) => functionCallOf(argvOf(s), functions) !== undefined);
+}
+export function segmentMayMove(argv, functions) {
+    const pos = readProgramPosition(argv);
+    if (pos.program === undefined)
+        return false;
+    const word = argv[pos.program.index];
+    return shellWordsOf("base_mover").has(pos.program.basename) || TEXT_RUNNING_PROGRAMS.has(pos.program.basename) || functionCallOf(argv, functions) !== undefined || word.pieces.some((p) => p.expansion !== undefined || p.literal === undefined);
+}
+export function textMovesOf(defined, argvs, inFunctionBody, inherited) {
+    const unread = new Set([...evalDefinedFunctions(argvs), ...(inherited?.unread ?? [])]);
+    const functions = new Set([...defined, ...unread, ...(inherited?.functions ?? [])]);
+    const programs = argvs.map(programOf);
+    const mayMove = argvs.map((argv) => segmentMayMove(argv, functions));
+    const bodyMoves = mayMove.some((m, si) => m && inFunctionBody(si));
+    const bodiesAt = programs.map((p) => (p === undefined ? [] : codeBodies(p.name, p.args)));
+    const mayCallAt = argvs.map((argv) => functionCallOf(argv, functions) !== undefined);
+    const runsTextAt = argvs.map((argv) => { const pos = readProgramPosition(argv); const word = pos.program === undefined ? undefined : argv[pos.program.index]; return word !== undefined && (["eval", "source", "."].includes(pos.program.basename) || word.pieces.some((p) => p.expansion !== undefined || p.literal === undefined)); });
+    const callAt = (si, table) => functionCallOf(argvs[si], functions, (name) => table.functionState(name));
+    const callsUnread = (si, table) => functionCallOf(argvs[si], unread, (name) => table.functionState(name)) !== undefined;
+    return {
+        functions, unread, mayMove, mayCallAt, runsBodyAt: mayCallAt.map((c, si) => c || runsTextAt[si] || bodiesAt[si].length > 0), bodiesAt, bodyMoves, callAt, callsUnread,
+        physicalAt: programs.map(setsPhysical),
+        cdableFrom: programs.findIndex((p) => p?.name === "shopt" && p.args.includes("-s") && p.args.includes("cdable_vars")),
+        losesBaseAt: (si, table) => (callAt(si, table) !== undefined && bodyMoves) || callsUnread(si, table) || bodiesAt[si].some((b) => bodyMoves || textMayMove(b, functions)),
+    };
+}

package/dist/tools/fs/shell-read-write-targets.d.ts

@@ -5,7 +5,8 @@
  * writes, the operands an option made edited in place, a copy's destination and its children, an in-place edit's
  * backups), at the seats the role and the selected options name ({@link WriteSeat}: the directory entry, or where the
  * path lands). The establisher (`shell-read-establish.ts`) places what this module names; the judge reads the result
- * on the deny table's write face. No table of programs or options lives here: what a program writes is its row's.
+ * on the write face (the write deny rows, then the write roots). No table of programs or options lives here: what a
+ * program writes is its row's.
  */
 import type { ReadCandidate, ShellReadSegment } from "./shell-read-plan.js";
 import { type WriteSeat } from "./program-read-model.js";
@@ -47,5 +48,7 @@ export interface JudgedCandidate {
 }
 /** Every candidate a segment hands the judge: its reads minus the write targets, plus its `cd` target (the plan already
  *  lists it among the reads), plus its WRITE targets for the write face ({@link writeTargetsOf}), plus the deny-floor
- *  shadow of every unplaced home word ({@link denyFloorShadowsOf}) on both faces. */
+ *  shadow of every unplaced home word ({@link denyFloorShadowsOf}) on both faces. A word the program only writes keeps
+ *  its read copy for the read deny rows alone (`denyOnly`): whether it lands inside the write roots — or cannot be placed
+ *  at all — is the write face's question, never a read's. */
 export declare function judgedCandidatesOf(segment: ShellReadSegment): readonly JudgedCandidate[];

package/dist/tools/fs/shell-read-write-targets.js

@@ -29,6 +29,7 @@ function writeOwnersOf(segment) {
 }
 function writeTargetsOf(segment) {
     const out = [];
+    const writeOnly = new Set();
     const write = (c, seats, written, child, onlyIfExists) => void out.push({ candidate: { ...c, face: "write" }, ...(seats !== undefined ? { seats } : {}), ...(written !== undefined ? { written } : {}), ...(child === true ? { child } : {}), ...(onlyIfExists !== undefined ? { onlyIfExists } : {}) });
     for (const r of segment.redirects)
         if (r.direction === "out" && r.target !== undefined)
@@ -48,9 +49,12 @@ function writeTargetsOf(segment) {
             continue;
         const placed = owners.filter((o) => o.words.some((w) => w.raw === c.raw));
         const fallback = placed.length === 0 ? owners.filter((o) => o.program) : [];
+        let only = placed.length > 0;
         for (const o of [...placed, ...fallback]) {
-            if (o.readings.length === 0)
+            if (o.readings.length === 0) {
+                only = false;
                 continue;
+            }
             const at = new Set(o.words.flatMap((w, i) => (w.raw === c.raw ? [i] : [])));
             const roles = [];
             let readings = 0;
@@ -64,8 +68,11 @@ function writeTargetsOf(segment) {
                 readings += 1;
                 unexplained ||= unplaced;
             }
-            if (roles.length === 0)
+            if (roles.length === 0) {
+                only = false;
                 continue;
+            }
+            only &&= !unexplained && readings === o.all.length && roles.every((role) => role.effect !== "edit-in-place" && role.writtenAt === undefined);
             const stated = roles.some((role) => (o.override ?? role.seats) !== undefined);
             const seats = stated ? [...new Set(roles.flatMap((role) => o.override ?? role.seats ?? ["landing"]))] : undefined;
             const written = unexplained || roles.some((role) => role.writtenAt === undefined) ? undefined : [...new Set(roles.flatMap((role) => role.writtenAt ?? []))];
@@ -74,13 +81,15 @@ function writeTargetsOf(segment) {
             if (roles.some((role) => role.effect === "edit-in-place") && c.expands === false)
                 edited.set(o, [...(edited.get(o) ?? []), { candidate: c, ...(speculative !== undefined ? { onlyIfExists: speculative } : {}) }]);
         }
+        if (only)
+            writeOnly.add(c);
     }
     for (const o of owners) {
         for (const c of copyDestinationChildren(segment, o.words, o.readings))
             write(c, ["landing", "entry"], undefined, true);
         out.push(...backupTargetsOf(edited.get(o) ?? [], o.readings, o.override));
     }
-    return out;
+    return { targets: out, writeOnly };
 }
 function backupTargetsOf(edited, readings, override) {
     const suffixes = [...new Set(readings.flatMap((r) => r.suffixes))];
@@ -114,8 +123,8 @@ function copyDestinationChildren(segment, words, readings) {
     return [...children.values()];
 }
 export function judgedCandidatesOf(segment) {
-    const reads = segment.reads.filter((c) => c.provenance !== "write_redirect_target");
-    const writes = writeTargetsOf(segment);
+    const { targets: writes, writeOnly } = writeTargetsOf(segment);
+    const reads = segment.reads.flatMap((c) => (c.provenance === "write_redirect_target" ? [] : [writeOnly.has(c) ? { ...c, denyOnly: true } : c]));
     const plain = (cs) => cs.map((candidate) => ({ candidate }));
     return [...plain(reads), ...plain(denyFloorShadowsOf(reads)), ...writes, ...plain(denyFloorShadowsOf(writes.map((w) => w.candidate)))];
 }

package/dist/tools/fs/shell-reentry-text.d.ts

@@ -120,13 +120,14 @@ export interface LaunchedSpelling {
  * characters escaped and its pattern characters bare ({@link launchedSpellingOf}). A word whose field the reader does not
  * know is handed AS WRITTEN: the launched shell re-reads the expansion with the command line's quoting, so the word stays
  * one argument (an unknown there) and its neighbours stay theirs (`"#$Y" d` is never `#$Y d`). Any other launcher hands a
- * word's text as `spell.word` spells it. One argv, as a list of the one.
+ * word's text as `spell.word` spells it.
  */
-export declare function spellLaunched(argv: readonly LexedWord[], args: readonly LaunchedArg[], spell: LaunchedSpelling): string[][];
+export declare function spellLaunched(argv: readonly LexedWord[], args: readonly LaunchedArg[], spell: LaunchedSpelling): string[];
 /** The argv index of the SCRIPT FILE a shell runs where its argv carries no text ({@link scriptSourceOf}). */
 export declare function scriptFileAt(basename: string, args: readonly string[]): number | undefined;
 /** One text that may arrive on a segment's standard input: `from` = its source as written (a here-document's body,
- *  `<<<WORD`, `<FILE`, `<&N`, the segment the pipe comes from); `literal` = the text, where the command spells it. */
+ *  `<<<WORD`, `<FILE`, `<&N`, the segment the pipe comes from); `literal` = the text, where the command spells it — a
+ *  here-document or here-string written in the command; never a pipe's text, which a program PRODUCES. */
 export interface StdinText {
     readonly from: string;
     readonly literal?: string;
@@ -137,6 +138,3 @@ export interface StdinText {
  *  pipe or the input of the group it stands in, the input of the shell running its text) unless one of those three
  *  replaces it. */
 export declare function stdinTextsOf(segment: LexedSegment, fed: readonly StdinText[]): StdinText[];
-/** What one segment (its argv) writes into the pipe after it: the text a printer spells ({@link printedText}) when its
- *  program word and every argument are literal, else only the segment as written. */
-export declare function pipedTextOf(segment: LexedSegment, argv: readonly LexedWord[]): StdinText;

package/dist/tools/fs/shell-reentry-text.js

@@ -1,6 +1,6 @@
 import { literalHeredocBody, literalTextOf } from "../../shell/lex.js";
 import { programBasename, readProgramPosition } from "./bash-program-position.js";
-import { implementationRejects, implementationsOf, printedText, programRow, readArgRoles, selectedOptions, targetUserOf } from "./program-read-model.js";
+import { implementationRejects, implementationsOf, programRow, readArgRoles, selectedOptions, targetUserOf } from "./program-read-model.js";
 import { namesStandardInput } from "./safety.js";
 export function codeBodies(basename, args) {
     const row = programRow(basename);
@@ -167,8 +167,7 @@ export function launchedInput(argv, pos, spell) {
         if (line === undefined && c.program !== undefined && "at" in c.program && c.program.from === undefined)
             programWords.push(c.program.at);
         const words = c.args.map((x) => ("at" in x && x.from === undefined ? x.at : undefined));
-        const args = asArgs(c.args);
-        return asTexts(c.args).map((texts, i) => ({ shell, texts, args: args[i], words, ...(c.as !== undefined ? { as: c.as } : {}) }));
+        return [{ shell, texts: asTexts(c.args), args: asArgs(c.args), words, ...(c.as !== undefined ? { as: c.as } : {}) }];
     });
     return { shells, programWords, lines: [...lines] };
 }
@@ -186,7 +185,7 @@ export function spellLaunched(argv, args, spell) {
         const values = spell.values?.(k);
         return values?.length === 1 ? launchedSpellingOf(values[0]) : argv[k].raw;
     };
-    return [args.map((a) => ("fixed" in a ? a.fixed : "at" in a ? spell.word(a.at, a.from ?? 0) : a.joined.map((k) => (a.escaped === true ? field(k) : spell.word(k, 0))).join(" ")))];
+    return args.map((a) => ("fixed" in a ? a.fixed : "at" in a ? spell.word(a.at, a.from ?? 0) : a.joined.map((k) => (a.escaped === true ? field(k) : spell.word(k, 0))).join(" ")));
 }
 export function scriptFileAt(basename, args) {
     const row = programRow(basename);
@@ -219,10 +218,3 @@ export function stdinTextsOf(segment, fed) {
     }
     return replacesPipe ? out : [...fed, ...out];
 }
-export function pipedTextOf(segment, argv) {
-    const from = `${segment.text.trim()} |`;
-    const pos = readProgramPosition(argv);
-    const program = pos.program;
-    const literal = program === undefined || pos.refusal !== undefined || literalTextOf(argv[program.index].pieces) === undefined ? undefined : printedText(programRow(program.basename), argv.slice(program.index + 1).map((w) => literalTextOf(w.pieces)));
-    return literal === undefined ? { from } : { from, literal };
-}

package/dist/tools/task-list.d.ts

@@ -96,8 +96,7 @@ export interface TaskListStore {
 export declare function normalizeTaskShape<T>(item: T): T;
 export declare function assertJsonMetadata(value: unknown, path?: string): void;
 /**
- * RB-274 — the contract's `list` order, mirroring the CC-compat backend's `orderIds`
- * (`stores/cc/task-list-store.ts`): numeric ids ascending (CC's own task order), any non-numeric id
+ * RB-274 — the contract's `list` order: numeric ids ascending (CC's own task order), any non-numeric id
  * after them, lexicographically. Ties broken lexicographically so the comparator is total (and the
  * order therefore stable across repeated calls, which the contract also requires).
  */

package/dist/tools/web.js

@@ -67,7 +67,7 @@ function assessGrounding(text, bytes) {
     return { level: low ? "low" : "ok", textChars, bytes, textRatio: Math.round(textRatio * 1000) / 1000 };
 }
 function recoveryToolRuledOut(ctx, toolName) {
-    if (ctx.excludeTools?.includes(toolName) ?? false)
+    if (ctx.toolSelector !== undefined && !ctx.toolSelector.admits({ name: toolName }))
         return true;
     const deferred = ctx.deferTools?.includes(toolName) ?? false;
     const pinnedInline = ctx.alwaysLoadTools?.includes(toolName) ?? false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.48.0",
+  "version": "7.49.1",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -72,6 +72,7 @@
     "handoff:diff": "node scripts/dist-handoff-diff.mjs",
     "post-ship": "node scripts/post-ship.mjs",
     "gate:debts:rc": "node scripts/verify-debts.mjs --rc-gate",
+    "gate:rulings": "node scripts/rulings-gate.mjs --require-comms",
     "gate:error-surface": "node scripts/verify-error-surface.mjs",
     "gate:criteria": "node scripts/criteria-lint.mjs",
     "gate:reminder-literal": "node scripts/verify-reminder-literal.mjs",
@@ -89,7 +90,9 @@
     "gate:child-clamp-seats": "node scripts/verify-child-clamp-seats.mjs",
     "gate:spawn-sites": "node scripts/verify-spawn-sites.mjs",
     "gate:point-free-callbacks": "node scripts/verify-point-free-callbacks.mjs",
+    "gate:weak-identity": "node scripts/gate-weak-identity.mjs",
     "gate:docs-tool-names": "node scripts/verify-docs-tool-names.mjs",
+    "gate:credential-vocabulary": "node scripts/verify-credential-vocabulary.mjs",
     "gate:comment-ratio": "vitest run test/comment-ratio-ratchet.test.ts",
     "gate:negative-controls": "vitest run test/gate-negative-controls.test.ts",
     "gate:memory-ga": "node scripts/gate-memory-distillation-ga.mjs",