omp-conductor 0.18.0 → 0.18.1

package/src/dashboard/app.js

@@ -35,6 +35,7 @@ const STATE_TEXT = {
   ok: "daemon up",
   stopped: "daemon down",
   unreachable: "daemon down — not answering /healthz",
+  unresponsive: "daemon up — healthz timed out",
   "other-project": "daemon down — serves another project",
 };
 
@@ -239,7 +240,9 @@ async function openProject(name) {
     projectDaemon.textContent = daemonLine(row);
     projectDaemon.classList.toggle(
       "state-degraded",
-      row.daemon.state === "unreachable" || row.daemon.state === "other-project",
+      row.daemon.state === "unreachable" ||
+        row.daemon.state === "unresponsive" ||
+        row.daemon.state === "other-project",
     );
   }
   await refreshProject("board");

package/src/dashboard/server.ts

@@ -114,7 +114,7 @@ export interface DashboardProjectView {
   repo: string;
   daemon: {
     /** The shared verdict every viewer uses (#379). */
-    state: "ok" | "stopped" | "unreachable" | "other-project";
+    state: "ok" | "stopped" | "unreachable" | "unresponsive" | "other-project";
     /** The living daemon's port when a record exists; null when there is none. */
     port: number | null;
     /** The raw `/healthz` body, parsed, when this project's daemon answered it. */
@@ -210,7 +210,10 @@ export async function fleetOverview(): Promise<FleetOverviewRow[]> {
       liveWorkers: snap.liveWorkers,
       spendTodayUsd: snap.spendTodayUsd,
       baseHealth: snap.baseHealth,
-      degraded: view.daemon.state === "unreachable" || view.daemon.state === "other-project",
+      degraded:
+        view.daemon.state === "unreachable" ||
+        view.daemon.state === "unresponsive" ||
+        view.daemon.state === "other-project",
     };
   });
 }

package/src/decisions.ts

@@ -12,13 +12,14 @@
  * open row is rendered into a tick prompt.
  */
 
-import type { DecisionRecord, Store, Tracker } from "./types.ts";
+import type { DecisionRecord, RunRecord, Store, Tracker } from "./types.ts";
+import { shellQuote } from "./shell.ts";
 import { fetchRateLimit, RATE_LIMIT_COOLDOWN_MS } from "./tracker/github.ts";
 
 /**
  * A precondition whose truth this package can check on its own.
  *
- * Exactly six kinds, deliberately. Each one is a question the tracker or npm
+ * Exactly seven kinds, deliberately. Each one is a question the tracker or npm
  * already answers, so the row moves from "parked" to "act on this" without a
  * human re-reading it. Anything richer — a label appearing, a workflow going
  * green — is a follow-on issue rather than a grammar nobody validated.
@@ -28,6 +29,7 @@ export type DecisionCondition =
   | { kind: "issue-closed"; issue: number }
   | { kind: "npm-version"; spec: string }
   | { kind: "pr-checks-green"; url: string }
+  | { kind: "pr-review-ready"; url: string }
   | { kind: "pr-mergeable"; url: string }
   | { kind: "rate-limit-reset" };
 
@@ -42,6 +44,64 @@ const NPM_SPEC = /^(@[^/@\s]+\/)?[^@\s]+@[^\s]+$/;
  */
 const GREEN_CHECK_STATES: Record<string, true> = { success: true, neutral: true };
 
