@uchibeke/gallivant 0.0.0-stage → 0.2.0

package/lib/commands/serve.mjs

@@ -0,0 +1,349 @@
+import { acquireCliMutation } from "../daemon.mjs";
+// `gallivant serve`: the tracker. One local page showing every entry and every run, with the log tailing live.
+//
+// Reads remain GET-only. One protected POST queues a local operator request; only the daemon
+// applies it through the existing resume and review loop. No shell commands come from the browser.
+//
+// It binds to 127.0.0.1 and takes no auth, which is the same trust boundary as the CLI: anything that can reach it
+// can already read ~/.gallivant. That is exactly why it must never bind to 0.0.0.0.
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { requestControl, lastMessage } from "../control.mjs";
+import { model } from "./status.mjs";
+import { isOurProcess, alive } from "../run.mjs";
+import { executionRunner, executionLive, unsubmittedInitialDispatch } from "../execution.mjs";
+import { logWindow } from "../run_log.mjs";
+import { executionCapabilities } from "../harness.mjs";
+import { redact } from "../execution_io.mjs";
+import { readJson } from "../fs.mjs";
+import { join } from "node:path";
+// `handleFor` from state.mjs is the canonical handle. This file used to spell the rule again with its own fallback,
+// and two spellings of one rule is how the canonical one kept the `undefined#3` bug that never showed up here.
+import { handleFor } from "../state.mjs";
+import { streamRun, sliceRun, TAIL } from "../tracker/stream.mjs";
+import { listRuns, listFlatRuns, runDir, sourceRunDir, validRunId } from "../tracker/runs.mjs";
+import { ASSETS, themeOf } from "../tracker/assets.mjs";
+import { dashboard, runPage, runsPage, page, esc, CSP, GROUPINGS } from "../tracker/pages.mjs";
+
+export const DEFAULT_PORT = 8791;
+const HOST = "127.0.0.1";
+const TOKENS = new WeakMap();
+const tokenFor = ctx => {
+  if (!TOKENS.has(ctx)) TOKENS.set(ctx, randomBytes(32).toString("hex"));
+  return TOKENS.get(ctx);
+};
+// Check the peer and Host independently: loopback binding alone does not stop DNS rebinding.
+const localRequest = req => {
+  if (!["127.0.0.1", "::1", "::ffff:127.0.0.1"].includes(req.socket?.remoteAddress)) return false;
+  try {
+    const host = req.headers.host;
+    const url = new URL(`http://${host}`);
+    return ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)
+      && url.host === host && Number(url.port || 80) === req.socket.localPort;
+  } catch { return false; }
+};
+
+/** Headers every response carries. The CSP is explained in tracker/pages.mjs. */
+const SECURITY = {
+  "content-security-policy": CSP,
+  "referrer-policy": "no-referrer",
+  "x-content-type-options": "nosniff",
+};
+
+const send = (res, code, type, body, cache = "no-store") => { res.writeHead(code, { "content-type": type, "cache-control": cache, ...SECURITY }); res.end(body); };
+const html = (res, code, body) => send(res, code, "text/html; charset=utf-8", body);
+const json = (res, code, value) => send(res, code, "application/json; charset=utf-8", JSON.stringify(value, null, 2));
+const notFound = (res, what, view) => html(res, 404, page({ title: "not found - gallivant", theme: view?.theme, base: view?.base || "",
+  body: `<header class="top"><h1>404</h1></header><section class="main"><p>${esc(what)}</p><p><a href="${esc(view?.base || "")}/">back to the dashboard</a></p></section>` }));
+
+const liveness = job => job?.execution?.provider && !job.bin ? executionLive(job) : !!job && job.exit === null && isOurProcess(job.pid, job.bin);
+
+/**
+ * Every run the tracker knows about: Gallivant's own, plus any flat run trees the caller pointed it at.
+ *
+ * `ctx.runSources` is a list of `{ label, dir }`. The point of it is that a run folder is a run folder: command
+ * center writes the same job.json and job.log under `<project>/.content-pipeline/runs/`, so the same table can show
+ * those rows rather than the operator keeping two tabs open. They are listed, never opened: there is no registry to
+ * validate an id against outside Gallivant's own tree, so nothing here builds a path from a query string for them.
+ */
+const allRuns = (ctx, entries, { entry = null } = {}) => {
+  const mine = listRuns(ctx.home, entries, { isRunning: liveness, entry });
+  // A filter names a Gallivant entry, and no foreign run belongs to one, so a filtered list is Gallivant's alone.
+  if (entry) return mine;
+  const theirs = (ctx.runSources || []).flatMap(s => listFlatRuns(s.dir, { source: s.label, isRunning: liveness }));
+  return [...mine, ...theirs].sort((a, b) => (b.startedAt ?? 0) - (a.startedAt ?? 0) || b.run.localeCompare(a.run));
+};
+
+/** What the URL asks for about presentation: which palette to force, which grouping, and where we are mounted. */
+const viewOf = (url, base = "", home = null) => {
+  const by = url.searchParams.get("by") || "";
+  return {
+    theme: themeOf(url.searchParams.get("theme")),
+    by: GROUPINGS.includes(by) ? by : GROUPINGS[0],
+    // The raw values, so a link out of one page keeps the reader's choices rather than resetting them.
+    query: { theme: themeOf(url.searchParams.get("theme")) || "" },
+    base,
+    home,
+  };
+};
+
+/**
+ * Resolve `?id=` to a registry entry. The query string is never joined to a path: an id is accepted only when the
+ * registry has it, so a traversal attempt (`../../etc`, `..%2f..`) simply does not match an entry and is a 404.
+ */
+const entryFrom = (ctx, url) => {
+  const id = url.searchParams.get("id") || "";
+  const entry = id ? ctx.state.get(id) : null;
+  return entry ? { id, entry } : null;
+};
+
+/**
+ * Which run a page or a stream is about: `?run=` when the reader picked one from the runs list, otherwise the run
+ * this entry last dispatched. A `?run=` that is not a valid run id, or that names no folder, is refused rather than
+ * silently falling back to the current run, because a reader following a link deserves to know it was wrong.
+ */
+const runFor = (ctx, id, wanted) => {
+  const runner = executionRunner(ctx, id);
+  if (!wanted) { const cur = runner.current(); return cur ? { id: cur.id, exit: cur.exit, running: cur.running } : null; }
+  if (!validRunId(wanted)) return null;
+  const job = runner.read(wanted);
+  return job ? { id: job.id, exit: job.exit, running: liveness(job) } : null;
+};
+
+/**
+ * Which run directory a log request is about, or null.
+ *
+ * The two log routes (the live stream and the history window) address a run exactly the same way, so they resolve it
+ * the same way, here, once. Two spellings of one rule is how a traversal gets into the second one after the first is
+ * fixed: a run from a configured flat tree is addressed by its source label, matched against the configured list; one
+ * of Gallivant's own is addressed by a registry entry id and a run id, and the directory is rebuilt from those rather
+ * than from the query string. Nothing a query string contains is ever joined to a path as given.
+ */
+const logDirFor = (ctx, url) => {
+  const source = url.searchParams.get("source") || "";
+  const wanted = url.searchParams.get("run") || "";
+  if (source) {
+    const dir = sourceRunDir(ctx.runSources, source, wanted);
+    return dir ? { dir, isRunning: job => !!job && job.exit === null && alive(job.pid) } : null;
+  }
+  const hit = entryFrom(ctx, url);
+  if (!hit) return null;
+  const run = runFor(ctx, hit.id, wanted);
+  if (!run) return null;
+  const dir = runDir(ctx.home, ctx.state.entries(), hit.id, run.id);
+  return dir ? { dir, id: hit.id, runId: run.id, isRunning: liveness } : null;
+};
+
+// The route table, keyed by method and path, as in command-center's server.mjs. Anything not listed is a 404, and
+// GET never changes state; the one write queues a request for the daemon.
+export const routes = {
+  "GET /": (ctx, _req, res, url, v) => html(res, 200, dashboard(model(ctx), { clock: ctx.clock, ...v })),
+
+  "GET /runs": (ctx, _req, res, url, v) => {
+    const entries = ctx.state.entries();
+    const filter = url.searchParams.get("entry") || "";
+    // A filter naming an entry the registry does not have lists nothing rather than everything, so a stale link
+    // never quietly widens what it shows.
+    const known = filter && entries.some(([id]) => id === filter);
+    const rows = filter && !known ? [] : allRuns(ctx, entries, { entry: filter || null });
+    // The run the reader picked in the sidebar, matched against the rows already listed rather than resolved from
+    // the query string, so `open` can name nothing that is not on this page anyway.
+    const want = url.searchParams.get("open") || "", from = url.searchParams.get("source") || "";
+    const open = want ? rows.find(r => r.run === want && (r.source || "") === from) || null : null;
+    html(res, 200, runsPage(rows, { entry: filter, open, ...v }));
+  },
+
+  "GET /run": (ctx, req, res, url, v) => {
+    const hit = entryFrom(ctx, url);
+    if (!hit) return notFound(res, "No entry with that id. The dashboard lists the ones the registry has.", v);
+    const { id, entry } = hit;
+    const wanted = url.searchParams.get("run") || "";
+    const run = runFor(ctx, id, wanted);
+    if (wanted && !run) return notFound(res, "No such run for that entry.", v);
+    // The divergence comes off the model's own row rather than being recomputed here: the model is built for this
+    // response anyway, and one comparison per request beats two that could disagree.
+    const m = model(ctx);
+    const row = [...m.needs_you, ...m.running, ...m.done].find(r => r.id === id) || null;
+    let initialLaunch = false;
+    try { initialLaunch = !!unsubmittedInitialDispatch(entry, executionRunner(ctx, id)); } catch { /* Unresolved or stopped ownership cannot enable a launch control. */ }
+    html(res, 200, runPage({ id, entry, handle: handleFor(id, entry), run, initialLaunch, maxIterations: ctx.config.max_iterations, model: m, divergence: row?.divergence ?? null, controlToken: localRequest(req) ? tokenFor(ctx) : null, ...v }));
+  },
+
+  "GET /api/run/control": (ctx, _req, res, url) => {
+    const hit = entryFrom(ctx, url);
+    if (!hit) return json(res, 404, { error: "unknown entry" });
+    json(res, 200, { control: hit.entry.control || null, lastMessage: lastMessage(hit.entry), state: hit.entry.state, reason: hit.entry.reason });
+  },
+
+  "POST /api/run/control": async (ctx, req, res, url) => {
+    if (!localRequest(req) || req.headers.origin !== `http://${req.headers.host}`
+      || req.headers["x-gallivant-token"] !== tokenFor(ctx)) return json(res, 403, { error: "Open this page on localhost and reload before trying again." });
+    if (req.headers["content-type"]?.split(";")[0] !== "application/json") return json(res, 415, { error: "JSON required" });
+    const hit = entryFrom(ctx, url);
+    if (!hit) return json(res, 404, { error: "unknown entry" });
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+      size += Buffer.byteLength(chunk);
+      if (size > 32768) return json(res, 413, { error: "Request too large" });
+      chunks.push(Buffer.from(chunk));
+    }
+    let input;
+    try { input = JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+    catch { return json(res, 400, { error: "Invalid JSON" }); }
+    if (!input || typeof input !== "object" || Array.isArray(input)) return json(res, 400, { error: "Invalid request" });
+    try {
+      const owner = acquireCliMutation(ctx.home);
+      try { json(res, 202, requestControl(ctx, { handle: hit.id, action: input.action, note: input.note, interrupt: input.interrupt })); }
+      finally { owner.release(); }
+    }
+    catch (e) { json(res, 409, { error: e.message }); }
+  },
+
+  // The stylesheet and the script, served rather than inlined so the CSP needs no nonce and no hash. They cannot
+  // change under a running server, so they are the one thing here worth caching in the browser.
+  "GET /tracker.css": (_ctx, _req, res) => send(res, 200, ASSETS["/tracker.css"].type, ASSETS["/tracker.css"].body, "max-age=60"),
+  "GET /tracker.js": (_ctx, _req, res) => send(res, 200, ASSETS["/tracker.js"].type, ASSETS["/tracker.js"].body, "max-age=60"),
+
+  "GET /api/status": (ctx, _req, res) => json(res, 200, model(ctx)),
+  "GET /api/capabilities": (_ctx, _req, res) => json(res, 200, { version: 1, providers: executionCapabilities() }),
+
+  "GET /api/runs": (ctx, _req, res, url) => {
+    const filter = url.searchParams.get("entry") || "";
+    json(res, 200, { runs: allRuns(ctx, ctx.state.entries(), { entry: filter || null }) });
+  },
+
+  // The live log of a run, as server-sent events.
+  //
+  // The path is /output rather than /log on purpose. "log?id=" has the shape of a tracking pixel, and content
+  // blockers that filter on the URL (uBlock Origin Lite's default rules, via declarativeNetRequest) reject it
+  // inside the browser before the request is sent: Chrome reports blocked:other, the server sees nothing at all,
+  // and the pane waits on a stream that was never opened. Ordinary fetches to /api/run/status are untouched, which
+  // is what made this look like a streaming bug rather than a blocked request.
+  "GET /api/run/output": (ctx, req, res, url) => {
+    const hit = logDirFor(ctx, url);
+    if (!hit) return json(res, 404, { error: "unknown run" });
+    streamRun(res, hit.dir, { req, isRunning: hit.isRunning });
+  },
+
+  // A window of a run's log, older than what the pane is already showing. A read, not a stream, so it is its own
+  // path rather than a mode of /output: the tail on open exists because thousands of lines as individual
+  // server-sent events stall the browser until it drops the connection, and answering "give me the previous 400" as
+  // one JSON body is the shape that does not have that problem. Same addressing and the same validation as /output,
+  // through the same `logDirFor`, so a traversal that fails on one fails on the other by construction.
+  //
+  // `?before=<id>` is the id of the oldest line the pane has, so the answer is the window before it, and `before` in
+  // the answer is how many lines are older still. No `before` means the window the tail did not show.
+  "GET /api/run/history": (ctx, _req, res, url) => {
+    const hit = logDirFor(ctx, url);
+    if (!hit) return json(res, 404, { error: "unknown run" });
+    const raw = url.searchParams.get("before");
+    // A non-numeric `before` is not a request for the start of the file, it is a broken link, and answering it with
+    // the first 400 lines would look like the feature working. Absent is the one case that means "the default".
+    if (raw !== null && !/^-?\d+$/.test(raw)) return json(res, 400, { error: "before must be a line number" });
+    json(res, 200, { run: url.searchParams.get("run") || "", tail: TAIL, ...sliceRun(hit.dir, { end: raw === null ? null : Number(raw) }) });
+  },
+
+  // Kept so an old bookmark or a copied URL still resolves.
+  "GET /api/run/log": (_ctx, _req, res, url, v) => { res.writeHead(302, { location: `${v.base}/api/run/output${url.search || ""}`, ...SECURITY }); res.end(); },
+
+  "GET /api/run/status": (ctx, _req, res, url) => {
+    const hit = entryFrom(ctx, url);
+    if (!hit) return json(res, 404, { error: "unknown entry" });
+    const run = runFor(ctx, hit.id, url.searchParams.get("run") || "");
+    if (!run) return json(res, 404, { error: "no run" });
+    const window = logWindow(executionRunner(ctx, hit.id).dirOf(run.id));
+    json(res, 200, { entry: hit.id, run: run.id, running: run.running, exit: run.exit, lines: window.total, last: window.lines.at(-1) || "", ...(window.gap ? { gap: window.gap } : {}) });
+  },
+  "GET /api/run/result": (ctx, _req, res, url) => {
+    const hit = logDirFor(ctx, url);
+    if (!hit) return json(res, 404, { error: "unknown run" });
+    const result = readJson(join(hit.dir, "result.json"));
+    if (!result) return json(res, 404, { error: "result has not been collected" });
+    // Private results retain exact ownership and artifacts. Public responses
+    // use the summary and the run's supplied-secret redaction, never payloads.
+    const artifacts = (Array.isArray(result.artifacts) ? result.artifacts.slice(0, 100)
+      : Array.isArray(result.files) ? result.files.slice(0, 100).map(f => ({ path: f.path, hash: f.afterHash })) : [])
+      .map(f => ({ path: f.path, hash: f.hash }));
+    const publication = readJson(join(hit.dir, "result-application.json"));
+    if (Array.isArray(publication?.paths)) publication.paths = artifacts.map(f => f.path);
+    const execution = hit.id ? executionRunner(ctx, hit.id) : null;
+    const outcome = execution?.outcome?.(hit.runId) ?? result.outcome;
+    const view = { version: result.version, taskId: result.taskId, runId: result.runId, inputHead: result.inputHead ?? null,
+      providerJobId: result.providerJobId ?? null, sessionId: result.sessionId ?? null, turnId: result.turnId ?? null,
+      outcome, artifacts, publication, verification: readJson(join(hit.dir, "verification.json")) };
+    json(res, 200, execution?.sanitize ? execution.sanitize(view, hit.runId) : redact(view));
+  },
+};
+
+/**
+ * Route one request. Exported so the tests can drive every handler with fake request and response objects, and so a
+ * host server can delegate a prefix to it (see `mount`).
+ *
+ * `base` is the mount path to strip from the request and to put back on every URL the pages emit. Empty means this
+ * tracker owns the origin, which is what `gallivant serve` does.
+ */
+export function handle(ctx, req, res, { base = "", home = null } = {}) {
+  const url = new URL(req.url, `http://${HOST}`);
+  // Under a mount, `/gallivant/runs` is this router's `/runs`, and `/gallivant` itself is its `/`.
+  const path = base && url.pathname.startsWith(base) ? url.pathname.slice(base.length) || "/" : url.pathname;
+  const route = routes[`${req.method} ${path}`];
+  const view = viewOf(url, base, home);
+  if (!route) return path.startsWith("/api/") ? json(res, 404, { error: "not found" }) : notFound(res, `No page at ${esc(url.pathname)}.`, view);
+  const failed = e => {
+    ctx.log?.warn?.(`serve ${req.method} ${url.pathname}: ${e.message}`);
+    // The reader gets the status, never the exception text: a message can carry a path or a token, and this page is
+    // the one thing in Gallivant a browser renders.
+    if (res.headersSent) return res.end();
+    return url.pathname.startsWith("/api/")
+      ? json(res, 500, { error: "internal error" })
+      : html(res, 500, page({ title: "error - gallivant", body: `<header class="top"><h1>500</h1></header><section class="main"><p>Something went wrong. The terminal running <code>gallivant serve</code> has the reason.</p></section>` }));
+  };
+  try {
+    const result = route(ctx, req, res, url, view);
+    return result?.catch ? result.catch(failed) : result;
+  } catch (e) { return failed(e); }
+}
+
+/**
+ * Mount the tracker inside a server somebody else owns, so one process and one port serve both. The host matches the
+ * prefix and hands the request over; everything below that prefix is this router's, including its own 404.
+ *
+ *   import { mount } from "@uchibeke/gallivant/lib/commands/serve.mjs";
+ *   const tracker = mount(makeContext(), { base: "/gallivant" });
+ *   createServer((req, res) => {
+ *     if (tracker.owns(req)) return tracker.handle(req, res);
+ *     ...the host's own routes
+ *   }).listen(8790, "127.0.0.1");
+ *
+ * `home` is an optional `{ label, url }` link back out to the host, so the switch works both ways rather than being a
+ * one-way trip into the tracker.
+ *
+ * The host keeps its own auth and its own bind address. Two things follow from that, and they are the host's to get
+ * right rather than something this module can enforce: a host that answers on a public address publishes the
+ * tracker there too, and a host with auth should put this behind it, because nothing here asks who is calling.
+ */
+export function mount(ctx, { base = "/gallivant", home = null } = {}) {
+  const prefix = "/" + String(base).replace(/^\/+|\/+$/g, "");
+  if (prefix === "/") throw new Error("mount needs a non-empty base path, for example /gallivant");
+  return {
+    base: prefix,
+    /** Whether this request belongs to the tracker: the prefix itself, or anything under it. */
+    owns: req => { const p = new URL(req.url, `http://${HOST}`).pathname; return p === prefix || p.startsWith(prefix + "/"); },
+    handle: (req, res) => handle(ctx, req, res, { base: prefix, home }),
+  };
+}
+
+export function serve(ctx, { port = DEFAULT_PORT, instance = null } = {}) {
+  const server = createServer((req, res) => {
+    if (instance && req.method === "GET" && req.url === "/api/health") return localRequest(req)
+      ? json(res, 200, { instance }) : json(res, 403, { error: "local requests only" });
+    return handle(ctx, req, res);
+  });
+  return new Promise((resolve, reject) => {
+    server.on("error", reject);
+    // 127.0.0.1, never 0.0.0.0 and never a hostname that could resolve to a LAN address. There is no auth here and
+    // the pages show branch names, paths and log output, so reachability from another machine is the whole risk.
+    server.listen(port, HOST, () => { ctx.log.info(`serve: http://${HOST}:${port}`); resolve(server); });
+  });
+}

