@starci/hfs 4.7.31 → 4.7.33

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

@@ -0,0 +1,343 @@
+// 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-io.mjs

@@ -0,0 +1,76 @@
+import { HOOK_INPUT_LIMITS } from '../lib/hook-limits.mjs';
+export { HOOK_INPUT_LIMITS } from '../lib/hook-limits.mjs';
+
+/** Keep fail-open and fail-closed input diagnostics on one stderr line, including parser errors containing input. */
+export const hookErrorMessage = (error) => String(error?.message ?? error).replace(/[\r\n\u2028\u2029]+/g, ' ');
+
+/** Flush hook output before explicit exit; false means the output deadline elapsed before the write completed. */
+export const writeHookOutput = (stream, text) => new Promise((resolve, reject) => {
+  let settled = false;
+  const onError = (error) => done(error);
+  const done = (error) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    // A Writable reports callback failure before emitting its error event. Keep the listener through that turn.
+    if (error) setImmediate(() => stream.removeListener?.('error', onError));
+    else stream.removeListener?.('error', onError);
+    if (error) reject(error);
+    else resolve(true);
+  };
+  const timer = setTimeout(() => {
+    settled = true;
+    stream.removeListener?.('error', onError);
+    resolve(false);
+  }, HOOK_INPUT_LIMITS.outputTimeoutMs);
+  stream.once?.('error', onError);
+  try { stream.write(text, done); }
+  catch (error) { done(error); }
+});
+
+/**
+ * Consume one EOF-delimited hook payload within a wall-clock deadline and byte budget. The stream belongs to this
+ * one-shot hook: every outcome releases its input handle and listeners. Callers choose their existing failure policy.
+ */
+export const readInput = (stream, { timeoutMs = HOOK_INPUT_LIMITS.minInputWindowMs, maxBytes = HOOK_INPUT_LIMITS.maxBytes } = {}) => new Promise((resolve, reject) => {
+  const chunks = [];
+  const deadline = performance.now() + timeoutMs;
+  const deadlineError = () => Object.assign(new Error(`hook stdin deadline exceeded (${timeoutMs} ms)`), { kind: 'deadline' });
+  let bytes = 0;
+  let settled = false;
+  let closeCheck;
+  const finish = (error) => {
+    if (settled) return;
+    if (!error && performance.now() >= deadline) error = deadlineError();
+    settled = true;
+    clearTimeout(timer);
+    clearImmediate(closeCheck);
+    stream.removeListener('data', onData);
+    stream.removeListener('end', onEnd);
+    stream.removeListener('error', onError);
+    stream.removeListener('close', onClose);
+    stream.pause();
+    stream.unref?.();
+    stream.destroy();
+    if (error) reject(error);
+    else resolve(Buffer.concat(chunks, bytes).toString('utf8'));
+  };
+  const onData = (chunk) => {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    bytes += buffer.length;
+    if (bytes > maxBytes) finish(Object.assign(new Error(`hook stdin exceeds ${maxBytes} bytes; split the tool input`), { kind: 'too-large' }));
+    else chunks.push(buffer);
+  };
+  const onEnd = () => finish();
+  const onError = (error) => finish(error);
+  const onClose = () => finish(stream.errored ?? new Error('hook stdin closed before EOF'));
+  // Keep the timer referenced so an idle pipe still reaches the caller's bound-session refusal.
+  const timer = setTimeout(() => finish(deadlineError()), timeoutMs);
+  stream.on('data', onData);
+  stream.once('end', onEnd);
+  stream.once('error', onError);
+  stream.once('close', onClose);
+  // destroy(error) marks a stream closed before its queued error event; let that event reach our listener first.
+  if (stream.destroyed) closeCheck = setImmediate(onClose);
+  else if (stream.readableEnded) onEnd();
+});

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

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,41 @@
+// 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

@@ -0,0 +1,63 @@
+// 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);
+}

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

