@technomoron/agent-run 0.99.28 → 0.99.29

package/CHANGES

@@ -1,6 +1,19 @@
 CHANGES
 =======
 
+Version 0.99.29 (2026-09-04)
+----------------------------
+* Add tracked per-profile project memory under `notes/memory`, while keeping
+  native Codex memories in ignored machine-local runtime state.
+* Detect older memory layouts before profile updates and agent launches, ask
+  before staging tracked moves with `git mv`, and support
+  `migrate-config --yes` for non-interactive migrations.
+* Make copied systemd updater files portable, install the helper under
+  `/usr/local/libexec`, and remove stale AI tool launchers before global
+  package updates.
+* Explain the shared configuration model for native coding agents in the
+  README.
+
 Version 0.99.28 (2026-08-30)
 ----------------------------
 * Add interactive `agent-run setup [org/repo]`, make `agent-run generate` the

package/README.md

@@ -1,9 +1,46 @@
 # agent-run
 
-Small wrapper for AI coding CLIs like Codex and Claude.
+**Config once. Run with any native coding agent.**
 
-It keeps agent files out of normal repos and stores them in a separate
-agent config tree. By default, that tree lives at `~/.agent-run`.
+`agent-run` lets you manage Codex, Claude Code, Gemini CLI, and Grok Build from
+one shared configuration system while continuing to use each vendor's native
+agent.
+
+Keep agent configuration in a separate Git repository instead of adding
+agent-specific files to every codebase. Define project instructions, skills,
+MCP servers, policies, and reusable configuration fragments once, then generate
+the native configuration each agent expects.
+
+Configuration is template-based using Nunjucks/Jinja-style templates, making it
+easy to build hierarchical setups from global defaults, organization rules,
+project-specific settings, reusable fragments, and local overrides.
+
+`agent-run` generates isolated agent runtimes outside the source repository, so
+application repositories remain clean and developers do not have to maintain
+separate `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, skills, and tool configuration
+for every agent.
+
+The core idea is simple:
+
+**One configuration repository. One set of skills. Multiple native agents.**
+
+```text
+shared config repository
+        ↓
+global + project + local templates
+        ↓
+canonical instructions / skills / MCP
+        ↓
+agent-specific generated runtime
+        ↓
+Codex | Claude Code | Gemini CLI | Grok Build
+```
+
+The native agents remain native. `agent-run` does not replace their execution
+engines, authentication, models, or tooling. It provides the portable
+configuration layer around them.
+
+**Config once, run anywhere.**
 
 ## Model
 
@@ -23,6 +60,9 @@ Example:
       agent-run.jsonc
       local.md.njk       # optional
       overrides/         # optional
+      notes/
+        memory/
+          README.md      # durable project memory, normally tracked
       live/
         CLAUDE.md
         .claude/
@@ -31,6 +71,7 @@ Example:
           codex-home/
             AGENTS.md
             config.toml
+            memories/    # native Codex memory, local generated state
             skills/
 ~/source/org/my-api/
 ```
@@ -50,6 +91,7 @@ the agent config tree.
 - `agent-run.jsonc`: sparse profile manifest and profile-discovery marker
 - `local.md.njk`: optional project-specific instructions
 - `overrides/`: optional per-profile template overrides
+- `notes/memory/`: durable project memory shared through the config repository
 - `live/memories/codex-home/AGENTS.md`: generated Codex instructions
 - `live/memories/codex-home/config.toml`: generated Codex config
 - `live/memories/codex-home/skills/`: generated Codex skills
@@ -152,6 +194,26 @@ When `~/.codex/auth.json` exists, profile-specific Codex homes link their
 `auth.json` to that shared login cache so changing profiles does not require a
 new ChatGPT login.
 
+### Project Memory
+
+Each profile has a durable `notes/memory/` directory outside the source repo.
+`README.md` is a short index; agents read only the linked files relevant to the
+current task. Agents may update project memory only when the user explicitly
+asks them to remember or update something for that project.
+
+Codex's native `$CODEX_HOME/memories/` remains under ignored `live/` state. It
+is generated, machine-local recall data and is not copied into the tracked
+project memory directory. Project memory is plain Markdown so it can be
+reviewed and shared through the Git repository that normally holds the
+`.agent-run` config tree.
+
+When a profile still uses `memory/`, loose `memory*.md` files, or Markdown files
+directly under the old `memories/` directory, agent-run detects the old layout
+before updating or launching an agent. If those files are tracked, agent-run
+shows the moves and asks before staging them with `git mv`. In a non-Git config
+tree, or for untracked files, it uses ordinary filesystem moves. Non-interactive
+runs stop with a command that can confirm the migration explicitly.
+
 Claude Code currently has no `--cd` equivalent. `agent-run` keeps Claude's
 process cwd at the project root, appends the generated `CLAUDE.md` with
 `--append-system-prompt-file`, passes generated settings with `--settings`, and
@@ -287,14 +349,17 @@ agent-run check --all ~/source
 Migrate an existing config tree to the manifest/template layout:
 
 ```sh
-agent-run migrate-config ~/.agent-run
+agent-run migrate-config --yes ~/.agent-run
 ```
 
 This preserves `AGENTS-MODS.md`, creates `local.md.njk` and a sparse
 `agent-run.jsonc` marker for legacy profiles, creates the root defaults and
 `global/` templates, moves loose review files into `reviews/`, moves loose
-`memory*.md` files into `memories/`, and moves old Codex runtime files into
-`live/memories/codex-home` without overwriting existing files.
+project memory files into each profile's `notes/memory/`, and moves old Codex
+runtime files into `live/memories/codex-home` without overwriting existing
+files. Use `--yes` to confirm tracked `git mv` operations in a non-interactive
+run. Omit `--yes` to review and confirm tracked moves interactively. The
+command stages moves but never commits them.
 
 ## Systemd Jobs
 

package/dist/checks.js

@@ -8,6 +8,7 @@ exports.hasErrors = hasErrors;
 const fs = require("fs");
 const path = require("path");
 const constants_1 = require("./constants");
+const config_tree_1 = require("./config-tree");
 const manifest_1 = require("./manifest");
 const project_1 = require("./project");
 const renderer_1 = require("./renderer");
