@zq-silk/yui 0.16.1 → 0.16.2

package/dist/runtime/agentHost.js

@@ -5,16 +5,16 @@ import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { withSessionContextPointer } from "../context/sessionBootstrapManifest.js";
-import { publishStructuredConversationRecoverability, publishStructuredProviderAccepted, publishStructuredProviderActivity, publishStructuredProviderAttachmentExit, publishStructuredProviderConnection, publishStructuredProviderGoal, publishStructuredProviderInputObserved, publishStructuredProviderInputSettlement, publishStructuredProviderOpened, publishStructuredProviderStarted, publishStructuredProviderTerminal, structuredProviderEventDelivery } from "../controller/structuredProviderObservation.js";
+import { publishStructuredConversationRecoverability, publishStructuredProviderAccepted, publishStructuredProviderActivity, publishStructuredProviderAttachmentExit, publishStructuredProviderConnection, publishStructuredProviderDiagnostic, publishStructuredProviderGoal, publishStructuredProviderInputObserved, publishStructuredProviderInputSettlement, publishStructuredProviderOpened, publishStructuredProviderStarted, publishStructuredProviderTerminal, structuredProviderEventDelivery } from "../controller/structuredProviderObservation.js";
 import { callController, controllerCallMayHaveApplied, ControllerClientError } from "../core/controllerClient.js";
 import { readHomeFilesystemId } from "../core/homeFilesystemIdentity.js";
-import { FILE_TASK_CONTROLLER_PROTOCOL_VERSION } from "../core/protocol.js";
 import { isForeignHandoverLockHeld } from "../release/runtimeRelease.js";
 import { yuiTmuxServerName, yuiTmuxSessionName } from "../tmux/tmuxManager.js";
 import { tmuxSocketDirectory } from "../tmux/tmuxSocketEndpoint.js";
 import { createAgentEndpointOwner } from "./agentEndpointOwnership.js";
 import { providerDeliveryFailure, providerDeliveryFailureFrom, redactAgentErrorText, serializeAgentErrorRaw } from "./agentError.js";
-import { AGENT_HOST_CONTROL_PROTOCOL, AGENT_HOST_EVENT_PROTOCOL } from "./agentHostProtocol.js";
+import { AGENT_HOST_CONTROL_PROTOCOL } from "./agentHostProtocol.js";
+import { closeAgentHostEndpoints } from "./agentHostCleanup.js";
 import { readAgentRunConfigurationObservation, unknownAgentRunConfiguration } from "./agentRunConfiguration.js";
 import { CodexPreSubmissionError } from "./codexAppServerRuntime.js";
 import { runCodexInteractiveHost } from "./codexInteractiveHost.js";
