@uchibeke/gallivant 0.0.0-stage → 0.2.1

package/lib/execution_contract.mjs

@@ -0,0 +1,15 @@
+// Portable execution metadata shared by projections and Node transport adapters.
+export const EXECUTION_TRANSPORTS = Object.freeze({
+  claude: "cli", codex: "cli", gemini: "cli", opencode: "cli", goose: "cli",
+  "openai-agents": "remote", "codex-cloud": "remote",
+});
+export const PROVIDER_STATES = Object.freeze(["queued", "provisioning", "running", "waiting-for-input", "retrieving-results", "succeeded", "failed", "cancellation-requested", "cancelled", "status-unknown"]);
+export const providerTerminal = state => ["succeeded", "failed", "cancelled"].includes(state);
+const exactIdentity = id => typeof id === "string" && !!id.trim();
+export const ownedRemoteExecution = ex => exactIdentity(ex?.providerJobId) && exactIdentity(ex?.turnId);
+export const executionLive = job => {
+  const ex = job?.execution;
+  if (!ex) return false;
+  const remote = (ex.transport ?? EXECUTION_TRANSPORTS[ex.provider]) === "remote";
+  return (remote && (ex.acceptance !== "accepted" || !ownedRemoteExecution(ex))) || !providerTerminal(ex.providerState) || !ex.collected;
+};

package/lib/execution_input.mjs

@@ -0,0 +1,4 @@
+import { agentsInput } from "./openai_agents_input.mjs";
+import { cloudInput } from "./codex_cloud_input.mjs";
+export const remoteInput = (ctx, id, entry, input, contextPaths) => entry.harness === "codex-cloud"
+  ? cloudInput(ctx, id, entry, input, contextPaths) : agentsInput(ctx, id, entry, input, contextPaths);

package/lib/execution_io.mjs

