@starci/hfs 4.8.0 → 4.9.0

package/runtime/scripts/guards/env-dump-verdict.mjs

@@ -1,89 +0,0 @@
-// env-dump-verdict.mjs - the command guard's ENV_DUMP rule: a command that writes the WHOLE environment to output (`env`,
-// `printenv`, bare `set`, `export -p`, `declare -x|-p`, `Get-ChildItem env:`, [Environment]::GetEnvironmentVariables(),
-// `node -p process.env`, `python -c "print(os.environ)"`, `cmd /c set`). The environment carries every token and key the
-// session holds (the AWS, Azure and Anthropic values reached a transcript through `env | grep ... | sed`); a filter or a
-// redaction after the dump does not make it safe, because names outside the pattern leak. Reading ONE named variable
-// (`echo $PATH`, `printenv HOME`, `$env:PATH`, process.env.HOME), `env VAR=x cmd`, `env -u VAR cmd` and shell options
-// (`set -e`, `set -euo pipefail`) pass, and so does any text that only mentions these commands: the rule judges parsed
-// commands, so an echo, a commit message, a heredoc or a comment never reaches it.
-import { assignedCommand } from './assigned-command.mjs';
-
-const ENV_DRIVE = /^env:[\\/]?\*?$/i;
-const LISTERS = new Set(['get-childitem', 'gci', 'dir', 'ls', 'get-item', 'gi']);
-const GET_ENV = /^\[(?:system\.)?environment\]::getenvironmentvariables$/i;
-const NODE_PROGRAMS = new Set(['node', 'nodejs']);
-const PYTHON_PROGRAMS = new Set(['python', 'python3', 'python2', 'py']);
-// process.env as the whole argument of a printing or serialising call; or the whole value of `node -p`.
-const NODE_WHOLE = new RegExp([
-  String.raw`(?:console\.\w+|JSON\.stringify|util\.inspect|\binspect|Object\.(?:keys|entries|values)|process\.std(?:out|err)\.write|require\(['"]fs['"]\)\.\w+|writeFileSync)`,
-  String.raw`\s*\(\s*(?:[^()]*,\s*)?process\.env\s*[,)]`,
-].join(''));
-const NODE_PRINT_WHOLE = new RegExp([String.raw`^\s*`, String.raw`process\.env`, String.raw`\s*;?\s*$`].join(''));
-const PYTHON_WHOLE = new RegExp([
-  String.raw`(?:\bprint|pprint|json\.dumps|\bdict|\blist|\bsorted|\brepr|\bstr)`,
-  String.raw`\s*\(\s*(?:[^()]*,\s*)?(?:os\.)?environ\s*[,)\]]|\benviron\.(?:items|keys|values|copy)\s*\(`,
-].join(''));
-const PYTHON_OUTPUT = /\bprint\b|pprint|json\.dumps|stdout|\.write\(/;
-
-const refusal = (c, how) => ({ code: 'ENV_DUMP', command: [c.program, ...c.args].join(' ').slice(0, 200),
-  reason: `${how} writes the whole environment to output, including every token and key the session holds; a grep or a redaction after it still leaks the names it does not match (the AWS, Azure and Anthropic values reached a transcript that way)`,
-  remedy: 'read only the one named, non-secret variable you need (echo $NAME, $env:NAME, printenv NAME); never dump the environment' });
-
-const namesNothing = (args) => !args.some((a) => !a.startsWith('-'));
-const scriptAfter = (args, flag) => { const at = args.findIndex((a) => flag.test(a)); return at >= 0 ? args[at + 1] ?? '' : null; };
-
-// A relative path such as runtime/env is a file of that name, not the env program (an absolute path still is).
-const isRelativeProgramPath = (word) => /[\\/]/.test(String(word ?? '')) && !/^(?:[a-z]:)?[\\/]/i.test(String(word));
-
-// `declare`/`typeset` with no name lists every variable (no option, or -x / -p).
-const declareListsAll = (args) => {
-  const options = args.filter((a) => /^-[a-zA-Z]+$/.test(a)).join('');
-  return namesNothing(args) && (!options || /[xp]/.test(options));
-};
-
-const declareDump = (c) => (declareListsAll(c.args) ? refusal(c, `${c.program} with no name`) : null);
-const BUILTIN_DUMPS = new Map([
-  ['set', (c) => (c.args.length === 0 && c.dialect !== 'powershell' ? refusal(c, 'set') : null)],
-  ['export', (c) => (c.args.length === 0 || (c.args.length === 1 && c.args[0] === '-p') ? refusal(c, 'export -p') : null)],
-  ['declare', declareDump],
-  ['typeset', declareDump],
-]);
-
-/** The shell-form dumpers (env/printenv/set/export/declare, PowerShell env: listers, GetEnvironmentVariables). */
-const shellDumpVerdict = (c) => {
-  const { program, args } = c;
-  if ((program === 'env' || program === 'printenv') && !isRelativeProgramPath(c.word)) return namesNothing(args) ? refusal(c, program) : null;
-  const builtin = BUILTIN_DUMPS.get(program);
-  if (builtin) return builtin(c);
-  if (LISTERS.has(program) && args.some((a) => ENV_DRIVE.test(a))) return refusal(c, `${program} env:`);
-  if (GET_ENV.test(program)) return refusal(c, '[Environment]::GetEnvironmentVariables()');
-  return null;
-};
-
-/** `node -p|-e` whose script body prints or serializes process.env whole. */
-const nodeDumpHow = (args) => {
-  const print = scriptAfter(args, /^(?:-p|--print)$/);
-  const evalOnly = scriptAfter(args, /^(?:-e|--eval)$/);
-  const body = print ?? evalOnly;
-  return body != null && (NODE_WHOLE.test(body) || (print != null && NODE_PRINT_WHOLE.test(body))) ? 'a node script printing process.env' : null;
-};
-
-/** `python -c` whose script body prints os.environ. */
-const pythonDumpHow = (args) => {
-  const body = scriptAfter(args, /^-c$/);
-  return body != null && PYTHON_WHOLE.test(body) && PYTHON_OUTPUT.test(body) ? 'a python script printing os.environ' : null;
-};
-
-/** The ENV_DUMP refusal for one parsed command, or null. */
-const interpreterDumpVerdict = (c) => {
-  if (NODE_PROGRAMS.has(c.program)) { const how = nodeDumpHow(c.args); if (how) return refusal(c, how); }
-  if (PYTHON_PROGRAMS.has(c.program)) { const how = pythonDumpHow(c.args); if (how) return refusal(c, how); }
-  return null;
-};
-
-export function envDumpVerdict(parsed) {
-  const c = assignedCommand(parsed);
-  const shell = shellDumpVerdict(c);
-  if (shell) return shell;
-  return interpreterDumpVerdict(c);
-}

package/runtime/scripts/guards/guards-root.mjs

@@ -1,27 +0,0 @@
-// guards-root.mjs - the one home of the op guard directory (jobs/, terminals/, seats/, refusals.jsonl).
-//
-// The runtime's own guards live in the host state root, never in a tracked path: <starciLocalRoot>/guards
-// (<runtime root>/.runtime/guards, or STARCI_LOCAL_ROOT/guards). STARCI_GUARDS_ROOT relocates THAT directory only - a
-// caller that names another root (a fixture's skill root) keeps <root>/runtime/guards. The node --test preload
-// (e2e/setup/isolated-temp.mjs) gives every spec process its own STARCI_GUARDS_ROOT, so two spec files that bind the
-// same fake Orca handle (fake-terminal-1) never read each other's binding, and no spec writes the live runtime's guards.
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { starciLocalRoot } from '../../engine/db/machine.mjs';
-import { isSpecRun } from '../lib/env.mjs';
-import { tempRoot } from '../../engine/temp-root.mjs';
-
-export const GUARDS_ROOT_ENV = 'STARCI_GUARDS_ROOT';
-export const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-const key = (p) => { const r = path.resolve(p); return process.platform === 'win32' ? r.toLowerCase() : r; };
-
-/**
- * The guard directory of `skillRoot`: the runtime's own lives in the host state root, a fixture root keeps its own. A spec
- * run with no STARCI_GUARDS_ROOT and no STARCI_LOCAL_ROOT uses an OS-temp directory, so a spec never writes the host's guards.
- */
-export function guardsRoot(skillRoot = SKILL_ROOT, env = process.env) {
-  if (key(skillRoot) !== key(SKILL_ROOT)) return path.join(skillRoot, 'runtime', 'guards');
-  if (env[GUARDS_ROOT_ENV]) return path.resolve(env[GUARDS_ROOT_ENV]);
-  if (isSpecRun(env) && !env.STARCI_LOCAL_ROOT) return path.join(tempRoot({ env }), 'starci-test-guards');
-  return path.join(starciLocalRoot(env), 'guards');
-}

package/runtime/scripts/guards/hook-install.mjs

@@ -1,343 +0,0 @@
-// install.mjs — puts the shared-checkout guard around an op or [Worker] agent.
-//
-// starci kernel dispatch (opGuardLaunch), the [Worker] launch (workers.mjs workerGuard) and the Kernel launch
-// (scripts/kernel/start-workflow.mjs, role 'kernel') call guardLaunch() for every agent they start
-// (modules/kernel/api.yaml conventions.sharedCheckout). Each layer is idempotent and best effort - a
-// guard that cannot be installed is reported on the dispatch receipt, never a reason to refuse the launch:
-//  1. <guards root>/jobs/<job>.json — the job's identity and owned paths as absolute paths. worker-start owns the
-//     agent's environment, so the launch binds it to the agent's Orca terminal (bindGuardTerminal ->
-//     <guards root>/terminals/<handle>.json, unbound when that terminal closes). The agent's host runs
-//     scripts/guards/command-guard.mjs as a PreToolUse hook (registered by launch trust, scripts/agent/trust.mjs):
-//     it finds the guard by ORCA_TERMINAL_HANDLE and refuses a shell command the policy forbids before it runs.
-//  2. the target repository's reference-transaction hook (git runs it for every ref update, whoever the caller is):
-//     a protected branch only moves forward and is never deleted; an op (its Orca terminal bound to a guard) creates
-//     no worktree and lands only its owned paths. (refs/stash stays writable: lint-staged's pre-commit backup stores
-//     one; the command guard refuses a sweeping stash.)
-//  3. the target repository's pre-commit hook (ensureWorkHook): a commit that stages files under .starciwork/ or
-//     .starcistacks/ is refused when a YAML does not parse, a record the commit touches fails its scoped strict
-//     validation, or a non-.enc file carries a secret (scripts/work/validate/work-hygiene.mjs; e2e never runs there).
-// config.yaml `guards: {historyHook: false}` / `{workHook: false}` switches a hook layer off.
-import fs from 'node:fs';
-import path from 'node:path';
-import { guardsRoot } from './guards-root.mjs';
-import { fileURLToPath } from 'node:url';
-import { revParseQuery } from '../api/git/rev-parse-query.mjs';
-import { checkIgnore } from '../api/git/check-ignore.mjs';
-import { lsFiles } from '../api/git/ls-files.mjs';
-import { worktreeListQuery } from '../api/git/worktree-list-query.mjs';
-import { safeRemove } from '../api/fs/safe-remove.mjs';
-import { artifactHoldReason } from '../machine/artifact-hold.mjs';
-import { allocationMs } from '../../engine/config.mjs';
-
-const here = path.dirname(fileURLToPath(import.meta.url));
-export { guardsRoot };
-const HOOK_MARKER = 'starci-history-guard';
-export const HOOK_VERSION = 9;
-export const WORK_HOOK_MARKER = 'starci-work-guard';
-export const RUNTIME_GIT_HOOKS_MARKER = 'starci-git-hooks';
-export const WORK_HOOK_VERSION = 1;
-
-const normOwned = (p) => path.resolve(p).replaceAll('\\', '/');
-const safeName = (s) => String(s).replace(/[^A-Za-z0-9._-]/g, '_');
-// A single-quoted shell word: ' wrapped as '\'' (close, escaped quote, reopen).
-const SQUOTE = String.raw`'\''`;
-export const shellQuote = (s) => `'${String(s).replaceAll('\\', '/').replaceAll("'", SQUOTE)}'`;
-const JOB_GUARD_TTL_MS = allocationMs('jobGuard.ttlMs');
-const terminalsDir = (skillRoot = path.resolve(here, '..', '..')) => path.join(guardsRoot(skillRoot), 'terminals');
-
-// tmp + rename: a reader never sees a torn guard file. Files of the directory older than JOB_GUARD_TTL_MS are pruned: a
-// guard outlives its worker only as history.
-function writeGuardFile(dir, name, body) {
-  fs.mkdirSync(dir, { recursive: true });
-  const file = path.join(dir, `${safeName(name)}.json`);
-  const tmp = `${file}.${process.pid}.tmp`;
-  fs.writeFileSync(tmp, `${JSON.stringify(body, null, 2)}\n`);
-  fs.renameSync(tmp, file);
-  try {
-    const cutoff = Date.now() - JOB_GUARD_TTL_MS;
-    for (const other of fs.readdirSync(dir)) {
-      const full = path.join(dir, other);
-      if (full !== file && fs.statSync(full).mtimeMs < cutoff) fs.rmSync(full, { force: true });
-    }
-  } catch { /* pruning is housekeeping */ }
-  return file;
-}
-
-/**
- * The roles a job guard is written for. 'op' is an op or [Worker] agent. 'kernel' is the Kernel: its shell commands meet
- * the same command guard (PreToolUse) as an op's, but the history hook does not apply its op rules to a kernel guard,
- * because the runtime's own git (checkpoints, land scratch trees) runs as children of the Kernel's api calls and
- * inherits its ORCA_TERMINAL_HANDLE (contract change kernel-guard-file). 'critic' is the Critic of a product: its `reach` names the
- * one directory it may read and the one file it may write (scripts/guards/critic-reach.mjs).
- */
-const GUARD_ROLES = Object.freeze(['op', 'kernel', 'critic']);
-
-/** <guards root>/jobs/<job>.json — who the worker is, its role and which absolute paths it owns. */
-export function writeJobGuard({ skillRoot = path.resolve(here, '..', '..'), jobId, workflowId, ledgerRepo, owned, workflowWorktree = null, role = 'op', op = null, reach = null }) {
-  if (!GUARD_ROLES.includes(role)) throw new Error(`unknown guard role ${role}`);
-  // op: the job's op id, for the rules one op family owes (a uat op never starts a test world, launch-verdict.mjs).
-  return writeGuardFile(path.join(guardsRoot(skillRoot), 'jobs'), jobId, { schema: 'starci/op-guard@1', role, jobId, workflowId, op: op ?? null,
-    ledgerRepo: ledgerRepo ? path.resolve(ledgerRepo) : null, owned: [...new Set((owned ?? []).filter(Boolean).map(normOwned))],
-    // The workflow worktree the op works in (scripts/kernel/workflow-worktree.mjs), or null: the guard refuses git history
-    // rewrites and ref changes inside it; scoped worker commits are adopted by the runtime at settle.
-    workflowWorktree: workflowWorktree ? path.resolve(workflowWorktree) : null, ...(reach ? { reach: { dir: path.resolve(reach.dir), verdictFile: reach.verdictFile } } : {}), writtenAt: new Date().toISOString() });
-}
-
-/**
- * <guards root>/terminals/<handle>.json — the job guard of a managed op, keyed by the Orca terminal its agent runs
- * in. worker-start owns a managed agent's environment; Orca exports ORCA_TERMINAL_HANDLE into that terminal, and the
- * command guard (PreToolUse hook) and the history hook find the op's guard by it.
- */
-export function bindGuardTerminal({ skillRoot = path.resolve(here, '..', '..'), handle, jobFile }) {
-  const guard = JSON.parse(fs.readFileSync(jobFile, 'utf8'));
-  return writeGuardFile(terminalsDir(skillRoot), handle, { ...guard, terminal: handle, boundAt: new Date().toISOString() });
-}
-
-/**
- * <guards root>/seats/<handle>.json — the tools a seat's agent may not use, keyed by the Orca terminal it runs in.
- * worker-start takes no provider argv, so a seat's tool denial (the [Supervisor]'s Agent/Task, start-supervisor.mjs
- * SEAT_DENIED_TOOLS) is enforced by the project PreToolUse hook (.claude/settings.json -> scripts/guards/seat-tools.mjs),
- * which denies a tool only for the terminal bound here.
- */
-const seatsDir = (skillRoot = path.resolve(here, '..', '..')) => path.join(guardsRoot(skillRoot), 'seats');
-export function bindSeatGuard({ skillRoot = path.resolve(here, '..', '..'), handle, role, deniedTools }) {
-  return writeGuardFile(seatsDir(skillRoot), handle, { schema: 'starci/seat-guard@1', role, terminal: handle,
-    deniedTools: [...new Set((deniedTools ?? []).map(String))], boundAt: new Date().toISOString() });
-}
-
-/** Remove the guard bound to terminal `handle` once that terminal is closed; true when a file was removed. */
-export function unbindGuardTerminal({ skillRoot = path.resolve(here, '..', '..'), handle }) {
-  if (!handle) return false;
-  const file = path.join(terminalsDir(skillRoot), `${safeName(handle)}.json`);
-  if (!fs.existsSync(file)) return false;
-  fs.rmSync(file, { force: true });
-  return true;
-}
-
-/** One git call (a scripts/api/git call file) in the repository at `cwd`. */
-const git = (call, cwd, args) => call(args, { dir: cwd, timeout: 20_000 });
-
-export function historyHookBody({ branches = [], root, nodePath = process.execPath, terminals = terminalsDir() }) {
-  const protectedList = [...new Set(['main', 'master', ...branches.filter((b) => /^[A-Za-z0-9._/-]+$/.test(b))])].join(' ');
-  const q = shellQuote;
-  return `#!/bin/sh
-# ${HOOK_MARKER} v${HOOK_VERSION} — installed by the StarCi runtime (scripts/guards/hook-install.mjs); rewritten on every op dispatch.
-# The shared branch is append-only (modules/ops/_common.yaml "Evidence, completion and commits"):
-# a protected branch only moves forward and is never deleted. An op - named by the Orca terminal it runs in
-# (<guards root>/terminals/<handle>.json) - never creates a worktree, and the commits it lands carry only its
-# owned paths (starci guard verify-commit).
-if [ "$1" != "prepared" ]; then exit 0; fi
-PROTECTED=" ${protectedList} "
-guard=""
-if [ -n "\${ORCA_TERMINAL_HANDLE:-}" ]; then
-  guard=${q(terminals)}/"$(printf '%s' "$ORCA_TERMINAL_HANDLE" | tr -c 'A-Za-z0-9._-' '_')".json
-fi
-[ -n "$guard" ] && [ -f "$guard" ] || guard=""
-# A kernel guard (role "kernel", writeJobGuard) is the command guard's alone: the runtime's own git under the Kernel's
-# api calls inherits its terminal, so the op rules below never read it.
-if [ -n "$guard" ] && grep -q '"role": "kernel"' "$guard"; then guard=""; fi
-status=0
-op_worktree_refused=0
-while read -r old new ref; do
-  case "$ref" in
-    HEAD)
-      # An op worker never creates a git worktree. \`git worktree add\` writes the new
-      # worktree's HEAD from the checkout it runs in, whose own HEAD is not locked: however the worker ran git, the
-      # new worktree's first ref update is refused here.
-      if [ -n "$guard" ] && [ "$op_worktree_refused" = 0 ]; then
-        gd=$(git rev-parse --git-dir 2>/dev/null)
-        fmt=$(git rev-parse --show-ref-format 2>/dev/null)
-        # A git that predates --show-ref-format (before 2.46) echoes the flag back and has only the files backend.
-        case "$fmt" in files|--show-ref-format) fmt=files ;; esac
-        if [ -n "$gd" ] && [ "$fmt" = "files" ] && [ ! -e "$gd/HEAD.lock" ]; then
-          echo "starci history guard: refused - an op worker never creates a git worktree; work in the checkout you were dispatched to (a private worktree with links into the live repository deleted live files)" >&2
-          op_worktree_refused=1; status=1
-        fi
-      fi ;;
-    refs/heads/*)
-      b="\${ref#refs/heads/}"
-      case "$PROTECTED" in *" $b "*) ;; *) continue ;; esac
-      case "$new" in *[!0]*) ;; *)
-        echo "starci history guard: refused deleting protected branch $b" >&2; status=1; continue ;; esac
-      case "$old" in *[!0]*) ;; *) old=$(git rev-parse -q --verify "$ref^{commit}" 2>/dev/null) ;; esac
-      [ -z "$old" ] && continue
-      if ! git merge-base --is-ancestor "$old" "$new" 2>/dev/null; then
-        # The runtime rewinds a workflow branch to its last checkpoint (preserveAndReset) naming the target in STARCI_BRANCH_REWIND; that is
-        # allowed only while the commit it leaves is kept under refs/heads/preserved, so nothing is lost.
-        if [ "\${STARCI_BRANCH_REWIND:-}" = "$new" ] && [ -n "$(git for-each-ref --contains "$old" --format=x refs/heads/preserved 2>/dev/null)" ]; then continue; fi
-        echo "starci history guard: refused moving protected branch $b from $old to $new - not a fast-forward (reset/amend/rebase rewrite a branch other workflows commit on; undo a commit with git revert)" >&2
-        status=1; continue
-      fi
-      if [ -n "$guard" ]; then
-        STARCI_GUARD_FILE="$guard" STARCI_RUNTIME=${q(root)} ${q(nodePath)} ${q(path.join(root, 'packages', 'cli', 'bin', 'starci.mjs'))} guard verify-commit "$old" "$new" || status=1
-      fi ;;
-  esac
-done
-exit $status
-`;
-}
-
-// A relative core.hooksPath (husky's .husky/_) resolves per checkout: husky generates that directory, with
-// its own `.gitignore` of `*`, only where `npm install` ran, so a linked worktree has none. A hooks directory
-// that does not exist yet, holds no file and has nothing tracked is given husky's own self-ignoring layout;
-// anything else stays refused. True when the hook file may be written.
-const admitFreshHooksDir = (root, hooksDir, isIgnored) => {
-  const relDir = path.relative(root, hooksDir).replaceAll('\\', '/');
-  const absent = !fs.existsSync(hooksDir);
-  const empty = absent || (fs.statSync(hooksDir).isDirectory() && fs.readdirSync(hooksDir).length === 0);
-  const tracked = git(lsFiles, root, ['--', relDir]);
-  if (!empty || tracked.status !== 0 || tracked.stdout.trim()) return false;
-  fs.mkdirSync(hooksDir, { recursive: true });
-  fs.writeFileSync(path.join(hooksDir, '.gitignore'), '*\n');
-  if (isIgnored()) return true;
-  if (absent) safeRemove(hooksDir, { hold: artifactHoldReason });
-  else fs.rmSync(path.join(hooksDir, '.gitignore'), { force: true });
-  return false;
-};
-
-/**
- * hookTarget(repoRoot, name) -> {root, hooksDir, file} | {installed: false, reason, path?}
- * Resolves where hook `name` goes: into the repository's effective hooks
- * directory (core.hooksPath, e.g. husky's .husky/_, else .git/hooks). A foreign
- * hook of that name is never overwritten; a hooks directory whose new file git
- * would offer for tracking is left alone (no foreign file in a product repo),
- * except an absent, untracked one (husky's .husky/_ in a linked worktree), which
- * gets husky's own self-ignoring `.gitignore` of `*`.
- */
-function hookTarget(repoRoot, name) {
-  const top = git(revParseQuery, repoRoot, ['--show-toplevel']);
-  if (top.status !== 0) return { installed: false, reason: 'not-a-git-checkout' };
-  const root = path.resolve(top.stdout.trim());
-  const hooks = git(revParseQuery, root, ['--git-path', 'hooks']);
-  if (hooks.status !== 0) return { installed: false, reason: 'no-hooks-path' };
-  const hooksDir = path.resolve(root, hooks.stdout.trim());
-  const file = path.join(hooksDir, name);
-  const inside = (parent, child) => { const rel = path.relative(parent, child); return !rel.startsWith('..') && !path.isAbsolute(rel); };
-  const inWorktree = inside(root, hooksDir) && !inside(path.join(root, '.git'), hooksDir);
-  if (inWorktree && !fs.existsSync(file)) {
-    const rel = path.relative(root, file).replaceAll('\\', '/');
-    const isIgnored = () => git(checkIgnore, root, ['-q', '--no-index', '--', rel]).status === 0;
-    if (!isIgnored() && !admitFreshHooksDir(root, hooksDir, isIgnored)) return { installed: false, reason: 'hooks-dir-tracked', path: file };
-  }
-  return { root, hooksDir, file };
-}
-
-/**
- * ensureHistoryHook(repoRoot) -> {installed, path?, reason?}
- * Writes the reference-transaction hook into the repository's effective hooks directory (hookTarget).
- * A foreign hook of that name is never overwritten.
- */
-export function ensureHistoryHook(repoRoot, { skillRoot = path.resolve(here, '..', '..'), nodePath = process.execPath } = {}) {
-  const target = hookTarget(repoRoot, 'reference-transaction');
-  if (target.installed === false) return target;
-  const { root, hooksDir, file } = target;
-  const branches = [];
-  const list = git(worktreeListQuery, root, ['--porcelain']);
-  if (list.status === 0) for (const line of list.stdout.split(/\r?\n/)) if (line.startsWith('branch refs/heads/')) branches.push(line.slice('branch refs/heads/'.length));
-  const body = historyHookBody({ branches, root: skillRoot, nodePath, terminals: terminalsDir(skillRoot) });
-  if (fs.existsSync(file)) {
-    const current = fs.readFileSync(file, 'utf8');
-    if (!current.includes(HOOK_MARKER)) return { installed: false, reason: 'foreign-hook', path: file };
-    if (current === body) return { installed: true, path: file, changed: false };
-  }
-  fs.mkdirSync(hooksDir, { recursive: true });
-  const tmp = `${file}.${process.pid}.tmp`;
-  fs.writeFileSync(tmp, body, { mode: 0o700 });
-  fs.renameSync(tmp, file);
-  try { fs.chmodSync(file, 0o700); } catch { /* windows */ }
-  return { installed: true, path: file, changed: true };
-}
-
-/** The work-record check shared by the dispatch hook and the runtime's generated pre-commit hook. */
-export function workHookCheck({ root, nodePath = process.execPath }) {
-  const q = shellQuote;
-  return String.raw`# ${WORK_HOOK_MARKER} v${WORK_HOOK_VERSION} - installed by the StarCi runtime (scripts/guards/hook-install.mjs); rewritten on every op dispatch.
-# Staged Work and stack files are checked before the commit exists: YAML that parses, records that pass their scoped
-# strict validation, and no secret outside an .enc file (starci work hygiene). e2e never runs here.
-if git diff --cached --name-only --diff-filter=ACMR | grep -Eq '(^|/)\.(starciwork|starcistacks)/'; then
-  STARCI_RUNTIME=${q(root)} ${q(nodePath)} ${q(path.join(root, 'packages', 'cli', 'bin', 'starci.mjs'))} work hygiene staged --repo "$(git rev-parse --show-toplevel)" || exit 1
-fi
-`;
-}
-
-/**
- * The pre-commit hook body. The check runs only when the index holds a file under .starciwork/ or .starcistacks/ (a
- * commit of anything else costs one git call). A husky dispatcher that shared the hook's place is chained after it.
- */
-function workHookBody({ root, nodePath = process.execPath }) {
-  return `#!/bin/sh
-${workHookCheck({ root, nodePath })}
-# husky's generated dispatcher (.husky/_/h) keeps running the repository's own pre-commit
-if [ -f "$(dirname "$0")/h" ]; then . "$(dirname "$0")/h"; fi
-`;
-}
-// husky 9 writes this two-line dispatcher into .husky/_/<hook>; it is generated output, so it may be wrapped.
-const HUSKY_DISPATCHER = /^#!\/usr\/bin\/env sh\s+\.\s+"\$\(dirname "\$0"\)\/h"\s*$/;
-
-/**
- * ensureWorkHook(repoRoot) -> {installed, path?, reason?, changed?}
- * Writes the pre-commit hook next to ensureHistoryHook's, by the same hookTarget rules. A foreign hook is never
- * overwritten, except husky's generated dispatcher, which the new hook wraps.
- */
-export function ensureWorkHook(repoRoot, { skillRoot = path.resolve(here, '..', '..'), nodePath = process.execPath } = {}) {
-  const target = hookTarget(repoRoot, 'pre-commit');
-  if (target.installed === false) return target;
-  const { hooksDir, file } = target;
-  const body = workHookBody({ root: skillRoot, nodePath });
-  if (fs.existsSync(file)) {
-    const current = fs.readFileSync(file, 'utf8');
-    if (current.includes(RUNTIME_GIT_HOOKS_MARKER)) return { installed: true, path: file, changed: false };
-    if (current.includes(WORK_HOOK_MARKER)) { if (current === body) return { installed: true, path: file, changed: false }; }
-    else if (!HUSKY_DISPATCHER.test(current)) return { installed: false, reason: 'foreign-hook', path: file };
-  }
-  fs.mkdirSync(hooksDir, { recursive: true });
-  const tmp = `${file}.${process.pid}.tmp`;
-  fs.writeFileSync(tmp, body, { mode: 0o700 });
-  fs.renameSync(tmp, file);
-  try { fs.chmodSync(file, 0o700); } catch { /* windows */ }
-  return { installed: true, path: file, changed: true };
-}
-
-const guardSettings = (config) => ({
-  historyHook: config?.guards?.historyHook !== false,
-  workHook: config?.guards?.workHook !== false,
-});
-
-/**
- * guardLaunch({jobId, workflowId, ledgerRepo, owned, repos, config, workflowWorktree, role, op}) -> {receipt}
- * receipt rides on the dispatch record. The caller binds receipt.jobFile to the agent's Orca terminal once
- * worker-start returns it (bindGuardTerminal), which is what the command guard and the history hook read.
- */
-export function guardLaunch({ skillRoot = path.resolve(here, '..', '..'), jobId, workflowId, ledgerRepo, owned = [], repos = [], config = null, workflowWorktree = null, role = 'op', op = null }) {
-  const settings = guardSettings(config);
-  const receipt = { jobFile: null, hooks: [] };
-  try { receipt.jobFile = writeJobGuard({ skillRoot, jobId, workflowId, ledgerRepo, owned, workflowWorktree, role, op }); }
-  catch (e) { receipt.jobFile = { error: String(e?.message ?? e) }; }
-  const installPerRepo = (repos, install, sink) => {
-    for (const repo of new Set(repos.filter(Boolean).map((r) => path.resolve(r)))) {
-      try { sink.push({ repo, ...install(repo) }); }
-      catch (e) { sink.push({ repo, installed: false, reason: String(e?.message ?? e) }); }
-    }
-  };
-  if (settings.historyHook) installPerRepo(repos, (repo) => ensureHistoryHook(repo, { skillRoot }), receipt.hooks);
-  else receipt.hooks = [{ disabled: true }];
-  if (settings.workHook) { receipt.workHooks = []; installPerRepo(repos, (repo) => ensureWorkHook(repo, { skillRoot }), receipt.workHooks); }
-  else receipt.workHooks = [{ disabled: true }];
-  return { receipt };
-}
-
-/**
- * The layers a dispatch receipt (guardLaunch's, as starci kernel dispatch records it on op-dispatched `guard`) says did not
- * install: [] for a whole guard. A switched-off layer is not a failure.
- */
-export function guardReceiptErrors(receipt) {
-  if (!receipt || typeof receipt !== 'object') return [];
-  const out = [];
-  const err = (layer, value) => { if (value) out.push(`${layer}: ${String(value).slice(0, 160)}`); };
-  err('guard', receipt.error);
-  err('jobFile', receipt.jobFile?.error);
-  err('terminal', receipt.terminal?.error);
-  for (const hook of Array.isArray(receipt.hooks) ? receipt.hooks : []) if (hook?.installed === false) err(`history hook ${hook.repo ?? ''}`.trim(), hook.reason ?? 'not installed');
-  for (const hook of Array.isArray(receipt.workHooks) ? receipt.workHooks : []) if (hook?.installed === false) err(`work hook ${hook.repo ?? ''}`.trim(), hook.reason ?? 'not installed');
-  return out;
-}

package/runtime/scripts/guards/hook-verdict.mjs

@@ -1,12 +0,0 @@
-import { hookErrorMessage } from './hook-io.mjs';
-
-/** One IPC request from the owning hook; the process ends after its result reaches that parent. */
-export function receiveVerdict(decide) {
-  process.once('disconnect', () => process.exit(2));
-  process.once('message', async ({ input, root, bindings }) => {
-    let result;
-    try { result = { ok: true, decision: await decide(input, { root, bindings }) }; }
-    catch (error) { result = { ok: false, error: hookErrorMessage(error) }; }
-    process.send(result, (error) => process.exit(error ? 2 : 0));
-  });
-}

package/runtime/scripts/guards/install-verdict.mjs

@@ -1,41 +0,0 @@
-// The refusals of install-family and Kernel-mailbox commands, split out of command-guard.mjs (which calls them).
-/** The install-through-link refusal of one npm/pnpm/yarn command (no guard needed), or null. `npm`: deps-guard.mjs. */
-export function installLinkVerdict({ program, args, cwd, npm }) {
-  if (npm.classifyInstall(program, args).kind === 'pass') return null;
-  const linked = npm.linkedNodeModulesOf(program, args, cwd);
-  if (!linked) return null;
-  return { tool: program, code: 'DEPS_THROUGH_LINK', command: `${program} ${args.join(' ')}`.slice(0, 200),
-    reason: `${linked.nodeModules} is a link to ${linked.target ?? 'another tree'}: ${program} would empty that live node_modules`,
-    remedy: 'node_modules here is a link to another checkout: unlink it first (cmd /c rmdir) and install for real' };
-}
-
-export async function installVerdict({ program, args, cwd, guard, deps }) {
-  const { classifyInstall, peerLeasedJobs } = deps.npm;
-  const kind = classifyInstall(program, args).kind;
-  if (kind === 'pass') return null;
-  const command = `${program} ${args.join(' ')}`.slice(0, 200);
-  const linked = installLinkVerdict({ program, args, cwd, npm: deps.npm });
-  if (linked) return linked;
-  if (kind !== 'clean-install' || !guard?.ledgerRepo) return null;
-  let peers;
-  try { peers = await peerLeasedJobs({ ledgerRepo: guard.ledgerRepo, workflowId: guard.workflowId }); }
-  catch (e) { deps.say(`starci guard: could not read peer leases (${e?.message ?? e})`); return null; }
-  if (!peers.jobs.length) return null;
-  const names = peers.jobs.slice(0, 5).map((j) => `${j.jobId} (${j.workflowId})`).join(', ');
-  return { tool: 'npm', code: 'DEPS_DELETE_WHILE_PEER_LEASED', command,
-    reason: `${command} deletes node_modules while other workflows' jobs run checks from it: ${names}`,
-    remedy: 'use `npm install`, or report blocked environment naming the missing dependency' };
-}
-
-// The Kernel never reads Orca's mailbox itself: `orchestration check --ack` consumes deliveries before the ledger records
-// them, so it reads through `starci kernel messages` / `starci kernel questions` and the runtime's api drains (lane MAILC). Ops and
-// [Worker]s keep `check`: Orca's worker protocol has them read their own Run's deliveries (modules/host/orca/api.yaml
-// operationAgent), and no ledger record depends on those.
-export function kernelMailboxVerdict(program, args, guard) {
-  if (program !== 'orca' || guard?.role !== 'kernel') return null;
-  const words = args.filter((a) => !a.startsWith('-'));
-  if (words[0] !== 'orchestration' || words[1] !== 'check') return null;
-  return { code: 'KERNEL_ORCA_CHECK', command: ['orca', ...args].join(' ').slice(0, 200),
-    reason: 'the Kernel never runs orca orchestration check: its --ack consumes deliveries before the ledger records them',
-    remedy: 'read messages with `starci kernel messages --repo <repo> --workflow <id>` and questions with `starci kernel questions`; the runtime drains the mailbox' };
-}

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

@@ -1,63 +0,0 @@
-// kernel-seat.mjs — what a Kernel seat (a bound guard of role kernel) may run, from the `kernel` table of
-// modules/kernel/command-policy.yaml. The PreToolUse guard and the PATH shims evaluate it (command-policy.mjs policyVerdict): a
-// mutating verb is the runtime's, never the seat's. Refusals name the status and decision verbs without running them.
-import path from 'node:path';
-import { plainWords } from '../lib/menu-parts.mjs';
-import { redirectTargetsOf, refusal } from './rights.mjs';
-import { kernelMailboxVerdict } from './install-verdict.mjs';
-import { orcaSelfLifecycleAllowed } from './orca-self-lifecycle.mjs';
-
-const OPTION = /^--?([A-Za-z][\w-]*)(?:=.*)?$/;
-const flagsOf = (args) => new Set(args.map((value) => OPTION.exec(String(value))?.[1]).filter(Boolean));
-
-/** The first two non-option words of a starci call: its group and verb. */
-/** Whether the Kernel seat may run `starci <group> <verb>` with these option names: {allowed, reason?}. */
-function kernelSeatAllowsVerb(table, group, verb, flags = new Set()) {
-  if (!(table?.verbs?.[group] ?? []).includes(verb)) return { allowed: false, reason: `starci ${group} ${verb} is not a verb of the Kernel seat` };
-  const blocked = (table['read-flags']?.[verb] ?? []).find((flag) => flags.has(flag));
-  return blocked ? { allowed: false, reason: `starci ${group} ${verb} --${blocked} mutates the workflow` } : { allowed: true };
-}
-
-/**
- * The refusal of a call that redirects output into a file, or null. The Kernel writes no file: a redirection (> file, 2>file, >> file) leaves a stray in the workflow
- * tree it works in, which a later fail decision of that tree then has to recover from (live: a file named 0, left by a redirect, made every settle-fail of a job unrecoverable).
- * The null devices are not files; the status text is read with --field, never redirected.
- */
-function kernelRedirectVerdict({ command, cwd }) {
-  const targets = redirectTargetsOf(command, cwd);
-  if (!targets.length) return null;
-  const use = 'read with starci kernel status --field <name> or starci kernel logs; the call needs no file';
-  return refusal('KERNEL_NO_FILE_WRITE', command, `the Kernel seat writes no file: the redirection into ${path.basename(targets[0])} would leave a stray file in its workflow tree`, use, use);
-}
-
-/** The Kernel-seat verdicts of one shell call as a tool verdict, or null for any other role: today the no-file-write rule. */
-export const kernelSeatCallVerdict = ({ role, command, cwd }) => {
-  const v = role === 'lead' ? kernelRedirectVerdict({ command, cwd }) : null;
-  return v ? { tool: 'shell', ...v } : null;
-};
-
-const useOf = (table) => table.use ?? 'starci kernel decide';
-
-/** The refusal of a call a Kernel seat may not make, or null when the seat may run it. Programs other than starci are refused unless pure reads. */
-export function kernelSeatVerdict({ policy, program, args, text, guard = null, handle = null }) {
-  const table = policy?.kernel;
-  if (!table) return null;
-  // The seat is an Orca worker: its own heartbeat, ask and worker_done stay, and its mailbox stays the runtime's.
-  if (program === 'orca') {
-    const mailbox = kernelMailboxVerdict('orca', args, guard);
-    if (mailbox) return mailbox;
-    if (orcaSelfLifecycleAllowed({ role: 'lead', args, handle, policy })) return null;
-  }
-  if (program === 'starci') {
-    const [group, verb] = plainWords(args, 2);
-    const verdict = kernelSeatAllowsVerb(table, group, verb, flagsOf(args));
-    if (verdict.allowed) return null;
-    const use = useOf(table);
-    return refusal('KERNEL_USE_DECIDE', text, `${verdict.reason}: the runtime runs it, and the Kernel answers the items of its menu`, use, use);
-  }
-  const reads = new Set((policy.read ?? []).map(String));
-  const denied = new Set((table['deny-programs'] ?? []).map(String));
-  if (reads.has(program) && !denied.has(program)) return null;
-  const use = useOf(table);
-  return refusal('KERNEL_STARCI_ONLY', text, `the Kernel seat runs starci verbs and pure reads: ${program} is neither`, use, use);
-}