@sema-agent/core 7.52.0 → 7.54.0

package/dist/shell/lex.js

@@ -2,13 +2,14 @@ import { shellWordsOf } from "./shell-words.js";
 export const SHELL_LEX_DIALECT = "bash";
 export const QUOTE_KINDS = Object.freeze(["'", '"', "$'", '$"', "\\"]);
 export const EXPANSION_KINDS = Object.freeze(["parameter", "command", "process", "arithmetic", "tilde", "brace", "glob"]);
-export const UNRESOLVED_REASONS = Object.freeze(["ansi_c_escape", "locale_string", "parameter_text", "subscript_text", "compound_array_value"]);
+export const UNRESOLVED_REASONS = Object.freeze(["ansi_c_escape", "locale_string", "parameter_text", "subscript_text", "compound_array_value", "trailing_backslash"]);
 export const UNRESOLVED_SENTENCE = {
     ansi_c_escape: "an ANSI-C quoted word carries an escape this lexer does not fold",
     locale_string: "a locale-translated string carries text this lexer does not read",
     parameter_text: "a parameter expansion carries text this lexer does not read",
     subscript_text: "a subscript carries text this lexer does not read",
     compound_array_value: "a compound assignment value is a list this lexer does not read",
+    trailing_backslash: "a backslash ends the command, which the shell versions read differently (3.2 drops it, 5 keeps it)",
 };
 export const PARSE_FAILURE_REASONS = Object.freeze([
     "unterminated_single_quote",
@@ -19,6 +20,7 @@ export const PARSE_FAILURE_REASONS = Object.freeze([
     "unterminated_command_substitution",
     "unterminated_process_substitution",
     "unterminated_parameter_expansion",
+    "unterminated_arithmetic_expansion",
     "unterminated_heredoc",
     "undelimited_substitution",
     "redirect_without_target",
@@ -34,6 +36,7 @@ export const PARSE_FAILURE_SENTENCE = {
     unterminated_command_substitution: "a command substitution never terminates",
     unterminated_process_substitution: "a process substitution never terminates",
     unterminated_parameter_expansion: "a parameter expansion never terminates",
+    unterminated_arithmetic_expansion: "an arithmetic expansion never terminates",
     unterminated_heredoc: "a here-document body never terminates",
     undelimited_substitution: "a command substitution carries a construct this lexer cannot delimit",
     redirect_without_target: "a redirection names no target",
@@ -71,13 +74,14 @@ export const SUBSTITUTION_PLACEHOLDER = " subst";
 export const SHELL_CONTROL_PREFIXES = shellWordsOf("control_prefix");
 const COMPOUND_OPERAND_COMMANDS = new Set(["alias", "declare", "eval", "export", "let", "local", "readonly", "typeset"]);
 const GROUP_WORDS = shellWordsOf("group");
+const SCOPE_OPEN_WORDS = shellWordsOf("scope_open");
 const DEFINITION_WORDS = shellWordsOf("definition");
 const BACKGROUND_WORDS = shellWordsOf("background");
 const COMPOUND_OPEN_WORDS = shellWordsOf("compound_open");
 const CASE_ARM_WORDS = shellWordsOf("case_arms");
 const TIMER_WORDS = shellWordsOf("timer");
 export function dollarOpensQuote(text, at) {
-    const next = text[at + 1];
+    const next = text[past(text, at + 1)];
     if (next !== "'" && next !== '"')
         return false;
     let run = 0;
@@ -218,7 +222,7 @@ function heredocHeaderAt(text, from, dash, op) {
         return fail("heredoc_without_delimiter", op);
     if (/[~[]/.test(raw))
         return "undelimited";
-    const lexed = scan(raw, true);
+    const lexed = scan(raw, true, [firstSegment(raw)], 0);
     const tokens = "command" in lexed && lexed.command.segments.length === 1 ? lexed.command.segments[0].tokens : [];
     const word = tokens.length === 1 ? tokens[0] : undefined;
     if (word?.kind !== "word")
@@ -228,8 +232,9 @@ function heredocHeaderAt(text, from, dash, op) {
 }
 const BASH_READING = { heredoc: true, startComment: true };
 const BASH32_READINGS = [{ heredoc: false, startComment: true }, { heredoc: false, startComment: false }];
+const ARITHMETIC_READING = { heredoc: false, startComment: true, arithmetic: true };
 const BODY_NESTING_MAX = 64;
-function walkBody(text, open, reading, inDouble, level = 0) {
+function walkBody(text, open, reading, inDouble, level) {
     if (level > BODY_NESTING_MAX)
         return "undelimited";
     let depth = 0;
@@ -237,9 +242,10 @@ function walkBody(text, open, reading, inDouble, level = 0) {
     let wordStart = true;
     let word = "";
     let heredoc = false;
+    let innerClose;
     const owed = [];
     const nested = (at, dq) => {
-        const inner = walkBody(text, at, reading, dq, level + 1);
+        const inner = walkBody(text, at, reading.arithmetic === true ? BASH_READING : reading, dq, level + 1);
         if (typeof inner === "object" && "end" in inner) {
             heredoc ||= inner.heredoc;
             return inner.end - 1;
@@ -278,6 +284,13 @@ function walkBody(text, open, reading, inDouble, level = 0) {
                 continue;
             }
             if (c === "$" && text[k] === "{") {
+                if (opensCurrentShellSubstitution(text, k)) {
+                    const run = currentShellSubstitutionEnd(text, k, level + 1);
+                    if (typeof run !== "object" || !("end" in run))
+                        return run;
+                    j = run.end - 1;
+                    continue;
+                }
                 const close = braceExpansionEnd(text, k);
                 if (close === undefined)
                     return "unterminated";
@@ -356,7 +369,16 @@ function walkBody(text, open, reading, inDouble, level = 0) {
             word = "$";
             continue;
         }
-        if (reading.heredoc && c === "$" && text[k] === "{") {
+        if ((reading.heredoc || reading.arithmetic === true) && c === "$" && text[k] === "{") {
+            if (opensCurrentShellSubstitution(text, k)) {
+                const run = currentShellSubstitutionEnd(text, k, level + 1);
+                if (typeof run !== "object" || !("end" in run))
+                    return run;
+                j = run.end - 1;
+                wordStart = false;
+                word = "";
+                continue;
+            }
             const close = braceExpansionEnd(text, k);
             if (close === undefined)
                 return "unterminated";
@@ -383,8 +405,10 @@ function walkBody(text, open, reading, inDouble, level = 0) {
             depth++;
         else if (c === ")") {
             depth--;
+            if (depth === 1)
+                innerClose ??= j;
             if (depth === 0)
-                return owed.length > 0 ? "undelimited" : { end: j + 1, heredoc };
+                return owed.length > 0 ? "undelimited" : { end: j + 1, heredoc, ...(innerClose !== undefined ? { innerClose } : {}) };
         }
         if (!reading.heredoc) {
             wordStart = j === open ? reading.startComment && !inDouble && level === 0 : c === " " || c === "\t" || c === "\n";
@@ -398,18 +422,29 @@ function walkBody(text, open, reading, inDouble, level = 0) {
     }
     return "unterminated";
 }
-function substitutionBodyEnd(text, open, inDouble) {
-    const read = walkBody(text, open, BASH_READING, inDouble);
+function substitutionBodyEnd(text, open, inDouble, level) {
+    const arithmetic = arithmeticWalk(text, open, inDouble, level);
+    if (arithmetic !== undefined)
+        return { end: arithmetic.end, arithmetic: true };
+    const read = walkBody(text, open, BASH_READING, inDouble, level);
     if (typeof read !== "object" || !("end" in read))
         return read;
     if (!read.heredoc)
-        return read.end;
+        return { end: read.end, arithmetic: false };
     for (const reading of BASH32_READINGS) {
-        const counted = walkBody(text, open, reading, inDouble);
+        const counted = walkBody(text, open, reading, inDouble, level);
         if (counted !== "unterminated" && !(typeof counted === "object" && "end" in counted && counted.end === read.end))
             return "undelimited";
     }
-    return read.end;
+    return { end: read.end, arithmetic: false };
+}
+function arithmeticWalk(text, open, inDouble, level) {
+    if (text[past(text, open + 1)] !== "(")
+        return undefined;
+    const read = walkBody(text, open, ARITHMETIC_READING, inDouble, level);
+    if (typeof read !== "object" || !("end" in read) || read.heredoc || read.innerClose === undefined)
+        return undefined;
+    return past(text, read.innerClose + 1) === read.end - 1 ? { end: read.end, heredoc: false } : undefined;
 }
 function braceExpansionEnd(text, open) {
     let quoted;
@@ -435,7 +470,47 @@ function braceExpansionEnd(text, open) {
     }
     return undefined;
 }
-function matchedParen(text, open) {
+function opensCurrentShellSubstitution(text, open) {
+    const after = text[open + 1];
+    return after === "|" || after === " " || after === "\t" || after === "\n";
+}
+function currentShellSubstitutionEnd(text, open, level) {
+    if (level > BODY_NESTING_MAX)
+        return "undelimited";
+    const list = { from: open + (text[open + 1] === "|" ? 2 : 1), groups: 0 };
+    const read = scan(text, false, [firstSegment(text)], level, list);
+    if ("parseFailure" in read)
+        return read;
+    return list.closed === undefined ? "undelimited" : { end: list.closed, from: list.from };
+}
+function bracketExpansionEnd(text, open) {
+    let depth = 0;
+    let quoted;
+    for (let j = open; j < text.length; j++) {
+        const c = text[j];
+        if (quoted !== undefined) {
+            if (c === "\\" && quoted === '"')
+                j++;
+            else if (c === quoted)
+                quoted = undefined;
+            continue;
+        }
+        if (c === "\\") {
+            j++;
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            quoted = c;
+            continue;
+        }
+        if (c === "[")
+            depth++;
+        else if (c === "]" && --depth === 0)
+            return j + 1;
+    }
+    return undefined;
+}
+function matchedParen(text, open, level) {
     let depth = 0;
     let quoted;
     for (let j = open; j < text.length; j++) {
@@ -463,6 +538,13 @@ function matchedParen(text, open) {
             continue;
         }
         if (c === "$" && text[j + 1] === "{") {
+            if (opensCurrentShellSubstitution(text, j + 1)) {
+                const run = currentShellSubstitutionEnd(text, j + 1, level + 1);
+                if (typeof run !== "object" || !("end" in run))
+                    return run === "undelimited" ? fail("undelimited_substitution", j) : run;
+                j = run.end - 1;
+                continue;
+            }
             const close = braceExpansionEnd(text, j + 1);
             if (close === undefined)
                 return undefined;
@@ -477,9 +559,12 @@ function matchedParen(text, open) {
     return undefined;
 }
 const UNREADABLE_EXPANSION_TEXT = /[$`()<>{\\]/;
-const EXPANSION_NAME = /^[#!]?([A-Za-z_][A-Za-z0-9_]*|\d+|[@*#?$!0-])/;
+const PARAMETER = String.raw `(?:[A-Za-z_][A-Za-z0-9_]*|\d+|[*@#?$!-])`;
+const PARAMETER_HEAD = new RegExp(String.raw `^[#!]?${PARAMETER}`);
+const EXPANSION_NAME = new RegExp(String.raw `^[#!]?(${PARAMETER})`);
 const BARE_PARAMETER = /^(?:[A-Za-z_][A-Za-z0-9_]*|\d|[@*#?$!0-])/;
 const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const PER_ELEMENT_BODY = /^!?@|\[@\]|^![^}]*@$/;
 const NAME_HEAD = /^[A-Za-z_][A-Za-z0-9_]*/;
 function backtickBody(source, open) {
     let body = "";
@@ -501,7 +586,7 @@ function backtickBody(source, open) {
     }
     return undefined;
 }
-export function substitutionsInHeredocBody(body) {
+export function expansionsInHeredocBody(body) {
     const out = [];
     for (let i = 0; i < body.length; i++) {
         const ch = body[i];
@@ -513,20 +598,121 @@ export function substitutionsInHeredocBody(body) {
             const tick = backtickBody(body, i);
             if (tick === undefined)
                 return undefined;
-            out.push({ body: tick.body, kind: "command" });
+            out.push({ expansion: { kind: "command", yields: "one", body: tick.body } });
             i = tick.close;
             continue;
         }
-        if (ch === "$" && body[i + 1] === "(") {
-            const end = substitutionBodyEnd(body, i + 1, true);
-            if (typeof end !== "number")
+        if (ch !== "$")
+            continue;
+        const open = body[i + 1];
+        if (open === "(") {
+            const close = substitutionBodyEnd(body, i + 1, true, 0);
+            if (typeof close !== "object" || !("end" in close))
+                return undefined;
+            out.push({ expansion: { kind: close.arithmetic ? "arithmetic" : "command", yields: "one", body: body.slice(i + 2, close.end - 1) } });
+            i = close.end - 1;
+        }
+        else if (open === "[") {
+            const end = bracketExpansionEnd(body, i + 1);
+            if (end === undefined)
                 return undefined;
-            out.push({ body: body.slice(i + 2, end - 1), kind: body[i + 2] === "(" ? "arithmetic" : "command" });
+            out.push({ expansion: { kind: "arithmetic", yields: "one", body: body.slice(i + 2, end - 1) } });
             i = end - 1;
         }
+        else if (open === "{") {
+            if (opensCurrentShellSubstitution(body, i + 1)) {
+                const run = currentShellSubstitutionEnd(body, i + 1, 1);
+                if (typeof run !== "object" || !("end" in run))
+                    return undefined;
+                out.push({ expansion: { kind: "command", yields: "one", body: body.slice(run.from, run.end - 1) }, currentShell: true });
+                i = run.end - 1;
+                continue;
+            }
+            const end = braceExpansionEnd(body, i + 1);
+            if (end === undefined)
+                return undefined;
+            const text = body.slice(i + 2, end - 1);
+            const name = EXPANSION_NAME.exec(text)?.[1];
+            out.push({ expansion: { kind: "parameter", yields: "one", body: text, ...(name !== undefined ? { name } : {}) }, ...(UNREADABLE_EXPANSION_TEXT.test(text) ? { unresolved: "parameter_text" } : {}) });
+            i = end - 1;
+        }
+        else {
+            const head = BARE_PARAMETER.exec(body.slice(i + 1, i + 65))?.[0];
+            if (head === undefined)
+                continue;
+            out.push({ expansion: { kind: "parameter", yields: "one", name: head } });
+            i += head.length;
+        }
     }
     return out;
 }
+export function substitutionsInHeredocBody(body) {
+    const all = expansionsInHeredocBody(body);
+    if (all === undefined)
+        return undefined;
+    return all.flatMap(({ expansion: e, currentShell }) => (e.kind === "command" || e.kind === "arithmetic" ? [{ body: e.body ?? "", kind: e.kind, ...(currentShell === true ? { currentShell } : {}) }] : []));
+}
+export function heredocBodyHidesRun(body) {
+    const all = expansionsInHeredocBody(body);
+    return all === undefined || /[<>]\(/.test(body) || all.some((x) => x.unresolved !== undefined || expansionHidesRun(x.expansion));
+}
+const SUBSTITUTION_OPENER = /\$\(|`|<\(|>\(|\$\[/;
+export function parameterArithmeticTexts(body) {
+    const text = body.replace(/\\\n/g, "");
+    const head = PARAMETER_HEAD.exec(text);
+    if (head === null)
+        return {};
+    let rest = text.slice(head[0].length);
+    let subscript;
+    if (rest.startsWith("[")) {
+        const close = rest.indexOf("]");
+        subscript = rest.slice(1, close < 0 ? undefined : close);
+        rest = close < 0 ? "" : rest.slice(close + 1);
+    }
+    const offset = /^:(?![-=+?])(.*)$/s.exec(rest)?.[1];
+    return { ...(subscript !== undefined ? { subscript } : {}), ...(offset !== undefined ? { offset } : {}) };
+}
+function bodyEvaluatesText(body) {
+    const { subscript, offset } = parameterArithmeticTexts(body);
+    return (subscript !== undefined && /[A-Za-z_$]/.test(subscript)) || (offset !== undefined && /^[^}]*[A-Za-z_$]/.test(offset));
+}
+function nestedBodyEvaluatesText(text) {
+    for (let i = text.indexOf("${"); i >= 0; i = text.indexOf("${", i + 1))
+        if (bodyEvaluatesText(text.slice(i + 2)))
+            return true;
+    return false;
+}
+const TRANSFORM_FORM = new RegExp(String.raw `^${PARAMETER}(?:\[(?:'[^']*'|"(?:[^"\\]|\\.)*"|\\.|[^\]'"\\])*\])?@([A-Za-z])$`, "s");
+const RESPELLING_TRANSFORMS = new Set(["Q", "E", "A", "K", "k", "a", "U", "u", "L"]);
+const NAME_OR_KEY_LIST = /^![A-Za-z_][A-Za-z0-9_]*(?:[*@]|\[[@*]\])$/;
+const PLAIN_ARITHMETIC = /^[\s\d+\-*/%&|^~!<>=?:,()]*$/;
+export function expansionHidesRun(e) {
+    if (e.kind === "command" || e.kind === "process" || e.inner?.some(expansionHidesRun) === true)
+        return true;
+    const body = e.body?.replace(/\\\n/g, "");
+    if (body === undefined)
+        return false;
+    if (e.kind === "arithmetic")
+        return !PLAIN_ARITHMETIC.test(body);
+    return SUBSTITUTION_OPENER.test(body) || (e.kind === "parameter" && (bodyEvaluatesText(body) || parameterRereadsValue(body))) || nestedBodyEvaluatesText(body);
+}
+export function compoundValueHidesRun(w) {
+    return w.assignment?.form === "compound" && /\$(?!')|`|\[[^\]]*[$`A-Za-z_]/.test(w.assignment.value.raw);
+}
+export function transformEvaluates(body) {
+    const transform = TRANSFORM_FORM.exec(body)?.[1];
+    return transform !== undefined && !RESPELLING_TRANSFORMS.has(transform);
+}
+export function parameterRereadsValue(body) {
+    const text = body.replace(/\\\n/g, "");
+    return (text.startsWith("!") && !NAME_OR_KEY_LIST.test(text)) || transformEvaluates(text);
+}
+export function arithmeticTextIsPlain(text) {
+    return PLAIN_ARITHMETIC.test(text.replace(/\\\n/g, ""));
+}
+export function namesRedirectDescriptor(word, next) {
+    return next?.kind === "redirect" && word.expansions.length === 0 && word.quotedSpans.length === 0 && /^\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(word.raw);
+}
 export function literalTextOf(pieces) {
     return pieces.every((q) => q.literal !== undefined) ? pieces.map((q) => q.literal).join("") : undefined;
 }
@@ -717,7 +903,8 @@ class WordBuilder {
         const covering = this.pieces.find((p) => p.literal !== undefined && p.rawStart <= from && p.rawEnd >= to);
         if (covering === undefined)
             return;
-        this.carve(from, to, { kind: "tilde", yields: "one", body: this.raw.slice(from, to) });
+        const body = this.raw.slice(from, to);
+        this.carve(from, to, { kind: "tilde", yields: /[*?[]/.test(body) ? "many" : "one", body });
     }
     carveBraceAndGlob() {
         const inExp = this.inExpansion();
@@ -816,6 +1003,14 @@ class WordBuilder {
                 k = close;
             }
         }
+        const enclosed = this.pieces.filter((p) => p.expansion !== undefined);
+        if (enclosed.length > 0) {
+            for (const r of ranges) {
+                const inner = enclosed.filter((p) => p.rawStart >= r.from && p.rawEnd <= r.to).map((p) => p.expansion);
+                if (inner.length > 0)
+                    r.exp = { ...r.exp, inner };
+            }
+        }
         this.carveAll(ranges);
     }
     readAssignment() {
@@ -955,9 +1150,8 @@ class WordBuilder {
         };
     }
 }
-function scan(source, connectorsAreText) {
+function scan(source, connectorsAreText, segments, level, list) {
     const split = !connectorsAreText;
-    const segments = [{ start: 0, end: source.length, connector: "start", tokens: [], substitutions: [] }];
     const current = () => segments[segments.length - 1];
     const pendingHeredocs = [];
     let pendingRedirect;
@@ -981,7 +1175,7 @@ function scan(source, connectorsAreText) {
     const take = (ch, src) => w.emit(ch, ch, quotedBy(), src, src + 1);
     const substitution = (from, to, body, kind) => {
         const by = quotedBy();
-        w.opaque(source.slice(from, to), SUBSTITUTION_PLACEHOLDER, by, from, to, { kind, yields: kind === "command" && by === undefined ? "many" : "one", body });
+        w.opaque(source.slice(from, to), SUBSTITUTION_PLACEHOLDER, by, from, to, { kind, yields: kind !== "process" && by === undefined ? "many" : "one", body });
         current().substitutions.push(body);
     };
     const resetPosition = () => { acceptable = true; commandWord = undefined; afterLeadingRedirect = false; assignmentSeen = false; subscriptsClosed = false; timeGrammar = undefined; definitionName = false; coprocWord = undefined; };
@@ -1038,6 +1232,8 @@ function scan(source, connectorsAreText) {
             return undefined;
         }
         if (acceptable && bare && (SHELL_CONTROL_PREFIXES.has(word.folded) || GROUP_WORDS.has(word.folded))) {
+            if (list !== undefined && GROUP_WORDS.has(word.folded))
+                list.groups += SCOPE_OPEN_WORDS.has(word.folded) ? 1 : -1;
             timeGrammar = TIMER_WORDS.has(word.folded) ? "opt" : undefined;
             coprocWord = undefined;
             return undefined;
@@ -1088,7 +1284,7 @@ function scan(source, connectorsAreText) {
         pendingHeredocs.length = 0;
         return read.resume;
     };
-    for (let i = 0; i < source.length; i++) {
+    for (let i = list?.from ?? 0; i < source.length; i++) {
         if (!inSingle) {
             const j = past(source, i);
             if (j >= source.length)
@@ -1096,6 +1292,12 @@ function scan(source, connectorsAreText) {
             i = j;
         }
         const ch = source[i];
+        if (list !== undefined && ch === "}" && list.groups === 0 && !inSingle && !inDouble && !w.started && acceptable && pendingRedirect === undefined && pendingHeredoc === undefined) {
+            if (pendingHeredocs.length > 0)
+                return fail("undelimited_substitution", i);
+            list.closed = i + 1;
+            return { command: { segments: [], substitutions: [] } };
+        }
         if (ch === "$" && !inSingle && !inDouble && dollarOpensQuote(source, i)) {
             const q = next(i);
             if (source[q] === '"') {
@@ -1198,7 +1400,8 @@ function scan(source, connectorsAreText) {
         if (ch === "\\") {
             const escaped = source[i + 1];
             if (escaped === undefined) {
-                take(ch, i);
+                w.mark("trailing_backslash", w.raw.length);
+                w.opaque(ch, ch, "\\", i, i + 1, undefined);
                 continue;
             }
             if (inDouble && !"$`\"\\".includes(escaped))
@@ -1217,15 +1420,31 @@ function scan(source, connectorsAreText) {
             continue;
         }
         if (ch === "$" && source[n1] === "(") {
-            const arithmetic = source[next(n1)] === "(";
-            const end = substitutionBodyEnd(source, n1, inDouble);
-            if (typeof end !== "number")
-                return end === "unterminated" ? fail("unterminated_command_substitution", i) : end === "undelimited" ? fail("undelimited_substitution", i) : end;
-            substitution(i, end, source.slice(n1 + 1, end - 1), arithmetic ? "arithmetic" : "command");
+            const close = substitutionBodyEnd(source, n1, inDouble, level);
+            if (typeof close !== "object" || !("end" in close))
+                return close === "unterminated" ? fail("unterminated_command_substitution", i) : close === "undelimited" ? fail("undelimited_substitution", i) : close;
+            substitution(i, close.end, source.slice(n1 + 1, close.end - 1), close.arithmetic ? "arithmetic" : "command");
+            i = close.end - 1;
+            continue;
+        }
+        if (ch === "$" && source[n1] === "[") {
+            const end = bracketExpansionEnd(source, n1);
+            if (end === undefined)
+                return fail("unterminated_arithmetic_expansion", i);
+            substitution(i, end, source.slice(n1 + 1, end - 1), "arithmetic");
             i = end - 1;
             continue;
         }
         if (ch === "$" && source[n1] === "{") {
+            if (opensCurrentShellSubstitution(source, n1)) {
+                const run = currentShellSubstitutionEnd(source, n1, level + 1);
+                if (typeof run !== "object" || !("end" in run))
+                    return run === "undelimited" ? fail("undelimited_substitution", i) : run;
+                substitution(i, run.end, source.slice(run.from, run.end - 1), "command");
+                (current().currentShell ??= []).push(source.slice(run.from, run.end - 1));
+                i = run.end - 1;
+                continue;
+            }
             const end = braceExpansionEnd(source, n1);
             if (end === undefined)
                 return fail("unterminated_parameter_expansion", i);
@@ -1234,7 +1453,7 @@ function scan(source, connectorsAreText) {
             const name = EXPANSION_NAME.exec(body)?.[1];
             if (UNREADABLE_EXPANSION_TEXT.test(body))
                 w.mark("parameter_text", w.raw.length);
-            w.opaque(text, text, quotedBy(), i, end, { kind: "parameter", yields: inDouble ? "one" : "many", body, ...(name !== undefined ? { name } : {}) });
+            w.opaque(text, text, quotedBy(), i, end, { kind: "parameter", yields: inDouble && !PER_ELEMENT_BODY.test(body) ? "one" : "many", body, ...(name !== undefined ? { name } : {}) });
             i = end - 1;
             continue;
         }
@@ -1242,7 +1461,7 @@ function scan(source, connectorsAreText) {
             const head = BARE_PARAMETER.exec(source.slice(n1, n1 + 64))?.[0];
             if (head !== undefined) {
                 const text = source.slice(i, n1 + head.length);
-                w.opaque(text, text, quotedBy(), i, n1 + head.length, { kind: "parameter", yields: inDouble ? "one" : "many", name: head });
+                w.opaque(text, text, quotedBy(), i, n1 + head.length, { kind: "parameter", yields: inDouble && head !== "@" ? "one" : "many", name: head });
                 i = n1 + head.length - 1;
                 continue;
             }
@@ -1252,18 +1471,21 @@ function scan(source, connectorsAreText) {
             continue;
         }
         if ((ch === "<" || ch === ">") && source[n1] === "(") {
-            const end = substitutionBodyEnd(source, n1, false);
-            if (typeof end !== "number")
-                return end === "unterminated" ? fail("unterminated_process_substitution", i) : end === "undelimited" ? fail("undelimited_substitution", i) : end;
-            substitution(i, end, source.slice(n1 + 1, end - 1), "process");
-            i = end - 1;
+            const close = substitutionBodyEnd(source, n1, false, level);
+            if (typeof close !== "object" || !("end" in close))
+                return close === "unterminated" ? fail("unterminated_process_substitution", i) : close === "undelimited" ? fail("undelimited_substitution", i) : close;
+            substitution(i, close.end, source.slice(n1 + 1, close.end - 1), "process");
+            i = close.end - 1;
             continue;
         }
         if (ch === "(" && w.started && w.isAssignmentHead() && (acceptable || (commandWord !== undefined && COMPOUND_OPERAND_COMMANDS.has(commandWord)))) {
-            const end = matchedParen(source, i);
+            const end = matchedParen(source, i, level);
             if (end === undefined)
                 return fail("unterminated_compound_value", i);
-            const inner = scan(source.slice(i + 1, end - 1), true);
+            if (typeof end !== "number")
+                return end;
+            const value = source.slice(i + 1, end - 1);
+            const inner = scan(value, true, [firstSegment(value)], level);
             if ("parseFailure" in inner)
                 return fail(inner.parseFailure.reason, i + 1 + inner.parseFailure.at);
             const text = source.slice(i, end);
@@ -1271,6 +1493,9 @@ function scan(source, connectorsAreText) {
             w.opaque(text, text, undefined, i, end, undefined);
             w.compound = true;
             current().substitutions.push(...inner.command.substitutions);
+            const runsHere = inner.command.segments.flatMap((s) => s.currentShell ?? []);
+            if (runsHere.length > 0)
+                (current().currentShell ??= []).push(...runsHere);
             i = end - 1;
             continue;
         }
@@ -1350,6 +1575,11 @@ function scan(source, connectorsAreText) {
                 i = n1;
                 continue;
             }
+            if (ch === "<" && source[n1] === ">") {
+                pendingRedirect = { op: "<>", ...written };
+                i = n1;
+                continue;
+            }
             if (ch === ">" && (source[n1] === ">" || source[n1] === "|")) {
                 pendingRedirect = { op: source[n1] === ">" ? ">>" : ">", ...written };
                 i = n1;
@@ -1406,18 +1636,22 @@ function scan(source, connectorsAreText) {
         return tail;
     if (pendingHeredocs.length > 0)
         return fail("unterminated_heredoc", source.length);
-    const out = segments.map((s) => ({
-        text: source.slice(s.start, s.end),
-        connector: s.connector,
-        ...(s.pipesStderr ? { pipesStderr: true } : {}),
-        tokens: s.tokens,
-        substitutions: s.substitutions,
-    }));
+    const out = segments.map((s) => segmentView(source, s));
     return { command: { segments: out, substitutions: out.flatMap((s) => s.substitutions) } };
 }
+const firstSegment = (source) => ({ start: 0, end: source.length, connector: "start", tokens: [], substitutions: [] });
+const segmentView = (source, s) => ({
+    text: source.slice(s.start, s.end),
+    connector: s.connector,
+    ...(s.pipesStderr ? { pipesStderr: true } : {}),
+    tokens: s.tokens,
+    substitutions: s.substitutions,
+    ...(s.currentShell !== undefined ? { currentShell: s.currentShell } : {}),
+});
 export function lexShell(source) {
-    const pass = scan(source, false);
-    return "parseFailure" in pass ? pass : pass.command;
+    const segments = [firstSegment(source)];
+    const pass = scan(source, false, segments, 0);
+    return "parseFailure" in pass ? { ...pass, readBefore: segments.map((s) => segmentView(source, s)) } : pass.command;
 }
 export function lexShellText(source) {
     const lexed = lexShell(source);

package/dist/stores/file/index.d.ts

@@ -14,6 +14,7 @@ import type { RosterStore } from "../../agents/roster-store.js";
 import type { SessionPolicyStore } from "../../core/session-policy-store.js";
 import type { WorkflowJournalStore } from "../../core/workflow-journal-store.js";
 import type { UsageWindowStore } from "../../core/usage-window-store.js";
+import type { EngineStorageBackend } from "../../core/engine-storage-backend.js";
 export { FileCheckpointStore, type FileCheckpointStoreOptions } from "./checkpoint-store.js";
 export { FileMemoryStore } from "./memory-store.js";
 export { FileSessionRepo, type FileSessionRepoOptions } from "./session-store.js";
@@ -29,9 +30,10 @@ export { processFingerprint, isProcessLive, type ProcessFingerprint } from "./fs
 export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, type AdoptionErrorCode, type AdoptionSource, type AdoptionReport, type AdoptionReceipt, type AdoptionLegReport, type AffectedDeploymentConfig, type RootAdoptionFile, } from "./adoption/marker.js";
 export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, type AdoptionStatus, type AdoptLocalDataRootOptions, type AdoptLocalDataRootResult, type AdoptionCarriageLeg, type AdoptionCarriageLegContext, type AdoptionConfigWitnessReceipt, } from "./adoption/adopt.js";
 /**
- * design/80 — the file-backed `StorageBackend` for the local (TOC) single-user binary: the 3rd store impl
- * alongside `InMemory*` and `Pg*`, selected purely by what the embedder injects into `RunnerDeps` (no engine
- * change). Construct one over a single data root and pass its four members straight into `RunnerDeps`:
+ * design/80 — the file-backed {@link EngineStorageBackend} for the local (TOC) single-user binary, selected
+ * purely by what the embedder injects into `RunnerDeps` (no engine change). Construct one over a single data
+ * root and pass its members into the `RunnerDeps` seats of the same names (every member of the contract is
+ * one; the class's extra members — `root`, `memoryStore`, `consolidationLock` — are not seats):
  *
  * ```ts
  * const backend = new FileStorageBackend(); // ~/.ai-agent (or $AGENT_DATA_DIR)
@@ -39,8 +41,8 @@ export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdopt
  *   brain,
  *   sessionStore: backend.sessionStore,
  *   checkpointStore: backend.checkpointStore,
- *   memoryStore: backend.memoryStore,
  *   toolResultStore: backend.toolResultStore,
+ *   // …and the other seats the contract names (sessionPolicyStore, fileHistoryStore, …)
  * });
  * // …on shutdown:
  * await backend.dispose();
@@ -122,8 +124,8 @@ export type FileStorageCorruptReadInfo = CorruptReadInfo & {
     /** Present only when the read was keyed by a principal. */
     principal?: string;
 };
-export declare class FileStorageBackend {
-    /** The resolved, canonical data root all four stores live under. */
+export declare class FileStorageBackend implements EngineStorageBackend {
+    /** The resolved, canonical data root every store of this backend lives under. */
     readonly root: string;
     readonly sessionStore: SessionStore;
     readonly checkpointStore: CheckpointStore;

package/dist/stores/file/permission-rule-store.d.ts

@@ -52,7 +52,7 @@
 import type { PersistedRule, RuleTombstone } from "../../core/permission-rule-model.js";
 import type { DurableRulePartition, DurableRulePartitionProvider, PermissionRuleWriter, QuarantinedRuleAdd, RuleOwner, RuleSyncFrontier, StoredRules, WritableDurableRulePartition } from "../../core/permission-rule-store.js";
 import { PERMISSION_RULE_WRITER } from "../../core/permission-rule-store.js";
-import type { OrgRuleStatePersistence, PersistedOrgRuleState } from "../../core/permission-rule-org.js";
+import { type OrgRuleStatePersistence, type PersistedOrgRuleState } from "../../core/permission-rule-org.js";
 import type { StoreDurability, StoreFidelity } from "../../core/checkpoint-store.js";
 /**
  * The on-disk shape of one bucket. `schemaVersion` is the only field a future reader may rely on before