@treeseed/sdk 0.4.12 → 0.4.13

package/dist/workflow/operations.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import {
@@ -33,32 +33,36 @@ import {
 } from "../operations/services/deploy.js";
 import {
   assertCleanWorktree,
+  assertCleanWorktrees,
   assertFeatureBranch,
   branchExists,
   checkoutBranch,
+  checkoutTaskBranchFromStaging,
   createDeprecatedTaskTag,
-  createFeatureBranchFromStaging,
-  currentManagedBranch,
   deleteLocalBranch,
   deleteRemoteBranch,
   ensureLocalBranchTracking,
   gitWorkflowRoot,
+  headCommit,
   listTaskBranches,
-  mergeCurrentBranchIntoStaging,
+  mergeBranchIntoTarget,
   mergeStagingIntoMain,
   prepareReleaseBranches,
   PRODUCTION_BRANCH,
   pushBranch,
   remoteBranchExists,
   STAGING_BRANCH,
+  squashMergeBranchIntoStaging,
   syncBranchWithOrigin,
   waitForStagingAutomation
 } from "../operations/services/git-workflow.js";
+import { waitForGitHubWorkflowCompletion } from "../operations/services/github-automation.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";
 import {
   applyWorkspaceVersionChanges,
+  assertWorkspaceVersionConsistency,
   collectMergeConflictReport,
   currentBranch,
   formatMergeConflictReport,
@@ -69,8 +73,30 @@ import {
   planWorkspaceReleaseBump,
   repoRoot
 } from "../operations/services/workspace-save.js";
-import { run, workspaceRoot } from "../operations/services/workspace-tools.js";
+import {
+  changedWorkspacePackages,
+  publishableWorkspacePackages,
+  run,
+  sortWorkspacePackages,
+  workspaceRoot
+} from "../operations/services/workspace-tools.js";
 import { resolveTreeseedWorkflowState } from "../workflow-state.js";
+import {
+  acquireWorkflowLock,
+  createWorkflowRunJournal,
+  generateWorkflowRunId,
+  inspectWorkflowLock,
+  listInterruptedWorkflowRuns,
+  listWorkflowRunJournals,
+  readWorkflowRunJournal,
+  refreshWorkflowLock,
+  releaseWorkflowLock,
+  updateWorkflowRunJournal
+} from "./runs.js";
+import {
+  checkedOutWorkspacePackageRepos,
+  resolveTreeseedWorkflowSession
+} from "./session.js";
 import {
   classifyTreeseedBranchRole,
   resolveTreeseedWorkflowPaths
@@ -167,17 +193,81 @@ function resolveRepoState(repoDir) {
     dirtyWorktree: gitStatusPorcelain(repoDir).length > 0
   };
 }
-function buildWorkflowResult(operation, cwd, payload, nextSteps) {
+function createRepoReport(name, path, branch, dirty) {
+  return {
+    name,
+    path,
+    branch,
+    dirty,
+    created: false,
+    resumed: false,
+    merged: false,
+    verified: false,
+    committed: false,
+    pushed: false,
+    deletedLocal: false,
+    deletedRemote: false,
+    tagName: null,
+    commitSha: branch ? headCommit(path) : null,
+    skippedReason: null,
+    publishWait: null
+  };
+}
+function createWorkspaceRootRepoReport(root) {
+  const gitRoot = repoRoot(root);
+  return createRepoReport("@treeseed/market", gitRoot, currentBranch(gitRoot) || null, hasMeaningfulChanges(gitRoot));
+}
+function createWorkspacePackageReports(root) {
+  return checkedOutWorkspacePackageRepos(root).map((pkg) => createRepoReport(pkg.name, pkg.dir, currentBranch(pkg.dir) || null, hasMeaningfulChanges(pkg.dir)));
+}
+function findReportByName(reports, name) {
+  return reports.find((report) => report.name === name) ?? null;
+}
+function findReportByPath(reports, path) {
+  return reports.find((report) => report.path === path) ?? null;
+}
+function assertWorkspaceClean(root) {
+  const repoDirs = [repoRoot(root), ...checkedOutWorkspacePackageRepos(root).map((pkg) => pkg.dir)];
+  assertCleanWorktrees(repoDirs);
+  return repoDirs;
+}
+function buildWorkflowResult(operation, cwd, payload, options = {}) {
+  const resolvedPayload = options.includeFinalState ?? true ? {
+    ...payload,
+    finalState: resolveWorkflowStateSnapshot(cwd)
+  } : payload;
   return {
+    schemaVersion: 1,
+    kind: "treeseed.workflow.result",
+    command: operation,
+    executionMode: options.executionMode ?? "execute",
+    runId: options.runId ?? null,
     ok: true,
     operation,
-    payload: {
-      ...payload,
-      finalState: resolveWorkflowStateSnapshot(cwd)
-    },
-    nextSteps
+    summary: options.summary,
+    facts: options.facts,
+    payload: resolvedPayload,
+    result: resolvedPayload,
+    nextSteps: options.nextSteps,
+    recovery: options.recovery ?? null,
+    errors: options.errors ?? []
   };
 }
+function normalizeExecutionMode(input) {
+  return input?.plan === true || input?.dryRun === true ? "plan" : "execute";
+}
+function submodulePointerForRef(repoDir, ref, relativeDir) {
+  try {
+    const output = run("git", ["ls-tree", ref, relativeDir], { cwd: repoDir, capture: true }).trim();
+    if (!output) {
+      return null;
+    }
+    const match = output.match(/^[0-9]{6}\s+commit\s+([0-9a-f]{40})\t/u);
+    return match?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
 function ensureLocalReadinessOrThrow(operation, tenantRoot) {
   const state = resolveWorkflowStateSnapshot(tenantRoot);
   if (!state.readiness.local.ready) {
@@ -207,12 +297,10 @@ function createNextSteps(steps) {
 }
 function createStatusResult(cwd) {
   const state = resolveTreeseedWorkflowState(cwd);
-  return {
-    ok: true,
-    operation: "status",
-    payload: state,
-    nextSteps: createNextSteps(state.recommendations)
-  };
+  return buildWorkflowResult("status", cwd, state, {
+    nextSteps: createNextSteps(state.recommendations),
+    includeFinalState: false
+  });
 }
 function createTasksResult(cwd) {
   const tenantRoot = cwd;
@@ -223,6 +311,21 @@ function createTasksResult(cwd) {
     const previewState = loadDeployState(tenantRoot, deployConfig, {
       target: createBranchPreviewDeployTarget(branch.name)
     });
+    const packages = checkedOutWorkspacePackageRepos(tenantRoot).map((pkg) => {
+      const packageBranches = listTaskBranches(pkg.dir);
+      const match = packageBranches.find((candidate) => candidate.name === branch.name) ?? null;
+      const pointer = submodulePointerForRef(repoDir, branch.name, pkg.relativeDir);
+      return {
+        name: pkg.name,
+        path: pkg.relativeDir,
+        local: match?.local === true,
+        remote: match?.remote === true,
+        current: match?.current === true,
+        head: match?.head ?? null,
+        pointer,
+        aligned: pointer != null && match?.head != null ? pointer === match.head : match != null
+      };
+    });
     return {
       ...branch,
       ageDays: ageDays(branch.lastCommitDate),
@@ -231,10 +334,11 @@ function createTasksResult(cwd) {
         enabled: previewState.previewEnabled === true || previewState.readiness?.initialized === true,
         url: previewState.lastDeployedUrl ?? null,
         lastDeploymentTimestamp: previewState.lastDeploymentTimestamp ?? null
-      }
+      },
+      packages
     };
   });
-  return { ok: true, operation: "tasks", payload: { tasks } };
+  return buildWorkflowResult("tasks", cwd, { tasks }, { includeFinalState: false });
 }
 function maybePrint(write, line, stream = "stdout") {
   if (!line) return;
@@ -259,6 +363,210 @@ function toError(operation, error) {
   }
   throw new TreeseedWorkflowError(operation, "unsupported_state", String(error));
 }
+function workflowSessionSnapshot(session) {
+  return {
+    root: session.root,
+    mode: session.mode,
+    branchName: session.branchName,
+    repos: [session.rootRepo, ...session.packageRepos].map((repo) => ({
+      name: repo.name,
+      path: repo.path,
+      branchName: repo.branchName
+    }))
+  };
+}
+function nextPendingJournalStep(journal) {
+  return journal.steps.find((step) => step.status === "pending") ?? null;
+}
+async function executeJournalStep(root, runId, stepId, action) {
+  const current = readWorkflowRunJournal(root, runId);
+  const step = current?.steps.find((entry) => entry.id === stepId) ?? null;
+  if (!current || !step) {
+    throw new Error(`Unknown workflow step "${stepId}" for run ${runId}.`);
+  }
+  if (step.status === "completed") {
+    return step.data ?? null;
+  }
+  const data = await Promise.resolve(action());
+  updateWorkflowRunJournal(root, runId, (journal) => ({
+    ...journal,
+    steps: journal.steps.map((entry) => entry.id === stepId ? {
+      ...entry,
+      status: "completed",
+      completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      data: data ?? null
+    } : entry)
+  }));
+  refreshWorkflowLock(root, runId);
+  return data;
+}
+function skipJournalStep(root, runId, stepId, data = null) {
+  updateWorkflowRunJournal(root, runId, (journal) => ({
+    ...journal,
+    steps: journal.steps.map((entry) => entry.id === stepId ? {
+      ...entry,
+      status: "skipped",
+      completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      data
+    } : entry)
+  }));
+  refreshWorkflowLock(root, runId);
+}
+function acquireWorkflowRun(operation, session, input, steps, context) {
+  const resumeRunId = context.workflow?.resumeRunId;
+  if (resumeRunId) {
+    const existing = readWorkflowRunJournal(session.root, resumeRunId);
+    if (!existing || existing.command !== operation) {
+      workflowError(operation, "resume_unavailable", `Treeseed ${operation} cannot resume run ${resumeRunId}.`, {
+        details: { runId: resumeRunId, command: operation }
+      });
+    }
+    const lockResult2 = acquireWorkflowLock(session.root, operation, resumeRunId);
+    if (!lockResult2.acquired) {
+      workflowError(operation, "workflow_locked", `Treeseed ${operation} is blocked by active run ${lockResult2.lock.runId}.`, {
+        details: {
+          lock: lockResult2.lock,
+          recovery: {
+            resumable: true,
+            runId: lockResult2.lock.runId,
+            command: lockResult2.lock.command,
+            recoverCommand: "treeseed recover",
+            resumeCommand: `treeseed resume ${lockResult2.lock.runId}`
+          }
+        }
+      });
+    }
+    return {
+      runId: resumeRunId,
+      session,
+      journal: existing,
+      resumed: true
+    };
+  }
+  const runId = generateWorkflowRunId(operation);
+  const lockResult = acquireWorkflowLock(session.root, operation, runId);
+  if (!lockResult.acquired) {
+    workflowError(operation, "workflow_locked", `Treeseed ${operation} is blocked by active run ${lockResult.lock.runId}.`, {
+      details: {
+        lock: lockResult.lock,
+        recovery: {
+          resumable: true,
+          runId: lockResult.lock.runId,
+          command: lockResult.lock.command,
+          recoverCommand: "treeseed recover",
+          resumeCommand: `treeseed resume ${lockResult.lock.runId}`
+        }
+      }
+    });
+  }
+  const journal = createWorkflowRunJournal(session.root, {
+    runId,
+    command: operation,
+    input,
+    session: workflowSessionSnapshot(session),
+    steps
+  });
+  return {
+    runId,
+    session,
+    journal,
+    resumed: false
+  };
+}
+function completeWorkflowRun(root, runId, result) {
+  updateWorkflowRunJournal(root, runId, (journal) => ({
+    ...journal,
+    status: "completed",
+    result,
+    failure: null
+  }));
+  releaseWorkflowLock(root, runId);
+}
+function failWorkflowRun(root, runId, error, recovery) {
+  const message = error instanceof Error ? error.message : String(error);
+  const code = error instanceof TreeseedWorkflowError ? error.code : "unsupported_state";
+  const details = error instanceof TreeseedWorkflowError ? {
+    ...error.details ?? {},
+    recovery: recovery ?? error.details?.recovery ?? null
+  } : recovery ? { recovery } : null;
+  updateWorkflowRunJournal(root, runId, (journal) => ({
+    ...journal,
+    status: "failed",
+    failure: {
+      code,
+      message,
+      details,
+      at: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  }));
+  releaseWorkflowLock(root, runId);
+}
+function validatePackageReleaseWorkflows(root, packageNames) {
+  if (process.env.TREESEED_GITHUB_AUTOMATION_MODE === "stub") {
+    return;
+  }
+  const missing = checkedOutWorkspacePackageRepos(root).filter((pkg) => packageNames.includes(pkg.name)).filter((pkg) => !existsSync(resolve(pkg.dir, ".github", "workflows", "publish.yml"))).map((pkg) => pkg.name);
+  if (missing.length > 0) {
+    workflowError("release", "workflow_contract_missing", `Treeseed release requires .github/workflows/publish.yml in: ${missing.join(", ")}.`, {
+      details: {
+        missing
+      }
+    });
+  }
+}
+function validateStagingWorkflowContracts(root) {
+  if (process.env.TREESEED_GITHUB_AUTOMATION_MODE === "stub" || process.env.TREESEED_STAGE_WAIT_MODE === "skip") {
+    return;
+  }
+  const missing = [];
+  for (const fileName of ["verify.yml", "deploy.yml"]) {
+    if (!existsSync(resolve(root, ".github", "workflows", fileName))) {
+      missing.push(fileName);
+    }
+  }
+  if (missing.length > 0) {
+    workflowError("stage", "workflow_contract_missing", `Treeseed stage requires standardized root workflows: ${missing.join(", ")}.`, {
+      details: { missing }
+    });
+  }
+}
+function assertSessionBranchSafety(operation, session, {
+  requireCleanPackages = false,
+  requireCurrentBranch = false,
+  allowPackageReposWithoutOrigin = false
+} = {}) {
+  const detached = session.packageRepos.filter((repo) => repo.detached).map((repo) => repo.name);
+  if (detached.length > 0) {
+    workflowError(operation, "validation_failed", `Detached package heads detected: ${detached.join(", ")}.`, {
+      details: { detached }
+    });
+  }
+  if (requireCleanPackages) {
+    const dirty = session.packageRepos.filter((repo) => repo.dirty).map((repo) => repo.name);
+    if (dirty.length > 0) {
+      workflowError(operation, "validation_failed", `Dirty package repos block ${operation}: ${dirty.join(", ")}.`, {
+        details: { dirty }
+      });
+    }
+  }
+  if (requireCurrentBranch && session.branchName) {
+    const missing = session.packageRepos.filter((repo) => repo.branchName !== session.branchName).map((repo) => ({ name: repo.name, branchName: repo.branchName }));
+    if (missing.length > 0) {
+      workflowError(operation, "validation_failed", `Package branch alignment is required for ${operation}.`, {
+        details: { expectedBranch: session.branchName, repos: missing }
+      });
+    }
+  }
+  const missingOriginRepos = [
+    session.rootRepo,
+    ...allowPackageReposWithoutOrigin ? [] : session.packageRepos
+  ].filter((repo) => !repo.hasOriginRemote).map((repo) => repo.name);
+  if (missingOriginRepos.length > 0 && operation !== "destroy") {
+    workflowError(operation, "validation_failed", `Missing origin remote on: ${missingOriginRepos.join(", ")}.`, {
+      details: { missingOrigin: missingOriginRepos }
+    });
+  }
+}
 function previewStateFor(tenantRoot, branchName) {
   const deployConfig = loadCliDeployConfig(tenantRoot);
   return loadDeployState(tenantRoot, deployConfig, {
@@ -365,9 +673,11 @@ function syncCurrentBranchToOrigin(operation, repoDir, branch) {
 }
 async function maybeAutoSaveCurrentTaskBranch(helpers, operation, input) {
   const tenantRoot = resolveProjectRootOrThrow(operation, helpers.cwd());
-  const repoDir = gitWorkflowRoot(tenantRoot);
+  const root = workspaceRoot(tenantRoot);
+  const repoDir = gitWorkflowRoot(root);
   const before = resolveRepoState(repoDir);
-  if (!before.dirtyWorktree) {
+  const packageDirty = checkedOutWorkspacePackageRepos(root).some((pkg) => hasMeaningfulChanges(pkg.dir));
+  if (!before.dirtyWorktree && !packageDirty) {
     return { performed: false, save: null };
   }
   if (input.autoSave === false) {
@@ -384,6 +694,142 @@ async function maybeAutoSaveCurrentTaskBranch(helpers, operation, input) {
     save: saveResult.payload
   };
 }
+function checkoutOrCreateSaveBranch(repoDir, branch) {
+  const current = currentBranch(repoDir);
+  if (current === branch) {
+    return current;
+  }
+  if (branchExists(repoDir, branch)) {
+    checkoutBranch(repoDir, branch);
+    return branch;
+  }
+  if (remoteBranchExists(repoDir, branch)) {
+    run("git", ["checkout", "-b", branch, `origin/${branch}`], { cwd: repoDir });
+    return branch;
+  }
+  run("git", ["checkout", "-b", branch], { cwd: repoDir });
+  return branch;
+}
+function runPackageVerifyLocal(pkgDir) {
+  run("npm", ["run", "verify:local"], { cwd: pkgDir });
+}
+function branchNeedsSync(repoDir, branch) {
+  if (!remoteBranchExists(repoDir, branch)) {
+    return true;
+  }
+  const localHead = run("git", ["rev-parse", "HEAD"], { cwd: repoDir, capture: true }).trim();
+  const remoteHead = run("git", ["rev-parse", `origin/${branch}`], { cwd: repoDir, capture: true }).trim();
+  return localHead !== remoteHead;
+}
+function savePackageRepo(report, message, branch, shouldVerify) {
+  checkoutOrCreateSaveBranch(report.path, branch);
+  report.branch = currentBranch(report.path);
+  report.dirty = hasMeaningfulChanges(report.path);
+  const needsSync = branchNeedsSync(report.path, branch);
+  if (!report.dirty && !needsSync) {
+    report.skippedReason = "clean";
+    report.commitSha = run("git", ["rev-parse", "HEAD"], { cwd: report.path, capture: true }).trim();
+    return report;
+  }
+  if (shouldVerify && report.dirty) {
+    runPackageVerifyLocal(report.path);
+    report.verified = true;
+  }
+  if (report.dirty) {
+    run("git", ["add", "-A"], { cwd: report.path });
+    run("git", ["commit", "-m", message], { cwd: report.path });
+    report.committed = true;
+  }
+  report.commitSha = run("git", ["rev-parse", "HEAD"], { cwd: report.path, capture: true }).trim();
+  const branchSync = syncCurrentBranchToOrigin("save", report.path, branch);
+  report.pushed = branchSync.pushed === true;
+  if (!report.dirty && needsSync) {
+    report.skippedReason = "sync-only";
+  }
+  return report;
+}
+function createSaveFailure(message, repos, rootRepo, failingRepo, error) {
+  const rendered = error instanceof Error ? error.message : String(error);
+  const code = error instanceof TreeseedWorkflowError ? error.code : "unsupported_state";
+  const exitCode = error instanceof TreeseedWorkflowError ? error.exitCode : void 0;
+  throw new TreeseedWorkflowError("save", code, `${message}
+${rendered}`, {
+    details: {
+      partialFailure: {
+        message,
+        failingRepo: failingRepo?.name ?? null,
+        repos,
+        rootRepo,
+        error: rendered
+      }
+    },
+    exitCode
+  });
+}
+function ensureLocalTaskBranch(repoDir, branchName) {
+  if (!branchExists(repoDir, branchName) && !remoteBranchExists(repoDir, branchName)) {
+    return false;
+  }
+  if (!branchExists(repoDir, branchName) && remoteBranchExists(repoDir, branchName)) {
+    ensureLocalBranchTracking(repoDir, branchName);
+  }
+  if (currentBranch(repoDir) !== branchName) {
+    checkoutBranch(repoDir, branchName);
+  }
+  return true;
+}
+function cleanupTaskBranchReport(report, branchName, message, { deleteBranch = true, targetBranch = STAGING_BRANCH } = {}) {
+  if (!ensureLocalTaskBranch(report.path, branchName)) {
+    report.skippedReason = "branch-missing";
+    return report;
+  }
+  const deprecatedTag = createDeprecatedTaskTag(report.path, branchName, message);
+  report.tagName = deprecatedTag.tagName;
+  report.commitSha = deprecatedTag.head;
+  report.deletedRemote = deleteBranch ? deleteRemoteBranch(report.path, branchName) : false;
+  syncBranchWithOrigin(report.path, targetBranch);
+  if (deleteBranch) {
+    deleteLocalBranch(report.path, branchName);
+    report.deletedLocal = true;
+  }
+  report.branch = currentBranch(report.path) || targetBranch;
+  report.dirty = hasMeaningfulChanges(report.path);
+  return report;
+}
+function syncAllCheckedOutPackageRepos(root, branchName) {
+  for (const pkg of checkedOutWorkspacePackageRepos(root)) {
+    syncBranchWithOrigin(pkg.dir, branchName);
+  }
+}
+function collectReleasePackageSelection(root) {
+  const publishable = sortWorkspacePackages(
+    publishableWorkspacePackages(root).filter((pkg) => pkg.name?.startsWith("@treeseed/"))
+  );
+  const changed = changedWorkspacePackages({
+    root,
+    baseRef: PRODUCTION_BRANCH,
+    includeDependents: false,
+    packages: publishable
+  });
+  const selected = changedWorkspacePackages({
+    root,
+    baseRef: PRODUCTION_BRANCH,
+    includeDependents: true,
+    packages: publishable
+  });
+  const changedNames = changed.map((pkg) => pkg.name);
+  const selectedNames = selected.map((pkg) => pkg.name);
+  const dependents = selected.filter((pkg) => !changedNames.includes(pkg.name)).map((pkg) => pkg.name);
+  return {
+    changed: changedNames,
+    dependents,
+    selected: selectedNames,
+    publishable
+  };
+}
+function hasStagedChanges(repoDir) {
+  return run("git", ["diff", "--cached", "--name-only"], { cwd: repoDir, capture: true }).trim().length > 0;
+}
 async function workflowStatus(helpers) {
   return withContextEnv(helpers.context.env, () => createStatusResult(helpers.cwd()));
 }
@@ -425,10 +871,10 @@ async function workflowConfig(helpers, input = {}) {
           }),
           provider: checkTreeseedProviderConnections({ tenantRoot, scope, env: helpers.context.env })
         }));
-        return {
-          ok: true,
-          operation: "config",
-          payload: {
+        return buildWorkflowResult(
+          "config",
+          tenantRoot,
+          {
             mode: "print-env-only",
             scopes,
             sync,
@@ -438,17 +884,19 @@ async function workflowConfig(helpers, input = {}) {
             preflight,
             toolHealth
           },
-          nextSteps: createNextSteps([
-            { operation: "config", reason: "Initialize the selected environment after reviewing the generated values.", input: { environment: scopes } }
-          ])
-        };
+          {
+            nextSteps: createNextSteps([
+              { operation: "config", reason: "Initialize the selected environment after reviewing the generated values.", input: { environment: scopes } }
+            ])
+          }
+        );
       }
       if (rotateMachineKeyFlag) {
         const result = rotateTreeseedMachineKey(tenantRoot);
-        return {
-          ok: true,
-          operation: "config",
-          payload: {
+        return buildWorkflowResult(
+          "config",
+          tenantRoot,
+          {
             mode: "rotate-machine-key",
             scopes,
             sync,
@@ -457,10 +905,12 @@ async function workflowConfig(helpers, input = {}) {
             preflight,
             toolHealth
           },
-          nextSteps: createNextSteps([
-            { operation: "config", reason: "Inspect the regenerated local environment after the machine key rotation.", input: { environment: ["local"], printEnvOnly: true } }
-          ])
-        };
+          {
+            nextSteps: createNextSteps([
+              { operation: "config", reason: "Inspect the regenerated local environment after the machine key rotation.", input: { environment: ["local"], printEnvOnly: true } }
+            ])
+          }
+        );
       }
       const explicitUpdates = Array.isArray(input.updates) ? input.updates.map((update) => ({
         scope: update.scope,
@@ -539,46 +989,129 @@ async function workflowExport(helpers, input = {}) {
 }
 async function workflowSwitch(helpers, input) {
   try {
-    return withContextEnv(helpers.context.env, () => {
+    return await withContextEnv(helpers.context.env, async () => {
       const tenantRoot = resolveProjectRootOrThrow("switch", helpers.cwd());
+      const root = workspaceRoot(tenantRoot);
+      const session = resolveTreeseedWorkflowSession(root);
       const branchName = String(input.branch ?? input.branchName ?? "").trim();
       if (!branchName) {
         workflowError("switch", "validation_failed", "Treeseed switch requires a branch name.");
       }
       const preview = input.preview === true;
-      const repoDir = gitWorkflowRoot(tenantRoot);
-      const currentBranchName = currentManagedBranch(tenantRoot);
-      let created = false;
-      let resumed = false;
+      const executionMode = normalizeExecutionMode(input);
+      const mode = session.mode;
+      const repoDir = session.gitRoot;
+      const rootRepo = createWorkspaceRootRepoReport(root);
+      const packageReports = createWorkspacePackageReports(root);
       let previewResult = null;
-      if (currentBranchName === branchName) {
-        resumed = true;
-      } else if (!branchExists(repoDir, branchName) && !remoteBranchExists(repoDir, branchName)) {
-        if (input.createIfMissing === false) {
-          workflowError("switch", "validation_failed", `Branch "${branchName}" does not exist locally or on origin.`);
+      const dirtyRepos = [rootRepo, ...packageReports].filter((repo) => repo.dirty).map((repo) => repo.name);
+      if (executionMode === "plan") {
+        for (const report of [rootRepo, ...packageReports]) {
+          const local = branchExists(report.path, branchName);
+          const remote = remoteBranchExists(report.path, branchName);
+          report.created = !local && !remote;
+          report.resumed = local || remote;
         }
-        const result = createFeatureBranchFromStaging(tenantRoot, branchName);
-        pushBranch(result.repoDir, branchName, { setUpstream: true });
-        created = true;
-      } else {
-        assertCleanWorktree(tenantRoot);
-        ensureLocalBranchTracking(repoDir, branchName);
-        checkoutBranch(repoDir, branchName);
-        syncBranchWithOrigin(repoDir, branchName);
-        resumed = true;
+        return buildWorkflowResult(
+          "switch",
+          root,
+          {
+            mode,
+            branchName,
+            rootRepo,
+            repos: packageReports,
+            previewRequested: preview,
+            blockers: dirtyRepos.length > 0 ? [`Clean worktrees required: ${dirtyRepos.join(", ")}`] : [],
+            plannedSteps: [
+              { id: "switch-root", description: `Switch market repo to ${branchName}` },
+              ...packageReports.map((report) => ({ id: `switch-${report.name}`, description: `Mirror ${branchName} into ${report.name}` })),
+              ...preview ? [{ id: "preview", description: `Provision or refresh preview for ${branchName}` }] : []
+            ]
+          },
+          {
+            executionMode,
+            nextSteps: createNextSteps([
+              { operation: "switch", reason: "Run without --plan to create or resume the task branch.", input: { branch: branchName, preview } }
+            ])
+          }
+        );
       }
-      const stateAfterSwitch = resolveTreeseedWorkflowState(tenantRoot);
-      if (preview && !stateAfterSwitch.preview.enabled) {
-        previewResult = deployBranchPreview(tenantRoot, branchName, helpers.context, { initialize: true });
+      if (mode === "recursive-workspace") {
+        assertWorkspaceClean(root);
+        assertSessionBranchSafety("switch", session);
+      } else {
+        assertCleanWorktree(root);
       }
-      const state = resolveTreeseedWorkflowState(tenantRoot);
-      return buildWorkflowResult(
+      const workflowRun = acquireWorkflowRun(
         "switch",
-        tenantRoot,
-        {
+        session,
+        { branch: branchName, preview },
+        [
+          { id: "switch-root", description: `Switch market repo to ${branchName}`, repoName: rootRepo.name, repoPath: rootRepo.path, branch: branchName, resumable: true },
+          ...packageReports.map((report) => ({
+            id: `switch-${report.name}`,
+            description: `Mirror ${branchName} into ${report.name}`,
+            repoName: report.name,
+            repoPath: report.path,
+            branch: branchName,
+            resumable: true
+          })),
+          ...preview ? [{ id: "preview", description: `Provision or refresh preview ${branchName}`, repoName: rootRepo.name, repoPath: rootRepo.path, branch: branchName, resumable: true }] : []
+        ],
+        helpers.context
+      );
+      try {
+        const rootSwitch = await executeJournalStep(
+          root,
+          workflowRun.runId,
+          "switch-root",
+          () => checkoutTaskBranchFromStaging(repoDir, branchName, {
+            createIfMissing: input.createIfMissing !== false,
+            pushIfCreated: true
+          })
+        );
+        rootRepo.branch = currentBranch(repoDir) || branchName;
+        rootRepo.created = rootSwitch.created;
+        rootRepo.resumed = rootSwitch.resumed;
+        rootRepo.commitSha = headCommit(repoDir);
+        rootRepo.pushed = rootSwitch.created;
+        for (const pkg of checkedOutWorkspacePackageRepos(root)) {
+          const report = findReportByName(packageReports, pkg.name);
+          if (!report) {
+            continue;
+          }
+          const packageSwitch = await executeJournalStep(
+            root,
+            workflowRun.runId,
+            `switch-${report.name}`,
+            () => checkoutTaskBranchFromStaging(pkg.dir, branchName, {
+              createIfMissing: input.createIfMissing !== false,
+              pushIfCreated: false
+            })
+          );
+          report.branch = currentBranch(pkg.dir) || branchName;
+          report.created = packageSwitch.created;
+          report.resumed = packageSwitch.resumed;
+          report.commitSha = headCommit(pkg.dir);
+          report.dirty = hasMeaningfulChanges(pkg.dir);
+        }
+        const stateAfterSwitch = resolveTreeseedWorkflowState(root);
+        if (preview) {
+          previewResult = await executeJournalStep(
+            root,
+            workflowRun.runId,
+            "preview",
+            () => deployBranchPreview(root, branchName, helpers.context, { initialize: !stateAfterSwitch.preview.enabled })
+          ) ?? null;
+        }
+        const state = resolveTreeseedWorkflowState(root);
+        const payload = {
+          mode,
           branchName,
-          created,
-          resumed,
+          created: rootRepo.created,
+          resumed: rootRepo.resumed,
+          repos: packageReports,
+          rootRepo,
           previewRequested: preview,
           preview: {
             enabled: state.preview.enabled,
@@ -590,12 +1123,31 @@ async function workflowSwitch(helpers, input) {
             cleanWorktreeRequired: true,
             baseBranch: STAGING_BRANCH
           }
-        },
-        createNextSteps([
-          state.preview.enabled ? { operation: "save", reason: "Persist and verify the current task branch, then refresh its preview deployment.", input: { message: "describe your change", preview: true } } : { operation: "dev", reason: "Start the local development environment for this task branch." },
-          { operation: "stage", reason: "Merge the task into staging once the task branch is verified.", input: { message: "describe the resolution" } }
-        ])
-      );
+        };
+        completeWorkflowRun(root, workflowRun.runId, payload);
+        return buildWorkflowResult(
+          "switch",
+          root,
+          payload,
+          {
+            runId: workflowRun.runId,
+            nextSteps: createNextSteps([
+              state.preview.enabled ? { operation: "save", reason: "Persist and verify the current task branch, then refresh its preview deployment.", input: { message: "describe your change", preview: true } } : { operation: "dev", reason: "Start the local development environment for this task branch." },
+              { operation: "stage", reason: "Merge the task into staging once the task branch is verified.", input: { message: "describe the resolution" } }
+            ])
+          }
+        );
+      } catch (error) {
+        failWorkflowRun(root, workflowRun.runId, error, {
+          resumable: true,
+          runId: workflowRun.runId,
+          command: "switch",
+          message: `Resume the interrupted switch for ${branchName}.`,
+          recoverCommand: "treeseed recover",
+          resumeCommand: `treeseed resume ${workflowRun.runId}`
+        });
+        throw error;
+      }
     });
   } catch (error) {
     toError("switch", error);
@@ -669,15 +1221,19 @@ async function workflowDev(helpers, input = {}) {
 }
 async function workflowSave(helpers, input) {
   try {
-    return withContextEnv(helpers.context.env, () => {
+    return await withContextEnv(helpers.context.env, async () => {
       const tenantRoot = resolveProjectRootOrThrow("save", helpers.cwd());
       const message = ensureMessage("save", input.message, "a commit message");
       const optionsHotfix = input.hotfix === true;
       const root = workspaceRoot(tenantRoot);
-      const gitRoot = repoRoot(root);
-      const branch = currentBranch(gitRoot);
+      const session = resolveTreeseedWorkflowSession(root);
+      const gitRoot = session.gitRoot;
+      const branch = session.branchName;
       const scope = branch === STAGING_BRANCH ? "staging" : branch === PRODUCTION_BRANCH ? "prod" : "local";
       const beforeState = resolveTreeseedWorkflowState(root);
+      const recursiveWorkspace = session.mode === "recursive-workspace";
+      const mode = session.mode;
+      const executionMode = normalizeExecutionMode(input);
       applyTreeseedEnvironmentToProcess({ tenantRoot: root, scope, override: true });
       if (!branch) {
         workflowError("save", "validation_failed", "Treeseed save requires an active git branch.");
@@ -685,42 +1241,218 @@ async function workflowSave(helpers, input) {
       if (branch === PRODUCTION_BRANCH && !optionsHotfix) {
         workflowError("save", "unsupported_state", "Treeseed save is blocked on main unless --hotfix is explicitly set.");
       }
+      const packageReports = createWorkspacePackageReports(root);
+      const rootRepo = createRepoReport("@treeseed/market", gitRoot, branch, hasMeaningfulChanges(gitRoot));
+      const blockers = [];
+      if (executionMode === "plan") {
+        if (!session.rootRepo.hasOriginRemote) {
+          blockers.push("Market repo is missing origin remote.");
+        }
+        if (branch === PRODUCTION_BRANCH && !optionsHotfix) {
+          blockers.push("Main saves require --hotfix.");
+        }
+        if (recursiveWorkspace) {
+          try {
+            assertWorkspaceVersionConsistency(root);
+          } catch (error) {
+            blockers.push(error instanceof Error ? error.message : String(error));
+          }
+        }
+        return buildWorkflowResult(
+          "save",
+          root,
+          {
+            mode,
+            branch,
+            scope,
+            hotfix: optionsHotfix,
+            message,
+            repos: packageReports,
+            rootRepo,
+            blockers,
+            plannedSteps: [
+              ...packageReports.map((report) => ({ id: `save-${report.name}`, description: `Verify, commit, and push ${report.name}` })),
+              ...input.verify !== false ? [{ id: "verify-root", description: "Run market workspace verification" }] : [],
+              { id: "commit-root", description: "Commit market repo changes if present" },
+              { id: "sync-root", description: `Push ${branch} to origin` },
+              ...beforeState.branchRole === "feature" && (input.preview === true || beforeState.preview.enabled) ? [{ id: "preview", description: `Refresh preview deployment for ${branch}` }] : []
+            ]
+          },
+          {
+            executionMode,
+            nextSteps: createNextSteps([
+              { operation: "save", reason: "Run without --plan to persist the workspace checkpoint.", input: { message, hotfix: optionsHotfix, preview: input.preview === true } }
+            ])
+          }
+        );
+      }
+      assertSessionBranchSafety("save", session, {
+        allowPackageReposWithoutOrigin: true
+      });
       try {
         originRemoteUrl(gitRoot);
       } catch {
         workflowError("save", "validation_failed", "Treeseed save requires an origin remote.");
       }
-      if (input.verify !== false) {
-        runWorkspaceSavePreflight({ cwd: root });
-      }
-      const hadMeaningfulChanges = hasMeaningfulChanges(gitRoot);
-      let head = run("git", ["rev-parse", "HEAD"], { cwd: gitRoot, capture: true }).trim();
-      let commitCreated = false;
-      if (hadMeaningfulChanges) {
-        run("git", ["add", "-A"], { cwd: gitRoot });
-        run("git", ["commit", "-m", message], { cwd: gitRoot });
-        head = run("git", ["rev-parse", "HEAD"], { cwd: gitRoot, capture: true }).trim();
-        commitCreated = true;
-      }
-      const branchSync = syncCurrentBranchToOrigin("save", gitRoot, branch);
-      let previewAction = { status: "skipped" };
-      if (beforeState.branchRole === "feature" && branch) {
-        if (input.preview === true) {
-          previewAction = {
-            status: beforeState.preview.enabled ? "refreshed" : "created",
-            details: deployBranchPreview(root, branch, helpers.context, { initialize: !beforeState.preview.enabled })
-          };
-        } else if (input.refreshPreview !== false && beforeState.preview.enabled) {
-          previewAction = {
-            status: "refreshed",
-            details: deployBranchPreview(root, branch, helpers.context, { initialize: false })
-          };
-        }
-      }
-      return buildWorkflowResult(
+      const workflowRun = acquireWorkflowRun(
         "save",
-        root,
+        session,
         {
+          message,
+          hotfix: optionsHotfix,
+          preview: input.preview === true,
+          refreshPreview: input.refreshPreview !== false,
+          verify: input.verify !== false
+        },
+        [
+          ...packageReports.map((report) => ({
+            id: `save-${report.name}`,
+            description: `Save ${report.name}`,
+            repoName: report.name,
+            repoPath: report.path,
+            branch,
+            resumable: true
+          })),
+          ...input.verify !== false ? [{
+            id: "verify-root",
+            description: "Verify market workspace",
+            repoName: rootRepo.name,
+            repoPath: rootRepo.path,
+            branch,
+            resumable: true
+          }] : [],
+          {
+            id: "commit-root",
+            description: "Commit market workspace changes",
+            repoName: rootRepo.name,
+            repoPath: rootRepo.path,
+            branch,
+            resumable: true
+          },
+          {
+            id: "sync-root",
+            description: `Push ${branch} to origin`,
+            repoName: rootRepo.name,
+            repoPath: rootRepo.path,
+            branch,
+            resumable: true
+          },
+          ...beforeState.branchRole === "feature" && (input.preview === true || input.refreshPreview !== false && beforeState.preview.enabled) ? [{
+            id: "preview",
+            description: `Refresh preview ${branch}`,
+            repoName: rootRepo.name,
+            repoPath: rootRepo.path,
+            branch,
+            resumable: true
+          }] : []
+        ],
+        helpers.context
+      );
+      try {
+        if (recursiveWorkspace) {
+          assertWorkspaceVersionConsistency(root);
+          for (const pkg of checkedOutWorkspacePackageRepos(root)) {
+            const report = findReportByName(packageReports, pkg.name);
+            if (!report) {
+              continue;
+            }
+            try {
+              const step = readWorkflowRunJournal(root, workflowRun.runId)?.steps.find((entry) => entry.id === `save-${report.name}`) ?? null;
+              const resumePendingSync = workflowRun.resumed && step?.status === "pending" && branchNeedsSync(report.path, branch);
+              if (!report.dirty && !resumePendingSync) {
+                report.skippedReason = "clean";
+                skipJournalStep(root, workflowRun.runId, `save-${report.name}`, {
+                  skippedReason: "clean"
+                });
+                continue;
+              }
+              const savedReport = await executeJournalStep(root, workflowRun.runId, `save-${report.name}`, () => savePackageRepo(report, message, branch, input.verify !== false));
+              Object.assign(report, savedReport);
+            } catch (error) {
+              createSaveFailure(
+                `Treeseed save stopped while saving workspace package ${pkg.name}.`,
+                packageReports,
+                rootRepo,
+                report,
+                error
+              );
+            }
+          }
+        }
+        if (input.verify !== false) {
+          try {
+            await executeJournalStep(root, workflowRun.runId, "verify-root", () => {
+              runWorkspaceSavePreflight({ cwd: root });
+              rootRepo.verified = true;
+              return {
+                verified: true
+              };
+            });
+          } catch (error) {
+            createSaveFailure(
+              "Treeseed save stopped while verifying the market workspace.",
+              packageReports,
+              rootRepo,
+              null,
+              error
+            );
+          }
+        }
+        const hadMeaningfulChanges = hasMeaningfulChanges(gitRoot);
+        let head = run("git", ["rev-parse", "HEAD"], { cwd: gitRoot, capture: true }).trim();
+        let commitCreated = false;
+        if (hadMeaningfulChanges) {
+          const commitResult = await executeJournalStep(root, workflowRun.runId, "commit-root", () => {
+            run("git", ["add", "-A"], { cwd: gitRoot });
+            run("git", ["commit", "-m", message], { cwd: gitRoot });
+            return {
+              commitSha: run("git", ["rev-parse", "HEAD"], { cwd: gitRoot, capture: true }).trim()
+            };
+          });
+          head = String(commitResult?.commitSha ?? head);
+          commitCreated = true;
+          rootRepo.committed = true;
+        } else {
+          skipJournalStep(root, workflowRun.runId, "commit-root", {
+            skippedReason: "clean"
+          });
+        }
+        rootRepo.commitSha = head;
+        let branchSync;
+        try {
+          branchSync = await executeJournalStep(root, workflowRun.runId, "sync-root", () => syncCurrentBranchToOrigin("save", gitRoot, branch));
+        } catch (error) {
+          createSaveFailure(
+            "Treeseed save stopped while syncing the market repository.",
+            packageReports,
+            rootRepo,
+            rootRepo,
+            error
+          );
+        }
+        rootRepo.pushed = branchSync.pushed === true;
+        if (input.verify !== false) {
+          rootRepo.verified = true;
+        }
+        if (!hadMeaningfulChanges) {
+          rootRepo.skippedReason = "clean";
+        }
+        let previewAction = { status: "skipped" };
+        if (beforeState.branchRole === "feature" && branch) {
+          if (input.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 }))
+            };
+          } else if (input.refreshPreview !== false && beforeState.preview.enabled) {
+            previewAction = {
+              status: "refreshed",
+              details: await executeJournalStep(root, workflowRun.runId, "preview", () => deployBranchPreview(root, branch, helpers.context, { initialize: false }))
+            };
+          }
+        }
+        const payload = {
+          mode,
           branch,
           scope,
           hotfix: optionsHotfix,
@@ -729,13 +1461,54 @@ async function workflowSave(helpers, input) {
           commitCreated,
           noChanges: !hadMeaningfulChanges,
           branchSync,
+          repos: packageReports,
+          rootRepo,
+          partialFailure: null,
           previewAction,
           mergeConflict: null
-        },
-        createNextSteps([
-          branch === STAGING_BRANCH ? { operation: "release", reason: "Promote the validated staging branch into production.", input: { bump: "patch" } } : branch === PRODUCTION_BRANCH ? { operation: "status", reason: "Inspect production state after the explicit hotfix save." } : { operation: "stage", reason: "Merge the verified task branch into staging.", input: { message: "describe the resolution" } }
-        ])
-      );
+        };
+        completeWorkflowRun(root, workflowRun.runId, payload);
+        return buildWorkflowResult(
+          "save",
+          root,
+          payload,
+          {
+            runId: workflowRun.runId,
+            nextSteps: createNextSteps([
+              branch === STAGING_BRANCH ? { operation: "release", reason: "Promote the validated staging branch into production.", input: { bump: "patch" } } : branch === PRODUCTION_BRANCH ? { operation: "status", reason: "Inspect production state after the explicit hotfix save." } : { operation: "stage", reason: "Merge the verified task branch into staging.", input: { message: "describe the resolution" } }
+            ])
+          }
+        );
+      } catch (error) {
+        const failingRepo = packageReports.find((report) => report.dirty && report.pushed !== true) ?? rootRepo;
+        const wrappedError = error instanceof TreeseedWorkflowError && error.details?.partialFailure != null ? error : new TreeseedWorkflowError(
+          "save",
+          error instanceof TreeseedWorkflowError ? error.code : "unsupported_state",
+          error instanceof Error ? error.message : String(error),
+          {
+            details: {
+              ...error instanceof TreeseedWorkflowError ? error.details ?? {} : {},
+              partialFailure: {
+                message: "Treeseed save stopped before the workspace could finish syncing.",
+                failingRepo: failingRepo.name,
+                repos: packageReports,
+                rootRepo,
+                error: error instanceof Error ? error.message : String(error)
+              }
+            },
+            exitCode: error instanceof TreeseedWorkflowError ? error.exitCode : void 0
+          }
+        );
+        failWorkflowRun(root, workflowRun.runId, wrappedError, {
+          resumable: true,
+          runId: workflowRun.runId,
+          command: "save",
+          message: `Resume the interrupted save on ${branch}.`,
+          recoverCommand: "treeseed recover",
+          resumeCommand: `treeseed resume ${workflowRun.runId}`
+        });
+        throw wrappedError;
+      }
     });
   } catch (error) {
     toError("save", error);
@@ -743,41 +1516,148 @@ async function workflowSave(helpers, input) {
 }
 async function workflowClose(helpers, input) {
   try {
-    return withContextEnv(helpers.context.env, async () => {
+    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);
+      if (executionMode === "plan") {
+        const branchName = session.branchName;
+        const blockers = session.branchRole !== "feature" ? ["Close only applies to task branches."] : [];
+        return buildWorkflowResult(
+          "close",
+          root,
+          {
+            mode: session.mode,
+            branchName,
+            message,
+            autoSaveRequired: session.rootRepo.dirty || session.packageRepos.some((repo) => repo.dirty),
+            repos: createWorkspacePackageReports(root),
+            rootRepo: createWorkspaceRootRepoReport(root),
+            blockers,
+            plannedSteps: [
+              { 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}`
+              }))
+            ]
+          },
+          {
+            executionMode,
+            nextSteps: createNextSteps([
+              { operation: "close", reason: "Run without --plan to archive and delete the task branch.", input: { message } }
+            ])
+          }
+        );
+      }
       const autoSave = await maybeAutoSaveCurrentTaskBranch(helpers, "close", {
         message,
         autoSave: input.autoSave
       });
-      const featureBranch = assertFeatureBranch(tenantRoot);
-      const repoDir = gitWorkflowRoot(tenantRoot);
-      assertCleanWorktree(tenantRoot);
-      const previewCleanup = input.deletePreview === false ? { performed: false } : destroyPreviewIfPresent(tenantRoot, featureBranch);
-      const deprecatedTag = createDeprecatedTaskTag(repoDir, featureBranch, `close: ${message}`);
-      const remoteDeleted = input.deleteBranch === false ? false : deleteRemoteBranch(repoDir, featureBranch);
-      syncBranchWithOrigin(repoDir, STAGING_BRANCH);
-      if (input.deleteBranch !== false) {
-        deleteLocalBranch(repoDir, featureBranch);
+      const activeSession = resolveTreeseedWorkflowSession(root);
+      const featureBranch = assertFeatureBranch(root);
+      const mode = activeSession.mode;
+      const repoDir = activeSession.gitRoot;
+      assertSessionBranchSafety("close", activeSession);
+      if (mode === "recursive-workspace") {
+        assertWorkspaceClean(root);
+      } else {
+        assertCleanWorktree(root);
       }
-      return buildWorkflowResult(
+      const rootRepo = createWorkspaceRootRepoReport(root);
+      const packageReports = createWorkspacePackageReports(root);
+      const workflowRun = acquireWorkflowRun(
         "close",
-        tenantRoot,
-        {
+        activeSession,
+        { message, deletePreview: input.deletePreview !== false, deleteBranch: input.deleteBranch !== false },
+        [
+          { 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) => ({
+            id: `cleanup-${report.name}`,
+            description: `Archive ${featureBranch} in ${report.name}`,
+            repoName: report.name,
+            repoPath: report.path,
+            branch: featureBranch,
+            resumable: true
+          }))
+        ],
+        helpers.context
+      );
+      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));
+        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);
+          syncBranchWithOrigin(repoDir, STAGING_BRANCH);
+          if (input.deleteBranch !== false) {
+            deleteLocalBranch(repoDir, featureBranch);
+          }
+          return {
+            deprecatedTag,
+            deletedRemote,
+            deletedLocal: input.deleteBranch !== false,
+            branch: currentBranch(repoDir) || STAGING_BRANCH,
+            dirty: hasMeaningfulChanges(repoDir)
+          };
+        });
+        rootRepo.tagName = String(rootCleanup?.deprecatedTag?.tagName ?? null);
+        rootRepo.commitSha = String(rootCleanup?.deprecatedTag?.head ?? rootRepo.commitSha ?? "");
+        rootRepo.deletedRemote = rootCleanup?.deletedRemote === true;
+        rootRepo.deletedLocal = rootCleanup?.deletedLocal === true;
+        rootRepo.branch = typeof rootCleanup?.branch === "string" ? rootCleanup.branch : currentBranch(repoDir) || STAGING_BRANCH;
+        rootRepo.dirty = rootCleanup?.dirty === true;
+        for (const pkg of checkedOutWorkspacePackageRepos(root)) {
+          const report = findReportByName(packageReports, pkg.name);
+          if (!report) {
+            continue;
+          }
+          const cleanup = await executeJournalStep(root, workflowRun.runId, `cleanup-${report.name}`, () => cleanupTaskBranchReport(report, featureBranch, `close: ${message}`, {
+            deleteBranch: input.deleteBranch !== false,
+            targetBranch: STAGING_BRANCH
+          }));
+          Object.assign(report, cleanup);
+        }
+        const payload = {
+          mode,
           branchName: featureBranch,
           message,
           autoSaved: autoSave.performed,
           autoSaveResult: autoSave.save,
-          deprecatedTag,
+          deprecatedTag: rootCleanup?.deprecatedTag ?? null,
+          repos: packageReports,
+          rootRepo,
           previewCleanup,
-          remoteDeleted,
-          localDeleted: input.deleteBranch !== false,
+          remoteDeleted: rootRepo.deletedRemote,
+          localDeleted: rootRepo.deletedLocal,
           finalBranch: currentBranch(repoDir) || STAGING_BRANCH
-        },
-        createNextSteps([
-          { operation: "tasks", reason: "Inspect the remaining task branches after closing this one." }
-        ])
-      );
+        };
+        completeWorkflowRun(root, workflowRun.runId, payload);
+        return buildWorkflowResult(
+          "close",
+          root,
+          payload,
+          {
+            runId: workflowRun.runId,
+            nextSteps: createNextSteps([
+              { operation: "tasks", reason: "Inspect the remaining task branches after closing this one." }
+            ])
+          }
+        );
+      } catch (error) {
+        failWorkflowRun(root, workflowRun.runId, error, {
+          resumable: true,
+          runId: workflowRun.runId,
+          command: "close",
+          message: `Resume the interrupted close for ${featureBranch}.`,
+          recoverCommand: "treeseed recover",
+          resumeCommand: `treeseed resume ${workflowRun.runId}`
+        });
+        throw error;
+      }
     });
   } catch (error) {
     toError("close", error);
@@ -785,53 +1665,232 @@ async function workflowClose(helpers, input) {
 }
 async function workflowStage(helpers, input) {
   try {
-    return withContextEnv(helpers.context.env, async () => {
+    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);
+      if (executionMode === "plan") {
+        const blockers = [];
+        try {
+          validateStagingWorkflowContracts(root);
+        } catch (error) {
+          blockers.push(error instanceof Error ? error.message : String(error));
+        }
+        return buildWorkflowResult(
+          "stage",
+          root,
+          {
+            mode: initialSession.mode,
+            branchName: initialSession.branchName,
+            mergeTarget: STAGING_BRANCH,
+            mergeStrategy: "squash",
+            message,
+            autoSaveRequired: initialSession.rootRepo.dirty || initialSession.packageRepos.some((repo) => repo.dirty),
+            blockers,
+            rootRepo: createWorkspaceRootRepoReport(root),
+            repos: createWorkspacePackageReports(root),
+            plannedSteps: [
+              ...checkedOutWorkspacePackageRepos(root).map((pkg) => ({
+                id: `merge-${pkg.name}`,
+                description: `Squash-merge ${initialSession.branchName ?? "(current task)"} into ${pkg.name} staging`
+              })),
+              { id: "merge-root", description: `Squash-merge ${initialSession.branchName ?? "(current task)"} into market staging` },
+              { id: "wait-staging", description: "Wait for staging automation" },
+              { id: "preview-cleanup", description: "Destroy preview resources" },
+              { id: "cleanup-root", description: "Archive and delete the task branch from market" },
+              ...checkedOutWorkspacePackageRepos(root).map((pkg) => ({
+                id: `cleanup-${pkg.name}`,
+                description: `Archive and delete the task branch from ${pkg.name}`
+              }))
+            ]
+          },
+          {
+            executionMode,
+            nextSteps: createNextSteps([
+              { operation: "stage", reason: "Run without --plan to promote the task branch into staging.", input: { message } }
+            ])
+          }
+        );
+      }
       const autoSave = await maybeAutoSaveCurrentTaskBranch(helpers, "stage", {
         message,
         autoSave: input.autoSave
       });
-      const featureBranch = assertFeatureBranch(tenantRoot);
-      runWorkspaceSavePreflight({ cwd: tenantRoot });
-      let repoDir;
-      try {
-        repoDir = mergeCurrentBranchIntoStaging(tenantRoot, featureBranch);
-      } catch (error) {
-        const report = collectMergeConflictReport(gitWorkflowRoot(tenantRoot));
-        throw new TreeseedWorkflowError("stage", "merge_conflict", formatMergeConflictReport(report, gitWorkflowRoot(tenantRoot), STAGING_BRANCH), {
-          details: { branch: featureBranch, report, originalError: error instanceof Error ? error.message : String(error) },
-          exitCode: 12
-        });
-      }
-      const stagingWait = input.waitForStaging === false ? { status: "skipped", reason: "disabled" } : waitForStagingAutomation(repoDir);
-      const previewCleanup = input.deletePreview === false ? { performed: false } : destroyPreviewIfPresent(tenantRoot, featureBranch);
-      const deprecatedTag = createDeprecatedTaskTag(repoDir, featureBranch, `stage: ${message}`);
-      const remoteDeleted = input.deleteBranch === false ? false : deleteRemoteBranch(repoDir, featureBranch);
-      if (input.deleteBranch !== false) {
-        deleteLocalBranch(repoDir, featureBranch);
+      const session = resolveTreeseedWorkflowSession(root);
+      const featureBranch = assertFeatureBranch(root);
+      const mode = session.mode;
+      assertSessionBranchSafety("stage", session);
+      if (mode === "recursive-workspace") {
+        assertWorkspaceClean(root);
+      } else {
+        assertCleanWorktree(root);
       }
-      return buildWorkflowResult(
+      validateStagingWorkflowContracts(root);
+      runWorkspaceSavePreflight({ cwd: root });
+      const repoDir = session.gitRoot;
+      const rootRepo = createWorkspaceRootRepoReport(root);
+      const packageReports = createWorkspacePackageReports(root);
+      const workflowRun = acquireWorkflowRun(
         "stage",
-        tenantRoot,
-        {
+        session,
+        { message, waitForStaging: input.waitForStaging !== false, deletePreview: input.deletePreview !== false, deleteBranch: input.deleteBranch !== false },
+        [
+          ...packageReports.map((report) => ({
+            id: `merge-${report.name}`,
+            description: `Merge ${featureBranch} into ${report.name} staging`,
+            repoName: report.name,
+            repoPath: report.path,
+            branch: featureBranch,
+            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: "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) => ({
+            id: `cleanup-${report.name}`,
+            description: `Archive ${featureBranch} in ${report.name}`,
+            repoName: report.name,
+            repoPath: report.path,
+            branch: featureBranch,
+            resumable: true
+          }))
+        ],
+        helpers.context
+      );
+      try {
+        for (const pkg of checkedOutWorkspacePackageRepos(root)) {
+          const report = findReportByName(packageReports, pkg.name);
+          if (!report) {
+            continue;
+          }
+          if (!ensureLocalTaskBranch(pkg.dir, featureBranch)) {
+            report.skippedReason = "branch-missing";
+            skipJournalStep(root, workflowRun.runId, `merge-${report.name}`, { skippedReason: "branch-missing" });
+            continue;
+          }
+          try {
+            const mergeResult = await executeJournalStep(root, workflowRun.runId, `merge-${report.name}`, () => squashMergeBranchIntoStaging(pkg.dir, featureBranch, message, { pushTarget: true }));
+            report.merged = mergeResult.committed;
+            report.committed = mergeResult.committed;
+            report.pushed = mergeResult.pushed;
+            report.commitSha = mergeResult.commitSha;
+            report.branch = STAGING_BRANCH;
+            checkoutBranch(pkg.dir, featureBranch);
+            report.branch = featureBranch;
+          } catch (error) {
+            const reportData = collectMergeConflictReport(pkg.dir);
+            throw new TreeseedWorkflowError("stage", "merge_conflict", formatMergeConflictReport(reportData, pkg.dir, STAGING_BRANCH), {
+              details: { branch: featureBranch, packageName: pkg.name, report: reportData, originalError: error instanceof Error ? error.message : String(error) },
+              exitCode: 12
+            });
+          }
+        }
+        try {
+          const rootMerge = await executeJournalStep(root, workflowRun.runId, "merge-root", () => {
+            assertCleanWorktree(root);
+            syncBranchWithOrigin(repoDir, STAGING_BRANCH);
+            run("git", ["merge", "--squash", featureBranch], { cwd: repoDir });
+            if (mode === "recursive-workspace") {
+              syncAllCheckedOutPackageRepos(root, STAGING_BRANCH);
+            }
+            if (hasStagedChanges(repoDir) || hasMeaningfulChanges(repoDir)) {
+              run("git", ["add", "-A"], { cwd: repoDir });
+              run("git", ["commit", "-m", message], { cwd: repoDir });
+            }
+            pushBranch(repoDir, STAGING_BRANCH);
+            return {
+              commitSha: headCommit(repoDir),
+              branch: currentBranch(repoDir) || STAGING_BRANCH,
+              committed: hasMeaningfulChanges(repoDir) ? false : true
+            };
+          });
+          rootRepo.merged = true;
+          rootRepo.committed = true;
+          rootRepo.commitSha = String(rootMerge?.commitSha ?? headCommit(repoDir));
+          rootRepo.pushed = true;
+          rootRepo.branch = typeof rootMerge?.branch === "string" ? rootMerge.branch : currentBranch(repoDir) || STAGING_BRANCH;
+        } catch (error) {
+          const report = collectMergeConflictReport(repoDir);
+          throw new TreeseedWorkflowError("stage", "merge_conflict", formatMergeConflictReport(report, repoDir, STAGING_BRANCH), {
+            details: { branch: featureBranch, report, originalError: error instanceof Error ? error.message : String(error) },
+            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 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) {
+            deleteLocalBranch(repoDir, featureBranch);
+          }
+          return {
+            deprecatedTag,
+            deletedRemote,
+            deletedLocal: input.deleteBranch !== false,
+            branch: currentBranch(repoDir) || STAGING_BRANCH
+          };
+        });
+        rootRepo.tagName = String(rootCleanup?.deprecatedTag?.tagName ?? rootRepo.tagName ?? "");
+        rootRepo.commitSha = String(rootCleanup?.deprecatedTag?.head ?? rootRepo.commitSha ?? "");
+        rootRepo.deletedRemote = rootCleanup?.deletedRemote === true;
+        rootRepo.deletedLocal = rootCleanup?.deletedLocal === true;
+        rootRepo.branch = typeof rootCleanup?.branch === "string" ? rootCleanup.branch : currentBranch(repoDir) || STAGING_BRANCH;
+        for (const pkg of checkedOutWorkspacePackageRepos(root)) {
+          const report = findReportByName(packageReports, pkg.name);
+          if (!report) {
+            continue;
+          }
+          const cleanup = await executeJournalStep(root, workflowRun.runId, `cleanup-${report.name}`, () => cleanupTaskBranchReport(report, featureBranch, `stage: ${message}`, {
+            deleteBranch: input.deleteBranch !== false,
+            targetBranch: STAGING_BRANCH
+          }));
+          Object.assign(report, cleanup);
+        }
+        const payload = {
+          mode,
           branchName: featureBranch,
           mergeTarget: STAGING_BRANCH,
+          mergeStrategy: "squash",
           message,
           autoSaved: autoSave.performed,
           autoSaveResult: autoSave.save,
-          deprecatedTag,
+          deprecatedTag: rootCleanup?.deprecatedTag ?? null,
+          repos: packageReports,
+          rootRepo,
           stagingWait,
           previewCleanup,
-          remoteDeleted,
-          localDeleted: input.deleteBranch !== false,
+          remoteDeleted: rootRepo.deletedRemote,
+          localDeleted: rootRepo.deletedLocal,
           finalBranch: currentBranch(repoDir) || STAGING_BRANCH
-        },
-        createNextSteps([
-          { operation: "release", reason: "Promote the updated staging branch into production when ready.", input: { bump: "patch" } },
-          { operation: "status", reason: "Inspect staging readiness after the task branch merge." }
-        ])
-      );
+        };
+        completeWorkflowRun(root, workflowRun.runId, payload);
+        return buildWorkflowResult(
+          "stage",
+          root,
+          payload,
+          {
+            runId: workflowRun.runId,
+            nextSteps: createNextSteps([
+              { operation: "release", reason: "Promote the updated staging branch into production when ready.", input: { bump: "patch" } },
+              { operation: "status", reason: "Inspect staging readiness after the task branch merge." }
+            ])
+          }
+        );
+      } catch (error) {
+        failWorkflowRun(root, workflowRun.runId, error, {
+          resumable: true,
+          runId: workflowRun.runId,
+          command: "stage",
+          message: `Resume the interrupted stage for ${featureBranch}.`,
+          recoverCommand: "treeseed recover",
+          resumeCommand: `treeseed resume ${workflowRun.runId}`
+        });
+        throw error;
+      }
     });
   } catch (error) {
     toError("stage", error);
@@ -839,101 +1898,507 @@ async function workflowStage(helpers, input) {
 }
 async function workflowRelease(helpers, input) {
   try {
-    return withContextEnv(helpers.context.env, () => {
+    return await withContextEnv(helpers.context.env, async () => {
       const level = input.bump ?? "patch";
       const root = resolveProjectRootOrThrow("release", helpers.cwd());
-      const gitRoot = repoRoot(root);
+      const session = resolveTreeseedWorkflowSession(root);
+      const gitRoot = session.gitRoot;
+      const mode = session.mode;
+      const executionMode = normalizeExecutionMode(input);
+      const rootRepo = createWorkspaceRootRepoReport(root);
+      const packageReports = createWorkspacePackageReports(root);
+      const packageSelection = session.packageSelection;
+      const selectedPackageNames = new Set(packageSelection.selected);
+      const blockers = [];
+      if (session.branchName !== STAGING_BRANCH) {
+        blockers.push("Release must start from staging.");
+      }
+      if (mode === "recursive-workspace") {
+        try {
+          assertWorkspaceVersionConsistency(root);
+          validatePackageReleaseWorkflows(root, packageSelection.selected);
+        } catch (error) {
+          blockers.push(error instanceof Error ? error.message : String(error));
+        }
+      }
+      const versionPlan = planWorkspaceReleaseBump(level, root, mode === "recursive-workspace" ? { selectedPackageNames } : {});
+      const plannedVersions = Object.fromEntries(versionPlan.versions.entries());
+      if (executionMode === "plan") {
+        return buildWorkflowResult(
+          "release",
+          root,
+          {
+            mode,
+            mergeStrategy: "merge-commit",
+            level,
+            stagingBranch: STAGING_BRANCH,
+            productionBranch: PRODUCTION_BRANCH,
+            packageSelection,
+            plannedVersions,
+            repos: packageReports,
+            rootRepo,
+            plannedSteps: [
+              ...packageReports.filter((report) => selectedPackageNames.has(report.name)).map((report) => ({
+                id: `release-${report.name}`,
+                description: `Release ${report.name} from staging to main and tag ${plannedVersions[report.name] ?? "(planned)"}`
+              })),
+              { id: "release-root", description: `Release market ${plannedVersions["@treeseed/market"] ?? "(planned)"}` }
+            ],
+            blockers
+          },
+          {
+            executionMode,
+            nextSteps: createNextSteps([
+              { operation: "release", reason: "Run without --plan to promote staging into production.", input: { bump: level } }
+            ])
+          }
+        );
+      }
+      if (blockers.length > 0) {
+        workflowError("release", "validation_failed", blockers.join("\n"), {
+          details: { blockers }
+        });
+      }
+      assertSessionBranchSafety("release", session);
       prepareReleaseBranches(root);
       applyTreeseedEnvironmentToProcess({ tenantRoot: root, scope: "staging", override: true });
       runWorkspaceSavePreflight({ cwd: root });
-      const plan = planWorkspaceReleaseBump(level, root);
-      applyWorkspaceVersionChanges(plan);
-      const rootVersion = bumpRootPackageJson(root, level);
-      run("git", ["checkout", STAGING_BRANCH], { cwd: gitRoot });
-      run("git", ["add", "-A"], { cwd: gitRoot });
-      run("git", ["commit", "-m", `release: ${level} bump`], { cwd: gitRoot });
-      pushBranch(gitRoot, STAGING_BRANCH);
-      mergeStagingIntoMain(root);
-      const releasedCommit = run("git", ["rev-parse", PRODUCTION_BRANCH], { cwd: gitRoot, capture: true }).trim();
-      run("git", ["tag", "-a", rootVersion, "-m", `release: ${rootVersion}`], { cwd: gitRoot });
-      run("git", ["push", "origin", rootVersion], { cwd: gitRoot });
-      syncBranchWithOrigin(gitRoot, STAGING_BRANCH);
-      return buildWorkflowResult(
+      const workflowRun = acquireWorkflowRun(
         "release",
-        root,
-        {
+        session,
+        { bump: level },
+        [
+          ...packageReports.filter((report) => selectedPackageNames.has(report.name)).map((report) => ({
+            id: `release-${report.name}`,
+            description: `Release ${report.name}`,
+            repoName: report.name,
+            repoPath: report.path,
+            branch: STAGING_BRANCH,
+            resumable: true
+          })),
+          { id: "release-root", description: "Release market repo", repoName: rootRepo.name, repoPath: rootRepo.path, branch: STAGING_BRANCH, resumable: true }
+        ],
+        helpers.context
+      );
+      try {
+        if (mode === "root-only") {
+          const rootRelease2 = await executeJournalStep(root, workflowRun.runId, "release-root", () => {
+            applyWorkspaceVersionChanges(versionPlan);
+            const rootVersion = bumpRootPackageJson(root, level);
+            run("git", ["checkout", STAGING_BRANCH], { cwd: gitRoot });
+            run("git", ["add", "-A"], { cwd: gitRoot });
+            run("git", ["commit", "-m", `release: ${level} bump`], { cwd: gitRoot });
+            pushBranch(gitRoot, STAGING_BRANCH);
+            const released = mergeStagingIntoMain(root);
+            run("git", ["tag", "-a", rootVersion, "-m", `release: ${rootVersion}`], { cwd: gitRoot });
+            run("git", ["push", "origin", rootVersion], { cwd: gitRoot });
+            syncBranchWithOrigin(gitRoot, STAGING_BRANCH);
+            return {
+              rootVersion,
+              releasedCommit: released.commitSha
+            };
+          });
+          rootRepo.committed = true;
+          rootRepo.pushed = true;
+          rootRepo.merged = true;
+          rootRepo.branch = PRODUCTION_BRANCH;
+          rootRepo.commitSha = String(rootRelease2?.releasedCommit ?? headCommit(gitRoot));
+          rootRepo.tagName = String(rootRelease2?.rootVersion ?? "");
+          const payload2 = {
+            mode,
+            mergeStrategy: "merge-commit",
+            level,
+            rootVersion: String(rootRelease2?.rootVersion ?? ""),
+            releaseTag: String(rootRelease2?.rootVersion ?? ""),
+            releasedCommit: String(rootRelease2?.releasedCommit ?? rootRepo.commitSha ?? ""),
+            stagingBranch: STAGING_BRANCH,
+            productionBranch: PRODUCTION_BRANCH,
+            touchedPackages: [...versionPlan.touched],
+            packageSelection: { changed: [], dependents: [], selected: [] },
+            publishWait: [],
+            repos: [],
+            rootRepo,
+            finalBranch: currentBranch(gitRoot) || STAGING_BRANCH,
+            pushStatus: { stagingPushed: true, productionPushed: true, tagPushed: true }
+          };
+          completeWorkflowRun(root, workflowRun.runId, payload2);
+          return buildWorkflowResult("release", root, payload2, {
+            runId: workflowRun.runId,
+            nextSteps: createNextSteps([
+              { operation: "status", reason: "Inspect release readiness and production state after the promotion." }
+            ])
+          });
+        }
+        assertWorkspaceVersionConsistency(root);
+        validatePackageReleaseWorkflows(root, packageSelection.selected);
+        for (const pkg of checkedOutWorkspacePackageRepos(root)) {
+          if (selectedPackageNames.has(pkg.name)) {
+            prepareReleaseBranches(pkg.dir);
+          }
+        }
+        applyWorkspaceVersionChanges(versionPlan);
+        const publishWait = [];
+        for (const pkg of checkedOutWorkspacePackageRepos(root)) {
+          const report = findReportByName(packageReports, pkg.name);
+          if (!report || !selectedPackageNames.has(pkg.name)) {
+            if (report) {
+              report.skippedReason = "unchanged";
+            }
+            continue;
+          }
+          const releasedPackage = await executeJournalStep(root, workflowRun.runId, `release-${report.name}`, () => {
+            checkoutBranch(pkg.dir, STAGING_BRANCH);
+            if (hasMeaningfulChanges(pkg.dir)) {
+              run("git", ["add", "-A"], { cwd: pkg.dir });
+              run("git", ["commit", "-m", `release: ${versionPlan.versions.get(pkg.name)}`], { cwd: pkg.dir });
+            }
+            pushBranch(pkg.dir, STAGING_BRANCH);
+            const mergeResult = mergeBranchIntoTarget(pkg.dir, {
+              sourceBranch: STAGING_BRANCH,
+              targetBranch: PRODUCTION_BRANCH,
+              message: `release: ${STAGING_BRANCH} -> ${PRODUCTION_BRANCH}`,
+              pushTarget: true
+            });
+            const tagName = String(versionPlan.versions.get(pkg.name));
+            run("git", ["tag", "-a", tagName, "-m", `release: ${tagName}`], { cwd: pkg.dir });
+            run("git", ["push", "origin", tagName], { cwd: pkg.dir });
+            const publish = waitForGitHubWorkflowCompletion(pkg.dir, {
+              workflow: "publish.yml",
+              headSha: mergeResult.commitSha,
+              branch: PRODUCTION_BRANCH
+            });
+            syncBranchWithOrigin(pkg.dir, STAGING_BRANCH);
+            return {
+              commitSha: mergeResult.commitSha,
+              tagName,
+              publish
+            };
+          });
+          report.committed = true;
+          report.pushed = true;
+          report.merged = true;
+          report.tagName = String(releasedPackage?.tagName ?? "");
+          report.commitSha = String(releasedPackage?.commitSha ?? report.commitSha ?? "");
+          report.publishWait = releasedPackage?.publish ?? null;
+          report.branch = STAGING_BRANCH;
+          publishWait.push({
+            name: report.name,
+            ...releasedPackage?.publish ?? {}
+          });
+        }
+        const rootRelease = await executeJournalStep(root, workflowRun.runId, "release-root", () => {
+          const rootVersion = bumpRootPackageJson(root, level);
+          run("git", ["checkout", STAGING_BRANCH], { cwd: gitRoot });
+          run("git", ["add", "-A"], { cwd: gitRoot });
+          run("git", ["commit", "-m", `release: ${level} bump`], { cwd: gitRoot });
+          pushBranch(gitRoot, STAGING_BRANCH);
+          const released = mergeBranchIntoTarget(root, {
+            sourceBranch: STAGING_BRANCH,
+            targetBranch: PRODUCTION_BRANCH,
+            message: `release: ${STAGING_BRANCH} -> ${PRODUCTION_BRANCH}`,
+            pushTarget: false
+          });
+          for (const pkg of checkedOutWorkspacePackageRepos(root)) {
+            if (selectedPackageNames.has(pkg.name)) {
+              syncBranchWithOrigin(pkg.dir, PRODUCTION_BRANCH);
+            }
+          }
+          run("git", ["add", "-A"], { cwd: gitRoot });
+          if (hasMeaningfulChanges(gitRoot)) {
+            run("git", ["commit", "-m", "release: sync package main heads"], { cwd: gitRoot });
+          }
+          run("git", ["tag", "-a", rootVersion, "-m", `release: ${rootVersion}`], { cwd: gitRoot });
+          run("git", ["push", "origin", PRODUCTION_BRANCH], { cwd: gitRoot });
+          run("git", ["push", "origin", rootVersion], { cwd: gitRoot });
+          syncAllCheckedOutPackageRepos(root, STAGING_BRANCH);
+          syncBranchWithOrigin(gitRoot, STAGING_BRANCH);
+          return {
+            rootVersion,
+            releasedCommit: headCommit(gitRoot)
+          };
+        });
+        rootRepo.committed = true;
+        rootRepo.pushed = true;
+        rootRepo.merged = true;
+        rootRepo.branch = PRODUCTION_BRANCH;
+        rootRepo.commitSha = String(rootRelease?.releasedCommit ?? headCommit(gitRoot));
+        rootRepo.tagName = String(rootRelease?.rootVersion ?? "");
+        const payload = {
+          mode,
+          mergeStrategy: "merge-commit",
           level,
-          rootVersion,
-          releaseTag: rootVersion,
-          releasedCommit,
+          rootVersion: String(rootRelease?.rootVersion ?? ""),
+          releaseTag: String(rootRelease?.rootVersion ?? ""),
+          releasedCommit: String(rootRelease?.releasedCommit ?? rootRepo.commitSha ?? ""),
           stagingBranch: STAGING_BRANCH,
           productionBranch: PRODUCTION_BRANCH,
-          touchedPackages: [...plan.touched],
+          touchedPackages: packageSelection.selected,
+          packageSelection,
+          publishWait,
+          repos: packageReports,
+          rootRepo,
           finalBranch: currentBranch(gitRoot) || STAGING_BRANCH,
           pushStatus: {
             stagingPushed: true,
             productionPushed: true,
             tagPushed: true
           }
+        };
+        completeWorkflowRun(root, workflowRun.runId, payload);
+        return buildWorkflowResult(
+          "release",
+          root,
+          payload,
+          {
+            runId: workflowRun.runId,
+            nextSteps: createNextSteps([
+              { operation: "status", reason: "Inspect release readiness and production state after the promotion." }
+            ])
+          }
+        );
+      } catch (error) {
+        failWorkflowRun(root, workflowRun.runId, error, {
+          resumable: true,
+          runId: workflowRun.runId,
+          command: "release",
+          message: `Resume the interrupted release on ${STAGING_BRANCH}.`,
+          recoverCommand: "treeseed recover",
+          resumeCommand: `treeseed resume ${workflowRun.runId}`
+        });
+        throw error;
+      }
+    });
+  } catch (error) {
+    toError("release", error);
+  }
+}
+async function workflowResume(helpers, input) {
+  try {
+    return await withContextEnv(helpers.context.env, async () => {
+      const root = resolveProjectRootOrThrow("resume", helpers.cwd());
+      const runId = String(input.runId ?? "").trim();
+      if (!runId) {
+        workflowError("resume", "validation_failed", "Treeseed resume requires a run id.");
+      }
+      const journal = readWorkflowRunJournal(root, runId);
+      if (!journal) {
+        workflowError("resume", "resume_unavailable", `Treeseed resume could not find run ${runId}.`, {
+          details: { runId }
+        });
+      }
+      if (journal.status === "completed") {
+        workflowError("resume", "resume_unavailable", `Run ${runId} is already completed.`, {
+          details: { runId, status: journal.status }
+        });
+      }
+      if (!journal.resumable) {
+        workflowError("resume", "resume_unavailable", `Run ${runId} is not resumable.`, {
+          details: { runId, status: journal.status }
+        });
+      }
+      const resumedHelpers = {
+        ...helpers,
+        context: {
+          ...helpers.context,
+          workflow: {
+            ...helpers.context.workflow ?? {},
+            resumeRunId: runId
+          }
+        }
+      };
+      switch (journal.command) {
+        case "switch":
+          return workflowSwitch(resumedHelpers, journal.input);
+        case "save":
+          return workflowSave(resumedHelpers, journal.input);
+        case "close":
+          return workflowClose(resumedHelpers, journal.input);
+        case "stage":
+          return workflowStage(resumedHelpers, journal.input);
+        case "release":
+          return workflowRelease(resumedHelpers, journal.input);
+        case "destroy":
+          return workflowDestroy(resumedHelpers, journal.input);
+        default:
+          workflowError("resume", "resume_unavailable", `Run ${runId} uses unsupported command ${journal.command}.`, {
+            details: { runId, command: journal.command }
+          });
+      }
+    });
+  } catch (error) {
+    toError("resume", error);
+  }
+}
+async function workflowRecover(helpers, input = {}) {
+  try {
+    return await withContextEnv(helpers.context.env, async () => {
+      const root = resolveProjectRootOrThrow("recover", helpers.cwd());
+      const lock = inspectWorkflowLock(root);
+      const journals = listWorkflowRunJournals(root);
+      const interruptedRuns = listInterruptedWorkflowRuns(root).map((journal) => ({
+        runId: journal.runId,
+        command: journal.command,
+        status: journal.status,
+        createdAt: journal.createdAt,
+        updatedAt: journal.updatedAt,
+        nextStep: nextPendingJournalStep(journal)?.description ?? null,
+        failure: journal.failure,
+        resumeCommand: `treeseed resume ${journal.runId}`
+      }));
+      const selectedRun = input.runId ? readWorkflowRunJournal(root, input.runId) : null;
+      return buildWorkflowResult(
+        "recover",
+        root,
+        {
+          lock,
+          interruptedRuns,
+          selectedRun,
+          runCount: journals.length
         },
-        createNextSteps([
-          { operation: "status", reason: "Inspect release readiness and production state after the promotion." }
-        ])
+        {
+          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." }]
+          ])
+        }
       );
     });
   } catch (error) {
-    toError("release", error);
+    toError("recover", error);
   }
 }
 async function workflowDestroy(helpers, input) {
   try {
     return withContextEnv(helpers.context.env, async () => {
-      const tenantRoot = helpers.cwd();
+      const tenantRoot = resolveProjectRootOrThrow("destroy", helpers.cwd());
+      const root = workspaceRoot(tenantRoot);
+      const session = resolveTreeseedWorkflowSession(root);
       const scope = String(input.environment ?? input.target ?? "");
       if (!scope) {
         workflowError("destroy", "validation_failed", "Treeseed destroy requires an environment target.");
       }
+      const executionMode = normalizeExecutionMode(input);
       const target = createPersistentDeployTarget(scope);
-      const dryRun = input.dryRun === true;
+      const dryRun = executionMode === "plan";
       const force = input.force === true;
       const destroyRemote = input.destroyRemote !== false;
       const destroyLocal = input.destroyLocal !== false;
       const removeBuildArtifacts = input.removeBuildArtifacts === true;
       applyTreeseedEnvironmentToProcess({ tenantRoot, scope, override: true });
       assertTreeseedCommandEnvironment({ tenantRoot, scope, purpose: "destroy" });
-      const deployConfig = validateDestroyPrerequisites(tenantRoot, { requireRemote: !dryRun && destroyRemote });
+      const deployConfig = validateDestroyPrerequisites(tenantRoot, { requireRemote: executionMode === "execute" && destroyRemote });
       const state = loadDeployState(tenantRoot, deployConfig, { target });
       const expectedConfirmation = deployConfig.slug;
-      const confirmed = await Promise.resolve(resolveDestroyConfirmation(helpers.context, expectedConfirmation, input));
-      if (!confirmed) {
-        workflowError("destroy", "confirmation_required", `Destroy confirmation required. Re-run with confirm="${expectedConfirmation}".`);
-      }
-      const result = destroyRemote ? destroyCloudflareResources(tenantRoot, { dryRun, force, target }) : null;
-      if (!dryRun && destroyLocal) {
-        cleanupDestroyedState(tenantRoot, { target, removeBuildArtifacts });
+      const payload = {
+        scope,
+        dryRun,
+        force,
+        destroyRemote,
+        destroyLocal,
+        removeBuildArtifacts,
+        expectedConfirmation,
+        stateSummary: {
+          workerName: state.workerName,
+          lastDeploymentTimestamp: state.lastDeploymentTimestamp ?? null
+        },
+        plannedSteps: [
+          ...destroyRemote ? [{ id: "destroy-remote", description: `Destroy remote ${scope} resources` }] : [],
+          ...destroyLocal ? [{ id: "cleanup-local", description: `Clean local ${scope} state${removeBuildArtifacts ? " and build artifacts" : ""}` }] : []
+        ],
+        remoteResult: null
+      };
+      if (executionMode === "plan") {
+        return buildWorkflowResult(
+          "destroy",
+          tenantRoot,
+          payload,
+          {
+            executionMode,
+            nextSteps: createNextSteps([
+              { operation: "destroy", reason: "Run without --plan to destroy the selected environment.", input: { environment: scope, force, removeBuildArtifacts } },
+              { operation: "status", reason: "Confirm the current environment state before making destructive changes." }
+            ])
+          }
+        );
       }
-      return {
-        ok: true,
-        operation: "destroy",
-        payload: {
-          scope,
-          dryRun,
+      const workflowRun = acquireWorkflowRun(
+        "destroy",
+        session,
+        {
+          environment: scope,
           force,
           destroyRemote,
           destroyLocal,
-          removeBuildArtifacts,
-          expectedConfirmation,
-          stateSummary: {
-            workerName: state.workerName,
-            lastDeploymentTimestamp: state.lastDeploymentTimestamp ?? null
-          },
-          remoteResult: result
+          removeBuildArtifacts
         },
-        nextSteps: createNextSteps([
-          { operation: "config", reason: "Recreate the destroyed environment before using it again.", input: { environment: [scope] } },
-          { operation: "status", reason: "Confirm the environment teardown state and any remaining local runtime setup." }
-        ])
-      };
+        [
+          ...destroyRemote ? [{
+            id: "destroy-remote",
+            description: `Destroy remote ${scope} resources`,
+            repoName: session.rootRepo.name,
+            repoPath: session.rootRepo.path,
+            branch: session.branchName,
+            resumable: false
+          }] : [],
+          ...destroyLocal ? [{
+            id: "cleanup-local",
+            description: `Clean local ${scope} state${removeBuildArtifacts ? " and build artifacts" : ""}`,
+            repoName: session.rootRepo.name,
+            repoPath: session.rootRepo.path,
+            branch: session.branchName,
+            resumable: false
+          }] : []
+        ],
+        helpers.context
+      );
+      try {
+        const confirmed = await Promise.resolve(resolveDestroyConfirmation(helpers.context, expectedConfirmation, input));
+        if (!confirmed) {
+          workflowError("destroy", "confirmation_required", `Destroy confirmation required. Re-run with confirm="${expectedConfirmation}".`);
+        }
+        const remoteResult = destroyRemote ? await executeJournalStep(root, workflowRun.runId, "destroy-remote", () => destroyCloudflareResources(tenantRoot, { dryRun: false, force, target })) : null;
+        if (!destroyRemote) {
+          skipJournalStep(root, workflowRun.runId, "destroy-remote", { skippedReason: "destroyRemote=false" });
+        }
+        if (destroyLocal) {
+          await executeJournalStep(root, workflowRun.runId, "cleanup-local", () => {
+            cleanupDestroyedState(tenantRoot, { target, removeBuildArtifacts });
+            return {
+              cleaned: true,
+              removeBuildArtifacts
+            };
+          });
+        } else {
+          skipJournalStep(root, workflowRun.runId, "cleanup-local", { skippedReason: "destroyLocal=false" });
+        }
+        const resultPayload = {
+          ...payload,
+          dryRun: false,
+          remoteResult
+        };
+        completeWorkflowRun(root, workflowRun.runId, resultPayload);
+        return buildWorkflowResult(
+          "destroy",
+          tenantRoot,
+          resultPayload,
+          {
+            runId: workflowRun.runId,
+            nextSteps: createNextSteps([
+              { operation: "config", reason: "Recreate the destroyed environment before using it again.", input: { environment: [scope] } },
+              { operation: "status", reason: "Confirm the environment teardown state and any remaining local runtime setup." }
+            ])
+          }
+        );
+      } catch (error) {
+        failWorkflowRun(root, workflowRun.runId, error, {
+          resumable: false,
+          runId: workflowRun.runId,
+          command: "destroy",
+          message: `Inspect the failed destroy run for ${scope} before retrying manually.`,
+          recoverCommand: "treeseed recover"
+        });
+        throw error;
+      }
     });
   } catch (error) {
     toError("destroy", error);
@@ -946,7 +2411,9 @@ export {
   workflowDestroy,
   workflowDev,
   workflowExport,
+  workflowRecover,
   workflowRelease,
+  workflowResume,
   workflowSave,
   workflowStage,
   workflowStatus,