@zq-silk/yui 0.11.3 → 0.12.0

package/dist/review/reviewOutcomeClassifier.js

@@ -62,7 +62,7 @@ export function classifyReviewRoundOutcome(round, evidence) {
             reason: corroborationFailure
         };
 }
-/** True only when a Round may consume semantic Review budget or feed findings. */
+/** True only when a Round contains semantic Reviewer evidence. */
 export function isSemanticReviewRound(round, evidence) {
     return classifyReviewRoundOutcome(round, evidence)?.kind === "semantic";
 }

package/dist/review/reviewRound.js

@@ -120,7 +120,7 @@ export function finishReviewRound(round, status, summary, now, result = {}) {
         return terminal;
     }
     // Fail closed: a completed delta Round without an explicit, valid
-    // disposition escalates to a full Review.  Uncertainty never accepts.
+    // disposition remains non-accepting for Leader routing. Uncertainty never accepts.
     const disposition = result.deltaDisposition ?? "requires-full-review";
     const reasoning = result.deltaReasoning ?? result.report ?? summary;
     return validateReviewRound({

package/dist/review/reviewerAvailability.js

@@ -0,0 +1,69 @@
+import { nextPendingBatch, mailboxHasWork } from "../coordination/workMailbox.js";
+import { runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
+/** One authoritative read-only projection for a Task Reviewer Role slot. */
+export function projectReviewerAvailability(store, taskId, reviewerRoleName) {
+    const active = store.getActiveAgentRun(taskId, reviewerRoleName)
+        ?? store.listAgentRuns(taskId).find((run) => (run.roleName === reviewerRoleName && run.status === "active"));
+    if (active !== null && active !== undefined) {
+        return {
+            kind: "busy",
+            reviewerRoleName,
+            phase: "active-run",
+            activeRunId: active.id,
+            ...(active.reviewRoundId === undefined
+                ? {}
+                : { activeReviewRoundId: active.reviewRoundId }),
+            startedAt: active.createdAt,
+            retryable: true,
+            retryAfterSeconds: 5
+        };
+    }
+    const activeRound = store.listReviewRounds(taskId).find((round) => ((round.scope ?? "work-item") === "task"
+        && (round.status === "pending" || round.status === "running")
+        && (round.reviewerRoleName === reviewerRoleName
+            || round.executionGroup?.lanes.some(({ roleName }) => roleName === reviewerRoleName) === true)));
+    if (activeRound !== undefined) {
+        return {
+            kind: "busy",
+            reviewerRoleName,
+            phase: "review-slot",
+            activeReviewRoundId: activeRound.id,
+            startedAt: activeRound.createdAt,
+            retryable: true,
+            retryAfterSeconds: 5
+        };
+    }
+    const reviewerMailbox = store.getWorkMailbox({
+        kind: "role",
+        taskId,
+        roleName: reviewerRoleName
+    });
+    if (reviewerMailbox !== null && mailboxHasWork(reviewerMailbox)) {
+        return mailboxBusy(reviewerRoleName, "mailbox", reviewerMailbox);
+    }
+    const runtimeMailbox = store.getWorkMailbox(runtimeLifecycleTarget({
+        scope: "task",
+        taskId,
+        roleName: reviewerRoleName
+    }));
+    if (runtimeMailbox !== null && mailboxHasWork(runtimeMailbox)) {
+        return mailboxBusy(reviewerRoleName, "runtime-lifecycle", runtimeMailbox);
+    }
+    return {
+        kind: "available",
+        reviewerRoleName,
+        retryable: true
+    };
+}
+function mailboxBusy(reviewerRoleName, phase, mailbox) {
+    const pending = nextPendingBatch(mailbox);
+    const startedAt = mailbox.processing?.startedAt ?? pending?.firstQueuedAt;
+    return {
+        kind: "busy",
+        reviewerRoleName,
+        phase,
+        ...(startedAt === undefined ? {} : { startedAt }),
+        retryable: true,
+        retryAfterSeconds: 5
+    };
+}

package/dist/runtime/agentDriverObservation.js

@@ -33,18 +33,24 @@ export function mapAgentDriverUsage(input, usage) {
     });
 }
 function observation(input, mapped) {
-    const eventId = hookEventId(input, mapped);
+    const requestOccurrenceId = mapped.kind === "activity.observed"
+        && mapped.payload.usage?.semantics === "request-context"
+        ? requireRequestOccurrenceId(mapped.payload.activityId)
+        : undefined;
+    const eventId = hookEventId(input, mapped, requestOccurrenceId);
     const fence = { ...input.fence, ...mapped.fence };
     return createRuntimeObservation({
         schemaVersion: 2,
         eventId,
-        semanticKey: runtimeObservationSemanticKey({
-            eventId,
-            kind: mapped.kind,
-            fence,
-            ...(input.sequence === undefined ? {} : { sequence: input.sequence }),
-            payload: mapped.payload
-        }),
+        semanticKey: requestOccurrenceId === undefined
+            ? runtimeObservationSemanticKey({
+                eventId,
+                kind: mapped.kind,
+                fence,
+                ...(input.sequence === undefined ? {} : { sequence: input.sequence }),
+                payload: mapped.payload
+            })
+            : `provider-request:${eventId}`,
         kind: mapped.kind,
         authority: "provider-structured",
         receivedAt: input.receivedAt,
@@ -60,13 +66,21 @@ function requireMatchingDriver(input) {
         throw new Error("Agent Driver Hook fence does not match the selected Driver.");
     }
 }
-function hookEventId(input, mapped) {
+function hookEventId(input, mapped, requestOccurrenceId) {
     const digest = createHash("sha256").update(JSON.stringify([
         input.driver.id,
         input.hookEventName,
         input.fence,
         mapped.kind,
-        mapped.payload
+        ...(requestOccurrenceId === undefined
+            ? [mapped.payload]
+            : [{ requestOccurrenceId }])
     ])).digest("hex");
     return `runtime-observation-${digest}`;
 }
+function requireRequestOccurrenceId(value) {
+    if (value === undefined || value.trim().length === 0 || value.includes("\0")) {
+        throw new Error("Request-context usage requires a stable activity id.");
+    }
+    return value.trim();
+}

package/dist/runtime/builtinAgentDrivers.js

@@ -51,8 +51,8 @@ const STRUCTURED_CLI_CAPABILITIES = Object.freeze({
         preInputReadiness: "unavailable",
         promptAcceptance: "exact",
         turnLifecycle: "exact",
-        // Model activity is inferred from usage deltas; these are the operation
-        // boundaries the current Hook surfaces actually expose.
+        // Transcript sources may emit an explicit activity identity separately
+        // from usage snapshots. Numeric token values never decide runtime health.
         operations: Object.freeze(["tool", "subagent"]),
         waiting: Object.freeze(["permission"]),
         usage: "streaming-cumulative",
@@ -70,7 +70,8 @@ export const BUILTIN_AGENT_DRIVERS = Object.freeze([
             observation: Object.freeze({
                 ...STRUCTURED_CLI_CAPABILITIES.observation,
                 sessionBootstrap: "preallocated",
-                preInputReadiness: "exact"
+                preInputReadiness: "exact",
+                usage: "event-snapshot"
             })
         }),
         runtime: Object.freeze({

package/dist/runtime/builtinTranscriptObserver.js

@@ -5,6 +5,7 @@ const MAX_INITIAL_TAIL_BYTES = 1024 * 1024;
 const MAX_SAMPLE_BYTES = 1024 * 1024;
 const MAX_REMAINDER_BYTES = 64 * 1024;
 const MAX_CLAUDE_MESSAGES = 4_096;
+const INITIAL_CONTINUITY_EPOCH = "initial";
 export function transcriptObserverSource(driverId, input) {
     if (input.hookEventName !== "UserPromptSubmit")
         return null;
@@ -12,12 +13,8 @@ export function transcriptObserverSource(driverId, input) {
     if (typeof locator !== "string" || !isAbsolute(locator) || locator.includes("\0"))
         return null;
     const sessionId = identity(input.payload.session_id) ?? "session";
-    const turnId = identity(input.payload.prompt_id)
-        ?? identity(input.payload.turn_id)
-        ?? input.occurrenceId
-        ?? "turn";
     const digest = createHash("sha256")
-        .update(JSON.stringify([driverId, sessionId, turnId, locator]))
+        .update(JSON.stringify([driverId, sessionId, locator]))
         .digest("hex");
     return Object.freeze({
         schemaVersion: 1,
@@ -26,13 +23,13 @@ export function transcriptObserverSource(driverId, input) {
         locator
     });
 }
-export async function codexTranscriptObserver(source, cursor) {
-    return sampleJsonl(source, cursor, parseCodexLines);
+export async function codexTranscriptObserver(source, cursor, resume) {
+    return sampleJsonl(source, cursor, resume, parseCodexLines);
 }
-export async function claudeTranscriptObserver(source, cursor) {
-    return sampleJsonl(source, cursor, parseClaudeLines);
+export async function claudeTranscriptObserver(source, cursor, resume) {
+    return sampleJsonl(source, cursor, resume, parseClaudeLines);
 }
-async function sampleJsonl(source, rawCursor, parse) {
+async function sampleJsonl(source, rawCursor, resume, parse) {
     const previous = normalizeCursor(rawCursor);
     let metadata;
     try {
@@ -43,8 +40,33 @@ async function sampleJsonl(source, rawCursor, parse) {
     }
     if (!metadata.isFile())
         return unavailable(previous, new Error("observer locator is not a file"));
-    const reset = previous !== undefined && metadata.size < previous.offset;
+    const fileFingerprint = transcriptFileFingerprint(metadata);
+    const checkpoint = previous === undefined
+        ? transcriptCheckpoint(resume?.latestCheckpoint, resume?.latestOccurrenceId)
+        : undefined;
+    let checkpointMatches = false;
+    if (previous === undefined && checkpoint !== undefined) {
+        try {
+            checkpointMatches = await matchesTranscriptCheckpoint(source.locator, metadata, fileFingerprint, checkpoint);
+        }
+        catch (error) {
+            return unavailable(previous, error);
+        }
+    }
+    const reset = previous !== undefined && (previous.fileFingerprint === undefined
+        || previous.fileFingerprint !== fileFingerprint
+        || metadata.size < previous.offset
+        || (metadata.size === previous.offset && (previous.fileCtimeMs === undefined
+            || previous.fileCtimeMs !== metadata.ctimeMs)));
+    const offlineReset = previous === undefined
+        && checkpoint !== undefined
+        && !checkpointMatches;
     const initial = previous === undefined || reset;
+    const continuityEpoch = reset || offlineReset
+        ? rotateContinuityEpoch(previous?.continuityEpoch ?? checkpoint?.continuityEpoch ?? INITIAL_CONTINUITY_EPOCH, fileFingerprint)
+        : previous?.continuityEpoch
+            ?? checkpoint?.continuityEpoch
+            ?? initialContinuityEpoch(fileFingerprint);
     const start = initial
         ? Math.max(0, metadata.size - MAX_INITIAL_TAIL_BYTES)
         : previous.offset;
@@ -67,32 +89,80 @@ async function sampleJsonl(source, rawCursor, parse) {
         return unavailable(previous, error);
     }
     let text = `${initial ? "" : previous?.remainder ?? ""}${bytes.toString("utf8")}`;
+    let textOffset = initial
+        ? start
+        : previous.offset - Buffer.byteLength(previous.remainder, "utf8");
     if (initial && start > 0) {
         const firstLineEnd = text.indexOf("\n");
-        text = firstLineEnd < 0 ? "" : text.slice(firstLineEnd + 1);
+        if (firstLineEnd < 0) {
+            textOffset += Buffer.byteLength(text, "utf8");
+            text = "";
+        }
+        else {
+            const discarded = text.slice(0, firstLineEnd + 1);
+            textOffset += Buffer.byteLength(discarded, "utf8");
+            text = text.slice(firstLineEnd + 1);
+        }
     }
     const complete = text.endsWith("\n");
     const split = text.split("\n");
     const remainder = complete ? "" : split.pop() ?? "";
+    if (complete)
+        split.pop();
+    let lineOffset = textOffset;
+    const lines = split.map((content) => {
+        const line = Object.freeze({
+            content,
+            offset: lineOffset,
+            continuityEpoch,
+            fileFingerprint,
+            observedFileSize: metadata.size,
+            observedFileCtimeMs: metadata.ctimeMs
+        });
+        lineOffset += Buffer.byteLength(content, "utf8") + 1;
+        return line;
+    });
     const boundedRemainder = Buffer.byteLength(remainder, "utf8") <= MAX_REMAINDER_BYTES
         ? remainder
         : "";
-    const parsed = parse(split, initial ? {} : previous?.state ?? {});
+    const parsed = parse(lines, initial ? {} : previous?.state ?? {});
+    const clippedBaseline = initial && start > 0;
+    const discontinuousBaseline = clippedBaseline || reset || offlineReset;
+    // A verified checkpoint inside this bounded read proves continuity only for
+    // the occurrences that follow it. Everything earlier remains partial.
+    const recoveredCheckpointIndex = checkpointMatches && checkpoint !== undefined
+        ? parsed.usages.findIndex(({ occurrenceId }) => occurrenceId === checkpoint.occurrenceId)
+        : -1;
+    const usages = discontinuousBaseline
+        ? parsed.usages.map((occurrence, index) => (recoveredCheckpointIndex >= 0 && index > recoveredCheckpointIndex
+            ? occurrence
+            : Object.freeze({
+                ...occurrence,
+                observationQuality: "partial"
+            })))
+        : parsed.usages;
     const nextCursor = Object.freeze({
         offset: start + bytes.length,
         remainder: boundedRemainder,
-        state: parsed.state
+        state: parsed.state,
+        continuityEpoch,
+        fileFingerprint,
+        fileCtimeMs: metadata.ctimeMs
     });
     const fellBehind = start + bytes.length < metadata.size;
     const detail = parsed.degraded
+        ?? (clippedBaseline
+            ? "Initial transcript history was clipped; request-boundary evidence is partial."
+            : undefined)
         ?? (fellBehind ? "Transcript observer is catching up with a bounded read." : undefined)
+        ?? (offlineReset ? "Transcript changed while the observer was offline; baseline was reset." : undefined)
         ?? (reset ? "Transcript was truncated; observer baseline was reset." : undefined)
         ?? (remainder !== boundedRemainder ? "Oversized partial transcript line was discarded." : undefined);
     return Object.freeze({
         cursor: nextCursor,
         status: detail === undefined ? "healthy" : "degraded",
         ...(detail === undefined ? {} : { detail }),
-        ...(parsed.usage === undefined ? {} : { usage: parsed.usage }),
+        ...(usages.length === 0 ? {} : { usages: Object.freeze(usages) }),
         ...(parsed.activityId === undefined ? {} : {
             activity: "model",
             activityId: parsed.activityId
@@ -101,12 +171,17 @@ async function sampleJsonl(source, rawCursor, parse) {
 }
 function parseCodexLines(lines, state) {
     let usage = usageFrom(state.usage);
-    let activityId;
+    // Keep every recognized-but-incomplete request boundary durable. Reuse the
+    // last complete cumulative total as a partial marker until the next exact
+    // occurrence restores the numeric counter.
+    let usageContinuityGap = state.usageContinuityGap === true;
+    const usages = [];
     let malformed = 0;
+    let incompleteUsage = 0;
     for (const line of lines) {
-        const entry = jsonObject(line);
+        const entry = jsonObject(line.content);
         if (entry === null) {
-            if (line.trim().length > 0)
+            if (line.content.trim().length > 0)
                 malformed += 1;
             continue;
         }
@@ -115,27 +190,51 @@ function parseCodexLines(lines, state) {
         const payload = object(entry.payload);
         if (payload?.type !== "token_count")
             continue;
+        // Codex also emits token_count records that carry rate limits only. They
+        // contain no usage occurrence and therefore create no request boundary.
+        if (payload.info === null)
+            continue;
         const candidate = normalizedCodexUsage(object(object(payload.info)?.total_token_usage));
-        if (candidate === undefined)
+        if (candidate === undefined) {
+            usages.push(Object.freeze({
+                ...transcriptOccurrence(line),
+                observationQuality: "partial",
+                ...(usage === undefined ? {} : { usage })
+            }));
+            usageContinuityGap = true;
+            incompleteUsage += 1;
             continue;
+        }
         usage = candidate;
-        activityId = `usage:${candidate.inputTokens}:${candidate.outputTokens}`;
+        usages.push(Object.freeze({
+            ...transcriptOccurrence(line),
+            ...(usageContinuityGap ? { observationQuality: "partial" } : {}),
+            usage: candidate
+        }));
+        usageContinuityGap = false;
     }
+    const degraded = transcriptParseDetail(malformed, incompleteUsage);
     return Object.freeze({
-        state: Object.freeze({ ...(usage === undefined ? {} : { usage }) }),
-        ...(usage === undefined ? {} : { usage }),
-        ...(activityId === undefined ? {} : { activityId }),
-        ...(malformed === 0 ? {} : { degraded: `${malformed} malformed transcript line(s) ignored.` })
+        state: Object.freeze({
+            ...(usage === undefined ? {} : { usage }),
+            ...(usageContinuityGap ? { usageContinuityGap: true } : {})
+        }),
+        usages: Object.freeze(usages),
+        ...(degraded === undefined ? {} : { degraded })
     });
 }
 function parseClaudeLines(lines, state) {
     const messages = messageState(state.messages);
+    let usageContinuityGap = state.usageContinuityGap === true;
+    const usages = [];
     let activityId;
     let malformed = 0;
+    let incompleteUsage = 0;
+    let bounded = false;
     for (const line of lines) {
-        const entry = jsonObject(line);
+        const entry = jsonObject(line.content);
         if (entry === null) {
-            if (line.trim().length > 0)
+            if (line.content.trim().length > 0)
                 malformed += 1;
             continue;
         }
@@ -143,50 +242,209 @@ function parseClaudeLines(lines, state) {
             continue;
         const message = object(entry.message);
         const usage = normalizedClaudeUsage(object(message?.usage));
-        if (usage === undefined)
+        if (usage === undefined) {
+            usages.push(Object.freeze({
+                ...transcriptOccurrence(line),
+                observationQuality: "partial"
+            }));
+            usageContinuityGap = true;
+            incompleteUsage += 1;
             continue;
+        }
         const key = identity(message?.id) === undefined
             ? identity(entry.uuid) === undefined ? undefined : `entry:${identity(entry.uuid)}`
             : `message:${identity(message?.id)}`;
-        if (key === undefined)
+        if (key === undefined) {
+            usages.push(Object.freeze({
+                ...transcriptOccurrence(line),
+                observationQuality: "partial"
+            }));
+            usageContinuityGap = true;
+            incompleteUsage += 1;
             continue;
+        }
         messages[key] = usage;
-        activityId = `${key}:${usage.inputTokens}:${usage.outputTokens}`;
-    }
-    const keys = Object.keys(messages);
-    let degraded = malformed === 0 ? undefined : `${malformed} malformed transcript line(s) ignored.`;
-    if (keys.length > MAX_CLAUDE_MESSAGES) {
-        for (const key of keys.slice(0, keys.length - MAX_CLAUDE_MESSAGES))
-            delete messages[key];
-        degraded = "Claude transcript message baseline was bounded to the newest entries.";
+        activityId = key;
+        const keys = Object.keys(messages);
+        if (keys.length > MAX_CLAUDE_MESSAGES) {
+            for (const oldKey of keys.slice(0, keys.length - MAX_CLAUDE_MESSAGES)) {
+                delete messages[oldKey];
+            }
+            bounded = true;
+        }
+        usages.push(Object.freeze({
+            ...transcriptOccurrence(line),
+            activityId: key,
+            ...(usageContinuityGap ? { observationQuality: "partial" } : {}),
+            usage
+        }));
+        usageContinuityGap = false;
     }
-    const usage = sumUsage(Object.values(messages));
+    const degraded = transcriptParseDetail(malformed, incompleteUsage, bounded);
     return Object.freeze({
-        state: Object.freeze({ messages: Object.freeze(messages) }),
-        ...(usage === undefined ? {} : { usage }),
+        state: Object.freeze({
+            messages: Object.freeze(messages),
+            ...(usageContinuityGap ? { usageContinuityGap: true } : {})
+        }),
+        usages: Object.freeze(usages),
         ...(activityId === undefined ? {} : { activityId }),
         ...(degraded === undefined ? {} : { degraded })
     });
 }
+function transcriptParseDetail(malformed, incompleteUsage, bounded = false) {
+    const details = [];
+    if (malformed > 0)
+        details.push(`${malformed} malformed transcript line(s) ignored.`);
+    if (incompleteUsage > 0) {
+        details.push(`${incompleteUsage} incomplete usage record(s) created a request-boundary gap.`);
+    }
+    if (bounded)
+        details.push("Claude transcript message baseline was bounded to the newest entries.");
+    return details.length === 0 ? undefined : details.join(" ");
+}
+function transcriptOccurrence(line) {
+    // The durable semantic key retains this bounded checkpoint. A Controller
+    // restart can therefore reuse the epoch only when the sampled file is still
+    // the same continuity, without persisting the process-local cursor itself.
+    const digest = createHash("sha256").update(line.content).digest("hex");
+    const occurrenceId = `transcript-v1:${Buffer.from(JSON.stringify({
+        continuityEpoch: line.continuityEpoch,
+        fileFingerprint: line.fileFingerprint,
+        offset: line.offset,
+        digest
+    }), "utf8").toString("base64url")}`;
+    const resumeCheckpoint = `transcript-checkpoint-v1:${Buffer.from(JSON.stringify({
+        occurrenceId,
+        continuityEpoch: line.continuityEpoch,
+        fileFingerprint: line.fileFingerprint,
+        offset: line.offset,
+        length: Buffer.byteLength(line.content, "utf8"),
+        digest,
+        observedFileSize: line.observedFileSize,
+        observedFileCtimeMs: line.observedFileCtimeMs
+    }), "utf8").toString("base64url")}`;
+    return Object.freeze({ occurrenceId, resumeCheckpoint });
+}
+function initialContinuityEpoch(fileFingerprint) {
+    return continuityEpoch("initial", fileFingerprint);
+}
+function rotateContinuityEpoch(previous, fileFingerprint) {
+    return continuityEpoch(previous, fileFingerprint);
+}
+function continuityEpoch(previous, fileFingerprint) {
+    return `sha256:${createHash("sha256")
+        .update(JSON.stringify([previous, fileFingerprint]))
+        .digest("hex")}`;
+}
+function transcriptFileFingerprint(metadata) {
+    return `sha256:${createHash("sha256").update(JSON.stringify([
+        metadata.dev,
+        metadata.ino
+    ])).digest("hex")}`;
+}
+async function matchesTranscriptCheckpoint(locator, metadata, fileFingerprint, checkpoint) {
+    if (checkpoint.fileFingerprint !== fileFingerprint
+        || metadata.size < checkpoint.observedFileSize)
+        return false;
+    if (metadata.size === checkpoint.observedFileSize) {
+        return metadata.ctimeMs === checkpoint.observedFileCtimeMs;
+    }
+    if (checkpoint.offset + checkpoint.length + 1 > metadata.size)
+        return false;
+    const handle = await open(locator, "r");
+    try {
+        const bytes = Buffer.alloc(checkpoint.length + 1);
+        const read = await handle.read(bytes, 0, bytes.length, checkpoint.offset);
+        return read.bytesRead === bytes.length
+            && bytes.at(-1) === 0x0a
+            && createHash("sha256")
+                .update(bytes.subarray(0, checkpoint.length))
+                .digest("hex") === checkpoint.digest;
+    }
+    finally {
+        await handle.close();
+    }
+}
+function transcriptCheckpoint(raw, occurrenceId) {
+    const prefix = "transcript-checkpoint-v1:";
+    if (raw === undefined || occurrenceId === undefined || !raw.startsWith(prefix))
+        return undefined;
+    try {
+        const value = JSON.parse(Buffer.from(raw.slice(prefix.length), "base64url").toString("utf8"));
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            return undefined;
+        const checkpoint = value;
+        return checkpoint.occurrenceId !== occurrenceId
+            || typeof checkpoint.continuityEpoch !== "string"
+            || checkpoint.continuityEpoch.length === 0
+            || typeof checkpoint.fileFingerprint !== "string"
+            || checkpoint.fileFingerprint.length === 0
+            || !Number.isSafeInteger(checkpoint.offset)
+            || checkpoint.offset < 0
+            || !Number.isSafeInteger(checkpoint.length)
+            || checkpoint.length < 0
+            || typeof checkpoint.digest !== "string"
+            || checkpoint.digest.length === 0
+            || !Number.isSafeInteger(checkpoint.observedFileSize)
+            || checkpoint.observedFileSize < 0
+            || typeof checkpoint.observedFileCtimeMs !== "number"
+            || !Number.isFinite(checkpoint.observedFileCtimeMs)
+            || checkpoint.observedFileCtimeMs < 0
+            ? undefined
+            : Object.freeze({
+                occurrenceId,
+                continuityEpoch: checkpoint.continuityEpoch,
+                fileFingerprint: checkpoint.fileFingerprint,
+                offset: checkpoint.offset,
+                length: checkpoint.length,
+                digest: checkpoint.digest,
+                observedFileSize: checkpoint.observedFileSize,
+                observedFileCtimeMs: checkpoint.observedFileCtimeMs
+            });
+    }
+    catch {
+        return undefined;
+    }
+}
 function normalizeCursor(input) {
     if (input === undefined)
         return undefined;
     const offset = input.offset;
     const remainder = input.remainder;
     const state = input.state;
+    const continuityEpoch = input.continuityEpoch;
+    const fileFingerprint = input.fileFingerprint;
+    const fileCtimeMs = input.fileCtimeMs;
     if (!Number.isSafeInteger(offset) || offset < 0
         || typeof remainder !== "string"
-        || state === null || typeof state !== "object" || Array.isArray(state))
+        || state === null || typeof state !== "object" || Array.isArray(state)
+        || (continuityEpoch !== undefined
+            && (typeof continuityEpoch !== "string" || continuityEpoch.length === 0))
+        || (fileFingerprint !== undefined
+            && (typeof fileFingerprint !== "string" || fileFingerprint.length === 0))
+        || (fileCtimeMs !== undefined
+            && (typeof fileCtimeMs !== "number" || !Number.isFinite(fileCtimeMs) || fileCtimeMs < 0))) {
         return undefined;
+    }
     return Object.freeze({
         offset: offset,
         remainder,
-        state: state
+        state: state,
+        continuityEpoch: typeof continuityEpoch === "string"
+            ? continuityEpoch
+            : INITIAL_CONTINUITY_EPOCH,
+        ...(typeof fileFingerprint === "string" ? { fileFingerprint } : {}),
+        ...(typeof fileCtimeMs === "number" ? { fileCtimeMs } : {})
     });
 }
 function unavailable(cursor, error) {
     return Object.freeze({
-        cursor: cursor ?? Object.freeze({ offset: 0, remainder: "", state: Object.freeze({}) }),
+        cursor: cursor ?? Object.freeze({
+            offset: 0,
+            remainder: "",
+            state: Object.freeze({}),
+            continuityEpoch: INITIAL_CONTINUITY_EPOCH
+        }),
         status: "unavailable",
         detail: error instanceof Error ? error.message : String(error)
     });
@@ -215,7 +473,7 @@ function normalizedClaudeUsage(usage) {
     const cacheCreated = integer(usage?.cache_creation_input_tokens) ?? 0;
     const reasoningTokens = integer(object(usage?.output_tokens_details)?.thinking_tokens);
     return Object.freeze({
-        semantics: "cumulative-session",
+        semantics: "request-context",
         inputTokens: directInput + cacheRead + cacheCreated,
         outputTokens,
         cachedInputTokens: cacheRead + cacheCreated,
@@ -248,27 +506,6 @@ function usageFrom(value) {
         ...(reasoningTokens === undefined ? {} : { reasoningTokens })
     });
 }
-function sumUsage(values) {
-    if (values.length === 0)
-        return undefined;
-    let inputTokens = 0;
-    let outputTokens = 0;
-    let cachedInputTokens = 0;
-    let reasoningTokens = 0;
-    for (const usage of values) {
-        inputTokens += usage.inputTokens;
-        outputTokens += usage.outputTokens;
-        cachedInputTokens += usage.cachedInputTokens ?? 0;
-        reasoningTokens += usage.reasoningTokens ?? 0;
-    }
-    return Object.freeze({
-        semantics: "cumulative-session",
-        inputTokens,
-        outputTokens,
-        cachedInputTokens,
-        ...(reasoningTokens === 0 ? {} : { reasoningTokens })
-    });
-}
 function jsonObject(line) {
     if (line.trim().length === 0)
         return null;