@phnx-labs/agents-cli 1.22.60 → 1.22.61

package/dist/lib/accounting/rotate.js

@@ -131,6 +131,26 @@ export function isUsageVerified(candidate, nowMs = Date.now()) {
         return false;
     return nowMs - capturedAt.getTime() <= USAGE_DECISION_MAX_AGE_MS;
 }
+/**
+ * Whether this candidate carries a STALE-but-present usage number: a snapshot
+ * with windows whose capture time is older than {@link USAGE_DECISION_MAX_AGE_MS}.
+ *
+ * This is the misleading case the initial route must refuse — the number reads
+ * "48% used" with the same confidence whether captured a minute or three days
+ * ago, and a box whose refresh is failing stays wrong indefinitely. It is
+ * deliberately NARROWER than "not verified": a BLIND candidate with no snapshot
+ * (or a plan-only meterless one with no windows) carries no number to be misled
+ * by — a worker box whose usage endpoint 403s (RUSH-2392), or a meterless Grok
+ * login — so it is not "stale", and an entirely-blind pool still draws a pick
+ * (PHNX-3392) rather than fail loud with NO_VERIFIED_USAGE.
+ */
+export function hasStaleUsage(candidate, nowMs = Date.now()) {
+    const snapshot = candidate.usageSnapshot;
+    const capturedAt = snapshot?.capturedAt;
+    if (!capturedAt || !snapshot?.windows.length)
+        return false;
+    return nowMs - capturedAt.getTime() > USAGE_DECISION_MAX_AGE_MS;
+}
 function hasUsageAvailable(candidate) {
     const snapshot = candidate.usageSnapshot;
     if (snapshot) {
@@ -313,8 +333,8 @@ export function pickBalancedCandidate(candidates, nowMs = Date.now()) {
         if (!deduped.has(c))
             excluded.push(c);
     }
-    const { picked, usageUnverified } = preferVerified(sorted, nowMs, (from) => weightedRandomByCapacity(from, nowMs), 'representative');
-    return { picked, healthy: sorted, excluded, usageUnverified };
+    const { picked, usageUnverified, noVerifiedUsage } = preferVerified(sorted, nowMs, (from) => weightedRandomByCapacity(from, nowMs), 'representative');
+    return { picked, healthy: sorted, excluded, usageUnverified, noVerifiedUsage };
 }
 /**
  * Choose from the VERIFIED candidates when they are a representative share of
@@ -361,9 +381,17 @@ function preferVerified(pool, nowMs, choose, narrowing = 'any-verified') {
     const narrow = verified.length > 0 &&
         (narrowing === 'any-verified' || verified.length >= Math.ceil(pool.length / 2));
     const picked = choose(narrow ? verified : pool);
+    // Entirely-stale = zero verified AND at least one stale-but-present number. A
+    // BLIND pool (no snapshots at all) does NOT trip this — it carries no
+    // misleading figure, so it still draws a pick (see {@link hasStaleUsage}). The
+    // chosen `picked` is still returned so `healthy` (which includes it) stays
+    // whole for bounded post-rejection failover; the INITIAL selection acts on
+    // this flag instead of launching that stale pick.
+    const noVerifiedUsage = verified.length === 0 && pool.some((c) => hasStaleUsage(c, nowMs));
     return {
         picked,
         usageUnverified: !isUsageVerified(picked, nowMs),
+        noVerifiedUsage,
     };
 }
 // capacityWeight + PROJECTION_HORIZON_MIN moved to ./capacity.js (a pure,
@@ -424,13 +452,19 @@ export function pickAvailableCandidate(candidates, preferredVersion, nowMs = Dat
     // unconfirmed "48% used" outranks an accurate "90% used" — the same inversion
     // that put a launch on an exhausted account under `balanced`. It routes on the
     // same cache, so it gets the same rule: confirmed headroom first.
-    const { picked: bestVerified, usageUnverified } = preferVerified(sorted, nowMs, (from) => from[0]);
+    const { picked: bestVerified, usageUnverified, noVerifiedUsage } = preferVerified(sorted, nowMs, (from) => from[0]);
     // An explicit version preference is an instruction, not a ranking signal, so it
     // still wins — but only while that version is actually eligible.
     const preferred = preferredVersion
         ? sorted.find((candidate) => candidate.version === preferredVersion)
         : undefined;
-    return { picked: preferred ?? bestVerified, healthy: sorted, excluded, usageUnverified };
+    // `noVerifiedUsage` rides along even when a `preferred` default resolves: an
+    // all-stale pool can only make `preferred` a stale pick too (a verified
+    // preferred would make verified.length > 0), and auto-selecting the default
+    // pin on a stale number is the very thing PHNX-2526 refuses. The initial
+    // route (resolveRunVersion) acts on the flag; the failover chain keeps
+    // `healthy` regardless.
+    return { picked: preferred ?? bestVerified, healthy: sorted, excluded, usageUnverified, noVerifiedUsage };
 }
 /**
  * Classify every harness's candidates into healthy (with a representative
@@ -547,6 +581,37 @@ export function formatNoHealthyAccountError(agent, strategy, excluded, nowMs = D
     const resetSummary = formatResetSummary(earliestResetAcross(excluded, nowMs));
     return `agents: no healthy ${agent} account under strategy '${strategy}' — excluded: ${excludedStr}; earliest window resets ${resetSummary}. Use --strategy pinned to force the default.`;
 }
+/**
+ * How old this candidate's usage snapshot is, in whole minutes, or null when it
+ * carries no dated snapshot (a blind account). Used only to explain WHY a route
+ * was refused as unverified — never to route on.
+ */
+function snapshotAgeMinutes(candidate, nowMs) {
+    const capturedAt = candidate.usageSnapshot?.capturedAt;
+    if (!capturedAt || !candidate.usageSnapshot?.windows.length)
+        return null;
+    return Math.max(0, Math.round((nowMs - capturedAt.getTime()) / 60_000));
+}
+/**
+ * The all-stale-usage error (PHNX-2526) an UNATTENDED `balanced`/`available`
+ * run fails loud with when no account's usage is fresh enough to route on. EXACT
+ * contract — it MUST contain the literal `NO_VERIFIED_USAGE` so a machine caller
+ * (and the Factory watchdog) can tail-detect it distinctly from the
+ * `no healthy` throttle error, which is a different condition (throttled vs
+ * merely stale). Names each candidate with how stale its snapshot is, so the
+ * operator can see the failing-refresh box rather than guess.
+ */
+export function formatNoVerifiedUsageError(agent, strategy, candidates, nowMs = Date.now()) {
+    const detail = candidates.length === 0
+        ? 'no signed-in accounts'
+        : candidates.map((c) => {
+            const age = snapshotAgeMinutes(c, nowMs);
+            const staleness = age === null ? 'no usage snapshot' : `usage ${age}m old`;
+            return `${c.version} (${staleness})`;
+        }).join(', ');
+    const maxAgeMin = Math.round(USAGE_DECISION_MAX_AGE_MS / 60_000);
+    return `agents: NO_VERIFIED_USAGE — no signed-in ${agent} account has usage newer than ${maxAgeMin}m under strategy '${strategy}', so routing refuses to guess on a stale number: ${detail}. Refresh usage (agents view ${agent}) or pin the default with --strategy pinned.`;
+}
 /**
  * The zero-healthy-harness error for `agents run auto` — names each harness's
  * exclusion reason plus the earliest reset across all snapshots.
@@ -724,6 +789,141 @@ function readRotationStamp(agent) {
     catch { /* missing or corrupt — treat as no stamp */ }
     return null;
 }
