@phnx-labs/agents-cli 1.22.33 → 1.22.35

package/dist/lib/project-root.js

@@ -18,6 +18,7 @@ import { readMeta, updateMeta } from './state.js';
 import { getMainRepoRoot } from './git.js';
 import { toPosix } from './platform/index.js';
 import { loadProjectDef, resolveDefinedProjectPath } from './projects.js';
+import { shellQuote } from './ssh-exec.js';
 const HOME = process.env.HOME ?? os.homedir();
 /** Rewrite an absolute path under the local home to a `~/`-relative string; pass others through. */
 export function toHomeRelative(abs) {
@@ -53,6 +54,73 @@ export function toRemotePortable(p) {
         return toHomeRelative(p);
     return p;
 }
+/**
+ * If `p` is anchored at the home dir — a leading `~` or `$HOME` — return the
+ * remainder (no leading slash), else null. Callers that want a local-home
+ * absolute (`/Users/<me>/x`, from a shell-expanded `--cwd ~/x`) re-rooted at the
+ * remote home normalize it to `~/x` first (`toRemotePortable`); explicit
+ * `--remote-cwd` is left literal and so is never re-rooted here.
+ *
+ * The canonical home-anchor stripper — shared by `remoteCdPrefix`,
+ * `deriveMirroredCwd`, and the interactive-login shell builder
+ * (`devices/connect.ts`), so there is exactly one notion of "the part below the
+ * home dir".
+ */
+export function homeRemainder(p) {
+    if (p === '~' || p === '$HOME')
+        return '';
+    if (p.startsWith('~/'))
+        return p.slice(2);
+    if (p.startsWith('$HOME/'))
+        return p.slice(6);
+    return null;
+}
+/**
+ * Derive the remote directory to mirror from the local cwd, for a host run the
+ * caller gave no `--cwd`/`--remote-cwd` (and for an interactive `agents ssh`
+ * login with no command).
+ *
+ * Without this a `--host` run — or an `agents ssh <device>` login — lands in the
+ * remote `$HOME`, so an agent launched from a repo starts with no project
+ * context and the user has to `cd` by hand. Only a cwd under the LOCAL home is
+ * mirrored — that is the part with a meaningful remote analogue (`~/src/x`
+ * re-roots onto the remote home). A path outside home returns undefined:
+ * `/opt/thing` on this box says nothing about the target's filesystem, so the
+ * run keeps the remote home.
+ */
+export function deriveMirroredCwd(localCwd) {
+    const portable = toRemotePortable(localCwd);
+    return homeRemainder(portable) === null ? undefined : portable;
+}
+/**
+ * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
+ *
+ * A `~`/`$HOME`-anchored path must resolve against the REMOTE user's home, not
+ * the local one (`/home/<me>` vs `/Users/<me>`). We emit an unquoted `"$HOME"`
+ * for that segment — the remote login shell expands it — and shell-quote the
+ * remainder. Any other path (absolute or relative) is quoted verbatim.
+ *
+ * `mirror` marks a directory the caller DERIVED from the local cwd rather than
+ * one the user asked for (see `deriveMirroredCwd`). The same repo checked out at
+ * the same home-relative path on both boxes is the common fleet layout, so
+ * mirroring lands the remote agent in the project instead of `$HOME`. It is a
+ * best-effort mirror by definition — the host may simply not have that checkout
+ * — so a missing directory falls back to the remote home instead of failing the
+ * run. An explicit `--cwd`/`--remote-cwd` is never mirrored: the user named that
+ * directory, so a missing one must surface as a `cd` error.
+ */
+export function remoteCdPrefix(remoteCwd, opts = {}) {
+    if (!remoteCwd)
+        return '';
+    const rest = homeRemainder(remoteCwd);
+    if (rest === '')
+        return 'cd "$HOME" && ';
+    if (rest !== null) {
+        const dir = `"$HOME"/${shellQuote(rest)}`;
+        return opts.mirror ? `{ cd ${dir} || cd "$HOME"; } && ` : `cd ${dir} && `;
+    }
+    return `cd ${shellQuote(remoteCwd)} && `;
+}
 /** The configured projects root (home-relative or absolute), or undefined when unset. */
 export function getProjectRoot() {
     return readMeta().projectRoot;

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

@@ -263,7 +263,7 @@ export declare function brokerPidAlive(): boolean;
 export declare function runSecretsAgent(opts?: {
     service?: boolean;
 }): Promise<{
-    close(): void;
+    close(): void | Promise<void>;
 } | null>;
 /**
  * Host the secrets broker inside the always-on daemon (#416).
@@ -284,8 +284,15 @@ export declare function runSecretsAgent(opts?: {
  * or null off-darwin (nothing to broker without biometry).
  */
 export declare function startHostedBroker(): Promise<{
-    close(): void;
+    close(): void | Promise<void>;
 } | null>;
+/**
+ * Call Node's net.Server.close() and wait for the 'close' event (or a bounded
+ * timeout). Without this, close() returned while the listen socket could still
+ * be held — a successor bind could race EADDRINUSE against a half-closed server
+ * (RUSH-2421). Pure side-effect helper; never throws.
+ */
+export declare function closeServerBounded(server: net.Server, timeoutMs?: number): Promise<void>;
 /** True if a broker socket exists at all. Cheap; gates the sync read so the
  * never-unlocked path stays a single stat. */
 export declare function agentSocketExists(): boolean;

package/dist/lib/secrets/agent.js

@@ -760,6 +760,9 @@ export async function runSecretsAgent(opts = {}) {
     }
     let watcher = null;
     let sweepTimer = null;
+    // Sync cleanup for SIGTERM/SIGINT → process.exit: we cannot await the
+    // server's 'close' event before exit, so fire-and-forget close + unlink.
+    // The public close() path below awaits with a bounded timeout (RUSH-2421).
     cleanupActive = () => {
         store.clear();
         if (sweepTimer)
@@ -806,12 +809,25 @@ export async function runSecretsAgent(opts = {}) {
         watcher = null;
     }
     return {
-        close() {
+        async close() {
             if (shuttingDown)
                 return;
             shuttingDown = true;
             detachSignals();
-            cleanupActive?.();
+            store.clear();
+            if (sweepTimer)
+                clearInterval(sweepTimer);
+            try {
+                watcher?.kill();
+            }
+            catch { /* already gone */ }
+            await closeServerBounded(server);
+            try {
+                fs.unlinkSync(sock);
+            }
+            catch { /* gone */ }
+            releaseBrokerPid();
+            releasePid();
         },
     };
 }
@@ -877,17 +893,18 @@ export async function startHostedBroker() {
         watcher = null;
     }
     return {
-        close() {
+        // RUSH-2421: await net.Server's 'close' (bounded) so a caller relying on
+        // close() cannot proceed past a socket that is not actually released yet.
+        // The daemon may fire-and-forget this promise; tests and any awaiter get
+        // the real release boundary.
+        async close() {
             store.clear();
             clearInterval(sweepTimer);
             try {
                 watcher?.kill();
             }
             catch { /* already gone */ }
-            try {
-                server.close();
-            }
-            catch { /* not listening */ }
+            await closeServerBounded(server);
             try {
                 fs.unlinkSync(sock);
             }
@@ -896,6 +913,34 @@ export async function startHostedBroker() {
         },
     };
 }
+/** How long to wait for net.Server.close()'s 'close' event before giving up. */
+const SERVER_CLOSE_TIMEOUT_MS = 2_000;
+/**
+ * Call Node's net.Server.close() and wait for the 'close' event (or a bounded
+ * timeout). Without this, close() returned while the listen socket could still
+ * be held — a successor bind could race EADDRINUSE against a half-closed server
+ * (RUSH-2421). Pure side-effect helper; never throws.
+ */
+export function closeServerBounded(server, timeoutMs = SERVER_CLOSE_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(finish, timeoutMs);
+        try {
+            server.close(() => finish());
+        }
+        catch {
+            // Already closed / not listening — treat as released.
+            finish();
+        }
+    });
+}
 // ─── Client ──────────────────────────────────────────────────────────────────
 /** 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. */

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

@@ -31,9 +31,17 @@ export interface KeychainProcessSnapshot {
      * True when this process is a REAP-ELIGIBLE helper invocation — the installed
      * helper binary running a short-lived keychain verb. False for a non-helper
      * process AND for the long-lived `watch-lock` watcher (see
-     * {@link isReapableHelperCommand}), which must never be reaped.
+     * {@link isReapableHelperCommand}).
      */
     isHelper: boolean;
+    /**
+     * True when this process is the deliberately long-lived `watch-lock` watcher
+     * (auto-lock-on-sleep). Mutually exclusive with {@link isHelper}:
+     * {@link isReapableHelperCommand} keeps live-parent watch-locks out of the
+     * stuck-helper path, and a SEPARATE orphan path in {@link planKeychainReap}
+     * reaps them only once the owning daemon is provably dead (RUSH-2419).
+     */
+    isWatchLock?: boolean;
 }
 /**
  * Tracked state for a stuck `agents` parent that has a live helper child.
@@ -59,7 +67,7 @@ export interface ReapPlan {
  * Pure predicate: decide which processes to kill given a `ps`-like snapshot.
  *
  * Mirrors the shape of {@link isExpiredPoolStray} in `lib/crabbox/lease.ts`:
- * a side-effect-free classifier that the impure driver shells `ps` for. Two
+ * a side-effect-free classifier that the impure driver shells `ps` for. Three
  * conservative reap classes:
  *
  *   1. Orphaned helper: PPID == 1, path-matches the helper, alive longer than
@@ -68,9 +76,15 @@ export interface ReapPlan {
  *      {@link STUCK_GRACE_SEC}. Recorded on first sight, child killed on the
  *      second consecutive sweep with the same PID + startTime, parent killed on
  *      the third sweep if the helper child is still present.
+ *   3. Orphaned `watch-lock` watcher (RUSH-2419): the long-lived auto-lock
+ *      child whose owning daemon is provably dead. {@link isReapableHelperCommand}
+ *      still excludes live-parent watch-locks from class 1/2; this path only
+ *      reaps when the parent is gone from the snapshot (Unix reparents to init
+ *      after daemon death) and the watcher itself has a start-time fingerprint.
  *
  * Never reaps a process whose start time could not be captured, whose path does
- * not match the helper, or whose parent is no longer in the snapshot.
+ * not match the helper, or (for stuck parents) whose parent is no longer in the
+ * snapshot. A watch-lock whose parent IS still in the snapshot is never touched.
  */
 export declare function planKeychainReap(snapshots: KeychainProcessSnapshot[], now: number, prevCandidates: ReadonlyMap<number, StuckParentCandidate>): ReapPlan;
 /**
@@ -92,6 +106,13 @@ export declare function parseEtimeToSeconds(raw: string): number | null;
  * mistaken for a stuck read and killed. Pure; unit-tested.
  */
 export declare function isReapableHelperCommand(command: string, helperPath: string): boolean;
+/**
+ * Whether a `ps` command line is the deliberately long-lived `watch-lock`
+ * watcher (auto-lock-on-sleep). Inverse of {@link isReapableHelperCommand} for
+ * the watch-lock verb only — used by the orphaned-watch-lock reaper path
+ * (RUSH-2419). Pure; unit-tested.
+ */
+export declare function isWatchLockHelperCommand(command: string, helperPath: string): boolean;
 /** Test seam: reset the persisted candidate state. */
 export declare function resetKeychainReaperCandidatesForTest(): void;
 /**

package/dist/lib/secrets/reaper.js

@@ -23,7 +23,7 @@ export const STUCK_GRACE_SEC = 90;
  * Pure predicate: decide which processes to kill given a `ps`-like snapshot.
  *
  * Mirrors the shape of {@link isExpiredPoolStray} in `lib/crabbox/lease.ts`:
- * a side-effect-free classifier that the impure driver shells `ps` for. Two
+ * a side-effect-free classifier that the impure driver shells `ps` for. Three
  * conservative reap classes:
  *
  *   1. Orphaned helper: PPID == 1, path-matches the helper, alive longer than
@@ -32,9 +32,15 @@ export const STUCK_GRACE_SEC = 90;
  *      {@link STUCK_GRACE_SEC}. Recorded on first sight, child killed on the
  *      second consecutive sweep with the same PID + startTime, parent killed on
  *      the third sweep if the helper child is still present.
+ *   3. Orphaned `watch-lock` watcher (RUSH-2419): the long-lived auto-lock
+ *      child whose owning daemon is provably dead. {@link isReapableHelperCommand}
+ *      still excludes live-parent watch-locks from class 1/2; this path only
+ *      reaps when the parent is gone from the snapshot (Unix reparents to init
+ *      after daemon death) and the watcher itself has a start-time fingerprint.
  *
  * Never reaps a process whose start time could not be captured, whose path does
- * not match the helper, or whose parent is no longer in the snapshot.
+ * not match the helper, or (for stuck parents) whose parent is no longer in the
+ * snapshot. A watch-lock whose parent IS still in the snapshot is never touched.
  */
 export function planKeychainReap(snapshots, now, prevCandidates) {
     const pidMap = new Map(snapshots.map((s) => [s.pid, s]));
@@ -88,6 +94,34 @@ export function planKeychainReap(snapshots, now, prevCandidates) {
             stage: 'watch',
         });
     }
