@starci/hfs 4.7.31 → 4.7.33

package/runtime/scripts/guards/rights.mjs

@@ -0,0 +1,268 @@
+// rights.mjs - the ROLE RIGHTS of the PreToolUse command guard (rules R223 RIGHTS_ROLE_DENIED, R224 RIGHTS_PROTECTED_ZONE).
+//
+// Who may do what is decided by the caller's role, which the guard already resolves from the Orca terminal the agent
+// runs in (scripts/guards/command-guard.mjs boundGuard, hook-install.mjs bindSeatGuard) and never from anything the agent
+// says about itself:
+//   op          an op worker of a workflow on an app (job guard, role op): path 3 of the source process
+//   supervisor  the Supervisor seat (seat guard) and its [Worker] jobs (job guard of workflow 'supervisor'): path 2, the
+//               self-upgrade of .claude
+//   lead        the Kernel (job guard, role kernel)
+//   coordinator a session launched with STARCI_ROLE=coordinator (the land seat)
+//   release     STARCI_ROLE=release AND the host lock held live by role release (scripts/machine/host-lock.mjs): the release cut
+//   null        no guard, no seat, no role: the owner's own session, which the rights never restrict
+//
+// Command admission is data in modules/kernel/command-policy.yaml and is evaluated by command-policy.mjs. This module keeps
+// only role resolution and the small parsers that both the PreToolUse guard and PATH shim share. It imports nothing heavy:
+// the YAML of either policy loads only after a caller is known to have a bound role.
+import fs from 'node:fs';
+import path from 'node:path';
+import { guardsRoot } from './guards-root.mjs';
+import { pathKey, sameOrUnder } from '../lib/path-key.mjs';
+import { RUNTIME_CHANGE_CODE, runtimeWriteRefusal } from '../machine/runtime-change.mjs';
+import { opWriteScopeRefusal } from './op-write-scope.mjs';
+
+const ENV_ROLES = new Set(['op', 'supervisor', 'lead', 'coordinator', 'release']);
+const safeName = (s) => String(s).replace(/[^A-Za-z0-9._-]/g, '_');
+const RUNTIME_MARKER = path.join('knowledge', 'hfs', 'runtime-slots.yaml');
+const WALK_LIMIT = 24;
+
+/** <guards root>/seats/<handle>.json (the seat guard bound to an Orca terminal), or null. */
+export function boundSeat(handle, { root, env = process.env } = {}) {
+  if (!handle) return null;
+  try { return JSON.parse(fs.readFileSync(path.join(guardsRoot(root, env), 'seats', `${safeName(handle)}.json`), 'utf8')); }
+  catch { return null; }
+}
+
+/** <guards root>/terminals/<handle>.json (the terminal-bound job guard), or null. */
+export function boundGuard(handle, { root, env = process.env } = {}) {
+  if (!handle) return null;
+  try { return JSON.parse(fs.readFileSync(path.join(guardsRoot(root, env), 'terminals', `${safeName(handle)}.json`), 'utf8')); }
+  catch { return null; }
+}
+
+/** Actual terminal/seat binding: missing is absent; unreadable, linked or contradictory is unknown. */
+export function boundIdentityOf(handle, { root, env = process.env } = {}) {
+  const read = (family) => {
+    const file = path.join(guardsRoot(root, env), family, `${safeName(handle)}.json`);
+    let stat;
+    try { stat = fs.lstatSync(file); } catch (error) { if (error.code === 'ENOENT') { return null; } throw error; }
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('non-regular caller binding');
+    const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value) || value.terminal !== handle) throw new Error('contradictory caller binding');
+    return value;
+  };
+  if (!handle) return { guard: null, seat: null };
+  return { guard: read('terminals'), seat: read('seats') };
+}
+
+/**
+ * The caller's rights role, or null (the owner's own session). `lockOwner` is the host lock's owner object (or null): the
+ * release role needs it, so a session cannot claim release by an environment variable alone.
+ */
+export function rightsRoleOf({ guard = null, seat = null, env = process.env, lockOwner = null } = {}) {
+  const claimed = String(env?.STARCI_ROLE ?? '').toLowerCase();
+  if (guard?.role === 'kernel') return 'lead';
+  if (guard?.role === 'critic') return 'critic';
+  if (guard?.role === 'op') return guard.workflowId === 'supervisor' ? 'supervisor' : 'op';
+  if (seat?.role === 'supervisor') return 'supervisor';
+  // A claim never outranks a bound guard or seat; the release claim holds only while the host lock is held live by role release.
+  if (claimed === 'release') return lockOwner && !lockOwner.stale && lockOwner.role === 'release' ? 'release' : null;
+  if (ENV_ROLES.has(claimed)) return claimed;
+  return null;
+}
+
+/* ------------------------------------------------------------------------------------------ command-policy parsers */
+
+const GIT_GLOBAL_WITH_VALUE = new Set(['--git-dir', '--work-tree', '--namespace', '--super-prefix', '--exec-path', '--attr-source']);
+
+/** {sub, rest} of `git [global options] <sub> <args...>`. */
+export function gitSubOf(args) {
+  let i = 0;
+  while (i < args.length) {
+    const a = String(args[i]);
+    if ((a === '-C' || a === '-c' || a === '--config-env' || GIT_GLOBAL_WITH_VALUE.has(a)) && i + 1 < args.length) { i += 2; continue; }
+    if (a.startsWith('-')) { i += 1; continue; }
+    break;
+  }
+  return { sub: args[i] == null ? null : String(args[i]), rest: args.slice(i + 1).map(String) };
+}
+
+const PUSH_VALUE_OPTIONS = new Set(['-o', '--push-option', '--repo', '--receive-pack', '--exec']);
+const PUSH_ALL = /^--(?:all|mirror|tags|follow-tags|prune)$/;
+
+/** The destination refs of one `git push` call: {remote, refs[], broad}. broad = the call pushes more than the refspecs name. */
+export function pushTargets(rest) {
+  const words = [];
+  let broad = false;
+  for (let i = 0; i < rest.length; i += 1) {
+    const a = rest[i];
+    if (PUSH_VALUE_OPTIONS.has(a)) { i += 1; continue; }
+    if (a.startsWith('-')) { if (PUSH_ALL.test(a)) { broad = true; } continue; }
+    words.push(a);
+  }
+  const refs = words.slice(1).map((spec) => {
+    const s = spec.replace(/^\+/, '');
+    const dst = s.includes(':') ? s.slice(s.indexOf(':') + 1) : s;
+    return dst.replace(/^refs\/heads\//, 'refs/heads/');
+  });
+  return { remote: words[0] ?? null, refs, broad: broad || words.length < 2 };
+}
+
+const optionName = (value) => String(value).split('=', 1)[0];
+const optionWords = (rest, takesValue = new Set()) => {
+  const options = [], words = [];
+  for (let i = 0; i < rest.length; i += 1) {
+    const value = String(rest[i]);
+    if (value === '--') { words.push(...rest.slice(i + 1).map(String)); break; }
+    if (!value.startsWith('-')) { words.push(value); continue; }
+    options.push(value);
+    if (!value.includes('=') && takesValue.has(optionName(value)) && rest[i + 1] != null) words.push(String(rest[++i]));
+  }
+  return { options, words };
+};
+
+const BRANCH_READ = new Set(['--list', '-l', '-a', '--all', '-r', '--remotes', '-v', '--verbose', '--show-current', '--contains', '--merged', '--points-at']);
+const BRANCH_VALUES = new Set(['--contains', '--merged', '--points-at']);
+const TAG_READ = new Set(['-l', '--list', '-v', '--verify', '--points-at', '--contains', '--merged', '-n']);
+const TAG_VALUES = new Set(['--points-at', '--contains', '--merged']);
+const CONFIG_READ = new Set(['--get', '--get-all', '--get-regexp', '--list', '-l', '--show-origin']);
+
+const branchListRead = (list) => {
+  const { options, words } = optionWords(list, BRANCH_VALUES);
+  if (options.some((value) => !BRANCH_READ.has(optionName(value)))) return false;
+  const valueCount = options.filter((value) => BRANCH_VALUES.has(optionName(value)) && !value.includes('=')).length;
+  return options.some((value) => ['--list', '-l'].includes(optionName(value))) || words.length <= valueCount;
+};
+
+const tagListRead = (list) => {
+  if (!list.length) return true;
+  const { options, words } = optionWords(list, TAG_VALUES);
+  const normalized = options.map((value) => /^-n\d*$/.test(value) ? '-n' : optionName(value));
+  if (normalized.some((value) => !TAG_READ.has(value))) return false;
+  const valueCount = normalized.filter((value, index) => TAG_VALUES.has(value) && !options[index].includes('=')).length;
+  if (normalized.includes('-l') || normalized.includes('--list')) return true;
+  return normalized.some((value) => TAG_READ.has(value)) && (normalized.includes('-v') || normalized.includes('--verify') ? words.length <= valueCount + 1 : words.length <= valueCount);
+};
+
+/** Whether one of git's mixed read/write subcommands is in an explicitly read-only form. */
+export function gitListFormRead(sub, rest) {
+  const list = rest.map(String);
+  if (sub === 'branch') return branchListRead(list);
+  if (sub === 'tag') return tagListRead(list);
+  const words = list.filter((value) => !value.startsWith('-'));
+  if (sub === 'stash') return ['list', 'show'].includes(words[0]) && !words.slice(1).includes('push');
+  if (sub === 'worktree') return words[0] === 'list';
+  if (sub === 'remote') {
+    const options = list.filter((value) => value.startsWith('-'));
+    if (options.some((value) => !['-v', '--verbose', '--all', '--push'].includes(optionName(value)))) return false;
+    return !words.length || (words[0] === 'show' && words.length <= 2) || (words[0] === 'get-url' && words.length <= 2);
+  }
+  if (sub === 'config') return list.some((value) => CONFIG_READ.has(optionName(value)))
+    && !list.some((value) => value.startsWith('-') && !CONFIG_READ.has(optionName(value)));
+  if (sub === 'reflog') return !words.length || (words[0] === 'show' && words.length <= 2);
+  if (sub === 'notes') return ['list', 'show'].includes(words[0]);
+  return false;
+}
+
+const NODE_VALUE_FLAGS = new Set(['--import', '--require', '-r', '--loader', '--experimental-loader', '--conditions', '-C', '--test-reporter', '--test-reporter-destination', '--test-concurrency', '--test-name-pattern', '--test-skip-pattern', '--test-timeout', '--eval', '-e', '--print', '-p']);
+const WHOLE_TREE = [/(?:^|\/)tests\/\*\*/, /^\*\*\/\*\.(?:spec|test)\.m?js$/, /^(?:\.\/)?tests\/?$/];
+
+/** True when a `node --test` call names no file or names the whole tests tree (a glob over tests/**, or the tests directory itself). */
+export function nodeWholeSuite(args) {
+  const list = args.map(String);
+  if (!list.includes('--test')) return false;
+  const targets = [];
+  for (let i = 0; i < list.length; i += 1) {
+    if (NODE_VALUE_FLAGS.has(list[i])) { i += 1; continue; }
+    if (!list[i].startsWith('-')) targets.push(list[i].replaceAll('\\', '/'));
+  }
+  return !targets.length || targets.some((x) => WHOLE_TREE.some((re) => re.test(x)));
+}
+
+/* ----------------------------------------------------------------------------------------------------- file writes */
+
+/** One refusal of the command guard: {code, command, reason, remedy}, plus `use` (the starci verb) when the table names one. */
+export const refusal = (code, command, reason, remedy, use = null) => ({ code, command: String(command).slice(0, 200), reason, remedy, ...(use ? { use } : {}) });
+
+/** The runtime checkout root a path lies in (the nearest ancestor holding the runtime marker), or null. */
+export function runtimeRootOf(file, { exists = fs.existsSync } = {}) {
+  let dir = path.dirname(path.resolve(file));
+  for (let i = 0; i < WALK_LIMIT; i += 1) {
+    if (exists(path.join(dir, RUNTIME_MARKER))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+  return null;
+}
+
+
+/**
+ * The refusal of one file write (an Edit/Write tool call or a shell write target), or null. `edit` is the text the call
+ * adds or replaces ({old, new}), read for catalog entries; `declaration` and `zoneOfPath` are injected by the guard (the
+ * YAML loads only here, only for a role that can be refused).
+ */
+export function fileWriteVerdict({ role, filePath, tool = 'Edit', edit = null, guard = null, zone = null, shell = false }) {
+  if (role !== 'supervisor' && role !== 'op') return null;
+  const file = path.resolve(filePath);
+  if (role === 'op') {
+    const runtimeRoot = zone?.runtimeRoot ?? runtimeRootOf(file);
+    const own = [guard?.workflowWorktree, ...(guard?.owned ?? [])].filter(Boolean);
+    if (!runtimeRoot || own.some((dir) => sameOrUnder(pathKey(file), pathKey(dir)))) return opScopeVerdict(file, guard);
+    return refusal('RIGHTS_OP_RUNTIME_WRITE', file, 'an op works on its app in the workflow worktree and never writes inside the .claude runtime checkout: a defect of the harness is not the op\'s to fix',
+      'record a lesson or an upgrade request in your report (kernel report: lessons / upgrade request); the owner path or the supervisor self-upgrade picks it up');
+  }
+  if (!zone?.runtimeRoot) return null;
+  if (zone.zone) {
+    return refusal('RIGHTS_PROTECTED_ZONE', zone.rel, `${zone.rel} is in the protected zone (${zone.zone.id}: ${zone.zone.why}): a supervisor self-upgrade does not edit it`,
+      'file an owner proposal (what to change in the protected zone and why); only the owner path edits the guard, the release cut, the git hooks, the CI triggers, the test policy, the host lock and the permission settings');
+  }
+  if (zone.catalog) {
+    const verdict = catalogWriteVerdict({ zone, shell, tool, edit });
+    if (verdict) return verdict;
+  }
+  const change = runtimeWriteRefusal();
+  return refusal(RUNTIME_CHANGE_CODE, zone.rel, change.reason, change.remedy);
+}
+
+/** The refusal of an Op write outside its owned paths (op-write-scope.mjs), or null. */
+function opScopeVerdict(file, guard) {
+  const outside = opWriteScopeRefusal({ file, guard });
+  return outside ? refusal(outside.code, file, outside.reason, outside.remedy) : null;
+}
+
+/** The protected-zone refusal for a catalog write, or null when no protected entry is named. */
+function catalogWriteVerdict({ zone, shell, tool, edit }) {
+  const named = shell || tool === 'Write' ? ['whole-file write'] : (zone.catalogNames?.(zone.catalog, `${edit?.old ?? ''}\n${edit?.new ?? ''}`) ?? []);
+  if (!named.length) return null;
+  const how = shell || tool === 'Write' ? 'rewrites the whole file' : `names ${named.join(', ')}`;
+  return refusal('RIGHTS_PROTECTED_ZONE', zone.rel, `${zone.rel} holds catalog entries that enforce the protected zone (${zone.catalog.ids.concat(zone.catalog.codes).slice(0, 6).join(', ')}...): this write ${how}`,
+    'edit other entries with the Edit tool (an edit that names no protected rule id or code passes); a change to a protected entry is an owner proposal');
+}
+
+const WRITE_LAST = new Set(['cp', 'install', 'copy', 'copy-item', 'cpi']);
+const WRITE_ALL = new Set(['mv', 'move', 'move-item', 'mi', 'ren', 'rename', 'rename-item', 'rni', 'rm', 'rmdir', 'rd', 'del', 'erase', 'remove-item', 'ri', 'tee', 'touch', 'truncate', 'set-content', 'sc', 'add-content', 'ac', 'out-file', 'clear-content', 'clc', 'new-item', 'ni', 'mkdir']);
+const IN_PLACE = new Set(['sed', 'perl', 'ruby']);
+
+/** The absolute paths one parsed command writes by a known writer program (cp, mv, rm, tee, sed -i, Set-Content, ...). */
+export function writeTargetsOf(command) {
+  const { program, args, cwd } = command;
+  const operands = args.map(String).filter((a) => !a.startsWith('-') && !/^[A-Za-z][A-Za-z0-9]*:$/.test(a));
+  let picks = [];
+  if (WRITE_LAST.has(program)) picks = operands.slice(-1);
+  else if (WRITE_ALL.has(program)) picks = operands;
+  else if (IN_PLACE.has(program) && args.some((a) => /^-[a-zA-Z]*i/.test(String(a)))) picks = operands.slice(1);
+  else if (program === 'dd') picks = args.map(String).filter((a) => a.startsWith('of=')).map((a) => a.slice(3));
+  return picks.filter((p) => p && !/[*?]/.test(p)).map((p) => path.resolve(cwd ?? process.cwd(), p));
+}
+
+/** The redirection targets (`> file`, `>> file`, `*> file`) of a raw command text, resolved against `cwd`. */
+export function redirectTargetsOf(text, cwd = process.cwd()) {
+  const out = [];
+  for (const m of String(text ?? '').matchAll(/(?:^|[^<>&0-9])(?:\d|\*)?>{1,2}\s*("[^"\n]+"|'[^'\n]+'|[^\s;&|()<>"']+)/g)) {
+    const target = m[1].replace(/^["']|["']$/g, '');
+    if (/^(?:&|\/dev\/null$|\$null$|nul$)/i.test(target)) continue;
+    out.push(path.resolve(cwd, target));
+  }
+  return out;
+}

package/runtime/scripts/guards/seat-tools.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// seat-tools.mjs — the Claude Code PreToolUse hook that enforces a seat's denied tools (.claude/settings.json).
+// worker-start takes no provider argv, so a seat launched through it cannot carry --disallowedTools: the runtime binds
+// the seat's terminal instead (scripts/guards/hook-install.mjs bindSeatGuard -> <guards root>/seats/<handle>.json) and this
+// hook denies exactly those tools for exactly that terminal (ORCA_TERMINAL_HANDLE, which Orca exports into it).
+// Every other session - no Orca handle, or a handle with no seat guard - passes untouched.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { boundGuard, boundSeat } from './rights.mjs';
+import { hookErrorMessage, readInput, writeHookOutput } from './hook-io.mjs';
+import { isMain } from '../lib/is-main.mjs';
+import { readEnv } from '../lib/env.mjs';
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+/** The deny decision for one hook input, or null to pass: {reason} when `toolName` is denied for `handle`. */
+function seatToolDecision({ handle, toolName, guard }) {
+  if (!handle || !toolName) return null;
+  if (!Array.isArray(guard?.deniedTools) || !guard.deniedTools.includes(toolName)) return null;
+  return { reason: `${toolName} is denied for the ${guard.role ?? 'seat'} (${handle}): in-process subagents are outside the Supervisor's menu - answer the menu with starci supervisor decide, or record a runtime defect with starci supervisor actions record --item runtime-defect:<cause> (modules/supervisor/supervisor-prompt.md).` };
+}
+
+/** Exported hook entry for the published CLI's in-process guard fast path. */
+export async function main({ stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, env = process.env, root = skillRoot } = {}) {
+  const handle = readEnv('ORCA_TERMINAL_HANDLE', env);
+  const seat = boundSeat(handle, { root, env });
+  const enforced = Boolean(seat || boundGuard(handle, { root, env }) || readEnv('STARCI_ROLE', env));
+  let toolName = null;
+  try { toolName = JSON.parse(await readInput(stdin))?.tool_name ?? null; }
+  catch (error) {
+    const reason = `seat-tools error (${hookErrorMessage(error)})`;
+    const outcome = enforced ? 'refusing the tool' : 'passing the tool through';
+    await writeHookOutput(stderr, `starci guard: ${reason}; ${outcome}\n`).catch(() => false);
+    if (enforced) await denyTool(stdout, reason);
+    return enforced ? 2 : 0;
+  }
+  if (toolName) {
+    const decision = seatToolDecision({ handle, toolName, guard: seat });
+    if (decision && !await denyTool(stdout, decision.reason)) return 2;
+  }
+  return 0;
+}
+
+/** Deliver a Claude denial within the output budget; failed delivery keeps the hook's blocking exit. */
+const denyTool = (stdout, reason) => writeHookOutput(stdout, `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason } })}\n`).catch(() => false);
+
+if (isMain(import.meta.url)) process.exit(await main());

package/runtime/scripts/guards/shell-commands.mjs

@@ -0,0 +1,328 @@
+// shell-commands.mjs - the shell text of one agent call read as commands: quotes group, separators split, redirections and comments drop,
+// command substitutions, wrappers (bash -c, powershell -Command, cmd /c, env, xargs, npx, command/exec/...), assignments and cd are opened,
+// so the command guard (command-guard.mjs) and its rule modules judge the commands that would run, never the text around them.
+// Pure: text in, [{program, args, cwd, env, word, dialect}] out. The guard re-exports simpleCommands, programOf and commandsOf.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/* ------------------------------------------------------------ command text */
+
+const SEPARATORS = new Set([';', '&', '|', '(', ')', '{', '}', '\n']);
+
+/** The index of the ')' closing the '(' just before `from` in `text` (text.length when none does). */
+function closingParenIn(text, from) {
+  let depth = 1;
+  for (let j = from; j < text.length; j += 1) {
+    if (text[j] === '(') depth += 1;
+    else if (text[j] === ')' && --depth === 0) return j;
+  }
+  return text.length;
+}
+
+/**
+ * The simple commands of one command line, in order: [[word, ...], ...]. Quotes group, separators (; & | && || ( ) { }
+ * newline) split, redirections and comments drop, and a command substitution $(...) is a command of its own. Bash
+ * and PowerShell text are both read: a backslash is a literal (Windows paths), a backtick splits in bash and escapes
+ * in PowerShell. $VAR, ${VAR}, $env:VAR and a leading ~ expand from `env`.
+ */
+export function simpleCommands(text, { dialect = 'bash', env = process.env } = {}) {
+  const s = String(text ?? '');
+  const st = { out: [], words: [], word: null, nested: [], heredocs: [] };
+  const endWord = () => { if (st.word != null) { st.words.push(st.word); } st.word = null; };
+  const endCommand = () => { endWord(); if (st.words.length) { st.out.push(st.words); } st.words = []; };
+  const expand = (name) => env?.[name] ?? env?.[Object.keys(env ?? {}).find((k) => k.toLowerCase() === name.toLowerCase())] ?? '';
+  const closingParen = (from) => closingParenIn(s, from);
+  // $NAME, ${NAME}, $env:NAME at s[i] ('$'); returns [value, next index] or null for a lone '$'.
+  const variable = (i) => {
+    const m = /^\$(?:\{([A-Z_]\w*)\}|(env:)?([A-Z_]\w*))/i.exec(s.slice(i));
+    if (!m) return null;
+    // PowerShell's $true, $false and $null are literals, never environment variables.
+    if (dialect === 'powershell' && !m[2] && m[3] && /^(?:true|false|null)$/i.test(m[3])) return [m[0], i + m[0].length];
+    return [expand(m[1] ?? m[3]), i + m[0].length];
+  };
+  /* Each `take*` below handles one special construct at s[i] and returns the index of its last consumed
+     character (the loop's += 1 resumes after it), or -1 when the construct does not apply at s[i]. */
+
+  // $(...) substitution (nested command), $env:NAME = value assignment, $VAR expansion.
+  const takeDollar = (i) => {
+    if (s[i + 1] === '(') {
+      const end = closingParen(i + 2);
+      st.nested.push(s.slice(i + 2, end));
+      st.word = (st.word ?? '') + '$()';
+      return end;
+    }
+    // PowerShell's `$env:NAME = value` is an assignment (NAME=value), not an expansion.
+    const assign = st.word == null ? /^\$env:([A-Z_]\w*)\s*=(?!=)\s*/i.exec(s.slice(i)) : null;
+    if (assign) { st.word = `${assign[1]}=`; return i + assign[0].length - 1; }
+    const v = variable(i);
+    if (v) { st.word = (st.word ?? '') + v[0]; return v[1] - 1; }
+    return -1;
+  };
+  const isQuotedEscape = (j) => (s[j] === '\\' && dialect !== 'powershell' && (s[j + 1] === '"' || s[j + 1] === '$' || s[j + 1] === '\\'))
+    || (s[j] === '`' && dialect === 'powershell');
+  const queueQuotedSubstitution = (j) => {
+    const end = closingParen(j + 2);
+    st.nested.push(s.slice(j + 2, end));
+    return end;
+  };
+  const doubleQuotedText = (i) => {
+    let j = i + 1;
+    let v = '';
+    while (j < s.length && s[j] !== '"') {
+      if (isQuotedEscape(j)) { v += s[j + 1] ?? ''; j += 2; continue; }
+      if (s[j] === '$' && s[j + 1] === '(') { const end = queueQuotedSubstitution(j); v += '$()'; j = end + 1; continue; }
+      const expanded = s[j] === '$' ? variable(j) : null;
+      if (expanded) { v += expanded[0]; j = expanded[1]; continue; }
+      v += s[j];
+      j += 1;
+    }
+    return { value: v, end: j };
+  };
+  const takeQuote = (i) => {
+    if (s[i] === "'") {
+      const end = s.indexOf("'", i + 1);
+      st.word = (st.word ?? '') + s.slice(i + 1, end < 0 ? s.length : end);
+      return end < 0 ? s.length : end;
+    }
+    const quoted = doubleQuotedText(i);
+    st.word = (st.word ?? '') + quoted.value;
+    return quoted.end;
+  };
+  const takeBacktick = (i) => {
+    if (dialect === 'powershell') { st.word = (st.word ?? '') + (s[i + 1] ?? ''); return i + 1; }
+    endCommand();
+    return i;
+  };
+  const takeComment = (i) => {
+    if (st.word != null) return -1;
+    const nl = s.indexOf('\n', i);
+    return nl < 0 ? s.length : nl - 1;
+  };
+  // A bash heredoc mark (<<WORD, <<-WORD, <<'WORD') queues the body the next newline skips.
+  const takeHeredocMark = (i) => {
+    const heredoc = dialect !== 'powershell' && s[i + 1] === '<' && s[i + 2] !== '<'
+      ? /^<<(-?)[ \t]*(?:'([^'\n]*)'|"([^"\n]*)"|\\?([^\s;&|()<>'"]+))/.exec(s.slice(i)) : null;
+    if (!heredoc) return -1;
+    endWord();
+    st.heredocs.push({ strip: heredoc[1] === '-', delimiter: heredoc[2] ?? heredoc[3] ?? heredoc[4], expands: heredoc[4] != null && !heredoc[0].includes('\\') });
+    return i + heredoc[0].length - 1;
+  };
+  // At a newline, each queued heredoc body is skipped to its delimiter; an unquoted body still runs its $(...) substitutions.
+  const queueHeredocSubstitutions = (line) => {
+    for (const m of line.matchAll(/\$\(/g)) st.nested.push(line.slice(m.index + 2, closingParenIn(line, m.index + 2)));
+  };
+  const skipHeredocBody = (doc, at) => {
+    while (at < s.length) {
+      const nl = s.indexOf('\n', at);
+      const line = s.slice(at, nl < 0 ? s.length : nl).replace(/\r$/, '');
+      at = nl < 0 ? s.length : nl + 1;
+      if ((doc.strip ? line.replace(/^\t+/, '') : line) === doc.delimiter) break;
+      if (doc.expands) queueHeredocSubstitutions(line);
+    }
+    return at;
+  };
+  const takeHeredocBody = (i) => {
+    if (!st.heredocs.length) return -1;
+    endCommand();
+    let at = i + 1;
+    for (const doc of st.heredocs.splice(0)) at = skipHeredocBody(doc, at);
+    return at - 1;
+  };
+  // A redirection and its target are not arguments: `2>&1`, `>> log`, `*> $null`, `< in`.
+  const takeRedirect = (i) => {
+    if (st.word != null && /^(?:\d|\*)$/.test(st.word)) st.word = null;
+    endWord();
+    let j = i + 1;
+    while (s[j] === '>' || s[j] === '&') j += 1;
+    if (/\d/.test(s[j] ?? '') && s[j - 1] === '&') return j;
+    while (s[j] === ' ' || s[j] === '\t') j += 1;
+    if (s[j] === '"' || s[j] === "'") { const q = s[j]; const end = s.indexOf(q, j + 1); j = end < 0 ? s.length : end + 1; }
+    else while (j < s.length && !/[\s;&|()<>]/.test(s[j])) j += 1;
+    return j - 1;
+  };
+  const takeTilde = (i) => {
+    if (st.word != null || !(s[i + 1] === '/' || s[i + 1] === '\\' || s[i + 1] == null || /\s/.test(s[i + 1]))) return -1;
+    st.word = os.homedir();
+    return i;
+  };
+  // s[i] as a special construct; -1 when it is an ordinary character.
+  const takeSpecial = (i) => {
+    const c = s[i];
+    if (c === '$') return takeDollar(i);
+    if (c === "'" || c === '"') return takeQuote(i);
+    if (c === '`') return takeBacktick(i);
+    if (c === '#') return takeComment(i);
+    if (c === '<') { const h = takeHeredocMark(i); return h >= 0 ? h : takeRedirect(i); }
+    if (c === '>') return takeRedirect(i);
+    if (c === '\n') return takeHeredocBody(i);
+    if (c === '~') return takeTilde(i);
+    return -1;
+  };
+  for (let i = 0, step = 1; i < s.length; i += step) {
+    step = 1;
+    const n = takeSpecial(i);
+    if (n >= 0) { step = n - i + 1; continue; }
+    const c = s[i];
+    if (c === '\r') continue;
+    if (SEPARATORS.has(c)) { endCommand(); continue; }
+    if (c === ' ' || c === '\t') { endWord(); continue; }
+    st.word = (st.word ?? '') + c;
+  }
+  endCommand();
+  for (const inner of st.nested) st.out.push(...simpleCommands(inner, { dialect, env }));
+  return st.out;
+}
+
+/** A command word as the program it names: basename, lowercase, without .exe/.cmd/.bat/.ps1. */
+export const programOf = (word) => path.basename(String(word ?? '').replaceAll('\\', '/')).toLowerCase().replace(/\.(?:exe|cmd|bat|ps1)$/, '');
+
+const ASSIGNMENT = /^([A-Za-z_]\w*)=(.*)$/s;
+const PREFIX_PROGRAMS = new Set(['command', 'exec', 'time', 'nohup', 'sudo', 'builtin']);
+const SHELLS = new Set(['bash', 'sh', 'zsh', 'dash']);
+const POWERSHELLS = new Set(['powershell', 'pwsh']);
+const CD_PROGRAMS = new Set(['cd', 'set-location', 'sl', 'chdir', 'pushd', 'push-location']);
+
+// command/exec/time/nohup/sudo/builtin <maybe one flag> <real command> - drop the wrapper word.
+const unPrefix = (w) => w.slice(1).filter((a, i, all) => !(i === 0 && a.startsWith('-') && all.length > 1));
+// env [-u NAME | -C dir | -S str | VAR=value]... <real command>: the options and assignments apply to what follows.
+const unEnv = (w, cmdEnv) => {
+  w = w.slice(1);
+  while (w.length && (w[0].startsWith('-') || ASSIGNMENT.test(w[0]))) {
+    const m = ASSIGNMENT.exec(w[0]);
+    if (m) cmdEnv[m[1]] = m[2];
+    const takesValue = /^-[uCS]$/.test(w[0]);
+    w.shift();
+    if (takesValue) w.shift();
+  }
+  return w;
+};
+const unXargs = (w) => {
+  w = w.slice(1);
+  while (w.length && w[0].startsWith('-')) {
+    const takesValue = /^-(?:[IdEnLPs]|-(?:replace|delimiter|eof|max-args|max-lines|max-procs|max-chars|arg-file))$/.test(w[0]);
+    w.shift();
+    if (takesValue) w.shift();
+  }
+  return w;
+};
+// npx [-y] [--package <pkg>] <bin> args: the package's bin is the program (@openai/codex -> codex); corepack
+// <pnpm|yarn> args runs that package manager. Same option-skip for bunx.
+const unRun = (w) => {
+  w = w.slice(1);
+  while (w.length && w[0].startsWith('-')) {
+    const takesValue = /^(?:-p|--package)$/.test(w[0]);
+    w.shift();
+    if (takesValue) w.shift();
+  }
+  return w;
+};
+// The inner command a wrapper program runs: {text, dialect} to recurse on, {} for a wrapper that runs
+// nothing visible (powershell -File with an unreadable body), null when the program is no open wrapper.
+const shellInner = (args) => {
+  const at = args.findIndex((a) => /^-[a-z]+$/.test(a) && a.includes('c'));
+  return at >= 0 && args[at + 1] != null ? { text: args[at + 1], dialect: 'bash' } : null;
+};
+const powershellInner = (args, dir) => {
+  const flagAt = (re) => args.findIndex((a) => re.test(a));
+  const enc = flagAt(/^-(?:e|ec|enc|encodedcommand)$/i);
+  if (enc >= 0 && args[enc + 1]) return { text: Buffer.from(args[enc + 1], 'base64').toString('utf16le'), dialect: 'powershell' };
+  const file = flagAt(/^-(?:f|file)$/i);
+  if (file >= 0 && args[file + 1]) {
+    let body = null;
+    try { body = fs.readFileSync(path.resolve(dir, args[file + 1]), 'utf8'); } catch { /* an unreadable script runs nothing we can see */ }
+    return body == null ? {} : { text: body, dialect: 'powershell' };
+  }
+  const command = flagAt(/^-(?:c|command)$/i);
+  if (command >= 0) return { text: args.slice(command + 1).join(' '), dialect: 'powershell' };
+  const bare = args.filter((a) => !a.startsWith('-'));
+  return bare.length ? { text: bare.join(' '), dialect: 'powershell' } : null;
+};
+const cmdInner = (args) => {
+  // Git Bash spells cmd's switch //c (MSYS would rewrite a single /c as a path).
+  const at = args.findIndex((a) => /^\/\/?[ck]$/i.test(a));
+  return at >= 0 ? { text: args.slice(at + 1).join(' '), dialect: 'cmd' } : null;
+};
+const wrappedInner = (program, args, dir) => {
+  if (SHELLS.has(program)) return shellInner(args);
+  if (POWERSHELLS.has(program)) return powershellInner(args, dir);
+  if (program === 'cmd') return cmdInner(args);
+  return null;
+};
+
+/**
+ * The commands one agent shell call runs, flattened: [{program, args, cwd, env, word, dialect}] with wrappers opened
+ * (bash -c, powershell -Command/-EncodedCommand/-File, cmd /c, env, xargs, npx/bunx, command/exec/...), leading VAR=value and
+ * export/$env: assignments applied to the commands after them, and cd/Set-Location/pushd moving the cwd.
+ */
+const leadingAssignments = (words) => {
+  const local = {};
+  while (words.length && ASSIGNMENT.test(words[0])) { const [, key, value] = ASSIGNMENT.exec(words[0]); local[key] = value; words.shift(); }
+  return local;
+};
+
+const recordEnvironmentCommand = (program, words, state) => {
+  if (program !== 'export' && program !== 'set') return false;
+  if (words.length === 1 || (words.length === 2 && words[1] === '-p'))
+    state.out.push({ program, args: words.slice(1), cwd: state.dir, env: state.scopeEnv, word: words[0], dialect: state.dialect });
+  for (const argument of words.slice(1)) {
+    const assignment = ASSIGNMENT.exec(argument);
+    if (assignment) state.scopeEnv[assignment[1]] = assignment[2];
+  }
+  return true;
+};
+
+const unwrapCommandWrappers = (words, program, cmdEnv, state) => {
+  for (let guard = 0; guard < 6; guard += 1) {
+    if (PREFIX_PROGRAMS.has(program)) words = unPrefix(words);
+    else if (program === 'env') {
+      const envWord = words[0];
+      words = unEnv(words, cmdEnv);
+      // `env` and `env -u NAME` with no command to run print the whole environment: they stay a command for ENV_DUMP.
+      if (!words.length) state.out.push({ program: 'env', args: [], cwd: state.dir, env: cmdEnv, word: envWord, dialect: state.dialect });
+    } else if (program === 'xargs') words = unXargs(words);
+    else if (program === 'npx' || program === 'bunx' || program === 'corepack') words = unRun(words);
+    else break;
+    if (!words.length) break;
+    program = programOf(words[0]);
+  }
+  return { words, program };
+};
+
+const changeDirectory = (program, args, state) => {
+  if (!CD_PROGRAMS.has(program)) return false;
+  // cmd's `cd /d <dir>` switches the drive too: /d is a switch there, not the target.
+  const target = args.find((a) => !a.startsWith('-') && !(state.dialect === 'cmd' && /^\/d$/i.test(a)));
+  if (target) state.dir = path.resolve(state.dir, target);
+  return true;
+};
+
+const openWrapper = (program, args, cmdEnv, state) => {
+  const inner = wrappedInner(program, args, state.dir);
+  if (!inner) return false;
+  if (inner.text != null) state.out.push(...commandsOf(inner.text, { cwd: state.dir, env: cmdEnv, dialect: inner.dialect, depth: state.depth + 1 }));
+  return true;
+};
+
+const processWords = (sourceWords, state) => {
+  let words = [...sourceWords];
+  const local = leadingAssignments(words);
+  if (!words.length) { Object.assign(state.scopeEnv, local); return; }
+  let program = programOf(words[0]);
+  if (recordEnvironmentCommand(program, words, state)) return;
+  const cmdEnv = { ...state.scopeEnv, ...local };
+  ({ words, program } = unwrapCommandWrappers(words, program, cmdEnv, state));
+  if (!words.length) return;
+  const args = words.slice(1);
+  if (changeDirectory(program, args, state)) return;
+  if (openWrapper(program, args, cmdEnv, state)) return;
+  state.out.push({ program, args, cwd: state.dir, env: cmdEnv, word: words[0], dialect: state.dialect });
+};
+
+export function commandsOf(text, { cwd, env = process.env, dialect = 'bash', depth = 0 } = {}) {
+  const out = [];
+  if (depth > 4) return out;
+  const state = { dir: cwd, scopeEnv: { ...env }, out, dialect, depth };
+  for (const words of simpleCommands(text, { dialect, env: state.scopeEnv })) processWords(words, state);
+  return out;
+}