@uchibeke/gallivant 0.2.0 → 0.3.0

package/lib/fs.mjs

@@ -14,10 +14,17 @@ export const HOME = homedir();
  * 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.
  */
-export const VERSION = (() => {
-  try { return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version || "unknown"; }
-  catch { return "unknown"; }
+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`

package/lib/gh.mjs

@@ -3,60 +3,33 @@
 //
 // Logins: GitHub renders bots as `name[bot]` in REST and as `login` + `is_bot` in gh's GraphQL output. Everything
 // is normalised to the bare login plus a `bot` flag before any comparison.
-import { execFile } from "node:child_process";
+import { execFileAsync, transportExecutor } from "./process.mjs";
+import { actor, normalizeLogin, MAX_DIFF_BYTES } from "./host_contract.mjs";
+import { parseRemote, repositoryMatches, remoteMatches } from "./repository.mjs";
+export { execFileAsync, actor, normalizeLogin, MAX_DIFF_BYTES, repositoryMatches, remoteMatches };
 
 import { ROUND_MARKER, NUDGE_MARKER, RESET_MARKER, READY_LABEL, NEEDS_LABEL, labelAliases } from "./public-format.mjs";
 import { assertPublicText, assertNoNul } from "./public_output.mjs";
-import { normalizePublicBody, parseBlock, renderBlock } from "./block.mjs";
 import { repositoryName, parseJson } from "./learning_data.mjs";
 import { redact } from "./execution_io.mjs";
+import { gitDiffSectionMatches } from "./git_diff.mjs";
+import { createHash } from "node:crypto";
+import { inspectReviewImageSet, REVIEW_IMAGE_LIMITS } from "./review_image.mjs";
+import { inspectReviewLink, MAX_REVIEW_LINK_BYTES } from "./review_link.mjs";
 export { ROUND_MARKER, NUDGE_MARKER, RESET_MARKER, READY_LABEL, NEEDS_LABEL };
 
 const GH_TIMEOUT_MS = 60_000;
+const decodeUtf8 = buffer => new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(buffer);
 // A hundred long, JSON-escaped bodies plus metadata can exceed one MiB.
 const LEARNING_PAGE_BYTES = 64 * 1024 * 1024;
-/** The scan cap for a PR diff. A diff this size or larger cannot be shown to the output scan whole. */
-export const MAX_DIFF_BYTES = 16 * 1024 * 1024;
-
-export const normalizeLogin = login => String(login || "").replace(/^app\//, "").replace(/\[bot\]$/, "").toLowerCase();
-
-/** One shape for authors from either API: { login, bot }. */
-export const actor = a => {
-  if (!a) return { login: "", bot: false };
-  const raw = a.login ?? a.user?.login ?? "";
-  const bot = a.is_bot === true || a.type === "Bot" || a.user?.type === "Bot" || /\[bot\]$/.test(raw) || /^app\//.test(raw);
-  return { login: normalizeLogin(raw), bot };
-};
-
-/** owner/name from any GitHub PR URL, as GitHub spells it (lowercased, since GitHub treats names case-insensitively). */
-export function repoFromUrl(url) {
-  const m = String(url || "").match(/github\.com\/([\w.-]+)\/([\w.-]+)\/pull\/(\d+)/i);
-  return m ? { repo: `${m[1]}/${m[2]}`.toLowerCase(), number: Number(m[3]) } : null;
-}
-
-/**
- * owner/repo from a git remote URL, lowercased, or null when the URL is not a GitHub remote we understand.
- * The supported forms are the ones `gh repo clone` and `git clone` produce: https, scp-style ssh, and ssh://.
- * Callers compare the result for equality, never by substring, so `acme/widget-fork` never matches `acme/widget`.
- */
+/** Compatibility exports for existing callers; all parsing uses the strict identity boundary. */
+export { parseGitHubPr as repoFromUrl } from "./hosts/github_contract.mjs";
 export function repoFromRemote(url) {
-  const s = String(url || "").trim().replace(/\/+$/, "");
-  const m = s.match(/^(?:https?:\/\/(?:[^@/]*@)?github\.com\/|(?:ssh:\/\/)?(?:[^@/]+@)?github\.com[:/])([\w-][\w.-]*)\/([\w-][\w.-]*?)(?:\.git)?$/i);
-  if (!m) return null;
-  return `${m[1]}/${m[2]}`.toLowerCase();
+  try { const r = parseRemote(url); return r.host === "github.com" ? r.key : null; } catch { return null; }
 }
 
-/** GitHub owner/repo identity ignores letter case without rewriting either spelling. */
-export const repositoryMatches = (left, right) => typeof left === "string" && left.length > 0 && typeof right === "string" && left.toLowerCase() === right.toLowerCase();
-
-/** Whether a remote URL points at exactly this `owner/repo`. */
-export const remoteMatches = (url, nameWithOwner) => {
-  const parsed = repoFromRemote(url);
-  return repositoryMatches(parsed, nameWithOwner);
-};
-
 // Reviews and comments come from REST (numeric ids, `user.type`, `since` filters); the rest from `gh pr view`.
-const PR_FIELDS = "number,url,title,state,isDraft,mergeable,headRefOid,headRefName,isCrossRepository,author,createdAt,updatedAt,statusCheckRollup,labels,body,baseRefName,mergeCommit,mergedAt";
+const PR_FIELDS = "number,url,title,state,isDraft,mergeable,headRefOid,headRefName,isCrossRepository,author,createdAt,updatedAt,statusCheckRollup,labels,body,baseRefName,baseRefOid,mergeCommit,mergedAt";
 
 /**
  * The `gh` the daemon itself runs.
@@ -66,13 +39,17 @@ const PR_FIELDS = "number,url,title,state,isDraft,mergeable,headRefOid,headRefNa
  * It defaults to resolving nothing, in which case `gh` falls back to its own stores exactly as before, which is
  * right for the daemon (not sandboxed) and is what keeps every existing test working unchanged.
  */
-export function makeGh({ credential = async () => null, exec = execFileAsync, log = null } = {}) {
+export function makeGh({ credential = async () => null, exec: execute = execFileAsync, log = null } = {}) {
+  const exec = transportExecutor(execute);
   const failureDetails = new WeakMap();
   const env = async () => {
-    const token = (await credential())?.token;
-    return token ? { ...process.env, GH_TOKEN: token } : process.env;
+    const resolved = await credential({ host: "github.com" });
+    if (resolved?.host && resolved.host !== "github.com") throw new Error("GitHub API credential host mismatch");
+    if (resolved?.sshKey && !resolved.token) throw new Error("A Git SSH key does not authorize the host API");
+    const token = resolved?.token;
+    return { ...process.env, GH_HOST: "github.com", ...(token ? { GH_TOKEN: token, GITHUB_TOKEN: "", GH_ENTERPRISE_TOKEN: "", GITHUB_ENTERPRISE_TOKEN: "" } : {}) };
   };
-  const LABELS = [[READY_LABEL, "5319e7", "Checks green, reviewer clear, completion receipt accepted"], [NEEDS_LABEL, "b60205", "Work paused; operator attention required"]];
+  const LABELS = [[READY_LABEL, "5319e7", "Ready for human review; inspect the recorded review and completion evidence"], [NEEDS_LABEL, "b60205", "Work paused; operator attention required"]];
   const run = async (args, { cwd, timeout = GH_TIMEOUT_MS, signal } = {}) => {
     signal?.throwIfAborted();
     const resolvedEnv = await env();
@@ -85,12 +62,20 @@ export function makeGh({ credential = async () => null, exec = execFileAsync, lo
         const secrets=Object.entries(resolvedEnv).filter(([key,value])=>/(?:TOKEN|SECRET|KEY|PASSWORD)/i.test(key) && typeof value==='string' && value.length).map(([,value])=>value);
         failureDetails.set(error,redact(String(error.stderr || error.message || 'GitHub CLI failed'),secrets).replace(/[\x00-\x08\x0b-\x1f\x7f]/g,' ').slice(0,1200));
       }
+      if (failureDetails.has(error)) {
+        error.message = failureDetails.get(error);
+        error.stderr = error.message;
+        error.stdout = "";
+      }
       throw error;
     }
   };
   const json = async (args, opts) => { const out = await run(args, opts); return out.trim() ? JSON.parse(out) : null; };
   // `--paginate` alone concatenates one JSON array per page; `--slurp` wraps them so the output parses as one array.
-  const pages = path => json(["api", path, "--paginate", "--slurp"]).then(r => (r || []).flat());
+  const pages = path => json(["api", path, "--paginate", "--slurp"]).then(r => {
+    if (!Array.isArray(r) || !r.length || r.some(page => !Array.isArray(page))) throw new Error("Incomplete host page; retry without advancing the cursor");
+    return r.flat();
+  });
 
   // Remove every historical spelling separately: one absent alias must not hide a forbidden/network failure on
   // another. Existing retry counters therefore cover the whole migration and never dispatch behind a stale label.
@@ -147,12 +132,13 @@ export function makeGh({ credential = async () => null, exec = execFileAsync, lo
     user: options => json(["api", "user", "--jq", "{login: .login}"], options).then(u => u.login),
     authStatus: () => run(["auth", "status"]).then(() => true).catch(() => false),
     /** owner/name and default branch for a checkout. */
-    repoInfo: dir => json(["repo", "view", "--json", "nameWithOwner,defaultBranchRef"], { cwd: dir })
+    repoInfo: (dir, repo = null) => json(["repo", "view", ...(repo ? [repo] : []), "--json", "nameWithOwner,defaultBranchRef"], { cwd: dir })
       .then(r => ({ nameWithOwner: r.nameWithOwner, defaultBranch: r.defaultBranchRef?.name })),
     markReady: (repo, n) => run(["pr", "ready", String(n), "--repo", repo]),
     /** Only generated recovery/receipt transport may migrate before prose is corrected. Read fresh, and derive
      * the replacement here: callers cannot use this path to smuggle an arbitrary unguarded body to GitHub. */
     setRecoveryMetadata: async (repo, n, identity, { taskId = null } = {}) => {
+      const { normalizePublicBody, parseBlock, renderBlock } = await import("./block.mjs");
       const pr = await json(["pr", "view", String(n), "--repo", repo, "--json", PR_FIELDS]);
       if (pr.isCrossRepository || identity.branch !== pr.headRefName) throw new Error("recovery identity branch differs from the same-repository PR head");
       const validated = parseBlock(renderBlock(identity));
@@ -201,6 +187,117 @@ export function makeGh({ credential = async () => null, exec = execFileAsync, lo
      * looked at. The cap stays, because a diff of any size in memory is its own problem; what it produces is a
      * refusal to decide rather than a partial answer presented as a whole one.
      */
+    reviewEvidence: async (repo, _n, head, base, maxBytes, { imageEvidence = false, linkEvidence = false } = {}) => {
+      if (![head, base].every(v => /^[a-f0-9]{40,64}$/.test(v))) throw new Error("review requires exact commit object IDs");
+      const comparison = `repos/${repo}/compare/${base}...${head}`;
+      const metadata = await json(["api", comparison]);
+      // GitHub caps compare files at 300. At the boundary completeness is
+      // unprovable; omitted patches/binary/submodule content also fail closed.
+      if (!metadata?.merge_base_commit?.sha || !Array.isArray(metadata.files) || !metadata.files.length || metadata.files.length >= 300) throw new Error("review comparison is empty, incomplete or at the host file limit");
+      const diff = await run(["api", comparison, "-H", "Accept: application/vnd.github.diff"]);
+      let bytes = Buffer.byteLength(diff);
+      if (!diff.trim() || bytes > maxBytes) throw new Error("complete review diff exceeds input limit or is unreadable");
+      const sections = diff.split(/(?=^diff --git )/m).filter(section => section.startsWith("diff --git "));
+      if (sections.length !== metadata.files.length || !imageEvidence && /^(?:GIT binary patch|Binary files )/m.test(diff) || /^(?:(?:old|new|new file|deleted file) mode 160000$|[ +\-]?Subproject commit )/m.test(diff) || !linkEvidence && /^(?:old|new|new file|deleted file) mode 120000$/m.test(diff)) throw new Error("host diff omitted, binary, symlink or submodule changed files; review is incomplete");
+      const read = async (path, ref) => {
+        const r = await json(["api", `repos/${repo}/contents/${path.split("/").map(encodeURIComponent).join("/")}?ref=${encodeURIComponent(ref)}`]);
+        if (r?.type !== "file" || r.encoding !== "base64" || typeof r.content !== "string" || r.submodule_git_url || r.target) throw new Error("review source is unreadable or not a regular text file");
+        const buffer = Buffer.from(r.content, "base64");
+        const value = decodeUtf8(buffer);
+        bytes += buffer.length;
+        if (value.includes("\0") || bytes > maxBytes) throw new Error("review source is binary or complete context exceeds input limit");
+        return value;
+      };
+      const context = [];
+      const paths = new Set();
+      const images = [], treeCache = new Map(), commitCache = new Map();
+      let imageCount = 0, imageBytes = 0;
+      // Contents endpoints may dereference symlinks. Bind each image to a
+      // regular blob from the exact commit's tree before reading its bytes.
+      const lookupTree = async (path, ref) => {
+        if (typeof path !== "string" || !path || /[\\\0\r\n]/.test(path) || path.split("/").some(part => !part || part === "." || part === ".." || part.toLowerCase() === ".git")) throw new Error("unsafe review image path");
+        let tree = commitCache.get(ref);
+        if (!tree) {
+          const commit = await json(["api", `repos/${repo}/git/commits/${ref}`]);
+          if (!/^[a-f0-9]{40}$/.test(commit?.tree?.sha || "") || commit?.sha !== ref) throw new Error("review image commit identity differs");
+          tree = commit.tree.sha; commitCache.set(ref, tree);
+        }
+        let entry;
+        const parts = path.split("/");
+        for (const [index, part] of parts.entries()) {
+          let data = treeCache.get(tree);
+          if (!data) { data = await json(["api", `repos/${repo}/git/trees/${tree}`]); treeCache.set(tree, data); }
+          if (data?.sha !== tree || data.truncated !== false || !Array.isArray(data.tree)) throw new Error("review image tree is incomplete");
+          const matches = data.tree.filter(item => item.path === part);
+          if (matches.length !== 1) throw new Error("review image tree path is absent or duplicated");
+          entry = matches[0];
+          if (index < parts.length - 1 && (entry.type !== "tree" || entry.mode !== "040000" || !/^[a-f0-9]{40}$/.test(entry.sha || ""))) throw new Error("review image parent is not a tree");
+          tree = entry.sha;
+        }
+        return entry;
+      };
+      const readImage = async (path, ref, side) => {
+        const entry = await lookupTree(path, ref), parts = path.split("/");
+        if (entry?.type !== "blob" || !["100644", "100755"].includes(entry.mode) || !/^[a-f0-9]{40}$/.test(entry.sha || "") || !Number.isSafeInteger(entry.size) || entry.size < 1 || entry.size > REVIEW_IMAGE_LIMITS.individualBytes || ++imageCount > REVIEW_IMAGE_LIMITS.count || (imageBytes += entry.size) > REVIEW_IMAGE_LIMITS.totalBytes) throw new Error("review image is not a bounded regular blob");
+        if (bytes + entry.size > maxBytes) throw new Error("complete review context exceeds input limit");
+        const r = await json(["api", `repos/${repo}/contents/${parts.map(encodeURIComponent).join("/")}?ref=${ref}`]);
+        const encoded = typeof r?.content === "string" ? r.content.replace(/\s/g, "") : "";
+        if (r?.type !== "file" || r.encoding !== "base64" || r.sha !== entry.sha || r.size !== entry.size || encoded.length !== Math.ceil(entry.size / 3) * 4 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded)) throw new Error("review image contents are incomplete");
+        const buffer = Buffer.from(encoded, "base64");
+        const object = createHash("sha1").update(`blob ${buffer.length}\0`).update(buffer).digest("hex");
+        if (buffer.length !== entry.size || object !== entry.sha) throw new Error("review image blob hash differs");
+        bytes += buffer.length;
+        return { bytes: buffer, identity: { path, revision: ref, side } };
+      };
+      const readLink = async (path, ref, side, entry) => {
+        if (entry?.type !== "blob" || entry.mode !== "120000" || !/^[a-f0-9]{40}$/.test(entry.sha || "") || !Number.isSafeInteger(entry.size) || entry.size < 1 || entry.size > MAX_REVIEW_LINK_BYTES || bytes + entry.size > maxBytes) throw new Error("review link is not a bounded blob");
+        const r = await json(["api", `repos/${repo}/git/blobs/${entry.sha}`]);
+        const encoded = typeof r?.content === "string" ? r.content.replace(/\s/g, "") : "";
+        if (r?.encoding !== "base64" || r.sha !== entry.sha || r.size !== entry.size || encoded.length !== Math.ceil(entry.size / 3) * 4 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded)) throw new Error("review link blob is incomplete");
+        const buffer = Buffer.from(encoded, "base64");
+        if (buffer.length !== entry.size || createHash("sha1").update(`blob ${buffer.length}\0`).update(buffer).digest("hex") !== entry.sha) throw new Error("review link blob hash differs");
+        bytes += buffer.length;
+        return inspectReviewLink(buffer, { path, revision: ref, side });
+      };
+      for (const [index, f] of metadata.files.entries()) {
+        if (!["added", "modified", "removed", "renamed"].includes(f.status) || (f.patch != null && typeof f.patch !== "string") || paths.has(f.filename)) throw new Error("host omitted or duplicated a changed-file patch; review is incomplete");
+        paths.add(f.filename);
+        const section = sections[index], beforePath = f.previous_filename || f.filename;
+        const beforeEntry = linkEvidence && f.status !== "added" ? await lookupTree(beforePath, metadata.merge_base_commit.sha) : null;
+        const afterEntry = linkEvidence && f.status !== "removed" ? await lookupTree(f.filename, head) : null;
+        const linkTypes = [beforeEntry, afterEntry].filter(Boolean).map(entry => entry.mode === "120000" && entry.type === "blob");
+        if (linkTypes.some(Boolean) && !linkTypes.every(Boolean)) throw new Error("review link type transition is incomplete");
+        const isLink = linkTypes.some(Boolean);
+        if (linkEvidence && !isLink && [beforeEntry, afterEntry].filter(Boolean).some(entry => entry.type !== "blob" || !["100644", "100755"].includes(entry.mode))) throw new Error("review source is not a regular Git blob");
+        const isImage = !isLink && imageEvidence && (/^(?:GIT binary patch|Binary files )/m.test(section) || [beforePath, f.filename].some(path => /\.(?:png|jpe?g)$/i.test(path || "")));
+        if (!gitDiffSectionMatches(section, { status: f.status, oldPath: beforePath, newPath: f.filename, binary: isImage })) throw new Error("host diff omitted content or its changed-path inventory differs from comparison metadata");
+        if (isLink) {
+          if (/^(?:old|new|new file|deleted file) mode (?!120000)/m.test(section)) throw new Error("review link type transition is incomplete");
+          const beforeLink = beforeEntry ? await readLink(beforePath, metadata.merge_base_commit.sha, "before", beforeEntry) : null;
+          const afterLink = afterEntry ? await readLink(f.filename, head, "after", afterEntry) : null;
+          context.push({ path: f.filename, status: f.status, patch: section, kind: "symlink",
+            before: beforeLink?.target ?? null, after: afterLink?.target ?? null, beforeLink, afterLink });
+          continue;
+        }
+        if (/^(?:old|new|new file|deleted file) mode 120000$/m.test(section)) throw new Error("review link metadata differs from diff");
+        if (isImage) {
+          const target = { path: f.filename, status: f.status, patch: section, kind: "image", before: null, after: null };
+          if (f.status !== "added") images.push({ ...await readImage(beforePath, metadata.merge_base_commit.sha, "before"), target });
+          if (f.status !== "removed") images.push({ ...await readImage(f.filename, head, "after"), target });
+          context.push(target);
+          continue;
+        }
+        if (/^(?:GIT binary patch|Binary files )/m.test(section)) throw new Error("unsupported binary review evidence");
+        if (typeof f.patch !== "string" && /^(?:--- |\+\+\+ |@@ )/m.test(section)) throw new Error("host omitted a changed-file patch; review is incomplete");
+        context.push({ path: f.filename, status: f.status, patch: section,
+          before: f.status === "added" ? null : await read(f.previous_filename || f.filename, metadata.merge_base_commit.sha),
+          after: f.status === "removed" ? null : await read(f.filename, head) });
+      }
+      if (imageEvidence) for (const [index, verified] of inspectReviewImageSet(images, { head, mergeBase: metadata.merge_base_commit.sha }).entries()) {
+        const image = images[index]; image.target[image.identity.side] = { ...verified, content: image.bytes.toString("base64") };
+      }
+      return { complete: true, head, base, mergeBase: metadata.merge_base_commit.sha, diff, context };
+    },
     prDiff: (repo, n) => run(["pr", "diff", String(n), "--repo", repo]).then(d => {
       // At the cap, not only over it: a diff of exactly the cap is indistinguishable from one the cap cut short.
       const bytes = Buffer.byteLength(d);
@@ -237,6 +334,7 @@ export function makeGh({ credential = async () => null, exec = execFileAsync, lo
     async publishResultPr({ repo, branch, base, title, body }) {
       assertPublicText(title, "PR title"); assertPublicText(body, "PR body");
       const prs = await json(["pr", "list", "--repo", repo, "--head", branch, "--state", "open", "--json", "number,url,headRefName,isCrossRepository,baseRefName"]);
+      if (!Array.isArray(prs)) throw new Error("Incomplete result PR list; reconcile the owned branch before publishing");
       if ((prs || []).length > 1) throw new Error("ambiguous result PR ownership; reconcile the recorded branch before publishing");
       const existing = prs?.[0];
       if (existing) {
@@ -277,13 +375,3 @@ export function makeGh({ credential = async () => null, exec = execFileAsync, lo
     repoPermissions: repo => json(["api", `repos/${repo}`, "--jq", "{push: .permissions.push, admin: .permissions.admin, archived: .archived}"]),
   };
 }
-
-/** execFile as a promise, with a timeout, and an error that carries stdout, stderr and the exit code. */
-export function execFileAsync(cmd, args, opts = {}) {
-  return new Promise((resolve, reject) => {
-    execFile(cmd, args, { maxBuffer: 16 * 1024 * 1024, encoding: "utf8", ...opts }, (err, stdout, stderr) => {
-      if (err) return reject(Object.assign(new Error(`${cmd} ${args.slice(0, 3).join(" ")}: ${String(stderr || "").trim() || err.message}`), { stdout, stderr, code: err.code, killed: err.killed }));
-      resolve({ stdout, stderr });
-    });
-  });
-}

package/lib/git.mjs

@@ -6,16 +6,18 @@ import { join } from "node:path";
 import { lstatSync } from "node:fs";
 import { exists, ensureDir } from "./fs.mjs";
 import { repositoryPath, writeRepositoryText } from "./repository_files.mjs";
-import { execFileAsync, remoteMatches, repoFromRemote } from "./gh.mjs";
-import { COMMIT_MSG_HOOK } from "./attribution.mjs";
+import { execFileAsync, transportExecutor } from "./process.mjs";
+import { remoteMatches, parseRemote, repositoryIdentity, safeOrigin, assertBranchName } from "./repository.mjs";
+import { hosts as defaultHosts } from "./hosts.mjs";
+import { commitMsgHook } from "./attribution.mjs";
 import { BRANCH_PREFIX, BRANCH_PREFIXES } from "./public-format.mjs";
 
 const CLONE_TIMEOUT_MS = 15 * 60_000;
 const GIT_TIMEOUT_MS = 5 * 60_000;
 export const GIT_PATH_LIMITS = Object.freeze({ timeoutMs: 2000, bytes: 1_048_576 });
-const cloneUrl = repo => `https://github.com/${repo}.git`;
 
-export const worktreePath = (config, nameWithOwner, prdId) => join(config.worktrees, ...nameWithOwner.toLowerCase().split("/"), prdId);
+
+export const worktreePath = (config, nameWithOwner, prdId) => join(config.worktrees, ...repositoryIdentity(nameWithOwner).key.split("/"), prdId);
 
 /** The branch naming convention, in one place with its inverse. */
 export const branchFor = prdId => `${BRANCH_PREFIX}${prdId}`;
@@ -34,7 +36,10 @@ export const prdIdFromBranch = branch => (isOurBranch(branch) ? branch.slice(bra
  */
 export const RUN_GIT_CONFIG = [
   ["push.default", "current"],
-  ["credential.helper", `!f() { test -n "$GH_TOKEN" && printf 'username=x\\npassword=%s\\n' "$GH_TOKEN"; }; f`],
+  ["credential.helper", ""],
+  ["credential.useHttpPath", "true"],
+  ["http.followRedirects", "false"],
+  ["credential.helper", `!f() { test "$1" = get || return; protocol= host= path=; while IFS='=' read -r k v; do case "$k" in protocol) protocol="$v";; host) host="$v";; path) path="$v";; esac; done; test "$protocol" = https && test "$host" = "$GIT_CREDENTIAL_HOST" || return; test -z "$GIT_CREDENTIAL_REPOSITORY" || test "$path" = "$GIT_CREDENTIAL_REPOSITORY" || test "$path" = "$GIT_CREDENTIAL_REPOSITORY.git" || return; test -n "${'$'}{GIT_HOST_TOKEN:-$GH_TOKEN}" && printf 'username=%s\\npassword=%s\\n' "${'$'}{GIT_HOST_USERNAME:-x}" "${'$'}{GIT_HOST_TOKEN:-$GH_TOKEN}"; }; f`],
 ];
 
 /**
@@ -107,10 +112,9 @@ export const NODE_TOOLING_ENV = Object.freeze({
  *    every sandbox permits; the alternative of leaving it unset makes git read `$HOME/.gitconfig`, which is outside
  *    the worktree and is the class of failure this whole function exists to end.
  *
- * What is NOT bounded by this, stated plainly because it is not new and is easy to mistake for new: a run's own
- * `.git/config` is still read, `credential.helper` is multi-valued, and a repo-local helper is consulted first. That
- * was equally true when the helper lived in a global file. A run controls its worktree, so it can always add one; the
- * control that bounds a run is the token's scope and the branch ruleset, not the transport of the config.
+ * The empty credential.helper entry resets repository-local helper lists before installing the bound helper.
+ * HTTPS redirects are disabled. Credentials are returned only for the expected host and repository path.
+ * A run can still read its own environment, so credential scope remains a separate authority boundary.
  *
  * The token reaches the helper through this environment and nothing else. It is never an argument, so `ps` cannot
  * show it, and nothing here writes it to a file.
@@ -121,16 +125,45 @@ export function runEnv(_config = null, credential = null, identity = null, workt
   // ones (`originOf`, `currentBranch`), or `doctor`'s probe. Anything that COMMITS must be given an identity, because
   // this function's own `GIT_CONFIG_GLOBAL=/dev/null` is what leaves the clone without one; `makeGit` says what git
   // does when it is not, and it is not a clean failure on every platform.
-  const pairs = [...RUN_GIT_CONFIG, ...(identity?.name && identity?.email ? identityConfig(identity) : [])];
-  const env = { GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_COUNT: String(pairs.length) };
+  // The coordinator may clone a Bitbucket repository with its private SSH key,
+  // but the coding session never receives that key. Rewrite only this selected
+  // repository's SSH origin to HTTPS inside the session. The existing helper
+  // supplies its already-bound account token only for that exact repo path.
+  const bitbucketRepo = credential?.host === "bitbucket.org" && credential?.token && credential?.repository
+    ? repositoryIdentity(credential.repository, "bitbucket.org").path : null;
+  const bitbucketGit = bitbucketRepo
+    ? ["git@ssh.bitbucket.org:", "git@bitbucket.org:"].map(origin => [
+        `url.https://bitbucket.org/${bitbucketRepo}.git.insteadOf`, `${origin}${bitbucketRepo}.git`,
+      ]) : [];
+  const pairs = [...RUN_GIT_CONFIG, ...bitbucketGit, ...(identity?.name && identity?.email ? identityConfig(identity) : [])];
+  const env = { GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_COUNT: String(pairs.length), GIT_SSH_COMMAND: "false" };
   for (const [i, [key, value]] of pairs.entries()) { env[`GIT_CONFIG_KEY_${i}`] = key; env[`GIT_CONFIG_VALUE_${i}`] = value; }
-  if (credential?.token) env.GH_TOKEN = credential.token;
+  env.GIT_CREDENTIAL_HOST = credential?.host || "github.com";
+  env.GIT_CREDENTIAL_REPOSITORY = credential?.repository || "";
+  env.GIT_HOST_USERNAME = credential?.username || "x";
+  for (const name of Object.keys(process.env)) if (/^(?:BITBUCKET_|BB_|REVIEWER_|CODE_REVIEW_|HOST_API_)/.test(name)) env[name] = "";
+  Object.assign(env, { HOST_API_HOST: "", HOST_API_REPOSITORY: "", HOST_API_TOKEN: "", HOST_API_EMAIL: "", HOST_API_BINDING: "" });
+  if (credential) {
+    // Only a host adapter may supply these explicitly bound coding credentials.
+    for (const key of ["HOST_API_HOST", "HOST_API_REPOSITORY", "HOST_API_TOKEN", "HOST_API_EMAIL", "HOST_API_BINDING"]) if (credential.environment?.[key] !== undefined) env[key] = credential.environment[key];
+    // A run must not inherit another account's API token or ambient SSH identity.
+    Object.assign(env, { GH_HOST: env.GIT_CREDENTIAL_HOST, GH_TOKEN: "", GITHUB_TOKEN: "", GH_ENTERPRISE_TOKEN: "", GITHUB_ENTERPRISE_TOKEN: "", GIT_HOST_TOKEN: "", GIT_CONFIG_PARAMETERS: "" });
+    if (credential.sshKey && !credential.sshCommand) throw new Error("The selected HTTPS Git policy requires its bound token; an SSH key does not authorize API operations");
+    if (credential.sshCommand) { env.GIT_SSH_COMMAND = credential.sshCommand; env.SSH_AUTH_SOCK = ""; }
+    if (credential.token) env[env.GIT_CREDENTIAL_HOST === "github.com" ? "GH_TOKEN" : "GIT_HOST_TOKEN"] = credential.token;
+  }
   // gh loads config even with GH_TOKEN. A sandboxed run cannot read ~/.config/gh, so keep its CLI state inside
   // Gallivant's private clone. The directory may be absent; gh uses defaults. No personal credentials are copied.
   if (worktree) env.GH_CONFIG_DIR = join(worktree, ".git", "gallivant-gh");
   return { ...env, ...NODE_TOOLING_ENV };
 }
 
+// Harness runtime settings may add paths and model settings, but cannot replace
+// the selected repository's Git/API authority or session isolation values.
+export function runSessionEnv(specEnv, config, credential, identity, worktree) {
+  return { ...specEnv, ...runEnv(config, credential, identity, worktree) };
+}
+
 /**
  * Git for the daemon's own clones and fetches.
  *
@@ -158,25 +191,58 @@ export function runEnv(_config = null, credential = null, identity = null, workt
  * The refusal belongs where a commit is actually being paid for: `requireIdentity` in `startRun` and in `start`, before
  * a session is spawned. So this resolver is allowed to answer nothing, and git decides what a commit without one means.
  */
-export function makeGit({ config, exec = execFileAsync, credential = async () => null, identity = async () => null } = {}) {
-  const env = async () => ({ ...process.env, ...runEnv(config, await credential(), await identity()) });
-  const git = async (args, cwd, timeout = GIT_TIMEOUT_MS) => (await exec("git", args, { cwd, env: await env(), timeout })).stdout.trim();
+export function makeGit({ config, exec: execute = execFileAsync, credential = async () => null, identity = async () => null, hosts = null } = {}) {
+  const exec = transportExecutor(execute);
+  const registry = hosts ?? defaultHosts;
+  const bindings = new Map();
+  const cleanEnv = () => Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^(?:GIT_|GH_|GITHUB_|BITBUCKET_|BB_|SSH_)/.test(key)));
+  const env = async (repository = null) => {
+    const resolved = repository && hosts ? await hosts.gitCredential(repository) : await credential(repository ?? {});
+    if (repository && (resolved?.host && resolved.host !== repository.host || resolved?.repository && resolved.repository !== repository.path)) throw new Error("Git credential host mismatch");
+    return { ...cleanEnv(), GIT_TERMINAL_PROMPT: "0", ...runEnv(config, resolved && { ...resolved, ...(repository ? { host: repository.host, repository: repository.path } : {}) }, await identity()) };
+  };
+  const git = async (args, cwd, timeout = GIT_TIMEOUT_MS, expected = null) => {
+    if (args[0] === "fetch" && args[2]) assertBranchName(args[2]);
+    let repository = expected ? registry.inspect(expected).repository : bindings.get(cwd) ?? null;
+    if (["fetch", "push"].includes(args[0])) {
+      const origin = (await exec("git", ["remote", "get-url", "origin"], { cwd, env: { ...cleanEnv(), ...runEnv() }, timeout })).stdout.trim();
+      // Local, credential-free fixture repositories are useful to exercise native merge semantics.
+      if (repository && !remoteMatches(origin, repository)) throw new Error("Git origin identity mismatch; restore the saved repository before retrying");
+      if (hosts || /^(?:https?:|ssh:|git@)/.test(origin)) repository ??= registry.inspectRemote(origin).repository;
+      const urls = (await exec("git", ["remote", "get-url", "--push", "--all", "origin"], { cwd, env: { ...cleanEnv(), ...runEnv() }, timeout })).stdout.trim().split("\n");
+      if (repository) {
+        const policy = registry.remote(repository);
+        if (origin !== policy.url || urls.some(url => url !== policy.url)) throw new Error("Git remote transport or push identity mismatch; restore the adapter's verified origin before retrying");
+        const api = registry.inspect(repository).api;
+        if (api.inspectRepository) await api.inspectRepository(repository.path);
+      }
+    }
+    return (await exec("git", args, { cwd, env: await env(repository), timeout })).stdout.trim();
+  };
   // NUL-delimited paths preserve whitespace and newlines; never trim them.
   const gitPaths = async (args, cwd) => {
-    const { stdout } = await exec("git", args, { cwd, env: await env(), timeout: GIT_PATH_LIMITS.timeoutMs, maxBuffer: GIT_PATH_LIMITS.bytes });
+    const { stdout } = await exec("git", args, { cwd, env: await env(bindings.get(cwd)), timeout: GIT_PATH_LIMITS.timeoutMs, maxBuffer: GIT_PATH_LIMITS.bytes });
     if (typeof stdout !== "string" || Buffer.byteLength(stdout) > GIT_PATH_LIMITS.bytes || (stdout && !stdout.endsWith("\0"))) throw new Error("incomplete or oversized Git path metadata; preserve the checkout and retrieve complete paths before publication");
     return stdout ? stdout.slice(0, -1).split("\0") : [];
   };
-  const gh = async (args, cwd, timeout = CLONE_TIMEOUT_MS, beforeExec = null) => {
-    const options = { cwd, env: await env(), timeout };
+  const clone = async (repo, path, options, beforeExec = null) => {
+    const { repository, api } = registry.inspect(repo), remote = registry.remote(repository);
+    if (api.inspectRepository) await api.inspectRepository(repository.path);
+    bindings.set(path, repository);
+    const optionsEnv = await env(repository);
+    if (remote.protocol === "ssh" && (!optionsEnv.GIT_SSH_COMMAND || optionsEnv.GIT_SSH_COMMAND === "false")) throw new Error("Host SSH transport requires its explicitly bound key");
     beforeExec?.();
-    return (await exec("gh", args, options)).stdout.trim();
+    return exec("git", ["clone", "--filter=blob:none", ...options, "--", remote.url, path], { env: optionsEnv, timeout: CLONE_TIMEOUT_MS });
   };
 
-  async function ensureHttpsRemote(dir) {
+  async function ensureHttpsRemote(dir, expected = null) {
     const origin = await git(["remote", "get-url", "origin"], dir);
-    const repo = repoFromRemote(origin);
-    if (repo && !origin.startsWith("https://")) await git(["remote", "set-url", "origin", cloneUrl(repo)], dir);
+    const { repository, api } = registry.inspectRemote(origin);
+    if (expected && !remoteMatches(origin, expected)) throw new Error("Checkout origin differs from the saved repository; restore origin before retrying");
+    if (api.inspectRepository) await api.inspectRepository(repository.path);
+    bindings.set(dir, repository);
+    const remote = registry.remote(repository);
+    if (origin !== remote.url) await git(["remote", "set-url", "origin", remote.url], dir);
   }
 
   /**
@@ -192,14 +258,43 @@ export function makeGit({ config, exec = execFileAsync, credential = async () =>
    * it needs, so the failure is returned and the caller logs it. The identity half of the guarantee (`user.name` and
    * `user.email` in `RUN_GIT_CONFIG`) does not depend on this file at all.
    */
-  function installHooks(dir) {
+  function installHooks(dir, publicationPolicy = {}) {
     try {
-      writeRepositoryText(dir, ".git/hooks/commit-msg", COMMIT_MSG_HOOK, { mode: 0o755, allowGit: true });
+      writeRepositoryText(dir, ".git/hooks/commit-msg", commitMsgHook(publicationPolicy), { mode: 0o755, allowGit: true });
       return { installed: true };
     } catch (e) { return { installed: false, why: e.message }; }
   }
 
   return {
+    async probeAccess(repo, base, expectedSha) {
+      assertBranchName(base);
+      const { repository } = registry.inspect(repo), remote = registry.remote(repository);
+      const { stdout } = await exec("git", ["ls-remote", "--exit-code", "--heads", remote.url, `refs/heads/${base}`], { env: await env(repository), timeout: GIT_TIMEOUT_MS });
+      const rows = stdout.trim().split("\n");
+      if (rows.length !== 1 || rows[0] !== `${expectedSha}\trefs/heads/${base}`) throw new Error("Git and API base identities differ or changed during preflight; retry a complete repository inspection");
+      return { gitRead: "proved", gitPush: "unknown" };
+    },
+    /** The checkout's current commit, for pinning a read-only context snapshot. */
+    revision: dir => git(["rev-parse", "--verify", "HEAD^{commit}"], dir),
+    /**
+     * Read-only listings for the intake snapshot, NUL-delimited and bounded by
+     * GIT_PATH_LIMITS. `treePaths` enumerates the recorded commit's tree, so a
+     * listing and the revision it is pinned to describe the same state; the
+     * index listings only decide which of those paths the checkout's ignore
+     * rules exclude (ignore evaluation needs the index) and which it can vouch for.
+     */
+    treePaths: (dir, revision) => gitPaths(["ls-tree", "-r", "-z", "--name-only", "--full-tree", `${revision}^{tree}`], dir),
+    indexPaths: dir => gitPaths(["ls-files", "-z", "--cached", "--full-name"], dir),
+    // Only in-tree .gitignore files decide ignores (no info/exclude or global
+    // excludes), and `ignoreRuleChanges` reports every .gitignore whose working
+    // copy differs from the recorded revision or is untracked, so the snapshot
+    // can refuse to evaluate rules that the recorded tree does not contain.
+    ignoredTrackedPaths: dir => gitPaths(["ls-files", "-z", "--cached", "--ignored", "--exclude-per-directory=.gitignore", "--full-name"], dir),
+    ignoreRuleChanges: async (dir, revision) => {
+      const changed = await gitPaths(["diff", "-z", "--name-only", `${revision}^{commit}`, "--", ":(glob,top)**/.gitignore", ":(top).gitignore"], dir);
+      const untracked = await gitPaths(["ls-files", "-z", "--others", "--full-name", "--", ":(glob,top)**/.gitignore", ":(top).gitignore"], dir);
+      return [...new Set([...changed, ...untracked])];
+    },
     containsCommit: async (dir, sha) => {
       try { await git(["merge-base", "--is-ancestor", sha, "HEAD"], dir); return true; }
       catch (e) { if (e.code === 1) return false; throw e; }
@@ -209,9 +304,13 @@ export function makeGit({ config, exec = execFileAsync, credential = async () =>
       if (!listing) return null;
       if (!listing.startsWith("100644 blob ") && !listing.startsWith("100755 blob ")) throw new Error(`${path} at ${ref} is not a regular file`);
       // Keep final newlines: these bytes are compared with the approved source snapshot.
-      return (await exec("git", ["show", `${ref}:${path}`], { cwd: dir, env: await env(), timeout: GIT_TIMEOUT_MS })).stdout;
+      return (await exec("git", ["show", `${ref}:${path}`], { cwd: dir, env: await env(bindings.get(dir)), timeout: GIT_TIMEOUT_MS })).stdout;
     },
     installHooks,
+    publicationPaths: (dir, base) => {
+      assertBranchName(base);
+      return gitPaths(["diff", "--name-only", "--diff-filter=ACMRT", "-z", `refs/remotes/origin/${base}...HEAD`], dir);
+    },
     ensureHttpsRemote,
     /**
      * Fresh worktree on a new branch cut from `base` on the remote.
@@ -220,7 +319,7 @@ export function makeGit({ config, exec = execFileAsync, credential = async () =>
      * branch when nothing configured one. It used to be `defaultBranch` and nothing else, which cut every branch from
      * the repository's default even for a project whose pull requests all target `staging`.
      *
-     * The fetch is the reason the clone is not the whole of this. `gh repo clone --no-checkout` brings the remote's
+     * The fetch is the reason the clone is not the whole of this. `git clone --no-checkout` brings the remote's
      * refs as they are at clone time, which for a fresh directory is current; for one whose parent directory was left
      * behind by a previous run it is whatever git last saw. Fetching the base by name before cutting from it is what
      * makes "cut from the current base" true rather than nearly true, and it is the whole of what a rebase would have
@@ -229,10 +328,11 @@ export function makeGit({ config, exec = execFileAsync, credential = async () =>
     async create({ nameWithOwner, prdId, base }) {
       let cloneAttempted = false;
       try {
+        assertBranchName(base); assertBranchName(prdId);
         const path = worktreePath(config, nameWithOwner, prdId);
         if (exists(join(path, ".git"))) throw new Error(`worktree already exists at ${path}`);
         ensureDir(join(path, ".."), 0o755);
-        await gh(["repo", "clone", cloneUrl(nameWithOwner), path, "--", "--filter=blob:none", "--no-checkout"], undefined, CLONE_TIMEOUT_MS, () => { cloneAttempted = true; });
+        await clone(nameWithOwner, path, ["--no-checkout"], () => { cloneAttempted = true; });
         await git(["fetch", "origin", base], path);
         await git(["checkout", "-b", branchFor(prdId), `origin/${base}`], path);
         installHooks(path);
@@ -294,18 +394,19 @@ export function makeGit({ config, exec = execFileAsync, credential = async () =>
      * reused.
      */
     async fromBranch({ nameWithOwner, prdId, branch, path = worktreePath(config, nameWithOwner, prdId) }) {
+      assertBranchName(branch); assertBranchName(prdId);
       if (exists(join(path, ".git"))) {
         const origin = await git(["remote", "get-url", "origin"], path);
         // Exact owner/repo, never a substring: `acme/widget-fork` is not `acme/widget`.
-        if (!remoteMatches(origin, nameWithOwner)) throw new Error(`${path} is a clone of ${origin}, not ${nameWithOwner}`);
-        await ensureHttpsRemote(path);
+        if (!remoteMatches(origin, nameWithOwner)) throw new Error(`${path} is a clone of ${safeOrigin(origin)}, not ${nameWithOwner}`);
+        await ensureHttpsRemote(path, nameWithOwner);
         await git(["fetch", "origin", branch], path);
         await git(["checkout", branch], path);
         installHooks(path);
         return path;
       }
       ensureDir(join(path, ".."), 0o755);
-      await gh(["repo", "clone", cloneUrl(nameWithOwner), path, "--", "--filter=blob:none", "--branch", branch]);
+      await clone(nameWithOwner, path, ["--branch", branch]);
       installHooks(path);
       return path;
     },
@@ -423,8 +524,8 @@ export function makeGit({ config, exec = execFileAsync, credential = async () =>
       if (pending.length) await git(["add", "--", ...pending], dir);
       if (await git(["diff", "--cached", "--name-only"], dir)) await git(["commit", "-m", "Apply execution artifacts"], dir);
     },
-    pushResult: (dir, branch) => git(["push", "--set-upstream", "origin", `HEAD:refs/heads/${branch}`], dir),
-    pushSnapshotRef: (dir, branch) => git(["push", "origin", `HEAD:refs/heads/${branch}`], dir),
+    pushResult: (dir, branch, repo = null) => git(["push", "--set-upstream", "origin", `HEAD:refs/heads/${branch}`], dir, GIT_TIMEOUT_MS, repo),
+    pushSnapshotRef: (dir, branch, repo = null) => git(["push", "origin", `HEAD:refs/heads/${branch}`], dir, GIT_TIMEOUT_MS, repo),
     async resultHeadMatches(dir, inputHead, paths) {
       try { await git(["merge-base", "--is-ancestor", inputHead, "HEAD"], dir); } catch { return false; }
       const changed = await gitPaths(["diff", "--name-only", "-z", inputHead, "HEAD"], dir);