trantor 0.18.20 → 0.18.22

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "trantor",
-  "version": "0.18.20",
-  "description": "Trantor \u2014 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)",
+  "version": "0.18.22",
+  "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": {
       "command": "node",

package/README.md

@@ -364,6 +364,11 @@ model-authored handoff instead of superseding it; the successor is injected a ca
 being spoken to; and a session hosted in a Workspace pane is replaced in place by a detached
 driver — the same chain the app's [Hand off now] button runs.
 
+Waking works the same way from the other end: hover a sleeping project in the app's sidebar and
+**Wake** hosts its session as an in-app pane — `trantor open` under the hood, opened in the
+project's own checkout wherever it is called from, handoff-beats-resume, and the same kickoff
+prompt so the woken session catches up (handoff, board, memory) and recaps on its own.
+
 Why crews never exhaust the orchestrator: bus messages are **by reference** (~70 tokens),
 work products stay in each agent's own context — the orchestrator burns at coordination
 rate, not work rate.

package/bin/crew.sh

@@ -194,6 +194,24 @@ _herdr_close_pane() { [ "$DRY" = "1" ] && { echo "[dry] herdr pane close $1";
 # So the project gets ONE claude session id, chosen by us and remembered. First open starts claude
 # under it; every later open resumes it. Discovering the id afterwards would be guesswork, and
 # `--continue` would grab whatever ran last in this directory, which may be a different window.
+# A NAMED project must open in ITS checkout, wherever the caller stands (2026-08-31: the app ran
+# `trantor open crebral-health` from the Tauri process cwd and claude booted THERE — a trust
+# prompt for a folder the operator never chose, transcripts under the wrong slug, no project
+# memory, ACTIVE NOW blind). Resolution mirrors the app's project_dir: $TRANTOR_DEV_ROOT
+# (default ~/development)/<name>. Unknown name from an unrelated cwd → refuse loudly rather
+# than open somewhere silly.
+_orch_resolve_dir() {   # $1=cwd $2=project-arg → dir to open in (stdout); fails when unresolvable
+  local herebase; herebase="$(basename "$(git -C "$1" rev-parse --show-toplevel 2>/dev/null || echo "$1")")"
+  if [ -z "$2" ] || [ "$2" = "$herebase" ]; then printf '%s' "$1"; return 0; fi
+  local devroot="${TRANTOR_DEV_ROOT:-$HOME/development}"
+  if [ -d "$devroot/$2" ]; then
+    echo "— opening $2 in its checkout: $devroot/$2 —" >&2
+    printf '%s' "$devroot/$2"; return 0
+  fi
+  echo "trantor open: '$2' has no checkout at $devroot/$2 and this is '$herebase' — cd into the project first" >&2
+  return 1
+}
+
 _orch_sid() {   # $1=project → the project's session uuid, minting one on first use
   local f="${STATE%/*}/orch-sessions.txt" p sid
   if [ -f "$f" ]; then
@@ -244,26 +262,31 @@ _orch_cmd() {   # $1=dir $2=sid
 }
 
 # A recorded thread that HANDED OFF has ended: resuming it replays a dead conversation while the
-# handoff waits for a successor (the 2026-08-27 seam — "Trantor resumes the wrong thread"). When the
-# newest unconsumed handoff for the project was written BY the recorded session, open must start a
-# FRESH id instead; the sessionstart hook then claims the baton and records the fresh id in
-# orch-sessions.txt (single writer for the map: the hook + adopt — this function writes nothing).
+# handoff waits for a successor (the 2026-08-27 seam — "Trantor resumes the wrong thread").
+# ANY unconsumed handoff for the project means a successor is OWED a fresh window — open must
+# start a FRESH id so the sessionstart hook claims the baton (it then records the fresh id in
+# orch-sessions.txt; single writer: the hook + adopt — this function writes nothing).
+# The old predicate required the handoff to be written BY the recorded session (session_id match)
+# — but MANUAL handoffs carry no session_id at all, so on 2026-08-31 the reboot flow resumed the
+# same maxed-out conversation TWICE while its handoff sat unclaimed, and the injected recap
+# banner made each resume LOOK like a clean takeover. Who wrote it doesn't matter; that it is
+# unclaimed does.
 _orch_takeover_sid() {   # $1=project $2=recorded-sid → prints the sid open should use
   local fresh
   if node -e '
 const fs=require("fs"),path=require("path"),os=require("os");
 const dir=path.join(process.env.AGENT_BUS_DIR||process.env.RELAY_DATA_DIR||path.join(os.homedir(),".agent-bus"),"handoffs");
-const [proj,sid]=process.argv.slice(1);
+const [proj]=process.argv.slice(1);
 try{
   const re=new RegExp("^"+proj.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")+"-(\\d+)\\.json$");
   const files=fs.readdirSync(dir).map(f=>{const m=re.exec(f);return m?{f,s:Number(m[1])}:null}).filter(Boolean).sort((a,b)=>b.s-a.s);
   for(const {f} of files){
     const r=JSON.parse(fs.readFileSync(path.join(dir,f),"utf8"));
     if(r.consumed) continue;
-    process.exit(r.session_id&&r.session_id===sid?0:1);   // newest UNCONSUMED decides
+    process.exit(0);   // newest UNCONSUMED exists → a successor is owed a fresh window
   }
 }catch(e){}
-process.exit(1);' "$1" "$2" 2>/dev/null; then
+process.exit(1);' "$1" 2>/dev/null; then
     fresh="$(uuidgen 2>/dev/null | tr 'A-Z' 'a-z')"
     [ -n "$fresh" ] && { echo "— recorded session $2 handed off: starting fresh as $fresh to claim it —" >&2; printf '%s' "$fresh"; return 0; }
   fi
@@ -596,6 +619,7 @@ open_orchestrator() {
     --*) echo "trantor open: unknown flag '$a'"; usage_open; return 1 ;;
     *) PROJ="$a" ;;
   esac; done
+  DIR="$(_orch_resolve_dir "$DIR" "$PROJ")" || exit 1
   command -v herdr >/dev/null 2>&1 || { echo "trantor open needs herdr (the pane host) — install: curl -fsSL https://herdr.dev/install.sh | sh"; exit 1; }
   local wsid="" orch="" live_ids="" live_names="" pair="" line fresh=0
   local sid; sid="$(_orch_sid "$PROJ")" || { echo "trantor open: could not mint a session id (uuidgen missing?)" >&2; exit 1; }
@@ -630,6 +654,8 @@ open_orchestrator() {
     if _herdr pane rename "$orch" "orchestrator · $PROJ" >/dev/null 2>&1; then
       if _herdr_pane_has_agent "$orch"; then
         echo "herdr:${wsid:-?}/$orch"
+        # CONTRACT: the app's orchestrator_open (desktop terminal.rs) matches this exact phrase
+        # to SKIP its kickoff prompt — a reattach is a live conversation, never to be typed into.
         echo "— orchestrator already hosted: reattached to herdr:${wsid:-?}/$orch —" >&2
         return 0
       fi

package/hooks/sessionstart.mjs

@@ -441,6 +441,11 @@ try {
   // The hold LAPSES (default 30m) so an unclaimed baton never strands every other session.
   // Any other handoff keeps first-fresh-session-wins.
   const isCompact = source === "compact";
+  // A RESUMED session must never claim a handoff (2026-08-31, twice in one afternoon): it
+  // already carries its whole history, so claiming injects the takeover banner into the same
+  // maxed-out context — the recap LOOKS right while the window never reset, which is worse
+  // than failing loudly. The successor is whatever fresh session `trantor open` starts.
+  const isResume = source === "resume";
   const orchEnv = process.env.TRANTOR_ORCH || "";
   const isOrchPane = !!orchEnv && (orchEnv === "1" || orchEnv === project);   // project-matched: a child claude in another dir must not inherit the badge
   const orchSid = readOrchSession(project);
@@ -450,12 +455,12 @@ try {
   const ageMs = peek ? Date.now() - (Number(peek.stamp) || 0) * 1000 : 0;
   const held = orchOrigin && !isOrchPane && !isCompact && ageMs < holdMs;
   const handoff = !peek ? null
-    : (isCompact || held) ? peek
+    : (isCompact || held || isResume) ? peek
     : loadPendingHandoff(basename(projectDir), {
         claim: true,
         freshSession: { session_id: stdinObj.session_id || "", transcript_path: stdinObj.transcript_path || "" },
       });
-  const claimed = !!handoff && !isCompact && !held;
+  const claimed = !!handoff && !isCompact && !held && !isResume;
   // Follow the thread: claiming the orchestrator's baton makes THIS session the orchestrator
   // thread, so the map `trantor open` resumes and the app's chat reads moves with it. The pane
   // also records itself on every fresh start — that keeps the map honest even if a future
@@ -468,6 +473,13 @@ try {
     additionalContext += `<trantor-handoff-held id="${sanitize(handoff.id)}" from="${sanitize(handoff.machine)}">\n`;
     additionalContext += `🔒 A handoff from this project's ORCHESTRATOR thread is pending, and it is being HELD for the Trantor orchestrator pane (\`trantor open\` claims it on start). This session did NOT claim it and does not have its content — do not act as the successor. If the user wants THIS session to take over instead: \`trantor adopt\`, then restart this session. Unclaimed, the hold lapses in ~${mins} minute(s) and the handoff becomes first-come.\n`;
     additionalContext += `</trantor-handoff-held>\n`;
+  } else if (handoff && isResume) {
+    // No takeover banner here — injecting it into a resumed session is exactly the failure this
+    // guard exists for: the recap reads like a clean handoff while the context never reset.
+    process.stderr.write(`[trantor] pending handoff ${handoff.id} NOT claimed — this session was RESUMED, not started fresh\n`);
+    additionalContext += `<trantor-handoff-unclaimed id="${sanitize(handoff.id)}" reason="resumed-session">\n`;
+    additionalContext += `⚠️ An unclaimed handoff (${sanitize(handoff.id)}) is waiting for this project, but THIS session was RESUMED (\`--resume\`) — it already carries its own history and is NOT the successor. Do not act on the handoff. Tell the user plainly: a fresh session must claim it — \`trantor open\` starts one. If they want THIS resumed session to continue instead, they can ignore the handoff or clear it.\n`;
+    additionalContext += `</trantor-handoff-unclaimed>\n`;
   } else if (handoff) {
     process.stderr.write(`[trantor] ${isCompact ? "showing (not claiming, compact)" : "loaded"} pending handoff ${handoff.id}\n`);
     // Baton claimed → supersede every OTHER instance of this durable identity (instance-keys

package/hooks/statusline.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// USAGE v2 — the Claude statusline sidechannel (docs/RESEARCH-orca-usage.md §1.1).
+// Claude Code >=2.1.80 pipes a JSON blob (with `rate_limits`) into the statusLine command on
+// every turn, piggybacked on the Messages API response — live usage that costs zero API budget.
+// This forwarder reads that stdin, POSTs the windows to the hub's /usage/claude (signed), and
+// prints NOTHING: it is designed to be tee'd ahead of the operator's real statusline command,
+// never to be one. Every failure is swallowed — a usage forwarder must never break a statusline.
+//
+// Floor: one POST per session per 15s (stamp file) — the statusline ticks ~3x/sec while
+// streaming, and the hub dedupes same-value posts inside 30s anyway.
+import { readFileSync, writeFileSync, statSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const FLOOR_MS = 15_000;
+
+async function main() {
+  let raw = "";
+  for await (const c of process.stdin) raw += c;
+  const j = JSON.parse(raw);
+  const rl = j.rate_limits;
+  if (!rl || typeof rl !== "object") return;               // most ticks carry none — free exit
+  const sid = String(j.session_id || j.sessionId || "nosession").replace(/[^A-Za-z0-9_.-]/g, "_").slice(0, 80);
+  const dir = join(homedir(), ".agent-bus");
+  const stamp = join(dir, `usage-claude-${sid}.stamp`);
+  try { if (Date.now() - statSync(stamp).mtimeMs < FLOOR_MS) return; } catch {}
+  try { mkdirSync(dir, { recursive: true }); writeFileSync(stamp, ""); } catch {}
+
+  const payload = {
+    configDir: process.env.CLAUDE_CONFIG_DIR || null,
+    fiveHour: rl.five_hour ?? rl.fiveHour ?? null,
+    sevenDay: rl.seven_day ?? rl.sevenDay ?? null,
+    // The fable/model-scoped window normally arrives via the OAuth poller, but accept the
+    // statusline-shaped variants too — schema drift degrades instead of going dark.
+    fable: rl.fable_weekly ?? rl.fable ?? null,
+  };
+  if (!payload.fiveHour && !payload.sevenDay && !payload.fable) return;
+  // PRIMARY: the local live cache — lib/balances.mjs merges it and skips the OAuth poll while
+  // it is fresh (Orca's isLiveClaudeUsageFresh, docs/RESEARCH-orca-usage.md §2). This is the
+  // path the app's footer actually reads (it shells the local CLI, not the hub).
+  try { writeFileSync(join(dir, "usage-claude-live.json"), JSON.stringify({ ts: Date.now(), ...payload })); } catch {}
+  // SECONDARY, best-effort: the hub copy, for dashboard surfaces that read hub state.
+  const { signedPost } = await import("./lib/api.mjs");
+  await signedPost("/usage/claude", payload, { timeoutMs: 2500 });
+}
+
+main().catch(() => {}).finally(() => process.exit(0));

package/hub.mjs

@@ -1642,6 +1642,29 @@ const server = http.createServer(async (req, res) => {
       if (ts >= (state.balances?.ts || 0)) { state.balances = { ts, by: String(b.by || "").slice(0, 120), entries }; dirty = true; }
       return json(res, 200, { ok: true });
     }
+    // USAGE v2: the Claude statusline sidechannel. Claude Code >=2.1.80 pipes rate_limits into
+    // the statusLine command on every turn; hooks/statusline.mjs forwards it here (floored 15s
+    // client-side). The live windows PATCH the cached balances snapshot — free usage between
+    // `trantor balances` runs, and the poller can skip Claude while liveTs is fresh (Orca's
+    // lesson, docs/RESEARCH-orca-usage.md §1.1: the OAuth endpoint 429s under polling).
+    if (req.method === "POST" && P === "/usage/claude") {
+      const b = await body(req);
+      const win = (w, name) => (w && (w.used_percentage ?? w.utilization) != null)
+        ? { name, usedPct: Math.round(Number(w.used_percentage ?? w.utilization)), resetsAt: w.resets_at ?? null } : null;
+      const wins = [["fiveHour", "5h"], ["sevenDay", "7d"], ["fable", "Fable"]]
+        .map(([k, n]) => win(b[k], n)).filter(Boolean);
+      if (!wins.length) return json(res, 400, { error: "no usable windows" });
+      state.balances ||= { ts: 0, by: "", entries: [] };
+      let e = state.balances.entries.find(x => x.provider === "claude");
+      if (!e) { e = { provider: "claude", label: "Claude", kind: "windows", ok: true, windows: [] }; state.balances.entries.push(e); }
+      // Same-value posts inside 30s are dropped (the statusline ticks ~3x/sec while streaming).
+      const sig = JSON.stringify(wins);
+      if (e._liveSig === sig && now() - (e.liveTs || 0) < 30_000) return json(res, 200, { ok: true, deduped: true });
+      for (const w of wins) { const cur = (e.windows ||= []).find(x => x.name === w.name); if (cur) Object.assign(cur, w); else e.windows.push(w); }
+      e.ok = true; e.liveTs = now(); e._liveSig = sig; e.liveSource = "statusline";
+      dirty = true;
+      return json(res, 200, { ok: true, windows: wins.length });
+    }
     if (req.method === "GET" && P === "/balances") {
       let cfg = {}; try { cfg = JSON.parse(readFileSync(join(homedir(), ".agent-bus", "config.json"), "utf8")); } catch {}
       const low = { USD: 5, CNY: 35, EUR: 5, ...(cfg.lowBalance || {}) };

package/lib/balances.mjs

@@ -11,6 +11,10 @@
 // ARCHITECTURE NOTE: the hub runs under launchd with a minimal env (no keys), so it can't fetch these
 // itself. The env-having clients fetch + POST /balances; the hub caches + serves the dashboard.
 
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
 const TIMEOUT = 8000;
 
 async function getJSON(url, key, extraHeaders = {}) {
@@ -40,13 +44,40 @@ export const ADAPTERS = [
     provider: "claude", label: "Claude", kind: "windows", match: ["claude", "anthropic"], envKeys: [],
     keyless: true,
     async fetch() {
+      // USAGE v2: the statusline sidechannel (hooks/statusline.mjs) keeps a live local cache —
+      // Claude Code pipes rate_limits to the statusLine every turn, free. When the OAuth
+      // endpoint fails (it 429s under polling — Orca's lesson, docs/RESEARCH-orca-usage.md
+      // §1.1), a fresh live capture answers instead of an error row. OAuth stays primary
+      // because only it carries the model-scoped (Fable) window.
+      const live = (() => {
+        try {
+          const l = JSON.parse(readFileSync(join(homedir(), ".agent-bus", "usage-claude-live.json"), "utf8"));
+          return l && Date.now() - (l.ts || 0) < 15 * 60 * 1000 ? l : null;
+        } catch { return null; }
+      })();
+      const liveWin = (w, name) => (w && (w.used_percentage ?? w.utilization) != null)
+        ? { name, usedPct: Math.round(Number(w.used_percentage ?? w.utilization)), resetsAt: w.resets_at || null, locked: null }
+        : null;
+      const liveWindows = () => [liveWin(live?.fiveHour, "5h"), liveWin(live?.sevenDay, "7d")].filter(Boolean);
       const tok = await claudeOAuthToken();
-      if (!tok) throw new Error("no Claude Code OAuth token found");
-      const r = await fetch("https://api.anthropic.com/api/oauth/usage", {
-        headers: { authorization: `Bearer ${tok}`, "anthropic-beta": "oauth-2025-04-20" },
-        signal: AbortSignal.timeout(8000),
-      });
-      if (!r.ok) throw new Error(`usage endpoint ${r.status}`);
+      if (!tok) {
+        if (live && liveWindows().length) return { windows: liveWindows(), live: true };
+        throw new Error("no Claude Code OAuth token found");
+      }
+      let r;
+      try {
+        r = await fetch("https://api.anthropic.com/api/oauth/usage", {
+          headers: { authorization: `Bearer ${tok}`, "anthropic-beta": "oauth-2025-04-20" },
+          signal: AbortSignal.timeout(8000),
+        });
+      } catch (e) {
+        if (live && liveWindows().length) return { windows: liveWindows(), live: true };
+        throw e;
+      }
+      if (!r.ok) {
+        if (live && liveWindows().length) return { windows: liveWindows(), live: true };
+        throw new Error(`usage endpoint ${r.status}`);
+      }
       const d = await r.json();
       const win = (w, name) => (w && w.utilization != null)
         ? { name, usedPct: Math.round(w.utilization), resetsAt: w.resets_at || null, locked: w.locked_reason || null }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.20",
+  "version": "0.18.22",
   "type": "module",
   "bin": {
     "trantor": "bin/cli.mjs"
@@ -11,9 +11,9 @@
     "zod": "^4.4.3"
   },
   "scripts": {
-    "test": "node bin/slop-gate.mjs --surface desktop/src && node test.mjs && node test-scenarios.mjs && node test-failure.mjs && node test-redelivery.mjs && node test-crew-completion.mjs && node test-contracts.mjs && node test-autonomy.mjs && node test-integrate.mjs && node test-handoff.mjs && node test-handoff-summarizer.mjs && node test-baton-turn-boundary.mjs && node test-agents.mjs && node test-update.mjs && node test-handoff-guard.mjs && node test-baton-latest.mjs && node test-balances.mjs && node test-subagent-cost.mjs && node test-inbox.mjs && node test-inflight.mjs && node test-notify.mjs && node test-focus.mjs && node test-cardlog.mjs && node test-checklist.mjs && node test-relay-note.mjs && node test-reaper.mjs && node test-events.mjs && node test-proposals.mjs && node test-scrub.mjs && node test-store-delta.mjs && node test-message-re.mjs && node test-claims.mjs && node test-adopt.mjs && node test-summarize.mjs && node test-identity-core.mjs && node test-identity.mjs && node test-identity-instances.mjs && node test-duty.mjs && node test-duty-dark.mjs && node test-duty-seat.mjs && node test-discovery.mjs && node test-doctor.mjs && node test-crew-env.mjs && node test-desktop-transport.mjs && node test-crew-worktree.mjs && bash test-crew-herdr.sh && npm --prefix desktop run test --silent && node test-splitbrain.mjs && node test-overseer.mjs && node test-overseer-lib.mjs && node test-overseer-warn.mjs && node test-provider-keys.mjs && node test-inbox-delivery.mjs && node test-identity-drift.mjs && node test-inbox-staleness.mjs && node test-seats.mjs && node test-seat-identity.mjs && node test-hub-routing.mjs && node test-hook-routing.mjs && node test-relay-wait.mjs && node test-dsh-seat.mjs && node test-kimi-bridge.mjs && node test-kimi-events.mjs && python3 engine/test-routing.py && node test-reconcile.mjs && node test-resources.mjs && node test-patrol.mjs && node test-bridge.mjs && bash test-crew.sh"
+    "test": "node bin/slop-gate.mjs --surface desktop/src && node test.mjs && node test-scenarios.mjs && node test-failure.mjs && node test-redelivery.mjs && node test-crew-completion.mjs && node test-contracts.mjs && node test-autonomy.mjs && node test-integrate.mjs && node test-handoff.mjs && node test-handoff-summarizer.mjs && node test-baton-turn-boundary.mjs && node test-agents.mjs && node test-update.mjs && node test-handoff-guard.mjs && node test-baton-latest.mjs && node test-balances.mjs && node test-usage-live.mjs && node test-subagent-cost.mjs && node test-inbox.mjs && node test-inflight.mjs && node test-notify.mjs && node test-focus.mjs && node test-cardlog.mjs && node test-checklist.mjs && node test-relay-note.mjs && node test-reaper.mjs && node test-events.mjs && node test-proposals.mjs && node test-scrub.mjs && node test-store-delta.mjs && node test-message-re.mjs && node test-claims.mjs && node test-adopt.mjs && node test-summarize.mjs && node test-identity-core.mjs && node test-identity.mjs && node test-identity-instances.mjs && node test-duty.mjs && node test-duty-dark.mjs && node test-duty-seat.mjs && node test-discovery.mjs && node test-doctor.mjs && node test-crew-env.mjs && node test-desktop-transport.mjs && node test-crew-worktree.mjs && bash test-crew-herdr.sh && npm --prefix desktop run test --silent && node test-splitbrain.mjs && node test-overseer.mjs && node test-overseer-lib.mjs && node test-overseer-warn.mjs && node test-provider-keys.mjs && node test-inbox-delivery.mjs && node test-identity-drift.mjs && node test-inbox-staleness.mjs && node test-seats.mjs && node test-seat-identity.mjs && node test-hub-routing.mjs && node test-hook-routing.mjs && node test-relay-wait.mjs && node test-dsh-seat.mjs && node test-kimi-bridge.mjs && node test-kimi-events.mjs && python3 engine/test-routing.py && node test-reconcile.mjs && node test-resources.mjs && node test-patrol.mjs && node test-bridge.mjs && bash test-crew.sh"
   },
-  "description": "The hub-world for AI agent crews \u2014 orchestrate Claude Code, Codex, GLM, Kimi, DeepSeek & any OpenRouter model as live crews with a plan-aware Advisor, a Kanban/flow command center, a testing gate, and an economics brain (Scrooge).",
+  "description": "The hub-world for AI agent crews — orchestrate Claude Code, Codex, GLM, Kimi, DeepSeek & any OpenRouter model as live crews with a plan-aware Advisor, a Kanban/flow command center, a testing gate, and an economics brain (Scrooge).",
   "files": [
     "hub.mjs",
     "mcp.mjs",