@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/vm/interp.ts

@@ -0,0 +1,1623 @@
+/**
+ * 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 type * as A from '../parser/ast.ts'
+import { parse, ParseError, literalOf } from '../parser/parser.ts'
+import type { Effect } from '../policy/effects.ts'
+import type { CommandKind, RedirectInfo, SubshellReason, TraceEvent } from '../trace/events.ts'
+import { known } from '../analysis/value.ts'
+import { ArithError, evaluateArith, type ArithEnv } from './arith.ts'
+import { BUILTINS, type BuiltinContext } from './builtins.ts'
+import { Expander, varElements } from './expand.ts'
+import { runExternal, type SpawnFn } from './external.ts'
+import { emulateFind, emulateXargs } from './emulate.ts'
+import type { FdPassing } from './fifo.ts'
+import {
+  BrokenPipeError, Capture, ConstInput, FdTable, FsError, HostFile, NullFile, Pipe,
+  type Channel, type ChannelKind, type DataListener, type OpenFile,
+} from './io.ts'
+import { matchPattern } from './pattern.ts'
+import { AbortRun, CommandError, DiscardError, ExitSignal, FatalError, LoopSignal, Proc, ReturnSignal, type Job } from './proc.ts'
+import { initShellVars, newVar, ShellState, type Variable } from './state.ts'
+import { evalCond, evalTest } from './test.ts'
+
+// ---------------------------------------------------------------------------
+// Runtime seam (implemented by Machine)
+// ---------------------------------------------------------------------------
+
+export interface ExecIntent {
+  execId: number
+  node: A.SimpleCommand
+  argv: string[]
+  kind: CommandKind
+  path?: string
+  cwd: string
+  env: Record<string, string>
+  redirectEffects: Effect[]
+  stdinKind: 'pipe' | 'file' | 'null' | 'terminal' | 'unknown'
+  pid: number
+}
+
+export type Assessment =
+  | { action: 'run'; readsStdin: boolean | 'maybe' }
+  | { action: 'deny'; reason: string; status: number }
+  | { action: 'abort'; reason: string; status: number }
+  | { action: 'simulate'; stdout: string; stderr: string; status: number }
+
+export interface Runtime {
+  emit(event: TraceEvent): void
+  readonly listeners: DataListener[]
+  channel(kind: ChannelKind, label: string, extra?: Partial<Channel>): Channel
+  nextPid(): number
+  nextExecId(): number
+  readonly shellPid: number
+  assess(intent: ExecIntent): Promise<Assessment>
+  /** Policy check for redirections of compound commands (no command to attach them to). */
+  assessRedirects(effects: Effect[], node: A.Node, proc: Proc): Promise<Assessment>
+  afterCommand(execId: number, status: number): Promise<void>
+  spawn: SpawnFn
+  readonly signal: AbortSignal
+  /** Source text of a node (from whichever parse produced it). */
+  text(node: { id: number; span: A.Span }): string
+  /** 1-based line number of a node in its source. */
+  line(node: { id: number; span: A.Span }): number
+  /** Parse source text (eval, source, trap actions), registering it for text()/line(). */
+  parse(source: string, origin: string, opts?: { partial?: boolean }): A.Script
+  findJob(pid: number): Job | undefined
+  /** Pending background work (process substitutions) to settle at the end. */
+  track(p: Promise<unknown>): void
+  registerJob(job: Job): void
+  /** Execute nested bash/sh scripts inside the VM. */
+  readonly inlineScripts: boolean
+  /** Emulate xargs and find -exec/-delete so each resulting command is traced and checked. */
+  readonly emulate: boolean
+  /** How `/dev/fd/N` arguments naming VM fds reach external commands (see fifo.ts). */
+  readonly fdPassing: FdPassing
+}
+
+interface ResolvedRedirect {
+  node: A.Redirect
+  fd: number
+  op: A.RedirectOp
+  /** Absolute path for file redirections. */
+  path?: string
+  /** Special device handling. */
+  special?: 'null' | { dup: number }
+  dupFd?: number
+  close?: boolean
+  content?: string
+  fdVar?: string
+}
+
+
+export class Interpreter {
+  readonly rt: Runtime
+  readonly expander: Expander
+
+  constructor(rt: Runtime) {
+    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: A.Script, proc: Proc): Promise<number> {
+    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: A.Script, proc: Proc): Promise<number> {
+    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
+  }
+
+  private handleTermination(e: unknown, proc: Proc): number {
+    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
+  }
+
+  private async runExitTrap(proc: Proc, status: number): Promise<number> {
+    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: Proc, fd: number, text: string | Uint8Array): Promise<void> {
+    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: Proc, message: string): void {
+    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: A.Stmt[], proc: Proc): Promise<number> {
+    let status = proc.state.lastStatus
+    for (const stmt of stmts) {
+      status = await this.execStmt(stmt, proc)
+    }
+    return status
+  }
+
+  async execStmt(stmt: A.Stmt, proc: Proc): Promise<number> {
+    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
+  }
+
+  private startBackground(stmt: A.Stmt, proc: Proc): void {
+    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: 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: Proc, fn: () => Promise<number>, reason: SubshellReason, nodeId: number): Promise<number> {
+    this.rt.emit({ type: 'subshell:start', pid: child.pid, parentPid: child.parentPid, nodeId, reason })
+    let status: number
+    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
+  }
+
+  private inErrTrap = false
+
+  /** After a failing command outside a condition: run the ERR trap, then apply `set -e`. */
+  private async checkErrexit(status: number, proc: Proc): Promise<void> {
+    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)
+  }
+
+  private step(node: A.Command, proc: Proc): void {
+    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 })
+  }
+
+  private stepCount = 0
+
+  async execCommand(cmd: A.Command, proc: Proc): Promise<number> {
+    // 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<void>((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
+        })
+    }
+  }
+
+  private async execCompound(cmd: A.CompoundCommand, proc: Proc): Promise<number> {
+    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
+        }
+      }
+    }
+  }
+
+  private async execAndOr(cmd: A.AndOr, proc: Proc): Promise<number> {
+    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
+  }
+
+  private async execIf(cmd: A.If, proc: Proc): Promise<number> {
+    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. */
+  private async loopBody(body: A.Stmt[], proc: Proc): Promise<{ status: number; ctl?: 'break' | 'continue' | 'outer' }> {
+    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
+    }
+  }
+
+  private async execLoop(cmd: A.Loop, proc: Proc): Promise<number> {
+    let status = 0
+    let iteration = 0
+    const inner = proc.derive({ loop: true })
+    const cond = inner.derive({ suppress: true })
+    for (;;) {
+      let c: number
+      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
+  }
+
+  private async execFor(cmd: A.For, proc: Proc): Promise<number> {
+    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
+  }
+
+  private async execSelect(cmd: A.Select, proc: Proc): Promise<number> {
+    // 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
+  }
+
+  private async execArithFor(cmd: A.ArithFor, proc: Proc): Promise<number> {
+    const ev = async (e: A.ArithExpr | null): Promise<bigint> => {
+      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
+  }
+
+  private async execCase(cmd: A.Case, proc: Proc): Promise<number> {
+    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
+  // -------------------------------------------------------------------------
+
+  private async execPipeline(cmd: A.Pipeline, proc: Proc): Promise<number> {
+    const start = Date.now()
+    const n = cmd.stages.length
+    const stageProc = cmd.negated ? proc.derive({ suppress: true }) : proc
+    let statuses: number[]
+    if (n === 1) {
+      statuses = [await this.execCommand(cmd.stages[0], stageProc)]
+    } else {
+      const pipes: Pipe[] = []
+      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
+  }
+
+  private setPipestatus(proc: Proc, statuses: number[]): void {
+    const values = new Map<number, string>()
+    statuses.forEach((s, i) => values.set(i, String(s)))
+    proc.state.globals.set('PIPESTATUS', newVar({ kind: 'indexed', values }))
+  }
+
+  // -------------------------------------------------------------------------
+  // Simple commands
+  // -------------------------------------------------------------------------
+
+  private async expandFieldsChecked(words: A.Word[], proc: Proc): Promise<string[]> {
+    return this.expander.expandFields(words, proc)
+  }
+
+  private async execSimple(cmd: A.SimpleCommand, proc: Proc): Promise<number> {
+    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)
+    }
+  }
+
+  private closeProcSubsts(proc: Proc, mark: number): void {
+    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. */
+  private async expandAlias(cmd: A.SimpleCommand, proc: Proc): Promise<number | null> {
+    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--
+    }
+  }
+
+  private async execSimpleInner(cmd: A.SimpleCommand, proc: Proc): Promise<number> {
+    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: string[] = []
+    const declAssigns: { index: number; assign: A.Assign }[] = []
+    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: { name: string; value: string }[] = []
+    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: CommandKind
+    let exePath: string | undefined
+    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: number
+    // 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
+  }
+
+  private setUnderscore(proc: Proc, argv: string[]): void {
+    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 }))
+  }
+
+  private realArgv(argv: string[], declAssigns: { index: number; assign: A.Assign }[]): string[] {
+    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)
+    })
+  }
+
+  private async dispatch(
+    kind: CommandKind, name: string, argv: string[], declAssigns: { index: number; assign: A.Assign }[],
+    prefix: { name: string; value: string }[], exePath: string | undefined, env: Record<string, string>,
+    cmd: A.SimpleCommand, cproc: Proc, base: Proc, readsStdin: boolean | 'maybe', execId: number,
+  ): Promise<number> {
+    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 = (): Promise<number> => 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.
+   */
+  private async runInlineScript(plan: InlinePlan, env: Record<string, string>, proc: Proc): Promise<number> {
+    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 as unknown as Record<string, boolean>)[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: string[], proc: Proc, node: A.SimpleCommand, opts: { skipFunctions?: boolean; externalOnly?: boolean; builtinOnly?: boolean }): Promise<number> {
+    const name = argv[0]
+    let kind: CommandKind
+    let exePath: string | undefined
+    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: number
+    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
+  }
+
+  private async withTempVars(proc: Proc, vars: { name: string; value: string }[], fn: () => Promise<number>): Promise<number> {
+    if (vars.length === 0) return fn()
+    const scope = new Map<string, Variable>()
+    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: A.FunctionDef, argv: string[], proc: Proc): Promise<number> {
+    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: number
+    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
+  }
+
+  private async runBuiltin(name: string, argv: string[], declAssigns: { index: number; assign: A.Assign }[], proc: Proc, base: Proc, cmd: A.SimpleCommand): Promise<number> {
+    const impl = BUILTINS.get(name)!
+    const ctx: BuiltinContext = {
+      interp: this,
+      proc,
+      base,
+      argv,
+      node: cmd,
+      assignArg: (arg: string) => {
+        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
+    }
+  }
+
+  private async redirectOnly(cmd: A.SimpleCommand, proc: Proc): Promise<number> {
+    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
+  }
+
+  private async xtrace(proc: Proc, words: string[]): Promise<void> {
+    const ps4 = proc.state.getString('PS4') ?? '+ '
+    const { shellQuote } = await import('./expand.ts')
+    await this.write(proc, 2, `${ps4}${words.map((w) => (w === '' ? "''" : shellQuote(w))).join(' ')}\n`).catch(() => {})
+  }
+
+  childEnv(proc: Proc, prefix: { name: string; value: string }[]): Record<string, string> {
+    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: Proc, name: string, value: string, opts: { local?: boolean } = {}): void {
+    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: Proc, name: string, index: string, value: string): Promise<void> {
+    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<number, string>()
+        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 })
+  }
+
+  private applyAttrs(v: Variable, value: string, proc: Proc): string {
+    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: A.Assign, proc: Proc): Promise<A.Assign> {
+    const lit = (value: string, like: { id: number; span: A.Span }): A.Word => ({
+      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: A.ArrayElem[] = []
+    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: A.Assign, proc: Proc, opts: { local?: boolean; exported?: boolean; declareKind?: 'indexed' | 'assoc' }): Promise<void> {
+    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<string, string>()
+        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<number, string>()
+        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<number, string>()
+          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: Proc): ArithEnv {
+    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<number, string>()
+            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: A.ArithExpr | null, proc: Proc): Promise<bigint> {
+    return evaluateArith(expr, this.arithEnv(proc))
+  }
+
+  async arithText(text: string, proc: Proc): Promise<bigint> {
+    const { evaluateArithText } = await import('./arith.ts')
+    try {
+      return evaluateArithText(text, this.arithEnv(proc))
+    } catch (e) {
+      if (e instanceof ArithError) throw new DiscardError(e.message)
+      throw e
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Dynamic variables
+  // -------------------------------------------------------------------------
+
+  private readonly startTime = Date.now()
+
+  dynamicVar(proc: Proc, name: string): string | undefined {
+    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: A.CmdSubst, proc: Proc): Promise<string> {
+    // $(< 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 as NodeJS.ErrnoException).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: A.ProcSubst, proc: Proc): Promise<string> {
+    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
+  // -------------------------------------------------------------------------
+
+  private async withCompoundRedirects(cmd: A.CompoundCommand, proc: Proc, fn: (p: Proc) => Promise<number>): Promise<number> {
+    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: A.Redirect[], proc: Proc): Promise<ResolvedRedirect[]> {
+    const out: ResolvedRedirect[] = []
+    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] as A.SglQuoted | undefined)?.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: ResolvedRedirect[], fds: FdTable, proc: Proc): Promise<void> {
+    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: OpenFile
+      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)
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface InlinePlan {
+  source: string
+  origin: string
+  arg0: string
+  args: string[]
+  options: Record<string, boolean>
+}
+
+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: string, argv: string[], cwd: string): InlinePlan | null {
+  const base = path.basename(exePath)
+  let args = argv.slice(1)
+  if (!INLINE_SHELLS.has(base)) {
+    // `./script.sh` with a bash/sh shebang
+    let head: string
+    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: string[], base: string, cwd: string): InlinePlan | null {
+  const options: Record<string, boolean> = {}
+  const flagMap: Record<string, string> = { e: 'errexit', u: 'nounset', x: 'xtrace', f: 'noglob', v: 'verbose', C: 'noclobber', a: 'allexport' }
+  let i = 0
+  let command: string | undefined
+  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: string
+  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.ts'
+
+function isNonRegular(p: string): boolean {
+  try {
+    return !fs.statSync(p).isFile()
+  } catch {
+    return false
+  }
+}
+
+function specialPath(p: string): ResolvedRedirect['special'] {
+  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: ResolvedRedirect[]): Effect[] {
+  const effects: Effect[] = []
+  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: ResolvedRedirect): RedirectInfo {
+  return { fd: r.fd, op: r.op, path: r.path ?? (r.special === 'null' ? '/dev/null' : undefined), dupFd: r.dupFd }
+}
+
+function kindOfStdin(f: OpenFile | undefined): ExecIntent['stdinKind'] {
+  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: string, state: ShellState, pathOverride?: string): string | undefined {
+  const isExec = (p: string): boolean => {
+    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 }