@phnx-labs/agents-cli 1.20.77 → 1.20.82

package/dist/lib/session/discover.js

@@ -26,7 +26,8 @@ import { extractSessionTopic } from './prompt.js';
 import { parseAntigravity } from './parse.js';
 import { extractPrUrl, detectWorktree, detectTicket, isPrCreateCommand, detectSpawnedTeam, isTicketCreateTool, extractCreatedTicket, extractRecentDirectoriesTouched, extractTodoProgressFromEvents } from './state.js';
 import { costOfUsage } from '../pricing/index.js';
-import { machineId } from './sync/config.js';
+import { machineForSessionFile } from './origin-machine.js';
+export { machineForSessionFile } from './origin-machine.js';
 import { mapBounded } from '../concurrency.js';
 import { getDB, getScanStampByPath, getScanStampsForPaths, getParserStatesForPaths, getDirLedgerForPaths, recordDirScans, recordScans, syncLabels, seedLabelsFromNames, syncTopics, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, cacheLinearProject, } from './db.js';
 import { buildRunNameMap } from './run-names.js';
@@ -223,7 +224,6 @@ function dispatchAgentScan(agent, onProgress) {
         default: return Promise.resolve();
     }
 }
-let _localMachineId;
 /**
  * The machine a discovered session originated on. Cross-machine sync mirrors a
  * remote transcript to backups/<agent>/<machine>/<subdir>/… (see mirrorPath in
@@ -270,15 +270,6 @@ export function isManagedSessionFile(filePath) {
         return !!realRoot && real.startsWith(realRoot + path.sep);
     });
 }
-export function machineForSessionFile(filePath, agent) {
-    const base = path.join(getHistoryDir(), 'backups', agent) + path.sep;
-    if (filePath.startsWith(base)) {
-        const seg = filePath.slice(base.length).split(path.sep)[0];
-        if (seg)
-            return seg;
-    }
-    return (_localMachineId ??= machineId());
-}
 /**
  * Count sessions in scope without running an incremental scan. Assumes the DB
  * is already fresh (typically true because `discoverSessions` ran first this
@@ -388,6 +379,23 @@ export function isCompleteSessionId(query) {
     const q = query.trim().toLowerCase();
     return UUID_36.test(q.replace(SESSION_UUID_PREFIX, '')) || SES_ULID.test(q);
 }
+/**
+ * Whether a query should be treated as a session id rather than a search phrase
+ * — the one canonical id-shaped test, shared by every session-id resolver.
+ *
+ * True for a complete id (`isCompleteSessionId`) AND for a bare hex short-id or
+ * prefix (`d3470b57`), which the complete-id check rejects. Any id-shaped query
+ * resolves by id ONLY (exact -> prefix -> `findSessionsById` index) and must
+ * never fall back to fuzzy content search: a short id like `d3470b57` otherwise
+ * surfaces every transcript that merely MENTIONS the string (a resume prompt
+ * echoes the parent id into the body of many later sessions). The hex test
+ * catches the bare short-id/prefix; `isCompleteSessionId` additionally catches
+ * the prefixed whole ids (`session_…`, `ses_…`) that the hex test rejects.
+ */
+export function looksLikeSessionId(query) {
+    const trimmed = query.trim();
+    return /^[0-9a-f-]{6,}$/i.test(trimmed) || isCompleteSessionId(trimmed);
+}
 /**
  * Resolve a session by full or short ID. Accepts a pre-loaded session list
  * (fast path from discoverSessions) and falls back to a DB lookup for the
@@ -992,6 +1000,7 @@ async function readClaudeMeta(filePath, sessionId, scanStamp, priorRow, account,
             filePath,
             gitBranch: scan.gitBranch,
             version: scan.version,
+            model: scan.model,
             account,
             topic: scan.topic,
             label,
@@ -1022,6 +1031,7 @@ async function readClaudeMeta(filePath, sessionId, scanStamp, priorRow, account,
             lastActivity: scan.lastActivity,
             filePath,
             account,
+            model: scan.model,
             label,
             messageCount: scan.messageCount,
             tokenCount: scan.tokenCount,
@@ -1319,6 +1329,7 @@ export async function readCodexMeta(filePath, resolveAccount, currentVersion, sc
         filePath,
         gitBranch: scan.gitBranch,
         version: resolveSessionVersion('codex', filePath, scan.version, currentVersion),
+        model: scan.model,
         topic: scan.topic,
         messageCount: scan.messageCount,
         tokenCount: scan.tokenCount,
@@ -1537,6 +1548,7 @@ function readGeminiMeta(filePath, hashDir, projectMap, currentVersion) {
         cwd,
         filePath,
         version: resolveSessionVersion('gemini', filePath, embeddedVersion, currentVersion),
+        model: sessionModel,
         topic,
         messageCount,
         tokenCount: sawTokenCount ? tokenCount : undefined,
@@ -2154,6 +2166,7 @@ function readHermesMeta(filePath) {
         project: platform,
         filePath,
         version: model,
+        model,
         topic,
         messageCount: messageCount || (typeof session.message_count === 'number' ? session.message_count : undefined),
     };
@@ -2252,6 +2265,7 @@ async function readDroidMeta(filePath, currentVersion) {
         cwd,
         filePath,
         version: resolveSessionVersion('droid', filePath, undefined, currentVersion),
+        model,
         topic: scan.topic,
         messageCount: scan.messageCount,
         tokenCount,
@@ -2395,6 +2409,7 @@ export function initClaudeParseState() {
         cwd: undefined,
         gitBranch: undefined,
         version: undefined,
+        model: undefined,
         topic: undefined,
         customTitle: undefined,
         aiTitle: undefined,
@@ -2579,6 +2594,8 @@ export function applyClaudeLine(state, parsed) {
     // Per-assistant-message cost: each event carries its own model, so we
     // multiply that event's raw token directions by that model's price.
     const model = parsed.message?.model;
+    if (typeof model === 'string' && model)
+        state.model = model;
     if (model && usageObj && typeof usageObj === 'object') {
         const eventCost = costOfUsage({
             model,
@@ -2611,6 +2628,7 @@ export function finalizeClaudeScan(state) {
         cwd: state.cwd,
         gitBranch: state.gitBranch,
         version: state.version,
+        model: state.model,
         topic: resolvedTopic,
         entrypoint: state.entrypoint,
         messageCount: state.messageCount,
@@ -2676,6 +2694,7 @@ export function serializeClaudeParserState(state, offset) {
         cwd: state.cwd,
         gitBranch: state.gitBranch,
         version: state.version,
+        model: state.model,
         entrypoint: state.entrypoint,
         firstTsMs: state.firstTsMs,
         topic: state.topic,
@@ -2736,6 +2755,7 @@ export function hydrateClaudeParseState(prior) {
         cwd: prior.cwd,
         gitBranch: prior.gitBranch,
         version: prior.version,
+        model: prior.model,
         topic: prior.topic,
         customTitle: prior.customTitle,
         aiTitle: prior.aiTitle,
@@ -3090,6 +3110,7 @@ export function finalizeCodexScan(state) {
         cwd: state.cwd,
         gitBranch: state.gitBranch,
         version: state.version,
+        model: state.model,
         topic: state.topic,
         messageCount: state.messageCount,
         tokenCount: state.tokenCount,

package/dist/lib/session/hook-sessions.d.ts

@@ -14,6 +14,15 @@ export interface HookSessionIndex {
     byTerminalId: Map<string, HookSessionRecord>;
     byPid: Map<number, HookSessionRecord>;
 }
+/**
+ * Read the deployed hook's record for one specific pid, or undefined if absent /
+ * corrupt / not fresh. `startedAtMs` (the live process's known start, when the
+ * caller has it) rejects a stale record left by a PRIOR process at a reused pid:
+ * the hook writes its record AFTER the agent boots, so a record whose `ts`
+ * predates the current process's start belongs to a dead predecessor. `ts` is
+ * Unix SECONDS (the hook stamps `date +%s`); `startedAtMs` is millis.
+ */
+export declare function readStateSessionRecord(pid: number, startedAtMs?: number): HookSessionRecord | undefined;
 /**
  * Scan the hook state dir once and index every record by launch_id, terminal_id,
  * and pid. Returns empty maps if the dir is absent. Newest-by-`ts` wins a key

package/dist/lib/session/hook-sessions.js

@@ -1,13 +1,18 @@
 /**
  * Read-only view of the SessionStart hook's live-session state files.
  *
- * The `@agents/session-tracker` hook (installed into each agent's own config)
- * writes `~/.agents/.cache/terminals/sessions/<pid>.json` AFTER an agent boots,
- * carrying the agent's OWN authoritative session id (from its SessionStart
- * payload) plus the join keys `launch_id` / `terminal_id`. It is the only writer
- * that sees agents `ag run` did NOT launch (you typing `claude` in a terminal),
- * and the only source of an exact id for non-Claude agents (whose id we can't
- * know at spawn).
+ * Two on-disk sources carry a non-Claude agent's authoritative id (whose id we
+ * can't know at spawn), both read here:
+ *   1. The `@agents/session-tracker` hook writes
+ *      `~/.agents/.cache/terminals/sessions/<pid>.json` with the id plus the join
+ *      keys `launch_id` / `terminal_id`. Rich schema, but this package is NOT
+ *      deployed on the fleet — its dir is empty there. Scanned into the index by
+ *      {@link loadHookSessionIndex}.
+ *   2. The ACTUALLY-DEPLOYED SessionStart hook writes
+ *      `~/.agents/.cache/state/sessions/<pid>.json` ({@link readStateSessionRecord})
+ *      — `{session_id,cwd,pid,ts}`, keyed purely by pid. This is the real fleet id
+ *      source for every agent; read targeted per-pid, never scanned (RUSH-2007).
+ * Both see agents `ag run` did NOT launch (you typing `claude` in a terminal).
  *
  * This module lets `sessions --active` reconcile a `ps`-discovered pid to that
  * authoritative id. It is deliberately a small hand-rolled reader — the CLI does
@@ -23,12 +28,56 @@
  */
 import fs from 'fs';
 import path from 'path';
