@treeseed/sdk 0.6.19 → 0.6.21

package/dist/operations/services/release-candidate.d.ts

@@ -0,0 +1,39 @@
+export type ReleaseCandidateStatus = 'passed' | 'failed';
+export type ReleaseCandidateFailure = {
+    code: string;
+    scope: string;
+    provider?: string | null;
+    message: string;
+    details?: Record<string, unknown> | null;
+};
+export type ReleaseCandidateFingerprint = {
+    key: string;
+    rootSha: string | null;
+    packageShas: Record<string, string | null>;
+    plannedVersions: Record<string, string>;
+    lockfiles: Record<string, string | null>;
+    selectedPackages: string[];
+};
+export type ReleaseCandidateCheck = {
+    name: string;
+    status: 'passed' | 'skipped' | 'failed';
+    detail: string;
+};
+export type ReleaseCandidateReport = {
+    status: ReleaseCandidateStatus;
+    fingerprint: ReleaseCandidateFingerprint;
+    reused: boolean;
+    checkedAt: string;
+    failures: ReleaseCandidateFailure[];
+    checks: ReleaseCandidateCheck[];
+};
+export type ReleaseCandidateInput = {
+    root: string;
+    plannedVersions: Record<string, unknown>;
+    selectedPackageNames?: string[];
+    allowReuse?: boolean;
+};
+export declare function buildReleaseCandidateFingerprint(input: ReleaseCandidateInput): ReleaseCandidateFingerprint;
+export declare function readCachedReleaseCandidateReport(root: string, key: string): ReleaseCandidateReport | null;
+export declare function writeReleaseCandidateReport(root: string, report: ReleaseCandidateReport): ReleaseCandidateReport;
+export declare function runReleaseCandidateGate(input: ReleaseCandidateInput): Promise<ReleaseCandidateReport>;

package/dist/operations/services/release-candidate.js

