trantor 0.17.52 → 0.17.55

package/bin/summarize.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// trantor summarize — narrative cards: what was ASSIGNED and what was DONE, in plain language.
+//
+//   trantor summarize [--project <p>] [--limit N] [--all] [--dry] [--quiet]
+//
+// Title-cleaning makes machine-generated cards readable; it cannot make them MEAN anything. This
+// gives each card a one-line narrative ("assigned — did") written by a CHEAP model from the card's
+// own thread (its events + the messages that cite it). The board then reads as a story a human can
+// follow, which was the ask: "what the agent was assigned, what the agent did, what the flow was."
+//
+// Economics by design (the Scrooge doctrine): candidates are MACHINE-TITLED cards without a
+// summary (--all widens to every unsummarized card), batched into ONE cheap-model call per hub,
+// difficulty easy, capped per run. The summary lands via /task/update and rides the tasks.extra
+// column — permanent, never recomputed. Runs ambiently from the heartbeat (hourly, detached) and
+// on demand as `trantor summarize`.
+import { execSync, spawnSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { loadOrCreate } from "../lib/identity.mjs";
+import { sfetchJson } from "../lib/signed-fetch.mjs";
+
+const argv = process.argv.slice(2);
+const val = (k) => { const i = argv.indexOf(`--${k}`); return i >= 0 ? (argv[i + 1] ?? "") : ""; };
+const has = (k) => argv.includes(`--${k}`);
+const QUIET = has("quiet");
+const say = (...a) => { if (!QUIET) console.log(...a); };
+
+const BUS_DIR = process.env.AGENT_BUS_DIR || join(homedir(), ".agent-bus");
+let config = {}; try { config = JSON.parse(readFileSync(join(BUS_DIR, "config.json"), "utf8")); } catch {}
+const LIMIT = Math.max(1, Number(val("limit")) || 25);
+const PROJECT = val("project");
+const OWNER = config.ownerIdentity || "admin";
+const ownerId = loadOrCreate(OWNER, "human");
+
+const scroogeBin = () => process.env.SCROOGE_BIN
+  || (() => { try { return execSync("command -v scrooge", { encoding: "utf8" }).trim(); } catch {} })()
+  || (existsSync(new URL("../engine/bin/scrooge", import.meta.url)) ? new URL("../engine/bin/scrooge", import.meta.url).pathname : "");
+
+// A title no human wrote: protocol frames, dumped prompts, id soup. These are the cards whose
+// board presence is noise until a narrative replaces them.
+const machineTitled = (t) =>
+  /^\s*[<{[]/.test(t) || /<task-notification>|<system-reminder>|toolu_[A-Za-z0-9]/.test(t) ||
+  /^\s*(subagent|general-purpose|Explore|Task|Plan):/i.test(t) || t.length > 130;
+
+const hubs = new Set([config.url || "http://127.0.0.1:4477", ...Object.values(config.hubs || {})]);
+const get = async (hub, path) => (await sfetchJson(`${hub}${path}`, { method: "GET", identity: ownerId, signal: AbortSignal.timeout(8000) })).json();
+const post = async (hub, path, payload) => (await sfetchJson(`${hub}${path}`, { identity: ownerId, payload, signal: AbortSignal.timeout(8000) })).json();
+
+let wrote = 0, considered = 0;
+for (const hub of hubs) {
+  let cards = [];
+  try { cards = (await get(hub, PROJECT ? `/tasks?project=${encodeURIComponent(PROJECT)}` : "/tasks")).tasks ?? []; }
+  catch { continue; }
+  const cand = cards
+    .filter(t => !t.summary && (has("all") || machineTitled(String(t.title || ""))))
+    .sort((a, b) => (b.updated ?? 0) - (a.updated ?? 0))
+    .slice(0, LIMIT);
+  considered += cand.length;
+  if (!cand.length) continue;
+  say(`${hub}: ${cand.length} card(s) need a narrative`);
+
+  // each card's own story: status + thread tail (the agent's reports of what it did)
+  const blocks = [];
+  for (const t of cand) {
+    let thread = "";
+    try {
+      const c = await get(hub, `/card?id=${t.id}`);
+      thread = (c.messages ?? []).slice(-5).map(m => `${m.from}: ${String(m.text).replace(/\s+/g, " ").slice(0, 220)}`).join("\n");
+    } catch {}
+    blocks.push(`CARD #${t.id} [${t.status}]${t.assignee ? ` assignee=${t.assignee}` : ""}\nTITLE: ${String(t.title).replace(/\s+/g, " ").slice(0, 400)}${thread ? `\nTHREAD:\n${thread}` : ""}`);
+  }
+  const prompt = `You write one-line narratives for cards on an AI-agent Kanban board. For EACH card below:
+- "assigned": the task in plain language, action-first, <=70 chars (from TITLE; ignore XML/ids/protocol noise)
+- "did": what actually happened per THREAD and status, <=80 chars; "" if nothing has happened yet
+Plain words a human skims. No ids, no paths unless essential, no XML.
+Return ONLY a JSON array: [{"id":<number>,"assigned":"...","did":"..."}]
+
+${blocks.join("\n\n")}`;
+
+  const bin = scroogeBin();
+  if (!bin) { console.error("scrooge not found (set SCROOGE_BIN) — cannot summarize."); process.exit(1); }
+  const res = spawnSync(bin, ["-t", "summarize", "-d", "easy", "--json"], { input: prompt, encoding: "utf8", timeout: 120000 });
+  if (res.error || (res.status !== 0 && !res.stdout)) { console.error(`scrooge failed: ${(res.stderr || res.error?.message || "").slice(-200)}`); continue; }
+  let rows = [];
+  try { const out = res.stdout || ""; rows = JSON.parse(out.slice(out.indexOf("["), out.lastIndexOf("]") + 1)); }
+  catch { console.error(`unparseable summarizer output: ${(res.stdout || "").slice(0, 200)}`); continue; }
+
+  const byId = new Map(cand.map(t => [t.id, t]));
+  for (const r of rows) {
+    const t = byId.get(Number(r.id));
+    const assigned = String(r.assigned || "").trim();
+    if (!t || !assigned) continue;
+    const summary = (r.did ? `${assigned} — ${String(r.did).trim()}` : assigned).slice(0, 220);
+    if (has("dry")) { say(`  #${t.id} would become: ${summary}`); continue; }
+    try { await post(hub, "/task/update", { id: t.id, summary, by: "scrooge-summarizer" }); wrote++; say(`  #${t.id} → ${summary}`); }
+    catch (e) { say(`  #${t.id} write failed: ${e.message}`); }
+  }
+}
+say(`\n${has("dry") ? "[dry] " : ""}${wrote} narrative(s) written · ${considered} candidate(s) seen`);

package/deploy/backup.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# trantor — backup Postgres + hub data to a timestamped tarball.
+# Safe to run while the hub is running (pg_dump is consistent per snapshot).
+# Retention: keeps last $KEEP_DAYS days (default 30).
+# Usage: ./deploy/backup.sh [--pg-password PASSWORD]
+set -euo pipefail
+
+BACKUP_DIR="${BACKUP_DIR:-/var/lib/trantor/backups}"
+KEEP_DAYS="${KEEP_DAYS:-30}"
+PG_USER="${PG_USER:-trantor}"
+PG_HOST="${PG_HOST:-127.0.0.1}"
+PG_DB="${PG_DB:-trantor}"
+DATA_DIR="${DATA_DIR:-/var/lib/trantor/data}"
+
+PG_PASSWORD=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --pg-password) PG_PASSWORD="$2"; shift 2 ;;
+    -p) PG_PASSWORD="$2"; shift 2 ;;
+    *) echo "unknown flag: $1"; exit 1 ;;
+  esac
+done
+
+mkdir -p "$BACKUP_DIR"
+TIMESTAMP="$(date -u +%Y-%m-%dT%H%M%SZ)"
+BACKUP_FILE="$BACKUP_DIR/trantor-$TIMESTAMP.tar.gz"
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+# Dump Postgres
+if [ -n "$PG_PASSWORD" ]; then
+  PGPASSWORD="$PG_PASSWORD" pg_dump -U "$PG_USER" -h "$PG_HOST" -d "$PG_DB" -Fc -f "$TMP/pg.dump"
+else
+  pg_dump -U "$PG_USER" -h "$PG_HOST" -d "$PG_DB" -Fc -f "$TMP/pg.dump"
+fi
+
+# Copy hub data (bus.json, identities, etc.)
+if [ -d "$DATA_DIR" ]; then
+  cp -r "$DATA_DIR" "$TMP/hub-data"
+fi
+
+tar -czf "$BACKUP_FILE" -C "$TMP" .
+
+# Prune backups older than KEEP_DAYS
+find "$BACKUP_DIR" -name "trantor-*.tar.gz" -mtime "+$KEEP_DAYS" -delete
+
+echo "backup: $BACKUP_FILE ($(du -h "$BACKUP_FILE" | cut -f1))"
+echo "retention: keeping last $KEEP_DAYS days"

