@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/lib/session/types.js

@@ -13,6 +13,21 @@ export const SESSION_AGENTS = ['claude', 'codex', 'gemini', 'antigravity', 'open
  * of {@link SESSION_AGENTS}). The single predicate every session-index writer
  * gates on, so "is this a trackable agent?" is decided in exactly one place.
  */
+/**
+ * The tmux session name the CLI mints for an agent run: `ag-<agent>-<shortid>`.
+ *
+ * ONE definition. This shape was independently re-written as a regex literal in
+ * five places (focus's selector test, sessions-resume's direct-selector test,
+ * active's name parsers, actor-sidecar, and the deeplink parser); they drifted —
+ * focus accepted a 6+ hex suffix while the others required exactly 8 — which is
+ * how the same alias could be an "identity" to one code path and a keyword query
+ * to the next.
+ */
+export const AG_TMUX_NAME_RE = /^ag-([a-z][a-z0-9-]*?)-([0-9a-f]{8})$/i;
+/** Whether `name` is an `ag-<agent>-<shortid>` tmux session name. */
+export function isAgentTmuxAlias(name) {
+    return AG_TMUX_NAME_RE.test(name);
+}
 export function isSessionTrackedAgent(agent) {
     return SESSION_AGENTS.includes(agent);
 }

package/dist/lib/session/viewing-in.d.ts

