@treeseed/cli 0.4.10 → 0.4.12

package/README.md

@@ -21,11 +21,14 @@ npm install @treeseed/cli @treeseed/core @treeseed/sdk
 
 Workflow guarantees:
 
-- `treeseed init`, `treeseed config`, and `treeseed release` resolve the project from nested directories and do not rely on the currently checked-out task branch.
-- `treeseed switch` requires a clean worktree before leaving the current branch and creates new task branches from the latest `staging`.
-- `treeseed save` is the canonical checkpoint command: it syncs the current branch with origin, succeeds even when no new changes exist, and can create or refresh preview deployments with `--preview`.
-- `treeseed stage` and `treeseed close` auto-save meaningful uncommitted task-branch changes before merge or cleanup, then leave the repository on `staging`.
-- `treeseed release` completes on `staging` after promoting `staging` into `main` and pushing the release tag.
+- `treeseed` is the only supported project-management surface for market and any checked-out `packages/sdk`, `packages/core`, and `packages/cli` repos.
+- `treeseed switch` requires clean worktrees, mirrors the task branch into checked-out package repos, and only pushes the market branch on branch creation.
+- `treeseed save` is the canonical recursive checkpoint command: it verifies, commits, and pushes dirty package repos in dependency order before saving the market repo.
+- `treeseed stage` squash-merges task branches into `staging` across package repos first, refreshes market submodule pointers to package `staging` heads, then stages the market repo.
+- `treeseed close` recursively archives and deletes matching task branches across market and checked-out package repos.
+- `treeseed release` only bumps, tags, and publishes changed packages plus internal dependents, then syncs market production to package `main` heads.
+- Every mutating workflow command supports `--plan`; `--dry-run` is only an alias where it still exists for compatibility.
+- Interrupted workflow runs are journaled under `.treeseed/workflow`; use `treeseed recover` to inspect them and `treeseed resume <run-id>` to continue a resumable run.
 
 After installation, the published binary is available as:
 
@@ -42,11 +45,13 @@ The main workflow commands exposed by the current CLI are:
 - `treeseed tasks [--json]`
 - `treeseed switch <branch-name> [--preview]`
 - `treeseed dev`
-- `treeseed save [--preview] "<commit message>"`
+- `treeseed save [--preview] [--plan] "<commit message>"`
 - `treeseed stage "<resolution message>"`
 - `treeseed close "<close reason>"`
-- `treeseed release --major|--minor|--patch`
-- `treeseed destroy --environment <local|staging|prod>`
+- `treeseed release --major|--minor|--patch [--plan]`
+- `treeseed resume <run-id>`
+- `treeseed recover`
+- `treeseed destroy --environment <local|staging|prod> [--plan]`
 
 Support utilities such as `treeseed rollback`, `treeseed doctor`, `treeseed auth:*`, `treeseed template`, `treeseed sync`, `treeseed lint`, `treeseed test`, `treeseed build`, service helpers, and `treeseed agents ...` remain available.
 
@@ -57,14 +62,36 @@ Use `treeseed help` for the full command list and `treeseed help <command>` for
 ```bash
 treeseed status
 treeseed config
+treeseed switch feature/search-improvements --plan
 treeseed switch feature/search-improvements --preview
 treeseed dev
 treeseed save --preview "feat: add search filters"
 treeseed stage "feat: add search filters"
 treeseed release --patch
+treeseed recover
 treeseed status --json
 ```
 
+## Agent-Safe Workflow
+
+Use planning mode before any destructive or multi-repo mutation:
+
+```bash
+treeseed switch feature/search-improvements --plan --json
+treeseed save --plan "feat: add search filters" --json
+treeseed stage --plan "feat: add search filters" --json
+treeseed release --patch --plan --json
+```
+
+If a workflow stops partway through, inspect the journaled state and resume from the recorded run:
+
+```bash
+treeseed recover
+treeseed resume <run-id>
+```
+
+In a full checked-out workspace, `treeseed tasks`, `treeseed status`, and `treeseed doctor` also report package-branch drift, dirty embedded repos, active workflow locks, and interrupted runs.
+
 ## Maintainer Workflow
 
 All package maintenance commands are npm-based and run from the `cli/` package root. This package verifies the published command surface, parser/help behavior, and packaged artifact shape.

package/dist/cli/handlers/close.js

