@phnx-labs/agents-cli 1.20.65 → 1.20.66

package/dist/lib/secrets/agent.js

@@ -27,6 +27,7 @@ import * as net from 'net';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { randomBytes } from 'crypto';
 import { spawn, spawnSync, execFileSync } from 'child_process';
 import { getHelpersDir, readMeta } from '../state.js';
 import { isAlive } from '../platform/process.js';
@@ -109,6 +110,42 @@ function socketPath() {
 function pidPath() {
     return path.join(agentDir(), 'agent.pid');
 }
+/**
+ * Path of the per-broker capability token. It lives in the 0700 agent dir and is
+ * written 0600, so only the same UID that owns the broker can read it — the file
+ * permission IS the authorization boundary. See isRequestAuthorized.
+ */
+function tokenPath() {
+    return path.join(agentDir(), 'agent.token');
+}
+/**
+ * Read the current broker capability token, or null if none is present. Clients
+ * read it fresh per request and attach it to every non-ping command; a broker
+ * restart mints a new token, so a stale read simply fails authorization and the
+ * caller falls back to a direct keychain read (soft, never a hard error).
+ */
+export function readAgentToken() {
+    try {
+        const t = fs.readFileSync(tokenPath(), 'utf-8').trim();
+        return t.length > 0 ? t : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Mint + persist a fresh capability token (0600) at socket-bind time. Only the
+ * process that actually binds the socket calls this, so a losing starter never
+ * clobbers the live owner's token. Returns the token for in-memory comparison. */
+function writeAgentToken() {
+    const token = randomBytes(32).toString('hex');
+    const fp = tokenPath();
+    fs.writeFileSync(fp, token, { mode: 0o600 });
+    try {
+        fs.chmodSync(fp, 0o600);
+    }
+    catch { /* dir 0700 already gates it */ }
+    return token;
+}
 /**
  * Argv for re-invoking THIS cli with a hidden subcommand, so a side-by-side dev
  * build spawns its own helpers rather than the registry-installed one. We always
@@ -272,6 +309,60 @@ export function handleAgentRequest(store, req, now = Date.now()) {
 export function shouldWipeOnWatchEvent(chunk) {
     return /\bSLEEP\b/.test(chunk);
 }
+/**
+ * Authorization gate applied to every request BEFORE handleAgentRequest touches
+ * the store (RUSH-1760). A bare same-UID socket connection is no longer trusted
+ * to load/get arbitrary bundle env: each command except the liveness `ping` must
+ * carry the per-broker capability token, which lives in a 0600 file inside the
+ * 0700 agent dir and so is readable only by the UID that owns the broker.
+ *
+ * Fail closed: a missing/empty expected token (no token file) rejects every
+ * command but ping. `ping` stays unauthenticated — it exposes only the protocol
+ * and cli version, and clients need it to detect a reachable broker before they
+ * have any reason to read the token. Pure + exported for direct unit testing.
+ */
+export function isRequestAuthorized(req, expectedToken) {
+    if (req.cmd === 'ping')
+        return true;
+    if (!expectedToken)
+        return false;
+    return req.token === expectedToken;
+}
+/**
+ * Build the socket `connection` handler shared by both brokers (standalone and
+ * daemon-hosted): newline-framed JSON in, one response line out, with the
+ * authorization gate (isRequestAuthorized) applied before `handle`. `token`
+ * resolves the currently-expected capability token per request so a token
+ * rotation on broker restart is picked up without rebuilding the handler.
+ */
+export function makeConnectionHandler(handle, token) {
+    return (conn) => {
+        conn.setEncoding('utf-8');
+        let buf = '';
+        conn.on('data', (chunk) => {
+            buf += chunk;
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                if (!line.trim())
+                    continue;
+                let resp;
+                try {
+                    const req = JSON.parse(line);
+                    resp = isRequestAuthorized(req, token())
+                        ? handle(req)
+                        : { ok: false, error: 'unauthorized' };
+                }
+                catch (err) {
+                    resp = { ok: false, error: err.message };
+                }
+                conn.write(JSON.stringify(resp) + '\n');
+            }
+        });
+        conn.on('error', () => { });
+    };
+}
 /**
  * Bind the shared broker socket without stealing it from another live owner.
  * Both the standalone service and daemon-hosted broker use this single path so
@@ -293,6 +384,13 @@ async function bindBrokerSocket(sock, onConnection) {
                 fs.chmodSync(sock, 0o600);
             }
             catch { /* dir 0700 already gates it */ }
+            // Mint the capability token here — the one moment this process is the
+            // confirmed socket owner — so a losing starter never clobbers the live
+            // owner's token (RUSH-1760).
+            try {
+                writeAgentToken();
+            }
+            catch { /* dir 0700 gates the socket regardless */ }
             resolve(server);
         });
     });