package/deploy/docker-compose.yml

@@ -0,0 +1,29 @@
+# trantor netcup deploy — Dockerised Postgres for the relay hub.
+# Start:  docker compose -f deploy/docker-compose.yml up -d
+# Stop:   docker compose -f deploy/docker-compose.yml down
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: trantor-pg
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: trantor
+      POSTGRES_PASSWORD: ${PG_PASSWORD:?set PG_PASSWORD in .env}
+      POSTGRES_DB: trantor
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    ports:
+      - "127.0.0.1:5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U trantor -d trantor"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+volumes:
+  pgdata:

package/deploy/hub.env

@@ -0,0 +1,29 @@
+# trantor hub env — deployed on netcup (Debian 13)
+# Bind to the tailnet IP so agents on other machines can reach the hub.
+# Non-loopback bind FORCES RELAY_AUTH=enforce (hub.mjs will exit otherwise).
+RELAY_HOST=100.79.242.104
+RELAY_PORT=4477
+RELAY_AUTH=enforce
+RELAY_ENROLL=invite
+
+# Persistent data directory (separate volume, survives restarts)
+RELAY_DATA_DIR=/var/lib/trantor/data
+
+# TIME-based retention — events older than this (ms) are pruned.
+# 30 days = 30 × 86400 × 1000
+RELAY_EVENT_RETENTION_MS=2592000000
+
+# Unbounded-log guard — cap total events regardless of age
+RELAY_EVENT_CAP=50000
+
+# Peer TTL: how long after last heartbeat before a peer is pruned (24h)
+RELAY_PEER_TTL_MS=86400000
+
+# Online window: a peer is "online" if last seen within this (5 min)
+RELAY_ONLINE_MS=300000
+
+# Stale-card reaper grace: card owner offline for 15 min → stale
+RELAY_REAP_GRACE_MS=900000
+
+# Postgres connection (set in /etc/trantor/env, never committed)
+# DATABASE_URL=postgresql://trantor:<password>@127.0.0.1:5432/trantor