package/lib/commands/start.mjs

@@ -0,0 +1,247 @@
+// `gallivant start <prd path>`: one brief becomes one running session in its own checkout.
+//
+// The brief arrives as a Request (lib/sources/), which already names the target repository. `start` no longer works
+// the repo out from the file's directory: it reads `request.repo`, so the only thing that has to know where a brief
+// lives is the source that read it.
+import { verifyCommands, prdFingerprint, prdDecision, sourcePathsOf } from "../prd.mjs";
+import { requestFor } from "../sources/index.mjs";
+import { startPrompt } from "../prompt.mjs";
+import { remoteInput } from "../execution_input.mjs";
+import { learningInput, learningDispatch, learningDelivered, learningDeliveryPatch } from "../learning_input.mjs";
+import { capabilitiesFor, adapterFor, buildRun } from "../harness.mjs";
+import { newEntry, entryId, STATES } from "../state.mjs";
+import { branchFor, runEnv, worktreePath } from "../git.mjs";
+import { resolveCredentialFor, describe as describeCredential } from "../credential.mjs";
+import { requireIdentity, describeIdentity } from "../identity.mjs";
+import { rememberRepo, resolveContextPaths, resolveBase, configuredBase, repoNames } from "../config.mjs";
+import { writeRepositoryText } from "../repository_files.mjs";
+import { validateStartRequest, captureStartInput, checkBaseFiles } from "../start_contract.mjs";
+import { nowIso, floorSecond } from "../time.mjs";
+import { requireHarness } from "../probe.mjs";
+import { criteriaFromPrd, receiptInstructions } from "../deliverable.mjs";
+import { executionRunner, EXECUTION_VERSION } from "../execution.mjs";
+import { taskExecutionConfig } from "../task_allowance.mjs";
+
+export async function start(ctx, options) {
+  ctx = { ...ctx, config: taskExecutionConfig(ctx.config, options.task) };
+  const progress = { cloneAttempted: false, spawnAttempted: false };
+  try { return await startRequest(ctx, options, progress); }
+  catch (error) {
+    // A clone can leave an owned checkout even if it throws or source delivery
+    // fails before spawn. Only a pre-clone failure is a clean retry boundary.
+    error.startUncertain = progress.cloneAttempted || progress.spawnAttempted;
+    if (progress.remoteRegistered && !progress.spawnAttempted) error.message += `; the unsubmitted task and checkout at ${progress.clone.worktree} are retained; repair preparation and explicitly resume the registered task`;
+    else if (progress.cloneAttempted && !progress.spawnAttempted) error.message += `; start ownership and the clone at ${progress.clone.worktree} are retained; inspect its snapshots and start claim before recovery`;
+    throw error;
+  }
+}
+
+async function startRequest(ctx, { path, base: askedBase = null, chain = null, request: prepared = null, task = null }, progress) {
+  const { config, state, gh, git, log, runnerFor, writePrd, writeSource, readSource } = ctx;
+  // Intake supplies an immutable, repository-resolved draft snapshot. All gates,
+  // source capture and dispatch ownership below remain shared with file starts.
+  const request = prepared ?? await requestFor(path, { git, gh });
+  // The gate. Every rule that applies to this source, every time, no override: a brief that fails cannot start.
+  // A `context_paths:` key in the frontmatter adds to the config list for this brief alone. It is held to exactly
+  // the same rules, so a PRD cannot hand a session the home directory or the Gallivant home that the config file is
+  // refused for. This is the operator's list either way: the daemon's later runs read the snapshot written below,
+  // not the copy in the checkout the session can edit.
+  validateStartRequest(request, config, path);
+
+  // The source resolved these four by asking git which checkout the file is in and gh what that repository is
+  // called. A PRD outside a checkout fails there, with git's own message, before anything is recorded.
+  //
+  // `checkout` is the operator's own tree, and it is recorded on the entry from here on. The source has always known
+  // it (it is where `relPath` is relative TO) and `start` used to drop it on the floor, which is why nothing could
+  // compare the daemon's snapshot with the brief the operator is actually looking at: `entry.prd` is a relative path
+  // and there was no second half to join it to. It is the operator's path, never the session's, so nothing a session
+  // does can move it, and the daemon reads it for exactly one thing: the divergence check.
+  const { repo: nameWithOwner, defaultBranch, relPath: prdRel, checkout } = request;
+  const id = entryId(nameWithOwner, request.id);
+  if (state.get(id)) throw new Error(`${id} already exists; \`gallivant why ${id}\` explains it, \`gallivant remove ${id}\` forgets it`);
+
+  // The base branch this pull request will target, resolved once here and then carried everywhere it is needed: the
+  // branch the clone is cut from, the instruction the session is given, and the branch the daemon merges in before
+  // every later round. `resolveBase` owns the precedence (flag, then this repository's config entry, then the
+  // repository's default branch), so there is one definition rather than three agreeing by luck.
+  const selection = resolveBase({ config, repo: nameWithOwner, defaultBranch, asked: askedBase });
+  const base = selection.base;
+  // Intake pins the resolved base, including its original provenance. Passing
+  // that frozen value must not turn a default into a persisted operator override.
+  const baseSource = task?.baseSource || selection.source;
+  if (!base) throw new Error(`no base branch for ${nameWithOwner}: GitHub reported no default branch and none is configured. Set one with \`gallivant start ${path} --base <branch>\`.`);
+  // A base that is not on the remote must fail HERE. Left to `gh pr create --base`, it fails after the session has
+  // implemented the entire brief, run the tests and spent the budget, with the work stranded on a branch nobody asked
+  // for. One API call before anything is cloned is the whole cost of not doing that.
+  //
+  // `branchExists` returns false for HTTP404; transport/CLI failures throw a
+  // bounded credential-redacted diagnostic before any clone or provider dispatch.
+  if (!await gh.branchExists(nameWithOwner, base)) {
+    const how = baseSource === "flag" ? "--base names it" : baseSource === "config" ? `repos in config.json names it for ${nameWithOwner}` : `it is ${nameWithOwner}'s default branch`;
+    throw new Error(`base branch "${base}" is not on ${nameWithOwner} (${how}), or GitHub could not be asked. Nothing was cloned and nothing was started. Check the branch name, or run \`gh api repos/${nameWithOwner}/branches/${base}\` to see what GitHub says.`);
+  }
+  if (baseSource !== "default") log.info(`${id}: base branch ${base} (from ${baseSource === "flag" ? "--base" : "config"}), not ${nameWithOwner}'s default ${defaultBranch ?? "branch"}`);
+
+  // Nothing is recorded or cloned for a harness too old to honour its adapter, or one that is signed out.
+  await requireHarness(request.harness, config);
+
+  // A credential, before anything is cloned or spawned.
+  //
+  // This refusal is the defect being fixed. A run with no credential implements the whole brief, commits it, and then
+  // cannot push: the money is spent, the work is stranded in a worktree, and nothing warned anybody. So the credential
+  // is resolved here, where there is an operator reading the output, and a run that could not push never starts.
+  //
+  // There is no checkout yet, so the host reads as github.com, which is what `gh repo clone owner/name` resolves.
+  // An enterprise install is the case this cannot see from here, and `noCredentialMessage` says so by name: the
+  // answer there is `github_token_file`, rather than sending a github.com token to a host it cannot authenticate.
+  const credential = await resolveCredentialFor(ctx);
+  if (!credential.token) throw new Error(credential.why);
+  log.info(`${id}: GitHub credential from ${describeCredential(credential)}`);
+  // And an identity, refused here for the same reason and in the same place. A run commits as the operator, so with no
+  // identity on the machine every commit the session makes would fail; refusing before the clone means no money spent.
+  const identity = await requireIdentity(ctx);
+  log.info(`${id}: commits as ${describeIdentity(identity)}`);
+
+  const branch = branchFor(request.id);
+  // Everything the run needs, worked out BEFORE the clone, because the clone is the one step here that leaves
+  // something behind when a later one throws. `buildRun` refuses a harness that cannot grant the configured
+  // `context_paths` as read-only, and it used to be called four lines after `git.create`: the refusal arrived with
+  // the repository already cloned and nothing in the registry, so the next `gallivant start` failed on `git.create`
+  // ("worktree already exists") and the operator had to find and delete the directory themselves. Nothing in the
+  // spec needs the checkout to exist: `worktreePath` is a pure function of the config, the repo and the PRD id, and
+  // `git.create` clones to that same path, so the `cwd` the spec carries is knowable first.
+  const worktreePlanned = worktreePath(config, nameWithOwner, request.id);
+  const remote = capabilitiesFor(request.harness).transport === "remote";
+  let session = remote ? null : adapterFor(request.harness).newSession();
+  const receipt = config.deliverable ? receiptInstructions(criteriaFromPrd(request), id) : null;
+  // The list the brief declared, which the contract rule has already proved readable, so the prompt can name the files
+  // before they are snapshotted below and there is no second source of truth about what a brief carries.
+  const declared = sourcePathsOf(request);
+  const prompt = startPrompt({ prd: request, repo: nameWithOwner, branch, base, verify: verifyCommands(request), receipt, carried: declared });
+  // Read-only extras for this session: the config list plus this brief's own frontmatter, merged in one place.
+  const contextPaths = resolveContextPaths(config, request);
+  if (remote && contextPaths.length) throw Object.assign(new Error("hosted backend cannot enforce private read-only context_paths"), { code: "EXECUTION_POLICY" });
+  let spec = remote ? null : buildRun({ harness: request.harness, config, mode: "start", session, prompt, cwd: worktreePlanned, contextPaths });
+  const input = captureStartInput(request, base);
+  if (task && input.digest !== task.digest) throw Object.assign(new Error("approved task input changed; validate the current revision before starting"), { code: "TASK_CONFLICT" });
+  if (chain && input.digest !== chain.digest) throw new Error(`queued PRD or sources changed for ${id}; retry the chain with --resnapshot after reviewing the changes`);
+  const claim = state.claimStart(id, chain, task);
+  try {
+
+    // The daemon's own copy of the brief: fix rounds and the completion gate read this, never the checkout.
+    writePrd(id, request.text);
+
+    // The files the brief carries, snapshotted beside it and for the same reason. The contract rule has already read
+    // every one of them, so a failure here is a race (an edit or a delete between `ready` and now) rather than a mistyped
+    // path, and it must still be loud: the session would otherwise start against a brief citing a document that is not
+    // there. This is above the clone because everything that can throw belongs before the irreversible step.
+    const carried = [];
+    for (const [rel, text] of input.sources) {
+      writeSource(id, rel, text);
+      carried.push(rel);
+    }
+
+    progress.clone = { worktree: worktreePlanned, base, branch };
+    state.markStartClone(id, claim.token, progress.clone);
+    progress.cloneAttempted = true;
+    let worktree;
+    try { worktree = await git.create({ nameWithOwner, prdId: request.id, base }); }
+    catch (error) {
+      // Keep ownership for unknown/partial failures. A known refusal before the
+      // clone executor is invoked is the same clean retry boundary as preflight.
+      if (error.cloneAttempted === false) progress.cloneAttempted = false;
+      throw error;
+    }
+    if (chain) {
+      for (const sha of chain.after) {
+        if (!await git.containsCommit(worktree, sha)) throw new Error(`the fresh ${base} checkout does not contain predecessor merge ${sha}; nothing spawned`);
+      }
+      await checkBaseFiles(input, chain.baseFiles, rel => git.fileAt(worktree, "HEAD", rel));
+    }
+    // The clone is where the process actually runs, so it is what the spawn below is given. The spec's own `cwd` was
+    // `worktreePath` for the same repo and PRD id, which is what `git.create` returns; no adapter reads `ctx.cwd` today,
+    // so the two are only ever compared here. A relocating `git.create` would want this to be a refusal rather than a
+    // note, and if `cwd` ever reaches argv it has to become one.
+    if (worktree !== worktreePlanned) log.warn(`${id}: the checkout landed at ${worktree}, not the ${worktreePlanned} the run spec was built for`);
+    const publicSince = floorSecond(nowIso());
+    let remoteRegistered = false;
+    if (remote) {
+      state.validateStart(id, claim.token, chain);
+      const pending = newEntry({ prd: prdRel, harness: request.harness, session: null, repo: nameWithOwner, branch, worktree, state: STATES.needsHuman, nowIso: nowIso(), checkout, prdFingerprint: prdFingerprint(request), prdDecision: prdDecision(request), base, sources: carried });
+      // The clone is owned, but snapshot delivery and read-only API preparation
+      // can still fail. Consume the claim into an actionable entry before them;
+      // preserve the checkout rather than silently deleting unfinished files.
+      state.putStarted(id, { ...pending, execution: { version: EXECUTION_VERSION, operationId: claim.token }, initial_dispatch: { version: 1, operationId: claim.token, status: "unsubmitted" }, reason: "launch-preparation", public_since: publicSince, ...(task ? { task } : {}), ...(chain ? { chain: { name: chain.name, index: chain.index, dispatch: chain.dispatch } } : {}), last: { at: nowIso(), run: null, exit: null, event: "managed launch preparation pending; repair prerequisites and explicitly resume" } }, claim.token);
+      remoteRegistered = progress.remoteRegistered = true;
+    }
+    // The PRD usually only exists in the operator's own checkout, so the fresh clone off the base branch does not
+    // have it. Write it in at the same relative path before the session starts, so the branch carries the brief and
+    // the PR can link it. The daemon's snapshot above stays the authoritative copy for the completion gate; this one
+    // is writable by the session and is never read back for a decision.
+    writeRepositoryText(worktree, prdRel, request.text);
+    // The carried files, written from the daemon's snapshot rather than from the operator's tree. Reading the snapshot is
+    // the point: it is the copy the gate judges, so the session and the gate cannot be handed different bytes even if the
+    // operator edits the file in the second between the two writes. Same 0o644/0o755 as the brief, because these are
+    // files in a source tree and must not be clamped to daemon-state modes.
+    for (const rel of carried) writeRepositoryText(worktree, rel, readSource(id, rel));
+    if (carried.length) log.info(`${id}: carried ${carried.length} file${carried.length === 1 ? "" : "s"} from ${request.checkout} into the checkout`);
+    if (!remote) state.validateStart(id, claim.token, chain);
+    const execution = executionRunner(ctx, id, request.harness);
+    const managed = await learningInput(ctx, id, { repo: nameWithOwner, harness: request.harness, session: null, prd: prdRel, sources: carried }, { operationId: claim.token, sessionId: null, recordedSessionId: session, inputHead: git.head ? await git.head(worktree) : null, prompt });
+    const { prompt: managedPrompt, ...dispatchInput } = managed;
+    if (!remote && managedPrompt !== prompt) spec = buildRun({ harness: request.harness, config, mode: "start", session, prompt: managedPrompt, cwd: worktree, contextPaths });
+    let job;
+    // Register the remote ownership before I/O. A launcher crash or lost reply
+    // must leave an entry the existing coordinator can reconcile, with no second
+    // start claim. Keep it actionable until exact launch identities are known.
+    if (remote) {
+      const preparedInput = await remoteInput(ctx, id, { harness: request.harness, prd: prdRel, worktree, checkout, repo: nameWithOwner, branch, base, sources: carried, task }, { ...dispatchInput, name: "start", prompt: managedPrompt }, contextPaths);
+      await execution.prepare(preparedInput);
+      state.update(id, { initial_dispatch: { version: 1, operationId: claim.token, status: "dispatching" }, reason: "dispatch-intent", last: { at: nowIso(), run: null, exit: null, event: "managed dispatch pending" } });
+      progress.spawnAttempted = true;
+      try { job = await learningDispatch(ctx, id, managed, () => execution.submit(preparedInput)); session = job.execution.sessionId; }
+      catch (error) {
+        const current = execution.current();
+        if (error.dispatchNotSent === true) state.update(id, { initial_dispatch: { version: 1, operationId: claim.token, status: "unsubmitted" }, reason: "dispatch-refused", last: { at: nowIso(), run: null, exit: null, event: "managed dispatch refused before any provider request; repair prerequisites and explicitly resume" } });
+        else if (current) state.update(id, { execution: current.execution, session: current.execution.sessionId, last: { at: nowIso(), run: current.id, exit: null, event: "managed dispatch acceptance unresolved" } });
+        throw error;
+      }
+    } else {
+      // Even a throwing local spawn can have created a child.
+      progress.spawnAttempted = true;
+      job = await learningDispatch(ctx, id, managed, () => execution.start("start", spec.cmd, spec.args, { cwd: worktree, runtimeSettings: spec.runtimeSettings, env: { ...runEnv(config, credential, identity, worktree), ...spec.env }, execution: dispatchInput }));
+    }
+
+    // `checkout` and the two prd fields are what the divergence check compares against: where the operator's copy lives,
+    // the contract the snapshot above carries, and the readiness decision the brief was blessed with. All three are
+    // recorded at the same moment as the snapshot, because a fingerprint of a brief other than the one snapshotted is
+    // worse than no fingerprint at all.
+    const entry = newEntry({
+      prd: prdRel, harness: request.harness, session, repo: nameWithOwner, branch, worktree, state: STATES.running, nowIso: nowIso(),
+      checkout, prdFingerprint: prdFingerprint(request), prdDecision: prdDecision(request), base, sources: carried,
+    });
+    const startedEntry = { ...entry, ...(remote ? { initial_dispatch: null } : {}), ...(job.execution ? { execution: job.execution } : {}), ...(task ? { task: { ...task, run: job.id } } : {}), public_since: publicSince, ...(chain ? { chain: { name: chain.name, index: chain.index, dispatch: chain.dispatch } } : {}), last: { at: nowIso(), run: job.id, exit: null, event: "start" } };
+    if (remoteRegistered) state.update(id, current => ({ ...startedEntry, ...learningDeliveryPatch(current, managed, job) }));
+    else state.putStarted(id, { ...startedEntry, ...learningDeliveryPatch(null, managed, job) }, claim.token);
+    await learningDelivered(ctx, id);
+    // The repository is recorded for recovery, and the base with it when one was chosen explicitly. `--base` is the
+    // "when initiating" half of configuring this: typed once, persisted for this repository, and every later start in it
+    // reads the same answer without the flag. A base that came from the repository's own default is NOT written, so an
+    // operator who configures nothing keeps the bare-string `repos` entry they have always had.
+    //
+    // `isNewRepo` is asked BEFORE the write, and it is a different question from "did the file change". The labels exist
+    // per repository and only want creating the first time one is seen; `rememberRepo` also returns true when it merely
+    // retargets the base of a repository already listed, so reading its return value for both would spend an
+    // `ensureLabels` call on every `--base` change.
+    const isNewRepo = configuredBase(config, nameWithOwner) === null && !repoNames(config).includes(nameWithOwner.toLowerCase());
+    const persistBase = baseSource === "flag" && !chain ? base : null;
+    rememberRepo(nameWithOwner, config.home, persistBase);
+    if (persistBase) log.info(`${nameWithOwner}: base branch ${base} recorded in ${config.home}/config.json; later starts in this repository need no --base`);
+    if (isNewRepo) await gh.ensureLabels(nameWithOwner).catch(e => log.warn(`${nameWithOwner}: labels not created: ${e.message}`));
+    log.info(`${id}: started ${request.harness} session in ${worktree}`);
+    return { id, worktree, branch, base, baseSource, session, run: job.id };
+  } catch (error) {
+    if (!progress.cloneAttempted && !progress.spawnAttempted) state.releaseStart(id, claim.token);
+    throw error;
+  }
+}