@@ -428,29 +526,7 @@ export async function runSecretsAgent(opts = {}) {
             emptySince = Date.now();
         return resp;
     };
-    const onConnection = (conn) => {
-        conn.setEncoding('utf-8');
-        let buf = '';
-        conn.on('data', (chunk) => {
-            buf += chunk;
-            let nl;
-            while ((nl = buf.indexOf('\n')) >= 0) {
-                const line = buf.slice(0, nl);
-                buf = buf.slice(nl + 1);
-                if (!line.trim())
-                    continue;
-                let resp;
-                try {
-                    resp = handle(JSON.parse(line));
-                }
-                catch (err) {
-                    resp = { ok: false, error: err.message };
-                }
-                conn.write(JSON.stringify(resp) + '\n');
-            }
-        });
-        conn.on('error', () => { });
-    };
+    const onConnection = makeConnectionHandler(handle, readAgentToken);
     let server = null;
     do {
         try {
@@ -558,29 +634,7 @@ export async function startHostedBroker() {
     const store = new Map();
     const sock = socketPath(); // agentDir() creates the 0700 dir as a side effect
     const handle = (req) => handleAgentRequest(store, req);
-    const onConn = (conn) => {
-        conn.setEncoding('utf-8');
-        let buf = '';
-        conn.on('data', (chunk) => {
-            buf += chunk;
-            let nl;
-            while ((nl = buf.indexOf('\n')) >= 0) {
-                const line = buf.slice(0, nl);
-                buf = buf.slice(nl + 1);
-                if (!line.trim())
-                    continue;
-                let resp;
-                try {
-                    resp = handle(JSON.parse(line));
-                }
-                catch (err) {
-                    resp = { ok: false, error: err.message };
-                }
-                conn.write(JSON.stringify(resp) + '\n');
-            }
-        });
-        conn.on('error', () => { });
-    };
+    const onConn = makeConnectionHandler(handle, readAgentToken);
     const server = await bindBrokerSocket(sock, onConn);
     if (!server)
         return null;
@@ -632,6 +686,9 @@ export async function startHostedBroker() {
 /** Open the socket, send one request, resolve the one response. Async path —
  * used by the unlock/lock/status commands, which already run in async actions. */
 function request(req, timeoutMs = 2000) {
+    // Attach the capability token to every command except ping (the auth gate;
+    // RUSH-1760). ping stays tokenless so a client can probe reachability first.
+    const authedReq = req.cmd === 'ping' ? req : { ...req, token: readAgentToken() ?? undefined };
     return new Promise((resolve) => {
         const conn = net.createConnection(socketPath());
         let buf = '';
@@ -649,7 +706,7 @@ function request(req, timeoutMs = 2000) {
         };
         const timer = setTimeout(() => finish(null), timeoutMs);
         conn.on('error', () => finish(null));
-        conn.on('connect', () => conn.write(JSON.stringify(req) + '\n'));
+        conn.on('connect', () => conn.write(JSON.stringify(authedReq) + '\n'));
         conn.setEncoding('utf-8');
         conn.on('data', (chunk) => {
             buf += chunk;
@@ -679,14 +736,15 @@ export function agentSocketExists() {
  * -e: [execPath, <socket>, <name>].
  */
 const SYNC_GET_PROGRAM = `
-const net = require('net');
-const sock = process.argv[1], name = process.argv[2];
+const net = require('net'), fs = require('fs');
+const sock = process.argv[1], name = process.argv[2], tokenPath = process.argv[3];
+let token; try { token = fs.readFileSync(tokenPath, 'utf-8').trim() || undefined; } catch (e) {}
 const c = net.createConnection(sock);
 let buf = '';
 const miss = () => { try { c.destroy(); } catch (e) {} process.exit(3); };
 const timer = setTimeout(miss, 2000);
 c.on('error', miss);
-c.on('connect', () => c.write(JSON.stringify({ cmd: 'get', name }) + '\\n'));
+c.on('connect', () => c.write(JSON.stringify({ cmd: 'get', name, token }) + '\\n'));
 c.setEncoding('utf-8');
 c.on('data', (d) => {
   buf += d;
@@ -707,7 +765,7 @@ c.on('data', (d) => {
 export function agentGetSync(name) {
     if (!agentSocketExists())
         return null;
-    const r = spawnSync(process.execPath, ['-e', SYNC_GET_PROGRAM, socketPath(), name], {
+    const r = spawnSync(process.execPath, ['-e', SYNC_GET_PROGRAM, socketPath(), name, tokenPath()], {
         encoding: 'utf-8',
         timeout: 3000,
     });
@@ -771,14 +829,15 @@ export function agentReachableSync() {
  * argv after -e: [execPath, <socket>, <name>].
  */
 const SYNC_LOCK_PROGRAM = `
-const net = require('net');
-const sock = process.argv[1], name = process.argv[2];
+const net = require('net'), fs = require('fs');
+const sock = process.argv[1], name = process.argv[2], tokenPath = process.argv[3];
+let token; try { token = fs.readFileSync(tokenPath, 'utf-8').trim() || undefined; } catch (e) {}
 const c = net.createConnection(sock);
 let buf = '';
 const down = () => { try { c.destroy(); } catch (e) {} process.exit(3); };
 const timer = setTimeout(down, 2000);
 c.on('error', down);
-c.on('connect', () => c.write(JSON.stringify({ cmd: 'lock', name }) + '\\n'));
+c.on('connect', () => c.write(JSON.stringify({ cmd: 'lock', name, token }) + '\\n'));
 c.setEncoding('utf-8');
 c.on('data', (d) => {
   buf += d;
@@ -803,7 +862,7 @@ export function agentEvictSync(name) {
     if (!agentSocketExists())
         return;
     try {
-        spawnSync(process.execPath, ['-e', SYNC_LOCK_PROGRAM, socketPath(), name], { timeout: 3000 });
+        spawnSync(process.execPath, ['-e', SYNC_LOCK_PROGRAM, socketPath(), name, tokenPath()], { timeout: 3000 });
     }
     catch { /* best-effort */ }
 }

package/dist/lib/secrets/filestore.d.ts

@@ -22,6 +22,15 @@
  */
 import type { KeychainBackend } from './index.js';
 export declare function fileDir(): string;
+/**
+ * Turn off terminal echo on the controlling TTY, or throw — fail CLOSED. If echo
+ * cannot be disabled (`stty` missing, no controlling terminal) we must NOT fall
+ * through and read the passphrase anyway: that echoes the secret to the screen
+ * and into scrollback (RUSH-1764). Refuse and point the user at the environment
+ * variable instead. `run` performs the echo-disable and throws iff it fails.
+ * Exported so the fail-closed contract has direct test coverage.
+ */
+export declare function disableTtyEchoOrThrow(run: () => void): void;
 /** True if a machine-local passphrase has already been provisioned. */
 export declare function machinePassphraseExists(): boolean;
 /**

package/dist/lib/secrets/filestore.js

@@ -65,6 +65,24 @@ finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr) }
     }
     return (res.stdout?.toString() ?? '').replace(/\r?\n$/, '');
 }
+/**
+ * Turn off terminal echo on the controlling TTY, or throw — fail CLOSED. If echo
+ * cannot be disabled (`stty` missing, no controlling terminal) we must NOT fall
+ * through and read the passphrase anyway: that echoes the secret to the screen
+ * and into scrollback (RUSH-1764). Refuse and point the user at the environment
+ * variable instead. `run` performs the echo-disable and throws iff it fails.
+ * Exported so the fail-closed contract has direct test coverage.
+ */
+export function disableTtyEchoOrThrow(run) {
+    try {
+        run();
+    }
+    catch {
+        throw new Error('Refusing to prompt for AGENTS_SECRETS_PASSPHRASE: terminal echo could not be ' +
+            'disabled (stty unavailable or no controlling TTY), so the passphrase would be ' +
+            'shown in cleartext. Set AGENTS_SECRETS_PASSPHRASE in the environment instead.');
+    }
+}
 function readPassphraseFromTty() {
     if (process.platform === 'win32')
         return readPassphraseFromTtyWindows();
@@ -72,14 +90,9 @@ function readPassphraseFromTty() {
     let echoDisabled = false;
     try {
         fs.writeSync(fd, 'Enter AGENTS_SECRETS_PASSPHRASE: ');
-        try {
-            execSync('stty -echo < /dev/tty', { stdio: 'ignore' });
-            echoDisabled = true;
-        }
-        catch {
-            // stty not available — fall through; passphrase will echo. Better
-            // than refusing to function.
-        }
+        // Fail closed: if echo can't be turned off, abort rather than echo the secret.
+        disableTtyEchoOrThrow(() => execSync('stty -echo < /dev/tty', { stdio: 'ignore' }));
+        echoDisabled = true;
         let pass = '';
         const buf = Buffer.alloc(1);
         while (true) {

package/dist/lib/secrets/index.d.ts

@@ -214,6 +214,13 @@ export declare function getKeychainTokens(items: string[]): Map<string, string>;
  * predates that path rejects the unknown command (exit 2) and this throws,
  * rather than silently falling back to an ACL'd `set` (which would behave like
  * `always`). Ignored by the Linux/Windows/test backends, which have no ACL. */
+/**
+ * argv for writing a bare (non-`agents-cli.`) keychain item via
+ * `/usr/bin/security add-generic-password`, deliberately WITHOUT the value: the
+ * secret travels over stdin (see setKeychainToken) so it never lands in argv or
+ * a `ps` snapshot. Exported so a test can assert the value is absent from argv.
+ */
+export declare function buildAddGenericPasswordArgs(account: string, item: string): string[];
 export declare function setKeychainToken(item: string, value: string, opts?: {
     noAcl?: boolean;
 }): void;

package/dist/lib/secrets/index.js

@@ -844,6 +844,15 @@ function parseBatchRecords(out, record) {
  * predates that path rejects the unknown command (exit 2) and this throws,
  * rather than silently falling back to an ACL'd `set` (which would behave like
  * `always`). Ignored by the Linux/Windows/test backends, which have no ACL. */
+/**
+ * argv for writing a bare (non-`agents-cli.`) keychain item via
+ * `/usr/bin/security add-generic-password`, deliberately WITHOUT the value: the
+ * secret travels over stdin (see setKeychainToken) so it never lands in argv or
+ * a `ps` snapshot. Exported so a test can assert the value is absent from argv.
+ */
+export function buildAddGenericPasswordArgs(account, item) {
+    return ['add-generic-password', '-U', '-a', account, '-s', item, '-w'];
+}
 export function setKeychainToken(item, value, opts) {
     // Validate the CLEARTEXT name (a hashed storage name is always clean), then
     // resolve the storage name.
@@ -872,12 +881,23 @@ export function setKeychainToken(item, value, opts) {
     // /usr/bin/security read can't satisfy without popping the legacy password
     // sheet. -U upserts so repeated sets overwrite in place.
     if (!isOurItem(item)) {
-        const sec = spawnSync('/usr/bin/security', [
-            'add-generic-password', '-U',
-            '-a', os.userInfo().username,
-            '-s', item,
-            '-w', value,
-        ], { stdio: ['ignore', 'pipe', 'pipe'] });
+        // The secret VALUE must never appear in argv — a `ps` snapshot on a shared
+        // host would leak it (RUSH-1764). `security add-generic-password` has no
+        // stdin-password flag; instead a BARE `-w` as the LAST option makes it prompt
+        // ("password data for new item:" / "retype...") and read the secret from fd 0
+        // via readpassphrase(3) -- so the value travels over stdin, never on the
+        // command line. The prompt asks twice (enter + confirm), so we pipe the value
+        // TWICE; a single line fails the confirm and would store an empty secret. The
+        // item stays ACL-free (no biometry gate), so the no-prompt /usr/bin/security
+        // read path in getKeychainToken still works. Values are newline-free on darwin
+        // (assertValueStorable above), so each line carries the whole secret verbatim
+        // (no shell/quoting layer). `timeout` bounds the call so a context that cannot
+        // read the prompt fails loudly instead of hanging.
+        const sec = spawnSync('/usr/bin/security', buildAddGenericPasswordArgs(os.userInfo().username, item), {
+            input: `${value}\n${value}\n`,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 10_000,
+        });
         if (sec.status !== 0) {
             const msg = sec.stderr?.toString().trim();
             throw new Error(msg || `Failed to write keychain item '${item}'.`);

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;
+};