@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/computer/download.js

@@ -3,48 +3,51 @@
  * ("ComputerHelper.app").
  *
  * The helper is a signed + notarized universal `.app` bundle published as a
- * GitHub release asset per tagged CLI version — the same distribution model as
- * the Windows helper (see `lib/computer/ssh-tunnel.ts`). A fresh `npm i -g` machine has
- * no local build, so `agents computer setup` / `agents setup computer` fetch the
- * asset for the running CLI version, verify its sha256 against the published
+ * GitHub release asset on its own `computer-mac/v<x.y.z>` tag (see
+ * `helper-versions.ts`). The Windows helper (`lib/computer/ssh-tunnel.ts`) does
+ * NOT yet follow this model — it still keys its exe to the CLI's own tag.
+ *
+ * A fresh `npm i -g` machine has no local build, so `agents computer setup` / `agents setup computer` fetch the
+ * asset for the pinned helper version, verify its sha256 against the published
  * `.sha256`, then verify the code signature (Developer ID Team + notarization)
  * before it is ever copied to /Applications.
  *
- * A `.app` is a directory, so the asset is a zip (`ditto -c -k --keepParent`);
- * we extract it with `ditto -x -k` after the checksum passes.
+ * The download + verify machinery is shared with the menu-bar helper in
+ * `../helper-download.ts`; this file is the ComputerHelper spec + its wrappers,
+ * keeping the historical export surface (`verifyMacHelper`, `downloadMacHelperApp`,
+ * `ensureMacHelperApp`, …) stable for existing callers. ComputerHelper does NOT
+ * pin a designated requirement (no `expectedBundleId`), matching its verification
+ * strength before the shared primitive existed.
  */
-import { execFileSync, spawnSync } from 'node:child_process';
-import * as fs from 'node:fs';
 import * as os from 'node:os';
-import * as path from 'node:path';
-import { Readable } from 'node:stream';
-import { pipeline } from 'node:stream/promises';
-import { getCacheDir } from '../state.js';
-import { getCliVersion } from '../version.js';
-import { parseSha256Asset, sha256File } from './ssh-tunnel.js';
 import { resolveHelperApp } from './computer-rpc.js';
-/** GitHub repo whose `v<version>` releases carry the helper asset. */
-export const HELPER_RELEASE_REPO = 'phnx-labs/agents-cli';
+import { EXPECTED_TEAM_ID, HELPER_RELEASE_REPO, downloadHelperApp, helperAssetUrls, helperCacheDir, parseTeamId, verifyHelperApp, } from '../helper-download.js';
+import { helperFloor } from '../helper-versions.js';
+// Re-exported so existing importers (and download.test.ts) keep resolving these
+// names from './download.js'.
+export { EXPECTED_TEAM_ID, HELPER_RELEASE_REPO, parseTeamId };
 /** The zipped `.app` release asset name. */
 export const MAC_HELPER_ASSET = 'ComputerHelper.app.zip';
 /** The bundle directory name once extracted. */
 export const MAC_HELPER_APP_NAME = 'ComputerHelper.app';
