@uchibeke/gallivant 0.0.0-stage → 0.2.1

package/bin/gallivant.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+// CLI entry. Parses arguments, builds the context, calls one command. No logic lives here.
+import { acquireCliMutation } from "../lib/daemon.mjs";
+import { parseArgs } from "node:util";
+import { makeContext } from "../lib/context.mjs";
+import { start } from "../lib/commands/start.mjs";
+import { register } from "../lib/commands/register.mjs";
+import { up, upInBackground, readDaemon, down } from "../lib/commands/up.mjs";
+import { status } from "../lib/commands/status.mjs";
+import { why } from "../lib/commands/why.mjs";
+import { doctor, renderDoctor } from "../lib/commands/doctor.mjs";
+import { diagnoseNetwork, renderNetworkDiagnostics } from "../lib/network_diagnostics.mjs";
+import { ready } from "../lib/commands/ready.mjs";
+import { newPrd } from "../lib/commands/new.mjs";
+import { resume } from "../lib/commands/resume.mjs";
+import { startServices } from "../lib/commands/start_services.mjs";
+import { trackerPort, stopTracker } from "../lib/tracker_process.mjs";
+import { init, renderInit } from "../lib/commands/init.mjs";
+import { VERSION } from "../lib/fs.mjs";
+import { hasConfig } from "../lib/config.mjs";
+import { resolveHandle } from "../lib/state.mjs";
+import { requestControl } from "../lib/control.mjs";
+import { queueChain, retryChain, cancelChain, renderChains } from "../lib/chains.mjs";
+import { taskCommand, renderTask } from "../lib/commands/task.mjs";
+import { TASK_VERSION } from "../lib/tasks.mjs";
+import { learnCommand } from "../lib/commands/learn.mjs";
+import { safeDisplay } from "../lib/learning_data.mjs";
+
+const HELP = `gallivant: give an agent a task, let the review loop run, go outside.
+
+  gallivant init [--harness codex|claude] [--worktrees <directory>]
+                                         set up the repository you are in: private config, this repo in repos,
+                                         then doctor's report. Safe to repeat; never signs in or overwrites settings
+  gallivant --version                    print the installed version
+  gallivant doctor [--send] [--probe]   install checklist and health probe
+  gallivant doctor --network <https-origin> [--json]   bounded DNS/HTTPS diagnosis
+  gallivant learn [--repo owner/repo] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--dry-run]
+                                         bounded historical feedback collection; independent coding cursor
+  gallivant learn doctor [--repo owner/repo]
+  gallivant learn setup --key-path <absolute-path> [--ssh-keygen /usr/bin/ssh-keygen]
+                                         explicit interactive encrypted-key enrollment; isolation required
+  gallivant learn configure --repo owner/repo --mode off|collect|apply
+  gallivant learn list|report --repo owner/repo [--status pending]
+  gallivant learn show|approve|retire|reject <id> --repo owner/repo --revision <SHA256> [--reason text]
+  gallivant learn revise <id> --repo owner/repo --from reviewed-rule.json
+  gallivant learn explain --repo owner/repo --run RUN_ID
+  gallivant learn recover|prune --repo owner/repo
+  gallivant learn extract --repo owner/repo --learning-budget <USD>
+                                         data-only qualified profile required; list/report never infer
+  gallivant new <name> [--harness <name>] [--dir <repo>]
+                                         write a starting PRD into docs/prds/ of the repo you are in
+  gallivant task [prepare] "<request>" [--stdin] [--dir <checkout>] [--repo <owner/repo>]
+                [--base <branch>] [--harness <name>] [--context <file>] [--request-id <id>] [--run] [--json]
+                [--completion-target delivery_ready|integrated] [--verify <command>] [--no-daemon]
+                                         prepare an isolated brief; --run authorizes its exact ready revision
+                                         Claude, Codex and OpenAI Agents support isolated preparation.
+                                         Other local harnesses use written PRDs; Codex Cloud dispatch is unavailable
+  gallivant task answer <task-id> --revision <n> --request-id <answer-id> --answer <question-id=text>
+                                         resume saved questions; --answer, --context and --verify may repeat
+  gallivant task inspect <task-id> [--json] | task list [--json]
+  gallivant task resume|validate|start <task-id> --revision <n> [--run] [--no-daemon] [--json]
+                                         shared versioned operations; start needs prior or --run authorization
+  gallivant ready <prd.md> [--check]     check the PRD against the contract; flip it to ready when it passes
+  gallivant start [prd.md] [--no-daemon] [--no-server] [--no-open] [--port 8791] [--base <branch>]
+                                         start the daemon and dashboard, then open it; optionally start a ready PRD
+                                         --base sets the branch the PR targets and remembers it for this repository
+  gallivant register <pr-url> [--harness <name>] [--session <id>] [--worktree <dir>]
+                                         watch a hand-made PR; on an existing entry, reset it
+  gallivant chain <name> <prd1.md> <prd2.md> ... [--base <branch>]
+                                         queue ready PRDs; each starts after the previous PR is merged
+  gallivant chain [<name>] [--cancel | --retry [--resnapshot]]
+                                         inspect chains, stop future work, or retry after fixing a blocker
+  gallivant up [--once]                  the daemon: recover from GitHub, then tick every poll_seconds
+  gallivant down                         stop the daemon and standalone dashboard; active runs keep going
+  gallivant status [--all] [--json]      needs-you, running, daemon health
+  gallivant serve [--port 8791] [--no-open] [--no-daemon] [--foreground]
+                                         same startup as start without a PRD; foreground keeps the tracker attached
+  gallivant why <handle>                 why a PR stopped; handle is <repo>#<pr>, a PRD path, or the id
+  gallivant resume <handle> [--note "..."] [--resnapshot] [--fresh-session]
+                                         put a stopped entry back to work in the session that was doing it;
+                                         --resnapshot makes an edited brief the one the gate judges
+                                         --fresh-session replaces retired learned memory after settlement
+  gallivant recheck <handle>           queue a PR recheck without resetting its budget
+  gallivant cancel <handle>            stop further dispatch; request provider cancellation
+  gallivant say <handle> --note "..." [--interrupt]
+                                         send an update in the same session; --interrupt stops the active run first
+  gallivant remove <handle>              forget an entry; the PR, the branch and the checkout are left alone
+
+Config: $GALLIVANT_HOME/config.json (default ~/.gallivant). Run doctor for the file to write.`;
+
+const OPTIONS = {
+  network: { type: "string" },
+  check: { type: "boolean" }, once: { type: "boolean" }, all: { type: "boolean" }, json: { type: "boolean" },
+  send: { type: "boolean" }, probe: { type: "boolean" }, help: { type: "boolean", short: "h" }, version: { type: "boolean", short: "v" },
+  "no-server": { type: "boolean" }, "no-open": { type: "boolean" }, foreground: { type: "boolean" }, worktrees: { type: "string" },
+  "no-daemon": { type: "boolean" }, note: { type: "string" }, resnapshot: { type: "boolean" }, "fresh-session": { type: "boolean" }, interrupt: { type: "boolean" },
+  base: { type: "string" }, harness: { type: "string" }, session: { type: "string" }, worktree: { type: "string" }, dir: { type: "string" }, port: { type: "string" },
+  cancel: { type: "boolean" }, retry: { type: "boolean" },
+  run: { type: "boolean" }, stdin: { type: "boolean" }, repo: { type: "string" }, revision: { type: "string" },
+  "request-id": { type: "string" }, context: { type: "string", multiple: true },
+  "completion-target": { type: "string" },
+  answer: { type: "string", multiple: true }, verify: { type: "string", multiple: true },
+  since: { type: "string" }, until: { type: "string" }, "dry-run": { type: "boolean" },
+  mode: { type: "string" }, status: { type: "string" }, from: { type: "string" }, reason: { type: "string" },
+  "key-path": { type: "string" }, "ssh-keygen": { type: "string" }, "learning-budget": { type: "string" },
+};
+
+async function dispatch(argv) {
+  const options = argv[0] === "learn" ? { ...OPTIONS, run: { type: "string" } } : OPTIONS;
+  const { values, positionals } = parseArgs({ args: argv, options, allowPositionals: true });
+  const [cmd, arg] = positionals;
+  if (values.version) { console.log(VERSION); return 0; }
+  if (values.help || !cmd || cmd === "help") { console.log(HELP); return 0; }
+  if (cmd === "init") {
+    if (arg) throw new Error("init takes no positional argument; run it from inside the target checkout");
+    const r = await init({ harness: values.harness, worktrees: values.worktrees });
+    const report = renderDoctor(r.doctor);
+    console.log(renderInit(r, report));
+    // Doctor's exit code, so a script or an agent reading only the status knows whether setup still has open items.
+    return report.exitCode;
+  }
+  if (values.foreground && cmd !== "serve") throw new Error("--foreground is available only with serve");
+  if (values.foreground && values["no-server"]) throw new Error("--foreground cannot be combined with --no-server");
+  // Validate before a PRD can dispatch paid work.
+  const serviceOptions = { port: ["start", "serve"].includes(cmd) ? trackerPort(values.port) : undefined,
+    noDaemon: values["no-daemon"], noServer: values["no-server"], noOpen: values["no-open"], foreground: values.foreground };
+  if (cmd === "learn") {
+    const ctx = makeContext({ needConfig: arg !== "setup" && (arg !== "doctor" || !!values.repo), readOnly: !!values["dry-run"] || ["list", "show", "report", "explain", "doctor"].includes(arg) });
+    const owner = !values["dry-run"] && !["list", "show", "report", "explain", "doctor", "setup"].includes(arg) ? acquireCliMutation(ctx.home) : null;
+    let result;
+    try { result = await learnCommand(ctx, { args: arg ? positionals.slice(1) : [], values }); }
+    finally { owner?.release(); }
+    process.stdout.write(safeDisplay(result) + "\n");
+    return result?.isolation?.qualified === false ? 1 : 0;
+  }
+
+  if (values.network && cmd !== "doctor") throw new Error("--network is available only with doctor");
+  if (cmd === "doctor" && values.network) {
+    const result = await diagnoseNetwork(values.network);
+    console.log(values.json ? JSON.stringify(result, null, 2) : renderNetworkDiagnostics(result));
+    return result.ok ? 0 : 1;
+  }
+  if (cmd === "doctor") { const r = renderDoctor(await doctor({ send: values.send, probe: values.probe })); console.log(r.text); return r.exitCode; }
+  if (cmd === "ready") {
+    if (!arg) throw new Error("ready needs a PRD path");
+    // A check only reads the brief and its sources. Recording readiness uses optional config; invalid config
+    // remains an error for that operation rather than silently selecting a local decision.
+    let readyCtx = {};
+    if (!values.check && hasConfig()) { const c = makeContext(); readyCtx = { config: c.config, apiKey: c.aportApiKey, log: c.log }; }
+    const r = await ready({ path: arg, checkOnly: values.check, ...readyCtx, onProgress: message => console.error(message) });
+    console.log(r.report);
+    return r.ok ? 0 : 1;
+  }
+
+  if (cmd === "task") {
+    try {
+      const ctx = makeContext();
+      const r = await taskCommand(ctx, { args: positionals.slice(1), values });
+      console.log(values.json ? JSON.stringify(r, null, 2) : renderTask(r));
+      return r.status === "blocked" || r.daemonError ? 1 : 0;
+    } catch (e) {
+      if (!values.json) throw e;
+      console.log(JSON.stringify({ version: TASK_VERSION, error: { code: e.code || "TASK_FAILED", message: e.message } }));
+      return 1;
+    }
+  }
+  const ctx = makeContext();
+  const mutating = ["start", "resume", "register", "remove", "recheck", "say", "cancel"].includes(cmd) || cmd === "chain" && (positionals.length > 2 || values.cancel || values.retry);
+  const owner = mutating ? acquireCliMutation(ctx.home) : null;
+  try {
+  if (cmd === "recheck" || cmd === "say" || cmd === "cancel") {
+    if (!arg) throw new Error(`${cmd} needs a handle`);
+    if (cmd === "say" && !values.note?.trim()) throw new Error("say needs --note with a message");
+    const r = requestControl(ctx, { handle: arg, action: cmd === "say" ? "message" : cmd, note: values.note, interrupt: values.interrupt });
+    console.log(`${r.entry}: ${r.action} queued; ${cmd === "cancel" ? "dispatch is fenced; the daemon will request and confirm cancellation" : r.interrupt ? "the daemon will stop the active run and resume its session with your message" : "it will wait for any active run to finish"}.`);
+    if (!values["no-daemon"]) {
+      try { await upInBackground(ctx); }
+      catch (e) { console.error(`Request saved, but the daemon could not start: ${e.message}\nAfter fixing the daemon, the saved request will be picked up; do not resend it.`); return 1; }
+    }
+    return 0;
+  }
+  switch (cmd) {
+    case "chain": {
+      const paths = positionals.slice(2);
+      const operation = paths.length > 0 || values.retry;
+      if (values.cancel && (values.retry || values.resnapshot || paths.length)) throw new Error("--cancel cannot be combined with a new plan or --retry");
+      if (values.resnapshot && !values.retry) throw new Error("chain --resnapshot requires --retry");
+      if (values.retry && paths.length) throw new Error("--retry uses the existing plan; do not pass PRD paths");
+      if ((values.cancel || values.retry) && !arg) throw new Error("a chain name is required");
+      if (values.base && !paths.length) throw new Error("--base is set when queuing a new chain");
+      if (paths.length) await queueChain(ctx, { name: arg, paths, base: values.base });
+      else if (values.cancel) cancelChain(ctx, arg);
+      else if (values.retry) await retryChain(ctx, { name: arg, resnapshot: values.resnapshot });
+      console.log(renderChains(ctx, arg));
+      if (operation && !values["no-daemon"]) {
+        try { await upInBackground(ctx); }
+        catch (e) { console.error(`Chain saved, but the daemon could not start: ${e.message}\nRun gallivant up after fixing it; do not queue the chain again.`); return 1; }
+      } else if (operation) console.log("Saved. Run gallivant up to dispatch the chain.");
+      return 0;
+    }
+    case "start":
+    case "serve": {
+      if (cmd === "serve" && arg) throw new Error("serve does not take a PRD; use gallivant start <prd.md>");
+      if (cmd === "start" && arg) {
+        const r = await start(ctx, { path: arg, base: values.base });
+        console.log(`${r.id}: started in ${r.worktree} on ${r.branch} -> ${r.base} (run ${r.run})`);
+        if (r.baseSource === "flag") console.log(`Base branch ${r.base} remembered for this repository; later starts here need no --base.`);
+        else if (r.baseSource === "config") console.log(`Base branch ${r.base} comes from repos in config.json.`);
+      }
+      const services = await startServices(ctx, serviceOptions);
+      for (const message of services.messages) console.log(message);
+      for (const error of services.errors) console.error(error);
+      return services.errors.length ? 1 : 0;
+    }
+    case "register": { if (!arg) throw new Error("register needs a PR URL"); const r = await register(ctx, { url: arg, harness: values.harness, session: values.session, worktree: values.worktree }); console.log(`${r.id}: watching PR #${r.pr} with ${r.harness}`); return 0; }
+    case "up": await up(ctx, { once: values.once }); return 0;
+    case "down": {
+      const tracker = stopTracker(ctx);
+      const r = down(ctx);
+      if (tracker.stopped) console.log(`Tracker ${tracker.pid} stopping.`);
+      if (!r.stopped && !tracker.stopped) { console.error(`${r.why}; ${tracker.why}`); return 1; }
+      if (r.stopped) console.log(`Daemon ${r.pid} stopping. Active runs keep going; gallivant start resumes monitoring.`);
+      if (tracker.unverified) { console.error(tracker.why); return 1; }
+      return 0;
+    }
+    case "status": { const r = status(ctx, { all: values.all, json: values.json }); console.log(r.text); return r.exitCode; }
+    case "new": {
+      if (!arg) throw new Error("new needs a name, for example: gallivant new widget-export");
+      const r = await newPrd(ctx, { name: arg, harness: values.harness, dir: values.dir });
+      console.log(`${r.rel}\n\nEdit it, then:\n  gallivant ready ${r.rel} --check\n  gallivant ready ${r.rel}\n  gallivant start ${r.rel}`);
+      return 0;
+    }
+    case "why": { if (!arg) throw new Error("why needs a handle"); console.log(why(ctx, { handle: arg })); return 0; }
+    case "resume": {
+      if (!arg) throw new Error("resume needs a handle: the id, a PRD path, or <repo>#<pr>");
+      const r = await resume(ctx, { handle: arg, note: values.note, resnapshot: values.resnapshot, freshSession: values["fresh-session"] });
+      console.log(`${r.handle}: resumed in ${r.worktree} (run ${r.run})${r.attach ? `\nby hand: ${r.attach}` : "\nProvider progress is recorded by the coordinator."}`);
+      // Printed because replacing the brief the gate judges is not something to do quietly, and the operator asked for it
+      // one command ago: what they see back is what they actually changed.
+      if (r.resnapshotted?.length) console.log(`\nThe brief was resnapshotted and the session was told what moved:\n${r.resnapshotted.map(l => `  - ${l}`).join("\n")}`);
+      if (!readDaemon(ctx.home)?.alive) {
+        try { const d = await upInBackground(ctx); console.log(d ? `\nDaemon running in the background (pid ${d.pid}).` : ""); }
+        catch (e) { console.log(`\nThe run started, but the daemon did not: ${e.message}\n  gallivant up`); }
+      }
+      return 0;
+    }
+    case "remove": { if (!arg) throw new Error("remove needs a handle"); const id = resolveHandle(ctx.state.entries(), arg); ctx.state.remove(id); console.log(`${id}: removed from the registry`); return 0; }
+    default: throw new Error(`unknown command "${cmd}"\n\n${HELP}`);
+  }
+  } finally { owner?.release(); }
+}
+
+async function main(argv) {
+  try { return await dispatch(argv); }
+  catch (e) {
+    if (argv[0] === "learn") e.message = safeDisplay({ error: { code: e.code || "LEARNING_FAILED", message: e.message } });
+    throw e;
+  }
+}
+
+main(process.argv.slice(2)).then(code => { process.exitCode = code; }, e => { console.error(`error: ${e.message}`); process.exitCode = 1; });

