@treeseed/sdk 0.6.9 → 0.6.11

package/dist/workflow/runs.d.ts

@@ -2,6 +2,25 @@ 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 TreeseedWorkflowRunClassificationState = 'resumable' | 'stale' | 'obsolete';
+export type TreeseedWorkflowRunClassification = {
+    state: TreeseedWorkflowRunClassificationState;
+    reasons: string[];
+    classifiedAt: string;
+    archivedAt?: string | null;
+};
+export type TreeseedWorkflowGateCacheEntry = {
+    repo: string | null;
+    workflow: string;
+    headSha: string;
+    branch: string | null;
+    status: string;
+    conclusion: string | null;
+    runId: string | number | null;
+    url: string | null;
+    cachedAt: string;
+    result: Record<string, unknown>;
+};
 export type TreeseedWorkflowRunStep = {
     id: string;
     description: string;
@@ -42,6 +61,8 @@ export type TreeseedWorkflowRunJournal = {
         at: string;
     };
     result: Record<string, unknown> | null;
+    classification?: TreeseedWorkflowRunClassification | null;
+    gateCache?: TreeseedWorkflowGateCacheEntry[];
 };
 export type TreeseedWorkflowLockRecord = {
     schemaVersion: 1;
@@ -78,6 +99,23 @@ export declare function releaseWorkflowLock(root: string, runId: string): boolea
 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 classifyWorkflowRunJournal(journal: TreeseedWorkflowRunJournal, options?: {
+    currentBranch?: string | null;
+    currentHeads?: Record<string, string | null | undefined>;
+    now?: string;
+}): TreeseedWorkflowRunClassification;
+export declare function classifyWorkflowRunJournals(root: string, options?: Parameters<typeof classifyWorkflowRunJournal>[1]): {
+    journal: TreeseedWorkflowRunJournal;
+    classification: TreeseedWorkflowRunClassification;
+}[];
+export declare function archiveWorkflowRun(root: string, runId: string, classification: TreeseedWorkflowRunClassification): TreeseedWorkflowRunJournal | null;
+export declare function getCachedSuccessfulWorkflowGate(root: string, runId: string, gate: {
+    repository?: string | null;
+    workflow: string;
+    headSha: string;
+    branch?: string | null;
+}): TreeseedWorkflowGateCacheEntry | null;
+export declare function cacheWorkflowGateResult(root: string, runId: string, result: Record<string, unknown>): TreeseedWorkflowGateCacheEntry | null;
 export declare function createWorkflowRunJournal(root: string, options: {
     runId: string;
     command: TreeseedWorkflowRunCommand;

package/dist/workflow/runs.js

@@ -1,23 +1,45 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 const WORKFLOW_CONTROL_DIR = ".treeseed/workflow";
 const WORKFLOW_RUNS_DIR = `${WORKFLOW_CONTROL_DIR}/runs`;
+const WORKTREE_METADATA_PATH = ".treeseed/worktree.json";
 const LOCK_STALE_AFTER_MS = 4 * 60 * 60 * 1e3;
+const WORKFLOW_RUN_STORAGE_ROOTS = /* @__PURE__ */ new Map();
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
-function workflowControlRoot(root) {
-  return resolve(root, WORKFLOW_CONTROL_DIR);
+function managedWorktreePrimaryRoot(root) {
+  const metadataPath = resolve(root, WORKTREE_METADATA_PATH);
+  if (!existsSync(metadataPath)) return null;
+  try {
+    const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
+    return metadata.kind === "treeseed.workflow.worktree" && typeof metadata.primaryRoot === "string" ? metadata.primaryRoot : null;
+  } catch {
+    return null;
+  }
+}
+function workflowStorageRoot(root, runId) {
+  if (runId && WORKFLOW_RUN_STORAGE_ROOTS.has(runId)) {
+    return WORKFLOW_RUN_STORAGE_ROOTS.get(runId);
+  }
+  const storageRoot = managedWorktreePrimaryRoot(root) ?? root;
+  if (runId) {
+    WORKFLOW_RUN_STORAGE_ROOTS.set(runId, storageRoot);
+  }
+  return storageRoot;
+}
+function workflowControlRoot(root, runId) {
+  return resolve(workflowStorageRoot(root, runId), WORKFLOW_CONTROL_DIR);
 }
-function workflowRunsRoot(root) {
-  return resolve(root, WORKFLOW_RUNS_DIR);
+function workflowRunsRoot(root, runId) {
+  return resolve(workflowStorageRoot(root, runId), WORKFLOW_RUNS_DIR);
 }
-function workflowLockPath(root) {
-  return resolve(root, WORKFLOW_CONTROL_DIR, "lock.json");
+function workflowLockPath(root, runId) {
+  return resolve(workflowStorageRoot(root, runId), WORKFLOW_CONTROL_DIR, "lock.json");
 }
 function workflowRunPath(root, runId) {
-  return resolve(root, WORKFLOW_RUNS_DIR, `${runId}.json`);
+  return resolve(workflowStorageRoot(root, runId), WORKFLOW_RUNS_DIR, `${runId}.json`);
 }
 function resolveGitDir(root) {
   const gitPath = resolve(root, ".git");
@@ -46,12 +68,13 @@ function ensureWorkflowExcludeRule(root) {
   if (current.includes(pattern)) {
     return;
   }
+  mkdirSync(dirname(excludePath), { recursive: true });
   writeFileSync(excludePath, `${current}${current.endsWith("\n") || current.length === 0 ? "" : "\n"}${pattern}
 `, "utf8");
 }
-function ensureWorkflowControlDirs(root) {
-  const controlDir = workflowControlRoot(root);
-  const runsDir = workflowRunsRoot(root);
+function ensureWorkflowControlDirs(root, runId) {
+  const controlDir = workflowControlRoot(root, runId);
+  const runsDir = workflowRunsRoot(root, runId);
   mkdirSync(runsDir, { recursive: true });
   ensureWorkflowExcludeRule(root);
   writeFileSync(resolve(controlDir, ".gitignore"), "*\n!.gitignore\n!runs/\nruns/*\n!runs/.gitignore\n", "utf8");
@@ -114,7 +137,7 @@ function inspectWorkflowLock(root) {
   };
 }
 function acquireWorkflowLock(root, command, runId) {
-  const dirs = ensureWorkflowControlDirs(root);
+  const dirs = ensureWorkflowControlDirs(root, runId);
   const inspection = inspectWorkflowLock(root);
   if (inspection.active && inspection.lock && inspection.lock.runId !== runId) {
     return {
@@ -148,7 +171,7 @@ function acquireWorkflowLock(root, command, runId) {
   };
 }
 function refreshWorkflowLock(root, runId) {
-  const path = workflowLockPath(root);
+  const path = workflowLockPath(root, runId);
   const lock = safeJsonParse(path);
   if (!lock || lock.runId !== runId) {
     return null;
@@ -164,7 +187,7 @@ function refreshWorkflowLock(root, runId) {
   return updated;
 }
 function releaseWorkflowLock(root, runId) {
-  const path = workflowLockPath(root);
+  const path = workflowLockPath(root, runId);
   const lock = safeJsonParse(path);
   if (!lock || lock.runId !== runId) {
     return false;
@@ -173,7 +196,7 @@ function releaseWorkflowLock(root, runId) {
   return true;
 }
 function writeWorkflowRunJournal(root, journal) {
-  ensureWorkflowControlDirs(root);
+  ensureWorkflowControlDirs(root, journal.runId);
   writeFileSync(workflowRunPath(root, journal.runId), `${JSON.stringify(journal, null, 2)}
 `, "utf8");
   return journal;
@@ -193,6 +216,145 @@ function updateWorkflowRunJournal(root, runId, updater) {
   });
   return readWorkflowRunJournal(root, runId);
 }
+function stringRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function journalReleasePlanHead(plan, repoName) {
+  if (repoName === "@treeseed/market") {
+    const rootRepo = stringRecord(plan.rootRepo);
+    return typeof rootRepo?.commitSha === "string" ? rootRepo.commitSha : null;
+  }
+  const repos = Array.isArray(plan.repos) ? plan.repos : [];
+  for (const repo of repos) {
+    const record = stringRecord(repo);
+    if (record?.name === repoName) {
+      return typeof record.commitSha === "string" ? record.commitSha : null;
+    }
+  }
+  return null;
+}
+function selectedReleasePackageNames(plan) {
+  const selection = stringRecord(plan.packageSelection);
+  const selected = Array.isArray(selection?.selected) ? selection.selected.filter((name) => typeof name === "string") : [];
+  return selected;
+}
+function classifyWorkflowRunJournal(journal, options = {}) {
+  const reasons = [];
+  const now = options.now ?? nowIso();
+  if (journal.classification?.archivedAt) {
+    return {
+      state: "obsolete",
+      reasons: journal.classification.reasons.length > 0 ? journal.classification.reasons : ["workflow run was archived"],
+      classifiedAt: now,
+      archivedAt: journal.classification.archivedAt
+    };
+  }
+  if (journal.status !== "failed") {
+    return {
+      state: "obsolete",
+      reasons: [`workflow run status is ${journal.status}`],
+      classifiedAt: now
+    };
+  }
+  if (!journal.resumable) {
+    return {
+      state: "obsolete",
+      reasons: ["workflow run is not marked resumable"],
+      classifiedAt: now
+    };
+  }
+  if (journal.command === "switch" && journal.steps.every((step) => step.status === "pending")) {
+    return {
+      state: "obsolete",
+      reasons: ["switch failed before completing any checkout step; rerun switch instead"],
+      classifiedAt: now
+    };
+  }
+  if (options.currentBranch && journal.session.branchName && options.currentBranch !== journal.session.branchName) {
+    reasons.push(`current branch ${options.currentBranch} does not match journal branch ${journal.session.branchName}`);
+  }
+  if (journal.command === "release" && options.currentHeads) {
+    const releasePlan = stringRecord(journal.steps.find((step) => step.id === "release-plan")?.data);
+    if (releasePlan) {
+      const rootHead = options.currentHeads["@treeseed/market"];
+      const plannedRootHead = journalReleasePlanHead(releasePlan, "@treeseed/market");
+      if (rootHead && plannedRootHead && rootHead !== plannedRootHead) {
+        reasons.push(`market head changed from ${plannedRootHead} to ${rootHead}`);
+      }
+      for (const name of selectedReleasePackageNames(releasePlan)) {
+        const currentHead = options.currentHeads[name];
+        const plannedHead = journalReleasePlanHead(releasePlan, name);
+        if (currentHead && plannedHead && currentHead !== plannedHead) {
+          reasons.push(`${name} head changed from ${plannedHead} to ${currentHead}`);
+        }
+      }
+    }
+  }
+  return {
+    state: reasons.length > 0 ? "stale" : "resumable",
+    reasons: reasons.length > 0 ? reasons : ["workflow run can be resumed"],
+    classifiedAt: now
+  };
+}
+function classifyWorkflowRunJournals(root, options = {}) {
+  return listWorkflowRunJournals(root).map((journal) => ({
+    journal,
+    classification: classifyWorkflowRunJournal(journal, options)
+  }));
+}
+function archiveWorkflowRun(root, runId, classification) {
+  const archivedAt = nowIso();
+  return updateWorkflowRunJournal(root, runId, (journal) => ({
+    ...journal,
+    resumable: false,
+    classification: {
+      ...classification,
+      state: classification.state === "resumable" ? "stale" : classification.state,
+      archivedAt,
+      classifiedAt: archivedAt
+    }
+  }));
+}
+function gateCacheMatches(entry, gate) {
+  return entry.workflow === gate.workflow && entry.headSha === gate.headSha && (gate.repository == null || entry.repo === gate.repository) && (gate.branch == null || entry.branch === gate.branch);
+}
+function getCachedSuccessfulWorkflowGate(root, runId, gate) {
+  const journal = readWorkflowRunJournal(root, runId);
+  const cache = journal?.gateCache ?? [];
+  return cache.find((entry) => gateCacheMatches(entry, gate) && entry.status === "completed" && entry.conclusion === "success") ?? null;
+}
+function cacheWorkflowGateResult(root, runId, result) {
+  const workflow = typeof result.workflow === "string" ? result.workflow : null;
+  const headSha = typeof result.headSha === "string" ? result.headSha : null;
+  if (!workflow || !headSha) {
+    return null;
+  }
+  const entry = {
+    repo: typeof result.repository === "string" ? result.repository : null,
+    workflow,
+    headSha,
+    branch: typeof result.branch === "string" ? result.branch : null,
+    status: typeof result.status === "string" ? result.status : "unknown",
+    conclusion: typeof result.conclusion === "string" ? result.conclusion : null,
+    runId: typeof result.runId === "string" || typeof result.runId === "number" ? result.runId : null,
+    url: typeof result.url === "string" ? result.url : null,
+    cachedAt: nowIso(),
+    result
+  };
+  updateWorkflowRunJournal(root, runId, (journal) => ({
+    ...journal,
+    gateCache: [
+      ...(journal.gateCache ?? []).filter((candidate) => !gateCacheMatches(candidate, {
+        repository: entry.repo,
+        workflow: entry.workflow,
+        headSha: entry.headSha,
+        branch: entry.branch
+      })),
+      entry
+    ]
+  }));
+  return entry;
+}
 function createWorkflowRunJournal(root, options) {
   const timestamp = nowIso();
   return writeWorkflowRunJournal(root, {
@@ -229,8 +391,13 @@ function listInterruptedWorkflowRuns(root) {
 }
 export {
   acquireWorkflowLock,
+  archiveWorkflowRun,
+  cacheWorkflowGateResult,
+  classifyWorkflowRunJournal,
+  classifyWorkflowRunJournals,
   createWorkflowRunJournal,
   generateWorkflowRunId,
+  getCachedSuccessfulWorkflowGate,
   inspectWorkflowLock,
   listInterruptedWorkflowRuns,
   listWorkflowRunJournals,

package/dist/workflow/worktrees.d.ts

@@ -0,0 +1,39 @@
+import type { TreeseedWorkflowWorktreeMode } from '../workflow.ts';
+export type ManagedWorkflowWorktreeMetadata = {
+    schemaVersion: 1;
+    kind: 'treeseed.workflow.worktree';
+    branch: string;
+    worktreePath: string;
+    primaryRoot: string;
+    ownerMode: 'agent' | 'human' | 'explicit';
+    createdAt: string;
+    lastUsedAt: string;
+};
+export type ManagedWorkflowWorktreeResult = ManagedWorkflowWorktreeMetadata & {
+    created: boolean;
+    resumed: boolean;
+};
+export declare function effectiveWorkflowWorktreeMode(mode: TreeseedWorkflowWorktreeMode | undefined, env?: NodeJS.ProcessEnv | Record<string, string | undefined>): "off" | "on";
+export declare function isManagedWorkflowWorktree(root: string): boolean;
+export declare function managedWorkflowWorktreeMetadata(root: string): ManagedWorkflowWorktreeMetadata | null;
+export declare function plannedManagedWorkflowWorktreePath(root: string, branchName: string): string;
+export declare function primaryWorkspaceRoot(root: string): any;
+export declare function ensureManagedWorkflowWorktree({ root, branchName, mode, env, }: {
+    root: string;
+    branchName: string;
+    mode?: TreeseedWorkflowWorktreeMode;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+}): ManagedWorkflowWorktreeResult;
+export declare function removeManagedWorkflowWorktree(root: string): {
+    removed: boolean;
+    reason: string;
+    worktreePath?: undefined;
+    primaryRoot?: undefined;
+    branch?: undefined;
+} | {
+    removed: boolean;
+    worktreePath: string;
+    primaryRoot: string;
+    branch: string;
+    reason?: undefined;
+};

package/dist/workflow/worktrees.js

@@ -0,0 +1,224 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { sortWorkspacePackages, workspacePackages, workspaceRoot } from "../operations/services/workspace-tools.js";
+import { repoRoot } from "../operations/services/workspace-save.js";
+const WORKTREE_METADATA_PATH = ".treeseed/worktree.json";
+const WORKTREE_ROOT = ".treeseed/worktrees";
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function runGit(args, { cwd, capture = true, allowFailure = false }) {
+  const result = spawnSync("git", args, {
+    cwd,
+    stdio: capture ? "pipe" : "inherit",
+    encoding: "utf8"
+  });
+  if (result.status !== 0 && !allowFailure) {
+    throw new Error(result.stderr?.trim() || result.stdout?.trim() || `git ${args.join(" ")} failed`);
+  }
+  return result;
+}
+function slugifyBranch(branchName) {
+  return branchName.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "branch";
+}
+function worktreeDirectoryName(branchName) {
+  const hash = createHash("sha256").update(branchName).digest("hex").slice(0, 10);
+  return `${slugifyBranch(branchName)}-${hash}`;
+}
+function parseWorktreeList(output) {
+  const entries = [];
+  let current = null;
+  for (const line of output.split(/\r?\n/u)) {
+    if (line.startsWith("worktree ")) {
+      if (current) entries.push(current);
+      current = { worktree: line.slice("worktree ".length).trim(), branch: null };
+      continue;
+    }
+    if (current && line.startsWith("branch ")) {
+      current.branch = line.slice("branch ".length).trim().replace(/^refs\/heads\//u, "");
+    }
+  }
+  if (current) entries.push(current);
+  return entries;
+}
+function worktreeList(repoDir) {
+  return parseWorktreeList(runGit(["worktree", "list", "--porcelain"], { cwd: repoDir }).stdout ?? "");
+}
+function currentBranchName(repoDir) {
+  return runGit(["branch", "--show-current"], { cwd: repoDir, allowFailure: true }).stdout?.trim() || null;
+}
+function localBranchExists(repoDir, branchName) {
+  return runGit(["show-ref", "--verify", "--quiet", `refs/heads/${branchName}`], { cwd: repoDir, allowFailure: true }).status === 0;
+}
+function remoteBranchExists(repoDir, branchName) {
+  return Boolean(runGit(["ls-remote", "--heads", "origin", branchName], { cwd: repoDir, allowFailure: true }).stdout?.trim());
+}
+function checkoutManagedPackageBranch(repoDir, branchName) {
+  runGit(["fetch", "origin"], { cwd: repoDir, allowFailure: true });
+  const baseBranch = remoteBranchExists(repoDir, "staging") ? "staging" : remoteBranchExists(repoDir, "main") ? "main" : null;
+  if (localBranchExists(repoDir, branchName)) {
+    runGit(["checkout", branchName], { cwd: repoDir });
+  } else if (remoteBranchExists(repoDir, branchName)) {
+    runGit(["checkout", "-b", branchName, `origin/${branchName}`], { cwd: repoDir });
+  } else if (baseBranch) {
+    runGit(["checkout", "-b", branchName, `origin/${baseBranch}`], { cwd: repoDir });
+  } else {
+    return;
+  }
+  if (remoteBranchExists(repoDir, branchName)) {
+    runGit(["merge", "--ff-only", `origin/${branchName}`], { cwd: repoDir, allowFailure: true });
+  }
+}
+function checkoutManagedPackageBranches(worktreePath, branchName) {
+  for (const pkg of sortWorkspacePackages(workspacePackages(worktreePath))) {
+    if (!pkg.name?.startsWith("@treeseed/")) continue;
+    if (!existsSync(resolve(pkg.dir, ".git"))) continue;
+    checkoutManagedPackageBranch(pkg.dir, branchName);
+  }
+}
+function metadataPath(root) {
+  return resolve(root, WORKTREE_METADATA_PATH);
+}
+function readMetadata(root) {
+  const filePath = metadataPath(root);
+  if (!existsSync(filePath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+    return parsed?.kind === "treeseed.workflow.worktree" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function writeMetadata(root, metadata) {
+  const filePath = metadataPath(root);
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(metadata, null, 2)}
+`, "utf8");
+}
+function ensureManagedWorktreeExclude(root) {
+  const commonGitDir = runGit(["rev-parse", "--git-common-dir"], { cwd: root }).stdout?.trim();
+  if (!commonGitDir) return;
+  const absolutePath = resolve(root, commonGitDir, "info", "exclude");
+  const current = existsSync(absolutePath) ? readFileSync(absolutePath, "utf8") : "";
+  const patterns = ["/.treeseed/worktree.json", "/.treeseed/workflow/", "/.treeseed/worktrees/"];
+  const missing = patterns.filter((pattern) => !current.includes(pattern));
+  if (missing.length === 0) return;
+  mkdirSync(dirname(absolutePath), { recursive: true });
+  writeFileSync(
+    absolutePath,
+    `${current}${current.endsWith("\n") || current.length === 0 ? "" : "\n"}${missing.join("\n")}
+`,
+    "utf8"
+  );
+}
+function effectiveWorkflowWorktreeMode(mode, env = process.env) {
+  const envMode = String(env.TREESEED_WORKTREE_MODE ?? "").trim().toLowerCase();
+  if (mode === "on" || envMode === "on" || envMode === "true" || envMode === "1") return "on";
+  if (mode === "off" || envMode === "off" || envMode === "false" || envMode === "0") return "off";
+  const agentMarkers = [
+    env.TREESEED_WORKFLOW_ACTOR === "agent",
+    env.TREESEED_AGENT_ID,
+    env.TREESEED_AGENT_RUN_ID,
+    env.CODEX_AGENT_ID,
+    env.CODEX_TASK_ID
+  ].some(Boolean);
+  return agentMarkers ? "on" : "off";
+}
+function isManagedWorkflowWorktree(root) {
+  return readMetadata(root) != null;
+}
+function managedWorkflowWorktreeMetadata(root) {
+  return readMetadata(root);
+}
+function plannedManagedWorkflowWorktreePath(root, branchName) {
+  const primaryRoot = primaryWorkspaceRoot(root);
+  return resolve(primaryRoot, WORKTREE_ROOT, worktreeDirectoryName(branchName));
+}
+function primaryWorkspaceRoot(root) {
+  const gitRoot = repoRoot(workspaceRoot(root));
+  const entries = worktreeList(gitRoot);
+  const first = entries[0]?.worktree;
+  return first ? workspaceRoot(first) : workspaceRoot(root);
+}
+function ensureManagedWorkflowWorktree({
+  root,
+  branchName,
+  mode = "auto",
+  env = process.env
+}) {
+  const effectiveMode = effectiveWorkflowWorktreeMode(mode, env);
+  if (effectiveMode !== "on") {
+    throw new Error("Managed workflow worktree mode is disabled.");
+  }
+  const primaryRoot = primaryWorkspaceRoot(root);
+  const primaryGitRoot = repoRoot(primaryRoot);
+  const worktreePath = plannedManagedWorkflowWorktreePath(primaryRoot, branchName);
+  const entries = worktreeList(primaryGitRoot);
+  const existingEntry = entries.find((entry) => entry.worktree === worktreePath);
+  const duplicate = entries.find((entry) => entry.branch === branchName && entry.worktree !== worktreePath);
+  if (duplicate) {
+    throw new Error(`Branch ${branchName} is already checked out in ${duplicate.worktree}.`);
+  }
+  const created = !existingEntry && !existsSync(worktreePath);
+  runGit(["fetch", "origin"], { cwd: primaryGitRoot });
+  const branchExists = remoteBranchExists(primaryGitRoot, branchName);
+  const baseRef = branchExists ? `origin/${branchName}` : "origin/staging";
+  if (created) {
+    mkdirSync(dirname(worktreePath), { recursive: true });
+    runGit(["worktree", "add", "--detach", worktreePath, baseRef], { cwd: primaryGitRoot });
+  } else if (!existingEntry) {
+    runGit(["worktree", "prune"], { cwd: primaryGitRoot, allowFailure: true });
+  } else if (!currentBranchName(worktreePath)) {
+    runGit(["fetch", "origin"], { cwd: worktreePath, allowFailure: true });
+    runGit(["reset", "--hard", baseRef], { cwd: worktreePath });
+  }
+  runGit(["submodule", "update", "--init", "--recursive"], { cwd: worktreePath });
+  checkoutManagedPackageBranches(worktreePath, branchName);
+  ensureManagedWorktreeExclude(worktreePath);
+  const timestamp = nowIso();
+  const previous = readMetadata(worktreePath);
+  const metadata = {
+    schemaVersion: 1,
+    kind: "treeseed.workflow.worktree",
+    branch: branchName,
+    worktreePath,
+    primaryRoot,
+    ownerMode: mode === "on" ? "explicit" : "agent",
+    createdAt: previous?.createdAt ?? timestamp,
+    lastUsedAt: timestamp
+  };
+  writeMetadata(worktreePath, metadata);
+  return {
+    ...metadata,
+    created,
+    resumed: !created
+  };
+}
+function removeManagedWorkflowWorktree(root) {
+  const metadata = readMetadata(root);
+  if (!metadata) {
+    return { removed: false, reason: "not-managed" };
+  }
+  const primaryRoot = metadata.primaryRoot;
+  const primaryGitRoot = repoRoot(primaryRoot);
+  process.chdir(primaryRoot);
+  runGit(["worktree", "remove", "--force", metadata.worktreePath], { cwd: primaryGitRoot });
+  rmSync(metadata.worktreePath, { recursive: true, force: true });
+  return {
+    removed: true,
+    worktreePath: metadata.worktreePath,
+    primaryRoot,
+    branch: metadata.branch
+  };
+}
+export {
+  effectiveWorkflowWorktreeMode,
+  ensureManagedWorkflowWorktree,
+  isManagedWorkflowWorktree,
+  managedWorkflowWorktreeMetadata,
+  plannedManagedWorkflowWorktreePath,
+  primaryWorkspaceRoot,
+  removeManagedWorkflowWorktree
+};

package/dist/workflow-state.d.ts

@@ -62,6 +62,19 @@ export type TreeseedWorkflowState = {
             updatedAt: string;
             nextStep: string | null;
         }>;
+        staleRuns: Array<{
+            runId: string;
+            command: string;
+            updatedAt: string;
+            nextStep: string | null;
+            reasons: string[];
+        }>;
+        obsoleteRuns: Array<{
+            runId: string;
+            command: string;
+            updatedAt: string;
+            reasons: string[];
+        }>;
         blockers: string[];
     };
     packageSync: {

package/dist/workflow-state.js

@@ -24,7 +24,7 @@ import { collectCliPreflight } from "./operations/services/workspace-preflight.j
 import { currentBranch, gitStatusPorcelain } from "./operations/services/workspace-save.js";
 import { hasCompleteTreeseedPackageCheckout, isWorkspaceRoot, run, workspacePackages } from "./operations/services/workspace-tools.js";
 import { inspectWorkspaceDependencyMode } from "./operations/services/workspace-dependency-mode.js";
-import { inspectWorkflowLock, listInterruptedWorkflowRuns } from "./workflow/runs.js";
+import { classifyWorkflowRunJournals, inspectWorkflowLock } from "./workflow/runs.js";
 import { createTreeseedManagedToolEnv, resolveTreeseedToolCommand } from "./managed-dependencies.js";
 import {
   resolveTreeseedWorkflowPaths,
@@ -248,6 +248,13 @@ function knownRemoteTrackingBranchExists(repoDir, branchName) {
     return false;
   }
 }
+function safeHeadCommit(repoDir) {
+  try {
+    return run("git", ["rev-parse", "HEAD"], { cwd: repoDir, capture: true }).trim();
+  } catch {
+    return null;
+  }
+}
 function resolveLocalStatusUrl(deployConfig) {
   return deployConfig.surfaces?.web?.localBaseUrl ?? deployConfig.surfaces?.api?.localBaseUrl ?? Object.values(deployConfig.services ?? {}).find((service) => service?.enabled !== false && service.environments?.local?.baseUrl)?.environments?.local?.baseUrl ?? null;
 }
@@ -312,12 +319,36 @@ function resolveTreeseedWorkflowState(cwd, options = {}) {
   const runnerHostId = typeof marketSettings?.runnerHostId === "string" && marketSettings.runnerHostId.trim() ? marketSettings.runnerHostId.trim() : typeof marketSettings?.projectId === "string" && marketSettings.projectId.trim() ? `market-runner:${marketSettings.projectId.trim()}` : null;
   const runnerSession = runnerHostId ? safeResolveRemoteSession(effectiveCwd, runnerHostId) : null;
   const workflowLock = inspectWorkflowLock(effectiveCwd);
-  const interruptedRuns = listInterruptedWorkflowRuns(effectiveCwd).map((journal) => ({
+  const workflowRunHeads = {};
+  if (root) {
+    workflowRunHeads["@treeseed/market"] = safeHeadCommit(root);
+  }
+  for (const pkg of completePackageCheckout ? workspacePackages(effectiveCwd).filter((entry) => entry.name?.startsWith("@treeseed/")) : []) {
+    workflowRunHeads[pkg.name] = safeHeadCommit(pkg.dir);
+  }
+  const classifiedRuns = classifyWorkflowRunJournals(effectiveCwd, {
+    currentBranch: branchName,
+    currentHeads: workflowRunHeads
+  });
+  const interruptedRuns = classifiedRuns.filter((entry) => entry.classification.state === "resumable").map(({ journal }) => ({
     runId: journal.runId,
     command: journal.command,
     updatedAt: journal.updatedAt,
     nextStep: journal.steps.find((step) => step.status === "pending")?.description ?? null
   }));
+  const staleRuns = classifiedRuns.filter((entry) => entry.classification.state === "stale").map(({ journal, classification }) => ({
+    runId: journal.runId,
+    command: journal.command,
+    updatedAt: journal.updatedAt,
+    nextStep: journal.steps.find((step) => step.status === "pending")?.description ?? null,
+    reasons: classification.reasons
+  }));
+  const obsoleteRuns = classifiedRuns.filter((entry) => entry.classification.state === "obsolete").map(({ journal, classification }) => ({
+    runId: journal.runId,
+    command: journal.command,
+    updatedAt: journal.updatedAt,
+    reasons: classification.reasons
+  }));
   const workflowBlockers = [];
   if (workflowLock.active && workflowLock.lock) {
     workflowBlockers.push(`Workflow lock active for ${workflowLock.lock.command} (${workflowLock.lock.runId}).`);
@@ -348,6 +379,8 @@ function resolveTreeseedWorkflowState(cwd, options = {}) {
         staleReason: workflowLock.staleReason
       },
       interruptedRuns,
+      staleRuns,
+      obsoleteRuns,
       blockers: workflowBlockers
     },
     packageSync: {