@starci/hfs 4.8.0 → 4.9.1

package/runtime/scripts/guards/command-policy.mjs

@@ -1,342 +0,0 @@
-// command-policy.mjs - the shared R223 command-policy evaluator.
-//
-// Both enforcement entries call policyVerdict with the object loaded from modules/kernel/command-policy.yaml:
-// command-guard.mjs for PreToolUse hosts, and shimDecision for the PATH wrappers installed in every Orca worker terminal.
-// A wrapper calls `await shimDecision({ program: 'git', args: process.argv.slice(2) })`; on a verdict it writes
-// shimRefusalLines(verdict) to stderr and exits 2, otherwise it execs the real tool. A missing or unreadable policy fails
-// open, because the guard never takes the shell away on its own fault.
-import fs from 'node:fs';
-import path from 'node:path';
-import { parseYaml } from '../../engine/yaml.mjs';
-import { slash } from '../lib/path-key.mjs';
-import { SKILL_ROOT } from './guards-root.mjs';
-import { boundGuard, boundSeat, gitListFormRead, gitSubOf, nodeWholeSuite, pushTargets, refusal as baseRefusal, rightsRoleOf } from './rights.mjs';
-import { refusalLines } from './refusals.mjs';
-import { supervisorSeatVerdict } from './supervisor-seat.mjs';
-import { opStarciVerdict } from './op-starci.mjs';
-import { kernelMailboxVerdict } from './install-verdict.mjs';
-import { orcaAddressedOption, orcaSelfLifecycleAllowed } from './orca-self-lifecycle.mjs';
-import { criticCommandVerdict } from './critic-reach.mjs';
-import { rolesContract } from '../machine/roles-contract.mjs';
-import { kernelSeatVerdict } from './kernel-seat.mjs';
-
-const policyCache = new Map();
-const compiledCache = new WeakMap();
-const toSet = (value) => new Set(Array.isArray(value) ? value.map(String) : []);
-const programName = (value) => path.basename(slash(value)).toLowerCase().replace(/\.(?:exe|cmd|bat|ps1)$/, '');
-// These utilities have no state-changing form. Keeping this tiny compiled subset beside the evaluator lets the hook avoid
-// filesystem/YAML work for its hottest path; the complete admission table remains command-policy.yaml and is tested through
-// policyVerdict. Programs with even one writing option belong to guarded-read and are deliberately absent here.
-const INTRINSIC_READ = new Set(['ls', 'dir', 'cat', 'type', 'head', 'tail', 'wc', 'uniq', 'cut', 'tr', 'diff', 'cmp', 'comm', 'rg', 'grep', 'egrep', 'fgrep',
-  'pwd', 'which', 'where', 'whoami', 'hostname', 'stat', 'file', 'realpath', 'readlink', 'dirname', 'basename', 'date', 'true', 'false', 'test', '[', 'expr',
-  'seq', 'md5sum', 'sha1sum', 'sha256sum', 'shasum', 'cksum', 'od', 'xxd', 'hexdump', 'jq', 'yq', 'column', 'nl', 'rev', 'tac', 'fold', 'fmt', 'join', 'paste']);
-
-/** True only for a program whose every form is intrinsically read-only. */
-// A PowerShell drive path like env: lists the whole environment (ls env:, dir env:, cat env:): never the hot path, the ENV_DUMP rule judges it.
-export const intrinsicPolicyRead = (command) => INTRINSIC_READ.has(programName(command?.program)) && !(command?.args ?? []).some((a) => /env:/i.test(String(a)));
-
-/** Load and parse the command policy once per runtime root. An unreadable or invalid file is cached as policy null. */
-export function loadCommandPolicy({ root = SKILL_ROOT, read = (file) => fs.readFileSync(file, 'utf8') } = {}) {
-  const key = path.resolve(root);
-  if (policyCache.has(key)) return policyCache.get(key);
-  let policy = null;
-  try {
-    const value = parseYaml(String(read(path.join(key, 'modules', 'kernel', 'command-policy.yaml'))));
-    if (value && typeof value === 'object' && !Array.isArray(value)) policy = value;
-  } catch { /* fail open */ }
-  policyCache.set(key, policy);
-  return policy;
-}
-
-const compile = (policy) => {
-  if (!policy || typeof policy !== 'object') return null;
-  if (compiledCache.has(policy)) return compiledCache.get(policy);
-  let backupRef = null;
-  try { backupRef = new RegExp(String(policy.roles?.['backup-ref'] ?? '')); } catch { /* invalid policy fails closed nowhere */ }
-  const value = {
-    bound: toSet(policy.roles?.bound), nodeTest: toSet(policy.roles?.['node-test']), suiteOps: toSet(policy.roles?.['suite-ops']),
-    backupRoles: toSet(policy.roles?.['backup-roles']), backupRef,
-    runtime: toSet(policy.runtime), nodeScripts: Array.isArray(policy['node-scripts']) ? policy['node-scripts'].map((file) => slash(file)) : [],
-    read: toSet(policy.read), scopedWrite: toSet(policy['scoped-write']), npmPrograms: toSet(policy.npm?.programs), npmRead: toSet(policy.npm?.read),
-    gitRead: toSet(policy.git?.read), gitListForms: toSet(policy.git?.['list-forms']), orcaRead: toSet(policy.orca?.read), orcaGroups: toSet(policy.orca?.['groups-read']),
-  };
-  compiledCache.set(policy, value);
-  return value;
-};
-
-const refusal = (code, command, reason, use) => baseRefusal(code, command, reason, use, use);
-const textOf = ({ program, args, word }) => [word ?? program, ...args].map(String).join(' ').trim();
-const useOf = (entry, fallback) => typeof entry?.use === 'string' && entry.use ? entry.use : fallback;
-const RIGHTS_CODES = new Set(['RIGHTS_ROLE_DENIED', 'RIGHTS_GIT_PUSH', 'RIGHTS_GIT_TAG', 'RIGHTS_GIT_COMMIT', 'RIGHTS_GIT_SYNC', 'RIGHTS_NPM_PUBLISH', 'RIGHTS_NPM_CI_UNLOCKED',
-  'RIGHTS_SUITE_RUN', 'RIGHTS_RELEASE_CUT', 'RIGHTS_RAW_TOOL']);
-/** The code a table entry names, when it is one of the R223 codes (a typo in the table never invents a code). */
-const codeOf = (entry, fallback) => (RIGHTS_CODES.has(entry?.code) ? entry.code : fallback);
-const genericUse = 'use the starci verb of the action (modules/cli/commands) or ask the owner';
-const raw = (role, text, use = genericUse, what = 'raw tool command') => refusal('RIGHTS_RAW_TOOL', text, `the ${role} role does not run this ${what} directly because side effects go through a starci verb`, use);
-
-/** A headless-call verb (policy.calls) or a capability verb (policy.renders) refuses every bound role but the ops the table names. */
-const callVerdict = ({ role, program, args, guard, policy, text }) => {
-  if (program !== 'starci') return null;
-  const words = args.filter((value) => !value.startsWith('-'));
-  const call = [...Object.values(policy.calls ?? {}), ...Object.values(policy.renders ?? {})].find((entry) => words[0] === entry.verb?.[0] && words[1] === entry.verb?.[1]);
-  if (!call || (role === 'op' && toSet(call.ops).has(String(guard?.op ?? '')))) return null;
-  return refusal('RIGHTS_ROLE_DENIED', text, `${guard?.op ?? role} does not run starci ${call.verb.join(' ')}: only ${[...toSet(call.ops)].join(', ')} call it`, useOf(call, genericUse));
-};
-
-const RELEASE_SCRIPTS = new Set(['release:cut', 'release:publish']);
-const releaseCall = (program, args, policy) => {
-  if (program === 'starci' && args[0] === 'release' && toSet(policy.release?.verbs).has(String(args[1] ?? ''))) return true;
-  if (program === 'node' && args.some((value) => /(?:^|[\\/])release-(?:cut|publish)\.mjs$/i.test(String(value)))) return true;
-  return toSet(policy.npm?.programs).has(program) && args.some((value, index) => RELEASE_SCRIPTS.has(String(value)) && ['run', 'run-script'].includes(String(args[index - 1] ?? '')));
-};
-
-const PM_VALUE_FLAGS = new Set(['--prefix', '--cwd', '-C', '--dir', '--workspace', '-w', '--registry', '--tag', '--filter']);
-const packageWords = (args) => {
-  const words = [];
-  for (let i = 0; i < args.length; i += 1) {
-    const value = String(args[i]);
-    if (value === '--') break;
-    if (value.startsWith('-')) {
-      const name = value.split('=', 1)[0];
-      if (!value.includes('=') && PM_VALUE_FLAGS.has(name)) i += 1;
-      continue;
-    }
-    words.push(value);
-  }
-  return words;
-};
-const afterDashDash = (args) => { const at = args.indexOf('--'); return at < 0 ? [] : args.slice(at + 1).map(String).filter((value) => !value.startsWith('-')); };
-const cleanInstall = (word) => ['ci', 'clean-install', 'install-clean', 'cit', 'install-ci-test'].includes(word);
-const suiteScript = (words) => ['test', 't'].includes(words[0]) || (['run', 'run-script'].includes(words[0]) && words[1] === 'test');
-const publishScript = (words) => ['run', 'run-script'].includes(words[0]) && /^(?:release:)?publish.*$/.test(words[1] ?? '');
-
-const nodeValueFlags = 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']);
-const nodeOperands = (args) => {
-  const out = [];
-  for (let i = 0; i < args.length; i += 1) {
-    const value = String(args[i]);
-    if (nodeValueFlags.has(value)) { i += 1; continue; }
-    if (!value.startsWith('-')) out.push(value);
-  }
-  return out;
-};
-const nodeEntry = (args, entries) => {
-  const script = nodeOperands(args)[0];
-  if (!script) return false;
-  const normalized = slash(script);
-  return entries.some((entry) => normalized === entry || normalized.endsWith(`/${entry}`));
-};
-const hasOption = (args, ...names) => args.some((value) => names.some((name) => value === name || (name.startsWith('--') && String(value).startsWith(`${name}=`)) || (name.length === 2 && name.startsWith('-') && String(value).startsWith(name))));
-
-const nestedProgram = (program, args) => {
-  if (!['npx', 'bunx', 'corepack'].includes(program)) return null;
-  const list = args.map(String);
-  let i = 0;
-  while (i < list.length && list[i].startsWith('-')) {
-    if (['-p', '--package'].includes(list[i].split('=', 1)[0]) && !list[i].includes('=')) i += 1;
-    i += 1;
-  }
-  return list[i] ? { program: programName(list[i]), args: list.slice(i + 1), word: list[i] } : null;
-};
-
-const forbiddenOption = (args, options) => args.some((value) => options.some((option) => {
-  const arg = String(value), flag = String(option);
-  if (!flag.startsWith('-')) return arg === flag;
-  if (flag.startsWith('--')) return arg === flag || arg.startsWith(`${flag}=`);
-  return arg === flag || (flag.length === 2 && arg.startsWith(flag));
-}));
-
-const gitPolicyVerdict = ({ role, args, p, policy, text }) => {
-  const { sub, rest } = gitSubOf(args);
-  if (!sub || p.gitRead.has(sub)) return null;
-  if (p.gitListForms.has(sub) && gitListFormRead(sub, rest)) return null;
-  if (sub === 'push') {
-    const targets = pushTargets(rest), mayBackup = p.backupRoles.has(role);
-    if (mayBackup && p.backupRef && !targets.broad && targets.refs.length && targets.refs.every((ref) => p.backupRef.test(ref))) return null;
-  }
-  const denied = policy.git?.deny?.[sub];
-  const fallbackUse = useOf(policy.git?.deny?.merge, 'starci git sync');
-  const use = useOf(denied, fallbackUse);
-  const code = codeOf(denied, 'RIGHTS_GIT_SYNC');
-  return refusal(code, text, `the ${role} role does not run git ${sub} directly because git writes and synchronization go through the starci git verbs`, use);
-};
-
-const npmReadAllowed = (args, words, verb, p) => p.npmRead.has(verb)
-  || (verb === 'config' && p.npmRead.has(`config ${words[1] ?? ''}`))
-  || (verb === 'pack' && args.includes('--dry-run'));
-
-const npmPublishVerdict = (role, text, policy) => {
-  const denied = policy.npm?.deny?.publish, use = useOf(denied, 'starci release publish');
-  return refusal(codeOf(denied, 'RIGHTS_NPM_PUBLISH'), text, `the ${role} role does not publish a package because packages are published once per release from the release commit`, use);
-};
-
-const npmSuiteVerdict = ({ role, args, p, policy, guard, text, words, verb }) => {
-  if (!suiteScript(words) || afterDashDash(args).length) return undefined;
-  if (p.suiteOps.has(String(guard?.op ?? ''))) return null;
-  const use = useOf(policy.npm?.deny?.[verb === 'run' || verb === 'run-script' ? verb : 'test'], 'starci gate unit --root <app>');
-  return refusal('RIGHTS_SUITE_RUN', text, `the ${role} role does not run a whole suite because full suites run in CI or the requested verify ops`, use);
-};
-
-const npmCleanInstallVerdict = ({ args, policy, handle, lockOwner, text, verb }) => {
-  if (!cleanInstall(verb)) return undefined;
-  if (args.includes('--dry-run')) return null;
-  let owner = null;
-  try { owner = lockOwner(); } catch { /* an unreadable lock proves no ownership */ }
-  const owns = (held) => !held.stale && (held.role === 'release' || (handle && held.handle === handle));
-  if (owner && owns(owner)) return null;
-  const denied = policy.npm?.deny?.ci, use = useOf(denied, 'the runtime installs dependencies under the host lock');
-  return refusal(codeOf(denied, 'RIGHTS_NPM_CI_UNLOCKED'), text, 'this clean install rewrites node_modules without the caller holding the host lock', use);
-};
-
-const npmPolicyVerdict = ({ role, args, p, policy, guard, handle, lockOwner, text }) => {
-  const words = packageWords(args), verb = words[0] ?? '';
-  if (args.length === 1 && ['-v', '--version'].includes(args[0])) return null;
-  if (npmReadAllowed(args, words, verb, p)) return null;
-  if (publishScript(words)) return npmPublishVerdict(role, text, policy);
-  const suite = npmSuiteVerdict({ role, args, p, policy, guard, text, words, verb });
-  if (suite !== undefined) return suite;
-  const install = npmCleanInstallVerdict({ args, policy, handle, lockOwner, text, verb });
-  if (install !== undefined) return install;
-  if (suiteScript(words) && afterDashDash(args).length) return null;
-  const denied = policy.npm?.deny?.[verb] ?? policy.npm?.deny?.run;
-  const use = useOf(denied, 'starci gate run --root <app>');
-  return refusal(codeOf(denied, 'RIGHTS_RAW_TOOL'), text, `the ${role} role does not run this package-manager action directly because scripts and dependency changes go through a starci verb`, use);
-};
-
-const SERVES_APP = /(?:^|[\\/])next(?:\.js)?$/;
-
-const nodePolicyVerdict = ({ role, args, p, policy, guard, text }) => {
-  if (hasOption(args, '--eval', '-e', '--print', '-p')) return raw(role, text, 'use the starci verb of the action or check a file with node --check', 'inline Node.js program');
-  if (args.length === 1 && ['--version', '-v'].includes(args[0])) return null;
-  if (hasOption(args, '--check', '-c')) return null;
-  if (args.includes('--test')) {
-    if (nodeWholeSuite(args)) {
-      if (p.suiteOps.has(String(guard?.op ?? ''))) return null;
-      return refusal('RIGHTS_SUITE_RUN', text, `the ${role} role does not run a whole suite because full suites run in CI or the requested verify ops`, 'starci runtime verify in the runtime (the check, package clean-test and scaffold e2e), or one explicit spec file');
-    }
-    const targets = nodeOperands(args).filter((value) => value !== 'test');
-    if (p.nodeTest.has(role) && targets.length && targets.every((value) => /\.(?:spec|test)\.[cm]?js$/i.test(value))) return null;
-    return raw(role, text, 'starci gate unit --root <app> (the op gate selects the specs of the change)', 'raw test runner');
-  }
-  if (nodeOperands(args).some((value) => SERVES_APP.test(slash(value)))) return raw(role, text, useOf(policy['raw-tools']?.next, genericUse), 'app server start');
-  return raw(role, text, genericUse, 'Node.js script');
-};
-
-const orcaPolicyVerdict = ({ role, args, p, policy, guard, handle, text }) => {
-  const [group, verb] = args;
-  const mailbox = kernelMailboxVerdict('orca', args, guard);
-  if (mailbox) return mailbox;
-  const addressed = orcaAddressedOption({ role, args, policy });
-  if (addressed) return refusal('OP_REPORTS_TO_KERNEL', text, `an Op reports only to its Kernel: ${addressed} addresses another recipient`, rolesContract().chain.opRefusal.use);
-  if (orcaSelfLifecycleAllowed({ role, args, handle, policy })) return null;
-  // Implicit current-terminal checks retain their existing read admission; an explicit target must prove self.
-  const targetedCheck = group === 'orchestration' && verb === 'check' && hasOption(args.slice(2), '--terminal');
-  if (!targetedCheck && p.orcaGroups.has(group) && p.orcaRead.has(verb)) return null;
-  return raw(role, text, useOf(policy.orca, genericUse), 'Orca mutation');
-};
-
-const specificCommandVerdict = (context) => {
-  const { role, program, args, p, policy, guard, handle, lockOwner, text } = context;
-  if (program === 'git') return gitPolicyVerdict({ role, args, p, policy, text });
-  if (p.npmPrograms.has(program)) return npmPolicyVerdict({ role, args, p, policy, guard, handle, lockOwner, text });
-  if (program === 'node') return nodePolicyVerdict({ role, args, p, policy, guard, text });
-  if (program === 'orca') return orcaPolicyVerdict({ role, args, p, policy, guard, handle, text });
-  return undefined;
-};
-
-const generalCommandVerdict = ({ role, program, args, p, policy, text }) => {
-  const rawTool = policy['raw-tools']?.[program];
-  if (rawTool) return raw(role, text, useOf(rawTool, genericUse));
-  const guarded = policy['guarded-read']?.[program];
-  if (Array.isArray(guarded)) {
-    const use = `use the read-only form of ${program}`;
-    if (forbiddenOption(args, guarded)) return raw(role, text, use, `${program} write form`);
-    const required = policy['require-flag']?.[program];
-    if (Array.isArray(required) && !required.some((flag) => args.includes(String(flag)))) return raw(role, text, use, `${program} emitting form`);
-    return null;
-  }
-  if (p.read.has(program) || p.scopedWrite.has(program)) return null;
-  return raw(role, text);
-};
-
-/** The Critic's verdict: the Orca self-lifecycle verbs, else only what critic-reach.mjs lets it read and write. */
-function criticPolicyVerdict({ program, args, command, guard, handle, policy }) {
-  if (program === 'orca' && orcaSelfLifecycleAllowed({ role: 'critic', args, handle, policy })) return null;
-  return criticCommandVerdict({ program, args, cwd: command.cwd, guard, critic: policy.critic, text: textOf({ ...command, program, args }) });
-}
-
-/**
- * The verdict of the seat tables (Supervisor, Op, Kernel). Undefined when the general policy decides: a Kernel seat is decided here in
- * full (null passes), a Supervisor or Op only when its table refuses.
- */
-function seatVerdict({ role, guard, handle, policy, program, args, text }) {
-  if (guard?.role === 'kernel') return kernelSeatVerdict({ policy, program, args, text, guard, handle });
-  if (role === 'supervisor') return supervisorSeatVerdict({ policy, program, args, text }) ?? undefined;
-  if (role === 'op') return opStarciVerdict({ policy, program, args, text }) ?? undefined;
-  return undefined;
-}
-
-/**
- * Decide one normalized command for a bound role. Returns null to pass or the shared refusal shape.
- * `lockOwner` is a synchronous reader and is called only for a clean install.
- */
-export function policyVerdict({ role, command, guard = null, handle = null, lockOwner = () => null, policy }) {
-  const p = compile(policy);
-  if (!p || !role || role === 'release' || !p.bound.has(role)) return null;
-  let { program, args = [] } = command;
-  program = programName(program);
-  args = args.map(String);
-  if (role === 'critic') return criticPolicyVerdict({ program, args, command, guard, handle, policy });
-  const nested = nestedProgram(program, args);
-  if (nested) return policyVerdict({ role, command: { ...nested, cwd: command.cwd }, guard, handle, lockOwner, policy });
-  const text = textOf({ ...command, program, args });
-
-  if (releaseCall(program, args, policy)) {
-    const use = useOf(policy.release, 'starci release cut');
-    return refusal('RIGHTS_RELEASE_CUT', text, `the ${role} role does not cut or publish a release because tagging a release and publishing packages are owner-approved`, use);
-  }
-  const seat = seatVerdict({ role, guard, handle, policy, program, args, text });
-  if (seat !== undefined) return seat;
-  const call = callVerdict({ role, program, args, guard, policy, text });
-  if (call) return call;
-  if (p.runtime.has(program)) return null;
-  if (program === 'node' && nodeEntry(args, p.nodeScripts)) return null;
-
-  const specific = specificCommandVerdict({ role, program, args, p, policy, guard, handle, lockOwner, text });
-  if (specific !== undefined) return specific;
-  return generalCommandVerdict({ role, program, args, p, policy, text });
-}
-
-const needsLock = (program, args, env) => {
-  if (String(env?.STARCI_ROLE ?? '').toLowerCase() === 'release') return true;
-  const nested = nestedProgram(program, args);
-  if (nested) return needsLock(nested.program, nested.args, env);
-  return ['npm', 'pnpm', 'yarn', 'bun'].includes(program) && cleanInstall(packageWords(args)[0] ?? '');
-};
-
-/** Decide one direct PATH-shim invocation without importing the PreToolUse parser or guard. */
-export async function shimDecision({ program, args = [], cwd = process.cwd(), env = process.env, root = SKILL_ROOT } = {}) {
-  const normalized = programName(program), argv = args.map(String), handle = env?.ORCA_TERMINAL_HANDLE ?? null;
-  let lockOwner = () => null;
-  if (needsLock(normalized, argv, env)) {
-    try {
-      const lock = await import('../machine/host-lock.mjs');
-      lockOwner = () => { try { return lock.hostLockOwner({ env }); } catch { return null; } };
-    } catch { /* a missing lock reader proves neither release nor install ownership */ }
-  }
-  const guard = boundGuard(handle, { root, env });
-  const seat = boundSeat(handle, { root, env });
-  const role = rightsRoleOf({ guard, seat, env, lockOwner: String(env?.STARCI_ROLE ?? '').toLowerCase() === 'release' ? lockOwner() : null });
-  const policy = role && role !== 'release' ? loadCommandPolicy({ root }) : null;
-  const verdict = policyVerdict({ role, command: { program: normalized, args: argv, cwd, word: normalized }, guard, handle, lockOwner, policy });
-  return { role, verdict };
-}
-
-/** Format a shim refusal exactly like the PreToolUse hook. */
-export function shimRefusalLines(verdict) {
-  const command = String(verdict?.command ?? '').trim();
-  const at = command.indexOf(' ');
-  const tool = at < 0 ? command || 'shell' : command.slice(0, at);
-  const tail = at < 0 ? '' : command.slice(at + 1);
-  return refusalLines(tool, { ...verdict, command: tail });
-}

