@technomoron/agent-run 0.99.43 → 0.99.45

package/CHANGES

@@ -1,6 +1,25 @@
 CHANGES
 =======
 
+Version 0.99.45 (2026-10-14)
+----------------------------
+* Move automatic session cleanup out of interactive startup and exit into
+  scheduled maintenance, using the hourly AI tools timer on Linux.
+* Add --clean-old and per-user cleanup.env retention settings, defaulting to
+  seven days; set AGENT_RUN_SESSION_RETENTION_DAYS=0 to disable retention cleanup.
+* Add hourly Windows session cleanup as a hidden, unelevated scheduled task.
+* Run Linux cleanup as explicitly selected normal users and preserve native
+  session deletion and history maintenance.
+
+Version 0.99.44 (2026-10-14)
+----------------------------
+* Remove local agent sessions last modified more than seven days ago before
+  startup, including Codex SQLite history, using native deletion where needed.
+* Add --clean to delete all saved sessions for selected agents while preserving
+  authentication, settings, skills and brain knowledge.
+* Check the configured brain MCP connection before launching an agent, and
+  explain socket ownership and permission failures.
+
 Version 0.99.43 (2026-09-25)
 ----------------------------
 * Report startup errors without a stack trace and include file ownership and

package/README.md

@@ -281,7 +281,7 @@ Config root:
 
 ## Commands
 
-Global flag:
+Global flags:
 
 - `-h`, `--help`: show wrapper help for `agent-run` and the built-in commands
 - `-v`, `--verbose`: print path resolution, file creation, include expansion,
@@ -290,6 +290,35 @@ Global flag:
 `agent-run codex --help`, `agent-run claude --help`, `agent-run gemini --help`,
 and `agent-run grok --help` pass `--help` through to the underlying tool.
 
+Session cleanup runs separately from interactive agent startup and exit. The
+hourly AI tool timer cleans sessions older than seven days by default for selected
+users. Set retention in `~/.agent-run/cleanup.env`:
+
+```sh
+AGENT_RUN_SESSION_RETENTION_DAYS=7
+```
+
+Use a non-negative whole number of days; `0` disables retention cleanup.
+An environment value overrides the file. `--configdir PATH` selects another
+configuration root and its `cleanup.env`. Sessions exactly at the retention
+boundary are retained. Authentication, settings, skills and brain knowledge are
+preserved. Run retention cleanup manually with `agent-run --clean-old all`.
+
+Delete all saved sessions for selected agents without launching an agent:
+
+```sh
+agent-run --clean all
+agent-run --clean codex,claude
+agent-run --clean grok gemini
+```
+
+`--configdir PATH` selects the configuration tree to scan. The native user homes
+are also included. Codex and Grok deletion requires an installed CLI with its
+native deletion command; Codex SQLite history is included. Failed or unsupported
+deletions are reported and retained; explicit cleanup exits with status 1 if any
+operation fails. A current session identified in the environment is skipped.
+Symlinks and paths owned by a different user are not cleaned.
+
 For any native agent command, use `--generate` to generate profile files
 without launching the underlying tool.
 
@@ -1067,6 +1096,8 @@ The supplied service uses `serve --pull`. On startup this pulls the configuratio
 repository with `--ff-only --no-rebase` when it is clean and has an upstream.
 Dirty checkouts and missing upstreams are skipped. Divergence or network failures
 are reported in the service journal and the service continues with local files.
+Before launching any configured agent, agent-run initializes its enabled brain MCP connection and calls `brain_status`. If this fails, launch stops with the underlying error. A disabled brain MCP connection also blocks launch when brain is enabled. Run the agent and brain service as the same user; private socket ownership is enforced. `--none` remains an explicit configuration bypass.
+
 Startup never commits, pushes, stashes, or rebases local work. Omit `--pull` to
 disable this behavior for a manually launched service.
 
@@ -1133,6 +1164,25 @@ starts at boot without an interactive login, and restarts it to load the update.
 No accounts are selected by default. The service remains owned by the selected
 user and listens on that user's private Unix socket.
 
