@phnx-labs/agents-cli 1.22.75 → 1.22.76

package/dist/lib/summarizer/config.js

@@ -0,0 +1,83 @@
+/**
+ * Session-summarizer configuration (PHNX-3939).
+ *
+ * Resolves the three knobs behind the daemon summarizer — enabled / base URL /
+ * model — from `agents config` (`summarizer.*`, user-scope in the central
+ * agents.yaml) with a per-process env override
+ * (`AGENTS_SUMMARIZER_ENABLED` / `AGENTS_SUMMARIZER_BASEURL` /
+ * `AGENTS_SUMMARIZER_MODEL`). Off by default: with no config and no env, the
+ * summarizer is disabled and makes zero model calls.
+ *
+ * `isSummarizerReady()` is memoized on a short TTL because the display merge
+ * (the watch-stream projections) calls it once per session row — a fresh
+ * agents.yaml read per row would defeat the "blazing fast" requirement.
+ */
+import { getConfigValue } from '../device-config.js';
+/** Parse a boolean-ish env value; undefined when the var is unset. */
+function envBool(raw) {
+    if (raw === undefined)
+        return undefined;
+    const v = raw.trim().toLowerCase();
+    if (v === '1' || v === 'true' || v === 'on' || v === 'yes')
+        return true;
+    if (v === '0' || v === 'false' || v === 'off' || v === 'no' || v === '')
+        return false;
+    return undefined;
+}
+function envString(raw) {
+    const v = raw?.trim();
+    return v ? v : undefined;
+}
+/**
+ * Resolve the full summarizer config. Env overrides the stored config key by key;
+ * an unset env var falls through to `agents config`, then to the built-in
+ * default (disabled). Never throws — a missing/corrupt config reads as unset.
+ */
+export function resolveSummarizerConfig(env = process.env) {
+    let storedEnabled;
+    let storedBaseUrl;
+    let storedModel;
+    try {
+        storedEnabled = getConfigValue('summarizer.enabled').value;
+        storedBaseUrl = getConfigValue('summarizer.baseUrl').value;
+        storedModel = getConfigValue('summarizer.model').value;
+    }
+    catch {
+        // A missing/corrupt config store must not break the read path — treat as unset.
+    }
+    const enabled = envBool(env.AGENTS_SUMMARIZER_ENABLED) ?? storedEnabled ?? false;
+    const baseUrl = envString(env.AGENTS_SUMMARIZER_BASEURL) ?? envString(storedBaseUrl);
+    const model = envString(env.AGENTS_SUMMARIZER_MODEL) ?? envString(storedModel);
+    return { enabled, baseUrl, model };
+}
+/**
+ * True only when the summarizer is enabled AND has a base URL + model to call.
+ * A configuration that is `enabled` but missing an endpoint cannot produce a
+ * summary, so it is treated as unconfigured (the service no-ops, the merge marks
+ * `skipped`) rather than erroring on every tick.
+ */
+export function isSummarizerRunnable(config) {
+    return config.enabled && Boolean(config.baseUrl) && Boolean(config.model);
+}
+let cachedReady = null;
+const READY_TTL_MS = 3_000;
+/**
+ * Memoized "will a summary actually be produced?" check for the hot merge path.
+ * Reflects {@link isSummarizerRunnable} — enabled AND a base URL AND a model —
+ * NOT just `enabled`, because an enabled-but-unconfigured summarizer computes
+ * nothing, so a row with no cached summary must read `skipped`, not a `pending`
+ * that never resolves (the exact case: `summarizer.enabled on` set before the
+ * endpoint). TTL keeps a config change visible within a few seconds without a
+ * per-row agents.yaml read.
+ */
+export function isSummarizerReady(nowMs = Date.now()) {
+    if (cachedReady && nowMs - cachedReady.at < READY_TTL_MS)
+        return cachedReady.value;
+    const value = isSummarizerRunnable(resolveSummarizerConfig());
+    cachedReady = { at: nowMs, value };
+    return value;
+}
+/** Test seam: drop the memoized ready flag so the next read re-resolves. */
+export function resetSummarizerReadyCacheForTest() {
+    cachedReady = null;
+}

