@starci/hfs 4.8.0 → 4.9.1

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

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

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

package/runtime/scripts/guards/op-write-scope.mjs

@@ -1,27 +0,0 @@
-// op-write-scope.mjs — where an Op may write: its attempt's owned paths and the runtime temp directory, nothing else. The owned paths
-// are the absolute paths its job guard records at launch (scripts/guards/hook-install.mjs writeJobGuard); a file the Op needs outside
-// them is reported as owed, never written. The PreToolUse guard applies it to Edit, Write and the shell write targets alike
-// (rights.mjs fileWriteVerdict).
-import os from 'node:os';
-import { tempRoot } from '../../engine/temp-root.mjs';
-import { pathKey, sameOrUnder } from '../lib/path-key.mjs';
-
-const inside = (file, dirs) => dirs.some((dir) => sameOrUnder(pathKey(file), pathKey(dir)));
-
-/** Directories every Op may write: the runtime temp root and the OS temp directory. */
-const scratchDirs = (env) => [tempRoot({ env }), os.tmpdir(), env?.TEMP, env?.TMP, env?.TMPDIR].filter(Boolean);
-
-/**
- * The refusal fields {code, reason, remedy} for an Op write to `file`, or null when it may write there. An Op with no workflow
- * worktree in its guard (a guard without scope information) is not confined.
- */
-export function opWriteScopeRefusal({ file, guard, env = process.env }) {
-  if (!guard?.workflowWorktree) return null;
-  if (inside(file, guard.owned ?? [])) return null;
-  if (!inside(file, [guard.workflowWorktree]) && inside(file, scratchDirs(env))) return null;
-  return {
-    code: 'RIGHTS_OP_OUTSIDE_OWNED',
-    reason: 'an Op writes only inside the paths its attempt owns and the runtime temp directory; this file is outside them',
-    remedy: 'put scratch files in the runtime temp directory; a change the work needs outside your owned paths is reported as owed in your report (starci kernel report) for your Kernel to cut',
-  };
-}

package/runtime/scripts/guards/orca-self-lifecycle.mjs

@@ -1,39 +0,0 @@
-// Own-seat lifecycle admission for R223; the policy table owns the verbs, roles, types and options.
-const optionsOf = (args, entry) => {
-  const values = new Set(entry.values ?? []), flags = new Set(entry.flags ?? []);
-  const options = new Map();
-  for (let i = 0; i < args.length; i += 1) {
-    const word = args[i], at = word.indexOf('=');
-    const name = at < 0 ? word : word.slice(0, at);
-    if (options.has(name)) return null; // Ambiguous identities/types never qualify, even if repeated identically.
-    if (flags.has(name) && at < 0) { options.set(name, true); continue; }
-    if (!values.has(name)) return null; // No positionals, terminators or unknown identity-changing options.
-    const value = at < 0 ? args[++i] : word.slice(at + 1);
-    if (value == null || (at < 0 && value.startsWith('--'))) return null;
-    options.set(name, value);
-  }
-  return options;
-};
-
-/** True only for a policy-listed lifecycle call whose explicit identity equals the trusted caller handle. */
-export function orcaSelfLifecycleAllowed({ role, args, handle, policy }) {
-  const lifecycle = policy.orca?.['self-lifecycle'];
-  if (!handle || args[0] !== lifecycle?.group || !lifecycle.roles?.includes(role)) return false;
-  const entry = lifecycle.verbs?.[args[1]];
-  if (!entry || (entry.roles && !entry.roles.includes(role))) return false;
-  const options = optionsOf(args.slice(2), entry);
-  if (!options || options.get(entry.identity) !== handle) return false;
-  const types = entry.typesByRole?.[role] ?? entry.types;
-  return !types || types.includes(options.get('--type'));
-}
-
-/**
- * The option a role may not use on a policy-listed lifecycle call ('refuse-for' in the policy entry), or null: an Op that names
- * a recipient (--to) or another Run (--run) addresses someone other than its own Kernel.
- */
-export function orcaAddressedOption({ role, args, policy }) {
-  const lifecycle = policy.orca?.['self-lifecycle'];
-  if (args[0] !== lifecycle?.group) return null;
-  const refused = lifecycle.verbs?.[args[1]]?.['refuse-for']?.[role] ?? [];
-  return args.slice(2).map((word) => String(word).split('=', 1)[0]).find((name) => refused.includes(name)) ?? null;
-}

package/runtime/scripts/guards/process-kill-verdict.mjs

