omp-conductor 0.5.6 → 0.6.0

package/README.md

@@ -204,6 +204,26 @@ Also required on the host:
     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.
 
+  - **A fleet that answers instead of narrating** needs one key, set once:
+    `/telegram set profile daemon` (omp-telegram 0.11.0 or newer). Without it the
+    bridge behaves as it does on a laptop: it finalizes a real Telegram message
+    per assistant turn for as long as a conversation is active — so one answer
+    arrives as several messages, and a message that lands mid-tick keeps relaying
+    that tick's internal turns — and it posts every local run's closing text to
+    `notifyChat`, which on a host whose runs are heartbeat ticks means each tick's
+    working prose. The profile switches all of it off at the transport: text
+    reaches Telegram only through `telegram_send` / `telegram_ask`, the idle post
+    is suppressed, and `telegram_ask` stays mounted and aimed at the paired owner
+    on every turn — including a locally injected tick, so it also removes the need
+    for `notifyMode` above. Approval and blocked-input pings still fire; those
+    mean a human is needed, which is the point of the channel.
+
+    `omp-conductor status` reports an interactive profile on the `telegram` row,
+    and every tick composed on one carries a prompt line saying so. Note the two
+    settings pull against each other before the profile exists: setting
+    `notifyMode` to make `telegram_ask` mountable is exactly what arms the idle
+    post, so the correctly askable fleet was also the loud one.
+
   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.
 

package/package.json

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

@@ -33,6 +33,17 @@
  * 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.
+ *
+ * Since omp-telegram 0.11.0 there is a second way for a locally injected turn to
+ * resolve a target, and it counts here for the same reason the legacy boolean
+ * does: `profile: "daemon"` makes `notifyTarget()` resolve without `notifyMode`
+ * at all, because the profile *is* the headless contract — explicit-only
+ * outbound, no idle notify post, and `telegram_ask` targeted at the paired owner
+ * on every turn including a cron tick. A fleet carrying it has the surface #114
+ * was about, so demanding `notifyMode` beside it would be the false alarm this
+ * file exists to avoid. The `notifyMode` paths are all still live: an older
+ * plugin ignores the `profile` key entirely, and a host running one keeps
+ * working unchanged.
  */
 
 import { readFileSync } from "node:fs";
@@ -46,6 +57,16 @@ export const TELEGRAM_APPROVAL_TOOL = "telegram_ask";
 
 export type ApprovalSurface = { kind: "ready" } | { kind: "missing"; reason: string };
 
+/** Whether the Telegram bridge is running the headless contract, or merely
+ *  configured well enough to answer a question.
+ *
+ *  Two questions, not one, which is why this is a separate answer from
+ *  {@link ApprovalSurface}: a fleet can be perfectly *askable* and still be
+ *  narrating every turn into its operator's chat. `interactive` carries the
+ *  reason because both readers of it — a tick prompt and a status row — have to
+ *  name the remedy, and one spelling of it keeps them in agreement. */
+export type DaemonProfileSurface = { kind: "daemon" } | { kind: "interactive"; 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
@@ -156,7 +177,20 @@ export function readApprovalSurface(path: string): ApprovalSurface {
     };
   }
   const mode = field(access, "notifyMode");
