@aragon-agent/cli 0.6.24 → 0.6.26

package/dist/session/clear-archive.js

@@ -0,0 +1,160 @@
+/**
+ * Archive the conversation a `/clear` is about to destroy
+ * (clear-command-context-reset §3.8 / D-5 / I-5).
+ *
+ * ASCII ONLY: `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THIS EXISTS AT ALL: a command whose whole job is to destroy context is a
+ * command a user will eventually fire by accident, one keystroke from `/cwd`. The
+ * difference between "I lost an hour of work" and "I resumed it" is one file, and
+ * `saveSession()` already knows how to write it.
+ *
+ * WHY THIS IS NOT `session/store.ts::writeSession()`: that function MOVES THE
+ * `--continue` POINTER and writes `meta`. An archive is not a session you continue;
+ * it is a record you resume BY PATH. Writing `meta` would also make the file look
+ * `aragon exec`-managed to `sessions list` / `prune`, which is the scoping rule
+ * `persist.ts` records at the top of `SessionMeta` - so a maintenance command would
+ * start deleting the user's cleared conversations.
+ *
+ * ISOLATION IS TWO DEEP (I-6 / P2-4). The directory is the first fence:
+ * `listSessions` / `pruneSessions` / `latestSessionForCwd` read `sessionsDir()`
+ * non-recursively and skip anything not ending in `.json` (`store.ts`), so a
+ * SUBDIRECTORY name is invisible to all three by construction. Omitting `meta` is
+ * the second fence, for the day someone makes that listing recursive or gives
+ * `--all` a wider meaning.
+ */
+import { mkdirSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+import { getLogger } from '../logging/logger.js';
+import { saveSession } from './persist.js';
+import { sessionsDir } from './store.js';
+/** Bounded retention: the newest N cleared conversations survive. */
+export const CLEAR_ARCHIVE_LIMITS = { maxArchives: 20 };
+/** `<sessions>/cleared` - a subdirectory, which is the first isolation fence. */
+const CLEARED_DIR_NAME = 'cleared';
+/** Every archive's filename starts with this, which is what `prune` selects on. */
+const ARCHIVE_PREFIX = 'cleared-';
+/**
+ * Best-effort archive of the conversation being cleared.
+ *
+ * @returns the absolute path of the written file, or `null` when there was
+ * nothing to save (an empty conversation) or the write failed. NEVER THROWS:
+ * a full disk must not be able to stop a user from starting a new conversation
+ * (I-5), and a caller that had to wrap this in `try` would eventually forget.
+ */
+export function archiveClearedConversation(input) {
+    // Clearing an empty conversation produces no file. Without this, every
+    // `/clear` on a fresh session would litter the directory with empty archives
+    // and push a real one out of the retention window.
+    if (input.messages.length === 0)
+        return null;
+    const dir = join(sessionsDir(), CLEARED_DIR_NAME);
+    const path = join(dir, `${archiveId(new Date())}.json`);
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch (err) {
+        getLogger().debug('agent', 'clear_archive_failed', { reason: reasonOf(err) });
+        return null;
+    }
+    // DEGRADE AND RETRY (P1-6 / C-8). `saveSession` VALIDATES the compaction
+    // identity and THROWS on a damaged or stale one, and an interrupted
+    // conversation - the one a user most wants back - is exactly the one most
+    // likely to carry a stale identity. Losing a whole conversation to an
+    // accessory field would break the only promise this module makes, so the
+    // second attempt drops it: `messages` is what makes the archive recoverable,
+    // the identity only lets the NEXT compaction reuse a prefix.
+    //
+    // The retry runs ONLY when there is an identity to drop. A disk that refused
+    // the first write will refuse an identical second one, so retrying without one
+    // would just double the log line and the wait without changing the outcome.
+    const wrote = writeArchive(path, input, true)
+        || (input.compactionIdentity !== undefined && writeArchive(path, input, false));
+    if (!wrote)
+        return null;
+    pruneArchives(dir);
+    return path;
+}
+/**
+ * One write attempt. `withIdentity` is the only difference between the first and
+ * the degraded second attempt, which is why it is a parameter rather than a
+ * duplicated body.
+ */
+function writeArchive(path, input, withIdentity) {
+    const identity = withIdentity ? input.compactionIdentity : undefined;
+    try {
+        saveSession(path, {
+            model: input.model,
+            messages: input.messages,
+            ...(identity ? { compactionIdentity: identity } : {}),
+            entries: input.entries,
+            todos: input.todos,
+        });
+        return true;
+    }
+    catch (err) {
+        getLogger().debug('agent', 'clear_archive_write_failed', {
+            withIdentity, reason: reasonOf(err),
+        });
+        return false;
+    }
+}
+/**
+ * Deterministic, collision-free id (P2-3).
+ *
+ * `cleared-<yyyyMMdd>-<HHmmss>-<pid>` is ASCII, matches `isValidSessionId`
+ * (`[A-Za-z0-9][A-Za-z0-9._-]*`), and is legible enough to type after
+ * `/resume `. The pid removes cross-process collisions; within one process a
+ * second `cleared-` file in the same second is unreachable because the FIRST
+ * clear leaves an empty conversation and `archiveClearedConversation` returns
+ * early on that. So no `-2`/`-3` suffix ladder is needed, and none is here.
+ */
+function archiveId(at) {
+    const pad = (n) => String(n).padStart(2, '0');
+    const day = `${at.getFullYear()}${pad(at.getMonth() + 1)}${pad(at.getDate())}`;
+    const clock = `${pad(at.getHours())}${pad(at.getMinutes())}${pad(at.getSeconds())}`;
+    return `${ARCHIVE_PREFIX}${day}-${clock}-${process.pid}`;
+}
+/**
+ * Keep the newest `maxArchives` files; delete the rest.
+ *
+ * A sweep, not a scheduled job: retention that runs on the write path cannot be
+ * forgotten, and the failure mode of a missed sweep is bounded disk usage rather
+ * than unbounded. Every error here is swallowed on purpose - pruning is
+ * housekeeping and must never be able to fail a clear that already succeeded.
+ */
+function pruneArchives(dir) {
+    const survivors = [];
+    for (const name of safeReaddir(dir)) {
+        if (!name.startsWith(ARCHIVE_PREFIX) || !name.endsWith('.json'))
+            continue;
+        const path = join(dir, name);
+        try {
+            survivors.push({ path, modified: statSync(path).mtimeMs });
+        }
+        catch {
+            // A file that vanished between listing and stat is already deleted.
+        }
+    }
+    survivors.sort((a, b) => b.modified - a.modified);
+    for (const doomed of survivors.slice(CLEAR_ARCHIVE_LIMITS.maxArchives)) {
+        try {
+            unlinkSync(doomed.path);
+        }
+        catch (err) {
+            getLogger().debug('agent', 'clear_archive_prune_failed', { reason: reasonOf(err) });
+        }
+    }
+}
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function reasonOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}

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

