@cydm/happy-elves 0.1.0-beta.74 → 0.1.0-beta.75

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

@@ -1,6 +1,6 @@
 import { type ControllerClient, type ControllerSnapshot } from "../../../../../packages/client/dist/index.js";
 import type { MachineSnapshot } from "../../../../../packages/shared/dist/index.js";
-import { localDaemonStatus, readLocalDaemonPidIdentity, type SpawnedDaemonHandle } from "./local-daemon.js";
+import { inspectLocalDaemonRuntime, localDaemonStatus, readLocalDaemonPidIdentity, stopLocalDaemon, stopSpawnedDaemon, type SpawnedDaemonHandle } from "./local-daemon.js";
 import type { DaemonConfig } from "./types.js";
 export declare function startFailureMayUseCommittedConfig(error: unknown): boolean;
 export declare function ensureDaemonRunning(expectedConfig: DaemonConfig, cwd?: string): Promise<{
@@ -12,6 +12,27 @@ export declare function ensureDaemonRunning(expectedConfig: DaemonConfig, cwd?:
     committedConfigMayBeInUse?: boolean;
     autostartNeedsAttention?: string;
 }>;
+type BootstrapDaemonRestartOptions = {
+    readStatus?: typeof localDaemonStatus;
+    inspectRuntime?: typeof inspectLocalDaemonRuntime;
+    readIdentity?: typeof readLocalDaemonPidIdentity;
+    stopLocal?: typeof stopLocalDaemon;
+    stopStarted?: typeof stopSpawnedDaemon;
+    ensureRunning?: typeof ensureDaemonRunning;
+    assertConfigFence?: (expectedConfig: DaemonConfig) => Promise<void>;
+};
+/**
+ * `happy-elves start` is an explicit foreground recovery/entry command. When
+ * it finds a verified local Daemon, restart that exact owner so the process
+ * always loads the currently installed package before the browser opens.
+ *
+ * The lower-level `ensureDaemonRunning()` deliberately remains idempotent for
+ * `happy-elves daemon start`, enrollment rollback, and service recovery.
+ */
+export declare function restartDaemonForBootstrap(expectedConfig: DaemonConfig, cwd?: string, options?: BootstrapDaemonRestartOptions): Promise<Awaited<ReturnType<typeof ensureDaemonRunning>> & {
+    restarted: boolean;
+    previousInstanceGeneration?: string;
+}>;
 export type DaemonReadinessResult = {
     phase: "relay-authenticated" | "process-exited" | "owner-changed" | "relay-pending";
     local: Awaited<ReturnType<typeof localDaemonStatus>>;

package/apps/cli/dist/commands/lib/bootstrap-daemon.js

@@ -3,7 +3,7 @@ import { daemonRuntimeConfigFingerprint } from "../../../../../packages/shared/d
 import { CliError } from "../../errors.js";
 import { startDaemonTimeoutMs } from "./paths.js";
 import { readDaemonConfig } from "./config.js";
-import { assertLocalDaemonRuntimeMatchesConfig, assertLocalDaemonVerified, inspectLocalDaemonRuntime, ensureRunningDaemonAutostart, localDaemonStatus, readLocalDaemonPidIdentity, spawnDaemonStartTracked, stopSpawnedDaemon, } from "./local-daemon.js";
+import { assertLocalDaemonRuntimeMatchesConfig, assertLocalDaemonVerified, inspectLocalDaemonRuntime, ensureRunningDaemonAutostart, localDaemonStatus, readLocalDaemonPidIdentity, spawnDaemonStartTracked, stopLocalDaemon, stopSpawnedDaemon, } from "./local-daemon.js";
 const committedConfigMayBeInUseErrors = new WeakSet();
 export function startFailureMayUseCommittedConfig(error) {
     return Boolean(error && typeof error === "object" && committedConfigMayBeInUseErrors.has(error));
@@ -183,6 +183,78 @@ export async function ensureDaemonRunning(expectedConfig, cwd = process.cwd()) {
         throw error;
     }
 }
+/**
+ * `happy-elves start` is an explicit foreground recovery/entry command. When
+ * it finds a verified local Daemon, restart that exact owner so the process
+ * always loads the currently installed package before the browser opens.
+ *
+ * The lower-level `ensureDaemonRunning()` deliberately remains idempotent for
+ * `happy-elves daemon start`, enrollment rollback, and service recovery.
+ */
+export async function restartDaemonForBootstrap(expectedConfig, cwd = process.cwd(), options = {}) {
+    const readStatus = options.readStatus ?? localDaemonStatus;
+    const inspectRuntime = options.inspectRuntime ?? inspectLocalDaemonRuntime;
+    const readIdentity = options.readIdentity ?? readLocalDaemonPidIdentity;
+    const stopLocal = options.stopLocal ?? stopLocalDaemon;
+    const stopStarted = options.stopStarted ?? stopSpawnedDaemon;
+    const ensureRunning = options.ensureRunning ?? ensureDaemonRunning;
+    const assertConfigFence = options.assertConfigFence ?? assertDaemonConfigFence;
+    await assertConfigFence(expectedConfig);
+    const current = await readStatus();
+    assertLocalDaemonVerified(current);
+    if (!current.running) {
+        return {
+            ...await ensureRunning(expectedConfig, cwd),
+            restarted: false,
+        };
+    }
+    const owner = await readIdentity();
+    if (!owner.record || owner.record.pid !== current.pid) {
+        throw new CliError("The verified Daemon owner identity changed before restart; no process was signalled.", "DAEMON_PID_INVALID");
+    }
+    const runtime = await inspectRuntime(expectedConfig);
+    if (runtime.state !== "match" && runtime.state !== "missing") {
+        const code = runtime.state === "invalid"
+            ? "DAEMON_RUNTIME_IDENTITY_INVALID"
+            : runtime.state === "owner-mismatch"
+                ? "DAEMON_RUNTIME_IDENTITY_MISMATCH"
+                : "DAEMON_RUNTIME_CONFIG_MISMATCH";
+        throw new CliError("The running Daemon identity could not be matched to daemon.json, so happy-elves start did not restart or signal it.", code);
+    }
+    if (runtime.state === "match" &&
+        (runtime.identity.pid !== owner.record.pid ||
+            runtime.identity.instanceNonce !== owner.record.instanceNonce ||
+            runtime.identity.startedAt !== owner.record.startedAt)) {
+        throw new CliError("The Daemon runtime owner changed while restart was being verified; no process was signalled.", "DAEMON_RUNTIME_IDENTITY_MISMATCH");
+    }
+    const previousInstanceGeneration = owner.record.instanceNonce;
+    await assertConfigFence(expectedConfig);
+    const stopped = await stopLocal(startDaemonTimeoutMs, {
+        pid: owner.record.pid,
+        instanceNonce: owner.record.instanceNonce,
+        startedAt: owner.record.startedAt,
+    });
+    if (stopped.running || stopped.alive) {
+        throw new CliError("Daemon did not stop before the restart deadline; no replacement process was started.", "DAEMON_STOP_FAILED");
+    }
+    const started = await ensureRunning(expectedConfig, cwd);
+    if (started.instanceGeneration === previousInstanceGeneration) {
+        if (started.startedHandle) {
+            try {
+                await stopStarted(started.startedHandle);
+            }
+            catch (error) {
+                throw new CliError(`Daemon restart returned a stale generation and its replacement cleanup failed: ${error instanceof Error ? error.message : String(error)}`, "DAEMON_START_CLEANUP_FAILED");
+            }
+        }
+        throw new CliError("Daemon restart did not publish a fresh process generation.", "DAEMON_RESTART_GENERATION_MISMATCH");
+    }
+    return {
+        ...started,
+        restarted: true,
+        previousInstanceGeneration,
+    };
+}
 function committedConfigInUseError(message) {
     return markCommittedConfigMayBeInUse(new CliError(message, "DAEMON_START_CONFLICT"));
 }

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

@@ -2,7 +2,7 @@ import { ControllerClient } from "../../../../../packages/client/dist/index.js";
 import { type DeviceRecoveryIntentV1 } from "../../../../../packages/shared/dist/index.js";
 import { stopSpawnedDaemon } from "./local-daemon.js";
 import { type StartConfigPreflight } from "./bootstrap-config.js";
-import { ensureDaemonRunning } from "./bootstrap-daemon.js";
+import { type ensureDaemonRunning } from "./bootstrap-daemon.js";
 export declare function startDeviceRecoveryBootstrap(params: {
     flags: Record<string, string | boolean>;
     preflight: StartConfigPreflight;
@@ -12,12 +12,15 @@ export declare function startDeviceRecoveryBootstrap(params: {
 }): Promise<void>;
 export declare function deviceRecoveryIntentNeedsReplacement(intent: Pick<DeviceRecoveryIntentV1, "status">): boolean;
 export declare function isTerminalRecoveryIntentCreationFailure(error: unknown): boolean;
-export declare function projectRecoveredDaemonReadinessFailure(started: Awaited<ReturnType<typeof ensureDaemonRunning>>, machineName: string, readinessError: unknown, options?: {
+export declare function projectRecoveredDaemonReadinessFailure(started: Awaited<ReturnType<typeof ensureDaemonRunning>> & {
+    restarted?: boolean;
+}, machineName: string, readinessError: unknown, options?: {
     stopStarted?: typeof stopSpawnedDaemon;
 }): Promise<{
     online: false;
     pid?: number;
     started: boolean;
+    restarted: boolean;
     name: string;
     needsAttention: string;
 }>;

package/apps/cli/dist/commands/lib/bootstrap-device-recovery.js

@@ -7,10 +7,10 @@ import { accountFingerprintV1, deviceRecoveryTtlMsV1, randomId, } from "../../..
 import { daemonRuntimeConfigFingerprint } from "../../../../../packages/shared/dist/node/daemon-process.js";
 import { CliError } from "../../errors.js";
 import { ok } from "./json.js";
-import { assertLocalDaemonVerified, ensureRunningDaemonAutostart, inspectLocalDaemonRuntime, localDaemonStatus, stopSpawnedDaemon, } from "./local-daemon.js";
+import { assertLocalDaemonVerified, localDaemonStatus, stopSpawnedDaemon, } from "./local-daemon.js";
 import { withAccountConfigTransaction } from "./config.js";
 import { controllerBaseUrl } from "./bootstrap-config.js";
-import { ensureDaemonRunning, readDaemonProjectionBaseline, waitForDaemonReadiness, } from "./bootstrap-daemon.js";
+import { readDaemonProjectionBaseline, restartDaemonForBootstrap, waitForDaemonReadiness, } from "./bootstrap-daemon.js";
 import { openUrl } from "./bootstrap-output.js";
 import { assertNoPendingDaemonEnrollmentForDeviceRecovery } from "./daemon-enrollment-intent.js";
 import { configDir, configPath, deviceRecoveryPendingPath, startDaemonTimeoutMs } from "./paths.js";
@@ -318,34 +318,10 @@ async function ensureRecoveredDaemonReady(params) {
             ...projection,
             ...(current.pid ? { pid: current.pid } : {}),
             started: false,
+            restarted: false,
             needsAttention: error instanceof Error ? error.message : "The local Daemon owner needs verification.",
         };
     }
-    if (current.running) {
-        const runtime = await inspectLocalDaemonRuntime(params.daemonConfig);
-        if (runtime.state !== "match") {
-            const projection = await readProjection();
-            const needsAttention = runtime.state === "missing"
-                ? "Automatic startup metadata will be repaired on the next controlled Daemon restart."
-                : "The running Daemon identity needs repair before Happy Elves can manage its process.";
-            return {
-                ...projection,
-                ...(current.pid ? { pid: current.pid } : {}),
-                started: false,
-                needsAttention,
-            };
-        }
-        const autostart = await ensureRunningDaemonAutostart();
-        const projection = await readProjection();
-        return {
-            ...projection,
-            ...(current.pid ? { pid: current.pid } : {}),
-            started: false,
-            ...(autostart.state === "needs-attention"
-                ? { needsAttention: autostart.message }
-                : {}),
-        };
-    }
     let baseline;
     try {
         baseline = await readDaemonProjectionBaseline(client, params.daemonConfig.machineId, {
@@ -357,37 +333,51 @@ async function ensureRecoveredDaemonReady(params) {
     }
     let started;
     try {
-        started = await ensureDaemonRunning(params.daemonConfig, params.cwd);
-    }
-    catch (error) {
-        const projection = await readProjection();
-        return {
-            ...projection,
-            ...(current.pid ? { pid: current.pid } : {}),
-            started: false,
-            needsAttention: error instanceof Error ? error.message : "The Daemon could not be started automatically.",
-        };
-    }
-    try {
-        const readiness = await waitForDaemonReadiness(client, params.daemonConfig.machineId, {
-            baseline,
-            expectedInstanceGeneration: started.instanceGeneration,
-            requireFreshProjection: started.started,
-            timeoutMs: startDaemonTimeoutMs,
+        const ready = await withAccountConfigTransaction(async (transaction) => {
+            const currentDaemonConfig = await transaction.readDaemon();
+            if (!currentDaemonConfig ||
+                daemonRuntimeConfigFingerprint(currentDaemonConfig) !== daemonRuntimeConfigFingerprint(params.daemonConfig)) {
+                throw new CliError("The local Daemon identity changed before restart. No process was signalled.", "CONFIG_CHANGED_DURING_START");
+            }
+            started = await restartDaemonForBootstrap(params.daemonConfig, params.cwd);
+            const readiness = await waitForDaemonReadiness(client, params.daemonConfig.machineId, {
+                baseline,
+                expectedInstanceGeneration: started.instanceGeneration,
+                requireFreshProjection: started.started || started.restarted,
+                timeoutMs: startDaemonTimeoutMs,
+            });
+            if (readiness.phase !== "relay-authenticated" || !readiness.machine?.online) {
+                throw new CliError("The Daemon did not authenticate before the startup deadline.", "DAEMON_ONLINE_TIMEOUT");
+            }
+            const confirmedDaemonConfig = await transaction.readDaemon();
+            if (!confirmedDaemonConfig ||
+                daemonRuntimeConfigFingerprint(confirmedDaemonConfig) !== daemonRuntimeConfigFingerprint(params.daemonConfig)) {
+                throw new CliError("The local Daemon identity changed during restart.", "CONFIG_CHANGED_DURING_START");
+            }
+            return { started, readiness };
         });
-        if (readiness.phase !== "relay-authenticated" || !readiness.machine?.online) {
-            throw new CliError("The Daemon did not authenticate before the startup deadline.", "DAEMON_ONLINE_TIMEOUT");
-        }
-        const pid = started.local.pid ?? started.startedPid;
+        const pid = ready.started.local.pid ?? ready.started.startedPid;
         return {
             online: true,
             ...(pid ? { pid } : {}),
-            started: started.started,
-            name: readiness.machine.name ?? params.daemonConfig.machineName,
+            started: ready.started.started,
+            restarted: ready.started.restarted,
+            name: ready.readiness.machine?.name ?? params.daemonConfig.machineName,
         };
     }
     catch (error) {
-        return await projectRecoveredDaemonReadinessFailure(started, params.daemonConfig.machineName, error);
+        if (started) {
+            return await projectRecoveredDaemonReadinessFailure(started, params.daemonConfig.machineName, error);
+        }
+        const settled = await localDaemonStatus().catch(() => current);
+        return {
+            online: false,
+            name: params.daemonConfig.machineName,
+            ...(settled.pid ? { pid: settled.pid } : {}),
+            started: false,
+            restarted: current.running && !settled.running,
+            needsAttention: error instanceof Error ? error.message : "The Daemon could not be restarted automatically.",
+        };
     }
 }
 export async function projectRecoveredDaemonReadinessFailure(started, machineName, readinessError, options = {}) {
@@ -408,6 +398,7 @@ export async function projectRecoveredDaemonReadinessFailure(started, machineNam
         online: false,
         ...(started.local.pid ?? started.startedPid ? { pid: started.local.pid ?? started.startedPid } : {}),
         started: daemonCleanupError ? started.started : false,
+        restarted: started.restarted === true,
         name: machineName,
         needsAttention,
     };

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

@@ -10,7 +10,7 @@ import { assertLocalDaemonRuntimeMatchesConfig, assertLocalDaemonVerified, inspe
 import { redactedRelayUrl, withAccountConfigTransaction, } from "./config.js";
 import { cliErrorFromFetch } from "./relay-http.js";
 import { controllerBaseUrl, ensureControllerConfig, ensureDaemonPaired, readStartConfigPreflight } from "./bootstrap-config.js";
-import { ensureDaemonRunning, readDaemonProjectionBaseline, startFailureMayUseCommittedConfig, waitForDaemonReadiness, } from "./bootstrap-daemon.js";
+import { readDaemonProjectionBaseline, restartDaemonForBootstrap, startFailureMayUseCommittedConfig, waitForDaemonReadiness, } from "./bootstrap-daemon.js";
 import { openUrl, writeHumanStartOutput } from "./bootstrap-output.js";
 import { startJoinBootstrap } from "./bootstrap-join.js";
 import { reconcileSatisfiedDeviceRecoveryPending, startDeviceRecoveryBootstrap } from "./bootstrap-device-recovery.js";
@@ -85,16 +85,15 @@ export async function startBootstrap(flags) {
         if (daemonBefore.running && preflight.kind !== "ready") {
             throw new CliError("A verified daemon is running, but the matching controller/daemon config pair is incomplete. No configuration or daemon process was changed. Run happy-elves doctor before recovering this workspace.", "CONFIG_SPLIT_BRAIN");
         }
-        // A running owner is accepted only when its signed runtime marker proves
-        // that it loaded the same daemon identity we just read under this lease.
-        // Ordinary `start` never restarts a healthy daemon because package files
-        // happen to have a newer mtime.
+        // Top-level `happy-elves start` deliberately restarts a verified owner so
+        // it always loads the currently installed package. A missing marker is the
+        // supported legacy-upgrade case: exact PID v2 ownership still fences the
+        // stop, and the replacement publishes a fresh marker. Invalid, mismatched,
+        // or unverified identities remain fail-closed and are never signalled.
         if (!daemonProcessNeedsAttention && daemonBefore.running && preflight.daemon) {
             const runtime = await inspectLocalDaemonRuntime(preflight.daemon);
-            if (runtime.state !== "match") {
-                daemonProcessNeedsAttention = runtime.state === "missing"
-                    ? "Automatic startup metadata will be repaired on the next controlled Daemon restart."
-                    : "The running Daemon identity needs repair before Happy Elves can manage its process.";
+            if (runtime.state !== "match" && runtime.state !== "missing") {
+                daemonProcessNeedsAttention = "The running Daemon identity needs repair before Happy Elves can manage its process.";
             }
         }
         const networkDeadline = Date.now() + startDaemonTimeoutMs;
@@ -187,19 +186,20 @@ export async function startBootstrap(flags) {
                         started: false,
                         startedPid: undefined,
                         committedConfigMayBeInUse: daemonBefore.running,
+                        restarted: false,
                     },
                     machine: baseline,
                     invite,
                     daemonProcessNeedsAttention,
                 };
             }
-            const daemon = await ensureDaemonRunning(daemonState.config, cwd);
+            const daemon = await restartDaemonForBootstrap(daemonState.config, cwd);
             startedHandle = daemon.startedHandle;
             committedConfigMayBeInUse = daemon.committedConfigMayBeInUse === true;
             const readiness = await waitForDaemonReadiness(client, daemonState.config.machineId, {
                 baseline,
                 expectedInstanceGeneration: daemon.instanceGeneration,
-                requireFreshProjection: daemon.started,
+                requireFreshProjection: daemon.started || daemon.restarted,
                 // Lifetime-lock acquisition/reclaim and relay-authenticated readiness
                 // are separate bounded phases.
                 timeoutMs: startDaemonTimeoutMs,
@@ -317,8 +317,9 @@ export async function startBootstrap(flags) {
             pid: daemon.local.pid ?? daemon.startedPid,
             pidPath: daemon.local.pidPath,
             started: daemon.started,
-            alreadyRunning: daemonBefore.running || daemon.committedConfigMayBeInUse === true,
-            restarted: false,
+            alreadyRunning: daemon.restarted !== true &&
+                (daemonBefore.running || daemon.committedConfigMayBeInUse === true),
+            restarted: daemon.restarted,
             ...(daemonNeedsAttention ? { needsAttention: daemonNeedsAttention } : {}),
         },
         ...(invite ? {

package/apps/daemon/dist/lifecycle/detached-helper-bundle.mjs

@@ -17833,6 +17833,7 @@ var capabilitiesSchema = external_exports.object({
   memoryCommandsV1: external_exports.boolean().optional(),
   memoryProjectsV1: external_exports.boolean().optional(),
   gatewayCommandsV1: external_exports.boolean().optional(),
+  sessionProviderRestoreV1: external_exports.boolean().optional(),
   filePreview: external_exports.boolean().optional(),
   scheduleAuthContextV1: external_exports.boolean().optional(),
   scheduleCreateSemanticDigestV1: external_exports.boolean().optional(),
@@ -17877,6 +17878,9 @@ var sessionSnapshotSchema = external_exports.object({
   }).optional(),
   sourceSessionId: external_exports.string().min(1).optional(),
   sourceCheckpointId: external_exports.string().min(1).optional(),
+  recovery: external_exports.object({
+    code: external_exports.literal("provider-archived")
+  }).optional(),
   historyModel: external_exports.enum(["append-only", "authoritative-linear"]).optional(),
   capabilities: sessionCapabilitiesSchema.optional()
 });
@@ -18198,6 +18202,11 @@ var controllerMessageSchema = external_exports.discriminatedUnion("type", [
     requestId: external_exports.string().min(1),
     sessionId: external_exports.string().min(1)
   }),
+  external_exports.object({
+    type: external_exports.literal("controller:restoreSession"),
+    requestId: external_exports.string().min(1),
+    sessionId: external_exports.string().min(1)
+  }),
   external_exports.object({
     type: external_exports.literal("controller:listHistoricalSessions"),
     requestId: external_exports.string().min(1),
@@ -18442,6 +18451,14 @@ var machineMessageSchema = external_exports.discriminatedUnion("type", [
     messageId: external_exports.string().min(1).optional(),
     encryptedMetadata: encryptedEnvelopeSchema.optional()
   }),
+  external_exports.object({
+    type: external_exports.literal("machine:sessionRestored"),
+    requestId: external_exports.string().min(1),
+    sessionId: external_exports.string().min(1),
+    name: external_exports.string().min(1).optional(),
+    messageId: external_exports.string().min(1).optional(),
+    encryptedMetadata: encryptedEnvelopeSchema.optional()
+  }),
   external_exports.object({
     type: external_exports.literal("machine:historicalSessions"),
     requestId: external_exports.string().min(1),
@@ -18669,6 +18686,12 @@ var machineCommandSchema = external_exports.discriminatedUnion("type", [
     sessionId: external_exports.string().min(1),
     encryptedMetadata: encryptedEnvelopeSchema.optional()
   }),
+  external_exports.object({
+    type: external_exports.literal("machine:restoreSession"),
+    requestId: external_exports.string().min(1),
+    sessionId: external_exports.string().min(1),
+    encryptedMetadata: encryptedEnvelopeSchema.optional()
+  }),
   external_exports.object({
     type: external_exports.literal("machine:listHistoricalSessions"),
     requestId: external_exports.string().min(1),
@@ -18791,6 +18814,7 @@ var _machineClientMessageTypeSchema = external_exports.enum([
   "machine:sessionHeadAdvanced",
   "machine:turnDone",
   "machine:sessionResumed",
+  "machine:sessionRestored",
   "machine:historicalSessions",
   "machine:directoryListed",
   "machine:filePreviewed",

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

@@ -5,7 +5,7 @@ import { tickLoops } from "../loop/runner.js";
 import { waitForRuntimeSessionRecovery } from "../runtime/session-recovery.js";
 import { handleListDirectory } from "../session/directory.js";
 import { handlePreviewFile } from "../session/file-preview.js";
-import { handleClose, handleCreateSession, handleImportHistoricalSession, handleListHistoricalSessions, handleResume } from "../session/lifecycle.js";
+import { handleClose, handleCreateSession, handleImportHistoricalSession, handleListHistoricalSessions, handleRestoreSession, handleResume } from "../session/lifecycle.js";
 import { handleScheduleAction, handleScheduleCreate, handleScheduleList } from "../loop/handlers.js";
 import { handleMemoryCommand } from "../memory/commands.js";
 import { handleMemoryProjectCommand } from "../memory/project-commands.js";
@@ -134,6 +134,10 @@ async function handleServerMessage(ws, config, message) {
         await handleResume(ws, config, message);
         return;
     }
+    if (message.type === "machine:restoreSession") {
+        await handleRestoreSession(ws, config, message);
+        return;
+    }
     if (message.type === "machine:close") {
         await handleClose(ws, config, message);
         return;

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

@@ -70,6 +70,7 @@ export async function registerMachine(ws, config, relayCapabilities) {
             daemonInstanceGeneration: instanceGeneration,
             ...(lifecycleRegistration ? { daemonLifecycleRegistrationV1: lifecycleRegistration } : {}),
             sessionPrimitives,
+            sessionProviderRestoreV1: typeof getRuntime(process.cwd()).restoreSession === "function",
             directoryBrowser: true,
             memory: config.memory?.enabled !== false,
             memoryTurnOptionsV1: true,

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

@@ -14,6 +14,7 @@ const criticalMessageTypes = new Set([
     "machine:sessionHeadAdvanced",
     "machine:turnDone",
     "machine:sessionResumed",
+    "machine:sessionRestored",
     "machine:sessionRewound",
     "machine:sessionForked",
     "machine:sessionRenamed",

package/apps/daemon/dist/runtime/external-provider.js

@@ -350,6 +350,13 @@ export function createExternalAgentRuntimeProvider(options) {
             }), "ensureSession result handle");
             return toRuntimeHandle(input.sessionKey, handle, input.cwd);
         },
+        async restoreSession(input) {
+            const client = requireClientForAgent(input.agent);
+            if (client || typeof options.fallback.restoreSession !== "function") {
+                throw Object.assign(new Error(`Provider ${input.agent} does not support restoring archived Sessions`), { code: "SESSION_RESTORE_UNSUPPORTED", retryable: false });
+            }
+            await options.fallback.restoreSession(input);
+        },
         async attachSession(input) {
             const client = requireClientForAgent(input.agent);
             if (!client) {

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

@@ -16,7 +16,9 @@ export type HistoricalBackfillResult = {
 export declare function handleCreateSession(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;
 export declare function handleImportHistoricalSession(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;
 export declare function handleListHistoricalSessions(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;
-export declare function resumeSession(ws: WebSocket, config: DaemonConfig, sessionId: string, requestId: string, fallback?: SessionFallback, announceSuccess?: boolean, operationAlreadyClaimed?: boolean): Promise<SessionState | null>;
+export declare function resumeSession(ws: WebSocket, config: DaemonConfig, sessionId: string, requestId: string, fallback?: SessionFallback, announceSuccess?: boolean, operationAlreadyClaimed?: boolean, failureCode?: string, forceProviderResumeSessionId?: string): Promise<SessionState | null>;
+export declare function refreshRuntimeSessionName(session: SessionState, metadata?: SessionMetadata): Promise<SessionState>;
+export declare function shouldReplaceLocalPlaceholderName(session: SessionState): boolean;
 export declare function usesAuthoritativeTranscript(session: SessionState): boolean;
 export declare function replaceAuthoritativeTranscript(ws: WebSocket, config: DaemonConfig, session: SessionState, runtimeSessionId?: string | undefined, input?: {
     currentHead?: string;
@@ -28,4 +30,5 @@ export declare function replaceAuthoritativeTranscript(ws: WebSocket, config: Da
     strict?: boolean;
 }): Promise<HistoricalBackfillResult>;
 export declare function handleResume(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;
+export declare function handleRestoreSession(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;
 export declare function handleClose(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;