@phnx-labs/agents-cli 1.22.114 → 1.22.115

package/dist/lib/session/remote/peer-stream.d.ts

@@ -5,11 +5,29 @@ export declare const PEER_BACKOFF_BASE_MS = 2000;
 export declare const PEER_BACKOFF_CAP_MS = 60000;
 /** Consecutive failed spawns before the peer is parked. */
 export declare const PEER_PARK_AFTER_FAILURES = 3;
+/**
+ * Consecutive failed spawns before the peer is RETIRED — the capped 60 s ladder
+ * gives way to {@link PEER_RETIRED_RECHECK_MS}.
+ *
+ * The cap alone bounds the delay but not the total work: a box that is off for a
+ * weekend was dialed every 60 s for two days, ~2,880 ssh children per watcher
+ * per peer, each one already known to fail. Ten consecutive failures is well
+ * past any transient network event, so past that point the peer is treated as
+ * genuinely absent and re-dialed on the slow cadence instead.
+ */
+export declare const PEER_RETIRE_AFTER_FAILURES = 10;
+/**
+ * Re-dial cadence for a retired peer. Still bounded rather than never, because a
+ * box can come back without anything touching the device registry — waiting
+ * only on a registry change would leave it unreachable until an operator acted.
+ */
+export declare const PEER_RETIRED_RECHECK_MS: number;
 /**
  * Reconnect delay for `failures` consecutive failed spawns: 0 for a healthy
- * peer, then {@link PEER_BACKOFF_BASE_MS} doubling to {@link PEER_BACKOFF_CAP_MS}.
+ * peer, then {@link PEER_BACKOFF_BASE_MS} doubling to {@link PEER_BACKOFF_CAP_MS},
+ * and {@link PEER_RETIRED_RECHECK_MS} once the peer is retired.
  */