package/dist/lib/summarizer/pass.d.ts

@@ -0,0 +1,45 @@
+/**
+ * One session-summarizer pass (PHNX-3939) — the work the background
+ * SessionSummarizerService does per tick, factored out so it is testable with an
+ * injected model stub and no daemon scaffolding.
+ *
+ * Off the request path by construction: it reads THIS box's already-published
+ * live sessions (the warm cache the session-state service writes — never a fresh
+ * gather) and, per session, reuses the transcript-keyed `session_summaries` row
+ * until the transcript bytes change, so an unchanged session costs one indexed
+ * read and zero model calls. When the summarizer is disabled or has no endpoint,
+ * the pass does nothing at all.
+ */
+import type { ActiveSession } from '../session/active.js';
+import { type SummarizerConfig } from './config.js';
+import { summarize as defaultSummarize } from './summarize.js';
+/** Max sessions summarized per tick — a debounce ceiling on local-model calls. */
+export declare const SUMMARIZER_MAX_PER_TICK = 8;
+export interface SummarizerPassOptions {
+    now?: number;
+    config?: SummarizerConfig;
+    /** Live sessions to consider; default = this box's warm local-session cache. */
+    sessions?: ActiveSession[];
+    /** Injectable model call (tests stub the endpoint here). */
+    summarizeImpl?: typeof defaultSummarize;
+    signal?: AbortSignal;
+    maxPerTick?: number;
+    /** Injectable stat for tests; defaults to fs.statSync. */
+    statFile?: (p: string) => {
+        mtimeMs: number;
+        size: number;
+    };
+    /** Skip the reader-recency gate (tests pass sessions directly). */
+    requireReader?: boolean;
+}
+export interface SummarizerPassResult {
+    disabled: boolean;
+    computed: number;
+    reused: number;
+    skipped: number;
+}
+/**
+ * Run one pass. Returns per-outcome counts. Never throws — a per-session failure
+ * is isolated so one bad transcript can't stall the whole tick.
+ */
+export declare function runSummarizerPass(opts?: SummarizerPassOptions): Promise<SummarizerPassResult>;

package/dist/lib/summarizer/pass.js

