@uchibeke/gallivant 0.2.1 → 0.3.0

package/lib/hosts.mjs

@@ -0,0 +1,130 @@
+import { HOST_DEFINITIONS } from "./host_definitions.mjs";
+import { github } from "./hosts/github.mjs";
+import { bitbucket } from "./hosts/bitbucket.mjs";
+import { repositoryIdentity, parseRemote, parsePullRequestUrl, savedRepository } from "./repository.mjs";
+import { requireHostCapabilities, completeItems, validateHostRecord, MAX_DIFF_BYTES } from "./host_contract.mjs";
+import { execFileAsync } from "./process.mjs";
+
+const IMPLEMENTATIONS = { [github.id]: github, [bitbucket.id]: bitbucket };
+const DEFAULT_ADAPTERS = HOST_DEFINITIONS.map(definition => ({ ...definition, ...IMPLEMENTATIONS[definition.id] }));
+
+const METHODS = ["branchExists", "repoDefaultBranch", "repoPermissions", "refSha", "containsCommit", "fileAt", "fileAtStrict", "commitDate",
+  "prView", "prDiff", "reviewEvidence", "prListMine", "prListByHead", "reviews", "inlineComments", "issueComments", "comment", "setBody", "setTitle", "setRecoveryMetadata", "markReady",
+  "addLabel", "removeLabel", "ensureLabels"];
+const LISTS = new Set(["prListMine", "prListByHead", "reviews", "inlineComments", "issueComments"]);
+const DECORATIONS = new Set(["addLabel", "removeLabel", "ensureLabels"]);
+
+/** Static, injectable registry. Each shipped host owns its own capabilities. */
+export function makeHostRegistry({ adapters = DEFAULT_ADAPTERS, config = {}, credential, exec, log, fetch, limits } = {}) {
+  const definitions = new Map(adapters.map(a => [a.host, a]));
+  if (definitions.size !== adapters.length) throw new Error("Duplicate host registration");
+  const instances = new Map();
+  function select(value, { transport = false } = {}) {
+    const repository = typeof value === "object" && value.repo ? savedRepository(value) : repositoryIdentity(value);
+    const adapter = definitions.get(repository.host);
+    if (!adapter) throw new Error(`Unsupported repository host ${repository.host}; this release has no qualified adapter. Use a supported checkout before init, doctor, start or register.`);
+    if (!transport) {
+      if (adapter.dispatch === false) throw new Error(adapter.dispatchReason);
+      requireHostCapabilities(adapter);
+    }
+    if (value?.repo && value.url) {
+      const target = adapter.parsePr(value.url);
+      if (!target || repositoryIdentity(target.repo).remoteIdentity !== repository.remoteIdentity || (value.pr != null && target.number !== value.pr)) throw new Error("Ambiguous saved PR identity; back up state and reconcile its repository, URL and PR number before retrying. Do not redispatch.");
+    }
+    if (!instances.has(repository.remoteIdentity)) instances.set(repository.remoteIdentity, adapter.create({ config, exec, log, fetch, limits, credential: async options => {
+      const resolved = await (credential ? credential({ ...options, ...repository }) : adapter.credential(config, { ...options, ...repository }));
+      if (!resolved?.token) throw Object.assign(new Error(resolved?.why || "Host API authorization is missing; a Git SSH key cannot authorize API operations"), { code: "NO_CREDENTIAL" });
+      if (resolved.host && resolved.host !== adapter.host || resolved.repository && resolved.repository !== repository.path) throw new Error("API credential host/repository mismatch");
+      return resolved;
+    } }));
+    return { repository, adapter, api: instances.get(repository.remoteIdentity) };
+  }
+  const inspect = value => select(value, { transport: true });
+  const registry = {
+    select, inspect,
+    fromRemote: url => select(parseRemote(url)),
+    inspectRemote: url => {
+      const remote = parseRemote(url), selected = inspect(remote);
+      if (remote.host !== "github.com" && !["https", "ssh"].includes(remote.transport)) throw new Error("Unsupported repository transport; use HTTPS or SSH");
+      return selected;
+    },
+    fromUrl: (url, options) => {
+      const envelope = parsePullRequestUrl(url), adapter = definitions.get(envelope.host);
+      if (!adapter) throw new Error(`Unsupported repository host ${envelope.host}; no qualified PR adapter is installed`);
+      const parsed = adapter.parsePr(url);
+      if (!parsed) throw new Error("Invalid pull request URL; use its canonical qualified URL");
+      return { ...select(parsed.repo, options), number: parsed.number };
+    },
+    credential: async value => {
+      const { repository, adapter } = select(value);
+      const resolved = credential ? await credential(repository) : await adapter.credential(config, repository);
+      if (resolved?.host && resolved.host !== repository.host || resolved?.repository && resolved.repository !== repository.path) throw new Error("Credential host mismatch; restore the explicitly bound credential");
+      return { ...resolved, host: repository.host, repository: repository.path };
+    },
+    gitCredential: async value => {
+      const { repository, adapter } = inspect(value);
+      const resolved = credential ? await credential({ ...repository, operation: "git" }) : await adapter.credential(config, { ...repository, operation: "git" });
+      if (resolved?.host && resolved.host !== repository.host || resolved?.repository && resolved.repository !== repository.path) throw new Error("Git credential host/repository mismatch");
+      return { ...resolved, host: repository.host, repository: repository.path };
+    },
+    remote: value => {
+      const { repository, adapter } = inspect(value), remote = adapter.remote(repository, config);
+      if (parseRemote(remote.url).remoteIdentity !== repository.remoteIdentity || parseRemote(remote.url).url !== remote.url || remote.host !== repository.host || remote.path !== repository.path) throw new Error("Adapter remote identity mismatch");
+      return remote;
+    },
+  };
+  const api = Object.fromEntries(METHODS.map(method => [method, async (repo, ...args) => {
+    const selected = inspect(repo);
+    if (DECORATIONS.has(method) && !selected.adapter.capabilities.labels) return;
+    if (typeof selected.api[method] !== "function") throw new Error(`Required host operation ${method} is unavailable; preserve state and recover host access`);
+    const value = await selected.api[method](selected.repository.path, ...args);
+    if (LISTS.has(method)) {
+      const items = completeItems(value, method);
+      for (const item of items) validateHostRecord(item, selected.repository.host, { pr: method.startsWith("prList"), event: !method.startsWith("prList") });
+      if (method === "prListByHead" && items.filter(pr => !pr.isCrossRepository).length > 1) throw new Error("Ambiguous PR ownership for the saved branch; reconcile its open PRs before retrying. Do not redispatch.");
+      if (method.startsWith("prList")) for (const pr of items) {
+        const target = registry.fromUrl(pr.url, { transport: true });
+        if (target.repository.remoteIdentity !== selected.repository.remoteIdentity || target.number !== pr.number) throw new Error("PR list identity mismatch; preserve recovery state");
+      }
+      return items;
+    }
+    if (method === "prView" || method === "setRecoveryMetadata") {
+      validateHostRecord(value, selected.repository.host, { pr: true, full: true });
+      const target = registry.fromUrl(value?.url, { transport: true });
+      if (target.repository.remoteIdentity !== selected.repository.remoteIdentity || target.number !== args[0] || value.number !== args[0]) throw new Error("PR response identity mismatch; preserve state and reconcile the saved PR");
+    }
+    if (method === "prDiff" && (typeof value !== "string" || Buffer.byteLength(value) >= MAX_DIFF_BYTES)) throw new Error("Unreadable or incomplete host diff");
+    return value;
+  }]));
+  Object.assign(api, {
+    user: options => select(config.repos?.[0]?.repo ?? config.repos?.[0] ?? repositoryIdentity("owner/name", adapters[0].host)).api.user(options),
+    userFor: (repo, options) => select(repo).api.user(options),
+    repoInfo: async dir => {
+      const origin = (await (exec ?? execFileAsync)("git", ["remote", "get-url", "origin"], { cwd: dir })).stdout.trim();
+      const { repository, api: selected } = registry.inspectRemote(origin);
+      const info = await selected.repoInfo(dir, repository.path);
+      if (repositoryIdentity(info.nameWithOwner, repository.host).remoteIdentity !== repository.remoteIdentity) throw new Error("Checkout and API repository identities differ; restore origin before dispatch");
+      return { ...info, nameWithOwner: repository.key, repository: info.repository ?? repository };
+    },
+    publishResultPr: async options => {
+      const { repository, api: selected } = inspect(options.repo);
+      const result = await selected.publishResultPr({ ...options, repo: repository.path });
+      const target = registry.fromUrl(result?.url, { transport: true });
+      if (target.repository.remoteIdentity !== repository.remoteIdentity || target.number !== result.number) throw new Error("Published PR identity mismatch; reconcile before retrying");
+      return result;
+    },
+  });
+  return { ...registry, api };
+}
+
+export const hosts = makeHostRegistry();
+// gh is a compatibility injection seam for old integrations and offline fixtures only.
+export const hostApi = ctx => ctx.host ?? ctx.hosts?.api ?? ctx.gh;
+export const repoFromUrl = url => { try { const found = hosts.fromUrl(url); return { repo: found.repository.key, number: found.number }; } catch { return null; } };
+export const hostPrompts = repo => hosts.select(repo || "owner/name").adapter.prompts;
+export const completionAdapter = (repo, registry = hosts) => registry.select(repo || "owner/name").adapter.id;
+
+export function pullRequestUrl(repo, number, registry = hosts) {
+  if (!Number.isSafeInteger(Number(number)) || Number(number) < 1) return null;
+  try { const { adapter, repository } = registry.inspect(repo); return adapter.prUrl(repository, Number(number)); } catch { return null; }
+}

