@phnx-labs/agents-cli 1.22.37 → 1.22.39

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

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

@@ -1,5 +1,6 @@
 import { type ResolvedDomainSkill } from './domain-skills.js';
-import { type TabInfo, type ProfileStatus, type HistoricalTask } from './types.js';
+import { type Task, type TabInfo, type ProfileStatus, type HistoricalTask, type ReapResult } from './types.js';
+import { type ReapOptions } from './hygiene.js';
 import { type RefOpts, type RefNode } from './refs.js';
 import type { TargetFilter } from './types.js';
 export type UploadMode = 'auto' | 'input' | 'drop' | 'chooser';
@@ -77,11 +78,17 @@ export declare class BrowserService {
     private networkRequests;
     private pendingDownloads;
     private enabledSessions;
+    /** Profile -> when a `touchTask` last persisted tasks.json for it. */
+    private lastTouchPersist;
+    /** Coalescing window for the `touchTask` write. See {@link touchTask}. */
+    private static readonly TOUCH_PERSIST_INTERVAL_MS;
     start(profileName: string, opts?: {
         taskName?: string;
         url?: string;
         endpointName?: string;
         skipDomainSkill?: boolean;
+        /** Always open a new tab, skipping the abandoned-task reclaim. */
+        fresh?: boolean;
         /** Caller identity, forwarded from the CLI (see IPCRequest.actor/launchId). */
         actor?: string;
         launchId?: string;
@@ -95,6 +102,54 @@ export declare class BrowserService {
         profile: string;
         skill?: ResolvedDomainSkill;
     }>;
+    /**
+     * Reclaim a live page already showing `url` from an ABANDONED task, instead
+     * of opening a second copy of the same page (RUSH-2622). Returns its CDP
+     * targetId, or undefined when there is nothing safe to reclaim.
+     *
+     * "Safe" is narrow on purpose, because both of the wider readings close a tab
+     * somebody is using:
+     *
+     *   - An UNOWNED matching page is NOT taken. No task claims it, which most
+     *     often means the user opened it themselves — and adopting it would make
+     *     this task's `done` close the user's tab.
+     *   - A page owned by a LIVE task is NOT taken. Stealing it would leave that
+     *     agent's `screenshot`/`click` throwing "No tabs open for this task", its
+     *     `navigate` silently opening the duplicate this feature exists to
+     *     prevent, and any in-flight recording truncated when the new owner calls
+     *     `done`.
+     *
+     * What is left is exactly the pile-up case: a page held by a task whose owner
+     * is provably gone. Liveness uses the reaper's own predicate
+     * (`taskOwnerIsGone`), so "dead" has one definition in this codebase rather
+     * than two that can drift. A task the reaper cannot prove dead keeps its tab
+     * and is closed later by the idle rule instead.
+     *
+     * Reclaiming transfers rather than shares: two tasks holding one targetId
+     * means the first `done` closes the other's tab. `start --fresh` skips this
+     * path entirely.
+     *
+     * URLs are compared canonically (`new URL(...).href`), so a requested
+     * `https://example.com` matches the `https://example.com/` Chrome reports. A
+     * page that has since redirected elsewhere simply does not match, and the
+     * caller opens a tab as before.
+     */
+    private adoptTabShowing;
+    /**
+     * Every live task across every connected profile — the reaper's input
+     * (`hygiene.ts`). A read-only view: mutating a returned `Task` mutates the
+     * daemon's live state, so callers only read it and act through `stop`.
+     */
+    listTasks(): Array<{
+        profile: string;
+        task: Task;
+    }>;
+    /**
+     * Close tasks whose owning agent session is gone, or that have sat untouched
+     * past the idle window. The entry point the daemon's periodic tick and
+     * `agents browser gc` both call; the policy lives in `hygiene.ts`.
+     */
+    reapAbandoned(opts?: ReapOptions): Promise<ReapResult>;
     stop(taskName: string): Promise<{
         ok: boolean;
         profile?: string;
@@ -281,6 +336,25 @@ export declare class BrowserService {
     private getOrCreateWindow;
     private hasTaskNamed;
     private generateUniqueTaskName;
+    /**
+     * Mark a task as active, so the reaper's idle window measures time since the
+     * last real use rather than time since `start` (RUSH-2622).
+     *
+     * Called from `findTask` — the single funnel every task-scoped operation
+     * resolves through — rather than from each of the ~26 call sites, so a new
+     * action added later cannot forget to stamp it.
+     *
+     * The in-memory stamp is what the reaper reads: it runs inside the same
+     * daemon that owns these `Task` objects. The write to tasks.json exists only
+     * so a daemon RESTART does not inherit a stale stamp and reap a task an agent
+     * has been clicking through for the last half hour — `click`, `type`,
+     * `evaluate`, and `screenshot` never call `saveTaskState` on their own, so
+     * without this the on-disk stamp would sit at the last navigation. It is
+     * coalesced to at most one write per profile per minute so a screenshot loop
+     * does not become a write loop; the resulting on-disk stamp trails by at most
+     * a minute, well inside the 30-minute idle window.
+     */
+    private touchTask;
     private findTask;
     private getTabsForTask;
     private getProfileStatus;

package/dist/lib/browser/service.js

@@ -9,6 +9,7 @@ import { connectSSH, shellQuote } from './drivers/ssh.js';
 import { clearProfileRuntime, listProfileCacheDirs, readProfileRuntimeMeta, isProcessAlive } from './runtime-state.js';
 import { resolveDomainSkill } from './domain-skills.js';
 import { generateTaskId, generateShortId, generateTaskName, } from './types.js';
+import { reapAbandonedTasks, resolveLiveIdentities, taskOwnerIsGone, } from './hygiene.js';
 import { getRefs, resolveRefToCoords, describeRefs, healRef } from './refs.js';
 import { clickAtCoords, hoverAtCoords, scrollAtCoords, typeText, pressKey, focusNode } from './input.js';
 import { typeEditorText } from './editor.js';
@@ -17,6 +18,20 @@ import { emit } from '../events.js';
 import { resolveActor } from '../actor.js';
 import { recordBrowserSession } from '../session/db.js';
 import { sshExecAsync } from '../ssh-exec.js';
+/**
+ * Canonical form for comparing a requested URL against what CDP reports for a
+ * live target. `new URL('https://example.com').href` is `https://example.com/`,
+ * which is exactly what Chrome reports — comparing the raw strings would miss
+ * every bare-origin match. Unparseable input compares as itself.
+ */
+function canonicalTabUrl(raw) {
+    try {
+        return new URL(raw).href;
+    }
+    catch {
+        return raw;
+    }
+}
 function isPathInside(candidate, dir) {
     const rel = path.relative(dir, candidate);
     return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel));
@@ -252,6 +267,10 @@ export class BrowserService {
     networkRequests = new Map();
     pendingDownloads = new Map();
     enabledSessions = new Map(); // sessionId -> enabled domains
+    /** Profile -> when a `touchTask` last persisted tasks.json for it. */
+    lastTouchPersist = new Map();
+    /** Coalescing window for the `touchTask` write. See {@link touchTask}. */
+    static TOUCH_PERSIST_INTERVAL_MS = 60_000;
     async start(profileName, opts = {}) {
         const profile = await getProfile(profileName);
         if (!profile) {
@@ -331,23 +350,37 @@ export class BrowserService {
         // Browsers launch with --no-startup-window (session-cookie persistence,
         // see launchBrowser), so a bare `start` with no --url would otherwise
         // leave the user staring at a process with zero windows. Recreate the
-        // old startup-window affordance: if no page target exists, open a blank
-        // one. Deliberately NOT registered on the task — the startup window
-        // never was either, and tasks track only tabs they created.
+        // old startup-window affordance: if no page target exists, open a blank one.
+        //
+        // This tab IS registered on the task below. It used to be deliberately
+        // unregistered ("tasks track only tabs they created") — but this daemon did
+        // create it, and an unregistered tab is one `done`/`stop` can never close:
+        // `stop` closes exactly the entries in `task.tabs`. So every bare `start`
+        // left a blank globe tab behind forever, which is a large share of the
+        // pile-up in RUSH-2622. Tabs the daemon did NOT open are still left alone —
+        // the branch only fires when the profile has no page target at all.
+        let startupBlankTargetId;
         if (!opts.url && !conn.electron) {
             const { targetInfos } = (await conn.cdp.send('Target.getTargets'));
             if (!targetInfos.some((t) => t.type === 'page')) {
-                await conn.cdp.send('Target.createTarget', { url: 'about:blank' });
+                const created = (await conn.cdp.send('Target.createTarget', {
+                    url: 'about:blank',
+                }));
+                startupBlankTargetId = created.targetId;
                 this.invalidateTargetCache(conn);
             }
         }
+        const now = Date.now();
         const task = {
             id: taskId,
             name: taskName,
             profile: effectiveProfileName,
             tabs: {},
             currentTabId: undefined,
-            createdAt: Date.now(),
+            createdAt: now,
+            // A brand-new task has done exactly one thing — start — so its last
+            // action is its creation. The reaper's idle window runs from here.
+            lastActionAt: now,
             pid: conn.pid,
             // Identity is forwarded from the caller (see resolveTaskIdentity): WHO
             // (owner), WHICH run (launchId), and WHICH agent session (sessionId).
@@ -355,6 +388,11 @@ export class BrowserService {
             // actor (the RUSH-2020 bug).
             ...resolveTaskIdentity({ actor: opts.actor, launchId: opts.launchId, sessionId: opts.sessionId }, () => resolveActor().id),
         };
+        if (startupBlankTargetId) {
+            const shortId = generateShortId();
+            task.tabs[shortId] = startupBlankTargetId;
+            task.currentTabId = shortId;
+        }
         // For Electron, get the existing window as the tab
         if (conn.electron) {
             const windowId = await this.getOrCreateWindow(conn);
@@ -400,14 +438,17 @@ export class BrowserService {
                 meta: { task: taskName },
             });
         }).catch(() => { });
-        // If URL provided, create tab directly (no about:blank)
+        // If URL provided, reclaim a tab an abandoned task is holding on it, else
+        // create one directly (no about:blank).
         let tabId;
         if (opts.url && !conn.electron) {
-            const result = (await conn.cdp.send('Target.createTarget', {
-                url: opts.url,
-            }));
+            const adopted = opts.fresh ? undefined : await this.adoptTabShowing(conn, opts.url);
+            const targetId = adopted ??
+                (await conn.cdp.send('Target.createTarget', {
+                    url: opts.url,
+                })).targetId;
             const shortId = generateShortId();
-            task.tabs[shortId] = result.targetId;
+            task.tabs[shortId] = targetId;
             task.currentTabId = shortId;
             this.invalidateTargetCache(conn);
             await this.saveTaskState(effectiveProfileName, conn.tasks);
@@ -428,6 +469,110 @@ export class BrowserService {
         }
         return { task: taskId, name: taskName, tabId, profile: effectiveProfileName, skill };
     }
+    /**
+     * Reclaim a live page already showing `url` from an ABANDONED task, instead
+     * of opening a second copy of the same page (RUSH-2622). Returns its CDP
+     * targetId, or undefined when there is nothing safe to reclaim.
+     *
+     * "Safe" is narrow on purpose, because both of the wider readings close a tab
+     * somebody is using:
+     *
+     *   - An UNOWNED matching page is NOT taken. No task claims it, which most
+     *     often means the user opened it themselves — and adopting it would make
+     *     this task's `done` close the user's tab.
+     *   - A page owned by a LIVE task is NOT taken. Stealing it would leave that
+     *     agent's `screenshot`/`click` throwing "No tabs open for this task", its
+     *     `navigate` silently opening the duplicate this feature exists to
+     *     prevent, and any in-flight recording truncated when the new owner calls
+     *     `done`.
+     *
+     * What is left is exactly the pile-up case: a page held by a task whose owner
+     * is provably gone. Liveness uses the reaper's own predicate
+     * (`taskOwnerIsGone`), so "dead" has one definition in this codebase rather
+     * than two that can drift. A task the reaper cannot prove dead keeps its tab
+     * and is closed later by the idle rule instead.
+     *
+     * Reclaiming transfers rather than shares: two tasks holding one targetId
+     * means the first `done` closes the other's tab. `start --fresh` skips this
+     * path entirely.
+     *
+     * URLs are compared canonically (`new URL(...).href`), so a requested
+     * `https://example.com` matches the `https://example.com/` Chrome reports. A
+     * page that has since redirected elsewhere simply does not match, and the
+     * caller opens a tab as before.
+     */
+    async adoptTabShowing(conn, url) {
+        const { targetInfos } = (await conn.cdp.send('Target.getTargets'));
+        const wanted = canonicalTabUrl(url);
+        const matching = new Set(targetInfos
+            .filter((t) => t.type === 'page' && canonicalTabUrl(t.url) === wanted)
+            .map((t) => t.targetId));
+        if (matching.size === 0)
+            return undefined;
+        const candidates = [];
+        for (const task of conn.tasks.values()) {
+            for (const [shortId, cdpId] of Object.entries(task.tabs)) {
+                if (matching.has(cdpId))
+                    candidates.push({ task, shortId, targetId: cdpId });
+            }
+        }
+        if (candidates.length === 0)
+            return undefined;
+        const live = resolveLiveIdentities();
+        for (const { task, shortId, targetId } of candidates) {
+            // An in-flight capture means the task is in use whatever its owner looks
+            // like — same guard the reaper applies before stopping anything.
+            if (this.recordings.has(task.name))
+                continue;
+            if (!(await taskOwnerIsGone(task, live)))
+                continue;
+            // Re-check the claim after the await. Nothing serializes IPC requests —
+            // `BrowserIPCServer` registers a per-connection `socket.on('data', async …)`
+            // that Node never awaits — so two concurrent `start`s can both pass the
+            // liveness check on one candidate and both return the same targetId,
+            // putting two live tasks on one tab and re-opening the double-owner bug
+            // this reclaim is careful to avoid. Whoever deletes it first owns it.
+            if (task.tabs[shortId] !== targetId)
+                continue;
+            delete task.tabs[shortId];
+            delete task.refDescriptors?.[shortId];
+            if (task.currentTabId === shortId) {
+                const remaining = Object.keys(task.tabs);
+                task.currentTabId = remaining.length > 0 ? remaining[remaining.length - 1] : undefined;
+            }
+            try {
+                await conn.cdp.send('Target.activateTarget', { targetId });
+            }
+            catch {
+                // Bringing the tab to the front is cosmetic and not every endpoint
+                // implements activateTarget; the tab is reclaimed either way.
+            }
+            return targetId;
+        }
+        return undefined;
+    }
+    /**
+     * Every live task across every connected profile — the reaper's input
+     * (`hygiene.ts`). A read-only view: mutating a returned `Task` mutates the
+     * daemon's live state, so callers only read it and act through `stop`.
+     */
+    listTasks() {
+        const out = [];
+        for (const [key, conn] of this.connections) {
+            for (const task of conn.tasks.values()) {
+                out.push({ profile: conn.profileName ?? key, task });
+            }
+        }
+        return out;
+    }
+    /**
+     * Close tasks whose owning agent session is gone, or that have sat untouched
+     * past the idle window. The entry point the daemon's periodic tick and
+     * `agents browser gc` both call; the policy lives in `hygiene.ts`.
+     */
+    async reapAbandoned(opts = {}) {
+        return reapAbandonedTasks(this, opts);
+    }
     async stop(taskName) {
         for (const [profileName, conn] of this.connections) {
             const task = conn.tasks.get(taskName);
@@ -1877,6 +2022,41 @@ export class BrowserService {
         }
         throw new Error('Could not generate unique task name after 8 attempts');
     }
+    /**
+     * Mark a task as active, so the reaper's idle window measures time since the
+     * last real use rather than time since `start` (RUSH-2622).
+     *
+     * Called from `findTask` — the single funnel every task-scoped operation
+     * resolves through — rather than from each of the ~26 call sites, so a new
+     * action added later cannot forget to stamp it.
+     *
+     * The in-memory stamp is what the reaper reads: it runs inside the same
+     * daemon that owns these `Task` objects. The write to tasks.json exists only
+     * so a daemon RESTART does not inherit a stale stamp and reap a task an agent
+     * has been clicking through for the last half hour — `click`, `type`,
+     * `evaluate`, and `screenshot` never call `saveTaskState` on their own, so
+     * without this the on-disk stamp would sit at the last navigation. It is
+     * coalesced to at most one write per profile per minute so a screenshot loop
+     * does not become a write loop; the resulting on-disk stamp trails by at most
+     * a minute, well inside the 30-minute idle window.
+     */
+    async touchTask(conn, task) {
+        const now = Date.now();
+        task.lastActionAt = now;
+        const last = this.lastTouchPersist.get(task.profile) ?? 0;
+        if (now - last < BrowserService.TOUCH_PERSIST_INTERVAL_MS)
+            return;
+        this.lastTouchPersist.set(task.profile, now);
+        try {
+            await this.saveTaskState(task.profile, conn.tasks);
+        }
+        catch {
+            // Durability here is best-effort — the in-memory stamp above is
+            // authoritative for the running daemon — and an unwritable runtime dir
+            // must not turn a working browser action into a failure. Same guard the
+            // `recordBrowserSession` call in `start` uses for the same reason.
+        }
+    }
     async findTask(taskId, profileName) {
         if (profileName) {
             const conn = this.connections.get(profileName);
@@ -1887,11 +2067,13 @@ export class BrowserService {
             if (!task) {
                 throw new Error(`Task "${taskId}" not found on profile "${profileName}"`);
             }
+            await this.touchTask(conn, task);
             return { conn, task, profileName };
         }
         for (const [key, conn] of this.connections) {
             const task = conn.tasks.get(taskId);
             if (task) {
+                await this.touchTask(conn, task);
                 return { conn, task, profileName: conn.profileName ?? key };
             }
         }
@@ -2055,11 +2237,19 @@ export class BrowserService {
                     tabs,
                     currentTabId: tabIds.length > 0 ? tabIds[tabIds.length - 1] : undefined,
                     createdAt: task.createdAt,
+                    lastActionAt: task.lastActionAt ?? task.createdAt,
                     pid: task.pid,
                 });
             }
             else {
-                tasks.set(key, task);
+                const loaded = task;
+                // Tasks persisted before RUSH-2622 carry no lastActionAt. Normalize on
+                // read so every in-memory task has one: its own createdAt is the last
+                // moment we can prove the task did anything.
+                if (typeof loaded.lastActionAt !== 'number') {
+                    loaded.lastActionAt = loaded.createdAt;
+                }
+                tasks.set(key, loaded);
             }
         }
         // Save migrated data back to disk