@@ -0,0 +1,112 @@
+/**
+ * One session-summarizer pass (PHNX-3939) — the work the background
+ * SessionSummarizerService does per tick, factored out so it is testable with an
+ * injected model stub and no daemon scaffolding.
+ *
+ * Off the request path by construction: it reads THIS box's already-published
+ * live sessions (the warm cache the session-state service writes — never a fresh
+ * gather) and, per session, reuses the transcript-keyed `session_summaries` row
+ * until the transcript bytes change, so an unchanged session costs one indexed
+ * read and zero model calls. When the summarizer is disabled or has no endpoint,
+ * the pass does nothing at all.
+ */
+import * as fs from 'node:fs';
+import { readSessionSummary, readSessionSummaryAny, writeSessionSummary, } from '../session/db.js';
+import { isActiveSessionsJournalReaderRecent, readActiveSessionsCache, } from '../session/session-cache.js';
+import { resolveSummarizerConfig, isSummarizerRunnable } from './config.js';
+import { summarize as defaultSummarize } from './summarize.js';
+/** Max sessions summarized per tick — a debounce ceiling on local-model calls. */
+export const SUMMARIZER_MAX_PER_TICK = 8;
+/**
+ * Merge model checkpoint TEXTS with any prior stored checkpoints so a line that
+ * already existed keeps its original `at`, and only genuinely new lines get
+ * stamped `now`. Order follows the model output (newest last).
+ */
+function stampCheckpoints(texts, prior, nowIso) {
+    const priorAt = new Map((prior ?? []).map((c) => [c.text, c.at]));
+    return texts.map((text) => ({ text, at: priorAt.get(text) ?? nowIso }));
+}
+/**
+ * Run one pass. Returns per-outcome counts. Never throws — a per-session failure
+ * is isolated so one bad transcript can't stall the whole tick.
+ */
+export async function runSummarizerPass(opts = {}) {
+    const now = opts.now ?? Date.now();
+    const config = opts.config ?? resolveSummarizerConfig();
+    const result = { disabled: false, computed: 0, reused: 0, skipped: 0 };
+    if (!isSummarizerRunnable(config)) {
+        result.disabled = true;
+        return result;
+    }
+    let sessions = opts.sessions;
+    if (!sessions) {
+        // Reader-gated like the active-sessions warm tick: no watcher, no work.
+        if (opts.requireReader !== false && !isActiveSessionsJournalReaderRecent(now))
+            return result;
+        sessions = readActiveSessionsCache('local')?.sessions ?? [];
+    }
+    const stat = opts.statFile ?? ((p) => {
+        const s = fs.statSync(p);
+        return { mtimeMs: s.mtimeMs, size: s.size };
+    });
+    const runSummarize = opts.summarizeImpl ?? defaultSummarize;
+    const maxPerTick = opts.maxPerTick ?? SUMMARIZER_MAX_PER_TICK;
+    const nowIso = new Date(now).toISOString();
+    let budget = maxPerTick;
+    for (const s of sessions) {
+        if (opts.signal?.aborted)
+            break;
+        if (budget <= 0)
+            break;
+        const id = s.sessionId;
+        const file = s.sessionFile;
+        if (!id || !file)
+            continue;
+        let stamp;
+        try {
+            const st = stat(file);
+            stamp = { fileMtimeMs: Math.round(st.mtimeMs), fileSize: st.size };
+        }
+        catch {
+            continue; // transcript unreadable this tick — try again next time
+        }
+        // Cached for these exact bytes → never recompute (the core "blazing fast" rule).
+        if (readSessionSummary(id, stamp)) {
+            result.reused++;
+            continue;
+        }
+        budget--;
+        const prompt = (s.firstUserMessage ?? s.topic ?? '').trim();
+        const prior = readSessionSummaryAny(id);
+        if (!prompt) {
+            // No extractable intent yet — cache a skip against these bytes so we don't
+            // re-attempt every tick; a later transcript write (new bytes) retries.
+            writeSessionSummary({ id, ...stamp, summary: { summaryState: 'skipped' } });
+            result.skipped++;
+            continue;
+        }
+        let computed;
+        try {
+            computed = await runSummarize(prompt, { todos: s.todos, plan: s.plan, phase: s.phase }, { baseUrl: config.baseUrl, model: config.model, ...(opts.signal ? { signal: opts.signal } : {}) });
+        }
+        catch {
+            computed = undefined;
+        }
+        if (!computed) {
+            writeSessionSummary({ id, ...stamp, summary: { summaryState: 'skipped' } });
+            result.skipped++;
+            continue;
+        }
+        const entry = {
+            // Goal is computed ONCE at first sight — a prior goal is kept across
+            // progress deltas so it stays stable while checkpoints/checklist refresh.
+            goal: prior?.goal ?? computed.goal,
+            checkpoints: stampCheckpoints(computed.checkpoints, prior?.checkpoints, nowIso),
+            summaryChecklist: computed.checklist,
+            summaryState: 'ready',
+        };
+        writeSessionSummary({ id, ...stamp, summary: entry });
+        result.computed++;
+    }
+    return result;
+}