@@ -41,7 +41,7 @@ export interface ViewingIn {
  * BOTH "no client attached" and "could not locate the pane", so the pane's resolved
  * `tmuxTarget` is what separates them: without it there is no evidence of absence,
  * only absence of evidence. Claiming `'detached'` there would invent an orphaned
- * session — and a consumer acts on that claim (Factory's picker pre-ticks every
+ * session — and a consumer acts on that claim (the ext's picker pre-ticks every
  * detached row for rescue), so the wrong answer resumes a session nobody asked for.
  *
  * Shared by the `--active` row renderer and the `--json` serializer so a machine

package/dist/lib/session/viewing-in.js

@@ -40,7 +40,7 @@ const execFileAsync = promisify(execFile);
  * BOTH "no client attached" and "could not locate the pane", so the pane's resolved
  * `tmuxTarget` is what separates them: without it there is no evidence of absence,
  * only absence of evidence. Claiming `'detached'` there would invent an orphaned
- * session — and a consumer acts on that claim (Factory's picker pre-ticks every
+ * session — and a consumer acts on that claim (the ext's picker pre-ticks every
  * detached row for rescue), so the wrong answer resumes a session nobody asked for.
  *
  * Shared by the `--active` row renderer and the `--json` serializer so a machine

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

@@ -0,0 +1,101 @@
+import type { ActiveSession } from './active.js';
+import { readActiveSessionsCache } from './session-cache.js';
+export declare const SESSION_WATCH_VERSION: 1;
+export declare const SESSION_WATCH_HEARTBEAT_MS = 15000;
+export type SessionWatchScopeStatus = 'available' | 'unavailable';
+export type SessionWatchEnvelope = {
+    version: 1;
+    type: 'reset';
+    streamId: string;
+    sequence: number;
+    capturedAt: number;
+    scope: string;
+    rows: SessionWatchRow[];
+} | {
+    version: 1;
+    type: 'upsert';
+    streamId: string;
+    sequence: number;
+    capturedAt: number;
+    scope: string;
+    rowKey: string;
+    row: SessionWatchRow;
+} | {
+    version: 1;
+    type: 'remove';
+    streamId: string;
+    sequence: number;
+    capturedAt: number;
+    scope: string;
+    rowKey: string;
+} | {
+    version: 1;
+    type: 'scope';
+    streamId: string;
+    sequence: number;
+    capturedAt: number;
+    scope: string;
+    status: SessionWatchScopeStatus;
+    reason?: string;
+} | {
+    version: 1;
+    type: 'heartbeat';
+    streamId: string;
+    sequence: number;
+    scope: string;
+    capturedAt: number;
+};
+export interface SessionWatchRow extends Omit<ActiveSession, 'viewingIn'> {
+    rowKey: string;
+    sourceDevice: string;
+    resumable: boolean;
+    unwatched: boolean;
+    viewingIn: string | null;
+    recovery: {
+        command: 'agents';
+        args: string[];
+        cwd?: string;
+    } | null;
+}
+/** Stable, opaque identity for one row within one device scope. */
+export declare function sessionWatchRowKey(scope: string, row: ActiveSession): string;
+export declare function toSessionWatchRow(scope: string, row: ActiveSession): SessionWatchRow;
+/** Stream-local sequencer and convergent row diff. */
+export declare class SessionWatchState {
+    readonly streamId: string;
+    private sequence;
+    private readonly rows;
+    constructor(streamId?: string);
+    private base;
+    reset(scope: string, sourceRows: ActiveSession[]): SessionWatchEnvelope;
+    update(scope: string, sourceRows: ActiveSession[]): SessionWatchEnvelope[];
+    patch(scope: string, upserts: ActiveSession[], removes: string[]): SessionWatchEnvelope[];
+    scope(scope: string, status: SessionWatchScopeStatus, reason?: string): SessionWatchEnvelope;
+    heartbeat(scope: string, capturedAt?: number): SessionWatchEnvelope;
+}
+export interface WatchLocalOptions {
+    scope: string;
+    signal: AbortSignal;
+    emit: (event: SessionWatchEnvelope) => void;
+    refreshMs?: number;
+    heartbeatMs?: number;
+    readCache?: typeof readActiveSessionsCache;
+    journalPath?: string;
+    journalPollMs?: number;
+}
+/**
+ * Keep one local subscription alive. Startup reads one canonical reset snapshot;
+ * steady state tails the canonical writer journal and never invokes a gather.
+ */
+export declare function watchLocalSessions(options: WatchLocalOptions): Promise<void>;
+export interface WatchFleetOptions {
+    signal: AbortSignal;
+    emit: (event: SessionWatchEnvelope) => void;
+    reconnectMs?: number;
+}
+/**
+ * Subscribe to every dialable compute device with one persistent SSH process.
+ * A peer disconnect emits `scope: unavailable` but no removes; reconnecting
+ * peer resets only its own scope. There is no recurring fleet list command.
+ */
+export declare function watchFleetSessions(options: WatchFleetOptions): Promise<void>;

package/dist/lib/session/watch.js

@@ -0,0 +1,242 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { loadDevices, isControlDevice, isDialableDevice } from '../devices/registry.js';
+import { deviceIdentityArgs, sshTargetFor } from '../devices/connect.js';
+import { machineId, normalizeHost } from '../machine-id.js';
+import { SSH_OPTS, controlOpts, shellQuote } from '../ssh-exec.js';
+import { buildWindowsAgentsCommand, remoteShellFor } from '../hosts/remote-cmd.js';
+import { activeSessionsJournalPath, activeSessionJournalIdentity, readActiveSessionsCache, } from './session-cache.js';
+export const SESSION_WATCH_VERSION = 1;
+export const SESSION_WATCH_HEARTBEAT_MS = 15_000;
+/** Stable, opaque identity for one row within one device scope. */
+export function sessionWatchRowKey(scope, row) {
+    const identity = activeSessionJournalIdentity(row);
+    return createHash('sha256').update(`${scope}\0${identity}`).digest('base64url').slice(0, 22);
+}
+export function toSessionWatchRow(scope, row) {
+    const rowKey = sessionWatchRowKey(scope, row);
+    const resumable = Boolean(row.sessionId);
+    const viewingIn = row.viewingIn
+        ? [row.viewingIn.app, row.viewingIn.tab ? `tab ${row.viewingIn.tab}` : undefined].filter(Boolean).join(' ')
+        : null;
+    return {
+        ...row,
+        rowKey,
+        sourceDevice: scope,
+        resumable,
+        unwatched: !viewingIn,
+        viewingIn,
+        recovery: resumable
+            ? { command: 'agents', args: ['sessions', 'resume', row.sessionId, '--device', scope], ...(row.cwd ? { cwd: row.cwd } : {}) }
+            : null,
+    };
+}
+function sameRow(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/** Stream-local sequencer and convergent row diff. */
+export class SessionWatchState {
+    streamId;
+    sequence = 0;
+    rows = new Map();
+    constructor(streamId = randomUUID()) { this.streamId = streamId; }
+    base(type) {
+        return { version: SESSION_WATCH_VERSION, type, streamId: this.streamId, sequence: ++this.sequence, capturedAt: Date.now() };
+    }
+    reset(scope, sourceRows) {
+        const rows = sourceRows.map((row) => toSessionWatchRow(scope, row));
+        this.rows.set(scope, new Map(rows.map((row) => [row.rowKey, row])));
+        return { ...this.base('reset'), scope, rows };
+    }
+    update(scope, sourceRows) {
+        const previous = this.rows.get(scope) ?? new Map();
+        const nextRows = sourceRows.map((row) => toSessionWatchRow(scope, row));
+        const next = new Map(nextRows.map((row) => [row.rowKey, row]));
+        const events = [];
+        for (const [rowKey, row] of next) {
+            if (!previous.has(rowKey) || !sameRow(previous.get(rowKey), row)) {
+                events.push({ ...this.base('upsert'), scope, rowKey, row });
+            }
+        }
+        for (const rowKey of previous.keys()) {
+            if (!next.has(rowKey))
+                events.push({ ...this.base('remove'), scope, rowKey });
+        }
+        this.rows.set(scope, next);
+        return events;
+    }
+    patch(scope, upserts, removes) {
+        const current = new Map(this.rows.get(scope) ?? []);
+        const events = [];
+        for (const source of upserts) {
+            const row = toSessionWatchRow(scope, source);
+            if (!current.has(row.rowKey) || !sameRow(current.get(row.rowKey), row)) {
+                current.set(row.rowKey, row);
+                events.push({ ...this.base('upsert'), scope, rowKey: row.rowKey, row });
+            }
+        }
+        for (const identity of removes) {
+            const rowKey = createHash('sha256').update(`${scope}\0${identity}`).digest('base64url').slice(0, 22);
+            if (current.delete(rowKey))
+                events.push({ ...this.base('remove'), scope, rowKey });
+        }
+        this.rows.set(scope, current);
+        return events;
+    }
+    scope(scope, status, reason) {
+        // Deliberately retain rows while unavailable. A reconnecting scope replaces
+        // them with a reset; transient fleet loss must not look like session death.
+        return { ...this.base('scope'), scope, status, ...(reason ? { reason } : {}) };
+    }
+    heartbeat(scope, capturedAt = Date.now()) {
+        return { ...this.base('heartbeat'), scope, capturedAt };
+    }
+}
+/**
+ * Keep one local subscription alive. Startup reads one canonical reset snapshot;
+ * steady state tails the canonical writer journal and never invokes a gather.
+ */
+export async function watchLocalSessions(options) {
+    const state = new SessionWatchState();
+    const readCache = options.readCache ?? readActiveSessionsCache;
+    const journal = options.journalPath ?? activeSessionsJournalPath();
+    const heartbeatMs = options.heartbeatMs ?? SESSION_WATCH_HEARTBEAT_MS;
+    let offset = 0;
+    try {
+        offset = fs.statSync(journal).size;
+    }
+    catch { /* first publication */ }
+    const initial = readCache('local');
+    options.emit(state.reset(options.scope, initial?.sessions ?? []));
+    options.emit(state.scope(options.scope, initial ? 'available' : 'unavailable', initial ? undefined : 'awaiting publisher'));
+    if (options.signal.aborted)
+        return;
+    await new Promise((resolve) => {
+        let partial = '';
+        let reading = false;
+        const readAppended = () => {
+            if (reading || options.signal.aborted)
+                return;
+            reading = true;
+            try {
+                const size = fs.statSync(journal).size;
+                if (size < offset) {
+                    offset = 0;
+                    partial = '';
+                }
+                if (size === offset)
+                    return;
+                const fd = fs.openSync(journal, 'r');
+                try {
+                    const buffer = Buffer.alloc(size - offset);
+                    fs.readSync(fd, buffer, 0, buffer.length, offset);
+                    offset = size;
+                    const lines = (partial + buffer.toString('utf8')).split('\n');
+                    partial = lines.pop() ?? '';
+                    for (const line of lines) {
+                        if (!line)
+                            continue;
+                        try {
+                            const record = JSON.parse(line);
+                            if (record.version !== 1 || record.scope !== 'local' || !Array.isArray(record.upserts) || !Array.isArray(record.removes))
+                                continue;
+                            for (const event of state.patch(options.scope, record.upserts, record.removes))
+                                options.emit(event);
+                            options.emit(state.scope(options.scope, 'available'));
+                        }
+                        catch { /* partial/corrupt journal lines are not state */ }
+                    }
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+            }
+            catch { /* journal may not exist until the first publisher write */ }
+            finally {
+                reading = false;
+            }
+        };
+        fs.mkdirSync(path.dirname(journal), { recursive: true });
+        const journalListener = () => readAppended();
+        fs.watchFile(journal, { interval: options.journalPollMs ?? 250 }, journalListener);
+        const heartbeatTimer = setInterval(() => options.emit(state.heartbeat(options.scope)), heartbeatMs);
+        const stop = () => { fs.unwatchFile(journal, journalListener); clearInterval(heartbeatTimer); resolve(); };
+        options.signal.addEventListener('abort', stop, { once: true });
+        // Close the offset/read/watch handoff: a publisher may append after the
+        // startup offset is captured but before watchFile is registered.
+        readAppended();
+    });
+}
+function remoteWatchCommand(os) {
+    const args = ['sessions', 'watch', '--json', '--local'];
+    return remoteShellFor(os) === 'powershell'
+        ? buildWindowsAgentsCommand({ args })
+        : `bash -lc ${shellQuote(`agents ${args.map(shellQuote).join(' ')}`)}`;
+}
+/**
+ * Subscribe to every dialable compute device with one persistent SSH process.
+ * A peer disconnect emits `scope: unavailable` but no removes; reconnecting
+ * peer resets only its own scope. There is no recurring fleet list command.
+ */
+export async function watchFleetSessions(options) {
+    const local = watchLocalSessions({ scope: machineId(), signal: options.signal, emit: options.emit });
+    let devices;
+    try {
+        devices = await loadDevices();
+    }
+    catch {
+        await local;
+        return;
+    }
+    const self = machineId();
+    const peers = Object.values(devices).filter((device) => isDialableDevice(device)
+        && !isControlDevice(device)
+        && normalizeHost(device.name) !== self
+        && ['windows', 'linux', 'macos'].includes(device.platform));
+    const reconnectMs = options.reconnectMs ?? 2_000;
+    const peerTasks = peers.map(async (device) => {
+        const scope = normalizeHost(device.name);
+        const state = new SessionWatchState();
+        while (!options.signal.aborted) {
+            let target;
+            try {
+                target = sshTargetFor(device);
+            }
+            catch (error) {
+                options.emit(state.scope(scope, 'unavailable', error instanceof Error ? error.message : String(error)));
+                break;
+            }
+            const child = spawn('ssh', [
+                ...SSH_OPTS, ...controlOpts(), ...deviceIdentityArgs(device), target, remoteWatchCommand(device.platform),
+            ], { stdio: ['ignore', 'pipe', 'ignore'] });
+            const stop = () => child.kill('SIGTERM');
+            options.signal.addEventListener('abort', stop, { once: true });
+            const reader = createInterface({ input: child.stdout });
+            reader.on('line', (line) => {
+                try {
+                    const event = JSON.parse(line);
+                    if (event.version === SESSION_WATCH_VERSION && typeof event.sequence === 'number')
+                        options.emit(event);
+                }
+                catch { /* incomplete/non-protocol peer output is not state */ }
+            });
+            const code = await new Promise((resolve) => {
+                child.once('error', () => resolve(null));
+                child.once('close', resolve);
+            });
+            reader.close();
+            options.signal.removeEventListener('abort', stop);
+            if (options.signal.aborted)
+                break;
+            options.emit(state.scope(scope, 'unavailable', code === null ? 'ssh failed' : `ssh exited ${code}`));
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, reconnectMs);
+                options.signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+            });
+        }
+    });
+    await Promise.all([local, ...peerTasks]);
+}

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

@@ -8,6 +8,10 @@ export interface ShareConfig {
     domain?: string;
     /** Cloudflare Web Analytics token injected into published HTML pages. */
     analyticsToken?: string;
+    /** sha256 of the Worker script deployed at the last provision/update. Absent
+     * on any config written before this field existed — treat that as "unknown",
+     * never as "outdated" (there is nothing to compare against). */
+    templateHash?: string;
 }
 export declare const SHARE_BUNDLE = "share";
 export declare const SHARE_TOKEN_KEY = "WRITE_TOKEN";

package/dist/lib/share/config.js

@@ -35,6 +35,7 @@ export function readShareConfig() {
         bucketName: s.bucketName,
         domain: s.domain,
         analyticsToken: s.analyticsToken,
+        templateHash: s.templateHash,
     };
 }
 /** Persist the endpoint config to `agents.yaml` (syncs across the fleet). */

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

@@ -51,6 +51,44 @@ export declare function mergeShareLifecycleRule(existing?: R2LifecycleRule[], ru
 export declare function configureBucketLifecycle(apiToken: string, accountId: string, bucketName: string, opts?: ProvisionOptions): Promise<void>;
 /** Upload the module Worker with an R2 binding (`BUCKET`). Secrets are set via the Workers Secrets API. */
 export declare function deployWorker(apiToken: string, accountId: string, workerName: string, script: string, bucketName: string, opts?: ProvisionOptions): Promise<void>;
+/** sha256 of the rendered Worker script, so a deployed endpoint can be compared
+ * against the current `worker-template.ts` without redeploying to find out. */
+export declare function hashWorkerScript(script: string): string;
+export interface UpdateWorkerResult {
+    /** sha256 of `script` (the hash the endpoint now matches, whether or not this
+     * call actually redeployed). */
+    templateHash: string;
+    /** True when the upload was skipped because `previousHash` already matched. */
+    skipped: boolean;
+}
+/**
+ * Re-deploy the Worker script against an ALREADY-provisioned endpoint (same
+ * account/worker/bucket `deployWorker` was first called with) and idempotently
+ * no-op when the template hasn't changed.
+ *
+ * Cloudflare's script-upload endpoint (`deployWorker`, above) replaces the
+ * Worker's bindings/secrets wholesale on every call — there is no documented,
+ * reliable way to tell it "keep the existing secret" (the `keep_bindings`
+ * metadata field some third-party guides mention is absent from Cloudflare's
+ * current Multipart upload metadata reference, and the community has reported
+ * it not preventing binding loss even when present:
+ * https://developers.cloudflare.com/workers/configuration/multipart-upload-metadata/,
+ * https://community.cloudflare.com/t/upload-worker-module-endpoint-removes-existing-bindings-despite-keep-bindings/766447).
+ * So instead this immediately re-applies WRITE_TOKEN via the documented Secrets
+ * API right after the upload — the same two-call sequence first-time
+ * provisioning already uses (`deployWorker` then `setWorkerSecret`), except
+ * `writeToken` here is the caller's EXISTING token, never a freshly generated
+ * one. Cloudflare's own docs describe exactly this "secrets survive a
+ * subsequent write" contract for the sibling `wrangler versions upload
+ * --secrets-file` flow ("Secrets not included in the file are preserved from
+ * the previous version" —
+ * https://developers.cloudflare.com/workers/configuration/secrets/#upload-secrets-alongside-code);
+ * re-setting the secret to its own value after every deploy gets the same
+ * outcome without depending on an unverified upload-time flag.
+ */
+export declare function updateWorker(apiToken: string, accountId: string, workerName: string, bucketName: string, script: string, writeToken: string, previousHash: string | undefined, opts?: ProvisionOptions & {
+    force?: boolean;
+}): Promise<UpdateWorkerResult>;
 /** Add/update the WRITE_TOKEN binding using Cloudflare's Workers Secrets API. */
 export declare function setWorkerSecret(apiToken: string, accountId: string, workerName: string, writeToken: string, opts?: ProvisionOptions): Promise<void>;
 /** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */

package/dist/lib/share/provision.js

@@ -3,6 +3,7 @@
 // lifecycle, uploads the Worker (with an R2 binding), sets the WRITE_TOKEN secret,
 // enables the free `*.workers.dev` subdomain, and — when the token owns the zone —
 // maps a custom domain.
+import { createHash } from 'node:crypto';
 const CF_API = 'https://api.cloudflare.com/client/v4';
 export const SHARE_LIFECYCLE_RULE_ID = 'agents-share-expire-objects';
 export const SHARE_LIFECYCLE_RETENTION_DAYS = 366;
@@ -95,6 +96,55 @@ export async function deployWorker(apiToken, accountId, workerName, script, buck
         form,
     });
 }
