@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/share/publish.js

@@ -10,17 +10,39 @@ import { basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { hostname as osHostname } from 'node:os';
-import { readShareConfig, readWriteToken } from './config.js';
+import { readShareConfig } from './config.js';
 import { resolveGitHubUsername } from '../git.js';
+import { resolveShareBackend, sanitizeShareNamespace } from './backend.js';
 import { captureCover, OG_WIDTH, OG_HEIGHT, OG_SCALE } from './capture.js';
 import { deriveMeta, injectOgMeta } from './og.js';
 import { injectAnalyticsBeacon } from './analytics.js';
+import { prepareShareHtml } from './html.js';
+/** `--unlisted` / `{ unlisted: true }` map to `unlisted`; otherwise `visibility` (default public). */
+export function resolveShareVisibility(opts = {}) {
+    if (opts.unlisted === true)
+        return 'unlisted';
+    if (opts.visibility === 'unlisted')
+        return 'unlisted';
+    return 'public';
+}
 /**
- * Reserved `customMetadata` keys the CLI sets automatically from the exec env,
- * git, and the local clock (plus `label`/`label-source`) — a `--meta key=value`
- * may not target any of these (see {@link parseMetaEntries}).
+ * Reserved `customMetadata` keys a `--meta key=value` may not target (see
+ * {@link parseMetaEntries}). Matches the Worker's `RESERVED_METADATA_KEYS`:
+ * provenance the CLI sets automatically, plus `expires-at` / `visibility` /
+ * `owner` which the Worker stamps itself.
  */
-export const RESERVED_META_KEYS = ['agent', 'session', 'host', 'repo', 'date', 'label', 'label-source'];
+export const RESERVED_META_KEYS = [
+    'expires-at',
+    'visibility',
+    'owner',
+    'agent',
+    'session',
+    'host',
+    'repo',
+    'date',
+    'label',
+    'label-source',
+];
 const META_KEY_RE = /^[a-z0-9-]{1,64}$/;
 /**
  * Auto-capture publish provenance from the exec env, git, and the local clock.
@@ -43,8 +65,9 @@ export function resolveShareProvenance(opts = {}) {
 /**
  * Parse repeated `--meta key=value` CLI args into a validated metadata record.
  * Keys are lowercase `[a-z0-9-]`, up to 64 characters, and may not collide with
- * {@link RESERVED_META_KEYS} (the provenance the CLI sets automatically, plus
- * label/label-source) — throws naming the offending pair on any violation.
+ * {@link RESERVED_META_KEYS} (Worker-stamped owner/visibility/expires-at, plus
+ * the provenance the CLI sets automatically, plus label/label-source) — throws
+ * naming the offending pair on any violation.
  */
 export function parseMetaEntries(pairs) {
     const meta = {};
@@ -59,7 +82,7 @@ export function parseMetaEntries(pairs) {
             throw new Error(`Bad --meta key '${key}'. Keys are lowercase letters, digits, and hyphens, up to 64 characters.`);
         }
         if (RESERVED_META_KEYS.includes(key)) {
-            throw new Error(`--meta ${key}=… is reserved (set automatically from your session/git) — pass a different key.`);
+            throw new Error(`--meta ${key}=… is reserved (Worker-stamped, or set automatically from your session/git) — pass a different key.`);
         }
         meta[key] = value;
     }
@@ -293,7 +316,7 @@ export function slugify(name) {
         .slice(0, 60) || 'page');
 }
 function sanitizeSlugPart(s) {
-    return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    return sanitizeShareNamespace(s);
 }
 /** The current repo's name, or undefined outside a git checkout — never a
  * fallback guess, since callers that want one (detectProject) supply it themselves. */
@@ -317,18 +340,19 @@ export function detectProject(dir = process.cwd()) {
     return gitRepoName(dir) ?? (sanitizeSlugPart(basename(dir)) || 'share');
 }
 /**
- * Notion-style default slug: `<project>-<feature>-<16hex>`. Project scopes the link
- * to the repo the agent is in; the random tail keeps it unguessable + collision-free.
- * A leading `plan-` on the filename is dropped (it's redundant under the project).
+ * Readable slug + view id: `<feature>-<16hex>`. A leading `plan-` on the
+ * filename is dropped. The project no longer prefixes the slug — the URL
+ * namespace is already the publisher's handle (`/<you>/<slug>`).
  *
  * The tail is 8 random bytes (64-bit, 16 hex chars). Reads are public — the URL is
  * the only capability — so the nonce must be genuinely infeasible to brute-force,
- * not merely unlisted; 64 bits puts a blind guess out of reach. (See docs/share.md
+ * not merely unlisted; 64 bits puts a blind guess out of reach. (See docs/distribution.md
  * §Security for the threat model and `--expire` for sensitive content.)
+ * `--slug` still publishes that exact slug, no view-id appended.
  */
