@git.zone/cli 4.0.0 → 6.0.0

package/ts/mod_release/index.ts

@@ -9,25 +9,54 @@ import {
   readPendingChangelog,
 } from "../helpers.changelog.js";
 import {
-  formatTsdockerMinimumVersion,
-  getDeclaredTsdockerRange,
-  getTsdockerMinimumVersion,
   resolveReleaseWorkflow,
-  supportsTsdockerMinimumVersion,
+  resolveReleaseResumeConfiguration,
+  type IResolvedReleaseResumeConfiguration,
   type IResolvedReleaseWorkflow,
 } from "../helpers.workflow.js";
 import * as commitHelpers from "../mod_commit/mod.helpers.js";
-import { hasInstalledProjectTsdockerBinary } from "../helpers.tsdocker.js";
+import {
+  inspectReleaseBranch,
+  integrateReleaseBranch,
+  prepareReleaseIntegration,
+  revalidatePreparedReleaseBranch,
+  revalidateReleasePublicationState,
+  releaseGitEnv,
+  resolveReleaseMergeFlag,
+  type IReleaseBranchContext,
+} from "./helpers.releasebranch.js";
+import {
+  ReleaseJournalStore,
+  createInitialTargetStatus,
+  finalizeJournalCompletion,
+  normalizeReleaseGitRemoteName,
+  normalizeReleaseVersion,
+  resolveGitCommonDirectory,
+  type IReleaseArtifact,
+  type IReleaseJournal,
+} from "./classes.releasejournal.js";
+import {
+  assertNoLegacyNpmPublisher,
+  assertPnpmReleaseCapability,
+  hashReleaseDestination,
+  normalizeNpmRegistryUrl,
+  packNpmArtifact,
+  verifyStoredNpmArtifact,
+} from "./helpers.npmartifact.js";
+import { executeReleasePublication } from "./helpers.releasepublication.js";
 
-type TTargetStatus = "success" | "already-published" | "skipped" | "failed";
+export { buildReleaseGitPushArgs } from "./helpers.releasepublication.js";
 
