@sema-agent/core 7.55.0 → 7.57.0

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

@@ -1,45 +1,44 @@
-import { canonicalRootsOnce, observeEnvironment } from "./shell-read-environment.js";
+import { canonicalRootsOnce, isAbsence, observeEnvironment } from "./shell-read-environment.js";
 import { anchorSpelling, normalizeAbsPathLexically, pathFamilyOf } from "./safety.js";
 import { boundaryIsTheSandbox } from "../../core/remote-env.js";
 import { resolveOperandSpellings } from "./bash-readonly-classifier.js";
 import { judgedCandidatesOf, sedBackupNames } from "./shell-read-write-targets.js";
 import { movedReads, withHomeViews } from "./shell-read-identity.js";
 import { passesUnasked } from "./shell-read-device.js";
+import { compileFsGlob, fsGlobClass } from "./fs-glob.js";
 const GLOB_METACHAR_RE = /[*?[]/;
 export const MAX_GLOB_DIRS = 256;
 export const MAX_GLOB_MATCHES = 8192;
 const WRITE_LINK_HOPS = 32;
-function compileGlobSegment(pattern) {
+export function compileGlobSegment(pattern) {
     if (pattern.includes("\\"))
         return undefined;
-    let src = "";
+    const tokens = [];
     for (let i = 0; i < pattern.length; i++) {
         const ch = pattern[i];
         if (ch === "*") {
-            src += "[^/]*";
+            tokens.push({ kind: "star" });
         }
         else if (ch === "?") {
-            src += "[^/]";
+            tokens.push({ kind: "one" });
         }
         else if (ch === "[") {
-            const cls = parseBracketExpression(pattern, i);
-            if (cls === undefined)
-                src += "\\[";
+            const bracket = parseBracketExpression(pattern, i);
+            if (bracket === undefined)
+                tokens.push({ kind: "text", text: "[" });
             else {
-                src += cls.source;
-                i = cls.end;
+                const cls = fsGlobClass(bracket.source);
+                if (cls === undefined)
+                    return undefined;
+                tokens.push({ kind: "class", class: cls });
+                i = bracket.end;
             }
         }
         else {
-            src += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            tokens.push({ kind: "text", text: ch });
         }
     }
-    try {
-        return new RegExp(`^${src}$`, "s");
-    }
-    catch {
-        return undefined;
-    }
+    return compileFsGlob(tokens, "start");
 }
 function parseBracketExpression(pattern, start) {
     let i = start + 1;
@@ -248,7 +247,7 @@ function establishLegOver(seen, readRoots) {
                     return { value: canon.value, exact: true };
                 return { value: [canon.value.replace(TRAILING_SEP, ""), ...[...tail].reverse()].join("/"), exact: false, missing: allAbsent };
             }
-            if (canon.error.code !== "not_found" && canon.error.code !== "not_directory")
+            if (!isAbsence(canon.error.code))
                 allAbsent = false;
             tail.push(parts.pop());
         }
@@ -339,7 +338,7 @@ function establishLegOver(seen, readRoots) {
                     return { unverifiable: `"${dir}" cannot be resolved to verify what "${seg}" would expand to` };
                 const listed = await env.listDir(canonDir?.value ?? dir, signal);
                 if (!listed.ok) {
-                    if (listed.error.code === "not_found" || listed.error.code === "not_directory")
+                    if (isAbsence(listed.error.code))
                         continue;
                     return { unverifiable: `"${dir}" cannot be enumerated to verify what "${seg}" would expand to (${listed.error.code})` };
                 }
@@ -414,7 +413,7 @@ function establishLegOver(seen, readRoots) {
                 return parent.missing === true ? name : undefined;
             const entry = await env.fileInfo(joinUnder(parent.value, leaf), signal);
             if (!entry.ok)
-                return entry.error.code === "not_found" || entry.error.code === "not_directory" ? name : undefined;
+                return isAbsence(entry.error.code) ? name : undefined;
             if (entry.value.kind !== "symlink")
                 return name;
             const link = await env.readLink?.(joinUnder(parent.value, leaf), signal);

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

@@ -1,18 +1,21 @@
-/**
- * The pre-spawn identity comparison: which established reads of one plan resolve somewhere else now.
- *
- * Compared PER CANDIDATE, never as one pooled set of targets: a candidate is keyed by where it stands in the plan
- * (segment, nested plan) and by what it is (deny-only or a read, provenance, spelling, expansion, raw word), and its
- * set of established targets is compared with the same candidate's set from the re-establishment. A pooled set let
- * one candidate's targets hide another's move — `head linkx` retargeted onto a path some other word's pattern already
- * matched, or onto a home shadow's target, left the pool unchanged and the call was admitted unjudged.
- */
 import type { EstablishedPlan } from "./shell-read-establish.js";
 import type { ObservedEnvironment } from "./shell-read-environment.js";
 import type { EstablishedRead } from "./shell-read-judge.js";
 import { type HomeViewsCarrier } from "./read-deny-home.js";
 /** Every read of either establishment whose candidate's settled target set differs between the two. */
 export declare function movedReads(previous: EstablishedPlan, again: EstablishedPlan): EstablishedRead[];
+/** One read candidate's landing: its key and where it settled, each as a sha256 hex digest (the key's raw tuple joins on
+ *  NUL and follows the command's length; a pattern lands on up to thousands of entries), with the raw word and the
+ *  settled targets kept for the sentence that names a moved one. */
+export interface ReadLanding {
+    readonly key: string;
+    readonly landing: string;
+    readonly raw: string;
+    readonly targets: readonly string[];
+}
+/** Every read candidate of the establishment (nested plans included) with where it landed, in plan order. A candidate
+ *  that settled nowhere (a lexical or unestablishable read) lands on the empty set — placed later, that is a move. */
+export declare function readLandingsOf(e: EstablishedPlan): ReadLanding[];
 /**
  * The establishment with every read that landed carrying its HOME VIEW (read-deny-home.ts) among its spellings, nested
  * plans included: the deny judge then places a home-anchored row wherever the target IS below the home, whatever it is

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

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { homeViewsOf } from "./read-deny-home.js";
 export function movedReads(previous, again) {
     const before = targetsByCandidate(previous);
@@ -6,12 +7,19 @@ export function movedReads(previous, again) {
     for (const key of new Set([...before.keys(), ...after.keys()])) {
         const b = before.get(key);
         const a = after.get(key);
-        if (b !== undefined && a !== undefined && sameTargets(b.targets, a.targets))
+        if (b !== undefined && a !== undefined && landingOf(b.targets) === landingOf(a.targets))
             continue;
         changed.push(...(b?.reads ?? []), ...(a?.reads ?? []));
     }
     return changed.filter((r) => r.target !== undefined);
 }
+export function readLandingsOf(e) {
+    return [...targetsByCandidate(e)].map(([key, l]) => ({ key: digest(key), landing: landingOf(l.targets), raw: l.reads[0]?.candidate.raw ?? "", targets: [...l.targets].sort() }));
+}
+function landingOf(targets) {
+    return digest(JSON.stringify([...targets].sort()));
+}
+const digest = (s) => createHash("sha256").update(s, "utf8").digest("hex");
 function targetsByCandidate(e) {
     const out = new Map();
     const walk = (p, at) => {
@@ -35,9 +43,6 @@ function targetsByCandidate(e) {
     walk(e, "");
     return out;
 }
-function sameTargets(a, b) {
-    return a.size === b.size && [...a].every((t) => b.has(t));
-}
 export async function withHomeViews(door, placed, established, signal) {
     const views = homeViewsOf(door.fs, placed, signal);
     const unread = [];

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

@@ -1,14 +1,14 @@
 import { expansionsInHeredocBody, lexShell, PARSE_FAILURE_SENTENCE, substitutionsInHeredocBody, literalTextOf, literalTildeSpelling, parameterRereadsValue, UNRESOLVED_SENTENCE, } from "../../shell/lex.js";
 import { programTextOf, readOfText, readsOf, rewritten, segmentReadingsOf, settledFieldsOf, spelledWithHome, unreadableSentenceOf } from "./shell-read-word.js";
 import { assignmentArithmetic, bare, listedVerbCandidates, pathSubcommandOf, programTextSentence, pushAssignment, roleReads, subscriptOnly, unlistedWords } from "./shell-read-argv.js";
-import { ARITHMETIC_TEST_OPERATORS, BindingThread, arithmeticSubstitutions, isArithmeticCommand, bindingEffectOf, joinRebound, loopListHeadAt, namesBoundIn, parameterBodySubstitutions, projectSegment, valueOf, } from "./shell-read-bindings.js";
+import { ARITHMETIC_TEST_OPERATORS, BindingThread, arithmeticSubstitutions, inheritedFunctionsOf, inheritedExportedFunctions, isArithmeticCommand, bindingEffectOf, joinRebound, loopListHeadAt, namesBoundIn, parameterBodySubstitutions, projectSegment, valueOf, } from "./shell-read-bindings.js";
 import { commandEnvironmentNames, isShellSyntaxWord, programBasename, programPositionRunsShell, readProgramPosition, shellScanDeclineOf, } from "./bash-program-position.js";
 import { WorkdirThread, baseShiftOf, textCalls, textMayMove, textMovesOf, textSetsPhysical, withCommandEnvironment } from "./shell-read-workdir.js";
 import { POLL_LOOP_MAX_BEATS, attachedOptionPayloads, resolveOperandLexically, isPathShapedToken, programTextSlotFiles, } from "./bash-readonly-classifier.js";
 import { BLOCK_WORD_NAMES, commandLineOf, commandLineOptionSpellings, declaredAttributes, isDeclarationBuiltin, isInertBuiltin, launcherOptionPathRole, launcherOptionStep, readOptionRole, programLanguageOf, programTextOpensOf, selectedOptions, movesBaseByStack, opensNoOperand, programDelivery, programRow, readArgRoles, runsShellText, } from "./program-read-model.js";
 import { shellWordsOf } from "../../shell/shell-words.js";
 import { isAbsoluteForFamily } from "./safety.js";
-import { codeBodies, launchedInput, reentryText, scriptFileAt, stdinTextsOf } from "./shell-reentry-text.js";
+import { codeBodies, launchedInput, reentersShell, reentryText, scriptFileAt, stdinTextsOf } from "./shell-reentry-text.js";
 import { heldAt, plannedOnce, rebasePlan, startedAt, stdinFeeds } from "./shell-read-start.js";
 import { markStandardDevices } from "./shell-read-device.js";
 export const READ_CANDIDATE_PROVENANCES = Object.freeze([
@@ -40,6 +40,7 @@ function planText(command, decl, depth, start, from) {
         return { plan: { segments: [], unreadable: PARSE_FAILURE_SENTENCE[lexed.parseFailure.reason], shape }, end: "unmodelled", physical: false };
     const unreadable = unreadableSentenceOf(lexed, command);
     const projected = lexed.segments.map((segment) => projectSegment(segment));
+    const exportedFunctions = inheritedFunctionsOf(projected, start?.exportedFunctions), exportedNames = new Set(exportedFunctions.keys());
     const named = projected.map((p, si) => bindingEffectOf(lexed.segments[si], p.argv, p, () => "unknown"));
     const boundHere = (name) => named.some((e) => e.all === "unknown" || e.bindings.some((b) => b.name === name));
     const boundAnywhere = (name) => boundHere(name) || start?.boundAnywhere(name) === true;
@@ -63,14 +64,15 @@ function planText(command, decl, depth, start, from) {
     }
     const names = new BindingThread(lexed.segments, named, initial, boundAnywhere, loopEndOf, start?.homeTouched === true, start?.inherited, start?.names);
     const laterStart = { initial: (name) => declared(name, boundAnywhere(name)), boundAnywhere, homeTouched: boundAnywhere("HOME"), inherited: names.inheritedAt() };
-    const nestedPlanner = (table, si) => (text, kind, at) => planShellReads(text, decl, depth + 1, kind === "substitution" ? { initial: (name) => table.stateOf(name), boundAnywhere, homeTouched: table.homeTouched, inherited: table.inherited, thread: heldThread(moves.functions), names: heldAt(table) } : startedAt(kind === "now" ? { ...laterStart, inherited: { ...laterStart.inherited, rebound: joinRebound(table.inherited.rebound, commandEnvironmentNames(projected[si].argv)) }, ...(readProgramPosition(projected[si].argv).program?.basename === "eval" ? { thread: heldThread(moves.unread), names: heldAt(table, names.functionBound()) } : {}) } : { ...laterStart, thread: heldThread(moves.functions, workdir.mayBePhysical || moves.physicalAt.some(Boolean)), names: names.heldAnywhere() }, at));
+    const nestedPlanner = (table, si) => (text, kind, at) => planShellReads(text, decl, depth + 1, kind === "substitution" ? { initial: (name) => table.stateOf(name), boundAnywhere, homeTouched: table.homeTouched, inherited: table.inherited, thread: heldThread(moves.functions), names: heldAt(table), ...(exportedFunctions.size > 0 ? { exportedFunctions } : {}) } : startedAt(kind === "now" ? { ...laterStart, inherited: { ...laterStart.inherited, rebound: joinRebound(table.inherited.rebound, commandEnvironmentNames(projected[si].argv)) }, ...(exportedFunctions.size > 0 ? { exportedFunctions } : {}), ...(readProgramPosition(projected[si].argv).program?.basename === "eval" ? { thread: heldThread(moves.unread), names: heldAt(table, names.functionBound()) } : exportedFunctions.size > 0 ? { thread: { physical: false, functions: exportedNames, unread: exportedNames }, names: inheritedExportedFunctions(exportedFunctions) } : {}) } : { ...laterStart, thread: heldThread(moves.functions, workdir.mayBePhysical || moves.physicalAt.some(Boolean)), names: names.heldAnywhere(), ...(exportedFunctions.size > 0 ? { exportedFunctions } : {}) }, at));
     const empty = lexed.segments.map((segment, si) => segmentIsEmpty(segment, projected[si]));
     const facts = projected.map(() => undefined);
     const tables = projected.map(() => undefined);
     const fedAt = stdinFeeds(lexed.segments, start?.stdin ?? [], (si) => [{ from: `${lexed.segments[si - 1].text.trim()} |` }]);
+    const inheritedFns = new Set([...(start?.exportedFunctions ?? [])].flatMap(([name, body]) => (body === "unread" ? [name] : [])));
     const factsAt = (si, table) => {
         tables[si] ??= table;
-        return (facts[si] ??= segmentFacts(lexed.segments[si], projected[si], decl, table, nestedPlanner(table, si), fedAt(si)));
+        return (facts[si] ??= segmentFacts(lexed.segments[si], projected[si], decl, table, nestedPlanner(table, si), fedAt(si), inheritedFns));
     };
     const basesOf = projected.map(() => new Set());
     const unmodelled = projected.map(() => false);
@@ -254,13 +256,13 @@ function segmentOpensNothing(f) {
     const inertProgram = program === undefined || (program.name === program.basename && isInertBuiltin(program.basename) && !(isDeclarationBuiltin(program.basename) && f.argv.slice(at + 1).some((w) => /^[-+]/.test(w.folded))));
     return inertProgram && f.argv.every((w) => !/[[\]$`]/.test(w.raw)) && f.nested.length === 0 && f.reentry === undefined && f.declines.length === 0 && f.launcherChain.length === 0 && f.redirects.every((r) => r.direction !== "in") && f.reads.every((c) => c.provenance === "env_assignment");
 }
-function segmentFacts(segment, p, decl, table, nestedPlan, fed) {
+function segmentFacts(segment, p, decl, table, nestedPlan, fed, inheritedFns = new Set()) {
     const targets = p.redirects.flatMap((r) => (r.target === undefined ? [] : [r.target]));
     const readings = segmentReadingsOf(p.argv, targets, table, decl.homeDir);
     if (readings.length === 1)
-        return readingFacts(segment, { ...p, argv: readings[0].argv }, decl, readings[0], nestedPlan, fed);
+        return readingFacts(segment, { ...p, argv: readings[0].argv }, decl, readings[0], nestedPlan, fed, inheritedFns);
     const once = plannedOnce(nestedPlan);
-    return readInSeveral(readings.map((reading) => readingFacts(segment, { ...p, argv: reading.argv }, decl, reading, once, fed)));
+    return readInSeveral(readings.map((reading) => readingFacts(segment, { ...p, argv: reading.argv }, decl, reading, once, fed, inheritedFns)));
 }
 function readInSeveral(each) {
     const first = each[0];
@@ -273,10 +275,10 @@ function readInSeveral(each) {
         readings: each.flatMap((f) => f.readings ?? [f]),
     };
 }
-function readingFacts(segment, p, decl, reading, nestedPlan, fed) {
+function readingFacts(segment, p, decl, reading, nestedPlan, fed, inheritedFns = new Set()) {
     const table = reading.table;
     const planner = (text, kind, at) => nestedPlan(text, kind, kind !== "substitution" ? { ...at, floors: reading.floors } : at);
-    const facts = segmentFactsRead(segment, p, decl, table, planner, fed, reading.reads);
+    const facts = segmentFactsRead(segment, p, decl, table, planner, fed, reading.reads, inheritedFns);
     const unresolvedRaw = new Set();
     for (const t of segment.tokens) {
         const w = t.kind === "word" ? t : t.kind === "redirect" ? t.target : undefined;
@@ -306,7 +308,7 @@ function readingFacts(segment, p, decl, reading, nestedPlan, fed) {
         ...(shift?.kind === "cd" && typeof shift.target !== "string" ? { shift: { ...shift, target: unsettle(shift.target) } } : {}),
     };
 }
-function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks) {
+function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks, inheritedFns = new Set()) {
     const nested = [];
     const elsewhere = new Set();
     const ctx = { table, reentered: [], programTextSeen: false };
@@ -378,10 +380,10 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks) {
         const once = plannedOnce(nestedPlan);
         const tail = (from) => ({ ...p, argv: p.argv.slice(coproc + from) });
         const background = (f) => ({ ...f, backgrounds: true, ...(f.readings !== undefined ? { readings: f.readings.map((g) => ({ ...g, backgrounds: true })) } : {}) });
-        const first = segmentFacts(segment, tail(1), decl, table, once, fed);
+        const first = segmentFacts(segment, tail(1), decl, table, once, fed, inheritedFns);
         if (toks.length < coproc + 3 || isShellSyntaxWord(p.argv[coproc + 1], RESERVED) || readProgramPosition(tail(2).argv.slice(0, 1)).refusal !== undefined)
             return background(first);
-        return background(readInSeveral([first, segmentFacts(segment, tail(2), decl, table, once, fed)]));
+        return background(readInSeveral([first, segmentFacts(segment, tail(2), decl, table, once, fed, inheritedFns)]));
     }
     const loop = loopShapeOf(p);
     if (loopListHeadAt(p.argv) !== undefined)
@@ -407,6 +409,8 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks) {
         declines.push(decline);
     const program = pos.program;
     const basename = program?.basename;
+    if (program?.name === basename && basename !== undefined && inheritedFns.has(basename) && !p.defines.includes(basename))
+        unread("runs a function this shell inherited from its environment, whose body is text the engine did not read");
     const listed = basename !== undefined && (decl.readers.has(basename) || basename === "cd");
     const verb = program === undefined ? undefined : { name: program.name, basename: program.basename, listed };
     for (const k of pos.assignments) {
@@ -511,7 +515,7 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks) {
         return done({ empty: false, launcherChain, verb, reentry: "shell", declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}), ...(stdin.length > 0 ? { stdin } : {}), ...(shift !== undefined ? { shift } : {}) });
     };
     if (pos.refusal !== undefined) {
-        const owner = programRow(programBasename(pos.refusal.owner));
+        const owner = "owner" in pos.refusal ? programRow(programBasename(pos.refusal.owner)) : undefined;
         if (pos.refusal.kind === "option_at_program_position" && owner !== undefined && commandLineOptionSpellings(owner).length > 0) {
             const text = commandStringValue(owner, toks, pos.refusal.option);
             if (text !== undefined) {
@@ -533,7 +537,11 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks) {
                 return done({ empty: false, launcherChain, reentry: "shell", declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}) });
             return reenterShell({ name: argvs[0].shell, basename: argvs[0].shell, listed: decl.readers.has(argvs[0].shell) }, argvs);
         }
-        const from = pos.launchers[0]?.index ?? written;
+        const from = pos.refusal.kind === "wildcard_program_word" ? pos.refusal.at + 1 : pos.launchers[0]?.index ?? written;
+        if (pos.refusal.kind === "wildcard_program_word") {
+            const c = bare(toks[pos.refusal.at], "program_path");
+            reads.push(c.expands === "unresolvable" ? c : { ...c, denyOnly: true });
+        }
         unlistedWords(reads, toks, from, launcherIndices, "unlisted_word", ctx);
         return done({ empty: false, launcherChain, ...(verb !== undefined ? { verb } : {}), ...(reentry !== undefined ? { reentry } : {}), declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}) });
     }
@@ -554,7 +562,7 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks) {
         shift = argReads.every((r) => literalTextOf(r.word.pieces) !== undefined) && reentryText("eval", texts) !== undefined ? { kind: "eval", text: reentryText("eval", texts) } : { kind: "lost" };
     if (basename === "source" || basename === ".")
         shift = { kind: "lost" };
-    if (runsShellText(basename))
+    if (reentersShell(basename, args))
         return reenterShell(verb, [{ shell: basename, texts, args, words: argReads }]);
     const row = programRow(basename);
     const delivery = programDelivery(row, args);
@@ -610,7 +618,7 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks) {
     const effectSub = pathSubcommandOf(row, args);
     const effectRow = effectSub?.row ?? row;
     const effectArgs = effectSub === undefined ? args : args.slice(effectSub.at + 1);
-    if (effectRow !== undefined && selectedOptions(effectRow, effectArgs).some((o) => o.effect === "executes"))
+    if (effectRow !== undefined && !runsShellText(basename) && selectedOptions(effectRow, effectArgs).some((o) => o.effect === "executes"))
         reentry = "shell";
     let unreadProgramText;
     const slot = row === undefined ? undefined : programTextSlotFiles(row, args);

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

@@ -5,7 +5,7 @@
  * the segment it sits in ({@link rebasePlan}), unless it starts in a working directory of its own.
  */
 import type { LexedSegment } from "../../shell/lex.js";
-import type { BindingTable, FloorValue, InheritedFunctions, NameReader } from "./shell-read-bindings.js";
+import type { BindingTable, FloorValue, InheritedBody, InheritedFunctions, NameReader } from "./shell-read-bindings.js";
 import type { TargetUser } from "./program-read-model.js";
 import type { StdinText } from "./shell-reentry-text.js";
 import type { ReadCandidate, ShellReadPlan } from "./shell-read-plan.js";
@@ -31,6 +31,11 @@ export interface PlanStart {
     readonly names?: InheritedFunctions;
     /** What arrives on its own standard input (the input of the shell running it). */
     readonly stdin?: readonly StdinText[];
+    /** The functions the shell running this text inherited (`export -f`, an environment's `BASH_FUNC_*`), each with whether
+     *  its body is text the engine read ({@link InheritedBody}), inherited by it and by ITS child shells: a child adds its own
+     *  exports and passes the whole on, so a grandchild still sees a function exported two shells up (#1628). Only on a
+     *  child-shell start; a substitution / eval runs in the same shell and reads its functions whole. */
+    readonly exportedFunctions?: ReadonlyMap<string, InheritedBody>;
 }
 /** The thread of the shell that runs a text, at the segment that hands it on: a literal `eval` text is not a new plan but the next
  *  segment of the same thread, so it starts in all of it and hands the working directory and the physical mode back; a substitution

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

@@ -16,8 +16,12 @@ export type { WriteSeat } from "./program-read-model.js";
 export interface ArgWord {
     readonly raw: string;
     readonly spelled: string;
+    /** The program receives a text the spelling is not (an expansion, or a value the lexer left unresolved: `$'-\x72f'`). */
+    readonly rewritten?: true;
+    /** Nothing but expansions that may yield no word (an unquoted `$E` or `$(cmd)`, `"$@"`): it may not be an argument at all. */
+    readonly vanishes?: true;
 }
-/** The words a segment hands its program — the argv after the program word (a launcher's own words are not the program's). */
+/** The words a segment hands its program — the argv after the program word the program position names (a launcher's own words, whatever they are spelled, are not the program's). */
 export declare function programArgs(segment: ShellReadSegment): ArgWord[];
 /**
  * The BACKUP names an in-place `sed` gives the file it knows as `name` — both readings a suffix has: GNU sed replaces every

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

@@ -4,9 +4,8 @@ import { renamed } from "./shell-read-word.js";
 import { byteBoundIsSmall, implementationsOf, programRow, readArgRoles, selectedOptions, subcommandOf, writeReadings } from "./program-read-model.js";
 import { programBasename, readProgramPosition } from "./bash-program-position.js";
 export function programArgs(segment) {
-    const words = segment.argv.map((w) => ({ raw: w.raw, spelled: w.folded }));
-    const at = words.findIndex((w) => w.spelled === segment.verb?.name);
-    return at < 0 ? [] : words.slice(at + 1);
+    const at = segment.verb === undefined ? undefined : readProgramPosition(segment.argv).program?.index;
+    return (at === undefined ? [] : segment.argv.slice(at + 1)).map((w) => ({ raw: w.raw, spelled: w.folded, ...(w.expansions.length > 0 || w.unresolved !== undefined ? { rewritten: true } : {}), ...(w.pieces.length > 0 && w.pieces.every((p) => p.expansion?.yields === "many") ? { vanishes: true } : {}) }));
 }
 export function sedBackupNames(name, suffix) {
     const appended = `${name}${suffix}`;

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

@@ -21,6 +21,15 @@ import type { BoundValue } from "./shell-read-bindings.js";
  * taken: a display option (`trap -p SIG`) and a lone operand (`trap SIG`) still count their operand as the body.
  */
 export declare function codeBodies(basename: string, args: readonly string[]): readonly string[];
+/** Does this program, handed `args`, run a line of the shell's HISTORY list (`fc -s`, `fc -e -`, `fc -e vi`, bare `fc`)? Its
+ *  row's text is `history`, and either an option it selects RUNS at once — `effect: "executes"` (`-s`) or its
+ *  `executesWhenValue` value (`-e -`), which win over a printing one (bash 5.3 runs `fc -l -s`, `fc -le -`) — or none it selects
+ *  only prints (`fc -e vi` edits then runs; `fc -l`, `fc -ln -1`, `fc -e vi -l` list). What runs is a line no word of the
+ *  command spells — a text built when the command runs, as a stream-fed or substituted script is. */
+export declare function runsStoredLine(basename: string, args: readonly string[]): boolean;
+/** Does this program, handed `args`, re-enter the shell — a shell re-entry row, unless its text is the history list and these
+ *  options only print it (`fc -l`: a listing runs nothing)? */
+export declare function reentersShell(basename: string, args: readonly string[]): boolean;
 /** The shell text a re-entry program runs, by its row: the shell-text value its walk reads for a shell (`-c`'s), its
  *  words joined for `eval`, its non-option words for `parallel`; none for `source` / `.` (a script file operand), for a
  *  shell whose first operand (a script file) or `--` comes before any text, or for a program that is no re-entry. Where

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, programRow, readArgRoles, selectedOptions, targetUserOf } from "./program-read-model.js";
+import { implementationRejects, implementationsOf, programRow, readArgRoles, selectedOptions, selectedSpellings, targetUserOf } from "./program-read-model.js";
 import { namesStandardInput } from "./safety.js";
 export function codeBodies(basename, args) {
     const row = programRow(basename);
@@ -43,8 +43,46 @@ function shellTextOf(e, args) {
         return args[e.at];
     if (e.kind === "option" && typeof e.reading === "object" && e.reading.role?.kind === "shell-text")
         return e.reading.attached;
+    if (e.kind === "value" && e.spec?.runsLater !== undefined)
+        return laterCommandLine(e.spec.runsLater, args[e.at]);
+    if (e.kind === "option" && typeof e.reading === "object" && e.reading.spec?.runsLater !== undefined)
+        return laterCommandLine(e.reading.spec.runsLater, e.reading.attached);
     return undefined;
 }
+const BOOLEAN_SPELLINGS = new Set(["", "true", "false", "yes", "no", "on", "off", "1", "0"]);
+function laterCommandLine(table, setting) {
+    const eq = setting.indexOf("=");
+    if (eq <= 0)
+        return undefined;
+    const key = setting.slice(0, eq).toLowerCase();
+    const value = setting.slice(eq + 1);
+    const entry = table.keys.find((k) => new RegExp(`^${k.key.split("*").map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`).test(key));
+    if (entry === undefined)
+        return undefined;
+    if (table.valueFrom === "environment")
+        return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value) ? `"$${value}"` : undefined;
+    if (value.trim() === "")
+        return undefined;
+    if (entry.orBoolean === true && BOOLEAN_SPELLINGS.has(value.toLowerCase()))
+        return undefined;
+    if (entry.bang === true)
+        return value.startsWith("!") ? value.slice(1) : undefined;
+    if (entry.prefixed !== undefined)
+        return value.startsWith("!") ? value.slice(1) : value.startsWith("/") ? value : `${entry.prefixed}${value}`;
+    return value;
+}
+export function runsStoredLine(basename, args) {
+    const row = programRow(basename);
+    if (row?.reentry?.kind !== "shell" || row.reentry.text !== "history")
+        return false;
+    const selected = selectedOptions(row, args, "one-implementation");
+    const runsAtOnce = selected.some((o) => o.effect === "executes") || selectedSpellings(row, args).values.some((v) => v.spec.executesWhenValue !== undefined && (v.value ?? args[v.at]) === v.spec.executesWhenValue);
+    return runsAtOnce || !selected.some((o) => o.mode === "banner");
+}
+export function reentersShell(basename, args) {
+    const r = programRow(basename)?.reentry;
+    return r?.kind === "shell" && (r.text !== "history" || runsStoredLine(basename, args));
+}
 export function reentryText(basename, args, stdin) {
     const row = programRow(basename);
     const r = row?.reentry;
@@ -61,7 +99,7 @@ function argvText(row, at, args) {
         return args.length === 0 ? undefined : args.join(" ");
     if (at === "non-option-words")
         return args.filter((a) => !a.startsWith("-")).join(" ") || undefined;
-    if (at === "file-operand")
+    if (at === "file-operand" || at === "history")
         return undefined;
     for (const e of optionSection(readArgRoles(row, args))) {
         const text = shellTextOf(e, args);

package/dist/tools/todo.js

@@ -12,69 +12,69 @@ export function createTodoWriteTool() {
             '- Each todo has `content`, `status` ("pending" | "in_progress" | "completed"), and `activeForm` (present-tense label shown while in progress).\n' +
             "- Send the full list each call; it replaces the previous one.\n" +
             "- Keep one item `in_progress` at a time and mark it `completed` when done.",
-        descriptionClassic: "Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.\n" +
-            "It also helps the user understand the progress of the task and overall progress of their requests.\n" +
-            "\n" +
-            "## When to Use This Tool\n" +
-            "Use this tool proactively in these scenarios:\n" +
-            "\n" +
-            "1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions\n" +
-            "2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations\n" +
-            "3. User explicitly requests todo list - When the user directly asks you to use the todo list\n" +
-            "4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)\n" +
-            "5. After receiving new instructions - Immediately capture user requirements as todos\n" +
-            "6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time\n" +
-            "7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation\n" +
-            "\n" +
-            "## When NOT to Use This Tool\n" +
-            "\n" +
-            "Skip using this tool when:\n" +
-            "1. There is only a single, straightforward task\n" +
-            "2. The task is trivial and tracking it provides no organizational benefit\n" +
-            "3. The task can be completed in less than 3 trivial steps\n" +
-            "4. The task is purely conversational or informational\n" +
-            "\n" +
-            "NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.\n" +
-            "\n" +
-            "## Task States and Management\n" +
-            "\n" +
-            "1. **Task States**: Use these states to track progress:\n" +
-            "   - pending: Task not yet started\n" +
-            "   - in_progress: Currently working on (limit to ONE task at a time)\n" +
-            "   - completed: Task finished successfully\n" +
-            "\n" +
-            "   **IMPORTANT**: Task descriptions must have two forms:\n" +
-            '   - content: The imperative form describing what needs to be done (e.g., "Run tests", "Build the project")\n' +
-            '   - activeForm: The present continuous form shown during execution (e.g., "Running tests", "Building the project")\n' +
-            "\n" +
-            "2. **Task Management**:\n" +
-            "   - Update task status in real-time as you work\n" +
-            "   - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)\n" +
-            "   - Exactly ONE task must be in_progress at any time (not less, not more)\n" +
-            "   - Complete current tasks before starting new ones\n" +
-            "   - Remove tasks that are no longer relevant from the list entirely\n" +
-            "\n" +
-            "3. **Task Completion Requirements**:\n" +
-            "   - ONLY mark a task as completed when you have FULLY accomplished it\n" +
-            "   - If you encounter errors, blockers, or cannot finish, keep the task as in_progress\n" +
-            "   - When blocked, create a new task describing what needs to be resolved\n" +
-            "   - Never mark a task as completed if:\n" +
-            "     - Tests are failing\n" +
-            "     - Implementation is partial\n" +
-            "     - You encountered unresolved errors\n" +
-            "     - You couldn't find necessary files or dependencies\n" +
-            "\n" +
-            "4. **Task Breakdown**:\n" +
-            "   - Create specific, actionable items\n" +
-            "   - Break complex tasks into smaller, manageable steps\n" +
-            "   - Use clear, descriptive task names\n" +
-            "   - Always provide both forms:\n" +
-            '     - content: "Fix authentication bug"\n' +
-            '     - activeForm: "Fixing authentication bug"\n' +
-            "\n" +
-            "When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.\n" +
-            "\n" +
-            "Pass the COMPLETE todo list each call — it replaces the prior list.",
+        descriptionVariants: [{ id: "classic", traits: { noneOf: ["lean_prompt"] }, text: "Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.\n" +
+                    "It also helps the user understand the progress of the task and overall progress of their requests.\n" +
+                    "\n" +
+                    "## When to Use This Tool\n" +
+                    "Use this tool proactively in these scenarios:\n" +
+                    "\n" +
+                    "1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions\n" +
+                    "2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations\n" +
+                    "3. User explicitly requests todo list - When the user directly asks you to use the todo list\n" +
+                    "4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)\n" +
+                    "5. After receiving new instructions - Immediately capture user requirements as todos\n" +
+                    "6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time\n" +
+                    "7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation\n" +
+                    "\n" +
+                    "## When NOT to Use This Tool\n" +
+                    "\n" +
+                    "Skip using this tool when:\n" +
+                    "1. There is only a single, straightforward task\n" +
+                    "2. The task is trivial and tracking it provides no organizational benefit\n" +
+                    "3. The task can be completed in less than 3 trivial steps\n" +
+                    "4. The task is purely conversational or informational\n" +
+                    "\n" +
+                    "NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.\n" +
+                    "\n" +
+                    "## Task States and Management\n" +
+                    "\n" +
+                    "1. **Task States**: Use these states to track progress:\n" +
+                    "   - pending: Task not yet started\n" +
+                    "   - in_progress: Currently working on (limit to ONE task at a time)\n" +
+                    "   - completed: Task finished successfully\n" +
+                    "\n" +
+                    "   **IMPORTANT**: Task descriptions must have two forms:\n" +
+                    '   - content: The imperative form describing what needs to be done (e.g., "Run tests", "Build the project")\n' +
+                    '   - activeForm: The present continuous form shown during execution (e.g., "Running tests", "Building the project")\n' +
+                    "\n" +
+                    "2. **Task Management**:\n" +
+                    "   - Update task status in real-time as you work\n" +
+                    "   - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)\n" +
+                    "   - Exactly ONE task must be in_progress at any time (not less, not more)\n" +
+                    "   - Complete current tasks before starting new ones\n" +
+                    "   - Remove tasks that are no longer relevant from the list entirely\n" +
+                    "\n" +
+                    "3. **Task Completion Requirements**:\n" +
+                    "   - ONLY mark a task as completed when you have FULLY accomplished it\n" +
+                    "   - If you encounter errors, blockers, or cannot finish, keep the task as in_progress\n" +
+                    "   - When blocked, create a new task describing what needs to be resolved\n" +
+                    "   - Never mark a task as completed if:\n" +
+                    "     - Tests are failing\n" +
+                    "     - Implementation is partial\n" +
+                    "     - You encountered unresolved errors\n" +
+                    "     - You couldn't find necessary files or dependencies\n" +
+                    "\n" +
+                    "4. **Task Breakdown**:\n" +
+                    "   - Create specific, actionable items\n" +
+                    "   - Break complex tasks into smaller, manageable steps\n" +
+                    "   - Use clear, descriptive task names\n" +
+                    "   - Always provide both forms:\n" +
+                    '     - content: "Fix authentication bug"\n' +
+                    '     - activeForm: "Fixing authentication bug"\n' +
+                    "\n" +
+                    "When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.\n" +
+                    "\n" +
+                    "Pass the COMPLETE todo list each call — it replaces the prior list." }],
         parameters: Type.Object({
             todos: Type.Array(Type.Object({
                 content: Type.String({ description: "The task, in imperative form (e.g. \"Run the tests\")." }),