-export function defaultSlug(filePath, dir) {
+export function defaultSlug(filePath, _dir) {
     const feature = slugify(filePath).replace(/^plan-/, '') || 'page';
-    return `${detectProject(dir)}-${feature}-${randomBytes(8).toString('hex')}`;
+    return `${feature}-${randomBytes(8).toString('hex')}`;
 }
 function guessContentType(filePath) {
     if (/\.html?$/i.test(filePath))
@@ -419,14 +443,12 @@ export function buildShareKey(username, slugPart) {
     return `${user}/${part}`;
 }
 export async function publishFile(filePath, opts = {}) {
-    const cfg = opts.config ?? readShareConfig();
-    if (!cfg) {
-        throw new Error("Not set up yet. Run 'agents artifacts setup' (provision your own endpoint) or 'agents artifacts share join' (use an existing one).");
-    }
-    const token = opts.writeToken ?? readWriteToken();
-    const username = await resolveShareUsername(opts);
-    const analyticsToken = opts.analyticsToken ?? cfg.analyticsToken;
-    return publishToEndpoint(filePath, { baseUrl: cfg.baseUrl, token }, {
+    const backend = resolveShareBackend(opts);
+    const username = backend.kind === 'managed'
+        ? backend.namespace
+        : await resolveShareUsername({ githubUser: opts.githubUser || backend.namespace || undefined });
+    const analyticsToken = opts.analyticsToken ?? (backend.kind === 'byo' ? (opts.config ?? readShareConfig())?.analyticsToken : undefined);
+    return publishToEndpoint(filePath, { baseUrl: backend.baseUrl, token: backend.token }, {
         ...opts,
         githubUser: username,
         analyticsToken,
@@ -437,7 +459,8 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     const slugPart = (opts.slug ?? defaultSlug(filePath)).replace(/^\/+/, '');
     const key = buildShareKey(username, slugPart);
     const expiresAt = resolveExpire(opts.expire);
-    const unlisted = opts.unlisted === true;
+    const visibility = resolveShareVisibility(opts);
+    const unlisted = visibility === 'unlisted';
     const pageUrl = `${endpoint.baseUrl.replace(/\/+$/, '')}/${key}`;
     const provenance = opts.provenance ?? resolveShareProvenance();
     const meta = opts.meta ?? {};
@@ -449,6 +472,9 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     let body = readFileSync(filePath);
     let coverUrl;
     const isHtml = /\.html?$/i.test(filePath);
+    if (isHtml) {
+        body = Buffer.from(prepareShareHtml(body.toString('utf8'), filePath), 'utf8');
+    }
     const explicitLabel = opts.label?.trim();
     // sanitizeLabel here (not just inside deriveLabel) covers an explicit
     // --label/--title the caller typed with an embedded newline — deriveLabel
@@ -492,8 +518,7 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         const h = { authorization: `Bearer ${endpoint.token}`, 'content-type': contentType };
         if (expiresAt)
             h['x-share-expires-at'] = expiresAt;
-        if (unlisted)
-            h['x-share-visibility'] = 'unlisted';
+        h['x-share-visibility'] = visibility;
         // Every free-text header goes through toHeaderValue: a non-latin1 code point
         // anywhere in a label, a repo name, or a --meta value throws inside fetch and
         // crashes the publish outright.
@@ -541,6 +566,9 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     }
     const r = await put(pageUrl, body, authHeaders(opts.contentType ?? guessContentType(filePath)));
     if (!r.ok) {
+        if (r.status === 409) {
+            throw new Error(`Handle '${username}' is already claimed by another account. The public URL namespace is the email local-part; two Phoenix users cannot share it.`);
+        }
         throw new Error(`Publish failed (${r.status}) for ${pageUrl}. Check the write token, or that 'agents artifacts setup' completed.`);
     }
     return {
@@ -549,6 +577,7 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         coverUrl,
         label,
         labelSource,
+        visibility,
         ...(unlisted ? { unlisted: true } : {}),
     };
 }

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;