@sema-agent/core 7.24.1 → 7.24.3

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

@@ -0,0 +1,700 @@
+import { lexShellText, substitutionsInHeredocBody, wordsOf, literalTildeSpelling, SUBSTITUTION_PLACEHOLDER, } from "./bash-lexer.js";
+import { LAUNCHER_TABLE, SHELL_BLOCK_WORDS, programBasename, programPositionRunsShell, readProgramPosition, shellScanDeclineOf, } from "./bash-program-position.js";
+import { ASSIGNMENT_VALUE_NOT_PATHS, INTERPRETER_INLINE_PROGRAMS, NO_PATH_OPERAND_COMMANDS, POLL_LOOP_MAX_BEATS, RECURSIVE_READ_FORMS, SHELL_REENTRY_PROGRAM_RE, UNMODELLED_BASE_MOVERS, argvProgramOf, assignmentWordPayload, attachedOptionPayloads, foldHomeVariableSpelling, resolveOperandLexically, hasUnquotedExpansionMetachar, hasUnquotedGlobMetachar, inlineProgramClause, interpreterKey, isPathShapedToken, readVerbOptionSlot, sedScriptSlotFiles, segmentSelectsRecursiveRead, slotValueCandidates, suppliesFirstOperandSlot, verbFirstOperandSlot, verbOptionsArePositionIndependent, } from "./bash-readonly-classifier.js";
+import { isAbsolutePathForm } from "./safety.js";
+export const READ_CANDIDATE_PROVENANCES = [
+    "operand",
+    "option_value",
+    "stdin_redirect",
+    "write_redirect_target",
+    "env_assignment",
+    "unlisted_word",
+    "traversal_root",
+    "cd_target",
+    "program_path",
+    "script_slot_file",
+];
+const NESTING_MAX = 4;
+const BASE_CANDIDATE_MAX = 256;
+export function planShellReads(command, decl, depth = 0) {
+    const shape = { grouped: false, backgrounded: false, strayRedirection: false };
+    if (depth > NESTING_MAX)
+        return { segments: [], unreadable: `command text nested more than ${NESTING_MAX} levels deep`, shape };
+    const lexed = lexShellText(foldHomeVariableSpelling(command, decl.homeDir), { mode: "lenient" });
+    if ("reject" in lexed)
+        return { segments: [], unreadable: lexed.reject, shape };
+    const nestedPlan = (text) => planShellReads(text, decl, depth + 1);
+    const projected = lexed.segments.map((segment) => projectSegment(segment));
+    const facts = projected.map((p, si) => segmentFacts(lexed.segments[si], p, decl, nestedPlan));
+    shape.grouped = projected.some((p) => p.grouped);
+    shape.backgrounded = lexed.segments.some((s) => s.connector === "&") || facts.some((f) => f.backgrounds === true);
+    shape.strayRedirection = projected.some((p) => p.words.folded.length === 0 && p.redirects.length > 0);
+    const basesOf = facts.map(() => new Set());
+    const unmodelled = facts.map(() => false);
+    let candidates = [{ base: decl.cwd, skippedCd: -1 }];
+    let baseLost = false;
+    let andRunStart = 0;
+    let crossedAllAnd = true;
+    let crossedAnyOr = false;
+    let previousEmitted = -1;
+    const reaches = facts.map(() => undefined);
+    const loops = [];
+    const thread = (si, replay) => {
+        const f = facts[si];
+        if (previousEmitted >= 0) {
+            const connector = f.connector;
+            if (replay || connector !== "&&")
+                crossedAllAnd = false;
+            if (!replay && connector === "||")
+                crossedAnyOr = true;
+        }
+        if (f.empty)
+            return;
+        if (previousEmitted >= 0 && !crossedAllAnd)
+            andRunStart = crossedAnyOr ? si + 1 : si;
+        const pipeFed = f.connector === "|" || facts[si + 1]?.connector === "|";
+        reaches[si] ??= { andJoined: previousEmitted >= 0 && crossedAllAnd, orBroken: !crossedAllAnd && crossedAnyOr, moveProvable: f.moveProvable && !replay && !pipeFed };
+        crossedAllAnd = true;
+        crossedAnyOr = false;
+        previousEmitted = si;
+        const reachable = candidates.filter((c) => c.skippedCd < andRunStart);
+        if (baseLost)
+            unmodelled[si] = true;
+        else
+            for (const c of reachable)
+                basesOf[si].add(c.base);
+        const move = f.baseMove;
+        if (move === undefined || baseLost)
+            return;
+        if (typeof move.target === "string" || move.target.expands !== false) {
+            baseLost = true;
+            return;
+        }
+        const target = move.target.spelled;
+        const provable = reaches[si].moveProvable;
+        const branched = [];
+        for (const c of candidates) {
+            if (c.skippedCd < andRunStart) {
+                const moved = joinBase(c.base, target, decl.homeDir);
+                if (moved === undefined) {
+                    baseLost = true;
+                    return;
+                }
+                branched.push({ base: moved, skippedCd: c.skippedCd });
+            }
+            branched.push({ base: c.base, skippedCd: provable ? si : c.skippedCd });
+        }
+        const byBase = new Map();
+        for (const c of branched) {
+            const prior = byBase.get(c.base);
+            if (prior === undefined || c.skippedCd < prior.skippedCd)
+                byBase.set(c.base, c);
+        }
+        const next = [...byBase.values()];
+        if (next.length > BASE_CANDIDATE_MAX)
+            baseLost = true;
+        else
+            candidates = next;
+    };
+    for (let si = 0; si < facts.length; si++) {
+        const f = facts[si];
+        if (f.loopHead !== undefined) {
+            loops.push({ bodyStart: si + 1, beats: f.loopHead.beats });
+            thread(si, false);
+            continue;
+        }
+        if (f.loopEnd) {
+            thread(si, false);
+            const frame = loops.pop();
+            if (frame === undefined)
+                continue;
+            const body = facts.slice(frame.bodyStart, si);
+            const moves = body.some((b) => b.baseMove !== undefined);
+            if (!moves)
+                continue;
+            if (frame.beats === undefined) {
+                for (let k = frame.bodyStart; k < si; k++)
+                    unmodelled[k] = true;
+                baseLost = true;
+                continue;
+            }
+            for (let beat = 1; beat < frame.beats && !baseLost; beat++) {
+                for (let k = frame.bodyStart; k < si; k++)
+                    thread(k, true);
+            }
+            continue;
+        }
+        thread(si, false);
+    }
+    const segments = [];
+    for (let si = 0; si < facts.length; si++) {
+        const f = facts[si];
+        if (f.empty)
+            continue;
+        const bases = unmodelled[si] ? "unmodelled" : [...basesOf[si]];
+        const withBases = (c) => ({ ...c, bases: relativeSpelling(c.spelled) ? bases : [] });
+        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 } : {}),
+            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,
+            reach: reaches[si] ?? { andJoined: false, orBroken: false, moveProvable: false },
+        });
+    }
+    return { segments, shape };
+}
+function projectSegment(segment) {
+    const tokens = [...segment.tokens];
+    let grouped = tokens.some((t) => t.kind === "group");
+    for (let k = 0; k + 2 < tokens.length; k++) {
+        const [a, b, c] = [tokens[k], tokens[k + 1], tokens[k + 2]];
+        if (a.kind === "word" && b.kind === "group" && b.op === "(" && c.kind === "group" && c.op === ")" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(a.folded))
+            tokens.splice(k, 3);
+    }
+    const words = tokens.filter((t) => {
+        if (t.kind !== "word")
+            return false;
+        if (t.raw === t.folded && (t.folded === "{" || t.folded === "}")) {
+            grouped = true;
+            return false;
+        }
+        return true;
+    });
+    return {
+        words: wordsOf({ ...segment, tokens: words }),
+        argv: words,
+        redirects: tokens.filter((t) => t.kind === "redirect"),
+        grouped,
+    };
+}
+function segmentFacts(segment, p, decl, nestedPlan) {
+    const nested = [];
+    for (const body of segment.substitutions)
+        nested.push(nestedPlan(body));
+    let unreadableHeredoc = false;
+    for (const t of segment.tokens) {
+        if (t.kind !== "heredoc" || t.quoted)
+            continue;
+        const inner = substitutionsInHeredocBody(t.body);
+        if (inner === undefined) {
+            unreadableHeredoc = true;
+            continue;
+        }
+        for (const body of inner)
+            nested.push(nestedPlan(body));
+    }
+    if (unreadableHeredoc)
+        nested.push({ segments: [], unreadable: "a here-document body carries a substitution this lexer cannot delimit", shape: { grouped: false, backgrounded: false, strayRedirection: false } });
+    const redirects = p.redirects.map((r) => redirectFact(r));
+    const reads = [];
+    for (const r of redirects)
+        if (r.direction === "in" && r.target !== undefined)
+            reads.push(r.target);
+    const base = {
+        text: segment.text,
+        connector: segment.connector,
+        argv: p.argv,
+        redirects,
+        nested,
+    };
+    const toks = p.words;
+    const head = toks.folded[0];
+    if (head === "coproc" && toks.raw[0] === head && toks.folded.length > 1) {
+        const tail = (from) => ({ words: { folded: toks.folded.slice(from), raw: toks.raw.slice(from) }, argv: p.argv.slice(from), redirects: p.redirects, grouped: p.grouped });
+        const first = segmentFacts(segment, tail(1), decl, nestedPlan);
+        if (toks.folded.length < 3)
+            return { ...first, backgrounds: true };
+        const second = segmentFacts(segment, tail(2), decl, nestedPlan);
+        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, reads: [...first.reads, ...second.reads], nested: [...first.nested, ...extraNested], backgrounds: true };
+    }
+    if (head !== undefined && toks.raw[0] === head && SHELL_BLOCK_WORDS.has(head)) {
+        if (head === "for" || head === "select")
+            return { ...base, empty: false, launcherChain: [], declines: [], reads, moveProvable: false, loopHead: { beats: literalBeats(toks) }, loopEnd: false };
+        if (head === "done")
+            return { ...base, empty: false, launcherChain: [], declines: [], reads, moveProvable: false, loopEnd: true };
+        return { ...base, empty: false, launcherChain: [], declines: [], reads, moveProvable: false, loopEnd: false };
+    }
+    const pos = readProgramPosition(toks);
+    const written = pos.written;
+    if (written === undefined)
+        return { ...base, empty: toks.folded.length === 0 && redirects.length === 0 && nested.length === 0, launcherChain: [], declines: [], reads, moveProvable: false, loopEnd: false };
+    const loopHead = pos.controlWords.some((i) => toks.folded[i] === "while" || toks.folded[i] === "until") ? { beats: undefined } : undefined;
+    const launcherChain = pos.launchers.map((l) => l.name);
+    const launcherIndices = new Set(pos.launchers.map((l) => l.index));
+    const declines = [];
+    const decline = shellScanDeclineOf(pos, NO_PATH_OPERAND_COMMANDS);
+    if (decline !== undefined)
+        declines.push(decline);
+    const program = pos.program;
+    const basename = program?.basename;
+    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)
+        pushAssignment(reads, toks, k, "env_assignment");
+    for (const l of pos.launchers) {
+        const raw = toks.raw[l.index];
+        const folded = toks.folded[l.index];
+        if (isPathShapedToken(folded))
+            reads.push(bare(raw, folded, "program_path"));
+    }
+    {
+        const controlIndices = new Set(pos.controlWords);
+        const assignmentIndices = new Set(pos.assignments);
+        const chainEnd = pos.program?.index ?? toks.folded.length;
+        for (let j = 0; j < chainEnd; j++) {
+            if (launcherIndices.has(j) || controlIndices.has(j) || assignmentIndices.has(j) || j === written)
+                continue;
+            const word = toks.folded[j];
+            const raw = toks.raw[j];
+            if (word.startsWith("-") && word !== "-") {
+                for (const payload of attachedOptionPayloads(word))
+                    reads.push(bare(raw, payload, "unlisted_word"));
+                if (isPathShapedToken(word))
+                    reads.push(bare(raw, word, "unlisted_word"));
+                continue;
+            }
+            if (expandsOf(raw, word) === "unresolvable") {
+                reads.push({ spelled: word, raw, provenance: "unlisted_word", expands: "unresolvable" });
+                continue;
+            }
+            if (assignmentWordPayload(word) !== undefined) {
+                pushAssignment(reads, toks, j, "env_assignment");
+                continue;
+            }
+            reads.push(bare(raw, word, "unlisted_word"));
+        }
+    }
+    let reentry;
+    if (pos.argvFromStdin)
+        reentry = "argv";
+    if (pos.refusal !== undefined) {
+        const owner = programBasename(pos.refusal.owner);
+        const row = LAUNCHER_TABLE.get(owner);
+        if (pos.refusal.kind === "option_at_program_position" && row?.commandString !== undefined) {
+            const text = commandStringValue(row.commandString, toks, pos.refusal.option);
+            if (text !== undefined) {
+                nested.push(nestedPlan(text.value));
+                reentry = "shell";
+                unlistedWords(reads, toks, text.next, launcherIndices, "unlisted_word");
+                return { ...base, empty: false, launcherChain, ...(verb !== undefined ? { verb } : {}), reentry, declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}), loopEnd: false };
+            }
+        }
+        if (programPositionRunsShell(pos, SHELL_REENTRY_PROGRAM_RE)) {
+            reentry = "shell";
+            const first = pos.launchers[0]?.index ?? written;
+            const text = toks.folded.slice(first + 1).filter((w) => !w.startsWith("-") || w === "-").join(" ");
+            if (text.length > 0)
+                nested.push(nestedPlan(text));
+            return { ...base, empty: false, launcherChain, ...(verb !== undefined ? { verb } : {}), reentry, declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}), loopEnd: false };
+        }
+        const from = pos.launchers[0]?.index ?? written;
+        unlistedWords(reads, toks, from, launcherIndices, "unlisted_word");
+        return { ...base, empty: false, launcherChain, ...(verb !== undefined ? { verb } : {}), ...(reentry !== undefined ? { reentry } : {}), declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}), loopEnd: false };
+    }
+    if (program === undefined) {
+        if (pos.launchers.length > 0)
+            unlistedWords(reads, toks, pos.launchers[0].index, launcherIndices, "unlisted_word");
+        return { ...base, empty: false, launcherChain, ...(reentry !== undefined ? { reentry } : {}), declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}), loopEnd: false };
+    }
+    const args = toks.folded.slice(program.index + 1);
+    const rawArgs = toks.raw.slice(program.index + 1);
+    const programWordUnread = program.name.includes(SUBSTITUTION_PLACEHOLDER) || hasUnquotedExpansionMetachar(toks.raw[program.index]);
+    if (programWordUnread)
+        reads.push(bare(toks.raw[program.index], program.name, "program_path"));
+    else if (isPathShapedToken(program.name))
+        reads.push(bare(toks.raw[program.index], program.name, "program_path"));
+    if (SHELL_REENTRY_PROGRAM_RE.test(basename)) {
+        reentry = "shell";
+        const text = reentryText(basename, args);
+        if (text !== undefined)
+            nested.push(nestedPlan(text));
+        if (basename === "source" || basename === ".") {
+            const file = args.find((a) => !a.startsWith("-") || a === "-");
+            if (file !== undefined)
+                reads.push(bare(rawArgs[args.indexOf(file)], file, "operand"));
+        }
+        else if (text === undefined) {
+            const file = args.find((a) => !a.startsWith("-") || a === "-");
+            if (file !== undefined && file !== "-")
+                reads.push(bare(rawArgs[args.indexOf(file)], file, "operand"));
+        }
+        return { ...base, empty: false, launcherChain, verb: verb, reentry, declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}), loopEnd: false };
+    }
+    const interpreter = INTERPRETER_INLINE_PROGRAMS.get(interpreterKey(basename));
+    if (interpreter !== undefined && inlineProgramClause(interpreter, args) !== undefined)
+        reentry = "interpreter";
+    const moveProvable = pos.controlWords.length === 0 && pos.launchers.length === 0 && pos.assignments.length === 0 && program.name === basename;
+    let baseMove;
+    if (basename === "cd") {
+        baseMove = cdMove(args, rawArgs, reads);
+    }
+    else if (UNMODELLED_BASE_MOVERS.has(basename)) {
+        baseMove = { target: "unmodelled" };
+        unlistedWords(reads, toks, program.index, launcherIndices, "unlisted_word", program);
+    }
+    else if (listed) {
+        listedVerbCandidates(basename, args, rawArgs, reads);
+    }
+    else {
+        unlistedWords(reads, toks, program.index, launcherIndices, "unlisted_word", program);
+    }
+    if (basename === "sed" && listed) {
+        const slot = sedScriptSlotFiles(args);
+        for (const f of slot.reads)
+            reads.push(bare(f, f, "script_slot_file"));
+        for (const f of slot.writes)
+            reads.push(bare(f, f, "write_redirect_target"));
+        for (const c of slot.commands)
+            nested.push(nestedPlan(c));
+    }
+    return {
+        ...base,
+        empty: false,
+        launcherChain,
+        verb: verb,
+        ...(reentry !== undefined ? { reentry } : {}),
+        declines,
+        reads,
+        ...(baseMove !== undefined ? { baseMove } : {}),
+        moveProvable,
+        ...(loopHead !== undefined ? { loopHead } : {}),
+        loopEnd: false,
+    };
+}
+function dedupe(reads) {
+    const seen = new Set();
+    const out = [];
+    for (const c of reads) {
+        const key = `${c.provenance}\u0000${c.spelled}\u0000${c.expands}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(c);
+    }
+    return out;
+}
+function bare(raw, folded, provenance) {
+    return { spelled: folded, raw, provenance, expands: expandsOf(raw, folded) };
+}
+function expandsOf(raw, folded) {
+    if (folded.includes(SUBSTITUTION_PLACEHOLDER) || hasUnquotedExpansionMetachar(raw))
+        return "unresolvable";
+    if (hasUnquotedGlobMetachar(raw))
+        return "glob";
+    return false;
+}
+function relativeSpelling(spelled) {
+    return !(isAbsolutePathForm(spelled) || spelled.startsWith("~"));
+}
+function joinBase(base, target, homeDir) {
+    return resolveOperandLexically(base, target, homeDir);
+}
+function redirectFact(r) {
+    if (r.target === undefined)
+        return { op: r.op, direction: "dup" };
+    if (r.op === "<")
+        return { op: r.op, direction: "in", target: bare(r.target.raw, r.target.folded, "stdin_redirect") };
+    if (r.op === "<<<")
+        return { op: r.op, direction: "in" };
+    return { op: r.op, direction: "out", target: bare(r.target.raw, r.target.folded, "write_redirect_target") };
+}
+function pushAssignment(reads, toks, k, provenance) {
+    const word = toks.folded[k];
+    const payload = assignmentWordPayload(word);
+    if (payload === undefined)
+        return;
+    if (payload.kind === "value")
+        reads.push(bare(toks.raw[k], payload.value, provenance));
+    else
+        reads.push({ spelled: word, raw: toks.raw[k], provenance, expands: "unresolvable" });
+}
+function unlistedWords(reads, toks, from, launcherIndices, provenance, program) {
+    const argv = program !== undefined ? { program: program.basename, from: program.index } : argvProgramOf(toks);
+    const argvStart = argv?.from ?? toks.folded.length;
+    const slotVerb = argv?.program;
+    const declaredNotPaths = ASSIGNMENT_VALUE_NOT_PATHS.has(slotVerb ?? "");
+    const noPathOperands = slotVerb !== undefined && NO_PATH_OPERAND_COMMANDS.has(slotVerb);
+    const permutes = slotVerb === undefined || !verbOptionsArePositionIndependent(slotVerb);
+    const expanding = new Set();
+    for (let j = from; j < toks.folded.length; j++) {
+        if (launcherIndices.has(j))
+            continue;
+        if (expandsOf(toks.raw[j], toks.folded[j]) !== "unresolvable")
+            continue;
+        expanding.add(j);
+        reads.push({ spelled: toks.folded[j], raw: toks.raw[j], provenance: j === argvStart ? "program_path" : provenance, expands: "unresolvable" });
+    }
+    const positional = [];
+    let stdinOperand = false;
+    let endOfOptions = false;
+    let sawArgvOperand = false;
+    for (let j = from; j < toks.folded.length; j++) {
+        if (launcherIndices.has(j) || expanding.has(j))
+            continue;
+        const word = toks.folded[j];
+        const raw = toks.raw[j];
+        if (j > from && !endOfOptions && word === "--") {
+            endOfOptions = true;
+            continue;
+        }
+        if (noPathOperands && j >= argvStart)
+            break;
+        if (j === argvStart && !isPathShapedToken(word))
+            continue;
+        const optionShaped = !endOfOptions && word.startsWith("-") && word !== "-";
+        if (optionShaped && j > argvStart) {
+            const slot = slotVerb === undefined ? undefined : readVerbOptionSlot(slotVerb, word);
+            if (sawArgvOperand && permutes) {
+                reads.push(bare(raw, word, provenance));
+                if (slot !== undefined && slot.form === "separated") {
+                    const ahead = toks.folded[j + 1];
+                    if (ahead !== undefined && expandsOf(toks.raw[j + 1], ahead) !== "unresolvable")
+                        for (const c of slotValueCandidates(ahead, slot.kind))
+                            reads.push(bare(toks.raw[j + 1], c, "option_value"));
+                }
+            }
+            if (slot !== undefined && slot.form !== "unexplained" && !(slot.form === "separated" && sawArgvOperand && permutes)) {
+                if (slot.form === "attached") {
+                    for (const c of slotValueCandidates(literalTildeSpelling(slot.value), slot.kind))
+                        reads.push(bare(raw, c, "option_value"));
+                }
+                else if (slot.form === "separated") {
+                    j++;
+                    const value = toks.folded[j];
+                    if (value !== undefined && !expanding.has(j)) {
+                        const named = slotValueCandidates(value, slot.kind);
+                        for (const c of named)
+                            reads.push(bare(toks.raw[j], c, "option_value"));
+                        if (named.length > 0)
+                            positional.push(value);
+                    }
+                }
+                continue;
+            }
+            for (const payload of attachedOptionPayloads(word))
+                reads.push(bare(raw, payload, provenance));
+            if (isPathShapedToken(word))
+                reads.push(bare(raw, word, provenance));
+            continue;
+        }
+        if (optionShaped) {
+            for (const payload of attachedOptionPayloads(word))
+                reads.push(bare(raw, payload, provenance));
+            if (isPathShapedToken(word))
+                reads.push(bare(raw, word, provenance));
+            continue;
+        }
+        if (j > argvStart) {
+            sawArgvOperand = true;
+            if (word === "-") {
+                const m = slotVerb === undefined ? undefined : RECURSIVE_READ_FORMS[slotVerb];
+                if (m === undefined || m.dashIsStdin === true)
+                    stdinOperand = true;
+                else
+                    positional.push(word);
+            }
+            else
+                positional.push(word);
+        }
+        reads.push(bare(raw, word, j === argvStart ? "program_path" : provenance));
+        if (j < argvStart || !declaredNotPaths)
+            pushAssignment(reads, toks, j, "env_assignment");
+    }
+    if (slotVerb !== undefined && argv !== undefined && segmentSelectsRecursiveRead(slotVerb, toks.folded.slice(argvStart + 1))) {
+        const roots = positional.length > 0 ? positional : stdinOperand ? [] : ["."];
+        for (const root of roots)
+            reads.push({ spelled: root, raw: root, provenance: "traversal_root", expands: false });
+    }
+    for (let j = from; j < toks.folded.length; j++) {
+        if (launcherIndices.has(j) || j === argvStart)
+            continue;
+        const raw = toks.raw[j];
+        if (expandsOf(raw, toks.folded[j]) === "glob")
+            reads.push(bare(raw, toks.folded[j], provenance));
+    }
+}
+function commandStringValue(options, toks, option) {
+    const at = toks.folded.indexOf(option);
+    if (at < 0)
+        return undefined;
+    for (const spelling of options) {
+        if (option === spelling) {
+            const value = toks.folded[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;
+}
+function reentryText(basename, args) {
+    if (basename === "eval")
+        return args.length === 0 ? undefined : args.join(" ");
+    if (basename === "parallel")
+        return args.filter((a) => !a.startsWith("-")).join(" ") || undefined;
+    if (basename === "source" || basename === ".")
+        return undefined;
+    for (let k = 0; k < args.length; k++) {
+        const a = args[k];
+        if (a === "--")
+            return undefined;
+        if (!a.startsWith("-") || a === "-")
+            return undefined;
+        const c = a.indexOf("c");
+        if (a.startsWith("--"))
+            continue;
+        if (c > 0)
+            return a.length > c + 1 ? a.slice(c + 1) : args[k + 1];
+    }
+    return undefined;
+}
+function literalBeats(toks) {
+    const at = toks.folded.indexOf("in");
+    if (at < 0)
+        return undefined;
+    const words = toks.folded.slice(at + 1);
+    const raws = toks.raw.slice(at + 1);
+    if (words.length === 0)
+        return undefined;
+    if (words.length === 1 && words[0].includes(SUBSTITUTION_PLACEHOLDER)) {
+        const m = /^\$\(\s*seq\s+(\d+)\s+(\d+)\s*\)$/.exec(raws[0]);
+        if (m === null)
+            return undefined;
+        const beats = Number(m[2]) - Number(m[1]) + 1;
+        return beats >= 1 && beats <= POLL_LOOP_MAX_BEATS ? beats : undefined;
+    }
+    for (let k = 0; k < words.length; k++) {
+        if (expandsOf(raws[k], words[k]) !== false)
+            return undefined;
+    }
+    return words.length <= POLL_LOOP_MAX_BEATS ? words.length : undefined;
+}
+function cdMove(args, rawArgs, reads) {
+    const idx = args.findIndex((t) => !t.startsWith("-") || t === "-");
+    if (idx < 0)
+        return { target: "home" };
+    const target = args[idx];
+    if (target === "-")
+        return { target: "previous" };
+    const c = bare(rawArgs[idx], target, "cd_target");
+    reads.push(c);
+    return { target: c };
+}
+function listedVerbCandidates(name, args, rawArgs, reads) {
+    if (NO_PATH_OPERAND_COMMANDS.has(name))
+        return;
+    const expanding = new Set();
+    rawArgs.forEach((raw, k) => {
+        if (!hasUnquotedExpansionMetachar(raw))
+            return;
+        expanding.add(k);
+        reads.push({ spelled: args[k], raw, provenance: "operand", expands: "unresolvable" });
+    });
+    const eoo = args.indexOf("--");
+    const firstOperandSlot = verbFirstOperandSlot(name);
+    const firstOperandSuppliedByFlag = firstOperandSlot !== undefined && (eoo === -1 ? args : args.slice(0, eoo)).some((t) => suppliesFirstOperandSlot(firstOperandSlot, t));
+    const positional = [];
+    let sawOperand = false;
+    let stdinOperand = false;
+    let endOfOptions = false;
+    const permutes = !verbOptionsArePositionIndependent(name);
+    const push = (k, text, provenance) => {
+        reads.push(bare(rawArgs[k], text, provenance));
+    };
+    for (let k = 0; k < args.length; k++) {
+        const t = args[k];
+        if (expanding.has(k))
+            continue;
+        if (!endOfOptions) {
+            if (t === "--") {
+                endOfOptions = true;
+                continue;
+            }
+            if (t.startsWith("-") && t !== "-") {
+                const slot = readVerbOptionSlot(name, t);
+                if (sawOperand && permutes) {
+                    push(k, t, "operand");
+                    if (slot !== undefined && slot.form === "separated") {
+                        const ahead = args[k + 1];
+                        if (ahead !== undefined && !expanding.has(k + 1))
+                            for (const c of slotValueCandidates(ahead, slot.kind))
+                                push(k + 1, c, "option_value");
+                    }
+                }
+                if (slot !== undefined && slot.form !== "unexplained" && !(slot.form === "separated" && sawOperand && permutes)) {
+                    if (slot.form === "attached") {
+                        for (const c of slotValueCandidates(literalTildeSpelling(slot.value), slot.kind))
+                            push(k, c, "option_value");
+                    }
+                    else if (slot.form === "separated") {
+                        const value = args[++k];
+                        if (value !== undefined && !expanding.has(k)) {
+                            const named = slotValueCandidates(value, slot.kind);
+                            for (const c of named)
+                                push(k, c, "option_value");
+                            if (named.length > 0)
+                                positional.push(value);
+                        }
+                    }
+                    continue;
+                }
+                for (const payload of attachedOptionPayloads(t))
+                    push(k, payload, "option_value");
+                continue;
+            }
+        }
+        const inFirstOperandSlot = firstOperandSlot !== undefined && !firstOperandSuppliedByFlag && !sawOperand;
+        sawOperand = true;
+        if (t === "-") {
+            if (inFirstOperandSlot)
+                continue;
+            const m = RECURSIVE_READ_FORMS[name];
+            if (m === undefined || m.dashIsStdin === true) {
+                stdinOperand = true;
+                continue;
+            }
+            positional.push(t);
+            continue;
+        }
+        if (inFirstOperandSlot) {
+            const named = slotValueCandidates(t, firstOperandSlot.kind);
+            for (const c of named)
+                push(k, c, "operand");
+            if (named.length > 0)
+                positional.push(t);
+            continue;
+        }
+        positional.push(t);
+        push(k, t, "operand");
+        if (!ASSIGNMENT_VALUE_NOT_PATHS.has(name)) {
+            const payload = assignmentWordPayload(t);
+            if (payload?.kind === "value")
+                push(k, payload.value, "env_assignment");
+            else if (payload !== undefined)
+                reads.push({ spelled: t, raw: rawArgs[k], provenance: "env_assignment", expands: "unresolvable" });
+        }
+    }
+    for (let k = 0; k < args.length; k++) {
+        if (expanding.has(k))
+            continue;
+        if (expandsOf(rawArgs[k], args[k]) === "glob")
+            reads.push(bare(rawArgs[k], args[k], "operand"));
+    }
+    if (segmentSelectsRecursiveRead(name, args)) {
+        const roots = positional.length > 0 ? positional : stdinOperand ? [] : ["."];
+        for (const root of roots)
+            reads.push({ spelled: root, raw: root, provenance: "traversal_root", expands: false });
+    }
+}