@swarmify/agents-cli 1.12.0 → 1.13.1

package/dist/lib/shims.d.ts

@@ -26,7 +26,7 @@ export declare function promptConflictStrategy(conflictInfos: ConflictInfo[]): P
  * Generate the shim script content for an agent.
  *
  * The shim resolves the version in order:
- * 1. .agents-version in cwd (walk up to root)
+ * 1. agents.yaml in project root (walk up from $PWD, skip ~/.agents/agents.yaml)
  * 2. ~/.agents/agents.yaml default
  *
  * If version is specified but not installed, auto-installs it.
@@ -34,6 +34,27 @@ export declare function promptConflictStrategy(conflictInfos: ConflictInfo[]): P
  * Config isolation is handled via symlinks:
  * ~/.{agent} -> ~/.agents/versions/{agent}/{version}/home/.{agent}/
  */
+/**
+ * Current shim schema version. Bump whenever `generateShimScript` changes
+ * in a way that requires existing on-disk shims to be regenerated (new
+ * flags, fixed argument parsing, new hooks, etc.). `isShimCurrent` reads
+ * this marker out of existing shims to decide whether to regenerate.
+ *
+ * History:
+ *   v1 — initial shim (implicit, no marker).
+ *   v2 — `--version=...` form in sync/refresh-memory calls; refresh-memory
+ *        shim hook for non-@-capable agents.
+ *   v3 — sync/refresh-memory flag renamed `--version` → `--agent-version`
+ *        so it no longer collides with commander's top-level `--version`.
+ *   v4 — project version marker changed from `.agents-version` to a
+ *        root-level `agents.yaml`; shim now skips ~/.agents/agents.yaml
+ *        when walking up for a project marker.
+ */
+export declare const SHIM_SCHEMA_VERSION = 4;
+/**
+ * Generate the full bash shim script for the given agent. The returned string
+ * is written to ~/.agents/shims/{cliCommand} and made executable.
+ */
 export declare function generateShimScript(agent: AgentId): string;
 /**
  * Create a shim for an agent.
@@ -43,11 +64,43 @@ export declare function createShim(agent: AgentId): string;
  * Remove the shim for an agent.
  */
 export declare function removeShim(agent: AgentId): boolean;
+/**
+ * Current versioned-alias schema. Bump whenever `generateVersionedAliasScript`
+ * changes in a way that requires existing on-disk aliases to be regenerated.
+ *
+ * History:
+ *   v1 — implicit (no marker); no CLAUDE_CONFIG_DIR export, so direct
+ *        `claude@X` invocations leaked into ~/.claude (the default version's
+ *        symlinked home) and `agents view` never saw the login.
+ *   v2 — emit CLAUDE_CONFIG_DIR for claude aliases so each version has its
+ *        own isolated config/OAuth slot; stamp a version marker so stale
+ *        aliases can be detected and regenerated.
+ */
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 2;
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary
  */
 export declare function generateVersionedAliasScript(agent: AgentId, version: string): string;
