@starci/hfs 4.7.47 → 4.9.0

package/runtime/scripts/machine/home.mjs

@@ -1,216 +0,0 @@
-// home.mjs — the Supervisor's durable state, in machine.sqlite (engine/db/machine.mjs, DBTREE.sql B1; decision Q3).
-//
-// There is no supervisor ledger and no supervisor home directory: every part is a machine.sqlite row.
-// Where each part lives:
-//   seat      seats row 'supervisor' (role supervisor): state booting while a launcher holds the startup reservation
-//             (detail_json.expiresAt), live once spawned; terminal_handle/agent/model/pid; detail_json {token, value}
-//   enabled   sup_signals scope 'supervisor-enabled' key 'main' {enabled, by, at}
-//   jobs      sup_jobs (runtime.fix [Worker] jobs), sup_leases (file leases), sup_attempts, sup_reports
-//   audit     sup_events (the digest-chained audit trail; kinds as before: supervisor-*, worker-*, owed-*, ...)
-//   learning  sup_learning; owed items and their acks sup_owed; owner rulings sup_owner_rulings; messages sup_messages
-//   logs      machine_logs actor 'supervisor' (supervisorLog; the Supervisor writes no text logs)
-// Product ledgers are only ever read from here.
-import os from 'node:os';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { DEFAULT_OWNER_LANGUAGE, loadConfig } from '../../engine/config.mjs';
-import { LOCAL_ROOT_ENV, machineLog, readMachine, starciLocalRoot, withMachine } from '../../engine/db/machine.mjs';
-import { headTime } from '../api/git/head-time.mjs';
-import { readEnv } from '../lib/env.mjs';
-
-export const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-
-/**
- * The rev of the runtime this process runs: '<HEAD committer time, ms, 13 digits>:<short sha>' of the .claude checkout
- * (STARCI_RUNTIME_REV overrides), 'unknown' outside a checkout. The machine db never spawns git: a writer that stamps a
- * store row passes this in. Computed once per process.
- */
-let cachedRev = null;
-export function runtimeRevOf() {
-  if (cachedRev) return cachedRev;
-  if (readEnv('STARCI_RUNTIME_REV')) {
-    cachedRev = String(readEnv('STARCI_RUNTIME_REV'));
-    return cachedRev;
-  }
-  const head = headTime(SKILL_ROOT);
-  cachedRev = head ? `${String(head.time * 1000).padStart(13, '0')}:${head.sha}` : 'unknown';
-  return cachedRev;
-}
-export const SUPERVISOR_ID = 'main';
-/** The seats row of the one Supervisor seat. */
-export const SEAT_ID = 'supervisor';
-const ENABLED_SCOPE = 'supervisor-enabled';
-export const SUPERVISOR_TITLE = `[Supervisor] ${SUPERVISOR_ID}`;
-export const SUPERVISOR_SEAT = Object.freeze({ id: SUPERVISOR_ID, seatId: SEAT_ID, enabledScope: ENABLED_SCOPE,
-  eventPrefix: 'supervisor', title: SUPERVISOR_TITLE });
-export const WORKER_TITLE_PREFIX = '[Worker]';
-export const FIX_KIND = 'runtime.fix';
-export const STARTUP_RESERVATION_MS = 180_000;
-
-export const DEFAULTS = Object.freeze({
-  workers: Object.freeze({ base: 0, max: 0, hardMax: 10 }),
-  landGate: Object.freeze({ mode: 'shared', push: true }),
-  frozenMinutes: 10,
-  pollIntervalMs: 600_000,
-});
-
-// The land scratch trees live under the one lanes root (lanesRoot below), never on C: unless the owner puts it there. A [Worker]
-// staging checkout is an Orca worktree (workers.mjs createStaging): Orca places it, the job records where.
-
-/** The host-state sub-root `archive` defaults to: <starciLocalRoot>/archive, i.e. <runtime root>/.runtime/archive. */
-const stateRootChild = (name, env) => path.join(starciLocalRoot(env), name);
-/**
- * Lane worktrees are git worktrees, so their default stays OUT of the runtime's own checkout (and its .runtime): the per-user
- * profile directory (<LOCALAPPDATA>/StarCi/lanes, ~/.local/state/StarCi/lanes), or <STARCI_LOCAL_ROOT>/lanes when that seam is set.
- * The owner moves it with roots.lanes or STARCI_LANES_ROOT.
- */
-const lanesDefault = (env) => (readEnv(LOCAL_ROOT_ENV, env) ? stateRootChild('lanes', env)
-  : path.join(readEnv('LOCALAPPDATA', env) || path.join(os.homedir(), '.local', 'state'), 'StarCi', 'lanes'));
-/** The owner's relocation of a host root (config.yaml `roots.<key>`, validated by engine/config.mjs), or null. `config` is the owner config (default: loadConfig()). */
-const ownerRoot = (key, config) => {
-  try { return (config === undefined ? loadConfig() : config)?.roots?.[key] ?? null; } catch { return null; }
-};
-
-/**
- * The one lane-worktree root: env STARCI_LANES_ROOT (specs, a one-off run), then the owner config `roots.lanes`
- * (config.yaml, gitignored), else lanesDefault (outside the checkout). No host location is written in a tracked file.
- */
-export function lanesRoot({ env = process.env, config = undefined } = {}) {
-  return path.resolve(String(env?.STARCI_LANES_ROOT || ownerRoot('lanes', config) || lanesDefault(env)));
-}
-
-/** The one archive root (session files, blob retention, ledger backups): env STARCI_ARCHIVE_ROOT, then the owner config `roots.archive`, else <starciLocalRoot>/archive. */
-export function archiveRoot({ env = process.env, config = undefined } = {}) {
-  return path.resolve(String(env?.STARCI_ARCHIVE_ROOT || ownerRoot('archive', config) || stateRootChild('archive', env)));
-}
-
-export const landRoot = (env = process.env) => path.join(lanesRoot({ env }), 'land');
-
-/** fn(machine handle) over a writer, closed afterwards. */
-export const withSupervisor = (fn, { env = process.env } = {}) => withMachine(fn, { env });
-/** fn(machine handle) over a read-only handle; `fallback` when machine.sqlite does not exist or cannot be read. */
-export const readSupervisor = (fn, fallback = null, { env = process.env } = {}) => readMachine(fn, fallback, { env });
-
-/**
- * The `{env}`-bound reader of a supervisor-store projection `read`: `fresh` yields the fallback when the
- * store is absent (a thunk, so the value is never shared between calls).
- */
-export const supervisorRead = (read, fresh) => ({ env = process.env } = {}) => readSupervisor(read, fresh(), { env });
-
-/**
- * The seat: {token, value, at, expiresAt, pid, expired, starting} or null (no seat, or an empty one). `value` is what
- * the launcher wrote ({terminal, agent, model, ...} or {state:'starting', attempt}).
- */
-export function seatOf(m, now = Date.now(), profile = SUPERVISOR_SEAT) {
-  const row = m.seatOf(profile.seatId);
-  if (!row || row.state === 'empty') return null;
-  const detail = row.detail ?? {};
-  const expiresAt = detail.expiresAt ?? null;
-  const expired = expiresAt != null && expiresAt <= now;
-  const value = detail.value ?? {};
-  return { token: detail.token ?? null, value, at: row.booted_at ?? row.last_seen_at ?? null, expiresAt, pid: row.pid ?? null, expired, starting: value.state === 'starting' && !expired, state: row.state };
-}
-/** Write the seat (replacing it): a {state:'starting'} value is the startup reservation (state booting, with expiry). A new seat starts with no refused input: the run of failures belongs to the seat it replaced. */
-export function writeSeat(m, { token, value, expiresAt = null, now = Date.now(), profile = SUPERVISOR_SEAT }) {
-  const starting = value?.state === 'starting';
-  return m.upsertSeat({ seatId: profile.seatId, role: 'supervisor', state: starting ? 'booting' : 'live', parkedReason: null,
-    terminalHandle: value?.terminal ?? null, agent: value?.agent ?? null, model: value?.model ?? null, pid: process.pid,
-    bootedAt: now, lastSeenAt: now, inputFailuresConsecutive: 0, lastInputFailureAt: null, detailJson: { token, value, expiresAt } });
-}
-/** Empty the seat (only the holder of `token` when given). True when it was cleared. */
-export function clearSeat(m, { token = null, profile = SUPERVISOR_SEAT } = {}) {
-  const cur = seatOf(m, Date.now(), profile);
-  if (!cur || (token && cur.token !== token)) return false;
-  m.upsertSeat({ seatId: profile.seatId, role: 'supervisor', state: 'empty', terminalHandle: null, pid: null, detailJson: null });
-  return true;
-}
-
-/** Whether the owner enabled the seat: true / false, or null when never set. */
-export function enabledOf(m, profile = SUPERVISOR_SEAT) {
-  const row = m.supSignal(profile.enabledScope, profile.id);
-  return row ? row.value?.enabled === true : null;
-}
-export function setEnabled(m, enabled, { by = 'cli', now = Date.now(), profile = SUPERVISOR_SEAT } = {}) {
-  m.transaction(() => {
-    m.setSupSignal({ scope: profile.enabledScope, key: profile.id, value: { enabled, by, at: new Date(now).toISOString() } });
-    supervisorEvent(m, { entityId: profile.id, kind: `${profile.eventPrefix}-${enabled ? 'enabled' : 'disabled'}`, payload: { by }, now });
-  });
-}
-
-/** Native supervised seats retain their terminals until their owning launcher proves closure. */
-export function supervisedSeatHandles(m) {
-  return new Set(m.seats().filter(row => row.role === 'supervisor' && row.state !== 'empty')
-    .map(row => row.terminal_handle ?? row.detail?.value?.terminal).filter(Boolean));
-}
-
-/** Append one audit event (sup_events). */
-export function supervisorEvent(m, { entityType = 'supervisor', entityId = SUPERVISOR_ID, kind, payload = null, now = Date.now() }) {
-  return m.supEvent({ entityType, entityId, kind, payload, at: now });
-}
-/** The newest event of `kind` as {at, ...payload}, or null. */
-export function newestEvent(m, kind) {
-  const row = m.newestSupEvent(kind);
-  return row ? { at: row.created_at, ...row.payload } : null;
-}
-
-/**
- * Where the Supervisor role runs (config.yaml supervisor.mode, default 'chat'). Owner, 2026-09-25: "move the
- * supervisor back into chat so it stays persistent" - the role lives in the owner's desktop chat session again: it owns channel 'main'
- * (registers and drains it with no Orca terminal), runs the 10-minute tick itself and lands its Opus lanes through
- * land.mjs --lane. 'kernel' is the optional [Supervisor] Orca kernel (start-supervisor.mjs + supervisor-watchdog.mjs); in chat
- * mode nothing (resume-all, restart-all, /start, the watchdog) starts one. STARCI_SUPERVISOR_MODE overrides the
- * config (specs, a one-off CLI run).
- */
-const SUPERVISOR_MODES = Object.freeze(['chat', 'kernel']);
-export const DEFAULT_SUPERVISOR_MODE = 'chat';
-/** engine/config.mjs owns the owner-language default; home re-exports it so base (scripts/lib/i18n.mjs) never imports machine. */
-export { DEFAULT_OWNER_LANGUAGE };
-export const DEFAULT_AGENT = 'claude';
-export function supervisorMode({ env = process.env, config = undefined } = {}) {
-  const fromEnv = String(env?.STARCI_SUPERVISOR_MODE ?? '').trim();
-  if (SUPERVISOR_MODES.includes(fromEnv)) return fromEnv;
-  let cfg = config;
-  if (cfg === undefined) { try { cfg = loadConfig(); } catch { cfg = null; } }
-  const mode = cfg?.supervisor?.mode;
-  return SUPERVISOR_MODES.includes(mode) ? mode : DEFAULT_SUPERVISOR_MODE;
-}
-
-/**
- * config.yaml supervisor block with defaults: {mode, agent, model, effort, repos, pollIntervalMs, workers, landGate, frozenMinutes}.
- * `agent` and `model` are the owner's pin of the seat (an `only` bias over the supervisor tier chain); both are null when unpinned.
- */
-export function supervisorSettings({ config = undefined } = {}) {
-  let cfg = config;
-  if (cfg === undefined) cfg = loadConfig();
-  const sup = cfg?.supervisor ?? {};
-  const seat = sup.kernel ?? {};
-  const pick = (...values) => values.find((v) => typeof v === 'string' && v.trim())?.trim() ?? null;
-  return {
-    mode: SUPERVISOR_MODES.includes(sup.mode) ? sup.mode : DEFAULT_SUPERVISOR_MODE,
-    agent: pick(seat.agent),
-    model: pick(seat.model),
-    effort: pick(seat.effort, cfg?.effort),
-    repos: Array.isArray(sup.repos) ? sup.repos : [],
-    pollIntervalMs: Number.isInteger(sup.pollIntervalMs) ? sup.pollIntervalMs : DEFAULTS.pollIntervalMs,
-    workers: { base: Number.isInteger(sup.workers?.base) ? sup.workers.base : DEFAULTS.workers.base,
-      max: Math.min(DEFAULTS.workers.hardMax, Number.isInteger(sup.workers?.max) ? sup.workers.max : DEFAULTS.workers.max) },
-    landGate: { mode: sup.landGate?.mode === 'exclusive' ? 'exclusive' : DEFAULTS.landGate.mode, push: typeof sup.landGate?.push === 'boolean' ? sup.landGate.push : DEFAULTS.landGate.push },
-    // supervisor-watchdog.mjs: a busy seat frame with no turn progress for this long is frozen, not busy.
-    frozenMinutes: Number.isInteger(sup.frozenMinutes) && sup.frozenMinutes > 0 ? sup.frozenMinutes : DEFAULTS.frozenMinutes,
-    language: typeof cfg?.language === 'string' ? cfg.language : DEFAULT_OWNER_LANGUAGE,
-  };
-}
-
-/** The product repositories the supervisor watches and pushes: config supervisor.repos resolved against the source root. */
-export const productRepos = (settings = supervisorSettings(), { sourceRoot = path.dirname(SKILL_ROOT) } = {}) =>
-  settings.repos.map((repo) => path.resolve(sourceRoot, repo));
-
-/** A db-shaped adapter that answers wakeKernel's one signal read with `terminal` (scripts/kernel/wake-delivery.mjs wakeKernel). */
-export const terminalSignalDb = (terminal) => ({
-  prepare: () => ({ get: () => ({ value_json: JSON.stringify({ terminal }) }) }),
-});
-
-/** One Supervisor log line in machine_logs (actor supervisor, kind supervisor.<name>). Never throws. */
-export function supervisorLog(name, line, { env = process.env, now = new Date(), level = 'info', data = null } = {}) {
-  return machineLog({ actor: 'supervisor', kind: `supervisor.${name}`, msg: String(line), level, data, at: now.getTime() }, { env });
-}

