@uchibeke/gallivant 0.0.0-stage → 0.2.0

package/lib/control.mjs

@@ -0,0 +1,202 @@
+// Local operator requests. UI and CLI enqueue; the daemon is the only consumer.
+// One outstanding request per entry avoids competing resumes and needs no second runner.
+import { randomUUID } from "node:crypto";
+import { needsAgentResume } from "./network_recovery.mjs";
+import { resolveHandle, STATES } from "./state.mjs";
+import { readDaemon, assertDaemonUsable } from "./daemon.mjs";
+import { nowIso } from "./time.mjs";
+import { NEEDS_LABEL, READY_LABEL } from "./gh.mjs";
+import { adapterFor } from "./harness.mjs";
+import { executionRunner, unsubmittedInitialDispatch, PROVIDER_STATES } from "./execution.mjs";
+import { requestRunCancellation } from "./run.mjs";
+import { executionResultCheckpoint, acquirePublicationLock } from "./execution_result.mjs";
+import { controlAvailability, controlPending } from "./control_contract.mjs";
+export { controlAvailability, controlPending } from "./control_contract.mjs";
+
+export const CONTROL_LABELS = { recheck: "Recheck PR", resume: "Resume agent", message: "Send message", cancel: "Cancel task" };
+export const CONTROL_ACTIONS = Object.keys(CONTROL_LABELS);
+export const MAX_NOTE = 4000; // resumePrompt's quote limit; never silently truncate a message.
+export const lastMessage = entry => [entry.control, ...(entry.control_history || []).slice().reverse()].find(c => c?.action === "message" && c.note) ?? null;
+export const cancellationStatus = answer => answer.confirmed
+  ? { reason: "cancelled", message: "Cancellation confirmed." }
+  : answer.terminal
+    ? { reason: "cancelled", message: "Further dispatch stopped; provider execution had already completed." }
+    : { reason: "cancellation-requested", message: "Further dispatch stopped; provider cancellation is unconfirmed. Remote execution may continue." };
+
+// Never expose subprocess output (which can contain credentials) in the tracker.
+export function controlFailure(error) {
+  const text = error.message || "";
+  if (error.code === "AGENT_RESUME_REQUIRED") return "The agent stopped with an execution error. Use Resume agent after fixing connectivity or credentials. Recheck PR cannot resume the agent or clear this failure.";
+  if (error.code === "EXECUTION_OWNERSHIP") return "The saved request no longer owns the current run. Inspect its execution identity before submitting a new request.";
+  if (error.code === "EXECUTION_RESULT_BLOCKED") return "Result publication is blocked. Inspect result-application.json, result.json and any verification.json, then explicitly resume the same session for correction; PR recheck cannot retry publication.";
+  if (/PR is no longer open|closed or merged/.test(text)) return "The PR is closed or merged. Start a follow-up PRD for further changes.";
+  if (/resnapshot|carried files differ|brief.*(changed|missing)|snapshot/i.test(text)) return "The brief or carried sources changed. Review gallivant why, then restore them or explicitly use gallivant resume --resnapshot to accept the changes.";
+  if (/already has a run|still needs settling/.test(text)) return "The previous run has not settled yet. Wait for it to stop, then retry. Your message is saved below.";
+  if (/no session/.test(text)) return "No resumable session or proven unsubmitted launch is available. Inspect execution ownership and the run log before retrying. Your message is saved below.";
+  if (/older than/.test(text)) return "The configured harness is too old. Run gallivant doctor --probe, update that binary, then retry.";
+  if (error.code === "NO_CREDENTIAL") return error.reason === "configured-token-file-unavailable"
+    ? "The configured github_token_file is unavailable. Restore that private token file, or set github_token_file to null and restart the daemon before retrying."
+    : "GitHub authentication is unavailable. Authenticate with gh auth login, then retry.";
+  if (error.code === "NO_IDENTITY") return "Git has no commit identity. Configure your Git name and email, then retry.";
+  return "Could not apply the request. Inspect gallivant why and the daemon log. Your last message is saved below for editing and resending.";
+}
+
+export function requestControl(ctx, { handle, action, note = "", interrupt = false, requestId = null }) {
+  if (!CONTROL_ACTIONS.includes(action)) throw new Error("Unknown run action.");
+  if (typeof note !== "string" || note.length > MAX_NOTE) throw new Error(`Messages must be at most ${MAX_NOTE} characters.`);
+  if (action === "message" && !note.trim()) throw new Error("Write a message before sending it.");
+  if (action !== "message" && note.trim()) throw new Error("Use Send message to deliver a message to the agent.");
+  if (typeof interrupt !== "boolean" || (interrupt && action !== "message")) throw new Error("Interrupt is available only when sending a message.");
+  const id = resolveHandle(ctx.state.entries(), handle);
+  if (requestId !== null && (typeof requestId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(requestId))) throw new Error("Invalid control request identity.");
+  const saved = ctx.state.get(id);
+  const previous = requestId && [saved?.control, ...(saved?.control_history || [])].find(c => c?.id === requestId);
+  if (requestId && previous?.id === requestId) {
+    if (previous.action !== action || previous.note !== note.trim() || previous.interrupt !== interrupt) throw new Error("Control identity belongs to different input.");
+    return { entry: id, ...previous };
+  }
+  // UI and CLI must refuse before saving a request an old daemon cannot consume.
+  assertDaemonUsable(ctx.coordinatorHealth ? ctx.coordinatorHealth() : readDaemon(ctx.home));
+  const request = { id: requestId || randomUUID(), action, note: note.trim(), interrupt, status: "queued", at: nowIso(ctx.clock) };
+  const runner = executionRunner(ctx, id);
+  const exclusion = action === "cancel" ? acquirePublicationLock(ctx, id, { execution: runner }) : null;
+  try { ctx.state.update(id, entry => {
+    if (entry.state === STATES.done) throw new Error("This task is already closed or merged.");
+    if (controlPending(entry.control)) throw new Error("A request is already queued or being applied. Wait for its result.");
+    if (action === "recheck" && !entry.pr) throw new Error("This entry has no PR to recheck.");
+    if (action === "recheck" && needsAgentResume(entry)) throw Object.assign(new Error(controlFailure({ code: "AGENT_RESUME_REQUIRED" })), { code: "AGENT_RESUME_REQUIRED" });
+    const run = runner.current();
+    const available = controlAvailability(entry, run, runner.capabilities, { resumable: Boolean(entry.session || unsubmittedInitialDispatch(entry, runner)) });
+    if (["resume", "message"].includes(action) && entry.dispatch_stopped) throw new Error("Further dispatch is stopped; reconcile cancellation before authorizing another task.");
+    if (action === "recheck" && executionResultCheckpoint(runner, run)?.phase === "blocked") throw Object.assign(new Error("Result publication needs an explicit corrective resume."), { code: "EXECUTION_RESULT_BLOCKED" });
+    if (interrupt && runner.capabilities?.controls?.interrupt === false) throw new Error("This provider cannot safely interrupt; cancel stops further dispatch and requires remote confirmation.");
+    if (interrupt && !available.interrupt) throw new Error("This task cannot currently be interrupted.");
+    const active = run?.running && run.id === entry.last?.run;
+    if (!["recheck", "cancel"].includes(action) && !entry.session && !active && !unsubmittedInitialDispatch(entry, runner)) throw new Error("This entry has no session to resume or proven unsubmitted launch. Inspect its execution ownership before retrying.");
+    // A new fixed action must not erase a failed message. Keep a small local history.
+    return { control: { ...request, ...(action === "resume" && run?.execution?.providerState === "status-unknown" ? { recoveryRun: run.id } : {}) }, ...(action === "cancel" ? { dispatch_stopped: "cancellation-requested" } : {}), control_history: [...(entry.control_history || []), ...(entry.control ? [entry.control] : [])].slice(-20) };
+  }); } finally { exclusion?.release(); }
+  ctx.log.info(`${id}: operator ${action} queued (${request.id})`);
+  return { entry: id, ...request };
+}
+
+/** Optional stop-and-resume steering, using the existing runner and session parser. */
+export async function cancelControl(ctx, id) {
+  const entry = ctx.state.get(id), request = entry?.control;
+  if (request?.status !== "queued" || request.action !== "cancel") return false;
+  const runner = executionRunner(ctx, id), run = runner.current();
+  let answer = { confirmed: false };
+  try { answer = runner.cancel ? await runner.cancel() : run?.running ? requestRunCancellation(runner, run.id) : { confirmed: true }; }
+  catch (error) {
+    if (/already running|lock recovery/.test(error.message)) {
+      ctx.state.update(id, { control: { ...request, message: "Cancellation is queued behind provider reconciliation; further dispatch is stopped." } });
+      return true;
+    }
+    ctx.log.warn(`${id}: cancellation requested, confirmation unavailable (${error.code || "control failed"})`);
+  }
+  const status = cancellationStatus(answer);
+  ctx.state.update(id, { state: STATES.needsHuman, reason: status.reason, network_retry: null, control: { ...request, status: "applied", stop_run: run?.id ?? null, message: status.message, finished_at: nowIso(ctx.clock) } });
+  return true;
+}
+
+// An explicit resume of an ambiguous remote launch means observing the owned
+// input, not sending a second turn. Persist that meaning before recovery so a
+// crash after adoption cannot turn the same request into a continuation.
+export async function recoverControl(ctx, id) {
+  const entry = ctx.state.get(id), request = entry?.control;
+  if (request?.status !== "queued" || request.action !== "resume" || entry.dispatch_stopped) return false;
+  try {
+    const runner = executionRunner(ctx, id), run = runner.current();
+    const canRecover = runner.recover && runner.capabilities?.transport === "remote" && run && run.id === entry.last?.run;
+    if (request.recoveryRun && (!canRecover || request.recoveryRun !== run.id)) throw Object.assign(new Error("Recovery control no longer owns its saved run"), { code: "EXECUTION_OWNERSHIP" });
+    if (!canRecover || !request.recoveryRun && run.execution?.providerState !== "status-unknown") return false;
+    let retained = false;
+    ctx.state.update(id, current => {
+      if (current.control?.id !== request.id || current.control.status !== "queued") return {};
+      if (current.dispatch_stopped || current.last?.run !== run.id) throw Object.assign(new Error("Recovery control no longer owns its saved run"), { code: "EXECUTION_OWNERSHIP" });
+      retained = true;
+      return { control: { ...current.control, recoveryRun: run.id } };
+    });
+    if (!retained) return true;
+    const observed = await runner.recover({ authorized: true, operationId: `control-recovery:${request.id}` });
+    const ex = observed?.execution;
+    // Earlier input acceptance does not prove this observation recovered access.
+    const recovered = ex?.acceptance === "accepted" && PROVIDER_STATES.includes(ex.providerState) && !["status-unknown", "cancellation-requested"].includes(ex.providerState);
+    ctx.state.update(id, current => current.control?.id === request.id ? { control: { ...current.control, status: recovered ? "applied" : "failed", finished_at: nowIso(ctx.clock), message: recovered ? "Recovered observation of the existing provider input; no new input was sent." : "The bounded observation retry did not resolve the existing input. Inspect its saved evidence before retrying; no new input was sent." } } : {});
+  } catch (error) {
+    ctx.state.update(id, current => current.control?.id === request.id ? { control: { ...current.control, status: "failed", finished_at: nowIso(ctx.clock), message: controlFailure(error) } } : {});
+  }
+  return true;
+}
+
+export function interruptControl(ctx, id) {
+  const entry = ctx.state.get(id), request = entry?.control;
+  if (request?.status !== "queued" || !request.interrupt) return;
+  const runner = executionRunner(ctx, id), run = runner.current();
+  if (!run?.running || run.id !== entry.last?.run) return;
+  if (request.stop_run && request.stop_run !== run.id) return;
+  const session = entry.session || (runner.sessionFrom ? runner.sessionFrom(run.id) : adapterFor(entry.harness).sessionFrom(runner.lines(run.id)));
+  if (!session) return; // Never stop a first turn before it gives us a resumable identity.
+  ctx.state.update(id, { session, control: { ...request, stop_run: run.id, message: "Stopping the active run; your files will be preserved before the same session resumes." } });
+  try { runner.kill(run.id); }
+  catch (error) {
+    ctx.log.warn(`${id}: interrupt failed: ${error.message}`);
+    ctx.state.update(id, { state: STATES.needsHuman, reason: "run-stop-unverified", control: {
+      ...request, status: "failed", finished_at: nowIso(ctx.clock),
+      message: "Could not safely stop the previous run. Inspect its process group using gallivant why and the daemon log before retrying. Your message is saved below; no replacement was started.",
+    } });
+    return true; // The daemon completes the central needs-human labels/notification transition.
+  }
+}
+
+/** Run only after the previous harness process has settled. */
+export async function applyControl(ctx, id) {
+  const entry = ctx.state.get(id);
+  const request = entry?.control;
+  if (!controlPending(request)) return false;
+  const finish = patch => ctx.state.update(id, current => current.control?.id === request.id
+    ? { control: { ...request, ...patch, finished_at: nowIso(ctx.clock) } } : {});
+  // A crash after spawning is indistinguishable from one just before it. Never auto-replay it.
+  if (request.status === "applying") {
+    finish({ status: "failed", message: "Request interrupted. Check the latest run before trying again." });
+    return true;
+  }
+  const runner = executionRunner(ctx, id);
+  if (runner.current()?.running) return false;
+  ctx.state.update(id, { control: { ...request, status: "applying" } });
+  try {
+    if (entry.state === STATES.done) throw new Error("The task was closed or merged before this request ran.");
+    if (entry.pr) {
+      const pr = await ctx.gh.prView(entry.repo, entry.pr);
+      if (pr.state !== "OPEN") throw new Error("The PR is no longer open.");
+    }
+    let run = null, initialLaunch = false;
+    if (request.action === "recheck") {
+      if (needsAgentResume(entry)) throw Object.assign(new Error("The agent failure requires resume, not PR recheck."), { code: "AGENT_RESUME_REQUIRED" });
+      if (executionResultCheckpoint(runner)?.phase === "blocked") throw Object.assign(new Error("Result publication needs an explicit corrective resume."), { code: "EXECUTION_RESULT_BLOCKED" });
+      await ctx.gh.removeLabel(entry.repo, entry.pr, READY_LABEL);
+      await ctx.gh.removeLabel(entry.repo, entry.pr, NEEDS_LABEL);
+      ctx.state.update(id, {
+        state: STATES.prOpen, reason: null, retry: null, labels_pending: false, public_fix: null,
+        last: { ...entry.last, event: "operator requested PR recheck" }, updated_at: nowIso(ctx.clock),
+      });
+      // Preserve budgets, dispatch markers and the brief. Only the normal tick judges readiness.
+    } else {
+      const { resume } = await import("./commands/resume.mjs");
+      const result = await resume(ctx, { handle: id, note: request.note || null });
+      run = result.run;
+      initialLaunch = result.initialLaunch === true;
+      // A cosmetic label failure after spawning must not invite another resume.
+      if (entry.pr) await ctx.gh.removeLabel(entry.repo, entry.pr, NEEDS_LABEL).catch(e => ctx.log.warn(`${id}: could not remove stopped label: ${e.message}`));
+    }
+    finish({ status: "applied", run, message: initialLaunch ? "Started the initial run after repairing launch prerequisites." : request.action === "message"
+      ? "Started the next run in the same session with your message."
+      : run ? "Resumed the same agent session." : "Watching PR checks and review again." });
+    return request.action !== "recheck"; // A recheck continues through normal judgement in this same tick.
+  } catch (e) {
+    ctx.log.warn(`${id}: operator ${request.action} failed: ${e.message}`);
+    // Subprocess errors can carry credentials. Details stay in the local daemon log.
+    finish({ status: "failed", message: controlFailure(e) });
+  }
+  return true;
+}