+/**
+ * Read the schema version of an on-disk versioned alias. Returns null if the
+ * alias doesn't exist or is a pre-v2 alias (no marker — treated as stale).
+ */
+export declare function readVersionedAliasSchemaVersion(agent: AgentId, version: string): number | null;
+/**
+ * True if the on-disk versioned alias matches the current schema version.
+ */
+export declare function isVersionedAliasCurrent(agent: AgentId, version: string): boolean;
+/**
+ * Regenerate a versioned alias if missing or stale. Mirrors ensureShimCurrent
+ * for the main shim — callers can surface a one-line notice when something
+ * was upgraded.
+ */
+export declare function ensureVersionedAliasCurrent(agent: AgentId, version: string): 'created' | 'updated' | 'current';
+/**
+ * Get the filesystem path for a versioned alias script.
+ */
+export declare function getVersionedAliasPath(agent: AgentId, version: string): string;
 /**
  * Create a versioned alias for a specific agent version.
  * e.g., claude@2.0.65
@@ -98,6 +151,34 @@ export declare function switchHomeFileSymlinks(agent: AgentId, version: string):
     switched: string[];
     errors: string[];
 };
+/**
+ * Claude reads `.claude.json` at `$CLAUDE_CONFIG_DIR/.claude.json`. Our shim
+ * points CLAUDE_CONFIG_DIR at `<ver>/home/.claude`, so Claude's real config
+ * file lives at `<ver>/home/.claude/.claude.json` (INSIDE), while
+ * `switchHomeFileSymlinks` manages `<ver>/home/.claude.json` (OUTSIDE).
+ *
+ * To keep both views consistent we make INSIDE a symlink to OUTSIDE. Claude's
+ * atomic write (`Uf6`) resolves symlinks before the tmp+rename cycle, so the
+ * symlink survives across writes and OUTSIDE remains the single source of
+ * truth that agents-cli's home-file machinery already manages.
+ *
+ * This function idempotently reconciles one version:
+ *   - INSIDE missing: create symlink -> `../.claude.json` (create OUTSIDE if needed).
+ *   - INSIDE already symlink to OUTSIDE: no-op.
+ *   - INSIDE is a real file: it's the authoritative auth state (Claude was
+ *     writing to it). Move its content to OUTSIDE (merging with OUTSIDE,
+ *     INSIDE wins for `oauthAccount`), then replace INSIDE with the symlink.
+ *   - Symlink points elsewhere: replace it.
+ */
+export declare function ensureClaudeInsideSymlink(version: string): void;
+/**
+ * Apply `ensureClaudeInsideSymlink` to every installed Claude version.
+ * Safe to call repeatedly; per-version calls are idempotent.
+ */
+export declare function ensureAllClaudeInsideSymlinks(): {
+    migrated: string[];
+    errors: string[];
+};
 /**
  * Get the current config symlink target version, if any.
  */
@@ -106,6 +187,23 @@ export declare function getConfigSymlinkVersion(agent: AgentId): string | null;
  * Check if shim exists for an agent.
  */
 export declare function shimExists(agent: AgentId): boolean;
+/**
+ * Read the schema version embedded in an existing on-disk shim. Returns
+ * `null` if the shim doesn't exist or has no version marker (pre-v2 shim).
+ */
+export declare function readShimSchemaVersion(agent: AgentId): number | null;
+/**
+ * True if the on-disk shim's schema version matches `SHIM_SCHEMA_VERSION`.
+ * False means either the shim is missing, is pre-v2 (no marker), or is an
+ * older version that needs regeneration.
+ */
+export declare function isShimCurrent(agent: AgentId): boolean;
+/**
+ * Regenerate the shim if it's missing or outdated. Returns a status describing
+ * what happened — callers can surface a one-line notice to the user ("Updated
+ * shim for codex") when appropriate.
+ */
+export declare function ensureShimCurrent(agent: AgentId): 'created' | 'updated' | 'current';
 /**
  * Get the path to the shim for an agent.
  */
