@cydm/happy-elves 0.1.0-beta.506 → 0.1.0-beta.507

package/README.md

@@ -6,8 +6,8 @@ Public beta CLI for Happy Elves.
 
 Run once in the existing user account; it detects %USERPROFILE%\.happy-elves\hosted, keeps the current daemon and sessions running, installs the independent updater, and registers per-user startup.
 
-    npm.cmd install --prefix $HOME\.happy-elves\management-entry --ignore-scripts --no-audit --no-fund --package-lock=false @cydm/happy-elves@0.1.0-beta.506
-    npm.cmd exec --yes --package @cydm/happy-elves@0.1.0-beta.506 -- happy-elves-updater install --state-root $HOME\.happy-elves\hosted --autostart
+    npm.cmd install --prefix $HOME\.happy-elves\management-entry --ignore-scripts --no-audit --no-fund --package-lock=false @cydm/happy-elves@0.1.0-beta.507
+    npm.cmd exec --yes --package @cydm/happy-elves@0.1.0-beta.507 -- happy-elves-updater install --state-root $HOME\.happy-elves\hosted --autostart
 
 The same updater entrypoint works on macOS after selecting a permanent user prefix.
 

package/apps/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cydm/happy-elves-cli",
-  "version": "0.1.0-beta.506",
+  "version": "0.1.0-beta.507",
   "private": true,
   "type": "module"
 }

package/apps/daemon/dist/orchestration/handler.js

@@ -607,13 +607,23 @@ async function followUpQueueRecord(config, record) {
         }
         catch { /* encrypted content is optional in projection */ }
     }
