omp-conductor 0.3.23 → 0.3.24

package/README.md

@@ -167,14 +167,20 @@ Also required on the host:
     dispatch is only defensible while a tier-2 page can reach a person.
   - **Approving a Learning-loop amendment from a heartbeat tick** needs one more
     setting than pairing: a notify destination. `/telegram notify` writes
-    `notifyMode` and `notifyChat` into the same `access.json`; `/telegram topics`
-    does it with a forum topic instead. omp-telegram mounts its `telegram_ask`
-    tool only for a turn that resolves a notify target, and a locally injected
-    tick resolves one only through that setting — so without it the orchestrator
-    can page you but cannot put a yes/no question in front of you, which is the
-    one thing the Learning loop's approval step requires. `omp-conductor status`
-    reports this on the `telegram` row, and a tick that finds the tool missing
-    says so in its own prompt and falls back to `telegram_send`.
+    `notifyMode` and `notifyChat` into the same `access.json`. omp-telegram
+    mounts its `telegram_ask` tool only for a turn that resolves a notify target,
+    and a locally injected tick resolves one only through that setting — so
+    without it the orchestrator can page you but cannot put a yes/no question in
+    front of you, which is the one thing the Learning loop's approval step
+    requires. `omp-conductor status` reports this on the `telegram` row, and a
+    tick that cannot ask says so in its own prompt and falls back to
+    `telegram_send`.
+
+    Set `notifyChat` even on a forum fleet. `/telegram topics` routes to a topic
+    this session claims at runtime, and that claim is not visible in
+    `access.json` — so a file carrying only `topicsChat` is reported as
+    unconfigured rather than guessed at, on the grounds that a health row which
+    reads green over a broken contract is worse than one that overstates a fault.
 
   With neither, tier 2 degrades to a comment on the issue. Nothing is broken in
   that configuration: it is supported, just slower to reach you.
@@ -714,12 +720,15 @@ Run history is untouched. A PR closed without merging becomes a concrete failed
 attempt; a merge does not spend failure or continuation budget. A settled row also
 loses `agent:in-progress` from its issue: the row transition and the label are one
 fact, and a terminal answer about the PR proves no worker process owns the issue,
-so the duplicate-dispatch guard it exists for is spent. Rows that did not settle
-keep the label, and a tracker that refuses the removal is logged rather than
-allowed to abort the sweep — `omp-conductor unblock` clears it by hand in that
-rare case. Anything beyond that one release — a re-queue, a `blocked` marker —
-is still the orchestrator's drain-duty judgement. One unreachable PR costs its own
-row and nothing else; the rest of the sweep still settles.
+so the duplicate-dispatch guard it exists for is spent. The label comes off
+*before* the row is written terminal, because this sweep is the only thing that
+revisits a `pushed-*` row: a tracker that refuses the removal therefore leaves the
+row pending and the next tick tries again, rather than stranding the label on an
+issue nothing will look at twice. The issue stays in the busy set while it waits,
+so nothing is dispatched onto it in between. Anything beyond that one release — a
+re-queue, a `blocked` marker — is still the orchestrator's drain-duty judgement.
+One unreachable PR costs its own row and nothing else; the rest of the sweep
+still settles.
 
 Until this existed, nothing ever revisited a `pushed-green` row: the startup
 reconciler only settles rows that held a process, and `merged` went unwritten. On
@@ -1259,13 +1268,23 @@ start: the bridge is reconfigured out-of-band, and a heartbeat that trusted a
 startup snapshot would keep dispatching for days after the channel went away. A
 stale arm marker must not outlive the channel that makes running unattended safe.
 
-The check passes only when the file parses to an object with `enabled: true` and
-exactly one `allowFrom` entry. Everything else stops the heartbeat: file missing,
+The check passes only when a bot token is resolvable — `TELEGRAM_BOT_TOKEN` in
+the environment, or in the `.env` beside `accessFile` — and the file parses to an
+object with `enabled: true` and exactly one `allowFrom` entry. Everything else
+stops the heartbeat: no token, so nothing outbound works at all; file missing,
 unreadable or truncated; not JSON, or JSON that is not an object; `enabled`
 absent or false; zero owners paired (nobody to page) or more than one (ambiguous:
 the conductor refuses to guess which human is on the hook). Failure modes are
 deliberately not distinguished in the decision: each one means a page lands