-/** Apple Developer ID Team the helper must be signed by (defense in depth on top
- * of `spctl` notarization assessment). "Developer ID Application: Muqit Nawaz". */
-export const EXPECTED_TEAM_ID = '2HTP252L87';
+/** ComputerHelper identity + verification policy. No `expectedBundleId`: this
+ *  helper has no upgrade-stable Accessibility grant to protect, so its
+ *  verification is codesign + Team + notarization exactly as before. */
+const COMPUTER_HELPER_SPEC = {
+    helper: 'computer-mac',
+    assetName: MAC_HELPER_ASSET,
+    appName: MAC_HELPER_APP_NAME,
+    cacheSubdir: ['computer', 'mac-helper'],
+    expectedTeamId: EXPECTED_TEAM_ID,
+    localBuildHint: 'bash native/computer-mac/scripts/build.sh release',
+};
 /** Cache dir for the downloaded helper, one subdir per release tag. */
 export function macHelperCacheDir(version) {
-    return path.join(getCacheDir(), 'computer', 'mac-helper', `v${version}`);
+    return helperCacheDir(COMPUTER_HELPER_SPEC, version);
 }
 /** Release-asset URLs for the helper zip + its checksum at one `v<version>` tag. */
 export function macHelperAssetUrls(version) {
-    const base = `https://github.com/${HELPER_RELEASE_REPO}/releases/download/v${version}`;
-    return { zip: `${base}/${MAC_HELPER_ASSET}`, sha256: `${base}/${MAC_HELPER_ASSET}.sha256` };
-}
-/** Extract `TeamIdentifier=XXXX` from `codesign -dv --verbose=4` output (which is
- * emitted on stderr). Returns null when absent (ad-hoc / unsigned). */
-export function parseTeamId(codesignInfo) {
-    return codesignInfo.match(/TeamIdentifier=([A-Z0-9]+)/)?.[1] ?? null;
+    return helperAssetUrls(COMPUTER_HELPER_SPEC, version);
 }
 /**
  * Verify a helper `.app` bundle is intact, signed by the expected Developer ID
@@ -52,31 +55,7 @@ export function parseTeamId(codesignInfo) {
  * on any failure — a downloaded bundle is never trusted without this.
  */
 export function verifyMacHelper(appPath) {
-    // 1. Structural + signature integrity.
-    try {
-        execFileSync('/usr/bin/codesign', ['--verify', '--deep', '--strict', appPath], { stdio: 'pipe' });
-    }
-    catch (e) {
-        throw new Error(`code signature invalid for ${appPath}: ${e.message}`);
-    }
-    // 2. Team identity — must be our Developer ID, not some other valid signer.
-    // `codesign -dv` writes its details to STDERR even on success (exit 0), so we
-    // must read stderr, not stdout. spawnSync captures both streams regardless of
-    // exit code; execFileSync would return only (empty) stdout and the Team check
-    // would falsely reject every validly-signed helper.
-    const dv = spawnSync('/usr/bin/codesign', ['-dv', '--verbose=4', appPath], { encoding: 'utf8' });
-    const info = `${dv.stdout ?? ''}${dv.stderr ?? ''}`;
-    const team = parseTeamId(info);
-    if (team !== EXPECTED_TEAM_ID) {
-        throw new Error(`helper signed by unexpected Team (${team ?? 'none'}), expected ${EXPECTED_TEAM_ID}. Refusing to install.`);
-    }
-    // 3. Notarization / Gatekeeper — confirms Apple stapled a notarization ticket.
-    try {
-        execFileSync('/usr/sbin/spctl', ['--assess', '--type', 'execute', '--verbose', appPath], { stdio: 'pipe' });
-    }
-    catch (e) {
-        throw new Error(`helper is not notarized / rejected by Gatekeeper: ${e.message}. Refusing to install.`);
-    }
+    verifyHelperApp(appPath, COMPUTER_HELPER_SPEC);
 }
 /**
  * Download the helper release asset for `version`, verify sha256, extract the
@@ -84,58 +63,16 @@ export function verifyMacHelper(appPath) {
  * `ComputerHelper.app`. A missing asset is a hard error naming the exact tag —
  * never a silent fallback to another release.
  */
