@phnx-labs/agents-cli 1.22.62 → 1.22.64

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 1.22.64
+
+- **`agents accounts attach` bootstraps a keychain-less Linux worker (PHNX-3502).**
+  Attaching a Claude account to a version home on a headless worker now seeds the
+  home's identity and writes its `.oauth_token` from the account's non-rotating
+  setup-token already synced in the `auth` bundle, instead of refusing because the
+  home was never interactively signed in. This is what lets all accounts show as
+  logged in — and interactive worker runs authenticate (the shim's Linux
+  `.oauth_token` fallback) instead of dropping to the login screen. No rotating
+  OAuth credential is ever copied. Source: `apps/cli/src/commands/accounts.ts`,
+  `apps/cli/src/lib/claude-account-token.ts`.
+
+- Fixed Rush-backed feed channel sinks failing on Linux workers by handing delivery to a reachable macOS fleet peer with the Keychain-bound transport.
+
+- **Auto-produce the origin/main release attestation on merge (RUSH-2666).** A new
+  `attest-main.yml` workflow runs the full suite on every push to `main` and uploads
+  the exact-tree attestation + pretested tarball to a rolling `main-attestations`
+  GitHub Release, keyed by tree hash. `release.sh` now prefetches that proof into the
+  local store before waiting, so an ordinary release promotes without running the
+  suite inline — no more human running the suite by hand to unwedge a release. Purely
+  additive and fail-safe: on any fetch miss or error it falls back to exactly the
+  prior poll-then-`require` behavior, and a fetched proof is trusted only because the
+  existing exact-tree `require` re-verifies it. Source: `cli/scripts/release.sh`,
+  `.github/workflows/attest-main.yml`.
+
+- **Phoenix ID now uses the branded `id.byphoenix.com` API hostname by default (PHNX-3543).** New CLI sessions start and poll device authorization, resolve `whoami`, and bind managed share/traces Workers against the same canonical Phoenix ID base. The legacy hostname remains live for older installed clients. `PHOENIX_ID_BASE` remains an environment override for development and private deployments. Source: `src/lib/identity/client.ts`.
+
+- **A pre-launch `run.launch` event makes a launch into a logged-out version visible instead of silent.** `agents run <agent> --device auto --strategy balanced` (the VS Code "New Claude" flow) launched a version that was LOGGED OUT on the target box: `--device auto` (`applyDeviceAutoToOptions`) only ensures SOME account is ready on the device, not that the SPECIFIC version launched is signed in there, and the failure was invisible — the pinned/default path in `resolveRunVersion` returns without emitting `rotation.resolved`, and `run.dispatched` only fires at run FINALIZE (post-exit), but a logged-out agent sits at the login screen and never finalizes, so nothing was recorded. A new `run.launch` event is now emitted RIGHT BEFORE the harness child is spawned, on the device that will run it, so it fires even when the agent then sits stuck at a login screen. Both live launch paths are covered by one shared emitter: `spawnAgent` (after the tmux-durability gate, for the tmux-wrapped AND bare spawns) and the Windows `execShimPassthrough` shim (`resolvedVia: 'shim'`), which was the second blind spot. Payload: `module: 'run'`, `agent`, `version`, `strategy`, `signedIn` (the launchable-signed-in verdict for the SPECIFIC launched version on THIS device — REUSED from the rotated pick's `rotationResult.picked.signedIn` when the command already computed it, else derived via the new `isVersionLaunchableHere` helper, which applies the same `getVersionHomePath` -> `getAccountInfo` -> `isLaunchableSignedIn` gate as `collectRunCandidates`), `launchedLoggedOut` (the headline flag, `signedIn === false`), `email`, and `resolvedVia`; the device hostname is auto-stamped by `emit()`. It sits in the AUDIT lane — the sibling of `run.dispatched` and the more reliable stuck-launch signal — so `agents events --level audit --include runs` surfaces it. Purely additive observability — the emit is best-effort (it can never break a launch) and no routing/launch behavior changes; refusing to launch a logged-out version is a separate follow-up. Source: `cli/src/lib/exec.ts`, `cli/src/lib/accounting/rotate.ts`, `cli/src/lib/feed/events.ts`, `cli/src/lib/event-families.ts`, `cli/src/commands/exec.ts`.
+
+- **Live session rows carry outcome-card metrics and deliverables (PHNX-3574).** `agents sessions --active --json` and `agents sessions watch --json` now enrich each live row with indexed `tokenCount`, `durationMs`, and `subAgentCount`, plus created plan/artifact documents detected by the existing bounded transcript-tail state engine. Thin clients such as AGI EXT can render the initial request, progress, deliverables, team fan-out, runtime, and token use from the one canonical stream without polling or parsing transcripts themselves. Source: `cli/src/lib/session/active.ts`, `cli/src/lib/session/state.ts`.
+
+## 1.22.63
+
+- **Managed share endpoint enforces a per-user storage quota, object limit, per-file size cap, and publish rate limit (PHNX-3542).** The managed `share.agents-cli.sh` Worker authenticated any Phoenix ID bearer and then accepted **unbounded** writes into shared R2 — no quota, no rate limit, no size cap — which blocked opening publishing to third parties. Each managed (Phoenix-identity) publish now charges a per-user usage ledger stored in R2 at `__usage/<owner>` (a conditional-put CAS object, mirroring the existing `__views`/`__handles` precedent — no Durable Object, no new binding): free tier is 200 MiB total, 150 canonical pages, 20 MiB per file, and 60 publishes/hour. Enforcement measures the **real request body** (bounded-buffered so a streaming body can't exceed the cap) and rejects on the true size **before any write**, so a spoofed-low declared size can't bypass the caps or destroy an existing page. It **fails loud** — `413` for a file, object-count, or byte-quota overage, `429` (with `Retry-After`) for the rate limit — and refunds bytes + object count on delete and on lazy expiry. Covers/views are server-generated overhead and excluded from the quota. BYO (`WRITE_TOKEN`) publishes write to the operator's own bucket at their own cost and are **unaffected** (a deliberate, documented policy). A `SHARE_PLANS` map is the seam for future paid tiers (billing follow-up PHNX-3569). Source: `cli/src/lib/share/worker-template.ts`.
+
+- Let feed channel sinks customize their delivered body with existing post placeholders, including fail-closed `{ticket}` routing for clickable tracker links in team channels.
+
 ## 1.22.62
 
 - **Owner notifications fan out across the configured normal-severity channels (PHNX-3567).** `agents send --to owner`, deprecated `agents notify`, monitor notifications, and an important feed's owner sink now attempt every addressable entry named by `owner.policy.normal` in `humans.yaml`, instead of silently selecting only the first. Each Rush-backed destination that cannot deliver on a Linux worker forwards its explicit channel and target to a capable Mac, avoiding both shell quoting and policy re-expansion/duplicate sends. Partial failures stay visible while successful channels still deliver; legacy single-channel configs retain their old behavior. Source: `cli/src/lib/humans.ts`, `cli/src/lib/notify.ts`, `cli/src/lib/channels/owner-forward.ts`, `cli/src/lib/feed-broadcast.ts`.

package/dist/commands/accounts.d.ts

@@ -37,7 +37,7 @@ export declare function classifyAttachTarget(target: string): AttachTarget;
  * the credential in the keychain, so `resolveClaudeSetupToken` returns null there and this
  * is a no-op off Linux.
  */
-export declare function writeClaudeInteractiveOauthToken(target: AttachTarget, targetAgent: AgentId): void;
+export declare function writeClaudeInteractiveOauthToken(target: AttachTarget, targetAgent: AgentId, email?: string): void;
 export declare function parseBundleKey(raw: string): {
     bundle: string;
     key: string;

package/dist/commands/accounts.js

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
 import { password, select } from '@inquirer/prompts';
-import { resolveClaudeSetupToken } from '../lib/claude-account-token.js';
+import { readClaudeAccountEmail, resolveClaudeSetupToken, resolveClaudeSetupTokenForEmail, seedClaudeWorkerHomeIdentity } from '../lib/claude-account-token.js';
 import { setHelpSections } from '../lib/help.js';
 import { readMeta, updateMeta } from '../lib/state.js';
 import { ALL_AGENT_IDS, getAccountInfo, resolveAgentName } from '../lib/agents.js';
@@ -91,12 +91,17 @@ export function classifyAttachTarget(target) {
  * the credential in the keychain, so `resolveClaudeSetupToken` returns null there and this
  * is a no-op off Linux.
  */
-export function writeClaudeInteractiveOauthToken(target, targetAgent) {
+export function writeClaudeInteractiveOauthToken(target, targetAgent, email) {
     if (process.platform !== 'linux' || targetAgent !== 'claude' || target.kind !== 'installation')
         return;
     const versionHome = getVersionHomePath('claude', target.version);
     const tokenPath = path.join(versionHome, '.claude', '.oauth_token');
-    const token = resolveClaudeSetupToken(versionHome);
+    // Resolve by the attached account's email when known (a freshly-seeded worker
+    // home the `.claude.json` read below could not key on yet), else by the home's
+    // own recorded identity for a re-point/detach.
+    const token = email
+        ? resolveClaudeSetupTokenForEmail(email, versionHome)
+        : resolveClaudeSetupToken(versionHome);
     // A re-point (attach B over A, or a detach) can leave no setup-token resolving for
     // this version — B's may not be minted yet. A leftover file from the previous binding
     // would silently authenticate interactive runs as the OLD account (the shim's Linux
@@ -536,9 +541,30 @@ agents run codex#work`,
                 else {
                     if (t.kind !== 'installation')
                         throw new Error(`${account.agent} authentication is per-version. Attach '${account.name}' to a specific ${account.agent}@<version>.`);
-                    const identity = await nativeIdentityFromSource(target);
-                    if (identity.identityKey !== account.identityKey)
-                        throw new Error(`'${target}' is signed in to a different identity than account '${account.name}'.`);
+                    const versionHome = getVersionHomePath(t.agent, t.version);
+                    // The literal email keys the account's `auth`-bundle setup-token. It lives
+                    // in `identityLabel` — `identityKey` is a synthetic composite
+                    // (`claude:account=<uuid>:org=<uuid>`, agents.ts nativeIdentityKey), never
+                    // the address, so it must NOT be used to derive the token key.
+                    const accountEmail = account.identityLabel;
+                    // Headless-worker bootstrap: a keychain-less Linux worker home never had
+                    // an interactive login, so its `.claude.json` carries no identity and
+                    // `nativeIdentityFromSource` would reject the attach — yet the account's
+                    // non-rotating setup-token is already fleet-synced in the `auth` bundle.
+                    // Seed the identity (email only, no rotating credential) so the token
+                    // resolves; `writeClaudeInteractiveOauthToken` then writes `.oauth_token`.
+                    if (process.platform === 'linux' &&
+                        account.agent === 'claude' &&
+                        accountEmail &&
+                        !readClaudeAccountEmail(versionHome) &&
+                        resolveClaudeSetupTokenForEmail(accountEmail)) {
+                        seedClaudeWorkerHomeIdentity(versionHome, accountEmail);
+                    }
+                    else {
+                        const identity = await nativeIdentityFromSource(target);
+                        if (identity.identityKey !== account.identityKey)
+                            throw new Error(`'${target}' is signed in to a different identity than account '${account.name}'.`);
+                    }
                 }
             }
             else {
@@ -546,7 +572,7 @@ agents run codex#work`,
                 getAccountProvider(account.provider).envFor(targetAgent, account.auth);
             }
             bindAccount(name, target);
-            writeClaudeInteractiveOauthToken(t, targetAgent);
+            writeClaudeInteractiveOauthToken(t, targetAgent, account.kind === 'native' && account.agent === 'claude' ? account.identityLabel : undefined);
             console.log(chalk.green(`Attached ${account.name} to ${target}.`));
         });
     });

package/dist/commands/exec.js

@@ -2356,6 +2356,18 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         // synthesize a same-agent fallback chain from the other healthy accounts
         // (issue #348). Stays null unless a non-pinned strategy actually rotated.
         let rotationResult = null;
+        // Precomputed launchable-signed-in verdict for the ACTUAL launched
+        // candidate, fed to the pre-launch `run.launch` event so it need not
+        // re-probe. Sourced per resolution branch from the candidate that WON, not
+        // the original auto-pick: the interactive picker (RUSH-2334 / PHNX-2526)
+        // deliberately lets the user launch a LOGGED-OUT account, which is a
+        // different candidate than `rotationResult.picked` — reading the verdict off
+        // the auto-pick there would report `launchedLoggedOut:false` for a version
+        // that is actually logged out, the exact false-negative this event exists to
+        // prevent. Left undefined for pinned-default / explicit-pin so emitRunLaunch
+        // falls back to probing the version home itself.
+        let launchSignedIn;
+        let launchEmail;
         // Set when the zero-healthy path already announced a deliberate
         // launch-to-sign-in, so the login preflight below does not repeat it.
         let signInLaunch = false;
@@ -2460,6 +2472,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                             if (!selected)
                                 return;
                             version = selected.version;
+                            // Source the run.launch verdict from the account the user ACTUALLY
+                            // picked — the picker may deliberately return a logged-out one
+                            // (RUSH-2334), so it can differ from rotationResult.picked.
+                            launchSignedIn = selected.signedIn;
+                            launchEmail = selected.email;
                             // Keep the rotation so mid-run failover can still cascade across
                             // the other (stale) healthy accounts after a real rejection.
                             rotationResult = resolved.rotation;
@@ -2476,6 +2493,12 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     else if (resolved.version) {
                         version = resolved.version;
                         rotationResult = resolved.rotation;
+                        // The auto-pick already computed the launchable-signed-in verdict for
+                        // this exact version via the same gate — reuse it for run.launch.
+                        if (resolved.rotation) {
+                            launchSignedIn = resolved.rotation.picked.signedIn;
+                            launchEmail = resolved.rotation.picked.email;
+                        }
                         // A balanced/available pick of a PROVIDER account (setup-token /
                         // API-key) carries `providerAccount`. Resolve its env through the
                         // same `resolveSpawnAccount` path an explicit `--account` uses, so
@@ -2818,6 +2841,23 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             // forwards `--emit-session-id`): print the resolved session id as a
             // stdout sentinel so the launcher captures the id this run coined.
             emitSessionId: options.emitSessionId === true,
+            // Observability-only: carried onto the pre-launch `run.launch` event so
+            // the stream records HOW this version was chosen. Neither affects the
+            // spawn. `resolvedVia` attributes the version source cheaply — an
+            // explicit @version pin, a strategy rotation, or the pinned default.
+            strategy,
+            resolvedVia: rawVersion
+                ? 'explicit-pin'
+                : rotationResult
+                    ? 'rotated'
+                    : 'pinned-default',
+            // Launchable-signed-in verdict for the ACTUAL launched candidate, set per
+            // resolution branch above (auto-pick from rotation.picked; interactive
+            // picker from the user's `selected`, which may be logged out). Undefined
+            // for a pinned-default / explicit-pin launch, where spawnAgent probes the
+            // version home itself.
+            launchSignedIn,
+            launchEmail,
         };
         if (options.interactive && options.headless) {
             console.error(chalk.red('--interactive and --headless are mutually exclusive. Pass one, or neither (mode is inferred from prompt presence).'));

package/dist/commands/feed.d.ts

@@ -20,7 +20,7 @@ import { type OpenBlock } from '../lib/feed/feed.js';
 import { type OutcomeGroup, type SessionOutcomeHint } from '../lib/feed-outcome.js';
 import { filterBlocksForFeed } from '../lib/ask-classifier.js';
 import { type FeedSessionSignal } from '../lib/feed-ranking.js';
-export declare const FEED_POST_HELP = "\nExamples:\n  # Title (subject) + body. Phone broadcasts put title first, body after a\n  # blank line, then a \"Sent from agent/session on host\" footer.\n  agents feed post --title \"CHANGELOG pushed\" \"Watching CI and mac-mini E2E\"\n  agents feed post --title \"Cover ready\" \"render at ./out/cover.png\" --attach ./out/cover.png\n  agents feed post --title \"Ready for review\" \"PR opened, waiting on prix-cloud\" --json\n\n  # Worth interrupting someone over - reaches sinks gated on minLevel: important:\n  agents feed post --title \"npm token expired\" \"Cannot publish the release\" --level important\n\n  # Also raise a local desktop banner on THIS machine (same notifier as run\n  # --notify), on top of any configured broadcast - useful when you are at the box:\n  agents feed post --title \"Build green\" \"all checks passed\" --notify\n\n  # Stuck: opens a needs-you block and always broadcasts at important:\n  agents feed post --title \"Force-push denied\" \"git-guard blocked PR #1749\" --blocked\n  agents feed post --title \"Publish or wait?\" \"npm publish now or after review\" --blocked --option publish --option wait\n  agents feed post --title \"Delete preview env?\" \"stale preview still running\" --blocked --default \"leave it\"\n\n  # Exhaust self-serve FIRST. A block is for what you genuinely cannot do:\n  # a credential only the user holds, a decision only they can make, an\n  # approval only they can give. Not \"should I do the obvious next step?\".\n\n  # Outside a run, pass the session explicitly:\n  agents feed post --title \"Manual note\" \"context for the next agent\" --session 00998b0e-2d15-4d2f-a58b-974a886c9b47\n\nIdentity (session, agent, host, runtime, pid, launchId) is stamped automatically\nand rides the phone footer of feed.broadcast {message}. Domain facts (tickets,\nPRs) are not CLI flags - the ticket is joined from the session index at post\ntime. No em-dashes in title/body - they are scrubbed on the way out.\n\nConfigure where a post is mirrored under feed.broadcast in agents.yaml - see\ndocs/observability.md. A milestone is always recorded, but it does not text\nthe owner when the sink has minLevel: important. Add --level important for a\nphone-worthy successful update. Use --blocked only when work cannot continue.\nThe owner destination comes from humans.yaml; do not duplicate it in agents.yaml.\n";
+export declare const FEED_POST_HELP = "\nExamples:\n  # Title (subject) + body. Phone broadcasts put title first, body after a\n  # blank line, then a \"Sent from agent/session on host\" footer.\n  agents feed post --title \"CHANGELOG pushed\" \"Watching CI and mac-mini E2E\"\n  agents feed post --title \"Cover ready\" \"render at ./out/cover.png\" --attach ./out/cover.png\n  agents feed post --title \"Ready for review\" \"PR opened, waiting on prix-cloud\" --json\n\n  # Worth interrupting someone over - reaches sinks gated on minLevel: important:\n  agents feed post --title \"npm token expired\" \"Cannot publish the release\" --level important\n\n  # Also raise a local desktop banner on THIS machine (same notifier as run\n  # --notify), on top of any configured broadcast - useful when you are at the box:\n  agents feed post --title \"Build green\" \"all checks passed\" --notify\n\n  # Stuck: opens a needs-you block and always broadcasts at important:\n  agents feed post --title \"Force-push denied\" \"git-guard blocked PR #1749\" --blocked\n  agents feed post --title \"Publish or wait?\" \"npm publish now or after review\" --blocked --option publish --option wait\n  agents feed post --title \"Delete preview env?\" \"stale preview still running\" --blocked --default \"leave it\"\n\n  # Exhaust self-serve FIRST. A block is for what you genuinely cannot do:\n  # a credential only the user holds, a decision only they can make, an\n  # approval only they can give. Not \"should I do the obvious next step?\".\n\n  # Outside a run, pass the session explicitly:\n  agents feed post --title \"Manual note\" \"context for the next agent\" --session 00998b0e-2d15-4d2f-a58b-974a886c9b47\n\nIdentity (session, agent, host, runtime, pid, launchId) is stamped automatically\nand rides the phone footer of feed.broadcast {message}. Domain facts (tickets,\nPRs) are not CLI flags - the ticket is joined from the session index at post\ntime. No em-dashes in title/body - they are scrubbed on the way out.\n\nConfigure where a post is mirrored under feed.broadcast in agents.yaml - see\ndocs/observability.md. A channel sink may set message: with placeholders such\nas {message} and {ticket}; a missing placeholder skips that sink. A milestone is always recorded, but it does not text\nthe owner when the sink has minLevel: important. Add --level important for a\nphone-worthy successful update. Use --blocked only when work cannot continue.\nThe owner destination comes from humans.yaml; do not duplicate it in agents.yaml.\n";
 export declare const FEED_NO_FANOUT_ENV = "AGENTS_FEED_LOCAL";
 /** Right-hand masthead summary: `N blocks · M agents`. */
 export declare function formatFeedMastheadRight(blocks: OpenBlock[]): string;

package/dist/commands/feed.js

@@ -57,7 +57,8 @@ PRs) are not CLI flags - the ticket is joined from the session index at post
 time. No em-dashes in title/body - they are scrubbed on the way out.
 
 Configure where a post is mirrored under feed.broadcast in agents.yaml - see
-docs/observability.md. A milestone is always recorded, but it does not text
+docs/observability.md. A channel sink may set message: with placeholders such
+as {message} and {ticket}; a missing placeholder skips that sink. A milestone is always recorded, but it does not text
 the owner when the sink has minLevel: important. Add --level important for a
 phone-worthy successful update. Use --blocked only when work cannot continue.
 The owner destination comes from humans.yaml; do not duplicate it in agents.yaml.

package/dist/lib/accounting/rotate.d.ts

@@ -131,6 +131,28 @@ export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrate
  * existing `signedIn` signal.
  */
 export declare function isLaunchableSignedIn(signedIn: boolean, presence: Pick<CredentialPresence, 'knownLocation' | 'perVersion'>): boolean;
+/** Launchable-signed-in verdict for ONE specific version on THIS device. */
+export interface VersionLaunchState {
+    /** True iff this exact version home can spawn a signed-in agent right now. */
+    launchable: boolean;
+    /** The version home's account email when launchable, else null. */
+    email: string | null;
+}
+/**
+ * Whether a SPECIFIC installed version is launchable-signed-in on THIS device,
+ * plus the account email when it is. Mirrors EXACTLY the per-version gate
+ * {@link collectRunCandidates} applies (getVersionHomePath -> getAccountInfo ->
+ * {@link isLaunchableSignedIn} over {@link credentialPresence}), so the
+ * pre-launch `run.launch` event can report the same signed-in verdict the
+ * balanced router computes for that version.
+ *
+ * The point is to make a launch into a logged-out version VISIBLE at spawn time:
+ * `--device auto` only guarantees SOME account is ready on the device, not that
+ * the specific version launched is signed in there (the yosemite-m3 2.1.219
+ * incident — 2.1.219 was logged out, the router correctly excluded it, yet it
+ * launched). Non-fatal by construction: callers wrap it best-effort.
+ */
+export declare function isVersionLaunchableHere(agent: AgentId, version: string): Promise<VersionLaunchState>;
 /**
  * How old a usage snapshot may be and still settle a routing DECISION.
  *

package/dist/lib/accounting/rotate.js

@@ -98,6 +98,26 @@ export function isLaunchableSignedIn(signedIn, presence) {
         return true;
     return presence.perVersion;
 }
+/**
+ * Whether a SPECIFIC installed version is launchable-signed-in on THIS device,
+ * plus the account email when it is. Mirrors EXACTLY the per-version gate
+ * {@link collectRunCandidates} applies (getVersionHomePath -> getAccountInfo ->
+ * {@link isLaunchableSignedIn} over {@link credentialPresence}), so the
+ * pre-launch `run.launch` event can report the same signed-in verdict the
+ * balanced router computes for that version.
+ *
+ * The point is to make a launch into a logged-out version VISIBLE at spawn time:
+ * `--device auto` only guarantees SOME account is ready on the device, not that
+ * the specific version launched is signed in there (the yosemite-m3 2.1.219
+ * incident — 2.1.219 was logged out, the router correctly excluded it, yet it
+ * launched). Non-fatal by construction: callers wrap it best-effort.
+ */
+export async function isVersionLaunchableHere(agent, version) {
+    const home = getVersionHomePath(agent, version);
+    const info = await getAccountInfo(agent, home);
+    const launchable = isLaunchableSignedIn(info.signedIn, credentialPresence(agent, home));
+    return { launchable, email: launchable ? info.email : null };
+}
 function isAvailableEligible(candidate) {
     return isRotationEligible(candidate);
 }

package/dist/lib/claude-account-token.d.ts

@@ -22,3 +22,29 @@ export declare function readClaudeAccountEmail(home?: string): string | null;
  * authenticate with the shareable setup-token, not the ACL-bound login item.
  */
 export declare function resolveClaudeSetupToken(home?: string): string | null;
+/**
+ * Resolve a long-lived setup-token for an EXPLICIT account email, independent of
+ * any version home's `.claude.json`. This is what lets `agents accounts attach`
+ * provision a headless worker home that has never had an interactive login: the
+ * account's non-rotating setup-token is already fleet-synced in the file-based
+ * `auth` bundle, keyed by email ({@link claudeAccountTokenKey}), so we can write
+ * the home's `.oauth_token` from it without the circular
+ * "read the home's email to resolve the home's token" dependency that
+ * {@link resolveClaudeSetupToken} has. Same file-backed-only, fail-closed,
+ * fingerprint-stable read as the home-keyed path — it is the shared core.
+ *
+ * `cacheKey` scopes the process-local token cache; callers pass a version home
+ * so a home-keyed and email-keyed read of the same account share nothing stale.
+ */
+export declare function resolveClaudeSetupTokenForEmail(email: string, cacheKey?: string): string | null;
+/**
+ * Seed a keychain-less Linux worker's Claude version-home identity so an account's
+ * fleet-synced setup-token resolves for it. A worker home never had an interactive
+ * browser login, so its `.claude.json` carries no `oauthAccount.emailAddress` and
+ * the account reads "signed out" even though its non-rotating setup-token is present
+ * in the `auth` bundle. This writes ONLY the descriptive identity (the email), merged
+ * into both `.claude.json` locations Claude Code reads, preserving every other field.
+ * It never copies a rotating OAuth credential (`.credentials.json`) — the setup-token
+ * stays the credential of record.
+ */
+export declare function seedClaudeWorkerHomeIdentity(versionHome: string, email: string): void;

package/dist/lib/claude-account-token.js

@@ -76,12 +76,32 @@ export function readClaudeAccountEmail(home) {
  * authenticate with the shareable setup-token, not the ACL-bound login item.
  */
 export function resolveClaudeSetupToken(home) {
+    // Require a known account (email) up front: without it we cannot key a
+    // per-account token, and we must NOT fall back to a bare shared key that
+    // would misapply one account's setup-token to another.
+    const email = readClaudeAccountEmail(home);
+    if (!email)
+        return null;
+    return resolveClaudeSetupTokenForEmail(email, home ?? os.homedir());
+}
+/**
+ * Resolve a long-lived setup-token for an EXPLICIT account email, independent of
+ * any version home's `.claude.json`. This is what lets `agents accounts attach`
+ * provision a headless worker home that has never had an interactive login: the
+ * account's non-rotating setup-token is already fleet-synced in the file-based
+ * `auth` bundle, keyed by email ({@link claudeAccountTokenKey}), so we can write
+ * the home's `.oauth_token` from it without the circular
+ * "read the home's email to resolve the home's token" dependency that
+ * {@link resolveClaudeSetupToken} has. Same file-backed-only, fail-closed,
+ * fingerprint-stable read as the home-keyed path — it is the shared core.
+ *
+ * `cacheKey` scopes the process-local token cache; callers pass a version home
+ * so a home-keyed and email-keyed read of the same account share nothing stale.
+ */
+export function resolveClaudeSetupTokenForEmail(email, cacheKey) {
     try {
-        // Require a known account (email) up front: without it we cannot key a
-        // per-account token, and we must NOT fall back to a bare shared key that
-        // would misapply one account's setup-token to another.
-        const email = readClaudeAccountEmail(home);
-        if (!email)
+        const trimmed = email.trim();
+        if (!trimmed)
             return null;
         if (!bundleExists(AUTH_BUNDLE))
             return null;
@@ -92,25 +112,26 @@ export function resolveClaudeSetupToken(home) {
             // hint that the seeded setup-token was being ignored.
             throw new ReservedBundleWrongBackendError(AUTH_BUNDLE, backend);
         }
-        const cacheKey = home ?? os.homedir();
-        const item = secretsKeychainItem(AUTH_BUNDLE, claudeAccountTokenKey(email));
+        const key = claudeAccountTokenKey(trimmed);
+        const ck = cacheKey ?? `email:${trimmed}`;
+        const item = secretsKeychainItem(AUTH_BUNDLE, key);
         const credentialPath = fileStoreItemPath(item);
         for (let attempt = 0; attempt < 2; attempt++) {
             const before = credentialFingerprint(credentialPath);
-            const cached = setupTokenCache.get(cacheKey);
+            const cached = setupTokenCache.get(ck);
             if (cached?.credentialPath === credentialPath && cached.fingerprint === before) {
                 return cached.token;
             }
             if (before === 'missing') {
-                setupTokenCache.set(cacheKey, { credentialPath, fingerprint: before, token: null });
+                setupTokenCache.set(ck, { credentialPath, fingerprint: before, token: null });
                 return null;
             }
             const { env } = readAndResolveBundleEnv(AUTH_BUNDLE, { caller: 'usage', agentOnly: true });
-            const v = (env[claudeAccountTokenKey(email)] ?? '').trim();
+            const v = (env[key] ?? '').trim();
             const token = v.length > 0 && isValidClaudeSetupToken(v) ? v : null;
             const after = credentialFingerprint(credentialPath);
             if (before === after) {
-                setupTokenCache.set(cacheKey, { credentialPath, fingerprint: after, token });
+                setupTokenCache.set(ck, { credentialPath, fingerprint: after, token });
                 return token;
             }
         }
@@ -124,3 +145,36 @@ export function resolveClaudeSetupToken(home) {
         return null;
     }
 }
+/**
+ * Seed a keychain-less Linux worker's Claude version-home identity so an account's
+ * fleet-synced setup-token resolves for it. A worker home never had an interactive
+ * browser login, so its `.claude.json` carries no `oauthAccount.emailAddress` and
+ * the account reads "signed out" even though its non-rotating setup-token is present
+ * in the `auth` bundle. This writes ONLY the descriptive identity (the email), merged
+ * into both `.claude.json` locations Claude Code reads, preserving every other field.
+ * It never copies a rotating OAuth credential (`.credentials.json`) — the setup-token
+ * stays the credential of record.
+ */
+export function seedClaudeWorkerHomeIdentity(versionHome, email) {
+    const trimmed = email.trim();
+    if (!trimmed)
+        return;
+    for (const p of [
+        path.join(versionHome, '.claude', '.claude.json'),
+        path.join(versionHome, '.claude.json'),
+    ]) {
+        let doc = {};
+        try {
+            doc = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        }
+        catch {
+            // Missing or unreadable at this location — write a fresh minimal document.
+        }
+        const existing = (doc.oauthAccount && typeof doc.oauthAccount === 'object'
+            ? doc.oauthAccount
+            : {});
+        doc.oauthAccount = { ...existing, emailAddress: trimmed };
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify(doc));
+    }
+}

package/dist/lib/event-families.js

@@ -36,7 +36,7 @@ export function parseFamilyList(raw, flagName) {
 /** Command-churn event kinds. */
 export const COMMAND_EVENT_TYPES = ['command.start', 'command.end'];
 /** Run-dispatch outcome kinds (replaces the separate audit/log.jsonl product). */
-export const RUN_EVENT_TYPES = ['run.dispatched', 'agent.run.end'];
+export const RUN_EVENT_TYPES = ['run.dispatched', 'run.launch', 'agent.run.end'];
 /**
  * Fold family include/exclude into a UnifiedQuery.
  * Precedence: family narrows sources/types; field filters (module, event, …)

package/dist/lib/exec.d.ts

@@ -1,4 +1,5 @@
-import type { AgentId, Mode } from './types.js';
+import type { AgentId, Mode, RunStrategy } from './types.js';
+import { type EventPayload } from './feed/events.js';
 import { type UsernsStatus } from './linux-userns.js';
 /**
  * Agent execution modes. Canonical name `skip` (dangerously skip permissions);
@@ -212,6 +213,31 @@ export interface ExecOptions {
      * session. Also forced off by AGENTS_NO_TMUX=1. No effect on headless runs.
      */
     raw?: boolean;
+    /**
+     * The run strategy that resolved this launch (pinned/available/balanced).
+     * Observability-only: threaded from the `agents run` command purely so the
+     * pre-launch `run.launch` event can record HOW the version was chosen. Never
+     * read by the spawn itself.
+     */
+    strategy?: RunStrategy;
+    /**
+     * How the launched version was resolved (e.g. 'pinned-default', 'rotated',
+     * 'explicit-pin'), when cheaply determinable. Observability-only, carried on
+     * `run.launch`. Optional — omitted when the caller can't attribute it.
+     */
+    resolvedVia?: string;
+    /**
+     * Precomputed launchable-signed-in verdict for the launched version, supplied
+     * by a caller that already computed it via the identical gate (a rotated pick
+     * carries `rotationResult.picked.signedIn`). When present, `run.launch` uses it
+     * instead of re-probing the version home — removing a double fs read on the hot
+     * path and any disagreement window. `undefined` means "not precomputed" (the
+     * pinned-default / shim paths), which makes `emitRunLaunch` fall back to
+     * {@link isVersionLaunchableHere}. Observability-only.
+     */
+    launchSignedIn?: boolean | null;
+    /** Precomputed account email companion to {@link launchSignedIn}. */
+    launchEmail?: string | null;
 }
 /**
  * Identity a custom-harness run stamps on env / pid-registry / sidecars.
@@ -550,6 +576,45 @@ export declare function writeTmuxEnvFile(env: NodeJS.ProcessEnv, filePath: strin
  * `[detached]` the pane-died hook otherwise leaves behind.
  */
 export declare function formatPaneTail(raw: string, maxLines?: number): string;
+/**
+ * Spawn an agent process and return its exit code plus a tee'd copy of stderr.
+ *
+ * Stderr is always piped so the caller can inspect it (e.g., for rate-limit
+ * detection) while also forwarding every chunk to process.stderr in real time --
+ * the user sees the same output they would with stdio: 'inherit'. Stdout keeps
+ * the original behavior: 'pipe' when downstream output is piped (so `agents
+ * run ... | ...` composes cleanly), otherwise 'inherit' so TTY output is
+ * unbuffered.
+ */
+/** Inputs the pre-launch `run.launch` payload is built from. */
+export interface RunLaunchInput {
+    agent: AgentId;
+    harnessName?: string;
+    /** The version being launched, or undefined when none could be resolved. */
+    version?: string;
+    strategy?: RunStrategy;
+    /**
+     * Whether the launched version is launchable-signed-in on THIS device
+     * ({@link isVersionLaunchableHere}). `null` when the verdict is unknown — a
+     * missing verdict must NOT be read as logged out.
+     */
+    signedIn: boolean | null;
+    /** Account email of the version home when signed in, else null. */
+    email: string | null;
+    /** How the version was resolved (explicit-pin / rotated / pinned-default). */
+    resolvedVia?: string;
+}
+/**
+ * Build the `run.launch` event payload. Pure and exported so the signedIn ->
+ * launchedLoggedOut mapping is unit-testable without spawning. Mirrors the
+ * buildRotationDecisionEvent / emitRotationDecision split in rotate.ts.
+ *
+ * `launchedLoggedOut` is the headline flag — true ONLY when `signedIn` was
+ * resolved to false (a launch into a logged-out version, the yosemite-m3 2.1.219
+ * incident). An UNKNOWN verdict (`signedIn === null`) is never treated as
+ * logged out.
+ */
+export declare function buildRunLaunchPayload(input: RunLaunchInput): EventPayload;
 /** Exit code spawnAgent resolves with when a run is killed for crossing a budget cap. */
 export declare const BUDGET_KILL_EXIT_CODE = 7;
 /**