@phnx-labs/agents-cli 1.22.107 → 1.22.109

package/dist/lib/daemon/leaked-daemons.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The daemon state dir for an ARBITRARY home — the same layout state.ts's
+ * DAEMON_DIR chain produces (`<home>/.agents/.cache/helpers/daemon`). A caller
+ * under a redirected HOME (a test/e2e harness) uses this to find the REAL
+ * install's daemon records. Kept here rather than exported from state.ts: any
+ * edit to state.ts selects its entire static-import closure into the required
+ * impact gate (186 files, 295s against the 240s budget, measured on this
+ * change's first CI run), so the helper cannot live there without a
+ * budget-policy change. If state.ts's layout ever moves, this must move with
+ * it — the two are the same address.
+ */
+export declare function getDaemonDirForHome(home: string): string;
+/** One live `__daemon-run` process from the box-wide `ps` scan. */
+export interface DaemonRunProcess {
+    pid: number;
+    /** Owning uid from `ps`, or null when unavailable. */
+    uid: number | null;
+    /** Whitespace-tokenized argv (`ps` renders it unquoted). */
+    tokens: string[];
+}
+/**
+ * Every live `__daemon-run` process on this box, regardless of which install
+ * launched it or which state dir it serves. POSIX-only (uses `ps`); a no-op on
+ * Windows.
+ *
+ * `getDaemonLaunch` always spawns `<node> <entry> __daemon-run` with nothing
+ * after it — the ONLY argv `__daemon-run` ever appears in for a real daemon.
+ * A substring/regex test anywhere in the full command line is not enough: an
+ * `agents run claude "<prompt>"` invocation whose prompt happens to quote the
+ * literal text `__daemon-run` (this ticket's own brief does) matches that test
+ * too, and was observed producing false "duplicate daemon" rows. Requiring it
+ * to be the LAST whitespace-delimited token is the actual invariant.
+ *
+ * This raw box-wide scan is deliberately NOT the duplicate-detection scope
+ * (RUSH-2368): a `__daemon-run` under a different HOME serves a different
+ * `getDaemonDir()` and is not a duplicate of THIS device's daemon, however
+ * `ps` sees it — a leaked vitest fixture under its own `/tmp` HOME matched
+ * this scan and was reported as a stray to `kill`. Callers attach their own
+ * scope: `agents daemon status` gates on the instance registry,
+ * {@link findLeakedDaemons} on the owner records above.
+ */
+export declare function listDaemonRunProcesses(): DaemonRunProcess[];
+/** A `__daemon-run` process no owner record names. */
+export interface LeakedDaemon {
+    pid: number;
+    /** The HOME the process runs under, or null when it cannot be read. */
+    home: string | null;
+    /** The process's start time as `ps lstart` renders it, or null when unavailable. */
+    startedAt: string | null;
+    /** The launch entry (the argv token before `__daemon-run`), best-effort. */
+    entry: string | null;
+}
+/**
+ * Every `__daemon-run` process running as THIS uid that no owner record names:
+ * neither the service manager's unit main PID nor the recorded
+ * `<daemonDir>/daemon.pid`. Each result carries the process's HOME and start
+ * time so the report can show them. An empty list means no leak — including
+ * the common stopped-daemon case, where there is simply nothing running.
+ */
+export declare function findLeakedDaemons(): LeakedDaemon[];

package/dist/lib/daemon/leaked-daemons.js

@@ -0,0 +1,180 @@
+/**
+ * Leaked-daemon detection (W4, PHNX-3736).
+ *
+ * One daemon per device is the contract: the always-on process behind
+ * `agents __daemon-run` is either the service manager's unit main PID or the
+ * pid recorded in `<daemonDir>/daemon.pid`. Anything else running
+ * `__daemon-run` as this uid is a LEAK — a daemon nothing owns.
+ *
+ * The motivating incident ran 4+ days on yosemite-s1: a headless e2e session
+ * launched a daemon under `HOME=/tmp/pin-e2e-<pid>` and never stopped it. The
+ * pid-file takeover in `daemon.ts` could not see it because it keeps its own
+ * pid file under the temp home, and `agents daemon status`'s duplicate scope
+ * (`findSurvivingStateDirDaemons`, RUSH-2368) deliberately covers only this
+ * install's state dir — so the leak was invisible to every existing surface.
+ *
+ * Why flagging a different-HOME daemon here is not the RUSH-2368 harm: that
+ * incident taught that a `__daemon-run` under another HOME is not a DUPLICATE
+ * of this device's daemon and must never be told to `kill` from the duplicate
+ * path. This module does not accuse it of being a duplicate — it reports that
+ * NO owner record (unit main PID, recorded daemon.pid) names the pid at all,
+ * and shows the process's own HOME and start time so the operator can judge
+ * before acting. A different uid is never named: we cannot inspect its
+ * environment or signal it.
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { productionDaemonServiceNames, readDaemonPid, readServiceManagerPid } from './daemon.js';
+import { getDaemonDir } from '../state.js';
+/**
+ * The daemon state dir for an ARBITRARY home — the same layout state.ts's
+ * DAEMON_DIR chain produces (`<home>/.agents/.cache/helpers/daemon`). A caller
+ * under a redirected HOME (a test/e2e harness) uses this to find the REAL
+ * install's daemon records. Kept here rather than exported from state.ts: any
+ * edit to state.ts selects its entire static-import closure into the required
+ * impact gate (186 files, 295s against the 240s budget, measured on this
+ * change's first CI run), so the helper cannot live there without a
+ * budget-policy change. If state.ts's layout ever moves, this must move with
+ * it — the two are the same address.
+ */
+export function getDaemonDirForHome(home) {
+    return path.join(home, '.agents', '.cache', 'helpers', 'daemon');
+}
+/**
+ * Every live `__daemon-run` process on this box, regardless of which install
+ * launched it or which state dir it serves. POSIX-only (uses `ps`); a no-op on
+ * Windows.
+ *
+ * `getDaemonLaunch` always spawns `<node> <entry> __daemon-run` with nothing
+ * after it — the ONLY argv `__daemon-run` ever appears in for a real daemon.
+ * A substring/regex test anywhere in the full command line is not enough: an
+ * `agents run claude "<prompt>"` invocation whose prompt happens to quote the
+ * literal text `__daemon-run` (this ticket's own brief does) matches that test
+ * too, and was observed producing false "duplicate daemon" rows. Requiring it
+ * to be the LAST whitespace-delimited token is the actual invariant.
+ *
+ * This raw box-wide scan is deliberately NOT the duplicate-detection scope
+ * (RUSH-2368): a `__daemon-run` under a different HOME serves a different
+ * `getDaemonDir()` and is not a duplicate of THIS device's daemon, however
+ * `ps` sees it — a leaked vitest fixture under its own `/tmp` HOME matched
+ * this scan and was reported as a stray to `kill`. Callers attach their own
+ * scope: `agents daemon status` gates on the instance registry,
+ * {@link findLeakedDaemons} on the owner records above.
+ */
+export function listDaemonRunProcesses() {
+    if (process.platform === 'win32')
+        return [];
+    let out;
+    try {
+        out = execFileSync('ps', ['-eo', 'pid=,uid=,args='], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const line of out.split('\n')) {
+        const m = line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/);
+        if (!m)
+            continue;
+        const tokens = m[3].trim().split(/\s+/);
+        if (tokens.length === 0 || tokens[tokens.length - 1] !== '__daemon-run')
+            continue;
+        const pid = parseInt(m[1], 10);
+        if (isNaN(pid))
+            continue;
+        const uidParsed = parseInt(m[2], 10);
+        found.push({ pid, uid: isNaN(uidParsed) ? null : uidParsed, tokens });
+    }
+    return found;
+}
+/**
+ * The HOME of a live process, or null when unreadable. Linux reads
+ * `/proc/<pid>/environ`; macOS has no equivalent zero-dependency primitive, so
+ * it falls back to `ps -E`, which appends the environment to the command
+ * column. Both are best-effort: a null HOME must never turn into an accusation
+ * beyond "unknown".
+ */
+function processHome(pid) {
+    if (process.platform === 'linux') {
+        try {
+            const env = fs.readFileSync(`/proc/${pid}/environ`, 'utf-8');
+            for (const entry of env.split('\0')) {
+                if (entry.startsWith('HOME='))
+                    return entry.slice('HOME='.length) || null;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    try {
+        const out = execFileSync('ps', ['-E', '-o', 'command=', '-p', String(pid)], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+        const m = out.match(/(?:^|\s)HOME=(\S+)/);
+        return m ? m[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The start time of a live process as `ps lstart` renders it, or null (best-effort, POSIX only). */
+function processStartTime(pid) {
+    if (process.platform === 'win32')
+        return null;
+    try {
+        const out = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Every `__daemon-run` process running as THIS uid that no owner record names:
+ * neither the service manager's unit main PID nor the recorded
+ * `<daemonDir>/daemon.pid`. Each result carries the process's HOME and start
+ * time so the report can show them. An empty list means no leak — including
+ * the common stopped-daemon case, where there is simply nothing running.
+ */
+export function findLeakedDaemons() {
+    const owned = new Set();
+    const recorded = readDaemonPid();
+    if (recorded)
+        owned.add(recorded);
+    const unitPid = readServiceManagerPid();
+    if (unitPid)
+        owned.add(unitPid);
+    // A caller under a redirected HOME (a test/e2e harness) must still recognize
+    // the REAL install's daemon as owned: its records live under the account
+    // home (`os.userInfo().homedir` reads the passwd record, ignoring $HOME),
+    // not under this process's HOME. Flagging the box's healthy production
+    // daemon as a leak would be the RUSH-2368 harm through a new door.
+    const realDaemonDir = getDaemonDirForHome(os.userInfo().homedir);
+    if (realDaemonDir !== getDaemonDir()) {
+        const realRecorded = readDaemonPid(realDaemonDir);
+        if (realRecorded)
+            owned.add(realRecorded);
+        const realUnitPid = readServiceManagerPid(os.platform(), productionDaemonServiceNames());
+        if (realUnitPid)
+            owned.add(realUnitPid);
+    }
+    const myUid = typeof process.getuid === 'function' ? process.getuid() : null;
+    const leaked = [];
+    for (const p of listDaemonRunProcesses()) {
+        if (owned.has(p.pid))
+            continue;
+        // Another uid's daemon is never named: we cannot read its environment
+        // reliably and could not signal it if we tried.
+        if (myUid !== null && p.uid !== null && p.uid !== myUid)
+            continue;
+        leaked.push({
+            pid: p.pid,
+            home: processHome(p.pid),
+            startedAt: processStartTime(p.pid),
+            entry: p.tokens.length >= 2 ? p.tokens[p.tokens.length - 2] : null,
+        });
+    }
+    return leaked;
+}

package/dist/lib/devices/doctor-findings.d.ts

@@ -1,6 +1,7 @@
 import type { AgentId } from '../types.js';
 import type { DuplicateVersionHook } from '../hooks/install.js';
 import type { AgentsBinaryShadow } from '../binary-shadow.js';
+import type { LeakedDaemon } from '../daemon/leaked-daemons.js';
 import type { RcSecretFinding } from '../secrets-types.js';
 import type { OwnerSinkStatus } from '../channels/owner-sink.js';
 import { type WindowsSshEnrollmentAudit } from './windows-ssh-enrollment.js';
@@ -13,7 +14,7 @@ export type FindingSeverity = 'critical' | 'warning';
  *  the JSON consumer group by kind. */
 /** Every finding class. Severity is NOT annotated here — {@link FINDING_SEVERITY}
  *  below owns it, and a second copy in these comments is a fourth place to drift. */
-export declare const ALL_FINDING_KINDS: readonly ["logged-out", "logout-unprovable", "missing-hook", "missing-plugin", "unwired-hook", "hook-runtime-broken", "hook-runtime-visibility-unavailable", "cli-missing", "missing-resource", "content-drift", "never-synced", "stale", "repo-behind", "repo-drift", "fleet-resource-gap", "host-cli-missing", "host-cli-invalid", "version-skew", "orphan", "duplicate-hook", "duplicate-hook-drift", "rc-secret-export", "env-secret-export", "auth-bundle-wrong-backend", "exec-policy", "ssh-key-enrollment", "stale-cli", "binary-shadow", "owner-sink-unreachable"];
+export declare const ALL_FINDING_KINDS: readonly ["logged-out", "logout-unprovable", "missing-hook", "missing-plugin", "unwired-hook", "hook-runtime-broken", "hook-runtime-visibility-unavailable", "cli-missing", "missing-resource", "content-drift", "never-synced", "stale", "repo-behind", "repo-drift", "fleet-resource-gap", "host-cli-missing", "host-cli-invalid", "version-skew", "orphan", "duplicate-hook", "duplicate-hook-drift", "rc-secret-export", "env-secret-export", "auth-bundle-wrong-backend", "exec-policy", "ssh-key-enrollment", "stale-cli", "binary-shadow", "owner-sink-unreachable", "leaked-daemon"];
 /**
  * The severity each kind is emitted with - the SINGLE source of truth, read by
  * the builders below and asserted against both prose rubrics by
@@ -124,6 +125,11 @@ export interface LocalFindingInputs {
     ownerSink?: OwnerSinkStatus;
     /** `agents` binaries that shadow the currently running CLI (RUSH-2431). */
     binaryShadows?: AgentsBinaryShadow[];
+    /** `__daemon-run` processes no owner record names — neither the service
+     *  manager's unit main PID nor the recorded daemon.pid (W4, PHNX-3736).
+     *  Collected by `findLeakedDaemons` in the command (it runs `ps` and reads
+     *  /proc, so it stays out of this pure module). */
+    leakedDaemons?: LeakedDaemon[];
 }
 /**
  * Fold this machine's signals into findings. Missing hooks/plugins and unwired

package/dist/lib/devices/doctor-findings.js

@@ -27,7 +27,7 @@
  *              fleet-resource-gap · hook-runtime-visibility-unavailable · orphan · duplicate-hook ·
  *              duplicate-hook-drift · host-cli-missing · host-cli-invalid ·
  *              rc-secret-export · env-secret-export · auth-bundle-wrong-backend · exec-policy · stale-cli ·
- *              binary-shadow.
+ *              binary-shadow · leaked-daemon.
  *   (RUSH-2162 moved never-synced and duplicate-hook-drift to WARNING: both are
  *   stale-sync states one `agents sync` resolves, not "needs you now".)
  *
@@ -38,6 +38,7 @@
  * format, so the layout is unit-tested against fixtures with no live fleet.
  */
 import chalk from 'chalk';
+import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS, supportsAccountInspection } from '../agents.js';
 import { blocksLocalScripts } from '../platform/winpath.js';
 import { loginHint } from '../signin-badge.js';
@@ -126,6 +127,7 @@ export const ALL_FINDING_KINDS = [
     'stale-cli',
     'binary-shadow', // another agents binary on PATH or in a well-known dir shadows the running copy
     'owner-sink-unreachable', // the feed/notify owner-delivery lane can't reach the owner from this box
+    'leaked-daemon', // a `__daemon-run` process no owner record names (not the unit main PID, not daemon.pid)
 ];
 /**
  * The severity each kind is emitted with - the SINGLE source of truth, read by
@@ -174,6 +176,12 @@ export const FINDING_SEVERITY = {
     'ssh-key-enrollment': 'critical',
     'stale-cli': 'warning',
     'binary-shadow': 'warning',
+    // A stray `__daemon-run` under its own (usually temp) HOME: it shares nothing
+    // with this install's state, so it cannot double-fire the real box's work —
+    // but it is a leak nothing owns and it outlives whatever launched it (W4,
+    // PHNX-3736). A human reads its HOME/start time and kills it; nothing is
+    // blocked right now.
+    'leaked-daemon': 'warning',
 };
 function agentName(agent) {
     return AGENT_NAMES[agent] || agent;
@@ -305,6 +313,11 @@ export function remediationFor(finding) {
             return 'upgrade';
         case 'binary-shadow':
             return 'remove or repoint the shadowing agents install(s)';
+        case 'leaked-daemon':
+            // The builder emits the concrete `kill <pid>` — the pid is a property of
+            // the row it builds, not of anything remediationFor can see. This is the
+            // shape only, for a kind constructed through finding() by a future caller.
+            return 'kill <pid>';
         case 'owner-sink-unreachable':
             // The lane delivers over the rush-backed owner channel, which needs rush on
             // PATH AND a usable session in THIS context. Non-interactive shells miss a
@@ -579,6 +592,24 @@ export function buildLocalFindings(input) {
                 : `${shadows.length} agents binaries may shadow the running copy (incl. ${examples})`,
         }));
     }
+    // Leaked daemons (warning) — a `__daemon-run` no owner record names. One row
+    // per pid: the remediation is pid-specific, and the HOME + start time are
+    // what let the operator tell a leaked test fixture from something they meant
+    // to run before they kill it (W4, PHNX-3736). Built directly, not through
+    // finding(): the remediation carries this row's own pid.
+    for (const d of input.leakedDaemons ?? []) {
+        const home = d.home ?? 'unknown HOME';
+        const started = d.startedAt ? `, started ${d.startedAt}` : '';
+        // The launch entry names WHICH install leaked the daemon — part of what
+        // the operator judges before killing. Only a real path: for a stand-in
+        // (`node -e '<code>' __daemon-run`) the token is the code blob.
+        const entry = d.entry && path.isAbsolute(d.entry) ? ` · ${d.entry}` : '';
+        out.push({
+            severity: FINDING_SEVERITY['leaked-daemon'], kind: 'leaked-daemon', device,
+            message: `stray agents daemon (pid ${d.pid}) no unit or pid file owns — HOME=${home}${started}${entry}`,
+            remediation: `kill ${d.pid}`,
+        });
+    }
     return collapseAcrossVersions(out, new Set(input.isolatedVersions ?? []));
 }
 /**

package/dist/lib/hooks/install.js

@@ -2256,12 +2256,72 @@ export function pruneVersionHomeHookEntriesFromSettings(settingsPath, agent, rem
     }
     return removed;
 }
+function trustCodexHooks(hooksPath) {
+    const configPath = path.join(path.dirname(hooksPath), 'config.toml');
+    const hooksFile = JSON.parse(fs.readFileSync(hooksPath, 'utf-8'));
+    let tomlConfig = {};
+    if (fs.existsSync(configPath)) {
+        tomlConfig = TOML.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+    if (!tomlConfig.features || typeof tomlConfig.features !== 'object') {
+        tomlConfig.features = {};
+    }
+    // Codex 0.116+ feature flag is `hooks` (the legacy `codex_hooks` name is
+    // an unrecognized key that triggers a deprecation error and is ignored).
+    const features = tomlConfig.features;
+    delete features.codex_hooks;
+    features.hooks = true;
+    // Pre-trust hooks. The [hooks.state] key is keyed by the hooks.json path
+    // exactly as Codex resolves it (the absolute CODEX_HOME path), the
+    // snake_case event label, and the per-event group/handler indices — which
+    // must match Codex's parse order, so we iterate the just-written
+    // hooksFile structure in array order.
+    if (!tomlConfig.hooks || typeof tomlConfig.hooks !== 'object') {
+        tomlConfig.hooks = {};
+    }
+    const hooksTable = tomlConfig.hooks;
+    const existingState = hooksTable.state && typeof hooksTable.state === 'object'
+        ? hooksTable.state
+        : {};
+    const hookState = {};
+    for (const [event, eventGroups] of Object.entries(hooksFile.hooks)) {
+        const eventKeyLabel = CODEX_EVENT_KEY_LABELS[event];
+        if (!eventKeyLabel)
+            continue;
+        eventGroups.forEach((group, groupIdx) => {
+            if (!group.hooks)
+                return;
+            group.hooks.forEach((handler, handlerIdx) => {
+                if (handler.type !== 'command')
+                    return;
+                const key = `${hooksPath}:${eventKeyLabel}:${groupIdx}:${handlerIdx}`;
+                const trustedHash = computeCodexHookTrustHash(eventKeyLabel, handler.command, handler.timeout, group.matcher);
+                // Preserve a user's explicit `enabled = false` for this exact hook;
+                // only (re)write the trust hash.
+                const prior = existingState[key];
+                const entry = { trusted_hash: trustedHash };
+                if (prior && prior.enabled === false) {
+                    entry.enabled = false;
+                }
+                hookState[key] = entry;
+            });
+        });
+    }
+    // Carry forward trust state for any hooks we did not (re)register this
+    // pass — e.g. user-added hooks under a different command path.
+    for (const [key, entry] of Object.entries(existingState)) {
+        if (!(key in hookState)) {
+            hookState[key] = entry;
+        }
+    }
+    hooksTable.state = hookState;
+    fs.writeFileSync(configPath, TOML.stringify(tomlConfig), 'utf-8');
+}
 function registerHooksForCodex(versionHome, manifest, resolveScript, managedPrefixes) {
     const registered = [];
     const errors = [];
     const configDir = path.join(versionHome, '.codex');
     const hooksPath = path.join(configDir, 'hooks.json');
-    const configPath = path.join(configDir, 'config.toml');
     // Read existing hooks.json — must have top-level "hooks" wrapper key
     let hooksFile = { hooks: {} };
     if (fs.existsSync(hooksPath)) {
@@ -2373,66 +2433,7 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
     // them, so an untrusted hook is silently dropped. We compute the same
     // trust hash Codex would and persist it under [hooks.state].
     try {
-        let tomlConfig = {};
-        if (fs.existsSync(configPath)) {
-            try {
-                tomlConfig = TOML.parse(fs.readFileSync(configPath, 'utf-8'));
-            }
-            catch { /* start fresh if corrupt */ }
-        }
-        if (!tomlConfig.features || typeof tomlConfig.features !== 'object') {
-            tomlConfig.features = {};
-        }
-        // Codex 0.116+ feature flag is `hooks` (the legacy `codex_hooks` name is
-        // an unrecognized key that triggers a deprecation error and is ignored).
-        const features = tomlConfig.features;
-        delete features.codex_hooks;
-        features.hooks = true;
-        // Pre-trust hooks. The [hooks.state] key is keyed by the hooks.json path
-        // exactly as Codex resolves it (the absolute CODEX_HOME path), the
-        // snake_case event label, and the per-event group/handler indices — which
-        // must match Codex's parse order, so we iterate the just-written
-        // hooksFile structure in array order.
-        if (!tomlConfig.hooks || typeof tomlConfig.hooks !== 'object') {
-            tomlConfig.hooks = {};
-        }
-        const hooksTable = tomlConfig.hooks;
-        const existingState = hooksTable.state && typeof hooksTable.state === 'object'
-            ? hooksTable.state
-            : {};
-        const hookState = {};
-        for (const [event, eventGroups] of Object.entries(hooksFile.hooks)) {
-            const eventKeyLabel = CODEX_EVENT_KEY_LABELS[event];
-            if (!eventKeyLabel)
-                continue;
-            eventGroups.forEach((group, groupIdx) => {
-                if (!group.hooks)
-                    return;
-                group.hooks.forEach((handler, handlerIdx) => {
-                    if (handler.type !== 'command')
-                        return;
-                    const key = `${hooksPath}:${eventKeyLabel}:${groupIdx}:${handlerIdx}`;
-                    const trustedHash = computeCodexHookTrustHash(eventKeyLabel, handler.command, handler.timeout, group.matcher);
-                    // Preserve a user's explicit `enabled = false` for this exact hook;
-                    // only (re)write the trust hash.
-                    const prior = existingState[key];
-                    const entry = { trusted_hash: trustedHash };
-                    if (prior && prior.enabled === false) {
-                        entry.enabled = false;
-                    }
-                    hookState[key] = entry;
-                });
-            });
-        }
-        // Carry forward trust state for any hooks we did not (re)register this
-        // pass — e.g. user-added hooks under a different command path.
-        for (const [key, entry] of Object.entries(existingState)) {
-            if (!(key in hookState)) {
-                hookState[key] = entry;
-            }
-        }
-        hooksTable.state = hookState;
-        fs.writeFileSync(configPath, TOML.stringify(tomlConfig), 'utf-8');
+        trustCodexHooks(hooksPath);
     }
     catch (err) {
         errors.push(`Failed to update config.toml: ${err.message}`);
@@ -3282,11 +3283,14 @@ export async function installSessionTrackerHook(agent, version, home) {
     if (!invocation) {
         return { installed: false, error: 'session-tracker not built and tsx is unavailable' };
     }
+    const env = sessionTrackerInstallEnv(agent, version, home);
     try {
         await execFileAsync(invocation.command, invocation.args, {
-            env: sessionTrackerInstallEnv(agent, version, home),
+            env,
             encoding: 'utf8',
         });
+        if (agent === 'codex')
+            trustCodexHooks(path.join(env.HOME ?? os.homedir(), '.codex', 'hooks.json'));
         return { installed: true };
     }
     catch (err) {
@@ -3324,12 +3328,15 @@ export function installSessionTrackerHookSync(agent, version, home) {
     if (!invocation) {
         return { installed: false, error: 'session-tracker not built and tsx is unavailable' };
     }
+    const env = sessionTrackerInstallEnv(agent, version, home);
     try {
         execFileSync(invocation.command, invocation.args, {
-            env: sessionTrackerInstallEnv(agent, version, home),
+            env,
             stdio: ['ignore', 'pipe', 'pipe'],
             encoding: 'utf8',
         });
+        if (agent === 'codex')
+            trustCodexHooks(path.join(env.HOME ?? os.homedir(), '.codex', 'hooks.json'));
         return { installed: true };
     }
     catch (err) {

package/dist/lib/models.js

@@ -13,7 +13,8 @@ import { execFileSync } from 'child_process';
 import chalk from 'chalk';
 import { getVersionDir, getVersionHomePath, getBinaryPath } from './installations/versions.js';
 import { getModelsCachePath } from './state.js';
-import { agentConfigDirName } from './agents.js';
+import { agentConfigDirName, resolveOpenCodeXdgPath } from './agents.js';
+import { stripJsonComments } from './permissions-registry.js';
 import { resolveRunDefaults } from './run-defaults.js';
 import { getModelPricing } from './pricing/index.js';
 const CACHE_PATH = getModelsCachePath();
@@ -1014,6 +1015,12 @@ export function resolveConfiguredModel(agent, version, home) {
     const nativeModel = readNativeConfigModel(agent, version, home);
     if (nativeModel)
         return { model: nativeModel, source: 'config' };
+    // The agent's own persisted selection, for a runtime that stores one instead
+    // of flagging a catalog default. Ranks below `config` (an explicit setting
+    // wins) and above the catalog, whose `isDefault` OpenCode never sets.
+    const selected = readNativeSelectedModel(agent, version);
+    if (selected)
+        return { model: selected, source: 'cli-default' };
     const catalog = getModelCatalog(agent, version);
     if (catalog) {
         const flagged = catalog.models.find((m) => m.isDefault);
@@ -1022,15 +1029,79 @@ export function resolveConfiguredModel(agent, version, home) {
     return null;
 }
 /**
- * Best-effort read of the agent's own `model` from its native settings.json
+ * Where each agent keeps its OWN `model` setting, when that is not the
+ * `<configDir>/settings.json` every Claude-shaped harness uses.
+ *
+ * OpenCode reads `~/.config/opencode/opencode.{jsonc,json}` and puts `model` at
+ * its top level as `"<provider>/<model-id>"`. Its `~/.opencode/settings.json`
+ * DOES exist, but that is agents-cli's own plugin-enablement file, which
+ * OpenCode never reads a model from — so the default path found nothing and
+ * every OpenCode row rendered the placeholder `default`. Comments are stripped
+ * for BOTH spellings because OpenCode's loader accepts them in both, which is
+ * also how the MCP writer treats the same file (`format: 'opencode-jsonc'`).
+ */
+const NATIVE_MODEL_CONFIGS = {
+    opencode: {
+        paths: (home) => [
+            path.join(home, '.config', 'opencode', 'opencode.jsonc'),
+            path.join(home, '.config', 'opencode', 'opencode.json'),
+        ],
+        jsonc: true,
+    },
+};
+/**
+ * Best-effort read of the agent's own `model` from its native config
  * (e.g. `~/.agents/.history/versions/claude/<ver>/home/.claude/settings.json`).
  * A missing/malformed file is a fall-through, not an error.
  */
 function readNativeConfigModel(agent, version, home) {
+    const resolvedHome = home ?? getVersionHomePath(agent, version);
+    const native = NATIVE_MODEL_CONFIGS[agent];
+    const candidates = native?.paths(resolvedHome)
+        ?? [path.join(resolvedHome, agentConfigDirName(agent), 'settings.json')];
+    for (const configPath of candidates) {
+        try {
+            const raw = fs.readFileSync(configPath, 'utf8');
+            const parsed = JSON.parse(native?.jsonc ? stripJsonComments(raw) : raw);
+            if (typeof parsed.model === 'string' && parsed.model.trim() !== '')
+                return parsed.model;
+        }
+        catch {
+            /* absent or malformed — try the next spelling */
+        }
+    }
+    return null;
+}
+/**
+ * The model the agent's OWN runtime will start with, for a harness that persists
+ * its selection rather than flagging a catalog default.
+ *
+ * OpenCode is the case that needs it: it ships no default model, so its catalog
+ * has no `isDefault` and `agents view` fell through to the literal `default` —
+ * a placeholder, not something the user could act on. OpenCode instead records
+ * the model picked in its TUI to `$XDG_STATE_HOME/opencode/model.json` as
+ * `{ recent: [{ providerID, modelID }, …] }`, newest first, and reuses
+ * `recent[0]` for the next session. That entry is the real answer to "what model
+ * is this install on", rendered the same `<provider>/<model-id>` way OpenCode's
+ * own config spells it.
+ *
+ * Returns null for every other agent, and for OpenCode when nothing has been
+ * selected yet — the catalog fallback still applies.
+ */
+function readNativeSelectedModel(agent, version) {
+    if (agent !== 'opencode')
+        return null;
+    const statePath = resolveOpenCodeXdgPath(getVersionHomePath(agent, version), 'state', 'model.json');
+    if (!statePath)
+        return null;
     try {
-        const settingsPath = path.join(home ?? getVersionHomePath(agent, version), agentConfigDirName(agent), 'settings.json');
-        const parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-        return typeof parsed.model === 'string' && parsed.model.trim() !== '' ? parsed.model : null;
+        const parsed = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+        const current = parsed.recent?.[0];
+        const provider = typeof current?.providerID === 'string' ? current.providerID : '';
+        const model = typeof current?.modelID === 'string' ? current.modelID : '';
+        if (!model)
+            return null;
+        return provider ? `${provider}/${model}` : model;
     }
     catch {
         return null;

package/dist/lib/session/cloud.js

@@ -53,6 +53,8 @@ function agentToFormat(agent) {
         return 'rush';
     if (agent === 'droid')
         return 'droid';
+    if (agent === 'opencode')
+        return 'opencode';
     return null;
 }
 export function assertContained(candidate, rootDir) {
@@ -128,7 +130,7 @@ export async function ensureCloudSessionCached(executionId, destPath) {
         throw new Error(`session.jsonl fetch ${res.status}: ${body.slice(0, 200)}`);
     }
     const format = (res.headers.get('X-Session-Format') || '').toLowerCase();
-    if (!['claude', 'codex', 'rush'].includes(format)) {
+    if (!['claude', 'codex', 'rush', 'opencode'].includes(format)) {
         throw new Error(`Unknown X-Session-Format on cloud response: "${format}"`);
     }
     const finalPath = callerPath ?? cachePathForExecution(id, format);

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

@@ -229,6 +229,7 @@ export declare function parseGrok(filePath: string): SessionEvent[];
  */
 export declare const OPENCODE_TRANSCRIPT_QUERY: string;
 export declare function parseOpenCode(filePath: string): SessionEvent[];
+export declare function parseOpencodeCloud(filePath: string): SessionEvent[];
 /** Parse a Rush JSONL session file into normalized events. */
 export declare function parseRush(filePath: string): SessionEvent[];
 /**