omp-conductor 0.18.2 → 0.19.0

package/src/upgrade.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { backupTimestamp, copyToUniqueBackup } from "./backups.ts";
 import { inspectBriefLayout, type BriefLayout } from "./brief-upgrade.ts";
 import { pauseInstance, setPaused, statusSnapshot, type AdmissionAckRecord } from "./daemon.ts";
@@ -23,6 +24,7 @@ import {
   appendJournal,
   readUpgradeJournal,
   upgradeJournalPath,
+  type UpgradeCheck,
   type UpgradeJournalEntry,
 } from "./upgrade-journal.ts";
 import {
@@ -43,6 +45,13 @@ import {
 const PACKAGE = "omp-conductor";
 const HERDR_PLUGIN = "herdr-conductor";
 const HERDR_SOURCE = "TerrifiedBug/conductor/herdr";
+
+/** The package root inside the repo, for a bootstrap install by git ref. */
+const PACKAGE_SOURCE = "TerrifiedBug/conductor/omp";
+
+/** A 40-hex commit: the only identity shape a bootstrap accepts. A branch or a
+ *  tag is a moving target, and "the exact build I verified" is the whole point. */
+const COMMIT_SHA = /^[0-9a-f]{40}$/i;
 const HERDR_UNIT = "herdr-fleet.service";
 const DRAIN_POLL_MS = 5_000;
 const RECOVERY_POLL_MS = 2_000;
@@ -50,6 +59,22 @@ const RECOVERY_ATTEMPTS = 30;
 
 export interface UpgradeOptions {
   version?: string;
+  /**
+   * Bootstrap from an exact source/build identity instead of a published semver
+   * (#908) — the path that exists because a reliability release cannot be cut
+   * when the *installed* conductor is the thing that is broken: publishing
+   * needs working workers, and the workers are what is broken.
+   *
+   * `sha` is the whole identity (a 40-hex commit, never a range), and `source`
+   * is a checkout of exactly that commit — its only job is to be the tree the
+   * package's own checks run against before anything is installed. The install
+   * itself is by git ref, so the identity is globally attestable rather than
+   * dependent on one machine's directory.
+   *
+   * Mutually exclusive with {@link version}: two identity kinds in one call is
+   * an ambiguity, not a merge.
+   */
+  bootstrap?: { sha: string; source: string };
   project?: string;
   /**
    * Run as the detached fleet installer (#486): journal every surface the
@@ -71,6 +96,15 @@ export interface UpgradeResult {
 
 export interface UpgradeDeps {
   run(command: string, args: readonly string[]): Promise<UpgradeCommandResult>;
+  /**
+   * A command run in a named working directory (#908): the bootstrap's checks
+   * run inside the source tree, and `run` is deliberately cwd-free everywhere
+   * else so no other step can depend on where it was invoked from.
+   */
+  runIn(cwd: string, command: string, args: readonly string[]): Promise<UpgradeCommandResult>;
+  /** Read one file as text. Injected so a bootstrap's manifest read is
+   *  testable without a checkout on disk. */
+  readFile(path: string): string;
   snapshot(project?: string): { liveWorkers: number };
   layers(project?: string): FleetLayers;
   brief(project?: string): { kind: BriefLayout["kind"]; current: boolean };
@@ -145,6 +179,8 @@ export interface UpgradeDeps {
  *  post-restart verifier and the rollback unit run processes the same way. */
 export const DEFAULT_DEPS: UpgradeDeps = {
   run: runCommand,
+  runIn: (cwd, command, args) => runCommand(command, args, cwd),
+  readFile: (path) => readFileSync(path, "utf8"),
   snapshot: statusSnapshot,
   layers: fleetLayers,
   brief: (projectName) => {
@@ -191,7 +227,7 @@ function commandLine(command: string, args: readonly string[]): string {
 }
 
 async function mustRun(
-  deps: UpgradeDeps,
+  deps: SurfaceProbeDeps,
   command: string,
   args: readonly string[],
 ): Promise<UpgradeCommandResult> {
@@ -222,6 +258,108 @@ function parseRegistry(raw: string): { version: string; gitHead: string } {
   return { version, gitHead };
 }
 
+/**
+ * One release identity plus how to install it (#908).
+ *
+ * Two kinds, one shape downstream: everything after this — the currentness
+ * comparison, the journal, the install, the attestation and the rollback —
+ * reads a `{ version, gitHead }` pair and an install spec, so a bootstrap is a
+ * second accepted identity rather than a parallel installer.
+ */
+interface ReleaseIdentityPlan {
+  version: string;
+  gitHead: string;
+  /** What `bun add -g` / `omp plugin install` are given for this identity. */
+  packageSpec: string;
+  /** Named checks already run to earn this identity, journalled as evidence. */
+  checks: UpgradeCheck[];
+  /** True for a source/build identity: npm does not have this version. */
+  bootstrap: boolean;
+}
+
+/** The version a source tree declares — the identity's other half, read from
+ *  the tree itself because npm has never seen it. */
+function sourceVersion(deps: UpgradeDeps, source: string): string {
+  const manifest = join(source, "omp", "package.json");
+  let raw: string;
+  try {
+    raw = deps.readFile(manifest);
+  } catch (err) {
+    throw new Error(
+      `bootstrap refused: cannot read ${manifest} (${err instanceof Error ? err.message : String(err)}) — ` +
+        "--source must be a checkout of this repository",
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`bootstrap refused: ${manifest} is not valid JSON`);
+  }
+  const version = parsed !== null && typeof parsed === "object" ? Reflect.get(parsed, "version") : undefined;
+  if (typeof version !== "string" || version.length === 0) {
+    throw new Error(`bootstrap refused: ${manifest} declares no version`);
+  }
+  return version;
+}
+
+/**
+ * Resolve which release this run installs, and prove a bootstrap identity
+ * before it can touch anything (#908).
+ *
+ * The three refusals are the deliverable, not the install: a sha that is not a
+ * sha, a source tree that is not at that sha, and a source tree whose own
+ * checks fail. Each names the identity and what failed, and each happens before
+ * the first surface is replaced — an unverified tree must never become a live
+ * install, which is the difference between this and the `bun add github:...`
+ * POLICY forbids.
+ */
+async function resolveIdentity(deps: UpgradeDeps, options: UpgradeOptions): Promise<ReleaseIdentityPlan> {
+  const bootstrap = options.bootstrap;
+  if (bootstrap === undefined) {
+    const requested = options.version === undefined ? `${PACKAGE}@latest` : `${PACKAGE}@${options.version}`;
+    const release = parseRegistry(
+      (await mustRun(deps, "npm", ["view", requested, "version", "gitHead", "--json"])).stdout,
+    );
+    return { ...release, packageSpec: `${PACKAGE}@${release.version}`, checks: [], bootstrap: false };
+  }
+  if (options.version !== undefined) {
+    throw new Error("bootstrap refused: pass either --to VERSION or --bootstrap SHA, never both");
+  }
+  const sha = bootstrap.sha.toLowerCase();
+  if (!COMMIT_SHA.test(sha)) {
+    throw new Error(`bootstrap refused: "${bootstrap.sha}" is not a 40-character commit sha`);
+  }
+  const checks: UpgradeCheck[] = [];
+  // The tree must BE that commit. Without this the identity is a label the
+  // operator typed, and the checks below would attest a different build than
+  // the one installed.
+  const head = await deps.run("git", ["-C", bootstrap.source, "rev-parse", "HEAD"]);
+  const at = head.stdout.trim().toLowerCase();
+  if (head.code !== 0 || at !== sha) {
+    checks.push({ name: "source-at-sha", ok: false, detail: at.length === 0 ? head.stderr.trim() : at });
+    throw new Error(
+      `bootstrap refused: ${bootstrap.source} is at ${at.length === 0 ? "an unreadable HEAD" : at}, not ${sha} — ` +
+        "the checks would attest a different build than the one installed",
+    );
+  }
+  checks.push({ name: "source-at-sha", ok: true, detail: sha });
+  const version = sourceVersion(deps, bootstrap.source);
+  // The package's own declared gate, against the source, before anything is
+  // installed. A failure refuses: a partially verified tree must not go live.
+  deps.log(`bootstrap: running the package checks against ${bootstrap.source} (${sha.slice(0, 12)})`);
+  const gate = await deps.runIn(join(bootstrap.source, "omp"), "bun", ["run", "check"]);
+  if (gate.code !== 0) {
+    const detail = (gate.stderr.trim() || gate.stdout.trim()).split("\n").slice(-3).join("; ");
+    checks.push({ name: "package-checks", ok: false, detail });
+    throw new Error(
+      `bootstrap refused: \`bun run check\` failed against ${bootstrap.source} at ${sha} — ${detail}`,
+    );
+  }
+  checks.push({ name: "package-checks", ok: true });
+  return { version, gitHead: sha, packageSpec: `github:${PACKAGE_SOURCE}#${sha}`, checks, bootstrap: true };
+}
+
 function ompPluginVersion(raw: string): string | undefined {
   let parsed: unknown;
   try {
@@ -255,13 +393,43 @@ function herdrPluginSource(raw: string): string | undefined {
   return source;
 }
 
-interface InstalledSurfaces {
+/** The three installed identities one host carries: the Bun-global CLI/daemon
+ *  tree, the omp plugin, and the herdr recovery plugin's pin. */
+export interface InstalledSurfaces {
   cliVersion: string;
   ompVersion?: string;
   herdrSource?: string;
 }
 
-async function inspectSurfaces(deps: UpgradeDeps): Promise<InstalledSurfaces> {
+/** What reading the three surfaces needs — deliberately narrower than
+ *  {@link UpgradeDeps} so a read-only consumer (`doctor`'s surface-parity
+ *  finding, #904) can supply three fields instead of a whole transaction. */
+export type SurfaceProbeDeps = Pick<UpgradeDeps, "run" | "log" | "env">;
+
+/**
+ * Read the CLI, omp-plugin and herdr-plugin identities actually installed on
+ * this host. Exported because `upgrade` is not the only thing that needs to
+ * know whether the three agree: a host whose installs are manual diverges
+ * silently between transactions, and `doctor` reads them through this one
+ * seam rather than growing a second implementation (#904).
+ */
+export async function inspectSurfaces(
+  deps: SurfaceProbeDeps,
+  /** `readHerdr: false` skips the herdr session probe and plugin read
+   *  entirely, so a host with no herdr on PATH can still be asked what its
+   *  CLI and omp plugin are (#904). The upgrade transaction always reads all
+   *  three — a release pins every surface. */
+  opts: { readHerdr?: boolean } = {},
+): Promise<InstalledSurfaces> {
+  if (opts.readHerdr === false) {
+    const [cliOnly, ompOnly] = await Promise.all([
+      mustRun(deps, "omp-conductor", ["--version"]),
+      mustRun(deps, "omp", ["plugin", "list", "--json"]),
+    ]);
+    const version = cliOnly.stdout.trim();
+    if (version.length === 0) throw new Error("installed omp-conductor CLI has no version");
+    return { cliVersion: version, ompVersion: ompPluginVersion(ompOnly.stdout) };
+  }
   // HERDR_SESSION is authoritative. Otherwise prefer DEFAULT_HERDR_SESSION, with
   // #320's one-release bridge to a populated legacy "fleet" session.
   let session = resolveHerdrSession(deps.env);
@@ -302,12 +470,25 @@ async function inspectSurfaces(deps: UpgradeDeps): Promise<InstalledSurfaces> {
   };
 }
 
-function expectedHerdrSource(gitHead: string): string {
+export function expectedHerdrSource(gitHead: string): string {
   return `github:${HERDR_SOURCE}@${gitHead}`;
 }
 
+/**
+ * The published identity of one release: its version and the exact commit it
+ * was cut from, straight from the registry metadata `upgrade` already trusts.
+ * Exported so a read-only consumer can answer "which commit should this
+ * host's herdr plugin be pinned to?" without re-deriving the mapping (#904).
+ */
+export async function releaseIdentity(
+  deps: SurfaceProbeDeps,
+  version: string,
+): Promise<{ version: string; gitHead: string }> {
+  return parseRegistry((await mustRun(deps, "npm", ["view", `${PACKAGE}@${version}`, "version", "gitHead", "--json"])).stdout);
+}
+
 function surfacesCurrent(
-  surfaces: Awaited<ReturnType<typeof inspectSurfaces>>,
+  surfaces: InstalledSurfaces,
   version: string,
   gitHead: string,
 ): boolean {
@@ -992,6 +1173,26 @@ export async function rollbackUpgrade(
     }
   }
 
+  // The units the forward transaction reconciled (#905). Restoring them is the
+  // same operation in the other direction: the *restored* CLI renders the
+  // previous version's templates, so running its own reconcile puts the
+  // pre-upgrade bytes back at every destination — and leaves anything the
+  // operator edited alone, because that drift is protected on both legs.
+  //
+  // Ordered before the restarts below, exactly as the forward leg is, and
+  // best-effort: a rollback that restored three surfaces must not fail because
+  // a unit file could not be rewritten. The failure is collected and reported
+  // with the rest.
+  if (installTouched) {
+    const restoreUnits = await deps.run("omp-conductor", ["reconcile-units", "--yes"]);
+    const summary = (restoreUnits.stdout.trim() || restoreUnits.stderr.trim()).split("\n").pop() ?? "";
+    if (restoreUnits.code === 0) {
+      deps.log(`rollback: ${summary.length === 0 ? "host units restored" : summary}`);
+    } else {
+      failures.push(`host units not restored: ${summary}`);
+    }
+  }
+
   if (herdrReloadStarted) {
     await restore("restart herdr-fleet.service", "systemctl", ["restart", HERDR_UNIT]);
   }
@@ -1053,7 +1254,16 @@ function logHostRuntimeDrift(deps: UpgradeDeps): void {
   if (plan.drift.length === 0) return;
   deps.log("host runtime:");
   for (const path of plan.drift) deps.log(`  ${path} differs from this version's render`);
-  deps.log("fix: run `omp-conductor setup host` from the fleet account to re-install the host units");
+  // Units are this transaction's own to reconcile (#905), and the reconcile
+  // verb is bounded to them. Anything else the render owns — the herdr
+  // pane-shell config, the herdr-conductor `config.env`, the worker identity —
+  // still needs `setup host`, so the advisory names the right tool for each
+  // rather than routing every drift into the flow that restarts (and kills)
+  // the caller's own pane (#834).
+  deps.log(
+    "fix: `omp-conductor reconcile-units` re-installs the host units; anything else above needs " +
+      "`omp-conductor setup host` from the fleet account",
+  );
 }
 
 export async function upgradeConductor(
@@ -1069,14 +1279,29 @@ export async function upgradeConductor(
     throw new Error("run omp-conductor upgrade from a shell outside the target Herdr session");
   }
 
-  const requested = options.version === undefined ? `${PACKAGE}@latest` : `${PACKAGE}@${options.version}`;
   // Host-wide by default (#389): one daemon serves every configured project,
   // so an upgrade that restarts it drains them all and refreshes every brief.
   const scope = resolveScope(deps, "upgrade", options.project);
 
-  const release = parseRegistry(
-    (await mustRun(deps, "npm", ["view", requested, "version", "gitHead", "--json"])).stdout,
-  );
+  // Published semver, or an exact source/build identity whose checks have
+  // already passed (#908). Everything below reads the same pair either way.
+  const identity = await resolveIdentity(deps, options);
+  const release = { version: identity.version, gitHead: identity.gitHead };
+  if (identity.bootstrap) {
+    // The bootstrap's evidence lands in the journal before the first surface
+    // moves, so an interrupted bootstrap leaves a record of what was verified
+    // rather than an unexplained half-install.
+    journal({
+      kind: "request",
+      ok: true,
+      version: release.version,
+      gitHead: release.gitHead,
+      phase: "bootstrap",
+      detail: `source identity from ${options.bootstrap?.source ?? "(source)"}`,
+      checks: identity.checks,
+      unit: deps.env["OMP_CONDUCTOR_UNIT"],
+    });
+  }
   if (detached) {
     // The durable request: written before anything can pause, so a unit that
     // dies after this line leaves a journal the returning process can act on
@@ -1096,6 +1321,18 @@ export async function upgradeConductor(
     ...deps.brief(selector),
   }));
   const installNeeded = !surfacesCurrent(surfaces, release.version, release.gitHead);
+  // The host-unit baseline, read while the OLD package is still the one
+  // rendering (#905). A destination already differing from the old render was
+  // edited outside conductor, so the reconcile after the install must not
+  // overwrite it; `undefined` means the baseline could not be established at
+  // all, and the reconcile is skipped rather than guessing.
+  const preInstallDrift = ((): string[] | undefined => {
+    try {
+      return [...deps.hostRuntime().drift];
+    } catch {
+      return undefined;
+    }
+  })();
   if (!installNeeded && briefs.every((b) => b.current)) {
     if (detached) {
       journal({
@@ -1209,10 +1446,10 @@ export async function upgradeConductor(
     if (installNeeded) {
       installTouched = true;
       deps.log(`install 1/3: Bun-global omp-conductor CLI → ${release.version}`);
-      await mustRun(deps, "bun", ["add", "-g", `${PACKAGE}@${release.version}`]);
+      await mustRun(deps, "bun", ["add", "-g", identity.packageSpec]);
       journal({ kind: "phase", phase: "install", surface: "cli", ok: true, version: release.version, gitHead: release.gitHead });
       deps.log(`install 2/3: omp plugin omp-conductor → ${release.version}`);
-      await mustRun(deps, "omp", ["plugin", "install", `${PACKAGE}@${release.version}`]);
+      await mustRun(deps, "omp", ["plugin", "install", identity.packageSpec]);
       journal({ kind: "phase", phase: "install", surface: "omp", ok: true, version: release.version, gitHead: release.gitHead });
       if (surfaces.herdrSource?.startsWith("local:")) {
         await mustRun(deps, "herdr", ["plugin", "unlink", HERDR_PLUGIN]);
@@ -1236,6 +1473,56 @@ export async function upgradeConductor(
     await upgradeBriefs(deps, briefs);
     journal({ kind: "phase", phase: "brief", surface: "brief", ok: true, version: release.version });
 
+    // #905: the templates this release re-rendered. The render is CODE, so
+    // this process — which loaded the previous version before replacing it —
+    // cannot see the new one: the reconcile runs as a fresh child of the
+    // just-installed CLI, which is also why it is spawned rather than called.
+    // (Not an escalation of conductor itself: the child escalates only its own
+    // bounded `install`/`daemon-reload` steps, which is exactly the boundary
+    // `privileged.ts` draws.)
+    //
+    // It lands here, before the restarts below, so the daemon and the herdr
+    // session come up reading the units this release actually ships — and
+    // inside the same pause/drain window, so nothing is admitted against a
+    // half-reconciled host.
+    {
+      // No baseline means no *refresh*: drift the operator made cannot be told
+      // from drift the upgrade made, so nothing is overwritten. It does not
+      // mean no *retirement* (#895) — a unit this release stopped shipping is
+      // not a comparison against any render, and skipping the whole child
+      // there left an affected host mounting an obsolete bind after every
+      // upgrade, forever. So the child always runs; only its refresh half is
+      // gated.
+      const refreshable = preInstallDrift !== undefined;
+      if (!refreshable) {
+        deps.log(
+          "host units: refresh skipped — this version's host state could not be read before the install, " +
+            "so drift the operator made cannot be told from drift the upgrade made. Retirement still runs; " +
+            "run `omp-conductor reconcile-units --dry-run` to see what differs.",
+        );
+      }
+      const reconcile = await deps.run("omp-conductor", [
+        "reconcile-units",
+        "--yes",
+        ...(refreshable ? [] : ["--no-refresh"]),
+        // Destinations that already differed from the OLD render are the
+        // operator's own edits, not this upgrade's doing: named here so the
+        // child leaves them alone and reports them.
+        ...(preInstallDrift ?? []).flatMap((path) => ["--protect", path]),
+      ]);
+      const summary = (reconcile.stdout.trim() || reconcile.stderr.trim()).split("\n").pop() ?? "";
+      if (reconcile.code === 0) {
+        deps.log(summary.length === 0 ? "host units: reconciled" : summary);
+        journal({ kind: "phase", phase: "reconcile", surface: "units", ok: true, version: release.version, detail: summary });
+      } else {
+        // A failed reconcile is a drifted host, not a failed upgrade: the
+        // packages are installed and verifiable, and the units are exactly as
+        // they were. Say so precisely instead of rolling three surfaces back.
+        deps.log(`host units: reconcile did not complete — ${summary}`);
+        journal({ kind: "phase", phase: "reconcile", surface: "units", ok: false, version: release.version, detail: summary });
+      }
+    }
+
     if (initial.herdr === "active") {
       herdrReloadStarted = true;
       deps.log("reload: restarting herdr-fleet.service and recovering the orchestrator pane");

package/src/verbs/actions.ts

@@ -321,6 +321,46 @@ export function githubVerbActions(
       : { ok: true, sha };
   };
 
+  /**
+   * Resolve a caller-pinned release commit and prove it belongs on the released
+   * branch (#695).
+   *
+   * Two questions, both fail-closed. `rev-parse <sha>^{commit}` answers "does
+   * this commit exist in the released repository at all" — an abbreviation is
+   * expanded here, so what the tag receives is always a full id. `merge-base
+   * --is-ancestor` answers the one that matters: a tag pointing at a commit
+   * that is not on the released branch is a release of code nobody merged, and
+   * that is the failure a decorative `sha` argument would create. The ancestor
+   * check accepts the branch tip itself, which is the ordinary case.
+   */
+  const pinnedReleaseCommit = async (
+    mirror: string,
+    repo: RepoTarget,
+    sha: string,
+  ): Promise<CommitOutcome> => {
+    const resolved = await readCommit(mirror, ["rev-parse", `${sha}^{commit}`], `pinned commit ${sha}`);
+    if (!resolved.ok) {
+      return {
+        ok: false,
+        stderr:
+          `refusing release: ${sha} is not a commit in ${repo.name}. ` +
+          `Pass a commit that exists on ${repo.defaultBranch}.\n${resolved.stderr}`,
+      };
+    }
+    const branchRef = `refs/remotes/origin/${repo.defaultBranch}`;
+    const reachable = await git(mirror, ["merge-base", "--is-ancestor", resolved.sha, branchRef]);
+    if (!reachable.result.ok) {
+      return {
+        ok: false,
+        stderr:
+          `refusing release: ${resolved.sha} is not reachable from ${repo.name}'s ${repo.defaultBranch}. ` +
+          "A tag must never point at a commit that is not on the released branch — check the sha, or " +
+          "wait for the commit to land.",
+      };
+    }
+    return resolved;
+  };
+
   const releaseTargetMoved = (repo: RepoTarget, target: string, live: string): { ok: false; stderr: string } => ({
     ok: false,
     stderr:
@@ -636,6 +676,38 @@ export function githubVerbActions(
       };
     },
 
+    // Closing a rejected PR is the one destructive half of an adjudication's
+    // disposition (#876), and it is REST rather than `gh pr close` for the same
+    // reason `updatePrBranch` is: a selective GraphQL outage must not leave a
+    // rejected PR open, permanently blocking the issue's reimplementation.
+    closePr: async (prUrl, comment) => {
+      const parts = prUrlParts(prUrl);
+      if (parts === undefined) {
+        return { ok: false, stderr: `could not parse ${prUrl} as a pull request URL` };
+      }
+      // The comment first, and only then the close: a closed PR still shows its
+      // comments, but a close that succeeds while the explanation fails leaves a
+      // PR nobody can account for. Ordering the durable explanation before the
+      // irreversible act is the same rule the merge path follows.
+      const said = await gh([
+        "api",
+        "--method",
+        "POST",
+        `repos/${parts.owner}/${parts.repo}/issues/${parts.number}/comments`,
+        "-f",
+        `body=${comment}`,
+      ]);
+      if (!said.ok) return { ok: false, stderr: said.stderr };
+      return gh([
+        "api",
+        "--method",
+        "PATCH",
+        `repos/${parts.owner}/${parts.repo}/pulls/${parts.number}`,
+        "-f",
+        "state=closed",
+      ]);
+    },
+
     updatePr: async (prUrl, fields) => {
       const argv = ["pr", "edit", prUrl];
       if (fields.title !== undefined) argv.push("--title", fields.title);
@@ -682,15 +754,31 @@ export function githubVerbActions(
       if (!prepared.ok) return prepared;
       const mirror = prepared.path;
       if (execution.shape === "git-tag") {
-        const target = await readCommit(
-          mirror,
-          ["rev-parse", `refs/remotes/origin/${execution.repo.defaultBranch}^{commit}`],
-          `refreshed ${execution.repo.defaultBranch}`,
-        );
+        // A pinned commit (#695) is the whole point of the argument: the tag
+        // points where the caller says, so the branch moving afterwards — which
+        // is what reaching a quiet release window requires — cannot strand it.
+        // The moved-branch guards below exist to catch main shifting under an
+        // implicit "current main" target; for an explicit commit they would
+        // refuse exactly the case the pin was asked for, so they are skipped
+        // and the reachability check is the invariant instead.
+        const pinned =
+          execution.sha === undefined
+            ? undefined
+            : await pinnedReleaseCommit(mirror, execution.repo, execution.sha);
+        if (pinned !== undefined && !pinned.ok) return pinned;
+        const target =
+          pinned ??
+          (await readCommit(
+            mirror,
+            ["rev-parse", `refs/remotes/origin/${execution.repo.defaultBranch}^{commit}`],
+            `refreshed ${execution.repo.defaultBranch}`,
+          ));
         if (!target.ok) return target;
-        const liveBefore = await liveDefaultHead(mirror, execution.repo);
-        if (!liveBefore.ok) return liveBefore;
-        if (target.sha !== liveBefore.sha) return releaseTargetMoved(execution.repo, target.sha, liveBefore.sha);
+        if (pinned === undefined) {
+          const liveBefore = await liveDefaultHead(mirror, execution.repo);
+          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;
@@ -736,7 +824,12 @@ export function githubVerbActions(
         ]);
         if (!tagged.result.ok) return failed(tagged.result, tagged.argv);
 
-        const liveAfter = await liveDefaultHead(mirror, execution.repo);
+        // Only meaningful for an implicit target: a pinned tag is *expected* to
+        // sit behind a branch that has moved on.
+        const liveAfter =
+          pinned === undefined
+            ? await liveDefaultHead(mirror, execution.repo)
+            : ({ ok: true, sha: target.sha } as const);
         if (!liveAfter.ok || liveAfter.sha !== target.sha) {
           const rollback = previousSha !== undefined
             ? await git(mirror, [
@@ -774,6 +867,27 @@ export function githubVerbActions(
       const target = await readCommit(mirror, ["rev-parse", `refs/tags/${tag}^{commit}`], `tag ${tag}`);
       if (!target.ok) return target;
       let tagSha = target.sha;
+      // A pinned push publishes the tag EXACTLY as it was cut (#695). Without
+      // this the retarget-to-live-main path below would quietly move a pinned
+      // tag onto whatever merged since — which is the same stranding, inverted:
+      // the caller would get a published tag pointing somewhere it never asked
+      // for. The pin is re-proven against the branch and against the local tag,
+      // so a mismatch is a refusal rather than a silent move.
+      const pinnedPush =
+        execution.sha === undefined
+          ? undefined
+          : await pinnedReleaseCommit(mirror, execution.repo, execution.sha);
+      if (pinnedPush !== undefined) {
+        if (!pinnedPush.ok) return pinnedPush;
+        if (pinnedPush.sha !== tagSha) {
+          return {
+            ok: false,
+            stderr:
+              `refusing release: ${tag} is at ${tagSha} locally, and you asked to publish it at ` +
+              `${pinnedPush.sha}. A published tag is never force-moved; cut the tag you mean to push.`,
+          };
+        }
+      }
       const live = await liveDefaultHead(mirror, execution.repo);
       if (!live.ok) return live;
 
@@ -795,7 +909,7 @@ export function githubVerbActions(
       if (!versionReady.ok) return versionReady;
 
       let oldSha: string | undefined;
-      if (tagSha !== live.sha) {
+      if (pinnedPush === undefined && tagSha !== live.sha) {
         const fresh = await readCommit(
           mirror,
           ["rev-parse", `refs/remotes/origin/${execution.repo.defaultBranch}^{commit}`],