+After a successful timer update, session cleanup runs as each selected user.
+Set `AI_TOOLS_CLEANUP_USERS="bjorn"` in `/etc/default/ai-tools-update` to select
+accounts; if unset, it uses `AI_TOOLS_BRAIN_USERS`. An explicitly empty value
+disables scheduled cleanup. Each user's `~/.agent-run/cleanup.env` controls
+retention, defaulting to seven days. Failures appear in the systemd journal.
+
+On Windows, install hourly cleanup for the current user from PowerShell:
+
+```powershell
+$prefix = npm.cmd prefix -g
+& "$prefix\node_modules\@technomoron\agent-run\scripts\install-windows-cleanup.ps1"
+```
+
+The `Agent Session Cleanup` task runs hidden without elevation while the user is
+signed in, starting ten minutes after installation and repeating hourly. It uses
+the same `cleanup.env` and seven-day default. Pass `-ConfigRoot PATH` to select
+another configuration tree. Its latest output is in
+`<config-root>/runtime/cleanup.log`. The task skips overlapping runs.
+
 Node 24 or newer must be installed at `/usr/local/bin/node` before running the
 updater. `AI_TOOLS_AGENT_RUN_PACKAGE` can select a package version or a
 root-owned local package archive while testing an unpublished build; it defaults

package/dist/brain/server.js