@@ -0,0 +1,74 @@
+// The refusals of launches outside the runtime (raw terminal create, headless agent CLIs, an agent's own Orca worktree, a test
+// world in a uat op), split out of command-guard.mjs.
+// An agent launch outside Orca is invisible to it: no liveness, no stop, no release, and a dead worker sits unnoticed
+// (owner rule 2026-10-01). Every agent and every worker terminal starts through `orca orchestration worker-start`.
+const WORKER_START = '`orca orchestration worker-start --agent <provider> [--model <id>] --worktree <selector> --spec "<task>" --task-title "<title>"`, supervised with worker-show / worker-read / worker-stop / worker-release';
+// The first non-flag word of `args`, skipping the values of `valued` flags.
+const subcommandOf = (args, valued) => {
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === '--') return args[i + 1] ?? null;
+    if (a.startsWith('-')) {
+      if (valued.test(a)) { i += 1; }
+      continue;
+    }
+    return a;
+  }
+  return null;
+};
+const CODEX_VALUED = /^(?:-m|--model|-c|--config|-C|--cd|-s|--sandbox|-a|--ask-for-approval|-p|--profile|-i|--image|--enable|--disable|--add-dir|--local-provider)$/;
+const printFlag = (args, flags) => {
+  const options = args.includes('--') ? args.slice(0, args.indexOf('--')) : args;
+  return options.find((a) => flags.includes(a)) ?? null;
+};
+// The one headless call the runtime makes for an op (tiers.yaml calls.imagegen; owner decision 2026-10-07).
+const IMAGE_CALL = ' An image is generated with `starci work imagegen` (interface.draw, interface.asset and brand.decide), never with a hand-run codex exec.';
+const launchRefusal = (program, args, how) => ({ command: [program, ...args].join(' ').slice(0, 200),
+  reason: `${how} outside Orca's supervision: no liveness, no stop or release, and a dead worker goes unnoticed (owner rule 2026-10-01)`,
+  remedy: `launch every agent and worker through ${WORKER_START}${program === 'codex' ? IMAGE_CALL : ''}` });
+// The workspace and runtime rules (workspace.manage, runtime.operate; OPS2 3.1): an agent never creates or removes an Orca
+// worktree itself - the runtime's worktree API (scripts/machine/worktree-orca.mjs createOrcaWorktree / removeOrcaWorktree,
+// releaseWorkflowWorktree) runs the link check first and keeps the registry and its cap (git worktree writes are
+// git-policy.mjs WORKTREE_NOT_OPS).
+const ORCA_WORKTREE_WRITES = new Set(['create', 'add', 'rm', 'remove', 'delete', 'prune', 'move']);
+// The uat rule (uat.verify, uat.assisted.*; OPS2 3.1): a walk runs on the app's real dev stack, never a test world.
+const TEST_WORLD_RUNNER = /(?:^|[\\/])test-world-run\.mjs$/;
+const testWorldOf = (program, args) => {
+  if (program === 'node' && args.some((a) => TEST_WORLD_RUNNER.test(a))) return 'test-world-run.mjs';
+  if (program !== 'starci') return null;
+  const words = args.filter((a) => !a.startsWith('-'));
+  return words[0] === 'gate' && words[1] === 'test-world' ? 'starci gate test-world' : null;
+};
+const headlessHow = (program, args) => {
+  if (program === 'codex') {
+    const sub = subcommandOf(args, CODEX_VALUED);
+    return sub === 'exec' || sub === 'e' ? `codex ${sub} runs a headless Codex agent` : null;
+  }
+  if (program === 'claude' || program === 'cursor-agent' || program === 'devin') {
+    const flag = printFlag(args, ['-p', '--print']);
+    return flag ? `${program} ${flag} runs a headless agent` : null;
+  }
+  if (program === 'gemini') {
+    const flag = printFlag(args, ['-p', '--prompt']);
+    return flag ? `gemini ${flag} runs a headless agent` : null;
+  }
+  if (program === 'opencode' && subcommandOf(args, /^(?:-m|--model|--agent|--log-level)$/) === 'run') return 'opencode run runs a headless agent';
+  return null;
+};
+export const launchVerdict = (program, args, guard = null) => {
+  if (program === 'orca') {
+    const words = args.filter((a) => !a.startsWith('-'));
+    if (words[0] === 'terminal' && words[1] === 'create') return { code: 'RAW_TERMINAL_CREATE', ...launchRefusal(program, args, 'a raw terminal create starts a terminal outside worker-start') };
+    if (words[0] === 'worktree' && ORCA_WORKTREE_WRITES.has(words[1])) return { code: 'AGENT_ORCA_WORKTREE', command: [program, ...args].join(' ').slice(0, 200),
+      reason: `orca worktree ${words[1]}: an agent never creates or removes a worktree - a removal without the runtime's link check follows node_modules junctions into the live tree (inc-c8fbf76aa499; Orca itself walks junctions), and a tree outside the registry escapes its cap and GC`,
+      remedy: 'inspect with `starci machine worktrees counts`; remove clean merged lane worktrees with `starci machine worktrees-clean`; worktrees are created and removed only by the runtime worktree API (scripts/machine/worktree-orca.mjs createOrcaWorktree / removeOrcaWorktree, scripts/kernel/workflow-worktree.mjs releaseWorkflowWorktree); report a need you cannot meet as blocked environment' };
+    return null;
+  }
+  const op = String(guard?.op ?? '');
+  const testWorld = op.startsWith('uat.') ? testWorldOf(program, args) : null;
+  if (testWorld) return { code: 'UAT_TEST_WORLD', command: [program, ...args].join(' ').slice(0, 200),
+    reason: `${op} walks the app's real dev stack: a test world (${testWorld}) fakes what the walk must prove`,
+    remedy: 'bring up the dev stack the app-root .starcistacks/<env> declares with its own start commands, check it with env-health, and walk it; a stack that will not come up is reported blocked environment' };
+  const how = headlessHow(program, args);
+  return how ? { code: 'AGENT_HEADLESS_LAUNCH', ...launchRefusal(program, args, how) } : null;
+};

package/runtime/scripts/guards/op-starci.mjs

@@ -0,0 +1,16 @@
+// op-starci.mjs — the starci groups an Op never runs, from the `op` table of modules/kernel/command-policy.yaml. An Op's starci calls are
+// its work: the capability verbs for servers, renders, image generation and tests, the checks, and its report to its Kernel. The control
+// plane (the Supervisor, the reconciler, workflow start and routing, Debug) belongs to the controllers, the Kernel and the Supervisor.
+import { refusal } from './rights.mjs';
+
+/** The first non-option word of a starci call: its group. */
+const groupOf = (args) => String(args.find((word) => !String(word).startsWith('-')) ?? '');
+
+/** The refusal of a starci call of a group an Op never runs, or null. */
+export function opStarciVerdict({ policy, program, args, text }) {
+  const table = policy?.op;
+  if (!table || program !== 'starci') return null;
+  const group = groupOf(args);
+  if (!(table['deny-groups'] ?? []).includes(group)) return null;
+  return refusal('RIGHTS_OP_CONTROL_PLANE', text, `starci ${group} is the control plane: an Op runs the capability verbs of its work and reports to its Kernel`, table.use, table.use);
+}