@@ -3,21 +3,26 @@ import { createWorkflowSdk, renderWorkflowNextSteps, workflowErrorResult } from
 const handleClose = async (invocation, context) => {
   try {
     const result = await createWorkflowSdk(context).close({
-      message: invocation.positionals.join(" ").trim()
+      message: invocation.positionals.join(" ").trim(),
+      plan: invocation.args.plan === true || invocation.args.dryRun === true,
+      dryRun: invocation.args.dryRun === true
     });
     const payload = result.payload;
+    const deletedPackages = payload.repos.filter((repo) => repo.deletedLocal || repo.deletedRemote).length;
     return guidedResult({
       command: invocation.commandName || "close",
-      summary: "Treeseed close completed successfully.",
+      summary: result.executionMode === "plan" ? "Treeseed close plan ready." : "Treeseed close completed successfully.",
       facts: [
+        { label: "Mode", value: payload.mode },
         { label: "Closed branch", value: payload.branchName },
         { label: "Auto-saved", value: payload.autoSaved ? "yes" : "no" },
-        { label: "Deprecated tag", value: payload.deprecatedTag.tagName },
+        { label: "Deprecated tag", value: payload.rootRepo.tagName ?? payload.deprecatedTag.tagName },
+        { label: "Package branches cleaned", value: String(deletedPackages) },
         { label: "Preview cleanup", value: payload.previewCleanup.performed ? "performed" : "not needed" },
         { label: "Final branch", value: payload.finalBranch }
       ],
       nextSteps: renderWorkflowNextSteps(result),
-      report: payload
+      report: result
     });
   } catch (error) {
     return workflowErrorResult(error);

package/dist/cli/handlers/config.js

@@ -34,6 +34,7 @@ function formatPrintEnvReports(payload) {
 function renderConfigResult(commandName, result) {
   const payload = result.payload;
   const toolHealth = payload.toolHealth;
+  const readinessByScope = payload.result?.readinessByScope ?? {};
   const summary = payload.mode === "print-env-only" ? "Treeseed config environment report completed." : payload.mode === "rotate-machine-key" ? "Treeseed machine key rotated successfully." : "Treeseed config completed successfully.";
   return guidedResult({
     command: commandName,
@@ -45,6 +46,9 @@ function renderConfigResult(commandName, result) {
       { label: "Safe repairs", value: Array.isArray(payload.repairs) ? payload.repairs.length : 0 },
       { label: "Machine config", value: payload.configPath },
       { label: "Machine key", value: payload.keyPath },
+      { label: "Local readiness", value: readinessByScope.local?.deployable ? "deployable" : readinessByScope.local?.configured ? "configured" : "pending" },
+      { label: "Staging readiness", value: readinessByScope.staging?.deployable ? "deployable" : readinessByScope.staging?.provisioned ? "provisioned" : readinessByScope.staging?.configured ? "configured" : "pending" },
+      { label: "Prod readiness", value: readinessByScope.prod?.deployable ? "deployable" : readinessByScope.prod?.provisioned ? "provisioned" : readinessByScope.prod?.configured ? "configured" : "pending" },
       { label: "GitHub CLI", value: toolHealth?.githubCli?.available ? "ready" : "missing" },
       { label: "gh act", value: toolHealth?.ghActExtension?.available ? "ready" : "missing" },
       { label: "Docker", value: toolHealth?.dockerDaemon?.available ? "ready" : "missing" },

package/dist/cli/handlers/destroy.js

@@ -24,6 +24,7 @@ const handleDestroy = async (invocation, context) => {
       }
     }).destroy({
       environment: String(invocation.args.environment),
+      plan: invocation.args.plan === true || invocation.args.dryRun === true,
       dryRun: invocation.args.dryRun === true,
       force: invocation.args.force === true,
       removeBuildArtifacts: invocation.args.removeBuildArtifacts === true
@@ -31,14 +32,14 @@ const handleDestroy = async (invocation, context) => {
     const payload = result.payload;
     return guidedResult({
       command: invocation.commandName || "destroy",
-      summary: payload.dryRun ? "Treeseed destroy dry run completed." : "Treeseed destroy completed successfully.",
+      summary: result.executionMode === "plan" ? "Treeseed destroy plan ready." : "Treeseed destroy completed successfully.",
       facts: [
         { label: "Environment", value: payload.scope },
         { label: "Dry run", value: payload.dryRun ? "yes" : "no" },
         { label: "Removed build artifacts", value: payload.removeBuildArtifacts ? "yes" : "no" }
       ],
       nextSteps: renderWorkflowNextSteps(result),
-      report: payload
+      report: result
     });
   } catch (error) {
     return workflowErrorResult(error);

package/dist/cli/handlers/doctor.js

@@ -1,54 +1,83 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
 import { collectCliPreflight } from "@treeseed/sdk/workflow-support";
 import { guidedResult } from "./utils.js";
-import { resolveTreeseedWorkflowState } from "../workflow-state.js";
 import { applyTreeseedSafeRepairs } from "../repair.js";
-const handleDoctor = (invocation, context) => {
-  const performedFixes = invocation.args.fix === true && resolveTreeseedWorkflowState(context.cwd).deployConfigPresent ? applyTreeseedSafeRepairs(context.cwd) : [];
-  const state = resolveTreeseedWorkflowState(context.cwd);
-  const preflight = collectCliPreflight({ cwd: context.cwd, requireAuth: false });
-  const railwayManagedServicesEnabled = Object.values(state.managedServices).some((service) => service.enabled);
-  const mustFixNow = [];
-  const optional = [];
-  if (!state.workspaceRoot) mustFixNow.push("Run Treeseed inside a Treeseed workspace so package commands and workflow state can resolve correctly.");
-  if (!state.repoRoot) mustFixNow.push("Initialize or clone the git repository before using save, close, stage, or release flows.");
-  if (!state.deployConfigPresent) mustFixNow.push("Create or restore treeseed.site.yaml so the tenant contract can be loaded.");
-  if (preflight.missingCommands.includes("git")) mustFixNow.push("Install Git.");
-  if (preflight.missingCommands.includes("npm")) mustFixNow.push("Install npm 10 or newer.");
-  if (!state.files.machineConfig) mustFixNow.push("Run `treeseed config --environment local` to create the local machine config.");
-  if (!state.files.envLocal) optional.push("Create `.env.local` or run `treeseed config --environment local` to generate it.");
-  if (!state.files.devVars) optional.push("Generate `.dev.vars` by running `treeseed config --environment local`.");
-  if (!state.auth.gh) optional.push("Configure `GH_TOKEN` for GitHub CLI automation and Copilot-backed workflows.");
-  if (!state.auth.wrangler) optional.push("Configure `CLOUDFLARE_API_TOKEN` before staging, preview, or production deployment work.");
-  if (!state.auth.railway && railwayManagedServicesEnabled) {
-    optional.push("Configure `RAILWAY_API_TOKEN` before deploying the managed Railway services.");
+import { createWorkflowSdk, workflowErrorResult } from "./workflow.js";
+const handleDoctor = async (invocation, context) => {
+  try {
+    const status = await createWorkflowSdk(context).status();
+    const state = status.payload;
+    const performedFixes = invocation.args.fix === true && state.deployConfigPresent ? applyTreeseedSafeRepairs(state.cwd) : [];
+    const preflight = collectCliPreflight({ cwd: context.cwd, requireAuth: false });
+    const railwayManagedServicesEnabled = Object.values(state.managedServices).some((service) => service.enabled);
+    const mustFixNow = [];
+    const optional = [];
+    if (!state.workspaceRoot) mustFixNow.push("Run Treeseed inside a Treeseed workspace so package commands and workflow state can resolve correctly.");
+    if (!state.repoRoot) mustFixNow.push("Initialize or clone the git repository before using save, close, stage, or release flows.");
+    if (!state.deployConfigPresent) mustFixNow.push("Create or restore treeseed.site.yaml so the tenant contract can be loaded.");
+    if (preflight.missingCommands.includes("git")) mustFixNow.push("Install Git.");
+    if (preflight.missingCommands.includes("npm")) mustFixNow.push("Install npm 10 or newer.");
+    if (!state.files.machineConfig) mustFixNow.push("Run `treeseed config --environment local` to create the local machine config.");
+    if (state.packageSync.blockers.length > 0) mustFixNow.push(...state.packageSync.blockers);
+    if (state.workflowControl.lock.active && state.workflowControl.lock.runId) {
+      mustFixNow.push(`Active workflow lock detected for run ${state.workflowControl.lock.runId}. Use \`treeseed recover\` before starting another mutating command.`);
+    }
+    if (state.workflowControl.interruptedRuns.length > 0) {
+      mustFixNow.push(`Interrupted workflow runs detected. Resume the latest run with \`treeseed resume ${state.workflowControl.interruptedRuns[0].runId}\` or inspect \`treeseed recover\`.`);
+    }
+    if (state.packageSync.completeCheckout) {
+      for (const repo of state.packageSync.repos) {
+        const publishWorkflowPath = resolve(state.cwd, repo.path, ".github", "workflows", "publish.yml");
+        if (!existsSync(publishWorkflowPath)) {
+          mustFixNow.push(`${repo.name} is missing .github/workflows/publish.yml required for recursive release.`);
+        }
+      }
+    }
+    for (const workflowName of ["verify.yml", "deploy.yml"]) {
+      const workflowPath = resolve(state.cwd, ".github", "workflows", workflowName);
+      if (!existsSync(workflowPath)) {
+        mustFixNow.push(`Missing root workflow contract .github/workflows/${workflowName}.`);
+      }
+    }
+    if (!state.files.envLocal) optional.push("Create `.env.local` or run `treeseed config --environment local` to generate it.");
+    if (!state.files.devVars) optional.push("Generate `.dev.vars` by running `treeseed config --environment local`.");
+    if (!state.auth.gh) optional.push("Configure `GH_TOKEN` for GitHub CLI automation and Copilot-backed workflows.");
+    if (!state.auth.wrangler) optional.push("Configure `CLOUDFLARE_API_TOKEN` before staging, preview, or production deployment work.");
+    if (!state.auth.railway && railwayManagedServicesEnabled) {
+      optional.push("Configure `RAILWAY_API_TOKEN` before deploying the managed Railway services.");
+    }
+    if (!state.auth.remoteApi && state.managedServices.api.enabled) {
+      optional.push("Run `treeseed auth:login` so the CLI can use the configured remote API.");
+    }
+    if (!state.auth.copilot) optional.push("Configure `GH_TOKEN` if you rely on local Copilot-assisted workflows.");
+    return guidedResult({
+      command: "doctor",
+      summary: mustFixNow.length === 0 ? "Treeseed doctor found no blocking issues." : "Treeseed doctor found issues that need attention.",
+      facts: [
+        { label: "Must fix now", value: mustFixNow.length },
+        { label: "Optional follow-up", value: optional.length },
+        { label: "Safe fixes applied", value: performedFixes.length },
+        { label: "Branch", value: state.branchName ?? "(none)" },
+        { label: "Workspace root", value: state.workspaceRoot ? "yes" : "no" }
+      ],
+      nextSteps: [
+        ...mustFixNow.map((item) => item),
+        ...mustFixNow.length === 0 ? optional : optional.map((item) => `Optional: ${item}`)
+      ],
+      report: {
+        ...status,
+        state,
+        preflight,
+        performedFixes,
+        mustFixNow,
+        optional
+      },
+      exitCode: mustFixNow.length === 0 ? 0 : 1
+    });
+  } catch (error) {
+    return workflowErrorResult(error);
   }
-  if (!state.auth.remoteApi && state.managedServices.api.enabled) {
-    optional.push("Run `treeseed auth:login` so the CLI can use the configured remote API.");
-  }
-  if (!state.auth.copilot) optional.push("Configure `GH_TOKEN` if you rely on local Copilot-assisted workflows.");
-  return guidedResult({
-    command: "doctor",
-    summary: mustFixNow.length === 0 ? "Treeseed doctor found no blocking issues." : "Treeseed doctor found issues that need attention.",
-    facts: [
-      { label: "Must fix now", value: mustFixNow.length },
-      { label: "Optional follow-up", value: optional.length },
-      { label: "Safe fixes applied", value: performedFixes.length },
-      { label: "Branch", value: state.branchName ?? "(none)" },
-      { label: "Workspace root", value: state.workspaceRoot ? "yes" : "no" }
-    ],
-    nextSteps: [
-      ...mustFixNow.map((item) => item),
-      ...mustFixNow.length === 0 ? optional : optional.map((item) => `Optional: ${item}`)
-    ],
-    report: {
-      state,
-      preflight,
-      performedFixes,
-      mustFixNow,
-      optional
-    },
-    exitCode: mustFixNow.length === 0 ? 0 : 1
-  });
 };
 export {
   handleDoctor

package/dist/cli/handlers/recover.d.ts

@@ -0,0 +1,2 @@
+import type { TreeseedCommandHandler } from '../types.js';
+export declare const handleRecover: TreeseedCommandHandler;

package/dist/cli/handlers/recover.js

@@ -0,0 +1,25 @@
+import { guidedResult } from "./utils.js";
+import { createWorkflowSdk, renderWorkflowNextSteps, workflowErrorResult } from "./workflow.js";
+const handleRecover = async (_invocation, context) => {
+  try {
+    const result = await createWorkflowSdk(context).recover({});
+    const payload = result.payload;
+    return guidedResult({
+      command: "recover",
+      summary: payload.interruptedRuns.length > 0 || payload.lock.active ? "Treeseed recover found workflow state that may need attention." : "Treeseed recover found no active locks or interrupted runs.",
+      facts: [
+        { label: "Active lock", value: payload.lock.active ? "yes" : "no" },
+        { label: "Stale lock", value: payload.lock.stale ? "yes" : "no" },
+        { label: "Interrupted runs", value: payload.interruptedRuns.length },
+        { label: "Recorded runs", value: payload.runCount }
+      ],
+      nextSteps: renderWorkflowNextSteps(result),
+      report: result
+    });
+  } catch (error) {
+    return workflowErrorResult(error);
+  }
+};
+export {
+  handleRecover
+};

package/dist/cli/handlers/release.js

@@ -3,23 +3,33 @@ import { createWorkflowSdk, renderWorkflowNextSteps, workflowErrorResult } from
 const handleRelease = async (invocation, context) => {
   try {
     const bump = ["major", "minor", "patch"].find((candidate) => invocation.args[candidate] === true) ?? "patch";
-    const result = await createWorkflowSdk(context).release({ bump });
+    const result = await createWorkflowSdk(context).release({
+      bump,
+      plan: invocation.args.plan === true || invocation.args.dryRun === true,
+      dryRun: invocation.args.dryRun === true
+    });
     const payload = result.payload;
+    const completedPublishes = payload.publishWait.filter((entry) => entry.status === "completed").length;
     return guidedResult({
       command: invocation.commandName || "release",
-      summary: "Treeseed release completed successfully.",
+      summary: result.executionMode === "plan" ? "Treeseed release plan ready." : "Treeseed release completed successfully.",
       facts: [
+        { label: "Mode", value: payload.mode },
         { label: "Staging branch", value: payload.stagingBranch },
         { label: "Production branch", value: payload.productionBranch },
+        { label: "Merge strategy", value: payload.mergeStrategy },
         { label: "Release level", value: payload.level },
         { label: "Root version", value: payload.rootVersion },
         { label: "Release tag", value: payload.releaseTag },
         { label: "Released commit", value: payload.releasedCommit.slice(0, 12) },
-        { label: "Updated packages", value: payload.touchedPackages.length },
+        { label: "Changed packages", value: String(payload.packageSelection.changed.length) },
+        { label: "Dependent packages", value: String(payload.packageSelection.dependents.length) },
+        { label: "Released packages", value: String(payload.touchedPackages.length) },
+        { label: "Publish waits", value: String(completedPublishes) },
         { label: "Final branch", value: payload.finalBranch }
       ],
       nextSteps: renderWorkflowNextSteps(result),
-      report: payload
+      report: result
     });
   } catch (error) {
     return workflowErrorResult(error);

package/dist/cli/handlers/resume.d.ts

@@ -0,0 +1,2 @@
+import type { TreeseedCommandHandler } from '../types.js';
+export declare const handleResume: TreeseedCommandHandler;

package/dist/cli/handlers/resume.js

@@ -0,0 +1,23 @@
+import { guidedResult } from "./utils.js";
+import { createWorkflowSdk, renderWorkflowNextSteps, workflowErrorResult } from "./workflow.js";
+const handleResume = async (invocation, context) => {
+  try {
+    const runId = invocation.positionals[0] ?? "";
+    const result = await createWorkflowSdk(context).resume({ runId });
+    return guidedResult({
+      command: invocation.commandName || "resume",
+      summary: `Resumed workflow run ${runId}.`,
+      facts: [
+        { label: "Run", value: result.runId ?? runId },
+        { label: "Command", value: result.command }
+      ],
+      nextSteps: renderWorkflowNextSteps(result),
+      report: result
+    });
+  } catch (error) {
+    return workflowErrorResult(error);
+  }
+};
+export {
+  handleResume
+};

package/dist/cli/handlers/save.js

@@ -5,22 +5,28 @@ const handleSave = async (invocation, context) => {
     const result = await createWorkflowSdk(context).save({
       message: invocation.positionals.join(" ").trim(),
       hotfix: invocation.args.hotfix === true,
-      preview: invocation.args.preview === true
+      preview: invocation.args.preview === true,
+      plan: invocation.args.plan === true || invocation.args.dryRun === true,
+      dryRun: invocation.args.dryRun === true
     });
     const payload = result.payload;
+    const savedRepos = (payload.repos ?? []).filter((repo) => repo.committed || repo.pushed).map((repo) => `${repo.name}@${String(repo.commitSha ?? "").slice(0, 12)}`).join(", ");
     return guidedResult({
       command: invocation.commandName || "save",
-      summary: payload.noChanges ? "Treeseed save found no new changes and confirmed branch sync." : "Treeseed save completed successfully.",
+      summary: result.executionMode === "plan" ? "Treeseed save plan ready." : payload.noChanges ? "Treeseed save found no new changes and confirmed branch sync." : "Treeseed save completed successfully.",
       facts: [
+        { label: "Mode", value: payload.mode },
         { label: "Branch", value: payload.branch },
         { label: "Environment scope", value: payload.scope },
         { label: "Hotfix", value: payload.hotfix ? "yes" : "no" },
         { label: "Commit", value: payload.commitSha.slice(0, 12) },
         { label: "Commit created", value: payload.commitCreated ? "yes" : "no" },
+        { label: "Workspace repos", value: savedRepos || ((payload.repos ?? []).length > 0 ? "none saved" : "not applicable") },
+        { label: "Market pushed", value: payload.rootRepo?.pushed ? "yes" : "no" },
         { label: "Preview action", value: payload.previewAction?.status ?? "skipped" }
       ],
       nextSteps: renderWorkflowNextSteps(result),
-      report: payload
+      report: result
     });
   } catch (error) {
     return workflowErrorResult(error);

package/dist/cli/handlers/stage.js

@@ -3,23 +3,29 @@ import { createWorkflowSdk, renderWorkflowNextSteps, workflowErrorResult } from
 const handleStage = async (invocation, context) => {
   try {
     const result = await createWorkflowSdk(context).stage({
-      message: invocation.positionals.join(" ").trim()
+      message: invocation.positionals.join(" ").trim(),
+      plan: invocation.args.plan === true || invocation.args.dryRun === true,
+      dryRun: invocation.args.dryRun === true
     });
     const payload = result.payload;
+    const mergedPackages = payload.repos.filter((repo) => repo.merged).length;
     return guidedResult({
       command: invocation.commandName || "stage",
-      summary: "Treeseed stage completed successfully.",
+      summary: result.executionMode === "plan" ? "Treeseed stage plan ready." : "Treeseed stage completed successfully.",
       facts: [
+        { label: "Mode", value: payload.mode },
         { label: "Merged branch", value: payload.branchName },
         { label: "Merge target", value: payload.mergeTarget },
+        { label: "Merge strategy", value: payload.mergeStrategy },
         { label: "Auto-saved", value: payload.autoSaved ? "yes" : "no" },
-        { label: "Deprecated tag", value: payload.deprecatedTag.tagName },
+        { label: "Deprecated tag", value: payload.rootRepo.tagName ?? payload.deprecatedTag.tagName },
+        { label: "Package merges", value: String(mergedPackages) },
         { label: "Staging wait", value: payload.stagingWait.status },
         { label: "Preview cleanup", value: payload.previewCleanup.performed ? "performed" : "not needed" },
         { label: "Final branch", value: payload.finalBranch }
       ],
       nextSteps: renderWorkflowNextSteps(result),
-      report: payload
+      report: result
     });
   } catch (error) {
     return workflowErrorResult(error);

package/dist/cli/handlers/status.js

@@ -14,6 +14,11 @@ const handleStatus = async (_invocation, context) => {
         { label: "Branch role", value: state.branchRole },
         { label: "Mapped environment", value: state.environment },
         { label: "Dirty worktree", value: state.dirtyWorktree ? "yes" : "no" },
+        { label: "Package mode", value: state.packageSync.mode },
+        { label: "Full package checkout", value: state.packageSync.completeCheckout ? "yes" : "no" },
+        { label: "Package branch aligned", value: state.packageSync.aligned ? "yes" : "no" },
+        { label: "Dirty package repos", value: state.packageSync.dirty ? "yes" : "no" },
+        { label: "Package blockers", value: state.packageSync.blockers.length > 0 ? state.packageSync.blockers.join(" | ") : "(none)" },
         { label: "Local initialized", value: state.persistentEnvironments.local.initialized ? "yes" : "no" },
         { label: "Staging initialized", value: state.persistentEnvironments.staging.initialized ? "yes" : "no" },
         { label: "Prod initialized", value: state.persistentEnvironments.prod.initialized ? "yes" : "no" },
@@ -28,6 +33,7 @@ const handleStatus = async (_invocation, context) => {
       ],
       nextSteps: renderWorkflowNextSteps(result),
       report: {
+        ...result,
         state
       }
     });

package/dist/cli/handlers/switch.js

@@ -5,20 +5,27 @@ const handleSwitch = async (invocation, context) => {
     const branch = invocation.positionals[0];
     const result = await createWorkflowSdk(context).switchTask({
       branch,
-      preview: invocation.args.preview === true
+      preview: invocation.args.preview === true,
+      plan: invocation.args.plan === true || invocation.args.dryRun === true,
+      dryRun: invocation.args.dryRun === true
     });
     const payload = result.payload;
+    const packageCreated = payload.repos.filter((repo) => repo.created).length;
+    const packageResumed = payload.repos.filter((repo) => repo.resumed).length;
     return guidedResult({
       command: invocation.commandName || "switch",
-      summary: payload.created ? `Created task branch ${payload.branchName}.` : payload.resumed ? `Switched to task branch ${payload.branchName}.` : `Task branch ${payload.branchName} is ready.`,
+      summary: result.executionMode === "plan" ? `Switch plan for ${payload.branchName}.` : payload.rootRepo.created ? `Created task branch ${payload.branchName}.` : payload.rootRepo.resumed ? `Switched to task branch ${payload.branchName}.` : `Task branch ${payload.branchName} is ready.`,
       facts: [
+        { label: "Mode", value: payload.mode },
         { label: "Branch", value: payload.branchName },
-        { label: "Created", value: payload.created ? "yes" : "no" },
+        { label: "Market created", value: payload.rootRepo.created ? "yes" : "no" },
+        { label: "Package branches created", value: String(packageCreated) },
+        { label: "Package branches resumed", value: String(packageResumed) },
         { label: "Preview", value: payload.preview.enabled ? "enabled" : "disabled" },
         { label: "Preview URL", value: payload.preview.url ?? "(none)" }
       ],
       nextSteps: renderWorkflowNextSteps(result),
-      report: payload
+      report: result
     });
   } catch (error) {
     return workflowErrorResult(error);

package/dist/cli/handlers/tasks.js

@@ -19,6 +19,7 @@ const handleTasks = async (_invocation, context) => {
       })),
       nextSteps: renderWorkflowNextSteps(result),
       report: {
+        ...result,
         tasks
       }
     });

package/dist/cli/handlers/utils.js

@@ -19,18 +19,25 @@ function guidedResult(options) {
       lines.push(`- ${step}`);
     }
   }
+  const report = options.report && typeof options.report === "object" ? {
+    ...options.report,
+    command: options.command,
+    ok: (options.exitCode ?? 0) === 0,
+    summary: options.summary,
+    facts: facts.map((fact) => ({ label: fact.label, value: fact.value })),
+    nextSteps: options.nextSteps ?? []
+  } : {
+    command: options.command,
+    ok: (options.exitCode ?? 0) === 0,
+    summary: options.summary,
+    facts: facts.map((fact) => ({ label: fact.label, value: fact.value })),
+    nextSteps: options.nextSteps ?? []
+  };
   return {
     exitCode: options.exitCode ?? 0,
     stdout: lines,
     stderr: options.stderr,
-    report: {
-      command: options.command,
-      ok: (options.exitCode ?? 0) === 0,
-      summary: options.summary,
-      facts: facts.map((fact) => ({ label: fact.label, value: fact.value })),
-      nextSteps: options.nextSteps ?? [],
-      ...options.report ?? {}
-    }
+    report
   };
 }
 function writeResult(result, context) {

package/dist/cli/handlers/workflow.js

@@ -10,15 +10,33 @@ function createWorkflowSdk(context, overrides = {}) {
 }
 function workflowErrorResult(error) {
   if (error instanceof TreeseedWorkflowError) {
+    const recovery = error.details?.recovery ?? null;
     return {
       exitCode: error.exitCode ?? (error.code === "merge_conflict" ? 12 : 1),
       stderr: [error.message],
       report: {
+        schemaVersion: 1,
+        kind: "treeseed.workflow.result",
+        command: error.operation,
+        executionMode: "execute",
+        runId: typeof recovery?.runId === "string" ? recovery.runId : null,
         ok: false,
+        operation: error.operation,
+        summary: error.message,
+        facts: [],
         error: error.message,
         code: error.code,
-        operation: error.operation,
-        details: error.details ?? null
+        payload: null,
+        result: null,
+        nextSteps: [],
+        recovery,
+        errors: [
+          {
+            code: error.code,
+            message: error.message,
+            details: error.details ?? null
+          }
+        ]
       }
     };
   }
@@ -27,8 +45,26 @@ function workflowErrorResult(error) {
     exitCode: 1,
     stderr: [message],
     report: {
+      schemaVersion: 1,
+      kind: "treeseed.workflow.result",
+      command: "status",
+      executionMode: "execute",
+      runId: null,
       ok: false,
-      error: message
+      operation: "status",
+      summary: message,
+      facts: [],
+      error: message,
+      payload: null,
+      result: null,
+      nextSteps: [],
+      recovery: null,
+      errors: [
+        {
+          code: "unsupported_state",
+          message
+        }
+      ]
     }
   };
 }
@@ -45,6 +81,10 @@ function renderWorkflowNextStep(step) {
       return `treeseed stage "${String(input.message ?? "describe the resolution")}"`;
     case "release":
       return `treeseed release --${String(input.bump ?? "patch")}`;
+    case "resume":
+      return `treeseed resume ${String(input.runId ?? "<run-id>")}`;
+    case "recover":
+      return "treeseed recover";
     case "config": {
       const environments = Array.isArray(input.environment) ? input.environment : Array.isArray(input.target) ? input.target : null;
       return environments?.length ? `treeseed config --environment ${environments[0]}` : "treeseed config";

package/dist/cli/operations-registry.js

@@ -202,9 +202,11 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
     arguments: [{ name: "branch-name", description: "Task branch to create or resume.", required: true }],
     options: [
       { name: "preview", flags: "--preview", description: "Provision or refresh a branch-scoped Cloudflare preview environment.", kind: "boolean" },
+      { name: "plan", flags: "--plan", description: "Compute the recursive branch switch plan without mutating any repo.", kind: "boolean" },
+      { name: "dryRun", flags: "--dry-run", description: "Alias for --plan.", kind: "boolean" },
       { name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }
     ],
-    examples: ["treeseed switch feature/search-improvements", "treeseed switch feature/search-improvements --preview"],
+    examples: ["treeseed switch feature/search-improvements", "treeseed switch feature/search-improvements --preview", "treeseed switch feature/search-improvements --plan"],
     help: {
       workflowPosition: "start work",
       longSummary: [
@@ -252,9 +254,11 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
     options: [
       { name: "hotfix", flags: "--hotfix", description: "Allow save on main for an explicit hotfix.", kind: "boolean" },
       { name: "preview", flags: "--preview", description: "Create or refresh the branch preview during save.", kind: "boolean" },
+      { name: "plan", flags: "--plan", description: "Compute the recursive save plan without mutating any repo.", kind: "boolean" },
+      { name: "dryRun", flags: "--dry-run", description: "Alias for --plan.", kind: "boolean" },
       { name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }
     ],
-    examples: ['treeseed save "feat: add search filters"', 'treeseed save --preview "feat: add search filters"', 'treeseed save --hotfix "fix: unblock production form submit"'],
+    examples: ['treeseed save "feat: add search filters"', 'treeseed save --preview "feat: add search filters"', 'treeseed save --plan "feat: add search filters"', 'treeseed save --hotfix "fix: unblock production form submit"'],
     help: {
       workflowPosition: "checkpoint work",
       longSummary: [
@@ -294,8 +298,12 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
   })],
   ["close", command({
     arguments: [{ name: "message", description: "Reason for closing the task without staging it.", required: true, kind: "message_tail" }],
-    options: [{ name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }],
-    examples: ['treeseed close "superseded by feature/search-v2"'],
+    options: [
+      { name: "plan", flags: "--plan", description: "Compute the recursive close plan without mutating any repo.", kind: "boolean" },
+      { name: "dryRun", flags: "--dry-run", description: "Alias for --plan.", kind: "boolean" },
+      { name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }
+    ],
+    examples: ['treeseed close "superseded by feature/search-v2"', 'treeseed close --plan "superseded by feature/search-v2"'],
     notes: ["Auto-saves meaningful uncommitted task-branch changes before cleanup unless disabled in the workflow API."],
     help: {
       workflowPosition: "abandon task",
@@ -328,8 +336,12 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
   })],
   ["stage", command({
     arguments: [{ name: "message", description: "Resolution message for the staged task.", required: true, kind: "message_tail" }],
-    options: [{ name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }],
-    examples: ['treeseed stage "feat: add search filters"'],
+    options: [
+      { name: "plan", flags: "--plan", description: "Compute the recursive staging plan without mutating any repo.", kind: "boolean" },
+      { name: "dryRun", flags: "--dry-run", description: "Alias for --plan.", kind: "boolean" },
+      { name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }
+    ],
+    examples: ['treeseed stage "feat: add search filters"', 'treeseed stage --plan "feat: add search filters"'],
     notes: ["Auto-saves meaningful uncommitted task-branch changes before merging into staging."],
     help: {
       workflowPosition: "merge to staging",
@@ -358,6 +370,56 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
     executionMode: "handler",
     handlerName: "stage"
   })],
+  ["resume", command({
+    arguments: [{ name: "run-id", description: "Interrupted workflow run id to resume.", required: true }],
+    options: [{ name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }],
+    examples: ["treeseed resume save-abcd12", "treeseed resume stage-ef3456 --json"],
+    help: {
+      workflowPosition: "recover",
+      longSummary: [
+        "Resume continues a previously interrupted journaled workflow run from its next incomplete step."
+      ],
+      whenToUse: [
+        "Use this after `treeseed recover` or a workflow failure tells you a run is resumable."
+      ],
+      beforeYouRun: [
+        "Confirm the run id from `treeseed recover` and repair any missing remotes, credentials, or package drift that caused the interruption."
+      ],
+      outcomes: [
+        "Re-enters the original workflow command using its recorded input and journal."
+      ],
+      automationNotes: [
+        "`resume --json` preserves the versioned workflow result envelope so agents can continue from a known run id without reparsing a different shape."
+      ]
+    },
+    executionMode: "handler",
+    handlerName: "resume"
+  })],
+  ["recover", command({
+    options: [{ name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }],
+    examples: ["treeseed recover", "treeseed recover --json"],
+    help: {
+      workflowPosition: "recover",
+      longSummary: [
+        "Recover lists the active workflow lock plus resumable interrupted runs so humans and agents can decide whether to resume, wait, or repair manually."
+      ],
+      whenToUse: [
+        "Use this before starting a new mutating workflow when you suspect another run may already hold the workspace lock.",
+        "Use this after any interrupted recursive save, stage, close, release, or destroy command."
+      ],
+      beforeYouRun: [
+        "Run it from the market workspace root or anywhere inside the tenant so the CLI can inspect the correct `.treeseed/workflow` journal directory."
+      ],
+      outcomes: [
+        "Reports the active workflow lock, interrupted runs, and the exact `treeseed resume <run-id>` command for resumable runs."
+      ],
+      automationNotes: [
+        "`recover --json` is the supported discovery entrypoint for agents that need to inspect lock state and resumable run ids safely before mutating the workspace."
+      ]
+    },
+    executionMode: "handler",
+    handlerName: "recover"
+  })],
   ["rollback", command({
     arguments: [{ name: "environment", description: "The persistent environment to roll back.", required: true }],
     options: [
@@ -668,9 +730,11 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
       { name: "major", flags: "--major", description: "Bump to the next major version.", kind: "boolean" },
       { name: "minor", flags: "--minor", description: "Bump to the next minor version.", kind: "boolean" },
       { name: "patch", flags: "--patch", description: "Bump to the next patch version.", kind: "boolean" },
+      { name: "plan", flags: "--plan", description: "Compute the recursive release plan without mutating any repo.", kind: "boolean" },
+      { name: "dryRun", flags: "--dry-run", description: "Alias for --plan.", kind: "boolean" },
       { name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }
     ],
-    examples: ["treeseed release --patch", "treeseed release --minor"],
+    examples: ["treeseed release --patch", "treeseed release --minor", "treeseed release --patch --plan"],
     notes: ["Requires exactly one bump flag."],
     help: {
       workflowPosition: "promote to production",
@@ -707,17 +771,18 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
     handlerName: "release"
   })],
   ["destroy", command({
-    usage: "treeseed destroy --environment <local|staging|prod> [--dry-run] [--force] [--skip-confirmation] [--confirm <slug>] [--remove-build-artifacts]",
+    usage: "treeseed destroy --environment <local|staging|prod> [--plan|--dry-run] [--force] [--skip-confirmation] [--confirm <slug>] [--remove-build-artifacts]",
     options: [
       { name: "environment", flags: "--environment <scope>", description: "Select the persistent environment to destroy.", kind: "enum", values: ["local", "staging", "prod"] },
-      { name: "dryRun", flags: "--dry-run", description: "Preview the destroy operation.", kind: "boolean" },
+      { name: "plan", flags: "--plan", description: "Compute the destroy plan without mutating the environment.", kind: "boolean" },
+      { name: "dryRun", flags: "--dry-run", description: "Alias for --plan.", kind: "boolean" },
       { name: "force", flags: "--force", description: "Force worker deletion when supported.", kind: "boolean" },
       { name: "skipConfirmation", flags: "--skip-confirmation", description: "Skip the interactive confirmation prompt.", kind: "boolean" },
       { name: "confirm", flags: "--confirm <slug>", description: "Provide the expected slug confirmation non-interactively.", kind: "string" },
       { name: "removeBuildArtifacts", flags: "--remove-build-artifacts", description: "Also remove local build artifacts after destroy.", kind: "boolean" },
       { name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }
     ],
-    examples: ["treeseed destroy --environment staging --dry-run", "treeseed destroy --environment prod --confirm example --skip-confirmation"],
+    examples: ["treeseed destroy --environment staging --plan", "treeseed destroy --environment prod --confirm example --skip-confirmation"],
     notes: ["Only for persistent environments. Task cleanup belongs to treeseed close.", "This command is destructive and requires explicit confirmation."],
     help: {
       workflowPosition: "tear down environment",
@@ -726,7 +791,7 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
       ],
       whenToUse: [
         "Use this when a persistent environment should be intentionally removed rather than rolled back or updated.",
-        "Use `--dry-run` first when you want to inspect the destroy plan without committing to it."
+        "Use `--plan` first when you want to inspect the destroy plan without committing to it."
       ],
       beforeYouRun: [
         "Confirm the environment scope exactly. This command does not target task-branch cleanup; it targets persistent environments only.",
@@ -737,7 +802,7 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
         "Optionally removes local build artifacts if requested."
       ],
       examples: [
-        example("treeseed destroy --environment staging --dry-run", "Preview the destroy plan", "Inspect what would be removed from staging without actually performing the destroy."),
+        example("treeseed destroy --environment staging --plan", "Preview the destroy plan", "Inspect what would be removed from staging without actually performing the destroy."),
         example("treeseed destroy --environment prod --confirm example --skip-confirmation", "Run a deliberate non-interactive destroy", "Provide the expected slug explicitly when operating in a scripted or no-prompt environment."),
         example("treeseed destroy --environment local --remove-build-artifacts", "Remove a local environment and its artifacts", "Destroy the local environment and also delete local build outputs.")
       ],

package/dist/cli/registry.d.ts

@@ -16,6 +16,8 @@ export declare const COMMAND_HANDLERS: {
     readonly tasks: import("./operations-types.js").TreeseedCommandHandler;
     readonly switch: import("./operations-types.js").TreeseedCommandHandler;
     readonly stage: import("./operations-types.js").TreeseedCommandHandler;
+    readonly resume: import("./operations-types.js").TreeseedCommandHandler;
+    readonly recover: import("./operations-types.js").TreeseedCommandHandler;
     readonly export: import("./operations-types.js").TreeseedCommandHandler;
     readonly 'auth:login': import("./operations-types.js").TreeseedCommandHandler;
     readonly 'auth:logout': import("./operations-types.js").TreeseedCommandHandler;

package/dist/cli/registry.js

@@ -22,6 +22,8 @@ import { handleTasks } from "./handlers/tasks.js";
 import { handleSwitch } from "./handlers/switch.js";
 import { handleStage } from "./handlers/stage.js";
 import { handleExport } from "./handlers/export.js";
+import { handleResume } from "./handlers/resume.js";
+import { handleRecover } from "./handlers/recover.js";
 const COMMAND_HANDLERS = {
   init: handleInit,
   config: handleConfig,
@@ -39,6 +41,8 @@ const COMMAND_HANDLERS = {
   tasks: handleTasks,
   switch: handleSwitch,
   stage: handleStage,
+  resume: handleResume,
+  recover: handleRecover,
   export: handleExport,
   "auth:login": handleAuthLogin,
   "auth:logout": handleAuthLogout,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeseed/cli",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "Operator-facing Treeseed CLI package.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -43,7 +43,7 @@
     "release:publish": "node ./scripts/run-ts.mjs ./scripts/publish-package.ts"
   },
   "dependencies": {
-    "@treeseed/sdk": "^0.4.9",
+    "@treeseed/sdk": "^0.4.13",
     "ink": "^7.0.0",
     "react": "^19.2.5"
   },

package/dist/cli/workflow-state.d.ts

@@ -1,58 +0,0 @@
-export type TreeseedBranchRole = 'feature' | 'staging' | 'main' | 'detached' | 'none';
-export type TreeseedWorkflowRecommendation = {
-    command: string;
-    reason: string;
-};
-export type TreeseedWorkflowState = {
-    cwd: string;
-    workspaceRoot: boolean;
-    tenantRoot: boolean;
-    deployConfigPresent: boolean;
-    repoRoot: string | null;
-    branchName: string | null;
-    branchRole: TreeseedBranchRole;
-    environment: 'local' | 'staging' | 'prod' | 'none';
-    dirtyWorktree: boolean;
-    preview: {
-        enabled: boolean;
-        url: string | null;
-        lastDeploymentTimestamp: string | null;
-    };
-    persistentEnvironments: Record<string, {
-        initialized: boolean;
-        lastValidatedAt: string | null;
-        lastDeploymentTimestamp: string | null;
-        lastDeployedUrl: string | null;
-    }>;
-    auth: {
-        gh: boolean;
-        wrangler: boolean;
-        railway: boolean;
-        copilot: boolean;
-        remoteApi: boolean;
-    };
-    managedServices: Record<string, {
-        enabled: boolean;
-        initialized: boolean;
-        lastDeploymentTimestamp: string | null;
-        lastDeployedUrl: string | null;
-        provider: string | null;
-    }>;
-    files: {
-        treeseedConfig: boolean;
-        machineConfig: boolean;
-        machineKey: boolean;
-        envLocal: boolean;
-        devVars: boolean;
-    };
-    releaseReady: boolean;
-    rollbackCandidates: Array<{
-        scope: 'staging' | 'prod';
-        commit: string | null;
-        timestamp: string | null;
-        url: string | null;
-    }>;
-    recommendations: TreeseedWorkflowRecommendation[];
-};
-export declare function resolveTreeseedWorkflowState(cwd: string): TreeseedWorkflowState;
-export declare function recommendTreeseedNextSteps(state: TreeseedWorkflowState): TreeseedWorkflowRecommendation[];

package/dist/cli/workflow-state.js

@@ -1,195 +0,0 @@
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
-import { getTreeseedMachineConfigPaths, resolveTreeseedRemoteSession } from "@treeseed/sdk/workflow-support";
-import {
-  createBranchPreviewDeployTarget,
-  createPersistentDeployTarget,
-  loadDeployState
-} from "@treeseed/sdk/workflow-support";
-import { PRODUCTION_BRANCH, STAGING_BRANCH } from "@treeseed/sdk/workflow-support";
-import { loadCliDeployConfig } from "@treeseed/sdk/workflow-support";
-import { collectCliPreflight } from "@treeseed/sdk/workflow-support";
-import { currentBranch, gitStatusPorcelain, repoRoot } from "@treeseed/sdk/workflow-support";
-import { isWorkspaceRoot } from "@treeseed/sdk/workflow-support";
-function safeResolveRepoRoot(cwd) {
-  try {
-    return repoRoot(cwd);
-  } catch {
-    return null;
-  }
-}
-function branchRoleFor(branchName) {
-  if (!branchName) return "none";
-  if (branchName === STAGING_BRANCH) return "staging";
-  if (branchName === PRODUCTION_BRANCH) return "main";
-  return "feature";
-}
-function environmentForBranchRole(branchRole) {
-  if (branchRole === "staging") return "staging";
-  if (branchRole === "main") return "prod";
-  if (branchRole === "feature") return "local";
-  return "none";
-}
-function emptyPersistentEnvironments() {
-  return {
-    local: { initialized: false, lastValidatedAt: null, lastDeploymentTimestamp: null, lastDeployedUrl: null },
-    staging: { initialized: false, lastValidatedAt: null, lastDeploymentTimestamp: null, lastDeployedUrl: null },
-    prod: { initialized: false, lastValidatedAt: null, lastDeploymentTimestamp: null, lastDeployedUrl: null }
-  };
-}
-function resolveTreeseedWorkflowState(cwd) {
-  const workspaceRoot = isWorkspaceRoot(cwd);
-  const treeseedConfigPath = resolve(cwd, "treeseed.site.yaml");
-  const tenantRoot = existsSync(treeseedConfigPath);
-  const root = safeResolveRepoRoot(cwd);
-  const branchName = root ? currentBranch(root) || null : null;
-  const branchRole = branchRoleFor(branchName);
-  const dirtyWorktree = root ? gitStatusPorcelain(root).length > 0 : false;
-  const preflight = collectCliPreflight({ cwd, requireAuth: false });
-  const { configPath, keyPath } = getTreeseedMachineConfigPaths(cwd);
-  const state = {
-    cwd,
-    workspaceRoot,
-    tenantRoot,
-    deployConfigPresent: tenantRoot,
-    repoRoot: root,
-    branchName,
-    branchRole,
-    environment: environmentForBranchRole(branchRole),
-    dirtyWorktree,
-    preview: {
-      enabled: false,
-      url: null,
-      lastDeploymentTimestamp: null
-    },
-    persistentEnvironments: emptyPersistentEnvironments(),
-    auth: {
-      gh: preflight.checks.auth.gh?.authenticated === true,
-      wrangler: preflight.checks.auth.wrangler?.authenticated === true,
-      railway: preflight.checks.auth.railway?.authenticated === true,
-      copilot: preflight.checks.auth.copilot?.configured === true,
-      remoteApi: Boolean(resolveTreeseedRemoteSession(cwd))
-    },
-    managedServices: {
-      api: { enabled: false, initialized: false, lastDeploymentTimestamp: null, lastDeployedUrl: null, provider: null },
-      agents: { enabled: false, initialized: false, lastDeploymentTimestamp: null, lastDeployedUrl: null, provider: null },
-      manager: { enabled: false, initialized: false, lastDeploymentTimestamp: null, lastDeployedUrl: null, provider: null },
-      worker: { enabled: false, initialized: false, lastDeploymentTimestamp: null, lastDeployedUrl: null, provider: null },
-      workdayStart: { enabled: false, initialized: false, lastDeploymentTimestamp: null, lastDeployedUrl: null, provider: null },
-      workdayReport: { enabled: false, initialized: false, lastDeploymentTimestamp: null, lastDeployedUrl: null, provider: null }
-    },
-    files: {
-      treeseedConfig: tenantRoot,
-      machineConfig: existsSync(configPath),
-      machineKey: existsSync(keyPath),
-      envLocal: existsSync(resolve(cwd, ".env.local")),
-      devVars: existsSync(resolve(cwd, ".dev.vars"))
-    },
-    releaseReady: branchRole === "staging" && !dirtyWorktree,
-    rollbackCandidates: [],
-    recommendations: []
-  };
-  if (tenantRoot) {
-    try {
-      const deployConfig = loadCliDeployConfig(cwd);
-      for (const scope of ["local", "staging", "prod"]) {
-        const deployState = loadDeployState(cwd, deployConfig, { target: createPersistentDeployTarget(scope) });
-        state.persistentEnvironments[scope] = {
-          initialized: deployState.readiness?.initialized === true || scope === "local",
-          lastValidatedAt: deployState.readiness?.lastValidatedAt ?? deployState.readiness?.initializedAt ?? null,
-          lastDeploymentTimestamp: deployState.lastDeploymentTimestamp ?? null,
-          lastDeployedUrl: deployState.lastDeployedUrl ?? null
-        };
-        if (scope !== "local") {
-          const history = Array.isArray(deployState.deploymentHistory) ? deployState.deploymentHistory ?? [] : [];
-          const latestHistory = history.at(-1) ?? null;
-          state.rollbackCandidates.push({
-            scope,
-            commit: typeof latestHistory?.commit === "string" ? latestHistory.commit : deployState.lastDeployedCommit ?? null,
-            timestamp: typeof latestHistory?.timestamp === "string" ? latestHistory.timestamp : deployState.lastDeploymentTimestamp ?? null,
-            url: typeof latestHistory?.url === "string" ? latestHistory.url : deployState.lastDeployedUrl ?? null
-          });
-        }
-        for (const serviceKey of ["api", "agents", "manager", "worker", "workdayStart", "workdayReport"]) {
-          const service = deployState.services?.[serviceKey];
-          if (!service) continue;
-          state.managedServices[serviceKey] = {
-            enabled: service.enabled === true,
-            initialized: service.initialized === true,
-            lastDeploymentTimestamp: service.lastDeploymentTimestamp ?? null,
-            lastDeployedUrl: service.lastDeployedUrl ?? service.publicBaseUrl ?? null,
-            provider: service.provider ?? null
-          };
-        }
-      }
-      if (branchRole === "feature" && branchName) {
-        const previewState = loadDeployState(cwd, deployConfig, { target: createBranchPreviewDeployTarget(branchName) });
-        state.preview = {
-          enabled: previewState.previewEnabled === true || previewState.readiness?.initialized === true,
-          url: previewState.lastDeployedUrl ?? null,
-          lastDeploymentTimestamp: previewState.lastDeploymentTimestamp ?? null
-        };
-      }
-    } catch {
-    }
-  }
-  state.recommendations = recommendTreeseedNextSteps(state);
-  return state;
-}
-function recommendTreeseedNextSteps(state) {
-  const recommendations = [];
-  if (!state.workspaceRoot) {
-    return [{ command: "treeseed status", reason: "Run this command from inside a Treeseed workspace so the CLI can resolve the project root." }];
-  }
-  if (!state.deployConfigPresent) {
-    return [{ command: "treeseed init <directory>", reason: "Create a new Treeseed tenant before configuring or releasing anything." }];
-  }
-  if (!state.files.machineConfig) {
-    recommendations.push({ command: "treeseed status", reason: "Validate tooling, auth, and repository readiness first." });
-    recommendations.push({ command: "treeseed config", reason: "Bootstrap the local machine config and local environment files." });
-    return recommendations;
-  }
-  if (state.branchRole === "feature") {
-    if (state.dirtyWorktree) {
-      recommendations.push({ command: 'treeseed save "describe your change"', reason: "Persist, verify, and push the current task branch before staging or closing it." });
-    } else {
-      recommendations.push({ command: 'treeseed stage "describe the resolution"', reason: "Merge this task branch into staging and clean up branch artifacts." });
-    }
-    if (state.preview.enabled && state.branchName) {
-      recommendations.push({ command: 'treeseed save "describe your change"', reason: "Save refreshes the branch preview deployment when one is enabled." });
-    } else {
-      recommendations.push({ command: "treeseed dev", reason: "Use the local environment for iterative work on this feature branch." });
-    }
-    recommendations.push({ command: 'treeseed close "reason"', reason: "Archive this task without merging if it should be abandoned." });
-    return recommendations.slice(0, 3);
-  }
-  if (state.branchRole === "staging") {
-    if (!state.persistentEnvironments.staging.initialized) {
-      recommendations.push({ command: "treeseed config --environment staging", reason: "Initialize the staging environment before releasing." });
-    } else {
-      recommendations.push({ command: "treeseed release --patch", reason: "Promote staging into main when the integration branch is ready for production." });
-      if (state.managedServices.api.enabled || state.managedServices.agents.enabled) {
-        recommendations.push({ command: "treeseed auth:login", reason: "Keep the local CLI authenticated to the remote API used by managed services." });
-      }
-    }
-    return recommendations.slice(0, 3);
-  }
-  if (state.branchRole === "main") {
-    if (state.dirtyWorktree) {
-      recommendations.push({ command: 'treeseed save --hotfix "describe the hotfix"', reason: "Only explicit hotfix saves are allowed on main." });
-    } else if (!state.persistentEnvironments.prod.initialized) {
-      recommendations.push({ command: "treeseed config --environment prod", reason: "Initialize production before a release requires it." });
-    } else {
-      recommendations.push({ command: "treeseed status", reason: "Inspect production state and release readiness." });
-      recommendations.push({ command: "treeseed rollback prod", reason: "Roll back production to the previous recorded deployment if needed." });
-    }
-    return recommendations.slice(0, 3);
-  }
-  recommendations.push({ command: "treeseed dev", reason: "Start the local Treeseed development environment." });
-  recommendations.push({ command: "treeseed switch feature/my-change", reason: "Create a task branch from the latest staging commit." });
-  return recommendations.slice(0, 3);
-}
-export {
-  recommendTreeseedNextSteps,
-  resolveTreeseedWorkflowState
-};