trantor 0.18.109 → 0.18.111

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.109",
+  "version": "0.18.111",
   "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/README.md

@@ -417,9 +417,16 @@ rate, not work rate.
 ```
 trantor setup | doctor | connect | profile | provider | models
         | new <name> | up <agents…> | swap <old> <new> | down | seat-why <agent> | ui | advise | hub | watch
-        | adopt <project> | reconcile | duty | orchestrate | patrol | app | backfill | init-hooks
+        | adopt <project> | reconcile | duty | orchestrate | patrol | app | backfill | init-hooks | pair
 ```
 
+- **`trantor pair`** pairs the iPhone and iPad companion app (`ios/`, an operator console for
+  fleet decisions). It mints a single-use, ten-minute invite with the `approver` role (decides
+  holds, proposals and gates; never deletes projects or mints invites) and prints a
+  `trantor://enroll` link. `--sim` opens it in the booted simulator, `--json` prints it for
+  scripts, and `--role owner` widens the scope. The desktop app's Settings shows the same invite
+  as a QR code. It signs as the operator's owner identity (`TRANTOR_IDENTITY`, default `sasha@mac`).
+
 - **`trantor new <name>`** — project genesis in one command: makes the dir under your dev root
   (`TRANTOR_DEV_ROOT` or `~/development`), git on main (or `--from <git-url>`, or `--adopt` an
   existing folder), installs the auto-card hook, posts the brief to the hub, and opens the first

package/bin/cli.mjs

@@ -187,6 +187,7 @@ switch (cmd) {
     else console.error(`Invite failed: ${j.error || r.statusText}`);
     break;
   }
