@groundnuty/macf 0.2.35 → 0.2.37

package/dist/reconciler/reconcile.js

@@ -0,0 +1,119 @@
+/**
+ * Route-receipt reconciler — pure drop-detection logic (groundnuty/macf#444
+ * Option D, piece 4).
+ *
+ * Closes the structural gap: a `turn_processed` span nobody queries is
+ * *forensic*, not *surfacing*. This is the consumer that turns the ABSENCE of
+ * a receipt span into a structural signal.
+ *
+ * It joins two sets on `(runId, agent)`:
+ *   - DELIVERED — the routes the macf-actions router LOGGED as delivered
+ *     (`Routed … to <AGENT> via helper|inline`), each with the route run's
+ *     timestamp. (Source: GitHub run logs — see sources.ts.)
+ *   - PROCESSED — the `turn_processed` spans the substrate UserPromptSubmit
+ *     hook emitted when the marked prompt became a turn. (Source: Tempo
+ *     TraceQL `{name="turn_processed" && resource.service.namespace="macf"}`.)
+ *
+ * A DELIVERED route is a **drop** iff it has no matching PROCESSED span AND it
+ * is older than the open-threshold. The threshold is load-bearing: a
+ * *legitimately busy* agent processes the ping late (the #437 co-verify showed
+ * ~4 min legit latency), so a recent unmatched delivery is "still in flight",
+ * NOT a drop. The threshold must exceed observed busy-turn latency (≈15–20 min,
+ * tunable). This + the per-run recompute gives the open-on-absence /
+ * self-close-on-appearance behaviour (e2e.yml #166/#163 shape): while drops
+ * exist the workflow holds an incident open; once a late span lands (or none
+ * remain) the next run reports zero drops and the workflow self-closes.
+ *
+ * The join key is the **marker-parsed** `(runId, agent)` — both sides derive
+ * from the router's `[macf-route:${GITHUB_RUN_ID}:${AGENT_NAME}]` marker /
+ * `Routed … to <AGENT>` log line, so they match by construction. (NOT the
+ * receiving agent's `MACF_AGENT_NAME`, which is unset on substrate — see #444
+ * discussion + the #451 hook.)
+ *
+ * This module is intentionally PURE (no I/O) so the load-bearing logic is fully
+ * unit-testable; the GitHub/Tempo fetchers + the incident open/self-close live
+ * in sources.ts / run.ts / the scheduled workflow.
+ */
+/** Canonical join key for a `(runId, agent)` pair. */
+export function receiptKey(p) {
+    return `${p.runId}:${p.agent}`;
+}
+/**
+ * macf#479 coalesced-turn gate. For a would-be drop, find a *different*
+ * delivery to the same agent within ±proximityMs that WAS receipted. Its
+ * existence means the agent was alive + processing routed turns around the
+ * delivery, so this one benignly coalesced/clobbered into a sibling's turn.
+ *
+ * Crucially it counts only ROUTED receipts (the `processed` set), so an
+ * RC-bound agent — alive on the RC-SDK but silently dropping ALL its tmux
+ * pings, none of which receipt — has NO receipted sibling near a real drop and
+ * is correctly NOT suppressed. (Returns null ⇒ no benign sibling ⇒ real drop.)
+ */
+function findReceiptedSibling(route, inScope, processedKeys, proximityMs) {
+    let best = null;
+    for (const sib of inScope) {
+        if (sib.runId === route.runId)
+            continue; // not itself
+        if (sib.agent !== route.agent)
+            continue; // same agent only
+        const deltaMs = sib.deliveredAtMs - route.deliveredAtMs;
+        if (Math.abs(deltaMs) > proximityMs)
+            continue; // outside the window
+        if (!processedKeys.has(receiptKey(sib)))
+            continue; // sibling must be receipted
+        // Prefer the temporally-nearest receipted sibling for the log.
+        if (best === null || Math.abs(deltaMs) < Math.abs(best.deltaMs)) {
+            best = { route, siblingRunId: sib.runId, deltaMs };
+        }
+    }
+    return best;
+}
+/**
+ * Pure reconciliation: which delivered routes are drops (no receipt span +
+ * older than the open-threshold) vs. still-in-flight (no receipt yet but
+ * within the threshold) vs. processed (have a receipt).
+ */
+export function reconcile(delivered, processed, opts) {
+    const processedKeys = new Set(processed.map(receiptKey));
+    // Deployment-boundary guard (groundnuty/macf#444): drop routes delivered
+    // before the receipt mechanism went live from scope entirely — those prompts
+    // had no marker and hit hookless sessions, so a missing receipt is EXPECTED,
+    // not a drop. Else the first reconcile after enabling would false-alarm on
+    // every pre-deployment route in the lookback window.
+    const sinceMs = opts.sinceMs;
+    const inScope = sinceMs ? delivered.filter((r) => r.deliveredAtMs >= sinceMs) : delivered;
+    const proximityMs = opts.proximityMs ?? 0;
+    const drops = [];
+    const inFlight = [];
+    const suppressed = [];
+    for (const route of inScope) {
+        if (processedKeys.has(receiptKey(route)))
+            continue; // receipt landed — fine
+        const ageMs = opts.nowMs - route.deliveredAtMs;
+        if (ageMs <= opts.openThresholdMs) {
+            inFlight.push(route); // unmatched but young → busy agent may process late
+            continue;
+        }
+        // Unmatched + past the threshold → a would-be drop. macf#479: suppress it
+        // (benign coalesce) iff a receipted sibling delivery to the same agent sits
+        // within the proximity window — the agent was demonstrably processing routed
+        // turns then. No receipted sibling (lone / offline / RC-bound) ⇒ real drop.
+        const sibling = proximityMs > 0
+            ? findReceiptedSibling(route, inScope, processedKeys, proximityMs)
+            : null;
+        if (sibling !== null) {
+            suppressed.push(sibling);
+        }
+        else {
+            drops.push(route);
+        }
+    }
+    return {
+        drops,
+        inFlight,
+        suppressed,
+        deliveredCount: inScope.length,
+        processedCount: processedKeys.size,
+    };
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/reconciler/reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../../src/reconciler/reconcile.ts"],"names":[],"mappings":"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"}

package/dist/reconciler/run.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/** DELIVERED set: parse the router runs' `Routed … to <AGENT>` success lines.
+ *  `truncated` is true when `gh run list` hit its page cap — the set is then
+ *  UNKNOWABLE (older routes fell off the page), so the caller must NOT flag
+ *  drops this run. Symmetric to the Tempo `tempo_ok` guard, on the delivered
+ *  side (Pattern A): silently bounding coverage would let a real drop hide. */
+/**
+ * Window-aware DELIVERED truncation (macf#477). The set is UNKNOWABLE only when
+ * the run-list page is full AND its OLDEST run is still inside the lookback
+ * window — i.e. older in-window runs were pushed off the page. When the oldest
+ * run on the page predates the window start, the window is fully covered and
+ * the page is NOT truncated (the older entries are simply out-of-window).
+ *
+ * The previous check (`runs.length >= LIMIT`) measured LIFETIME page-fullness,
+ * so it went dark — `delivered_ok=false` every run — in any repo with >LIMIT
+ * lifetime router runs regardless of in-window count, making the reconciler a
+ * permanent no-op (and blocking #462 self-close). `gh run list` returns
+ * newest-first, so `runs.at(-1)` is the oldest on the page.
+ */
+export declare function isDeliveredTruncated(runs: ReadonlyArray<{
+    createdAt: string;
+}>, nowMs: number, lookbackMs: number, limit: number): boolean;
+//# sourceMappingURL=run.d.ts.map

package/dist/reconciler/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/reconciler/run.ts"],"names":[],"mappings":";AAkGA;;;;+EAI+E;AAC/E;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,CAAC;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,EAC1C,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAOT"}

package/dist/reconciler/run.js

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+/**
+ * Route-receipt reconciler entrypoint (groundnuty/macf#444 Option D, piece 4).
+ *
+ * Invoked by the scheduled `route-reconciler.yml` workflow. Thin I/O glue over
+ * the unit-tested pure pieces (reconcile / parse-delivered / parse-processed):
+ *
+ *   1. DELIVERED — `gh run list` the `agent-router` runs (success, recent) +
+ *      `gh run view --log` each → parse the `Routed … to <AGENT>` lines.
+ *   2. PROCESSED — Tempo `/api/search` for `turn_processed` spans → parse the
+ *      `(routed_run_id, agent)` attrs.
+ *   3. reconcile() → drops (delivered, no receipt, older than the open-threshold).
+ *   4. Emit `tempo_ok` + `drops_count` / `drops_json` to `$GITHUB_OUTPUT` for
+ *      the workflow's open-on-absence / self-close-on-appearance incident steps.
+ *
+ * Pattern-A safety (false-drop avoidance): any Tempo problem — unreachable,
+ * HTTP error, OR a result hitting the `limit` (truncation) — makes the
+ * PROCESSED set UNKNOWABLE, which is NOT the same as "zero drops". Treating it
+ * as empty would false-OPEN incidents (a truncated set reads as missing
+ * receipts) and treating it as `drops_count=0` would false-CLOSE a real
+ * incident on a transient outage. So all three paths emit `tempo_ok=false`;
+ * the workflow gates BOTH the open AND the self-close steps on
+ * `tempo_ok == 'true'`, making a Tempo problem a TRUE no-op (incidents left
+ * exactly as they are). Only a verified-complete query opens (real drops) or
+ * closes (verified zero).
+ *
+ * Config (env, set by the workflow):
+ *   RECONCILER_REPO        owner/repo (default $GITHUB_REPOSITORY)
+ *   ROUTER_WORKFLOW        router workflow file (default agent-router.yml)
+ *   TEMPO_QUERY_ENDPOINT   Tempo query base; default is the dedicated
+ *                          monitoring VM over Tailscale on the OTel-native
+ *                          port (no +10000 offset):
+ *                          http://orzech-dev-agents-monitoring.tail491af.ts.net:3200
+ *                          (macf#516 — the old k3d loopback default is DEAD)
+ *   OPEN_THRESHOLD_MIN     drop threshold, must exceed busy-turn latency (default 15)
+ *   PROXIMITY_MIN          macf#479 coalesced-turn gate: suppress a would-be drop
+ *                          when a receipted sibling delivery to the same agent is
+ *                          within ±this (default 5; must be < OPEN_THRESHOLD_MIN)
+ *   LOOKBACK_MIN           how far back to scan runs + Tempo (default 120). The
+ *                          DELIVERED query is scoped to this window via
+ *                          `gh run list --created`, so truncation means
+ *                          ">RUN_LIST_LIMIT router runs INSIDE the window"
+ *                          (genuine high volume), not lifetime page-fullness (macf#477)
+ *   TEMPO_LIMIT            Tempo search result cap (default 1000)
+ */
+import { execFileSync } from 'node:child_process';
+import { appendFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { reconcile } from './reconcile.js';
+import { parseDeliveredFromLog } from './parse-delivered.js';
+import { parseProcessedFromTempo, receiptsIfComplete } from './parse-processed.js';
+const MIN = 60_000;
+/** `gh run list` page cap. If the router bursts past this in the lookback
+ *  window the DELIVERED set truncates silently (Pattern A on the delivered
+ *  side: a missed delivery → its receipt is never looked for → a real drop is
+ *  silently NOT flagged). We WARN when the cap is hit so the symmetry is
+ *  observable, but don't abort: delivered-side truncation under-reports drops
+ *  (false negative), which is far less harmful than the processed-side
+ *  truncation that would over-report them (false incident). */
+const RUN_LIST_LIMIT = 100;
+const envStr = (name, def) => {
+    const v = process.env[name];
+    return v !== undefined && v.length > 0 ? v : def;
+};
+const REPO = envStr('RECONCILER_REPO', process.env['GITHUB_REPOSITORY'] ?? '');
+const ROUTER_WORKFLOW = envStr('ROUTER_WORKFLOW', 'agent-router.yml');
+const TEMPO = envStr('TEMPO_QUERY_ENDPOINT', 'http://orzech-dev-agents-monitoring.tail491af.ts.net:3200').replace(/\/+$/, '');
+const OPEN_THRESHOLD_MS = Number(envStr('OPEN_THRESHOLD_MIN', '15')) * MIN;
+const LOOKBACK_MS = Number(envStr('LOOKBACK_MIN', '120')) * MIN;
+// macf#479 coalesced-turn gate: suppress a would-be drop when a receipted
+// sibling delivery to the same agent is within ±this. Must be > the turn-batching
+// window (~couple min) and < OPEN_THRESHOLD_MIN (so real lone/offline/RC-bound
+// drops still flag). 0 ⇒ disabled.
+const PROXIMITY_MS = Number(envStr('PROXIMITY_MIN', '5')) * MIN;
+const TEMPO_LIMIT = Number(envStr('TEMPO_LIMIT', '1000'));
+/** Deployment-boundary cutoff (groundnuty/macf#444): ignore routes delivered
+ *  before the receipt mechanism went live. Set `RECONCILER_SINCE` to the
+ *  hook-go-live time (ISO-8601 e.g. `2026-06-06T08:00:00Z`, or epoch ms) at the
+ *  first `RECONCILER_ENABLED` flip — pre-deployment routes had no marker + hit
+ *  hookless sessions, so their missing receipt is EXPECTED, not a drop. Without
+ *  it, run 1 would false-alarm on every pre-deployment route in the lookback.
+ *  Self-obsoletes once LOOKBACK_MIN slides fully past the cutoff; unset ⇒ no cutoff. */
+const SINCE_MS = (() => {
+    const raw = process.env['RECONCILER_SINCE'];
+    if (!raw)
+        return undefined;
+    const ms = /^\d+$/.test(raw) ? Number(raw) : Date.parse(raw);
+    if (!Number.isFinite(ms)) {
+        console.error(`WARN: RECONCILER_SINCE="${raw}" not parseable (want ISO-8601 or epoch ms) — ignoring cutoff.`);
+        return undefined;
+    }
+    return ms;
+})();
+/** DELIVERED set: parse the router runs' `Routed … to <AGENT>` success lines.
+ *  `truncated` is true when `gh run list` hit its page cap — the set is then
+ *  UNKNOWABLE (older routes fell off the page), so the caller must NOT flag
+ *  drops this run. Symmetric to the Tempo `tempo_ok` guard, on the delivered
+ *  side (Pattern A): silently bounding coverage would let a real drop hide. */
+/**
+ * Window-aware DELIVERED truncation (macf#477). The set is UNKNOWABLE only when
+ * the run-list page is full AND its OLDEST run is still inside the lookback
+ * window — i.e. older in-window runs were pushed off the page. When the oldest
+ * run on the page predates the window start, the window is fully covered and
+ * the page is NOT truncated (the older entries are simply out-of-window).
+ *
+ * The previous check (`runs.length >= LIMIT`) measured LIFETIME page-fullness,
+ * so it went dark — `delivered_ok=false` every run — in any repo with >LIMIT
+ * lifetime router runs regardless of in-window count, making the reconciler a
+ * permanent no-op (and blocking #462 self-close). `gh run list` returns
+ * newest-first, so `runs.at(-1)` is the oldest on the page.
+ */
+export function isDeliveredTruncated(runs, nowMs, lookbackMs, limit) {
+    if (runs.length < limit)
+        return false; // page not full → window fully covered
+    const oldest = runs[runs.length - 1];
+    if (oldest === undefined)
+        return false;
+    const oldestMs = Date.parse(oldest.createdAt);
+    if (!Number.isFinite(oldestMs))
+        return true; // unparseable oldest → conservative: unknowable
+    return oldestMs > nowMs - lookbackMs; // oldest still in-window ⇒ older runs fell off ⇒ truncated
+}
+function fetchDelivered(nowMs) {
+    // Scope the query to the lookback window SERVER-SIDE (macf#477): the page then
+    // holds only in-window runs, so a full page genuinely means ">LIMIT deliveries
+    // INSIDE the window" — and we fetch logs only for in-window runs instead of all
+    // RUN_LIST_LIMIT (incl. out-of-window ones the old code fetched then discarded).
+    const windowStartIso = new Date(nowMs - LOOKBACK_MS).toISOString();
+    const listJson = execFileSync('gh', ['run', 'list', '--repo', REPO, '--workflow', ROUTER_WORKFLOW,
+        '--status', 'success', '--created', `>=${windowStartIso}`,
+        '--limit', String(RUN_LIST_LIMIT), '--json', 'databaseId,createdAt'], { encoding: 'utf-8' });
+    const runs = JSON.parse(listJson);
+    const truncated = isDeliveredTruncated(runs, nowMs, LOOKBACK_MS, RUN_LIST_LIMIT);
+    if (truncated) {
+        console.error(`WARN: >${RUN_LIST_LIMIT} router runs INSIDE the ${LOOKBACK_MS / MIN}-min window — DELIVERED set UNKNOWABLE (older in-window routes fell off the ${RUN_LIST_LIMIT}-run page). Emitting delivered_ok=false (no drops this run); narrow LOOKBACK_MIN or raise the cap.`);
+    }
+    const out = [];
+    for (const run of runs) {
+        const createdMs = Date.parse(run.createdAt);
+        if (!Number.isFinite(createdMs) || nowMs - createdMs > LOOKBACK_MS)
+            continue;
+        let log;
+        try {
+            log = execFileSync('gh', ['run', 'view', String(run.databaseId), '--repo', REPO, '--log'], { encoding: 'utf-8', maxBuffer: 64 * 1024 * 1024 });
+        }
+        catch {
+            continue; // log unavailable (expired/in-progress) — skip, not a drop signal
+        }
+        out.push(...parseDeliveredFromLog(log, String(run.databaseId), createdMs));
+    }
+    return { routes: out, truncated };
+}
+/** PROCESSED set: Tempo `turn_processed` spans → receipts. Aborts (no drops)
+ *  on a Tempo failure to avoid false alarms (Pattern A). */
+async function fetchProcessed(nowMs) {
+    const startSec = Math.floor((nowMs - LOOKBACK_MS) / 1000);
+    const endSec = Math.floor(nowMs / 1000);
+    const q = '{name="turn_processed" && resource.service.namespace="macf"} | select(span.routed_run_id, span.agent)';
+    const url = `${TEMPO}/api/search?q=${encodeURIComponent(q)}&start=${startSec}&end=${endSec}&limit=${TEMPO_LIMIT}`;
+    let res;
+    try {
+        res = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+    }
+    catch (err) {
+        // `fetch failed` is opaque — the real cause is in err.cause (undici wraps
+        // the network error). Surface its code + message so an unreachable Tempo
+        // tells us WHICH failure: ENOTFOUND (MagicDNS not resolving the host),
+        // ECONNREFUSED (nothing listening / not `tailscale serve`d), ETIMEDOUT
+        // (ACL/firewall dropping the connection), or AbortError (15s timeout).
+        const e = err;
+        const detail = e.cause?.code ?? e.cause?.message ?? e.name;
+        console.error(`WARN: Tempo query unreachable [${url}] — ${e.message}: ${detail} — PROCESSED set unknowable; NOT flagging drops this run (avoids false alarms).`);
+        return null;
+    }
+    if (!res.ok) {
+        console.error(`WARN: Tempo query HTTP ${res.status} — PROCESSED set unknowable; treating as Tempo-unknown (true no-op this run).`);
+        return null;
+    }
+    const parsed = parseProcessedFromTempo(await res.json());
+    // Truncation is a Tempo problem too: an incomplete PROCESSED set reads as
+    // missing receipts → false drops. receiptsIfComplete() returns null when the
+    // result hit the limit, so it's handled identically to unreachable/HTTP-error.
+    const receipts = receiptsIfComplete(parsed, TEMPO_LIMIT);
+    if (receipts === null) {
+        console.error(`WARN: Tempo returned ${parsed.traceCount} >= limit ${TEMPO_LIMIT} — PROCESSED set may be truncated (Pattern A: a truncated set reads as missing receipts → false drops). Treating as Tempo-unknown (true no-op this run); narrow LOOKBACK_MIN or raise TEMPO_LIMIT.`);
+    }
+    return receipts;
+}
+async function main() {
+    const nowMs = Date.now();
+    const processed = await fetchProcessed(nowMs);
+    if (processed === null) {
+        // Tempo problem (unreachable / HTTP error / truncated) — the PROCESSED set
+        // is UNKNOWABLE, NOT "zero drops". Emit tempo_ok=false; the workflow gates
+        // BOTH its open AND its self-close steps on tempo_ok==true, so this is a
+        // TRUE no-op: incidents are left exactly as they are (never false-OPEN on a
+        // truncated set, never false-CLOSE a real incident on a transient outage).
+        console.error('WARN: PROCESSED set unknowable this run — emitting tempo_ok=false (no open, no close).');
+        emit({ tempoOk: false, deliveredOk: true, dropsCount: 0, inFlightCount: 0, dropsJson: '[]' });
+        return;
+    }
+    const { routes: delivered, truncated } = fetchDelivered(nowMs);
+    if (truncated) {
+        // DELIVERED set unknowable (truncated) — like a Tempo problem, NOT "zero
+        // drops". Emit delivered_ok=false so the workflow's open AND self-close
+        // steps both no-op this run (each gated on tempo_ok && delivered_ok).
+        emit({ tempoOk: true, deliveredOk: false, dropsCount: 0, inFlightCount: 0, dropsJson: '[]' });
+        return;
+    }
+    const result = reconcile(delivered, processed, {
+        nowMs, openThresholdMs: OPEN_THRESHOLD_MS, sinceMs: SINCE_MS, proximityMs: PROXIMITY_MS,
+    });
+    const dropsJson = JSON.stringify(result.drops);
+    console.error(`reconcile: delivered=${result.deliveredCount} processed=${result.processedCount} ` +
+        `drops=${result.drops.length} in_flight=${result.inFlight.length} suppressed=${result.suppressed.length}` +
+        (SINCE_MS ? ` (since=${new Date(SINCE_MS).toISOString()} — pre-deployment routes excluded)` : ''));
+    // macf#479: coalesced-turn suppressions are LOUD + counted, NEVER silent. Each
+    // is a delivery whose marker never receipted but whose agent demonstrably
+    // processed a sibling ROUTED turn within PROXIMITY_MS (benign coalesce/clobber,
+    // not a real send≠receipt drop). Logging the rate keeps the underlying
+    // C-u-clobber visible (its source-side fix is tracked separately); a spike here
+    // is itself a signal. RC-bound real-drops are NOT suppressed (no receipted
+    // sibling — their tmux pings all drop), so the detector keeps its #437 cause-3
+    // teeth. Known residual (rare, same loud-log captures the rate): a content-loss
+    // clobber (the clobbering sibling DID receipt) is suppressed — and likewise a
+    // genuinely-independent transport loss of A that happens to fall within ±T of an
+    // UNRELATED receipted sibling. Both are closed at the root by the source-side
+    // C-u-clobber fix; until then the suppressed-rate signal keeps them visible.
+    for (const s of result.suppressed) {
+        console.error(`suppressed_coalesced_drop: run=${s.route.runId} agent=${s.route.agent} ` +
+            `sibling=${s.siblingRunId} delta_ms=${s.deltaMs} ` +
+            `(benign: receipted sibling within ${PROXIMITY_MS / MIN}min — macf#479)`);
+    }
+    if (result.drops.length > 0)
+        console.error(`DROPS: ${dropsJson}`);
+    emit({
+        tempoOk: true, deliveredOk: true, dropsCount: result.drops.length,
+        inFlightCount: result.inFlight.length, dropsJson, suppressedCount: result.suppressed.length,
+    });
+}
+function emit(o) {
+    const out = process.env['GITHUB_OUTPUT'];
+    if (!out)
+        return;
+    appendFileSync(out, `tempo_ok=${o.tempoOk}\ndelivered_ok=${o.deliveredOk}\ndrops_count=${o.dropsCount}\n` +
+        `in_flight_count=${o.inFlightCount}\nsuppressed_count=${o.suppressedCount ?? 0}\ndrops_json=${o.dropsJson}\n`);
+}
+/**
+ * Run main() ONLY when invoked as the CLI entrypoint (the route-reconciler.yml
+ * workflow runs `node dist/reconciler/run.js`). Guarded so the unit test can
+ * `import { isDeliveredTruncated }` from this module WITHOUT triggering main():
+ * an unguarded top-level main() rejects under the test's no-network env and
+ * calls process.exit(1), which vitest surfaces as an unhandled error + leaves a
+ * pending fetch keeping the worker alive (macf#477 test imported it; macf#479).
+ */
+function isCliEntrypoint() {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined)
+        return false;
+    try {
+        return realpathSync(argv1) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false; // argv1 unresolvable (e.g. under a test runner) — not the entrypoint
+    }
+}
+if (isCliEntrypoint()) {
+    main().catch((err) => {
+        console.error(`Fatal: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=run.js.map

package/dist/reconciler/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/reconciler/run.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundnuty/macf",
-  "version": "0.2.35",
+  "version": "0.2.37",
   "description": "Multi-Agent Coordination Framework CLI — coordinate Claude Code agents via GitHub. Installs as `macf` binary; use `macf init` to set up an agent workspace, `macf update` to refresh rules + version pins.",
   "type": "module",
   "main": "dist/index.js",
@@ -35,7 +35,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@groundnuty/macf-core": "0.2.35",
+    "@groundnuty/macf-core": "0.2.37",
     "commander": "^14.0.3",
     "reflect-metadata": "^0.2.2",
     "zod": "^4.0.0"

package/plugin/rules/coordination.md

@@ -115,6 +115,27 @@ The rules here are topology-agnostic: they work whether the project uses a scien
 
 4. **Concise comments** — 1-3 sentences unless detail is needed.
 
+5. **Inbound review requests are action asks that block the requester — not status FYIs.** Issue Lifecycle rule 2 covers the implementer's OUTBOUND queue ("work through your assigned-label queue without prompting"). This rule covers the symmetric REVIEWER-side INBOUND obligation, which is just as load-bearing and far easier to strand.
+
+   **(a) Treat "PR ready: #N" / "ready for review" as a request that blocks the peer's next move.** When a peer posts a review-request comment on a thread, that is not an informational status update you can note-and-defer — it is an action ask directed at you. The LGTM/merge-gate makes this structural: per `pr-discipline.md`, a peer's PR cannot merge without a reviewer's **formal approval** (`gh pr review --approve`), so until you review, the peer is blocked. Not slowed — blocked, and silently, because nothing on their side surfaces "my reviewer never saw this." A stranded review request stalls the peer indefinitely. Pick it up, review honestly, and submit a formal approve / request-changes (not a plain comment — see `pr-discipline.md §"How to submit LGTM"`; only the formal state-change fires the reviewer-notification routing).
+
+   **(b) Run an INBOUND review-sweep before declaring idle — especially after surfacing from a long single-threaded task.** Before you say "caught up" / "nothing pending" / "your call" / go idle, sweep your repos for review requests addressed to you. This matters most right after you surface from a deep, single-threaded arc (a long workflow, a multi-step investigation): while you were heads-down on one thread, a review request can have arrived on another and been easy to miss.
+
+        # Peer-authored PRs awaiting YOUR review (review not yet given):
+        for r in <your-repos>; do
+          gh pr list --repo "$r" --state open \
+            --json number,author,reviewDecision,title \
+            --jq '.[] | select(.reviewDecision == "REVIEW_REQUIRED" or .reviewDecision == null)
+                       | select(.author.login != "<your-login>")'
+        done
+        # Plus: open threads where you were @mentioned and haven't replied.
+
+   (The query intentionally surfaces *any* peer-authored PR lacking a review, not only those that formally requested you by name — on a small fleet that breadth is a feature: it catches a peer blocked on review even when the request didn't route to you. Narrow it with a requested-reviewer filter on a larger fleet.)
+
+   **Why the sweep is necessary — and why it's mechanism-agnostic.** Routing delivers each notification as a **discrete event at the moment it occurs** — a push to your channel-server, an A2A message — not as a standing inbox you can re-open and re-read later. Once that event has been delivered (or has arrived while you were mid-turn on a different thread), it is not re-presented to you on its own. So a review-request ping that landed while you were deep in another task is gone from the live stream and only recoverable by querying GitHub state directly. This is the **general silent-fallback shape** (see `silent-fallback-hazards.md`): the routing layer reports the ping delivered, but "delivered" does not guarantee "processed by the recipient," and nothing surfaces the gap until the blocked peer escalates. The sweep is the result-invariant check at the reviewer boundary — assert against GitHub state ("are there peer PRs awaiting my review?") rather than trusting that you'd remember every ping that flowed past.
+
+   **Verified motivation:** three operator-surfaced stalls where a peer's review request sat idle (42 min in one case; ~2.5 h in another) because the reviewer went idle without sweeping — the ping had arrived during a long single-threaded task and was never picked back up. In each case the peer's PR was blocked the entire time on a formal approval that never came.
+
 ---
 
 ## When You're Stuck — Escalation
@@ -160,19 +181,7 @@ The goal is correctness through dialogue, not compliance.
 
 ---
 
-## Submitting a Prompt to a Claude Code TUI (tmux)
-
-When a hook or script needs to programmatically submit a prompt to a Claude Code TUI running in tmux, **always use the canonical helper**:
-
-        .claude/scripts/tmux-send-to-claude.sh <session-or-empty> "<prompt text>"
-
-Pass `""` for the session to target the current pane.
-
-**Never** call `tmux send-keys "<prompt>" Enter` inline. Claude Code's TUI is in multi-line input mode by default, so a single Enter inserts a newline instead of submitting — the prompt sits in the buffer unsubmitted. The helper handles the submit-quirk correctly: clear existing input with `C-u`, send the text with a first Enter, sleep 1 second (load-bearing — without it tmux batches both Enters and Claude processes them atomically as "newline + newline"), then send a second Enter that actually submits.
-
-The helper is distributed to every agent workspace by `macf init` and refreshed by `macf update` (same mechanism as this rules file). If you're writing a new hook or automation that needs to prompt Claude, use the helper — do not re-implement the pattern.
-
-### Canonical tmux launch pattern
+## Canonical tmux launch pattern
 
 **One session per agent, named `<project>@<agent>`.** Post-v0.2.10, `claude.sh` self-wraps in tmux with this naming structurally — bare `./claude.sh` produces the canonical session. Pre-v0.2.10 consumers (and operators wanting manual launch) use the explicit form:
 

package/plugin/rules/gh-token-attribution-traps.md

@@ -50,6 +50,10 @@ case "$TOKEN" in ghs_*) ;; *) echo "FATAL: bad token prefix" >&2; exit 1 ;; esac
 export GH_TOKEN="$TOKEN"
 ```
 
+**Why the bare `TOKEN=$(...)` + separate `export`, never `export GH_TOKEN=$(...)`:** `export` is a builtin whose own exit status (`0`) *replaces* the command-substitution's, so `export GH_TOKEN=$(helper) || exit 1` and `export GH_TOKEN=$(helper) && gh ...` both proceed even when the helper failed (ShellCheck SC2155). The failure only propagates from a **bare** assignment (`TOKEN=$(helper) || …`). This is load-bearing under GitHub's intermittent token-endpoint 401s: a refresh that can yield an empty token *without aborting* the dependent `gh` ops re-creates mode #3 (witnessed 2026-06-12 — `cv-architect` posted 4 comments as the operator under a transient 401).
+
+**The PreToolUse hook does NOT cover this.** `check-gh-token.sh` validates the *ambient* `GH_TOKEN` before the command runs, so an inline `export GH_TOKEN=$(...) && gh ...` (refresh-chain *or* file-cache read) reassigns the token *after* the hook has already passed — the hook is structurally blind to it (silent-fallback **Instance 12**, `silent-fallback-hazards.md`). Refresh in a **separate step** (to a pre-validated file, or a bare-assigned var with the checks above), never inline in the `gh` command. The durable structural cover is a result-invariant **PostToolUse** `author`-check (macf#489), not the PreToolUse precondition.
+
 ### 4. Wrong `gh auth` on the VM providing fallback
 
 Having `gh auth login` configured as a user account creates the fallback surface in #3. Even a "good" setup where the script is correct can hide a broken bot token because `gh` quietly uses the user auth.

package/plugin/rules/mention-routing-hygiene.md

@@ -117,6 +117,8 @@ Per `groundnuty/macf#244` + `#272`, this rule is enforced by a Claude Code PreTo
 
 The hook is the same shape as `check-gh-token.sh` (#140 attribution-trap defense) — bash command-type hook distributed via `macf init` / `macf update` / `macf rules refresh` to every workspace's `.claude/scripts/check-mention-routing.sh` with the entry registered in `.claude/settings.json` `hooks.PreToolUse`. Substrate workspaces, tester agents, CV consumers, and future MACF-consumer projects all get the protection uniformly.
 
+Because the hook is registered as a path-invocation (`"command": "$CLAUDE_PROJECT_DIR/.claude/scripts/check-mention-routing.sh"`), Claude Code execs the script fresh on every event, so a change to the **script body** goes live on the very next event as soon as the file is synced on disk — a `macf update` that updates the script is immediately in force for consumers with no session relaunch and no relaunch-coordination needed. Only a change to the hook **registration** in `.claude/settings.json` (or to the launch environment) requires a relaunch to take effect.
+
 **Heuristic** (subject to refinement; documented for transparency):
 
 - Already wrapped in backticks (`` `@<bot>[bot]` ``) → routing-suppressed; allowed (canonical describing form §5); does NOT count toward Check A

package/plugin/rules/observability-wiring.md

@@ -13,7 +13,7 @@ Every MACF agent's `claude.sh` launcher exports the Claude Code native OpenTelem
 | `OTEL_TRACES_EXPORTER` | `otlp` | Emit traces. Without it, no spans even if master gate is on |
 | `OTEL_METRICS_EXPORTER` | `otlp` | Emit metrics. **Per-signal** — separate from traces |
 | `OTEL_LOGS_EXPORTER` | `otlp` | Emit logs. **Per-signal** — separate from traces |
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` (default) | OTLP HTTP receiver. Override via `MACF_OTEL_ENDPOINT` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:14318` (macf canonical — the bare OTLP default `:4318` is overridden by `macf init`/`update`) | OTLP HTTP receiver. Override via `MACF_OTEL_ENDPOINT` |
 | `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf` | Wire protocol |
 | `OTEL_SERVICE_NAME` | `macf-agent-<name>` | All MACF agents grouped under one service.name family |
 | `OTEL_RESOURCE_ATTRIBUTES` | `gen_ai.agent.name=<name>,gen_ai.agent.role=<role>,service.namespace=macf` | Semconv-compliant resource attrs |
@@ -32,10 +32,10 @@ Per-workspace, two env knobs read at `macf init` / `macf update` time:
   - Deployment has no OTLP receiver running (no observability stack)
   - You want zero retry-spam from the exporter
   - Agent runs offline / on a host that can't reach the collector
-- `MACF_OTEL_ENDPOINT=http://central-host:4318` — overrides the default `http://localhost:4318`. Use when:
+- `MACF_OTEL_ENDPOINT=http://central-host:14318` — overrides the default `http://localhost:14318`. Use when:
   - The observability stack is on a different host (Tailscale tailnet, reverse proxy, central collector)
   - You're running multiple MACF deployments and want them all reporting to one collector
-  - The default port `4318` collides with another service on the agent's host (e.g., devops-toolkit's compose stack uses `:14318` for this reason)
+  - **Note:** the canonical macf-devops-toolkit k3d stack serves OTLP HTTP on `:14318` (the bare-SDK default `:4318` was retired 2026-04-25 after it collided with the prior compose stack and caused 34 min of zero-telemetry on CV agents — macf#282/#283). Use `:14318`, not `:4318`.
 
 To apply a knob: set the env var BEFORE running `macf update`. The launcher re-renders with the new state.
 

package/plugin/rules/reflection-staging.md

@@ -0,0 +1,65 @@
+# Reflection Staging (canonical, shared)
+
+**Maintain a staged reflection as you work. At compaction it is harvested automatically.** This file is the single source of truth for the reflection-staging discipline; it is copied into each agent workspace's `.claude/rules/` by `macf init` and refreshed by `macf update` / `macf rules refresh`. Do not edit workspace copies directly — edit the canonical file at `groundnuty/macf:packages/macf/plugin/rules/reflection-staging.md` and re-distribute.
+
+Applies to every MACF agent. The mechanism is local + cheap and never blocks compaction (DR-026 F2, groundnuty/macf#500).
+
+---
+
+## What this is
+
+You accumulate observations as you work — recurring patterns, canonical-rule breaches you committed or witnessed, signals that a rule should evolve, loose ends. Historically these lived in "remember to synthesize before compaction" / "codify at decision time" disciplines, which depended on you remembering to act at exactly the moment your context was about to be summarized away.
+
+This rule gives those disciplines a **structural home**: a single file you keep current as you go. They stop being "remember to do X at compaction" and become "keep `pending.json` current." At compaction, the `harvest-reflection.sh` PreCompact hook reads the staged file, wraps it in the versioned reflection envelope, appends it to a local per-session JSONL ledger, and clears the stage for the next session. You never run the harvest by hand — the hook fires on both auto-compaction and manual `/compact`.
+
+---
+
+## The staged file
+
+Maintain `.claude/.macf/reflections/pending.json` incrementally. It holds only the **protocol-signal fields** — the hook adds the envelope (`schema_version`, `kind`, agent identity, project, session id, timestamp, trigger, compaction type) at harvest time.
+
+```jsonc
+{
+  // Recurring behaviour / coordination dynamic / workflow shape worth surfacing.
+  "observed_patterns": [
+    { "pattern": "<short name>", "evidence": "<what you saw / a ref>", "tier_hint": "<where it might belong>" }
+  ],
+  // Canonical-rule breaches you committed or witnessed this session.
+  "breaches": [
+    { "rule": "<rule name>", "what": "<the breach>", "ref": "<issue/PR/commit/file:line>" }
+  ],
+  // Signals that a coordination rule should evolve (proposals for governance).
+  "rule_evolution_signals": [
+    { "signal": "<what changed/recurred>", "proposed_tier": "<suggested tier>", "rationale": "<why>" }
+  ],
+  // Loose ends to pick up next session.
+  "unresolved": [ "<string>", "<string>" ],
+  // One-paragraph free-form synthesis of the session.
+  "synthesis": "<prose>"
+}
+```
+
+Every field is optional. An empty `{}` (the cleared state) is valid — the hook still emits a **mechanical-only** record at compaction so the Monitor sees that a compaction happened. Arrays default to `[]`, `synthesis` to `""`.
+
+`observed_patterns[]` and `rule_evolution_signals[]` may carry an optional `key` field — reserved for deterministic cross-agent dedup later (additive; leave it out for now unless you have a stable key).
+
+## How to keep it current
+
+- **Append, don't wait.** When you notice a pattern, breach, or evolution signal mid-session, add it to the relevant array right then. Don't batch it for "later" — later is compaction, and the point is that the staging already happened.
+- **Edit the file directly** (`Read` then `Edit`/`Write`). It is plain JSON in your workspace; no command or tool call is needed.
+- **Keep `synthesis` a living summary.** Overwrite it as your understanding of the session firms up.
+- **Don't clear it yourself.** The harvest hook clears the stage after appending. If you clear it, the next compaction emits a mechanical-only record and your observations are lost.
+
+## Where it lands
+
+- Ledger: `.claude/.macf/reflections/<session_id>.jsonl` (one JSON object per line, schema-validated by `@groundnuty/macf-core` `ReflectionRecordSchema`).
+- The ledger is **local + observational** — DR-023 §UC-3 posture. The harvest never blocks compaction; an internal error fails open (`exit 0`).
+- Opt out of harvesting for a session with `MACF_SKIP_REFLECTION_HARVEST=1`.
+
+---
+
+## When to read vs. modify
+
+- **Read:** every session start. This rule defines how to stage your reflection.
+- **Modify:** never directly in workspace copies. Edit the canonical file and re-distribute via `macf update`.
+- **Disagree with a rule?** Open an issue on `groundnuty/macf` proposing the change, with rationale. Peer review applies.