@phnx-labs/agents-cli 1.20.66 → 1.20.67

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 1.20.67
+
+- **Interactive session browser — `agents sessions --active` and a bare `agents sessions`
+  now open a live, filterable picker on a TTY (RUSH-1802).** One canonical filter driven by
+  single keys, re-pulled across the fleet as you toggle: `s` search, `r` running-only, `c`
+  teams, `a` agent (cycles), `d` device (cycles), `p` this-repo↔all-dirs, `w` time window;
+  filters **stack** (AND together) and the active set shows in the header, with a live
+  preview of the highlighted row and `⏎` to resume/attach via the existing dispatch. Every
+  hotkey mirrors a flag, so the view is reproducible as a command — `y` copies (and
+  `--print-cmd` prints) the exact `ag sessions …` line the filters map to, bridging the
+  human picker and the agent/script flag surface. The interactive front-end is TTY-only:
+  `--json`, a pipe, or the new `--no-interactive` keep the existing static listing verbatim,
+  so scripts and headless agents are unchanged. Adds `-p` as the short form of `--project`,
+  `--print-cmd`, `--preview` (`agents sessions <id> --preview` prints the compact digest
+  without the pager), and `--no-interactive`. Built on a new async-refetch `dynamicPicker`
+  variant that reuses the existing render/pagination/preview machinery, the fleet SSH
+  fan-out, and the resume/focus path. Source: `apps/cli/src/lib/picker.ts` (`dynamicPicker`),
+  `apps/cli/src/commands/sessions-browser.ts` (+ `sessions-browser.test.ts`),
+  `apps/cli/src/commands/sessions.ts`.
+
+- **kimi/grok headless `--mode plan` now auto-downgrades to `auto` instead of
+  crashing or stalling (RUSH-1810).** kimi's headless `-p` refuses to combine with
+  `--plan` (it hard-failed at spawn) and grok's `--permission-mode plan` silently
+  stalls a headless run at its ExitPlanMode gate. Both now model this honestly with
+  a `capabilities.headlessPlan: false` flag: a headless plan request degrades to
+  `auto` (kimi `-p` auto-runs; grok maps `auto`→`edit`) with a one-line stderr
+  warning, mirroring the graceful plan→edit degrade cursor/antigravity already get.
+  Interactive plan is unchanged, and claude/codex/droid/opencode keep read-only
+  plan headless. The same downgrade covers `agents run`, `agents teams add`
+  teammates, and routine jobs. Source: `apps/cli/src/lib/exec.ts`
+  (`resolveHeadlessMode`), `apps/cli/src/lib/runner.ts`, `apps/cli/src/lib/agents.ts`,
+  `apps/cli/src/lib/types.ts`.
+
 ## 1.20.66
 
 - **Fix (`agents monitors`, RUSH-1782 follow-up): `--watch-device` no longer silently watches the local machine on a bad name.** An unregistered or mistyped `--watch-device` name is now rejected at `add` time (same registry gate as `--device`/`--devices`), and the device source evaluator returns an explicit `device not registered` observation instead of falling back to local stats if a watched device is removed later — closing a "monitors the wrong box, silently" gap. The rate-limit firehose trip now also writes a fire record (`ok:false, error:'rate limited'`), so `agents monitors runs` reflects the auto-pause that `view`'s `last fired` already showed. Adds `sources/device.test.ts`. Source: `apps/cli/src/lib/monitors/sources/device.ts`, `apps/cli/src/commands/monitors.ts`, `apps/cli/src/lib/monitors/engine.ts`.

package/dist/commands/exec.js