@@ -0,0 +1,531 @@
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { isTreeseedEnvironmentEntryRelevant, isTreeseedEnvironmentEntryRequired } from "../../platform/environment.js";
+import { getGitHubAutomationMode, maybeResolveGitHubRepositorySlug } from "./github-automation.js";
+import { createGitHubApiClient, listGitHubEnvironmentSecretNames, listGitHubEnvironmentVariableNames } from "./github-api.js";
+import { collectInternalDevReferenceIssues } from "./package-reference-policy.js";
+import { collectTreeseedEnvironmentContext, resolveTreeseedMachineEnvironmentValues, validateTreeseedCommandEnvironment } from "./config-runtime.js";
+import { loadDeployState } from "./deploy.js";
+import { loadCliDeployConfig } from "./runtime-tools.js";
+import { run, workspacePackages } from "./workspace-tools.js";
+const RELEASE_CANDIDATE_CACHE_DIR = ".treeseed/workflow/release-candidates";
+const STABLE_SEMVER = /^\d+\.\d+\.\d+$/u;
+const REHEARSAL_IGNORED_SEGMENTS = /* @__PURE__ */ new Set([
+  ".git",
+  ".treeseed",
+  ".wrangler",
+  ".astro",
+  "coverage",
+  "dist",
+  "node_modules"
+]);
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function sortedRecord(record) {
+  return Object.fromEntries(Object.entries(record).sort(([left], [right]) => left.localeCompare(right)));
+}
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function fileSha256(filePath) {
+  if (!existsSync(filePath)) return null;
+  return createHash("sha256").update(readFileSync(filePath)).digest("hex");
+}
+function safeGitHead(repoDir) {
+  try {
+    return run("git", ["rev-parse", "HEAD"], { cwd: repoDir, capture: true }).trim();
+  } catch {
+    return null;
+  }
+}
+function safePackageJson(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeJsonFile(filePath, value) {
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+function packageScripts(filePath) {
+  const packageJson = safePackageJson(filePath);
+  return packageJson?.scripts && typeof packageJson.scripts === "object" && !Array.isArray(packageJson.scripts) ? packageJson.scripts : {};
+}
+function releaseCandidateCachePath(root, key) {
+  return resolve(root, RELEASE_CANDIDATE_CACHE_DIR, `${key}.json`);
+}
+function ensureReleaseCandidateCacheDir(root) {
+  const dir = resolve(root, RELEASE_CANDIDATE_CACHE_DIR);
+  mkdirSync(dir, { recursive: true });
+  const gitignorePath = resolve(root, ".treeseed", "workflow", ".gitignore");
+  mkdirSync(dirname(gitignorePath), { recursive: true });
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, "*\n!.gitignore\n!runs/\nruns/*\n!runs/.gitignore\n", "utf8");
+  }
+  return dir;
+}
+function buildReleaseCandidateFingerprint(input) {
+  const selectedPackages = [...new Set((input.selectedPackageNames ?? []).map(String))].sort();
+  const selectedPackageSet = new Set(selectedPackages);
+  const packages = workspacePackages(input.root).filter((pkg) => typeof pkg.name === "string" && pkg.name.startsWith("@treeseed/"));
+  const packageShas = sortedRecord(Object.fromEntries(
+    packages.map((pkg) => [pkg.name, safeGitHead(pkg.dir)])
+  ));
+  const plannedVersions = sortedRecord(Object.fromEntries(
+    Object.entries(input.plannedVersions).filter(([name]) => name === "@treeseed/market" || selectedPackageSet.has(name)).map(([name, version]) => [name, String(version)])
+  ));
+  const lockfiles = sortedRecord({
+    "@treeseed/market": fileSha256(resolve(input.root, "package-lock.json")),
+    ...Object.fromEntries(packages.map((pkg) => [pkg.name, fileSha256(resolve(pkg.dir, "package-lock.json"))]))
+  });
+  const base = {
+    rootSha: safeGitHead(input.root),
+    packageShas,
+    plannedVersions,
+    lockfiles,
+    selectedPackages
+  };
+  return {
+    ...base,
+    key: sha256(JSON.stringify(base))
+  };
+}
+function readCachedReleaseCandidateReport(root, key) {
+  const cachePath = releaseCandidateCachePath(root, key);
+  if (!existsSync(cachePath)) return null;
+  try {
+    return JSON.parse(readFileSync(cachePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeReleaseCandidateReport(root, report) {
+  ensureReleaseCandidateCacheDir(root);
+  writeFileSync(releaseCandidateCachePath(root, report.fingerprint.key), `${JSON.stringify(report, null, 2)}
+`, "utf8");
+  return report;
+}
+function addFailure(failures, failure) {
+  failures.push({
+    ...failure,
+    details: failure.details ?? null,
+    provider: failure.provider ?? null
+  });
+}
+function packageReadinessChecks(root, selectedPackageNames, failures) {
+  if (selectedPackageNames.length === 0) {
+    return { name: "package-release-readiness", status: "skipped", detail: "No packages are selected for this release." };
+  }
+  if (getGitHubAutomationMode() === "stub") {
+    return { name: "package-release-readiness", status: "skipped", detail: "GitHub automation is stubbed." };
+  }
+  const selected = new Set(selectedPackageNames);
+  const packages = workspacePackages(root).filter((pkg) => selected.has(pkg.name));
+  for (const pkg of packages) {
+    const packageJson = safePackageJson(resolve(pkg.dir, "package.json"));
+    const scripts = packageJson?.scripts && typeof packageJson.scripts === "object" && !Array.isArray(packageJson.scripts) ? packageJson.scripts : {};
+    if (!existsSync(resolve(pkg.dir, ".github", "workflows", "publish.yml"))) {
+      addFailure(failures, {
+        code: "missing_publish_workflow",
+        scope: pkg.name,
+        provider: "github",
+        message: `${pkg.name} is missing .github/workflows/publish.yml.`
+      });
+    }
+    if (typeof scripts["release:publish"] !== "string") {
+      addFailure(failures, {
+        code: "missing_publish_script",
+        scope: pkg.name,
+        message: `${pkg.name} is missing a release:publish script.`
+      });
+    }
+    if (typeof scripts["verify:local"] !== "string" && typeof scripts["verify"] !== "string" && typeof scripts["verify:action"] !== "string") {
+      addFailure(failures, {
+        code: "missing_verify_script",
+        scope: pkg.name,
+        message: `${pkg.name} is missing a release-ready verify script.`
+      });
+    }
+    try {
+      run("npm", ["pack", "--dry-run"], { cwd: pkg.dir, capture: true, timeoutMs: 12e4 });
+    } catch (error) {
+      addFailure(failures, {
+        code: "npm_pack_dry_run_failed",
+        scope: pkg.name,
+        message: `${pkg.name} failed npm pack --dry-run.`,
+        details: { error: error instanceof Error ? error.message : String(error) }
+      });
+    }
+  }
+  return {
+    name: "package-release-readiness",
+    status: failures.some((failure) => failure.code.startsWith("missing_") || failure.code === "npm_pack_dry_run_failed") ? "failed" : "passed",
+    detail: `Checked ${packages.length} selected package${packages.length === 1 ? "" : "s"}.`
+  };
+}
+function copyWorkspaceForProductionRehearsal(root) {
+  const tempParent = mkdtempSync(join(tmpdir(), "treeseed-release-candidate-"));
+  const tempRoot = join(tempParent, "workspace");
+  cpSync(root, tempRoot, {
+    recursive: true,
+    filter: (source) => {
+      const rel = relative(root, source);
+      if (!rel) return true;
+      const segments = rel.split(/[\\/]+/u);
+      return !segments.some((segment) => REHEARSAL_IGNORED_SEGMENTS.has(segment));
+    }
+  });
+  return { tempParent, tempRoot };
+}
+function applyPlannedStableMetadata(root, plannedVersions) {
+  const stableVersions = new Map(
+    Object.entries(plannedVersions).filter(([, version]) => STABLE_SEMVER.test(version))
+  );
+  const targets = [
+    { name: "@treeseed/market", dir: root },
+    ...workspacePackages(root).map((pkg) => ({ name: pkg.name, dir: pkg.dir }))
+  ];
+  for (const target of targets) {
+    const packageJsonPath = resolve(target.dir, "package.json");
+    const packageJson = safePackageJson(packageJsonPath);
+    if (!packageJson) continue;
+    let changed = false;
+    const plannedVersion = stableVersions.get(target.name);
+    if (plannedVersion && packageJson.version !== plannedVersion) {
+      packageJson.version = plannedVersion;
+      changed = true;
+    }
+    for (const field of ["dependencies", "optionalDependencies", "peerDependencies", "devDependencies"]) {
+      const values = packageJson[field];
+      if (!values || typeof values !== "object" || Array.isArray(values)) continue;
+      for (const [dependencyName, version] of stableVersions.entries()) {
+        if (!(dependencyName in values)) continue;
+        if (String(values[dependencyName]) === version) continue;
+        values[dependencyName] = version;
+        changed = true;
+      }
+    }
+    if (changed) {
+      writeJsonFile(packageJsonPath, packageJson);
+    }
+  }
+}
+function rehearsalVerifyScript(root) {
+  const scripts = packageScripts(resolve(root, "package.json"));
+  for (const scriptName of ["verify:direct", "verify:local", "verify", "build"]) {
+    if (typeof scripts[scriptName] === "string") {
+      return scriptName;
+    }
+  }
+  return null;
+}
+function runProductionDependencyRehearsal(root, plannedVersions, selectedPackageNames, failures) {
+  if (getGitHubAutomationMode() === "stub" || process.env.TREESEED_RELEASE_CANDIDATE_REHEARSAL_MODE === "skip") {
+    return "Skipped clean install rehearsal in stub/skip mode.";
+  }
+  const selectedPackageSet = new Set(selectedPackageNames);
+  let tempParent = null;
+  try {
+    const copied = copyWorkspaceForProductionRehearsal(root);
+    tempParent = copied.tempParent;
+    applyPlannedStableMetadata(copied.tempRoot, plannedVersions);
+    run("npm", ["install", "--package-lock-only", "--ignore-scripts"], { cwd: copied.tempRoot, timeoutMs: 3e5 });
+    run("npm", ["ci"], { cwd: copied.tempRoot, timeoutMs: 6e5 });
+    const scriptName = rehearsalVerifyScript(copied.tempRoot);
+    if (scriptName) {
+      run("npm", ["run", scriptName], { cwd: copied.tempRoot, timeoutMs: 9e5 });
+    }
+    const postInstallIssues = collectInternalDevReferenceIssues(copied.tempRoot, selectedPackageSet);
+    if (postInstallIssues.length > 0) {
+      addFailure(failures, {
+        code: "internal_dev_references_after_rehearsal",
+        scope: "@treeseed/market",
+        message: "Production dependency rehearsal still found internal dev references after clean install.",
+        details: {
+          references: postInstallIssues.map((issue) => ({
+            filePath: issue.filePath,
+            field: issue.field,
+            dependencyName: issue.dependencyName,
+            spec: issue.spec,
+            reason: issue.reason
+          }))
+        }
+      });
+    }
+    return scriptName ? `Ran clean install and npm run ${scriptName} in a temporary production rehearsal workspace.` : "Ran clean install in a temporary production rehearsal workspace.";
+  } catch (error) {
+    addFailure(failures, {
+      code: "production_dependency_rehearsal_failed",
+      scope: "@treeseed/market",
+      message: "Production dependency rehearsal failed in the temporary workspace.",
+      details: { error: error instanceof Error ? error.message : String(error) }
+    });
+    return "Production dependency rehearsal failed.";
+  } finally {
+    if (tempParent) {
+      rmSync(tempParent, { recursive: true, force: true });
+    }
+  }
+}
+function dependencyRehearsalChecks(root, plannedVersions, selectedPackageNames, failures) {
+  const before = failures.length;
+  for (const [name, version] of Object.entries(plannedVersions)) {
+    if ((name === "@treeseed/market" || selectedPackageNames.includes(name)) && !STABLE_SEMVER.test(version)) {
+      addFailure(failures, {
+        code: "unstable_planned_version",
+        scope: name,
+        message: `${name} planned release version is not stable semver: ${version}.`
+      });
+    }
+  }
+  const selectedPackageSet = new Set(selectedPackageNames);
+  const devReferenceIssues = collectInternalDevReferenceIssues(root);
+  const unrehearsableDevReferences = devReferenceIssues.filter((issue) => {
+    const dependencyName = issue.dependencyName ?? "";
+    const planned = plannedVersions[dependencyName];
+    return !selectedPackageSet.has(dependencyName) || !planned || !STABLE_SEMVER.test(planned);
+  });
+  if (unrehearsableDevReferences.length > 0) {
+    addFailure(failures, {
+      code: "internal_dev_references",
+      scope: "@treeseed/market",
+      message: "Production dependency rehearsal found internal dev references without a stable planned replacement.",
+      details: {
+        references: unrehearsableDevReferences.map((issue) => ({
+          filePath: issue.filePath,
+          field: issue.field,
+          dependencyName: issue.dependencyName,
+          spec: issue.spec,
+          reason: issue.reason
+        }))
+      }
+    });
+  }
+  const rehearsalDetail = unrehearsableDevReferences.length === 0 && failures.length === before ? runProductionDependencyRehearsal(root, plannedVersions, selectedPackageNames, failures) : "Skipped clean install rehearsal because stable dependency metadata is incomplete.";
+  return {
+    name: "production-dependency-rehearsal",
+    status: failures.length > before ? "failed" : "passed",
+    detail: `${devReferenceIssues.length > 0 ? `Rehearsed stable replacements for ${devReferenceIssues.length} internal dev reference${devReferenceIssues.length === 1 ? "" : "s"}.` : "Checked planned stable versions and internal dependency references."} ${rehearsalDetail}`
+  };
+}
+function localConfigCheck(root, scope, failures) {
+  try {
+    const report = validateTreeseedCommandEnvironment({ tenantRoot: root, scope, purpose: "deploy" });
+    const problems = [...report.validation.missing, ...report.validation.invalid];
+    for (const problem of problems) {
+      addFailure(failures, {
+        code: "missing_local_config",
+        scope,
+        provider: problem.entry.group ?? "config",
+        message: `${scope} deploy config is missing or invalid: ${problem.id}.`,
+        details: { key: problem.id, provider: problem.entry.group ?? null }
+      });
+    }
+  } catch (error) {
+    addFailure(failures, {
+      code: "config_validation_failed",
+      scope,
+      provider: "config",
+      message: `${scope} deploy config could not be validated.`,
+      details: { error: error instanceof Error ? error.message : String(error) }
+    });
+  }
+}
+async function githubRemoteConfigCheck(root, scope, failures) {
+  if (getGitHubAutomationMode() === "stub") {
+    return;
+  }
+  const repository = maybeResolveGitHubRepositorySlug(root);
+  if (!repository) {
+    addFailure(failures, {
+      code: "missing_github_repository",
+      scope,
+      provider: "github",
+      message: `${scope} GitHub config parity could not determine the repository from origin.`
+    });
+    return;
+  }
+  try {
+    const environment = scope === "prod" ? "production" : scope;
+    const expected = expectedGitHubDeployEnvironment(root, scope);
+    const client = createGitHubApiClient();
+    const [secretNames, variableNames] = await Promise.all([
+      listGitHubEnvironmentSecretNames(repository, environment, { client }),
+      listGitHubEnvironmentVariableNames(repository, environment, { client })
+    ]);
+    const missingSecrets = expected.secrets.filter((key) => !secretNames.has(key));
+    const missingVariables = expected.variables.filter((key) => !variableNames.has(key));
+    for (const key of missingSecrets) {
+      addFailure(failures, {
+        code: "missing_remote_config",
+        scope,
+        provider: "github-secret",
+        message: `${scope} GitHub secret is missing: ${key}.`,
+        details: { key, provider: "github-secret", repository, environment }
+      });
+    }
+    for (const key of missingVariables) {
+      addFailure(failures, {
+        code: "missing_remote_config",
+        scope,
+        provider: "github-variable",
+        message: `${scope} GitHub variable is missing: ${key}.`,
+        details: { key, provider: "github-variable", repository, environment }
+      });
+    }
+  } catch (error) {
+    addFailure(failures, {
+      code: "remote_config_check_failed",
+      scope,
+      provider: "github",
+      message: `${scope} GitHub config parity check failed.`,
+      details: { error: error instanceof Error ? error.message : String(error) }
+    });
+  }
+}
+function expectedGitHubDeployEnvironment(root, scope) {
+  const registry = collectTreeseedEnvironmentContext(root);
+  const values = resolveTreeseedMachineEnvironmentValues(root, scope);
+  const expectedEntries = registry.entries.filter((entry) => {
+    if (!isTreeseedEnvironmentEntryRelevant(entry, registry.context, scope, "deploy")) return false;
+    if (isTreeseedEnvironmentEntryRequired(entry, registry.context, scope, "deploy")) return true;
+    return typeof values[entry.id] === "string" && values[entry.id].trim().length > 0;
+  });
+  return {
+    secrets: [...new Set(expectedEntries.filter((entry) => entry.targets.includes("github-secret")).map((entry) => entry.id))],
+    variables: [...new Set(expectedEntries.filter((entry) => entry.targets.includes("github-variable")).map((entry) => entry.id))]
+  };
+}
+function providerResourceIdentifierCheck(root, scope, failures) {
+  try {
+    const deployConfig = loadCliDeployConfig(root);
+    const state = loadDeployState(root, deployConfig, { scope });
+    const siteDataDb = state.d1Databases?.SITE_DATA_DB;
+    if (!siteDataDb?.databaseName || !siteDataDb?.databaseId) {
+      addFailure(failures, {
+        code: "missing_remote_resource_identifier",
+        scope,
+        provider: "cloudflare-d1",
+        message: `${scope} Cloudflare D1 SITE_DATA_DB is missing a database name or id.`,
+        details: { resource: "SITE_DATA_DB", required: ["databaseName", "databaseId"] }
+      });
+    }
+    const services = state.services && typeof state.services === "object" && !Array.isArray(state.services) ? state.services : {};
+    for (const [serviceKey, service] of Object.entries(services)) {
+      if ((service.provider ?? "railway") !== "railway") continue;
+      if (!service.projectName && !service.projectId) {
+        addFailure(failures, {
+          code: "missing_remote_resource_identifier",
+          scope,
+          provider: "railway",
+          message: `${scope} Railway service ${serviceKey} is missing a project name or id.`,
+          details: { service: serviceKey, required: ["projectName", "projectId"] }
+        });
+      }
+      if (!service.serviceName && !service.serviceId) {
+        addFailure(failures, {
+          code: "missing_remote_resource_identifier",
+          scope,
+          provider: "railway",
+          message: `${scope} Railway service ${serviceKey} is missing a service name or id.`,
+          details: { service: serviceKey, required: ["serviceName", "serviceId"] }
+        });
+      }
+    }
+  } catch (error) {
+    addFailure(failures, {
+      code: "provider_resource_check_failed",
+      scope,
+      provider: "deployment-state",
+      message: `${scope} provider resource identifiers could not be validated.`,
+      details: { error: error instanceof Error ? error.message : String(error) }
+    });
+  }
+}
+async function configParityChecks(root, failures) {
+  if (getGitHubAutomationMode() === "stub") {
+    return { name: "config-parity", status: "skipped", detail: "GitHub automation is stubbed." };
+  }
+  const before = failures.length;
+  localConfigCheck(root, "staging", failures);
+  localConfigCheck(root, "prod", failures);
+  await githubRemoteConfigCheck(root, "staging", failures);
+  await githubRemoteConfigCheck(root, "prod", failures);
+  providerResourceIdentifierCheck(root, "staging", failures);
+  providerResourceIdentifierCheck(root, "prod", failures);
+  return {
+    name: "config-parity",
+    status: failures.length > before ? "failed" : "passed",
+    detail: "Checked staging and production config, GitHub names, Railway service identifiers, and D1 identifiers without reading secret values."
+  };
+}
+function migrationCompatibilityChecks(root, failures) {
+  if (!existsSync(resolve(root, "migrations"))) {
+    return {
+      name: "migration-compatibility",
+      status: "skipped",
+      detail: "No migrations directory is present in this workspace."
+    };
+  }
+  const requiredMigrations = [
+    "migrations/0007_site_web_sessions.sql",
+    "migrations/0014_better_auth_integer_timestamps.sql"
+  ];
+  const missing = requiredMigrations.filter((path) => !existsSync(resolve(root, path)));
+  for (const path of missing) {
+    addFailure(failures, {
+      code: "missing_migration_fixture",
+      scope: "@treeseed/market",
+      message: `Migration compatibility check is missing ${path}.`,
+      details: { path }
+    });
+  }
+  return {
+    name: "migration-compatibility",
+    status: missing.length > 0 ? "failed" : "passed",
+    detail: "Checked required legacy web session and Better Auth migration coverage."
+  };
+}
+async function runReleaseCandidateGate(input) {
+  const fingerprint = buildReleaseCandidateFingerprint(input);
+  if (input.allowReuse !== false) {
+    const cached = readCachedReleaseCandidateReport(input.root, fingerprint.key);
+    if (cached?.status === "passed") {
+      return {
+        ...cached,
+        reused: true
+      };
+    }
+  }
+  const selectedPackageNames = [...new Set((input.selectedPackageNames ?? []).map(String))].sort();
+  const plannedVersions = Object.fromEntries(
+    Object.entries(input.plannedVersions).map(([name, version]) => [name, String(version)])
+  );
+  const failures = [];
+  const checks = [];
+  checks.push(dependencyRehearsalChecks(input.root, plannedVersions, selectedPackageNames, failures));
+  checks.push(packageReadinessChecks(input.root, selectedPackageNames, failures));
+  checks.push(await configParityChecks(input.root, failures));
+  checks.push(migrationCompatibilityChecks(input.root, failures));
+  const report = {
+    status: failures.length === 0 ? "passed" : "failed",
+    fingerprint,
+    reused: false,
+    checkedAt: nowIso(),
+    failures,
+    checks
+  };
+  writeReleaseCandidateReport(input.root, report);
+  return report;
+}
+export {
+  buildReleaseCandidateFingerprint,
+  readCachedReleaseCandidateReport,
+  runReleaseCandidateGate,
+  writeReleaseCandidateReport
+};

package/dist/workflow/operations.d.ts

@@ -1,3 +1,4 @@
+import { type ReleaseCandidateReport } from '../operations/services/release-candidate.ts';
 import { resolveTreeseedWorkflowState, type TreeseedWorkflowStatusOptions } from '../workflow-state.ts';
 import { type TreeseedWorkflowRunCommand, type TreeseedWorkflowRunJournal } from './runs.ts';
 import { type TreeseedWorkflowMode } from './session.ts';
@@ -42,6 +43,7 @@ type WorkflowRepoReport = {
     skippedReason: string | null;
     publishWait: Record<string, unknown> | null;
     workflowGates: Array<Record<string, unknown>>;
+    backMerge: Record<string, unknown> | null;
 };
 export declare function workflowStatus(helpers: WorkflowOperationHelpers, input?: TreeseedWorkflowStatusOptions): Promise<TreeseedWorkflowResult<import("../workflow-state.ts").TreeseedWorkflowState>>;
 export declare function workflowCi(helpers: WorkflowOperationHelpers, input?: TreeseedCiInput): Promise<TreeseedWorkflowResult<TreeseedCiResult>>;
@@ -414,6 +416,7 @@ export declare function workflowSave(helpers: WorkflowOperationHelpers, input: T
         runId: null;
         url: null;
     }[];
+    releaseCandidate: ReleaseCandidateReport | null;
 } & {
     finalState?: WorkflowStatePayload;
 }>>;
@@ -551,6 +554,7 @@ export declare function workflowClose(helpers: WorkflowOperationHelpers, input:
             runId: null;
             url: null;
         }[];
+        releaseCandidate: ReleaseCandidateReport | null;
     } & {
         finalState?: WorkflowStatePayload;
     }) | null;
@@ -729,6 +733,7 @@ export declare function workflowStage(helpers: WorkflowOperationHelpers, input:
             runId: null;
             url: null;
         }[];
+        releaseCandidate: ReleaseCandidateReport | null;
     } & {
         finalState?: WorkflowStatePayload;
     }) | null;
