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

package/dist/session_handoff.d.ts

@@ -0,0 +1,25 @@
+import type { Session } from './session.js';
+import type { Message } from './types.js';
+import { type TaskHandoffInput, type TaskHandoffSnapshot } from './session_handoff_contract.js';
+export type TaskHandoffAdmissionReason = 'invalid_handoff' | 'unsupported_handoff_version' | 'handoff_fingerprint_mismatch';
+export declare class TaskHandoffAdmissionError extends Error {
+    readonly reason: TaskHandoffAdmissionReason;
+    constructor(reason: TaskHandoffAdmissionReason, message: string);
+}
+type Checkpoint = Pick<Session, 'metadata' | 'messages' | 'evidence'>;
+/** Cwd association is canonical filesystem identity when available, never a pane ID. */
+export declare function canonicalHandoffCwd(cwd: string): string;
+/** Fingerprints cover exactly the normalized persisted checkpoint, including delivery metadata. */
+export declare function taskHandoffFingerprints(session: Checkpoint): {
+    messagesSha256: string;
+    evidenceSha256: string;
+};
+/** Parse and bind a snapshot to its original complete session payload. No fuzzy transplant. */
+export declare function admitTaskHandoff(value: unknown, session: Checkpoint): TaskHandoffSnapshot;
+/**
+ * Derive host facts only; narrated completion and inferred next actions remain unavailable.
+ * previousMessages belongs to the same admitted predecessor as previous. A
+ * retained Clear event is consumed there, even if compaction rewrites row IDs.
+ */
+export declare function deriveTaskHandoff(session: Checkpoint, input?: TaskHandoffInput, previous?: TaskHandoffSnapshot, previousMessages?: readonly Message[]): TaskHandoffSnapshot | null;
+export {};

package/dist/session_handoff.js

