@cydm/happy-elves 0.1.0-beta.40 → 0.1.0-beta.42

package/apps/cli/dist/commands/lib/args.js

@@ -27,6 +27,8 @@ const valueFlags = new Set([
     "reason",
     "relay",
     "root",
+    "runtime-limit",
+    "runtime-session",
     "shell",
     "actions",
     "expires-in",
@@ -58,6 +60,7 @@ const booleanFlags = new Set([
     "h",
     "include-archived",
     "json",
+    "keep-source",
     "local",
     "no-open",
     "no-wait",

package/apps/cli/dist/commands/lib/usage.js

@@ -50,7 +50,8 @@ Check local controller config, relay reachability, and daemon state.
   happy-elves session history --machine <machineId> [--cwd <path>] [--agent <agent>] [--include-archived] [--limit 20] --json
   happy-elves session continue <runtimeSessionId> --machine <machineId> [--name <name>] --json
   happy-elves session status <sessionId> [--verbose] [--json]
-  happy-elves session diagnose <sessionId> [--limit 200] [--repair-head] [--json]
+  happy-elves session diagnose <sessionId> [--limit 200] [--runtime-limit 500] [--repair-head] [--json]
+  happy-elves session repair-binding <sessionId> [--runtime-session <runtimeSessionId>] [--runtime-limit 500] [--keep-source] --json
   happy-elves session close <sessionId> [--reason <reason>] --json
 
 Session management:
@@ -64,6 +65,8 @@ Session management:
   counters, and latest materialized relay page counts for debugging empty or
   stale transcripts. --repair-head advances a stale canonical head to the
   latest completed relay event when the relay already has the event basis.
+  repair-binding imports the matching runtime history row as a new loaded
+  session and closes the empty/stale source session unless --keep-source is set.
   close archives a loaded session. There is no separate archive command.
 `,
     turn: `Usage:
@@ -141,8 +144,9 @@ Core commands:
   session create --machine <machineId> [--agent codex] [--cwd <path>] [--name <name>] --json
   session history --machine <machineId> [--cwd <path>] [--limit 20] --json
   session continue <runtimeSessionId> --machine <machineId> --json
+  session repair-binding <sessionId> [--runtime-session <runtimeSessionId>] --json
   session status <sessionId> [--verbose] [--json]
-  session diagnose <sessionId> [--limit 200] [--repair-head] [--json]
+  session diagnose <sessionId> [--limit 200] [--runtime-limit 500] [--repair-head] [--json]
   session close <sessionId> [--reason <reason>] --json
 
   turn list <sessionId> [--limit 10] [--json]
@@ -217,6 +221,9 @@ Session management:
   provider sessions unless --include-archived is set.
   session continue <runtimeSessionId> --machine <machineId> --json continues a
   runtime history row as a loaded session, or returns an existing sessionId.
+  session repair-binding <sessionId> --json recovers a loaded session that was
+  bound to the wrong/empty provider history by importing the matching runtime
+  history row as a new loaded session.
   session close <sessionId> --reason "archived" --json archives a loaded
   session. There is no separate archive command.
 

package/apps/cli/dist/commands/lib/workspace.js

@@ -2,7 +2,7 @@ import { CliError } from "../../errors.js";
 import { showMachine } from "./session-view.js";
 export async function listWorkspaceHistoricalSessions(client, input) {
     const snapshot = await client.snapshot();
-    const providerLimit = Math.min(200, Math.max(input.limit, 50));
+    const providerPageSize = Math.min(200, Math.max(Math.min(input.limit, 200), 50));
     const selectedMachines = snapshot.machines.filter((machine) => {
         if (input.machineId)
             return machine.id === input.machineId;
@@ -17,13 +17,26 @@ export async function listWorkspaceHistoricalSessions(client, input) {
     const rows = await Promise.all(machines.map(async ({ machine, projected }) => {
         const machineName = projected.metadata.name ?? projected.metadata.hostname ?? machine.name;
         try {
-            const sessions = await client.listHistoricalSessions({
-                machineId: machine.id,
-                cwd: input.cwd,
-                agent: input.agent,
-                includeArchived: input.includeArchived,
-                limit: providerLimit,
-            });
+            const sessions = [];
+            let cursor;
+            const seenCursors = new Set();
+            while (sessions.length < input.limit) {
+                const page = await client.listHistoricalSessionsPage({
+                    machineId: machine.id,
+                    cwd: input.cwd,
+                    agent: input.agent,
+                    includeArchived: input.includeArchived,
+                    limit: providerPageSize,
+                    cursor,
+                });
+                sessions.push(...page.sessions);
+                if (!page.hasMore || !page.nextCursor)
+                    break;
+                if (seenCursors.has(page.nextCursor))
+                    break;
+                seenCursors.add(page.nextCursor);
+                cursor = page.nextCursor;
+            }
             return {
                 sessions: sessions
                     .filter((session) => input.includeArchived === true || session.runtimeState !== "archived")

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

@@ -125,6 +125,7 @@ function repairHeadInputForLatestCompletedEvent(events) {
     return {
         currentHead,
         lastTurnId,
+        status: "completed",
         basis: {
             turnId: doneEvent.turnId,
             eventMessageId: doneEvent.messageId,
@@ -217,6 +218,130 @@ function diagnosticSessionMetadata(metadata) {
         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;
@@ -363,15 +488,15 @@ export async function handleSession({ domain, action, positional, flags }) {
         if (!initialSession)
             throw new CliError("Session not found", "SESSION_NOT_FOUND");
         let session = initialSession;
-        if (flags["repair-head"] === true && session.status === "running") {
-            throw new CliError("Cannot repair a running session head", "SESSION_HEAD_REPAIR_RUNNING");
-        }
         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;
@@ -430,12 +555,25 @@ export async function handleSession({ domain, action, positional, flags }) {
                 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,
@@ -452,9 +590,59 @@ export async function handleSession({ domain, action, positional, flags }) {
             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: "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;

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

@@ -4,7 +4,7 @@ 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 emitSessionHeadAdvanced(ws: WebSocket, sessionId: string, head: HistoricalSessionHead, encryptedMetadata?: EncryptedEnvelope, status?: "completed" | "cancelled" | "failed"): Promise<void>;
 export declare function emitTranscriptReplacement(ws: WebSocket, config: DaemonConfig, sessionId: string, events: RuntimeHistoricalEvent[], input?: {
     requestId?: string;
     currentHead?: string;

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

@@ -32,13 +32,14 @@ export async function emitRuntimeTailEvents(ws, config, sessionId, events, start
         }, ws);
     }
 }
-export async function emitSessionHeadAdvanced(ws, sessionId, head, encryptedMetadata) {
+export async function emitSessionHeadAdvanced(ws, sessionId, head, encryptedMetadata, status) {
     await sendReliable({
         type: "machine:sessionHeadAdvanced",
         sessionId,
         currentHead: head.currentHead,
         lastTurnId: head.lastTurnId,
         basis: head.basis,
+        status,
         encryptedMetadata,
     }, ws);
 }

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

@@ -605,7 +605,7 @@ async function backfillHistoricalEvents(ws, config, session, runtimeSessionId =
         await emitSessionHeadAdvanced(ws, session.sessionId, head, await encryptedSessionMetadata(config, session.sessionId, backfilledSession, {
             ...historicalBackfillMetadata(result),
             historicalBackfilledAt: new Date().toISOString(),
-        }));
+        }), "completed");
     }
     return result;
 }

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

@@ -121,7 +121,7 @@ export async function handlePrompt(ws, config, command) {
                 currentHead: result.currentHead,
                 lastTurnId: result.lastTurnId,
             });
-        await refreshAuthoritativeTranscriptAfterTurn(ws, config, session, command.requestId, result.currentHead, result.lastTurnId);
+        await refreshAuthoritativeTranscriptAfterTurn(ws, config, session, command.requestId, result.currentHead, result.lastTurnId, result.status);
         releasePromptTurn();
         await sendReliable({
             type: "machine:turnDone",

package/apps/daemon/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cydm/happy-elves-daemon",
-  "version": "0.1.0-beta.40",
+  "version": "0.1.0-beta.42",
   "private": true,
   "type": "module"
 }

package/apps/relay/dist/http-routes.js

@@ -249,7 +249,7 @@ export function registerHttpRoutes(app, context, controllerInviteTtlMs) {
             .get(token.account_id, params.sessionId);
         if (!session)
             throw new HttpError(404, "SESSION_NOT_FOUND", "Session not found");
-        if (session.status === "running") {
+        if (session.status === "running" && !body.status) {
             throw new HttpError(409, "SESSION_HEAD_REPAIR_RUNNING", "Cannot repair a running session head");
         }
         const basisEvent = context.db
@@ -265,18 +265,28 @@ export function registerHttpRoutes(app, context, controllerInviteTtlMs) {
         const currentOrder = sessionHeadBasisOrderForRow(context.db, session);
         const rewriteFenced = typeof session.head_basis_message_id === "string" &&
             session.head_basis_message_id.startsWith("rewrite:");
-        const advanced = !rewriteFenced && compareHeadOrders(nextOrder, currentOrder) > 0;
-        if (advanced) {
+        const comparison = compareHeadOrders(nextOrder, currentOrder);
+        const currentHeadAlreadySettled = session.current_head === `event:${basisEvent.id}` ||
+            session.current_head === body.currentHead ||
+            session.last_turn_id === body.lastTurnId;
+        const advanced = !rewriteFenced && comparison > 0;
+        const statusChanged = !rewriteFenced &&
+            body.status !== undefined &&
+            session.status === "running" &&
+            comparison === 0 &&
+            currentHeadAlreadySettled;
+        if (advanced || statusChanged) {
             const ts = context.now();
             context.db.prepare(`UPDATE sessions
-         SET current_head = ?,
-             last_turn_id = ?,
-             head_basis_event_id = ?,
-             head_basis_message_id = ?,
-             head_basis_logical_time = ?,
-             head_basis_turn_seq = ?,
+         SET status = COALESCE(?, status),
+             current_head = COALESCE(?, current_head),
+             last_turn_id = COALESCE(?, last_turn_id),
+             head_basis_event_id = COALESCE(?, head_basis_event_id),
+             head_basis_message_id = COALESCE(?, head_basis_message_id),
+             head_basis_logical_time = COALESCE(?, head_basis_logical_time),
+             head_basis_turn_seq = COALESCE(?, head_basis_turn_seq),
              updated_at = ?
-         WHERE id = ? AND account_id = ?`).run(body.currentHead, body.lastTurnId, basisEvent.id, basisEvent.message_id, nextOrder.time, nextOrder.seq, ts, params.sessionId, token.account_id);
+         WHERE id = ? AND account_id = ?`).run(body.status && session.status === "running" ? body.status : null, advanced ? body.currentHead : null, advanced ? body.lastTurnId : null, advanced ? basisEvent.id : null, advanced ? basisEvent.message_id : null, advanced ? nextOrder.time : null, advanced ? nextOrder.seq : null, ts, params.sessionId, token.account_id);
         }
         const row = context.db
             .prepare("SELECT * FROM sessions WHERE account_id = ? AND id = ?")
@@ -294,6 +304,7 @@ export function registerHttpRoutes(app, context, controllerInviteTtlMs) {
                 logicalTime: nextOrder.time,
                 turnSeq: nextOrder.seq,
             },
+            ...(statusChanged ? { settled: true } : {}),
             ...(rewriteFenced ? { reason: "rewrite-fenced" } : {}),
         };
     });

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

@@ -49,6 +49,11 @@ export declare const sessionEventsQuerySchema: z.ZodObject<{
 export declare const sessionHeadAdvanceSchema: z.ZodObject<{
     currentHead: z.ZodString;
     lastTurnId: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+    }>>;
     basis: z.ZodObject<{
         turnId: z.ZodString;
         eventMessageId: z.ZodString;

package/apps/relay/dist/http-schemas.js

@@ -56,6 +56,7 @@ export const sessionEventsQuerySchema = z.object({
 export const sessionHeadAdvanceSchema = z.object({
     currentHead: z.string().min(1),
     lastTurnId: z.string().min(1),
+    status: z.enum(["completed", "cancelled", "failed"]).optional(),
     basis: z.object({
         turnId: z.string().min(1),
         eventMessageId: z.string().min(1),

package/apps/relay/dist/machine-handlers.js

@@ -418,6 +418,7 @@ export function handleMachineMessage(context, connection, message) {
             currentHead: message.currentHead,
             lastTurnId: message.lastTurnId,
             basis: message.basis,
+            status: message.status,
             ...(message.encryptedMetadata ? { encryptedMetadata: message.encryptedMetadata } : {}),
         };
         const result = applySessionHeadAdvance(db, input, ts);
@@ -634,6 +635,7 @@ function pendingRowToHeadAdvanceInput(row) {
             turnSeq: row.basis_turn_seq,
             ...(row.basis_occurred_at !== null ? { occurredAt: row.basis_occurred_at } : {}),
         },
+        status: "completed",
         ...(row.encrypted_metadata ? { encryptedMetadata: JSON.parse(row.encrypted_metadata) } : {}),
     };
 }
@@ -655,19 +657,28 @@ function applySessionHeadAdvance(db, input, ts) {
         sessionRow.head_basis_message_id.startsWith(REWRITE_HEAD_BASIS_PREFIX);
     const comparison = compareHeadBasisOrder(nextOrder, currentOrder);
     const currentHeadIsBasisEvent = sessionRow.current_head === `event:${basisEvent.id}`;
+    const currentHeadAlreadySettled = currentHeadIsBasisEvent ||
+        sessionRow.current_head === input.currentHead ||
+        sessionRow.last_turn_id === input.lastTurnId;
     const shouldAdvance = !rewriteFenced && (comparison > 0 || (comparison === 0 && currentHeadIsBasisEvent));
-    if (!shouldAdvance)
+    const shouldSettleStatus = !rewriteFenced &&
+        input.status !== undefined &&
+        sessionRow.status === "running" &&
+        comparison === 0 &&
+        currentHeadAlreadySettled;
+    if (!shouldAdvance && !shouldSettleStatus)
         return { status: "noop", session: sessionRow };
     db.prepare(`UPDATE sessions
-     SET current_head = ?,
-         last_turn_id = ?,
-         head_basis_event_id = ?,
-         head_basis_message_id = ?,
-         head_basis_logical_time = ?,
-         head_basis_turn_seq = ?,
+     SET status = COALESCE(?, status),
+         current_head = COALESCE(?, current_head),
+         last_turn_id = COALESCE(?, last_turn_id),
+         head_basis_event_id = COALESCE(?, head_basis_event_id),
+         head_basis_message_id = COALESCE(?, head_basis_message_id),
+         head_basis_logical_time = COALESCE(?, head_basis_logical_time),
+         head_basis_turn_seq = COALESCE(?, head_basis_turn_seq),
          encrypted_metadata = COALESCE(?, encrypted_metadata),
          updated_at = ?
-     WHERE id = ? AND account_id = ? AND machine_id = ?`).run(input.currentHead, input.lastTurnId, basisEvent.id, basisEvent.message_id, nextOrder.time, nextOrder.seq, input.encryptedMetadata ? JSON.stringify(input.encryptedMetadata) : null, ts, input.sessionId, input.accountId, input.machineId);
+     WHERE id = ? AND account_id = ? AND machine_id = ?`).run(input.status && sessionRow.status === "running" ? input.status : null, shouldAdvance ? input.currentHead : null, shouldAdvance ? input.lastTurnId : null, shouldAdvance ? basisEvent.id : null, shouldAdvance ? basisEvent.message_id : null, shouldAdvance ? nextOrder.time : null, shouldAdvance ? nextOrder.seq : null, input.encryptedMetadata ? JSON.stringify(input.encryptedMetadata) : null, ts, input.sessionId, input.accountId, input.machineId);
     const session = db.prepare("SELECT * FROM sessions WHERE id = ?").get(input.sessionId);
     return { status: "applied", session };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cydm/happy-elves",
-  "version": "0.1.0-beta.40",
+  "version": "0.1.0-beta.42",
   "description": "Remote controller for local coding agents with hosted or self-hosted relay support.",
   "type": "module",
   "bin": {

package/packages/client/dist/client.js

@@ -165,6 +165,7 @@ export class ControllerClient {
         const checkedSessionId = requireNonEmpty(sessionId, "sessionId");
         const currentHead = requireNonEmpty(input.currentHead, "currentHead");
         const lastTurnId = requireNonEmpty(input.lastTurnId, "lastTurnId");
+        const status = input.status;
         const turnId = requireNonEmpty(input.basis.turnId, "basis.turnId");
         const eventMessageId = requireNonEmpty(input.basis.eventMessageId, "basis.eventMessageId");
         return await authenticatedJson(this.config, `/api/sessions/${encodeURIComponent(checkedSessionId)}/head`, {
@@ -173,6 +174,7 @@ export class ControllerClient {
             body: JSON.stringify({
                 currentHead,
                 lastTurnId,
+                ...(status ? { status } : {}),
                 basis: {
                     turnId,
                     eventMessageId,

package/packages/client/dist/parsers.js

@@ -183,6 +183,7 @@ export function parseRepairSessionHeadResult(value) {
     const reason = record.reason;
     return {
         advanced: readBooleanField(record, "advanced", "Session head repair"),
+        ...(typeof record.settled === "boolean" ? { settled: record.settled } : {}),
         session: session,
         basis: {
             eventId: readNumberField(basis, "eventId", "Session head repair basis"),

package/packages/client/dist/types.d.ts

@@ -205,6 +205,7 @@ export type CollectInput = {
 export type RepairSessionHeadInput = {
     currentHead: string;
     lastTurnId: string;
+    status?: "completed" | "cancelled" | "failed";
     basis: {
         turnId: string;
         eventMessageId: string;
@@ -214,6 +215,7 @@ export type RepairSessionHeadInput = {
 };
 export type RepairSessionHeadResult = {
     advanced: boolean;
+    settled?: boolean;
     session: SessionSnapshot;
     basis: {
         eventId: number;

package/packages/shared/dist/protocol.d.ts

@@ -144,6 +144,7 @@ export type MachineClientMessage = {
     currentHead: string;
     lastTurnId: string;
     basis: SessionHeadAdvanceBasis;
+    status?: "completed" | "cancelled" | "failed";
     encryptedMetadata?: EncryptedEnvelope;
 } | {
     type: "machine:turnDone";

package/packages/shared/dist/protocol.js

@@ -169,6 +169,7 @@ const machineMessageSchema = z.discriminatedUnion("type", [
         messageId: z.string().min(1).optional(),
         currentHead: z.string().min(1),
         lastTurnId: z.string().min(1),
+        status: z.enum(["completed", "cancelled", "failed"]).optional(),
         basis: z.object({
             turnId: z.string().min(1),
             eventMessageId: z.string().min(1),