package/deploy/restore.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# trantor — restore a backup created by backup.sh.
+# WARNING: this drops and recreates the Postgres database.
+# Usage: ./deploy/restore.sh <backup.tar.gz> [--pg-password PASSWORD]
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo "usage: $0 <backup.tar.gz> [--pg-password PASS]"
+  echo "backups available:"
+  ls -1 /var/lib/trantor/backups/ 2>/dev/null || echo "  (none)"
+  exit 1
+fi
+
+BACKUP_FILE="$1"; shift
+PG_USER="${PG_USER:-trantor}"
+PG_HOST="${PG_HOST:-127.0.0.1}"
+PG_DB="${PG_DB:-trantor}"
+DATA_DIR="${DATA_DIR:-/var/lib/trantor/data}"
+
+PG_PASSWORD=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --pg-password) PG_PASSWORD="$2"; shift 2 ;;
+    -p) PG_PASSWORD="$2"; shift 2 ;;
+    *) echo "unknown flag: $1"; exit 1 ;;
+  esac
+done
+
+if [ ! -f "$BACKUP_FILE" ]; then
+  echo "backup file not found: $BACKUP_FILE"
+  exit 1
+fi
+
+echo "=== RESTORE from $BACKUP_FILE ==="
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+tar -xzf "$BACKUP_FILE" -C "$TMP"
+
+# Ensure psql/pg_restore are available
+command -v psql >/dev/null 2>&1 || { echo "psql not found — install postgresql-client"; exit 1; }
+command -v pg_restore >/dev/null 2>&1 || { echo "pg_restore not found — install postgresql-client"; exit 1; }
+
+# Determine connection mechanism
+CONN=""
+if [ -n "$PG_PASSWORD" ]; then
+  export PGPASSWORD="$PG_PASSWORD"
+  CONN=(-U "$PG_USER" -h "$PG_HOST" -d "$PG_DB")
+else
+  CONN=(-U "$PG_USER" -h "$PG_HOST" -d "$PG_DB")
+fi
+
+if [ -f "$TMP/pg.dump" ]; then
+  echo "restoring Postgres..."
+  psql "${CONN[@]}" -c "SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = '$PG_DB' AND pid <> pg_backend_pid();" >/dev/null 2>&1 || true
+  psql "${CONN[@]}" -c "DROP DATABASE IF EXISTS $PG_DB;" postgres >/dev/null 2>&1 || true
+  psql "${CONN[@]}" -c "CREATE DATABASE $PG_DB OWNER $PG_USER;" postgres >/dev/null 2>&1 || true
+  pg_restore --no-owner --no-privileges -U "$PG_USER" -h "$PG_HOST" -d "$PG_DB" -c "$TMP/pg.dump"
+else
+  echo "(no pg.dump in backup — skipping Postgres restore)"
+fi
+
+if [ -d "$TMP/hub-data" ]; then
+  echo "restoring hub data..."
+  rm -rf "$DATA_DIR"
+  cp -r "$TMP/hub-data" "$DATA_DIR"
+fi
+
+echo "=== restore complete ==="