-nowhere.
+nowhere. `omp-conductor status` is where they are told apart — its `telegram` row
+names the specific fault.
+
+One caveat the file cannot express: omp-telegram binds its own copy of the token
+in `startBot()` at session start, and rebinds it only on `/telegram token` or
+`/telegram on`. Writing a token into `.env` out-of-band therefore restores
+tier-2 paging immediately — conductor sends those itself — while the bridge's own
+tools, `telegram_send` and `telegram_ask`, stay dead until you reload it. After
+adding a token by hand, run `/telegram on` in the orchestrator session.
 
 Leaving `accessFile` unset passes the gate, because an ordinary developer session
 that happens to have a `.conductor-tick.json` has no bridge to check. It is not an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.3.23",
+  "version": "0.3.24",
   "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/approval-surface.ts

@@ -0,0 +1,218 @@
+/**
+ * Can a *locally injected* turn ask its operator a yes/no question?
+ *
+ * One predicate, shared by the tick that has to warn about the answer and the
+ * status row that has to report it, because two spellings of it would drift and
+ * the whole point is that the health line and the tick agree.
+ *
+ * It is deliberately a question about **configuration**, not about the mounted
+ * tool set, and that distinction is the correction to a first attempt that got
+ * it wrong. omp-telegram mounts `telegram_ask` in `before_agent_start` and
+ * removes it again in `agent_end` (`restorePromptTools`), so the tool exists
+ * only *during* a turn. Anything that looks at `getActiveTools()` between turns
+ * — which is exactly where a heartbeat composes its prompt — sees the base set
+ * and would report the tool missing on every tick, including a correctly
+ * configured fleet. A false alarm every interval is worse than no alarm: it
+ * trains the operator to ignore the line that is supposed to mean something.
+ *
+ * What actually decides the mounting is knowable ahead of the turn. omp-telegram
+ * resolves a prompt target from the turn's own `<telegram-message>` wrapper, or
+ * failing that from `notifyTarget()`, which needs `notifyMode` set to "away" or
+ * "always" *and* a destination it can reach. A locally injected tick never has a
+ * wrapper, so for ticks the predicate reduces to config keys readable before the
+ * turn starts — with one deliberate narrowing, documented at the destination
+ * check below: only `notifyChat` counts, because a forum topic depends on live
+ * per-session state no file can evidence.
+ *
+ * That is exactly what failed on 2026-08-09 06:17Z: the fleet's access.json had
+ * no `notifyMode`, so the locally injected tick could not ask the Learning-loop
+ * yes/no question the package floor requires — while the status line reported
+ * `telegram  ok  (@tbcoder_bot; inbound configured)` throughout (#114). A health
+ * row that stays green through a broken contract is worse than no row.
+ *
+ * The legacy `away: true` boolean counts: `loadAccess()` migrates it to
+ * `notifyMode: "away"` on read, so a fleet still carrying it resolves a target
+ * and must not be reported as broken.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** The tool the package floor names for the Learning-loop yes/no amendment
+ *  approval (`## Learning loop`, step 2, in `briefs/orchestrator.md`). Held as
+ *  a constant because the prose that tells a turn to call it and the check that
+ *  says whether it can be called must name the same thing. */
+export const TELEGRAM_APPROVAL_TOOL = "telegram_ask";
+
+export type ApprovalSurface = { kind: "ready" } | { kind: "missing"; reason: string };
+
+/** One checked read of a JSON property, so nothing below asserts a shape the
+ *  parse never proved. Anything that is not a plain object, or a key that is
+ *  absent, answers undefined — which every caller here already treats as
+ *  "unconfigured". */
+function field(value: unknown, key: string): unknown {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  return Object.hasOwn(value, key) ? Reflect.get(value, key) : undefined;
+}
+
+/**
+ * Whether omp-telegram would find a bot token — its rule, not a reasonable one.
+ *
+ * This gates the heartbeat, so it has to predict another package's answer, and
+ * anywhere it is more generous than that package the gate fails *open*: it would
+ * report a token, let the tick fire, and leave the fleet dispatching with an
+ * outbound channel that never worked. So it mirrors `resolveToken()` in
+ * omp-telegram's `access.ts` exactly — process environment first, then the first
+ * line of `<state dir>/.env` matching `/^TELEGRAM_BOT_TOKEN=(.*)$/` after a
+ * trim, first match winning even when its value is empty.
+ *
+ * That regex is deliberately strict where a dotenv reader would not be:
+ * `export TELEGRAM_BOT_TOKEN=…` and `TELEGRAM_BOT_TOKEN = …` are both files
+ * omp-telegram reads no token from, so both must close this gate.
+ *
+ * `escalate.ts` parses the same file more permissively on purpose, and the two
+ * are not a contradiction to be tidied away: that one asks "can *conductor* send
+ * a page with this", and it can, because it does the parsing and the request
+ * itself. This one asks "will *omp-telegram* have a token", and only omp-telegram
+ * decides that.
+ */
+export function hasBotToken(stateDir: string): boolean {
+  const fromEnv = process.env["TELEGRAM_BOT_TOKEN"];
+  if (fromEnv !== undefined && fromEnv.length > 0) return true;
+  let raw: string;
+  try {
+    raw = readFileSync(join(stateDir, ".env"), "utf8");
+  } catch {
+    return false;
+  }
+  for (const line of raw.split("\n")) {
+    const match = /^TELEGRAM_BOT_TOKEN=(.*)$/.exec(line.trim());
+    if (match === null) continue;
+    // First match wins even when empty, exactly as `resolveToken()` returns on
+    // its first hit — a file whose first token line is blank has no token, and
+    // reading past it would disagree with the package this predicts.
+    return (match[1] ?? "").length > 0;
+  }
+  return false;
+}
+
+/** Reads the omp-telegram access file and answers whether a locally injected
+ *  turn would resolve an answerable destination.
+ *
+ *  A bot token is *not* checked here, deliberately: without one nothing outbound
+ *  works at all, so it is a whole-channel fault rather than an approval-surface
+ *  one. Both callers settle it first — the tick through its escalation-channel
+ *  gate, which refuses to fire at all, and `probeTelegramHealth` through a
+ *  `getMe` that has already succeeded. This function is only ever asked about a
+ *  bridge that can send. Never throws: an unreadable or malformed file is a
+ *  missing surface with the path named, not an exception taken out of a
+ *  heartbeat. */
+export function readApprovalSurface(path: string): ApprovalSurface {
+  let access: unknown;
+  try {
+    access = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return { kind: "missing", reason: `${TELEGRAM_APPROVAL_TOOL} unavailable on local ticks: cannot read ${path}` };
+  }
+  if (access === null || typeof access !== "object" || Array.isArray(access)) {
+    return {
+      kind: "missing",
+      reason: `${TELEGRAM_APPROVAL_TOOL} unavailable on local ticks: ${path} is not an object`,
+    };
+  }
+  const mode = field(access, "notifyMode");
+  const active = mode === "away" || mode === "always" || field(access, "away") === true;
+  if (!active) {
+    return {
+      kind: "missing",
+      reason:
+        `${TELEGRAM_APPROVAL_TOOL} unavailable on local ticks: no notifyMode in ${path} — ` +
+        `set it to "always" and set notifyChat to the paired owner id`,
+    };
+  }
+  // Only `notifyChat` counts, and `topicsChat` deliberately does not, even
+  // though omp-telegram can resolve a forum topic. `notifyTarget()` is handed a
+  // topic destination only when `ownTopic && access.topicsChat`, and `ownTopic`
+  // is per-session runtime state — the thread this process actually claimed —
+  // assigned during topic setup and cleared on failure. A file cannot prove it.
+  // So a fleet carrying `topicsChat` alone may or may not have the tool mounted,
+  // and this check answers the safe way: #114 exists because a health signal
+  // said "ok" through a broken contract, and repeating that with a stale
+  // `topicsChat` would be the same bug wearing a different key. `notifyChat` is
+  // resolvable from the file alone, so it is what "configured" means here.
+  const destination = field(access, "notifyChat");
+  if (typeof destination !== "string" || destination.length === 0) {
+    const topicsChat = field(access, "topicsChat");
+    const viaTopic =
+      typeof topicsChat === "string" && topicsChat.length > 0
+        ? " — topicsChat only resolves once this session has claimed its forum topic, which this file cannot show"
+        : "";
+    return {
+      kind: "missing",
+      reason:
+        `${TELEGRAM_APPROVAL_TOOL} unavailable on local ticks: notifyMode is set but ${path} names no notifyChat` +
+        `${viaTopic} — set notifyChat to the paired owner id`,
+    };
+  }
+
+  // Naming a destination is not the same as being able to answer in it, and
+  // `buildPromptTarget()` applies two more gates before a target exists. Both
+  // are decidable from this file, so both belong here — a `ready` that skipped
+  // them would say the approval works while a stale or wrong chat id silently
+  // reproduces #114.
+  //
+  // First, `pairedOwnerId()` is the single entry of `allowFrom`; anything else
+  // yields no responder and therefore no target.
+  const allowFrom = field(access, "allowFrom");
+  const owner = Array.isArray(allowFrom) && allowFrom.length === 1 ? String(allowFrom[0]) : undefined;
+  if (owner === undefined) {
+    return {
+      kind: "missing",
+      reason:
+        `${TELEGRAM_APPROVAL_TOOL} unavailable on local ticks: ${path} has no single paired owner in allowFrom, ` +
+        "so no one is authorised to answer",
+    };
+  }
+
+  // Then `canAnswerPrompt()`, which is the same DM/group policy inbound turns
+  // use. `isDmChat()` calls anything not starting with "-" a DM, and a DM only
+  // authorises the owner's *own* chat — a DM chat id equals its user id, so a
+  // notifyChat pointing at any other person is unanswerable by the paired owner.
+  if (!destination.startsWith("-")) {
+    if (destination !== owner) {
+      return {
+        kind: "missing",
+        reason:
+          `${TELEGRAM_APPROVAL_TOOL} unavailable on local ticks: notifyChat ${destination} in ${path} is a DM that ` +
+          `is not the paired owner's (${owner}), and only the owner's own DM authorises an answer — ` +
+          "set notifyChat to the paired owner id",
+      };
+    }
+    return { kind: "ready" };
+  }
+
+  // A group destination needs a policy entry, and that policy must admit the
+  // owner: an empty or absent `allowFrom` means everyone in the group, else the
+  // owner has to be listed.
+  const policy = field(field(access, "groups"), destination);
+  if (policy === null || typeof policy !== "object") {
+    return {
+      kind: "missing",
+      reason:
+        `${TELEGRAM_APPROVAL_TOOL} unavailable on local ticks: notifyChat ${destination} in ${path} is a group with ` +
+        "no entry under groups, so no answer from it is authorised",
+    };
+  }
+  const groupAllow = field(policy, "allowFrom");
+  const admitted =
+    !Array.isArray(groupAllow) || groupAllow.length === 0 || groupAllow.map(String).includes(owner);
+  if (!admitted) {
+    return {
+      kind: "missing",
+      reason:
+        `${TELEGRAM_APPROVAL_TOOL} unavailable on local ticks: group ${destination} in ${path} does not admit the ` +
+        `paired owner (${owner}) in its allowFrom, so their answer would be rejected`,
+    };
+  }
+  return { kind: "ready" };
+}