+/**
+ * The run states a review revision may start from (#795) — the single
+ * definition shared by `conductor_pr_review` and the `pr-review-ready` watch,
+ * so the verb's gate and the condition can never name different sets.
+ *
+ * A revision round resumes the exact run whose row owns the PR, so the
+ * revisable states are exactly the terminal runs that pushed one: a settled
+ * `pushed-green` row, or a `failed` / `killed` row — a run that capped or
+ * failed *after* pushing a green PR. The PR is the durable artefact, the
+ * exact-head green verification is the gate on "green at the reviewed SHA",
+ * and a terminal row proves no worker is in flight, so findings are returned
+ * without the close-PR → unblock → continuation dance.
+ *
+ * Closed on purpose: a live row (`running` / `claimed`) is already doing its
+ * own work, a `pushed-pending` PR is not green yet, and a `blocked` /
+ * `orphaned` / `stopped` / `merged` row is not work returned for revision.
+ */
+export const REVISABLE_RUN_STATES: Record<string, true> = {
+  "pushed-green": true,
+  failed: true,
+  killed: true,
+};
+
+/**
+ * How far back a PR's project-owned run may be looked up. PR verbs and the
+ * `pr-review-ready` watch share this bound: a pull request older than it is
+ * not one an orchestrator is mid-flight on.
+ */
+export const PR_LOOKUP_WINDOW_MS = 30 * 24 * 60 * 60_000;
+
+/**
+ * One predicate for "a run-owned pull request can be returned for revision",
+ * read by both `conductor_pr_review` and the `pr-review-ready` watch so they
+ * cannot drift.
+ *
+ * Ownership is the same newest-first resolution the review verb uses: the
+ * newest attempt of this project that recorded the PR within the
+ * recent-history window (`runsForProjectPr`), never the issue's newest row —
+ * a requeued continuation must not hide the PR its predecessor opened
+ * (#434), and a newer live owner hides an older settled one. That older
+ * settled row is exactly the shape dogfood #844 started from: PR #838 was
+ * green while its newest owner was still `running`, and a watch keyed only to
+ * checks woke the orchestrator before `conductor_pr_review` was actionable.
+ *
+ * `no-owner` and `not-revisable` both fail closed: a review can never act, so
+ * a watch must not wake, even when the checks are green.
+ */
+export type PrReviewReadiness =
+  | { kind: "ready"; run: RunRecord }
+  | { kind: "no-owner" }
+  | { kind: "not-revisable"; run: RunRecord };
+
+export function prReviewReadiness(store: Store, project: string, prUrl: string, now: number): PrReviewReadiness {
+  const run = store.runsForProjectPr(project, prUrl, now - PR_LOOKUP_WINDOW_MS)[0];
+  if (run === undefined) return { kind: "no-owner" };
+  return REVISABLE_RUN_STATES[run.state] === true ? { kind: "ready", run } : { kind: "not-revisable", run };
+}
+
 /**
  * Parse a raw condition, or `undefined` when it is not one of the three forms.
  *
@@ -58,7 +118,7 @@ export function parseCondition(raw: string): DecisionCondition | undefined {
   const rest = text.slice(at + 1).trim();
   if (rest.length === 0) return undefined;
 
-  if (kind === "pr-merged" || kind === "pr-checks-green" || kind === "pr-mergeable") {
+  if (kind === "pr-merged" || kind === "pr-checks-green" || kind === "pr-review-ready" || kind === "pr-mergeable") {
     return rest.startsWith("https://") ? { kind, url: rest } : undefined;
   }
   if (kind === "issue-closed") {
@@ -77,12 +137,13 @@ export function parseCondition(raw: string): DecisionCondition | undefined {
   return undefined;
 }
 
-/** The six accepted forms, for a refusal that can be acted on in one turn. */
+/** The seven accepted forms, for a refusal that can be acted on in one turn. */
 export const CONDITION_FORMS = [
   "pr-merged:https://github.com/owner/repo/pull/123",
   "issue-closed:123",
   "npm-version:omp-conductor@0.4.3",
   "pr-checks-green:https://github.com/owner/repo/pull/123",
+  "pr-review-ready:https://github.com/owner/repo/pull/123",
   "pr-mergeable:https://github.com/owner/repo/pull/123",
   "rate-limit-reset:github",
 ] as const;