-export async function downloadMacHelperApp(version) {
-    const dir = macHelperCacheDir(version);
-    const cachedApp = path.join(dir, MAC_HELPER_APP_NAME);
-    if (fs.existsSync(cachedApp)) {
-        // Re-verify a cached bundle cheaply; a tampered cache must not be trusted.
-        verifyMacHelper(cachedApp);
-        return cachedApp;
-    }
-    const tag = `v${version}`;
-    const { zip: zipUrl, sha256: shaUrl } = macHelperAssetUrls(version);
-    const missing = (status, url) => new Error(`no ${MAC_HELPER_ASSET} release asset for tag ${tag} (HTTP ${status} on ${url}). ` +
-        `The macOS helper ships as a GitHub release asset per tagged CLI version; ` +
-        `from a repo checkout you can build it locally instead: ` +
-        `bash native/computer-mac/scripts/build.sh release`);
-    // Checksum first: it is tiny and 404s fast when the tag has no assets.
-    const shaRes = await fetch(shaUrl, { signal: AbortSignal.timeout(30_000) });
-    if (!shaRes.ok)
-        throw missing(shaRes.status, shaUrl);
-    const expected = parseSha256Asset(await shaRes.text());
-    console.error(`Downloading ${MAC_HELPER_ASSET} ${tag} from GitHub releases...`);
-    const zipRes = await fetch(zipUrl, { signal: AbortSignal.timeout(15 * 60_000) });
-    if (!zipRes.ok || !zipRes.body)
-        throw missing(zipRes.status, zipUrl);
-    fs.mkdirSync(dir, { recursive: true });
-    const partial = path.join(dir, `${MAC_HELPER_ASSET}.download`);
-    try {
-        await pipeline(Readable.fromWeb(zipRes.body), fs.createWriteStream(partial));
-        const actual = await sha256File(partial);
-        if (actual !== expected) {
-            throw new Error(`sha256 mismatch for ${zipUrl}: expected ${expected}, got ${actual}`);
-        }
-        // Extract the zip (created with `ditto -c -k --keepParent`, so it contains
-        // ComputerHelper.app/ at top level) into the version cache dir.
-        fs.rmSync(cachedApp, { recursive: true, force: true });
-        execFileSync('/usr/bin/ditto', ['-x', '-k', partial, dir], { stdio: 'pipe' });
-        if (!fs.existsSync(cachedApp)) {
-            throw new Error(`extracted asset did not contain ${MAC_HELPER_APP_NAME}`);
-        }
-        verifyMacHelper(cachedApp);
-    }
-    finally {
-        fs.rmSync(partial, { force: true });
-    }
-    return cachedApp;
+export function downloadMacHelperApp(version) {
+    return downloadHelperApp(COMPUTER_HELPER_SPEC, version);
 }
 /**
  * Resolve the helper `.app` to install from: a local build / bundled copy first
  * (repo checkout), else the checksum + signature-verified release-asset download
- * for the running CLI version. Throws with the tag it checked when neither
+ * for the pinned helper version. Throws with the tag it checked when neither
  * exists. macOS only.
  */
-export async function ensureMacHelperApp(version = getCliVersion()) {
+export async function ensureMacHelperApp(version = helperFloor('computer-mac')) {
     if (os.platform() !== 'darwin') {
         throw new Error('The macOS computer helper is only available on macOS.');
     }

package/dist/lib/computer/ssh-tunnel.d.ts

@@ -72,9 +72,6 @@ export declare function winHelperAssetUrls(version: string): {
  * Parse the published `.sha256` asset — `sha256sum` format (`<hex>  <name>`) or
  * a bare hex digest. Throws on anything that does not lead with 64 hex chars.
  */
-export declare function parseSha256Asset(text: string): string;
-/** Stream a file through sha256 — the exe is ~157MB, never read it whole. */
-export declare function sha256File(file: string): Promise<string>;
 /**
  * Download the exe release asset for this CLI version, verify its sha256
  * against the published `.sha256` asset, and cache it under the agents cache

package/dist/lib/computer/ssh-tunnel.js

@@ -21,7 +21,8 @@ import * as net from 'net';
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { randomBytes, createHash } from 'crypto';
+import { randomBytes } from 'crypto';
+import { parseSha256Asset, sha256File } from '../sha256-asset.js';
 import { Readable } from 'stream';
 import { pipeline } from 'stream/promises';
 import { sshExec, SSH_OPTS, assertValidSshTarget } from '../ssh-exec.js';
@@ -31,8 +32,8 @@ import { getDevice } from '../devices/registry.js';
 import { deviceIdentityArgs, sshTargetFor } from '../devices/connect.js';
 import { hostNameFor } from '../devices/ssh-config.js';
 import { getCacheDir } from '../state.js';
-import { getCliVersion } from '../version.js';
 import { openComputerClient, resolveTcpEndpoint } from './computer-rpc.js';
+import { helperFloor, helperTag } from '../helper-versions.js';
 /** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure.
  *
  * Composes the shared hardened baseline (`SSH_OPTS`) rather than re-listing it,
@@ -115,8 +116,8 @@ export const WIN_HELPER_TOKEN_FILE = 'helper-token';
 export function resolveWinHelperExe() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const candidates = [
-        // Running from the agents-cli checkout. apps/cli/dist/lib/computer -> repo root (5 up) -> native/computer-win.
-        path.resolve(here, '..', '..', '..', '..', '..', 'native', 'computer-win', 'dist', WIN_HELPER_EXE),
+        // Running from the agents-cli checkout. cli/dist/lib/computer -> repo root (4 up) -> native/computer-win.
+        path.resolve(here, '..', '..', '..', '..', 'native', 'computer-win', 'dist', WIN_HELPER_EXE),
         // Bundled with the npm package (dist/lib/computer -> dist/).
         path.resolve(here, '..', '..', 'computer-helper-win', WIN_HELPER_EXE),
     ];
@@ -134,29 +135,18 @@ export function winHelperCacheDir(version) {
 }
 /** Release-asset URLs for the exe + its checksum at one exact `v<version>` tag. */
 export function winHelperAssetUrls(version) {
-    const base = `https://github.com/${WIN_HELPER_RELEASE_REPO}/releases/download/v${version}`;
+    // The helper's OWN tag, not the CLI's. This exe is not an .app bundle so it
+    // cannot share helper-download.ts's zip/codesign machinery, but it had the
+    // identical coupling: keyed to `v${cliVersion}`, every CLI release had to
+    // re-stage a ~165MB exe or the download 404'd, and a helper fix could not
+    // reach anyone without a CLI release. Same fix, same tag namespace.
+    const base = `https://github.com/${WIN_HELPER_RELEASE_REPO}/releases/download/${helperTag('computer-win', version)}`;
     return { exe: `${base}/${WIN_HELPER_EXE}`, sha256: `${base}/${WIN_HELPER_EXE}.sha256` };
 }
 /**
  * Parse the published `.sha256` asset — `sha256sum` format (`<hex>  <name>`) or
  * a bare hex digest. Throws on anything that does not lead with 64 hex chars.
  */
-export function parseSha256Asset(text) {
-    const m = text.trim().match(/^([A-Fa-f0-9]{64})(\s|$)/);
-    if (!m)
-        throw new Error(`malformed .sha256 release asset: ${JSON.stringify(text.slice(0, 80))}`);
-    return m[1].toLowerCase();
-}
-/** Stream a file through sha256 — the exe is ~157MB, never read it whole. */
-export function sha256File(file) {
-    return new Promise((resolve, reject) => {
-        const hash = createHash('sha256');
-        fs.createReadStream(file)
-            .on('error', reject)
-            .on('data', (d) => hash.update(d))
-            .on('end', () => resolve(hash.digest('hex')));
-    });
-}
 /**
  * Download the exe release asset for this CLI version, verify its sha256
  * against the published `.sha256` asset, and cache it under the agents cache
@@ -203,7 +193,7 @@ export async function downloadWinHelperExe(version) {
  * checkout / bundled), then the checksum-verified release-asset download for
  * the running CLI version. Throws with the tag it checked when neither exists.
  */
-export async function ensureWinHelperExe(version = getCliVersion()) {
+export async function ensureWinHelperExe(version = helperFloor('computer-win')) {
     const local = resolveWinHelperExe();
     if (local)
         return local;

package/dist/lib/config-keys.d.ts

@@ -9,7 +9,7 @@
 import type { AgentId } from './types.js';
 import { type ModelTier } from './model-tiers.js';
 /** The top-level scope of a unified config key. */
-export type ConfigScope = 'run' | 'interactive' | 'usage' | 'auto' | 'browser' | 'project' | 'device';
+export type ConfigScope = 'run' | 'interactive' | 'auto' | 'browser' | 'project' | 'device';
 /** A run-time default key: model, mode, effort, or tier override. */
 export interface ParsedRunConfigKey {
     scope: 'run';
@@ -23,20 +23,16 @@ export interface ParsedInteractiveConfigKey {
     scope: 'interactive';
     property: 'host';
 }
-/** The host whose usage snapshots are authoritative for fleet-wide reporting. */
-export interface ParsedUsageConfigKey {
-    scope: 'usage';
-    property: 'primary-host';
-}
 /** Which devices automatic placement (`--device auto`) may pick. */
 export interface ParsedAutoConfigKey {
     scope: 'auto';
     property: 'pool';
 }
-/** The default browser profile (device-scope, self or peer). */
+/** A device-scope browser key (self or peer): the profile agents drive, or the
+ *  browser that shows the user a page. */
 export interface ParsedBrowserConfigKey {
     scope: 'browser';
-    property: 'profile';
+    property: 'profile' | 'viewer';
     device?: string;
 }
 export interface ParsedProjectConfigKey {
@@ -49,8 +45,8 @@ export interface ParsedDeviceConfigKey {
     device: string;
     property: DeviceConfigProperty;
 }
-export type ParsedConfigKey = ParsedRunConfigKey | ParsedInteractiveConfigKey | ParsedUsageConfigKey | ParsedAutoConfigKey | ParsedBrowserConfigKey | ParsedProjectConfigKey | ParsedDeviceConfigKey;
-export type DeviceConfigProperty = 'role' | 'max-agents' | 'scheduler' | 'daemon' | 'watchdog' | 'tmux' | 'browser.remote-control' | 'browser.task-idle-minutes' | 'notes' | 'browser.profile';
+export type ParsedConfigKey = ParsedRunConfigKey | ParsedInteractiveConfigKey | ParsedAutoConfigKey | ParsedBrowserConfigKey | ParsedProjectConfigKey | ParsedDeviceConfigKey;
+export type DeviceConfigProperty = 'role' | 'max-agents' | 'scheduler' | 'daemon' | 'watchdog' | 'tmux' | 'browser.remote-control' | 'browser.task-idle-minutes' | 'notes' | 'browser.profile' | 'browser.viewer';
 /** Normalize agent@version to use `@` consistently. */
 export declare function formatAgentVersion(agent: AgentId, version: string): string;
 /**
@@ -62,7 +58,6 @@ export declare function formatAgentVersion(agent: AgentId, version: string): str
  *   run.<agent@version>.effort
  *   run.<agent@version>.tier.<cheap|default|best|ultra>
  *   interactive.host
- *   usage.primary-host
  *   auto.pool
  *   browser.profile
  *   project.root

package/dist/lib/config-keys.js

@@ -10,6 +10,7 @@ import { AGENTS } from './agents.js';
 import { MODEL_TIERS } from './model-tiers.js';
 import { VERSION_RE } from './run-defaults.js';
 const DEVICE_CONFIG_PROPERTIES = [
+    'browser.viewer',
     'role',
     'max-agents',
     'scheduler',
@@ -47,7 +48,6 @@ export function formatAgentVersion(agent, version) {
  *   run.<agent@version>.effort
  *   run.<agent@version>.tier.<cheap|default|best|ultra>
  *   interactive.host
- *   usage.primary-host
  *   auto.pool
  *   browser.profile
  *   project.root
@@ -79,19 +79,19 @@ export function parseConfigKey(key) {
     if (raw === 'interactive.host') {
         return { scope: 'interactive', property: 'host' };
     }
-    if (raw === 'usage.primary-host') {
-        return { scope: 'usage', property: 'primary-host' };
-    }
     if (raw === 'auto.pool') {
         return { scope: 'auto', property: 'pool' };
     }
     if (raw === 'browser.profile') {
         return { scope: 'browser', property: 'profile' };
     }
+    if (raw === 'browser.viewer') {
+        return { scope: 'browser', property: 'viewer' };
+    }
     if (raw === 'project.root') {
         return { scope: 'project', property: 'root' };
     }
-    const deviceMatch = raw.match(/^devices\.(.+)\.(role|max-agents|scheduler|daemon|watchdog|tmux|notes|browser\.remote-control|browser\.task-idle-minutes|browser\.profile)$/);
+    const deviceMatch = raw.match(/^devices\.(.+)\.(role|max-agents|scheduler|daemon|watchdog|tmux|notes|browser\.remote-control|browser\.task-idle-minutes|browser\.profile|browser\.viewer)$/);
     if (deviceMatch) {
         return {
             scope: 'device',
@@ -106,14 +106,11 @@ export function parseConfigKey(key) {
     if (raw.startsWith('interactive.')) {
         throw new Error(`Invalid interactive config key '${key}'. Use interactive.host.`);
     }
-    if (raw.startsWith('usage.')) {
-        throw new Error(`Invalid usage config key '${key}'. Use usage.primary-host.`);
-    }
     if (raw.startsWith('auto.')) {
         throw new Error(`Invalid auto config key '${key}'. Use auto.pool.`);
     }
     if (raw.startsWith('browser.')) {
-        throw new Error(`Invalid browser config key '${key}'. Use browser.profile.`);
+        throw new Error(`Invalid browser config key '${key}'. Use browser.profile or browser.viewer.`);
     }
     if (raw.startsWith('project.')) {
         throw new Error(`Invalid project config key '${key}'. Use project.root.`);
@@ -121,7 +118,7 @@ export function parseConfigKey(key) {
     if (raw.startsWith('devices.')) {
         throw new Error(`Invalid device config key '${key}'. Expected devices.<name>.<${DEVICE_CONFIG_PROPERTIES.join('|')}>.`);
     }
-    throw new Error(`Unknown config scope in '${key}'. Use one of: run, interactive, usage, auto, browser, project, devices.`);
+    throw new Error(`Unknown config scope in '${key}'. Use one of: run, interactive, auto, browser, project, devices.`);
 }
 /** Render a parsed key back to its canonical dotted string. */
 export function formatConfigKey(parsed) {
@@ -133,12 +130,12 @@ export function formatConfigKey(parsed) {
             return `run.${formatAgentVersion(parsed.agent, parsed.version)}.${parsed.property}`;
         case 'interactive':
             return 'interactive.host';
-        case 'usage':
-            return 'usage.primary-host';
         case 'auto':
             return 'auto.pool';
         case 'browser':
-            return parsed.device ? `devices.${parsed.device}.browser.profile` : 'browser.profile';
+            return parsed.device
+                ? `devices.${parsed.device}.browser.${parsed.property}`
+                : `browser.${parsed.property}`;
         case 'project':
             return 'project.root';
         case 'device':
@@ -152,7 +149,7 @@ export function listKnownConfigKeys() {
     for (const tier of MODEL_TIERS) {
         keys.push(`run.<agent@version>.tier.${tier}`);
     }
-    keys.push('interactive.host', 'usage.primary-host', 'auto.pool', 'browser.profile', 'project.root');
+    keys.push('interactive.host', 'auto.pool', 'browser.profile', 'browser.viewer', 'project.root');
     for (const prop of DEVICE_CONFIG_PROPERTIES) {
         keys.push(`devices.<name>.${prop}`);
     }
@@ -185,6 +182,8 @@ export function devicePropertyToConfigName(property) {
             return 'notes';
         case 'browser.profile':
             return 'browser.profile';
+        case 'browser.viewer':
+            return 'browser.viewer';
     }
 }
 /**
@@ -200,14 +199,14 @@ export function configKeyStorageHint(parsed) {
             return `run.defaults.${parsed.agent}:${parsed.version}.${parsed.property}`;
         case 'interactive':
             return 'config.interactiveHost';
-        case 'usage':
-            return 'config.usagePrimaryHost';
         case 'auto':
             return 'config.autoPool';
-        case 'browser':
+        case 'browser': {
+            const yamlKey = parsed.property === 'viewer' ? 'browserViewer' : 'defaultBrowserProfile';
             return parsed.device
-                ? `devices/${parsed.device}/agents.yaml config.defaultBrowserProfile`
-                : 'devices/<self>/agents.yaml config.defaultBrowserProfile';
+                ? `devices/${parsed.device}/agents.yaml config.${yamlKey}`
+                : `devices/<self>/agents.yaml config.${yamlKey}`;
+        }
         case 'project':
             return 'devices.<self>.projectRoot';
         case 'device':

package/dist/lib/crabbox/cli.d.ts

@@ -242,7 +242,7 @@ export declare function reapSafeOrphans(boxes: CrabboxBox[], nowSecs: number): C
 /**
  * List reap-safe orphans and (unless `dryRun`) stop them. Returns the candidates
  * considered and the slugs actually stopped. Best-effort per box — a stop failure
- * is skipped, never thrown. Backs `agents devices lease gc` and the 403 auto-reap opt-in.
+ * is skipped, never thrown. Backs `agents devices lease prune` and the 403 auto-reap opt-in.
  */
 export declare function reapOrphans(opts?: CrabboxOptions & {
     nowSecs?: number;

package/dist/lib/crabbox/cli.js

@@ -394,7 +394,7 @@ export async function crabboxWarmup(opts = {}) {
                 if (orphans.length) {
                     hint =
                         ` ${orphans.length} expired, idle box(es) are holding the quota — free them with ` +
-                            `\`agents devices lease gc\` (or \`crabbox stop ${orphans[0].slug}\`).`;
+                            `\`agents devices lease prune\` (or \`crabbox stop ${orphans[0].slug}\`).`;
                 }
             }
             catch {
@@ -586,7 +586,7 @@ export function reapSafeOrphans(boxes, nowSecs) {
 /**
  * List reap-safe orphans and (unless `dryRun`) stop them. Returns the candidates
  * considered and the slugs actually stopped. Best-effort per box — a stop failure
- * is skipped, never thrown. Backs `agents devices lease gc` and the 403 auto-reap opt-in.
+ * is skipped, never thrown. Backs `agents devices lease prune` and the 403 auto-reap opt-in.
  */
 export function reapOrphans(opts = {}) {
     const nowSecs = opts.nowSecs ?? Math.floor(Date.now() / 1000);

package/dist/lib/crabbox/lease.d.ts

@@ -115,6 +115,15 @@ export interface LeaseRunResult {
     exitCode: number | null;
     toreDown: boolean;
 }
+/**
+ * Exit code the box-side bootstrap raises when `agents setup` did not leave a
+ * usable install (`~/.agents/.system` is still not a git repo). The run-side gate
+ * (`ensureInitialized`, commands/setup.ts) refuses `agents run` with "agents-cli
+ * is not set up" in exactly that state, so the bootstrap aborts with this code
+ * instead of running the agent into that refusal. `leaseAndRun` reads it to stop
+ * a box THIS run provisioned — a newly created box that can't run is pure cost.
+ */
+export declare const LEASE_BOOTSTRAP_FAILED_CODE = 97;
 /** Build a shell-safe, collision-resistant workspace id for one lease run. */
 export declare function leaseWorkspaceId(repoRoot: string, startedAtMs?: number, pid?: number): string;
 /** Isolated box-home path for one run, relative to the shared box user's home. */

package/dist/lib/crabbox/lease.js

@@ -35,6 +35,15 @@ import { assertNoNativeOAuthTransfer, buildCredentialScript, buildHomeFileWriteS
 import { LEASE_AGENT_MARKER, leasePhaseSentinel } from './progress.js';
 import { copySetupToBox } from './setup-copy.js';
 import { DEFAULT_CRABBOX_PROFILE } from './config.js';
+/**
+ * Exit code the box-side bootstrap raises when `agents setup` did not leave a
+ * usable install (`~/.agents/.system` is still not a git repo). The run-side gate
+ * (`ensureInitialized`, commands/setup.ts) refuses `agents run` with "agents-cli
+ * is not set up" in exactly that state, so the bootstrap aborts with this code
+ * instead of running the agent into that refusal. `leaseAndRun` reads it to stop
+ * a box THIS run provisioned — a newly created box that can't run is pure cost.
+ */
+export const LEASE_BOOTSTRAP_FAILED_CODE = 97;
 /** POSIX single-quote for safe embedding in the generated bootstrap script. */
 function q(s) {
     return "'" + s.replace(/'/g, "'\\''") + "'";
@@ -74,12 +83,14 @@ function runtimeInstallSpec(id, dispatchProfile) {
     return id;
 }
 /**
- * Bash snippet that guarantees `agents` is runnable on the box. Fresh crabbox
- * images ship without node, and the box user may not own the global npm prefix,
- * so everything installs user-level under ~/.local (node from the official
+ * Bash snippet that guarantees `agents` is runnable AND set up on the box. Fresh
+ * crabbox images ship without node, and the box user may not own the global npm
+ * prefix, so everything installs user-level under ~/.local (node from the official
  * latest-v22.x tarball to satisfy engines.node >=22.5.0). Exits 96 with a
- * diagnostic when the CLI still isn't runnable — a silent `|| true` here used
- * to surface only as `agents: command not found` deep in the script.
+ * diagnostic when the CLI still isn't runnable, and {@link LEASE_BOOTSTRAP_FAILED_CODE}
+ * when `agents setup` did not leave a git-repo `~/.agents/.system` — both used to
+ * surface only as a downstream failure (`agents: command not found`, or the run-side
+ * "agents-cli is not set up" gate) after a swallowed `|| true`.
  */
 const ENSURE_AGENTS_CLI = [
     'export PATH="$HOME/.local/bin:$PATH"',
@@ -97,9 +108,22 @@ const ENSURE_AGENTS_CLI = [
     '  echo "lease bootstrap: agents-cli install failed (node: $(command -v node || echo missing))" >&2',
     '  exit 96',
     'fi',
-    // Same first-run guard the hosts bootstrap uses (hosts/ready.ts) — a fresh
-    // install refuses `agents run` with "agents-cli is not set up" until setup ran.
-    'if [ ! -d "$HOME/.agents/.system" ]; then agents setup >/dev/null 2>&1 || true; fi',
+    // The run-side gate (`ensureInitialized`, commands/setup.ts) refuses `agents run`
+    // with "agents-cli is not set up" until `~/.agents/.system` is a GIT REPO. Gate
+    // setup on that same postcondition — not a swallowed exit: capture setup's output,
+    // and if the repo still isn't there afterward, print the real cause and abort so
+    // the box is never run into that refusal (a swallowed `|| true` here is what left
+    // a provisioned box dying at "agents-cli is not set up"). `-e` (not `-d`) matches
+    // the gate's `isGitRepo` (git.ts), which is `existsSync('.git')` — true for a
+    // gitfile/gitlink too, so a linked-worktree `.system` never false-aborts here.
+    'if [ ! -e "$HOME/.agents/.system/.git" ]; then',
+    '  setup_out=$(agents setup 2>&1)',
+    '  if [ ! -e "$HOME/.agents/.system/.git" ]; then',
+    '    echo "lease bootstrap: agents setup did not complete (~/.agents/.system is not a git repo)" >&2',
+    '    printf "%s\\n" "$setup_out" >&2',
+    `    exit ${LEASE_BOOTSTRAP_FAILED_CODE}`,
+    '  fi',
+    'fi',
 ].join('\n');
 /**
  * Build the single bootstrap script run on the box: ensure agents-cli, install
@@ -331,28 +355,59 @@ export async function leaseAndRun(opts) {
                 remoteDir: opts.workspaceId ? `${leaseHomeDir(opts.workspaceId)}/.agents/` : undefined,
             });
         }
-        catch {
-            /* best-effort — never block the run on a config-copy failure */
+        catch (err) {
+            // Best-effort — a config-copy failure never blocks the run (the agent runs
+            // without the pushed ~/.agents config), but surface it instead of swallowing
+            // it silently so a broken sync is visible rather than a mystery.
+            opts.onData?.(`lease: setup copy failed — running without pushed ~/.agents config (${err.message})\n`);
         }
     }
     const script = buildBootstrapScript(opts);
     let exitCode = null;
     let toreDown = false;
+    // Track whether the box-side script reached the agent — the bootstrap echoes
+    // LEASE_AGENT_MARKER on its own line immediately before `agents run`, and aborts
+    // (LEASE_BOOTSTRAP_FAILED_CODE) strictly BEFORE that. So "marker never seen" is
+    // how we tell a pre-agent bootstrap abort from an agent that merely happened to
+    // exit with the same numeric code — only the former is an unusable box. A short
+    // rolling tail keeps the check robust if the marker straddles two output chunks.
+    let sawAgentMarker = false;
+    let markerTail = '';
+    const trackedOnData = (chunk) => {
+        if (!sawAgentMarker) {
+            const combined = markerTail + chunk;
+            if (combined.includes(LEASE_AGENT_MARKER))
+                sawAgentMarker = true;
+            // Keep only enough tail to catch a marker straddling the NEXT chunk boundary.
+            else
+                markerTail = combined.slice(-(LEASE_AGENT_MARKER.length + 8));
+        }
+        opts.onData?.(chunk);
+    };
     try {
         const renewIdleTimeoutSecs = reused && !opts.reuseBox && box.idleTimeoutSecs !== null
             ? box.idleTimeoutSecs
             : undefined;
         exitCode = await crabboxRunScript(box.slug, script, {
             secretsBundle: opts.secretsBundle,
-            onData: opts.onData,
+            onData: trackedOnData,
             renewIdleTimeoutSecs,
         });
     }
     finally {
-        // Normal --lease establishes or reuses the warm pool, so the box outlives
-        // this run; credentials are still shredded inside the script above. Only
-        // --fresh requests the old one-shot lifecycle and tears its new box down.
-        if (!opts.keep && opts.fresh && !reused) {
+        // A box this run PROVISIONED (never a reused one) whose BOOTSTRAP failed is
+        // unusable capacity — keep it and it bills until the idle GC window. Stop it
+        // regardless of --keep-box: the user asked to keep a working box, not a broken
+        // one. A reused box is left alone (a concurrent run may share it). The
+        // failed-code check is gated on the agent never having started (marker unseen),
+        // so an agent that legitimately exits with the same code keeps its --keep-box box.
+        const bootstrapFailed = exitCode === LEASE_BOOTSTRAP_FAILED_CODE && !sawAgentMarker;
+        // Normal --lease establishes or reuses the warm pool, so a healthy box outlives
+        // this run; credentials are still shredded inside the script above. Only --fresh
+        // requests the old one-shot lifecycle and tears its new box down.
+        const teardownHealthy = !opts.keep && opts.fresh && !reused;
+        const teardownBroken = bootstrapFailed && !reused;
+        if (teardownHealthy || teardownBroken) {
             opts.onPhase?.({ kind: 'teardown' });
             toreDown = crabboxStop(box.slug, { secretsBundle: opts.secretsBundle });
         }

package/dist/lib/crabbox/runtimes.js

@@ -32,7 +32,7 @@ export const LEASE_RUNTIMES = [
  * copying any of them between devices — including to an ephemeral leased box —
  * because a shared refresh token rotates server-side on the next refresh and
  * invalidates every other copy (`docs/specifications.md` SING-1b,
- * `docs/credential-management.md` invariant 2). The set is derived from
+ * `docs/secrets.md`). The set is derived from
  * `LEASE_RUNTIMES` so a newly-added runtime can never be silently exempted. This
  * is the single canonical predicate; `--copy-creds` (`hosts/credentials.ts`) and
  * `--lease` (this module's `buildCredentialScript`) both refuse against it.

package/dist/lib/daemon/account-state-daemon-service.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Account-state service lifecycle as a `DaemonService` (RUSH-3193 P2).
+ *
+ * Wraps `startAccountStateService()` under the `ServiceSupervisor` contract
+ * so the supervisor owns start/stop and reports health through the uniform
+ * path. The account-state service owns its own internal intervals for usage
+ * and auth refreshes; the supervisor just starts and stops it.
+ */
+import { BaseDaemonService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+export declare class AccountStateDaemonService extends BaseDaemonService {
+    readonly id: DaemonServiceId;
+    private service;
+    protected onStart(ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+}