@cjhyy/code-shell-core 0.7.1 → 0.8.0

package/dist/session/session-manager.js

@@ -4,21 +4,150 @@
 import { closeSync, existsSync, mkdirSync, lstatSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { createHash } from "node:crypto";
 import { nanoid } from "nanoid";
 import { Transcript } from "./transcript.js";
 import { SessionError } from "../exceptions.js";
-import { normalizeCumulativeUsageCounters } from "../engine/session-usage.js";
-import { isSameGoalInstance } from "../engine/goal.js";
-import { branchExists, isGitWorktreeRoot } from "../git/worktree.js";
+import { addCumulativeUsage, addTokenUsage, normalizeCumulativeUsageCounters } from "./usage.js";
+import { armGoalLifecycle, createGoalLifecycle, decodeGoalLifecycle, deriveLegacyGoalId, goalConfigFromLifecycle, isGoalLifecycleCurrent, isSameGoalVersion, mergeGoalTerminals, terminateGoalLifecycle, waitGoalLifecycle, } from "../goal/lifecycle.js";
+import { lockSync } from "../utils/lockfile.js";
+import { resolveCapabilities } from "../capabilities/index.js";
 // Shared close epochs for SessionManager instances in this process. Concurrent
 // Engines bind the same epoch; only close advances it. This intentionally does
 // not claim cross-process/Worker protection.
 const currentSessionCloseEpochs = new Map();
+const SESSION_STATE_LOCK_STALE_MS = 10_000;
+const SESSION_STATE_LOCK_RETRY_DELAYS_MS = [5, 10, 20, 40];
+const syncSleepCell = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+    Atomics.wait(syncSleepCell, 0, 0, ms);
+}
+function lifecycleTerminalReason(reason) {
+    return reason;
+}
+function newestLegacyTerminal(state) {
+    return mergeGoalTerminals(state.goalTerminals, state.goalTerminal).at(-1);
+}
+function legacyTerminalMatchesGoal(terminal, goal) {
+    if (terminal.goalId && goal.goalId) {
+        return (terminal.goalId === goal.goalId &&
+            Math.max(1, Math.floor(terminal.revision ?? 1)) ===
+                Math.max(1, Math.floor(goal.revision ?? 1)));
+    }
+    return terminal.objective === goal.objective && terminal.setAtMs === goal.setAtMs;
+}
+/** Decode the canonical union or derive it once from legacy aliases. */
+function hydrateGoalLifecycle(state) {
+    const hasCanonical = Object.prototype.hasOwnProperty.call(state, "goalLifecycle");
+    const persistedLifecycle = state.goalLifecycle;
+    let lifecycle;
+    if (hasCanonical && persistedLifecycle !== undefined) {
+        lifecycle = decodeGoalLifecycle(persistedLifecycle);
+        if (!lifecycle) {
+            throw new SessionError(`Session goal lifecycle is unsupported or corrupt for ${state.sessionId}`);
+        }
+    }
+    else if (state.activeGoal) {
+        const active = {
+            ...state.activeGoal,
+            goalId: state.activeGoal.goalId ?? deriveLegacyGoalId(state.sessionId, state.activeGoal),
+            revision: Math.max(1, Math.floor(state.activeGoal.revision ?? 1)),
+        };
+        const terminal = mergeGoalTerminals(state.goalTerminals, state.goalTerminal).find((candidate) => legacyTerminalMatchesGoal(candidate, active));
+        const base = createGoalLifecycle(active, active.paused === true ? "paused" : "active");
+        lifecycle = terminal
+            ? terminateGoalLifecycle(base, lifecycleTerminalReason(terminal.reason), terminal.terminatedAtMs ?? Date.now())
+            : base;
+    }
+    else {
+        const terminal = newestLegacyTerminal(state);
+        if (terminal) {
+            const goal = {
+                objective: terminal.objective,
+                goalId: terminal.goalId ??
+                    deriveLegacyGoalId(state.sessionId, {
+                        objective: terminal.objective,
+                        setAtMs: terminal.setAtMs,
+                    }),
+                revision: Math.max(1, Math.floor(terminal.revision ?? 1)),
+                ...(terminal.setAtMs !== undefined ? { setAtMs: terminal.setAtMs } : {}),
+            };
+            lifecycle = terminateGoalLifecycle(createGoalLifecycle(goal, "active", terminal.terminatedAtMs ?? Date.now()), lifecycleTerminalReason(terminal.reason), terminal.terminatedAtMs ?? Date.now());
+        }
+    }
+    if (lifecycle)
+        state.goalLifecycle = lifecycle;
+    else
+        delete state.goalLifecycle;
+    // Legacy aliases are migration inputs only. Never reconstruct them in RAM:
+    // all runtime readers and writers consume the canonical lifecycle union.
+    delete state.activeGoal;
+    delete state.goalTerminal;
+    delete state.goalTerminals;
+    return state;
+}
+/** New files and runtime state contain only the canonical union. */
+function stateForPersistence(state) {
+    const persisted = { ...state };
+    delete persisted.activeGoal;
+    delete persisted.goalTerminal;
+    delete persisted.goalTerminals;
+    return persisted;
+}
+/**
+ * Temporary adapter for tests/older in-repo callers that still mutate the
+ * hydrated aliases before calling whole-state saveState. Production Goal paths
+ * use the domain methods below. The adapter never writes aliases to disk.
+ */
+function adoptCompatibilityGoalMutation(state) {
+    const activeTouched = Object.prototype.hasOwnProperty.call(state, "activeGoal");
+    const terminalTouched = Object.prototype.hasOwnProperty.call(state, "goalTerminal") ||
+        Object.prototype.hasOwnProperty.call(state, "goalTerminals");
+    if (!activeTouched && !terminalTouched)
+        return;
+    const lifecycle = decodeGoalLifecycle(state.goalLifecycle);
+    const alias = state.activeGoal
+        ? {
+            ...state.activeGoal,
+            goalId: state.activeGoal.goalId ?? deriveLegacyGoalId(state.sessionId, state.activeGoal),
+            revision: Math.max(1, Math.floor(state.activeGoal.revision ?? 1)),
+        }
+        : undefined;
+    const terminals = mergeGoalTerminals(state.goalTerminals, state.goalTerminal);
+    if (!lifecycle) {
+        if (alias) {
+            state.goalLifecycle = createGoalLifecycle(alias, alias.paused === true ? "paused" : "active");
+        }
+        return;
+    }
+    if (alias) {
+        const sameIdentity = lifecycle.goalId === alias.goalId;
+        const sameRevision = lifecycle.revision === alias.revision;
+        const matchingTerminal = terminals.find((terminal) => legacyTerminalMatchesGoal(terminal, alias));
+        if (matchingTerminal) {
+            const base = createGoalLifecycle(alias, alias.paused === true ? "paused" : "active");
+            state.goalLifecycle = terminateGoalLifecycle(base, lifecycleTerminalReason(matchingTerminal.reason), matchingTerminal.terminatedAtMs ?? Date.now());
+            return;
+        }
+        if (lifecycle.phase === "terminal" && sameIdentity && sameRevision)
+            return;
+        const canonicalGoal = goalConfigFromLifecycle(lifecycle);
+        if (!sameIdentity || !sameRevision || !isSameGoalVersion(alias, canonicalGoal)) {
+            state.goalLifecycle = createGoalLifecycle(alias, alias.paused === true ? "paused" : "active");
+        }
+        return;
+    }
+    const matchingTerminal = terminals.find((terminal) => legacyTerminalMatchesGoal(terminal, goalConfigFromLifecycle(lifecycle)));
+    if (matchingTerminal && lifecycle.phase !== "terminal") {
+        state.goalLifecycle = terminateGoalLifecycle(lifecycle, lifecycleTerminalReason(matchingTerminal.reason), matchingTerminal.terminatedAtMs ?? Date.now());
+    }
+}
 const FORK_COPY_EVENT_TYPES = new Set([
     "message",
     "tool_use",
     "tool_result",
     "summary",
+    "context_transfer",
     "content_replace",
     "subagent",
     "external_file_changes",
@@ -72,6 +201,18 @@ export function assertSafeSessionId(sessionId) {
         throw new SessionError(`invalid session id: too long (max 128 chars)`);
     }
 }
+/**
+ * Runtime source of truth for sessions whose state must not outlive their UI
+ * lifecycle. The explicit marker covers modern side forks; the qchat namespace
+ * keeps historical/blank quick chats fail-closed if their older state file did
+ * not contain the marker yet.
+ */
+export function isEphemeralSessionState(state) {
+    return state.ephemeral === true || state.sessionId.startsWith("qchat-");
+}
+function normalizedSessionKind(kind) {
+    return kind === "pet" ? "pet" : "work";
+}
 /**
  * Resolve the `.code-shell` home dir. `CODE_SHELL_HOME` overrides the default
  * `~/.code-shell` — mirrors Codex's `CODEX_HOME`. Tests set it to a temp dir
@@ -82,6 +223,14 @@ export function assertSafeSessionId(sessionId) {
 export function codeShellHome() {
     return process.env.CODE_SHELL_HOME || join(homedir(), ".code-shell");
 }
+/**
+ * Canonical root for every persisted CodeShell session. An explicit `home`
+ * (a `~/.code-shell`-equivalent data root) overrides the default resolution;
+ * absent → `codeShellHome()` exactly as before.
+ */
+export function sessionsRoot(home) {
+    return join(home ?? codeShellHome(), "sessions");
+}
 function isSessionWorkspace(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -102,7 +251,16 @@ function isSessionWorkspace(value) {
         wt.baseRef.length > 0 &&
         wt.createdBy === "codeshell");
 }
-async function validateResumeWorktreeRoot(root) {
+/**
+ * Read the session's persisted main-project root from the legacy `state.cwd`
+ * field. The field name is part of the state.json compatibility contract and
+ * must not be rewritten to `projectRoot`; `state.workspace.root` separately
+ * identifies the current main/worktree execution root used on resume.
+ */
+export function sessionMainRoot(state) {
+    return typeof state.cwd === "string" && state.cwd.length > 0 ? state.cwd : undefined;
+}
+async function validateResumeWorktreeRoot(root, workspaceCapability) {
     if (!existsSync(root))
         return "no longer exists";
     let stat;
@@ -116,15 +274,21 @@ async function validateResumeWorktreeRoot(root) {
         return "is not a valid git worktree (symbolic link)";
     if (!stat.isDirectory())
         return "is not a valid git worktree (not a directory)";
-    if (!(await isGitWorktreeRoot(root)))
-        return "is not a valid git worktree";
+    if (!(await workspaceCapability.validateRoot(root)))
+        return "is not a valid workspace root";
     return null;
 }
 export class SessionManager {
     sessionsDir;
     registeredCloseEpochs = new Map();
-    constructor(storageDir) {
-        this.sessionsDir = storageDir ?? join(codeShellHome(), "sessions");
+    workspaceCapability;
+    constructor(storageDir, workspaceCapability) {
+        this.sessionsDir = storageDir ?? sessionsRoot();
+        this.workspaceCapability =
+            workspaceCapability ??
+                resolveCapabilities()
+                    .map((capability) => capability.sessionWorkspace)
+                    .find((candidate) => candidate !== undefined);
         mkdirSync(this.sessionsDir, { recursive: true });
         this.cleanupStaleForkStaging();
     }
@@ -178,7 +342,7 @@ export class SessionManager {
      * nanoid. Either way the on-disk directory is materialized and the
      * state.json + transcript.jsonl files are written before return.
      */
-    create(cwd, model, provider, explicitSessionId, parentSessionId, origin) {
+    create(cwd, model, provider, explicitSessionId, parentSessionId, origin, kind = "work") {
         // External callers may pass any string; nanoid output is trusted. Either
         // way the ID gets joined into a filesystem path, so the public entry
         // point validates before that join.
@@ -197,6 +361,8 @@ export class SessionManager {
         }
         const state = {
             sessionId,
+            kind,
+            stateRevision: 0,
             cwd,
             workspace: { root: cwd, kind: "main" },
             startedAt: Date.now(),
@@ -214,6 +380,7 @@ export class SessionManager {
             // new top-level session (key present, null) apart from a legacy session
             // (key absent) and from a sub-agent (key present, non-empty string).
             parentSessionId: parentSessionId ?? null,
+            ...(sessionId.startsWith("qchat-") ? { ephemeral: true } : {}),
             ...(origin ? { origin } : {}),
         };
         // Atomic write (tmp+rename) like saveState, so a crash during this one-time
@@ -229,6 +396,7 @@ export class SessionManager {
             model,
             provider,
             startedAt: state.startedAt,
+            kind,
         });
         return { state, transcript };
     }
@@ -250,16 +418,124 @@ export class SessionManager {
         return existsSync(join(this.sessionsDir, sessionId));
     }
     /**
-     * Cheap "what cwd is this session bound to?" probe — reads only state.json,
-     * NOT the transcript (unlike resume()). engine.run uses this to recover a
-     * resumed session's project directory when the caller omits options.cwd
-     * (e.g. a desktop host whose sidebar repo selection has drifted to null),
-     * so a project-bound session keeps loading its own agents/settings/memory
-     * instead of falling back to process.cwd(). Returns undefined for an
-     * unknown, malformed, or traversal-shaped id rather than throwing — the
-     * caller treats "no recoverable cwd" the same as "not given".
+     * Cheap persisted-main-root probe — reads only state.json, NOT the transcript
+     * (unlike resume()). This deliberately reads legacy `state.cwd`, not the
+     * current `state.workspace.root`; callers use it as the stable main-project
+     * fallback when a worktree is unavailable or is being released.
+     */
+    readSessionMainRoot(sessionId) {
+        try {
+            assertSafeSessionId(sessionId);
+        }
+        catch {
+            return undefined;
+        }
+        const stateFile = join(this.sessionsDir, sessionId, "state.json");
+        if (!existsSync(stateFile))
+            return undefined;
+        try {
+            const state = JSON.parse(readFileSync(stateFile, "utf-8"));
+            return sessionMainRoot(state);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Cheap durable classification read. Legacy sessions are ordinary work sessions. */
+    readSessionKind(sessionId) {
+        try {
+            assertSafeSessionId(sessionId);
+        }
+        catch {
+            return undefined;
+        }
+        const stateFile = join(this.sessionsDir, sessionId, "state.json");
+        if (!existsSync(stateFile))
+            return undefined;
+        try {
+            const state = JSON.parse(readFileSync(stateFile, "utf-8"));
+            return normalizedSessionKind(state.kind);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Cheap durable digital-human binding read. */
+    readSessionWorkspaceProfile(sessionId) {
+        try {
+            assertSafeSessionId(sessionId);
+            const stateFile = join(this.sessionsDir, sessionId, "state.json");
+            if (!existsSync(stateFile))
+                return undefined;
+            const state = JSON.parse(readFileSync(stateFile, "utf-8"));
+            return typeof state.workspaceProfile === "string" && state.workspaceProfile
+                ? state.workspaceProfile
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Find durable Sessions currently bound to one digital-human profile without loading
+     * transcripts. Used by profile deletion guards so a reusable/historical
+     * Session cannot be left permanently unresumable.
+     */
+    /**
+     * Sessions whose state pins this digital human.
+     *
+     * `includeArchived: false` drops archived Sessions: they are closed history,
+     * not a live binding, so they should not block deleting the profile. A
+     * dangling name is already handled downstream — resolveActiveWorkspaceProfile
+     * logs `profile.active_missing_from_library` and returns undefined.
      */
+    findSessionIdsByWorkspaceProfile(profileName, limit = 20, options = {}) {
+        const includeArchived = options.includeArchived !== false;
+        const target = typeof profileName === "string" ? profileName.trim() : "";
+        if (!target || target.length > 64 || limit <= 0)
+            return [];
+        const cap = Math.max(1, Math.min(100, Math.floor(limit)));
+        let entries;
+        try {
+            entries = readdirSync(this.sessionsDir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        const matches = [];
+        for (const entry of entries) {
+            if (matches.length >= cap)
+                break;
+            if (!entry.isDirectory() ||
+                entry.name.startsWith(".pending-") ||
+                entry.name.startsWith("qchat-")) {
+                continue;
+            }
+            try {
+                assertSafeSessionId(entry.name);
+                const stateFile = join(this.sessionsDir, entry.name, "state.json");
+                const info = lstatSync(stateFile);
+                if (info.isSymbolicLink() || !info.isFile() || info.size > 1024 * 1024)
+                    continue;
+                const state = JSON.parse(readFileSync(stateFile, "utf-8"));
+                if (state.workspaceProfile !== target)
+                    continue;
+                if (!includeArchived && typeof state.archivedAt === "number")
+                    continue;
+                matches.push(entry.name);
+            }
+            catch {
+                // Corrupt or unsafe Sessions are isolated from the deletion decision.
+            }
+        }
+        return matches.sort();
+    }
+    /** @deprecated Use readSessionMainRoot; retained for public API compatibility. */
     readCwd(sessionId) {
+        return this.readSessionMainRoot(sessionId);
+    }
+    /** Disk-only direct-parent ACL metadata. Undefined means unprovable/corrupt. */
+    readParentSessionId(sessionId) {
         try {
             assertSafeSessionId(sessionId);
         }
@@ -271,7 +547,9 @@ export class SessionManager {
             return undefined;
         try {
             const state = JSON.parse(readFileSync(stateFile, "utf-8"));
-            return typeof state.cwd === "string" && state.cwd.length > 0 ? state.cwd : undefined;
+            return state.parentSessionId === null || typeof state.parentSessionId === "string"
+                ? state.parentSessionId
+                : undefined;
         }
         catch {
             return undefined;
@@ -296,9 +574,8 @@ export class SessionManager {
             const state = JSON.parse(readFileSync(stateFile, "utf-8"));
             if (isSessionWorkspace(state.workspace))
                 return state.workspace;
-            return typeof state.cwd === "string" && state.cwd.length > 0
-                ? { root: state.cwd, kind: "main" }
-                : undefined;
+            const mainRoot = sessionMainRoot(state);
+            return mainRoot ? { root: mainRoot, kind: "main" } : undefined;
         }
         catch {
             return undefined;
@@ -314,19 +591,30 @@ export class SessionManager {
         if (!isSessionWorkspace(workspace)) {
             throw new SessionError(`invalid workspace for session ${sessionId}`);
         }
-        const stateFile = join(this.sessionsDir, sessionId, "state.json");
-        if (!existsSync(stateFile)) {
-            throw new SessionError(`Session state file not found: ${sessionId}`);
+        return this.updateSessionState(sessionId, { workspace });
+    }
+    /** Read the durable archival timestamp; undefined = not archived / unprovable. */
+    readSessionArchivedAt(sessionId) {
+        try {
+            assertSafeSessionId(sessionId);
         }
-        let state;
+        catch {
+            return undefined;
+        }
+        const stateFile = join(this.sessionsDir, sessionId, "state.json");
+        if (!existsSync(stateFile))
+            return undefined;
         try {
-            state = JSON.parse(readFileSync(stateFile, "utf-8"));
+            const state = JSON.parse(readFileSync(stateFile, "utf-8"));
+            return typeof state.archivedAt === "number" ? state.archivedAt : undefined;
         }
-        catch (err) {
-            throw new SessionError(`Session state is corrupt for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+        catch {
+            return undefined;
         }
-        state.workspace = workspace;
-        this.saveState(state);
+    }
+    /** Set (number) or clear (undefined) the durable archival marker. */
+    setSessionArchived(sessionId, archivedAt) {
+        return this.updateSessionState(sessionId, { archivedAt });
     }
     recordWorkspaceHandoff(sessionId, from, to) {
         assertSafeSessionId(sessionId);
@@ -368,9 +656,8 @@ export class SessionManager {
         catch (err) {
             throw new SessionError(`Session state is corrupt for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
         }
-        const legacyMain = typeof state.cwd === "string" && state.cwd.length > 0
-            ? { root: state.cwd, kind: "main" }
-            : undefined;
+        const mainRoot = sessionMainRoot(state);
+        const legacyMain = mainRoot ? { root: mainRoot, kind: "main" } : undefined;
         const workspace = isSessionWorkspace(state.workspace) ? state.workspace : legacyMain;
         if (!workspace) {
             throw new SessionError(`Session ${sessionId} has no recoverable cwd`);
@@ -383,16 +670,28 @@ export class SessionManager {
                 reason: isSessionWorkspace(state.workspace) ? "main" : "legacy",
             };
         }
-        const invalidWorktreeReason = await validateResumeWorktreeRoot(workspace.root);
+        if (!this.workspaceCapability) {
+            return {
+                ok: false,
+                cwd: mainRoot ?? workspace.root,
+                workspace,
+                reason: "workspace_capability_unavailable",
+                message: `Session ${sessionId} uses a product workspace, but this host did not install ` +
+                    `the matching workspace capability. Install it before resuming this session.`,
+            };
+        }
+        const invalidWorktreeReason = await validateResumeWorktreeRoot(workspace.root, this.workspaceCapability);
         if (!invalidWorktreeReason) {
             return { ok: true, cwd: workspace.root, workspace, reason: "worktree" };
         }
         const branch = workspace.worktree?.branch;
-        const mainRoot = typeof state.cwd === "string" && state.cwd.length > 0 ? state.cwd : workspace.root;
-        if (branch && existsSync(mainRoot) && (await branchExists(mainRoot, branch))) {
+        const fallbackMainRoot = mainRoot ?? workspace.root;
+        if (branch &&
+            existsSync(fallbackMainRoot) &&
+            (await this.workspaceCapability.branchExists(fallbackMainRoot, branch))) {
             return {
                 ok: false,
-                cwd: mainRoot,
+                cwd: fallbackMainRoot,
                 workspace,
                 reason: "worktree_missing_branch_exists",
                 message: `Session ${sessionId} is bound to worktree ${workspace.root}, but that directory ` +
@@ -401,23 +700,23 @@ export class SessionManager {
                     `back to main explicitly.`,
             };
         }
-        const fallback = { root: mainRoot, kind: "main" };
+        const fallback = { root: fallbackMainRoot, kind: "main" };
         state.workspace = fallback;
-        this.saveState(state);
+        state.stateRevision = this.updateSessionState(sessionId, { workspace: fallback });
         return {
             ok: true,
-            cwd: mainRoot,
+            cwd: fallbackMainRoot,
             workspace: fallback,
             reason: "worktree_missing_branch_gone",
             message: `Session ${sessionId} was bound to worktree ${workspace.root}, but that directory ` +
                 `${invalidWorktreeReason}${branch ? ` and branch ${branch} is gone` : ""}; fell back to main ` +
-                `${mainRoot}. Re-run the request if you want to continue there.`,
+                `${fallbackMainRoot}. Re-run the request if you want to continue there.`,
         };
     }
     /**
      * Cheap "does this session have a persisted goal?" probe — reads only
-     * state.json, NOT the transcript (like readCwd). A persistent goal lives ONLY
-     * in state.activeGoal; it is never appended to the transcript as an event, so
+     * state.json, NOT the transcript (like readSessionMainRoot). A persistent goal lives in
+     * the canonical goalLifecycle union; it is never appended to the transcript as an event, so
      * a session rebuilt from disk (e.g. localStorage wiped) can't recover the
      * goal from its messages. The desktop host calls this on session load to
      * re-surface the active-goal block + its Cancel button, which would otherwise
@@ -436,10 +735,18 @@ export class SessionManager {
         if (!existsSync(stateFile))
             return undefined;
         try {
-            const state = JSON.parse(readFileSync(stateFile, "utf-8"));
-            return isSameGoalInstance(state.activeGoal, state.goalTerminal)
-                ? undefined
-                : state.activeGoal;
+            const state = hydrateGoalLifecycle(JSON.parse(readFileSync(stateFile, "utf-8")));
+            const lifecycle = state.goalLifecycle;
+            if (!lifecycle || lifecycle.phase === "terminal")
+                return undefined;
+            const goal = goalConfigFromLifecycle(lifecycle);
+            // Expose a concrete version even for legacy state.json so UI delete/edit
+            // operations can send an expected fence instead of acting unconditionally.
+            return {
+                ...goal,
+                goalId: goal.goalId ?? deriveLegacyGoalId(sessionId, goal),
+                revision: goal.revision ?? 1,
+            };
         }
         catch {
             return undefined;
@@ -447,8 +754,9 @@ export class SessionManager {
     }
     /**
      * Disk-only "wipe this session's persistent goal" — the counterpart to
-     * readActiveGoal. Reads state.json, removes state.activeGoal, and rewrites it
-     * atomically (via saveState). Returns true only if a goal was actually
+     * readActiveGoal. Reads state.json, transitions the matching goalLifecycle
+     * to terminal(user_cleared), and rewrites it through the field-level CAS.
+     * Returns true only if a goal was actually
      * present (idempotent — clearing a session with no goal is a no-op returning
      * false). Never throws on an unknown / malformed / traversal-shaped id
      * (returns false), matching readActiveGoal's tolerance.
@@ -461,28 +769,107 @@ export class SessionManager {
      * Engine.clearGoal also delegates its disk write here so the wipe logic lives
      * in exactly one place.
      */
-    clearActiveGoal(sessionId) {
+    clearActiveGoal(sessionId, expected) {
         try {
             assertSafeSessionId(sessionId);
         }
         catch {
             return false;
         }
-        const stateFile = join(this.sessionsDir, sessionId, "state.json");
-        if (!existsSync(stateFile))
-            return false;
-        let state;
+        for (let attempt = 0; attempt <= SESSION_STATE_LOCK_RETRY_DELAYS_MS.length; attempt++) {
+            let state;
+            try {
+                state = this.readPersistedState(sessionId);
+            }
+            catch {
+                return false;
+            }
+            const lifecycle = state.goalLifecycle;
+            if (!lifecycle || !isGoalLifecycleCurrent(lifecycle))
+                return false;
+            const clearedGoal = goalConfigFromLifecycle(lifecycle);
+            const revision = lifecycle.revision;
+            if (expected?.goalId !== undefined && clearedGoal.goalId !== expected.goalId)
+                return false;
+            if (expected?.revision !== undefined && revision !== expected.revision)
+                return false;
+            const terminal = terminateGoalLifecycle(lifecycle, "user_cleared");
+            if (!terminal)
+                return false;
+            state.goalLifecycle = terminal;
+            hydrateGoalLifecycle(state);
+            const result = this.saveStateAttempt(state);
+            if (result.ok)
+                return true;
+            if (result.reason !== "revision_conflict")
+                return false;
+        }
+        return false;
+    }
+    /**
+     * Edit or pause/resume the currently active goal with an identity-checked,
+     * field-level CAS. The goalId is preserved: editing the objective changes
+     * the same user-owned goal rather than terminally cancelling it and arming a
+     * replacement. A changed objective receives a fresh deadline anchor.
+     *
+     * Returns undefined when the session/goal is absent or the patch is invalid.
+     * The returned state lets a live Engine rebase its in-memory bundle after
+     * this control operation.
+     */
+    updateActiveGoal(sessionId, patch) {
         try {
-            state = JSON.parse(readFileSync(stateFile, "utf-8"));
+            assertSafeSessionId(sessionId);
         }
         catch {
-            return false;
+            return undefined;
         }
-        if (state.activeGoal === undefined)
-            return false;
-        state.activeGoal = undefined;
-        this.saveState(state);
-        return true;
+        if (patch.objective === undefined && patch.paused === undefined)
+            return undefined;
+        if (patch.objective !== undefined && !patch.objective.trim())
+            return undefined;
+        if (patch.paused !== undefined && typeof patch.paused !== "boolean")
+            return undefined;
+        let expectedGoalId = patch.expectedGoalId;
+        let expectedRevision = patch.expectedRevision;
+        for (let attempt = 0; attempt <= SESSION_STATE_LOCK_RETRY_DELAYS_MS.length; attempt++) {
+            let state;
+            try {
+                state = this.readPersistedState(sessionId);
+            }
+            catch {
+                return undefined;
+            }
+            const lifecycle = state.goalLifecycle;
+            if (!lifecycle || !isGoalLifecycleCurrent(lifecycle))
+                return undefined;
+            const current = goalConfigFromLifecycle(lifecycle);
+            const currentRevision = lifecycle.revision;
+            expectedGoalId ??= current.goalId;
+            expectedRevision ??= currentRevision;
+            if (current.goalId !== expectedGoalId || currentRevision !== expectedRevision) {
+                return undefined;
+            }
+            const objective = patch.objective?.trim() ?? current.objective;
+            const objectiveChanged = objective !== current.objective;
+            const goal = {
+                ...current,
+                objective,
+                revision: currentRevision + 1,
+                ...(objectiveChanged ? { setAtMs: Date.now() } : {}),
+            };
+            if (patch.paused === true)
+                goal.paused = true;
+            else if (patch.paused === false)
+                delete goal.paused;
+            state.goalLifecycle = createGoalLifecycle(goal, goal.paused === true ? "paused" : "active");
+            hydrateGoalLifecycle(state);
+            const result = this.saveStateAttempt(state);
+            if (result.ok)
+                return { goal, stateRevision: state.stateRevision, state };
+            if (result.reason !== "revision_conflict")
+                return undefined;
+        }
+        return undefined;
     }
     resume(sessionId) {
         assertSafeSessionId(sessionId);
@@ -496,7 +883,7 @@ export class SessionManager {
         }
         let state;
         try {
-            state = JSON.parse(readFileSync(stateFile, "utf-8"));
+            state = hydrateGoalLifecycle(JSON.parse(readFileSync(stateFile, "utf-8")));
         }
         catch (err) {
             // A corrupt state.json (external tampering, disk corruption, or a crash
@@ -506,89 +893,402 @@ export class SessionManager {
         }
         const transcriptFile = join(sessionDir, "transcript.jsonl");
         const transcript = Transcript.loadFromFile(transcriptFile);
+        state.kind = normalizedSessionKind(state.kind);
         state.status = "active";
+        delete state.lastCompletionKind;
         Object.assign(state, normalizeCumulativeUsageCounters(state, state.tokenUsage));
         return { state, transcript };
     }
+    /**
+     * Return the exact persistence directory owned by this manager.
+     *
+     * Cross-session sidecars (for example versioned handoffs) use this to stay
+     * inside an identity/custom-data-root boundary instead of falling back to
+     * the process-global default sessions directory.
+     */
+    getStorageDir() {
+        return this.sessionsDir;
+    }
+    /**
+     * Read one durable session state without changing its lifecycle status.
+     * `resume()` intentionally marks the returned in-memory state active; host
+     * coordination code needs a read-only snapshot for completed cursors and
+     * workspace/profile metadata.
+     */
+    readSessionState(sessionId) {
+        try {
+            assertSafeSessionId(sessionId);
+            return structuredClone(this.readPersistedState(sessionId));
+        }
+        catch {
+            return undefined;
+        }
+    }
     /**
      * Merge a field-level state update into the latest persisted snapshot.
      *
      * Unlike saveState(), callers do not supply a potentially stale whole-state
-     * object. The read, shallow merge, and atomic write are synchronous, so no
-     * other callback on this process's event loop can interleave between them.
-     * This is deliberately not a session-level lock. Engine.run rejects re-entry
-     * on one Engine (G6), and the generation check in saveState rejects an older
-     * registered Engine in this process. Workers and separate processes remain
-     * an unresolved finding requiring locking/CAS.
+     * object. saveState serializes the read/revision-check/write section with the
+     * per-session lock and returns the new persisted revision to the caller.
      */
     updateSessionState(sessionId, partial) {
         assertSafeSessionId(sessionId);
-        const stateFile = join(this.sessionsDir, sessionId, "state.json");
-        if (!existsSync(stateFile)) {
-            throw new SessionError(`Session state file not found: ${sessionId}`);
+        for (let attempt = 0; attempt <= SESSION_STATE_LOCK_RETRY_DELAYS_MS.length; attempt++) {
+            const state = this.readPersistedState(sessionId);
+            if (partial.kind !== undefined &&
+                normalizedSessionKind(partial.kind) !== normalizedSessionKind(state.kind)) {
+                throw new SessionError(`Session kind is immutable for ${sessionId}`);
+            }
+            Object.assign(state, partial);
+            state.sessionId = sessionId;
+            const result = this.saveStateAttempt(state);
+            if (result.ok)
+                return state.stateRevision;
+            if (result.reason === "generation_conflict") {
+                throw new SessionError(`Session generation conflict for ${sessionId}`);
+            }
+            if (result.reason === "lock_conflict") {
+                throw new SessionError(`Session state lock contention for ${sessionId}`);
+            }
+            if (result.reason === "kind_conflict") {
+                throw new SessionError(`Session kind is immutable for ${sessionId}`);
+            }
+            // A field-level update is explicitly authorized to merge into the newest
+            // snapshot. Re-read it on the next iteration instead of treating its CAS
+            // miss like a lock collision.
         }
-        let state;
+        throw new SessionError(`Session state revision conflict for ${sessionId}`);
+    }
+    /**
+     * Atomically add one billed auxiliary request to the latest source state.
+     * This field-level read/add/write avoids publishing a detached stale state
+     * snapshot and accounts prompt, completion, total, cache, and cost together.
+     */
+    recordAuxiliaryUsage(sessionId, usage, costState) {
+        assertSafeSessionId(sessionId);
+        for (let attempt = 0; attempt <= SESSION_STATE_LOCK_RETRY_DELAYS_MS.length; attempt++) {
+            const state = this.readPersistedState(sessionId);
+            Object.assign(state, normalizeCumulativeUsageCounters(state, state.tokenUsage));
+            Object.assign(state, addCumulativeUsage(state, usage));
+            state.tokenUsage = addTokenUsage(state.tokenUsage, usage);
+            if (costState !== undefined)
+                state.costState = costState;
+            const result = this.saveStateAttempt(state);
+            if (result.ok)
+                return;
+            if (result.reason === "generation_conflict") {
+                throw new SessionError(`Session generation conflict for ${sessionId}`);
+            }
+            if (result.reason === "lock_conflict") {
+                throw new SessionError(`Session state lock contention for ${sessionId}`);
+            }
+            // Recompute the delta from the latest counters after a CAS miss so the
+            // auxiliary usage is added exactly once without overwriting another writer.
+        }
+        throw new SessionError(`Session state revision conflict for ${sessionId}`);
+    }
+    /** @deprecated Compatibility fixture writer; runtime code must use domain updates. */
+    saveState(state, generation) {
+        adoptCompatibilityGoalMutation(state);
+        return this.saveStateAttempt(state, generation).ok;
+    }
+    /**
+     * Persist one goal terminal transition without allowing a revision race to
+     * resurrect that goal. This is always a Goal-domain update: read the newest
+     * snapshot, transition only the matching lifecycle identity, then commit. A detached run
+     * snapshot is never used as the write candidate,
+     * so a successful terminal transition cannot publish stale summary/workspace
+     * or accounting fields. Lock/generation conflicts remain distinct failures.
+     */
+    saveGoalTerminal(state, goal, reason) {
+        return this.saveGoalTerminalOutcome(state, goal, reason) !== "failed";
+    }
+    /**
+     * Persist a terminal transition and distinguish a durable commit from a stale
+     * run whose Goal identity has already been replaced. Callers may publish a
+     * terminal event only for `persisted`.
+     */
+    saveGoalTerminalOutcome(state, goal, reason) {
+        if (!goal)
+            return "failed";
+        const terminalGoal = {
+            ...goal,
+            goalId: goal.goalId ?? deriveLegacyGoalId(state.sessionId, goal),
+            revision: goal.revision ?? 1,
+        };
+        for (let attempt = 0; attempt <= SESSION_STATE_LOCK_RETRY_DELAYS_MS.length; attempt++) {
+            const latest = this.readPersistedState(state.sessionId);
+            const lifecycle = latest.goalLifecycle;
+            if (!lifecycle)
+                return "failed";
+            if (lifecycle.goalId !== terminalGoal.goalId ||
+                lifecycle.revision !== (terminalGoal.revision ?? 1)) {
+                // A newer replacement/edit already owns the canonical slot. The stale
+                // run is obsolete, but must not mutate that newer goal.
+                this.rebaseLiveState(state, latest);
+                return "obsolete";
+            }
+            if (lifecycle.phase !== "terminal") {
+                latest.goalLifecycle = terminateGoalLifecycle(lifecycle, lifecycleTerminalReason(reason));
+                hydrateGoalLifecycle(latest);
+            }
+            const result = this.saveStateAttempt(latest);
+            if (result.ok) {
+                this.rebaseLiveState(state, latest);
+                return "persisted";
+            }
+            if (result.reason !== "revision_conflict")
+                return "failed";
+        }
+        return "failed";
+    }
+    /**
+     * Arm or migrate one active goal as a Goal-domain update. The newest state is
+     * always the write base, so unrelated fields written by another host survive.
+     * Replacement is explicit and terminally closes the latest active identity;
+     * a non-replacement write may only normalize the same legacy/current goal.
+     */
+    saveActiveGoal(state, goal, options = {}) {
+        const armedGoal = {
+            ...goal,
+            goalId: goal.goalId ?? deriveLegacyGoalId(state.sessionId, goal),
+            revision: goal.revision ?? 1,
+        };
+        for (let attempt = 0; attempt <= SESSION_STATE_LOCK_RETRY_DELAYS_MS.length; attempt++) {
+            const latest = this.readPersistedState(state.sessionId);
+            const current = latest.goalLifecycle;
+            if (current) {
+                const sameIdentity = current.goalId === armedGoal.goalId;
+                const sameRevision = current.revision === (armedGoal.revision ?? 1);
+                if (current.phase === "terminal" && sameIdentity && sameRevision)
+                    return false;
+                if (current.phase !== "terminal" && !options.replaceCurrent && !sameIdentity)
+                    return false;
+            }
+            if (current?.phase === "waiting" &&
+                current.goalId === armedGoal.goalId &&
+                current.revision === (armedGoal.revision ?? 1)) {
+                latest.goalLifecycle = armGoalLifecycle(current) ?? current;
+            }
+            else {
+                latest.goalLifecycle = createGoalLifecycle(armedGoal, armedGoal.paused === true ? "paused" : "active");
+            }
+            hydrateGoalLifecycle(latest);
+            const result = this.saveStateAttempt(latest);
+            if (result.ok) {
+                this.rebaseLiveState(state, latest);
+                return true;
+            }
+            if (result.reason !== "revision_conflict")
+                return false;
+        }
+        return false;
+    }
+    /** Persist active → waiting only for the expected concrete Goal version. */
+    markGoalWaiting(state, goal) {
+        const expectedGoalId = goal.goalId ?? deriveLegacyGoalId(state.sessionId, goal);
+        const expectedRevision = Math.max(1, Math.floor(goal.revision ?? 1));
+        for (let attempt = 0; attempt <= SESSION_STATE_LOCK_RETRY_DELAYS_MS.length; attempt++) {
+            const latest = this.readPersistedState(state.sessionId);
+            const lifecycle = latest.goalLifecycle;
+            if (!lifecycle)
+                return false;
+            if (lifecycle.goalId !== expectedGoalId || lifecycle.revision !== expectedRevision) {
+                this.rebaseLiveState(state, latest);
+                return false;
+            }
+            if (lifecycle.phase === "waiting") {
+                this.rebaseLiveState(state, latest);
+                return true;
+            }
+            const waiting = waitGoalLifecycle(lifecycle);
+            if (!waiting)
+                return false;
+            latest.goalLifecycle = waiting;
+            hydrateGoalLifecycle(latest);
+            const result = this.saveStateAttempt(latest);
+            if (result.ok) {
+                this.rebaseLiveState(state, latest);
+                return true;
+            }
+            if (result.reason !== "revision_conflict")
+                return false;
+        }
+        return false;
+    }
+    /** Drop a matching active goal only when its terminal identity is durable. */
+    clearTerminatedActiveGoal(state, goal) {
+        for (let attempt = 0; attempt <= SESSION_STATE_LOCK_RETRY_DELAYS_MS.length; attempt++) {
+            const latest = this.readPersistedState(state.sessionId);
+            const expectedGoalId = goal.goalId ?? deriveLegacyGoalId(state.sessionId, goal);
+            const lifecycle = latest.goalLifecycle;
+            if (!lifecycle ||
+                lifecycle.goalId !== expectedGoalId ||
+                lifecycle.revision !== Math.max(1, Math.floor(goal.revision ?? 1))) {
+                this.rebaseLiveState(state, latest);
+                return true;
+            }
+            if (lifecycle.phase !== "terminal")
+                return false;
+            this.rebaseLiveState(state, latest);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Commit only the fields owned by a live run. The detached `state` object is
+     * used solely as a live-view target for the returned revision; it is never
+     * serialized wholesale. This prevents a Goal/workspace/title domain write
+     * from authorizing a later stale metadata overwrite.
+     */
+    saveStateOrUpdateFields(state, partial) {
         try {
-            state = JSON.parse(readFileSync(stateFile, "utf-8"));
+            const stateRevision = this.updateSessionState(state.sessionId, partial);
+            Object.assign(state, partial, { stateRevision });
+            return true;
         }
-        catch (err) {
-            throw new SessionError(`Session state is corrupt for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+        catch {
+            return false;
         }
-        Object.assign(state, partial);
-        state.sessionId = sessionId;
-        this.saveState(state);
     }
-    saveState(state, generation) {
+    saveStateAttempt(state, generation) {
         // state.sessionId could come from a deserialized state.json that was
         // tampered with on disk. Validate before joining.
         assertSafeSessionId(state.sessionId);
+        try {
+            hydrateGoalLifecycle(state);
+        }
+        catch {
+            return { ok: false, reason: "goal_schema_conflict" };
+        }
         const writerGeneration = generation ?? this.registeredCloseEpochs.get(state.sessionId);
         if (writerGeneration !== undefined &&
             (currentSessionCloseEpochs.get(this.generationKey(state.sessionId)) ?? 0) !== writerGeneration) {
-            // A closing/old Engine may finish asynchronously after its generation was
-            // invalidated. Reject explicitly without throwing into an unobserved
-            // engine finally path, and most importantly without touching the disk.
-            return false;
+            return { ok: false, reason: "generation_conflict" };
         }
         const sessionDir = join(this.sessionsDir, state.sessionId);
         mkdirSync(sessionDir, { recursive: true });
-        // Atomic file replacement: stage to .tmp, then rename, preventing a torn
-        // state.json. Registered Engines share one epoch until close advances it,
-        // so concurrent opens are not fenced from each other. Workers, separate
-        // processes, and their stale-writer ordering still require locking/CAS.
         const target = join(sessionDir, "state.json");
-        // Preserve the newest goal tombstone across whole-state writers. If an old
-        // detached bundle still carries the tombstoned goal, drop it before write;
-        // when disk already contains a newer replacement goal, retain that goal as
-        // well instead of letting the stale bundle erase it.
-        let persisted;
-        if (existsSync(target)) {
+        // proper-lockfile uses an atomic mkdir lock plus an mtime lease. It
+        // recovers crash-orphaned locks after `stale` and refreshes live locks so a
+        // slow writer is not stolen. Short genuine contention gets bounded retry.
+        const release = this.acquireStateLock(target);
+        if (!release)
+            return { ok: false, reason: "lock_conflict" };
+        try {
+            let persisted;
+            if (existsSync(target)) {
+                try {
+                    persisted = hydrateGoalLifecycle(JSON.parse(readFileSync(target, "utf-8")));
+                }
+                catch {
+                    return { ok: false, reason: "goal_schema_conflict" };
+                }
+            }
+            const incomingKind = normalizedSessionKind(state.kind);
+            const persistedKind = persisted ? normalizedSessionKind(persisted.kind) : incomingKind;
+            if (persisted && incomingKind !== persistedKind) {
+                return { ok: false, reason: "kind_conflict" };
+            }
+            state.kind = persistedKind;
+            const persistedRevision = persisted?.stateRevision;
+            const incomingRevision = state.stateRevision;
+            const revisionsMatch = persisted === undefined ||
+                (persistedRevision === undefined && incomingRevision === undefined) ||
+                (typeof persistedRevision === "number" && incomingRevision === persistedRevision);
+            if (!revisionsMatch)
+                return { ok: false, reason: "revision_conflict" };
+            // A title can be generated by a field-level writer while this bundle is
+            // live. Preserve it when the incoming object never owned the field.
+            if (persisted?.title !== undefined && !("title" in state)) {
+                state.title = persisted.title;
+            }
+            state.stateRevision = (persistedRevision ?? incomingRevision ?? 0) + 1;
+            const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+            writeFileSync(tmp, JSON.stringify(stateForPersistence(state), null, 2), "utf-8");
+            renameSync(tmp, target);
+            return { ok: true };
+        }
+        finally {
             try {
-                persisted = JSON.parse(readFileSync(target, "utf-8"));
+                release();
             }
             catch {
-                // The atomic writer should make this rare. Preserve the existing
-                // behavior and overwrite malformed state with the caller's snapshot.
+                // A compromised/reaped lease must not mask the persistence result.
             }
         }
-        // A title is generated after the first run and may be merged while the
-        // next run still owns a state object loaded before that title existed.
-        // Preserve the newly persisted title when such a stale whole-state writer
-        // saves later; assigning title = undefined explicitly still clears it.
-        if (persisted?.title !== undefined && !("title" in state)) {
-            state.title = persisted.title;
+    }
+    acquireStateLock(target) {
+        const lockPath = `${target}.lock`;
+        for (let attempt = 0; attempt <= SESSION_STATE_LOCK_RETRY_DELAYS_MS.length; attempt++) {
+            if (!this.prepareLegacyStateLock(lockPath)) {
+                const delay = SESSION_STATE_LOCK_RETRY_DELAYS_MS[attempt];
+                if (delay === undefined)
+                    return undefined;
+                sleepSync(delay);
+                continue;
+            }
+            try {
+                return lockSync(target, {
+                    stale: SESSION_STATE_LOCK_STALE_MS,
+                    update: SESSION_STATE_LOCK_STALE_MS / 2,
+                    retries: 0,
+                    realpath: false,
+                });
+            }
+            catch (err) {
+                const code = err.code;
+                if (code !== "ELOCKED" && code !== "EEXIST")
+                    throw err;
+                const delay = SESSION_STATE_LOCK_RETRY_DELAYS_MS[attempt];
+                if (delay === undefined)
+                    return undefined;
+                sleepSync(delay);
+            }
         }
-        const terminal = newestGoalTerminal(state.goalTerminal, persisted?.goalTerminal);
-        if (terminal)
-            state.goalTerminal = terminal;
-        if (terminal && isSameGoalInstance(state.activeGoal, terminal)) {
-            const diskGoal = persisted?.activeGoal;
-            state.activeGoal = diskGoal && !isSameGoalInstance(diskGoal, terminal) ? diskGoal : undefined;
+        return undefined;
+    }
+    /** Recover only the old implementation's regular-file orphan lock. */
+    prepareLegacyStateLock(lockPath) {
+        if (!existsSync(lockPath))
+            return true;
+        let stat;
+        try {
+            stat = lstatSync(lockPath);
+        }
+        catch {
+            return true;
+        }
+        if (stat.isDirectory())
+            return true;
+        if (Date.now() - stat.mtimeMs <= SESSION_STATE_LOCK_STALE_MS)
+            return false;
+        try {
+            rmSync(lockPath, { force: true });
+            return true;
+        }
+        catch {
+            return false;
         }
-        const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
-        writeFileSync(tmp, JSON.stringify(state, null, 2), "utf-8");
-        renameSync(tmp, target);
-        return true;
+    }
+    readPersistedState(sessionId) {
+        const stateFile = join(this.sessionsDir, sessionId, "state.json");
+        if (!existsSync(stateFile)) {
+            throw new SessionError(`Session state file not found: ${sessionId}`);
+        }
+        try {
+            return hydrateGoalLifecycle(JSON.parse(readFileSync(stateFile, "utf-8")));
+        }
+        catch (err) {
+            throw new SessionError(`Session state is corrupt for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    rebaseLiveState(live, persisted) {
+        for (const key of Object.keys(live)) {
+            if (!(key in persisted))
+                delete live[key];
+        }
+        Object.assign(live, persisted);
     }
     generationKey(sessionId) {
         return `${this.sessionsDir}\0${sessionId}`;
@@ -598,7 +1298,10 @@ export class SessionManager {
         assertSafeSessionId(sourceSessionId);
         if (options.targetSessionId !== undefined)
             assertSafeSessionId(options.targetSessionId);
-        const snapshot = this.readForkSnapshot(sourceSessionId, options.throughEventId);
+        if (options.snapshotMode === "completed" && options.throughEventId !== undefined) {
+            throw new SessionError(`Completed snapshot cannot use an explicit fork cursor`);
+        }
+        const snapshot = this.readForkSnapshot(sourceSessionId, options.throughEventId, options.snapshotMode ?? "tail");
         const targetSessionId = options.targetSessionId ?? nanoid(16);
         const createdAt = Date.now();
         const lineage = {
@@ -610,11 +1313,70 @@ export class SessionManager {
             createdAt,
         };
         const state = buildForkState(snapshot.sourceState, targetSessionId, lineage, createdAt);
+        if (options.ephemeral === true)
+            state.ephemeral = true;
         const events = buildForkTranscript(snapshot.copiedEvents, state);
         const bundle = this.publishSessionAtomically(targetSessionId, state, events);
         return { bundle, lineage, copiedEventCount: snapshot.copiedEvents.length };
     }
-    readForkSnapshot(sourceSessionId, throughEventId) {
+    /** Freeze and validate an inclusive source range before any model call. */
+    selectContextPackage(sourceSessionId, range) {
+        assertSafeSessionId(sourceSessionId);
+        const transcriptFile = join(this.sessionsDir, sourceSessionId, "transcript.jsonl");
+        const stateFile = join(this.sessionsDir, sourceSessionId, "state.json");
+        if (!existsSync(stateFile))
+            throw new SessionError(`Session not found: ${sourceSessionId}`);
+        const parsed = Transcript.readEvents(transcriptFile);
+        if (parsed.malformedLineCount > 0) {
+            throw new SessionError(`Session transcript is malformed for ${sourceSessionId}: ${parsed.malformedLineCount} invalid line(s)`);
+        }
+        return Transcript.selectContextRange(parsed.events, range);
+    }
+    /** Publish a summary-only top-level fork after summarization has succeeded. */
+    createSummaryFork(sourceSessionId, options) {
+        assertSafeSessionId(sourceSessionId);
+        if (options.targetSessionId !== undefined)
+            assertSafeSessionId(options.targetSessionId);
+        if (!options.fromEventId || !options.toEventId) {
+            throw new SessionError("Summary fork requires a closed source event range");
+        }
+        if (!options.summary.trim())
+            throw new SessionError("Summary fork requires a non-empty summary");
+        const source = this.resume(sourceSessionId);
+        const targetSessionId = options.targetSessionId ?? nanoid(16);
+        const createdAt = Date.now();
+        const lineage = {
+            sessionId: sourceSessionId,
+            mode: "summary",
+            fromEventId: options.fromEventId,
+            throughEventId: options.toEventId,
+            sourceEventCount: options.sourceEventCount,
+            createdAt,
+        };
+        const state = buildForkState(source.state, targetSessionId, lineage, createdAt);
+        const [meta] = buildForkTranscript([], state);
+        const summaryEvent = {
+            id: nanoid(12),
+            type: "context_transfer",
+            timestamp: createdAt,
+            turnNumber: 0,
+            data: {
+                summary: options.summary,
+                sourceRange: {
+                    sessionId: sourceSessionId,
+                    fromEventId: options.fromEventId,
+                    toEventId: options.toEventId,
+                },
+                sourceEventCount: options.sourceEventCount,
+                estimatedTokens: options.estimatedTokens,
+                summaryVersion: 1,
+                summaryHash: createHash("sha256").update(options.summary).digest("hex"),
+            },
+        };
+        const bundle = this.publishSessionAtomically(targetSessionId, state, [meta, summaryEvent]);
+        return { bundle, lineage, copiedEventCount: 0 };
+    }
+    readForkSnapshot(sourceSessionId, throughEventId, snapshotMode) {
         const sessionDir = join(this.sessionsDir, sourceSessionId);
         const stateFile = join(sessionDir, "state.json");
         const transcriptFile = join(sessionDir, "transcript.jsonl");
@@ -633,12 +1395,26 @@ export class SessionManager {
         }
         const sourceEvents = structuredClone(parsed.events);
         let frozen = sourceEvents;
-        if (throughEventId !== undefined) {
+        const effectiveCursor = snapshotMode === "completed" ? sourceState.completedThroughEventId : throughEventId;
+        if (snapshotMode === "completed" && effectiveCursor === undefined) {
+            // Legacy sessions predate completedThroughEventId. Their tail is a safe
+            // completed snapshot only when the persisted lifecycle status says the
+            // last run completed naturally. A modern schema marker without a cursor
+            // means persistence was degraded, so even status=completed must not use
+            // the tail. Active/error/abort tails may be partial as well.
+            frozen =
+                sourceState.completedSnapshotVersion === undefined && sourceState.status === "completed"
+                    ? sourceEvents
+                    : [];
+        }
+        else if (effectiveCursor !== undefined) {
             const matches = sourceEvents
-                .map((event, index) => (event.id === throughEventId ? index : -1))
+                .map((event, index) => (event.id === effectiveCursor ? index : -1))
                 .filter((index) => index >= 0);
             if (matches.length !== 1) {
-                throw new SessionError(`Fork cursor must identify exactly one source event`);
+                throw new SessionError(snapshotMode === "completed"
+                    ? `Completed fork cursor must identify exactly one source event`
+                    : `Fork cursor must identify exactly one source event`);
             }
             const cursor = sourceEvents[matches[0]];
             if (cursor.type === "session_meta") {
@@ -687,11 +1463,16 @@ export class SessionManager {
                 rmSync(stagingDir, { recursive: true, force: true });
         }
     }
-    list(limit = 20) {
+    list(limit = 20, opts) {
         if (!existsSync(this.sessionsDir))
             return [];
+        // Extension-owned session kinds stay out of generic lists. Defaults to
+        // hiding "pet" so default-arg callers keep today's behavior.
+        // TODO(pet-out-of-core): drop the default once every caller passes the
+        // host's hidden-kind union explicitly.
+        const excludeKinds = opts?.excludeKinds ?? ["pet"];
         const dirs = readdirSync(this.sessionsDir, { withFileTypes: true })
-            .filter((d) => d.isDirectory() && !d.name.startsWith(".pending-"))
+            .filter((d) => d.isDirectory() && !d.name.startsWith(".pending-") && !d.name.startsWith("qchat-"))
             .map((d) => d.name);
         const candidates = [];
         for (const dir of dirs) {
@@ -718,11 +1499,17 @@ export class SessionManager {
             candidates.push({ dir, lastActiveAt, transcriptFile, stateFile, transcriptExists });
         }
         candidates.sort((a, b) => b.lastActiveAt - a.lastActiveAt);
-        const top = candidates.slice(0, limit);
         const sessions = [];
-        for (const c of top) {
+        for (const c of candidates) {
+            if (sessions.length >= limit)
+                break;
             try {
                 const state = JSON.parse(readFileSync(c.stateFile, "utf-8"));
+                if (isEphemeralSessionState(state))
+                    continue;
+                state.kind = normalizedSessionKind(state.kind);
+                if (excludeKinds.includes(state.kind))
+                    continue;
                 const preview = c.transcriptExists ? readLastUserMessage(c.transcriptFile) : undefined;
                 sessions.push({ ...state, preview, lastActiveAt: c.lastActiveAt });
             }
@@ -739,6 +1526,8 @@ export function buildForkState(source, targetSessionId, lineage, startedAt = Dat
         : { root: source.cwd, kind: "main" };
     return {
         sessionId: targetSessionId,
+        kind: "work",
+        stateRevision: 0,
         cwd: source.cwd,
         workspace,
         startedAt,
@@ -880,15 +1669,6 @@ function validateForkToolPairs(events) {
         throw new SessionError(`Fork tool metadata does not match provider history`);
     }
 }
-function newestGoalTerminal(incoming, persisted) {
-    if (!incoming)
-        return persisted;
-    if (!persisted)
-        return incoming;
-    const incomingAt = incoming.terminatedAtMs ?? Number.NEGATIVE_INFINITY;
-    const persistedAt = persisted.terminatedAtMs ?? Number.NEGATIVE_INFINITY;
-    return incomingAt > persistedAt ? incoming : persisted;
-}
 /**
  * Scan a transcript.jsonl for the LAST user message and return a short
  * preview, reading the file from the END in 64 KiB chunks.