package/deploy/retention.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# trantor TIME-based retention — prune old events from Postgres.
+# Keeps projections (tasks, messages, peers) — invariant 5 from store-contract.
+# Run via cron: 0 3 * * * /opt/trantor/deploy/retention.sh
+set -euo pipefail
+
+RETENTION_DAYS="${RETENTION_DAYS:-90}"
+CUTOFF_MS="$(node -e "const d=Number(process.env.RETENTION_DAYS||90); process.stdout.write(String(Date.now() - d*864e5))")"
+
+docker exec trantor-pg psql -U trantor -d trantor -c "
+  DELETE FROM events WHERE ts < ${CUTOFF_MS};
+" 2>&1 | tail -1

package/deploy/setup-netcup.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# trantor — netcup Debian 13 one-shot server setup. Run as root.
+set -euo pipefail
+
+echo "=== trantor netcup setup (node $(node --version)) ==="
+
+if ! id trantor &>/dev/null; then
+  useradd -r -m -d /var/lib/trantor -s /usr/sbin/nologin trantor
+  echo "created trantor user"
+fi
+
+install -d -o trantor -g trantor -m 750 /opt/trantor
+install -d -o trantor -g trantor -m 750 /var/lib/trantor/data
+install -d -o trantor -g trantor -m 750 /var/lib/trantor/backups
+
+if [ ! -f /opt/trantor/hub.mjs ]; then
+  echo "copy repo to /opt/trantor first (e.g. rsync ./ netcup:/opt/trantor/), then re-run"
+  exit 1
+fi
+chown -R trantor:trantor /opt/trantor
+
+# secrets: generate Postgres password, write to /etc/trantor/env
+# Secrets live in /etc/trantor/pg.env — the EXACT path trantor-hub.service reads via
+# EnvironmentFile. That file is prefixed `-`, so a name mismatch fails SILENTLY: the hub would boot
+# with no DATABASE_URL and no RELAY_STORE, quietly ignoring the Postgres we just provisioned.
+# It must also carry RELAY_STORE=pg — lib/store-pg.mjs is only selected when that is set.
+if [ ! -f /etc/trantor/pg.env ]; then
+  PG_PASS="$(openssl rand -base64 32 | tr -d '/+=' | head -c 32)"
+  install -d -m 750 /etc/trantor
+  # One-time bootstrap secret for the FIRST admin. A remote hub binds non-loopback, so it must run
+  # enforce+invite — but minting an invite needs an enrolled owner, and there is none. This token is
+  # accepted ONLY while the identity store is empty; the first enrollment closes the path for good.
+  BOOT_TOK="$(openssl rand -hex 24)"
+  cat > /etc/trantor/pg.env <<EOF
+PG_PASSWORD=$PG_PASS
+RELAY_STORE=pg
+DATABASE_URL=postgresql://trantor:$PG_PASS@127.0.0.1:5432/trantor
+RELAY_BOOTSTRAP_TOKEN=$BOOT_TOK
+EOF
+  chmod 600 /etc/trantor/pg.env
+  echo "wrote /etc/trantor/pg.env (RELAY_STORE=pg + DATABASE_URL)"
+fi
+source /etc/trantor/pg.env
+export PG_PASSWORD DATABASE_URL RELAY_STORE
+
+# install dependencies (node 20 native — no build tools needed)
+cd /opt/trantor
+npm install --omit=dev --no-audit --no-fund 2>/dev/null || true
+chown -R trantor:trantor node_modules
+
+# Dockerised Postgres
+echo "starting Postgres..."
+docker compose -f deploy/docker-compose.yml up -d
+RETRIES=30
+until docker exec trantor-pg pg_isready -U trantor -d trantor 2>/dev/null; do
+  sleep 1; ((RETRIES--))
+  if [ "$RETRIES" -le 0 ]; then echo "Postgres failed to start after 30s"; exit 1; fi
+done
+echo "Postgres ready"
+
+# apply schema (from store-contract.mjs)
+echo "applying schema..."
+SCHEMA_SQL="$(node --input-type=module --eval '
+  import { SCHEMA_SQL } from "./lib/store-contract.mjs";
+  console.log(SCHEMA_SQL);
+' 2>/dev/null || true)"
+if [ -n "$SCHEMA_SQL" ]; then
+  echo "$SCHEMA_SQL" | docker exec -i trantor-pg psql -U trantor -d trantor 2>/dev/null || true
+fi
+echo "  schema applied"
+
+# systemd unit
+cp deploy/trantor-hub.service /etc/systemd/system/trantor-hub.service
+systemctl daemon-reload
+systemctl enable --now trantor-hub
+
+# crons: daily backup + nightly retention
+chmod +x deploy/backup.sh deploy/retention.sh deploy/restore.sh
+echo "0 2 * * * root /opt/trantor/deploy/backup.sh" > /etc/cron.d/trantor
+echo "0 3 * * * root /opt/trantor/deploy/retention.sh" >> /etc/cron.d/trantor
+
+echo ""
+echo "=== done ==="
+echo "Hub:      http://100.79.242.104:4477"
+echo "Logs:     journalctl -u trantor-hub -f"
+echo "Backups:  /var/lib/trantor/backups/"
+echo "Restore:  bash /opt/trantor/deploy/restore.sh <file>"

