@phnx-labs/agents-cli 1.20.64 → 1.20.66

package/dist/lib/serve/token.d.ts

@@ -0,0 +1,35 @@
+/** One issued token, stored by hash only. */
+export interface ControlTokenRecord {
+    /** Short public id for display / revocation (not secret). */
+    id: string;
+    /** SHA-256 hex of the raw token. */
+    hash: string;
+    /** Human label, e.g. "muqsit-iphone". */
+    label: string;
+    createdAt: string;
+}
+/**
+ * Mint a new control token, persist its hash, and return the raw token ONCE.
+ * The caller must surface it to the operator immediately — it cannot be
+ * recovered later.
+ */
+export declare function addControlToken(label: string): {
+    id: string;
+    token: string;
+};
+/**
+ * Ensure at least one token exists. Returns the raw token only when it had to
+ * mint one (first `--control` boot); otherwise `{ created: false }` and the
+ * existing tokens stand.
+ */
+export declare function ensureControlToken(label?: string): {
+    created: true;
+    id: string;
+    token: string;
+} | {
+    created: false;
+};
+/** True when `presented` matches a stored token hash (constant-time compare). */
+export declare function verifyControlToken(presented: string | undefined): boolean;
+/** List issued tokens (hashes only — safe to display). */
+export declare function listControlTokens(): ControlTokenRecord[];

package/dist/lib/serve/token.js