@@ -742,6 +747,7 @@ export declare function workflowStage(helpers: WorkflowOperationHelpers, input:
         status: string;
         workflowGates: any;
     };
+    releaseCandidate: ReleaseCandidateReport;
     previewCleanup: {
         performed: boolean;
         state: any;
@@ -855,6 +861,24 @@ export declare function workflowRelease(helpers: WorkflowOperationHelpers, input
     publishWait: never[];
     repos: never[];
     rootRepo: WorkflowRepoReport;
+    releaseCandidate: ReleaseCandidateReport;
+    releaseBackMerge: {
+        status: string;
+        merged: boolean;
+        repoName: string;
+        sourceBranch: string;
+        targetBranch: string;
+        commitSha: string;
+    } | {
+        packageStagingPointersSynced: boolean;
+        packageStagingPointerCommit: string;
+        status: string;
+        merged: boolean;
+        repoName: string;
+        sourceBranch: string;
+        targetBranch: string;
+        commitSha: string;
+    };
     finalBranch: string;
     pushStatus: {
         stagingPushed: boolean;
@@ -914,6 +938,24 @@ export declare function workflowRelease(helpers: WorkflowOperationHelpers, input
     publishWait: Record<string, unknown>[];
     repos: WorkflowRepoReport[];
     rootRepo: WorkflowRepoReport;
+    releaseCandidate: ReleaseCandidateReport;
+    releaseBackMerge: {
+        status: string;
+        merged: boolean;
+        repoName: string;
+        sourceBranch: string;
+        targetBranch: string;
+        commitSha: string;
+    } | {
+        packageStagingPointersSynced: boolean;
+        packageStagingPointerCommit: string;
+        status: string;
+        merged: boolean;
+        repoName: string;
+        sourceBranch: string;
+        targetBranch: string;
+        commitSha: string;
+    };
     finalBranch: string;
     pushStatus: {
         stagingPushed: boolean;

package/dist/workflow/operations.js

@@ -73,6 +73,9 @@ import {
   skippedGitHubActionsGate,
   waitForGitHubActionsGate
 } from "../operations/services/github-actions-verification.js";
+import {
+  runReleaseCandidateGate
+} from "../operations/services/release-candidate.js";
 import { loadCliDeployConfig, packageScriptPath, resolveWranglerBin } from "../operations/services/runtime-tools.js";
 import { runTenantDeployPreflight, runWorkspaceReleasePreflight, runWorkspaceSavePreflight } from "../operations/services/save-deploy-preflight.js";
 import { collectCliPreflight } from "../operations/services/workspace-preflight.js";
@@ -517,7 +520,8 @@ function createRepoReport(name, path, branch, dirty) {
     commitSha: branch ? headCommit(path) : null,
     skippedReason: null,
     publishWait: null,
-    workflowGates: []
+    workflowGates: [],
+    backMerge: null
   };
 }
 function createWorkspaceRootRepoReport(root) {
@@ -1247,6 +1251,58 @@ function assertNoInternalDevReferencesForRepo(root, repoDir, packageNames) {
   throw new Error(`Stable release still contains internal Git/dev dependency references.
 ${rendered}`);
 }
+function backMergeProductionIntoStaging(repoDir, repoName) {
+  syncBranchWithOrigin(repoDir, PRODUCTION_BRANCH);
+  syncBranchWithOrigin(repoDir, STAGING_BRANCH);
+  checkoutBranch(repoDir, STAGING_BRANCH);
+  try {
+    run("git", ["merge-base", "--is-ancestor", `origin/${PRODUCTION_BRANCH}`, "HEAD"], { cwd: repoDir, capture: true });
+    return {
+      status: "up-to-date",
+      merged: false,
+      repoName,
+      sourceBranch: PRODUCTION_BRANCH,
+      targetBranch: STAGING_BRANCH,
+      commitSha: headCommit(repoDir)
+    };
+  } catch {
+  }
+  try {
+    run("git", ["merge", "--no-ff", `origin/${PRODUCTION_BRANCH}`, "-m", `release: back-merge ${PRODUCTION_BRANCH} into ${STAGING_BRANCH}`], { cwd: repoDir });
+  } catch (error) {
+    const report = collectMergeConflictReport(repoDir);
+    throw new TreeseedWorkflowError("release", "merge_conflict", formatMergeConflictReport(report, repoDir, STAGING_BRANCH), {
+      details: { repoName, branch: STAGING_BRANCH, sourceBranch: PRODUCTION_BRANCH, report, originalError: error instanceof Error ? error.message : String(error) },
+      exitCode: 12
+    });
+  }
+  pushBranch(repoDir, STAGING_BRANCH);
+  return {
+    status: "merged",
+    merged: true,
+    repoName,
+    sourceBranch: PRODUCTION_BRANCH,
+    targetBranch: STAGING_BRANCH,
+    commitSha: headCommit(repoDir)
+  };
+}
+function backMergeRootProductionIntoStaging(root, syncPackageStagingHeads) {
+  const gitRoot = repoRoot(root);
+  const backMerge = backMergeProductionIntoStaging(gitRoot, "@treeseed/market");
+  if (!syncPackageStagingHeads) {
+    return backMerge;
+  }
+  syncAllCheckedOutPackageRepos(root, STAGING_BRANCH);
+  const pointerSync = commitAllIfChanged(gitRoot, "release: sync package staging heads");
+  if (pointerSync.committed) {
+    pushBranch(gitRoot, STAGING_BRANCH);
+  }
+  return {
+    ...backMerge,
+    packageStagingPointersSynced: pointerSync.committed,
+    packageStagingPointerCommit: pointerSync.commitSha
+  };
+}
 function collectActiveDevTagReferences(root) {
   return collectInternalDevReferenceIssues(root).map((issue) => devTagFromDependencySpec(issue.spec) ?? (issue.spec.includes("-dev.") ? issue.spec : null)).filter((value) => Boolean(value));
 }
@@ -1263,6 +1319,32 @@ function releasePlanPackageSelection(value) {
     selected: Array.isArray(record.selected) ? record.selected.map(String) : []
   };
 }
+function assertReleaseCandidatePassed(operation, report) {
+  if (report.status === "passed") {
+    return;
+  }
+  const rendered = report.failures.map((failure) => `- ${failure.scope}${failure.provider ? ` ${failure.provider}` : ""}: ${failure.message}`);
+  workflowError(operation, "validation_failed", [
+    "Treeseed release-candidate readiness failed.",
+    ...rendered
+  ].join("\n"), {
+    details: {
+      releaseCandidate: report
+    }
+  });
+}
+async function runReleaseCandidateForPlan(operation, root, plannedRelease, options = {}) {
+  const plannedVersions = plannedRelease.plannedVersions && typeof plannedRelease.plannedVersions === "object" && !Array.isArray(plannedRelease.plannedVersions) ? plannedRelease.plannedVersions : {};
+  const packageSelection = releasePlanPackageSelection(plannedRelease.packageSelection);
+  const report = await runReleaseCandidateGate({
+    root,
+    plannedVersions,
+    selectedPackageNames: packageSelection.selected,
+    allowReuse: options.allowReuse
+  });
+  assertReleaseCandidatePassed(operation, report);
+  return report;
+}
 function buildReleasePlanSnapshot(input) {
   const selectedPackageNames = new Set(input.packageSelection.selected);
   const versionPlan = planWorkspaceReleaseBump(input.level, input.root, input.mode === "recursive-workspace" ? { selectedPackageNames } : {});
@@ -1295,6 +1377,7 @@ function buildReleasePlanSnapshot(input) {
     finalBranch: STAGING_BRANCH,
     plannedSteps: [
       { id: "release-plan", description: "Record immutable release plan and target versions" },
+      { id: "release-candidate", description: "Run exact staging release-candidate readiness checks" },
       { id: "workspace-unlink", description: "Remove local workspace links before stable release install" },
       { id: "prepare-release-metadata", description: "Rewrite package metadata and lockfiles to production dependency mode" },
       ...input.packageReports.filter((report) => selectedPackageNames.has(report.name)).map((report) => ({
@@ -1302,6 +1385,7 @@ function buildReleasePlanSnapshot(input) {
         description: `Release ${report.name} from staging to main and tag ${plannedVersions[report.name] ?? "(planned)"}`
       })),
       { id: "release-root", description: `Release market ${rootVersion}` },
+      { id: "release-back-merge", description: "Back-merge production release history into staging" },
       { id: "cleanup-dev-tags", description: "Clean replaced Treeseed dev tags after stable release" },
       { id: "workspace-link", description: "Restore local workspace links after release syncs back to staging" }
     ],
@@ -2400,6 +2484,7 @@ async function workflowSave(helpers, input) {
               { id: "workspace-unlink", description: "Remove local workspace links before deployment install and lockfile updates" },
               ...repositoryPlan.plannedSteps,
               { id: "lockfile-validation", description: "Validate refreshed package-lock.json files before any save commit is pushed" },
+              ...branch === STAGING_BRANCH ? [{ id: "release-candidate", description: "Run release-candidate readiness checks for the saved staging state" }] : [],
               { id: "workspace-link", description: "Restore local workspace links after save" },
               ...beforeState.branchRole === "feature" && (effectiveInput.preview === true || previewInitialized) ? [{ id: "preview", description: `Refresh preview deployment for ${branch}` }] : []
             ]
@@ -2457,6 +2542,14 @@ async function workflowSave(helpers, input) {
             branch,
             resumable: true
           }] : [],
+          ...branch === STAGING_BRANCH ? [{
+            id: "release-candidate",
+            description: "Run release-candidate readiness checks",
+            repoName: rootRepo.name,
+            repoPath: rootRepo.path,
+            branch,
+            resumable: true
+          }] : [],
           ...beforeState.branchRole === "feature" && (effectiveInput.preview === true || effectiveInput.refreshPreview !== false && previewInitialized) ? [{
             id: "preview",
             description: `Refresh preview ${branch}`,
@@ -2534,6 +2627,19 @@ async function workflowSave(helpers, input) {
             headSha: String(repo.commitSha)
           }))
         ], "hosted", { root, runId: workflowRun.runId }).then((workflowGates) => ({ workflowGates }))) : { workflowGates: [] };
+        const releaseCandidate = branch === STAGING_BRANCH ? await executeJournalStep(root, workflowRun.runId, "release-candidate", () => {
+          const releaseSession = resolveTreeseedWorkflowSession(root);
+          const stagingReleasePlan = buildReleasePlanSnapshot({
+            root,
+            mode,
+            level: effectiveInput.bump ?? "patch",
+            packageSelection: releaseSession.packageSelection,
+            packageReports: savedPackageReports,
+            rootRepo: savedRootRepo,
+            blockers: []
+          });
+          return runReleaseCandidateForPlan("save", root, stagingReleasePlan);
+        }) : null;
         let previewAction = { status: "skipped" };
         if (beforeState.branchRole === "feature" && branch) {
           if (effectiveInput.preview === true) {
@@ -2574,6 +2680,7 @@ async function workflowSave(helpers, input) {
           ciMode: normalizeCiMode(effectiveInput.ciMode, "save"),
           verifyMode: effectiveInput.verifyMode ?? "fast",
           workflowGates: saveWorkflowGates?.workflowGates ?? [],
+          releaseCandidate,
           ...worktreePayload(root, effectiveInput.worktreeMode)
         };
         completeWorkflowRun(root, workflowRun.runId, payload);
@@ -2869,6 +2976,7 @@ async function workflowStage(helpers, input) {
               { id: "merge-root", description: `Squash-merge ${initialSession.branchName ?? "(current task)"} into market staging` },
               { id: "lockfile-validation", description: "Refresh and validate the merged root workspace lockfile before pushing staging" },
               { id: "wait-staging", description: "Wait for exact-SHA staging GitHub Actions gates" },
+              { id: "release-candidate", description: "Run release-candidate readiness checks for the exact staging state" },
               { id: "preview-cleanup", description: "Destroy preview resources" },
               { id: "cleanup-root", description: "Archive and delete the task branch from market" },
               ...checkedOutWorkspacePackageRepos(root).map((pkg) => ({
@@ -2929,6 +3037,7 @@ async function workflowStage(helpers, input) {
           })),
           { id: "merge-root", description: `Merge ${featureBranch} into market staging`, repoName: rootRepo.name, repoPath: rootRepo.path, branch: featureBranch, resumable: true },
           { id: "wait-staging", description: "Wait for exact-SHA staging GitHub Actions gates", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, resumable: true },
+          { id: "release-candidate", description: "Run release-candidate readiness checks", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, resumable: true },
           { id: "preview-cleanup", description: "Destroy preview resources", repoName: rootRepo.name, repoPath: rootRepo.path, branch: featureBranch, resumable: true },
           { id: "cleanup-root", description: `Archive ${featureBranch} in market`, repoName: rootRepo.name, repoPath: rootRepo.path, branch: featureBranch, resumable: true },
           ...packageReports.map((report) => ({
@@ -3060,6 +3169,16 @@ async function workflowStage(helpers, input) {
           status: String(stageWorkflowGateResult?.status ?? "completed"),
           workflowGates: Array.isArray(stageWorkflowGateResult?.workflowGates) ? stageWorkflowGateResult.workflowGates : []
         };
+        const stageReleasePlan = buildReleasePlanSnapshot({
+          root,
+          mode,
+          level: "patch",
+          packageSelection: session.packageSelection,
+          packageReports,
+          rootRepo,
+          blockers: []
+        });
+        const releaseCandidate = await executeJournalStep(root, workflowRun.runId, "release-candidate", () => runReleaseCandidateForPlan("stage", root, stageReleasePlan));
         const previewCleanup = effectiveInput.deletePreview === false ? (skipJournalStep(root, workflowRun.runId, "preview-cleanup", { performed: false }), { performed: false }) : await executeJournalStep(root, workflowRun.runId, "preview-cleanup", () => destroyPreviewIfPresent(root, featureBranch));
         const rootCleanup = await executeJournalStep(root, workflowRun.runId, "cleanup-root", () => {
           const deprecatedTag = createDeprecatedTaskTag(repoDir, featureBranch, `stage: ${message}`);
@@ -3106,6 +3225,7 @@ async function workflowStage(helpers, input) {
           repos: packageReports,
           rootRepo,
           stagingWait,
+          releaseCandidate,
           previewCleanup,
           lockfileValidation: rootMerge?.lockfileValidation ?? null,
           lockfileInstall: rootMerge?.lockfileInstall ?? null,
@@ -3216,6 +3336,7 @@ async function workflowRelease(helpers, input) {
         },
         [
           { id: "release-plan", description: "Record release plan", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, resumable: true },
+          { id: "release-candidate", description: "Run release-candidate readiness checks", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, resumable: true },
           { id: "workspace-unlink", description: "Remove local workspace links before release", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, resumable: true },
           ...mode === "recursive-workspace" ? [{ id: "prepare-release-metadata", description: "Rewrite stable release metadata", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, resumable: true }] : [],
           ...packageReports.filter((report) => selectedPackageNames.has(report.name)).map((report) => ({
@@ -3228,6 +3349,7 @@ async function workflowRelease(helpers, input) {
           })),
           { id: "release-root", description: "Release market repo", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, resumable: true },
           { id: "release-root-gates", description: "Wait for market release GitHub Actions gates", repoName: rootRepo.name, repoPath: rootRepo.path, branch: PRODUCTION_BRANCH, resumable: true },
+          { id: "release-back-merge", description: "Back-merge main into staging", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, resumable: true },
           ...mode === "recursive-workspace" ? [{ id: "cleanup-dev-tags", description: "Clean replaced dev package tags", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, resumable: true }] : []
         ],
         autoResumeRun ? {
@@ -3249,6 +3371,7 @@ async function workflowRelease(helpers, input) {
         const rootVersion = String(releasePlan.rootVersion);
         applyTreeseedEnvironmentToProcess({ tenantRoot: root, scope: "staging", override: true });
         assertReleaseGitHubAutomationReady(root, effectiveSelectedPackageNames);
+        const releaseCandidate = await executeJournalStep(root, workflowRun.runId, "release-candidate", () => runReleaseCandidateForPlan("release", root, releasePlan, { allowReuse: true }));
         if (!isResume) {
           assertSessionBranchSafety("release", session, { requireCleanPackages: true, requireCurrentBranch: true });
           assertCleanWorktree(root);
@@ -3317,6 +3440,7 @@ async function workflowRelease(helpers, input) {
               headSha: String(rootRelease2?.releasedCommit ?? rootRepo.commitSha ?? "")
             }
           ].filter((gate) => gate.headSha), ciMode, { root, runId: workflowRun.runId }).then((workflowGates) => ({ workflowGates })));
+          const releaseBackMerge2 = await executeJournalStep(root, workflowRun.runId, "release-back-merge", () => backMergeRootProductionIntoStaging(root, false));
           const workspaceLinks2 = ensureWorkflowWorkspaceLinks(root, helpers, effectiveInput.workspaceLinks ?? "auto");
           const payload2 = {
             mode,
@@ -3335,6 +3459,8 @@ async function workflowRelease(helpers, input) {
             publishWait: [],
             repos: [],
             rootRepo,
+            releaseCandidate,
+            releaseBackMerge: releaseBackMerge2,
             finalBranch: currentBranch(gitRoot) || STAGING_BRANCH,
             pushStatus: { stagingPushed: true, productionPushed: true, tagPushed: true },
             workspaceLinks: workspaceLinks2,
@@ -3433,13 +3559,15 @@ async function workflowRelease(helpers, input) {
             ], ciMode, { root, runId: workflowRun.runId });
             const publish = workflowGates.find((gate) => gate.workflow === "publish.yml") ?? workflowGates[0] ?? null;
             assertReleaseGitHubWorkflowSucceeded(pkg.name, publish);
+            const backMerge = backMergeProductionIntoStaging(pkg.dir, pkg.name);
             syncBranchWithOrigin(pkg.dir, STAGING_BRANCH);
             return {
               commitSha: mergeResult.commitSha,
               tagName,
               tag,
               publish,
-              workflowGates
+              workflowGates,
+              backMerge
             };
           });
           report.committed = true;
@@ -3449,6 +3577,7 @@ async function workflowRelease(helpers, input) {
           report.commitSha = String(releasedPackage?.commitSha ?? report.commitSha ?? "");
           report.publishWait = releasedPackage?.publish ?? null;
           report.workflowGates = Array.isArray(releasedPackage?.workflowGates) ? releasedPackage.workflowGates : [];
+          report.backMerge = releasedPackage?.backMerge ?? null;
           report.branch = STAGING_BRANCH;
           publishWait.push({
             name: report.name,
@@ -3539,6 +3668,7 @@ async function workflowRelease(helpers, input) {
             headSha: String(rootRelease?.releasedCommit ?? rootRepo.commitSha ?? "")
           }
         ].filter((gate) => gate.headSha), ciMode, { root, runId: workflowRun.runId }).then((workflowGates) => ({ workflowGates })));
+        const releaseBackMerge = await executeJournalStep(root, workflowRun.runId, "release-back-merge", () => backMergeRootProductionIntoStaging(root, true));
         const devTagCleanupMode = effectiveInput.devTagCleanup ?? "safe-after-release";
         const devTagCleanup = devTagCleanupMode === "off" ? (skipJournalStep(root, workflowRun.runId, "cleanup-dev-tags", { status: "skipped", reason: "disabled" }), { status: "skipped", reason: "disabled" }) : await executeJournalStep(root, workflowRun.runId, "cleanup-dev-tags", () => {
           const activeDevTags = collectActiveDevTagReferences(root);
@@ -3585,6 +3715,8 @@ async function workflowRelease(helpers, input) {
           publishWait,
           repos: packageReports,
           rootRepo,
+          releaseCandidate,
+          releaseBackMerge,
           finalBranch: currentBranch(gitRoot) || STAGING_BRANCH,
           pushStatus: {
             stagingPushed: true,

package/dist/workflow/runs.js

@@ -238,6 +238,15 @@ function selectedReleasePackageNames(plan) {
   const selected = Array.isArray(selection?.selected) ? selection.selected.filter((name) => typeof name === "string") : [];
   return selected;
 }
+function isReleaseGateOnlyCompletion(journal) {
+  if (journal.command !== "release") return false;
+  const releaseRoot = journal.steps.find((step) => step.id === "release-root");
+  if (releaseRoot?.status !== "completed") return false;
+  const releaseRootData = stringRecord(releaseRoot.data);
+  if (typeof releaseRootData?.releasedCommit !== "string") return false;
+  const pendingStep = journal.steps.find((step) => step.status === "pending");
+  return pendingStep?.id === "release-root-gates" || pendingStep?.id === "release-back-merge" || pendingStep?.id === "cleanup-dev-tags";
+}
 function classifyWorkflowRunJournal(journal, options = {}) {
   const reasons = [];
   const now = options.now ?? nowIso();
@@ -273,7 +282,8 @@ function classifyWorkflowRunJournal(journal, options = {}) {
   if (options.currentBranch && journal.session.branchName && options.currentBranch !== journal.session.branchName) {
     reasons.push(`current branch ${options.currentBranch} does not match journal branch ${journal.session.branchName}`);
   }
-  if (journal.command === "release" && options.currentHeads) {
+  const releaseGateOnlyCompletion = isReleaseGateOnlyCompletion(journal);
+  if (journal.command === "release" && options.currentHeads && !releaseGateOnlyCompletion) {
     const releasePlan = stringRecord(journal.steps.find((step) => step.id === "release-plan")?.data);
     if (releasePlan) {
       const rootHead = options.currentHeads["@treeseed/market"];
@@ -292,7 +302,7 @@ function classifyWorkflowRunJournal(journal, options = {}) {
   }
   return {
     state: reasons.length > 0 ? "stale" : "resumable",
-    reasons: reasons.length > 0 ? reasons : ["workflow run can be resumed"],
+    reasons: reasons.length > 0 ? reasons : releaseGateOnlyCompletion ? ["release commits already exist; remaining release gates can be rechecked"] : ["workflow run can be resumed"],
     classifiedAt: now
   };
 }

package/dist/workflow-state.d.ts

@@ -183,6 +183,12 @@ export type TreeseedWorkflowState = {
         startupPassphraseConfigured: boolean;
     };
     releaseReady: boolean;
+    releaseHistory: {
+        stagingAheadMain: number | null;
+        stagingBehindMain: number | null;
+        backMerged: boolean | null;
+        detail: string;
+    };
     readiness: {
         local: {
             ready: boolean;

package/dist/workflow-state.js

@@ -255,6 +255,38 @@ function safeHeadCommit(repoDir) {
     return null;
   }
 }
+function safeReleaseHistory(repoDir) {
+  if (!repoDir) {
+    return {
+      stagingAheadMain: null,
+      stagingBehindMain: null,
+      backMerged: null,
+      detail: "Repository root is unavailable."
+    };
+  }
+  try {
+    const output = run("git", ["rev-list", "--left-right", "--count", "staging...main"], { cwd: repoDir, capture: true }).trim();
+    const [aheadRaw, behindRaw] = output.split(/\s+/u);
+    const stagingAheadMain = Number.parseInt(aheadRaw ?? "", 10);
+    const stagingBehindMain = Number.parseInt(behindRaw ?? "", 10);
+    if (!Number.isFinite(stagingAheadMain) || !Number.isFinite(stagingBehindMain)) {
+      throw new Error("invalid rev-list output");
+    }
+    return {
+      stagingAheadMain,
+      stagingBehindMain,
+      backMerged: stagingBehindMain === 0,
+      detail: stagingBehindMain === 0 ? "Staging contains current main release history." : `Staging is missing ${stagingBehindMain} main commit${stagingBehindMain === 1 ? "" : "s"}.`
+    };
+  } catch {
+    return {
+      stagingAheadMain: null,
+      stagingBehindMain: null,
+      backMerged: null,
+      detail: "Could not compare staging and main release history."
+    };
+  }
+}
 function resolveLocalStatusUrl(deployConfig) {
   return deployConfig.surfaces?.web?.localBaseUrl ?? deployConfig.surfaces?.api?.localBaseUrl ?? Object.values(deployConfig.services ?? {}).find((service) => service?.enabled !== false && service.environments?.local?.baseUrl)?.environments?.local?.baseUrl ?? null;
 }
@@ -472,6 +504,7 @@ function resolveTreeseedWorkflowState(cwd, options = {}) {
       startupPassphraseConfigured: Boolean(process.env.TREESEED_KEY_PASSPHRASE?.trim())
     },
     releaseReady: branchRole === "staging" && !dirtyWorktree,
+    releaseHistory: safeReleaseHistory(root),
     readiness: {
       local: { ready: false, blockers: [], warnings: [] },
       staging: { ready: false, blockers: [], warnings: [] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeseed/sdk",
-  "version": "0.6.19",
+  "version": "0.6.21",
   "description": "Shared Treeseed SDK for content-backed and D1-backed object models.",
   "license": "AGPL-3.0-only",
   "repository": {