@treeseed/sdk 0.6.31 → 0.6.33

package/dist/operations/services/git-workflow.d.ts

@@ -162,8 +162,9 @@ export declare function mergeStagingIntoMain(cwd?: any): {
     commitSha: string;
     pushed: boolean;
 };
-export declare function mergeBranchIntoTarget(cwd?: any, { sourceBranch, targetBranch, message, pushTarget }?: {
+export declare function mergeBranchIntoTarget(cwd?: any, { sourceBranch, targetBranch, message, pushTarget, quietMerge }?: {
     pushTarget?: boolean | undefined;
+    quietMerge?: boolean | undefined;
 }): {
     repoDir: string;
     targetBranch: any;

package/dist/operations/services/git-workflow.js

@@ -425,13 +425,13 @@ function mergeStagingIntoMain(cwd = workspaceRoot()) {
     pushTarget: true
   });
 }
-function mergeBranchIntoTarget(cwd = workspaceRoot(), { sourceBranch, targetBranch, message, pushTarget = true } = {}) {
+function mergeBranchIntoTarget(cwd = workspaceRoot(), { sourceBranch, targetBranch, message, pushTarget = true, quietMerge = false } = {}) {
   const repoDir = prepareReleaseBranches(cwd);
   checkoutBranch(repoDir, targetBranch);
   if (remoteBranchExists(repoDir, targetBranch)) {
     runGit(["merge", "--ff-only", `origin/${targetBranch}`], { cwd: repoDir });
   }
-  runGit(["merge", "--no-ff", sourceBranch, "-m", message], { cwd: repoDir });
+  runGit(["merge", "--no-ff", sourceBranch, "-m", message], { cwd: repoDir, capture: quietMerge });
   pushBranch(repoDir, STAGING_BRANCH);
   if (pushTarget) {
     pushBranch(repoDir, targetBranch);

package/dist/operations/services/github-actions-verification.js

@@ -431,6 +431,21 @@ function formatElapsed(seconds) {
 function shortSha(value) {
   return value ? value.slice(0, 12) : "(unknown)";
 }
+function activeJobSummary(event) {
+  const activeJobs = event.activeJobs ?? [];
+  if (activeJobs.length === 0) return "";
+  const summaries = activeJobs.slice(0, 2).map((job) => {
+    const activeStep = (job.steps ?? []).find((step) => step.status && step.status !== "completed");
+    return activeStep?.name ? `${job.name} > ${activeStep.name}` : job.name;
+  }).filter(Boolean);
+  return summaries.length > 0 ? `; active: ${summaries.join(", ")}` : "";
+}
+function failedJobSummary(event) {
+  const failedJobs = event.failedJobs ?? [];
+  if (failedJobs.length === 0) return "";
+  const names = failedJobs.slice(0, 3).map((job) => job.name).filter(Boolean);
+  return names.length > 0 ? `; failed: ${names.join(", ")}` : "";
+}
 function formatGitHubActionsGateProgress(gate, event, operation) {
   const prefix = `[${operation}][gate][${gate.name}] ${event.workflow}`;
   if (event.type === "waiting") {
@@ -439,12 +454,12 @@ function formatGitHubActionsGateProgress(gate, event, operation) {
   if (event.type === "completed") {
     const conclusion = event.conclusion === "success" ? "successfully" : `with conclusion ${event.conclusion ?? "unknown"}`;
     const url2 = event.url ? `: ${event.url}` : "";
-    return `${prefix} completed ${conclusion} in ${formatElapsed(event.elapsedSeconds)}${url2}`;
+    return `${prefix} completed ${conclusion}${failedJobSummary(event)} in ${formatElapsed(event.elapsedSeconds)}${url2}`;
   }
   const status = event.status ?? "waiting";
   const url = event.url ? `: ${event.url}` : "";
   const run = event.runId ? ` run ${event.runId}` : "";
-  return `${prefix}${run} ${status}${url} (${formatElapsed(event.elapsedSeconds)} elapsed)`;
+  return `${prefix}${run} ${status}${activeJobSummary(event)}${url} (${formatElapsed(event.elapsedSeconds)} elapsed)`;
 }
 async function waitForGitHubActionsGate(gate, options = {}) {
   const { waitForGitHubWorkflowCompletion } = await import("./github-automation.js");

package/dist/operations/services/github-api.d.ts

@@ -33,6 +33,12 @@ export interface GitHubWorkflowJobSummary {
     status: string | null;
     conclusion: string | null;
     url: string | null;
+    steps?: GitHubWorkflowJobStepSummary[];
+}
+export interface GitHubWorkflowJobStepSummary {
+    name: string;
+    status: string | null;
+    conclusion: string | null;
 }
 export type GitHubWorkflowProgressEvent = {
     type: 'waiting' | 'running' | 'completed';
@@ -45,6 +51,10 @@ export type GitHubWorkflowProgressEvent = {
     url: string | null;
     status: string | null;
     conclusion: string | null;
+    jobs?: GitHubWorkflowJobSummary[];
+    activeJobs?: GitHubWorkflowJobSummary[];
+    completedJobs?: GitHubWorkflowJobSummary[];
+    failedJobs?: GitHubWorkflowJobSummary[];
 };
 export declare function resolveGitHubApiToken(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): string;
 export declare function parseGitHubRepositorySlug(value: string): {

package/dist/operations/services/github-api.js

@@ -529,9 +529,27 @@ function normalizeWorkflowJob(job) {
     name: String(job.name ?? ""),
     status: typeof job.status === "string" ? job.status : null,
     conclusion: typeof job.conclusion === "string" ? job.conclusion : null,
-    url: typeof job.html_url === "string" ? job.html_url : null
+    url: typeof job.html_url === "string" ? job.html_url : null,
+    steps: Array.isArray(job.steps) ? job.steps.map((step) => ({
+      name: String(step.name ?? ""),
+      status: typeof step.status === "string" ? step.status : null,
+      conclusion: typeof step.conclusion === "string" ? step.conclusion : null
+    })) : []
   };
 }
+async function listWorkflowJobsForProgress(client, owner, repo, runId) {
+  try {
+    const jobs = await client.rest.actions.listJobsForWorkflowRun({
+      owner,
+      repo,
+      run_id: runId,
+      per_page: 100
+    });
+    return jobs.data.jobs.map((job) => normalizeWorkflowJob(job));
+  } catch {
+    return [];
+  }
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -547,7 +565,10 @@ async function waitForGitHubWorkflowRunCompletion(repository, {
   const { owner, name } = typeof repository === "string" ? parseGitHubRepositorySlug(repository) : repository;
   const startedAt = Date.now();
   let lastProgress = null;
-  const emitProgress = (type, run = null) => {
+  const emitProgress = (type, run = null, jobs = []) => {
+    const completedJobs = jobs.filter((job) => job.status === "completed");
+    const failedJobs = jobs.filter((job) => job.conclusion && job.conclusion !== "success" && job.conclusion !== "skipped");
+    const activeJobs = jobs.filter((job) => job.status && job.status !== "completed");
     const event = {
       type,
       repository: `${owner}/${name}`,
@@ -558,7 +579,11 @@ async function waitForGitHubWorkflowRunCompletion(repository, {
       runId: run?.id ?? null,
       url: run?.url ?? null,
       status: run?.status ?? null,
-      conclusion: run?.conclusion ?? null
+      conclusion: run?.conclusion ?? null,
+      jobs,
+      activeJobs,
+      completedJobs,
+      failedJobs
     };
     lastProgress = event;
     onProgress?.(event);
@@ -587,15 +612,10 @@ async function waitForGitHubWorkflowRunCompletion(repository, {
           run_id: match.id
         });
         const normalized = normalizeWorkflowRun(current.data);
+        const progressJobs = await listWorkflowJobsForProgress(client, owner, name, match.id);
         if (normalized.status === "completed") {
-          emitProgress("completed", normalized);
-          const jobs = await client.rest.actions.listJobsForWorkflowRun({
-            owner,
-            repo: name,
-            run_id: match.id,
-            per_page: 100
-          });
-          const normalizedJobs = jobs.data.jobs.map((job) => normalizeWorkflowJob(job));
+          const normalizedJobs = progressJobs;
+          emitProgress("completed", normalized, normalizedJobs);
           return {
             status: "completed",
             repository: `${owner}/${name}`,
@@ -609,7 +629,7 @@ async function waitForGitHubWorkflowRunCompletion(repository, {
             failedJobs: normalizedJobs.filter((job) => job.conclusion && job.conclusion !== "success" && job.conclusion !== "skipped")
           };
         }
-        emitProgress("running", normalized);
+        emitProgress("running", normalized, progressJobs);
         await sleep(pollSeconds * 1e3);
       }
     } catch (error) {

package/dist/scripts/check-build-warnings.js

@@ -4,11 +4,19 @@ import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
 const args = process.argv.slice(2);
+const defaultAllowlisted = [
+	/Module "url" has been externalized for browser compatibility, imported by ".*libsodium-sumo.*"/u,
+];
 const allowlisted = [];
 const files = [];
+let useDefaultPolicy = true;
 
 for (let index = 0; index < args.length; index += 1) {
 	const arg = args[index];
+	if (arg === '--no-default-policy') {
+		useDefaultPolicy = false;
+		continue;
+	}
 	if (arg === '--allow') {
 		const pattern = args[index + 1];
 		if (!pattern) {
@@ -22,17 +30,21 @@ for (let index = 0; index < args.length; index += 1) {
 }
 
 if (files.length === 0) {
-	throw new Error('Usage: node check-build-warnings.mjs <log-file> [<log-file> ...] [--allow <regex>]');
+	throw new Error('Usage: node check-build-warnings.mjs <log-file> [<log-file> ...] [--allow <regex>] [--no-default-policy]');
 }
 
 const warningLines = [];
+const effectiveAllowlisted = [
+	...(useDefaultPolicy ? defaultAllowlisted : []),
+	...allowlisted,
+];
 for (const file of files) {
 	const contents = readFileSync(resolve(process.cwd(), file), 'utf8');
 	for (const line of contents.split(/\r?\n/u)) {
 		if (!line.includes('[WARN]')) {
 			continue;
 		}
-		if (allowlisted.some((pattern) => pattern.test(line))) {
+		if (effectiveAllowlisted.some((pattern) => pattern.test(line))) {
 			continue;
 		}
 		warningLines.push(line);

package/dist/workflow/operations.d.ts

@@ -798,6 +798,8 @@ export declare function workflowRelease(helpers: WorkflowOperationHelpers, input
     worktreePath: string | null;
     primaryRoot: string | null;
     ciMode: "hosted" | "off";
+    fresh: boolean;
+    freshArchivedRuns: never[];
     mode: TreeseedWorkflowMode;
     mergeStrategy: string;
     level: string;
@@ -844,6 +846,11 @@ export declare function workflowRelease(helpers: WorkflowOperationHelpers, input
     mode: "root-only";
     mergeStrategy: string;
     level: "patch" | "major" | "minor";
+    fresh: boolean;
+    freshArchivedRuns: {
+        runId: string;
+        reasons: string[];
+    }[];
     resumed: boolean;
     resumedRunId: string | null;
     autoResumed: boolean;
@@ -909,6 +916,11 @@ export declare function workflowRelease(helpers: WorkflowOperationHelpers, input
     mode: "recursive-workspace";
     mergeStrategy: string;
     level: "patch" | "major" | "minor";
+    fresh: boolean;
+    freshArchivedRuns: {
+        runId: string;
+        reasons: string[];
+    }[];
     resumed: boolean;
     resumedRunId: string | null;
     autoResumed: boolean;
@@ -1041,6 +1053,11 @@ export declare function workflowRecover(helpers: WorkflowOperationHelpers, input
         } | null;
         classification: import("./runs.ts").TreeseedWorkflowRunClassification;
     }[];
+    markedObsoleteRun: {
+        runId: string;
+        command: TreeseedWorkflowRunCommand;
+        reason: string;
+    } | null;
     selectedRun: TreeseedWorkflowRunJournal | null;
     runCount: number;
 } & {

package/dist/workflow/operations.js

@@ -254,13 +254,30 @@ function resolveRootReleaseSubmoduleConflicts(root, selectedPackageNames) {
   const packagePaths = new Set(packages.map((pkg) => pkg.repoPath));
   const unresolved = unresolvedMergePaths(gitRoot);
   if (unresolved.length === 0 || unresolved.some((filePath) => !packagePaths.has(filePath))) {
-    return false;
+    return {
+      resolved: false,
+      allUnresolvedPathsWerePackagePointers: unresolved.length > 0 && unresolved.every((filePath) => packagePaths.has(filePath)),
+      unresolvedPaths: unresolved,
+      entries: []
+    };
   }
+  const entries = [];
   for (const pkg of packages) {
     syncBranchWithOrigin(pkg.dir, PRODUCTION_BRANCH);
     run("git", ["add", pkg.repoPath], { cwd: gitRoot });
+    entries.push({
+      packageName: pkg.name,
+      path: pkg.repoPath,
+      targetBranch: PRODUCTION_BRANCH,
+      resolvedCommit: headCommit(pkg.dir)
+    });
   }
-  return true;
+  return {
+    resolved: true,
+    allUnresolvedPathsWerePackagePointers: true,
+    unresolvedPaths: unresolved,
+    entries
+  };
 }
 function unlinkWorkflowWorkspaceLinks(root, helpers, mode = "auto") {
   if (!shouldManageWorkspaceLinks(mode, helpers.context.env)) {
@@ -1060,6 +1077,123 @@ function releasePlanMatchesCurrentHeads(plan, rootRepo, packageReports) {
 function releaseRunHasCompletedMutation(journal) {
   return journal.steps.some((step) => step.status === "completed" && step.id !== "release-plan" && step.id !== "workspace-unlink");
 }
+function generatedReleaseMetadataFiles(repoDir) {
+  return ["package.json", "package-lock.json", "npm-shrinkwrap.json"].filter((filePath) => {
+    if (existsSync(resolve(repoDir, filePath))) return true;
+    try {
+      run("git", ["ls-files", "--error-unmatch", filePath], { cwd: repoDir, capture: true });
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+function collectReleaseCleanupSnapshot(root, selectedPackageNames) {
+  return {
+    repos: [
+      {
+        name: "@treeseed/market",
+        path: repoRoot(root),
+        branch: currentBranch(repoRoot(root)) || null,
+        files: generatedReleaseMetadataFiles(repoRoot(root))
+      },
+      ...checkedOutWorkspacePackageRepos(root).filter((pkg) => selectedPackageNames.has(pkg.name)).map((pkg) => ({
+        name: pkg.name,
+        path: pkg.dir,
+        branch: currentBranch(pkg.dir) || null,
+        files: generatedReleaseMetadataFiles(pkg.dir)
+      }))
+    ]
+  };
+}
+function restoreReleaseGeneratedMetadata(repo) {
+  const restored = [];
+  const skipped = [];
+  for (const filePath of repo.files) {
+    const status = run("git", ["status", "--porcelain", "--", filePath], { cwd: repo.path, capture: true });
+    if (!status.trim()) {
+      skipped.push(filePath);
+      continue;
+    }
+    run("git", ["restore", "--staged", "--worktree", "--", filePath], { cwd: repo.path, capture: true });
+    restored.push(filePath);
+  }
+  return { restored, skipped };
+}
+function cleanupFailedReleaseLocalState(root, helpers, snapshot, workspaceLinksMode) {
+  const report = { restored: [], skipped: [], manualReview: [] };
+  try {
+    ensureWorkflowWorkspaceLinks(root, helpers, workspaceLinksMode ?? "auto");
+  } catch (error) {
+    report.manualReview.push({
+      scope: "workspace-links",
+      reason: error instanceof Error ? error.message : String(error)
+    });
+  }
+  if (!snapshot) {
+    report.skipped.push({ scope: "release-metadata", reason: "cleanup snapshot was not recorded before failure" });
+    return report;
+  }
+  for (const repo of snapshot.repos) {
+    try {
+      const restored = restoreReleaseGeneratedMetadata(repo);
+      if (repo.branch && currentBranch(repo.path) !== repo.branch) {
+        checkoutBranch(repo.path, repo.branch);
+      }
+      if (restored.restored.length > 0) {
+        report.restored.push({ repo: repo.name, path: repo.path, files: restored.restored });
+      }
+      if (restored.skipped.length > 0) {
+        report.skipped.push({ repo: repo.name, path: repo.path, files: restored.skipped, reason: "unchanged" });
+      }
+    } catch (error) {
+      report.manualReview.push({
+        repo: repo.name,
+        path: repo.path,
+        branch: repo.branch,
+        files: repo.files,
+        reason: error instanceof Error ? error.message : String(error),
+        nextCommand: repo.branch ? `git -C ${repo.path} restore --staged --worktree -- ${repo.files.join(" ")} && git -C ${repo.path} checkout ${repo.branch}` : null
+      });
+    }
+  }
+  return report;
+}
+function prepareFreshReleaseRun(root, branch, rootRepo, packageReports) {
+  if (branch !== STAGING_BRANCH) return { archived: [], blockers: [] };
+  const currentHeads = Object.fromEntries([
+    [rootRepo.name, rootRepo.commitSha ?? null],
+    ...packageReports.map((report) => [report.name, report.commitSha ?? null])
+  ]);
+  const archived = [];
+  const blockers = [];
+  for (const journal of listInterruptedWorkflowRuns(root).filter((entry) => entry.command === "release")) {
+    const classification = classifyWorkflowRunJournal(journal, {
+      currentBranch: branch,
+      currentHeads
+    });
+    if (classification.state === "stale") {
+      archiveWorkflowRun(root, journal.runId, {
+        ...classification,
+        reasons: ["fresh release superseded stale failed release", ...classification.reasons]
+      });
+      archived.push({ runId: journal.runId, reasons: classification.reasons });
+      continue;
+    }
+    if (classification.state === "resumable" && releaseRunHasCompletedMutation(journal)) {
+      blockers.push(`${journal.runId}: completed release mutations and is still safe to resume. Mark it obsolete with \`npx trsd recover --obsolete ${journal.runId} --reason "superseded by fresh release"\` before using --fresh.`);
+    }
+  }
+  if (blockers.length > 0) {
+    workflowError("release", "validation_failed", [
+      "Treeseed release --fresh will not bypass a resumable partial release that already completed release mutations.",
+      ...blockers
+    ].join("\n"), {
+      details: { archived, blockers }
+    });
+  }
+  return { archived, blockers };
+}
 function findAutoResumableReleaseRun(root, branch, rootRepo, packageReports) {
   if (branch !== STAGING_BRANCH) return null;
   return listInterruptedWorkflowRuns(root).find((journal) => {
@@ -3323,8 +3457,10 @@ async function workflowRelease(helpers, input) {
       const rootRepo = createWorkspaceRootRepoReport(root);
       const packageReports = createWorkspacePackageReports(root);
       const explicitResumeRunId = helpers.context.workflow?.resumeRunId ?? null;
-      const autoResumeRun = executionMode === "execute" && !explicitResumeRunId ? findAutoResumableReleaseRun(root, session.branchName, rootRepo, packageReports) : null;
-      const planAutoResumeRun = executionMode === "plan" ? findAutoResumableReleaseRun(root, session.branchName, rootRepo, packageReports) : null;
+      const freshRelease = input.fresh === true && !explicitResumeRunId;
+      const freshPreparation = freshRelease && executionMode === "execute" ? prepareFreshReleaseRun(root, session.branchName, rootRepo, packageReports) : { archived: [], blockers: [] };
+      const autoResumeRun = executionMode === "execute" && !explicitResumeRunId && !freshRelease ? findAutoResumableReleaseRun(root, session.branchName, rootRepo, packageReports) : null;
+      const planAutoResumeRun = executionMode === "plan" && input.fresh !== true ? findAutoResumableReleaseRun(root, session.branchName, rootRepo, packageReports) : null;
       const effectiveInput = autoResumeRun ? autoResumeRun.input : input;
       const level = effectiveInput.bump ?? "patch";
       const ciMode = normalizeCiMode(effectiveInput.ciMode, "release");
@@ -3345,6 +3481,8 @@ async function workflowRelease(helpers, input) {
         return buildWorkflowResult("release", root, {
           ...plannedRelease,
           ciMode,
+          fresh: input.fresh === true,
+          freshArchivedRuns: [],
           ...worktreePayload(root, effectiveInput.worktreeMode),
           autoResumeCandidate: planAutoResumeRun ? {
             runId: planAutoResumeRun.runId,
@@ -3372,6 +3510,7 @@ async function workflowRelease(helpers, input) {
           gitDependencyProtocol: effectiveInput.gitDependencyProtocol ?? "preserve-origin",
           gitRemoteWriteMode: effectiveInput.gitRemoteWriteMode ?? "ssh-pushurl",
           ciMode,
+          fresh: input.fresh === true,
           worktreeMode: effectiveInput.worktreeMode ?? "auto",
           workspaceLinks: effectiveInput.workspaceLinks ?? "auto"
         },
@@ -3404,6 +3543,7 @@ async function workflowRelease(helpers, input) {
       if (autoResumeRun) {
         helpers.write(`[workflow][resume] Resuming interrupted release ${autoResumeRun.runId} on ${STAGING_BRANCH}.`);
       }
+      let releaseCleanupSnapshot = null;
       try {
         const releasePlan = await executeJournalStep(root, workflowRun.runId, "release-plan", () => plannedRelease);
         const effectivePackageSelection = releasePlanPackageSelection(releasePlan.packageSelection);
@@ -3491,6 +3631,8 @@ async function workflowRelease(helpers, input) {
             mode,
             mergeStrategy: "merge-commit",
             level,
+            fresh: input.fresh === true,
+            freshArchivedRuns: freshPreparation.archived,
             resumed: workflowRun.resumed,
             resumedRunId: workflowRun.resumed ? workflowRun.runId : null,
             autoResumed: autoResumeRun != null,
@@ -3527,6 +3669,7 @@ async function workflowRelease(helpers, input) {
             prepareReleaseBranches(pkg.dir);
           }
         }
+        releaseCleanupSnapshot = collectReleaseCleanupSnapshot(root, effectiveSelectedPackageNames);
         const metadata = await executeJournalStep(root, workflowRun.runId, "prepare-release-metadata", () => {
           const releasedPackageDevTags2 = Object.fromEntries(
             checkedOutWorkspacePackageRepos(root).filter((pkg) => effectiveSelectedPackageNames.has(pkg.name)).map((pkg) => {
@@ -3641,17 +3784,22 @@ async function workflowRelease(helpers, input) {
           pushBranch(gitRoot, STAGING_BRANCH);
           const stagingCommit = headCommit(gitRoot);
           let released;
+          let submoduleReconciliation = null;
           try {
             released = mergeBranchIntoTarget(root, {
               sourceBranch: STAGING_BRANCH,
               targetBranch: PRODUCTION_BRANCH,
               message: `release: ${STAGING_BRANCH} -> ${PRODUCTION_BRANCH}`,
-              pushTarget: false
+              pushTarget: false,
+              quietMerge: true
             });
           } catch (error) {
-            if (!resolveRootReleaseSubmoduleConflicts(root, effectiveSelectedPackageNames)) {
+            const reconciliation = resolveRootReleaseSubmoduleConflicts(root, effectiveSelectedPackageNames);
+            if (!reconciliation.resolved) {
               throw error;
             }
+            helpers.write(`[release][reconcile] Resolving generated package pointer reconciliation for ${reconciliation.entries.map((entry) => String(entry.path)).join(", ")}.`);
+            submoduleReconciliation = reconciliation;
             commitAllIfChanged(gitRoot, `release: ${STAGING_BRANCH} -> ${PRODUCTION_BRANCH}`);
             released = { commitSha: headCommit(gitRoot) };
           }
@@ -3671,7 +3819,8 @@ async function workflowRelease(helpers, input) {
             stagingCommit,
             releasedCommit,
             mergeCommit: released.commitSha,
-            tag
+            tag,
+            submoduleReconciliation
           };
         });
         rootRepo.committed = true;
@@ -3752,6 +3901,8 @@ async function workflowRelease(helpers, input) {
           mode,
           mergeStrategy: "merge-commit",
           level,
+          fresh: input.fresh === true,
+          freshArchivedRuns: freshPreparation.archived,
           resumed: workflowRun.resumed,
           resumedRunId: workflowRun.resumed ? workflowRun.runId : null,
           autoResumed: autoResumeRun != null,
@@ -3792,7 +3943,7 @@ async function workflowRelease(helpers, input) {
           ])
         });
       } catch (error) {
-        ensureWorkflowWorkspaceLinks(root, helpers, effectiveInput.workspaceLinks ?? "auto");
+        const localCleanup = cleanupFailedReleaseLocalState(root, helpers, releaseCleanupSnapshot, effectiveInput.workspaceLinks ?? "auto");
         const latestJournal = readWorkflowRunJournal(root, workflowRun.runId);
         const lastCompleted = [...latestJournal?.steps ?? []].reverse().find((step) => step.status === "completed") ?? null;
         const nextPending = latestJournal?.steps.find((step) => step.status === "pending") ?? null;
@@ -3808,14 +3959,22 @@ ${repair.blockers.join("\n")}`, "stderr");
         } catch (repairError) {
           helpers.write(`[release][recovery] Package repo repair failed: ${repairError instanceof Error ? repairError.message : String(repairError)}`, "stderr");
         }
-        helpers.write(`Safe recovery: npx trsd release --${level} --json, or inspect with npx trsd recover --json.`, "stderr");
+        if (localCleanup.restored.length > 0) {
+          helpers.write(`[release][recovery] Restored generated release metadata in ${localCleanup.restored.length} repo(s).`, "stderr");
+        }
+        if (localCleanup.manualReview.length > 0) {
+          helpers.write(`[release][recovery] Local cleanup needs manual review:
+${localCleanup.manualReview.map((entry) => `- ${String(entry.repo ?? entry.scope ?? "repo")}: ${String(entry.reason ?? "unknown")}`).join("\n")}`, "stderr");
+        }
+        helpers.write(`Safe recovery: npx trsd release --${level} --json, npx trsd release --${level} --fresh --json, or inspect with npx trsd recover --json.`, "stderr");
         failWorkflowRun(root, workflowRun.runId, error, {
           resumable: true,
           runId: workflowRun.runId,
           command: "release",
           message: `Resume the interrupted release on ${STAGING_BRANCH}. Last phase: ${lastCompleted?.id ?? "not-started"}; next phase: ${nextPending?.id ?? "none"}.`,
           recoverCommand: "npx trsd recover --json",
-          resumeCommand: `npx trsd release --${level} --json`
+          resumeCommand: `npx trsd release --${level} --json`,
+          localCleanup
         });
         throw error;
       }
@@ -3909,7 +4068,29 @@ async function workflowRecover(helpers, input = {}) {
         currentBranch: session.branchName,
         currentHeads
       });
-      const interruptedRuns = classifiedRuns.filter((entry) => entry.classification.state === "resumable").map(({ journal }) => ({
+      const markedObsoleteRun = input.obsoleteRunId ? (() => {
+        const entry = classifiedRuns.find((candidate) => candidate.journal.runId === input.obsoleteRunId);
+        if (!entry) {
+          workflowError("recover", "validation_failed", `Treeseed recover could not find workflow run ${input.obsoleteRunId}.`);
+        }
+        const reason = input.obsoleteReason?.trim() || "marked obsolete by operator";
+        const classification = {
+          state: "obsolete",
+          reasons: [reason],
+          classifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        archiveWorkflowRun(root, entry.journal.runId, classification);
+        return {
+          runId: entry.journal.runId,
+          command: entry.journal.command,
+          reason
+        };
+      })() : null;
+      const effectiveClassifiedRuns = markedObsoleteRun ? classifyWorkflowRunJournals(root, {
+        currentBranch: session.branchName,
+        currentHeads
+      }) : classifiedRuns;
+      const interruptedRuns = effectiveClassifiedRuns.filter((entry) => entry.classification.state === "resumable").map(({ journal }) => ({
         runId: journal.runId,
         command: journal.command,
         status: journal.status,
@@ -3919,7 +4100,7 @@ async function workflowRecover(helpers, input = {}) {
         failure: journal.failure,
         resumeCommand: `treeseed resume ${journal.runId}`
       }));
-      const staleRuns = classifiedRuns.filter((entry) => entry.classification.state === "stale").map(({ journal, classification }) => ({
+      const staleRuns = effectiveClassifiedRuns.filter((entry) => entry.classification.state === "stale").map(({ journal, classification }) => ({
         runId: journal.runId,
         command: journal.command,
         status: journal.status,
@@ -3929,7 +4110,7 @@ async function workflowRecover(helpers, input = {}) {
         failure: journal.failure,
         classification
       }));
-      const obsoleteRuns = classifiedRuns.filter((entry) => entry.classification.state === "obsolete").map(({ journal, classification }) => ({
+      const obsoleteRuns = effectiveClassifiedRuns.filter((entry) => entry.classification.state === "obsolete").map(({ journal, classification }) => ({
         runId: journal.runId,
         command: journal.command,
         status: journal.status,
@@ -3952,6 +4133,7 @@ async function workflowRecover(helpers, input = {}) {
           staleRuns,
           obsoleteRuns,
           prunedRuns,
+          markedObsoleteRun,
           selectedRun,
           runCount: journals.length
         },

package/dist/workflow/runs.js

@@ -247,6 +247,16 @@ function isReleaseGateOnlyCompletion(journal) {
   const pendingStep = journal.steps.find((step) => step.status === "pending");
   return pendingStep?.id === "release-root-gates" || pendingStep?.id === "release-back-merge" || pendingStep?.id === "cleanup-dev-tags";
 }
+function releaseStepData(journal, stepId) {
+  return stringRecord(journal.steps.find((step) => step.id === stepId)?.data);
+}
+function expectedPackageHeadAfterReleaseGate(journal, packageName) {
+  const data = releaseStepData(journal, `release-${packageName}`);
+  const backMerge = stringRecord(data?.backMerge);
+  if (typeof backMerge?.commitSha === "string") return backMerge.commitSha;
+  if (typeof data?.commitSha === "string") return data.commitSha;
+  return null;
+}
 function classifyWorkflowRunJournal(journal, options = {}) {
   const reasons = [];
   const now = options.now ?? nowIso();
@@ -283,6 +293,22 @@ function classifyWorkflowRunJournal(journal, options = {}) {
     reasons.push(`current branch ${options.currentBranch} does not match journal branch ${journal.session.branchName}`);
   }
   const releaseGateOnlyCompletion = isReleaseGateOnlyCompletion(journal);
+  if (journal.command === "release" && options.currentHeads && releaseGateOnlyCompletion) {
+    const rootRelease = releaseStepData(journal, "release-root");
+    const expectedRootHead = typeof rootRelease?.stagingCommit === "string" ? rootRelease.stagingCommit : null;
+    const rootHead = options.currentHeads["@treeseed/market"];
+    if (rootHead && expectedRootHead && rootHead !== expectedRootHead) {
+      reasons.push(`market staging head changed from ${expectedRootHead} to ${rootHead}`);
+    }
+    const releasePlan = releaseStepData(journal, "release-plan");
+    for (const name of selectedReleasePackageNames(releasePlan)) {
+      const currentHead = options.currentHeads[name];
+      const expectedHead = expectedPackageHeadAfterReleaseGate(journal, name);
+      if (currentHead && expectedHead && currentHead !== expectedHead) {
+        reasons.push(`${name} staging head changed from ${expectedHead} to ${currentHead}`);
+      }
+    }
+  }
   if (journal.command === "release" && options.currentHeads && !releaseGateOnlyCompletion) {
     const releasePlan = stringRecord(journal.steps.find((step) => step.id === "release-plan")?.data);
     if (releasePlan) {

package/dist/workflow.d.ts

@@ -25,6 +25,7 @@ export type TreeseedWorkflowRecovery = {
     recoverCommand?: string | null;
     resumeCommand?: string | null;
     lock?: Record<string, unknown> | null;
+    localCleanup?: Record<string, unknown> | null;
 };
 export type TreeseedWorkflowExecutionMode = 'execute' | 'plan';
 export type TreeseedWorkflowWorktreeMode = 'auto' | 'on' | 'off';
@@ -214,6 +215,7 @@ export type TreeseedReleaseInput = {
     ciMode?: TreeseedWorkflowCiMode;
     worktreeMode?: TreeseedWorkflowWorktreeMode;
     workspaceLinks?: 'auto' | 'off';
+    fresh?: boolean;
     plan?: boolean;
     dryRun?: boolean;
 };
@@ -223,6 +225,8 @@ export type TreeseedResumeInput = {
 export type TreeseedRecoverInput = {
     runId?: string;
     pruneStale?: boolean;
+    obsoleteRunId?: string;
+    obsoleteReason?: string;
 };
 export type TreeseedDestroyInput = {
     target?: 'local' | 'staging' | 'prod';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeseed/sdk",
-  "version": "0.6.31",
+  "version": "0.6.33",
   "description": "Shared Treeseed SDK for content-backed and D1-backed object models.",
   "license": "AGPL-3.0-only",
   "repository": {