package/runtime/scripts/machine/host-lock.mjs

@@ -1,184 +0,0 @@
-// host-lock.mjs — the ONE host lock of the heavy runtime work (a land's gate run, a release cut): one holder at a time on this host.
-//
-// The primitive is the atomic mkdir of a single lock directory. Its owner file is JSON (schema starci/host-lock@1) naming
-// who holds it: token, pid, role, purpose, the Orca terminal handle, the host and the start time. That makes three things possible:
-//   - a dead holder is detected (its pid is gone) and the lock is taken over atomically instead of blocking everyone;
-//   - a release is refused for a stranger (the token must match), so one actor never drops another's lock;
-//   - the rights guard (scripts/guards/rights.mjs) reads the owner (hostLockOwner) and decides who may do what meanwhile.
-// A lock directory without a readable owner file (no pid to test) is held, never stale, until it is older than
-// ownerlessStaleMs. The release cut (scripts/supervisor/release-cut.mjs, GOVERNANCE lane) runs under
-// withHostLock({role: 'release', purpose: 'release-cut'}); the land gate under withHostLock({role: 'coordinator', purpose: 'land'}).
-//
-// Every function is synchronous and pure fs; the seams {fs, now, isAlive, pid, host, env, dir, newToken, remove} are injectable.
-import nodeFs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { randomBytes } from 'node:crypto';
-import { pidAlive, starciLocalRoot } from '../../engine/db/machine.mjs';
-import { readEnv } from '../lib/env.mjs';
-import { safeRemove } from '../api/fs/safe-remove.mjs';
-import { onInterrupt } from '../lib/interrupt-cleanup.mjs';
-
-const HOST_LOCK_SCHEMA = 'starci/host-lock@1';
-export const ROLES = Object.freeze(['release', 'coordinator', 'lead', 'worker']);
-const OWNERLESS_STALE_MS = 6 * 60 * 60 * 1000;
-const OWNER_FILE = 'owner';
-const OWNERLESS_TEXT_CLIP = 500;
-
-/** The lock directory: STARCI_HOST_LOCK_DIR, else <starci local root>/host-lock. */
-export function hostLockDir({ env = process.env } = {}) {
-  const set = readEnv('STARCI_HOST_LOCK_DIR', env);
-  return set ? path.resolve(set) : path.join(starciLocalRoot(env), 'host-lock');
-}
-
-// The lock directory as found on disk: {kind: 'free'} | {kind: 'json', owner} | {kind: 'ownerless', text, mtimeMs}.
-// A directory without a readable owner file (a holder between its mkdir and its write, or a crash there) is 'ownerless' with
-// the directory's own age, so it too expires through ownerlessStaleMs.
-function readRaw(dir, fs) {
-  let st;
-  try { st = fs.statSync(dir); } catch (error) {
-    if (error?.code === 'ENOENT') return { kind: 'free' };
-    throw error;
-  }
-  let text = '';
-  try { text = String(fs.readFileSync(path.join(dir, OWNER_FILE), 'utf8')); } catch { /* no owner file yet */ }
-  try {
-    const owner = JSON.parse(text);
-    if (owner && typeof owner === 'object' && owner.schema === HOST_LOCK_SCHEMA && typeof owner.token === 'string') return { kind: 'json', owner };
-  } catch { /* not an owner document */ }
-  return { kind: 'ownerless', text, mtimeMs: st.mtimeMs };
-}
-
-// The owner object a raw lock stands for, with `stale` set: a JSON owner is stale when its ttl ran out, or when it is on this
-// host and its pid is gone; an ownerless lock is stale only past ownerlessStaleMs.
-function viewOf(raw, { now, isAlive, host, ownerlessStaleMs }) {
-  if (raw.kind === 'free') return null;
-  const at = now();
-  if (raw.kind === 'ownerless') {
-    return { schema: 'ownerless', ownerless: true, text: raw.text.slice(0, OWNERLESS_TEXT_CLIP), token: null, pid: null, role: null, purpose: null, handle: null, host: null,
-      since: new Date(raw.mtimeMs).toISOString(), ttlMs: null, stale: at - raw.mtimeMs >= ownerlessStaleMs };
-  }
-  const owner = raw.owner;
-  const since = Date.parse(owner.since);
-  const expired = Number.isFinite(owner.ttlMs) && owner.ttlMs > 0 && Number.isFinite(since) && at - since >= owner.ttlMs;
-  const dead = owner.host === host && !isAlive(owner.pid);
-  return { ...owner, stale: expired || dead };
-}
-
-const seamsOf = ({ fs = nodeFs, now = Date.now, isAlive = pidAlive, host = os.hostname(), ownerlessStaleMs = OWNERLESS_STALE_MS } = {}) => ({ fs, now, isAlive, host, ownerlessStaleMs });
-const sameLock = (raw, view) => (raw.kind === 'json' ? view.token === raw.owner.token : raw.kind === 'ownerless' && view.ownerless === true && view.text === raw.text.slice(0, OWNERLESS_TEXT_CLIP));
-const removeTree = (target, remove) => { try { const r = remove(target); return r !== false && r?.ok !== false; } catch { return false; } };
-const defaultRemove = (target) => safeRemove(target, { hold: () => null });
-
-// Move the lock directory aside (an atomic rename, so exactly one contender wins), then check that what moved is the lock
-// the caller judged (`expected`, a view). When it is not - another actor re-took the lock between the judgement and the
-// rename - the directory is put back if its place is still free. Returns {moved: true, aside} | {moved: false, gone} where
-// `gone` says the lock was already absent.
-function moveAside(dir, expected, { fs, newToken }) {
-  const aside = `${dir}.aside-${newToken().slice(0, 12)}`;
-  try { fs.renameSync(dir, aside); } catch (error) {
-    if (error?.code === 'ENOENT') return { moved: false, gone: true };
-    throw error;
-  }
-  const raw = readRaw(aside, fs);
-  if (!sameLock(raw, expected)) {
-    try { fs.renameSync(aside, dir); } catch { /* the place was re-taken: the moved lock stays aside, never deleted */ }
-    return { moved: false, gone: false };
-  }
-  return { moved: true, aside };
-}
-
-/**
- * The owner of the lock: null when it is free, else {schema, token, pid, role, purpose, handle, host, since, ttlMs, stale}.
- * `stale` is true for a holder whose process is gone (or whose ttl ran out): callers report it, acquireHostLock takes it over.
- * A lock directory without a readable owner reads {ownerless: true, text, since: <file time>, stale} with null token/pid/role.
- */
-export function hostLockOwner({ dir, env = process.env, ...seams } = {}) {
-  const s = seamsOf(seams);
-  return viewOf(readRaw(dir ?? hostLockDir({ env }), s.fs), s);
-}
-
-// One attempt to create the lock directory: `{ created }`; a lock a live holder keeps is `{ held }`; a vanished lock or a stale one
-// moved aside is `{ retry, seen, tookOver }` (tookOver: the stale owner whose lock was replaced).
-function createLockDir(lockDir, s, { newToken, remove }) {
-  try {
-    s.fs.mkdirSync(lockDir);
-    return { created: true };
-  } catch (error) {
-    if (error?.code !== 'EEXIST') throw error;
-    const seen = viewOf(readRaw(lockDir, s.fs), s);
-    if (!seen) return { retry: true, seen: null };
-    if (!seen.stale) return { held: seen };
-    const moved = moveAside(lockDir, seen, { fs: s.fs, newToken });
-    if (moved.moved) removeTree(moved.aside, remove);
-    return { retry: true, seen, tookOver: moved.moved ? seen : null };
-  }
-}
-
-function writeOwnerFile(lockDir, owner, s, remove) {
-  try { s.fs.writeFileSync(path.join(lockDir, OWNER_FILE), `${JSON.stringify(owner, null, 2)}\n`, { flag: 'wx' }); } catch (error) {
-    try { remove(lockDir); } catch { /* a directory without an owner expires through ownerlessStaleMs */ }
-    throw error;
-  }
-}
-
-/**
- * Take the lock. {ok: true, token, owner} (plus tookOverFrom: <the stale owner> when a dead holder's lock was replaced) or
- * {ok: false, reason: 'held', owner} or {ok: false, reason: 'bad-role', role}. A role outside ROLES is refused.
- */
-export function acquireHostLock({ role, purpose = null, handle, pid = process.pid, ttlMs = null, env = process.env, dir, newToken = () => randomBytes(16).toString('hex'), remove = defaultRemove, ...seams } = {}) {
-  if (!ROLES.includes(role)) return { ok: false, reason: 'bad-role', role: role ?? null, roles: ROLES };
-  const s = seamsOf(seams);
-  const lockDir = dir ?? hostLockDir({ env });
-  const token = newToken();
-  const owner = { schema: HOST_LOCK_SCHEMA, token, pid, role, purpose: purpose ?? null, handle: handle ?? readEnv('ORCA_TERMINAL_HANDLE', env) ?? null,
-    host: s.host, since: new Date(s.now()).toISOString(), ttlMs: ttlMs ?? null };
-  s.fs.mkdirSync(path.dirname(lockDir), { recursive: true });
-  let tookOverFrom = null;
-  let seen = null;
-  for (let attempt = 0; attempt < 4; attempt += 1) {
-    const step = createLockDir(lockDir, s, { newToken, remove });
-    if (step.held) return { ok: false, reason: 'held', owner: step.held };
-    if (step.retry) { seen = step.seen; tookOverFrom = step.tookOver ?? tookOverFrom; continue; }
-    writeOwnerFile(lockDir, owner, s, remove);
-    return { ok: true, token, owner, ...(tookOverFrom ? { tookOverFrom } : {}) };
-  }
-  return { ok: false, reason: 'held', owner: seen };
-}
-
-/**
- * Release the lock `token` holds: {ok: true, released: true}; {ok: true, released: false} when there is no lock;
- * {ok: false, reason: 'not-owner', owner} when someone else (or an ownerless owner) holds it - a stranger's release never removes it.
- */
-export function releaseHostLock({ token, env = process.env, dir, newToken = () => randomBytes(16).toString('hex'), remove = defaultRemove, ...seams } = {}) {
-  const s = seamsOf(seams);
-  const lockDir = dir ?? hostLockDir({ env });
-  const raw = readRaw(lockDir, s.fs);
-  if (raw.kind === 'free') return { ok: true, released: false };
-  const view = viewOf(raw, s);
-  if (!token || raw.kind !== 'json' || raw.owner.token !== token) return { ok: false, reason: 'not-owner', owner: view };
-  const moved = moveAside(lockDir, view, { fs: s.fs, newToken });
-  if (!moved.moved) {
-    if (moved.gone) return { ok: true, released: false };
-    return { ok: false, reason: 'not-owner', owner: hostLockOwner({ dir: lockDir, ...seams }) };
-  }
-  const left = !removeTree(moved.aside, remove);
-  return { ok: true, released: true, ...(left ? { leftover: moved.aside } : {}) };
-}
-
-/**
- * Run `fn({token, owner})` under the lock and always release it. Returns fn's result, or the refusal of acquireHostLock
- * ({ok: false, reason: 'held', owner}) without running fn (`options.onInterrupt` is the registration seam). An async fn holds the lock until its promise settles; a signal or an exit meanwhile releases it too (scripts/lib/interrupt-cleanup.mjs).
- */
-export function withHostLock(options, fn) {
-  const got = acquireHostLock(options);
-  if (!got.ok) return got;
-  const release = () => releaseHostLock({ token: got.token, env: options?.env, dir: options?.dir, fs: options?.fs, now: options?.now, isAlive: options?.isAlive, host: options?.host, remove: options?.remove });
-  const dispose = (options?.onInterrupt ?? onInterrupt)(release); // an interrupted holder drops its lock before the process ends
-  const done = () => { dispose(); release(); };
-  let out;
-  try { out = fn(got); } catch (error) { done(); throw error; }
-  if (typeof out?.then === 'function') return out.finally(done);
-  done();
-  return out;
-}

