@phnx-labs/agents-cli 1.22.37 → 1.22.38

package/dist/commands/share.js

@@ -1,5 +1,9 @@
-// `agents share` — publish an HTML file to your own Cloudflare R2 behind a tiny
-// Worker, and get a shareable link (~$0). See apps/cli/docs/share.md.
+// `agents artifacts share` — publish an HTML file to your own Cloudflare R2
+// behind a tiny Worker, and get a shareable link (~$0). See apps/cli/docs/share.md.
+//
+// Registered under the `artifacts` group by commands/artifacts.ts; the
+// provisioning door lives beside it at `agents artifacts setup`
+// (commands/artifacts-setup.ts), which calls `runShareProvision` below.
 import { existsSync } from 'node:fs';
 import chalk from 'chalk';
 import { DEFAULT_BUCKET_NAME, DEFAULT_CF_BUNDLE, DEFAULT_SHARE_DOMAIN, DEFAULT_WORKER_NAME, generateWriteToken, readCloudflareCreds, readShareConfig, readWriteToken, readWriteTokenEnv, readWriteTokenFromBundle, storeWriteToken, writeShareConfig, } from '../lib/share/config.js';
@@ -35,10 +39,10 @@ export function shareTemplateStatus(cfg) {
 }
 /** Shown whenever the deployed Worker has no `?format=json` listing route — an
  * endpoint provisioned before this feature. Points at the RUSH-2449 update path
- * (`agents share update`) instead of letting the caller hit a 404 or an HTML body
- * and get a confusing parse error. */
-const OUTDATED_TEMPLATE_HINT = 'Your deployed share Worker has no machine-readable listing route — it predates `agents share list`. ' +
-    'Run `agents share update` to deploy the current Worker template, then retry (`agents share status` shows whether an update is due).';
+ * (`agents artifacts share update`) instead of letting the caller hit a 404 or an
+ * HTML body and get a confusing parse error. */
+const OUTDATED_TEMPLATE_HINT = 'Your deployed share Worker has no machine-readable listing route — it predates `agents artifacts share list`. ' +
+    'Run `agents artifacts share update` to deploy the current Worker template, then retry (`agents artifacts share status` shows whether an update is due).';
 async function defaultListingFetch(url) {
     const res = await fetch(url, { headers: { accept: 'application/json' } });
     return { status: res.status, contentType: res.headers.get('content-type') ?? '', body: await res.text() };
@@ -80,7 +84,7 @@ export function parseShareListing(user, body) {
 export async function runShareList(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).");
+        throw new Error("Not set up yet. Run 'agents artifacts setup' (provision your own endpoint) or 'agents artifacts share join' (use an existing one).");
     }
     // A known-stale template can't have the listing route — say so before any network
     // call. 'unknown' (provisioned before templateHash tracking) is attempted, then
@@ -100,14 +104,14 @@ export async function runShareList(opts = {}) {
         // endpoint predates the listing route entirely. The recorded templateHash
         // disambiguates: a 'current' template HAS the route, so its 404 means an empty
         // namespace ("nothing published"); otherwise the route may be absent, so point
-        // at `agents share update`.
+        // at `agents artifacts share update`.
         if (templateStatus === 'current') {
             return { user, count: 0, objects: [] };
         }
         throw new Error(OUTDATED_TEMPLATE_HINT);
     }
     if (res.status !== 200) {
-        throw new Error(`Listing failed (${res.status}) for ${listUrl}. Check the endpoint is reachable, or that 'agents share setup' completed.`);
+        throw new Error(`Listing failed (${res.status}) for ${listUrl}. Check the endpoint is reachable, or that 'agents artifacts setup' completed.`);
     }
     if (!/application\/json/i.test(res.contentType)) {
         // A 200 that isn't JSON means the old Worker ignored ?format=json and served
@@ -157,8 +161,8 @@ export function formatShareDeleteResult(result, json = false) {
     }
     return lines.join('\n');
 }
-/** Shared handler for `agents share delete <targets...>` and the top-level
- * `agents unshare <targets...>` alias. Deletes each target independently and
+/** Shared handler for `agents artifacts share delete <targets...>` and the
+ * top-level `agents unshare <targets...>` alias. Deletes each target independently and
  * continues past a failed one (rm-style), reporting all results and exiting
  * non-zero if any target failed to verify as gone.
  *
@@ -200,10 +204,10 @@ function registerShareDeleteOptions(cmd) {
 }
 const SHARE_DELETE_EXAMPLES = `
       # Delete by full URL — also takes down the sibling OG cover
-      agents share delete https://share.agents-cli.sh/octocat/my-plan-a1b2
+      agents artifacts share delete https://share.agents-cli.sh/octocat/my-plan-a1b2
 
       # Delete by <user>/<slug>, or a bare slug in your own namespace
-      agents share delete octocat/my-plan-a1b2
+      agents artifacts share delete octocat/my-plan-a1b2
       agents unshare my-plan-a1b2
 
       # Several at once
@@ -220,17 +224,23 @@ const SHARE_DELETE_NOTES = `
   Worker's DELETE is idempotent and returns {"ok":true} even for a key that was
   never there, so that response alone is never proof of a takedown.
 
-  agents share delete === agents unshare (same command, different name).
+  agents artifacts share delete === agents unshare (same command, different name).
 `;
-export function registerShareCommands(program) {
-    const shareCmd = program
+/**
+ * Register the `share` subtree under its parent group — `agents artifacts share`
+ * (see commands/artifacts.ts). The top-level `agents unshare` alias is a sibling
+ * registration on the ROOT program, so it is {@link registerUnshareCommand}, not
+ * part of this subtree.
+ */
+export function registerShareCommands(artifactsCmd) {
+    const shareCmd = artifactsCmd
         .command('share')
         .description('Publish an HTML file to your own Cloudflare R2 and get a shareable link (~$0).')
         .argument('[file]', 'file to publish (HTML or any static asset)')
         .option('--slug <slug>', 'custom URL slug under your namespace (default: <project>-<feature>-<hash>)')
         .option('--github-user <user>', 'GitHub username for the share namespace (default: resolved from gh/git config)')
         .option('--expire <spec>', "auto-expire (default 30d). e.g. 12h, 30d, 2026-08-01, or 'never'")
-        .option('--unlisted', 'hide from the public gallery and `agents share list` (direct URL still works)')
+        .option('--unlisted', 'hide from the public gallery and `agents artifacts share list` (direct URL still works)')
         .option('--private', 'alias of --unlisted')
         .option('--force', 'publish even when the file contains emails or credential-shaped strings')
         .option('--no-cover', 'skip the OG preview image (HTML pages get one by default)')
@@ -266,30 +276,30 @@ export function registerShareCommands(program) {
     setHelpSections(shareCmd, {
         examples: `
       # Publish an HTML file — auto OG cover, default 30d expiry, shareable link
-      agents share ./out/plan.html
+      agents artifacts share ./out/plan.html
 
       # Hide from the public gallery (direct URL still works) and expire sooner
-      agents share ./out/report.html --unlisted --expire 12h
+      agents artifacts share ./out/report.html --unlisted --expire 12h
 
       # Permanent public page (opt out of the default 30d expiry)
-      agents share ./out/landing.html --slug landing --expire never
+      agents artifacts share ./out/landing.html --slug landing --expire never
 
       # Custom slug, expiring in 7 days
-      agents share ./out/report.html --slug q3-report --expire 7d
+      agents artifacts share ./out/report.html --slug q3-report --expire 7d
 ${SHARE_DELETE_EXAMPLES}
       # One-time setup (or join an existing endpoint)
-      agents share setup
-      agents share join https://share.agents-cli.sh
+      agents artifacts setup
+      agents artifacts share join https://share.agents-cli.sh
 
       # Push a worker-template.ts change out to an already-provisioned endpoint
-      agents share update
+      agents artifacts share update
     `,
         notes: `
   Default expiry is 30d so an accidental publish decays. Pass --expire never for
   a permanent link. --unlisted / --private hides the page from the public gallery
-  and agents share list; the direct URL is still world-readable (unlisted, not
-  secret). A pre-publish scan refuses emails and credential-shaped strings
-  unless --force is passed.
+  and agents artifacts share list; the direct URL is still world-readable
+  (unlisted, not secret). A pre-publish scan refuses emails and credential-shaped
+  strings unless --force is passed.
 ${SHARE_DELETE_NOTES}
     `,
     });
@@ -300,32 +310,6 @@ ${SHARE_DELETE_NOTES}
     shareDeleteCmd.action(async (targets, opts) => {
         await runShareDelete(targets, opts);
     });
-    const unshareCmd = registerShareDeleteOptions(program
-        .command('unshare <targets...>')
-        .description('Alias of `agents share delete` — take down a published page (and by default its OG cover).'));
-    setHelpSections(unshareCmd, { examples: SHARE_DELETE_EXAMPLES, notes: SHARE_DELETE_NOTES });
-    unshareCmd.action(async (targets, opts) => {
-        await runShareDelete(targets, opts);
-    });
-    shareCmd
-        .command('setup')
-        .description('One-time: provision an R2 bucket + Worker on your Cloudflare and save the config.')
-        .option('--bundle <name>', 'secrets bundle holding the Cloudflare API token', DEFAULT_CF_BUNDLE)
-        .option('--worker <name>', 'Worker name', DEFAULT_WORKER_NAME)
-        .option('--bucket <name>', 'R2 bucket name', DEFAULT_BUCKET_NAME)
-        .option('--account <id>', 'Cloudflare account id (else read from the bundle / prompt)')
-        .option('--token <t>', 'Cloudflare API token (else read from the --bundle)')
-        .option('--domain <host>', `custom domain to map (default: ${DEFAULT_SHARE_DOMAIN}; workers.dev if zone is not visible)`)
-        .option('--analytics-token <token>', 'Cloudflare Web Analytics token to inject into published HTML pages')
-        .action(async (opts) => {
-        try {
-            await runShareProvision(opts);
-        }
-        catch (e) {
-            console.error(chalk.red(e.message));
-            process.exitCode = 1;
-        }
-    });
     shareCmd
         .command('join')
         .description('Use an existing synced share endpoint and write token (no provisioning).')
@@ -370,15 +354,15 @@ ${SHARE_DELETE_NOTES}
     setHelpSections(shareUpdateCmd, {
         examples: `
       # Push a worker-template.ts change out to your already-provisioned endpoint
-      agents share update
+      agents artifacts share update
 
       # Force a re-deploy even though the template hash already matches
-      agents share update --force
+      agents artifacts share update --force
     `,
         notes: `
-  Reuses the existing account/worker/bucket from 'agents share status' and the
+  Reuses the existing account/worker/bucket from 'agents artifacts share status' and the
   existing write token — it never re-provisions a bucket, touches routes, or
-  regenerates the token. See 'agents share status' for whether an update is due.
+  regenerates the token. See 'agents artifacts share status' for whether an update is due.
     `,
     });
     shareCmd
@@ -387,7 +371,7 @@ ${SHARE_DELETE_NOTES}
         .action(async () => {
         const cfg = readShareConfig();
         if (!cfg) {
-            console.log(chalk.dim("Not configured. Run 'agents share setup' or 'agents share join'."));
+            console.log(chalk.dim("Not configured. Run 'agents artifacts setup' or 'agents artifacts share join'."));
             return;
         }
         console.log(`${chalk.bold('endpoint')}  ${chalk.green(cfg.baseUrl)}`);
@@ -399,8 +383,8 @@ ${SHARE_DELETE_NOTES}
         const templateLabel = templateStatus === 'current'
             ? chalk.green('current')
             : templateStatus === 'outdated'
-                ? chalk.yellow('outdated — run `agents share update`')
-                : chalk.dim("unknown — provisioned before version tracking; run `agents share update` to adopt it");
+                ? chalk.yellow('outdated — run `agents artifacts share update`')
+                : chalk.dim("unknown — provisioned before version tracking; run `agents artifacts share update` to adopt it");
         console.log(`${chalk.bold('template')}  ${templateLabel}`);
     });
     const shareListCmd = shareCmd
@@ -421,21 +405,21 @@ ${SHARE_DELETE_NOTES}
     setHelpSections(shareListCmd, {
         examples: `
       # Everything you've published, newest first
-      agents share list
+      agents artifacts share list
 
       # Machine-readable — e.g. pull every still-public URL with jq
-      agents share list --json | jq -r '.objects[].url'
+      agents artifacts share list --json | jq -r '.objects[].url'
 
       # List another namespace
-      agents share list --github-user octocat
+      agents artifacts share list --github-user octocat
     `,
         notes: `
   Lists the ACTIVE pages in your namespace — expired links and the sibling .png OG
   covers are omitted (it mirrors the public gallery). It reads the endpoint's JSON
   listing route, which ships with the current Worker template. If your deployed
-  Worker predates this feature the command says so and points you at 'agents share
-  update' (RUSH-2449) rather than returning a wrong or empty result — see 'agents
-  share status' for whether an update is due.
+  Worker predates this feature the command says so and points you at 'agents
+  artifacts share update' (RUSH-2449) rather than returning a wrong or empty result
+  — see 'agents artifacts share status' for whether an update is due.
     `,
     });
     shareCmd
@@ -444,7 +428,7 @@ ${SHARE_DELETE_NOTES}
         .action(async () => {
         const cfg = readShareConfig();
         if (!cfg) {
-            console.log(chalk.dim("Not configured. Run 'agents share setup' or 'agents share join'."));
+            console.log(chalk.dim("Not configured. Run 'agents artifacts setup' or 'agents artifacts share join'."));
             return;
         }
         if (!analyticsEnabled(cfg)) {
@@ -464,9 +448,24 @@ ${SHARE_DELETE_NOTES}
         }
     });
 }
+/**
+ * Register the top-level `agents unshare <targets...>` alias of
+ * `agents artifacts share delete`. It takes the ROOT program (not the artifacts
+ * group) because it is deliberately a top-level convenience verb — taking a page
+ * down is the one artifact action typed often enough to keep at the root.
+ */
+export function registerUnshareCommand(program) {
+    const unshareCmd = registerShareDeleteOptions(program
+        .command('unshare <targets...>')
+        .description('Alias of `agents artifacts share delete` — take down a published page (and by default its OG cover).'));
+    setHelpSections(unshareCmd, { examples: SHARE_DELETE_EXAMPLES, notes: SHARE_DELETE_NOTES });
+    unshareCmd.action(async (targets, opts) => {
+        await runShareDelete(targets, opts);
+    });
+}
 /** Provision a fresh R2 bucket + Worker on the user's Cloudflare and persist the
- * endpoint config + write token. Shared by `agents share setup` and the unified
- * `agents setup share` wizard. */
+ * endpoint config + write token. Shared by both modes of `agents artifacts setup`
+ * (the flag-driven provision and the interactive wizard). */
 export async function runShareProvision(opts) {
     const { default: ora } = await import('ora');
     const { input } = await import('@inquirer/prompts');
@@ -521,7 +520,7 @@ export async function runShareProvision(opts) {
         writeShareConfig(cfg);
         storeWriteToken(token);
         console.log(chalk.green(`\nShare endpoint ready → ${chalk.bold(baseUrl)}`));
-        console.log(chalk.dim('Publish with:  ') + chalk.cyan('agents share <file>'));
+        console.log(chalk.dim('Publish with:  ') + chalk.cyan('agents artifacts share <file>'));
         console.log(chalk.dim(`Fleet: push the token with 'agents secrets export share --host <box>' and pull config with 'agents repo pull'.`));
     }
     catch (e) {
@@ -539,7 +538,7 @@ export async function runShareProvision(opts) {
 export async function runShareUpdate(opts = {}) {
     const cfg = readShareConfig();
     if (!cfg) {
-        throw new Error("Not configured. Run 'agents share setup' (to provision) or 'agents share join' first.");
+        throw new Error("Not configured. Run 'agents artifacts setup' (to provision) or 'agents artifacts share join' first.");
     }
     const { apiToken, accountId: acctFromBundle } = readCloudflareCreds(opts.bundle ?? DEFAULT_CF_BUNDLE, {
         apiToken: opts.token,
@@ -568,14 +567,14 @@ function cleanHostname(domain) {
     }
 }
 /** Join an existing share endpoint (no provisioning): prompt for the endpoint
- * details + write token and persist them. Shared by `agents share join` and the
- * unified `agents setup share` wizard. */
+ * details + write token and persist them. Shared by `agents artifacts share join`
+ * and the `agents artifacts setup` wizard. */
 export async function runShareJoin(baseUrl, opts = {}) {
     const { password, input } = await import('@inquirer/prompts');
     const existing = readShareConfig();
     const clean = baseUrl?.replace(/\/+$/, '');
     if (!clean && !existing) {
-        throw new Error("No synced share endpoint found. Pull config first with 'agents repo pull', or pass the endpoint URL: agents share join <baseUrl>.");
+        throw new Error("No synced share endpoint found. Pull config first with 'agents repo pull', or pass the endpoint URL: agents artifacts share join <baseUrl>.");
     }
     let cfg;
     if (existing && (!clean || clean === existing.baseUrl)) {
@@ -608,5 +607,5 @@ export async function runShareJoin(baseUrl, opts = {}) {
         throw new Error('A write token is required to join.');
     writeShareConfig(cfg);
     storeWriteToken(token);
-    console.log(chalk.green(`Joined ${chalk.bold(cfg.baseUrl)} — publish with `) + chalk.cyan('agents share <file>'));
+    console.log(chalk.green(`Joined ${chalk.bold(cfg.baseUrl)} — publish with `) + chalk.cyan('agents artifacts share <file>'));
 }

package/dist/lib/browser/hygiene.d.ts

@@ -0,0 +1,90 @@
+import { type PidSessionEntry } from '../session/pid-registry.js';
+import type { ReapResult, Task } from './types.js';
+/** Default idle window before an untouched task is reaped. */
+export declare const DEFAULT_IDLE_MS: number;
+/**
+ * The slice of `BrowserService` the reaper needs. Structural, so a test drives
+ * it with a stub and `BrowserService` satisfies it without an import — which
+ * also keeps this module off the service's import cycle.
+ */
+export interface ReapableService {
+    listTasks(): Array<{
+        profile: string;
+        task: Task;
+    }>;
+    recordStatus(taskName: string): Promise<{
+        recording: boolean;
+    }>;
+    stop(taskName: string): Promise<{
+        ok: boolean;
+        profile?: string;
+    }>;
+}
+/**
+ * Injectable liveness sources. Same shape as `feed-post.ts`
+ * (`input.listEntries ?? listPidSessionEntries`, feed-post.ts:119) — the
+ * defaults are the real registry and the real process table, so a test can
+ * substitute them without mocking a module.
+ */
+export interface ReapDeps {
+    listEntries?: () => PidSessionEntry[];
+    pidAlive?: (pid: number, startedAtMs?: number) => boolean;
+    sessionIdOfPid?: (pid: number) => string | undefined;
+    sessionLiveOnProcessTable?: (sessionId: string) => Promise<boolean>;
+}
+export interface ReapOptions {
+    /** Idle window in ms. Default {@link DEFAULT_IDLE_MS}. */
+    idleMs?: number;
+    /** Clock, injectable for tests. Default `Date.now()`. */
+    now?: number;
+    /** Report what would be closed without closing anything. */
+    dryRun?: boolean;
+    deps?: ReapDeps;
+}
+export interface LiveIdentities {
+    sessions: Set<string>;
+    launches: Set<string>;
+}
+/**
+ * Session and launch ids belonging to a process that is alive right now.
+ *
+ * Built from the per-pid launch registry, filtered to live pids —
+ * `isPidAlive(pid, startedAtMs)` rather than a bare existence check, so a pid
+ * the OS recycled onto an unrelated process does not read as a live agent.
+ * An entry with no recorded `sessionId` still contributes one when the live
+ * process carries `--session-id` on its argv, which is the RUSH-2384 recovery
+ * path the registry itself documents (pid-registry.ts:102-107).
+ */
+export declare function resolveLiveIdentities(deps?: ReapDeps): LiveIdentities;
+/**
+ * True when the task's owner is PROVABLY gone. The bar is proof, not absence of
+ * evidence, because being wrong here closes a working agent's tabs.
+ *
+ * Only a `sessionId` can carry that proof. It has two independent sources — the
+ * per-pid launch registry, and a live process carrying `--session-id <id>` in
+ * its argv — so a session the registry missed is still caught by the process
+ * table. The registry misses constantly: a wrapper pid exits, a prune sweeps
+ * the entry, or the agent was never launched via `agents run`
+ * (pid-registry.ts:102-107, RUSH-2384).
+ *
+ * A `launchId` has NO second source — the registry is its only witness, and
+ * that witness is the unreliable one. So a task carrying only a `launchId` is
+ * never session-reaped, exactly like a task carrying no identity at all; both
+ * fall through to the idle rule. This is not a corner case: `launchId` is
+ * minted for every run (`exec.ts` `resolveLaunchId`) while `AGENT_SESSION_ID`
+ * is Claude-only and skipped on resume, so treating a missing registry entry as
+ * proof of death would close the tabs of every live codex/droid/grok run whose
+ * launch pid had already exited.
+ *
+ * A live `launchId` still RESCUES a task whose `sessionId` looks dead — proof of
+ * life needs only one witness, unlike proof of death.
+ */
+export declare function taskOwnerIsGone(task: Task, live: LiveIdentities, deps?: ReapDeps): Promise<boolean>;
+/**
+ * Stop every task whose owner is gone or that has sat untouched past `idleMs`.
+ *
+ * Returns what it closed and how many it left alone. A task that is mid-
+ * recording is always left alone: reaping it would truncate a capture the user
+ * asked for, and an in-flight recording is itself proof the task is in use.
+ */
+export declare function reapAbandonedTasks(service: ReapableService, opts?: ReapOptions): Promise<ReapResult>;

package/dist/lib/browser/hygiene.js

@@ -0,0 +1,146 @@
+/**
+ * Abandoned browser-task reaper (RUSH-2622).
+ *
+ * `agents browser done` / `stop` already close a task's tabs, but agents
+ * routinely never call them — the run ends, the process exits, and the task's
+ * tabs stay open in the profile window forever. Over a day of fleet activity
+ * that is dozens of leftover tabs in Comet/Chrome.
+ *
+ * This closes the loop from the other end: a periodic pass that finds tasks
+ * nobody is driving any more and stops them.
+ *
+ * Two independent reasons, both conservative:
+ *
+ *   - `session-dead` — the task recorded WHICH agent session (`sessionId`) or
+ *     WHICH run (`launchId`) started it, and neither is alive on this host.
+ *     That is the honest end of the task: the thing that would have called
+ *     `done` no longer exists.
+ *   - `idle` — nothing has touched the task for `idleMs` (default 30 minutes).
+ *     The catch-all for a task with no recorded identity (a human running
+ *     `agents browser start` by hand) or an agent that stalled without exiting.
+ *
+ * Closing always goes through `BrowserService.stop`, never a direct
+ * `Target.closeTarget`, so history, the session cache, the target cache, and
+ * forked-profile teardown all stay on the one code path that already handles
+ * them. Two things this deliberately never does: touch a tab that is not in
+ * `task.tabs` (a tab the user opened themselves is not ours to close), and kill
+ * the profile window or the browser process because one task went idle.
+ */
+import { isPidAlive, isSessionIdLiveOnProcessTable } from '../session/active.js';
+import { listPidSessionEntries, sessionIdFromLivePid } from '../session/pid-registry.js';
+/** Default idle window before an untouched task is reaped. */
+export const DEFAULT_IDLE_MS = 30 * 60_000;
+/**
+ * Session and launch ids belonging to a process that is alive right now.
+ *
+ * Built from the per-pid launch registry, filtered to live pids —
+ * `isPidAlive(pid, startedAtMs)` rather than a bare existence check, so a pid
+ * the OS recycled onto an unrelated process does not read as a live agent.
+ * An entry with no recorded `sessionId` still contributes one when the live
+ * process carries `--session-id` on its argv, which is the RUSH-2384 recovery
+ * path the registry itself documents (pid-registry.ts:102-107).
+ */
+export function resolveLiveIdentities(deps = {}) {
+    const listEntries = deps.listEntries ?? listPidSessionEntries;
+    const alive = deps.pidAlive ?? isPidAlive;
+    const sessionIdOf = deps.sessionIdOfPid ?? sessionIdFromLivePid;
+    const sessions = new Set();
+    const launches = new Set();
+    for (const entry of listEntries()) {
+        if (!alive(entry.pid, entry.startedAtMs))
+            continue;
+        const sessionId = entry.sessionId ?? sessionIdOf(entry.pid);
+        if (sessionId)
+            sessions.add(sessionId);
+        if (entry.launchId)
+            launches.add(entry.launchId);
+    }
+    return { sessions, launches };
+}
+/**
+ * True when the task's owner is PROVABLY gone. The bar is proof, not absence of
+ * evidence, because being wrong here closes a working agent's tabs.
+ *
+ * Only a `sessionId` can carry that proof. It has two independent sources — the
+ * per-pid launch registry, and a live process carrying `--session-id <id>` in
+ * its argv — so a session the registry missed is still caught by the process
+ * table. The registry misses constantly: a wrapper pid exits, a prune sweeps
+ * the entry, or the agent was never launched via `agents run`
+ * (pid-registry.ts:102-107, RUSH-2384).
+ *
+ * A `launchId` has NO second source — the registry is its only witness, and
+ * that witness is the unreliable one. So a task carrying only a `launchId` is
+ * never session-reaped, exactly like a task carrying no identity at all; both
+ * fall through to the idle rule. This is not a corner case: `launchId` is
+ * minted for every run (`exec.ts` `resolveLaunchId`) while `AGENT_SESSION_ID`
+ * is Claude-only and skipped on resume, so treating a missing registry entry as
+ * proof of death would close the tabs of every live codex/droid/grok run whose
+ * launch pid had already exited.
+ *
+ * A live `launchId` still RESCUES a task whose `sessionId` looks dead — proof of
+ * life needs only one witness, unlike proof of death.
+ */
+export async function taskOwnerIsGone(task, live, deps = {}) {
+    if (!task.sessionId)
+        return false;
+    if (task.launchId && live.launches.has(task.launchId))
+        return false;
+    if (live.sessions.has(task.sessionId))
+        return false;
+    const onProcessTable = deps.sessionLiveOnProcessTable ?? ((id) => isSessionIdLiveOnProcessTable(id));
+    return !(await onProcessTable(task.sessionId));
+}
+/**
+ * Stop every task whose owner is gone or that has sat untouched past `idleMs`.
+ *
+ * Returns what it closed and how many it left alone. A task that is mid-
+ * recording is always left alone: reaping it would truncate a capture the user
+ * asked for, and an in-flight recording is itself proof the task is in use.
+ */
+export async function reapAbandonedTasks(service, opts = {}) {
+    const idleMs = opts.idleMs ?? DEFAULT_IDLE_MS;
+    // Fail loud rather than reap everything. A caller-supplied `0` survives `??`
+    // and would close every task including one created a millisecond ago; a
+    // non-numeric value makes every `>=` comparison false and silently disables
+    // idle reaping. Both are worse than an error.
+    if (!Number.isFinite(idleMs) || idleMs <= 0) {
+        throw new Error(`idleMs must be a positive number of milliseconds, got ${String(idleMs)}`);
+    }
+    const now = opts.now ?? Date.now();
+    const deps = opts.deps ?? {};
+    const live = resolveLiveIdentities(deps);
+    const closed = [];
+    let skipped = 0;
+    for (const { profile, task } of service.listTasks()) {
+        if ((await service.recordStatus(task.name)).recording) {
+            skipped++;
+            continue;
+        }
+        let reason;
+        if (await taskOwnerIsGone(task, live, deps)) {
+            reason = 'session-dead';
+        }
+        else if (now - (task.lastActionAt ?? task.createdAt) >= idleMs) {
+            reason = 'idle';
+        }
+        if (!reason) {
+            skipped++;
+            continue;
+        }
+        if (opts.dryRun) {
+            closed.push({ task: task.name, profile, reason });
+            continue;
+        }
+        const result = await service.stop(task.name);
+        if (result.ok) {
+            closed.push({ task: task.name, profile: result.profile ?? profile, reason });
+        }
+        else {
+            // `stop` reports not-found only when the task already left the map — a
+            // concurrent `done`, or a profile torn down mid-pass. Nothing was closed,
+            // so it is not reported as closed.
+            skipped++;
+        }
+    }
+    return { closed, skipped };
+}

package/dist/lib/browser/ipc.js

@@ -340,6 +340,7 @@ export class BrowserIPCServer {
                     url: request.url,
                     endpointName: request.endpoint,
                     skipDomainSkill: request.skipDomainSkill,
+                    fresh: request.fresh,
                     actor: request.actor,
                     launchId: request.launchId,
                     sessionId: request.sessionId,
@@ -352,6 +353,17 @@ export class BrowserIPCServer {
                     skill: result.skill,
                 };
             }
+            // The out-of-process seam onto the abandoned-task reaper: the daemon
+            // owns the live BrowserService, so a CLI verb (`agents browser gc`) can
+            // only reach `reapAbandoned` through IPC. The daemon's own periodic tick
+            // calls the service method directly.
+            case 'gc': {
+                const reaped = await this.service.reapAbandoned({
+                    idleMs: request.idleMinutes !== undefined ? request.idleMinutes * 60_000 : undefined,
+                    dryRun: request.dryRun,
+                });
+                return { ok: true, reaped };
+            }
             case 'done': {
                 if (!request.task) {
                     return { ok: false, error: 'Task required' };