@cydm/happy-elves 0.1.0-beta.36 → 0.1.0-beta.38

package/apps/cli/dist/commands/lib/bootstrap-daemon.d.ts

@@ -1,5 +1,5 @@
-import type { ControllerClient } from "@happy-elves/client";
-import type { MachineSnapshot } from "@happy-elves/shared";
+import type { ControllerClient } from "../../../../../packages/client/dist/index.js";
+import type { MachineSnapshot } from "../../../../../packages/shared/dist/index.js";
 import { localDaemonStatus, stopLocalDaemon } from "./local-daemon.js";
 export declare function ensureDaemonRunning(relayUrl: string, cwd?: string): Promise<{
     local: Awaited<ReturnType<typeof localDaemonStatus>>;

package/apps/cli/dist/commands/lib/index.d.ts

@@ -1,5 +1,5 @@
-export { ControllerClient, type ScopedTokenScope } from "@happy-elves/client";
-export { generateAccountSecret, randomId } from "@happy-elves/shared";
+export { ControllerClient, type ScopedTokenScope } from "../../../../../packages/client/dist/index.js";
+export { generateAccountSecret, randomId } from "../../../../../packages/shared/dist/index.js";
 export { CliError } from "../../errors.js";
 export * from "./args.js";
 export * from "./audit.js";

package/apps/cli/dist/commands/lib/json.d.ts

@@ -1,4 +1,4 @@
-import type { JsonEnvelope } from "@happy-elves/shared";
+import type { JsonEnvelope } from "../../../../../packages/shared/dist/index.js";
 export declare function ok<T>(type: string, data: T, meta?: JsonEnvelope["meta"]): void;
 export declare function writeError(code: string, message: string, meta?: JsonEnvelope["meta"], capability?: string): void;
 export declare function wantsJson(flags: Record<string, string | boolean>): boolean;

package/apps/cli/dist/commands/lib/relay-http.d.ts

@@ -1,4 +1,4 @@
-import type { PairingClaimResponse, PairingStartResponse } from "@happy-elves/shared";
+import type { PairingClaimResponse, PairingStartResponse } from "../../../../../packages/shared/dist/index.js";
 import { CliError } from "../../errors.js";
 import type { CliConfig, DaemonConfig } from "./types.js";
 export declare function relayHealth(relayUrl: string): Promise<{

package/apps/cli/dist/commands/lib/scope.d.ts

@@ -1,4 +1,4 @@
-import type { ControllerClient, ScopedTokenScope } from "@happy-elves/client";
+import type { ControllerClient, ScopedTokenScope } from "../../../../../packages/client/dist/index.js";
 import type { LoopRecord, PermissionMode } from "./types.js";
 export declare const DEFAULT_COMMAND_TIMEOUT_MS: number;
 export declare function parseDurationMs(value: string | boolean | undefined, fallbackMs: number): number;

package/apps/cli/dist/commands/lib/session-output.d.ts

@@ -1,4 +1,4 @@
-import type { ControllerClient, DecodedSessionEvent } from "@happy-elves/client";
+import type { ControllerClient, DecodedSessionEvent } from "../../../../../packages/client/dist/index.js";
 export declare function compactText(value: string, max?: number): string;
 export declare function lastAssistantOutput(events: DecodedSessionEvent[]): string;
 export declare function displayPath(filePath: string): string;
@@ -18,6 +18,7 @@ export type TurnSummary = {
     turnId: string;
     checkpointId?: string;
     runtimeTurnId?: string;
+    turnSeq?: number;
     status: "running" | "completed" | "failed" | "cancelled";
     prompt: string;
     output: string;

package/apps/cli/dist/commands/lib/session-output.js

@@ -160,6 +160,8 @@ export function summarizeTurns(events) {
         current.updatedAt = event.createdAt;
         current.lastEventId = event.id;
         current.eventCount += 1;
+        if (event.turnSeq !== undefined)
+            current.turnSeq = event.turnSeq;
         const payload = event.decoded;
         if (payload?.type === "user_prompt" && payload.text.trim()) {
             current.promptChunks.push(payload.text.trim());
@@ -181,6 +183,7 @@ export function summarizeTurns(events) {
         turnId: turn.turnId,
         checkpointId: turn.checkpointId,
         runtimeTurnId: turn.runtimeTurnId,
+        turnSeq: turn.turnSeq,
         status: turn.status,
         prompt: turn.promptChunks.join("\n").trim(),
         output: turn.outputChunks.join("").trim() || turn.terminalText,

package/apps/cli/dist/commands/lib/session-view.d.ts

@@ -1,5 +1,5 @@
-import type { ControllerClient, DecodedSessionEvent } from "@happy-elves/client";
-import type { MachineSnapshot, SessionSnapshot } from "@happy-elves/shared";
+import type { ControllerClient, DecodedSessionEvent } from "../../../../../packages/client/dist/index.js";
+import type { MachineSnapshot, SessionSnapshot } from "../../../../../packages/shared/dist/index.js";
 import { type MachineMetadata, type OrchestrationSummary, type OrchestrationState } from "./types.js";
 export declare function showMachine(client: ControllerClient, machine: MachineSnapshot): Promise<MachineSnapshot & {
     defaultCwd?: string;

package/apps/cli/dist/commands/lib/types.d.ts

@@ -1,5 +1,5 @@
-import type { ScopedTokenScope } from "@happy-elves/client";
-import type { SessionSnapshot } from "@happy-elves/shared";
+import type { ScopedTokenScope } from "../../../../../packages/client/dist/index.js";
+import type { SessionSnapshot } from "../../../../../packages/shared/dist/index.js";
 export type CliConfig = {
     relayUrl: string;
     controllerToken: string;

package/apps/cli/dist/commands/lib/workspace.d.ts

@@ -1,5 +1,5 @@
-import type { ControllerClient } from "@happy-elves/client";
-import type { HistoricalSessionSnapshot } from "@happy-elves/shared";
+import type { ControllerClient } from "../../../../../packages/client/dist/index.js";
+import type { HistoricalSessionSnapshot } from "../../../../../packages/shared/dist/index.js";
 export type WorkspaceHistoricalSession = HistoricalSessionSnapshot & {
     machineId: string;
     machineName: string;

package/apps/cli/dist/commands/session.js

@@ -53,6 +53,7 @@ function compactTurnRef(turn) {
         status: turn.status,
         ...(turn.prompt ? { promptPreview: compactText(turn.prompt, 180) } : {}),
         time: turn.completedAt ?? turn.updatedAt,
+        ...(turn.turnSeq !== undefined ? { turnSeq: turn.turnSeq } : {}),
     };
 }
 function countBy(values) {
@@ -114,6 +115,38 @@ function eventCollectionDiagnostics(events) {
         visiblePayloads: events.filter(isVisibleTranscriptPayloadEvent).length,
     };
 }
+function headMatchesTurn(session, turn) {
+    if (!turn)
+        return false;
+    const turnHeads = new Set([
+        turn.checkpointId,
+        turn.runtimeTurnId,
+        turn.turnId,
+    ].filter((value) => typeof value === "string" && value.length > 0));
+    if (session.currentHead?.startsWith("event:")) {
+        const eventId = Number(/^event:(\d+)$/.exec(session.currentHead)?.[1]);
+        if (Number.isFinite(eventId) && eventId >= turn.firstEventId && eventId <= turn.lastEventId)
+            return true;
+    }
+    return (session.currentHead !== undefined && turnHeads.has(session.currentHead)) ||
+        (session.lastTurnId !== undefined && turnHeads.has(session.lastTurnId));
+}
+function staleHeadSuspected(session, latestCompletedTurn) {
+    if (!latestCompletedTurn)
+        return false;
+    if (headMatchesTurn(session, latestCompletedTurn))
+        return false;
+    const basisTime = session.headBasis?.logicalTime;
+    const latestTime = latestCompletedTurn.completedAt ?? latestCompletedTurn.updatedAt;
+    if (basisTime !== undefined) {
+        if (latestTime !== basisTime)
+            return latestTime > basisTime;
+        if (session.headBasis?.turnSeq !== undefined && latestCompletedTurn.turnSeq !== undefined) {
+            return latestCompletedTurn.turnSeq > session.headBasis.turnSeq;
+        }
+    }
+    return Boolean(session.currentHead || session.lastTurnId);
+}
 function stringMetadata(metadata, key) {
     const value = metadata[key];
     return typeof value === "string" ? value : undefined;
@@ -318,6 +351,7 @@ export async function handleSession({ domain, action, positional, flags }) {
                 historyModel: session.historyModel ?? "append-only",
                 currentHead: session.currentHead,
                 lastTurnId: session.lastTurnId,
+                headBasis: session.headBasis,
                 sourceSessionId: session.sourceSessionId,
                 sourceCheckpointId: session.sourceCheckpointId,
                 updatedAt: session.updatedAt,
@@ -358,6 +392,8 @@ export async function handleSession({ domain, action, positional, flags }) {
                 backfillAvailableEvents: numberMetadata(metadata, "availableHistoricalEvents"),
                 backfillEmittedEvents: numberMetadata(metadata, "backfilledEvents"),
                 backfillStatus: stringMetadata(metadata, "historicalBackfillStatus") ?? stringMetadata(metadata, "historicalBackfill"),
+                staleHeadSuspected: staleHeadSuspected(session, latestCompletedTurn),
+                headMatchesLatestCompletedTurn: headMatchesTurn(session, latestCompletedTurn),
             },
         };
         if (wantsJson(flags) || wantsVerbose(flags)) {
@@ -369,8 +405,8 @@ export async function handleSession({ domain, action, positional, flags }) {
             const runtime = isRecord(metadata.runtime) ? metadata.runtime : {};
             console.log(`Runtime: ${stringMetadata(metadata, "importedFromRuntimeSessionId") ?? stringMetadata(runtime, "backendSessionId") ?? stringMetadata(runtime, "agentSessionId") ?? "-"}`);
             console.log(`Backfill: ${data.diagnosis.backfillStatus ?? "-"}  available=${data.diagnosis.backfillAvailableEvents ?? "-"} emitted=${data.diagnosis.backfillEmittedEvents ?? "-"}`);
+            console.log(`Head: ${session.currentHead ?? "-"}  lastTurn=${session.lastTurnId ?? "-"}  stale=${data.diagnosis.staleHeadSuspected ? "yes" : "no"}`);
             console.log(`Latest page: ${latestPage.events.length} events, visible=${latestPage.events.filter(isVisibleTranscriptPayloadEvent).length}, hasMore=${latestPage.hasMoreBefore}`);
-            console.log(`Head: ${session.currentHead ?? "-"}  lastTurn: ${session.lastTurnId ?? "-"}`);
         }
         return true;
     }

package/apps/daemon/dist/relay/devtools.d.ts

@@ -1,4 +1,4 @@
-import type { MachineCommand } from "@happy-elves/shared";
+import type { MachineCommand } from "../../../../packages/shared/dist/index.js";
 import type { DaemonConfig } from "../types.js";
 export declare function handleDiagnose(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;
 export declare function handleDevExec(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;

package/apps/daemon/dist/relay/send.d.ts

@@ -1,5 +1,5 @@
-import type { MachineClientMessage } from "@happy-elves/shared";
-import type { RuntimeTurn } from "@happy-elves/runtime";
+import type { MachineClientMessage } from "../../../../packages/shared/dist/index.js";
+import type { RuntimeTurn } from "../../../../packages/runtime/dist/index.js";
 import type { DaemonConfig } from "../types.js";
 export declare function send(ws: WebSocket, message: unknown): void;
 export declare function configureRelaySender(config: DaemonConfig): void;

package/apps/daemon/dist/relay/send.js

@@ -8,6 +8,7 @@ const criticalMessageTypes = new Set([
     "machine:event",
     "machine:sessionTranscriptReplaced",
     "machine:sessionTranscriptPrepended",
+    "machine:sessionHeadAdvanced",
     "machine:turnDone",
     "machine:sessionResumed",
     "machine:sessionRewound",

package/apps/daemon/dist/relay-http.d.ts

@@ -1,4 +1,4 @@
-import { type PairingClaimResponse, type ServerMessage } from "@happy-elves/shared";
+import { type PairingClaimResponse, type ServerMessage } from "../../../packages/shared/dist/index.js";
 import { DaemonCliError } from "./errors.js";
 export declare function relayHttpError(response: Response, fallback: string): Promise<DaemonCliError>;
 export declare function readRelayJson(response: Response, fallback: string): Promise<unknown>;

package/apps/daemon/dist/runtime/external-provider.d.ts

@@ -1,4 +1,4 @@
-import type { HappyElvesRuntime } from "@happy-elves/runtime";
+import type { HappyElvesRuntime } from "../../../../packages/runtime/dist/index.js";
 export type ExternalProviderConfig = {
     id: string;
     command: string;

package/apps/daemon/dist/runtime.d.ts

@@ -1,8 +1,7 @@
-import type { HappyElvesRuntime } from "@happy-elves/runtime";
+import type { HappyElvesRuntime } from "../../../packages/runtime/dist/index.js";
 import type { PrimitiveSupport } from "./types.js";
 export declare function getRuntime(defaultCwd: string): HappyElvesRuntime;
 export declare function initializeRuntime(defaultCwd: string): Promise<void>;
-export declare function runtimeDiagnostics(): Array<Record<string, unknown>>;
 export declare function disposeRuntime(): void;
 export declare function setRuntimeForTests(runtimeOverride: HappyElvesRuntime | null): void;
 export declare function runtimePrimitiveSupport(runtimeInstance: HappyElvesRuntime): {

package/apps/daemon/dist/runtime.js

@@ -57,9 +57,6 @@ export async function initializeRuntime(defaultCwd) {
         await runtimeInstance.initialize();
     }
 }
-export function runtimeDiagnostics() {
-    return runtime?.diagnostics?.() ?? [];
-}
 export function disposeRuntime() {
     runtime?.dispose?.();
     runtime = null;

package/apps/daemon/dist/session/create-session.d.ts

@@ -1,4 +1,4 @@
-import type { MachineClientMessage, MachineCommand } from "@happy-elves/shared";
+import type { MachineClientMessage, MachineCommand } from "../../../../packages/shared/dist/index.js";
 type CreateSessionCommand = Extract<MachineCommand, {
     type: "machine:createSession";
 }>;

package/apps/daemon/dist/session/directory.d.ts

@@ -1,3 +1,3 @@
-import type { MachineCommand } from "@happy-elves/shared";
+import type { MachineCommand } from "../../../../packages/shared/dist/index.js";
 import type { DaemonConfig } from "../types.js";
 export declare function handleListDirectory(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;

package/apps/daemon/dist/session/events.d.ts

@@ -1,12 +1,15 @@
-import { type EncryptedEnvelope, type SessionEventPayload } from "@happy-elves/shared";
-import type { RuntimeEvent, RuntimeHistoricalEvent } from "@happy-elves/runtime";
+import { type EncryptedEnvelope, type SessionEventPayload, type SessionHeadAdvanceBasis } from "../../../../packages/shared/dist/index.js";
+import type { RuntimeEvent, RuntimeHistoricalEvent } from "../../../../packages/runtime/dist/index.js";
 import type { DaemonConfig } from "../types.js";
 export declare function emitEvent(ws: WebSocket, config: DaemonConfig, sessionId: string, turnId: string, payload: SessionEventPayload): Promise<void>;
 export declare function emitHistoricalEvents(ws: WebSocket, config: DaemonConfig, sessionId: string, events: RuntimeHistoricalEvent[], startIndex?: number): Promise<void>;
 export declare function emitRuntimeTailEvents(ws: WebSocket, config: DaemonConfig, sessionId: string, events: RuntimeHistoricalEvent[], startIndex?: number): Promise<void>;
+export declare function emitSessionHeadAdvanced(ws: WebSocket, sessionId: string, head: HistoricalSessionHead, encryptedMetadata?: EncryptedEnvelope): Promise<void>;
 export declare function emitTranscriptReplacement(ws: WebSocket, config: DaemonConfig, sessionId: string, events: RuntimeHistoricalEvent[], input?: {
+    requestId?: string;
     currentHead?: string;
     lastTurnId?: string;
+    replacementKind?: "command" | "sync";
     status?: "completed" | "cancelled" | "failed";
     encryptedMetadata?: EncryptedEnvelope;
     hasMoreBefore?: boolean;
@@ -17,4 +20,14 @@ export declare function emitTranscriptPrepended(ws: WebSocket, config: DaemonCon
     hasMoreBefore?: boolean;
     nextBefore?: string;
 }): Promise<void>;
+export type HistoricalSessionHead = {
+    currentHead: string;
+    lastTurnId: string;
+    basis: SessionHeadAdvanceBasis;
+};
+export declare function latestCompletedHistoricalHead(sessionId: string, events: RuntimeHistoricalEvent[], input?: {
+    preferTailBasisForExistingEvents?: boolean;
+    previousTotalEvents?: number;
+    tailStartIndex?: number;
+}): HistoricalSessionHead | undefined;
 export declare function runtimeEventToPayload(event: RuntimeEvent): SessionEventPayload;

package/apps/daemon/dist/session/events.js

@@ -32,12 +32,27 @@ export async function emitRuntimeTailEvents(ws, config, sessionId, events, start
         }, ws);
     }
 }
+export async function emitSessionHeadAdvanced(ws, sessionId, head, encryptedMetadata) {
+    await sendReliable({
+        type: "machine:sessionHeadAdvanced",
+        sessionId,
+        currentHead: head.currentHead,
+        lastTurnId: head.lastTurnId,
+        basis: head.basis,
+        encryptedMetadata,
+    }, ws);
+}
 export async function emitTranscriptReplacement(ws, config, sessionId, events, input = {}) {
+    const head = latestCompletedHistoricalHead(sessionId, events);
+    const fallbackHead = transcriptHead(events);
     await sendReliable({
         type: "machine:sessionTranscriptReplaced",
         sessionId,
-        currentHead: input.currentHead ?? transcriptHead(events).currentHead,
-        lastTurnId: input.lastTurnId ?? transcriptHead(events).lastTurnId,
+        requestId: input.requestId,
+        currentHead: input.currentHead ?? head?.currentHead ?? fallbackHead.currentHead,
+        lastTurnId: input.lastTurnId ?? head?.lastTurnId ?? fallbackHead.lastTurnId,
+        basis: head?.basis,
+        replacementKind: input.replacementKind,
         status: input.status,
         hasMoreBefore: input.hasMoreBefore,
         nextBefore: input.nextBefore,
@@ -79,6 +94,7 @@ async function encryptedRuntimeTailEvents(config, sessionId, events, startIndex
             turnId: event.turnId,
             seq: stableTailSeq,
             messageId: runtimeTailEventMessageId(sessionId, event, stableTailSeq),
+            occurredAt: event.occurredAt,
             payload: await encryptJson(config.accountSecret, `event:${sessionId}:${event.turnId}:${stableTailSeq}`, event.payload),
         });
     }
@@ -98,6 +114,33 @@ function transcriptHead(events) {
     }
     return events.at(-1)?.turnId ? { currentHead: events.at(-1)?.turnId, lastTurnId: events.at(-1)?.turnId } : {};
 }
+export function latestCompletedHistoricalHead(sessionId, events, input = {}) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (!event || event.payload.type !== "done" || event.payload.status !== "completed")
+            continue;
+        const seq = event.seq ?? index + 1;
+        const hasRuntimeTailMessageId = (input.tailStartIndex !== undefined && index >= input.tailStartIndex)
+            || (input.previousTotalEvents !== undefined && index >= input.previousTotalEvents)
+            || input.preferTailBasisForExistingEvents === true;
+        const eventMessageId = hasRuntimeTailMessageId
+            ? runtimeTailEventMessageId(sessionId, event, seq)
+            : historicalEventMessageId(sessionId, event, seq);
+        const currentHead = event.payload.currentHead ?? event.payload.lastTurnId ?? event.turnId;
+        const lastTurnId = event.payload.lastTurnId ?? event.payload.currentHead ?? event.turnId;
+        return {
+            currentHead,
+            lastTurnId,
+            basis: {
+                turnId: event.turnId,
+                eventMessageId,
+                turnSeq: seq,
+                ...(event.occurredAt !== undefined ? { occurredAt: event.occurredAt } : {}),
+            },
+        };
+    }
+    return undefined;
+}
 function historicalEventMessageId(sessionId, event, seq) {
     const digest = createHash("sha256")
         .update(JSON.stringify({ occurredAt: event.occurredAt, payload: event.payload, seq }))

package/apps/daemon/dist/session/file-preview.d.ts

@@ -1,4 +1,4 @@
-import type { FilePreviewMode, FilePreviewResult, MachineCommand } from "@happy-elves/shared";
+import type { FilePreviewMode, FilePreviewResult, MachineCommand } from "../../../../packages/shared/dist/index.js";
 import type { DaemonConfig } from "../types.js";
 export declare function handlePreviewFile(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;
 export declare function buildFilePreview(config: DaemonConfig, rootPath: string, requestedPath: string, mode?: FilePreviewMode): Promise<FilePreviewResult>;

package/apps/daemon/dist/session/lifecycle.d.ts

@@ -1,5 +1,6 @@
-import { type MachineCommand } from "@happy-elves/shared";
+import { type MachineCommand } from "../../../../packages/shared/dist/index.js";
 import type { DaemonConfig, HistoricalBackfillStatus, SessionFallback, SessionState } from "../types.js";
+import { type HistoricalSessionHead } from "./events.js";
 export type HistoricalBackfillResult = {
     availableEvents: number;
     cursor: number;
@@ -10,6 +11,7 @@ export type HistoricalBackfillResult = {
     tailRepairedEvents: number;
     totalEvents: number;
     truncated: boolean;
+    head?: HistoricalSessionHead;
 };
 export declare function handleCreateSession(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;
 export declare function handleImportHistoricalSession(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;
@@ -19,6 +21,8 @@ export declare function usesAuthoritativeTranscript(session: SessionState): bool
 export declare function replaceAuthoritativeTranscript(ws: WebSocket, config: DaemonConfig, session: SessionState, runtimeSessionId?: string | undefined, input?: {
     currentHead?: string;
     lastTurnId?: string;
+    replacementKind?: "command" | "sync";
+    requestId?: string;
     status?: "completed" | "cancelled" | "failed";
     strict?: boolean;
 }): Promise<HistoricalBackfillResult>;

package/apps/daemon/dist/session/lifecycle.js

@@ -4,7 +4,7 @@ import { getRuntime } from "../runtime.js";
 import { sessions } from "../state.js";
 import { claimCommandRequest, sendCommandResponse } from "../relay/send.js";
 import { createSessionFailureAuditEvent, createSessionFailureResponse } from "./create-session.js";
-import { emitHistoricalEvents, emitRuntimeTailEvents, emitTranscriptPrepended, emitTranscriptReplacement } from "./events.js";
+import { emitHistoricalEvents, emitRuntimeTailEvents, emitSessionHeadAdvanced, emitTranscriptPrepended, emitTranscriptReplacement, latestCompletedHistoricalHead, } from "./events.js";
 import { commandSessionMetadata, encryptedSessionMetadata, sessionFallbackFromCommand } from "./metadata.js";
 const historicalBackfillEventLimit = 200;
 export async function handleCreateSession(ws, config, command) {
@@ -461,8 +461,10 @@ export async function replaceAuthoritativeTranscript(ws, config, session, runtim
     }
     const result = authoritativeBackfillResult(page);
     await emitTranscriptReplacement(ws, config, session.sessionId, page.events, {
+        requestId: input.requestId,
         currentHead: input.currentHead ?? page.currentHead,
         lastTurnId: input.lastTurnId ?? page.lastTurnId,
+        replacementKind: input.replacementKind,
         status: input.status,
         hasMoreBefore: page.hasMoreBefore,
         nextBefore: page.nextBefore,
@@ -579,7 +581,15 @@ async function backfillHistoricalEvents(ws, config, session, runtimeSessionId =
         await emitHistoricalEvents(ws, config, session.sessionId, olderWindow.events, olderWindow.startIndex);
     }
     const status = olderWindow.nextCursor > 0 ? "partial" : "completed";
-    return {
+    const computedHead = latestCompletedHistoricalHead(session.sessionId, historicalEvents, {
+        ...(previousBackfill?.totalEvents !== undefined && previousBackfill.head === undefined
+            ? { preferTailBasisForExistingEvents: true }
+            : {}),
+        ...(previousBackfill?.totalEvents !== undefined ? { previousTotalEvents: previousBackfill.totalEvents } : {}),
+        ...(tailWindow.events.length > 0 ? { tailStartIndex: tailWindow.startIndex } : {}),
+    });
+    const head = preferPersistedHistoricalHeadBasis(computedHead, previousBackfill?.head);
+    const result = {
         emittedEvents: tailWindow.events.length + olderWindow.events.length,
         availableEvents: historicalEvents.length,
         cursor: olderWindow.nextCursor,
@@ -588,7 +598,27 @@ async function backfillHistoricalEvents(ws, config, session, runtimeSessionId =
         tailRepairedEvents: tailWindow.events.length,
         totalEvents: historicalEvents.length,
         truncated: status === "partial",
+        ...(head ? { head } : {}),
     };
+    if (head) {
+        const backfilledSession = withHistoricalBackfill(session, result);
+        await emitSessionHeadAdvanced(ws, session.sessionId, head, await encryptedSessionMetadata(config, session.sessionId, backfilledSession, {
+            ...historicalBackfillMetadata(result),
+            historicalBackfilledAt: new Date().toISOString(),
+        }));
+    }
+    return result;
+}
+function preferPersistedHistoricalHeadBasis(computed, persisted) {
+    if (!computed || !persisted)
+        return computed;
+    if (computed.currentHead === persisted.currentHead &&
+        computed.lastTurnId === persisted.lastTurnId &&
+        computed.basis.turnId === persisted.basis.turnId &&
+        computed.basis.turnSeq === persisted.basis.turnSeq) {
+        return persisted;
+    }
+    return computed;
 }
 function completedBackfillResult(totalEvents) {
     return {
@@ -665,6 +695,7 @@ function withHistoricalBackfill(session, backfill) {
         ...session,
         historicalBackfill: {
             cursor: backfill.cursor,
+            ...(backfill.head ? { head: backfill.head } : {}),
             providerCursor: backfill.providerCursor,
             status: backfill.status,
             totalEvents: backfill.totalEvents,
@@ -681,6 +712,7 @@ function historicalBackfillMetadata(backfill) {
         backfilledEvents: backfill.emittedEvents,
         historicalOlderBackfilledEvents: backfill.olderBackfilledEvents,
         historicalTailRepairedEvents: backfill.tailRepairedEvents,
+        historicalHead: backfill.head,
         availableHistoricalEvents: backfill.availableEvents,
         truncatedHistoricalBackfill: backfill.truncated,
     };
@@ -699,11 +731,22 @@ export async function handleClose(ws, config, command) {
         return;
     const session = sessions.get(command.sessionId);
     const fallback = session ? undefined : await sessionFallbackFromCommand(config, command);
+    const fallbackHandle = fallback ? runtimeHandleFromFallback(command.sessionId, fallback.agent, fallback.cwd, fallback) : undefined;
+    const sessionForClose = session ?? (fallback && fallbackHandle
+        ? {
+            sessionId: command.sessionId,
+            agent: fallback.agent,
+            cwd: fallback.cwd,
+            name: fallback.name,
+            handle: fallbackHandle,
+            historicalBackfill: fallback.historicalBackfill,
+        }
+        : undefined);
     let runtimeCloseError;
-    if (session) {
+    if (sessionForClose) {
         try {
-            await getRuntime(session.cwd).close({
-                handle: session.handle,
+            await getRuntime(sessionForClose.cwd).close({
+                handle: sessionForClose.handle,
                 reason: command.reason ?? "closed by controller",
             });
         }
@@ -722,8 +765,9 @@ export async function handleClose(ws, config, command) {
             requestId: command.requestId,
             reason: command.reason,
             loaded: Boolean(session),
-            agent: session?.agent ?? fallback?.agent,
-            cwd: session?.cwd ?? fallback?.cwd,
+            ...(!session && fallbackHandle ? { runtimeHandleFallback: true } : {}),
+            agent: sessionForClose?.agent ?? fallback?.agent,
+            cwd: sessionForClose?.cwd ?? fallback?.cwd,
             runtimeCloseError,
         },
     });

package/apps/daemon/dist/session/metadata.d.ts

@@ -1,4 +1,4 @@
-import { type EncryptedEnvelope, type MachineCommand } from "@happy-elves/shared";
+import { type EncryptedEnvelope, type MachineCommand } from "../../../../packages/shared/dist/index.js";
 import type { DaemonConfig, SessionFallback, SessionMetadata, SessionState } from "../types.js";
 export declare function encryptedSessionMetadata(config: DaemonConfig, sessionId: string, state: Pick<SessionState, "agent" | "cwd" | "name" | "handle">, extra: Record<string, unknown>): Promise<EncryptedEnvelope>;
 export declare function commandSessionMetadata(config: DaemonConfig, encryptedMetadata?: EncryptedEnvelope): Promise<SessionMetadata | undefined>;

package/apps/daemon/dist/session/metadata.js

@@ -52,6 +52,7 @@ function historicalBackfillStateFromMetadata(metadata) {
     if (status && totalEvents !== undefined && cursor !== undefined) {
         return {
             cursor: Math.min(cursor, totalEvents),
+            ...(historicalHeadStateFromMetadata(metadata) ? { head: historicalHeadStateFromMetadata(metadata) } : {}),
             ...(typeof metadata.historicalBackfillProviderCursor === "string" ? { providerCursor: metadata.historicalBackfillProviderCursor } : {}),
             status,
             totalEvents,
@@ -60,6 +61,7 @@ function historicalBackfillStateFromMetadata(metadata) {
     if (status === "completed") {
         return {
             cursor: 0,
+            ...(historicalHeadStateFromMetadata(metadata) ? { head: historicalHeadStateFromMetadata(metadata) } : {}),
             ...(typeof metadata.historicalBackfillProviderCursor === "string" ? { providerCursor: metadata.historicalBackfillProviderCursor } : {}),
             status: "completed",
             totalEvents: totalEvents ?? 0,
@@ -70,6 +72,7 @@ function historicalBackfillStateFromMetadata(metadata) {
         if (totalEvents !== undefined && backfilledEvents !== undefined) {
             return {
                 cursor: Math.max(0, totalEvents - backfilledEvents),
+                ...(historicalHeadStateFromMetadata(metadata) ? { head: historicalHeadStateFromMetadata(metadata) } : {}),
                 ...(typeof metadata.historicalBackfillProviderCursor === "string" ? { providerCursor: metadata.historicalBackfillProviderCursor } : {}),
                 status: "partial",
                 totalEvents,
@@ -78,6 +81,31 @@ function historicalBackfillStateFromMetadata(metadata) {
     }
     return undefined;
 }
+function historicalHeadStateFromMetadata(metadata) {
+    const head = metadata.historicalHead;
+    if (!head || typeof head !== "object")
+        return undefined;
+    const basis = head.basis;
+    if (typeof head.currentHead !== "string" ||
+        typeof head.lastTurnId !== "string" ||
+        !basis ||
+        typeof basis !== "object" ||
+        typeof basis.turnId !== "string" ||
+        typeof basis.eventMessageId !== "string" ||
+        !Number.isInteger(basis.turnSeq)) {
+        return undefined;
+    }
+    return {
+        currentHead: head.currentHead,
+        lastTurnId: head.lastTurnId,
+        basis: {
+            turnId: basis.turnId,
+            eventMessageId: basis.eventMessageId,
+            turnSeq: basis.turnSeq,
+            ...(typeof basis.occurredAt === "number" ? { occurredAt: basis.occurredAt } : {}),
+        },
+    };
+}
 function historicalBackfillStatus(value) {
     return value === "partial" || value === "completed" ? value : undefined;
 }

package/apps/daemon/dist/session/primitives.d.ts

@@ -1,4 +1,4 @@
-import { type MachineCommand } from "@happy-elves/shared";
+import { type MachineCommand } from "../../../../packages/shared/dist/index.js";
 import type { DaemonConfig } from "../types.js";
 export declare function handleRewind(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;
 export declare function handleFork(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;

package/apps/daemon/dist/session/primitives.js

@@ -113,7 +113,11 @@ export async function handleRewind(ws, config, command) {
     });
     if (usesAuthoritativeTranscript(nextSession)) {
         try {
-            const backfill = await replaceAuthoritativeTranscript(ws, config, nextSession, undefined, head);
+            const backfill = await replaceAuthoritativeTranscript(ws, config, nextSession, undefined, {
+                ...head,
+                replacementKind: "command",
+                requestId: command.requestId,
+            });
             sessions.set(command.sessionId, {
                 ...nextSession,
                 historicalBackfill: {
@@ -241,6 +245,7 @@ export async function handleFork(ws, config, command) {
             ...primitiveRuntimeEvidence(source.handle, forkState.handle),
         },
     });
+    const authoritativeForkTranscript = usesAuthoritativeTranscript(forkState);
     await sendCommandResponse(ws, {
         type: "machine:sessionForked",
         requestId: command.requestId,
@@ -248,6 +253,7 @@ export async function handleFork(ws, config, command) {
         sourceCheckpointId,
         sessionId: command.targetSessionId,
         name: command.name,
+        ...(authoritativeForkTranscript ? { transcriptPending: true } : {}),
         encryptedMetadata: await encryptedSessionMetadata(config, command.targetSessionId, forkState, {
             forkedAt: new Date().toISOString(),
             importedFromRuntimeSessionId: sourceMetadata?.importedFromRuntimeSessionId,
@@ -256,10 +262,15 @@ export async function handleFork(ws, config, command) {
             sourceCheckpointId,
         }),
     });
-    if (usesAuthoritativeTranscript(forkState)) {
+    if (authoritativeForkTranscript) {
         try {
             const targetHead = primitiveResultHead(result);
-            const backfill = await replaceAuthoritativeTranscript(ws, config, forkState, undefined, targetHead);
+            const backfill = await replaceAuthoritativeTranscript(ws, config, forkState, undefined, {
+                ...targetHead,
+                replacementKind: "command",
+                requestId: command.requestId,
+                status: "completed",
+            });
             sessions.set(command.targetSessionId, {
                 ...forkState,
                 historicalBackfill: {
@@ -279,6 +290,14 @@ export async function handleFork(ws, config, command) {
                 summary: `Failed to refresh fork target transcript ${command.targetSessionId}`,
                 evidence: { requestId: command.requestId, sourceSessionId: command.sessionId, error: error instanceof Error ? error.message : String(error) },
             });
+            await sendCommandResponse(ws, {
+                type: "machine:error",
+                requestId: command.requestId,
+                sessionId: command.targetSessionId,
+                code: "SESSION_TRANSCRIPT_REPLACE_FAILED",
+                capability: "session.history",
+                message: error instanceof Error ? error.message : String(error),
+            });
         }
     }
 }