@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/behaviors/roles.ts

@@ -0,0 +1,187 @@
+/**
+ * Argument roles for display: which arguments of a command are directories,
+ * files, search patterns, program text or nested command names.
+ *
+ * The behavior definition is run over literal argument values, each a
+ * distinct object. Path effects carry *resolved* values, so the registry's
+ * tracer records which input each resolved value came from; an effect then
+ * maps back to its argument:
+ *
+ *   chdir, or a recursive read/write/delete   → dir
+ *   other reads, writes, deletes              → file
+ *   argv[0] of a nested command (exec effect) → cmd
+ *   h.role(value, 'pattern' | 'code' | …)     → that role (wins over effects)
+ *   SUBCOMMANDS table (cargo, docker, gh, …)  → subcommand (when nothing else said)
+ *
+ * Arguments no definition explains get a lexical guess (`x.ts` → file,
+ * `out/` → dir). Nothing here affects analysis or policy.
+ */
+
+import { known, unknownString, type AValue } from '../analysis/value.ts'
+import type { Effect } from '../policy/effects.ts'
+import { basename, type BehaviorRegistry } from './registry.ts'
+import type { ArgRole } from './types.ts'
+import { defaultBehaviors } from './index.ts'
+
+let shared: BehaviorRegistry | null = null
+
+/** A directory that does not exist, so definitions that look at files find nothing. */
+const NOWHERE = '/nonexistent/mash-roles'
+
+/**
+ * Roles of a command's arguments. `words[i]` is the literal text of word i
+ * (argv[0] first), or undefined when it is not a literal. Returns one entry
+ * per word (index 0 included: always undefined).
+ */
+export function argRoles(words: (string | undefined)[], registry?: BehaviorRegistry): (ArgRole | undefined)[] {
+  const roles: (ArgRole | undefined)[] = words.map(() => undefined)
+  const name = words[0]
+  if (name === undefined) return roles
+  const cmd = basename(name)
+
+  // builtins the registry does not describe
+  if (cmd === 'cd' || cmd === 'pushd' || cmd === 'source' || cmd === '.') {
+    const i = words.findIndex((w, j) => j > 0 && w !== undefined && !/^-./.test(w))
+    if (i > 0) roles[i] = cmd === 'cd' || cmd === 'pushd' ? 'dir' : 'file'
+    return roles
+  }
+
+  const reg = registry ?? (shared ??= defaultBehaviors())
+  const values: AValue[] = words.map((w) => (w === undefined ? unknownString('word') : known(w)))
+  const index = new Map<AValue, number>(values.map((v, i) => [v, i]))
+  const resolvedFrom = new Map<AValue, number>()
+  const hinted = new Set<number>()
+  const prev = reg.tracer
+  reg.tracer = {
+    resolved(input, output) {
+      const i = index.get(input)
+      if (i !== undefined) resolvedFrom.set(output, i)
+    },
+    role(value, role) {
+      const i = index.get(value)
+      if (i !== undefined && i > 0) {
+        roles[i] = role
+        hinted.add(i)
+      }
+    },
+  }
+  let effects: Effect[] = []
+  try {
+    effects = reg.analyze({ name: cmd, argv: values, cwd: known(NOWHERE), env: () => undefined, stdin: 'unknown' }).effects
+  } catch {
+    // display only: ignore failures
+  } finally {
+    reg.tracer = prev
+  }
+  const nested: number[] = []
+  for (const e of effects) {
+    if (e.kind === 'exec') {
+      const i = index.get(e.argv[0])
+      if (i !== undefined && i > 0 && !hinted.has(i)) {
+        roles[i] = 'cmd'
+        nested.push(i)
+      }
+      continue
+    }
+    if (e.kind !== 'read' && e.kind !== 'write' && e.kind !== 'delete' && e.kind !== 'chdir') continue
+    const i = resolvedFrom.get(e.path) ?? index.get(e.path)
+    if (i === undefined || i === 0 || hinted.has(i)) continue
+    const role: ArgRole = e.kind === 'chdir' || ('recursive' in e && e.recursive) ? 'dir' : 'file'
+    // a later recursive effect on the same argument makes it a directory
+    if (roles[i] !== 'dir') roles[i] = role
+  }
+  // a nested command's own arguments (`timeout 5 npx vitest run x.test.ts`): roles from its own analysis
+  for (const i of nested) {
+    const inner = argRoles(words.slice(i), reg)
+    inner.forEach((r, j) => {
+      if (j > 0 && r !== undefined && roles[i + j] === undefined) roles[i + j] = r
+    })
+  }
+  // tools with subcommands that no definition annotates
+  if (!roles.includes('subcommand')) markSubcommands(cmd, words, roles)
+  // lexical guesses for arguments nothing explained
+  words.forEach((w, i) => {
+    if (i === 0 || roles[i] !== undefined || w === undefined) return
+    roles[i] = lexicalRole(w)
+  })
+  return roles
+}
+
+/** A guess from the text alone: `dir/`, `~`, `.`, `..` → dir; a path-like name with an extension → file. */
+export function lexicalRole(w: string): ArgRole | undefined {
+  if (/^-/.test(w) || /[\s=*?[\]{}$`'"\\|<>;&()]/.test(w) || /^\w+:\/\//.test(w)) return undefined
+  if (w === '.' || w === '..' || w === '~' || /\/$/.test(w)) return 'dir'
+  if (/^(?:~|\.{1,2})?\/?(?:[\w.@+-]+\/)*[\w@+-][\w.@+-]*\.[A-Za-z][\w]{0,7}$/.test(w) && !/^\d+(\.\d+)+$/.test(w)) return 'file'
+  return undefined
+}
+
+/**
+ * Tools whose first operand is a subcommand. `value`: flags that take a
+ * value (skipped together with it); `nested`: subcommands that have their own
+ * (`gh pr view`, `docker compose up`); `all: true` for tools where every
+ * first-level subcommand is a group (`aws s3 ls`, `gcloud compute instances`).
+ * Not exhaustive: unknown tools just get no subcommand color.
+ */
+const SUBCOMMANDS: Record<string, { value?: string[]; nested?: string[]; all?: boolean }> = {
+  cargo: { value: ['-Z', '--config', '--color', '-C'] },
+  go: {},
+  rustup: { nested: ['toolchain', 'target', 'component', 'override', 'self', 'set'] },
+  docker: { value: ['-H', '--host', '--context', '-c', '--config', '-l', '--log-level'], nested: ['compose', 'image', 'container', 'network', 'volume', 'buildx', 'system', 'builder', 'context', 'plugin', 'manifest', 'swarm', 'node', 'service', 'stack', 'secret', 'config', 'trust'] },
+  podman: { nested: ['image', 'container', 'network', 'volume', 'machine', 'system', 'pod'] },
+  'docker-compose': { value: ['-f', '--file', '-p', '--project-name'] },
+  kubectl: { value: ['-n', '--namespace', '--context', '--kubeconfig', '-l', '--selector', '-o', '--output', '-f', '--filename'], nested: ['config', 'rollout', 'auth', 'certificate', 'top', 'create'] },
+  helm: { value: ['-n', '--namespace', '--kube-context'], nested: ['repo', 'plugin', 'dependency', 'registry', 'search', 'show'] },
+  gh: { value: ['-R', '--repo'], all: true },
+  glab: { value: ['-R', '--repo'], all: true },
+  aws: { value: ['--profile', '--region', '--output', '--endpoint-url'], all: true },
+  gcloud: { value: ['--project', '--account', '--format', '--region', '--zone'], all: true },
+  az: { value: ['--subscription', '-o', '--output'], all: true },
+  brew: { nested: ['services', 'bundle', 'tap-info', 'cask'] },
+  apt: {}, 'apt-get': {}, 'apt-cache': {}, dnf: {}, yum: {}, pacman: {}, apk: {}, snap: {}, flatpak: {}, port: {},
+  pip: {}, pip3: {}, uv: { nested: ['pip', 'tool', 'python', 'cache', 'self'] }, poetry: { nested: ['env', 'self', 'source', 'cache'] }, pipx: {}, conda: { nested: ['env'] }, pyenv: {},
+  swift: { nested: ['package'] }, xcrun: { nested: ['simctl', 'devicectl'], value: ['--sdk', '--toolchain'] }, xcodebuild: {},
+  deno: {}, bun: {}, yarn: {}, volta: {}, nvm: {}, corepack: {},
+  terraform: { value: ['-chdir'], nested: ['state', 'workspace', 'providers'] }, tofu: { nested: ['state', 'workspace'] }, pulumi: { nested: ['stack', 'config'] },
+  systemctl: {}, launchctl: {}, defaults: {}, diskutil: { nested: ['apfs', 'image'] }, hdiutil: {}, security: {}, tmutil: {}, pmset: {}, scutil: {}, networksetup: {},
+  tmux: { value: ['-L', '-S', '-f'] }, screen: {}, tailscale: {}, zig: {}, dotnet: {}, mix: {}, gem: {}, bundle: {}, rails: {}, composer: {}, mvn: {}, gradle: {}, sbt: {},
+  openssl: {}, gpg: {}, ssh_keygen: {}, git_lfs: {}, jj: { nested: ['git', 'op', 'bookmark', 'branch', 'workspace', 'config'] }, hg: {}, svn: {},
+  wrangler: { nested: ['kv', 'r2', 'd1', 'secret', 'pages', 'queues'] }, vercel: {}, netlify: {}, fly: { nested: ['apps', 'machine', 'secrets', 'volumes', 'ips', 'certs', 'postgres', 'redis'] }, flyctl: { nested: ['apps', 'machine', 'secrets', 'volumes'] },
+  heroku: {}, firebase: {}, supabase: { nested: ['db', 'functions', 'migration', 'projects', 'secrets'] }, stripe: {},
+  ollama: {}, hf: { nested: ['auth', 'repo', 'cache'] }, 'huggingface-cli': {}, code: {}, cursor: {}, op: { nested: ['item', 'vault', 'account', 'document', 'user'] },
+  sqlx: { nested: ['migrate', 'database'] }, prisma: { nested: ['migrate', 'db', 'generate'] }, drizzle_kit: {}, turbo: {}, nx: {}, lerna: {},
+  ffmpeg: { value: [] }, magick: {}, typst: {}, quarto: {}, jupyter: {}, npm: {}, pnpm: {}, npx: {},
+  container: { nested: ['system', 'image', 'images', 'builder', 'network', 'volume', 'registry'] }, log: {}, lms: {}, ruff: {}, taplo: {}, uvx: {}, rye: {}, pixi: {},
+  vitest: {}, jest: {}, playwright: {}, vite: {}, next: {}, nuxt: {}, astro: {}, expo: {}, eas: { nested: ['build', 'submit', 'update'] }, tauri: {}, 'wasm-pack': {}, maturin: {}, tsx: {}, biome: {}, eslint: {}, prettier: {},
+}
+// ffmpeg's first operand is not a subcommand
+delete SUBCOMMANDS.ffmpeg
+
+function markSubcommands(cmd: string, words: (string | undefined)[], roles: (ArgRole | undefined)[]): void {
+  const spec = SUBCOMMANDS[cmd]
+  if (!spec || cmd === 'npm' || cmd === 'pnpm' || cmd === 'npx') return
+  const value = new Set(spec.value ?? [])
+  const isSub = (w: string | undefined): w is string => w !== undefined && /^[a-z][a-z0-9._:-]*$/.test(w)
+  let i = 1
+  const next = (): number => {
+    for (; i < words.length; i++) {
+      const w = words[i]
+      if (w === undefined) return -1
+      if (w === '--') return -1
+      if (w.startsWith('+')) continue // cargo +nightly
+      if (w.startsWith('-')) {
+        if (value.has(w)) i++
+        continue
+      }
+      return i
+    }
+    return -1
+  }
+  const first = next()
+  if (first < 0 || !isSub(words[first]) || roles[first] !== undefined) return
+  roles[first] = 'subcommand'
+  if (spec.all || spec.nested?.includes(words[first]!)) {
+    i = first + 1
+    const second = next()
+    if (second > 0 && isSub(words[second]) && roles[second] === undefined) roles[second] = 'subcommand'
+  }
+}

package/src/behaviors/types.ts

@@ -0,0 +1,127 @@
+/**
+ * Behavior definitions: what an executable WOULD read, write, delete,
+ * execute or connect to, given its argv — without running it.
+ *
+ * A behavior receives abstract argv ({@link AValue}s). At runtime every value
+ * is concrete; during static analysis some are unknown. Definitions should be
+ * conservative: when an argument they need is unknown they still report the
+ * effect with the unknown path (the policy then answers `unknown`), and set
+ * `complete: false` when they cannot tell what the command does at all.
+ */
+
+import type { AValue, HoleType } from '../analysis/value.ts'
+import type { Effect } from '../policy/effects.ts'
+
+export type StdinKind = 'pipe' | 'file' | 'null' | 'terminal' | 'unknown'
+
+export interface Invocation {
+  /** Basename of argv[0]. */
+  name: string
+  /** Full argv (argv[0] included). */
+  argv: AValue[]
+  /** Working directory (absolute). */
+  cwd: AValue
+  /** Environment lookup (exported variables). */
+  env(name: string): AValue | undefined
+  stdin: StdinKind
+  /**
+   * Static analysis only: did the snippet (possibly) write this concrete path
+   * before this command? Then the file's current contents (a script to
+   * follow) are not what the command will see.
+   */
+  mayHaveChanged?(path: string): boolean
+}
+
+export interface OutputInfo {
+  /** Type of the command's stdout (as captured by `$(...)`, trailing newlines stripped). */
+  type: HoleType
+  /** For `path` outputs: a directory the output lies under. */
+  under?: string
+  /** Output is a list of lines, each of `type`. */
+  lines?: boolean
+  /** Exactly known output (e.g. `pwd`, `basename` of a literal). */
+  value?: AValue
+}
+
+/** Where nested script text came from (for effect provenance). */
+export interface ScriptInfo {
+  /** The script file (absolute), when the text was read from one. */
+  file?: string
+}
+
+export interface BehaviorResult {
+  effects: Effect[]
+  /** Does the command read stdin? Lets the VM avoid pumping stdin into commands that never read it. */
+  readsStdin?: boolean | 'maybe'
+  stdout?: OutputInfo
+  /** False when the definition could not determine all effects (unknown flags, opaque arguments). */
+  complete?: boolean
+  /** Free-form notes for reports. */
+  notes?: string[]
+}
+
+export interface Behavior {
+  /** Command basenames this definition handles. */
+  names: string[]
+  summary?: string
+  analyze(inv: Invocation, h: BehaviorHelpers): BehaviorResult
+}
+
+export interface ParsedArgs {
+  /** Short and long flags seen, by canonical name (value `true` or the option argument). */
+  flags: Map<string, AValue | true>
+  /** Repeated options (`-e x -e y`), in order. */
+  multi: Map<string, AValue[]>
+  operands: AValue[]
+  /** Arguments whose role could not be determined (unknown values that might be options). */
+  ambiguous: AValue[]
+  /** Flags not in the spec. */
+  unknownFlags: string[]
+}
+
+export interface ArgSpec {
+  /** Short flags without arguments, e.g. `'rfiv'`. */
+  short?: string
+  /** Short flags taking an argument, e.g. `'tS'`. */
+  shortWithArg?: string
+  /**
+   * Long options: name → takes an argument? A number is how many arguments
+   * it takes (`--cropOffset y x`: 2; the last one is recorded). Values may also
+   * be an alias (`'=r'` maps to short `r`).
+   */
+  long?: Record<string, boolean | number | string>
+  /** Short flags (in `shortWithArg`) taking more than one argument: `{ c: 2 }`. The last one is recorded. */
+  arity?: Record<string, number>
+  /** Single-dash long options (`-layout`, `-show_entries x`): `-word` is looked up in `long` first, then parsed as short flags. */
+  longSingle?: boolean
+  /** Stop option parsing at the first operand (like POSIX getopt; default false = GNU permutation). */
+  posix?: boolean
+  /** Accept `-<digits>` (`head -20`) as this flag with the digits as its value. */
+  numeric?: string
+}
+
+export interface BehaviorHelpers {
+  /** Resolve a (possibly relative) path argument against the invocation's cwd. */
+  resolve(p: AValue): AValue
+  /** GNU-style argument parsing over abstract values. */
+  parseArgs(args: AValue[], spec: ArgSpec): ParsedArgs
+  /** Analyze a nested command (xargs, find -exec, env, timeout, sudo...). */
+  subcommand(argv: AValue[], opts?: { stdin?: StdinKind; cwd?: AValue }): BehaviorResult
+  /** Analyze a shell script string (bash -c, sh -c, eval); `info.file` names the script file it was read from. */
+  script(source: AValue, positional?: AValue[], info?: ScriptInfo): BehaviorResult
+  /** Home directory, if known. */
+  home(): AValue | undefined
+  /**
+   * Hint what an argument *is* when no effect says so: a search pattern
+   * (grep, find -name) or program text (sed/awk/jq programs, `python -c`).
+   * Used for display (syntax highlighting, summaries); no effect on policy.
+   */
+  role(value: AValue, role: ArgRole): void
+}
+
+/**
+ * What an argument is, for display. `dir`/`file` come from effects;
+ * `pattern`/`code`/`subcommand` from {@link BehaviorHelpers.role} (and a
+ * table of tools with subcommands in roles.ts).
+ */
+export type ArgRole = 'dir' | 'file' | 'pattern' | 'code' | 'cmd' | 'subcommand'

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * mash — a bash virtual machine for agent harnesses.
+ *
+ * - `parse` → span-preserving AST (`./parser/ast.ts`)
+ * - `Machine.analyze` → static effect analysis and pre-flight policy verdict
+ * - `Machine.run` → policy-checked streaming execution with trace events and hooks
+ * - behavior definitions → predicted effects of executables (`./behaviors`)
+ */
+
+export * as AST from './parser/ast.ts'
+export { parse, ParseError, lineColumn, literalOf, staticWordValue } from './parser/parser.ts'
+export { Machine, type MachineOptions, type RunOptions, type RunResult } from './machine.ts'
+export * from './trace/events.ts'
+export type { Channel, ChannelKind, DataListener } from './vm/io.ts'
+export * from './policy/policy.ts'
+export * from './policy/effects.ts'
+export * from './behaviors/index.ts'
+export * from './analysis/value.ts'
+export { analyzeScript, analyzeSource, type AnalysisReport, type CommandSite, type Violation, type VariableInfo, type AnalyzeOptions } from './analysis/analyze.ts'
+export { defaultSpawn, type SpawnFn, type SpawnRequest } from './vm/external.ts'
+export type { FdPassing } from './vm/fifo.ts'
+export { ProgressTracker, type ProgressSnapshot } from './trace/progress.ts'
+export { format, printScript, type FormatOptions, type FormatResult } from './printer/print.ts'
+export { formatHtml, printScriptHtml, attachHtmlHandlers, HTML_CSS, HTML_SCRIPT, type HtmlOptions, type HtmlResult } from './printer/html.ts'
+export { summarize, summarizeScript, type SummaryOptions, type SummaryResult } from './printer/summary.ts'
+export { argRoles, lexicalRole } from './behaviors/roles.ts'
+export type { ArgRole } from './behaviors/types.ts'

package/src/integrations/deepsea.ts

@@ -0,0 +1,259 @@
+/**
+ * Adapter for the DeepSea / DeepSeek agent harness (the `deepsea-harness` repo).
+ *
+ * Dependency-free: the harness types are mirrored structurally so this file
+ * can be copied into a harness package (e.g. a `dsh-bash-mash` executor that
+ * registers `ctx.shell`) without importing mash's internals.
+ *
+ * Layering with the harness's existing confinement:
+ * - mash checks every command (and redirection) against the policy BEFORE it
+ *   runs, and rejects whole snippets that would definitely violate it;
+ * - each external command mash spawns is still wrapped by `ctx.sandbox.confine`
+ *   (seatbelt / bwrap / landlock / ACL), so anything mash cannot see
+ *   (an interpreter's own file writes) remains confined by the OS.
+ */
+
+import { spawn } from 'node:child_process'
+import type { Policy } from '../policy/policy.ts'
+import { describeEffect } from '../policy/effects.ts'
+import type { SpawnFn } from '../vm/external.ts'
+import { Machine, type MachineOptions } from '../machine.ts'
+import { ParseError } from '../parser/parser.ts'
+import type { AnalysisReport } from '../analysis/analyze.ts'
+import type { TraceEvent } from '../trace/events.ts'
+
+/** Mirrors `SandboxExecutionPolicy` from `@deepseek-ai/dsh-sandbox`. */
+export interface HarnessSandboxPolicy {
+  mode: 'read-only' | 'workspace-write' | 'danger-full-access'
+  workspaceRoot: string
+  additionalWritableRoots?: readonly string[]
+  sessionId?: string
+}
+
+/** Mirrors `SandboxProvider.confine` (the `ctx.sandbox` service). */
+export type ConfineFn = (argv: readonly string[], policy: HarnessSandboxPolicy & { mode: 'read-only' | 'workspace-write' }, signal?: AbortSignal) => Promise<{ argv: string[] }>
+
+/**
+ * Map the harness policy onto a mash policy, with optional mash-only
+ * restrictions. Harness defaults: `rm -f` of a path that does not exist is a
+ * no-op, not a violation (`missingDeletes: 'allow'`; existence is re-checked
+ * at runtime just before each delete).
+ */
+export function fromHarnessPolicy(p: HarnessSandboxPolicy, extra: Partial<Policy> = {}): Policy {
+  return {
+    mode: p.mode,
+    workspaceRoot: p.workspaceRoot,
+    additionalWritableRoots: p.additionalWritableRoots,
+    writableTemp: true,
+    missingDeletes: 'allow',
+    ...extra,
+  }
+}
+
+/**
+ * A spawn function that confines every external command through the
+ * harness sandbox provider (per command, instead of once around `bash -c`).
+ */
+export function confiningSpawn(confine: ConfineFn, policy: HarnessSandboxPolicy, signal?: AbortSignal): SpawnFn {
+  return async (req) => {
+    if (policy.mode === 'danger-full-access') {
+      return spawn(req.file, req.args, { argv0: req.argv0, cwd: req.cwd, env: req.env, stdio: req.stdio })
+    }
+    const { argv } = await confine([req.file, ...req.args], { ...policy, mode: policy.mode }, signal)
+    return spawn(argv[0], argv.slice(1), { cwd: req.cwd, env: req.env, stdio: req.stdio })
+  }
+}
+
+export interface PreflightResult {
+  /** `reject`: refuse the tool call; `check-at-runtime`: run with per-step enforcement; `allow`. */
+  verdict: AnalysisReport['verdict']
+  /** Model-facing explanation (one line per definite violation). */
+  message: string
+  report: AnalysisReport
+}
+
+/**
+ * Static pre-flight for the `bash` tool: call before executing a snippet and
+ * return `message` as the tool error when `verdict === 'reject'`.
+ */
+export function preflight(command: string, opts: { cwd: string; policy: HarnessSandboxPolicy; env?: Record<string, string>; extra?: Partial<Policy> }): PreflightResult {
+  const m = new Machine({ cwd: opts.cwd, env: opts.env, policy: fromHarnessPolicy(opts.policy, opts.extra) })
+  let report: AnalysisReport
+  try {
+    report = m.analyze(command)
+  } catch (e) {
+    if (!(e instanceof ParseError)) throw e
+    // never block on mash's own parsing gaps
+    const r = emptyReport()
+    r.reasons.push(`not analyzed: ${e.message}`)
+    return { verdict: 'check-at-runtime', message: '', report: r }
+  }
+  const message = report.verdict === 'reject'
+    ? `This command was not run: it would definitely violate the ${opts.policy.mode} sandbox policy.\n${report.reasons.map((r) => `- ${r}`).join('\n')}`
+    : report.verdict === 'check-at-runtime'
+      ? `Some steps can only be checked while running:\n${report.violations.slice(0, 8).map((v) => `- line ${v.line}: ${v.effect} (${v.reach})`).join('\n')}`
+      : ''
+  return { verdict: report.verdict, message, report }
+}
+
+/** Mirrors the parts of `ShellRunResult` a tool renders. */
+export interface HarnessRunResult {
+  exitCode: number | null
+  signal: NodeJS.Signals | null
+  timedOut: boolean
+  aborted: boolean
+  timeoutMs: number
+  stdout: { text: string; truncated: boolean }
+  stderr: { text: string; truncated: boolean }
+  sandbox: { mode: HarnessSandboxPolicy['mode']; denied: boolean }
+  /** mash extras: pre-flight report and runtime denials. */
+  mash: { preflight: AnalysisReport; denials: { argv: string[]; reason: string }[] }
+}
+
+export interface HarnessRunOptions {
+  command: string
+  workdir: string
+  timeoutMs: number
+  policy: HarnessSandboxPolicy
+  env?: Record<string, string>
+  stdin?: string
+  signal?: AbortSignal
+  stdoutMaxBytes?: number
+  confine?: ConfineFn
+  /** Live trace events (tool-card progress, stream previews). */
+  onEvent?: (e: TraceEvent) => void
+  /** Machine options to override (hooks, denyUnknown, ...). */
+  machine?: Partial<MachineOptions>
+  /**
+   * When mash cannot parse the snippet (unsupported syntax such as extglob):
+   * `bash` runs it with real (confined) bash instead — the current harness
+   * behavior; `error` returns a syntax error. Default `bash`.
+   */
+  onParseError?: 'bash' | 'error'
+}
+
+/**
+ * Run a `bash` tool call the way `ctx.shell.execute(spec).result()` would,
+ * but through mash: static pre-flight, per-command enforcement, optional
+ * per-command OS confinement, and a live event stream.
+ */
+export async function runForHarness(o: HarnessRunOptions): Promise<HarnessRunResult> {
+  const max = o.stdoutMaxBytes ?? 1024 * 1024
+  const out: Uint8Array[] = []
+  const err: Uint8Array[] = []
+  let outBytes = 0
+  let errBytes = 0
+  const ac = new AbortController()
+  const timer = setTimeout(() => ac.abort(), o.timeoutMs)
+  const onAbort = (): void => ac.abort()
+  o.signal?.addEventListener('abort', onAbort, { once: true })
+  const machine = new Machine({
+    cwd: o.workdir,
+    env: o.env ?? (process.env as Record<string, string>),
+    policy: fromHarnessPolicy(o.policy),
+    stdin: o.stdin ? (async function* () { yield o.stdin! })() : undefined,
+    stdout: (c) => {
+      outBytes += c.length
+      if (outBytes <= max) out.push(c)
+    },
+    stderr: (c) => {
+      errBytes += c.length
+      if (errBytes <= max) err.push(c)
+    },
+    spawn: o.confine ? confiningSpawn(o.confine, o.policy, ac.signal) : undefined,
+    background: 'detach',
+    ...o.machine,
+  })
+  if (o.onEvent) machine.on(o.onEvent)
+  let script: ReturnType<Machine['parse']>
+  try {
+    script = machine.parse(o.command)
+  } catch (e) {
+    if (!(e instanceof ParseError)) throw e
+    clearTimeout(timer)
+    if (o.onParseError === 'error') {
+      return {
+        exitCode: 2, signal: null, timedOut: false, aborted: false, timeoutMs: o.timeoutMs,
+        stdout: { text: '', truncated: false }, stderr: { text: `mash: syntax error: ${e.message}\n`, truncated: false },
+        sandbox: { mode: o.policy.mode, denied: false }, mash: { preflight: emptyReport(), denials: [] },
+      }
+    }
+    return runRealBash(o, e)
+  }
+  const report = machine.analyze(script)
+  const dec = (cs: Uint8Array[]): string => Buffer.concat(cs).toString('utf8')
+  if (report.verdict === 'reject') {
+    clearTimeout(timer)
+    const text = `mash: refusing to run: the snippet would definitely violate the sandbox policy\n${report.reasons.map((r) => `  ✗ ${r}\n`).join('')}`
+    return {
+      exitCode: 126, signal: null, timedOut: false, aborted: false, timeoutMs: o.timeoutMs,
+      stdout: { text: '', truncated: false }, stderr: { text, truncated: false },
+      sandbox: { mode: o.policy.mode, denied: true }, mash: { preflight: report, denials: [] },
+    }
+  }
+  const r = await machine.run(script, { signal: ac.signal })
+  clearTimeout(timer)
+  o.signal?.removeEventListener('abort', onAbort)
+  const timedOut = ac.signal.aborted && !o.signal?.aborted
+  return {
+    exitCode: r.status,
+    signal: null,
+    timedOut,
+    aborted: o.signal?.aborted ?? false,
+    timeoutMs: o.timeoutMs,
+    stdout: { text: dec(out), truncated: outBytes > max },
+    stderr: { text: dec(err), truncated: errBytes > max },
+    sandbox: { mode: o.policy.mode, denied: r.denials.length > 0 },
+    mash: { preflight: report, denials: r.denials },
+  }
+}
+
+function emptyReport(): AnalysisReport {
+  return { commands: [], variables: [], functions: [], violations: [], verdict: 'check-at-runtime', reasons: [] }
+}
+
+/** Fallback: the snippet as one `bash -c`, confined as a whole (today's harness behavior). */
+async function runRealBash(o: HarnessRunOptions, parseError: ParseError): Promise<HarnessRunResult> {
+  const argv = ['bash', '-c', o.command]
+  const confined = o.confine && o.policy.mode !== 'danger-full-access'
+    ? (await o.confine(argv, { ...o.policy, mode: o.policy.mode }, o.signal)).argv
+    : argv
+  return new Promise((resolve) => {
+    const child = spawn(confined[0], confined.slice(1), { cwd: o.workdir, env: o.env ?? process.env, stdio: ['pipe', 'pipe', 'pipe'], signal: o.signal })
+    const out: Buffer[] = []
+    const err: Buffer[] = []
+    let timedOut = false
+    const timer = setTimeout(() => {
+      timedOut = true
+      child.kill('SIGKILL')
+    }, o.timeoutMs)
+    child.stdout.on('data', (d: Buffer) => out.push(d))
+    child.stderr.on('data', (d: Buffer) => err.push(d))
+    child.stdin.on('error', () => {}) // EPIPE when bash exits without reading stdin
+    child.stdin.end(o.stdin ?? '')
+    child.on('error', () => {})
+    child.on('close', (code, signal) => {
+      clearTimeout(timer)
+      const report = emptyReport()
+      report.reasons.push(`not analyzed: ${parseError.message}`)
+      resolve({
+        exitCode: code, signal, timedOut, aborted: o.signal?.aborted ?? false, timeoutMs: o.timeoutMs,
+        stdout: { text: Buffer.concat(out).toString('utf8'), truncated: false },
+        stderr: { text: Buffer.concat(err).toString('utf8'), truncated: false },
+        sandbox: { mode: o.policy.mode, denied: false }, mash: { preflight: report, denials: [] },
+      })
+    })
+  })
+}
+
+/** One-line description of a trace event, for tool-card progress lines. */
+export function describeEvent(e: TraceEvent): string | null {
+  switch (e.type) {
+    case 'command:start': return `$ ${e.argv.join(' ')}`
+    case 'command:denied': return `⛔ ${e.argv.join(' ')}: ${e.reason}`
+    case 'loop:iteration': return `↻ ${e.variable ? `${e.variable}=${e.value}` : `iteration ${e.iteration}`}`
+    default: return null
+  }
+}
+
+export { describeEffect }