trantor 0.18.58 → 0.18.59

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.58",
+  "version": "0.18.59",
   "description": "Trantor — the hub-world for AI agent crews: live message bus, presence, project Kanban/flow board + crew orchestration for independent AI coding agents (Claude, Codex, Gemini, Kimi, DeepSeek)",
   "mcpServers": {
     "relay": {

package/bin/crew-runner.mjs

@@ -284,7 +284,7 @@ if (!CLI[AGENT]) log(`'${AGENT}' is not a built-in seat — running it as an ope
 
 // RUNNER_RULES / RUNNER_KICKOFF env overrides: the runner is also the substrate for non-crew
 // always-on seats (the fleet DUTY agent, bin/duty.mjs) whose doctrine is not "work your card".
-const RULES = process.env.RUNNER_RULES || `Rules: you are ${SESSION} on the trantor crew. Before starting a card, read YOUR card: relay_board with card:<id> (the card, its deps, its notes, and the last five done cards whose title shares a word); never the whole board. Work your assigned file(s), report on the bus (relay_send, <280 chars), move your Kanban card as you go with a NOTE saying what you did (doing -> testing -> done; in 'testing' run YOUR OWN test file — never the full npm test, suites collide across seats — plus \`node bin/slop-gate.mjs\` when the repo has one: it lints ONLY your changed files against the anti-slop rules, and a card must not reach done with slop-gate failing; use 'failed' + a report if anything breaks). If you need something from another session, message THAT SESSION (relay_peers to find its id, relay_send to reach it) — never ask the human to pass it along; carrying messages between agents is the job this bus exists to remove. When your work for THIS message is finished, END YOUR TURN — do NOT park, do NOT loop relay_wait; the runner waits for you and will wake you with the next message. Path discipline: build/test from your worktree root ${TURN_DIR} with absolute paths or --manifest-path/--prefix instead of cd-ing into subdirs, and put anything that must land outside the repo under ${TURN_DIR}/.agent-bus-out/ (gitignored) — never ~/.agent-bus. Realigning your seat branch after the orchestrator harvested your commits is \`trantor sync\` run from your worktree: it reads the harvest receipts and refuses when an unharvested commit would be lost, so never reset or rebase onto main by hand. Cross-project action is a breach: never \`trantor up\` a crew, register a seat, or send a card/contract into a project other than ${PROJ} unless the operator ran \`trantor policy link ${PROJ} <other> --reason "<why>"\` first — the hub, the CLI and this runner all refuse it mechanically, so ask the operator to link the projects instead of routing around the refusal.`;
+const RULES = process.env.RUNNER_RULES || `Rules: you are ${SESSION} on the trantor crew. Before starting a card, read YOUR card: relay_board with card:<id> (the card, its deps, its notes, and the last five done cards whose title shares a word); never the whole board. Work your assigned file(s), report on the bus (relay_send, <280 chars), move your Kanban card as you go with a NOTE saying what you did (doing -> testing -> done; in 'testing' run YOUR OWN test file — never the full npm test, suites collide across seats — plus \`node bin/slop-gate.mjs\` when the repo has one: it lints ONLY your changed files against the anti-slop rules, and a card must not reach done with slop-gate failing; use 'failed' + a report if anything breaks). If a contract omits a fact you cannot proceed without, ASK — never invent the value: relay_ask(<card>, <question>) blocks the card with your question, keeps the turn owed (no park, no failure), and resumes you when the assigner's answer lands; an invented value that reads as reasoned is the worst outcome this crew ships (#7756). If you need something from another session, message THAT SESSION (relay_peers to find its id, relay_send to reach it) — never ask the human to pass it along; carrying messages between agents is the job this bus exists to remove. When your work for THIS message is finished, END YOUR TURN — do NOT park, do NOT loop relay_wait; the runner waits for you and will wake you with the next message. Path discipline: build/test from your worktree root ${TURN_DIR} with absolute paths or --manifest-path/--prefix instead of cd-ing into subdirs, and put anything that must land outside the repo under ${TURN_DIR}/.agent-bus-out/ (gitignored) — never ~/.agent-bus. Realigning your seat branch after the orchestrator harvested your commits is \`trantor sync\` run from your worktree: it reads the harvest receipts and refuses when an unharvested commit would be lost, so never reset or rebase onto main by hand. Cross-project action is a breach: never \`trantor up\` a crew, register a seat, or send a card/contract into a project other than ${PROJ} unless the operator ran \`trantor policy link ${PROJ} <other> --reason "<why>"\` first — the hub, the CLI and this runner all refuse it mechanically, so ask the operator to link the projects instead of routing around the refusal.`;
 
 // ---- the pulse --------------------------------------------------------------
 // RUNNER_PULSE_MS re-runs an orchestrator seat's mission note on a cadence when the bus is silent;
@@ -331,6 +331,11 @@ function startDutyNudgeWatcher(plan, sinceMs) {
 // The hub hands a message out exactly once, so a turn that died took its wake with it. Here a
 // message is consumed only when a turn exits 0; the queue lives on disk and retries on backoff.
 const PENDF = join(homedir(), ".agent-bus", `pending-${AGENT}-${PROJ}.json`);
+// #7778: message ids this seat already consumed through its OWN inbox path (relay_inbox, the
+// PostToolUse hook) — reconciled from the hub's deliveredUpTo ledger at each clean turn boundary
+// and persisted in the pending file, so a message the session read mid-turn is never re-woken by
+// the poll, across turn AND process boundaries.
+let seenLedger = [];
 // A cap, so a long outage cannot grow the queue without bound. Overflow drops the OLDEST and says
 // so on the bus — a silent drop is the exact failure this whole mechanism exists to end.
 const PENDING_MAX = 50;
@@ -345,17 +350,45 @@ const RETRY_MS = (() => {
   const custom = raw ? raw.split(",").map(Number).filter(n => Number.isFinite(n) && n > 0) : [];
   return custom.length ? custom : [30e3, 60e3, 120e3, 300e3, 900e3];
 })();
+// #7756: while an ask awaits its answer the contract's wake stays owed but is NOT redelivered —
+// the answer (re = the ask's id, or any direct word from the assigner) is what releases it.
+let awaitingAsk = null;
+// The bus is the record of a turn that ended by ASKING: an open kind:ask contract from this
+// session. deliverWake judges each clean wake turn against /contracts — an open ask renames the
+// ledger row "asked" and HOLDS the wake (no failure count, no backoff, no park) until the answer.
+let turnAsk = null;
+async function askJudge() {
+  try {
+    const r = await api(`/contracts?session=${encodeURIComponent(SESSION)}&project=${encodeURIComponent(PROJ)}`);
+    // abandonedContracts included on purpose: an ask to a gone-quiet assigner is exactly the ask
+    // that must keep holding, and the hub files those rows under their own key (#7079).
+    const rows = [...(r?.contracts || []), ...(r?.abandonedContracts || [])];
+    const open = rows.filter(c => c.kind === "ask" && !c.answered);
+    turnAsk = open.length ? { id: open[open.length - 1].id, to: String(open[open.length - 1].to || "") } : null;
+    return turnAsk ? "asked" : null;
+  } catch { return null; }
+}
 function savePending(wake, bcast) {
   try {
-    if (!wake.length && !bcast.length) { try { unlinkSync(PENDF); } catch {} return; }
-    writeFileSync(PENDF, JSON.stringify({ agent: AGENT, project: PROJ, ts: Date.now(), wake, bcast }));
+    // the seen-set (#7778) and a held ask (#7756) keep the file alive even with both queues empty:
+    // the dedupe ledger outlives the deliveries it guards, and a restarted runner must wait for
+    // the answer instead of redelivering the very contract the seat already asked about.
+    if (!wake.length && !bcast.length && !seenLedger.length && !awaitingAsk) { try { unlinkSync(PENDF); } catch {} return; }
+    writeFileSync(PENDF, JSON.stringify({ agent: AGENT, project: PROJ, ts: Date.now(), wake, bcast, seen: seenLedger, ask: awaitingAsk?.id || 0, askTo: awaitingAsk?.to || "" }));
   } catch {}
 }
 function loadPending() {
   try {
     const j = JSON.parse(readFileSync(PENDF, "utf8"));
-    return { wake: Array.isArray(j.wake) ? j.wake : [], bcast: Array.isArray(j.bcast) ? j.bcast : [] };
-  } catch { return { wake: [], bcast: [] }; }
+    return {
+      wake: Array.isArray(j.wake) ? j.wake : [],
+      bcast: Array.isArray(j.bcast) ? j.bcast : [],
+      seen: Array.isArray(j.seen)
+        ? j.seen.filter(e => e && Number.isFinite(Number(e.id))).map(e => ({ id: Number(e.id), ts: Number(e.ts) || 0 }))
+        : [],
+      ask: Number(j.ask) || 0, askTo: String(j.askTo || ""),
+    };
+  } catch { return { wake: [], bcast: [], seen: [], ask: 0, askTo: "" }; }
 }
 
 // Auth failures in TURN OUTPUT: opencode prints its auth error and still exits 0 (#5405). The rules
@@ -835,7 +868,13 @@ exit $turn_exit`;
   // api-error (the CLI failed), completed — and what it cost in tokens, even when this CLI printed
   // no usage line (0 means "not reported", never "free"). `cut` stays too: the drills read it.
   const outcome = cut ? "cut" : (effExit !== 0 ? "api-error" : lastEmptyTurn ? "empty" : "completed");
-  const telemetryRow = { ts: Date.now(), agent: AGENT, project: PROJ, turn: TURN, trigger, model: MODEL || "cli-default", duration_ms: Date.now() - t0, exit: realExit, effExit, authFailed: effExit !== realExit, emptyOutput: lastEmptyOutput, emptyTurn: lastEmptyTurn, verdict, outcome, tokens };
+  // #7756: a clean turn that ASKED its assigner is demoted-but-owed, not "completed". The judge
+  // (deliverWake's /contracts read) renames the ledger row, so "asked" is what the log keeps.
+  let finalOutcome = outcome;
+  if (outcome === "completed" && opts.judgeOutcome) {
+    try { finalOutcome = (await opts.judgeOutcome()) || outcome; } catch {}
+  }
+  const telemetryRow = { ts: Date.now(), agent: AGENT, project: PROJ, turn: TURN, trigger, model: MODEL || "cli-default", duration_ms: Date.now() - t0, exit: realExit, effExit, authFailed: effExit !== realExit, emptyOutput: lastEmptyOutput, emptyTurn: lastEmptyTurn, verdict, outcome: finalOutcome, tokens };
   if (cut) telemetryRow.cut = true;
   telemetry(telemetryRow);
   log(`turn ended (exit ${realExit}${effExit !== realExit ? ` → effective ${effExit} (${lastEmptyOutput ? "empty-output" : "auth"})` : ""}, ${((Date.now() - t0) / 1000).toFixed(0)}s)`);
@@ -1051,6 +1090,12 @@ function askedExcerpt(message) {
   // broadcasts batched behind them. Restored from disk first: a runner that was killed mid-turn
   // (or a machine that rebooted) still owes those messages, and the hub will never send them again.
   const restored = loadPending();
+  seenLedger = restored.seen;
+  if (seenLedger.length) log(`\x1b[33m${seenLedger.length} consumed message id(s) restored from the pending file — the poll keeps standing down on them\x1b[0m`);
+  if (restored.ask) {
+    awaitingAsk = { id: restored.ask, to: restored.askTo };
+    log(`resuming a held ask (#${awaitingAsk.id}) — the queue stays owed until ${awaitingAsk.to || "the assigner"} answers`);
+  }
   // Say what the restore SHED, not just what it kept. A queue that quietly halves itself on restart
   // is indistinguishable from one that lost real work, and this is the moment the expiry above
   // actually bites — a wedged seat comes back carrying only what still means something.
@@ -1073,6 +1118,10 @@ function askedExcerpt(message) {
   stateSkip("kickoff");
   const ec0 = await runTurn(composedTurn({ base: KICKOFF, lessons: pickLessons(LESSONS_RAW, "") }), true, "kickoff");
   if (ec0) await reportFailure(ec0, "kickoff", pendingWake.length);   // a failed kickoff = the "fired up, died, nobody knew" case
+  // #7778: the kickoff is a turn like any other — a message that landed mid-kickoff and was read
+  // through the session's own inbox is consumed by a successful kickoff, and the first poll must
+  // not wake on it. Same reconcile, same clean-boundary rule as deliverWake below.
+  else await reconcileSessionReads(cursor);
   let lastTurnAt = Date.now();
   if (PULSE_MS) log(`pulse armed — mission re-read every ${Math.round(PULSE_MS / 1000)}s (${MISSION_FILE})`);
   log(`parked — long-polling the bus as ${SESSION} (free; this poll is also the heartbeat)`);
@@ -1083,18 +1132,21 @@ function askedExcerpt(message) {
     if (PULSE_MS && Date.now() - lastTurnAt >= PULSE_MS) {
       stateSkip("pulse");
       const ecp = await runTurn(composedTurn({ base: PULSE_PROMPT + "\n\n", rulesText: RULES, lessons: pickLessons(LESSONS_RAW, PULSE_PROMPT) }), false, "pulse");
-      if (ecp) await reportFailure(ecp, "pulse"); else await reportHealthy();
+      // #7778: a pulse turn is also a clean boundary when it succeeds — same reconcile rule.
+      if (ecp) await reportFailure(ecp, "pulse");
+      else { await reconcileSessionReads(cursor); await reportHealthy(); }
       lastTurnAt = Date.now();
       log("parked — waiting for the next message or pulse");
       continue;
     }
     // A due REDELIVERY runs before we go back to waiting — during an outage the bus is silent by
     // definition, so the retry timer is the only thing that will ever move these messages.
-    if (pendingWake.length && Date.now() >= retryAt) { await deliverWake(); continue; }
+    // #7756: a held ask is owed but NEVER redelivered — only the assigner's answer releases it.
+    if (pendingWake.length && !awaitingAsk && Date.now() >= retryAt) { await deliverWake(); continue; }
     // cap the long-poll hold so neither a due pulse nor a due redelivery waits out a silent 280s window
     const due = [];
     if (PULSE_MS) due.push(PULSE_MS - (Date.now() - lastTurnAt));
-    if (pendingWake.length) due.push(retryAt - Date.now());
+    if (pendingWake.length && !awaitingAsk) due.push(retryAt - Date.now());
     const holdS = due.length
       ? Math.max(5, Math.min(280, Math.ceil(Math.min(...due) / 1000)))
       : 280;
@@ -1123,6 +1175,23 @@ function askedExcerpt(message) {
     // reply-linked outcomes, and the old stable marker before direct-address logic sees them. Status
     // broadcasts are presence chatter and are dropped rather than saved as future prompt context.
     msgs = msgs.filter(m => !isReceipt(m) && !isStatusBroadcast(m));
+    // #7778: ids in the seen-set were already handed to the model through the session's own inbox
+    // read mid-turn (the reconcile at the last clean turn boundary recorded them). The poll still
+    // serves them — it filters by THIS runner's cursor, not the shared ledger — so the second
+    // reader stands down here, and the cursor adopts the consumed ids so the hub stops re-serving.
+    // Filtering BEFORE the wake/bcast split keeps a dupe out of the demoted-sender notice too:
+    // the seat DID turn on that message, and #7766's notice must not say otherwise.
+    if (seenLedger.length) {
+      const seenIds = new Set(seenLedger.map(e => e.id));
+      const dupes = msgs.filter(m => seenIds.has(m.id));
+      if (dupes.length) {
+        log(`duplicate delivery suppressed — ${dupes.map(m => `#${m.id}`).join(", ")} already consumed by the session's own inbox read`);
+        msgs = msgs.filter(m => !seenIds.has(m.id));
+        const top = Math.max(...dupes.map(m => m.id));
+        if (top > cursor) cursor = top;
+        seenLedger = seenLedger.filter(e => e.id > cursor);
+      }
+    }
     // #5760: the hub's hourly same-project-sessions FYI is coordination context, batched like a
     // broadcast; file-conflict and linked-activity overseer warnings still wake.
     const fyi = msgs.filter(m => m.from === "hub:duty" && String(m.text || "").startsWith("🤝 OVERSEER same-project-sessions"));
@@ -1173,6 +1242,15 @@ function askedExcerpt(message) {
         kind: "status", text: `⚠️ ${SESSION} dropped ${dropped.length} undelivered message(s) — queue hit its ${PENDING_MAX} cap during a failure streak` }).catch(() => {});
     }
     savePending(pendingWake, pendingBcast);
+    // #7756: the assigner's answer releases a held ask — by `re` on the ask's id, or any direct
+    // word from the assigner (an older peer answers untagged). The owed contract is still queued
+    // ahead of it, so the resumed turn reads the contract re-attached above the answer.
+    if (awaitingAsk && wake.some(m => m.to === SESSION && (Number(m.re) === awaitingAsk.id || m.from === awaitingAsk.to))) {
+      log(`answer to ask #${awaitingAsk.id} landed — resuming with the contract re-attached`);
+      awaitingAsk = null;
+      savePending(pendingWake, pendingBcast);
+    }
+    if (awaitingAsk) { log(`holding for the answer to ask #${awaitingAsk.id} — ${wake.length} new message(s) queued behind it`); continue; }
     // Respect an active backoff: a new message during an outage joins the batch, it does not
     // reset the clock and hammer a CLI that is already failing.
     if (Date.now() < retryAt) { log(`queued — ${pendingWake.length} undelivered, next attempt in ${Math.max(0, Math.round((retryAt - Date.now()) / 1000))}s`); continue; }
@@ -1182,6 +1260,31 @@ function askedExcerpt(message) {
 
   // Run the pending batch. The messages are cleared ONLY on exit 0; any other outcome leaves them
   // queued, on disk, with a backoff — which is the whole point of the change.
+  // #7778 — one message, one delivery, whichever path sees it first. The session's own inbox read
+  // and this runner's /poll are two readers of one bus with no shared cursor: a message the seat
+  // read and answered MID-TURN was re-polled after the turn and woken AGAIN (seen live: a seat
+  // answered inside its turn, then a second turn 16s later re-quoted the same message verbatim).
+  // The hub's deliveredUpTo is the one ledger both paths already write, so at a CLEAN turn
+  // boundary every id above our poll cursor but at-or-below it was necessarily consumed by the
+  // session-side path. Those ids go into the persisted seen-set; the poll filter stands the
+  // second reader down. A failed, parked or hollow turn reconciles NOTHING — dedupe must never
+  // swallow a message the seat still owes, so only full success is trusted to mark history read.
+  async function reconcileSessionReads(upToCursor) {
+    try {
+      const peer = await api(`/peer?session=${encodeURIComponent(SESSION)}`);
+      const readUpTo = Number(peer?.deliveredUpTo || 0);
+      // A delta wider than one turn could plausibly carry is a corrupt or rewound ledger: mark
+      // nothing. Non-marking only risks the duplicate this fixes, never a lost message.
+      if (!(readUpTo > upToCursor) || readUpTo - upToCursor > 10000) return 0;
+      for (let id = upToCursor + 1; id <= readUpTo; id++) seenLedger.push({ id, ts: Date.now() });
+      seenLedger = seenLedger.filter(e => e.id > upToCursor).slice(-500);
+      // persist HERE, at every caller: a runner killed seconds after the boundary is exactly the
+      // restart the restored seen-set exists for.
+      savePending(pendingWake, pendingBcast);
+      log(`dedupe: message id(s) ${upToCursor + 1}..${readUpTo} were consumed by the session's own inbox read — the poll will not wake on them again`);
+      return readUpTo - upToCursor;
+    } catch { return 0; }
+  }
   async function deliverWake() {
     const wake = pendingWake;
     const dutyPlan = DUTY_NUDGES
@@ -1257,6 +1360,7 @@ function askedExcerpt(message) {
     });
     const stopDutyNudgeWatcher = startDutyNudgeWatcher(dutyPlan, tStart);
     let ec;
+    turnAsk = null;   // #7756: the judge reads THIS turn's ending, never a previous turn's ask
     const stateStep = !stateSkip("wake", card);
     try {
       ec = stateStep
@@ -1268,7 +1372,7 @@ function askedExcerpt(message) {
           // dies quietly (§4.6).
           observation: [stateObservation, wakeText, ctxText, againText + freshText].filter(Boolean).join("\n"),
         })
-        : await runTurn(prompt, fresh, deliveryFails ? `${trigger} (redelivery)` : trigger);
+        : await runTurn(prompt, fresh, deliveryFails ? `${trigger} (redelivery)` : trigger, { judgeOutcome: askJudge });
     }
     finally { stopDutyNudgeWatcher(); }
     const secs = Math.round((Date.now() - tStart) / 1000);
@@ -1350,6 +1454,14 @@ function askedExcerpt(message) {
       await notifyAssigners(assigners,
         `⚠️ your contract FAILED on ${SESSION} (exit ${ec}, ${reason}) · retrying in ${Math.round(wait / 1000)}s · asked: "${asked}"`);
       log(`\x1b[31m${pendingWake.length} message(s) still UNDELIVERED — next attempt in ${Math.round(wait / 1000)}s\x1b[0m`);
+    } else if (turnAsk) {
+      // #7756: a clean exit that ASKED is not "done". The wake stays owed — queued on disk with
+      // the ask's id, so a restart keeps holding — and the failure ladder never sees it. The
+      // assigner is NOT notified here: the kind:ask message itself is already that notification.
+      awaitingAsk = turnAsk; turnAsk = null;
+      savePending(pendingWake, pendingBcast);
+      await reportHealthy();
+      log(`turn asked its assigner — holding the contract until ask #${awaitingAsk.id} is answered`);
     } else if (lastEmptyTurn) {
       // #7759: the turn exited 0 but was HOLLOW — a banner is not work. The wake is NOT
       // consumed: the queue is kept and the ladder retries, and the assigner hears EMPTY,
@@ -1370,6 +1482,8 @@ function askedExcerpt(message) {
         `🫥 EMPTY turn on ${SESSION} (exit 0, ${secs}s — no worktree change, no substantive output, no bus activity) · wake stays owed · retrying in ${Math.round(wait / 1000)}s · asked: "${asked}"`);
     } else {
       pendingWake = []; pendingBcast = []; deliveryFails = 0; retryAt = 0;
+      // #7778: reconcile BEFORE the write below so the persisted snapshot carries the seen-set.
+      await reconcileSessionReads(cursor);
       savePending([], []);
       await reportHealthy();
       await notifyAssigners(assigners,

package/hub/reaper.mjs

@@ -82,12 +82,10 @@ function appendReaperStaleLog(t, reason, ts) {
   const lastSeen = seen ? `${humanMs(ts - seen)} ago` : "never";
   appendTaskLog(t, "reaper", `${reason}; owner last seen ${lastSeen}`, ts);
 }
-// The general stale-card reaper prunePeers never was. Every 60s:
-//  (a) close a focus card once its session has been OFFLINE past FOCUS_OFFLINE_MS (not the old 6h peer TTL).
-//  (b) move an OFFLINE-owner doing card to "stale" once it's untouched past REAP_GRACE_MS.
-// Testing is waiting for the operator's verdict and is therefore outside the reaper's authority.
-// It NEVER touches a card whose owner is still online, so a live long task is safe; the owner-alive-but-idle
-// "forgot its card" case is left to the explicit /sweep path (preview + confirm).
+// The general stale-card reaper prunePeers never was. Every 60s: (a) close a focus card whose
+// session is OFFLINE past FOCUS_OFFLINE_MS; (b) stale an offline-owner doing card past REAP_GRACE_MS.
+// Testing (the operator's verdict) and online owners are NEVER touched — the owner-alive-but-idle
+// case belongs to the explicit /sweep path (preview + confirm).
 function reapStaleCards() {
   const onCut = now() - ONLINE_MS;
   const focusCut = now() - FOCUS_OFFLINE_MS;
@@ -133,20 +131,10 @@ function reapStaleCards() {
 }
 setInterval(reapStaleCards, REAP_INTERVAL_MS).unref?.();
 
-// ---- the contract ledger -------------------------------------------------------------------
-// ONE derivation, shared by GET /contracts and the reaper below. Two copies of this is how you get
-// an endpoint and a sweeper that disagree about what is open, which is the same "two names for one
-// intent" mistake the spawn guards made.
-//
-// A contract is a DIRECT message from `session` to one peer. It closes when that peer answers:
-// strictly by `re`, or, for seats that predate that column, oldest-open-first. Excluded outright,
-// because none of these can ever be answered and so would hang open forever:
-//   - broadcasts (`to === "all"`)
-//   - self-dispatch (`from === to`) — a reply from yourself is never counted as an answer
-//   - the hub's own pseudo-identities (`hub:*`) and hub-authored mail — nothing polls them (0.17.87)
-// Durations an agent READS and acts on, so they must not round to nonsense. Minutes are the useful
-// unit in production (the abandon window is an hour), but the drills run in seconds and "past the 0m
-// abandon window" is a sentence that tells the reader nothing.
+// ---- the contract ledger: ONE derivation shared by GET /contracts and the reaper below ---------
+// A contract is a DIRECT message from `session` to one peer, closed when that peer answers:
+// strictly by `re`, or, for seats that predate that column, oldest-open-first. Broadcasts,
+// self-dispatch and hub:* identities are excluded — none can ever be answered (0.17.87).
 function humanMs(ms) {
   const n = Math.max(0, Number(ms) || 0);
   if (n < 60000) return `${Math.max(1, Math.round(n / 1000))}s`;
@@ -158,11 +146,10 @@ function contractRecipientIsAnswerable(m) {
   return !!m.to && m.to !== "all" && m.from !== m.to && !m.to.startsWith("hub:") && !m.from.startsWith("hub:");
 }
 
-// A direct message the SENDER declared owes nothing back (#7079). `wake:false` is the sender saying
-// "context, not a contract" — the send result even prints "(batched — no turn)" — and a `receipt` or
-// `status` is a report, not a request. None of these ever buys the recipient a turn, so none can be
-// answered; counted as contracts they age into `stalled` and block the dispatcher's stop hook over
-// work that was never owed (four times in one day, every row an ack to an idle seat).
+// A direct message the SENDER declared owes nothing back (#7079): `wake:false` ("context, not a
+// contract"), a `receipt`, or a `status` never buys the recipient a turn, so none can be answered —
+// counted as contracts they age into `stalled` and block the dispatcher's stop hook over work that
+// was never owed.
 function contractIsAck(m) {
   return m.wake === false || m.kind === "receipt" || m.kind === "status";
 }
@@ -175,10 +162,12 @@ function contractsFor(session, { project = "", windowMs = CONTRACT_WINDOW_MS, ov
   const mine = state.messages.filter(m =>
     m.from === session && m.ts >= cutoff && contractRecipientIsAnswerable(m) && (!project || m.project === project));
   const replies = state.messages.filter(m => m.to === session && m.from !== session && m.ts >= cutoff);
+  // #7756: an ask (kind:"ask") rides `re` to name the contract it QUESTIONS — it is not the answer.
+  // Counted as one, the contract would read answered while the seat sits blocked waiting.
   const byRe = new Map();
-  for (const r of replies) if (r.re) byRe.set(Number(r.re), r);
+  for (const r of replies) if (r.re && r.kind !== "ask") byRe.set(Number(r.re), r);
   const looseByPeer = new Map();
-  for (const r of replies) if (!r.re) { if (!looseByPeer.has(r.from)) looseByPeer.set(r.from, []); looseByPeer.get(r.from).push(r); }
+  for (const r of replies) if (!r.re && r.kind !== "ask") { if (!looseByPeer.has(r.from)) looseByPeer.set(r.from, []); looseByPeer.get(r.from).push(r); }
   for (const arr of looseByPeer.values()) arr.sort((a, b) => a.ts - b.ts);
 
   const out = [];
@@ -227,17 +216,8 @@ function contractsFor(session, { project = "", windowMs = CONTRACT_WINDOW_MS, ov
 
   // ---- superseded: the terminal state for a row nobody will ever answer ------------------------
   // `abandoned` keys on the ASSIGNEE being gone, so a permanently HEALTHY seat could strand a
-  // contract forever: it can never be answered (that seat's replies all carry `re` for other
-  // contracts, so the loose-reply fallback above never claims this one) and it can never be
-  // abandoned (the seat is alive). The row then blocks its dispatcher's stop hook every single
-  // turn, for days — observed on #10573 across two consecutive sessions.
-  //
-  // TWO signals must agree, because either alone is wrong. "The peer answered something newer" on
-  // its own would punish honest out-of-order completion — a seat handed three jobs may finish the
-  // third first and still be working the second, which is a real pattern this suite already drills.
-  // Age on its own would punish a seat legitimately grinding one long job. Together they are only
-  // true when the assignee is alive, has moved on to later work, AND the row has sat unanswered
-  // past the window in which any genuine in-flight job would have reported.
+  // contract forever — unanswerable, yet never abandoned — blocking the stop hook for days (#10573).
+  // Two signals must agree (a newer answer AND age past the window) so out-of-order completion is safe.
   const newestAnswered = new Map();
   for (const c of out) {
     if (c.answered && c.ts > (newestAnswered.get(c.to) || 0)) newestAnswered.set(c.to, c.ts);
@@ -248,20 +228,9 @@ function contractsFor(session, { project = "", windowMs = CONTRACT_WINDOW_MS, ov
     if (c.ts < (newestAnswered.get(c.to) || 0)) c.disposition = "superseded";
   }
   // ---- superseded by a later DIRECT reply: the morning case (#11047/#11048) --------------------
-  // A row can be unanswerable by a seat that is perfectly healthy: its later replies all carry `re`
-  // for NEWER contracts (a re-dispatch, or an "ack by reference" threaded to the newer id), so
-  // neither byRe nor the loose fallback ever claims the old row — the two matchers above only ever
-  // see replies aimed at the NEWER work. The row then sits WAITING forever: it can never be
-  // answered, it can never be abandoned (the seat is alive), and the newestAnswered rule above
-  // misses it whenever the newer work was dispatched under a peer identity the old row never shares.
-  //
-  // The signal both matchers ignored is the DIRECT reply itself: if the assignee has sent this
-  // session ANY message after the row was dispatched, the assignee is alive, reachable, and has
-  // demonstrably moved on to later work — an older row that has then sat unanswered past the
-  // abandon window is dead weight, not in flight. Age still gates it, so honest out-of-order
-  // completion (a seat that answered a newer job while still working an older one) is never
-  // punished — the older row stays open until the window that any genuine in-flight job would have
-  // reported within has passed.
+  // Both matchers above only see replies aimed at NEWER work, so a healthy seat whose replies are
+  // all `re`-threaded to newer contracts strands the old row even when newestAnswered misses it.
+  // ANY later direct reply + past the abandon window = moved on; age gates out-of-order completion.
   const latestDirectReply = new Map();
   for (const r of replies) {
     if (r.ts > (latestDirectReply.get(r.from) || 0)) latestDirectReply.set(r.from, r.ts);
@@ -285,10 +254,8 @@ function contractDispatchers(windowMs = CONTRACT_WINDOW_MS) {
 }
 
 // The contract reaper. Records — never invents an answer for — a contract whose assignee has been
-// quiet past CONTRACT_ABANDON_MS, so the abandonment survives a hub restart (in-memory-only state is
-// exactly why the escalation backlog re-fires on every restart) and shows up once in the FEED.
-// After this the contract stops counting as open, so it stops nagging every future session; it stays
-// listed with its evidence, so `relay_contracts` can still show what died.
+// quiet past CONTRACT_ABANDON_MS, persisted so the abandonment survives a hub restart and shows once
+// in the FEED. It stops counting as open but stays listed with its evidence for `relay_contracts`.
 function reapAbandonedContracts() {
   let changed = false;
   for (const session of contractDispatchers()) {

package/hub/routes/messages.mjs

@@ -4,7 +4,7 @@ import { setTimeout, setInterval, clearInterval } from "node:timers";
 export async function routeMessages({ req, res, q, P, auth, ctx }) {
   const {
     state, body, json, stripNulText, crossProjectGuard, touch, pushToStreams,
-    appendEvent, markDelivered, contractsFor, canUseInboxSession, inboxWindow,
+    appendEvent, appendCardEvent, appendTaskLog, markDelivered, contractsFor, canUseInboxSession, inboxWindow,
     deliverable, inboxReadable, inboxResponse, filterReadable, streams, UI,
     AUTH_MODE, persistHealth, duty, now, markDirty, assertNoSecrets,
     CONTRACT_WINDOW_MS,
@@ -39,20 +39,28 @@ export async function routeMessages({ req, res, q, P, auth, ctx }) {
       // that field is the card-event key, and /card must keep counting card events only.
       const refs = [...new Set((msg.text.match(/#(\d{1,7})(?![0-9])/g) || []).map(s => Number(s.slice(1))))].slice(0, 8);
       appendEvent("message", msg.project, msg.from, { msgId: msg.id, toSession: msg.to, text: msg.text.slice(0, 2000), refs });
+      // #7756: the ask primitive's board half — a kind:ask blocks the card it cites (the question is
+      // the note, so the board reads why nothing moves); the answer (re = the ask's id) unblocks it.
+      const askCardMove = (cardId, to, noteText) => {
+        const t = cardId && state.tasks.find(x => x.id === cardId && x.project === msg.project);
+        if (!t || t.status === to || (to === "doing" && t.status !== "blocked")) return;
+        const from = t.status;
+        (t.history ||= []).push({ from, to, by: msg.from, ts: now() });
+        if (t.history.length > 40) t.history.splice(0, 10);
+        t.status = to; t.updated = now();
+        appendTaskLog(t, msg.from, noteText); appendCardEvent("moved", t, msg.from, from, to); markDirty();
+      };
+      if (kind === "ask") askCardMove(refs[0] || 0, "blocked", msg.text);
+      else if (re) {
+        const opened = state.messages.find(m => m.id === re && m.kind === "ask");
+        if (opened) askCardMove(Number((String(opened.text).match(/#(\d{1,7})(?![0-9])/) || [])[1] || 0), "doing", `answered: ${text}`);
+      }
       return json(res, 200, { ok: true, id: msg.id });
     }
     // ---- /contracts: what this session dispatched and has not been answered on ----------------
-    // A contract is a DIRECT message from you to one peer. It closes when that peer sends you an
-    // outcome: strictly by `re`, or, for seats that predate it, oldest-open-first. Broadcasts are
-    // never contracts. Each open one carries the assignee's presence, because the actionable half
-    // of "still waiting" is whether anyone is still on the other end.
-    // ---- /delivered: an endpoint that has actually READ its mail says so ----------------------
-    // The desktop app lists with peek=1 on purpose, so it never steals a message from a session's
-    // delivery hooks. For a HUMAN endpoint there are no hooks — the app is the only reader — so
-    // sasha@mac's deliveredUpTo sat at 0 forever while mail piled up. dutyTick then escalated every
-    // message the human had already read, told the duty seat about it, the seat messaged the human,
-    // and that was undelivered too: about six escalations a minute, all about mail already read.
-    // Peeking stays the default; this lets a reader record delivery explicitly instead.
+    // Open contracts carry the assignee's presence — the actionable half of "still waiting" is
+    // whether anyone is on the other end. /delivered lets a HUMAN endpoint (the app peeks, never
+    // steals) record delivery explicitly, so duty stops escalating mail the human already read.
     if (req.method === "POST" && P === "/delivered") {
       const b = await body(req);
       const session = String(b.session || "");
@@ -73,19 +81,10 @@ export async function routeMessages({ req, res, q, P, auth, ctx }) {
       const overdueMs = Number.isFinite(rawOverdue) ? Math.max(0, rawOverdue) : null;
       const all = contractsFor(session, { project: String(q.project || ""), windowMs, overdueMs });
       const by = (d) => all.filter(c => c.disposition === d).length;
-      // Abandoned contracts leave `contracts` entirely and ride in their own key.
-      //
-      // Not cosmetic. A session's hooks are PINNED at session start, so an older stop hook iterates
-      // `contracts` with its own predicate and knows nothing about `disposition` — it kept blocking on
-      // ghosts no matter what the hub called them. Keeping them in the array meant the fix only
-      // reached sessions that restarted, and a live one nagged its operator every single turn.
-      // Splitting them out fixes every running session the moment the hub redeploys, and the ledger
-      // still shows what died via `abandonedContracts`.
-      // `superseded` leaves `contracts` for exactly the reason `abandoned` does: a session's hooks
-      // are PINNED at session start, so an older stop hook filters this array with its own
-      // predicate and would keep blocking on a row the hub has already settled.
-      // `ack` leaves `contracts` too (#7079): a `wake:false` send, a `receipt` or a `status` is the
-      // sender declaring nothing is owed, so an old pinned hook must never see it as a row to block on.
+      // Abandoned/superseded/ack contracts leave `contracts` and ride in their own keys (#7079).
+      // Not cosmetic: a session's hooks are PINNED at session start, so an older stop hook filters
+      // this array with its own predicate and would keep blocking on rows the hub already settled —
+      // splitting them out fixes every running session the moment the hub redeploys.
       const out = all.filter(c => c.disposition !== "abandoned" && c.disposition !== "superseded" && c.disposition !== "ack");
       return json(res, 200, {
         session, contracts: out, abandonedContracts: all.filter(c => c.disposition === "abandoned"),

package/mcp.mjs

@@ -442,6 +442,33 @@ server.tool("relay_send", "Send a live message to another agent session (or 'all
     return { content: [{ type: "text", text: `sent #${id} to ${to}${wake === false ? " (batched — no turn)" : ""}` }] };
   });
 
+server.tool("relay_ask", "Ask a BLOCKING question on your card without forfeiting the contract (#7756). This is the correct move when the contract omits a fact you cannot proceed without — never invent the value. Sends a kind:ask message to the card's assigner: the hub blocks the card with your question as its note so the board reads why nothing is moving, your runner keeps the wake owed (no failure, no park), and the assigner's answer resumes THIS session with the original contract re-attached. End your turn right after calling it.",
+  { card: z.number().describe("the card your current contract is working"),
+    question: z.string().describe("the ONE missing fact you cannot proceed without, stated precisely") },
+  async ({ card, question }) => {
+    // Append-only log rule, same as relay_send: a secret is refused BEFORE anything reaches the hub.
+    const scrub = assertNoSecrets(question);
+    if (!scrub.ok) return { content: [{ type: "text", text: `REFUSED — not sent. Credential-shaped string(s) detected: ${scrub.kinds.join(", ")}. Remove them and resend.` }], isError: true };
+    const { task } = await api("GET", `/card?project=${encodeURIComponent(PROJECT)}&id=${card}`);
+    if (!task) return { content: [{ type: "text", text: `${PROJECT}: no card #${card}` }], isError: true };
+    // The assigner is who DISPATCHED the card (by); the assignee is usually this seat itself.
+    const assigner = task.by && task.by !== SESSION ? task.by
+      : task.assignee && task.assignee !== SESSION ? task.assignee : "";
+    if (!assigner) return { content: [{ type: "text", text: `card #${card} has nobody to ask (by=${task.by || "?"}, assignee=${task.assignee || "?"})` }], isError: true };
+    // `re` threads the ask to the contract it questions: the assigner's latest direct message to
+    // this session, preferring one that cites this card. Peek only — the hooks own delivery.
+    let re = 0;
+    try {
+      const { messages } = await api("GET", `/inbox?session=${encodeURIComponent(SESSION)}&since=0&peek=1`);
+      const direct = (messages || []).filter(m => m.from === assigner && m.to === SESSION);
+      re = (direct.filter(m => String(m.text || "").includes(`#${card}`)).pop() || direct.pop())?.id || 0;
+    } catch {}
+    const payload = { from: SESSION, to: assigner, kind: "ask", text: `❓ ask on #${card}: ${question}` };
+    if (re) payload.re = re;
+    const sentAsk = await api("POST", "/send", payload);
+    return { content: [{ type: "text", text: `ask #${sentAsk.id} sent to ${assigner} — card #${card} now reads blocked with your question. Your turn stays owed (no park, no failure); the answer resumes this session with the contract re-attached. End your turn now.` }] };
+  });
+
 server.tool("relay_duty_failure", "Duty-seat only: record that a required cross-session socket nudge was skipped or that a relay send returned 403. The hub appends the failure to the target project's active focus card and exposes it in trantor doctor.",
   { recipient: z.string().describe("recipient session whose project is affected"), project: z.string().optional().describe("target project; normally inferred from the recipient"), kind: z.enum(["relay-403", "skipped-nudge"]), detail: z.string().max(500).optional() },
   async ({ recipient, project, kind, detail }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.58",
+  "version": "0.18.59",
   "type": "module",
   "bin": {
     "trantor": "bin/cli.mjs"