@sema-agent/core 7.47.0 → 7.48.0

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

@@ -1,12 +1,13 @@
 import { lexShell, PARSE_FAILURE_SENTENCE, substitutionsInHeredocBody, literalTextOf, literalTildeSpelling, } from "../../shell/lex.js";
-import { programTextOf, readOfText, readsOf, renamed, rewritten, settledFieldsOf, spelledWithHome, isArithmeticBody, unreadableSentenceOf } from "./shell-read-word.js";
+import { programTextOf, readOfText, readsOf, rewritten, segmentReadingsOf, settledFieldsOf, spelledWithHome, isArithmeticBody, 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, parameterBodySubstitutions, projectSegment, valueOf, } from "./shell-read-bindings.js";
-import { programBasename, programPositionRunsShell, readProgramPosition, shellScanDeclineOf, } from "./bash-program-position.js";
+import { ARITHMETIC_TEST_OPERATORS, BindingThread, arithmeticSubstitutions, isArithmeticCommand, bindingEffectOf, loopListHeadAt, parameterBodySubstitutions, projectSegment, valueOf, } from "./shell-read-bindings.js";
+import { isShellSyntaxWord, programBasename, programPositionRunsShell, readProgramPosition, shellScanDeclineOf, } from "./bash-program-position.js";
 import { POLL_LOOP_MAX_BEATS, attachedOptionPayloads, resolveOperandLexically, isPathShapedToken, programTextSlotFiles, } from "./bash-readonly-classifier.js";
-import { BLOCK_WORD_NAMES, commandLineOptionSpellings, declaredAttributes, isDeclarationBuiltin, isInertBuiltin, launcherOptionPathRole, launcherOptionStep, readOptionRole, programLanguageOf, programTextOpensOf, selectedOptions, movesBaseUnfollowed, opensNoOperand, programDelivery, programRow, readArgRoles, runsShellText, } from "./program-read-model.js";
+import { BLOCK_WORD_NAMES, commandLineOf, commandLineOptionSpellings, declaredAttributes, isDeclarationBuiltin, isInertBuiltin, launcherOptionPathRole, launcherOptionStep, readOptionRole, programLanguageOf, programTextOpensOf, selectedOptions, movesBaseUnfollowed, opensNoOperand, programDelivery, programRow, readArgRoles, runsShellText, } from "./program-read-model.js";
 import { isAbsolutePathForm } from "./safety.js";
 import { codeBodies, launchedInput, pipedTextOf, reentryText, scriptFileAt, stdinTextsOf } from "./shell-reentry-text.js";