package/lib/control_contract.mjs

@@ -0,0 +1,16 @@
+// Shared cached control visibility; requestControl remains the validation/writer.
+export const controlPending = control => ["queued", "applying"].includes(control?.status);
+export function controlAvailability(entry, run, capabilities, { resumable = Boolean(entry?.session) } = {}) {
+  const pending = controlPending(entry?.control);
+  const stopped = !entry || entry.state === "done" || pending;
+  const active = run?.running && run.id === entry?.last?.run;
+  const canContinue = !stopped && !entry.dispatch_stopped && Boolean(resumable || active);
+  return {
+    recheck: !stopped && Boolean(entry.pr),
+    resume: canContinue,
+    message: canContinue,
+    cancel: !stopped,
+    interrupt: canContinue && capabilities?.controls?.interrupt !== false,
+    cancellation: capabilities?.controls?.cancel === false ? "stop-future-dispatch; remote-compute-may-continue" : "requires-provider-confirmation",
+  };
+}

package/lib/coordinator.mjs

@@ -0,0 +1,19 @@
+// Portable wake-up envelope. It adds exclusion/scheduling, never task decisions.
+import { deliveryError } from "./task_delivery_contract.mjs";
+export function createCoordinator({ store, advance, schedule, clock = Date, intervalMs = 10000 }) {
+  if (!store?.withOwner || typeof advance !== "function" || typeof schedule !== "function" || !Number.isSafeInteger(intervalMs) || intervalMs < 1) throw deliveryError("COORDINATOR_CONFIG", "Inject durable fenced ownership, canonical advance, clock and wake-up scheduling");
+  return {
+    wake: async () => store.withOwner(async owner => {
+      await owner.assertCurrent();
+      // A durable next wake is written BEFORE advance. Eviction during advance
+      // must not lose the next reconciliation. Scheduler callbacks may repeat.
+      await schedule(clock.now() + intervalMs);
+      const result = await advance(owner);
+      await owner.assertCurrent();
+      // The pre-advance callback may have fired and been consumed while busy.
+      // Renew it from completion time so slow advances retain a future wake.
+      await schedule(clock.now() + intervalMs);
+      return result;
+    }),
+  };
+}

