@aragon-agent/cli 0.5.12 → 0.6.1

package/dist/exec/stdin-stream.js

@@ -0,0 +1,144 @@
+/**
+ * `--input-format stream-json`: an NDJSON reader on stdin
+ * (cli-integration-surface section 4.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * TOLERANT BY CONTRACT (AC-20). A malformed line yields ONE non-fatal `error`
+ * event and is skipped; an unknown `type` is ignored entirely. The forward
+ * compatibility the schema promises consumers has to run in both directions, or
+ * a caller written against a newer version could not talk to an older CLI at
+ * all - and a run that dies on one bad line is the worst possible failure for a
+ * long-lived worker feeding turns down a pipe.
+ *
+ * Three message types are understood:
+ *
+ *   { "type": "user", "text": "..." }   the next turn
+ *   { "type": "interrupt" }             abort the turn in flight
+ *   { "type": "end" }                   no more turns; settle and exit
+ *
+ * Reaching end-of-stream means the same as `end`, so a caller that simply closes
+ * the pipe is not punished for it.
+ */
+/**
+ * A prompt source backed by NDJSON on stdin.
+ *
+ * IT BUFFERS RATHER THAN PAUSING THE STREAM. A caller may legitimately push
+ * three turns in one write before the first has finished, and a reader that only
+ * accepted a line when someone was waiting for one would deadlock the second and
+ * third behind a turn that is minutes long.
+ */
+export function createStdinPromptSource(opts) {
+    const queue = [];
+    const waiting = [];
+    let finished = false;
+    let buffer = '';
+    const deliver = (text) => {
+        const resolve = waiting.shift();
+        if (resolve)
+            resolve(text);
+        else
+            queue.push(text);
+    };
+    const finish = () => {
+        if (finished)
+            return;
+        finished = true;
+        // Everything still parked is answered with `null`, so a `next()` in flight
+        // when the pipe closes resolves instead of hanging the process forever.
+        while (waiting.length > 0)
+            waiting.shift()?.(null);
+    };
+    const handleLine = (line) => {
+        // AFTER `end`, NOTHING ELSE IS A TURN. Lines arrive in chunks, so a caller
+        // that wrote `end` and a stray `user` in one write would otherwise have the
+        // second QUEUED and run - the exact opposite of what `end` means, and
+        // invisible until someone looked at the transcript.
+        if (finished)
+            return;
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            opts.onBadLine(`Skipped a line that is not JSON: ${clip(trimmed)}`);
+            return;
+        }
+        if (!parsed || typeof parsed !== 'object') {
+            opts.onBadLine(`Skipped a line that is not a JSON object: ${clip(trimmed)}`);
+            return;
+        }
+        const message = parsed;
+        if (message.type === 'end') {
+            finish();
+            return;
+        }
+        if (message.type === 'interrupt') {
+            opts.onInterrupt();
+            return;
+        }
+        if (message.type !== 'user') {
+            // An unknown type is IGNORED, not reported: reporting it would make every
+            // additive change to the schema noisy for callers running an older CLI.
+            return;
+        }
+        const text = typeof message.text === 'string' ? message.text : message.content;
+        if (typeof text !== 'string' || text.trim().length === 0) {
+            opts.onBadLine('Skipped a "user" message with no non-empty "text".');
+            return;
+        }
+        deliver(text);
+    };
+    opts.input.setEncoding?.('utf-8');
+    opts.input.on('data', (chunk) => {
+        buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+        let index = buffer.indexOf('\n');
+        while (index >= 0) {
+            handleLine(buffer.slice(0, index));
+            buffer = buffer.slice(index + 1);
+            index = buffer.indexOf('\n');
+        }
+    });
+    opts.input.on('end', () => {
+        // A final line with no trailing newline is still a line.
+        if (buffer.length > 0) {
+            handleLine(buffer);
+            buffer = '';
+        }
+        finish();
+    });
+    opts.input.on('error', () => finish());
+    return {
+        next: () => {
+            const queued = queue.shift();
+            if (queued !== undefined)
+                return Promise.resolve(queued);
+            if (finished)
+                return Promise.resolve(null);
+            return new Promise((resolve) => waiting.push(resolve));
+        },
+    };
+}
+/**
+ * Serve a fixed list of prompts, then delegate.
+ *
+ * Used for `aragon exec --input-format stream-json "first turn"`, where the
+ * positional argument is the opening message and stdin supplies the rest.
+ */
+export function prefixSource(prefix, rest) {
+    const pending = [...prefix];
+    return {
+        next: async () => {
+            const first = pending.shift();
+            if (first !== undefined)
+                return first;
+            return rest.next();
+        },
+    };
+}
+function clip(text) {
+    return text.length <= 120 ? text : `${text.slice(0, 117)}...`;
+}

