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

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

@@ -217,6 +217,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;
@@ -372,6 +496,9 @@ export async function handleSession({ domain, action, positional, flags }) {
         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,9 +557,20 @@ 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,
                 basis: repair.basis,
@@ -452,7 +590,57 @@ 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") {

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.41",
   "private": true,
   "type": "module"
 }

package/package.json

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