package/lib/credential.mjs

@@ -0,0 +1,161 @@
+// The one place a GitHub credential for a run is resolved.
+//
+// The defect this exists for. A run is sandboxed: it cannot reach the operator's macOS keyring, their Linux secret
+// service, or `~/.git-credentials`. The credential helper used to be `!gh auth git-credential`, which asks `gh` to
+// look in exactly those places, so inside a run the helper returned nothing and `git push` failed after the work was
+// done and paid for. `runEnv` set `GH_TOKEN` only when `github_token_file` was configured, and the default is null,
+// so the common install got no credential at all.
+//
+// The fix is to resolve the credential in the DAEMON, which is not sandboxed and can reach whatever store the
+// operator actually used, and to pass it to the run in its environment. The helper then reads `$GH_TOKEN` from that
+// environment instead of shelling out to `gh`. The helper itself travels in the environment too, as one of
+// `RUN_GIT_CONFIG`'s pairs in lib/git.mjs, so a run names no file outside its worktree.
+//
+// Resolution order, first answer wins. The order is the contract; it is documented in docs/config.md and asserted
+// in the tests, because changing it silently changes which identity a run acts as.
+//
+//   1. `github_token_file` from the config. Explicit and deliberately narrow, so it keeps winning over everything
+//      below. An operator who set it has decided what a run may reach, and nothing here may widen that.
+//   2. `GH_TOKEN` or `GITHUB_TOKEN` already in the daemon's own environment. This is CI, and anyone who exports a
+//      token in a shell profile.
+//   3. Whatever `gh auth token` hands over. Asking `gh` is the honest way to cover every store `gh` supports: the
+//      macOS keyring, the Linux secret service, the plain `~/.config/gh/hosts.yml` when no keyring is available,
+//      and an enterprise host. Parsing `hosts.yml` here would reimplement `gh`'s own resolution and drift from it.
+//   4. Nothing. `resolve` returns a reason, and the caller refuses to start the run.
+//
+// Two rules hold for every path through this file, and both are about where the token must never land:
+//
+//   - Never in argv. `gh auth token --hostname <host>` puts the HOST in argv, never the token, which arrives on
+//     stdout. `ps` shows argv to every process on the machine.
+//   - This resolver writes no token to disk. The runner records argv without env in `cmd.json`. A child can
+//     still print its credential into raw `provider.log`; tracker logs redact recognized secrets but are not a
+//     complete data-loss boundary. `describe` below reports only the source and length.
+import { execFile } from "node:child_process";
+import { readText } from "./fs.mjs";
+
+const GH_TOKEN_TIMEOUT_MS = 20_000;
+
+/** Where a resolved credential came from, as a stable key. Printed and asserted on; never the token itself. */
+export const SOURCES = Object.freeze({
+  file: "github_token_file",
+  env: "daemon environment",
+  gh: "gh auth token",
+});
+
+/**
+ * The host a remote URL's credential belongs to. `gh` can be logged in to an enterprise host as well as
+ * github.com, and the token for github.com is the wrong one for `github.acme.com`.
+ *
+ * Only the host is taken, and only from a URL shape we recognise. An SSH remote has no useful host for a token
+ * (a token cannot authenticate SSH), so it reads as github.com and the caller's own remote check is what fails.
+ */
+export function hostFromRemote(url) {
+  const s = String(url || "").trim();
+  const m = s.match(/^https?:\/\/(?:[^@/]*@)?([a-z0-9.-]+)/i);
+  if (m) return m[1].toLowerCase();
+  const ssh = s.match(/^(?:ssh:\/\/)?(?:[^@/]+@)([a-z0-9.-]+)[:/]/i);
+  return ssh ? ssh[1].toLowerCase() : "github.com";
+}
+
+/** True when a host is github.com itself rather than an enterprise install. */
+export const isDotCom = host => String(host || "").toLowerCase() === "github.com";
+
+/** The token in a `github_token_file`, or empty when none is configured. */
+export const readTokenFile = file => (file ? readText(file, "").trim() : "");
+
+/** A token in the daemon's own environment, `GH_TOKEN` first. Empty when neither is set to anything. */
+export const tokenFromEnv = (env = process.env) => String(env.GH_TOKEN || env.GITHUB_TOKEN || "").trim();
+
+/**
+ * `gh auth token` for one host, or empty when `gh` has nothing for it. Never throws: a machine with no `gh`, or a
+ * `gh` that is signed out, is a reason to fall through to the next source, not a crash in the daemon.
+ *
+ * The host goes in argv. The token comes back on stdout, so it is never visible to `ps`.
+ */
+export function tokenFromGh(host = "github.com", { exec = execFileAsyncQuiet } = {}) {
+  const args = ["auth", "token"];
+  // `--hostname` is only passed for an enterprise host: an older `gh` without the flag would fail the whole lookup
+  // for the overwhelmingly common github.com case, and for github.com the flag changes nothing.
+  if (!isDotCom(host)) args.push("--hostname", host);
+  return exec("gh", args).then(out => String(out || "").trim()).catch(() => "");
+}
+
+/** execFile for a token read: stdout only, failures become empty rather than throwing, stderr is never kept. */
+function execFileAsyncQuiet(cmd, args) {
+  return new Promise(resolve => {
+    execFile(cmd, args, { encoding: "utf8", timeout: GH_TOKEN_TIMEOUT_MS, maxBuffer: 1024 * 1024 }, (err, stdout) => resolve(err ? "" : stdout));
+  });
+}
+
+/**
+ * The message a refusal carries. It names all three sources in the order they are tried, because an operator who
+ * sees this has to pick one, and the cheapest fix is nearly always the first line.
+ */
+export function noCredentialMessage(host = "github.com") {
+  const lines = [
+    "No GitHub credential could be resolved, so a run would do the work and then fail to push.",
+    "Nothing was started. Fix one of these, in the order Gallivant tries them:",
+    `  1. gh auth login${isDotCom(host) ? "" : ` --hostname ${host}`}                      (uses whatever store gh has: keyring, secret service, or hosts.yml)`,
+    "  2. export GH_TOKEN=<token>                    (in the shell that starts the daemon, or in CI)",
+    "  3. a fine-grained PAT in a file, then set github_token_file to its path in ~/.gallivant/config.json",
+  ];
+  if (!isDotCom(host)) lines.push(`The remote is on ${host}, not github.com. If gh is not logged in to ${host}, use github_token_file: a github.com token will not authenticate ${host}.`);
+  return lines.join("\n");
+}
+
+/**
+ * Resolve a credential for one host. Returns `{ token, source, host }` or `{ token: null, source: null, host, why }`.
+ * An unusable explicitly configured token file throws `NO_CREDENTIAL`; it never tries a broader source.
+ *
+ * `env` and `exec` are injected so a test can drive every branch without a `gh` on the machine and without ever
+ * putting a real token anywhere near a fixture.
+ */
+export async function resolveCredential(config, { host = "github.com", env = process.env, exec = execFileAsyncQuiet } = {}) {
+  // A configured file is an authority boundary, not merely the first candidate.
+  // Missing, unreadable or blank must not silently widen to an ambient login.
+  if (config?.github_token_file) {
+    const fromFile = readTokenFile(config.github_token_file);
+    if (fromFile) return { token: fromFile, source: SOURCES.file, host };
+    throw Object.assign(new Error("The configured github_token_file is missing, unreadable or empty. No fallback credential was used. Restore that private token file, or explicitly set github_token_file to null and restart the daemon to use environment/gh authentication."), { code: "NO_CREDENTIAL", reason: "configured-token-file-unavailable" });
+  }
+  const fromEnv = tokenFromEnv(env);
+  if (fromEnv) return { token: fromEnv, source: SOURCES.env, host };
+  const fromGh = await tokenFromGh(host, { exec });
+  if (fromGh) return { token: fromGh, source: SOURCES.gh, host };
+  return { token: null, source: null, host, why: noCredentialMessage(host) };
+}
+
+/**
+ * One line about a resolved credential, safe to log and to print. It names the source and the host and the token's
+ * length, never the token: a length is enough to tell "the file has a token in it" from "the file has a newline in
+ * it" while being useless to anyone who reads a log.
+ */
+export const describe = ({ token, source, host }) =>
+  token ? `${source}${isDotCom(host) ? "" : ` for ${host}`} (${token.length} characters)` : "none";
+
+/**
+ * The host a checkout's credential belongs to, from its `origin` remote. Failure reads as github.com, because a
+ * checkout whose remote cannot be read has a bigger problem than which host its token is for and the caller's own
+ * git operations will say so.
+ */
+export async function hostForWorktree(git, dir) {
+  try { return hostFromRemote(await git.originOf(dir)); } catch { return "github.com"; }
+}
+
+/**
+ * The credential for one entry or one request, resolved through the context's own resolver.
+ *
+ * The host is taken from the checkout's `origin` when there is a checkout, because that is the only thing that knows
+ * whether this repository lives on github.com or on an enterprise install. A repository named `owner/name` with no
+ * checkout yet (a `start` before its clone) has no host to read, so it reads as github.com, which is right for every
+ * install `gh repo clone owner/name` would resolve.
+ *
+ * `ctx.credential` is what `makeContext` builds. A context without one (every test's hand-built context) resolves
+ * from the config alone, so a test that wants a credential sets `github_token_file` and one that wants none sets
+ * nothing, and no test needs a `gh` on the machine.
+ */
+export async function resolveCredentialFor(ctx, { worktree = null } = {}) {
+  const host = worktree && ctx.git ? await hostForWorktree(ctx.git, worktree) : "github.com";
+  const resolve = ctx.credential ?? (opts => resolveCredential(ctx.config, opts));
+  return resolve({ host });
+}