+    // Once the owner has delivered the prompt, prefer the runtime's canonical
+    // turn identity.  The command turn is a durable admission alias used while
+    // the prompt is being sent; provider history may materialize the same turn
+    // under a different (canonical) id after a restart.  Returning that binding
+    // lets a reloaded Web client reconcile the historical user item without
+    // injecting a second placeholder.  Queued records still expose their
+    // reserved command turn, when one exists.
+    const turnId = record.dispatch === "delivered"
+        ? record.runtimeTurnId ?? record.turnId
+        : record.turnId;
     return {
         id: record.followUpId ?? record.taskId,
         requestId: record.requestId,
         sessionId: record.consumerSessionId,
         machineId: record.crewMachineId ?? config.machineId,
         status: record.followUpStatus ?? (record.dispatch === "delivered" ? "delivered" : record.dispatch === "failed" ? "failed" : "queued"),
-        ...(record.turnId ? { turnId: record.turnId } : {}),
+        ...(turnId ? { turnId } : {}),
         ...(text !== undefined ? { text } : {}),
         createdAt: record.createdAt,
         ...(record.dispatch === "delivered" ? { deliveredAt: record.updatedAt } : {}),

package/apps/daemon/package.json

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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cydm/happy-elves",
-  "version": "0.1.0-beta.506",
+  "version": "0.1.0-beta.507",
   "description": "Remote controller for local coding agents with hosted or self-hosted relay support.",
-  "buildId": "80a6a4f86152f7e235be3216093c3c6b",
+  "buildId": "65825729e3f9e3e9a3d5a0e46b99bc22",
   "type": "module",
   "bin": {
     "happy-elves": "./apps/cli/dist/index.js",

package/packages/agent-sdk/dist/index.d.ts

@@ -2,7 +2,8 @@ import { type HeadlessRuntimeProvider, type HeadlessRuntimeServeOptions } from "
 export type HeadlessProviderServeOptions = Omit<HeadlessRuntimeServeOptions, "provider" | "core">;
 export declare function serveHeadlessProvider(provider: HeadlessRuntimeProvider | (() => HeadlessRuntimeProvider | Promise<HeadlessRuntimeProvider>), options?: HeadlessProviderServeOptions): Promise<void>;
 export declare function assertHeadlessProviderConformance(provider: HeadlessRuntimeProvider): Promise<void>;
-export type { HeadlessRuntimeProvider, HeadlessRuntimeProviderContext, HeadlessRuntimeProviderTurnInput, } from "../../headless-runtime/dist/index.js";
+export type { HeadlessRuntimeProvider, HeadlessRuntimeProviderContext, HeadlessRuntimeProviderNativeHistory, HeadlessRuntimeProviderNativeRead, HeadlessRuntimeProviderTurnInput, } from "../../headless-runtime/dist/index.js";
 export { addProviderTurnBinding, providerTurnBinding, rewindProviderTurnMetadata, type ProviderTurnBinding, } from "../../headless-runtime/dist/index.js";
-export type { AgentControlParams, AgentNode, CommandExecParams, CommandExecResult, CommandExecution, CommandResizeParams, CommandTerminateParams, CommandWriteParams, ForkThreadParams, ForkThreadResult, HeadlessClientRequest, HeadlessJsonId, HeadlessNotification, HeadlessRuntimeCapabilities, HeadlessRuntimeError, HeadlessRuntimeProtocol, HeadlessServerRequest, HeadlessServerResponse, HeadlessWireMessage, HostToolDescriptor, InitializeParams, InitializeResult, InterruptTurnParams, ListAgentsParams, ListAgentsResult, ListModelsParams, ListModelsResult, ListThreadItemsParams, ListThreadItemsResult, ListThreadsParams, ListThreadsResult, ModelDescriptor, ListThreadTurnsParams, ListThreadTurnsResult, ReadThreadParams, ReadThreadResult, RespondServerRequestParams, RuntimeEvent, RuntimeTraceRecord, SendAgentMessageParams, ServerRequest, SpawnAgentParams, SpawnAgentResult, StartThreadParams, StartThreadResult, StartTurnParams, StartTurnResult, SteerTurnParams, Thread, ThreadItem, ThreadStatus, ThinkingLevelDescriptor, Turn, TurnError, TurnStatus, UserInput, WaitAgentParams, WaitAgentResult, WaitTurnParams, WaitTurnResult, } from "../../runtime/dist/headless.js";
+export { nativeHistoryVersionForHistory, nativeHistoryVersionForTurnIds, } from "../../headless-runtime/dist/index.js";
+export type { AgentControlParams, AgentNode, CommandExecParams, CommandExecResult, CommandExecution, CommandResizeParams, CommandTerminateParams, CommandWriteParams, ForkThreadParams, ForkThreadResult, HeadlessClientRequest, HeadlessJsonId, HeadlessNotification, HeadlessRuntimeCapabilities, HeadlessRuntimeError, HeadlessRuntimeProtocol, HeadlessServerRequest, HeadlessServerResponse, HeadlessWireMessage, HostToolDescriptor, InitializeParams, InitializeResult, InterruptTurnParams, ListAgentsParams, ListAgentsResult, ListModelsParams, ListModelsResult, ListNativeSessionsParams, ListNativeSessionsResult, NativeSessionSummary, ListThreadItemsParams, ListThreadItemsResult, ListThreadsParams, ListThreadsResult, ModelDescriptor, ListThreadTurnsParams, ListThreadTurnsResult, ReadThreadParams, ReadThreadResult, RespondServerRequestParams, RuntimeEvent, RuntimeTraceRecord, SendAgentMessageParams, ServerRequest, SpawnAgentParams, SpawnAgentResult, StartThreadParams, StartThreadResult, StartTurnParams, StartTurnResult, SteerTurnParams, Thread, ThreadItem, ThreadStatus, ThinkingLevelDescriptor, Turn, TurnError, TurnStatus, UserInput, WaitAgentParams, WaitAgentResult, WaitTurnParams, WaitTurnResult, } from "../../runtime/dist/headless.js";
 //# sourceMappingURL=index.d.ts.map

package/packages/agent-sdk/dist/index.js

@@ -10,4 +10,5 @@ export async function assertHeadlessProviderConformance(provider) {
         throw new Error("provider must implement runTurn");
 }
 export { addProviderTurnBinding, providerTurnBinding, rewindProviderTurnMetadata, } from "../../headless-runtime/dist/index.js";
+export { nativeHistoryVersionForHistory, nativeHistoryVersionForTurnIds, } from "../../headless-runtime/dist/index.js";
 //# sourceMappingURL=index.js.map

package/packages/headless-runtime/dist/client.d.ts

@@ -1,3 +1,4 @@
+import type { HeadlessRuntimeProviderNativeRead } from "./core.js";
 import { type ForkThreadParams, type ForkThreadResult, type CancelSidechatParams, type CancelSidechatResult, type HeadlessRuntimeError, type HeadlessServerRequest, type InitializeResult, type InterruptTurnParams, type ListModelsParams, type ListModelsResult, type CommandExecParams, type CommandExecResult, type CommandResizeParams, type CommandTerminateParams, type CommandWriteParams, type ListThreadEventsParams, type ListThreadEventsResult, type ListThreadItemsParams, type ListThreadItemsResult, type ListThreadTurnsParams, type ListThreadTurnsResult, type AgentControlParams, type AdoptThreadParams, type ListNativeSessionsParams, type ListNativeSessionsResult, type ListAgentsParams, type ListAgentsResult, type ListThreadsParams, type ListThreadsResult, type ReadThreadParams, type ReadThreadResult, type RewindThreadParams, type RewindThreadResult, type RunSidechatParams, type RunSidechatResult, type ResumeThreadParams, type RespondServerRequestParams, type ServerRequestResult, type RuntimeEvent, type SendAgentMessageParams, type SpawnAgentParams, type SpawnAgentResult, type StartThreadParams, type StartThreadResult, type SyncNativeHistoryParams, type SyncNativeHistoryResult, type StartTurnParams, type StartTurnResult, type SteerTurnParams, type ThreadItem, type WaitAgentParams, type WaitAgentResult, type WaitTurnParams, type WaitTurnResult } from "../../runtime/dist/headless.js";
 export type HeadlessRuntimeClientOptions = {
     socketPath?: string;
@@ -15,6 +16,10 @@ export type HeadlessRuntimeClient = {
     startThread(params?: StartThreadParams): Promise<StartThreadResult>;
     adoptThread(params: AdoptThreadParams): Promise<StartThreadResult>;
     syncNativeHistory(params: SyncNativeHistoryParams): Promise<SyncNativeHistoryResult>;
+    readNativeHistory(params: {
+        threadId: string;
+        timeoutMs?: number;
+    }): Promise<HeadlessRuntimeProviderNativeRead>;
     resumeThread(params: ResumeThreadParams): Promise<StartThreadResult>;
     forkThread(params: ForkThreadParams): Promise<ForkThreadResult>;
     rewindThread(params: RewindThreadParams): Promise<RewindThreadResult>;

package/packages/headless-runtime/dist/client.js

@@ -51,6 +51,7 @@ class HeadlessRuntimeClientProcess {
             startThread: (params = {}) => this.request("thread/start", params),
             adoptThread: (params) => this.request("thread/adopt", params),
             syncNativeHistory: (params) => this.request("thread/native-sync", params),
+            readNativeHistory: (params) => this.request("thread/native-read", { threadId: params.threadId }, params.timeoutMs),
             resumeThread: (params) => this.request("thread/resume", params),
             forkThread: (params) => this.request("thread/fork", params),
             rewindThread: (params) => this.request("thread/rewind", params),

package/packages/headless-runtime/dist/core.d.ts

@@ -210,6 +210,13 @@ export declare class HeadlessRuntimeCore {
         threadId: string;
         nativeIdentity?: string;
     }): Promise<SyncNativeHistoryResult>;
+    /**
+     * Read provider-native history without mutating the HE projection. This is
+     * intentionally separate from native-sync so provider-command adapters can
+     * preserve the native history boundary while keeping the local runtime
+     * projection authoritative.
+     */
+    readNativeHistory(threadId: string): Promise<HeadlessRuntimeProviderNativeRead>;
     private syncNativeHistoryDurable;
     resumeThread(params: ResumeThreadParams): Promise<StartThreadResult>;
     forkThread(params: ForkThreadParams): Promise<ForkThreadResult>;

package/packages/headless-runtime/dist/core.js

@@ -681,6 +681,19 @@ export class HeadlessRuntimeCore {
                 this.activeNativeHistorySyncs.delete(params.threadId);
         }
     }
+    /**
+     * Read provider-native history without mutating the HE projection. This is
+     * intentionally separate from native-sync so provider-command adapters can
+     * preserve the native history boundary while keeping the local runtime
+     * projection authoritative.
+     */
+    async readNativeHistory(threadId) {
+        const thread = this.requireThread(threadId);
+        if (!thread.providerSessionId || !this.provider.readNativeHistory) {
+            throw new HeadlessRuntimeCoreError("CAPABILITY_UNSUPPORTED", `Provider ${this.provider.id} does not support read-only native history refresh.`);
+        }
+        return await this.provider.readNativeHistory({ thread, timeoutMs: this.nativeHistoryReadTimeoutMs });
+    }
     async syncNativeHistoryDurable(params, isActive = () => true) {
         const thread = this.requireThread(params.threadId);
         if (!thread.providerSessionId || !this.provider.readNativeHistory) {

package/packages/headless-runtime/dist/index.js

@@ -193,6 +193,8 @@ async function dispatch(core, request) {
                 threadId: requiredString(params.threadId, "threadId", request.method),
                 ...(typeof params.nativeIdentity === "string" && params.nativeIdentity.trim() ? { nativeIdentity: params.nativeIdentity.trim() } : {}),
             });
+        case "thread/native-read":
+            return await core.readNativeHistory(requiredString(params.threadId, "threadId", request.method));
         case "thread/resume":
             return await core.resumeThread({
                 ...requiredThreadId(params, request.method),

package/packages/headless-runtime/dist/provider-command.js

@@ -38,6 +38,78 @@ class ProviderCommandHeadlessRuntimeProvider {
             throw error;
         }
     }
+    async listNativeSessions(input = {}) {
+        const client = await this.ensureClient();
+        try {
+            const result = await client.listNativeSessions(input);
+            return { ...result, provider: this.id };
+        }
+        catch (error) {
+            const code = errorCode(error);
+            if (code === "CAPABILITY_UNSUPPORTED" || code === "METHOD_NOT_FOUND") {
+                throw new HeadlessRuntimeCoreError("CAPABILITY_UNSUPPORTED", `Remote provider ${this.id} does not support native session discovery`);
+            }
+            throw error;
+        }
+    }
+    async adoptThread(input) {
+        const client = await this.ensureClient();
+        const nativeSessionId = input.thread.providerSessionId;
+        if (!nativeSessionId)
+            throw new HeadlessRuntimeCoreError("INVALID_REQUEST", "Provider command adoption requires a native provider session id.");
+        try {
+            // Keep the HE thread id stable across the command boundary. The remote
+            // runtime binds that explicit id to the provider-native session; it must
+            // not start a fresh remote thread and lose the native history.
+            const result = await client.adoptThread({
+                threadId: input.thread.id,
+                providerSessionId: nativeSessionId,
+                cwd: input.thread.cwd,
+                name: input.thread.name,
+                model: input.thread.model,
+                modelProvider: input.thread.modelProvider,
+                thinkingLevel: input.thread.thinkingLevel,
+                provider: this.id,
+                sessionContext: input.thread.sessionContext ?? null,
+                ...(input.manualHandoff ? { manualHandoff: true } : {}),
+                ...(input.managedHandoff ? { managedHandoff: true } : {}),
+                ...(input.manualHandoffProof ? { manualHandoffProof: input.manualHandoffProof } : {}),
+            });
+            const native = await client.readNativeHistory({ threadId: result.thread.id });
+            const binding = providerCommandBindingFromThread(result.thread, {
+                remoteProviderSessionId: nativeSessionId,
+            });
+            this.remoteThreadsByThread.set(input.thread.id, binding.providerSessionId);
+            return {
+                ...binding,
+                ...(result.thread.providerMetadata?.nativeHistoryVersion ? { providerMetadata: { ...binding.providerMetadata, nativeHistoryVersion: result.thread.providerMetadata.nativeHistoryVersion } } : {}),
+                history: native.history,
+            };
+        }
+        catch (error) {
+            const code = errorCode(error);
+            if (code === "CAPABILITY_UNSUPPORTED" || code === "METHOD_NOT_FOUND") {
+                throw new HeadlessRuntimeCoreError("CAPABILITY_UNSUPPORTED", `Remote provider ${this.id} does not support native session adoption`);
+            }
+            throw error;
+        }
+    }
+    async readNativeHistory(input) {
+        const client = await this.ensureClient();
+        const remoteThreadId = remoteRuntimeThreadId(input.thread);
+        if (!remoteThreadId)
+            throw new HeadlessRuntimeCoreError("INVALID_REQUEST", "Provider command native history refresh requires a remote runtime thread id.");
+        try {
+            return await client.readNativeHistory({ threadId: remoteThreadId, timeoutMs: input.timeoutMs });
+        }
+        catch (error) {
+            const code = errorCode(error);
+            if (code === "CAPABILITY_UNSUPPORTED" || code === "METHOD_NOT_FOUND") {
+                throw new HeadlessRuntimeCoreError("CAPABILITY_UNSUPPORTED", `Remote provider ${this.id} does not support native history refresh`);
+            }
+            throw error;
+        }
+    }
     async startThread(input) {
         const client = await this.ensureClient();
         const result = await client.startThread({
@@ -407,6 +479,10 @@ function providerCommandBindingFromThread(thread, extraMetadata = {}, existingMe
         ...(Object.keys(metadata).length > 0 ? { providerMetadata: metadata } : {}),
     };
 }
+function remoteRuntimeThreadId(thread) {
+    const metadata = recordFrom(thread.providerMetadata);
+    return stringField(metadata, "remoteRuntimeThreadId") ?? (thread.providerSessionId || undefined);
+}
 function compactRecord(record) {
     return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined));
 }

package/packages/pie-provider/dist/index.js

@@ -3,10 +3,10 @@ import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import { tmpdir } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import readline from "node:readline";
-import { serveHeadlessProvider, addProviderTurnBinding, providerTurnBinding, rewindProviderTurnMetadata, } from "../../agent-sdk/dist/index.js";
+import { serveHeadlessProvider, addProviderTurnBinding, providerTurnBinding, rewindProviderTurnMetadata, nativeHistoryVersionForHistory, } from "../../agent-sdk/dist/index.js";
 const providerId = "pie";
 const happyElvesToolDescription = "Official Happy Elves orchestration gateway. Use when the user asks to inspect, continue, fork, rewind, wait for, or delegate work to HE sessions, machines, daemons, agents, or remote controllers. First call `skill` or `help` unless the needed command is already known from this turn. Do not guess shell commands. Do not start, stop, or reconfigure HE daemons/relays/controllers unless the user explicitly asks for HE administration.";
 const happyElvesComputerUseToolDescription = "Official Happy Elves computer-use gateway for a trusted HE machine/session. Use for remote screen/browser/input/file-preview operations. First call `manual` or `snapshot` to understand the available surface. Do not use it for normal code edits when provider-native file/shell tools are sufficient.";
@@ -33,6 +33,90 @@ const provider = {
     async listModels() {
         return await listPieModels();
     },
+    async listNativeSessions(input = {}) {
+        await assertPieAvailable();
+        const limit = Math.max(1, Math.min(200, Math.floor(input.limit ?? 50)));
+        const cwd = input.cwd ? canonicalPath(input.cwd) : undefined;
+        const listed = await runPieJson([
+            "sessions",
+            "list",
+            "--json",
+            "--limit",
+            String(limit),
+            ...(input.cursor ? ["--cursor", input.cursor] : []),
+            ...(cwd ? ["--cwd", cwd] : []),
+        ]);
+        const sessions = (Array.isArray(listed.sessions) ? listed.sessions : [])
+            .map((value) => pieNativeSessionSummary(value, cwd))
+            .filter((value) => value !== undefined);
+        return {
+            provider: providerId,
+            sessions,
+            ...(typeof listed.nextCursor === "string" && listed.nextCursor.length > 0 ? { nextCursor: listed.nextCursor } : {}),
+            history: "available",
+        };
+    },
+    async adoptThread(input) {
+        const providerSessionId = input.thread.providerSessionId;
+        if (!providerSessionId)
+            throw new PieProviderError("INVALID_REQUEST", "Pie native adoption requires a provider session id", true);
+        const native = await readPieNativeHistory(providerSessionId, input.thread.cwd);
+        if (native.takeoverState === "active") {
+            throw new PieProviderError("NATIVE_SESSION_ACTIVE", `Pie native session ${providerSessionId} is active and cannot be adopted`, true);
+        }
+        if (native.takeoverState === "unknown" && input.manualHandoff !== true && input.managedHandoff !== true) {
+            throw new PieProviderError("CAPABILITY_UNSUPPORTED", `Pie native session ${providerSessionId} has no verifiable idle/takeover state`, true);
+        }
+        if (input.manualHandoffProof?.updatedAt !== undefined && native.updatedAt !== undefined && native.updatedAt > input.manualHandoffProof.updatedAt) {
+            throw new PieProviderError("NATIVE_HANDOFF_RECONFIRM_REQUIRED", `Pie native session ${providerSessionId} changed after the handoff confirmation`, true);
+        }
+        const historyVersion = nativeHistoryVersionForHistory(native.history);
+        if (input.manualHandoffProof?.historyVersion && input.manualHandoffProof.historyVersion !== historyVersion) {
+            throw new PieProviderError("NATIVE_HANDOFF_RECONFIRM_REQUIRED", `Pie native session ${providerSessionId} history changed after the handoff confirmation`, true);
+        }
+        return {
+            providerSessionId,
+            history: native.history,
+            providerMetadata: {
+                authority: "pie-file-session-store",
+                pieSessionId: providerSessionId,
+                pieSessionInitialized: true,
+                nativeHistoryTurnIds: native.history.turns.map((turn) => turn.id),
+                nativeHistoryVersion: historyVersion,
+            },
+        };
+    },
+    async readNativeHistory(input) {
+        const providerSessionId = input.thread.providerSessionId;
+        if (!providerSessionId)
+            throw new PieProviderError("INVALID_REQUEST", "Pie native history refresh requires a provider session id", true);
+        return await readPieNativeHistory(providerSessionId, input.thread.cwd, input.timeoutMs);
+    },
+    async validateNativeHandoff(input) {
+        const providerSessionId = input.thread.providerSessionId;
+        if (!providerSessionId)
+            throw new PieProviderError("INVALID_REQUEST", "Pie native handoff validation requires a provider session id", true);
+        const expectedIdentity = stringValue(recordFrom(input.thread.providerMetadata).nativeIdentity);
+        if (!expectedIdentity || input.proof?.identity !== expectedIdentity) {
+            throw new PieProviderError("NATIVE_HANDOFF_RECONFIRM_REQUIRED", "Pie native handoff proof does not match the provider session identity", true);
+        }
+        const native = await readPieNativeHistory(providerSessionId, input.thread.cwd);
+        if (native.takeoverState === "active")
+            throw new PieProviderError("NATIVE_HANDOFF_RECONFIRM_REQUIRED", `Pie native session ${providerSessionId} is still active`, true);
+        const historyVersion = nativeHistoryVersionForHistory(native.history);
+        if (!input.proof?.historyVersion || input.proof.historyVersion !== historyVersion) {
+            throw new PieProviderError("NATIVE_HANDOFF_RECONFIRM_REQUIRED", `Pie native session ${providerSessionId} changed after the handoff confirmation`, true);
+        }
+        return {
+            providerSessionId,
+            providerMetadata: {
+                ...recordFrom(input.thread.providerMetadata),
+                nativeHistoryTurnIds: native.history.turns.map((turn) => turn.id),
+                nativeHistoryVersion: historyVersion,
+                nativeHistoryChangedExternally: undefined,
+            },
+        };
+    },
     async startThread(input) {
         return pieThreadBinding(input, false);
     },
@@ -508,8 +592,117 @@ async function listPieModels() {
         warnings: [...warnings, ...fromConfig.warnings],
     };
 }
-async function runPieJson(args) {
-    const output = await runPieText(args);
+async function readPieNativeHistory(providerSessionId, requestedCwd, timeoutMs) {
+    await assertPieAvailable();
+    const pages = [];
+    let before;
+    let session = {};
+    let pageCount = 0;
+    do {
+        if (++pageCount > 256)
+            throw new PieProviderError("PIE_HISTORY_TOO_LARGE", `Pie native session ${providerSessionId} history exceeded the supported page limit`, true);
+        const response = await runPieJson([
+            "sessions",
+            "read",
+            providerSessionId,
+            "--json",
+            "--raw",
+            "--limit",
+            "200",
+            ...(before ? ["--before", before] : []),
+        ], timeoutMs);
+        if (isRecord(response.session))
+            session = response.session;
+        pages.unshift(Array.isArray(response.events) ? response.events : []);
+        before = typeof response.nextBefore === "string" && response.nextBefore.length > 0 && response.hasMoreBefore === true
+            ? response.nextBefore
+            : undefined;
+    } while (before);
+    const rowCwd = stringValue(session.cwd);
+    if (rowCwd && canonicalPath(rowCwd) !== canonicalPath(requestedCwd)) {
+        throw new PieProviderError("INVALID_REQUEST", `Pie native session ${providerSessionId} belongs to ${rowCwd}, not ${requestedCwd}`, true);
+    }
+    const events = pages.flat();
+    const history = pieNativeHistory(providerSessionId, events);
+    return {
+        history,
+        takeoverState: pieTakeoverState(session),
+        ...(epochMs(session.updatedAt ?? session.updated_at) !== undefined ? { updatedAt: epochMs(session.updatedAt ?? session.updated_at) } : {}),
+    };
+}
+function pieNativeHistory(providerSessionId, events) {
+    const turns = [];
+    let current;
+    let currentNativeTurnId;
+    let itemIndex = 0;
+    for (const raw of events) {
+        const event = recordFrom(raw);
+        const message = recordFrom(event.message);
+        const roleValue = stringValue(event.role) ?? stringValue(message.role);
+        const kind = roleValue === "user" ? "user" : roleValue === "assistant" ? "assistant" : undefined;
+        if (!kind)
+            continue;
+        const text = pieEventText(event, message);
+        if (!text)
+            continue;
+        const itemId = stringValue(event.entryId) ?? stringValue(event.id) ?? `pie-native:${providerSessionId}:item:${itemIndex}`;
+        const nativeTurnId = stringValue(event.turnId);
+        if (!current || (nativeTurnId ? currentNativeTurnId !== nativeTurnId : kind === "user" && current.items.length > 0)) {
+            if (current)
+                turns.push(current);
+            const startedAt = epochMs(event.timestamp ?? event.occurredAt);
+            current = {
+                id: nativeTurnId ? `pie-native:${providerSessionId}:turn:${nativeTurnId}` : `pie-native:${providerSessionId}:turn:${itemId}`,
+                status: "completed",
+                ...(startedAt !== undefined ? { startedAt, completedAt: startedAt } : {}),
+                items: [],
+            };
+            currentNativeTurnId = nativeTurnId ?? undefined;
+        }
+        const createdAt = epochMs(event.timestamp ?? event.occurredAt);
+        current.items.push({ id: itemId, kind, text, ...(createdAt !== undefined ? { createdAt } : {}) });
+        current.providerCheckpointId = itemId;
+        if (createdAt !== undefined)
+            current.completedAt = Math.max(current.completedAt ?? createdAt, createdAt);
+        const status = stringValue(event.status);
+        if (status === "failed")
+            current.status = "failed";
+        else if (status === "cancelled" || status === "interrupted")
+            current.status = "interrupted";
+        else if (status === "completed")
+            current.status = "completed";
+        itemIndex += 1;
+    }
+    if (current)
+        turns.push(current);
+    return { turns };
+}
+function pieEventText(event, message) {
+    const direct = stringValue(event.content);
+    if (direct)
+        return direct;
+    const content = event.content ?? message.content ?? event.message;
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content.map((part) => {
+        if (typeof part === "string")
+            return part;
+        const record = recordFrom(part);
+        return stringValue(record.text) ?? stringValue(record.content) ?? "";
+    }).filter(Boolean).join("\n");
+}
+function pieTakeoverState(session) {
+    const status = stringValue(session.status)?.toLowerCase();
+    if (status && ["active", "busy", "running", "waiting"].includes(status))
+        return "active";
+    if (status && ["idle", "completed", "closed", "archived"].includes(status))
+        return "idle";
+    return "unknown";
+}
+async function runPieJson(args, timeoutMs) {
+    const output = await runPieText(args, timeoutMs);
     const trimmed = output.trim();
     if (!trimmed.startsWith("{"))
         throw new PieProviderError("PIE_INVALID_JSON", `pie ${args.join(" ")} returned non-JSON output`, true);
@@ -520,7 +713,7 @@ async function runPieJson(args) {
     }
     return parsed;
 }
-function runPieText(args) {
+function runPieText(args, timeoutMs) {
     const child = spawnPie(args, {
         env: providerEnv(),
         stdio: ["ignore", "pipe", "pipe"],
@@ -536,8 +729,17 @@ function runPieText(args) {
         stderrRing = `${stderrRing}${String(chunk)}`.slice(-stderrRingChars);
     });
     return new Promise((resolve, reject) => {
+        const timer = timeoutMs !== undefined && Number.isFinite(timeoutMs) && timeoutMs > 0
+            ? setTimeout(() => {
+                child.kill("SIGTERM");
+                reject(new PieProviderError("PIE_HISTORY_TIMEOUT", `Pie command timed out after ${Math.floor(timeoutMs)}ms`, true));
+            }, Math.floor(timeoutMs))
+            : undefined;
+        timer?.unref?.();
         child.once("error", (error) => reject(new PieProviderError("PIE_SPAWN_FAILED", `Pie command could not be started: ${normalizeError(error).message}`, true)));
         child.once("close", (code) => {
+            if (timer)
+                clearTimeout(timer);
             const text = `${stdout}\n${stderr}`.trim();
             if (code === 0)
                 resolve(text);
@@ -554,6 +756,60 @@ function parsePieJson(stdout) {
         throw new PieProviderError("PIE_INVALID_JSON", `Pie command returned invalid JSON: ${normalizeError(error).message}`, true);
     }
 }
+function pieNativeSessionSummary(value, requestedCwd) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const row = value;
+    const providerSessionId = stringValue(row.id) ?? stringValue(row.sessionId);
+    if (!providerSessionId)
+        return undefined;
+    const rowCwd = stringValue(row.cwd) ?? requestedCwd ?? process.cwd();
+    const canonicalCwd = canonicalPath(rowCwd);
+    if (requestedCwd && canonicalCwd !== canonicalPath(requestedCwd))
+        return undefined;
+    const updatedAt = epochMs(row.updatedAt ?? row.updated_at ?? row.lastModified ?? row.createdAt ?? row.created_at);
+    if (updatedAt === undefined)
+        return undefined;
+    const createdAt = epochMs(row.createdAt ?? row.created_at);
+    const name = stringValue(row.name) ?? stringValue(row.title);
+    const summary = stringValue(row.summary) ?? name;
+    return {
+        provider: providerId,
+        providerSessionId,
+        cwd: canonicalCwd,
+        updatedAt,
+        ...(createdAt !== undefined ? { createdAt } : {}),
+        ...(row.archived === true ? { archived: true } : {}),
+        ...(name ? { name } : {}),
+        ...(summary ? { summary } : {}),
+        history: "available",
+    };
+}
+// macOS commonly exposes /var as a symlink to /private/var. Native session
+// records are reported with the provider's canonical cwd, while HE may carry
+// the user's spelling. Compare identities rather than raw path strings so
+// native discovery/adoption works across those equivalent cwd aliases.
+function canonicalPath(value) {
+    const resolved = path.resolve(value);
+    try {
+        return realpathSync.native(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+function epochMs(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value < 10_000_000_000 ? value * 1000 : value;
+    if (typeof value === "string" && value.trim()) {
+        const numeric = Number(value);
+        if (Number.isFinite(numeric))
+            return epochMs(numeric);
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
 function providerEnv(extra = {}) {
     return {
         ...process.env,