package/runtime/scripts/machine/lock-recovery.mjs

@@ -1,55 +0,0 @@
-// lock-recovery.mjs — the compositions around the ONE stale `.git/index.lock` recovery (scripts/api/git/index-lock.mjs
-// indexLock): the git-process probe over the host's process table (scripts/api/process/process-list.mjs), the Supervisor
-// audit event a removal records, and the command guard's pre-flight (scripts/guards/command-guard.mjs). The housekeeping
-// area `gitlocks` (scripts/housekeeping/hk-git-locks.mjs) uses the probe and the recorder too.
-import path from 'node:path';
-import { checkoutOf, gitDirOf, isGitImage, lockStat } from '../lib/git-dir.mjs';
-import { indexLock } from '../api/git/index-lock.mjs';
-import { processList } from '../api/process/process-list.mjs';
-import { isSpecRun } from '../lib/env.mjs';
-
-const LOCK_EVENT = 'git-index-lock-removed';
-
-/** Git-family processes on this host: [{pid, name, commandLine}], or null when the probe failed. A spec run (NODE_TEST_CONTEXT) never reads the host process table. */
-export function listGitProcesses({ platform = process.platform, run, env = process.env } = {}) {
-  if (isSpecRun(env)) return null;
-  const rows = processList({ where: "Name LIKE 'git%'", run, platform, timeoutMs: 30000 });
-  return rows ? rows.map((p) => ({ pid: p.pid, name: String(p.name ?? ''), commandLine: p.cmd })).filter((p) => isGitImage(p.name)) : null;
-}
-
-/** `record` for api/git/index-lock.mjs indexLock: one Supervisor audit event (machine.sqlite sup_events) per removal, naming who removed it. */
-export async function supervisorLockRecorder({ env = process.env, by, jobId = null, workflowId = null } = {}) {
-  const { withSupervisor, supervisorEvent } = await import('./home.mjs');
-  return (result) => withSupervisor((m) => supervisorEvent(m, { entityType: 'repo', entityId: result.repo, kind: LOCK_EVENT,
-    payload: { lock: result.lock, ageMs: Math.round(result.ageMs), bytes: result.bytes, mtime: result.mtime, by, jobId, workflowId } }), { env });
-}
-
-/**
- * The command guard's git pre-flight (scripts/guards/command-guard.mjs): when the checkout `cwd` is in holds an index
- * lock older than the declared window, try the recovery once and say what happened on stderr. Costs one stat when no
- * lock stands. Never throws: the command runs either way.
- */
-export async function preflightIndexLock({ cwd = process.cwd(), guard = null, env = process.env, say = () => {}, now = Date.now(), list = listGitProcesses } = {}) {
-  try {
-    const repo = checkoutOf(cwd);
-    const gitDir = repo ? gitDirOf(repo) : null;
-    const st = gitDir ? lockStat(path.join(gitDir, 'index.lock')) : null;
-    if (!st) return null;
-    const { allocationMs } = await import('../../engine/config.mjs');
-    const staleMs = allocationMs('housekeeping.gitIndexLockStaleMs');
-    if (now - st.mtimeMs < staleMs) return null;
-    const record = await supervisorLockRecorder({ env, by: 'command-guard', jobId: guard?.jobId ?? null, workflowId: guard?.workflowId ?? null });
-    const result = indexLock({ repo, staleMs, now, list, record });
-    const age = `${Math.round((result.ageMs ?? 0) / 60000)} min`;
-    if (result.state === 'removed') say(`starci guard: removed a stale ${result.lock} (${age} old, no git process on this repository); recorded as ${LOCK_EVENT}.`);
-    else if (result.state === 'held') say(`starci guard: ${result.lock} is ${age} old but a git process may still hold it (${result.holders.map((h) => h.pid).join(', ')}); left in place - retry shortly, never delete it by hand.`);
-    else if (result.state !== 'fresh' && result.state !== 'absent') {
-      const error = result.error ? `: ${result.error}` : '';
-      say(`starci guard: ${result.lock} is ${age} old and was left in place (${result.state}${error}).`);
-    }
-    return result;
-  } catch (error) {
-    say(`starci guard: index-lock check error (${error?.message ?? error}); running git anyway`);
-    return null;
-  }
-}