package/bin/package-plugin.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { buildPluginPackage, validatePublicRelease } from "../lib/plugin_package.mjs";
+try {
+  const { values } = parseArgs({ options: { config: { type: "string" }, out: { type: "string" }, "core-version": { type: "string" }, "source-commit": { type: "string" }, internal: { type: "boolean" }, "validate-public": { type: "boolean" } } });
+  if (!values.config) throw new Error("Pass --config with the APort endpoint, resource, publisher and asset inputs");
+  const config = JSON.parse(readFileSync(values.config, "utf8"));
+  if (values["validate-public"]) {
+    const result = validatePublicRelease(config); console.log(JSON.stringify(result, null, 2)); if (!result.ok) process.exitCode = 1;
+  } else {
+    if (!values.out) throw new Error("Pass --out with an empty artifact directory");
+    const manifest = buildPluginPackage({ config, out: values.out, coreVersion: values["core-version"], sourceCommit: values["source-commit"], internal: values.internal });
+    console.log(JSON.stringify({ classification: manifest.classification, coreSha256: manifest.coreSha256, hashes: manifest.hashes }, null, 2));
+  }
+} catch (error) { console.error(`${error.code || "PACKAGE_FAILED"}: ${error.message}`); process.exitCode = 1; }

package/bin/release-live.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Explicit opt-in entry point. Task execution stays in the existing G8 scripts.
+import { parseArgs } from 'node:util';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { readReleaseJson, verifyReleasePayload, evaluateRelease } from '../lib/release_package.mjs';
+try {
+  const { values } = parseArgs({ options: { out: { type: 'string' }, backend: { type: 'string' }, phase: { type: 'string', default: 'preflight' }, execute: { type: 'boolean' }, host: { type: 'boolean' } } });
+  if (!values.out) throw new Error('Supply --out for the exact installed candidate; no live action was taken');
+  const manifest = readReleaseJson(join(values.out, 'manifest.json'));
+  verifyReleasePayload(values.out, manifest);
+  const saved = readReleaseJson(join(values.out, 'qualification.json'));
+  const evidence = readReleaseJson(join(values.out, 'evidence.json'));
+  const result = evaluateRelease({ manifest, deployment: saved.deployment, evidence });
+  if (values.host) {
+    if (values.execute || values.backend) throw new Error('Host verification reads actual operator-captured observations; it does not simulate or dispatch a host session');
+    const ids = ['integration', 'deployment', 'host', 'recovery', 'reviewer', 'media'];
+    console.log(JSON.stringify({ kind: 'record-validation', actualHostExecution: false, checks: Object.fromEntries(ids.map(id => [id, result.checks[id]])), blockers: result.blockers.filter(item => ids.includes(item.id)) }, null, 2));
+    process.exitCode = ids.every(id => result.checks[id].status === 'passed') ? 0 : 1;
+  } else {
+    if (!['openai-agents', 'codex-cloud'].includes(values.backend) || !['preflight', 'implementation', 'correction'].includes(values.phase)) throw new Error('Select --backend openai-agents|codex-cloud and --phase preflight|implementation|correction');
+    if (values.execute && (!['implementation', 'correction'].includes(values.phase) || result.checks.integration.status !== 'passed' || result.checks.deployment.status !== 'passed')) throw new Error('Before paid phases, record qualified integration and human-approved deployment for this candidate; use preflight without --execute');
+    const script = fileURLToPath(new URL(`../test/${values.backend}-live.mjs`, import.meta.url));
+    const child = spawnSync(process.execPath, [script, `--phase=${values.phase}`, ...(values.execute ? ['--execute'] : [])], { stdio: 'inherit', env: process.env });
+    if (child.error) throw child.error;
+    process.exitCode = child.status ?? 1;
+  }
+} catch (error) { console.error(error.message); process.exitCode = 1; }

