@technomoron/agent-run 0.99.42 → 0.99.44

package/CHANGES

@@ -1,6 +1,20 @@
 CHANGES
 =======
 
+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
+  permissions guidance when access is denied.
+
 Version 0.99.42 (2026-09-25)
 ----------------------------
 * Apply repository AI-file checks only to project scopes and actual repositories.

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,26 @@ 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.
 
+Agent launches purge local sessions last modified more than seven days ago for all
+four agents. This covers native user homes and the profiles under the selected
+configuration root. Sessions exactly seven days old are retained. Authentication,
+settings, skills and brain knowledge are preserved.
+
+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 +1087,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.
 

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,26 @@ function parseInvocation(invokedTool, argv) {
     let command = normalizeCommandName(invokedTool);
     const options = extractGlobalOptions(argv);
     applyGlobalOptions(options);
+    if (command === null && (options.args[0] === '--clean' || options.args[0]?.startsWith('--clean='))) {
+        return parseCleanCommand(options.args);
+    }
     if (command === null) {
         command = extractCommand(options.args);
     }
     return parseCommand(command, options.args);
 }
+function parseCleanCommand(args) {
+    const flag = args[0];
+    const values = [
+        ...(flag.includes('=') ? [flag.slice('--clean='.length)] : []),
+        ...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)('--clean requires all or a list of codex, claude, gemini, grok');
+    }
+    return { command: 'clean', agents: values[0] === 'all' ? [...types_1.AGENT_IDS] : [...new Set(values)] };
+}
 function applyGlobalOptions(options) {
     if (options.verbose) {
         process.env[constants_1.VERBOSE_ENV] = '1';
@@ -52,6 +67,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 +173,8 @@ function parseRunCommand(command, inputArgs) {
     const args = [];
     let passthrough = false;
     for (const arg of inputArgs) {
+        if (!passthrough && (arg === '--clean' || arg.startsWith('--clean=')))
+            (0, utils_1.fail)('Use --clean on its own: agent-run --clean all|codex,claude,gemini,grok');
         if (passthrough) {
             args.push(arg);
             continue;
@@ -380,6 +399,7 @@ 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',
         '  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,14 +13,25 @@ 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) {
-    dispatch((0, cli_1.parseInvocation)(invokedTool, argv));
+    try {
+        dispatch((0, cli_1.parseInvocation)(invokedTool, argv));
+    }
+    catch (error) {
+        process.stderr.write(`agent-run: ${(0, utils_1.formatError)(error)}\n`);
+        process.exitCode = 1;
+    }
 }
 function dispatch(command) {
     switch (command.command) {
+        case 'clean':
+            (0, clean_sessions_1.reportCleanup)((0, clean_sessions_1.cleanSessions)((0, project_1.defaultConfigRoot)(process.cwd()), command.agents, true), true);
+            return;
         case 'compress':
-            void runCompress(command).catch((error) => { process.stderr.write(`agent-run: ${error instanceof Error ? error.message : String(error)}\n`); process.exitCode = 1; });
+            void runCompress(command).catch((error) => { process.stderr.write(`agent-run: ${(0, utils_1.formatError)(error)}\n`); process.exitCode = 1; });
             return;
         case 'mcp':
         case 'create':
@@ -51,7 +62,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) {
@@ -90,11 +101,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());
@@ -138,11 +149,13 @@ 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) {
         (0, utils_1.fail)(`no generated ${command} runtime found for profile ${rendered.profile}`);
     }
+    (0, clean_sessions_1.reportCleanup)((0, clean_sessions_1.cleanSessions)(configRoot));
     (0, spawn_agent_1.spawnAgent)(adapter.spawn(runtime, { binary: realBinary, passthroughArgs: args, wrapperArgs }));
 }
 function runStatus() {

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/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,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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 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()) {
+    return agents.map((agent) => {
+        const result = { agent, removed: 0, errors: [] };
+        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 - WEEK)
+                        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/dist/utils.js

@@ -35,6 +35,12 @@ function localDateString() {
     return `${year}-${month}-${day}`;
 }
 function formatError(error) {
+    if (error instanceof Error) {
+        const { code, path: filePath } = error;
+        if (code === 'EACCES' || code === 'EPERM') {
+            return `${error.message}\nCheck file ownership and permissions${filePath ? ` for ${filePath}` : ''} and its parent directories. Run agent-run as your normal user, not with sudo.`;
+        }
+    }
     return error instanceof Error ? error.message : String(error);
 }
 function verbose(message) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@technomoron/agent-run",
-  "version": "0.99.42",
+  "version": "0.99.44",
   "packageManager": "pnpm@10.34.5",
   "bin": {
     "agent-run": "dist/agent-run.js",
@@ -36,7 +36,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",
     "test:brain": "node --test scripts/test-brain.cjs",
     "test:integration": "bash ./scripts/test.sh",
     "test:release": "bash ./scripts/test-release.sh",