@phnx-labs/agents-cli 1.22.47 → 1.22.49

package/dist/lib/share/worker-template.js

@@ -1,8 +1,21 @@
 // The Cloudflare Worker that fronts the R2 share bucket.
 //
 // One tiny Worker does both sides:
-//   - PUT  /<username>/<slug>  — bearer-gated (WRITE_TOKEN secret); writes the body
-//     to R2 via the BUCKET binding, storing an optional expires-at value plus
+//   - PUT  /<username>/<slug>  — bearer-gated by TWO principals (not a fallback):
+//       1. Static WRITE_TOKEN (BYO Cloudflare) — checked first when the presented
+//          bearer equals env.WRITE_TOKEN. owner = env.SHARE_NAMESPACE or the
+//          path's first segment.
+//       2. Phoenix bearer — otherwise GET ${env.PHOENIX_ID_BASE}/api/v1/auth/me
+//          with that bearer → {userId,email}; 401 if absent/invalid.
+//          customMetadata.owner = userId (stable). The path's first segment MUST
+//          equal handleFromEmail(email) (the public handle, e.g. muqsitnawaz),
+//          so one user cannot write another's prefix (403 namespace mismatch).
+//          A __handles/<handle> claim binds the handle to the first userId that
+//          writes it; a different userId gets 409 handle taken.
+//     A managed deployment sets PHOENIX_ID_BASE; BYO sets WRITE_TOKEN; the
+//     platform endpoint may set both. Fail loud (401) when neither authenticates.
+//     Writes the body to R2 via the BUCKET binding, storing visibility
+//     (public|unlisted; org → 400 in P1), owner, an optional expires-at, plus
 //     provenance (agent/session/host/repo/date), a label, and any `--meta`
 //     entries in object metadata. Overwriting an existing slug first copies the
 //     current object to <slug>/rev-<ts>-<rand> (revision history) unless
