@aragon-agent/cli 0.6.25 → 0.6.27

package/dist/session/checkpoint.js

@@ -0,0 +1,512 @@
+/**
+ * Session checkpoint writer (tui-session-id-resume §3.4 / D-2 / D-3 / D-4 /
+ * D-21 / D-22 / D-23).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THIS MODULE EXISTS AT ALL: a TUI conversation lives in memory
+ * (`agent.state.messages`). Another terminal can only continue it if the process
+ * has put it on disk, and the only serializer that exists (`saveSession`) is
+ * written for explicit exports. So this is the one owner of three properties an
+ * export never needed:
+ *
+ *   1. THE FILE ON DISK IS ALWAYS SENDABLE (D-3 / I-4). A checkpoint taken
+ *      mid-tool would leave an assistant `tool_call` with no `tool_result`, and
+ *      the next request of the branch that resumes it is an HTTP 400 - the very
+ *      first thing `--resume` is for.
+ *   2. THE REPLACEMENT IS ATOMIC (D-4). This is the repository's first "a writer
+ *      and a reader coexist" session file: the parent TUI writes while another
+ *      terminal reads. A truncated read says "corrupt session", and one false
+ *      report is enough for a user to stop trusting the feature.
+ *   3. NOTHING LIVE SURVIVES INTO THE FILE (D-22 / I-11). A `running` tool card
+ *      that never settles keeps `ToolCard` spinning and keeps `Transcript`'s
+ *      MONOTONIC settled boundary from ever moving past it, so every frame
+ *      re-renders the tail. The settlement happens on the WRITE COPY, not on the
+ *      load path, because `live-session.test.ts` pins the `/save` decision that
+ *      a reloaded card keeps its status - and `/save` is an explicit export made
+ *      with the user watching, while a checkpoint is not.
+ *
+ * NOTHING HERE MAY INTERRUPT A CONVERSATION (I-8): every filesystem failure is
+ * swallowed, logged, and reported as a value.
+ */
+import { renameSync, statSync, unlinkSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { validateHistory } from '@aragon-agent/core';
+import { getSessionsDir } from '../config/app-paths.js';
+import { getLogger } from '../logging/logger.js';
+import { SESSION_CHECKPOINT_LIMITS } from './limits.js';
+import { saveSession } from './persist.js';
+import { tryAcquireSessionLock } from './store.js';
+/** The literal text a repaired `tool_result` carries. Read by the MODEL next turn. */
+const INTERRUPTED_TOOL_RESULT = 'interrupted before completion';
+/** The literal `preview` a settled tool card carries. Rendered in the transcript. */
+const INTERRUPTED_TOOL_PREVIEW = 'interrupted (session checkpoint)';
+/**
+ * Repair every `tool_call` that never received its `tool_result` (D-3).
+ *
+ * ON A COPY, AND THAT IS THE POINT (I-2). The live history belongs to the
+ * engine; a host that edited it would change what the next request sends. Each
+ * dangling call gets an `isError` result carrying one fixed sentence, and the
+ * caller re-runs `validateHistory` afterwards: a repair that is still not
+ * sendable means the file must not be written.
+ */
+export function closeDanglingToolCalls(messages) {
+    const open = new Set();
+    for (const message of messages) {
+        if (message.role === 'assistant') {
+            for (const block of message.content) {
+                if (block.type === 'tool_call')
+                    open.add(block.toolCallId);
+            }
+        }
+        else if (message.role === 'tool_result') {
+            open.delete(message.toolCallId);
+        }
+    }
+    if (open.size === 0)
+        return { messages: [...messages], repaired: 0 };
+    const patched = [...messages];
+    for (const toolCallId of open) {
+        patched.push({
+            role: 'tool_result',
+            toolCallId,
+            isError: true,
+            content: INTERRUPTED_TOOL_RESULT,
+        });
+    }
+    return { messages: patched, repaired: open.size };
+}
+/**
+ * Settle every `running` tool card on a COPY (D-22 / I-11).
+ *
+ * `error` rather than `done`: the command did not finish, and a card that said
+ * otherwise would claim a result nobody saw. The live tail is cleared for the
+ * same reason `stripLiveToolOutput` clears it - it describes a process that died
+ * with the session - and `preview` names WHY, so a resumed card is not a silent
+ * lie. `pending` is left alone: `ToolCard` draws no spinner for it and
+ * `Transcript.nowSecFor` never re-clocks it, so it settles by itself.
+ */
+export function settleRunningToolCards(entries) {
+    let settled = 0;
+    const out = entries.map((entry) => {
+        if (entry.kind !== 'tool' || entry.status !== 'running')
+            return entry;
+        settled += 1;
+        return {
+            ...entry,
+            status: 'error',
+            isError: true,
+            preview: INTERRUPTED_TOOL_PREVIEW,
+            live: undefined,
+            liveSeq: undefined,
+            lastOutputAt: undefined,
+        };
+    });
+    return { entries: out, settled };
+}
+/** What may reach the disk: nothing at all, or a history the engine can resend. */
+export function isSendable(messages) {
+    if (messages.length === 0)
+        return true;
+    return validateHistory(messages).ok;
+}
+/**
+ * The checkpoint writer.
+ *
+ * ONE TIMER (I-10). Several `agent_end` events in a row - a todo follow-through
+ * restarts the run without the user typing - are merged into one write, and the
+ * timer is `unref`ed so a pending write can never hold the process open. Every
+ * exit path calls `flushSync`, which is idempotent so the three of them
+ * (`waitUntilExit().then()`, the signal hook and `process.on('exit')`) can
+ * coexist without writing three times.
+ */
+export class SessionCheckpointWriter {
+    deps;
+    pathFor;
+    lastFingerprint = null;
+    lastWriteAt = 0;
+    createdAt = null;
+    pinned;
+    failureStreak = 0;
+    pending = null;
+    unsubscribe = null;
+    exited = false;
+    /**
+     * Whether the LAST WRITE FILE still says `live: true`.
+     *
+     * The fingerprint deliberately does not include the reason for the write, so
+     * without this the exit flush would short-circuit as "nothing changed" and the
+     * file would keep `live: true` forever - which is the flag `sessions prune`
+     * reads as "a writer is still here" (T-10's sibling, and the reason
+     * `flushSync` must be able to write a file whose CONTENT is unchanged but whose
+     * METADATA is not).
+     */
+    lastWroteLive = false;
+    lastResult = null;
+    /**
+     * THIS PROCESS'S CLAIM ON THE FILE IT WRITES (S-7).
+     *
+     * Without it, `meta.live` is a flag nobody can verify: `sessions prune` reads
+     * the `.lock` payload to decide whether the writer is still alive, and the TUI
+     * never took one - so `prune --origin tui --yes` deleted the checkpoint of a
+     * session that was running at that moment. The lock is the same one `exec`
+     * uses to keep two writers off one file; a killed process leaves a dead pid
+     * behind and the existing staleness probe collects it.
+     */
+    lock = null;
+    lockedId = null;
+    constructor(deps) {
+        this.deps = deps;
+        this.pinned = deps.startPinned === true;
+        this.pathFor = deps.pathFor ?? ((id) => join(getSessionsDir(), `${id}.json`));
+    }
+    /**
+     * Write once now: after mount, so the id on screen is resumable immediately.
+     *
+     * THE `no-identity` ANSWER IS A TIMING ANSWER, NOT A PERMANENT ONE. `render()`
+     * returns before `App` has run its first effects, so the session slot can still
+     * be empty when this is called - and "the id on screen is not resumable until
+     * the first turn" is exactly the failure D-2 exists to prevent (a zero-turn
+     * session must already be a session). One deferred retry through the SAME
+     * single timer (I-10) turns that window into the write; if the view was already
+     * published, the first call succeeded and no timer is armed at all.
+     */
+    start() {
+        const result = this.write('running');
+        if (!result.ok && result.reason === 'no-identity')
+            this.schedule();
+        return result;
+    }
+    /** Subscribe to `agent_end`. The writer does not own the controller's lifetime. */
+    attach(subscribe) {
+        this.unsubscribe?.();
+        this.unsubscribe = subscribe(() => this.onAgentEnd());
+    }
+    /** Write now, optionally pinning (`/session pin`) or forcing past the short circuit. */
+    writeNow(opts = {}) {
+        if (opts.pin)
+            this.pinned = true;
+        return this.write('running', opts.force === true);
+    }
+    /**
+     * The exit-path write. Never throws, and after the first call it is a no-op
+     * (I-10): all three exit paths run on a normal quit.
+     */
+    flushSync(reason) {
+        if (this.exited)
+            return this.lastResult ?? noIdentity();
+        this.exited = true;
+        this.clearPending();
+        const result = this.write(reason);
+        // AFTER THE WRITE, BEFORE ANYONE ELSE LOOKS: the exit flush is the last
+        // thing this process does to this file, and a lock left behind would make
+        // `sessions prune` skip a session nobody is writing any more.
+        this.releaseLock();
+        return result;
+    }
+    dispose() {
+        this.clearPending();
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        this.releaseLock();
+    }
+    // -------------------------------------------------------------------------
+    // Scheduling
+    // -------------------------------------------------------------------------
+    onAgentEnd() {
+        if (this.fingerprint() === this.lastFingerprint)
+            return;
+        this.schedule();
+    }
+    /**
+     * Coalesce into one timer. `debounceMs` is the window; `minWriteIntervalMs`
+     * keeps two consecutive run boundaries - which arrive closer together than a
+     * human can type - from landing two full session writes back to back.
+     */
+    schedule() {
+        if (this.pending)
+            return;
+        const since = this.now() - this.lastWriteAt;
+        const wait = Math.max(SESSION_CHECKPOINT_LIMITS.debounceMs, SESSION_CHECKPOINT_LIMITS.minWriteIntervalMs - since);
+        const timer = setTimeout(() => {
+            this.pending = null;
+            this.write('running');
+        }, wait);
+        // A checkpoint must never be the reason `aragon` does not exit.
+        timer.unref?.();
+        this.pending = timer;
+    }
+    clearPending() {
+        if (!this.pending)
+            return;
+        clearTimeout(this.pending);
+        this.pending = null;
+    }
+    now() {
+        return (this.deps.now ?? Date.now)();
+    }
+    // -------------------------------------------------------------------------
+    // Writing
+    // -------------------------------------------------------------------------
+    /**
+     * The full write, in the one order that keeps the file honest: read, repair,
+     * gate, settle, write to a temporary file, replace.
+     *
+     * `force` is ONE switch with ONE effect (D-15 / I-7): it skips the fingerprint
+     * short circuit below. Everything after it - the dangling-call repair, the
+     * sendable gate, the settle pass, the atomic replace - runs unchanged, because a
+     * forced write still has to produce a file `loadSession()` can read back.
+     */
+    write(reason, force = false) {
+        const view = this.deps.readView();
+        if (!view) {
+            this.lastResult = noIdentity();
+            return this.lastResult;
+        }
+        const fingerprint = this.fingerprint();
+        const wantsLive = reason === 'running';
+        if (!force && fingerprint === this.lastFingerprint && wantsLive === this.lastWroteLive) {
+            // No change: not touching the file is the answer, not a failure (T-11).
+            // `force` skips exactly this branch and nothing else (D-15 / I-7).
+            this.lastResult = {
+                ok: true,
+                path: this.pathFor(view.id),
+                bytes: 0,
+                repaired: 0,
+                settled: 0,
+            };
+            return this.lastResult;
+        }
+        const history = this.deps.readHistory();
+        const repaired = closeDanglingToolCalls(history.messages);
+        if (!isSendable(repaired.messages)) {
+            // SKIPPED, NOT WRITTEN (D-3). An orphan `tool_result` cannot be repaired
+            // host-side - inventing the `tool_call` it belongs to would forge a call
+            // the engine never made - so the previous good file stays, and the reason
+            // goes to the log rather than into the user's conversation (I-8).
+            const verdict = validateHistory(repaired.messages);
+            const why = verdict.ok ? 'unknown' : verdict.reason;
+            getLogger().warn('session', 'checkpoint_not_sendable', { reason: why });
+            this.lastResult = { ok: false, reason: 'not-sendable', message: why };
+            return this.lastResult;
+        }
+        const settled = settleRunningToolCards(view.entries);
+        this.lastResult = this.persist({
+            view,
+            messages: repaired.messages,
+            ...(history.compactionIdentity ? { compactionIdentity: history.compactionIdentity } : {}),
+            entries: settled.entries,
+            repaired: repaired.repaired,
+            settled: settled.settled,
+            reason,
+        });
+        if (this.lastResult.ok) {
+            this.lastFingerprint = fingerprint;
+            this.lastWroteLive = wantsLive;
+            this.lastWriteAt = this.now();
+            this.failureStreak = 0;
+            if (this.createdAt === null)
+                this.createdAt = this.lastWriteAt;
+        }
+        return this.lastResult;
+    }
+    /** Serialize to `<id>.json.tmp-<uuid>` and rename over the real file (D-4). */
+    persist(input) {
+        this.holdLock(input.view.id);
+        const path = this.pathFor(input.view.id);
+        const tmp = `${path}.tmp-${randomUUID()}`;
+        const data = {
+            model: this.deps.readModel(),
+            messages: input.messages,
+            ...(input.compactionIdentity ? { compactionIdentity: input.compactionIdentity } : {}),
+            entries: input.entries,
+            todos: this.deps.readTodos(),
+            meta: this.buildMeta(input),
+        };
+        try {
+            saveSession(tmp, data);
+            const bytes = replaceFile(tmp, path, () => saveSession(path, data));
+            if (input.repaired > 0) {
+                getLogger().info('session', 'checkpoint_repaired_tool_calls', { repaired: input.repaired });
+            }
+            if (input.settled > 0) {
+                getLogger().info('session', 'checkpoint_settled_tool_cards', { settled: input.settled });
+            }
+            return {
+                ok: true,
+                path,
+                bytes,
+                repaired: input.repaired,
+                settled: input.settled,
+            };
+        }
+        catch (error) {
+            unlinkQuietly(tmp);
+            return this.fail(error);
+        }
+    }
+    /**
+     * `meta`, field by field (§6.1). Two of these are easy to get subtly wrong:
+     * `createdAt` is frozen at the first write (re-reading it every time would
+     * make the field a second `updatedAt`), and `turns` counts assistant messages
+     * IN THE FILE - a quantity a reader can verify, unlike "what this cost".
+     */
+    buildMeta(input) {
+        const model = this.deps.readModel();
+        const parentId = this.deps.readParentId?.();
+        return {
+            id: input.view.id,
+            cwd: this.deps.readCwd(),
+            createdAt: this.createdAt ?? this.now(),
+            updatedAt: this.now(),
+            turns: input.messages.filter((message) => message.role === 'assistant').length,
+            cli: this.deps.version,
+            provider: model.providerId,
+            model: model.modelId,
+            usage: {
+                inputTokens: input.view.usageTotal.inputTokens,
+                outputTokens: input.view.usageTotal.outputTokens,
+            },
+            origin: 'tui',
+            ...(this.pinned ? { pinned: true } : {}),
+            // Omitted by the exit flush: `live` means "a writer believes a process is
+            // still here", and both exit paths know better.
+            ...(input.reason === 'running' ? { live: true } : {}),
+            ...(parentId ? { branchOf: parentId } : {}),
+        };
+    }
+    /**
+     * Take, or move, this process's lock on the id being written (S-7).
+     *
+     * BEST EFFORT, AND NEVER FATAL: a checkpoint must not fail because someone
+     * else holds the lock - the write is atomic and the file is this id's own, so
+     * the worst case is a `live` flag that `prune` declines to trust.
+     */
+    holdLock(id) {
+        if (this.lockedId === id && this.lock)
+            return;
+        this.releaseLock();
+        this.lockedId = id;
+        try {
+            this.lock = (this.deps.lockFor ?? tryAcquireSessionLock)(id);
+        }
+        catch (error) {
+            // An id the lock refuses is an id that could not be a file name either; the
+            // write below reports that on its own terms.
+            this.lock = null;
+            getLogger().debug('session', 'checkpoint_lock_skipped', {
+                reason: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    releaseLock() {
+        this.lock?.release();
+        this.lock = null;
+        this.lockedId = null;
+    }
+    /** A failed write is a log line and a return value, never an exception (I-8). */
+    fail(error) {
+        this.failureStreak += 1;
+        const message = error instanceof Error ? error.message : String(error);
+        const data = { reason: message, streak: this.failureStreak };
+        if (this.failureStreak >= SESSION_CHECKPOINT_LIMITS.loudFailureStreak) {
+            getLogger().error('session', 'checkpoint_write_failed', data);
+        }
+        else {
+            getLogger().warn('session', 'checkpoint_write_failed', data);
+        }
+        return { ok: false, reason: 'write-failed', message };
+    }
+    /**
+     * A cheap content fingerprint: identity, message count, last message shape,
+     * entry count, last entry id, todo count and the pin flag.
+     *
+     * SHORT AND STRUCTURAL ON PURPOSE. Hashing the whole conversation would cost
+     * as much as writing it (K-1), and the question this answers is only "did
+     * anything settle since the last write".
+     */
+    fingerprint() {
+        const view = this.deps.readView();
+        if (!view)
+            return 'none';
+        const { messages } = this.deps.readHistory();
+        const last = messages[messages.length - 1];
+        const lastShape = last === undefined
+            ? '-'
+            : last.role === 'assistant'
+                ? `a:${last.stopReason ?? '-'}:${last.content.length}`
+                : last.role === 'tool_result'
+                    ? `t:${last.toolCallId}`
+                    : 'u';
+        const lastEntry = view.entries[view.entries.length - 1]?.id ?? '-';
+        return [
+            view.id,
+            messages.length,
+            lastShape,
+            view.entries.length,
+            lastEntry,
+            this.deps.readTodos().length,
+            this.pinned ? 'pin' : '-',
+        ].join('|');
+    }
+}
+function noIdentity() {
+    return {
+        ok: false,
+        reason: 'no-identity',
+        message: 'This process has no session identity, so nothing was checkpointed.',
+    };
+}
+/**
+ * Replace `path` with `tmp`, retrying while Windows refuses (D-4 / K-2).
+ *
+ * `EPERM`/`EEXIST` here means a reader has the file open, which is the NORMAL
+ * case for this feature rather than an error. Three short synchronous waits
+ * cover a reader finishing a read; if all of them fail, `degrade()` writes the
+ * payload in place and says so in the log - a checkpoint that records its own
+ * degradation beats a conversation that was never saved at all.
+ */
+function replaceFile(tmp, path, degrade) {
+    let lastError;
+    for (let attempt = 0; attempt < SESSION_CHECKPOINT_LIMITS.renameAttempts; attempt += 1) {
+        try {
+            renameSync(tmp, path);
+            return sizeOf(path);
+        }
+        catch (error) {
+            lastError = error;
+            sleepSync(SESSION_CHECKPOINT_LIMITS.renameRetryMs);
+        }
+    }
+    getLogger().warn('session', 'checkpoint_write_degraded', {
+        reason: 'rename-failed',
+        error: lastError instanceof Error ? lastError.message : String(lastError),
+    });
+    degrade();
+    unlinkQuietly(tmp);
+    return sizeOf(path);
+}
+/** The only synchronous sleep available without a native dependency. */
+function sleepSync(ms) {
+    const cell = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(cell, 0, 0, ms);
+}
+function sizeOf(path) {
+    try {
+        // Measured AFTER the rename, so the number reported describes the file a
+        // reader would find rather than the buffer that was written.
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function unlinkQuietly(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Already gone, or a handle still open. Neither is worth failing a run for.
+    }
+}

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;