@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/session.js

@@ -14,12 +14,22 @@
  */
 import { mkdir, open, readFile, readdir, stat, rename, unlink, rm } from 'fs/promises';
 import { existsSync } from 'fs';
-import { dirname, join, resolve } from 'path';
+import { basename, dirname, join, relative, resolve, sep } from 'path';
 import { homedir } from 'os';
 import { createHash } from 'crypto';
+import { parseEvidenceSnapshot } from './agent/runtime/evidence.js';
+import { mergeDiagnosticSnapshots, parseDiagnosticSnapshot } from './diagnostics/session_export.js';
+import { mergeUsageSnapshots, parseUsageSnapshot } from './usage_snapshot.js';
 import { writeFileAtomic } from './utils/atomic_write.js';
+import { withPathLock } from './utils/path_lock.js';
+import { prepareSessionMedia } from './session_media.js';
 import { stripEphemeralMessages } from './utils/ephemeral.js';
+import { stripEphemeralToolPayloads } from './utils/ephemeral_tools.js';
 import { activeProfile } from './config/profiles.js';
+import { retainSessionForProcess, retainedSessionIds, withSessionCleanupBarrier } from './session_ownership.js';
+import { admitTaskHandoff, canonicalHandoffCwd, deriveTaskHandoff, taskHandoffFingerprints, TaskHandoffAdmissionError } from './session_handoff.js';
+import { projectTaskHandoff } from './session_handoff_contract.js';
+import { admitBoardSessionBinding } from './board/binding.js';
 /**
  * Schema version for on-disk Session payloads.
  *
@@ -34,6 +44,18 @@ export const MAX_SESSION_FILE_BYTES = 4 * 1024 * 1024;
 function buildRuntimeMetadata(runtimeState, existingSession) {
     const metadata = {};
     const existingMetadata = existingSession?.metadata;
+    if (runtimeState && Object.prototype.hasOwnProperty.call(runtimeState, 'environment'))
+        metadata.environment = runtimeState.environment;
+    else if (existingMetadata?.environment !== undefined)
+        metadata.environment = existingMetadata.environment;
+    if (existingMetadata?.labels)
+        metadata.labels = { ...existingMetadata.labels };
+    const authMode = runtimeState?.authMode ?? existingMetadata?.authMode;
+    if (authMode)
+        metadata.authMode = authMode;
+    const routerOrigin = runtimeState?.routerOrigin ?? existingMetadata?.routerOrigin;
+    if (authMode !== 'direct' && routerOrigin)
+        metadata.routerOrigin = routerOrigin;
     const mode = runtimeState?.mode ?? existingMetadata?.mode;
     if (mode) {
         metadata.mode = mode;
@@ -83,15 +105,147 @@ function isSessionShape(value) {
         return false;
     if (typeof meta.id !== 'string' || !meta.id)
         return false;
+    if (meta.environment !== undefined && meta.environment !== null) {
+        if (typeof meta.environment !== 'object')
+            return false;
+        const environment = meta.environment;
+        if (typeof environment.id !== 'string' || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(environment.id)
+            || typeof environment.name !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(environment.name))
+            return false;
+    }
     if (!Array.isArray(v.messages))
         return false;
     return true;
 }
-function normalizeLoadedSession(session) {
+function admitSessionDiagnostics(value, path) {
+    const snapshot = parseDiagnosticSnapshot(value);
+    if (snapshot === null) {
+        throw new SessionLoadError(`Session file ${path} contains invalid or unsupported diagnostics`, 'diagnostics-invalid', path);
+    }
+    return snapshot;
+}
+function mergeSessionDiagnostics(runtimeState, existing, path) {
+    const prior = existing?.diagnostics === undefined ? undefined : admitSessionDiagnostics(existing.diagnostics, path);
+    const current = runtimeState?.diagnostics === undefined ? undefined : admitSessionDiagnostics(runtimeState.diagnostics, path);
+    if (current === undefined)
+        return prior;
+    if (prior === undefined)
+        return current;
+    try {
+        return mergeDiagnosticSnapshots(prior, current);
+    }
+    catch (error) {
+        throw new SessionLoadError(`Session file ${path} contains conflicting diagnostic identities`, 'diagnostics-invalid', path, error);
+    }
+}
+function normalizeLoadedSession(session, path) {
+    if (session.board_binding !== undefined) {
+        try {
+            session.board_binding = admitBoardSessionBinding(session.board_binding, session.metadata.id);
+        }
+        catch (error) {
+            throw new SessionLoadError('Invalid Zergboard session binding', 'board-binding-invalid', path, error);
+        }
+    }
+    if (session.evidence !== undefined) {
+        session.evidence = parseEvidenceSnapshot(session.evidence) ?? undefined;
+    }
+    if (session.diagnostics !== undefined)
+        session.diagnostics = admitSessionDiagnostics(session.diagnostics, path);
+    if (session.usage !== undefined)
+        session.usage = admitSessionUsage(session.usage, path);
     session.messages = stripEphemeralMessages(session.messages);
+    // Admit the complete saved payload before normalizing display-only clocks.
+    // A changed execution source must never be repaired by rehashing it.
+    if (session.task_handoff !== undefined)
+        session.task_handoff = admitTaskHandoff(session.task_handoff, session);
+    const savedAt = Date.parse(session.metadata.updatedAt);
+    session.messages = stripEphemeralMessages(session.messages).map(message => {
+        const turn = message.turn;
+        if (!turn)
+            return message;
+        if (typeof turn.id !== 'string' || !Number.isFinite(turn.startedAt)
+            || !Number.isFinite(turn.tokens) || turn.tokens < 0 || typeof turn.estimated !== 'boolean'
+            || (turn.finishedAt !== undefined && !Number.isFinite(turn.finishedAt))) {
+            return { ...message, turn: undefined };
+        }
+        if (turn.finishedAt !== undefined)
+            return message;
+        // A saved snapshot is history: a crashed process cannot keep its clock live.
+        return { ...message, turn: Number.isFinite(savedAt) ? { ...turn, finishedAt: Math.max(turn.startedAt, savedAt) } : undefined };
+    });
     session.metadata.messageCount = session.messages.length;
+    if (session.task_handoff !== undefined) {
+        session.task_handoff = { ...session.task_handoff, source: {
+                ...session.task_handoff.source, ...taskHandoffFingerprints(session),
+            } };
+    }
+    if (isCompactionTitle(session.metadata.title)) {
+        session.metadata.title = deriveSessionTitle(session.messages);
+    }
     return session;
 }
+function admitSessionUsage(value, path) {
+    const snapshot = parseUsageSnapshot(value);
+    if (snapshot === null) {
+        throw new SessionLoadError(`Session file ${path} contains invalid or unsupported usage`, 'usage-invalid', path);
+    }
+    return snapshot;
+}
+function mergeSessionUsage(runtimeState, existing, path) {
+    const prior = existing?.usage === undefined ? undefined : admitSessionUsage(existing.usage, path);
+    const current = runtimeState?.usage === undefined ? undefined : admitSessionUsage(runtimeState.usage, path);
+    if (current === undefined)
+        return prior;
+    if (prior === undefined)
+        return current;
+    // A conflicting logical-call identity is a caller error, not a replaceable observation.
+    return mergeUsageSnapshots(prior, current);
+}
+function isCompactionTitle(title) {
+    // Includes the truncated 50-character title written by older versions.
+    return typeof title === 'string' && title.startsWith('[Conversation summary');
+}
+/** Recover only the explicit original-user record in the local summary format. */
+function titleFromCompactedStart(content, depth = 0) {
+    if (depth >= 8)
+        return undefined;
+    const record = /\*\*Conversation start\*\*\r?\n([^\r\n]+)/.exec(content)?.[1];
+    if (!record)
+        return undefined;
+    try {
+        const parsed = JSON.parse(record);
+        if (!isPlainJsonObject(parsed) || parsed.role !== 'user' || typeof parsed.content !== 'string')
+            return undefined;
+        return isCompactionTitle(parsed.content)
+            ? titleFromCompactedStart(parsed.content, depth + 1)
+            : parsed.content.slice(0, 50) || undefined;
+    }
+    catch {
+        // A bounded summary may have elided this record. Use surviving dialogue.
+        return undefined;
+    }
+}
+/** Session identity belongs to the original request, not a summary carrier. */
+function deriveSessionTitle(messages, previousTitle) {
+    if (typeof previousTitle === 'string' && previousTitle && previousTitle !== 'Untitled session' && previousTitle !== 'Untitled'
+        && !isCompactionTitle(previousTitle))
+        return previousTitle;
+    for (const message of messages) {
+        if (message.role !== 'user' || typeof message.content !== 'string'
+            || message.metadata?.ephemeral || message.metadata?.toolResult)
+            continue;
+        if (message.metadata?.compactionSummary === true || isCompactionTitle(message.content)) {
+            const recovered = titleFromCompactedStart(message.content);
+            if (recovered)
+                return recovered;
+        }
+        else if (message.content) {
+            return message.content.slice(0, 50);
+        }
+    }
+    return 'Untitled session';
+}
 export const COLONY_WORKTREE_MARKER = '.colony-worktree.json';
 /**
  * Bounded prefix read for session heads.
@@ -264,6 +418,7 @@ function summaryFromHeadMetadata(metadata, entry) {
         cwd: typeof metadata.cwd === 'string' ? metadata.cwd : '',
         title: typeof metadata.title === 'string' && metadata.title ? metadata.title : 'Untitled',
         ...(typeof metadata.name === 'string' && metadata.name ? { name: metadata.name } : {}),
+        ...(metadata.labels && typeof metadata.labels === 'object' ? { labels: metadata.labels } : {}),
         messageCount,
         updatedAt: typeof metadata.updatedAt === 'string'
             ? metadata.updatedAt
@@ -391,6 +546,13 @@ export function getToolResponsesDir(projectHash, sessionId) {
 function getSessionDirForStorage(storage, sessionId) {
     return join(storage.sessionDir, sessionId);
 }
+function getSessionCoordinationDirectory(storage) {
+    // Legacy colony transcripts are readable in the worktree, but new runtime
+    // metadata belongs in global colony storage, like new chat and mux data.
+    return storage.kind === 'legacy-colony'
+        ? makeGlobalColonyStorage(storage.projectHash).sessionDir
+        : storage.sessionDir;
+}
 function getSessionJsonPath(storage, sessionId) {
     return join(getSessionDirForStorage(storage, sessionId), 'session.json');
 }
@@ -421,7 +583,7 @@ async function ensureSessionDir(projectHash, sessionId) {
 }
 async function readSessionJson(path, muxStatePath) {
     try {
-        const session = await loadSessionFromFile(path);
+        const session = await loadSessionFromFile(path, false);
         if (!session)
             return null;
         if (muxStatePath && existsSync(muxStatePath)) {
@@ -435,7 +597,9 @@ async function readSessionJson(path, muxStatePath) {
         }
         return session;
     }
-    catch {
+    catch (error) {
+        if (error instanceof SessionLoadError && (error.reason.startsWith('handoff-') || error.reason === 'diagnostics-invalid' || error.reason === 'usage-invalid' || error.reason === 'board-binding-invalid'))
+            throw error;
         return null;
     }
 }
@@ -443,8 +607,62 @@ async function readSessionJson(path, muxStatePath) {
  * Atomic session write: pretty-JSON-encode `session` to a temp file and rename
  * into place. A crash mid-write never leaves the canonical session truncated.
  */
