trantor 0.18.109 → 0.18.110

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.109",
+  "version": "0.18.110",
   "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/pair.mjs

@@ -0,0 +1,85 @@
+#!/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 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: trantor pair [--role owner] [--sim] [--json]");
+  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 OWNER_ENDPOINTS = new Set(["/project/delete", "/sweep", "/reconcile", "/invite", "/import", "/policy"]);
+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"]);
-const roleRank = { read: 1, write: 2, owner: 3 };
+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) {
@@ -247,6 +248,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/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 };
 }
 
 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 : {};

package/hub.mjs

@@ -17,6 +17,8 @@ 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 { 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 +65,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 +125,7 @@ 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 routes = [routeDevices, routeAdmin, routeCards, routeInsights, routeMessages];
 
 const server = http.createServer(async (req, res) => {
   const u = new URL(req.url, "http://x");

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.110",
   "type": "module",
   "bin": {
     "trantor": "bin/cli.mjs"