package/deploy/trantor-hub.service

@@ -0,0 +1,50 @@
+# trantor hub — systemd service for Debian 13 (netcup).
+# Install: sudo cp deploy/trantor-hub.service /etc/systemd/system/ && sudo systemctl daemon-reload
+
+[Unit]
+Description=trantor relay hub (agent bus + dashboard)
+After=network-online.target docker.service
+Wants=network-online.target
+Requires=docker.service
+
+[Service]
+Type=simple
+User=trantor
+Group=trantor
+WorkingDirectory=/opt/trantor
+ExecStart=/usr/bin/node /opt/trantor/hub.mjs
+Restart=always
+RestartSec=10
+
+# Bind tailnet IP 100.79.242.104 (non-loopback).
+# hub.mjs L39-42 REFUSES non-loopback unless RELAY_AUTH=enforce.
+Environment=RELAY_HOST=100.79.242.104
+Environment=RELAY_PORT=4477
+Environment=RELAY_AUTH=enforce
+Environment=RELAY_ENROLL=invite
+
+# Data directory — persistent, outside the repo.
+Environment=RELAY_DATA_DIR=/var/lib/trantor/data
+
+# TIME-based retention controls (all env-overridable; defaults shown).
+Environment=RELAY_EVENT_CAP=50000
+Environment=RELAY_ONLINE_MS=300000
+Environment=RELAY_PEER_TTL_MS=21600000
+Environment=RELAY_REAP_GRACE_MS=900000
+
+# Postgres connection (pg-store lands via #3931).
+EnvironmentFile=-/etc/trantor/pg.env
+
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=trantor-hub
+
+# Security hardening
+NoNewPrivileges=yes
+ProtectSystem=strict
+ProtectHome=yes
+ReadWritePaths=/var/lib/trantor /tmp
+ReadOnlyPaths=/opt/trantor
+
+[Install]
+WantedBy=multi-user.target

