@aragon-agent/cli 0.6.2 → 0.6.3

package/dist/commands/builtins.js

@@ -3,10 +3,8 @@
  * /help /model /settings /thinking /max-tokens /tools /clear /reset /cwd /save
  * /resume /copy /exit (/quit), plus the /team, /fast and /todo subsystems.
  */
-import { spawn } from 'node:child_process';
 import { existsSync, statSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
-import process from 'node:process';
 import { resolveOutputTokens } from '@aragon-agent/core';
 import { clampThinkingLevel, clampTheme, isAdapterProvider, isThemeName, parseMaxTokensInput, ADAPTER_PROVIDERS, DEFAULT_MAX_TOKENS, HARD_MAX_RETRIES, LEGACY_DARK_THEME, THEME_NAMES, THINKING_LEVELS, } from '../config/schema.js';
 import { computeCost, formatCost, formatTokens } from '../agent/usage.js';
@@ -16,7 +14,9 @@ import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
 import { loadConfig } from '../config/load.js';
 import { loadSession, resolveSessionPath, saveSession } from '../session/persist.js';
 import { getLogger } from '../logging/logger.js';
+import { copyText } from '../ui/clipboard.js';
 import { perfCommand } from './perf.js';
+import { runCompactCommand } from '../compaction/command.js';
 /**
  * `/fast status` — THE GUARANTEED REPORTING SURFACE for the tier (§4.4 / R-8).
  *
@@ -801,8 +801,21 @@ const COMMANDS = [
             ctx.notify('warn', `Unknown argument "${verb}" - use /retry [show|on|off|max <n>].`);
         },
     },
+    {
+        // REGISTRATION ONLY. The body lives in `compaction/command.ts` because this
+        // file is already past the 1000-line guideline and `/compact` has six forms
+        // plus the longest status report in the package (C-16 / P1-12).
+        name: 'compact',
+        description: 'Context compaction: status | on | off | threshold <n> | keep <n> | <instructions>',
+        run: (ctx) => runCompactCommand(ctx),
+    },
     {
         name: 'expand',
+        // DELIBERATELY LEFT TOOL-ONLY, and the asymmetry with Ctrl+O is a decision
+        // rather than an oversight (§6.3). Its description says "a recent tool card",
+        // it takes an N-from-last index over tool cards specifically, and widening it
+        // would change what `/expand 3` means for every existing user. Ctrl+O is the
+        // general expansion surface — that is where `'compaction'` was added.
         description: 'Expand / collapse a recent tool card (default: last)',
         run: (ctx) => {
             const toolEntries = ctx.state.entries.filter((e) => e.kind === 'tool');
@@ -942,8 +955,60 @@ const COMMANDS = [
                 ctx.notify('warn', 'No assistant message to copy.');
                 return;
             }
-            const ok = copyToClipboard(last.text);
-            ctx.toast(ok ? 'success' : 'warn', ok ? 'Copied to clipboard.' : 'Clipboard not available.');
+            // ROUTED THROUGH `ui/clipboard.ts` (§4.4.5). The duplicate spawn helper this
+            // command used to own is gone, and the command gained SSH support on the
+            // way: OSC 52 reaches the clipboard of the machine the USER is sitting at,
+            // which the local `pbcopy` never could.
+            //
+            // `ctx.writeForeign` and not `stdout.write` — see the field's comment.
+            const via = copyText(last.text, ctx.writeForeign);
+            if (via === 'none') {
+                ctx.toast('warn', 'Clipboard not available.');
+                return;
+            }
+            // NAMES THE MECHANISM RATHER THAN CLAIMING SUCCESS: neither path is
+            // detectable, and tmux without `set -g set-clipboard on` swallows OSC 52
+            // silently (R-7).
+            ctx.toast('success', via === 'osc52' ? 'Sent to the terminal clipboard.' : 'Sent to the system clipboard.');
+        },
+    },
+    {
+        name: 'mouse',
+        description: 'Release the mouse to the terminal, or take it back',
+        run: (ctx) => {
+            const port = ctx.mouse;
+            if (!port) {
+                // Inline mode, `--no-mouse`, a non-TTY, or a console that cannot deliver
+                // reports. Saying so beats pretending to toggle something that is not on.
+                ctx.notify('info', 'The mouse is not captured in this session, so there is nothing to release.');
+                return;
+            }
+            const arg = ctx.args.trim().toLowerCase();
+            if (arg === 'off') {
+                port.setCapture(false);
+                // NAMING THE COST IS THE HONEST THING TO DO, and it is one clause. The
+                // wheel goes INERT rather than back to scrolling: alternate scroll is
+                // saved and disabled alongside the capture, because otherwise every notch
+                // becomes a burst of arrow keys that `PromptInput` reads as prompt-history
+                // recall (I-10 / P1-1).
+                ctx.toast('info', 'Mouse released to the terminal - the wheel will not scroll. /mouse on gives it back.');
+                return;
+            }
+            if (arg === 'on') {
+                port.setCapture(true);
+                ctx.toast('info', 'Mouse captured - the wheel scrolls the transcript again.');
+                return;
+            }
+            const captured = port.captured();
+            const lines = [
+                `Mouse capture: ${captured ? 'on' : 'off'}`,
+                `  drag-select  ${port.selectEnabled() ? 'on' : 'off (mouseSelect is false)'}`,
+                '  /mouse off   hand the mouse to your terminal for this session',
+                '  /mouse on    take it back',
+                '  --no-mouse   never capture it (also ARAGON_MOUSE=0)',
+                '  aragon config set mouseSelect false   keep the wheel, drop drag-select',
+            ];
+            ctx.notify('info', lines.join('\n'));
         },
     },
     {
@@ -1006,22 +1071,7 @@ export const BUILTIN_COMMAND_NAMES = COMMANDS.flatMap((c) => [
     c.name,
     ...(c.aliases ?? []),
 ]).sort();
-/** Best-effort clipboard copy via the platform's clipboard CLI. */
-function copyToClipboard(text) {
-    const cmd = process.platform === 'win32'
-        ? { file: 'clip', args: [] }
-        : process.platform === 'darwin'
-            ? { file: 'pbcopy', args: [] }
-            : { file: 'xclip', args: ['-selection', 'clipboard'] };
-    try {
-        const child = spawn(cmd.file, cmd.args, { stdio: ['pipe', 'ignore', 'ignore'] });
-        child.on('error', () => {
-            /* swallow — clipboard is best-effort */
-        });
-        child.stdin?.end(text);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+// The `copyToClipboard` helper that used to live here moved into
+// `ui/clipboard.ts` (tui-selection-and-scroll-follow §4.4.5), unchanged, so that
+// `/copy` and the drag-select release share ONE clipboard path instead of two
+// that can drift.

package/dist/commands/registry.d.ts

@@ -87,6 +87,33 @@ export interface CommandContext {
         effective: AgentMode;
         pending: AgentMode | null;
     };
+    /**
+     * Mouse capture, for `/mouse` (tui-selection-and-scroll-follow §6.2 / G3).
+     *
+     * OPTIONAL, and legitimately absent: inline mode, `--no-mouse`, a non-TTY, a
+     * Windows console that cannot deliver reports, and every test that builds this
+     * context by literal. `/mouse` has to have something honest to say when it is
+     * missing, which is the same reason `update` above it is optional.
+     */
+    mouse?: MouseCommandPort;
+    /**
+     * The foreign-write door, for `/copy`'s OSC 52 half (§4.4.5).
+     *
+     * NOT `process.stdout.write`. In full-screen mode stdout is a `Proxy` in front
+     * of the frame differ, and an unrecognised chunk there is counted as a foreign
+     * write and prints a diagnostic at the user the first time they copy anything
+     * (P1-6). Absent in inline mode and with `--no-diff-render`, where the real
+     * stream is handed over directly.
+     */
+    writeForeign?: (text: string) => void;
+}
+/** What `/mouse` can see and do. Read at command time, never captured. */
+export interface MouseCommandPort {
+    /** Whether the CLI is holding the mouse right now. */
+    captured(): boolean;
+    /** Whether drag-select is on for this session (`mouseSelect`). */
+    selectEnabled(): boolean;
+    setCapture(on: boolean): void;
 }
 export interface SlashCommand {
     name: string;

package/dist/compaction/archive.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The compaction archive - a compaction stops being irreversible
+ * (context-auto-compaction-hardening §3.5 / W4).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`), and that INCLUDES the field names below and every
+ * string `/compact history` and `/compact show` print.
+ *
+ * WHAT THIS IS FOR. Round 1's non-goal was stated plainly: "the dropped messages
+ * are gone". Combined with R-1 - "the summary is wrong or lossy, and the agent
+ * proceeds confidently on a false record... this is the feature's defining risk
+ * and it cannot be eliminated" - the product was asking the user to accept an
+ * unverifiable, unrecoverable transformation of their session. That is the wrong
+ * default for a tool that runs unattended. This does not add undo (§12: restoring
+ * an over-full history re-creates the condition that triggered compaction). It
+ * adds FIDELITY ON DISK, so R-1 becomes something a human can check.
+ *
+ * NO IMPORTS FROM `ui/`. This module writes files and formats two report blocks;
+ * it has no terminal, no theme and no glyphs.
+ */
+import type { Message } from '@aragon-agent/core';
+import type { CompactionMode, CompactionUiTrigger } from './types.js';
+/** Bumped only when the SHAPE changes; the reader rejects anything else. */
+export declare const ARCHIVE_FORMAT_VERSION = 1;
+export interface CompactionArchive {
+    version: number;
+    /** `COMPACTION_BLOCK_VERSION` at write time, so a bad summary ties to a revision. */
+    blockVersion: string;
+    createdAt: number;
+    /**
+     * Which process wrote this.
+     *
+     * STORED INSIDE THE DOCUMENT as well as in the name, so a file renamed or
+     * copied by hand is still self-describing and the reader never has to parse a
+     * filename for meaning it cannot verify.
+     */
+    runId: string;
+    /** 1-based within this run. */
+    index: number;
+    trigger: CompactionUiTrigger;
+    mode: CompactionMode;
+    model: string;
+    generation: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    messagesBefore: number;
+    messagesAfter: number;
+    /**
+     * THE NUMBER. Deliberately not called `droppedMessages`: that name already
+     * means a COUNT in three typed places (`CompactionPlan`, `finish`'s `applied`
+     * argument, and `AgentEvent.compaction_end`), and this is the document someone
+     * reads while diagnosing a bad summary (RV-3).
+     */
+    droppedCount: number;
+    summary?: string;
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    /** True when `dropped` was shortened to fit `archiveMaxBytes`. */
+    clipped: boolean;
+    /** THE ARRAY. Verbatim, oldest first. */
+    dropped: Message[];
+}
+/** One row of `/compact history`, already resolved from disk. */
+export interface ArchiveListing {
+    entries: ArchiveEntry[];
+    /** Archives in the directory belonging to OTHER runs. Counted, never listed. */
+    otherRuns: number;
+    dir: string;
+}
+export interface ArchiveEntry {
+    path: string;
+    fileName: string;
+    index: number;
+    createdAt: number;
+    trigger: CompactionUiTrigger;
+    mode: CompactionMode;
+    model: string;
+    tokensBefore: number;
+    tokensAfter: number;
+    droppedCount: number;
+    summary?: string;
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    clipped: boolean;
+}
+export interface ArchiveWriteInput {
+    runId: string;
+    index: number;
+    trigger: CompactionUiTrigger;
+    mode: CompactionMode;
+    model: string;
+    generation: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    messagesBefore: number;
+    messagesAfter: number;
+    summary?: string;
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    dropped: Message[];
+    /** Injected by the tests; production passes nothing. */
+    dir?: string;
+    now?: number;
+}
+/**
+ * `compaction-<YYYY-MM-DD>-<hhmmss>-<runId>-<index>.json`.
+ *
+ * THE RUN ID IS IN THE NAME BECAUSE THE DIRECTORY IS SHARED (RV-6).
+ * `file-sink.ts` makes log retention best-effort precisely because "on Windows
+ * another `aragon` process may hold a handle on a file we would like to remove",
+ * so concurrent CLI processes are an acknowledged in-tree condition rather than
+ * an edge case. Without this segment `/compact history` presents another
+ * session's compactions as this one's and `/compact show 2` is ambiguous the
+ * moment two runs both reach their second compaction.
+ */
+export declare function archiveFileName(runId: string, index: number, at: Date): string;
+/**
+ * Mint this process's archive key.
+ *
+ * NOT `SessionMeta.id`: that exists only once a session has been SAVED, and the
+ * unattended long run this feature serves is exactly the one nobody saved. Short,
+ * filename-safe, and only ever compared for equality - a grouping key, not an
+ * identity.
+ */
+export declare function mintRunId(pid?: number, now?: number): string;
+/**
+ * Serialize, clipping the dropped bodies from the OLDEST end if the document
+ * exceeds `archiveMaxBytes`.
+ *
+ * THE METADATA AND THE SUMMARY ARE NEVER CLIPPED. A truncated archive that still
+ * says what happened, when, and with which model beats no archive at all - and
+ * the oldest dropped messages are the least likely to be the ones a human came
+ * looking for.
+ */
+export declare function serializeArchive(doc: CompactionArchive, maxBytes: number): string;
+/**
+ * Write one archive, then prune. Returns the path written, or `null`.
+ *
+ * NEVER THROWS. The caller runs inside an event handler on the compaction path;
+ * a filesystem is not allowed to affect whether a session survives its context
+ * window. Every failure is a `warn` with the path and nothing else - a toast for
+ * a best-effort audit file trains users to ignore toasts.
+ */
+export declare function writeArchive(input: ArchiveWriteInput): string | null;
+/**
+ * Two-tier retention, and the ORDER MATTERS (§3.5.2 / RV-6).
+ *
+ *  1. WITHIN THIS RUN: keep the newest `archiveMaxFiles` files carrying THIS
+ *     `runId`. This is the bound that protects the user from their own long
+ *     session, and it can never touch another run.
+ *  2. ACROSS RUNS: delete files older than `archiveMaxAgeMs`, regardless of
+ *     `runId`, so an abandoned run's archives do not accumulate forever. AGE, not
+ *     count - a count-based global prune is exactly the rule that deletes a live
+ *     session's work while it is still running.
+ *
+ * Best-effort throughout, in the `enforceRetention` shape: every `rmSync` in its
+ * own `try`, a locked file skipped rather than fatal.
+ */
+export declare function pruneArchives(runId: string, dir: string, now: number): void;
+/**
+ * This run's archives, newest first, plus a COUNT of everyone else's.
+ *
+ * THE COUNT IS REPORTED RATHER THAN THE FILES, because the alternative is a user
+ * concluding their own compactions went missing when the directory holds a
+ * neighbour's.
+ */
+export declare function listArchives(runId: string, dirOverride?: string): ArchiveListing;
+/** One archive by its `#n`, or `null`. `n` is the index within THIS run. */
+export declare function findArchive(runId: string, index: number, dirOverride?: string): ArchiveEntry | null;

package/dist/compaction/archive.js

@@ -0,0 +1,267 @@
+/**
+ * The compaction archive - a compaction stops being irreversible
+ * (context-auto-compaction-hardening §3.5 / W4).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`), and that INCLUDES the field names below and every
+ * string `/compact history` and `/compact show` print.
+ *
+ * WHAT THIS IS FOR. Round 1's non-goal was stated plainly: "the dropped messages
+ * are gone". Combined with R-1 - "the summary is wrong or lossy, and the agent
+ * proceeds confidently on a false record... this is the feature's defining risk
+ * and it cannot be eliminated" - the product was asking the user to accept an
+ * unverifiable, unrecoverable transformation of their session. That is the wrong
+ * default for a tool that runs unattended. This does not add undo (§12: restoring
+ * an over-full history re-creates the condition that triggered compaction). It
+ * adds FIDELITY ON DISK, so R-1 becomes something a human can check.
+ *
+ * NO IMPORTS FROM `ui/`. This module writes files and formats two report blocks;
+ * it has no terminal, no theme and no glyphs.
+ */
+import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getCompactionArchiveDir } from '../config/app-paths.js';
+import { getLogger } from '../logging/logger.js';
+import { COMPACTION_BLOCK_VERSION, COMPACTION_LIMITS } from './limits.js';
+const FILE_PREFIX = 'compaction-';
+const FILE_SUFFIX = '.json';
+/** Bumped only when the SHAPE changes; the reader rejects anything else. */
+export const ARCHIVE_FORMAT_VERSION = 1;
+/**
+ * `compaction-<YYYY-MM-DD>-<hhmmss>-<runId>-<index>.json`.
+ *
+ * THE RUN ID IS IN THE NAME BECAUSE THE DIRECTORY IS SHARED (RV-6).
+ * `file-sink.ts` makes log retention best-effort precisely because "on Windows
+ * another `aragon` process may hold a handle on a file we would like to remove",
+ * so concurrent CLI processes are an acknowledged in-tree condition rather than
+ * an edge case. Without this segment `/compact history` presents another
+ * session's compactions as this one's and `/compact show 2` is ambiguous the
+ * moment two runs both reach their second compaction.
+ */
+export function archiveFileName(runId, index, at) {
+    const pad = (n) => String(n).padStart(2, '0');
+    const date = `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())}`;
+    const time = `${pad(at.getHours())}${pad(at.getMinutes())}${pad(at.getSeconds())}`;
+    return `${FILE_PREFIX}${date}-${time}-${runId}-${index}${FILE_SUFFIX}`;
+}
+/**
+ * The inverse of `archiveFileName`, or `null` when the name is not one of ours.
+ *
+ * AN EXACT PARSE RATHER THAN `name.includes('-' + runId + '-')`, because that
+ * substring test is not the question either caller is asking. A run id is a pid
+ * in base 36 followed by four base-36 characters of the clock, so a six-character
+ * all-digit one matches the `hhmmss` segment of EVERY other run's file written at
+ * that second - and the two places this attribution is used are precisely the two
+ * RV-6 exists to protect: retention deleting a neighbour's archive, and
+ * `/compact history` presenting one as this run's.
+ *
+ * KEEP IT IN STEP WITH `archiveFileName` ABOVE. The two are one format, written
+ * adjacently so a change to either is visible against the other.
+ */
+function parseArchiveName(name) {
+    const match = /^compaction-\d{4}-\d{2}-\d{2}-\d{6}-(.+)-(\d+)\.json$/.exec(name);
+    if (!match)
+        return null;
+    return { runId: match[1], index: Number(match[2]) };
+}
+/**
+ * Mint this process's archive key.
+ *
+ * NOT `SessionMeta.id`: that exists only once a session has been SAVED, and the
+ * unattended long run this feature serves is exactly the one nobody saved. Short,
+ * filename-safe, and only ever compared for equality - a grouping key, not an
+ * identity.
+ */
+export function mintRunId(pid = process.pid, now = Date.now()) {
+    return `${pid.toString(36)}${now.toString(36).slice(-4)}`;
+}
+/**
+ * Serialize, clipping the dropped bodies from the OLDEST end if the document
+ * exceeds `archiveMaxBytes`.
+ *
+ * THE METADATA AND THE SUMMARY ARE NEVER CLIPPED. A truncated archive that still
+ * says what happened, when, and with which model beats no archive at all - and
+ * the oldest dropped messages are the least likely to be the ones a human came
+ * looking for.
+ */
+export function serializeArchive(doc, maxBytes) {
+    let dropped = doc.dropped;
+    let clipped = doc.clipped;
+    let text = JSON.stringify({ ...doc, dropped, clipped }, null, 2);
+    while (Buffer.byteLength(text, 'utf8') > maxBytes && dropped.length > 0) {
+        // HALVED RATHER THAN SHIFTED ONE AT A TIME: a 100 MB archive of 4 000
+        // messages would otherwise re-serialize 4 000 times, inside a write that is
+        // supposed to be invisible to the run.
+        dropped = dropped.slice(Math.max(1, Math.ceil(dropped.length / 2)));
+        clipped = true;
+        text = JSON.stringify({ ...doc, dropped, clipped }, null, 2);
+    }
+    return text;
+}
+/**
+ * Write one archive, then prune. Returns the path written, or `null`.
+ *
+ * NEVER THROWS. The caller runs inside an event handler on the compaction path;
+ * a filesystem is not allowed to affect whether a session survives its context
+ * window. Every failure is a `warn` with the path and nothing else - a toast for
+ * a best-effort audit file trains users to ignore toasts.
+ */
+export function writeArchive(input) {
+    const dir = input.dir ?? getCompactionArchiveDir();
+    const now = input.now ?? Date.now();
+    const path = join(dir, archiveFileName(input.runId, input.index, new Date(now)));
+    try {
+        mkdirSync(dir, { recursive: true });
+        const doc = {
+            version: ARCHIVE_FORMAT_VERSION,
+            blockVersion: COMPACTION_BLOCK_VERSION,
+            createdAt: now,
+            runId: input.runId,
+            index: input.index,
+            trigger: input.trigger,
+            mode: input.mode,
+            model: input.model,
+            generation: input.generation,
+            tokensBefore: input.tokensBefore,
+            tokensAfter: input.tokensAfter,
+            messagesBefore: input.messagesBefore,
+            messagesAfter: input.messagesAfter,
+            droppedCount: input.dropped.length,
+            ...(input.summary !== undefined ? { summary: input.summary } : {}),
+            ...(input.tailRelief ? { tailRelief: input.tailRelief } : {}),
+            clipped: false,
+            dropped: input.dropped,
+        };
+        writeFileSync(path, serializeArchive(doc, COMPACTION_LIMITS.archiveMaxBytes), 'utf8');
+    }
+    catch (err) {
+        getLogger()
+            .child('compaction')
+            .warn('compaction_archive_failed', { path, error: errorText(err) });
+        return null;
+    }
+    pruneArchives(input.runId, dir, now);
+    return path;
+}
+/**
+ * Two-tier retention, and the ORDER MATTERS (§3.5.2 / RV-6).
+ *
+ *  1. WITHIN THIS RUN: keep the newest `archiveMaxFiles` files carrying THIS
+ *     `runId`. This is the bound that protects the user from their own long
+ *     session, and it can never touch another run.
+ *  2. ACROSS RUNS: delete files older than `archiveMaxAgeMs`, regardless of
+ *     `runId`, so an abandoned run's archives do not accumulate forever. AGE, not
+ *     count - a count-based global prune is exactly the rule that deletes a live
+ *     session's work while it is still running.
+ *
+ * Best-effort throughout, in the `enforceRetention` shape: every `rmSync` in its
+ * own `try`, a locked file skipped rather than fatal.
+ */
+export function pruneArchives(runId, dir, now) {
+    let files;
+    try {
+        files = readdirSync(dir)
+            .filter((name) => name.startsWith(FILE_PREFIX) && name.endsWith(FILE_SUFFIX))
+            .map((name) => {
+            const path = join(dir, name);
+            try {
+                return { path, name, mtime: statSync(path).mtimeMs };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((e) => e !== null);
+    }
+    catch {
+        return; // The directory does not exist yet, or is unreadable.
+    }
+    const mine = files
+        .filter((f) => parseArchiveName(f.name)?.runId === runId)
+        .sort((a, b) => a.mtime - b.mtime);
+    for (const f of mine.slice(0, Math.max(0, mine.length - COMPACTION_LIMITS.archiveMaxFiles))) {
+        remove(f.path);
+    }
+    for (const f of files) {
+        if (now - f.mtime > COMPACTION_LIMITS.archiveMaxAgeMs)
+            remove(f.path);
+    }
+}
+function remove(path) {
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        // Held by another instance. Retention is best-effort by design.
+    }
+}
+/**
+ * This run's archives, newest first, plus a COUNT of everyone else's.
+ *
+ * THE COUNT IS REPORTED RATHER THAN THE FILES, because the alternative is a user
+ * concluding their own compactions went missing when the directory holds a
+ * neighbour's.
+ */
+export function listArchives(runId, dirOverride) {
+    const dir = dirOverride ?? getCompactionArchiveDir();
+    const entries = [];
+    let otherRuns = 0;
+    let names;
+    try {
+        names = readdirSync(dir).filter((name) => name.startsWith(FILE_PREFIX) && name.endsWith(FILE_SUFFIX));
+    }
+    catch {
+        return { entries: [], otherRuns: 0, dir };
+    }
+    for (const name of names) {
+        if (parseArchiveName(name)?.runId !== runId) {
+            otherRuns += 1;
+            continue;
+        }
+        const entry = readArchiveEntry(join(dir, name), name);
+        if (entry)
+            entries.push(entry);
+    }
+    entries.sort((a, b) => b.index - a.index);
+    return { entries, otherRuns, dir };
+}
+/** One archive by its `#n`, or `null`. `n` is the index within THIS run. */
+export function findArchive(runId, index, dirOverride) {
+    return listArchives(runId, dirOverride).entries.find((e) => e.index === index) ?? null;
+}
+/**
+ * Read one document's METADATA. The `dropped` array is never returned.
+ *
+ * `/compact show` prints no message bodies (DH-9): a single archive can be
+ * megabytes and the transcript is not a pager. The path is the useful output.
+ */
+function readArchiveEntry(path, fileName) {
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        if (raw.version !== ARCHIVE_FORMAT_VERSION)
+            return null;
+        return {
+            path,
+            fileName,
+            index: Number(raw.index ?? 0),
+            createdAt: Number(raw.createdAt ?? 0),
+            trigger: (raw.trigger ?? 'pressure'),
+            mode: (raw.mode ?? 'none'),
+            model: String(raw.model ?? ''),
+            tokensBefore: Number(raw.tokensBefore ?? 0),
+            tokensAfter: Number(raw.tokensAfter ?? 0),
+            droppedCount: Number(raw.droppedCount ?? 0),
+            ...(typeof raw.summary === 'string' ? { summary: raw.summary } : {}),
+            ...(raw.tailRelief ? { tailRelief: raw.tailRelief } : {}),
+            clipped: raw.clipped === true,
+        };
+    }
+    catch {
+        // A half-written file from a process that was killed mid-write, or a format
+        // from a future version. Skipping it is the only sensible reading.
+        return null;
+    }
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}