@@ -328,6 +328,12 @@ export function registerRunCommand(program) {
         skip  bypass every permission prompt (dangerously-skip-permissions)
         Legacy 'full' is silently rewritten to 'skip'.
 
+      Headless plan support (a prompt makes the run headless):
+        plan works headless on claude, codex, droid, opencode.
+        kimi, grok, cursor, antigravity have no headless plan mode — a headless
+        --mode plan auto-downgrades to --mode auto (with a stderr warning).
+        Interactive plan (omit the prompt) works everywhere it is listed.
+
       Run strategy (set via --strategy or run.<agent>.strategy in agents.yaml):
         pinned     use the workspace/global pinned version
         available  use pinned if it can run right now; otherwise switch to another signed-in version

package/dist/commands/teams.js

@@ -1059,7 +1059,7 @@ export function registerTeamsCommands(program) {
         .alias('a')
         .description("Add a teammate to work on a task. Runs in background; returns immediately. Use 'status' to check in.")
         .option('-n, --name <name>', 'Friendly name for this teammate (e.g. alice). Required if using --after. Unique within team.')
-        .option('-m, --mode <mode>', `Permissions: plan (read-only) | edit (can write files) | auto (smart classifier auto-approves safe ops) | skip (bypass all permission prompts). 'full' accepted as alias for skip.`, 'edit')
+        .option('-m, --mode <mode>', `Permissions: plan (read-only) | edit (can write files) | auto (smart classifier auto-approves safe ops) | skip (bypass all permission prompts). 'full' accepted as alias for skip. Teammates run headless: plan works headless on claude/codex/droid/opencode; kimi/grok/cursor/antigravity have no headless plan mode and auto-downgrade a plan request to auto.`, 'edit')
         .option('-e, --effort <effort>', `Reasoning intensity: ${VALID_EFFORTS.join('|')}`, 'medium')
         .option('--model <model>', 'Override the effort tier and use this specific model (e.g. claude-opus-4-6)')
         .option('--env <key=value>', 'Set an environment variable for this teammate (repeatable for multiple vars)', (val, prev) => [...prev, val], [])

package/dist/lib/agents.js

@@ -505,6 +505,10 @@ export const AGENTS = {
             workflows: false,
             memory: true,
             modes: ['plan', 'edit', 'skip'],
+            // grok's `--permission-mode plan` silently stalls a headless `-p` run at
+            // its ExitPlanMode gate (no TTY to approve). Headless plan auto-downgrades
+            // to auto (→ edit via resolveMode). Interactive plan is unaffected.
+            headlessPlan: false,
             rulesImports: true,
         },
     },
@@ -544,6 +548,10 @@ export const AGENTS = {
             workflows: true,
             memory: false,
             modes: ['plan', 'edit', 'auto', 'skip'],
+            // kimi's headless `-p` refuses to combine with `--plan` (`Cannot combine
+            // --prompt with --plan`). Headless plan auto-downgrades to auto (kimi -p
+            // auto-runs). Interactive plan is unaffected.
+            headlessPlan: false,
             rulesImports: false,
         },
     },

package/dist/lib/exec.d.ts