package/runtime/scripts/machine/roles-contract.mjs

@@ -1,90 +0,0 @@
-// roles-contract.mjs — reads the one roles contract (modules/kernel/roles.yaml) and renders a role's block: the Markdown a surface
-// carries between its markers, and the compact lines the op prompt prints at launch. The roles-contract self-check compares
-// every surface with this rendering.
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { parseYaml } from '../../engine/yaml.mjs';
-
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-export const ROLES_FILE = 'modules/kernel/roles.yaml';
-
-/** The roles contract document of the tree at `root`. */
-export const rolesContract = (root = ROOT) => parseYaml(fs.readFileSync(path.join(root, ROLES_FILE), 'utf8'));
-
-export const markerOf = (id) => ({ begin: `<!-- roles:begin ${id} -->`, end: `<!-- roles:end ${id} -->` });
-
-const bullets = (label, items) => (items?.length ? [`- ${label}:`, ...items.map((item) => `  - ${item}`)] : []);
-const nameOf = (doc, id) => (id === 'runtime' ? 'the runtime' : doc.roles.find((role) => role.id === id)?.label ?? id);
-
-/** The lines that state who a role reports to, who oversees it and what it owns. */
-function chainLines(doc, role) {
-  const up = role.reportsTo ? `${nameOf(doc, role.reportsTo)} (${role.reportsUpWhen})` : 'no one';
-  return [`- Owns: ${role.owns}. Decides alone: ${role.decidesAlone}.`,
-    `- Reports to: ${up}. Overseen by: ${role.overseenBy.map((id) => nameOf(doc, id)).join(', ') || 'no one'}.`,
-    `- Measure: ${role.measure}.`];
-}
-
-/** The token budget line of a role that declares one. */
-function budgetLines(role) {
-  const b = role.tokenBudget;
-  const wake = role.wakeBudget;
-  if (b) return [`- Token budget (${b.status}): ${b.perAttempt.default} per ${b.unit ?? 'attempt'}; over it, ${b.onExceed}.`];
-  if (wake) {
-    const boot = wake.perBoot ? `, ${wake.perBoot.turns} turns and ${wake.perBoot.tokens} tokens for its boot (the contract files and the rev-ack manifest)` : '';
-    return [`- Wake budget (${wake.status}): ${wake.perWake.turns} turns and ${wake.perWake.tokens} tokens per wake${boot}; over it, ${wake.onExceed}.`];
-  }
-  return role.noBudget ? [`- No budget: ${role.noBudget}.`] : [];
-}
-
-/** The line that states how a role learns that the runtime tree changed (its revisionAck declaration). */
-function revisionLines(role) {
-  const decl = role.revisionAck;
-  if (!decl) return [];
-  if (decl.noAck) return [`- Runtime changes: ${decl.noAck}.`];
-  if (decl.admission) return [`- Runtime changes: ${decl.reason}.`];
-  return [`- Runtime changes (modules/kernel/revision-scope.yaml): woken once with exactly the changed files that concern it, it reads them and attests with ${decl.verb}; a change that concerns it nothing costs it nothing; it is replaced by a fresh seat, at its next yield, only when a rule of its contract was removed or reversed or its boot prompt changed.`];
-}
-
-/** The guard binding, the happy errors and the bug surface of a role that declares them (the owner's two classes of error). */
-function standardLines(role) {
-  const unbound = role.noSeat ? [`- Guard: none by design; ${role.noSeatReason}.`] : [];
-  const guard = role.guard ? [`- Guard: its terminals are bound as the "${role.guard.role}" role of modules/kernel/command-policy.yaml.`] : unbound;
-  const happy = role.happyErrors?.map((error) => `${error.id} (policy row ${error.row}): ${error.what}`);
-  const bugs = role.bugSurface?.map((entry) => `${entry.bug}: ${entry.signal}`);
-  return [...guard, ...bullets('Happy errors it handles (the system working as designed, handled inside the chain through the policy)', happy),
-    ...bullets('A bug in this role (the chain neither fixes nor works around it; Debug removes it with a change to .claude) is detected by', bugs)];
-}
-
-/** The Debug lines that state whom it audits and when it retires. */
-function debugLines(doc, role) {
-  if (!role.oversees) return [];
-  const criteria = role.endCondition.criteria.map((c) => `${c.id}: ${c.rule}`);
-  return [`- Audits: ${role.oversees.map((id) => nameOf(doc, id)).join(', ')}.`, ...bullets('Retires when', criteria)];
-}
-
-/** The Markdown block of one role (without its markers). */
-export function renderRoleBlock(doc, id) {
-  const role = doc.roles.find((entry) => entry.id === id);
-  const lines = [`**${role.label}** (${ROLES_FILE}#${id}): ${role.scope}`, ...bullets('Does', role.does), ...bullets('Must clean up', role.cleanup),
-    ...bullets('Never', role.never), ...chainLines(doc, role), ...budgetLines(role), ...revisionLines(role), ...standardLines(role), ...debugLines(doc, role), `- Principles: ${role.binds.join(' ')} (${ROLES_FILE}, principles).`];
-  return lines.join('\n');
-}
-
-/** The compact lines of a role for a launch prompt. */
-export function renderRoleLines(id, root = ROOT) {
-  const doc = rolesContract(root);
-  const role = doc.roles.find((entry) => entry.id === id);
-  return [`role: ${role.label} (${ROLES_FILE}#${id}) - ${role.scope}`, ...role.never.map((item) => `  never: ${item}`),
-    ...role.cleanup.map((item) => `  clean up: ${item}`), `  reports to: ${nameOf(doc, role.reportsTo)} only`];
-}
-
-/** The text with the role's block replaced between its markers, or appended with markers when it has none. */
-export function withRoleBlock(text, doc, id) {
-  const { begin, end } = markerOf(id);
-  const block = `${begin}\n${renderRoleBlock(doc, id)}\n${end}`;
-  const from = text.indexOf(begin);
-  const to = text.indexOf(end);
-  if (from < 0 || to < from) return `${text.trimEnd()}\n\n${block}\n`;
-  return text.slice(0, from) + block + text.slice(to + end.length);
-}

