@treeseed/sdk 0.6.9 → 0.6.10

package/dist/workflow/operations.js

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { isAbsolute, relative, resolve } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import {
   applyTreeseedEnvironmentToProcess,
@@ -23,7 +23,7 @@ import {
   setTreeseedRemoteSession,
   writeTreeseedMachineConfig
 } from "../operations/services/config-runtime.js";
-import { formatTreeseedDependencyFailureDetails, installTreeseedDependencies } from "../managed-dependencies.js";
+import { collectTreeseedToolStatus, formatTreeseedDependencyFailureDetails, installTreeseedDependencies } from "../managed-dependencies.js";
 import { ControlPlaneClient } from "../control-plane-client.js";
 import { exportTreeseedCodebase } from "../operations/services/export-runtime.js";
 import {
@@ -46,6 +46,7 @@ import {
   assertFeatureBranch,
   branchExists,
   checkoutBranch,
+  checkoutDetachedOriginBranch,
   checkoutTaskBranchFromStaging,
   createDeprecatedTaskTag,
   deleteLocalBranch,
@@ -59,14 +60,13 @@ import {
   prepareReleaseBranches,
   PRODUCTION_BRANCH,
   pushBranch,
+  pushHeadToBranch,
   remoteBranchExists,
   STAGING_BRANCH,
   squashMergeBranchIntoStaging,
-  syncBranchWithOrigin,
-  waitForStagingAutomation
+  syncBranchWithOrigin
 } from "../operations/services/git-workflow.js";
 import { getGitHubAutomationMode, resolveGitHubRepositorySlug, waitForGitHubWorkflowCompletion } from "../operations/services/github-automation.js";
-import { createGitHubApiClient } from "../operations/services/github-api.js";
 import { loadCliDeployConfig, packageScriptPath, resolveWranglerBin } from "../operations/services/runtime-tools.js";
 import { runTenantDeployPreflight, runWorkspaceSavePreflight } from "../operations/services/save-deploy-preflight.js";
 import { collectCliPreflight } from "../operations/services/workspace-preflight.js";
@@ -111,8 +111,13 @@ import { resolveTreeseedWorkflowState } from "../workflow-state.js";
 import { createTreeseedReconcileRegistry, deriveTreeseedDesiredUnits, filterTreeseedDesiredUnitsByBootstrapSystems, planTreeseedReconciliation, resolveTreeseedBootstrapSelection, reconcileTreeseedTarget } from "../reconcile/index.js";
 import {
   acquireWorkflowLock,
+  archiveWorkflowRun,
+  cacheWorkflowGateResult,
+  classifyWorkflowRunJournal,
+  classifyWorkflowRunJournals,
   createWorkflowRunJournal,
   generateWorkflowRunId,
+  getCachedSuccessfulWorkflowGate,
   inspectWorkflowLock,
   listInterruptedWorkflowRuns,
   listWorkflowRunJournals,
@@ -129,6 +134,14 @@ import {
   classifyTreeseedBranchRole,
   resolveTreeseedWorkflowPaths
 } from "./policy.js";
+import {
+  effectiveWorkflowWorktreeMode,
+  ensureManagedWorkflowWorktree,
+  isManagedWorkflowWorktree,
+  managedWorkflowWorktreeMetadata,
+  plannedManagedWorkflowWorktreePath,
+  removeManagedWorkflowWorktree
+} from "./worktrees.js";
 class TreeseedWorkflowError extends Error {
   code;
   operation;
@@ -161,8 +174,64 @@ function ensureWorkflowWorkspaceLinks(root, helpers, mode = "auto") {
   if (report.created.length > 0) {
     helpers.write(`[workspace][link] Linked ${report.created.length} local workspace package paths.`);
   }
+  ensureWorkflowWorkspacePackageArtifacts(root, helpers);
+  ensureWorkflowCommandBins(root, helpers);
   return report;
 }
+function readPackageScript(root, packageDir, scriptName) {
+  try {
+    const packageJson = JSON.parse(readFileSync(resolve(root, packageDir, "package.json"), "utf8"));
+    const scripts = packageJson.scripts && typeof packageJson.scripts === "object" && !Array.isArray(packageJson.scripts) ? packageJson.scripts : null;
+    const script = scripts?.[scriptName];
+    return typeof script === "string" && script.trim() ? script : null;
+  } catch {
+    return null;
+  }
+}
+function ensureWorkflowWorkspacePackageArtifacts(root, helpers) {
+  const packages = [
+    { name: "@treeseed/sdk", dir: "packages/sdk", artifacts: ["dist/workflow-support.js", "dist/plugin-default.js", "dist/platform/env.yaml"] },
+    { name: "@treeseed/core", dir: "packages/core", artifacts: ["dist/api.js", "dist/plugin-default.js"] },
+    { name: "@treeseed/cli", dir: "packages/cli", artifacts: ["dist/cli/main.js"] }
+  ];
+  for (const entry of packages) {
+    const packageDir = resolve(root, entry.dir);
+    if (!existsSync(resolve(packageDir, "package.json"))) continue;
+    if (!readPackageScript(root, entry.dir, "build:dist")) continue;
+    const missing = entry.artifacts.filter((artifact) => !existsSync(resolve(packageDir, artifact)));
+    if (missing.length === 0) continue;
+    helpers.write(`[workspace][build] Building ${entry.name} artifacts for local workspace links.`);
+    run("npm", ["--prefix", packageDir, "run", "build:dist"], { cwd: root });
+  }
+}
+function ensureWorkflowCommandBins(root, helpers) {
+  const cliBin = resolve(root, "node_modules/@treeseed/cli/dist/cli/main.js");
+  if (!existsSync(cliBin)) return;
+  const binDir = resolve(root, "node_modules/.bin");
+  mkdirSync(binDir, { recursive: true });
+  for (const name of ["trsd", "treeseed"]) {
+    const linkPath = resolve(binDir, name);
+    const target = relative(dirname(linkPath), cliBin) || cliBin;
+    try {
+      const stat = lstatSync(linkPath);
+      if (stat.isSymbolicLink()) {
+        const currentTarget = readlinkSync(linkPath);
+        if (currentTarget === target || resolve(dirname(linkPath), currentTarget) === cliBin) {
+          continue;
+        }
+        rmSync(linkPath, { force: true });
+      } else {
+        continue;
+      }
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+    symlinkSync(target, linkPath);
+    helpers.write(`[workspace][link] Linked ${name} command shim.`);
+  }
+}
 function unlinkWorkflowWorkspaceLinks(root, helpers, mode = "auto") {
   if (!shouldManageWorkspaceLinks(mode, helpers.context.env)) {
     return inspectWorkspaceDependencyMode(root, { mode: "off", env: helpers.context.env });
@@ -173,6 +242,163 @@ function unlinkWorkflowWorkspaceLinks(root, helpers, mode = "auto") {
   }
   return report;
 }
+function normalizeCiMode(mode, operation) {
+  if (mode === "hosted" || mode === "off") return mode;
+  return operation === "save" ? "off" : "hosted";
+}
+function normalizeSaveVerifyMode(mode) {
+  switch (mode) {
+    case "skip":
+    case "fast":
+    case void 0:
+      return "skip";
+    case "local":
+    case "local-only":
+      return "local-only";
+    case "hosted":
+      return "skip";
+    case "both":
+    case "action-first":
+      return "action-first";
+    default:
+      return "skip";
+  }
+}
+function shouldUseHostedSaveCi(input) {
+  return normalizeCiMode(input.ciMode, "save") === "hosted" || input.verifyMode === "hosted" || input.verifyMode === "both";
+}
+function worktreePayload(root, requestedMode) {
+  const metadata = managedWorkflowWorktreeMetadata(root);
+  return {
+    worktreeMode: requestedMode ?? "auto",
+    managedWorktree: metadata,
+    worktreePath: metadata?.worktreePath ?? null,
+    primaryRoot: metadata?.primaryRoot ?? null
+  };
+}
+function helpersForCwd(helpers, cwd) {
+  return {
+    ...helpers,
+    context: {
+      ...helpers.context,
+      cwd
+    },
+    cwd: () => cwd
+  };
+}
+function shouldDispatchSwitchToManagedWorktree(root, input, env) {
+  return !isManagedWorkflowWorktree(root) && effectiveWorkflowWorktreeMode(input.worktreeMode, env) === "on";
+}
+function skippedWorkflowGate(gate, reason) {
+  return {
+    name: gate.name,
+    repository: gate.repository ?? null,
+    workflow: gate.workflow,
+    branch: gate.branch,
+    headSha: gate.headSha,
+    status: "skipped",
+    reason,
+    conclusion: null,
+    runId: null,
+    url: null
+  };
+}
+function workflowGateFailureMessage(gate, result) {
+  const repository = String(result.repository ?? gate.repository ?? gate.name);
+  const runId = typeof result.runId === "number" || typeof result.runId === "string" ? String(result.runId) : "";
+  const url = typeof result.url === "string" && result.url ? `
+${result.url}` : "";
+  const failedJobs = Array.isArray(result.failedJobs) ? result.failedJobs.map((job) => stringRecord(job)?.name).filter((name) => typeof name === "string" && name.length > 0) : [];
+  const jobLine = failedJobs.length > 0 ? `
+Failed jobs: ${failedJobs.join(", ")}` : "";
+  const command = runId ? `
+Inspect with: gh run view ${runId} --repo ${repository} --log-failed` : "";
+  return `${gate.name} ${gate.workflow} completed with conclusion ${String(result.conclusion ?? "unknown")} in ${repository}.${url}${jobLine}${command}`;
+}
+function assertHostedGitHubWorkflowAuthReady(operation, root) {
+  if (getGitHubAutomationMode() === "stub") {
+    return null;
+  }
+  const tools = collectTreeseedToolStatus({
+    tenantRoot: root,
+    env: process.env
+  });
+  const github = tools.auth.github;
+  if (!github.authenticated) {
+    const command = github.command.length > 0 ? github.command.join(" ") : "npx trsd tools --json";
+    workflowError(
+      operation,
+      "github_auth_unavailable",
+      [
+        "Treeseed hosted GitHub workflow gates require an authenticated managed GitHub CLI.",
+        github.detail,
+        `Managed gh check: ${command}`,
+        "Remediation:",
+        ...github.remediation.map((item) => `- ${item}`)
+      ].join("\n"),
+      {
+        details: {
+          toolsHome: tools.toolsHome,
+          ghConfigDir: tools.ghConfigDir,
+          github,
+          tools: tools.tools
+        }
+      }
+    );
+  }
+  return tools;
+}
+async function waitForWorkflowGates(operation, gates, ciMode, options = {}) {
+  if (ciMode === "off" || process.env.TREESEED_STAGE_WAIT_MODE === "skip") {
+    return gates.map((gate) => skippedWorkflowGate(gate, ciMode === "off" ? "disabled" : "stubbed"));
+  }
+  if (gates.length === 0) {
+    return [];
+  }
+  assertHostedGitHubWorkflowAuthReady(operation, options.root ?? gates[0].repoPath);
+  const results = [];
+  for (const gate of gates) {
+    if (options.root && options.runId) {
+      const cached = getCachedSuccessfulWorkflowGate(options.root, options.runId, {
+        repository: gate.repository ?? null,
+        workflow: gate.workflow,
+        headSha: gate.headSha,
+        branch: gate.branch
+      });
+      if (cached) {
+        results.push({
+          ...cached.result,
+          name: gate.name,
+          cached: true
+        });
+        continue;
+      }
+    }
+    const result = await waitForGitHubWorkflowCompletion(gate.repoPath, {
+      repository: gate.repository,
+      workflow: gate.workflow,
+      headSha: gate.headSha,
+      branch: gate.branch
+    });
+    const normalized = {
+      name: gate.name,
+      ...result,
+      workflow: String(result.workflow ?? gate.workflow),
+      branch: String(result.branch ?? gate.branch),
+      headSha: String(result.headSha ?? gate.headSha)
+    };
+    if (normalized.status === "completed" && normalized.conclusion !== "success") {
+      workflowError(operation, "github_workflow_failed", workflowGateFailureMessage(gate, normalized), {
+        details: { gate, workflow: normalized }
+      });
+    }
+    if (options.root && options.runId && normalized.status === "completed" && normalized.conclusion === "success") {
+      cacheWorkflowGateResult(options.root, options.runId, normalized);
+    }
+    results.push(normalized);
+  }
+  return results;
+}
 function ensureTreeseedCommandReadiness(root) {
   if (getGitHubAutomationMode() === "stub") {
     return {
@@ -295,7 +521,8 @@ function createRepoReport(name, path, branch, dirty) {
     tagName: null,
     commitSha: branch ? headCommit(path) : null,
     skippedReason: null,
-    publishWait: null
+    publishWait: null,
+    workflowGates: []
   };
 }
 function createWorkspaceRootRepoReport(root) {
@@ -712,6 +939,10 @@ function findAutoResumableSaveRun(root, branch) {
   if (!branch) return null;
   return listInterruptedWorkflowRuns(root).find((journal) => journal.command === "save" && journal.resumable && journal.session.branchName === branch) ?? null;
 }
+function findAutoResumableTaskRun(root, command, branch) {
+  if (!branch) return null;
+  return listInterruptedWorkflowRuns(root).find((journal) => journal.command === command && journal.resumable && journal.session.branchName === branch) ?? null;
+}
 function stringRecord(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
@@ -1033,7 +1264,7 @@ function assertReleaseGitHubAutomationReady(root, selectedPackageNames) {
   if (process.env.TREESEED_GITHUB_AUTOMATION_MODE === "stub") {
     return;
   }
-  createGitHubApiClient();
+  assertHostedGitHubWorkflowAuthReady("release", root);
   for (const pkg of checkedOutWorkspacePackageRepos(root)) {
     if (!selectedPackageNames.has(pkg.name)) continue;
     resolveGitHubRepositorySlug(pkg.dir);
@@ -1101,6 +1332,14 @@ function previewStateFor(tenantRoot, branchName) {
     target: createBranchPreviewDeployTarget(branchName)
   });
 }
+function branchPreviewInitialized(tenantRoot, branchName) {
+  if (!branchName) return false;
+  try {
+    return previewStateFor(tenantRoot, branchName).readiness?.initialized === true;
+  } catch {
+    return false;
+  }
+}
 async function deployBranchPreview(tenantRoot, branchName, context, { initialize }) {
   applyTreeseedEnvironmentToProcess({ tenantRoot, scope: "staging", override: true });
   assertTreeseedCommandEnvironment({ tenantRoot, scope: "staging", purpose: "deploy" });
@@ -1710,7 +1949,10 @@ async function workflowExport(helpers, input = {}) {
   return await withContextEnv(helpers.context.env, async () => {
     const directory = resolve(helpers.context.cwd ?? helpers.cwd(), input.directory ?? ".");
     const exported = await exportTreeseedCodebase({ directory });
-    return buildWorkflowResult("export", exported.tenantRoot, exported);
+    return buildWorkflowResult("export", exported.tenantRoot, {
+      ...exported,
+      ...worktreePayload(exported.tenantRoot, input.worktreeMode)
+    });
   });
 }
 async function workflowSwitch(helpers, input) {
@@ -1725,6 +1967,27 @@ async function workflowSwitch(helpers, input) {
       }
       const preview = input.preview === true;
       const executionMode = normalizeExecutionMode(input);
+      if (executionMode !== "plan" && shouldDispatchSwitchToManagedWorktree(root, input, helpers.context.env)) {
+        const managed = ensureManagedWorkflowWorktree({
+          root,
+          branchName,
+          mode: input.worktreeMode,
+          env: helpers.context.env
+        });
+        const result = await workflowSwitch(helpersForCwd(helpers, managed.worktreePath), {
+          ...input,
+          worktreeMode: "off"
+        });
+        return {
+          ...result,
+          payload: {
+            ...result.payload,
+            worktreeMode: input.worktreeMode ?? "auto",
+            worktreePath: managed.worktreePath,
+            managedWorktree: managed
+          }
+        };
+      }
       const mode = session.mode;
       const repoDir = session.gitRoot;
       const rootRepo = createWorkspaceRootRepoReport(root);
@@ -1747,6 +2010,8 @@ async function workflowSwitch(helpers, input) {
             rootRepo,
             repos: packageReports,
             previewRequested: preview,
+            worktreeMode: input.worktreeMode ?? "auto",
+            worktreePath: effectiveWorkflowWorktreeMode(input.worktreeMode, helpers.context.env) === "on" ? plannedManagedWorkflowWorktreePath(root, branchName) : null,
             blockers: dirtyRepos.length > 0 ? [`Clean worktrees required: ${dirtyRepos.join(", ")}`] : [],
             plannedSteps: [
               { id: "switch-root", description: `Switch market repo to ${branchName}` },
@@ -1772,7 +2037,7 @@ async function workflowSwitch(helpers, input) {
       const workflowRun = acquireWorkflowRun(
         "switch",
         session,
-        { branch: branchName, preview },
+        { branch: branchName, preview, worktreeMode: input.worktreeMode ?? "auto" },
         [
           { id: "switch-root", description: `Switch market repo to ${branchName}`, repoName: rootRepo.name, repoPath: rootRepo.path, branch: branchName, resumable: true },
           ...packageReports.map((report) => ({
@@ -1849,6 +2114,7 @@ async function workflowSwitch(helpers, input) {
           },
           previewResult,
           workspaceLinks,
+          ...worktreePayload(root, input.worktreeMode),
           preconditions: {
             cleanWorktreeRequired: true,
             baseBranch: STAGING_BRANCH
@@ -1975,6 +2241,7 @@ async function workflowSave(helpers, input) {
       const effectiveInput = autoResumeRun ? autoResumeRun.input : input;
       const message = String(effectiveInput.message ?? "").trim();
       const optionsHotfix = effectiveInput.hotfix === true;
+      const previewInitialized = branchPreviewInitialized(root, branch);
       applyTreeseedEnvironmentToProcess({ tenantRoot: root, scope, override: true });
       if (!branch) {
         workflowError("save", "validation_failed", "Treeseed save requires an active git branch.");
@@ -2002,7 +2269,7 @@ async function workflowSave(helpers, input) {
           devDependencyReferenceMode: effectiveInput.devDependencyReferenceMode ?? "git-tag",
           gitDependencyProtocol: effectiveInput.gitDependencyProtocol ?? "preserve-origin",
           gitRemoteWriteMode: effectiveInput.gitRemoteWriteMode ?? "ssh-pushurl",
-          verifyMode: effectiveInput.verifyMode ?? (effectiveInput.verify === false ? "skip" : "action-first"),
+          verifyMode: normalizeSaveVerifyMode(effectiveInput.verify === false ? "skip" : effectiveInput.verifyMode),
           commitMessageMode: effectiveInput.commitMessageMode ?? "auto"
         });
         const workspaceLinks = inspectWorkspaceDependencyMode(root, { mode: effectiveInput.workspaceLinks ?? "auto", env: helpers.context.env });
@@ -2024,6 +2291,9 @@ async function workflowSave(helpers, input) {
               failure: planAutoResumeRun.failure
             } : null,
             workspaceLinks,
+            ciMode: normalizeCiMode(effectiveInput.ciMode, "save"),
+            verifyMode: effectiveInput.verifyMode ?? "fast",
+            ...worktreePayload(root, effectiveInput.worktreeMode),
             repositoryPlan,
             waves: repositoryPlan.waves,
             plannedVersions: repositoryPlan.plannedVersions,
@@ -2032,7 +2302,7 @@ async function workflowSave(helpers, input) {
               ...repositoryPlan.plannedSteps,
               { id: "lockfile-validation", description: "Validate refreshed package-lock.json files before any save commit is pushed" },
               { id: "workspace-link", description: "Restore local workspace links after save" },
-              ...beforeState.branchRole === "feature" && (effectiveInput.preview === true || beforeState.preview.enabled) ? [{ id: "preview", description: `Refresh preview deployment for ${branch}` }] : []
+              ...beforeState.branchRole === "feature" && (effectiveInput.preview === true || previewInitialized) ? [{ id: "preview", description: `Refresh preview deployment for ${branch}` }] : []
             ]
           },
           {
@@ -2065,7 +2335,9 @@ async function workflowSave(helpers, input) {
           devDependencyReferenceMode: effectiveInput.devDependencyReferenceMode ?? "git-tag",
           gitDependencyProtocol: effectiveInput.gitDependencyProtocol ?? "preserve-origin",
           gitRemoteWriteMode: effectiveInput.gitRemoteWriteMode ?? "ssh-pushurl",
-          verifyMode: effectiveInput.verifyMode ?? (effectiveInput.verify === false ? "skip" : "action-first"),
+          verifyMode: effectiveInput.verifyMode ?? (effectiveInput.verify === false ? "skip" : "fast"),
+          ciMode: effectiveInput.ciMode ?? "auto",
+          worktreeMode: effectiveInput.worktreeMode ?? "auto",
           commitMessageMode: effectiveInput.commitMessageMode ?? "auto",
           workspaceLinks: effectiveInput.workspaceLinks ?? "auto"
         },
@@ -2078,7 +2350,15 @@ async function workflowSave(helpers, input) {
             branch,
             resumable: true
           },
-          ...beforeState.branchRole === "feature" && (effectiveInput.preview === true || effectiveInput.refreshPreview !== false && beforeState.preview.enabled) ? [{
+          ...shouldUseHostedSaveCi(effectiveInput) ? [{
+            id: "hosted-ci",
+            description: `Wait for hosted save workflows on ${branch}`,
+            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}`,
             repoName: rootRepo.name,
@@ -2112,7 +2392,7 @@ async function workflowSave(helpers, input) {
               devDependencyReferenceMode: effectiveInput.devDependencyReferenceMode ?? "git-tag",
               gitDependencyProtocol: effectiveInput.gitDependencyProtocol ?? "preserve-origin",
               gitRemoteWriteMode: effectiveInput.gitRemoteWriteMode ?? "ssh-pushurl",
-              verifyMode: effectiveInput.verifyMode ?? (effectiveInput.verify === false ? "skip" : "action-first"),
+              verifyMode: normalizeSaveVerifyMode(effectiveInput.verify === false ? "skip" : effectiveInput.verifyMode),
               commitMessageMode: effectiveInput.commitMessageMode ?? "auto",
               workflowRunId: workflowRun.runId,
               onProgress: (line, stream) => helpers.write(line, stream)
@@ -2139,14 +2419,30 @@ async function workflowSave(helpers, input) {
             lockfileValidation: repo.lockfileValidation
           }))
         };
+        const saveWorkflowGates = shouldUseHostedSaveCi(effectiveInput) ? await executeJournalStep(root, workflowRun.runId, "hosted-ci", () => waitForWorkflowGates("save", [
+          ...savedRootRepo.pushed && savedRootRepo.commitSha && branch ? [{
+            name: savedRootRepo.name,
+            repoPath: savedRootRepo.path,
+            workflow: "verify.yml",
+            branch,
+            headSha: savedRootRepo.commitSha
+          }] : [],
+          ...savedPackageReports.filter((repo) => repo.pushed && repo.commitSha && repo.branch).map((repo) => ({
+            name: repo.name,
+            repoPath: repo.path,
+            workflow: "verify.yml",
+            branch: String(repo.branch),
+            headSha: String(repo.commitSha)
+          }))
+        ], "hosted", { root, runId: workflowRun.runId }).then((workflowGates) => ({ workflowGates }))) : { workflowGates: [] };
         let previewAction = { status: "skipped" };
         if (beforeState.branchRole === "feature" && branch) {
           if (effectiveInput.preview === true) {
             previewAction = {
-              status: beforeState.preview.enabled ? "refreshed" : "created",
-              details: await executeJournalStep(root, workflowRun.runId, "preview", () => deployBranchPreview(root, branch, helpers.context, { initialize: !beforeState.preview.enabled }))
+              status: previewInitialized ? "refreshed" : "created",
+              details: await executeJournalStep(root, workflowRun.runId, "preview", () => deployBranchPreview(root, branch, helpers.context, { initialize: !previewInitialized }))
             };
-          } else if (effectiveInput.refreshPreview !== false && beforeState.preview.enabled) {
+          } else if (effectiveInput.refreshPreview !== false && previewInitialized) {
             previewAction = {
               status: "refreshed",
               details: await executeJournalStep(root, workflowRun.runId, "preview", () => deployBranchPreview(root, branch, helpers.context, { initialize: false }))
@@ -2175,7 +2471,11 @@ async function workflowSave(helpers, input) {
           mergeConflict: null,
           workspaceLinks,
           commandReadiness,
-          lockfileValidation
+          lockfileValidation,
+          ciMode: normalizeCiMode(effectiveInput.ciMode, "save"),
+          verifyMode: effectiveInput.verifyMode ?? "fast",
+          workflowGates: saveWorkflowGates?.workflowGates ?? [],
+          ...worktreePayload(root, effectiveInput.worktreeMode)
         };
         completeWorkflowRun(root, workflowRun.runId, payload);
         return buildWorkflowResult(
@@ -2232,9 +2532,13 @@ async function workflowClose(helpers, input) {
     return await withContextEnv(helpers.context.env, async () => {
       const tenantRoot = resolveProjectRootOrThrow("close", helpers.cwd());
       const root = workspaceRoot(tenantRoot);
-      const message = ensureMessage("close", input.message, "a close reason");
       const executionMode = normalizeExecutionMode(input);
       const session = resolveTreeseedWorkflowSession(root);
+      const explicitResumeRunId = helpers.context.workflow?.resumeRunId ?? null;
+      const autoResumeRun = executionMode === "execute" && !explicitResumeRunId ? findAutoResumableTaskRun(root, "close", session.branchName) : null;
+      const planAutoResumeRun = executionMode === "plan" ? findAutoResumableTaskRun(root, "close", session.branchName) : null;
+      const effectiveInput = autoResumeRun ? autoResumeRun.input : input;
+      const message = ensureMessage("close", effectiveInput.message, "a close reason");
       if (executionMode === "plan") {
         const branchName = session.branchName;
         const blockers = session.branchRole !== "feature" ? ["Close only applies to task branches."] : [];
@@ -2245,18 +2549,26 @@ async function workflowClose(helpers, input) {
             mode: session.mode,
             branchName,
             message,
+            autoResumeCandidate: planAutoResumeRun ? {
+              runId: planAutoResumeRun.runId,
+              branch: planAutoResumeRun.session.branchName,
+              failure: planAutoResumeRun.failure
+            } : null,
+            ...worktreePayload(root, effectiveInput.worktreeMode),
             autoSaveRequired: session.rootRepo.dirty || session.packageRepos.some((repo) => repo.dirty),
             repos: createWorkspacePackageReports(root),
             rootRepo: createWorkspaceRootRepoReport(root),
             blockers,
             plannedSteps: [
+              { id: "workspace-unlink", description: "Remove local workspace links before task cleanup" },
               { id: "preview-cleanup", description: `Destroy preview resources for ${branchName ?? "(current task)"}` },
               { id: "cleanup-root", description: `Archive and delete ${branchName ?? "(current task)"} in market` },
               ...checkedOutWorkspacePackageRepos(root).map((pkg) => ({
                 id: `cleanup-${pkg.name}`,
                 description: `Archive and delete ${branchName ?? "(current task)"} in ${pkg.name}`
               })),
-              { id: "workspace-link", description: "Restore local workspace links on the final branch" }
+              { id: "workspace-link", description: "Restore local workspace links on the final branch" },
+              ...isManagedWorkflowWorktree(root) ? [{ id: "worktree-cleanup", description: "Remove managed workflow worktree" }] : []
             ]
           },
           {
@@ -2267,12 +2579,10 @@ async function workflowClose(helpers, input) {
           }
         );
       }
-      unlinkWorkflowWorkspaceLinks(root, helpers, input.workspaceLinks ?? "auto");
       const autoSave = await maybeAutoSaveCurrentTaskBranch(helpers, "close", {
         message,
-        autoSave: input.autoSave
+        autoSave: effectiveInput.autoSave
       });
-      unlinkWorkflowWorkspaceLinks(root, helpers, input.workspaceLinks ?? "auto");
       const activeSession = resolveTreeseedWorkflowSession(root);
       const featureBranch = assertFeatureBranch(root);
       const mode = activeSession.mode;
@@ -2288,8 +2598,14 @@ async function workflowClose(helpers, input) {
       const workflowRun = acquireWorkflowRun(
         "close",
         activeSession,
-        { message, deletePreview: input.deletePreview !== false, deleteBranch: input.deleteBranch !== false },
+        {
+          message,
+          deletePreview: effectiveInput.deletePreview !== false,
+          deleteBranch: effectiveInput.deleteBranch !== false,
+          worktreeMode: effectiveInput.worktreeMode ?? "auto"
+        },
         [
+          { id: "workspace-unlink", description: "Remove local workspace links", repoName: rootRepo.name, repoPath: rootRepo.path, branch: featureBranch, resumable: true },
           { id: "preview-cleanup", description: `Destroy preview resources for ${featureBranch}`, 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) => ({
@@ -2299,23 +2615,35 @@ async function workflowClose(helpers, input) {
             repoPath: report.path,
             branch: featureBranch,
             resumable: true
-          }))
+          })),
+          { id: "workspace-link", description: "Restore local workspace links", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, resumable: true },
+          ...isManagedWorkflowWorktree(root) ? [{ id: "worktree-cleanup", description: "Remove managed workflow worktree", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, resumable: false }] : []
         ],
-        helpers.context
+        autoResumeRun ? {
+          ...helpers.context,
+          workflow: {
+            ...helpers.context.workflow ?? {},
+            resumeRunId: autoResumeRun.runId
+          }
+        } : helpers.context
       );
+      if (autoResumeRun) {
+        helpers.write(`[workflow][resume] Resuming interrupted close ${autoResumeRun.runId} on ${featureBranch}.`);
+      }
       try {
-        const previewCleanup = input.deletePreview === false ? (skipJournalStep(root, workflowRun.runId, "preview-cleanup", { performed: false }), { performed: false }) : await executeJournalStep(root, workflowRun.runId, "preview-cleanup", () => destroyPreviewIfPresent(root, featureBranch));
+        await executeJournalStep(root, workflowRun.runId, "workspace-unlink", () => unlinkWorkflowWorkspaceLinks(root, helpers, effectiveInput.workspaceLinks ?? "auto"), { rerunCompleted: true });
+        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, `close: ${message}`);
-          const deletedRemote = input.deleteBranch === false ? false : deleteRemoteBranch(repoDir, featureBranch);
+          const deletedRemote = effectiveInput.deleteBranch === false ? false : deleteRemoteBranch(repoDir, featureBranch);
           syncBranchWithOrigin(repoDir, STAGING_BRANCH);
-          if (input.deleteBranch !== false) {
+          if (effectiveInput.deleteBranch !== false) {
             deleteLocalBranch(repoDir, featureBranch);
           }
           return {
             deprecatedTag,
             deletedRemote,
-            deletedLocal: input.deleteBranch !== false,
+            deletedLocal: effectiveInput.deleteBranch !== false,
             branch: currentBranch(repoDir) || STAGING_BRANCH,
             dirty: hasMeaningfulChanges(repoDir)
           };
@@ -2332,12 +2660,15 @@ async function workflowClose(helpers, input) {
             continue;
           }
           const cleanup = await executeJournalStep(root, workflowRun.runId, `cleanup-${report.name}`, () => cleanupTaskBranchReport(report, featureBranch, `close: ${message}`, {
-            deleteBranch: input.deleteBranch !== false,
+            deleteBranch: effectiveInput.deleteBranch !== false,
             targetBranch: STAGING_BRANCH
           }));
           Object.assign(report, cleanup);
         }
-        const workspaceLinks = ensureWorkflowWorkspaceLinks(root, helpers, input.workspaceLinks ?? "auto");
+        const workspaceLinks = await executeJournalStep(root, workflowRun.runId, "workspace-link", () => ensureWorkflowWorkspaceLinks(root, helpers, effectiveInput.workspaceLinks ?? "auto"));
+        const finalBranch = currentBranch(repoDir) || STAGING_BRANCH;
+        const managedWorktree = managedWorkflowWorktreeMetadata(root);
+        const worktreeCleanup = isManagedWorkflowWorktree(root) ? await executeJournalStep(root, workflowRun.runId, "worktree-cleanup", () => removeManagedWorkflowWorktree(root)) : { removed: false, reason: "not-managed" };
         const payload = {
           mode,
           branchName: featureBranch,
@@ -2350,8 +2681,13 @@ async function workflowClose(helpers, input) {
           previewCleanup,
           remoteDeleted: rootRepo.deletedRemote,
           localDeleted: rootRepo.deletedLocal,
-          finalBranch: currentBranch(repoDir) || STAGING_BRANCH,
-          workspaceLinks
+          finalBranch,
+          workspaceLinks,
+          worktreeCleanup,
+          worktreeMode: effectiveInput.worktreeMode ?? "auto",
+          managedWorktree,
+          worktreePath: managedWorktree?.worktreePath ?? null,
+          primaryRoot: managedWorktree?.primaryRoot ?? null
         };
         completeWorkflowRun(root, workflowRun.runId, payload);
         return buildWorkflowResult(
@@ -2366,7 +2702,7 @@ async function workflowClose(helpers, input) {
           }
         );
       } catch (error) {
-        ensureWorkflowWorkspaceLinks(root, helpers, input.workspaceLinks ?? "auto");
+        ensureWorkflowWorkspaceLinks(root, helpers, effectiveInput.workspaceLinks ?? "auto");
         failWorkflowRun(root, workflowRun.runId, error, {
           resumable: true,
           runId: workflowRun.runId,
@@ -2387,11 +2723,19 @@ async function workflowStage(helpers, input) {
     return await withContextEnv(helpers.context.env, async () => {
       const tenantRoot = resolveProjectRootOrThrow("stage", helpers.cwd());
       const root = workspaceRoot(tenantRoot);
-      const message = ensureMessage("stage", input.message, "a resolution message");
       const executionMode = normalizeExecutionMode(input);
       const initialSession = resolveTreeseedWorkflowSession(root);
+      const explicitResumeRunId = helpers.context.workflow?.resumeRunId ?? null;
+      const autoResumeRun = executionMode === "execute" && !explicitResumeRunId ? findAutoResumableTaskRun(root, "stage", initialSession.branchName) : null;
+      const planAutoResumeRun = executionMode === "plan" ? findAutoResumableTaskRun(root, "stage", initialSession.branchName) : null;
+      const effectiveInput = autoResumeRun ? autoResumeRun.input : input;
+      const message = ensureMessage("stage", effectiveInput.message, "a resolution message");
+      const ciMode = normalizeCiMode(effectiveInput.ciMode, "stage");
       if (executionMode === "plan") {
         const blockers = [];
+        if (initialSession.branchRole !== "feature") {
+          blockers.push("Stage only applies to task branches.");
+        }
         try {
           validateStagingWorkflowContracts(root);
         } catch (error) {
@@ -2406,6 +2750,13 @@ async function workflowStage(helpers, input) {
             mergeTarget: STAGING_BRANCH,
             mergeStrategy: "squash",
             message,
+            ciMode,
+            autoResumeCandidate: planAutoResumeRun ? {
+              runId: planAutoResumeRun.runId,
+              branch: planAutoResumeRun.session.branchName,
+              failure: planAutoResumeRun.failure
+            } : null,
+            ...worktreePayload(root, effectiveInput.worktreeMode),
             autoSaveRequired: initialSession.rootRepo.dirty || initialSession.packageRepos.some((repo) => repo.dirty),
             blockers,
             rootRepo: createWorkspaceRootRepoReport(root),
@@ -2418,7 +2769,7 @@ async function workflowStage(helpers, input) {
               { id: "workspace-unlink", description: "Remove local workspace links before staging promotion" },
               { 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 staging automation" },
+              { id: "wait-staging", description: "Wait for exact-SHA staging GitHub Actions gates" },
               { id: "preview-cleanup", description: "Destroy preview resources" },
               { id: "cleanup-root", description: "Archive and delete the task branch from market" },
               ...checkedOutWorkspacePackageRepos(root).map((pkg) => ({
@@ -2436,12 +2787,10 @@ async function workflowStage(helpers, input) {
           }
         );
       }
-      unlinkWorkflowWorkspaceLinks(root, helpers, input.workspaceLinks ?? "auto");
       const autoSave = await maybeAutoSaveCurrentTaskBranch(helpers, "stage", {
         message,
-        autoSave: input.autoSave
+        autoSave: effectiveInput.autoSave
       });
-      unlinkWorkflowWorkspaceLinks(root, helpers, input.workspaceLinks ?? "auto");
       const session = resolveTreeseedWorkflowSession(root);
       const featureBranch = assertFeatureBranch(root);
       const mode = session.mode;
@@ -2451,6 +2800,8 @@ async function workflowStage(helpers, input) {
       } else {
         assertCleanWorktree(root);
       }
+      ensureWorkflowWorkspaceLinks(root, helpers, effectiveInput.workspaceLinks ?? "auto");
+      applyTreeseedEnvironmentToProcess({ tenantRoot: root, scope: "staging", override: true });
       validateStagingWorkflowContracts(root);
       runWorkspaceSavePreflight({ cwd: root });
       const repoDir = session.gitRoot;
@@ -2459,8 +2810,16 @@ async function workflowStage(helpers, input) {
       const workflowRun = acquireWorkflowRun(
         "stage",
         session,
-        { message, waitForStaging: input.waitForStaging !== false, deletePreview: input.deletePreview !== false, deleteBranch: input.deleteBranch !== false },
+        {
+          message,
+          waitForStaging: effectiveInput.waitForStaging !== false,
+          deletePreview: effectiveInput.deletePreview !== false,
+          deleteBranch: effectiveInput.deleteBranch !== false,
+          ciMode,
+          worktreeMode: effectiveInput.worktreeMode ?? "auto"
+        },
         [
+          { id: "workspace-unlink", description: "Remove local workspace links", repoName: rootRepo.name, repoPath: rootRepo.path, branch: featureBranch, resumable: true },
           ...packageReports.map((report) => ({
             id: `merge-${report.name}`,
             description: `Merge ${featureBranch} into ${report.name} staging`,
@@ -2470,7 +2829,7 @@ async function workflowStage(helpers, input) {
             resumable: true
           })),
           { 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 staging automation", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, 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: "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) => ({
@@ -2480,12 +2839,23 @@ async function workflowStage(helpers, input) {
             repoPath: report.path,
             branch: featureBranch,
             resumable: true
-          }))
+          })),
+          { id: "workspace-link", description: "Restore local workspace links", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, resumable: true },
+          ...isManagedWorkflowWorktree(root) ? [{ id: "worktree-cleanup", description: "Remove managed workflow worktree", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, resumable: false }] : []
         ],
-        helpers.context
+        autoResumeRun ? {
+          ...helpers.context,
+          workflow: {
+            ...helpers.context.workflow ?? {},
+            resumeRunId: autoResumeRun.runId
+          }
+        } : helpers.context
       );
+      if (autoResumeRun) {
+        helpers.write(`[workflow][resume] Resuming interrupted stage ${autoResumeRun.runId} on ${featureBranch}.`);
+      }
       try {
-        unlinkWorkflowWorkspaceLinks(root, helpers, input.workspaceLinks ?? "auto");
+        await executeJournalStep(root, workflowRun.runId, "workspace-unlink", () => unlinkWorkflowWorkspaceLinks(root, helpers, effectiveInput.workspaceLinks ?? "auto"), { rerunCompleted: true });
         for (const pkg of checkedOutWorkspacePackageRepos(root)) {
           const report = findReportByName(packageReports, pkg.name);
           if (!report) {
@@ -2517,7 +2887,11 @@ async function workflowStage(helpers, input) {
         try {
           rootMerge = await executeJournalStep(root, workflowRun.runId, "merge-root", async () => {
             assertCleanWorktree(root);
-            syncBranchWithOrigin(repoDir, STAGING_BRANCH);
+            if (isManagedWorkflowWorktree(root)) {
+              checkoutDetachedOriginBranch(repoDir, STAGING_BRANCH);
+            } else {
+              syncBranchWithOrigin(repoDir, STAGING_BRANCH);
+            }
             run("git", ["merge", "--squash", featureBranch], { cwd: repoDir });
             if (mode === "recursive-workspace") {
               syncAllCheckedOutPackageRepos(root, STAGING_BRANCH);
@@ -2532,10 +2906,14 @@ async function workflowStage(helpers, input) {
               run("git", ["add", "-A"], { cwd: repoDir });
               run("git", ["commit", "-m", message], { cwd: repoDir });
             }
-            pushBranch(repoDir, STAGING_BRANCH);
+            if (isManagedWorkflowWorktree(root)) {
+              pushHeadToBranch(repoDir, STAGING_BRANCH);
+            } else {
+              pushBranch(repoDir, STAGING_BRANCH);
+            }
             return {
               commitSha: headCommit(repoDir),
-              branch: currentBranch(repoDir) || STAGING_BRANCH,
+              branch: STAGING_BRANCH,
               committed: hasMeaningfulChanges(repoDir) ? false : true,
               lockfileValidation: lockfileSafety.lockfileValidation,
               lockfileInstall: lockfileSafety.install
@@ -2553,18 +2931,47 @@ async function workflowStage(helpers, input) {
             exitCode: 12
           });
         }
-        const stagingWait = input.waitForStaging === false ? (skipJournalStep(root, workflowRun.runId, "wait-staging", { status: "skipped", reason: "disabled" }), { status: "skipped", reason: "disabled" }) : await executeJournalStep(root, workflowRun.runId, "wait-staging", () => waitForStagingAutomation(repoDir));
-        const previewCleanup = input.deletePreview === false ? (skipJournalStep(root, workflowRun.runId, "preview-cleanup", { performed: false }), { performed: false }) : await executeJournalStep(root, workflowRun.runId, "preview-cleanup", () => destroyPreviewIfPresent(root, featureBranch));
+        const stageWorkflowGateResult = effectiveInput.waitForStaging === false ? (skipJournalStep(root, workflowRun.runId, "wait-staging", { status: "skipped", reason: "disabled" }), { status: "skipped", reason: "disabled" }) : await executeJournalStep(root, workflowRun.runId, "wait-staging", () => waitForWorkflowGates("stage", [
+          {
+            name: rootRepo.name,
+            repoPath: rootRepo.path,
+            workflow: "verify.yml",
+            branch: STAGING_BRANCH,
+            headSha: rootRepo.commitSha
+          },
+          {
+            name: rootRepo.name,
+            repoPath: rootRepo.path,
+            workflow: "deploy.yml",
+            branch: STAGING_BRANCH,
+            headSha: rootRepo.commitSha
+          },
+          ...packageReports.filter((report) => report.merged && report.commitSha).map((report) => ({
+            name: report.name,
+            repoPath: report.path,
+            workflow: "verify.yml",
+            branch: STAGING_BRANCH,
+            headSha: String(report.commitSha)
+          }))
+        ], ciMode, { root, runId: workflowRun.runId }).then((workflowGates) => ({
+          status: "completed",
+          workflowGates
+        })));
+        const stagingWait = {
+          status: String(stageWorkflowGateResult?.status ?? "completed"),
+          workflowGates: Array.isArray(stageWorkflowGateResult?.workflowGates) ? stageWorkflowGateResult.workflowGates : []
+        };
+        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}`);
-          const deletedRemote = input.deleteBranch === false ? false : deleteRemoteBranch(repoDir, featureBranch);
-          if (input.deleteBranch !== false) {
+          const deletedRemote = effectiveInput.deleteBranch === false ? false : deleteRemoteBranch(repoDir, featureBranch);
+          if (effectiveInput.deleteBranch !== false) {
             deleteLocalBranch(repoDir, featureBranch);
           }
           return {
             deprecatedTag,
             deletedRemote,
-            deletedLocal: input.deleteBranch !== false,
+            deletedLocal: effectiveInput.deleteBranch !== false,
             branch: currentBranch(repoDir) || STAGING_BRANCH
           };
         });
@@ -2579,12 +2986,15 @@ async function workflowStage(helpers, input) {
             continue;
           }
           const cleanup = await executeJournalStep(root, workflowRun.runId, `cleanup-${report.name}`, () => cleanupTaskBranchReport(report, featureBranch, `stage: ${message}`, {
-            deleteBranch: input.deleteBranch !== false,
+            deleteBranch: effectiveInput.deleteBranch !== false,
             targetBranch: STAGING_BRANCH
           }));
           Object.assign(report, cleanup);
         }
-        const workspaceLinks = ensureWorkflowWorkspaceLinks(root, helpers, input.workspaceLinks ?? "auto");
+        const workspaceLinks = await executeJournalStep(root, workflowRun.runId, "workspace-link", () => ensureWorkflowWorkspaceLinks(root, helpers, effectiveInput.workspaceLinks ?? "auto"));
+        const finalBranch = currentBranch(repoDir) || STAGING_BRANCH;
+        const managedWorktree = managedWorkflowWorktreeMetadata(root);
+        const worktreeCleanup = isManagedWorkflowWorktree(root) ? await executeJournalStep(root, workflowRun.runId, "worktree-cleanup", () => removeManagedWorkflowWorktree(root)) : { removed: false, reason: "not-managed" };
         const payload = {
           mode,
           branchName: featureBranch,
@@ -2602,8 +3012,15 @@ async function workflowStage(helpers, input) {
           lockfileInstall: rootMerge?.lockfileInstall ?? null,
           remoteDeleted: rootRepo.deletedRemote,
           localDeleted: rootRepo.deletedLocal,
-          finalBranch: currentBranch(repoDir) || STAGING_BRANCH,
-          workspaceLinks
+          finalBranch,
+          workspaceLinks,
+          ciMode,
+          workflowGates: stagingWait.workflowGates,
+          worktreeCleanup,
+          worktreeMode: effectiveInput.worktreeMode ?? "auto",
+          managedWorktree,
+          worktreePath: managedWorktree?.worktreePath ?? null,
+          primaryRoot: managedWorktree?.primaryRoot ?? null
         };
         completeWorkflowRun(root, workflowRun.runId, payload);
         return buildWorkflowResult(
@@ -2619,7 +3036,7 @@ async function workflowStage(helpers, input) {
           }
         );
       } catch (error) {
-        ensureWorkflowWorkspaceLinks(root, helpers, input.workspaceLinks ?? "auto");
+        ensureWorkflowWorkspaceLinks(root, helpers, effectiveInput.workspaceLinks ?? "auto");
         failWorkflowRun(root, workflowRun.runId, error, {
           resumable: true,
           runId: workflowRun.runId,
@@ -2650,6 +3067,7 @@ async function workflowRelease(helpers, input) {
       const planAutoResumeRun = executionMode === "plan" ? findAutoResumableReleaseRun(root, session.branchName, rootRepo, packageReports) : null;
       const effectiveInput = autoResumeRun ? autoResumeRun.input : input;
       const level = effectiveInput.bump ?? "patch";
+      const ciMode = normalizeCiMode(effectiveInput.ciMode, "release");
       const isResume = Boolean(explicitResumeRunId || autoResumeRun);
       const packageSelection = session.packageSelection;
       const selectedPackageNames = new Set(packageSelection.selected);
@@ -2666,6 +3084,8 @@ async function workflowRelease(helpers, input) {
       if (executionMode === "plan") {
         return buildWorkflowResult("release", root, {
           ...plannedRelease,
+          ciMode,
+          ...worktreePayload(root, effectiveInput.worktreeMode),
           autoResumeCandidate: planAutoResumeRun ? {
             runId: planAutoResumeRun.runId,
             branch: planAutoResumeRun.session.branchName,
@@ -2691,6 +3111,8 @@ async function workflowRelease(helpers, input) {
           devTagCleanup: effectiveInput.devTagCleanup ?? "safe-after-release",
           gitDependencyProtocol: effectiveInput.gitDependencyProtocol ?? "preserve-origin",
           gitRemoteWriteMode: effectiveInput.gitRemoteWriteMode ?? "ssh-pushurl",
+          ciMode,
+          worktreeMode: effectiveInput.worktreeMode ?? "auto",
           workspaceLinks: effectiveInput.workspaceLinks ?? "auto"
         },
         [
@@ -2706,6 +3128,7 @@ async function workflowRelease(helpers, input) {
             resumable: true
           })),
           { 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 },
           ...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 ? {
@@ -2732,19 +3155,22 @@ async function workflowRelease(helpers, input) {
           assertCleanWorktree(root);
         }
         prepareReleaseBranches(root);
+        ensureWorkflowWorkspaceLinks(root, helpers, effectiveInput.workspaceLinks ?? "auto");
         runWorkspaceSavePreflight({ cwd: root });
-        await executeJournalStep(root, workflowRun.runId, "workspace-unlink", () => unlinkWorkflowWorkspaceLinks(root, helpers, effectiveInput.workspaceLinks ?? "auto"));
+        await executeJournalStep(root, workflowRun.runId, "workspace-unlink", () => unlinkWorkflowWorkspaceLinks(root, helpers, effectiveInput.workspaceLinks ?? "auto"), { rerunCompleted: true });
         if (mode === "root-only") {
           const rootRelease2 = await executeJournalStep(root, workflowRun.runId, "release-root", () => {
             setRootPackageJsonVersion(root, rootVersion);
             run("git", ["checkout", STAGING_BRANCH], { cwd: gitRoot });
             commitAllIfChanged(gitRoot, `release: ${level} bump`);
             pushBranch(gitRoot, STAGING_BRANCH);
+            const stagingCommit = headCommit(gitRoot);
             const released = mergeStagingIntoMain(root);
             const tag = ensureReleaseTag(gitRoot, rootVersion, released.commitSha);
             syncBranchWithOrigin(gitRoot, STAGING_BRANCH);
             return {
               rootVersion,
+              stagingCommit,
               releasedCommit: released.commitSha,
               tag
             };
@@ -2755,6 +3181,43 @@ async function workflowRelease(helpers, input) {
           rootRepo.branch = PRODUCTION_BRANCH;
           rootRepo.commitSha = String(rootRelease2?.releasedCommit ?? headCommit(gitRoot));
           rootRepo.tagName = String(rootRelease2?.rootVersion ?? "");
+          const rootWorkflowGateResult2 = await executeJournalStep(root, workflowRun.runId, "release-root-gates", () => waitForWorkflowGates("release", [
+            {
+              name: rootRepo.name,
+              repoPath: rootRepo.path,
+              workflow: "verify.yml",
+              branch: STAGING_BRANCH,
+              headSha: String(rootRelease2?.stagingCommit ?? "")
+            },
+            {
+              name: rootRepo.name,
+              repoPath: rootRepo.path,
+              workflow: "deploy.yml",
+              branch: STAGING_BRANCH,
+              headSha: String(rootRelease2?.stagingCommit ?? "")
+            },
+            {
+              name: rootRepo.name,
+              repoPath: rootRepo.path,
+              workflow: "verify.yml",
+              branch: rootVersion,
+              headSha: String(rootRelease2?.releasedCommit ?? rootRepo.commitSha ?? "")
+            },
+            {
+              name: rootRepo.name,
+              repoPath: rootRepo.path,
+              workflow: "verify.yml",
+              branch: PRODUCTION_BRANCH,
+              headSha: String(rootRelease2?.releasedCommit ?? rootRepo.commitSha ?? "")
+            },
+            {
+              name: rootRepo.name,
+              repoPath: rootRepo.path,
+              workflow: "deploy.yml",
+              branch: PRODUCTION_BRANCH,
+              headSha: String(rootRelease2?.releasedCommit ?? rootRepo.commitSha ?? "")
+            }
+          ].filter((gate) => gate.headSha), ciMode, { root, runId: workflowRun.runId }).then((workflowGates) => ({ workflowGates })));
           const workspaceLinks2 = ensureWorkflowWorkspaceLinks(root, helpers, effectiveInput.workspaceLinks ?? "auto");
           const payload2 = {
             mode,
@@ -2775,7 +3238,10 @@ async function workflowRelease(helpers, input) {
             rootRepo,
             finalBranch: currentBranch(gitRoot) || STAGING_BRANCH,
             pushStatus: { stagingPushed: true, productionPushed: true, tagPushed: true },
-            workspaceLinks: workspaceLinks2
+            workspaceLinks: workspaceLinks2,
+            ciMode,
+            workflowGates: rootWorkflowGateResult2?.workflowGates ?? [],
+            ...worktreePayload(root, effectiveInput.worktreeMode)
           };
           completeWorkflowRun(root, workflowRun.runId, payload2);
           return buildWorkflowResult("release", root, payload2, {
@@ -2843,18 +3309,38 @@ async function workflowRelease(helpers, input) {
             });
             const tagName = String(effectiveVersions.get(pkg.name));
             const tag = ensureReleaseTag(pkg.dir, tagName, mergeResult.commitSha);
-            const publish = await waitForGitHubWorkflowCompletion(pkg.dir, {
-              workflow: "publish.yml",
-              headSha: mergeResult.commitSha,
-              branch: tagName
-            });
+            const workflowGates = await waitForWorkflowGates("release", [
+              {
+                name: pkg.name,
+                repoPath: pkg.dir,
+                workflow: "publish.yml",
+                headSha: mergeResult.commitSha,
+                branch: tagName
+              },
+              {
+                name: pkg.name,
+                repoPath: pkg.dir,
+                workflow: "verify.yml",
+                headSha: mergeResult.commitSha,
+                branch: tagName
+              },
+              {
+                name: pkg.name,
+                repoPath: pkg.dir,
+                workflow: "verify.yml",
+                headSha: mergeResult.commitSha,
+                branch: PRODUCTION_BRANCH
+              }
+            ], ciMode, { root, runId: workflowRun.runId });
+            const publish = workflowGates.find((gate) => gate.workflow === "publish.yml") ?? workflowGates[0] ?? null;
             assertReleaseGitHubWorkflowSucceeded(pkg.name, publish);
             syncBranchWithOrigin(pkg.dir, STAGING_BRANCH);
             return {
               commitSha: mergeResult.commitSha,
               tagName,
               tag,
-              publish
+              publish,
+              workflowGates
             };
           });
           report.committed = true;
@@ -2863,6 +3349,7 @@ async function workflowRelease(helpers, input) {
           report.tagName = String(releasedPackage?.tagName ?? "");
           report.commitSha = String(releasedPackage?.commitSha ?? report.commitSha ?? "");
           report.publishWait = releasedPackage?.publish ?? null;
+          report.workflowGates = Array.isArray(releasedPackage?.workflowGates) ? releasedPackage.workflowGates : [];
           report.branch = STAGING_BRANCH;
           publishWait.push({
             name: report.name,
@@ -2875,6 +3362,7 @@ async function workflowRelease(helpers, input) {
           run("git", ["checkout", STAGING_BRANCH], { cwd: gitRoot });
           commitAllIfChanged(gitRoot, `release: ${level} bump`);
           pushBranch(gitRoot, STAGING_BRANCH);
+          const stagingCommit = headCommit(gitRoot);
           const released = mergeBranchIntoTarget(root, {
             sourceBranch: STAGING_BRANCH,
             targetBranch: PRODUCTION_BRANCH,
@@ -2894,6 +3382,7 @@ async function workflowRelease(helpers, input) {
           syncBranchWithOrigin(gitRoot, STAGING_BRANCH);
           return {
             rootVersion,
+            stagingCommit,
             releasedCommit,
             mergeCommit: released.commitSha,
             tag
@@ -2905,6 +3394,43 @@ async function workflowRelease(helpers, input) {
         rootRepo.branch = PRODUCTION_BRANCH;
         rootRepo.commitSha = String(rootRelease?.releasedCommit ?? headCommit(gitRoot));
         rootRepo.tagName = String(rootRelease?.rootVersion ?? "");
+        const rootWorkflowGateResult = await executeJournalStep(root, workflowRun.runId, "release-root-gates", () => waitForWorkflowGates("release", [
+          {
+            name: rootRepo.name,
+            repoPath: rootRepo.path,
+            workflow: "verify.yml",
+            branch: STAGING_BRANCH,
+            headSha: String(rootRelease?.stagingCommit ?? "")
+          },
+          {
+            name: rootRepo.name,
+            repoPath: rootRepo.path,
+            workflow: "deploy.yml",
+            branch: STAGING_BRANCH,
+            headSha: String(rootRelease?.stagingCommit ?? "")
+          },
+          {
+            name: rootRepo.name,
+            repoPath: rootRepo.path,
+            workflow: "verify.yml",
+            branch: rootVersion,
+            headSha: String(rootRelease?.releasedCommit ?? rootRepo.commitSha ?? "")
+          },
+          {
+            name: rootRepo.name,
+            repoPath: rootRepo.path,
+            workflow: "verify.yml",
+            branch: PRODUCTION_BRANCH,
+            headSha: String(rootRelease?.releasedCommit ?? rootRepo.commitSha ?? "")
+          },
+          {
+            name: rootRepo.name,
+            repoPath: rootRepo.path,
+            workflow: "deploy.yml",
+            branch: PRODUCTION_BRANCH,
+            headSha: String(rootRelease?.releasedCommit ?? rootRepo.commitSha ?? "")
+          }
+        ].filter((gate) => gate.headSha), ciMode, { root, runId: workflowRun.runId }).then((workflowGates) => ({ workflowGates })));
         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);
@@ -2956,7 +3482,13 @@ async function workflowRelease(helpers, input) {
             productionPushed: true,
             tagPushed: true
           },
-          workspaceLinks
+          workspaceLinks,
+          ciMode,
+          workflowGates: [
+            ...packageReports.flatMap((report) => report.workflowGates),
+            ...Array.isArray(rootWorkflowGateResult?.workflowGates) ? rootWorkflowGateResult.workflowGates : []
+          ],
+          ...worktreePayload(root, effectiveInput.worktreeMode)
         };
         completeWorkflowRun(root, workflowRun.runId, payload);
         return buildWorkflowResult("release", root, payload, {
@@ -3006,7 +3538,21 @@ async function workflowResume(helpers, input) {
           details: { runId, status: journal.status }
         });
       }
-      const resumedHelpers = {
+      const session = resolveTreeseedWorkflowSession(root);
+      const currentHeads = Object.fromEntries(
+        [createWorkspaceRootRepoReport(root), ...createWorkspacePackageReports(root)].map((report) => [report.name, report.commitSha ?? null])
+      );
+      const classification = classifyWorkflowRunJournal(journal, {
+        currentBranch: session.branchName,
+        currentHeads
+      });
+      if (classification.state !== "resumable") {
+        workflowError("resume", "resume_unavailable", `Run ${runId} is ${classification.state} and is not safe to resume.`, {
+          details: { runId, status: journal.status, classification }
+        });
+      }
+      const resumeRoot = typeof journal.session?.root === "string" && existsSync(journal.session.root) ? journal.session.root : root;
+      const resumedHelpers = helpersForCwd({
         ...helpers,
         context: {
           ...helpers.context,
@@ -3015,7 +3561,7 @@ async function workflowResume(helpers, input) {
             resumeRunId: runId
           }
         }
-      };
+      }, resumeRoot);
       switch (journal.command) {
         case "switch":
           return workflowSwitch(resumedHelpers, journal.input);
@@ -3045,7 +3591,15 @@ async function workflowRecover(helpers, input = {}) {
       const root = resolveProjectRootOrThrow("recover", helpers.cwd());
       const lock = inspectWorkflowLock(root);
       const journals = listWorkflowRunJournals(root);
-      const interruptedRuns = listInterruptedWorkflowRuns(root).map((journal) => ({
+      const session = resolveTreeseedWorkflowSession(root);
+      const currentHeads = Object.fromEntries(
+        [createWorkspaceRootRepoReport(root), ...createWorkspacePackageReports(root)].map((report) => [report.name, report.commitSha ?? null])
+      );
+      const classifiedRuns = classifyWorkflowRunJournals(root, {
+        currentBranch: session.branchName,
+        currentHeads
+      });
+      const interruptedRuns = classifiedRuns.filter((entry) => entry.classification.state === "resumable").map(({ journal }) => ({
         runId: journal.runId,
         command: journal.command,
         status: journal.status,
@@ -3055,6 +3609,29 @@ async function workflowRecover(helpers, input = {}) {
         failure: journal.failure,
         resumeCommand: `treeseed resume ${journal.runId}`
       }));
+      const staleRuns = classifiedRuns.filter((entry) => entry.classification.state === "stale").map(({ journal, classification }) => ({
+        runId: journal.runId,
+        command: journal.command,
+        status: journal.status,
+        createdAt: journal.createdAt,
+        updatedAt: journal.updatedAt,
+        nextStep: nextPendingJournalStep(journal)?.description ?? null,
+        failure: journal.failure,
+        classification
+      }));
+      const obsoleteRuns = classifiedRuns.filter((entry) => entry.classification.state === "obsolete").map(({ journal, classification }) => ({
+        runId: journal.runId,
+        command: journal.command,
+        status: journal.status,
+        createdAt: journal.createdAt,
+        updatedAt: journal.updatedAt,
+        failure: journal.failure,
+        classification
+      }));
+      const prunedRuns = input.pruneStale === true ? staleRuns.map((run2) => {
+        archiveWorkflowRun(root, run2.runId, run2.classification);
+        return run2;
+      }) : [];
       const selectedRun = input.runId ? readWorkflowRunJournal(root, input.runId) : null;
       return buildWorkflowResult(
         "recover",
@@ -3062,13 +3639,16 @@ async function workflowRecover(helpers, input = {}) {
         {
           lock,
           interruptedRuns,
+          staleRuns,
+          obsoleteRuns,
+          prunedRuns,
           selectedRun,
           runCount: journals.length
         },
         {
           includeFinalState: false,
           nextSteps: createNextSteps([
-            ...interruptedRuns.length > 0 ? [{ operation: "resume", reason: "Resume the most recent interrupted workflow run.", input: { runId: interruptedRuns[0].runId } }] : [{ operation: "status", reason: "No interrupted runs were found; inspect current workflow state instead." }]
+            ...interruptedRuns.length > 0 ? [{ operation: "resume", reason: "Resume the most recent interrupted workflow run.", input: { runId: interruptedRuns[0].runId } }] : staleRuns.length > 0 && input.pruneStale !== true ? [{ operation: "recover", reason: "Archive stale interrupted runs that no longer match current heads.", input: { pruneStale: true } }] : [{ operation: "status", reason: "No interrupted runs were found; inspect current workflow state instead." }]
           ])
         }
       );