@@ -21,6 +21,8 @@ export interface SessionsCliOptions {
     json?: boolean;
     lines?: string;
     all?: boolean;
+    /** `exec` (default) | `tui` | `all`; see the truth table in §3.7. */
+    origin?: string;
     olderThan?: string;
     dryRun?: boolean;
     yes?: boolean;

package/dist/session/cli-commands.js

@@ -34,7 +34,13 @@ export function registerSessionsCommand(program) {
         .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)')
+        // TWO ORTHOGONAL AXES, TWO FLAGS (tui-session-id-resume 3.7 / R-7).
+        // `--all` widens "which rows exist" to files with no metadata at all; it can no
+        // longer reach a TUI checkpoint, because a TUI checkpoint HAS metadata and is
+        // separated by `--origin` instead. One merged axis made `--all` a maintenance
+        // command that deleted the conversation the user was still having.
+        .option('--all', 'Also include files with no session metadata (hand-written /save exports)')
+        .option('--origin <exec|tui|all>', 'Which writer `prune` may touch (default: exec)')
         .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`)')
@@ -70,12 +76,17 @@ function runList(opts) {
     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');
+            : 'No sessions found. Pass --all to include files with no session metadata.\n');
         return 0;
     }
     for (const entry of entries) {
+        // THE ORIGIN COLUMN IS THE ONE VISIBLE CHANGE TO THIS LINE (I-7), and it is
+        // what makes `prune --origin` comprehensible: without it a user cannot tell
+        // which of these files a sweep would touch. `pin` follows it for the same
+        // reason - a file that can never be pruned should look like one.
+        const tags = `${entry.origin ?? 'exec'}${entry.pinned ? '  pin' : ''}`;
         process.stdout.write(`${entry.id}  ${stamp(entry.updatedAt)}  ${entry.turns} turns  ` +
-            `${entry.provider}/${entry.model}  ${entry.cwd}\n`);
+            `${entry.provider}/${entry.model}  ${tags}  ${entry.cwd}\n`);
     }
     return 0;
 }
@@ -112,7 +123,9 @@ function runShow(argument, opts) {
         `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)'}`,
