omp-conductor 0.3.22 → 0.3.24

package/README.md

@@ -165,6 +165,22 @@ Also required on the host:
     writes `access.json`. The fleet heartbeat also reads that file and refuses to
     tick unless exactly one owner is paired, on the grounds that unattended
     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`. 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.
@@ -462,22 +478,34 @@ Four control planes used to answer "stop" differently. The package verbs:
 
 `omp-conductor board [--project NAME]` opens the same facts as a live terminal
 kanban instead of a scrolling wall of status text. Its columns are Queue,
-Claimed, Running, Green, Blocked, Failed, and Merged. Queue cards are the
-bounded per-issue hold sample recorded by the latest dispatch; the Queue count
-is the authoritative ready count even when there are more ready issues than
-sampled cards. Run columns show the newest attempt for each issue. Merged keeps
-only the last 24 hours so the board stays operational rather than becoming an
-analytics archive.
+Claimed, Running, Green, Blocked, Failed, Orphaned, Merged, and History.
+
+Every column is a claim about an issue's state **now**, and each issue appears
+in exactly one of them. Claimed, Running, and Green come from the store, because
+a live worker or an open pull request is the most current fact there is. Every
+stopped column comes from the labels the tracker carries right now: Queue is the
+queue label plus the latest tick's admission holds, Failed is the failed state
+label, Blocked is the blocked state label, and Orphaned is an issue the
+in-progress label still claims with no worker running it — a protected orphan
+whose worktree is kept because it may hold uncommitted work. So a requeued issue
+is queue work even when its last attempt failed, and a closed issue is not
+active work at all. Merged and History are the two backward-looking columns,
+both bounded to the last 24 hours and neither one an action list: History holds
+recently finished runs that no current label claims, so the board stays
+operational rather than becoming an analytics archive.
 
 The board refreshes run, spend, turn, and dispatch values from SQLite every
-second. It refreshes the slower daemon, Herdr, Telegram, and code-graph health
-layer every ten seconds or immediately with `r`. Use arrow keys or `h/j/k/l` to
-select a card, `Enter` to inspect and follow its worker transcript, `u` to run
-the normal unblock workflow, `i` / `p` to open the issue / pull request, `?` for
-help, and `q`, `Esc`, or `Ctrl-C` to go back and quit. Narrow terminals show a
-sliding subset of columns around the selection; terminals below 50×20 get a
-single resize instruction instead of a broken layout. The board is read-only
-except for the explicit `u` action: it never claims work or changes stages.
+second. It refreshes the slower daemon, Herdr, Telegram, code-graph, and tracker
+label layer every ten seconds or immediately with `r`; the header reports
+`tracker ok`, or how stale the label read is and why, so an empty Queue is never
+mistaken for an empty queue. Use arrow keys or `h/j/k/l` to select a card,
+`Enter` to inspect and follow its worker transcript, `u` to run the normal
+unblock workflow on a Blocked, Failed, or Orphaned card, `i` / `p` to open the
+issue / pull request, `?` for help, and `q`, `Esc`, or `Ctrl-C` to go back and
+quit. Narrow terminals show a sliding subset of columns around the selection;
+terminals below 50×20 get a single resize instruction instead of a broken
+layout. The board is read-only except for the explicit `u` action: it never
+claims work or changes stages.
 
 `halt --pane` is **fail-closed**: it exits `0` only when the conductor agent is
 *proven* gone. It writes the recovery pin first, so a failed stop still cannot be
@@ -518,7 +546,8 @@ Per tick, for the daemon's project:
    the independent head/check verification; green → `pushed-green`, red →
    `failed`, and still pending stays occupied. For every verified
    `pushed-green` run, ask what became of its PR. Merged → `merged`; closed
-   without merging → `failed`. Unknown answers leave the row unchanged. This
+   without merging → `failed`. Unknown answers leave the row unchanged. Every row
+   that settles also loses its `agent:in-progress` label. This
    maintenance runs even while dispatch is paused or workers are active, so
    status converges on the five-minute tick cadence. It also runs above admission
    so a row settled here frees its issue in the same tick. See
@@ -548,8 +577,12 @@ Per tick, for the daemon's project:
    survived step 8 — so at most one API call per free slot, never one per queued
    issue — the daemon asks whether an **open** PR already closes it. An open PR
    normally holds the issue. One narrow exception permits a routed continuation:
-   the PR URL must match the latest terminal run's retained PR exactly. Drafts
-   count because their branch can hold the only copy of the work.
+   the latest run must be terminal, and the open PR must be that run's retained
+   work — either the PR URL it recorded or a PR opened on the branch it retained.
+   The branch half matters because a run can be cap-killed before its worker ever
+   opens a PR, leaving a retained branch and no recorded URL; a PR pushed to that
+   branch afterwards is still the continuation target. Drafts count because their
+   branch can hold the only copy of the work.
    The tracker also finds work missing from a new, moved, restored, or cleared
    store. If the check fails, the candidate is **held**, not admitted, and
    retried next tick: the cost of holding is five minutes, the cost of admitting
@@ -583,13 +616,14 @@ Then, per admitted issue:
    | Outcome | Labels | Worktree | Escalation |
    | --- | --- | --- | --- |
    | `pushed-pending` | `agent:in-progress` stays while the daemon rechecks GitHub | removed | none |
-   | `pushed-green` | `agent:in-progress` stays until the merge closes the issue | removed | none |
+   | `pushed-green` | `agent:in-progress` stays while the PR is open | removed | none |
    | `blocked` | swapped to `agent:blocked` | removed | Tier 1 |
    | `failed` / `killed` | swapped to `agent:failed` | dirty tree committed to the branch, then retained until the PR or issue is terminal | Tier 1 |
    | unexpected error | swapped to `agent:failed` | same | Tier 1 |
 
    `pushed-pending` and `pushed-green` are not the end of the row: later ticks
-   verify outstanding checks and settle the PR once it resolves. See
+   verify outstanding checks and settle the PR once it resolves, and a row that
+   settles gives up its `agent:in-progress` label. See
    [what settles a green PR](#what-settles-a-green-pr).
 
    Label swaps add the new label before removing the old one: the reverse order
@@ -683,11 +717,18 @@ every pushed PR it is still holding:
 | could not be determined | unchanged | A flaky network, a revoked token, a deleted PR. An unknown answer never settles a row; the next tick asks again for free. |
 
 Run history is untouched. A PR closed without merging becomes a concrete failed
-attempt; a merge does not spend failure or continuation budget. A merge normally
-closes the issue, and a human who closed a PR is already looking at it, so what
-an issue's labels should say next remains the orchestrator's drain-duty
-judgement. One unreachable PR costs its own row and nothing else; the rest of
-the sweep still settles.
+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. 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
@@ -696,6 +737,12 @@ merged and whose issues were all closed, through two daemon restarts — and bec
 the active set *is* the busy set, those three issues were permanently unclaimable.
 A status page that has stopped being evidence is worse than no status page.
 
+The label half of that outlived the row half by two days. On 2026-08-09 a merged
+PR and a closed-unmerged one both settled their rows correctly and both left their
+issues carrying `agent:in-progress`, which eligibility reads as "a worker owns
+this" — with the brief forbidding the orchestrator from editing a state label and
+`unblock` declining to clear that one, neither issue could ever be claimed again.
+
 ### Continuation runs
 
 When a worktree is provisioned onto a branch that already exists in the mirror
@@ -960,7 +1007,9 @@ label on the issue, and eligibility reads any state label as disqualifying, so a
 answered issue that keeps one is never re-claimed and the answer is inert — nothing
 fails, the issue just stops existing as far as dispatch is concerned.
 [`omp-conductor unblock <issue>`](#cli-reference) is the way back: it clears the
-label through the same tracker the dispatcher writes with. The brief tells the
+label through the same tracker the dispatcher writes with, including
+`agent:in-progress` when the newest recorded run is terminal, since a terminal row
+is proof the worker process is gone. The brief tells the
 orchestrator to run that verb rather than edit the label itself, and that is not a
 formality — orphan detection works by comparing `agent:in-progress` labels against
 live runs, and it is only trustworthy while every state label on the tracker was
@@ -1219,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
@@ -1350,7 +1409,7 @@ omp-conductor help
 | `restart` | Prefer `systemctl restart` when the unit owns the live pid so the replacement stays supervised; otherwise `stop` then `start`, inheriting the running daemon's port and project unless a flag overrides them. The new process **salvages dirty live worktrees before orphaning** those rows — see [Deploying a new package onto a busy fleet](#deploying-a-new-package-onto-a-busy-fleet). |
 | `upgrade [--to VERSION] [--project NAME]` | Deterministically update the Bun-global CLI, omp plugin, Herdr recovery plugin, and managed brief as one release. Resolves the npm version and exact `gitHead`, pauses only new claims, drains active workers, installs all surfaces, reloads Herdr and the daemon, waits for pane recovery, verifies identities and fleet health twice, then restores the original dispatch state. A no-op when already current. Failure leaves dispatch paused. Must run outside a Herdr-managed session. |
 | `status [--project NAME]` | Layered fleet report first: `dispatch` / `ticks` / next scheduled tick / `pane` / `recovery` / `herdr` / `telegram` / optional `code graph` / `daemon`, then the project body. The project body includes the latest completed dispatch timestamp, ready/routed/admitted counts, and bounded hold groups; API failures are marked `DEGRADED` so queue starvation cannot look idle. The next tick comes from the live heartbeat process, not a guess from log timestamps. Telegram health uses `getMe` to prove API authentication without sending a message and reports inbound bridge configuration separately. Configured graphs report prerequisites, indexed repos, timer state, and refresh freshness without blocking dispatch. The daemon block includes `rss` from `/healthz`; live workers add a busy-deploy warning. A `.conductor-stalled` marker adds an `orchestrator STALLED since …` line. |
-| `board [--project NAME]` | Live keyboard-driven kanban over the same SQLite and `/healthz` truth as `status`: Queue, Claimed, Running, Green, Blocked, Failed, and the last 24 hours of Merged. Refreshes run/spend/turn values every second and slower health every ten seconds. `Enter` follows the selected transcript in place; `u` invokes the existing unblock workflow; `i` / `p` open the issue / PR; `r` refreshes health; `?` shows all keys. Requires an interactive terminal of at least 50×20. |
+| `board [--project NAME]` | Live keyboard-driven kanban over the same SQLite and `/healthz` truth as `status`, plus the tracker's current labels: Queue, Claimed, Running, Green, Blocked, Failed, Orphaned, and the last 24 hours of Merged and History. Columns are mutually exclusive and describe current state, not the newest run row, so a requeued issue is queued rather than failed and a closed issue is neither. Refreshes run/spend/turn values every second, and health plus the label read every ten seconds. `Enter` follows the selected transcript in place; `u` invokes the existing unblock workflow on a Blocked, Failed, or Orphaned card; `i` / `p` open the issue / PR; `r` refreshes health; `?` shows all keys. Requires an interactive terminal of at least 50×20. |
 | `hold [--project NAME]` | Soft stop: pause claiming **and** disarm ticks. Daemon and pane stay up. Prefer this over `pause` when the intent is "stop the conductor" without killing processes. See [Stop the conductor](#stop-the-conductor-hold--halt). |
 | `halt [--pane] [--project NAME]` | `hold`, then stop the dispatch daemon (systemctl-aware). Pane stays up unless `--pane` is passed. `halt --pane` also pins herdr-conductor recovery off for the conductor agent only — it does **not** stop `herdr-fleet.service` or any other herdr session. Fail-closed: exits nonzero unless the agent is proven gone. |
 | `arm [--project NAME]` | Proof-gated: send a Telegram challenge and write the arm marker only after your reply appears as a user turn in the orchestrator transcript. Never auto-armed by `resume` / `hold`. |
@@ -1358,7 +1417,7 @@ omp-conductor help
 | `release-pane [--project NAME]` | Clear the `halt --pane` recovery pin so herdr-conductor may resume the fleet agent again. |
 | `tail <issue>` | Follow the newest run for that issue: the worker's assistant text as `assistant: …` and each tool it calls as `tool: <name>`, printed as they land. Workers are omp sessions inside the daemon rather than terminals, so this is the only way to watch one live — a herdr pane running it becomes an observation window. Starts from the top of the transcript, not the end, so attaching to a run that is already ten turns in shows those ten turns. Exits `1` with `no run recorded for #N` when the issue has never been dispatched, or `no transcript yet (state: …)` when the attempt has not opened one. Otherwise it runs until `Ctrl-C`, or until the run has finished and its transcript has been silent for five seconds, and prints `run ended: <state>`. |
 | `extend <issue> --turns N [--project NAME]` | Monotonically raise that live worker's effective turn ceiling through its owning daemon. The current omp session keeps running; no restart or continuation is created. The daemon persists the new ceiling for `status` and rejects missing, settled, cap-killed, equal, or lower requests instead of implying that an immutable session changed. |