package/hooks/agent-notify.mjs

@@ -12,21 +12,14 @@
 // (session_id + notification_type + message are the confirmed fields). We read several candidates and let the
 // hub key/guard on whatever we send; TRANTOR_DEBUG_NOTIFY=1 dumps the raw payload to stderr so the first real
 // firing reveals the true shape. Fail-silent: a notification must never block the session.
-import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
 import { resolveProject, hostId } from "../lib/project.mjs";
+import { signedPost } from "./lib/api.mjs";
 
 function readStdin() {
   return new Promise(res => { let d = ""; process.stdin.setEncoding("utf8");
     process.stdin.on("data", c => (d += c)); process.stdin.on("end", () => res(d));
     setTimeout(() => res(d), 100); });
 }
-function relayUrl() {
-  if (process.env.RELAY_URL) return process.env.RELAY_URL;
-  try { const c = join(homedir(), ".agent-bus", "config.json"); if (existsSync(c)) { const u = JSON.parse(readFileSync(c, "utf8")).url; if (u) return u; } } catch {}
-  return "http://127.0.0.1:4477";
-}
 
 try {
   const input = JSON.parse((await readStdin()) || "{}");
@@ -48,15 +41,11 @@ try {
   const msg = String(input.message || "").replace(/\s+/g, " ").trim().slice(0, 90);
   const title = `${agentType}${msg ? `: ${msg}` : ""}`.slice(0, 180);
 
-  await fetch(`${relayUrl()}/task`, {
-    method: "POST", headers: { "content-type": "application/json" },
-    body: JSON.stringify({
+  await signedPost("/task", {
       project, source: "cc-bg-agent", notificationType: ntype,
       title, agentId, agentType, parent,
       assignee: `${agentType}:${project}`, by: `${hostId()}:${project}`, phase: "sub-agents",
-    }),
-    signal: AbortSignal.timeout(1500),
-  }).catch(() => {});
+    });
 } catch (e) {
   process.stderr.write(`[trantor] agent-notify error: ${e?.message || e}\n`);
 }

package/hooks/file-claim.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// trantor PreToolUse file-claim — shared-resource awareness across sessions.
+//
+// THE problem this solves: two orchestrators (or an orchestrator and a crew seat) touching the
+// same project learn about each other's edits at git time — merge conflicts, clobbered work,
+// "Edit succeeded but didn't persist". The bus already carries messages; this makes it carry
+// INTENT: before every file edit, the session posts a claim, and the hub answers with any LIVE
+// claim on the same file by a DIFFERENT session. That answer is handed to the acting session's
+// own model as context — through its own harness, the only safe channel (see stop-inbox.mjs for
+// why reaching across process boundaries is forbidden).
+//
+// Deliberately INFORMATIONAL, never blocking: a warning in context lets the model decide to
+// coordinate (relay_send) or proceed; a denied edit would make the hook a lock server, and a
+// lock server that fails open (as hooks must) is worse than no lock at all.
+//
+// Fail-open + cheap by contract: tight timeout, per-(session,file) stamp throttles re-claims of
+// the same file to once per window — but the FIRST touch of each file always goes out, and that
+// is exactly the moment a collision warning matters.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, relative, isAbsolute } from "node:path";
+import { homedir } from "node:os";
+import { relayUrl, sessionContext, signedPost } from "./lib/api.mjs";
+
+const FETCH_TIMEOUT_MS = Number(process.env.RELAY_CLAIM_TIMEOUT_MS || 900);
+const RECLAIM_MS = Number(process.env.RELAY_RECLAIM_MS || 60 * 1000);
+
+const allow = () => { process.stdout.write("{}"); process.exit(0); };
+
+function readStdin() {
+  return new Promise(res => {
+    let d = ""; process.stdin.setEncoding("utf8");
+    process.stdin.on("data", c => { d += c; });
+    process.stdin.on("end", () => res(d));
+    setTimeout(() => res(d), 400);
+  });
+}
+
+function fileOf(toolName, input) {
+  if (!input || typeof input !== "object") return "";
+  if (toolName === "NotebookEdit") return String(input.notebook_path || "");
+  return String(input.file_path || "");
+}
+
+const ago = s => (s < 60 ? `${s}s` : s < 3600 ? `${Math.round(s / 60)}m` : `${Math.round(s / 3600)}h`);
+
+try {
+  const raw = await readStdin();
+  const input = JSON.parse(raw || "{}");
+  const abs = fileOf(String(input.tool_name || ""), input.tool_input);
+  if (!abs) allow();
+
+  const ctx = sessionContext(input.cwd);
+  if (!ctx.project) allow();
+  // claims compare by path, and absolute paths differ per machine — store repo-relative
+  const file = isAbsolute(abs) && !relative(ctx.projectDir, abs).startsWith("..")
+    ? relative(ctx.projectDir, abs)
+    : abs;
+
+  // throttle re-claims of the same file; never throttle its first touch
+  const stampDir = join(process.env.AGENT_BUS_DIR || join(homedir(), ".agent-bus"), "claims");
+  const stamp = join(stampDir, `${ctx.session} ${file}`.replace(/[^A-Za-z0-9_.-]/g, "_"));
+  try {
+    const last = Number(readFileSync(stamp, "utf8"));
+    if (Date.now() - last < RECLAIM_MS) allow();
+  } catch {}
+
+  const r = await signedPost(`${relayUrl(ctx.project)}/claim`,
+    { project: ctx.project, file, session: ctx.session },
+    { timeoutMs: FETCH_TIMEOUT_MS, session: ctx.session });
+
+  try { mkdirSync(stampDir, { recursive: true }); writeFileSync(stamp, String(Date.now())); } catch {}
+
+  const conflicts = r.ok ? r.json?.conflicts ?? [] : [];
+  if (!conflicts.length) allow();
+
+  const who = conflicts.map(c => `${c.session} (${ago(c.agoSec)} ago)`).join(", ");
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "allow",
+      additionalContext:
+        `⚠️ trantor: ${who} also edited ${file} in project "${ctx.project}" within the last few minutes — ` +
+        `you are both touching the same file RIGHT NOW. Before making conflicting changes, coordinate over ` +
+        `the bus: relay_send to ${conflicts[0].session} saying what you're changing, or split the work. ` +
+        `Proceed only if your edits cannot collide.`,
+    },
+  }));
+  process.exit(0);
+} catch {
+  allow();
+}

