@aragon-agent/cli 0.6.25 → 0.6.27

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[];

package/dist/session/store.js

@@ -91,6 +91,19 @@ export function sessionPathFor(id) {
  * 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
@@ -98,6 +111,8 @@ export function sessionPathFor(id) {
  * wondering which session it just wrote.
  */
 export function resumedSessionId(path, saved) {
+    if (saved.meta?.origin === 'tui')
+        return randomUUID();
     const declared = saved.meta?.id;
     if (typeof declared === 'string' && isValidSessionId(declared))
         return declared;
@@ -106,6 +121,17 @@ export function resumedSessionId(path, saved) {
         return base;
     return randomUUID();
 }
+/**
+ * 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 function looksLikeSessionPath(value) {
+    return (isAbsolute(value) || value.includes('/') || value.includes('\\') || value.endsWith('.json'));
+}
 function ensureDir() {
     const dir = getSessionsDir();
     if (!existsSync(dir))
@@ -135,8 +161,7 @@ export function resolveSessionRef(idOrPath, cwd) {
     const value = idOrPath.trim();
     if (value.length === 0)
         return null;
-    const looksLikePath = isAbsolute(value) || value.includes('/') || value.includes('\\') || value.endsWith('.json');
-    const path = looksLikePath
+    const path = looksLikeSessionPath(value)
         ? resolve(cwd, value)
         : isValidSessionId(value)
             ? sessionPathFor(value)
@@ -199,9 +224,24 @@ function describe(path, session) {
         provider: meta?.provider ?? session.model?.providerId ?? '',
         model: meta?.model ?? session.model?.modelId ?? '',
         managed: typeof meta?.id === 'string' && meta.id.length > 0,
+        // UNTRUSTED INPUT, DEGRADED TO THE OLD BEHAVIOUR. `origin` is read out of a
+        // file, so an unknown or hostile value must not be able to make a TUI
+        // checkpoint look like an exec one (or the reverse); anything that is not
+        // exactly `'tui'` reads as `'exec'`, which is what every pre-feature file
+        // means.
+        origin: meta?.origin === 'tui' ? 'tui' : 'exec',
+        pinned: meta?.pinned === true,
+        live: meta?.live === true,
     };
 }
-function basenameId(path) {
+/**
+ * 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 function basenameId(path) {
     const name = path.replace(/\\/g, '/').split('/').pop() ?? path;
     return name.endsWith('.json') ? name.slice(0, -'.json'.length) : name;
 }
@@ -242,8 +282,12 @@ function safeReaddir(dir) {
 /** `--dry-run` reports and deletes nothing; nothing is ever pruned automatically. */
 export function pruneSessions(opts = {}) {
     const now = (opts.now ?? Date.now)();
+    const isAlive = opts.isProcessAlive ?? defaultIsProcessAlive;
     const cutoff = opts.olderThanDays === undefined ? now : now - opts.olderThanDays * 24 * 60 * 60 * 1000;
-    const doomed = listSessions({ ...(opts.all ? { all: true } : {}) }).filter((entry) => entry.updatedAt <= cutoff);
+    const doomed = listSessions({ ...(opts.all ? { all: true } : {}) }).filter((entry) => entry.updatedAt <= cutoff &&
+        isInPruneScope(entry, opts.origin ?? 'exec') &&
+        !entry.pinned &&
+        !isOwnedByALiveProcess(entry, isAlive));
     if (opts.dryRun)
         return doomed;
     for (const entry of doomed) {
@@ -257,6 +301,41 @@ export function pruneSessions(opts = {}) {
     }
     return doomed;
 }
+/**
+ * The origin half of the truth table. Files WITHOUT metadata are governed by
+ * `all` alone (they were already included or already excluded by the listing),
+ * so they pass here rather than being re-judged by a `meta` they do not have.
+ */
+function isInPruneScope(entry, origin) {
+    if (origin === 'all')
+        return true;
+    if (!entry.managed)
+        return true;
+    return (entry.origin ?? 'exec') === origin;
+}
+/**
+ * `live: true` PLUS A LIVE OWNER PID IS NEVER DELETED (§3.7 / T-33).
+ *
+ * The pid comes from the file's `.lock` payload, which is the only per-session
+ * process identity this directory carries and the same source
+ * `tryAcquireSessionLock` trusts. A `live: true` file with NO lock is deletable,
+ * and that is the honest answer rather than a gap: the flag says a writer
+ * believed itself live, not that one is alive now - a process killed in the
+ * night leaves the flag behind, and a protection that could never expire is a
+ * file nobody can ever clean up.
+ */
+function isOwnedByALiveProcess(entry, isAlive) {
+    if (!entry.live)
+        return false;
+    // THE FILE NAME, NOT `meta.id`: the lock is named after the file, and `meta.id`
+    // comes out of that file (I-12). Reading it here would probe the wrong lock for
+    // a file whose metadata disagrees with its name - and, since `join` normalises,
+    // a hostile id containing separators would read outside this directory.
+    const holder = readLock(join(getSessionsDir(), `${basenameId(entry.path)}.lock`));
+    if (!holder || holder.host !== hostname())
+        return false;
+    return isAlive(holder.pid);
+}
 // ---------------------------------------------------------------------------
 // `--continue`: the pointer, and the scan that makes it safe to keep
 // ---------------------------------------------------------------------------
@@ -299,16 +378,26 @@ export function latestSessionForCwd(cwd) {
     if (hinted && isValidSessionId(hinted.id)) {
         const path = sessionPathFor(hinted.id);
         const session = existsSync(path) ? readSessionFile(path) : null;
-        if (session?.meta && sameCwd(session.meta.cwd, cwd))
+        // BOTH BRANCHES EXCLUDE TUI CHECKPOINTS (tui-session-id-resume §3.7). The
+        // pointer branch is not defensive padding: `--continue` promises "the newest
+        // EXEC session", and TUI sessions are resumed by id. Today only
+        // `writeSession()` moves the pointer, so a TUI file cannot be named there -
+        // and that is precisely the kind of "nobody writes it today" assumption this
+        // repository has already paid for. One predicate, applied twice, is cheap.
+        if (session?.meta && originOf(session.meta) === 'exec' && sameCwd(session.meta.cwd, cwd)) {
             return describe(path, session);
+        }
     }
     const target = resolve(cwd);
     for (const entry of listSessions()) {
-        if (sameCwd(entry.cwd, target))
+        if (originOf(entry) === 'exec' && sameCwd(entry.cwd, target))
             return entry;
     }
     return null;
 }
+function originOf(value) {
+    return value.origin === 'tui' ? 'tui' : 'exec';
+}
 function sameCwd(a, b) {
     if (!a || !b)
         return false;

package/dist/ui/App.d.ts

@@ -8,10 +8,13 @@ import React from 'react';
 import type { ScrollbarBridge } from './scrollbar-controller.js';
 import type { AgentController } from '../agent/controller.js';
 import type { ConfirmRequest } from '../tools/index.js';
-import { type Overlay, type ToastLevel } from '../agent/reducer.js';
+import { type Entry, type Overlay, type ToastLevel } from '../agent/reducer.js';
 import type { UpdateBridge } from '../update/types.js';
 import type { MouseSource } from '../input/stdin-filter.js';
 import { type PasteBridge } from '../input/limits.js';
+import type { CheckpointResult } from '../session/checkpoint.js';
+import type { BranchCommandPort } from '../commands/branch-command.js';
+import type { SessionIdentity } from '../session/startup-session.js';
 import type { SelectionBridge } from './selection/selection-controller.js';
 import type { HumanInputBridge } from '../tools/human-input.js';
 export interface ConfirmBridge {
@@ -83,6 +86,55 @@ export interface AppProps {
      */
     pasteBridge?: PasteBridge;
     terminal?: TerminalBridge;
+    /**
+     * The transcript to seed the first frame with, from a resumed session
+     * (tui-session-id-resume 3.12).
+     *
+     * ABSENT IN EVERY ORDINARY LAUNCH, and absent is what keeps the first frame
+     * byte-identical to the pre-feature build (I-6).
+     */
+    initialEntries?: Entry[];
+    /** This process's session identity. `undefined` means "no chip, no checkpoint". */
+    session?: SessionIdentity;
+    /** The two actions `cli.tsx` owns: checkpoint now, and rotate after `/resume`. */
+    sessionBridge?: SessionBridge;
+    /**
+     * One line to show when the identity is NOT the obvious one (D-13): a branch,
+     * or a `--save` name. An ordinary new session says nothing - the chip is the
+     * affordance, and a notice on every launch trains users to ignore notices.
+     */
+    sessionNotice?: string;
+}
+/**
+ * `App`'s and `cli.tsx`'s small two-way surface for the session, shaped exactly
+ * like `confirmBridge` / `pasteBridge`.
+ *
+ * `checkpoint` and `rotate` are INSTALLED BY `cli.tsx` because the writer lives
+ * outside React (two of its callers are process-level); `onIdentity` is
+ * installed by the App so a rotation can move the chip, which is the only piece
+ * of the identity the view owns.
+ */
+export interface SessionBridge {
+    /**
+     * Write a checkpoint now; `pin` also marks the file as never-prunable, and
+     * `force` skips the fingerprint short circuit so `/branch` can guarantee that
+     * the file the new process is about to read is current (D-15).
+     */
+    checkpoint?: (opts?: {
+        pin?: boolean;
+        force?: boolean;
+    }) => CheckpointResult;
+    /** Adopt another conversation's identity (D-15); `undefined` if it cannot. */
+    rotate?: (loadedPath: string) => SessionIdentity | undefined;
+    /**
+     * Ctrl+L / `/branch`: branch this session into a NEW terminal. Installed by
+     * `cli.tsx`, because opening a window is a process-level act the App only asks
+     * for (tui-branch-terminal-shortcut 3.11). Absent in a build with no session,
+     * which is what lets `/branch` say so instead of throwing.
+     */
+    branch?: BranchCommandPort;
+    /** Installed by `App`; called by `rotate` after the new id is claimed. */
+    onIdentity?: (identity: SessionIdentity) => void;
 }
 export interface TerminalBridge {
     scrollbar?: ScrollbarBridge;
@@ -96,4 +148,4 @@ export interface TerminalBridge {
     writeForeign?: (text: string) => void;
     selection?: SelectionBridge;
 }
-export declare function App({ controller, version, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, pasteBridge, terminal, }: AppProps): React.ReactElement;
+export declare function App({ controller, version, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, pasteBridge, terminal, initialEntries, session, sessionBridge, sessionNotice, }: AppProps): React.ReactElement;