-import { getTerminalsDir } from '../state.js';
+import { getTerminalsDir, getRuntimeStateDir } from '../state.js';
 function hookSessionsDir() {
     // Sibling of the pid-registry's by-pid/ dir. The hook hardcodes this same path
     // (packages/session-tracker/src/hook.sh); we read it, never move it.
     return path.join(getTerminalsDir(), 'sessions');
 }
+/**
+ * The path the ACTUALLY-DEPLOYED SessionStart hook writes:
+ * `~/.agents/.cache/state/sessions/<pid>.json`, carrying `{session_id,cwd,pid,ts}`
+ * for EVERY agent (claude/codex/gemini/kimi/grok/antigravity). This is the fleet's
+ * real id source; the `terminals/sessions/` path above belongs to the separate
+ * `@agents/session-tracker` package, which is not deployed (its dir is empty on the
+ * fleet), so a non-Claude tmux session's id resolved ONLY through the index above
+ * never landed (RUSH-2007). These records are keyed purely by pid — no
+ * launch_id/terminal_id/agent — so they join only on pid. The dir is an unpruned
+ * graveyard (thousands of dead-pid files), so this is a TARGETED per-pid read on
+ * demand, never a full-dir scan folded into {@link loadHookSessionIndex}.
+ */
+function stateSessionRecordPath(pid) {
+    return path.join(getRuntimeStateDir(), 'sessions', `${pid}.json`);
+}
+/**
+ * Read the deployed hook's record for one specific pid, or undefined if absent /
+ * corrupt / not fresh. `startedAtMs` (the live process's known start, when the
+ * caller has it) rejects a stale record left by a PRIOR process at a reused pid:
+ * the hook writes its record AFTER the agent boots, so a record whose `ts`
+ * predates the current process's start belongs to a dead predecessor. `ts` is
+ * Unix SECONDS (the hook stamps `date +%s`); `startedAtMs` is millis.
+ */
+export function readStateSessionRecord(pid, startedAtMs) {
+    if (!pid || pid < 1)
+        return undefined;
+    let rec;
+    try {
+        rec = parseRecord(fs.readFileSync(stateSessionRecordPath(pid), 'utf8'));
+    }
+    catch {
+        return undefined; // absent (the common case) or unreadable
+    }
+    if (!rec)
+        return undefined;
+    if (startedAtMs !== undefined && typeof rec.ts === 'number') {
+        // Allow a small skew: the hook fires just after exec, and ts is second-
+        // granular so it can floor to just before a sub-second process start.
+        const SKEW_MS = 5_000;
+        if (rec.ts * 1000 < startedAtMs - SKEW_MS)
+            return undefined; // reused-pid graveyard record
+    }
+    return rec;
+}
 function parseRecord(raw) {
     try {
         const o = JSON.parse(raw);

package/dist/lib/session/origin-machine.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Resolve which machine a session transcript originated on.
+ *
+ * Cross-machine sync mirrors a remote transcript to
+ * `backups/<agent>/<machine>/<subdir>/…`. Every other transcript is a live-home
+ * file on this box, so the origin is the local machine id.
+ *
+ * Kept in a leaf module (no session/db imports) so both discovery and the
+ * sessions DB upsert path can stamp `machine` without circular deps.
+ */
+/** Local machine id, cached for the process lifetime. */
+export declare function localMachineId(): string;
+/**
+ * The machine a discovered session originated on.
+ * When the path sits under the agent's backups root, the first segment below it
+ * is the origin machine id; otherwise it's the local machine.
+ */
+export declare function machineForSessionFile(filePath: string, agent: string): string;

package/dist/lib/session/origin-machine.js

@@ -0,0 +1,34 @@
+/**
+ * Resolve which machine a session transcript originated on.
+ *
+ * Cross-machine sync mirrors a remote transcript to
+ * `backups/<agent>/<machine>/<subdir>/…`. Every other transcript is a live-home
+ * file on this box, so the origin is the local machine id.
+ *
+ * Kept in a leaf module (no session/db imports) so both discovery and the
+ * sessions DB upsert path can stamp `machine` without circular deps.
+ */
+import * as path from 'path';
+import { getHistoryDir } from '../state.js';
+import { machineId } from '../machine-id.js';
+let _localMachineId;
+/** Local machine id, cached for the process lifetime. */
+export function localMachineId() {
+    return (_localMachineId ??= machineId());
+}
+/**
+ * The machine a discovered session originated on.
+ * When the path sits under the agent's backups root, the first segment below it
+ * is the origin machine id; otherwise it's the local machine.
+ */
+export function machineForSessionFile(filePath, agent) {
+    if (!filePath)
+        return localMachineId();
+    const base = path.join(getHistoryDir(), 'backups', agent) + path.sep;
+    if (filePath.startsWith(base)) {
+        const seg = filePath.slice(base.length).split(path.sep)[0];
+        if (seg)
+            return seg;
+    }
+    return localMachineId();
+}

package/dist/lib/session/pid-registry.d.ts

@@ -4,6 +4,19 @@ export interface PidSessionEntry {
     /** The launch session id. Present for agents launched with a known id (Claude). */
     sessionId?: string;
     cwd?: string;
+    /**
+     * Resolved actor id (`resolveActor().id`) stamped at spawn — who initiated this
+     * run. A tailnet login/email for a resolved human, or `UNRESOLVED@<host>` when
+     * it can't be determined. Read back by the active-sessions path to surface an
+     * `owner` per session (RUSH-2018), so a co-located fleet shows who launched what.
+     */
+    actor?: string;
+    /**
+     * The actor's kind (`resolveActor().kind`): `'human'` for a person-initiated
+     * run, `'agent'` for one an agent spawned. Pairs with {@link actor} the same way
+     * `AGENTS_ACTOR` / `AGENTS_ACTOR_KIND` do on the exec env.
+     */
+    initiatedBy?: 'human' | 'agent';
     /**
      * The launch id minted by `ag run` and exported to the child as
      * `AGENT_LAUNCH_ID`. The agent's SessionStart hook records the SAME id in its

package/dist/lib/session/render.d.ts

@@ -64,6 +64,8 @@ export interface SessionStats {
 }
 /** Compute aggregate statistics (turns, tools, tokens, duration) from session events. */
 export declare function computeSummaryStats(events: SessionEvent[]): SessionStats;
+/** Strip the 'claude-' prefix and date suffix from a model identifier. */
+export declare function shortenModel(model: string): string;
 /** Format a duration in milliseconds as a human-readable string (e.g. '12 min', '2h 30min'). */
 export declare function formatDuration(ms: number): string;
 /**

package/dist/lib/session/render.js

@@ -220,7 +220,7 @@ export function computeSummaryStats(events) {
     };
 }
 /** Strip the 'claude-' prefix and date suffix from a model identifier. */
-function shortenModel(model) {
+export function shortenModel(model) {
     return model.replace(/^claude-/, '').replace(/-\d{8}$/, '');
 }
 /** Format a token count as a human-readable string (e.g. 67.5K, 1.2M). */

package/dist/lib/session/state.d.ts

@@ -130,6 +130,7 @@ export declare function extractTodoProgress(args?: Record<string, any>): TodoPro
 export declare function extractTodoProgressFromEvents(events: SessionEvent[]): TodoProgress | undefined;
 /** Derive a recency-ordered, de-duplicated list of directories touched by tools. */
 export declare function extractRecentDirectoriesTouched(events: SessionEvent[], cwd?: string): string[] | undefined;
+export declare const WORKTREE_RE: RegExp;
 /** Detect a worktree from the session cwd, per the `.agents/worktrees/<slug>/` convention. */
 export declare function detectWorktree(cwd?: string, branch?: string): DetectedWorktree | undefined;
 /** Detect a tracker ticket from free text (prompt/topic) then a branch name. */

package/dist/lib/session/state.js

@@ -188,7 +188,7 @@ const TICKET_BRANCH_RE = /(?:^|[/_-])([a-z]{2,6})-(\d{2,6})(?=[/_-]|$)/;
 /** Keys that look like tickets but aren't — avoid false positives from branches. */
 const TICKET_DENYLIST = new Set(['UTF', 'SHA', 'ISO', 'RFC', 'IPV', 'X86', 'ARM', 'MP', 'H']);
 const PR_URL_RE = /https:\/\/github\.com\/[^\s"'()<>]+\/pull\/(\d+)/;
-const WORKTREE_RE = /\/\.agents\/worktrees\/([^/]+)/;
+export const WORKTREE_RE = /\/\.agents\/worktrees\/([^/]+)/;
 /** gh invocations that create/open a PR. */
 const GH_PR_CREATE_RE = /\bgh\s+pr\s+(?:create|new)\b/;
 /** gh invocation that opens an issue — the created number is read from its result. */

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

@@ -15,8 +15,8 @@ function resolveR2Config() {
     // The daemon monitor loop is headless by construction (no TTY, ever), so
     // isHeadlessSecretsContext() is true here and this resolves broker-only — a
     // broker miss can never pop an unattended Touch ID sheet on the user's screen
-    // (same rationale as daemon.ts readDaemonClaudeOAuthToken). Using the shared
-    // predicate rather than a literal keeps it consistent with the other callers
+    // (the same broker-only-when-headless rationale the secrets readers use). Using
+    // the shared predicate rather than a literal keeps it consistent with the other callers
     // and lets any interactive caller of loadR2Config still prompt.
     const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'sessions-sync', agentOnly: isHeadlessSecretsContext() });
     const accountId = env.R2_ACCOUNT_ID?.trim();

package/dist/lib/session/types.d.ts

@@ -119,6 +119,8 @@ export interface SessionMeta {
     costUsd?: number;
     /** Wall-clock duration in ms (lastTs − firstTs), persisted at scan time. */
     durationMs?: number;
+    /** Underlying LLM model observed in the transcript, when the agent records one. */
+    model?: string;
     version?: string;
     account?: string;
     topic?: string;
@@ -190,6 +192,20 @@ export interface SessionMeta {
      * undefined for sessions obtained outside that path.
      */
     machine?: string;
+    /**
+     * Resolved actor id (`resolveActor().id`) who initiated this session — a
+     * tailnet login/email for a resolved human, or `UNRESOLVED@<host>`. Persisted
+     * write-once at session creation and preserved across content rescans (kept
+     * out of the DB upsert's ON CONFLICT set). Undefined for rows created before
+     * actor stamping. RUSH-2018.
+     */
+    actor?: string;
+    /**
+     * The actor's kind (`resolveActor().kind`): `'human'` for a person-initiated
+     * run, `'agent'` for one an agent spawned. Pairs with {@link actor}, same
+     * split as `AGENTS_ACTOR` / `AGENTS_ACTOR_KIND` on the exec env. RUSH-2018.
+     */
+    initiatedBy?: 'human' | 'agent';
     /**
      * True only for rows pulled from another machine over the live cross-machine
      * fan-out (`remote-list.ts`) — their transcript is on that peer's disk, so

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

@@ -0,0 +1,86 @@
+/**
+ * Device affinity for `--device auto` / `--host auto`.
+ *
+ * Picks a host from 14d session usage (launches by machine), weighted sample
+ * among online devices. Most-used has highest probability — not a hard lock.
+ * Account selection is separate (`--strategy balanced` / rotate.ts).
+ */
+import { type AffinityRow } from './session/db.js';
+/** Peakiness of usage weights; >1 amplifies the most-used option. */
+export declare const DEFAULT_AFFINITY_ALPHA = 1.3;
+export interface WeightedCandidate {
+    key: string;
+    launches: number;
+    weight: number;
+}
+/**
+ * Convert affinity rows into positive weights: launches^α (floor 1 for any
+ * row with launches > 0 so a single-use host still participates).
+ */
+export declare function affinityWeights(rows: AffinityRow[], alpha?: number): WeightedCandidate[];
+/**
+ * Weighted random sample. Returns null when candidates is empty.
+ * Pure — inject `rng` for tests.
+ */
+export declare function sampleWeighted(candidates: WeightedCandidate[], rng?: () => number): string | null;
+/** Online device names from the local registry (+ always include local). */
+export declare function listOnlineDeviceNames(localName?: string): string[];
+export interface DeviceAffinityOptions {
+    sinceDays?: number;
+    alpha?: number;
+    /**
+     * Eligible hosts (normalized). Defaults to online devices + local.
+     * Empty after filter → fall back to local.
+     */
+    eligibleHosts?: string[];
+    localMachine?: string;
+    /** Injected affinity (tests). When omitted, reads sessions.db. */
+    deviceAffinity?: AffinityRow[];
+    rng?: () => number;
+    project?: string;
+}
+export interface DeviceAffinityPlan {
+    /** null means run locally (do not pass --host). */
+    host: string | null;
+    deviceCandidates: WeightedCandidate[];
+    pickedDeviceKey: string | null;
+}
+/**
+ * Resolve host for `--device auto`. Does NOT pick harness or accounts.
+ */
+export declare function resolveDeviceAffinity(opts?: DeviceAffinityOptions): DeviceAffinityPlan;
+/** True when a host flag value means affinity pick. */
+export declare function isDeviceAuto(value: string | undefined | null): boolean;
+export type DeviceAutoHostOptions = {
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+    /** @deprecated Hidden alias for `--device auto`. */
+    smart?: boolean;
+    balanced?: boolean;
+    strategy?: string;
+};
+export type DeviceAutoApplyResult = {
+    /** True when affinity ran (success or degrade-to-local). */
+    attempted: boolean;
+    /** True when deprecated `--smart` was seen. */
+    deprecationSmart: boolean;
+    /** Affinity threw: host slots cleared → local; message for stderr. */
+    skipped?: string;
+    /** Present when affinity resolved without error. */
+    banner?: {
+        hostLabel: string;
+        deviceHint: string;
+        acctNote: string;
+    };
+};
+/**
+ * Apply `--device auto` / `--host auto` (and deprecated `--smart`) onto run options.
+ * Mutates `options` in place. On affinity failure, clears auto slots (local) and
+ * returns `skipped` — never throws; callers must not hard-exit.
+ */
+export declare function applyDeviceAutoToOptions(options: DeviceAutoHostOptions, deps?: {
+    resolve?: () => DeviceAffinityPlan;
+    accountPickerRequested?: boolean;
+}): DeviceAutoApplyResult;

package/dist/lib/smart-launch.js

@@ -0,0 +1,172 @@
+/**
+ * Device affinity for `--device auto` / `--host auto`.
+ *
+ * Picks a host from 14d session usage (launches by machine), weighted sample
+ * among online devices. Most-used has highest probability — not a hard lock.
+ * Account selection is separate (`--strategy balanced` / rotate.ts).
+ */
+import { queryAffinityRollup } from './session/db.js';
+import { localMachineId } from './session/origin-machine.js';
+import { loadDevicesSync } from './devices/registry.js';
+import { normalizeHost } from './machine-id.js';
+/** Peakiness of usage weights; >1 amplifies the most-used option. */
+export const DEFAULT_AFFINITY_ALPHA = 1.3;
+/**
+ * Convert affinity rows into positive weights: launches^α (floor 1 for any
+ * row with launches > 0 so a single-use host still participates).
+ */
+export function affinityWeights(rows, alpha = DEFAULT_AFFINITY_ALPHA) {
+    return rows
+        .filter((r) => r.launches > 0 && r.key && r.key !== '(unknown)')
+        .map((r) => ({
+        key: r.key,
+        launches: r.launches,
+        weight: Math.max(1, Math.pow(r.launches, alpha)),
+    }));
+}
+/**
+ * Weighted random sample. Returns null when candidates is empty.
+ * Pure — inject `rng` for tests.
+ */
+export function sampleWeighted(candidates, rng = Math.random) {
+    if (candidates.length === 0)
+        return null;
+    const total = candidates.reduce((s, c) => s + c.weight, 0);
+    if (total <= 0)
+        return candidates[0].key;
+    let roll = rng() * total;
+    for (const c of candidates) {
+        roll -= c.weight;
+        if (roll <= 0)
+            return c.key;
+    }
+    return candidates[candidates.length - 1].key;
+}
+/** Online device names from the local registry (+ always include local). */
+export function listOnlineDeviceNames(localName = localMachineId()) {
+    const names = new Set([normalizeHost(localName)]);
+    try {
+        const reg = loadDevicesSync();
+        for (const [name, d] of Object.entries(reg)) {
+            if (!d || typeof d !== 'object')
+                continue;
+            const online = d.tailscale?.online;
+            // No tailscale snapshot → treat as candidate (registry-only box).
+            if (online === false)
+                continue;
+            names.add(normalizeHost(name));
+        }
+    }
+    catch {
+        /* registry missing — local only */
+    }
+    return [...names];
+}
+/**
+ * Resolve host for `--device auto`. Does NOT pick harness or accounts.
+ */
+export function resolveDeviceAffinity(opts = {}) {
+    const local = normalizeHost(opts.localMachine ?? localMachineId());
+    const alpha = opts.alpha ?? DEFAULT_AFFINITY_ALPHA;
+    const rng = opts.rng ?? Math.random;
+    const sinceDays = opts.sinceDays ?? 14;
+    const sinceMs = Date.now() - sinceDays * 24 * 60 * 60 * 1000;
+    const eligible = new Set((opts.eligibleHosts ?? listOnlineDeviceNames(local)).map(normalizeHost));
+    if (eligible.size === 0)
+        eligible.add(local);
+    const deviceRows = opts.deviceAffinity ??
+        queryAffinityRollup({
+            groupBy: 'machine',
+            sinceMs,
+            excludeTeamOrigin: true,
+            onlyCli: true,
+            project: opts.project,
+        });
+    // Hosts with history get launches^α; online hosts with no history explore at weight 1.
+    const launchesByHost = new Map();
+    for (const r of deviceRows) {
+        const k = normalizeHost(r.key);
+        if (!eligible.has(k) || k === '(unknown)')
+            continue;
+        launchesByHost.set(k, (launchesByHost.get(k) ?? 0) + r.launches);
+    }
+    let deviceWeights = [...eligible].map((key) => {
+        const launches = launchesByHost.get(key) ?? 0;
+        return {
+            key,
+            launches,
+            weight: launches > 0 ? Math.max(1, Math.pow(launches, alpha)) : 1,
+        };
+    });
+    if (deviceWeights.length === 0) {
+        deviceWeights = [{ key: local, launches: 1, weight: 1 }];
+    }
+    const pickedDeviceKey = sampleWeighted(deviceWeights, rng);
+    const hostNorm = pickedDeviceKey ? normalizeHost(pickedDeviceKey) : local;
+    const host = hostNorm === local ? null : hostNorm;
+    return {
+        host,
+        deviceCandidates: deviceWeights,
+        pickedDeviceKey,
+    };
+}
+/** True when a host flag value means affinity pick. */
+export function isDeviceAuto(value) {
+    return typeof value === 'string' && value.trim().toLowerCase() === 'auto';
+}
+const HOST_SLOTS = ['host', 'device', 'on', 'computer'];
+/**
+ * Apply `--device auto` / `--host auto` (and deprecated `--smart`) onto run options.
+ * Mutates `options` in place. On affinity failure, clears auto slots (local) and
+ * returns `skipped` — never throws; callers must not hard-exit.
+ */
+export 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 };
+    }
+    try {
+        const plan = (deps.resolve ?? (() => resolveDeviceAffinity({})))();
+        const concrete = plan.host; // null = local
+        for (const k of HOST_SLOTS) {
+            if (isDeviceAuto(options[k])) {
+                options[k] = concrete ?? undefined;
+            }
+        }
+        const accountPickerRequested = deps.accountPickerRequested ?? false;
+        if (!accountPickerRequested && !options.strategy && !options.balanced) {
+            options.balanced = true;
+        }
+        const hostLabel = concrete ?? 'local';
+        const deviceHint = plan.deviceCandidates
+            .slice(0, 4)
+            .map((c) => `${c.key}:${c.launches}`)
+            .join(', ');
+        const acctNote = accountPickerRequested ? 'accounts=picker' : 'accounts=balanced';
+        return {
+            attempted: true,
+            deprecationSmart,
+            banner: { hostLabel, deviceHint, acctNote },
+        };
+    }
+    catch (err) {
+        // Graceful degrade: clear auto slots so the run continues locally.
+        for (const k of HOST_SLOTS) {
+            if (isDeviceAuto(options[k])) {
+                options[k] = undefined;
+            }
+        }
+        return {
+            attempted: true,
+            deprecationSmart,
+            skipped: err.message,
+        };
+    }
+}