+/** Cap on candidates serialized into a rotation decision event — a pathological
+ *  backstop on the log line; a real fleet is ~19 accounts, well under it. The
+ *  candidates are emitted as a keyed OBJECT (not an array) so the event sink's
+ *  generic `sanitizeNested` does not truncate them to its 10-element array cap
+ *  (feed/events.ts) — an object is recursed uncapped, so the whole pool up to
+ *  this bound survives. */
+const ROTATION_EVENT_CANDIDATE_CAP = 32;
+/**
+ * Compact, queryable descriptor of ONE candidate exactly as the router saw it,
+ * for the `rotation.resolved`/`rotation.unresolved` event. These are the fields
+ * that disambiguate WHY a route landed on a bad account, so a post-mortem reads
+ * them from `agents events` instead of guessing:
+ *
+ * - `usageKey` is the per-org quota key — the ONLY identity that joins the same
+ *   account across devices (version numbers are device-local and meaningless
+ *   across the fleet).
+ * - `tier` is the freshness class the weighting actually used: `verified`
+ *   (fresh windowed → routed at real headroom), `stale` (windowed but past the
+ *   {@link USAGE_DECISION_MAX_AGE_MS} decision window → floored weight), `blind`
+ *   (no snapshot at all — a worker whose usage endpoint 403s, or a never-synced
+ *   network:false harness → still drawn at floor weight).
+ * - `source`/`ageMs`/`capturedAt` expose staleness and provenance: a `last_seen`
+ *   snapshot showing `tier: verified` with a large `ageMs` is the cross-host
+ *   clock-skew failure (capturedAt is stamped by the reading host's clock, this
+ *   `ageMs` by the routing host's — they disagree under skew).
+ */
+function describeRotationCandidate(c, nowMs) {
+    const snap = c.usageSnapshot;
+    const capturedAtMs = snap?.capturedAt ? snap.capturedAt.getTime() : null;
+    const tier = isUsageVerified(c, nowMs) ? 'verified' : hasStaleUsage(c, nowMs) ? 'stale' : 'blind';
+    const readiness = readinessFromCandidate(c);
+    return {
+        usageKey: c.usageKey,
+        // A RUSH-3182 provider/setup-token account carries a null usageKey and
+        // shares its `version` with the native login and every sibling provider
+        // account, so neither is a unique identity here. `accountKey` is the pool's
+        // own dedup boundary (foldRegistryCandidates), and `providerAccount` names
+        // the injected account — together they keep same-version rows distinct.
+        accountKey: c.accountKey,
+        providerAccount: c.providerAccount ?? null,
+        email: c.email,
+        version: c.version,
+        signedIn: c.signedIn,
+        // NOT `authVerdict`: the event sink's generic sanitizer redacts any payload
+        // key matching /auth/i to "[REDACTED]" (feed/events.ts SENSITIVE_PAYLOAD_KEY),
+        // which would silently blank this field on every row. `credentialVerdict`
+        // carries the same value ('revoked'/null/…) past the redaction.
+        credentialVerdict: c.authVerdict,
+        usageStatus: c.usageStatus,
+        tier,
+        source: snap?.source ?? null,
+        sourceLabel: snap?.sourceLabel ?? null,
+        capturedAt: snap?.capturedAt ? snap.capturedAt.toISOString() : null,
+        ageMs: capturedAtMs === null ? null : nowMs - capturedAtMs,
+        windows: (snap?.windows ?? []).map((w) => ({ key: w.key, usedPercent: Math.round(w.usedPercent) })),
+        unavailable: snap?.unavailable?.reason ?? null,
+        eligible: readiness.ready,
+        excludedReason: readiness.ready ? null : readiness.reason,
+    };
+}
+/**
+ * Build the enriched `rotation.resolved`/`rotation.unresolved` event payload:
+ * the full candidate pool as the router saw it, the pick and WHY, and a
+ * freshness tally. Replaces the old `{ version, healthy: <n>, excluded: <n> }`
+ * shape, which recorded only counts and a device-local version and so could not
+ * tell a blind-pool draw from a skewed-verified pick from a refused-stale route
+ * — the exact ambiguity that keeps a bad pick undebuggable from the log. All
+ * candidates share ONE `nowMs` so their `tier`/`ageMs` are mutually consistent.
+ */
+export function buildRotationDecisionEvent(rotation, agent, strategy) {
+    const nowMs = Date.now();
+    const tally = { verified: 0, stale: 0, blind: 0 };
+    for (const c of rotation.healthy) {
+        const t = isUsageVerified(c, nowMs) ? 'verified' : hasStaleUsage(c, nowMs) ? 'stale' : 'blind';
+        tally[t] += 1;
+    }
+    const pickedTier = isUsageVerified(rotation.picked, nowMs)
+        ? 'verified'
+        : hasStaleUsage(rotation.picked, nowMs)
+            ? 'stale'
+            : 'blind';
+    // WHY the pick: a verified-weighted draw is the healthy path; an
+    // `unverified-*-draw` names the fallback the router was forced into (a blind
+    // worker pool, or a stale-but-plausible number); `refused-no-verified` is the
+    // fail-closed exit where no version launches. Read straight from the result's
+    // own `usageUnverified`/`noVerifiedUsage`, so the event can never disagree
+    // with what rotation actually did.
+    const pickReason = rotation.noVerifiedUsage
+        ? 'refused-no-verified'
+        : rotation.usageUnverified
+            ? `unverified-${pickedTier}-draw`
+            : 'verified-weighted';
+    const pool = [...rotation.healthy, ...rotation.excluded];
+    return {
+        module: 'rotate',
+        agent,
+        strategy,
+        version: rotation.picked.version,
+        picked: {
+            usageKey: rotation.picked.usageKey,
+            email: rotation.picked.email,
+            version: rotation.picked.version,
+            tier: pickedTier,
+        },
+        pickReason,
+        healthy: rotation.healthy.length,
+        excluded: rotation.excluded.length,
+        freshness: tally,
+        // An OBJECT (not an array), so the sink cannot truncate it to 10 entries
+        // (see ROTATION_EVENT_CANDIDATE_CAP). Keyed by POOL INDEX, not by version or
+        // usageKey: a RUSH-3182 provider-account pool has multiple candidates
+        // sharing one `version` AND a null `usageKey` (foldRegistryCandidates), so
+        // either would collide and silently drop rows via Object.fromEntries. The
+        // index is structural only; each row's identity is its `accountKey` /
+        // `usageKey` / `providerAccount`. `candidatesTotal` reveals cap overflow.
+        candidates: Object.fromEntries(pool.slice(0, ROTATION_EVENT_CANDIDATE_CAP).map((c, i) => [String(i), describeRotationCandidate(c, nowMs)])),
+        candidatesTotal: pool.length,
+    };
+}
+/**
+ * Build AND emit a rotation decision event without ever letting an observability
+ * bug crash a live route. `emit` swallows its own IO errors, but the payload
+ * ARGUMENT is evaluated before `emit` is called, so a future null-deref inside
+ * `describeRotationCandidate` would otherwise propagate into `resolveRunVersion`
+ * and abort the launch. This wraps both build and emit, so the worst case is a
+ * lost log line, never a failed run.
+ */
+function emitRotationDecision(event, rotation, agent, strategy, extra = {}) {
+    try {
+        emit(event, { ...buildRotationDecisionEvent(rotation, agent, strategy), ...extra });
+    }
+    catch {
+        /* observability must never break a route */
+    }
+}
 /**
  * Resolve the version `agents run` should use when the caller did not pin
  * one with `@version`. The caller supplies the effective strategy.
@@ -740,6 +940,21 @@ function readRotationStamp(agent) {
 export async function resolveRunVersion(agent, strategy, cwd = process.cwd(), collect = collectRunCandidates) {
     const fallback = resolveVersion(agent, cwd);
     const candidates = await collect(agent);
+    // Entirely stale usage (PHNX-2526): every eligible account carries a
+    // stale-but-present number and none is verified. Refuse to auto-pick on a
+    // number that looks plausible but is wrong. `rotation` is returned so its
+    // `healthy` set survives for BOUNDED post-rejection failover, but `version`
+    // is null so the caller diverts — interactive to the account picker,
+    // unattended to a loud NO_VERIFIED_USAGE exit. Shared across BOTH rotating
+    // paths (the pinned auth-blocked-pin fallback AND balanced/available), since
+    // both reuse `pickAvailableCandidate`/`pickBalancedCandidate` and neither may
+    // launch a stale pick.
+    const refuseStaleUsage = (rotation) => {
+        emitRotationDecision('rotation.unresolved', rotation, agent, strategy, {
+            reason: 'no_verified_usage',
+        });
+        return { version: null, rotation, noVerifiedUsage: true };
+    };
     if (strategy === 'pinned') {
         const pinnedCandidate = fallback
             ? candidates.find((c) => c.version === fallback)
@@ -748,15 +963,14 @@ export async function resolveRunVersion(agent, strategy, cwd = process.cwd(), co
         // guaranteed miss. Prefer a signed-in sibling on this device.
         if (pinnedCandidate && isSignInRecoverable(readinessFromCandidate(pinnedCandidate))) {
             const rotation = pickAvailableCandidate(candidates, fallback);
+            // The auth-blocked pin rotates to a sibling — an initial selection, so it
+            // gets the same verified-only gate as balanced/available. Without this, a
+            // revoked pin with only stale siblings launched one blind (the yosemite-s1
+            // trap through the pinned path — PR #3295 review).
+            if (rotation && rotation.noVerifiedUsage)
+                return refuseStaleUsage(rotation);
             if (rotation) {
-                emit('rotation.resolved', {
-                    module: 'rotate',
-                    agent,
-                    version: rotation.picked.version,
-                    strategy,
-                    healthy: rotation.healthy.length,
-                    excluded: rotation.excluded.length,
-                });
+                emitRotationDecision('rotation.resolved', rotation, agent, strategy);
                 return { version: rotation.picked.version, rotation };
             }
             return {
@@ -770,6 +984,8 @@ export async function resolveRunVersion(agent, strategy, cwd = process.cwd(), co
     const rotation = strategy === 'available'
         ? pickAvailableCandidate(candidates, fallback)
         : pickBalancedCandidate(candidates);
+    if (rotation && rotation.noVerifiedUsage)
+        return refuseStaleUsage(rotation);
     if (rotation) {
         // `available` is sticky to the pinned default when healthy. Use the 60s
         // anti-collision stamp to nudge parallel callers off the same version.
@@ -784,7 +1000,7 @@ export async function resolveRunVersion(agent, strategy, cwd = process.cwd(), co
             }
             recordRotationPick(agent, rotation.picked.version);
         }
-        emit('rotation.resolved', { module: 'rotate', agent, version: rotation.picked.version, strategy, healthy: rotation.healthy.length, excluded: rotation.excluded.length });
+        emitRotationDecision('rotation.resolved', rotation, agent, strategy);
         return { version: rotation.picked.version, rotation };
     }
     return { version: fallback, rotation: null, exhausted: candidates.length > 0 ? candidates : undefined };

package/dist/lib/browser/drivers/local.d.ts

@@ -5,6 +5,17 @@ export interface LocalConnection {
     port: number;
     pid: number;
 }
+/**
+ * Arc is single-instance: relaunching the Arc binary with a fresh
+ * `--user-data-dir` does not create a second debuggable process — macOS routes
+ * the launch to the running Arc, which was started with no debug port, so the
+ * spawn produces a stray window and no CDP endpoint (issue #2779). agents
+ * browser therefore ATTACHES to the user's running Arc and never launches its
+ * own. When the running Arc exposes no CDP endpoint on the profile's port, we
+ * fail loud with the one relaunch that fixes it rather than silently spawning a
+ * duplicate. Exported so the contract is unit-testable without a real Arc.
+ */
+export declare function arcAttachRequiredError(profileName: string, port: number): Error;
 export declare function connectLocal(endpoint: string, profile: BrowserProfile, 
 /**
  * Runtime key (`<profile>@<endpoint>`) the launched browser's user-data-dir,

package/dist/lib/browser/drivers/local.js

@@ -31,6 +31,24 @@ const TUNNEL_PROCESS_NAMES = new Set(['ssh', 'autossh', 'mosh-client', 'socat'])
 function isTunnelProcess(command) {
     return TUNNEL_PROCESS_NAMES.has(command.toLowerCase());
 }
+/**
+ * Arc is single-instance: relaunching the Arc binary with a fresh
+ * `--user-data-dir` does not create a second debuggable process — macOS routes
+ * the launch to the running Arc, which was started with no debug port, so the
+ * spawn produces a stray window and no CDP endpoint (issue #2779). agents
+ * browser therefore ATTACHES to the user's running Arc and never launches its
+ * own. When the running Arc exposes no CDP endpoint on the profile's port, we
+ * fail loud with the one relaunch that fixes it rather than silently spawning a
+ * duplicate. Exported so the contract is unit-testable without a real Arc.
+ */
+export function arcAttachRequiredError(profileName, port) {
+    return new Error(`Arc is not exposing a CDP endpoint on cdp://127.0.0.1:${port} for profile ` +
+        `"${profileName}". Arc is single-instance — agents browser attaches to your ` +
+        `RUNNING Arc and never launches a second one, so it will not start an isolated ` +
+        `Arc for you. Quit Arc, then relaunch it with remote debugging on this port:\n` +
+        `  open -a Arc --args --remote-debugging-port=${port}\n` +
+        `and retry. The port must match the profile's endpoint (\`agents browser profiles list\`).`);
+}
 export async function connectLocal(endpoint, profile, 
 /**
  * Runtime key (`<profile>@<endpoint>`) the launched browser's user-data-dir,
@@ -71,6 +89,14 @@ key) {
         if (err instanceof Error && err.message.startsWith('Browser identity mismatch')) {
             throw err;
         }
+        // Arc reached the catch, so the attach above failed: the running Arc is not
+        // serving CDP on this port. Never fall through to launchBrowser — that would
+        // spawn the duplicate/stray-window this ticket set out to end (#2779,
+        // PHNX-2399). Fail loud with the relaunch that makes the user's Arc
+        // attachable.
+        if (profile.browser === 'arc') {
+            throw arcAttachRequiredError(profile.name, port);
+        }
         // Distinguish "nothing listening on this port" (fine to launch fresh) from
         // "something is listening but it's not a debuggable browser" (bail loudly —
         // silently launching on a different port leads to confusing `pid 0` and

package/dist/lib/browser/profiles.js

@@ -513,13 +513,15 @@ export async function editProfile(name, patch) {
     const current = configToProfile(name, local.config, devices);
     const merged = { ...current, ...patch, name };
     const changed = Object.keys(patch).filter((k) => JSON.stringify(current[k]) !== JSON.stringify(merged[k]));
-    // A target filter only means anything for an Electron app, and the gate must
+    // A target filter only means anything for a profile that reuses an existing
+    // page target rather than creating one — an Electron app or Arc (which crashes
+    // on tab creation, so it drives an open tab / Space, PHNX-2399). The gate must
     // read the MERGED record: `--target-filter x` on a profile that is already
-    // electron is valid, and `--no-electron` on one that still carries a filter is
-    // not. Checking the patch alone would accept both.
-    if (merged.targetFilter && !merged.electron) {
-        throw new Error(`--target-filter only applies to an Electron profile. ` +
-            `Pass --electron, or clear the filter with --target-filter ''.`);
+    // electron/arc is valid, and `--no-electron` on a Chromium profile that still
+    // carries a filter is not. Checking the patch alone would accept both.
+    if (merged.targetFilter && !merged.electron && merged.browser !== 'arc') {
+        throw new Error(`--target-filter only applies to an Electron or Arc profile. ` +
+            `Pass --electron, use --browser arc, or clear the filter with --target-filter ''.`);
     }
     assertLocalPortFree(merged, { ignore: name });
     // Same rule as create: the binary lives on the remote for an SSH profile, so a

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

@@ -53,9 +53,10 @@ interface ProfileConnection {
     electron?: boolean;
     /**
      * The profile's declared browser family. Load-bearing for Arc: Arc answers
-     * `Browser.getVersion` but exposes zero CDP page targets and CRASHES on
-     * `Target.createTarget` (verified live, PR #2778), so any tab-creating path
-     * must refuse rather than crash the user's Arc. See `createPageTarget`.
+     * `Browser.getVersion` and DOES expose CDP page targets it honors `Page.navigate`
+     * on, but CRASHES on `Target.createTarget` (verified live, PR #2778), so any
+     * tab-CREATING path must refuse and drive an EXISTING tab instead rather than
+     * crash the user's Arc. See `createPageTarget` / `pickReusableTargetWithoutCreate`.
      */
     browserType?: BrowserType;
     /** Raw `url:<v>` / `title:<v>` filter copied from the profile config. */
@@ -88,11 +89,14 @@ interface ProfileConnection {
 /** Join error lines so callers get a next command, not a dead-end message. */
 export declare function actionable(...lines: string[]): string;
 /**
- * Arc answers `Browser.getVersion` (so a connection succeeds) but exposes zero
- * CDP page targets via every discovery method and CRASHES when a new tab is
- * requested via `Target.createTarget` (verified live, PR #2778). It is therefore
- * not drivable. This is the single clear, actionable error every tab-creating
- * path throws instead of crashing the user's Arc window.
+ * Arc DOES expose CDP page targets and honors `Page.navigate` on the ones the
+ * user already has open (measured live against Arc: 33 targets, PR #2786), so
+ * agents browser drives an attached Arc by reusing existing tabs. What it CANNOT
+ * survive is `Target.createTarget` — opening a brand-new tab crashes the user's
+ * Arc window (verified live, PR #2778). Tab creation is the one CDP-only op that
+ * fails clearly here (PHNX-2399): every tab-creating path throws this actionable
+ * error instead of crashing Arc, and steers the caller to reuse an existing
+ * tab/Space (via `--target-filter`) or to a Chromium-family browser for new tabs.
  */
 export declare function arcNotDrivableError(profileName?: string): Error;
 /** Derive a human label from an explicit title or a navigated URL. */

package/dist/lib/browser/service.js

@@ -247,15 +247,18 @@ export function actionable(...lines) {
     return lines.filter((l) => l != null && l !== '').join('\n');
 }
 /**
- * Arc answers `Browser.getVersion` (so a connection succeeds) but exposes zero
- * CDP page targets via every discovery method and CRASHES when a new tab is
- * requested via `Target.createTarget` (verified live, PR #2778). It is therefore
- * not drivable. This is the single clear, actionable error every tab-creating
- * path throws instead of crashing the user's Arc window.
+ * Arc DOES expose CDP page targets and honors `Page.navigate` on the ones the
+ * user already has open (measured live against Arc: 33 targets, PR #2786), so
+ * agents browser drives an attached Arc by reusing existing tabs. What it CANNOT
+ * survive is `Target.createTarget` — opening a brand-new tab crashes the user's
+ * Arc window (verified live, PR #2778). Tab creation is the one CDP-only op that
+ * fails clearly here (PHNX-2399): every tab-creating path throws this actionable
+ * error instead of crashing Arc, and steers the caller to reuse an existing
+ * tab/Space (via `--target-filter`) or to a Chromium-family browser for new tabs.
  */
 export function arcNotDrivableError(profileName) {
     const scope = profileName ? ` (profile "${profileName}")` : '';
-    return new Error(actionable(`Browser "arc"${scope} is not drivable: Arc exposes no CDP page targets and`, 'crashes when a new tab is requested, so `agents browser` cannot control it.', 'Use a Chromium-family browser instead — Comet, Chrome, Chromium, or Brave:', '  agents browser profiles create <name> --browser comet'));
+    return new Error(actionable(`Browser "arc"${scope} cannot open a NEW tab: Arc crashes when a tab is created`, 'over CDP (Target.createTarget). agents browser drives Arc by attaching to your', 'running window and reusing an EXISTING tab — bind the profile to the tab/Space you', 'want with --target-filter (url:<substring> or title:<substring>), or navigate to a', 'URL that is already open. To open brand-new tabs, use a Chromium-family browser:', '  agents browser profiles create <name> --browser comet'));
 }
 /** Derive a human label from an explicit title or a navigated URL. */
 export function deriveTaskLabel(opts) {
@@ -481,7 +484,7 @@ export class BrowserService {
         // 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) {
+        if (opts.url && !conn.electron && conn.browserType !== 'arc') {
             const adopted = opts.fresh ? undefined : await this.adoptTabShowing(conn, opts.url);
             const targetId = adopted ?? (await this.createPageTarget(conn, { url: opts.url })).targetId;
             const shortId = generateShortId();
@@ -491,7 +494,13 @@ export class BrowserService {
             await this.saveTaskState(effectiveKey, conn.tasks);
             tabId = shortId;
         }
-        else if (opts.url && conn.electron) {
+        else if (opts.url && (conn.electron || conn.browserType === 'arc')) {
+            // Electron and Arc share the reuse-in-place path: neither may open a fresh
+            // tab here (Electron drives its one window; Arc crashes on Target.createTarget),
+            // so the implicit first navigate attaches to an existing tab — honoring the
+            // profile's --target-filter — instead of throwing. This is what makes the
+            // documented `navigate --profile arc --url …` first-use workflow attach rather
+            // than refuse on a task-less profile (PHNX-2399 review).
             const result = await this.navigate(taskName, opts.url, effectiveKey);
             tabId = result.tabId;
         }
@@ -583,13 +592,32 @@ export class BrowserService {
             for (const id of Object.values(t.tabs))
                 owned.add(id);
         }
-        const free = targetInfos.filter((t) => t.type === 'page' && !owned.has(t.targetId));
+        let free = targetInfos.filter((t) => t.type === 'page' && !owned.has(t.targetId));
+        // A bound --target-filter (url:/title:<substring>) is how the profile names the
+        // tab/Space it drives — e.g. an Arc Space pinned with `--target-filter url:notion.so`.
+        // Scope the reusable set to tabs matching it; an explicit filter that matches nothing
+        // returns undefined so the caller refuses rather than borrowing an unrelated tab (the
+        // same contract pickWindowTarget holds for the tab-creating path). Without this the
+        // filter was accepted and stored but never consulted when driving Arc (PHNX-2399 review).
+        const parsed = parseTargetFilter(conn.targetFilter);
+        if (parsed) {
+            const needle = parsed.value.toLowerCase();
+            free = free.filter((t) => ((parsed.kind === 'url' ? t.url : t.title) ?? '').toLowerCase().includes(needle));
+            if (free.length === 0)
+                return undefined;
+        }
         const wanted = canonicalTabUrl(url);
         const sameUrl = free.find((t) => canonicalTabUrl(t.url) === wanted);
         if (sameUrl)
             return sameUrl.targetId;
         const BLANK = new Set(['', 'about:blank', 'about:newtab', 'chrome://newtab/', 'chrome://new-tab-page/']);
-        return free.find((t) => BLANK.has(t.url))?.targetId;
+        const blank = free.find((t) => BLANK.has(t.url));
+        if (blank)
+            return blank.targetId;
+        // With a filter set, every remaining tab already IS the bound Space, so reuse the
+        // first even when it is neither the exact URL nor blank — that is the target the
+        // operator pinned. With no filter, only an exact-URL or blank tab is safe to borrow.
+        return parsed ? free[0]?.targetId : undefined;
     }
     async adoptTabShowing(conn, url) {
         const { targetInfos } = (await conn.cdp.send('Target.getTargets'));

package/dist/lib/claude-statusline.d.ts

@@ -9,6 +9,7 @@ export declare const CLAUDE_STATUSLINE_COMMAND = "agents __claude-statusline";
 export declare function isStatusLineSelfReference(command: string): boolean;
 interface ClaudeStatusLinePayload {
     cwd?: string;
+    session_id?: string;
     workspace?: {
         current_dir?: string;
     };
@@ -29,7 +30,19 @@ interface ClaudeStatusLinePayload {
 }
 export declare function ingestClaudeStatusLineUsage(payload: ClaudeStatusLinePayload, versionHome: string): boolean;
 export declare function renderDelegate(payload: string, versionHome: string): string;
-export declare function renderClaudeStatusLine(payload: ClaudeStatusLinePayload, host?: string, delegated?: string): string;
+/**
+ * Format a reminder as a dimmed statusline part (empty string when none). The
+ * ◆ marker distinguishes it from the host/model/usage parts, and the ANSI dim
+ * keeps it quiet next to the live figures.
+ */
+export declare function formatReminderPart(short: string | undefined): string;
+export declare function renderClaudeStatusLine(payload: ClaudeStatusLinePayload, host?: string, delegated?: string, reminder?: string): string;
+/**
+ * Resolve the per-session reminder for the statusline, or '' when none is
+ * configured. A malformed reminders file is swallowed here on purpose — a broken
+ * prompt is worse than a missing reminder — while `agents reminders` surfaces it.
+ */
+export declare function resolveReminderPart(sessionId?: string): string;
 export declare function runClaudeStatusLine(): Promise<number>;
 export declare function installClaudeStatusLine(versionHome: string): {
     changed: boolean;

package/dist/lib/claude-statusline.js

@@ -5,6 +5,7 @@ import { spawnSync } from 'child_process';
 import { readClaudeHomeConfig } from './agent-spec/agents.js';
 import { atomicWriteFileSync } from './fs-atomic.js';
 import { mergeClaudeUsageCacheWindows } from './accounting/usage.js';
+import { loadReminders, pickReminderForSession } from './reminders.js';
 export const CLAUDE_STATUSLINE_COMMAND = 'agents __claude-statusline';
 const DELEGATE_FILE = path.join('.agents', 'claude-statusline-delegate');
 // The private subcommand this feature runs. It is only ever invoked internally,
@@ -103,7 +104,16 @@ export function renderDelegate(payload, versionHome) {
     });
     return result.status === 0 ? result.stdout.trim() : '';
 }
-export function renderClaudeStatusLine(payload, host = os.hostname().split('.')[0] || os.hostname(), delegated = '') {
+/**
+ * Format a reminder as a dimmed statusline part (empty string when none). The
+ * ◆ marker distinguishes it from the host/model/usage parts, and the ANSI dim
+ * keeps it quiet next to the live figures.
+ */
+export function formatReminderPart(short) {
+    const text = short?.trim();
+    return text ? `\x1b[2m◆ ${text}\x1b[22m` : '';
+}
+export function renderClaudeStatusLine(payload, host = os.hostname().split('.')[0] || os.hostname(), delegated = '', reminder = '') {
     const model = payload.model?.display_name?.trim() || payload.model?.id?.trim() || 'model pending';
     const parts = [host, model];
     if (delegated)
@@ -114,8 +124,23 @@ export function renderClaudeStatusLine(payload, host = os.hostname().split('.')[
         parts.push(`5h ${Math.round(fiveHour)}%`);
     if (Number.isFinite(sevenDay))
         parts.push(`7d ${Math.round(sevenDay)}%`);
+    if (reminder)
+        parts.push(reminder);
     return parts.join(' · ');
 }
+/**
+ * Resolve the per-session reminder for the statusline, or '' when none is
+ * configured. A malformed reminders file is swallowed here on purpose — a broken
+ * prompt is worse than a missing reminder — while `agents reminders` surfaces it.
+ */
+export function resolveReminderPart(sessionId) {
+    try {
+        return formatReminderPart(pickReminderForSession(loadReminders(), sessionId)?.short);
+    }
+    catch {
+        return '';
+    }
+}
 export async function runClaudeStatusLine() {
     const raw = await new Promise((resolve, reject) => {
         let input = '';
@@ -135,7 +160,7 @@ export async function runClaudeStatusLine() {
     const versionHome = versionHomeFromEnv(process.env);
     if (versionHome)
         ingestClaudeStatusLineUsage(payload, versionHome);
-    process.stdout.write(renderClaudeStatusLine(payload, undefined, versionHome ? renderDelegate(raw, versionHome) : ''));
+    process.stdout.write(renderClaudeStatusLine(payload, undefined, versionHome ? renderDelegate(raw, versionHome) : '', resolveReminderPart(payload.session_id)));
     return 0;
 }
 export function installClaudeStatusLine(versionHome) {