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

package/dist/session_media.d.ts

@@ -0,0 +1,41 @@
+import type { Message, MessageAttachment } from './types.js';
+export declare const SESSION_MEDIA_LIMITS: Readonly<{
+    imageBytes: number;
+    sessionBytes: number;
+    assetCount: 128;
+    /** Bound standalone pane-input metadata, not a session's text transcript. */
+    checkpointBytes: number;
+}>;
+export type SessionMediaErrorCode = 'invalid_reference' | 'unavailable' | 'quota_exceeded' | 'write_failed';
+export declare class SessionMediaError extends Error {
+    readonly code: SessionMediaErrorCode;
+    constructor(code: SessionMediaErrorCode, message: string, cause?: unknown);
+}
+export interface DurableSessionImage {
+    localPath: string;
+    mediaType: string;
+    data: Buffer;
+}
+export interface PreparedSessionMedia {
+    /** Detached messages: the caller's live transcript is never modified during preparation. */
+    messages: Message[];
+    /** Call immediately after the canonical checkpoint rename succeeds. */
+    markCommitted(): void;
+    /** Idempotent; after commitment this deliberately retains every owned image. */
+    rollback(): Promise<void>;
+}
+/**
+ * A durable ref is authority only when its actual checkpoint contains that exact
+ * attachment. Paths are derived from the owner sidecar; localPath is never trusted.
+ */
+export declare function readDurableSessionImageSync(attachment: MessageAttachment): DurableSessionImage | null;
+/**
+ * Stage immutable owner copies before the JSON rename. Existing generations are
+ * retained for the session lifetime; another checkpoint/queue source may use them.
+ * Public session writers serialize this transaction in-process with withPathLock.
+ */
+export declare function prepareSessionMedia(options: {
+    sessionFile: string;
+    sessionId: string;
+    messages: readonly Message[];
+}): Promise<PreparedSessionMedia>;

package/dist/session_media.js