package/lib/learning_qualification.mjs

@@ -5,7 +5,7 @@ import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readlinkSync, rmSy
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { verificationSandboxSpec } from "./verification_sandbox.mjs";
-import { execFileAsync } from "./gh.mjs";
+import { execFileAsync } from "./process.mjs";
 import { hash } from "./learning_data.mjs";
 
 const PROBE = `const fs=require('node:fs'),cp=require('node:child_process'),net=require('node:net');

package/lib/notify.mjs

@@ -12,7 +12,7 @@ import { shortRepo } from "./state.mjs";
 export const messages = {
   ready: ({ entry, max, checks, reviewerNote }) => ({
     title: `${shortRepo(entry.repo)}#${entry.pr} ready for a human`,
-    body: `Round ${entry.iteration}/${max}. Reviewer: ${reviewerNote}. Checks green (${checks}).`,
+    body: `Round ${entry.iteration}/${max}. Reviewer: ${reviewerNote}. ${checks ? `Checks green (${checks}).` : "No checks reported; inspect the recorded CI policy."}${entry.gate_skipped ? ` Completion gate skipped (${entry.gate_skipped}).` : ""}`,
     priority: "default", tags: "white_check_mark", click: entry.url,
   }),
   needs: ({ entry, max, handle }) => ({

package/lib/openai_agents_input.mjs

@@ -2,14 +2,19 @@
 import { prepareAgentsSources } from "./openai_agents_sources.mjs";
 import { executionError } from "./execution_io.mjs";
 import { taskProviderAllowance } from "./task_allowance.mjs";
+import { parsePrd } from "./prd.mjs";
+import { publicationPolicyOf, workArtifactReason } from "./work_artifacts.mjs";
 export async function agentsInput(ctx, id, entry, input, contextPaths) {
   if (contextPaths?.length) throw executionError("EXECUTION_POLICY", "hosted backend cannot enforce configured read-only private context_paths");
   const config = ctx.config.harness[entry.harness];
   if (!config) throw executionError("AGENTS_CONFIG", "selected managed API account is not configured");
   const overlays = [];
-  if (entry.prd) overlays.push({ path: entry.prd, text: ctx.readPrd(id) });
+  const brief = ctx.readPrd(id);
+  if (entry.prd) overlays.push({ path: entry.prd, text: brief });
   for (const path of entry.sources || []) overlays.push({ path, text: ctx.readSource(id, path) });
-  const source = await prepareAgentsSources({ worktree: entry.worktree, inputHead: input.inputHead, repo: entry.repo, branch: entry.branch, base: entry.base, overlays });
+  const policy = publicationPolicyOf(parsePrd(brief || "", entry.prd || `${id}.md`), { sources: entry.sources || [] });
+  const deliveryPaths = overlays.filter(item => !workArtifactReason(item.path, policy)).map(item => item.path);
+  const source = await prepareAgentsSources({ worktree: entry.worktree, inputHead: input.inputHead, repo: entry.repo, branch: entry.branch, base: entry.base, overlays, deliveryPaths });
   return { ...input, repo: entry.repo, branch: entry.branch, base: entry.base, allowance: taskProviderAllowance(config.allowance, entry.task), mandatoryPolicy: config.mandatory_policy || [], model: config.model, environment: config.environment,
     sources: { data: source.bytes.toString("base64"), hash: source.hash, hashes: source.hashes, modes: source.modes, inputHead: source.inputHead, repo: source.repo, branch: source.branch } };
 }

package/lib/openai_agents_sources.mjs

@@ -15,19 +15,28 @@ export function portablePath(path) {
 }
 // Only approved brief/source overlays may differ from HEAD. An explicit resume
 // must never describe preserved local edits while dispatching stale Git blobs.
-export async function assertAgentsCheckout({ worktree, overlays = [], signal }, exec = sourceExec) {
+export async function assertAgentsCheckout({ worktree, overlays = [], immutableOverlays = false, signal }, exec = sourceExec) {
   const allowed = new Set(overlays.map(item => portablePath(typeof item === "string" ? item : item.path)));
   const { stdout } = await exec("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { cwd: worktree, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" }, signal, encoding: "utf8", maxBuffer: 10 * 1024 * 1024, timeout: 20_000 });
   for (const entry of stdout.split("\0").filter(Boolean)) {
-    if (entry.length < 4 || entry[2] !== " " || /[RCU]/.test(entry.slice(0, 2)) || !allowed.has(entry.slice(3))) {
+    if (entry.length < 4 || entry[2] !== " " || /[RCU]/.test(entry.slice(0, 2)) || !allowed.has(entry.slice(3)) ||
+        immutableOverlays && !["??", " M"].includes(entry.slice(0, 2))) {
       throw executionError("AGENTS_DIRTY_SOURCE", "hosted execution requires unfinished repository edits to be committed before resume; preserve the index/worktree, commit the intended changes on the owned branch, then resume the existing session; only approved brief/source overlays may remain uncommitted");
     }
   }
+  // Verification may read private overlays, but cannot change, delete, stage or
+  // replace them with links. Check bytes even for ignored or Git-clean inputs.
+  if (immutableOverlays) for (const item of overlays) {
+    if (typeof item.text !== "string" || item.text.includes("\0") || readRepositoryText(worktree, item.path) !== item.text) {
+      throw executionError("AGENTS_DIRTY_SOURCE", "private carried input differs from its immutable approved snapshot");
+    }
+  }
 }
 // Immutable Git blobs, plus the foundation's explicitly snapshotted brief and
 // carried sources. Never upload the checkout's environment or Git history.
-export async function prepareAgentsSources({ worktree, inputHead, repo, branch, base, overlays = [], signal }, exec = sourceExec) {
+export async function prepareAgentsSources({ worktree, inputHead, repo, branch, base, overlays = [], deliveryPaths = [], signal }, exec = sourceExec) {
   if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(inputHead || "") || !/^[\w.-]+\/[\w.-]+$/.test(repo || "") || typeof branch !== "string" || branch === base) throw executionError("AGENTS_SOURCE", "exact source head and owned repository/branch/base are required");
+  if (!Array.isArray(deliveryPaths) || new Set(deliveryPaths).size !== deliveryPaths.length || deliveryPaths.some(path => !overlays.some(item => item.path === portablePath(path)))) throw executionError("AGENTS_SOURCE", "delivery paths must name exact selected source overlays");
   const options = { cwd: worktree, signal, encoding: "utf8", maxBuffer: 10 * 1024 * 1024, timeout: 20_000 };
   const { stdout: head } = await exec("git", ["rev-parse", "HEAD"], options);
   if (head.trim() !== inputHead) throw executionError("AGENTS_SOURCE", "source head changed during preparation");
@@ -54,11 +63,10 @@ export async function prepareAgentsSources({ worktree, inputHead, repo, branch,
   assertRepositoryTargets([...files.keys()], [...files.keys()]);
   await assertAgentsCheckout({ worktree, overlays, signal }, exec);
   if ((await exec("git", ["rev-parse", "HEAD"], options)).stdout.trim() !== inputHead) throw executionError("AGENTS_SOURCE", "source head changed during preparation");
-  // Carried files can be uncommitted on the coordinator's fresh checkout. Include
-  // them in delivery even when the agent leaves their approved bytes unchanged,
-  // so the single PR writer commits them with the implementation. Later receipt
-  // repairs use the same verified files without manufacturing a code change.
-  const manifest = { version: 1, inputHead, repo, branch, base, deliveryPaths: overlays.map(item => item.path), files: [...files.values()] };
+  // Reading an approved input does not authorize publishing it. Only selected
+  // output overlays (the brief and exact operator-approved deliverables) are
+  // forced into unchanged results; every private input still retains its hash.
+  const manifest = { version: 1, inputHead, repo, branch, base, deliveryPaths, files: [...files.values()] };
   const bytes = gzipSync(Buffer.from(JSON.stringify(manifest)));
   if (bytes.length > AGENTS_LIMITS.uploadBytes || bytes.length * 4 / 3 > AGENTS_LIMITS.inputBytes - 65_536) throw executionError("AGENTS_SIZE", "portable snapshot exceeds inline request limits; reduce explicitly selected context");
   return { bytes, hash: contentHash(bytes), inputHead, repo, branch, base, hashes: Object.fromEntries(manifest.files.map(f => [f.path, f.hash])), modes: Object.fromEntries(manifest.files.map(f => [f.path, f.mode])) };

package/lib/plugin_package.mjs

@@ -325,7 +325,19 @@ export function buildPluginPackage({ config, out, coreVersion, sourceCommit, int
   }
   const archive = join(out, "aport-task-delivery.zip");
   execFileSync("zip", ["-X", "-q", archive, ...Object.keys(hashes).sort()], { cwd: stage });
-  const runtime = { ...contracts, sourceCommit, sourceVerified, uncommittedPayload: payloadChanges, requirements: NODE_RUNTIME_REQUIREMENTS, exports: pkg.exports, endpoint, resource,
+  // The shared typed-profile validator ships byte-identical in the runtime
+  // tarball and in Agent Passport. The committed pin is the ship gate for both.
+  const intakeContract = JSON.parse(readFileSync(join(root, "templates/plugin/task-intake-contract.json"), "utf8"));
+  // Every pinned file (validator and fixture corpus) must ship in the tarball
+  // with the pinned bytes, so a consumer of the published artifact can run the
+  // exact promised corpus rather than only compare a hash.
+  for (const [path, pinnedHash] of Object.entries(intakeContract.files || {})) {
+    if (!payloadHashes[path]) throw deliveryError("PACKAGE_SOURCE", `Pinned task-intake file ${path} is not in the packed runtime; keep it under a packaged path`);
+    if (payloadHashes[path] !== pinnedHash) throw deliveryError("PACKAGE_SOURCE", `Packed ${path} differs from the committed task-intake contract pin; review the change and run npm run contract:intake -- --write before packaging`);
+  }
+  const validatorHash = payloadHashes[intakeContract.validator];
+  const runtime = { ...contracts, intakeContract: { profileVersion: intakeContract.profileVersion, validator: intakeContract.validator, validatorSha256: validatorHash, fixtures: intakeContract.fixtures, fixturesSha256: intakeContract.files[intakeContract.fixtures] },
+    sourceCommit, sourceVerified, uncommittedPayload: payloadChanges, requirements: NODE_RUNTIME_REQUIREMENTS, exports: pkg.exports, endpoint, resource,
     coreArtifact: packed.filename, coreSha256: sha(readFileSync(join(out, packed.filename))), dependencyLockSha256: sha(lock), assetHashes: hashes };
   writeFileSync(join(out, "runtime.json"), json(runtime));
   writeFileSync(join(out, "operations.json"), json(TASK_OPERATIONS));

package/lib/pr_operation.mjs

@@ -0,0 +1,41 @@
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { execFileAsync } from "./process.mjs";
+import { makeHostRegistry } from "./hosts.mjs";
+import { parseRemote, repositoryIdentity, assertBranchName } from "./repository.mjs";
+
+// Small, bounded PR operation surface for a local session. No config-directory
+// reads, remote installation, shell expansion, merge or repository settings API.
+export async function prOperation(argv, { env = process.env, cwd = process.cwd(), exec = execFileAsync, registry = null, read = path => readFileSync(path, "utf8") } = {}) {
+  const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: Object.fromEntries(
+    ["base", "head", "title-file", "body-file", "reply-to"].map(k => [k, { type: "string" }])) });
+  const [operation, number] = positionals;
+  if (!["create", "view", "diff", "edit", "comment"].includes(operation) || positionals.length !== (operation === "create" ? 1 : 2)) throw new Error("Use task-pr create --base <branch> --head <branch> --title-file <file> --body-file <file>, or view|diff|edit|comment <number>");
+  const allowed = { create: ["base", "head", "title-file", "body-file"], view: [], diff: [], edit: ["body-file"], comment: ["body-file", "reply-to"] }[operation];
+  if (Object.keys(values).some(k => !allowed.includes(k))) throw new Error("Unsupported option for this PR operation");
+  if (!env.HOST_API_HOST || !env.HOST_API_REPOSITORY || !env.HOST_API_TOKEN) throw new Error("No bound host API credential; run this command only in the authorized task session");
+  const repository = repositoryIdentity(env.HOST_API_REPOSITORY, env.HOST_API_HOST);
+  const git = async args => (await exec("git", args, { cwd })).stdout.trim();
+  if (parseRemote(await git(["remote", "get-url", "origin"])).remoteIdentity !== repository.remoteIdentity) throw new Error("Checkout differs from the bound API repository");
+  const branch = assertBranchName(await git(["branch", "--show-current"]));
+  const settings = env.HOST_API_BINDING ? JSON.parse(env.HOST_API_BINDING) : null;
+  registry ??= makeHostRegistry({ config: settings ? { git_hosts: { [repository.host]: { repositories: { [repository.path]: settings } } } } : {},
+    credential: async () => ({ host: repository.host, repository: repository.path, token: env.HOST_API_TOKEN, email: env.HOST_API_EMAIL }) });
+  const api = registry.api;
+  const body = () => { if (!values["body-file"]) throw new Error("--body-file is required"); return read(values["body-file"]); };
+  if (operation === "create") {
+    if (values.head !== branch || !values["title-file"]) throw new Error("--head must match the current branch and --title-file is required");
+    assertBranchName(values.base);
+    return api.publishResultPr({ repo: repository.key, branch, base: values.base, title: read(values["title-file"]).trim(), body: body() });
+  }
+  if (!/^[1-9]\d*$/.test(number ?? "") || !Number.isSafeInteger(Number(number))) throw new Error("Use an exact positive PR number");
+  const n = Number(number), pr = await api.prView(repository.key, n);
+  if (pr.headRefName !== branch || pr.isCrossRepository) throw new Error("PR is not owned by this checkout branch");
+  if (operation === "view") return pr;
+  if (operation === "diff") return api.prDiff(repository.key, n);
+  if (pr.state !== "OPEN") throw new Error("Only an open PR may be edited or answered");
+  if (operation === "edit") return api.setBody(repository.key, n, body());
+  const replyTo = values["reply-to"] === undefined ? null : Number(values["reply-to"]);
+  if (replyTo !== null && (!/^[1-9]\d*$/.test(values["reply-to"]) || !Number.isSafeInteger(replyTo))) throw new Error("Invalid reply parent");
+  return api.comment(repository.key, n, body(), { replyTo });
+}

package/lib/prd.mjs

@@ -1,3 +1,5 @@
+import { publicationPolicyOf } from "./work_artifacts.mjs";
+import { hostApi } from "./hosts.mjs";
 // The contract. It is the one gate: a brief that fails any rule cannot be marked ready and cannot start. There is no
 // override flag. The rules are data so `ready --check` can print them as a checklist.
 //
@@ -11,6 +13,7 @@ import { shortHash } from "./hash.mjs";
 import { readText } from "./fs.mjs";
 import { readRepositoryText } from "./repository_files.mjs";
 import { OWNER_DELIVERY_SECTION, ownerDeliveryFromPrd } from "./owner_delivery.mjs";
+import { DELIVERY_PROFILE_SECTION, deliveryProfileFromPrd } from "./task_profile.mjs";
 
 export const RULES = Object.freeze([
   { id: "path", kinds: ["prd"], text: "lives under docs/prds/ with a lowercase-dash filename" },
@@ -23,6 +26,7 @@ export const RULES = Object.freeze([
   { id: "look", text: "## Where to look: files or directories to start from, or 'none'" },
   { id: "scope", text: "## Out of scope: at least one bullet" },
   { id: "placeholders", text: "no TODO, TBD, FIXME, ???, lorem or <angle-bracket> placeholders anywhere" },
+  { id: "publish-files", text: "publish_files names at most 100 exact repository deliverables; no globs or directories" },
   { id: "size", text: "under 1,500 words; a PRD is one pull request, split anything bigger" },
   // Scoped to `prd` because it resolves paths against the checkout the brief lives in, and only a PRD source has one.
   { id: "sources", kinds: ["prd"], text: "every file in `sources` exists, is readable text, and is named inside the repository" },
@@ -239,7 +243,7 @@ export function check(prd) {
 
   const criteria = items(s["Acceptance criteria"]);
   const badCriteria = criteria.filter(x => !GWT.test(x));
-  let ownershipError = ""; try { ownerDeliveryFromPrd(prd); } catch (error) { ownershipError = error.message; }
+  let ownershipError = ""; try { ownerDeliveryFromPrd(prd); deliveryProfileFromPrd(prd); } catch (error) { ownershipError = error.message; }
   rule("criteria", has("Acceptance criteria") && criteria.length >= Math.max(1, stories.length) && badCriteria.length === 0 && !ownershipError,
     ownershipError || (!has("Acceptance criteria") ? "section missing" : criteria.length < Math.max(1, stories.length) ? `${criteria.length} criteria for ${stories.length} stories; at least one each` : `${badCriteria.length} bullet(s) lack Given/When/Then: "${badCriteria[0]?.slice(0, 60)}"`));
 
@@ -256,6 +260,9 @@ export function check(prd) {
   const ph = findPlaceholder(prd.body);
   rule("placeholders", !ph, ph ? `found "${ph}"` : "");
 
+  try { publicationPolicyOf(prd); rule("publish-files", true, ""); }
+  catch (error) { rule("publish-files", false, error.message); }
+
   rule("size", prd.words <= MAX_WORDS, `${prd.words} words`);
 
   // The files the brief carries. Checked here rather than at `start` for the reason `resolveBase` validates the base
@@ -332,6 +339,9 @@ export const contractOf = prd => ({
   // Typed stage ownership changes what provider receipts must attest. Preserve
   // legacy fingerprints exactly; new contracts include even malformed edits.
   ...(prd.sections[OWNER_DELIVERY_SECTION] !== undefined ? { ownerDelivery: prd.sections[OWNER_DELIVERY_SECTION].replaceAll("\r\n", "\n") } : {}),
+  // The typed delivery profile is part of the contract for the same reason:
+  // editing it changes which external action the coordinator may take.
+  ...(prd.sections[DELIVERY_PROFILE_SECTION] !== undefined ? { deliveryProfile: prd.sections[DELIVERY_PROFILE_SECTION].replaceAll("\r\n", "\n") } : {}),
   // `id: description`, not the descriptions alone, and the id is the load-bearing half. `criteriaFromPrd` numbers
   // criteria BY POSITION (`ac-1`, `ac-2`), and the completion receipt on the open pull request attests those ids: an
   // attestation says `ac-1` is met, with evidence, and the gate matches it to whatever the brief's first criterion is
@@ -349,6 +359,8 @@ export const contractOf = prd => ({
   // The list, not the contents. A carried file's bytes are compared separately by `sourceDivergence`, because a diff of
   // a document belongs next to that document and not in a summary of the brief's contract.
   sources: sourcePathsOf(prd),
+  // Preserve existing fingerprints when absent; any exception edit changes authority.
+  ...(prd.meta?.publish_files !== undefined ? { publish_files: prd.meta.publish_files } : {}),
 });
 
 /**
@@ -394,6 +406,7 @@ export function contractDiff(before, after) {
   const b = contractOf(after);
   const out = [];
   if (a.ownerDelivery !== b.ownerDelivery) out.push("coordinator delivery ownership contract changed");
+  if (a.deliveryProfile !== b.deliveryProfile) out.push("typed delivery profile changed");
   // Multiplicity-aware, so a duplicate that IS reported is reported once per copy rather than swallowed. It still cannot
   // describe every change on its own, which is `sameContract`'s job; this only makes the description less lossy.
   const listDiff = (was, now) => {
@@ -422,6 +435,7 @@ export function contractDiff(before, after) {
   const sources = listDiff(a.sources, b.sources);
   for (const p of sources.gone) out.push(`source removed: ${p}`);
   for (const p of sources.added) out.push(`source added: ${p}`);
+  if (JSON.stringify(a.publish_files) !== JSON.stringify(b.publish_files)) out.push("publish_files deliverable exceptions changed");
   return out;
 }
 
@@ -573,10 +587,11 @@ export const divergenceReason = d => DIVERGENCE_REASONS[d.verdict] ?? null;
  * own judgement.
  */
 export async function ensurePrdSnapshot(ctx, { id, repo, path, ref }) {
-  const { gh, log, readPrd, writePrd } = ctx;
+  const { log, readPrd, writePrd } = ctx;
+  const host = hostApi(ctx);
   try {
     if (!path || readPrd(id)) return false;
-    const text = await gh.fileAt(repo, path, ref);
+    const text = await host.fileAt(repo, path, ref);
     if (!text) { log.warn(`${id}: ${path} not found on ${ref}; the completion gate is skipped until a snapshot exists`); return false; }
     // A CLI start may have approved its own snapshot while this network read was in flight.
     if (readPrd(id) || ctx.state?.startClaim?.(id)) return false;

package/lib/preparation_codex.mjs

@@ -66,7 +66,9 @@ function effectiveConfig(spec, { cwd, env, signal }) {
       child.kill("SIGKILL"); child.stdin.destroy();
       if (error) reject(error); else resolve(config);
     };
-    const invalid = () => finish(fail("effective configuration could not be verified; check managed Codex policy and the supported CLI version"));
+    const invalid = () => {
+      finish(fail("effective configuration could not be verified; check managed Codex policy and the supported CLI version"));
+    };
     const abort = () => finish(fail("configuration inspection was cancelled"));
     const timer = setTimeout(invalid, 20_000);
     signal?.addEventListener("abort", abort, { once: true });
@@ -179,6 +181,9 @@ export const codexPreparation = Object.freeze({
       try { config = parse(readFileSync(configPath, "utf8")); } catch { throw fail("the private provider configuration is invalid TOML"); }
       if (config.profile) throw fail("a named Codex config profile requires an explicit isolated profile snapshot");
       delete config.sandbox_mode; delete config.sandbox_workspace_write;
+      // The desktop app can persist this client-only flag even when the
+      // selected CLI version does not recognize it under --strict-config.
+      delete config.daybreak;
       // Legacy notify spawns outside the tool sandbox independently of hooks.
       delete config.notify;
       for (const key of PRIVATE_ONLY_FIELDS) delete config[key];

package/lib/probe.mjs

@@ -1,3 +1,4 @@
+import { hostApi } from "./hosts.mjs";
 // Health probes shared by `doctor`, `start` and the daemon: is each harness signed in, is gh authenticated,
 // does ntfy answer. Each returns { ok, detail } and never throws.
 import { execFile } from "node:child_process";
@@ -99,8 +100,8 @@ export async function requireHarness(harness, config, options = {}) {
   if (!result.ok) throw new Error(`${harness} is not ready (${result.detail}); ${result.fix}`);
 }
 
-export async function checkGh(gh, options = {}) {
-  try { const login = await gh.user(options); return { ok: true, detail: login }; }
+export async function checkGh(host, options = {}) {
+  try { const login = await host.user(options); return { ok: true, detail: login }; }
   catch (e) {
     const interrupted = e.code === "EXECUTION_DEADLINE" || e.name === "TimeoutError" || e.killed ? "EXECUTION_DEADLINE"
       : e.code === "EXECUTION_ABORTED" || e.code === "ABORT_ERR" || options.signal?.aborted ? "EXECUTION_ABORTED" : null;
@@ -111,8 +112,9 @@ export async function checkGh(gh, options = {}) {
 
 /** All probes the daemon needs before it dispatches anything. */
 export async function probeAll(ctx) {
-  const { config, gh } = ctx;
-  const pairs = await Promise.all([["gh", () => checkGh(gh)], ...Object.keys(config.harness).map(h => [h, () => checkHarness(h, config)])].map(async ([key, fn]) => [key, await fn()]));
+  const { config } = ctx;
+  const host = hostApi(ctx);
+  const pairs = await Promise.all([["gh", () => checkGh(host)], ...Object.keys(config.harness).map(h => [h, () => checkHarness(h, config)])].map(async ([key, fn]) => [key, await fn()]));
   const out = Object.fromEntries(pairs);
   return out;
 }

package/lib/process.mjs

@@ -0,0 +1,24 @@
+import { execFile } from "node:child_process";
+import { redact } from "./execution_io.mjs";
+
+/** Credentialed transports must sanitize every diagnostic, including cached stacks. */
+export const transportExecutor = execute => async (cmd, args, options = {}) => {
+  try { return await execute(cmd, args, options); }
+  catch (error) {
+    const secrets = Object.entries(options.env ?? {}).filter(([key, value]) => /(?:TOKEN|SECRET|KEY|PASSWORD)/i.test(key) && typeof value === "string" && value.length).map(([, value]) => value);
+    if (error && typeof error === "object") for (const field of ["stack", "message", "stderr", "stdout"]) {
+      if (typeof error[field] === "string") error[field] = redact(error[field], secrets).replace(/([a-z][a-z0-9+.-]*:\/\/)[^/\s@]*@/gi, "$1");
+    }
+    throw error;
+  }
+};
+
+/** Bounded subprocess helper shared by transports, without a host dependency. */
+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/promotion.mjs

@@ -0,0 +1,132 @@
+// A deliberately narrow cross-host handoff. Review, credentials and publication
+// remain owned by their existing services; this module never runs an agent.
+import { reviewBinding, reviewDigest, policyConfig, reviewVerdict, assertReviewPolicy } from "./review_policy.mjs";
+import { isGreen, makeTrust, readFeedback, exactReviewerVerdict, requiredFeedback, deriveEvents } from "./events.mjs";
+import { repositoryIdentity, assertBranchName } from "./repository.mjs";
+import { withoutTaskMetadata } from "./block.mjs";
+import { assertPublicText } from "./public_output.mjs";
+import { STATES } from "./state.mjs";
+import { controlPending } from "./control_contract.mjs";
+
+const sha = value => {
+  if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value || "")) throw new Error("Missing exact Git commit identity");
+  return value;
+};
+const requireOpen = pr => {
+  if (pr.state !== "OPEN" || pr.isDraft || pr.isCrossRepository !== false) throw new Error("Promotion requires an open, non-draft, same-repository PR; a merged source must retain exact accepted readiness. Merge/squash commits are not substituted.");
+};
+const requireUnstopped = entry => {
+  if (entry?.dispatch_stopped || controlPending(entry?.control)) throw new Error("Source dispatch is stopped or an operator control is pending; reconcile that request and acceptance before promotion");
+};
+
+/** Read-only live plan. A ready label or PR-authored assertion is not authority. */
+export async function planPromotion(ctx, options, transfer) {
+  const selected = ctx.hosts.fromUrl(options.githubPr, { transport: true });
+  const sourceRepo = selected.repository.key;
+  const targetRepo = repositoryIdentity(options.bitbucketRepo);
+  if (selected.repository.host !== "github.com" || targetRepo.host !== "bitbucket.org") throw new Error("Supply an explicit GitHub PR and bitbucket.org/workspace/repository mapping");
+  const found = ctx.state.findByPr(sourceRepo, selected.number);
+  const entry = found?.[1];
+  if (!entry || ![STATES.ready, STATES.done].includes(entry.state)) throw new Error("Source run must have retained accepted readiness");
+  requireUnstopped(entry);
+  const pr = await ctx.host.prView(sourceRepo, selected.number);
+  const accepted = options.acceptedPlan;
+  if (accepted) {
+    const { digest, ...payload } = accepted;
+    if (accepted.version !== 1 || reviewDigest(payload) !== digest || accepted.source?.url !== pr.url || accepted.target?.repo !== targetRepo.key) throw new Error("Accepted plan is invalid or belongs to a different repository mapping");
+  }
+  if (pr.state === "MERGED") {
+    if (pr.isCrossRepository !== false || pr.isDraft || accepted && (accepted.source?.head !== pr.headRefOid || accepted.source?.binding !== entry.review_readiness?.binding)) throw new Error("Merged source must match its retained exact readiness binding and any supplied accepted plan; never substitute the merge/squash commit");
+  } else {
+    requireOpen(pr);
+    if (entry.state !== STATES.ready) throw new Error("Open source run is no longer ready-for-human");
+  }
+  if (entry.branch !== pr.headRefName || entry.base !== pr.baseRefName) throw new Error("Source PR branch or base changed from the registered run");
+  const policy = assertReviewPolicy(entry.reviewPolicy);
+  if (policy.version !== 1) throw new Error("Promotion requires an explicit review policy; legacy/no-review clearance is not accepted");
+  let reviewedPr = pr, binding = reviewBinding(pr, policy);
+  // GitHub normally retains the original base on a merged PR. Use that exact
+  // accepted binding directly; an archived plan is only a base-reconstruction
+  // fallback and can never supply acceptance absent from coordinator state.
+  if (pr.state === "MERGED" && binding !== entry.review_readiness?.binding && accepted) {
+    reviewedPr = { ...pr, baseRefOid: sha(accepted.source.baseHead) };
+    binding = reviewBinding(reviewedPr, policy);
+  }
+  if (entry.review_readiness?.binding !== binding || entry.review_readiness?.completion !== "accepted") throw new Error("Source readiness is stale or its completion gate was not accepted; recheck the run first");
+  const config = policyConfig(ctx.config, entry);
+  if (!isGreen(pr.statusCheckRollup, config.required_checks) || (!pr.statusCheckRollup.length && policy.zeroChecks !== true)) throw new Error("Checks are not green, required checks are missing, or zero checks were not explicitly allowed");
+  const trust = makeTrust(config, await ctx.host.userFor(sourceRepo));
+  const [reviews, inline, comments] = await readFeedback(ctx.host, sourceRepo, pr);
+  if (requiredFeedback({ reviews, inline, trust, headSha: pr.headRefOid }).length) throw new Error("Required feedback remains unresolved");
+  if (!entry.cursor || !Number.isFinite(Date.parse(entry.cursor.since))) throw new Error("Source feedback cursor is missing; recheck the registered run");
+  if (deriveEvents({ pr, reviews, inline, comments, entry, trust }).events.length) throw new Error("Pending trusted feedback must be processed by the coordinator before promotion");
+  const external = await exactReviewerVerdict({ reviews, inline, comments, config, trust, sinceIso: "1970-01-01T00:00:00.000Z", headSha: pr.headRefOid }, ref => ctx.host.refSha(sourceRepo, ref));
+  const verdict = reviewVerdict(policy, external, entry.firstPartyReview, binding);
+  if (verdict.verdict !== "clear") throw new Error(`Review is not clear: ${verdict.note}`);
+  // Local working files are not promotion inputs. Fetching the exact reviewed
+  // remote ref into a disposable bare repository preserves untracked carried
+  // sources and dirty checkouts without reading or publishing any of them.
+
+  let existing = null;
+  if (options.bitbucketPr !== undefined) {
+    if (!Number.isSafeInteger(options.bitbucketPr) || options.bitbucketPr < 1) throw new Error("Invalid --bitbucket-pr number");
+    existing = await ctx.host.prView(targetRepo.key, options.bitbucketPr);
+    requireOpen(existing);
+  }
+  const branch = assertBranchName(existing?.headRefName ?? options.branch ?? `work/github-${selected.repository.path.replaceAll("/", "-")}-pr-${selected.number}`);
+  const base = assertBranchName(options.base ?? existing?.baseRefName ?? pr.baseRefName);
+  if (branch === base || existing && (existing.headRefName !== branch || existing.baseRefName !== base || options.branch && options.branch !== branch)) throw new Error("Bitbucket branch/base mapping conflicts with the selected PR");
+  const candidates = await ctx.host.prListByHead(targetRepo.key, branch, { allStates: true });
+  if (candidates.length > 1 || candidates.some(p => p.isCrossRepository !== false || p.state !== "OPEN" || p.baseRefName !== base)) throw new Error("Conflicting or duplicate Bitbucket PRs; reconcile the explicit mapping before promotion");
+  if (existing && candidates[0]?.number !== existing.number) throw new Error("Selected Bitbucket PR no longer owns this branch");
+  if (!existing && candidates.length) {
+    existing = await ctx.host.prView(targetRepo.key, candidates[0].number);
+    requireOpen(existing);
+    // A deterministic name is not permission to overwrite somebody else's PR.
+    if (!existing.body?.includes(`Source review: ${pr.url}\n`)) throw new Error("An existing PR needs an explicit --bitbucket-pr mapping");
+  }
+  const targetHead = await ctx.host.branchExists(targetRepo.key, branch) ? sha(await ctx.host.refSha(targetRepo.key, branch)) : null;
+  if (existing && targetHead !== existing.headRefOid) throw new Error("Bitbucket PR head changed during planning");
+  const body = `${withoutTaskMetadata(pr.body)}\n\nSource review: ${pr.url}\nReviewed source commit: ${sha(pr.headRefOid)}\n\nThis handoff preserves the source commits. Bitbucket merge and deployment approval remain separate.`.trim();
+  const plan = { version: 1,
+    source: { repo: sourceRepo, url: pr.url, number: pr.number, branch: pr.headRefName, head: sha(pr.headRefOid), base: pr.baseRefName, baseHead: sha(reviewedPr.baseRefOid), binding },
+    target: { repo: targetRepo.key, branch, base, head: targetHead, baseHead: sha(await ctx.host.refSha(targetRepo.key, base)), pr: existing?.number ?? null,
+      previousText: existing ? { title: existing.title, body: existing.body } : null },
+    title: assertPublicText(pr.title, "PR title"), body: assertPublicText(body, "PR body"),
+    review: { mode: policy.mode, verdict: verdict.verdict, checks: pr.statusCheckRollup.length, zeroChecks: policy.zeroChecks === true },
+  };
+  await transfer.validate(plan);
+  // Network and object validation can outlive a newly queued operator request.
+  // Re-read local authority before the caller can use this plan for a write.
+  const current = ctx.state.findByPr(sourceRepo, selected.number)?.[1];
+  requireUnstopped(current);
+  if (!current || current.state !== entry.state || current.review_readiness?.binding !== binding || current.review_readiness?.completion !== "accepted") throw new Error("Source acceptance changed during planning; inspect the run before promotion");
+  return { ...plan, digest: reviewDigest(plan) };
+}
+
+/** The approved digest binds both repositories, all heads and the public text. */
+export async function promote(ctx, options, transfer) {
+  const plan = await planPromotion(ctx, options, transfer);
+  if (!options.apply) return { applied: false, plan };
+  if (!/^[a-f0-9]{64}$/.test(options.expectedPlan || "") || options.expectedPlan !== plan.digest) throw new Error("Plan changed or approval pin missing. Run the dry run, inspect it, then pass --apply --expected-plan <digest>");
+  let pushAttempted = false, publicationAttempted = false;
+  try {
+    // Re-read immediately before the Git operation. The native pre-push hook
+    // also checks the actual advertised target old OID, closing that race.
+    const fresh = await planPromotion(ctx, options, transfer);
+    if (fresh.digest !== plan.digest) throw new Error("Source, target or review changed before push; inspect a new plan");
+    if (plan.target.head !== plan.source.head) { pushAttempted = true; await transfer.push(plan); }
+    const after = await planPromotion(ctx, options, transfer);
+    const expected = { ...plan, target: { ...plan.target, head: plan.source.head } };
+    delete expected.digest;
+    if (after.digest !== reviewDigest(expected)) throw new Error("Source, target or review changed after push; no PR was published");
+    publicationAttempted = true;
+    const result = await ctx.host.publishResultPr({ repo: plan.target.repo, branch: plan.target.branch, base: plan.target.base, title: plan.title, body: plan.body,
+      expectedNumber: plan.target.pr, expectedPreviousText: plan.target.previousText, expectAbsent: plan.target.pr === null });
+    if (result.headRefOid !== plan.source.head || result.baseRefOid !== plan.target.baseHead || result.headRefName !== plan.target.branch || result.baseRefName !== plan.target.base || plan.target.pr !== null && result.number !== plan.target.pr) throw new Error("Published PR moved during publication; inspect it before any merge");
+    return { applied: true, url: result.url, head: plan.source.head, plan };
+  } catch (error) {
+    if (pushAttempted || publicationAttempted) error.message += ` The ${publicationAttempted ? "branch or PR may already be updated for" : "branch may already contain"} ${plan.source.head}; no merge was attempted. Inspect the target and rerun the dry run; do not force-push.`;
+    throw error;
+  }
+}