package/bin/release-package.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { join } from 'node:path';
+import { readReleaseJson, releasePreflight, assembleRelease, verifyReleasePayload, evaluateRelease } from '../lib/release_package.mjs';
+try {
+  const { values } = parseArgs({ options: { mode: { type: 'string', default: 'preflight' }, config: { type: 'string' }, setup: { type: 'string' }, evidence: { type: 'string' }, deployment: { type: 'string' }, out: { type: 'string' }, 'source-commit': { type: 'string' }, 'core-version': { type: 'string' }, internal: { type: 'boolean' } } });
+  let report;
+  if (values.mode === 'preflight') {
+    if (!values.config) throw new Error('Pass --config with the existing package configuration; keep private credentials outside it');
+    report = releasePreflight(readReleaseJson(values.config), values.setup ? readReleaseJson(values.setup) : {});
+  } else if (values.mode === 'build') {
+    if (!values.config || !values.out || !values.deployment) throw new Error('Build requires --config, --out and --deployment with the observed target revision and configuration digest');
+    report = assembleRelease({ config: readReleaseJson(values.config), out: values.out, deployment: readReleaseJson(values.deployment), evidence: values.evidence ? readReleaseJson(values.evidence) : undefined, coreVersion: values['core-version'], sourceCommit: values['source-commit'], internal: values.internal }).evaluation;
+  } else if (values.mode === 'validate') {
+    if (!values.out) throw new Error('Validate requires --out with the existing candidate directory');
+    const manifest = readReleaseJson(join(values.out, 'manifest.json'));
+    verifyReleasePayload(values.out, manifest);
+    const saved = readReleaseJson(join(values.out, 'qualification.json'));
+    report = evaluateRelease({ manifest, deployment: values.deployment ? readReleaseJson(values.deployment) : saved.deployment, evidence: readReleaseJson(values.evidence || join(values.out, 'evidence.json')) });
+  } else throw new Error('Use preflight, build or validate; this command never deploys, dispatches or publishes');
+  console.log(JSON.stringify(report, null, 2));
+  if (report.status !== 'submission-ready' && report.status !== 'prepared-unqualified') process.exitCode = 1;
+} catch (error) { console.error(error.message); process.exitCode = 1; }

