@uchibeke/gallivant 0.2.1 → 0.3.0

package/lib/git_diff.mjs

@@ -0,0 +1,121 @@
+const lines = section => section.split(/\r?\n/);
+
+function quotedPath(value) {
+  if (!value.startsWith('"')) return null;
+  const bytes = [];
+  for (let i = 1; i < value.length;) {
+    const char = value[i++];
+    if (char === '"') {
+      let path;
+      try { path = new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(bytes)); } catch { return null; }
+      return { path, rest: value.slice(i) };
+    }
+    if (char !== "\\") {
+      const point = value.codePointAt(i - 1), width = point > 0xffff ? 2 : 1;
+      bytes.push(...Buffer.from(value.slice(i - 1, i - 1 + width))); i += width - 1; continue;
+    }
+    if (i >= value.length) return null;
+    const escape = value[i++], simple = { a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13, '"': 34, "\\": 92 }[escape];
+    if (simple !== undefined) { bytes.push(simple); continue; }
+    if (!/[0-7]/.test(escape)) return null;
+    let octal = escape;
+    while (octal.length < 3 && /[0-7]/.test(value[i] || "")) octal += value[i++];
+    const byte = Number.parseInt(octal, 8);
+    if (byte > 255) return null;
+    bytes.push(byte);
+  }
+  return null;
+}
+
+function consumePath(value, expected) {
+  if (value.startsWith('"')) {
+    const parsed = quotedPath(value);
+    return parsed?.path === expected ? parsed.rest : null;
+  }
+  return value.startsWith(expected) ? value.slice(expected.length) : null;
+}
+
+function pathLineMatches(value, expected, allowMetadata = false) {
+  const rest = consumePath(value, expected);
+  return rest === "" || allowMetadata && rest?.startsWith("\t");
+}
+
+function diffHeaderMatches(line, oldPath, newPath) {
+  if (!line?.startsWith("diff --git ")) return false;
+  const first = consumePath(line.slice("diff --git ".length), `a/${oldPath}`);
+  if (!first?.startsWith(" ")) return false;
+  return pathLineMatches(first.slice(1), `b/${newPath}`);
+}
+
+/** Match one complete raw Git diff section to one host changed-path record. */
+export function gitDiffSectionMatches(section, { status, oldPath, newPath, binary = false }) {
+  if (typeof section !== "string" || !["added", "modified", "removed", "renamed"].includes(status)) return false;
+  const oldName = oldPath ?? newPath, newName = newPath ?? oldPath, rows = lines(section);
+  if (!oldName || !newName || !diffHeaderMatches(rows[0], oldName, newName)) return false;
+  if (binary && rows.some(row => /^Binary files .+ and .+ differ$/.test(row))) return true;
+  const marker = (prefix, path) => rows.some(row => row.startsWith(`${prefix} `) && pathLineMatches(row.slice(prefix.length + 1), path, true));
+  const metadata = (prefix, path) => rows.some(row => row.startsWith(prefix) && pathLineMatches(row.slice(prefix.length), path));
+  const oldMarker = marker("---", `a/${oldName}`), newMarker = marker("+++", `b/${newName}`), hasMarkers = rows.some(row => /^(?:---|\+\+\+) /.test(row));
+  if (status === "added") return marker("---", "/dev/null") && newMarker || rows.some(row => /^new file mode [0-7]{6}$/.test(row)) && !hasMarkers;
+  if (status === "removed") return oldMarker && marker("+++", "/dev/null") || rows.some(row => /^deleted file mode [0-7]{6}$/.test(row)) && !hasMarkers;
+  if (status === "renamed") return metadata("rename from ", oldName) && metadata("rename to ", newName) || oldMarker && newMarker;
+  return oldMarker && newMarker || rows.some(row => /^old mode [0-7]{6}$/.test(row)) && rows.some(row => /^new mode [0-7]{6}$/.test(row)) && !hasMarkers;
+}
+
+/** Non-deleted destinations in a complete host diff, including quoted names and binary/mode-only changes. */
+export function gitDiffChangedPaths(diff) {
+  if (typeof diff !== "string") throw new Error("publication diff is unavailable");
+  if (!diff.trim()) return [];
+  if (!diff.startsWith("diff --git ")) throw new Error("publication diff has no complete Git file header");
+  const result = [];
+  const decode = value => {
+    if (!value.startsWith('"')) return value;
+    const parsed = quotedPath(value);
+    if (!parsed || parsed.rest && !parsed.rest.startsWith("\t")) throw new Error("publication diff has an invalid quoted path");
+    return parsed.path;
+  };
+  for (const section of diff.split(/(?=^diff --git )/m)) {
+    const rows = lines(section), header = rows[0];
+    // Read metadata only: hunk contents can contain lines that resemble headers.
+    const end = rows.findIndex(row => row.startsWith("@@") || row === "GIT binary patch");
+    const metadata = end < 0 ? rows : rows.slice(0, end);
+    if (metadata.some(row => /^deleted file mode [0-7]{6}$/.test(row) || row === "+++ /dev/null")) continue;
+    const destination = metadata.find(row => row.startsWith("+++ "));
+    const rename = metadata.find(row => row.startsWith("rename to ") || row.startsWith("copy to "));
+    let path;
+    if (destination) {
+      const value = destination.slice(4);
+      const decoded = decode(value.startsWith('"') ? value : value.split("\t")[0]);
+      if (!decoded.startsWith("b/")) throw new Error("publication diff has an invalid destination");
+      path = decoded.slice(2);
+      if (!rows.some(row => row.startsWith("@@"))) throw new Error("publication diff has no content hunk");
+    } else if (rename) path = decode(rename.slice(rename.startsWith("rename") ? 10 : 8));
+    else {
+      if (!rows.some(row => /^(?:new file mode |old mode |Binary files |GIT binary patch$)/.test(row))) throw new Error("publication diff has incomplete file metadata");
+      // Git omits ---/+++ for binary and mode-only changes. Their same-path
+      // header is unambiguous even when an unquoted filename contains spaces.
+      const value = header.slice("diff --git ".length);
+      if (value.startsWith('"')) {
+        const first = quotedPath(value);
+        if (!first?.path.startsWith("a/") || !first.rest.startsWith(" ")) throw new Error("publication diff has an invalid file header");
+        const second = decode(first.rest.slice(1));
+        if (second !== `b/${first.path.slice(2)}`) throw new Error("publication diff has an ambiguous destination");
+        path = second.slice(2);
+      } else {
+        const candidates = [...value.matchAll(/ b\//g)].map(match => [value.slice(0, match.index), value.slice(match.index + 1)])
+          .filter(([oldPath, newPath]) => oldPath.startsWith("a/") && oldPath.slice(2) === newPath.slice(2));
+        if (candidates.length !== 1) throw new Error("publication diff has an ambiguous destination");
+        path = candidates[0][1].slice(2);
+      }
+    }
+    if (!path) throw new Error("publication diff has an empty destination");
+    const original = metadata.find(row => row.startsWith("rename from ") || row.startsWith("copy from "));
+    const oldMarker = metadata.find(row => row.startsWith("--- a/") || row.startsWith('--- "a/'));
+    const oldValue = oldMarker?.slice(4);
+    const oldPath = original ? decode(original.slice(original.startsWith("rename") ? 12 : 10))
+      : oldValue ? decode(oldValue.startsWith('"') ? oldValue : oldValue.split("\t")[0]).slice(2) : path;
+    if (!diffHeaderMatches(header, oldPath, path)) throw new Error("publication diff destination differs from its file header");
+    result.push(path);
+  }
+  return [...new Set(result)];
+}

package/lib/harness.mjs

@@ -8,7 +8,7 @@
 // Coding/push evidence and current blocks are separate: docs/audit/harness-live-validation.md.
 import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
-import { runtimeEnvironment } from "./runtime-environment.mjs";
+import { runtimeEnvironment, CLAUDE_FOREGROUND_ENV } from "./runtime-environment.mjs";
 import { codexPreparation } from "./preparation_codex.mjs";
 import { agentsPreparation } from "./preparation_agents.mjs";
 import { CLOUD_DISPATCH_UNAVAILABLE } from "./codex_cloud_config.mjs";
@@ -32,8 +32,9 @@ const CODEX_OVERRIDES = [
 const GEMINI_COMMON = ["--output-format", "stream-json", "-p"];
 const GOOSE_COMMON = ["--output-format", "stream-json"];
 
-const claudeCommon = ({ budget, settings }) => [
+const claudeCommon = ({ budget, settings, foreground }) => [
   "-p", "--permission-mode", "auto", "--permission-prompts", "none",
+  ...(foreground ? ["--disallowedTools", "Monitor"] : []),
   "--max-budget-usd", String(budget), "--settings", settings,
   "--output-format", "stream-json", "--verbose",
 ];
@@ -111,12 +112,15 @@ export const adapters = {
     newSession: () => randomUUID(),
     // `--session-id` takes a UUID and claude refuses anything else, so that is exactly what a block may carry.
     isSession: s => UUID.test(s),
-    start: ({ session, prompt, budget, settings }) => ["--session-id", session, ...claudeCommon({ budget, settings }), prompt],
-    resume: ({ session, prompt, budget, settings }) => ["--resume", session, ...claudeCommon({ budget, settings }), prompt],
-    env: ({ configDir }) => (configDir ? { APORT_CLAUDE_CODE_CONFIG_DIR: configDir } : {}),
+    start: ({ session, prompt, budget, settings, foreground = true }) => ["--session-id", session, ...claudeCommon({ budget, settings, foreground }), prompt],
+    resume: ({ session, prompt, budget, settings, foreground = true }) => ["--resume", session, ...claudeCommon({ budget, settings, foreground }), prompt],
+    env: ({ configDir }) => ({ ...CLAUDE_FOREGROUND_ENV, ...(configDir ? { APORT_CLAUDE_CODE_CONFIG_DIR: configDir } : {}) }),
     sessionFrom: lines => findLast(lines, ev => ev.type === "system" && ev.subtype === "init")?.session_id ?? null,
     outcome(lines) {
-      const result = findLast(lines, ev => ev.type === "result");
+      // A resumed Monitor may emit an empty successful notification result
+      // before the user's turn has even begun (or after that turn failed).
+      // It cannot settle the worker or mask a terminal provider error.
+      const result = findLast(lines, ev => ev.type === "result" && ev.origin?.kind !== "task-notification");
       const lastText = findLast(lines, ev => ev.type === "assistant")?.message?.content?.filter(c => c.type === "text").map(c => c.text).join("\n") ?? null;
       if (!result) return { ok: false, finished: false, lastMessage: lastText, denials: [], cost: null, error: "no result event" };
       const reasons = denialReasons(lines);
@@ -333,14 +337,14 @@ export const adapters = {
 // Remote providers implement transport; the coordinator owns review decisions.
 export const executionRegistry = Object.freeze({
   ...Object.fromEntries(Object.entries(adapters).map(([name, adapter]) => [name, Object.freeze({
-    name, adapter, available: true, transport: EXECUTION_TRANSPORTS[name], authentication: "operator-cli",
+    name, adapter, available: true, repositoryAccess: { mode: "local-worktree" }, transport: EXECUTION_TRANSPORTS[name], authentication: "operator-cli",
     environments: ["isolated-checkout"], continuation: "native-session", observability: ["jsonl", "process"],
     controls: { cancel: true, interrupt: true }, cost: { source: name === "claude" ? "provider-usd" : "unknown-or-provider", hardCap: name === "claude" },
     policy: name === "codex" ? ["workspace-write", "auto-review"] : name === "claude" ? ["configured-hooks"] : [],
     preparation: adapter.preparation || null,
   })])),
-  "openai-agents": Object.freeze({ name: "openai-agents", available: true, isSession: value => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value), transport: EXECUTION_TRANSPORTS["openai-agents"], authentication: "project-api-key", environments: ["openai_hosted"], continuation: "native-session", observability: ["events", "saved-items", "polling"], controls: { cancel: true, interrupt: false }, cost: { source: "api-usage-and-hosted-compute", hardCap: false }, policy: [], preparation: agentsPreparation }),
-  "codex-cloud": Object.freeze({ name: "codex-cloud", available: false, reason: CLOUD_DISPATCH_UNAVAILABLE.reason, fix: CLOUD_DISPATCH_UNAVAILABLE.fix, isSession: value => typeof value === "string" && /^task_[A-Za-z0-9_-]{1,200}$/.test(value), transport: EXECUTION_TRANSPORTS["codex-cloud"], authentication: "operator-chatgpt", environments: [], continuation: "successor-task", observability: ["polling", "summary", "diff", "task-link"], controls: { cancel: false, interrupt: false }, cost: { source: "chatgpt-account", hardCap: false }, policy: [], preparation: null, liveQualified: false }),
+  "openai-agents": Object.freeze({ name: "openai-agents", repositoryAccess: { mode: "snapshot" }, available: true, isSession: value => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value), transport: EXECUTION_TRANSPORTS["openai-agents"], authentication: "project-api-key", environments: ["openai_hosted"], continuation: "native-session", observability: ["events", "saved-items", "polling"], controls: { cancel: true, interrupt: false }, cost: { source: "api-usage-and-hosted-compute", hardCap: false }, policy: [], preparation: agentsPreparation }),
+  "codex-cloud": Object.freeze({ name: "codex-cloud", repositoryAccess: { mode: "bound-host", hosts: ["github.com"] }, available: false, reason: CLOUD_DISPATCH_UNAVAILABLE.reason, fix: CLOUD_DISPATCH_UNAVAILABLE.fix, isSession: value => typeof value === "string" && /^task_[A-Za-z0-9_-]{1,200}$/.test(value), transport: EXECUTION_TRANSPORTS["codex-cloud"], authentication: "operator-chatgpt", environments: [], continuation: "successor-task", observability: ["polling", "summary", "diff", "task-link"], controls: { cancel: false, interrupt: false }, cost: { source: "chatgpt-account", hardCap: false }, policy: [], preparation: null, liveQualified: false }),
 });
 export const capabilitiesFor = name => {
   const c = executionRegistry[name];
@@ -467,7 +471,7 @@ export function buildRun({ harness, config, mode, session, prompt, cwd, contextP
     "For task-authorized tests of this harness, invoke that exact executable, quoted as one path, instead of assuming the bare command on PATH is the same installation. This does not authorize nested jobs, model/provider changes, extra paid calls or weaker permissions. Keep the task's existing scope and security settings.",
     "Before substantial implementation or retrying blocked work, check the brief's mandatory external prerequisites: required host/plugin support, model access and any browser or capture surface. Use the available native tools and the smallest authorized check; version/sign-in checks alone do not prove model access or installed-plugin behavior. If a required capability is unavailable, report the observed failure, affected criteria and exact remedy early. Continue useful independent work, preserve unmet attestations, and do not repeat unchanged blocked calls or replace required live evidence with fixtures.",
   ].join("\n");
-  const ctx = { session, prompt: `${runtime}\n\n${prompt}`, budget: config.max_budget_usd, settings: h.settings, cwd };
+  const ctx = { session, prompt: `${runtime}\n\n${prompt}`, budget: config.max_budget_usd, settings: h.settings, cwd, foreground: runtimeSetup };
   const base = mode === "start" ? a.start(ctx) : a.resume(ctx);
   const args = assertSafeArgv(withContext(a, base, contextPaths));
   const env = assertSafeEnv({ ...runtimeEnvironment(process.env, process.execPath, cwd), ...a.env({ configDir: h.settings ? dirname(h.settings) : null }) });

package/lib/host_contract.mjs

@@ -0,0 +1,71 @@
+export { ROUND_MARKER, NUDGE_MARKER, RESET_MARKER, READY_LABEL, NEEDS_LABEL } from "./public-format.mjs";
+export const MAX_DIFF_BYTES = 16 * 1024 * 1024;
+export const normalizeLogin = login => String(login || "").replace(/^app\//, "").replace(/\[bot\]$/, "").toLowerCase();
+export const actor = a => {
+  if (!a) return { login: "", bot: false };
+  const raw = a.login ?? a.user?.login ?? "";
+  return { login: normalizeLogin(raw), bot: a.bot === true || a.is_bot === true || a.type === "Bot" || a.user?.type === "Bot" || /\[bot\]$/.test(raw) || /^app\//.test(raw) };
+};
+
+export const REQUIRED_HOST_CAPABILITIES = Object.freeze(["pullRequests", "reviews", "comments", "checks", "diff", "mergeProof", "recovery"]);
+export function requireHostCapabilities(adapter) {
+  for (const name of REQUIRED_HOST_CAPABILITIES) if (adapter.capabilities?.[name] !== true) throw new Error(`Host ${adapter.host} lacks required ${name} evidence; preserve state and configure a qualified host adapter before retrying`);
+}
+export function completeItems(value, operation) {
+  if (Array.isArray(value)) return value;
+  if (value?.complete === true && Array.isArray(value.items) && !value.rateLimited) return value.items;
+  throw new Error(`Incomplete ${operation} evidence; preserve state and retry after host access recovers`);
+}
+
+/** Required observations are checked before the shared engine can consume them. */
+export function validateHostRecord(record, host, { pr = false, full = false, event = false } = {}) {
+  if (!record || record.complete === false || record.rateLimited || record.source?.host !== host ||
+      typeof record.source?.adapter !== "string" || typeof record.eventId !== "string" || !record.eventId ||
+      typeof record.actor?.login !== "string" || typeof record.actor?.bot !== "boolean" ||
+      (record.headSha !== null && typeof record.headSha !== "string") ||
+      [record.createdAt, record.updatedAt].some(value => value !== null && (typeof value !== "string" || !Number.isFinite(Date.parse(value))))) {
+    throw new Error("Incomplete normalized host evidence; preserve state and recover a complete observation");
+  }
+  if (event && record.state !== "PENDING" && !Number.isFinite(Date.parse(record.at))) throw new Error("Incomplete event timestamp; preserve the review cursor");
+  if (pr && (!Number.isSafeInteger(record.number) || record.number < 1 || !record.headRefOid || record.headSha !== record.headRefOid ||
+      !["OPEN", "CLOSED", "MERGED"].includes(record.state))) throw new Error("Incomplete pull request evidence");
+  if (full) {
+    if (record.feedback !== undefined) {
+      const f = record.feedback;
+      if (f?.complete !== true || f.headSha !== record.headSha || ![f.reviews, f.inline, f.comments].every(Array.isArray)) throw new Error("Incomplete normalized feedback snapshot");
+      for (const item of [...f.reviews, ...f.inline, ...f.comments]) validateHostRecord(item, host, { event: true });
+    }
+    if (!Array.isArray(record.statusCheckRollup)) throw new Error("Incomplete CI evidence");
+    for (const check of record.statusCheckRollup) {
+      validateHostRecord(check, host);
+      if (check.headSha !== record.headSha || !["passed", "failed", "pending"].includes(check.outcome)) throw new Error("Incomplete or mismatched CI evidence");
+    }
+  }
+  return record;
+}
+
+/** Providers declare access requirements; no host-by-harness switch table. */
+export function assertRepositoryAccess(capabilities, repository) {
+  const access = capabilities?.repositoryAccess;
+  if (access?.mode === "local-worktree" || access?.mode === "snapshot") return;
+  if (access?.mode === "bound-host" && access.hosts?.includes(repository.host)) return;
+  throw new Error(`Execution provider cannot access repository host ${repository.host}; select a compatible provider before dispatch`);
+}
+
+/** Adapters opt into immutable task identity; legacy observations retain their semantics. */
+export function observedIdentityProblem(entry, pr) {
+  if (!pr.strictIdentity) return null;
+  if (entry.pr != null && pr.number !== entry.pr || pr.isCrossRepository !== false || entry.url && pr.url !== entry.url || pr.headRefName !== entry.branch || entry.base && pr.baseRefName !== entry.base) return "PR repository, branch or approved base changed; restore the recorded identity before resuming";
+  return null;
+}
+
+export async function terminalIdentityProblem(host, entry, pr) {
+  if (!pr.strictIdentity) return null;
+  const mismatch = observedIdentityProblem(entry, pr);
+  if (mismatch) return mismatch;
+  if (pr.state !== "MERGED") return `PR is ${pr.hostState || pr.state}; it was not merged. Reopen and register it or cancel the task`;
+  if (!entry.cursor?.fixed_sha || entry.cursor.fixed_sha !== pr.headRefOid) return "Merged head differs from the recorded head; inspect the PR and saved readiness before continuing";
+  const merge = pr.mergeCommit?.oid;
+  if (!/^[a-f0-9]{40,64}$/i.test(merge || "") || !pr.mergedAt || !await host.containsCommit(entry.repo, entry.base, merge)) return "Cannot prove the merge commit is in the approved base; restore repository access and inspect merge ancestry";
+  return null;
+}

package/lib/host_definitions.mjs

@@ -0,0 +1,22 @@
+// The one shipped host catalogue. Portable consumers read policy only; Node's
+// hosts.mjs binds these declarations to transport implementations by adapter ID.
+import { githubDefinition } from "./hosts/github_contract.mjs";
+import { bitbucketDefinition } from "./hosts/bitbucket_contract.mjs";
+import { repositoryIdentity } from "./repository.mjs";
+export const HOST_DEFINITIONS = Object.freeze([githubDefinition, bitbucketDefinition]);
+export function hostDefinition(repo = "owner/name", { transport = false } = {}) {
+  const repository = repositoryIdentity(repo), adapter = HOST_DEFINITIONS.find(d => d.host === repository.host);
+  if (!adapter) throw new Error(`Unsupported repository host ${repository.host}; configure a qualified host before dispatch`);
+  if (!transport && adapter.dispatch === false) throw new Error(adapter.dispatchReason);
+  return { repository, adapter };
+}
+export const completionAdapter = repo => hostDefinition(repo || "owner/name").adapter.id;
+export const hostPrompts = repo => hostDefinition(repo || "owner/name").adapter.prompts;
+export function hostGuidance(repo) {
+  try { return hostDefinition(repo, { transport: true }).adapter.dispatchReason ?? null; }
+  catch (error) { return error.message; }
+}
+export function pullRequestUrl(repo, number) {
+  if (!Number.isSafeInteger(Number(number)) || Number(number) < 1) return null;
+  try { const { adapter, repository } = hostDefinition(repo, { transport: true }); return adapter.prUrl(repository, Number(number)); } catch { return null; }
+}