@@ -0,0 +1,357 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, } from 'node:fs';
+import { mkdir, open, opendir, rm } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { isMirrorMediaPath, MIRROR_MEDIA_ROOT } from './utils/mirror_media.js';
+export const SESSION_MEDIA_LIMITS = Object.freeze({
+    imageBytes: 10 * 1024 * 1024,
+    sessionBytes: 100 * 1024 * 1024,
+    assetCount: 128,
+    /** Bound standalone pane-input metadata, not a session's text transcript. */
+    checkpointBytes: 4 * 1024 * 1024,
+});
+export class SessionMediaError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, { cause });
+        this.code = code;
+        this.name = 'SessionMediaError';
+    }
+}
+const GENERATION = /^g-[0-9a-f]{32}$/u;
+const BLOB = /^([0-9a-f]{64})\.(png|jpg|gif|webp)$/u;
+const FILE = /^(g-[0-9a-f]{32})\/([0-9a-f]{64})\.(png|jpg|gif|webp)$/u;
+const MAX_DIRECTORY_ENTRIES = 4096;
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function canonicalCheckpoint(path) {
+    if (!isAbsolute(path) || /[\u0000-\u001f\u007f]/u.test(path)) {
+        throw new SessionMediaError('invalid_reference', 'Image checkpoint must be an absolute canonical file path.');
+    }
+    return join(realpathSync(dirname(path)), basename(path));
+}
+function imageType(data) {
+    if (data.length >= 8 && data.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+        return { mediaType: 'image/png', extension: 'png' };
+    }
+    if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) {
+        return { mediaType: 'image/jpeg', extension: 'jpg' };
+    }
+    if (data.length >= 6 && ['GIF87a', 'GIF89a'].includes(data.subarray(0, 6).toString('ascii'))) {
+        return { mediaType: 'image/gif', extension: 'gif' };
+    }
+    if (data.length >= 12 && data.subarray(0, 4).toString('ascii') === 'RIFF'
+        && data.subarray(8, 12).toString('ascii') === 'WEBP') {
+        return { mediaType: 'image/webp', extension: 'webp' };
+    }
+    return null;
+}
+function sha256(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+function checkedDirectory(path) {
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new SessionMediaError('invalid_reference', 'Image storage directory is not an owned regular directory.');
+    }
+}
+/** Reads use one regular file; transcript reads stop at its admitted size. */
+function boundedRead(path, maximum) {
+    const before = lstatSync(path);
+    if (!before.isFile() || before.isSymbolicLink()) {
+        throw new SessionMediaError('invalid_reference', 'Image or checkpoint reference is not a regular nonsymlink file.');
+    }
+    const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino) {
+            throw new SessionMediaError('invalid_reference', 'Image reference changed while it was being opened.');
+        }
+        // Session loading already admits the complete JSON transcript. Media proof
+        // must read that same checkpoint, without charging text against asset quotas.
+        // Snapshot the opened file size so concurrent growth cannot make this read
+        // unbounded. Individual images retain their explicit byte limit.
+        maximum ??= stat.size;
+        if (stat.size > maximum) {
+            throw new SessionMediaError('quota_exceeded', `Image or checkpoint exceeds its ${maximum}-byte read limit.`);
+        }
+        const parts = [];
+        let length = 0;
+        while (length <= maximum) {
+            const chunk = Buffer.alloc(Math.min(64 * 1024, maximum + 1 - length));
+            const count = readSync(fd, chunk, 0, chunk.length, null);
+            if (count === 0)
+                break;
+            parts.push(chunk.subarray(0, count));
+            length += count;
+        }
+        if (length > maximum) {
+            throw new SessionMediaError('quota_exceeded', `Image or checkpoint exceeds its ${maximum}-byte read limit.`);
+        }
+        return Buffer.concat(parts, length);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function checkpointAttachments(path, sessionId) {
+    const parsed = JSON.parse(boundedRead(path).toString('utf8'));
+    if (!record(parsed) || !record(parsed.metadata) || typeof parsed.metadata.id !== 'string'
+        || !Array.isArray(parsed.messages)) {
+        throw new SessionMediaError('invalid_reference', 'Image reference checkpoint is malformed.');
+    }
+    // A caller replacing an export with a different logical session must not
+    // inherit the former session's missing-upload compatibility exception.
+    if (sessionId !== undefined && parsed.metadata.id !== sessionId)
+        return [];
+    const attachments = [];
+    for (const message of parsed.messages) {
+        if (!record(message) || !Array.isArray(message.attachments))
+            continue;
+        for (const attachment of message.attachments) {
+            if (record(attachment))
+                attachments.push(attachment);
+        }
+    }
+    return attachments;
+}
+function validReference(value) {
+    return record(value) && Object.keys(value).length === 4 && value.version === 1
+        && typeof value.sessionFile === 'string' && typeof value.file === 'string'
+        && typeof value.sha256 === 'string' && /^[0-9a-f]{64}$/u.test(value.sha256)
+        && FILE.test(value.file) && value.file.split('/')[1].startsWith(value.sha256 + '.');
+}
+function sameReference(first, second) {
+    return validReference(second) && first.version === second.version && first.sessionFile === second.sessionFile
+        && first.file === second.file && first.sha256 === second.sha256;
+}
+function sameAttachment(first, second) {
+    return first.id === second.id && first.kind === second.kind && first.mediaType === second.mediaType
+        && first.size === second.size;
+}
+/**
+ * A durable ref is authority only when its actual checkpoint contains that exact
+ * attachment. Paths are derived from the owner sidecar; localPath is never trusted.
+ */
+export function readDurableSessionImageSync(attachment) {
+    if (attachment.durable === undefined)
+        return null;
+    try {
+        const ref = attachment.durable;
+        if (!validReference(ref) || attachment.kind !== 'image' || typeof attachment.id !== 'string'
+            || !Number.isSafeInteger(attachment.size) || attachment.size <= 0
+            || attachment.size > SESSION_MEDIA_LIMITS.imageBytes) {
+            throw new SessionMediaError('invalid_reference', 'Saved image reference is malformed or exceeds its bounds.');
+        }
+        const checkpoint = canonicalCheckpoint(ref.sessionFile);
+        if (checkpoint !== ref.sessionFile) {
+            throw new SessionMediaError('invalid_reference', 'Saved image checkpoint identity is not canonical.');
+        }
+        if (!checkpointAttachments(checkpoint).some(saved => sameAttachment(attachment, saved)
+            && sameReference(ref, saved.durable))) {
+            throw new SessionMediaError('invalid_reference', 'Saved image does not match its original checkpoint attachment.');
+        }
+        const root = checkpoint + '.media';
+        const [generation, file] = ref.file.split('/');
+        checkedDirectory(root);
+        checkedDirectory(join(root, generation));
+        const localPath = join(root, generation, file);
+        const data = boundedRead(localPath, SESSION_MEDIA_LIMITS.imageBytes);
+        const detected = imageType(data);
+        if (!detected || detected.mediaType !== attachment.mediaType || data.length !== attachment.size
+            || sha256(data) !== ref.sha256 || !file.endsWith('.' + detected.extension)) {
+            throw new SessionMediaError('invalid_reference', 'Saved image bytes, MIME, size or checksum no longer match its checkpoint.');
+        }
+        return { localPath, mediaType: detected.mediaType, data };
+    }
+    catch (error) {
+        if (error instanceof SessionMediaError)
+            throw error;
+        throw new SessionMediaError('unavailable', 'Saved image is unavailable; restore its owned sidecar or attach the image again.', error);
+    }
+}
+/** Only the private generation/blob grammar is counted; unrelated entries are never deleted. */
+async function physicalImages(root) {
+    let directory;
+    try {
+        checkedDirectory(root);
+        directory = await opendir(root);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    let observed = 0;
+    const countEntry = () => {
+        observed += 1;
+        if (observed > MAX_DIRECTORY_ENTRIES) {
+            throw new SessionMediaError('quota_exceeded', 'Session image directory exceeds its bounded entry scan.');
+        }
+    };
+    const images = [];
+    for await (const entry of directory) {
+        countEntry();
+        if (!GENERATION.test(entry.name))
+            continue;
+        checkedDirectory(join(root, entry.name));
+        const files = await opendir(join(root, entry.name));
+        for await (const file of files) {
+            countEntry();
+            if (!BLOB.test(file.name))
+                continue;
+            const stat = lstatSync(join(root, entry.name, file.name));
+            if (!stat.isFile() || stat.isSymbolicLink()) {
+                throw new SessionMediaError('invalid_reference', 'Owned image entry is not a regular nonsymlink file.');
+            }
+            images.push({ file: entry.name + '/' + file.name, size: stat.size });
+        }
+    }
+    return images;
+}
+function quota(count, size) {
+    if (count > SESSION_MEDIA_LIMITS.assetCount) {
+        throw new SessionMediaError('quota_exceeded', `Session image count exceeds its ${SESSION_MEDIA_LIMITS.assetCount}-asset quota. Remove an unneeded session or use a fresh session.`);
+    }
+    if (size > SESSION_MEDIA_LIMITS.sessionBytes) {
+        throw new SessionMediaError('quota_exceeded', `Session images exceed their ${SESSION_MEDIA_LIMITS.sessionBytes}-byte quota. Remove an unneeded session or use a fresh session.`);
+    }
+}
+function rawMirrorImage(attachment) {
+    const path = resolve(attachment.localPath);
+    const root = realpathSync(MIRROR_MEDIA_ROOT);
+    const actual = realpathSync(path);
+    if (!actual.startsWith(root + sep)) {
+        throw new SessionMediaError('invalid_reference', 'Uploaded image is outside its admitted mirror storage.');
+    }
+    // Inspect every component below the known upload root, including the file.
+    const relative = path.slice(resolve(MIRROR_MEDIA_ROOT).length + 1).split(sep);
+    let cursor = resolve(MIRROR_MEDIA_ROOT);
+    for (const segment of relative.slice(0, -1)) {
+        cursor = join(cursor, segment);
+        checkedDirectory(cursor);
+    }
+    const data = boundedRead(path, SESSION_MEDIA_LIMITS.imageBytes);
+    const detected = imageType(data);
+    if (!detected || detected.mediaType !== attachment.mediaType || data.length !== attachment.size) {
+        throw new SessionMediaError('invalid_reference', 'Uploaded image bytes do not match their accepted MIME and size.');
+    }
+    return { localPath: actual, mediaType: detected.mediaType, data };
+}
+/**
+ * Stage immutable owner copies before the JSON rename. Existing generations are
+ * retained for the session lifetime; another checkpoint/queue source may use them.
+ * Public session writers serialize this transaction in-process with withPathLock.
+ */
+export async function prepareSessionMedia(options) {
+    const checkpoint = canonicalCheckpoint(resolve(options.sessionFile));
+    const root = checkpoint + '.media';
+    const messages = structuredClone(options.messages);
+    let committed = false;
+    let generation = null;
+    const prepared = {
+        messages,
+        markCommitted() { committed = true; },
+        async rollback() {
+            if (committed || generation === null)
+                return;
+            const owned = generation;
+            checkedDirectory(root);
+            checkedDirectory(join(root, owned));
+            await rm(join(root, owned), { recursive: true });
+            generation = null;
+        },
+    };
+    try {
+        const applicable = messages.flatMap(message => message.attachments ?? [])
+            .filter(attachment => attachment.kind === 'image'
+            && (attachment.durable !== undefined || isMirrorMediaPath(attachment.localPath)));
+        if (applicable.length === 0)
+            return prepared;
+        const physical = await physicalImages(root);
+        let prior = [];
+        try {
+            prior = checkpointAttachments(checkpoint, options.sessionId);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        let physicalCount = physical.length;
+        let physicalBytes = physical.reduce((total, asset) => total + asset.size, 0);
+        quota(physicalCount, physicalBytes);
+        const byBlob = new Map();
+        for (const asset of physical)
+            byBlob.set(basename(asset.file), asset.file);
+        for (const attachment of applicable) {
+            let source;
+            try {
+                if (attachment.durable !== undefined) {
+                    source = readDurableSessionImageSync(attachment);
+                }
+                else {
+                    // A live caller may still carry its pre-adoption path. Reuse the exact
+                    // previously committed owner instead of reading an expired upload.
+                    const previous = prior.find(saved => sameAttachment(attachment, saved) && saved.durable !== undefined);
+                    source = previous ? readDurableSessionImageSync(previous) : rawMirrorImage(attachment);
+                }
+            }
+            catch (error) {
+                const legacy = prior.some(saved => sameAttachment(attachment, saved)
+                    && saved.durable === undefined && saved.localPath === attachment.localPath);
+                if (attachment.durable === undefined && legacy && error.code === 'ENOENT')
+                    continue;
+                if (error instanceof SessionMediaError)
+                    throw error;
+                throw new SessionMediaError('unavailable', `Accepted image ${attachment.name} is unavailable; attach it again. The checkpoint was not changed.`, error);
+            }
+            const detected = imageType(source.data);
+            const hash = sha256(source.data);
+            const blobName = hash + '.' + detected.extension;
+            let file = byBlob.get(blobName);
+            if (file) {
+                const data = boundedRead(join(root, ...file.split('/')), SESSION_MEDIA_LIMITS.imageBytes);
+                if (data.length !== source.data.length || sha256(data) !== hash) {
+                    throw new SessionMediaError('invalid_reference', 'Existing owned image bytes changed; the checkpoint was not changed.');
+                }
+            }
+            else {
+                quota(physicalCount + 1, physicalBytes + source.data.length);
+                if (generation === null) {
+                    await mkdir(root, { recursive: true, mode: 0o700 });
+                    checkedDirectory(root);
+                    const next = 'g-' + randomUUID().replace(/-/gu, '');
+                    await mkdir(join(root, next), { mode: 0o700 });
+                    generation = next;
+                }
+                file = generation + '/' + blobName;
+                const handle = await open(join(root, generation, blobName), 'wx', 0o600);
+                try {
+                    await handle.writeFile(source.data);
+                }
+                finally {
+                    await handle.close();
+                }
+                const verify = boundedRead(join(root, generation, blobName), SESSION_MEDIA_LIMITS.imageBytes);
+                if (verify.length !== source.data.length || sha256(verify) !== hash) {
+                    throw new SessionMediaError('write_failed', 'Owned image copy could not be verified; the checkpoint was not changed.');
+                }
+                physicalCount += 1;
+                physicalBytes += source.data.length;
+                byBlob.set(blobName, file);
+            }
+            attachment.localPath = join(root, ...file.split('/'));
+            attachment.durable = { version: 1, sessionFile: checkpoint, file, sha256: hash };
+            attachment.mediaType = detected.mediaType;
+            attachment.size = source.data.length;
+        }
+        return prepared;
+    }
+    catch (error) {
+        await prepared.rollback();
+        if (error instanceof SessionMediaError)
+            throw error;
+        throw new SessionMediaError('write_failed', 'Could not preserve session image bytes; the checkpoint was not changed. Retry the save or attach the image again.', error);
+    }
+}

package/dist/session_ownership.d.ts

@@ -0,0 +1,16 @@
+/** Pin before use; the pin remains valid until this process exits. */
+export declare function retainSessionForProcess(sessionDirectory: string, sessionId: string): Promise<void>;
+/**
+ * Publish before scanning: two contenders cannot both see no other live writer.
+ * They may both refuse during simultaneous admission; callers can retry. Each
+ * candidate is an independently atomically published file, so process exit never
+ * leaves a partially initialized exclusive lock that needs an age-based steal.
+ * Retention pins/barriers continue to protect the transcript from cleanup.
+ */
+export declare function acquireSessionWriter(sessionDirectory: string, sessionId: string): Promise<() => Promise<void>>;
+/** Retention readers protect cleanup; only admitted writers block another writer. */
+export declare function hasActiveSessionWriter(sessionDirectory: string, sessionId: string): Promise<boolean>;
+/** Reclaim exited pins under a barrier; keep the pre-upgrade registry read-only. */
+export declare function retainedSessionIds(sessionDirectory: string): Promise<Set<string>>;
+/** A barrier only blocks new users; already pinned users are never candidates. */
+export declare function withSessionCleanupBarrier<T>(sessionDirectory: string, run: () => Promise<T>): Promise<T>;

package/dist/session_ownership.js

@@ -0,0 +1,221 @@
+/**
+ * Conservative, process-lifetime pins for automatic session retention.
+ *
+ * Owners publish a pin before reading or writing a session. Cleaners publish a
+ * barrier before enumerating candidates. A new owner waits for existing
+ * barriers before using its session; a new cleaner sees already published pins.
+ * Independent files avoid the lost updates of a shared read/modify/write list.
+ * PID liveness deliberately ignores heartbeat age: a paused process still owns
+ * its history. Unreadable ownership evidence fails closed.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { link, mkdir, opendir, readFile, rename, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { writeFileAtomic } from './utils/atomic_write.js';
+const pins = new Map();
+const MARKER_SCAN_LIMIT = 512;
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // Only ESRCH proves the owner is gone. EPERM and other uncertainty retain it.
+        return error.code !== 'ESRCH';
+    }
+}
+async function readMarker(path, requireSession) {
+    let marker;
+    try {
+        marker = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    if (!Number.isSafeInteger(marker?.pid) || marker.pid <= 0
+        || (requireSession && (typeof marker.sessionId !== 'string' || !marker.sessionId))) {
+        throw new Error(`Invalid session ownership marker: ${path}`);
+    }
+    return marker;
+}
+async function restoreMarker(captured, original) {
+    try {
+        // Never overwrite a newer publication. On conflict both JSON files remain
+        // visible ownership evidence for subsequent scans.
+        await link(captured, original);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'EEXIST' || code === 'ENOENT')
+            return;
+        throw error;
+    }
+    await unlink(captured);
+}
+async function reclaimExitedMarker(path, requireSession) {
+    // A legacy owner pathname can be atomically replaced after our first read.
+    // Capture the current file, then revalidate its identity/liveness before
+    // deleting. The capture remains discoverable JSON if interrupted or uncertain.
+    const captured = `${path}.${randomUUID()}.json`;
+    try {
+        await rename(path, captured);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    let preserve = true;
+    try {
+        const marker = await readMarker(captured, requireSession);
+        if (marker && isProcessAlive(marker.pid))
+            return marker;
+        if (marker)
+            await unlink(captured);
+        preserve = false;
+        return undefined;
+    }
+    finally {
+        if (preserve)
+            await restoreMarker(captured, path);
+    }
+}
+async function liveMarkers(directory, requireSession) {
+    let entries;
+    try {
+        entries = await opendir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const live = [];
+    let scanned = 0;
+    for await (const entry of entries) {
+        if (++scanned > MARKER_SCAN_LIMIT) {
+            throw new Error(`Session ownership scan limit ${MARKER_SCAN_LIMIT} reached; retry maintenance before opening or cleaning sessions.`);
+        }
+        if (!entry.name.endsWith('.json'))
+            continue;
+        const path = join(directory, entry.name);
+        const marker = await readMarker(path, requireSession);
+        if (!marker)
+            continue;
+        if (isProcessAlive(marker.pid))
+            live.push(marker);
+        else {
+            const replacement = await reclaimExitedMarker(path, requireSession);
+            if (replacement)
+                live.push(replacement);
+        }
+    }
+    return live;
+}
+/** Pin before use; the pin remains valid until this process exits. */
+export function retainSessionForProcess(sessionDirectory, sessionId) {
+    const directory = join(sessionDirectory, '.retention', 'owners');
+    const key = join(directory, `${process.pid}-${createHash('sha256').update(sessionId).digest('hex')}.json`);
+    const existing = pins.get(key);
+    if (existing)
+        return existing;
+    const pending = (async () => {
+        await mkdir(directory, { recursive: true });
+        await writeFileAtomic(key, JSON.stringify({ pid: process.pid, sessionId }));
+        const barriers = join(sessionDirectory, '.retention', 'cleaners');
+        const deadline = Date.now() + 30_000;
+        while ((await liveMarkers(barriers, false)).length > 0) {
+            if (Date.now() >= deadline)
+                throw new Error('Timed out waiting for session retention cleanup. Retry opening the session.');
+            await delay(10);
+        }
+    })();
+    pins.set(key, pending);
+    void pending.catch(() => { pins.delete(key); });
+    return pending;
+}
+/**
+ * Publish before scanning: two contenders cannot both see no other live writer.
+ * They may both refuse during simultaneous admission; callers can retry. Each
+ * candidate is an independently atomically published file, so process exit never
+ * leaves a partially initialized exclusive lock that needs an age-based steal.
+ * Retention pins/barriers continue to protect the transcript from cleanup.
+ */
+export async function acquireSessionWriter(sessionDirectory, sessionId) {
+    await retainSessionForProcess(sessionDirectory, sessionId);
+    const directory = join(sessionDirectory, '.retention', 'writers', createHash('sha256').update(sessionId).digest('hex'));
+    await mkdir(directory, { recursive: true });
+    const writerId = randomUUID();
+    const marker = join(directory, `${process.pid}-${writerId}.json`);
+    await writeFileAtomic(marker, JSON.stringify({ pid: process.pid, sessionId, writerId }));
+    let admitted = false;
+    try {
+        const writers = await liveMarkers(directory, true);
+        if (writers.some(writer => writer.sessionId !== sessionId || typeof writer.writerId !== 'string'
+            || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(writer.writerId))) {
+            throw new Error('Invalid session writer ownership marker');
+        }
+        if (writers.some(writer => writer.writerId !== writerId)) {
+            throw new Error('Delegated session is already being written; retry after its current writer stops.');
+        }
+        admitted = true;
+        return async () => { await unlink(marker); };
+    }
+    finally {
+        if (!admitted)
+            await unlink(marker);
+    }
+}
+/** Retention readers protect cleanup; only admitted writers block another writer. */
+export async function hasActiveSessionWriter(sessionDirectory, sessionId) {
+    const directory = join(sessionDirectory, '.retention', 'writers', createHash('sha256').update(sessionId).digest('hex'));
+    const writers = await liveMarkers(directory, true);
+    if (writers.some(writer => writer.sessionId !== sessionId || typeof writer.writerId !== 'string'
+        || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(writer.writerId))) {
+        throw new Error('Invalid session writer ownership marker');
+    }
+    return writers.length > 0;
+}
+/** Reclaim exited pins under a barrier; keep the pre-upgrade registry read-only. */
+export async function retainedSessionIds(sessionDirectory) {
+    return withSessionCleanupBarrier(sessionDirectory, async () => {
+        const owned = await liveMarkers(join(sessionDirectory, '.retention', 'owners'), true);
+        const ids = new Set(owned.map(marker => marker.sessionId));
+        let registry;
+        try {
+            registry = JSON.parse(await readFile(join(homedir(), '.ztc', 'instances.json'), 'utf8'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return ids;
+            throw error;
+        }
+        if (!Array.isArray(registry))
+            throw new Error('Invalid ZTC instance registry; automatic session retention skipped.');
+        for (const marker of registry) {
+            if (!Number.isSafeInteger(marker?.pid) || marker.pid <= 0 || typeof marker.sessionId !== 'string') {
+                throw new Error('Invalid ZTC instance registry; automatic session retention skipped.');
+            }
+            if (isProcessAlive(marker.pid))
+                ids.add(marker.sessionId);
+        }
+        return ids;
+    });
+}
+/** A barrier only blocks new users; already pinned users are never candidates. */
+export async function withSessionCleanupBarrier(sessionDirectory, run) {
+    const directory = join(sessionDirectory, '.retention', 'cleaners');
+    await mkdir(directory, { recursive: true });
+    const marker = join(directory, `${process.pid}-${randomUUID()}.json`);
+    await writeFileAtomic(marker, JSON.stringify({ pid: process.pid }));
+    try {
+        return await run();
+    }
+    finally {
+        await unlink(marker);
+    }
+}

package/dist/session_public.d.ts

@@ -12,6 +12,14 @@
  * This file re-exports exactly those symbols under the `zerg-ztc/session`
  * package export. The default `~/.ztc/sessions/` path helpers remain internal.
  */
-export { loadSessionFromFile, saveSessionToFile, generateSessionId, getProjectHash, hasSessionSelector, ensureSessionSelector, } from './session.js';
-export type { Session, SessionMetadata, SessionSummary, } from './session.js';
+export { loadSessionFromFile, saveSessionToFile, generateSessionId, getProjectHash, hasSessionSelector, ensureSessionSelector, findSessionHandoffOffers, updateSessionBoardBinding, } from './session.js';
+export { admitBoardSessionBinding } from './board/binding.js';
+export type { BoardSessionBinding } from './board/binding.js';
+export type { Session, SessionMetadata, SessionSummary, SessionRuntimeState, SessionHandoffLookupOptions, } from './session.js';
+export type { TaskHandoffInput, TaskHandoffCorrection, TaskHandoffSnapshot, TaskHandoffProjection } from './session_handoff_contract.js';
+export { parseTaskHandoffSnapshot, parseTaskHandoffProjection, projectTaskHandoff, formatTaskHandoffContext } from './session_handoff_contract.js';
 export type { Message, MessageRole, ToolCall } from './types.js';
+export { buildSessionDiagnosticDocument, exportSessionDiagnostics, parseDiagnosticExport, formatSessionDiagnosticsMarkdown, parseDiagnosticSnapshot, DiagnosticExportError, DIAGNOSTIC_LIMITS } from './diagnostics/session_export.js';
+export type { DiagnosticSnapshot, DiagnosticEvent, DiagnosticExportHeader, DiagnosticDocument, DiagnosticJsonValue, DiagnosticJsonObject, DiagnosticTruncation, SessionDiagnosticInput } from './diagnostics/session_export.js';
+export { buildSessionEvidencePackage, saveSessionEvidencePackage, SESSION_EVIDENCE_INDEX_MAX_BYTES } from './diagnostics/session_evidence_package.js';
+export type { SessionEvidencePackageInput, SessionEvidencePackageSource, SessionEvidencePackageEntry, SessionEvidencePackageManifestEntry, SessionEvidencePackage } from './diagnostics/session_evidence_package.js';

package/dist/session_public.js

@@ -12,4 +12,9 @@
  * This file re-exports exactly those symbols under the `zerg-ztc/session`
  * package export. The default `~/.ztc/sessions/` path helpers remain internal.
  */
-export { loadSessionFromFile, saveSessionToFile, generateSessionId, getProjectHash, hasSessionSelector, ensureSessionSelector, } from './session.js';
+export { loadSessionFromFile, saveSessionToFile, generateSessionId, getProjectHash, hasSessionSelector, ensureSessionSelector, findSessionHandoffOffers, updateSessionBoardBinding, } from './session.js';
+export { admitBoardSessionBinding } from './board/binding.js';
+export { parseTaskHandoffSnapshot, parseTaskHandoffProjection, projectTaskHandoff, formatTaskHandoffContext } from './session_handoff_contract.js';
+// Canonical, redacted diagnostic artifacts are shared by terminal and desktop consumers.
+export { buildSessionDiagnosticDocument, exportSessionDiagnostics, parseDiagnosticExport, formatSessionDiagnosticsMarkdown, parseDiagnosticSnapshot, DiagnosticExportError, DIAGNOSTIC_LIMITS } from './diagnostics/session_export.js';
+export { buildSessionEvidencePackage, saveSessionEvidencePackage, SESSION_EVIDENCE_INDEX_MAX_BYTES } from './diagnostics/session_evidence_package.js';