omp-conductor 0.15.6 → 0.15.7

package/src/store.ts

@@ -864,11 +864,15 @@ export function openStore(dbPath: string): Store {
 
   const db = new Database(dbPath, { create: true });
 
+  // Set the wait before *any* pragma that may need SQLite's writer lock.
+  // journal_mode itself can return SQLITE_BUSY during another connection's
+  // close/checkpoint; setting this afterwards caused load-only CLI flakes
+  // before the schema path ever had a chance to use the timeout (#396).
+  db.exec("PRAGMA busy_timeout = 5000;");
   // WAL lets the plugin read status while the daemon is mid-write; the busy
   // timeout covers the single writer lock they still contend for.
   db.exec("PRAGMA journal_mode = WAL;");
   db.exec("PRAGMA foreign_keys = ON;");
-  db.exec("PRAGMA busy_timeout = 5000;");
   db.exec(SCHEMA);
   // #274: a terminally failed digest did not count as sent, but the old unique
   // index still blocked a replacement under the same daily key. Replace that

package/src/types.ts

@@ -125,6 +125,13 @@ export interface RepoTarget {
    * = no chain check.
    */
   migrations?: { dir: string };
+  /**
+   * Repository-native release preparation. `versionFile` is a repo-relative
+   * JSON file with a top-level string `version` (for example
+   * `omp/package.json`). A delegated tag is refused until that live value
+   * matches the requested tag; `version-bump-pr` is the mediated review path.
+   */
+  release?: { versionFile: string };
 }
 
 /**
@@ -237,6 +244,7 @@ export const DEFAULT_REPORT_POLICY: ReportingPolicy = {
  * dead config nor be asked about them by the wizard.
  */
 export const RELEASE_SHAPES = [
+  "version-bump-pr",
   "git-tag",
   "git-push-tags",
   "package-publish",
@@ -279,6 +287,7 @@ export const LEGACY_RELEASE_POLICIES = ["none", "operator-brief"] as const;
  * and `undefined !== role` is only accidentally safe.
  */
 export const DENIED_RELEASE_GRANTS: ResolvedGrants = {
+  "version-bump-pr": "human",
   "git-tag": "human",
   "git-push-tags": "human",
   "package-publish": "human",
@@ -293,6 +302,7 @@ export const DENIED_RELEASE_GRANTS: ResolvedGrants = {
  * gave — see #122.
  */
 export const OPERATOR_BRIEF_GRANTS: ResolvedGrants = {
+  "version-bump-pr": "orchestrator",
   "git-tag": "orchestrator",
   "git-push-tags": "orchestrator",
   "package-publish": "orchestrator",
@@ -492,6 +502,21 @@ export const MERGE_REASONS = [
 
 export type MergeReason = (typeof MERGE_REASONS)[number];
 
+/**
+ * A one-PR provenance exception an operator placed in config for recovery.
+ *
+ * It replaces broad standing merge authority for this exact request and lets
+ * an orchestrator present an otherwise-unrecorded PR to the ordinary merge
+ * gate, including while dispatch is held. It does not relax the normal merge
+ * checks. Exact URL, head and reason binding keeps the exception narrower
+ * than the action it authorizes (#382).
+ */
+export interface RecoveryMergeAuthorization {
+  prUrl: string;
+  headSha: string;
+  reason: Extract<MergeReason, "operator-instructed">;
+}
+
 /** Why a release is being cut now. Closed for the reason {@link MERGE_REASONS} is. */
 export const RELEASE_REASONS = [
   /** The batching unit the operator described in POLICY.md has been reached. */
@@ -622,6 +647,13 @@ export interface ProjectConfig {
    * reaching for `.merge` on a project some test hand-built.
    */
   policy?: ProjectPolicy;
+  /**
+   * Exact operator-authored exceptions for recovery PRs that no run recorded.
+   * Optional and hand-edited: setup preserves entries but never invents them.
+   * Each entry still passes routing, live-head, checks, migration-chain, and
+   * single-flight gates.
+   */
+  recoveryMerges?: RecoveryMergeAuthorization[];
   /**
    * How loud the orchestrator is, and when the daily rollup happens. Optional
    * on disk — a config written before this key existed loads as
@@ -1836,6 +1868,8 @@ export const VERB_REFUSALS = [
   "open-pr-lookup-error",
   /** The named pull request is not this run's, or not this project's. */
   "pr-not-this-run",
+  /** An unrecorded recovery PR was authorized, but not for these exact inputs. */
+  "recovery-authorization-mismatch",
   /** The run has no pull request to act on. */
   "pr-missing",
   /**

package/src/verbs/actions.ts

@@ -22,7 +22,7 @@ import type { ActionOutcome, ReleaseExecution, VerbActions } from "./server.ts";
 /**
  * What this daemon can actually cut.
  *
- * The three GitHub-shaped ones, and deliberately not `package-publish` or
+ * The four GitHub-shaped ones, and deliberately not `package-publish` or
  * `deploy`: the daemon holds a GitHub credential and nothing else — no npm
  * token, no registry login, no deploy key — and that is deliberate. A shape
  * outside this list is refused by name in `server.ts` rather than
@@ -31,6 +31,7 @@ import type { ActionOutcome, ReleaseExecution, VerbActions } from "./server.ts";
  * of them tells an operator to go and do it themselves.
  */
 export const GITHUB_RELEASABLE_SHAPES: readonly ReleaseShape[] = [
+  "version-bump-pr",
   "git-tag",
   "git-push-tags",
   "github-release",
@@ -51,6 +52,103 @@ export type CommandRunner = (
 export type MirrorPreparer = (repo: RepoTarget, mirrorRoot: string) => Promise<string>;
 
 type CommitOutcome = { ok: true; sha: string } | { ok: false; stderr: string };
+type ReadOutcome<T> = { ok: true; value: T } | { ok: false; stderr: string };
+
+interface VersionPullRequest {
+  url: string;
+  headRefOid: string;
+  baseRefOid: string;
+  headRefName: string;
+  baseRefName: string;
+  files: { path: string }[];
+}
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+const RELEASE_VERSION_TAG = new RegExp(`^v(${SEMVER.source.slice(1, -1)})$`);
+
+function versionFromTag(tag: string): string | undefined {
+  return RELEASE_VERSION_TAG.exec(tag)?.[1];
+}
+
+function compareSemver(left: string, right: string): number | undefined {
+  const l = SEMVER.exec(left);
+  const r = SEMVER.exec(right);
+  if (l === null || r === null) return undefined;
+  for (let index = 1; index <= 3; index += 1) {
+    const a = BigInt(l[index] as string);
+    const b = BigInt(r[index] as string);
+    if (a !== b) return a < b ? -1 : 1;
+  }
+  const leftPre = l[4]?.split(".");
+  const rightPre = r[4]?.split(".");
+  if (leftPre === undefined || rightPre === undefined) {
+    return leftPre === rightPre ? 0 : leftPre === undefined ? 1 : -1;
+  }
+  const count = Math.max(leftPre.length, rightPre.length);
+  for (let index = 0; index < count; index += 1) {
+    const a = leftPre[index];
+    const b = rightPre[index];
+    if (a === undefined || b === undefined) return a === b ? 0 : a === undefined ? -1 : 1;
+    if (a === b) continue;
+    const aNumeric = /^\d+$/.test(a);
+    const bNumeric = /^\d+$/.test(b);
+    if (aNumeric && bNumeric) return BigInt(a) < BigInt(b) ? -1 : 1;
+    if (aNumeric !== bNumeric) return aNumeric ? -1 : 1;
+    return a < b ? -1 : 1;
+  }
+  return 0;
+}
+
+function objectFromJson(raw: string): Record<string, unknown> | undefined {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function exactVersionChange(
+  base: Record<string, unknown>,
+  head: Record<string, unknown>,
+  version: string,
+): boolean {
+  if (typeof base.version !== "string") return false;
+  return JSON.stringify({ ...base, version }) === JSON.stringify(head);
+}
+
+function versionPullRequest(raw: unknown): VersionPullRequest | undefined {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return undefined;
+  const pr = raw as Record<string, unknown>;
+  const files = pr.files;
+  if (
+    typeof pr.url !== "string" ||
+    !FULL_COMMIT.test(String(pr.headRefOid)) ||
+    !FULL_COMMIT.test(String(pr.baseRefOid)) ||
+    typeof pr.headRefName !== "string" ||
+    typeof pr.baseRefName !== "string" ||
+    !Array.isArray(files) ||
+    files.some(
+      (file) =>
+        typeof file !== "object" ||
+        file === null ||
+        Array.isArray(file) ||
+        typeof (file as Record<string, unknown>).path !== "string",
+    )
+  ) {
+    return undefined;
+  }
+  return {
+    url: pr.url,
+    headRefOid: String(pr.headRefOid).toLowerCase(),
+    baseRefOid: String(pr.baseRefOid).toLowerCase(),
+    headRefName: pr.headRefName,
+    baseRefName: pr.baseRefName,
+    files: files.map((file) => ({ path: String((file as Record<string, unknown>).path) })),
+  };
+}
 
 const FULL_COMMIT = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
 const RELEASE_TAG_CONFIG = [
@@ -105,10 +203,49 @@ export function githubVerbActions(
 ): VerbActions {
   const env = (): Record<string, string> => credentialedEnv();
 
-  const gh = async (argv: string[], cwd?: string): Promise<ActionOutcome> => {
+  const runGh = async (argv: string[], cwd?: string): Promise<{ argv: string[]; result: CommandRun }> => {
     const full = ["gh", ...argv];
-    const result = await run(full, { env: env(), ...(cwd === undefined ? {} : { cwd }) });
-    return result.ok ? { ok: true, detail: result.stdout.trim() || undefined } : failed(result, full);
+    return {
+      argv: full,
+      result: await run(full, { env: env(), ...(cwd === undefined ? {} : { cwd }) }),
+    };
+  };
+
+  const gh = async (argv: string[], cwd?: string): Promise<ActionOutcome> => {
+    const result = await runGh(argv, cwd);
+    return result.result.ok
+      ? { ok: true, detail: result.result.stdout.trim() || undefined }
+      : failed(result.result, result.argv);
+  };
+
+  const ghJson = async <T>(argv: string[], fact: string): Promise<ReadOutcome<T>> => {
+    const result = await runGh(argv);
+    if (!result.result.ok) return failed(result.result, result.argv);
+    try {
+      return { ok: true, value: JSON.parse(result.result.stdout) as T };
+    } catch {
+      return { ok: false, stderr: `${fact} returned invalid JSON` };
+    }
+  };
+
+  const readVersionDocument = async (
+    slug: string,
+    path: string,
+    ref: string,
+  ): Promise<ReadOutcome<{ sha: string; document: Record<string, unknown> }>> => {
+    const encodedPath = path.split("/").map(encodeURIComponent).join("/");
+    const file = await ghJson<{ sha?: unknown; content?: unknown }>(
+      ["api", `repos/${slug}/contents/${encodedPath}?ref=${encodeURIComponent(ref)}`],
+      `${path} at ${ref}`,
+    );
+    if (!file.ok) return file;
+    if (typeof file.value.sha !== "string" || typeof file.value.content !== "string") {
+      return { ok: false, stderr: `${path} at ${ref} returned no file SHA or content` };
+    }
+    const document = objectFromJson(Buffer.from(file.value.content.replace(/\s/g, ""), "base64").toString("utf8"));
+    return document === undefined
+      ? { ok: false, stderr: `${path} at ${ref} is not a JSON object` }
+      : { ok: true, value: { sha: file.value.sha, document } };
   };
 
   const git = async (mirror: string, args: string[]): Promise<{ argv: string[]; result: CommandRun }> => {
@@ -174,6 +311,253 @@ export function githubVerbActions(
     }
   };
 
+  const releaseVersionRefusal = async (
+    mirror: string,
+    repo: RepoTarget,
+    ref: string,
+    tag: string,
+  ): Promise<{ ok: true } | { ok: false; stderr: string }> => {
+    const versionFile = repo.release?.versionFile;
+    if (versionFile === undefined) return { ok: true };
+    const version = versionFromTag(tag);
+    if (version === undefined) {
+      return { ok: false, stderr: `${repo.name} requires a v<semver> tag because it declares ${versionFile}` };
+    }
+    const shown = await git(mirror, ["show", `${ref}:${versionFile}`]);
+    if (!shown.result.ok) return failed(shown.result, shown.argv);
+    const document = objectFromJson(shown.result.stdout);
+    if (document === undefined || typeof document.version !== "string") {
+      return { ok: false, stderr: `${versionFile} at ${ref} has no top-level string version` };
+    }
+    return document.version === version
+      ? { ok: true }
+      : {
+          ok: false,
+          stderr:
+            `refusing ${tag}: live ${versionFile} declares ${document.version}, not ${version}. ` +
+            "Land the mediated version-bump-pr first.",
+        };
+  };
+
+  const validateVersionPr = async (
+    repo: RepoTarget,
+    version: string,
+    branch: string,
+    raw: unknown,
+  ): Promise<ReadOutcome<VersionPullRequest>> => {
+    const pr = versionPullRequest(raw);
+    const versionFile = repo.release?.versionFile;
+    if (pr === undefined || versionFile === undefined) {
+      return { ok: false, stderr: "release preparation lookup returned an invalid pull request" };
+    }
+    if (
+      pr.headRefName !== branch ||
+      pr.baseRefName !== repo.defaultBranch ||
+      pr.files.length !== 1 ||
+      pr.files[0]?.path !== versionFile
+    ) {
+      return {
+        ok: false,
+        stderr:
+          `refusing release preparation ${pr.url}: expected ${branch} -> ${repo.defaultBranch} ` +
+          `with only ${versionFile} changed`,
+      };
+    }
+    const slug = repoSlugFor(repo);
+    const [base, head] = await Promise.all([
+      readVersionDocument(slug, versionFile, pr.baseRefOid),
+      readVersionDocument(slug, versionFile, pr.headRefOid),
+    ]);
+    if (!base.ok) return base;
+    if (!head.ok) return head;
+    if (!exactVersionChange(base.value.document, head.value.document, version)) {
+      return {
+        ok: false,
+        stderr:
+          `refusing release preparation ${pr.url}: ${versionFile} is not an exact version-only change to ${version}`,
+      };
+    }
+    return { ok: true, value: pr };
+  };
+
+  const prepareVersionBump = async (execution: ReleaseExecution, tag: string): Promise<ActionOutcome> => {
+    const versionFile = execution.repo.release?.versionFile;
+    if (versionFile === undefined) {
+      return {
+        ok: false,
+        stderr: `${execution.repo.name} declares no release.versionFile, so no version-bump-pr can be prepared`,
+      };
+    }
+    const version = versionFromTag(tag);
+    if (version === undefined) {
+      return { ok: false, stderr: `version-bump-pr needs a v<semver> tag, found ${JSON.stringify(tag)}` };
+    }
+
+    const repo = execution.repo;
+    const slug = repoSlugFor(repo);
+    const branch = `conductor/release-${version}`;
+    const refPath = `repos/${slug}/git/ref/heads/${encodeURIComponent(branch)}`;
+    const live = await ghJson<{ object?: { sha?: unknown } }>(
+      ["api", `repos/${slug}/git/ref/heads/${encodeURIComponent(repo.defaultBranch)}`],
+      `live ${repo.defaultBranch}`,
+    );
+    const liveSha = live.ok ? commitFrom(String(live.value.object?.sha ?? "")) : undefined;
+    if (!live.ok) return live;
+    if (liveSha === undefined) {
+      return { ok: false, stderr: `live ${repo.defaultBranch} returned no full commit SHA` };
+    }
+
+    const liveFile = await readVersionDocument(slug, versionFile, liveSha);
+    if (!liveFile.ok) return liveFile;
+    if (liveFile.value.document.version === version) {
+      return {
+        ok: true,
+        sha: liveSha,
+        detail: `${versionFile} already declares ${version} on ${repo.defaultBranch}`,
+      };
+    }
+    if (typeof liveFile.value.document.version !== "string") {
+      return { ok: false, stderr: `${versionFile} has no top-level string version` };
+    }
+    const order = compareSemver(version, liveFile.value.document.version);
+    if (order === undefined) {
+      return {
+        ok: false,
+        stderr: `${versionFile} declares non-semantic version ${JSON.stringify(liveFile.value.document.version)}`,
+      };
+    }
+    if (order <= 0) {
+      return {
+        ok: false,
+        stderr:
+          `refusing release preparation ${version}: it is not newer than live ` +
+          `${versionFile} version ${liveFile.value.document.version}`,
+      };
+    }
+
+    const listed = await ghJson<unknown[]>(
+      [
+        "pr",
+        "list",
+        "--repo",
+        slug,
+        "--head",
+        branch,
+        "--state",
+        "open",
+        "--limit",
+        "2",
+        "--json",
+        "url,headRefOid,baseRefOid,headRefName,baseRefName,files",
+      ],
+      `open release preparation for ${branch}`,
+    );
+    if (!listed.ok) return listed;
+    if (!Array.isArray(listed.value) || listed.value.length > 1) {
+      return { ok: false, stderr: `release preparation lookup for ${branch} did not return one unambiguous list` };
+    }
+    const existing = listed.value[0];
+    if (existing !== undefined) {
+      const validated = await validateVersionPr(repo, version, branch, existing);
+      return validated.ok
+        ? {
+            ok: true,
+            sha: validated.value.headRefOid,
+            detail: `reused exact version-only pull request ${validated.value.url}`,
+            review: { prUrl: validated.value.url, created: false },
+          }
+        : validated;
+    }
+
+    const branchRef = await runGh(["api", refPath, "--jq", ".object.sha"]);
+    let branchSha: string | undefined;
+    if (branchRef.result.ok) {
+      branchSha = commitFrom(branchRef.result.stdout);
+      if (branchSha === undefined) {
+        return { ok: false, stderr: `${branch} returned no full commit SHA` };
+      }
+    } else if (!/\b404\b|not found/i.test(branchRef.result.stderr)) {
+      return failed(branchRef.result, branchRef.argv);
+    }
+
+    if (branchSha === undefined) {
+      const created = await gh([
+        "api",
+        "--method",
+        "POST",
+        `repos/${slug}/git/refs`,
+        "-f",
+        `ref=refs/heads/${branch}`,
+        "-f",
+        `sha=${liveSha}`,
+      ]);
+      if (!created.ok) return created;
+      branchSha = liveSha;
+    }
+
+    const branchFile = await readVersionDocument(slug, versionFile, branchSha);
+    if (!branchFile.ok) return branchFile;
+    if (branchFile.value.document.version !== version) {
+      if (branchSha !== liveSha || JSON.stringify(branchFile.value.document) !== JSON.stringify(liveFile.value.document)) {
+        return {
+          ok: false,
+          stderr: `refusing to reuse ${branch}: it is not the live base and not an exact ${version} version bump`,
+        };
+      }
+      const content = Buffer.from(
+        `${JSON.stringify({ ...liveFile.value.document, version }, null, 2)}\n`,
+        "utf8",
+      ).toString("base64");
+      const updated = await gh([
+        "api",
+        "--method",
+        "PUT",
+        `repos/${slug}/contents/${versionFile.split("/").map(encodeURIComponent).join("/")}`,
+        "-f",
+        `message=chore: release ${repo.name} ${version}`,
+        "-f",
+        `content=${content}`,
+        "-f",
+        `sha=${branchFile.value.sha}`,
+        "-f",
+        `branch=${branch}`,
+      ]);
+      if (!updated.ok) return updated;
+    } else if (!exactVersionChange(liveFile.value.document, branchFile.value.document, version)) {
+      return { ok: false, stderr: `refusing to reuse ${branch}: ${versionFile} contains changes besides version ${version}` };
+    }
+
+    const opened = await runGh([
+      "pr",
+      "create",
+      "--repo",
+      slug,
+      "--head",
+      branch,
+      "--base",
+      repo.defaultBranch,
+      "--title",
+      `chore: release ${repo.name} ${version}`,
+      "--body",
+      `Prepare ${tag}. This PR changes only ${versionFile}; release remains blocked until it lands.`,
+    ]);
+    if (!opened.result.ok) return failed(opened.result, opened.argv);
+    const prUrl = opened.result.stdout.trim();
+    if (!/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+$/.test(prUrl)) {
+      return { ok: false, stderr: `gh pr create returned no pull request URL` };
+    }
+    const head = await ghJson<{ object?: { sha?: unknown } }>(["api", refPath], branch);
+    const headSha = head.ok ? commitFrom(String(head.value.object?.sha ?? "")) : undefined;
+    if (!head.ok) return head;
+    if (headSha === undefined) return { ok: false, stderr: `${branch} returned no full commit SHA after PR creation` };
+    return {
+      ok: true,
+      sha: headSha,
+      detail: `opened exact version-only pull request ${prUrl}`,
+      review: { prUrl, created: true },
+    };
+  };
+
   return {
     releasableShapes: GITHUB_RELEASABLE_SHAPES,
 
@@ -220,7 +604,22 @@ export function githubVerbActions(
       if (tag === undefined) {
         return { ok: false, stderr: `a ${execution.shape} needs a tag; none was given` };
       }
+      if (execution.shape === "version-bump-pr") {
+        return prepareVersionBump(execution, tag);
+      }
       if (execution.shape === "github-release") {
+        if (execution.repo.release === undefined) {
+          return gh(["release", "create", tag, "--repo", slug, "--generate-notes"]);
+        }
+        const prepared = await releaseMirror(execution.repo);
+        if (!prepared.ok) return prepared;
+        const remoteTag = await remoteTagCommit(prepared.path, tag);
+        if (!remoteTag.ok) return remoteTag;
+        if (remoteTag.sha === undefined) {
+          return { ok: false, stderr: `refusing GitHub release ${tag}: push the reviewed tag first` };
+        }
+        const versionReady = await releaseVersionRefusal(prepared.path, execution.repo, remoteTag.sha, tag);
+        if (!versionReady.ok) return versionReady;
         return gh(["release", "create", tag, "--repo", slug, "--generate-notes"]);
       }
       // The two git shapes act on the project's serialized, freshly fetched
@@ -241,6 +640,8 @@ export function githubVerbActions(
         if (!liveBefore.ok) return liveBefore;
         if (target.sha !== liveBefore.sha) return releaseTargetMoved(execution.repo, target.sha, liveBefore.sha);
 
+        const versionReady = await releaseVersionRefusal(mirror, execution.repo, target.sha, tag);
+        if (!versionReady.ok) return versionReady;
         const localTag = await git(mirror, ["rev-parse", "-q", "--verify", `refs/tags/${tag}^{commit}`]);
         let previousSha: string | undefined;
         if (localTag.result.ok) {
@@ -338,6 +739,8 @@ export function githubVerbActions(
             "A published tag is never force-moved; cut a new tag instead.",
         };
       }
+      const versionReady = await releaseVersionRefusal(mirror, execution.repo, live.sha, tag);
+      if (!versionReady.ok) return versionReady;
 
       let oldSha: string | undefined;
       if (tagSha !== live.sha) {

package/src/verbs/protocol.ts

@@ -247,7 +247,7 @@ export const VERB_SPECS: Readonly<Record<VerbName, VerbSpec>> = {
     mutating: true,
     allowedRoles: ["orchestrator"],
     description:
-      "Cut one release of one declared shape. The caller's role must equal the configured release " +
+      "Perform one mediated release step. The caller's role must equal the configured release " +
       "holder and the per-shape grant must permit it; a worker is refused whatever the config says.",
     args: {
       shape: {
@@ -270,7 +270,7 @@ export const VERB_SPECS: Readonly<Record<VerbName, VerbSpec>> = {
       tag: {
         type: "string",
         required: false,
-        description: "Tag to cut, for the git-tag and github-release shapes.",
+        description: "Tag to prepare or cut, for version-bump-pr, git-tag, and github-release.",
       },
       artefact: {
         type: "string",