@phnx-labs/agents-cli 1.22.34 → 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/delete.d.ts

@@ -0,0 +1,93 @@
+import { type ShareConfig } from './config.js';
+/** DI seam for tests — override the real HTTP DELETE. */
+export type DeleteFn = (url: string, headers: Record<string, string>) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+/** DI seam for tests — override the real HTTP existence check (HEAD). */
+export type CheckFn = (url: string) => Promise<{
+    status: number;
+}>;
+export interface DeleteEndpoint {
+    baseUrl: string;
+    token: string;
+}
+export interface ResolvedShareTarget {
+    /** R2 object key for the page, `<user>/<slug>`. */
+    key: string;
+    /** R2 object key for the sibling OG cover, `<user>/<slug>.png`. */
+    coverKey: string;
+}
+/**
+ * Normalize any of the three accepted target forms to the R2 key that publish
+ * would have written:
+ *   - a full share URL: `https://share.agents-cli.sh/<user>/<slug>`
+ *   - `<user>/<slug>`
+ *   - a bare `<slug>` — resolved against the caller's own namespace exactly as
+ *     `publishToEndpoint` resolves it at publish time (resolveShareUsername +
+ *     buildShareKey), so a bare slug always targets *your* published page.
+ *
+ * The URL and `<user>/<slug>` forms are taken as already the exact key a prior
+ * publish produced (no re-sanitizing) — only the bare-slug form runs through
+ * `buildShareKey`, because that's the one case where the slug hasn't already
+ * been normalized by a publish.
+ */
+export declare function resolveDeleteTarget(target: string, opts?: {
+    githubUser?: string;
+}): Promise<ResolvedShareTarget>;
+export interface DeleteObjectResult {
+    key: string;
+    url: string;
+    /** Whether the object resolved (non-404) before the DELETE was issued. */
+    existedBefore: boolean;
+    /** Whether the Worker's DELETE call itself reported ok. */
+    deleted: boolean;
+    /** The postcondition: a follow-up check resolved 404 after the DELETE. */
+    verified404: boolean;
+}
+/**
+ * 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
+ * idempotent, so a DELETE on a key that was never there also returns `ok:true`.
+ * This checks existence before (so callers can tell "deleted" from "was never
+ * there") and re-checks after (so callers can tell "deleted" from "still public").
+ */
+export declare function deleteObject(endpoint: DeleteEndpoint, key: string, opts?: {
+    deleter?: DeleteFn;
+    checker?: CheckFn;
+}): Promise<DeleteObjectResult>;
+export interface DeleteShareOptions {
+    /** Skip deleting the sibling `<slug>.png` OG cover (default: delete it too). */
+    keepCover?: 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;
+    /** Override the GitHub username used to resolve a bare-slug target. */
+    githubUser?: string;
+    /** DI seam for tests — override the persisted share endpoint config. */
+    config?: ShareConfig;
+    /** DI seam for tests — override the keychain-backed write token. */
+    writeToken?: string;
+    /** DI seam for tests — override the real HTTP DELETE. */
+    deleter?: DeleteFn;
+    /** DI seam for tests — override the real HTTP existence check. */
+    checker?: CheckFn;
+}
+export interface DeleteShareResult {
+    key: string;
+    url: string;
+    existedBefore: boolean;
+    verified404: boolean;
+    /** True when `ifExists` was set and the target was already gone — nothing ran. */
+    skipped?: boolean;
+    cover?: {
+        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
+ * object that still resolves. */
+export declare function deleteShare(target: string, opts?: DeleteShareOptions): Promise<DeleteShareResult>;

package/dist/lib/share/delete.js

@@ -0,0 +1,127 @@
+// The delete path for `agents share delete` / `agents unshare` — an authed DELETE
+// to the Worker, which already implements it (worker-template.ts). Mirrors
+// publish.ts: pure target-resolution logic is exported for tests, the network
+// calls (a status check + a delete) sit behind an injectable DI seam.
+//
+// The Worker's R2 delete is idempotent — DELETE on a key that never existed still
+// returns `{"ok":true}` — so `{"ok":true}` alone is never proof of a takedown.
+// Every delete here is followed by a status check that must observe 404 before
+// the operation is reported as successful.
+import { readShareConfig, readWriteToken } from './config.js';
+import { buildShareKey, resolveShareUsername } from './publish.js';
+/**
+ * Normalize any of the three accepted target forms to the R2 key that publish
+ * would have written:
+ *   - a full share URL: `https://share.agents-cli.sh/<user>/<slug>`
+ *   - `<user>/<slug>`
+ *   - a bare `<slug>` — resolved against the caller's own namespace exactly as
+ *     `publishToEndpoint` resolves it at publish time (resolveShareUsername +
+ *     buildShareKey), so a bare slug always targets *your* published page.
+ *
+ * The URL and `<user>/<slug>` forms are taken as already the exact key a prior
+ * publish produced (no re-sanitizing) — only the bare-slug form runs through
+ * `buildShareKey`, because that's the one case where the slug hasn't already
+ * been normalized by a publish.
+ */
+export async function resolveDeleteTarget(target, opts = {}) {
+    const trimmed = target.trim();
+    if (!trimmed)
+        throw new Error('Share target is empty.');
+    let key;
+    if (/^https?:\/\//i.test(trimmed)) {
+        const url = new URL(trimmed);
+        const segments = url.pathname
+            .replace(/^\/+|\/+$/g, '')
+            .split('/')
+            .filter(Boolean)
+            .map(decodeURIComponent);
+        if (segments.length < 2) {
+            throw new Error(`Not a share page URL (expected .../<user>/<slug>): ${trimmed}`);
+        }
+        key = segments.slice(0, 2).join('/');
+    }
+    else if (trimmed.includes('/')) {
+        const segments = trimmed.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+        if (segments.length !== 2) {
+            throw new Error(`Expected <user>/<slug>, got: ${trimmed}`);
+        }
+        key = segments.join('/');
+    }
+    else {
+        const username = await resolveShareUsername(opts);
+        key = buildShareKey(username, trimmed);
+    }
+    return { key, coverKey: `${key}.png` };
+}
+async function defaultCheck(url) {
+    const res = await fetch(url, { method: 'HEAD' });
+    return { status: res.status };
+}
+async function defaultDelete(url, headers) {
+    const res = await fetch(url, { method: 'DELETE', headers });
+    return { ok: res.ok, status: res.status };
+}
+/**
+ * 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
+ * idempotent, so a DELETE on a key that was never there also returns `ok:true`.
+ * This checks existence before (so callers can tell "deleted" from "was never
+ * there") and re-checks after (so callers can tell "deleted" from "still public").
+ */
+export async function deleteObject(endpoint, key, opts = {}) {
+    const url = `${endpoint.baseUrl.replace(/\/+$/, '')}/${key}`;
+    const check = opts.checker ?? defaultCheck;
+    const del = opts.deleter ?? defaultDelete;
+    const before = await check(url);
+    const existedBefore = before.status !== 404;
+    const r = await del(url, { authorization: `Bearer ${endpoint.token}` });
+    if (!r.ok) {
+        throw new Error(`Delete failed (${r.status}) for ${url}. Check the write token, or that 'agents share setup' completed.`);
+    }
+    const after = await check(url);
+    const verified404 = after.status === 404;
+    return { key, url, existedBefore, deleted: r.ok, verified404 };
+}
+/** 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
+ * object that still resolves. */
+export async function deleteShare(target, opts = {}) {
+    const cfg = opts.config ?? readShareConfig();
+    if (!cfg) {
+        throw new Error("Not set up yet. Run 'agents share setup' (provision your own endpoint) or 'agents share join' (use an existing one).");
+    }
+    const token = opts.writeToken ?? readWriteToken();
+    const resolved = await resolveDeleteTarget(target, { githubUser: opts.githubUser });
+    const endpoint = { baseUrl: cfg.baseUrl, token };
+    const page = await deleteObject(endpoint, resolved.key, { deleter: opts.deleter, checker: opts.checker });
+    if (!page.existedBefore) {
+        if (opts.ifExists) {
+            return { key: page.key, url: page.url, existedBefore: false, verified404: page.verified404, skipped: true };
+        }
+        throw new Error(`Nothing to delete — ${page.url} was already not found. Pass --if-exists to treat this as a no-op instead of an error.`);
+    }
+    if (!page.verified404) {
+        throw new Error(`Delete reported success but ${page.url} still resolves — takedown NOT verified. Retry, or investigate the Worker/R2 directly.`);
+    }
+    const result = {
+        key: page.key,
+        url: page.url,
+        existedBefore: page.existedBefore,
+        verified404: page.verified404,
+    };
+    if (!opts.keepCover) {
+        const cover = await deleteObject(endpoint, resolved.coverKey, { deleter: opts.deleter, checker: opts.checker });
+        result.cover = {
+            key: cover.key,
+            url: cover.url,
+            existedBefore: cover.existedBefore,
+            verified404: cover.verified404,
+        };
+        // A missing cover is normal (non-HTML publishes, or --no-cover at publish
+        // time never made one) — only a cover that existed and is still up is a bug.
+        if (cover.existedBefore && !cover.verified404) {
+            throw new Error(`Cover delete reported success but ${cover.url} still resolves — takedown NOT verified. Retry, or pass --keep-cover and delete it manually.`);
+        }
+    }
+    return result;
+}

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. */