package/hooks/heartbeat.mjs

@@ -13,7 +13,7 @@
 // per HEARTBEAT_MS, and a short fetch timeout means we never add real latency to a tool call.
 // We POST /register WITHOUT a status field so the session's meaningful status is preserved
 // (the hub only overwrites status when one is supplied).
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, statSync, openSync, readSync, closeSync } from "node:fs";
 import { join, basename, dirname } from "node:path";
 import { homedir, hostname } from "node:os";
 import { spawn } from "node:child_process";
@@ -21,12 +21,33 @@ import { fileURLToPath } from "node:url";
 import { readConfig, contextUsage, warnFrac, alreadyHandedOff, markHandedOff, controllingTty, terminalWindowForTty, subagentsActive } from "./lib/handoff.mjs";
 import { resolveProject, hostId } from "../lib/project.mjs";
 import { installedVersion } from "./lib/update-check.mjs";   // report our hook version so the hub can flag stale sessions
+import { signedPost } from "./lib/api.mjs";
 
 const HEARTBEAT_MS = Number(process.env.RELAY_HEARTBEAT_MS || 60 * 1000);
 const FETCH_TIMEOUT_MS = Number(process.env.RELAY_HEARTBEAT_TIMEOUT_MS || 1500);
 const INFLIGHT_MS = 5 * 60 * 1000;
 const HERE = dirname(fileURLToPath(import.meta.url));
 