package/dist/lib/summarizer/summarize.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The one model call behind the session summarizer (PHNX-3939).
+ *
+ * A pure boundary: given the session's first user turn (the goal source) and its
+ * live progress (todos / plan / phase off the state engine), it asks a local
+ * Anthropic-wire endpoint (Ollama / vLLM / LiteLLM — the same configurable base
+ * URL `computer/model.ts` speaks) for a strict JSON `{goal, checkpoints, checklist}`
+ * and validates the shape. On ANY failure — network, non-2xx, non-JSON, wrong
+ * shape — it returns `undefined`, and the caller records `summaryState: 'skipped'`.
+ *
+ * NEVER called on the request path: only the background SessionSummarizerService
+ * invokes it, debounced and reader-gated.
+ */
+import type { TodoProgress } from '../session/types.js';
+/** Live progress fed to the model alongside the goal-bearing prompt. */
+export interface SummarizeProgress {
+    /** Latest checklist write (TodoWrite / update_plan), when the session has one. */
+    todos?: TodoProgress;
+    /** Plan markdown from the last ExitPlanMode, when present. */
+    plan?: string;
+    /** Coarse lifecycle phase (running / waiting / idle / …), when known. */
+    phase?: string;
+}
+/** The validated model output. `at` timestamps are stamped by the caller. */
+export interface SummarizeResult {
+    goal: string;
+    /** Progress checkpoints, newest last (short lines). */
+    checkpoints: string[];
+    /** Detailed checklist. */
+    checklist: {
+        text: string;
+        done: boolean;
+    }[];
+}
+export interface SummarizeOptions {
+    baseUrl: string;
+    model: string;
+    maxTokens?: number;
+    /**
+     * API key for the endpoint. Deliberately NOT resolved from `ANTHROPIC_API_KEY`:
+     * the summarizer targets an operator-configured local/remote endpoint
+     * (Ollama/vLLM/LiteLLM) that typically ignores the key, so forwarding the real
+     * Anthropic credential there would leak it. Only an explicit
+     * `AGENTS_SUMMARIZER_API_KEY` (or this option) is ever sent; otherwise the
+     * header is empty.
+     */
+    apiKey?: string;
+    /** Injectable for tests; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Abort the request when the daemon tick's deadline elapses. */
+    signal?: AbortSignal;
+}
+/** Compose the user message from the goal-bearing prompt and the live progress. */
+export declare function buildSummarizeUserMessage(prompt: string, progress: SummarizeProgress): string;
+/**
+ * Coerce an untrusted parsed object into a {@link SummarizeResult}, or undefined
+ * when the shape is wrong. Extra/missing optional arrays degrade to `[]` rather
+ * than failing, but a non-string goal is a hard reject — a summary with no goal
+ * is not a summary.
+ */
+export declare function validateSummarizeResult(parsed: unknown): SummarizeResult | undefined;
+/** Strip ``` fences and pull the first {...} block so a chatty model still parses. */
+export declare function extractJsonObject(text: string): string | undefined;
+/**
+ * Run one summarization. Returns the validated result, or `undefined` on any
+ * failure (the caller then marks the session `summaryState: 'skipped'`).
+ */
+export declare function summarize(prompt: string, progress: SummarizeProgress, opts: SummarizeOptions): Promise<SummarizeResult | undefined>;

package/dist/lib/summarizer/summarize.js

