@aragon-agent/cli 0.6.24 → 0.6.26

package/dist/session/persist.d.ts

@@ -18,8 +18,17 @@ import { type CompactionIdentity } from '../compaction/memory-identity.js';
  * 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.
+ * saved by hand.
+ *
+ * THE TUI NOW WRITES `meta`, AND THE RE-EXAMINATION THAT WARNING DEMANDED IS
+ * DONE (tui-session-id-resume 3.7 / R-7). Two axes were hiding in the one
+ * `managed` flag: "may a maintenance command see this row" (still `meta.id`) and
+ * "which writer produced it" (`origin`). `prune` now defaults to
+ * `origin === 'exec'`, so it behaves EXACTLY as it did before this feature on
+ * every file that existed before it; `--all` still only means "also consider
+ * files with no metadata at all" and can no longer reach a TUI checkpoint;
+ * `pinned` is a permanent opt-out and `live` plus a live owner pid is a
+ * temporary one. Four fields, four different jobs - none derivable from another.
  */
 export interface SessionMeta {
     id: string;
@@ -36,6 +45,20 @@ export interface SessionMeta {
         inputTokens: number;
         outputTokens: number;
     };
+    /**
+     * Who wrote this file. Absent (every pre-feature file) reads as 'exec'.
+     *
+     * OPTIONAL AND ADDITIVE, so SESSION_VERSION stays 1: validate-session.ts does
+     * not shape-check `meta` at all, so an older build reads a newer file and a
+     * newer build reads an older one without a migration.
+     */
+    origin?: 'exec' | 'tui';
+    /** `--save <id>` / `/session pin`: `sessions prune` never deletes it. */
+    pinned?: true;
+    /** The writer was alive at this write; omitted by the exit flush. */
+    live?: true;
+    /** The id this session branched from (D-5); absent for a fresh or named one. */
+    branchOf?: string;
 }
 export interface SavedSession {
     version: number;
@@ -53,13 +76,15 @@ export interface SavedSession {
      */
     todos?: TodoItem[];
     /**
-     * Written only by `aragon exec` (cli-integration-surface §5.2 / D-10).
+     * Written by `aragon exec` (cli-integration-surface §5.2 / D-10) AND by the
+     * TUI's session checkpoint (tui-session-id-resume §6.1).
      *
      * `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. Boundary validation preserves it without changing its shape.
-     * A TUI `/save` file simply has no `meta`, which is exactly how
-     * `sessions list` tells the two apart.
+     * A TUI `/save` EXPORT still has no `meta` at all, which is what keeps a
+     * hand-made file out of the maintenance commands' scope; a TUI CHECKPOINT has
+     * one, and is told apart from an exec file by `meta.origin`.
      */
     meta?: SessionMeta;
 }

package/dist/session/startup-session.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Startup-time session resolution: `--resume <id|path>` and `--save <id>`
+ * (tui-session-id-resume §3.8 / D-5..D-9 / D-20 / D-23).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * ONE RESOLUTION, TWO CALLERS. The TUI (`runInteractive`) and the headless
+ * one-shot (`runOneShot`) both come through here, and the in-TUI `/resume`
+ * command shares `applyRestoredSession` with them, because two copies of "adopt
+ * a saved conversation" is how `/clear` and `/reset` drifted apart once already.
+ *
+ * THIS MODULE DOES NO I/O BEYOND READING THE FILE AND CLAIMING THE NEW ID. It
+ * builds no controller and renders nothing, so every rule below is testable as a
+ * pure function: a caller gets either an identity plus an `apply` thunk, or one
+ * message and exit code 2.
+ *
+ * THE PARENT IS NEVER WRITTEN (I-3). The id comes from the file NAME, the new id
+ * is always derived, and the only write this module performs is the `wx` claim
+ * of that new id - which is a different file by construction.
+ */
+import type { Message } from '@aragon-agent/core';
+import type { Entry } from '../agent/reducer.js';
+import type { TodoItem } from '../todo/types.js';
+import type { CompactionIdentity } from '../compaction/memory-identity.js';
+import { type SavedSession } from './persist.js';
+/** Who this process is, as the rest of the CLI sees it. */
+export interface SessionIdentity {
+    id: string;
+    kind: 'fresh' | 'named' | 'branch';
+    /** The id this one branched from; absent unless `kind === 'branch'`. */
+    parentId?: string;
+    /** `--save` / `/session pin`: `sessions prune` will not delete it. */
+    pinned?: boolean;
+}
+export interface StartupSessionInput {
+    /** `--resume <id|path>` - both spellings are legal (D-5 / R-8). */
+    resume?: string;
+    /** `--save <id>` - an ID, never a path (D-6). */
+    saveAs?: string;
+    cwd: string;
+    /** True when the user named `--model` / `--provider` explicitly (D-9). */
+    explicitModel?: boolean;
+}
+/**
+ * The minimum controller surface the restore needs.
+ *
+ * THREE METHODS, and `getConfig` is deliberately not one of them: the three
+ * calls below need nothing else, and a wider port only makes the startup path
+ * look like it knows more about the controller than it does.
+ */
+export interface SessionRestorePort {
+    replaceMessages(messages: Message[], identity?: CompactionIdentity): void;
+    restoreTodos(items: TodoItem[]): void;
+    setModel(providerId: string, modelId: string, baseUrl?: string): void;
+}
+export type StartupSessionResolution = {
+    ok: true;
+    identity: SessionIdentity;
+    initialEntries: Entry[];
+    notice?: string;
+    /** The file this session was branched from, if any. */
+    saved?: SavedSession;
+    apply(port: SessionRestorePort): void;
+} | {
+    ok: false;
+    exitCode: 2;
+    message: string;
+};
+/**
+ * Adopt a saved conversation. THE ONLY IMPLEMENTATION of the three calls
+ * `/resume` makes; the slash command and both startup paths call it.
+ *
+ * `skipModel` exists because an explicit `--model` / `--provider` on this run
+ * outranks the model recorded in the file: a user who says which model they want
+ * has said it more recently than the file did.
+ *
+ * `clearAllQueues()` and the `restoreEntries` dispatch are NOT here and belong at
+ * the call sites: the first is a no-op on the startup path (there are no queues
+ * yet) and indispensable inside a live TUI, and the second is a VIEW action with
+ * no controller to attach it to - the startup path seeds the reducer instead.
+ */
+export declare function applyRestoredSession(port: SessionRestorePort, saved: SavedSession, opts?: {
+    skipModel?: boolean;
+}): void;
+/**
+ * Work out which session this process is, and what it starts from.
+ *
+ * FAILURE IS EXIT 2 WITH ONE COPYABLE SENTENCE, and it happens BEFORE any write
+ * (the only write is the id claim, and it is last). Sources: a `--save` value
+ * that is not an id (D-6), a `--save` id that is already taken (D-6), a `--save`
+ * naming the id being resumed (D-7), and a `--resume` that is missing or
+ * unreadable (D-8).
+ */
+export declare function resolveStartupSession(input: StartupSessionInput): StartupSessionResolution;
+/**
+ * Move to a derived id after a `/resume` inside the TUI (D-15 / R-9).
+ *
+ * THE ROTATION IS NOT COSMETIC. `/resume` adopts another conversation, so the
+ * next checkpoint would otherwise write THAT conversation into THIS id's file -
+ * silently destroying the disk record the user was building. The id therefore
+ * changes with the content, exactly as it does on a startup branch, and the
+ * caller resets the spend in the same breath (D-10).
+ *
+ * The parent id comes from the FILE NAME, never from `meta.id` (D-5): a file's
+ * contents are input.
+ */
+export declare function rotateToChildOf(loadedPath: string): SessionIdentity | undefined;

package/dist/session/startup-session.js

@@ -0,0 +1,315 @@
+/**
+ * Startup-time session resolution: `--resume <id|path>` and `--save <id>`
+ * (tui-session-id-resume §3.8 / D-5..D-9 / D-20 / D-23).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * ONE RESOLUTION, TWO CALLERS. The TUI (`runInteractive`) and the headless
+ * one-shot (`runOneShot`) both come through here, and the in-TUI `/resume`
+ * command shares `applyRestoredSession` with them, because two copies of "adopt
+ * a saved conversation" is how `/clear` and `/reset` drifted apart once already.
+ *
+ * THIS MODULE DOES NO I/O BEYOND READING THE FILE AND CLAIMING THE NEW ID. It
+ * builds no controller and renders nothing, so every rule below is testable as a
+ * pure function: a caller gets either an identity plus an `apply` thunk, or one
+ * message and exit code 2.
+ *
+ * THE PARENT IS NEVER WRITTEN (I-3). The id comes from the file NAME, the new id
+ * is always derived, and the only write this module performs is the `wx` claim
+ * of that new id - which is a different file by construction.
+ */
+import { existsSync } from 'node:fs';
+import { getSessionsDir } from '../config/app-paths.js';
+import { branchSessionId, createSessionId, derivedChildId, isGeneratedSessionId, reserveSessionId, } from './identity.js';
+import { SESSION_ID_LIMITS } from './limits.js';
+import { loadSession } from './persist.js';
+import { basenameId, isValidSessionId, looksLikeSessionPath, resolveSessionRef, sessionPathFor, } from './store.js';
+/**
+ * Adopt a saved conversation. THE ONLY IMPLEMENTATION of the three calls
+ * `/resume` makes; the slash command and both startup paths call it.
+ *
+ * `skipModel` exists because an explicit `--model` / `--provider` on this run
+ * outranks the model recorded in the file: a user who says which model they want
+ * has said it more recently than the file did.
+ *
+ * `clearAllQueues()` and the `restoreEntries` dispatch are NOT here and belong at
+ * the call sites: the first is a no-op on the startup path (there are no queues
+ * yet) and indispensable inside a live TUI, and the second is a VIEW action with
+ * no controller to attach it to - the startup path seeds the reducer instead.
+ */
+export function applyRestoredSession(port, saved, opts = {}) {
+    port.replaceMessages(saved.messages, saved.compactionIdentity);
+    // Absence clears the previous conversation's list, including old files.
+    port.restoreTodos(saved.todos ?? []);
+    if (!opts.skipModel && saved.model?.providerId && saved.model?.modelId) {
+        port.setModel(saved.model.providerId, saved.model.modelId, saved.model.baseUrl);
+    }
+}
+/**
+ * Work out which session this process is, and what it starts from.
+ *
+ * FAILURE IS EXIT 2 WITH ONE COPYABLE SENTENCE, and it happens BEFORE any write
+ * (the only write is the id claim, and it is last). Sources: a `--save` value
+ * that is not an id (D-6), a `--save` id that is already taken (D-6), a `--save`
+ * naming the id being resumed (D-7), and a `--resume` that is missing or
+ * unreadable (D-8).
+ */
+export function resolveStartupSession(input) {
+    const rawSaveAs = input.saveAs?.trim();
+    if (rawSaveAs !== undefined && rawSaveAs.length > 0 && !isValidSessionId(rawSaveAs)) {
+        return invalidSaveId(rawSaveAs);
+    }
+    const saveAs = rawSaveAs !== undefined && rawSaveAs.length > 0 ? rawSaveAs : undefined;
+    const resume = input.resume?.trim();
+    if (resume !== undefined && resume.length > 0)
+        return resolveBranch(input, resume, saveAs);
+    return resolveFresh(saveAs);
+}
+/** A brand new session: optionally named by `--save`, otherwise auto-minted. */
+function resolveFresh(saveAs) {
+    if (saveAs !== undefined) {
+        const fate = tryReserve(saveAs);
+        if (fate === 'taken')
+            return alreadyExists(saveAs);
+        if (fate === 'unwritable')
+            return unwritable(saveAs);
+        return {
+            ok: true,
+            identity: { id: saveAs, kind: 'named', pinned: true },
+            initialEntries: [],
+            notice: `Session ${saveAs} (pinned). Resume it from any terminal: aragon --resume ${saveAs}`,
+            apply: () => { },
+        };
+    }
+    // A collision is not a failure for an auto-minted id: another process took the
+    // name in the last few milliseconds, so minting again is the whole fix.
+    for (let attempt = 0; attempt < SESSION_ID_LIMITS.reserveAttempts; attempt += 1) {
+        const id = createSessionId();
+        const fate = tryReserve(id);
+        // Retrying cannot repair a directory that refuses writes, and burning the
+        // remaining attempts only delays the same answer.
+        if (fate === 'unwritable')
+            return unwritable(id);
+        if (fate === 'ok') {
+            return { ok: true, identity: { id, kind: 'fresh' }, initialEntries: [], apply: () => { } };
+        }
+    }
+    return {
+        ok: false,
+        exitCode: 2,
+        message: `Could not allocate a session id after ${SESSION_ID_LIMITS.reserveAttempts} attempts. ` +
+            `Try: aragon sessions prune --origin tui --yes  (sessions live in ${getSessionsDir()}).`,
+    };
+}
+/** `--resume`: read the parent, derive a new id, claim it (D-5 / D-8). */
+function resolveBranch(input, reference, saveAs) {
+    const path = resolveSessionRef(reference, input.cwd);
+    if (path === null)
+        return notFound(reference);
+    let saved;
+    try {
+        saved = loadSession(path);
+    }
+    catch (error) {
+        // A file that exists but cannot be read is NOT the same absence: this third
+        // message exists because a raw stack trace here is a user staring at a
+        // puzzle, and the only way out of it is deleting the file (D-8 / R-3).
+        const id = basenameId(path);
+        const reason = error instanceof Error ? error.message : String(error);
+        const next = isValidSessionId(id)
+            ? `Delete it with: aragon sessions rm ${id} --yes`
+            : 'Delete the file, or resume another one.';
+        return {
+            ok: false,
+            exitCode: 2,
+            message: `Session "${id}" exists but could not be read (${reason}). ${next}`,
+        };
+    }
+    // D-7 compares IDS, not the text the user typed: `--resume ./x/a4k2m9.json
+    // --save a4k2m9` is the same session (D-5 derives the parent from the file
+    // NAME), so the path spelling must be refused identically.
+    const loadedId = basenameId(path);
+    if (saveAs !== undefined && saveAs === loadedId) {
+        return {
+            ok: false,
+            exitCode: 2,
+            message: `--save ${saveAs} names the session you are resuming. ` +
+                'Pick a different id to branch into.',
+        };
+    }
+    // LINEAGE ONLY EXISTS FOR A GENERATED NAME (D-5 / §5.1). A `/save` export, a
+    // `/clear` archive and a user-chosen name all land in this directory under
+    // names this CLI did not mint; recording one of those as `meta.branchOf` would
+    // write a parent that is not a session, and announcing it would claim a
+    // lineage that does not exist. `derivedChildId` already draws that line for the
+    // NEW id; the recorded parent must be drawn on the same line.
+    const parentId = isGeneratedSessionId(loadedId) ? loadedId : undefined;
+    const derived = saveAs ?? derivedChildId(path);
+    const claimed = claimBranchId(derived, {
+        named: saveAs !== undefined,
+        // A retry must keep the branch SHAPE: losing the `-xxxx` suffix on a
+        // collision would drop the one thing on disk that says where this came from.
+        mint: () => (parentId ? branchSessionId(parentId) : createSessionId()),
+    });
+    if (!claimed.ok)
+        return claimed.resolution;
+    const identity = {
+        id: claimed.id,
+        // Not a "branch" when the file it came from has no id of ours to name, and
+        // not a "branch" that the `-p` notice should announce.
+        kind: parentId !== undefined ? 'branch' : saveAs !== undefined ? 'named' : 'fresh',
+        ...(parentId !== undefined ? { parentId } : {}),
+        // Written only when TRUE, like `SessionMeta.pinned`: the field means "the
+        // user asked for this name", and `pinned: false` would be a second spelling
+        // of the same absence.
+        ...(saveAs !== undefined ? { pinned: true } : {}),
+    };
+    const notice = parentId !== undefined
+        ? `Resumed ${parentId} as a new branch: session ${claimed.id}. ` +
+            'The session you branched from is unchanged.'
+        : saveAs !== undefined
+            ? `Session ${claimed.id} (pinned). ` +
+                `Resume it from any terminal: aragon --resume ${claimed.id}`
+            : undefined;
+    return {
+        ok: true,
+        identity,
+        initialEntries: saved.entries,
+        ...(notice === undefined ? {} : { notice }),
+        saved,
+        apply: (port) => applyRestoredSession(port, saved, { skipModel: input.explicitModel === true }),
+    };
+}
+/**
+ * Claim the branch id, retrying only when it was auto-derived.
+ *
+ * A `--save` name that is taken is the user's decision to lose, so it is refused
+ * (D-6); an auto-derived suffix colliding means nothing to anyone, so it is
+ * re-minted - WITH THE SAME ROOT (`mint`), because the suffix is the disposable
+ * half of a branch id and the root is the part that carries the lineage.
+ */
+function claimBranchId(derived, opts) {
+    if (derived !== null) {
+        const fate = tryReserve(derived);
+        if (fate === 'ok')
+            return { ok: true, id: derived };
+        if (fate === 'unwritable')
+            return { ok: false, resolution: unwritable(derived) };
+        if (opts.named)
+            return { ok: false, resolution: alreadyExists(derived) };
+    }
+    for (let attempt = 0; attempt < SESSION_ID_LIMITS.reserveAttempts; attempt += 1) {
+        const id = opts.mint();
+        const fate = tryReserve(id);
+        if (fate === 'ok')
+            return { ok: true, id };
+        if (fate === 'unwritable')
+            return { ok: false, resolution: unwritable(id) };
+    }
+    return {
+        ok: false,
+        resolution: {
+            ok: false,
+            exitCode: 2,
+            message: `Could not allocate a branch id after ${SESSION_ID_LIMITS.reserveAttempts} attempts.`,
+        },
+    };
+}
+/**
+ * `reserveSessionId` answers "did I get this name"; the CALLER needs to know
+ * "who refused, and what should I tell the user".
+ *
+ * A read-only (or full) session directory fails the reservation for every id
+ * exactly like a collision does, and reporting that as `Session "myfix" already
+ * exists` sends the user to `--resume myfix`, which then reports that nothing is
+ * there. One `existsSync` between the two is enough to tell "somebody holds this
+ * name" from "nothing can be written here at all".
+ */
+function tryReserve(id) {
+    if (reserveSessionId(id))
+        return 'ok';
+    return existsSync(sessionPathFor(id)) ? 'taken' : 'unwritable';
+}
+/**
+ * Move to a derived id after a `/resume` inside the TUI (D-15 / R-9).
+ *
+ * THE ROTATION IS NOT COSMETIC. `/resume` adopts another conversation, so the
+ * next checkpoint would otherwise write THAT conversation into THIS id's file -
+ * silently destroying the disk record the user was building. The id therefore
+ * changes with the content, exactly as it does on a startup branch, and the
+ * caller resets the spend in the same breath (D-10).
+ *
+ * The parent id comes from the FILE NAME, never from `meta.id` (D-5): a file's
+ * contents are input.
+ */
+export function rotateToChildOf(loadedPath) {
+    // Same lineage rule as a startup branch: a name this CLI did not mint has no
+    // id to record, so it records none (D-5 / §5.1).
+    const loadedId = basenameId(loadedPath);
+    const parentId = isGeneratedSessionId(loadedId) ? loadedId : undefined;
+    const claimed = claimBranchId(derivedChildId(loadedPath), {
+        named: false,
+        mint: () => (parentId ? branchSessionId(parentId) : createSessionId()),
+    });
+    if (!claimed.ok)
+        return undefined;
+    return {
+        id: claimed.id,
+        kind: parentId !== undefined ? 'branch' : 'fresh',
+        ...(parentId !== undefined ? { parentId } : {}),
+    };
+}
+function invalidSaveId(value) {
+    return {
+        ok: false,
+        exitCode: 2,
+        message: `Invalid session id "${value}". --save takes an id ` +
+            '(letters, digits, ".", "_", "-"), not a path. ' +
+            'Use /save inside the TUI to export to a file.',
+    };
+}
+function alreadyExists(id) {
+    return {
+        ok: false,
+        exitCode: 2,
+        message: `Session "${id}" already exists. ` +
+            `Use --resume ${id} to continue it as a new branch, or pick a new id.`,
+    };
+}
+/**
+ * The id was free but the file could not be created: a read-only or full
+ * directory. Naming the directory is the only actionable half of this sentence -
+ * "already exists" (the answer a bare `false` used to produce) would send the
+ * user to `--resume <id>`, which reports that nothing is there.
+ */
+function unwritable(id) {
+    return {
+        ok: false,
+        exitCode: 2,
+        message: `Could not create session "${id}" in ${getSessionsDir()} ` +
+            '(the directory is not writable).',
+    };
+}
+/**
+ * `--resume` found nothing. TWO SPELLINGS, TWO SENTENCES, because the next step
+ * differs: an id is looked up in a directory, a path is looked at directly.
+ */
+function notFound(reference) {
+    // THE SAME PREDICATE THE LOOKUP USED (D-5 / R-8), not a second copy of it: two
+    // copies would eventually disagree about one spelling and send the user to the
+    // wrong next step (`sessions list --all` for a path, or `sessions path` for an
+    // id).
+    if (looksLikeSessionPath(reference)) {
+        return {
+            ok: false,
+            exitCode: 2,
+            message: `No session file at "${reference}". Try: aragon sessions path`,
+        };
+    }
+    return {
+        ok: false,
+        exitCode: 2,
+        message: `No session "${reference}". Try: aragon sessions list --all  ` +
+            `(sessions live in ${getSessionsDir()}).`,
+    };
+}

package/dist/session/store.d.ts

@@ -41,6 +41,16 @@ export declare function isValidSessionId(id: string): boolean;
  * feature exists for.
  */
 export declare const SESSION_LOCK_TTL_MS = 600000;
+/**
+ * Who wrote a session file (tui-session-id-resume §3.7 / D-20).
+ *
+ * A SECOND, ORTHOGONAL AXIS from `managed`. `managed` answers "may a maintenance
+ * command see this row at all" (it means "the file carries `meta.id`"); `origin`
+ * answers "which writer produced it". TUI checkpoints are managed AND
+ * `origin: 'tui'`, which is exactly why `--all` must no longer be able to reach
+ * them: widening axis A must not widen axis B.
+ */
+export type SessionOrigin = 'exec' | 'tui';
 export interface SessionListEntry {
     id: string;
     path: string;
@@ -50,8 +60,14 @@ export interface SessionListEntry {
     turns: number;
     provider: string;
     model: string;
-    /** `true` when the file carries `meta.id`, i.e. `aragon exec` wrote it. */
+    /** `true` when the file carries `meta.id`, i.e. `aragon exec` or the TUI wrote it. */
     managed: boolean;
+    /** Who wrote it; absent/unknown metadata reads as `'exec'` (older files). */
+    origin?: SessionOrigin;
+    /** `--save <id>` or `/session pin`: `sessions prune` never deletes it. */
+    pinned?: boolean;
+    /** The writer considered itself live at its last write. */
+    live?: boolean;
 }
 export declare function sessionsDir(): string;
 export declare function sessionPathFor(id: string): string;
@@ -66,6 +82,19 @@ export declare function sessionPathFor(id: string): string;
  * prevent, arriving through the flag next to it. `meta.id` is no safer: it comes
  * out of a file, and files are inputs.
  *
+ * A TUI CHECKPOINT NEVER NAMES ITSELF (D-20 / R-1). This is the single line that
+ * keeps `aragon exec --resume <tui-id>` from OVERWRITING the parent checkpoint:
+ * before this check, a TUI file carrying `meta.id` made `exec` take that id,
+ * write its own result into `a4k2m9.json` and move the `--continue` pointer -
+ * silent, unrecoverable loss of the one conversation the user was still having,
+ * arriving through a directory the design had declared out of scope. The rule
+ * belongs HERE rather than in `exec/**` because every exec write-back path
+ * already funnels through this function, so one check covers all of them and
+ * `exec/**` stays untouched.
+ *
+ * The fallthrough is the "stranger file" branch that already existed below:
+ * mint a fresh id rather than build a path out of the leftovers.
+ *
  * The order is the one that keeps every legitimate resume landing where the user
  * expects: an exec-written session names itself, a TUI `/save` is named by its
  * file, and anything else gets a fresh id rather than a guess - reported back in
@@ -73,6 +102,15 @@ export declare function sessionPathFor(id: string): string;
  * wondering which session it just wrote.
  */
 export declare function resumedSessionId(path: string, saved: SavedSession): string;
+/**
+ * Whether a `--resume` value is meant as a PATH rather than an id.
+ *
+ * EXPORTED SO THE FAILURE MESSAGE CANNOT DISAGREE WITH THE LOOKUP: the startup
+ * path prints one sentence for "no such id" and another for "no such file", and
+ * a second copy of this predicate is a copy that can drift (`isAbsolute` was
+ * missing from exactly such a copy).
+ */
+export declare function looksLikeSessionPath(value: string): boolean;
 /** Read one file, or `null` for anything unreadable. NEVER THROWS. */
 export declare function readSessionFile(path: string): SavedSession | null;
 /**
@@ -100,6 +138,14 @@ export interface WriteSessionInput {
  */
 export declare function writeSession(input: WriteSessionInput): string;
 export declare function removeSession(id: string): boolean;
+/**
+ * The file name without its directory or `.json` suffix.
+ *
+ * Exported because session IDENTITY derives the parent of a branch from this
+ * value and NOT from `meta.id` (D-5): the contents of a file are input, so a
+ * hand-written `meta.id` must not be able to name where this process writes.
+ */
+export declare function basenameId(path: string): string;
 /**
  * Every session in the directory, newest first.
  *
@@ -114,7 +160,20 @@ export interface PruneOptions {
     olderThanDays?: number;
     dryRun?: boolean;
     all?: boolean;
+    /**
+     * Which WRITER's files this sweep may touch: `'exec'` (default), `'tui'`, or
+     * `'all'` (tui-session-id-resume §3.7 / R-7).
+     *
+     * A SECOND AXIS, NOT A THIRD CHOICE. `all` above widens "which rows exist"
+     * (files with no metadata too); this narrows "which writers are in scope".
+     * Keeping them separate is what makes `--all` mean, forever, exactly what its
+     * help text says - and never "also delete every TUI checkpoint", which is what
+     * a single merged axis produced when TUI files started carrying `meta`.
+     */
+    origin?: SessionOrigin | 'all';
     now?: () => number;
+    /** Injected for tests; defaults to `process.kill(pid, 0)` liveness probing. */
+    isProcessAlive?: (pid: number) => boolean;
 }
 /** `--dry-run` reports and deletes nothing; nothing is ever pruned automatically. */
 export declare function pruneSessions(opts?: PruneOptions): SessionListEntry[];