privateer-agent 0.9.2 → 0.10.0

package/src/nostr/keys.ts

@@ -0,0 +1,172 @@
+/**
+ * The agent's Nostr identity.
+ *
+ * A Nostr secret key is not a bot token. It is a PERMANENT identity: it cannot be
+ * rotated without becoming a different participant, everything it ever signed stays
+ * attributable to it, and there is no issuer to revoke it. So it gets the same
+ * treatment as the terminal identity key — minted locally, written 0600, and never
+ * sent anywhere — rather than living in plaintext config.json beside the revocable
+ * platform bot tokens.
+ *
+ * DEFAULT PATH: the agent generates its own keypair and reports the npub, which the
+ * user pastes into their Buzz workspace so an Owner can add it as a Bot member. The
+ * secret never crosses a wire, not even the sealed app→terminal channel.
+ *
+ * IMPORT PATH: a user who already has a Buzz identity can send an nsec through the
+ * app's sealed-secret flow; importBuzzKey() moves it into the 0600 file so it stops
+ * living in config.json.
+ *
+ * Construction mirrors crypto/terminalKey.ts deliberately, including the 0600
+ * TOCTOU-avoiding write and the process-lifetime cache.
+ */
+
+import { readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { schnorr } from "@noble/curves/secp256k1";
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils";
+import { globalDir } from "../config/paths.ts";
+import { npubEncode, npubDecode, nsecEncode, nsecDecode } from "./bech32.ts";
+
+interface BuzzKeyFile {
+  v: 1;
+  secretKey: string; // base64, 32 raw bytes — never leaves this machine
+}
+
+export interface BuzzIdentity {
+  secretHex: string;
+  pubkeyHex: string;
+  npub: string;
+}
+
+function keyPath(): string {
+  return join(globalDir(), "buzz-key.json");
+}
+
+let cached: BuzzIdentity | undefined;
+
+// ── pure ────────────────────────────────────────────────────────────────────────
+
+/** A fresh 32-byte secp256k1 secret key. */
+export function generateSecretKey(): Uint8Array {
+  return schnorr.utils.randomSecretKey();
+}
+
+/** The 32-byte x-only public key for a secret, as lowercase hex — a Nostr pubkey. */
+export function publicKeyHex(secret: Uint8Array | string): string {
+  return bytesToHex(schnorr.getPublicKey(typeof secret === "string" ? hexToBytes(secret) : secret));
+}
+
+/**
+ * Normalize a configured identity to lowercase hex.
+ *
+ * Allowlists are written by humans, who will paste whichever form Buzz showed them —
+ * so accept both npub and raw hex and store one canonical form. Returns undefined
+ * for anything that isn't a valid 32-byte key, so a typo'd entry fails closed
+ * (dropped from the allowlist) rather than silently matching nothing forever.
+ */
+export function toHexPubkey(npubOrHex: string): string | undefined {
+  const s = npubOrHex.trim();
+  if (/^[0-9a-fA-F]{64}$/.test(s)) return s.toLowerCase();
+  if (s.startsWith("npub1")) {
+    try {
+      return bytesToHex(npubDecode(s));
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/** Accept either an nsec or raw hex secret; throws on anything else. */
+export function secretFromNsec(nsecOrHex: string): Uint8Array {
+  const s = nsecOrHex.trim();
+  if (/^[0-9a-fA-F]{64}$/.test(s)) return hexToBytes(s.toLowerCase());
+  if (s.startsWith("nsec1")) return nsecDecode(s);
+  throw new Error("expected an nsec1… key or 64 hex characters");
+}
+
+function identityFrom(secret: Uint8Array): BuzzIdentity {
+  const pubkeyHex = publicKeyHex(secret);
+  return { secretHex: bytesToHex(secret), pubkeyHex, npub: npubEncode(hexToBytes(pubkeyHex)) };
+}
+
+// ── persisted ───────────────────────────────────────────────────────────────────
+
+function persist(secret: Uint8Array): BuzzIdentity {
+  const file: BuzzKeyFile = { v: 1, secretKey: Buffer.from(secret).toString("base64") };
+  // 0600 from creation — see terminalKey.ts for why `mode` plus a follow-up chmod.
+  writeFileSync(keyPath(), JSON.stringify(file), { mode: 0o600 });
+  try {
+    chmodSync(keyPath(), 0o600);
+  } catch {
+    /* best effort — e.g. non-POSIX FS */
+  }
+  cached = identityFrom(secret);
+  return cached;
+}
+
+/** Load the persisted identity, minting and persisting one on first use. */
+export function loadOrCreateBuzzKey(): BuzzIdentity {
+  if (cached) return cached;
+  try {
+    const parsed = JSON.parse(readFileSync(keyPath(), "utf8")) as BuzzKeyFile;
+    if (parsed?.v === 1 && parsed.secretKey) {
+      const buf = Buffer.from(parsed.secretKey, "base64");
+      if (buf.length === 32) {
+        cached = identityFrom(new Uint8Array(buf));
+        return cached;
+      }
+    }
+  } catch {
+    /* missing or malformed → mint a fresh keypair below */
+  }
+  return persist(generateSecretKey());
+}
+
+/**
+ * Adopt an existing identity, replacing any current one.
+ *
+ * Called when a user supplies an nsec through the app: the value arrives sealed,
+ * lands here, and the caller then deletes it from config.json so the only copy on
+ * disk is the 0600 file.
+ */
+export function importBuzzKey(nsecOrHex: string): BuzzIdentity {
+  return persist(secretFromNsec(nsecOrHex));
+}
+
+/**
+ * Every textual form of the persisted secret, for the outbound redactor.
+ *
+ * The agent can read its own key file — it's a file on the machine it operates —
+ * so without this it could quote its permanent identity into a public channel.
+ * Both encodings are returned because either could plausibly appear in output.
+ * Non-minting: no key file means nothing to redact.
+ */
+export function buzzRedactionSecrets(): string[] {
+  const secretHex = cached?.secretHex ?? readPersistedSecretHex();
+  if (!secretHex) return [];
+  return [secretHex, nsecEncode(hexToBytes(secretHex))];
+}
+
+function readPersistedSecretHex(): string | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(keyPath(), "utf8")) as BuzzKeyFile;
+    const buf = Buffer.from(parsed?.secretKey ?? "", "base64");
+    if (parsed?.v === 1 && buf.length === 32) return bytesToHex(new Uint8Array(buf));
+  } catch {
+    /* not configured yet */
+  }
+  return undefined;
+}
+
+/**
+ * Read the persisted npub WITHOUT minting one.
+ *
+ * Side-effect-free by design: the app lists every platform, configured or not, and
+ * merely rendering an empty Buzz card must not conjure a permanent identity.
+ */
+export function peekBuzzNpub(): string | undefined {
+  if (cached) return cached.npub;
+  const secretHex = readPersistedSecretHex();
+  return secretHex ? identityFrom(hexToBytes(secretHex)).npub : undefined;
+}

package/src/nostr/tags.ts

@@ -0,0 +1,60 @@
+// NIP-10 threading and NIP-27 mention helpers — reading meaning out of an event's
+// positional tag arrays, and building the tags for a reply.
+//
+// Pure and adapter-agnostic: the Buzz adapter uses these, but nothing here is
+// Buzz-specific.
+
+import type { Tag } from "./event.ts";
+
+/**
+ * Extract a reply's thread position from its "e" tags.
+ *
+ * Two encodings exist in the wild and both must be handled:
+ *   MARKERED (current)  ["e", <id>, <relay>, "root"] / [… "reply"]
+ *   POSITIONAL (legacy) the FIRST "e" tag is the root, the LAST is the direct
+ *                       parent; with exactly one, it is both.
+ * A markered tag anywhere wins — mixing the two is malformed, and trusting the
+ * explicit marker is the safer read.
+ */
+export function threadRefs(tags: Tag[]): { root?: string; reply?: string } {
+  const eTags = tags.filter((t) => t[0] === "e" && typeof t[1] === "string" && t[1].length > 0);
+  if (eTags.length === 0) return {};
+
+  const markered = eTags.filter((t) => t[3] === "root" || t[3] === "reply");
+  if (markered.length > 0) {
+    return {
+      root: markered.find((t) => t[3] === "root")?.[1],
+      reply: markered.find((t) => t[3] === "reply")?.[1],
+    };
+  }
+
+  // Legacy positional form.
+  if (eTags.length === 1) return { root: eTags[0][1], reply: eTags[0][1] };
+  return { root: eTags[0][1], reply: eTags[eTags.length - 1][1] };
+}
+
+/** Every pubkey this event tags — i.e. everyone it @-mentions. */
+export function pTags(tags: Tag[]): string[] {
+  return tags.filter((t) => t[0] === "p" && typeof t[1] === "string" && t[1].length > 0).map((t) => t[1]);
+}
+
+/** Blossom content hashes attached to this event (["x", <sha256>]). */
+export function xTags(tags: Tag[]): string[] {
+  return tags.filter((t) => t[0] === "x" && typeof t[1] === "string" && t[1].length > 0).map((t) => t[1]);
+}
+
+/**
+ * Build the tags for a reply.
+ *
+ * `root` is the thread root and `parent` the message being answered; when only one
+ * is known, pass it as both — a reply that marks a root but no parent reads as a
+ * top-level post to most clients. Mentioned pubkeys are deduped, since duplicate "p"
+ * tags inflate relay-side mention indexes for no benefit.
+ */
+export function replyTags(root?: string, parent?: string, mentionPubkeys: string[] = []): Tag[] {
+  const out: Tag[] = [];
+  if (root) out.push(["e", root, "", "root"]);
+  if (parent && parent !== root) out.push(["e", parent, "", "reply"]);
+  for (const pk of [...new Set(mentionPubkeys)]) out.push(["p", pk]);
+  return out;
+}

package/src/permissions/classify.ts

@@ -1,5 +1,7 @@
 import { resolve, isAbsolute, relative, dirname, join, basename } from "node:path";
 import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
 import { isProtectedPath } from "./protected.ts";
 import type { PermissionRequest } from "./gate.ts";
 
@@ -42,8 +44,57 @@ function realBase(abs: string): string {
   }
 }
 