-export declare function peerBackoffDelayMs(failures: number, base?: number, cap?: number): number;
+export declare function peerBackoffDelayMs(failures: number, base?: number, cap?: number, retireAfter?: number, retiredMs?: number): number;
 interface PeerStreamOptions {
     /** The device to subscribe to. */
     device: DeviceProfile;
@@ -29,6 +47,10 @@ interface PeerStreamOptions {
     backoffCapMs?: number;
     /** Override the park threshold (tests). */
     parkAfterFailures?: number;
+    /** Override the retire threshold (tests). */
+    retireAfterFailures?: number;
+    /** Override the retired re-dial cadence (tests). */
+    retiredRecheckMs?: number;
     /** Override the ssh binary (tests). */
     sshBin?: string;
     /** Override the parked peer's registry re-check cadence (tests). */

package/dist/lib/session/remote/peer-stream.js

@@ -19,6 +19,9 @@
  * - a peer that fails {@link PEER_PARK_AFTER_FAILURES} spawns in a row parked —
  *   it stops the reconnect cycle and re-dials only when the device registry
  *   changes or the capped backoff elapses;
+ * - a peer that fails {@link PEER_RETIRE_AFTER_FAILURES} in a row RETIRED — the
+ *   capped 60 s ladder is itself unbounded in total work, so past that point the
+ *   re-dial drops to {@link PEER_RETIRED_RECHECK_MS};
  * - abort listeners removed per iteration, so a watcher open for hours does not
  *   accumulate one per reconnect on the caller's AbortSignal.
  */
@@ -34,17 +37,37 @@ export const PEER_BACKOFF_BASE_MS = 2_000;
 export const PEER_BACKOFF_CAP_MS = 60_000;
 /** Consecutive failed spawns before the peer is parked. */
 export const PEER_PARK_AFTER_FAILURES = 3;
+/**
+ * Consecutive failed spawns before the peer is RETIRED — the capped 60 s ladder
+ * gives way to {@link PEER_RETIRED_RECHECK_MS}.
+ *
+ * The cap alone bounds the delay but not the total work: a box that is off for a
+ * weekend was dialed every 60 s for two days, ~2,880 ssh children per watcher
+ * per peer, each one already known to fail. Ten consecutive failures is well
+ * past any transient network event, so past that point the peer is treated as
+ * genuinely absent and re-dialed on the slow cadence instead.
+ */
+export const PEER_RETIRE_AFTER_FAILURES = 10;
+/**
+ * Re-dial cadence for a retired peer. Still bounded rather than never, because a
+ * box can come back without anything touching the device registry — waiting
+ * only on a registry change would leave it unreachable until an operator acted.
+ */
+export const PEER_RETIRED_RECHECK_MS = 15 * 60_000;
 /** Bytes of a peer's stderr retained for the `unavailable` reason. */
 const PEER_STDERR_BYTES = 2_048;
 /** How often a parked peer re-checks the device registry for a refresh. */
 const PEER_REGISTRY_POLL_MS = 5_000;
 /**
  * Reconnect delay for `failures` consecutive failed spawns: 0 for a healthy
- * peer, then {@link PEER_BACKOFF_BASE_MS} doubling to {@link PEER_BACKOFF_CAP_MS}.
+ * peer, then {@link PEER_BACKOFF_BASE_MS} doubling to {@link PEER_BACKOFF_CAP_MS},
+ * and {@link PEER_RETIRED_RECHECK_MS} once the peer is retired.
  */
-export function peerBackoffDelayMs(failures, base = PEER_BACKOFF_BASE_MS, cap = PEER_BACKOFF_CAP_MS) {
+export function peerBackoffDelayMs(failures, base = PEER_BACKOFF_BASE_MS, cap = PEER_BACKOFF_CAP_MS, retireAfter = PEER_RETIRE_AFTER_FAILURES, retiredMs = PEER_RETIRED_RECHECK_MS) {
     if (failures <= 0)
         return 0;
+    if (failures >= retireAfter)
+        return retiredMs;
     return Math.min(cap, base * 2 ** (failures - 1));
 }
 /** Bounded tail of a child's stderr, kept for the unavailable reason. */
@@ -133,10 +156,14 @@ export async function streamFromPeer(options) {
         failures += 1;
         const exit = code == null ? 'ssh failed' : `ssh exited ${code}`;
         const parked = failures >= parkAfter;
-        const delay = peerBackoffDelayMs(failures, options.backoffBaseMs, options.backoffCapMs);
-        options.onUnavailable(parked
-            ? `${reasonFor(exit, stderr)} — parked after ${failures} failed connections, retrying in ${Math.round(delay / 1000)}s or on a device refresh`
-            : reasonFor(exit, stderr));
+        const retireAfter = options.retireAfterFailures ?? PEER_RETIRE_AFTER_FAILURES;
+        const retired = failures >= retireAfter;
+        const delay = peerBackoffDelayMs(failures, options.backoffBaseMs, options.backoffCapMs, retireAfter, options.retiredRecheckMs);
+        options.onUnavailable(retired
+            ? `${reasonFor(exit, stderr)} — retired after ${failures} failed connections, re-dialing in ${Math.round(delay / 60_000)}min or on a device refresh`
+            : parked
+                ? `${reasonFor(exit, stderr)} — parked after ${failures} failed connections, retrying in ${Math.round(delay / 1000)}s or on a device refresh`
+                : reasonFor(exit, stderr));
         await parkedWait(options, delay);
     }
 }

package/dist/lib/session/sync/backend.d.ts

@@ -18,9 +18,9 @@
  * MANAGED-FIRST — the mere PRESENCE of an r2.backups bundle is NOT a BYO
  * override. A signed-in user with a stale r2.backups bundle still backs up to
  * managed unless they opt out explicitly: `--byo`, `AGENTS_SESSIONS_BACKEND=byo`,
- * or a DI write token. This mirrors `lib/share/backend.ts` (a persisted BYO
- * config is deliberately not an override) so the product's managed-first
- * contract is identical across surfaces.
+ * or a DI write token. This mirrors the artifact-share backend contract (a
+ * persisted BYO config is deliberately not an override) so the product's
+ * managed-first contract is identical across surfaces.
  */
 import { type PhoenixSession } from '../../identity/client.js';
 import { type R2Config } from './config.js';

package/dist/lib/session/sync/backend.js

@@ -18,9 +18,9 @@
  * MANAGED-FIRST — the mere PRESENCE of an r2.backups bundle is NOT a BYO
  * override. A signed-in user with a stale r2.backups bundle still backs up to
  * managed unless they opt out explicitly: `--byo`, `AGENTS_SESSIONS_BACKEND=byo`,
- * or a DI write token. This mirrors `lib/share/backend.ts` (a persisted BYO
- * config is deliberately not an override) so the product's managed-first
- * contract is identical across surfaces.
+ * or a DI write token. This mirrors the artifact-share backend contract (a
+ * persisted BYO config is deliberately not an override) so the product's
+ * managed-first contract is identical across surfaces.
  */
 import { readSession } from '../../identity/client.js';
 import { selectStorageBackendKind } from '../../storage/selection.js';

package/dist/lib/session/sync/provision.d.ts

@@ -1,4 +1,4 @@
-import { type CloudflareRequester } from '../../share/provision.js';
+import { type CloudflareRequester } from '../../cloudflare/provision.js';
 interface ProvisionOptions {
     request?: CloudflareRequester;
 }

package/dist/lib/session/sync/provision.js

@@ -1,11 +1,11 @@
 // Cloudflare orchestration for the managed session-backup store. The generic
-// request primitives live in share/provision; only the isolated sessions
+// request primitives live in cloudflare/provision; only the isolated sessions
 // resource choices and Worker template belong here. Mirrors lib/traces/provision.ts.
 //
 // This is the OPERATOR provisioning path — cutting the `agents-sessions` Worker +
 // bucket + custom domain once. Product traffic never runs it; a signed-in user
 // talks to the already-deployed Worker through `SessionsHttpClient`.
-import { addCustomDomain, createBucket, deployWorker, enableWorkersDev, findZoneId, putWorkerSecret, } from '../../share/provision.js';
+import { addCustomDomain, createBucket, deployWorker, enableWorkersDev, findZoneId, putWorkerSecret, } from '../../cloudflare/provision.js';
 import { DEFAULT_SESSIONS_BUCKET_NAME, DEFAULT_SESSIONS_DOMAIN, DEFAULT_SESSIONS_WORKER_NAME, } from './managed-config.js';
 import { renderSessionsWorkerScript } from './worker-template.js';
 /** Bind the Phoenix identity base URL used to verify every session read and write. */

package/dist/lib/sessions-client.js

@@ -70,12 +70,9 @@ const ENGINE_VERBS = new Set([
     'tail',
     'watch',
     'preview',
-    'attach',
     'focus',
     'render',
     'stats',
-    'go',
-    'reconnect',
     'migrations',
     'export',
 ]);

package/dist/lib/setup-tool-install.d.ts

@@ -0,0 +1,3 @@
+import { type SetupTool } from './setup-tool-status.js';
+/** Use the host installer; setup must not install or start a tool from a read. */
+export declare function installSetupTool(tool: Exclude<SetupTool, 'secrets'>): Promise<boolean>;

package/dist/lib/setup-tool-install.js

@@ -0,0 +1,26 @@
+import { installCli, resolveCliManifest } from './cli-resources.js';
+import { getCachedToolSetup, refreshToolSetup } from './setup-tool-status.js';
+const PACKAGES = {
+    browser: '@phnx-labs/browser-cli@0.1.3',
+    computer: '@phnx-labs/computer-cli@0.1.5',
+};
+/** Use the host installer; setup must not install or start a tool from a read. */
+export async function installSetupTool(tool) {
+    if (getCachedToolSetup().find((row) => row.tool === tool)?.installed)
+        return true;
+    const manifest = resolveCliManifest(tool) ?? {
+        name: tool,
+        check: { kind: 'which', cmd: tool },
+        install: [{ npm: PACKAGES[tool] }],
+        source: 'builtin',
+        path: '',
+    };
+    const result = installCli(manifest);
+    if (result.error)
+        console.error(result.error);
+    const rows = await refreshToolSetup(tool);
+    const installed = rows[0]?.installed === true;
+    if (!installed && !result.error)
+        console.error(`${tool} installation did not produce a standalone executable on PATH.`);
+    return result.installed && installed;
+}

package/dist/lib/setup-tool-status.d.ts

@@ -0,0 +1,22 @@
+export declare const SETUP_TOOLS: readonly ["browser", "computer", "secrets"];
+export type SetupTool = typeof SETUP_TOOLS[number];
+export interface ToolSetupRow {
+    tool: SetupTool;
+    installed: boolean | null;
+    executable?: string;
+    version?: string;
+    readiness: 'ready' | 'needs-setup' | 'permission-required' | 'stopped' | 'unsupported' | 'unknown';
+    detail: string;
+    checkedAtMs: number | null;
+}
+export interface ToolSetupOptions {
+    cacheDir?: string;
+}
+export declare function toolSetupCacheDir(options?: ToolSetupOptions): string;
+/** Presence is metadata; health is the last explicit check, never a timer probe. */
+export declare function getCachedToolSetup(options?: ToolSetupOptions): ToolSetupRow[];
+export declare function toolReadiness(tool: SetupTool, status: unknown): Pick<ToolSetupRow, 'readiness' | 'detail'>;
+/** A shared disk lock coalesces overlapping requests from separate CLI clients. */
+export declare function refreshToolSetup(tool?: SetupTool | 'all', options?: ToolSetupOptions): Promise<ToolSetupRow[]>;
+/** File notifications are shared by the daemon collector; no background probes. */
+export declare function subscribeToolSetup(listener: (rows: ToolSetupRow[]) => void, options?: ToolSetupOptions): () => void;

package/dist/lib/setup-tool-status.js

@@ -0,0 +1,215 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { findInPath } from './agent-spec/agents.js';
+import { getCacheDir, getDeviceMetaPath, getHelpersDir, getUserAgentsDir } from './state.js';
+import { atomicWriteJsonSync, withFileLockAsync } from './fs-atomic.js';
+import { probeCapture } from './probe.js';
+import { invocation, isStandaloneComputer } from './computer-client.js';
+import { getSocketPath as browserSocketPath } from './browser/ipc.js';
+export const SETUP_TOOLS = ['browser', 'computer', 'secrets'];
+export function toolSetupCacheDir(options = {}) {
+    return path.join(options.cacheDir ?? getCacheDir(), 'setup-tools');
+}
+function cachePath(tool, options) {
+    return path.join(toolSetupCacheDir(options), `${tool}.json`);
+}
+function setupInputs(tool) {
+    const inputs = [path.join(getUserAgentsDir(), 'agents.yaml'), getDeviceMetaPath()];
+    if (tool === 'browser')
+        inputs.push(browserSocketPath());
+    if (tool === 'computer')
+        inputs.push(process.env.COMPUTER_HELPER_SOCKET || path.join(getHelpersDir(), 'computer.sock'));
+    return inputs;
+}
+function inputStamp(tool) {
+    return setupInputs(tool).map((file) => {
+        try {
+            const stat = fs.statSync(file);
+            return `${file}:${stat.ino}:${stat.mtimeMs}:${stat.size}`;
+        }
+        catch {
+            return `${file}:missing`;
+        }
+    }).join('|');
+}
+function binaryMetadata(tool) {
+    const empty = { tool, installed: false, readiness: 'needs-setup', detail: 'CLI is not installed.', checkedAtMs: null };
+    try {
+        const explicit = process.env[`${tool.toUpperCase()}_BIN`]?.trim();
+        const accept = (candidate) => {
+            if (tool === 'computer')
+                return isStandaloneComputer(candidate);
+            if (tool === 'browser') {
+                try {
+                    return !fs.realpathSync(candidate).endsWith(path.join('dist', 'browser.js'));
+                }
+                catch {
+                    return false;
+                }
+            }
+            return true;
+        };
+        let executable = explicit ? (accept(explicit) ? explicit : null) : findInPath(tool, { accept });
+        if (!executable)
+            return { row: empty, fingerprint: 'missing' };
+        if (/\.(cmd|ps1)$/i.test(executable)) {
+            const packageDir = path.join(path.dirname(executable), 'node_modules', '@phnx-labs', `${tool}-cli`);
+            const pkg = JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8'));
+            const entry = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.[tool];
+            if (pkg.name !== `@phnx-labs/${tool}-cli` || typeof entry !== 'string')
+                throw new Error('unrecognized npm launcher');
+            const resolved = path.resolve(packageDir, entry);
+            if (!resolved.startsWith(`${path.resolve(packageDir)}${path.sep}`))
+                throw new Error('invalid npm entrypoint');
+            executable = resolved;
+        }
+        fs.accessSync(executable, process.platform === 'win32' || /\.[cm]?js$/i.test(executable) ? fs.constants.R_OK : fs.constants.X_OK);
+        const real = fs.realpathSync(executable);
+        const stat = fs.statSync(real);
+        if (!stat.isFile())
+            throw new Error('not a file');
+        let version;
+        let dir = path.dirname(real);
+        for (let depth = 0; depth < 5; depth++) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+                if (pkg.name === `@phnx-labs/${tool}-cli` && typeof pkg.version === 'string') {
+                    version = pkg.version;
+                    break;
+                }
+            }
+            catch { /* Executables need not be npm packages. */ }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return {
+            fingerprint: `${real}:${stat.size}:${stat.mtimeMs}:${version ?? ''}|${inputStamp(tool)}`,
+            row: { tool, installed: true, executable, version, readiness: 'unknown', detail: 'Installed. Health has not been checked.', checkedAtMs: null },
+        };
+    }
+    catch {
+        return { fingerprint: 'unavailable', row: { ...empty, installed: null, readiness: 'unknown', detail: 'Executable could not be inspected.' } };
+    }
+}
+function readCache(tool, options) {
+    try {
+        const cached = JSON.parse(fs.readFileSync(cachePath(tool, options), 'utf8'));
+        if (cached.v === 1 && cached.row?.tool === tool && typeof cached.fingerprint === 'string')
+            return cached;
+    }
+    catch { /* No health result yet. */ }
+    return null;
+}
+/** Presence is metadata; health is the last explicit check, never a timer probe. */
+export function getCachedToolSetup(options = {}) {
+    return SETUP_TOOLS.map((tool) => {
+        const { row, fingerprint } = binaryMetadata(tool);
+        const cached = readCache(tool, options);
+        return cached?.fingerprint === fingerprint ? { ...cached.row, executable: row.executable, version: row.version } : row;
+    });
+}
+export function toolReadiness(tool, status) {
+    if (!status || typeof status !== 'object')
+        return { readiness: 'unknown', detail: 'The CLI returned an unreadable health result.' };
+    const value = status;
+    if (tool === 'computer') {
+        if (value.installed === false)
+            return { readiness: 'needs-setup', detail: 'CLI installed; computer helper needs setup.' };
+        if (value.running === true && value.trusted === true)
+            return { readiness: 'ready', detail: 'Helper is running and Accessibility is granted. Screen Recording is checked when capturing.' };
+        if (value.running === true && value.trusted === false)
+            return { readiness: 'permission-required', detail: 'Grant Accessibility to Agents Computer in System Settings.' };
+        if (value.running === false)
+            return { readiness: 'stopped', detail: 'Computer helper is stopped or unreachable.' };
+    }
+    if (tool === 'browser') {
+        if (value.running === true)
+            return { readiness: 'ready', detail: 'Browser service is running.' };
+        if (value.running === false)
+            return { readiness: 'stopped', detail: 'Browser service is stopped.' };
+    }
+    return { readiness: 'unknown', detail: typeof value.error === 'string' && value.error.trim() ? value.error.slice(0, 500) : 'The CLI did not report a recognized health state.' };
+}
+async function checkTool(row) {
+    if (!row.installed || !row.executable)
+        return { ...row, checkedAtMs: Date.now() };
+    // The standalone has no non-interactive health JSON. Do not list bundles or
+    // unlock the broker merely to paint a settings row.
+    if (row.tool === 'secrets')
+        return { ...row, checkedAtMs: Date.now(), detail: 'Installed. Secret access is checked when used; this check does not unlock secrets.' };
+    try {
+        const { command, prefix } = invocation(row.executable);
+        const { stdout } = await probeCapture(command, [...prefix, 'status', '--json'], 8000, { acceptedExitCodes: [0, 1], maxOutputBytes: 256 * 1024 });
+        return { ...row, ...toolReadiness(row.tool, JSON.parse(stdout)), checkedAtMs: Date.now() };
+    }
+    catch {
+        return { ...row, readiness: 'unknown', detail: 'Health check failed or timed out. Check again to retry.', checkedAtMs: Date.now() };
+    }
+}
+/** A shared disk lock coalesces overlapping requests from separate CLI clients. */
+export async function refreshToolSetup(tool = 'all', options = {}) {
+    const requestedAt = Date.now();
+    const dir = toolSetupCacheDir(options);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    for (const selected of tool === 'all' ? SETUP_TOOLS : [tool]) {
+        const file = cachePath(selected, options);
+        await withFileLockAsync(file, async () => {
+            const metadata = binaryMetadata(selected);
+            const cached = readCache(selected, options);
+            if (cached?.fingerprint === metadata.fingerprint && (cached.row.checkedAtMs ?? 0) >= requestedAt)
+                return;
+            const row = await checkTool(metadata.row);
+            atomicWriteJsonSync(file, { v: 1, fingerprint: metadata.fingerprint, row });
+        }, { realpath: false, acquireTimeoutMs: 20_000 });
+    }
+    return getCachedToolSetup(options).filter((row) => tool === 'all' || row.tool === tool);
+}
+/** File notifications are shared by the daemon collector; no background probes. */
+export function subscribeToolSetup(listener, options = {}) {
+    const dir = toolSetupCacheDir(options);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const paths = new Set([dir, ...(process.env.PATH ?? '').split(path.delimiter).filter(Boolean)]);
+    for (const tool of SETUP_TOOLS)
+        for (const input of setupInputs(tool))
+            paths.add(path.dirname(input));
+    for (const row of getCachedToolSetup(options)) {
+        if (row.executable) {
+            paths.add(path.dirname(row.executable));
+            try {
+                paths.add(path.dirname(fs.realpathSync(row.executable)));
+            }
+            catch { /* Removed since discovery. */ }
+        }
+    }
+    let previous = JSON.stringify(getCachedToolSetup(options));
+    let debounce;
+    const changed = () => {
+        if (debounce)
+            return;
+        debounce = setTimeout(() => {
+            debounce = undefined;
+            const rows = getCachedToolSetup(options);
+            const next = JSON.stringify(rows);
+            if (next !== previous) {
+                previous = next;
+                listener(rows);
+            }
+        }, 150);
+        debounce.unref();
+    };
+    const watchers = [];
+    for (const target of paths) {
+        try {
+            const watcher = fs.watch(target, { persistent: false }, changed);
+            watcher.on('error', changed);
+            watchers.push(watcher);
+        }
+        catch { /* Absent PATH entries have no executable to report. */ }
+    }
+    changed();
+    return () => { if (debounce)
+        clearTimeout(debounce); for (const watcher of watchers)
+        watcher.close(); };
+}

package/dist/lib/share-runtime.d.ts

@@ -0,0 +1,11 @@
+/** Best-effort runtime env for spawned agents. Never throws AND never prompts.
+ *
+ * Auto-injecting the share write token on every `agents run` is a background
+ * convenience, NOT a user-initiated secret access — so it MUST NOT raise a Touch
+ * ID sheet (SEC-13: an agent launch never pops biometry on its own). The read is
+ * always `agentOnly`: it resolves the token only from the injected env or an
+ * already-held / no-ACL bundle, and silently returns undefined otherwise (the
+ * agent can still publish via its own `artifacts share` credentials). For
+ * zero-friction auto-share with no prompt: unlock once (`agents secrets unlock
+ * share`) or make it no-ACL (`agents secrets policy share never`). */
+export declare function shareRuntimeEnv(): Record<string, string> | undefined;

package/dist/lib/share-runtime.js

@@ -0,0 +1,63 @@
+// Runtime share-token injection for spawned agents.
+//
+// The artifact share ENGINE moved to `@phnx-labs/artifacts-cli` (PHNX-3992);
+// agents-cli no longer publishes artifacts itself. What stays here is the thin
+// glue that lets a dispatched agent inherit the operator's BYO write token so
+// its own `artifacts share` can publish headlessly: `run`/`teams`/`cloud`
+// dispatch call `shareRuntimeEnv()` and forward the result into the agent env.
+// artifacts-cli honors the same `SHARE_WRITE_TOKEN` variable, so the injection
+// contract is unchanged by the extraction.
+//
+// The endpoint config still lives in `agents.yaml` under `share:` (Meta.share)
+// so a previously-provisioned BYO endpoint keeps syncing fleet-wide; the raw
+// write token lives in the keychain-backed `share` secrets bundle, never on disk.
+import { readMeta } from './state.js';
+import { bundleExistsSync as bundleExists, readAndResolveBundleEnvSync as readAndResolveBundleEnv, } from './secrets-client.js';
+const SHARE_BUNDLE = 'share';
+const SHARE_TOKEN_KEY = 'WRITE_TOKEN';
+const SHARE_TOKEN_ENV_KEY = 'SHARE_WRITE_TOKEN';
+/** Trim; empty / whitespace-only strings are absent. */
+function nonempty(v) {
+    const t = v?.trim();
+    return t ? t : undefined;
+}
+/** Whether a BYO share endpoint is still configured in `agents.yaml`. */
+function hasShareEndpoint() {
+    return !!nonempty(readMeta().share?.baseUrl);
+}
+/** The write token as injected ephemerally into fleet/cloud agents. */
+function readWriteTokenEnv(env = process.env) {
+    const token = env[SHARE_TOKEN_ENV_KEY]?.trim();
+    return token ? token : null;
+}
+/** Best-effort runtime env for spawned agents. Never throws AND never prompts.
+ *
+ * Auto-injecting the share write token on every `agents run` is a background
+ * convenience, NOT a user-initiated secret access — so it MUST NOT raise a Touch
+ * ID sheet (SEC-13: an agent launch never pops biometry on its own). The read is
+ * always `agentOnly`: it resolves the token only from the injected env or an
+ * already-held / no-ACL bundle, and silently returns undefined otherwise (the
+ * agent can still publish via its own `artifacts share` credentials). For
+ * zero-friction auto-share with no prompt: unlock once (`agents secrets unlock
+ * share`) or make it no-ACL (`agents secrets policy share never`). */
+export function shareRuntimeEnv() {
+    if (!hasShareEndpoint())
+        return undefined;
+    const fromEnv = readWriteTokenEnv();
+    if (fromEnv)
+        return { [SHARE_TOKEN_ENV_KEY]: fromEnv };
+    try {
+        if (!bundleExists(SHARE_BUNDLE))
+            return undefined;
+        const { env } = readAndResolveBundleEnv(SHARE_BUNDLE, {
+            caller: 'share',
+            keys: [SHARE_TOKEN_KEY],
+            agentOnly: true, // never raise a Touch ID sheet on an agent launch (SEC-13)
+        });
+        const token = env[SHARE_TOKEN_KEY];
+        return token ? { [SHARE_TOKEN_ENV_KEY]: token } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/lib/smart-launch.d.ts

@@ -117,16 +117,12 @@ type DeviceAutoHostOptions = {
     device?: string;
     on?: string;
     computer?: string;
-    /** @deprecated Hidden alias for `--device auto`. */
-    smart?: boolean;
     balanced?: boolean;
     strategy?: string;
 };
 export type DeviceAutoApplyResult = {
     /** True when automatic placement ran successfully. */
     attempted: boolean;
-    /** True when deprecated `--smart` was seen. */
-    deprecationSmart: boolean;
     /** Present when affinity resolved without error. */
     banner?: {
         hostLabel: string;
@@ -135,7 +131,7 @@ export type DeviceAutoApplyResult = {
     };
 };
 /**
- * Apply `--device auto` (and deprecated `--smart`) onto run options.
+ * Apply `--device auto` onto run options.
  * Mutates `options` in place. Placement failures propagate without rewriting
  * `auto`, so callers fail loud instead of silently launching locally.
  */

package/dist/lib/smart-launch.js

@@ -176,7 +176,7 @@ export async function resolveDeviceAuto(agent, opts = {}) {
     if (eligiblePool.length === 0) {
         throw new Error(formatNoHealthyDeviceError(pool, signals, agent));
     }
-    // `agents devices prefer <name>` boosts a device in the ranking — resolved
+    // `agents devices config <name> auto-launch.preferred on` boosts a device in the ranking — resolved
     // over the same pool so a fleet default reaches a doc-less box.
     const preferred = opts.preferred ?? autoLaunchPreferredSet(pool, { roster: pool });
     const picked = pickBestDevice(eligiblePool, [], { signals, agentLabel: agent, preferred });
@@ -260,21 +260,14 @@ export function isDeviceAuto(value) {
 }
 const HOST_SLOTS = ['host', 'device', 'on', 'computer'];
 /**
- * Apply `--device auto` (and deprecated `--smart`) onto run options.
+ * Apply `--device auto` onto run options.
  * Mutates `options` in place. Placement failures propagate without rewriting
  * `auto`, so callers fail loud instead of silently launching locally.
  */
 export async function applyDeviceAutoToOptions(options, deps = {}) {
-    let deprecationSmart = false;
-    if (options.smart) {
-        const anyHost = HOST_SLOTS.some((k) => typeof options[k] === 'string' && options[k].trim() !== '');
-        if (!anyHost)
-            options.device = 'auto';
-        deprecationSmart = true;
-    }
     const hasAuto = HOST_SLOTS.some((k) => isDeviceAuto(options[k]));
     if (!hasAuto) {
-        return { attempted: false, deprecationSmart };
+        return { attempted: false };
     }
     const accountPickerRequested = deps.accountPickerRequested ?? false;
     const resolve = deps.resolve ?? ((accountPicker) => resolveDeviceAuto(deps.agent, { accountPicker }));
@@ -296,7 +289,6 @@ export async function applyDeviceAutoToOptions(options, deps = {}) {
     const acctNote = accountPickerRequested ? 'accounts=picker' : 'accounts=balanced';
     return {
         attempted: true,
-        deprecationSmart,
         banner: { hostLabel, deviceHint, acctNote },
     };
 }

package/dist/lib/ssh-exec.d.ts

@@ -173,6 +173,50 @@ interface SshExecRawStreamOptions extends SshExecOptions {
  * offset-resumed log following where a UTF-8 decode boundary must not shift the
  * byte cursor.
  */
+/** Grace between SIGTERM and SIGKILL for a stream that will not stop. */
+export declare const SSH_STREAM_KILL_GRACE_MS = 3000;
+/** Bytes of a stream's stderr retained; the rest is dropped, with a note. */
+export declare const SSH_STREAM_MAX_STDERR: number;
+export interface SshStreamResult {
+    code: number | null;
+    stderr: Buffer;
+    timedOut: boolean;
+    /** True when the child had to be SIGKILLed after ignoring SIGTERM. */
+    killed: boolean;
+    /** True when stderr was truncated at {@link SSH_STREAM_MAX_STDERR}. */
+    stderrTruncated: boolean;
+}
+/**
+ * Stream one ssh command's stdout, with the args and env a CALLER built.
+ *
+ * This exists because {@link sshExecRawStream} assembles its own ssh args, which
+ * means it cannot carry a device's canonical auth — the askpass shim for a
+ * password-auth box, `-i`/`IdentitiesOnly` for an explicit identity file, or the
+ * managed known-hosts pinning. A caller that has already built those through
+ * `buildSshInvocation` needs a way to run them, and duplicating the transport to
+ * get it would be the worse answer. So this takes `args`/`env` verbatim and adds
+ * only the lifecycle guarantees:
+ *
+ * - **SIGTERM then SIGKILL.** A timeout or abort that only sends SIGTERM leaks a
+ *   child that ignores it — ssh does, mid-handshake — and the promise never
+ *   settles. After {@link SSH_STREAM_KILL_GRACE_MS} the child is SIGKILLed and
+ *   `killed` says so.
+ * - **Bounded stderr.** A peer that writes endlessly to stderr would otherwise
+ *   grow this buffer without limit; it is capped and `stderrTruncated` says so.
+ * - **`onStdout` cannot break the caller's cleanup.** A throw from the consumer
+ *   is captured and re-thrown by the awaiting caller, so a write failure ends the
+ *   transfer instead of escaping as an unhandled error inside a stream event.
+ */
+export declare function sshStreamWithArgs(opts: {
+    args: string[];
+    env?: Record<string, string>;
+    onStdout: (chunk: Buffer) => void;
+    timeoutMs?: number;
+    killGraceMs?: number;
+    maxStderrBytes?: number;
+    signal?: AbortSignal;
+    sshBin?: string;
+}): Promise<SshStreamResult>;
 export declare function sshExecRawStream(target: string, remoteCmd: string, opts: SshExecRawStreamOptions): Promise<Omit<SshExecRawResult, 'stdout'>>;
 /** True if `target` is reachable over ssh (a passwordless `true` succeeds quickly). */
 export declare function sshReachable(target: string, timeoutMs?: number): boolean;