@@ -138,7 +236,8 @@ export declare function addShimsToPath(): {
  */
 export declare function ensureAllShims(): void;
 /**
- * Resource diff between two versions.
+ * Resource diff between two versions. Each field lists resources present in
+ * the current version but missing from the target.
  */
 export interface ResourceDiff {
     commands: string[];

package/dist/lib/shims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/lib/shims.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/lib/shims.ts"],"names":[],"mappings":"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"}

package/dist/lib/shims.js

@@ -1,3 +1,13 @@
+/**
+ * Shim generation and config symlink management for agent version switching.
+ *
+ * Shims are small shell scripts placed in ~/.agents/shims/ that resolve the
+ * active agent version (project-level or user-default), then exec the real
+ * binary. Config isolation is achieved by symlinking ~/.{agent} into the
+ * per-version home directory. This module also handles versioned aliases
+ * (e.g., claude@2.0.65), PATH setup, conflict detection during migration,
+ * and resource diffing between versions.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -130,7 +140,7 @@ export async function promptConflictStrategy(conflictInfos) {
  * Generate the shim script content for an agent.
  *
  * The shim resolves the version in order:
- * 1. .agents-version in cwd (walk up to root)
+ * 1. agents.yaml in project root (walk up from $PWD, skip ~/.agents/agents.yaml)
  * 2. ~/.agents/agents.yaml default
  *
  * If version is specified but not installed, auto-installs it.
@@ -138,6 +148,29 @@ export async function promptConflictStrategy(conflictInfos) {
  * Config isolation is handled via symlinks:
  * ~/.{agent} -> ~/.agents/versions/{agent}/{version}/home/.{agent}/
  */
+/**
+ * Current shim schema version. Bump whenever `generateShimScript` changes
+ * in a way that requires existing on-disk shims to be regenerated (new
+ * flags, fixed argument parsing, new hooks, etc.). `isShimCurrent` reads
+ * this marker out of existing shims to decide whether to regenerate.
+ *
+ * History:
+ *   v1 — initial shim (implicit, no marker).
+ *   v2 — `--version=...` form in sync/refresh-memory calls; refresh-memory
+ *        shim hook for non-@-capable agents.
+ *   v3 — sync/refresh-memory flag renamed `--version` → `--agent-version`
+ *        so it no longer collides with commander's top-level `--version`.
+ *   v4 — project version marker changed from `.agents-version` to a
+ *        root-level `agents.yaml`; shim now skips ~/.agents/agents.yaml
+ *        when walking up for a project marker.
+ */
+export const SHIM_SCHEMA_VERSION = 4;
+/** Internal marker string used to embed the schema version in shim scripts. */
+const SHIM_VERSION_MARKER = 'agents-shim-version:';
+/**
+ * Generate the full bash shim script for the given agent. The returned string
+ * is written to ~/.agents/shims/{cliCommand} and made executable.
+ */
 export function generateShimScript(agent) {
     const agentConfig = AGENTS[agent];
     const cliCommand = agentConfig.cliCommand;
@@ -148,40 +181,43 @@ export function generateShimScript(agent) {
 # selected version's config directory so switching versions also switches the
 # live Claude account.
 export CLAUDE_CONFIG_DIR="$VERSION_DIR/home/${configDirName}"
+`
+        : '';
+    // Agents that don't natively resolve @-imports in their memory file need
+    // agents-cli to recompile when the user edits a rule/preset file. The
+    // check is fast (sha256 of ~8 small files) and skips the recompile when
+    // sources haven't changed.
+    const refreshMemoryCall = !agentConfig.capabilities.memoryImports
+        ? `
+# Recompile memory if any rule/preset source has changed since last sync.
+# Fast-path check (~10-20ms) when nothing changed; full recompile only on
+# actual diff. Non-blocking failure — if the refresh errors, we still launch.
+agents refresh-memory --agent "$AGENT" --agent-version "$VERSION" --quiet 2>/dev/null || true
 `
         : '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
 # Shim for ${agentConfig.name}
+# ${SHIM_VERSION_MARKER} ${SHIM_SCHEMA_VERSION}
 
 AGENTS_DIR="$HOME/.agents"
 AGENT="${agent}"
 CLI_COMMAND="${cliCommand}"
 
-# Find .agents-version walking up from cwd
+# Find project agents.yaml walking up from cwd (skip ~/.agents/agents.yaml)
 find_project_version() {
   local dir="$PWD"
+  local user_agents_yaml="$HOME/.agents/agents.yaml"
   while [ "$dir" != "/" ]; do
-    if [ -f "$dir/.agents-version" ]; then
-      # Parse YAML - handle both "agent: version" and "agent:\\n  - version"
+    local candidate="$dir/agents.yaml"
+    if [ -f "$candidate" ] && [ "$candidate" != "$user_agents_yaml" ]; then
+      # Parse agents: section — same shape as resolve_default_version()
       local version
       version=$(awk -v agent="$AGENT" '
-        $0 ~ "^" agent ":" {
-          # Check if value is on same line
-          if (match($0, /:[[:space:]]+[0-9]/)) {
-            gsub(/.*:[[:space:]]*["'"'"']?|["'"'"']?[[:space:]]*$/, "")
-            print
-            exit
-          }
-          # Value might be on next line (array format)
-          getline
-          if (/^[[:space:]]+-[[:space:]]/) {
-            gsub(/^[[:space:]]+-[[:space:]]*["'"'"']?|["'"'"']?[[:space:]]*$/, "")
-            print
-            exit
-          }
-        }
-      ' "$dir/.agents-version")
+        /^agents:/ { in_agents=1; next }
+        in_agents && /^[^ ]/ { in_agents=0 }
+        in_agents && $0 ~ "^  " agent ":" { gsub(/.*:[[:space:]]*["'"'"']?|["'"'"']?[[:space:]]*$/, ""); print; exit }
+      ' "$candidate")
       if [ -n "$version" ]; then
         echo "$version"
         return 0
@@ -204,7 +240,7 @@ resolve_default_version() {
   fi
 }
 
-# Find project-scoped .agents directory (stop at .git or .agents-version)
+# Find project-scoped .agents directory (stop at agents.yaml or .git)
 find_project_agents_dir() {
   local dir="$PWD"
   while [ "$dir" != "/" ]; do
@@ -212,7 +248,7 @@ find_project_agents_dir() {
       echo "$dir/.agents"
       return 0
     fi
-    if [ -f "$dir/.agents-version" ] || [ -d "$dir/.git" ] || [ -f "$dir/.git" ]; then
+    if [ -f "$dir/agents.yaml" ] || [ -d "$dir/.git" ] || [ -f "$dir/.git" ]; then
       break
     fi
     dir=$(dirname "$dir")
@@ -240,7 +276,7 @@ BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
 # Auto-install if not present
 if [ ! -x "$BINARY" ]; then
   if [ "$VERSION_SOURCE" = "project" ]; then
-    echo "agents: $AGENT@$VERSION required by .agents-version but not installed" >&2
+    echo "agents: $AGENT@$VERSION required by agents.yaml but not installed" >&2
 
     # Spinner animation
     spin() {
@@ -277,9 +313,9 @@ fi
 # Sync project-scoped resources into version home if a project .agents/ is present
 PROJECT_AGENTS_DIR=$(find_project_agents_dir)
 if [ -n "$PROJECT_AGENTS_DIR" ]; then
-  agents sync --agent "$AGENT" --version "$VERSION" --project-dir "$PROJECT_AGENTS_DIR" --quiet >/dev/null 2>&1
+  agents sync --agent "$AGENT" --agent-version "$VERSION" --project-dir "$PROJECT_AGENTS_DIR" --quiet >/dev/null 2>&1
 fi
-${managedEnv}
+${refreshMemoryCall}${managedEnv}
 
 exec "$BINARY" "$@"
 `;
@@ -309,6 +345,21 @@ export function removeShim(agent) {
     }
     return false;
 }
+/**
+ * Current versioned-alias schema. Bump whenever `generateVersionedAliasScript`
+ * changes in a way that requires existing on-disk aliases to be regenerated.
+ *
+ * History:
+ *   v1 — implicit (no marker); no CLAUDE_CONFIG_DIR export, so direct
+ *        `claude@X` invocations leaked into ~/.claude (the default version's
+ *        symlinked home) and `agents view` never saw the login.
+ *   v2 — emit CLAUDE_CONFIG_DIR for claude aliases so each version has its
+ *        own isolated config/OAuth slot; stamp a version marker so stale
+ *        aliases can be detected and regenerated.
+ */
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 2;
+/** Internal marker string used to embed the schema version in versioned alias scripts. */
+const VERSIONED_ALIAS_VERSION_MARKER = 'agents-versioned-alias-version:';
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary
@@ -325,6 +376,7 @@ export CLAUDE_CONFIG_DIR="$HOME/.agents/versions/${agent}/${version}/home/${conf
         : '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
+# ${VERSIONED_ALIAS_VERSION_MARKER} ${VERSIONED_ALIAS_SCHEMA_VERSION}
 # Direct alias for ${agentConfig.name}@${version}
 
 BINARY="$HOME/.agents/versions/${agent}/${version}/node_modules/.bin/${agentConfig.cliCommand}"
@@ -338,6 +390,55 @@ ${managedEnv}
 exec "$BINARY" "$@"
 `;
 }
+/**
+ * Read the schema version of an on-disk versioned alias. Returns null if the
+ * alias doesn't exist or is a pre-v2 alias (no marker — treated as stale).
+ */
+export function readVersionedAliasSchemaVersion(agent, version) {
+    const aliasPath = getVersionedAliasPath(agent, version);
+    if (!fs.existsSync(aliasPath))
+        return null;
+    try {
+        const content = fs.readFileSync(aliasPath, 'utf8');
+        const header = content.split('\n', 10).join('\n');
+        const match = header.match(new RegExp(VERSIONED_ALIAS_VERSION_MARKER + '\\s*(\\d+)'));
+        if (!match)
+            return null;
+        return Number(match[1]);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True if the on-disk versioned alias matches the current schema version.
+ */
+export function isVersionedAliasCurrent(agent, version) {
+    return readVersionedAliasSchemaVersion(agent, version) === VERSIONED_ALIAS_SCHEMA_VERSION;
+}
+/**
+ * Regenerate a versioned alias if missing or stale. Mirrors ensureShimCurrent
+ * for the main shim — callers can surface a one-line notice when something
+ * was upgraded.
+ */
+export function ensureVersionedAliasCurrent(agent, version) {
+    const aliasPath = getVersionedAliasPath(agent, version);
+    if (!fs.existsSync(aliasPath)) {
+        createVersionedAlias(agent, version);
+        return 'created';
+    }
+    if (!isVersionedAliasCurrent(agent, version)) {
+        createVersionedAlias(agent, version);
+        return 'updated';
+    }
+    return 'current';
+}
+/**
+ * Get the filesystem path for a versioned alias script.
+ */
+export function getVersionedAliasPath(agent, version) {
+    return path.join(getShimsDir(), `${AGENTS[agent].cliCommand}@${version}`);
+}
 /**
  * Create a versioned alias for a specific agent version.
  * e.g., claude@2.0.65
@@ -507,6 +608,15 @@ export function switchHomeFileSymlinks(agent, version) {
     const versionsDir = getVersionsDir();
     const switched = [];
     const errors = [];
+    // For Claude, Claude's binary reads CLAUDE_CONFIG_DIR/.claude.json (INSIDE
+    // the per-version .claude dir) — not the home-level file this function
+    // manages. Reconcile all installed Claude versions so INSIDE is a symlink
+    // to OUTSIDE, making OUTSIDE the single source of truth.
+    if (agent === 'claude') {
+        const reconcile = ensureAllClaudeInsideSymlinks();
+        for (const e of reconcile.errors)
+            errors.push(e);
+    }
     for (const fileName of homeFiles) {
         const globalPath = path.join(home, fileName);
         const versionFilePath = path.join(versionsDir, agent, version, 'home', fileName);
@@ -595,6 +705,108 @@ export function switchHomeFileSymlinks(agent, version) {
     }
     return { switched, errors };
 }
+/**
+ * Claude reads `.claude.json` at `$CLAUDE_CONFIG_DIR/.claude.json`. Our shim
+ * points CLAUDE_CONFIG_DIR at `<ver>/home/.claude`, so Claude's real config
+ * file lives at `<ver>/home/.claude/.claude.json` (INSIDE), while
+ * `switchHomeFileSymlinks` manages `<ver>/home/.claude.json` (OUTSIDE).
+ *
+ * To keep both views consistent we make INSIDE a symlink to OUTSIDE. Claude's
+ * atomic write (`Uf6`) resolves symlinks before the tmp+rename cycle, so the
+ * symlink survives across writes and OUTSIDE remains the single source of
+ * truth that agents-cli's home-file machinery already manages.
+ *
+ * This function idempotently reconciles one version:
+ *   - INSIDE missing: create symlink -> `../.claude.json` (create OUTSIDE if needed).
+ *   - INSIDE already symlink to OUTSIDE: no-op.
+ *   - INSIDE is a real file: it's the authoritative auth state (Claude was
+ *     writing to it). Move its content to OUTSIDE (merging with OUTSIDE,
+ *     INSIDE wins for `oauthAccount`), then replace INSIDE with the symlink.
+ *   - Symlink points elsewhere: replace it.
+ */
+export function ensureClaudeInsideSymlink(version) {
+    const versionsDir = getVersionsDir();
+    const versionHome = path.join(versionsDir, 'claude', version, 'home');
+    const outsidePath = path.join(versionHome, '.claude.json');
+    const insideDir = path.join(versionHome, '.claude');
+    const insidePath = path.join(insideDir, '.claude.json');
+    const linkTarget = '../.claude.json'; // relative so version dir can be moved
+    if (!fs.existsSync(insideDir)) {
+        fs.mkdirSync(insideDir, { recursive: true });
+    }
+    let insideStat = null;
+    try {
+        insideStat = fs.lstatSync(insidePath);
+    }
+    catch {
+        /* INSIDE does not exist */
+    }
+    if (insideStat?.isSymbolicLink()) {
+        const currentTarget = fs.readlinkSync(insidePath);
+        if (currentTarget === linkTarget)
+            return;
+        // Wrong target — replace.
+        if (!fs.existsSync(outsidePath))
+            fs.writeFileSync(outsidePath, '{}');
+        fs.unlinkSync(insidePath);
+        fs.symlinkSync(linkTarget, insidePath);
+        return;
+    }
+    if (insideStat?.isFile()) {
+        // INSIDE is the authoritative file — Claude has been reading/writing it.
+        // Merge INSIDE into OUTSIDE, with INSIDE winning on every field, then
+        // replace INSIDE with a symlink.
+        let insideContent = {};
+        try {
+            insideContent = JSON.parse(fs.readFileSync(insidePath, 'utf-8'));
+        }
+        catch {
+            /* INSIDE corrupt — treat as empty; OUTSIDE preserved as-is */
+        }
+        let outsideContent = {};
+        if (fs.existsSync(outsidePath)) {
+            try {
+                outsideContent = JSON.parse(fs.readFileSync(outsidePath, 'utf-8'));
+            }
+            catch {
+                /* OUTSIDE corrupt — drop it */
+            }
+        }
+        const merged = { ...outsideContent, ...insideContent };
+        fs.writeFileSync(outsidePath, JSON.stringify(merged, null, 2));
+        fs.unlinkSync(insidePath);
+        fs.symlinkSync(linkTarget, insidePath);
+        return;
+    }
+    // INSIDE missing — ensure OUTSIDE exists, then create symlink.
+    if (!fs.existsSync(outsidePath))
+        fs.writeFileSync(outsidePath, '{}');
+    fs.symlinkSync(linkTarget, insidePath);
+}
+/**
+ * Apply `ensureClaudeInsideSymlink` to every installed Claude version.
+ * Safe to call repeatedly; per-version calls are idempotent.
+ */
+export function ensureAllClaudeInsideSymlinks() {
+    const versionsDir = getVersionsDir();
+    const claudeVersionsDir = path.join(versionsDir, 'claude');
+    const migrated = [];
+    const errors = [];
+    if (!fs.existsSync(claudeVersionsDir))
+        return { migrated, errors };
+    for (const entry of fs.readdirSync(claudeVersionsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        try {
+            ensureClaudeInsideSymlink(entry.name);
+            migrated.push(entry.name);
+        }
+        catch (err) {
+            errors.push(`${entry.name}: ${err.message}`);
+        }
+    }
+    return { migrated, errors };
+}
 /**
  * Get the current config symlink target version, if any.
  */
@@ -709,6 +921,51 @@ export function shimExists(agent) {
     const shimPath = path.join(shimsDir, agentConfig.cliCommand);
     return fs.existsSync(shimPath);
 }
+/**
+ * Read the schema version embedded in an existing on-disk shim. Returns
+ * `null` if the shim doesn't exist or has no version marker (pre-v2 shim).
+ */
+export function readShimSchemaVersion(agent) {
+    if (!shimExists(agent))
+        return null;
+    try {
+        const content = fs.readFileSync(getShimPath(agent), 'utf8');
+        // Look at the first ~10 lines only — the marker lives in the header.
+        const header = content.split('\n', 10).join('\n');
+        const match = header.match(new RegExp(SHIM_VERSION_MARKER + '\\s*(\\d+)'));
+        if (!match)
+            return null;
+        return Number(match[1]);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True if the on-disk shim's schema version matches `SHIM_SCHEMA_VERSION`.
+ * False means either the shim is missing, is pre-v2 (no marker), or is an
+ * older version that needs regeneration.
+ */
+export function isShimCurrent(agent) {
+    const version = readShimSchemaVersion(agent);
+    return version === SHIM_SCHEMA_VERSION;
+}
+/**
+ * Regenerate the shim if it's missing or outdated. Returns a status describing
+ * what happened — callers can surface a one-line notice to the user ("Updated
+ * shim for codex") when appropriate.
+ */
+export function ensureShimCurrent(agent) {
+    if (!shimExists(agent)) {
+        createShim(agent);
+        return 'created';
+    }
+    if (!isShimCurrent(agent)) {
+        createShim(agent);
+        return 'updated';
+    }
+    return 'current';
+}
 /**
  * Get the path to the shim for an agent.
  */