@@ -1,106 +0,0 @@
-// process-kill-verdict.mjs - the command guard's process rules: a kill that selects processes by image name or pattern
-// (PROCESS_KILL_BY_NAME), and a kill whose targets come from a process QUERY - Get-CimInstance Win32_Process, Get-Process,
-// ps | grep, pgrep - which ends other lanes' processes by their command line, parent or path (a lane killed other lanes'
-// node test runs that way, 2026-10-02). An agent ends only a PID it started and recorded: `taskkill /PID <pid>`,
-// `kill <pid>`, `Stop-Process -Id <pid>`, or a variable assigned from its own Start-Process or `cmd & pid=$!`.
-// Reads (Get-CimInstance listing, `ps aux | grep node`) and text that only mentions these commands pass: the query rule
-// judges parsed commands, so an echo, a commit message or a heredoc never reaches it.
-// A kill whose variable was set in an EARLIER shell call (`$x = ...` in one call, `Stop-Process -Id $x` or `kill $pid` in the
-// next) is not judged, by design. The guard sees one call's text and keeps no state: a Bash or PowerShell tool call is a
-// fresh shell, so a variable never survives into the next call - what carries a PID across calls is a file, an environment
-// value or the model's own memory of a literal, none of which the guard can trace to its source. Refusing every non-literal
-// target would refuse `Stop-Process -Id (Get-Content run.pid)` and `kill $(cat run.pid)`, the PID file the remedy itself
-// tells an agent to keep; a query stage is the one evidence of a foreign target, and it is judged only where it is visible,
-// in the same call. Tracking provenance across calls would need a ledger of the PIDs an agent started, which no hook can
-// fill soundly; the by-name rule above and the same-call query rule are the sound part.
-import { assignedCommand } from './assigned-command.mjs';
-const TASKKILL_SELECTOR = /^(?:\/\/?|-)(?:im|fi)$/i;
-const NAME_PARAMETER = /^-(?:n|na|nam|name|processname)(?::.*)?$/i;
-const POWERSHELL_STOP = new Set(['stop-process', 'spps']);
-const REMEDY = 'end only a PID you started yourself, the one you recorded when you started it (taskkill /PID <pid>, kill <pid>, Stop-Process -Id <pid>), never one found by a query; a process you did not start is reported, never killed';
-
-/** The refusal for one command that kills by name or pattern, or null. */
-export const nameKillVerdict = (program, args) => {
-  let how = null;
-  if (program === 'taskkill' && args.some((a) => TASKKILL_SELECTOR.test(a))) how = 'taskkill by image name or filter (/IM, /FI)';
-  else if (program === 'pkill' || program === 'killall') how = `${program}, which selects processes by name or pattern`;
-  // PowerShell's kill alias takes the full -Name/-ProcessName; a POSIX `kill -n <signal>` is not a name.
-  else if ((POWERSHELL_STOP.has(program) && args.some((a) => NAME_PARAMETER.test(a))) || (program === 'kill' && args.some((a) => /^-(?:name|processname)(?::.*)?$/i.test(a)))) how = 'Stop-Process -Name';
-  else if (program === 'wmic' && args.some((a) => /^process$/i.test(a)) && args.some((a) => /\bname\s*=|^name$/i.test(a))) how = 'wmic process selected by name';
-  // wmic process where <filter> delete | call terminate, unless the filter is one literal ProcessId.
-  else if (program === 'wmic' && args.some((a) => /^process$/i.test(a)) && args.some((a) => /\b(?:delete|terminate)\b/i.test(a)) && !args.some((a) => /(?<![a-z])(?:process)?id\s*=\s*\d+\s*$/i.test(a))) how = 'wmic process ... delete|terminate selected by a filter';
-  if (!how) return null;
-  return { code: 'PROCESS_KILL_BY_NAME', command: [program, ...args].join(' ').slice(0, 200),
-    reason: `${how} ends every process it matches on the machine, including Orca and other agents' workers (a lane's taskkill of node.exe restarted Orca, 2026-10-01)`,
-    remedy: REMEDY };
-};
-
-const QUERY_PROGRAMS = new Set(['get-process', 'gps', 'ps', 'pgrep', 'pidof', 'tasklist']);
-const CIM_PROGRAMS = new Set(['get-ciminstance', 'gcim', 'get-wmiobject', 'gwmi']);
-const isQuery = (c) => QUERY_PROGRAMS.has(c.program) || (CIM_PROGRAMS.has(c.program) && c.args.some((a) => /win32_process/i.test(a))) || (c.program === 'wmic' && c.args.some((a) => /^process$/i.test(a)));
-const LITERAL = /^\d+(?:,\d+)*$/;
-const OPTION_VALUE = /^-(?:ea|erroraction|wa|warningaction|ev|errorvariable|ov|outvariable|s|n|signal)$/i;
-const TARGET_OPTION = /^-(?:id|inputobject)$/i;
-
-// The targets one kill command names ([] when it names none: its targets come down a pipe or an xargs).
-function targetsOf(args) {
-  const out = [];
-  for (let i = 0; i < args.length; i += 1) {
-    const a = args[i];
-    const inline = /^-(?:id|inputobject):(.*)$/i.exec(a);
-    if (inline) out.push(inline[1]);
-    else if (TARGET_OPTION.test(a)) { if (i + 1 < args.length) { out.push(args[i + 1]); } i += 1; }
-    else if (OPTION_VALUE.test(a)) i += 1;
-    else if (!a.startsWith('-')) out.push(a);
-  }
-  return out;
-}
-
-// 'kill' or 'Stop-Process' when its named targets are not all literal PIDs, else null.
-const killTargetHow = (program, targets) => {
-  if (targets.length && targets.every((t) => LITERAL.test(t))) return null;
-  return program === 'kill' ? 'kill' : 'Stop-Process';
-};
-
-// A kill sink whose target is not one literal PID: how it is spelled, or null.
-function sinkOf(c) {
-  const { program, args } = c;
-  if (POWERSHELL_STOP.has(program) || program === 'kill') {
-    if (args.some((a) => /^-l$/.test(a))) return null;
-    return killTargetHow(program, targetsOf(args));
-  }
-  if (program === 'taskkill') {
-    const at = args.findIndex((a) => /^(?:\/\/?|-)pid$/i.test(a));
-    return at >= 0 && !LITERAL.test(args[at + 1] ?? '') ? 'taskkill /PID' : null;
-  }
-  if (program === 'invoke-cimmethod' && args.some((a) => /^terminate$/i.test(a))) return 'Invoke-CimMethod Terminate';
-  if (/\.(?:terminate|kill)$/.test(program)) return `.${program.split('.').pop()}()`;
-  return null;
-}
-
-// The variables a kill names in the raw text, once per kill: `Stop-Process -Id $p.Id`, `$p | Stop-Process`, `$p.Kill()`,
-// `kill $pid`, `kill $!`. A kill target that is no plain variable (a $(...), a pipe from a query) names none.
-const ROOTS = [
-  new RegExp([
-    String.raw`\b(?:stop-process|spps|kill|taskkill)\b`,
-    String.raw`(?:\s+(?:-(?:id|inputobject)(?::|(?=\s))|(?:\/\/?|-)pid(?=\s)|-\w+(?=\s+\S*\$)))*`,
-    String.raw`\s*"?\$(\w+|!)`,
-  ].join(''), 'gi'),
-  /\$(\w+)\s*\|\s*(?:stop-process|spps)\b/gi,
-  /\$(\w+)\.(?:terminate|kill)\s*\(/gi,
-];
-const OWN_START = (root) => new RegExp(root === '!' ? '$^' : String.raw`(?:\$${root}\s*=\s*\(?\s*(?:start-process|start-job|\[[\w.]+\]::start)\b|(?<![\w$])${root}=\$!)`, 'i');
-
-/** The refusal for a kill whose targets come from a process query, or null. `commands` are the parsed commands, `text` the raw call. */
-export function queryKillVerdict(parsed, text) {
-  const commands = parsed.map(assignedCommand);
-  if (!commands.some(isQuery)) return null;
-  const sinks = commands.map((c) => [c, sinkOf(c)]).filter(([, how]) => how);
-  if (!sinks.length) return null;
-  const roots = ROOTS.flatMap((re) => [...String(text).matchAll(re)].map((m) => m[1]));
-  if (roots.length >= sinks.length && roots.every((r) => r === '!' || OWN_START(r).test(text))) return null;
-  const [c, how] = sinks[0];
-  return { code: 'PROCESS_KILL_BY_NAME', command: [c.program, ...c.args].join(' ').slice(0, 200),
-    reason: `${how} on targets found by a process query (Get-CimInstance Win32_Process, Get-Process, ps, pgrep) ends other lanes' and agents' processes selected by command line, name, path or parent - not a process you started`,
-    remedy: REMEDY };
-}

package/runtime/scripts/guards/protected-zone.mjs

@@ -1,56 +0,0 @@
-// protected-zone.mjs - the reader of modules/kernel/protected-zone.yaml, the ONE declaration of the protected zone
-// (rule R224 RIGHTS_PROTECTED_ZONE), and the question the command guard asks of it: is this path inside a runtime checkout,
-// and does it fall in a zone or on a protected catalog entry?
-//
-// A runtime checkout is found by rights.mjs runtimeRootOf (any directory tree holding knowledge/hfs/runtime-slots.yaml: the live
-// .claude, a lane worktree of it, a staging checkout), so every worktree of the runtime is judged by the same declaration
-// without asking git. Pure fs and one YAML read, loaded only when a role that can be
-// refused writes a file (the guard's common path never loads it).
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { parseYaml } from '../../engine/yaml.mjs';
-import { globExpression } from '../lib/glob.mjs';
-import { pathKey, posixPath } from '../lib/path-key.mjs';
-import { runtimeRootOf } from './rights.mjs';
-
-const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-const PROTECTED_ZONE_FILE = 'modules/kernel/protected-zone.yaml';
-
-const cache = new Map();
-
-/** {zones: [{id, why, matchers}], catalog: [{file, ids, codes}]} parsed from the declaration of `root`, or an empty zone when unreadable. */
-function loadProtectedZone({ root = SKILL_ROOT, read = (file) => fs.readFileSync(file, 'utf8') } = {}) {
-  const key = pathKey(root);
-  if (cache.has(key)) return cache.get(key);
-  let parsed = null;
-  try { parsed = parseYaml(read(path.join(root, PROTECTED_ZONE_FILE))); } catch { parsed = null; }
-  const zone = {
-    zones: (parsed?.zones ?? []).map((z) => ({ id: String(z.id), why: String(z.why ?? ''), matchers: (z.paths ?? []).map((p) => globExpression(String(p))) })),
-    catalog: (parsed?.catalogEntries ?? []).map((c) => ({ file: posixPath(String(c.file)), ids: (c.ids ?? []).map(String), codes: (c.codes ?? []).map(String) })),
-  };
-  cache.set(key, zone);
-  return zone;
-}
-
-/**
- * Where `file` stands against the zone: {runtimeRoot, rel, zone: {id, why} | null, catalog: entry | null}. runtimeRoot is
- * null when the path is outside every runtime checkout (then nothing here applies).
- */
-export function zoneOfPath(file, { declaration = loadProtectedZone(), exists = fs.existsSync } = {}) {
-  const runtimeRoot = runtimeRootOf(file, { exists });
-  if (!runtimeRoot) return { runtimeRoot: null, rel: null, zone: null, catalog: null };
-  const rel = posixPath(path.relative(runtimeRoot, path.resolve(file)));
-  const zone = declaration.zones.find((z) => z.matchers.some((m) => m.test(rel))) ?? null;
-  const catalog = declaration.catalog.find((c) => c.file === rel) ?? null;
-  return { runtimeRoot, rel, zone: zone ? { id: zone.id, why: zone.why } : null, catalog };
-}
-
-/** The ids or codes of a catalog entry that `text` names (a rule id as a whole token, a code as a substring), or []. */
-export function catalogNames(entry, text) {
-  const body = String(text ?? '');
-  const hits = [];
-  for (const id of entry.ids) if (new RegExp(`(?:^|[^A-Za-z0-9])${id}(?![0-9])`).test(body)) hits.push(id);
-  for (const code of entry.codes) if (body.includes(code)) hits.push(code);
-  return hits;
-}

package/runtime/scripts/guards/refusals.mjs

@@ -1,27 +0,0 @@
-// refusals.mjs — how an op guard refuses: the lines the agent reads and the <guards root>/refusals.jsonl record.
-// Shared by the agent command guard (command-guard.mjs, a PreToolUse hook) and the history hook's commit check
-// (verify-commit.mjs).
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { guardsRoot } from './guards-root.mjs';
-
-const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-
-/** The refusal as the agent reads it: what was refused and why, the remedy, and the shared-checkout rule. */
-export function refusalLines(tool, verdict) {
-  return [
-    `starci guard: refused \`${tool} ${verdict.command ?? ''}\` [${verdict.code}] — ${verdict.reason}.`,
-    ...(verdict.remedy ? [`starci guard: instead: ${verdict.remedy}.`] : []),
-    'starci guard: this checkout is shared with other workflows (modules/ops/_common.yaml "Evidence, completion and commits"). Report a real need in your report; never work around this guard.',
-  ];
-}
-
-/** Append one refusal to <guards root>/refusals.jsonl; the refusal stands without its log line. */
-export function logRefusal(entry, { root = skillRoot } = {}) {
-  try {
-    const dir = guardsRoot(root);
-    fs.mkdirSync(dir, { recursive: true });
-    fs.appendFileSync(path.join(dir, 'refusals.jsonl'), `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`);
-  } catch { /* the refusal stands without its log line */ }
-}

package/runtime/scripts/guards/rights.mjs

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