package/src/daemon.ts

@@ -893,26 +893,33 @@ export function settlementFor(pr: PrState | undefined, prUrl: string): Settlemen
  * hand-editing one, and `unblock` refused to clear that particular label — so
  * both issues were permanently unclaimable with no supported way back (#18).
  *
- * Never throws, and that is the point of it being a function rather than a
- * bare `removeLabel`. Callers are sweeps: the store transition this accompanies
- * has already been written, so a tracker that fails here must cost one label,
- * not the remaining rows. There is no retry — the row is terminal, so no later
- * tick revisits it — which makes the log line the entire record of the miss and
- * why it names both the label and the reason. The operator's recovery for that
- * rare case is `omp-conductor unblock`, which clears the label itself once the
- * newest run is terminal.
+ * Never throws, and reports whether the label is provably gone, because the
+ * caller has to decide what to write to the store on the strength of it. A
+ * sweep must not lose the rest of its rows to one unreachable tracker, and it
+ * must not terminalise a row whose label it failed to drop: the settlement
+ * sweep only ever revisits `pushed-*` rows, so a row written terminal is a row
+ * nothing asks about again, and swallowing the failure under it would recreate
+ * the exact permanent-`agent:in-progress` state of #18 in the one case that
+ * still reaches it. Answering false instead leaves the row where the next tick
+ * will find it.
+ *
+ * Removing a label the issue does not carry is success, not failure: the GitHub
+ * adapter treats an absent label as a no-op, so false means the tracker could
+ * not be reached or refused — a condition that passes.
  */
 export async function releaseInProgress(
   d: Pick<Deps, "project" | "tracker">,
   issue: number,
   why: string,
-): Promise<void> {
+): Promise<boolean> {
   const label = d.project.stateLabels.inProgress;
   try {
     await d.tracker.removeLabel(issue, label);
     log(`#${issue} released ${label}: ${why}`);
+    return true;
   } catch (err) {
-    log(`#${issue} could not release ${label} (${errText(err)}) — ${why}; clear it with \`unblock\``);
+    log(`#${issue} could not release ${label} (${errText(err)}) — ${why}; retrying next tick`);
+    return false;
   }
 }
 
@@ -946,6 +953,15 @@ export async function releaseInProgress(
  * the same Tracker port the dispatcher claimed the issue with — orphan detection
  * is only trustworthy while every state label on the tracker came from this
  * package.
+ *
+ * The two writes are ordered label-then-row, and the order is load-bearing. This
+ * sweep is the only thing that revisits a `pushed-*` row, so the terminal state
+ * is also the row's exit from it: written first, a tracker that then failed on
+ * the label would leave `agent:in-progress` with nothing left to retry it — #18
+ * exactly, in the last window able to reach it. Writing the label first makes
+ * failure cost a repeated `gh` call on the next tick instead, and the row stays
+ * in the busy set throughout, so no second worker can be sent at the issue while
+ * it waits.
  */
 export async function settlePushedGreen(
   d: Pick<Deps, "project" | "tracker" | "store">,
@@ -978,14 +994,19 @@ export async function settlePushedGreen(
 
     const settlement = settlementFor(pr, run.prUrl);
     if (settlement !== undefined) {
+      // Label first, row second, and the order is the whole safety argument.
+      // The sweep only ever revisits `pushed-*` rows, so writing the terminal
+      // state first would put this row beyond every later tick — and a tracker
+      // that failed on the label in that instant would strand
+      // `agent:in-progress` permanently, which is #18 again in the one window
+      // still able to reach it. Leaving the row `pushed-*` costs a stale active
+      // row until the tracker answers, and the busy set keeps the issue
+      // occupied meanwhile, so nothing can be dispatched onto it in between.
+      if (!(await releaseInProgress(d, run.issue, settlement.reason))) continue;
       const patch: Partial<RunRecord> = { state: settlement.state, endedAt: Date.now() };
       if (settlement.state === "failed") patch.lastError = settlement.reason;
       store.updateRun(run.id, patch);
       log(`#${run.issue} settled: ${settlement.reason}`);
-      // Store and tracker in the same breath, for the reason above: the row is
-      // terminal, so the label's interlock is spent. `releaseInProgress` never
-      // throws, so a tracker hiccup costs this label and not the later rows.
-      await releaseInProgress(d, run.issue, settlement.reason);
       continue;
     }
 
@@ -1002,13 +1023,13 @@ export async function settlePushedGreen(
       store.updateRun(run.id, { state: "pushed-green", lastError: undefined });
       log(`#${run.issue} checks settled: ${verification.reason}`);
     } else if (verification.status === "failed") {
+      // Equally terminal, so the same label-first order for the same reason:
+      // this row is about to leave the sweep's reach. The green branch above
+      // releases nothing — that row is still awaiting a merge, and its live PR
+      // is exactly the work the label must keep guarding.
+      if (!(await releaseInProgress(d, run.issue, verification.reason))) continue;
       store.updateRun(run.id, { state: "failed", lastError: verification.reason });
       log(`#${run.issue} checks failed: ${verification.reason}`);
-      // Equally terminal: a red check on a pushed row ends the attempt, so the
-      // same release applies. The green branch above deliberately does not —
-      // that row is still awaiting a merge, and its live PR is exactly the work
-      // the label must keep guarding.
-      await releaseInProgress(d, run.issue, verification.reason);
     } else {
       store.updateRun(run.id, { lastError: verification.reason });
     }

package/src/fleet.ts

@@ -28,6 +28,7 @@ import { createInterface } from "node:readline";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { findProject, loadConfig, stateDir } from "./config.ts";
+import { readApprovalSurface } from "./approval-surface.ts";
 import { probeCodeGraph, type CodeGraphHealth } from "./graph-health.ts";
 import { formatDispatchSummary, isPaused, setPaused, statusSnapshot, type StatusSnapshot } from "./daemon.ts";
 import {
@@ -1082,62 +1083,11 @@ function readPairedChannel(path: string): Channel {
 }
 
 /**
- * Whether the *approval* half of the Telegram surface works, which is a
- * different question from whether inbound works and was never asked before.
- *
- * `telegram_ask` is mounted by omp-telegram's `before_agent_start` handler only
- * for a turn whose prompt resolves a notify target. A Telegram-originated turn
- * resolves one from its own `<telegram-message>` wrapper; a locally injected
- * orchestrator tick has no wrapper, so it resolves one only through
- * `notifyTarget()` — which needs `notifyMode` set to "away" or "always" *and* a
- * destination, this session's forum topic under `topicsChat` or the flat
- * `notifyChat`. With neither, the tool is simply absent from the tick.
- *
- * That is exactly what happened on 2026-08-09 06:17Z: the fleet's access.json
- * had no `notifyMode`, so the locally injected tick could not ask the
- * Learning-loop yes/no question the package floor requires — while this very
- * status line reported `telegram  ok  (@tbcoder_bot; inbound configured)`
- * throughout (#114). A health row that stays green through a broken contract is
- * worse than no row, so the approval surface is now part of it.
- *
- * The legacy `away: true` boolean counts: `loadAccess()` migrates it to
- * `notifyMode: "away"` on read, so a fleet still carrying it resolves a target
- * and must not be reported as broken.
+ * The approval half of the Telegram surface is a different question from
+ * whether inbound works, and it is answered by {@link readApprovalSurface} —
+ * shared with the orchestrator tick so this row and the tick's own warning can
+ * never disagree about whether an amendment can be asked.
  */
-type ApprovalSurface = { kind: "ready" } | { kind: "missing"; reason: string };
-
-function readApprovalSurface(path: string): ApprovalSurface {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    return { kind: "missing", reason: `telegram_ask unavailable on local ticks: cannot read ${path}` };
-  }
-  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-    return { kind: "missing", reason: `telegram_ask unavailable on local ticks: ${path} is not an object` };
-  }
-  const access = parsed as { readonly [key: string]: unknown };
-  const mode = access["notifyMode"];
-  const active = mode === "away" || mode === "always" || access["away"] === true;
-  if (!active) {
-    return {
-      kind: "missing",
-      reason:
-        `telegram_ask unavailable on local ticks: no notifyMode in ${path} — ` +
-        `set it to "always" and give it a destination (notifyChat, or topicsChat for a forum)`,
-    };
-  }
-  const destination = access["notifyChat"] ?? access["topicsChat"];
-  if (typeof destination !== "string" || destination.length === 0) {
-    return {
-      kind: "missing",
-      reason:
-        `telegram_ask unavailable on local ticks: notifyMode is set but ${path} names no destination — ` +
-        "set notifyChat to the paired owner id (or topicsChat for a forum)",
-    };
-  }
-  return { kind: "ready" };
-}
 
 function readBotToken(): string | undefined {
   const env = process.env["TELEGRAM_BOT_TOKEN"];
@@ -1205,6 +1155,8 @@ export async function probeTelegramHealth(
   // Inbound first: a bridge that is down says nothing about the approval
   // surface, and stacking two remedies on one row buries the one to act on.
   if (channel.kind === "down") return { kind: "degraded", detail: `${username}; inbound ${channel.reason}` };
+  // The token is already proven: `getMe` succeeded above. What is left is
+  // whether an answer could come back, which is the access file's business.
   const approval = readApprovalSurface(accessPath);
   if (approval.kind === "missing") {
     return { kind: "degraded", detail: `${username}; inbound configured; ${approval.reason}` };

package/src/orchestrator-tick.ts

@@ -46,8 +46,9 @@
 
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { findProject, loadConfig, resolveReleasePolicy } from "./config.ts";
+import { hasBotToken, readApprovalSurface, TELEGRAM_APPROVAL_TOOL } from "./approval-surface.ts";
 import {
   briefPathForProject,
   policyPathForProject,
@@ -340,15 +341,9 @@ export const TICK_SCOPE_CONSTRAINTS: { readonly [K in ReportScope]: string } = {
 export const TICK_DELIVERY_RULE =
   "This tick was injected locally, not sent from Telegram, so your end-of-turn text does NOT reach your operator. Deliver anything reportable this turn by calling the telegram_send tool and confirming success; never claim a report was sent otherwise.";
 
-/**
- * The tool the package floor names for the Learning-loop yes/no amendment
- * approval (`## Learning loop`, step 2, in `briefs/orchestrator.md`).
- *
- * Held as a constant because two things must agree on it: the prose that tells
- * the turn to call it, and the preflight that checks whether it is callable at
- * all.
- */
-export const TELEGRAM_APPROVAL_TOOL = "telegram_ask";
+/** Re-exported so the tick's own contract stays readable from one file: the
+ *  constant itself lives beside the check that decides whether it is callable. */
+export { TELEGRAM_APPROVAL_TOOL };
 
 /**
  * Appended to every tick — the shipped prompt or the operator's own — composed
@@ -917,21 +912,44 @@ export function tickDecision(input: {
 }
 
 /**
- * Whether the Telegram bridge can still reach a person: enabled, with exactly
- * one paired owner.
+ * Whether the Telegram bridge can still reach a person: a bot token, enabled,
+ * with exactly one paired owner.
  *
  * Fail-closed, and every failure mode collapses to the same answer on purpose —
  * missing file, truncated write, hand-edit that dropped `enabled`, a second
- * chat id pasted in, or the pairing revoked. Distinguishing them would only
- * tempt a future reader into treating one of them as benign, and none of them
- * are: each one means a tier-2 escalation lands nowhere.
+ * chat id pasted in, the pairing revoked, or no token for the bot to send with.
+ * Distinguishing them would only tempt a future reader into treating one of them
+ * as benign, and none of them are: each one means a tier-2 escalation lands
+ * nowhere.
+ *
+ * The token belongs in this gate rather than further down. Without one nothing
+ * outbound works, so a tick would carry a delivery rule ordering a
+ * `telegram_send` that cannot happen and an approval fallback naming the same
+ * unusable tool — an unattended fleet dispatching with no way to page anybody,
+ * which is the one thing the arm handshake exists to prevent. A missing token
+ * fails the whole channel; the narrower approval preflight is reserved for a
+ * bridge that can send but cannot ask.
  *
- * Re-read on every tick rather than cached at session start, because the bridge
- * is reconfigured by a long-lived operator out-of-band and a heartbeat that
- * trusted a startup snapshot would keep dispatching for days after the channel
- * went away.
+ * Re-read on every tick, and specifically *not* snapshotted at session start,
+ * because of what this gate is actually about. Tier 2 is paged by conductor
+ * itself: `escalate.ts` reads the same `.env` and calls `api.telegram.org`
+ * directly, never through omp-telegram's bridge. So the question "can an
+ * escalation still reach a person" is answered by the file as it stands now, and
+ * an operator who fixes a missing token has fixed paging immediately — a startup
+ * snapshot would keep a working fleet silent until somebody restarted the
+ * session, which is a worse failure than the one it would prevent. Re-reading
+ * also catches the reverse: a channel that goes away mid-session stops the
+ * heartbeat on the next tick rather than days later.
+ *
+ * What the file cannot answer is whether *omp-telegram* holds a token. It binds
+ * one in `startBot()` at session start and rebinds only on `/telegram token` and
+ * `/telegram on`, so a token added out-of-band leaves the bridge's own tools —
+ * `telegram_ask`, `telegram_send` — dead until one of those runs. That is real,
+ * and it is deliberately not modelled here: this gate protects paging, the
+ * README says to reload the bridge, and `omp-conductor status` shows the row.
  */
 function channelIsUp(path: string): boolean {
+  if (!hasBotToken(dirname(path))) return false;
   let parsed: unknown;
   try {
     parsed = JSON.parse(readFileSync(path, "utf8"));
@@ -1115,13 +1133,32 @@ function tick(pi: TickApi, ctx: TickContext, config: TickConfig, session: TickSe
     }
   }
 
-  // The floor's approval primitive, checked against the live mounted set at the
-  // moment this tick is composed — not once at session start, because the
-  // mounted set is exactly what differed between two consecutive turns of the
-  // same session on 2026-08-09 (#114). Appended last, after the friction
-  // digest: the digest is what provokes an amendment, so the sentence that says
-  // the amendment cannot be approved here is the one that should read last.
-  if (!pi.getActiveTools().includes(TELEGRAM_APPROVAL_TOOL)) {
+  // The floor's approval primitive, decided from configuration rather than from
+  // the live mounted set — and that is a correction, not a shortcut. The first
+  // attempt at this read `pi.getActiveTools()` here, which is wrong at exactly
+  // this point in the lifecycle: omp-telegram mounts `telegram_ask` in
+  // `before_agent_start` and takes it away again in `agent_end`
+  // (`restorePromptTools`), so it exists only *during* a turn. This runs between
+  // turns, composing the prompt that is about to start one, so the live set
+  // never contains the tool — a correctly configured fleet would have been told
+  // the approval was unavailable on every single tick, and the error line meant
+  // to flag a real fault would have fired 144 times a day saying nothing.
+  //
+  // What decides the mounting is knowable in advance and is shared with the
+  // status row, so the two cannot disagree: a locally injected tick has no
+  // `<telegram-message>` wrapper, so omp-telegram can only resolve a target
+  // through `notifyTarget()` — `notifyMode` plus a destination, both in the
+  // access file. Appended last, after the friction digest: the digest is what
+  // provokes an amendment, so the sentence saying the amendment cannot be
+  // approved here is the one that should read last.
+  //
+  // No access file configured means no fleet channel to judge, so nothing is
+  // claimed: the channel gate above already treats that as "not the fleet". A
+  // missing bot token is likewise not this check's business — it fails the
+  // channel gate outright, so a tick that reaches here can already send, and the
+  // only open question is whether an answer can come back.
+  const approval = config.accessFile === undefined ? undefined : readApprovalSurface(config.accessFile);
+  if (approval?.kind === "missing") {
     content = `${content}\n${TICK_APPROVAL_UNAVAILABLE_RULE}`;
     if (!session.approvalToolMissingLogged) {
       session.approvalToolMissingLogged = true;
@@ -1129,20 +1166,10 @@ function tick(pi: TickApi, ctx: TickContext, config: TickConfig, session: TickSe
       // inbound configured)` throughout the incident, so nothing else told the
       // operator the approval contract was unsatisfiable. A line buried at
       // info, beside one "tick sent" per interval, would not be found.
-      //
-      // It names the cause, not just the symptom, because the remedy is a file
-      // the operator owns: omp-telegram mounts the tool only for a turn whose
-      // prompt resolves a notify target, and a locally injected tick resolves
-      // one only through `notifyTarget()` — `notifyMode` "away" or "always",
-      // plus a destination.
-      pi.logger.error(
-        `[omp-conductor] ${TELEGRAM_APPROVAL_TOOL} is not mounted on this tick surface: omp-telegram mounts it ` +
-          "only for a turn that resolves a notify target, and a locally injected tick resolves one only when " +
-          `notifyMode is "away" or "always" with a destination (notifyChat, or topicsChat for a forum) in ` +
-          `${config.accessFile ?? "the omp-telegram access.json"} — until then ticks instruct the orchestrator ` +
-          "to deliver amendment questions with telegram_send and never to assume an answer",
-        { tool: TELEGRAM_APPROVAL_TOOL, ...(config.accessFile === undefined ? {} : { accessFile: config.accessFile }) },
-      );
+      pi.logger.error(`[omp-conductor] ${approval.reason}`, {
+        tool: TELEGRAM_APPROVAL_TOOL,
+        accessFile: config.accessFile,
+      });
     }
   }