package/lib/commands/start_services.mjs

@@ -0,0 +1,22 @@
+import { upInBackground } from "./up.mjs";
+import { trackerInBackground, trackerForeground, trackerPort, trackerUrl, openTracker } from "../tracker_process.mjs";
+
+// One startup path for start (with or without a PRD) and serve. A UI failure
+// never resubmits a run or stops work already accepted by the daemon.
+export async function startServices(ctx, options = {}, deps = {}) {
+  const port = trackerPort(options.port);
+  const { daemon = upInBackground, tracker = trackerInBackground, foreground = trackerForeground, open = openTracker } = deps;
+  const messages = [], errors = [];
+  if (!options.noDaemon) {
+    try { const d = await daemon(ctx); messages.push(d ? `Daemon running (pid ${d.pid}).` : "Daemon already running."); }
+    catch (error) { errors.push(`Daemon: ${error.message}. Retry with gallivant start; do not resubmit the PRD.`); }
+  } else messages.push("Daemon startup skipped; existing daemons are unchanged.");
+  if (!options.noServer) {
+    try {
+      await (options.foreground ? foreground : tracker)(ctx, { port });
+      messages.push(`Dashboard: ${trackerUrl(port)}${options.foreground ? " (Ctrl-C stops this tracker)" : " (background)"}`);
+      if (!options.noOpen && !await open(port)) messages.push("Browser could not be opened; use the dashboard URL above.");
+    } catch (error) { errors.push(`Dashboard: ${error.message}. Retry gallivant serve --port ${port}; existing runs are unchanged.`); }
+  }
+  return { messages, errors };
+}