omp-conductor 0.3.9 → 0.3.12

package/src/orchestrator-tick.ts

@@ -1,7 +1,7 @@
 /**
  * Self-tick for the fleet orchestrator session.
  *
- * The orchestrator is a 24/7 omp session with a standing brief (ORCHESTRATOR.md)
+ * The orchestrator is a 24/7 omp session with a standing brief (composed ORCHESTRATOR.md + POLICY.md)
  * and no user typing into it. A session that is never prompted never runs its
  * loop, so this extension is the heartbeat: every `intervalSeconds` it injects
  * one message that starts a turn.
@@ -44,6 +44,11 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { findProject, loadConfig } from "./config.ts";
+import {
+  briefPathForProject,
+  policyPathForProject,
+  refreshComposedBriefForProject,
+} from "./setup.ts";
 import { DEFAULT_REPORT_SCOPE, type ReportScope } from "./types.ts";
 
 /** The activation file. Absent means "this is not an orchestrator session". */
@@ -94,6 +99,14 @@ const RETRY_OWNERSHIP_MS = 60_000;
 export const STALL_MARKER_FILE = ".conductor-stalled";
 export const STALL_TICKS = 2;
 
+/**
+ * Written by herdr-conductor `recover.sh` *before* `agent start`, so a resumed
+ * fleet can reconcile orphans without waiting a full `intervalSeconds`. Cleared
+ * only after a tick is actually sent — a disarmed or channel-down fleet keeps
+ * the request until gates pass (or a human removes the file).
+ */
+export const TICK_REQUESTED_FILE = ".conductor-tick-requested";
+
 /**
  * The marker's one line after its ISO timestamp, and the middle of the error
  * log. Shared so the file and the log can never describe different failures.
@@ -229,8 +242,16 @@ export type TickConfigResult =
  * A second spelling of it here would contradict the first inside one prompt the
  * moment a fleet chose `escalations`.
  */