+// ⚠️ SECURITY-CRITICAL: this MUST resolve a path string to exactly the same place
+// Pi's file tools do, or the gate judges one file and the tool touches another.
+//
+// Pi resolves every tool path through `resolveToCwd` → `resolvePath` →
+// `normalizePath` (node_modules/@earendil-works/pi-coding-agent/dist/utils/paths.js
+// and dist/core/tools/path-utils.js), which EXPANDS `~`, STRIPS a leading `@`, and
+// converts `file://` URLs. `node:path` treats all three as RELATIVE, so a classifier
+// using bare resolve() computed `<cwd>/~/.ssh/authorized_keys` — comfortably "inside"
+// the working directory — while `write` truly targeted `$HOME/.ssh/authorized_keys`.
+// That made `outside` false and `protected` false (isProtectedPath matches basenames,
+// and `authorized_keys` isn't one), so:
+//   • reads returned null from classifyToolCall — NO gate at all, in every posture
+//     including plan/readonly, at the default read-only tool ceiling; and
+//   • writes auto-allowed under acceptEdits / bypass / no-quarter.
+// The adversary here is the MODEL (prompt injection), not the user, so "the operator
+// could read that file anyway" does not apply.
+//
+// Pi does not export normalizePath (package exports are "." and "./rpc-entry" only),
+// so it is mirrored here. KEEP IN SYNC — tests/classifyPathParity.test.ts asserts this
+// function agrees with Pi's own resolver, so a Pi upgrade that changes normalization
+// fails the suite instead of silently reopening the hole.
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+function normalizeLikePi(input: string, opts: { unicodeSpaces?: boolean; stripAt?: boolean } = {}): string {
+  let s = input;
+  if (opts.unicodeSpaces) s = s.replace(UNICODE_SPACES, " ");
+  if (opts.stripAt && s.startsWith("@")) s = s.slice(1);
+  const home = homedir();
+  if (s === "~") return home;
+  if (s.startsWith("~/") || (process.platform === "win32" && s.startsWith("~\\"))) return join(home, s.slice(2));
+  if (/^file:\/\//.test(s)) {
+    // Pi lets fileURLToPath throw here, which fails the tool call. We must not throw
+    // (that would break the gate), so fall back to the raw string: it then resolves
+    // inside cwd, but the tool errors on the same input, so there is no divergence
+    // a caller can exploit.
+    try {
+      return fileURLToPath(s);
+    } catch {
+      return s;
+    }
+  }
+  return s;
+}
+
 function resolveInCwd(cwd: string, p: string): string {
-  return realBase(isAbsolute(p) ? p : resolve(cwd, p));
+  // Mirrors resolvePath(): the TARGET gets the tools' options
+  // ({normalizeUnicodeSpaces, stripAtPrefix}); the BASE gets normalizePath's defaults
+  // (tilde/file:// only), because Pi normalizes baseDir with no options.
+  const target = normalizeLikePi(p, { unicodeSpaces: true, stripAt: true });
+  const base = normalizeLikePi(cwd);
+  return realBase(isAbsolute(target) ? resolve(target) : resolve(base, target));
 }
 
 function isInsideDir(root: string, abs: string): boolean {

package/src/remote/channelsControl.ts

@@ -23,24 +23,18 @@
  */
 import { readFileSync, writeFileSync } from "node:fs";
 import { configPath } from "../config/paths.ts";
+// The platform roster, per-platform secret field names, and the "is this block
+// startable" predicate all live in ONE place, shared with the channels runtime —
+// see channels/platforms.ts. Re-exported here so existing importers of
+// CHANNEL_PLATFORMS/ChannelPlatform from this module keep working unchanged.
+import { CHANNEL_PLATFORMS, SECRET_FIELDS, isChannelPlatform, type ChannelPlatform } from "../channels/platforms.ts";
 
-// The platforms channels/run.ts knows how to start. Order is the app's display
-// order. Keep in sync with the `startChannel` calls in run.ts.
-export const CHANNEL_PLATFORMS = ["telegram", "slack", "discord", "whatsapp"] as const;
-export type ChannelPlatform = (typeof CHANNEL_PLATFORMS)[number];
+export { CHANNEL_PLATFORMS };
+export type { ChannelPlatform };
 
 const POSTURES = ["readonly", "approve", "auto"] as const;
 export type ChannelPosture = (typeof POSTURES)[number];
 
-// The secret (never-echoed) fields per platform — the union of the token blocks
-// run.ts requires to START each platform. `secretsSet` reports presence of these.
-const SECRET_FIELDS: Record<ChannelPlatform, string[]> = {
-  telegram: ["botToken"],
-  slack: ["appToken", "botToken"],
-  discord: ["botToken"],
-  whatsapp: ["phoneNumberId", "accessToken", "verifyToken", "appSecret"],
-};
-
 // Non-secret projection of one platform's config, sent to the app. No token
 // values, ever — only which secret fields are already present (`secretsSet`).
 export interface RemoteChannel {
@@ -79,9 +73,7 @@ export interface ChannelsControl {
   remove(platform: ChannelPlatform): { ok: boolean; message?: string };
 }
 
-function isPlatform(v: unknown): v is ChannelPlatform {
-  return typeof v === "string" && (CHANNEL_PLATFORMS as readonly string[]).includes(v);
-}
+const isPlatform = isChannelPlatform;
 
 function normalizePosture(v: unknown): ChannelPosture | undefined {
   return typeof v === "string" && (POSTURES as readonly string[]).includes(v) ? (v as ChannelPosture) : undefined;

package/src/remote/liveTaskSession.ts

@@ -31,6 +31,8 @@ import { RemoteBridge } from "./remoteBridge.ts";
 import { makeRelayFileTools } from "../tools/relayFileTools.ts";
 import { AttachmentStore, type StoredAttachment } from "../util/attachmentStore.ts";
 import { spawnAccountCredentials, revokeAccountSession, hasCredentials } from "../auth/privateer.ts";
+import { createUIContext } from "../ext/headlessUi.ts";
+import { noQuarterActive } from "../permissions/noQuarter.ts";
 
 export interface LiveTaskHandle {
   termId: string;
@@ -161,7 +163,11 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
       attached = true;
       if (attachTimer) { clearTimeout(attachTimer); attachTimer = undefined; }
       relay?.sendSnapshot([]);
-      relay?.sendContext({ model: modelSpec, version: agentVersion() });
+      // cwd rides along here (and nowhere else — see RelayClient.sendContext): this
+      // session's working directory was either named by the driver in the spawn form
+      // or defaulted to the harbor's own, and they have no other way to see which.
+      // Every file this agent touches is under it.
+      relay?.sendContext({ model: modelSpec, cwd, version: agentVersion() });
       relay?.sendCommands([]);
       // Deliver the spawn's initial prompt exactly once, THROUGH the bridge's own prompt
       // path so it counts as a driven turn (remote=true → tools relay to the app).
@@ -189,6 +195,13 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
     },
     getRemote: bridge.getRemote,
     getNoQuarter: bridge.getNoQuarter,
+    // Session-wide TOTAL bypass when the harbor itself was launched `--no-quarter`
+    // (env PRIVATEER_NO_QUARTER): every action auto-approves with no prompt, here as
+    // in the TUI. Without this the flag meant nothing on a spawn — the app's own
+    // no-quarter toggle (getNoQuarter above) was the only switch that reached this
+    // gate, so an operator who had lowered the moat harbor-wide still got prompted
+    // for everything. Off unless the flag is set, which launchd/systemd never does.
+    getSkipAllPermissions: noQuarterActive,
     remoteAsk: bridge.remoteAsk,
     blockedWhenRemote: isRemoteUnsafeTool,
     onRemoteBlocked: (toolName) => bridge.sendNotice(`${toolName} is disabled while driving remotely — its prompts can't reach the app.`),
@@ -248,7 +261,7 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
   // Relay the extension mid-turn UI (select/confirm/input) to the app when driven, so an
   // extension asking a question doesn't silently cancel. Mirrors cli/chat.ts's uiContext.
   const driven = (): boolean => bridge.getRemote() && bridge.isConnected();
-  const uiContext = {
+  const uiContext = createUIContext({
     async select(t: string, options: string[], opts?: { signal?: AbortSignal }): Promise<string | undefined> {
       if (!options.length) return undefined;
       if (!driven()) return undefined;
@@ -268,7 +281,7 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
     notify(message: string): void {
       if (driven()) bridge.sendNotice(message);
     },
-  };
+  });
   await (session as any).bindExtensions({ uiContext });
 
   const adapter = createEngineEventAdapter();

package/src/remote/relayClient.ts

@@ -17,6 +17,7 @@
  */
 import WebSocket from "ws";
 import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
 import { apiRequest, serverBaseUrl } from "../auth/privateer.ts";
 import type { EngineEvent } from "../engine/events.ts";
 import type { PermissionRequest } from "../permissions/gate.ts";
@@ -227,6 +228,15 @@ export interface RelayCallbacks {
 }
 
 const RECONNECT_MS = 3000;
+// Ceiling for the reconnect backoff below. A blip should be invisible (first retry at
+// RECONNECT_MS), but a relay that is genuinely down must not be hammered every 3s for
+// hours by every harbor on the fleet — and when it comes back, they must not all
+// stampede it in the same 3s window. So: grow the delay on consecutive failures, cap it
+// here, jitter it, and reset the moment a socket opens.
+const RECONNECT_MAX_MS = 30_000;
+const RECONNECT_GROWTH = 1.7;
+// Fraction of the delay to randomize (±), so restarts don't resynchronize the fleet.
+const RECONNECT_JITTER = 0.25;
 // Retry cadence after the relay REFUSES us (4xx — in practice the plan's live-agent
 // cap). Slow, because only an account change can clear it, but not never: the harbor
 // should come up on its own once a slot frees. Kept well under the server's denial
@@ -241,12 +251,27 @@ const REFUSED_RECONNECT_MS = 60_000;
 // the server prunes the terminal from its presence registry after ~60s, so the app
 // shows the harbor as offline while the harbor's own log says "connected", forever.
 //
-// So don't wait to be told. The server pings every 25s, so an alive socket sees
-// inbound traffic at least that often; we ping on our own timer too (the peer's pong
-// counts as inbound). If nothing arrives for LIVENESS_TIMEOUT_MS — three missed
-// server pings — the socket is dead: terminate it and take the normal reconnect path.
+// So don't wait to be told. The server pings every 25s, so an alive socket sees inbound
+// traffic at least that often; we ping on our own timer too and a healthy peer pongs
+// immediately, so in practice inbound arrives every ~20s. If nothing arrives for
+// LIVENESS_TIMEOUT_MS the socket is dead: terminate it and take the normal reconnect path.
+//
+// The timeout is sized against the SERVER's presence TTL, not against comfort. The server
+// refreshes a 60s presence key on its own 25s heartbeat tick (server.js relayHeartbeat →
+// relayHub.markOnline, PRESENCE_TTL_SECS = 60), and the app's agent list reads exactly
+// that key. So the budget to detect a dead socket AND finish reconnecting is 60s from the
+// last tick that reached us — otherwise the key lapses and the harbor blinks out of the
+// app even though recovery is already under way. At the old 75s this was guaranteed: a
+// silent death always cost ~20-40s of visible "offline". 50s of silence is already
+// conclusive (two-plus missed exchanges) and leaves ~10s for the reconnect to re-register.
+//
+// Detection granularity is its own timer: polling silence on the 20s PING cadence added
+// up to a whole extra ping interval of latency, and after a laptop wake (timers frozen
+// while asleep — the common cause of this whole failure mode) it decided how long the
+// harbor stayed dark. Checking every 5s costs nothing and bounds that.
 const HEARTBEAT_MS = 20_000;
-const LIVENESS_TIMEOUT_MS = 75_000;
+const LIVENESS_CHECK_MS = 5_000;
+const LIVENESS_TIMEOUT_MS = 50_000;
 // Cap the opening handshake too. Without this a black-holed connect leaves `this.ws`
 // set with no open/close/error ever firing, and connect()'s `if (this.ws) return`
 // guard then blocks every future attempt — the same permanent silence by another route.
@@ -267,6 +292,20 @@ function clip(s: string, max: number): string {
   return s.slice(0, max) + `\n… (${s.length - max} more chars)`;
 }
 
+// Rewrite a path under the home directory as `~/…` — the CLI's own display form.
+// Used on the cwd we report in a context frame: the driver still sees which folder
+// the agent is working in, without the account name in the absolute path crossing
+// the relay. Only an exact home prefix is collapsed (`/Users/pat2` is left alone);
+// a path outside home is returned unchanged.
+function homeCollapsed(p: string): string {
+  let home = "";
+  try { home = homedir(); } catch { /* no home → nothing to collapse */ }
+  if (!home || !p.startsWith(home)) return p;
+  const rest = p.slice(home.length);
+  if (rest === "") return "~";
+  return rest.startsWith("/") || rest.startsWith("\\") ? `~${rest}` : p;
+}
+
 function asText(output: unknown): string {
   return typeof output === "string" ? output : JSON.stringify(output);
 }
@@ -314,6 +353,8 @@ export class RelayClient {
   private heartbeatTimer: ReturnType<typeof setInterval> | undefined;
   private lastInboundAt = 0;
   private connectedAt = 0;
+  // Current backoff delay for the next unqualified scheduleReconnect(); reset on 'open'.
+  private reconnectDelay = RECONNECT_MS;
   // Last refusal reason reported, so a 4xx is logged once instead of on every retry.
   private refusal: string | null = null;
   // Ordered delta buffer (text/reasoning) coalesced into one frame per flush.
@@ -402,6 +443,7 @@ export class RelayClient {
     if (this.flushTimer) { clearTimeout(this.flushTimer); this.flushTimer = undefined; }
     this.stopHeartbeat();
     this.connectedAt = 0;
+    this.reconnectDelay = RECONNECT_MS; // a restarted client shouldn't inherit old backoff
     this.bufKind = null;
     this.buf = "";
     this.incoming.clear();
@@ -450,6 +492,7 @@ export class RelayClient {
       ws.on("open", () => {
         opened = true;
         this.refusal = null; // a later refusal is news again
+        this.reconnectDelay = RECONNECT_MS; // reachable again — next blip retries fast
         this.connectedAt = Date.now();
         this.startHeartbeat(ws);
         this.settleFirstConnect(); // terminal is live on the relay — awaitRegistered() resolves
@@ -525,11 +568,13 @@ export class RelayClient {
   private startHeartbeat(ws: WebSocket): void {
     this.stopHeartbeat();
     this.lastInboundAt = Date.now();
+    let lastPingAt = Date.now();
     this.heartbeatTimer = setInterval(() => {
       // A socket we've since replaced or dropped isn't ours to police anymore.
       if (this.ws !== ws) { this.stopHeartbeat(); return; }
       if (ws.readyState !== WebSocket.OPEN) return; // closing — 'close' will clean up
-      const quietMs = Date.now() - this.lastInboundAt;
+      const now = Date.now();
+      const quietMs = now - this.lastInboundAt;
       if (quietMs > LIVENESS_TIMEOUT_MS) {
         this.cb.onStatus?.(
           `Remote access went silent for ${Math.round(quietMs / 1000)}s (the connection died without closing) — dropping it and reconnecting…`,
@@ -538,8 +583,13 @@ export class RelayClient {
         try { ws.terminate(); } catch (_) { /* already gone — 'close' still fires */ }
         return;
       }
-      try { ws.ping(); } catch (_) { /* socket dying — the next tick or 'close' handles it */ }
-    }, HEARTBEAT_MS);
+      // The check runs on LIVENESS_CHECK_MS; the ping stays on its own slower cadence so
+      // tightening detection doesn't multiply the traffic we put on the wire.
+      if (now - lastPingAt >= HEARTBEAT_MS) {
+        lastPingAt = now;
+        try { ws.ping(); } catch (_) { /* socket dying — the next tick or 'close' handles it */ }
+      }
+    }, LIVENESS_CHECK_MS);
     // Never hold the process open for a heartbeat alone.
     this.heartbeatTimer.unref?.();
   }
@@ -548,12 +598,28 @@ export class RelayClient {
     if (this.heartbeatTimer) { clearInterval(this.heartbeatTimer); this.heartbeatTimer = undefined; }
   }
 
-  private scheduleReconnect(delayMs: number = RECONNECT_MS): void {
+  // Schedule the next connect attempt. With no explicit delay this walks the backoff
+  // ladder (reset to RECONNECT_MS by a successful 'open'), so the first retry after a
+  // blip is still ~3s and only a genuinely unreachable relay backs off. An explicit
+  // delay — the REFUSED_RECONNECT_MS path — is a deliberate cadence for a decision that
+  // won't change on its own, so it bypasses the ladder rather than compounding with it.
+  private scheduleReconnect(delayMs?: number): void {
     if (this.closed || this.reconnectTimer) return;
+    let wait: number;
+    if (typeof delayMs === "number") {
+      wait = delayMs;
+    } else {
+      wait = this.reconnectDelay;
+      this.reconnectDelay = Math.min(Math.round(this.reconnectDelay * RECONNECT_GROWTH), RECONNECT_MAX_MS);
+    }
+    // Jitter every wait (including the fixed ones): the point is to break up fleet-wide
+    // synchronization after a server restart, which is exactly when many clients are
+    // sitting on the same timer.
+    const jittered = Math.max(250, Math.round(wait * (1 + (Math.random() * 2 - 1) * RECONNECT_JITTER)));
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = undefined;
       void this.connect();
-    }, delayMs);
+    }, jittered);
   }
 
   private handle(data: WebSocket.RawData): void {
@@ -926,13 +992,22 @@ export class RelayClient {
   // Push this terminal's live context (selected model, agent version) to a
   // controller so the app's session banner reflects reality instead of a stub.
   // Sent on controller attach — like the snapshot/no_quarter resync. NON-PII ONLY
-  // by design: deliberately NO cwd / hostname / username, matching terminalLabel's
+  // by design: deliberately NO hostname / username, matching terminalLabel's
   // stance (the server/controller learns as little as possible about the machine).
   // Empty/absent fields are omitted so the app renders less rather than blank.
-  sendContext(ctx: { model?: string; version?: string; terminalPub?: string }): void {
+  //
+  // `cwd` is the one scoped exception, and ONLY a harbor-spawned live session passes
+  // it (see liveTaskSession): the driver chose that directory in the spawn form — or,
+  // having left it blank, needs to see which one the harbor picked — because it is
+  // where everything that session reads, writes and `@`-mentions lives, and unlike an
+  // interactive terminal there is no human sitting in it to already know. It is
+  // home-collapsed (`~/…`) on the way out, so the banner reads like the CLI's own and
+  // the OS username still never crosses the relay.
+  sendContext(ctx: { model?: string; version?: string; cwd?: string; terminalPub?: string }): void {
     const frame: Record<string, unknown> = { type: "context" };
     if (typeof ctx.model === "string" && ctx.model) frame.model = ctx.model;
     if (typeof ctx.version === "string" && ctx.version) frame.version = ctx.version;
+    if (typeof ctx.cwd === "string" && ctx.cwd) frame.cwd = clip(homeCollapsed(ctx.cwd), 300);
     // The terminal's identity public key (base64). NOT PII — it's a public key, and
     // the app uses it to confirm this terminal is the one it PINNED at link time
     // before sealing any secret to it (channel tokens). A malicious relay can swap