@@ -47,6 +48,9 @@ function checkAgentDirectory(projectRoot, agentDir) {
     if (!(0, manifest_1.isProfileConfigured)(agentDir)) {
         return [{ message: `missing manifest or legacy/local source file in ${agentDir}`, severity: 'ERROR' }];
     }
+    for (const legacyPath of (0, config_tree_1.describeLegacyProfileLayout)(agentDir)) {
+        findings.push({ message: `old profile layout needs migration: ${legacyPath}`, severity: 'ERROR' });
+    }
     for (const relativeTemplate of constants_1.REQUIRED_GLOBAL_TEMPLATES) {
         if (!fs.existsSync(path.join(configRoot, relativeTemplate))) {
             findings.push({

package/dist/cli.js

@@ -254,16 +254,22 @@ function parseUpdateCommand(inputArgs) {
 }
 function parseMigrateConfigCommand(inputArgs) {
     let configRoot = (0, project_1.defaultConfigRoot)();
+    let yes = false;
     for (const arg of inputArgs) {
         if (isHelpFlag(arg)) {
             printHelp('migrate-config');
         }
-        if (arg.startsWith('--')) {
+        if (arg === '--yes') {
+            yes = true;
+        }
+        else if (arg.startsWith('--')) {
             (0, utils_1.fail)(`unknown migrate-config option: ${arg}`);
         }
-        configRoot = arg;
+        else {
+            configRoot = arg;
+        }
     }
-    return { command: 'migrate-config', configRoot: path.resolve(configRoot) };
+    return { command: 'migrate-config', configRoot: path.resolve(configRoot), yes };
 }
 function isHelpFlag(value) {
     return value === '-h' || value === '--help';
@@ -306,9 +312,12 @@ function renderHelp(topic) {
         ],
         'migrate-config': [
             'Usage:',
-            '  agent-run migrate-config [config-root]',
+            '  agent-run migrate-config [--yes] [config-root]',
             '',
             'Convert an existing agent config tree to the current manifest and global-template layout.',
+            '',
+            'Options:',
+            '  --yes  Confirm tracked Git moves without prompting',
             ''
         ]
     };
@@ -331,7 +340,7 @@ function renderHelp(topic) {
         '  generate [path]                       Create a sparse profile marker and render output',
         '  edit [path]                           Create or open local.md.njk',
         '  update [--all] [path]                 Regenerate existing profile output',
-        '  migrate-config [config-root]           Convert existing config tree layout',
+        '  migrate-config [--yes] [config-root]   Convert existing config tree layout',
         '',
         'Global options:',
         '  -h, --help         Show this help text',

package/dist/commands.js

@@ -59,9 +59,9 @@ function runTool(parsed) {
         (0, utils_1.fail)(profileResult.reason);
     }
     const profile = profileResult.profile;
+    const configRoot = (0, project_1.defaultConfigRoot)(projectRoot);
+    const agentDir = path.join(configRoot, profile);
     if (wrapperArgs.show) {
-        const configRoot = (0, project_1.defaultConfigRoot)(projectRoot);
-        const agentDir = path.join(configRoot, profile);
         (0, utils_1.verbose)(`profile=${profile} configRoot=${configRoot} agentPath=${agentDir}`);
         requireProfile(command, agentDir);
         showToolProfile(command, projectRoot, agentDir);
@@ -70,11 +70,10 @@ function runTool(parsed) {
     if (wrapperArgs.create) {
         runGenerate({ command: 'generate', targetPath: projectRoot });
     }
-    const configRoot = (0, project_1.defaultConfigRoot)(projectRoot);
-    const agentDir = path.join(configRoot, profile);
     (0, utils_1.verbose)(`profile=${profile} configRoot=${configRoot} agentPath=${agentDir}`);
     prepareConfigRoot(configRoot);
     requireProfile(command, agentDir);
+    migrateProfileOnStart(configRoot, agentDir, false);
     const preview = (0, renderer_1.renderProfile)(projectRoot, agentDir, true, command);
     ensureToolEnabled(preview.context, command);
     if (wrapperArgs.generate) {
@@ -158,6 +157,7 @@ function runGenerate(parsed) {
         return;
     }
     const agentDir = initializeProfileSource(projectRoot, true);
+    migrateProfileOnStart((0, project_1.defaultConfigRoot)(projectRoot), agentDir, false);
     printUpdateSummary((0, renderer_1.syncAgentProfile)(projectRoot, agentDir));
 }
 function runSetup(parsed) {
@@ -170,7 +170,9 @@ function runSetup(parsed) {
         (0, utils_1.fail)(`starter config skeleton not found: ${sourcePath}`);
     }
     (0, config_tree_1.copySkeletonTree)(sourcePath, configRoot, new Set(['starter']));
+    (0, config_tree_1.ensurePortableSystemdFiles)(configRoot);
     const agentDir = path.join(configRoot, profile);
+    migrateProfileOnStart(configRoot, agentDir, false);
     (0, config_tree_1.copySkeletonTree)(path.join(sourcePath, 'starter', 'basic-project'), agentDir);
     if (profile !== detectedProfile) {
         writeProjectProfileMapping(projectRoot, profile);
@@ -193,9 +195,9 @@ function confirmProfile(detectedProfile) {
     }
     return requireValidProfile(promptLine('Profile (org/repo): '));
 }
-function promptLine(prompt) {
+function promptLine(prompt, nonInteractiveMessage = 'setup requires a profile argument when input is not interactive') {
     if (!process.stdin.isTTY) {
-        (0, utils_1.fail)('setup requires a profile argument when input is not interactive');
+        (0, utils_1.fail)(nonInteractiveMessage);
     }
     process.stdout.write(prompt);
     const bytes = [];
@@ -234,6 +236,7 @@ function runEdit(parsed) {
         return;
     }
     const agentDir = initializeProfileSource(projectRoot, false);
+    migrateProfileOnStart((0, project_1.defaultConfigRoot)(projectRoot), agentDir, false);
     const editPath = (0, manifest_1.createDefaultLocalFile)(agentDir);
     (0, renderer_1.syncAgentProfile)(projectRoot, agentDir);
     process.stdout.write(`Edit: ${editPath}\n`);
@@ -254,6 +257,7 @@ function runUpdate(parsed) {
     const agentDir = (0, project_1.resolveAgentDir)(projectRoot);
     prepareConfigRoot(configRoot);
     requireProfile(null, agentDir);
+    migrateProfileOnStart(configRoot, agentDir, false);
     printUpdateSummary((0, renderer_1.syncAgentProfile)(projectRoot, agentDir));
 }
 function runUpdateAll(targetPath) {
@@ -264,6 +268,7 @@ function runUpdateAll(targetPath) {
     prepareConfigRoot(configRoot);
     const profileDirs = (0, config_tree_1.findProfileDirs)(configRoot);
     for (const agentDir of profileDirs) {
+        migrateProfileOnStart(configRoot, agentDir, false);
         const profile = path.relative(configRoot, agentDir).replace(/\\/g, '/');
         const projectRoot = (0, project_1.projectRootForProfile)(profile, configRoot);
         (0, renderer_1.syncAgentProfile)(projectRoot, agentDir, { configRoot, profile });
@@ -281,15 +286,16 @@ function runMigrateConfig(parsed) {
     (0, config_tree_1.migrateOldTemplates)(configRoot);
     (0, config_tree_1.ensureDefaultGlobalTemplates)(configRoot);
     (0, manifest_1.ensureRootDefaultsFile)(configRoot);
-    const profileDirs = (0, config_tree_1.findLegacyProfileDirs)(configRoot);
+    const profileDirs = (0, utils_1.uniqueSorted)([...(0, config_tree_1.findLegacyProfileDirs)(configRoot), ...(0, config_tree_1.findProfileDirs)(configRoot)]);
     let createdManifestCount = 0;
     let createdLocalCount = 0;
     let movedRuntimeCount = 0;
     let movedReviewCount = 0;
     let movedMemoryCount = 0;
     for (const agentDir of profileDirs) {
+        const layout = migrateProfileOnStart(configRoot, agentDir, parsed.yes);
         const localPath = path.join(agentDir, constants_1.LOCAL_TEMPLATE_FILE_NAME);
-        if (!fs.existsSync(localPath)) {
+        if (!fs.existsSync(localPath) && fs.existsSync(path.join(agentDir, 'AGENTS-MODS.md'))) {
             fs.writeFileSync(localPath, (0, config_tree_1.convertLegacyTemplateVars)(fs.readFileSync(path.join(agentDir, 'AGENTS-MODS.md'), 'utf8')), 'utf8');
             createdLocalCount += 1;
         }
@@ -299,7 +305,7 @@ function runMigrateConfig(parsed) {
         }
         movedRuntimeCount += (0, config_tree_1.migrateCodexRuntimeFiles)(agentDir);
         movedReviewCount += (0, config_tree_1.migrateLooseFiles)(agentDir, /^REVIEW(?:-.+)?\.md$/, 'reviews');
-        movedMemoryCount += (0, config_tree_1.migrateLooseFiles)(agentDir, /^memory.*\.md$/i, 'memories');
+        movedMemoryCount += layout.projectMemoryMoves;
     }
     process.stdout.write(`OK migrated ${configRoot}\n`);
     process.stdout.write(`Profiles converted: ${profileDirs.length}\n`);
@@ -309,6 +315,29 @@ function runMigrateConfig(parsed) {
     process.stdout.write(`Moved review files: ${movedReviewCount}\n`);
     process.stdout.write(`Moved memory files: ${movedMemoryCount}\n`);
 }
+function migrateProfileOnStart(configRoot, profileDir, assumeYes) {
+    const result = (0, config_tree_1.migrateProfileLayout)(configRoot, profileDir, ({ gitRoot, moves }) => {
+        process.stdout.write('agent-run: this profile uses an older project-memory layout.\n');
+        process.stdout.write(`Git working tree: ${gitRoot}\n`);
+        for (const move of moves) {
+            process.stdout.write(`  ${path.relative(gitRoot, move.source)} -> ${path.relative(gitRoot, move.target)}\n`);
+        }
+        if (assumeYes) {
+            return true;
+        }
+        const migrateCommand = (0, utils_1.formatCommand)('agent-run', ['migrate-config', '--yes', configRoot]);
+        const message = `tracked project-memory files need migration; rerun interactively or run \`${migrateCommand}\``;
+        const answer = promptLine('Stage these moves with git mv? [Y/n] ', message).trim().toLowerCase();
+        return answer === '' || answer === 'y' || answer === 'yes';
+    });
+    if (result.gitMoves > 0) {
+        process.stdout.write(`Staged Git moves: ${result.gitMoves}\n`);
+    }
+    if (result.runtimeMoves > 0) {
+        process.stdout.write(`Moved local Codex runtime entries: ${result.runtimeMoves}\n`);
+    }
+    return result;
+}
 function runCheck(parsed) {
     if (parsed.all) {
         const report = (0, checks_1.checkSourceTree)(parsed.targetPath);
@@ -328,6 +357,7 @@ function prepareConfigRoot(configRoot) {
     (0, config_tree_1.ensureConfigRootLayout)(configRoot);
     (0, config_tree_1.ensureConfigRootGitignore)(configRoot);
     (0, config_tree_1.ensureDefaultGlobalTemplates)(configRoot);
+    (0, config_tree_1.ensurePortableSystemdFiles)(configRoot);
 }
 function activeProject(targetPath, action) {
     const projectRoot = (0, project_1.findProjectRoot)(targetPath);

package/dist/config-tree.js

@@ -3,14 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureConfigRootLayout = ensureConfigRootLayout;
 exports.ensureConfigRootGitignore = ensureConfigRootGitignore;
 exports.ensureDefaultGlobalTemplates = ensureDefaultGlobalTemplates;
+exports.ensurePortableSystemdFiles = ensurePortableSystemdFiles;
 exports.migrateOldTemplates = migrateOldTemplates;
 exports.findLegacyProfileDirs = findLegacyProfileDirs;
 exports.findProfileDirs = findProfileDirs;
 exports.convertLegacyTemplateVars = convertLegacyTemplateVars;
 exports.migrateCodexRuntimeFiles = migrateCodexRuntimeFiles;
 exports.migrateLooseFiles = migrateLooseFiles;
+exports.describeLegacyProfileLayout = describeLegacyProfileLayout;
+exports.migrateProfileLayout = migrateProfileLayout;
 exports.starterConfigRootPath = starterConfigRootPath;
 exports.copySkeletonTree = copySkeletonTree;
+const childProcess = require("child_process");
 const fs = require("fs");
 const path = require("path");
 const constants_1 = require("./constants");
@@ -68,6 +72,25 @@ function ensureDefaultGlobalTemplates(configRoot) {
         }
     }
 }
+function ensurePortableSystemdFiles(configRoot) {
+    const packageRoot = path.resolve(__dirname, '..');
+    const files = new Map([
+        ['install-systemd-jobs.sh', { source: 'scripts/install-systemd-jobs.sh', mode: 0o755 }],
+        ['update-ai-tools.sh', { source: 'scripts/update-ai-tools.sh', mode: 0o755 }],
+        ['ai-tools-update.service', { source: 'ops/systemd/ai-tools-update.service', mode: 0o644 }],
+        ['ai-tools-update.timer', { source: 'ops/systemd/ai-tools-update.timer', mode: 0o644 }]
+    ]);
+    for (const [targetName, asset] of files) {
+        const sourcePath = path.join(packageRoot, asset.source);
+        const targetPath = path.join(configRoot, targetName);
+        if (!fs.existsSync(sourcePath)) {
+            continue;
+        }
+        fs.copyFileSync(sourcePath, targetPath);
+        fs.chmodSync(targetPath, asset.mode);
+        (0, utils_1.verbose)(`updated ${targetPath}`);
+    }
+}
 function migrateOldTemplates(configRoot) {
     const oldCodeTemplate = path.join(configRoot, 'templates', 'AGENTS-CODE.md');
     const newCodeTemplate = path.join(configRoot, 'global', 'agents', 'code.md.njk');
@@ -150,6 +173,232 @@ function migrateLooseFiles(agentDir, pattern, targetDirName) {
     }
     return moved;
 }
+function describeLegacyProfileLayout(profileDir) {
+    const paths = [];
+    const legacyMemoryDir = path.join(profileDir, 'memory');
+    if (fs.existsSync(legacyMemoryDir)) {
+        paths.push(legacyMemoryDir);
+    }
+    for (const filePath of legacyProjectMemoryFiles(profileDir)) {
+        paths.push(filePath);
+    }
+    const legacyCodexHome = path.join(profileDir, 'memories', 'codex-home');
+    if (fs.existsSync(legacyCodexHome) || (0, utils_1.isSymlink)(legacyCodexHome)) {
+        paths.push(legacyCodexHome);
+    }
+    return [...new Set(paths)].sort();
+}
+function migrateProfileLayout(configRoot, profileDir, confirmGitMoves) {
+    const projectMoves = planProjectMemoryMoves(profileDir);
+    validateMoveTargets(projectMoves);
+    const git = findGitWorktree(configRoot);
+    const trackedMoves = git === null ? [] : projectMoves.filter((move) => isTrackedByGit(git, move.source));
+    if (git !== null && trackedMoves.length > 0 && !confirmGitMoves({ gitRoot: git.root, moves: trackedMoves })) {
+        throw new Error('profile layout migration declined; no files were moved');
+    }
+    let gitMoves = 0;
+    for (const move of projectMoves) {
+        fs.mkdirSync(path.dirname(move.target), { recursive: true });
+        if (git !== null && trackedMoves.includes(move)) {
+            runGitMove(git, move);
+            gitMoves += 1;
+        }
+        else {
+            fs.renameSync(move.source, move.target);
+        }
+        removeEmptyParents(path.dirname(move.source), profileDir);
+        (0, utils_1.verbose)(`moved project memory ${move.source} -> ${move.target}`);
+    }
+    removeEmptyParents(path.join(profileDir, 'memory'), profileDir);
+    removeEmptyParents(path.join(profileDir, 'memories'), profileDir);
+    const runtimeMoves = migrateLegacyCodexHome(profileDir);
+    return { gitMoves, projectMemoryMoves: projectMoves.length, runtimeMoves };
+}
+function planProjectMemoryMoves(profileDir) {
+    const targetDir = path.join(profileDir, 'notes', 'memory');
+    const moves = [];
+    const legacyMemoryDir = path.join(profileDir, 'memory');
+    for (const source of listTreeFiles(legacyMemoryDir)) {
+        moves.push({ source, target: path.join(targetDir, path.relative(legacyMemoryDir, source)) });
+    }
+    for (const source of legacyProjectMemoryFiles(profileDir)) {
+        moves.push({ source, target: path.join(targetDir, path.basename(source)) });
+    }
+    return moves.sort((left, right) => left.source.localeCompare(right.source));
+}
+function legacyProjectMemoryFiles(profileDir) {
+    const files = [];
+    for (const entry of safeReadDir(profileDir)) {
+        if (entry.isFile() && /^memory.*\.md$/i.test(entry.name)) {
+            files.push(path.join(profileDir, entry.name));
+        }
+    }
+    const legacyMemoriesDir = path.join(profileDir, 'memories');
+    for (const entry of safeReadDir(legacyMemoriesDir)) {
+        if (entry.isFile() && /\.md$/i.test(entry.name)) {
+            files.push(path.join(legacyMemoriesDir, entry.name));
+        }
+    }
+    return files.sort();
+}
+function safeReadDir(dir) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+function listTreeFiles(root) {
+    const files = [];
+    for (const entry of safeReadDir(root)) {
+        const filePath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...listTreeFiles(filePath));
+        }
+        else if (entry.isFile() || entry.isSymbolicLink()) {
+            files.push(filePath);
+        }
+    }
+    return files;
+}
+function validateMoveTargets(moves) {
+    const targets = new Set();
+    for (const move of moves) {
+        const target = path.resolve(move.target);
+        if (targets.has(target) || fs.existsSync(target) || (0, utils_1.isSymlink)(target)) {
+            throw new Error(`cannot migrate project memory because the destination already exists: ${move.target}`);
+        }
+        targets.add(target);
+    }
+}
+function findGitWorktree(configRoot) {
+    const searchPath = process.env.AGENT_RUN_REAL_PATH ?? process.env.PATH ?? '';
+    const gitCommand = findCommandOnPath('git', searchPath);
+    if (gitCommand === null) {
+        return null;
+    }
+    const env = { ...process.env, PATH: searchPath };
+    const result = childProcess.spawnSync(gitCommand, ['-C', configRoot, 'rev-parse', '--show-toplevel'], {
+        encoding: 'utf8',
+        env,
+        shell: false
+    });
+    if (result.status !== 0) {
+        return null;
+    }
+    const root = result.stdout.trim();
+    return root ? { command: gitCommand, env, root: path.resolve(root) } : null;
+}
+function findCommandOnPath(command, searchPath) {
+    const extensions = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+    for (const dir of searchPath.split(path.delimiter).filter(Boolean)) {
+        for (const extension of extensions) {
+            const candidate = path.join(dir, `${command}${extension}`);
+            try {
+                fs.accessSync(candidate, process.platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK);
+                return candidate;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+function isTrackedByGit(git, filePath) {
+    const relativePath = path.relative(git.root, filePath).replace(/\\/g, '/');
+    const result = childProcess.spawnSync(git.command, ['-C', git.root, '--literal-pathspecs', 'ls-files', '--error-unmatch', '--', relativePath], { encoding: 'utf8', env: git.env, shell: false });
+    return result.status === 0;
+}
+function runGitMove(git, move) {
+    const source = path.relative(git.root, move.source).replace(/\\/g, '/');
+    const target = path.relative(git.root, move.target).replace(/\\/g, '/');
+    const result = childProcess.spawnSync(git.command, ['-C', git.root, '--literal-pathspecs', 'mv', '--', source, target], {
+        encoding: 'utf8',
+        env: git.env,
+        shell: false
+    });
+    if (result.status !== 0) {
+        const detail = result.stderr.trim() || result.stdout.trim() || `git exited with status ${result.status}`;
+        throw new Error(`cannot migrate tracked project memory ${move.source}: ${detail}`);
+    }
+}
+function migrateLegacyCodexHome(profileDir) {
+    const source = path.join(profileDir, 'memories', 'codex-home');
+    if (!fs.existsSync(source) && !(0, utils_1.isSymlink)(source)) {
+        return 0;
+    }
+    const target = path.join(profileDir, constants_1.LIVE_DIR_NAME, 'memories', 'codex-home');
+    if (!fs.existsSync(target) && !(0, utils_1.isSymlink)(target)) {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.renameSync(source, target);
+        removeEmptyParents(path.dirname(source), profileDir);
+        (0, utils_1.verbose)(`moved Codex runtime ${source} -> ${target}`);
+        return 1;
+    }
+    const sourceIsDirectory = !(0, utils_1.isSymlink)(source) && fs.statSync(source).isDirectory();
+    const targetIsDirectory = !(0, utils_1.isSymlink)(target) && fs.statSync(target).isDirectory();
+    if (!sourceIsDirectory || !targetIsDirectory) {
+        const backupTarget = (0, utils_1.nextBackupPath)(target);
+        fs.renameSync(source, backupTarget);
+        removeEmptyParents(path.dirname(source), profileDir);
+        (0, utils_1.verbose)(`moved Codex runtime ${source} -> ${backupTarget}`);
+        return 1;
+    }
+    const moved = mergeRuntimeTree(source, target);
+    removeEmptyParents(path.dirname(source), profileDir);
+    return moved;
+}
+function mergeRuntimeTree(sourceDir, targetDir) {
+    let moved = 0;
+    fs.mkdirSync(targetDir, { recursive: true });
+    for (const entry of safeReadDir(sourceDir)) {
+        const source = path.join(sourceDir, entry.name);
+        let target = path.join(targetDir, entry.name);
+        if (entry.isDirectory() && !entry.isSymbolicLink()) {
+            const targetIsDirectory = fs.existsSync(target) && !(0, utils_1.isSymlink)(target) && fs.statSync(target).isDirectory();
+            if ((fs.existsSync(target) || (0, utils_1.isSymlink)(target)) && !targetIsDirectory) {
+                target = (0, utils_1.nextBackupPath)(target);
+            }
+            moved += mergeRuntimeTree(source, target);
+            continue;
+        }
+        const resolvedTarget = fs.existsSync(target) || (0, utils_1.isSymlink)(target) ? (0, utils_1.nextBackupPath)(target) : target;
+        fs.mkdirSync(path.dirname(resolvedTarget), { recursive: true });
+        fs.renameSync(source, resolvedTarget);
+        (0, utils_1.verbose)(`moved Codex runtime ${source} -> ${resolvedTarget}`);
+        moved += 1;
+    }
+    try {
+        fs.rmdirSync(sourceDir);
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+            throw error;
+        }
+    }
+    return moved;
+}
+function removeEmptyParents(startDir, stopDir) {
+    let dir = path.resolve(startDir);
+    const stop = path.resolve(stopDir);
+    while (dir !== stop && (0, utils_1.isSamePathOrDescendant)(dir, stop)) {
+        try {
+            fs.rmdirSync(dir);
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && ['ENOENT', 'ENOTEMPTY'].includes(String(error.code))) {
+                return;
+            }
+            throw error;
+        }
+        dir = path.dirname(dir);
+    }
+}
 function starterConfigRootPath() {
     return path.resolve(__dirname, '..', 'examples', 'basic-config', 'agent-config');
 }

package/dist/constants.js

@@ -11,7 +11,7 @@ exports.LIVE_DIR_NAME = 'live';
 exports.CONFIG_ROOT_OVERRIDE_ENV = 'AGENT_RUN_CONFIG_ROOT_OVERRIDE';
 exports.CONFIG_DIR_ENV = 'AGENT_CONFIG_DIR';
 exports.VERBOSE_ENV = 'AGENT_RUN_VERBOSE';
-exports.PACKAGE_VERSION = '0.99.28';
+exports.PACKAGE_VERSION = '0.99.29';
 exports.UNEXPANDED_TEMPLATE_RE = /\{\{[^}]+\}\}|\{%[^%]+%\}/;
 exports.LOCAL_AI_FILE_NAMES = new Set([
     'AGENTS.md',

package/dist/defaults.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultManifest = defaultManifest;
 exports.stringifyRootDefaults = stringifyRootDefaults;
 exports.defaultLocalTemplate = defaultLocalTemplate;
+exports.defaultProjectMemoryIndex = defaultProjectMemoryIndex;
 exports.defaultGlobalTemplates = defaultGlobalTemplates;
 exports.defaultToolInstructionsTemplate = defaultToolInstructionsTemplate;
 exports.defaultCodexConfigContent = defaultCodexConfigContent;
@@ -34,7 +35,8 @@ function defaultManifest(profile) {
             changesFile: '{{ projectRoot }}/CHANGES',
             reviewDir: '{{ profileDir }}/reviews',
             reviewFile: '{{ profileDir }}/reviews/REVIEW-{{ date }}.md',
-            memoriesDir: '{{ agentDir }}/memories'
+            memoriesDir: '{{ agentDir }}/memories',
+            projectMemoryDir: '{{ profileDir }}/notes/memory'
         }
     };
 }
@@ -71,6 +73,19 @@ function defaultLocalTemplate() {
         ''
     ].join('\n');
 }
+function defaultProjectMemoryIndex() {
+    return [
+        '# Project memory',
+        '',
+        'This directory contains durable notes for this project across agent sessions and machines.',
+        'Keep the notes short, factual, and free of secrets. Link additional topic files from this index.',
+        '',
+        '## Files',
+        '',
+        '- Add project memory files here as they are needed.',
+        ''
+    ].join('\n');
+}
 function defaultGlobalTemplates() {
     return new Map([
         ['global/agents/code.md.njk', defaultCodeAgentTemplate()],
@@ -293,6 +308,18 @@ function defaultToolInstructionsTemplate(isClaude) {
         '{{ paths.memoriesDir }}',
         '```',
         '',
+        'Project memory directory:',
+        '',
+        '```text',
+        '{{ paths.projectMemoryDir }}',
+        '```',
+        '',
+        'Native Codex memory directory:',
+        '',
+        '```text',
+        '{{ paths.nativeMemoryDir }}',
+        '```',
+        '',
         'Global memory directory:',
         '',
         '```text',
@@ -337,7 +364,8 @@ function defaultCodexConfigTemplate() {
         'writable_roots = [',
         '  {{ projectRoot | dump }},',
         '  {{ paths.reviewDir | dump }},',
-        '  {{ paths.memoriesDir | dump }}',
+        '  {{ paths.memoriesDir | dump }},',
+        '  {{ paths.projectMemoryDir | dump }}',
         ']',
         'network_access = false',
         ''
@@ -349,6 +377,7 @@ function defaultClaudeSettingsTemplate() {
         '    "AGENT_DIR": {{ agentDir | dump }},',
         '    "AGENT_PROFILE_DIR": {{ profileDir | dump }},',
         '    "AGENT_RUN_PROJECT_ROOT": {{ projectRoot | dump }},',
+        '    "AGENT_PROJECT_MEMORY_DIR": {{ paths.projectMemoryDir | dump }},',
         '    "AGENT_GLOBAL_MEMORY_DIR": {{ paths.globalMemoryDir | dump }}',
         '  }'
     ].join('\n');
@@ -377,7 +406,8 @@ function defaultCodexConfigContent(context) {
         'writable_roots = [',
         `  ${JSON.stringify(context.projectRoot)},`,
         `  ${JSON.stringify(context.paths.reviewDir)},`,
-        `  ${JSON.stringify(context.paths.memoriesDir)}`,
+        `  ${JSON.stringify(context.paths.memoriesDir)},`,
+        `  ${JSON.stringify(context.paths.projectMemoryDir)}`,
         ']',
         'network_access = false',
         ''
@@ -389,6 +419,7 @@ function defaultClaudeSettingsContent(context) {
             AGENT_DIR: context.agentDir,
             AGENT_PROFILE_DIR: context.profileDir,
             AGENT_RUN_PROJECT_ROOT: context.projectRoot,
+            AGENT_PROJECT_MEMORY_DIR: context.paths.projectMemoryDir,
             AGENT_GLOBAL_MEMORY_DIR: context.paths.globalMemoryDir
         }
     };

package/dist/manifest.js

@@ -165,7 +165,8 @@ function normalizeManifest(manifest, profile) {
             reviewDir: normalizeLegacyReviewPath(paths.reviewDir ?? fallbackPaths.reviewDir ?? '{{ profileDir }}/reviews'),
             reviewFile: normalizeLegacyReviewPath(paths.reviewFile ?? fallbackPaths.reviewFile ?? '{{ profileDir }}/reviews/REVIEW-{{ date }}.md'),
             reviewConsolidatedFile: paths.reviewConsolidatedFile ?? fallbackPaths.reviewConsolidatedFile,
-            memoriesDir: paths.memoriesDir ?? fallbackPaths.memoriesDir ?? '{{ agentDir }}/memories'
+            memoriesDir: paths.memoriesDir ?? fallbackPaths.memoriesDir ?? '{{ agentDir }}/memories',
+            projectMemoryDir: paths.projectMemoryDir ?? fallbackPaths.projectMemoryDir ?? '{{ profileDir }}/notes/memory'
         }
     };
 }

package/dist/renderer.js

@@ -51,11 +51,23 @@ function renderAgentSections(env, configRoot, manifest, context, trace) {
         }
         sections.push((0, templates_1.renderTemplateFile)(env, configRoot, include, context, trace));
     }
-    return sections.map((section, index) => {
+    const renderedSections = sections.map((section, index) => {
         const label = index === 0 ? manifest.agent.base : manifest.agent.includes[index - 1] ?? `section ${index}`;
         (0, templates_1.assertNoUnexpandedTemplateVars)(label, section);
         return section.trimEnd();
     });
+    renderedSections.push(projectMemoryInstructions(context));
+    return renderedSections;
+}
+function projectMemoryInstructions(context) {
+    return [
+        '## Project Memory',
+        '',
+        `Project memory is stored in ${context.paths.projectMemoryDir}.`,
+        'Read README.md there before starting work when prior project context may matter, then read only the linked files relevant to the task.',
+        'Do not store secrets, raw chat transcripts, or temporary task state there.',
+        'Update project memory only when the user explicitly asks you to remember or update something for this project.'
+    ].join('\n');
 }
 function renderProfileFiles(env, configRoot, context, targetTool, trace) {
     const files = [];
@@ -210,6 +222,7 @@ function checkRenderedFiles(rendered, findings) {
 function checkRuntimeDirectories(context, findings) {
     for (const dir of [
         context.paths.reviewDir,
+        context.paths.projectMemoryDir,
         context.paths.memoriesDir,
         context.paths.codexHomeDir,
         context.paths.liveDir,
@@ -303,6 +316,7 @@ function resolveProfileOverrideTemplate(configRoot, context, overrideFileName, g
 function syncRuntimeDirs(context) {
     for (const dir of [
         context.paths.reviewDir,
+        context.paths.projectMemoryDir,
         context.paths.memoriesDir,
         context.paths.codexHomeDir,
         context.paths.codexSkillsDir,
@@ -312,6 +326,11 @@ function syncRuntimeDirs(context) {
     ]) {
         fs.mkdirSync(dir, { recursive: true });
     }
+    const projectMemoryIndex = path.join(context.paths.projectMemoryDir, 'README.md');
+    if (!fs.existsSync(projectMemoryIndex)) {
+        fs.writeFileSync(projectMemoryIndex, (0, defaults_1.defaultProjectMemoryIndex)(), 'utf8');
+        (0, utils_1.verbose)(`created ${projectMemoryIndex}`);
+    }
     migrateLiveReviewFiles(context);
     removeLegacyCodexSkillDirs(context);
     removeLegacyCodeReviewSkillDirs(context);

package/dist/templates.js

@@ -35,6 +35,7 @@ function buildRenderContext(projectRoot, profileDir, configRoot, manifest, env)
     };
     const reviewDir = resolveRuntimePath(configRoot, manifest.paths.reviewDir, env, baseContext);
     const memoriesDir = resolveRuntimePath(configRoot, manifest.paths.memoriesDir, env, baseContext);
+    const projectMemoryDir = resolveRuntimePath(configRoot, manifest.paths.projectMemoryDir, env, baseContext);
     const codexHomeDir = path.join(memoriesDir, 'codex-home');
     const paths = {
         profileDir,
@@ -47,6 +48,8 @@ function buildRenderContext(projectRoot, profileDir, configRoot, manifest, env)
             : path.join(reviewDir, 'REVIEW.md'),
         memoriesDir,
         globalMemoryDir: path.join(configRoot, 'notes', 'memory'),
+        projectMemoryDir,
+        nativeMemoryDir: path.join(codexHomeDir, 'memories'),
         codexHomeDir,
         overridesDir: path.join(profileDir, 'overrides'),
         codexSkillsDir: path.join(codexHomeDir, 'skills'),

package/dist/tools.js

@@ -23,6 +23,7 @@ function runCodex(realBinary, permissionArgs, context, args, wrapperArgs) {
         AGENT_DIR: liveDir,
         AGENT_PROFILE_DIR: context.profileDir,
         AGENT_RUN_PROJECT_ROOT: projectRoot,
+        AGENT_PROJECT_MEMORY_DIR: context.paths.projectMemoryDir,
         AGENT_RUN_REAL_PATH: realPath,
         PATH: `${path.join(liveDir, 'bin')}${path.delimiter}${realPath}`
     };
@@ -30,6 +31,8 @@ function runCodex(realBinary, permissionArgs, context, args, wrapperArgs) {
     (0, process_1.execCommand)(realBinary, [
         ...permissionArgs,
         ...runtimeArgs,
+        '--add-dir',
+        context.paths.projectMemoryDir,
         '-C',
         projectRoot,
         ...(wrapperArgs.sandboxMode !== 'danger' && wrapperArgs.codexNetwork
@@ -51,12 +54,15 @@ function runClaude(realBinary, permissionArgs, context, args, wrapperArgs) {
         AGENT_DIR: liveDir,
         AGENT_PROFILE_DIR: context.profileDir,
         AGENT_RUN_PROJECT_ROOT: context.projectRoot,
+        AGENT_PROJECT_MEMORY_DIR: context.paths.projectMemoryDir,
         AGENT_RUN_REAL_PATH: realPath,
         PATH: `${path.join(liveDir, 'bin')}${path.delimiter}${realPath}`
     };
     const runtimeArgs = wrapperArgs.sandboxMode === 'danger' ? getDangerArgs('claude') : permissionArgs;
     (0, process_1.execCommand)(realBinary, [
         ...runtimeArgs,
+        '--add-dir',
+        context.paths.projectMemoryDir,
         '--append-system-prompt-file',
         claudePath,
         '--settings',

package/examples/basic-config/README.md

@@ -9,7 +9,8 @@ It contains two pieces:
   config root.
 - `agent-config/`: a complete config root with shared manifest defaults, global
   templates, snippets, skill templates, a personal memory skill, a sparse
-  profile manifest, profile-local instructions, and profile overrides.
+  profile manifest, durable project memory, profile-local instructions, and
+  profile overrides.
 
 Try it from this repository after building:
 

package/examples/basic-config/agent-config/agent-run.defaults.jsonc

@@ -33,6 +33,7 @@
     "changesFile": "{{ projectRoot }}/CHANGES",
     "reviewDir": "{{ profileDir }}/reviews",
     "reviewFile": "{{ profileDir }}/reviews/REVIEW-{{ date }}.md",
-    "memoriesDir": "{{ agentDir }}/memories"
+    "memoriesDir": "{{ agentDir }}/memories",
+    "projectMemoryDir": "{{ profileDir }}/notes/memory"
   }
 }

package/examples/basic-config/agent-config/global/tool-templates/AGENTS.md.njk

@@ -14,6 +14,8 @@ Do not edit this generated file. Edit root defaults or profile-specific source f
 - reviewFile: `{{ paths.reviewFile }}`
 - reviewConsolidatedFile: `{{ paths.reviewConsolidatedFile }}`
 - memoriesDir: `{{ paths.memoriesDir }}`
+- nativeMemoryDir: `{{ paths.nativeMemoryDir }}`
+- projectMemoryDir: `{{ paths.projectMemoryDir }}`
 - globalMemoryDir: `{{ paths.globalMemoryDir }}`
 
 ## Skills

package/examples/basic-config/agent-config/global/tool-templates/CLAUDE.md.njk

@@ -6,4 +6,5 @@
 {% endfor %}
 Claude reads this file from the private agent directory.
 
+projectMemoryDir: `{{ paths.projectMemoryDir }}`
 globalMemoryDir: `{{ paths.globalMemoryDir }}`

package/examples/basic-config/agent-config/global/tool-templates/claude-settings.json.njk

@@ -3,6 +3,7 @@
     "AGENT_DIR": {{ agentDir | dump }},
     "AGENT_PROFILE_DIR": {{ profileDir | dump }},
     "AGENT_RUN_PROJECT_ROOT": {{ projectRoot | dump }},
+    "AGENT_PROJECT_MEMORY_DIR": {{ paths.projectMemoryDir | dump }},
     "AGENT_GLOBAL_MEMORY_DIR": {{ paths.globalMemoryDir | dump }},
     "STARTER_PROFILE": {{ profile | dump }}
   },
@@ -15,6 +16,7 @@
     "AGENT_DIR": {{ agentDir | dump }},
     "AGENT_PROFILE_DIR": {{ profileDir | dump }},
     "AGENT_RUN_PROJECT_ROOT": {{ projectRoot | dump }},
+    "AGENT_PROJECT_MEMORY_DIR": {{ paths.projectMemoryDir | dump }},
     "AGENT_GLOBAL_MEMORY_DIR": {{ paths.globalMemoryDir | dump }},
     "STARTER_PROFILE": {{ profile | dump }}
   }

package/examples/basic-config/agent-config/global/tool-templates/codex-config.toml.njk

@@ -7,6 +7,7 @@ sandbox_mode = "workspace-write"
 writable_roots = [
   {{ projectRoot | dump }},
   {{ paths.reviewDir | dump }},
-  {{ paths.memoriesDir | dump }}
+  {{ paths.memoriesDir | dump }},
+  {{ paths.projectMemoryDir | dump }}
 ]
 network_access = false

package/examples/basic-config/agent-config/starter/basic-project/notes/memory/README.md

@@ -0,0 +1,8 @@
+# Project memory
+
+This directory contains durable notes for this project across agent sessions and machines.
+Keep the notes short, factual, and free of secrets. Link additional topic files from this index.
+
+## Files
+
+- Add project memory files here as they are needed.

package/examples/basic-config/agent-config/starter/basic-project/overrides/claude-settings.json.njk

@@ -3,6 +3,7 @@
     "AGENT_DIR": {{ agentDir | dump }},
     "AGENT_PROFILE_DIR": {{ profileDir | dump }},
     "AGENT_RUN_PROJECT_ROOT": {{ projectRoot | dump }},
+    "AGENT_PROJECT_MEMORY_DIR": {{ paths.projectMemoryDir | dump }},
     "AGENT_GLOBAL_MEMORY_DIR": {{ paths.globalMemoryDir | dump }},
     "STARTER_PROFILE": {{ profile | dump }},
     "STARTER_OVERRIDE": "true"
@@ -16,6 +17,7 @@
     "AGENT_DIR": {{ agentDir | dump }},
     "AGENT_PROFILE_DIR": {{ profileDir | dump }},
     "AGENT_RUN_PROJECT_ROOT": {{ projectRoot | dump }},
+    "AGENT_PROJECT_MEMORY_DIR": {{ paths.projectMemoryDir | dump }},
     "AGENT_GLOBAL_MEMORY_DIR": {{ paths.globalMemoryDir | dump }},
     "STARTER_PROFILE": {{ profile | dump }},
     "STARTER_OVERRIDE": "true"

package/examples/basic-config/agent-config/starter/basic-project/overrides/codex-config.toml.njk

@@ -7,6 +7,7 @@ sandbox_mode = "workspace-write"
 writable_roots = [
   {{ projectRoot | dump }},
   {{ paths.reviewDir | dump }},
-  {{ paths.memoriesDir | dump }}
+  {{ paths.memoriesDir | dump }},
+  {{ paths.projectMemoryDir | dump }}
 ]
 network_access = false

package/ops/systemd/ai-tools-update.service

@@ -13,4 +13,4 @@ Environment=XDG_CONFIG_HOME=/root/.config
 Environment=NPM_CONFIG_PREFIX=/usr/local
 Environment=PNPM_HOME=/usr/local
 Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
-ExecStart=/usr/local/lib/agent-run/update-ai-tools.sh
+ExecStart=/usr/local/libexec/agent-run/update-ai-tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@technomoron/agent-run",
-  "version": "0.99.28",
+  "version": "0.99.29",
   "packageManager": "pnpm@10.28.1",
   "bin": {
     "agent-run": "dist/agent-run.js"

package/scripts/install-systemd-jobs.sh

@@ -19,10 +19,20 @@ USAGE
 }
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-INSTALL_LIB_DIR="${INSTALL_LIB_DIR:-/usr/local/lib/agent-run}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+INSTALL_LIBEXEC_DIR="${INSTALL_LIBEXEC_DIR:-${INSTALL_LIB_DIR:-/usr/local/libexec/agent-run}}"
 SYSTEMD_DIR="${SYSTEMD_DIR:-/etc/systemd/system}"
 ORIGINAL_ARGS=("$@")
 
+UPDATE_SCRIPT="$ROOT/scripts/update-ai-tools.sh"
+SERVICE_FILE="$ROOT/ops/systemd/ai-tools-update.service"
+TIMER_FILE="$ROOT/ops/systemd/ai-tools-update.timer"
+if [ ! -f "$UPDATE_SCRIPT" ]; then
+	UPDATE_SCRIPT="$SCRIPT_DIR/update-ai-tools.sh"
+	SERVICE_FILE="$SCRIPT_DIR/ai-tools-update.service"
+	TIMER_FILE="$SCRIPT_DIR/ai-tools-update.timer"
+fi
+
 INSTALL_AI_TOOLS=0
 DRY_RUN=0
 
@@ -71,10 +81,10 @@ run() {
 	"$@"
 }
 
-run install -d -m 0755 "$INSTALL_LIB_DIR" "$SYSTEMD_DIR"
-run install -m 0755 "$ROOT/scripts/update-ai-tools.sh" "$INSTALL_LIB_DIR/update-ai-tools.sh"
-run install -m 0644 "$ROOT/ops/systemd/ai-tools-update.service" "$SYSTEMD_DIR/ai-tools-update.service"
-run install -m 0644 "$ROOT/ops/systemd/ai-tools-update.timer" "$SYSTEMD_DIR/ai-tools-update.timer"
+run install -d -m 0755 "$INSTALL_LIBEXEC_DIR" "$SYSTEMD_DIR"
+run install -m 0755 "$UPDATE_SCRIPT" "$INSTALL_LIBEXEC_DIR/update-ai-tools"
+run install -m 0644 "$SERVICE_FILE" "$SYSTEMD_DIR/ai-tools-update.service"
+run install -m 0644 "$TIMER_FILE" "$SYSTEMD_DIR/ai-tools-update.timer"
 
 if [ "$INSTALL_AI_TOOLS" -eq 1 ]; then
 	run systemctl daemon-reload

package/scripts/update-ai-tools.sh

@@ -6,18 +6,44 @@ export NPM_CONFIG_PREFIX="${NPM_CONFIG_PREFIX:-/usr/local}"
 export PNPM_HOME="${PNPM_HOME:-/usr/local}"
 export PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:${PATH:-}"
 
-NPM_BIN="${AI_TOOLS_NPM_BIN:-/usr/local/bin/npm}"
+NPM_BIN="${AI_TOOLS_NPM_BIN:-/usr/bin/npm}"
+NODE_BIN="${AI_TOOLS_NODE_BIN:-/usr/bin/node}"
 APT_GET_BIN="${AI_TOOLS_APT_GET_BIN:-/usr/bin/apt-get}"
 
 AI_TOOLS_NPM_PACKAGES="${AI_TOOLS_NPM_PACKAGES:-npm@latest pnpm@latest corepack@latest fallow@latest ripgrep@latest pm2@latest tsx@latest typescript@latest @openai/codex@latest @anthropic-ai/claude-code@latest @technomoron/agent-run@latest}"
 AI_TOOLS_PNPM_PACKAGE="${AI_TOOLS_PNPM_PACKAGE:-pnpm@latest}"
 AI_TOOLS_APT_PACKAGES="${AI_TOOLS_APT_PACKAGES:-gh}"
+AI_TOOLS_CLEAN_BINS="${AI_TOOLS_CLEAN_BINS:-agent-run claude codex}"
+AI_TOOLS_SYSTEM_BIN_DIRS="${AI_TOOLS_SYSTEM_BIN_DIRS:-/usr/local/bin /usr/bin}"
 
 if [ "$(id -u)" -ne 0 ]; then
 	echo "update-ai-tools.sh must run as root" >&2
 	exit 1
 fi
 
+clean_tool_bins() {
+	local bin_dir="$1"
+	local bin_name
+	local -a bin_names
+
+	[ -d "$bin_dir" ] || return 0
+	read -r -a bin_names <<<"$AI_TOOLS_CLEAN_BINS"
+	for bin_name in "${bin_names[@]}"; do
+		case "$bin_name" in
+			agent-run|claude|codex)
+				rm -f -- "$bin_dir/$bin_name"
+				;;
+			*)
+				echo "Refusing to clean unexpected AI tool bin: $bin_name" >&2
+				exit 1
+				;;
+		esac
+	done
+}
+
+target_bin_dir="${NPM_CONFIG_PREFIX%/}/bin"
+clean_tool_bins "$target_bin_dir"
+
 if [ -n "$AI_TOOLS_NPM_PACKAGES" ]; then
 	read -r -a npm_packages <<<"$AI_TOOLS_NPM_PACKAGES"
 	"$NPM_BIN" install -g --force "${npm_packages[@]}"
@@ -30,9 +56,18 @@ if [ -n "$AI_TOOLS_PNPM_PACKAGE" ]; then
 	"$NPM_BIN" install -g --force "${pnpm_packages[@]}"
 fi
 
+# Once the new launchers are installed, remove exact-name duplicates from the
+# other conventional system prefix so PATH ordering cannot select a stale copy.
+read -r -a system_bin_dirs <<<"$AI_TOOLS_SYSTEM_BIN_DIRS"
+for system_bin_dir in "${system_bin_dirs[@]}"; do
+	if [ "${system_bin_dir%/}" != "${target_bin_dir%/}" ]; then
+		clean_tool_bins "$system_bin_dir"
+	fi
+done
+
 CLAUDE_INSTALL="$("$NPM_BIN" root -g)/@anthropic-ai/claude-code/install.cjs"
 if [ -f "$CLAUDE_INSTALL" ]; then
-	/usr/local/bin/node "$CLAUDE_INSTALL"
+	"$NODE_BIN" "$CLAUDE_INSTALL"
 fi
 
 if [ -n "$AI_TOOLS_APT_PACKAGES" ] && command -v "$APT_GET_BIN" >/dev/null 2>&1; then