@@ -99,6 +99,12 @@ export async function runAgentHost(input) {
     let conversationRecoverability = "unknown";
     let authority;
     let hostStopRequested = false;
+    const reportDiagnostic = async (diagnostic) => {
+        const observedPayload = activeRunPayload ?? sessionPayload ?? payload;
+        await publishStructuredProviderDiagnostic({
+            home: input.home, environment: observedPayload.environment, diagnostic
+        });
+    };
     let snapshot = hostSnapshot("idle");
     let dispatchTail = Promise.resolve();
     let promptHuman = () => { };
@@ -361,6 +367,9 @@ export async function runAgentHost(input) {
                         handleStarted(event.value, currentPayload);
                     else if (event.type === "terminal")
                         handleTerminal(event.value);
+                    else if (event.type === "diagnostic")
+                        void enqueueSerialized(() => reportDiagnostic(event.value))
+                            .catch(error => process.stderr.write(`Provider diagnostic delivery failed: ${serializeAgentErrorRaw(error)}\n`));
                     else if (event.type === "goal")
                         handleGoal(event.value);
                     else
@@ -617,6 +626,9 @@ export async function runAgentHost(input) {
                         handleStarted(event.value, next);
                     else if (event.type === "terminal")
                         handleTerminal(event.value);
+                    else if (event.type === "diagnostic")
+                        void enqueueSerialized(() => reportDiagnostic(event.value))
+                            .catch(error => process.stderr.write(`Provider diagnostic delivery failed: ${serializeAgentErrorRaw(error)}\n`));
                     else if (event.type === "goal")
                         handleGoal(event.value);
                     else
@@ -1214,55 +1226,13 @@ export async function runAgentHost(input) {
         if (forceKillTimer !== undefined)
             clearTimeout(forceKillTimer);
         humanConsole?.close();
-        // Ask the client to exit, then hand back the Session's hold. The reference
-        // is only actually returned once the client proves it exited, so the bounded
-        // stop below waits on the real dependency instead of an assumed one.
-        session?.detach();
-        const adapterId = endpointAdapterId;
-        await endpointLease?.release();
-        endpointLease = undefined;
-        if (adapterId !== undefined) {
-            // Stop new acquisition and wait a bounded time for what is already
-            // running. A timeout reports the references and pending effects that are
-            // genuinely still in use; it never escalates to killing a Provider this
-            // Endpoint does not own, and it never reports quiescence it cannot prove.
-            const drain = await endpointOwner.stop(adapterId, ENDPOINT_DRAIN_TIMEOUT_MS);
-            if (!drain.quiescent) {
-                const detail = `Endpoint stop ${drain.timedOut ? "timed out" : "returned"} after ${drain.waitedMs}ms`
-                    + ` (bound ${ENDPOINT_DRAIN_TIMEOUT_MS}ms); ${drain.references} reference(s), `
-                    + `${drain.opening} opening client(s) and `
-                    + `${drain.sessions.reduce((total, held) => total + held.pending.length, 0)} pending effect(s) `
-                    + "may still be in use. Owned client resources are unknown.";
-                updateSnapshot(hostSnapshot(snapshot.state, {
-                    ...definedFields({
-                        adapterId,
-                        nativeSessionId: snapshot.nativeSessionId,
-                        conversationId: snapshot.conversationId
-                    }),
-                    ...authorityFields(),
-                    detail
-                }));
-                // The snapshot is about to stop being reachable, and a stop this process
-                // could not prove quiescent must remain diagnosable afterwards. Written
-                // to the Host's own stream, which its pane and logs retain.
-                process.stderr.write(`${detail}\n`);
-            }
-        }
-        // Final cleanup is bounded on its own deadline. The bounded stop above may
-        // already have given up on a client that never proves exit, and waiting for
-        // that same drain again would leave the control socket open and this function
-        // never returning. Anything still held is reported, not silently released.
-        const remaining = await endpointOwner.close(ENDPOINT_DRAIN_TIMEOUT_MS).catch(() => []);
-        const held = remaining.filter((drain) => !drain.quiescent);
-        if (held.length > 0) {
-            const references = held.reduce((total, drain) => total + drain.references, 0);
-            const opening = held.reduce((total, drain) => total + drain.opening, 0);
-            process.stderr.write(`Endpoint cleanup returned with ${references} reference(s) and ${opening} opening client(s) `
-                + `still held across ${held.length} implementation(s) (bound ${ENDPOINT_DRAIN_TIMEOUT_MS}ms); `
-                + "those implementations stay detached and undisposed. Owned client resources are unknown.\n");
-        }
-        await control.close();
-        void sessionPayload;
+        await closeAgentHostEndpoints({
+            owner: endpointOwner, session, lease: endpointLease, adapterId: endpointAdapterId,
+            attemptId: activeRunAttemptId ?? lastTerminal?.attemptId,
+            nativeTurnId: activeNativeTurnId ?? lastTerminal?.nativeTurnId,
+            timeoutMs: ENDPOINT_DRAIN_TIMEOUT_MS,
+            report: reportDiagnostic, closeControl: () => control.close()
+        });
     }
 }
 /** Host-restart-independent OS custody. No secret or launch payload is stored. */
@@ -1497,16 +1467,6 @@ export async function openAgentHostControl(home, payload, snapshot, dispatch) {
                         ...result,
                         snapshot: {
                             ...result.snapshot,
-                            compatibility: {
-                                control: AGENT_HOST_CONTROL_PROTOCOL, events: AGENT_HOST_EVENT_PROTOCOL,
-                                rpc: FILE_TASK_CONTROLLER_PROTOCOL_VERSION, storage: "controller-owned"
-                            },
-                            hostProcess: { pid: process.pid, startIdentity: readLinuxProcessIdentity(process.pid).startIdentity },
-                            owner: {
-                                scope: payload.environment.YUI_SESSION_SCOPE ?? "task",
-                                ...(payload.environment.YUI_TASK_ID === undefined ? {} : { taskId: payload.environment.YUI_TASK_ID }),
-                                roleName: payload.environment.YUI_ROLE ?? "unknown-role"
-                            },
                             ...(payload.environment.YUI_SESSION_SCOPE !== "task" ? {} : {
                                 eventDelivery: structuredProviderEventDelivery(home, payload.environment, result.snapshot.nativeSessionId)
                             })

package/dist/runtime/agentHostCleanup.js

@@ -0,0 +1,85 @@
+import { providerDeliveryFailureFrom, serializeAgentErrorRaw } from "./agentError.js";
+/** Finish the Host's owned cleanup steps even when one fails. Neither a failed
+ * inspection nor a timeout is proof that an implementation or client drained. */
+export async function closeAgentHostEndpoints(input) {
+    const errors = [];
+    let lastObservedDrain;
+    const report = async (operation, error, drains) => {
+        const failure = providerDeliveryFailureFrom(error, {
+            phase: "host-stop", inputDisposition: "unknown",
+            detail: `Endpoint ${operation}: ${error instanceof Error ? error.message : String(error)}. Owned client resources are unknown.`
+        });
+        const raw = serializeAgentErrorRaw({
+            operation, error, adapterId: input.adapterId, implementation: input.lease?.implementation,
+            nativeSessionId: input.session?.nativeSessionId, processInstanceId: input.session?.processInstanceId,
+            attemptId: input.attemptId, timeoutMs: input.timeoutMs,
+            ...(drains === undefined ? { lastObservedDrain } : { drains }),
+            unknown: "Current resource quiescence and pending Provider effects; no input is replayed."
+        });
+        // The Host stream remains evidence even if its Inbox cannot be written.
+        process.stderr.write(`${raw}\n`);
+        if (input.session === undefined)
+            return;
+        try {
+            await input.report({
+                nativeSessionId: input.session.nativeSessionId,
+                ...(input.attemptId === undefined ? {} : { attemptId: input.attemptId }),
+                ...(input.nativeTurnId === undefined ? {} : { nativeTurnId: input.nativeTurnId }),
+                failure: { ...failure, raw }
+            });
+        }
+        catch (error) {
+            errors.push(error);
+            process.stderr.write(`Endpoint cleanup diagnostic delivery failed: ${serializeAgentErrorRaw(error)}\n`);
+        }
+    };
+    try {
+        try {
+            input.session?.detach();
+        }
+        catch (error) {
+            errors.push(error);
+            await report("detach failed", error);
+        }
+        try {
+            await input.lease?.release();
+        }
+        catch (error) {
+            errors.push(error);
+            await report("lease release failed", error);
+        }
+        if (input.adapterId !== undefined) {
+            try {
+                lastObservedDrain = await input.owner.stop(input.adapterId, input.timeoutMs);
+                if (!lastObservedDrain.quiescent) {
+                    await report("stop incomplete", new Error("The bounded stop did not prove quiescence."), [lastObservedDrain]);
+                }
+            }
+            catch (error) {
+                errors.push(error);
+                await report("stop failed", error);
+            }
+        }
+        try {
+            const remaining = await input.owner.close(input.timeoutMs);
+            const held = remaining.filter(drain => !drain.quiescent);
+            if (held.length > 0)
+                await report("close incomplete", new Error("Endpoint references remain held."), held);
+        }
+        catch (error) {
+            errors.push(error);
+            await report("close failed", error);
+        }
+    }
+    finally {
+        try {
+            await input.closeControl();
+        }
+        catch (error) {
+            errors.push(error);
+            await report("control close failed", error);
+        }
+    }
+    if (errors.length > 0)
+        throw new AggregateError(errors, "Agent Host cleanup failed; resource effects remain unknown.");
+}

package/dist/runtime/agentHostProtocol.js

@@ -1,5 +1,5 @@
 import { createSessionOwnerIdentity } from "./sessionOwnerIdentity.js";
-/** Independent of CLI/RPC and Home schema. Keep v1 readable while v1 Hosts live. */
+/** Current Host event source contract, independent of Home storage access. */
 export const AGENT_HOST_EVENT_PROTOCOL = "yui-agent-host-events/v1";
 export const AGENT_HOST_CONTROL_PROTOCOL = "yui-agent-host/v5";
 export function readAgentHostObservationSource(value) {

package/dist/runtime/builtinAgentDrivers.js

@@ -93,7 +93,8 @@ export const BUILTIN_AGENT_DRIVERS = Object.freeze([
         }),
         runtime: Object.freeze({
             nativeSessionId: ({ payload }) => (optionalIdentityFrom(payload, ["session_id"])),
-            nativeTurnId: ({ payload }) => (optionalIdentityFrom(payload, ["prompt_id", "turn_id"])),
+            nativeTurnId: ({ hookEventName, payload }) => (optionalIdentityFrom(payload, hookEventName === "MessageDisplay"
+                ? ["prompt_id", "turn_id"] : ["prompt_id"])),
             mapError: mapClaudeAgentError,
             mapHook: ({ hookEventName, payload, occurrenceId }) => (mapClaudeHook(hookEventName, payload, occurrenceId)),
             classifyHook: ({ hookEventName, payload }) => Object.freeze({
@@ -102,7 +103,7 @@ export const BUILTIN_AGENT_DRIVERS = Object.freeze([
                     : {}),
                 terminal: isTerminalHook(hookEventName),
                 ...(hookEventName !== "SubagentStop" ? {} : {
-                    continuationId: subagentId(payload),
+                    continuationId: firstIdentity(payload, ["agent_id"], "Claude subagent id"),
                 })
             }),
             observer: Object.freeze({
@@ -295,16 +296,6 @@ export function builtinAgentDriverRegistry() {
     return registry;
 }
 function mapClaudeHook(name, payload, occurrenceId) {
-    const lifecycle = mapClaudeLifecycleHook(name, payload, occurrenceId);
-    const goal = claudeGoalObservation(payload, occurrenceId);
-    if (goal === undefined)
-        return lifecycle;
-    return Object.freeze([
-        ...(Array.isArray(lifecycle) ? lifecycle : [lifecycle]),
-        goal
-    ]);
-}
-function mapClaudeLifecycleHook(name, payload, occurrenceId) {
     switch (name) {
         case "SessionStart":
             return [
@@ -316,15 +307,15 @@ function mapClaudeLifecycleHook(name, payload, occurrenceId) {
         case "UserPromptSubmit":
             return mapped("turn.accepted");
         case "PreToolUse":
-            return operation("operation.started", "tool", toolId(payload));
+            return operation("operation.started", "tool", firstIdentity(payload, ["tool_use_id"], "Claude tool id"));
         case "PostToolUse":
-            return operation("operation.completed", "tool", toolId(payload));
+            return operation("operation.completed", "tool", firstIdentity(payload, ["tool_use_id"], "Claude tool id"));
         case "PostToolUseFailure":
-            return operation("operation.failed", "tool", toolId(payload));
+            return operation("operation.failed", "tool", firstIdentity(payload, ["tool_use_id"], "Claude tool id"));
         case "PermissionRequest":
             return mapped("turn.waiting", {
                 reason: "permission",
-                waitId: optionalIdentityFrom(payload, ["tool_use_id", "call_id"]) ?? requireOccurrence(occurrenceId)
+                waitId: requireOccurrence(occurrenceId)
             });
         case "MessageDisplay": {
             const messageId = optionalIdentityFrom(payload, ["message_id"]);
@@ -338,48 +329,60 @@ function mapClaudeLifecycleHook(name, payload, occurrenceId) {
                     : `${messageId}:${index ?? "message"}`
             });
         }
-        case "SubagentStart":
+        case "SubagentStart": {
+            const continuationId = firstIdentity(payload, ["agent_id"], "Claude subagent id");
             return [
-                operation("operation.started", "subagent", subagentId(payload)),
-                continuationObservation("continuation.started", payload, {
+                operation("operation.started", "subagent", continuationId),
+                mapped("continuation.started", {
                     execution: "active",
                     outcome: "pending",
                     attachment: "attached",
                     observationQuality: "exact",
                     mayWriteWorkspace: true
-                })
+                }, { continuationId })
             ];
-        case "SubagentStop":
+        }
+        case "SubagentStop": {
+            const continuationId = firstIdentity(payload, ["agent_id"], "Claude subagent id");
+            const summary = claudeSummary(payload);
             return [
-                operation("operation.completed", "subagent", subagentId(payload)),
-                ...(optionalSummary(payload).summary === undefined ? [] : [
-                    continuationObservation("continuation.reported", payload, {
+                operation("operation.completed", "subagent", continuationId),
+                ...(summary.summary === undefined ? [] : [
+                    mapped("continuation.reported", {
                         execution: "quiescent",
-                        outcome: "succeeded",
+                        outcome: "unknown",
                         attachment: "attached",
                         observationQuality: "exact",
                         mayWriteWorkspace: false,
-                        reportId: reportId(payload),
-                        ...optionalSummary(payload)
-                    })
+                        reportId: continuationId,
+                        ...summary
+                    }, { continuationId })
                 ]),
-                continuationObservation("continuation.settled", payload, {
+                mapped("continuation.settled", {
                     execution: "quiescent",
-                    outcome: continuationOutcome(payload),
+                    // SubagentStop also fires on interrupted queries. Its current
+                    // payload has no outcome/status field; a report is not success.
+                    outcome: "unknown",
                     attachment: "attached",
                     observationQuality: "exact",
                     mayWriteWorkspace: false,
-                    ...optionalSummary(payload)
-                })
+                    ...summary
+                }, { continuationId })
             ];
-        case "Stop":
+        }
+        case "Stop": {
+            const complete = claudeBackgroundEmpty(payload);
             return [
                 mapped("turn.completed", optionalResultOutput(payload)),
                 mapped("native-work.snapshot", {
-                    snapshotComplete: payload.background_tasks_complete === true,
-                    observationQuality: payload.background_tasks_complete === true ? "exact" : "partial"
+                    // Current Stop fields are optional lists, never the invented
+                    // background_tasks_complete boolean. Only explicit empty lists
+                    // prove that no background work or scheduled wake remains.
+                    snapshotComplete: complete,
+                    observationQuality: complete ? "exact" : "partial"
                 })
             ];
+        }
         case "StopFailure":
             return mapped("turn.failed", claudeFailure(payload));
         case "SessionEnd":
@@ -391,70 +394,13 @@ function mapClaudeLifecycleHook(name, payload, occurrenceId) {
             throw new Error(`Claude Code Driver does not support Hook event: ${name}.`);
     }
 }
-function claudeGoalObservation(payload, occurrenceId) {
-    if (!Object.hasOwn(payload, "active_goal"))
-        return undefined;
-    if (payload.active_goal === null)
-        return mapped("goal.cleared");
-    const goal = objectValue(payload.active_goal);
-    if (goal === undefined)
-        return undefined;
-    const objective = textValue(goal.objective);
-    const status = normalizedGoalStatus(goal.status);
-    const updatedAt = timestampValue(goal.updated_at ?? goal.updatedAt)
-        ?? timestampValue(payload.timestamp)
-        ?? occurrenceTimestamp(occurrenceId);
-    if (objective === undefined || status === undefined || updatedAt === undefined)
-        return undefined;
-    const tokenBudget = positiveIntegerValue(goal.token_budget ?? goal.tokenBudget);
-    return mapped("goal.updated", {
-        goalStatus: status,
-        goalObjective: objective,
-        goalUpdatedAt: updatedAt,
-        ...(optionalIdentityFrom(goal, ["turn_id", "turnId"]) === undefined
-            ? {}
-            : { goalNativeTurnId: optionalIdentityFrom(goal, ["turn_id", "turnId"]) }),
-        ...(tokenBudget === undefined ? {} : { goalTokenBudget: tokenBudget })
-    });
-}
-function normalizedGoalStatus(value) {
-    if (value === "active" || value === "paused" || value === "blocked" || value === "complete") {
-        return value;
-    }
-    if (value === "usageLimited" || value === "usage_limited" || value === "usage-limited") {
-        return "usage-limited";
-    }
-    if (value === "budgetLimited" || value === "budget_limited" || value === "budget-limited") {
-        return "budget-limited";
-    }
-    return undefined;
-}
-function objectValue(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : undefined;
-}
-function textValue(value) {
-    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+function claudeSummary(payload) {
+    const summary = optionalText(payload.last_assistant_message);
+    return summary === undefined ? {} : { summary };
 }
-function positiveIntegerValue(value) {
-    return Number.isSafeInteger(value) && value > 0 ? value : undefined;
-}
-function timestampValue(value) {
-    if (typeof value === "string" && Number.isFinite(Date.parse(value))) {
-        return new Date(value).toISOString();
-    }
-    if (Number.isSafeInteger(value) && value >= 0) {
-        const epoch = value;
-        return new Date(epoch < 1_000_000_000_000 ? epoch * 1_000 : epoch).toISOString();
-    }
-    return undefined;
-}
-function occurrenceTimestamp(value) {
-    const prefix = value?.slice(0, 24);
-    return prefix !== undefined && Number.isFinite(Date.parse(prefix))
-        ? new Date(prefix).toISOString()
-        : undefined;
+function claudeBackgroundEmpty(payload) {
+    return Array.isArray(payload.background_tasks) && payload.background_tasks.length === 0
+        && Array.isArray(payload.session_crons) && payload.session_crons.length === 0;
 }
 function mapCodexHook(name, payload, occurrenceId) {
     switch (name) {
@@ -531,16 +477,6 @@ function reportId(payload) {
     return optionalIdentityFrom(payload, ["report_id", "message_id", "agent_id", "subagent_id"])
         ?? subagentId(payload);
 }
-function continuationOutcome(payload) {
-    if (payload.cancelled === true || payload.status === "cancelled")
-        return "cancelled";
-    if (payload.error !== undefined || payload.status === "failed")
-        return "failed";
-    if (payload.status === undefined || payload.status === "completed" || payload.status === "succeeded") {
-        return "succeeded";
-    }
-    return "unknown";
-}
 function operation(kind, operationKind, operationId) {
     return mapped(kind, { operationId, operation: operationKind });
 }
@@ -589,11 +525,6 @@ function claudeFailure(payload) {
     const lastOutput = optionalText(payload.last_assistant_message);
     const raw = serializeAgentErrorRaw(payload);
     const classification = mapClaudeAgentError({ message: code, raw });
-    const retryAfterMs = typeof payload.retry_after_ms === "number"
-        && Number.isSafeInteger(payload.retry_after_ms)
-        && payload.retry_after_ms > 0
-        ? payload.retry_after_ms
-        : undefined;
     return {
         failure: {
             error: standardAgentError({
@@ -602,13 +533,9 @@ function claudeFailure(payload) {
                 classification,
                 message: code,
                 raw,
-                inputDisposition: "accepted",
-                ...(retryAfterMs === undefined ? {} : { retryAfterMs })
+                inputDisposition: "accepted"
             }),
-            ...(lastOutput === undefined ? {} : { lastOutput }),
-            ...(payload.run_terminal === true || payload.unrecoverable === true
-                ? { runTerminal: true }
-                : {})
+            ...(lastOutput === undefined ? {} : { lastOutput })
         },
         summary: [
             "Agent turn failed.",

package/dist/runtime/builtinTranscriptObserver.js

@@ -418,21 +418,25 @@ function normalizeCursor(input) {
     if (!Number.isSafeInteger(offset) || offset < 0
         || typeof remainder !== "string"
         || state === null || typeof state !== "object" || Array.isArray(state)
-        || (continuityEpoch !== undefined
-            && (typeof continuityEpoch !== "string" || continuityEpoch.length === 0))
+        || 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;
+        throw new Error("Transcript observer cursor is invalid or unsupported.");
+    }
+    // Only our unavailable-before-first-read cursor lacks file metadata. An old
+    // partially shaped cursor must not silently reset/replay a healthy source.
+    const unstarted = offset === 0 && remainder === "" && Object.keys(state).length === 0
+        && continuityEpoch === INITIAL_CONTINUITY_EPOCH;
+    if (!unstarted && (fileFingerprint === undefined || fileCtimeMs === undefined)) {
+        throw new Error("Transcript observer cursor has no current file identity.");
     }
     return Object.freeze({
         offset: offset,
         remainder,
         state: state,
-        continuityEpoch: typeof continuityEpoch === "string"
-            ? continuityEpoch
-            : INITIAL_CONTINUITY_EPOCH,
+        continuityEpoch,
         ...(typeof fileFingerprint === "string" ? { fileFingerprint } : {}),
         ...(typeof fileCtimeMs === "number" ? { fileCtimeMs } : {})
     });