@taliesinb/mash 0.0.0-stage → 0.1.0

package/dist/src/vm/interp.js

@@ -0,0 +1,1641 @@
+/**
+ * The tree-walking interpreter. Every command node emits a `step` event
+ * before it runs; simple commands are expanded, resolved, assessed against
+ * the policy (through {@link Runtime.assess}, which consults behavior
+ * definitions and hooks), and only then have their redirections opened and
+ * run. Pipelines run their stages concurrently over in-memory pipes; external
+ * commands are real child processes whose stdio is pumped through the VM's
+ * channels so it can be observed.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parse, ParseError, literalOf } from "../parser/parser.js";
+import { known } from "../analysis/value.js";
+import { ArithError, evaluateArith } from "./arith.js";
+import { BUILTINS } from "./builtins.js";
+import { Expander, varElements } from "./expand.js";
+import { runExternal } from "./external.js";
+import { emulateFind, emulateXargs } from "./emulate.js";
+import { BrokenPipeError, Capture, ConstInput, FdTable, FsError, HostFile, NullFile, Pipe, } from "./io.js";
+import { matchPattern } from "./pattern.js";
+import { AbortRun, CommandError, DiscardError, ExitSignal, FatalError, LoopSignal, Proc, ReturnSignal } from "./proc.js";
+import { initShellVars, newVar, ShellState } from "./state.js";
+import { evalCond, evalTest } from "./test.js";
+export class Interpreter {
+    rt;
+    expander;
+    constructor(rt) {
+        this.rt = rt;
+        this.expander = new Expander({
+            commandSubst: (node, proc) => this.commandSubst(node, proc),
+            processSubst: (node, proc) => this.processSubst(node, proc),
+            arith: (expr, proc) => this.arith(expr, proc),
+            assign: (proc, name, value) => this.assignScalar(proc, name, value),
+            dynamic: (proc, name) => this.dynamicVar(proc, name),
+            shellPid: rt.shellPid,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Entry points
+    // -------------------------------------------------------------------------
+    /** Run a parsed script in `proc` (the top-level shell). Returns the exit status. */
+    async runTop(script, proc) {
+        let status = 0;
+        try {
+            status = await this.execTopLevel(script, proc);
+        }
+        catch (e) {
+            status = this.handleTermination(e, proc);
+        }
+        status = await this.runExitTrap(proc, status);
+        return status;
+    }
+    /**
+     * Execute a script's top-level statements like bash reads them: an
+     * expansion error discards only the current top-level command, and a
+     * syntax error further down (partial parse) is reported when reached.
+     */
+    async execTopLevel(script, proc) {
+        let status = proc.state.lastStatus;
+        let discardedLine = -1;
+        for (const stmt of script.body) {
+            // bash reads one line (a newline-terminated list) at a time; a discard drops the rest of it
+            if (this.rt.line(stmt) === discardedLine)
+                continue;
+            try {
+                status = await this.execStmt(stmt, proc);
+            }
+            catch (e) {
+                if (!(e instanceof DiscardError))
+                    throw e;
+                this.errorMessage(proc, e.message);
+                status = e.status;
+                proc.state.lastStatus = status;
+                discardedLine = this.rt.line(stmt);
+            }
+        }
+        if (script.error) {
+            this.errorMessage(proc, `syntax error: ${script.error.message}`);
+            throw new ExitSignal(2);
+        }
+        return status;
+    }
+    handleTermination(e, proc) {
+        if (e instanceof ExitSignal)
+            return e.status;
+        if (e instanceof FatalError || e instanceof DiscardError) {
+            this.errorMessage(proc, e.message);
+            return e.status;
+        }
+        if (e instanceof ReturnSignal)
+            return e.status;
+        if (e instanceof LoopSignal)
+            return 0;
+        if (e instanceof BrokenPipeError)
+            return 141;
+        throw e;
+    }
+    async runExitTrap(proc, status) {
+        const trap = proc.state.traps.get('EXIT');
+        if (trap === undefined || trap === '')
+            return status;
+        proc.state.traps.delete('EXIT');
+        proc.state.lastStatus = status;
+        try {
+            const script = this.rt.parse(trap, 'trap EXIT');
+            await this.execList(script.body, proc);
+        }
+        catch (e) {
+            if (e instanceof ExitSignal)
+                return e.status;
+            if (e instanceof AbortRun)
+                throw e;
+            if (!(e instanceof ParseError || e instanceof FatalError || e instanceof DiscardError || e instanceof ReturnSignal))
+                throw e;
+            if (e instanceof FatalError || e instanceof DiscardError)
+                this.errorMessage(proc, e.message);
+        }
+        return status;
+    }
+    // -------------------------------------------------------------------------
+    // Output helpers
+    // -------------------------------------------------------------------------
+    async write(proc, fd, text) {
+        const f = proc.fds.get(fd);
+        if (!f || !f.writable) {
+            if (fd === 1)
+                throw new CommandError('write error: Bad file descriptor');
+            return;
+        }
+        await f.write(text);
+    }
+    errorMessage(proc, message) {
+        const f = proc.fds.get(2);
+        this.rt.emit({ type: 'error', message, pid: proc.pid });
+        if (f?.writable)
+            f.write(`mash: ${message}\n`).catch(() => { });
+    }
+    // -------------------------------------------------------------------------
+    // Lists and statements
+    // -------------------------------------------------------------------------
+    async execList(stmts, proc) {
+        let status = proc.state.lastStatus;
+        for (const stmt of stmts) {
+            status = await this.execStmt(stmt, proc);
+        }
+        return status;
+    }
+    async execStmt(stmt, proc) {
+        if (this.rt.signal.aborted)
+            throw new AbortRun('aborted', 130);
+        if (proc.state.options.noexec)
+            return 0;
+        if (stmt.background) {
+            this.startBackground(stmt, proc);
+            proc.state.lastStatus = 0;
+            return 0;
+        }
+        const status = await this.execCommand(stmt.command, proc);
+        proc.state.lastStatus = status;
+        return status;
+    }
+    startBackground(stmt, proc) {
+        const pid = this.rt.nextPid();
+        const child = proc.subshell(pid);
+        // background jobs do not read the terminal: stdin is /dev/null unless redirected
+        const stdin = proc.fds.get(0);
+        if (stdin && (stdin.channel.kind === 'host'))
+            child.fds.set(0, new NullFile(this.rt.channel('null', '/dev/null'), this.rt.listeners));
+        const ac = new AbortController();
+        child.jobSignal = ac.signal;
+        child.jobChildren = new Set();
+        const children = child.jobChildren;
+        const job = {
+            pid,
+            nodeId: stmt.id,
+            status: null,
+            done: Promise.resolve(0),
+            kill: (sig = 'SIGTERM') => {
+                ac.abort();
+                for (const c of children)
+                    c.kill(sig);
+            },
+        };
+        this.rt.emit({ type: 'job:start', jobPid: pid, nodeId: stmt.id });
+        job.done = this.runSubshell(child, () => this.execCommand(stmt.command, child), 'background', stmt.id).then((s) => {
+            job.status = s;
+            this.rt.emit({ type: 'job:end', jobPid: pid, status: s });
+            return s;
+        });
+        proc.jobs.set(pid, job);
+        this.rt.registerJob(job);
+        proc.state.lastBgPid = pid;
+    }
+    /** Run `fn` as the body of subshell `child`, handling exit, traps and fd cleanup. */
+    async runSubshell(child, fn, reason, nodeId) {
+        this.rt.emit({ type: 'subshell:start', pid: child.pid, parentPid: child.parentPid, nodeId, reason });
+        let status;
+        try {
+            try {
+                status = await fn();
+            }
+            catch (e) {
+                if (e instanceof AbortRun)
+                    throw e;
+                status = this.handleTermination(e, child);
+                // bash 5: an unbound variable or ${x:?} ends a ( … ) subshell with status 1
+                // (the top-level shell still exits with 127; bash 3.2 uses 127 for both)
+                if (reason === 'subshell' && e instanceof FatalError && e.status === 127)
+                    status = 1;
+            }
+            status = await this.runExitTrap(child, status);
+        }
+        finally {
+            child.fds.closeAll();
+        }
+        this.rt.emit({ type: 'subshell:end', pid: child.pid, status });
+        return status;
+    }
+    inErrTrap = false;
+    /** After a failing command outside a condition: run the ERR trap, then apply `set -e`. */
+    async checkErrexit(status, proc) {
+        if (status === 0 || proc.errexitSuppressed > 0)
+            return;
+        const trap = proc.state.traps.get('ERR');
+        if (trap && !this.inErrTrap) {
+            this.inErrTrap = true;
+            try {
+                proc.state.lastStatus = status;
+                await this.execList(this.rt.parse(trap, 'trap ERR').body, proc.derive({ suppress: true }));
+            }
+            finally {
+                this.inErrTrap = false;
+            }
+            proc.state.lastStatus = status;
+        }
+        if (proc.state.options.errexit)
+            throw new ExitSignal(status);
+    }
+    step(node, proc) {
+        if (this.rt.signal.aborted)
+            throw new AbortRun('aborted', 130);
+        if (proc.jobSignal?.aborted)
+            throw new ExitSignal(143);
+        proc.line = this.rt.line(node);
+        this.rt.emit({ type: 'step', nodeId: node.id, span: node.span, line: proc.line, node: node.type, pid: proc.pid, depth: proc.depth });
+    }
+    stepCount = 0;
+    async execCommand(cmd, proc) {
+        // In-process loops only await microtasks while pipes have room; yield to
+        // the event loop regularly so child I/O (and the host) is never starved.
+        if (++this.stepCount % 64 === 0)
+            await new Promise((r) => setImmediate(r));
+        this.step(cmd, proc);
+        switch (cmd.type) {
+            case 'SimpleCommand': {
+                const s = await this.execSimple(cmd, proc);
+                // a lone command is a pipeline of one: PIPESTATUS=($?)
+                this.setPipestatus(proc, [s]);
+                await this.checkErrexit(s, proc);
+                return s;
+            }
+            case 'Pipeline': {
+                const s = await this.execPipeline(cmd, proc);
+                if (!cmd.negated)
+                    await this.checkErrexit(s, proc);
+                return s;
+            }
+            case 'AndOr':
+                return this.execAndOr(cmd, proc);
+            case 'FunctionDef':
+                proc.state.functions.set(cmd.name, { def: cmd });
+                return 0;
+            default:
+                return this.withCompoundRedirects(cmd, proc, async (p) => {
+                    const s = await this.execCompound(cmd, p);
+                    if (cmd.type === 'Subshell' || cmd.type === 'ArithCommand' || cmd.type === 'CondCommand') {
+                        this.setPipestatus(p, [s]);
+                        await this.checkErrexit(s, p);
+                    }
+                    return s;
+                });
+        }
+    }
+    async execCompound(cmd, proc) {
+        switch (cmd.type) {
+            case 'Group':
+                return this.execList(cmd.body, proc);
+            case 'Subshell': {
+                const child = proc.subshell(this.rt.nextPid());
+                return this.runSubshell(child, () => this.execList(cmd.body, child), 'subshell', cmd.id);
+            }
+            case 'If':
+                return this.execIf(cmd, proc);
+            case 'Loop':
+                return this.execLoop(cmd, proc);
+            case 'For':
+                return this.execFor(cmd, proc);
+            case 'ArithFor':
+                return this.execArithFor(cmd, proc);
+            case 'Select':
+                return this.execSelect(cmd, proc);
+            case 'Case':
+                return this.execCase(cmd, proc);
+            case 'ArithCommand': {
+                try {
+                    const v = await this.arith(cmd.expr, proc);
+                    return v !== 0n ? 0 : 1;
+                }
+                catch (e) {
+                    if (e instanceof ArithError) {
+                        this.errorMessage(proc, `((: ${e.message}`);
+                        return 1;
+                    }
+                    throw e;
+                }
+            }
+            case 'CondCommand': {
+                try {
+                    return (await evalCond(cmd.expr, proc, this)) ? 0 : 1;
+                }
+                catch (e) {
+                    if (e instanceof CommandError) {
+                        this.errorMessage(proc, e.message);
+                        return 2;
+                    }
+                    throw e;
+                }
+            }
+        }
+    }
+    async execAndOr(cmd, proc) {
+        const suppressed = proc.derive({ suppress: true });
+        let status = await this.execCommand(cmd.items[0], cmd.items.length > 1 ? suppressed : proc);
+        for (let i = 1; i < cmd.items.length; i++) {
+            const op = cmd.ops[i - 1];
+            proc.state.lastStatus = status;
+            if ((op === '&&' && status !== 0) || (op === '||' && status === 0))
+                continue;
+            const last = i === cmd.items.length - 1;
+            status = await this.execCommand(cmd.items[i], last ? proc : suppressed);
+        }
+        return status;
+    }
+    async execIf(cmd, proc) {
+        const cond = proc.derive({ suppress: true });
+        for (let i = 0; i < cmd.clauses.length; i++) {
+            const c = cmd.clauses[i];
+            const s = await this.execList(c.cond, cond);
+            if (s === 0) {
+                this.rt.emit({ type: 'branch', nodeId: cmd.id, taken: i, pid: proc.pid });
+                return this.execList(c.body, proc);
+            }
+        }
+        if (cmd.elseBody) {
+            this.rt.emit({ type: 'branch', nodeId: cmd.id, taken: 'else', pid: proc.pid });
+            return this.execList(cmd.elseBody, proc);
+        }
+        this.rt.emit({ type: 'branch', nodeId: cmd.id, taken: 'none', pid: proc.pid });
+        return 0;
+    }
+    /** Run a loop body; returns 'break' / 'continue' / status. */
+    async loopBody(body, proc) {
+        try {
+            return { status: await this.execList(body, proc) };
+        }
+        catch (e) {
+            if (e instanceof LoopSignal) {
+                if (e.levels > 1) {
+                    e.levels--;
+                    throw e;
+                }
+                return { status: 0, ctl: e.kind };
+            }
+            throw e;
+        }
+    }
+    async execLoop(cmd, proc) {
+        let status = 0;
+        let iteration = 0;
+        const inner = proc.derive({ loop: true });
+        const cond = inner.derive({ suppress: true });
+        for (;;) {
+            let c;
+            try {
+                c = await this.execList(cmd.cond, cond);
+            }
+            catch (e) {
+                if (e instanceof LoopSignal && e.levels <= 1) {
+                    if (e.kind === 'break')
+                        break;
+                    continue;
+                }
+                if (e instanceof LoopSignal)
+                    e.levels--;
+                throw e;
+            }
+            if ((cmd.kind === 'while') !== (c === 0))
+                break;
+            iteration++;
+            this.rt.emit({ type: 'loop:iteration', nodeId: cmd.id, iteration, pid: proc.pid });
+            const r = await this.loopBody(cmd.body, inner);
+            status = r.status;
+            if (r.ctl === 'break')
+                break;
+        }
+        return status;
+    }
+    async execFor(cmd, proc) {
+        const items = cmd.items === null ? [...proc.state.positional] : await this.expandFieldsChecked(cmd.items, proc);
+        let status = 0;
+        let iteration = 0;
+        const inner = proc.derive({ loop: true });
+        for (const item of items) {
+            iteration++;
+            this.assignScalar(proc, cmd.variable, item);
+            this.rt.emit({ type: 'loop:iteration', nodeId: cmd.id, iteration, variable: cmd.variable, value: item, pid: proc.pid });
+            const r = await this.loopBody(cmd.body, inner);
+            status = r.status;
+            if (r.ctl === 'break')
+                break;
+        }
+        return status;
+    }
+    async execSelect(cmd, proc) {
+        // Non-interactive: print the menu to stderr, read choices from stdin.
+        const items = cmd.items === null ? [...proc.state.positional] : await this.expandFieldsChecked(cmd.items, proc);
+        let status = 0;
+        const inner = proc.derive({ loop: true });
+        for (;;) {
+            await this.write(proc, 2, items.map((it, i) => `${i + 1}) ${it}\n`).join('') + (proc.state.getString('PS3') ?? '#? '));
+            const stdin = proc.fds.get(0);
+            const line = stdin ? await stdin.readUntil(10) : null;
+            if (line === null)
+                return status;
+            const reply = new TextDecoder().decode(line).replace(/\n$/, '');
+            this.assignScalar(proc, 'REPLY', reply);
+            const n = Number(reply);
+            this.assignScalar(proc, cmd.variable, Number.isInteger(n) && n >= 1 && n <= items.length ? items[n - 1] : '');
+            const r = await this.loopBody(cmd.body, inner);
+            status = r.status;
+            if (r.ctl === 'break')
+                break;
+        }
+        return status;
+    }
+    async execArithFor(cmd, proc) {
+        const ev = async (e) => {
+            try {
+                return await this.arith(e, proc);
+            }
+            catch (err) {
+                if (err instanceof ArithError)
+                    throw new DiscardError(err.message);
+                throw err;
+            }
+        };
+        let status = 0;
+        let iteration = 0;
+        const inner = proc.derive({ loop: true });
+        await ev(cmd.init);
+        for (;;) {
+            if (cmd.cond && (await ev(cmd.cond)) === 0n)
+                break;
+            iteration++;
+            this.rt.emit({ type: 'loop:iteration', nodeId: cmd.id, iteration, pid: proc.pid });
+            const r = await this.loopBody(cmd.body, inner);
+            status = r.status;
+            if (r.ctl === 'break')
+                break;
+            await ev(cmd.step);
+        }
+        return status;
+    }
+    async execCase(cmd, proc) {
+        const word = await this.expander.expandString(cmd.word, proc);
+        const nocase = proc.state.shopts.has('nocasematch');
+        let status = 0;
+        let fallthrough = false;
+        for (let i = 0; i < cmd.items.length; i++) {
+            const item = cmd.items[i];
+            let matched = fallthrough;
+            if (!matched) {
+                for (const p of item.patterns) {
+                    const pat = await this.expander.expandPattern(p, proc);
+                    if (matchPattern(word, pat, { nocase })) {
+                        matched = true;
+                        break;
+                    }
+                }
+            }
+            if (!matched)
+                continue;
+            this.rt.emit({ type: 'branch', nodeId: cmd.id, taken: i, pid: proc.pid });
+            status = await this.execList(item.body, proc);
+            if (item.terminator === ';;')
+                return status;
+            fallthrough = item.terminator === ';&';
+        }
+        if (!fallthrough)
+            this.rt.emit({ type: 'branch', nodeId: cmd.id, taken: 'none', pid: proc.pid });
+        return status;
+    }
+    // -------------------------------------------------------------------------
+    // Pipelines
+    // -------------------------------------------------------------------------
+    async execPipeline(cmd, proc) {
+        const start = Date.now();
+        const n = cmd.stages.length;
+        const stageProc = cmd.negated ? proc.derive({ suppress: true }) : proc;
+        let statuses;
+        if (n === 1) {
+            statuses = [await this.execCommand(cmd.stages[0], stageProc)];
+        }
+        else {
+            const pipes = [];
+            for (let i = 0; i < n - 1; i++) {
+                const label = `${this.rt.text(cmd.stages[i])} | ${this.rt.text(cmd.stages[i + 1])}`;
+                const ch = this.rt.channel('pipe', label, { nodeId: cmd.id });
+                pipes.push(new Pipe(ch, this.rt.listeners));
+            }
+            const runs = cmd.stages.map((stage, i) => {
+                const child = stageProc.subshell(this.rt.nextPid());
+                if (i > 0)
+                    child.fds.set(0, pipes[i - 1].readEnd.retain());
+                if (i < n - 1) {
+                    child.fds.set(1, pipes[i].writeEnd.retain());
+                    if (cmd.pipeStderr[i])
+                        child.fds.dup(1, 2);
+                }
+                return this.runSubshell(child, () => this.execCommand(stage, child), 'pipeline', stage.id);
+            });
+            for (const p of pipes) {
+                p.readEnd.release();
+                p.writeEnd.release();
+            }
+            statuses = await Promise.all(runs);
+        }
+        this.setPipestatus(proc, statuses);
+        let status = statuses[statuses.length - 1];
+        if (proc.state.options.pipefail) {
+            for (let i = statuses.length - 1; i >= 0; i--) {
+                if (statuses[i] !== 0) {
+                    status = statuses[i];
+                    break;
+                }
+            }
+        }
+        if (cmd.timed) {
+            const secs = (Date.now() - start) / 1000;
+            await this.write(proc, 2, `\nreal\t${Math.floor(secs / 60)}m${(secs % 60).toFixed(3)}s\nuser\t0m0.000s\nsys\t0m0.000s\n`).catch(() => { });
+        }
+        if (cmd.negated)
+            status = status === 0 ? 1 : 0;
+        return status;
+    }
+    setPipestatus(proc, statuses) {
+        const values = new Map();
+        statuses.forEach((s, i) => values.set(i, String(s)));
+        proc.state.globals.set('PIPESTATUS', newVar({ kind: 'indexed', values }));
+    }
+    // -------------------------------------------------------------------------
+    // Simple commands
+    // -------------------------------------------------------------------------
+    async expandFieldsChecked(words, proc) {
+        return this.expander.expandFields(words, proc);
+    }
+    async execSimple(cmd, proc) {
+        const mark = proc.procSubstFds.length;
+        try {
+            return await this.execSimpleInner(cmd, proc);
+        }
+        catch (e) {
+            if (e instanceof CommandError) {
+                this.errorMessage(proc, e.message);
+                return e.status;
+            }
+            throw e;
+        }
+        finally {
+            this.closeProcSubsts(proc, mark);
+        }
+    }
+    closeProcSubsts(proc, mark) {
+        while (proc.procSubstFds.length > mark) {
+            const { fds, fd } = proc.procSubstFds.pop();
+            fds.close(fd);
+        }
+    }
+    /** `expand_aliases`: re-parse the command with the alias text substituted for its first word. */
+    async expandAlias(cmd, proc) {
+        const st = proc.state;
+        if (!st.shopts.has('expand_aliases') || st.aliases.size === 0 || st.aliasDepth > 16)
+            return null;
+        const first = cmd.words[0];
+        if (!first || first.type !== 'Word')
+            return null;
+        const name = literalOf(first);
+        if (name === null || !st.aliases.has(name))
+            return null;
+        const full = this.rt.text(cmd);
+        const offset = cmd.span.start;
+        const text = full.slice(0, first.span.start - offset) + st.aliases.get(name) + full.slice(first.span.end - offset);
+        const script = this.rt.parse(text, `alias ${name}`);
+        st.aliasDepth++;
+        try {
+            return await this.execList(script.body, proc);
+        }
+        finally {
+            st.aliasDepth--;
+        }
+    }
+    async execSimpleInner(cmd, proc) {
+        proc.lastSubstStatus = null;
+        const aliased = await this.expandAlias(cmd, proc);
+        if (aliased !== null)
+            return aliased;
+        // 1. Expand words (Assign nodes after declaration builtins are evaluated by the builtin).
+        const argv = [];
+        const declAssigns = [];
+        for (const w of cmd.words) {
+            if (w.type === 'Assign') {
+                declAssigns.push({ index: argv.length, assign: w });
+                argv.push(`\u0000assign:${declAssigns.length - 1}`);
+            }
+            else {
+                argv.push(...(await this.expander.expandFields([w], proc)));
+            }
+        }
+        // 2. Assignment-only statement
+        if (argv.length === 0) {
+            for (const a of cmd.assigns) {
+                try {
+                    await this.performAssign(a, proc, {});
+                }
+                catch (e) {
+                    if (e instanceof CommandError && /readonly variable/.test(e.message))
+                        throw new FatalError(e.message, 1);
+                    throw e;
+                }
+            }
+            const redirStatus = await this.redirectOnly(cmd, proc);
+            if (redirStatus !== 0)
+                return redirStatus;
+            if (proc.state.options.xtrace && cmd.assigns.length > 0) {
+                await this.xtrace(proc, cmd.assigns.map((a) => `${a.name}=${this.rt.text(a.value ?? a)}`));
+            }
+            return proc.lastSubstStatus ?? 0;
+        }
+        // 3. Prefix assignments (temporary for functions/builtins, environment for externals)
+        const prefix = [];
+        for (const a of cmd.assigns) {
+            if (a.value?.type === 'ArrayLiteral')
+                continue;
+            const v = a.value ? await this.expander.expandString(a.value, proc, { tildeAssign: true }) : '';
+            prefix.push({ name: a.name, value: v });
+        }
+        // 4. Resolve
+        const name = argv[0];
+        let kind;
+        let exePath;
+        const fn = proc.state.functions.get(name);
+        const tempPath = prefix.find((p) => p.name === 'PATH')?.value;
+        if (fn)
+            kind = 'function';
+        else if (BUILTINS.has(name))
+            kind = 'builtin';
+        else {
+            exePath = resolveCommand(name, proc.state, tempPath);
+            kind = exePath ? 'external' : 'not-found';
+        }
+        // 5. Redirect targets
+        const redirects = await this.resolveRedirects(cmd.redirs, proc);
+        const redirectEffects = redirectEffectsOf(redirects);
+        // 6. Assess (behavior + policy + hooks)
+        const execId = this.rt.nextExecId();
+        const env = this.childEnv(proc, prefix);
+        const realArgv = this.realArgv(argv, declAssigns);
+        const stdinFile = redirects.find((r) => r.fd === 0);
+        const stdinKind = stdinFile ? (stdinFile.path ? 'file' : 'pipe') : kindOfStdin(proc.fds.get(0));
+        const assessment = await this.rt.assess({
+            execId, node: cmd, argv: realArgv, kind, path: exePath, cwd: proc.state.cwd, env, redirectEffects, stdinKind, pid: proc.pid,
+        });
+        if (assessment.action === 'abort')
+            throw new AbortRun(assessment.reason, assessment.status);
+        if (assessment.action === 'deny') {
+            this.errorMessage(proc, `${name}: ${assessment.reason}`);
+            return assessment.status;
+        }
+        if (proc.state.options.xtrace)
+            await this.xtrace(proc, [...prefix.map((p) => `${p.name}=${p.value}`), ...realArgv]);
+        this.rt.emit({
+            type: 'command:start', execId, nodeId: cmd.id, span: cmd.span, argv: realArgv, kind, path: exePath, cwd: proc.state.cwd, pid: proc.pid,
+            redirects: redirects.map(redirectInfo), line: proc.line,
+        });
+        const started = Date.now();
+        let status;
+        // 7. Open redirections into a command-local fd table
+        const fds = proc.fds.clone();
+        try {
+            try {
+                await this.openRedirects(redirects, fds, proc);
+            }
+            catch (e) {
+                if (e instanceof FsError || e instanceof CommandError) {
+                    this.errorMessage(proc, e.message);
+                    status = 1;
+                    this.rt.emit({ type: 'command:end', execId, nodeId: cmd.id, status, durationMs: Date.now() - started });
+                    return status;
+                }
+                throw e;
+            }
+            const cproc = proc.derive({ fds });
+            if (assessment.action === 'simulate') {
+                if (assessment.stdout)
+                    await this.write(cproc, 1, assessment.stdout).catch(() => { });
+                if (assessment.stderr)
+                    await this.write(cproc, 2, assessment.stderr).catch(() => { });
+                status = assessment.status;
+            }
+            else {
+                status = await this.dispatch(kind, name, argv, declAssigns, prefix, exePath, env, cmd, cproc, proc, assessment.readsStdin, execId);
+            }
+        }
+        catch (e) {
+            if (e instanceof BrokenPipeError) {
+                // SIGPIPE: an in-process write to a pipe nobody reads kills this (sub)shell, as in bash
+                this.rt.emit({ type: 'command:end', execId, nodeId: cmd.id, status: 141, durationMs: Date.now() - started });
+                throw new ExitSignal(141);
+            }
+            else {
+                this.rt.emit({ type: 'command:end', execId, nodeId: cmd.id, status: e instanceof ExitSignal || e instanceof ReturnSignal ? e.status : 1, durationMs: Date.now() - started });
+                throw e;
+            }
+        }
+        finally {
+            fds.closeAll();
+        }
+        this.rt.emit({ type: 'command:end', execId, nodeId: cmd.id, status, durationMs: Date.now() - started });
+        await this.rt.afterCommand(execId, status);
+        this.setUnderscore(proc, realArgv);
+        return status;
+    }
+    setUnderscore(proc, argv) {
+        const v = proc.state.globals.get('_');
+        const last = argv[argv.length - 1] ?? '';
+        if (v)
+            v.value = { kind: 'string', value: last };
+        else
+            proc.state.globals.set('_', newVar({ kind: 'string', value: last }));
+    }
+    realArgv(argv, declAssigns) {
+        if (declAssigns.length === 0)
+            return argv;
+        return argv.map((a) => {
+            const m = /^\u0000assign:(\d+)$/.exec(a);
+            if (!m)
+                return a;
+            const as = declAssigns[Number(m[1])].assign;
+            return this.rt.text(as);
+        });
+    }
+    async dispatch(kind, name, argv, declAssigns, prefix, exePath, env, cmd, cproc, base, readsStdin, execId) {
+        switch (kind) {
+            case 'function': {
+                const entry = cproc.state.functions.get(name);
+                return this.withTempVars(cproc, prefix, () => this.callFunction(entry.def, argv, cproc));
+            }
+            case 'builtin': {
+                const run = () => this.runBuiltin(name, argv, declAssigns, cproc, base, cmd);
+                if (prefix.length === 0)
+                    return run();
+                return this.withTempVars(cproc, prefix, run);
+            }
+            case 'external': {
+                if (this.rt.inlineScripts) {
+                    const plan = inlineShellPlan(exePath, argv, cproc.state.cwd);
+                    if (plan)
+                        return this.runInlineScript(plan, env, cproc);
+                }
+                if (this.rt.emulate) {
+                    const base = path.basename(exePath);
+                    const req = { execId, path: exePath, argv, env, proc: cproc, node: cmd };
+                    const emulated = base === 'xargs' ? await emulateXargs(this, req) : base === 'find' ? await emulateFind(this, req) : null;
+                    if (emulated !== null)
+                        return emulated;
+                }
+                return runExternal(this, {
+                    execId, path: exePath, argv, env, cwd: cproc.state.cwd, proc: cproc, readsStdin,
+                });
+            }
+            case 'not-found': {
+                const p = name.includes('/') ? path.resolve(cproc.state.cwd, name) : null;
+                if (p && fs.existsSync(p)) {
+                    this.errorMessage(cproc, `${name}: ${fs.statSync(p).isDirectory() ? 'Is a directory' : 'Permission denied'}`);
+                    return 126;
+                }
+                this.errorMessage(cproc, `${name}: ${p ? 'No such file or directory' : 'command not found'}`);
+                return 127;
+            }
+            default:
+                return 0;
+        }
+    }
+    /**
+     * Execute a nested shell script (`bash -c ...`, `bash file`, `./script.sh`)
+     * inside the VM as a fresh shell process: only exported variables carry
+     * over, functions and options do not. Its commands are traced and
+     * policy-checked individually instead of disappearing into a child bash.
+     */
+    async runInlineScript(plan, env, proc) {
+        const script = this.rt.parse(plan.source, plan.origin, { partial: true });
+        const state = new ShellState(proc.state.cwd);
+        for (const [k, v] of Object.entries(env)) {
+            const fm = /^BASH_FUNC_(.+)%%$/.exec(k);
+            if (fm) {
+                const def = proc.state.functions.get(fm[1]);
+                if (def?.exported)
+                    state.functions.set(fm[1], def);
+                continue;
+            }
+            state.globals.set(k, newVar({ kind: 'string', value: v }, { exported: true }));
+        }
+        state.globals.set('SHLVL', newVar({ kind: 'string', value: String(Number(env.SHLVL ?? '1') + 1) }, { exported: true }));
+        initShellVars(state);
+        for (const [k, v] of Object.entries(plan.options))
+            state.options[k] = v;
+        state.positional = plan.args;
+        state.arg0 = plan.arg0;
+        const child = new Proc(state, proc.fds.clone(), this.rt.nextPid(), proc.pid, 0, new Map(), true);
+        child.jobSignal = proc.jobSignal;
+        child.jobChildren = proc.jobChildren;
+        return this.runSubshell(child, () => this.execTopLevel(script, child), 'script', script.id);
+    }
+    /**
+     * Run an already-expanded argv (for `command`, `builtin`, `exec`): resolve,
+     * assess against the policy, and dispatch.
+     */
+    async runArgv(argv, proc, node, opts) {
+        const name = argv[0];
+        let kind;
+        let exePath;
+        if (!opts.externalOnly && !opts.skipFunctions && !opts.builtinOnly && proc.state.functions.has(name))
+            kind = 'function';
+        else if (!opts.externalOnly && BUILTINS.has(name))
+            kind = 'builtin';
+        else if (opts.builtinOnly)
+            kind = 'not-found';
+        else {
+            exePath = resolveCommand(name, proc.state);
+            kind = exePath ? 'external' : 'not-found';
+        }
+        const execId = this.rt.nextExecId();
+        const env = this.childEnv(proc, []);
+        const assessment = await this.rt.assess({
+            execId, node, argv, kind, path: exePath, cwd: proc.state.cwd, env, redirectEffects: [], stdinKind: kindOfStdin(proc.fds.get(0)), pid: proc.pid,
+        });
+        if (assessment.action === 'abort')
+            throw new AbortRun(assessment.reason, assessment.status);
+        if (assessment.action === 'deny') {
+            this.errorMessage(proc, `${name}: ${assessment.reason}`);
+            return assessment.status;
+        }
+        this.rt.emit({ type: 'command:start', execId, nodeId: node.id, span: node.span, argv, kind, path: exePath, cwd: proc.state.cwd, pid: proc.pid, redirects: [] });
+        const started = Date.now();
+        let status;
+        if (assessment.action === 'simulate') {
+            if (assessment.stdout)
+                await this.write(proc, 1, assessment.stdout).catch(() => { });
+            if (assessment.stderr)
+                await this.write(proc, 2, assessment.stderr).catch(() => { });
+            status = assessment.status;
+        }
+        else {
+            status = await this.dispatch(kind, name, argv, [], [], exePath, env, node, proc, proc, assessment.readsStdin, execId);
+        }
+        this.rt.emit({ type: 'command:end', execId, nodeId: node.id, status, durationMs: Date.now() - started });
+        await this.rt.afterCommand(execId, status);
+        return status;
+    }
+    async withTempVars(proc, vars, fn) {
+        if (vars.length === 0)
+            return fn();
+        const scope = new Map();
+        for (const v of vars)
+            scope.set(v.name, newVar({ kind: 'string', value: v.value }, { exported: true }));
+        proc.state.locals.push(scope);
+        try {
+            return await fn();
+        }
+        finally {
+            const i = proc.state.locals.lastIndexOf(scope);
+            if (i >= 0)
+                proc.state.locals.splice(i, 1);
+        }
+    }
+    async callFunction(def, argv, proc) {
+        const st = proc.state;
+        const savedPositional = st.positional;
+        st.positional = argv.slice(1);
+        st.locals.push(new Map());
+        st.funcStack.unshift(def.name);
+        this.rt.emit({ type: 'function:enter', name: def.name, nodeId: def.id, pid: proc.pid, args: argv.slice(1) });
+        let status;
+        try {
+            status = await this.execCommand(def.body, proc);
+        }
+        catch (e) {
+            if (e instanceof ReturnSignal)
+                status = e.status;
+            else
+                throw e;
+        }
+        finally {
+            const ret = st.traps.get('RETURN');
+            if (ret) {
+                try {
+                    await this.execList(this.rt.parse(ret, 'trap RETURN').body, proc);
+                }
+                catch {
+                    // a failing RETURN trap does not change the function's status
+                }
+            }
+            st.locals.pop();
+            st.positional = savedPositional;
+            st.funcStack.shift();
+        }
+        this.rt.emit({ type: 'function:exit', name: def.name, status, pid: proc.pid });
+        return status;
+    }
+    async runBuiltin(name, argv, declAssigns, proc, base, cmd) {
+        const impl = BUILTINS.get(name);
+        const ctx = {
+            interp: this,
+            proc,
+            base,
+            argv,
+            node: cmd,
+            assignArg: (arg) => {
+                const m = /^\u0000assign:(\d+)$/.exec(arg);
+                return m ? declAssigns[Number(m[1])].assign : null;
+            },
+            out: (text) => this.write(proc, 1, text),
+            err: (text) => this.write(proc, 2, text),
+            error: (message) => this.errorMessage(proc, `${name}: ${message}`),
+        };
+        try {
+            return await impl(ctx);
+        }
+        catch (e) {
+            if (e instanceof CommandError) {
+                this.errorMessage(proc, `${name}: ${e.message}`);
+                return e.status;
+            }
+            throw e;
+        }
+    }
+    async redirectOnly(cmd, proc) {
+        if (cmd.redirs.length === 0)
+            return 0;
+        const redirects = await this.resolveRedirects(cmd.redirs, proc);
+        const a = await this.rt.assessRedirects(redirectEffectsOf(redirects), cmd, proc);
+        if (a.action === 'abort')
+            throw new AbortRun(a.reason, a.status);
+        if (a.action === 'deny') {
+            this.errorMessage(proc, a.reason);
+            return a.status;
+        }
+        const fds = proc.fds.clone();
+        try {
+            await this.openRedirects(redirects, fds, proc);
+        }
+        catch (e) {
+            if (e instanceof FsError || e instanceof CommandError) {
+                this.errorMessage(proc, e.message);
+                return 1;
+            }
+            throw e;
+        }
+        finally {
+            fds.closeAll();
+        }
+        return 0;
+    }
+    async xtrace(proc, words) {
+        const ps4 = proc.state.getString('PS4') ?? '+ ';
+        const { shellQuote } = await import("./expand.js");
+        await this.write(proc, 2, `${ps4}${words.map((w) => (w === '' ? "''" : shellQuote(w))).join(' ')}\n`).catch(() => { });
+    }
+    childEnv(proc, prefix) {
+        const env = proc.state.environment();
+        for (const [name, f] of proc.state.functions) {
+            if (f.exported)
+                env[`BASH_FUNC_${name}%%`] = `() ${this.rt.text(f.def.body)}`;
+        }
+        for (const p of prefix)
+            env[p.name] = p.value;
+        return env;
+    }
+    // -------------------------------------------------------------------------
+    // Assignments
+    // -------------------------------------------------------------------------
+    assignScalar(proc, name, value, opts = {}) {
+        const st = proc.state;
+        const v = opts.local ? st.declareLocal(name) : st.ensure(name);
+        if (v.readonly)
+            throw new CommandError(`${name}: readonly variable`);
+        value = this.applyAttrs(v, value, proc);
+        if (v.value?.kind === 'indexed')
+            v.value.values.set(0, value);
+        else if (v.value?.kind === 'assoc')
+            v.value.values.set('0', value);
+        else
+            v.value = { kind: 'string', value };
+        this.rt.emit({ type: 'assign', name, value, pid: proc.pid, nodeId: 0 });
+        if (name === 'PWD' && path.isAbsolute(value)) {
+            // keep the VM cwd in sync only through cd
+        }
+    }
+    /** `name[index]=value` from an already-expanded subscript (`printf -v 'a[1]'`). */
+    async assignElement(proc, name, index, value) {
+        const v = proc.state.ensure(name);
+        if (v.readonly)
+            throw new CommandError(`${name}: readonly variable`);
+        if (v.value?.kind === 'assoc' || v.declaredKind === 'assoc') {
+            if (v.value?.kind !== 'assoc')
+                v.value = { kind: 'assoc', values: new Map() };
+            v.value.values.set(index, this.applyAttrs(v, value, proc));
+        }
+        else {
+            let idx = Number(await this.arithText(index, proc));
+            if (v.value === null || v.value.kind !== 'indexed') {
+                const values = new Map();
+                if (v.value?.kind === 'string')
+                    values.set(0, v.value.value);
+                v.value = { kind: 'indexed', values };
+            }
+            if (idx < 0)
+                idx = (v.value.values.size === 0 ? 0 : Math.max(...v.value.values.keys()) + 1) + idx;
+            v.value.values.set(idx, this.applyAttrs(v, value, proc));
+        }
+        this.rt.emit({ type: 'assign', name: `${name}[…]`, value, pid: proc.pid, nodeId: 0 });
+    }
+    applyAttrs(v, value, proc) {
+        if (v.integer) {
+            try {
+                const env = this.arithEnv(proc);
+                // synchronous evaluation of text
+                value = String(evaluateArithTextSync(value, env));
+            }
+            catch {
+                value = '0';
+            }
+        }
+        if (v.upper)
+            value = value.toUpperCase();
+        if (v.lower)
+            value = value.toLowerCase();
+        return value;
+    }
+    /**
+     * Expand an assignment's value now and return an equivalent assignment with
+     * literal parts (so `local x=1 y=$x` sees the old `$x`, as bash expands
+     * all arguments before the builtin runs).
+     */
+    async freezeAssign(a, proc) {
+        const lit = (value, like) => ({
+            type: 'Word', id: like.id, span: like.span, parts: [{ type: 'SglQuoted', value, ansi: false, id: like.id, span: like.span }],
+        });
+        const index = a.index ? lit(await this.expander.expandString(a.index, proc), a.index) : null;
+        if (a.value === null)
+            return { ...a, index };
+        if (a.value.type === 'Word')
+            return { ...a, index, value: lit(await this.expander.expandString(a.value, proc, { tildeAssign: true }), a.value) };
+        const elems = [];
+        for (const el of a.value.elems) {
+            if (el.index)
+                elems.push({ index: lit(await this.expander.expandString(el.index, proc), el.index), value: lit(await this.expander.expandString(el.value, proc), el.value) });
+            else
+                for (const f of await this.expander.expandFields([el.value], proc))
+                    elems.push({ index: null, value: lit(f, el.value) });
+        }
+        return { ...a, index, value: { ...a.value, elems } };
+    }
+    /** Perform an assignment node (prefix, bare, or declaration-builtin argument). */
+    async performAssign(a, proc, opts) {
+        const st = proc.state;
+        const v = opts.local ? st.declareLocal(a.name) : st.ensure(a.name);
+        if (v.readonly)
+            throw new CommandError(`${a.name}: readonly variable`);
+        if (opts.exported)
+            v.exported = true;
+        if (opts.declareKind)
+            v.declaredKind = opts.declareKind;
+        if (a.value?.type === 'ArrayLiteral') {
+            const isAssoc = opts.declareKind === 'assoc' || v.declaredKind === 'assoc' || v.value?.kind === 'assoc';
+            if (isAssoc) {
+                const values = a.append && v.value?.kind === 'assoc' ? v.value.values : new Map();
+                for (const el of a.value.elems) {
+                    if (!el.index) {
+                        // bash 5.1+: `declare -A m=(k v k2 v2)` key/value pairs
+                        continue;
+                    }
+                    const key = await this.expander.expandString(el.index, proc);
+                    values.set(key, this.applyAttrs(v, await this.expander.expandString(el.value, proc), proc));
+                }
+                const pairs = a.value.elems.filter((e) => !e.index);
+                for (let i = 0; i + 1 < pairs.length; i += 2) {
+                    values.set(await this.expander.expandString(pairs[i].value, proc), await this.expander.expandString(pairs[i + 1].value, proc));
+                }
+                v.value = { kind: 'assoc', values };
+            }
+            else {
+                const values = a.append && v.value?.kind === 'indexed' ? v.value.values : a.append && v.value?.kind === 'string' ? new Map([[0, v.value.value]]) : new Map();
+                let next = values.size === 0 ? 0 : Math.max(...values.keys()) + 1;
+                for (const el of a.value.elems) {
+                    if (el.index) {
+                        const idxText = await this.expander.expandString(el.index, proc);
+                        next = Number(await this.arithText(idxText, proc));
+                        values.set(next, this.applyAttrs(v, await this.expander.expandString(el.value, proc), proc));
+                        next++;
+                    }
+                    else {
+                        for (const f of await this.expander.expandFields([el.value], proc)) {
+                            values.set(next++, this.applyAttrs(v, f, proc));
+                        }
+                    }
+                }
+                v.value = { kind: 'indexed', values };
+            }
+            this.rt.emit({ type: 'assign', name: a.name, value: `(${varElements(v).join(' ')})`, pid: proc.pid, nodeId: a.id });
+            return;
+        }
+        let value = a.value ? await this.expander.expandString(a.value, proc, { tildeAssign: true }) : '';
+        if (a.index) {
+            const isAssoc = v.value?.kind === 'assoc' || v.declaredKind === 'assoc';
+            if (isAssoc) {
+                const key = await this.expander.expandString(a.index, proc);
+                if (v.value?.kind !== 'assoc')
+                    v.value = { kind: 'assoc', values: new Map() };
+                const old = v.value.values.get(key) ?? '';
+                v.value.values.set(key, this.applyAttrs(v, a.append ? old + value : value, proc));
+            }
+            else {
+                const idxText = await this.expander.expandString(a.index, proc);
+                let idx = Number(await this.arithText(idxText, proc));
+                if (v.value === null || v.value.kind !== 'indexed') {
+                    const values = new Map();
+                    if (v.value?.kind === 'string')
+                        values.set(0, v.value.value);
+                    v.value = { kind: 'indexed', values };
+                }
+                if (idx < 0)
+                    idx = (v.value.values.size === 0 ? 0 : Math.max(...v.value.values.keys()) + 1) + idx;
+                const old = v.value.values.get(idx) ?? '';
+                v.value.values.set(idx, this.applyAttrs(v, a.append ? old + value : value, proc));
+            }
+            this.rt.emit({ type: 'assign', name: `${a.name}[…]`, value, pid: proc.pid, nodeId: a.id });
+            return;
+        }
+        if (a.append) {
+            if (v.integer) {
+                const old = st.getString(a.name) ?? '0';
+                value = String(BigInt(this.applyAttrs(v, old, proc)) + BigInt(this.applyAttrs(v, value, proc)));
+            }
+            else if (v.value?.kind === 'indexed') {
+                const values = v.value.values;
+                values.set(values.size === 0 ? 0 : Math.max(...values.keys()) + 1, value);
+                return;
+            }
+            else {
+                value = (st.getString(a.name) ?? '') + value;
+            }
+        }
+        if (a.value === null && opts.declareKind === undefined && (opts.local || opts.exported)) {
+            // `local x` / `export x` without value: declare only
+        }
+        value = this.applyAttrs(v, value, proc);
+        if (v.value?.kind === 'indexed')
+            v.value.values.set(0, value);
+        else if (v.value?.kind === 'assoc')
+            v.value.values.set('0', value);
+        else
+            v.value = { kind: 'string', value };
+        this.rt.emit({ type: 'assign', name: a.name, value, pid: proc.pid, nodeId: a.id });
+    }
+    // -------------------------------------------------------------------------
+    // Arithmetic
+    // -------------------------------------------------------------------------
+    arithEnv(proc) {
+        const st = proc.state;
+        return {
+            get: (name, index) => {
+                if (index === null) {
+                    if (/^[0-9]+$/.test(name))
+                        return st.positional[Number(name) - 1];
+                    return this.dynamicVar(proc, name) ?? st.getString(name);
+                }
+                const v = st.lookup(name);
+                if (!v || v.value === null)
+                    return undefined;
+                if (v.value.kind === 'indexed')
+                    return v.value.values.get(Number(index));
+                if (v.value.kind === 'assoc')
+                    return v.value.values.get(index);
+                return index === '0' ? v.value.value : undefined;
+            },
+            isAssoc: (name) => {
+                const v = st.lookup(name);
+                return v?.value?.kind === 'assoc' || v?.declaredKind === 'assoc';
+            },
+            set: (name, index, value) => {
+                const v = st.ensure(name);
+                if (v.readonly)
+                    throw new ArithError(`${name}: readonly variable`);
+                const s = String(value);
+                if (index === null) {
+                    if (v.value?.kind === 'indexed')
+                        v.value.values.set(0, s);
+                    else
+                        v.value = { kind: 'string', value: s };
+                }
+                else if (v.value?.kind === 'assoc' || v.declaredKind === 'assoc') {
+                    if (v.value?.kind !== 'assoc')
+                        v.value = { kind: 'assoc', values: new Map() };
+                    v.value.values.set(index, s);
+                }
+                else {
+                    if (v.value?.kind !== 'indexed') {
+                        const values = new Map();
+                        if (v.value?.kind === 'string')
+                            values.set(0, v.value.value);
+                        v.value = { kind: 'indexed', values };
+                    }
+                    v.value.values.set(Number(index), s);
+                }
+                this.rt.emit({ type: 'assign', name, value: s, pid: proc.pid, nodeId: 0 });
+            },
+            expandWord: (word) => this.expander.expandString(word, proc),
+            nounset: st.options.nounset,
+        };
+    }
+    async arith(expr, proc) {
+        return evaluateArith(expr, this.arithEnv(proc));
+    }
+    async arithText(text, proc) {
+        const { evaluateArithText } = await import("./arith.js");
+        try {
+            return evaluateArithText(text, this.arithEnv(proc));
+        }
+        catch (e) {
+            if (e instanceof ArithError)
+                throw new DiscardError(e.message);
+            throw e;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Dynamic variables
+    // -------------------------------------------------------------------------
+    startTime = Date.now();
+    dynamicVar(proc, name) {
+        switch (name) {
+            case 'RANDOM': return String(Math.floor(Math.random() * 32768));
+            case 'SECONDS': return String(Math.floor((Date.now() - this.startTime) / 1000));
+            case 'EPOCHSECONDS': return String(Math.floor(Date.now() / 1000));
+            case 'EPOCHREALTIME': return (Date.now() / 1000).toFixed(6);
+            case 'LINENO': return String(proc.line);
+            case 'BASHPID': return String(proc.pid);
+            case 'BASH_SUBSHELL': return String(proc.depth);
+            case 'PPID': return String(process.pid);
+            case 'FUNCNAME': return proc.state.funcStack[0];
+            case 'UID': return String(process.getuid?.() ?? 0);
+            case 'EUID': return String(process.geteuid?.() ?? 0);
+            case 'BASH': return '/bin/bash';
+            default: return undefined;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Substitutions
+    // -------------------------------------------------------------------------
+    async commandSubst(node, proc) {
+        // $(< file)
+        if (node.body.length === 1 && node.body[0].command.type === 'SimpleCommand') {
+            const c = node.body[0].command;
+            if (c.words.length === 0 && c.assigns.length === 0 && c.redirs.length === 1 && c.redirs[0].op === '<') {
+                const target = await this.expander.expandString(c.redirs[0].target, proc);
+                const abs = path.resolve(proc.state.cwd, target);
+                const a = await this.rt.assessRedirects([{ kind: 'read', path: known(abs), source: '$(<)' }], c, proc);
+                if (a.action === 'abort')
+                    throw new AbortRun(a.reason, a.status);
+                if (a.action === 'deny') {
+                    this.errorMessage(proc, a.reason);
+                    proc.lastSubstStatus = a.status;
+                    return '';
+                }
+                try {
+                    const text = fs.readFileSync(abs, 'utf8');
+                    proc.lastSubstStatus = 0;
+                    return text.replace(/\n+$/, '');
+                }
+                catch (e) {
+                    this.errorMessage(proc, `${target}: ${e.code === 'ENOENT' ? 'No such file or directory' : String(e)}`);
+                    proc.lastSubstStatus = 1;
+                    return '';
+                }
+            }
+        }
+        const child = proc.subshell(this.rt.nextPid());
+        if (!proc.state.shopts.has('inherit_errexit'))
+            child.state.options.errexit = false;
+        const capture = new Capture(this.rt.channel('capture', `$(${this.rt.text(node).replace(/^\$\(|\)$/g, '').replace(/^`|`$/g, '')})`, { nodeId: node.id }), this.rt.listeners);
+        child.fds.set(1, capture);
+        // keep a reference so closeAll does not discard the bytes before we read them
+        capture.retain();
+        const status = await this.runSubshell(child, () => this.execList(node.body, child), 'cmdsubst', node.id);
+        proc.lastSubstStatus = status;
+        proc.state.lastStatus = status;
+        const text = capture.text();
+        capture.release();
+        return text.replace(/\n+$/, '');
+    }
+    async processSubst(node, proc) {
+        const ch = this.rt.channel('procsubst', `${node.direction}(${this.rt.text(node).slice(2, -1)})`, { nodeId: node.id });
+        const pipe = new Pipe(ch, this.rt.listeners);
+        const child = proc.subshell(this.rt.nextPid());
+        let fd = 63;
+        while (proc.fds.get(fd) && fd > 10)
+            fd--;
+        if (node.direction === '<') {
+            child.fds.set(1, pipe.writeEnd);
+            proc.fds.set(fd, pipe.readEnd);
+        }
+        else {
+            child.fds.set(0, pipe.readEnd);
+            proc.fds.set(fd, pipe.writeEnd);
+        }
+        proc.procSubstFds.push({ fds: proc.fds, fd });
+        this.rt.track(this.runSubshell(child, () => this.execList(node.body, child), 'procsubst', node.id));
+        return `/dev/fd/${fd}`;
+    }
+    // -------------------------------------------------------------------------
+    // Redirections
+    // -------------------------------------------------------------------------
+    async withCompoundRedirects(cmd, proc, fn) {
+        if (cmd.redirs.length === 0)
+            return fn(proc);
+        const mark = proc.procSubstFds.length;
+        const redirects = await this.resolveRedirects(cmd.redirs, proc);
+        const a = await this.rt.assessRedirects(redirectEffectsOf(redirects), cmd, proc);
+        if (a.action === 'abort')
+            throw new AbortRun(a.reason, a.status);
+        if (a.action === 'deny') {
+            this.errorMessage(proc, a.reason);
+            this.closeProcSubsts(proc, mark);
+            return a.status;
+        }
+        const fds = proc.fds.clone();
+        try {
+            try {
+                await this.openRedirects(redirects, fds, proc);
+            }
+            catch (e) {
+                if (e instanceof FsError || e instanceof CommandError) {
+                    this.errorMessage(proc, e.message);
+                    return 1;
+                }
+                throw e;
+            }
+            this.closeProcSubsts(proc, mark);
+            return await fn(proc.derive({ fds }));
+        }
+        finally {
+            fds.closeAll();
+            this.closeProcSubsts(proc, mark);
+        }
+    }
+    async resolveRedirects(redirs, proc) {
+        const out = [];
+        for (const r of redirs) {
+            const defaultFd = r.op.startsWith('<') ? 0 : 1;
+            const fd = r.fd ?? defaultFd;
+            if (r.op === '<<' || r.op === '<<-') {
+                const body = r.heredoc ? (r.heredoc.quoted ? r.heredoc.body.parts[0]?.value ?? '' : await this.expander.expandHeredoc(r.heredoc.body, proc)) : '';
+                out.push({ node: r, fd, op: r.op, content: body, fdVar: r.fdVar ?? undefined });
+                continue;
+            }
+            if (r.op === '<<<') {
+                const s = await this.expander.expandString(r.target, proc);
+                out.push({ node: r, fd, op: r.op, content: s + '\n', fdVar: r.fdVar ?? undefined });
+                continue;
+            }
+            const fields = await this.expander.expandFields([r.target], proc);
+            if (fields.length !== 1 && !(r.op === '<&' || r.op === '>&'))
+                throw new CommandError(`${this.rt.text(r.target)}: ambiguous redirect`);
+            const targetText = fields[0] ?? '';
+            if (r.op === '<&' || r.op === '>&') {
+                if (targetText === '-') {
+                    out.push({ node: r, fd, op: r.op, close: true, fdVar: r.fdVar ?? undefined });
+                    continue;
+                }
+                const m = /^(\d+)(-?)$/.exec(targetText);
+                if (m) {
+                    out.push({ node: r, fd, op: r.op, dupFd: Number(m[1]), close: m[2] === '-', fdVar: r.fdVar ?? undefined });
+                    continue;
+                }
+                if (r.op === '>&' && r.fd === null) {
+                    // `>& file` == `&> file`
+                    out.push({ node: r, fd: 1, op: '&>', path: path.resolve(proc.state.cwd, targetText) });
+                    continue;
+                }
+                throw new CommandError(`${targetText}: ambiguous redirect`);
+            }
+            const special = specialPath(targetText);
+            out.push({ node: r, fd: r.op === '&>' || r.op === '&>>' ? 1 : fd, op: r.op, path: special ? undefined : path.resolve(proc.state.cwd, targetText), special, fdVar: r.fdVar ?? undefined });
+        }
+        return out;
+    }
+    async openRedirects(redirects, fds, proc) {
+        for (const r of redirects) {
+            let fd = r.fd;
+            if (r.fdVar) {
+                if (r.close && r.dupFd === undefined) {
+                    const n = Number(proc.state.getString(r.fdVar));
+                    if (Number.isInteger(n))
+                        fds.close(n);
+                    continue;
+                }
+                fd = fds.freeFd(10);
+                this.assignScalar(proc, r.fdVar, String(fd));
+            }
+            if (r.close && r.dupFd === undefined) {
+                fds.close(fd);
+                continue;
+            }
+            if (r.dupFd !== undefined) {
+                if (!fds.dup(r.dupFd, fd))
+                    throw new CommandError(`${r.dupFd}: Bad file descriptor`);
+                if (r.close)
+                    fds.close(r.dupFd);
+                continue;
+            }
+            if (r.content !== undefined) {
+                fds.set(fd, new ConstInput(this.rt.channel('heredoc', r.op === '<<<' ? '<<<' : `<<${r.node.heredoc?.delimiter ?? ''}`, { nodeId: r.node.id }), r.content, this.rt.listeners));
+                continue;
+            }
+            let file;
+            if (r.special === 'null')
+                file = new NullFile(this.rt.channel('null', '/dev/null'), this.rt.listeners);
+            else if (r.special && typeof r.special === 'object') {
+                const src = fds.get(r.special.dup) ?? proc.fds.get(r.special.dup);
+                if (!src)
+                    throw new CommandError(`/dev/fd/${r.special.dup}: Bad file descriptor`);
+                file = src.retain();
+            }
+            else {
+                const mode = r.op === '<' ? 'read' : r.op === '>>' || r.op === '&>>' ? 'append' : r.op === '<>' ? 'readwrite' : 'write';
+                const noclobber = proc.state.options.noclobber && (r.op === '>' || r.op === '&>') && !isNonRegular(r.path);
+                file = await HostFile.open(this.rt.channel('file', `${r.op} ${r.path}`, { path: r.path, nodeId: r.node.id }), r.path, mode, this.rt.listeners, noclobber, proc.state.umask);
+            }
+            fds.set(fd, file);
+            if (r.op === '&>' || r.op === '&>>')
+                fds.dup(1, 2);
+        }
+    }
+}
+const INLINE_SHELLS = new Set(['bash', 'sh']);
+/**
+ * Decide whether an external invocation is a shell script mash can run
+ * itself: `bash [-euxo opt] -c SCRIPT [arg0 args]`, `bash [opts] FILE args`,
+ * or an executable file whose shebang names bash/sh.
+ */
+function inlineShellPlan(exePath, argv, cwd) {
+    const base = path.basename(exePath);
+    let args = argv.slice(1);
+    if (!INLINE_SHELLS.has(base)) {
+        // `./script.sh` with a bash/sh shebang
+        let head;
+        try {
+            const fd = fs.openSync(exePath, 'r');
+            const buf = Buffer.alloc(128);
+            const n = fs.readSync(fd, buf, 0, 128, 0);
+            fs.closeSync(fd);
+            head = buf.subarray(0, n).toString('utf8');
+        }
+        catch {
+            return null;
+        }
+        const m = /^#![ \t]*(\S+)(?:[ \t]+(\S+))?/.exec(head.split("\n")[0]);
+        if (!m) {
+            // no shebang: the kernel returns ENOEXEC and bash runs the file as a shell script
+            if (head.startsWith('#!') || head.includes('\0') || /[\x00-\x08\x0e-\x1f]/.test(head.slice(0, 64)) || head.startsWith('\x7fELF') || head.startsWith('\xca\xfe') || head.startsWith('\xcf\xfa'))
+                return null;
+            args = [exePath, ...args];
+            return inlineFromArgs(args, base, cwd);
+        }
+        const interp = path.basename(m[1]) === 'env' ? m[2] : path.basename(m[1]);
+        if (!interp || !INLINE_SHELLS.has(interp))
+            return null;
+        if (m[2] && path.basename(m[1]) !== 'env' && m[2] !== '-e')
+            return null;
+        args = [exePath, ...args];
+        if (m[2] === '-e')
+            args.unshift('-e');
+    }
+    return inlineFromArgs(args, base, cwd);
+}
+function inlineFromArgs(args, base, cwd) {
+    const options = {};
+    const flagMap = { e: 'errexit', u: 'nounset', x: 'xtrace', f: 'noglob', v: 'verbose', C: 'noclobber', a: 'allexport' };
+    let i = 0;
+    let command;
+    for (; i < args.length; i++) {
+        const a = args[i];
+        if (a === '-c') {
+            command = args[i + 1];
+            i += 2;
+            break;
+        }
+        if (a === '-o' || a === '+o') {
+            const name = args[++i];
+            if (name === 'pipefail' || name === 'errexit' || name === 'nounset' || name === 'xtrace' || name === 'noglob')
+                options[name] = a === '-o';
+            else
+                return null;
+            continue;
+        }
+        if (a === '--') {
+            i++;
+            break;
+        }
+        if (/^[-+][euxfvCa]+$/.test(a)) {
+            for (const f of a.slice(1))
+                options[flagMap[f]] = a[0] === '-';
+            continue;
+        }
+        if (a.startsWith('-'))
+            return null; // interactive, login, --rcfile, ... : spawn a real shell
+        break;
+    }
+    if (command !== undefined) {
+        return { source: command, origin: 'bash -c', arg0: args[i] ?? base, args: args.slice(i + 1), options };
+    }
+    const file = args[i];
+    if (file === undefined)
+        return null; // reads the script from stdin
+    const abs = path.resolve(cwd, file);
+    let source;
+    try {
+        source = fs.readFileSync(abs, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    return { source, origin: abs, arg0: file, args: args.slice(i + 1), options };
+}
+import { evaluateArithText as evaluateArithTextSync } from "./arith.js";
+function isNonRegular(p) {
+    try {
+        return !fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function specialPath(p) {
+    if (p === '/dev/null')
+        return 'null';
+    if (p === '/dev/stdin')
+        return { dup: 0 };
+    if (p === '/dev/stdout')
+        return { dup: 1 };
+    if (p === '/dev/stderr')
+        return { dup: 2 };
+    const m = /^\/dev\/fd\/(\d+)$/.exec(p);
+    if (m)
+        return { dup: Number(m[1]) };
+    return undefined;
+}
+function redirectEffectsOf(redirects) {
+    const effects = [];
+    for (const r of redirects) {
+        if (!r.path)
+            continue;
+        if (r.op === '<')
+            effects.push({ kind: 'read', path: known(r.path), source: 'redirect' });
+        else if (r.op === '<>') {
+            effects.push({ kind: 'read', path: known(r.path), source: 'redirect' });
+            effects.push({ kind: 'write', path: known(r.path), source: 'redirect' });
+        }
+        else
+            effects.push({ kind: 'write', path: known(r.path), append: r.op === '>>' || r.op === '&>>', source: 'redirect' });
+    }
+    return effects;
+}
+function redirectInfo(r) {
+    return { fd: r.fd, op: r.op, path: r.path ?? (r.special === 'null' ? '/dev/null' : undefined), dupFd: r.dupFd };
+}
+function kindOfStdin(f) {
+    if (!f)
+        return 'null';
+    switch (f.channel.kind) {
+        case 'null': return 'null';
+        case 'file':
+        case 'heredoc': return 'file';
+        case 'host': return 'terminal';
+        default: return 'pipe';
+    }
+}
+/** PATH lookup (with the shell's hash table). */
+export function resolveCommand(name, state, pathOverride) {
+    const isExec = (p) => {
+        try {
+            const st = fs.statSync(p);
+            if (!st.isFile())
+                return false;
+            fs.accessSync(p, fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (name.includes('/')) {
+        const p = path.resolve(state.cwd, name);
+        return isExec(p) ? p : undefined;
+    }
+    const cached = pathOverride === undefined ? state.hash.get(name) : undefined;
+    if (cached && isExec(cached))
+        return cached;
+    const PATH = pathOverride ?? state.getString('PATH') ?? '/usr/bin:/bin';
+    for (const dir of PATH.split(':')) {
+        const p = path.resolve(state.cwd, dir === '' ? '.' : dir, name);
+        if (isExec(p)) {
+            if (pathOverride === undefined)
+                state.hash.set(name, p);
+            return p;
+        }
+    }
+    return undefined;
+}
+export { literalOf, evalTest };
+//# sourceMappingURL=interp.js.map