-| `unblock <issue>` | Remove that issue's `blocked` and `failed` labels so an answered escalation can be claimed again. `agent:in-progress` is never touched. Run history remains intact: blocks consume the independent continuation budget, not failed implementation attempts. The output reports both budgets and warns when either will make the next tick escalate instead of dispatch. Exits `2` when the issue number is missing or malformed. |
+| `unblock <issue>` | Remove that issue's `blocked` and `failed` labels so an answered escalation can be claimed again. `agent:in-progress` comes off too, but only when the newest recorded run is terminal — that row is the proof no worker still owns the issue, so a live run keeps the label, and so does an issue with no run row at all. Run history remains intact: blocks consume the independent continuation budget, not failed implementation attempts. The output reports both budgets and warns when either will make the next tick escalate instead of dispatch. Exits `2` when the issue number is missing or malformed. |
 | `friction <kind> --detail TEXT [--issue N]` | Record one bounded judgment the daemon cannot infer: an escalation belonged in a digest, or a tick report was noise/surprising. The detail is limited to 160 characters. One event never changes policy; three observations inside seven days make the aggregate eligible for one Learning-loop prompt, followed by a seven-day cooldown. |
 | `daemon` | Run the loop in the **foreground**, ticking every 5 minutes and serving `/healthz`. Admitted workers run in a tracked background pool, so settlement and capacity checks remain periodic while they work; shutdown drains the pool before closing the store. This is what `start` launches and what a systemd unit should call. |
 | `daemon --once` | Run a single tick, wait for workers admitted by that tick, and exit. No HTTP server or pidfile — a drill must not register itself as the daemon, or the next reader believes it and the real daemon's in-flight runs get reconciled as orphans. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.3.22",
+  "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" };
+}