@@ -39,6 +52,10 @@
 export function renderWorkerScript() {
     return `// GENERATED by agents-cli agents share setup — do not edit here; edit
 // src/lib/share/worker-template.ts and re-run setup.
+export const hooks = {
+  verifyPhoenixToken: defaultVerifyPhoenixToken,
+};
+
 export default {
   async fetch(request, env) {
     const url = new URL(request.url);
@@ -50,15 +67,30 @@ export default {
       });
     }
 
+    const firstSeg = path.split('/').filter(Boolean)[0] || '';
+    if ((request.method === 'GET' || request.method === 'HEAD') && firstSeg.startsWith('__')) {
+      return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain' } });
+    }
+
     if (request.method === 'PUT') {
-      const presented = (request.headers.get('authorization') || '').replace(/^Bearer\\s+/i, '');
-      if (!env.WRITE_TOKEN || !safeEqual(presented, env.WRITE_TOKEN)) {
-        return json({ error: 'unauthorized' }, 401);
+      const auth = await authorizeWrite(request, env);
+      if (auth.error) return auth.error;
+      const vis = normalizeVisibility(request.headers.get('x-share-visibility'));
+      if (vis.error) return vis.error;
+      const visibility = vis.value;
+      const segments = path.split('/').filter(Boolean);
+      if (auth.kind === 'phoenix') {
+        const expected = phoenixHandle(auth);
+        if (!expected || segments[0] !== expected) {
+          return json({ error: 'namespace mismatch', owner: expected }, 403);
+        }
+        const claimed = await claimHandle(env.BUCKET, expected, auth.owner);
+        if (claimed.error) return claimed.error;
       }
       const expiresAt = request.headers.get('x-share-expires-at') || '';
       // 'unlisted' hides the page from the public gallery + JSON listing while
       // keeping the direct URL world-readable (capability URL, not secret).
-      const visibility = (request.headers.get('x-share-visibility') || '').toLowerCase();
+      // GET also sends X-Robots-Tag: noindex for unlisted objects.
       const contentType = request.headers.get('content-type') || 'text/html; charset=utf-8';
       // Provenance (RUSH-2683): captured client-side from the exec env/git/clock,
       // never invented here — a header is simply absent when the CLI had nothing
@@ -93,7 +125,12 @@ export default {
         delete customMetadata[reservedKey];
       }
       if (expiresAt) customMetadata['expires-at'] = expiresAt;
-      if (visibility === 'unlisted') customMetadata['visibility'] = 'unlisted';
+      customMetadata['visibility'] = visibility;
+      const owner =
+        auth.kind === 'phoenix'
+          ? auth.owner
+          : (env.SHARE_NAMESPACE || segments[0] || 'byo');
+      if (owner) customMetadata['owner'] = owner;
       if (agent) customMetadata['agent'] = agent;
       if (session) customMetadata['session'] = session;
       if (host) customMetadata['host'] = host;
@@ -129,7 +166,7 @@ export default {
         httpMetadata: { contentType },
         customMetadata,
       });
-      return json({ ok: true, url: url.origin + '/' + path, expiresAt: expiresAt || null, unlisted: visibility === 'unlisted' }, 200);
+      return json({ ok: true, url: url.origin + '/' + path, expiresAt: expiresAt || null, unlisted: visibility === 'unlisted', visibility }, 200);
     }
 
     if (request.method === 'GET' || request.method === 'HEAD') {
@@ -174,12 +211,32 @@ export default {
       headers.set('etag', obj.httpEtag);
       if (!headers.has('content-type')) headers.set('content-type', 'text/html; charset=utf-8');
       headers.set('cache-control', 'public, max-age=60');
+      if (obj.customMetadata && obj.customMetadata.visibility === 'unlisted') {
+        headers.set('X-Robots-Tag', 'noindex');
+      }
       return new Response(request.method === 'HEAD' ? null : obj.body, { status: 200, headers });
     }
 
     if (request.method === 'DELETE') {
-      const presented = (request.headers.get('authorization') || '').replace(/^Bearer\\s+/i, '');
-      if (!env.WRITE_TOKEN || !safeEqual(presented, env.WRITE_TOKEN)) return json({ error: 'unauthorized' }, 401);
+      const auth = await authorizeWrite(request, env);
+      if (auth.error) return auth.error;
+      if (auth.kind === 'phoenix') {
+        const handle = phoenixHandle(auth);
+        const uid = sanitizeNamespace(auth.owner);
+        const delSegments = path.split('/').filter(Boolean);
+        // Handle is the public namespace; userId prefix is still deletable so
+        // P1 UUID-namespaced objects the same account published can be taken down.
+        // A colliding local-part (same handle, different userId) must not be
+        // able to DELETE the claimant's pages — consult the claim the same way PUT does.
+        if (delSegments[0] && delSegments[0] === uid) {
+          // own leftover UUID prefix
+        } else if (delSegments[0] && delSegments[0] === handle) {
+          const owned = await assertHandleOwner(env.BUCKET, handle, auth.owner);
+          if (owned.error) return owned.error;
+        } else {
+          return json({ error: 'namespace mismatch', owner: handle || uid }, 403);
+        }
+      }
       await env.BUCKET.delete(path);
       return json({ ok: true, deleted: path }, 200);
     }
@@ -347,7 +404,7 @@ async function renderRevisions(bucket, origin, key, method) {
 // before it ever reaches this Worker; see RESERVED_META_KEYS in publish.ts).
 // One list, reused both to strip a same-named --meta collision on write and
 // to split arbitrary --meta entries back out on read.
-var RESERVED_METADATA_KEYS = ['expires-at', 'visibility', 'agent', 'session', 'host', 'repo', 'date', 'label', 'label-source'];
+var RESERVED_METADATA_KEYS = ['expires-at', 'visibility', 'owner', 'agent', 'session', 'host', 'repo', 'date', 'label', 'label-source'];
 
 // Everything in customMetadata that ISN'T one of the reserved provenance/label
 // keys above — i.e. the caller's own \`--meta key=value\` entries. Surfaced on
@@ -383,5 +440,108 @@ function safeEqual(a, b) {
   for (let i = 0; i < la; i++) out |= a.charCodeAt(i) ^ b.charCodeAt(i % lb || 0);
   return out === 0 && la === lb;
 }
+
+// URL-safety, not collision-resistance. Two values that differ only in
+// case/punctuation share a prefix.
+function sanitizeNamespace(s) {
+  return String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+// Public handle: email local-part, plus-tag stripped. Must match CLI handleFromEmail.
+function handleFromEmail(email) {
+  if (!email) return '';
+  const local = String(email).split('@')[0] || '';
+  const beforePlus = local.split('+')[0] || local;
+  return sanitizeNamespace(beforePlus);
+}
+
+function phoenixHandle(auth) {
+  return handleFromEmail(auth.email) || sanitizeNamespace(auth.owner);
+}
+
+// First writer of a handle owns it. Later PUTs from the same userId are fine;
+// a different userId whose email local-part collides gets 409, not a silent overwrite.
+async function assertHandleOwner(bucket, handle, userId) {
+  // Pages under the handle already stamp customMetadata.owner = userId.
+  // Treat that as the source of truth so a colliding local-part cannot
+  // PUT/DELETE another account's objects even if the claim object is missing.
+  const list = await bucket.list({ prefix: handle + '/', include: ['customMetadata'] });
+  for (const o of list.objects || []) {
+    const owner = o.customMetadata && o.customMetadata.owner;
+    if (owner && owner !== userId) {
+      return { error: json({ error: 'handle taken', handle: handle }, 409) };
+    }
+  }
+  const key = '__handles/' + handle;
+  const existing = await bucket.get(key);
+  if (!existing) return {};
+  const claimed = existing.customMetadata && existing.customMetadata.userId;
+  if (claimed && claimed !== userId) {
+    return { error: json({ error: 'handle taken', handle: handle }, 409) };
+  }
+  return {};
+}
+
+async function claimHandle(bucket, handle, userId) {
+  const owned = await assertHandleOwner(bucket, handle, userId);
+  if (owned.error) return owned;
+  const key = '__handles/' + handle;
+  // Write (or rewrite) so a same-user republish resets object Age against the
+  // bucket's 366-day lifecycle — otherwise the claim can expire while pages stay live.
+  await bucket.put(key, JSON.stringify({ userId: userId }), {
+    httpMetadata: { contentType: 'application/json' },
+    customMetadata: { userId: userId, visibility: 'unlisted' },
+  });
+  return {};
+}
+
+// P1 visibility: public | unlisted. 'org' (and anything else) is 400 — org is Phase 2.
+function normalizeVisibility(raw) {
+  const v = (raw || '').trim().toLowerCase();
+  if (!v || v === 'public') return { value: 'public' };
+  if (v === 'unlisted') return { value: 'unlisted' };
+  if (v === 'org') return { error: json({ error: 'visibility org is not supported yet' }, 400) };
+  return { error: json({ error: 'visibility must be public or unlisted' }, 400) };
+}
+
+async function defaultVerifyPhoenixToken(request, env) {
+  const presented = (request.headers.get('authorization') || '').replace(/^Bearer\\s+/i, '');
+  if (!presented) return null;
+  const base = typeof env.PHOENIX_ID_BASE === 'string' ? env.PHOENIX_ID_BASE.replace(/\\/+$/, '') : '';
+  if (!base) return null;
+  let res;
+  try {
+    res = await fetch(base + '/api/v1/auth/me', {
+      method: 'GET',
+      headers: { Authorization: 'Bearer ' + presented },
+    });
+  } catch {
+    return null;
+  }
+  if (!res.ok) return null;
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    return null;
+  }
+  if (!body || typeof body.userId !== 'string' || !body.userId) return null;
+  return { userId: body.userId, email: typeof body.email === 'string' ? body.email : '' };
+}
+
+// Two legitimate principals: WRITE_TOKEN equality first (admin/BYO), otherwise
+// the bearer is a Phoenix token and we verify it. 401 when neither authenticates.
+async function authorizeWrite(request, env) {
+  const presented = (request.headers.get('authorization') || '').replace(/^Bearer\\s+/i, '');
+  if (!presented) return { error: json({ error: 'unauthorized' }, 401) };
+  if (env.WRITE_TOKEN && safeEqual(presented, env.WRITE_TOKEN)) {
+    return { kind: 'byo', owner: env.SHARE_NAMESPACE || 'byo' };
+  }
+  const claims = await hooks.verifyPhoenixToken(request, env);
+  if (claims && typeof claims.userId === 'string' && claims.userId) {
+    return { kind: 'phoenix', owner: claims.userId, email: typeof claims.email === 'string' ? claims.email : '' };
+  }
+  return { error: json({ error: 'unauthorized' }, 401) };
+}
 `;
 }