@@ -0,0 +1,94 @@
+// Every transport operation must honor signal; a missed deadline still fences its late reply.
+// A transport operation includes native verification startup as well as I/O.
+// Two seconds expired during healthy sandbox startup before any provider call.
+// Keep one configurable, bounded deadline and the existing late-reply fences.
+export const EXECUTION_LIMITS = Object.freeze({ deadlineMs: 20_000, progressMs: 10_000, maxBackoffMs: 300_000, concurrency: 4, eventBytes: 65_536, events: 100 });
+export const executionError = (code, message) => Object.assign(new Error(message), { code });
+export function accessProbeFailure(error,signal,fallback,fix=null) {
+  const timeout=error?.name==='TimeoutError' || signal?.reason?.name==='TimeoutError';
+  const aborted=signal?.aborted || error?.name==='AbortError';
+  const detail=timeout?'EXECUTION_DEADLINE':aborted?'EXECUTION_ABORTED':typeof error?.code==='string'?error.code:fallback;
+  return {ok:false,detail,fix:timeout?'Provider access check exceeded its configured deadline; inspect host/network latency and execution.deadlineMs. This read-only check did not submit implementation.':aborted?'Provider access check was cancelled; no later response authorizes implementation.':fix||redact(String(error?.message||fallback)),
+    ...(Number.isFinite(error?.retryAfterMs)?{retryAfterMs:error.retryAfterMs}:{})};
+}
+// Only deterministic validation of a completed, owned provider result uses this
+// marker. Network, authentication, missing delivery and local I/O stay retryable.
+export const collectionValidationError = message => Object.assign(executionError("EXECUTION_RESULT", message), { collectionValidation: true });
+// Provider records stay claims; the shared writer runs its own verification.
+// Each recorded command must still identify the owned revision and integer exit.
+export const validProviderTestRecords = (tests, inputHead) => Array.isArray(tests) &&
+  tests.every(record => record && typeof record.command === "string" && record.inputHead === inputHead && Number.isInteger(record.exit));
+// A trusted transport may mark only local failures before its durable operation
+// and every provider request. Error codes or missing replies alone prove nothing.
+export const dispatchNotSentError = error => Object.assign(error, { dispatchNotSent: true });
+export const EXECUTION_CURSOR_BYTES = 4096;
+export function assertExecutionCursor(cursor, { persisted = false } = {}) {
+  if (cursor == null) return;
+  // Reject objects before serialization: custom toJSON, cycles and BigInt
+  // cannot become durable paging tokens. Bound escaping and UTF-8 as saved.
+  const scalar = typeof cursor === "boolean" || (typeof cursor === "number" && Number.isFinite(cursor)) ||
+    (typeof cursor === "string" && cursor.length <= EXECUTION_CURSOR_BYTES);
+  if (!scalar || Buffer.byteLength(JSON.stringify(cursor)) > EXECUTION_CURSOR_BYTES) {
+    throw executionError("EXECUTION_PROTOCOL", persisted
+      ? "invalid persisted provider cursor; preserve the run files and restore its exact bounded provider checkpoint before restarting; do not redispatch"
+      : "provider cursor must be a JSON scalar of at most 4096 serialized UTF-8 bytes; return a bounded paging token");
+  }
+}
+// Omitted sessions retain recorded ownership; reported sessions must be exact.
+export const ownsProviderSession = (owned, reported) => reported == null ||
+  (typeof reported === "string" && !!reported.trim() && (owned == null || reported === owned));
+// A collected outcome cannot replace an authoritative root-turn observation.
+// Older collected runs may retain that observation only in providerState.
+export function assertTerminalOutcome(execution, outcome) {
+  const observed = execution?.terminalState ?? execution?.providerState;
+  if (["succeeded", "failed"].includes(observed) &&
+    (outcome?.finished !== true || typeof outcome.ok !== "boolean" || outcome.ok !== (observed === "succeeded"))) {
+    throw executionError("EXECUTION_RESULT", "result outcome contradicts the authoritative terminal root; reconcile the exact completed turn");
+  }
+}
+export async function boundedCall(fn, { deadlineMs = EXECUTION_LIMITS.deadlineMs } = {}) {
+  const controller = new AbortController();
+  let timer;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(() => fn(controller.signal)),
+      new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(executionError("EXECUTION_DEADLINE", "transport deadline exceeded; reconcile acceptance before retrying")); }, deadlineMs); }),
+    ]);
+  } finally { clearTimeout(timer); }
+}
+export function nextAttempt(now, failures, retryAfterMs = 0, limits = EXECUTION_LIMITS, jitter = Math.random) {
+  const backoff = limits.progressMs * 2 ** Math.min(failures, 10);
+  const delay = Number.isFinite(retryAfterMs) ? Math.max(0, retryAfterMs) : 0;
+  return now + Math.min(limits.maxBackoffMs, Math.max(delay, backoff + Math.floor(backoff * 0.1 * jitter())));
+}
+// Redaction precedes persistence in projections, journals and result evidence. Callers
+// also supply resolved secrets, including tokens whose formats cannot be recognized.
+export function redact(value, secrets = []) {
+  const clean = text => {
+    let out = text;
+    // Replace enclosing credentials before their substrings, regardless of
+    // environment order. Filtering produces a copy, preserving caller input.
+    for (const secret of secrets.filter(s => typeof s === "string" && s.length).sort((a, b) => b.length - a.length)) out = out.split(secret).join("[redacted]");
+    return out.replace(/\b(?:sk-[A-Za-z0-9_-]{12,}|gh[pousr]_[A-Za-z0-9_]{12,}|github_pat_[A-Za-z0-9_]{12,})\b/g, "[redacted]")
+      .replace(/(Bearer\s+)[^\s"\\]+/gi, "$1[redacted]")
+      .replace(/((?:api[_-]?key|token|password|secret|authorization)"?\s*[=:]\s*"?)[^"\s,;]+/gi, "$1[redacted]");
+  };
+  if (typeof value === "string") return clean(value);
+  if (Array.isArray(value)) return value.map(v => redact(v, secrets));
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, /^(?:api[_-]?key|token|password|secret|authorization|credentials)$/i.test(k) ? "[redacted]" : redact(v, secrets)]));
+  return value;
+}
+
+// Ownership and artifact manifests are private protocol/publication input:
+// redaction cannot change routing IDs, revisions, repository paths or hashes.
+// Callers validate ownership; public readers must redact their own projection.
+export function redactResultMetadata(result, secrets = []) {
+  const { files, artifacts: _artifacts, ...metadata } = result;
+  const clean = redact(metadata, secrets);
+  for (const key of ["taskId", "runId", "providerJobId", "sessionId", "turnId", "inputHead", "repo", "branch", "pushedHead"]) {
+    if (Object.hasOwn(result, key)) clean[key] = result[key];
+  }
+  if (files !== undefined) clean.files = structuredClone(files);
+  clean.artifacts = redact(Array.isArray(files) ? files.slice(0, 100).map(file => ({ path: file?.path, hash: file?.afterHash })) : [], secrets);
+  return clean;
+}

package/lib/execution_journal.mjs

@@ -0,0 +1,69 @@
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { existsSync, appendFileSync, fsyncSync, openSync, closeSync, statSync, readSync, truncateSync } from "node:fs";
+import { ensureDir, readJson, writeJsonAtomic } from "./fs.mjs";
+import { redact } from "./execution_io.mjs";
+import { appendProjection, LOG_LIMITS } from "./run_log.mjs";
+export const JOURNAL_VERSION = 1;
+const size = file => { try { return statSync(file).size; } catch { return 0; } };
+export function journalFor(dir, { taskId, runId, provider, secrets = [] }) {
+  ensureDir(dir);
+  const stateFile = join(dir, "journal.json"), events = join(dir, "events.jsonl");
+  const keys = ensureDir(join(dir, "event-keys"));
+  const load = () => {
+    const s = readJson(stateFile, { version: JOURNAL_VERSION, sequence: 0 });
+    if (s.version !== JOURNAL_VERSION) throw new Error("unsupported journal version; restore a matching backup/package before replay");
+    return s;
+  };
+  const project = record => appendProjection(dir, typeof record.data === "string" && record.data ? record.data : JSON.stringify(record), { sequence: record.sequence });
+  // Repair an interrupted append before accepting another event. Inspect at most
+  // one bounded record at the saved offset, never scan the journal in full.
+  const recover = () => {
+    const s = load(), pending = s.pending;
+    if (!pending) return;
+    let record = null, terminated = false;
+    if (existsSync(events)) {
+      if (size(events) < pending.offset) throw new Error("acknowledged journal prefix is truncated; preserve the run files and restore a matching journal backup before replay");
+      const fd = openSync(events, "r");
+      try {
+        const buf = Buffer.alloc(LOG_LIMITS.lineBytes + 1);
+        const n = readSync(fd, buf, 0, buf.length, pending.offset);
+        terminated = buf.subarray(0, n).includes(10);
+        try { record = JSON.parse(buf.subarray(0, n).toString("utf8").split("\n")[0]); } catch { /* interrupted record */ }
+      } finally { closeSync(fd); }
+    }
+    if (record?.sequence !== s.sequence) {
+      record = { version: JOURNAL_VERSION, taskId, runId, provider, sequence: s.sequence, eventId: pending.eventId, timestamp: pending.timestamp, type: "gap", provenance: "coordinator", data: "interrupted journal append; this event's history is unrecoverable" };
+      // Preserve the acknowledged prefix and remove partial/invalid JSON before
+      // replacing the pending event. The acknowledged prefix must stay intact.
+      if (existsSync(events)) truncateSync(events, pending.offset);
+      appendFileSync(events, JSON.stringify(record) + "\n", { mode: 0o600, flush: true });
+    } else if (!terminated) {
+      // The JSON was fully written but its delimiter was not acknowledged.
+      appendFileSync(events, "\n", { mode: 0o600, flush: true });
+    }
+    writeJsonAtomic(join(keys, pending.hash), { sequence: s.sequence, eventId: pending.eventId });
+    if (Math.floor(size(join(dir, "job.idx")) / 8) < s.sequence) project({ ...record, type: "gap", data: "[gap: interrupted projection recovered; consult normalized history]" });
+    writeJsonAtomic(stateFile, { version: JOURNAL_VERSION, sequence: s.sequence });
+  };
+  recover();
+  return { recover, append(input) {
+    if (typeof input.eventId !== "string" || !input.eventId || input.eventId.length > 512) throw new Error("journal requires a bounded provider event identity");
+    recover();
+    const state = load();
+    const identity = [provider, input.providerJobId ?? null, input.turnId ?? null, input.eventId];
+    const hash = createHash("sha256").update(JSON.stringify(identity)).digest("hex");
+    const key = join(keys, hash);
+    if (existsSync(key)) return readJson(key);
+    const sequence = state.sequence + 1;
+    let record = redact({ ...input, providerSequence: input.sequence ?? null, version: JOURNAL_VERSION, taskId, runId, provider, sequence, provenance: input.provenance || "provider", timestamp: input.timestamp ?? Date.now() }, secrets);
+    if (Buffer.byteLength(JSON.stringify(record)) + 1 > LOG_LIMITS.lineBytes) record = { version: JOURNAL_VERSION, taskId, runId, provider, sequence, eventId: record.eventId, type: "gap", timestamp: record.timestamp, provenance: record.provenance, data: "oversized provider record omitted" };
+    writeJsonAtomic(stateFile, { version: JOURNAL_VERSION, sequence, pending: { hash, eventId: record.eventId, timestamp: record.timestamp, offset: size(events) } });
+    appendFileSync(events, JSON.stringify(record) + "\n", { mode: 0o600, flush: true });
+    writeJsonAtomic(key, { sequence, eventId: record.eventId });
+    project(record);
+    for (const file of ["job.log", "job.idx"]) { const fd = openSync(join(dir, file), "r"); try { fsyncSync(fd); } finally { closeSync(fd); } }
+    writeJsonAtomic(stateFile, { version: JOURNAL_VERSION, sequence });
+    return { sequence, eventId: record.eventId };
+  } };
+}

package/lib/execution_preparation.mjs

@@ -0,0 +1,29 @@
+// Local preparation is an execution operation with a smaller adapter authority.
+// A private HOME alone never qualifies that authority. Native policy lives in
+// the selected capability, not in task drafting/clarification/repair callers.
+import { buildPreparationRun, adapterFor, preparationReceipt, assertSafeArgv, assertSafeEnv } from "./harness.mjs";
+import { preparationEnvironment } from "./task_environment.mjs";
+import { requireHarness } from "./probe.mjs";
+import { ensureDir } from "./fs.mjs";
+import { MAX_PREPARATION_PROMPT_BYTES } from "./task_contract.mjs";
+import { taskError } from "./task_store.mjs";
+import { boundedCall } from "./execution_io.mjs";
+
+export async function prepareLocalExecution(provider, capabilities, account, input, build = buildPreparationRun, limits = {}) {
+  const receipt = preparationReceipt(provider, capabilities, account);
+  const adapter = adapterFor(provider);
+  let spec = build({ harness: provider, config: input.config, mode: "start", session: adapter.newSession(), prompt: input.prompt, cwd: input.cwd }, capabilities);
+  const check = () => {
+    if (spec.boundary !== receipt.boundary) throw taskError("TASK_PREPARATION_BOUNDARY", "preparation builder returned a different authority; no provider call was made");
+    assertSafeArgv(spec.args);
+    if (typeof spec.args.at(-1) !== "string" || Buffer.byteLength(spec.args.at(-1)) > MAX_PREPARATION_PROMPT_BYTES) throw taskError("TASK_INPUT", `serialized preparation prompt exceeds ${MAX_PREPARATION_PROMPT_BYTES} bytes; select fewer or smaller context files, or prepare a smaller task; saved requirements were retained`);
+  };
+  check(); // Reject oversized input before a probe or launch intent.
+  await requireHarness(provider, input.config, { minimumVersion: spec.minimumVersion });
+  ensureDir(input.cwd);
+  const env = preparationEnvironment(provider, input.cwd, spec.env, input.sourceEnv, input.callerCwd);
+  if (spec.configure) spec = await boundedCall(signal => spec.configure(spec, { cwd: input.cwd, env, signal }), limits);
+  check(); // An adapter's final configuration cannot replace its authority.
+  assertSafeEnv(env);
+  return { receipt, environment: input.environment, spec: { cmd: spec.cmd, args: spec.args, options: { cwd: input.cwd, env, inheritEnv: false } } };
+}

package/lib/execution_result.mjs

@@ -0,0 +1,266 @@
+// Result transport ends here. Git/gh own the one publication path; the existing
+// tick still owns readiness, receipts, review rounds, conflicts and human merge.
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { unlinkSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { repositoryPath, repositoryRelativePath, assertRepositoryTargets, readRepositoryText, writeRepositoryText } from "./repository_files.mjs";
+import { isOurBranch, runEnv } from "./git.mjs";
+import { ensureDir, readJson, writeJsonAtomic } from "./fs.mjs";
+import { execFileAsync, remoteMatches } from "./gh.mjs";
+import { parsePrd, verifyCommands } from "./prd.mjs";
+import { normalizePublicBody } from "./block.mjs";
+import { assertPublicText, assertNoNul } from "./public_output.mjs";
+import { executionError, ownsProviderSession, assertTerminalOutcome, redact } from "./execution_io.mjs";
+import { acquireProcessLock } from "./daemon.mjs";
+import { idSlug } from "./state.mjs";
+import { prepareVerificationSandbox, validVerificationSandbox, verificationSandboxUnavailable } from "./verification_sandbox.mjs";
+const hash = text => text === null ? null : createHash("sha256").update(text).digest("hex");
+
+// Verification executes provider-controlled code, never coordinator credentials.
+// Keep only tooling/display basics and an empty private profile for this list.
+export function verificationEnvironment(root, source = process.env) {
+  const basics = ["PATH", "LANG", "LC_ALL", "LC_CTYPE", "TZ", "TERM", "COLORTERM", "NO_COLOR", "FORCE_COLOR", "CI"];
+  const env = Object.fromEntries(basics.filter(key => typeof source[key] === "string").map(key => [key, source[key]]));
+  const git = runEnv(), count = Number(git.GIT_CONFIG_COUNT);
+  const npmUser = join(root, "npm-user.conf"), npmGlobal = join(root, "npm-global.conf");
+  // npm rejects one file loaded twice as both user and global configuration.
+  for (const path of [npmUser, npmGlobal]) writeFileSync(path, "", { mode: 0o600 });
+  return { ...env, PATH: env.PATH || "/usr/bin:/bin", ...git,
+    [`GIT_CONFIG_KEY_${count}`]: "credential.helper", [`GIT_CONFIG_VALUE_${count}`]: "", GIT_CONFIG_COUNT: String(count + 1),
+    HOME: root, USERPROFILE: root, XDG_CONFIG_HOME: ensureDir(join(root, "config")), XDG_DATA_HOME: ensureDir(join(root, "data")),
+    XDG_STATE_HOME: ensureDir(join(root, "state")), XDG_CACHE_HOME: ensureDir(join(root, "cache")),
+    TMPDIR: ensureDir(join(root, "tmp")), TMP: join(root, "tmp"), TEMP: join(root, "tmp"),
+    GH_CONFIG_DIR: ensureDir(join(root, "gh")), GH_PROMPT_DISABLED: "1", GIT_TERMINAL_PROMPT: "0",
+    GIT_SSH_COMMAND: "false", GIT_ASKPASS: "false", SSH_ASKPASS: "false", NPM_CONFIG_USERCONFIG: npmUser, NPM_CONFIG_GLOBALCONFIG: npmGlobal };
+}
+
+// Readiness uses the same native enforcement and empty profile as publication,
+// in disposable directories before a checkout exists. No repository code runs.
+export async function checkVerificationSandbox({ signal, sandbox = prepareVerificationSandbox } = {}) {
+  let root;
+  try {
+    signal?.throwIfAborted();
+    root = mkdtempSync(join(tmpdir(), "verification-readiness-"));
+    const worktree = ensureDir(join(root, "checkout")), home = ensureDir(join(root, "profile"));
+    const result = await sandbox({ worktree, home, env: verificationEnvironment(home), signal });
+    signal?.throwIfAborted();
+    if (!validVerificationSandbox(result?.evidence)) throw verificationSandboxUnavailable();
+    return { ok: true, detail: `${result.evidence.driver} filesystem/network enforcement passed`, evidence: result.evidence };
+  } catch {
+    const failure = verificationSandboxUnavailable();
+    return { ok: false, detail: failure.code, fix: failure.message };
+  } finally { if (root) rmSync(root, { recursive: true, force: true }); }
+}
+
+export async function requireVerificationSandbox(options) {
+  const result = await checkVerificationSandbox(options);
+  if (!result.ok) throw executionError(result.detail, result.fix);
+  return result.evidence;
+}
+
+export function executionResultCheckpoint(execution, run = execution?.current?.()) {
+  return run && execution?.dirOf ? readJson(join(execution.dirOf(run.id), "result-application.json")) : null;
+}
+
+// Queueing a stop and starting publication have one order across processes.
+// Progress holds only execution.lock, so it cannot prevent queueing cancellation.
+// Publication takes publication.lock first, then the existing execution lock to
+// exclude direct stop/dispatch controls until its external writes are finished.
+export function acquirePublicationLock(ctx, id, { execution, dir, ownsExecution = false } = {}) {
+  const boundary = typeof execution?.state === "function" && typeof execution.root === "string";
+  const root = boundary ? execution.root : ctx.home ? join(ctx.home, "runs", idSlug(id)) : dir;
+  let publication, owned;
+  try {
+    publication = acquireProcessLock(join(ensureDir(root), "publication.lock"), "publication");
+    if (ownsExecution && boundary) owned = acquireProcessLock(join(root, "execution.lock"), "execution");
+    return { release: () => { try { owned?.release(); } finally { publication.release(); } } };
+  } catch (error) {
+    publication?.release();
+    if (/already running|startup already in progress|lock recovery is in progress/.test(error.message)) {
+      throw executionError("EXECUTION_PUBLICATION_BUSY", "Publication or execution is in progress; retry cancellation or publication after it finishes. No cancellation was queued.");
+    }
+    throw error;
+  }
+}
+
+export async function reconcileExecutionResult(ctx, input) {
+  const checkpoint = join(input.dir, "result-application.json");
+  if (readJson(checkpoint)?.phase === "blocked") throw executionError("EXECUTION_RESULT_BLOCKED", "result publication is blocked; inspect result-application.json, result.json and any verification.json, then explicitly resume for correction");
+  try { return await applyExecutionResult(ctx, input); }
+  catch (error) {
+    if (error.code === "EXECUTION_RESULT" && error.publicationValidation) {
+      const prior = readJson(checkpoint, {});
+      writeJsonAtomic(checkpoint, { ...prior, fingerprint: prior.fingerprint ?? hash(JSON.stringify(input.result)),
+        phase: "blocked", reason: "result-validation", blockedAt: new Date().toISOString() });
+    }
+    throw error;
+  }
+}
+
+async function applyExecutionResult(ctx, { id, entry, result, dir, verify = execFileAsync, sandbox = prepareVerificationSandbox }) {
+  // Collection and unavailable I/O remain retryable; rejected owned publication
+  // input requires an explicit corrective run, with no repeated application.
+  const fail = (message, retryable = false) => { throw Object.assign(executionError("EXECUTION_RESULT", message), { publicationValidation: !retryable }); };
+  const validate = fn => { try { return fn(); } catch (error) { if (error.code) throw error; fail(error.message); } };
+  const execution = ctx.executionFor?.(id, entry.harness);
+  const assertNotStopped = () => {
+    const current = ctx.state?.get(id) || entry;
+    const owned = execution?.state?.();
+    if (current.dispatch_stopped || current.execution?.quarantined || owned?.stopped || owned?.current?.execution.quarantined) fail("late results are quarantined after a concurrent stop", true);
+  };
+  assertNotStopped();
+  const ex = entry.execution;
+  if (!result || typeof result !== "object" || Array.isArray(result)) fail("result requires a bounded object manifest");
+  if (!ex || result.taskId !== id || result.runId !== ex.runId || result.providerJobId !== ex.providerJobId || result.turnId !== ex.turnId || result.inputHead !== ex.inputHead || !ownsProviderSession(ex.sessionId, result.sessionId)) fail("result does not belong to this task/run/root turn/input head/session");
+  try { assertTerminalOutcome(ex, result.outcome); } catch (error) { fail(error.message); }
+  if (result.outcome?.ok === false) fail("failed root-turn results cannot authorize publication; preserve diagnostics and explicitly resume for correction");
+  if (entry.dispatch_stopped || ex.quarantined || ["cancelled", "cancellation-requested"].includes(ex.providerState)) fail("late results are quarantined", true);
+  if (!isOurBranch(entry.branch) || entry.branch === entry.base || result.repo !== entry.repo || result.branch !== entry.branch) fail("result branch is not owned by the task");
+  if (await ctx.git.currentBranch(entry.worktree) !== entry.branch || !remoteMatches(await ctx.git.originOf(entry.worktree), entry.repo)) fail("checkout repository/branch differs from recorded ownership");
+  if (!/^[a-f0-9]{40,64}$/.test(result.inputHead || "")) fail("result requires an exact input revision");
+  if (!result.pr || typeof result.pr.title !== "string" || typeof result.pr.body !== "string") fail("result requires a reviewable PR title and receipt body");
+  validate(() => assertPublicText(result.pr.title, "PR title"));
+  validate(() => assertNoNul(result.pr.body, "PR body"));
+  const body = validate(() => normalizePublicBody(result.pr.body, { identity: { prd: entry.prd, harness: entry.harness, session: entry.session || result.sessionId, branch: entry.branch }, taskId: id }));
+  validate(() => assertPublicText(body, "PR body"));
+  const checkpoint = join(dir, "result-application.json");
+  const prior = readJson(checkpoint, {});
+  const fingerprint = hash(JSON.stringify(result));
+  if (prior.fingerprint && prior.fingerprint !== fingerprint) fail("run already owns a different result; inspect the application checkpoint");
+  const block = (reason, message, appliedHead = prior.appliedHead) => {
+    writeJsonAtomic(checkpoint, { ...readJson(checkpoint, {}), fingerprint, phase: "blocked", appliedHead, reason, blockedAt: new Date().toISOString() });
+    throw executionError("EXECUTION_RESULT_BLOCKED", `${message}; preserve the checkout and verification.json, then explicitly resume the same session for a corrective run`);
+  };
+  if (prior.phase === "blocked") throw executionError("EXECUTION_RESULT_BLOCKED", "result publication is blocked; inspect verification.json and explicitly resume the same session for a corrective run");
+  // Commands can have side effects. A lost verification acknowledgement cannot
+  // be repaired by replaying the command list on the next coordinator poll.
+  if (prior.phase === "verifying") block("verification-interrupted", "verification acknowledgement is unresolved; commands will not be replayed");
+  if (prior.phase === "published") return { head: prior.appliedHead, pr: { number: prior.pr, url: prior.url }, evidence: readJson(join(dir, "verification.json"), {}).evidence || [] };
+  const verified = prior.phase === "verified";
+  const head = await ctx.git.head(entry.worktree);
+  const validateTargets = async paths => {
+    let tracked;
+    try { tracked = await ctx.git.trackedPaths(entry.worktree); }
+    catch { fail("tracked repository paths unavailable; preserve the checkout and retrieve complete Git path metadata before publication", true); }
+    try { assertRepositoryTargets([], tracked); }
+    catch (error) { fail(error.message, true); }
+    try { assertRepositoryTargets(paths ?? tracked, tracked); }
+    catch (error) { fail(error.message); }
+  };
+  if (result.pushedHead) {
+    if (result.files?.length || await ctx.gh.refSha(entry.repo, entry.branch) !== result.pushedHead || !await ctx.gh.containsCommit(entry.repo, entry.branch, result.inputHead)) fail("pushed result revision or input ancestry cannot be verified");
+    if (head !== result.pushedHead) fail("reconcile the exact pushed provider branch into its isolated checkout before collection");
+    await validateTargets();
+  } else {
+    if (!Array.isArray(result.files) || !result.files.length || result.files.length > 100 || Buffer.byteLength(JSON.stringify(result.files)) > 1_048_576) fail("missing, truncated or oversized artifact manifest; use bounded verified artifacts");
+    const paths = new Set(), changes = [];
+    for (const file of result.files) {
+      if (!file || (file.text !== null && typeof file.text !== "string") || file.text?.includes("\0")) fail("duplicate or invalid result file");
+      const path = validate(() => repositoryRelativePath(entry.worktree, file.path, { allowMissingParents: true }));
+      paths.add(path);
+      changes.push({ ...file, path });
+    }
+    await validateTargets(changes.map(file => file.path));
+    let modesMatch;
+    try { modesMatch = await ctx.git.resultModesMatch(entry.worktree, result.inputHead, [...paths]); }
+    catch { fail("artifact mode metadata unavailable; retrieve complete input, HEAD, index and filesystem modes before publication", true); }
+    if (typeof modesMatch !== "boolean") fail("artifact mode metadata unavailable; retrieve complete input, HEAD, index and filesystem modes before publication", true);
+    if (modesMatch !== true) fail("artifact target mode differs from its input revision; text artifacts cannot authorize mode changes");
+    if (!verified) {
+      // Resolve the entire manifest before reading content or applying any file.
+      // Commit/recovery ownership uses these same canonical repository targets.
+      for (const file of changes) {
+        let current = null;
+        try { current = validate(() => readRepositoryText(entry.worktree, file.path)); } catch (e) { if (e.code !== "ENOENT") throw e; }
+        if (file.afterHash !== hash(file.text)) fail("artifact content hash differs; result may be truncated");
+        if (hash(current) !== file.beforeHash && hash(current) !== file.afterHash) fail("artifact base differs from owned checkout");
+        file.current = current;
+      }
+      if (head !== result.inputHead && head !== prior.appliedHead) {
+        const applied = changes.every(file => hash(file.current) === file.afterHash);
+        if (!applied || !ctx.git.resultHeadMatches || !await ctx.git.resultHeadMatches(entry.worktree, result.inputHead, [...paths])) fail("input head changed; reconcile before applying a result");
+      }
+      assertNotStopped();
+      writeJsonAtomic(checkpoint, { ...prior, fingerprint, phase: "applying", paths: [...paths] });
+      for (const file of changes) if (hash(file.current) !== file.afterHash) {
+        if (file.text === null) unlinkSync(validate(() => repositoryPath(entry.worktree, file.path)));
+        else validate(() => writeRepositoryText(entry.worktree, file.path, file.text));
+      }
+      await ctx.git.commitResult(entry.worktree, [...paths]);
+    }
+  }
+  const appliedHead = verified ? prior.appliedHead : await ctx.git.head(entry.worktree);
+  const assertVerifiedTree = async () => {
+    let revision, tree;
+    try {
+      revision = await ctx.git.head(entry.worktree);
+      tree = await ctx.git.dirty(entry.worktree, { strict: true });
+    } catch { block("verification-state-unavailable", "cannot verify the checkout revision and clean index/worktree", appliedHead); }
+    if (revision !== appliedHead) block("verification-head-changed", "verification changed the input head; review that change before publishing", appliedHead);
+    if (!tree || ![tree.modified, tree.untracked].every(count => Number.isInteger(count) && count >= 0)) block("verification-state-unavailable", "cannot verify clean index/worktree status", appliedHead);
+    if (tree.modified || tree.untracked) block("verification-dirty", "verification requires a clean index/worktree; preserve uncommitted files before correction", appliedHead);
+  };
+  await assertVerifiedTree();
+  const evidenceFile = join(dir, "verification.json");
+  const savedEvidence = readJson(evidenceFile, {});
+  let commands;
+  try { commands = verifyCommands(parsePrd(ctx.readPrd(id), `${id}.md`)); }
+  catch { block("verification-brief-unavailable", "cannot read the approved verification commands", appliedHead); }
+  const evidence = verified ? savedEvidence.evidence : [];
+  if (verified && (savedEvidence.head !== appliedHead || !Array.isArray(evidence) || evidence.length !== commands.length || evidence.some((item, i) => item.command !== commands[i] || item.head !== appliedHead || item.exit !== 0 || item.source !== "coordinator-executed" || !validVerificationSandbox(item.sandbox)))) {
+    block("verification-evidence-unavailable", "saved verification evidence does not cover this revision, approved command list and enforced OS sandbox", appliedHead);
+  }
+  const saveEvidence = () => writeJsonAtomic(evidenceFile, { version: 1, head: appliedHead, evidence });
+  const secrets = Object.entries(process.env).filter(([key]) => /token|password|secret|api.?key/i.test(key)).map(([, value]) => value);
+  const cleanOutput = output => execution?.sanitize ? execution.sanitize(output, ex.runId, secrets) : redact(output, secrets);
+  if (!verified) {
+    writeJsonAtomic(checkpoint, { fingerprint, phase: "verifying", appliedHead });
+    saveEvidence();
+  }
+  let verificationHome;
+  try {
+    const env = !verified && commands.length ? verificationEnvironment(verificationHome = mkdtempSync(join(dir, "verification-"))) : null;
+    let isolation;
+    if (env) {
+      try {
+        isolation = await sandbox({ worktree: entry.worktree, home: verificationHome, env });
+        if (!validVerificationSandbox(isolation?.evidence)) throw executionError("EXECUTION_VERIFICATION_SANDBOX", "verification sandbox did not supply enforcement evidence");
+      } catch (error) {
+        block("verification-sandbox-unavailable", cleanOutput(error.message), appliedHead);
+      }
+      assertNotStopped();
+    }
+    for (const command of verified ? [] : commands) {
+      assertNotStopped();
+      const startedAt = new Date().toISOString();
+      try {
+        const observed = await verify(isolation.cmd, [...isolation.args, "/bin/sh", "-c", command], { cwd: entry.worktree, timeout: 120_000, maxBuffer: 262_144, env });
+        evidence.push({ command, head: appliedHead, startedAt, finishedAt: new Date().toISOString(), exit: 0, source: "coordinator-executed", sandbox: isolation.evidence, output: cleanOutput(`${observed.stdout || ""}${observed.stderr || ""}`) });
+      } catch (e) {
+        evidence.push({ command, head: appliedHead, startedAt, finishedAt: new Date().toISOString(), exit: typeof e.code === "number" ? e.code : null, source: "coordinator-executed", sandbox: isolation.evidence, output: cleanOutput(`${e.stdout || ""}${e.stderr || ""}`) });
+        saveEvidence();
+        block("verification-failed", "approved verification failed", appliedHead);
+      }
+      saveEvidence();
+      await assertVerifiedTree();
+    }
+  } finally {
+    if (verificationHome) rmSync(verificationHome, { recursive: true, force: true });
+  }
+  // Empty checks remain empty evidence, never a claim that tests passed.
+  saveEvidence();
+  await assertVerifiedTree();
+  writeJsonAtomic(checkpoint, { fingerprint, phase: "verified", appliedHead });
+  const exclusion = acquirePublicationLock(ctx, id, { execution, dir, ownsExecution: true });
+  try {
+    assertNotStopped();
+    if (execution?.current && execution.current()?.id !== result.runId) fail("publication root changed; reconcile the exact owned result before publishing", true);
+    await ctx.git.pushResult(entry.worktree, entry.branch);
+    await assertVerifiedTree();
+    assertNotStopped();
+    const pr = await ctx.gh.publishResultPr({ repo: entry.repo, branch: entry.branch, base: entry.base, title: result.pr.title, body });
+    writeJsonAtomic(checkpoint, { fingerprint, phase: "published", appliedHead, pr: pr.number, url: pr.url });
+    return { head: appliedHead, pr, evidence };
+  } finally { exclusion.release(); }
+}

package/lib/fs.mjs

@@ -0,0 +1,140 @@
+// Small filesystem and path helpers shared by every module.
+//
+// Everything Gallivant owns lives under one home directory (default ~/.gallivant) so that a single `rm -rf` removes
+// it and so that permissions can be set once. Paths in config may use `~`, which is expanded here and nowhere else.
+import { homedir } from "node:os";
+import { join, dirname, resolve, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync, statSync, chmodSync, readdirSync, lstatSync, realpathSync } from "node:fs";
+
+export const HOME = homedir();
+
+/**
+ * Gallivant's own version, from its package.json, read once. Reported in the provenance an APort decision carries,
+ * so a decision can be traced to the release that asked for it. Unknown rather than fatal if the file is missing:
+ * a version string is never worth failing a run over.
+ */
+const PACKAGE = (() => {
+  try { return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")); }
+  catch { return {}; }
+})();
+export const VERSION = PACKAGE.version || "unknown";
+
+/**
+ * The published npm name, read from the same package.json. `init` prints the `npx` and `npm install -g` commands
+ * that run this package again, and a name typed into a command module would drift from the one npm publishes.
+ */
+export const PACKAGE_NAME = PACKAGE.name || "@uchibeke/gallivant";
+
+/**
+ * When the code a process is running was last changed, as the newest mtime across `lib/`. Paired with `VERSION`
+ * because `VERSION` cannot answer the question this exists for: it comes from package.json, so it stays `0.1.0`
+ * across every commit, and a daemon running code from before a fix reports the same string as one running the fix.
+ *
+ * This is for one failure and it is a bad one. `gallivant up` is long lived and node caches modules at import, so a
+ * daemon started before an upgrade keeps executing the old code with no symptom of its own. Observed: a daemon ran
+ * for three hours on a `runEnv` that predated its fix by 52 minutes, so every run it spawned failed on a gitconfig
+ * path the current code does not name, and the failure looked like a sandbox problem rather than a stale process.
+ * Every release can do this again.
+ *
+ * The newest mtime rather than a git revision, because an operator may run from a tarball or an npm install with no
+ * `.git` at all, and because what matters is whether the FILES changed, not whether a commit happened. Unknown rather
+ * than fatal, on the same reasoning as `VERSION`.
+ */
+export const codeStamp = (dir = join(dirname(fileURLToPath(import.meta.url)))) => {
+  let newest = 0;
+  const walk = d => {
+    let entries = [];
+    try { entries = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith(".")) continue;
+      const full = join(d, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.name.endsWith(".mjs")) { try { newest = Math.max(newest, statSync(full).mtimeMs); } catch { /* raced */ } }
+    }
+  };
+  walk(dir);
+  return newest ? Math.round(newest) : null;
+};
+
+/** Gallivant's own directory. Overridable for tests and for running a second instance. */
+export const gallivantHome = () => expand(process.env.GALLIVANT_HOME || "~/.gallivant");
+
+/** Expand a leading `~` and make the path absolute. Leaves absolute paths alone. */
+export function expand(p) {
+  if (!p) return p;
+  const s = String(p);
+  if (s === "~") return HOME;
+  if (s.startsWith("~/")) return join(HOME, s.slice(2));
+  return resolve(s);
+}
+
+/** Replace the home prefix with `~` for display. */
+/**
+ * A file that ships inside the package, resolved from this module so it is found wherever the package is installed.
+ * Every quickstart and one of doctor's fix lines used to name `templates/<file>` relative to the reader's cwd, which
+ * resolved only inside a clone. Paths into the package are this module's business, not a command's.
+ */
+export const templatePath = name => fileURLToPath(new URL(`../templates/${name}`, import.meta.url));
+
+export const contract = p => (p && p.startsWith(HOME) ? "~" + p.slice(HOME.length) : p);
+
+export function ensureDir(dir, mode = 0o700) {
+  mkdirSync(dir, { recursive: true, mode });
+  // mkdirSync's mode is masked by umask and ignored for existing dirs; set it explicitly for our private dirs.
+  try { chmodSync(dir, mode); } catch { /* not ours to change */ }
+  return dir;
+}
+
+export const exists = p => existsSync(p);
+
+/** True only for a directory that is there now. A file or a broken symlink is not one. */
+export const isDir = p => { try { return statSync(p).isDirectory(); } catch { return false; } };
+
+export const fileMode = p => { try { return statSync(p).mode & 0o777; } catch { return null; } };
+
+export function readText(p, fallback = null) {
+  try { return readFileSync(p, "utf8"); } catch { return fallback; }
+}
+
+export function readJson(p, fallback = null) {
+  const text = readText(p);
+  if (text === null) return fallback;
+  try { return JSON.parse(text); } catch (e) { throw new Error(`${p} is not valid JSON: ${e.message}`); }
+}
+
+/**
+ * Write JSON via a temp file and rename, so a reader never sees a half-written file and a crash mid-write leaves
+ * the previous version intact. Mode is applied to the temp file before the rename.
+ */
+export function writeJsonAtomic(p, value, mode = 0o600) {
+  ensureDir(dirname(p));
+  const tmp = `${p}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { mode, flush: true });
+  renameSync(tmp, p);
+}
+
+/**
+ * `dirMode` is for the one caller that writes outside Gallivant's own home: the PRD copied into a session's
+ * checkout, whose parent directories are part of a source tree and must not be clamped to 0o700.
+ */
+export function writeText(p, text, mode = 0o600, dirMode = 0o700) {
+  ensureDir(dirname(p), dirMode);
+  writeFileSync(p, text, { mode, flush: true });
+}
+
+export function appendLine(p, line, mode = 0o600) {
+  ensureDir(dirname(p));
+  writeFileSync(p, line.endsWith("\n") ? line : line + "\n", { flag: "a", mode });
+}
+
+// Resolve existing ancestors of fresh destinations; dangling symlinks fail closed.
+export function canonicalPath(path) {
+  path = resolve(path);
+  try { lstatSync(path); }
+  catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return join(canonicalPath(dirname(path)), basename(path));
+  }
+  return realpathSync(path);
+}