@phnx-labs/agents-cli 1.22.59 → 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, weightedRandomByCapacity, '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,
@@ -376,8 +404,16 @@ export { PROJECTION_HORIZON_MIN, capacityWeight };
  * routing capacity (see {@link capacityWeight}). Floor each weight at 1 so a
  * near-exhausted-but-still-eligible candidate can still be picked occasionally.
  */
-function weightedRandomByCapacity(sorted) {
-    const weights = sorted.map((c) => capacityWeight(getRoutingUsedPercent(c.usageSnapshot), c.usageMinutesToLimit));
+function weightedRandomByCapacity(sorted, nowMs = Date.now()) {
+    const weights = sorted.map((c) => capacityWeight(
+    // An unverified (stale or absent) snapshot carries no trustworthy number,
+    // so it weights as UNVERIFIED_WEIGHT (the floor) instead of by its frozen
+    // usedPercent. Otherwise a day-old "45% used" competes as if it were live
+    // headroom and can win the draw over a verified-healthy account — which is
+    // exactly how balanced launched into an account already at its weekly cap
+    // on a worker whose usage refresh had stalled (PHNX-3479). A verified
+    // snapshot keeps its real remaining-headroom weight.
+    isUsageVerified(c, nowMs) ? getRoutingUsedPercent(c.usageSnapshot) : null, c.usageMinutesToLimit));
     const total = weights.reduce((sum, w) => sum + w, 0);
     if (total <= 0)
         return sorted[0];
@@ -416,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
@@ -485,7 +527,7 @@ export function pickHarnessWeighted(byHarness, nowMs = Date.now()) {
     const excluded = summaries.filter((s) => s.best === null);
     if (healthy.length === 0)
         return null;
-    const pickedBest = weightedRandomByCapacity(healthy.map((s) => s.best));
+    const pickedBest = weightedRandomByCapacity(healthy.map((s) => s.best), nowMs);
     const picked = healthy.find((s) => s.best === pickedBest);
     return { picked, healthy, excluded };
 }
@@ -539,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.
@@ -716,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.
@@ -732,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)
@@ -740,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 {
@@ -762,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.
@@ -776,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/accounting/usage-sync.d.ts

@@ -1,9 +1,18 @@
 import { type DeviceProfile } from '../devices/registry.js';
 import { type ConfiguredDeviceRole } from '../device-config.js';
-import { type CachedUsageSnapshot, type UsageSnapshot } from './usage.js';
+import { type CachedUsageSnapshot } from './usage.js';
 /** How long a single peer push may take before it is abandoned for this tick. */
 export declare const USAGE_PUSH_DEADLINE_MS = 20000;
 export declare const USAGE_PULL_DEADLINE_MS = 20000;
+/**
+ * A worker's newest local usage row older than this triggers a pull from the
+ * primary. A worker cannot self-read usage (setup-token lacks `user:profile`,
+ * RUSH-2392), so its only source of a fresh row is the daemon push every
+ * `USAGE_SYNC_TICK_MS` (15m); this cutoff is 2× that tick, so one missed push
+ * cycle is tolerated before the worker actively pulls. Bounds worker staleness
+ * to ~30m instead of the days-old caches this replaces.
+ */
+export declare const USAGE_SYNC_MAX_AGE_MS: number;
 /** The stdin envelope the `__usage-ingest` verb reads. `v` guards the shape. */
 export interface UsageSyncPayload {
     v: 1;
@@ -75,8 +84,9 @@ export interface UsagePullDeps {
     listRoles?: () => Record<string, ConfiguredDeviceRole>;
     isPinned?: (name: string) => boolean;
     exportRows?: () => Record<string, CachedUsageSnapshot>;
-    readRow?: (usageKey: string) => Pick<UsageSnapshot, 'windows'> | null;
     ingestRows?: (rows: Record<string, CachedUsageSnapshot>) => number;
+    /** Injectable clock for the staleness gate; defaults to `Date.now`. */
+    now?: () => number;
     /** Read the versioned payload from the primary. Default: ssh `__usage-export`. */
     pull?: (device: DeviceProfile) => {
         ok: boolean;

package/dist/lib/accounting/usage-sync.js

@@ -32,10 +32,26 @@ import { sshTargetFor } from '../devices/connect.js';
 import { isHostPinned } from '../devices/known-hosts.js';
 import { machineId, normalizeHost } from '../session/sync/config.js';
 import { isHeadedDeviceRole, listConfiguredDeviceRoles, selfConfiguredDeviceRole, } from '../device-config.js';
-import { exportClaudeUsageCacheRows, ingestPeerClaudeUsageRows, readClaudeUsageCache, } from './usage.js';
+import { exportClaudeUsageCacheRows, ingestPeerClaudeUsageRows, } from './usage.js';
 /** How long a single peer push may take before it is abandoned for this tick. */
 export const USAGE_PUSH_DEADLINE_MS = 20_000;
 export const USAGE_PULL_DEADLINE_MS = 20_000;
+/**
+ * A worker's newest local usage row older than this triggers a pull from the
+ * primary. A worker cannot self-read usage (setup-token lacks `user:profile`,
+ * RUSH-2392), so its only source of a fresh row is the daemon push every
+ * `USAGE_SYNC_TICK_MS` (15m); this cutoff is 2× that tick, so one missed push
+ * cycle is tolerated before the worker actively pulls. Bounds worker staleness
+ * to ~30m instead of the days-old caches this replaces.
+ */
+export const USAGE_SYNC_MAX_AGE_MS = 30 * 60_000;
+/** Epoch ms of a cache row's capture time, or null when unparseable/absent. */
+function capturedAtMs(capturedAt) {
+    if (!capturedAt)
+        return null;
+    const ms = Date.parse(capturedAt);
+    return Number.isFinite(ms) ? ms : null;
+}
 /**
  * Decide, per peer, whether to push the local usage snapshot. Pure.
  *
@@ -109,12 +125,24 @@ export function pullUsageFromPrimary(deps = {}) {
         return result;
     }
     const localRows = (deps.exportRows ?? exportClaudeUsageCacheRows)();
-    const readRow = deps.readRow ?? readClaudeUsageCache;
     const localEntries = Object.entries(localRows);
-    if (localEntries.length > 0 && localEntries.every(([key, row]) => {
-        const fresh = readRow(key);
-        return fresh !== null && fresh.windows.length === row.windows.length;
-    })) {
+    // Fresh means RECENT, not "the cache equals itself". The prior check read the
+    // SAME on-disk cache twice (exportRows() and readRow()) and compared window
+    // COUNT, so `fresh.windows.length === row.windows.length` was always true and
+    // any non-empty worker cache skipped the pull forever — which is how a worker
+    // served a days-old snapshot indefinitely and balanced launched into an
+    // account already at its weekly cap. A worker cannot self-read usage, so any
+    // row older than the sync cadence is stale and must trigger a pull; the merge
+    // is newest-wins + idempotent, so pulling when the primary is no fresher is a
+    // harmless no-op.
+    const now = (deps.now ?? Date.now)();
+    const staleCutoff = now - USAGE_SYNC_MAX_AGE_MS;
+    const allFresh = localEntries.length > 0 &&
+        localEntries.every(([, row]) => {
+            const ms = capturedAtMs(row.capturedAt);
+            return ms !== null && ms >= staleCutoff;
+        });
+    if (allFresh) {
         result.skipped = 'local usage cache is fresh';
         return result;
     }

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