+    // Separate path for orphaned watch-lock watchers (RUSH-2419). Does NOT
+    // weaken {@link isReapableHelperCommand}: a watch-lock with a live parent
+    // stays isHelper=false and is skipped above. Here we only kill when the
+    // owning daemon is provably absent from the process table.
+    for (const s of snapshots) {
+        if (!s.isWatchLock)
+            continue;
+        // Fail closed: no start-time fingerprint → refuse to kill (pid-reuse guard
+        // for the process we are about to target, same as orphan helpers).
+        if (s.startTime == null)
+            continue;
+        if (s.elapsedSec <= ORPHAN_GRACE_SEC)
+            continue;
+        // Live parent in this snapshot → owning daemon is still up. Leave it alone
+        // (this is the property isReapableHelperCommand protects for stuck-helper
+        // reaping; re-assert it here so a mis-tagged row cannot be killed either).
+        if (s.ppid !== 1) {
+            const parent = pidMap.get(s.ppid);
+            if (parent)
+                continue;
+            // Parent pid not listed: the process occupying that slot is gone. On Unix
+            // a dead parent reparents the child to init; a missing parent with a
+            // non-1 ppid is the race window before reparenting. Either way the owner
+            // is dead — safe to reap after grace + fingerprint.
+        }
+        // ppid===1 (reparented to init/launchd) or parent missing → orphaned.
+        kill.push(s.pid);
+    }
     return { kill, nextCandidates };
 }
 /**
@@ -159,6 +193,18 @@ export function isReapableHelperCommand(command, helperPath) {
     const firstArg = command.slice(helperPath.length + 1).trimStart().split(/\s+/)[0];
     return firstArg !== HELPER_WATCH_LOCK_VERB;
 }
+/**
+ * Whether a `ps` command line is the deliberately long-lived `watch-lock`
+ * watcher (auto-lock-on-sleep). Inverse of {@link isReapableHelperCommand} for
+ * the watch-lock verb only — used by the orphaned-watch-lock reaper path
+ * (RUSH-2419). Pure; unit-tested.
+ */
+export function isWatchLockHelperCommand(command, helperPath) {
+    if (!command.startsWith(`${helperPath} `))
+        return false;
+    const firstArg = command.slice(helperPath.length + 1).trimStart().split(/\s+/)[0];
+    return firstArg === HELPER_WATCH_LOCK_VERB;
+}
 /** Module-state for the two-sweep stuck-parent debounce. */
 let stuckParentCandidates = new Map();
 /** Test seam: reset the persisted candidate state. */