package/runtime/scripts/guards/critic-reach.mjs

@@ -1,82 +0,0 @@
-// critic-reach.mjs — what the Critic (rights role `critic`) may reach, enforced and not described. Its job guard names one
-// directory (`reach.dir`: the product files and the rubric handed to it) and one file (`reach.verdictFile`: its answer). The
-// shell may run only the read-only programs modules/kernel/command-policy.yaml `critic.read` lists, on paths inside that
-// directory, and the writers it lists only onto the verdict file; the Orca self-lifecycle verbs (worker_done, escalation) stay.
-// The Edit and Write tools reach the verdict file only; on Claude and Devin the Read, Grep and Glob tools reach the directory only.
-// Every other command, path or tool is refused with RIGHTS_CRITIC_REACH.
-import path from 'node:path';
-import { pathKey, sameOrUnder, slash } from '../lib/path-key.mjs';
-import { refusal } from './rights.mjs';
-
-const CRITIC_REACH_CODE = 'RIGHTS_CRITIC_REACH';
-const USE = 'read only the files in your own directory and write only the verdict file there; report with worker_done or an escalation';
-const OPTION_PATH = /^-(?:path|filepath|literalpath)$/i;
-// Programs whose operands are text, not paths: only an expansion could smuggle a path into them.
-const TEXT_PROGRAMS = new Set(['echo', 'printf', 'write-output', 'write-host']);
-
-const deny = (text, reason) => refusal(CRITIC_REACH_CODE, text, reason, USE, USE);
-const inside = (file, dir) => sameOrUnder(pathKey(path.resolve(file)), pathKey(path.resolve(dir)));
-const same = (a, b) => pathKey(path.resolve(a)) === pathKey(path.resolve(b));
-/** Readable by the Critic: its directory, and the one Task file the runtime wrote for it outside that directory (reach.taskFile). */
-const readable = (file, guard) => inside(file, guard.reach.dir) || (typeof guard.reach.taskFile === 'string' && same(file, guard.reach.taskFile));
-const expands = (value, program) => /[$`]/.test(value) || (!TEXT_PROGRAMS.has(program) && (/%/.test(value) || String(value).startsWith('~')));
-
-/** The verdict file of the guard, absolute. */
-const verdictPathOf = (guard) => path.resolve(guard.reach.dir, guard.reach.verdictFile);
-
-/** The operands that name paths in `args`: the value of `--opt=value`, every non-option word. */
-function pathWords(args) {
-  return args.map(String).flatMap((word) => {
-    if (!word.startsWith('-')) return [word];
-    const at = word.indexOf('=');
-    return at < 0 ? [] : [word.slice(at + 1)];
-  });
-}
-
-/** The words of a read program outside the critic's directory, or an expansion no check can resolve. */
-function readReach({ program, args, cwd, guard }) {
-  const dir = guard.reach.dir;
-  if (!inside(cwd, dir)) return cwd;
-  const words = TEXT_PROGRAMS.has(program) ? args.map(String).filter((word) => expands(word, program)) : pathWords(args);
-  return words.find((word) => expands(word, program) || (!TEXT_PROGRAMS.has(program) && !readable(path.resolve(cwd, slash(word)), guard))) ?? null;
-}
-
-/** The target path a writer program names: the -Path/-FilePath value, else its first non-option word. */
-function writeTarget(args) {
-  const list = args.map(String);
-  const named = list.findIndex((word) => OPTION_PATH.test(word));
-  if (named >= 0) return list[named + 1] ?? null;
-  return list.find((word) => !word.startsWith('-')) ?? null;
-}
-
-/**
- * The refusal of one shell command of a Critic, or null. `critic` is the policy section (read[], write[]), `text` the
- * command as written. Orca lifecycle verbs are judged before this by the caller.
- */
-export function criticCommandVerdict({ program, args, cwd, guard, critic, text }) {
-  const dir = guard?.reach?.dir;
-  if (!dir) return deny(text, 'the critic guard names no directory, so nothing is reachable');
-  const base = cwd ?? dir;
-  if ((critic?.write ?? []).includes(program)) {
-    const target = writeTarget(args);
-    return target && !expands(target, program) && same(path.resolve(base, target), verdictPathOf(guard)) ? null
-      : deny(text, `the critic writes only ${guard.reach.verdictFile} in its directory`);
-  }
-  if (!(critic?.read ?? []).includes(program)) return deny(text, `the critic runs only read-only commands (${program} is not one of them)`);
-  const outside = readReach({ program, args: args.map(String), cwd: base, guard });
-  return outside === null ? null : deny(text, `the critic reads only inside its own directory (${outside} is not)`);
-}
-
-/** The refusal of a write to `filePath` (a file tool or a shell redirection target) by a Critic, or null. */
-export function criticWriteVerdict({ filePath, guard, tool = 'shell' }) {
-  if (!guard?.reach?.dir) return deny(filePath, 'the critic guard names no directory, so nothing is writable');
-  return same(filePath, verdictPathOf(guard)) ? null : deny(filePath, `the critic writes only ${guard.reach.verdictFile} (${tool} targeted another path)`);
-}
-
-/** The refusal of a read tool call (Read, Grep, Glob) of a Critic, or null: `paths` are the absolute paths the call reaches. */
-export function criticReadVerdict({ paths, guard, tool }) {
-  const dir = guard?.reach?.dir;
-  if (!dir) return deny(tool, 'the critic guard names no directory, so nothing is readable');
-  const outside = paths.find((one) => !readable(one, guard));
-  return outside ? deny(`${tool} ${outside}`, `the critic reads only inside its own directory (${tool} reached ${outside})`) : null;
-}

package/runtime/scripts/guards/deps-guard.mjs

@@ -1,150 +0,0 @@
-// deps-guard.mjs — dependency installs in a checkout several workflows share.
-//
-// A shared checkout's node_modules was deleted and recreated while a
-// workflow's cut ran jest and tsc in the same checkout; one of its workers saw
-// "node_modules disappeared mid-run" and every check in that window had to be
-// re-run. The rule (modules/kernel/api.yaml conventions.sharedCheckout):
-//  - a command that deletes node_modules (npm ci and its aliases) is refused
-//    while a job of ANOTHER workflow of the same ledger is leased, because that
-//    job's checks read node_modules right now;
-//  - an install-family command of npm, pnpm or yarn through a linked node_modules is always refused, with or without
-//    a guard file: it empties the live tree the link points to (node-modules-link-wipe, contract change
-//    install-through-link).
-// scripts/guards/command-guard.mjs (a PreToolUse hook) applies it to an agent's shell command before it runs.
-import fs from 'node:fs';
-import path from 'node:path';
-
-/** The package managers whose install family rewrites node_modules. */
-export const PACKAGE_MANAGERS = Object.freeze(['npm', 'pnpm', 'yarn']);
-const NPM_INSTALL = new Set(['install', 'i', 'in', 'ins', 'inst', 'insta', 'instal', 'isnt', 'isnta', 'isntal', 'isntall', 'add',
-  'uninstall', 'un', 'unlink', 'remove', 'rm', 'r', 'update', 'up', 'upgrade', 'udpate', 'prune', 'dedupe', 'ddp', 'rebuild', 'rb', 'link', 'ln',
-  'it', 'install-test']);
-const NPM_CLEAN_INSTALL = new Set(['ci', 'clean-install', 'ic', 'install-clean', 'isntall-clean', 'cit', 'install-ci-test', 'clean-install-test', 'sit']);
-const PNPM_INSTALL = new Set(['install', 'i', 'add', 'remove', 'rm', 'uninstall', 'un', 'update', 'up', 'upgrade', 'prune', 'rebuild', 'rb',
-  'link', 'ln', 'unlink', 'dedupe', 'import', 'install-test', 'it']);
-const YARN_INSTALL = new Set(['install', 'add', 'remove', 'upgrade', 'up', 'upgrade-interactive', 'dedupe', 'link', 'unlink', 'import']);
-// Options that consume the next word, per manager.
-const VALUE_OPTIONS = {
-  npm: new Set(['--prefix', '-C', '--dir', '--workspace', '-w', '--userconfig', '--cache', '--registry', '--loglevel', '--tag', '--omit', '--include', '--install-strategy']),
-  pnpm: new Set(['-C', '--dir', '--prefix', '--filter', '-F', '--workspace-dir', '--store-dir', '--virtual-store-dir', '--reporter', '--loglevel', '--registry', '--config']),
-  yarn: new Set(['--cwd', '--modules-folder', '--cache-folder', '--mutex', '--network-timeout', '--registry', '--global-folder', '--link-folder']),
-};
-// The options that name the package root an install works in.
-const ROOT_OPTIONS = ['--prefix', '-C', '--dir', '--cwd'];
-
-const optionValue = (args, names) => {
-  for (let i = 0; i < args.length; i += 1) {
-    const a = args[i];
-    if (names.includes(a) && args[i + 1] != null) return args[i + 1];
-    const eq = names.find((n) => n.startsWith('--') && a.startsWith(`${n}=`));
-    if (eq) return a.slice(eq.length + 1);
-  }
-  return null;
-};
-
-/** The package root an install of `argv` works in: --prefix / -C / --dir / --cwd, else the nearest package.json above `cwd`. */
-export function packageRootOf(argv, cwd = process.cwd()) {
-  const given = optionValue(argv.map(String), ROOT_OPTIONS);
-  if (given) return path.resolve(cwd, given);
-  for (let d = path.resolve(cwd); ; d = path.dirname(d)) {
-    if (fs.existsSync(path.join(d, 'package.json'))) return d;
-    if (path.dirname(d) === d) return null;
-  }
-}
-
-// `nm` when it is a link (a junction or symlink, or a directory whose real path is not its own place), else null.
-function linkAt(nm) {
-  let st; try { st = fs.lstatSync(nm); } catch { return null; }
-  let linked = st.isSymbolicLink();
-  if (!linked && st.isDirectory()) {
-    try { linked = path.resolve(fs.realpathSync.native(nm)).toLowerCase() !== path.join(fs.realpathSync.native(path.dirname(nm)), path.basename(nm)).toLowerCase(); }
-    catch { linked = true; }
-  }
-  if (!linked) return null;
-  let target = null; try { target = fs.realpathSync.native(nm); } catch { /* dangling */ }
-  return { nodeModules: nm, target };
-}
-
-// The workspace root above `root` (a package.json with "workspaces", or a pnpm-workspace.yaml), whose node_modules a
-// workspace install also writes; null when there is none.
-function workspaceRootAbove(root) {
-  for (let d = path.dirname(root); path.dirname(d) !== d; d = path.dirname(d)) {
-    if (fs.existsSync(path.join(d, 'pnpm-workspace.yaml'))) return d;
-    try { if (JSON.parse(fs.readFileSync(path.join(d, 'package.json'), 'utf8'))?.workspaces) return d; } catch { /* none or unreadable */ }
-  }
-  return null;
-}
-
-/**
- * The node_modules an install of `program argv` in `cwd` would rewrite that is a LINK (junction/symlink), or null. npm
- * reifies through a linked node_modules and empties its target: proven 2026-09-28 (npm 11.6, "Removing non-directory
- * node_modules" left the junction's target empty), and the wipes kept coming (the runtime's live .claude/node_modules;
- * 2026-10-01 a lane's `npm ci` emptied main's packages/grammar/node_modules through its junction). Checked in order:
- * the package root's node_modules (yarn --modules-folder when given), every node_modules the root itself sits inside,
- * and the workspace root's node_modules. A node_modules that does not exist yet is no link. Never throws.
- */
-export function linkedNodeModulesOf(program, argv, cwd = process.cwd()) {
-  try {
-    const args = argv.map(String);
-    const root = packageRootOf(args, cwd);
-    if (!root) return null;
-    const modulesFolder = program === 'yarn' ? optionValue(args, ['--modules-folder']) : null;
-    const candidates = [modulesFolder ? path.resolve(root, modulesFolder) : path.join(root, 'node_modules')];
-    for (let d = root; path.dirname(d) !== d; d = path.dirname(d)) if (path.basename(d).toLowerCase() === 'node_modules') candidates.push(d);
-    const ws = workspaceRootAbove(root);
-    if (ws) candidates.push(path.join(ws, 'node_modules'));
-    for (const nm of candidates) { const hit = linkAt(nm); if (hit) return hit; }
-    return null;
-  } catch { return null; }
-}
-
-/** The install kind for a package manager's subcommand (npm/pnpm/yarn membership tables). */
-const installKindOf = (program, sub) => {
-  if (program === 'npm') {
-    if (NPM_CLEAN_INSTALL.has(sub)) return 'clean-install';
-    return sub && NPM_INSTALL.has(sub) ? 'install' : 'pass';
-  }
-  if (program === 'pnpm') return sub && PNPM_INSTALL.has(sub) ? 'install' : 'pass';
-  // yarn with no subcommand installs; any other word runs a script.
-  return !sub || YARN_INSTALL.has(sub) ? 'install' : 'pass';
-};
-
-/** classifyInstall(program, argv) -> {kind: 'pass'|'install'|'clean-install', sub}: whether the command rewrites node_modules. */
-export function classifyInstall(program, argv) {
-  if (!PACKAGE_MANAGERS.includes(program)) return { kind: 'pass', sub: null };
-  const args = argv.map(String);
-  const valued = VALUE_OPTIONS[program];
-  let sub = null;
-  for (let i = 0; i < args.length; i += 1) {
-    const a = args[i];
-    if (valued.has(a)) { i += 1; continue; }
-    if (a.startsWith('-')) continue;
-    sub = a;
-    break;
-  }
-  const global = args.some((a) => a === '-g' || a === '--global' || a === '--location=global') || (program === 'yarn' && sub === 'global');
-  const dry = args.some((a) => a === '--dry-run' || a === '--lockfile-only');
-  if (global || dry) return { kind: 'pass', sub };
-  return { kind: installKindOf(program, sub), sub };
-}
-
-/** Jobs of OTHER workflows of this ledger that hold a lease right now (read-only). */
-export async function peerLeasedJobs({ ledgerRepo, workflowId, env = process.env, now = Date.now() }) {
-  if (!ledgerRepo) return { known: false, jobs: [] };
-  const { openLedgerReader, ledgerFileFor } = await import('../../engine/db/ledger.mjs');
-  // The repo's runtime ledger is the one file ledgerFileFor resolves (machine.ledgers names it); there is no other place to look.
-  let file = null;
-  try {
-    const resolved = ledgerFileFor(ledgerRepo, { env });
-    if (fs.existsSync(resolved)) file = resolved;
-  } catch { file = null; }
-  if (!file) return { known: false, jobs: [] };
-  const db = openLedgerReader(file);
-  try {
-    db.exec('PRAGMA busy_timeout=5000');
-    const rows = db.prepare(`SELECT j.job_id, j.workflow_id, j.op_id, j.status FROM jobs j
-      WHERE j.kind<>'kernel' AND j.status IN ('leased','running','answering') AND j.workflow_id<>?`).all(workflowId ?? '');
-    return { known: true, jobs: rows.map((r) => ({ jobId: r.job_id, workflowId: r.workflow_id, opId: r.op_id, status: r.status })) };
-  } finally { db.close(); }
-}
-