@uchibeke/gallivant 0.0.0-stage → 0.2.0

package/lib/learning_contract.mjs

@@ -0,0 +1,2 @@
+// Pending durable audit deliveries keep the coordinator awake on every host.
+export const learningDeliveryPending = entry => Object.keys(entry?.learning_deliveries || {}).length > 0;

package/lib/learning_data.mjs

@@ -0,0 +1,135 @@
+// All learning input is data. These bytes are also the approval/signature format.
+import { createHash } from "node:crypto";
+import { redact } from "./execution_io.mjs";
+
+export const learningError = (code, message) => Object.assign(new Error(message), { code: `LEARNING_${code}` });
+export const hash = value => createHash("sha256").update(typeof value === "string" || Buffer.isBuffer(value) ? value : canonical(value)).digest("hex");
+const bad = message => { throw learningError("INPUT", message); };
+const dangerousText = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/u;
+export function textField(value, name, max = 2048) {
+  if (typeof value !== "string" || !value.trim() || Buffer.byteLength(value) > max || dangerousText.test(value) || /[\ud800-\udfff]/u.test(value.replace(/[\ud800-\udbff][\udc00-\udfff]/g, ""))) bad(`invalid ${name}`);
+  return value;
+}
+export function closed(value, keys, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype || Object.keys(value).some(k => !keys.includes(k)) || keys.some(k => !Object.hasOwn(value, k))) bad(`invalid ${name} schema`);
+}
+export function canonical(value) {
+  // RFC 8785: ECMAScript number serialization, UTF-16 key order, no Unicode normalization.
+  const walk = (v, depth = 0) => {
+    if (depth > 24) bad("JSON nesting limit");
+    if (v === null || typeof v === "boolean") return JSON.stringify(v);
+    if (typeof v === "number") { if (!Number.isFinite(v)) bad("nonfinite JSON number"); return JSON.stringify(v); }
+    if (typeof v === "string") {
+      if (/[\ud800-\udfff]/u.test(v.replace(/[\ud800-\udbff][\udc00-\udfff]/g, ""))) bad("invalid Unicode");
+      return JSON.stringify(v);
+    }
+    if (Array.isArray(v)) return `[${v.map(x => walk(x, depth + 1)).join(",")}]`;
+    if (v && Object.getPrototypeOf(v) === Object.prototype) return `{${Object.keys(v).sort().map(k => `${walk(k)}:${walk(v[k], depth + 1)}`).join(",")}}`;
+    bad("non-JSON value");
+  };
+  return walk(value);
+}
+export function parseJson(input, max = 256 * 1024) {
+  const bytes = Buffer.isBuffer(input) ? input : Buffer.from(input);
+  if (bytes.length > max) bad("JSON byte limit");
+  let raw;
+  try { raw = new TextDecoder("utf-8", { fatal: true }).decode(bytes); } catch { bad("invalid UTF-8"); }
+  // Parse object keys before JSON.parse can discard duplicates. Bound nesting and tokens.
+  let pos = 0, tokens = 0;
+  const ws = () => { while (/\s/.test(raw[pos] || "") && pos < raw.length) pos++; };
+  const string = () => {
+    const start = pos++;
+    while (pos < raw.length) {
+      const c = raw[pos++];
+      if (c === "\\") pos++;
+      else if (c === '"') { try { return JSON.parse(raw.slice(start, pos)); } catch { bad("invalid JSON string"); } }
+    }
+    bad("unterminated JSON string");
+  };
+  const value = (depth = 0) => {
+    if (depth > 24 || ++tokens > 100_000) bad("JSON structure limit");
+    ws();
+    const c = raw[pos];
+    if (c === '"') return string();
+    if (c === "{" || c === "[") {
+      const object = c === "{", end = object ? "}" : "]", keys = new Set(); pos++; ws();
+      if (raw[pos] === end) { pos++; return; }
+      for (;;) {
+        if (object) {
+          ws(); if (raw[pos] !== '"') bad("invalid JSON key");
+          const key = string(); if (keys.has(key) || ["__proto__", "constructor", "prototype"].includes(key)) bad("duplicate or unsafe JSON key"); keys.add(key);
+          ws(); if (raw[pos++] !== ":") bad("invalid JSON object");
+        }
+        value(depth + 1); ws();
+        if (raw[pos] === end) { pos++; return; }
+        if (raw[pos++] !== ",") bad("invalid JSON delimiter");
+      }
+    }
+    const m = raw.slice(pos).match(/^(?:null|true|false|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)/);
+    if (!m) bad("invalid JSON value"); pos += m[0].length;
+  };
+  value(); ws(); if (pos !== raw.length) bad("trailing JSON");
+  let result; try { result = JSON.parse(raw); } catch { bad("invalid JSON"); }
+  canonical(result);
+  return result;
+}
+export function literalPath(path) {
+  textField(path, "project path", 512);
+  if (path.startsWith("/") || /[\\:*?\[\]{}\s]/.test(path) || path.split("/").some(x => !x || x === "." || x === "..") || path.split("/").some(x => x.startsWith("."))) bad("unsafe literal project path");
+  return path;
+}
+export function repository(repo) {
+  closed(repo, ["host", "id"], "repository");
+  if (repo.host !== "github.com" || typeof repo.id !== "string" || !/^[1-9]\d{0,19}$/.test(repo.id)) bad("unsupported repository identity");
+  return repo;
+}
+export function repositoryName(name) {
+  if (typeof name !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(name) || name.includes("..")) bad("expected owner/repository");
+  return name;
+}
+export const digestField = v => { if (typeof v !== "string" || !/^[a-f0-9]{64}$/.test(v)) bad("expected SHA-256 digest"); return v; };
+export const candidateId = v => { if (typeof v !== "string" || !/^lesson-[a-z0-9-]{1,80}$/.test(v)) bad("invalid candidate ID"); return v; };
+export function candidate(value, repo) {
+  closed(value, ["version", "id", "repo", "paths", "applicability", "guidance", "rationale", "example", "evidence", "disposition", "regression", "provenance"], "candidate");
+  if (value.version !== 1) bad("unsupported candidate version");
+  candidateId(value.id); repository(value.repo);
+  if (canonical(value.repo) !== canonical(repo)) bad("foreign repository candidate");
+  if (!Array.isArray(value.paths) || value.paths.length > 20 || new Set(value.paths).size !== value.paths.length) bad("invalid project scopes");
+  value.paths.forEach(literalPath);
+  for (const name of ["applicability", "guidance", "rationale", "example"]) textField(value[name], name);
+  if (!Array.isArray(value.evidence) || !value.evidence.length || value.evidence.length > 20 || new Set(value.evidence).size !== value.evidence.length) bad("invalid candidate evidence");
+  value.evidence.forEach(digestField);
+  if (!["unconfirmed", "fixed", "contested", "retracted"].includes(value.disposition)) bad("invalid fix disposition");
+  if (value.regression !== null) literalPath(value.regression);
+  closed(value.provenance, ["provider", "inputDigest", "at"], "provenance");
+  textField(value.provenance.provider, "provider", 80); digestField(value.provenance.inputDigest); iso(value.provenance.at);
+  // A lesson is advice, never an alternative configuration/policy program.
+  const advice = [value.applicability, value.guidance, value.rationale, value.example].join("\n");
+  if (/\b(?:disable|skip|bypass|override|change|replace|ignore|increase|remove|set|grant)\b[^.\n]{0,120}\b(?:permissions?|tools?|budgets?|trust|verify|verification|acceptance|merge policy|aport|gates?|sandbox|signer|checkpoint)\b/i.test(advice)) bad("candidate attempts to change authority or task gates");
+  if (canonical(redact(value)) !== canonical(value)) bad("candidate contains unredacted secret material");
+  if (Buffer.byteLength(canonical(value)) > 16 * 1024) bad("candidate byte limit");
+  return { content: parseJson(canonical(value)), digest: hash(value) };
+}
+export function iso(value) {
+  if (typeof value !== "string" || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{3})?Z$/.test(value) || !Number.isFinite(Date.parse(value))) bad("invalid UTC timestamp");
+  return value;
+}
+export function dateRange(since, until, now) {
+  const end = until ? date(until) : now, start = since ? date(since) : end - 30 * 86400_000;
+  if (!Number.isFinite(start) || !Number.isFinite(end) || start >= end) bad("expected half-open UTC date range");
+  return { since: new Date(start).toISOString(), until: new Date(end).toISOString() };
+}
+const date = value => {
+  if (typeof value !== "string" || !/^\d{4}-\d\d-\d\d$/.test(value)) bad("dates use YYYY-MM-DD");
+  const n = Date.parse(value + "T00:00:00Z");
+  if (!Number.isFinite(n) || new Date(n).toISOString().slice(0, 10) !== value) bad("invalid date");
+  return n;
+};
+export function minimized(text, secrets = []) {
+  const raw = String(text ?? "");
+  const clean = redact(raw, secrets).replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+  const bytes = Buffer.from(clean), excerpt = new TextDecoder().decode(bytes.subarray(0, 2048));
+  return { excerpt, incomplete: bytes.length > 2048, redacted: clean !== raw, sourceDigest: hash(raw) };
+}
+// JSON escapes all terminal controls; Markdown is a view, never interpreted or fetched.
+export const safeDisplay = value => JSON.stringify(value, null, 2).replace(/[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);

package/lib/learning_input.mjs

@@ -0,0 +1,111 @@
+// Both initial and subsequent, local and hosted dispatch use this seam. No raw
+// feedback, candidate, repository instruction or task field can enable learning.
+import { hash, learningError, literalPath } from "./learning_data.mjs";
+import { executionRunner } from "./execution.mjs";
+
+export { learningDeliveryPending } from "./learning_contract.mjs";
+
+export async function revokeLearningAttempts(ctx, { repo, removed, reason, prepared = [] }) {
+  const outcomes = [];
+  const entries = new Map(ctx.state.entries());
+  for (const id of new Set([...entries.keys(), ...prepared.map(d => d.taskId)])) {
+    const entry = entries.get(id), intents = prepared.filter(d => d.taskId === id);
+    const delivered = entry?.learning && hash(entry.learning.repo) === hash(repo) && entry.learning.rules?.some(r => !removed || removed.some(x => x.id === r.id && x.digest === r.digest));
+    if (!delivered && !intents.length) continue;
+    const runner = executionRunner(ctx, id, entry?.harness || intents[0]?.profile), current = runner.current();
+    const pending = intents.some(d => current?.execution?.learning?.key === d.key || current?.execution?.operationId === d.operationId);
+    // An old undelivered intent must not cancel a later unrelated operation.
+    if (!delivered && !pending) continue;
+    // Preserve task identity, PR, code, review cursor and spend. Do not promise
+    // cancellation or erased provider memory when the backend cannot confirm it.
+    if (entry) ctx.state.update(id, { learning_revocation: { reason, freshSessionRequired: true, at: new Date().toISOString() } });
+    let answer = { confirmed: false, unsupported: true };
+    try { if (current?.running && runner.cancel) answer = await runner.cancel("learned advice retired"); else if (!current?.running) answer = { confirmed: true, terminal: true }; } catch { /* saved intent remains actionable */ }
+    if (entry) ctx.state.update(id, { learning_revocation: { reason, freshSessionRequired: true, cancellation: answer, at: new Date().toISOString() } });
+    outcomes.push({ id, cancellation: answer, freshSessionRequired: true });
+  }
+  return outcomes;
+}
+
+export function learningPaths(entry, paths = []) {
+  const selected = new Set();
+  for (const path of [...paths, ...(entry.learning?.paths || []), ...(entry.sources || []), entry.prd].filter(Boolean)) {
+    try { selected.add(literalPath(path)); } catch { continue; }
+    if (selected.size >= 200) break;
+  }
+  return [...selected].sort();
+}
+
+export async function learningInput(ctx, id, entry, input) {
+  const service = ctx.learning || ctx.learningFor?.();
+  if (!service) return input;
+  const repo = service.identityFor(entry.repo);
+  if (!repo) return input;
+  const previous = entry.learning ?? ctx.state?.get?.(id)?.learning ?? null;
+  const mode = service.mode(repo);
+  if (mode !== "apply" && !previous?.rules?.length) return input;
+  // Recheck immutable GitHub identity; a cached renamed/replaced owner/name is
+  // navigation, never authority for delivering old repository content.
+  if (mode === "apply") {
+    const actual = await service.resolveRepo(entry.repo);
+    if (hash(actual) !== hash(repo)) throw learningError("REPOSITORY", "repository identity changed; foreign learning cannot be delivered");
+  }
+  const paths = learningPaths(entry, input.paths);
+  if (paths.length) input = { ...input, paths };
+  // Pin an empty snapshot locally when disabled. A concurrent enable cannot
+  // cause unchecked repository content to enter this offline clearing attempt.
+  const snapshot = mode !== "apply"
+    ? { section: "", delivered: false, freshSessionRequired: !!previous?.rules?.length, mode }
+    : await service.context(repo, { operationId: input.operationId, profile: entry.harness, paths, inputDigest: hash(input), previous, taskId: id });
+  if (snapshot.freshSessionRequired && entry.session) throw learningError("CONTINUITY", "retired/disabled advice remains in native session memory; use resume --fresh-session after the prior run settles; code, PR and task state were preserved");
+  return { ...input, prompt: input.prompt + (snapshot.section ? "\n\n" + snapshot.section : ""), learning: { ...snapshot, repo, paths }, managedInputDigest: hash({ ...input, advice: snapshot.section || "" }) };
+}
+
+export async function learningDispatch(ctx, id, input, launch) {
+  if (!input.learning?.key) return launch();
+  const service = ctx.learning || ctx.learningFor?.();
+  let attempted = false;
+  try {
+    if (!service?.dispatch) throw learningError("UNQUALIFIED", "learning dispatch admission unavailable; nothing launched");
+    return await service.dispatch(input.learning.repo, { key: input.learning.key, taskId: id, contextDigest: input.learning.contextDigest }, () => { attempted = true; return launch(); });
+  } catch (error) {
+    if (!attempted) error.dispatchNotSent = true;
+    throw error;
+  }
+}
+
+// Save this patch atomically with accepted-run ownership. The registry outbox
+// survives learning-store locks, process restarts, and later accepted attempts.
+export function learningDeliveryPatch(entry, input, job) {
+  if (!input.learning || !job?.id || (job.execution && job.execution.acceptance !== "accepted")) return {};
+  const learning = { ...input.learning, rules: input.learning.rules || [], runId: job.id };
+  if (!input.learning.key) return { learning };
+  const delivery = { repo: input.learning.repo, key: input.learning.key, runId: job.id };
+  const key = hash(delivery);
+  return { learning, learning_deliveries: { ...entry?.learning_deliveries, [key]: delivery } };
+}
+
+export async function learningDelivered(ctx, id) {
+  // Reporting must never undo or obscure provider acceptance. Successful writes
+  // are idempotent if the process dies before removing the registry outbox item.
+  try {
+    for (const [key, delivery] of Object.entries(ctx.state.get(id)?.learning_deliveries || {}).slice(0, 10)) {
+      const service = ctx.learning || ctx.learningFor?.();
+      const snapshot = await service.delivered(delivery.repo, delivery.key, delivery.runId);
+      // Retirement may have won after acceptance but before registry ownership.
+      // Keep the outbox until controls have been reconciled against that ownership.
+      if (snapshot.revoked) {
+        const controls = await revokeLearningAttempts(ctx, { repo: delivery.repo, removed: snapshot.rules, reason: snapshot.revoked.reason });
+        if (controls.some(c => c.cancellation?.confirmed !== true)) throw learningError("CONTROL", "revoked delivery cancellation remains unconfirmed");
+      }
+      ctx.state.update(id, entry => {
+        const pending = { ...entry.learning_deliveries };
+        delete pending[key];
+        return { learning_deliveries: pending, ...(entry.last?.run === delivery.runId && entry.learning?.key === delivery.key
+          ? { learning: { ...snapshot, repo: delivery.repo } } : {}) };
+      });
+    }
+  } catch {
+    ctx.log?.warn(`${id}: learning delivery audit pending; accepted run retained`);
+  }
+}

package/lib/learning_qualification.mjs

@@ -0,0 +1,67 @@
+// Disposable OS-denial evidence, never a config boolean or production enrollment.
+// The current coding adapters do not launch through this outer profile. A passed
+// standalone probe therefore cannot qualify their production apply mode.
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readlinkSync, rmSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { verificationSandboxSpec } from "./verification_sandbox.mjs";
+import { execFileAsync } from "./gh.mjs";
+import { hash } from "./learning_data.mjs";
+
+const PROBE = `const fs=require('node:fs'),cp=require('node:child_process'),net=require('node:net');
+const paths=JSON.parse(process.argv[1]),namespace=process.argv[2]||'';
+if(namespace&&fs.readlinkSync('/proc/self/ns/net')===namespace)process.exit(49);
+for(const p of paths) {
+  for(const action of [()=>fs.readFileSync(p),()=>fs.writeFileSync(p,'changed')]) {
+    try {action();process.exit(41);} catch(e){if(!['EPERM','EACCES','ENOENT','EROFS'].includes(e.code))process.exit(42);}
+  }
+}
+try{fs.openSync('/dev/tty','r+');process.exit(43);}catch(e){if(!['EPERM','EACCES','ENXIO','ENOENT','ENODEV'].includes(e.code))process.exit(44);}
+try{cp.execFileSync('/usr/bin/sandbox-exec',['-p','(version 1)(allow default)','/bin/cat',paths[0]],{stdio:'pipe'});process.exit(45);}catch{}
+const s=net.connect({host:'127.0.0.1',port:9});s.on('connect',()=>process.exit(46));
+s.on('error',e=>{if(!['EPERM','EACCES'].includes(e.code)&&!(namespace&&['ENETUNREACH','EHOSTUNREACH','ECONNREFUSED'].includes(e.code)))process.exit(47);process.stdout.write('denied-key-trust-verifier-checkpoint-terminal-control');});
+setTimeout(()=>process.exit(48),2000).unref();`;
+
+export async function probeLearningIsolation({ exec = execFileAsync } = {}) {
+  const dir = mkdtempSync(join(realpathSync(tmpdir()), "learning-isolation-"));
+  try {
+    const worktree = join(dir, "worker"), home = join(dir, "empty-home"), protectedDir = join(dir, "protected");
+    for (const p of [worktree, home, protectedDir]) mkdirSync(p, { mode: 0o700 });
+    const canaries = ["private-key", "public-trust", "active-store", "checkpoint", "verifier"].map(name => join(protectedDir, name));
+    for (const p of canaries) writeFileSync(p, "disposable-canary", { mode: 0o600 });
+    const spec = verificationSandboxSpec({ worktree, home, env: { HOME: home, LANG: "C" } });
+    const namespace = spec.driver === "bubblewrap" ? readlinkSync("/proc/self/ns/net") : "";
+    const result = await exec(spec.cmd, [...spec.args, spec.node, "-e", PROBE, JSON.stringify(canaries), namespace], { env: spec.env, cwd: worktree, timeout: 5000, maxBuffer: 4096 });
+    if (result.stdout !== "denied-key-trust-verifier-checkpoint-terminal-control" || canaries.some(p => readFileSync(p, "utf8") !== "disposable-canary")) throw new Error("denial probes failed");
+    return { qualified: false, status: "UNQUALIFIED", standaloneProbe: "passed", platform: process.platform, driver: spec.driver, profileDigest: hash({ cmd: spec.cmd, args: spec.args, node: spec.node }), output: result.stdout, reason: "disposable offline OS profile passed; installed coding adapters are not enclosed by it", remedy: "integrate and qualify the exact installed worker/extractor launch and privileged/control routes before production apply" };
+  } catch (e) {
+    return { qualified: false, status: "UNQUALIFIED", platform: process.platform, standaloneProbe: "failed", reason: String(e.stderr || e.message).slice(0, 2048), remedy: "macOS must permit sandbox-exec; Linux needs /usr/bin/bwrap and working user/PID/network namespaces; run from the operator terminal" };
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+}
+
+// The live ceremony owns these disposable directories and launches every probe
+// through the very same compiled profile. It is never returned by config or the
+// installed coordinator's learningFor factory.
+export function disposableLearningProfile(dir, { exec = execFileAsync } = {}) {
+  const worktree = join(dir, "worker"), home = join(dir, "empty-home"), protectedDir = join(dir, "protected");
+  for (const p of [worktree, home, protectedDir]) mkdirSync(p, { mode: 0o700 });
+  const paths = ["private-key", "public-trust", "active-store", "checkpoint", "verifier"].map(name => join(protectedDir, name));
+  for (const path of paths) writeFileSync(path, "disposable-canary", { mode: 0o600 });
+  const spec = verificationSandboxSpec({ worktree, home, env: { HOME: home, LANG: "C" } });
+  const namespace = spec.driver === "bubblewrap" ? readlinkSync("/proc/self/ns/net") : "";
+  return {
+    worktree, home, protectedDir,
+    async qualify() {
+      const result = await exec(spec.cmd, [...spec.args, spec.node, "-e", PROBE, JSON.stringify(paths), namespace], { env: spec.env, cwd: worktree, timeout: 5000, maxBuffer: 4096 });
+      if (result.stdout !== "denied-key-trust-verifier-checkpoint-terminal-control" || paths.some(p => readFileSync(p, "utf8") !== "disposable-canary")) throw new Error("disposable live authority boundary failed");
+      return { qualified: true, disposableOnly: true, status: "disposable offline profile passed", driver: spec.driver, profileDigest: hash({ cmd: spec.cmd, args: spec.args, node: spec.node }), observed: result.stdout };
+    },
+    async consume(snapshot) {
+      const program = `const s=JSON.parse(process.argv[1]),c=require('node:crypto');const digest=c.createHash('sha256').update(s.section).digest('hex');if(digest!==s.contextDigest)process.exit(51);process.stdout.write(JSON.stringify({contextDigest:digest,bundleDigest:s.bundleDigest,rules:s.rules}));`;
+      const result = await exec(spec.cmd, [...spec.args, spec.node, "-e", program, JSON.stringify(snapshot)], { env: spec.env, cwd: worktree, timeout: 5000, maxBuffer: 4096 });
+      const consumed = JSON.parse(result.stdout);
+      if (consumed.contextDigest !== snapshot.contextDigest || consumed.bundleDigest !== snapshot.bundleDigest) throw new Error("live worker consumed different context bytes");
+      return { runId: `disposable-live-${hash(result.stdout).slice(0, 24)}`, consumed };
+    },
+  };
+}

package/lib/learning_signer.mjs

@@ -0,0 +1,151 @@
+// OpenSSH owns cryptography and passphrase entry. No secret enters Node or its logs.
+import { execFileSync, spawnSync } from "node:child_process";
+import { readFileSync, lstatSync, mkdtempSync, writeFileSync, rmSync, openSync, closeSync, realpathSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { safePath, inside } from "./learning_store.mjs";
+import { hash, canonical, learningError, closed, textField } from "./learning_data.mjs";
+
+export const NAMESPACE = "gallivant-learning-v1";
+export const SIGNER_ID = "learning-operator";
+export const signingEnvironment = home => ({ PATH: "/usr/bin:/bin", HOME: home, LANG: "C", LC_ALL: "C", SSH_ASKPASS_REQUIRE: "never" });
+export function pinnedExecutable(path, forbidden = []) {
+  safePath(path, { file: true });
+  const s = lstatSync(path);
+  const trustedOwner = stat => stat.uid === 0 || stat.uid === process.getuid?.();
+  const unsafe = () => learningError("SIGNER", "ssh-keygen and its ancestors must be root/operator-owned and protected from directory replacement outside worker writes");
+  if (!trustedOwner(s) || !(s.mode & 0o111) || (s.mode & 0o022) || forbidden.some(root => inside(path, root))) throw unsafe();
+  // File permissions do not prevent rename/unlink through a writable parent.
+  // Permit the fixed system temporary root (not environment-selected TMPDIR)
+  // as a root-owned sticky ancestor only above a private trusted
+  // directory: sticky semantics protect that directory's entry, and its own
+  // permissions protect everything below it. Never permit a writable parent of
+  // the executable itself. Same-UID workers still require outer isolation.
+  let child = s;
+  for (let current = dirname(path);; current = dirname(current)) {
+    const parent = lstatSync(current);
+    const protectedTemporaryAncestor = parent.uid === 0 && (parent.mode & 0o1000) && current === realpathSync("/tmp") && child.isDirectory() && trustedOwner(child) && !(child.mode & 0o077);
+    if (!parent.isDirectory() || !trustedOwner(parent) || ((parent.mode & 0o022) && !protectedTemporaryAncestor)) throw unsafe();
+    if (current === dirname(current)) break;
+    child = parent;
+  }
+  return { path, digest: hash(readFileSync(path)) };
+}
+export function encryptedKey(path) {
+  safePath(dirname(path), { privateMode: true }); safePath(path, { file: true, privateMode: true });
+  if (lstatSync(path).nlink !== 1 || lstatSync(path).size > 32 * 1024) throw learningError("KEY", "unsafe private key file");
+  const pem = readFileSync(path, "utf8");
+  if (!/^-----BEGIN OPENSSH PRIVATE KEY-----\n[A-Za-z0-9+/=\n]+-----END OPENSSH PRIVATE KEY-----\n?$/.test(pem)) throw learningError("KEY", "expected encrypted OpenSSH key");
+  const b = Buffer.from(pem.trim().split("\n").slice(1, -1).join(""), "base64");
+  let pos = 15;
+  const take = () => { if (pos + 4 > b.length) throw learningError("KEY", "truncated private key"); const n = b.readUInt32BE(pos); pos += 4; if (n > b.length - pos) throw learningError("KEY", "truncated key field"); const v = b.subarray(pos, pos + n); pos += n; return v; };
+  if (!b.subarray(0, 15).equals(Buffer.from("openssh-key-v1\0"))) throw learningError("KEY", "unknown private key format");
+  const cipher = take().toString(), kdf = take().toString(), options = take();
+  if (!["aes256-ctr", "aes256-cbc", "aes256-gcm@openssh.com", "chacha20-poly1305@openssh.com"].includes(cipher) || kdf !== "bcrypt" || options.length < 8) throw learningError("KEY", "private key must be passphrase encrypted with bcrypt");
+  const saltLength = options.readUInt32BE(0);
+  if (saltLength < 16 || saltLength + 8 !== options.length || options.readUInt32BE(4 + saltLength) < 100) throw learningError("KEY", "private key requires bcrypt rounds >= 100");
+  if (pos + 4 > b.length || b.readUInt32BE(pos) !== 1) throw learningError("KEY", "expected one dedicated key"); pos += 4;
+  const pub = take();
+  if (pub.length !== 51 || pub.readUInt32BE(0) !== 11 || pub.subarray(4, 15).toString() !== "ssh-ed25519" || pub.readUInt32BE(15) !== 32) throw learningError("KEY", "expected Ed25519 key");
+  const privatePayload = take();
+  if (!privatePayload.length || pos !== b.length) throw learningError("KEY", "invalid encrypted payload");
+  return { publicKey: `ssh-ed25519 ${pub.toString("base64")}`, fingerprint: "SHA256:" + Buffer.from(hash(pub), "hex").toString("base64").replace(/=+$/, "") };
+}
+export function validateAuthority(a) {
+  closed(a, ["version", "id", "namespace", "identity", "publicKey", "fingerprint", "signer", "keyPath", "enrollment", "signature"], "authority");
+  if (a.version !== 1 || a.namespace !== NAMESPACE || a.identity !== SIGNER_ID || !/^[a-f0-9-]{36}$/.test(a.id) || !/^ssh-ed25519 [A-Za-z0-9+/]{68}$/.test(a.publicKey)) throw learningError("TRUST", "invalid enrolled authority");
+  const blob = Buffer.from(a.publicKey.split(" ")[1], "base64");
+  if (a.fingerprint !== "SHA256:" + Buffer.from(hash(blob), "hex").toString("base64").replace(/=+$/, "")) throw learningError("TRUST", "enrolled key fingerprint differs");
+  closed(a.signer, ["path", "digest"], "pinned signer");
+  textField(a.fingerprint, "fingerprint", 80);
+  return a;
+}
+export function openSshSigner({ executable = "/usr/bin/ssh-keygen", forbidden = [] } = {}) {
+  const pinned = () => pinnedExecutable(executable, forbidden);
+  const unchanged = authority => {
+    validateAuthority(authority);
+    if (canonical(pinned()) !== canonical(authority.signer)) throw learningError("TRUST", "pinned signer changed; requalification required");
+  };
+  const temporary = fn => {
+    const dir = mkdtempSync(join(realpathSync(tmpdir()), "learning-sshsig-"));
+    try { return fn(dir); } finally { rmSync(dir, { recursive: true, force: true }); }
+  };
+  const verify = (bytes, signature, authority) => {
+    unchanged(authority);
+    if (typeof signature !== "string" || signature.length > 8192 || !signature.startsWith("-----BEGIN SSH SIGNATURE-----\n")) throw learningError("SIGNATURE", "invalid SSHSIG encoding");
+    return temporary(dir => {
+      const allowed = join(dir, "allowed_signers"), sig = join(dir, "manifest.sig");
+      writeFileSync(allowed, `${SIGNER_ID} namespaces="${NAMESPACE}" ${authority.publicKey}\n`, { flag: "wx", mode: 0o600 });
+      writeFileSync(sig, signature, { flag: "wx", mode: 0o600 });
+      try { execFileSync(executable, ["-Y", "verify", "-f", allowed, "-I", SIGNER_ID, "-n", NAMESPACE, "-s", sig], { env: signingEnvironment(dir), input: bytes, stdio: ["pipe", "pipe", "pipe"], timeout: 10_000, maxBuffer: 8192 }); }
+      catch { throw learningError("SIGNATURE", "OpenSSH authorization verification failed"); }
+      return true;
+    });
+  };
+  const terminal = () => {
+    if (!process.stdin.isTTY || !process.stdout.isTTY || !process.stderr.isTTY) throw learningError("TERMINAL", "setup/approval requires the operator's interactive terminal");
+    let fd; try { fd = openSync("/dev/tty", "r+"); } catch { throw learningError("TERMINAL", "no controlling operator terminal"); } finally { if (fd !== undefined) closeSync(fd); }
+  };
+  return {
+    pinned, verify, terminal,
+    probe() {
+      pinned();
+      return temporary(dir => {
+        const key = join(dir, "disposable"), data = join(dir, "probe");
+        const env = signingEnvironment(dir);
+        try {
+          // Only this capability probe uses a disposable unencrypted key; it is never enrolled.
+          execFileSync(executable, ["-q", "-t", "ed25519", "-N", "", "-f", key], { env, timeout: 10_000 });
+          writeFileSync(data, "capability-probe", { mode: 0o600 });
+          execFileSync(executable, ["-Y", "sign", "-f", key, "-n", NAMESPACE, data], { env, stdio: "pipe", timeout: 10_000 });
+          const pub = readFileSync(key + ".pub", "utf8").split(" ").slice(0, 2).join(" ");
+          const allowed = join(dir, "allowed"); writeFileSync(allowed, `${SIGNER_ID} ${pub}\n`, { mode: 0o600 });
+          execFileSync(executable, ["-Y", "verify", "-f", allowed, "-I", SIGNER_ID, "-n", NAMESPACE, "-s", data + ".sig"], { env, input: "capability-probe", stdio: "pipe", timeout: 10_000 });
+          return { sign: true, verify: true, signer: pinned(), platform: process.platform };
+        } catch { throw learningError("SIGNER", "OpenSSH -Y sign/verify capability probe failed; install portable OpenSSH with SSHSIG support"); }
+      });
+    },
+    createKey(keyPath) {
+      terminal(); pinned(); safePath(dirname(keyPath), { privateMode: true });
+      // Refuse every existing target, including dangling links.
+      for (const path of [keyPath, keyPath + ".pub"]) { let exists = false; try { lstatSync(path); exists = true; } catch (e) { if (e.code !== "ENOENT") throw e; } if (exists) throw learningError("KEY", "refusing to overwrite key files"); }
+      const r = spawnSync(executable, ["-t", "ed25519", "-a", "100", "-f", keyPath, "-C", "dedicated-learning-approval"], { env: signingEnvironment(dirname(keyPath)), stdio: "inherit", timeout: 180_000 });
+      if (r.status !== 0) throw learningError("CANCELLED", "key creation cancelled or failed; no enrollment was written");
+      return encryptedKey(keyPath);
+    },
+    sign(bytes, authority) {
+      terminal(); unchanged(authority);
+      const key = encryptedKey(authority.keyPath);
+      if (key.publicKey !== authority.publicKey || key.fingerprint !== authority.fingerprint) throw learningError("TRUST", "private key differs from enrolled signer");
+      return temporary(dir => {
+        const manifest = join(dir, "manifest"); writeFileSync(manifest, bytes, { flag: "wx", mode: 0o400 });
+        const r = spawnSync(executable, ["-Y", "sign", "-f", authority.keyPath, "-n", NAMESPACE, manifest], { env: signingEnvironment(dir), stdio: ["ignore", "inherit", "inherit"], timeout: 120_000 });
+        if (r.status !== 0) throw learningError("CANCELLED", "signing cancelled, timed out or failed; active state unchanged");
+        if (readFileSync(manifest, "utf8") !== bytes) throw learningError("SIGNATURE", "frozen manifest changed during signing");
+        const signature = readFileSync(manifest + ".sig", "utf8"); verify(bytes, signature, authority); return signature;
+      });
+    },
+  };
+}
+
+
+// Resolve only when cryptographic operations are needed: local collection and
+// emergency disable must not depend on a working signer installation.
+export function storedOpenSshSigner(store, { executable } = {}) {
+  let selected;
+  const resolveSigner = () => {
+    const authority = store.readAuthority();
+    if (authority) {
+      validateAuthority(authority);
+      if (canonical(authority.enrollment?.signer) !== canonical(authority.signer)) throw learningError("TRUST", "enrollment signer differs from trust root");
+    }
+    const recorded = authority?.signer ?? store.readEnrollment()?.signer;
+    if (recorded) closed(recorded, ["path", "digest"], "pinned signer");
+    selected ??= openSshSigner({ executable: executable ?? recorded?.path ?? "/usr/bin/ssh-keygen" });
+    // Includes doctor/probe and terminal checks, before any selected executable
+    // can run. Never silently adopt changed bytes or fall back to another binary.
+    if (recorded && canonical(selected.pinned()) !== canonical(recorded)) throw learningError("TRUST", "pinned signer changed; requalification required");
+    return selected;
+  };
+  return Object.fromEntries(["pinned", "verify", "terminal", "probe", "createKey", "sign"].map(name => [name, (...args) => resolveSigner()[name](...args)]));
+}

package/lib/learning_store.mjs

@@ -0,0 +1,88 @@
+import { join, dirname, resolve, isAbsolute } from "node:path";
+import { existsSync, lstatSync, realpathSync, mkdirSync, openSync, closeSync, readFileSync, writeFileSync, renameSync, fsyncSync, rmSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { acquireProcessLock } from "./daemon.mjs";
+import { canonical, hash, parseJson, learningError, repository, closed } from "./learning_data.mjs";
+
+export const inside = (path, root) => path === root || path.startsWith(root + "/");
+export function safePath(path, { file = false, privateMode = false } = {}) {
+  if (typeof path !== "string" || Buffer.byteLength(path) > 4096 || /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/u.test(path)) throw learningError("PATH", "learning path contains terminal controls or exceeds its bound");
+  if (!isAbsolute(path) || resolve(path) !== path) throw learningError("PATH", "path must be explicit, absolute and normalized");
+  // Resolve system /tmp aliases at the caller, never silently follow a user-controlled link.
+  let current = path;
+  while (current !== dirname(current)) {
+    if (existsSync(current) || (() => { try { lstatSync(current); return true; } catch { return false; } })()) {
+      const s = lstatSync(current);
+      if (s.isSymbolicLink()) throw learningError("PATH", "symlink in learning path");
+      if (current === path && (file ? !s.isFile() : !s.isDirectory())) throw learningError("PATH", "wrong learning path type");
+      if (current === path && privateMode && ((s.mode & 0o077) || s.uid !== process.getuid?.())) throw learningError("PATH", "learning path must be operator-owned and private");
+    }
+    current = dirname(current);
+  }
+  return path;
+}
+export function durableWrite(file, value) {
+  safePath(dirname(file)); safePath(file, { file: true });
+  const bytes = canonical(value) + "\n";
+  if (Buffer.byteLength(bytes) > 32 * 1024 * 1024) throw learningError("STORAGE", "learning state exceeds its 32 MiB cap; preserve current state and review retention before retrying");
+  const tmp = `${file}.${randomUUID()}.tmp`;
+  let fd;
+  try {
+    fd = openSync(tmp, "wx", 0o600); writeFileSync(fd, bytes); fsyncSync(fd); closeSync(fd); fd = undefined;
+    renameSync(tmp, file); const dir = openSync(dirname(file), "r"); try { fsyncSync(dir); } finally { closeSync(dir); }
+  }
+  catch (e) { if (fd !== undefined) closeSync(fd); throw e; }
+  finally { rmSync(tmp, { force: true }); }
+}
+export function learningStore(root) {
+  safePath(root);
+  const loadFile = file => { safePath(file, { file: true, privateMode: true }); return parseJson(readFileSync(file), 32 * 1024 * 1024); };
+  const init = () => { safePath(root); mkdirSync(root, { recursive: true, mode: 0o700 }); safePath(root, { privateMode: true }); };
+  const repoPath = repo => { repository(repo); return join(root, `repo-${hash(repo)}.json`); };
+  const empty = repo => ({ version: 1, repo, mode: "off", modeGeneration: null, observations: {}, candidates: {}, scans: [], backoffUntil: null, extraction: [], deliveries: {}, sequence: 0, parent: null, active: [], transitions: {}, prepared: {}, preparationHistory: {}, checkpoint: null });
+  const load = repo => {
+    const path = repoPath(repo);
+    if (!existsSync(path)) return empty(repo);
+    const state = loadFile(path);
+    // Legacy stores have no obsolete-preparation archive; reading remains free
+    // of writes, including report and dry-run collection.
+    if (!Object.hasOwn(state, "preparationHistory")) state.preparationHistory = {};
+    if (!Object.hasOwn(state, "modeGeneration")) state.modeGeneration = null;
+    closed(state, Object.keys(empty(repo)), "repository state");
+    if (state.modeGeneration !== null && !/^[a-f0-9-]{36}$/.test(state.modeGeneration)) throw learningError("STATE", "invalid learning mode generation");
+    if (state.version !== 1 || canonical(state.repo) !== canonical(repo)) throw learningError("STATE", "repository state identity/schema mismatch");
+    if (!["off", "collect", "apply"].includes(state.mode)) throw learningError("STATE", "invalid protected learning mode");
+    return state;
+  };
+  const lock = () => {
+    init();
+    const path = join(root, "operation.lock");
+    safePath(path, { file: true, privateMode: true });
+    return acquireProcessLock(path, "learning operation").release;
+  };
+  return {
+    root, load, init, lock,
+    identities() { const p = join(root, "repositories.json"); return existsSync(p) ? loadFile(p) : {}; },
+    remember(name, repo, visibility) {
+      repository(repo);
+      if (visibility !== undefined && !["public", "private", "internal", "unknown"].includes(visibility)) throw learningError("INPUT", "invalid repository visibility");
+      const release = lock();
+      try {
+        const known = this.identities(), previous = known[name.toLowerCase()];
+        if (previous && canonical(repository(previous.repo ?? previous)) !== canonical(repo)) throw learningError("REPOSITORY", "repository identity changed; refusing to replace remembered identity");
+        known[name.toLowerCase()] = visibility === undefined ? repo : { repo, visibility }; durableWrite(join(root, "repositories.json"), known);
+      }
+      finally { release(); }
+    },
+    readEnrollment() { const p = join(root, "enrollment-intent.json"); return existsSync(p) ? loadFile(p) : null; },
+    writeEnrollment(value) { init(); durableWrite(join(root, "enrollment-intent.json"), value); },
+    readAuthority() { const p = join(root, "authority.json"); return existsSync(p) ? loadFile(p) : null; },
+    writeAuthority(value) { init(); durableWrite(join(root, "authority.json"), value); },
+    async transaction(repo, fn) {
+      const release = lock();
+      try { const state = load(repo), result = await fn(state); durableWrite(repoPath(repo), state); return result; } finally { release(); }
+    },
+    saveLocked(repo, state) { durableWrite(repoPath(repo), state); },
+    canonicalRoot() { return existsSync(root) ? realpathSync(root) : root; },
+  };
+}

package/lib/log.mjs

@@ -0,0 +1,53 @@
+// Logging: stderr for the terminal, plus errors.log on disk so `status` can show the newest problem when nobody
+// was watching the terminal. The file is rotated at 1 MB and its last line is read from the tail, not the whole file.
+import { join } from "node:path";
+import { openSync, readSync, fstatSync, closeSync, renameSync } from "node:fs";
+import { appendLine, fileMode } from "./fs.mjs";
+import { nowIso } from "./time.mjs";
+
+const MAX_BYTES = 1_000_000;
+
+export function makeLog(home, { stream = process.stderr, clock = Date } = {}) {
+  const file = join(home, "errors.log");
+  const line = (level, msg) => `${nowIso(clock)} ${level} ${msg}`;
+  // Recording is best effort on purpose. The log is a convenience for `status` to show the newest problem when
+  // nobody was watching the terminal; the terminal write above is the report that matters and has already happened.
+  // A sandboxed harness, a read-only home or a full disk must not turn a warning into a failed command: `ready` had
+  // already printed its verdict and done its work when this threw, and the operator saw a crash instead of a result.
+  // Once per process is enough of a notice, since a home that cannot be written stays that way for the whole run.
+  let warned = false;
+  const record = l => {
+    try {
+      if (fileSize(file) > MAX_BYTES) renameSync(file, file + ".1");
+    } catch { /* no file yet, or it cannot be rotated; the append below decides whether that matters */ }
+    try {
+      appendLine(file, l);
+    } catch (e) {
+      if (!warned) { warned = true; stream.write(`${line("warn", `cannot write ${file} (${e.code || e.message}); logging to this terminal only`)}\n`); }
+    }
+  };
+  return {
+    info: msg => stream.write(line("info", msg) + "\n"),
+    warn: msg => { stream.write(line("warn", msg) + "\n"); record(line("warn", msg)); },
+    error: msg => { stream.write(line("error", msg) + "\n"); record(line("error", msg)); },
+    /** Newest recorded problem, for the status header. Reads only the tail of the file, and never throws. */
+    latest: () => { try { return lastLine(file); } catch { return null; } },
+  };
+}
+
+const fileSize = p => { const fd = openSync(p, "r"); try { return fstatSync(fd).size; } finally { closeSync(fd); } };
+
+function lastLine(p) {
+  if (fileMode(p) === null) return null;
+  const fd = openSync(p, "r");
+  try {
+    const size = fstatSync(fd).size;
+    const len = Math.min(size, 4096);
+    const buf = Buffer.alloc(len);
+    readSync(fd, buf, 0, len, size - len);
+    const lines = buf.toString("utf8").trim().split("\n").filter(Boolean);
+    return lines.at(-1) || null;
+  } finally { closeSync(fd); }
+}
+
+export const silentLog = { info() {}, warn() {}, error() {}, latest: () => null };