@cydm/happy-elves 0.1.0-beta.31 → 0.1.0-beta.310

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

@@ -1,4 +1,5 @@
-import { CliError, ControllerClient, compactSessionListItem, compactText, conciseSessionSummary, deriveOrchestration, listWorkspaceHistoricalSessions, ok, parsePermissionMode, readConfig, readStoredTurnOutput, requirePositional, requireString, showSession, structuredSessionProjection, summarizeTurns, wantsJson, wantsVerbose } from "./lib/index.js";
+import { normalizeSessionTags, sessionTagKeys } from "../../../../packages/shared/dist/index.js";
+import { CliError, ControllerClient, compareSessionEventLogicalOrder, compactSessionListItem, compactText, conciseSessionSummary, deriveOrchestration, listWorkspaceHistoricalSessions, ok, parsePermissionMode, readConfig, readStoredTurnOutput, requirePositional, requireString, showSession, structuredSessionProjection, summarizeTurns, wantsJson, wantsVerbose } from "./lib/index.js";
 function formatTurnTimestamp(value) {
     return value === undefined ? "-" : new Date(value).toISOString();
 }
@@ -26,6 +27,14 @@ function parsePositiveIntFlag(flags, name) {
     }
     return parsed;
 }
+function tagsFromFlagValue(value) {
+    if (typeof value !== "string")
+        return [];
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function tagsFromFlags(flags, names = ["tag", "tags"]) {
+    return normalizeSessionTags(names.flatMap((name) => tagsFromFlagValue(flags[name])));
+}
 function selectWindow(items, flags, defaultLimit) {
     const limit = parsePositiveIntFlag(flags, "limit");
     const tail = parsePositiveIntFlag(flags, "tail");
@@ -53,8 +62,298 @@ 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) {
+    const counts = {};
+    for (const value of values)
+        counts[value] = (counts[value] ?? 0) + 1;
+    return counts;
+}
+function messagePrefix(messageId) {
+    if (!messageId)
+        return "none";
+    const index = messageId.indexOf("_");
+    return index > 0 ? messageId.slice(0, index) : "other";
+}
+function eventPayloadText(event) {
+    const payload = event.decoded;
+    if (!payload)
+        return event.decryptError ?? "";
+    if (payload.type === "user_prompt")
+        return payload.text;
+    if (payload.type === "text_delta")
+        return payload.text;
+    if (payload.type === "tool_call")
+        return `${payload.title ?? "tool"} ${payload.status ?? ""} ${payload.text ?? ""}`;
+    if (payload.type === "status" || payload.type === "control")
+        return payload.text;
+    if (payload.type === "done")
+        return payload.error ?? payload.stopReason ?? payload.status;
+    return "";
+}
+function isVisibleTranscriptPayloadEvent(event) {
+    const payload = event.decoded;
+    if (!payload)
+        return false;
+    return payload.type === "user_prompt" ||
+        (payload.type === "text_delta" && payload.stream !== "thought" && payload.text.trim().length > 0) ||
+        payload.type === "tool_call";
+}
+function compactEventDiagnostic(event) {
+    const text = compactText(eventPayloadText(event), 120);
+    return {
+        id: event.id,
+        ...(event.messageId ? { messageId: event.messageId } : {}),
+        payloadType: event.decoded?.type ?? (event.decryptError ? "decrypt_error" : "encrypted"),
+        seq: event.seq,
+        ...(text ? { textPreview: text } : {}),
+        turnId: event.turnId,
+        ...(event.turnSeq !== undefined ? { turnSeq: event.turnSeq } : {}),
+    };
+}
+function repairHeadInputForLatestCompletedEvent(events) {
+    const doneEvent = [...events]
+        .sort(compareSessionEventLogicalOrder)
+        .reverse()
+        .find((event) => event.decoded?.type === "done" && event.decoded.status === "completed");
+    const done = doneEvent?.decoded;
+    if (!doneEvent || done?.type !== "done") {
+        throw new CliError("No completed done event is available for head repair", "SESSION_HEAD_REPAIR_UNAVAILABLE");
+    }
+    if (!doneEvent.messageId) {
+        throw new CliError("Latest completed done event has no messageId basis", "SESSION_HEAD_REPAIR_UNAVAILABLE");
+    }
+    const turnSeq = doneEvent.turnSeq;
+    if (turnSeq === undefined) {
+        throw new CliError("Latest completed done event has no turnSeq basis", "SESSION_HEAD_REPAIR_UNAVAILABLE");
+    }
+    const currentHead = done.currentHead ?? done.lastTurnId ?? doneEvent.turnId;
+    const lastTurnId = done.lastTurnId ?? done.currentHead ?? doneEvent.turnId;
+    return {
+        currentHead,
+        lastTurnId,
+        status: "completed",
+        basis: {
+            turnId: doneEvent.turnId,
+            eventMessageId: doneEvent.messageId,
+            turnSeq,
+            ...(doneEvent.occurredAt === undefined ? {} : { occurredAt: doneEvent.occurredAt }),
+        },
+    };
+}
+function eventCollectionDiagnostics(events) {
+    return {
+        decryptErrors: events.filter((event) => event.decryptError).length,
+        first: events.slice(0, 5).map(compactEventDiagnostic),
+        last: events.slice(-5).map(compactEventDiagnostic),
+        messagePrefixes: countBy(events.map((event) => messagePrefix(event.messageId))),
+        payloadTypes: countBy(events.map((event) => event.decoded?.type ?? (event.decryptError ? "decrypt_error" : "encrypted"))),
+        total: events.length,
+        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;
+    }
+    if (session.headBasis?.eventId !== undefined && session.headBasis.eventId >= turn.firstEventId && session.headBasis.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;
+}
+function numberMetadata(metadata, key) {
+    const value = metadata[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function diagnosticSessionMetadata(metadata) {
+    const runtime = isRecord(metadata.runtime) ? metadata.runtime : {};
+    return {
+        agent: stringMetadata(metadata, "agent"),
+        cwd: stringMetadata(metadata, "cwd"),
+        name: stringMetadata(metadata, "name"),
+        providerName: stringMetadata(metadata, "providerName"),
+        importedFromRuntimeSessionId: stringMetadata(metadata, "importedFromRuntimeSessionId"),
+        runtime: {
+            backend: stringMetadata(runtime, "backend"),
+            runtimeSessionName: stringMetadata(runtime, "runtimeSessionName"),
+            acpxRecordId: stringMetadata(runtime, "acpxRecordId"),
+            backendSessionId: stringMetadata(runtime, "backendSessionId"),
+            agentSessionId: stringMetadata(runtime, "agentSessionId"),
+            externalProviderId: stringMetadata(runtime, "externalProviderId"),
+            externalHandleSessionId: isRecord(runtime.externalHandle) ? stringMetadata(runtime.externalHandle, "sessionId") : undefined,
+        },
+        historicalBackfillStatus: stringMetadata(metadata, "historicalBackfillStatus") ?? stringMetadata(metadata, "historicalBackfill"),
+        historicalBackfillCursor: numberMetadata(metadata, "historicalBackfillCursor"),
+        historicalBackfillTotalEvents: numberMetadata(metadata, "historicalBackfillTotalEvents"),
+        availableHistoricalEvents: numberMetadata(metadata, "availableHistoricalEvents"),
+        backfilledEvents: numberMetadata(metadata, "backfilledEvents"),
+        historicalOlderBackfilledEvents: numberMetadata(metadata, "historicalOlderBackfilledEvents"),
+        historicalTailRepairedEvents: numberMetadata(metadata, "historicalTailRepairedEvents"),
+        truncatedHistoricalBackfill: metadata.truncatedHistoricalBackfill === true,
+        importRequestId: stringMetadata(metadata, "importRequestId"),
+        currentHead: stringMetadata(metadata, "currentHead"),
+        emptyRuntimeSession: metadata.emptyRuntimeSession === true,
+    };
+}
+function addRuntimeSessionId(ids, value) {
+    if (typeof value === "string" && value.trim())
+        ids.add(value.trim());
+}
+function metadataRuntimeSessionIds(metadata) {
+    const ids = new Set();
+    addRuntimeSessionId(ids, stringMetadata(metadata, "importedFromRuntimeSessionId"));
+    const runtime = isRecord(metadata.runtime) ? metadata.runtime : {};
+    addRuntimeSessionId(ids, runtime.backendSessionId);
+    addRuntimeSessionId(ids, runtime.agentSessionId);
+    addRuntimeSessionId(ids, runtime.acpxRecordId);
+    if (isRecord(runtime.externalHandle))
+        addRuntimeSessionId(ids, runtime.externalHandle.sessionId);
+    return ids;
+}
+function normalizedMatchValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim().toLocaleLowerCase() : undefined;
+}
+function runtimeBindingCandidates(session, metadata, historicalSessions) {
+    const knownRuntimeIds = metadataRuntimeSessionIds(metadata);
+    const expectedAgent = stringMetadata(metadata, "agent") ?? session.agent;
+    const expectedCwd = stringMetadata(metadata, "cwd") ?? session.cwd;
+    const names = new Set([
+        normalizedMatchValue(stringMetadata(metadata, "name")),
+        normalizedMatchValue(stringMetadata(metadata, "providerName")),
+        normalizedMatchValue(session.name),
+    ].filter((value) => Boolean(value)));
+    const summaries = new Set([
+        normalizedMatchValue(stringMetadata(metadata, "importedSummary")),
+        normalizedMatchValue(session.name),
+    ].filter((value) => Boolean(value)));
+    return historicalSessions
+        .filter((historical) => historical.agent === expectedAgent &&
+        historical.cwd === expectedCwd &&
+        !knownRuntimeIds.has(historical.runtimeSessionId))
+        .map((historical) => {
+        const reasons = [];
+        let score = 0;
+        const historicalName = normalizedMatchValue(historical.name ?? historical.runtimeSessionName);
+        const historicalSummary = normalizedMatchValue(historical.summary);
+        if (historicalName && names.has(historicalName)) {
+            score += 100;
+            reasons.push("name");
+        }
+        if (historicalSummary && summaries.has(historicalSummary)) {
+            score += 30;
+            reasons.push("summary");
+        }
+        if (historical.loadedSessionId) {
+            score -= 20;
+            reasons.push("already-loaded");
+        }
+        if (score <= 0)
+            return undefined;
+        return {
+            runtimeSessionId: historical.runtimeSessionId,
+            agent: historical.agent,
+            cwd: historical.cwd,
+            name: historical.name ?? historical.runtimeSessionName,
+            summary: historical.summary,
+            updatedAt: historical.updatedAt,
+            score,
+            reasons,
+            ...(historical.runtimeState === "archived" ? { runtimeState: "archived" } : {}),
+        };
+    })
+        .filter((candidate) => Boolean(candidate))
+        .sort((left, right) => right.score - left.score || right.updatedAt - left.updatedAt || left.runtimeSessionId.localeCompare(right.runtimeSessionId));
+}
+function shouldSearchRuntimeBindingCandidates(latestEvents, metadata) {
+    const available = numberMetadata(metadata, "availableHistoricalEvents");
+    const emitted = numberMetadata(metadata, "backfilledEvents");
+    return latestEvents.length === 0 &&
+        (available === undefined || available === 0) &&
+        (emitted === undefined || emitted === 0);
+}
+function runtimeBindingSuspected(candidates) {
+    return candidates.some((candidate) => candidate.reasons.includes("name") && !candidate.reasons.includes("already-loaded"));
+}
+async function findRuntimeBindingCandidates(client, session, metadata, flags) {
+    const limit = parsePositiveIntFlag(flags, "runtime-limit") ?? 500;
+    const result = await listWorkspaceHistoricalSessions(client, {
+        machineId: session.machineId,
+        cwd: stringMetadata(metadata, "cwd") ?? session.cwd,
+        agent: stringMetadata(metadata, "agent") ?? session.agent,
+        includeArchived: true,
+        limit,
+    });
+    return {
+        candidates: runtimeBindingCandidates(session, metadata, result.sessions).slice(0, 8),
+        searched: true,
+        limit,
     };
 }
+async function resolveRuntimeBindingRepairTarget(client, session, metadata, flags) {
+    const runtimeSessionId = typeof flags["runtime-session"] === "string" ? flags["runtime-session"].trim() : undefined;
+    const limit = parsePositiveIntFlag(flags, "runtime-limit") ?? 500;
+    const result = await listWorkspaceHistoricalSessions(client, {
+        machineId: session.machineId,
+        cwd: stringMetadata(metadata, "cwd") ?? session.cwd,
+        agent: stringMetadata(metadata, "agent") ?? session.agent,
+        includeArchived: true,
+        limit,
+    });
+    const candidateDiagnostics = runtimeBindingCandidates(session, metadata, result.sessions);
+    if (runtimeSessionId) {
+        const explicit = result.sessions.find((item) => item.runtimeSessionId === runtimeSessionId);
+        if (!explicit)
+            throw new CliError(`Runtime session not found in the first ${limit} historical rows: ${runtimeSessionId}`, "RUNTIME_SESSION_NOT_FOUND");
+        return { candidate: explicit, candidates: candidateDiagnostics.slice(0, 8) };
+    }
+    const usableCandidates = candidateDiagnostics.filter((candidate) => !candidate.reasons.includes("already-loaded"));
+    if (usableCandidates.length === 0) {
+        throw new CliError("No unambiguous runtime binding repair candidate found. Re-run with --runtime-session <id>.", "SESSION_BINDING_REPAIR_UNAVAILABLE");
+    }
+    const [first, second] = usableCandidates;
+    if (second && second.score === first.score) {
+        throw new CliError("Multiple runtime binding repair candidates found. Re-run with --runtime-session <id>.", "SESSION_BINDING_REPAIR_AMBIGUOUS");
+    }
+    const selected = result.sessions.find((item) => item.runtimeSessionId === first.runtimeSessionId);
+    if (!selected)
+        throw new CliError("Selected repair candidate disappeared from runtime history", "SESSION_BINDING_REPAIR_UNAVAILABLE");
+    return { candidate: selected, candidates: candidateDiagnostics.slice(0, 8) };
+}
 export async function handleSession({ domain, action, positional, flags }) {
     if (domain !== "session")
         return false;
@@ -66,8 +365,21 @@ export async function handleSession({ domain, action, positional, flags }) {
         const requestedRuntimeName = typeof flags.name === "string" ? flags.name : undefined;
         const name = "main";
         const permissionMode = parsePermissionMode(flags["permission-mode"] ?? flags.permission);
+        const model = typeof flags.model === "string" && flags.model.trim() ? flags.model.trim() : undefined;
+        const tags = tagsFromFlags(flags);
         const client = await makeClient();
-        const result = await client.createSession({ machineId, agent, cwd, name, runtimeName: requestedRuntimeName, permissionMode });
+        const result = await client.createSession({
+            machineId,
+            agent,
+            cwd,
+            name,
+            runtimeName: requestedRuntimeName,
+            permissionMode,
+            model,
+            ...(tags.length > 0 ? { tags } : {}),
+            ...(flags.hidden === true ? { hiddenFromWorkspace: true } : {}),
+            ...(typeof flags.source === "string" ? { source: flags.source } : {}),
+        });
         const session = result.sessionId ? await client.getSession(result.sessionId) : undefined;
         const projectedSession = session
             ? wantsVerbose(flags)
@@ -89,8 +401,13 @@ export async function handleSession({ domain, action, positional, flags }) {
             agent: typeof flags.agent === "string" ? flags.agent : undefined,
             cwd: cwdFilter,
             name: typeof flags.name === "string" ? flags.name : undefined,
+            tags: tagsFromFlags(flags),
         });
-        const visibleSessions = flags.all === true ? allSessions : allSessions.filter((session) => session.status !== "closed");
+        const visibleSessions = flags.all === true
+            ? allSessions
+            : (await Promise.all(allSessions.map(async (session) => ({ session, metadata: await client.decodeSessionMetadata(session) }))))
+                .filter(({ session, metadata }) => session.status !== "closed" && metadata.hiddenFromWorkspace !== true)
+                .map(({ session }) => session);
         const { items: sessions, page } = selectWindow(visibleSessions, flags, 20);
         if (wantsJson(flags) || wantsVerbose(flags)) {
             const machinesById = new Map();
@@ -126,6 +443,37 @@ export async function handleSession({ domain, action, positional, flags }) {
         }
         return true;
     }
+    if (action === "tag") {
+        const subaction = requirePositional(positional[0], "tag action");
+        const sessionId = requirePositional(positional[1], "sessionId");
+        const client = await makeClient();
+        const session = await client.getSession(sessionId);
+        if (!session)
+            throw new CliError("Session not found", "SESSION_NOT_FOUND");
+        const metadata = await client.decodeSessionMetadata(session);
+        const currentTags = normalizeSessionTags(metadata.tags);
+        if (subaction === "list") {
+            ok("session.tag.list", { sessionId, tags: currentTags, tagKeys: sessionTagKeys(currentTags) }, { sessionId });
+            return true;
+        }
+        const requested = tagsFromFlags(flags);
+        if (requested.length === 0)
+            throw new CliError("Missing --tag", "MISSING_ARGUMENT");
+        if (subaction === "add") {
+            const tags = normalizeSessionTags([...currentTags, ...requested]);
+            const result = await client.setSessionTags(sessionId, tags);
+            ok("session.tag.add", { sessionId, tags: result.tags, tagKeys: sessionTagKeys(result.tags) }, { sessionId });
+            return true;
+        }
+        if (subaction === "remove") {
+            const removeKeys = new Set(sessionTagKeys(requested));
+            const tags = currentTags.filter((tag) => !removeKeys.has(sessionTagKeys([tag])[0]));
+            const result = await client.setSessionTags(sessionId, tags);
+            ok("session.tag.remove", { sessionId, tags: result.tags, tagKeys: sessionTagKeys(result.tags) }, { sessionId });
+            return true;
+        }
+        throw new CliError(`Unsupported session tag action: ${subaction}`, "USAGE");
+    }
     if (action === "status") {
         const sessionId = requirePositional(positional[0], "sessionId");
         const client = await makeClient();
@@ -140,7 +488,7 @@ export async function handleSession({ domain, action, positional, flags }) {
         const latestCompletedTurn = turns.find((turn) => turn.status === "completed");
         const latestTerminalTurn = turns.find((turn) => turn.status !== "running");
         const orchestration = deriveOrchestration(session, recentEvents);
-        const latestOutput = await readStoredTurnOutput(session.id).catch(() => undefined);
+        const latestOutput = await readStoredTurnOutput(session.id, latestCompletedTurn?.turnId).catch(async () => await readStoredTurnOutput(session.id).catch(() => undefined));
         const terminalOutput = latestCompletedTurn?.output || latestCompletedTurn?.terminalText || latestTerminalTurn?.output || latestTerminalTurn?.terminalText || undefined;
         const data = {
             state: orchestration.state,
@@ -192,6 +540,170 @@ export async function handleSession({ domain, action, positional, flags }) {
         }
         return true;
     }
+    if (action === "diagnose") {
+        const sessionId = requirePositional(positional[0], "sessionId");
+        const limit = parsePositiveIntFlag(flags, "limit") ?? 200;
+        const client = await makeClient();
+        const snapshot = await client.snapshot();
+        const initialSession = snapshot.sessions.find((item) => item.id === sessionId);
+        if (!initialSession)
+            throw new CliError("Session not found", "SESSION_NOT_FOUND");
+        let session = initialSession;
+        const machine = snapshot.machines.find((item) => item.id === session.machineId);
+        const metadata = await client.decodeSessionMetadata(session);
+        const latestPage = await client.collectPage(session.id, { limit });
+        const turns = summarizeTurns(latestPage.events);
+        const latestCompletedTurn = turns.find((turn) => turn.status === "completed");
+        const latestTerminalTurn = turns.find((turn) => turn.status !== "running");
+        const runtimeBinding = shouldSearchRuntimeBindingCandidates(latestPage.events, metadata)
+            ? await findRuntimeBindingCandidates(client, session, metadata, flags)
+            : { candidates: [], searched: false, limit: parsePositiveIntFlag(flags, "runtime-limit") ?? 500 };
+        const repair = flags["repair-head"] === true
+            ? await client.repairSessionHead(session.id, repairHeadInputForLatestCompletedEvent(latestPage.events))
+            : undefined;
+        if (repair)
+            session = repair.session;
+        const data = {
+            generatedAt: new Date().toISOString(),
+            session: {
+                id: session.id,
+                machineId: session.machineId,
+                agent: session.agent,
+                status: session.status,
+                name: session.name,
+                cwd: session.cwd,
+                historyModel: session.historyModel ?? "append-only",
+                currentHead: session.currentHead,
+                lastTurnId: session.lastTurnId,
+                headBasis: session.headBasis,
+                sourceSessionId: session.sourceSessionId,
+                sourceCheckpointId: session.sourceCheckpointId,
+                updatedAt: session.updatedAt,
+                capabilities: session.capabilities,
+            },
+            machine: machine ? {
+                id: machine.id,
+                name: machine.name,
+                online: machine.online,
+                agents: machine.capabilities.agents.map((agent) => ({
+                    id: agent.id,
+                    historyModel: agent.historyModel,
+                    sessionPrimitives: agent.sessionPrimitives,
+                })),
+            } : undefined,
+            metadata: diagnosticSessionMetadata(metadata),
+            latestPage: {
+                limit,
+                hasMoreBefore: latestPage.hasMoreBefore,
+                newestCursor: latestPage.newestCursor,
+                newestEventId: latestPage.newestEventId,
+                oldestCursor: latestPage.oldestCursor,
+                oldestEventId: latestPage.oldestEventId,
+                events: eventCollectionDiagnostics(latestPage.events),
+            },
+            turns: {
+                count: turns.length,
+                latestCompletedTurn: compactTurnRef(latestCompletedTurn),
+                latestTerminalTurn: compactTurnRef(latestTerminalTurn),
+                first: turns.slice(0, 4).map(compactTurnRef),
+                last: turns.slice(-4).map(compactTurnRef),
+            },
+            diagnosis: {
+                importedRuntimeSessionId: stringMetadata(metadata, "importedFromRuntimeSessionId"),
+                latestPageEmpty: latestPage.events.length === 0,
+                latestPageHasVisibleTranscript: latestPage.events.some(isVisibleTranscriptPayloadEvent),
+                metadataReportsEmptyRuntimeSession: metadata.emptyRuntimeSession === true,
+                backfillAvailableEvents: numberMetadata(metadata, "availableHistoricalEvents"),
+                backfillEmittedEvents: numberMetadata(metadata, "backfilledEvents"),
+                backfillStatus: stringMetadata(metadata, "historicalBackfillStatus") ?? stringMetadata(metadata, "historicalBackfill"),
+                wrongRuntimeBindingSuspected: runtimeBindingSuspected(runtimeBinding.candidates),
+                runtimeBindingCandidateCount: runtimeBinding.candidates.length,
+                staleHeadSuspected: staleHeadSuspected(session, latestCompletedTurn),
+                headMatchesLatestCompletedTurn: headMatchesTurn(session, latestCompletedTurn),
+            },
+            runtimeBinding: {
+                searched: runtimeBinding.searched,
+                searchLimit: runtimeBinding.limit,
+                suspected: runtimeBindingSuspected(runtimeBinding.candidates),
+                candidates: runtimeBinding.candidates,
+                repairCommand: runtimeBinding.candidates[0]
+                    ? `happy-elves session repair-binding ${session.id} --runtime-session ${runtimeBinding.candidates[0].runtimeSessionId} --json`
+                    : undefined,
+            },
+            repair: repair ? {
+                advanced: repair.advanced,
+                settled: repair.settled,
+                basis: repair.basis,
+                status: repair.session.status,
+                currentHead: repair.session.currentHead,
+                lastTurnId: repair.session.lastTurnId,
+                reason: repair.reason,
+            } : undefined,
+        };
+        if (wantsJson(flags) || wantsVerbose(flags)) {
+            ok("session.diagnose", data, { machineId: session.machineId, sessionId: session.id });
+        }
+        else {
+            console.log(`Session: ${session.id}  ${session.status}  ${session.agent}`);
+            console.log(`Machine: ${session.machineId}${machine ? `  ${machine.online ? "online" : "offline"}` : ""}`);
+            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}`);
+            if (data.runtimeBinding.suspected && data.runtimeBinding.candidates[0]) {
+                console.log(`Runtime binding: suspected wrong binding; candidate=${data.runtimeBinding.candidates[0].runtimeSessionId}`);
+                console.log(`Repair: ${data.runtimeBinding.repairCommand}`);
+            }
+        }
+        return true;
+    }
+    if (action === "repair-binding") {
+        const sessionId = requirePositional(positional[0], "sessionId");
+        const client = await makeClient();
+        const session = await client.getSession(sessionId);
+        if (!session)
+            throw new CliError("Session not found", "SESSION_NOT_FOUND");
+        if (session.status === "running")
+            throw new CliError("Cannot repair binding for a running session", "SESSION_BINDING_REPAIR_RUNNING");
+        const metadata = await client.decodeSessionMetadata(session);
+        const { candidate, candidates } = await resolveRuntimeBindingRepairTarget(client, session, metadata, flags);
+        const name = typeof flags.name === "string" && flags.name.trim()
+            ? flags.name.trim()
+            : stringMetadata(metadata, "name") ?? session.name ?? candidate.name ?? candidate.summary ?? candidate.runtimeSessionId;
+        const imported = await client.importHistoricalSession({
+            machineId: session.machineId,
+            agent: candidate.agent,
+            cwd: candidate.cwd,
+            runtimeSessionId: candidate.runtimeSessionId,
+            name,
+            summary: candidate.summary,
+            runtimeState: candidate.runtimeState,
+            ...(candidate.name ? { providerName: candidate.name } : {}),
+        });
+        const closeSource = flags["keep-source"] !== true;
+        let sourceClosed = false;
+        if (closeSource) {
+            await client.close(session.id, `replaced by runtime session ${candidate.runtimeSessionId}`);
+            sourceClosed = true;
+        }
+        ok("session.repair-binding", {
+            sourceSessionId: session.id,
+            sessionId: imported.sessionId,
+            runtimeSessionId: candidate.runtimeSessionId,
+            mode: imported.mode === "existing" ? "existing" : "created",
+            sourceClosed,
+            candidate: {
+                runtimeSessionId: candidate.runtimeSessionId,
+                name: candidate.name ?? candidate.runtimeSessionName,
+                summary: candidate.summary,
+                updatedAt: candidate.updatedAt,
+                ...(candidate.runtimeState === "archived" ? { runtimeState: "archived" } : {}),
+            },
+            candidates,
+        }, { requestId: imported.requestId, machineId: session.machineId, sessionId: imported.sessionId });
+        return true;
+    }
     if (action === "history") {
         const machineId = requireString(flags, "machine");
         const limit = parsePositiveIntFlag(flags, "limit") ?? 20;
@@ -280,7 +792,7 @@ export async function handleSession({ domain, action, positional, flags }) {
         ok("session.continue", {
             sessionId: continued.sessionId,
             runtimeSessionId,
-            mode: "created",
+            mode: continued.mode === "existing" ? "existing" : "created",
             ...(historical.runtimeState === "archived" ? { runtimeState: "archived" } : {}),
         }, { requestId: continued.requestId, machineId, sessionId: continued.sessionId });
         return true;