@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/lib/session/shell-programs.js

@@ -4,7 +4,7 @@ const SHELL_WRAPPERS = new Set(['bash', 'sh', 'zsh', 'dash', 'ksh']);
 const PROGRAM_WRAPPERS = new Set(['command', 'builtin', 'env', 'nohup', 'sudo']);
 const MAX_NESTED_DEPTH = 3;
 const SUDO_OPTIONS_WITH_VALUE = new Set([
-    '-C', '--close-from', '-D', '--chdir', '-g', '--group', '-h', '--host',
+    '-C', '--close-from', '-D', '--chdir', '-g', '--group', '-h', '--device',
     '-p', '--prompt', '-R', '--chroot', '-r', '--role', '-t', '--type',
     '-T', '--command-timeout', '-u', '--user',
 ]);

package/dist/lib/session/state.js

@@ -208,15 +208,15 @@ const GH_ISSUE_URL_RE = /https:\/\/github\.com\/[^\s"'()<>]+\/issues\/(\d+)/;
  * Flags of `teams create` / `teams add` that take a value, so the value is not
  * mistaken for the positional team name. Mirrors their value-taking flags in
  * `commands/teams.ts` — most are `.option('… <x>')` registrations, but
- * `--device`/`--host` come from `addHostOption`, so auditing this list against
- * `.option(` alone would wrongly drop them. A flag missing here degrades to "no
+ * `--device` comes from `addHostOption`, so auditing this list against
+ * `.option(` alone would wrongly drop it. A flag missing here degrades to "no
  * team detected", never to a wrong one.
  */
 const TEAM_VALUE_FLAGS = [
     '-d', '--description', '--use-worktree', '--devices', '--hosts', '--repo',
     '-n', '--name', '-m', '--mode', '-e', '--effort', '--model', '--env',
     '--cwd', '--worktree', '--after', '--task-type', '--cloud', '--branch',
-    '--device', '--host',
+    '--device',
 ];
 /**
  * One flag value: a quoted string or a bare token. `-d "sessions lineage"` is the
@@ -319,11 +319,11 @@ export function detectSpawnedTeam(command) {
     if (!m)
         return undefined;
     const name = m[1];
-    // A single character is a doc placeholder (`agents teams create t --host <box>`)
+    // A single character is a doc placeholder (`agents teams create t --device <box>`)
     // far more often than a real team, and an English article is prose. Both used to
     // land in the index as a team name, and now that the name is rendered on the row
     // a wrong one is worse than none.
-    // A single character is a doc placeholder (`agents teams create t --host <name>`)
+    // A single character is a doc placeholder (`agents teams create t --device <name>`)
     // far more often than a real team; an all-digits token is a flag value or a list
     // index that leaked through, never a name someone typed. Both had reached the
     // index, and now that the name is rendered a wrong one is worse than none.

package/dist/lib/session/team-filter.d.ts

@@ -69,7 +69,7 @@ export declare function filterTeamSessions(sessions: SessionMeta[], showTeams: b
  * record backs the origin ({@link TeamOrigin.source} === `'meta'`).
  *
  * `source` is newer than the rest of {@link TeamOrigin}, so a row that arrived
- * from a pre-`source` peer over the `--host` fan-out carries none. There the
+ * from a pre-`source` peer over the `--device` fan-out carries none. There the
  * meta-only fields settle it: the entrypoint fallback is a bare `{ handle }`, so
  * any `team` / `mode` / `parentSessionId` / `startedAt` means a real teammate
  * record produced it — otherwise a genuine teammate from an unupgraded peer

package/dist/lib/session/team-filter.js

@@ -184,7 +184,7 @@ export function filterTeamSessions(sessions, showTeams) {
  * record backs the origin ({@link TeamOrigin.source} === `'meta'`).
  *
  * `source` is newer than the rest of {@link TeamOrigin}, so a row that arrived
- * from a pre-`source` peer over the `--host` fan-out carries none. There the
+ * from a pre-`source` peer over the `--device` fan-out carries none. There the
  * meta-only fields settle it: the entrypoint fallback is a bare `{ handle }`, so
  * any `team` / `mode` / `parentSessionId` / `startedAt` means a real teammate
  * record produced it — otherwise a genuine teammate from an unupgraded peer

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

@@ -173,11 +173,11 @@ export interface SessionMeta {
     gitBranch?: string;
     messageCount?: number;
     tokenCount?: number;
-    /** Real generated (output) tokens — excludes cache-read/-write context (issue: `agents output`). */
+    /** Real generated (output) tokens — excludes cache-read/-write context (issue: `agents insights output`). */
     outputTokens?: number;
     /**
      * Uncached input tokens, cache-read tokens, and cache-write (cache-creation)
-     * tokens — the burn split `agents output` reports, kept only for harnesses that
+     * tokens — the burn split `agents insights output` reports, kept only for harnesses that
      * record a per-message cache split (Claude/Codex/Gemini/Droid). Undefined for
      * harnesses that expose no split (RUSH-2287).
      */
@@ -188,7 +188,7 @@ export interface SessionMeta {
     costUsd?: number;
     /**
      * USD cost priced as if caching were off — cache read/write billed at the full
-     * input rate. Backs `agents output --pricing no-cache` (RUSH-2287). Undefined
+     * input rate. Backs `agents insights output --pricing no-cache` (RUSH-2287). Undefined
      * when the harness records no cache split (then no-cache == actual by definition).
      */
     costUsdNoCache?: number;

package/dist/lib/session/width.d.ts

@@ -4,7 +4,7 @@
  * `String.length` is the wrong ruler for a terminal: it over-counts ANSI colour
  * escapes (chalk output) and under-counts wide glyphs (CJK, emoji) which occupy
  * two cells. The result is the drifting, wrapping session-table line users see
- * under tmux and over `--host` SSH. Every renderer that sizes a session-table
+ * under tmux and over `--device` SSH. Every renderer that sizes a session-table
  * cell measures and truncates through this module so alignment is computed once,
  * correctly, from the same source of truth.
  */
@@ -22,7 +22,7 @@ export declare function truncateToWidth(s: string, max: number): string;
 export declare function padToWidth(s: string, width: number): string;
 /**
  * Effective terminal width. Reads `$COLUMNS` first so it survives tmux and
- * `--host` SSH (where `process.stdout.columns` is unset or wrong), falls back to
+ * `--device` SSH (where `process.stdout.columns` is unset or wrong), falls back to
  * the TTY's reported width, then to `fallback`. Clamped to a sane band so a
  * bogus value can't produce a 0-wide or absurdly long table.
  */

package/dist/lib/session/width.js

@@ -4,7 +4,7 @@
  * `String.length` is the wrong ruler for a terminal: it over-counts ANSI colour
  * escapes (chalk output) and under-counts wide glyphs (CJK, emoji) which occupy
  * two cells. The result is the drifting, wrapping session-table line users see
- * under tmux and over `--host` SSH. Every renderer that sizes a session-table
+ * under tmux and over `--device` SSH. Every renderer that sizes a session-table
  * cell measures and truncates through this module so alignment is computed once,
  * correctly, from the same source of truth.
  */
@@ -88,7 +88,7 @@ export function padToWidth(s, width) {
 }
 /**
  * Effective terminal width. Reads `$COLUMNS` first so it survives tmux and
- * `--host` SSH (where `process.stdout.columns` is unset or wrong), falls back to
+ * `--device` SSH (where `process.stdout.columns` is unset or wrong), falls back to
  * the TTY's reported width, then to `fallback`. Clamped to a sane band so a
  * bogus value can't produce a 0-wide or absurdly long table.
  */

package/dist/lib/settings-manifest.d.ts

@@ -13,6 +13,8 @@
  * version home. It never overwrites a value the target already has: scalars
  * keep the target's value, objects merge recursively, arrays union. That makes
  * the operation idempotent and safe to run on every `agents add` / `agents use`.
+ * (One scoped exception: the 'claude-trust' strategy promotes a stamped-default
+ * `hasTrustDialogAccepted: false` to `true` — see the note on that entry.)
  */
 import type { AgentId } from './types.js';
 export interface CarryForwardResult {

package/dist/lib/settings-manifest.js

@@ -13,16 +13,26 @@
  * version home. It never overwrites a value the target already has: scalars
  * keep the target's value, objects merge recursively, arrays union. That makes
  * the operation idempotent and safe to run on every `agents add` / `agents use`.
+ * (One scoped exception: the 'claude-trust' strategy promotes a stamped-default
+ * `hasTrustDialogAccepted: false` to `true` — see the note on that entry.)
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as TOML from 'smol-toml';
+import { atomicWriteFileSync } from './fs-atomic.js';
 import { getBackupsDir } from './state.js';
 const SETTINGS_MANIFEST = {
     claude: [
         { rel: '.claude/settings.json', strategy: 'json-merge' },
         { rel: '.claude/settings.local.json', strategy: 'copy-if-absent' },
         { rel: '.claude/keybindings.json', strategy: 'copy-if-absent' },
+        // `.claude.json` holds the login (oauthAccount) and per-session stats, so it
+        // must never merge wholesale — but it is also where Claude records workspace
+        // trust (`projects[<path>].hasTrustDialogAccepted`). Without carrying that,
+        // every newly pinned version re-shows the trust dialog once per project
+        // (issue #2776). The 'claude-trust' strategy projects ONLY the trust flags
+        // out of the source file; credentials and stats stay per-version.
+        { rel: '.claude.json', strategy: 'claude-trust' },
     ],
     codex: [
         {
@@ -33,9 +43,10 @@ const SETTINGS_MANIFEST = {
         // `.codex/auth.json` is deliberately NOT carried forward. Copying it seeded
         // every new Codex version with the current default's ChatGPT token, so two
         // installed versions always reported the same account and could never sign
-        // into separate accounts. Claude omits its credential (`.claude.json`) for
-        // the same reason — a version home holds its own login, keeping accounts
-        // per-version. A fresh Codex version installs signed-out; run `codex login`
+        // into separate accounts. Claude never merges `.claude.json` for the same
+        // reason (its 'claude-trust' entry extracts only the trust flags) — a
+        // version home holds its own login, keeping accounts per-version. A fresh
+        // Codex version installs signed-out; run `codex login`
         // (or `agents run codex --version <v>`) inside it to authenticate.
         { rel: '.codex/instructions.md', strategy: 'copy-if-absent' },
         { rel: '.codex/hooks.json', strategy: 'copy-if-absent' },
@@ -70,6 +81,21 @@ export function fillGaps(target, source) {
     }
     return out;
 }
+/**
+ * Project paths the source `.claude.json` records an accepted trust dialog for.
+ * Only an explicit `true` counts: Claude Code never persists a decline (the
+ * dialog exits without writing), so `false` is only ever the stamped default —
+ * not a user decision worth propagating. Verified against Claude Code
+ * 2.1.219/2.1.220 (decline paths exit via code 1 / code 0 without a config
+ * write); if a future Claude Code starts persisting declines, this premise —
+ * and the false→true promotion in the 'claude-trust' case — must be revisited.
+ */
+function trustedClaudeProjects(source) {
+    const projects = isPlainObject(source.projects) ? source.projects : {};
+    return Object.entries(projects)
+        .filter(([, project]) => isPlainObject(project) && project.hasTrustDialogAccepted === true)
+        .map(([projectPath]) => projectPath);
+}
 function stripStateKeys(obj, stateKeys) {
     if (!stateKeys?.length)
         return obj;
@@ -128,6 +154,58 @@ export function carryForwardSettings(agent, fromHome, toHome) {
                         result.applied.push(entry.rel);
                     break;
                 }
+                case 'claude-trust': {
+                    // Projection, not a merge: pull ONLY `projects[<path>].hasTrustDialogAccepted`
+                    // out of the source `.claude.json`. Everything else in that file
+                    // (oauthAccount, onboarding state, per-session stats) stays per-version.
+                    // Trust granted anywhere wins over the target's stamped-default `false`
+                    // (headless runs create project entries with the flag unset-as-false
+                    // without ever showing the dialog), but a target entry's other keys
+                    // are preserved untouched.
+                    const source = JSON.parse(fs.readFileSync(sourcePath, 'utf-8'));
+                    const trusted = trustedClaudeProjects(source);
+                    if (trusted.length === 0)
+                        break;
+                    const targetExists = fs.existsSync(targetPath);
+                    const parsedTarget = targetExists
+                        ? JSON.parse(fs.readFileSync(targetPath, 'utf-8'))
+                        : {};
+                    // A target that isn't an object (or whose `projects` isn't) is not
+                    // ours to repair — skip rather than clobber it with a rebuilt shape.
+                    if (!isPlainObject(parsedTarget))
+                        break;
+                    const targetObj = parsedTarget;
+                    if ('projects' in targetObj && !isPlainObject(targetObj.projects))
+                        break;
+                    const targetProjects = isPlainObject(targetObj.projects) ? { ...targetObj.projects } : {};
+                    let changed = false;
+                    for (const projectPath of trusted) {
+                        const existing = isPlainObject(targetProjects[projectPath])
+                            ? targetProjects[projectPath]
+                            : {};
+                        if (existing.hasTrustDialogAccepted === true)
+                            continue;
+                        targetProjects[projectPath] = { ...existing, hasTrustDialogAccepted: true };
+                        changed = true;
+                    }
+                    if (!changed)
+                        break;
+                    if (targetExists) {
+                        backupFile(backupRoot, toHome, entry.rel);
+                        result.backupDir = backupRoot;
+                    }
+                    else {
+                        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+                    }
+                    // Atomic (tmp + rename): a running Claude session rewrites this exact
+                    // file (it holds the login and session stats), so a plain write risks
+                    // a reader seeing a partial file. The OUTSIDE `.claude.json` is the
+                    // real file (the INSIDE `.claude/.claude.json` symlink resolves to it
+                    // and survives the rename).
+                    atomicWriteFileSync(targetPath, JSON.stringify({ ...targetObj, projects: targetProjects }, null, 2) + '\n');
+                    result.applied.push(entry.rel);
+                    break;
+                }
                 case 'json-merge':
                 case 'toml-merge': {
                     const parse = entry.strategy === 'json-merge'

package/dist/lib/share/delete.d.ts

@@ -8,6 +8,12 @@ export type DeleteFn = (url: string, headers: Record<string, string>) => Promise
 export type CheckFn = (url: string) => Promise<{
     status: number;
 }>;
+/** DI seam for tests — override the real HTTP GET of the revisions listing route. */
+export type RevisionsFetchFn = (url: string) => Promise<{
+    status: number;
+    contentType: string;
+    body: string;
+}>;
 export interface DeleteEndpoint {
     baseUrl: string;
     token: string;
@@ -59,6 +65,11 @@ export declare function deleteObject(endpoint: DeleteEndpoint, key: string, opts
 export interface DeleteShareOptions {
     /** Skip deleting the sibling `<slug>.png` OG cover (default: delete it too). */
     keepCover?: boolean;
+    /** Skip deleting the target's retained revisions (`<key>/rev-*`, RUSH-2683
+     * revision retention) — default: delete them too. A republished-then-deleted
+     * share would otherwise leave its prior world-readable versions live for up
+     * to the bucket's lifecycle max-age (see docs/share.md §Revisions). */
+    keepRevisions?: boolean;
     /** Treat an already-missing target as a no-op success instead of an error
      * (mirrors SQL's `DROP ... IF EXISTS`). Default: missing target is an error. */
     ifExists?: boolean;
@@ -72,6 +83,8 @@ export interface DeleteShareOptions {
     deleter?: DeleteFn;
     /** DI seam for tests — override the real HTTP existence check. */
     checker?: CheckFn;
+    /** DI seam for tests — override the real HTTP GET of the revisions listing route. */
+    fetchRevisions?: RevisionsFetchFn;
 }
 export interface DeleteShareResult {
     key: string;
@@ -86,6 +99,14 @@ export interface DeleteShareResult {
         existedBefore: boolean;
         verified404: boolean;
     };
+    /** Retained revisions of this target that were also deleted (omitted when
+     * there were none, or `keepRevisions` was passed). */
+    revisions?: Array<{
+        key: string;
+        url: string;
+        existedBefore: boolean;
+        verified404: boolean;
+    }>;
 }
 /** Delete one share target (page + by default its OG cover) and verify both
  * are gone. Throws on an unverified takedown — never reports success for an

package/dist/lib/share/delete.js

@@ -61,6 +61,33 @@ async function defaultDelete(url, headers) {
     const res = await fetch(url, { method: 'DELETE', headers });
     return { ok: res.ok, status: res.status };
 }
+async function defaultRevisionsFetch(url) {
+    const res = await fetch(url, { headers: { accept: 'application/json' } });
+    return { status: res.status, contentType: res.headers.get('content-type') ?? '', body: await res.text() };
+}
+/**
+ * List the R2 keys of a slug's retained revisions via the Worker's
+ * `?revisions=json` route (worker-template.ts `renderRevisions`). Best-effort:
+ * any failure to reach or parse the route (an endpoint provisioned before
+ * revisions existed, a network blip) yields an empty list rather than
+ * throwing — purging revisions is a safety improvement on top of the primary
+ * delete contract (take the canonical page down), never a reason to fail it.
+ */
+async function listRevisionKeys(endpoint, key, fetchRevisions) {
+    try {
+        const url = `${endpoint.baseUrl.replace(/\/+$/, '')}/${key}?revisions=json`;
+        const res = await fetchRevisions(url);
+        if (res.status !== 200 || !/application\/json/i.test(res.contentType))
+            return [];
+        const data = JSON.parse(res.body);
+        if (!Array.isArray(data.revisions))
+            return [];
+        return data.revisions.map((r) => String(r.key ?? '')).filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * Delete one R2 object behind the share Worker and assert the postcondition.
  * `{"ok":true}` from the Worker is not evidence a page came down — R2 delete is
@@ -123,5 +150,20 @@ export async function deleteShare(target, opts = {}) {
             throw new Error(`Cover delete reported success but ${cover.url} still resolves — takedown NOT verified. Retry, or pass --keep-cover and delete it manually.`);
         }
     }
+    if (!opts.keepRevisions) {
+        const revisionKeys = await listRevisionKeys(endpoint, resolved.key, opts.fetchRevisions ?? defaultRevisionsFetch);
+        if (revisionKeys.length > 0) {
+            const revisions = [];
+            for (const revisionKey of revisionKeys) {
+                const rev = await deleteObject(endpoint, revisionKey, { deleter: opts.deleter, checker: opts.checker });
+                revisions.push({ key: rev.key, url: rev.url, existedBefore: rev.existedBefore, verified404: rev.verified404 });
+            }
+            result.revisions = revisions;
+            const stillUp = revisions.filter((r) => r.existedBefore && !r.verified404);
+            if (stillUp.length > 0) {
+                throw new Error(`Delete reported success but ${stillUp.length} retained revision(s) still resolve — takedown NOT verified. Retry, or pass --keep-revisions and delete them manually.`);
+            }
+        }
+    }
     return result;
 }

package/dist/lib/share/publish.d.ts

@@ -45,6 +45,27 @@ export interface PublishOptions {
     uploader?: PutFn;
     /** DI seam for tests — override cover capture (returns a PNG buffer or null). */
     capturer?: (htmlPath: string) => Promise<Buffer | null>;
+    /**
+     * Human display title, shown instead of the slug in the gallery and
+     * `agents artifacts share list`. When omitted, one is derived (HTML `<title>`,
+     * else a Markdown frontmatter `title:`, else the filename) — a share always
+     * carries a label, never a blocking prompt (see {@link deriveLabel}).
+     */
+    label?: string;
+    /**
+     * Structured metadata (`--meta key=value`, repeatable). Keys are validated by
+     * {@link parseMetaEntries} — lowercase `[a-z0-9-]`, and may not collide with
+     * {@link RESERVED_META_KEYS}, which the CLI sets automatically.
+     */
+    meta?: Record<string, string>;
+    /**
+     * Skip revision retention on this publish — overwrite an existing slug's
+     * object in place with no `<slug>/rev-<ts>` backup of the version it replaces
+     * (default: keep it; see docs/share.md §Revisions).
+     */
+    noRevision?: boolean;
+    /** DI seam for tests — override provenance auto-capture (agent/session/host/repo/date). */
+    provenance?: ShareProvenance;
 }
 export interface PublishResult {
     url: string;
@@ -52,7 +73,87 @@ export interface PublishResult {
     coverUrl?: string;
     /** True when the page was published with `visibility=unlisted`. */
     unlisted?: boolean;
+    /** The label stored with this share — explicit (`--label`) or derived. */
+    label?: string;
+    /** Whether `label` came from `--label` or was auto-derived. */
+    labelSource?: 'explicit' | 'derived';
+}
+export interface ShareProvenance {
+    /** Harness/agent name (`AGENTS_AGENT_NAME`), when publishing from an agent run. */
+    agent?: string;
+    /** Session id (`AGENTS_SESSION_ID` / `AGENT_SESSION_ID`), when publishing from an agent run. */
+    session?: string;
+    /** The machine the publish ran from (`os.hostname()`) — always present. */
+    host?: string;
+    /** git repo name at publish time, absent outside a git checkout — never invented. */
+    repo?: string;
+    /** ISO date (`yyyy-mm-dd`) this publish happened, from the local clock. */
+    date?: string;
 }
+/**
+ * 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}).
+ */
+export declare const RESERVED_META_KEYS: readonly ["agent", "session", "host", "repo", "date", "label", "label-source"];
+/**
+ * Auto-capture publish provenance from the exec env, git, and the local clock.
+ * Every field is present only when the environment genuinely carries it — a
+ * human running the command by hand outside a git repo yields `session`/`agent`/
+ * `repo` all undefined, never an invented value. `host` is always present
+ * (`os.hostname()` never fails to return something real about where the publish
+ * ran, so it isn't "invented" in the same sense).
+ */
+export declare function resolveShareProvenance(opts?: {
+    env?: NodeJS.ProcessEnv;
+    hostname?: string;
+    dir?: string;
+    now?: Date;
+}): ShareProvenance;
+/**
+ * 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.
+ */
+export declare function parseMetaEntries(pairs: string[]): Record<string, string>;
+/** Throws when the combined `customMetadata` payload would exceed {@link MAX_METADATA_BYTES}. */
+export declare function assertMetadataSize(customMetadata: Record<string, string>): void;
+/**
+ * Collapse a label to a single line before it goes into the `x-share-label`
+ * header or public customMetadata. `<title>[^<]{1,200}</title>` matches
+ * newlines (`[^<]` excludes only `<`), and `.trim()` only strips leading/
+ * trailing whitespace, not embedded newlines — a multi-line `<title>` (or an
+ * explicit `--label`/`--title` the caller typed with a literal newline) was
+ * previously passed straight into `Headers.set()` unsanitized, which throws
+ * an unhandled `TypeError: Invalid value` and crashes the publish outright.
+ */
+export declare function sanitizeLabel(text: string): string;
+/**
+ * Make a free-text value safe to put in an HTTP header.
+ *
+ * `fetch` encodes header values as a **ByteString**, so any code point above 255
+ * throws `TypeError: Cannot convert argument to a ByteString` — an unhandled
+ * crash with a stack trace, mid-publish, after the body has already been read.
+ * Reproduced by publishing a session whose title ended in `…` (U+2026), and
+ * reachable by any emoji, curly quote, accented name, or CJK text in a `--label`,
+ * a `--meta` value, or a repo name.
+ *
+ * The transliterations above cover what actually shows up; anything else outside
+ * latin1 is dropped, and a value that transliterates to nothing at all (a title
+ * written entirely in a non-latin script) degrades to a marker rather than an
+ * empty header. Lossy on purpose: carrying full Unicode needs percent-encoding
+ * here AND a matching decode in the Worker, which every already-deployed Worker
+ * would render as `%E2%80%A6` until its operator ran `agents artifacts share
+ * update` — tracked as RUSH-2786.
+ */
+export declare function toHeaderValue(text: string): string;
+/**
+ * Best-effort human title when `--label` is omitted: the HTML `<title>`, else a
+ * Markdown frontmatter `title:`, else the filename. Always returns something —
+ * a headless publish must never hang waiting on a prompt for one.
+ */
+export declare function deriveLabel(filePath: string, body: Buffer): string;
 /** Default auto-expire for unflagged publishes — accidental links decay (RUSH-2443). */
 export declare const DEFAULT_SHARE_EXPIRE = "30d";
 /** `30d` / `12h` / `2026-08-01` → an absolute ISO timestamp (or undefined). */
@@ -68,6 +169,25 @@ export interface SensitiveHit {
     /** Short redacted sample so the error names *what* was found without dumping it. */
     sample: string;
 }
+/**
+ * Mask every email address in `text`, so a page can be published without tripping
+ * {@link scanShareContent}.
+ *
+ * Lives here, beside the scanner, rather than in `lib/redact.ts`: it exists solely
+ * to satisfy this gate, and sharing {@link EMAIL_RE} is what makes the masking
+ * *sufficient* to clear it rather than merely reducing the hit count. Two copies of
+ * the pattern in two modules would drift, and the failure mode of that drift is a
+ * refused publish at runtime.
+ *
+ * Deliberately NOT part of `redactSecrets`: an email is not a credential, and a
+ * transcript rendered for a private gist or local review reads better with the real
+ * author addresses intact. It only becomes a leak once the text is PUBLISHED — a
+ * world-readable page carrying seven of them is the RUSH-2428 incident.
+ *
+ * The whole address goes, domain included — a personal domain identifies its owner
+ * as surely as the local part does, and keeping it would buy the reader nothing.
+ */
+export declare function redactEmails(text: string): string;
 /**
  * Scan a text body for email addresses and credential-shaped strings. Returns
  * the first few hits (deduped by kind+sample). Binary / non-text bodies yield