@@ -0,0 +1,322 @@
+import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { SESSION_MEDIA_LIMITS } from './session_media.js';
+import { stripEphemeralMessages } from './utils/ephemeral.js';
+import { parseEvidenceSnapshot } from './agent/runtime/evidence.js';
+import { parseTaskHandoffSnapshot, TASK_HANDOFF_MAX_BYTES, TASK_HANDOFF_MAX_CORRECTIONS, TASK_HANDOFF_MAX_REFERENCES, TASK_HANDOFF_MAX_TEXT_BYTES, } from './session_handoff_contract.js';
+export class TaskHandoffAdmissionError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'TaskHandoffAdmissionError';
+    }
+}
+function correctionSourceText(session, correction) {
+    const message = session.messages.find(item => item.id === correction.sourceMessageId);
+    if (!message)
+        return null;
+    if (message.role === 'user' && !message.metadata?.synthetic && !message.metadata?.toolResult && !message.metadata?.compactionSummary)
+        return message.content;
+    const raw = message.metadata?.taskHandoffCorrection;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const source = raw;
+    return source.id === correction.id && typeof source.text === 'string' ? source.text : null;
+}
+/** Image-only intent requires its exact source, not a vacuous empty preview. */
+function hasMediaOnlySource(session, correction) {
+    const message = session.messages.find(item => item.id === correction.sourceMessageId);
+    if (!message || (message.role !== 'user' && message.role !== 'system')
+        || message.metadata?.synthetic || message.metadata?.toolResult || message.metadata?.compactionSummary)
+        return false;
+    const source = correctionSourceText(session, correction);
+    if (source === null || source.trim()
+        || (source !== correction.text && (Buffer.byteLength(source) <= TASK_HANDOFF_MAX_TEXT_BYTES
+            || boundedText(source, { corrections: 0, completedObservations: 0, unresolvedCalls: 0, textBytes: 0 }) !== correction.text)))
+        return false;
+    if (!Array.isArray(message.attachments))
+        return false;
+    return message.attachments.some(attachment => {
+        if (!attachment || attachment.kind !== 'image' || typeof attachment.id !== 'string'
+            || !attachment.id || Buffer.byteLength(attachment.id) > 256 || /[\u0000-\u001f\u007f]/u.test(attachment.id)
+            || typeof attachment.name !== 'string' || typeof attachment.mediaType !== 'string'
+            || !Number.isSafeInteger(attachment.size) || attachment.size <= 0 || attachment.size > SESSION_MEDIA_LIMITS.imageBytes)
+            return false;
+        const ref = attachment.durable;
+        if (!ref || typeof ref !== 'object' || Array.isArray(ref) || Object.keys(ref).length !== 4 || ref.version !== 1
+            || typeof ref.sessionFile !== 'string' || !/^(?:\/|[A-Za-z]:[\\/]|\\\\)/u.test(ref.sessionFile)
+            || /[\u0000-\u001f\u007f]/u.test(ref.sessionFile) || typeof ref.sha256 !== 'string'
+            || !/^[a-f0-9]{64}$/u.test(ref.sha256) || typeof ref.file !== 'string')
+            return false;
+        const file = /^g-[a-f0-9]{32}\/([a-f0-9]{64})\.(png|jpg|gif|webp)$/u.exec(ref.file);
+        const mediaTypes = { png: 'image/png', jpg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp' };
+        return file !== null && file[1] === ref.sha256 && mediaTypes[file[2]] === attachment.mediaType;
+    });
+}
+/** Cwd association is canonical filesystem identity when available, never a pane ID. */
+export function canonicalHandoffCwd(cwd) {
+    const absolute = resolve(cwd);
+    try {
+        return realpathSync(absolute);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return absolute;
+        throw error;
+    }
+}
+function canonicalJson(value) {
+    const normalized = JSON.parse(JSON.stringify(value ?? null));
+    const sorted = (item) => {
+        if (Array.isArray(item))
+            return item.map(sorted);
+        if (item && typeof item === 'object')
+            return Object.fromEntries(Object.entries(item).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, child]) => [key, sorted(child)]));
+        return item;
+    };
+    return JSON.stringify(sorted(normalized));
+}
+/** Fingerprints cover exactly the normalized persisted checkpoint, including delivery metadata. */
+export function taskHandoffFingerprints(session) {
+    const digest = (value) => createHash('sha256').update(canonicalJson(value)).digest('hex');
+    return { messagesSha256: digest(stripEphemeralMessages(session.messages)), evidenceSha256: digest(session.evidence === undefined ? null : parseEvidenceSnapshot(session.evidence)) };
+}
+/** Parse and bind a snapshot to its original complete session payload. No fuzzy transplant. */
+export function admitTaskHandoff(value, session) {
+    if (value && typeof value === 'object' && 'schemaVersion' in value && value.schemaVersion !== 1) {
+        throw new TaskHandoffAdmissionError('unsupported_handoff_version', 'Saved task handoff declares an unsupported schema version. The original checkpoint was not changed.');
+    }
+    const snapshot = parseTaskHandoffSnapshot(value);
+    if (!snapshot)
+        throw new TaskHandoffAdmissionError('invalid_handoff', 'Saved task handoff is malformed or exceeds its bounds. The original checkpoint was not changed.');
+    const expectedTaskId = snapshot.objective.kind === 'goal'
+        ? `goal:${snapshot.objective.goalId}` : `request:${snapshot.objective.sourceMessageId}`;
+    if (snapshot.taskId !== expectedTaskId) {
+        throw new TaskHandoffAdmissionError('handoff_fingerprint_mismatch', 'Saved task handoff task identity does not match its original objective source. The original checkpoint was not changed.');
+    }
+    const hashes = taskHandoffFingerprints(session);
+    if (snapshot.source.sessionId !== session.metadata.id || snapshot.source.cwd !== canonicalHandoffCwd(session.metadata.cwd)
+        || snapshot.source.messagesSha256 !== hashes.messagesSha256 || snapshot.source.evidenceSha256 !== hashes.evidenceSha256) {
+        throw new TaskHandoffAdmissionError('handoff_fingerprint_mismatch', 'Saved task handoff does not match its source session, cwd, messages or evidence. The original checkpoint was not changed.');
+    }
+    const evidence = session.evidence === undefined ? null : parseEvidenceSnapshot(session.evidence);
+    if (snapshot.objective.kind === 'goal') {
+        const goal = session.metadata.goal;
+        if (!goal || goal.goalId !== snapshot.objective.goalId || goal.status !== snapshot.taskStatus || !goal.objective.startsWith(snapshot.objective.text)) {
+            throw new TaskHandoffAdmissionError('handoff_fingerprint_mismatch', 'Saved task handoff goal identity, status or objective does not match its source goal. The original checkpoint was not changed.');
+        }
+    }
+    else {
+        const message = session.messages.find(item => item.id === snapshot.objective.sourceMessageId && item.role === 'user' && !item.metadata?.synthetic && !item.metadata?.compactionSummary && !item.metadata?.toolResult);
+        const instruction = evidence?.records.find(item => item.kind === 'user_instruction' && item.source.messageId === snapshot.objective.sourceMessageId);
+        const present = Boolean(message || instruction);
+        if ((snapshot.objective.sourceAvailability === 'present') !== present || (message && !message.content.startsWith(snapshot.objective.text))) {
+            throw new TaskHandoffAdmissionError('handoff_fingerprint_mismatch', 'Saved task handoff opening-request source identity or availability does not match its checkpoint. The original checkpoint was not changed.');
+        }
+    }
+    for (const blocker of snapshot.blockers) {
+        const goal = session.metadata.goal;
+        if (!goal || goal.goalId !== blocker.sourceGoalId || typeof goal.blockedReason !== 'string' || !goal.blockedReason.startsWith(blocker.text)) {
+            throw new TaskHandoffAdmissionError('handoff_fingerprint_mismatch', 'Saved blocker text does not match its original goal source. The original checkpoint was not changed.');
+        }
+    }
+    if (snapshot.nextAction.availability === 'recorded') {
+        const message = session.messages.find(item => item.id === snapshot.nextAction.sourceMessageId && item.role === 'user'
+            && !item.metadata?.synthetic && !item.metadata?.toolResult && !item.metadata?.compactionSummary && !item.metadata?.managedCommandObservation);
+        if (!message || !message.content.startsWith(snapshot.nextAction.text)) {
+            throw new TaskHandoffAdmissionError('handoff_fingerprint_mismatch', 'Saved next-action text does not match its original authored message source. The original checkpoint was not changed.');
+        }
+    }
+    for (const correction of snapshot.corrections)
+        if (correction.sourceMessageId !== null) {
+            if (!correction.text.trim() && !hasMediaOnlySource(session, correction)) {
+                throw new TaskHandoffAdmissionError('handoff_fingerprint_mismatch', 'Saved image-only correction does not match its exact owned image source. The original checkpoint was not changed.');
+            }
+            const source = correctionSourceText(session, correction);
+            if (source === null || !source.startsWith(correction.text))
+                throw new TaskHandoffAdmissionError('handoff_fingerprint_mismatch', 'Saved correction preview does not match its original transcript source. The original checkpoint was not changed.');
+        }
+    for (const row of snapshot.completedObservations) {
+        const observation = evidence?.records.find(item => item.kind === 'observation' && item.id === row.observationId && item.source.origin === 'host_receipt');
+        const job = observation?.source.job;
+        if (!observation || !job || job.sessionId !== session.metadata.id || observation.source.toolCallId !== row.toolCallId
+            || job.jobId !== row.jobId || job.status !== row.status || job.exitCode !== row.exitCode || !job.endedAt) {
+            throw new TaskHandoffAdmissionError('handoff_fingerprint_mismatch', 'Saved terminal process reference does not match its host receipt. The original checkpoint was not changed.');
+        }
+    }
+    for (const row of snapshot.unresolvedCalls) {
+        const call = session.messages.find(message => message.id === row.sourceMessageId)?.toolCalls?.find(item => item.id === row.toolCallId);
+        if (!call || call.name !== row.name || (call.status !== 'pending' && call.status !== 'running' && (call.result !== undefined || call.error !== undefined))) {
+            throw new TaskHandoffAdmissionError('handoff_fingerprint_mismatch', 'Saved unresolved call does not match its source tool call. The original checkpoint was not changed.');
+        }
+    }
+    return snapshot;
+}
+function boundedText(value, omitted) {
+    let size = 0;
+    let kept = '';
+    for (const char of value) {
+        const length = Buffer.byteLength(char);
+        if (size + length > TASK_HANDOFF_MAX_TEXT_BYTES)
+            break;
+        kept += char;
+        size += length;
+    }
+    omitted.textBytes += Buffer.byteLength(value) - size;
+    return kept;
+}
+function taskHandoffResetId(message) {
+    const value = message.metadata?.taskHandoffReset;
+    return message.role === 'system' && typeof value === 'string'
+        && /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/u.test(value)
+        ? value : null;
+}
+/**
+ * Derive host facts only; narrated completion and inferred next actions remain unavailable.
+ * previousMessages belongs to the same admitted predecessor as previous. A
+ * retained Clear event is consumed there, even if compaction rewrites row IDs.
+ */
+export function deriveTaskHandoff(session, input, previous, previousMessages) {
+    const messages = stripEphemeralMessages(session.messages);
+    const goal = session.metadata.goal;
+    const usableGoal = goal && typeof goal.goalId === 'string' && typeof goal.objective === 'string' && goal.objective.trim()
+        && ['active', 'paused', 'blocked', 'budget_limited', 'complete'].includes(goal.status) ? goal : null;
+    let resetIndex = -1;
+    let resetId = null;
+    messages.forEach((message, index) => {
+        const event = taskHandoffResetId(message);
+        if (event !== null) {
+            resetIndex = index;
+            resetId = event;
+        }
+    });
+    const resetConsumed = resetId !== null && stripEphemeralMessages(previousMessages ?? [])
+        .some(message => taskHandoffResetId(message) === resetId);
+    const opening = messages.find((message, index) => index > resetIndex && message.role === 'user' && typeof message.content === 'string' && message.content.trim()
+        && !message.metadata?.synthetic && !message.metadata?.toolResult && !message.metadata?.steering
+        && !message.metadata?.compactionSummary && !message.metadata?.managedCommandObservation);
+    const prior = previous?.source.sessionId === session.metadata.id && previous.source.cwd === canonicalHandoffCwd(session.metadata.cwd) ? previous : undefined;
+    const retainOpening = !usableGoal && prior?.objective.kind === 'opening_request' && messages.length > 0
+        && (resetIndex < 0 || resetConsumed);
+    if (!usableGoal && !opening && !retainOpening)
+        return null;
+    const omitted = { corrections: 0, completedObservations: 0, unresolvedCalls: 0, textBytes: 0 };
+    const objective = usableGoal
+        ? { kind: 'goal', text: boundedText(usableGoal.objective, omitted), sourceMessageId: null, goalId: usableGoal.goalId, sourceAvailability: 'present' }
+        : retainOpening ? { ...prior.objective }
+            : { kind: 'opening_request', text: boundedText(opening.content, omitted), sourceMessageId: opening.id, goalId: null, sourceAvailability: 'present' };
+    const taskId = usableGoal ? `goal:${usableGoal.goalId}` : retainOpening ? prior.taskId : `request:${opening.id}`;
+    const sameTask = prior?.taskId === taskId;
+    const corrections = input?.corrections ?? (sameTask ? prior.corrections : []);
+    const applicableCorrections = corrections.filter(correction => !usableGoal || correction.deliveryState !== 'delivered'
+        || !Number.isFinite(usableGoal.createdAt) || Date.parse(correction.queuedAt) >= usableGoal.createdAt);
+    const recordedOrder = (a, b) => {
+        if (a.queuedPosition !== undefined && b.queuedPosition !== undefined) {
+            const difference = a.queuedPosition - b.queuedPosition;
+            if (difference !== 0)
+                return difference;
+        }
+        else if (a.queuedPosition !== undefined)
+            return -1;
+        else if (b.queuedPosition !== undefined)
+            return 1;
+        return a.queuedAt.localeCompare(b.queuedAt) || a.id.localeCompare(b.id);
+    };
+    const uncertain = applicableCorrections.filter(correction => correction.deliveryState !== 'delivered').sort(recordedOrder);
+    const delivered = applicableCorrections.filter(correction => correction.deliveryState === 'delivered').sort(recordedOrder);
+    const pendingPreview = uncertain.slice(0, TASK_HANDOFF_MAX_CORRECTIONS);
+    const deliveredSlots = TASK_HANDOFF_MAX_CORRECTIONS - pendingPreview.length;
+    const selectedCorrections = [...pendingPreview, ...(deliveredSlots > 0 ? delivered.slice(-deliveredSlots) : [])];
+    const snapshot = {
+        schemaVersion: 1, revision: prior ? prior.revision + 1 : 1, taskId,
+        taskStatus: usableGoal?.status ?? 'unknown',
+        source: { sessionId: session.metadata.id, cwd: canonicalHandoffCwd(session.metadata.cwd), capturedAt: session.metadata.updatedAt, ...taskHandoffFingerprints(session) },
+        objective,
+        owner: input ? { ...input.owner } : sameTask ? { ...prior.owner } : { pid: null, paneId: null },
+        corrections: selectedCorrections.map(correction => {
+            if (!correction.text.trim() && !hasMediaOnlySource(session, correction)) {
+                throw new TaskHandoffAdmissionError('invalid_handoff', 'Image-only correction requires its exact authored source and owned image metadata; the previous checkpoint was not changed.');
+            }
+            const source = correction.sourceMessageId === null ? null : correctionSourceText(session, correction);
+            let sourceMessageId = correction.sourceMessageId;
+            if (sourceMessageId !== null && source === null) {
+                const historical = sameTask && prior.corrections.some(row => row.id === correction.id
+                    && row.deliveryState === 'delivered' && row.text === correction.text && row.sourceMessageId === sourceMessageId);
+                if (correction.deliveryState !== 'delivered' || !historical) {
+                    throw new TaskHandoffAdmissionError('invalid_handoff', 'Pending correction original source is unavailable; the previous checkpoint was not changed.');
+                }
+                // A delivered, admitted preview remains descriptive historical context;
+                // it must not pretend that its missing exact source is retrievable.
+                sourceMessageId = null;
+            }
+            else if (source !== null && !source.startsWith(correction.text)) {
+                throw new TaskHandoffAdmissionError('invalid_handoff', 'Correction text does not match its original transcript source; the previous checkpoint was not changed.');
+            }
+            if (Buffer.byteLength(correction.text) > TASK_HANDOFF_MAX_TEXT_BYTES && correctionSourceText(session, correction) !== correction.text) {
+                throw new TaskHandoffAdmissionError('invalid_handoff', 'Oversized correction requires its exact full transcript source before a bounded preview can be saved.');
+            }
+            // A route save may retain an admitted preview rather than a live queue.
+            // Rebind it to available exact source text so clipping remains explicit.
+            return { ...correction, sourceMessageId, text: boundedText(source ?? correction.text, omitted) };
+        }),
+        completedObservations: [], unresolvedCalls: [], blockers: [],
+        nextAction: { text: null, sourceMessageId: null, availability: 'unavailable' }, omitted,
+    };
+    omitted.corrections = Math.max(0, corrections.length - snapshot.corrections.length);
+    const evidence = session.evidence === undefined ? null : parseEvidenceSnapshot(session.evidence);
+    if (objective.kind === 'opening_request')
+        objective.sourceAvailability = messages.some(message => message.id === objective.sourceMessageId)
+            || (evidence?.records.some(item => item.kind === 'user_instruction' && item.source.messageId === objective.sourceMessageId) ?? false)
+            ? 'present' : 'historical_checkpoint';
+    const terminal = new Set(['completed', 'failed', 'cancelled', 'timed_out', 'interrupted']);
+    for (const observation of evidence?.records ?? []) {
+        if (observation.kind !== 'observation' || observation.source.origin !== 'host_receipt')
+            continue;
+        const job = observation.source.job;
+        if (!job || job.sessionId !== session.metadata.id || !terminal.has(job.status) || !job.endedAt || !observation.source.toolCallId)
+            continue;
+        const row = { observationId: observation.id, toolCallId: observation.source.toolCallId,
+            jobId: job.jobId, status: job.status, exitCode: job.exitCode, verification: 'unknown' };
+        if (snapshot.completedObservations.length < TASK_HANDOFF_MAX_REFERENCES)
+            snapshot.completedObservations.push(row);
+        else
+            omitted.completedObservations += 1;
+    }
+    const seen = new Set();
+    for (const message of messages)
+        for (const call of message.toolCalls ?? []) {
+            if (seen.has(call.id) || (call.status !== 'pending' && call.status !== 'running' && (call.result !== undefined || call.error !== undefined)))
+                continue;
+            seen.add(call.id);
+            if (snapshot.unresolvedCalls.length < TASK_HANDOFF_MAX_REFERENCES)
+                snapshot.unresolvedCalls.push({ toolCallId: call.id, name: call.name, sourceMessageId: message.id, outcome: 'unknown' });
+            else
+                omitted.unresolvedCalls += 1;
+        }
+    if (usableGoal?.blockedReason)
+        snapshot.blockers.push({ text: boundedText(usableGoal.blockedReason, omitted), sourceGoalId: usableGoal.goalId });
+    // Drop complete rows only when aggregate JSON escaping exceeds the bound.
+    // Correction text is never silently clipped: an oversized required row rejects the save.
+    while (Buffer.byteLength(JSON.stringify(snapshot)) > TASK_HANDOFF_MAX_BYTES) {
+        if (snapshot.completedObservations.length) {
+            snapshot.completedObservations.pop();
+            omitted.completedObservations += 1;
+        }
+        else if (snapshot.unresolvedCalls.length) {
+            snapshot.unresolvedCalls.pop();
+            omitted.unresolvedCalls += 1;
+        }
+        else if (snapshot.corrections.length) {
+            snapshot.corrections.pop();
+            omitted.corrections += 1;
+        }
+        else
+            break;
+    }
+    const parsed = parseTaskHandoffSnapshot(snapshot);
+    if (!parsed)
+        throw new TaskHandoffAdmissionError('invalid_handoff', 'Task handoff input or captured source identity is invalid or exceeds its bounds; no checkpoint was written.');
+    return parsed;
+}

