@treeseed/sdk 0.6.21 → 0.6.23

package/dist/operations/services/config-runtime.d.ts

@@ -220,6 +220,7 @@ export declare function resolveTreeseedRemoteConfig(startRoot?: string, env?: No
 export declare function resolveTreeseedTemplateCatalogEndpoint(startRoot?: string, env?: NodeJS.ProcessEnv): string;
 export declare function resolveTreeseedTemplateCatalogCachePath(startRoot?: string): string;
 export declare function ensureTreeseedGitignoreEntries(tenantRoot: any): string;
+export declare function ensureTreeseedRailwayIgnoreEntries(tenantRoot: any): string;
 export type TreeseedRepairAction = {
     id: string;
     detail: string;

package/dist/operations/services/config-runtime.js

@@ -1210,6 +1210,46 @@ function ensureTreeseedGitignoreEntries(tenantRoot) {
   }
   return gitignorePath;
 }
+function ensureTreeseedRailwayIgnoreEntries(tenantRoot) {
+  const railwayIgnorePath = resolve(tenantRoot, ".railwayignore");
+  const requiredEntries = [
+    ".astro/",
+    ".codex/",
+    ".dev.vars",
+    ".env.local",
+    ".git/",
+    ".treeseed/",
+    ".wrangler/",
+    "coverage/",
+    "dist/",
+    "node_modules/",
+    "npm-debug.log*",
+    "packages/*/.git/",
+    "packages/*/dist/",
+    "packages/*/node_modules/",
+    "public/__treeseed/*.json",
+    "public/books/*.json",
+    "public/books/*.md",
+    "scripts/.ts-run-*.mjs",
+    "tmp/",
+    "*.log",
+    "*.tgz"
+  ];
+  const current = existsSync(railwayIgnorePath) ? readFileSync(railwayIgnorePath, "utf8") : "";
+  const lines = current.split(/\r?\n/);
+  let changed = false;
+  for (const entry of requiredEntries) {
+    if (!lines.includes(entry)) {
+      lines.push(entry);
+      changed = true;
+    }
+  }
+  if (changed || !existsSync(railwayIgnorePath)) {
+    writeFileSync(railwayIgnorePath, `${lines.filter(Boolean).join("\n")}
+`, "utf8");
+  }
+  return railwayIgnorePath;
+}
 function dedupeRepairActions(actions) {
   const seen = /* @__PURE__ */ new Set();
   return actions.filter((action) => {
@@ -1224,6 +1264,8 @@ function applyTreeseedSafeRepairs(tenantRoot) {
   const actions = [];
   ensureTreeseedGitignoreEntries(tenantRoot);
   actions.push({ id: "gitignore", detail: "Ensured Treeseed gitignore entries are present." });
+  ensureTreeseedRailwayIgnoreEntries(tenantRoot);
+  actions.push({ id: "railwayignore", detail: "Ensured Railway deploy ignore entries are present." });
   const deprecatedFiles = warnDeprecatedTreeseedLocalEnvFiles(tenantRoot);
   if (deprecatedFiles.length > 0) {
     actions.push({ id: "deprecated-local-env", detail: "Detected deprecated .env.local/.dev.vars files that Treeseed now ignores." });
@@ -2382,6 +2424,7 @@ function collectTreeseedConfigContext({
   env = process.env
 }) {
   ensureTreeseedGitignoreEntries(tenantRoot);
+  ensureTreeseedRailwayIgnoreEntries(tenantRoot);
   const registry = collectTreeseedEnvironmentContext(tenantRoot);
   const { configPath, keyPath } = getTreeseedMachineConfigPaths(tenantRoot);
   const valuesByScope = Object.fromEntries(
@@ -2843,6 +2886,7 @@ export {
   createDefaultTreeseedMachineConfig,
   ensureTreeseedActVerificationTooling,
   ensureTreeseedGitignoreEntries,
+  ensureTreeseedRailwayIgnoreEntries,
   ensureTreeseedSecretSessionForConfig,
   finalizeTreeseedConfig,
   formatTreeseedConfigEnvironmentReport,

package/dist/operations/services/deploy.js

@@ -325,7 +325,6 @@ const LOCAL_RUNTIME_AUTH_ENV_KEYS = [
   "TREESEED_AUTH_INTERNAL_SIGNUP",
   "TREESEED_AUTH_EMAIL_LINKING",
   "TREESEED_AUTH_ALLOW_MEMORY_DB",
-  "TREESEED_AUTH_LOCAL_USE_MAILPIT",
   "TREESEED_AUTH_EMAIL_FROM",
   "TREESEED_WEB_SESSION_TTL",
   "TREESEED_API_BOOTSTRAP_ADMIN_ALLOWLIST",
@@ -362,9 +361,8 @@ function buildLocalRuntimeVars(deployConfig, state, target, env) {
     TREESEED_BETTER_AUTH_SECRET: envValue(env, "TREESEED_BETTER_AUTH_SECRET") ?? state.generatedSecrets?.TREESEED_BETTER_AUTH_SECRET ?? state.generatedSecrets?.TREESEED_FORM_TOKEN_SECRET ?? "treeseed-local-better-auth-secret-minimum-32-characters",
     TREESEED_EDITORIAL_PREVIEW_SECRET: envValue(env, "TREESEED_EDITORIAL_PREVIEW_SECRET") ?? state.generatedSecrets?.TREESEED_EDITORIAL_PREVIEW_SECRET ?? "treeseed-local-editorial-preview-secret",
     TREESEED_FORMS_LOCAL_BYPASS_CLOUDFLARE_GUARDS: envValue(env, "TREESEED_FORMS_LOCAL_BYPASS_CLOUDFLARE_GUARDS") ?? "",
-    TREESEED_FORMS_LOCAL_USE_MAILPIT: envValue(env, "TREESEED_FORMS_LOCAL_USE_MAILPIT") ?? "false",
-    TREESEED_MAILPIT_SMTP_HOST: envValue(env, "TREESEED_MAILPIT_SMTP_HOST") ?? "127.0.0.1",
-    TREESEED_MAILPIT_SMTP_PORT: envValue(env, "TREESEED_MAILPIT_SMTP_PORT") ?? "1025"
+    TREESEED_SMTP_HOST: envValue(env, "TREESEED_SMTP_HOST") ?? "127.0.0.1",
+    TREESEED_SMTP_PORT: envValue(env, "TREESEED_SMTP_PORT") ?? "1025"
   };
 }
 function buildSecretMap(deployConfig, state) {

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

@@ -1,6 +1,74 @@
 export declare const STAGING_BRANCH = "staging";
 export declare const PRODUCTION_BRANCH = "main";
 export declare function headCommit(repoDir: any, ref?: string): string;
+export declare function inspectDetachedHeadRepair(repoDir: any, expectedBranches?: string[]): {
+    repoDir: any;
+    branchName: string;
+    detached: boolean;
+    dirty: boolean;
+    headSha: string | null;
+    targetBranch: string;
+    targetSha: string | null;
+    repairable: boolean;
+    repaired: boolean;
+    blocker: null;
+} | {
+    repoDir: any;
+    branchName: null;
+    detached: boolean;
+    dirty: boolean;
+    headSha: string;
+    targetBranch: string;
+    targetSha: string;
+    repairable: boolean;
+    repaired: boolean;
+    blocker: null;
+} | {
+    repoDir: any;
+    branchName: null;
+    detached: boolean;
+    dirty: boolean;
+    headSha: string | null;
+    targetBranch: null;
+    targetSha: null;
+    repairable: boolean;
+    repaired: boolean;
+    blocker: string;
+};
+export declare function reattachDetachedHeadIfSafe(repoDir: any, expectedBranches?: string[]): {
+    repoDir: any;
+    branchName: string;
+    detached: boolean;
+    dirty: boolean;
+    headSha: string | null;
+    targetBranch: string;
+    targetSha: string | null;
+    repairable: boolean;
+    repaired: boolean;
+    blocker: null;
+} | {
+    repoDir: any;
+    branchName: null;
+    detached: boolean;
+    dirty: boolean;
+    headSha: string;
+    targetBranch: string;
+    targetSha: string;
+    repairable: boolean;
+    repaired: boolean;
+    blocker: null;
+} | {
+    repoDir: any;
+    branchName: null;
+    detached: boolean;
+    dirty: boolean;
+    headSha: string | null;
+    targetBranch: null;
+    targetSha: null;
+    repairable: boolean;
+    repaired: boolean;
+    blocker: string;
+};
 export declare function gitWorkflowRoot(cwd?: any): string;
 export declare function assertCleanWorktree(cwd?: any): string;
 export declare function assertCleanWorktrees(repoDirs: any): any;

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

@@ -40,6 +40,75 @@ function resolveGeneratedPackageMetadataConflicts(repoDir) {
 function headCommit(repoDir, ref = "HEAD") {
   return runGit(["rev-parse", ref], { cwd: repoDir, capture: true }).trim();
 }
+function maybeHeadCommit(repoDir, ref = "HEAD") {
+  try {
+    return headCommit(repoDir, ref);
+  } catch {
+    return null;
+  }
+}
+function inspectDetachedHeadRepair(repoDir, expectedBranches = [STAGING_BRANCH, PRODUCTION_BRANCH]) {
+  const branchName = currentBranch(repoDir) || null;
+  const headSha = maybeHeadCommit(repoDir);
+  const dirty = gitStatusPorcelain(repoDir).length > 0;
+  if (branchName) {
+    return {
+      repoDir,
+      branchName,
+      detached: false,
+      dirty,
+      headSha,
+      targetBranch: branchName,
+      targetSha: headSha,
+      repairable: false,
+      repaired: false,
+      blocker: null
+    };
+  }
+  for (const branch of expectedBranches) {
+    const branchSha = branchExists(repoDir, branch) ? maybeHeadCommit(repoDir, branch) : null;
+    if (headSha && branchSha && headSha === branchSha) {
+      return {
+        repoDir,
+        branchName: null,
+        detached: true,
+        dirty,
+        headSha,
+        targetBranch: branch,
+        targetSha: branchSha,
+        repairable: true,
+        repaired: false,
+        blocker: null
+      };
+    }
+  }
+  const expected = expectedBranches.join(" or ");
+  return {
+    repoDir,
+    branchName: null,
+    detached: true,
+    dirty,
+    headSha,
+    targetBranch: null,
+    targetSha: null,
+    repairable: false,
+    repaired: false,
+    blocker: `Detached HEAD ${headSha ?? "(unknown)"} does not match ${expected}; review manually before continuing.`
+  };
+}
+function reattachDetachedHeadIfSafe(repoDir, expectedBranches = [STAGING_BRANCH, PRODUCTION_BRANCH]) {
+  const inspection = inspectDetachedHeadRepair(repoDir, expectedBranches);
+  if (!inspection.detached || !inspection.repairable || !inspection.targetBranch) {
+    return inspection;
+  }
+  runGit(["switch", inspection.targetBranch], { cwd: repoDir });
+  return {
+    ...inspection,
+    branchName: inspection.targetBranch,
+    detached: false,
+    repaired: true
+  };
+}
 function gitWorkflowRoot(cwd = workspaceRoot()) {
   return repoRoot(cwd);
 }
@@ -394,6 +463,7 @@ export {
   fetchOrigin,
   gitWorkflowRoot,
   headCommit,
+  inspectDetachedHeadRepair,
   isTaskBranch,
   listTaskBranches,
   mergeBranchIntoTarget,
@@ -402,6 +472,7 @@ export {
   prepareReleaseBranches,
   pushBranch,
   pushHeadToBranch,
+  reattachDetachedHeadIfSafe,
   remoteBranchExists,
   squashMergeBranchIntoStaging,
   syncBranchWithOrigin,

package/dist/operations/services/github-actions-verification.d.ts

@@ -119,5 +119,7 @@ export declare function formatGitHubActionsGateFailure(gate: GitHubActionsWorkfl
 export declare function waitForGitHubActionsGate(gate: GitHubActionsWorkflowGate, options?: {
     timeoutSeconds?: number;
     pollSeconds?: number;
+    operation?: string;
+    onProgress?: (message: string, stream?: 'stdout' | 'stderr') => void;
 }): Promise<Record<string, unknown>>;
 export {};

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

@@ -421,6 +421,31 @@ Failed jobs: ${failedJobs.join(", ")}` : "";
 Inspect with: gh run view ${runId} --repo ${repository} --log-failed` : "";
   return `${gate.name} ${gate.workflow} completed with conclusion ${String(result.conclusion ?? "unknown")} in ${repository}.${url}${jobLine}${command}`;
 }
+function formatElapsed(seconds) {
+  const safe = Math.max(0, Math.round(seconds));
+  if (safe < 60) return `${safe}s`;
+  const minutes = Math.floor(safe / 60);
+  const remainder = safe % 60;
+  return remainder === 0 ? `${minutes}m` : `${minutes}m${remainder}s`;
+}
+function shortSha(value) {
+  return value ? value.slice(0, 12) : "(unknown)";
+}
+function formatGitHubActionsGateProgress(gate, event, operation) {
+  const prefix = `[${operation}][gate][${gate.name}] ${event.workflow}`;
+  if (event.type === "waiting") {
+    return `${prefix} on ${event.branch ?? gate.branch}: waiting for run for ${shortSha(event.headSha ?? gate.headSha)} (${formatElapsed(event.elapsedSeconds)} elapsed)`;
+  }
+  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}`;
+  }
+  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)`;
+}
 async function waitForGitHubActionsGate(gate, options = {}) {
   const { waitForGitHubWorkflowCompletion } = await import("./github-automation.js");
   return await waitForGitHubWorkflowCompletion(gate.repoPath, {
@@ -429,7 +454,10 @@ async function waitForGitHubActionsGate(gate, options = {}) {
     headSha: gate.headSha,
     branch: gate.branch,
     timeoutSeconds: options.timeoutSeconds,
-    pollSeconds: options.pollSeconds
+    pollSeconds: options.pollSeconds,
+    onProgress: (event) => {
+      options.onProgress?.(formatGitHubActionsGateProgress(gate, event, options.operation ?? "workflow"));
+    }
   });
 }
 export {

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

@@ -34,6 +34,18 @@ export interface GitHubWorkflowJobSummary {
     conclusion: string | null;
     url: string | null;
 }
+export type GitHubWorkflowProgressEvent = {
+    type: 'waiting' | 'running' | 'completed';
+    repository: string;
+    workflow: string;
+    branch: string | null;
+    headSha: string | null;
+    elapsedSeconds: number;
+    runId: number | null;
+    url: string | null;
+    status: string | null;
+    conclusion: string | null;
+};
 export declare function resolveGitHubApiToken(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): string;
 export declare function parseGitHubRepositorySlug(value: string): {
     owner: string;
@@ -125,13 +137,14 @@ export declare function upsertGitHubRepositoryVariableWithGhCli(repository: stri
 export declare function waitForGitHubWorkflowRunCompletion(repository: string | {
     owner: string;
     name: string;
-}, { client, workflow, headSha, branch, timeoutSeconds, pollSeconds, }?: {
+}, { client, workflow, headSha, branch, timeoutSeconds, pollSeconds, onProgress, }?: {
     client?: GitHubApiClient;
     workflow?: string;
     headSha?: string | null;
     branch?: string | null;
     timeoutSeconds?: number;
     pollSeconds?: number;
+    onProgress?: (event: GitHubWorkflowProgressEvent) => void;
 }): Promise<{
     status: string;
     repository: string;

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

@@ -541,10 +541,28 @@ async function waitForGitHubWorkflowRunCompletion(repository, {
   headSha,
   branch,
   timeoutSeconds = 600,
-  pollSeconds = 5
+  pollSeconds = 5,
+  onProgress
 } = {}) {
   const { owner, name } = typeof repository === "string" ? parseGitHubRepositorySlug(repository) : repository;
   const startedAt = Date.now();
+  let lastProgress = null;
+  const emitProgress = (type, run = null) => {
+    const event = {
+      type,
+      repository: `${owner}/${name}`,
+      workflow,
+      branch: run?.headBranch ?? branch ?? null,
+      headSha: run?.headSha ?? headSha ?? null,
+      elapsedSeconds: Math.max(0, Math.round((Date.now() - startedAt) / 1e3)),
+      runId: run?.id ?? null,
+      url: run?.url ?? null,
+      status: run?.status ?? null,
+      conclusion: run?.conclusion ?? null
+    };
+    lastProgress = event;
+    onProgress?.(event);
+  };
   while (Date.now() - startedAt < timeoutSeconds * 1e3) {
     try {
       const listed = await client.rest.actions.listWorkflowRuns({
@@ -555,10 +573,14 @@ async function waitForGitHubWorkflowRunCompletion(repository, {
       });
       const match = listed.data.workflow_runs.map((run) => normalizeWorkflowRun(run)).find((run) => (!headSha || run.headSha === headSha) && (!branch || run.headBranch === branch));
       if (!match?.id) {
+        emitProgress("waiting");
         await sleep(pollSeconds * 1e3);
         continue;
       }
       for (; ; ) {
+        if (Date.now() - startedAt >= timeoutSeconds * 1e3) {
+          break;
+        }
         const current = await client.rest.actions.getWorkflowRun({
           owner,
           repo: name,
@@ -566,6 +588,7 @@ async function waitForGitHubWorkflowRunCompletion(repository, {
         });
         const normalized = normalizeWorkflowRun(current.data);
         if (normalized.status === "completed") {
+          emitProgress("completed", normalized);
           const jobs = await client.rest.actions.listJobsForWorkflowRun({
             owner,
             repo: name,
@@ -586,13 +609,15 @@ async function waitForGitHubWorkflowRunCompletion(repository, {
             failedJobs: normalizedJobs.filter((job) => job.conclusion && job.conclusion !== "success" && job.conclusion !== "skipped")
           };
         }
+        emitProgress("running", normalized);
         await sleep(pollSeconds * 1e3);
       }
     } catch (error) {
       throw normalizeGitHubApiError(error, `Unable to monitor GitHub workflow ${workflow} in ${owner}/${name}`);
     }
   }
-  throw new Error(`Timed out waiting for GitHub workflow ${workflow} in ${owner}/${name}.`);
+  const lastState = lastProgress ? ` Last known state: run ${lastProgress.runId ?? "(not created)"} ${lastProgress.status ?? "waiting"}${lastProgress.conclusion ? `/${lastProgress.conclusion}` : ""}${lastProgress.url ? ` ${lastProgress.url}` : ""}.` : "";
+  throw new Error(`Timed out waiting for GitHub workflow ${workflow} in ${owner}/${name}.${lastState}`);
 }
 async function ensureGitHubBranchFromBase(repository, branch, {
   baseBranch = "main",

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

@@ -271,7 +271,7 @@ export declare function ensureGitHubDeployAutomation(tenantRoot: any, { dryRun }
         mode?: undefined;
     };
 }>;
-export declare function waitForGitHubWorkflowCompletion(tenantRoot: any, { repository, workflow, headSha, branch, timeoutSeconds, pollSeconds, }?: {
+export declare function waitForGitHubWorkflowCompletion(tenantRoot: any, { repository, workflow, headSha, branch, timeoutSeconds, pollSeconds, onProgress, }?: {
     workflow?: string | undefined;
     timeoutSeconds?: number | undefined;
     pollSeconds?: number | undefined;

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

@@ -502,7 +502,8 @@ async function waitForGitHubWorkflowCompletion(tenantRoot, {
   headSha,
   branch,
   timeoutSeconds = 600,
-  pollSeconds = 5
+  pollSeconds = 5,
+  onProgress
 } = {}) {
   if (isGitHubAutomationStubbed()) {
     return {
@@ -521,7 +522,8 @@ async function waitForGitHubWorkflowCompletion(tenantRoot, {
     headSha,
     branch,
     timeoutSeconds,
-    pollSeconds
+    pollSeconds,
+    onProgress
   });
 }
 export {

package/dist/operations/services/local-dev.js

@@ -47,8 +47,8 @@ function runLocalD1Migration(persistTo) {
 }
 function prepareCloudflareLocalRuntime({ envOverrides = {}, persistTo, outDir } = {}) {
   const mergedEnvOverrides = {
-    TREESEED_MAILPIT_SMTP_HOST: "127.0.0.1",
-    TREESEED_MAILPIT_SMTP_PORT: "1025",
+    TREESEED_SMTP_HOST: "127.0.0.1",
+    TREESEED_SMTP_PORT: "1025",
     ...envOverrides
   };
   runNodeScript("./scripts/patch-starlight-content-path.js");

package/dist/platform/env.yaml

@@ -929,7 +929,7 @@ entries:
     sourcePriority:
       - machine-config
       - process-env
-    localDefaultValueRef: localMailpitHostDefault
+    localDefaultValueRef: localSmtpHostDefault
     relevanceRef: smtpEnabled
     requiredWhenRef: smtpNonLocal
   TREESEED_SMTP_PORT:
@@ -960,7 +960,7 @@ entries:
     sourcePriority:
       - machine-config
       - process-env
-    localDefaultValueRef: localMailpitPortDefault
+    localDefaultValueRef: localSmtpPortDefault
     relevanceRef: smtpEnabled
     requiredWhenRef: smtpNonLocal
   TREESEED_SMTP_USERNAME:

package/dist/platform/environment.js

@@ -108,10 +108,10 @@ function generatedSecret(bytes = 24) {
 function localTimezoneDefault() {
   return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
 }
-function localMailpitHostDefault() {
+function localSmtpHostDefault() {
   return "127.0.0.1";
 }
-function localMailpitPortDefault() {
+function localSmtpPortDefault() {
   return "1025";
 }
 function contactEmailDefault(context) {
@@ -232,8 +232,8 @@ function resolveGitHubRepositoryNameDefault(context) {
 const VALUE_RESOLVERS = {
   generatedSecret: () => generatedSecret(),
   localFormsBypassDefault: () => "true",
-  localMailpitHostDefault: () => localMailpitHostDefault(),
-  localMailpitPortDefault: () => localMailpitPortDefault(),
+  localSmtpHostDefault: () => localSmtpHostDefault(),
+  localSmtpPortDefault: () => localSmtpPortDefault(),
   contactEmailDefault: (context) => contactEmailDefault(context),
   projectDomainsDefault: (context) => primaryHostFromUrl(context.deployConfig.siteUrl),
   apiBaseUrlDefault: (context, scope, values) => resolveConfiguredApiBaseUrl(context, scope, values),

package/dist/scripts/test-cloudflare-local.js

@@ -137,9 +137,8 @@ async function main() {
         envOverrides: {
             TREESEED_LOCAL_DEV_MODE: 'cloudflare',
             TREESEED_FORMS_LOCAL_BYPASS_CLOUDFLARE_GUARDS: 'false',
-            TREESEED_FORMS_LOCAL_USE_MAILPIT: 'true',
-            TREESEED_MAILPIT_SMTP_HOST: '127.0.0.1',
-            TREESEED_MAILPIT_SMTP_PORT: '1025',
+            TREESEED_SMTP_HOST: '127.0.0.1',
+            TREESEED_SMTP_PORT: '1025',
         },
     });
     const worker = startWranglerDev(['--port', String(TEST_PORT), '--persist-to', PERSIST_TO], {

package/dist/workflow/operations.js

@@ -61,6 +61,7 @@ import {
   PRODUCTION_BRANCH,
   pushBranch,
   pushHeadToBranch,
+  reattachDetachedHeadIfSafe,
   remoteBranchExists,
   STAGING_BRANCH,
   squashMergeBranchIntoStaging,
@@ -377,7 +378,10 @@ async function waitForWorkflowGates(operation, gates, ciMode, options = {}) {
         continue;
       }
     }
-    const result = await waitForGitHubActionsGate(gate);
+    const result = await waitForGitHubActionsGate(gate, {
+      operation,
+      onProgress: options.onProgress
+    });
     const normalized = {
       name: gate.name,
       ...result,
@@ -1731,6 +1735,27 @@ function syncAllCheckedOutPackageRepos(root, branchName) {
     syncBranchWithOrigin(pkg.dir, branchName);
   }
 }
+function reattachRepairablePackageRepos(root, expectedBranches = [STAGING_BRANCH, PRODUCTION_BRANCH], options = {}) {
+  const reports = checkedOutWorkspacePackageRepos(root).map((pkg) => {
+    const report = reattachDetachedHeadIfSafe(pkg.dir, expectedBranches);
+    if (report.repaired && report.targetBranch && report.headSha) {
+      options.onProgress?.(`[workflow][repair] Reattached ${pkg.name} to ${report.targetBranch} at ${report.headSha.slice(0, 12)}.`);
+    }
+    return {
+      name: pkg.name,
+      path: pkg.dir,
+      ...report
+    };
+  });
+  const blockers = reports.filter((report) => report.detached && !report.repairable).map((report) => `${report.name}: ${report.blocker ?? "detached HEAD requires manual review."}`);
+  if (blockers.length > 0 && options.throwOnBlocker) {
+    workflowError(options.operation ?? "release", "validation_failed", `Detached package heads require manual recovery:
+${blockers.join("\n")}`, {
+      details: { blockers, reports }
+    });
+  }
+  return { reports, blockers };
+}
 function collectReleasePackageSelection(root) {
   const publishable = sortWorkspacePackages(
     publishableWorkspacePackages(root).filter((pkg) => pkg.name?.startsWith("@treeseed/"))
@@ -2143,11 +2168,16 @@ async function workflowSwitch(helpers, input) {
     return await withContextEnv(helpers.context.env, async () => {
       const tenantRoot = resolveProjectRootOrThrow("switch", helpers.cwd());
       const root = workspaceRoot(tenantRoot);
-      const session = resolveTreeseedWorkflowSession(root);
       const branchName = String(input.branch ?? input.branchName ?? "").trim();
       if (!branchName) {
         workflowError("switch", "validation_failed", "Treeseed switch requires a branch name.");
       }
+      reattachRepairablePackageRepos(root, [branchName, STAGING_BRANCH, PRODUCTION_BRANCH], {
+        operation: "switch",
+        onProgress: (line, stream) => helpers.write(line, stream),
+        throwOnBlocker: true
+      });
+      const session = resolveTreeseedWorkflowSession(root);
       const preview = input.preview === true;
       const executionMode = normalizeExecutionMode(input);
       if (executionMode !== "plan" && shouldDispatchSwitchToManagedWorktree(root, input, helpers.context.env)) {
@@ -2410,6 +2440,12 @@ async function workflowSave(helpers, input) {
     return await withContextEnv(helpers.context.env, async () => {
       const tenantRoot = resolveProjectRootOrThrow("save", helpers.cwd());
       const root = workspaceRoot(tenantRoot);
+      const rootBranch = currentBranch(repoRoot(root)) || null;
+      reattachRepairablePackageRepos(root, [rootBranch, STAGING_BRANCH, PRODUCTION_BRANCH].filter((branch2) => Boolean(branch2)), {
+        operation: "save",
+        onProgress: (line, stream) => helpers.write(line, stream),
+        throwOnBlocker: true
+      });
       const session = resolveTreeseedWorkflowSession(root);
       const gitRoot = session.gitRoot;
       const branch = session.branchName;
@@ -3275,6 +3311,11 @@ async function workflowRelease(helpers, input) {
   try {
     return await withContextEnv(helpers.context.env, async () => {
       const root = resolveProjectRootOrThrow("release", helpers.cwd());
+      reattachRepairablePackageRepos(root, [STAGING_BRANCH, PRODUCTION_BRANCH], {
+        operation: "release",
+        onProgress: (line, stream) => helpers.write(line, stream),
+        throwOnBlocker: true
+      });
       const session = resolveTreeseedWorkflowSession(root);
       const gitRoot = session.gitRoot;
       const mode = session.mode;
@@ -3439,7 +3480,11 @@ async function workflowRelease(helpers, input) {
               branch: PRODUCTION_BRANCH,
               headSha: String(rootRelease2?.releasedCommit ?? rootRepo.commitSha ?? "")
             }
-          ].filter((gate) => gate.headSha), ciMode, { root, runId: workflowRun.runId }).then((workflowGates) => ({ workflowGates })));
+          ].filter((gate) => gate.headSha), ciMode, {
+            root,
+            runId: workflowRun.runId,
+            onProgress: (line, stream) => helpers.write(line, stream)
+          }).then((workflowGates) => ({ workflowGates })));
           const releaseBackMerge2 = await executeJournalStep(root, workflowRun.runId, "release-back-merge", () => backMergeRootProductionIntoStaging(root, false));
           const workspaceLinks2 = ensureWorkflowWorkspaceLinks(root, helpers, effectiveInput.workspaceLinks ?? "auto");
           const payload2 = {
@@ -3556,7 +3601,11 @@ async function workflowRelease(helpers, input) {
                 headSha: mergeResult.commitSha,
                 branch: PRODUCTION_BRANCH
               }
-            ], ciMode, { root, runId: workflowRun.runId });
+            ], ciMode, {
+              root,
+              runId: workflowRun.runId,
+              onProgress: (line, stream) => helpers.write(line, stream)
+            });
             const publish = workflowGates.find((gate) => gate.workflow === "publish.yml") ?? workflowGates[0] ?? null;
             assertReleaseGitHubWorkflowSucceeded(pkg.name, publish);
             const backMerge = backMergeProductionIntoStaging(pkg.dir, pkg.name);
@@ -3667,7 +3716,11 @@ async function workflowRelease(helpers, input) {
             branch: PRODUCTION_BRANCH,
             headSha: String(rootRelease?.releasedCommit ?? rootRepo.commitSha ?? "")
           }
-        ].filter((gate) => gate.headSha), ciMode, { root, runId: workflowRun.runId }).then((workflowGates) => ({ workflowGates })));
+        ].filter((gate) => gate.headSha), ciMode, {
+          root,
+          runId: workflowRun.runId,
+          onProgress: (line, stream) => helpers.write(line, stream)
+        }).then((workflowGates) => ({ workflowGates })));
         const releaseBackMerge = await executeJournalStep(root, workflowRun.runId, "release-back-merge", () => backMergeRootProductionIntoStaging(root, true));
         const devTagCleanupMode = effectiveInput.devTagCleanup ?? "safe-after-release";
         const devTagCleanup = devTagCleanupMode === "off" ? (skipJournalStep(root, workflowRun.runId, "cleanup-dev-tags", { status: "skipped", reason: "disabled" }), { status: "skipped", reason: "disabled" }) : await executeJournalStep(root, workflowRun.runId, "cleanup-dev-tags", () => {
@@ -3740,13 +3793,29 @@ async function workflowRelease(helpers, input) {
         });
       } catch (error) {
         ensureWorkflowWorkspaceLinks(root, helpers, 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;
+        helpers.write(`[release][recovery] Last release phase: ${lastCompleted?.id ?? "not-started"}; next phase: ${nextPending?.id ?? "none"}.`, "stderr");
+        try {
+          const repair = reattachRepairablePackageRepos(root, [STAGING_BRANCH, PRODUCTION_BRANCH], {
+            onProgress: (line, stream) => helpers.write(line, stream)
+          });
+          if (repair.blockers.length > 0) {
+            helpers.write(`[release][recovery] Package repos need manual review before retrying:
+${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");
         failWorkflowRun(root, workflowRun.runId, error, {
           resumable: true,
           runId: workflowRun.runId,
           command: "release",
-          message: `Resume the interrupted release on ${STAGING_BRANCH}.`,
-          recoverCommand: "treeseed recover",
-          resumeCommand: `treeseed resume ${workflowRun.runId}`
+          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`
         });
         throw error;
       }

package/dist/workflow-state.d.ts

@@ -93,8 +93,11 @@ export type TreeseedWorkflowState = {
             aligned: boolean;
             localBranch: boolean;
             remoteBranch: boolean;
+            detached: boolean;
+            detachedRepair: Record<string, unknown> | null;
         }>;
         blockers: string[];
+        warnings: string[];
     };
     preview: {
         enabled: boolean;

package/dist/workflow-state.js

@@ -24,6 +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 { inspectDetachedHeadRepair, PRODUCTION_BRANCH, STAGING_BRANCH } from "./operations/services/git-workflow.js";
 import { classifyWorkflowRunJournals, inspectWorkflowLock } from "./workflow/runs.js";
 import { createTreeseedManagedToolEnv, resolveTreeseedToolCommand } from "./managed-dependencies.js";
 import {
@@ -306,6 +307,7 @@ function resolveTreeseedWorkflowState(cwd, options = {}) {
     const repoBranch = currentBranch(pkg.dir) || null;
     const dirty = gitStatusPorcelain(pkg.dir).length > 0;
     const expectedBranch = branchName;
+    const detachedRepair = repoBranch ? null : inspectDetachedHeadRepair(pkg.dir, [expectedBranch, STAGING_BRANCH, PRODUCTION_BRANCH].filter((branch) => Boolean(branch)));
     let localBranch = false;
     if (expectedBranch) {
       if (repoBranch === expectedBranch) {
@@ -327,14 +329,35 @@ function resolveTreeseedWorkflowState(cwd, options = {}) {
       dirty,
       aligned: expectedBranch ? repoBranch === expectedBranch : true,
       localBranch,
-      remoteBranch
+      remoteBranch,
+      detached: repoBranch == null,
+      detachedRepair: detachedRepair ? {
+        repairable: detachedRepair.repairable,
+        targetBranch: detachedRepair.targetBranch,
+        headSha: detachedRepair.headSha,
+        targetSha: detachedRepair.targetSha,
+        dirty: detachedRepair.dirty,
+        blocker: detachedRepair.blocker
+      } : null
     };
   }) : [];
   const packageSyncBlockers = [];
+  const packageSyncWarnings = [];
   for (const repo of packageSyncRepos) {
     if (repo.dirty) {
       packageSyncBlockers.push(`${repo.name} has uncommitted changes.`);
     }
+    const detachedRepair = repo.detachedRepair;
+    if (repo.detached && detachedRepair?.repairable === true) {
+      const targetBranch = typeof detachedRepair.targetBranch === "string" ? detachedRepair.targetBranch : branchName;
+      const dirtyNote = detachedRepair.dirty === true ? " with local changes preserved" : "";
+      packageSyncWarnings.push(`${repo.name} is detached at ${targetBranch ?? "an expected branch"} HEAD${dirtyNote}; workflow commands can reattach it automatically.`);
+      continue;
+    }
+    if (repo.detached && detachedRepair?.repairable !== true) {
+      packageSyncBlockers.push(`${repo.name} is detached at a commit that does not match ${branchName ?? STAGING_BRANCH}/${PRODUCTION_BRANCH}; review manually.`);
+      continue;
+    }
     if (branchName && !repo.localBranch && !repo.remoteBranch) {
       packageSyncBlockers.push(`${repo.name} is missing branch ${branchName}.`);
       continue;
@@ -424,7 +447,8 @@ function resolveTreeseedWorkflowState(cwd, options = {}) {
       aligned: packageSyncRepos.every((repo) => repo.aligned),
       dirty: packageSyncRepos.some((repo) => repo.dirty),
       repos: packageSyncRepos,
-      blockers: packageSyncBlockers
+      blockers: packageSyncBlockers,
+      warnings: packageSyncWarnings
     },
     preview: {
       enabled: false,
@@ -707,6 +731,13 @@ function recommendTreeseedNextSteps(state) {
     return recommendations.slice(0, 3);
   }
   if (state.branchRole === "staging") {
+    if (state.packageSync.mode === "recursive-workspace" && state.packageSync.warnings.length > 0 && state.branchName) {
+      recommendations.push({
+        operation: "release",
+        reason: "Reattach repairable package repos automatically before continuing the release.",
+        input: { bump: "patch" }
+      });
+    }
     if (state.packageSync.mode === "recursive-workspace" && state.packageSync.blockers.length > 0 && state.branchName) {
       recommendations.push({
         operation: "switch",

package/package.json

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