@phnx-labs/agents-cli 1.20.76 → 1.20.78

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

@@ -37,6 +37,13 @@ export interface SessionProvenance {
     mux?: MuxLocation;
     /** Whether an existing rail can type back into this session (see module doc). */
     reply: ReplyRail;
+    /** The initiating device, resolved at query time from ssh.clientIp against the
+     * device registry (ssh transport only). Answers "who launched this and from
+     * where" without scraping ps/who/tailscale. */
+    origin?: {
+        device: string;
+        user?: string;
+    };
 }
 /** Env vars that carry provenance. Kept small so the macOS `ps` scan stays cheap. */
 export declare const PROVENANCE_ENV_KEYS: readonly ["SSH_CONNECTION", "SSH_TTY", "TMUX", "TMUX_PANE", "TERM_PROGRAM", "STY", "ITERM_SESSION_ID"];

package/dist/lib/session/render.js

@@ -13,6 +13,7 @@ import { cleanSessionPrompt, extractSessionTopic } from './prompt.js';
 import { renderMarkdown } from '../markdown.js';
 import { redactSecrets } from '../redact.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from './digest.js';
+import { extractTodoProgressFromEvents } from './state.js';
 // ── Path helpers ──────────────────────────────────────────────────────────────
 /**
  * Return absPath relative to cwd; fall back to ~/… then absolute.
@@ -528,7 +529,7 @@ export function renderSummary(events, cwd) {
     // Commands with timestamps
     const cmdList = [];
     // Plan items
-    const todoItems = [];
+    const todoItems = extractTodoProgressFromEvents(events)?.items.map(item => item.content) ?? [];
     let exitPlanContent = null;
     let planFilePath = null;
     // Subagent spawns
@@ -569,19 +570,6 @@ export function renderSummary(events, cwd) {
                     recentActivity.push({ kind: 'cmd', label: cmd, ts });
                 }
             }
-            // Plan items: TodoWrite items + TaskCreate descriptions (project's task tracker)
-            if (tool === 'TodoWrite' && Array.isArray(args.todos)) {
-                for (const item of args.todos) {
-                    const text = item.content || item.text || String(item);
-                    if (text && !todoItems.includes(text))
-                        todoItems.push(text);
-                }
-            }
-            if (tool === 'TaskCreate' && (args.description || args.prompt)) {
-                const text = String(args.description || args.prompt || '').slice(0, 140);
-                if (text && !todoItems.includes(text))
-                    todoItems.push(text);
-            }
             if (tool === 'ExitPlanMode') {
                 exitPlanContent = args.result || args.plan || args.content || null;
             }
@@ -796,6 +784,9 @@ export function parseRoleList(raw, flag) {
     return parts;
 }
 function roleOfEvent(e) {
+    // Synthetic scaffolding still maps to 'user' here so `--exclude user` drops it
+    // like any other user-role event (pre-flag behavior). `--include user`'s
+    // "genuine intent only" carve-out lives in applyRoleFilter, not here.
     if (e.type === 'message' && e.role === 'user')
         return 'user';
     if (e.type === 'message' && e.role === 'assistant')
@@ -817,7 +808,14 @@ function applyRoleFilter(events, opts) {
         const set = new Set(opts.include);
         return events.filter(e => {
             const role = roleOfEvent(e);
-            return role !== null && set.has(role);
+            if (role === null)
+                return false;
+            // `--include user` means genuine user intent, so drop harness-injected
+            // `_synthetic` scaffolding (bash-input, system-reminder) even though it
+            // carries role=user. `--exclude user` still drops it via roleOfEvent.
+            if (role === 'user' && e._synthetic)
+                return false;
+            return set.has(role);
         });
     }
     if (opts.exclude && opts.exclude.length > 0) {
@@ -845,7 +843,11 @@ function applyTurnSlice(events, opts) {
     if (!Number.isFinite(n) || n <= 0) {
         throw new Error(`Turn count must be a positive integer, got ${n}`);
     }
-    const isTurnStart = (e) => e.type === 'message' && e.role === 'user';
+    // A turn starts at a GENUINE user message — harness-injected `_synthetic`
+    // scaffolding (`<bash-input>`/`<bash-stdout>`, etc.) does not start a turn,
+    // so `--first N` / `--last N` count real asks, not the jump command that
+    // opened the session and its shell output.
+    const isTurnStart = (e) => e.type === 'message' && e.role === 'user' && !e._synthetic;
     const turnStartIdx = [];
     for (let i = 0; i < events.length; i++)
         if (isTurnStart(events[i]))

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

@@ -126,6 +126,11 @@ export interface StateContext {
  * list, so a session with no plan carries no `todos` field.
  */
 export declare function extractTodoProgress(args?: Record<string, any>): TodoProgress | undefined;
