omp-conductor 0.20.0 → 0.20.2

package/src/graph-health.ts

@@ -52,7 +52,10 @@ export type CodeGraphHealth =
         active: "active" | "inactive" | "unknown";
       };
       refresh: {
-        result: "success" | "failed" | "unknown";
+        /** "running": the oneshot is executing right now (#1090). systemd has
+         *  already cleared the previous exit timestamp mid-run, so this is a
+         *  progress report — never a claim about staleness or absence. */
+        result: "success" | "failed" | "running" | "unknown";
         fresh: boolean | null;
         lastSuccessAt?: string;
         ageMs?: number;
@@ -208,6 +211,12 @@ function refreshResult(result: ReadOnlyCommandResult, now: number): RefreshResul
   const serviceResult = fields.get("Result");
   const exitStatus = fields.get("ExecMainStatus");
   const completedAt = fields.get("ExecMainExitTimestamp");
+  // #1090: an empty ExecMainExitTimestamp says "no completed run yet", which
+  // is equally true of a unit that has never run and of one executing right
+  // now — systemd clears it when the next run starts. ActiveState comes back
+  // from the same single `systemctl show` and separates the two; evidence
+  // captured without the property keeps the conservative pre-#1090 reading.
+  const activeState = fields.get("ActiveState");
   if (serviceResult === undefined || exitStatus === undefined || completedAt === undefined) {
     return unknown("refresh service returned an unrecognized result", true);
   }
@@ -219,6 +228,12 @@ function refreshResult(result: ReadOnlyCommandResult, now: number): RefreshResul
     };
   }
   if (completedAt === "" || completedAt === "n/a") {
+    if (activeState === "activating" || activeState === "active") {
+      // There is no completed timestamp to measure staleness against yet, but
+      // this is progress, not absence: the reindex is keeping the graph fresh
+      // at this moment, so neither the row nor the previous message degrades.
+      return { health: { result: "running", fresh: null }, uncertain: false };
+    }
     return unknown("no successful refresh has been recorded", false);
   }
   const completedMs = Date.parse(completedAt);
@@ -290,6 +305,7 @@ export async function probeCodeGraph(
       "--property=Result",
       "--property=ExecMainStatus",
       "--property=ExecMainExitTimestamp",
+      "--property=ActiveState",
     ]),
   ]);
 

package/src/groom.ts