-async function writeSessionAtomic(path, session) {
-    await writeFileAtomic(path, JSON.stringify(session, null, 2));
+async function writeSessionAtomic(path, session, signal) {
+    const checkpoint = JSON.stringify(session, null, 2);
+    await writeFileAtomic(path, checkpoint, { signal });
+}
+async function writeSessionWithMedia(path, session, runtimeState, existingSession, signal) {
+    await withPathLock(path, async () => {
+        signal?.throwIfAborted();
+        // An autosave may have captured messages before a board request yielded.
+        // Merge the latest binding while holding the same canonical-file lock.
+        let latest = null;
+        try {
+            latest = await loadSessionFromFile(path, false);
+        }
+        catch (error) {
+            if (!(error instanceof SessionLoadError) || error.reason === 'board-binding-invalid')
+                throw error;
+            // Preserve existing writer recovery of previously unreadable checkpoints.
+        }
+        if (latest?.metadata.id === session.metadata.id)
+            session.board_binding = latest.board_binding;
+        session.messages = stripEphemeralToolPayloads(session.messages, runtimeState?.ephemeralToolNames, runtimeState?.ephemeralToolRules);
+        const media = await prepareSessionMedia({ sessionFile: resolve(path), sessionId: session.metadata.id, messages: session.messages });
+        try {
+            session.messages = media.messages;
+            // Task identity and consumed Clear events must come from the same admitted
+            // predecessor. A save prepared before the lock can have an older capture.
+            const predecessor = latest ?? existingSession;
+            session.task_handoff = deriveTaskHandoff(session, runtimeState?.taskHandoffInput, predecessor?.task_handoff, predecessor?.messages) ?? undefined;
+            await writeSessionAtomic(path, session, signal);
+            // Dedicated mux persistence runs afterward; it must never roll back
+            // image bytes that this canonical checkpoint already owns.
+            media.markCommitted();
+        }
+        finally {
+            await media.rollback();
+        }
+    });
+}
+/** Compare-and-set the association without rewriting captured chat/media state. */
+export async function updateSessionBoardBinding(path, sessionId, expected, next) {
+    await withPathLock(path, async () => {
+        const session = await loadSessionFromFile(path, false);
+        if (!session || session.metadata.id !== sessionId)
+            throw new Error('Zergboard requires the current saved session checkpoint');
+        const admittedExpected = expected === undefined ? undefined : admitBoardSessionBinding(expected, sessionId);
+        if (JSON.stringify(session.board_binding) !== JSON.stringify(admittedExpected))
+            throw new Error('Zergboard session association changed; reload before retrying');
+        if (next === undefined)
+            delete session.board_binding;
+        else
+            session.board_binding = admitBoardSessionBinding(next, sessionId);
+        const text = JSON.stringify(session, null, 2);
+        if (Buffer.byteLength(text) > MAX_SESSION_FILE_BYTES)
+            throw new Error('Zergboard checkpoint exceeds the session size limit; export evidence to a file instead');
+        await writeSessionAtomic(path, session);
+    });
 }
 /**
  * Migrate a legacy flat `{sessionId}.json` into the directory layout.
@@ -479,8 +697,11 @@ async function migrateLegacyFlatFile(storage, sessionId) {
         return false;
     }
 }
-async function loadSessionFromStorage(storage, sessionId) {
+async function loadSessionFromStorage(storage, sessionId, retain = true) {
     const sessionPath = getSessionJsonPath(storage, sessionId);
+    if (retain && (existsSync(sessionPath) || existsSync(getLegacyFlatPath(storage, sessionId)))) {
+        await retainSessionForProcess(getSessionCoordinationDirectory(storage), sessionId);
+    }
     const muxStatePath = getMuxStateFilePath(storage, sessionId);
     const session = await readSessionJson(sessionPath, muxStatePath);
     if (session)
@@ -533,8 +754,14 @@ async function listSessionEntries(storage) {
 }
 async function readSessionSummaryEntry(entry, maxFileBytes) {
     const head = await readSessionHeadSummary(entry);
-    if (head.kind === 'summary')
-        return head.summary;
+    if (head.kind === 'summary') {
+        if (!isCompactionTitle(head.summary.title))
+            return head.summary;
+        // Repair old titles for display without rewriting another session's file.
+        // Keep oversized entries visible even when their transcript cannot be read.
+        return await readSessionSummaryFromFullParse(entry, maxFileBytes)
+            ?? { ...head.summary, title: 'Untitled session' };
+    }
     if (head.kind === 'excluded')
         return null;
     return readSessionSummaryFromFullParse(entry, maxFileBytes);
@@ -567,13 +794,14 @@ async function readSessionSummaryFromFullParse(entry, maxFileBytes) {
             if (typeof parsed.schemaVersion === 'number' && parsed.schemaVersion > SESSION_SCHEMA_VERSION) {
                 return null;
             }
-            const session = normalizeLoadedSession(parsed);
+            const session = normalizeLoadedSession(parsed, entry.path);
             const metadata = session.metadata;
             return {
                 id: metadata.id,
                 cwd: typeof metadata.cwd === 'string' ? metadata.cwd : '',
                 title: typeof metadata.title === 'string' && metadata.title ? metadata.title : 'Untitled',
                 ...(typeof metadata.name === 'string' && metadata.name ? { name: metadata.name } : {}),
+                ...(metadata.labels && typeof metadata.labels === 'object' ? { labels: metadata.labels } : {}),
                 messageCount: session.messages.length,
                 updatedAt: typeof metadata.updatedAt === 'string'
                     ? metadata.updatedAt
@@ -620,6 +848,149 @@ export async function findRecentSessionSummary(cwd, options = {}) {
     }
     return undefined;
 }
+/**
+ * Inspect a bounded same-project window and offer exact, validated checkpoints.
+ * Metadata inspection is bounded to 128 heads and, for canonical alias recovery,
+ * 128 project directories. File mtime orders the selected window; checkpoint
+ * as-of and session ID determine offer ordering. This is not a complete history
+ * search. Selection never imports a task or asserts liveness.
+ */
+export async function findSessionHandoffOffers(cwd, options = {}) {
+    const limit = options.maxCandidates ?? 16;
+    if (!Number.isSafeInteger(limit) || limit < 0 || limit > 16)
+        throw new RangeError('Handoff candidate limit must be an integer from 0 to 16.');
+    if (limit === 0)
+        return [];
+    const canonicalCwd = canonicalHandoffCwd(cwd);
+    const entries = [];
+    const seenPaths = new Set();
+    const offeredSessionIds = new Set();
+    const storageDirectories = new Set();
+    const storages = [...getStorageCandidates(cwd), ...getStorageCandidates(canonicalCwd)]
+        .filter(storage => {
+        if (storageDirectories.has(storage.sessionDir))
+            return false;
+        storageDirectories.add(storage.sessionDir);
+        return true;
+    });
+    for (const storage of storages)
+        for (const entry of await listSessionEntries(storage)) {
+            if (entry.sessionId === options.excludeSessionId || entry.size >= MAX_SESSION_FILE_BYTES)
+                continue;
+            entries.push(entry);
+        }
+    const order = (a, b) => b.mtimeMs - a.mtimeMs || a.sessionId.localeCompare(b.sessionId) || a.path.localeCompare(b.path);
+    entries.sort(order);
+    const offers = [];
+    let headReads = 0;
+    let fullReads = 0;
+    const inspect = async (entry) => {
+        if (headReads >= 128 || fullReads >= limit || seenPaths.has(entry.path) || offeredSessionIds.has(entry.sessionId)
+            || entry.sessionId === options.excludeSessionId || entry.size >= MAX_SESSION_FILE_BYTES)
+            return;
+        seenPaths.add(entry.path);
+        headReads += 1;
+        try {
+            const handle = await open(entry.path, 'r');
+            let session;
+            try {
+                const current = await handle.stat();
+                if (!current.isFile() || current.size >= MAX_SESSION_FILE_BYTES)
+                    return;
+                const head = Buffer.alloc(Math.min(current.size, SESSION_HEAD_MAX_BYTES));
+                const read = await handle.read(head, 0, head.length, 0);
+                const text = head.subarray(0, read.bytesRead).toString('utf8');
+                // Current writers put this bounded object before messages; old or
+                // incomplete payloads are not guessed from conversation prose.
+                const handoffText = extractTopLevelJsonObject(text, 'task_handoff');
+                const metadataText = extractTopLevelJsonObject(text, 'metadata');
+                if (!handoffText || !metadataText)
+                    return;
+                const metadata = JSON.parse(metadataText);
+                if (metadata.id !== entry.sessionId || typeof metadata.cwd !== 'string' || canonicalHandoffCwd(metadata.cwd) !== canonicalCwd)
+                    return;
+                fullReads += 1;
+                const buffer = Buffer.alloc(current.size + 1);
+                let count = 0;
+                while (count < buffer.length) {
+                    const chunk = await handle.read(buffer, count, buffer.length - count, count);
+                    if (chunk.bytesRead === 0)
+                        break;
+                    count += chunk.bytesRead;
+                }
+                if (count !== current.size)
+                    return;
+                const raw = JSON.parse(buffer.subarray(0, count).toString('utf8'));
+                if (!isSessionShape(raw) || (typeof raw.schemaVersion === 'number' && raw.schemaVersion > SESSION_SCHEMA_VERSION))
+                    return;
+                session = normalizeLoadedSession(raw, entry.path);
+            }
+            finally {
+                await handle.close();
+            }
+            if (!session.task_handoff || session.task_handoff.taskStatus === 'complete')
+                return;
+            offeredSessionIds.add(entry.sessionId);
+            offers.push(projectTaskHandoff(session.task_handoff));
+        }
+        catch (error) {
+            if (error instanceof TaskHandoffAdmissionError || error instanceof SyntaxError || error.code === 'ENOENT')
+                return;
+            // Unreadable candidates cannot be offered; the explicit load path still
+            // raises its source-specific diagnostic without rewriting the file.
+            if (['EACCES', 'EPERM', 'EISDIR'].includes(error.code ?? ''))
+                return;
+            throw error;
+        }
+    };
+    for (const entry of entries.slice(0, limit))
+        await inspect(entry);
+    if (offers.length === 0 && fullReads < limit) {
+        // Older saves used lexical project hashes. A different alias cannot derive
+        // that hash, so inspect a small deterministic directory window and require
+        // exact canonical cwd association before admitting any complete payload.
+        const roots = [{ root: getGlobalSessionsRoot(), colony: false }];
+        if (storages.some(storage => storage.kind === 'colony'))
+            roots.push({ root: join(getGlobalColonyRoot(), 'worktrees'), colony: true });
+        const projects = [];
+        for (const location of roots) {
+            try {
+                for (const project of await readdir(location.root, { withFileTypes: true })) {
+                    if (!project.isDirectory())
+                        continue;
+                    projects.push({ storage: location.colony ? makeGlobalColonyStorage(project.name) : makeGlobalStorage(project.name), key: `${location.root}/${project.name}` });
+                }
+            }
+            catch (error) {
+                if (!['ENOENT', 'EACCES', 'EPERM'].includes(error.code ?? ''))
+                    throw error;
+            }
+        }
+        projects.sort((a, b) => a.key.localeCompare(b.key));
+        const candidates = [];
+        for (const project of projects.slice(0, 128)) {
+            if (candidates.length >= 128)
+                break;
+            try {
+                const names = await readdir(project.storage.sessionDir, { withFileTypes: true });
+                names.sort((a, b) => a.name.localeCompare(b.name));
+                for (const name of names.slice(0, 128 - candidates.length)) {
+                    const entry = await resolveSessionEntry(project.storage, name);
+                    if (entry)
+                        candidates.push(entry);
+                }
+            }
+            catch (error) {
+                if (!['ENOENT', 'EACCES', 'EPERM', 'ENOTDIR'].includes(error.code ?? ''))
+                    throw error;
+            }
+        }
+        candidates.sort(order);
+        for (const entry of candidates)
+            await inspect(entry);
+    }
+    return offers.sort((a, b) => b.asOf.localeCompare(a.asOf) || a.snapshot.source.sessionId.localeCompare(b.snapshot.source.sessionId));
+}
 export function getSessionDirForCwd(cwd) {
     return getStorageCandidates(cwd)[0].sessionDir;
 }
@@ -650,32 +1021,56 @@ export function getMuxStatePathForCwd(cwd, sessionId) {
  * ~/.ztc/colony/worktrees; normal projects bind to ~/.ztc/sessions.
  */
 export async function bindToolResponseStoreToSession(store, discovered, cwd, sessionId, config, sessionFile) {
+    const invalidateRestoredCoverage = () => {
+        const coverage = store.evidence.getSnapshot().verificationCoverage;
+        if (coverage?.length)
+            store.evidence.setVerificationCoverage(coverage.map(projection => ({
+                ...projection, source_id: null, applicability: 'unknown',
+                reason: 'Restored source applicability is historical; a fresh admitted host check is required.',
+            })));
+    };
+    const restoreExportedEvidence = async (path) => {
+        const session = await loadSessionFromFile(path, false);
+        const exported = session?.evidence;
+        if (!exported || exported.revision <= store.evidence.getSnapshot().revision)
+            return;
+        store.evidence.restore(exported);
+        for (const record of exported.records) {
+            if (record.kind === 'observation' && !store.getMeta(record.source.toolCallId ?? record.id)) {
+                store.evidence.setAvailability(record.id, 'unavailable');
+            }
+        }
+    };
     if (config)
         store.setConfig(config);
     if (sessionFile) {
         const dir = join(dirname(sessionFile), `${sessionId}.tool_responses`);
         await mkdir(dir, { recursive: true });
         await store.setSessionDir(dir);
+        await restoreExportedEvidence(sessionFile);
+        invalidateRestoredCoverage();
         discovered.clear();
         return;
     }
     const storage = getStorageCandidates(cwd)[0];
+    await retainSessionForProcess(getSessionCoordinationDirectory(storage), sessionId);
     await ensureSessionStorage(storage, sessionId);
     await store.setSessionDir(getToolResponsesDirForStorage(storage, sessionId));
+    await restoreExportedEvidence(getSessionJsonPath(storage, sessionId));
+    invalidateRestoredCoverage();
     discovered.clear();
 }
-export async function saveSession(sessionId, cwd, messages, model, provider, muxState, paneSpecs, runtimeState, hostedSettings) {
+export async function saveSession(sessionId, cwd, messages, model, provider, muxState, paneSpecs, runtimeState, hostedSettings, signal) {
     const storage = getStorageCandidates(cwd)[0];
+    await retainSessionForProcess(getSessionCoordinationDirectory(storage), sessionId);
     await ensureSessionStorage(storage, sessionId);
     const sessionPath = getSessionJsonPath(storage, sessionId);
     const existingSession = await loadSessionById(sessionId, cwd);
-    const firstUserMsg = messages.find((message) => message.role === 'user');
-    const title = firstUserMsg?.content?.slice(0, 50) || existingSession?.metadata.title || 'Untitled session';
-    // Preserve user-set name across re-saves. saveSession is called every turn
-    // and re-derives `title` from the latest first-user-message; `name` is the
-    // opposite — set explicitly via /rename and must NOT be clobbered here.
+    const title = deriveSessionTitle(messages, existingSession?.metadata.title);
+    // User-set names remain independently controlled by /rename.
     const session = {
         schemaVersion: SESSION_SCHEMA_VERSION,
+        evidence: runtimeState?.evidence ?? existingSession?.evidence,
         metadata: {
             id: sessionId,
             projectHash: storage.projectHash,
@@ -690,12 +1085,15 @@ export async function saveSession(sessionId, cwd, messages, model, provider, mux
             ...(existingSession?.metadata.name ? { name: existingSession.metadata.name } : {}),
             ...buildRuntimeMetadata(runtimeState, existingSession),
         },
-        messages,
+        diagnostics: mergeSessionDiagnostics(runtimeState, existingSession, sessionPath),
+        usage: mergeSessionUsage(runtimeState, existingSession, sessionPath),
+        task_handoff: undefined,
+        messages: stripEphemeralMessages(messages),
         mux_state: muxState,
         pane_specs: paneSpecs,
         hosted_settings: hostedSettings ?? existingSession?.hosted_settings,
     };
-    await writeSessionAtomic(sessionPath, session);
+    await writeSessionWithMedia(sessionPath, session, runtimeState, existingSession, signal);
     const muxStatePath = getMuxStateFilePath(storage, sessionId);
     if (muxStatePath) {
         if (muxState) {
@@ -713,11 +1111,39 @@ export async function saveSession(sessionId, cwd, messages, model, provider, mux
 export async function loadSession(projectHash, sessionId) {
     return loadSessionFromStorage(makeGlobalStorage(projectHash), sessionId);
 }
-/**
- * Load a session from an arbitrary file path (bypasses the ~/.ztc/sessions tree).
- * Used by embedders that manage session storage themselves.
- */
-export async function loadSessionFromFile(path) {
+/** Retain explicit file loads only when the path belongs to managed storage. */
+async function retainManagedSessionFile(path) {
+    const absolute = resolve(path);
+    const candidates = [
+        { root: getGlobalSessionsRoot(), colony: false },
+        { root: join(getGlobalColonyRoot(), 'worktrees'), colony: true },
+    ];
+    for (const { root, colony } of candidates) {
+        const parts = relative(resolve(root), absolute).split(sep);
+        if (parts[0] === '..' || (colony && parts[1] !== 'sessions'))
+            continue;
+        const prefix = colony ? 2 : 1;
+        const storage = join(root, ...parts.slice(0, prefix));
+        if (parts.length === prefix + 2 && parts[prefix + 1] === 'session.json') {
+            await retainSessionForProcess(storage, parts[prefix]);
+            return;
+        }
+        if (parts.length === prefix + 1 && parts[prefix].endsWith('.json')) {
+            await retainSessionForProcess(storage, parts[prefix].slice(0, -5));
+            return;
+        }
+    }
+    const storage = basename(absolute) === 'session.json' ? dirname(dirname(absolute)) : dirname(absolute);
+    if (basename(storage) === 'sessions' && basename(dirname(storage)) === '.colony'
+        && (basename(absolute) === 'session.json' || absolute.endsWith('.json'))) {
+        const id = basename(absolute) === 'session.json' ? basename(dirname(absolute)) : basename(absolute, '.json');
+        await retainSessionForProcess(makeGlobalColonyStorage(getProjectHash(dirname(dirname(storage)))).sessionDir, id);
+    }
+}
+/** Load a managed session or an arbitrary file owned by an embedder. */
+export async function loadSessionFromFile(path, retain = true) {
+    if (retain && existsSync(path))
+        await retainManagedSessionFile(path);
     let content;
     try {
         content = await readFile(path, 'utf-8');
@@ -743,15 +1169,22 @@ export async function loadSessionFromFile(path) {
     if (declaredVersion > SESSION_SCHEMA_VERSION) {
         throw new SessionLoadError(`Session file ${path} declares schemaVersion=${declaredVersion}; this ZTC build only understands up to v${SESSION_SCHEMA_VERSION}`, 'schema-mismatch', path);
     }
-    return normalizeLoadedSession(parsed);
+    try {
+        return normalizeLoadedSession(parsed, path);
+    }
+    catch (error) {
+        if (!(error instanceof TaskHandoffAdmissionError))
+            throw error;
+        const reason = error.reason === 'handoff_fingerprint_mismatch' ? 'handoff-source-mismatch'
+            : error.reason === 'unsupported_handoff_version' ? 'handoff-schema-mismatch' : 'handoff-invalid';
+        throw new SessionLoadError(error.message, reason, path, error);
+    }
 }
 /**
  * Save a session to an arbitrary file path (bypasses the ~/.ztc/sessions tree).
  */
-export async function saveSessionToFile(path, sessionId, cwd, messages, model, provider, muxState, paneSpecs, runtimeState, hostedSettings) {
+export async function saveSessionToFile(path, sessionId, cwd, messages, model, provider, muxState, paneSpecs, runtimeState, hostedSettings, signal) {
     const projectHash = getProjectHash(cwd);
-    const firstUserMsg = messages.find(m => m.role === 'user');
-    const title = firstUserMsg?.content?.slice(0, 50) || 'Untitled session';
     let createdAt = new Date().toISOString();
     let preservedName;
     let existingSession = null;
@@ -765,12 +1198,16 @@ export async function saveSessionToFile(path, sessionId, cwd, messages, model, p
                 preservedName = existingSession.metadata.name;
             }
         }
-        catch {
+        catch (error) {
+            if (error instanceof SessionLoadError && (error.reason.startsWith('handoff-') || error.reason === 'diagnostics-invalid' || error.reason === 'usage-invalid' || error.reason === 'board-binding-invalid'))
+                throw error;
             // Existing file is broken; proceed with fresh createdAt.
         }
     }
+    const title = deriveSessionTitle(messages, existingSession?.metadata.title);
     const session = {
         schemaVersion: SESSION_SCHEMA_VERSION,
+        evidence: runtimeState?.evidence ?? existingSession?.evidence,
         metadata: {
             id: sessionId,
             projectHash,
@@ -785,7 +1222,10 @@ export async function saveSessionToFile(path, sessionId, cwd, messages, model, p
             ...(preservedName ? { name: preservedName } : {}),
             ...buildRuntimeMetadata(runtimeState, existingSession),
         },
-        messages,
+        diagnostics: mergeSessionDiagnostics(runtimeState, existingSession, path),
+        usage: mergeSessionUsage(runtimeState, existingSession, path),
+        task_handoff: undefined,
+        messages: stripEphemeralMessages(messages),
         mux_state: muxState,
         pane_specs: paneSpecs,
         hosted_settings: hostedSettings ?? existingSession?.hosted_settings,
@@ -794,7 +1234,7 @@ export async function saveSessionToFile(path, sessionId, cwd, messages, model, p
     if (dir && dir !== '.' && !existsSync(dir)) {
         await mkdir(dir, { recursive: true });
     }
-    await writeSessionAtomic(path, session);
+    await writeSessionWithMedia(path, session, runtimeState, existingSession, signal);
     return path;
 }
 export async function saveMuxStateOnly(sessionId, cwd, muxState) {
@@ -802,6 +1242,7 @@ export async function saveMuxStateOnly(sessionId, cwd, muxState) {
     await ensureSessionStorage(storage);
     const muxStatePath = getMuxStateFilePath(storage, sessionId);
     if (muxStatePath) {
+        await retainSessionForProcess(getSessionCoordinationDirectory(storage), sessionId);
         await writeFileAtomic(muxStatePath, JSON.stringify(muxState, null, 2));
         return true;
     }
@@ -894,7 +1335,7 @@ export async function loadSessionByIdOrName(idOrName, cwd) {
             if (head.kind === 'excluded')
                 return null;
             if (head.kind === 'unknown') {
-                const session = await loadSessionFromStorage(entry.storage, entry.sessionId);
+                const session = await loadSessionFromStorage(entry.storage, entry.sessionId, false);
                 return session?.metadata.name === idOrName ? entry : null;
             }
             const name = head.kind === 'summary' ? head.summary.name : head.name;
@@ -952,6 +1393,7 @@ export async function setSessionName(sessionId, cwd, name, defaults) {
         metadata: {
             ...session.metadata,
             updatedAt: new Date().toISOString(),
+            labels: { ...session.metadata.labels, updated_at_ms: Math.max(Date.now(), (session.metadata.labels?.updated_at_ms ?? 0) + 1) },
             ...(trimmed ? { name: trimmed } : { name: undefined }),
         },
     };
@@ -963,6 +1405,25 @@ export async function setSessionName(sessionId, cwd, name, defaults) {
     await writeSessionAtomic(path, updated);
     return updated;
 }
+/** Atomically persist label choices; metadata.name remains the resume-name owner. */
+export async function setSessionLabels(sessionId, cwd, labels, defaults) {
+    const storage = getStorageCandidates(cwd)[0];
+    let session = await loadSessionFromStorage(storage, sessionId);
+    if (!session) {
+        await saveSession(sessionId, cwd, [], defaults.model, defaults.provider);
+        session = await loadSessionFromStorage(storage, sessionId);
+    }
+    if (!session)
+        throw new Error(`Unable to create session ${sessionId}`);
+    const { manual_title, ...preferences } = labels;
+    const updated = { ...session, metadata: { ...session.metadata,
+            labels: { ...preferences, updated_at_ms: Math.max(Date.now(), (preferences.updated_at_ms ?? 0) + 1) }, name: manual_title || undefined, updatedAt: new Date().toISOString(),
+        } };
+    if (!manual_title)
+        delete updated.metadata.name;
+    await writeSessionAtomic(getSessionJsonPath(storage, sessionId), updated);
+    return updated;
+}
 /**
  * List all sessions for a project
  */
@@ -990,11 +1451,11 @@ export async function listSessions(cwd) {
  */
 async function readSessionSummaryForListing(entry) {
     const head = await readSessionHead(entry);
-    if (head.kind === 'summary')
+    if (head.kind === 'summary' && !isCompactionTitle(head.summary.title))
         return head.summary;
     if (head.kind === 'excluded')
         return null;
-    const session = await loadSessionFromStorage(entry.storage, entry.sessionId);
+    const session = await loadSessionFromStorage(entry.storage, entry.sessionId, false);
     if (!session)
         return null;
     return {
@@ -1002,6 +1463,7 @@ async function readSessionSummaryForListing(entry) {
         cwd: session.metadata.cwd,
         title: session.metadata.title || 'Untitled',
         ...(session.metadata.name ? { name: session.metadata.name } : {}),
+        ...(session.metadata.labels ? { labels: session.metadata.labels } : {}),
         messageCount: session.metadata.messageCount,
         updatedAt: session.metadata.updatedAt,
     };
@@ -1155,17 +1617,60 @@ export async function listAllSessions(options = {}) {
     }
     return collectCatalogEntries(storages, options);
 }
-export async function cleanupOldSessions(cwd, keepCount = 10) {
-    const sessions = await listSessions(cwd);
-    if (sessions.length <= keepCount) {
+/** Protect the current session even before its first save. */
+export async function retainCurrentSession(cwd, sessionId) {
+    const storage = getStorageCandidates(cwd)[0];
+    await retainSessionForProcess(getSessionCoordinationDirectory(storage), sessionId);
+}
+/** Opt-in retention of unowned, unnamed sessions; null disables pruning. */
+export async function cleanupOldSessions(cwd, keepCount = null) {
+    if (keepCount === null)
         return 0;
+    if (!Number.isSafeInteger(keepCount) || keepCount < 0) {
+        throw new RangeError('Session retention count must be a non-negative safe integer or null.');
     }
-    const toDelete = sessions.slice(keepCount);
-    let deleted = 0;
-    for (const session of toDelete) {
-        if (await deleteSession(cwd, session.id)) {
-            deleted++;
+    const storages = getStorageCandidates(cwd);
+    // Publish barriers in every visible storage before listing or selecting IDs.
+    const protectedCleanup = async (index) => {
+        if (index < storages.length) {
+            return withSessionCleanupBarrier(getSessionCoordinationDirectory(storages[index]), () => protectedCleanup(index + 1));
         }
-    }
-    return deleted;
+        const owned = new Set();
+        for (const storage of storages) {
+            for (const id of await retainedSessionIds(getSessionCoordinationDirectory(storage)))
+                owned.add(id);
+        }
+        const sessions = await listSessions(cwd);
+        const candidates = sessions.filter(session => !session.name && !owned.has(session.id));
+        let deleted = 0;
+        for (const session of candidates.slice(keepCount)) {
+            // An owner may publish its pin while waiting on our barrier. Recheck it
+            // and the name immediately before pruning, retaining uncertainty.
+            let protectedNow = false;
+            for (const storage of storages) {
+                if ((await retainedSessionIds(getSessionCoordinationDirectory(storage))).has(session.id))
+                    protectedNow = true;
+                for (const path of [getSessionJsonPath(storage, session.id), getLegacyFlatPath(storage, session.id)]) {
+                    let currentStat;
+                    try {
+                        currentStat = await stat(path);
+                    }
+                    catch (error) {
+                        if (error.code === 'ENOENT')
+                            continue;
+                        throw error;
+                    }
+                    const current = await readSessionSummaryForListing({
+                        storage, sessionId: session.id, path, mtimeMs: currentStat.mtimeMs, size: currentStat.size,
+                    });
+                    if (!current || current.name)
+                        protectedNow = true;
+                }
+            }
+            if (!protectedNow && await deleteSession(cwd, session.id))
+                deleted++;
+        }
+        return deleted;
+    };
+    return protectedCleanup(0);
 }