package/dist/lib/sqlite.js

@@ -41,10 +41,23 @@ function loadNodeSqlite() {
         process.emitWarning = original;
     }
 }
-// Keep Node on createRequire() so Vitest doesn't try to prebundle the built-in
-// sqlite module as a userland package during test collection.
+// Keep BOTH runtimes on createRequire() so Vitest doesn't try to prebundle the
+// built-in sqlite module as a userland package during test collection.
+//
+// The Bun arm used to be `await import('bun:sqlite' as string)`, which made this
+// a TOP-LEVEL AWAIT. esbuild cannot lower top-level await to CJS, so every test
+// that spawns a subprocess through `tsx` (CJS mode) died at transform time with
+// `Top-level await is currently not supported with the "cjs" output format` --
+// 49 failures across 7 files, none of which touch sqlite. `require` is
+// synchronous, so the await disappears and with it the whole failure class.
+//
+// The specifier is held in a variable, not written inline: a literal
+// `require('bun:sqlite')` is statically analyzable, so bundlers and Vitest's
+// collector try to resolve a module that does not exist off-Bun. That
+// indirection is what the old `as string` cast was doing for the dynamic import.
+const BUN_SQLITE = 'bun:sqlite';
 const sqliteMod = isBun
-    ? await import('bun:sqlite')
+    ? require(BUN_SQLITE)
     : loadNodeSqlite();
 // bun:sqlite exports `Database`; node:sqlite exports `DatabaseSync`.
 const NativeDatabase = sqliteMod.Database