@@ -154,7 +215,8 @@ export async function probeRateLimitReset(runGh: RateLimitGh = ghRateLimit): Pro
 }
 
 /**
- * Check every open decision that carries a condition and has not met it yet.
+ * Check every open decision that carries a condition; a met row is only
+ * revisited when its condition can stop holding (`pr-checks-green`, #808).
  *
  * Errors are swallowed per row on purpose: this runs fire-and-forget beside a
  * tick, and one deleted PR or one flaky `gh` call must not stop the rest of the
@@ -171,6 +233,16 @@ export async function probeRateLimitReset(runGh: RateLimitGh = ghRateLimit): Pro
  * was waiting and why it stopped survives. Operator questions are untouched:
  * they answer to a human and expire on the seven-day clock.
  *
+ * A met `pr-checks-green` / `pr-review-ready` row is the exception to "met is
+ * final" (#808): both are verdicts *about a commit*, so the met state is bound
+ * to the head it was observed at and re-read here. A head change drops the met
+ * state (and with it the binding) and the row re-evaluates against the live
+ * head — it cannot render `[CONDITION MET]` for a head whose checks are still
+ * running or have gone red. A row met before head binding existed has no
+ * binding to compare and is preserved as met as-is: nothing is guessed for it,
+ * and it is never withdrawn with the never-met reason. Every other condition
+ * is monotone or human-answered and keeps its permanent met transition.
+ *
  * Returns the rows that just became met, so the caller can log what changed
  * rather than a count.
  */
