@phnx-labs/agents-cli 1.22.23 → 1.22.24

package/dist/lib/doctor-diff.js

@@ -33,7 +33,8 @@ import { shouldInstallCommandAsSkill, commandSkillMatches, commandSkillName } fr
 import { gooseCommandMatches, gooseCommandsDir } from './goose-commands.js';
 import { supports } from './capabilities.js';
 import { listSkillsInVersionHome, getVersionSkillsDir } from './skills.js';
-import { listHooksInVersionHome, listHookEntriesFromDir, checkVersionHookWiring } from './hooks.js';
+import { listHookEntriesFromDir } from './hooks.js';
+import { getResourceInventory } from './resource-inventory.js';
 const RULES_DOC_FILENAME = 'README.md';
 const ALL_KINDS = [
     'commands',
@@ -300,11 +301,10 @@ function diffSkills(agent, version, cwd, excludeProject = false) {
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
 // ─── hooks ────────────────────────────────────────────────────────────────────
-function diffHooks(agent, version, cwd) {
+function diffHooks(agent, version, cwd, inventory) {
     if (!AGENTS[agent].supportsHooks)
         return [];
-    const installedEntries = listHooksInVersionHome(agent, version);
-    const installedByName = new Map(installedEntries.map((e) => [e.name, e]));
+    const installedByName = new Map(inventory.onDisk.map((e) => [e.name, e]));
     // Sync intentionally excludes project/.agents/hooks/ — mirror that.
     const layerBases = buildLayerBases(cwd, 'hooks', { excludeProject: true });
     // Group source files the same way the hook installer does (basename across
@@ -329,14 +329,14 @@ function diffHooks(agent, version, cwd) {
             continue;
         }
         const a = readSafe(src.entry.scriptPath);
-        const b = readSafe(installed.scriptPath);
+        const b = readSafe(installed.path);
         let matches = a != null && b != null && normalize(a) === normalize(b);
-        if (matches && src.entry.dataFile && installed.dataFile) {
+        if (matches && src.entry.dataFile && installed.detail) {
             const ad = readSafe(src.entry.dataFile);
-            const bd = readSafe(installed.dataFile);
+            const bd = readSafe(installed.detail);
             matches = ad != null && bd != null && normalize(ad) === normalize(bd);
         }
-        else if (matches && (!!src.entry.dataFile !== !!installed.dataFile)) {
+        else if (matches && (!!src.entry.dataFile !== !!installed.detail)) {
             matches = false;
         }
         rows.push({
@@ -345,13 +345,13 @@ function diffHooks(agent, version, cwd) {
             status: matches ? 'ok' : 'diff',
             source: src.layer,
             sourcePath: src.entry.scriptPath,
-            homePath: installed.scriptPath,
+            homePath: installed.path,
         });
     }
     for (const [name, installed] of installedByName) {
         if (seen.has(name))
             continue;
-        rows.push({ kind: 'hooks', name, status: 'extra', homePath: installed.scriptPath });
+        rows.push({ kind: 'hooks', name, status: 'extra', homePath: installed.path });
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -609,12 +609,13 @@ export function diffVersionResources(agent, version, options = {}) {
         empty.commands = diffCommands(agent, version, cwd, excludeProject);
     if (requested.has('skills'))
         empty.skills = diffSkills(agent, version, cwd, excludeProject);
-    if (requested.has('hooks'))
-        empty.hooks = diffHooks(agent, version, cwd);
+    const hookInventory = requested.has('hooks') ? getResourceInventory(agent, version, 'hooks', { cwd }) : undefined;
+    if (hookInventory)
+        empty.hooks = diffHooks(agent, version, cwd, hookInventory);
     // Wiring check: a hook FILE can be present and byte-identical to source (ok
     // above) yet never referenced in settings.json, so it never fires. Only
     // meaningful when hooks are in scope.
-    const hookWiring = requested.has('hooks') ? checkVersionHookWiring(agent, version) : undefined;
+    const hookWiring = hookInventory?.wiring;
     if (requested.has('rules'))
         empty.rules = diffRules(agent, version, cwd, excludeProject);
     if (requested.has('mcp'))
@@ -654,6 +655,7 @@ export function diffVersionResources(agent, version, options = {}) {
         kinds: empty,
         summary: { ok, diff, missing, extra },
         ...(hookWiring ? { hookWiring } : {}),
+        ...(hookInventory ? { hookInventory } : {}),
     };
 }
 export const DOCTOR_ALL_KINDS = ALL_KINDS;

package/dist/lib/event-stream.d.ts

@@ -36,6 +36,8 @@ export interface UnifiedQuery {
  * Read a unified, newest-first event stream. Operational events come from
  * events.ts `query()`; agent-semantic events from the activity logs, normalized
  * to the same record shape and filtered identically. `limit` caps the merged
- * result (each source is fetched up to `limit`, so the top-N is exact).
+ * result (each source is fetched up to `limit` *after* its primary filters —
+ * eventTypes for activity, eventTypes/module/bundle for ops — so the top-N is
+ * exact for those filters).
  */
 export declare function readUnifiedEvents(q?: UnifiedQuery): EventRecord[];

package/dist/lib/event-stream.js

@@ -46,7 +46,9 @@ function matches(r, q) {
  * Read a unified, newest-first event stream. Operational events come from
  * events.ts `query()`; agent-semantic events from the activity logs, normalized
  * to the same record shape and filtered identically. `limit` caps the merged
- * result (each source is fetched up to `limit`, so the top-N is exact).
+ * result (each source is fetched up to `limit` *after* its primary filters —
+ * eventTypes for activity, eventTypes/module/bundle for ops — so the top-N is
+ * exact for those filters).
  */
 export function readUnifiedEvents(q = {}) {
     // `bundle` is filtered inside query()'s scan (before its limit cutoff) so a
@@ -66,10 +68,21 @@ export function readUnifiedEvents(q = {}) {
     });
     if (q.includeActivity === false)
         return ops;
+    // Activity events always stamp module: 'activity'. A non-activity module
+    // filter can never match them — skip the activity scan entirely.
+    if (q.module != null && q.module !== 'activity')
+        return ops;
+    // Push eventTypes into the activity reader so `limit` is applied AFTER the
+    // event-type filter (readRecentActivity already does this for `events`).
+    // Without this, a rare match older than the newest-`limit` window of routine
+    // churn is silently dropped — the same class of bug as the ops-side bundle
+    // pre-filter above (RUSH-2093). Remaining filters (agent, sessionId, …) still
+    // run via matches() for fields activity.ts does not pre-filter.
     const acts = readActivityAsEventRecords({
         sinceMs: q.startDate?.getTime(),
         limit: q.limit,
         root: q.activityRoot,
+        events: q.eventTypes,
     }).filter((r) => matches(r, q));
     const merged = [...ops, ...acts].sort((a, b) => Date.parse(b.ts) - Date.parse(a.ts));
     return typeof q.limit === 'number' ? merged.slice(0, q.limit) : merged;

package/dist/lib/exec.d.ts

@@ -389,7 +389,19 @@ export declare function shouldWrapInTmux(ctx: TmuxWrapContext): boolean;
  */
 export declare function buildTmuxAgentCommand(executable: string, args: string[], env: NodeJS.ProcessEnv, opts?: {
     redactEnvValues?: boolean;
+    envFile?: string;
 }): string;
+/**
+ * Serialize the pane env to a shell-sourceable file, created 0600 and exclusively
+ * (`wx`) so it can never adopt a pre-existing file's mode or content.
+ *
+ * EVERY key goes in the file, not a curated "secret-bearing" subset: a denylist
+ * has to be updated for each new credential and is wrong the moment someone
+ * forgets, whereas routing all of it through the file makes the guarantee hold by
+ * construction. Keys are filtered to valid shell identifiers for the same reason
+ * `env` needed it — an exported function (`BASH_FUNC_x%%`) is not assignable.
+ */
+export declare function writeTmuxEnvFile(env: NodeJS.ProcessEnv, filePath: string): void;
 /**
  * Trim a raw `tmux capture-pane` dump to its last `maxLines` non-empty lines
  * (right-stripping each). Used by runInTmux to recap a fast-failed agent's

package/dist/lib/exec.js

@@ -17,7 +17,7 @@ import { isTierToken, resolveTier } from './model-tiers.js';
 import { createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { resolveActor, actorEnv } from './actor.js';
-import { getShimsDir, getHistoryDir } from './state.js';
+import { getShimsDir, getHistoryDir, getRuntimeStateDir } from './state.js';
 import { resolveCodexHome } from './codex-home.js';
 import { readCodexConfiguredModel } from './shims.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
@@ -362,6 +362,28 @@ export function buildExecEnv(options) {
         delete result.CODEX_HOME;
         delete result.COPILOT_HOME;
     }
+    else if (options.agent === 'muse') {
+        // Muse has no MUSE_CONFIG_DIR. Config is XDG-based:
+        //   $XDG_CONFIG_HOME/muse  (settings, skills, hooks, auth)
+        //   $XDG_DATA_HOME/muse    (sessions, plugins)
+        // Pin both into the version home so multi-version isolation matches
+        // Claude's CLAUDE_CONFIG_DIR / Codex's CODEX_HOME, and so Muse never
+        // resolves through the adopt-time ~/.config/muse symlink (SymlinkOrReparse).
+        const cwd = options.cwd || process.cwd();
+        const resolvedVersion = options.version ?? resolveVersion('muse', cwd);
+        const version = options.version
+            ? resolvedVersion
+            : (resolvedVersion && isVersionInstalled('muse', resolvedVersion) ? resolvedVersion : null);
+        if (version) {
+            const versionHome = getVersionHomePath('muse', version);
+            result.XDG_CONFIG_HOME = path.join(versionHome, '.config');
+            result.XDG_DATA_HOME = path.join(versionHome, '.local', 'share');
+        }
+        delete result.CLAUDE_CONFIG_DIR;
+        delete result.CODEX_HOME;
+        delete result.COPILOT_HOME;
+        delete result.KIMI_CODE_HOME;
+    }
     else {
         delete result.CLAUDE_CONFIG_DIR;
         delete result.CODEX_HOME;
@@ -1167,13 +1189,53 @@ export function shouldWrapInTmux(ctx) {
  * real values; the stored/informational copy uses the redacted form (RUSH-1758).
  */
 export function buildTmuxAgentCommand(executable, args, env, opts = {}) {
+    const agentCmd = [executable, ...args].map(shellQuote).join(' ');
+    // envFile: source the values instead of inlining them, so no VALUE ever lands
+    // in the pane's argv. `exec env K=V …` put every resolved secret into the
+    // process table, readable by any process of this user — on one fleet box six
+    // live processes carried the secrets-store master passphrase, which decrypts
+    // every file-backed bundle including the Claude OAuth tokens (RUSH-2100).
+    // `set -a` exports what the file assigns; the file is unlinked before `exec`,
+    // so it exists only for the sourcing itself. A missing file aborts the pane
+    // rather than silently launching with a half-built env.
+    if (opts.envFile) {
+        const f = shellQuote(opts.envFile);
+        // Remove the file whether or not sourcing succeeds — a bare `. f || exit 1`
+        // strands the plaintext env (incl. the secrets-store master passphrase) on
+        // disk on any source failure, worse than the argv leak this replaces
+        // (RUSH-2100). Capture the source rc, unlink, then honor it.
+        return `set -a; . ${f}; __agents_rc=$?; set +a; rm -f ${f}; [ "$__agents_rc" -eq 0 ] || exit 1; exec ${agentCmd}`;
+    }
     const envPrefix = Object.entries(env)
         .filter(([k, v]) => v !== undefined && EXEC_ENV_KEY_PATTERN.test(k))
         .map(([k, v]) => `${k}=${opts.redactEnvValues ? '<redacted>' : shellQuote(String(v))}`)
         .join(' ');
-    const agentCmd = [executable, ...args].map(shellQuote).join(' ');
     return `exec env ${envPrefix} ${agentCmd}`;
 }
+/**
+ * Serialize the pane env to a shell-sourceable file, created 0600 and exclusively
+ * (`wx`) so it can never adopt a pre-existing file's mode or content.
+ *
+ * EVERY key goes in the file, not a curated "secret-bearing" subset: a denylist
+ * has to be updated for each new credential and is wrong the moment someone
+ * forgets, whereas routing all of it through the file makes the guarantee hold by
+ * construction. Keys are filtered to valid shell identifiers for the same reason
+ * `env` needed it — an exported function (`BASH_FUNC_x%%`) is not assignable.
+ */
+export function writeTmuxEnvFile(env, filePath) {
+    const body = Object.entries(env)
+        .filter(([k, v]) => v !== undefined && EXEC_ENV_KEY_PATTERN.test(k))
+        .map(([k, v]) => `${k}=${shellQuote(String(v))}`)
+        .join('\n');
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const fd = fs.openSync(filePath, 'wx', 0o600);
+    try {
+        fs.writeSync(fd, `${body}\n`);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 /**
  * Trim a raw `tmux capture-pane` dump to its last `maxLines` non-empty lines
  * (right-stripping each). Used by runInTmux to recap a fast-failed agent's
@@ -1231,15 +1293,32 @@ async function runInTmux(options, executable, args) {
     // SessionStart learns some harness IDs only after launch. Carry the wrapper
     // name into that hook so it can bind both identities durably.
     const execEnv = { ...buildExecEnv(options), AGENT_TMUX_SESSION_NAME: name };
-    // Launch with the real env (secret VALUES materialized into the pane); persist
-    // only a value-redacted copy in SessionMeta.cmd so resolved secrets never hit
-    // disk via the informational cmd field (RUSH-1758).
-    const cmd = buildTmuxAgentCommand(executable, args, execEnv);
+    // The pane sources its env from a 0600 file it unlinks before exec, so no
+    // resolved secret VALUE reaches the process table (RUSH-2100). SessionMeta.cmd
+    // keeps the value-redacted inline form — the human-readable record of what ran,
+    // which never carried real values anyway (RUSH-1758).
+    const envFile = path.join(getRuntimeStateDir(), 'tmux-env', `${name}-${randomUUID().slice(0, 8)}.env`);
+    writeTmuxEnvFile(execEnv, envFile);
+    const cmd = buildTmuxAgentCommand(executable, args, execEnv, { envFile });
     const metaCmd = buildTmuxAgentCommand(executable, args, execEnv, { redactEnvValues: true });
     const labels = { agent: options.agent };
     if (options.sessionId)
         labels.sessionId = options.sessionId;
-    const meta = await createSession({ name, cmd, metaCmd, cwd, socket, source: 'cli', labels });
+    // Only a launched pane sources-and-unlinks the env file. If createSession
+    // throws, the pane never runs, so the resolved secrets (incl. the master
+    // passphrase) would linger on disk — remove it on that failure path
+    // (RUSH-2100). On success the detached pane owns the unlink.
+    let meta;
+    try {
+        meta = await createSession({ name, cmd, metaCmd, cwd, socket, source: 'cli', labels });
+    }
+    catch (err) {
+        try {
+            fs.rmSync(envFile, { force: true });
+        }
+        catch { /* best-effort */ }
+        throw err;
+    }
     const pane = meta.pane;
     if (options.sessionId)
         writeSessionAliasRecord(options.sessionId, name);
@@ -1317,7 +1396,7 @@ async function runInTmux(options, executable, args) {
     };
     // The agent could exit before we attach (fast failure). Don't attach to an
     // already-dead pane — surface its output + status directly and tear down.
-    const before = pane ? await paneExitStatus(pane, socket) : { dead: false };
+    const before = pane ? await paneExitStatus(pane, socket) : { found: false, dead: false, status: undefined };
     if (before.dead) {
         // F2 (RUSH-2185 / EXEC-23a): for interactive runs, ALWAYS recap — a clean
         // exit-0 before attach means the harness has no interactive REPL and the
@@ -1343,7 +1422,7 @@ async function runInTmux(options, executable, args) {
             return false;
         }
     };
-    const after = pane ? await paneExitStatus(pane, socket) : { dead: false };
+    const after = pane ? await paneExitStatus(pane, socket) : { found: false, dead: false, status: undefined };
     if (after.dead) {
         // Nonzero exit after attach → the agent crashed rather than the user
         // detaching cleanly (a clean detach leaves the pane ALIVE, handled below).

package/dist/lib/hooks/cache.js

@@ -463,6 +463,9 @@ except Exception: pass' 2>/dev/null || true)"
     ;;
 esac
 CACHE_FILE="$CACHE_DIR/$HOOK_NAME$cache_suffix.out"
+# Failure sentinel: touched on bg-refresh failure; mtime drives the backoff window.
+FAIL_FILE="$CACHE_FILE.fail"
+BACKOFF_SEC=60
 
 # Monotonic-ish nanosecond timer (macOS \`date\` has no %N).
 now_ns() { "$PY" -c 'import time; print(int(time.time()*1e9))'; }
@@ -491,9 +494,38 @@ if [ "$CACHE_STATUS" = miss ]; then
     # Stale-while-revalidate: serve stale immediately, refresh in detached child.
     cat "$CACHE_FILE"
     CACHE_STATUS=stale-prefetch
-    tmp="$CACHE_FILE.new.$$"
-    ( printf '%s' "$STDIN_PAYLOAD" | "$SOURCE" >"$tmp" 2>/dev/null && mv -f "$tmp" "$CACHE_FILE" || rm -f "$tmp" ) >/dev/null 2>&1 &
-    disown 2>/dev/null || true
+    # Fix 2: backoff — skip bg refresh if last attempt failed within BACKOFF_SEC.
+    _in_backoff=0
+    if [ -f "$FAIL_FILE" ]; then
+      _fail_mtime=$("$PY" -c 'import os,sys; print(int(os.path.getmtime(sys.argv[1])))' "$FAIL_FILE" 2>/dev/null || echo 0)
+      _now_s=$(date +%s)
+      _fail_age=$((_now_s - \${_fail_mtime:-0}))
+      [ "$_fail_age" -lt "$BACKOFF_SEC" ] && _in_backoff=1
+    fi
+    if [ "$_in_backoff" -eq 0 ]; then
+      # Fix 1: lockdir — only one background refresh runs at a time.
+      LOCK_DIR="$CACHE_FILE.bg.lck"
+      if mkdir "$LOCK_DIR" 2>/dev/null; then
+        tmp="$CACHE_FILE.new.$$"
+        # Fix 3: background subshell captures and logs its own real exit code.
+        (
+          trap 'rm -rf "$LOCK_DIR"' EXIT
+          _bg_exit=0
+          if printf '%s' "$STDIN_PAYLOAD" | "$SOURCE" >"$tmp" 2>/dev/null; then
+            mv -f "$tmp" "$CACHE_FILE" && rm -f "$FAIL_FILE"
+          else
+            _bg_exit=$?
+            rm -f "$tmp"
+            touch "$FAIL_FILE"
+          fi
+          _bg_ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+          _bg_log_file="$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl"
+          printf '{"ts":"%s","event":"hook.cache.refresh","hook":"%s","cache":"bg-refresh","exit":%d}\\n' \\
+            "$_bg_ts" "$HOOK_NAME" "$_bg_exit" >>"$_bg_log_file" 2>/dev/null || true
+        ) >/dev/null 2>&1 &
+        disown 2>/dev/null || true
+      fi
+    fi
   else
     # Synchronous fetch + cache.
     tmp="$CACHE_FILE.new.$$"
@@ -501,6 +533,7 @@ if [ "$CACHE_STATUS" = miss ]; then
       EXIT=0
       cat "$tmp"
       mv -f "$tmp" "$CACHE_FILE"
+      rm -f "$FAIL_FILE"
     else
       EXIT=$?
       rm -f "$tmp"

package/dist/lib/hooks.d.ts

@@ -73,6 +73,14 @@ export declare function hookExists(agentId: AgentId, hookName: string): boolean;
  * Compares both script file and data file (if present).
  */
 export declare function hookContentMatches(agentId: AgentId, hookName: string, sourceEntry: HookEntry): boolean;
+/**
+ * Hooks dir for an agent under an arbitrary home (version home or effective
+ * home). An agent whose `hooksDir` is configured absolute under `$HOME` (grok,
+ * kimi) must be translated to config-dir-relative first — a raw `path.join`
+ * would embed the absolute path as a relative segment and produce a hybrid
+ * path that never exists (RUSH-2237).
+ */
+export declare function getHooksDirInHome(agentId: AgentId, home: string): string;
 export declare function listInstalledHooksWithScope(agentId: AgentId, cwd?: string, options?: {
     home?: string;
 }): InstalledHook[];
@@ -99,7 +107,7 @@ export interface HookWiringIssue {
      *  group). Real hooks scope by matcher — ask-user-question-guard=AskUserQuestion,
      *  user-message-guard=Bash — so wiring is verified per (event, matcher). */
     matcher: string;
-    /** The command settings.json should reference for this hook under `event`. */
+    /** The command the harness-native config should reference under `event`. */
     command: string;
 }
 export interface HookWiringReport {
@@ -109,18 +117,22 @@ export interface HookWiringReport {
     settingsPath?: string;
     /** Number of hooks the manifest says should be wired for this version. */
     expected?: number;
-    /** settings.json does not exist — nothing declared can be wired. */
+    /** Native hook config does not exist — nothing declared can be wired. */
     settingsMissing?: boolean;
-    /** settings.json exists but is not valid JSON — wiring can't be verified. */
+    /** Native hook config cannot be parsed — wiring can't be verified. */
     settingsUnparseable?: boolean;
     /** Hooks whose file is present/resolvable but that are NOT referenced in the
-     *  event array settings.json should carry them in. */
+     *  native event group/entry should carry them in. */
     unwired: HookWiringIssue[];
+    /** Expected hooks that ARE referenced in native config (expected − unwired).
+     *  Empty whenever wiring cannot be verified (unsupported family, missing or
+     *  unparseable settings). */
+    wired: HookWiringIssue[];
 }
 /**
- * Verify that every hook the manifest says should be wired for a (claude|droid)
- * version is actually REFERENCED in that version's native settings.json — not
- * merely present as a file on disk.
+ * Verify that every hook the manifest says should be wired is actually
+ * referenced in that version's harness-native config, not merely present as a
+ * file on disk.
  *
  * `agents doctor` compares hook FILES against source (see diffHooks in
  * doctor-diff.ts) but never checks the wiring, so a hook whose script is

package/dist/lib/hooks.js

@@ -673,6 +673,20 @@ export function hookContentMatches(agentId, hookName, sourceEntry) {
         return false;
     }
 }
+/**
+ * Hooks dir for an agent under an arbitrary home (version home or effective
+ * home). An agent whose `hooksDir` is configured absolute under `$HOME` (grok,
+ * kimi) must be translated to config-dir-relative first — a raw `path.join`
+ * would embed the absolute path as a relative segment and produce a hybrid
+ * path that never exists (RUSH-2237).
+ */
+export function getHooksDirInHome(agentId, home) {
+    const config = AGENTS[agentId];
+    const hooksDir = path.isAbsolute(config.hooksDir)
+        ? path.relative(config.configDir, config.hooksDir)
+        : config.hooksDir;
+    return path.join(home, agentConfigDirName(agentId), hooksDir);
+}
 export function listInstalledHooksWithScope(agentId, cwd = process.cwd(), options) {
     const agent = AGENTS[agentId];
     if (!agent.supportsHooks) {
@@ -702,7 +716,7 @@ export function listInstalledHooksWithScope(agentId, cwd = process.cwd(), option
     }
     // User-scoped hooks (version-aware when home is provided)
     const home = options?.home || getEffectiveHome(agentId);
-    const userDir = path.join(home, agentConfigDirName(agentId), agent.hooksDir);
+    const userDir = getHooksDirInHome(agentId, home);
     const userHooks = listHookEntriesFromDir(userDir);
     for (const hook of userHooks) {
         addHook(hook, 'user', agentId);
@@ -740,8 +754,7 @@ export async function installHooks(source, agents, options = {}) {
  * Path to the hooks dir of a specific version home (not the active one).
  */
 export function getVersionHooksDir(agent, version) {
-    const home = getVersionHomePath(agent, version);
-    return path.join(home, agentConfigDirName(agent), AGENTS[agent].hooksDir);
+    return getHooksDirInHome(agent, getVersionHomePath(agent, version));
 }
 /**
  * List hook entries in a specific version home.
@@ -749,20 +762,20 @@ export function getVersionHooksDir(agent, version) {
 export function listHooksInVersionHome(agent, version) {
     return listHookEntriesFromDir(getVersionHooksDir(agent, version));
 }
-// ─── wiring inspection (settings.json family: claude, droid) ──────────────────
+// ─── wiring inspection ────────────────────────────────────────────────────────
 /**
- * Agents whose hooks register through {@link registerHooksForClaude} — a native
- * settings.json shaped `hooks[event] = [{ matcher, hooks: [{ command }] }]`, with
- * no event renaming. These are the only agents this read-only wiring inspector
- * understands; every other harness uses a divergent config format and/or event
- * map (Gemini/Antigravity settings.json variants, Codex config.toml, the OpenCode
- * plugin, …), so it reports them unsupported rather than risk a false verdict.
+ * Native hook-config families understood by this read-only inspector. Claude,
+ * Droid, and Muse share settings.json; Grok uses the same grouped event shape
+ * in hooks/hooks.json; Kimi stores one hook per [[hooks]] config.toml table.
+ * Other harnesses report unsupported rather than risk a false verdict.
  */
 const SETTINGS_JSON_HOOK_FAMILY = ['claude', 'droid', 'muse'];
+const HOOKS_JSON_HOOK_FAMILY = ['grok'];
+const TOML_ARRAY_HOOK_FAMILY = ['kimi'];
 /**
- * Verify that every hook the manifest says should be wired for a (claude|droid)
- * version is actually REFERENCED in that version's native settings.json — not
- * merely present as a file on disk.
+ * Verify that every hook the manifest says should be wired is actually
+ * referenced in that version's harness-native config, not merely present as a
+ * file on disk.
  *
  * `agents doctor` compares hook FILES against source (see diffHooks in
  * doctor-diff.ts) but never checks the wiring, so a hook whose script is
@@ -774,11 +787,18 @@ const SETTINGS_JSON_HOOK_FAMILY = ['claude', 'droid', 'muse'];
  * resolveHookCommand performs, so it never mutates the version home.
  */
 export function checkVersionHookWiring(agent, version) {
-    if (!AGENTS[agent].supportsHooks || !SETTINGS_JSON_HOOK_FAMILY.includes(agent)) {
-        return { supported: false, unwired: [] };
+    if (!AGENTS[agent].supportsHooks ||
+        (!SETTINGS_JSON_HOOK_FAMILY.includes(agent) &&
+            !HOOKS_JSON_HOOK_FAMILY.includes(agent) &&
+            !TOML_ARRAY_HOOK_FAMILY.includes(agent))) {
+        return { supported: false, unwired: [], wired: [] };
     }
     const versionHome = getVersionHomePath(agent, version);
-    const settingsPath = path.join(versionHome, agentConfigDirName(agent), 'settings.json');
+    const settingsPath = HOOKS_JSON_HOOK_FAMILY.includes(agent)
+        ? path.join(versionHome, '.grok', 'hooks', 'hooks.json')
+        : TOML_ARRAY_HOOK_FAMILY.includes(agent)
+            ? path.join(versionHome, '.kimi-code', 'config.toml')
+            : path.join(versionHome, agentConfigDirName(agent), 'settings.json');
     const localHooksDir = getVersionHooksDir(agent, version);
     // Resolve ONLY to a script that was actually synced for THIS agent+version: the
     // copy in the version home hooks dir, or an absolute subrule-dir path (those are
@@ -815,11 +835,17 @@ export function checkVersionHookWiring(agent, version) {
         const command = expectedCommand(name, hookDef);
         if (!command)
             continue; // script unresolved — a file gap, reported by diffHooks
-        // Mirror registerHooksForClaude: a hook registers under the matcher group
-        // `hookDef.matcher || ''` for each of its events.
-        const matcher = hookDef.matcher || '';
-        for (const event of hookDef.events)
-            expected.push({ name, event, matcher, command });
+        for (const event of hookDef.events) {
+            if (HOOKS_JSON_HOOK_FAMILY.includes(agent)) {
+                const matcher = GROK_MATCHER_EVENTS.has(event)
+                    ? (GROK_MATCHER_ALIASES[hookDef.matcher || ''] ?? hookDef.matcher ?? '')
+                    : '';
+                expected.push({ name, event, matcher, command });
+            }
+            else {
+                expected.push({ name, event, matcher: hookDef.matcher || '', command });
+            }
+        }
     }
     if (!fs.existsSync(settingsPath)) {
         return {
@@ -828,11 +854,15 @@ export function checkVersionHookWiring(agent, version) {
             expected: expected.length,
             settingsMissing: expected.length > 0,
             unwired: [],
+            wired: [],
         };
     }
     let config;
     try {
-        config = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+        const raw = fs.readFileSync(settingsPath, 'utf-8');
+        config = TOML_ARRAY_HOOK_FAMILY.includes(agent)
+            ? TOML.parse(raw)
+            : JSON.parse(raw);
     }
     catch {
         return {
@@ -841,6 +871,7 @@ export function checkVersionHookWiring(agent, version) {
             expected: expected.length,
             settingsUnparseable: true,
             unwired: [],
+            wired: [],
         };
     }
     // Command strings actually referenced, keyed by (event, matcher) — a hook wired
@@ -848,30 +879,49 @@ export function checkVersionHookWiring(agent, version) {
     // not just by event.
     const wiredByGroup = new Map();
     const groupKey = (event, matcher) => `${event}\n${matcher}`;
-    const hooks = config.hooks && typeof config.hooks === 'object'
-        ? config.hooks
-        : {};
-    for (const [event, groups] of Object.entries(hooks)) {
-        if (!Array.isArray(groups))
-            continue;
-        for (const group of groups) {
-            if (!group || !Array.isArray(group.hooks))
+    if (TOML_ARRAY_HOOK_FAMILY.includes(agent)) {
+        const hooks = Array.isArray(config.hooks) ? config.hooks : [];
+        for (const hook of hooks) {
+            if (typeof hook.event !== 'string' || typeof hook.command !== 'string')
                 continue;
-            const matcher = typeof group.matcher === 'string' ? group.matcher : '';
-            const key = groupKey(event, matcher);
+            const matcher = typeof hook.matcher === 'string' ? hook.matcher : '';
+            const key = groupKey(hook.event, matcher);
             let cmds = wiredByGroup.get(key);
             if (!cmds) {
                 cmds = new Set();
                 wiredByGroup.set(key, cmds);
             }
-            for (const h of group.hooks) {
-                if (h && typeof h.command === 'string')
-                    cmds.add(h.command);
+            cmds.add(hook.command);
+        }
+    }
+    else {
+        const hooks = config.hooks && typeof config.hooks === 'object'
+            ? config.hooks
+            : {};
+        for (const [event, groups] of Object.entries(hooks)) {
+            if (!Array.isArray(groups))
+                continue;
+            for (const group of groups) {
+                if (!group || !Array.isArray(group.hooks))
+                    continue;
+                const matcher = typeof group.matcher === 'string' ? group.matcher : '';
+                const key = groupKey(event, matcher);
+                let cmds = wiredByGroup.get(key);
+                if (!cmds) {
+                    cmds = new Set();
+                    wiredByGroup.set(key, cmds);
+                }
+                for (const h of group.hooks) {
+                    if (h && typeof h.command === 'string')
+                        cmds.add(h.command);
+                }
             }
         }
     }
-    const unwired = expected.filter((e) => !wiredByGroup.get(groupKey(e.event, e.matcher))?.has(e.command));
-    return { supported: true, settingsPath, expected: expected.length, unwired };
+    const isWired = (entry) => wiredByGroup.get(groupKey(entry.event, entry.matcher))?.has(entry.command) ?? false;
+    const unwired = expected.filter((entry) => !isWired(entry));
+    const wired = expected.filter(isWired);
+    return { supported: true, settingsPath, expected: expected.length, unwired, wired };
 }
 /**
  * Check if a hook installed in a specific version matches central content.
@@ -1402,7 +1452,7 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     // Scripts are copied into the version home during sync — prefer that stable
     // local path so registered commands don't break when source dirs change.
     const localHooksDir = !overrideRoots
-        ? path.join(versionHome, agentConfigDirName(agentId), AGENTS[agentId].hooksDir)
+        ? getHooksDirInHome(agentId, versionHome)
         : null;
     const resolveScript = (script) => {
         // Subrule-dir hooks declare an already-absolute script path. Use it

package/dist/lib/hosts/session-index.d.ts

@@ -11,6 +11,10 @@
  * issued from, so the run appears in that project's session listing like any
  * local run. The `[host/<name>]` label mirrors the cloud path's
  * `[cloud/<status>]` convention.
+ *
+ * `machine` is the dispatch host, not this box. Both the transcript and the
+ * version-isolated harness home live there; omitting it makes the SQLite upsert
+ * infer this box from the empty file path and sends recovery to the wrong home.
  */
 import type { SessionMeta } from '../session/types.js';
 import { type HostTask } from './tasks.js';