+// The model this session is ACTUALLY running, read from the transcript tail — the harness does not
+// hand hooks a model field, but every assistant entry records one. Tail-read only (transcripts grow
+// to MBs); any failure returns "" and the peer simply keeps its last known model.
+function modelFromTranscript(stdinRaw) {
+  try {
+    const tp = JSON.parse(stdinRaw || "{}").transcript_path;
+    if (!tp || !existsSync(tp)) return "";
+    const size = statSync(tp).size, want = Math.min(size, 65536);
+    const f = openSync(tp, "r");
+    try {
+      const buf = Buffer.alloc(want);
+      readSync(f, buf, 0, want, size - want);
+      const m = [...buf.toString("utf8").matchAll(/"model"\s*:\s*"([^"]+)"/g)]
+        .map(x => x[1]).filter(v => v.startsWith("claude"));
+      return m.length ? m[m.length - 1] : "";
+    } finally { closeSync(f); }
+  } catch { return ""; }
+}
+
+
 function readStdin() {
   return new Promise(res => { let d = ""; process.stdin.setEncoding("utf8");
     process.stdin.on("data", c => (d += c)); process.stdin.on("end", () => res(d));
@@ -84,15 +105,6 @@ async function maybeEarlyWarn(stdinRaw, session) {
   } catch {}
 }
 
-function relayUrl() {
-  if (process.env.RELAY_URL) return process.env.RELAY_URL;
-  try {
-    const cfg = join(homedir(), ".agent-bus", "config.json");
-    if (existsSync(cfg)) { const u = JSON.parse(readFileSync(cfg, "utf8")).url; if (u) return u; }
-  } catch {}
-  return "http://127.0.0.1:4477";
-}
-
 async function main(stdinRaw) {
   const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   // Mirror sessionstart.mjs: home-directory sessions aren't project work — don't register
@@ -118,13 +130,21 @@ async function main(stdinRaw) {
   try { writeFileSync(stamp, String(Date.now())); } catch {}
 
   // POST /register with no status -> hub refreshes lastSeen + project, preserves status.
+  await signedPost("/register", { session, project, llm: "claude", model: modelFromTranscript(stdinRaw),
+    hookVersion: (() => { try { return installedVersion(); } catch { return ""; } })() }, { session, timeoutMs: Number(process.env.RELAY_HEARTBEAT_TIMEOUT_MS || 1500) });
+
+  // Ambient narratives: once an hour (machine-wide stamp), spawn the summarizer detached — the
+  // board's machine-titled cards gain a plain-language "assigned — did" line without anyone asking.
   try {
-    await fetch(`${relayUrl()}/register`, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ session, project, hookVersion: (() => { try { return installedVersion(); } catch { return ""; } })() }),
-      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-    });
+    const sumStamp = join(homedir(), ".agent-bus", "summarize.stamp");
+    const last = existsSync(sumStamp) ? Number(readFileSync(sumStamp, "utf8")) || 0 : 0;
+    if (Date.now() - last > 60 * 60 * 1000) {
+      writeFileSync(sumStamp, String(Date.now()));
+      const worker = spawn(process.execPath, [join(HERE, "..", "bin", "summarize.mjs"), "--quiet"], {
+        detached: true, stdio: "ignore",
+      });
+      worker.unref();
+    }
   } catch {}
 
   // Same cadence as the presence ping: check context pressure and hand off early