@@ -114,6 +114,17 @@ export interface ReadyGateRejection {
  * {@link toSpecDurableVerdict} still recovers the verdict and the candidate is
  * not re-groomed — the spec is rejected, not ungroomed.
  *
+ * That durability is bounded by the verdict itself (#1060). A rejection
+ * beside a verdict the contract still accepts is not re-groomable, because
+ * the fault lies in the issue — missing criteria, a missing lane — and only
+ * an edit to the issue can fix it. A rejection beside a verdict the contract
+ * refuses — veltro#731's prose lane entry, persisted before parse-time lane
+ * validation — reads as not-durable through {@link toSpecDurableVerdict},
+ * and the candidate becomes re-groomable: no issue edit can ever satisfy a
+ * gate whose refusal is baked into the verdict, and complying with the
+ * refusal's remedy would write the unusable entry into the issue itself, so
+ * a fresh pass is the only repair.
+ *
  * Fails closed on anything it cannot read: an empty `missing` array is not a
  * rejection (a gate that found nothing missing passed), and a non-string entry
  * would render as `undefined` in a digest line an operator is asked to act on.

package/src/orchestrator-tick.ts

@@ -46,7 +46,7 @@
 
 import { createHash, randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { availabilityPrompt, interruptDisposition } from "./availability.ts";
 import {
@@ -132,6 +132,20 @@ import {
   type ToSpecTrackerSeam,
 } from "./groom.ts";
 import { heldNoticeId } from "./notices.ts";
+import {
+  clearArmTransaction,
+  expiredArmChallenges,
+  FLEET_ARM_KEY,
+  resolveArmReply,
+  type ArmChallengeSighting,
+  type ArmReplyMatch,
+} from "./arm-challenge.ts";
+import {
+  readTelegramChannel,
+  readTelegramToken,
+  resolveProjectTopicId,
+  sendTelegram,
+} from "./escalate.ts";
 
 /** The activation file. Absent means "this is not an orchestrator session". */
 export const TICK_CONFIG_FILE = ".conductor-tick.json";
@@ -489,6 +503,10 @@ const AUTONOMOUS_RECOVERY_ACTIONS: Record<RecoveryAction, boolean> = {
   "rerun-checks": true,
   settle: true,
   escalate: false,
+  // An observation row never stamps `recoveredAt` (the recovery IS the later
+  // sweep pass), so it never lands in this digest; `false` is the honest value
+  // if one ever did — it is not "already handled", it is waiting (#1068).
+  observe: false,
   hold: false,
   none: false,
 };
@@ -1638,6 +1656,20 @@ export function resolveArmState(armedFile: string, projectName?: string): ArmSta
   return shared ? { armed: true } : { armed: true, legacy: "honoured" };
 }
 
+/**
+ * The one armed-marker write both settlement paths share — the CLI's
+ * `arm --reply` half and the orchestrator session's mechanical reply consumer
+ * (#1061): same content, same mode, and the same restamp of the pre-per-project
+ * shared marker the heartbeat still honours (#316). It lives here, beside
+ * {@link resolveArmState}, so the session consumer can write the gate it reads
+ * — the reverse import (into `fleet.ts`) would cycle.
+ */
+export function writeArmedMarker(path: string, owner: string, arm: ArmState): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `armed ${new Date().toISOString()} owner=${owner}\n`, { mode: 0o600 });
+  if (arm.legacy === "honoured") rmSync(legacyArmedMarkerPath(), { force: true });
+}
+
 /**
  * Best-effort recompose of `ORCHESTRATOR.md` from the installed package floor +
  * live `POLICY.md`.
@@ -2854,6 +2886,7 @@ async function tick(
   config: TickConfig,
   session: TickSession,
   toSpecTrackerSeam: ToSpecTrackerSeam | undefined,
+  armSeam: ArmConsumerSeam | undefined,
 ): Promise<void> {
   const live = currentConfig(ctx.cwd, config);
   const arm = live.armedFile === undefined ? undefined : resolveArmState(live.armedFile, live.project);
@@ -2863,6 +2896,29 @@ async function tick(
       `[omp-conductor] ${legacyArmedMarkerPath()}: ${LEGACY_ARM_MARKER_DETAIL} — this heartbeat stays disarmed`,
     );
   }
+  // An unanswered ceremony that passed its window is a dead ceremony, not a
+  // silent one (#1061): the tick that notices tells the operator why and how
+  // to re-run it, on the surface the challenge was sent to. Deliberately
+  // before the tick gate — a disarmed fleet is exactly the state an
+  // unanswered challenge leaves, and its death notice must not wait for an
+  // arm to be heard. The scan is synchronous so an idle host (no expired
+  // records) costs the tick nothing; only a send is awaited.
+  const armNow = (armSeam?.now ?? Date.now)();
+  for (const expired of expiredArmChallenges(live.project, armNow)) {
+    const surface: ArmNoticeSurface = { accessFile: live.accessFile, project: live.project };
+    const send = armSeam?.notify ?? sendArmNotice;
+    try {
+      await send(armExpiryNotice(expired, live.project), surface);
+    } catch (err) {
+      // Keep the record: the next heartbeat retries, and `doctor` still
+      // reports it.
+      pi.logger.error(
+        `[omp-conductor] arm expiry notice not delivered: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      continue;
+    }
+    clearArmTransaction(expired.key, expired.id);
+  }
   const decision = tickDecision({
     armed: arm === undefined || arm.armed,
     channelOk: live.accessFile === undefined || channelIsUp(live.accessFile),
@@ -3371,11 +3427,12 @@ function armTickHeartbeat(
   config: TickConfig,
   session: TickSession,
   toSpecTrackerSeam: ToSpecTrackerSeam | undefined,
+  armSeam: ArmConsumerSeam | undefined,
 ): void {
   writeTickRuntimeStatus(pi, ctx.cwd, config.intervalSeconds);
   const runScheduledTick = async (): Promise<void> => {
     try {
-      await tick(pi, ctx, config, session, toSpecTrackerSeam);
+      await tick(pi, ctx, config, session, toSpecTrackerSeam, armSeam);
     } finally {
       writeTickRuntimeStatus(pi, ctx.cwd, config.intervalSeconds);
     }
@@ -3431,7 +3488,7 @@ function armTickHeartbeat(
   // call runs inside the session_start handler dispatch, which cannot see an
   // async rejection — an escaped one reaches the process-level
   // unhandledRejection handler and takes the session down.
-  void tick(pi, ctx, config, session, toSpecTrackerSeam).catch((err) => {
+  void tick(pi, ctx, config, session, toSpecTrackerSeam, armSeam).catch((err) => {
     pi.logger.error(
       `[omp-conductor] arm-time tick failed: ${err instanceof Error ? err.message : String(err)}`,
     );
@@ -3496,6 +3553,215 @@ export interface OrchestratorTickExtensionOptions {
    * present-tense empty queue.
    */
   toSpec?: { tracker?: ToSpecTrackerSeam };
+  /**
+   * The arm ceremony's mechanical consumer seams (#1061). Production omits
+   * them and the extension classifies inbound turns against the pending
+   * challenge records itself, sending confirmations and expiry notices over
+   * the same bridge transport `armTicks` sends the challenge on. Tests inject
+   * a recorder (`notify`) and a fixed clock (`now`) so the settle and the
+   * notices are provable without Telegram or timers.
+   */
+  arm?: {
+    now?: () => number;
+    notify?: ArmNoticeFn;
+  };
+}
+
+/** The send surface an arm notice rides: the live tick config's channel and project. */
+export interface ArmNoticeSurface {
+  accessFile?: string;
+  project?: string;
+}
+
+/**
+ * One mechanical Telegram send the arm consumer raises: the confirmation when
+ * a reply settles the ceremony, or the expiry notice when a challenge dies
+ * unanswered. The default is {@link sendArmNotice}; tests record instead.
+ */
+export type ArmNoticeFn = (text: string, surface: ArmNoticeSurface) => Promise<void> | void;
+
+/** The consumer's injectable clock and transport, carried into the tick's helpers. */
+export interface ArmConsumerSeam {
+  now?: () => number;
+  notify?: ArmNoticeFn;
+}
+
+/**
+ * The plain text of an inbound message, for the arm classifier. Content blocks
+ * join with newlines so a code split across block boundaries still tokenises
+ * whole; non-text blocks contribute nothing. `undefined` for an absent or
+ * empty message, which is ordinary chat either way.
+ */
+function inboundMessageText(content: readonly { type?: string; text?: string }[] | undefined): string | undefined {
+  if (content === undefined || content.length === 0) return undefined;
+  const text = content.map((block) => block.text ?? "").join("\n");
+  return text.length === 0 ? undefined : text;
+}
+
+/**
+ * The ready-to-send expiry notice: the reason — never answered, or answered
+ * but never settled — and the exact command that re-runs the ceremony. The
+ * code is the proof and is never named in a notice; only the window is.
+ */
+function armExpiryNotice(expired: { key: string; sighting: ArmChallengeSighting }, project: string | undefined): string {
+  const reissue =
+    expired.key === FLEET_ARM_KEY || project === undefined || project === ""
+      ? "omp-conductor arm"
+      : `omp-conductor arm --project ${project}`;
+  const sentAt =
+    expired.sighting.sentAt === undefined
+      ? ""
+      : ` sent ${new Date(expired.sighting.sentAt).toISOString()}`;
+  const reason =
+    expired.sighting.acknowledgedAt === undefined
+      ? `The arming challenge${sentAt} expired without being answered — nothing is armed.`
+      : `The arming challenge${sentAt} was answered but never settled before its window closed — nothing is armed.`;
+  return `${reason} Send a fresh one: ${reissue}`;
+}
+
+/**
+ * The default transport for the arm consumer's confirmation and expiry
+ * notices: the same bot token, paired channel and project topic `armTicks`
+ * sends the challenge on, so the notice lands on the surface the operator was
+ * asked in. Deliberately not availability-gated — the ceremony is the
+ * operator's own interaction, exactly like the challenge send itself, and a
+ * notice held for quiet hours would be the silent failure #1061 removes. Any
+ * missing or down fact throws; the caller logs and keeps the challenge record
+ * so the next heartbeat retries and `doctor` still reports it.
+ */
+export async function sendArmNotice(text: string, surface: ArmNoticeSurface): Promise<void> {
+  if (surface.accessFile === undefined) {
+    throw new Error("no accessFile — the arm notice has no channel");
+  }
+  const channel = readTelegramChannel(surface.accessFile);
+  if (channel.kind === "down") {
+    throw new Error(`escalation channel is not up (${surface.accessFile}): ${channel.reason}`);
+  }
+  const token = readTelegramToken();
+  if (token === undefined) {
+    throw new Error("no Telegram bot token readable — the arm notice cannot send");
+  }
+  let topicId: number | undefined;
+  let project: { name: string; workspaceRoot?: string } | undefined;
+  if (surface.project !== undefined) {
+    try {
+      const p = findProject(loadConfig(), surface.project);
+      topicId = resolveProjectTopicId(p);
+      project = { name: p.name, workspaceRoot: p.workspaceRoot };
+    } catch {
+      /* no project config — flat chat, exactly like armTicks */
+    }
+  }
+  await sendTelegram(token, channel.owner, text, {
+    topicId,
+    ...(project === undefined ? {} : { project }),
+  });
+}
+
+/**
+ * The settle half of the mechanical consumer: write the markers the matched
+ * challenge recorded and clear its transaction, then confirm on the
+ * challenge's surface. The recorded targets are the contract — the exact rule
+ * `armReply` applies — so nothing is ever armed that the challenge did not
+ * name. A pre-targets record (one release of overlap) is not settled here:
+ * nothing in-session may guess a marker the challenge never recorded; the CLI
+ * half still settles it, and the operator is told so.
+ */
+function settleInboundArmMatch(
+  pi: TickApi,
+  match: ArmReplyMatch,
+  notify: (text: string) => void,
+): void {
+  if (match.targets === undefined || match.owner === undefined) {
+    pi.logger.error(
+      "[omp-conductor] an inbound arming code matched a pre-targets challenge — nothing armed in-session; " +
+        'run `omp-conductor arm --reply "<the reply>"` to settle it',
+    );
+    return;
+  }
+  for (const target of match.targets) {
+    const state = resolveArmState(target.armedFile, target.project);
+    writeArmedMarker(target.armedFile, match.owner, state);
+  }
+  clearArmTransaction(match.key, match.id);
+  const label =
+    match.targets.length === 1 && match.targets[0]!.project !== undefined
+      ? `project ${match.targets[0]!.project}`
+      : `${match.targets.length} project(s)`;
+  notify(`Arming verified — ${label} armed. The reply was consumed; nothing else to do.`);
+}
+
+/**
+ * The arm ceremony's mechanical consumer (#1061): classify one inbound user
+ * turn against this host's pending challenges and, on a match, settle the
+ * ceremony exactly as `omp-conductor arm --reply` would — markers for the
+ * recorded targets, transaction cleared, a confirmation on the surface the
+ * challenge was sent to. This is the real owner the ceremony needed on a host
+ * with no console session: the challenge goes to the project topic, which is
+ * this pane's own claimed surface, so the reply lands here and the ceremony
+ * completes with no second human command. A code past its window is answered
+ * with the re-run command and the dead record is cleared; a lookalike matching
+ * nothing stays inert (#415's non-disclosure bound is unchanged).
+ *
+ * Never throws: an inbound message must not take the session down. Failures
+ * are logged and the CLI half of the ceremony stays available.
+ */
+function consumeInboundArmReply(
+  pi: TickApi,
+  cwd: string,
+  startupProject: string | undefined,
+  text: string,
+  seam: ArmConsumerSeam | undefined,
+): void {
+  // The state key the send half derived from the same file, read fresh so a
+  // re-stamp between the send and the reply cannot split the ceremony. An
+  // invalid config cannot be trusted to name either the key or a marker —
+  // fail closed exactly like `armReply`, but without throwing at a message.
+  const reread = readTickConfig(cwd);
+  if (reread.kind === "invalid") {
+    pi.logger.error(
+      `[omp-conductor] inbound arm reply not classified — tick config invalid at ${reread.path}: ` +
+        `${reread.problem}; use \`omp-conductor arm --reply\` on the host`,
+    );
+    return;
+  }
+  const project = reread.kind === "ok" ? reread.config.project : startupProject;
+  const surface: ArmNoticeSurface = {
+    ...(reread.kind === "ok" ? { accessFile: reread.config.accessFile } : {}),
+    project,
+  };
+  const now = (seam?.now ?? Date.now)();
+  const resolved = resolveArmReply(project, text, now);
+  const notify = (notice: string): void => {
+    const send = seam?.notify ?? sendArmNotice;
+    try {
+      // The send is async on the production path; message_start handlers are
+      // not, so delivery rides the microtask queue and its failure lands in
+      // the log, never on the session.
+      void Promise.resolve(send(notice, surface)).catch((err: unknown) => {
+        pi.logger.error(
+          `[omp-conductor] arm notice not delivered: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+    } catch (err) {
+      pi.logger.error(
+        `[omp-conductor] arm notice not delivered: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  };
+  if (resolved.verdict === "matched") {
+    settleInboundArmMatch(pi, resolved.match, notify);
+    return;
+  }
+  // A code past its window: the ceremony is dead, so answer the person who is
+  // clearly trying to complete it — and clear the expired record so neither
+  // this path nor the heartbeat ever notifies twice.
+  if (resolved.verdict === "expired") {
+    for (const expired of expiredArmChallenges(project, now)) {
+      notify(armExpiryNotice(expired, project));
+      clearArmTransaction(expired.key, expired.id);
+    }
+  }
 }
 
 export default function orchestratorTickExtension(
@@ -3634,8 +3900,10 @@ export default function orchestratorTickExtension(
 
   /** `configuredProject` carries {@link TickConfig.project} for the same reason
    *  {@link armReleaseGate} takes it: a recovered tick must reconstruct *this*
-   *  fleet's availability policy, not refuse to guess between two projects. */
-  const armAvailabilityGate = (configuredProject?: string): void => {
+   *  fleet's availability policy, not refuse to guess between two projects.
+   *  `cwd` is the fleet directory itself, which the arm consumer re-reads the
+   *  tick config from at reply time (#1061). */
+  const armAvailabilityGate = (configuredProject?: string, cwd?: string): void => {
     if (availabilityGateArmed) return;
     availabilityGateArmed = true;
 
@@ -3667,23 +3935,33 @@ export default function orchestratorTickExtension(
         }
         return;
       }
-      // An inbound user turn on THIS session is now an anomaly, not a
+      // An inbound user turn on THIS session is an anomaly, not a
       // conversation: operator DMs belong to the 24/7 console session, so a
-      // turn arriving here is an accidental topic post. It is recorded for one
-      // purpose only — {@link tickGuardDecision}'s preemption, which lets a
-      // human waiting on this pane cut a running tick short. Nothing is
-      // classified: the arming ceremony is two CLI steps on the host
-      // (`omp-conductor arm`, then `omp-conductor arm --reply "<message>"`),
-      // because with the console owning DMs an arming reply lands where no tick
-      // extension runs, and a classifier here would only ever have been dead
-      // code waiting to misfire.
-      if (
-        message.role === "user" &&
-        message.synthetic !== true &&
-        message.attribution !== "agent" &&
-        session.activeLocalTick !== undefined
-      ) {
-        session.activeLocalTick.humanWaiting = true;
+      // turn arriving here is an accidental topic post. Two things happen,
+      // and both are mechanisms — nothing here is left to model behaviour:
+      //
+      // 1. The arm ceremony's reply is classified against the pending
+      //    challenge records (#1061). The pre-#415 tombstone is retired: it
+      //    reasoned the reply lands "where no tick extension runs", but the
+      //    send half delivers the challenge to the project topic — this
+      //    pane's own claimed surface — so the reply lands exactly here, and
+      //    on a host with no console session the CLI's `arm --reply` step had
+      //    no owner at all. A matching code settles the ceremony
+      //    (markers written, transaction cleared) and answers with a
+      //    confirmation; a code past its window is answered with the re-run
+      //    command; a lookalike matching nothing stays inert, exactly as
+      //    #415 required.
+      // 2. {@link tickGuardDecision}'s preemption, unchanged: a person who
+      //    posts into the fleet topic by accident is still a person waiting,
+      //    and the autonomous-interrupt refusal must not fire at them.
+      if (message.role === "user" && message.synthetic !== true && message.attribution !== "agent") {
+        if (cwd !== undefined) {
+          const text = inboundMessageText(message.content);
+          if (text !== undefined) consumeInboundArmReply(pi, cwd, configuredProject, text, options.arm);
+        }
+        if (session.activeLocalTick !== undefined) {
+          session.activeLocalTick.humanWaiting = true;
+        }
       }
     });
     pi.on("agent_end", () => {
@@ -3921,7 +4199,7 @@ export default function orchestratorTickExtension(
     // invalid config names none — it cannot be trusted to.
     const configuredProject = result.kind === "ok" ? result.config.project : undefined;
     armReleaseGate(configuredProject);
-    armAvailabilityGate(configuredProject);
+    armAvailabilityGate(configuredProject, ctx.cwd);
     // The tool is already registered (extension-factory time); only the session
     // state it acts on is filled, and only once ownership is accepted below.
     // `configuredProject` isn't closed over at all — routing is re-read from
@@ -4011,7 +4289,7 @@ export default function orchestratorTickExtension(
         // not create or deliver decisions). `cwd` is for re-reading the live
         // tick config at execution, `config` for the startup-only ceiling.
         askSession = { cwd: ctx.cwd, config };
-        armTickHeartbeat(pi, ctx, config, session, toSpecTrackerSeam);
+        armTickHeartbeat(pi, ctx, config, session, toSpecTrackerSeam, options.arm);
         if (!guardArmed) {
           guardArmed = true;
           armTickGuard(pi, ctx, (config.budgetSeconds ?? DEFAULT_TICK_BUDGET_SECONDS) * 1000);
@@ -4033,7 +4311,7 @@ export default function orchestratorTickExtension(
     // why): a declined or unresolved session keeps `askSession` undefined and
     // the tool fails closed.
     askSession = { cwd: ctx.cwd, config };
-    armTickHeartbeat(pi, ctx, config, session, toSpecTrackerSeam);
+    armTickHeartbeat(pi, ctx, config, session, toSpecTrackerSeam, options.arm);
     if (!guardArmed) {
       guardArmed = true;
       armTickGuard(pi, ctx, (config.budgetSeconds ?? DEFAULT_TICK_BUDGET_SECONDS) * 1000);

package/src/reports.ts

@@ -361,7 +361,10 @@ export function telegramReportSend(p: ProjectConfig): ReportSend {
     // limit would still be delivered whole (never truncated) — the seam would
     // simply under-report the extra ids, which is why the split lives at the
     // caller, not here.
-    const ids = await sendTelegram(token, chatId, text, { topicId: resolveProjectTopicId(p) });
+    const ids = await sendTelegram(token, chatId, text, {
+      topicId: resolveProjectTopicId(p),
+      project: { name: p.name, workspaceRoot: p.workspaceRoot },
+    });
     return ids[0];
   };
 }