@@ -206,16 +252,18 @@ export function reapOrphanedKeychainProcesses() {
         // Reap-eligible = the helper binary running a short-lived keychain verb. The
         // full-argv match excludes the deliberately long-lived `watch-lock` watcher,
         // whose live-parent child would otherwise be killed as if it were stuck
-        // (RUSH-2232 — that silently disabled auto-lock-on-sleep).
+        // (RUSH-2232 — that silently disabled auto-lock-on-sleep). Orphaned
+        // watch-locks are tracked separately via isWatchLock (RUSH-2419).
         const isHelper = isReapableHelperCommand(command, helperPath);
-        rows.push({ pid, ppid, elapsedSec, isHelper, startTime: null });
+        const isWatchLock = isWatchLockHelperCommand(command, helperPath);
+        rows.push({ pid, ppid, elapsedSec, isHelper, isWatchLock, startTime: null });
     }
     const rowByPid = new Map(rows.map((r) => [r.pid, r]));
     for (const row of rows) {
-        if (!row.isHelper)
+        if (!row.isHelper && !row.isWatchLock)
             continue;
         row.startTime = captureProcessStartTime(row.pid);
-        if (row.ppid !== 1 && row.elapsedSec > STUCK_GRACE_SEC) {
+        if (row.isHelper && row.ppid !== 1 && row.elapsedSec > STUCK_GRACE_SEC) {
             const parent = rowByPid.get(row.ppid);
             if (parent && parent.startTime === null) {
                 parent.startTime = captureProcessStartTime(row.ppid);
@@ -228,6 +276,7 @@ export function reapOrphanedKeychainProcesses() {
         elapsedSec: r.elapsedSec,
         startTime: r.startTime,
         isHelper: r.isHelper,
+        isWatchLock: r.isWatchLock,
     }));
     const plan = planKeychainReap(snapshots, Date.now(), stuckParentCandidates);
     stuckParentCandidates = plan.nextCandidates;

package/dist/lib/session/discover.js

@@ -442,6 +442,18 @@ function normalizeCwd(cwd) {
     if (process.platform === 'win32' && /^\//.test(cwd) && !/^[a-zA-Z]:/.test(cwd)) {
         return stripTrailingSep(path.posix.normalize(cwd));
     }
+    // The mirror case (RUSH-2358): a Windows-rooted path (`C:\...`, `C:/...`, or a
+    // UNC `\\server\share\...`) read on POSIX belongs to another machine too, but
+    // `path.isAbsolute()` here uses POSIX rules and doesn't recognize a drive
+    // letter — without this branch such a cwd falls into the `path.resolve()` arm
+    // below and gets silently prefixed with THIS process's own cwd, corrupting the
+    // path (and, via WORKTREE_RE, can misattribute the worktree slug to whatever
+    // worktree the reading process happens to be running in). Normalize with
+    // win32 rules so separators survive; never realpath it, for the same
+    // cross-drive reason as the mirror branch above.
+    if (process.platform !== 'win32' && /^([a-zA-Z]:[\\/]|\\\\)/.test(cwd)) {
+        return stripTrailingSep(path.win32.normalize(cwd));
+    }
     const normalized = path.isAbsolute(cwd) ? stripTrailingSep(path.normalize(cwd)) : path.resolve(cwd);
     return safeRealpathSync(normalized) || normalized;
 }

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

@@ -67,6 +67,8 @@ export interface SessionStats {
 export declare function computeSummaryStats(events: SessionEvent[]): SessionStats;
 /** Strip the 'claude-' prefix and date suffix from a model identifier. */
 export declare function shortenModel(model: string): string;
+/** Format a token count as a human-readable string (e.g. 67.5K, 1.2M). */
+export declare function formatTokenCount(n: number): string;
 /** Format a duration in milliseconds as a human-readable string (e.g. '12 min', '2h 30min'). */
 export declare function formatDuration(ms: number): string;
 /**

package/dist/lib/session/render.js

@@ -219,7 +219,7 @@ export function shortenModel(model) {
     return model.replace(/^claude-/, '').replace(/-\d{8}$/, '');
 }
 /** Format a token count as a human-readable string (e.g. 67.5K, 1.2M). */
-function formatTokenCount(n) {
+export function formatTokenCount(n) {
     if (n === 0)
         return '0';
     if (n < 1000)

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