package/dist/session_handoff_contract.d.ts

@@ -0,0 +1,89 @@
+/** Portable source-qualified task checkpoints. Historical facts never grant ownership. */
+export declare const TASK_HANDOFF_MAX_BYTES: number;
+export declare const TASK_HANDOFF_MAX_TEXT_BYTES = 2048;
+export declare const TASK_HANDOFF_MAX_CORRECTIONS = 10;
+export declare const TASK_HANDOFF_MAX_REFERENCES = 16;
+export interface TaskHandoffCorrection {
+    id: string;
+    text: string;
+    delivery: 'subturn' | 'end-of-turn';
+    deliveryState: 'pending' | 'delivered' | 'unknown';
+    queuedAt: string;
+    sourceMessageId: string | null;
+    /** Historical captured queue order only; never proof of current dispatch ownership. */
+    queuedPosition?: number;
+}
+export interface TaskHandoffInput {
+    corrections: TaskHandoffCorrection[];
+    owner: {
+        pid: number;
+        paneId: number | null;
+    };
+}
+export interface TaskHandoffSnapshot {
+    schemaVersion: 1;
+    revision: number;
+    taskId: string;
+    taskStatus: 'active' | 'paused' | 'blocked' | 'budget_limited' | 'complete' | 'unknown';
+    source: {
+        sessionId: string;
+        cwd: string;
+        capturedAt: string;
+        messagesSha256: string;
+        evidenceSha256: string;
+    };
+    objective: {
+        kind: 'goal' | 'opening_request';
+        text: string;
+        sourceMessageId: string | null;
+        goalId: string | null;
+        sourceAvailability: 'present' | 'historical_checkpoint';
+    };
+    owner: {
+        pid: number | null;
+        paneId: number | null;
+    };
+    corrections: TaskHandoffCorrection[];
+    completedObservations: Array<{
+        observationId: string;
+        toolCallId: string;
+        jobId: string;
+        status: 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'interrupted';
+        exitCode: number | null;
+        verification: 'unknown';
+    }>;
+    unresolvedCalls: Array<{
+        toolCallId: string;
+        name: string;
+        sourceMessageId: string;
+        outcome: 'unknown';
+    }>;
+    blockers: Array<{
+        text: string;
+        sourceGoalId: string;
+    }>;
+    nextAction: {
+        text: string | null;
+        sourceMessageId: string | null;
+        availability: 'recorded' | 'unavailable';
+    };
+    omitted: {
+        corrections: number;
+        completedObservations: number;
+        unresolvedCalls: number;
+        textBytes: number;
+    };
+}
+export interface TaskHandoffProjection {
+    snapshot: TaskHandoffSnapshot;
+    resumeCommand: string;
+    provenance: 'validated_session_checkpoint';
+    ownerLiveness: 'unknown';
+    asOf: string;
+}
+/** Admission is strict; malformed checkpoints remain unavailable rather than partially authoritative. */
+export declare function parseTaskHandoffSnapshot(value: unknown): TaskHandoffSnapshot | null;
+export declare function parseTaskHandoffProjection(value: unknown): TaskHandoffProjection | null;
+export declare function projectTaskHandoff(snapshot: TaskHandoffSnapshot): TaskHandoffProjection;
+/** Historical checkpoint context; display alone never resumes or repeats an operation. */
+export declare function formatTaskHandoffContext(snapshot: TaskHandoffSnapshot): string;