+import { plannedOnce, rebasePlan, startedAt, stdinFeeds } from "./shell-read-start.js";
 export const READ_CANDIDATE_PROVENANCES = Object.freeze([
     "operand",
     "option_value",
@@ -22,6 +23,7 @@ export const READ_CANDIDATE_PROVENANCES = Object.freeze([
     "object_path",
 ]);
 const NESTING_MAX = 4;
+const LOOP_END = new Set(["done"]), COPROC = new Set(["coproc"]);
 const BASE_CANDIDATE_MAX = 256;
 export function planShellReads(command, decl, depth = 0, start) {
     const shape = { grouped: false, backgrounded: false, strayRedirection: false };
@@ -53,19 +55,19 @@ export function planShellReads(command, decl, depth = 0, start) {
     }
     const names = new BindingThread(lexed.segments, named, initial, boundAnywhere, loopEndOf, start?.homeTouched === true, start?.inherited);
     const laterStart = { initial: (name) => (name === "HOME" && !boundAnywhere("HOME") ? declaredHome : "unknown"), boundAnywhere, homeTouched: boundAnywhere("HOME"), inherited: names.inheritedAt() };
-    const nestedPlanner = (table) => (text, kind) => planShellReads(text, decl, depth + 1, kind === "substitution" ? { initial: (name) => table.stateOf(name), boundAnywhere, homeTouched: table.homeTouched, inherited: table.inherited } : laterStart);
+    const nestedPlanner = (table) => (text, kind, at) => planShellReads(text, decl, depth + 1, kind === "substitution" ? { initial: (name) => table.stateOf(name), boundAnywhere, homeTouched: table.homeTouched, inherited: table.inherited } : startedAt(laterStart, 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) => (facts[si - 1] === undefined ? [projected[si - 1].argv] : (facts[si - 1].readings ?? [facts[si - 1]]).map((f) => f.argv)).map((argv) => pipedTextOf(lexed.segments[si - 1], argv)));
     const factsAt = (si, table) => {
         tables[si] ??= table;
-        const piped = si > 0 && lexed.segments[si].connector === "|" ? pipedTextOf(lexed.segments[si - 1], projected[si - 1].argv) : undefined;
-        return (facts[si] ??= segmentFacts(lexed.segments[si], projected[si], decl, table, nestedPlanner(table), piped));
+        return (facts[si] ??= segmentFacts(lexed.segments[si], projected[si], decl, table, nestedPlanner(table), fedAt(si)));
     };
     const basesOf = projected.map(() => new Set());
     const unmodelled = projected.map(() => false);
-    let candidates = [{ base: decl.cwd, skippedCd: -1 }];
-    let baseLost = false;
+    let candidates = (start?.bases !== undefined && start.bases !== "unmodelled" ? start.bases : [decl.cwd]).map((base) => ({ base, skippedCd: -1 }));
+    let baseLost = start?.bases === "unmodelled";
     let floorBases;
     const loseBase = (reachable, floorTarget) => {
         baseLost = true;
@@ -182,15 +184,15 @@ export function planShellReads(command, decl, depth = 0, start) {
         }
     }
     const planned = facts.map((f) => f);
-    const inert = depth === 0 && unreadable === undefined && planned.every(segmentOpensNothing);
-    const settled = inert ? planned.map((f) => ({ ...f, reads: f.reads.filter((c) => c.provenance !== "env_assignment") })) : planned;
+    const inert = depth === 0 && unreadable === undefined && planned.every((f) => (f.readings ?? [f]).every(segmentOpensNothing));
+    const settled = inert ? planned.map((f) => ({ ...f, reads: f.reads.filter((c) => c.provenance !== "env_assignment"), ...(f.readings !== undefined ? { readings: f.readings.map((g) => ({ ...g, reads: g.reads.filter((c) => c.provenance !== "env_assignment") })) } : {}) })) : planned;
     shape.grouped = projected.some((p) => p.grouped);
-    shape.backgrounded = lexed.segments.some((s) => s.connector === "&") || settled.some((f) => f.backgrounds === true);
+    shape.backgrounded = lexed.segments.some((s) => s.connector === "&") || settled.some((f) => (f.readings ?? [f]).some((g) => g.backgrounds === true));
     shape.strayRedirection = projected.some((p) => p.argv.length === 0 && p.redirects.length > 0);
     const segments = [];
     for (let si = 0; si < settled.length; si++) {
-        const f = settled[si];
-        if (f.empty)
+        const threaded = settled[si];
+        if (threaded.empty)
             continue;
         const bases = unmodelled[si] ? "unmodelled" : [...basesOf[si]];
         const floor = unmodelled[si] && floorBases !== undefined && floorBases.length > 0 ? floorBases : undefined;
@@ -199,23 +201,26 @@ export function planShellReads(command, decl, depth = 0, start) {
             const here = c.provenance === "object_path" && bases !== "unmodelled" ? [...new Set(bases.flatMap(ancestorsOf))] : bases;
             return { ...c, bases: relative ? here : [], ...(relative && floor !== undefined ? { floorBases: floor } : {}) };
         };
-        segments.push({
-            text: f.text,
-            connector: f.connector,
-            argv: f.argv,
-            launcherChain: f.launcherChain,
-            ...(f.verb !== undefined ? { verb: f.verb } : {}),
-            ...(f.reentry !== undefined ? { reentry: f.reentry } : {}),
-            ...(f.unreadProgramText !== undefined ? { unreadProgramText: f.unreadProgramText } : {}),
-            ...(f.stdin !== undefined ? { stdin: f.stdin } : {}),
-            declines: f.declines,
-            reads: dedupe(f.reads).map(withBases),
-            redirects: f.redirects.map((r) => (r.target === undefined ? { op: r.op, direction: r.direction } : { op: r.op, direction: r.direction, target: withBases(r.target) })),
-            ...(f.baseMove !== undefined ? { baseMove: { target: typeof f.baseMove.target === "string" ? f.baseMove.target : withBases(f.baseMove.target) } } : {}),
-            bases,
-            nested: f.nested.map((n) => rebasePlan(n, decl.cwd, bases)),
-            reach: reaches[si] ?? { andJoined: false, orBroken: false, moveProvable: false },
-        });
+        const move = threaded.baseMove;
+        for (const f of threaded.readings ?? [threaded]) {
+            segments.push({
+                text: f.text,
+                connector: f.connector,
+                argv: f.argv,
+                launcherChain: f.launcherChain,
+                ...(f.verb !== undefined ? { verb: f.verb } : {}),
+                ...(f.reentry !== undefined ? { reentry: f.reentry } : {}),
+                ...(f.unreadProgramText !== undefined ? { unreadProgramText: f.unreadProgramText } : {}),
+                ...(f.stdin !== undefined ? { stdin: f.stdin } : {}),
+                declines: f.declines,
+                reads: dedupe(f.reads).map(withBases),
+                redirects: f.redirects.map((r) => (r.target === undefined ? { op: r.op, direction: r.direction } : { op: r.op, direction: r.direction, target: withBases(r.target) })),
+                ...(move !== undefined ? { baseMove: { target: typeof move.target === "string" ? move.target : withBases(move.target) } } : {}),
+                bases,
+                nested: f.nested.map((n) => (f.elsewhere?.has(n) === true ? n : rebasePlan(n, decl.cwd, bases))),
+                reach: reaches[si] ?? { andJoined: false, orBroken: false, moveProvable: false },
+            });
+        }
     }
     return { segments, shape, ...(unreadable !== undefined ? { unreadable } : {}) };
 }
@@ -232,9 +237,9 @@ function loopShapeOf(p) {
     const head = p.argv[0];
     if (head === undefined)
         return undefined;
-    if (head.raw === head.folded && (head.folded === "for" || head.folded === "select") && BLOCK_WORD_NAMES.has(head.folded))
+    if (loopListHeadAt(p.argv) !== undefined)
         return "head";
-    if (head.raw === head.folded && head.folded === "done" && BLOCK_WORD_NAMES.has(head.folded))
+    if (isShellSyntaxWord(head, LOOP_END))
         return "end";
     const pos = readProgramPosition(p.argv);
     return pos.controlWords.some((i) => p.argv[i].folded === "while" || p.argv[i].folded === "until") ? "head" : undefined;
@@ -252,8 +257,26 @@ 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, piped) {
-    const facts = segmentFactsRead(segment, p, decl, table, nestedPlan, piped);
+function segmentFacts(segment, p, decl, table, nestedPlan, fed) {
+    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);
+    const once = plannedOnce(nestedPlan);
+    const each = readings.map((reading) => readingFacts(segment, { ...p, argv: reading.argv }, decl, reading, once, fed));
+    const first = each[0];
+    const move = each.find((f) => f.baseMove !== undefined)?.baseMove;
+    return {
+        ...first,
+        moveProvable: false,
+        ...(move !== undefined ? { baseMove: { target: typeof move.target === "string" ? move.target : { ...move.target, expands: "unresolvable" } } } : {}),
+        readings: each,
+    };
+}
+function readingFacts(segment, p, decl, reading, nestedPlan, fed) {
+    const table = reading.table;
+    const planner = (text, kind, at) => nestedPlan(text, kind, kind === "later" ? { ...at, floors: reading.floors } : at);
+    const facts = segmentFactsRead(segment, p, decl, table, planner, fed, reading.reads);
     const unresolvedRaw = new Set();
     for (const t of segment.tokens) {
         const w = t.kind === "word" ? t : t.kind === "redirect" ? t.target : undefined;
@@ -269,20 +292,21 @@ function segmentFacts(segment, p, decl, table, nestedPlan, piped) {
     };
     const unsettle = (c) => floor((unresolvedRaw.has(c.raw) || (homeWithheld && c.spelled.startsWith("~"))) && c.expands !== "unresolvable" ? { ...c, expands: "unresolvable" } : c);
     const each = (c) => {
-        const { alternatives, floors, ...one } = c;
-        const shadows = (floors ?? []).map((v) => ({ spelled: v.spelled, raw: one.raw, provenance: one.provenance, expands: v.glob === true ? "glob" : false, denyOnly: true }));
-        return [...[one, ...(alternatives ?? []).map((a) => ({ ...renamed(one, a.spelled), ...a }))].map(unsettle), ...shadows];
+        const { floors, ...one } = c;
+        const shadows = (floors ?? []).map((v) => ({ spelled: v.spelled, ...(v.pattern !== undefined ? { pattern: v.pattern } : {}), raw: one.raw, provenance: one.provenance, expands: v.glob === true ? "glob" : false, denyOnly: true }));
+        return [unsettle(one), ...shadows];
     };
     const move = facts.baseMove;
     return {
         ...facts,
         reads: facts.reads.flatMap(each),
         redirects: facts.redirects.map((r) => (r.target === undefined ? r : { ...r, target: unsettle(r.target) })),
-        ...(move !== undefined && typeof move.target !== "string" ? { baseMove: { target: unsettle(move.target.alternatives !== undefined ? { ...each(move.target)[0], expands: "unresolvable" } : move.target) } } : {}),
+        ...(move !== undefined && typeof move.target !== "string" ? { baseMove: { target: unsettle(move.target) } } : {}),
     };
 }
-function segmentFactsRead(segment, p, decl, table, nestedPlan, piped) {
+function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks) {
     const nested = [];
+    const elsewhere = new Set();
     const ctx = { table, reentered: [], programTextSeen: false };
     const arithmetic = segment.tokens.flatMap((t) => (t.kind === "word" ? t : t.kind === "redirect" ? t.target : undefined)?.pieces ?? []).flatMap((q) => (q.expansion?.kind === "arithmetic" && q.expansion.body !== undefined && isArithmeticBody(q.expansion.body) ? [q.expansion.body] : []));
     const count = (list, body) => list.filter((b) => b === body).length;
@@ -339,7 +363,6 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, piped) {
         redirects,
         nested,
     };
-    const toks = readsOf(p.argv, table, decl.homeDir);
     const done = (f) => {
         const reentered = [...new Set(ctx.reentered)];
         for (const body of reentered)
@@ -349,23 +372,24 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, piped) {
             ...f,
             ...(reentered.length > 0 ? { reentry: "shell" } : {}),
             ...(f.unreadProgramText === undefined && ctx.programText !== undefined ? { unreadProgramText: ctx.programText } : {}),
+            ...(elsewhere.size > 0 ? { elsewhere } : {}),
         };
     };
     const head = toks[0]?.folded;
-    if (head === "coproc" && toks[0].raw === head && toks.length > 1) {
+    if (isShellSyntaxWord(p.argv[0], COPROC) && toks.length > 1) {
         const tail = (from) => ({ ...p, argv: p.argv.slice(from) });
-        const first = segmentFacts(segment, tail(1), decl, table, nestedPlan, piped);
+        const first = segmentFacts(segment, tail(1), decl, table, nestedPlan, fed);
         if (toks.length < 3)
             return { ...first, backgrounds: true };
-        const second = segmentFacts(segment, tail(2), decl, table, nestedPlan, piped);
+        const second = segmentFacts(segment, tail(2), decl, table, nestedPlan, fed);
         const seen = new Set(first.nested.map((n) => JSON.stringify(n.segments.map((sg) => sg.text))));
         const extraNested = second.nested.filter((n) => !seen.has(JSON.stringify(n.segments.map((sg) => sg.text))));
         return { ...first, ...(second.reentry === "shell" ? { reentry: second.reentry } : {}), reads: [...first.reads, ...second.reads], nested: [...first.nested, ...extraNested], backgrounds: true };
     }
     const loop = loopShapeOf(p);
-    if (head !== undefined && toks[0].raw === head && BLOCK_WORD_NAMES.has(head)) {
-        if (loop === "head")
-            return done({ empty: false, launcherChain: [], declines: [], reads, moveProvable: false, loopHead: { beats: literalBeats(toks) } });
+    if (loopListHeadAt(p.argv) !== undefined)
+        return done({ empty: false, launcherChain: [], declines: [], reads, moveProvable: false, loopHead: { beats: literalBeats(toks) } });
+    if (head !== undefined && isShellSyntaxWord(p.argv[0], BLOCK_WORD_NAMES)) {
         if (head === "[[") {
             toks.forEach((r, i) => {
                 if (ARITHMETIC_TEST_OPERATORS.has(toks[i - 1]?.folded ?? "") || ARITHMETIC_TEST_OPERATORS.has(toks[i + 1]?.folded ?? "") || toks[i - 1]?.folded === "-v")
@@ -413,7 +437,7 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, piped) {
                 if (!w.startsWith("-") || w === "-")
                     break;
                 const step = launcherOptionStep(row, w);
-                if (step === undefined)
+                if (step === undefined || (step === 2 && j + 1 >= chainEnd))
                     break;
                 if (step === 2) {
                     const role = launcherOptionPathRole(row, w);
@@ -461,11 +485,26 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, piped) {
     if (pos.argvFromStdin)
         reentry = "argv";
     const reenterShell = (verb, argvs) => {
-        const stdin = stdinTextsOf(segment, piped);
-        const scripts = argvs.flatMap(({ shell, texts: t, args: a }) => [reentryText(shell, t), reentryText(shell, a), ...stdin.map((s) => (s.literal === undefined ? undefined : reentryText(shell, t, s.literal)))]);
-        for (const t of new Set(scripts))
-            if (t !== undefined)
-                nested.push(nestedPlan(t, "later"));
+        const stdin = stdinTextsOf(segment, fed);
+        const scripts = new Map();
+        const script = (text, at) => { if (text !== undefined)
+            scripts.set(JSON.stringify([text, at]), { ...at, text }); };
+        for (const { shell, texts: t, args: a, as } of argvs) {
+            const user = as !== undefined ? { as } : {};
+            const argvText = [reentryText(shell, t), reentryText(shell, a)];
+            for (const text of argvText)
+                script(text, { ...user, ...(stdin.length > 0 ? { stdin } : {}) });
+            if (argvText.every((text) => text === undefined))
+                for (const s of stdin)
+                    if (s.literal !== undefined)
+                        script(reentryText(shell, t, s.literal), user);
+        }
+        for (const { text, ...at } of scripts.values()) {
+            const plan = nestedPlan(text, "later", at);
+            nested.push(plan);
+            if (at.as?.login === true)
+                elsewhere.add(plan);
+        }
         for (const { shell, args: a, words } of argvs) {
             const at = shell === "source" || shell === "." ? a.findIndex((w) => !w.startsWith("-") || w === "-") : scriptFileAt(shell, a);
             const file = at === undefined ? undefined : words[at];
@@ -475,9 +514,9 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, piped) {
         return done({ empty: false, launcherChain, verb, reentry: "shell", declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}), ...(stdin.length > 0 ? { stdin } : {}) });
     };
     if (pos.refusal !== undefined) {
-        const commandLine = commandLineOptionSpellings(programRow(programBasename(pos.refusal.owner)));
-        if (pos.refusal.kind === "option_at_program_position" && commandLine.length > 0) {
-            const text = commandStringValue(commandLine, toks, pos.refusal.option);
+        const owner = programRow(programBasename(pos.refusal.owner));
+        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) {
                 nested.push(nestedPlan(text.value, "later"));
                 reentry = "shell";
@@ -596,38 +635,6 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, piped) {
         ...(loopHead !== undefined ? { loopHead } : {}),
     });
 }
-function rebasePlan(plan, from, to) {
-    if (to !== "unmodelled" && to.length === 1 && to[0] === from)
-        return plan;
-    const fromSep = from.endsWith("/") || from.endsWith("\\") ? from : `${from}/`;
-    const moveBase = (b) => {
-        if (to === "unmodelled")
-            return [];
-        if (b === from)
-            return [...to];
-        if (b.startsWith(fromSep))
-            return to.map((t) => `${t.endsWith("/") || t.endsWith("\\") ? t : `${t}/`}${b.slice(fromSep.length)}`);
-        return [b];
-    };
-    const moveCandidate = (c) => {
-        if (c.bases === "unmodelled" || c.bases.length === 0)
-            return c;
-        if (to === "unmodelled")
-            return { ...c, bases: "unmodelled" };
-        return { ...c, bases: [...new Set(c.bases.flatMap(moveBase))] };
-    };
-    return {
-        ...plan,
-        segments: plan.segments.map((s) => ({
-            ...s,
-            reads: s.reads.map(moveCandidate),
-            redirects: s.redirects.map((r) => (r.target === undefined ? r : { ...r, target: moveCandidate(r.target) })),
-            ...(s.baseMove !== undefined ? { baseMove: { target: typeof s.baseMove.target === "string" ? s.baseMove.target : moveCandidate(s.baseMove.target) } } : {}),
-            bases: s.bases === "unmodelled" || to === "unmodelled" ? "unmodelled" : [...new Set(s.bases.flatMap(moveBase))],
-            nested: s.nested.map((n) => rebasePlan(n, from, to)),
-        })),
-    };
-}
 function dedupe(reads) {
     const seen = new Set();
     const out = [];
@@ -655,21 +662,15 @@ function redirectFact(r, table, homeDir) {
         return { op: r.op, direction: "in" };
     return { op: r.op, direction: "out", target: bare(readsOf([r.target], table, homeDir)[0], "write_redirect_target") };
 }
-function commandStringValue(options, toks, option) {
+function commandStringValue(row, toks, option) {
     const at = toks.findIndex((r) => r.folded === option);
-    if (at < 0)
+    const line = at < 0 ? undefined : commandLineOf(row, option);
+    if (line === undefined)
         return undefined;
-    for (const spelling of options) {
-        if (option === spelling) {
-            const value = toks[at + 1] === undefined ? undefined : programTextOf(toks[at + 1]);
-            return value === undefined ? undefined : { value, next: at + 2 };
-        }
-        if (spelling.startsWith("--") && option.startsWith(`${spelling}=`))
-            return { value: option.slice(spelling.length + 1), next: at + 1 };
-        if (!spelling.startsWith("--") && option.startsWith(spelling) && option.length > spelling.length)
-            return { value: option.slice(spelling.length), next: at + 1 };
-    }
-    return undefined;
+    if (line !== "next")
+        return { value: line.attached, next: at + 1 };
+    const value = toks[at + 1] === undefined ? undefined : programTextOf(toks[at + 1]);
+    return value === undefined ? undefined : { value, next: at + 2 };
 }
 function literalBeats(toks) {
     const at = toks.findIndex((r) => r.folded === "in");

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

@@ -0,0 +1,57 @@
+/**
+ * Where a text the read plan (`shell-read-plan.ts`) plans starts: a nested text's start — its names, the deny floors the
+ * words handing it on carry, the user its shell runs as, its standard input and its working directory — and where each
+ * segment's standard input comes from. A nested plan parsed against the declarations' working directory is re-based onto
+ * 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, 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";
+/** Where a nested text starts its names: a substitution body inherits the table of the segment it sits in (a subshell
+ *  holds every variable); a text the shell runs later or elsewhere (a code body, `eval`'s text, a child shell's `-c`)
+ *  starts from the text's own start — every name unknown, `HOME` the declared home unless the enclosing text binds it
+ *  anywhere. `boundAnywhere` answers for the enclosing texts. */
+export interface PlanStart {
+    readonly initial: NameReader;
+    readonly boundAnywhere: (name: string) => boolean;
+    /** `HOME` may already hold something other than the declared home where the nested text starts. */
+    readonly homeTouched: boolean;
+    /** The attributes, name references and deny floors in force where the nested text starts. */
+    readonly inherited: BindingTable["inherited"];
+    /** The working directories it starts in, where they are not the enclosing segment's (a login shell starts in its user's
+     *  home; `"unmodelled"` — a home the text does not settle). */
+    readonly bases?: readonly string[] | "unmodelled";
+    /** What arrives on its own standard input (the input of the shell running it). */
+    readonly stdin?: readonly StdinText[];
+}
+/** What a segment says of the start of a text it hands a shell to run later: the deny floors of the words it holds as
+ *  written, the user the shell runs as ({@link TargetUser}), and the shell's standard input. */
+export interface NestedStart {
+    readonly floors?: ReadonlyMap<string, readonly FloorValue[]>;
+    readonly as?: TargetUser;
+    readonly stdin?: readonly StdinText[];
+}
+/** Where a text run later starts ({@link NestedStart}): the later start, with the shell's standard input, the floors of the
+ *  words that hand it on, and — run as another user — that user's `HOME` (the caller's, the target's, or either) and, for
+ *  a login shell, the target's home as its working directory. */
+export declare function startedAt(later: PlanStart, at: NestedStart | undefined): PlanStart;
+/** A planner that plans each text once per start: a segment read in several readings hands most of its nested texts (a
+ *  substitution's body, a launched shell's text) on alike in every reading. */
+export declare function plannedOnce<K, P>(plan: (text: string, kind: K, at?: NestedStart) => P): (text: string, kind: K, at?: NestedStart) => P;
+/**
+ * What arrives on each segment's standard input: the pipe it is reached through (`piped`, what the segment before it
+ * prints); else the input of the group (`{ …; }`, `( … )`) it stands in — a group a pipe feeds hands each member that
+ * pipe; else the input the text itself was handed (`start`: a shell's `-c` text reads that shell's standard input).
+ */
+export declare function stdinFeeds(segments: readonly LexedSegment[], start: readonly StdinText[], piped: (si: number) => readonly StdinText[]): (si: number) => readonly StdinText[];
+/**
+ * A nested plan (a substitution body, a here-document's substitution, a launcher's command string) was parsed
+ * against the declarations' working directory; the segment it sits in may stand elsewhere (`cd sub && cat <<EOF
+ * $(cat secret)`), so its relative candidates are re-based onto the ENCLOSING segment's bases — every base the
+ * nested text derived from the start is carried over by prefix, an unsettled enclosing base leaves every
+ * relative candidate unplaced, and absolute candidates are untouched. Recursive: a nested plan's own nested plans
+ * derive from the same start.
+ */
+export declare function rebasePlan(plan: ShellReadPlan, from: string, to: ReadCandidate["bases"]): ShellReadPlan;

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

@@ -0,0 +1,92 @@
+const ROOT_HOMES = ["/root", "/var/root"];
+export function startedAt(later, at) {
+    if (at === undefined)
+        return later;
+    const fed = at.stdin !== undefined && at.stdin.length > 0 ? { ...later, stdin: at.stdin } : later;
+    const withFloors = at.floors === undefined || at.floors.size === 0 ? fed : { ...fed, inherited: { ...fed.inherited, floors: joinedFloors(fed.inherited.floors, at.floors) } };
+    const as = at.as;
+    if (as === undefined || as.home === "caller")
+        return withFloors;
+    const homes = as.name === "root" ? ROOT_HOMES : undefined;
+    const target = homes === undefined ? "unknown" : homes.map((spelled) => ({ spelled }));
+    const caller = later.initial("HOME");
+    const home = as.home === "target" ? target : caller === "unknown" || target === "unknown" ? "unknown" : [...caller, ...target];
+    return {
+        ...withFloors,
+        initial: (name) => (name === "HOME" ? home : withFloors.initial(name)),
+        homeTouched: true,
+        ...(as.login ? { bases: homes ?? "unmodelled" } : {}),
+    };
+}
+export function plannedOnce(plan) {
+    const planned = new Map();
+    return (text, kind, at) => {
+        const key = JSON.stringify([kind, text, [...(at?.floors ?? [])], at?.as, at?.stdin]);
+        if (!planned.has(key))
+            planned.set(key, plan(text, kind, at));
+        return planned.get(key);
+    };
+}
+function joinedFloors(a, b) {
+    const out = new Map(a);
+    for (const [name, floors] of b)
+        out.set(name, [...(out.get(name) ?? []), ...floors]);
+    return out;
+}
+export function stdinFeeds(segments, start, piped) {
+    const opener = [];
+    const enclosing = [];
+    const open = [];
+    segments.forEach((segment, si) => {
+        enclosing[si] = open.at(-1);
+        let opens = false;
+        for (const t of segment.tokens) {
+            if ((t.kind === "group" && t.op === "(") || (t.kind === "word" && t.raw === "{")) {
+                open.push(si);
+                opens = true;
+            }
+            else if ((t.kind === "group" && t.op === ")") || (t.kind === "word" && t.raw === "}"))
+                open.pop();
+        }
+        opener[si] = opens ? si : enclosing[si];
+    });
+    const fedAt = (si) => {
+        if (si > 0 && segments[si].connector === "|")
+            return [...new Map(piped(si).map((s) => [JSON.stringify(s), s])).values()];
+        const group = opener[si] !== si ? opener[si] : enclosing[si];
+        return group !== undefined ? fedAt(group) : start;
+    };
+    return fedAt;
+}
+export function rebasePlan(plan, from, to) {
+    if (to !== "unmodelled" && to.length === 1 && to[0] === from)
+        return plan;
+    const fromSep = from.endsWith("/") || from.endsWith("\\") ? from : `${from}/`;
+    const moveBase = (b) => {
+        if (to === "unmodelled")
+            return [];
+        if (b === from)
+            return [...to];
+        if (b.startsWith(fromSep))
+            return to.map((t) => `${t.endsWith("/") || t.endsWith("\\") ? t : `${t}/`}${b.slice(fromSep.length)}`);
+        return [b];
+    };
+    const moveCandidate = (c) => {
+        if (c.bases === "unmodelled" || c.bases.length === 0)
+            return c;
+        if (to === "unmodelled")
+            return { ...c, bases: "unmodelled" };
+        return { ...c, bases: [...new Set(c.bases.flatMap(moveBase))] };
+    };
+    return {
+        ...plan,
+        segments: plan.segments.map((s) => ({
+            ...s,
+            reads: s.reads.map(moveCandidate),
+            redirects: s.redirects.map((r) => (r.target === undefined ? r : { ...r, target: moveCandidate(r.target) })),
+            ...(s.baseMove !== undefined ? { baseMove: { target: typeof s.baseMove.target === "string" ? s.baseMove.target : moveCandidate(s.baseMove.target) } } : {}),
+            bases: s.bases === "unmodelled" || to === "unmodelled" ? "unmodelled" : [...new Set(s.bases.flatMap(moveBase))],
+            nested: s.nested.map((n) => rebasePlan(n, from, to)),
+        })),
+    };
+}

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

@@ -18,7 +18,7 @@ export interface Read {
     readonly raw: string;
     readonly folded: string;
     /** A pattern's names are matched by this spelling where it is not {@link folded} (a class the judge widens, read as
-     *  any one character — {@link LexedWord.judged}, {@link patternOf}); `folded` stays the name opened where none match. */
+     *  any one character — {@link LexedWord.judged}, {@link judgedSpellingOf}); `folded` stays the name opened where none match. */
     readonly pattern?: string;
     readonly expands: WordExpands;
     /** The names the word refers to were read through the table: its expansion IS the spelling above (and, where the
@@ -38,17 +38,46 @@ export interface Read {
 /** The reads of a segment's words against the binding table at that segment (`homeDir` = the declared home, the
  *  state `HOME` starts in). A word that refers to no name, or only to a `HOME` the text has not touched (`~/x`, placed
  *  by the establishment at the declared home), reads as written. */
-export declare function readsOf(words: readonly LexedWord[], table: BindingTable | undefined, homeDir: string | undefined): Read[];
+export declare function readsOf(words: readonly LexedWord[], table: BindingTable | undefined, homeDir: string | undefined, split?: boolean): Read[];
+/** One reading of a segment: the binding table with each name its words read held to ONE value (or, past
+ *  {@link READINGS_MAX}, made unknown — every value it held stays a deny-floor spelling, {@link BindingTable.floorOf}),
+ *  the reads of its argv against it ({@link readsOf}), and the argv the shell hands the program in it — a word whose
+ *  names settle into one value that is no pattern is that value, as a literal word (a reader of the program position,
+ *  of a launcher's fields, of a program's options reads it as it reads a literal word); any other word as written, its
+ *  names' deny floors in `floors` (a shell that re-reads the word — `sh -c`, `eval`, a launcher's shell — starts with
+ *  them: the word names in that text what it names here). */
+export interface SegmentReading {
+    readonly table: BindingTable;
+    readonly reads: readonly Read[];
+    readonly argv: readonly LexedWord[];
+    readonly floors: ReadonlyMap<string, readonly FloorValue[]>;
+}
+/**
+ * The readings of one segment's words (its argv and its redirection targets): the names they read through the table that
+ * may hold several values here, in the order the words read them (the program position first), each held to one value
+ * per reading — every combination while the readings stay within {@link READINGS_MAX}, so the program position, a
+ * launcher's fields, a re-entered text and an operand are spelled from the same values (`$P` read twice takes one value
+ * in a reading: the shell expands both alike); a name past that bound is unknown in every reading — its word as written,
+ * every value it held a deny floor — never a sample of its combinations. A segment whose names hold one value each has
+ * one reading.
+ */
+export declare function segmentReadingsOf(argv: readonly LexedWord[], targets: readonly LexedWord[], table: BindingTable, homeDir: string | undefined): SegmentReading[];
 /** The spelling a reader names a value by, read directly as a path — for a pattern, the name the program opens where it
  *  matches nothing: its text, a leading `~` spelled as the literal tilde it is ({@link literalTildeSpelling}, the lexer's
  *  spelling of a written one) — the shell never tilde-expands what a quoted piece or an expansion produced, so a value that
  *  starts with `~` starts with a literal one (`X=/w; rm \~$X/*` reads `./~/w/*`, as `rm \~/w/*` does). A shell that
  *  re-parses the value reads {@link programTextOf} instead. */
 export declare const spellingOf: (v: BoundValue) => string;
-/** The spelling a pattern value's names are matched by, where it is not {@link spellingOf}: its runs as a reader judges
- *  them (a class the judge widens as `?`, the lexer's `WordExpansion.pattern.judged`) — a candidate's
- *  `pattern`. */
-export declare function patternOf(v: BoundValue): string | undefined;
+/** The pattern a PART of a pattern word is matched by (an option value attached to its option word, `--file=["!"a]*`; an
+ *  assignment-shaped word's value, `if=["!"a]*`): the word's own judged spelling (`pattern`) past the text in front of
+ *  the part — bash expands the WHOLE word, so the names the part may take are those the word's widened spelling reaches
+ *  (a superset: a name is judged whether or not the word in front of it matches too). `undefined` where the word carries
+ *  none, the part is not the end of the word's spelling, or the text in front holds a widened class itself (its judged
+ *  spelling no longer lines up). */
+export declare function partPattern(word: {
+    readonly folded: string;
+    readonly pattern?: string;
+}, part: string): string | undefined;
 /** A candidate under another name (a value of several, a backup, a copy's child): the word's `pattern` matched the word,
  *  not that name — the name is matched by its own text. */
 export declare function renamed<C extends {