omp-conductor 0.16.0 → 0.16.2

package/src/doctor.ts

@@ -35,7 +35,7 @@ import {
 } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, sep } from "node:path";
 import type { Stats } from "node:fs";
 import { Database } from "bun:sqlite";
 import { stringify } from "yaml";
@@ -54,9 +54,17 @@ import {
   DEFAULT_HERDR_UNIT,
   probeTelegramHealth,
   resolveHerdrSessionWithBridge,
+  sessionsRoot,
+  sessionDirForCwd,
   telegramStateDir,
 } from "./fleet.ts";
 import type { TelegramHealth } from "./status-render.ts";
+import {
+  claimForProject,
+  claimedTelegramTopics,
+  telegramTopicsTidy,
+  type ClaimedTopic,
+} from "./escalate.ts";
 import {
   herdrConductorPluginConfigDir,
   planHostRuntime,
@@ -204,6 +212,10 @@ export interface DoctorDeps {
   herdrConfig?: () => string | undefined;
   /** The live herdr-conductor plugin `config.env`, or undefined. */
   herdrEnv?: () => string | undefined;
+  /** Live omp-telegram topic claims (threads.json), for the #600 probes. */
+  claimedTopics?: () => ClaimedTopic[];
+  /** Whether the bridge's access.json runs per-session topic tidy on. */
+  topicsTidy?: () => boolean;
   /** The fleet agent name the tick config of one project names, or undefined
    *  when there is no (readable) tick — the expected live herdr pane identity. */
   tickAgentName?: (project: ProjectConfig) => string | undefined;
@@ -1068,6 +1080,103 @@ function herdrAgentNameProbe(probes: Probes, p: ProjectConfig): Finding {
   );
 }
 
+/**
+ * #600 check — the orchestrator's claimed session file vs the directory arm
+ * scans.
+ *
+ * A pane resumed from a session created elsewhere keeps the original transcript
+ * path (herdr pins the pane to it), so the claimed file can live outside the
+ * session directory the tick cwd implies. arm follows the claim, so the
+ * mismatch alone is handled — but it is exactly the shape of host that once
+ * made arming silently impossible, and an operator reading transcript paths
+ * should not have to rediscover it. A claimed file *outside the session tree*
+ * is worse: arm refuses to arm there (the reply could never be seen), so
+ * doctor fails rather than letting the fleet sit disarmed.
+ */
+function armSessionDirProbe(probes: Probes, p: ProjectConfig): Finding {
+  const claims = probes.claimedTopics();
+  if (claims.length === 0) {
+    return passFinding(
+      "arm-session-dir",
+      `[${p.name}] no live omp-telegram claim — arm scans the tick-cwd session directory`,
+    );
+  }
+  const claim = claimForProject(claims, p.name);
+  if (claim === undefined || claim.sessionFile === undefined) {
+    return passFinding(
+      "arm-session-dir",
+      `[${p.name}] the live claim names no session file — arm scans the tick-cwd session directory`,
+    );
+  }
+  const root = sessionsRoot();
+  const claimDir = dirname(claim.sessionFile);
+  const scanDir = sessionDirForCwd(tickCwdForProject(p));
+  if (claimDir !== root && !claimDir.startsWith(join(root, sep))) {
+    return failFinding(
+      "arm-session-dir",
+      `[${p.name}] the orchestrator's claimed session file ${claim.sessionFile} is outside the session tree arm scans (${root}) — ` +
+        `arm cannot arm while the reply can only land there`,
+      `start the orchestrator pane's session under ${root}, or from the tick cwd ${scanDir}`,
+    );
+  }
+  if (claimDir !== scanDir) {
+    return warnFinding(
+      "arm-session-dir",
+      `[${p.name}] the orchestrator's claimed session file ${claim.sessionFile} lives in ${claimDir}, not the tick-cwd session directory ${scanDir} — ` +
+        `arm follows the claim, so arming works, but this is the resumed-pane shape #600 names`,
+      `optional tidy-up: start the pane's session from the tick cwd so transcript and cwd agree again`,
+    );
+  }
+  return passFinding(
+    "arm-session-dir",
+    `[${p.name}] the orchestrator's claimed session file is inside the session directory arm scans`,
+  );
+}
+
+/**
+ * #600 check — a pinned escalation.telegramTopicId that no live claim carries.
+ *
+ * The wizard pins from the claims at setup time, but the bridge re-claims
+ * topics across restarts and conductor restarts the service itself (#407), so
+ * the pin drifts. On a host with `topicsTidy` on it drifts *structurally*:
+ * every pane exit closes the topic, so a pinned id can never be live again.
+ * There the pin is vestigial — reporting a dead id as the live destination is
+ * the exact false belief this check exists to remove.
+ */
+function topicPinProbe(probes: Probes, p: ProjectConfig): Finding {
+  const pinned = p.escalation.telegramTopicId;
+  if (pinned === undefined) {
+    return passFinding(
+      "topic-pin",
+      `[${p.name}] no pinned topic id — sends follow the live claim or the flat chat`,
+    );
+  }
+  const claims = probes.claimedTopics();
+  if (claims.length === 0) {
+    return passFinding(
+      "topic-pin",
+      `[${p.name}] pinned topic ${pinned} — no live claims to compare (bridge state unreadable, or not a forum host)`,
+    );
+  }
+  if (claims.some((claim) => claim.threadId === pinned)) {
+    return passFinding("topic-pin", `[${p.name}] pinned topic ${pinned} is a live claim`);
+  }
+  if (probes.topicsTidy()) {
+    return warnFinding(
+      "topic-pin",
+      `[${p.name}] pinned topic ${pinned} is not among omp-telegram's live claims, and this host runs topicsTidy — ` +
+        `the pin is vestigial and can never be live again (every pane exit closes its topic)`,
+      `remove escalation.telegramTopicId from ${p.name}'s config (sends already follow the live claim), or turn topicsTidy off`,
+    );
+  }
+  return warnFinding(
+    "topic-pin",
+    `[${p.name}] pinned topic ${pinned} is not among omp-telegram's live claims (${claims.map((c) => c.threadId).join(", ")}) — ` +
+      `sends fall back to the live claim or the flat chat`,
+    `update or remove escalation.telegramTopicId in ${p.name}'s config`,
+  );
+}
+
 /**
  * #541 check 2 — `[session] resume_agents_on_restore` on the live herdr config.
  *
@@ -1260,6 +1369,12 @@ export async function runDoctor(projectName: string | undefined, opts: DoctorDep
     findings.push(
       passFinding("herdr-agent-name", projectProblem === undefined ? "no project resolved — nothing to check" : `agent name uncheckable: ${projectProblem}`),
     );
+    findings.push(
+      passFinding("arm-session-dir", projectProblem === undefined ? "no project resolved — nothing to check" : `arm session dir uncheckable: ${projectProblem}`),
+    );
+    findings.push(
+      passFinding("topic-pin", projectProblem === undefined ? "no project resolved — nothing to check" : `topic pin uncheckable: ${projectProblem}`),
+    );
     findings.push(
       passFinding("omp-settings", projectProblem === undefined ? "no project resolved — nothing to check" : `omp settings overlay uncheckable: ${projectProblem}`),
     );
@@ -1267,6 +1382,8 @@ export async function runDoctor(projectName: string | undefined, opts: DoctorDep
     for (const p of projects) {
       findings.push(await labelProbe(probes, p));
       findings.push(herdrAgentNameProbe(probes, p));
+      findings.push(armSessionDirProbe(probes, p));
+      findings.push(topicPinProbe(probes, p));
       findings.push(ompSettingsProbe(p, sessionRootState));
     }
   }
@@ -1331,6 +1448,8 @@ export function defaultProbes(): Probes {
     herdrSession: () => resolveHerdrSessionWithBridge(),
     herdrConfig: defaultHerdrConfig,
     herdrEnv: defaultHerdrEnv,
+    claimedTopics: () => claimedTelegramTopics(),
+    topicsTidy: () => telegramTopicsTidy(),
     tickAgentName: (p) => {
       const tick = readTickConfig(tickCwdForProject(p));
       if (tick.kind !== "ok") return undefined;

package/src/escalate.ts

@@ -436,6 +436,13 @@ export interface ClaimedTopic {
   name: string;
   /** The herdr space the claiming pane sits in, when the bridge captured one. */
   workspaceLabel?: string;
+  /**
+   * The transcript the claiming pane actually writes, when the bridge captured
+   * one. This is the *live* session file — herdr pins a restored pane to it
+   * (`omp --resume=<that path>`) — so it can sit in a different session
+   * directory than the pane's cwd implies (#600).
+   */
+  sessionFile?: string;
 }
 
 /**
@@ -470,17 +477,47 @@ export function resolveProjectTopicId(project: ProjectConfig): number | undefine
   const claims = claimedTelegramTopics();
   if (claims.length === 0) return pinned;
   if (claims.some((claim) => claim.threadId === pinned)) return pinned;
-  const bySpace = soleClaim(claims, (claim) => claim.workspaceLabel === project.name);
-  const match = bySpace ?? soleClaim(claims, (claim) => claim.name === project.name);
+  const match = claimForProject(claims, project.name);
   if (match === undefined) return pinned;
   warn(
     `escalation.telegramTopicId for ${project.name} is no longer a claimed topic; ` +
       `following omp-telegram's current "${project.name}" ` +
-      `${bySpace === undefined ? "claim" : "herdr space claim"} instead`,
+      `${match.workspaceLabel === project.name ? "herdr space claim" : "claim"} instead`,
   );
   return match.threadId;
 }
 
+/**
+ * The one claim answering to a project's identity — herdr space first, title
+ * second — or nothing when none or several do (#412).
+ */
+export function claimForProject(
+  claims: readonly ClaimedTopic[],
+  projectName: string,
+): ClaimedTopic | undefined {
+  const bySpace = soleClaim(claims, (claim) => claim.workspaceLabel === projectName);
+  return bySpace ?? soleClaim(claims, (claim) => claim.name === projectName);
+}
+
+/**
+ * The transcript this project's live omp-telegram claim names — where the
+ * orchestrator pane's reply actually lands.
+ *
+ * `arm` derives its scan directory from the tick cwd, but a pane resumed from
+ * a session created elsewhere keeps the original transcript path (herdr pins
+ * the pane to it), so the cwd-derived directory is the one place the reply is
+ * guaranteed *not* to be (#600). The claim's `sessionFile` is the live answer;
+ * identity resolves exactly as {@link resolveProjectTopicId}'s substitution
+ * does, via {@link claimForProject}. Absent when the bridge has no claim or
+ * the claim names no file — the caller then falls back to the cwd-derived
+ * directory, which is the honest answer for a host that predates claims.
+ */
+export function resolveClaimedSessionFile(project: ProjectConfig): string | undefined {
+  const claims = claimedTelegramTopics();
+  if (claims.length === 0) return undefined;
+  return claimForProject(claims, project.name)?.sessionFile;
+}
+
 /**
  * The one claim answering to `predicate`, or nothing when none or several do.
  *
@@ -523,6 +560,7 @@ export function claimedTelegramTopics(stateDir?: string): ClaimedTopic[] {
     if (!Number.isFinite(threadId) || !Number.isSafeInteger(threadId)) continue;
     let name = id;
     let workspaceLabel: string | undefined;
+    let sessionFile: string | undefined;
     if (typeof entry === "object" && entry !== null) {
       if ("name" in entry) {
         const candidate = entry.name;
@@ -532,12 +570,47 @@ export function claimedTelegramTopics(stateDir?: string): ClaimedTopic[] {
         const candidate = entry.workspaceLabel;
         if (typeof candidate === "string" && candidate.trim() !== "") workspaceLabel = candidate.trim();
       }
+      if ("sessionFile" in entry) {
+        const candidate = entry.sessionFile;
+        if (typeof candidate === "string" && candidate.trim() !== "") sessionFile = candidate.trim();
+      }
     }
-    out.push(workspaceLabel === undefined ? { threadId, name } : { threadId, name, workspaceLabel });
+    out.push(
+      workspaceLabel === undefined && sessionFile === undefined
+        ? { threadId, name }
+        : workspaceLabel === undefined
+          ? { threadId, name, sessionFile }
+          : sessionFile === undefined
+            ? { threadId, name, workspaceLabel }
+            : { threadId, name, workspaceLabel, sessionFile },
+    );
   }
   return out;
 }
 
+/**
+ * Whether the paired bridge runs with per-session topic tidy on (access.json
+ * `topicsTidy: true` — `/telegram topics tidy on`).
+ *
+ * On a tidy host every pane exit closes (forum) or deletes (DM) its own topic,
+ * so a pinned `escalation.telegramTopicId` is structurally stale: it can never
+ * be among the live claims again, and treating it as a live pin is the false
+ * belief #600 names. The bridge's own setting is read here so `doctor` can say
+ * "vestigial" rather than "moved once".
+ */
+export function telegramTopicsTidy(stateDirPath?: string): boolean {
+  const override = stateDirPath?.trim() ?? process.env.OMP_TELEGRAM_STATE_DIR?.trim();
+  const dir = override ? override : join(homedir(), ".omp", "agent", "telegram");
+  try {
+    const parsed = JSON.parse(readFileSync(join(dir, "access.json"), "utf8")) as {
+      readonly topicsTidy?: unknown;
+    };
+    return parsed.topicsTidy === true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * The one Telegram send in this package. Exported so the report outbox (#123)
  * reuses it rather than forking it: the response handling below is load-bearing

package/src/fleet.ts

@@ -26,10 +26,10 @@ import {
 } from "node:fs";
 import { createInterface } from "node:readline";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, sep } from "node:path";
 import { findProject, loadConfig, stateDir } from "./config.ts";
 import { clearArmChallenge, recordArmChallenge } from "./arm-challenge.ts";
-import { resolveProjectTopicId, sendTelegram } from "./escalate.ts";
+import { resolveClaimedSessionFile, resolveProjectTopicId, sendTelegram } from "./escalate.ts";
 import { readPlanUsage, sharedUsageSource } from "./usage.ts";
 import { readApprovalSurface, readDaemonProfile } from "./approval-surface.ts";
 import { inspectBriefLayout } from "./brief-upgrade.ts";
@@ -287,13 +287,22 @@ export interface ArmResult {
 export interface ArmDeps {
   sendChallenge?: (token: string, owner: string, text: string, topicId?: number) => Promise<void>;
   /**
-   * Waits for the challenge to appear as a user turn somewhere under the
-   * session directory. The waiter owns transcript discovery — not the caller —
+   * The orchestrator session file the live omp-telegram claim names for this
+   * project, or undefined when there is no (readable) claim. The default
+   * resolves the claim the same way the send does; tests inject a fixture.
+   * Absent → arm watches the cwd-derived session directory, the pre-claim
+   * behaviour.
+   */
+  claimedSessionFile?: () => string | undefined;
+  /**
+   * Waits for the challenge to appear as a user turn somewhere under the scan
+   * directories. The waiter owns transcript discovery — not the caller —
    * because the reply may land in a session that starts *after* the send, so a
    * path resolved before the challenge went out can be the wrong file by the
-   * time the operator answers (#142).
+   * time the operator answers (#142), and because the claimed session file can
+   * sit in a different directory than the tick cwd implies (#600).
    */
-  waitForUserTurn?: (dir: string, code: string, sentAt: number, timeoutMs: number) => Promise<boolean>;
+  waitForUserTurn?: (dirs: readonly string[], code: string, sentAt: number, timeoutMs: number) => Promise<boolean>;
   now?: () => number;
   sleep?: (ms: number) => Promise<void>;
   timeoutMs?: number;
@@ -332,10 +341,23 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
     );
   }
 
-  const dir = sessionDirForCwd(tick.cwd);
-  if (!existsSync(dir)) {
+  // One bot, one chat, and — once a host runs more than one fleet — more than
+  // one pane that can ask. The challenge names which one, or the operator is
+  // answering a question they cannot attribute.
+  const named = tick.config.project ?? projectName;
+
+  // Resolve the orchestrator's live session file *before* the challenge goes
+  // out — the same claim the send follows (#600). A pane resumed from a
+  // session created elsewhere (herdr pins it to the original transcript)
+  // writes a session file outside the directory the tick cwd implies, and a
+  // cwd-derived scan would poll the one place the reply is guaranteed not to
+  // be. A claim outside the session tree arm scans can never be answered, so
+  // that is a stop, not five minutes of polling.
+  const claimed = deps.claimedSessionFile !== undefined ? deps.claimedSessionFile() : claimedOrchestratorSessionFile(named);
+  const dirs = armSessionScanDirs(tick.cwd, claimed);
+  if (dirs.every((d) => !existsSync(d))) {
     throw new Error(
-      `no orchestrator session directory at ${dir} — ` +
+      `no orchestrator session directory under ${dirs.join(" or ")} — ` +
         `the inbound proof is read from a user turn in a transcript there. Start the pane orchestrator, let it settle, then arm again`,
     );
   }
@@ -347,10 +369,6 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
   const arm = resolveArmState(path, tick.config.project ?? projectName);
   const alreadyArmed = arm.armed;
   const code = makeChallengeCode();
-  // One bot, one chat, and — once a host runs more than one fleet — more than
-  // one pane that can ask. The challenge names which one, or the operator is
-  // answering a question they cannot attribute.
-  const named = tick.config.project ?? projectName;
   const text =
     `Fleet arming check${named === undefined ? "" : ` — project ${named}`}. ` +
     `Reply to this chat with exactly:\n${code}\n` +
@@ -391,25 +409,37 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
 
   const injected = deps.waitForUserTurn;
   const scan: SessionScan = injected
-    ? { seen: await injected(dir, code, sentAt, timeoutMs), scanned: [], ignored: [] }
-    : await waitForChallengeInSessions(dir, code, sentAt, timeoutMs, deps);
+    ? { seen: await injected(dirs, code, sentAt, timeoutMs), scanned: [], ignored: [] }
+    : await waitForChallengeInSessions(dirs, code, sentAt, timeoutMs, deps);
   if (!scan.seen) {
     // The proof missed its window: a lookalike reply must not stay classifiable
     // after arming gave up, so the record is cleared before the failure lands.
     clearArmChallenge(named);
+    // The claimed session file is named before the bridge/token/chat block: a
+    // rotation under the window is visible from this error alone, and on the
+    // host this guard exists for the claimed file is the one that held the
+    // answer (#600).
     const listing = [
-      `session dir: ${dir}`,
+      ...(claimed === undefined
+        ? []
+        : [
+            `claimed orchestrator session file: ${claimed}` +
+              (dirs.includes(dirname(claimed))
+                ? " (watched)"
+                : ` (NOT under any watched dir — a reply there can never be seen)`),
+          ]),
+      `session dir: ${dirs.join(", ")}`,
       ...scan.scanned.map((f) => `  watched: ${f}`),
       ...scan.ignored.map((f) => `  ignored (stale, last written before the challenge): ${f}`),
     ].join("\n");
     throw new Error(
       `arm: the challenge never arrived as a user turn in time — NOT armed.\n` +
-        `Inbound Telegram is not reaching the omp session. Check, in order:\n` +
+        listing +
+        `\nInbound Telegram is not reaching the omp session. Check, in order:\n` +
         `  * is the bridge polling?      attach and run: /telegram status\n` +
         `  * is another process holding this bot token? Telegram allows exactly one\n` +
         `    getUpdates consumer and rejects the second with HTTP 409.\n` +
-        `  * did you reply in the DM with the bot, not another chat?\n` +
-        listing,
+        `  * did you reply in the DM with the bot, not another chat?\n`,
     );
   }
 
@@ -1605,6 +1635,56 @@ export function sessionDirForCwd(cwd: string): string {
   return join(home, ".omp", "agent", "sessions", slug.replaceAll("/", "-"));
 }
 
+/** The session tree arm scans: every transcript under it, whatever the cwd slug. */
+export function sessionsRoot(): string {
+  return join(homedir(), ".omp", "agent", "sessions");
+}
+
+/**
+ * The orchestrator session file omp-telegram's live claim names for this
+ * project — the transcript a resumed/restored pane actually writes, which can
+ * live in a different session directory than the tick cwd implies (#600).
+ * Never throws: no claim, or an unreadable config, means undefined and arm
+ * falls back to the cwd-derived directory.
+ */
+function claimedOrchestratorSessionFile(named: string | undefined): string | undefined {
+  if (named === undefined) return undefined;
+  try {
+    return resolveClaimedSessionFile(findProject(loadConfig(), named));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The session directories `arm` watches for the reply — the cwd-derived one
+ * plus, when the live claim's file lives elsewhere, that file's directory.
+ *
+ * The cwd-derived directory is where a *fresh* session started from the tick
+ * cwd writes; the claimed file's directory is where the *restored* pane keeps
+ * writing (herdr pins it to the original transcript). Watching both covers a
+ * resumed session, a rotated one, and a session that starts after the send.
+ *
+ * A claim outside the session tree is a stop, not a slower failure: arm polls
+ * only transcripts under {@link sessionsRoot}, so a claimed file elsewhere can
+ * never satisfy the challenge, and five minutes of polling cannot discover a
+ * file that is not in the search set. The throw names both paths.
+ */
+function armSessionScanDirs(cwd: string, claimed: string | undefined): string[] {
+  const cwdDir = sessionDirForCwd(cwd);
+  if (claimed === undefined) return [cwdDir];
+  const root = sessionsRoot();
+  const claimDir = dirname(claimed);
+  if (claimDir !== root && !claimDir.startsWith(join(root, sep))) {
+    throw new Error(
+      `arm: the orchestrator's claimed session file ${claimed} is outside the session tree arm scans (${root}) — ` +
+        `no transcript there can satisfy the challenge. Resume the pane under ${root}, or start it from ${cwd}; ` +
+        `arm would otherwise poll ${cwdDir} until the timer runs out`,
+    );
+  }
+  return claimDir === cwdDir ? [cwdDir] : [cwdDir, claimDir];
+}
+
 function makeChallengeCode(): string {
   const bytes = new Uint8Array(4);
   crypto.getRandomValues(bytes);
@@ -1631,20 +1711,23 @@ interface SessionScan {
 }
 
 /**
- * Polls the session directory — re-read on every pass, never snapshotted —
+ * Polls the session directories — re-read on every pass, never snapshotted —
  * until the challenge shows up as a user turn or the deadline passes.
  *
  * Discovery lives here because the reply can land in a transcript that does not
  * exist yet when the challenge is sent: a rotated session, or the first one of
- * a pane started right after arming (#142). A waiter handed one path polls a
- * file the answer will never be written to, and arming becomes impossible.
+ * a pane started right after arming (#142). And the scan set can be two
+ * directories when the live claim's session file lives outside the tick-cwd
+ * directory: the restored pane keeps writing the claimed file, so its
+ * directory is watched alongside the cwd-derived one (#600).
  *
  * Files untouched since just before the send are named, not parsed: an append
  * bumps mtime, so a transcript older than the challenge cannot hold the reply,
- * and skipping it keeps a large stale session out of every 5 s pass.
+ * and skipping it keeps a large stale session out of every 5 s pass. A missing
+ * directory is not an error — it can vanish under a rotation and reappear.
  */
 async function waitForChallengeInSessions(
-  dir: string,
+  dirs: readonly string[],
   code: string,
   sentAt: number,
   timeoutMs: number,
@@ -1656,28 +1739,30 @@ async function waitForChallengeInSessions(
   for (;;) {
     const scanned: string[] = [];
     const ignored: string[] = [];
-    let names: string[] = [];
-    try {
-      names = readdirSync(dir);
-    } catch {
-      /* the directory can go away under a rotation; the next pass re-reads it */
-    }
-    for (const name of names.sort()) {
-      if (!name.endsWith(".jsonl")) continue;
-      const path = join(dir, name);
-      let mtimeMs: number;
+    for (const dir of dirs) {
+      let names: string[] = [];
       try {
-        mtimeMs = statSync(path).mtimeMs;
+        names = readdirSync(dir);
       } catch {
-        continue; /* race */
+        /* the directory can go away under a rotation; the next pass re-reads it */
       }
-      const label = `${name} (mtime ${new Date(mtimeMs).toISOString()})`;
-      if (mtimeMs < sentAt - 1_000) {
-        ignored.push(label);
-        continue;
+      for (const name of names.sort()) {
+        if (!name.endsWith(".jsonl")) continue;
+        const path = join(dir, name);
+        let mtimeMs: number;
+        try {
+          mtimeMs = statSync(path).mtimeMs;
+        } catch {
+          continue; /* race */
+        }
+        const label = `${name} (mtime ${new Date(mtimeMs).toISOString()})`;
+        if (mtimeMs < sentAt - 1_000) {
+          ignored.push(label);
+          continue;
+        }
+        scanned.push(label);
+        if (await transcriptHasUserCode(path, code)) return { seen: true, scanned, ignored };
       }
-      scanned.push(label);
-      if (await transcriptHasUserCode(path, code)) return { seen: true, scanned, ignored };
     }
     if (now() >= deadline) return { seen: false, scanned, ignored };
     await sleep(5_000);

package/src/setup-host.ts

@@ -211,6 +211,14 @@ export interface HostRuntimePlan {
    * the installed unit matched.
    */
   installedAction: PlannedWrite<string>["action"];
+  /**
+   * The installed destinations whose live bytes differ from this version's
+   * render — exactly the files the privileged steps would rewrite. `upgrade`
+   * names them after a release that re-rendered a template, and
+   * {@link currentInstall} is `true` iff this list is empty, so the two can
+   * never disagree (#598).
+   */
+  drift: readonly string[];
   /**
    * True when every file the privileged install steps would write is already
    * at its destination with the current bytes. `runHostInstall` uses it to
@@ -1285,18 +1293,27 @@ export function planHostRuntime(
   // nothing to restart. The herdr unit is absent on a host without herdr, and
   // an absent unit that would not be provisioned is nothing to do.
   const installedAction = actionFor(installedPath, serviceContent);
+  // The same comparison as a destination list, so `upgrade` can name the
+  // drifted files and `currentInstall` can never disagree with that list: a
+  // plan is current exactly when no installed destination differs from the
+  // render.
+  const drift: string[] = [];
+  const noteDrift = (path: string, content: string | undefined): void => {
+    if (content !== undefined && actionFor(path, content) !== "keep") drift.push(path);
+  };
+  noteDrift(installedPath, serviceContent);
+  noteDrift(join(unitDir, RECOVER_SERVICE_NAME), recoverUnitContent);
+  noteDrift(recoverScriptInstallPath, recoverScriptContent);
+  if (herdrUnit !== undefined) noteDrift(installedHerdr, herdrUnit.content);
+  // The pane-shell file is a destination like the units: a plan with all
+  // units current but the config merge still pending must not report
+  // "nothing to install" and skip the very write it exists to make.
+  if (herdrConfig !== undefined) noteDrift(herdrConfigPath, herdrConfig.content);
+  // Same for the herdr-conductor config.env: a pending env merge is pending
+  // work, not an already-current install.
+  if (herdrEnv !== undefined) noteDrift(herdrEnvTarget, herdrEnv.content);
   const currentInstall =
-    installedAction === "keep" &&
-    actionFor(join(unitDir, RECOVER_SERVICE_NAME), recoverUnitContent) === "keep" &&
-    actionFor(recoverScriptInstallPath, recoverScriptContent) === "keep" &&
-    (herdrUnit === undefined || actionFor(installedHerdr, herdrUnit.content) === "keep") &&
-    // The pane-shell file is a destination like the units: a re-run with all
-    // units current but the config merge still pending must not report
-    // "nothing to install" and skip the very write the plan exists to make.
-    (herdrConfig === undefined || actionFor(herdrConfigPath, herdrConfig.content) === "keep") &&
-    // Same for the herdr-conductor config.env: pending env merge is pending
-    // work, not an already-current install.
-    (herdrEnv === undefined || actionFor(herdrEnvTarget, herdrEnv.content) === "keep");
+    drift.length === 0;
   return {
     service,
     // The herdr unit and pane-shell config stand and fall together: no herdr, no
@@ -1349,6 +1366,7 @@ export function planHostRuntime(
     cliSource: runtime.cli === undefined ? "plugin" : "global",
     installedPath,
     installedAction,
+    drift,
     currentInstall,
   };
 }