+/** Fold snapshot checklist tools and Claude TaskCreate/TaskUpdate event logs. */
+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

@@ -14,6 +14,7 @@
  * markers. Codex has no such tools, so it falls back to last-role + question
  * shape + mtime — same function, driven off the normalized events.
  */
+import * as path from 'path';
 import { summarizeToolUse } from './parse.js';
 /**
  * Detect per-session rate-limit / usage-limit signals in assistant or error
@@ -47,9 +48,9 @@ const PROSE_QUESTION_FRESH_MS = 30 * 60_000;
 /** Claude tool names that structurally mean "the agent handed control back to you". */
 const PLAN_TOOL = 'ExitPlanMode';
 const ASK_TOOL = 'AskUserQuestion';
-/** The live plan/checklist tools: Claude's `TodoWrite` and Codex's `update_plan`. */
-const TODO_TOOL = 'TodoWrite';
-const CODEX_PLAN_TOOL = 'update_plan';
+const SNAPSHOT_TODO_TOOLS = new Set(['TodoWrite', 'todo_write', 'update_plan']);
+const TASK_CREATE_TOOL = 'TaskCreate';
+const TASK_UPDATE_TOOL = 'TaskUpdate';
 /**
  * Derive live plan progress from a checklist tool call's args. Accepts both
  * Claude's `TodoWrite` (`todos: [{content,status,activeForm}]`) and Codex's
@@ -58,10 +59,11 @@ const CODEX_PLAN_TOOL = 'update_plan';
  * list, so a session with no plan carries no `todos` field.
  */
 export function extractTodoProgress(args) {
-    const raw = Array.isArray(args?.todos)
-        ? args.todos
-        : Array.isArray(args?.plan)
-            ? args.plan
+    const input = args?.input && typeof args.input === 'object' ? args.input : args;
+    const raw = Array.isArray(input?.todos)
+        ? input.todos
+        : Array.isArray(input?.plan)
+            ? input.plan
             : undefined;
     if (!Array.isArray(raw) || raw.length === 0)
         return undefined;
@@ -78,7 +80,8 @@ export function extractTodoProgress(args) {
         if (!content)
             continue;
         const status = t?.status === 'completed' || t?.status === 'in_progress' ? t.status : 'pending';
-        items.push(activeForm ? { content, status, activeForm } : { content, status });
+        const description = typeof t?.description === 'string' && t.description ? t.description : undefined;
+        items.push({ content, status, ...(description ? { description } : {}), ...(activeForm ? { activeForm } : {}) });
     }
     if (items.length === 0)
         return undefined;
@@ -91,6 +94,86 @@ export function extractTodoProgress(args) {
         activeForm: inProgress ? inProgress.activeForm ?? inProgress.content : undefined,
     };
 }