package/lib/daemon.mjs

@@ -0,0 +1,156 @@
+// Process exclusion is independent of best-effort health reporting.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { execFileSync } from "node:child_process";
+import { openSync, closeSync, writeFileSync, unlinkSync, mkdirSync, rmdirSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { readJson, codeStamp } from "./fs.mjs";
+
+export const daemonPath = home => join(home, "daemon.json");
+const lockPath = home => join(home, "daemon.lock");
+const liveOwners = new WeakMap();
+const taskOwners = new AsyncLocalStorage();
+export function withTaskMutationOwner(home, owner, fn) {
+  borrowTaskMutation(home, owner);
+  return taskOwners.run({ home: resolve(home), owner }, fn);
+}
+export function acquireServiceMutation(home, owner) {
+  const inherited = taskOwners.getStore();
+  owner ||= inherited?.home === resolve(home) ? inherited.owner : null;
+  return owner ? borrowTaskMutation(home, owner) : acquireCliMutation(home);
+}
+
+// Borrow only an actual, still-held owner for this namespace.
+export function borrowTaskMutation(home, owner) {
+  const held = liveOwners.get(owner);
+  if (!held || !((held.file === resolve(home, "task-mutation.lock")) ||
+    (held.file === resolve(home, "daemon.lock") && held.purpose === "runtime"))) {
+    throw new Error("task mutation requires a live owner for this namespace");
+  }
+  return { release() {} };
+}
+
+export function processIdentity(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  try {
+    // ps formats lstart using the caller's locale and timezone. A second CLI
+    // must not mistake a formatting change for PID reuse and replace a live lock.
+    const identity = execFileSync("ps", ["-o", "lstart=", "-o", "command=", "-p", String(pid)], {
+      encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"],
+      env: { ...process.env, LC_ALL: "C", LANG: "C", TZ: "UTC" },
+    }).trim();
+    return identity ? `v2:${identity}` : null;
+  } catch { return null; }
+}
+
+export const isStableProcessIdentity = identity => typeof identity === "string" && identity.startsWith("v2:");
+export const matchesProcess = (record, identity = processIdentity(record?.pid)) => Boolean(record?.identity && record.identity === identity);
+
+export function pidExists(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
+}
+
+function clearStaleLock(file, label = "daemon") {
+  // Serialize stale-owner recovery too: two contenders must never unlink a replacement owner's lock.
+  const recovery = `${file}.recovery`;
+  try { mkdirSync(recovery, { mode: 0o700 }); }
+  catch (e) {
+    if (e.code === "EEXIST") throw new Error(`${label} lock recovery is in progress (${recovery}); retry shortly`);
+    throw e;
+  }
+  try {
+    const previous = readJson(file, null);
+    if (!previous) throw new Error(`${label} startup already in progress; retry shortly`);
+    const identity = processIdentity(previous.pid);
+    // A legacy fingerprint has no recorded locale/timezone. A mismatch cannot
+    // prove PID reuse: require that process to exit before replacing its lock.
+    if (pidExists(previous.pid) && (!isStableProcessIdentity(previous.identity) || !identity || previous.identity === identity)) throw new Error(`${label} already running (pid ${previous.pid})`);
+    unlinkSync(file);
+  } finally { rmdirSync(recovery); }
+}
+
+export function daemonRecord(home) {
+  const lock = readJson(lockPath(home), null);
+  const health = readJson(daemonPath(home), null);
+  if (!lock) return health;
+  return { ...(health?.instance === lock.instance ? health : {}), ...lock };
+}
+
+export const readDaemon = home => {
+  const d = daemonRecord(home);
+  if (!d) return null;
+  // `stale` is the code on disk being newer than the code this daemon booted with, which means it is running a version
+  // of Gallivant that no longer exists. Only meaningful while it is alive, and only when it recorded a stamp at all: a
+  // daemon from before this existed has no `code` field and must not be reported as fresh OR stale, because nothing
+  // was measured.
+  const onDisk = codeStamp();
+  const identity = processIdentity(d.pid);
+  const live = !d.stoppedAt && matchesProcess(d, identity);
+  const stale = Boolean(d.code && onDisk && live && onDisk > d.code);
+  const unverified = !d.stoppedAt && !live && pidExists(d.pid) && (!isStableProcessIdentity(d.identity) || !identity);
+  return { ...d, alive: live && d.purpose !== "runtime", runtimeBusy: live && d.purpose === "runtime", unverified, onDisk, stale };
+};
+
+
+/** Refuse an incompatible live owner; an absent daemon can still be started later. */
+export function assertDaemonUsable(daemon, { starting = false } = {}) {
+  if (starting && daemon?.runtimeBusy) throw new Error("runtime maintenance or delivery owns this namespace; retry daemon startup after it finishes");
+  if (daemon?.unverified) throw new Error(`daemon pid ${daemon.pid} has an unverifiable process identity; verify and stop the older daemon before restarting`);
+  if (daemon?.stale) throw new Error(`daemon pid ${daemon.pid} is running older code and cannot accept new requests. Restart it: gallivant down && gallivant up. Active agent runs keep going.`);
+}
+
+/** Claim before any await. Failure to publish ownership is fatal; health writes may fail later. */
+export function acquireDaemon(home) {
+  const owner = acquireProcessLock(lockPath(home));
+  try { assertUnpinnedHome(home); return owner; }
+  catch (error) { owner.release(); throw error; }
+}
+
+// Same exclusion boundary, without claiming daemon liveness or shutdown rights.
+export function acquireRuntimeOwner(home) {
+  return acquireProcessLock(lockPath(home), "runtime", "runtime");
+}
+
+export function acquireTaskMutation(home) {
+  return acquireProcessLock(join(home, "task-mutation.lock"), "task mutation");
+}
+
+export function assertUnpinnedHome(home) {
+  if (existsSync(join(home, "runtime-pin.json"))) throw Object.assign(new Error("Use the manifest-aware task delivery adapter and coordinator for this pinned namespace; ordinary CLI writes and daemon startup require an unpinned local home"), { code: "TASK_RUNTIME_PIN", version: 1 });
+}
+
+// CLI writers share maintenance exclusion and cannot write artifact-pinned homes.
+export function acquireCliMutation(home) {
+  const owner = acquireTaskMutation(home);
+  try {
+    assertUnpinnedHome(home);
+    return owner;
+  } catch (error) { owner.release(); throw error; }
+}
+
+/** Also used for long-lived intake mutations; elapsed time never expires a live owner. */
+export function acquireProcessLock(file, label = "daemon", purpose) {
+  const identity = processIdentity(process.pid);
+  if (!identity) throw new Error(`cannot identify this ${label} process; refusing to start without process exclusion`);
+  const owner = { ...(purpose ? { purpose } : {}), pid: process.pid, identity, instance: randomUUID(), startedAt: new Date().toISOString() };
+  for (;;) {
+    let fd;
+    try { fd = openSync(file, "wx", 0o600); }
+    catch (e) {
+      if (e.code !== "EEXIST") throw e;
+      clearStaleLock(file, label);
+      continue;
+    }
+    try { writeFileSync(fd, JSON.stringify(owner), { flush: true }); }
+    catch (e) { try { unlinkSync(file); } catch { /* preserve original error */ } throw e; }
+    finally { closeSync(fd); }
+    break;
+  }
+  const token = { owner, release: () => {
+    liveOwners.delete(token);
+    if (readJson(file, null)?.instance === owner.instance) unlinkSync(file);
+  } };
+  liveOwners.set(token, { file: resolve(file), purpose });
+  return token;
+}