appback-remoteagent 0.15.7 → 0.17.0

package/dist/services/agent-memory-service.js

@@ -9,6 +9,7 @@ export class AgentMemoryService {
     artifactsPath;
     secretsPath;
     docsPath;
+    macrosPath;
     telegramUploadsDir;
     constructor(dataDir) {
         this.dataDir = dataDir;
@@ -16,6 +17,7 @@ export class AgentMemoryService {
         this.artifactsPath = path.join(this.rootDir, "artifacts.json");
         this.secretsPath = path.join(this.rootDir, "secrets.json");
         this.docsPath = path.join(this.rootDir, "docs-index.json");
+        this.macrosPath = path.join(this.rootDir, "macros.json");
         this.telegramUploadsDir = path.join(dataDir, "uploads", "telegram");
     }
     async recordInstruction(session, instruction) {
@@ -238,6 +240,57 @@ export class AgentMemoryService {
         await this.writeSecrets(secrets);
         return existed;
     }
+    async setMacro(alias, prompt) {
+        const normalizedAlias = this.normalizeMacroAlias(alias);
+        const normalizedPrompt = prompt.trim();
+        if (!normalizedPrompt) {
+            throw new Error("Macro prompt must not be empty.");
+        }
+        const macros = await this.readMacros();
+        const now = new Date().toISOString();
+        const record = {
+            alias: normalizedAlias,
+            prompt: normalizedPrompt,
+            createdAt: macros[normalizedAlias]?.createdAt ?? now,
+            updatedAt: now,
+        };
+        macros[normalizedAlias] = record;
+        await this.writeJson(this.macrosPath, macros);
+        return record;
+    }
+    async removeMacro(alias) {
+        const normalizedAlias = this.normalizeMacroAlias(alias);
+        const macros = await this.readMacros();
+        const existed = Boolean(macros[normalizedAlias]);
+        delete macros[normalizedAlias];
+        await this.writeJson(this.macrosPath, macros);
+        return existed;
+    }
+    async getMacro(aliasOrIndex) {
+        const macros = Object.values(await this.readMacros())
+            .sort((left, right) => left.alias.localeCompare(right.alias, "ko"));
+        const trimmed = aliasOrIndex.trim();
+        if (/^[0-9]+$/.test(trimmed)) {
+            const index = Number.parseInt(trimmed, 10);
+            return index >= 1 && index <= macros.length ? macros[index - 1] : undefined;
+        }
+        const normalizedAlias = this.normalizeMacroAlias(trimmed);
+        return macros.find((macro) => macro.alias === normalizedAlias);
+    }
+    async listMacros() {
+        const macros = Object.values(await this.readMacros())
+            .sort((left, right) => left.alias.localeCompare(right.alias, "ko"));
+        if (macros.length === 0) {
+            return "No macros are stored.";
+        }
+        return [
+            `Macros (${macros.length})`,
+            ...macros.map((macro, index) => {
+                const preview = macro.prompt.replace(/\s+/g, " ").slice(0, 120);
+                return `${index + 1}. ${macro.alias}\n   ${preview}${macro.prompt.length > preview.length ? "..." : ""}`;
+            }),
+        ].join("\n");
+    }
     async getSecret(key) {
         this.assertSecretKey(key);
         const secrets = await this.readSecrets();
@@ -646,6 +699,19 @@ export class AgentMemoryService {
     async readDocs() {
         return this.readJson(this.docsPath, {});
     }
+    async readMacros() {
+        return this.readJson(this.macrosPath, {});
+    }
+    normalizeMacroAlias(alias) {
+        const normalized = alias.trim();
+        if (/^[0-9]+$/.test(normalized)) {
+            throw new Error("Macro alias cannot be numeric. Numeric values are reserved for list selection.");
+        }
+        if (!/^[a-z0-9가-힣._-]{1,80}$/i.test(normalized)) {
+            throw new Error("Macro alias must be 1-80 chars and may contain letters, numbers, Korean, dot, underscore, or dash.");
+        }
+        return normalized;
+    }
     normalizeKeyword(keyword) {
         const normalized = keyword.trim().toLowerCase();
         if (!/^[a-z0-9가-힣._-]{1,80}$/i.test(normalized)) {

package/dist/services/workspace-cleanup-service.js

@@ -0,0 +1,150 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const PRESERVED_WORKSPACE_TODO_FILES = new Set(["TODO.md", "todo.md", "todo.json"]);
+export class WorkspaceCleanupService {
+    dataDir;
+    workspaceRoot;
+    constructor(dataDir, workspaceRoot) {
+        this.dataDir = dataDir;
+        this.workspaceRoot = workspaceRoot;
+    }
+    async cleanupOrphanWorkspaces() {
+        const referenced = await this.referencedWorkspaceNames();
+        const entries = await fs.readdir(this.workspaceRoot, { withFileTypes: true }).catch(() => []);
+        const result = { removedPaths: 0, removedBytes: 0, skipped: 0, messages: [] };
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            if (referenced.has(entry.name)) {
+                continue;
+            }
+            const target = path.join(this.workspaceRoot, entry.name);
+            const bytes = await this.directorySize(target);
+            await fs.rm(target, { recursive: true, force: true });
+            result.removedPaths += 1;
+            result.removedBytes += bytes;
+            result.messages.push(`${entry.name} (${formatBytes(bytes)})`);
+        }
+        return [
+            "Workspace orphan cleanup finished.",
+            `removed=${result.removedPaths}`,
+            `freed=${formatBytes(result.removedBytes)}`,
+            result.messages.length > 0 ? `items=${result.messages.join(", ")}` : "items=none",
+        ].join(" ");
+    }
+    async cleanupSessionWorkspace(session) {
+        if (!this.isManagedWorkspace(session.workspace)) {
+            return [
+                `Workspace cleanup skipped for ${session.publicId}.`,
+                "The current workspace is not managed by RemoteAgent.",
+                `workspace=${session.workspace}`,
+            ].join("\n");
+        }
+        const result = { removedPaths: 0, removedBytes: 0, skipped: 0, messages: [] };
+        await this.cleanupWorkspaceContents(session.workspace, result);
+        return [
+            `Workspace cleanup finished for ${session.publicId}.`,
+            `workspace=${session.workspace}`,
+            `preservedSessionMemory=${path.join(this.dataDir, "managed", "sessions", session.publicId)}`,
+            `removed=${result.removedPaths}`,
+            `freed=${formatBytes(result.removedBytes)}`,
+            `skipped=${result.skipped}`,
+            result.messages.length > 0
+                ? ["removedItems:", ...result.messages.slice(0, 30).map((item) => `- ${item}`)].join("\n")
+                : "removedItems: none",
+        ].join("\n");
+    }
+    async cleanupWorkspaceContents(root, result) {
+        const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const entryPath = path.join(root, entry.name);
+            if (entry.isFile() && PRESERVED_WORKSPACE_TODO_FILES.has(entry.name)) {
+                result.skipped += 1;
+                continue;
+            }
+            await this.removePath(entryPath, result);
+        }
+    }
+    async removePath(target, result) {
+        const bytes = await this.pathSize(target);
+        await fs.rm(target, { recursive: true, force: true });
+        result.removedPaths += 1;
+        result.removedBytes += bytes;
+        result.messages.push(`${path.relative(this.workspaceRoot, target)} (${formatBytes(bytes)})`);
+    }
+    async referencedWorkspaceNames() {
+        const state = await this.readState();
+        const referenced = new Set();
+        const root = path.resolve(this.workspaceRoot);
+        for (const session of Object.values(state.sessions ?? {})) {
+            const workspace = session.workspace ? path.resolve(session.workspace) : "";
+            if (!workspace || !this.isPathInside(root, workspace)) {
+                continue;
+            }
+            referenced.add(path.basename(workspace));
+        }
+        return referenced;
+    }
+    async readState() {
+        const statePath = path.join(this.dataDir, "state.json");
+        const raw = await fs.readFile(statePath, "utf8").catch((error) => {
+            throw new Error(`state unavailable, refusing workspace cleanup: ${error.message}`);
+        });
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || !parsed.sessions || typeof parsed.sessions !== "object") {
+            throw new Error(`state unavailable, refusing workspace cleanup: invalid state at ${statePath}`);
+        }
+        return parsed;
+    }
+    isManagedWorkspace(workspace) {
+        const root = path.resolve(this.workspaceRoot);
+        const resolved = path.resolve(workspace);
+        return this.isPathInside(root, resolved) && resolved !== root;
+    }
+    isPathInside(parent, child) {
+        const relative = path.relative(parent, child);
+        return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+    }
+    async pathSize(target) {
+        const stat = await fs.stat(target).catch(() => undefined);
+        if (!stat) {
+            return 0;
+        }
+        if (stat.isFile()) {
+            return stat.size;
+        }
+        if (stat.isDirectory()) {
+            return this.directorySize(target);
+        }
+        return 0;
+    }
+    async directorySize(directory) {
+        const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+        let total = 0;
+        for (const entry of entries) {
+            const entryPath = path.join(directory, entry.name);
+            const stat = await fs.stat(entryPath).catch(() => undefined);
+            if (!stat) {
+                continue;
+            }
+            if (stat.isFile()) {
+                total += stat.size;
+            }
+            else if (stat.isDirectory()) {
+                total += await this.directorySize(entryPath);
+            }
+        }
+        return total;
+    }
+}
+function formatBytes(bytes) {
+    const units = ["B", "KB", "MB", "GB"];
+    let value = bytes;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex += 1;
+    }
+    return `${unitIndex === 0 ? value.toFixed(0) : value.toFixed(1)}${units[unitIndex]}`;
+}

package/dist/telegram-bot-identity.js

@@ -0,0 +1,36 @@
+export function buildBotInfoFromIdentity(id, username, firstName) {
+    return {
+        id,
+        is_bot: true,
+        first_name: firstName || username,
+        username,
+        can_join_groups: false,
+        can_read_all_group_messages: false,
+        supports_inline_queries: false,
+    };
+}
+export function buildFallbackBotInfo(token, index, configuredUsername) {
+    const id = Number.parseInt(token.split(":", 1)[0] ?? "", 10);
+    const persistedUsername = configuredUsername?.trim().replace(/^@/, "");
+    const username = persistedUsername
+        || knownBotUsername(id)
+        || `bot_${Number.isFinite(id) ? id : index + 1}`;
+    return {
+        id: Number.isFinite(id) ? id : index + 1,
+        is_bot: true,
+        first_name: username,
+        username,
+        can_join_groups: false,
+        can_read_all_group_messages: false,
+        supports_inline_queries: false,
+    };
+}
+function knownBotUsername(id) {
+    if (id === 8369496408) {
+        return "codex_remoteagent_bot";
+    }
+    if (id === 8429712341) {
+        return "sqream_bot";
+    }
+    return undefined;
+}

package/dist/telegram-command-menu.js

@@ -13,11 +13,14 @@ export const TELEGRAM_COMMAND_MENU = [
     { command: "option", description: "Show or change runtime options" },
     { command: "secret", description: "Store or manage hidden secret values" },
     { command: "docs", description: "Pin or find session documents" },
+    { command: "macro", description: "Save or run reusable instructions" },
     { command: "model", description: "Show or change provider model" },
+    { command: "queue", description: "List or remove queued instructions" },
     { command: "stop", description: "Stop active work and clear queued messages" },
     { command: "sandbox", description: "Set Codex sandbox mode" },
     { command: "batch", description: "Collect and send a multi-message batch" },
     { command: "artifacts", description: "List or clean uploaded artifacts" },
+    { command: "cleanup", description: "Clean current session workspace" },
     { command: "bots", description: "List configured Telegram bots" },
     { command: "bot", description: "Manage Telegram bots" },
     { command: "install", description: "Install or update Codex or Claude" },

package/docs/OPERATIONS.md

@@ -44,6 +44,10 @@ Current production bot ownership is intentionally split:
 Assign each Telegram bot token to one runtime at a time.
 Bot polling conflicts are treated as incidents, not harmless warnings.
 
+`TELEGRAM_BOT_TOKENS` and `TELEGRAM_BOT_USERNAMES` are parallel persisted lists.
+At startup, Telegram `getMe` is the preferred identity source, but a temporary DNS or Telegram failure must fall back to the persisted username at the same list position.
+Using a generated `bot_<numeric-id>` identity when a persisted username exists breaks the existing `<username>:<chat-id>` session binding.
+
 When a runtime has several configured Telegram bots, polling pressure can become operationally visible.
 RemoteAgent reduces that pressure with rank-based polling intervals instead of deep sleep or a special main bot.
 See [BOT_POLLING_POLICY.md](./BOT_POLLING_POLICY.md).
@@ -122,6 +126,75 @@ Check the lock owner:
 cat /home/au2223/.remoteagent/remoteagent.lock
 ```
 
+## Disk maintenance
+
+RemoteAgent disk growth usually comes from Docker build cache, Docker volumes, Codex session logs, managed workspaces, Telegram uploads, and temporary build artifacts.
+
+Use one script for repeatable checks and conservative cleanup:
+
+```bash
+npm run maintenance:disk -- report
+```
+
+Run the safe cleanup path:
+
+```bash
+npm run maintenance:disk -- prune-safe
+```
+
+`prune-safe` performs only these actions:
+
+- `docker builder prune -f`
+- remove old `/tmp/remoteagent-codex-*`, `/tmp/remoteagent-claude-*`, and `/tmp/appback-*` directories older than 2 days
+- remove managed workspace directories under `WORKSPACE_ROOT` only when they are not referenced by RemoteAgent `state.json`
+
+Clean only orphan managed workspaces:
+
+```bash
+npm run maintenance:disk -- prune-workspaces
+```
+
+RemoteAgent also runs conservative workspace cleanup on a schedule when enabled:
+
+```bash
+WORKSPACE_CLEANUP_ENABLED=true
+WORKSPACE_CLEANUP_INTERVAL_MS=86400000
+```
+
+Scheduled workspace cleanup only removes managed workspace directories under `WORKSPACE_ROOT` when they are not referenced by RemoteAgent `state.json`.
+If `state.json` is missing or invalid, workspace cleanup refuses to run.
+
+Clean the current chat session workspace manually from Telegram:
+
+```text
+/cleanup
+```
+
+`/cleanup` does not delete the session workspace directory itself. It removes the contents of the current managed workspace while preserving RemoteAgent's session todo/state/history under `~/.remoteagent/managed/sessions/<session>`. If a top-level `TODO.md`, `todo.md`, or `todo.json` exists inside the workspace, it is also preserved. The command refuses non-RemoteAgent-managed workspaces.
+
+Archive old Codex session logs explicitly:
+
+```bash
+npm run maintenance:disk -- prune-codex-sessions 45
+```
+
+This creates an archive under `~/.codex/session-archive/` and removes the archived jsonl files from `~/.codex/sessions`.
+Use this only when old Codex resume history is no longer needed.
+
+For server 30, run the installed package script through npm:
+
+```bash
+ssh au2223@192.168.0.30 'export PATH="/home/au2223/.local/bin:/home/au2223/.nvm/versions/node/v22.22.0/bin:$PATH"; npm explore -g appback-remoteagent -- npm run maintenance:disk -- report'
+ssh au2223@192.168.0.30 'export PATH="/home/au2223/.local/bin:/home/au2223/.nvm/versions/node/v22.22.0/bin:$PATH"; npm explore -g appback-remoteagent -- npm run maintenance:disk -- prune-safe'
+```
+
+For server 26:
+
+```bash
+ssh ospadmin@192.168.0.26 'export PATH="$HOME/.local/bin:$PATH"; npm explore -g appback-remoteagent -- npm run maintenance:disk -- report'
+ssh ospadmin@192.168.0.26 'export PATH="$HOME/.local/bin:$PATH"; npm explore -g appback-remoteagent -- npm run maintenance:disk -- prune-safe'
+```
+
 ## Git workflow
 
 The intended workflow is:

package/docs/RELEASING.md

@@ -174,3 +174,26 @@ Runtime targets:
 server 30: 0.15.5 active
 server 26: 0.15.5 running
 ```
+
+## Release 0.17.0
+
+Date: 2026-07-29
+
+Changes:
+
+- Queued instructions receive runtime-unique `Q001`-style ids.
+- `/queue` lists instructions waiting behind the current session work.
+- `/queue remove <id>` removes one selected waiting instruction.
+- `/queue del` removes the most recently queued instruction.
+- `/stop` reports and clears queued work-loop instructions as well as pending message batches.
+- Telegram startup preserves the configured bot username when `getMe` temporarily fails, preventing existing chat/session bindings from being bypassed by a generated numeric bot identity.
+
+Validated:
+
+```bash
+npm run check
+npm run build
+npm run selftest:telegram
+npm run release:publish
+npm run release:deploy -- 0.17.0 all
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appback-remoteagent",
-  "version": "0.15.7",
+  "version": "0.17.0",
   "description": "Personal installable session server for continuing local AI work across PC and Telegram",
   "license": "MIT",
   "type": "module",
@@ -23,7 +23,8 @@
     "prepublishOnly": "node scripts/prepublish-guard.mjs",
     "release:version": "bash scripts/release-version.sh",
     "release:publish": "bash scripts/release-publish.sh",
-    "release:deploy": "bash scripts/release-deploy.sh"
+    "release:deploy": "bash scripts/release-deploy.sh",
+    "maintenance:disk": "bash scripts/disk-maintenance.sh"
   },
   "dependencies": {
     "dotenv": "^16.6.1",

package/scripts/disk-maintenance.sh

@@ -0,0 +1,216 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'USAGE'
+Usage: scripts/disk-maintenance.sh <report|prune-safe|prune-workspaces|prune-codex-sessions> [days]
+
+Examples:
+  scripts/disk-maintenance.sh report
+  scripts/disk-maintenance.sh prune-safe
+  scripts/disk-maintenance.sh prune-workspaces
+  scripts/disk-maintenance.sh prune-codex-sessions 45
+
+Notes:
+  report              Prints disk, Docker, workspace, cache, and large-file usage.
+  prune-safe          Removes Docker build cache, old RemoteAgent temp dirs, and orphan managed workspaces only.
+  prune-workspaces    Removes only managed workspace directories not referenced by RemoteAgent state.
+  prune-codex-sessions <days>
+                      Archives Codex session jsonl files older than <days> into ~/.codex/session-archive.
+                      This can break resume for archived old sessions, so it must be explicit.
+USAGE
+}
+
+ACTION="${1:-}"
+RETENTION_DAYS="${2:-}"
+DATA_DIR="${DATA_DIR:-$HOME/.remoteagent}"
+WORKSPACE_ROOT="${WORKSPACE_ROOT:-$HOME/workspaces/remoteagent}"
+CODEX_SESSIONS_DIR="${CODEX_SESSIONS_DIR:-$HOME/.codex/sessions}"
+CODEX_ARCHIVE_DIR="${CODEX_ARCHIVE_DIR:-$HOME/.codex/session-archive}"
+
+if [[ -z "$ACTION" ]]; then
+  usage
+  exit 1
+fi
+
+require_integer_days() {
+  local value="$1"
+  if [[ ! "$value" =~ ^[0-9]+$ ]] || [[ "$value" -lt 1 ]]; then
+    echo "Retention days must be a positive integer." >&2
+    exit 1
+  fi
+}
+
+print_section() {
+  printf '\n== %s ==\n' "$1"
+}
+
+docker_available() {
+  command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1
+}
+
+report() {
+  print_section "filesystem"
+  df -hT /
+
+  print_section "top level"
+  sudo -n du -xhd1 / 2>/dev/null | sort -h | tail -30 || du -xhd1 "$HOME" 2>/dev/null | sort -h | tail -30 || true
+
+  print_section "home"
+  du -xhd1 "$HOME" 2>/dev/null | sort -h | tail -50 || true
+
+  if [[ -d "$WORKSPACE_ROOT" ]]; then
+    print_section "remoteagent workspaces"
+    du -xhd1 "$WORKSPACE_ROOT" 2>/dev/null | sort -h | tail -80 || true
+    print_section "orphan managed workspaces"
+    orphan_workspaces dry-run
+  fi
+
+  if [[ -d "$CODEX_SESSIONS_DIR" ]]; then
+    print_section "codex sessions"
+    du -xhd1 "$HOME/.codex" "$CODEX_SESSIONS_DIR" 2>/dev/null | sort -h | tail -40 || true
+  fi
+
+  print_section "tmp"
+  du -xhd1 /tmp 2>/dev/null | sort -h | tail -50 || true
+
+  if docker_available; then
+    print_section "docker system df"
+    docker system df || true
+  fi
+
+  print_section "largest files over 200M"
+  sudo -n find "$HOME" /var /tmp -xdev -type f -size +200M -printf '%s\t%p\n' 2>/dev/null \
+    | sort -n \
+    | tail -80 \
+    | awk '{size=$1/1024/1024/1024; $1=""; sub(/^\t/, ""); printf "%.2fG\t%s\n", size, $0}' || true
+}
+
+orphan_workspaces() {
+  local mode="${1:-dry-run}"
+  python3 - "$DATA_DIR" "$WORKSPACE_ROOT" "$mode" <<'PY'
+import json
+import os
+import shutil
+import subprocess
+import sys
+
+data_dir, workspace_root, mode = sys.argv[1:4]
+state_path = os.path.join(data_dir, "state.json")
+
+def size_label(path):
+    try:
+        return subprocess.check_output(["du", "-sh", path], text=True).split()[0]
+    except Exception:
+        return "?"
+
+if not os.path.isdir(workspace_root):
+    print(f"workspace root not found: {workspace_root}")
+    sys.exit(0)
+
+try:
+    with open(state_path, "r", encoding="utf-8") as handle:
+        state = json.load(handle)
+except Exception as exc:
+    print(f"state unavailable, refusing workspace cleanup: {exc}")
+    sys.exit(0 if mode == "dry-run" else 1)
+
+referenced = set()
+for session in (state.get("sessions") or {}).values():
+    workspace = session.get("workspace") or session.get("workspacePath")
+    if isinstance(workspace, str):
+        normalized = os.path.abspath(workspace)
+        root = os.path.abspath(workspace_root)
+        if normalized == root or normalized.startswith(root + os.sep):
+            referenced.add(os.path.basename(normalized.rstrip(os.sep)))
+
+all_dirs = {
+    name for name in os.listdir(workspace_root)
+    if os.path.isdir(os.path.join(workspace_root, name))
+}
+orphans = sorted(all_dirs - referenced)
+
+print(f"referenced={len(referenced)} all={len(all_dirs)} orphan={len(orphans)}")
+for name in orphans:
+    path = os.path.join(workspace_root, name)
+    print(f"{size_label(path)}\t{name}")
+    if mode == "delete":
+        shutil.rmtree(path, ignore_errors=True)
+PY
+}
+
+prune_safe() {
+  print_section "before"
+  df -hT /
+
+  if docker_available; then
+    print_section "docker builder prune"
+    docker builder prune -f
+  else
+    print_section "docker builder prune skipped"
+    echo "docker is unavailable or current user cannot access it"
+  fi
+
+  print_section "old temp directories"
+  find /tmp -maxdepth 1 -mindepth 1 -type d \
+    \( -name 'remoteagent-codex-*' -o -name 'remoteagent-claude-*' -o -name 'appback-*' \) \
+    -mtime +2 -print -exec rm -rf {} +
+
+  print_section "orphan managed workspaces"
+  orphan_workspaces delete
+
+  print_section "after"
+  df -hT /
+}
+
+prune_codex_sessions() {
+  local days="$1"
+  require_integer_days "$days"
+
+  if [[ ! -d "$CODEX_SESSIONS_DIR" ]]; then
+    echo "Codex sessions dir not found: $CODEX_SESSIONS_DIR"
+    exit 0
+  fi
+
+  mkdir -p "$CODEX_ARCHIVE_DIR"
+  local stamp
+  stamp="$(date +%Y%m%d-%H%M%S)"
+  local list_file archive_file
+  list_file="$(mktemp)"
+  archive_file="$CODEX_ARCHIVE_DIR/codex-sessions-older-than-${days}d-$stamp.tar.gz"
+  find "$CODEX_SESSIONS_DIR" -type f -name '*.jsonl' -mtime +"$days" -print > "$list_file"
+
+  if [[ ! -s "$list_file" ]]; then
+    rm -f "$list_file"
+    echo "No Codex session files older than ${days}d."
+    exit 0
+  fi
+
+  tar -czf "$archive_file" --files-from "$list_file"
+  while IFS= read -r file; do
+    rm -f "$file"
+  done < "$list_file"
+  rm -f "$list_file"
+
+  find "$CODEX_SESSIONS_DIR" -type d -empty -delete
+  echo "Archived old Codex session files to $archive_file"
+}
+
+case "$ACTION" in
+  report)
+    report
+    ;;
+  prune-safe)
+    prune_safe
+    ;;
+  prune-workspaces)
+    orphan_workspaces delete
+    ;;
+  prune-codex-sessions)
+    prune_codex_sessions "${RETENTION_DAYS:-}"
+    ;;
+  *)
+    usage
+    exit 1
+    ;;
+esac