agent-coord-mcp 0.26.28 → 0.26.30

package/scripts/check-test-count.mjs

@@ -93,18 +93,25 @@ function rel(file) {
   return file ? `test/${path.basename(file)}` : "(unattributed)";
 }
 
-if (failures.length) {
+// ⟨q-4b2362a8⟩ — A FAILING TEST MUST NOT MASK STRUCTURAL DRIFT. This used to report the failures and
+// exit, so an unrecorded test file stayed invisible behind any red: #393's `bind-list.test.mjs` was
+// missing from the record for days, hidden behind the quiet-fleet failure of merge-window. The
+// failures are still the headline — a count over a failing suite means little — but the drift that
+// does NOT depend on the counts (a file nobody recorded, a record entry with no file) is reported in
+// the same run, because one red hiding another is how both survive.
+const failed = failures.length > 0;
+if (failed) {
   console.error(`[check-test-count] ${failures.length} test(s) FAILED — the count is not the story here:`);
   for (const f of failures) console.error(`    ${f}`);
-  process.exit(1);
 }
 
 // `=0` disables; any other override asserts the old single global total.
-if (globalOverride === 0) {
+// Both early exits are skipped on a failing suite: a green there would report a pass over a red run.
+if (globalOverride === 0 && !failed) {
   console.log(`[check-test-count] disabled by AGENT_COORD_EXPECTED_TESTS=0 — ${total} test(s) passed, unchecked`);
   process.exit(0);
 }
-if (globalOverride !== null && Number.isFinite(globalOverride)) {
+if (globalOverride !== null && Number.isFinite(globalOverride) && !failed) {
   if (total !== globalOverride) {
     console.error(`[check-test-count] FAIL — ${total} tests passed, override expected ${globalOverride}.`);
     process.exit(1);
@@ -115,11 +122,15 @@ if (globalOverride !== null && Number.isFinite(globalOverride)) {
 
 // ── the real comparison, per file ──────────────────────────────────────────
 const drifted = [];
+// STRUCTURAL drift does not depend on the counts — which file is recorded at all, which record entry
+// has no file. It is the half that still means something when the suite is red (⟨q-4b2362a8⟩).
+const structural = [];
 for (const f of files) {
   const want = expected[f];
   const got = actual.get(f) ?? 0;
   if (want === undefined) {
-    drifted.push(`${f}: ran ${got} test(s) and is NOT in the record — a new test file must be recorded in the same commit`);
+    const line = `${f}: ran ${got} test(s) and is NOT in the record — a new test file must be recorded in the same commit`;
+    drifted.push(line); structural.push(line);
   } else if (got !== want) {
     drifted.push(`${f}: ran ${got}, record says ${want}`);
   }
@@ -134,15 +145,30 @@ for (const f of files) {
 // exists to exercise — the guard's own test caught it.
 for (const f of Object.keys(expected)) {
   if (!existsSync(path.join(pkgRoot, f))) {
-    drifted.push(`${f}: in the record but no such file exists — deleted, or renamed and its coverage lost`);
+    const line = `${f}: in the record but no such file exists — deleted, or renamed and its coverage lost`;
+    drifted.push(line); structural.push(line);
   } else if (files.includes(f) === false && GLOB === "test/*.test.mjs") {
-    drifted.push(`${f}: exists but did not run — the glob no longer selects it`);
+    const line = `${f}: exists but did not run — the glob no longer selects it`;
+    drifted.push(line); structural.push(line);
   }
 }
 // An unattributed pass would make every per-file number meaningless.
 const unattributed = actual.get("(unattributed)") ?? 0;
 if (unattributed) drifted.push(`${unattributed} test(s) passed with no file attribution — the per-file record cannot be verified against this run`);
 
+// On a red suite: report the structural half (never the counts, which a failing test legitimately
+// changes) and exit on the failures.
+if (failed) {
+  if (structural.length) {
+    console.error(`[check-test-count] AND, not masked by those failures — ${structural.length} structural drift(s) in the record:`);
+    for (const d of structural) console.error(`    ${d}`);
+    console.error(`  Record them with \`node scripts/check-test-count.mjs --write\` once the suite is green.`);
+  } else {
+    console.error(`[check-test-count] no structural record drift besides the failures above (per-file counts are not judged over a red suite)`);
+  }
+  process.exit(1);
+}
+
 if (!drifted.length) {
   console.log(
     `[check-test-count] ${total} test(s) across ${files.length} file(s), each matching its recorded count — ` +

package/src/capabilities.ts

@@ -64,7 +64,7 @@ import { queueWriteSchema } from "./tools/queue-write.js";
 import { treeProvenance } from "./tools/tree-provenance.js";
 import { detectSpread } from "./server-spread.js";
 import { answeringServerIdentity } from "./tools/registry.js";
-import { HerdrTransport, herdrKeyName } from "./transports/herdr.js";
+import { HerdrTransport, herdrKeyName, interpretHerdrReply, submitModeOf, SUBMIT_MODE_ENV_VAR } from "./transports/herdr.js";
 import { tickVerdict } from "./tools/tick.js";
 import { ensureHerdrTail, herdrTailState, newContext, newMessagesIn, stopHerdrTail } from "./tools/herdr-tail.js";
 import { HERDR, TICK_READS_AS, TICK_STORED_AS, type TickState } from "./transports/types.js";
@@ -461,6 +461,62 @@ const PROBES: Probe[] = [
       };
     },
   },
+  {
+    // ⟨q-f7e3c701⟩ 0.26.29 — ATOMIC SUBMIT. Two properties, and BOTH are here because each one
+    // alone would have shipped a defect that was actually shipped:
+    //
+    // 1. THE PARSE. #397 first read `json?.status ?? json?.result?.status`. The real herdr 0.9.1
+    //    reply carries `result.type`, and there is no `status` anywhere — so on real hardware the
+    //    success check NEVER fired and every genuine delivery fell through to unverified /
+    //    safeToRetry:false, which is the DROP path. It would have reported 100% failure while
+    //    succeeding, and the canary would have binned a working fix on false evidence.
+    //    ⛔ THE UNIT TESTS COULD NOT CATCH IT: they mocked `{status:"agent_prompted"}` — the code's
+    //    own assumption — so they asserted the belief rather than the world. The payloads below are
+    //    VERBATIM CAPTURES from a real binary, which is the only fixture shape that can fail.
+    //
+    // 2. THE SAFE DEFAULT. Blast radius is both fleets and the failure mode is silence, so the
+    //    canary must be opt-in by EXACT literal. A near-miss must NOT opt in.
+    //
+    // Both are pure predicates handed the REJECTED input, per this file's mutation-matrix rule:
+    // a probe that cannot be given the case it must refuse is decorative.
+    id: "atomic-submit-parses-real-herdr-replies",
+    since: "0.26.29",
+    run: () => {
+      // VERBATIM from `herdr agent prompt` on herdr 0.9.1 — success carries result.type.
+      const REAL_PROMPTED = '{"id":"cli:agent:prompt","result":{"agent":{"agent":"claude","agent_status":"idle","pane_id":"w16:pD"},"type":"agent_prompted"}}';
+      // VERBATIM from the same binary against a blocked agent — a TOP-LEVEL error.code, no result.
+      const REAL_BLOCKED = '{"error":{"code":"agent_blocked","message":"agent w16:pD is blocked and requires interactive input"},"id":"cli:agent:prompt"}';
+
+      const okReply = interpretHerdrReply({ status: 0, stdout: REAL_PROMPTED, stderr: "" });
+      const blockedReply = interpretHerdrReply({ status: 1, stdout: REAL_BLOCKED, stderr: "" });
+
+      const prompted = (okReply.json as { result?: { type?: string } } | undefined)?.result?.type === "agent_prompted";
+      // The two live in DIFFERENT PLACES — one field cannot serve both, which was the bug.
+      const blockedCode = blockedReply.ok === false && blockedReply.error?.code === "agent_blocked";
+      // ⛔ THE NEGATIVE CONTROL FOR THE PARSE: the old expression must NOT find anything, or this
+      // probe would pass on the broken code it exists to refuse.
+      const oldPathFindsNothing =
+        (okReply.json as { status?: string; result?: { status?: string } } | undefined)?.status === undefined &&
+        (okReply.json as { status?: string; result?: { status?: string } } | undefined)?.result?.status === undefined;
+
+      const defaultsSafe = submitModeOf({}) === "send-keys";
+      const optsIn = submitModeOf({ [SUBMIT_MODE_ENV_VAR]: "agent-prompt" }) === "agent-prompt";
+      // ⛔ NEGATIVE CONTROLS FOR THE FLAG: a trailing space and a near-miss must NOT flip a fleet.
+      const typoStaysSafe =
+        submitModeOf({ [SUBMIT_MODE_ENV_VAR]: "agent-prompt " }) === "send-keys" &&
+        submitModeOf({ [SUBMIT_MODE_ENV_VAR]: "AGENT-PROMPT" }) === "send-keys" &&
+        submitModeOf({ [SUBMIT_MODE_ENV_VAR]: "true" }) === "send-keys";
+
+      const present = prompted && blockedCode && oldPathFindsNothing && defaultsSafe && optsIn && typoStaysSafe;
+      return {
+        present,
+        evidence:
+          `real agent_prompted -> result.type read=${prompted} · real agent_blocked -> error.code read=${blockedCode} · ` +
+          `old \`status\` path finds nothing on the real payload=${oldPathFindsNothing} · ` +
+          `default=${JSON.stringify(submitModeOf({}))} safe=${defaultsSafe} · exact opt-in=${optsIn} · near-misses stay send-keys=${typoStaysSafe} -> present=${present}`,
+      };
+    },
+  },
   {
     // ⟨q-1c95f7d4⟩ Phase 5.4 Task 5 — the external tick, probed by CALLING the code that
     // decides what a reading MEANS (every probe here is synchronous, so the async read is
@@ -567,6 +623,35 @@ const PROBES: Probe[] = [
       return { present, evidence: `module ${me.serverModule ?? "UNRESOLVED"} · dead stamp -> unknown: ${staleUnknown} · split + unstamped seat -> ${split?.state ?? "n/a"} -> present=${present}` };
     },
   },
+  {
+    // ⟨q-caa2959e⟩ (0.26.30) — the merge-window live control's APPLICABILITY is own landings in the
+    // horizon, never its own window count. A quiet fleet (record commits, no landing) is NOT
+    // APPLICABLE and says so with both counts; a landing whose PR announced no window is a problem,
+    // which is the violation the control exists to catch and the one a count-based rule would skip
+    // green. Asked of the running function, so a server on the pre-fix build answers false.
+    id: "merge-window-applies-on-own-landings",
+    since: "0.26.30",
+    run: () => {
+      const T = Date.parse("2026-09-20T12:00:00Z");
+      const landing = { sha: "a".repeat(40), at: T, author: "seat", subject: "docs(done): close it (#900)", mergeOf: 900 };
+      const plain = { sha: "b".repeat(40), at: T, author: "seat", subject: "docs(board): claim a row", mergeOf: null };
+      const opts = { now: T + 60_000, floorMs: T - 60_000 };
+      const unannounced = mergeWindowLivePopulation({ logText: "", writes: [landing], ...opts });
+      const quiet = mergeWindowLivePopulation({ logText: "", writes: [plain], ...opts });
+      const windowsOnly = mergeWindowLivePopulation({ logText: `{"ts":${T},"from":"qa","to":"#k","text":"QA GATE: PASS #900\nMERGE WINDOW: #900 — hold queue/board writes"}`, writes: [], ...opts });
+      const present =
+        unannounced.applicable === true && unannounced.missingWindow.length === 1 &&
+        quiet.applicable === false && /landed nothing in the horizon/.test(quiet.reason) && /0 own landing\(s\)/.test(quiet.reason) &&
+        windowsOnly.applicable === false;
+      return {
+        present,
+        evidence:
+          `landing with no window -> applicable=${unannounced.applicable} missingWindow=${unannounced.missingWindow.length} · ` +
+          `record commit, no landing -> applicable=${quiet.applicable} (names both counts: ${/0 own landing\(s\)/.test(quiet.reason)}) · ` +
+          `windows but no landing -> applicable=${windowsOnly.applicable} -> present=${present}`,
+      };
+    },
+  },
   {
     id: "record-authority",
     since: "0.24.0",
@@ -750,7 +835,7 @@ export function probeCapabilities(context: { module: string; versionLabel: strin
 
 import { resolveServerIdentity } from "./server-identity.js";
 import { seatBuildOf, installedFrom, psReader, type SeatBuild } from "./tools/seat-build.js";
-import { isInFlightStatus, gateClaimsIn } from "./tools/stall.js";
+import { isInFlightStatus, gateClaimsIn, mergeWindowLivePopulation } from "./tools/stall.js";
 import { parseWorkDoc, queueItemsOf, stampQueueIds } from "@davidbalzan/groundwork-seam";
 
 export const capabilitiesSchema = {} as const;

package/src/tools/herdr-tail.ts

@@ -127,6 +127,19 @@ export async function tailOnce(
   // read its marker file on every tick while the stated idle cost said otherwise.
   if (refresh) {
     ctx.marker = (opts.markerOf ?? readOwnMarker)(agentId);
+    // ⟨q-d58ccdce⟩ ⛔⛆⛆ THIS BRANCH IS THE WHOLE DEFECT. `marker.rooms === false` makes
+    // `ctx.rooms` PERMANENTLY EMPTY — every room this agent belongs to is silently excluded
+    // from `sources` below, so the per-source loop never runs for a single one of them. That
+    // is a total, structural skip with no `continue` to log: #395's per-outcome push logging
+    // fires only for a source the loop actually reaches, and a room that is never a source
+    // produces zero log lines forever — indistinguishable from a room with nothing owed.
+    // Measured live 2026-09-19: every groundwork-kit-* seat's marker had `rooms:false` (a
+    // side effect of `attach_agent {..., includeRoom:false}`, called believing it only
+    // affected DM liveness), while every unaffected control seat had `rooms:true`. So THIS
+    // is the log line the class needed — not one more line inside a loop that never starts.
+    if (ctx.marker && ctx.marker.transport === HERDR && ctx.marker.rooms === false) {
+      log(`[herdr-tail] rooms DISABLED for ${agentId} — marker.rooms=false, so no room is ever tailed regardless of membership (⟨q-d58ccdce⟩); re-attach with includeRoom:true (or omit it) to restore room delivery`);
+    }
     if (ctx.marker && ctx.marker.transport === HERDR && ctx.marker.rooms !== false) {
       try {
         const all = await (opts.roomsOf ?? getRooms)();
@@ -150,13 +163,20 @@ export async function tailOnce(
     // ⛔ FIRST SIGHT OF A SOURCE UNDER seedEof: adopt EOF and type NOTHING. This is the only place
     // the starting offset is decided, and it is decided EXPLICITLY rather than inherited from a
     // cursor file that a restart may have reset. Per source, so a room joined later seeds on its
-    // own first sight instead of replaying its history.
+    // own first sight instead of replaying its history. Logged (low-frequency: once per source
+    // per process) so a seat that never types into a newly-joined room is distinguishable from
+    // one that was never told the room existed.
     if (ctx.seedEof && !ctx.seeded.has(key)) {
       ctx.seeded.add(key);
       ctx.hw.set(key, size);
+      log(`[herdr-tail] seeded ${key} at EOF (${size} bytes) for ${agentId} — first sight this process, nothing predating the tail will be typed`);
       continue;
     }
     const from = await offsetOf(agentId, src, ctx);
+    // ⭐ NEGATIVE CONTROL FOR THE CLASS THIS ROW IS ABOUT: nothing is logged here when
+    // `size === from` — a source with nothing owed must stay silent, or every idle room on
+    // every tick becomes a line and the log that is supposed to make a real stall visible
+    // drowns in ones that are not.
     if (size <= from) continue;
 
     for (const { msg, end } of newMessagesIn(src.file, from)) {

package/src/tools/stall.ts

@@ -512,6 +512,57 @@ export function mergeWindowChecks(input: { logText: string; writes: RecordWrite[
   return { hits: withAudience(hits), windows: out, unmeasurable };
 }
 
+/**
+ * ⟨q-caa2959e⟩ — WHETHER THE MERGE-WINDOW CONVENTION CAN BE JUDGED ON THIS BUS RIGHT NOW,
+ * decided from OWN LANDINGS IN THE HORIZON and never from the window count.
+ *
+ * The live check used to assert `windows.length > 0`. A stand-down left the fleet quiet: 0 window
+ * announcements inside the horizon while record commits remained, so a control pinned to a live
+ * baseline failed for everyone — it expired when the fleet went quiet, not when anything broke.
+ *
+ * ⛔ AND APPLICABILITY IS NEVER READ OFF THE PREDICATE'S OWN COUNT. Deciding it from `windows.length`
+ * is the by-mention trap ⟨q-552b9912⟩ taught us, inverted: a fleet that landed PRs and announced NO
+ * window — precisely the violation this check exists to catch — would skip itself green. The
+ * population is what the fleet DID (its landings); the windows are what it is judged ON.
+ *
+ * Applicable when the horizon holds at least one landing of this fleet's (a squash carrying the
+ * forge's `(#N)` marker). Then every one of them MUST carry a window announcement, and a missing one
+ * is a problem. With no landing there is nothing to judge: NOT APPLICABLE, named with both counts.
+ */
+export function mergeWindowLivePopulation(input: { logText: string; writes: RecordWrite[] | null; now: number; floorMs?: number; horizonMs?: number }): {
+  applicable: boolean;
+  reason: string;
+  population: string;
+  landings: RecordWrite[];
+  missingWindow: { sha: string; pr: number }[];
+  windows: ReturnType<typeof mergeWindowChecks>["windows"];
+  hits: ReturnType<typeof mergeWindowChecks>["hits"];
+} {
+  const floor = input.floorMs ?? MERGE_WINDOW_ADOPTED_MS;
+  const horizon = input.horizonMs ?? CONVENTION_WINDOW_MS;
+  const r = mergeWindowChecks(input);
+  const since = new Date(input.now - horizon).toISOString();
+  const head = `horizon ${since} → ${new Date(input.now).toISOString()}, floor ${new Date(floor).toISOString()}`;
+  if (input.writes === null) {
+    const reason = `NOT APPLICABLE: record-document writes could not be read from the shared branch — ${head}. UNMEASURED is not the same as kept.`;
+    return { applicable: false, reason, population: reason, landings: [], missingWindow: [], windows: r.windows, hits: r.hits };
+  }
+  const inHorizon = input.writes.filter((c) => Number.isFinite(c.at) && c.at >= input.now - horizon);
+  const landings = inHorizon.filter((c) => c.mergeOf !== null);
+  const population = `${head}: ${inHorizon.length} record commit(s), ${landings.length} own landing(s), ${r.windows.length} window(s), ${r.hits.length} hit(s)`;
+  if (landings.length === 0) {
+    return {
+      applicable: false,
+      reason: `NOT APPLICABLE: this fleet landed nothing in the horizon, so there is no window to require — ${population}. (A quiet fleet, not a broken convention; the window count is never what decides this.)`,
+      population, landings, missingWindow: [], windows: r.windows, hits: r.hits,
+    };
+  }
+  const missingWindow = landings
+    .filter((c) => !r.windows.some((w) => w.pr === c.mergeOf))
+    .map((c) => ({ sha: c.sha, pr: c.mergeOf as number }));
+  return { applicable: true, reason: `APPLICABLE — ${population}`, population, landings, missingWindow, windows: r.windows, hits: r.hits };
+}
+
 export function conventionChecks(input: {
   recentMerges: RecentMerge[] | null | undefined;
   /** PRs the caller knows merged express. Nothing populates this yet — see isDocsOnlyMerge. */

package/src/transports/herdr.ts

@@ -170,8 +170,28 @@ export type HerdrTransportOptions = {
    * variable at a time, six others left in place — was what turned it green.
    */
   env?: Record<string, string | undefined>;
+  /** Override the submit mode this instance uses; defaults to `submitModeOf(this.#env)`. Tests only. */
+  submitMode?: SubmitMode;
 };
 
+/**
+ * ⟨q-f7e3c701⟩ — WHICH SUBMIT PATH `push` USES. `agent-prompt` is the atomic fix
+ * (`herdr agent prompt <target> <text>`, one call, no type→read-back→Enter window). `send-keys`
+ * is today's path (type, verify it landed, Enter, verify it submitted).
+ *
+ * DEFAULT IS `send-keys`, DELIBERATELY. The blast radius of switching is both fleets and the
+ * failure mode is silence — a wrong default ships broken delivery to every seat with no signal
+ * until someone notices nothing arrived. `agent-prompt` is enabled per-seat as a canary via
+ * `AGENT_COORD_SUBMIT=agent-prompt`, compared against control seats by `outcome=` rate in
+ * bus-daemon.err.log, and reverted by unsetting the variable — no republish required, which
+ * matters because 0.26.28 took two days to travel merged→observed.
+ */
+export type SubmitMode = "agent-prompt" | "send-keys";
+export const SUBMIT_MODE_ENV_VAR = "AGENT_COORD_SUBMIT";
+export function submitModeOf(env: Record<string, string | undefined> = process.env): SubmitMode {
+  return env[SUBMIT_MODE_ENV_VAR] === "agent-prompt" ? "agent-prompt" : "send-keys";
+}
+
 /**
  * ⟨q-abd88dd4⟩ — THE PID A HERDR MARKER CARRIES, chosen for the readers that CANNOT be patched.
  *
@@ -225,6 +245,7 @@ export class HerdrTransport implements Transport {
   #readLines: number;
   #markerPid: () => HerdrMarkerPid;
   #env: Record<string, string | undefined>;
+  #submitMode: SubmitMode;
 
   constructor(opts: HerdrTransportOptions = {}) {
     this.#run = opts.run ?? defaultHerdrRunner;
@@ -237,6 +258,7 @@ export class HerdrTransport implements Transport {
     this.#readLines = opts.readLines ?? 40;
     this.#markerPid = opts.markerPid ?? (() => herdrMarkerPid());
     this.#env = opts.env ?? process.env;
+    this.#submitMode = opts.submitMode ?? submitModeOf(this.#env);
   }
 
   /** Is herdr on this host AND is its server running? Both, or the reason. */
@@ -330,6 +352,9 @@ export class HerdrTransport implements Transport {
     if (!avail.available) return { delivered: false, outcome: "held", safeToRetry: true, error: avail.reason };
     const target = targetOf(marker);
     if (!target) return { delivered: false, outcome: "held", safeToRetry: true, error: "no target recorded on the marker" };
+    // ⟨q-f7e3c701⟩ ATOMIC SUBMIT, canaried per seat via AGENT_COORD_SUBMIT. Everything below this
+    // branch is the send-keys path (today's default); #pushAgentPrompt is the opt-in replacement.
+    if (this.#submitMode === "agent-prompt") return this.#pushAgentPrompt(target, text);
     const payload = opts.paste === false ? text : `${PASTE_START}${neutralizeControls(text)}${PASTE_END}`;
     const enterKey = herdrKeyName("enter");
     if (!enterKey.ok) return { delivered: false, outcome: "held", safeToRetry: true, error: enterKey.error };
@@ -363,6 +388,73 @@ export class HerdrTransport implements Transport {
     return { delivered: false, verified: true, outcome: "pending", safeToRetry: true, enters, error: `text still sitting unsubmitted in ${target}'s input after ${enters} enters` };
   }
 
+  /**
+   * ⟨q-f7e3c701⟩ ATOMIC SUBMIT, behind `AGENT_COORD_SUBMIT=agent-prompt` (default `send-keys` —
+   * see `submitModeOf`). `herdr agent prompt <target> <text> --wait --until working` types and
+   * submits in ONE call: no type→read-back→Enter window for a decoration to land in, which is
+   * the class the send-keys path above exists to survive. MEASURED (joint cross-fleet design,
+   * 2026-09-21): 4/4 across two hosts, including a LIVE WEDGE the send-keys path had already
+   * abandoned in the same minute.
+   *
+   * ⛔ `refusalBeforeKeys` IS NOT OPTIONAL — MEASURED ON A THROWAWAY PANE: `agent prompt` into a
+   * DIRTY composer returned `agent_prompted` (success) and CONCATENATED the stale draft with the
+   * new text, no separator, then submitted both. Atomic submit alone is strictly WORSE than
+   * today: a recoverable `held` becomes unrecoverable corruption carrying a success receipt.
+   * `agent_blocked` is a STATUS axis and is BLIND to a dirty composer (reads
+   * `status: idle · interactive_ready: true` regardless), so it cannot substitute for reading
+   * the box first — this method still reads it, exactly as the send-keys path does.
+   *
+   * Receipt is `--until working`, an OBSERVED state transition — strictly stronger than "I typed
+   * it and could read it back", the only receipt class send-keys has ever had. A stall/timeout is
+   * treated as UNCONFIRMED, never as safe to retry: unlike send-keys's `typed-unconfirmed` (where
+   * nothing had actually been typed yet), a stalled atomic submit may already have gone through,
+   * and retrying risks a genuine double-send.
+   *
+   * ⛔⛔ THE FIELD PATH BELOW WAS WRONG ONCE, SHIPPED, AND CAUGHT BY QA'S OWN LIVE SMOKE TEST
+   * BEFORE MERGE — recorded because the wrong version passed every unit test, having been
+   * written against a GUESSED shape (`json.status ?? json.result.status`) that the mocks then
+   * reproduced instead of measuring. Against the real CLI that path is always `undefined`, so
+   * every genuine success fell through to the catch-all and the feature would have reported
+   * 100% failure on real hardware. VERIFIED PAYLOADS, captured against herdr 0.9.1 by the aide
+   * and independently reproduced here on a disposable scratch pane (`herdr workspace create` /
+   * `agent start --kind claude` / closed after):
+   *   success:  {"result":{"agent":{...},"type":"agent_prompted"}}   — result.type, not result.status
+   *   blocked:  {"error":{"code":"agent_blocked","message":"..."}}   — TOP-LEVEL error, no `result` at all
+   *   timeout:  {"error":{"code":"timeout","message":"..."}}         — same top-level shape as blocked
+   * So this is TWO PATHS, not one field read: `result.type` for success, `error.code` for every
+   * refusal. A single-location parse mishandles one of them regardless of which is picked — the
+   * exact shape of the bug that shipped. `agent_prompt_stalled` was NOT reproduced against a real
+   * binary despite attempting it (the 5000ms stall window did not fire in either kit's or my own
+   * attempts) — it is handled via the same `error.code` path as `agent_blocked`/`timeout` BY
+   * ANALOGY with the CLI's consistent refuse-via-top-level-error convention, not by measurement.
+   * If that analogy is wrong, the failure mode is `unverified/safeToRetry:false` (never a
+   * double-send) rather than a false "delivered", so the untested case fails safe.
+   */
+  async #pushAgentPrompt(target: string, text: string): Promise<HerdrPushResult> {
+    if (readyProfile().profile !== "none") {
+      const before = readReadyBox(this.#screen(target));
+      const refusal = refusalBeforeKeys(before);
+      if (refusal) return { delivered: false, verified: false, outcome: "held", safeToRetry: true, error: `held, nothing typed into ${target}: ${refusal}` };
+    }
+    const r = this.#run(["agent", "prompt", target, text, "--wait", "--until", "working"]);
+    const resultType = (r.json as { result?: { type?: string } } | undefined)?.result?.type;
+    if (r.ok && resultType === "agent_prompted") {
+      return { delivered: true, verified: true, outcome: "delivered", safeToRetry: false };
+    }
+    if (r.error?.code === "agent_blocked") {
+      // MEASURED: nothing is typed into the pane on agent_blocked — the agent itself refused the
+      // prompt before any input was sent. Safe to retry, same as a send-keys `held`.
+      return { delivered: false, verified: false, outcome: "held", safeToRetry: true, error: `agent_blocked at ${target}: ${r.error.message}` };
+    }
+    if (r.error?.code === "agent_prompt_stalled" || r.error?.code === "timeout") {
+      return {
+        delivered: false, verified: false, outcome: "unverified", safeToRetry: false,
+        error: `${r.error.code} at ${target}: submission unconfirmed by --wait --until working — not retried, to avoid a double-send on an atomic path`,
+      };
+    }
+    return { delivered: false, verified: false, outcome: "unverified", safeToRetry: false, error: `agent prompt to ${target} refused or unrecognised: ${r.error?.message ?? r.stderr ?? JSON.stringify(r.json)}` };
+  }
+
   /** The screen, styled, so the ready-box reader can tell a ghost suggestion from a draft. null = unreadable. */
   #screen(target: string): string | null {
     const read = this.#run(["pane", "read", target, "--source", "visible", "--lines", String(this.#readLines), "--format", "ansi"]);

package/src/transports/index.ts

@@ -14,7 +14,7 @@ import { configuredTransport } from "./config.js";
 export * from "./types.js";
 export * from "./config.js";
 export { TmuxTransport, tmuxAvailable, paneExists, probePane, tmuxVersion, type TmuxHost } from "./tmux.js";
-export { HerdrTransport, defaultHerdrRunner, interpretHerdrReply, herdrKeyName, herdrPaneExists, herdrMarkerPid, HERDR_KEYS, HERDR_ABSENT_MESSAGE, type HerdrRunner, type HerdrResult, type HerdrMarkerPid } from "./herdr.js";
+export { HerdrTransport, defaultHerdrRunner, interpretHerdrReply, herdrKeyName, herdrPaneExists, herdrMarkerPid, submitModeOf, SUBMIT_MODE_ENV_VAR, HERDR_KEYS, HERDR_ABSENT_MESSAGE, type HerdrRunner, type HerdrResult, type HerdrMarkerPid, type SubmitMode } from "./herdr.js";
 
 let host: TmuxHost | undefined;