package/runtime/scripts/machine/runtime-change.mjs

@@ -1,20 +0,0 @@
-// runtime-change.mjs — the typed refusal of a runtime change by the Supervisor. Changing .claude belongs to Debug and the owner's
-// release flow (modules/kernel/roles.yaml chain.runtimeChange); the verbs and the code are read from there, so the command guard,
-// the file-write guard and the CLI dispatcher refuse with one voice.
-import { rolesContract } from './roles-contract.mjs';
-
-export const RUNTIME_CHANGE_CODE = 'RUNTIME_CHANGE_OWNED_BY_DEBUG';
-
-/** The refusal fields {code, reason, remedy} for `words` (the group, verb and subcommand a caller runs), or null when they change nothing. */
-export function runtimeChangeRefusal(words) {
-  const { runtimeChange } = rolesContract().chain;
-  const hit = runtimeChange.verbs.find((verb) => verb.every((word, index) => words[index] === word));
-  if (!hit) return null;
-  return { code: RUNTIME_CHANGE_CODE, reason: `the Supervisor changes no runtime code: starci ${hit.join(' ')} belongs to Debug`, remedy: runtimeChange.use };
-}
-
-/** The refusal fields for a Supervisor write inside the runtime checkout. */
-export function runtimeWriteRefusal() {
-  const { runtimeChange } = rolesContract().chain;
-  return { code: RUNTIME_CHANGE_CODE, reason: 'the Supervisor changes no file of the runtime checkout: .claude belongs to Debug and the owner\'s release flow', remedy: runtimeChange.use };
-}