@phnx-labs/agents-cli 1.22.38 → 1.22.40

package/dist/lib/session/remote.js

@@ -1,5 +1,5 @@
 /**
- * `agents sessions --host <target>` — run the session query on a remote machine
+ * `agents sessions --device <target>` — run the session query on a remote machine
  * over SSH and stream its output back. Session transcripts and the index DB live
  * on the machine that produced them (see `discover.ts`, all `os.homedir()`-rooted),
  * so instead of syncing the bytes here we invoke the *remote's own* `agents
@@ -18,7 +18,7 @@
  * banner. The cache is a byproduct of fetches you already made — freely
  * deletable — so the fetch-don't-replicate model holds.
  *
- * Mirrors the transport already used by `agents secrets export --host`
+ * Mirrors the transport already used by `agents secrets export --device`
  * (`src/commands/secrets.ts`): `ssh -o BatchMode=yes <host> bash -lc '<cmd>'`,
  * with `bash -lc` so the remote login PATH resolves `agents`.
  */
@@ -44,11 +44,11 @@ export function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
 /**
- * Strip the `--host`/`-H` flag (and its value) from a raw `agents sessions` argv,
+ * Strip the `--device`/`-D` flag (and its value) from a raw `agents sessions` argv,
  * leaving the args to forward to the remote unchanged. The remote runs the same
  * binary, so every other flag (`--since`, `--last`, `--json`, query, …) carries
- * over for free. Handles every form commander accepts: `--host h`, `--host=h`,
- * `-H h`, `-H=h`, and the glued short form `-Hh`.
+ * over for free. Handles every form commander accepts: `--device h`, `--device=h`,
+ * `-D h`, `-D=h`, and the glued short form `-Dh`.
  *
  * @param argv full process argv; the sessions args begin at index 2
  *             (`[runtime, script, 'sessions', ...]`).
@@ -58,12 +58,10 @@ export function buildForwardedArgs(argv, hosts = new Set()) {
     const out = [];
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
-        if (a === '--host' || a === '-H' || a === '--device' || a === '--devices') {
-            // Commander's `<target...>` variadic accepts both `--host a --host b` and
-            // `--host a b` — consume every consecutive token that is a known host so
-            // the variadic form doesn't leak the extra hosts into the remote argv.
-            // `--device` is an alias for `--host` (its values are merged into the same
-            // host set), so strip it the same way — else the peer would re-fan-out.
+        if (a === '--device' || a === '--devices') {
+            // Commander's `<target...>` variadic accepts both `--device a --device b`
+            // and `--device a b` — consume every consecutive token that is a known host
+            // so the variadic form doesn't leak the extra hosts into the remote argv.
             // Fall back to consuming the single next token when we have no host set
             // (e.g. malformed input) so the flag value never leaks either way.
             if (hosts.size > 0) {
@@ -75,10 +73,8 @@ export function buildForwardedArgs(argv, hosts = new Set()) {
             }
             continue;
         }
-        if (a.startsWith('--host=') || a.startsWith('-H=') || a.startsWith('--device=') || a.startsWith('--devices='))
+        if (a.startsWith('--device=') || a.startsWith('--devices='))
             continue;
-        if (/^-H.+/.test(a))
-            continue; // glued short form: -Hyosemite-s1
         out.push(a);
     }
     return out;
@@ -87,9 +83,9 @@ export function buildForwardedArgs(argv, hosts = new Set()) {
  * Force a forwarded `agents sessions` listing to span the peer's WHOLE index.
  *
  * A remote listing runs in the peer's SSH-login cwd — its home dir — and the
- * default listing is silently cwd-scoped, so `sessions --host box` reads as
+ * default listing is silently cwd-scoped, so `sessions --device box` reads as
  * empty even when the box's index is full (`No sessions found for /home/<user>`).
- * Across SSH a peer's cwd is meaningless, so `--host` defaults to `--all`
+ * Across SSH a peer's cwd is meaningless, so `--device` defaults to `--all`
  * (whole-index) scope. This only drops the *cwd* narrowing — an explicit path
  * query, `--project`, `--since`, or `--agent` filter still narrows on top, and
  * a query that looks like a path takes precedence over `--all` on the remote.
@@ -110,7 +106,7 @@ export function ensureWholeIndex(forwardedArgs) {
  * remote renders its table to the local screen.
  */
 export function buildRemoteCommand(forwardedArgs, columns, os) {
-    // `--host <box>` means "that box's own sessions" — so the peer must answer for
+    // `--device <box>` means "that box's own sessions" — so the peer must answer for
     // ITSELF and not re-sweep its fleet. Without this the remote `agents sessions`
     // fans back out to every device IT knows (including us), printing a spurious
     // `<this-machine>: unreachable`. AGENTS_SESSIONS_LOCAL=1 pins the peer local,

package/dist/lib/session/resume-command.d.ts

@@ -1,6 +1,7 @@
 /**
  * The one public command used by UI and lifecycle consumers to reopen a session.
- * `agents resume` owns identity resolution, source-device routing, version/home
- * selection, and harness-specific continuation; callers must not recreate it.
+ * `agents sessions resume` owns identity resolution, source-device routing,
+ * version/home selection, and harness-specific continuation; callers must not
+ * recreate it.
  */
 export declare function buildCanonicalResumeCommand(sessionId: string): string[];

package/dist/lib/session/resume-command.js

@@ -1,8 +1,9 @@
 /**
  * The one public command used by UI and lifecycle consumers to reopen a session.
- * `agents resume` owns identity resolution, source-device routing, version/home
- * selection, and harness-specific continuation; callers must not recreate it.
+ * `agents sessions resume` owns identity resolution, source-device routing,
+ * version/home selection, and harness-specific continuation; callers must not
+ * recreate it.
  */
 export function buildCanonicalResumeCommand(sessionId) {
-    return ['agents', 'resume', sessionId];
+    return ['agents', 'sessions', 'resume', sessionId];
 }

package/dist/lib/session/resume-owner.d.ts

@@ -20,10 +20,10 @@
  * remote session resumed in whatever directory the user happened to be in.
  *
  * Callers act on the answer differently, and the difference is deliberate:
- * `agents resume` and `agents sessions attach` HOP to the owner over SSH, while
+ * `agents sessions resume` and `agents sessions attach` HOP to the owner over SSH, while
  * `resumeSessionInPlace` — the local takeover every routed caller reaches only
  * after deciding — REFUSES. The batch `sessions resume` needs no check of its
- * own: each of its tabs runs the canonical `agents resume <id>`
+ * own: each of its tabs runs the canonical `agents sessions resume <id>`
  * (lib/session/resume-command.ts), which routes itself.
  */
 import type { SessionMeta } from './types.js';
@@ -41,7 +41,7 @@ import type { SessionMeta } from './types.js';
 export declare const RESUME_PINNED_ENV = "AGENTS_RESUME_PINNED";
 /**
  * Whether this process was handed a resume by its owner-routing hop — read once,
- * then cleared so a nested `agents resume` inside the running agent still routes
+ * then cleared so a nested `agents sessions resume` inside the running agent still routes
  * normally.
  */
 export declare function consumeResumePinned(): boolean;

package/dist/lib/session/resume-owner.js

@@ -20,10 +20,10 @@
  * remote session resumed in whatever directory the user happened to be in.
  *
  * Callers act on the answer differently, and the difference is deliberate:
- * `agents resume` and `agents sessions attach` HOP to the owner over SSH, while
+ * `agents sessions resume` and `agents sessions attach` HOP to the owner over SSH, while
  * `resumeSessionInPlace` — the local takeover every routed caller reaches only
  * after deciding — REFUSES. The batch `sessions resume` needs no check of its
- * own: each of its tabs runs the canonical `agents resume <id>`
+ * own: each of its tabs runs the canonical `agents sessions resume <id>`
  * (lib/session/resume-command.ts), which routes itself.
  */
 import { isSelfHost } from '../devices/self-host.js';
@@ -41,7 +41,7 @@ import { isSelfHost } from '../devices/self-host.js';
 export const RESUME_PINNED_ENV = 'AGENTS_RESUME_PINNED';
 /**
  * Whether this process was handed a resume by its owner-routing hop — read once,
- * then cleared so a nested `agents resume` inside the running agent still routes
+ * then cleared so a nested `agents sessions resume` inside the running agent still routes
  * normally.
  */
 export function consumeResumePinned() {

package/dist/lib/session/session-cache.d.ts

@@ -154,6 +154,10 @@ export interface LoadFleetActiveSessionsOptions {
     gather: () => Promise<{
         sessions: ActiveSession[];
         remoteDeviceCount: number;
+        /** Peer names that went unheard on this gather (RUSH-2507). Undefined when the gather didn't compute it. */
+        remoteSkipped?: string[];
+        /** True when the device list itself could not be loaded — no peer was even attempted. */
+        remoteDiscoveryFailed?: boolean;
     }>;
     readCache?: typeof readActiveSessionsCache;
     writeCache?: typeof writeActiveSessionsCache;
@@ -163,6 +167,14 @@ export interface LoadFleetActiveSessionsResult {
     remoteDeviceCount: number;
     servedFromCache: boolean;
     capturedAt: number;
+    /**
+     * Diagnostics from the gather that produced this result. Only populated on a
+     * live gather (`servedFromCache: false`) — a cache hit serves a prior
+     * snapshot that never persisted these fields, so they read `undefined`
+     * ("not probed this call") rather than falsely claiming a clean fleet.
+     */
+    remoteSkipped?: string[];
+    remoteDiscoveryFailed?: boolean;
 }
 /**
  * Cache-first load of the fleet-wide active set. A prior gather (or any surface

package/dist/lib/session/session-cache.js

@@ -442,6 +442,8 @@ export async function loadFleetActiveSessions(opts) {
         remoteDeviceCount: live.remoteDeviceCount,
         servedFromCache: false,
         capturedAt: snap.capturedAt,
+        remoteSkipped: live.remoteSkipped,
+        remoteDiscoveryFailed: live.remoteDiscoveryFailed,
     };
 }
 /**

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/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,68 @@ 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;
+/**
+ * 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). */