+/** sha256 of the rendered Worker script, so a deployed endpoint can be compared
+ * against the current `worker-template.ts` without redeploying to find out. */
+export function hashWorkerScript(script) {
+    return createHash('sha256').update(script, 'utf8').digest('hex');
+}
+/**
+ * Re-deploy the Worker script against an ALREADY-provisioned endpoint (same
+ * account/worker/bucket `deployWorker` was first called with) and idempotently
+ * no-op when the template hasn't changed.
+ *
+ * Cloudflare's script-upload endpoint (`deployWorker`, above) replaces the
+ * Worker's bindings/secrets wholesale on every call — there is no documented,
+ * reliable way to tell it "keep the existing secret" (the `keep_bindings`
+ * metadata field some third-party guides mention is absent from Cloudflare's
+ * current Multipart upload metadata reference, and the community has reported
+ * it not preventing binding loss even when present:
+ * https://developers.cloudflare.com/workers/configuration/multipart-upload-metadata/,
+ * https://community.cloudflare.com/t/upload-worker-module-endpoint-removes-existing-bindings-despite-keep-bindings/766447).
+ * So instead this immediately re-applies WRITE_TOKEN via the documented Secrets
+ * API right after the upload — the same two-call sequence first-time
+ * provisioning already uses (`deployWorker` then `setWorkerSecret`), except
+ * `writeToken` here is the caller's EXISTING token, never a freshly generated
+ * one. Cloudflare's own docs describe exactly this "secrets survive a
+ * subsequent write" contract for the sibling `wrangler versions upload
+ * --secrets-file` flow ("Secrets not included in the file are preserved from
+ * the previous version" —
+ * https://developers.cloudflare.com/workers/configuration/secrets/#upload-secrets-alongside-code);
+ * re-setting the secret to its own value after every deploy gets the same
+ * outcome without depending on an unverified upload-time flag.
+ */
+export async function updateWorker(apiToken, accountId, workerName, bucketName, script, writeToken, previousHash, opts = {}) {
+    const templateHash = hashWorkerScript(script);
+    if (!opts.force && previousHash === templateHash) {
+        return { templateHash, skipped: true };
+    }
+    await deployWorker(apiToken, accountId, workerName, script, bucketName, opts);
+    // Script upload clears bindings/secrets (see JSDoc above). If re-applying
+    // WRITE_TOKEN fails here, the live Worker has no write token — every
+    // `agents share` publish/delete 401s until a re-run of `agents share update`
+    // completes both steps. Surface that explicitly instead of the raw CF error.
+    try {
+        await setWorkerSecret(apiToken, accountId, workerName, writeToken, opts);
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        throw new Error(`Worker deployed but the write token failed to re-apply — re-run \`agents share update\` to fix this before publishing/deleting anything. (${detail})`);
+    }
+    return { templateHash, skipped: false };
+}
 /** Add/update the WRITE_TOKEN binding using Cloudflare's Workers Secrets API. */
 export async function setWorkerSecret(apiToken, accountId, workerName, writeToken, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;

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

@@ -10,9 +10,25 @@ export interface PublishEndpoint {
 }
 export interface PublishOptions {
     slug?: string;
-    /** e.g. `30d`, `12h`, or an absolute date like `2026-08-01`. */
+    /**
+     * Auto-expire window. Relative (`30d`, `12h`), absolute (`2026-08-01`), or
+     * `never` / `none` / `permanent` for no expiry. When omitted, publishes default
+     * to {@link DEFAULT_SHARE_EXPIRE} so an accidental share decays instead of
+     * living forever (RUSH-2443).
+     */
     expire?: string;
     contentType?: string;
+    /**
+     * Hide this page from the public `/<user>` gallery and `agents share list`
+     * (metadata `visibility=unlisted`). The direct URL is still world-readable —
+     * unlisted, not secret (RUSH-2443). Alias of `--private` on the CLI.
+     */
+    unlisted?: boolean;
+    /**
+     * Bypass the pre-publish sensitive-content scan (emails / credential-shaped
+     * strings). Required when the page intentionally carries those patterns.
+     */
+    force?: boolean;
     /** Generate + attach an OG cover for HTML pages (default true). */
     cover?: boolean;
     /** Inject the Cloudflare Web Analytics beacon (default true for HTML). */
@@ -34,9 +50,32 @@ export interface PublishResult {
     url: string;
     expiresAt?: string;
     coverUrl?: string;
+    /** True when the page was published with `visibility=unlisted`. */
+    unlisted?: boolean;
 }
+/** 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). */
 export declare function parseExpire(spec: string | undefined): string | undefined;
+/**
+ * Resolve the publish expiry. Omitted → {@link DEFAULT_SHARE_EXPIRE}. Explicit
+ * `never` / `none` / `permanent` → no expiry. Anything else → {@link parseExpire}.
+ */
+export declare function resolveExpire(spec: string | undefined): string | undefined;
+export type SensitiveHitKind = 'email' | 'credential';
+export interface SensitiveHit {
+    kind: SensitiveHitKind;
+    /** Short redacted sample so the error names *what* was found without dumping it. */
+    sample: 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
+ * nothing — the gate is for HTML/text reports, not screenshots.
+ */
+export declare function scanShareContent(body: string | Buffer): SensitiveHit[];
+/** Build the refuse message when the pre-publish scan finds sensitive content. */
+export declare function formatSensitiveContentError(hits: SensitiveHit[]): string;
 /** Derive a URL-safe slug from a filename (or pass one through). */
 export declare function slugify(name: string): string;
 /** The project the file belongs to — git repo name, else the cwd's basename. */