package/dist/lib/ssh-exec.d.ts

@@ -13,6 +13,14 @@
  * smuggled in as part of a remote command, and `sshExec` additionally rejects a
  * leading `-` so it can never be parsed as an ssh argv flag.
  */
+/**
+ * ssh's own connection-layer failure code — the transport dropped or never came
+ * up, as opposed to the remote command choosing an exit status. Defined here,
+ * in the layer that owns the ssh invocation, and re-exported by
+ * `lib/hosts/reconnect.ts` as `SSH_CONN_FAILURE` so there is one constant for
+ * the concept rather than two that can drift apart.
+ */
+export declare const SSH_CONN_FAILURE_CODE = 255;
 export declare const SSH_TARGET_RE: RegExp;
 export declare function assertValidSshTarget(host: string): void;
 /** POSIX single-quote a string for safe interpolation into a remote shell command. */
@@ -156,11 +164,68 @@ export interface SshStreamOptions {
     /** Additional OpenSSH argv placed before the target (for example `-i <path>`). */
     extraSshArgs?: string[];
 }
+/**
+ * The DEC private modes a full-screen remote app turns ON and, when it exits
+ * cleanly, turns back off itself. A remote agent TUI killed by a dropped link
+ * never gets to, so they stay enabled on the LOCAL terminal after ssh is gone:
+ * focus reporting (1004) and the mode/colour-scheme reports (996/997) then make
+ * the terminal emit answerback sequences at a shell that is not expecting them,
+ * which is the `^[[?997;1n ^[[I ^[[O` litter seen after a drop (RUSH-3125). Also
+ * resets bracketed paste (2004), the alternate screen (1049), mouse tracking
+ * (1000/1002/1003/1006), and re-shows the cursor (25) — every one of which a TUI
+ * leaves armed the same way.
+ */
+export declare const TERMINAL_MODE_RESET: string;
+/**
+ * Put the local terminal back the way ssh found it.
+ *
+ * Two independent kinds of state survive a hard ssh death, and BOTH have to be
+ * undone or the next thing the user sees is corrupted:
+ *
+ *  - **termios** (kernel side): `-tt` puts the tty in raw mode, so a killed ssh
+ *    leaves it with echo and line-editing off. `saved` is the `stty -g` snapshot
+ *    taken before the spawn; restoring it is exact, unlike guessing at `sane`.
+ *  - **DEC private modes** (terminal side): see {@link TERMINAL_MODE_RESET}.
+ *
+ * Then drain whatever the terminal already answered back into the input buffer.
+ * Without the drain those bytes are not merely cosmetic — they are still queued
+ * on the tty, so the NEXT attach hands them straight to the agent as if the user
+ * had typed them.
+ *
+ * Best-effort by construction: this runs while recovering from a failure, so a
+ * missing `stty`, a non-TTY stdin, or a closed stream must never turn a
+ * recoverable drop into a thrown error.
+ */
+export declare function restoreLocalTerminal(saved: string | undefined, opts: {
+    drainStdin: boolean;
+}): void;
+/** `stty -g` snapshot of the local tty, or undefined when there is nothing to snapshot. */
+export declare function saveLocalTerminal(): string | undefined;
 /**
  * Foreground counterpart to `sshExec`: run `remoteCmd` on `target` with the
  * local stdio wired straight through (`stdio: 'inherit'`), so output streams as
  * it is produced and — with `tty` — keystrokes reach a remote picker. Blocks
  * until the remote command exits and returns its exit code (255 is ssh's own
  * connection-layer failure; any other non-zero is the remote command's code).
+ *
+ * On a `tty` stream the local terminal state is snapshotted before the spawn and
+ * restored after it. ssh restores termios itself when it exits cleanly, so this
+ * is for the case that matters here: the link dying under a full-screen agent
+ * TUI, which leaves the tty raw and the TUI's DEC modes armed. Doing it HERE
+ * rather than in the reconnect loop means every caller that opens an interactive
+ * remote stream is covered, not just the one that noticed (RUSH-3125).
+ *
+ * **The stdin drain is gated on an ABNORMAL exit, and the distinction is not
+ * cosmetic.** Resetting termios and the DEC modes is idempotent — on a clean
+ * exit ssh and the remote TUI have already done it, so re-doing it changes
+ * nothing. Draining stdin is destructive: it discards whatever the user has
+ * typed ahead. On a clean exit those bytes are legitimate type-ahead the
+ * resuming shell should receive, and eating them would be a new bug in every
+ * caller of this function (`runInteractiveOnHost`, the remote-tmux attach in
+ * commands/go.ts, the remote secrets browse) rather than a fix. Only an
+ * abnormal exit — ssh killed by a signal (`status === null`) or its own
+ * connection-layer failure (255) — produces the answerback storm the drain
+ * exists to clear, because only then did the TUI die without sending its own
+ * mode resets.
  */
 export declare function sshStream(target: string, remoteCmd: string, opts?: SshStreamOptions): number;