+  case "pair":    run("bin/pair.mjs"); break;
   case "enroll": {
     const token = args[0];
     if (!token) { console.error("usage: trantor enroll <token>"); process.exit(1); }
@@ -256,6 +257,7 @@ switch (cmd) {
   trantor down        tear the crew down (kills processes, closes windows, no dialogs)
   trantor prune       drop dead crew-window tracking rows (ghost workspaces/panes) without spawning anything
   trantor ui          open the live dashboard (board + flow views)
+  trantor pair        pair a phone: mint a trantor://enroll link for the companion app — [--role owner] [--sim] [--json]
   trantor app         the DESKTOP app: status | install | update — pulls the latest DMG from GitHub Releases
   trantor catchup     "where are we?" — the continuous board + git, with a synthesized brief
   trantor agents      what this session's sub-agents did (task · returned? · files written · survived on disk) — [<sessionId>] [--json]

package/bin/crew/codex-relay.mjs

@@ -0,0 +1,8 @@
+// Codex's MCP env table overrides ambient runner variables and may pin another seat.
+export function codexRelayFlags({ persona, session, project, hub }) {
+  const env = { RELAY_AGENT: persona, RELAY_SESSION: session, RELAY_PROJECT: project, RELAY_URL: hub };
+  return Object.entries(env).map(([key, value]) => {
+    const setting = `mcp_servers.relay.env.${key}=${JSON.stringify(value)}`;
+    return ` -c '${setting.replaceAll("'", "'\"'\"'")}'`;
+  }).join("");
+}

package/bin/crew-runner.mjs

@@ -48,6 +48,7 @@ import { costLine } from "../lib/state/cost.mjs";
 import { resolveStateFlags, stateFeatureOn } from "../lib/state/flags.mjs";
 
 import { awaitSwapRelease } from "./crew/stage.mjs";
+import { codexRelayFlags } from "./crew/codex-relay.mjs";
 
 const releaseState = process.env.CREW_RELEASE_STATE ? JSON.parse(process.env.CREW_RELEASE_STATE) : null;
 delete process.env.CREW_RELEASE_STATE;
@@ -243,8 +244,8 @@ let MODEL = process.env.CREW_MODEL || "";
 // ZAI-coding-plan models into deepseek/…). `scrooge route` returns qualified ids.
 if (MODEL && !MODEL.includes("/") && AGENT === "deepseek") MODEL = `deepseek/${MODEL}`;
 const CLI = {
-  codex:    { first: `codex exec{M} --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox "$(cat {P})" < /dev/null`,
-              next:  `codex exec resume --last{M} --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox "$(cat {P})" < /dev/null`, mflag: " -m " },
+  codex:    { first: `codex exec{M}{R} --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox "$(cat {P})" < /dev/null`,
+              next:  `codex exec resume --last{M}{R} --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox "$(cat {P})" < /dev/null`, mflag: " -m " },
   gemini:   { first: `gemini --yolo{M} -p "$(cat {P})"`,
               next:  `gemini --yolo{M} -r latest -p "$(cat {P})"`, mflag: " -m " },
   // kimi-code (successor to kimi-cli) has no --print (-p alone is non-interactive), REJECTS
@@ -863,7 +864,8 @@ async function runTurn(prompt, isFirst, trigger = "kickoff", opts = {}) {
   const turnEffort = effortForTurn({ agent: DRIVER, model: MODEL, launchEffort: EFFORT, cardDifficulty });
   const mfrag = (MODEL && cli.mflag ? `${cli.mflag}${MODEL}` : "") + turnEffort.flag;
   cmd = cmd.replaceAll("{M}", mfrag).replaceAll("{P}", pf).replaceAll("{SID}", sid).replaceAll("{DIR}", TURN_DIR)
-    .replaceAll("{S}", STATE_SCHEMA_FILE);
+    .replaceAll("{S}", STATE_SCHEMA_FILE)
+    .replaceAll("{R}", () => codexRelayFlags({ persona: PERSONA, session: SESSION, project: PROJ, hub: HUB }));
   // PRECEDENCE: each file is PREPENDED, so the list is iterated in written order, highest priority
   // first, and the CREW layer (~/.agent-bus/.env) wins. test-crew-env.mjs runs the real shell.
   const envs = [join(homedir(), ".agent-bus", ".env"), cli.env].filter(f => f && existsSync(f));

package/bin/keys.mjs

@@ -8,7 +8,7 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { load, migrateKeysToKeychain, keyLocationReport, IDENTITY_SERVICE } from "../lib/identity.mjs";
 import { sfetch } from "../lib/signed-fetch.mjs";
-import { pruneTestKeys } from "../lib/key-prune.mjs";
+import { pruneTestKeys, pruneStaleTmp } from "../lib/key-prune.mjs";
 
 const args = process.argv.slice(2);
 const verb = args[0] || "status";
@@ -65,6 +65,10 @@ async function prune() {
   const idleDays = at < 0 ? 7 : Number(args[at + 1]);
   if (!Number.isFinite(idleDays) || idleDays <= 0) throw new Error("--idle-days must be a positive number");
   if (args.includes("--apply") && args.includes("--dry-run")) throw new Error("choose --apply or --dry-run");
+  const apply = args.includes("--apply");
+  // The tmp sweep is local (a stranded atomic-write temp is not a key and needs no hub) and runs
+  // first, so it works even when the hub is unreachable; --apply gates it like the rest of prune.
+  const tmp = pruneStaleTmp({ apply });
   const bus = process.env.AGENT_BUS_DIR || join(homedir(), ".agent-bus");
   let config = {};
   try { config = JSON.parse(readFileSync(join(bus, "config.json"), "utf8")); }
@@ -79,8 +83,11 @@ async function prune() {
       snapshots.push(await response.json());
     } catch (error) { throw new Error(`cannot check hub ${hub}: ${error.message}; no keys pruned`); }
   }
-  const result = pruneTestKeys({ snapshots, idleDays, apply: args.includes("--apply") });
-  if (JSON_MODE) { console.log(JSON.stringify(result, null, 2)); return; }
+  const result = pruneTestKeys({ snapshots, idleDays, apply });
+  if (JSON_MODE) { console.log(JSON.stringify({ ...result, tmp }, null, 2)); return; }
+  const tmpDid = tmp.dryRun ? "dry run — would remove" : "removed";
+  console.log(`${tmpDid} ${tmp.removed.length} stale key-write tmp file(s) older than 1h${tmp.dryRun && tmp.removed.length ? "; use --apply to remove them" : ""}`);
+  for (const f of tmp.removed) console.log(`  ${f}`);
   console.log(`${result.dryRun ? "dry run — would remove" : "removed"} ${result.removed.length} test key file(s), idle over ${idleDays} days`);
   for (const name of result.removed) console.log(`  ${name}`);
   console.log(`kept ${result.kept.length} key file(s)${result.dryRun ? "; use --apply to remove the listed files" : ""}`);

package/bin/pair.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// trantor pair — mint a phone-pairing invite and print it as a trantor://enroll link.
+// Same owner signing as `trantor invite`, but scoped for the companion app: every project,
+// the approver role, single use, ten minutes. The phone scans the QR (desktop Settings) or
+// opens the link (this command, --sim) and enrolls itself.
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const args = process.argv.slice(2);
+const USAGE = "usage: trantor pair [--role owner] [--sim] [--json]";
+if (args.includes("--help") || args.includes("-h")) { console.log(USAGE); process.exit(0); }
+const asJson = args.includes("--json");
+const openSim = args.includes("--sim");
+const roleIdx = args.indexOf("--role");
+const role = roleIdx >= 0 ? (args[roleIdx + 1] || "") : "approver";
+if (!role || role.startsWith("--")) {
+  console.error(USAGE);
+  process.exit(1);
+}
+
+const { load, signRequest } = await import(join(ROOT, "lib/identity.mjs"));
+const { resolveHubInfo } = await import(join(ROOT, "lib/project.mjs"));
+
+const hub = resolveHubInfo().url.replace(/\/+$/, "");
+// The operator's owner key, the same one the desktop app signs with (hub.rs owner_identity).
+// Loaded, never minted: a fresh key is unknown to the hub and every invite would 401.
+const owner = process.env.TRANTOR_IDENTITY || "sasha@mac";
+const id = load(owner);
+if (!id) { console.error(`error: no key for the owner identity "${owner}". Set TRANTOR_IDENTITY, or run \`trantor keys status\``); process.exit(1); }
+
+const payload = { scopes: [{ project: "*", role }], ttlSec: 600, kind: "human" };
+const body = JSON.stringify(payload);
+const sig = signRequest(id, { method: "POST", path: "/invite", body });
+let r;
+try {
+  r = await fetch(`${hub}/invite`, { method: "POST", headers: { "content-type": "application/json", ...sig }, body });
+} catch (e) {
+  console.error(`error: hub unreachable at ${hub} — ${e.message}`);
+  process.exit(1);
+}
+const j = await r.json().catch(() => ({}));
+
+// The hub may predate the approver role (#12113): an explicit 400 names it, an older hub is
+// quieter — cleanScope folds unknown roles down to read and echoes the folded scope. Either
+// way a link minted here would pair the phone into near-nothing, so refuse it instead.
+const echoed = Array.isArray(j.scopes) ? j.scopes[0]?.role : undefined;
+const roleRefused = !r.ok
+  ? /role|approver/i.test(String(j.error || "")) || r.status === 400
+  : echoed !== role;
+if (roleRefused) {
+  const why = r.ok
+    ? `this hub does not know the "${role}" role yet — it answered with "${echoed}", which would pair the phone near-read-only`
+    : `hub refused the invite: ${j.error || r.statusText}`;
+  if (asJson) console.log(JSON.stringify({ error: why, hint: "retry with --role owner" }));
+  else console.error(`Pairing refused: ${why}\nRetry with --role owner.`);
+  process.exit(1);
+}
+if (!r.ok) {
+  if (asJson) console.log(JSON.stringify({ error: j.error || r.statusText }));
+  else console.error(`Pairing failed: ${j.error || r.statusText}`);
+  process.exit(1);
+}
+
+const link = `trantor://enroll?hub=${encodeURIComponent(hub)}&token=${j.token}`;
+const expiresAt = Number(j.expiresAt) || Date.now() + 600000;
+const mins = Math.max(0, Math.round((expiresAt - Date.now()) / 60000));
+
+if (asJson) {
+  console.log(JSON.stringify({ link, token: j.token, hub, expiresAt }));
+} else {
+  console.log(`Pair link (single use):\n${link}\nExpires in ${mins} minute${mins === 1 ? "" : "s"}.`);
+}
+
+if (openSim) {
+  if (process.platform !== "darwin") {
+    console.error("--sim needs macOS (xcrun simctl)");
+    process.exit(1);
+  }
+  const sim = spawnSync("xcrun", ["simctl", "openurl", "booted", link], { stdio: "pipe" });
+  if (sim.status !== 0) {
+    console.error(`simctl could not open the link: ${String(sim.stderr).trim() || "no booted simulator?"}`);
+    process.exit(1);
+  }
+  if (!asJson) console.log("Opened in the booted simulator.");
+}

package/hub/auth.mjs

@@ -53,15 +53,16 @@ function cmpSemver(a, b) {
 }
 const AUTH_HEADERS = ["x-trantor-pubkey", "x-trantor-sig", "x-trantor-ts", "x-trantor-nonce"];
 const PUBLIC_ENDPOINTS = new Set(["/", "/ui", "/health", "/enroll"]);
-const OWNER_ENDPOINTS = new Set(["/project/delete", "/sweep", "/reconcile", "/invite", "/import", "/policy", "/proposal/decide"]);
-const READ_ENDPOINTS = new Set(["/peers", "/tasks", "/events", "/inbox", "/peer", "/card", "/stream", "/history", "/projects", "/catchup", "/phases", "/recent", "/handoffs", "/verify-gates", "/claims", "/proposals", "/grants", "/overseer/context", "/overseer/status"]);
-const roleRank = { read: 1, write: 2, owner: 3 };
+const OWNER_ENDPOINTS = new Set(["/project/delete", "/sweep", "/reconcile", "/invite", "/import", "/policy", "/session/prompts", "/session/prompt/claim", "/session/prompt/ack"]);
+const DEVICE_ENDPOINTS = new Set(["/device/register", "/device/unregister", "/devices"]);
+const READ_ENDPOINTS = new Set(["/peers", "/tasks", "/events", "/inbox", "/peer", "/card", "/stream", "/history", "/projects", "/catchup", "/phases", "/recent", "/handoffs", "/verify-gates", "/claims", "/proposals", "/grants", "/overseer/context", "/overseer/status", "/session/chat", "/session/prompt"]);
+const roleRank = { read: 1, write: 2, approver: 3, owner: 4 };
 const hasAuthHeaders = (req) => AUTH_HEADERS.some(h => !!req.headers[h]);
 const authPath = (u) => `${u.pathname}${u.search || ""}`;
 function cleanScope(s) {
   if (!s || typeof s !== "object") return null;
   const project = canon(String(s.project || s.proj || "*").slice(0, 80)) || "*";
-  const role = ["read", "write", "owner"].includes(s.role) ? s.role : "read";
+  const role = ["read", "write", "approver", "owner"].includes(s.role) ? s.role : "read";
   return { project, role };
 }
 function defaultScopesFor(identity, b) {
@@ -69,7 +70,7 @@ function defaultScopesFor(identity, b) {
   if (explicit.length) return explicit.slice(0, 20);
   const name = String(b.name || identity.name || "");
   const project = canon(String(b.project || (name.includes(":") ? name.split(":").pop() : "*")).slice(0, 80)) || "*";
-  const role = ["read", "write", "owner"].includes(b.role) ? b.role : (String(b.kind || identity.kind || "") === "agent" ? "write" : "owner");
+  const role = ["read", "write", "approver", "owner"].includes(b.role) ? b.role : (String(b.kind || identity.kind || "") === "agent" ? "write" : "owner");
   return [{ project, role }];
 }
 function findIdentity(pubkey) {
@@ -115,6 +116,13 @@ function projectFromRequest(P, q, b) {
     const p = state.proposals.find(x => x.id === Number(b?.id ?? q?.id));
     return p?.project || "";
   }
+  // claim/ack and the single-prompt GET carry only an id — authorization runs against the
+  // PROMPT's project, or a project-scoped key could claim any project's queued prompt (#12129).
+  if (P === "/session/prompt" || P === "/session/prompt/claim" || P === "/session/prompt/ack") {
+    const pr = (state.sessionPrompts || []).find(x => x.id === Number(b?.id ?? q?.id));
+    if (pr) return pr.project || "";
+    if (P !== "/session/prompt") return "";
+  }
   return canon(String(b?.project || q?.project || "").slice(0, 80));
 }
 // Cross-project actions require a declared link or the operator identity, even with wildcard scopes (#6228).
@@ -247,6 +255,8 @@ function authorize(auth, method, P, project) {
   if (AUTH_MODE === "off" || PUBLIC_ENDPOINTS.has(P)) return { ok: true };
   if (auth?.warning && AUTH_MODE === "warn") return { ok: true };
   if (!auth?.identity) return { ok: false, code: 401, error: "signature required" };
+  // Device management is self-keyed, not project-scoped; the route enforces the signer boundary.
+  if (DEVICE_ENDPOINTS.has(P)) return { ok: true };
   const need = OWNER_ENDPOINTS.has(P) ? "owner" : (method === "POST" ? "write" : (READ_ENDPOINTS.has(P) ? "read" : "read"));
   if (isDutyIdentity(auth) && (need === "read" || P === "/send" || P === "/duty/failure")) return { ok: true };
   return scopeAllows(auth.identity, project, need) ? { ok: true } : { ok: false, code: 403, error: "forbidden" };

package/hub/events.mjs

@@ -1,7 +1,7 @@
 /* oxlint-disable anti-slop/no-runtime-typeof -- SAFETY: Event payloads preserve the established card wire contract, including numeric cost fields from legacy durable rows. */
 import { publicView } from "../lib/identity.mjs";
 
-export function createEventRuntime({ state, markDirty, AUTH_MODE, ONLINE_MS, canon }) {
+export function createEventRuntime({ state, markDirty, AUTH_MODE, ONLINE_MS, canon, notifier = null }) {
 const streams = [];
 // live file claims: "project file session" -> { project, file, session, ts }. Ephemeral like
 // presence — see the /claim handler for the design.
@@ -26,12 +26,9 @@ function applyPeerAuth(p, auth) {
 function touch(session, status, project, hookVersion, auth) {
   if (!session || session === "all") return;   // "all" is a wildcard, not a real peer
   const p = state.peers[session] || { lastSeen: 0, status: "", project: "" };
-  // NOTE: peers deliberately carry NO terminal address (tty/window). A short-lived experiment recorded
-  // one so an idle session could be woken by typing into its terminal; that was removed as unsafe.
-  // /send is unauthenticated and `from` is self-asserted, so a routable terminal address turns any local
-  // process into arbitrary keystrokes in a session that may be running with permissions bypassed. A
-  // message must reach an agent through a channel the agent's own harness controls (see hooks/
-  // inbox-deliver.mjs and hooks/stop-inbox.mjs), never by driving a process we do not own.
+  // Peers carry no terminal address: /send is unauthenticated and `from` is self-asserted, so one
+  // would turn any local process into arbitrary keystrokes. Messages reach agents only through
+  // channels their own harness controls (hooks/inbox-deliver.mjs and hooks/stop-inbox.mjs).
   delete p.tty; delete p.windowId; delete p.host;
   const wasOnline = p._on === true;   // explicit flag, so the log gets ONE event per transition
   p.lastSeen = now();
@@ -70,11 +67,9 @@ function healthOf(status) {
   return "ok";
 }
 function deliverable(m, session) { return (m.to === session || m.to === "all") && m.from !== session; }
-// The delivery ledger: the highest message id this session has actually been handed. Every read path
-// (/inbox, /poll) reports here, so ONE record answers "has this session seen message N yet?" regardless
-// of whether it was the model polling (relay_inbox) or the PostToolUse hook injecting mid-turn.
-// That is what lets the deferred waker give in-session delivery first refusal and only type into
-// somebody's terminal when nothing else got there first. Monotonic — a later read never lowers it.
+// The delivery ledger records the highest message id handed to a session across /inbox and /poll,
+// whether read by relay_inbox or a PostToolUse hook. The deferred waker gives in-session delivery
+// first refusal; the high-water mark is monotonic.
 function markDelivered(session, upTo) {
   const p = state.peers[session]; const n = Number(upTo || 0);
   if (!p || !n) return;
@@ -82,7 +77,7 @@ function markDelivered(session, upTo) {
 }
 function pushToStreams(msg) {
   for (const s of streams) {
-    if (!deliverable(msg, s.session) || s.res.writableEnded || s.res.destroyed) continue;
+    if (!deliverable(msg, s.session) || (s.readsMessage && !s.readsMessage(msg)) || s.res.writableEnded || s.res.destroyed) continue;
     try { s.res.write(`data: ${JSON.stringify(msg)}\n\n`); } catch {}
   }
 }
@@ -107,18 +102,13 @@ function inboxResponse(auth, messages, cursor, rewound = false) {
 // message and nothing else — can never see it. Backwards-safe by construction.
 function pushEventToStreams(ev) {
   for (const s of streams) {
-    if (!s.events || s.res.writableEnded || s.res.destroyed) continue;
+    if (!s.events || (s.readsEvent && !s.readsEvent(ev)) || s.res.writableEnded || s.res.destroyed) continue;
     try { s.res.write(`event: ev\ndata: ${JSON.stringify(ev)}\n\n`); } catch {}
   }
 }
-// --- the unified event log ---------------------------------------------------------------
-// One append-only stream for everything that happens in a project. Two families share it:
-//   • CARD events keep the LEGACY flat shape and legacy type names ("created"/"moved"/"updated")
-//     so /history, /card, /project/merge and the TIMELINE view are byte-for-byte unaffected.
-//   • Everything else uses a DOTTED type ("message", "presence.online", "focus", "handoff.written",
-//     "lesson", "verify.gate.opened", …) and is filtered OUT of /history — it surfaces via /events.
-// Card events carry `source` + `costUsd` so the FEED can render a git commit or a sub-agent's
-// spend distinctly from an ordinary card move without a second lookup.
+// The unified log keeps card events in their legacy flat shape for /history, /card and TIMELINE.
+// Dotted non-card types surface only through /events. Card events also carry source and costUsd
+// so the FEED can distinguish commits and sub-agent spend without another lookup.
 const EVENT_CAP = Number(process.env.RELAY_EVENT_CAP || 20000);
 const CARD_TYPES = new Set(["created", "moved", "updated"]);
 const isCardEvent = e => CARD_TYPES.has(e?.type);
@@ -134,6 +124,13 @@ function appendEvent(type, project, by, extra = {}) {
   state.events.push(ev);
   if (state.events.length > EVENT_CAP) state.events.splice(0, state.events.length - EVENT_CAP);
   pushEventToStreams(ev);
+  try {
+    if (notifier) Promise.resolve(notifier.notify(ev)).catch(error => {
+      process.stderr.write(`[trantor] push failed: ${error?.message || error}\n`);
+    });
+  } catch (error) {
+    process.stderr.write(`[trantor] push failed: ${error?.message || error}\n`);
+  }
   markDirty();
   return ev;
 }
@@ -159,13 +156,3 @@ function appendCardEvent(type, task, by, from = null, to = null, extra = {}) {
     appendCardEvent, EVENT_CAP, CARD_TYPES, isCardEvent,
   };
 }
-
-// --- FLOW v2: derive a project's PHASES (the orchestrator-rooted flowchart spine) ---
-// Real data is deps-sparse (most cards carry no deps), so we DON'T derive phases from the
-// dependency graph. Instead: a card's phase = its title-prefix family (P5a/P5b → "P5",
-// CBv2-1/CBfix → "CB", FA-comp1 → "FA", …) when present; otherwise it's clustered with its
-// time-neighbours into a "Setup N" round (gap > 8h opens a new round). Phases are ordered by
-// first-seen. The orchestrator (host session, "machine:project") vs crew ("brand:project")
-// split gives each phase its fan-out actors; the plan/integrate spine nodes are synthetic
-// because real per-phase orchestrator cards are rare. `sparse` flags a board that's mostly
-// un-prefixed (the UI shows an "inferred phases" notice — never a silent blob).

package/hub/notifier.mjs

@@ -0,0 +1,171 @@
+import http2 from "node:http2";
+import { createPrivateKey, sign } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+const APNS_HOSTS = {
+  sandbox: "api.sandbox.push.apple.com",
+  production: "api.push.apple.com",
+};
+const JWT_REUSE_MS = 50 * 60 * 1000;
+const text = (value, max = 300) => String(value || "").slice(0, max);
+
+function apnsTransport({ host, path, headers, body }) {
+  return new Promise((resolve, reject) => {
+    const session = http2.connect(`https://${host}`);
+    let settled = false;
+    const fail = error => {
+      if (settled) return;
+      settled = true;
+      session.destroy();
+      reject(error);
+    };
+    session.on("error", fail);
+    const req = session.request({ ...headers, ":method": "POST", ":path": path });
+    let status = 0;
+    let responseBody = "";
+    req.setEncoding("utf8");
+    req.on("response", headers => { status = Number(headers[":status"] || 0); });
+    req.on("data", chunk => { responseBody += chunk; });
+    req.on("error", fail);
+    req.setTimeout(10000, () => fail(new Error("APNs request timed out")));
+    req.on("end", () => {
+      if (settled) return;
+      settled = true;
+      session.close();
+      resolve({ status, body: responseBody });
+    });
+    req.end(body);
+  });
+}
+
+function clearFor(event) {
+  // Whatever ends the item clears the phone's alert: decided, resolved, expired or withdrawn.
+  const match = /^(hold|verify\.gate|proposal)\.(?:decided|resolved|closed|expired|withdrawn)$/.exec(event.type || "");
+  if (!match) return null;
+  const kind = match[1] === "verify.gate" ? "gate" : match[1];
+  const id = Number(kind === "hold" ? event.holdId : kind === "gate" ? event.gateId : event.proposalId);
+  if (!id) return null;
+  return { kind, id, project: text(event.project, 80), silent: true };
+}
+
+function alertFor(event, state) {
+  const base = { project: text(event.project, 80), silent: false, direct: false, category: "" };
+  if (event.type === "hold.opened" && Number(event.holdId)) {
+    return { ...base, kind: "hold", id: Number(event.holdId), category: "HOLD",
+      title: `File hold #${Number(event.holdId)}`, body: text(event.file || event.reason) };
+  }
+  if (event.type === "verify.gate.opened" && Number(event.gateId)) {
+    return { ...base, kind: "gate", id: Number(event.gateId), category: "GATE",
+      title: `Verify gate #${Number(event.gateId)}`, body: text(event.claim) };
+  }
+  if (event.type === "proposal.filed" && Number(event.proposalId)) {
+    return { ...base, kind: "proposal", id: Number(event.proposalId), category: "PROPOSAL",
+      title: `Proposal #${Number(event.proposalId)}`, body: text(event.scope) };
+  }
+  if (event.type === "message" && Number(event.msgId)) {
+    return { ...base, kind: "message", id: Number(event.msgId), direct: true,
+      title: `Message from ${text(event.by, 120)}`, body: text(event.text) };
+  }
+  if (event.type === "presence.offline" && state.peers?.[event.by]?.kind === "agent" && Number(event.id)) {
+    return { ...base, kind: "presence", id: Number(event.id),
+      title: `${text(event.by, 120)} offline`, body: text(event.project ? `Crew seat offline in ${event.project}` : "Crew seat offline") };
+  }
+  return null;
+}
+
+export function createNotifier({ state, markDirty, canRead, transport = apnsTransport,
+  env = process.env, now = Date.now, log = line => process.stderr.write(`[trantor] ${line}\n`) }) {
+  const keyId = String(env.APNS_KEY_ID || "");
+  const teamId = String(env.APNS_TEAM_ID || "");
+  let keyText = String(env.APNS_PRIVATE_KEY || env.APNS_KEY || "").replace(/\\n/g, "\n");
+  if (!keyText && env.APNS_KEY_PATH) {
+    try { keyText = readFileSync(String(env.APNS_KEY_PATH), "utf8"); }
+    catch { log("push disabled: APNS_KEY_PATH unreadable"); }
+  }
+  const defaultBundleId = String(env.APNS_BUNDLE_ID || "ai.trantor.companion");
+  let privateKey = null;
+  if (keyId && teamId && keyText) {
+    try { privateKey = createPrivateKey(keyText); }
+    catch { log("push disabled: invalid APNs key"); }
+  } else {
+    log("push disabled: no APNs key");
+  }
+  let cachedJwt = "";
+  let cachedJwtAt = 0;
+
+  function jwt() {
+    const time = now();
+    if (cachedJwt && time >= cachedJwtAt && time - cachedJwtAt < JWT_REUSE_MS) return cachedJwt;
+    const header = Buffer.from(JSON.stringify({ alg: "ES256", kid: keyId })).toString("base64url");
+    const claims = Buffer.from(JSON.stringify({ iss: teamId, iat: Math.floor(time / 1000) })).toString("base64url");
+    const signature = sign("sha256", Buffer.from(`${header}.${claims}`), { key: privateKey, dsaEncoding: "ieee-p1363" }).toString("base64url");
+    cachedJwt = `${header}.${claims}.${signature}`;
+    cachedJwtAt = time;
+    return cachedJwt;
+  }
+
+  function dropDevice(device) {
+    const index = state.devices.findIndex(d => d.pubkey === device.pubkey && d.apns_token === device.apns_token);
+    if (index < 0) return;
+    state.devices.splice(index, 1);
+    markDirty();
+  }
+
+  async function send(device, delivery) {
+    const aps = delivery.silent
+      ? { "content-available": 1 }
+      : { alert: { title: delivery.title, body: delivery.body }, sound: "default" };
+    if (delivery.category) aps.category = delivery.category;
+    const payload = JSON.stringify({ aps, kind: delivery.kind, id: delivery.id, project: delivery.project });
+    // kind in the id: hold #5 and gate #5 are different alerts
+    const collapseId = `${delivery.kind}-${delivery.id}`;
+    try {
+      const result = await transport({
+        host: APNS_HOSTS[device.env] || APNS_HOSTS.production,
+        path: `/3/device/${device.apns_token}`,
+        headers: {
+          authorization: `bearer ${jwt()}`,
+          "apns-topic": device.bundle_id || defaultBundleId,
+          "apns-push-type": delivery.silent ? "background" : "alert",
+          "apns-priority": delivery.silent ? "5" : "10",
+          "apns-collapse-id": collapseId,
+        },
+        body: payload,
+      });
+      let reason = "";
+      try { reason = JSON.parse(result.body || "{}").reason || ""; } catch {}
+      if (result.status === 410 || reason === "BadDeviceToken") {
+        dropDevice(device);
+        return;
+      }
+      if (result.status !== 200) {
+        log(`push failed (${Number(result.status || 0)}): ${reason || "APNs error"}`);
+        return;
+      }
+      const current = state.devices.find(d => d.pubkey === device.pubkey && d.apns_token === device.apns_token);
+      if (current) {
+        current.last_ok = now();
+        markDirty();
+      }
+    } catch (error) {
+      log(`push failed: ${text(error?.message || error)}`);
+    }
+  }
+
+  async function notify(event) {
+    if (!privateKey) return;
+    const delivery = clearFor(event) || alertFor(event, state);
+    if (!delivery) return;
+    const deliveries = [];
+    for (const device of [...(state.devices || [])]) {
+      const identity = state.identities?.[device.pubkey];
+      if (!identity || identity.revoked || !canRead({ identity }, delivery.project)) continue;
+      if ((device.muted_projects || []).includes(delivery.project)) continue;
+      if (delivery.direct && String(identity.name || "") !== String(event.toSession || "")) continue;
+      deliveries.push(send(device, delivery));
+    }
+    await Promise.all(deliveries);
+  }
+
+  return { notify };
+}

package/hub/routes/admin.mjs

@@ -305,7 +305,7 @@ export async function routeAdmin({ req, res, q, P, auth, ctx }) {
       const b = await body(req);
       const hold = overseer.listHolds().find(h => h.id === Number(b.id));
       if (!hold) return json(res, 404, { error: "hold expired or not found" });
-      if (AUTH_MODE !== "off" && !scopeAllows(auth?.identity, hold.project, "owner")) return json(res, 403, { error: "operator permission required" });
+      if (AUTH_MODE !== "off" && !scopeAllows(auth?.identity, hold.project, "approver")) return json(res, 403, { error: "operator permission required" });
       if (b.status !== "go" && b.status !== "nogo") return json(res, 400, { error: "status must be go or nogo" });
       const decided = overseer.decideHold(hold.id, b.status, auth?.identity?.name || "operator");
       return decided ? json(res, 200, { ok: true, hold: decided }) : json(res, 409, { error: "hold already decided" });

package/hub/routes/cards.mjs

@@ -38,7 +38,7 @@ export async function routeCards({ req, res, q, P, auth, ctx }) {
     appendTaskLog, appendTaskNote, cleanChecklist, cleanDrill, hasDrillLine, linkCommitToFocus,
     derivePhases, PROPOSAL_CAP, propFp, healthOf, REAP_GRACE_MS, subFp,
     prunePeers, canRead, HUB_VERSION, cmpSemver, isCardEvent, fmtAge, hubSend,
-    ONLINE_MS, PEER_TTL_MS, AUTH_MODE,
+    ONLINE_MS, PEER_TTL_MS, AUTH_MODE, scopeAllows,
   } = ctx;
     if (req.method === "POST" && P === "/task") {           // create a card
       const b = await body(req);
@@ -647,7 +647,7 @@ export async function routeCards({ req, res, q, P, auth, ctx }) {
     // --- agent-proposed permissions (governance): the autonomy ladder made two-directional ---
     // An agent needing more rope FILES A PROPOSAL here instead of assuming or working around.
     // Enforced HERE: unbounded proposal = 400; queue caps at 3 pending/session; near-duplicate of
-    // a DENIED proposal = refused. Deciding is the HUMAN's alone — /proposal/decide is owner-gated.
+    // a DENIED proposal = refused. Deciding is the HUMAN's alone — /proposal/decide requires approver or owner.
     if (req.method === "POST" && P === "/propose") {
       const b = await body(req);
       const session = String(b.session || b.by || "").slice(0, 120);
@@ -689,6 +689,7 @@ export async function routeCards({ req, res, q, P, auth, ctx }) {
       const b = await body(req);
       const pr = state.proposals.find(p => p.id === Number(b.id));
       if (!pr) return json(res, 404, { error: "no such proposal" });
+      if (AUTH_MODE !== "off" && !scopeAllows(auth?.identity, pr.project, "approver")) return json(res, 403, { error: "operator permission required" });
       // A grant that GATES tool behavior needs an off-switch: the operator may REVOKE an
       // approved proposal. Revocation is not a denial — it leaves no denial memory, so the
       // agent may re-propose a refined bound later.

package/hub/routes/devices.mjs

@@ -0,0 +1,55 @@
+export async function routeDevices({ req, res, q, P, auth, ctx }) {
+  if (!((req.method === "POST" && (P === "/device/register" || P === "/device/unregister")) ||
+    (req.method === "GET" && P === "/devices"))) return false;
+  const { state, body, json, markDirty, canon, AUTH_MODE } = ctx;
+  if (AUTH_MODE === "off" || !auth?.identity || !auth?.pubkey) {
+    return json(res, 401, { error: "signed identity required" });
+  }
+  const pubkey = auth.pubkey;
+  state.devices ||= [];
+
+  if (req.method === "GET") {
+    if (q.pubkey && q.pubkey !== pubkey) return json(res, 403, { error: "cannot read another signer's devices" });
+    return json(res, 200, { devices: state.devices.filter(d => d.pubkey === pubkey) });
+  }
+
+  const b = await body(req);
+  if (b.pubkey && b.pubkey !== pubkey) return json(res, 403, { error: "cannot manage another signer's devices" });
+  const token = String(b.apnsToken || b.apns_token || "").trim().toLowerCase();
+  if (!/^[a-f0-9]{32,128}$/.test(token)) return json(res, 400, { error: "a hexadecimal apnsToken is required" });
+
+  if (P === "/device/unregister") {
+    const index = state.devices.findIndex(d => d.apns_token === token && d.pubkey === pubkey);
+    if (index < 0) return json(res, 404, { error: "device not found" });
+    const [device] = state.devices.splice(index, 1);
+    markDirty();
+    return json(res, 200, { ok: true, device });
+  }
+
+  const requestedEnv = String(b.env || "production").toLowerCase();
+  const env = requestedEnv === "development" ? "sandbox" : requestedEnv;
+  if (env !== "sandbox" && env !== "production") return json(res, 400, { error: "env must be sandbox or production" });
+  // A token is one physical device. Re-pairing makes a new key for the same phone, so the newest
+  // registration wins and the old identity's row goes; otherwise a re-paired phone loses push.
+  const before = state.devices.length;
+  state.devices = state.devices.filter(d => d.apns_token !== token || d.pubkey === pubkey);
+  if (state.devices.length !== before) markDirty();
+  const existing = state.devices.find(d => d.apns_token === token && d.pubkey === pubkey);
+  const muted = Array.isArray(b.muted_projects) ? b.muted_projects : b.mutedProjects;
+  const device = {
+    pubkey,
+    apns_token: token,
+    env,
+    bundle_id: String(b.bundleId || b.bundle_id || process.env.APNS_BUNDLE_ID || "ai.trantor.companion").slice(0, 200),
+    name: String(b.name || auth.identity.name || "").slice(0, 120),
+    created: existing?.created || Date.now(),
+    last_ok: existing?.last_ok || 0,
+    muted_projects: Array.isArray(muted)
+      ? [...new Set(muted.map(p => canon(String(p).slice(0, 80))).filter(Boolean))].slice(0, 100)
+      : (existing?.muted_projects || []),
+  };
+  if (existing) Object.assign(existing, device);
+  else state.devices.push(device);
+  markDirty();
+  return json(res, 200, { ok: true, device: existing || device });
+}

package/hub/routes/messages.mjs

@@ -7,7 +7,7 @@ export async function routeMessages({ req, res, q, P, auth, ctx }) {
   const {
     state, body, json, stripNulText, crossProjectGuard, touch, pushToStreams,
     appendEvent, appendCardEvent, appendTaskLog, markDelivered, contractsFor, canUseInboxSession, inboxWindow,
-    deliverable, inboxReadable, inboxResponse, filterReadable, streams, UI,
+    deliverable, inboxReadable, inboxResponse, filterReadable, canRead, streams, UI,
     AUTH_MODE, persistHealth, duty, now, markDirty, assertNoSecrets, PEER_TTL_MS,
     CONTRACT_WINDOW_MS,
   } = ctx;
@@ -143,7 +143,13 @@ export async function routeMessages({ req, res, q, P, auth, ctx }) {
       touch(session, q.status, undefined, undefined, auth);
       // events=1 opts this stream into the unified log as NAMED "ev" frames (see pushEventToStreams).
       // Existing consumers omit it and keep receiving bus messages on the default channel only.
-      const entry = { session, res, events: q.events === "1" };
+      // #12112: a stream carries only what its signer may read, by the same checks /inbox and /events
+      // apply, so a key scoped to one project never sees another project's messages or events live.
+      const entry = {
+        session, res, events: q.events === "1",
+        readsMessage: m => inboxReadable(auth, m, session),
+        readsEvent: ev => canRead(auth, ev.project || ""),
+      };
       streams.push(entry);
       const ka = setInterval(() => {
         if (res.writableEnded || res.destroyed) return;

package/hub/routes/session.mjs

@@ -0,0 +1,187 @@
+// #12129: the hub is the meeting point between the desktop relay and the phone. The chat mirror
+// is MEMORY-ONLY (a restart answers have:0, the desktop resends its window); the prompt queue
+// lives in state so a restart never strands a queued prompt. Live frames ride pushEventToStreams
+// (scope-filtered, never logged); only chat.prompt.queued/.delivered/.failed are audit-appended.
+import { setInterval } from "node:timers";
+
+const CHAT_CAP = 400;            // turns kept per project, highest idx wins
+const CHAT_PAGE = 200;           // max turns per GET
+const PROMPT_CAP = 200;
+const PROMPT_TEXT_MAX = 8000;
+const EVENT_TEXT_MAX = 500;
+const PROMPT_TTL_MS = Number(process.env.RELAY_PROMPT_TTL_MS || 120000);
+const PROMPT_SWEEP_MS = Number(process.env.RELAY_PROMPT_SWEEP_MS || 30000);
+const EXPIRED_REASON = "No Mac is relaying this project. Is the Trantor app open?";
+const ACK_OUTCOMES = new Set(["delivered", "blocked", "not_ready", "stalled", "no_agent"]);
+
+export function createSessionRuntime({ state, markDirty, appendEvent, pushEventToStreams }) {
+  const now = () => Date.now();
+  const mirrors = new Map();     // project -> { session, total, turns: Map(idx->turn), have, meta, updatedAt, host }
+  state.sessionPrompts ||= [];
+  state.sessionPromptSeq = Number(state.sessionPromptSeq || 0);
+
+  const findPrompt = (id) => state.sessionPrompts.find(p => p.id === Number(id));
+
+  // A prompt still queued past the TTL means no desktop relay claimed it. Expiry is lazy (on
+  // read) plus a sweep that is a no-op when nothing is queued, so an idle hub does no work.
+  function expireQueued() {
+    let changed = false;
+    for (const p of state.sessionPrompts) {
+      if (p.status !== "queued" || now() - p.ts <= PROMPT_TTL_MS) continue;
+      p.status = "expired"; p.outcome = "expired"; p.error = EXPIRED_REASON;
+      appendEvent("chat.prompt.failed", p.project, p.by, { promptId: p.id, outcome: "expired", error: EXPIRED_REASON });
+      changed = true;
+    }
+    if (changed) markDirty();
+    return changed;
+  }
+  const sweep = setInterval(() => {
+    if (state.sessionPrompts.some(p => p.status === "queued")) expireQueued();
+  }, PROMPT_SWEEP_MS);
+  sweep.unref?.();
+
+  function mergeChat(b, auth) {
+    const project = String(b.project || "").slice(0, 80);
+    const session = String(b.session || "").slice(0, 200);
+    if (!project) return { code: 400, body: { error: "project required" } };
+    if (!session) return { code: 400, body: { error: "session required" } };
+    let m = mirrors.get(project);
+    // A different session resets the mirror (handoff/compaction): the desktop then sends its
+    // whole window, and stale turns from the previous session must not survive the switch.
+    if (!m || m.session !== session) {
+      m = { session, total: 0, turns: new Map(), have: 0, meta: {}, updatedAt: 0, host: "" };
+      mirrors.set(project, m);
+    }
+    // The last turn grows while the assistant writes, so the desktop resends from the lowest
+    // changed idx and the hub REPLACES by idx — re-sends are idempotent by construction.
+    for (const t of Array.isArray(b.turns) ? b.turns : []) {
+      const idx = Number(t?.idx);
+      if (!Number.isInteger(idx) || idx < 0) continue;
+      const clean = {
+        idx,
+        role: String(t.role || "").slice(0, 40),
+        blocks: Array.isArray(t.blocks) ? t.blocks : [],
+      };
+      if (t.queued) clean.queued = true;
+      m.turns.set(idx, clean);
+      if (idx + 1 > m.have) m.have = idx + 1;
+    }
+    if (m.turns.size > CHAT_CAP) {
+      const drop = [...m.turns.keys()].sort((a, b) => a - b).slice(0, m.turns.size - CHAT_CAP);
+      for (const k of drop) m.turns.delete(k);
+    }
+    m.total = Math.max(0, Number(b.total) || 0);
+    // Property access on a primitive is safe (undefined); only null/undefined would throw.
+    const meta = b.meta || {};
+    m.meta = {
+      working: !!meta.working,
+      model: String(meta.model || "").slice(0, 120),
+      context: meta.context ?? null,
+    };
+    m.updatedAt = now();
+    m.host = String(b.host || auth?.identity?.name || "").slice(0, 120);
+    pushEventToStreams({ ts: m.updatedAt, type: "chat.updated", project, total: m.total, working: m.meta.working });
+    return { code: 200, body: { ok: true, have: m.have } };
+  }
+
+  async function route({ req, res, q, P, auth, ctx }) {
+    const isChat = P === "/session/chat";
+    const isPrompts = P === "/session/prompts";
+    const isPrompt = P === "/session/prompt" || P === "/session/prompt/claim" || P === "/session/prompt/ack";
+    if (!isChat && !isPrompts && !isPrompt) return false;
+    const { body, json, canon } = ctx;
+
+    if (req.method === "POST" && isChat) {
+      const b = await body(req);
+      // the same canon the GET reads with, or a publish and a read could name two mirrors
+      b.project = canon(String(b.project || "").slice(0, 80));
+      const r = mergeChat(b, auth);
+      return json(res, r.code, r.body);
+    }
+
+    if (req.method === "GET" && isChat) {
+      const project = canon(String(q.project || "").slice(0, 80));
+      const m = mirrors.get(project);
+      if (!m) return json(res, 200, { session: "", total: 0, turns: [], meta: {}, updatedAt: 0, host: "" });
+      const afterRaw = Number(q.after);
+      const after = Number.isFinite(afterRaw) ? afterRaw : -1;
+      const turns = [...m.turns.values()].filter(t => t.idx > after).sort((a, b) => a.idx - b.idx).slice(0, CHAT_PAGE);
+      return json(res, 200, { session: m.session, total: m.total, turns, meta: m.meta, updatedAt: m.updatedAt, host: m.host });
+    }
+
+    if (req.method === "POST" && P === "/session/prompt") {
+      const b = await body(req);
+      const project = canon(String(b.project || "").slice(0, 80));
+      const text = String(b.text || "");
+      if (!project || !text.trim()) return json(res, 400, { error: "project and non-empty text required" });
+      if (text.length > PROMPT_TEXT_MAX) return json(res, 400, { error: `text must be <= ${PROMPT_TEXT_MAX} chars` });
+      expireQueued();
+      state.sessionPromptSeq += 1;
+      const p = { id: state.sessionPromptSeq, project, text, by: String(auth?.identity?.name || "").slice(0, 120), ts: now(), status: "queued" };
+      state.sessionPrompts.push(p);
+      // Cap: evict oldest terminal rows first so live work is never the first casualty.
+      while (state.sessionPrompts.length > PROMPT_CAP) {
+        const ti = state.sessionPrompts.findIndex(x => x.status !== "queued" && x.status !== "claimed");
+        state.sessionPrompts.splice(ti >= 0 ? ti : 0, 1);
+      }
+      markDirty();
+      appendEvent("chat.prompt.queued", project, p.by, { promptId: p.id, text: text.slice(0, EVENT_TEXT_MAX) });
+      pushEventToStreams({ ts: p.ts, type: "chat.prompt", id: p.id, project });
+      return json(res, 200, { id: p.id, status: "queued" });
+    }
+
+    if (req.method === "GET" && isPrompts) {
+      expireQueued();
+      const project = canon(String(q.project || "").slice(0, 80));
+      const status = String(q.status || "").slice(0, 40);
+      const prompts = state.sessionPrompts
+        .filter(p => (!project || p.project === project) && (!status || p.status === status))
+        .map(p => ({ id: p.id, project: p.project, text: p.text, by: p.by, ts: p.ts, status: p.status }));
+      return json(res, 200, { prompts });
+    }
+
+    if (req.method === "POST" && P === "/session/prompt/claim") {
+      const b = await body(req);
+      expireQueued();
+      const p = findPrompt(b.id);
+      if (!p) return json(res, 404, { error: "prompt not found" });
+      // The first claim wins; a second claim — even from the same host — gets 409.
+      if (p.status !== "queued") return json(res, 409, { error: `prompt already ${p.status}`, status: p.status });
+      p.status = "claimed"; p.host = String(b.host || "").slice(0, 120); p.claimedAt = now();
+      markDirty();
+      // The full text goes only to the claimer.
+      return json(res, 200, { ok: true, prompt: { id: p.id, project: p.project, text: p.text, by: p.by, ts: p.ts } });
+    }
+
+    if (req.method === "POST" && P === "/session/prompt/ack") {
+      const b = await body(req);
+      const p = findPrompt(b.id);
+      if (!p) return json(res, 404, { error: "prompt not found" });
+      const outcome = String(b.outcome || "");
+      if (!ACK_OUTCOMES.has(outcome)) return json(res, 400, { error: `outcome must be one of: ${[...ACK_OUTCOMES].join(", ")}` });
+      if (p.status === "delivered" || p.status === "failed" || p.status === "expired") {
+        return json(res, 409, { error: `prompt already ${p.status}`, status: p.status });
+      }
+      const error = String(b.error || "").slice(0, EVENT_TEXT_MAX);
+      p.outcome = outcome; p.error = error; p.ackedAt = now();
+      p.status = outcome === "delivered" ? "delivered" : "failed";
+      markDirty();
+      const extra = { promptId: p.id, outcome };
+      if (error) extra.error = error;
+      appendEvent(outcome === "delivered" ? "chat.prompt.delivered" : "chat.prompt.failed", p.project,
+        String(auth?.identity?.name || ""), extra);
+      return json(res, 200, { ok: true, status: p.status });
+    }
+
+    if (req.method === "GET" && P === "/session/prompt") {
+      expireQueued();
+      const p = findPrompt(q.id);
+      if (!p) return json(res, 404, { error: "prompt not found" });
+      return json(res, 200, { id: p.id, status: p.status, outcome: p.outcome || "", error: p.error || "" });
+    }
+
+    return false;
+  }
+
+  return { route, expireQueued };
+}

package/hub/store.mjs

@@ -6,7 +6,7 @@ import { DEFAULT_ORG } from "../lib/store-contract.mjs";
 
 export async function createStoreRuntime({ STORE_KIND, PG_URL, ORG_ID, DATA }) {
 function emptyState() {
-  return { messages: [], peers: {}, seq: 0, tasks: [], taskSeq: 0, projectMeta: {}, lessons: [], events: [], cardEventsBackfilled: false, aliases: {}, phaseMeta: {}, verifyGates: [], verifyGateSeq: 0, proposals: [], proposalSeq: 0, balances: { ts: 0, by: "", entries: [] }, balancesByMachine: {}, subagentCostReset: false, handoffLog: [], identities: {}, inviteTokens: {}, focus: {}, orgPolicy: {}, overseerState: {}, instances: {}, dutySession: "", contractReap: {}, eventSeq: 0 };
+  return { messages: [], peers: {}, seq: 0, tasks: [], taskSeq: 0, projectMeta: {}, lessons: [], events: [], cardEventsBackfilled: false, aliases: {}, phaseMeta: {}, verifyGates: [], verifyGateSeq: 0, proposals: [], proposalSeq: 0, balances: { ts: 0, by: "", entries: [] }, balancesByMachine: {}, subagentCostReset: false, handoffLog: [], identities: {}, devices: [], inviteTokens: {}, focus: {}, orgPolicy: {}, overseerState: {}, instances: {}, dutySession: "", contractReap: {}, eventSeq: 0, sessionPrompts: [], sessionPromptSeq: 0 };
 }
 
 const CARD_LOG_MAX = 40;
@@ -107,6 +107,7 @@ function normalizeState(loaded = {}) {
   s.subagentCostReset = !!loaded.subagentCostReset;
   s.handoffLog = Array.isArray(loaded.handoffLog) ? loaded.handoffLog : [];
   s.identities = loaded.identities && typeof loaded.identities === "object" ? loaded.identities : {};
+  s.devices = Array.isArray(loaded.devices) ? loaded.devices : [];
   s.inviteTokens = loaded.inviteTokens && typeof loaded.inviteTokens === "object" ? loaded.inviteTokens : {};
   s.instances = loaded.instances && typeof loaded.instances === "object" ? loaded.instances : {};
   s.focus = loaded.focus && typeof loaded.focus === "object" ? loaded.focus : {};
@@ -114,6 +115,10 @@ function normalizeState(loaded = {}) {
   s.overseerState = loaded.overseerState || {};
   s.dutySession = String(loaded.dutySession || "");
   s.contractReap = loaded.contractReap && typeof loaded.contractReap === "object" ? loaded.contractReap : {};
+  // #12129: the phone's prompt queue survives a hub restart (JSON store); the id high-water mark
+  // is rebuilt from the rows so a reloaded queue never mints a colliding id.
+  s.sessionPrompts = Array.isArray(loaded.sessionPrompts) ? loaded.sessionPrompts : [];
+  s.sessionPromptSeq = Number(loaded.sessionPromptSeq || Math.max(0, ...s.sessionPrompts.map(p => Number(p.id) || 0))) || 0;
   // The event id high-water mark. Seeded from the store's own MAX(id) where it supplied one, and
   // otherwise from the largest id in the array — never from the array TAIL, which is exactly the
   // assumption that let a clobbered id mint colliding event ids and kill the log.

package/hub.mjs

@@ -17,6 +17,9 @@ import { routeAdmin } from "./hub/routes/admin.mjs";
 import { routeCards } from "./hub/routes/cards.mjs";
 import { routeInsights } from "./hub/routes/insights.mjs";
 import { routeMessages } from "./hub/routes/messages.mjs";
+import { routeDevices } from "./hub/routes/devices.mjs";
+import { createSessionRuntime } from "./hub/routes/session.mjs";
+import { createNotifier } from "./hub/notifier.mjs";
 
 const PORT = Number(process.env.RELAY_PORT || 4477);
 const HOST = process.env.RELAY_HOST || "127.0.0.1";
@@ -63,7 +66,8 @@ const authRuntime = createAuthRuntime({
   state: store.state, markDirty: store.markDirty, AUTH_MODE, SUPERSEDE_GRACE_MS,
   LOOPBACK_BIND, ENROLL_MODE,
 });
-const events = createEventRuntime({ state: store.state, markDirty: store.markDirty, AUTH_MODE, ONLINE_MS, canon: authRuntime.canon });
+const notifier = createNotifier({ state: store.state, markDirty: store.markDirty, canRead: authRuntime.canRead });
+const events = createEventRuntime({ state: store.state, markDirty: store.markDirty, AUTH_MODE, ONLINE_MS, canon: authRuntime.canon, notifier });
 runStoreMigrations({ ...store, subFp: authRuntime.subFp });
 if (process.argv.includes("--smoke")) {
   // The smoke exists to refuse a restart that would boot into a broken store: a configured pg
@@ -122,7 +126,11 @@ const context = {
   hubSend: duty.hubSend, assertNoSecrets, UI, AUTH_MODE, ONLINE_MS, PEER_TTL_MS,
   REAP_GRACE_MS, CONTRACT_WINDOW_MS,
 };
-const routes = [routeAdmin, routeCards, routeInsights, routeMessages];
+const sessionChat = createSessionRuntime({
+  state: store.state, markDirty: store.markDirty,
+  appendEvent: events.appendEvent, pushEventToStreams: events.pushEventToStreams,
+});
+const routes = [routeDevices, routeAdmin, routeCards, routeInsights, routeMessages, sessionChat.route];
 
 const server = http.createServer(async (req, res) => {
   const u = new URL(req.url, "http://x");

package/lib/identity.mjs

@@ -28,7 +28,7 @@ export const HDR_INST = {
 };
 
 const busDir = () => process.env.AGENT_BUS_DIR || join(homedir(), ".agent-bus");
-const keysDir = () => join(busDir(), "keys");
+export const keysDir = () => join(busDir(), "keys");
 // A name is cosmetic, but it becomes a filename, so it gets sanitised twice over: dot-runs collapse
 // FIRST (so no `..` survives even in principle), then anything outside the safe charset goes. Relying
 // on "we stripped the separators" alone would make traversal one regex edit away.
@@ -187,17 +187,17 @@ export function loadOrCreate(name, kind = "agent") {
   const f = keyPath(name);
   const tmp = `${f}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
   try {
-    writeFileSync(tmp, JSON.stringify(id), { mode: 0o600 });
-    if (existsSync(f)) {                                     // someone beat us between check and write
-      try { unlinkSync(tmp); } catch {}                      // the loser's tmp still holds a private key
-      return load(name) || id;
+    try {
+      writeFileSync(tmp, JSON.stringify(id), { mode: 0o600 });
+      if (existsSync(f)) return load(name) || id;             // someone beat us between check and write
+      renameSync(tmp, f);
+      chmodSync(f, 0o600);
+      processCache.set(cacheKey(String(name)), id);
+      return id;
+    } finally {
+      try { unlinkSync(tmp); } catch {}                       // unconditional: no early exit leaves a tmp holding a private key
     }
-    renameSync(tmp, f);
-    chmodSync(f, 0o600);
-    processCache.set(cacheKey(String(name)), id);
-    return id;
   } catch {
-    try { unlinkSync(tmp); } catch {}
     return load(name) || id;                                  // lost the race, or unwritable — never throw
   }
 }
@@ -220,8 +220,12 @@ export function listKeyNames() {
 function writeKeyStub(f, id) {
   const stub = { name: id.name, kind: id.kind, pubkey: id.pubkey, createdAt: id.createdAt, keychain: IDENTITY_SERVICE };
   const tmp = `${f}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
-  writeFileSync(tmp, JSON.stringify(stub), { mode: 0o600 });
-  renameSync(tmp, f);
+  try {
+    writeFileSync(tmp, JSON.stringify(stub), { mode: 0o600 });
+    renameSync(tmp, f);
+  } finally {
+    try { unlinkSync(tmp); } catch {}                         // a failed rename must not strand its tmp
+  }
   try { chmodSync(f, 0o600); } catch {}
 }
 
@@ -353,11 +357,15 @@ export function loadOrCreateInstance(durableIdentity, instanceId) {
       durablePubkey: durableIdentity.pubkey,
     };
     const tmp = `${f}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
-    writeFileSync(tmp, JSON.stringify(inst), { mode: 0o600 });
-    if (existsSync(f)) { try { return JSON.parse(readFileSync(f, "utf8")); } catch { return inst; } }
-    renameSync(tmp, f);
-    chmodSync(f, 0o600);
-    return inst;
+    try {
+      writeFileSync(tmp, JSON.stringify(inst), { mode: 0o600 });
+      if (existsSync(f)) { try { return JSON.parse(readFileSync(f, "utf8")); } catch { return inst; } }
+      renameSync(tmp, f);
+      chmodSync(f, 0o600);
+      return inst;
+    } finally {
+      try { unlinkSync(tmp); } catch {}                       // the race loser's tmp still holds a private key — never strand it
+    }
   } catch { return null; }                                  // unwritable — caller falls back to durable
 }
 

package/lib/key-prune.mjs

@@ -1,5 +1,6 @@
-import { lstatSync, readFileSync, unlinkSync } from "node:fs";
-import { keyPath, listKeyNames } from "./identity.mjs";
+import { lstatSync, readFileSync, unlinkSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { keyPath, listKeyNames, keysDir } from "./identity.mjs";
 
 import { isTestIdentity } from "./test-identity-names.mjs";
 export { isTestIdentity } from "./test-identity-names.mjs";
@@ -47,3 +48,30 @@ export function pruneTestKeys({ snapshots, idleDays = 7, apply = false, now = Da
   }
   return { dryRun: !apply, idleDays, removed, kept };
 }
+
+// An interrupted atomic key write strands `<name>.json.<pid>.<rand>.tmp` — and a tmp from a lost
+// race holds a full PRIVATE key. Real keys always end in `.json`, so anything ending in `.tmp` in
+// the keys tree is by construction an incomplete write; an hour past its mtime no live writer is
+// still between write and rename, so it is safe to remove (--apply only, like the rest of prune).
+export function pruneStaleTmp({ maxAgeMs = 3_600_000, apply = false, now = Date.now() } = {}) {
+  if (!Number.isFinite(maxAgeMs) || maxAgeMs <= 0) throw new Error("tmp age must be a positive number");
+  const cutoff = now - maxAgeMs;
+  const removed = [], kept = [];
+  for (const dir of [keysDir(), join(keysDir(), "instances")]) {
+    let entries = [];
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      if (!entry.name.endsWith(".tmp")) continue;              // a real key file never matches
+      const file = join(dir, entry.name);
+      let stat;
+      try { stat = lstatSync(file); } catch { continue; }      // vanished mid-sweep
+      if (!stat.isFile() || stat.isSymbolicLink()) continue;   // never follow a link out of the keys tree
+      if (stat.mtimeMs >= cutoff) { kept.push(file); continue; }
+      if (apply) {
+        try { unlinkSync(file); } catch { kept.push(file); continue; }
+      }
+      removed.push(file);
+    }
+  }
+  return { dryRun: !apply, maxAgeMs, removed, kept };
+}

package/lib/store-contract.mjs

@@ -42,6 +42,19 @@ CREATE TABLE IF NOT EXISTS identities (
 ALTER TABLE identities DROP CONSTRAINT IF EXISTS identities_kind_check;
 ALTER TABLE identities ADD CONSTRAINT identities_kind_check CHECK (kind IN (${IDENTITY_KINDS_SQL}));
 
+CREATE TABLE IF NOT EXISTS devices (
+  org_id         TEXT NOT NULL,
+  pubkey         TEXT NOT NULL,
+  apns_token     TEXT NOT NULL,
+  env            TEXT NOT NULL CHECK (env IN ('sandbox','production')),
+  bundle_id      TEXT NOT NULL,
+  name           TEXT NOT NULL DEFAULT '',
+  created        BIGINT NOT NULL,
+  last_ok        BIGINT NOT NULL DEFAULT 0,
+  muted_projects JSONB NOT NULL DEFAULT '[]'::jsonb,
+  PRIMARY KEY (org_id, apns_token)
+);
+
 
 -- THE LOG. Append-only, never updated, never deleted except by retention. Everything else derives.
 CREATE TABLE IF NOT EXISTS events (

package/lib/store-pg.mjs

@@ -139,6 +139,19 @@ function identityFromRow(row) {
   };
 }
 
+function deviceFromRow(row) {
+  return {
+    pubkey: row.pubkey,
+    apns_token: row.apns_token,
+    env: row.env,
+    bundle_id: row.bundle_id,
+    name: row.name || "",
+    created: Number(row.created || 0),
+    last_ok: Number(row.last_ok || 0),
+    muted_projects: Array.isArray(row.muted_projects) ? row.muted_projects : [],
+  };
+}
+
 // The kv projection of hub state — shared by saveSnapshot and saveDelta so the two can never drift.
 function kvFromState(state) {
   return {
@@ -501,6 +514,14 @@ export class PgStore {
         "DELETE FROM peers WHERE org_id=$1 AND NOT (session = ANY($2::text[]))",
         [orgId, Object.keys(state.peers || {})],
       );
+      await c.query("DELETE FROM devices WHERE org_id=$1", [orgId]);
+      for (const d of state.devices || []) {
+        await c.query(
+          `INSERT INTO devices(org_id, pubkey, apns_token, env, bundle_id, name, created, last_ok, muted_projects)
+           VALUES($1,$2,$3,$4,$5,$6,$7,$8,$9::jsonb)`,
+          [orgId, d.pubkey, d.apns_token, d.env, d.bundle_id, d.name || "", ms(d.created, 0), Number(d.last_ok || 0), JSON.stringify(d.muted_projects || [])],
+        );
+      }
       for (const id of Object.values(state.identities || {})) {
         await c.query(
           `INSERT INTO identities(pubkey, org_id, name, kind, scopes, enrolled_by, created_at, revoked_at)
@@ -548,12 +569,13 @@ export class PgStore {
       p => p.session,
     );
     const identities = diffById(Object.values(prev.identities || {}), Object.values(next.identities || {}), i => i.pubkey);
+    const devices = diffById(prev.devices, next.devices, d => d.apns_token);
     const prevKv = kvFromState(prev), nextKv = kvFromState(next);
     const kvChanged = KV_KEYS.filter(k => JSON.stringify(prevKv[k] ?? null) !== JSON.stringify(nextKv[k] ?? null));
 
     const changed = tasks.upserts.length + tasks.deletes.length + events.upserts.length + events.deletes.length
       + messages.upserts.length + messages.deletes.length + peers.upserts.length + peers.deletes.length
-      + identities.upserts.length + kvChanged.length;
+      + identities.upserts.length + devices.upserts.length + devices.deletes.length + kvChanged.length;
     if (!changed) return 0;
 
     const c = await this.pool.connect();
@@ -618,6 +640,17 @@ export class PgStore {
         );
       }
       if (peers.deletes.length) await c.query("DELETE FROM peers WHERE org_id=$1 AND session = ANY($2::text[])", [orgId, peers.deletes]);
+      for (const d of devices.upserts) {
+        await c.query(
+          `INSERT INTO devices(org_id, pubkey, apns_token, env, bundle_id, name, created, last_ok, muted_projects)
+           VALUES($1,$2,$3,$4,$5,$6,$7,$8,$9::jsonb)
+           ON CONFLICT(org_id, apns_token) DO UPDATE SET pubkey=EXCLUDED.pubkey, env=EXCLUDED.env,
+             bundle_id=EXCLUDED.bundle_id, name=EXCLUDED.name, created=EXCLUDED.created,
+             last_ok=EXCLUDED.last_ok, muted_projects=EXCLUDED.muted_projects`,
+          [orgId, d.pubkey, d.apns_token, d.env, d.bundle_id, d.name || "", ms(d.created, 0), Number(d.last_ok || 0), JSON.stringify(d.muted_projects || [])],
+        );
+      }
+      if (devices.deletes.length) await c.query("DELETE FROM devices WHERE org_id=$1 AND apns_token = ANY($2::text[])", [orgId, devices.deletes]);
       for (const id of identities.upserts) {
         await c.query(
           `INSERT INTO identities(pubkey, org_id, name, kind, scopes, enrolled_by, created_at, revoked_at)
@@ -681,12 +714,13 @@ export class PgStore {
   }
 
   async loadSnapshot(orgId) {
-    const [tasks, peersRows, eventsRows, messagesRows, identitiesRows, kvRows, eventMaxRow] = await Promise.all([
+    const [tasks, peersRows, eventsRows, messagesRows, identitiesRows, devicesRows, kvRows, eventMaxRow] = await Promise.all([
       this.pool.query("SELECT * FROM tasks WHERE org_id=$1 ORDER BY id ASC", [orgId]),
       this.pool.query("SELECT * FROM peers WHERE org_id=$1 ORDER BY session ASC", [orgId]),
       this.pool.query("SELECT * FROM events WHERE org_id=$1 ORDER BY id ASC", [orgId]),
       this.pool.query("SELECT * FROM messages WHERE org_id=$1 ORDER BY id ASC", [orgId]),
       this.pool.query("SELECT * FROM identities WHERE org_id=$1 ORDER BY created_at ASC", [orgId]),
+      this.pool.query("SELECT * FROM devices WHERE org_id=$1 ORDER BY created ASC", [orgId]),
       this.pool.query("SELECT key, value FROM kv WHERE org_id=$1", [orgId]),
       // The authoritative high-water mark for event ids. Deriving it from the loaded array is what
       // broke: a clobbered tail reported a lower id than the table actually held. Ask the table.
@@ -730,6 +764,7 @@ export class PgStore {
       subagentCostReset: !!kv.subagentCostReset,
       handoffLog: Array.isArray(kv.handoffLog) ? kv.handoffLog : [],
       identities,
+      devices: devicesRows.rows.map(deviceFromRow),
       inviteTokens: meta.inviteTokens && typeof meta.inviteTokens === "object" ? meta.inviteTokens : {},
       instances: meta.instances && typeof meta.instances === "object" ? meta.instances : {},
       balancesByMachine: meta.balancesByMachine && typeof meta.balancesByMachine === "object" ? meta.balancesByMachine : {},

package/package.json

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