@@ -52,6 +52,21 @@ export declare function headlessPlanStallCommand(args: {
  *   explicitly asked to bypass permissions; pretending we did is unsafe.
  */
 export declare function resolveMode(agent: AgentId, requested: Mode): Mode;
+/**
+ * Resolve a requested mode for a run, honoring whether the run is HEADLESS.
+ *
+ * Wraps resolveMode with one extra rule: an agent may list `plan` in its modes
+ * (so interactive plan works) yet declare `capabilities.headlessPlan === false`
+ * because plan is broken in a headless `--prompt`/`-p` run — kimi refuses
+ * `--prompt` + `--plan`, and grok's `--permission-mode plan` silently stalls at
+ * its ExitPlanMode gate. For those agents, a headless plan request degrades to
+ * `auto` (kimi -p auto-runs; grok maps auto→edit via resolveMode) with a visible
+ * one-line stderr warning, mirroring the graceful plan→edit degrade cursor and
+ * antigravity get for having no plan flag at all. Interactive runs are never
+ * downgraded. This is the single source of truth shared by buildExecCommand
+ * (agents run / teams) and the routine runner.
+ */
+export declare function resolveHeadlessMode(agent: AgentId, requested: Mode, interactive: boolean): Mode;
 /**
  * The mode an agent should run in when the caller has no preference.
  *

package/dist/lib/exec.js

@@ -104,6 +104,28 @@ export function resolveMode(agent, requested) {
     }
     throw new Error(`${agent} does not support '${requested}' mode. Supported modes: ${supported.join(', ')}.`);
 }
+/**
+ * Resolve a requested mode for a run, honoring whether the run is HEADLESS.
+ *
+ * Wraps resolveMode with one extra rule: an agent may list `plan` in its modes
+ * (so interactive plan works) yet declare `capabilities.headlessPlan === false`
+ * because plan is broken in a headless `--prompt`/`-p` run — kimi refuses
+ * `--prompt` + `--plan`, and grok's `--permission-mode plan` silently stalls at
+ * its ExitPlanMode gate. For those agents, a headless plan request degrades to
+ * `auto` (kimi -p auto-runs; grok maps auto→edit via resolveMode) with a visible
+ * one-line stderr warning, mirroring the graceful plan→edit degrade cursor and
+ * antigravity get for having no plan flag at all. Interactive runs are never
+ * downgraded. This is the single source of truth shared by buildExecCommand
+ * (agents run / teams) and the routine runner.
+ */
+export function resolveHeadlessMode(agent, requested, interactive) {
+    const mode = resolveMode(agent, requested);
+    if (!interactive && mode === 'plan' && AGENTS[agent].capabilities.headlessPlan === false) {
+        process.stderr.write(`warning: ${agent} has no headless plan mode; running --mode auto instead\n`);
+        return resolveMode(agent, 'auto');
+    }
+    return mode;
+}
 /**
  * The mode an agent should run in when the caller has no preference.
  *
@@ -573,9 +595,11 @@ export function buildExecCommand(options) {
     // Resolve the requested mode against the agent's capability table.
     // - `auto` on an agent without auto support → silently degrades to `edit`
     // - `plan` on an agent without a read-only mode → degrades to modes[0]
+    // - headless `plan` on an agent with headlessPlan:false (kimi, grok) →
+    //   degrades to `auto` with a stderr warning (see resolveHeadlessMode)
     // - `skip` on an unsupported agent → throws a clear error
-    // After resolveMode, the chosen mode is guaranteed to be in template.modeFlags.
-    const resolvedMode = resolveMode(options.agent, normalizeMode(options.mode));
+    // After resolution, the chosen mode is guaranteed to be in template.modeFlags.
+    const resolvedMode = resolveHeadlessMode(options.agent, normalizeMode(options.mode), interactive);
     const modeFlags = template.modeFlags[resolvedMode];
     if (!modeFlags) {
         // Defense in depth: would only fire if AGENTS.capabilities.modes and
@@ -609,11 +633,12 @@ export function buildExecCommand(options) {
         // all abort with "Cannot combine --prompt with --X" (verified against the live
         // kimi CLI). The write-capable modes (edit/auto/skip) all collapse to kimi's
         // default `-p` behavior, which already auto-approves tool calls, so we emit no
-        // mode flag. Plan (read-only) has no headless equivalent, so fail closed rather
-        // than silently letting a plan-mode run mutate the workspace.
+        // mode flag. Plan can't reach here headless — resolveHeadlessMode already
+        // downgraded it to auto (kimi's headlessPlan:false); this asserts that
+        // invariant so a plan-mode run can never silently mutate the workspace.
         if (resolvedMode === 'plan') {
-            throw new Error('kimi has no headless read-only mode: `--prompt` cannot be combined with `--plan`. ' +
-                'Run kimi in plan mode interactively (omit the prompt), or use --mode edit, auto, or skip.');
+            throw new Error(`Internal error: kimi reached headless command build with resolved mode 'plan'; ` +
+                `resolveHeadlessMode should have downgraded it to auto (capabilities.headlessPlan is false).`);
         }
         // edit/auto/skip: emit no mode flag — `kimi -p` auto-runs.
     }

package/dist/lib/runner.js

@@ -22,7 +22,7 @@ import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { createTimer, maybeRotate, redactPrompt } from './events.js';
-import { normalizeMode, buildExecEnv, detectRateLimit, } from './exec.js';
+import { normalizeMode, resolveHeadlessMode, buildExecEnv, detectRateLimit, } from './exec.js';
 import { loadTask as loadHostTask } from './hosts/tasks.js';
 import { reconcileTask as reconcileHostTask } from './hosts/reconcile.js';
 import { backgroundSpawnOptions } from './platform/process.js';
@@ -129,12 +129,11 @@ export function buildJobCommand(config, resolvedPrompt) {
         // kimi daemon jobs always run headless via `--prompt`, which cannot be
         // combined with any startup-mode flag (--plan/--auto/--yolo all abort with
         // "Cannot combine --prompt with --X"). edit/auto/skip reduce to kimi's default
-        // headless auto-run, so emit no flag; plan has no headless read-only
-        // equivalent, so fail closed rather than silently allowing writes.
-        if (mode === 'plan') {
-            throw new Error('kimi has no headless read-only mode: routine jobs cannot run kimi with --mode plan ' +
-                '(kimi rejects --prompt + --plan). Use --mode edit, auto, or skip.');
-        }
+        // headless auto-run, so emit no flag. plan has no headless read-only
+        // equivalent, so resolveHeadlessMode downgrades a plan request to auto with a
+        // stderr warning (kimi's headlessPlan is false) — routines run headless, so
+        // interactive is always false here. The returned mode carries no flag either.
+        resolveHeadlessMode('kimi', mode, false);
         appendModelAndReasoning(cmd, config);
     }
     if (config.agent === 'droid') {

package/dist/lib/types.d.ts

@@ -160,6 +160,16 @@ export interface AgentConfig {
          * `skip` errors with a clear message naming the supported modes.
          */
         modes: Mode[];
+        /**
+         * Whether `plan` mode works in a HEADLESS run (`--prompt`/`-p`). Some CLIs
+         * list a `plan` mode that only works interactively — kimi refuses `--prompt`
+         * combined with `--plan`, and grok's `--permission-mode plan` silently stalls
+         * a headless run at its ExitPlanMode gate. Absent (undefined) means true:
+         * headless plan is assumed to work unless a agent opts out with `false`, in
+         * which case a headless `--mode plan` request auto-downgrades to `auto`
+         * (see resolveHeadlessMode). Interactive plan is unaffected.
+         */
+        headlessPlan?: boolean;
         /**
          * Whether the agent natively resolves `@path/to/file` imports inside its
          * rules file at session start. If false, agents-cli must pre-compile the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.66",
+  "version": "1.20.67",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",