package/dist/logging/install.d.ts

@@ -47,6 +47,28 @@ export declare function setScreenRestore(fn: () => void): void;
  * Replace what a signal does after the flush. The default (a bare
  * `exit(128 + signo)`) is correct for headless, inline and every subcommand;
  * full-screen substitutes one that restores the terminal first.
+ *
+ * A TERMINATOR MAY NOW RETURN WITHOUT EXITING, AND THAT IS A CONTRACT CHANGE
+ * WORTH WRITING DOWN (cli-integration-surface section 3.6 / D-15). The module
+ * header above says of the default "it must exit itself" - true of THAT
+ * terminator, and true because nothing before now had anything to settle.
+ * `aragon exec` does: it aborts the run, persists the session and emits its one
+ * `result` line, so a wrapper reading NDJSON learns the run ended instead of
+ * timing out. Returning is safe here for one specific reason - the logger has
+ * ALREADY FLUSHED by the time this is called, so a terminator that returns
+ * cannot lose log records.
+ *
+ * THE PRICE IS THAT SUCH A TERMINATOR MUST OWN AN EXIT PATH OF ITS OWN. Merely
+ * having a signal listener stops Node terminating by default, so one that
+ * returns and then never exits turns Ctrl-C into "nothing happens". exec's pays
+ * for it with a second-signal escape (a second SIGINT within 2s exits
+ * immediately) and with `process.exitCode` on the settle path. Any future
+ * terminator that returns needs the same two.
+ *
+ * REPLACING, NOT ADDING, IS ALSO NOT OPTIONAL for a caller that wants to be
+ * heard: the listeners registered by `installProcessHooks` run FIRST
+ * (EventEmitter order) and the default terminator exits, so a
+ * `process.on('SIGINT')` added later never runs at all (P0-1).
  */
 export declare function setSignalTerminator(fn: (signo: number) => void): void;
 /** Tests only: undo the hook swaps so cases cannot leak into each other. */

package/dist/logging/install.js

