@starci/hfs 4.7.31 → 4.7.33

package/runtime/scripts/machine/evidence-store.mjs

@@ -0,0 +1,223 @@
+// evidence-store.mjs — agent output into runtime.sqlite + the blob store (docs/ledger-db.md).
+//
+// Bytes live in the content-addressed store (engine/db/blob.mjs, <runtime root>/.runtime/artifacts/<sha[0:2]>/<sha>);
+// the ledger holds only the index rows that point at them:
+//   blobs                         one row per sha this ledger references (media type, redaction, file uri)
+//   job_artifacts                 every file output, keyed (attempt_id, name) — or (workflow_id, name) for the Kernel's
+//                                 own outputs — immutable: a second put with other bytes is refused (H10)
+//   check_runs                    every op / settler / parity / integrate check: the RAW exit the runner saw apart from
+//                                 the exit the op DECLARED (H8); 'unavailable' is its own status and never red (H7)
+//   attempt_transcript_snapshots  the redacted scrollback of a live op terminal, every 60 s
+//   op_attempts.transcript_sha    the full redacted scrollback when the attempt ends
+// Text bytes pass scripts/lib/redact.mjs before every put (blobs.redaction='v1'); media is stored as is ('binary').
+// The rows go through the runtime writer (engine/db/ledger.mjs recordBlob, recordArtifact, recordCheckRun,
+// recordTranscriptSnapshot, setAttemptTranscript); this module is the evidence policy on top of it: redaction,
+// naming, kinds and roles, the H7/H8 status rules. Every write runs inside the caller's ledger.transaction; the blob
+// put happens BEFORE the transaction (stageBlob), so a rolled-back transaction leaves only an unreferenced blob for GC.
+import fs from 'node:fs';
+import path from 'node:path';
+import { putBlob, blobPath } from '../../engine/db/blob.mjs';
+import { redactBytes } from '../lib/redact.mjs';
+import { recordBlob, recordArtifact, recordCheckRun as writeCheckRun, recordTranscriptSnapshot, attachToReport, setAttemptTranscript,
+  JOB_ARTIFACT_KINDS, JOB_ARTIFACT_SUBKINDS, JOB_ARTIFACT_ROLES } from '../../engine/db/ledger.mjs';
+import { newSpanId } from '../../engine/db/machine.mjs';
+import { refuse } from '../../engine/refuse.mjs';
+
+const ARTIFACT_ROLES = JOB_ARTIFACT_ROLES;
+export const ARTIFACT_KINDS = JOB_ARTIFACT_KINDS;
+export const ARTIFACT_SUBKINDS = JOB_ARTIFACT_SUBKINDS;
+const ARTIFACT_ORIGINS = Object.freeze(['op', 'settler', 'checker', 'kernel']);
+const CHECK_PHASES = Object.freeze(['before', 'after', 'verify', 'parity', 'integrate']);
+const CHECK_RUNNERS = Object.freeze(['op', 'settler', 'kernel', 'parity', 'integrate']);
+export const CHECK_STATUSES = Object.freeze(['pass', 'fail', 'unavailable', 'error', 'skipped']);
+/** A check whose status counts as red. 'unavailable' (the checker could not run: infra) and 'skipped' never do (H7). */
+const RED_CHECK_STATUSES = Object.freeze(['fail', 'error']);
+export const TRANSCRIPT_SNAPSHOT_MS = 60_000;
+
+
+const slash = (p) => String(p).replaceAll('\\', '/');
+
+const IMAGE = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif', '.svg': 'image/svg+xml' };
+const VIDEO = { '.webm': 'video/webm', '.mp4': 'video/mp4', '.mov': 'video/quicktime' };
+const OTHER = { '.json': 'application/json', '.md': 'text/markdown', '.yaml': 'text/yaml', '.yml': 'text/yaml', '.txt': 'text/plain',
+  '.log': 'text/plain', '.jsonl': 'application/x-ndjson', '.out': 'text/plain', '.patch': 'text/x-diff', '.diff': 'text/x-diff', '.html': 'text/html',
+  '.htm': 'text/html', '.mhtml': 'multipart/related', '.zip': 'application/zip', '.trace': 'application/octet-stream', '.csv': 'text/csv', '.xml': 'application/xml' };
+/** The media type of a file, from its extension. */
+export const mediaTypeOf = (file) => { const ext = path.extname(String(file)).toLowerCase(); return IMAGE[ext] ?? VIDEO[ext] ?? OTHER[ext] ?? 'application/octet-stream'; };
+
+/** The job_artifacts.kind of a file, from its name. */
+export function kindOf(file) {
+  const base = path.basename(String(file)).toLowerCase(), ext = path.extname(base);
+  if (ext === '.patch') return 'patch';
+  if (ext === '.diff') return 'diff';
+  if (IMAGE[ext]) return 'image';
+  if (VIDEO[ext]) return 'video';
+  if (ext === '.trace' || (ext === '.zip' && base.includes('trace'))) return 'trace';
+  if (/^(report|result)([.-].*)?\.(json|md|ya?ml)$/.test(base)) return 'report';
+  if (['.log', '.txt', '.out', '.jsonl'].includes(ext)) return 'log';
+  return 'file';
+}
+
+/** The artifact role of an attached file, from its name. */
+export function roleOf(file) {
+  const kind = kindOf(file), ext = path.extname(String(file)).toLowerCase();
+  if (kind === 'image') return 'screenshot';
+  if (kind === 'video') return 'video';
+  if (kind === 'trace') return 'trace';
+  if (kind === 'patch') return 'patch';
+  if (kind === 'diff') return 'diff';
+  if (kind === 'log') return 'log';
+  if (['.html', '.htm', '.mhtml'].includes(ext)) return 'dom';
+  return 'report-attachment';
+}
+
+// --------------------------------------------------------------------------------------------- blobs
+/**
+ * Put bytes (a Buffer, a string, or a file path) in the blob store, redacted first when they are text. Runs OUTSIDE
+ * the ledger transaction. Returns {sha, bytes, mediaType, redaction, fileUri} for registerBlob / putArtifact.
+ * @param {string|Uint8Array|ArrayBuffer|ArrayLike<number>} source
+ * @param {{mediaType?: string|null, file?: boolean|null, repoRoots?: string[]}} [options]
+ */
+export function stageBlob(source, { mediaType = null, file = null, repoRoots = [] } = {}) {
+  let raw;
+  if (Buffer.isBuffer(source)) raw = source;
+  else if (typeof source === 'string' && file === false) raw = Buffer.from(source, 'utf8');
+  else if (typeof source === 'string') raw = fs.readFileSync(source);
+  else raw = Buffer.from(source);
+  const type = mediaType ?? (typeof source === 'string' && file !== false ? mediaTypeOf(source) : 'application/octet-stream');
+  const { bytes, redaction } = redactBytes(raw, type, { repoRoots });
+  const put = putBlob(bytes, { mediaType: type });
+  return { sha: put.sha, bytes: put.size, mediaType: type, redaction, fileUri: slash(blobPath(put.sha)) };
+}
+
+/** Text as a staged blob (redacted), or null for empty text. */
+export const stageText = (text, { mediaType = 'text/plain', repoRoots = [] } = {}) =>
+  (typeof text === 'string' && text.length ? stageBlob(text, { mediaType, file: false, repoRoots }) : null);
+
+/** The blobs row of one staged blob; a sha already known keeps its first row. Returns the sha. */
+export function registerBlob(db, staged, { now = Date.now() } = {}) {
+  if (!staged?.sha) return null;
+  recordBlob(db, { sha256: staged.sha, bytes: staged.bytes, mediaType: staged.mediaType, fileUri: staged.fileUri, redaction: staged.redaction ?? null, createdAt: now });
+  return staged.sha;
+}
+
+// ----------------------------------------------------------------------------------------- artifacts
+/**
+ * One job_artifacts row for a staged blob. `name` is the logical name, unique per attempt (per workflow for a
+ * Kernel artifact, attemptId null). Filing the same name with the same bytes again returns the existing row;
+ * other bytes under a filed name are refused `artifact-immutable` (H10). Returns {artifactId, created}.
+ */
+export function putArtifact(db, { workflowId, attemptId = null, jobId = null, opId = null, cut = null, role, kind = null, subkind = null,
+  name, blob, label = null, scopeRef = null, round = null, runId = null, origin, baseSha = null, headSha = null, integratedSha = null, now = Date.now() }) {
+  if (!ARTIFACT_ROLES.includes(role)) throw refuse(`artifact role must be ${ARTIFACT_ROLES.join('|')}, got '${role}'`, 'artifact-role-unknown');
+  if (!ARTIFACT_ORIGINS.includes(origin)) throw refuse(`artifact origin must be ${ARTIFACT_ORIGINS.join('|')}, got '${origin}'`, 'artifact-origin-unknown');
+  const logical = slash(name ?? '').replace(/^\/+/, '');
+  if (!logical || logical.split('/').includes('..')) throw refuse(`unsafe artifact name: ${name}`, 'artifact-name-invalid');
+  const k = kind ?? kindOf(logical);
+  if (!ARTIFACT_KINDS.includes(k)) throw refuse(`artifact kind must be ${ARTIFACT_KINDS.join('|')}, got '${k}'`, 'artifact-kind-unknown');
+  if (subkind != null && !ARTIFACT_SUBKINDS.includes(subkind)) throw refuse(`artifact subkind must be ${ARTIFACT_SUBKINDS.join('|')}, got '${subkind}'`, 'artifact-subkind-unknown');
+  registerBlob(db, blob, { now });
+  const before = attemptId != null ? db.prepare('SELECT artifact_id FROM job_artifacts WHERE attempt_id=? AND name=?').get(attemptId, logical)
+    : db.prepare('SELECT artifact_id FROM job_artifacts WHERE workflow_id=? AND attempt_id IS NULL AND name=?').get(workflowId, logical);
+  let row;
+  try {
+    row = recordArtifact(db, { workflowId, attemptId, name: logical, sha256: blob.sha, role, kind: k, origin, subkind, label, scopeRef, round, runId, cut,
+      baseSha, headSha, integratedSha, createdAt: now, ...(attemptId == null ? { jobId, opId } : {}) });
+  } catch (error) {
+    if (error?.code === 'STARCI_ARTIFACT_IMMUTABLE') throw refuse(`artifact '${logical}' of attempt ${attemptId ?? '(kernel)'} is already filed with other bytes; artifacts are immutable, file a new name`, 'artifact-immutable', { name: logical });
+    throw error;
+  }
+  return { artifactId: row.artifact_id, created: !before };
+}
+
+/** Link report → artifact (report_attachments). */
+export const linkReportAttachment = (db, { reportId, artifactId }) => attachToReport(db, { reportId, artifactId });
+
+// ------------------------------------------------------------------------------------------- attempts
+/** The op_attempts row of a dispatch (workflow + dispatch id), else of the job's latest dispatch, else null. */
+export function attemptOf(db, { workflowId = null, dispatchId = null, jobId = null, attemptId = null } = {}) {
+  if (attemptId != null) return db.prepare('SELECT * FROM op_attempts WHERE attempt_id=?').get(attemptId) ?? null;
+  if (workflowId && dispatchId) { const row = db.prepare('SELECT * FROM op_attempts WHERE workflow_id=? AND dispatch_id=?').get(workflowId, dispatchId); if (row) return row; }
+  if (jobId) return db.prepare('SELECT * FROM op_attempts WHERE job_id=? ORDER BY dispatch_seq DESC LIMIT 1').get(jobId) ?? null;
+  return null;
+}
+
+// ------------------------------------------------------------------------------------------- checks
+/**
+ * The status of one check run. `unavailable` (the checker could not run: missing tool, host down, spawn error)
+ * is infra, never red (H7); a runner-observed non-zero exit is never 'pass' (H8).
+ * @param {{exitCode?: number|null, declaredExitCode?: number|null, unavailable?: boolean, error?: boolean,
+ *   skipped?: boolean, status?: string|null}} [options]
+ */
+function checkStatusOf({ exitCode = null, declaredExitCode = null, unavailable = false, error = false, skipped = false, status = null } = {}) {
+  if (status && !CHECK_STATUSES.includes(status)) throw refuse(`check status must be ${CHECK_STATUSES.join('|')}, got '${status}'`, 'check-status-unknown');
+  if (skipped || status === 'skipped') return 'skipped';
+  if (unavailable || status === 'unavailable') return 'unavailable';
+  if (error || status === 'error') return 'error';
+  // The raw exit wins over the declared one; an explicit 'fail' (a green exit with red findings) stays fail.
+  let exit = null;
+  if (Number.isInteger(exitCode)) exit = exitCode;
+  else if (Number.isInteger(declaredExitCode)) exit = declaredExitCode;
+  if (exit == null) return status === 'pass' || status === 'fail' ? status : 'error';
+  return exit === 0 && status !== 'fail' ? 'pass' : 'fail';
+}
+
+const integerOrNull = (value) => (Number.isInteger(value) ? value : null);
+
+// The raw exit the runtime observed and the exit an op declared: an op's own exit is only its claim.
+function exitCodesOf(runner, exitCode, declaredExitCode) {
+  if (runner !== 'op') return { raw: integerOrNull(exitCode), declared: integerOrNull(declaredExitCode) };
+  return { raw: null, declared: Number.isInteger(exitCode) ? exitCode : integerOrNull(declaredExitCode) };
+}
+
+/**
+ * One check_runs row (engine/db/ledger.mjs recordCheckRun). `runner` 'op' is always authority 'declared' (the op's own claim: exitCode is stored as
+ * declared_exit_code, exit_code stays NULL — the runtime did not observe it); the runtime's own runners store the
+ * raw exit they observed in exit_code. stdout/stderr/output are staged blobs (stageBlob/stageText) or null.
+ * run_seq numbers re-runs of the same (attempt, runner, phase, name). Returns {checkId, runSeq, status, red}.
+ */
+export function recordCheck(db, { attemptId, name, phase, runner, authority = null, command = null, cwd = null,
+  inputDigest = null, exitCode = null, declaredExitCode = null, attribution = null, status = null, unavailable = false, error = false, skipped = false,
+  startedAt = null, finishedAt = null, wallMs = null, stdout = null, stderr = null, output = null, summary = null, note = null,
+  spanId = newSpanId(), now = Date.now() }) {
+  if (!CHECK_RUNNERS.includes(runner)) throw refuse(`check runner must be ${CHECK_RUNNERS.join('|')}, got '${runner}'`, 'check-runner-unknown');
+  if (!CHECK_PHASES.includes(phase)) throw refuse(`check phase must be ${CHECK_PHASES.join('|')}, got '${phase}'`, 'check-phase-unknown');
+  if (attemptId == null) throw refuse(`check '${name}' has no attempt`, 'check-attempt-missing');
+  const auth = runner === 'op' ? 'declared' : authority ?? 'runtime';
+  const { raw, declared } = exitCodesOf(runner, exitCode, declaredExitCode);
+  const st = checkStatusOf({ exitCode: raw, declaredExitCode: declared, unavailable, error, skipped, status });
+  for (const b of [stdout, stderr, output]) if (b) registerBlob(db, b, { now });
+  const wall = wallMs ?? (Number.isFinite(startedAt) && Number.isFinite(finishedAt) ? finishedAt - startedAt : null);
+  const row = writeCheckRun(db, { attemptId, name, phase, runner, authority: auth, status: st, spanId, createdAt: now, command, cwd, inputDigest,
+    exitCode: raw, declaredExitCode: declared, attributionJson: attribution == null ? null : JSON.stringify(attribution), startedAt, finishedAt, wallMs: wall,
+    stdoutSha: stdout?.sha ?? null, stderrSha: stderr?.sha ?? null, outputSha: output?.sha ?? null,
+    summaryJson: summary == null ? null : JSON.stringify(summary), note });
+  return { checkId: row.check_id, runSeq: row.run_seq, status: st, red: RED_CHECK_STATUSES.includes(st) };
+}
+
+/** The latest run of every check of an attempt (optionally one runner): [row] ordered by check_id. */
+export const latestCheckRuns = (db, attemptId, { runner = null } = {}) => db.prepare(`SELECT c.* FROM check_runs c
+  WHERE c.attempt_id=? ${runner ? 'AND c.runner=?' : ''} AND c.run_seq=(SELECT max(run_seq) FROM check_runs x
+    WHERE x.attempt_id=c.attempt_id AND x.runner=c.runner AND x.phase=c.phase AND x.name=c.name) ORDER BY c.check_id`)
+  .all(attemptId, ...(runner ? [runner] : []));
+
+// ---------------------------------------------------------------------------------------- transcripts
+const linesOf = (text) => (text ? text.split('\n').length : 0);
+
+/** A periodic scrollback snapshot of a live attempt; an unchanged scrollback adds no row. Returns {written, sha}. */
+export function recordAttemptSnapshot(db, { attemptId, text, blob = null, at = Date.now() }) {
+  const staged = blob ?? stageText(text);
+  if (!staged) return { written: false, sha: null };
+  registerBlob(db, staged, { now: at });
+  const written = recordTranscriptSnapshot(db, { attemptId, sha256: staged.sha, lines: linesOf(text ?? ''), bytes: staged.bytes, at });
+  return { written, sha: staged.sha };
+}
+
+/** The attempt's full redacted scrollback at its end: op_attempts.transcript_sha. Returns the sha or null. */
+export function recordFinalTranscript(db, { attemptId, text = null, blob = null, at = Date.now() }) {
+  const staged = blob ?? stageText(text);
+  if (!staged || attemptId == null) return null;
+  registerBlob(db, staged, { now: at });
+  setAttemptTranscript(db, { attemptId, transcriptSha: staged.sha, at });
+  return staged.sha;
+}

package/runtime/scripts/machine/home.mjs

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

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