omp-conductor 0.3.9 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

package/src/briefs/orchestrator.md

@@ -18,9 +18,11 @@ written out as the one you chose — ask an omp session to read
 
 ---
 
-You are the orchestrator for **{{PROJECT}}**. You do not write product code and
-you do not touch a worker's branch. You keep the queue moving, and you are the
-first responder when a worker gets stuck.
+You are the orchestrator for **{{PROJECT}}**. You do not write product code —
+**Hard boundaries** below names the exact acts that are out (checkout / commit /
+push inside a worker's worktree; inventing a commit identity) and the one that
+is in (`gh pr update-branch` for a green PR that fell behind). You keep the
+queue moving, and you are the first responder when a worker gets stuck.
 
 You are prompted on a timer. Each tick: do the three duties below, then stop.
 
@@ -225,8 +227,12 @@ The protocol, in order:
      big for that, send the one-sentence version of each change and say the
      full text lands in the file on yes — the diff stays in your transcript for
      anyone who wants it verbatim.
-3. **On yes, apply it** by editing this file yourself. On no, or on no answer at
-   all, drop it and do not re-ask that amendment.
+3. **On yes, apply it** by editing this file yourself. **On explicit no, drop
+   it** forever and do not re-ask that amendment. **On cancel, timeout, or no
+   answer**, park it — that means "not now", not "never": mention it once in the
+   next report as `pending amendment: <one-liner> — say 'apply it' or 'drop it'`,
+   never re-open the yes/no dialog, and drop it if still unanswered after 7 days.
+   A cancelled dialog is not a permanent rejection.
 4. **Log it.** Append one line to **Amendments** at the bottom of this file: the
    date, what triggered it, a one-sentence summary.
 5. **Offer general fixes upstream.** Ask one question of the amendment you just

package/src/daemon.ts

@@ -11,7 +11,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { configPath, findProject, loadConfig, resolveCaps, stateDir } from "./config.ts";
-import { createEscalator } from "./escalate.ts";
+import { createEscalator, escalationIssueRef } from "./escalate.ts";
 import { graphHint } from "./graph.ts";
 import { livingDaemon } from "./lifecycle.ts";
 import { STALL_MARKER_FILE } from "./orchestrator-tick.ts";
@@ -369,7 +369,7 @@ async function safeEscalate(d: Pick<Deps, "escalate">, e: Escalation): Promise<b
     await d.escalate(e);
     return true;
   } catch (err) {
-    log(`escalation for #${e.issue} could not be delivered: ${errText(err)}`);
+    log(`escalation for ${escalationIssueRef(e.issue)} could not be delivered: ${errText(err)}`);
     return false;
   }
 }
@@ -393,13 +393,22 @@ export function salvageLines(outcome: SalvageOutcome, worktree: string): string[
     ];
   }
 
-  return [
+  const where =
     `WIP committed to ${outcome.branch} @ ${outcome.sha}` +
-      (outcome.pushed
-        ? " and pushed — the work outlives this worktree"
-        : ` but NOT pushed (${outcome.pushError ?? "no reason given"}) — it lives only in this host's mirror`),
-    kept,
-  ];
+    (outcome.pushed
+      ? " and pushed — the work outlives this worktree"
+      : ` but NOT pushed (${outcome.pushError ?? "no reason given"}) — it lives only in this host's mirror`);
+  // Manifest belongs in the escalation too: opening the commit is how the
+  // orchestrator talked itself into scrubbing a worker tree (#38).
+  const n = outcome.files.length;
+  const count = `${n} file${n === 1 ? "" : "s"}`;
+  const manifest =
+    outcome.newPaths.length === 0
+      ? `${count} (all modifications to tracked paths)`
+      : `${count}; new: ${outcome.newPaths.slice(0, 12).join(", ")}${
+          outcome.newPaths.length > 12 ? `, … +${outcome.newPaths.length - 12} more` : ""
+        }`;
+  return [where, manifest, kept];
 }
 
 /**

package/src/escalate.ts

@@ -45,11 +45,21 @@ export interface Escalator {
  * send, turning a cosmetic problem into a lost escalation. Plain text is also
  * valid Markdown, so the same string renders fine as an issue comment.
  */
+/**
+ * Fleet-scoped pages (integrity tripwire, spend-cap halt, stall) use issue `0`
+ * as a sentinel — there is no tracker issue. Rendering that as `#0` made
+ * Telegram pages and daemon logs look like a bug (#52). Keep the sentinel in
+ * the typed field; only the human-facing label changes here.
+ */
+export function escalationIssueRef(issue: number): string {
+  return issue === 0 ? "fleet" : `#${issue}`;
+}
+
 export function formatEscalation(e: Escalation, project: string): string {
   const lines = [
     `omp-conductor · tier ${e.tier} escalation`,
     `project: ${project}`,
-    `issue: #${e.issue}`,
+    `issue: ${escalationIssueRef(e.issue)}`,
     `summary: ${e.summary}`,
   ];
   if (e.detail) lines.push(`detail: ${e.detail}`);
@@ -99,18 +109,21 @@ export function createEscalator(
           const onTurnFailed = async (cause: unknown): Promise<void> => {
             if (!p.escalation.fallbackToIssueComment) {
               warn(
-                `tier 1 escalation on issue #${e.issue} was accepted by the orchestrator but its ` +
+                `tier 1 escalation on ${escalationIssueRef(e.issue)} was accepted by the orchestrator but its ` +
                   `turn failed (${errText(cause)}), and no fallback is configured — left unmarked ` +
                   `so the next tick retries`,
               );
               return;
             }
             try {
+              if (e.issue === 0) {
+                throw new Error("fleet-scoped escalation has no issue to comment on");
+              }
               await tracker.comment(e.issue, text);
               store.markNotified(key);
             } catch (err) {
               warn(
-                `tier 1 escalation on issue #${e.issue} failed after acceptance ` +
+                `tier 1 escalation on ${escalationIssueRef(e.issue)} failed after acceptance ` +
                   `(${errText(cause)}) and its issue-comment fallback failed too ` +
                   `(${errText(err)}) — left unmarked so the next tick retries`,
               );
@@ -154,10 +167,19 @@ export function createEscalator(
       if (!p.escalation.fallbackToIssueComment) {
         throw new Error(
           `no escalation transport configured for project "${p.name}": tier ${e.tier} ` +
-            `escalation on issue #${e.issue} (${e.summary}) could not be delivered — ` +
+            `escalation on ${escalationIssueRef(e.issue)} (${e.summary}) could not be delivered — ` +
             `set escalation.telegramChatId or escalation.fallbackToIssueComment`,
         );
       }
+      // Fleet pages (issue 0) have nowhere to comment. Falling through here used
+      // to call `issues/0/comments` and surface as a confusing "#0" delivery
+      // failure after Telegram had already been tried (#52).
+      if (e.issue === 0) {
+        throw new Error(
+          `fleet-scoped tier ${e.tier} escalation (${e.summary}) has no issue to comment on — ` +
+            `configure escalation.telegramChatId so integrity/spend/stall pages can reach an operator`,
+        );
+      }
       await tracker.comment(e.issue, text);
       store.markNotified(key);
     },

package/src/orchestrator-tick.ts

@@ -94,6 +94,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.
@@ -834,6 +842,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 {
   /**
@@ -900,6 +925,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 +1035,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 +1048,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/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() ||