@@ -183,10 +255,53 @@ export async function evaluateDecisionConditions(
 ): Promise<DecisionRecord[]> {
   const met: DecisionRecord[] = [];
   for (const decision of store.openDecisions(project)) {
-    if (decision.condition === undefined || decision.conditionMetAt !== undefined) continue;
+    if (decision.condition === undefined) continue;
     const condition = parseCondition(decision.condition);
     if (condition === undefined) continue;
+    if (decision.conditionMetAt !== undefined) {
+      // A met row is normally final: the digest's "act on this now" is the
+      // whole point, and flapping a verdict would reopen a question the
+      // orchestrator may already be acting on. The two head-bound conditions
+      // — `pr-checks-green` and `pr-review-ready` — are the ones whose
+      // observation can stop holding: they are about a commit, and a PR head
+      // change makes the old verdict stale.
+      if (condition.kind !== "pr-checks-green" && condition.kind !== "pr-review-ready") continue;
+      // A row met before head binding existed has no binding to compare and no
+      // way to prove a head moved. It is preserved as met rather than cleared
+      // and re-verified: a clear would let the settled-PR path below withdraw
+      // it as "before its checks were seen", which the durable ledger itself
+      // contradicts (review round 2, #808). No head is ever guessed for it.
+      if (decision.conditionHead === undefined) continue;
+      let head: string | undefined;
+      try {
+        head = await tracker.prHead(condition.url);
+      } catch {
+        continue;
+      }
+      // An unreadable head is not proof a head changed: flip the row only on a
+      // definitive observation, or it flaps on every flaky `gh` call.
+      if (head === undefined) continue;
+      if (decision.conditionHead === head) {
+        // A stable head is the whole story for `pr-checks-green` — checks are
+        // a verdict about a commit, and the commit did not move. For
+        // `pr-review-ready` it is only half: the row also gates on which run
+        // owns the PR, and a review revision resumes the owner to live
+        // (`running` / `claimed`) without moving the head. So a met
+        // review-ready row falls through to the branch below, whose shared
+        // readiness gate clears it the moment the verb can no longer accept —
+        // the repeated wake this condition exists to prevent (#844 review 1).
+        if (condition.kind === "pr-checks-green") continue;
+      } else {
+        // The head moved — or the row predates head binding — so the old met
+        // observation is no longer the PR's state. Clear it and let the pass
+        // below judge the live head: still green, the row re-marks with the
+        // new binding and wakes the orchestrator; pending or red, it stays
+        // pending until it is not.
+        store.clearDecisionConditionMet(decision.id);
+      }
+    }
     let satisfied = false;
+    let satisfiedHead: string | undefined;
     try {
       if (condition.kind === "pr-merged") {
         const state = await tracker.prState(condition.url);
@@ -204,21 +319,115 @@ export async function evaluateDecisionConditions(
       } else if (condition.kind === "pr-checks-green") {
         // A watch whose PR settled before its checks were seen green cannot
         // ever be met: the checks surface does not answer for a merged or
-        // closed PR, so the row would render `pending` forever (#664).
+        // closed PR, so the row would render `pending` forever (#664). A row
+        // that was already met — then had its head move and its PR settle
+        // before the new head's checks — did see its checks green at the
+        // earlier head, and its withdrawal must record that, or the durable
+        // ledger gains a fact it contradicts (review round 2, #808).
         if (decision.kind === "watch") {
           const state = await tracker.prState(condition.url);
           if (state === "merged" || state === "closed") {
-            store.resolveDecision(decision.id, "withdrawn", `PR ${state} before its checks were seen`, now());
+            const seenGreen = decision.conditionMetAt !== undefined;
+            store.resolveDecision(
+              decision.id,
+              "withdrawn",
+              seenGreen ? `PR ${state} after its checks were seen green` : `PR ${state} before its checks were seen`,
+              now(),
+            );
             continue;
           }
         }
+        // The head anchor is read BEFORE the checks: a verdict is only ever
+        // bound to a head that did not move while the checks were read, and
+        // the anchor-first order is what closes the push race in both
+        // directions. Reading the checks first would let a push that landed
+        // after the checks answered bind the old head's green verdict to the
+        // new, untested commit — both confirming head reads would agree on a
+        // head the checks were never read for (review round 1, #808).
+        const before = await tracker.prHead(condition.url);
         // The same conclusion values the daemon's failure classifier treats as
         // a green verdict (`success` / `neutral`, lowercased): a non-empty list
         // in which every check is terminally successful and none is failing or
         // pending (#189).
         const checks = await tracker.checkConclusions(condition.url);
-        satisfied =
-          checks.length > 0 && checks.every((c) => GREEN_CHECK_STATES[c.state.trim().toLowerCase()] === true);
+        if (
+          before !== undefined &&
+          checks.length > 0 &&
+          checks.every((c) => GREEN_CHECK_STATES[c.state.trim().toLowerCase()] === true)
+        ) {
+          // Confirm the anchor still holds after the checks read: a push that
+          // landed anywhere inside the window surfaces as a mismatch, so the
+          // green list is bound only to a head it was actually read for. A
+          // list without a readable, stable anchor is not yet met — an
+          // unbound verdict is exactly the staleness this fixes, and the next
+          // tick can ask again for free.
+          const after = await tracker.prHead(condition.url);
+          if (before === after) {
+            satisfied = true;
+            satisfiedHead = before;
+          }
+        }
+      } else if (condition.kind === "pr-review-ready") {
+        // A watch whose PR settled before it was seen review-ready can never
+        // be met: neither the checks surface nor a revisable run answers for
+        // a merged or closed PR, so the row would render `pending` forever
+        // (#664). A row that was already met — then had its head move and its
+        // PR settle before the new head's checks — did see its PR ready at
+        // the earlier head, and its withdrawal must record that, the same
+        // history-preserving convention as pr-checks-green (review round 2,
+        // #808).
+        if (decision.kind === "watch") {
+          const state = await tracker.prState(condition.url);
+          if (state === "merged" || state === "closed") {
+            const seenReady = decision.conditionMetAt !== undefined;
+            store.resolveDecision(
+              decision.id,
+              "withdrawn",
+              seenReady ? `PR ${state} after it was review-ready` : `PR ${state} before it was review-ready`,
+              now(),
+            );
+            continue;
+          }
+        }
+        // The store-owned half of review readiness, shared with the verb
+        // (#844): the newest project-owned run that recorded this PR must be
+        // in a revisable state (`pushed-green` / `failed` / `killed`). A PR
+        // with no owner, or whose newest owner is live (`claimed` / `running`
+        // — the original worker or an earlier review revision) or otherwise
+        // non-revisable, stays pending even while its checks are green: the
+        // watch must not wake the orchestrator before `conductor_pr_review`
+        // can legally act.
+        const readiness = prReviewReadiness(store, project, condition.url, now());
+        if (readiness.kind !== "ready") {
+          // A met row whose owner stopped being revisable — the revision
+          // dispatched and the owner is live again (`running` / `claimed`)
+          // or the owner ended non-revisable — returns to pending on the
+          // same tick: the watch exists precisely so the orchestrator is
+          // not woken while `conductor_pr_review` would refuse. The clear
+          // is idempotent, and a revision that settles at the same head
+          // re-marks the row on a later tick.
+          if (decision.conditionMetAt !== undefined) store.clearDecisionConditionMet(decision.id);
+          continue;
+        }
+        // The tracker half, with the same fail-closed exact-head anchor as
+        // pr-checks-green (#808): the current head must be readable, every
+        // current check terminally green, and the head must not move while
+        // the checks were read. An unreadable or unstable head is not yet
+        // ready — never a verdict fabricated from a head the checks were not
+        // read for.
+        const before = await tracker.prHead(condition.url);
+        const checks = await tracker.checkConclusions(condition.url);
+        if (
+          before !== undefined &&
+          checks.length > 0 &&
+          checks.every((c) => GREEN_CHECK_STATES[c.state.trim().toLowerCase()] === true)
+        ) {
+          const after = await tracker.prHead(condition.url);
+          if (before === after) {
+            satisfied = true;
+            satisfiedHead = before;
+          }
+        }
       } else if (condition.kind === "pr-mergeable") {
         // A watch whose PR settled before it was seen mergeable is the same
         // unobservable case as checks: the mergeability literal exists only
@@ -248,8 +457,12 @@ export async function evaluateDecisionConditions(
       continue;
     }
     if (!satisfied) continue;
-    if (store.markDecisionConditionMet(decision.id, now())) {
-      met.push({ ...decision, conditionMetAt: now() });
+    if (store.markDecisionConditionMet(decision.id, now(), satisfiedHead)) {
+      met.push({
+        ...decision,
+        conditionMetAt: now(),
+        ...(satisfiedHead === undefined ? {} : { conditionHead: satisfiedHead }),
+      });
     }
   }
   return met;
@@ -280,8 +493,10 @@ function age(since: number, now: number): string {
  * GitHub's checks is never mistaken for a fleet that is waiting on its
  * operator. A met watch still surfaces to the orchestrator with its note and
  * the same `[CONDITION MET]` flag a met question gets. Every watch line also
- * names the command that closes it (`watch withdraw <id>`), because the
- * surface that shows a watch is where the reader learns how to end one (#664).
+ * names the command that closes it (`watch withdraw <id> --project <project>`),
+ * because the surface that shows a watch is where the reader learns how to end
+ * one (#664). The row's own project is always named — a digest is per-project,
+ * and a bare `watch withdraw <id>` is ambiguous on a host with several (#810).
  */
 export function formatDecisionDigest(open: readonly DecisionRecord[], now = Date.now()): string {
   const questions = open.filter((d) => d.kind !== "watch");
@@ -300,9 +515,12 @@ export function formatDecisionDigest(open: readonly DecisionRecord[], now = Date
       `Watches (${watches.length}) — conditions the orchestrator set for itself; no operator action needed:`,
     );
     for (const d of watches) {
-      // Each line names the verb that closes it, so the orchestrator reading a
-      // digest does not have to know the decisions vocabulary (#664).
-      lines.push(decisionLine(d, now, `watch withdraw ${d.id}`));
+      // Each line names the verb that closes it, qualified by the row's stored
+      // project so a copied command runs verbatim on a multi-project host
+      // (#810). The rows are project-scoped by construction; the stored
+      // project is the one the command must name, shell-quoted because a
+      // project name may contain characters a shell would read.
+      lines.push(decisionLine(d, now, `watch withdraw ${d.id} --project ${shellQuote(d.project)}`));
     }
   }
   return lines.join("\n");

package/src/diff-flags.ts

@@ -37,7 +37,7 @@
  * repository.
  */
 
-import type { PrDiff, PrDiffFile, SettlementFlag } from "./types.ts";
+import type { FileLane, PrDiff, PrDiffFile, SettlementFlag } from "./types.ts";
 
 // ------------------------------------------------------------------ diff parse
 
@@ -504,6 +504,15 @@ export interface SettlementAudit {
    *  had none or it could not be read. Absent means no claimed command can be
    *  checked — same silence, for the same reason. */
   transcript?: string;
+  /**
+   * The effective file lane admission resolved for this run at dispatch
+   * (`effectiveLane` — a pre-dispatch comment declaration supersedes an older
+   * body one) and persisted on the row (#744/#758): the exact snapshot the
+   * gate enforced and the worker brief rendered. Absent means the issue was
+   * admitted with no declaration (fail open) — never "empty lane" — and no
+   * diff can then be outside it.
+   */
+  lane?: FileLane;
 }
 
 /**
@@ -522,6 +531,7 @@ export function analyseSettlement(audit: SettlementAudit): SettlementFlag[] {
   const flags: SettlementFlag[] = [];
   detectWeakening(audit, flags);
   detectClaimedProof(audit, flags);
+  detectLaneEscape(audit, flags);
   return flags;
 }
 
@@ -538,6 +548,70 @@ export const UNREADABLE_TREE_FLAG: SettlementFlag = {
     "the settlement could not read the PR's diff, so no `changed:` file list could be derived",
 };
 
+// ---------------------------------------------------------- declared file lane
+
+/**
+ * Whether a diff path counts as inside the declared lane: an explicitly
+ * declared path, or the co-located test of one — `foo.ts` vouches for
+ * `foo.test.ts`, which is the "obviously intended" case. Other test shapes
+ * (`.spec.ts`, pytest's `test_` prefix) are not vouched for: the rule is the
+ * shape the fleet actually uses, and a lane that wants a differently-shaped
+ * sibling declares it. Deliberately one-directional: a lane that declares a
+ * *test* file does not vouch for its source, because declaring the test alone
+ * is a narrower promise and widening it silently is exactly what this flag
+ * exists to name. A containing directory never vouches for its contents
+ * either — the lane grammar names files, and a lane that means "everything
+ * under `src/`" fails open exactly as an undeclared one would if it cannot
+ * name them.
+ */
+function withinLane(path: string, declared: readonly string[]): boolean {
+  if (declared.includes(path)) return true;
+  for (const d of declared) {
+    if (coLocatedTest(d) === path) return true;
+  }
+  return false;
+}
+
+/** `omp/src/verbs/server.ts` → `omp/src/verbs/server.test.ts`; undefined when
+ *  the declared path has no file extension to splice before, since the
+ *  co-located-test shape is defined by an extension. */
+function coLocatedTest(declared: string): string | undefined {
+  const dot = declared.lastIndexOf(".");
+  const slash = declared.lastIndexOf("/");
+  if (dot <= slash + 1) return undefined;
+  return `${declared.slice(0, dot)}.test${declared.slice(dot)}`;
+}
+
+/**
+ * A diff that escapes its issue's declared file lane (#739).
+ *
+ * The lane is the effective declaration admission resolved at dispatch —
+ * `effectiveLane(body, comments)`, so a pre-dispatch comment beats an older
+ * body declaration — and the flag uses that resolved snapshot, never a re-parse
+ * of the body. The finding names every delivered file outside it, which is the
+ * part a reviewer is worst placed to notice: the diff's own file list is the
+ * only surface that shows the escape, and reading PR file lists by hand is
+ * exactly what nothing else in the loop does.
+ *
+ * Fail-open, like admission: an issue with no lane declaration has nothing to
+ * escape, so no flag — a flag on every undeclared run would be noise within a
+ * day, worse than no flag. Advisory like every other flag here: a widened lane
+ * is often legitimate, and the orchestrator is the judge this exists to brief.
+ */
+function detectLaneEscape(audit: SettlementAudit, flags: SettlementFlag[]): void {
+  const lane = audit.lane;
+  if (lane === undefined || lane.files.length === 0) return;
+  const outside = audit.diff.files
+    .map((f) => f.path)
+    .filter((path) => !withinLane(path, lane.files));
+  if (outside.length === 0) return;
+  flags.push({
+    kind: "lane-escape",
+    file: "(lane)",
+    detail: `PR diff touches files outside the declared file lane: ${outside.join(", ")}`,
+  });
+}
+
 function detectWeakening(audit: SettlementAudit, flags: SettlementFlag[]): void {
   // A test file that left one path and arrived at another is a move, not a
   // deletion. `status: renamed` covers the renames git detected; the basename

package/src/doctor.ts

@@ -85,7 +85,10 @@ import {
   SYSTEMD_UNIT_DIR,
   tickCwdForProject,
   totalConfiguredWorkers,
+  workerAclHealth,
+  type WorkerAclHealth,
 } from "./setup-host.ts";
+import { WORKER_ACCOUNT } from "./host.ts";
 import { checkTokenScopes, type ScopeCheck } from "./setup.ts";
 import { DB_SNAPSHOT_STEM, dbPath, LIVE_STATES } from "./store.ts";
 import { telegramReportSend, type ReportSend } from "./reports.ts";
@@ -142,6 +145,10 @@ const INCIDENTS = {
   spend:
     "spend telemetry was once absent, so the USD cap never fired — $0.00 spend is not proof of no spend",
   ghauth: "gh auth expired under a live daemon and every tracker call failed silently",
+  workerAcl:
+    "the #835 incident: a setup host granted the worker's path ACLs before restarting the fleet, an OMP startup chmod'd " +
+    "the agent config dir back to 0700 and rewrote the ACL mask, and the next two admitted workers died on EACCES " +
+    "before connecting — the named ACL entry was still there, only its effective permissions were gone",
 } as const;
 
 // ------------------------------------------------------------------ dependencies
@@ -268,6 +275,13 @@ export interface DoctorDeps {
   tickAgentName?: (project: ProjectConfig) => string | undefined;
   /** Clock, so a run is deterministic in tests. */
   now?: () => number;
+  /** The linked worker config paths' effective-ACL verdict for the dedicated
+   *  worker account (#835): `checkable` paths judged, `missing` the ones that
+   *  do not currently grant the worker's needed effective access. Read-only
+   *  and injectable so no test ever touches the host's ACLs; the production
+   *  wiring is the identity plan's own getfacl probe, so `doctor` and
+   *  `setup host` cannot disagree about an ACL. */
+  workerAclHealth?: () => WorkerAclHealth;
   /** The one opt-in side effect: send one self-identified Telegram probe. */
   probeTelegram?: boolean;
 }
@@ -902,6 +916,37 @@ function ownershipProbe(probes: Probes): Finding {
   return failFinding("systemd-ownership", summary, fix);
 }
 
+/**
+ * The dedicated worker account's path ACLs (#835): every linked worker config
+ * path must grant the worker its *effective* search/read permissions. The
+ * installed OMP harness chmods its agent config dir back to 0700 on every
+ * open, and a chmod rewrites the ACL mask — the named entry survives as
+ * `user:omp-worker:--x  #effective:---` while the worker's access silently
+ * vanishes, which is exactly the incident this finding exists to catch
+ * (`${INCIDENTS.workerAcl}`). The verdict comes from the identity plan's own
+ * probe through the read-only {@link DoctorDeps.workerAclHealth} seam, so a
+ * pass here is a pass the plan agrees with and a fail names the paths whose
+ * mask is stripping the grant.
+ */
+function workerAclProbeFinding(probes: Probes): Finding {
+  const health = probes.workerAclHealth();
+  if (health.checkable === 0) {
+    return passFinding("worker-acl", "no linked worker config paths on this host yet — nothing to check");
+  }
+  if (health.missing.length === 0) {
+    return passFinding(
+      "worker-acl",
+      `${health.checkable} linked worker config path(s) grant ${WORKER_ACCOUNT} effective search/read access`,
+    );
+  }
+  return failFinding(
+    "worker-acl",
+    `the ${WORKER_ACCOUNT} account's ACL is not effective on ${health.missing.join(", ")} — a named entry the ACL mask strips is ` +
+      "unreachable by the worker, and the next admitted worker dies on EACCES before connecting",
+    "re-run `omp-conductor setup host`: the transaction re-applies the ACL grants (mask included) after the final fleet restart",
+  );
+}
+
 /** IANA timezone in reporting config — an invalid zone silently mis-schedules
  *  the availability window and the daily digest (#273). */
 function timezoneProbe(project: ProjectConfig | undefined): Finding {
@@ -1645,6 +1690,10 @@ export async function runDoctor(projectName: string | undefined, opts: DoctorDep
   findings.push(unitProbe(probes, projects[0], cfg));
   findings.push(recoveryProbe(probes));
   findings.push(ownershipProbe(probes));
+  // The worker's path ACLs are a host-wide fact like the unit ownership: one
+  // shared daemon account, one shared worker identity, one shared set of
+  // linked config paths. A finding once, never once per project.
+  findings.push(workerAclProbeFinding(probes));
   // #541 seam checks, host-global: the live herdr config and the plugin's
   // config.env are single files on the host, not per-project facts.
   findings.push(herdrResumeProbe(probes));
@@ -1688,6 +1737,9 @@ export function defaultProbes(): Probes {
     readUnit: defaultReadUnit,
     stat: defaultStat,
     uidOf: defaultUidOf,
+    // The same effective-ACL read the identity plan plans with — doctor and
+    // setup cannot disagree about a worker grant (#835).
+    workerAclHealth: () => workerAclHealth(join(homedir(), ".omp", "agent")),
     dbIntegrity: defaultDbIntegrity,
     snapshotDirState: defaultSnapshotDirState,
     sessionRootState: defaultSessionRootState,

package/src/escalate.ts

@@ -403,11 +403,17 @@ function errText(e: unknown): string {
  *
  * Exported for the report outbox (#123), which pages over the same bot and must
  * resolve the token the same way. Two readers of one `.env` is fine; two
- * *implementations* of the parse below is how they drift.
+ * *implementations* of the parse below is how they drift. The state dir is the
+ * shared resolution both the token read and the interactive ask surface (#722)
+ * need, so it is one function rather than a second copy of the override.
  */
-export function readTelegramToken(): string | undefined {
+export function telegramStateDir(): string {
   const override = process.env.OMP_TELEGRAM_STATE_DIR?.trim();
-  const dir = override ? override : join(homedir(), ".omp", "agent", "telegram");
+  return override ? override : join(homedir(), ".omp", "agent", "telegram");
+}
+
+export function readTelegramToken(): string | undefined {
+  const dir = telegramStateDir();
   let raw: string;
   try {
     raw = readFileSync(join(dir, ".env"), "utf8");