@@ -0,0 +1,120 @@
+/**
+ * The one model call behind the session summarizer (PHNX-3939).
+ *
+ * A pure boundary: given the session's first user turn (the goal source) and its
+ * live progress (todos / plan / phase off the state engine), it asks a local
+ * Anthropic-wire endpoint (Ollama / vLLM / LiteLLM — the same configurable base
+ * URL `computer/model.ts` speaks) for a strict JSON `{goal, checkpoints, checklist}`
+ * and validates the shape. On ANY failure — network, non-2xx, non-JSON, wrong
+ * shape — it returns `undefined`, and the caller records `summaryState: 'skipped'`.
+ *
+ * NEVER called on the request path: only the background SessionSummarizerService
+ * invokes it, debounced and reader-gated.
+ */
+import { ANTHROPIC_VERSION } from '../computer/model.js';
+const SYSTEM_PROMPT = [
+    'You summarize a coding-agent session for an operator dashboard.',
+    'Reply with ONLY a single JSON object, no prose and no code fences, of exactly this shape:',
+    '{"goal": string, "checkpoints": string[], "checklist": [{"text": string, "done": boolean}]}',
+    '- goal: 1-2 lines capturing what the user actually asked for, in plain language.',
+    '- checkpoints: short lines of concrete progress so far, newest last; [] if none yet.',
+    '- checklist: the detailed steps to finish the goal, each with a done flag; [] if unknown.',
+    'Do not invent progress that is not evidenced by the provided context.',
+].join('\n');
+/** Compose the user message from the goal-bearing prompt and the live progress. */
+export function buildSummarizeUserMessage(prompt, progress) {
+    const parts = [`USER REQUEST:\n${prompt.trim()}`];
+    if (progress.phase)
+        parts.push(`PHASE: ${progress.phase}`);
+    if (progress.todos && progress.todos.items.length > 0) {
+        const lines = progress.todos.items.map((t) => `- [${t.status === 'completed' ? 'x' : ' '}] ${t.content}`);
+        parts.push(`CURRENT CHECKLIST (${progress.todos.done}/${progress.todos.total} done):\n${lines.join('\n')}`);
+    }
+    if (progress.plan)
+        parts.push(`PLAN:\n${progress.plan.trim().slice(0, 4000)}`);
+    return parts.join('\n\n');
+}
+/**
+ * Coerce an untrusted parsed object into a {@link SummarizeResult}, or undefined
+ * when the shape is wrong. Extra/missing optional arrays degrade to `[]` rather
+ * than failing, but a non-string goal is a hard reject — a summary with no goal
+ * is not a summary.
+ */
+export function validateSummarizeResult(parsed) {
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return undefined;
+    const obj = parsed;
+    if (typeof obj.goal !== 'string' || obj.goal.trim().length === 0)
+        return undefined;
+    const checkpoints = Array.isArray(obj.checkpoints)
+        ? obj.checkpoints.filter((c) => typeof c === 'string' && c.trim().length > 0).map((c) => c.trim())
+        : [];
+    const checklist = Array.isArray(obj.checklist)
+        ? obj.checklist
+            .filter((c) => Boolean(c) && typeof c === 'object' && !Array.isArray(c))
+            .map((c) => ({ text: typeof c.text === 'string' ? c.text.trim() : '', done: Boolean(c.done) }))
+            .filter((c) => c.text.length > 0)
+        : [];
+    return { goal: obj.goal.trim(), checkpoints, checklist };
+}
+/** Extract the assistant text from an Anthropic Messages response body. */
+function textFromBody(body) {
+    const content = body.content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((b) => Boolean(b) && typeof b === 'object')
+        .filter((b) => b.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join('');
+}
+/** Strip ``` fences and pull the first {...} block so a chatty model still parses. */
+export function extractJsonObject(text) {
+    const unfenced = text.replace(/```(?:json)?/gi, '').trim();
+    const start = unfenced.indexOf('{');
+    const end = unfenced.lastIndexOf('}');
+    if (start === -1 || end === -1 || end < start)
+        return undefined;
+    return unfenced.slice(start, end + 1);
+}
+/**
+ * Run one summarization. Returns the validated result, or `undefined` on any
+ * failure (the caller then marks the session `summaryState: 'skipped'`).
+ */
+export async function summarize(prompt, progress, opts) {
+    if (!prompt.trim())
+        return undefined;
+    const baseUrl = opts.baseUrl.replace(/\/+$/, '');
+    const doFetch = opts.fetchImpl ?? fetch;
+    // Only an explicit summarizer key is ever forwarded — never the ambient
+    // ANTHROPIC_API_KEY, which would leak to the operator's local endpoint.
+    const apiKey = opts.apiKey ?? process.env.AGENTS_SUMMARIZER_API_KEY ?? '';
+    try {
+        const res = await doFetch(`${baseUrl}/v1/messages`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-api-key': apiKey,
+                'anthropic-version': ANTHROPIC_VERSION,
+            },
+            body: JSON.stringify({
+                model: opts.model,
+                max_tokens: opts.maxTokens ?? 512,
+                system: SYSTEM_PROMPT,
+                messages: [{ role: 'user', content: buildSummarizeUserMessage(prompt, progress) }],
+            }),
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        });
+        if (!res.ok)
+            return undefined;
+        const body = await res.json();
+        const text = textFromBody(body);
+        const json = extractJsonObject(text);
+        if (!json)
+            return undefined;
+        return validateSummarizeResult(JSON.parse(json));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/lib/teams/agents.d.ts

@@ -569,9 +569,10 @@ export declare class AgentManager {
     private resolveScheduledPlacement;
     /**
      * Place an UNPINNED, non-cloud teammate onto the team pool via the cascade
-     * (least-loaded), if the team declares one. A no-op for a pinned teammate
-     * (hostName already set from `--device`), a cloud teammate, or a poolless team —
-     * leaving hostName null so the local spawn runs unchanged. Shared by spawn()
+     * (least-loaded). A poolless team consumes the active worker allowlist and
+     * fails loud when none exists; it never silently lands on the orchestrator.
+     * A no-op only for a pinned teammate (hostName already set from `--device`) or
+     * a cloud teammate. Shared by spawn()
      * (immediate add-launch) and startReady() (staged launch) so an unpinned pool
      * teammate schedules identically no matter how it was fired.
      */

package/dist/lib/teams/agents.js

@@ -38,6 +38,7 @@ import { atomicWriteJsonSync } from '../fs-atomic.js';
 import { resolvePlacement, classifyExclusions, isTransientPlacementBlock, NoViableDeviceError, } from './scheduler.js';
 import { probePoolSignals } from './placement-probe.js';
 import { readMaxConcurrentCaps } from '../device-config.js';
+import { filterAutoPool, listWorkerDevices } from '../devices/pool.js';
 import { redactSecrets, sanitizeForTerminal } from '../redact.js';
 import chalk from 'chalk';
 let lastMemoryWarnAt = 0;
@@ -2328,9 +2329,10 @@ export class AgentManager {
     }
     /**
      * Place an UNPINNED, non-cloud teammate onto the team pool via the cascade
-     * (least-loaded), if the team declares one. A no-op for a pinned teammate
-     * (hostName already set from `--device`), a cloud teammate, or a poolless team —
-     * leaving hostName null so the local spawn runs unchanged. Shared by spawn()
+     * (least-loaded). A poolless team consumes the active worker allowlist and
+     * fails loud when none exists; it never silently lands on the orchestrator.
+     * A no-op only for a pinned teammate (hostName already set from `--device`) or
+     * a cloud teammate. Shared by spawn()
      * (immediate add-launch) and startReady() (staged launch) so an unpinned pool
      * teammate schedules identically no matter how it was fired.
      */
@@ -2341,7 +2343,12 @@ export class AgentManager {
         if (!teamMeta)
             return;
         const roster = await this.listByTask(taskName);
-        const pool = teamMeta.devices ?? [];
+        // A poolless team is still an automatic placement request: use the same
+        // explicit worker allowlist as `--device auto`. Never silently run it on a
+        // personal/desktop orchestrator merely because `devices` was omitted.
+        const pool = teamMeta.devices?.length
+            ? teamMeta.devices
+            : filterAutoPool(listWorkerDevices());
         const maxConcurrent = pool.length > 1 ? readMaxConcurrentCaps(pool) : undefined;
         // On the start path (opts.probe), gather live signals so the pick is health-,
         // harness-, and load-aware (RUSH-2002); the add path stays the cap-only
@@ -2353,6 +2360,7 @@ export class AgentManager {
         const placeOpts = {
             maxConcurrent,
             signals,
+            defaultDevices: pool,
             agentLabel: this.placementAgentLabel(agent),
         };
         if (signals) {

package/dist/lib/teams/scheduler.d.ts

@@ -45,6 +45,8 @@ export interface PlacementTeam {
  * is never second-guessed.
  */
 export interface PlacementOptions {
+    /** Worker pool used when the team does not declare an explicit device pool. */
+    defaultDevices?: string[];
     maxConcurrent?: Record<string, number>;
     /**
      * Live per-device signals (RUSH-2002). When present, the many-device pick
@@ -144,8 +146,8 @@ export declare function classifyExclusions(devices: string[], roster: RosterEntr
  */
 export declare function pickBestDevice(devices: string[], roster: RosterEntry[], opts?: PlacementOptions): string;
 /**
- * Resolve where a teammate runs. Returns `{ device: null }` for a local run
- * (no pin, no pool, or the chosen device is the local machine) and
+ * Resolve where a teammate runs. Returns `{ device: null }` only when the
+ * explicitly/default-selected device is the local machine, and
  * `{ device: <name> }` for a remote placement. See the cascade in the module
  * header. Throws {@link NoViableDeviceError} when a required pool has no viable
  * host — the caller surfaces it at `teams start` rather than falling back local.

package/dist/lib/teams/scheduler.js

@@ -9,7 +9,7 @@
  *   1. teammate has an explicit `--device` pin      → that device
  *   2. else the team pool has exactly one device     → that device (whole team)
  *   3. else the team pool has many devices           → best-viable pick
- *   4. else (no pin, no pool)                         → null == run local
+ *   4. else (no pin, no pool)                         → active worker pool
  *
  * Step 3 is cap-, health-, and harness-aware (RUSH-2002). When the caller
  * supplies live {@link DevicePlacementSignal}s (probed reachability, headroom,
@@ -294,8 +294,8 @@ export function pickBestDevice(devices, roster, opts) {
     })[0];
 }
 /**
- * Resolve where a teammate runs. Returns `{ device: null }` for a local run
- * (no pin, no pool, or the chosen device is the local machine) and
+ * Resolve where a teammate runs. Returns `{ device: null }` only when the
+ * explicitly/default-selected device is the local machine, and
  * `{ device: <name> }` for a remote placement. See the cascade in the module
  * header. Throws {@link NoViableDeviceError} when a required pool has no viable
  * host — the caller surfaces it at `teams start` rather than falling back local.
@@ -306,10 +306,10 @@ export function resolvePlacement(team, explicitDevice, roster, opts) {
     if (explicitDevice) {
         return { device: isLocalDevice(explicitDevice) ? null : explicitDevice };
     }
-    const pool = team.devices ?? [];
-    // 4. No pool → local, exactly like today.
+    const pool = team.devices?.length ? team.devices : (opts?.defaultDevices ?? []);
+    // An omitted pool means automatic worker placement, never implicit local.
     if (pool.length === 0)
-        return { device: null };
+        throw new NoViableDeviceError([], opts?.agentLabel);
     // 2. Pool of one → the whole team runs there. Respect the choice for
     //    load/cap/reachability, but still fail loud when the agent is provably
     //    NOT installed there — running it would be futile.

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

@@ -25,6 +25,8 @@ export declare const AGENTS_TMUX_HISTORY_LIMIT = 20000;
  * these defaults, silently. Same shape as AGENT_HOOK_SCHEMA below.
  */
 export declare const AGENTS_TMUX_CONFIG_SCHEMA = 1;
+/** Source one user config without tmux's quiet flag, preserving path bytes. */
+export declare function userConfigSourceLine(value: string): string;
 /** Provenance written alongside each live tmux session. */
 export interface SessionMeta {
     name: string;

package/dist/lib/tmux/session.js

@@ -55,6 +55,10 @@ let startupConfigSequence = 0;
 function tmuxConfigArgument(value) {
     return `"${value.replace(/([\\"$])/g, '\\$1')}"`;
 }