@@ -65,6 +65,28 @@ export function setScreenRestore(fn) {
  * Replace what a signal does after the flush. The default (a bare
  * `exit(128 + signo)`) is correct for headless, inline and every subcommand;
  * full-screen substitutes one that restores the terminal first.
+ *
+ * A TERMINATOR MAY NOW RETURN WITHOUT EXITING, AND THAT IS A CONTRACT CHANGE
+ * WORTH WRITING DOWN (cli-integration-surface section 3.6 / D-15). The module
+ * header above says of the default "it must exit itself" - true of THAT
+ * terminator, and true because nothing before now had anything to settle.
+ * `aragon exec` does: it aborts the run, persists the session and emits its one
+ * `result` line, so a wrapper reading NDJSON learns the run ended instead of
+ * timing out. Returning is safe here for one specific reason - the logger has
+ * ALREADY FLUSHED by the time this is called, so a terminator that returns
+ * cannot lose log records.
+ *
+ * THE PRICE IS THAT SUCH A TERMINATOR MUST OWN AN EXIT PATH OF ITS OWN. Merely
+ * having a signal listener stops Node terminating by default, so one that
+ * returns and then never exits turns Ctrl-C into "nothing happens". exec's pays
+ * for it with a second-signal escape (a second SIGINT within 2s exits
+ * immediately) and with `process.exitCode` on the settle path. Any future
+ * terminator that returns needs the same two.
+ *
+ * REPLACING, NOT ADDING, IS ALSO NOT OPTIONAL for a caller that wants to be
+ * heard: the listeners registered by `installProcessHooks` run FIRST
+ * (EventEmitter order) and the default terminator exits, so a
+ * `process.on('SIGINT')` added later never runs at all (P0-1).
  */
 export function setSignalTerminator(fn) {
     signalTerminator = fn;

package/dist/session/cli-commands.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `aragon sessions` (cli-integration-surface section 4.3).
+ *
+ * ASCII ONLY - `src/session/**` is inside the glyph scanner's scope from this
+ * feature onward.
+ *
+ * `list` AND `prune` SEE ONLY EXEC-MANAGED SESSIONS (P1-5 / R-16 / AC-23). The
+ * sessions directory is SHARED with the TUI's `/save`, so a sweep that treated
+ * every `*.json` as its own would destroy conversations a human saved by hand -
+ * unrecoverable loss, triggered by a maintenance command the docs recommend.
+ * `--all` opts in and says how many foreign files it will touch; `show` and `rm`
+ * take any id, because the user named it.
+ *
+ * NOTHING IS EVER DELETED AUTOMATICALLY. `sessions list` makes the growth
+ * visible; deciding to delete a user's conversations is not a call this CLI
+ * should make on its own.
+ */
+import type { Command } from 'commander';
+import { type SessionListEntry } from './store.js';
+export interface SessionsCliOptions {
+    json?: boolean;
+    lines?: string;
+    all?: boolean;
+    olderThan?: string;
+    dryRun?: boolean;
+    yes?: boolean;
+}
+export declare function registerSessionsCommand(program: Command): void;
+export declare function runSessionsCommand(subcommand: string, argument: string | undefined, opts: SessionsCliOptions): number;
+export type { SessionListEntry };

package/dist/session/cli-commands.js

@@ -0,0 +1,162 @@
+/**
+ * `aragon sessions` (cli-integration-surface section 4.3).
+ *
+ * ASCII ONLY - `src/session/**` is inside the glyph scanner's scope from this
+ * feature onward.
+ *
+ * `list` AND `prune` SEE ONLY EXEC-MANAGED SESSIONS (P1-5 / R-16 / AC-23). The
+ * sessions directory is SHARED with the TUI's `/save`, so a sweep that treated
+ * every `*.json` as its own would destroy conversations a human saved by hand -
+ * unrecoverable loss, triggered by a maintenance command the docs recommend.
+ * `--all` opts in and says how many foreign files it will touch; `show` and `rm`
+ * take any id, because the user named it.
+ *
+ * NOTHING IS EVER DELETED AUTOMATICALLY. `sessions list` makes the growth
+ * visible; deciding to delete a user's conversations is not a call this CLI
+ * should make on its own.
+ */
+import process from 'node:process';
+import { listSessions, pruneSessions, readSessionFile, removeSession, sessionPathFor, sessionsDir, } from './store.js';
+const SUBCOMMANDS = ['list', 'show', 'rm', 'prune', 'path'];
+export function registerSessionsCommand(program) {
+    program
+        .command('sessions [subcommand] [argument]')
+        .description('Manage `aragon exec` sessions: list | show | rm | prune | path')
+        .option('--json', 'Machine-readable output')
+        .option('-n, --lines <n>', 'Entries for `sessions list` (default 20)')
+        .option('--all', 'Include sessions this CLI did not create (TUI `/save` files)')
+        .option('--older-than <days>', 'Only prune sessions untouched for this many days')
+        .option('--dry-run', 'Print what `sessions prune` would delete, and delete nothing')
+        .option('--yes', 'Confirm destructive actions (required by `rm` and `prune`)')
+        .action((subcommand, argument, opts) => {
+        process.exitCode = runSessionsCommand(subcommand ?? 'list', argument, opts);
+    });
+}
+export function runSessionsCommand(subcommand, argument, opts) {
+    switch (subcommand) {
+        case 'path':
+            process.stdout.write(`${sessionsDir()}\n`);
+            return 0;
+        case 'list':
+            return runList(opts);
+        case 'show':
+            return runShow(argument, opts);
+        case 'rm':
+            return runRemove(argument, opts);
+        case 'prune':
+            return runPrune(opts);
+        default:
+            process.stderr.write(`Unknown sessions subcommand "${subcommand}". Choose: ${SUBCOMMANDS.join(' | ')}.\n`);
+            return 2;
+    }
+}
+function runList(opts) {
+    const limit = parseCount(opts.lines) ?? 20;
+    const entries = listSessions({ ...(opts.all ? { all: true } : {}) }).slice(0, limit);
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(entries, null, 2)}\n`);
+        return 0;
+    }
+    if (entries.length === 0) {
+        process.stdout.write(opts.all
+            ? 'No sessions found.\n'
+            : 'No `aragon exec` sessions found. Pass --all to include TUI /save files.\n');
+        return 0;
+    }
+    for (const entry of entries) {
+        process.stdout.write(`${entry.id}  ${stamp(entry.updatedAt)}  ${entry.turns} turns  ` +
+            `${entry.provider}/${entry.model}  ${entry.cwd}\n`);
+    }
+    return 0;
+}
+function runShow(argument, opts) {
+    if (!argument) {
+        process.stderr.write('Usage: aragon sessions show <id> [--json]\n');
+        return 2;
+    }
+    const path = sessionPathFor(argument);
+    const session = readSessionFile(path);
+    if (!session) {
+        process.stderr.write(`session_not_found: no readable session "${argument}".\n`);
+        return 2;
+    }
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(session, null, 2)}\n`);
+        return 0;
+    }
+    // THE BODIES ARE NOT PRINTED WITHOUT `--json`. A session transcript can be
+    // megabytes and is frequently the most sensitive thing on the machine; a
+    // command whose job is "tell me about this session" should not paste it into a
+    // shared terminal because someone typed an id.
+    const meta = session.meta;
+    process.stdout.write([
+        `id        ${meta?.id ?? argument}`,
+        `path      ${path}`,
+        `saved     ${stamp(session.savedAt)}`,
+        `cwd       ${meta?.cwd ?? '(unknown)'}`,
+        `turns     ${meta?.turns ?? 0}`,
+        `model     ${meta?.provider ?? session.model?.providerId ?? '?'}/${meta?.model ?? session.model?.modelId ?? '?'}`,
+        `messages  ${session.messages.length}`,
+        `todos     ${session.todos?.length ?? 0}`,
+        `managed   ${meta?.id ? 'yes (aragon exec)' : 'no (TUI /save)'}`,
+        '',
+    ].join('\n'));
+    return 0;
+}
+function runRemove(argument, opts) {
+    if (!argument) {
+        process.stderr.write('Usage: aragon sessions rm <id> --yes\n');
+        return 2;
+    }
+    if (!opts.yes) {
+        process.stderr.write('Refusing to delete without --yes.\n');
+        return 2;
+    }
+    if (!removeSession(argument)) {
+        process.stderr.write(`session_not_found: no session "${argument}".\n`);
+        return 2;
+    }
+    process.stdout.write(`Removed ${argument}.\n`);
+    return 0;
+}
+function runPrune(opts) {
+    const days = parseCount(opts.olderThan);
+    if (opts.olderThan !== undefined && days === null) {
+        process.stderr.write('--older-than takes a non-negative number of days.\n');
+        return 2;
+    }
+    if (!opts.dryRun && !opts.yes) {
+        process.stderr.write('Refusing to prune without --yes. Use --dry-run to preview.\n');
+        return 2;
+    }
+    const doomed = pruneSessions({
+        ...(days !== null ? { olderThanDays: days } : {}),
+        ...(opts.dryRun ? { dryRun: true } : {}),
+        ...(opts.all ? { all: true } : {}),
+    });
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(doomed, null, 2)}\n`);
+        return 0;
+    }
+    const verb = opts.dryRun ? 'Would remove' : 'Removed';
+    for (const entry of doomed)
+        process.stdout.write(`${verb} ${entry.id}  ${stamp(entry.updatedAt)}\n`);
+    const foreign = doomed.filter((e) => !e.managed).length;
+    process.stdout.write(`${verb.toLowerCase()} ${doomed.length} session(s)` +
+        (foreign > 0 ? `, ${foreign} of them saved from the TUI (--all was given).` : '.') +
+        '\n');
+    return 0;
+}
+function parseCount(raw) {
+    if (raw === undefined)
+        return null;
+    if (!/^\d+$/.test(raw.trim()))
+        return null;
+    return Number.parseInt(raw.trim(), 10);
+}
+/** ISO-8601 without the fractional seconds. ASCII, sortable, unambiguous. */
+function stamp(ms) {
+    if (!ms)
+        return '-';
+    return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}

package/dist/session/persist.d.ts

@@ -8,6 +8,34 @@
 import type { Message, ModelRef } from '@aragon-agent/core';
 import type { Entry } from '../agent/reducer.js';
 import type { TodoItem } from '../todo/types.js';
+/**
+ * Bookkeeping `aragon exec` attaches to the sessions it owns
+ * (cli-integration-surface §5.2).
+ *
+ * ITS PRESENCE IS ALSO A MARKER, AND THAT IS LOAD-BEARING (P1-5 / R-16). This
+ * directory is SHARED with the TUI's `/save`: `resolveSessionPath` above puts
+ * every bare-name and default `/save` target in `getSessionsDir()`. So
+ * `aragon sessions list` / `prune` operate ONLY on files carrying `meta.id`,
+ * which is what stops a maintenance command destroying conversations a human
+ * saved by hand. Anything that starts writing `meta` from the TUI path must
+ * revisit that scoping first.
+ */
+export interface SessionMeta {
+    id: string;
+    cwd: string;
+    createdAt: number;
+    updatedAt: number;
+    /** Cumulative across invocations, not per run. */
+    turns: number;
+    /** The CLI version that last wrote this file. */
+    cli: string;
+    provider: string;
+    model: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
 export interface SavedSession {
     version: number;
     savedAt: number;
@@ -23,6 +51,16 @@ export interface SavedSession {
      * right answer for a session that predates the feature (D-20 / D-22).
      */
     todos?: TodoItem[];
+    /**
+     * Written only by `aragon exec` (cli-integration-surface §5.2 / D-10).
+     *
+     * `SESSION_VERSION` STAYS 1 for the reason `todos?` records above, and this is
+     * the precedent that file's own comments already set: the field is additive
+     * and optional, and `loadSession` validates only array-ness of `messages` /
+     * `entries`. A TUI `/save` file simply has no `meta`, which is exactly how
+     * `sessions list` tells the two apart.
+     */
+    meta?: SessionMeta;
 }
 /** Resolve a `/save` target: absolute/relative path, or a name in the data dir. */
 export declare function resolveSessionPath(nameOrPath: string | undefined, cwd: string): string;
@@ -31,12 +69,20 @@ export declare function resolveSessionPath(nameOrPath: string | undefined, cwd:
  * the writer below builds its payload from THIS parameter, not from the type, so
  * a `todos?` field on the interface with no field here would ship a key nothing
  * ever writes.
+ *
+ * `meta` JOINS ON EXACTLY THOSE TERMS (cli-integration-surface P2-6). Adding it
+ * to `SavedSession` alone would type-check, `aragon exec` would appear to write
+ * sessions, and `sessions list` would report none of them — because the marker
+ * that identifies an exec-managed file would never be on disk. It is SPREAD
+ * conditionally so a `/save` from the TUI, which passes no `meta`, produces a
+ * payload with no such key and a file byte-identical to today's.
  */
 export declare function saveSession(filePath: string, data: {
     model: ModelRef;
     messages: Message[];
     entries: Entry[];
     todos: TodoItem[];
+    meta?: SessionMeta;
 }): void;
 /**
  * Settle any team entry that was saved mid-dispatch (team-subagents §5.3 / P1-5),

package/dist/session/persist.js

@@ -64,6 +64,13 @@ function stripLiveToolOutput(entries) {
  * the writer below builds its payload from THIS parameter, not from the type, so
  * a `todos?` field on the interface with no field here would ship a key nothing
  * ever writes.
+ *
+ * `meta` JOINS ON EXACTLY THOSE TERMS (cli-integration-surface P2-6). Adding it
+ * to `SavedSession` alone would type-check, `aragon exec` would appear to write
+ * sessions, and `sessions list` would report none of them — because the marker
+ * that identifies an exec-managed file would never be on disk. It is SPREAD
+ * conditionally so a `/save` from the TUI, which passes no `meta`, produces a
+ * payload with no such key and a file byte-identical to today's.
  */
 export function saveSession(filePath, data) {
     const dir = dirname(filePath);
@@ -76,6 +83,7 @@ export function saveSession(filePath, data) {
         messages: data.messages,
         entries: stripLiveToolOutput(data.entries),
         todos: data.todos,
+        ...(data.meta ? { meta: data.meta } : {}),
     };
     writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
 }

package/dist/session/store.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The id-keyed session store behind `aragon exec` (cli-integration-surface
+ * section 3.4 / 4.3).
+ *
+ * ASCII ONLY - `src/session/**` is inside the glyph scanner's scope from this
+ * feature onward (R-3 / AC-25). `session/` was outside the predicate BEFORE this
+ * change too, so adding it is closing a pre-existing hole rather than extending
+ * a guard to new code.
+ *
+ * `persist.ts` KEEPS THE FILE FORMAT; this module owns identity, listing,
+ * retention and mutual exclusion. The two exist separately because the format is
+ * shared with the TUI's `/save` and must not acquire exec-shaped opinions.
+ *
+ * THE DIRECTORY IS SHARED WITH `/save`, AND EVERY LISTING RULE HERE FOLLOWS FROM
+ * THAT (P1-5 / R-16). `resolveSessionPath` puts every bare-name and default
+ * `/save` target in `getSessionsDir()`, so a naive `prune` would delete
+ * conversations a human saved by hand - unrecoverable loss, from a maintenance
+ * command the docs recommend. `list` and `prune` therefore see only files
+ * carrying `meta.id`; `show` and `rm` accept any id, because the user named it.
+ */
+import { type SavedSession, type SessionMeta } from './persist.js';
+/**
+ * The id is a FILENAME under the user's home directory, and the caller supplying
+ * it is frequently the least trusted input in the pipeline (a branch name, a
+ * ticket id, a webhook field). Rejecting `/`, `\`, `..` and a leading dot is a
+ * SECURITY REQUIREMENT, not tidiness (R-7 / AC-8).
+ *
+ * A leading dot is excluded by the first character class rather than by a
+ * separate check, which is also what keeps `.last.json` unreachable as an id.
+ */
+export declare const SESSION_ID_RE: RegExp;
+export declare function isValidSessionId(id: string): boolean;
+/**
+ * 10 minutes, matching `UPDATE_LIMITS.lockTtlMs`.
+ *
+ * The TTL is the WORST CASE for a wedge, so a long one is not the safe choice:
+ * without the liveness probe below, a CI job killed mid-run would hold its
+ * `--session-id` for the whole window and every retry would return
+ * `session_busy` - a hang wearing an exit code, in the one environment this
+ * feature exists for.
+ */
+export declare const SESSION_LOCK_TTL_MS = 600000;
+export interface SessionListEntry {
+    id: string;
+    path: string;
+    savedAt: number;
+    updatedAt: number;
+    cwd: string;
+    turns: number;
+    provider: string;
+    model: string;
+    /** `true` when the file carries `meta.id`, i.e. `aragon exec` wrote it. */
+    managed: boolean;
+}
+export declare function sessionsDir(): string;
+export declare function sessionPathFor(id: string): string;
+/** Read one file, or `null` for anything unreadable. NEVER THROWS. */
+export declare function readSessionFile(path: string): SavedSession | null;
+/**
+ * Resolve `--resume <id|path>` to a file that exists, or `null`.
+ *
+ * A value containing a separator, or an absolute one, is a PATH; anything else
+ * is an id. That split is the same one `resolveSessionPath` makes for `/save`,
+ * so the two spellings agree about what "a name" means.
+ */
+export declare function resolveSessionRef(idOrPath: string, cwd: string): string | null;
+export interface WriteSessionInput {
+    id: string;
+    session: Omit<SavedSession, 'version' | 'savedAt' | 'meta'>;
+    meta: SessionMeta;
+}
+/**
+ * Write a session and refresh the `--continue` pointer.
+ *
+ * THE POINTER IS UPDATED AFTER THE FILE, never before: a crash between the two
+ * leaves a pointer naming a file that is one run stale, which the fallback scan
+ * corrects. The other order would leave a pointer naming a file that does not
+ * exist yet.
+ */
+export declare function writeSession(input: WriteSessionInput): string;
+export declare function removeSession(id: string): boolean;
+/**
+ * Every session in the directory, newest first.
+ *
+ * `all: false` (the default) keeps ONLY exec-managed files. `.last.json` and
+ * `*.lock` are excluded by name on both paths, because neither is a session in
+ * any sense and listing them would invite `sessions rm` on the pointer.
+ */
+export declare function listSessions(opts?: {
+    all?: boolean;
+}): SessionListEntry[];
+export interface PruneOptions {
+    olderThanDays?: number;
+    dryRun?: boolean;
+    all?: boolean;
+    now?: () => number;
+}
+/** `--dry-run` reports and deletes nothing; nothing is ever pruned automatically. */
+export declare function pruneSessions(opts?: PruneOptions): SessionListEntry[];
+/**
+ * The newest exec session whose `meta.cwd` matches, or `null`.
+ *
+ * THE POINTER IS A CACHE AND IS TREATED AS ONE (R-9 / AC-9). If it is missing,
+ * unparseable, or names a file that is gone, this falls through to reading the
+ * directory - so a desync SELF-HEALS instead of stranding the user, which is the
+ * property that makes it safe to keep a denormalised index at all.
+ */
+export declare function latestSessionForCwd(cwd: string): SessionListEntry | null;
+export interface SessionLockHandle {
+    path: string;
+    release(): void;
+}
+export interface SessionLockOptions {
+    now?: () => number;
+    /** Injected for tests; defaults to `process.kill(pid, 0)` liveness probing. */
+    isProcessAlive?: (pid: number) => boolean;
+}
+/**
+ * Take the lock for one `--session-id`, or report that someone else has it.
+ * NEVER SLEEPS, NEVER THROWS (D-11).
+ *
+ * ONE ATTEMPT, NO RETRY. A second process exits 2 with `session_busy` rather
+ * than waiting, because a wrapper that wants a queue can build one and a CLI
+ * that blocks for an unbounded time on a lock it cannot show the user is a hang.
+ * `skills/lock.ts::acquireRootLock` busy-waits through `Atomics.wait` and
+ * throws, which is right for a human who typed `aragon skills install` and wrong
+ * for a background caller; `update/install-lock.ts` already made that split.
+ */
+export declare function tryAcquireSessionLock(id: string, opts?: SessionLockOptions): SessionLockHandle | null;