@phnx-labs/agents-cli 1.14.2 → 1.14.3

package/dist/lib/migrate.js

@@ -76,10 +76,87 @@ function migratePromptcutsIntoHooks() {
         catch { /* best-effort */ }
     }
 }
+/**
+ * Move installed agent versions from the legacy single-root layout
+ * (~/.agents/versions/<agent>/<ver>/) into the system root
+ * (~/.agents-system/versions/<agent>/<ver>/).
+ *
+ * Pre-split installs put binaries and home dirs under ~/.agents/. After the
+ * split, the system code only scans ~/.agents-system/versions/, so without
+ * this migration the versions become invisible to listInstalledVersions and
+ * every command that depends on it (view, prune, run).
+ *
+ * Idempotent and non-destructive: if a same-named dest already exists we
+ * leave the legacy copy in place so the user can reconcile manually.
+ */
+function migrateUserVersionsToSystem() {
+    const userVersions = path.join(USER_DIR, 'versions');
+    const sysVersions = path.join(SYSTEM_DIR, 'versions');
+    if (!fs.existsSync(userVersions))
+        return;
+    let movedCount = 0;
+    let skippedCount = 0;
+    let agentEntries;
+    try {
+        agentEntries = fs.readdirSync(userVersions, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const agent of agentEntries) {
+        if (!agent.isDirectory())
+            continue;
+        const srcAgentDir = path.join(userVersions, agent.name);
+        const dstAgentDir = path.join(sysVersions, agent.name);
+        try {
+            fs.mkdirSync(dstAgentDir, { recursive: true, mode: 0o700 });
+        }
+        catch { /* best-effort */ }
+        let verEntries;
+        try {
+            verEntries = fs.readdirSync(srcAgentDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const ver of verEntries) {
+            if (!ver.isDirectory())
+                continue;
+            const src = path.join(srcAgentDir, ver.name);
+            const dst = path.join(dstAgentDir, ver.name);
+            if (fs.existsSync(dst)) {
+                skippedCount++;
+                continue;
+            }
+            try {
+                fs.renameSync(src, dst);
+                movedCount++;
+            }
+            catch { /* best-effort, leave legacy in place */ }
+        }
+        try {
+            if (fs.readdirSync(srcAgentDir).length === 0)
+                fs.rmdirSync(srcAgentDir);
+        }
+        catch { /* best-effort */ }
+    }
+    try {
+        if (fs.readdirSync(userVersions).length === 0)
+            fs.rmdirSync(userVersions);
+    }
+    catch { /* best-effort */ }
+    if (movedCount > 0) {
+        console.log(`Migrated ${movedCount} version dir${movedCount === 1 ? '' : 's'} from ~/.agents/versions/ to ~/.agents-system/versions/`);
+    }
+    if (skippedCount > 0) {
+        console.log(`Skipped ${skippedCount} version dir${skippedCount === 1 ? '' : 's'} already present in ~/.agents-system/versions/ (kept legacy copy at ~/.agents/versions/)`);
+    }
+}
 /** Run all idempotent migrations. Safe to call multiple times. */
 export function runMigration() {
     migrateAgentsYaml();
     deleteSystemPromptsJson();
     migrateSystemConfigJson();
     migratePromptcutsIntoHooks();
+    migrateUserVersionsToSystem();
 }

package/dist/lib/pty-client.js

@@ -9,7 +9,7 @@ import * as fs from 'fs';
 import { spawn, execSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import * as path from 'path';
-import { getSocketPath, isPtyServerRunning } from './pty-server.js';
+import { getSocketPath, getPtyLogPath, isPtyServerRunning } from './pty-server.js';
 const CONNECT_TIMEOUT_MS = 5000;
 const RESPONSE_TIMEOUT_MS = 30000;
 /**
@@ -33,7 +33,7 @@ async function ensureServer() {
         return;
     // Find the entry point to spawn the server
     const { bin, args } = getServerSpawnArgs();
-    const logPath = path.join(path.dirname(getSocketPath()), 'pty.log');
+    const logPath = getPtyLogPath();
     const logFd = fs.openSync(logPath, 'a');
     const child = spawn(bin, args, {
         stdio: ['ignore', logFd, logFd],
@@ -57,7 +57,7 @@ async function ensureServer() {
         }
         await new Promise(r => setTimeout(r, 100));
     }
-    throw new Error('PTY server failed to start within 5 seconds. Check ~/.agents/pty.log');
+    throw new Error('PTY server failed to start within 5 seconds. Check ~/.agents-system/helpers/pty/logs.jsonl');
 }
 function getServerSpawnArgs() {
     // Prefer the dist/index.js from the same installation as this code.

package/dist/lib/pty-server.js

@@ -53,9 +53,12 @@ export function captureProcessStartTime(pid) {
 }
 // --- Constants ---
 const SENTINEL = '__AGENTS_PTY_DONE__';
+const PTY_DIR = 'helpers/pty';
 const SOCKET_NAME = 'pty.sock';
 const PID_FILE = 'pty.pid';
-const LOG_FILE = 'pty.log';
+const LOG_FILE = 'logs.jsonl';
+const LOG_MAX_SIZE = 5 * 1024 * 1024; // 5 MB
+const LOG_ROTATE_COUNT = 3;
 const SESSION_IDLE_MS = 30 * 60 * 1000; // 30 min
 const SERVER_IDLE_MS = 60 * 60 * 1000; // 1 hour
 // --- Path helpers ---
@@ -79,17 +82,24 @@ function buildPtyEnv() {
     }
     return env;
 }
+/** Get the PTY helper directory, creating it if needed. */
+function getPtyDir() {
+    const dir = path.join(getAgentsDir(), PTY_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
 /** Get the unix socket path for the PTY server. */
 export function getSocketPath() {
-    return path.join(getAgentsDir(), SOCKET_NAME);
+    return path.join(getPtyDir(), SOCKET_NAME);
 }
 /** Get the path to the PTY server PID file. */
 export function getPtyPidPath() {
-    return path.join(getAgentsDir(), PID_FILE);
+    return path.join(getPtyDir(), PID_FILE);
 }
 /** Get the path to the PTY server log file. */
 export function getPtyLogPath() {
-    return path.join(getAgentsDir(), LOG_FILE);
+    const logDir = getPtyDir();
+    return path.join(logDir, LOG_FILE);
 }
 /** Check if the PTY server process is alive by probing the stored PID. */
 export function isPtyServerRunning() {
@@ -112,11 +122,30 @@ export function isPtyServerRunning() {
     }
 }
 // --- Logging ---
+function rotateLogsIfNeeded(logPath) {
+    try {
+        const stat = fs.statSync(logPath);
+        if (stat.size < LOG_MAX_SIZE)
+            return;
+        for (let i = LOG_ROTATE_COUNT - 1; i >= 1; i--) {
+            const older = `${logPath}.${i}`;
+            const newer = i === 1 ? logPath : `${logPath}.${i - 1}`;
+            if (fs.existsSync(newer)) {
+                fs.renameSync(newer, older);
+            }
+        }
+        if (fs.existsSync(logPath)) {
+            fs.renameSync(logPath, `${logPath}.1`);
+        }
+    }
+    catch { }
+}
 function log(level, message) {
-    const ts = new Date().toISOString();
-    const line = `[${ts}] [${level}] ${message}\n`;
+    const logPath = getPtyLogPath();
+    rotateLogsIfNeeded(logPath);
+    const entry = { ts: new Date().toISOString(), level, message };
     try {
-        fs.appendFileSync(getPtyLogPath(), line, 'utf-8');
+        fs.appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf-8');
     }
     catch { }
 }

package/dist/lib/resources.js

@@ -8,7 +8,7 @@ import { AGENTS, listInstalledMcpsWithScope } from './agents.js';
 import { listInstalledCommandsWithScope } from './commands.js';
 import { listInstalledSkillsWithScope } from './skills.js';
 import { listInstalledHooksWithScope } from './hooks.js';
-import { listInstalledInstructionsWithScope } from './memory.js';
+import { listInstalledInstructionsWithScope } from './rules/rules.js';
 import { getEffectiveHome } from './versions.js';
 import { listMcpServerConfigs } from './mcp.js';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from './state.js';

package/dist/lib/rotate.d.ts

@@ -35,7 +35,14 @@ export declare const RUN_STRATEGIES: RunStrategy[];
 export declare function normalizeRunStrategy(value: unknown): RunStrategy | null;
 /** Read project-local run strategy from the nearest agents.yaml, if present. */
 export declare function getProjectRunStrategy(agent: AgentId, startPath: string): RunStrategy | null;
-/** Resolve the configured strategy: project agents.yaml, then ~/.agents-system/agents.yaml, then pinned. */
+/**
+ * Resolve the configured strategy. Lookup order:
+ *   1. project-local agents.yaml (nearest to `startPath`)
+ *   2. ~/.agents-system/agents.yaml
+ *   3. default: `available` (use the pinned default version when healthy,
+ *      otherwise fall through to a healthy account so a single rate-limited
+ *      account doesn't block the run).
+ */
 export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: string): RunStrategy;
 /** Persist the global run strategy used by bare `agents run <agent>`. */
 export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrategy): void;

package/dist/lib/rotate.js

@@ -11,6 +11,12 @@ import { getAccountInfo } from './agents.js';
 import { readMeta, writeMeta, getAgentsDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
 import { getUsageInfoByIdentity, getUsageLookupKey, isClaudeAuthValid, } from './usage.js';
+const ROTATE_DIR = 'helpers/rotate';
+function getRotateDir() {
+    const dir = path.join(getAgentsDir(), ROTATE_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
 export const RUN_STRATEGIES = ['pinned', 'available', 'balanced'];
 /**
  * Return a run strategy when the input is valid, otherwise null.
@@ -47,11 +53,18 @@ export function getProjectRunStrategy(agent, startPath) {
     }
     return null;
 }
-/** Resolve the configured strategy: project agents.yaml, then ~/.agents-system/agents.yaml, then pinned. */
+/**
+ * Resolve the configured strategy. Lookup order:
+ *   1. project-local agents.yaml (nearest to `startPath`)
+ *   2. ~/.agents-system/agents.yaml
+ *   3. default: `available` (use the pinned default version when healthy,
+ *      otherwise fall through to a healthy account so a single rate-limited
+ *      account doesn't block the run).
+ */
 export function getConfiguredRunStrategy(agent, startPath = process.cwd()) {
     return getProjectRunStrategy(agent, startPath)
         ?? normalizeRunStrategy(readMeta().run?.[agent]?.strategy)
-        ?? 'pinned';
+        ?? 'available';
 }
 /** Persist the global run strategy used by bare `agents run <agent>`. */
 export function setGlobalRunStrategy(agent, strategy) {
@@ -279,7 +292,7 @@ export async function selectAvailableVersion(agent, preferredVersion) {
  * a torn write just means the next reader sees a stale timestamp (harmless).
  */
 function recordRotationPick(agent, version) {
-    const stampPath = path.join(getAgentsDir(), `rotate-stamp-${agent}.json`);
+    const stampPath = path.join(getRotateDir(), `stamp-${agent}.json`);
     try {
         fs.writeFileSync(stampPath, JSON.stringify({ version, ts: Date.now() }), 'utf-8');
     }
@@ -290,7 +303,7 @@ function recordRotationPick(agent, version) {
  * or stamp is older than 60 seconds (stale).
  */
 function readRotationStamp(agent) {
-    const stampPath = path.join(getAgentsDir(), `rotate-stamp-${agent}.json`);
+    const stampPath = path.join(getRotateDir(), `stamp-${agent}.json`);
     try {
         const raw = JSON.parse(fs.readFileSync(stampPath, 'utf-8'));
         if (Date.now() - raw.ts < 60_000)

package/dist/lib/rules/compile.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Rules file compilation -- resolving @-imports into a single flat file.
+ *
+ * Agents that do not natively resolve `@path/to/file` imports (Codex, Cursor)
+ * need a pre-compiled rules file with all imports inlined. This module
+ * handles that expansion for both user-scope (writes into version home) and
+ * project-scope (writes into the workspace).
+ */
+import type { AgentId } from '../types.js';
+import { type RulesLayer } from './compose.js';
+/** Sidecar manifest recording source file hashes for staleness detection. */
+export interface CompileManifest {
+    compiledAt: string;
+    sources: {
+        path: string;
+        sha256: string;
+        mtime?: number;
+        size?: number;
+    }[];
+}
+/** Result of resolving @-imports in a rules file. */
+export interface ResolveResult {
+    /** Fully-inlined content. */
+    content: string;
+    /** Absolute paths of every file read during resolution (including the root). */
+    sources: string[];
+}
+/**
+ * Expand all `@path/to/file` imports in `content`, recursively up to
+ * MAX_DEPTH. Imports inside fenced code blocks and inline code spans are
+ * left alone, matching Claude Code's parser. Missing files are left as-is
+ * (silent skip), matching the documented behavior.
+ *
+ * Relative paths resolve against `baseDir`; absolute and tilde-prefixed
+ * paths resolve against the filesystem root / home directory.
+ */
+export declare function resolveImports(content: string, baseDir: string): ResolveResult;
+/** True if the agent's native runtime resolves `@path` imports in its rules file. */
+export declare function supportsRulesImports(agentId: AgentId): boolean;
+/**
+ * Fast staleness check. Returns true when:
+ *  - the compiled file or its manifest is missing
+ *  - any recorded source file is missing
+ *  - any recorded source's sha256 no longer matches
+ *
+ * For agents that support @-imports natively, always returns false — there's
+ * nothing to compile.
+ */
+export declare function isRulesStale(agentId: AgentId, version: string): boolean;
+/**
+ * Resolve the source `rules/AGENTS.md` (with all @-imports expanded) and
+ * write the result into the version home, alongside a sidecar manifest that
+ * records source file hashes for staleness detection.
+ *
+ * Agents that natively resolve @-imports are skipped (no-op) — their sync
+ * uses the standard copyFileSync path in `syncResourcesToVersion`.
+ */
+export declare function compileRulesForAgent(agentId: AgentId, version: string): {
+    compiled: boolean;
+    compiledPath: string;
+    sources: number;
+};
+/**
+ * Recompile rules if stale. Safe to call on every agent invocation — the
+ * staleness check is fast (sha256 of 8-10 small files, ~10-20ms). Returns
+ * true if a recompile happened, false otherwise.
+ */
+export declare function ensureRulesFresh(agentId: AgentId, version: string): boolean;
+export interface ProjectCompileResult {
+    /** True when cwd/AGENTS.md was newly written or rewritten. */
+    compiled: boolean;
+    /** Absolute path to cwd/AGENTS.md. Empty when no project rules dir was present. */
+    agentsPath: string;
+    /** Per-agent instruction filenames symlinked (or copied) to AGENTS.md. */
+    symlinks: string[];
+    /** Number of source files inlined (root + recursive @-imports). */
+    sources: number;
+    /** Per-agent files we left alone because the user wrote/owns them. */
+    skippedClobber: string[];
+}
+/**
+ * Compile project-scope rules into a workspace's root memory files so each
+ * agent's native loader picks them up.
+ *
+ * Composes rules from all available layers (project > user > extras > system)
+ * with project highest priority — so a project's `subrules/` and `rules.yaml`
+ * shadow user/system fragments and presets. Writes `cwd/AGENTS.md` with
+ * COMPILED_HEADER_PROJECT and creates symlinks (CLAUDE.md, GEMINI.md,
+ * .cursorrules, etc.) → AGENTS.md so every agent finds its expected file at
+ * cwd. The agent's own loader merges this project-level file with its
+ * user-level rules (in version home) at runtime.
+ *
+ * Don't-clobber guard: if `cwd/AGENTS.md` exists without our header, the user
+ * authored it — leave it alone and report via `skippedClobber`. Same for any
+ * pre-existing per-agent file or symlink that doesn't already point at
+ * AGENTS.md.
+ *
+ * No-op when `cwd/.agents/rules/` does not exist. Idempotent on repeated
+ * calls — content equality short-circuits the write.
+ */
+export declare function compileRulesForProject(cwd: string, opts?: {
+    preset?: string;
+    layers?: RulesLayer[];
+}): ProjectCompileResult;

package/dist/lib/{memory-compile.js → rules/compile.js}

@@ -1,16 +1,18 @@
 /**
  * Rules file compilation -- resolving @-imports into a single flat file.
  *
- * Agents that do not natively resolve `@path/to/file` imports (Codex, Gemini)
+ * Agents that do not natively resolve `@path/to/file` imports (Codex, Cursor)
  * need a pre-compiled rules file with all imports inlined. This module
- * handles that expansion.
+ * handles that expansion for both user-scope (writes into version home) and
+ * project-scope (writes into the workspace).
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
-import { AGENTS } from './agents.js';
-import { getResolvedRulesDir, getVersionsDir } from './state.js';
+import { AGENTS } from '../agents.js';
+import { getResolvedRulesDir, getVersionsDir } from '../state.js';
+import { composeRules, composeRulesFromState } from './compose.js';
 // Match `@path` preceded by start-of-string or whitespace. This avoids
 // matching emails ("foo@bar.com") and the middle of words. The leading
 // whitespace (if any) is captured so we can preserve it in the output.
@@ -18,6 +20,8 @@ const IMPORT_RE = /(^|\s)@(\S+)/g;
 const MAX_DEPTH = 5;
 const COMPILED_HEADER = '<!-- Auto-compiled by agents-cli from ~/.agents/rules/AGENTS.md + imports.\n' +
     '     Edit the source files under ~/.agents/rules/ — edits to this file will be overwritten on next sync. -->\n\n';
+const COMPILED_HEADER_PROJECT = '<!-- Auto-compiled by agents-cli from .agents/rules/AGENTS.md + imports.\n' +
+    '     Edit the source files under .agents/rules/ — edits to this file will be overwritten on next sync. -->\n\n';
 function expandTilde(p) {
     if (p === '~')
         return os.homedir();
@@ -87,10 +91,10 @@ export function resolveImports(content, baseDir) {
     return { content: result, sources };
 }
 /** True if the agent's native runtime resolves `@path` imports in its rules file. */
-export function supportsMemoryImports(agentId) {
-    return !!AGENTS[agentId].capabilities.memoryImports;
+export function supportsRulesImports(agentId) {
+    return !!AGENTS[agentId].capabilities.rulesImports;
 }
-function getCompiledMemoryPath(agentId, version) {
+function getCompiledRulesPath(agentId, version) {
     const agentConfig = AGENTS[agentId];
     const versionHome = path.join(getVersionsDir(), agentId, version, 'home');
     return path.join(versionHome, `.${agentId}`, agentConfig.instructionsFile);
@@ -107,10 +111,10 @@ function getManifestPath(compiledPath) {
  * For agents that support @-imports natively, always returns false — there's
  * nothing to compile.
  */
-export function isMemoryStale(agentId, version) {
-    if (supportsMemoryImports(agentId))
+export function isRulesStale(agentId, version) {
+    if (supportsRulesImports(agentId))
         return false;
-    const compiledPath = getCompiledMemoryPath(agentId, version);
+    const compiledPath = getCompiledRulesPath(agentId, version);
     const manifestPath = getManifestPath(compiledPath);
     if (!fs.existsSync(compiledPath) || !fs.existsSync(manifestPath))
         return true;
@@ -143,19 +147,19 @@ export function isMemoryStale(agentId, version) {
  * Agents that natively resolve @-imports are skipped (no-op) — their sync
  * uses the standard copyFileSync path in `syncResourcesToVersion`.
  */
-export function compileMemoryForAgent(agentId, version) {
-    if (supportsMemoryImports(agentId)) {
+export function compileRulesForAgent(agentId, version) {
+    if (supportsRulesImports(agentId)) {
         return { compiled: false, compiledPath: '', sources: 0 };
     }
-    const memoryDir = getResolvedRulesDir();
-    const sourceAgents = path.join(memoryDir, 'AGENTS.md');
+    const rulesDir = getResolvedRulesDir();
+    const sourceAgents = path.join(rulesDir, 'AGENTS.md');
     if (!fs.existsSync(sourceAgents)) {
         return { compiled: false, compiledPath: '', sources: 0 };
     }
     const rootContent = fs.readFileSync(sourceAgents, 'utf8');
-    const { content, sources } = resolveImports(rootContent, memoryDir);
+    const { content, sources } = resolveImports(rootContent, rulesDir);
     const newContent = COMPILED_HEADER + content;
-    const compiledPath = getCompiledMemoryPath(agentId, version);
+    const compiledPath = getCompiledRulesPath(agentId, version);
     fs.mkdirSync(path.dirname(compiledPath), { recursive: true });
     const existing = fs.existsSync(compiledPath) ? fs.readFileSync(compiledPath, 'utf8') : null;
     if (existing === newContent) {
@@ -175,15 +179,150 @@ export function compileMemoryForAgent(agentId, version) {
     return { compiled: true, compiledPath, sources: allSources.length };
 }
 /**
- * Recompile memory if stale. Safe to call on every agent invocation — the
+ * Recompile rules if stale. Safe to call on every agent invocation — the
  * staleness check is fast (sha256 of 8-10 small files, ~10-20ms). Returns
  * true if a recompile happened, false otherwise.
  */
-export function ensureMemoryFresh(agentId, version) {
-    if (supportsMemoryImports(agentId))
+export function ensureRulesFresh(agentId, version) {
+    if (supportsRulesImports(agentId))
         return false;
-    if (!isMemoryStale(agentId, version))
+    if (!isRulesStale(agentId, version))
         return false;
-    const result = compileMemoryForAgent(agentId, version);
+    const result = compileRulesForAgent(agentId, version);
     return result.compiled;
 }
+/**
+ * Compile project-scope rules into a workspace's root memory files so each
+ * agent's native loader picks them up.
+ *
+ * Composes rules from all available layers (project > user > extras > system)
+ * with project highest priority — so a project's `subrules/` and `rules.yaml`
+ * shadow user/system fragments and presets. Writes `cwd/AGENTS.md` with
+ * COMPILED_HEADER_PROJECT and creates symlinks (CLAUDE.md, GEMINI.md,
+ * .cursorrules, etc.) → AGENTS.md so every agent finds its expected file at
+ * cwd. The agent's own loader merges this project-level file with its
+ * user-level rules (in version home) at runtime.
+ *
+ * Don't-clobber guard: if `cwd/AGENTS.md` exists without our header, the user
+ * authored it — leave it alone and report via `skippedClobber`. Same for any
+ * pre-existing per-agent file or symlink that doesn't already point at
+ * AGENTS.md.
+ *
+ * No-op when `cwd/.agents/rules/` does not exist. Idempotent on repeated
+ * calls — content equality short-circuits the write.
+ */
+export function compileRulesForProject(cwd, opts = {}) {
+    const projectRulesDir = path.join(cwd, '.agents', 'rules');
+    const empty = {
+        compiled: false, agentsPath: '', symlinks: [], sources: 0, skippedClobber: [],
+    };
+    if (!fs.existsSync(projectRulesDir))
+        return empty;
+    let composed;
+    try {
+        // Tests inject `layers` to isolate from real ~/.agents-system / ~/.agents
+        // state. Production callers omit it and compose from discovered state.
+        const result = opts.layers
+            ? composeRules({ preset: opts.preset, layers: opts.layers })
+            : composeRulesFromState({ cwd, preset: opts.preset });
+        composed = { content: result.content, subrules: result.subrules };
+    }
+    catch {
+        // Composer threw (no preset, malformed yaml). Don't write a half-baked
+        // file — bail out cleanly, same as if the rules dir didn't exist.
+        return empty;
+    }
+    const newContent = COMPILED_HEADER_PROJECT + composed.content;
+    const agentsPath = path.join(cwd, 'AGENTS.md');
+    const skippedClobber = [];
+    let compiled = false;
+    let weOwnAgentsMd = false;
+    let agentsLstat = null;
+    try {
+        agentsLstat = fs.lstatSync(agentsPath);
+    }
+    catch { /* missing */ }
+    if (!agentsLstat) {
+        fs.writeFileSync(agentsPath, newContent);
+        compiled = true;
+        weOwnAgentsMd = true;
+    }
+    else if (agentsLstat.isFile()) {
+        let existing = '';
+        try {
+            existing = fs.readFileSync(agentsPath, 'utf8');
+        }
+        catch { /* unreadable */ }
+        if (existing.startsWith(COMPILED_HEADER_PROJECT)) {
+            if (existing !== newContent) {
+                fs.writeFileSync(agentsPath, newContent);
+                compiled = true;
+            }
+            weOwnAgentsMd = true;
+        }
+        else {
+            skippedClobber.push('AGENTS.md');
+        }
+    }
+    else {
+        // Symlink or other non-regular file — treat as user-owned, do not clobber
+        skippedClobber.push('AGENTS.md');
+    }
+    // Per-agent symlinks. Only attempt when we own AGENTS.md — never create a
+    // dangling symlink to a file we couldn't write.
+    const symlinks = [];
+    if (weOwnAgentsMd) {
+        const seen = new Set(['AGENTS.md']);
+        for (const agent of Object.values(AGENTS)) {
+            const fname = agent.instructionsFile;
+            if (seen.has(fname))
+                continue;
+            // Skip agents whose instructions live at a nested path (e.g. OpenClaw's
+            // workspace/AGENTS.md) — those are managed by their own setup paths.
+            if (fname.includes('/') || fname.includes('\\'))
+                continue;
+            seen.add(fname);
+            const linkPath = path.join(cwd, fname);
+            let lstat = null;
+            try {
+                lstat = fs.lstatSync(linkPath);
+            }
+            catch { /* missing */ }
+            if (lstat) {
+                if (lstat.isSymbolicLink()) {
+                    let target = '';
+                    try {
+                        target = fs.readlinkSync(linkPath);
+                    }
+                    catch { /* unreadable */ }
+                    if (target === 'AGENTS.md') {
+                        symlinks.push(fname);
+                        continue;
+                    }
+                    skippedClobber.push(fname);
+                    continue;
+                }
+                // Regular file — user authored
+                skippedClobber.push(fname);
+                continue;
+            }
+            try {
+                fs.symlinkSync('AGENTS.md', linkPath);
+                symlinks.push(fname);
+            }
+            catch {
+                // Filesystems that disallow symlinks (some Windows configs) — fall
+                // back to a copy. The agent reads the same content either way.
+                try {
+                    fs.copyFileSync(agentsPath, linkPath);
+                    symlinks.push(fname);
+                }
+                catch {
+                    // Give up on this one quietly; the agent that needs this filename
+                    // will fall back to its own discovery rules.
+                }
+            }
+        }
+    }
+    return { compiled, agentsPath, symlinks, sources: composed.subrules.length, skippedClobber };
+}