+/** Source one user config without tmux's quiet flag, preserving path bytes. */
+export function userConfigSourceLine(value) {
+    return `source-file ${tmuxConfigArgument(value)}`;
+}
 /**
  * tmux loads `-f` instead of its normal user config, so put agents-cli's
  * defaults first and explicitly source the first user config tmux would have
@@ -90,7 +94,9 @@ function writeStartupConfig(env) {
         'bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-selection-no-clear',
     ];
     for (const userConfig of userConfigs) {
-        lines.push(`source-file -q ${tmuxConfigArgument(userConfig)}`);
+        // Do not suppress parse/read failures: a broken user config must fail the
+        // launch visibly instead of producing a silently half-configured server.
+        lines.push(userConfigSourceLine(userConfig));
     }
     fs.writeFileSync(startupConfig, `${lines.join('\n')}\n`, { mode: 0o600 });
     return startupConfig;

package/dist/lib/types.d.ts

@@ -1204,6 +1204,26 @@ export interface BrowserProfileConfig {
     }>;
     /** Preset name to use when `--endpoint` is not passed to `start`. */
     defaultEndpoint?: string;
+    /**
+     * How `agents browser` obtains a live browser for this profile (PHNX-3967):
+     *   - `launch` (default when absent): agents-cli spawns the browser itself
+     *     under a managed `--user-data-dir` when nothing is serving CDP on the port.
+     *   - `attach-only`: agents-cli NEVER spawns a rival window. It attaches to a
+     *     browser the user (or a one-time command) already started with remote
+     *     debugging, and fails loud with a relaunch hint when none is there. This
+     *     is how "enforce one window" is expressed — Arc is inherently attach-only,
+     *     and a canonical signed-in Comet uses it so agents can't spawn a second,
+     *     logged-out instance. Pairs with a durable {@link userDataDir}.
+     */
+    launchPolicy?: 'attach-only' | 'launch';
+    /**
+     * Absolute durable `--user-data-dir` for this profile's browser (PHNX-3967).
+     * When absent, an attach-only profile resolves a default durable dir outside
+     * `~/.agents/.cache` (`getBrowserDurableDir()`), so a one-time sign-in survives
+     * quit+relaunch and `profiles remove`'s cache sweep. Also the value the
+     * ownership guard compares a running instance against to reject a port-squatter.
+     */
+    userDataDir?: string;
     chrome?: {
         headless?: boolean;
         args?: string[];

package/dist/lib/verbs.d.ts

@@ -0,0 +1,23 @@
+import type { Command } from 'commander';
+/**
+ * The ONE place that defines the CLI's standard short-form verb aliases.
+ *
+ * These are the canonical short forms an agent or user reaches for on a
+ * command group's CRUD verbs — `ls` for `list`, `rm` for `remove`, and so on.
+ * They are NOT cross-verb synonyms (`info`/`install`/`create`); those are
+ * per-command back-compat aliases owned by the individual commands.
+ *
+ * Apply them with {@link withAliases} so every group stays in lockstep instead
+ * of each command hand-rolling its own `.alias('rm')`.
+ */
+export declare const CANONICAL_ALIASES: {
+    readonly list: readonly ["ls"];
+    readonly view: readonly ["show"];
+    readonly add: readonly [];
+    readonly remove: readonly ["rm"];
+    readonly rename: readonly ["mv"];
+    readonly edit: readonly [];
+};
+export type CanonicalVerb = keyof typeof CANONICAL_ALIASES;
+/** Apply the standard aliases for `verb` to an already-created subcommand, returning it. */
+export declare function withAliases(cmd: Command, verb: CanonicalVerb): Command;

package/dist/lib/verbs.js

@@ -0,0 +1,24 @@
+/**
+ * The ONE place that defines the CLI's standard short-form verb aliases.
+ *
+ * These are the canonical short forms an agent or user reaches for on a
+ * command group's CRUD verbs — `ls` for `list`, `rm` for `remove`, and so on.
+ * They are NOT cross-verb synonyms (`info`/`install`/`create`); those are
+ * per-command back-compat aliases owned by the individual commands.
+ *
+ * Apply them with {@link withAliases} so every group stays in lockstep instead
+ * of each command hand-rolling its own `.alias('rm')`.
+ */
+export const CANONICAL_ALIASES = {
+    list: ['ls'],
+    view: ['show'],
+    add: [],
+    remove: ['rm'],
+    rename: ['mv'],
+    edit: [],
+};
+/** Apply the standard aliases for `verb` to an already-created subcommand, returning it. */
+export function withAliases(cmd, verb) {
+    const aliases = CANONICAL_ALIASES[verb];
+    return aliases.length ? cmd.aliases([...aliases]) : cmd;
+}