-interface ITargetResult {
-  target: string;
-  status: TTargetStatus;
-  message?: string;
-}
+export const run = async (argvArg: any): Promise<void> => {
+  try {
+    await runInternal(argvArg);
+  } catch (error) {
+    logger.log("error", error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+};
 
-export const run = async (argvArg: any) => {
+const runInternal = async (argvArg: any): Promise<void> => {
   const mode = await getCliMode(argvArg);
   const subcommand = argvArg._?.[1];
 
@@ -36,47 +65,88 @@ export const run = async (argvArg: any) => {
     return;
   }
 
+  if (subcommand === "inspect") {
+    await runReleaseInspect(argvArg, mode);
+    return;
+  }
+  if (subcommand === "resume") {
+    await runReleaseResume(argvArg, mode);
+    return;
+  }
+  if (subcommand !== undefined) {
+    throw new Error(`Unknown release subcommand: ${subcommand}`);
+  }
+
   if (mode.json) {
     printJson({
       ok: false,
-      error: "JSON output is not supported for mutating release workflows yet. Use `gitzone release --plan` for a human-readable plan.",
+      error:
+        "JSON output is not supported for mutating release workflows yet. Use `gitzone release --plan` for a human-readable plan.",
     });
     return;
   }
 
+  const smartshellInstance = new plugins.smartshell.Smartshell({
+    executor: "bash",
+    sourceFilePaths: [],
+  });
+  const mergeRequested = resolveReleaseMergeFlag(argvArg);
   const workflow = await resolveReleaseWorkflow(argvArg);
-  printReleasePlan(workflow);
+  assertReleaseConfiguration(workflow);
+  let branchContext: IReleaseBranchContext = await inspectReleaseBranch({
+    smartshell: smartshellInstance,
+    cwd: paths.cwd,
+    gitRemote: workflow.gitRemote,
+    gitTargetActive: workflow.targets.includes("git"),
+    pushBranch: workflow.pushBranch,
+    pushTags: workflow.pushTags,
+    mergeRequested,
+    planMode: workflow.confirmation === "plan",
+  });
+  printReleasePlan(workflow, branchContext);
   if (workflow.confirmation === "plan") {
     return;
   }
 
-  const smartshellInstance = new plugins.smartshell.Smartshell({
-    executor: "bash",
-    sourceFilePaths: [],
-  });
+  await assertFreshReleaseCapabilities(
+    smartshellInstance,
+    workflow,
+    branchContext.sourceCwd,
+    branchContext.pushUrl,
+  );
 
   const pending = await readPendingChangelog(
-    plugins.path.join(paths.cwd, workflow.changelogFile),
+    plugins.path.join(branchContext.sourceCwd, workflow.changelogFile),
     workflow.changelogPendingSection,
   );
   if (pending.isEmpty && !argvArg["allow-empty"] && !argvArg.allowEmpty) {
-    logger.log("error", "No pending changelog entries. Nothing to release.");
-    process.exit(1);
+    throw new Error("No pending changelog entries. Nothing to release.");
   }
 
   const versionType = resolveVersionType(argvArg, pending.block);
-  const projectType = await commitHelpers.detectProjectType();
-  const currentVersion = await commitHelpers.readCurrentVersion(projectType);
-  const plannedVersion = commitHelpers.calculateNewVersion(currentVersion, versionType);
+  const projectType = await commitHelpers.detectProjectType(
+    branchContext.sourceCwd,
+  );
+  const currentVersion = await commitHelpers.readCurrentVersion(
+    projectType,
+    branchContext.sourceCwd,
+  );
+  const plannedVersion = commitHelpers.calculateNewVersion(
+    currentVersion,
+    versionType,
+  );
 
   if (workflow.confirmation === "prompt") {
     if (!mode.interactive) {
-      throw new Error("Release confirmation requires an interactive terminal. Use `-y` or set release.confirmation to `auto`.");
+      throw new Error(
+        "Release confirmation requires an interactive terminal. Use `-y` or set release.confirmation to `auto`.",
+      );
     }
-    const confirmed = await plugins.smartinteract.SmartInteract.getCliConfirmation(
-      `Release v${plannedVersion} (${versionType}) now?`,
-      true,
-    );
+    const confirmed =
+      await plugins.smartinteract.SmartInteract.getCliConfirmation(
+        `Release v${plannedVersion} (${versionType}) now?`,
+        true,
+      );
     if (!confirmed) {
       logger.log("info", "Release cancelled.");
       return;
@@ -84,44 +154,513 @@ export const run = async (argvArg: any) => {
   }
 
   let newVersion = plannedVersion;
-  const gitResults: ITargetResult[] = [];
-  const npmResults: ITargetResult[] = [];
-  const dockerResults: ITargetResult[] = [];
-
-  if (workflow.requireCleanTree) {
-    await verifyCleanTree(smartshellInstance, "Working tree is not clean. Commit or stash changes before releasing.");
-  }
+  branchContext = await prepareReleaseIntegration(
+    smartshellInstance,
+    branchContext,
+  );
   if (workflow.runTests) {
-    await runCommandStep(smartshellInstance, "Running tests", workflow.testCommand);
+    await runCommandStep(
+      smartshellInstance,
+      branchContext.sourceCwd,
+      "Running tests",
+      workflow.testCommand,
+    );
   }
 
-  newVersion = await runVersionStep(projectType, versionType);
-  await runChangelogStep(workflow, newVersion);
-  await runReleaseCommitStep(smartshellInstance, newVersion);
-  await runTagStep(smartshellInstance, newVersion);
+  let releaseCwd = branchContext.sourceCwd;
+  let releasePushUrl = branchContext.pushUrl;
+  let expectedRemoteMainOid = branchContext.remoteMainOid;
+  if (branchContext.sourceBranch === "main") {
+    await revalidatePreparedReleaseBranch(smartshellInstance, branchContext);
+  } else {
+    const integration = await integrateReleaseBranch(
+      smartshellInstance,
+      branchContext,
+    );
+    releaseCwd = integration.releaseCwd;
+    releasePushUrl = integration.pushUrl;
+    expectedRemoteMainOid = integration.expectedRemoteMainOid;
+  }
+
+  newVersion = await runVersionStep(projectType, versionType, releaseCwd);
+  await runChangelogStep(workflow, newVersion, releaseCwd);
+  const releaseCommitOid = await runReleaseCommitStep(
+    smartshellInstance,
+    newVersion,
+    releaseCwd,
+  );
+  await runTagStep(
+    smartshellInstance,
+    newVersion,
+    releaseCommitOid,
+    releaseCwd,
+  );
+  const releaseRefs = await captureReleaseRefs(
+    smartshellInstance,
+    releaseCwd,
+    newVersion,
+    releaseCommitOid,
+  );
 
   if (workflow.runBuild) {
-    await runCommandStep(smartshellInstance, "Running release build", workflow.buildCommand);
-    await verifyCleanTree(smartshellInstance, "Build produced uncommitted changes. Aborting release.");
+    await runCommandStep(
+      smartshellInstance,
+      releaseCwd,
+      "Running release build",
+      workflow.buildCommand,
+    );
+    await verifyCleanTree(
+      smartshellInstance,
+      releaseCwd,
+      "Build produced uncommitted changes. Aborting release.",
+    );
   }
 
-  if (workflow.targets.includes("git")) {
-    gitResults.push(...(await runGitTarget(smartshellInstance, workflow)));
+  const ensurePublicationState = async (
+    expectedRemoteMainOidArg = expectedRemoteMainOid,
+  ): Promise<void> => {
+    await verifyReleaseRefs(
+      smartshellInstance,
+      releaseCwd,
+      newVersion,
+      releaseRefs,
+    );
+    await revalidateReleasePublicationState(
+      smartshellInstance,
+      branchContext,
+      releaseRefs.mainOid,
+      expectedRemoteMainOidArg,
+    );
+  };
+
+  await ensurePublicationState();
+  const journalContext = await createReleaseJournal({
+    smartshell: smartshellInstance,
+    workflow,
+    releaseCwd,
+    releasePushUrl,
+    expectedRemoteMainOid,
+    version: newVersion,
+    refs: releaseRefs,
+    ensurePublicationState,
+  });
+  const finalJournal = await executeReleasePublication({
+    smartshell: smartshellInstance,
+    cwd: releaseCwd,
+    store: journalContext.store,
+    journal: journalContext.journal,
+    pushUrl: releasePushUrl,
+    ensurePublicationState,
+  });
+  printReleaseJournalSummary(finalJournal);
+};
+
+const assertFreshReleaseCapabilities = async (
+  smartshellArg: plugins.smartshell.Smartshell,
+  workflowArg: IResolvedReleaseWorkflow,
+  cwdArg: string,
+  pushUrlArg?: string,
+): Promise<void> => {
+  if (workflowArg.targets.includes("docker")) {
+    throw new Error(
+      "Journaled Docker publication requires the planned structured tSDocker digest capability. Disable the Docker target until that upstream release is installed.",
+    );
   }
-  if (workflow.targets.includes("npm")) {
-    npmResults.push(...(await runNpmTarget(smartshellInstance, workflow)));
+  if (workflowArg.targets.includes("git") && !pushUrlArg) {
+    throw new Error("The Git release target requires one resolved push destination.");
   }
-  if (workflow.targets.includes("docker")) {
-    dockerResults.push(...(await runDockerTarget(smartshellInstance, workflow)));
+  if (
+    workflowArg.targets.includes("git") ||
+    workflowArg.targets.includes("npm")
+  ) {
+    await assertNoLegacyNpmPublisher(cwdArg);
+  }
+  if (workflowArg.targets.includes("npm")) {
+    await assertPnpmReleaseCapability(smartshellArg, cwdArg);
+  }
+};
+
+const assertReleaseConfiguration = (
+  workflowArg: IResolvedReleaseWorkflow,
+): void => {
+  if (workflowArg.targets.includes("git")) {
+    normalizeReleaseGitRemoteName(workflowArg.gitRemote);
+  }
+  if (!workflowArg.targets.includes("npm")) {
+    return;
+  }
+  if (workflowArg.npmRegistries.length === 0) {
+    throw new Error("The npm release target requires at least one registry.");
+  }
+  if (workflowArg.npmAccessLevel !== "public") {
+    throw new Error(
+      "Journaled npm publication currently requires public access so every destination can be verified anonymously.",
+    );
+  }
+  if (
+    workflowArg.npmAlreadyPublished !== "success" &&
+    workflowArg.npmAlreadyPublished !== "error"
+  ) {
+    throw new Error(
+      "release.targets.npm.alreadyPublished must be success or error.",
+    );
+  }
+  const canonicalRegistries = workflowArg.npmRegistries.map(
+    normalizeNpmRegistryUrl,
+  );
+  if (
+    new Set(canonicalRegistries).size !== canonicalRegistries.length ||
+    canonicalRegistries.some(
+      (registryArg, indexArg) => registryArg !== workflowArg.npmRegistries[indexArg],
+    )
+  ) {
+    throw new Error(
+      "npm release registries must be unique canonical credential-free http(s) URLs.",
+    );
+  }
+};
+
+interface ICreateReleaseJournalOptions {
+  smartshell: plugins.smartshell.Smartshell;
+  workflow: IResolvedReleaseWorkflow;
+  releaseCwd: string;
+  releasePushUrl?: string;
+  expectedRemoteMainOid?: string;
+  version: string;
+  refs: IReleaseRefs;
+  ensurePublicationState: (expectedRemoteMainOidArg?: string) => Promise<void>;
+}
+
+const createReleaseJournal = async (
+  optionsArg: ICreateReleaseJournalOptions,
+): Promise<{ store: ReleaseJournalStore; journal: IReleaseJournal }> => {
+  const gitCommonDirectory = await resolveGitCommonDirectory(
+    optionsArg.smartshell,
+    optionsArg.releaseCwd,
+  );
+  const store = new ReleaseJournalStore(gitCommonDirectory);
+  const releaseDirectory = store.getReleaseDirectory(optionsArg.version);
+  const releaseDirectoryExists = await plugins.fs
+    .lstat(releaseDirectory)
+    .then(() => true)
+    .catch((error: NodeJS.ErrnoException) => {
+      if (error.code === "ENOENT") return false;
+      throw error;
+    });
+  if (releaseDirectoryExists) {
+    throw new Error(
+      `Release journal v${optionsArg.version} already exists. Inspect or resume it instead of regenerating artifacts.`,
+    );
+  }
+
+  let temporaryDirectory = await store.createTemporaryDirectory(optionsArg.version);
+  try {
+    let artifact: IReleaseArtifact | null = null;
+    if (optionsArg.workflow.targets.includes("npm")) {
+      artifact = await packNpmArtifact(
+        optionsArg.smartshell,
+        optionsArg.releaseCwd,
+        temporaryDirectory,
+        optionsArg.version,
+      );
+      await verifyCleanTree(
+        optionsArg.smartshell,
+        optionsArg.releaseCwd,
+        "npm pack lifecycle scripts changed the release worktree. Aborting release.",
+      );
+      await optionsArg.ensurePublicationState();
+    }
+
+    const gitEnabled = optionsArg.workflow.targets.includes("git");
+    if (
+      gitEnabled &&
+      (!optionsArg.releasePushUrl || !optionsArg.expectedRemoteMainOid)
+    ) {
+      throw new Error("Git release destination state is incomplete.");
+    }
+    const now = new Date().toISOString();
+    const gitStatus = createInitialTargetStatus(gitEnabled);
+    const journal = finalizeJournalCompletion({
+      kind: "gitzone-release-journal",
+      schemaVersion: 1,
+      revision: 1,
+      release: {
+        version: optionsArg.version,
+        tag: `v${optionsArg.version}`,
+        mainOid: optionsArg.refs.mainOid,
+        tagOid: optionsArg.refs.tagOid,
+      },
+      artifact,
+      git: {
+        state: gitStatus.state,
+        attempts: gitStatus.attempts,
+        attempt: gitStatus.attempt,
+        error: gitStatus.error,
+        remote: gitEnabled ? optionsArg.workflow.gitRemote : null,
+        destinationHash: gitEnabled
+          ? hashReleaseDestination(optionsArg.releasePushUrl as string)
+          : null,
+        expectedRemoteMainOid: gitEnabled
+          ? (optionsArg.expectedRemoteMainOid as string)
+          : null,
+      },
+      npm: {
+        access: "public",
+        tag: "latest",
+        alreadyPublished: optionsArg.workflow.targets.includes("npm")
+          ? optionsArg.workflow.npmAlreadyPublished
+          : "success",
+        registries: optionsArg.workflow.targets.includes("npm")
+          ? optionsArg.workflow.npmRegistries.map((registryArg) => {
+              const status = createInitialTargetStatus(true);
+              return {
+                state: status.state,
+                attempts: status.attempts,
+                attempt: status.attempt,
+                error: status.error,
+                registry: registryArg,
+              };
+            })
+          : [],
+      },
+      createdAt: now,
+      updatedAt: now,
+      completedAt: null,
+    }, now);
+    const installed = await store.installPrepared(temporaryDirectory, journal);
+    temporaryDirectory = "";
+    return { store, journal: installed };
+  } finally {
+    if (temporaryDirectory) {
+      await plugins.fs.rm(temporaryDirectory, { recursive: true, force: true });
+    }
+  }
+};
+
+const runReleaseInspect = async (
+  argvArg: any,
+  modeArg: ICliMode,
+): Promise<void> => {
+  if (argvArg._?.length > 3) {
+    throw new Error("Usage: gitzone release inspect [version] [--json]");
+  }
+  const smartshellInstance = new plugins.smartshell.Smartshell({
+    executor: "bash",
+    sourceFilePaths: [],
+  });
+  const store = new ReleaseJournalStore(
+    await resolveGitCommonDirectory(smartshellInstance, paths.cwd),
+  );
+  const requestedVersion = argvArg._?.[2];
+  const journals = requestedVersion
+    ? [await store.read(normalizeReleaseVersion(requestedVersion))]
+    : await store.list();
+  if (modeArg.json) {
+    printJson({ ok: true, journals });
+    return;
+  }
+  if (journals.length === 0) {
+    console.log("No release journals found.");
+    return;
+  }
+  for (const journal of journals) {
+    printReleaseJournalSummary(journal);
+  }
+};
+
+const assertResumeArguments = (argvArg: any): void => {
+  const forbiddenKeys = [
+    "allow-empty",
+    "allowEmpty",
+    "b",
+    "build",
+    "docker",
+    "git",
+    "major",
+    "merge",
+    "minor",
+    "npm",
+    "p",
+    "patch",
+    "plan",
+    "publish",
+    "push",
+    "t",
+    "target",
+    "targets",
+    "test",
+  ];
+  if (
+    forbiddenKeys.some((keyArg) =>
+      Object.prototype.hasOwnProperty.call(argvArg, keyArg),
+    )
+  ) {
+    throw new Error(
+      "release resume rejects fresh-release target, integration, build, test, and version overrides.",
+    );
+  }
+  if (argvArg._?.length !== 3) {
+    throw new Error(
+      "Usage: gitzone release resume <version> [-y] [--recover-attempt=<id>]",
+    );
+  }
+};
+
+const runReleaseResume = async (
+  argvArg: any,
+  modeArg: ICliMode,
+): Promise<void> => {
+  assertResumeArguments(argvArg);
+  if (modeArg.json) {
+    throw new Error("JSON output is read-only. Use release inspect --json.");
+  }
+  const recoveryAttemptId =
+    argvArg["recover-attempt"] || argvArg.recoverAttempt;
+  if (
+    recoveryAttemptId !== undefined &&
+    (typeof recoveryAttemptId !== "string" ||
+      !/^[0-9a-f]{32}$/.test(recoveryAttemptId))
+  ) {
+    throw new Error("--recover-attempt requires one exact 32-character owner ID.");
+  }
+  const version = normalizeReleaseVersion(argvArg._[2]);
+  const smartshellInstance = new plugins.smartshell.Smartshell({
+    executor: "bash",
+    sourceFilePaths: [],
+  });
+  const store = new ReleaseJournalStore(
+    await resolveGitCommonDirectory(smartshellInstance, paths.cwd),
+  );
+  const journal = await store.read(version);
+  const gitEnabled = journal.git.state !== "skipped";
+  const resumeConfiguration = await resolveReleaseResumeConfiguration({
+    git: gitEnabled,
+    npm: journal.npm.registries.length > 0,
+  });
+  await assertResumeConfiguration(resumeConfiguration, journal, paths.cwd);
+  if (journal.artifact) {
+    await assertPnpmReleaseCapability(smartshellInstance, paths.cwd);
+    await assertNoLegacyNpmPublisher(paths.cwd);
+    await verifyStoredNpmArtifact(store.getArtifactPath(version), journal.artifact);
   }
 
-  printReleaseSummary(newVersion, gitResults, npmResults, dockerResults);
-  if ([...gitResults, ...npmResults, ...dockerResults].some((result) => result.status === "failed")) {
-    process.exit(1);
+  const branchContext = await inspectReleaseBranch({
+    smartshell: smartshellInstance,
+    cwd: paths.cwd,
+    gitRemote: journal.git.remote || resumeConfiguration.gitRemote,
+    gitTargetActive: gitEnabled,
+    pushBranch: true,
+    pushTags: true,
+    mergeRequested: false,
+    planMode: false,
+  });
+  if (branchContext.sourceOid !== journal.release.mainOid) {
+    throw new Error("Resume must run from the journaled release commit on main.");
+  }
+  const refs = await captureReleaseRefs(
+    smartshellInstance,
+    paths.cwd,
+    version,
+    journal.release.mainOid,
+  );
+  if (refs.tagOid !== journal.release.tagOid) {
+    throw new Error("The local release tag no longer matches the journal.");
+  }
+  const pushUrl = gitEnabled ? branchContext.pushUrl : undefined;
+  if (
+    gitEnabled &&
+    (!pushUrl || hashReleaseDestination(pushUrl) !== journal.git.destinationHash)
+  ) {
+    throw new Error("The Git push destination changed after journal creation.");
   }
+
+  if (!modeArg.yes) {
+    if (!modeArg.interactive) {
+      throw new Error("Release resume requires an interactive terminal or -y.");
+    }
+    const confirmed =
+      await plugins.smartinteract.SmartInteract.getCliConfirmation(
+        `Resume release v${version} now?`,
+        true,
+      );
+    if (!confirmed) {
+      logger.log("info", "Release resume cancelled.");
+      return;
+    }
+  }
+
+  const ensurePublicationState = async (
+    expectedRemoteMainOidArg?: string,
+  ): Promise<void> => {
+    await verifyReleaseRefs(smartshellInstance, paths.cwd, version, refs);
+    await revalidateReleasePublicationState(
+      smartshellInstance,
+      branchContext,
+      journal.release.mainOid,
+      expectedRemoteMainOidArg,
+    );
+  };
+  const finalJournal = await executeReleasePublication({
+    smartshell: smartshellInstance,
+    cwd: paths.cwd,
+    store,
+    journal,
+    pushUrl,
+    recoveryAttemptId,
+    ensurePublicationState,
+  });
+  printReleaseJournalSummary(finalJournal);
 };
 
-function resolveVersionType(argvArg: any, pendingBlock: string): commitHelpers.VersionType {
+const assertResumeConfiguration = async (
+  workflowArg: IResolvedReleaseResumeConfiguration,
+  journalArg: IReleaseJournal,
+  cwdArg: string,
+): Promise<void> => {
+  if (
+    journalArg.git.state !== "skipped" &&
+    workflowArg.gitRemote !== journalArg.git.remote
+  ) {
+    throw new Error("Current Git release remote does not match the journal.");
+  }
+  const currentRegistries = workflowArg.npmRegistries.map(
+    normalizeNpmRegistryUrl,
+  );
+  if (
+    journalArg.npm.registries.length > 0 &&
+    (JSON.stringify(currentRegistries) !==
+      JSON.stringify(
+        journalArg.npm.registries.map((registryArg) => registryArg.registry),
+      ) ||
+      workflowArg.npmAccessLevel !== journalArg.npm.access ||
+      workflowArg.npmAlreadyPublished !== journalArg.npm.alreadyPublished)
+  ) {
+    throw new Error("Current npm release configuration does not match the journal.");
+  }
+  if (journalArg.git.state !== "skipped" || journalArg.artifact) {
+    await assertNoLegacyNpmPublisher(cwdArg);
+  }
+};
+
+const printReleaseJournalSummary = (journalArg: IReleaseJournal): void => {
+  console.log("");
+  console.log(`Release v${journalArg.release.version}`);
+  console.log(`journal revision: ${journalArg.revision}`);
+  console.log(
+    `artifact: ${journalArg.artifact ? `${journalArg.artifact.integrity} (${journalArg.artifact.sha256})` : "none"}`,
+  );
+  console.log(`git: ${journalArg.git.state}`);
+  for (const registry of journalArg.npm.registries) {
+    console.log(`npm ${registry.registry}: ${registry.state}`);
+  }
+  console.log(`completed: ${journalArg.completedAt || "no"}`);
+  console.log("");
+};
+
+function resolveVersionType(
+  argvArg: any,
+  pendingBlock: string,
+): commitHelpers.VersionType {
   if (argvArg.major) return "major";
   if (argvArg.minor) return "minor";
   if (argvArg.patch) return "patch";
@@ -130,51 +669,71 @@ function resolveVersionType(argvArg: any, pendingBlock: string): commitHelpers.V
 
 async function runCommandStep(
   smartshellInstance: plugins.smartshell.Smartshell,
+  cwdArg: string,
   label: string,
   command: string,
 ): Promise<void> {
   console.log(`\n${label}`);
-  const result = await smartshellInstance.exec(command);
+  const result = await smartshellInstance.exec(command, { cwd: cwdArg });
   if (result.exitCode !== 0) {
-    logger.log("error", `${label} failed. Aborting release.`);
-    process.exit(1);
+    throw new Error(`${label} failed. Aborting release.`);
   }
   logger.log("success", `${label} passed.`);
 }
 
 async function verifyCleanTree(
   smartshellInstance: plugins.smartshell.Smartshell,
+  cwdArg: string,
   errorMessage: string,
 ): Promise<void> {
-  const statusResult = await smartshellInstance.exec("git status --porcelain");
+  const statusResult = await smartshellInstance.execSpawn(
+    "git",
+    ["status", "--porcelain"],
+    {
+      cwd: cwdArg,
+      env: releaseGitEnv,
+      timeout: 60_000,
+      timeoutKillGraceMs: 5_000,
+    },
+  );
   if (statusResult.stdout.trim() !== "") {
-    logger.log("error", errorMessage);
-    console.log(statusResult.stdout);
-    process.exit(1);
+    throw new Error(errorMessage);
   }
 }
 
 async function runVersionStep(
   projectType: commitHelpers.ProjectType,
   versionType: commitHelpers.VersionType,
+  cwdArg: string,
 ): Promise<string> {
-  const currentVersion = await commitHelpers.readCurrentVersion(projectType);
-  const newVersion = commitHelpers.calculateNewVersion(currentVersion, versionType);
+  const currentVersion = await commitHelpers.readCurrentVersion(
+    projectType,
+    cwdArg,
+  );
+  const newVersion = commitHelpers.calculateNewVersion(
+    currentVersion,
+    versionType,
+  );
   logger.log("info", `Bumping version: ${currentVersion} -> ${newVersion}`);
 
-  const commitInfo = new plugins.commitinfo.CommitInfo(paths.cwd, versionType);
+  const commitInfo = new plugins.commitinfo.CommitInfo(cwdArg, versionType);
   await commitInfo.writeIntoPotentialDirs();
-  await commitHelpers.updateProjectVersionFiles(projectType, newVersion);
+  await commitHelpers.updateProjectVersionFiles(
+    projectType,
+    newVersion,
+    cwdArg,
+  );
   return newVersion;
 }
 
 async function runChangelogStep(
   workflow: IResolvedReleaseWorkflow,
   newVersion: string,
+  cwdArg: string,
 ): Promise<void> {
   const dateString = new Date().toISOString().slice(0, 10);
   await movePendingToVersion(
-    plugins.path.join(paths.cwd, workflow.changelogFile),
+    plugins.path.join(cwdArg, workflow.changelogFile),
     workflow.changelogPendingSection,
     workflow.changelogVersionHeading,
     newVersion,
@@ -185,149 +744,172 @@ async function runChangelogStep(
 async function runReleaseCommitStep(
   smartshellInstance: plugins.smartshell.Smartshell,
   newVersion: string,
-): Promise<void> {
-  await smartshellInstance.exec("git add -A");
-  const result = await smartshellInstance.exec(`git commit -m ${shellQuote(`v${newVersion}`)}`);
+  cwdArg: string,
+): Promise<string> {
+  const addResult = await smartshellInstance.execSpawn("git", ["add", "-A"], {
+    cwd: cwdArg,
+    env: releaseGitEnv,
+    timeout: 60_000,
+    timeoutKillGraceMs: 5_000,
+  });
+  if (addResult.exitCode !== 0) {
+    throw new Error("Staging release metadata failed.");
+  }
+  const result = await smartshellInstance.execSpawn(
+    "git",
+    ["commit", "-m", `v${newVersion}`],
+    {
+      cwd: cwdArg,
+      env: releaseGitEnv,
+      timeout: 60_000,
+      timeoutKillGraceMs: 5_000,
+    },
+  );
   if (result.exitCode !== 0) {
-    logger.log("error", "Release commit failed.");
-    process.exit(1);
+    throw new Error("Release commit failed.");
+  }
+  const branchResult = await smartshellInstance.execSpawn(
+    "git",
+    ["symbolic-ref", "--quiet", "HEAD"],
+    {
+      cwd: cwdArg,
+      env: releaseGitEnv,
+      silent: true,
+      timeout: 60_000,
+      timeoutKillGraceMs: 5_000,
+    },
+  );
+  if (
+    branchResult.exitCode !== 0 ||
+    branchResult.stdout.trim() !== "refs/heads/main"
+  ) {
+    throw new Error("The release commit was not created on main.");
+  }
+  const headOid = await resolveGitObjectOid(
+    smartshellInstance,
+    cwdArg,
+    "HEAD^{commit}",
+  );
+  const mainOid = await resolveGitObjectOid(
+    smartshellInstance,
+    cwdArg,
+    "refs/heads/main^{commit}",
+  );
+  if (headOid !== mainOid) {
+    throw new Error("HEAD and main diverged after creating the release commit.");
   }
+  return mainOid;
 }
 
 async function runTagStep(
   smartshellInstance: plugins.smartshell.Smartshell,
   newVersion: string,
+  releaseCommitOidArg: string,
+  cwdArg: string,
 ): Promise<void> {
-  const result = await smartshellInstance.exec(`git tag v${newVersion} -m ${shellQuote(`v${newVersion}`)}`);
+  const result = await smartshellInstance.execSpawn(
+    "git",
+    [
+      "tag",
+      "-a",
+      `v${newVersion}`,
+      "-m",
+      `v${newVersion}`,
+      releaseCommitOidArg,
+    ],
+    {
+      cwd: cwdArg,
+      env: releaseGitEnv,
+      timeout: 60_000,
+      timeoutKillGraceMs: 5_000,
+    },
+  );
   if (result.exitCode !== 0) {
-    logger.log("error", "Release tag failed.");
-    process.exit(1);
+    throw new Error("Release tag failed.");
   }
 }
 
-async function runGitTarget(
-  smartshellInstance: plugins.smartshell.Smartshell,
-  workflow: IResolvedReleaseWorkflow,
-): Promise<ITargetResult[]> {
-  const currentBranchResult = await smartshellInstance.exec("git branch --show-current");
-  const currentBranch = currentBranchResult.stdout.trim() || "master";
-  const commands: Array<{ target: string; command: string }> = [];
-  if (workflow.pushBranch) {
-    commands.push({
-      target: `${workflow.gitRemote}/${currentBranch}`,
-      command: `git push ${workflow.gitRemote} ${currentBranch}`,
-    });
-  }
-  if (workflow.pushTags) {
-    commands.push({
-      target: `${workflow.gitRemote}/tags`,
-      command: `git push ${workflow.gitRemote} --tags`,
-    });
-  }
-
-  const results: ITargetResult[] = [];
-  for (const { target, command } of commands) {
-    const result = await smartshellInstance.exec(command);
-    results.push({
-      target,
-      status: result.exitCode === 0 ? "success" : "failed",
-      message: result.exitCode === 0 ? undefined : "push failed",
-    });
-  }
-  return results;
+interface IReleaseRefs {
+  mainOid: string;
+  tagOid: string;
 }
 
-async function runNpmTarget(
-  smartshellInstance: plugins.smartshell.Smartshell,
-  workflow: IResolvedReleaseWorkflow,
-): Promise<ITargetResult[]> {
-  if (!workflow.npmEnabled) {
-    return [{ target: "npm", status: "skipped", message: "disabled" }];
-  }
-  if (workflow.npmRegistries.length === 0) {
-    return [{ target: "npm", status: "failed", message: "no registries configured" }];
-  }
-
-  const results: ITargetResult[] = [];
-  for (const registry of workflow.npmRegistries) {
-    const command = `pnpm publish --registry=${registry} --access=${workflow.npmAccessLevel}`;
-    const result = await smartshellInstance.exec(command);
-    const output = result.combinedOutput;
-    if (result.exitCode === 0) {
-      results.push({ target: registry, status: "success" });
-    } else if (isAlreadyPublishedOutput(output) && workflow.npmAlreadyPublished === "success") {
-      results.push({ target: registry, status: "already-published" });
-    } else {
-      results.push({ target: registry, status: "failed", message: firstMeaningfulLine(output) });
-    }
+const resolveGitObjectOid = async (
+  smartshellInstanceArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+  revisionArg: string,
+): Promise<string> => {
+  const result = await smartshellInstanceArg.execSpawn(
+    "git",
+    ["rev-parse", "--verify", revisionArg],
+    {
+      cwd: cwdArg,
+      env: releaseGitEnv,
+      silent: true,
+      timeout: 60_000,
+      timeoutKillGraceMs: 5_000,
+    },
+  );
+  const oid = result.stdout.trim();
+  if (result.exitCode !== 0 || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(oid)) {
+    throw new Error(`Unable to resolve release Git object ${revisionArg}.`);
   }
-  return results;
-}
+  return oid;
+};
 
-async function runDockerTarget(
-  smartshellInstance: plugins.smartshell.Smartshell,
-  workflow: IResolvedReleaseWorkflow,
-): Promise<ITargetResult[]> {
-  if (!workflow.dockerEnabled) {
-    return [{ target: "docker", status: "skipped", message: "disabled" }];
+const captureReleaseRefs = async (
+  smartshellInstanceArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+  newVersionArg: string,
+  expectedMainOidArg?: string,
+): Promise<IReleaseRefs> => {
+  const mainOid = await resolveGitObjectOid(
+    smartshellInstanceArg,
+    cwdArg,
+    "refs/heads/main^{commit}",
+  );
+  const tagOid = await resolveGitObjectOid(
+    smartshellInstanceArg,
+    cwdArg,
+    `refs/tags/v${newVersionArg}^{tag}`,
+  );
+  const tagCommitOid = await resolveGitObjectOid(
+    smartshellInstanceArg,
+    cwdArg,
+    `refs/tags/v${newVersionArg}^{commit}`,
+  );
+  if (
+    (expectedMainOidArg && mainOid !== expectedMainOidArg) ||
+    tagCommitOid !== mainOid
+  ) {
+    throw new Error(
+      "The release tag is not bound to the captured main release commit.",
+    );
   }
+  return { mainOid, tagOid };
+};
 
-  let packageJson: unknown;
-  try {
-    packageJson = JSON.parse(
-      await plugins.fs.readFile(plugins.path.join(paths.cwd, "package.json"), "utf8"),
+const verifyReleaseRefs = async (
+  smartshellInstanceArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+  newVersionArg: string,
+  expectedRefsArg: IReleaseRefs,
+): Promise<void> => {
+  const currentRefs = await captureReleaseRefs(
+    smartshellInstanceArg,
+    cwdArg,
+    newVersionArg,
+    expectedRefsArg.mainOid,
+  );
+  if (
+    currentRefs.mainOid !== expectedRefsArg.mainOid ||
+    currentRefs.tagOid !== expectedRefsArg.tagOid
+  ) {
+    throw new Error(
+      "Local release refs changed before publication. Inspect main and the release tag before retrying.",
     );
-  } catch {
-    packageJson = undefined;
-  }
-  if (!getDeclaredTsdockerRange(packageJson)) {
-    return [{
-      target: "tsdocker",
-      status: "failed",
-      message: "Docker releases require @git.zone/tsdocker as a project dependency",
-    }];
-  }
-  if (!(await hasInstalledProjectTsdockerBinary(paths.cwd))) {
-    return [{
-      target: "tsdocker",
-      status: "failed",
-      message: "Docker releases require the installed project-local tSDocker binary",
-    }];
-  }
-
-  const minimumTsdockerVersion = getTsdockerMinimumVersion(
-    workflow.dockerBuildRegistries.length > 0,
-    workflow.dockerTest,
-  );
-  if (minimumTsdockerVersion) {
-    const versionResult = await smartshellInstance.exec("pnpm exec tsdocker --version");
-    if (
-      versionResult.exitCode !== 0
-      || !supportsTsdockerMinimumVersion(
-        versionResult.combinedOutput,
-        minimumTsdockerVersion,
-      )
-    ) {
-      const minimumVersion = formatTsdockerMinimumVersion(minimumTsdockerVersion);
-      return [{
-        target: "tsdocker",
-        status: "failed",
-        message: `Docker release options require project-local @git.zone/tsdocker >= ${minimumVersion}`,
-      }];
-    }
   }
-
-  const command = buildTsdockerPushCommand(workflow);
-  const result = await smartshellInstance.exec(command);
-  const output = result.combinedOutput;
-  return [{
-    target: workflow.dockerPatterns.length > 0
-      ? `tsdocker:${workflow.dockerPatterns.join(",")}`
-      : "tsdocker",
-    status: result.exitCode === 0 ? "success" : "failed",
-    message: result.exitCode === 0 ? undefined : firstMeaningfulLine(output),
-  }];
-}
+};
 
 type TDockerCommandWorkflow = Pick<
   IResolvedReleaseWorkflow,
@@ -341,7 +923,9 @@ type TDockerCommandWorkflow = Pick<
   | "dockerPatterns"
 >;
 
-export function buildTsdockerPushCommand(workflow: TDockerCommandWorkflow): string {
+export function buildTsdockerPushCommand(
+  workflow: TDockerCommandWorkflow,
+): string {
   const commandParts = ["pnpm", "exec", "tsdocker", "push"];
   for (const pattern of workflow.dockerPatterns) {
     commandParts.push(shellQuote(pattern));
@@ -350,7 +934,9 @@ export function buildTsdockerPushCommand(workflow: TDockerCommandWorkflow): stri
     commandParts.push(`--registry=${shellQuote(workflow.dockerRegistry)}`);
   }
   if (workflow.dockerBuildRegistries.length > 0) {
-    commandParts.push(`--build-registries=${shellQuote(workflow.dockerBuildRegistries.join(","))}`);
+    commandParts.push(
+      `--build-registries=${shellQuote(workflow.dockerBuildRegistries.join(","))}`,
+    );
   }
   if (workflow.dockerTest) {
     commandParts.push("--test");
@@ -363,7 +949,11 @@ export function buildTsdockerPushCommand(workflow: TDockerCommandWorkflow): stri
   }
   if (workflow.dockerParallel === true) {
     commandParts.push("--parallel");
-  } else if (typeof workflow.dockerParallel === "number" && Number.isFinite(workflow.dockerParallel) && workflow.dockerParallel > 0) {
+  } else if (
+    typeof workflow.dockerParallel === "number" &&
+    Number.isFinite(workflow.dockerParallel) &&
+    workflow.dockerParallel > 0
+  ) {
     commandParts.push(`--parallel=${Math.floor(workflow.dockerParallel)}`);
   }
   if (workflow.dockerContext) {
@@ -372,37 +962,50 @@ export function buildTsdockerPushCommand(workflow: TDockerCommandWorkflow): stri
   return commandParts.join(" ");
 }
 
-function isAlreadyPublishedOutput(output: string): boolean {
-  return /previously published versions|cannot publish over|already exists/i.test(output);
-}
-
-function firstMeaningfulLine(output: string): string {
-  return output
-    .split("\n")
-    .map((line) => line.trim())
-    .find((line) => line.length > 0) || "command failed";
-}
-
 function shellQuote(value: string): string {
   return `'${value.replaceAll("'", "'\\''")}'`;
 }
 
-function printReleasePlan(workflow: IResolvedReleaseWorkflow): void {
+function printReleasePlan(
+  workflow: IResolvedReleaseWorkflow,
+  branchContextArg: IReleaseBranchContext,
+): void {
   console.log("");
   console.log("gitzone release - resolved workflow");
   console.log(`confirmation: ${workflow.confirmation}`);
   console.log(`plan: ${workflow.plan.join(" -> ")}`);
-  console.log(`targets: ${workflow.targets.length > 0 ? workflow.targets.join(", ") : "none"}`);
-  console.log(`changelog: ${workflow.changelogFile}#${workflow.changelogPendingSection}`);
+  console.log(`source branch: ${branchContextArg.sourceBranch}`);
+  if (branchContextArg.sourceBranch !== "main") {
+    console.log("release branch: main (fast-forward integration requested)");
+    console.log(
+      `remote main ancestry: ${branchContextArg.planAncestryVerified ? "verified" : "deferred until execution"}`,
+    );
+  }
+  console.log(
+    `targets: ${workflow.targets.length > 0 ? workflow.targets.join(", ") : "none"}`,
+  );
+  console.log(
+    `changelog: ${workflow.changelogFile}#${workflow.changelogPendingSection}`,
+  );
   if (workflow.targets.includes("npm")) {
-    console.log(`npm registries: ${workflow.npmRegistries.length > 0 ? workflow.npmRegistries.join(", ") : "none"}`);
+    console.log(
+      `npm registries: ${workflow.npmRegistries.length > 0 ? workflow.npmRegistries.join(", ") : "none"}`,
+    );
   }
   if (workflow.targets.includes("docker")) {
     console.log(`docker engine: ${workflow.dockerEngine}`);
-    console.log(`docker registry: ${workflow.dockerRegistry || "all configured registries"}`);
-    console.log(`docker build authentication: ${workflow.dockerBuildRegistries.length > 0 ? workflow.dockerBuildRegistries.join(", ") : "all configured registries"}`);
-    console.log(`docker image tests: ${workflow.dockerTest ? "required before destination publication" : "not requested"}`);
-    console.log(`docker patterns: ${workflow.dockerPatterns.length > 0 ? workflow.dockerPatterns.join(", ") : "all Dockerfiles"}`);
+    console.log(
+      `docker registry: ${workflow.dockerRegistry || "all configured registries"}`,
+    );
+    console.log(
+      `docker build authentication: ${workflow.dockerBuildRegistries.length > 0 ? workflow.dockerBuildRegistries.join(", ") : "all configured registries"}`,
+    );
+    console.log(
+      `docker image tests: ${workflow.dockerTest ? "required before destination publication" : "not requested"}`,
+    );
+    console.log(
+      `docker patterns: ${workflow.dockerPatterns.length > 0 ? workflow.dockerPatterns.join(", ") : "all Dockerfiles"}`,
+    );
     console.log(`docker options: ${formatDockerOptions(workflow)}`);
   }
   console.log("");
@@ -410,86 +1013,127 @@ function printReleasePlan(workflow: IResolvedReleaseWorkflow): void {
 
 function formatDockerOptions(workflow: IResolvedReleaseWorkflow): string {
   const options: string[] = [];
-  if (workflow.dockerRegistry) options.push(`registry=${workflow.dockerRegistry}`);
+  if (workflow.dockerRegistry)
+    options.push(`registry=${workflow.dockerRegistry}`);
   if (workflow.dockerBuildRegistries.length > 0) {
     options.push(`buildRegistries=${workflow.dockerBuildRegistries.join(",")}`);
   }
   if (workflow.dockerTest) options.push("test");
   if (workflow.dockerCached) options.push("cached");
-  if (workflow.dockerParallel) options.push(`parallel=${workflow.dockerParallel === true ? "true" : workflow.dockerParallel}`);
+  if (workflow.dockerParallel)
+    options.push(
+      `parallel=${workflow.dockerParallel === true ? "true" : workflow.dockerParallel}`,
+    );
   if (workflow.dockerNoBuild) options.push("no-build");
   if (workflow.dockerContext) options.push(`context=${workflow.dockerContext}`);
   return options.length > 0 ? options.join(", ") : "default";
 }
 
-function printReleaseSummary(
-  newVersion: string,
-  gitResults: ITargetResult[],
-  npmResults: ITargetResult[],
-  dockerResults: ITargetResult[],
-): void {
-  console.log("");
-  console.log(`Release v${newVersion}`);
-  console.log("");
-
-  if (gitResults.length > 0) {
-    console.log("git:");
-    for (const result of gitResults) {
-      console.log(`  ${result.target}  ${result.status}${result.message ? ` (${result.message})` : ""}`);
-    }
-  }
-
-  if (npmResults.length > 0) {
-    console.log("npm:");
-    for (const result of npmResults) {
-      console.log(`  ${result.target}  ${result.status}${result.message ? ` (${result.message})` : ""}`);
-    }
-  }
-
-  if (dockerResults.length > 0) {
-    console.log("docker:");
-    for (const result of dockerResults) {
-      console.log(`  ${result.target}  ${result.status}${result.message ? ` (${result.message})` : ""}`);
-    }
-  }
-}
-
 export function showHelp(mode?: ICliMode): void {
   if (mode?.json) {
     printJson({
       command: "release",
-      usage: "gitzone release [options]",
-      description: "Creates a versioned release from pending changelog entries and publishes configured artifacts.",
+      usage: "gitzone release [inspect [version]|resume <version>] [options]",
+      description:
+        "Creates a versioned release from pending changelog entries and publishes configured artifacts.",
       flags: [
-        { flag: "-y, --yes", description: "Run without interactive confirmation" },
+        {
+          flag: "-y, --yes",
+          description: "Run without interactive confirmation",
+        },
         { flag: "-t, --test", description: "Enable release preflight tests" },
-        { flag: "-b, --build", description: "Enable release preflight build" },
-        { flag: "-p, --push", description: "Enable the git release target" },
-        { flag: "--target <names>", description: "Release only selected targets: git,npm,docker" },
-        { flag: "--npm", description: "Enable the npm release target" },
-        { flag: "--docker", description: "Enable the tsdocker release target" },
-        { flag: "--no-publish", description: "Run release core and git target only" },
-        { flag: "--plan", description: "Show resolved workflow without mutating files" },
+        {
+          flag: "-b, --build",
+          description:
+            "Enable the build after local release metadata is created",
+        },
+        {
+          flag: "--no-build",
+          description: "Disable the post-metadata release build",
+        },
+        { flag: "-p, --push", description: "Explicitly select the git target" },
+        {
+          flag: "--target <names>",
+          description:
+            "Replace configured targets with a non-empty subset of git,npm,docker",
+        },
+        { flag: "--npm", description: "Explicitly select the npm target" },
+        {
+          flag: "--docker",
+          description: "Select Docker and fail closed under journal schema v1",
+        },
+        {
+          flag: "--no-publish",
+          description: "Remove npm and Docker without implicitly enabling Git",
+        },
+        {
+          flag: "--merge",
+          description:
+            "Fast-forward and lease-push a cleanly rebased feature branch before release metadata",
+        },
+        {
+          flag: "--plan",
+          description:
+            "Show the workflow without fetching or mutating refs, files, the index, or worktrees",
+        },
+        {
+          flag: "inspect [version]",
+          description: "Read one or all durable release journals without mutation",
+        },
+        {
+          flag: "resume <version>",
+          description: "Resume exact Git/npm publication without rebuilding or repacking",
+        },
+        {
+          flag: "--recover-attempt <id>",
+          description:
+            "Recover one exact 32-character hexadecimal attempt ID after proving it stopped",
+        },
       ],
     });
     return;
   }
 
   console.log("");
-  console.log("Usage: gitzone release [options]");
+  console.log(
+    "Usage: gitzone release [inspect [version]|resume <version>] [options]",
+  );
   console.log("");
   console.log("Creates a versioned release from changelog Pending entries.");
   console.log("");
   console.log("Flags:");
   console.log("  -y, --yes           Run without interactive confirmation");
   console.log("  -t, --test          Enable release preflight tests");
-  console.log("  -b, --build         Enable release preflight build");
-  console.log("  -p, --push          Enable the git release target");
-  console.log("  --target <names>    Release only selected targets: git,npm,docker");
-  console.log("  --npm               Enable the npm release target");
-  console.log("  --docker            Enable the tsdocker release target");
-  console.log("  --no-publish        Run release core and git target only");
+  console.log(
+    "  -b, --build         Build after creating local release metadata",
+  );
+  console.log("  --no-build          Disable the post-metadata release build");
+  console.log("  -p, --push          Explicitly select the git target");
+  console.log(
+    "  --target <names>    Replace configured targets with a non-empty subset of git,npm,docker",
+  );
+  console.log("  --npm               Explicitly select the npm target");
+  console.log(
+    "  --docker            Select Docker (fails closed under journal schema v1)",
+  );
+  console.log(
+    "  --no-publish        Remove npm and Docker without implicitly enabling Git",
+  );
+  console.log(
+    "  --merge             Fast-forward and lease-push a cleanly rebased feature branch before release metadata",
+  );
   console.log("  --major|--minor|--patch  Override inferred semver level");
-  console.log("  --plan              Show resolved workflow without mutating files");
+  console.log(
+    "  --plan              Show workflow without fetching or mutating refs, files, index, or worktrees",
+  );
+  console.log(
+    "  inspect [version]   Read one or all durable release journals without mutation",
+  );
+  console.log(
+    "  resume <version>    Resume exact Git/npm publication without rebuilding or repacking",
+  );
+  console.log(
+    "  --recover-attempt   Recover one exact 32-character hexadecimal attempt ID after proving its publisher stopped",
+  );
   console.log("");
 }