@@ -0,0 +1,85 @@
+/**
+ * Bearer-token store for the authenticated `agents serve --control` server.
+ *
+ * Only the SHA-256 *hash* of each token is written to disk — the raw token is
+ * shown once at creation (like an API key) and never persisted, so a leaked
+ * store file cannot be replayed. This is the anchor-side credential the iOS
+ * cockpit presents on every request; `agents devices pair-ios` (Phase 3) mints
+ * additional per-device tokens through {@link addControlToken}.
+ *
+ * Store path: `<cache>/serve/control-tokens.json` — under `.cache/`, which is
+ * gitignored, so no credential material lands in a version-controlled repo.
+ */
+import fs from 'fs';
+import path from 'path';
+import { createHash, randomBytes, timingSafeEqual } from 'crypto';
+import { getCacheDir } from '../state.js';
+function storePath() {
+    return path.join(getCacheDir(), 'serve', 'control-tokens.json');
+}
+function readStore() {
+    try {
+        const raw = fs.readFileSync(storePath(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && Array.isArray(parsed.tokens))
+            return parsed;
+    }
+    catch {
+        // Missing/corrupt store → start empty; a fresh token gets minted below.
+    }
+    return { tokens: [] };
+}
+function writeStore(store) {
+    const p = storePath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    // 0600: readable only by the owner — it holds token hashes. `mode` on
+    // writeFileSync is honored only at *creation*, so chmod every write to
+    // self-heal if the perms were ever widened externally (this is a credential
+    // file, even if only hashes).
+    fs.writeFileSync(p, JSON.stringify(store, null, 2), { mode: 0o600 });
+    fs.chmodSync(p, 0o600);
+}
+function sha256(s) {
+    return createHash('sha256').update(s).digest('hex');
+}
+/**
+ * Mint a new control token, persist its hash, and return the raw token ONCE.
+ * The caller must surface it to the operator immediately — it cannot be
+ * recovered later.
+ */
+export function addControlToken(label) {
+    const store = readStore();
+    const id = randomBytes(4).toString('hex');
+    const token = randomBytes(32).toString('hex');
+    store.tokens.push({ id, hash: sha256(token), label, createdAt: new Date().toISOString() });
+    writeStore(store);
+    return { id, token };
+}
+/**
+ * Ensure at least one token exists. Returns the raw token only when it had to
+ * mint one (first `--control` boot); otherwise `{ created: false }` and the
+ * existing tokens stand.
+ */
+export function ensureControlToken(label = 'default') {
+    const store = readStore();
+    if (store.tokens.length > 0)
+        return { created: false };
+    const { id, token } = addControlToken(label);
+    return { created: true, id, token };
+}
+/** True when `presented` matches a stored token hash (constant-time compare). */
+export function verifyControlToken(presented) {
+    if (!presented)
+        return false;
+    const want = Buffer.from(sha256(presented), 'hex');
+    for (const rec of readStore().tokens) {
+        const have = Buffer.from(rec.hash, 'hex');
+        if (have.length === want.length && timingSafeEqual(have, want))
+            return true;
+    }
+    return false;
+}
+/** List issued tokens (hashes only — safe to display). */
+export function listControlTokens() {
+    return readStore().tokens;
+}

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

@@ -76,6 +76,12 @@ export interface BuildRecordOpts {
     redact: boolean;
     /** Non-null → seal each body with this key; null → plaintext bodies. */
     encryptKey: Buffer | null;
+    /**
+     * Literal secret values to mask verbatim during redaction (value-aware pass):
+     * e.g. live credentials from an injected secrets bundle, so they never leak in
+     * an exported transcript regardless of format. Only used when `redact` is set.
+     */
+    knownSecrets?: readonly string[];
 }
 /** Look up the sync spec for an agent id (undefined → agent not sync-representable). */
 export declare function specForAgent(agentId: string): SyncAgentSpec | undefined;
@@ -104,6 +110,14 @@ export declare function makeHeader(args: {
 export declare function mergeRecords(sets: BundleRecord[][]): BundleRecord[];
 /** Serialize a bundle to its NDJSON wire form (header line + one line per record). */
 export declare function serializeBundle(header: BundleHeader, records: BundleRecord[]): string;
+/**
+ * Write a serialized bundle to disk owner-only (0600). A bundle carries raw
+ * transcript bodies — even redacted, never world/group-readable — and encryption
+ * is opt-in, so the file mode is the baseline confidentiality guard. `mode` on
+ * `writeFileSync` only applies when the file is created, so we `chmod` too to
+ * clamp an existing (possibly looser) file on overwrite.
+ */
+export declare function writeBundleFile(outPath: string, wire: string): void;
 /** Parse an NDJSON bundle, validating the header kind + version. Throws on malformed input. */
 export declare function parseBundle(text: string): ParsedBundle;
 /** Placement outcome for one record, computed against what is already on disk. */

package/dist/lib/session/bundle.js

@@ -42,7 +42,7 @@ export function isExportableAgent(agentId) {
 export function buildRecord(file, opts) {
     let body = fs.readFileSync(file.absPath, 'utf-8');
     if (opts.redact)
-        body = redactSecrets(body);
+        body = redactSecrets(body, opts.knownSecrets);
     const hash = hashContent(body);
     const size = Buffer.byteLength(body, 'utf-8');
     let stored = body;
@@ -105,6 +105,17 @@ export function serializeBundle(header, records) {
         lines.push(JSON.stringify(r));
     return lines.join('\n') + '\n';
 }
+/**
+ * Write a serialized bundle to disk owner-only (0600). A bundle carries raw
+ * transcript bodies — even redacted, never world/group-readable — and encryption
+ * is opt-in, so the file mode is the baseline confidentiality guard. `mode` on
+ * `writeFileSync` only applies when the file is created, so we `chmod` too to
+ * clamp an existing (possibly looser) file on overwrite.
+ */
+export function writeBundleFile(outPath, wire) {
+    fs.writeFileSync(outPath, wire, { encoding: 'utf-8', mode: 0o600 });
+    fs.chmodSync(outPath, 0o600);
+}
 /** Parse an NDJSON bundle, validating the header kind + version. Throws on malformed input. */
 export function parseBundle(text) {
     const lines = text.split('\n').filter(l => l.trim().length > 0);

package/dist/lib/session/remote-list.js

@@ -18,7 +18,7 @@ import chalk from 'chalk';
 import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from '../devices/connect.js';
 import { resolveExplicitTargets } from '../devices/resolve-target.js';
-import { loadDevices } from '../devices/registry.js';
+import { loadDevices, isControlDevice } from '../devices/registry.js';
 import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
 import { machineId, normalizeHost } from './sync/config.js';
 import { NO_FANOUT_ENV } from './remote-active.js';
@@ -129,6 +129,10 @@ export async function gatherRemoteList(forwardedArgs, hosts) {
                 continue;
             if (normalizeHost(d.name) === self)
                 continue;
+            // Control-only devices (a phone/tablet running the cockpit) drive the fleet
+            // but never run agents — never dial them, whatever their platform reads as.
+            if (isControlDevice(d))
+                continue;
             // Only machines that can actually run the CLI. iOS/tablet nodes register as
             // `unknown` platform and can never answer, so skip them rather than burn a
             // full ConnectTimeout on each.

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

@@ -14,7 +14,8 @@
  * markers. Codex has no such tools, so it falls back to last-role + question
  * shape + mtime — same function, driven off the normalized events.
  */
-import type { SessionAttachment, SessionEvent } from './types.js';
+import type { SessionAttachment, SessionEvent, TodoItem, TodoProgress } from './types.js';
+export type { TodoItem, TodoProgress };
 export type SessionActivity = 'working' | 'waiting_input' | 'idle';
 export type AwaitingReason = 'question' | 'plan_review' | 'permission';
 /** One discrete choice the agent offered the user. */
@@ -41,28 +42,6 @@ export interface StructuredQuestion {
     reason: AwaitingReason;
     options?: QuestionOption[];
 }
-/** One `TodoWrite` checklist item, as Claude's plan tool emits it. */
-export interface TodoItem {
-    content: string;
-    status: 'pending' | 'in_progress' | 'completed';
-    /** Present-continuous label shown while this item is the active step. */
-    activeForm?: string;
-}
-/**
- * Live plan progress derived from the most recent `TodoWrite` in the transcript
- * (RUSH-1380). Lets the Factory Floor show "N/M done" + the current step for any
- * session — including remote / device-dispatched agents that carry no local
- * tool-call stream — instead of only a coarse working/idle verb.
- */
-export interface TodoProgress {
-    items: TodoItem[];
-    /** Count of completed items. */
-    done: number;
-    /** Total items. */
-    total: number;
-    /** The in-progress item's activeForm (falls back to its content). The live step. */
-    activeForm?: string;
-}
 export interface DetectedPr {
     url: string;
     number?: number;
@@ -140,8 +119,11 @@ export interface StateContext {
     activeWindowMs?: number;
 }
 /**
- * Derive live plan progress from a `TodoWrite` tool call's args. Returns undefined
- * when there is no usable list, so a session with no plan carries no `todos` field.
+ * Derive live plan progress from a checklist tool call's args. Accepts both
+ * Claude's `TodoWrite` (`todos: [{content,status,activeForm}]`) and Codex's
+ * `update_plan` (`plan: [{step,status}]`) shapes, so the CLI is the single source
+ * of checklist state for every agent. Returns undefined when there is no usable
+ * list, so a session with no plan carries no `todos` field.
  */
 export declare function extractTodoProgress(args?: Record<string, any>): TodoProgress | undefined;
 /** Detect a worktree from the session cwd, per the `.agents/worktrees/<slug>/` convention. */

package/dist/lib/session/state.js

@@ -47,14 +47,22 @@ const PROSE_QUESTION_FRESH_MS = 30 * 60_000;
 /** Claude tool names that structurally mean "the agent handed control back to you". */
 const PLAN_TOOL = 'ExitPlanMode';
 const ASK_TOOL = 'AskUserQuestion';
-/** Claude's live plan/checklist tool. */
+/** The live plan/checklist tools: Claude's `TodoWrite` and Codex's `update_plan`. */
 const TODO_TOOL = 'TodoWrite';
+const CODEX_PLAN_TOOL = 'update_plan';
 /**
- * Derive live plan progress from a `TodoWrite` tool call's args. Returns undefined
- * when there is no usable list, so a session with no plan carries no `todos` field.
+ * Derive live plan progress from a checklist tool call's args. Accepts both
+ * Claude's `TodoWrite` (`todos: [{content,status,activeForm}]`) and Codex's
+ * `update_plan` (`plan: [{step,status}]`) shapes, so the CLI is the single source
+ * of checklist state for every agent. Returns undefined when there is no usable
+ * list, so a session with no plan carries no `todos` field.
  */
 export function extractTodoProgress(args) {
-    const raw = args?.todos;
+    const raw = Array.isArray(args?.todos)
+        ? args.todos
+        : Array.isArray(args?.plan)
+            ? args.plan
+            : undefined;
     if (!Array.isArray(raw) || raw.length === 0)
         return undefined;
     const items = [];
@@ -64,7 +72,9 @@ export function extractTodoProgress(args) {
             ? t.content
             : typeof t?.text === 'string' && t.text
                 ? t.text
-                : activeForm ?? '';
+                : typeof t?.step === 'string' && t.step
+                    ? t.step
+                    : activeForm ?? '';
         if (!content)
             continue;
         const status = t?.status === 'completed' || t?.status === 'in_progress' ? t.status : 'pending';
@@ -318,7 +328,7 @@ export function inferActivity(events, ctx = {}) {
     // Live plan progress: the most recent TodoWrite's checklist (RUSH-1380). Attached
     // to `base` so every return path below carries it — a working, waiting, or idle
     // session all keep showing how far the plan got.
-    const lastTodo = lastOf(meaningful, e => e.type === 'tool_use' && e.tool === TODO_TOOL);
+    const lastTodo = lastOf(meaningful, e => e.type === 'tool_use' && (e.tool === TODO_TOOL || e.tool === CODEX_PLAN_TOOL));
     const todos = lastTodo ? extractTodoProgress(lastTodo.args) : undefined;
     const base = {
         activity: 'idle',

package/dist/lib/session/sync/config.js

@@ -3,7 +3,7 @@
  * machine's stable identity. Credentials come from the `r2.backups` secrets
  * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
  */
-import { readAndResolveBundleEnv } from '../../secrets/bundles.js';
+import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../../secrets/bundles.js';
 /** Secrets bundle holding the R2 credentials. */
 export const SYNC_BUNDLE = 'r2.backups';
 /**
@@ -12,7 +12,13 @@ export const SYNC_BUNDLE = 'r2.backups';
  * without real credentials (no silent fallback).
  */
 function resolveR2Config() {
-    const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'sessions-sync' });
+    // The daemon monitor loop is headless by construction (no TTY, ever), so
+    // isHeadlessSecretsContext() is true here and this resolves broker-only — a
+    // broker miss can never pop an unattended Touch ID sheet on the user's screen
+    // (same rationale as daemon.ts readDaemonClaudeOAuthToken). Using the shared
+    // predicate rather than a literal keeps it consistent with the other callers
+    // and lets any interactive caller of loadR2Config still prompt.
+    const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'sessions-sync', agentOnly: isHeadlessSecretsContext() });
     const accountId = env.R2_ACCOUNT_ID?.trim();
     const bucket = env.R2_BUCKET_NAME?.trim();
     const accessKeyId = env.R2_ACCESS_KEY_ID?.trim();

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

@@ -41,6 +41,29 @@ export interface SessionAttachment {
     mediaType: string;
     sizeBytes?: number;
 }
+/** One checklist item, as Claude's `TodoWrite` (`content`) or Codex's `update_plan` (`step`) emits it. */
+export interface TodoItem {
+    content: string;
+    status: 'pending' | 'in_progress' | 'completed';
+    /** Present-continuous label shown while this item is the active step. */
+    activeForm?: string;
+}
+/**
+ * Live plan progress derived from the most recent checklist write in the transcript
+ * (Claude `TodoWrite` / Codex `update_plan`, RUSH-1380). Lets consumers show "N/M
+ * done" + the current step for any session — including remote / device-dispatched
+ * agents that carry no local tool-call stream — instead of only a coarse
+ * working/idle verb.
+ */
+export interface TodoProgress {
+    items: TodoItem[];
+    /** Count of completed items. */
+    done: number;
+    /** Total items. */
+    total: number;
+    /** The in-progress item's activeForm (falls back to its content). The live step. */
+    activeForm?: string;
+}
 /** Metadata attached when a session was spawned by `agents teams`. */
 export interface TeamOrigin {
     /** Teammate name if set, otherwise first 8 chars of the agent UUID. */
@@ -116,6 +139,13 @@ export interface SessionMeta {
      * recover the plan text — the CLI now carries it on the metadata row.
      */
     plan?: string;
+    /**
+     * Live plan progress from the most recent checklist write (Claude `TodoWrite`
+     * / Codex `update_plan`, RUSH-1503). Populated on `agents sessions <id> --json`
+     * from the state engine so the Factory panel reads the CLI's computed checklist
+     * instead of re-parsing the transcript. Absent when the session wrote no list.
+     */
+    todos?: TodoProgress;
     /**
      * True when the session was spawned programmatically (SDK entrypoint) rather
      * than by a human at the Claude CLI. Captured at scan time from the JSONL

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

@@ -0,0 +1,29 @@
+/**
+ * Render an HTML file to a 1200×630 PNG — the Open Graph cover for a shared plan.
+ *
+ * When `agents share plan.html` runs, we screenshot the plan's own hero and use it
+ * as the `og:image`, so the link unfurls into a card in Slack / iMessage / Twitter /
+ * Discord. No AI, no central render service: it's a headless screenshot on the
+ * publisher's machine, so it works identically for us and for any user, and costs
+ * nothing.
+ *
+ * Browser resolution reuses the repo's own detector (`findFirstInstalledBrowser`,
+ * the same auto-pick behind `agents browser`), then falls back to a managed
+ * Chromium in the Playwright/Puppeteer caches (present on machines that have done
+ * browser automation), then `PUPPETEER_EXECUTABLE_PATH`. If nothing headless-capable
+ * is found, `captureCover` returns null and publishing proceeds without a cover —
+ * the link still works, it just won't have a preview image.
+ */
+/** OG standard card size; captured at OG_SCALE× for retina crispness. */
+export declare const OG_WIDTH = 1200;
+export declare const OG_HEIGHT = 630;
+/** Device scale factor for the capture — the served PNG is OG_WIDTH*OG_SCALE × OG_HEIGHT*OG_SCALE. */
+export declare const OG_SCALE = 2;
+/** Ordered list of candidate Chromium-family binaries to try for headless capture. */
+export declare function candidateBrowsers(): string[];
+/**
+ * Screenshot `htmlPath`'s top 1200×630 (its hero) to a PNG buffer, or null if no
+ * headless-capable browser is available or every candidate fails. Never throws —
+ * a cover is a nice-to-have, never a reason to fail a publish.
+ */
+export declare function captureCover(htmlPath: string, timeoutMs?: number): Promise<Buffer | null>;

package/dist/lib/share/capture.js

@@ -0,0 +1,140 @@
+/**
+ * Render an HTML file to a 1200×630 PNG — the Open Graph cover for a shared plan.
+ *
+ * When `agents share plan.html` runs, we screenshot the plan's own hero and use it
+ * as the `og:image`, so the link unfurls into a card in Slack / iMessage / Twitter /
+ * Discord. No AI, no central render service: it's a headless screenshot on the
+ * publisher's machine, so it works identically for us and for any user, and costs
+ * nothing.
+ *
+ * Browser resolution reuses the repo's own detector (`findFirstInstalledBrowser`,
+ * the same auto-pick behind `agents browser`), then falls back to a managed
+ * Chromium in the Playwright/Puppeteer caches (present on machines that have done
+ * browser automation), then `PUPPETEER_EXECUTABLE_PATH`. If nothing headless-capable
+ * is found, `captureCover` returns null and publishing proceeds without a cover —
+ * the link still works, it just won't have a preview image.
+ */
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { findFirstInstalledBrowser } from '../browser/chrome.js';
+/** OG standard card size; captured at OG_SCALE× for retina crispness. */
+export const OG_WIDTH = 1200;
+export const OG_HEIGHT = 630;
+/** Device scale factor for the capture — the served PNG is OG_WIDTH*OG_SCALE × OG_HEIGHT*OG_SCALE. */
+export const OG_SCALE = 2;
+// Installed browsers that are poor `--headless` hosts (they hang instead of
+// capturing). We still let a managed Chromium or an explicit override handle those
+// machines; we just don't burn a timeout probing these. (Only members of the
+// browser detector's `BrowserType` are meaningful here; Comet is the real case.)
+const BAD_HEADLESS_TYPES = new Set(['comet']);
+/** Ordered list of candidate Chromium-family binaries to try for headless capture. */
+export function candidateBrowsers() {
+    const out = [];
+    const push = (p) => {
+        if (p && fs.existsSync(p) && !out.includes(p))
+            out.push(p);
+    };
+    // 1) An explicit override always wins.
+    push(process.env.PUPPETEER_EXECUTABLE_PATH || process.env.AGENTS_SHARE_BROWSER);
+    // 2) Managed Chromium in the Playwright / Puppeteer caches — purpose-built for
+    //    headless, so it's the most reliable capture host when present.
+    for (const bin of scanCaches())
+        push(bin);
+    // 3) The repo's own auto-pick (Chrome → Brave → Edge → Chromium by platform),
+    //    skipping browsers known to be poor headless hosts so we don't eat a timeout.
+    try {
+        const pick = findFirstInstalledBrowser();
+        if (pick && !BAD_HEADLESS_TYPES.has(pick.browserType))
+            push(pick.binary);
+    }
+    catch {
+        // detector is best-effort
+    }
+    return out;
+}
+/** Newest-first Chromium binaries under the Playwright / Puppeteer download caches. */
+function scanCaches() {
+    const home = os.homedir();
+    const roots = os.platform() === 'darwin'
+        ? [
+            path.join(home, 'Library/Caches/ms-playwright'),
+            path.join(home, '.cache/ms-playwright'),
+            path.join(home, '.cache/puppeteer/chrome'),
+        ]
+        : [path.join(home, '.cache/ms-playwright'), path.join(home, '.cache/puppeteer/chrome')];
+    const rel = os.platform() === 'darwin'
+        ? [
+            'chrome-mac/Chromium.app/Contents/MacOS/Chromium',
+            'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+            'chrome-mac-x64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+        ]
+        : ['chrome-linux/chrome', 'chrome-linux64/chrome'];
+    const found = [];
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = fs.readdirSync(root).sort().reverse(); // newest version dir first
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            for (const r of rel) {
+                const p = path.join(root, e, r);
+                if (fs.existsSync(p))
+                    found.push(p);
+            }
+        }
+    }
+    return found;
+}
+/**
+ * Screenshot `htmlPath`'s top 1200×630 (its hero) to a PNG buffer, or null if no
+ * headless-capable browser is available or every candidate fails. Never throws —
+ * a cover is a nice-to-have, never a reason to fail a publish.
+ */
+export async function captureCover(htmlPath, timeoutMs = 15_000) {
+    const abs = path.resolve(htmlPath);
+    if (!fs.existsSync(abs))
+        return null;
+    const fileUrl = `file://${abs.split('/').map(encodeURIComponent).join('/')}`;
+    for (const bin of candidateBrowsers()) {
+        const outPng = path.join(os.tmpdir(), `agents-share-cover-${process.pid}-${Date.now()}.png`);
+        const userDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-share-chrome-'));
+        try {
+            await new Promise((resolve, reject) => {
+                execFile(bin, [
+                    '--headless=new',
+                    '--disable-gpu',
+                    '--hide-scrollbars',
+                    '--no-first-run',
+                    '--no-default-browser-check',
+                    `--force-device-scale-factor=${OG_SCALE}`,
+                    // Bound page JS (count-up animations etc.) so the shot fires promptly
+                    // instead of waiting on long-running timers.
+                    '--virtual-time-budget=8000',
+                    `--window-size=${OG_WIDTH},${OG_HEIGHT}`,
+                    `--user-data-dir=${userDir}`,
+                    `--screenshot=${outPng}`,
+                    fileUrl,
+                ], { timeout: timeoutMs }, (err) => (err ? reject(err) : resolve()));
+            });
+            if (fs.existsSync(outPng)) {
+                const buf = fs.readFileSync(outPng);
+                // A valid PNG starts with the 8-byte signature; guard against 0-byte writes.
+                if (buf.length > 8 && buf[0] === 0x89 && buf[1] === 0x50)
+                    return buf;
+            }
+        }
+        catch {
+            // try the next candidate
+        }
+        finally {
+            fs.rmSync(outPng, { force: true });
+            fs.rmSync(userDir, { recursive: true, force: true });
+        }
+    }
+    return null;
+}

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

@@ -0,0 +1,35 @@
+export interface ShareConfig {
+    /** Public base, e.g. `https://share.agents-cli.sh` or `https://agent-share.<acct>.workers.dev`. */
+    baseUrl: string;
+    accountId: string;
+    workerName: string;
+    bucketName: string;
+    /** Custom domain when mapped (e.g. `share.agents-cli.sh`). */
+    domain?: string;
+}
+export declare const SHARE_BUNDLE = "share";
+export declare const SHARE_TOKEN_KEY = "SHARE_WRITE_TOKEN";
+export declare const DEFAULT_CF_BUNDLE = "cloudflare.com";
+export declare const DEFAULT_WORKER_NAME = "agents-share";
+export declare const DEFAULT_BUCKET_NAME = "agents-share";
+/** Read the persisted endpoint config, or null if `agents share setup`/`join` never ran. */
+export declare function readShareConfig(): ShareConfig | null;
+/** Persist the endpoint config to `agents.yaml` (syncs across the fleet). */
+export declare function writeShareConfig(cfg: ShareConfig): void;
+/** A fresh 32-byte hex write token. */
+export declare function generateWriteToken(): string;
+/** Persist the raw write token into the `share` secrets bundle (keychain-backed,
+ * fleet-injectable). Mirrors the add-key sequence in `commands/secrets.ts`. */
+export declare function storeWriteToken(token: string): void;
+/** Read the raw write token from the `share` secrets bundle. Throws with an
+ * actionable message if absent (run setup/join first). */
+export declare function readWriteToken(): string;
+/** Cloudflare API credentials for provisioning, read from `cloudflare.com` (or a
+ * user-named bundle). Fuzzy-matches key names so it works across bundle layouts. */
+export declare function readCloudflareCreds(bundle?: string, override?: {
+    apiToken?: string;
+    accountId?: string;
+}): {
+    apiToken: string;
+    accountId: string;
+};