@@ -116,7 +116,7 @@ function createBrainServer(store) {
 function requirePrivateSocketDirectory(socketPath) {
     const stat = fs.lstatSync(path.dirname(socketPath));
     if (!stat.isDirectory() || stat.uid !== process.getuid() || (stat.mode & 0o077) !== 0)
-        throw new Error('The socket directory must be owned by the current user with mode 0700.');
+        throw new Error(`The socket directory ${path.dirname(socketPath)} must be owned by the current user with mode 0700 (current uid ${process.getuid()}, owner uid ${stat.uid}, mode ${(stat.mode & 0o777).toString(8)}). Run agent-run and agent-brain as the same user.`);
 }
 async function serveApiCore(configRoot, socketPath) {
     if (process.platform !== 'win32') {

package/dist/cli.js

@@ -12,11 +12,28 @@ function parseInvocation(invokedTool, argv) {
     let command = normalizeCommandName(invokedTool);
     const options = extractGlobalOptions(argv);
     applyGlobalOptions(options);
+    if (command === null && options.args[0] && /^(--clean|--clean-old)(=|$)/.test(options.args[0])) {
+        return parseCleanCommand(options.args);
+    }
     if (command === null) {
         command = extractCommand(options.args);
     }
     return parseCommand(command, options.args);
 }
+function parseCleanCommand(args) {
+    const flag = args[0];
+    const olderOnly = flag === '--clean-old' || flag.startsWith('--clean-old=');
+    const name = olderOnly ? '--clean-old' : '--clean';
+    const values = [
+        ...(flag.includes('=') ? [flag.slice(name.length + 1)] : []),
+        ...args.slice(1)
+    ].flatMap((value) => value.split(','));
+    if (!values.length || values.some((value) => value !== 'all' && !types_1.AGENT_IDS.includes(value))
+        || (values.includes('all') && values.length !== 1)) {
+        (0, utils_1.fail)(`${name} requires all or a list of codex, claude, gemini, grok`);
+    }
+    return { command: 'clean', agents: values[0] === 'all' ? [...types_1.AGENT_IDS] : [...new Set(values)], ...(olderOnly ? { olderOnly: true } : {}) };
+}
 function applyGlobalOptions(options) {
     if (options.verbose) {
         process.env[constants_1.VERBOSE_ENV] = '1';
@@ -52,6 +69,8 @@ function parseCommand(command, args) {
         case 'create':
         case 'project':
             return { command, args };
+        case 'clean':
+            (0, utils_1.fail)('Use agent-run --clean all|codex,claude,gemini,grok');
         case 'compress':
             return parseCompressCommand(args);
         case 'check':
@@ -156,6 +175,8 @@ function parseRunCommand(command, inputArgs) {
     const args = [];
     let passthrough = false;
     for (const arg of inputArgs) {
+        if (!passthrough && /^(--clean|--clean-old)(=|$)/.test(arg))
+            (0, utils_1.fail)('Use --clean or --clean-old on its own: agent-run --clean-old all|codex,claude,gemini,grok');
         if (passthrough) {
             args.push(arg);
             continue;
@@ -380,6 +401,8 @@ function renderHelp(topic) {
         '                                           Run gemini with generated private config',
         '  grok [--none] [--create] [--local] [--show] [--generate] [--yolo|--sandboxed] [args...]',
         '                                           Run grok with generated private config',
+        '  --clean all|AGENTS                    Delete saved sessions for selected agents',
+        '  --clean-old all|AGENTS                Delete sessions older than configured retention (7 days)',
         '  compress [--agent NAME] [--scope SCOPE] [--dry-run]  Consolidate brain knowledge',
         '  setup [org/repo]                      Install the default tree and selected profile',
         '  check [--all] [path]                  Validate generated profile output',

package/dist/commands.js

@@ -13,6 +13,8 @@ const process_1 = require("./process");
 const project_1 = require("./project");
 const renderer_1 = require("./renderer");
 const spawn_agent_1 = require("./runtime/spawn-agent");
+const brain_preflight_1 = require("./runtime/brain-preflight");
+const clean_sessions_1 = require("./runtime/clean-sessions");
 const utils_1 = require("./utils");
 function main(invokedTool, argv) {
     try {
@@ -25,6 +27,11 @@ function main(invokedTool, argv) {
 }
 function dispatch(command) {
     switch (command.command) {
+        case 'clean': {
+            const root = (0, project_1.defaultConfigRoot)(process.cwd());
+            (0, clean_sessions_1.reportCleanup)((0, clean_sessions_1.cleanSessions)(root, command.agents, !command.olderOnly, Date.now(), command.olderOnly ? (0, clean_sessions_1.sessionRetentionDays)(root) : 7), true);
+            return;
+        }
         case 'compress':
             void runCompress(command).catch((error) => { process.stderr.write(`agent-run: ${(0, utils_1.formatError)(error)}\n`); process.exitCode = 1; });
             return;
@@ -57,7 +64,7 @@ function dispatch(command) {
             runMigrateConfig(command);
             return;
         default:
-            runTool(command);
+            void runTool(command).catch((error) => { process.stderr.write(`agent-run: ${(0, utils_1.formatError)(error)}\n`); process.exitCode = 1; });
     }
 }
 async function runCompress(command) {
@@ -96,11 +103,11 @@ async function runCompress(command) {
     if (process.platform === 'win32')
         prompt = prompt.replace(/\r?\n/g, ' ');
     // Use the normal adapters, configuration and permission modes. The prompt is one argv value.
-    runTool({ command: agent, args: agent === 'gemini' ? ['-i', prompt] : [prompt], wrapperArgs: {
+    await runTool({ command: agent, args: agent === 'gemini' ? ['-i', prompt] : [prompt], wrapperArgs: {
             none: false, create: false, local: false, show: false, generate: false, sandboxMode: null, codexNetwork: false
         } });
 }
-function runTool(parsed) {
+async function runTool(parsed) {
     const { args, command, wrapperArgs } = parsed;
     const adapter = (0, registry_1.getAgentAdapter)(command);
     const projectRoot = (0, project_1.findProjectRoot)(process.cwd());
@@ -144,6 +151,7 @@ function runTool(parsed) {
     }
     checkLocalAiFiles(command, projectRoot, agentDir, preview.context, wrapperArgs.local);
     const realBinary = (0, process_1.findRealBinary)(command);
+    await (0, brain_preflight_1.requireBrain)(preview.context);
     const rendered = (0, renderer_1.syncRenderedProfile)(preview);
     const runtime = rendered.runtimes[command];
     if (!runtime) {

package/dist/process.js

@@ -9,8 +9,8 @@ const path = require("path");
 const constants_1 = require("./constants");
 const utils_1 = require("./utils");
 const crossSpawn = require('cross-spawn');
-function findRealBinary(tool) {
-    const pathDirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+function findRealBinary(tool, searchPath = process.env.PATH ?? '') {
+    const pathDirs = searchPath.split(path.delimiter).filter(Boolean);
     const currentScriptArg = process.argv[1];
     const currentScript = currentScriptArg ? fs.realpathSync(currentScriptArg) : '';
     const wrappers = wrapperCandidates(tool);
@@ -31,7 +31,7 @@ function findRealBinary(tool) {
             return candidate;
         }
     }
-    (0, utils_1.fail)(`no ${tool} binary found in PATH`);
+    throw new Error(`no ${tool} binary found in PATH`);
 }
 function wrapperCandidates(tool) {
     const names = [

package/dist/project.js

@@ -12,6 +12,7 @@ exports.resolveProfile = resolveProfile;
 exports.resolveProfileResult = resolveProfileResult;
 exports.parseProfile = parseProfile;
 exports.projectRootForProfile = projectRootForProfile;
+exports.parseEnvFile = parseEnvFile;
 exports.defaultConfigRoot = defaultConfigRoot;
 const childProcess = require("child_process");
 const fs = require("fs");

package/dist/runtime/brain-preflight.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireBrain = requireBrain;
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/client/stdio.js");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
+const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
+const config_1 = require("../brain/config");
+const environment_1 = require("./environment");
+async function requireBrain(context) {
+    const server = context.mcpServers['agent-brain'];
+    if (!server?.enabled) {
+        if ((0, config_1.readBrainConfig)(context.configRoot)?.enabled)
+            throw new Error('Cannot start agent: agent-brain is enabled but its MCP connection is disabled or missing.');
+        return;
+    }
+    const client = new index_js_1.Client({ name: 'agent-run-preflight', version: '1.0.0' });
+    let diagnostics = '';
+    const transport = server.transport === 'stdio'
+        ? new stdio_js_1.StdioClientTransport({ command: server.command ?? '', args: server.args, cwd: server.cwd ?? context.projectRoot,
+            env: Object.fromEntries(Object.entries({ ...(0, environment_1.buildAgentEnvironment)(context), ...server.env }).filter((entry) => entry[1] !== undefined)), stderr: 'pipe' })
+        : server.transport === 'http'
+            ? new streamableHttp_js_1.StreamableHTTPClientTransport(new URL(server.url ?? ''), { requestInit: { headers: server.headers } })
+            : new sse_js_1.SSEClientTransport(new URL(server.url ?? ''), { requestInit: { headers: server.headers } });
+    if (transport instanceof stdio_js_1.StdioClientTransport)
+        transport.stderr?.on('data', (chunk) => { diagnostics = (diagnostics + chunk.toString()).slice(-8192); });
+    try {
+        await client.connect(transport, { timeout: 10000 });
+        const status = await client.callTool({ name: 'brain_status', arguments: {} }, undefined, { timeout: 10000 });
+        if (status.isError)
+            throw new Error(JSON.stringify(status.content));
+    }
+    catch (error) {
+        throw new Error(`Cannot start agent: agent-brain MCP check failed: ${error instanceof Error ? error.message : String(error)}${diagnostics.trim() ? `\n${diagnostics.trim()}` : ''}`);
+    }
+    finally {
+        await client.close();
+        await transport.close();
+    }
+}

package/dist/runtime/clean-sessions.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionRetentionDays = sessionRetentionDays;
+exports.cleanSessions = cleanSessions;
+exports.reportCleanup = reportCleanup;
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const node_sqlite_1 = require("node:sqlite");
+const cross_spawn_1 = require("cross-spawn");
+const process_1 = require("../process");
+const types_1 = require("../agents/types");
+const config_tree_1 = require("../config-tree");
+const manifest_1 = require("../manifest");
+const templates_1 = require("../templates");
+const project_1 = require("../project");
+const WEEK = 7 * 24 * 60 * 60 * 1000;
+const DAY = WEEK / 7;
+function sessionRetentionDays(configRoot) {
+    const file = path.join(configRoot, 'cleanup.env');
+    const settings = fs.existsSync(file) ? (0, project_1.parseEnvFile)(fs.readFileSync(file, 'utf8')) : {};
+    const value = process.env.AGENT_RUN_SESSION_RETENTION_DAYS ?? settings.AGENT_RUN_SESSION_RETENTION_DAYS ?? '7';
+    const days = Number(value);
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(days * DAY)) {
+        throw new Error('AGENT_RUN_SESSION_RETENTION_DAYS must be a non-negative whole number of days (0 disables retention cleanup).');
+    }
+    return days;
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// Do not follow symlinks, including symlinked parent directories or another user's home.
+function owned(file) {
+    const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+    if (!stat || stat.isSymbolicLink())
+        return undefined;
+    if (process.getuid && stat.uid !== process.getuid())
+        throw new Error(`Session path belongs to uid ${stat.uid}, current uid is ${process.getuid()}: ${file}`);
+    const parent = path.dirname(file);
+    if (parent !== file) {
+        const parentStat = fs.lstatSync(parent);
+        if (parentStat.isSymbolicLink())
+            return undefined;
+        // Shared ancestors such as /tmp need not belong to the user.
+        for (let dir = path.dirname(parent); path.dirname(dir) !== dir; dir = path.dirname(dir)) {
+            if (fs.lstatSync(dir).isSymbolicLink())
+                return undefined;
+        }
+    }
+    return stat;
+}
+function entries(dir) {
+    return owned(dir)?.isDirectory() ? fs.readdirSync(dir, { withFileTypes: true }) : [];
+}
+function files(dir) {
+    return entries(dir).flatMap((entry) => {
+        const file = path.join(dir, entry.name);
+        return entry.isDirectory() ? files(file) : entry.isFile() && owned(file)?.isFile() ? [file] : [];
+    });
+}
+function modified(paths) {
+    return Math.max(...paths.map((file) => owned(file)?.mtimeMs ?? Infinity));
+}
+function homes(configRoot, agent) {
+    const native = process.env[agent === 'claude' ? 'CLAUDE_CONFIG_DIR' : agent === 'gemini' ? 'GEMINI_CLI_HOME' : agent === 'grok' ? 'GROK_HOME' : 'CODEX_HOME'];
+    const result = [path.join(os.homedir(), `.${agent}`)];
+    if (native)
+        result.push(agent === 'gemini' ? path.join(native, '.gemini') : native);
+    if (agent === 'codex')
+        result.push(path.join(configRoot, 'runtime', 'codex'));
+    for (const profile of (0, config_tree_1.findProfileDirs)(configRoot)) {
+        const live = path.join(profile, 'live');
+        if (agent === 'codex') {
+            const profileName = path.relative(configRoot, profile).split(path.sep).join('/');
+            const manifest = (0, manifest_1.normalizeManifest)((0, manifest_1.loadManifest)(configRoot, profile, profileName), profileName);
+            const context = (0, templates_1.buildRenderContext)((0, project_1.projectRootForProfile)(profileName, configRoot), profile, configRoot, manifest, (0, templates_1.createNunjucksEnv)(configRoot));
+            result.push(context.paths.codexHomeDir);
+        }
+        if (agent === 'gemini')
+            result.push(path.join(live, 'gemini', 'home', '.gemini'));
+        if (agent === 'grok')
+            result.push(path.join(live, 'grok'));
+    }
+    return [...new Set(result.map((home) => {
+            const absolute = path.resolve(home);
+            const stat = fs.lstatSync(absolute, { throwIfNoEntry: false });
+            // Resolve system aliases such as macOS /var, but never follow a home symlink.
+            return stat && !stat.isSymbolicLink() ? fs.realpathSync(absolute) : absolute;
+        }))];
+}
+function fileSessions(home, agent) {
+    if (agent === 'grok') {
+        return entries(path.join(home, 'sessions')).filter((entry) => entry.isDirectory()).flatMap((group) => entries(path.join(home, 'sessions', group.name)).filter((entry) => entry.isDirectory() && UUID.test(entry.name)).map((entry) => {
+            const dir = path.join(home, 'sessions', group.name, entry.name);
+            return { id: entry.name, files: [dir], modified: modified([dir, ...files(dir)]) };
+        }));
+    }
+    if (agent === 'claude') {
+        return entries(path.join(home, 'projects')).filter((entry) => entry.isDirectory()).flatMap((group) => {
+            const dir = path.join(home, 'projects', group.name);
+            return entries(dir).filter((entry) => entry.isFile() && UUID.test(path.basename(entry.name, '.jsonl')) && entry.name.endsWith('.jsonl')).map((entry) => {
+                const id = path.basename(entry.name, '.jsonl');
+                const transcript = path.join(dir, entry.name);
+                const companions = [path.join(dir, id), path.join(home, 'file-history', id)].filter((file) => owned(file)?.isDirectory());
+                return { id, files: [transcript, ...companions], modified: modified([transcript, ...companions.flatMap(files)]) };
+            });
+        });
+    }
+    if (agent === 'gemini') {
+        return entries(path.join(home, 'tmp')).filter((entry) => entry.isDirectory()).flatMap((group) => {
+            const dir = path.join(home, 'tmp', group.name, 'chats');
+            return entries(dir).filter((entry) => entry.isFile() && entry.name.endsWith('.json')).map((entry) => {
+                const file = path.join(dir, entry.name);
+                return { id: entry.name, files: [file], modified: modified([file]) };
+            });
+        });
+    }
+    const sessions = new Map();
+    for (const dir of ['sessions', 'archived_sessions']) {
+        for (const file of files(path.join(home, dir)).filter((file) => file.endsWith('.jsonl'))) {
+            const id = path.basename(file, '.jsonl').slice(-36);
+            if (!UUID.test(id))
+                continue;
+            const previous = sessions.get(id);
+            sessions.set(id, { id, files: [...previous?.files ?? [], file], modified: Math.max(previous?.modified ?? 0, modified([file])) });
+        }
+    }
+    // Recent Codex keeps paginated history in SQLite; rollout files alone are incomplete.
+    for (const entry of entries(home).filter((entry) => entry.isFile() && /^state_\d+\.sqlite$/.test(entry.name))) {
+        const db = new node_sqlite_1.DatabaseSync(path.join(home, entry.name), { readOnly: true });
+        try {
+            for (const row of db.prepare('SELECT id, updated_at FROM threads').all()) {
+                if (typeof row.id !== 'string' || !UUID.test(row.id))
+                    continue;
+                const previous = sessions.get(row.id);
+                sessions.set(row.id, { id: row.id, files: previous?.files ?? [], modified: Math.max(previous?.modified ?? 0, Number(row.updated_at) * 1000) });
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
+    return [...sessions.values()];
+}
+function pruneIndexes(home, agent, ids) {
+    const jsonl = agent === 'claude' ? ['history.jsonl'] : agent === 'codex' ? ['history.jsonl', 'session_index.jsonl'] : [];
+    for (const name of jsonl) {
+        const file = path.join(home, name);
+        if (!owned(file)?.isFile())
+            continue;
+        const original = fs.readFileSync(file, 'utf8');
+        const lines = original.split(/(?<=\n)/).filter((line) => {
+            try {
+                const row = JSON.parse(line);
+                return !ids.has(row.sessionId ?? row.session_id ?? row.id);
+            }
+            catch {
+                return true;
+            }
+        });
+        if (lines.join('') !== original)
+            fs.writeFileSync(file, lines.join(''));
+    }
+    if (agent === 'claude') {
+        for (const group of entries(path.join(home, 'projects')).filter((entry) => entry.isDirectory())) {
+            const file = path.join(home, 'projects', group.name, 'sessions-index.json');
+            if (!owned(file)?.isFile())
+                continue;
+            const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (Array.isArray(data.entries)) {
+                data.entries = data.entries.filter((entry) => !ids.has(entry.sessionId ?? ''));
+                fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
+            }
+        }
+    }
+}
+function cleanSessions(configRoot, agents = types_1.AGENT_IDS, all = false, now = Date.now(), retentionDays = 7) {
+    return agents.map((agent) => {
+        const result = { agent, removed: 0, errors: [] };
+        if (!all && retentionDays === 0)
+            return result;
+        let directories;
+        try {
+            directories = homes(configRoot, agent);
+        }
+        catch (error) {
+            result.errors.push(error instanceof Error ? error.message : String(error));
+            return result;
+        }
+        for (const home of directories) {
+            try {
+                if (!owned(home)?.isDirectory())
+                    continue;
+                const removed = new Set();
+                for (const session of fileSessions(home, agent)) {
+                    if (!all && session.modified >= now - retentionDays * DAY)
+                        continue;
+                    if ([process.env.CODEX_THREAD_ID, process.env.CODEX_SESSION_ID, process.env.CLAUDE_SESSION_ID, process.env.GROK_SESSION_ID].includes(session.id)) {
+                        if (all)
+                            result.errors.push(`Skipped current session ${session.id}`);
+                        continue;
+                    }
+                    try {
+                        if (agent === 'codex' || agent === 'grok') {
+                            // Let the native CLI remove history and update its own databases/indexes.
+                            const binary = (0, process_1.findRealBinary)(agent, process.env.AGENT_RUN_REAL_PATH ?? process.env.PATH ?? '');
+                            const response = (0, cross_spawn_1.sync)(binary, agent === 'codex' ? ['delete', '--force', session.id] : ['sessions', 'delete', session.id], {
+                                env: { ...process.env, PATH: process.env.AGENT_RUN_REAL_PATH ?? process.env.PATH, [agent === 'codex' ? 'CODEX_HOME' : 'GROK_HOME']: home }, shell: false, encoding: 'utf8', timeout: 30000, maxBuffer: 1024 * 1024
+                            });
+                            if (response.error || response.status !== 0)
+                                throw new Error(response.error?.message ?? (response.stderr || response.stdout || `delete exited ${response.status}`).trim());
+                        }
+                        else {
+                            for (const file of session.files)
+                                if (owned(file))
+                                    fs.rmSync(file, { recursive: true, force: true });
+                        }
+                        if (session.files.some((file) => fs.existsSync(file)))
+                            throw new Error('Native deletion left session files in place');
+                        removed.add(session.id);
+                        result.removed++;
+                    }
+                    catch (error) {
+                        result.errors.push(`${home}: ${session.id}: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+                if (removed.size)
+                    pruneIndexes(home, agent, removed);
+            }
+            catch (error) {
+                result.errors.push(`${home}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        return result;
+    });
+}
+function reportCleanup(results, explicit = false) {
+    for (const result of results) {
+        if (explicit || result.removed)
+            process.stdout.write(`${result.agent}: removed ${result.removed} session(s)\n`);
+        for (const error of result.errors)
+            process.stderr.write(`agent-run: ${result.agent} session cleanup: ${error}\n`);
+    }
+    if (explicit && results.some((result) => result.errors.length))
+        process.exitCode = 1;
+}

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

@@ -15,3 +15,4 @@ Environment=PNPM_HOME=/usr/local
 Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
 EnvironmentFile=-/etc/default/ai-tools-update
 ExecStart=/usr/local/libexec/agent-run/update-ai-tools
+ExecStartPost=/usr/local/libexec/agent-run/cleanup-agent-sessions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@technomoron/agent-run",
-  "version": "0.99.43",
+  "version": "0.99.45",
   "packageManager": "pnpm@10.34.5",
   "bin": {
     "agent-run": "dist/agent-run.js",
@@ -17,8 +17,11 @@
     "scripts/install-systemd-jobs.sh",
     "scripts/update-ai-tools.sh",
     "scripts/ensure-agent-brain.sh",
+    "scripts/cleanup-agent-sessions.sh",
     "scripts/brain-pipe-security.ps1",
     "scripts/install-windows-brain.ps1",
+    "scripts/install-windows-cleanup.ps1",
+    "scripts/run-windows-cleanup.ps1",
     "scripts/run-windows-brain.ps1",
     "scripts/run-hidden.vbs",
     "README.md",
@@ -36,7 +39,7 @@
     "cleanbuild": "run-s clean:dist build",
     "prepack": "run-s build",
     "test": "run-s build test:codex-profiles test:integration test:release",
-    "test:codex-profiles": "node --test scripts/test-codex-profiles.cjs",
+    "test:codex-profiles": "node --test scripts/test-codex-profiles.cjs scripts/test-session-cleanup.cjs scripts/test-windows-cleanup.cjs",
     "test:brain": "node --test scripts/test-brain.cjs",
     "test:integration": "bash ./scripts/test.sh",
     "test:release": "bash ./scripts/test-release.sh",

package/scripts/cleanup-agent-sessions.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "$(id -u)" -ne 0 ]; then
+	echo "cleanup-agent-sessions.sh must run as root" >&2
+	exit 1
+fi
+
+# Select accounts explicitly; never scan every home or run native CLIs as root.
+read -r -a accounts <<<"${AI_TOOLS_CLEANUP_USERS-${AI_TOOLS_BRAIN_USERS:-}}"
+status=0
+for account in "${accounts[@]}"; do
+	entry="$(getent passwd "$account")" || { echo "Unknown cleanup account: $account" >&2; status=1; continue; }
+	IFS=: read -r username password uid gid gecos account_home login_shell <<<"$entry"
+	if [ "$uid" -lt 1000 ] || [ "$uid" -eq 65534 ]; then
+		echo "Refusing to clean sessions for system account: $account" >&2
+		status=1
+		continue
+	fi
+	# A clean environment avoids leaking root's home, session IDs or native settings.
+	if ! runuser -u "$username" -- env -i "HOME=$account_home" "USER=$username" "LOGNAME=$username" \
+		PATH=/usr/local/bin:/usr/bin:/bin /bin/sh -c 'cd "$HOME" && exec "$@"' cleanup-agent-sessions /usr/local/bin/agent-run \
+		--configdir "$account_home/.agent-run" --clean-old all; then
+		status=1
+	fi
+done
+exit "$status"

package/scripts/install-systemd-jobs.sh

@@ -29,6 +29,7 @@ SERVICE_FILE="$ROOT/ops/systemd/ai-tools-update.service"
 TIMER_FILE="$ROOT/ops/systemd/ai-tools-update.timer"
 BRAIN_HELPER="$ROOT/scripts/ensure-agent-brain.sh"
 BRAIN_SERVICE="$ROOT/ops/systemd/agent-brain.service"
+CLEANUP_HELPER="$ROOT/scripts/cleanup-agent-sessions.sh"
 
 
 INSTALL_AI_TOOLS=0
@@ -82,6 +83,7 @@ run() {
 run install -d -m 0755 "$INSTALL_LIBEXEC_DIR" "$SYSTEMD_DIR" "$SYSTEMD_USER_DIR"
 run install -m 0755 "$UPDATE_SCRIPT" "$INSTALL_LIBEXEC_DIR/update-ai-tools"
 run install -m 0755 "$BRAIN_HELPER" "$INSTALL_LIBEXEC_DIR/ensure-agent-brain"
+run install -m 0755 "$CLEANUP_HELPER" "$INSTALL_LIBEXEC_DIR/cleanup-agent-sessions"
 run install -m 0644 "$BRAIN_SERVICE" "$SYSTEMD_USER_DIR/agent-brain.service"
 run install -m 0644 "$SERVICE_FILE" "$SYSTEMD_DIR/ai-tools-update.service"
 run install -m 0644 "$TIMER_FILE" "$SYSTEMD_DIR/ai-tools-update.timer"

package/scripts/install-windows-cleanup.ps1

@@ -0,0 +1,14 @@
+param([string]$ConfigRoot = (Join-Path $env:USERPROFILE '.agent-run'))
+$ErrorActionPreference = 'Stop'
+$ConfigRoot = [System.IO.Path]::GetFullPath($ConfigRoot)
+$runner = Join-Path $PSScriptRoot 'run-windows-cleanup.ps1'
+$launcher = Join-Path $PSScriptRoot 'run-hidden.vbs'
+if ($ConfigRoot.Contains('"') -or $runner.Contains('"') -or $launcher.Contains('"')) { throw 'Paths cannot contain quotes.' }
+$wscript = Join-Path $env:SystemRoot 'System32\wscript.exe'
+$account = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
+$action = New-ScheduledTaskAction -Execute $wscript -Argument "//B //NoLogo `"$launcher`" `"$runner`" -ConfigRoot `"$ConfigRoot`"" -WorkingDirectory $env:USERPROFILE
+$principal = New-ScheduledTaskPrincipal -UserId $account -LogonType Interactive -RunLevel Limited
+$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(10) -RepetitionInterval (New-TimeSpan -Hours 1)
+$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -ExecutionTimeLimit (New-TimeSpan -Minutes 30) -MultipleInstances IgnoreNew
+Register-ScheduledTask -TaskName 'Agent Session Cleanup' -Action $action -Principal $principal -Trigger $trigger -Settings $settings -Description 'Hourly agent-run session retention cleanup for the signed-in user.' -Force | Out-Null
+Write-Host "Agent Session Cleanup registered hourly for $account. Retention: $ConfigRoot\cleanup.env (default 7 days). Log: $ConfigRoot\runtime\cleanup.log"

package/scripts/run-windows-cleanup.ps1

@@ -0,0 +1,23 @@
+param([Parameter(Mandatory = $true)][string]$ConfigRoot)
+$ErrorActionPreference = 'Stop'
+$ConfigRoot = [System.IO.Path]::GetFullPath($ConfigRoot)
+$env:Path = [Environment]::GetEnvironmentVariable('Path', 'Machine') + ';' + [Environment]::GetEnvironmentVariable('Path', 'User')
+# Do not inherit a wrapper's guarded PATH or a particular interactive session.
+foreach ($name in @('AGENT_RUN_REAL_PATH', 'CODEX_THREAD_ID', 'CODEX_SESSION_ID', 'CLAUDE_SESSION_ID', 'GROK_SESSION_ID')) {
+    [Environment]::SetEnvironmentVariable($name, $null, 'Process')
+}
+Set-Location $env:USERPROFILE
+$runtime = Join-Path $ConfigRoot 'runtime'
+New-Item -ItemType Directory -Path $runtime -Force | Out-Null
+$log = Join-Path $runtime 'cleanup.log'
+$agentRun = Join-Path $PSScriptRoot '..\dist\agent-run.js'
+try {
+    $node = (Get-Command node.exe -ErrorAction Stop).Source
+    # Native stderr is diagnostic output; the native exit status decides failure.
+    $ErrorActionPreference = 'Continue'
+    & $node $agentRun --configdir $ConfigRoot --clean-old all *> $log
+    exit $LASTEXITCODE
+} catch {
+    $_ | Out-File -FilePath $log
+    exit 1
+}