package/dist/session_handoff_contract.js

@@ -0,0 +1,179 @@
+/** Portable source-qualified task checkpoints. Historical facts never grant ownership. */
+export const TASK_HANDOFF_MAX_BYTES = 32 * 1024;
+export const TASK_HANDOFF_MAX_TEXT_BYTES = 2048;
+export const TASK_HANDOFF_MAX_CORRECTIONS = 10;
+export const TASK_HANDOFF_MAX_REFERENCES = 16;
+const encoder = new TextEncoder();
+const bytes = (value) => encoder.encode(value).length;
+const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const exact = (value, names) => Object.keys(value).length === names.length && names.every(name => Object.prototype.hasOwnProperty.call(value, name));
+const integer = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+const identity = (value) => typeof value === 'string' && value.length > 0 && bytes(value) <= 256 && !/[\u0000-\u001f\u007f]/u.test(value);
+const text = (value) => typeof value === 'string' && value.trim().length > 0 && bytes(value) <= TASK_HANDOFF_MAX_TEXT_BYTES;
+const nullableIdentity = (value) => value === null || identity(value);
+const sha = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const timestamp = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+const unique = (values, key) => new Set(values.map(value => value[key])).size === values.length;
+const detached = (value) => JSON.parse(JSON.stringify(value));
+/** Admission is strict; malformed checkpoints remain unavailable rather than partially authoritative. */
+export function parseTaskHandoffSnapshot(value) {
+    try {
+        if (!record(value) || bytes(JSON.stringify(value)) > TASK_HANDOFF_MAX_BYTES
+            || !exact(value, ['schemaVersion', 'revision', 'taskId', 'taskStatus', 'source', 'objective', 'owner', 'corrections', 'completedObservations', 'unresolvedCalls', 'blockers', 'nextAction', 'omitted'])
+            || value.schemaVersion !== 1 || !integer(value.revision) || value.revision === 0 || !identity(value.taskId)
+            || typeof value.taskStatus !== 'string' || !['active', 'paused', 'blocked', 'budget_limited', 'complete', 'unknown'].includes(value.taskStatus))
+            return null;
+        const source = value.source;
+        if (!record(source) || !exact(source, ['sessionId', 'cwd', 'capturedAt', 'messagesSha256', 'evidenceSha256'])
+            || !identity(source.sessionId) || typeof source.cwd !== 'string' || bytes(source.cwd) > 4096
+            || !/^(?:\/|[A-Za-z]:[\\/]|\\\\)/u.test(source.cwd) || /[\u0000-\u001f\u007f]/u.test(source.cwd)
+            || !timestamp(source.capturedAt) || !sha(source.messagesSha256) || !sha(source.evidenceSha256))
+            return null;
+        const objective = value.objective;
+        if (!record(objective) || !exact(objective, ['kind', 'text', 'sourceMessageId', 'goalId', 'sourceAvailability']) || !text(objective.text)
+            || typeof objective.sourceAvailability !== 'string' || !['present', 'historical_checkpoint'].includes(objective.sourceAvailability))
+            return null;
+        if (objective.kind === 'goal') {
+            if (!identity(objective.goalId) || objective.sourceMessageId !== null || value.taskStatus === 'unknown' || objective.sourceAvailability !== 'present')
+                return null;
+        }
+        else if (objective.kind === 'opening_request') {
+            if (!identity(objective.sourceMessageId) || objective.goalId !== null || value.taskStatus !== 'unknown')
+                return null;
+        }
+        else
+            return null;
+        const owner = value.owner;
+        if (!record(owner) || !exact(owner, ['pid', 'paneId'])
+            || !(owner.pid === null || (integer(owner.pid) && owner.pid > 0))
+            || !(owner.paneId === null || integer(owner.paneId)))
+            return null;
+        const corrections = value.corrections;
+        if (!Array.isArray(corrections) || corrections.length > TASK_HANDOFF_MAX_CORRECTIONS)
+            return null;
+        for (const correction of corrections) {
+            const hasPosition = record(correction) && Object.prototype.hasOwnProperty.call(correction, 'queuedPosition');
+            if (!record(correction) || !exact(correction, ['id', 'text', 'delivery', 'deliveryState', 'queuedAt', 'sourceMessageId', ...(hasPosition ? ['queuedPosition'] : [])])
+                || !identity(correction.id) || typeof correction.text !== 'string' || bytes(correction.text) > TASK_HANDOFF_MAX_TEXT_BYTES
+                || (!correction.text.trim() && !identity(correction.sourceMessageId))
+                || typeof correction.delivery !== 'string' || !['subturn', 'end-of-turn'].includes(correction.delivery)
+                || typeof correction.deliveryState !== 'string' || !['pending', 'delivered', 'unknown'].includes(correction.deliveryState)
+                || !timestamp(correction.queuedAt) || !nullableIdentity(correction.sourceMessageId)
+                || (hasPosition && (!integer(correction.queuedPosition) || correction.queuedPosition >= TASK_HANDOFF_MAX_CORRECTIONS)))
+                return null;
+        }
+        if (!unique(corrections, 'id'))
+            return null;
+        const positions = corrections.map(correction => correction.queuedPosition).filter(position => position !== undefined);
+        if (new Set(positions).size !== positions.length)
+            return null;
+        const completed = value.completedObservations;
+        if (!Array.isArray(completed) || completed.length > TASK_HANDOFF_MAX_REFERENCES)
+            return null;
+        for (const observation of completed) {
+            if (!record(observation) || !exact(observation, ['observationId', 'toolCallId', 'jobId', 'status', 'exitCode', 'verification'])
+                || !identity(observation.observationId) || !identity(observation.toolCallId) || !identity(observation.jobId)
+                || typeof observation.status !== 'string' || !['completed', 'failed', 'cancelled', 'timed_out', 'interrupted'].includes(observation.status)
+                || !(observation.exitCode === null || (integer(observation.exitCode) && observation.exitCode <= 255))
+                || observation.verification !== 'unknown')
+                return null;
+        }
+        if (!unique(completed, 'observationId'))
+            return null;
+        const unresolved = value.unresolvedCalls;
+        if (!Array.isArray(unresolved) || unresolved.length > TASK_HANDOFF_MAX_REFERENCES)
+            return null;
+        for (const call of unresolved) {
+            if (!record(call) || !exact(call, ['toolCallId', 'name', 'sourceMessageId', 'outcome'])
+                || !identity(call.toolCallId) || !identity(call.name) || !identity(call.sourceMessageId) || call.outcome !== 'unknown')
+                return null;
+        }
+        if (!unique(unresolved, 'toolCallId'))
+            return null;
+        const blockers = value.blockers;
+        if (!Array.isArray(blockers) || blockers.length > TASK_HANDOFF_MAX_REFERENCES)
+            return null;
+        for (const blocker of blockers) {
+            if (!record(blocker) || !exact(blocker, ['text', 'sourceGoalId']) || !text(blocker.text)
+                || blocker.sourceGoalId !== objective.goalId || objective.kind !== 'goal')
+                return null;
+        }
+        const next = value.nextAction;
+        if (!record(next) || !exact(next, ['text', 'sourceMessageId', 'availability']))
+            return null;
+        if (next.availability === 'unavailable') {
+            if (next.text !== null || next.sourceMessageId !== null)
+                return null;
+        }
+        else if (next.availability === 'recorded') {
+            if (!text(next.text) || !identity(next.sourceMessageId))
+                return null;
+        }
+        else
+            return null;
+        const omitted = value.omitted;
+        if (!record(omitted) || !exact(omitted, ['corrections', 'completedObservations', 'unresolvedCalls', 'textBytes'])
+            || Object.values(omitted).some(count => !integer(count)))
+            return null;
+        return detached(value);
+    }
+    catch {
+        return null;
+    }
+}
+function resumeSelector(sessionId) {
+    const argument = /^[A-Za-z0-9_.-]+$/u.test(sessionId) ? sessionId : `'${sessionId.replace(/'/g, "'\\''")}'`;
+    return `ztc resume ${argument}`;
+}
+export function parseTaskHandoffProjection(value) {
+    if (!record(value) || !exact(value, ['snapshot', 'resumeCommand', 'provenance', 'ownerLiveness', 'asOf']))
+        return null;
+    const snapshot = parseTaskHandoffSnapshot(value.snapshot);
+    if (!snapshot || value.provenance !== 'validated_session_checkpoint' || value.ownerLiveness !== 'unknown'
+        || value.asOf !== snapshot.source.capturedAt || value.resumeCommand !== resumeSelector(snapshot.source.sessionId))
+        return null;
+    return { snapshot, resumeCommand: value.resumeCommand, provenance: 'validated_session_checkpoint', ownerLiveness: 'unknown', asOf: snapshot.source.capturedAt };
+}
+export function projectTaskHandoff(snapshot) {
+    const parsed = parseTaskHandoffSnapshot(snapshot);
+    if (!parsed)
+        throw new TypeError('Invalid task handoff checkpoint');
+    return { snapshot: parsed, resumeCommand: resumeSelector(parsed.source.sessionId), provenance: 'validated_session_checkpoint', ownerLiveness: 'unknown', asOf: parsed.source.capturedAt };
+}
+/** Historical checkpoint context; display alone never resumes or repeats an operation. */
+export function formatTaskHandoffContext(snapshot) {
+    const projection = projectTaskHandoff(snapshot);
+    // Rendering removes terminal control bytes without changing saved authored data.
+    const display = (value) => value.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/gu, char => char === '\n' ? ' ↵ ' : ' ');
+    const value = projection.snapshot;
+    const lines = [
+        '[Saved task handoff — source-qualified checkpoint]',
+        `Objective: ${display(value.objective.text)}`,
+        `Task: ${display(value.taskId)}; recorded status: ${value.taskStatus}${value.objective.kind === 'opening_request' ? ' (opening request; current task lifecycle unknown)' : ''}.`,
+        `Source session: ${display(value.source.sessionId)}; checkpoint as-of ${projection.asOf}; revision ${value.revision}.`,
+        `Resume: ${display(projection.resumeCommand)} (source directory: ${display(value.source.cwd)}).`,
+        `Historical owner: PID ${value.owner.pid ?? 'unknown'}, pane ${value.owner.paneId ?? 'unknown'}; current owner liveness unknown. Recorded identity does not establish current ownership.`,
+        value.objective.sourceAvailability === 'historical_checkpoint'
+            ? `Objective source: historical checkpoint only; original message ${display(value.objective.sourceMessageId ?? '')} is unavailable.`
+            : `Objective source: ${display(value.objective.goalId ?? value.objective.sourceMessageId ?? '')}; source identity present in this checkpoint.`,
+        'This checkpoint does not authorize new actions or prove semantic completion. Inspect unresolved outcomes and uncertain delivery; never automatically replay them.',
+    ];
+    for (const row of value.completedObservations)
+        lines.push(`Recorded terminal process: ${display(row.observationId)}; call ${display(row.toolCallId)}; job ${display(row.jobId)}; ${row.status}, exit ${row.exitCode ?? 'unknown'}; semantic verification unknown; current task applicability unconfirmed.`);
+    if (!value.completedObservations.length)
+        lines.push('Recorded terminal observations: unavailable.');
+    for (const row of value.unresolvedCalls)
+        lines.push(`Unresolved call: ${display(row.toolCallId)} (${display(row.name)}); outcome unknown; source message ${display(row.sourceMessageId)}.`);
+    for (const row of value.corrections) {
+        const authoredText = row.deliveryState === 'pending' ? 'deferred authored text withheld until delivery' : display(row.text);
+        lines.push(`Recorded correction ${display(row.id)}: ${row.delivery}, recorded delivery ${row.deliveryState}; current dispatch state unknown; current task applicability unconfirmed; ${authoredText}${row.sourceMessageId ? ` (source ${display(row.sourceMessageId)})` : ' (source reference unavailable)'}.`);
+    }
+    for (const row of value.blockers)
+        lines.push(`Recorded blocker (goal ${display(row.sourceGoalId)}; unverified): ${display(row.text)}`);
+    if (!value.blockers.length)
+        lines.push('Blockers: unavailable in this source checkpoint.');
+    lines.push(value.nextAction.availability === 'unavailable' ? 'Next action: unavailable in this source checkpoint.' : `Recorded next action (unverified; source ${display(value.nextAction.sourceMessageId ?? '')}): ${display(value.nextAction.text ?? '')}`);
+    const omitted = value.omitted;
+    lines.push(`Omitted from summary: ${omitted.corrections} corrections, ${omitted.completedObservations} process observations, ${omitted.unresolvedCalls} unresolved calls, ${omitted.textBytes} text bytes. Recall original source messages and result handles for omitted data.`);
+    return lines.join('\n');
+}