@sema-agent/core 7.54.1 → 7.56.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-judge.d.ts

@@ -358,6 +358,10 @@ export interface ShellReadFold {
     readonly finding: ShellReadFinding;
     readonly witness?: ReadFinding;
     readonly declined?: ShellReadSegment;
+    /** EVERY segment of the text that re-enters a shell (`sh -c S`, `eval S`, a launcher handing text to a shell, a shell fed on its
+     *  standard input) and so is at least `unestablishable`, in text order — `declined` holds only the first finding of the rank, and the
+     *  account of this question names each program, not the first. Present only with an `unestablished` fold. */
+    readonly reentered?: readonly ShellReadSegment[];
     /** What the judge did not finish, for an `unanswered` finding: the first thing the establishment recorded ({@link Incomplete.detail}). */
     readonly cause?: string;
     /** Some read of the text could not be established (an `unestablishable`, `unanswered` or `declined` finding anywhere, winning or not). */

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

@@ -132,6 +132,7 @@ export function foldShellReadFindings(judged) {
     let best = { finding: "none" };
     let unestablished = false;
     let unplacedRead = false;
+    const reentered = [];
     const raise = (next) => {
         if (next.finding === "unestablishable" || next.finding === "declined" || next.finding === "unanswered") {
             const face = next.witness?.read.candidate.face;
@@ -158,8 +159,10 @@ export function foldShellReadFindings(judged) {
             if (!denyOnly) {
                 if (s.segment.declines.length > 0)
                     raise({ finding: "declined", declined: s.segment });
-                if (s.segment.reentry === "shell")
+                if (s.segment.reentry === "shell") {
                     raise({ finding: "unestablishable", declined: s.segment });
+                    reentered.push(s.segment);
+                }
                 if (s.segment.unreadProgramText !== undefined)
                     raise({ finding: "unestablishable", declined: s.segment });
                 const move = s.segment.baseMove;
@@ -177,7 +180,7 @@ export function foldShellReadFindings(judged) {
         unestablished = true;
         best = { finding: "unanswered", cause: unfinished.detail, ...(best.finding === "unestablishable" ? { ...(best.witness !== undefined ? { witness: best.witness } : {}), ...(best.declined !== undefined ? { declined: best.declined } : {}) } : {}) };
     }
-    return { ...best, ...(unestablished ? { unestablished: true } : {}), ...(unplacedRead ? { unplacedRead: true } : {}) };
+    return { ...best, ...(unestablished ? { unestablished: true } : {}), ...(unplacedRead ? { unplacedRead: true } : {}), ...(unestablished && reentered.length > 0 ? { reentered } : {}) };
 }
 export function judgeEstablishedPlan(plan, established, boundary, nestedOf) {
     return {

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/loop-tick.d.ts

@@ -19,9 +19,9 @@ export interface AutonomousLoopPromptOptions {
      */
     pushNotification?: boolean;
 }
-/** CC 2.1.209 `FFi` (:205310) — first-tick preamble, DEFAULT variant (steward framing). Verbatim through 2.1.259; the reference dropped this preamble from 2.1.278 on. */
+/** First-tick preamble, DEFAULT variant (steward framing). The reference later dropped this preamble. */
 export declare const AUTONOMOUS_LOOP_PREAMBLE = "# Autonomous loop check\n\nYou're being invoked on a timer while the user is away or occupied. The point is to keep work moving forward without the user driving every step \u2014 finishing things they started, maintaining PRs they're building, catching problems before they come back to find them. You're a steward, not an initiator. The user set you loose on their work, and the value you provide comes from reliably advancing things they've already set in motion, not from finding new things to do.\n\nThe key tension to navigate: the user trusts you enough to run autonomously, but that trust is easily lost. Acting on what the conversation already established is safe and valuable. Inventing new work or making irreversible changes without clear authorization erodes trust fast. When you're unsure whether something falls into \"continuing established work\" or \"inventing new work,\" lean toward the former only when the transcript provides clear evidence the user wanted it done. If you find yourself reaching for justifications about why a push is probably fine, that's a signal to wait.\n\n## What to act on\n\nThe current conversation is your highest-signal source \u2014 re-read the transcript above, since everything there is something the user was actively engaged with. The strongest signal is an in-progress PR you've been building together: review comments to address and resolve, failing CI checks to diagnose (and re-enqueue if they're flakes), merge conflicts to fix. The goal is to get the PR into a state where it's ready to merge pending only human review \u2014 the user shouldn't come back to find a PR blocked on things you could have handled. After that, look for unfinished implementation where the last exchange left something half-done, and explicit \"I'll also...\" or \"next I'll...\" commitments the conversation made and didn't honor. Weaker but still real: dangling questions you could now answer, verification steps that were skipped, edge cases that were mentioned but not handled, and natural continuations that don't require new decisions.\n\nIf you find anything in this category, act on it \u2014 actually do the work, don't describe what could be done. Run the tests, don't say \"you could run the tests.\" The whole point of autonomous operation is that work gets done while the user is away.\n\nWhen the conversation transcript has nothing left, the current branch's pull/merge request on the user's SCM is the next-best place to look. This is maintenance work \u2014 valuable, but lower priority than continuing the user's active work. Find the PR/MR for the current branch via the SCM's CLI, then check three things: CI status, unresolved review threads, and whether the branch has fallen behind the base. For failing CI, pull the failing job's logs and diagnose before acting \u2014 flaky-shaped failures (timeout, runner died, transient network) can be re-enqueued; real failures need a reproduction and a minimal fix. For unresolved review threads, fetch the comment, address the feedback, push, and resolve the thread via, for example, the GitHub GraphQL `resolveReviewThread` mutation (or the equivalent for whichever SCM the project uses). Before pushing anything, check whether someone else has pushed to the branch while you were working \u2014 if so, rebase (don't merge) to keep history clean.\n\nWhen CI is green, threads are clear, and there's idle time, sweeping the branch for issues is a good use of that time \u2014 bug-hunt or simplification passes catch problems before reviewers do, saving everyone a round-trip.\n\nIf everything is genuinely quiet \u2014 no conversation work, no PR maintenance \u2014 say so in one sentence and stop. No summary of what you checked, no list of what you might do later. The user will see your message in the transcript when they come back; three consecutive \"nothing to do\" results means you should scale back to a quick CI check and stop, not narrate.\n\n## Repeated invocations\n\nIf you see earlier autonomous checks in this conversation, adjust your scope accordingly. If a previous check left a question the user hasn't answered, the cost of acting depends on reversibility: for reversible actions (local edits, running tests), make your best call and proceed; for irreversible ones (pushing, deleting, sending), keep waiting \u2014 the cost of acting wrongly on something irreversible is much higher than the cost of waiting one more cycle. If three or more consecutive checks have found nothing actionable, things are quiet \u2014 do one quick CI/threads check and stop in a single line. Repeated \"nothing to do\" messages clutter the transcript and waste the user's attention when they come back to review.\n\nRead and analyze freely \u2014 understanding the state of things has no blast radius. Make edits and run tests when you're confident they continue established work. Commit and push only when you're clearly continuing something the user authorized, or when the work pattern makes the intent obvious \u2014 like fixing CI on a PR you've been building together.\n";
-/** CC 2.1.209 `w6c` (:205335) — first-tick preamble, PERSISTENT variant. Verbatim through 2.1.259; dropped from 2.1.278 on. */
+/** First-tick preamble, PERSISTENT variant. Later dropped by the reference. */
 export declare const AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT = "# Autonomous loop check\n\nYou're being invoked on a timer while the user is away or occupied. The point is to keep work moving forward without the user driving every step \u2014 finishing things they started, maintaining PRs they're building, catching problems before they come back to find them, and following through on the *spirit* of the task they gave you, not just its literal scope. The user set you loose on their work, and the value you provide comes from reliably advancing things they've already set in motion.\n\nThe key tension to navigate: the user trusts you enough to run autonomously, but that trust is easily lost. Acting on what the conversation already established is safe and valuable. For irreversible actions (push, delete, send), require clear authorization in the transcript or use a reversible alternative (a draft, a local commit, a queued message). For reversible actions (edits, tests, drafts, exploration), bias toward acting \u2014 the cost of an unneeded local edit is near zero, and the cost of a stalled loop is high. When you're unsure whether something falls into \"continuing established work\" or \"inventing new work,\" lean toward continuing whenever the transcript gives you any reasonable thread to pull on.\n\n## What to act on\n\nThe current conversation is your highest-signal source \u2014 re-read the transcript above, since everything there is something the user was actively engaged with. The strongest signal is an in-progress PR you've been building together: review comments to address and resolve, failing CI checks to diagnose (and re-enqueue if they're flakes), merge conflicts to fix. The goal is to get the PR into a state where it's ready to merge pending only human review \u2014 the user shouldn't come back to find a PR blocked on things you could have handled. After that, look for unfinished implementation where the last exchange left something half-done, and explicit \"I'll also...\" or \"next I'll...\" commitments the conversation made and didn't honor. Weaker but still real: dangling questions you could now answer, verification steps that were skipped, edge cases that were mentioned but not handled, and natural continuations that don't require new decisions.\n\nIf you find anything in this category, act on it \u2014 actually do the work, don't describe what could be done. Run the tests, don't say \"you could run the tests.\" The whole point of autonomous operation is that work gets done while the user is away.\n\nWhen the conversation transcript has nothing left, the current branch's pull/merge request on the user's SCM is the next-best place to look. This is maintenance work \u2014 valuable, but lower priority than continuing the user's active work. Find the PR/MR for the current branch via the SCM's CLI, then check three things: CI status, unresolved review threads, and whether the branch has fallen behind the base. For failing CI, pull the failing job's logs and diagnose before acting \u2014 flaky-shaped failures (timeout, runner died, transient network) can be re-enqueued; real failures need a reproduction and a minimal fix. For unresolved review threads, fetch the comment, address the feedback, push, and resolve the thread via, for example, the GitHub GraphQL `resolveReviewThread` mutation (or the equivalent for whichever SCM the project uses). Before pushing anything, check whether someone else has pushed to the branch while you were working \u2014 if so, rebase (don't merge) to keep history clean.\n\nWhen CI is green, threads are clear, and there's idle time, sweeping the branch for issues is a good use of that time \u2014 bug-hunt or simplification passes catch problems before reviewers do, saving everyone a round-trip.\n\nIf everything is genuinely quiet \u2014 no conversation work, no PR maintenance \u2014 say so in one sentence and keep the loop alive. Before stopping, broaden once: re-read the original task framing, check whether earlier ticks deferred anything (\"I'll wait for X\"), and look at sibling PRs/branches the user owns. Persistence is the point of autonomous mode. Only stop if the original task is provably complete or the user said to stop. (Pacing \u2014 how long to wait before the next tick \u2014 is handled by the per-mode reminder appended to this preamble; don't try to manage delay from here.)\n\n## Repeated invocations\n\nIf you see earlier autonomous checks in this conversation, adjust your scope accordingly. If a previous check left a question the user hasn't answered, the cost of acting depends on reversibility: for reversible actions (local edits, running tests), make your best call and proceed; for irreversible ones (pushing, deleting, sending), keep waiting \u2014 the cost of acting wrongly on something irreversible is much higher than the cost of waiting one more cycle. If three or more consecutive checks have found nothing actionable, broaden scope once before considering stopping \u2014 re-read the original task, check sibling work, look for verification or polish steps that were skipped. A loop that quits the moment work goes quiet is less useful than one that waits.\n\nRead and analyze freely \u2014 understanding the state of things has no blast radius. Make edits and run tests when you're confident they continue established work. Commit and push only when you're clearly continuing something the user authorized, or when the work pattern makes the intent obvious \u2014 like fixing CI on a PR you've been building together.\n";
 /**
  * Resolve a fire-time prompt: if it is one of the two autonomous-loop sentinels, return the tick

package/dist/tools/scheduler-tools.js

@@ -1,7 +1,7 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../core/tools.js";
 import { hasScheduler, isValidCronExpr, } from "../core/scheduler.js";
-import { toolFace } from "../core/tool-catalog-entries.js";
+import { mountRuleFace, toolFace } from "../core/tool-catalog-entries.js";
 export const SCHEDULE_WAKEUP_TOOL_NAME = "ScheduleWakeup";
 export const AUTONOMOUS_LOOP_SENTINEL = "<<autonomous-loop>>";
 export const AUTONOMOUS_LOOP_DYNAMIC_SENTINEL = "<<autonomous-loop-dynamic>>";
@@ -201,6 +201,7 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
     const cronCreate = defineTool({
         name: "CronCreate",
         ...toolFace("cron-create"),
+        ruleFace: mountRuleFace("cron-create"),
         description: cronCreateDescription,
         parameters: Type.Object({
             prompt: Type.String({ description: "Self-contained instructions for the future task (it runs unattended)." }),
@@ -306,6 +307,7 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
     const cronCancel = defineTool({
         name: "CronDelete",
         ...toolFace("cron-delete"),
+        ruleFace: mountRuleFace("cron-delete"),
         description: "Cancel a cron job previously scheduled with CronCreate. Idempotent; ids also appear in CronList.",
         parameters: Type.Object({ id: Type.String({ description: "Job ID returned by CronCreate." }) }),
         execute: async (args) => {
@@ -329,6 +331,7 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
     const cronList = defineTool({
         name: "CronList",
         ...toolFace("cron-list"),
+        ruleFace: mountRuleFace("cron-list"),
         description: "List all cron jobs scheduled via CronCreate (id, when, label).",
         parameters: Type.Object({}),
         execute: async () => {
@@ -408,6 +411,7 @@ MOUNT NOTE: this host does not vouch for session-scoped scheduling, so a wakeup
     const scheduleWakeup = defineTool({
         name: SCHEDULE_WAKEUP_TOOL_NAME,
         ...toolFace("schedule-wakeup"),
+        ruleFace: mountRuleFace("schedule-wakeup"),
         description: `${SCHEDULE_WAKEUP_PROMPT}${wakeupMountNote}`,
         parameters: Type.Object({
             delaySeconds: Type.Optional(Type.Number({

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

@@ -1,19 +1,19 @@
 import type { ToolSpec } from "../core/types.js";
 /**
- * design/119 (CC 2.1.198 parity) — the structured task-list tool family: `TaskCreate` / `TaskGet` /
- * `TaskUpdate` / `TaskList`. CC 198's upgrade path over TodoWrite: individual tasks with stable ids,
+ * design/119 — the structured task-list tool family: `TaskCreate` / `TaskGet` /
+ * `TaskUpdate` / `TaskList`. The upgrade path over TodoWrite: individual tasks with stable ids,
  * status transitions, dependencies (blocks/blockedBy), an optional owner, and free metadata — instead
- * of TodoWrite's replace-the-whole-list. CC209 对齐批B B3: the two families are MUTUALLY EXCLUSIVE and
- * this one is the DEFAULT — TodoWrite mounts only when the task list is explicitly off (the CC 209
+ * of TodoWrite's replace-the-whole-list. The two families are MUTUALLY EXCLUSIVE and
+ * this one is the DEFAULT — TodoWrite mounts only when the task list is explicitly off (the reference
  * shape: TodoWrite isEnabled = !taskList; see `scenarios/full-body.ts`).
  *
  * State default: like TodoWrite, the default store lives in this factory's closure — FRESH per task
  * and torn down with it; nothing durable, no deps, no egress (the model's own scratch, projected to
- * observers only through each call's tool result / `details`). Descriptions follow CC 2.1.198
+ * observers only through each call's tool result / `details`). Descriptions follow the reference
  * (product-specific lines — teammate assignment, spinner/UI wording — trimmed or generalized).
  *
- * design/147 §6 D2 (CC 2.1.216 shared team task list): pass a {@link TaskListStore} to share ONE
- * task list across several agents — CC 216's team coordination artifact ("Check the task list
+ * design/147 §6 D2 (shared team task list): pass a {@link TaskListStore} to share ONE
+ * task list across several agents — the reference's team coordination artifact ("Check the task list
  * periodically. Create new tasks when work should be divided. Mark tasks resolved when complete.")
  * is a task-list file under the team directory; the sema equivalent is this storage seam. A
  * deployment mounts the SAME store instance into each teammate's tool bundle (same session = same

package/dist/tools/task-list.js

@@ -1,5 +1,5 @@
 import { Type } from "typebox";
-import { toolFace } from "../core/tool-catalog-entries.js";
+import { mountRuleFace, toolFace } from "../core/tool-catalog-entries.js";
 const STATUS = Type.Union([
     Type.Literal("pending"),
     Type.Literal("in_progress"),
@@ -98,6 +98,7 @@ export function createTaskListTools(store) {
     const taskCreate = {
         name: "TaskCreate",
         ...toolFace("task-create"),
+        ruleFace: mountRuleFace("task-create"),
         description: "Use this tool to create a structured task list for your current session. This helps you track progress, organize complex tasks, and demonstrate thoroughness.\n" +
             "It also helps the user understand the progress of the task and overall progress of their requests.\n" +
             "\n" +
@@ -170,6 +171,7 @@ export function createTaskListTools(store) {
     const taskGet = {
         name: "TaskGet",
         ...toolFace("task-get"),
+        ruleFace: mountRuleFace("task-get"),
         description: "Use this tool to retrieve a task by its ID from the task list.\n" +
             "\n" +
             "## When to Use This Tool\n" +
@@ -201,6 +203,7 @@ export function createTaskListTools(store) {
     const taskUpdate = {
         name: "TaskUpdate",
         ...toolFace("task-update"),
+        ruleFace: mountRuleFace("task-update"),
         description: "Use this tool to update a task in the task list.\n" +
             "\n" +
             "## When to Use This Tool\n" +
@@ -394,6 +397,7 @@ export function createTaskListTools(store) {
     const taskList = {
         name: "TaskList",
         ...toolFace("task-list"),
+        ruleFace: mountRuleFace("task-list"),
         description: "Use this tool to list all tasks in the task list.\n" +
             "\n" +
             "## When to Use This Tool\n" +