-export function defaultTickMessage(now: Date, briefPath = "ORCHESTRATOR.md"): string {
-  return `Tick ${now.toISOString()}: re-read ${briefPath} from disk, then run your standing loop from it.`;
+export function defaultTickMessage(
+  now: Date,
+  briefPath = "ORCHESTRATOR.md",
+  policyPath = "POLICY.md",
+): string {
+  return (
+    `Tick ${now.toISOString()}: re-read ${briefPath} (composed package floor + policy) and ` +
+    `${policyPath} (editable fleet policy) from disk, then run your standing loop from them. ` +
+    `Learning-loop amendments edit only ${policyPath} — never the package floor.`
+  );
 }
 
 /**
@@ -288,18 +309,43 @@ export const TICK_DELIVERY_RULE =
  * `status`. Stopping the heartbeat over either preference would be the worse
  * trade.
  */
-export function resolveTickScope(): { scope: ReportScope; briefPath?: string; fallback?: string } {
+export function resolveTickScope(): {
+  scope: ReportScope;
+  briefPath?: string;
+  policyPath?: string;
+  projectName?: string;
+  fallback?: string;
+} {
   try {
     const project = findProject(loadConfig());
     return {
       scope: project.reporting?.scope ?? DEFAULT_REPORT_SCOPE,
-      briefPath: join(project.workspaceRoot, "ORCHESTRATOR.md"),
+      briefPath: briefPathForProject(project),
+      policyPath: policyPathForProject(project),
+      projectName: project.name,
     };
   } catch (err) {
     return { scope: DEFAULT_REPORT_SCOPE, fallback: err instanceof Error ? err.message : String(err) };
   }
 }
 
+/**
+ * Best-effort recompose of `ORCHESTRATOR.md` from the installed package floor +
+ * live `POLICY.md`.
+ *
+ * Runs on **every** successful send — including ticks that use a custom
+ * `message` — so protocol updates land after `npm install` without waiting for
+ * the default prompt path. Failures (no config, no `POLICY.md`, unreadable
+ * overlay) are silent: the tick still goes out.
+ */
+export function refreshComposedBriefBestEffort(): boolean {
+  try {
+    return refreshComposedBriefForProject(findProject(loadConfig()));
+  } catch {
+    return false;
+  }
+}
+
 /**
  * An optional file-path field. Relative paths resolve against the session cwd
  * so `state/armed` means what it looks like; a present-but-unusable value is a
@@ -834,6 +880,23 @@ function clearStallMarker(pi: TickApi, cwd: string): void {
   }
 }
 
+/**
+ * Best-effort, same posture as {@link clearStallMarker}. Leaving the file on a
+ * failed unlink means the next successful send retries the clear; that is
+ * preferable to treating a recover poke as fire-and-forget when the tick did
+ * land.
+ */
+function clearTickRequest(pi: TickApi, cwd: string): void {
+  const path = join(cwd, TICK_REQUESTED_FILE);
+  if (!existsSync(path)) return;
+  try {
+    rmSync(path, { force: true });
+    pi.logger.info("[omp-conductor] recover tick request cleared: a tick was sent");
+  } catch (err) {
+    pi.logger.error(`[omp-conductor] could not remove ${path}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 /** Everything one tick remembers for the next. */
 interface TickSession {
   /**
@@ -878,6 +941,10 @@ function tick(pi: TickApi, ctx: TickContext, config: TickConfig, session: TickSe
     return;
   }
 
+  // Floor refresh is independent of which prompt we send: a custom message still
+  // expects ORCHESTRATOR.md / AGENTS.md to track the installed package.
+  refreshComposedBriefBestEffort();
+
   // A configured message owns the whole contract, reporting and delivery clauses
   // included: an operator who wrote their own prompt did not ask for ours
   // appended to it.
@@ -888,7 +955,7 @@ function tick(pi: TickApi, ctx: TickContext, config: TickConfig, session: TickSe
       session.scopeFallbackLogged = true;
       pi.logger.info(`[omp-conductor] tick reporting scope: using ${DEFAULT_REPORT_SCOPE} — ${scope.fallback}`);
     }
-    content = `${defaultTickMessage(new Date(), scope.briefPath)}\n${TICK_SCOPE_CONSTRAINTS[scope.scope]}\n${TICK_DELIVERY_RULE}`;
+    content = `${defaultTickMessage(new Date(), scope.briefPath, scope.policyPath)}\n${TICK_SCOPE_CONSTRAINTS[scope.scope]}\n${TICK_DELIVERY_RULE}`;
   }
 
   pi.sendMessage(
@@ -900,6 +967,21 @@ function tick(pi: TickApi, ctx: TickContext, config: TickConfig, session: TickSe
   // this is the only place either the counter or the marker is cleared.
   session.pendingSkips = 0;
   clearStallMarker(pi, ctx.cwd);
+  // Recover poke is consumed only on a real send — gates still apply above.
+  clearTickRequest(pi, ctx.cwd);
+}
+
+/**
+ * Arm the interval heartbeat, then honour a recover poke if one is waiting.
+ * Extracted so the ownership-retry path and the immediate-accept path cannot
+ * drift: both must fire the same "do not wait a full interval after resume"
+ * behaviour.
+ */
+function armTickHeartbeat(pi: TickApi, ctx: TickContext, config: TickConfig, session: TickSession): void {
+  ctx.setInterval(() => tick(pi, ctx, config, session), config.intervalSeconds * 1000);
+  if (!existsSync(join(ctx.cwd, TICK_REQUESTED_FILE))) return;
+  pi.logger.info("[omp-conductor] tick requested by recover — firing without waiting for the interval");
+  tick(pi, ctx, config, session);
 }
 
 export default function orchestratorTickExtension(pi: TickApi): void {
@@ -995,7 +1077,7 @@ export default function orchestratorTickExtension(pi: TickApi): void {
           return;
         }
         if (next.note !== undefined) pi.logger.error(`[omp-conductor] tick ownership: ${next.note}`);
-        ctx.setInterval(() => tick(pi, ctx, config, session), config.intervalSeconds * 1000);
+        armTickHeartbeat(pi, ctx, config, session);
         pi.logger.info(`[omp-conductor] orchestrator tick active: ownership resolved on retry`, { agentName });
       }, retryMs);
       decided = true;
@@ -1008,7 +1090,7 @@ export default function orchestratorTickExtension(pi: TickApi): void {
       return;
     }
     if (ownership.note !== undefined) pi.logger.error(`[omp-conductor] tick ownership: ${ownership.note}`);
-    ctx.setInterval(() => tick(pi, ctx, config, session), config.intervalSeconds * 1000);
+    armTickHeartbeat(pi, ctx, config, session);
     decided = true;
     // Both gates are named at startup: "why is it not ticking?" is answered by
     // looking at the files this line lists, and an unset channel gate on a fleet

package/src/plugin.ts

@@ -11,8 +11,15 @@
  * worth protecting is on `setup()` below — nothing is written before the confirm.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { isAbsolute } from "node:path";
-import { checkBrief, formatBriefStatus, writeMergedBrief } from "./brief-upgrade.ts";
+import { dirname, isAbsolute } from "node:path";
+import {
+  checkBrief,
+  formatBriefStatus,
+  formatMigrateResult,
+  inspectBriefLayout,
+  migrateToPolicy,
+  writeMergedBrief,
+} from "./brief-upgrade.ts";
 import { configPath, expandHome, findProject, loadConfig, saveConfig } from "./config.ts";
 import {
   armConductor,
@@ -27,11 +34,14 @@ import { defaultGraphRoot } from "./graph.ts";
 import {
   AMEND_AREAS,
   ORCHESTRATOR_BRIEF_NAME,
+  POLICY_BRIEF_NAME,
   REPORT_SCOPE_CHOICES,
   SETUP_DEFAULTS,
   amendChoices,
   answersFromProject,
   briefPathForProject,
+  policyPathForProject,
+  renderFloorForProject,
   buildConfig,
   checkTokenScopes,
   createMissingLabels,
@@ -374,17 +384,17 @@ async function askGraphRoot(
 async function askOrchestratorBrief(ctx: CommandContext, a: SetupAnswers): Promise<boolean> {
   const path = orchestratorBriefPath(a);
   const wanted = await ctx.ui.confirm(
-    `Write an orchestrator brief template to ${path}?`,
-    `It is the standing prompt for your supervising session: duties, tiers, and boundaries, ` +
-      `plus a release policy and a reporting section that are yours to edit. ` +
-      `The conductor never reads it back — it stops at green PRs either way.`,
+    `Write ${ORCHESTRATOR_BRIEF_NAME} + ${POLICY_BRIEF_NAME} under ${dirname(path)}?`,
+    `Writes composed ${ORCHESTRATOR_BRIEF_NAME} (package floor, refreshed each tick) and ${POLICY_BRIEF_NAME} ` +
+      `(Releases, Project context, Reporting, Amendments — yours to edit via the Learning loop). ` +
+      `The conductor stops at green PRs either way.`,
   );
   if (!wanted) return false;
   if (!existsSync(path)) return true;
 
   return await ctx.ui.confirm(
-    `Overwrite the existing ${ORCHESTRATOR_BRIEF_NAME}?`,
-    `${path} already exists. Overwriting replaces it with the shipped template — any policy you wrote there is lost.`,
+    `Overwrite existing ${ORCHESTRATOR_BRIEF_NAME} / ${POLICY_BRIEF_NAME}?`,
+    `${path} already exists. Overwriting replaces the composed brief and POLICY.md scaffold — any policy you wrote is lost.`,
   );
 }
 
@@ -885,7 +895,7 @@ async function setup(ctx: CommandContext, projectArg: string | undefined): Promi
       `Wrote ${path} and armed the conductor.`,
       briefPath === undefined
         ? "No orchestrator brief written — the conductor stops at green PRs; merges and releases stay human."
-        : `Wrote ${briefPath} — edit its "Releases" and "Reporting" sections; nothing here reads them back.`,
+        : `Wrote ${briefPath} + POLICY.md — edit POLICY.md (Releases/Reporting); floor refreshes each tick.`,
       "",
       "Dry run against the config just written:",
       ...(await tryPreview(answers.projectName)),
@@ -929,18 +939,51 @@ export default function conductorPlugin(pi: PluginApi): void {
           case "brief-upgrade": {
             const p = findProject(loadConfig(), project);
             const path = briefPathForProject(p);
-            if (!existsSync(path)) {
+            const rendered = renderBriefForProject(p);
+            const layout = inspectBriefLayout(p.workspaceRoot, rendered);
+            if (layout.kind === "missing") {
+              ctx.ui.notify(
+                `No brief at ${path} — run /conductor setup and say yes to writing ${ORCHESTRATOR_BRIEF_NAME} + ${POLICY_BRIEF_NAME}.`,
+                "warning",
+              );
+              break;
+            }
+            if (layout.kind === "overlay") {
               ctx.ui.notify(
-                `No brief at ${path} — run /conductor setup and say yes to writing ${ORCHESTRATOR_BRIEF_NAME}.`,
+                formatBriefStatus(path, {
+                  kind: "overlay",
+                  policyPath: layout.policyPath,
+                  orchestratorPath: layout.orchestratorPath,
+                }),
+                "info",
+              );
+              break;
+            }
+            if (layout.kind === "legacy-bannered") {
+              ctx.ui.notify(
+                [
+                  `Legacy bannered brief at ${layout.orchestratorPath}.`,
+                  "Migrate the owned half into POLICY.md so the package floor refreshes each tick.",
+                ].join("\n"),
                 "warning",
               );
+              const migrate = await ctx.ui.confirm(
+                "Migrate to POLICY.md overlay?",
+                "Writes POLICY.md from everything below YOURS TO EDIT, recomposes ORCHESTRATOR.md from the package floor + that policy, and keeps backups.",
+              );
+              if (migrate) {
+                const result = migrateToPolicy({
+                  orchestratorPath: layout.orchestratorPath,
+                  policyPath: policyPathForProject(p),
+                  floor: renderFloorForProject(p),
+                  owned: layout.owned,
+                });
+                ctx.ui.notify(formatMigrateResult(result), "info");
+              }
               break;
             }
-            const status = checkBrief(readFileSync(path, "utf8"), renderBriefForProject(p));
-            ctx.ui.notify(formatBriefStatus(path, status), status.kind === "current" ? "info" : "warning");
-            // Confirmed here rather than applied on sight: this file is a standing
-            // prompt the operator may have spent an hour on, so the diff they just
-            // read is the thing they are agreeing to.
+            const status = checkBrief(readFileSync(path, "utf8"), rendered);
+            ctx.ui.notify(formatBriefStatus(path, status), "warning");
             if (status.kind === "mergeable") {
               const apply = await ctx.ui.confirm(
                 "Upgrade the brief?",

package/src/setup.ts

@@ -23,6 +23,15 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import {
+  COMPOSE_BANNER,
+  ORCHESTRATOR_BRIEF_NAME,
+  POLICY_BRIEF_NAME,
+  composeOrchestrator,
+  policyPathForRoot,
+  renderBriefTemplate,
+  writeWithBackup,
+} from "./brief-upgrade.ts";
 import { configPath, resolveCaps, stateDir } from "./config.ts";
 import { graphProjectPath, graphRepos } from "./graph.ts";
 import {
@@ -37,7 +46,6 @@ import {
   type ReportScope,
   type RepoTarget,
 } from "./types.ts";
-import { renderBrief } from "./worker.ts";
 
 /**
  * Every decision the wizard needs, in one plain object. Collected by the UI,
@@ -197,12 +205,14 @@ export const MERGE_DUTY: { readonly [K in ProjectConfig["authority"]["merge"]]:
     "  one is a hard boundary, not a preference.",
 };
 
-/** The operator's own brief, rendered into the project's workspace root. */
-export const ORCHESTRATOR_BRIEF_NAME = "ORCHESTRATOR.md";
+export { ORCHESTRATOR_BRIEF_NAME, POLICY_BRIEF_NAME };
 
-/** Shipped in `files[]`, so this resolves in an installed package too. */
+/** Shipped floor template — duties, tiers, hard boundaries, Learning loop. */
 const ORCHESTRATOR_TEMPLATE_PATH = join(import.meta.dir, "briefs", "orchestrator.md");
 
+/** Shipped POLICY.md scaffold — Releases, Project context, Reporting, Amendments. */
+const POLICY_TEMPLATE_PATH = join(import.meta.dir, "briefs", "policy.md");
+
 /**
  * `repo` writes labels and closes issues; `project` moves cards on the board.
  * Both are load-bearing for an unattended loop, so a missing one is reported
@@ -572,46 +582,69 @@ export function answersFromProject(p: ProjectConfig): SetupAnswers {
 }
 
 /**
- * Where a configured project's brief lives: beside its worktrees, under the state
- * directory, so it is on the same disk the fleet already owns and survives a
- * reinstall of the package. Derived from the project rather than fixed, so a
- * project that ever gains a chosen workspace root keeps its brief with it.
+ * Where a configured project's composed brief lives: beside its worktrees, under
+ * the state directory, so it is on the same disk the fleet already owns and
+ * survives a reinstall of the package. Derived from the project rather than
+ * fixed, so a project that ever gains a chosen workspace root keeps its brief
+ * with it.
  */
 export function briefPathForProject(p: ProjectConfig): string {
   return join(p.workspaceRoot, ORCHESTRATOR_BRIEF_NAME);
 }
 
-/**
- * The brief template exactly as shipped, placeholders and all.
- *
- * Exported for the upgrade check, which has to be able to read the shipped text
- * on a host that has no config to render it against.
- */
-export function shippedBriefTemplate(): string {
-  return readFileSync(ORCHESTRATOR_TEMPLATE_PATH, "utf8");
+/** Where the fleet-owned POLICY.md overlay lives for a project. */
+export function policyPathForProject(p: ProjectConfig): string {
+  return policyPathForRoot(p.workspaceRoot);
 }
 
-/**
- * The shipped template with a configured project's real values in it.
- *
- * Only the coordinates, the chosen scope and the authority paragraph are
- * substituted: the rest of the policy text is left exactly as shipped, because
- * from here on the file is the operator's to edit and nothing in this package
- * reads it back.
- *
- * Takes a `ProjectConfig` rather than answers so that a *later* upgrade check can
- * reproduce the same render from what is on disk, months after the wizard's
- * answers are gone.
- */
-export function renderBriefForProject(p: ProjectConfig): string {
-  return renderBrief(readFileSync(ORCHESTRATOR_TEMPLATE_PATH, "utf8"), {
+function briefVarsForProject(p: ProjectConfig): Record<string, string> {
+  return {
     PROJECT: p.name,
     TRACKER_REPO: p.tracker.repo,
     QUEUE_LABEL: p.queueLabel,
     RELEASES_DEFAULT: RELEASES_DEFAULTS[`${p.authority.merge}/${p.authority.release}`],
     MERGE_DUTY: MERGE_DUTY[p.authority.merge],
     REPORT_SCOPE: p.reporting?.scope ?? DEFAULT_REPORT_SCOPE,
-  });
+  };
+}
+
+/** Package floor template, placeholders and all. */
+export function shippedFloorTemplate(): string {
+  return readFileSync(ORCHESTRATOR_TEMPLATE_PATH, "utf8");
+}
+
+/** POLICY.md scaffold template, placeholders and all. */
+export function shippedPolicyTemplate(): string {
+  return readFileSync(POLICY_TEMPLATE_PATH, "utf8");
+}
+
+/**
+ * Floor + policy templates concatenated with the compose banner, placeholders
+ * intact. Used when no project config is available to render coordinates.
+ */
+export function shippedBriefTemplate(): string {
+  return composeOrchestrator(shippedFloorTemplate(), shippedPolicyTemplate());
+}
+
+/** Rendered package floor for a configured project. */
+export function renderFloorForProject(p: ProjectConfig): string {
+  return renderBriefTemplate(shippedFloorTemplate(), briefVarsForProject(p));
+}
+
+/** Rendered POLICY.md scaffold for a configured project. */
+export function renderPolicyForProject(p: ProjectConfig): string {
+  return renderBriefTemplate(shippedPolicyTemplate(), briefVarsForProject(p));
+}
+
+/**
+ * Composed session brief: rendered floor + POLICY scaffold (or a caller's policy).
+ *
+ * Setup writes the policy half to `POLICY.md` and this compose to
+ * `ORCHESTRATOR.md`. Later ticks recompose from the live POLICY.md so package
+ * floor updates apply without brief-upgrade.
+ */
+export function renderBriefForProject(p: ProjectConfig, policyText?: string): string {
+  return composeOrchestrator(renderFloorForProject(p), policyText ?? renderPolicyForProject(p));
 }
 
 /** Wizard-time path, via the project the answers describe. */
@@ -625,7 +658,7 @@ export function renderOrchestratorBrief(a: SetupAnswers): string {
 }
 
 /**
- * Writes the rendered brief and returns where it went.
+ * Writes `POLICY.md` + composed `ORCHESTRATOR.md`, and returns the composed path.
  *
  * Unconditional by design: the "do not clobber my edits" decision belongs to the
  * operator, is asked in the wizard, and arrives here as
@@ -634,10 +667,39 @@ export function renderOrchestratorBrief(a: SetupAnswers): string {
  * must get an overwrite.
  */
 export function writeOrchestratorBrief(a: SetupAnswers): string {
-  const path = orchestratorBriefPath(a);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, renderOrchestratorBrief(a));
-  return path;
+  const project = buildProject(a);
+  const policyPath = policyPathForProject(project);
+  const orchestratorPath = briefPathForProject(project);
+  mkdirSync(dirname(orchestratorPath), { recursive: true });
+  const policy = renderPolicyForProject(project);
+  writeFileSync(policyPath, policy);
+  writeFileSync(orchestratorPath, composeOrchestrator(renderFloorForProject(project), policy));
+  return orchestratorPath;
+}
+
+/**
+ * Recompose `ORCHESTRATOR.md` from the package floor + live `POLICY.md`.
+ *
+ * Returns false when POLICY.md is missing (caller should migrate or set up).
+ */
+export function refreshComposedBriefForProject(p: ProjectConfig): boolean {
+  const policyPath = policyPathForProject(p);
+  if (!existsSync(policyPath)) return false;
+  const orchestratorPath = briefPathForProject(p);
+  mkdirSync(dirname(orchestratorPath), { recursive: true });
+  writeFileSync(
+    orchestratorPath,
+    composeOrchestrator(renderFloorForProject(p), readFileSync(policyPath, "utf8")),
+  );
+  return true;
+}
+
+/** @internal test helper — expose compose banner for assertions. */
+export const BRIEF_COMPOSE_BANNER = COMPOSE_BANNER;
+
+/** Backup-aware POLICY write used by migrate paths that already computed text. */
+export function writePolicyFile(path: string, content: string): string | undefined {
+  return writeWithBackup(path, content);
 }
 
 /**
@@ -861,11 +923,12 @@ export function summarisePlan(
     `  scope          ${a.reportScope} — ${chosen?.description ?? "unknown scope"}`,
   );
   if (a.writeOrchestratorBrief) {
+    const policyPath = briefPath.replace(/ORCHESTRATOR\.md$/, "POLICY.md");
     lines.push(
-      existsSync(briefPath)
-        ? `  brief          would OVERWRITE ${briefPath}`
-        : `  brief          would write ${briefPath}`,
-      "                 yours to edit afterwards — release policy lives there, not in this package",
+      existsSync(briefPath) || existsSync(policyPath)
+        ? `  brief          would OVERWRITE ${briefPath} + POLICY.md`
+        : `  brief          would write ${briefPath} + POLICY.md`,
+      "                 POLICY.md is yours — Releases/Reporting/Amendments; floor recomposes each tick",
     );
   } else {
     lines.push(
@@ -1002,7 +1065,7 @@ export const AMEND_AREAS: {
   },
   brief: {
     name: "orchestrator brief",
-    asks: `whether to render ${ORCHESTRATOR_BRIEF_NAME} — the one area that writes no config key`,
+    asks: `whether to write ${ORCHESTRATOR_BRIEF_NAME} + ${POLICY_BRIEF_NAME} — the one area that writes no config key`,
     describe: (p) => {
       const path = briefPathForProject(p);
       return existsSync(path) ? `written at ${path}` : `none at ${path}`;

package/src/worktree.ts

@@ -379,7 +379,17 @@ export async function addWorktree(
  * none of that may be skipped by an exception from the last-ditch step.
  */
 export type SalvageOutcome =
-  | { kind: "salvaged"; sha: string; branch: string; pushed: boolean; pushError?: string }
+  | {
+      kind: "salvaged";
+      sha: string;
+      branch: string;
+      pushed: boolean;
+      pushError?: string;
+      /** Paths in the salvage commit (count = length). */
+      files: string[];
+      /** Subset that were untracked before salvage (`A` in the commit). */
+      newPaths: string[];
+    }
   /** Nothing uncommitted was there to save — a clean tree, or no tree at all. */
   | { kind: "nothing" }
   /** There was work and git would not commit it. This is the loud one. */
@@ -403,6 +413,51 @@ const SALVAGE_COMMIT_CONFIG = [
   "commit.gpgsign=false",
 ];
 
+/**
+ * Subject stays the historical one-liner so status greps keep working; the
+ * body is the manifest (#38). Cap the new-path list so a runaway tree cannot
+ * push a multi-kilobyte commit message into every escalation.
+ */
+export function salvageCommitMessage(
+  issue: number,
+  attempt: number,
+  reason: string,
+  files: string[],
+  newPaths: string[],
+): { subject: string; body: string } {
+  const subject = `wip(#${issue}): attempt ${attempt} killed by ${reason} — auto-salvaged`;
+  const n = files.length;
+  const count = `${n} file${n === 1 ? "" : "s"}`;
+  if (newPaths.length === 0) {
+    return { subject, body: `${count} (all modifications to tracked paths).` };
+  }
+  const cap = 30;
+  const shown = newPaths.slice(0, cap);
+  const more = newPaths.length - shown.length;
+  const list = shown.map((f) => `  ${f}`).join("\n");
+  const suffix = more > 0 ? `\n  … and ${more} more` : "";
+  return {
+    subject,
+    body: `${count}. New (untracked before salvage):\n${list}${suffix}`,
+  };
+}
+
+function parseCachedNameStatus(raw: string): { files: string[]; newPaths: string[] } {
+  const files: string[] = [];
+  const newPaths: string[] = [];
+  for (const line of raw.split("\n")) {
+    if (line === "") continue;
+    // name-status: "<status>\t<path>" or rename "R100\t<old>\t<new>"
+    const parts = line.split("\t");
+    const status = parts[0] ?? "";
+    const path = parts.length >= 3 ? (parts[2] ?? parts[1] ?? "") : (parts[1] ?? "");
+    if (path === "") continue;
+    files.push(path);
+    if (status.startsWith("A")) newPaths.push(path);
+  }
+  return { files, newPaths };
+}
+
 /**
  * Commits a dead run's uncommitted work to the run's own branch and pushes it,
  * so that the tree the next attempt destroys is no longer the only copy.
@@ -472,40 +527,42 @@ export async function salvageWip(
     // only changes were ignored scratch had work by that test and none by this.
     // Without this, `commit` exits non-zero on an empty index and a tree
     // holding nothing worth keeping gets reported as a salvage *failure*.
-    if ((await git(["diff", "--cached", "--name-only"], worktree)) === "") {
+    const cached = await git(["diff", "--cached", "--name-status"], worktree);
+    if (cached === "") {
       return { kind: "nothing" };
     }
+    const { files, newPaths } = parseCachedNameStatus(cached);
+    const msg = salvageCommitMessage(issue, attempt, reason, files, newPaths);
     await git(
       [
         ...SALVAGE_COMMIT_CONFIG,
         "commit",
         "--no-verify",
         "-m",
-        `wip(#${issue}): attempt ${attempt} killed by ${reason} — auto-salvaged`,
+        msg.subject,
+        "-m",
+        msg.body,
       ],
       worktree,
     );
     const sha = await git(["rev-parse", "HEAD"], worktree);
+    const salvaged = { kind: "salvaged" as const, sha, branch, files, newPaths };
 
     if (branch === "HEAD") {
       // Detached: the commit is real but reachable only by sha, and pushing
       // `HEAD` from here would publish a branch literally named HEAD.
       return {
-        kind: "salvaged",
-        sha,
-        branch,
+        ...salvaged,
         pushed: false,
         pushError: "detached HEAD — no branch to push",
       };
     }
 
     const push = await runGit(["push", "origin", `HEAD:refs/heads/${branch}`], worktree);
-    if (push.code === 0) return { kind: "salvaged", sha, branch, pushed: true };
+    if (push.code === 0) return { ...salvaged, pushed: true };
 
     return {
-      kind: "salvaged",
-      sha,
-      branch,
+      ...salvaged,
       pushed: false,
       pushError: (
         push.stderr.trim() ||