-  const active = mode === "away" || mode === "always" || field(access, "away") === true;
+  // Three spellings of the same fact, and none of them is redundant.
+  // `notifyMode` is what an interactive host sets; `away: true` is the retired
+  // boolean `loadAccess()` migrates on read; `profile: "daemon"` is the headless
+  // contract, which omp-telegram ≥ 0.11.0 treats as its own reason to resolve a
+  // notify target (`notifyTarget()` gates on `notifyMode || profile === "daemon"`
+  // and `before_agent_start` mounts `telegram_ask` on the same disjunction). A
+  // daemon-profile fleet with no `notifyMode` is therefore *more* answerable than
+  // the configuration #114 asked for, not less, and reporting it broken would be
+  // the every-interval false alarm this file was written to prevent.
+  const active =
+    mode === "away" ||
+    mode === "always" ||
+    field(access, "away") === true ||
+    field(access, "profile") === "daemon";
   if (!active) {
     return {
       kind: "missing",
@@ -251,3 +285,58 @@ export function readApprovalSurface(path: string): ApprovalSurface {
   }
   return { kind: "ready" };
 }
+
+/**
+ * Reads the same access file and answers the other question: does visible
+ * assistant text stay out of the operator's chat?
+ *
+ * A separate read rather than a field on {@link ApprovalSurface}, because the
+ * two faults have different remedies and a caller may care about only one. This
+ * one is about *noise*: without the profile, omp-telegram relays a real Telegram
+ * message per assistant turn for as long as a conversation is marked active
+ * (`outbound.ts` `onTurnEnd`), and — because the fleet sets `notifyMode` for the
+ * approval surface above — posts every local run's closing text to the notify
+ * chat from its `agent_end` handler. So a correctly *askable* fleet is exactly
+ * the one that narrates: the two settings pull against each other, which is why
+ * both are checked and only the profile silences the second.
+ *
+ * One key decides it, deliberately. `profile: "daemon"` is omp-telegram ≥ 0.11.0's
+ * whole headless contract — explicit-only outbound, no idle/final notify post,
+ * `telegram_ask` targeted at the paired owner on every turn — so verifying it is
+ * one comparison rather than three inferences about `streaming`, `notifyMode` and
+ * turn origin that would drift the moment the plugin changes. Anything other
+ * than the literal string is `interactive`: `loadAccess()` drops every other
+ * value to undefined, so `"DAEMON"` and `5` are not the contract on the host
+ * either, and reporting them as one would promise a suppression nothing applied.
+ *
+ * Never throws, and never writes: conductor reads this file, the operator's
+ * `/telegram set profile daemon` is what changes it. An unreadable or corrupt
+ * file answers `interactive` for the reason the whole module fails closed — a
+ * green signal over an unproven contract is what #114 was.
+ */
+export function readDaemonProfile(accessPath: string): DaemonProfileSurface {
+  const remedy = "assistant text can auto-relay to Telegram — run `/telegram set profile daemon`";
+  let access: unknown;
+  try {
+    access = JSON.parse(readFileSync(accessPath, "utf8"));
+  } catch {
+    return {
+      kind: "interactive",
+      reason: `cannot read or parse ${accessPath}, so no telegram profile is proven; ${remedy}`,
+    };
+  }
+  if (access === null || typeof access !== "object" || Array.isArray(access)) {
+    return {
+      kind: "interactive",
+      reason: `${accessPath} is not an object, so no telegram profile is proven; ${remedy}`,
+    };
+  }
+  const profile = field(access, "profile");
+  if (profile === "daemon") return { kind: "daemon" };
+  // An absent key reads as "default" rather than "undefined": that is the word
+  // the plugin's own `/telegram status` line and its `profile: daemon | default`
+  // help text use, and an operator matching a status row against this reason
+  // should not have to translate.
+  const observed = profile === undefined ? "default" : JSON.stringify(profile);
+  return { kind: "interactive", reason: `telegram profile is ${observed}; ${remedy}` };
+}

package/src/briefs/orchestrator.md

@@ -208,18 +208,23 @@ sent that way is undetectable when it does not arrive.
 
 ## Human messages
 
-A human writing to you between ticks is not a tick. Answer the question they
-actually asked, in one message, from evidence you already hold or go and fetch.
-
-Then stop. Do not continue loop narration in the same reply, and do not restate
-in-progress work unless they asked for it. The loop resumes on the next tick.
+A human writing to you between ticks is not a tick. Answer with a **single
+`telegram_send` call** — one message, the answer only, from evidence you already
+hold or go and fetch. Never answer as plain end-of-turn text: on this session,
+text you merely write reaches nobody — if you do not call `telegram_send`, the
+person gets silence. While handling any turn, produce no visible commentary
+between tool calls — reasoning stays in thinking, actions stay in tools.
+
+If the answer needs a decision from the operator (a choice, a yes/no, an
+approval), ask it with `telegram_ask` — never a numbered-options message via
+`telegram_send`, and never the generic `ask` UI. A cancelled or errored
+`telegram_ask` is a delivery failure, not an answer.
 
 A message may also reach you **mid-tick** (delivery is steering: it arrives
 between two of your tool calls). Treat it as an interrupt, not a new tick:
-answer it immediately with `telegram_send` in one message, then return to the
-duty you were in the middle of and finish it. Never abandon or restart the tick
-because a message arrived, and never batch the answer "for the report" — the
-person is waiting now.
+`telegram_send` the answer immediately, then return to the duty you were in the
+middle of and finish it. Never abandon or restart the tick because a message
+arrived, and never batch the answer "for the report" — the person is waiting now.
 
 ## Escalation tiers
 

package/src/briefs/policy.md

@@ -74,10 +74,11 @@ Your report scope is **`{{REPORT_SCOPE}}`**. All three scopes, spelled out:
   issue you pulled off the queue, a cap that stopped the fleet. A tick where
   nothing changed still says nothing — "no change" is not an event.
 
-**Delivery.** Your end-of-turn text reaches your operator only on a turn that
-*began* as an inbound Telegram message. A tick did not: it is injected locally,
-so a report you merely write at the end of one is read by nobody, however well
-you wrote it. Hand every reportable event to the conductor's outbox instead:
+**Delivery.** Never rely on end-of-turn text reaching anyone. The only delivery
+paths are `omp-conductor report` (reports — persisted, daemon-retried),
+`telegram_send` (a person who is waiting), and `telegram_ask` (a decision).
+Everything else is noise or silence. Hand every reportable event to the
+conductor's outbox:
 
 ```
 omp-conductor report --text "<the whole report>"          # a material event

package/src/fleet.ts

@@ -29,7 +29,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { findProject, loadConfig, stateDir } from "./config.ts";
 import { planUsageLine, readPlanUsage, sharedUsageSource } from "./usage.ts";
-import { readApprovalSurface } from "./approval-surface.ts";
+import { readApprovalSurface, readDaemonProfile } from "./approval-surface.ts";
 import { inspectBriefLayout } from "./brief-upgrade.ts";
 import { dbPath, openStore } from "./store.ts";
 import { renderBriefForProject } from "./setup.ts";
@@ -1303,6 +1303,24 @@ export async function probeTelegramHealth(
   if (approval.kind === "missing") {
     return { kind: "degraded", detail: `${username}; inbound configured; ${approval.reason}` };
   }
+  // Last, and only once the surface is answerable: whether it is *quiet*.
+  //
+  // The order is the order an operator should fix things in, and one row carries
+  // one remedy. A missing token means nothing outbound works, so the approval
+  // surface is not worth discussing; a missing approval surface means an
+  // amendment cannot be asked, which outranks noise; an interactive profile is
+  // real but strictly the least severe — the fleet works, it is just loud. And
+  // the two lower checks are not independent of each other: setting `notifyMode`
+  // to fix the approval surface is what *arms* the `agent_end` notify post this
+  // one warns about, so a fleet that fixes them in the other order would see the
+  // noise appear as the reward for fixing the silence.
+  const profile = readDaemonProfile(accessPath);
+  if (profile.kind === "interactive") {
+    return {
+      kind: "degraded",
+      detail: `${username}; inbound configured; interactive profile relays assistant text — /telegram set profile daemon`,
+    };
+  }
   return { kind: "ok", detail: `${username}; inbound configured; telegram_ask available` };
 }
 

package/src/orchestrator-tick.ts

@@ -52,6 +52,7 @@ import {
   bridgeTokenBound,
   hasBotToken,
   readApprovalSurface,
+  readDaemonProfile,
   TELEGRAM_APPROVAL_TOOL,
 } from "./approval-surface.ts";
 import {
@@ -363,12 +364,27 @@ export const TICK_SCOPE_CONSTRAINTS: { readonly [K in ReportScope]: string } = {
 /**
  * The delivery clause, appended to every default tick prompt.
  *
- * End-of-turn text streams to the operator's Telegram only on a turn that
- * *began* as an inbound Telegram message. A heartbeat tick is injected locally,
- * so it is never such a turn, and a session that believes otherwise reports
- * into a void: on 2026-08-06 the fleet this extension runs produced a release
- * report and two tier-2 escalations as end-of-turn text, and not one of the
- * three reached anybody.
+ * A tick's end-of-turn text does not reach the operator as a *report*, and the
+ * rule's job is to stop a session believing otherwise: on 2026-08-06 the fleet
+ * this extension runs produced a release report and two tier-2 escalations as
+ * end-of-turn text, and not one of the three reached anybody.
+ *
+ * This comment used to explain that by saying end-of-turn text streams to
+ * Telegram only on a turn that *began* as an inbound Telegram message. That
+ * premise is false, and the correction matters because it flips the reason:
+ * omp-telegram's `agent_end` handler posts `finalText` to the notify chat on
+ * every run that did *not* come from Telegram, whenever `notifyMode` is set —
+ * and the fleet must set it, because {@link readApprovalSurface} needs it for
+ * the approval surface. So a tick's closing prose *was* reaching the operator
+ * all along: not as a delivered report, as an unlogged, unretried, untracked
+ * ping in the middle of whatever else was in that chat. Both the void and the
+ * ping are the same fault seen from two sides — text is not a delivery channel.
+ *
+ * omp-telegram 0.11.0's `profile: "daemon"` removes it in the other direction:
+ * explicit-only outbound, and the idle/final notify post suppressed outright, so
+ * a tick's visible text goes nowhere at all. That is the configuration the fleet
+ * runs (see {@link TICK_NARRATION_RULE}, which warns when it is absent), and it
+ * makes this rule's demand literal rather than merely prudent.
  *
  * The clause used to name `telegram_send`, and that held — but it was still an
  * instruction where a mechanism was needed: the same miss recurs whenever the
@@ -418,6 +434,38 @@ export const TICK_APPROVAL_UNAVAILABLE_RULE =
   `If you have an amendment to propose, deliver the question with telegram_send and wait for your operator's reply on a later turn; ` +
   `never apply an amendment, or record one as approved, without an explicit answer you actually received.`;
 
+/**
+ * Appended to every tick — the shipped prompt or the operator's own — composed
+ * on a bridge that is not in omp-telegram's `profile: "daemon"`.
+ *
+ * The running commentary an operator sees is *mechanical*, not disobedience, and
+ * that is why a prompt line is the wrong permanent fix and the right interim one.
+ * Two verified paths carry visible text out without anyone calling a tool:
+ * `outbound.ts` `onTurnEnd()` finalizes one real Telegram message per assistant
+ * turn for as long as the chat is marked active — so a multi-step answer arrives
+ * as several messages, and a message that lands mid-tick keeps the chat active
+ * for the rest of that run, relaying every subsequent tick-internal turn — and
+ * the `agent_end` handler posts the closing text of every *local* run to the
+ * notify chat whenever `notifyMode` is set. The fleet has to set `notifyMode`
+ * (see {@link TICK_APPROVAL_UNAVAILABLE_RULE}), so the correctly-askable fleet is
+ * exactly the narrating one. `profile: "daemon"` closes both at the transport:
+ * explicit-only outbound, notify post suppressed.
+ *
+ * So this rule is a stopgap with an expiry date, and it says so: it names the
+ * one command that removes it. Until then the only defence is discipline the
+ * turn can actually exercise — no visible text between tool calls, and one
+ * `telegram_send` for a human answer rather than prose that leaks a turn at a
+ * time. It fires *because* the mechanism is absent, so a fleet that has run
+ * `/telegram set profile daemon` never sees it.
+ *
+ * Appended to a configured `message` too, for {@link TICK_APPROVAL_UNAVAILABLE_RULE}'s
+ * reason exactly: an operator's prompt owns the reporting contract, but it cannot
+ * consent on the orchestrator's behalf to what the transport does with its text.
+ * Transport truth is not the operator's prompt to waive.
+ */
+export const TICK_NARRATION_RULE =
+  "This session's Telegram bridge is NOT in daemon profile, so visible assistant text can auto-relay to your operator's chat (per-turn messages while a Telegram conversation is active, and end-of-run notify posts on local runs). Until the operator runs `/telegram set profile daemon`: produce no visible text between tool calls, and answer any human message with a single telegram_send call only.";
+
 function frictionLabel(kind: FrictionSignal["kind"]): string {
   if (kind.startsWith("admission:")) return `admission hold ${kind.slice("admission:".length)}`;
   if (kind === "feedback:escalation-should-digest") return "escalations classified as digest material";
@@ -1254,6 +1302,28 @@ function tick(pi: TickApi, ctx: TickContext, config: TickConfig, session: TickSe
     }
   }
 
+  // The other half of transport truth, read from the same file at the same
+  // moment: whether visible text stays out of the operator's chat. Appended
+  // after the approval line because it is the weaker instruction of the two —
+  // the approval rule stops an invented approval, this one asks the turn to keep
+  // quiet — and a prompt should end on the sentence that must not be missed.
+  //
+  // Gated on `bridgeTokenAtStart` for the same reason the approval read is, and
+  // the reasoning is the mirror image of it: with no token bound, omp-telegram
+  // sends *nothing*, so the two relay paths this rule warns about cannot fire
+  // either. A narration warning on a dead bridge would describe a hazard that
+  // does not exist, on top of an approval warning that already names the one
+  // command worth running (`/telegram on`) — two remedies on one prompt, and the
+  // operator acts on neither. So the rule fires only where the leak is real: a
+  // live bridge whose profile is not `daemon`.
+  //
+  // No `accessFile` means no fleet bridge to judge, exactly as above.
+  const profile =
+    config.accessFile === undefined || !session.bridgeTokenAtStart
+      ? undefined
+      : readDaemonProfile(config.accessFile);
+  if (profile?.kind === "interactive") content = `${content}\n${TICK_NARRATION_RULE}`;
+
   try {
     pi.sendMessage(
       { customType: TICK_CUSTOM_TYPE, content, display: true, attribution: "user" },