@dmsdc-ai/aigentry-telepty 0.5.9 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,65 @@ All notable changes to `@dmsdc-ai/aigentry-telepty` are documented here.
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-06-09
+
+### Added — inject audit log + verified sender identity (#43, P1–P3)
+
+- **Append-only inject audit log** (`src/audit/inject-log.js`): every delivery is
+  recorded to `~/.telepty/logs/injects.jsonl` (schema v1, one line per delivery —
+  one line per target for multicast/broadcast), file `0600` / dir `0700`. Default
+  is **hash-only** (`payload_sha256` always; no payload content on disk) — opt into
+  a truncated preview with `TELEPTY_AUDIT_PREVIEW=1`. Bounded async writer with
+  size+age rotation (`TELEPTY_AUDIT_*` env, default 30 days / 50 MB × 5); never
+  blocks the delivery hot path.
+- **Verified sender identity**: a per-session token is minted at
+  `/api/sessions/register` and carried in the parent-hijack-protected env beside
+  `TELEPTY_SESSION_ID`; the daemon maps it to a `verified_sender_sid` and flags
+  `spoof_suspected` when the caller-supplied `--from` disagrees with the verified
+  identity. Both `claimed_from` and `verified_sender_sid` are logged.
+- **Read API + CLI**: token-gated `GET /api/injects` (filter by `since`/`until`/
+  `to`/`from`/`spoof`, with cursor pagination) and a `telepty injects
+  [--tail --since --to --from --spoof --json]` subcommand for incident response.
+- The delivery provenance wrapper (P4) and broker/#45 audit seams (P5) are tracked
+  separately in #47 (deferred).
+
+### Security — operator-only fan-out (#45)
+
+- **`broadcast` / `multicast` now go through the peer-lane guardrail.** Previously
+  these handlers called delivery directly, bypassing `classifyPeerLaneInject` — a
+  fan-out escape past the peer-inject policy. **Behavior change:** fan-out
+  (`broadcast`/`multicast`) is now **operator/orchestrator-only**; a peer-lane
+  sender is rejected with `403 PEER_INJECT_BLOCKED` reaching **zero** sessions
+  (gate is by lane, not envelope). Per-target `peer_inject_blocked` bus events and
+  a `TELEPTY_FANOUT_MAX_TARGETS` (default 100) blast-radius cap were added.
+
+### Fixed
+
+- **Daemon restart never stopped the running daemon on macOS/Linux (#44).** The
+  daemon's `process.title = 'telepty-daemon'` defeated the `isLikelyTeleptyDaemon`
+  command-line heuristic, so the restart path could not find the old daemon to
+  stop. Recognize the title token (additive; the `aigentry-telepty` path is
+  preserved) and name the surviving state-file PID / port-3848 owner in the restart
+  failure message. Windows (`Win32_Process.CommandLine`) is unaffected.
+- **`[Windows] resolveWindowsExecutable` picked the extensionless npm shim (#46).**
+  The bare-name `PATH × PATHEXT` walk tried `''` first and matched npm's
+  extensionless `/bin/sh` shim before `.CMD`, crashing `CreateProcessW` with
+  `ERROR_BAD_EXE_FORMAT (193)`. The bare-name walk now tries real `PATHEXT`
+  extensions first (`''` last); the absolute/relative-path case is unchanged.
+- **Spurious daemon restart on a transient health-probe timeout (#567)** — ships
+  the previously-unreleased fix (meta-primary decision + bounded retry; restart
+  only on a real version/capability mismatch).
+- **`--submit` PTY 0x0D Enter intermittently not consumed (#568)** — ships the
+  previously-unreleased fix (render-gate input-ready before each CR +
+  state-transition-primary confirm + adaptive retry; telepty-PTY only).
+
+### Experimental (opt-in, default-OFF, not GA)
+
+- **Cross-machine relay/broker (hub) mode (#42)** is included in the package but is
+  **disabled by default** and opt-in only (enable via `AIGENTRY_BROKER_*` env). It
+  is not yet generally available or supported for general use; the code is dormant
+  unless explicitly enabled. GA gating remains pending a real-topology validation.
+
 ## [0.5.9] - 2026-06-08
 
 ### Fixed — managed service install never started the daemon (#41)

package/cli.js

@@ -11,7 +11,7 @@ const prompts = require('prompts');
 const updateNotifier = require('update-notifier');
 const pkg = require('./package.json');
 const { getConfig } = require('./auth');
-const { cleanupDaemonProcesses } = require('./daemon-control');
+const { cleanupDaemonProcesses, readDaemonState, findPortOwnerPid } = require('./daemon-control');
 const { attachInteractiveTerminal, getTerminalSize, restoreTerminalModes } = require('./interactive-terminal');
 const { getRuntimeInfo } = require('./runtime-info');
 const { formatHostLabel, groupSessionsByHost, pickSessionTarget } = require('./session-routing');
@@ -161,9 +161,106 @@ function getAuthToken() {
 
 const fetchWithAuth = (url, options = {}) => {
   const headers = { ...options.headers, 'x-telepty-token': getAuthToken() };
+  // #43 P2 — present the per-session verified-sender token (minted at register, carried in the
+  // parent-hijack-protected env beside TELEPTY_SESSION_ID) so the daemon can map token→sid and
+  // record verified_sender_sid. Header only, never the body. Absent for operator/human shells.
+  const sessionToken = process.env.TELEPTY_SESSION_TOKEN;
+  if (sessionToken) headers['x-telepty-session-token'] = sessionToken;
   return fetch(url, { ...options, headers });
 };
 
+function normalizeBrokerUrl(url) {
+  const value = String(url || '').trim();
+  if (!value) return '';
+  try {
+    return new URL(value).toString().replace(/\/+$/, '');
+  } catch {
+    return '';
+  }
+}
+
+function readBrokerEnrollSecret(value) {
+  const spec = String(value || '');
+  if (!spec) throw new Error('--enroll-secret is required');
+  if (spec.startsWith('env:')) {
+    const name = spec.slice(4);
+    const secret = process.env[name];
+    if (!secret) throw new Error(`Environment variable ${name} is empty or unset`);
+    return secret;
+  }
+  if (spec.startsWith('@')) {
+    return fs.readFileSync(spec.slice(1), 'utf8').trim();
+  }
+  return spec;
+}
+
+function readJsonFile(filePath, fallback) {
+  try {
+    if (!fs.existsSync(filePath)) return fallback;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJsonFile(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(filePath, 0o600); } catch {}
+}
+
+function brokerAclPath() {
+  return process.env.TELEPTY_BROKER_ACL || path.join(os.homedir(), '.telepty', 'broker-acl.json');
+}
+
+function brokerRevokedPath() {
+  return process.env.TELEPTY_BROKER_REVOKED || path.join(os.homedir(), '.telepty', 'broker-revoked.json');
+}
+
+function brokerAllow(fromNode, toNodes) {
+  const acl = readJsonFile(brokerAclPath(), {});
+  const existing = Array.isArray(acl[fromNode]) ? acl[fromNode] : [];
+  acl[fromNode] = Array.from(new Set([...existing, ...toNodes]));
+  writeJsonFile(brokerAclPath(), acl);
+  return acl[fromNode];
+}
+
+function brokerDeny(node) {
+  const acl = readJsonFile(brokerAclPath(), {});
+  delete acl[node];
+  writeJsonFile(brokerAclPath(), acl);
+}
+
+function brokerRevoke(node) {
+  const revoked = readJsonFile(brokerRevokedPath(), []);
+  const list = Array.isArray(revoked) ? revoked : [];
+  if (!list.includes(node)) list.push(node);
+  writeJsonFile(brokerRevokedPath(), list);
+  return list;
+}
+
+async function enrollBrokerNode(url, node, enrollSecret, pin) {
+  const brokerUrl = normalizeBrokerUrl(url);
+  if (!brokerUrl) throw new Error('connect-broker requires a valid broker URL');
+  const res = await fetch(`${brokerUrl}/broker/enroll`, {
+    method: 'POST',
+    signal: AbortSignal.timeout(10000),
+    headers: {
+      'Content-Type': 'application/json',
+      'x-telepty-enroll': enrollSecret
+    },
+    body: JSON.stringify({ node, pin_ack: pin || null })
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(data.error || data.code || `Broker enroll failed with HTTP ${res.status}`);
+  }
+  if (!data || typeof data.jwt !== 'string' || !data.jwt) {
+    throw new Error('Broker enroll response did not include a node JWT');
+  }
+  return { ...data, url: brokerUrl };
+}
+
 function isSubmitForceDefaultEnabled(env = process.env) {
   const value = (env.TELEPTY_SUBMIT_FORCE_DEFAULT || '').trim().toLowerCase();
   return value === '1' || value === 'true' || value === 'yes' || value === 'on';
@@ -377,7 +474,18 @@ async function restartDaemonGraceful(options = {}) {
     }
   }
 
-  console.error(`\x1b[31m❌ Daemon restart failed after ${maxAttempts} attempts. Run "telepty daemon" manually to start.\x1b[0m`);
+  // telepty#44: name the surviving daemon (state-file pid and/or current port owner) so
+  // manual recovery is obvious — `kill <pid>` then `telepty daemon`. Best-effort only.
+  let survivor = '';
+  try {
+    const statePid = (readDaemonState() || {}).pid;
+    const portOwner = findPortOwnerPid(3848);
+    const parts = [];
+    if (Number.isInteger(statePid) && statePid > 0) parts.push(`state-file pid ${statePid}`);
+    if (Number.isInteger(portOwner) && portOwner > 0 && portOwner !== statePid) parts.push(`port 3848 owner pid ${portOwner}`);
+    if (parts.length) survivor = ` Old daemon still alive (${parts.join(', ')}) — run "kill ${portOwner || statePid}" then "telepty daemon".`;
+  } catch {}
+  console.error(`\x1b[31m❌ Daemon restart failed after ${maxAttempts} attempts. Run "telepty daemon" manually to start.${survivor}\x1b[0m`);
   return { success: false, meta: null, attempt: maxAttempts };
 }
 
@@ -517,6 +625,15 @@ async function discoverSessions(options = {}) {
     // HTTP peer discovery is best-effort.
   }
 
+  // Remote peer sessions via broker relay. Default-OFF: without a
+  // transport='broker' peer in peers.json, this performs no broker call.
+  try {
+    const brokerSessions = await crossMachine.discoverBrokerRemoteSessions();
+    allSessions.push(...brokerSessions);
+  } catch {
+    // Broker peer discovery is best-effort.
+  }
+
   return allSessions;
 }
 
@@ -550,41 +667,99 @@ async function resolveSessionTarget(sessionRef, options = {}) {
   return target;
 }
 
+// #567: pure restart-decision policy. Separates a "slow-but-healthy" daemon from a
+// "genuinely-wrong/dead" one so a transient health-probe timeout under concurrent-
+// spawn load never kills a correct daemon. Exposed for unit-testing (no I/O).
+//
+//   meta                 - daemon /api/meta object ({version, capabilities}) or null
+//   requiredCapabilities - capabilities this spawn needs
+//   cliVersion           - local CLI version (pkg.version)
+//   sessionsReachable    - whether /api/sessions answered; ONLY consulted when meta
+//                          is null, to tell an older daemon that lacks /api/meta apart
+//                          from no daemon at all
+function decideDaemonAction({ meta, requiredCapabilities = [], cliVersion, sessionsReachable = false } = {}) {
+  if (meta && meta.version) {
+    // PRIMARY, definitive signal. A daemon reporting a matching version AND all
+    // required capabilities is healthy+correct → never restart, even if a follow-up
+    // probe (e.g. /api/sessions) is slow or times out (#567 core fix). Version policy
+    // is delegated to decideVersionAction so newer-wins semantics stay unchanged.
+    const decision = decideVersionAction({ daemonVersion: meta.version, cliVersion });
+    if (decision.action === 'restart') {
+      return { action: 'restart', reason: `version-${decision.reason}` };
+    }
+    const missingCap = requiredCapabilities.find((cap) => !(meta.capabilities || []).includes(cap));
+    if (missingCap) {
+      return { action: 'restart', reason: `capability-missing:${missingCap}` };
+    }
+    return { action: 'noop', reason: 'healthy' };
+  }
+
+  // No meta after probing. An older daemon (answers /api/sessions, lacks /api/meta)
+  // gets a legit restart; a genuinely absent/unreachable daemon gets auto-started.
+  if (sessionsReachable) {
+    return { action: 'restart', reason: 'legacy-daemon-no-meta' };
+  }
+  return { action: 'start', reason: 'daemon-unreachable' };
+}
+
 async function ensureDaemonRunning(options = {}) {
   if (REMOTE_HOST !== '127.0.0.1') return; // Only auto-start local daemon
 
   const requiredCapabilities = options.requiredCapabilities || [];
+  // Injectable seams (default to the real implementations) so the restart decision
+  // is unit-testable without touching a real daemon or making a real network call (#567).
+  const getMeta = options._getDaemonMeta || getDaemonMeta;
+  const fetchAuth = options._fetchWithAuth || fetchWithAuth;
+  const doRestart = options._restartDaemonGraceful || restartDaemonGraceful;
+  const probe = options._probe || {};
+  const attempts = probe.attempts || 3;
+  const backoffMs = probe.backoffMs == null ? 200 : probe.backoffMs;
+
+  // (1) PRIMARY signal: the daemon version/capability meta, with bounded retries to
+  // ride out a transient timeout under concurrent-spawn load before concluding (#567).
+  // getDaemonMeta already swallows timeouts/refusals and returns null, so a null here
+  // means "not (yet) confirmed healthy", not "definitely dead".
+  let meta = null;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    meta = await getMeta('127.0.0.1');
+    if (meta && meta.version) break;
+    if (attempt < attempts) {
+      await new Promise((resolve) => setTimeout(resolve, backoffMs * attempt));
+    }
+  }
+
+  // (2) Only when meta never came back do we consult /api/sessions — purely to tell an
+  // older daemon (answers sessions, lacks /api/meta) apart from no daemon at all. A slow
+  // sessions probe on an otherwise-confirmed daemon is irrelevant and never reached here.
+  let sessionsReachable = false;
+  if (!(meta && meta.version)) {
+    try {
+      const sessionsRes = await fetchAuth(`${DAEMON_URL}/api/sessions`, {
+        signal: AbortSignal.timeout(5000)
+      });
+      sessionsReachable = !!(sessionsRes && sessionsRes.ok);
+    } catch {
+      sessionsReachable = false; // timeout/refused while probing the legacy fallback
+    }
+  }
 
-  try {
-    const meta = await getDaemonMeta('127.0.0.1');
-    const hasCapabilities = meta && requiredCapabilities.every((item) => meta.capabilities.includes(item));
-
-    const sessionsRes = await fetchWithAuth(`${DAEMON_URL}/api/sessions`, {
-      signal: AbortSignal.timeout(1500)
-    });
+  const decision = decideDaemonAction({ meta, requiredCapabilities, cliVersion: pkg.version, sessionsReachable });
 
-    if (sessionsRes.ok && hasCapabilities) {
-      // Delegate decision to pure-functional handshake so the policy is unit-testable
-      // and consistent across CLI invocations.
-      const decision = decideVersionAction({ daemonVersion: meta && meta.version, cliVersion: pkg.version });
-      if (decision.action === 'restart') {
-        // stderr (not stdout): banner must not contaminate `telepty list --json` (task #400, telepty#15)
-        process.stderr.write(`\x1b[33m⚙️ Daemon version mismatch (running v${meta.version}, installed v${pkg.version}). Restarting...\x1b[0m\n`);
-        await restartDaemonGraceful({ requiredCapabilities });
-        return;
-      }
-      return;
-    } else if (sessionsRes.ok && !meta) {
-      process.stderr.write('\x1b[33m⚙️ Found an older local telepty daemon. Restarting it...\x1b[0m\n');
-    } else if (sessionsRes.ok && meta) {
-      process.stderr.write('\x1b[33m⚙️ Found a local telepty daemon without the required features. Restarting it...\x1b[0m\n');
-    }
-  } catch (e) {
-    // Continue to auto-start below.
+  if (decision.action === 'noop') {
+    return; // healthy + correct version + all capabilities → leave the daemon alone (#567)
   }
 
-  process.stderr.write('\x1b[33m⚙️ Auto-starting local telepty daemon...\x1b[0m\n');
-  await restartDaemonGraceful({ requiredCapabilities });
+  // stderr (not stdout): banner must not contaminate `telepty list --json` (task #400, telepty#15)
+  if (decision.action === 'restart' && decision.reason.startsWith('version-')) {
+    process.stderr.write(`\x1b[33m⚙️ Daemon version mismatch (running v${meta.version}, installed v${pkg.version}). Restarting...\x1b[0m\n`);
+  } else if (decision.reason === 'legacy-daemon-no-meta') {
+    process.stderr.write('\x1b[33m⚙️ Found an older local telepty daemon. Restarting it...\x1b[0m\n');
+  } else if (decision.action === 'restart') {
+    process.stderr.write('\x1b[33m⚙️ Found a local telepty daemon without the required features. Restarting it...\x1b[0m\n');
+  } else {
+    process.stderr.write('\x1b[33m⚙️ Auto-starting local telepty daemon...\x1b[0m\n');
+  }
+  await doRestart({ requiredCapabilities });
 }
 
 async function manageInteractiveAttach(sessionId, targetHost) {
@@ -892,6 +1067,57 @@ async function main() {
     return;
   }
 
+  if (cmd === 'broker') {
+    const subcmd = args[1];
+    if (subcmd === 'allow') {
+      const fromNode = args[2];
+      const toFlag = args.indexOf('--to');
+      const toNodes = toFlag !== -1 && args[toFlag + 1]
+        ? args[toFlag + 1].split(',').map((item) => item.trim()).filter(Boolean)
+        : [];
+      if (!fromNode || toNodes.length === 0) {
+        console.error('❌ Usage: telepty broker allow <fromNode> --to <nodeA,nodeB>');
+        process.exit(1);
+      }
+      const allowed = brokerAllow(fromNode, toNodes);
+      console.log(`\x1b[32m✅ Broker ACL: ${fromNode} may inject ${allowed.join(', ')}\x1b[0m`);
+      return;
+    }
+
+    if (subcmd === 'deny') {
+      const node = args[2];
+      if (!node) {
+        console.error('❌ Usage: telepty broker deny <node>');
+        process.exit(1);
+      }
+      brokerDeny(node);
+      console.log(`\x1b[32m✅ Broker ACL: ${node} denied\x1b[0m`);
+      return;
+    }
+
+    if (subcmd === 'revoke') {
+      const node = args[2];
+      if (!node) {
+        console.error('❌ Usage: telepty broker revoke <node>');
+        process.exit(1);
+      }
+      brokerRevoke(node);
+      console.log(`\x1b[32m✅ Broker revocation: ${node} revoked\x1b[0m`);
+      return;
+    }
+
+    if (subcmd) {
+      console.error('❌ Usage: telepty broker [allow <fromNode> --to <nodeA,nodeB> | deny <node> | revoke <node>]');
+      process.exit(1);
+    }
+
+    console.log('Starting telepty broker...');
+    process.env.TELEPTY_BROKER_MODE = '1';
+    process.env.AIGENTRY_TELEPTY_DAEMON_MAIN = '1';
+    require('./daemon.js');
+    return;
+  }
+
   if (cmd === 'tui' || cmd === 'dashboard') {
     const { TuiDashboard } = require('./tui');
     new TuiDashboard();
@@ -944,6 +1170,90 @@ async function main() {
     return;
   }
 
+  if (cmd === 'injects') {
+    // #43 P3 — query the inject audit log (GET /api/injects). Filters: --to/--from/--since/--spoof;
+    // --json for piping; --tail follows live (poll). Mirrors the list/status command blocks.
+    function flagValue(name) {
+      const i = args.indexOf(name);
+      return i !== -1 && args[i + 1] ? args[i + 1] : null;
+    }
+    const asJson = args.includes('--json');
+    const tail = args.includes('--tail');
+    const toFilter = flagValue('--to');
+    const fromFilter = flagValue('--from');
+    const spoofOnly = args.includes('--spoof');
+    const limit = flagValue('--limit');
+    let since = flagValue('--since');
+    // --since accepts a relative duration ("1h", "30m") or an ISO/epoch value. Convert a
+    // duration to an absolute ISO timestamp using the same parser as --idle-ttl (reuse).
+    if (since) {
+      try {
+        const ms = lifecycle.parseDuration(since, { fieldName: 'since' });
+        if (Number.isFinite(ms) && ms > 0) since = new Date(Date.now() - ms).toISOString();
+      } catch { /* not a duration — pass through as ISO/epoch */ }
+    }
+
+    function buildQuery(cursor) {
+      const p = new URLSearchParams();
+      if (since) p.set('since', since);
+      if (toFilter) p.set('to', toFilter);
+      if (fromFilter) p.set('from', fromFilter);
+      if (spoofOnly) p.set('spoof', '1');
+      if (limit) p.set('limit', limit);
+      if (cursor != null) p.set('cursor', String(cursor));
+      const qs = p.toString();
+      return `${DAEMON_URL}/api/injects${qs ? `?${qs}` : ''}`;
+    }
+
+    function formatRow(l) {
+      const spoofTag = l.spoof_suspected ? ' \x1b[31m⚠ SPOOF\x1b[0m' : '';
+      const verified = l.verified_sender_sid || '\x1b[90mnull\x1b[0m';
+      return `  ${l.ts}  \x1b[36m${l.claimed_from || '-'}\x1b[0m→${l.to}  verified=${verified}  ${l.kind}/${l.delivery_result}${spoofTag}`;
+    }
+
+    try {
+      if (tail) {
+        // Poll newest lines and print rows as they appear (dedup by inject_id+to).
+        const seen = new Set();
+        let firstPass = true;
+        console.log('\x1b[1mTailing inject audit log (Ctrl-C to stop)...\x1b[0m');
+        for (;;) {
+          const res = await fetchWithAuth(buildQuery());
+          if (res.ok) {
+            const data = await res.json();
+            const fresh = (data.injects || []).slice().reverse(); // oldest→newest for display
+            for (const l of fresh) {
+              const key = `${l.inject_id}|${l.to}`;
+              if (seen.has(key)) continue;
+              seen.add(key);
+              if (!firstPass) console.log(asJson ? JSON.stringify(l) : formatRow(l));
+            }
+            if (firstPass) {
+              // Print the initial window once, then stream only newer lines.
+              for (const l of fresh) console.log(asJson ? JSON.stringify(l) : formatRow(l));
+              firstPass = false;
+            }
+          }
+          await new Promise((r) => setTimeout(r, 1000));
+        }
+      }
+
+      const res = await fetchWithAuth(buildQuery());
+      const data = await res.json();
+      if (!res.ok) { console.error(`❌ ${formatApiError(data)}`); process.exit(1); }
+      if (asJson) { console.log(JSON.stringify(data, null, 2)); return; }
+      const injects = data.injects || [];
+      if (injects.length === 0) { console.log('No inject audit records found.'); return; }
+      console.log('\x1b[1mInject audit log (newest first):\x1b[0m');
+      injects.forEach((l) => console.log(formatRow(l)));
+      if (data.next_cursor != null) console.log(`  … more (--limit/cursor ${data.next_cursor})`);
+    } catch (e) {
+      console.error(`❌ ${e.message || 'Failed to query inject audit log.'}`);
+      process.exit(1);
+    }
+    return;
+  }
+
   if (cmd === 'spawn') {
     const idIndex = args.indexOf('--id');
     if (idIndex === -1 || !args[idIndex + 1]) { console.error('❌ Usage: telepty spawn --id <session_id> <command> [args...]'); process.exit(1); }
@@ -1032,6 +1342,10 @@ async function main() {
     delete process.env.TELEPTY_SESSION_ID;
     process.env.TELEPTY_SESSION_ID = sessionId;
     process.env.TELEPTY_AVAILABLE = 'true';
+    // #43 P2 — drop any inherited verified-sender token so a parent process cannot smuggle one
+    // in; the daemon mints the real one at register (below) and we set it into the same
+    // protected env. (Leaves room for a future per-session nonce — banner is P4, not built.)
+    delete process.env.TELEPTY_SESSION_TOKEN;
 
     await ensureDaemonRunning({ requiredCapabilities: ['wrapped-sessions'] });
 
@@ -1071,6 +1385,9 @@ async function main() {
         console.error(`❌ Error: ${data.error}`);
         process.exit(1);
       }
+      // #43 P2 — store the daemon-minted verified-sender token beside TELEPTY_SESSION_ID so the
+      // wrapped CLI (and any `telepty inject` it spawns) inherits it via sessionEnv below.
+      if (data.session_token) process.env.TELEPTY_SESSION_TOKEN = data.session_token;
     } catch (e) {
       console.error('❌ Failed to register with daemon:', e.message);
       process.exit(1);
@@ -1079,7 +1396,7 @@ async function main() {
     // Spawn local PTY (preserves isTTY, env, shell config)
     const pty = require('node-pty');
     const sessionCwd = process.cwd();
-    const sessionEnv = { ...process.env, TELEPTY_SESSION_ID: sessionId, TELEPTY_AVAILABLE: 'true' };
+    const sessionEnv = { ...process.env, TELEPTY_SESSION_ID: sessionId, TELEPTY_AVAILABLE: 'true', ...(process.env.TELEPTY_SESSION_TOKEN ? { TELEPTY_SESSION_TOKEN: process.env.TELEPTY_SESSION_TOKEN } : {}) };
     let child = null;
     let sessionStartTime = Date.now();
     let crashCount = 0;
@@ -3237,6 +3554,47 @@ Discuss the following topic from your project's perspective. Engage with other s
     return;
   }
 
+  // telepty connect-broker <url> --node <name> --enroll-secret <secret|@file|env:VAR> [--pin <sha256>]
+  // One-click broker enrollment: POST /broker/enroll with the fleet enroll
+  // secret, then persist the minted node JWT in ~/.telepty/broker.json (0600)
+  // and a non-secret transport='broker' peer in peers.json.
+  if (cmd === 'connect-broker') {
+    const target = args[1];
+    const nodeFlag = args.indexOf('--node');
+    const secretFlag = args.indexOf('--enroll-secret');
+    const pinFlag = args.indexOf('--pin');
+    const node = nodeFlag !== -1 ? args[nodeFlag + 1] : null;
+    const secretSpec = secretFlag !== -1 ? args[secretFlag + 1] : null;
+    const pin = pinFlag !== -1 ? args[pinFlag + 1] : null;
+    if (!target || !node || !secretSpec) {
+      console.error('❌ Usage: telepty connect-broker <url> --node <name> --enroll-secret <secret|@file|env:VAR> [--pin <sha256>]');
+      process.exit(1);
+    }
+
+    process.stdout.write(`\x1b[36m🔗 Enrolling ${node} with broker ${target}...\x1b[0m\n`);
+    try {
+      const enrollSecret = readBrokerEnrollSecret(secretSpec);
+      const enroll = await enrollBrokerNode(target, node, enrollSecret, pin);
+      const result = await crossMachine.connectBroker(enroll.url, {
+        node,
+        jwt: enroll.jwt,
+        pin
+      });
+      if (result.success) {
+        console.log(`\x1b[32m✅ Connected ${result.node} to broker\x1b[0m`);
+        console.log(`   Broker: ${result.url}`);
+        console.log(`\nBroker sessions are now discoverable via \x1b[36mtelepty list\x1b[0m`);
+      } else {
+        console.error(`\x1b[31m❌ ${result.error}\x1b[0m`);
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error(`\x1b[31m❌ ${err.message}\x1b[0m`);
+      process.exit(1);
+    }
+    return;
+  }
+
   // telepty disconnect [<name> | --all]
   if (cmd === 'disconnect') {
     if (args[1] === '--all') {
@@ -3394,6 +3752,8 @@ Discuss the following topic from your project's perspective. Engage with other s
 \x1b[1mCross-Machine:\x1b[0m
   telepty connect <user@host> [--name N] [--port P]      SSH tunnel to remote host
   telepty connect-http <host>[:port] [--name N] [--token T]  Register remote daemon via HTTP (no SSH)
+  telepty connect-broker <url> --node N --enroll-secret S [--pin P]  Enroll with broker relay
+  telepty broker [allow <from> --to a,b | deny <node> | revoke <node>]  Start/admin broker
   telepty disconnect <name> | --all              Disconnect remote host
   telepty peers [--remove <name>]                List connected peers
 
@@ -3447,4 +3807,6 @@ module.exports = {
   classifyBackend,        // #29: TERM_PROGRAM/CMUX/kitty → backend string
   isDaemonDestroyClose,   // #17 OQ-2: 1000 'Session destroyed' → terminate-not-reconnect
   sanitizePathArg,        // #26: path-arg validation/normalization
+  decideDaemonAction,     // #567: pure restart-decision policy (meta-primary; no I/O)
+  ensureDaemonRunning,    // #567: orchestrator (injectable probes for unit-testing)
 };