+/** Fold snapshot checklist tools and Claude TaskCreate/TaskUpdate event logs. */
+export function extractTodoProgressFromEvents(events) {
+    let items = [];
+    let nextTaskId = 1;
+    let sawChecklist = false;
+    for (const event of events) {
+        if (event.type !== 'tool_use')
+            continue;
+        const args = event.args ?? {};
+        if (SNAPSHOT_TODO_TOOLS.has(event.tool ?? '')) {
+            const input = args.input && typeof args.input === 'object' ? args.input : args;
+            const raw = Array.isArray(input.todos) ? input.todos : Array.isArray(input.plan) ? input.plan : undefined;
+            if (raw) {
+                items = raw.map((item) => ({ ...item }));
+                sawChecklist = true;
+            }
+            continue;
+        }
+        if (event.tool === TASK_CREATE_TOOL) {
+            const content = args.subject || args.description;
+            if (typeof content !== 'string' || !content.trim())
+                continue;
+            items.push({
+                taskId: String(nextTaskId++),
+                content: content.trim(),
+                description: typeof args.description === 'string' ? args.description : undefined,
+                activeForm: typeof args.activeForm === 'string' ? args.activeForm : undefined,
+                status: 'pending',
+            });
+            sawChecklist = true;
+            continue;
+        }
+        if (event.tool === TASK_UPDATE_TOOL) {
+            const taskId = String(args.taskId ?? args.task_id ?? '');
+            const index = items.findIndex(item => String(item.taskId ?? '') === taskId);
+            if (index < 0)
+                continue;
+            if (args.status === 'deleted') {
+                items.splice(index, 1);
+                continue;
+            }
+            const prior = items[index];
+            items[index] = {
+                ...prior,
+                ...(typeof args.subject === 'string' ? { content: args.subject } : {}),
+                ...(typeof args.description === 'string' ? { description: args.description } : {}),
+                ...(typeof args.activeForm === 'string' ? { activeForm: args.activeForm } : {}),
+                ...(typeof args.status === 'string' ? { status: args.status } : {}),
+            };
+        }
+    }
+    return sawChecklist ? extractTodoProgress({ todos: items }) : undefined;
+}
+/** Derive a recency-ordered, de-duplicated list of directories touched by tools. */
+export function extractRecentDirectoriesTouched(events, cwd) {
+    const dirs = [];
+    const add = (value, file = false) => {
+        if (typeof value !== 'string' || !value.trim())
+            return;
+        const resolved = path.isAbsolute(value) ? value : path.resolve(cwd || process.cwd(), value);
+        const dir = file ? path.dirname(resolved) : resolved;
+        const old = dirs.indexOf(dir);
+        if (old >= 0)
+            dirs.splice(old, 1);
+        dirs.push(dir);
+    };
+    for (const event of events) {
+        if (event.type !== 'tool_use')
+            continue;
+        const tool = event.tool ?? '';
+        const args = event.args ?? {};
+        if (['Edit', 'Write', 'edit_file', 'write_file', 'create_file', 'edit', 'write'].includes(tool)) {
+            add(args.file_path ?? args.filePath ?? args.path ?? event.path, true);
+        }
+        else if (['Bash', 'exec_command', 'run_shell_command', 'shell', 'Execute'].includes(tool)) {
+            add(args.cwd ?? args.Cwd ?? args.workdir ?? args.working_directory ?? cwd);
+        }
+    }
+    return dirs.length ? dirs.slice(-10) : undefined;
+}
 /** Trailing '?' or a leading interrogative — a question aimed at the user. */
 const QUESTION_TRAILING = /\?["'”)\]]?\s*$/;
 const QUESTION_PHRASE = /\b(shall i|should i|do you want|would you like|which (?:one|option|approach|of)|can you (?:confirm|clarify)|please (?:confirm|clarify|advise)|let me know|are you (?:ok|okay|sure)|proceed\?)\b/i;
@@ -105,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. */
@@ -325,11 +408,10 @@ export function inferActivity(events, ctx = {}) {
         .slice(-3)
         .map(e => oneLine(e.content ?? ''))
         .filter(Boolean);
-    // Live plan progress: the most recent TodoWrite's checklist (RUSH-1380). Attached
+    // Live plan progress: snapshot checklist tools or the folded Task* event log. Attached
     // to `base` so every return path below carries it — a working, waiting, or idle
     // session all keep showing how far the plan got.
-    const lastTodo = lastOf(meaningful, e => e.type === 'tool_use' && (e.tool === TODO_TOOL || e.tool === CODEX_PLAN_TOOL));
-    const todos = lastTodo ? extractTodoProgress(lastTodo.args) : undefined;
+    const todos = extractTodoProgressFromEvents(meaningful);
     const base = {
         activity: 'idle',
         lastRole: lastMsg?.role,

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

@@ -10,6 +10,12 @@
 export type SessionAgentId = 'claude' | 'codex' | 'gemini' | 'antigravity' | 'opencode' | 'openclaw' | 'rush' | 'hermes' | 'grok' | 'kimi' | 'droid';
 /** All agents with session discovery support, in display order. */
 export declare const SESSION_AGENTS: SessionAgentId[];
+/**
+ * True when `agent` stores session data `agents sessions` can discover (a member
+ * of {@link SESSION_AGENTS}). The single predicate every session-index writer
+ * gates on, so "is this a trackable agent?" is decided in exactly one place.
+ */
+export declare function isSessionTrackedAgent(agent: string): agent is SessionAgentId;
 /** A single normalized event within a session (message, tool call, thinking, etc.). */
 export interface SessionEvent {
     type: 'message' | 'tool_use' | 'tool_result' | 'thinking' | 'error' | 'init' | 'result' | 'usage' | 'attachment';
@@ -25,6 +31,16 @@ export interface SessionEvent {
     output?: string;
     /** Internal: marks tool_use events from local commands */
     _local?: boolean;
+    /**
+     * Internal: marks a `role=user` message that is harness-injected scaffolding
+     * (Claude `<bash-input>`/`<bash-stdout>` from `!`-prefix runs, `<system-reminder>`,
+     * `<task-notification>`, `<command-*>` wrappers, `[Request interrupted]`, skill
+     * bodies, hook feedback) rather than a genuine user turn. Set centrally in
+     * `parseSession` via `isSyntheticUserMessage`. Such events are excluded from
+     * `--include user` and are not counted as turn starts by `--first`/`--last`,
+     * but stay in the default full stream so `--markdown` keeps full fidelity.
+     */
+    _synthetic?: boolean;
     model?: string;
     inputTokens?: number;
     outputTokens?: number;
@@ -41,10 +57,12 @@ export interface SessionAttachment {
     mediaType: string;
     sizeBytes?: number;
 }
-/** One checklist item, as Claude's `TodoWrite` (`content`) or Codex's `update_plan` (`step`) emits it. */
+/** One normalized checklist/task item emitted by any transcript harness. */
 export interface TodoItem {
     content: string;
     status: 'pending' | 'in_progress' | 'completed';
+    /** Optional longer explanation supplied by task-based harnesses. */
+    description?: string;
     /** Present-continuous label shown while this item is the active step. */
     activeForm?: string;
 }
@@ -152,6 +170,12 @@ export interface SessionMeta {
      * instead of re-parsing the transcript. Absent when the session wrote no list.
      */
     todos?: TodoProgress;
+    /** Most-recent unique directories changed or used as a shell working directory. */
+    recentDirectoriesTouched?: string[];
+    /** Linear project containing ticketId, resolved lazily and cached in SQLite. */
+    linearProject?: string;
+    /** Browser URL for linearProject. */
+    linearProjectUrl?: string;
     /**
      * True when the session was spawned programmatically (SDK entrypoint) rather
      * than by a human at the Claude CLI. Captured at scan time from the JSONL

package/dist/lib/session/types.js

@@ -8,3 +8,11 @@
  */
 /** All agents with session discovery support, in display order. */
 export const SESSION_AGENTS = ['claude', 'codex', 'gemini', 'antigravity', 'opencode', 'openclaw', 'rush', 'hermes', 'grok', 'kimi', 'droid'];
+/**
+ * True when `agent` stores session data `agents sessions` can discover (a member
+ * of {@link SESSION_AGENTS}). The single predicate every session-index writer
+ * gates on, so "is this a trackable agent?" is decided in exactly one place.
+ */
+export function isSessionTrackedAgent(agent) {
+    return SESSION_AGENTS.includes(agent);
+}

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,
+        };
+    }
+}

package/dist/lib/state.d.ts

@@ -121,9 +121,13 @@ export declare function getSystemRoutinesDir(): string;
  * Path to a project-scoped routines directory (`<project>/.agents/routines/`),
  * or null when no project `.agents/` is found by walking up from cwd.
  *
- * Project routines participate in `list`/`view`/`run` for inspection but are
- * NOT fired by the daemon (which runs from $HOME and loads only user + system
- * routines). Opt-in firing for project routines is tracked as a follow-up.
+ * Project routines participate in `list`/`view` for inspection always. Daemon
+ * firing requires an explicit opt-in via `agents routines enable-project`
+ * (writes `meta.routines.projects`); after opt-in, `agents routines sync`
+ * materialises them into the user layer with `source:` provenance so the
+ * daemon (which loads user + system only) can fire them safely. A project's
+ * own `agents.yaml` `routines.enable: true` is a documentation signal only —
+ * it does not auto-enable firing. See `lib/routines-project.ts`.
  */
 export declare function getProjectRoutinesDir(cwd?: string): string | null;
 /** Path to routine execution logs (~/.agents/.history/runs/). */

package/dist/lib/state.js

@@ -319,9 +319,13 @@ export function getSystemRoutinesDir() { return SYSTEM_ROUTINES_DIR; }
  * Path to a project-scoped routines directory (`<project>/.agents/routines/`),
  * or null when no project `.agents/` is found by walking up from cwd.
  *
- * Project routines participate in `list`/`view`/`run` for inspection but are
- * NOT fired by the daemon (which runs from $HOME and loads only user + system
- * routines). Opt-in firing for project routines is tracked as a follow-up.
+ * Project routines participate in `list`/`view` for inspection always. Daemon
+ * firing requires an explicit opt-in via `agents routines enable-project`
+ * (writes `meta.routines.projects`); after opt-in, `agents routines sync`
+ * materialises them into the user layer with `source:` provenance so the
+ * daemon (which loads user + system only) can fire them safely. A project's
+ * own `agents.yaml` `routines.enable: true` is a documentation signal only —
+ * it does not auto-enable firing. See `lib/routines-project.ts`.
  */
 export function getProjectRoutinesDir(cwd = process.cwd()) {
     const projectAgentsDir = getProjectAgentsDir(cwd);
@@ -383,10 +387,21 @@ export function getTeamsDir() { return TEAMS_DIR; }
 export function getTeamsAgentsDir() { return TEAMS_AGENTS_DIR; }
 /** Path to the team registry — list of named teams with timestamps. Durable runtime, per-machine. */
 export function getTeamsRegistryPath() { return path.join(HISTORY_DIR, 'teams', 'registry.json'); }
+/**
+ * The devices dir (registry + ignore-list live here). Read at CALL time so a
+ * test can redirect it to a temp dir via AGENTS_DEVICES_DIR without racing the
+ * module-load capture of HISTORY_DIR — mirrors the AGENTS_EVENTS_PATH /
+ * AGENTS_SECRETS_AGENT_DIR test-isolation escape hatches. Never set in
+ * production code; it exists so the vitest fork's device-registry writes can
+ * never reach the user's real ~/.agents/.history/devices (RUSH-2042).
+ */
+function getDevicesDir() {
+    return process.env.AGENTS_DEVICES_DIR ?? path.join(HISTORY_DIR, 'devices');
+}
 /** Path to the device registry — SSH device profiles with platform/auth metadata. Durable runtime, per-machine (host list + addresses are NOT pulled by `agents repo push`). */
-export function getDevicesRegistryPath() { return path.join(HISTORY_DIR, 'devices', 'registry.json'); }
+export function getDevicesRegistryPath() { return path.join(getDevicesDir(), 'registry.json'); }
 /** Path to the device ignore-list — tailscale node names the user dismissed, so auto-discovery never re-suggests them. Per-machine, same dir as the registry. */
-export function getDevicesIgnoredPath() { return path.join(HISTORY_DIR, 'devices', 'ignored.json'); }
+export function getDevicesIgnoredPath() { return path.join(getDevicesDir(), 'ignored.json'); }
 /** Dir of "pending device" sentinels (~/.agents/.cache/state/devices-pending/) — one empty-ish file per newly-discovered, not-yet-approved tailnet node. Written by the daemon probe, read by the menu-bar helper (mirrors the attention sentinel dir). */
 export function getDevicesPendingDir() { return path.join(RUNTIME_STATE_DIR, 'devices-pending'); }
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */