@treeseed/sdk 0.4.11 → 0.4.13

package/dist/workflow/runs.d.ts

@@ -0,0 +1,90 @@
+import type { TreeseedWorkflowMode } from './session.ts';
+export type TreeseedWorkflowRunCommand = 'switch' | 'save' | 'close' | 'stage' | 'release' | 'destroy';
+export type TreeseedWorkflowExecutionMode = 'execute' | 'plan';
+export type TreeseedWorkflowRunStatus = 'running' | 'failed' | 'completed';
+export type TreeseedWorkflowRunStep = {
+    id: string;
+    description: string;
+    repoName: string | null;
+    repoPath: string | null;
+    branch: string | null;
+    resumable: boolean;
+    status: 'pending' | 'completed' | 'skipped';
+    completedAt: string | null;
+    data: Record<string, unknown> | null;
+};
+export type TreeseedWorkflowRunJournal = {
+    schemaVersion: 1;
+    kind: 'treeseed.workflow.run';
+    runId: string;
+    command: TreeseedWorkflowRunCommand;
+    executionMode: TreeseedWorkflowExecutionMode;
+    status: TreeseedWorkflowRunStatus;
+    createdAt: string;
+    updatedAt: string;
+    resumable: boolean;
+    input: Record<string, unknown>;
+    session: {
+        root: string;
+        mode: TreeseedWorkflowMode;
+        branchName: string | null;
+        repos: Array<{
+            name: string;
+            path: string;
+            branchName: string | null;
+        }>;
+    };
+    steps: TreeseedWorkflowRunStep[];
+    failure: null | {
+        code: string;
+        message: string;
+        details: Record<string, unknown> | null;
+        at: string;
+    };
+    result: Record<string, unknown> | null;
+};
+export type TreeseedWorkflowLockRecord = {
+    schemaVersion: 1;
+    kind: 'treeseed.workflow.lock';
+    runId: string;
+    command: TreeseedWorkflowRunCommand;
+    root: string;
+    host: string;
+    pid: number | null;
+    createdAt: string;
+    updatedAt: string;
+    stale: boolean;
+    staleReason: string | null;
+};
+export type TreeseedWorkflowLockInspection = {
+    lock: TreeseedWorkflowLockRecord | null;
+    active: boolean;
+    stale: boolean;
+    staleReason: string | null;
+};
+export declare function generateWorkflowRunId(command: TreeseedWorkflowRunCommand): string;
+export declare function inspectWorkflowLock(root: string): TreeseedWorkflowLockInspection;
+export declare function acquireWorkflowLock(root: string, command: TreeseedWorkflowRunCommand, runId: string): {
+    readonly acquired: false;
+    readonly lock: TreeseedWorkflowLockRecord;
+    readonly replacedStale?: undefined;
+} | {
+    readonly acquired: true;
+    readonly lock: TreeseedWorkflowLockRecord;
+    readonly replacedStale: boolean;
+};
+export declare function refreshWorkflowLock(root: string, runId: string): TreeseedWorkflowLockRecord | null;
+export declare function releaseWorkflowLock(root: string, runId: string): boolean;
+export declare function writeWorkflowRunJournal(root: string, journal: TreeseedWorkflowRunJournal): TreeseedWorkflowRunJournal;
+export declare function readWorkflowRunJournal(root: string, runId: string): TreeseedWorkflowRunJournal | null;
+export declare function updateWorkflowRunJournal(root: string, runId: string, updater: (journal: TreeseedWorkflowRunJournal) => TreeseedWorkflowRunJournal): TreeseedWorkflowRunJournal | null;
+export declare function createWorkflowRunJournal(root: string, options: {
+    runId: string;
+    command: TreeseedWorkflowRunCommand;
+    executionMode?: TreeseedWorkflowExecutionMode;
+    input: Record<string, unknown>;
+    session: TreeseedWorkflowRunJournal['session'];
+    steps: Omit<TreeseedWorkflowRunStep, 'status' | 'completedAt' | 'data'>[];
+}): TreeseedWorkflowRunJournal;
+export declare function listWorkflowRunJournals(root: string): TreeseedWorkflowRunJournal[];
+export declare function listInterruptedWorkflowRuns(root: string): TreeseedWorkflowRunJournal[];

package/dist/workflow/runs.js

@@ -0,0 +1,242 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { resolve } from "node:path";
+const WORKFLOW_CONTROL_DIR = ".treeseed/workflow";
+const WORKFLOW_RUNS_DIR = `${WORKFLOW_CONTROL_DIR}/runs`;
+const LOCK_STALE_AFTER_MS = 4 * 60 * 60 * 1e3;
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function workflowControlRoot(root) {
+  return resolve(root, WORKFLOW_CONTROL_DIR);
+}
+function workflowRunsRoot(root) {
+  return resolve(root, WORKFLOW_RUNS_DIR);
+}
+function workflowLockPath(root) {
+  return resolve(root, WORKFLOW_CONTROL_DIR, "lock.json");
+}
+function workflowRunPath(root, runId) {
+  return resolve(root, WORKFLOW_RUNS_DIR, `${runId}.json`);
+}
+function resolveGitDir(root) {
+  const gitPath = resolve(root, ".git");
+  if (existsSync(resolve(gitPath, "info"))) {
+    return gitPath;
+  }
+  if (!existsSync(gitPath)) {
+    return null;
+  }
+  try {
+    const gitFile = readFileSync(gitPath, "utf8").trim();
+    const match = gitFile.match(/^gitdir:\s*(.+)$/u);
+    return match ? resolve(root, match[1]) : null;
+  } catch {
+    return null;
+  }
+}
+function ensureWorkflowExcludeRule(root) {
+  const gitDir = resolveGitDir(root);
+  if (!gitDir) {
+    return;
+  }
+  const excludePath = resolve(gitDir, "info", "exclude");
+  const pattern = "/.treeseed/workflow/";
+  const current = existsSync(excludePath) ? readFileSync(excludePath, "utf8") : "";
+  if (current.includes(pattern)) {
+    return;
+  }
+  writeFileSync(excludePath, `${current}${current.endsWith("\n") || current.length === 0 ? "" : "\n"}${pattern}
+`, "utf8");
+}
+function ensureWorkflowControlDirs(root) {
+  const controlDir = workflowControlRoot(root);
+  const runsDir = workflowRunsRoot(root);
+  mkdirSync(runsDir, { recursive: true });
+  ensureWorkflowExcludeRule(root);
+  writeFileSync(resolve(controlDir, ".gitignore"), "*\n!.gitignore\n!runs/\nruns/*\n!runs/.gitignore\n", "utf8");
+  writeFileSync(resolve(runsDir, ".gitignore"), "*\n!.gitignore\n", "utf8");
+  return {
+    controlDir,
+    runsDir,
+    lockPath: workflowLockPath(root)
+  };
+}
+function safeJsonParse(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function pidIsAlive(pid) {
+  if (!Number.isInteger(pid) || (pid ?? 0) <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function generateWorkflowRunId(command) {
+  return `${command}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function inspectWorkflowLock(root) {
+  const lock = safeJsonParse(workflowLockPath(root));
+  if (!lock) {
+    return {
+      lock: null,
+      active: false,
+      stale: false,
+      staleReason: null
+    };
+  }
+  let staleReason = null;
+  if (lock.host === hostname() && lock.pid != null && !pidIsAlive(lock.pid)) {
+    staleReason = `process ${lock.pid} is no longer running`;
+  } else if (Date.now() - Date.parse(lock.updatedAt) > LOCK_STALE_AFTER_MS) {
+    staleReason = "lock heartbeat expired";
+  }
+  return {
+    lock: {
+      ...lock,
+      stale: staleReason != null,
+      staleReason
+    },
+    active: staleReason == null,
+    stale: staleReason != null,
+    staleReason
+  };
+}
+function acquireWorkflowLock(root, command, runId) {
+  const dirs = ensureWorkflowControlDirs(root);
+  const inspection = inspectWorkflowLock(root);
+  if (inspection.active && inspection.lock && inspection.lock.runId !== runId) {
+    return {
+      acquired: false,
+      lock: inspection.lock
+    };
+  }
+  if (inspection.stale) {
+    rmSync(dirs.lockPath, { force: true });
+  }
+  const timestamp = nowIso();
+  const lock = {
+    schemaVersion: 1,
+    kind: "treeseed.workflow.lock",
+    runId,
+    command,
+    root,
+    host: hostname(),
+    pid: process.pid,
+    createdAt: inspection.lock?.runId === runId ? inspection.lock.createdAt : timestamp,
+    updatedAt: timestamp,
+    stale: false,
+    staleReason: null
+  };
+  writeFileSync(dirs.lockPath, `${JSON.stringify(lock, null, 2)}
+`, "utf8");
+  return {
+    acquired: true,
+    lock,
+    replacedStale: inspection.stale
+  };
+}
+function refreshWorkflowLock(root, runId) {
+  const path = workflowLockPath(root);
+  const lock = safeJsonParse(path);
+  if (!lock || lock.runId !== runId) {
+    return null;
+  }
+  const updated = {
+    ...lock,
+    updatedAt: nowIso(),
+    stale: false,
+    staleReason: null
+  };
+  writeFileSync(path, `${JSON.stringify(updated, null, 2)}
+`, "utf8");
+  return updated;
+}
+function releaseWorkflowLock(root, runId) {
+  const path = workflowLockPath(root);
+  const lock = safeJsonParse(path);
+  if (!lock || lock.runId !== runId) {
+    return false;
+  }
+  rmSync(path, { force: true });
+  return true;
+}
+function writeWorkflowRunJournal(root, journal) {
+  ensureWorkflowControlDirs(root);
+  writeFileSync(workflowRunPath(root, journal.runId), `${JSON.stringify(journal, null, 2)}
+`, "utf8");
+  return journal;
+}
+function readWorkflowRunJournal(root, runId) {
+  return safeJsonParse(workflowRunPath(root, runId));
+}
+function updateWorkflowRunJournal(root, runId, updater) {
+  const current = readWorkflowRunJournal(root, runId);
+  if (!current) {
+    return null;
+  }
+  const updated = updater(current);
+  writeWorkflowRunJournal(root, {
+    ...updated,
+    updatedAt: nowIso()
+  });
+  return readWorkflowRunJournal(root, runId);
+}
+function createWorkflowRunJournal(root, options) {
+  const timestamp = nowIso();
+  return writeWorkflowRunJournal(root, {
+    schemaVersion: 1,
+    kind: "treeseed.workflow.run",
+    runId: options.runId,
+    command: options.command,
+    executionMode: options.executionMode ?? "execute",
+    status: "running",
+    createdAt: timestamp,
+    updatedAt: timestamp,
+    resumable: options.steps.every((step) => step.resumable),
+    input: options.input,
+    session: options.session,
+    steps: options.steps.map((step) => ({
+      ...step,
+      status: "pending",
+      completedAt: null,
+      data: null
+    })),
+    failure: null,
+    result: null
+  });
+}
+function listWorkflowRunJournals(root) {
+  const runsDir = workflowRunsRoot(root);
+  if (!existsSync(runsDir)) {
+    return [];
+  }
+  return readdirSync(runsDir).filter((entry) => entry.endsWith(".json")).map((entry) => safeJsonParse(resolve(runsDir, entry))).filter((entry) => entry != null).sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+}
+function listInterruptedWorkflowRuns(root) {
+  return listWorkflowRunJournals(root).filter((journal) => journal.status === "failed" && journal.resumable);
+}
+export {
+  acquireWorkflowLock,
+  createWorkflowRunJournal,
+  generateWorkflowRunId,
+  inspectWorkflowLock,
+  listInterruptedWorkflowRuns,
+  listWorkflowRunJournals,
+  readWorkflowRunJournal,
+  refreshWorkflowLock,
+  releaseWorkflowLock,
+  updateWorkflowRunJournal,
+  writeWorkflowRunJournal
+};

package/dist/workflow/session.d.ts

@@ -0,0 +1,31 @@
+import { type TreeseedWorkflowBranchRole } from './policy.ts';
+export type TreeseedWorkflowMode = 'root-only' | 'recursive-workspace';
+export type TreeseedWorkflowSessionRepo = {
+    name: string;
+    path: string;
+    relativePath: string;
+    branchName: string | null;
+    branchRole: TreeseedWorkflowBranchRole;
+    dirty: boolean;
+    detached: boolean;
+    hasOriginRemote: boolean;
+};
+export type TreeseedWorkflowPackageSelection = {
+    changed: string[];
+    dependents: string[];
+    selected: string[];
+};
+export type TreeseedWorkflowSession = {
+    root: string;
+    gitRoot: string;
+    mode: TreeseedWorkflowMode;
+    branchName: string | null;
+    branchRole: TreeseedWorkflowBranchRole;
+    rootRepo: TreeseedWorkflowSessionRepo;
+    packageRepos: TreeseedWorkflowSessionRepo[];
+    packageSelection: TreeseedWorkflowPackageSelection;
+};
+export declare function checkedOutWorkspacePackageRepos(root: string): any[];
+export declare function workflowModeForRoot(root: string): TreeseedWorkflowMode;
+export declare function collectReleasePackageSelection(root: string): TreeseedWorkflowPackageSelection;
+export declare function resolveTreeseedWorkflowSession(cwd: string): TreeseedWorkflowSession;

package/dist/workflow/session.js

@@ -0,0 +1,97 @@
+import { relative } from "node:path";
+import {
+  currentBranch,
+  gitStatusPorcelain,
+  originRemoteUrl,
+  repoRoot
+} from "../operations/services/workspace-save.js";
+import {
+  changedWorkspacePackages,
+  hasCompleteTreeseedPackageCheckout,
+  publishableWorkspacePackages,
+  sortWorkspacePackages,
+  workspacePackages,
+  workspaceRoot
+} from "../operations/services/workspace-tools.js";
+import {
+  classifyTreeseedBranchRole,
+  resolveTreeseedWorkflowPaths
+} from "./policy.js";
+function hasOriginRemote(repoDir) {
+  try {
+    originRemoteUrl(repoDir);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function repoState(root, name, repoDir) {
+  const branchName = currentBranch(repoDir) || null;
+  return {
+    name,
+    path: repoDir,
+    relativePath: relative(root, repoDir).replaceAll("\\", "/") || ".",
+    branchName,
+    branchRole: classifyTreeseedBranchRole(branchName, repoDir),
+    dirty: gitStatusPorcelain(repoDir).length > 0,
+    detached: branchName == null,
+    hasOriginRemote: hasOriginRemote(repoDir)
+  };
+}
+function checkedOutWorkspacePackageRepos(root) {
+  if (!hasCompleteTreeseedPackageCheckout(root)) {
+    return [];
+  }
+  return sortWorkspacePackages(
+    workspacePackages(root).filter((pkg) => pkg.name?.startsWith("@treeseed/"))
+  );
+}
+function workflowModeForRoot(root) {
+  return hasCompleteTreeseedPackageCheckout(root) ? "recursive-workspace" : "root-only";
+}
+function collectReleasePackageSelection(root) {
+  const publishable = sortWorkspacePackages(
+    publishableWorkspacePackages(root).filter((pkg) => pkg.name?.startsWith("@treeseed/"))
+  );
+  const changed = changedWorkspacePackages({
+    root,
+    baseRef: "main",
+    includeDependents: false,
+    packages: publishable
+  });
+  const selected = changedWorkspacePackages({
+    root,
+    baseRef: "main",
+    includeDependents: true,
+    packages: publishable
+  });
+  const changedNames = changed.map((pkg) => pkg.name);
+  return {
+    changed: changedNames,
+    dependents: selected.filter((pkg) => !changedNames.includes(pkg.name)).map((pkg) => pkg.name),
+    selected: selected.map((pkg) => pkg.name)
+  };
+}
+function resolveTreeseedWorkflowSession(cwd) {
+  const resolved = resolveTreeseedWorkflowPaths(cwd);
+  const root = workspaceRoot(resolved.cwd);
+  const gitRoot = repoRoot(root);
+  const mode = workflowModeForRoot(root);
+  const packageRepos = checkedOutWorkspacePackageRepos(root).map((pkg) => repoState(root, pkg.name, pkg.dir));
+  return {
+    root,
+    gitRoot,
+    mode,
+    branchName: currentBranch(gitRoot) || null,
+    branchRole: classifyTreeseedBranchRole(currentBranch(gitRoot) || null, gitRoot),
+    rootRepo: repoState(root, "@treeseed/market", gitRoot),
+    packageRepos,
+    packageSelection: collectReleasePackageSelection(root)
+  };
+}
+export {
+  checkedOutWorkspacePackageRepos,
+  collectReleasePackageSelection,
+  resolveTreeseedWorkflowSession,
+  workflowModeForRoot
+};

package/dist/workflow-state.d.ts

@@ -12,6 +12,40 @@ export type TreeseedWorkflowState = {
     branchRole: TreeseedBranchRole;
     environment: 'local' | 'staging' | 'prod' | 'none';
     dirtyWorktree: boolean;
+    workflowControl: {
+        lock: {
+            active: boolean;
+            stale: boolean;
+            runId: string | null;
+            command: string | null;
+            updatedAt: string | null;
+            staleReason: string | null;
+        };
+        interruptedRuns: Array<{
+            runId: string;
+            command: string;
+            updatedAt: string;
+            nextStep: string | null;
+        }>;
+        blockers: string[];
+    };
+    packageSync: {
+        mode: 'root-only' | 'recursive-workspace';
+        completeCheckout: boolean;
+        expectedBranch: string | null;
+        aligned: boolean;
+        dirty: boolean;
+        repos: Array<{
+            name: string;
+            path: string;
+            branchName: string | null;
+            dirty: boolean;
+            aligned: boolean;
+            localBranch: boolean;
+            remoteBranch: boolean;
+        }>;
+        blockers: string[];
+    };
     preview: {
         enabled: boolean;
         url: string | null;

package/dist/workflow-state.js

@@ -8,8 +8,9 @@ import {
 } from "./operations/services/deploy.js";
 import { loadCliDeployConfig } from "./operations/services/runtime-tools.js";
 import { collectCliPreflight } from "./operations/services/workspace-preflight.js";
-import { gitStatusPorcelain } from "./operations/services/workspace-save.js";
-import { isWorkspaceRoot } from "./operations/services/workspace-tools.js";
+import { currentBranch, gitStatusPorcelain } from "./operations/services/workspace-save.js";
+import { hasCompleteTreeseedPackageCheckout, isWorkspaceRoot, run, workspacePackages } from "./operations/services/workspace-tools.js";
+import { inspectWorkflowLock, listInterruptedWorkflowRuns } from "./workflow/runs.js";
 import {
   resolveTreeseedWorkflowPaths,
   workflowEnvironmentForBranchRole
@@ -48,6 +49,14 @@ function readinessForEnvironment(state, scope) {
     warnings
   };
 }
+function knownRemoteTrackingBranchExists(repoDir, branchName) {
+  try {
+    run("git", ["show-ref", "--verify", "--quiet", `refs/remotes/origin/${branchName}`], { cwd: repoDir, capture: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
 function resolveTreeseedWorkflowState(cwd) {
   const resolved = resolveTreeseedWorkflowPaths(cwd);
   const effectiveCwd = resolved.cwd;
@@ -58,8 +67,67 @@ function resolveTreeseedWorkflowState(cwd) {
   const branchName = resolved.branchName;
   const branchRole = resolved.branchRole;
   const dirtyWorktree = root ? gitStatusPorcelain(root).length > 0 : false;
+  const completePackageCheckout = hasCompleteTreeseedPackageCheckout(effectiveCwd);
+  const packageSyncRepos = completePackageCheckout ? workspacePackages(effectiveCwd).filter((pkg) => pkg.name?.startsWith("@treeseed/")).map((pkg) => {
+    const repoBranch = currentBranch(pkg.dir) || null;
+    const dirty = gitStatusPorcelain(pkg.dir).length > 0;
+    const expectedBranch = branchName;
+    let localBranch = false;
+    if (expectedBranch) {
+      if (repoBranch === expectedBranch) {
+        localBranch = true;
+      } else {
+        try {
+          run("git", ["show-ref", "--verify", "--quiet", `refs/heads/${expectedBranch}`], { cwd: pkg.dir, capture: true });
+          localBranch = true;
+        } catch {
+          localBranch = false;
+        }
+      }
+    }
+    const remoteBranch = Boolean(expectedBranch) ? knownRemoteTrackingBranchExists(pkg.dir, expectedBranch) : false;
+    return {
+      name: pkg.name,
+      path: pkg.relativeDir,
+      branchName: repoBranch,
+      dirty,
+      aligned: expectedBranch ? repoBranch === expectedBranch : true,
+      localBranch,
+      remoteBranch
+    };
+  }) : [];
+  const packageSyncBlockers = [];
+  for (const repo of packageSyncRepos) {
+    if (repo.dirty) {
+      packageSyncBlockers.push(`${repo.name} has uncommitted changes.`);
+    }
+    if (branchName && !repo.localBranch && !repo.remoteBranch) {
+      packageSyncBlockers.push(`${repo.name} is missing branch ${branchName}.`);
+      continue;
+    }
+    if (branchName && !repo.aligned) {
+      packageSyncBlockers.push(`${repo.name} is on ${repo.branchName ?? "(detached)"} instead of ${branchName}.`);
+    }
+  }
   const preflight = collectCliPreflight({ cwd: effectiveCwd, requireAuth: false });
   const { configPath, keyPath } = getTreeseedMachineConfigPaths(effectiveCwd);
+  const workflowLock = inspectWorkflowLock(effectiveCwd);
+  const interruptedRuns = listInterruptedWorkflowRuns(effectiveCwd).map((journal) => ({
+    runId: journal.runId,
+    command: journal.command,
+    updatedAt: journal.updatedAt,
+    nextStep: journal.steps.find((step) => step.status === "pending")?.description ?? null
+  }));
+  const workflowBlockers = [];
+  if (workflowLock.active && workflowLock.lock) {
+    workflowBlockers.push(`Workflow lock active for ${workflowLock.lock.command} (${workflowLock.lock.runId}).`);
+  }
+  if (workflowLock.stale && workflowLock.lock) {
+    workflowBlockers.push(`Workflow lock is stale: ${workflowLock.staleReason}.`);
+  }
+  if (interruptedRuns.length > 0) {
+    workflowBlockers.push(`Interrupted workflow runs detected: ${interruptedRuns.map((run2) => run2.runId).join(", ")}.`);
+  }
   const state = {
     cwd: effectiveCwd,
     workspaceRoot,
@@ -70,6 +138,27 @@ function resolveTreeseedWorkflowState(cwd) {
     branchRole,
     environment: workflowEnvironmentForBranchRole(branchRole),
     dirtyWorktree,
+    workflowControl: {
+      lock: {
+        active: workflowLock.active,
+        stale: workflowLock.stale,
+        runId: workflowLock.lock?.runId ?? null,
+        command: workflowLock.lock?.command ?? null,
+        updatedAt: workflowLock.lock?.updatedAt ?? null,
+        staleReason: workflowLock.staleReason
+      },
+      interruptedRuns,
+      blockers: workflowBlockers
+    },
+    packageSync: {
+      mode: completePackageCheckout ? "recursive-workspace" : "root-only",
+      completeCheckout: completePackageCheckout,
+      expectedBranch: branchName,
+      aligned: packageSyncRepos.every((repo) => repo.aligned),
+      dirty: packageSyncRepos.some((repo) => repo.dirty),
+      repos: packageSyncRepos,
+      blockers: packageSyncBlockers
+    },
     preview: {
       enabled: false,
       url: null,
@@ -171,7 +260,27 @@ function recommendTreeseedNextSteps(state) {
     recommendations.push({ operation: "config", reason: "Bootstrap the local machine config and local environment files." });
     return recommendations;
   }
+  if (state.workflowControl.interruptedRuns.length > 0) {
+    recommendations.push({
+      operation: "resume",
+      reason: "Resume the most recent interrupted workflow run before making new branch changes.",
+      input: { runId: state.workflowControl.interruptedRuns[0].runId }
+    });
+    recommendations.push({ operation: "recover", reason: "Inspect active workflow locks and interrupted runs." });
+    return recommendations.slice(0, 3);
+  }
+  if (state.workflowControl.lock.active && state.workflowControl.lock.runId) {
+    recommendations.push({ operation: "recover", reason: "Inspect the active workflow lock before starting another mutating command." });
+    return recommendations.slice(0, 3);
+  }
   if (state.branchRole === "feature") {
+    if (state.packageSync.mode === "recursive-workspace" && state.packageSync.blockers.length > 0 && state.branchName) {
+      recommendations.push({
+        operation: "switch",
+        reason: "Realign the checked-out package repos to the current task branch before continuing.",
+        input: { branch: state.branchName }
+      });
+    }
     recommendations.push({ operation: "stage", reason: "Merge this task branch into staging and clean up branch artifacts.", input: { message: "describe the resolution" } });
     recommendations.push({ operation: "save", reason: "Persist, verify, and push the current task branch before or independently of staging it.", input: { message: "describe your change" } });
     if (state.preview.enabled && state.branchName) {
@@ -183,6 +292,13 @@ function recommendTreeseedNextSteps(state) {
     return recommendations.slice(0, 3);
   }
   if (state.branchRole === "staging") {
+    if (state.packageSync.mode === "recursive-workspace" && state.packageSync.blockers.length > 0 && state.branchName) {
+      recommendations.push({
+        operation: "switch",
+        reason: "Realign the checked-out package repos to staging before releasing.",
+        input: { branch: state.branchName }
+      });
+    }
     if (!state.persistentEnvironments.staging.initialized) {
       recommendations.push({ operation: "config", reason: "Initialize the staging environment before releasing.", input: { environment: ["staging"] } });
     } else {