+        `origin    ${meta?.origin === 'tui' ? 'tui (session checkpoint)' : 'exec'}`,
+        `pinned    ${meta?.pinned === true ? 'yes' : 'no'}`,
+        `managed   ${meta?.id ? 'yes' : 'no (TUI /save)'}`,
         '',
     ].join('\n'));
     return 0;
@@ -142,6 +155,11 @@ function runRemove(argument, opts) {
     return 0;
 }
 function runPrune(opts) {
+    const originScope = parseOrigin(opts.origin);
+    if (originScope === null && opts.origin !== undefined) {
+        process.stderr.write('--origin takes exec, tui or all.\n');
+        return 2;
+    }
     const days = parseCount(opts.olderThan);
     if (opts.olderThan !== undefined && days === null) {
         process.stderr.write('--older-than takes a non-negative number of days.\n');
@@ -155,6 +173,7 @@ function runPrune(opts) {
         ...(days !== null ? { olderThanDays: days } : {}),
         ...(opts.dryRun ? { dryRun: true } : {}),
         ...(opts.all ? { all: true } : {}),
+        ...(originScope !== null ? { origin: originScope } : {}),
     });
     if (opts.json) {
         process.stdout.write(`${JSON.stringify(doomed, null, 2)}\n`);
@@ -163,12 +182,24 @@ function runPrune(opts) {
     const verb = opts.dryRun ? 'Would remove' : 'Removed';
     for (const entry of doomed)
         process.stdout.write(`${verb} ${entry.id}  ${stamp(entry.updatedAt)}\n`);
+    // `foreign` NOW MEANS EXACTLY ONE THING: files with NO metadata, i.e. a
+    // hand-written `/save` export reached only because `--all` was given. TUI
+    // checkpoints are managed and are reported through `--origin tui` instead, so
+    // this sentence can no longer claim something about a file it does not describe
+    // (R-7).
     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).` : '.') +
+        (foreign > 0 ? `, ${foreign} with no session metadata (--all was given).` : '.') +
         '\n');
     return 0;
 }
+/** `--origin` accepts the two writers plus `all`; anything else is refused. */
+function parseOrigin(raw) {
+    if (raw === undefined)
+        return null;
+    const value = raw.trim().toLowerCase();
+    return value === 'exec' || value === 'tui' || value === 'all' ? value : null;
+}
 function parseCount(raw) {
     if (raw === undefined)
         return null;

package/dist/session/identity.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Session identity: minting, branching, deriving, and reserving
+ * (tui-session-id-resume §3.5 / D-1 / D-5 / D-23).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * ONE AUTHORITY FOR "WHAT IS A SESSION CALLED". `store.ts` already owns the
+ * SYNTAX (`SESSION_ID_RE`) and the path (`sessionPathFor`); this module owns the
+ * generator and the branch rule, and it produces ids that pass that syntax by
+ * construction rather than by a second regex nobody re-checks.
+ *
+ * BRANCHING NEVER REUSES THE PARENT ID (D-5 / I-3). A `--resume` always derives
+ * a NEW id, so two processes can never take turns overwriting one file: the
+ * parent keeps writing its own id, the branch writes its own. That is the whole
+ * technical content of "a branch must not affect the session it branched from".
+ */
+import type { ModelRef } from '@aragon-agent/core';
+/**
+ * 31 characters: the ten digits and the lowercase alphabet MINUS `0 o 1 l i`.
+ *
+ * Those five are the pairs a human misreads when copying an id out of the
+ * bottom-right corner of a terminal, and copying an id by eye is the one
+ * irreducible failure mode this feature has (D-14 exists to remove it, and this
+ * alphabet removes most of the rest).
+ */
+export declare const SESSION_ID_ALPHABET = "23456789abcdefghjkmnpqrstuvwxyz";
+/** A fresh 6-character id. Satisfies `SESSION_ID_RE` by construction (D-1). */
+export declare function createSessionId(random?: () => number): string;
+/**
+ * The child id for `parentId`: 6-character root plus `-` plus 4 characters.
+ *
+ * THE ROOT DOES NOT GROW. `a4k2m9` and `a4k2m9-x7f2` both branch to
+ * `a4k2m9-<new>`, so a chain of branches keeps a name that still fits the
+ * status bar and still points at the conversation it came from.
+ */
+export declare function branchSessionId(parentId: string, random?: () => number): string;
+/** Whether `id` is a shape this CLI mints (as opposed to a hand-chosen name). */
+export declare function isGeneratedSessionId(id: string): boolean;
+/**
+ * The next id for a session LOADED FROM `loadedPath`, or `null` when the file
+ * name is not a generated id.
+ *
+ * THE INPUT IS A PATH, NOT AN ID, AND THE PARENT'S IDENTITY COMES FROM THE FILE
+ * NAME (D-5 / R-8). `meta.id` lives inside the file, and a file is input - a
+ * hand-written `meta.id` must not be able to name where this process writes.
+ * `null` means "this was a `/save` export or an archive": the caller mints a
+ * fresh id and the new file has no `branchOf`.
+ */
+export declare function derivedChildId(loadedPath: string, random?: () => number): string | null;
+/**
+ * Claim `id` with an atomic `wx` create, writing a READABLE EMPTY SESSION into
+ * it (D-23 / R-3).
+ *
+ * `wx` IS THE MUTUAL EXCLUSION and stays that way: `existsSync` followed by a
+ * write has a window in which two processes both see "absent". What changed in
+ * v2 is the CONTENT. A 0-byte placeholder is unparseable, so `loadSession()`
+ * throws a raw `SyntaxError` on it, `listSessions` silently skips it, and
+ * `--save` refuses the name forever - a file the user can neither see nor
+ * resume. A legal empty `SavedSession` fixes all three at once: it loads, it
+ * lists, and `sessions rm` can delete it.
+ *
+ * NO `meta` IS WRITTEN, deliberately: "has `meta`" stays equivalent to "at least
+ * one checkpoint has been written", which is the predicate `sessions list` /
+ * `prune` are built on. `model` is written only when the caller has one - it is
+ * optional in the format, and the startup path resolves an identity BEFORE the
+ * controller exists, so a fabricated model would be a lie on disk for a field
+ * nothing reads back.
+ */
+export declare function reserveSessionId(id: string, opts?: {
+    model?: ModelRef;
+    pathFor?: (id: string) => string;
+}): boolean;

package/dist/session/identity.js

@@ -0,0 +1,148 @@
+/**
+ * Session identity: minting, branching, deriving, and reserving
+ * (tui-session-id-resume §3.5 / D-1 / D-5 / D-23).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * ONE AUTHORITY FOR "WHAT IS A SESSION CALLED". `store.ts` already owns the
+ * SYNTAX (`SESSION_ID_RE`) and the path (`sessionPathFor`); this module owns the
+ * generator and the branch rule, and it produces ids that pass that syntax by
+ * construction rather than by a second regex nobody re-checks.
+ *
+ * BRANCHING NEVER REUSES THE PARENT ID (D-5 / I-3). A `--resume` always derives
+ * a NEW id, so two processes can never take turns overwriting one file: the
+ * parent keeps writing its own id, the branch writes its own. That is the whole
+ * technical content of "a branch must not affect the session it branched from".
+ */
+import { closeSync, mkdirSync, openSync, unlinkSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { SESSION_ID_LIMITS } from './limits.js';
+import { basenameId, sessionPathFor } from './store.js';
+/**
+ * 31 characters: the ten digits and the lowercase alphabet MINUS `0 o 1 l i`.
+ *
+ * Those five are the pairs a human misreads when copying an id out of the
+ * bottom-right corner of a terminal, and copying an id by eye is the one
+ * irreducible failure mode this feature has (D-14 exists to remove it, and this
+ * alphabet removes most of the rest).
+ */
+export const SESSION_ID_ALPHABET = '23456789abcdefghjkmnpqrstuvwxyz';
+/** A generated id: 6 characters, optionally with the 4-character branch suffix. */
+const GENERATED_ID_RE = /^([a-z0-9]{6})(?:-([a-z0-9]{4}))?$/;
+/** One character from the alphabet. `random` is injected for deterministic tests. */
+function pick(random) {
+    // `Math.min` because a stubbed generator may legitimately return 1.
+    const index = Math.min(SESSION_ID_ALPHABET.length - 1, Math.floor(Math.abs(random()) * SESSION_ID_ALPHABET.length));
+    return SESSION_ID_ALPHABET[index];
+}
+function randomChars(count, random) {
+    let out = '';
+    for (let i = 0; i < count; i += 1)
+        out += pick(random);
+    return out;
+}
+/** A fresh 6-character id. Satisfies `SESSION_ID_RE` by construction (D-1). */
+export function createSessionId(random = Math.random) {
+    return randomChars(SESSION_ID_LIMITS.idLength, random);
+}
+/**
+ * The child id for `parentId`: 6-character root plus `-` plus 4 characters.
+ *
+ * THE ROOT DOES NOT GROW. `a4k2m9` and `a4k2m9-x7f2` both branch to
+ * `a4k2m9-<new>`, so a chain of branches keeps a name that still fits the
+ * status bar and still points at the conversation it came from.
+ */
+export function branchSessionId(parentId, random = Math.random) {
+    const root = GENERATED_ID_RE.exec(parentId)?.[1];
+    if (!root)
+        return createSessionId(random);
+    const suffix = randomChars(SESSION_ID_LIMITS.suffixLength, random);
+    return `${root}-${suffix}`;
+}
+/** Whether `id` is a shape this CLI mints (as opposed to a hand-chosen name). */
+export function isGeneratedSessionId(id) {
+    return GENERATED_ID_RE.test(id);
+}
+/**
+ * The next id for a session LOADED FROM `loadedPath`, or `null` when the file
+ * name is not a generated id.
+ *
+ * THE INPUT IS A PATH, NOT AN ID, AND THE PARENT'S IDENTITY COMES FROM THE FILE
+ * NAME (D-5 / R-8). `meta.id` lives inside the file, and a file is input - a
+ * hand-written `meta.id` must not be able to name where this process writes.
+ * `null` means "this was a `/save` export or an archive": the caller mints a
+ * fresh id and the new file has no `branchOf`.
+ */
+export function derivedChildId(loadedPath, random = Math.random) {
+    const base = basenameId(loadedPath);
+    return isGeneratedSessionId(base) ? branchSessionId(base, random) : null;
+}
+/**
+ * Claim `id` with an atomic `wx` create, writing a READABLE EMPTY SESSION into
+ * it (D-23 / R-3).
+ *
+ * `wx` IS THE MUTUAL EXCLUSION and stays that way: `existsSync` followed by a
+ * write has a window in which two processes both see "absent". What changed in
+ * v2 is the CONTENT. A 0-byte placeholder is unparseable, so `loadSession()`
+ * throws a raw `SyntaxError` on it, `listSessions` silently skips it, and
+ * `--save` refuses the name forever - a file the user can neither see nor
+ * resume. A legal empty `SavedSession` fixes all three at once: it loads, it
+ * lists, and `sessions rm` can delete it.
+ *
+ * NO `meta` IS WRITTEN, deliberately: "has `meta`" stays equivalent to "at least
+ * one checkpoint has been written", which is the predicate `sessions list` /
+ * `prune` are built on. `model` is written only when the caller has one - it is
+ * optional in the format, and the startup path resolves an identity BEFORE the
+ * controller exists, so a fabricated model would be a lie on disk for a field
+ * nothing reads back.
+ */
+export function reserveSessionId(id, opts = {}) {
+    const path = (opts.pathFor ?? sessionPathFor)(id);
+    const payload = {
+        version: 1,
+        savedAt: Date.now(),
+        ...(opts.model ? { model: opts.model } : {}),
+        messages: [],
+        entries: [],
+    };
+    let fd;
+    try {
+        // THE DIRECTORY FIRST, and inside the same `try`: on a fresh machine
+        // `sessions/` does not exist yet, and a reservation that silently answered
+        // "name taken" because of a missing parent would send the caller into a
+        // pointless retry loop. A parent that is a FILE fails here, which is the
+        // honest answer.
+        mkdirSync(dirname(path), { recursive: true });
+        fd = openSync(path, 'wx');
+    }
+    catch {
+        // EEXIST is the ordinary answer to "someone already holds this name", and a
+        // missing directory is the ordinary answer on a fresh machine. Both mean
+        // "this id is not available", which is all the caller can act on.
+        return false;
+    }
+    try {
+        writeSync(fd, `${JSON.stringify(payload, null, 2)}\n`);
+    }
+    catch {
+        // A half-written placeholder is exactly the unreadable file D-23 exists to
+        // rule out, so the failure is undone rather than left behind.
+        closeSync(fd);
+        unlinkQuietly(path);
+        return false;
+    }
+    // Closed IMMEDIATELY: an open handle keeps Windows from replacing the file
+    // when the first checkpoint lands (the same reason `store.ts` closes its lock
+    // handle at once).
+    closeSync(fd);
+    return true;
+}
+/** Best effort: a cleanup failure must not turn "id unavailable" into a throw. */
+function unlinkQuietly(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Nothing to clean up, or someone else already did.
+    }
+}

package/dist/session/limits.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Structural bounds for session identity and the session checkpoint
+ * (tui-session-id-resume §3.13).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * STRUCTURE, NOT POLICY: these are the shapes an id and a checkpoint can
+ * physically take, so they live in the subsystem's own `limits.ts` like every
+ * other subsystem's do (CLAUDE.md: "`limits.ts` is structural,
+ * `config/schema.ts` is policy"). Nothing here is user-tunable (D-19): a
+ * "show an id but never write it" switch would manufacture the one state this
+ * feature must not have - an id a user can copy and cannot use.
+ */
+export declare const SESSION_ID_LIMITS: {
+    /** 6 characters of `SESSION_ID_ALPHABET`: 31^6 is about 8.9e8 ids. */
+    readonly idLength: 6;
+    /** The branch suffix, `-` plus this many characters. */
+    readonly suffixLength: 4;
+    /** The upper bound `SESSION_ID_RE` already imposes (`store.ts:50`). */
+    readonly maxIdLength: 64;
+    /** `maxIdLength - 1 - suffixLength` = 64 - 1 - 4. */
+    readonly maxRootLength: 59;
+    /** `wx` reservation attempts before a fresh id is minted instead. */
+    readonly reserveAttempts: 5;
+};
+export declare const SESSION_CHECKPOINT_LIMITS: {
+    /** The window several `agent_end` events are merged into (T-11b). */
+    readonly debounceMs: 750;
+    /** Floor between two writes, so a burst cannot land twice in one turn. */
+    readonly minWriteIntervalMs: 250;
+    /** `renameSync` retries when Windows refuses to replace an open file (D-4). */
+    readonly renameAttempts: 3;
+    /** Gap between those retries, waited synchronously (`Atomics.wait`). */
+    readonly renameRetryMs: 20;
+    /** Consecutive failures before the log record is raised from warn to error. */
+    readonly loudFailureStreak: 3;
+};
+/**
+ * Structural bounds for branching a session into a NEW terminal window
+ * (tui-branch-terminal-shortcut 5.3).
+ *
+ * WHY THESE LIVE HERE (R-12): this file's header says STRUCTURE, NOT POLICY, and
+ * `cooldownMs` is a timing policy. The precedent is already in this file -
+ * `SESSION_CHECKPOINT_LIMITS.debounceMs` / `minWriteIntervalMs` are timing
+ * policies of exactly the same kind. D-17 keeps every one of these out of
+ * `config/schema.ts`, so none of them is user-tunable.
+ *
+ * EVERY ENTRY NEEDS AN ENFORCEMENT POINT (R-7): a declared limit nobody checks is
+ * worse than no limit, because it makes a review believe the case was handled.
+ * `cooldownMs` is read in `branch-launch.ts` steps 1-2, `titleMaxCells` by
+ * `truncateTitle()` in step 7, `spawnProbeMs` by the `trySpawn` timer,
+ * `maxCommandLineCells` in step 4.5 BEFORE any spawn, and `maxRungs` as the
+ * bound of the rung loop in step 8.
+ */
+export declare const BRANCH_TERMINAL_LIMITS: {
+    /** Minimum gap between two successful opens (D-10). FAILURES DO NOT CONSUME IT. */
+    readonly cooldownMs: 2000;
+    /** Max cells of the new window title (`aragon ` + id; an id can be 64 long). */
+    readonly titleMaxCells: 60;
+    /** How long to wait for the `'spawn'` event; a timeout counts as success. */
+    readonly spawnProbeMs: 1500;
+    /** Hard cap on one command line (base64 included); over it we refuse (step 4.5). */
+    readonly maxCommandLineCells: 8000;
+    /** How many rungs to try (the POSIX candidate table can be long; 3 covers reality). */
+    readonly maxRungs: 3;
+};

package/dist/session/limits.js

@@ -0,0 +1,66 @@
+/**
+ * Structural bounds for session identity and the session checkpoint
+ * (tui-session-id-resume §3.13).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * STRUCTURE, NOT POLICY: these are the shapes an id and a checkpoint can
+ * physically take, so they live in the subsystem's own `limits.ts` like every
+ * other subsystem's do (CLAUDE.md: "`limits.ts` is structural,
+ * `config/schema.ts` is policy"). Nothing here is user-tunable (D-19): a
+ * "show an id but never write it" switch would manufacture the one state this
+ * feature must not have - an id a user can copy and cannot use.
+ */
+export const SESSION_ID_LIMITS = {
+    /** 6 characters of `SESSION_ID_ALPHABET`: 31^6 is about 8.9e8 ids. */
+    idLength: 6,
+    /** The branch suffix, `-` plus this many characters. */
+    suffixLength: 4,
+    /** The upper bound `SESSION_ID_RE` already imposes (`store.ts:50`). */
+    maxIdLength: 64,
+    /** `maxIdLength - 1 - suffixLength` = 64 - 1 - 4. */
+    maxRootLength: 59,
+    /** `wx` reservation attempts before a fresh id is minted instead. */
+    reserveAttempts: 5,
+};
+export const SESSION_CHECKPOINT_LIMITS = {
+    /** The window several `agent_end` events are merged into (T-11b). */
+    debounceMs: 750,
+    /** Floor between two writes, so a burst cannot land twice in one turn. */
+    minWriteIntervalMs: 250,
+    /** `renameSync` retries when Windows refuses to replace an open file (D-4). */
+    renameAttempts: 3,
+    /** Gap between those retries, waited synchronously (`Atomics.wait`). */
+    renameRetryMs: 20,
+    /** Consecutive failures before the log record is raised from warn to error. */
+    loudFailureStreak: 3,
+};
+/**
+ * Structural bounds for branching a session into a NEW terminal window
+ * (tui-branch-terminal-shortcut 5.3).
+ *
+ * WHY THESE LIVE HERE (R-12): this file's header says STRUCTURE, NOT POLICY, and
+ * `cooldownMs` is a timing policy. The precedent is already in this file -
+ * `SESSION_CHECKPOINT_LIMITS.debounceMs` / `minWriteIntervalMs` are timing
+ * policies of exactly the same kind. D-17 keeps every one of these out of
+ * `config/schema.ts`, so none of them is user-tunable.
+ *
+ * EVERY ENTRY NEEDS AN ENFORCEMENT POINT (R-7): a declared limit nobody checks is
+ * worse than no limit, because it makes a review believe the case was handled.
+ * `cooldownMs` is read in `branch-launch.ts` steps 1-2, `titleMaxCells` by
+ * `truncateTitle()` in step 7, `spawnProbeMs` by the `trySpawn` timer,
+ * `maxCommandLineCells` in step 4.5 BEFORE any spawn, and `maxRungs` as the
+ * bound of the rung loop in step 8.
+ */
+export const BRANCH_TERMINAL_LIMITS = {
+    /** Minimum gap between two successful opens (D-10). FAILURES DO NOT CONSUME IT. */
+    cooldownMs: 2_000,
+    /** Max cells of the new window title (`aragon ` + id; an id can be 64 long). */
+    titleMaxCells: 60,
+    /** How long to wait for the `'spawn'` event; a timeout counts as success. */
+    spawnProbeMs: 1_500,
+    /** Hard cap on one command line (base64 included); over it we refuse (step 4.5). */
+    maxCommandLineCells: 8_000,
+    /** How many rungs to try (the POSIX candidate table can be long; 3 covers reality). */
+    maxRungs: 3,
+};