package/bin/session-runtime.mjs

@@ -0,0 +1,13 @@
+import { appendFileSync } from "node:fs";
+import { sessionExports } from "../lib/runtime-environment.mjs";
+
+if (!process.env.CLAUDE_ENV_FILE) {
+  process.stderr.write("Gallivant runtime setup: CLAUDE_ENV_FILE unavailable; Node tool runtime is unverified.\n");
+  process.exitCode = 1;
+} else {
+  appendFileSync(process.env.CLAUDE_ENV_FILE, sessionExports(process.execPath, process.cwd()));
+  process.stdout.write(JSON.stringify({ hookSpecificOutput: {
+    hookEventName: "SessionStart",
+    additionalContext: `Selected tool runtime: ${process.execPath} (${process.platform}/${process.arch}, ${process.version}). The session environment prepends its directory to PATH for Bash commands. Before installing native dependencies, check node -p 'JSON.stringify({execPath:process.execPath,arch:process.arch,version:process.version})'. Native packages must match the Node process, not hardware architecture alone. If the selected runtime is inaccessible or differs, report the mismatch and blocked read; do not patch native packages, weaken the sandbox or change toolchains to conceal it.`,
+  } }));
+}

package/bin/task-delivery-state.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { checkRuntimeState, migrateRuntimeState, backupRuntimeState, restoreRuntimeState } from "../lib/runtime_state.mjs";
+try {
+  const { positionals, values } = parseArgs({ allowPositionals: true, options: { home: { type: "string" }, manifest: { type: "string" }, out: { type: "string" }, backup: { type: "string" } } });
+  if (!values.manifest || !values.home && positionals[0] !== "rollback") throw new Error("Pass --manifest runtime.json and --home the durable namespace");
+  const manifest = JSON.parse(readFileSync(values.manifest, "utf8"));
+  const fn = { check: checkRuntimeState, migrate: migrateRuntimeState, backup: backupRuntimeState, rollback: restoreRuntimeState }[positionals[0]];
+  if (!fn) throw new Error("Use check, migrate, backup or rollback (rollback needs --backup and fresh --out)");
+  console.log(JSON.stringify(fn({ ...values, manifest }), null, 2));
+} catch (error) { console.error(`${error.code || "RUNTIME_STATE"}: ${error.message}`); process.exitCode = 1; }