package/dist/lib/ssh-exec.js

@@ -18,6 +18,14 @@ import { getCacheDir } from './state.js';
  * smuggled in as part of a remote command, and `sshExec` additionally rejects a
  * leading `-` so it can never be parsed as an ssh argv flag.
  */
+/**
+ * ssh's own connection-layer failure code — the transport dropped or never came
+ * up, as opposed to the remote command choosing an exit status. Defined here,
+ * in the layer that owns the ssh invocation, and re-exported by
+ * `lib/hosts/reconnect.ts` as `SSH_CONN_FAILURE` so there is one constant for
+ * the concept rather than two that can drift apart.
+ */
+export const SSH_CONN_FAILURE_CODE = 255;
 export const SSH_TARGET_RE = /^[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
 export function assertValidSshTarget(host) {
     if (host.startsWith('-') || !SSH_TARGET_RE.test(host)) {
@@ -314,20 +322,128 @@ export function sshExecRawStream(target, remoteCmd, opts) {
 export function sshReachable(target, timeoutMs = 10000) {
     return sshExec(target, 'true', { timeoutMs, multiplex: true }).code === 0;
 }
+/**
+ * The DEC private modes a full-screen remote app turns ON and, when it exits
+ * cleanly, turns back off itself. A remote agent TUI killed by a dropped link
+ * never gets to, so they stay enabled on the LOCAL terminal after ssh is gone:
+ * focus reporting (1004) and the mode/colour-scheme reports (996/997) then make
+ * the terminal emit answerback sequences at a shell that is not expecting them,
+ * which is the `^[[?997;1n ^[[I ^[[O` litter seen after a drop (RUSH-3125). Also
+ * resets bracketed paste (2004), the alternate screen (1049), mouse tracking
+ * (1000/1002/1003/1006), and re-shows the cursor (25) — every one of which a TUI
+ * leaves armed the same way.
+ */
+export const TERMINAL_MODE_RESET = '\x1b[?1004l\x1b[?996l\x1b[?997l\x1b[?2004l\x1b[?1049l'
+    + '\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?25h';
+/**
+ * Put the local terminal back the way ssh found it.
+ *
+ * Two independent kinds of state survive a hard ssh death, and BOTH have to be
+ * undone or the next thing the user sees is corrupted:
+ *
+ *  - **termios** (kernel side): `-tt` puts the tty in raw mode, so a killed ssh
+ *    leaves it with echo and line-editing off. `saved` is the `stty -g` snapshot
+ *    taken before the spawn; restoring it is exact, unlike guessing at `sane`.
+ *  - **DEC private modes** (terminal side): see {@link TERMINAL_MODE_RESET}.
+ *
+ * Then drain whatever the terminal already answered back into the input buffer.
+ * Without the drain those bytes are not merely cosmetic — they are still queued
+ * on the tty, so the NEXT attach hands them straight to the agent as if the user
+ * had typed them.
+ *
+ * Best-effort by construction: this runs while recovering from a failure, so a
+ * missing `stty`, a non-TTY stdin, or a closed stream must never turn a
+ * recoverable drop into a thrown error.
+ */
+export function restoreLocalTerminal(saved, opts) {
+    try {
+        if (saved)
+            spawnSync('stty', [saved], { stdio: ['inherit', 'ignore', 'ignore'] });
+    }
+    catch { /* no stty, or stdin is not a tty — nothing to restore */ }
+    try {
+        if (process.stdout.isTTY)
+            process.stdout.write(TERMINAL_MODE_RESET);
+    }
+    catch { /* stream closed */ }
+    try {
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode?.(false);
+    }
+    catch { /* stdin not controllable in this context */ }
+    // The DRAIN is the one destructive step here, so it is opt-in per exit. See
+    // {@link sshStream} for why it must not run on a clean exit.
+    if (!opts.drainStdin)
+        return;
+    try {
+        // read() on a paused non-flowing stdin returns the buffered bytes and
+        // discards them; the loop clears a burst rather than one chunk.
+        if (process.stdin.isTTY) {
+            while (process.stdin.read() !== null) { /* discard */ }
+        }
+    }
+    catch { /* stdin not readable in this context */ }
+}
+/** `stty -g` snapshot of the local tty, or undefined when there is nothing to snapshot. */
+export function saveLocalTerminal() {
+    if (!process.stdin.isTTY)
+        return undefined;
+    try {
+        const r = spawnSync('stty', ['-g'], { stdio: ['inherit', 'pipe', 'ignore'], encoding: 'utf-8' });
+        const out = r.status === 0 ? r.stdout?.trim() : '';
+        return out || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Foreground counterpart to `sshExec`: run `remoteCmd` on `target` with the
  * local stdio wired straight through (`stdio: 'inherit'`), so output streams as
  * it is produced and — with `tty` — keystrokes reach a remote picker. Blocks
  * until the remote command exits and returns its exit code (255 is ssh's own
  * connection-layer failure; any other non-zero is the remote command's code).
+ *
+ * On a `tty` stream the local terminal state is snapshotted before the spawn and
+ * restored after it. ssh restores termios itself when it exits cleanly, so this
+ * is for the case that matters here: the link dying under a full-screen agent
+ * TUI, which leaves the tty raw and the TUI's DEC modes armed. Doing it HERE
+ * rather than in the reconnect loop means every caller that opens an interactive
+ * remote stream is covered, not just the one that noticed (RUSH-3125).
+ *
+ * **The stdin drain is gated on an ABNORMAL exit, and the distinction is not
+ * cosmetic.** Resetting termios and the DEC modes is idempotent — on a clean
+ * exit ssh and the remote TUI have already done it, so re-doing it changes
+ * nothing. Draining stdin is destructive: it discards whatever the user has
+ * typed ahead. On a clean exit those bytes are legitimate type-ahead the
+ * resuming shell should receive, and eating them would be a new bug in every
+ * caller of this function (`runInteractiveOnHost`, the remote-tmux attach in
+ * commands/go.ts, the remote secrets browse) rather than a fix. Only an
+ * abnormal exit — ssh killed by a signal (`status === null`) or its own
+ * connection-layer failure (255) — produces the answerback storm the drain
+ * exists to clear, because only then did the TUI die without sending its own
+ * mode resets.
  */
 export function sshStream(target, remoteCmd, opts = {}) {
     assertValidSshTarget(target);
     const mux = opts.multiplex === false ? [] : controlOpts();
     const tty = opts.tty ? ['-tt'] : [];
     const args = [...sshConnectOpts(mux, opts.hostKeyOpts), ...(opts.extraSshArgs ?? []), ...tty, target, remoteCmd];
-    const res = spawnSync('ssh', args, { stdio: 'inherit' });
-    if (typeof res.status === 'number')
-        return res.status;
-    return 255; // spawn error / signal — treat as a connection-layer failure
+    const saved = opts.tty ? saveLocalTerminal() : undefined;
+    let abnormal = true; // a throw before/inside the spawn is abnormal by definition
+    try {
+        const res = spawnSync('ssh', args, { stdio: 'inherit' });
+        const code = typeof res.status === 'number' ? res.status : 255;
+        // Killed by a signal (no numeric status) or ssh's own connection-layer
+        // failure — the two shapes in which the remote TUI never got to reset the
+        // terminal. Any other code is ssh exiting normally with the remote's status.
+        abnormal = res.status === null || code === SSH_CONN_FAILURE_CODE;
+        return code;
+    }
+    finally {
+        // `finally`, because the abnormal exits are precisely the ones that leave
+        // the terminal wrecked — but the drain within it is gated (see the doc).
+        if (opts.tty)
+            restoreLocalTerminal(saved, { drainStdin: abnormal });
+    }
 }

package/dist/lib/startup/command-registry.js

@@ -10,7 +10,7 @@ const LOADED_COMMAND_NAMES = [
     'ssh', 'devices', 'fleet', 'repos', 'repo', 'setup', 'uninstall', 'upgrade', 'sessions',
     'teams', 'cloud', 'message', 'send', 'notify', 'feed',
     'mailboxes', 'mailbox', 'artifacts', 'webhooks',
-    'humans', 'daemon',
+    'humans', 'daemon', 'traces',
 ];
 const INLINE_COMMAND_NAMES = [
     'perms', 'exec', 'jobs', 'cron', 'check', 'resources', 'hq', '_internal',

package/dist/lib/startup/dev-build.js

@@ -22,12 +22,12 @@ import * as path from 'path';
  * looking for `.git`.
  *
  * That package root does not always hold `.git` itself, though — this repo is a
- * monorepo where the package lives at `apps/cli` and `.git` sits one level
+ * monorepo where the package lives at `cli` and `.git` sits one level
  * higher, at the true repo root. `.git` is therefore searched for in a SMALL,
  * bounded set of ancestors above the package root (see
  * `DEV_BUILD_GIT_ANCESTOR_DEPTH`), not just the package root itself — a source
- * checkout run via tsx/ts-node from `apps/cli/src/` or built to
- * `apps/cli/dist/` must still be recognized. The bound keeps this well short of
+ * checkout run via tsx/ts-node from `cli/src/` or built to
+ * `cli/dist/` must still be recognized. The bound keeps this well short of
  * an unrelated ancestor repo: a real Homebrew npm-global install's package root
  * sits 3 directories below `/opt/homebrew` (`lib/node_modules/@phnx-labs/…`),
  * so a depth of 2 finds this repo's `.git` while staying short of Homebrew's.

package/dist/lib/state.d.ts

@@ -31,7 +31,7 @@ export declare function getHumansFilePath(): string;
  * file against `schema/agents-yaml.schema.json`. Exported so
  * `lib/devices/config-migration.ts` rewrites a device doc with the same header.
  */
-export declare const META_HEADER = "# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/apps/cli/schema/agents-yaml.schema.json\n\n";
+export declare const META_HEADER = "# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/cli/schema/agents-yaml.schema.json\n\n";
 /** Root of the system data directory (~/.agents/.system/). */
 export declare function getAgentsDir(): string;
 /** Root of the system data directory (~/.agents/.system/). */

package/dist/lib/state.js

@@ -168,7 +168,7 @@ const USER_PROMPTCUTS_FILE = path.join(USER_AGENTS_DIR, 'hooks', 'promptcuts.yam
 export const META_HEADER = `# agents-cli metadata
 # Auto-generated - do not edit manually
 # https://github.com/phnx-labs/agents-cli
-# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/apps/cli/schema/agents-yaml.schema.json
+# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/cli/schema/agents-yaml.schema.json
 
 `;
 // ─── Root getters ─────────────────────────────────────────────────────────────
@@ -895,7 +895,6 @@ const META_KEY_SCOPE = {
     actors: 'central',
     seededPresets: 'central',
     hooks: 'central',
-    browser: 'central',
     config: 'central',
     hosts: 'central',
     fleet: 'central',
@@ -910,7 +909,12 @@ const META_KEY_SCOPE = {
  * in central is stale and must be migrated out). A key NOT listed here — e.g. one
  * a newer CLI version added — is preserved verbatim, never dropped + synced away.
  */
-const KNOWN_META_KEYS = new Set(Object.keys(META_KEY_SCOPE));
+const KNOWN_META_KEYS = new Set([
+    ...Object.keys(META_KEY_SCOPE),
+    // Removed browser-profile store. Kept only as a serializer tombstone so the
+    // first registry read can migrate it into this device's file and delete it.
+    'browser',
+]);
 /**
  * Serialize the central (synced) meta to `agents.yaml` WITHOUT destroying the
  * hand-written comments in the committed file.

package/dist/lib/subagents-registry.js

@@ -27,7 +27,7 @@
  *
  * The per-agent `transform`/metadata parsers are the escape hatch: they live in
  * `subagents.ts` and are referenced by the table, so the generic engine has zero
- * per-agent branches. See the integration tiers in `docs/subagents.md`.
+ * per-agent branches. See `docs/orchestration.md`.
  */
 import * as fs from 'fs';
 import * as path from 'path';

package/dist/lib/terminal/index.d.ts

@@ -4,7 +4,7 @@
  *
  * Public entry point. Callers typically use `openSurfaces` (a batch with a
  * layout policy) or `openSurface` (a single request), and `availableBackends` /
- * `detectCurrentBackend` to pick a target. See docs/terminal-engine.md.
+ * `detectCurrentBackend` to pick a target. See docs/interfaces.md.
  */
 export type { Backend, SplitDirection, Layout, EngineContext, LaunchSpec, LaunchRequest, LaunchResult, TerminalBackend, } from './types.js';
 export { currentContext } from './types.js';

package/dist/lib/terminal/types.d.ts

@@ -5,7 +5,7 @@
  * command, in a chosen terminal backend (iTerm / Ghostty / tmux), on this
  * machine or a remote host. This is distinct from cloud providers
  * (src/lib/cloud), which dispatch autonomous headless tasks; a terminal surface
- * is attended and live. See docs/terminal-engine.md.
+ * is attended and live. See docs/interfaces.md.
  */
 /** An interactive terminal backend the engine can drive. */
 export type Backend = 'iterm' | 'ghostty' | 'tmux' | 'vscodium-agent' | 'terminal';

package/dist/lib/terminal/types.js

@@ -5,7 +5,7 @@
  * command, in a chosen terminal backend (iTerm / Ghostty / tmux), on this
  * machine or a remote host. This is distinct from cloud providers
  * (src/lib/cloud), which dispatch autonomous headless tasks; a terminal surface
- * is attended and live. See docs/terminal-engine.md.
+ * is attended and live. See docs/interfaces.md.
  */
 /** Snapshot the live process context. */
 export function currentContext() {

package/dist/lib/tmux/orphan-reap.js

@@ -172,7 +172,7 @@ export const DETACHED_HELPER_RULES = [CLAUDE_BG_DAEMON];
 export function isProtectedAgentsService(args) {
     return /\b__daemon-run\b/.test(args)
         || /\bsecrets\s+_agent-run\b/.test(args)
-        || /\bMenubarHelper\b/.test(args)
+        || /\bAGI Menu\b/.test(args)
         || /\bAgents CLI\.app\b/.test(args);
 }
 /** Is this pid currently running? Signal-0 probe, matching `platform/process.ts`. */