@technomoron/agent-run 0.99.44 → 0.99.45

package/CHANGES

@@ -1,6 +1,16 @@
 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

package/README.md

@@ -290,10 +290,19 @@ Global flags:
 `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.
+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:
 
@@ -1155,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/cli.js

@@ -12,7 +12,7 @@ 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='))) {
+    if (command === null && options.args[0] && /^(--clean|--clean-old)(=|$)/.test(options.args[0])) {
         return parseCleanCommand(options.args);
     }
     if (command === null) {
@@ -22,15 +22,17 @@ function parseInvocation(invokedTool, argv) {
 }
 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('--clean='.length)] : []),
+        ...(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)('--clean requires all or a list of codex, claude, gemini, grok');
+        (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)] };
+    return { command: 'clean', agents: values[0] === 'all' ? [...types_1.AGENT_IDS] : [...new Set(values)], ...(olderOnly ? { olderOnly: true } : {}) };
 }
 function applyGlobalOptions(options) {
     if (options.verbose) {
@@ -173,8 +175,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 && /^(--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;
@@ -400,6 +402,7 @@ function renderHelp(topic) {
         '  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

@@ -27,9 +27,11 @@ function main(invokedTool, argv) {
 }
 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);
+        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;
@@ -155,7 +157,6 @@ async function runTool(parsed) {
     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/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/clean-sessions.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionRetentionDays = sessionRetentionDays;
 exports.cleanSessions = cleanSessions;
 exports.reportCleanup = reportCleanup;
 const fs = require("node:fs");
@@ -14,6 +15,17 @@ 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) {
@@ -160,9 +172,11 @@ function pruneIndexes(home, agent, ids) {
         }
     }
 }
-function cleanSessions(configRoot, agents = types_1.AGENT_IDS, all = false, now = Date.now()) {
+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);
@@ -177,7 +191,7 @@ function cleanSessions(configRoot, agents = types_1.AGENT_IDS, all = false, now
                     continue;
                 const removed = new Set();
                 for (const session of fileSessions(home, agent)) {
-                    if (!all && session.modified >= now - WEEK)
+                    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)

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.44",
+  "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 scripts/test-session-cleanup.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
+}