package/docs/README.md

@@ -0,0 +1,72 @@
+# Documentation
+
+Start with [installation and your first run](install.md): inside the target
+checkout, `npx --yes @uchibeke/gallivant init --harness codex` (or
+`--harness claude`) writes the config, records the repository and prints the
+setup report. Then choose how to describe the work. [Natural-language tasks](tasks.md) prepare a reviewable brief
+from your request; [hand-authored PRDs](prd.md) let you write that brief directly.
+Both use the same validation, execution, GitHub review and completion workflow.
+Code, research and documentation can all be delivered as verifiable repository
+changes. You do not need to write a PRD by hand, but every run needs clear
+requirements and checks.
+
+## Choose a guide
+
+| Need | Guide |
+| --- | --- |
+| Install, configure access and complete a first task | [Getting started](install.md) |
+| Ask an agent to inspect, install and verify setup | [Agent setup](agent-setup.md) |
+| Describe work, answer questions, inspect a draft and authorize execution | [Natural-language tasks](tasks.md) |
+| Write a brief with acceptance criteria, source files and verification commands | [PRD contract](prd.md) |
+| Find commands, monitor progress, message or resume a run | [Commands](commands.md) |
+| Configure repositories, credentials, harnesses and execution limits | [Configuration](config.md) |
+| Use the local dashboard and understand product boundaries | [Application](app.md) |
+| Run coding work on an API-backed hosted environment | [OpenAI Agents API](openai-agents.md) |
+| Understand the unavailable Codex Cloud dispatch and its required qualification | [Codex Cloud](codex-cloud.md) |
+| Queue dependent tasks with a human merge between steps | [Chains](chains.md) |
+| Understand permissions, credentials and completion checks | [Guardrails](guardrails.md) |
+| Keep Node, Git and dependency execution consistent | [Runtime environment](runtime-environment.md) |
+| Diagnose DNS/HTTPS failures and understand automatic recovery | [Network recovery](network-recovery.md) |
+| Collect review feedback and understand why learned-rule activation is unavailable | [Learning](learning.md) |
+| Integrate the shared services or package a task-delivery plugin | [Task delivery](task-delivery.md) |
+| Qualify a specific task-delivery plugin release and its actual host evidence | [Release qualification](release-qualification.md) |
+| Understand preparation isolation and provider capabilities | [Preparation](preparation.md) |
+| Understand durable runs, continuation, cancellation and publication | [Execution](execution.md) |
+| Understand module ownership and the overall design | [Architecture](architecture.md) |
+| Prepare an announcement or publish a release | [Launch](launch.md), [releasing](releasing.md) |
+
+## Read support claims precisely
+
+The local execution adapters are Claude Code, Codex, Gemini CLI, OpenCode and
+Goose. The OpenAI Agents API adapter performs remote execution and restricted
+task preparation. Codex Cloud is registered but refuses new dispatch because
+the supported interface cannot verify the selected environment's repository.
+Local Codex and Claude execution remain available. Preparation has its own
+capabilities: an implementation adapter does not automatically support drafting.
+
+Run `gallivant doctor` to check the configured installation. An adapter or a
+passing fixture test does not establish access to your provider, model or paid
+plan. Follow the selected provider's guide for actual prerequisites and recorded
+qualification limits. When using hosted execution from the CLI, Gallivant's
+coordinator still needs to remain running to advance the task and review loop.
+A packaged plugin is also separate from a deployed, authenticated service.
+
+## Specifications and recorded evidence
+
+The guides above describe this checkout. The following source-repository material
+has a different purpose and is deliberately excluded from the npm package:
+
+- [Implementation PRDs](https://github.com/uchibeke/gallivant/tree/main/docs/prds):
+  requirements used to build features, including work with incomplete gates.
+- [Plans](https://github.com/uchibeke/gallivant/tree/main/docs/plans): architecture,
+  sequencing and release contracts, rather than a list of shipped capabilities.
+- [Audits](https://github.com/uchibeke/gallivant/tree/main/docs/audit): dated results,
+  exact source revisions, limitations and remaining qualification work.
+- [Original source-design notes](https://github.com/uchibeke/gallivant/blob/main/docs/design/sources-and-standards.md):
+  historical decisions and proposals with their original context.
+
+For an older installed release, inspect the matching Git tag instead of treating
+the current `main` branch as its feature set. Preserve queued PRDs and carried
+plans: their bytes can be pinned to a running chain. Record new implementation
+behavior in the operator guides and new evidence, rather than rewriting a
+historical test result or silently changing an approved task.