@phnx-labs/agents-cli 1.20.49 → 1.20.51

package/dist/lib/session/parse.js

@@ -6,8 +6,8 @@
  * objects suitable for rendering, filtering, and summarization.
  */
 import * as fs from 'fs';
+import { truncate } from '../format.js';
 import * as path from 'path';
-import { execFileSync } from 'child_process';
 import Database from '../sqlite.js';
 /**
  * Largest session file we will load into memory. Above this we throw a clean
@@ -218,10 +218,6 @@ export function summarizeToolUse(tool, args) {
         }
     }
 }
-/** Truncate a string to n characters, appending '...' if shortened. */
-function truncate(s, n) {
-    return s.length <= n ? s : s.slice(0, n - 3) + '...';
-}
 /** Replace the home directory prefix with ~ for display. */
 function shortenPath(p) {
     const home = process.env.HOME || '';
@@ -1006,45 +1002,50 @@ export function parseOpenCode(filePath) {
     if (!dbPath || !sessionId)
         return [];
     const events = [];
+    // Read through the node/bun SQLite wrapper (not the `sqlite3` CLI) so this
+    // works on every OS — the CLI is absent on Windows.
+    let rows;
+    let db;
     try {
-        // Query messages with their parts, ordered chronologically.
-        // Each row: msg_role ||| part_type ||| part_data (truncated for tool output) ||| msg_time
+        // Query messages with their parts, ordered chronologically. Tool parts are
+        // truncated to keep large tool outputs from bloating memory; the session id
+        // is bound as a parameter rather than interpolated.
         const query = `
       SELECT
-        json_extract(m.data, '$.role'),
-        json_extract(p.data, '$.type'),
+        json_extract(m.data, '$.role') AS role,
+        json_extract(p.data, '$.type') AS part_type,
         CASE
           WHEN json_extract(p.data, '$.type') = 'tool'
           THEN substr(p.data, 1, 2000)
           ELSE p.data
-        END,
-        m.time_created
+        END AS part_data,
+        m.time_created AS time_created
       FROM message m
       JOIN part p ON p.message_id = m.id AND p.session_id = m.session_id
-      WHERE m.session_id = '${sessionId.replace(/'/g, "''")}'
+      WHERE m.session_id = ?
       ORDER BY m.time_created ASC, p.time_created ASC;
     `.replace(/\n/g, ' ');
-        const out = execFileSync('sqlite3', ['-separator', '|||', dbPath, query], {
-            encoding: 'utf-8',
-            timeout: 10000,
-            maxBuffer: 32 * 1024 * 1024,
-            stdio: ['ignore', 'pipe', 'ignore'],
-        });
-        for (const line of out.split('\n')) {
-            if (!line.trim())
-                continue;
-            const sepIdx1 = line.indexOf('|||');
-            if (sepIdx1 === -1)
-                continue;
-            const sepIdx2 = line.indexOf('|||', sepIdx1 + 3);
-            if (sepIdx2 === -1)
-                continue;
-            const sepIdx3 = line.lastIndexOf('|||');
-            const role = line.slice(0, sepIdx1);
-            const partType = line.slice(sepIdx1 + 3, sepIdx2);
-            const partDataStr = line.slice(sepIdx2 + 3, sepIdx3);
-            const timeStr = line.slice(sepIdx3 + 3);
-            const timeMs = parseInt(timeStr, 10);
+        db = new Database(dbPath);
+        rows = db.prepare(query).all(sessionId);
+    }
+    catch {
+        /* DB not accessible, sqlite module unavailable, or query failed */
+        return events;
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch {
+            /* best-effort close */
+        }
+    }
+    try {
+        for (const row of rows) {
+            const role = typeof row.role === 'string' ? row.role : '';
+            const partType = typeof row.part_type === 'string' ? row.part_type : '';
+            const partDataStr = typeof row.part_data === 'string' ? row.part_data : '';
+            const timeMs = typeof row.time_created === 'number' ? row.time_created : parseInt(String(row.time_created), 10);
             const timestamp = isNaN(timeMs) ? new Date().toISOString() : new Date(timeMs).toISOString();
             let partData;
             try {
@@ -1112,7 +1113,7 @@ export function parseOpenCode(filePath) {
         }
     }
     catch {
-        /* DB not accessible or query failed */
+        /* malformed row payload — return what we parsed so far */
     }
     return events;
 }

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

@@ -6,7 +6,7 @@
  * errors, final message). The markdown renderer emits a full conversation
  * transcript. Filtering by role and turn slicing is handled here as well.
  */
-import type { SessionEvent } from './types.js';
+import type { SessionEvent, SessionMeta } from './types.js';
 /**
  * Return absPath relative to cwd; fall back to ~/… then absolute.
  */
@@ -103,7 +103,11 @@ export interface RenderConversationMarkdownOptions {
 }
 export declare function renderConversationMarkdown(events: SessionEvent[], opts?: RenderConversationMarkdownOptions): string;
 /**
- * Render session as JSON (normalized events).
+ * Render one session's JSON output — the shape `agents sessions <id> --json`
+ * emits. When `meta` is provided (the standard path), returns a
+ * `{ session, events }` wrapper so top-level fields (`plan`, `prUrl`, …) that
+ * live on `SessionMeta` are visible without re-parsing events. Legacy
+ * callers that pass no meta still get a bare `SessionEvent[]` array.
  */
-export declare function renderJson(events: SessionEvent[]): string;
+export declare function renderJson(events: SessionEvent[], meta?: SessionMeta): string;
 export {};

package/dist/lib/session/render.js

@@ -7,6 +7,7 @@
  * transcript. Filtering by role and turn slicing is handled here as well.
  */
 import chalk from 'chalk';
+import { truncate } from '../format.js';
 import { summarizeToolUse } from './parse.js';
 import { cleanSessionPrompt, extractSessionTopic } from './prompt.js';
 import { renderMarkdown } from '../markdown.js';
@@ -336,14 +337,14 @@ function renderCommandsSection(cmds, lines) {
                 if (catEntry.signal === 'mid') {
                     // Mid signal: display the bucket key (e.g. ssh→openclaw browser) with aggregate count
                     const countSuffix = v.count > 1 ? chalk.gray(` × ${v.count}`) : '';
-                    lines.push(`    ${chalk.cyan(truncateCmd(key, 80))}${countSuffix}`);
+                    lines.push(`    ${chalk.cyan(truncate(key, 80))}${countSuffix}`);
                 }
                 else {
                     // High signal: display distinct raw sample commands
                     const distinctSamples = pickDistinct(v.samples, 3);
                     for (const sample of distinctSamples) {
                         const countSuffix = v.count > 1 ? chalk.gray(` × ${v.count}`) : '';
-                        lines.push(`    ${chalk.cyan(truncateCmd(sample, 80))}${countSuffix}`);
+                        lines.push(`    ${chalk.cyan(truncate(sample, 80))}${countSuffix}`);
                     }
                 }
                 shown++;
@@ -354,7 +355,7 @@ function renderCommandsSection(cmds, lines) {
         lines.push(`  ${chalk.dim('Other')} ${chalk.gray(`(${otherCount})`)}`);
         for (const [, v] of Array.from(otherKeys.entries()).slice(0, 5)) {
             const countSuffix = v.count > 1 ? chalk.gray(` × ${v.count}`) : '';
-            lines.push(`    ${chalk.cyan(truncateCmd(v.samples[0] ?? '', 80))}${countSuffix}`);
+            lines.push(`    ${chalk.cyan(truncate(v.samples[0] ?? '', 80))}${countSuffix}`);
         }
     }
     lines.push('');
@@ -372,9 +373,6 @@ function pickDistinct(samples, max) {
     }
     return result.length > 0 ? result : samples.slice(0, max);
 }
-function truncateCmd(cmd, max) {
-    return cmd.length <= max ? cmd : cmd.slice(0, max - 1) + '…';
-}
 // ── File grouping ─────────────────────────────────────────────────────────────
 /** Group file paths by their parent directory, relative to cwd. */
 function groupByParentDir(paths, cwd) {
@@ -916,10 +914,18 @@ export function renderConversationMarkdown(events, opts = {}) {
     return parts.join('\n\n');
 }
 /**
- * Render session as JSON (normalized events).
+ * Render one session's JSON output — the shape `agents sessions <id> --json`
+ * emits. When `meta` is provided (the standard path), returns a
+ * `{ session, events }` wrapper so top-level fields (`plan`, `prUrl`, …) that
+ * live on `SessionMeta` are visible without re-parsing events. Legacy
+ * callers that pass no meta still get a bare `SessionEvent[]` array.
  */
-export function renderJson(events) {
-    return JSON.stringify(events, null, 2);
+export function renderJson(events, meta) {
+    if (!meta)
+        return JSON.stringify(events, null, 2);
+    // Strip internal-only bookkeeping fields the listing --json path also strips.
+    const { _matchedTerms, _bm25Score, _remote, ...session } = meta;
+    return JSON.stringify({ session, events }, null, 2);
 }
 /** Replace the home directory prefix with ~ for trace display. */
 function shortenPathTrace(p) {

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

@@ -17,6 +17,30 @@
 import type { SessionEvent } from './types.js';
 export type SessionActivity = 'working' | 'waiting_input' | 'idle';
 export type AwaitingReason = 'question' | 'plan_review' | 'permission';
+/** One discrete choice the agent offered the user. */
+export interface QuestionOption {
+    /** The choice label — also what a free-text reply channel sends back. */
+    label: string;
+    /** Optional longer description shown under the label. */
+    description?: string;
+    /**
+     * Selection keystroke for an interactive TUI prompt (AskUserQuestion / plan /
+     * permission are select-lists, not text inputs): a digit ('1'), or 'esc' to
+     * cancel/deny. Absent for a plain prose question, which takes free text.
+     */
+    key?: string;
+}
+/**
+ * The decision an agent handed back to the user, extracted at the SOURCE so every
+ * consumer (Factory panel, teams, cloud) gets the real question + options instead
+ * of re-deriving them from a truncated preview line. `reason` mirrors
+ * {@link AwaitingReason}; `options` is present when the agent offered discrete choices.
+ */
+export interface StructuredQuestion {
+    text: string;
+    reason: AwaitingReason;
+    options?: QuestionOption[];
+}
 export interface DetectedPr {
     url: string;
     number?: number;
@@ -40,6 +64,21 @@ export interface SessionState {
     lastEventKind?: SessionEvent['type'];
     /** Single-line description of the latest turn (message text or tool action). */
     preview?: string;
+    /**
+     * The structured decision the agent is waiting on (question / plan / permission),
+     * with its options when it offered any. Set only when activity is waiting_input.
+     */
+    question?: StructuredQuestion;
+    /**
+     * The plan markdown from the most recent `ExitPlanMode` tool call, surfaced
+     * when `awaitingReason === 'plan_review'`. The state engine detects the
+     * handoff off the same tool event; carrying the plan text alongside it lets
+     * consumers (the Factory NEEDS-YOU panel, `agents sessions <id> --json`)
+     * render the actual plan without re-parsing the transcript.
+     */
+    plan?: string;
+    /** Last few assistant turns (most-recent last), one line each — panel context. */
+    tail?: string[];
     lastActivityMs?: number;
     pr?: DetectedPr;
     worktree?: DetectedWorktree;
@@ -85,6 +124,22 @@ export declare function isTicketCreateTool(name?: string, command?: string): boo
  * take `#<number>`. Returns undefined when neither shape is present.
  */
 export declare function extractCreatedTicket(text?: string): string | undefined;
+/**
+ * Pull the plan markdown out of an `ExitPlanMode` tool_use event's args. The
+ * Claude tool schema is `{ plan: string }`; the transcript parser already
+ * lifts `input` onto `event.args`. Returns undefined for a missing/empty plan
+ * so consumers can rely on `plan?: string` truthiness.
+ */
+export declare function extractPlanText(args?: Record<string, any>): string | undefined;
+/**
+ * Structured question from a Claude `AskUserQuestion` tool call. Its input is
+ * `{ questions: [{ question, header, options: [{label, description}] }] }` and the
+ * whole thing is already parsed onto `event.args` by the transcript parser — this
+ * surfaces the first question + its options (instead of collapsing to a generic
+ * "Asked you a question"). The prompt is a select-list, so each option carries its
+ * 1-based selection digit as `key`.
+ */
+export declare function structuredQuestionFromAsk(args?: Record<string, any>): StructuredQuestion | undefined;
 /**
  * Infer live activity + a preview from a chronological event slice. `pr` /
  * `ticket` / `worktree` are attached by `inferSessionState`; this focuses on the

package/dist/lib/session/state.js

@@ -130,6 +130,69 @@ export function extractCreatedTicket(text) {
         return `#${gh[1]}`;
     return undefined;
 }
+/**
+ * Pull the plan markdown out of an `ExitPlanMode` tool_use event's args. The
+ * Claude tool schema is `{ plan: string }`; the transcript parser already
+ * lifts `input` onto `event.args`. Returns undefined for a missing/empty plan
+ * so consumers can rely on `plan?: string` truthiness.
+ */
+export function extractPlanText(args) {
+    const plan = args?.plan;
+    if (typeof plan !== 'string')
+        return undefined;
+    const trimmed = plan.trim();
+    return trimmed ? plan : undefined;
+}
+/**
+ * Structured question from a Claude `AskUserQuestion` tool call. Its input is
+ * `{ questions: [{ question, header, options: [{label, description}] }] }` and the
+ * whole thing is already parsed onto `event.args` by the transcript parser — this
+ * surfaces the first question + its options (instead of collapsing to a generic
+ * "Asked you a question"). The prompt is a select-list, so each option carries its
+ * 1-based selection digit as `key`.
+ */
+export function structuredQuestionFromAsk(args) {
+    const q = Array.isArray(args?.questions) ? args.questions[0] : undefined;
+    if (!q)
+        return undefined;
+    const text = oneLine(String(q.question ?? q.header ?? '')) || 'Asked you a question';
+    const raw = Array.isArray(q.options) ? q.options : [];
+    const options = [];
+    for (const o of raw) {
+        const label = typeof o === 'string' ? oneLine(o) : o?.label != null ? oneLine(String(o.label)) : '';
+        if (!label)
+            continue;
+        const description = typeof o === 'object' && o?.description != null ? oneLine(String(o.description)) : undefined;
+        options.push({ label, description, key: String(options.length + 1) });
+    }
+    return { text, reason: 'question', options: options.length ? options : undefined };
+}
+/**
+ * Canonical approve/deny choices for an interactive prompt that carries no
+ * agent-supplied option list: Claude's plan-review and permission dialogs. Approve
+ * is reliably option 1; deny/keep-planning maps to ESC, which cancels the prompt in
+ * every variant (2- or 3-option) — safer than guessing a digit that could differ.
+ */
+function planReviewQuestion() {
+    return {
+        text: 'Plan ready — review it',
+        reason: 'plan_review',
+        options: [
+            { label: 'Approve plan', key: '1' },
+            { label: 'Keep planning', key: 'esc' },
+        ],
+    };
+}
+function permissionQuestion(preview) {
+    return {
+        text: preview ? `Permission — ${preview}` : 'Waiting on a permission prompt',
+        reason: 'permission',
+        options: [
+            { label: 'Approve', key: '1' },
+            { label: 'Deny', key: 'esc' },
+        ],
+    };
+}
 /** Does an assistant message read as a question directed at the user? */
 function looksLikeQuestion(text) {
     const t = text.trim();
@@ -177,18 +240,27 @@ export function inferActivity(events, ctx = {}) {
     const lastToolUse = lastOf(meaningful, e => e.type === 'tool_use');
     // The most informative recent line: a message or tool call as-is, but for a
     // trailing tool_result/thinking show the tool *call* that produced it (its
-    // command) rather than a bare "↳ Bash".
+    // command), or — failing that — the last assistant message, rather than a bare
+    // "↳ Bash" or a content-free "thinking…". This is what stops a trailing thinking
+    // block from masking the real turn (the defect behind the "Thinking…" panel).
     const previewSource = !last
         ? undefined
         : last.type === 'message' || last.type === 'tool_use'
             ? last
-            : (lastToolUse ?? last);
+            : (lastToolUse ?? lastMsg ?? last);
+    // Last few assistant turns, most-recent last — context for the decision panel.
+    const tail = meaningful
+        .filter(e => e.type === 'message' && e.role === 'assistant' && e.content)
+        .slice(-3)
+        .map(e => oneLine(e.content ?? ''))
+        .filter(Boolean);
     const base = {
         activity: 'idle',
         lastRole: lastMsg?.role,
         lastEventKind: last?.type,
         lastActivityMs: ctx.mtimeMs,
         preview: previewSource ? describeEvent(previewSource) : undefined,
+        tail: tail.length ? tail : undefined,
     };
     if (!last)
         return base;
@@ -196,12 +268,15 @@ export function inferActivity(events, ctx = {}) {
     // tool and nothing has come after it.
     const lastPlanOrAsk = lastOf(meaningful, e => e.type === 'tool_use' && (e.tool === PLAN_TOOL || e.tool === ASK_TOOL));
     if (lastPlanOrAsk && meaningful.indexOf(lastPlanOrAsk) === meaningful.length - 1) {
-        return {
-            ...base,
-            activity: 'waiting_input',
-            awaitingReason: lastPlanOrAsk.tool === PLAN_TOOL ? 'plan_review' : 'question',
-            preview: lastPlanOrAsk.tool === PLAN_TOOL ? 'Plan ready — awaiting your review' : 'Asked you a question',
-        };
+        if (lastPlanOrAsk.tool === PLAN_TOOL) {
+            const question = planReviewQuestion();
+            const plan = extractPlanText(lastPlanOrAsk.args);
+            return { ...base, activity: 'waiting_input', awaitingReason: 'plan_review', preview: question.text, question, plan };
+        }
+        // AskUserQuestion: surface the real question + options (they're on `args`),
+        // not the generic "Asked you a question" that discarded them.
+        const question = structuredQuestionFromAsk(lastPlanOrAsk.args) ?? { text: 'Asked you a question', reason: 'question' };
+        return { ...base, activity: 'waiting_input', awaitingReason: 'question', preview: question.text, question };
     }
     // Pending tool call (tool_use with no following tool_result): mid-turn.
     if (last.type === 'tool_use') {
@@ -209,7 +284,7 @@ export function inferActivity(events, ctx = {}) {
             return { ...base, activity: 'working' };
         // Alive but the file hasn't moved — likely blocked on a permission prompt.
         if (ctx.pidAlive)
-            return { ...base, activity: 'waiting_input', awaitingReason: 'permission' };
+            return { ...base, activity: 'waiting_input', awaitingReason: 'permission', question: permissionQuestion(base.preview) };
         return { ...base, activity: 'idle' };
     }
     // Thinking or a tool result just landed → agent is mid-turn if recently active.
@@ -223,8 +298,10 @@ export function inferActivity(events, ctx = {}) {
             return { ...base, activity: canWork ? 'working' : 'idle' };
         }
         // Assistant spoke last and stopped. A trailing question → waiting; else idle.
+        // A prose question takes a free-text reply (no select-list), so no options/keys.
         if (looksLikeQuestion(last.content ?? '')) {
-            return { ...base, activity: 'waiting_input', awaitingReason: 'question' };
+            const text = oneLine(last.content ?? '');
+            return { ...base, activity: 'waiting_input', awaitingReason: 'question', question: { text, reason: 'question' } };
         }
         return { ...base, activity: 'idle' };
     }

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

@@ -97,6 +97,15 @@ export interface SessionMeta {
      * `isTeamOrigin` (which marks sessions spawned BY a team).
      */
     spawnedTeam?: string;
+    /**
+     * The plan markdown from the LAST `ExitPlanMode` tool call in the transcript
+     * (Claude sessions only), captured at scan time. Present whenever the session
+     * ever entered plan-review; consumers can pair it with a live
+     * `awaitingReason === 'plan_review'` to decide whether it is still pending.
+     * Fills the gap that forced the Factory extension to re-read raw JSONL to
+     * recover the plan text — the CLI now carries it on the metadata row.
+     */
+    plan?: 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/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 25;
+export declare const SHIM_SCHEMA_VERSION = 26;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -145,8 +145,14 @@ export declare function removeShim(agent: AgentId): boolean;
  *        editor opens the script and the agent never launches. The `.cmd` is
  *        now the only Windows artifact and carries this alias marker so
  *        staleness checks read it directly.
+ *  v13 — grok aliases resolve the binary from the versioned home's
+ *        .grok/downloads first, then fall back to the global ~/.grok/downloads.
+ *        The old template checked only the global dir, so a `grok@<version>`
+ *        alias failed with "not installed" whenever the binary was staged into
+ *        the versioned home (installer run with GROK_HOME set, or grok
+ *        self-update under the shim).
  */
-export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 12;
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 13;
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary
@@ -203,6 +209,23 @@ export declare function removeVersionedAlias(agent: AgentId, version: string): b
  * Check if a versioned alias exists (the on-disk artifact for this platform).
  */
 export declare function versionedAliasExists(agent: AgentId, version: string): boolean;
+/**
+ * Read the user's configured Codex model from their active `~/.codex/config.toml`.
+ *
+ * Codex runs under a per-version `CODEX_HOME` (see `buildExecEnv`). A dispatch
+ * pinned to a version whose home config lacks a top-level `model` key silently
+ * falls back to Codex's built-in default (currently `gpt-5.3-codex`), which a
+ * ChatGPT-tier account is not entitled to use — the run dies with HTTP 400
+ * before doing any work. The user's model preference lives in whichever
+ * version-home was active when they set it (`~/.codex` symlinks to it), so it is
+ * NOT visible to a run pinned to a different version. Forwarding it via `--model`
+ * keeps the user's "default model setup" regardless of the active version-home,
+ * and is concurrency-safe (no file writes) when fanning out many parallel runs.
+ *
+ * Returns the top-level `model` only (ignores `[profile.*]` tables). Best-effort:
+ * a missing/unreadable/unset config yields `undefined` (caller keeps prior behaviour).
+ */
+export declare function readCodexConfiguredModel(): string | undefined;
 /**
  * Switch the agent's config symlink to point to a specific version.
  * e.g., ~/.claude -> ~/.agents/versions/claude/2.0.65/home/.claude/

package/dist/lib/shims.js

@@ -214,7 +214,14 @@ async function promptConflictStrategy(conflictInfos) {
 // v25 — dispatcher self-recovery: if the baked AGENTS_BIN is gone (a removed/moved
 //        dev build that generated the shim), resolve `agents` on PATH instead of
 //        exiting 127, so a stale/vanished dev build can't brick every launch.
-export const SHIM_SCHEMA_VERSION = 25;
+// v26 — grok resolves its binary from the versioned home's .grok/downloads first
+//        ($VERSION_DIR/home/.grok/downloads, where the binary lands when the
+//        installer runs with GROK_HOME set or grok self-updates under the shim),
+//        then falls back to the global ~/.grok/downloads for pre-fix installs.
+//        The old dispatcher checked only the global dir, so a pinned grok that
+//        installed into the versioned home fell through to the "not installed"
+//        error.
+export const SHIM_SCHEMA_VERSION = 26;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -468,11 +475,14 @@ fi
 
 VERSION_DIR="$AGENTS_USER_DIR/.history/versions/$AGENT/$VERSION"
 
-# Grok special case: binary lives in ~/.grok/downloads/, not node_modules.
-# We still use the agents-cli version dir purely for GROK_HOME isolation.
+# Grok special case: binary lives in the versioned home's .grok/downloads (or,
+# for pre-fix installs, the global ~/.grok/downloads), not node_modules. We
+# still use the agents-cli version dir purely for GROK_HOME isolation.
 if [ "$AGENT" = "grok" ]; then
-  # Try to find a matching binary for the pinned version in the global grok downloads dir.
-  GROK_DOWNLOADS="$HOME/.grok/downloads"
+  # Check the versioned home first — this is where the binary lands when the
+  # installer runs with GROK_HOME set (i.e. via the shim or a correct
+  # \`agents add grok\`), or when grok self-updates from within the shim.
+  GROK_DOWNLOADS="$VERSION_DIR/home/.grok/downloads"
   if [ -d "$GROK_DOWNLOADS" ]; then
     # Prefer a binary whose filename contains the exact version
     BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | grep -i "$VERSION" | head -1)
@@ -481,6 +491,17 @@ if [ "$AGENT" = "grok" ]; then
       BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | head -1)
     fi
   fi
+  # Fall back to the global grok home (binary installed without GROK_HOME set,
+  # e.g. an earlier \`agents add grok@latest\` before this resolution fix).
+  if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
+    GROK_DOWNLOADS="$HOME/.grok/downloads"
+    if [ -d "$GROK_DOWNLOADS" ]; then
+      BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | grep -i "$VERSION" | head -1)
+      if [ -z "$BINARY" ]; then
+        BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | head -1)
+      fi
+    fi
+  fi
   if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
     # Last resort: the adopted native launcher (recorded absolute path) if we
     # adopted grok, else whatever is on PATH. Prefer the adopted record — after
@@ -744,8 +765,14 @@ export function removeShim(agent) {
  *        editor opens the script and the agent never launches. The `.cmd` is
  *        now the only Windows artifact and carries this alias marker so
  *        staleness checks read it directly.
+ *  v13 — grok aliases resolve the binary from the versioned home's
+ *        .grok/downloads first, then fall back to the global ~/.grok/downloads.
+ *        The old template checked only the global dir, so a `grok@<version>`
+ *        alias failed with "not installed" whenever the binary was staged into
+ *        the versioned home (installer run with GROK_HOME set, or grok
+ *        self-update under the shim).
  */
-export const VERSIONED_ALIAS_SCHEMA_VERSION = 12;
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 13;
 /** Internal marker string used to embed the schema version in versioned alias scripts. */
 const VERSIONED_ALIAS_VERSION_MARKER = 'agents-versioned-alias-version:';
 // The version string is interpolated into a generated bash script and into
@@ -822,13 +849,22 @@ export KIMI_CODE_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/
     // "agents __shim" which resolves via getBinaryPath() instead.
     const versionDir = `$HOME/.agents/.history/versions/${agent}/${version}`;
     const binaryResolution = agent === 'grok'
-        ? `# Grok ships its native binary in ~/.grok/downloads, not node_modules.
-GROK_DOWNLOADS="$HOME/.grok/downloads"
+        ? `# Grok ships its native binary in the versioned home's .grok/downloads (or,
+# for pre-fix installs, the global ~/.grok/downloads), not node_modules.
+GROK_DOWNLOADS="${versionDir}/home/.grok/downloads"
 BINARY=""
 if [ -d "$GROK_DOWNLOADS" ]; then
   BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | grep -i "${version}" | head -1)
   [ -n "$BINARY" ] || BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | head -1)
 fi
+# Fall back to the global grok home (binary installed without GROK_HOME set).
+if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
+  GROK_GLOBAL_DOWNLOADS="$HOME/.grok/downloads"
+  if [ -d "$GROK_GLOBAL_DOWNLOADS" ]; then
+    BINARY=$(ls "$GROK_GLOBAL_DOWNLOADS"/grok-* 2>/dev/null | grep -i "${version}" | head -1)
+    [ -n "$BINARY" ] || BINARY=$(ls "$GROK_GLOBAL_DOWNLOADS"/grok-* 2>/dev/null | head -1)
+  fi
+fi
 # Refuse a PATH match under our own shims dir — it resolves to this alias's
 # sibling dispatcher shim (shims dir is ahead of ~/.local/bin on PATH) and
 # re-execs forever. Fall through to the clean "not installed" error instead.
@@ -1008,6 +1044,35 @@ function getAgentConfigPath(agent) {
     const home = process.env.AGENTS_REAL_HOME || os.homedir();
     return agentConfig.configDir.replace(os.homedir(), home);
 }
+/**
+ * Read the user's configured Codex model from their active `~/.codex/config.toml`.
+ *
+ * Codex runs under a per-version `CODEX_HOME` (see `buildExecEnv`). A dispatch
+ * pinned to a version whose home config lacks a top-level `model` key silently
+ * falls back to Codex's built-in default (currently `gpt-5.3-codex`), which a
+ * ChatGPT-tier account is not entitled to use — the run dies with HTTP 400
+ * before doing any work. The user's model preference lives in whichever
+ * version-home was active when they set it (`~/.codex` symlinks to it), so it is
+ * NOT visible to a run pinned to a different version. Forwarding it via `--model`
+ * keeps the user's "default model setup" regardless of the active version-home,
+ * and is concurrency-safe (no file writes) when fanning out many parallel runs.
+ *
+ * Returns the top-level `model` only (ignores `[profile.*]` tables). Best-effort:
+ * a missing/unreadable/unset config yields `undefined` (caller keeps prior behaviour).
+ */
+export function readCodexConfiguredModel() {
+    try {
+        const cfg = path.join(getAgentConfigPath('codex'), 'config.toml');
+        const text = fs.readFileSync(cfg, 'utf-8');
+        // Only trust keys before the first [table]; a `model` under [profile.x] is
+        // not the default the CLI uses at top level.
+        const topLevel = text.split(/^\s*\[/m)[0];
+        return topLevel.match(/^\s*model\s*=\s*["']([^"']+)["']/m)?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Get the path to the version's config directory.
  * e.g., ~/.agents/versions/claude/2.0.65/home/.claude/