@phnx-labs/agents-cli 1.20.4 → 1.20.6

package/dist/lib/session/discover.js

@@ -15,7 +15,7 @@ import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { getAgentsDir, getHistoryDir } from '../state.js';
 const execFileAsync = promisify(execFile);
-import { AGENTS, getCliVersion } from '../agents.js';
+import { AGENTS, agentConfigDirName, getCliVersion } from '../agents.js';
 import { walkForFiles } from '../fs-walk.js';
 import { getConfigSymlinkVersion } from '../shims.js';
 import { SESSION_AGENTS } from './types.js';
@@ -61,6 +61,7 @@ export async function discoverSessions(options) {
                     case 'openclaw': return scanOpenClawIncremental();
                     case 'rush': return scanRushIncremental(onProgress);
                     case 'hermes': return scanHermesIncremental(onProgress);
+                    case 'kimi': return scanKimiIncremental(onProgress);
                 }
             }));
         }
@@ -201,14 +202,18 @@ export function getAgentSessionDirs(agent, subdir) {
         resolved.add(key);
         dirs.push(dir);
     }
-    addDir(path.join(HOME, `.${agent}`, subdir));
+    // Config-dir name relative to home — handles nested layouts (antigravity →
+    // .gemini/antigravity-cli) and ~/.config agents (amp, goose) as well as kimi
+    // (.kimi-code). Falls back to `.${agent}` for ids not in the registry.
+    const configDirName = agent in AGENTS ? agentConfigDirName(agent) : `.${agent}`;
+    addDir(path.join(HOME, configDirName, subdir));
     for (const root of VERSIONS_ROOTS) {
         const versionsBase = path.join(root, 'versions', agent);
         if (!fs.existsSync(versionsBase))
             continue;
         try {
             for (const version of fs.readdirSync(versionsBase)) {
-                addDir(path.join(versionsBase, version, 'home', `.${agent}`, subdir));
+                addDir(path.join(versionsBase, version, 'home', configDirName, subdir));
             }
         }
         catch { /* dir unreadable */ }
@@ -1574,6 +1579,116 @@ function sumKnownNumbers(values) {
 // ---------------------------------------------------------------------------
 // Time range parsing
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Kimi
+// ---------------------------------------------------------------------------
+// Kimi stores sessions under ~/.kimi-code/sessions/<workdir_hash>/session_<uuid>/.
+// Each session has state.json (metadata) and agents/main/wire.jsonl (conversation).
+// A session_index.jsonl at ~/.kimi-code/ maps session IDs to directories.
+/** Incrementally re-scan changed Kimi session state.json files and upsert into the DB. */
+async function scanKimiIncremental(onProgress) {
+    const filePaths = [];
+    for (const sessionsDir of getAgentSessionDirs('kimi', 'sessions')) {
+        if (!fs.existsSync(sessionsDir))
+            continue;
+        let workDirNames;
+        try {
+            workDirNames = fs.readdirSync(sessionsDir);
+        }
+        catch {
+            continue;
+        }
+        for (const workDirName of workDirNames) {
+            const workDir = path.join(sessionsDir, workDirName);
+            const stat = safeStatSync(workDir);
+            if (!stat?.isDirectory())
+                continue;
+            let sessionNames;
+            try {
+                sessionNames = fs.readdirSync(workDir);
+            }
+            catch {
+                continue;
+            }
+            for (const sessionName of sessionNames) {
+                if (!sessionName.startsWith('session_'))
+                    continue;
+                const statePath = path.join(workDir, sessionName, 'state.json');
+                if (!fs.existsSync(statePath))
+                    continue;
+                filePaths.push(statePath);
+            }
+        }
+    }
+    const changed = filterChangedFiles(filePaths);
+    if (changed.length === 0)
+        return;
+    onProgress?.({ agent: 'kimi', parsed: 0, total: changed.length });
+    const scanEntries = [];
+    const touched = [];
+    const seen = new Set();
+    let parsed = 0;
+    for (const { filePath, scan } of changed) {
+        try {
+            const result = readKimiMeta(filePath);
+            if (result && !seen.has(result.meta.id)) {
+                seen.add(result.meta.id);
+                scanEntries.push({ meta: result.meta, content: result.content, scan });
+            }
+            else {
+                touched.push({ filePath, scan });
+            }
+        }
+        catch {
+            touched.push({ filePath, scan });
+        }
+        parsed++;
+        onProgress?.({ agent: 'kimi', parsed, total: changed.length });
+    }
+    upsertSessionsBatch(scanEntries);
+    recordScans(touched);
+}
+/** Parse a single Kimi session state.json file to extract session metadata. */
+function readKimiMeta(filePath) {
+    let state;
+    try {
+        state = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    const sessionDir = path.dirname(filePath);
+    const sessionId = path.basename(sessionDir);
+    if (!sessionId.startsWith('session_'))
+        return null;
+    const title = typeof state.title === 'string' ? state.title : undefined;
+    const lastPrompt = typeof state.lastPrompt === 'string' ? state.lastPrompt : undefined;
+    const topic = title || lastPrompt || undefined;
+    const createdAt = typeof state.createdAt === 'string' ? state.createdAt : undefined;
+    const updatedAt = typeof state.updatedAt === 'string' ? state.updatedAt : undefined;
+    const timestamp = updatedAt || createdAt;
+    const shortId = sessionId.replace(/^session_/, '').slice(0, 8);
+    // Try to infer project from session directory path
+    // ~/.kimi-code/sessions/<workdir_hash>/session_<uuid>/
+    const workDirName = path.basename(path.dirname(sessionDir));
+    let project;
+    if (workDirName.startsWith('wd_')) {
+        const parts = workDirName.slice(3).split('_');
+        if (parts.length >= 2) {
+            project = parts.slice(0, -1).join('/');
+        }
+    }
+    const meta = {
+        id: sessionId,
+        shortId,
+        agent: 'kimi',
+        timestamp,
+        project,
+        filePath,
+        topic,
+    };
+    return { meta, content: lastPrompt || '' };
+}
 /** Parse a time filter string (relative like '7d' or ISO timestamp) into epoch milliseconds. */
 export function parseTimeFilter(input) {
     const relativeMatch = input.match(/^(\d+)([mhdw])$/i);

package/dist/lib/session/parse.js

@@ -105,6 +105,9 @@ export function parseSession(filePath, agent) {
         case 'hermes':
             events = parseHermes(filePath);
             break;
+        case 'kimi':
+            events = [];
+            break; // Kimi event parsing not implemented yet — discover.ts builds metadata only
     }
     // Chokepoint: every string field that originated in an untrusted session
     // file gets stripped of terminal escapes here, so renderers downstream can

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

@@ -7,7 +7,7 @@
  * speaks these types.
  */
 /** Agents that store session data on disk and can be discovered by `agents sessions`. */
-export type SessionAgentId = 'claude' | 'codex' | 'gemini' | 'opencode' | 'openclaw' | 'rush' | 'hermes' | 'grok';
+export type SessionAgentId = 'claude' | 'codex' | 'gemini' | 'opencode' | 'openclaw' | 'rush' | 'hermes' | 'grok' | 'kimi';
 /** All agents with session discovery support, in display order. */
 export declare const SESSION_AGENTS: SessionAgentId[];
 /** A single normalized event within a session (message, tool call, thinking, etc.). */

package/dist/lib/session/types.js

@@ -7,4 +7,4 @@
  * speaks these types.
  */
 /** All agents with session discovery support, in display order. */
-export const SESSION_AGENTS = ['claude', 'codex', 'gemini', 'opencode', 'openclaw', 'rush', 'hermes', 'grok'];
+export const SESSION_AGENTS = ['claude', 'codex', 'gemini', 'opencode', 'openclaw', 'rush', 'hermes', 'grok', 'kimi'];

package/dist/lib/shims.d.ts

@@ -62,8 +62,22 @@ export interface ConflictInfo {
  *   v15 — remove foreground resource sync / rules refresh from launch shims.
  *         Version homes are reconciled by agents-cli management commands; the
  *         shim hot path only resolves a version and execs the agent binary.
+ *   v16 — re-introduce project-scoped compile to the shim hot path via
+ *         `agents sync --launch`. This stays fast (filesystem-only): compiles
+ *         project rules, mirrors workspace resources, and synthesizes the
+ *         scoped plugin marketplaces (agents-cli/agents-system/extras-<alias>/
+ *         agents-project). Version-home reconciliation stays out of the hot
+ *         path — management commands still own that.
+ *   v17 — bash-side skip-fast sentinel under ~/.agents/.cache/launch-sync/.
+ *         When the sentinel mtime is newer than every source dir, exec the
+ *         agent binary directly without spawning node. Cuts steady-state
+ *         hot-path latency from ~680ms (node startup + module init) to ~11ms
+ *         (a few stat calls). Node writes the sentinel after each successful
+ *         sync. Documented limitation: POSIX dir mtime only updates on
+ *         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 = 15;
+export declare const SHIM_SCHEMA_VERSION = 17;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -223,14 +237,9 @@ export declare function getPathShadowingExecutable(agent: AgentId): string | nul
 export declare function removeLegacyUserShim(agent: AgentId, overrides?: {
     homeDir?: string;
 }): boolean;
-/**
- * Check if the agent's CLI command is shadowed by a shell alias.
- *
- * Shell aliases live in the user's session and aren't visible from a Node.js
- * child process. We do a best-effort scan of common RC files for `alias
- * <command>=` patterns. Returns false when detection is inconclusive.
- */
-export declare function hasAliasShadowingShim(agent: AgentId): boolean;
+export declare function hasAliasShadowingShim(agent: AgentId, overrides?: {
+    homeDir?: string;
+}): boolean;
 /**
  * Check if shims directory is in PATH.
  */

package/dist/lib/shims.js

@@ -186,8 +186,22 @@ async function promptConflictStrategy(conflictInfos) {
  *   v15 — remove foreground resource sync / rules refresh from launch shims.
  *         Version homes are reconciled by agents-cli management commands; the
  *         shim hot path only resolves a version and execs the agent binary.
+ *   v16 — re-introduce project-scoped compile to the shim hot path via
+ *         `agents sync --launch`. This stays fast (filesystem-only): compiles
+ *         project rules, mirrors workspace resources, and synthesizes the
+ *         scoped plugin marketplaces (agents-cli/agents-system/extras-<alias>/
+ *         agents-project). Version-home reconciliation stays out of the hot
+ *         path — management commands still own that.
+ *   v17 — bash-side skip-fast sentinel under ~/.agents/.cache/launch-sync/.
+ *         When the sentinel mtime is newer than every source dir, exec the
+ *         agent binary directly without spawning node. Cuts steady-state
+ *         hot-path latency from ~680ms (node startup + module init) to ~11ms
+ *         (a few stat calls). Node writes the sentinel after each successful
+ *         sync. Documented limitation: POSIX dir mtime only updates on
+ *         top-level entry add/remove — deep edits to plugin contents won't
+ *         trigger auto-resync, run `agents sync` for that.
  */
-export const SHIM_SCHEMA_VERSION = 15;
+export const SHIM_SCHEMA_VERSION = 17;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -244,14 +258,19 @@ export COPILOT_HOME="$VERSION_DIR/home/${configDirName}"
 # This gives agents-cli full versioned isolation + resource sync for grok.
 export GROK_HOME="$VERSION_DIR/home/.grok"
 `
-                    : '';
+                    : agent === 'kimi'
+                        ? `
+# Kimi Code CLI honors KIMI_CODE_HOME to relocate ~/.kimi-code (config.toml,
+# mcp.json, sessions, skills, hooks). Point it at the versioned home.
+export KIMI_CODE_HOME="$VERSION_DIR/home/${configDirName}"
+`
+                        : '';
     const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
 # Shim for ${agentConfig.name}
 # ${SHIM_VERSION_MARKER} ${SHIM_SCHEMA_VERSION}
 
-AGENTS_SYSTEM_DIR="$HOME/.agents-system"
 AGENTS_USER_DIR="$HOME/.agents"
 AGENTS_BIN=${agentsBin}
 AGENT="${agent}"
@@ -262,10 +281,10 @@ if [ -z "$AGENTS_BIN" ] || [ ! -x "$AGENTS_BIN" ]; then
   exit 127
 fi
 
-# Find project agents.yaml walking up from cwd (skip $HOME/.agents-system/agents.yaml)
+# Find project agents.yaml walking up from cwd (skip $HOME/.agents/agents.yaml)
 find_project_version() {
   local dir="$PWD"
-  local user_agents_yaml="$AGENTS_SYSTEM_DIR/agents.yaml"
+  local user_agents_yaml="$AGENTS_USER_DIR/agents.yaml"
   while [ "$dir" != "/" ]; do
     local candidate="$dir/agents.yaml"
     if [ -f "$candidate" ] && [ "$candidate" != "$user_agents_yaml" ]; then
@@ -384,6 +403,16 @@ if [ "$AGENT" = "grok" ]; then
     # Last resort: whatever is on PATH (user may have installed grok globally)
     BINARY=$(command -v grok 2>/dev/null || echo "")
   fi
+# Kimi special case: binary lives in ~/.kimi-code/bin/, not node_modules.
+# We still use the agents-cli version dir purely for KIMI_CODE_HOME isolation.
+elif [ "$AGENT" = "kimi" ]; then
+  KIMI_BINARY="$HOME/.kimi-code/bin/kimi"
+  if [ -x "$KIMI_BINARY" ]; then
+    BINARY="$KIMI_BINARY"
+  else
+    # Last resort: whatever is on PATH
+    BINARY=$(command -v kimi 2>/dev/null || echo "")
+  fi
 else
   BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
 fi
@@ -451,6 +480,34 @@ fi
 
 ${managedEnv}
 
+# Project-scoped compile (rules, workspace resources, scoped plugin marketplaces).
+# Skip-fast: if a sentinel from the last sync exists and is newer than all
+# source dirs (project .agents/, user plugins, system plugins), exec the
+# agent binary directly without spawning node. Cuts steady-state hot-path
+# latency from ~680ms (node startup + agents-cli module init) to ~11ms (a
+# handful of stat calls). Never blocks launch on failure of the sync itself.
+#
+# Known limitation: POSIX dir mtime updates only on entry add/remove at that
+# level. Deep edits to existing plugin contents (e.g. editing a SKILL.md
+# inside a plugin) won't bump the parent dir's mtime — the marketplace copy
+# stays stale until \`agents sync\` runs explicitly or a top-level entry
+# changes. Advanced users hot-iterating on plugins know to run sync.
+PROJECT_SLUG=\$(printf '%s' "\$PWD" | tr / _ | tr ' ' _)
+LAUNCH_SENTINEL="\$AGENTS_USER_DIR/.cache/launch-sync/\${AGENT}@\${VERSION}@\${PROJECT_SLUG}"
+LAUNCH_SKIP=0
+if [ -f "\$LAUNCH_SENTINEL" ]; then
+  LAUNCH_SKIP=1
+  for LAUNCH_SRC in "\$PWD/.agents" "\$AGENTS_USER_DIR/plugins" "\$AGENTS_USER_DIR/.system/plugins"; do
+    if [ -e "\$LAUNCH_SRC" ] && [ "\$LAUNCH_SRC" -nt "\$LAUNCH_SENTINEL" ]; then
+      LAUNCH_SKIP=0
+      break
+    fi
+  done
+fi
+if [ "\$LAUNCH_SKIP" = "0" ]; then
+  "\$AGENTS_BIN" sync --agent "\$AGENT" --agent-version "\$VERSION" --launch --cwd "\$PWD" --quiet 2>/dev/null || true
+fi
+
 exec "$BINARY"${launchArgs} "$@"
 `;
 }
@@ -540,7 +597,13 @@ export CODEX_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${co
 # version MCP and session state are isolated.
 export COPILOT_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
-                : '';
+                : agent === 'kimi'
+                    ? `
+# Kimi Code CLI honors KIMI_CODE_HOME to relocate ~/.kimi-code (config.toml,
+# mcp.json, sessions, skills, hooks). Point direct aliases at the versioned home.
+export KIMI_CODE_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
+`
+                    : '';
     const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
@@ -754,7 +817,7 @@ export async function switchConfigSymlink(agent, version) {
             // Different target - update it
             fs.unlinkSync(configPath);
             fs.mkdirSync(path.dirname(configPath), { recursive: true });
-            fs.symlinkSync(versionConfigPath, configPath);
+            fs.symlinkSync(versionConfigPath, configPath, process.platform === 'win32' ? 'junction' : undefined);
             return { success: true };
         }
         else if (stat.isDirectory()) {
@@ -766,8 +829,25 @@ export async function switchConfigSymlink(agent, version) {
             const finalBackupPath = path.join(agentBackupDir, String(timestamp));
             fs.mkdirSync(agentBackupDir, { recursive: true });
             fs.renameSync(configPath, finalBackupPath);
+            // Session JSONLs that lived under the old configPath have just moved to
+            // finalBackupPath on disk. Rewrite any DB rows pointing at the old prefix
+            // so querySessions stops returning phantom rows (issue #136). The
+            // discoverer at src/lib/session/discover.ts already scans backup dirs, so
+            // future indexer runs will find the new files — this just keeps the
+            // existing rows valid in the meantime.
+            //
+            // Dynamic import so loading shims.ts doesn't transitively open the
+            // sessions DB — many tests partially mock state.js and would break.
+            try {
+                const { updateSessionFilePaths } = await import('./session/db.js');
+                updateSessionFilePaths(configPath, finalBackupPath);
+            }
+            catch (err) {
+                console.error(`Warning: failed to update session file_paths after backing up ${configPath}: ` +
+                    `${err.message}. Stale rows may appear in session listings until the next scan.`);
+            }
             // Create symlink (parent already exists since the dir we just moved was here)
-            fs.symlinkSync(versionConfigPath, configPath);
+            fs.symlinkSync(versionConfigPath, configPath, process.platform === 'win32' ? 'junction' : undefined);
             return { success: true, backupPath: finalBackupPath };
         }
         else {
@@ -780,7 +860,7 @@ export async function switchConfigSymlink(agent, version) {
             // For nested layouts (e.g., ~/.gemini/antigravity-cli) the parent dir
             // may also be missing if the parent agent (Gemini) is not installed.
             fs.mkdirSync(path.dirname(configPath), { recursive: true });
-            fs.symlinkSync(versionConfigPath, configPath);
+            fs.symlinkSync(versionConfigPath, configPath, process.platform === 'win32' ? 'junction' : undefined);
             return { success: true };
         }
         return { success: false, error: err.message };
@@ -1251,23 +1331,53 @@ export function removeLegacyUserShim(agent, overrides) {
  * Shell aliases live in the user's session and aren't visible from a Node.js
  * child process. We do a best-effort scan of common RC files for `alias
  * <command>=` patterns. Returns false when detection is inconclusive.
+ *
+ * Tracks the LAST `alias` / `unalias` action for this command per rc file —
+ * a trailing `unalias codex` cancels an earlier `alias codex=...`, and
+ * `unalias` can name multiple commands on one line. Without this, an
+ * `alias` line elsewhere in the file would surface as a false positive
+ * (e.g. seen in zshrc setups that conditionally clear an alias later).
  */
-export function hasAliasShadowingShim(agent) {
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Walk rc lines in order; a later `unalias` clears an earlier `alias`. */
+function isAliasActiveInRcContent(content, cliCommand) {
+    let active = false;
+    const aliasPattern = new RegExp(`^\\s*alias\\s+${escapeRegex(cliCommand)}\\s*=`);
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        if (aliasPattern.test(line)) {
+            active = true;
+            continue;
+        }
+        const unaliasMatch = trimmed.match(/^unalias\s+(.+)$/);
+        if (!unaliasMatch)
+            continue;
+        const tokens = unaliasMatch[1].split(/\s+/).filter((token) => !token.startsWith('-'));
+        if (tokens.includes(cliCommand)) {
+            active = false;
+        }
+    }
+    return active;
+}
+export function hasAliasShadowingShim(agent, overrides) {
     const cliCommand = AGENTS[agent].cliCommand;
-    const HOME = os.homedir();
+    const homeDir = overrides?.homeDir ?? os.homedir();
     const rcFiles = [
-        path.join(HOME, '.zshrc'),
-        path.join(HOME, '.bashrc'),
-        path.join(HOME, '.bash_profile'),
-        path.join(HOME, '.profile'),
+        path.join(homeDir, '.zshrc'),
+        path.join(homeDir, '.bashrc'),
+        path.join(homeDir, '.bash_profile'),
+        path.join(homeDir, '.profile'),
     ];
-    const pattern = new RegExp(`^\\s*alias\\s+${cliCommand}\\s*=`, 'm');
     for (const rcFile of rcFiles) {
         try {
             if (!fs.existsSync(rcFile))
                 continue;
             const content = fs.readFileSync(rcFile, 'utf-8');
-            if (pattern.test(content))
+            if (isAliasActiveInRcContent(content, cliCommand))
                 return true;
         }
         catch {
@@ -1303,6 +1413,7 @@ function isShimPathCommandLine(line, shimsDir) {
     const markerRegexes = exactMarkers.map((marker) => new RegExp(`${escapeRegex(marker)}(?=$|[:\\s])`));
     const suffixRegexes = [
         /\/\.agents-system\/shims(?=$|[:\s])/,
+        /\/\.agents\/\.cache\/shims(?=$|[:\s])/,
         /\/\.agents\/shims(?=$|[:\s])/,
     ];
     const touchesShimPath = [...markerRegexes, ...suffixRegexes].some((pattern) => pattern.test(normalized));
@@ -1364,10 +1475,10 @@ export function getPathSetupInstructions() {
         return `Add to ~/.config/fish/config.fish:
   fish_add_path ${shimsDir}`;
     }
-    return `Add to ~/${rcFile} (AFTER any nvm/node setup):
+    return `Add to the end of ~/${rcFile} (after any nvm/node setup and agent installers):
   export PATH="${shimsDir}:$PATH"
 
-IMPORTANT: Shims must come FIRST in PATH to override global installs.
+IMPORTANT: Shims must be the last PATH prepend in your shell config to override global installs.
 
 Then restart your shell or run:
   source ~/${rcFile}`;
@@ -1398,25 +1509,6 @@ export function addShimsToPath(overrides) {
         exportBlock = `# agents-cli: version-managed agent CLIs\nexport PATH="${shimsDir}:$PATH"\n`;
     }
     const contentWithoutShimLines = stripShimPathLines(content, shimsDir);
-    // Find insertion point - AFTER node/nvm/fnm setup if present, otherwise append.
-    const insertAfterPatterns = [
-        /^export NVM_DIR=/m,
-        /^source.*nvm/m,
-        /^\[ -s.*nvm/m,
-        /^eval.*fnm/m,
-        /^export PATH.*node/m,
-        /^export PATH.*npm/m,
-    ];
-    let insertIndex = -1;
-    const lines = contentWithoutShimLines.split('\n');
-    let offset = 0;
-    for (const line of lines) {
-        const lineWithNewline = `${line}\n`;
-        if (insertAfterPatterns.some((pattern) => pattern.test(line))) {
-            insertIndex = offset + lineWithNewline.length;
-        }
-        offset += lineWithNewline.length;
-    }
     // Write the updated content
     try {
         // Ensure parent directories exist (especially for fish: ~/.config/fish/)
@@ -1424,18 +1516,9 @@ export function addShimsToPath(overrides) {
         if (!fs.existsSync(rcDir)) {
             fs.mkdirSync(rcDir, { recursive: true });
         }
-        let newContent;
-        if (insertIndex >= 0) {
-            // Insert after the last node/nvm/fnm-related line so our prepend wins.
-            const before = contentWithoutShimLines.slice(0, insertIndex);
-            const separator = before.length > 0 && !before.endsWith('\n\n') ? '\n' : '';
-            newContent = before + separator + exportBlock + contentWithoutShimLines.slice(insertIndex);
-        }
-        else {
-            // Append to end
-            const separator = contentWithoutShimLines.length > 0 && !contentWithoutShimLines.endsWith('\n') ? '\n' : '';
-            newContent = contentWithoutShimLines + separator + exportBlock;
-        }
+        // Append at EOF so later installer PATH prepends cannot shadow the shims.
+        const separator = contentWithoutShimLines.length > 0 && !contentWithoutShimLines.endsWith('\n') ? '\n' : '';
+        let newContent = contentWithoutShimLines + separator + exportBlock;
         newContent = newContent.replace(/\n{2,}$/g, '\n');
         if (newContent === content) {
             return { success: true, alreadyPresent: true, rcFile };

package/dist/lib/skills.d.ts

@@ -73,7 +73,7 @@ export declare function skillExists(agentId: AgentId, skillName: string): boolea
  */
 export declare function skillContentMatches(agentId: AgentId, skillName: string, sourcePath: string): boolean;
 /**
- * List skill names from user (~/.agents/skills/) and system (~/.agents-system/skills/) dirs.
+ * List skill names from user (~/.agents/skills/) and system (~/.agents/.system/skills/) dirs.
  * User dir takes priority; deduplication preserves first occurrence.
  */
 export declare function listCentralSkills(): string[];

package/dist/lib/skills.js

@@ -10,7 +10,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
-import { SKILLS_CAPABLE_AGENTS, ensureSkillsDir } from './agents.js';
+import { ensureSkillsDir, agentConfigDirName } from './agents.js';
+import { capableAgents, isCapable } from './capabilities.js';
 import { getUserSkillsDir, getSkillsDir as getSystemSkillsDir, getProjectAgentsDir, getEnabledExtraRepos, getTrashSkillsDir } from './state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
 import { emit } from './events.js';
@@ -27,7 +28,7 @@ export function ensureCentralSkillsDir() {
 }
 export function getAgentSkillsDir(agentId) {
     const home = getEffectiveHome(agentId);
-    return path.join(home, `.${agentId}`, 'skills');
+    return path.join(home, agentConfigDirName(agentId), 'skills');
 }
 export function getProjectSkillsDir(agentId, cwd = process.cwd()) {
     const dirs = [];
@@ -227,7 +228,7 @@ export function installSkill(sourcePath, skillName, agents, method = 'symlink')
     }
     // Symlink to each agent
     for (const agentId of agents) {
-        if (!SKILLS_CAPABLE_AGENTS.includes(agentId)) {
+        if (!isCapable(agentId, 'skills')) {
             continue;
         }
         ensureSkillsDir(agentId);
@@ -328,7 +329,7 @@ export function skillContentMatches(agentId, skillName, sourcePath) {
     }
 }
 /**
- * List skill names from user (~/.agents/skills/) and system (~/.agents-system/skills/) dirs.
+ * List skill names from user (~/.agents/skills/) and system (~/.agents/.system/skills/) dirs.
  * User dir takes priority; deduplication preserves first occurrence.
  */
 export function listCentralSkills() {
@@ -388,7 +389,7 @@ export function listAllSkills() {
  */
 export function getVersionSkillsDir(agent, version) {
     const home = getVersionHomePath(agent, version);
-    return path.join(home, `.${agent}`, 'skills');
+    return path.join(home, agentConfigDirName(agent), 'skills');
 }
 /**
  * List skill names installed in a specific version home.
@@ -586,9 +587,9 @@ export function removeSkillFromVersion(agent, version, skillName) {
  */
 export function iterSkillsCapableVersions(filter) {
     const pairs = [];
-    const agents = filter?.agent ? [filter.agent] : SKILLS_CAPABLE_AGENTS;
+    const agents = filter?.agent ? [filter.agent] : capableAgents('skills');
     for (const agent of agents) {
-        if (!SKILLS_CAPABLE_AGENTS.includes(agent))
+        if (!capableAgents('skills').includes(agent))
             continue;
         const versions = listInstalledVersions(agent);
         for (const version of versions) {
@@ -606,7 +607,7 @@ export function uninstallSkill(skillName) {
         return { success: false, error: `Skill '${skillName}' not found` };
     }
     // Remove from all agents
-    for (const agentId of SKILLS_CAPABLE_AGENTS) {
+    for (const agentId of capableAgents('skills')) {
         const agentSkillPath = path.join(getAgentSkillsDir(agentId), skillName);
         if (fs.existsSync(agentSkillPath)) {
             try {
@@ -727,7 +728,7 @@ export function listInstalledSkillsWithScope(agentId, cwd = process.cwd(), optio
     }
     // User-scoped skills (version-aware when home is provided)
     const userSkillsDir = options?.home
-        ? path.join(options.home, `.${agentId}`, 'skills')
+        ? path.join(options.home, agentConfigDirName(agentId), 'skills')
         : getAgentSkillsDir(agentId);
     if (fs.existsSync(userSkillsDir)) {
         try {

package/dist/lib/staleness/detectors/commands.d.ts

@@ -0,0 +1,3 @@
+import type { AgentId } from '../../types.js';
+import type { ResourceDetector } from './types.js';
+export declare const commandsDetectors: Partial<Record<AgentId, ResourceDetector>>;

package/dist/lib/staleness/detectors/commands.js

@@ -0,0 +1,46 @@
+/**
+ * Commands detector — mirrors versions.ts:343-357. Inspects the version home,
+ * returns command names. Honors the commands-as-skills marker for grok and
+ * Codex >= 0.117.0; falls back to scanning `{agentDir}/<commandsSubdir>/` for
+ * the native path.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS, agentConfigDirName } from '../../agents.js';
+import { shouldInstallCommandAsSkill, listCommandSkillsInVersion } from '../../command-skills.js';
+import { lazyAgentMap } from '../writers/lazy-map.js';
+function buildCommandsDetector(agent) {
+    return {
+        kind: 'commands',
+        agent,
+        list({ version, versionHome }) {
+            const agentConfig = AGENTS[agent];
+            const agentDir = path.join(versionHome, agentConfigDirName(agent));
+            if (shouldInstallCommandAsSkill(agent, version)) {
+                return listCommandSkillsInVersion(agentDir);
+            }
+            const commandsDir = path.join(agentDir, agentConfig.commandsSubdir);
+            if (!fs.existsSync(commandsDir))
+                return [];
+            const ext = agentConfig.format === 'toml' ? '.toml' : '.md';
+            return fs.readdirSync(commandsDir)
+                .filter(f => f.endsWith(ext))
+                .map(f => f.replace(new RegExp(`\\${ext}$`), ''));
+        },
+    };
+}
+// Detector registration mirrors writers/commands.ts — see that file for the
+// openclaw vs grok asymmetry.
+export const commandsDetectors = lazyAgentMap(() => {
+    const m = {};
+    for (const id of Object.keys(AGENTS)) {
+        const cfg = AGENTS[id];
+        if (cfg.capabilities.commands === false && (!cfg.commandsSubdir || cfg.commandsSubdir === '') && id !== 'grok')
+            continue;
+        const hasCommands = cfg.capabilities.commands !== false;
+        const hasSkills = cfg.capabilities.skills !== false;
+        if (hasCommands || hasSkills)
+            m[id] = buildCommandsDetector(id);
+    }
+    return m;
+});