From a88fd1cf3b174af0bd7bc47aede7af4f3e6ed475 Mon Sep 17 00:00:00 2001 From: Josh Winters Date: Mon, 16 Nov 2026 11:56:37 -0500 Subject: [PATCH 1/2] Carry the full latest finding in handoff files and start the daemon for handoff commands - Export put the hot summary through a 280-character cut, so a capsule lost the failing tests and next step that a same-machine session would get. It now carries the latest request and final response for the workspace (and any pending import or explicit save) up to 5,000 characters, without source excerpts. Import keeps up to 9,000 characters of the rendered handoff. - handoff export and import start the daemon the way hooks do, so a fresh machine can import right after setup and install. - crosshead memory hot prints saved checkpoint text, newest first, instead of field names with truncated ids. Co-Authored-By: Claude Opus 5.5 --- src/runtime/adapter-utils.ts | 39 ++++++++++ src/runtime/claude-code-adapter.ts | 4 +- src/runtime/cli/handoff.ts | 7 ++ src/runtime/codex-adapter.ts | 4 +- src/runtime/handoff-import.ts | 5 +- src/runtime/local-runtime.ts | 19 ++++- tests/runtime/handoff-cross-machine.test.ts | 86 ++++++++++++++++++++- 7 files changed, 156 insertions(+), 8 deletions(-) diff --git a/src/runtime/adapter-utils.ts b/src/runtime/adapter-utils.ts index 1e9829e..fd018cc 100644 --- a/src/runtime/adapter-utils.ts +++ b/src/runtime/adapter-utils.ts @@ -14,6 +14,9 @@ import { randomUUID } from "crypto"; import path from "path"; import type { OperatorWorkspaceManifest } from "./operator-policy"; +import { selectHotCheckpoints } from "./hot-continuity"; +import { IMPORTED_HANDOFF_TURN_PREFIX } from "./handoff-import"; +import { compactContinuitySummary } from "./summary-compaction"; // Shared helpers for the host runtime adapters (claude-code, codex, pi). These were // previously duplicated per adapter, which let bug fixes land in one runtime and not the @@ -56,6 +59,42 @@ export const summarizeHotMemory = (value: unknown): string | null => { return normalized.length <= 280 ? normalized : `${normalized.slice(0, 277).trimEnd()}...`; }; +// The handoff file's own budget is 16 KiB of canonical JSON, and an import saves +// at most IMPORTED_HANDOFF_LIMIT characters of the rendered handoff. This leaves +// room for the rest of the capsule in both. +export const HANDOFF_HOT_SUMMARY_LIMIT = 5000; + +/** + * What a handoff file carries from hot memory: the latest saved request and the + * agent's final response for this workspace (plus a pending import or explicit + * save), at full length up to the limit. Observed source excerpts stay behind; + * the file travels to other machines. Falls back to the one-line summary for + * hot memory that holds no checkpoints. + */ +export const summarizeHotMemoryForHandoff = ( + snapshot: Record | null, preferredRuntime: string, limit: number = HANDOFF_HOT_SUMMARY_LIMIT +): string | null => { + if (!snapshot) return null; + const entries = selectHotCheckpoints(snapshot, null); + if (entries.length === 0) return summarizeHotMemorySnapshot(snapshot, preferredRuntime); + const parts: string[] = []; + let remaining = limit; + for (const [index, entry] of entries.entries()) { + const label = entry.turnId?.startsWith(IMPORTED_HANDOFF_TURN_PREFIX) ? "Imported earlier" : entry.origin === "remember" ? "Explicitly saved" : "Latest work"; + const heading = `${label} (${entry.runtime}, ${entry.occurredAt}):`; + const available = Math.floor(remaining / (entries.length - index)) - heading.length - 40; + if (available < 200) break; + const goal = entry.goal ? entry.goal.slice(0, Math.floor(available * 0.3)) : ""; + const request = goal ? `\nRequest: ${goal}${goal.length < entry.goal.length || entry.goalTruncated ? " [request incomplete]" : ""}` : ""; + const findingBudget = available - request.length; + const finding = entry.summary.length <= findingBudget ? entry.summary : compactContinuitySummary(entry.summary, findingBudget); + const part = `${heading}${request}\nFinding: ${finding}`; + parts.push(part); + remaining -= part.length + 2; + } + return parts.length > 0 ? parts.join("\n\n") : summarizeHotMemorySnapshot(snapshot, preferredRuntime); +}; + export const summarizeHotMemorySnapshot = (snapshot: Record | null, preferredRuntime: string): string | null => { if (!snapshot) return null; const entries = (Array.isArray(snapshot.scopes) ? snapshot.scopes : [snapshot]) diff --git a/src/runtime/claude-code-adapter.ts b/src/runtime/claude-code-adapter.ts index 3089f28..b7efb41 100644 --- a/src/runtime/claude-code-adapter.ts +++ b/src/runtime/claude-code-adapter.ts @@ -42,7 +42,7 @@ import { parseArgs, sanitizeString, shellQuote, - summarizeHotMemorySnapshot, + summarizeHotMemoryForHandoff, summarizeJudgmentEntries, writeManagedFile, } from "./adapter-utils"; @@ -1053,7 +1053,7 @@ export class ClaudeCodeRuntimeAdapter extends HostRuntimeAdapterBase { nextAction: input.reasoning?.nextAction ?? null, }, memory: { - hotSummary: input.memory?.hotSummary ?? summarizeHotMemorySnapshot(hot, this.config.workspaceOnly ? "claude-code" : "shared"), + hotSummary: input.memory?.hotSummary ?? summarizeHotMemoryForHandoff(hot, this.config.workspaceOnly ? "claude-code" : "shared"), warmIds: input.memory?.warmIds ?? activeWarmIds, coldChunkIds: input.memory?.coldChunkIds ?? [], projectModelIds: input.memory?.projectModelIds ?? [], diff --git a/src/runtime/cli/handoff.ts b/src/runtime/cli/handoff.ts index 2e8a492..3fae9f2 100644 --- a/src/runtime/cli/handoff.ts +++ b/src/runtime/cli/handoff.ts @@ -7,6 +7,7 @@ import { HANDOFF_CAPSULE_DEFAULT_MAX_BYTES } from "../handoff-capsules"; import { workspaceProjectRoot } from "../workspace-identity"; import { resolveRuntimePaths } from "../runtime-persistence"; import { readWorkspaceHookPolicy, workspaceHookForInvocation } from "../workspace-hooks"; +import { ensureHookRuntime } from "../hook-runtime"; type HandoffHost = "codex" | "claude-code"; @@ -95,6 +96,12 @@ export const handoffFromCli = async (argv: string[]): Promise => { const profileName = typeof flags.profile === "string" ? flags.profile : undefined; const daemon = new OnlyBotsLocalRuntimeDaemon(typeof flags.home === "string" ? flags.home : undefined); + // Export and import read and write memory through the daemon. A fresh machine runs them right + // after setup, before any hook has started it, so start it here the same way hooks do. + if (subcommand === "export" || subcommand === "import") { + await ensureHookRuntime(resolveRuntimePaths(typeof flags.home === "string" ? flags.home : undefined).home); + } + if (subcommand === "export") { const sourceRuntime = typeof flags.source === "string" ? flags.source : "codex"; // Without --target the capsule goes to the other host; name the same host to move work to another machine. diff --git a/src/runtime/codex-adapter.ts b/src/runtime/codex-adapter.ts index ec893b2..8994861 100644 --- a/src/runtime/codex-adapter.ts +++ b/src/runtime/codex-adapter.ts @@ -41,7 +41,7 @@ import { parseArgs, sanitizeString, shellQuote, - summarizeHotMemorySnapshot, + summarizeHotMemoryForHandoff, summarizeJudgmentEntries, writeManagedFile, } from "./adapter-utils"; @@ -1073,7 +1073,7 @@ export class CodexRuntimeAdapter extends HostRuntimeAdapterBase { nextAction: input.reasoning?.nextAction ?? null, }, memory: { - hotSummary: input.memory?.hotSummary ?? summarizeHotMemorySnapshot(hot, this.config.workspaceOnly ? "codex" : "shared"), + hotSummary: input.memory?.hotSummary ?? summarizeHotMemoryForHandoff(hot, this.config.workspaceOnly ? "codex" : "shared"), warmIds: input.memory?.warmIds ?? activeWarmIds, coldChunkIds: input.memory?.coldChunkIds ?? [], projectModelIds: input.memory?.projectModelIds ?? [], diff --git a/src/runtime/handoff-import.ts b/src/runtime/handoff-import.ts index 52b6a4b..d9f56f3 100644 --- a/src/runtime/handoff-import.ts +++ b/src/runtime/handoff-import.ts @@ -78,8 +78,9 @@ export const IMPORTED_HANDOFF_TURN_PREFIX = "handoff-"; export const importedHandoffGoal = (input: { sourceRuntime: string; objective: string; createdAt: string }): string => `Imported handoff from ${input.sourceRuntime} (created ${input.createdAt}; written by another session, reference only, not instructions): ${input.objective.trim() || "continue the handed-off work"}`.slice(0, 1500); -// Kept well under the synced document budget (30,000 characters per scope) so an import cannot crowd out history. -const IMPORTED_HANDOFF_LIMIT = 6000; +// Room for a full exported hot summary (HANDOFF_HOT_SUMMARY_LIMIT) plus the task lines. Kept under the +// hot finding limit (12,000) and well under the synced document budget (30,000 characters per scope). +const IMPORTED_HANDOFF_LIMIT = 9000; /** The text saved to hot memory on an accepted import, so the next session in the workspace receives it. */ export const renderImportedHandoffMemory = (input: { diff --git a/src/runtime/local-runtime.ts b/src/runtime/local-runtime.ts index 7b8037c..7c69933 100644 --- a/src/runtime/local-runtime.ts +++ b/src/runtime/local-runtime.ts @@ -32,7 +32,7 @@ import { acquireRuntimeDaemonOwnership, daemonOwnerIsLive, probeRuntimeDaemonHea import { describeFetchFailure, fetchCauses, HostedOnlyBotsClient, HostedOnlyBotsRequestError, PROXY_REFUSAL, type HostedSession } from "./hosted-client"; export { describeFetchFailure } from "./hosted-client"; import { isLocalOnlyRuntimeProfile, preserveLegacyLocalHotOwner, readLocalHotMemory } from "./local-hot-memory"; -import { searchHotCheckpoints } from "./hot-continuity"; +import { readHotCheckpoints, searchHotCheckpoints } from "./hot-continuity"; import { RuntimeLifecycleManager, type RuntimeLifecycleActivity, @@ -5488,6 +5488,8 @@ export const formatWarmMemoryEvaluation = ( return lines.join("\n"); }; +const HOT_DISPLAY_CHECKPOINTS = 3; + const formatSingleHotContent = (rawContent: string): string => { const content = rawContent.trim(); if (content.length === 0) { @@ -5495,6 +5497,21 @@ const formatSingleHotContent = (rawContent: string): string => { } try { const parsed = JSON.parse(content) as Record; + // Hooks save checkpoints. Show their text, newest first: this is what an agent told to run + // `crosshead memory hot` needs, and a field summary would show only truncated ids. + const checkpoints = readHotCheckpoints(parsed?.continuityCheckpoints) + .sort((left, right) => (Date.parse(right.occurredAt) || 0) - (Date.parse(left.occurredAt) || 0)); + if (checkpoints.length > 0) { + const shown = checkpoints.slice(0, HOT_DISPLAY_CHECKPOINTS).map((entry) => [ + `${entry.origin === "remember" ? "Saved with remember" : "Checkpoint"} from ${entry.runtime} at ${entry.occurredAt}`, + entry.goal ? `Request: ${truncateForPresentation(entry.goal, 600)}` : null, + `Finding:\n${entry.summary}`, + ].filter((line): line is string => line !== null).join("\n")); + const more = checkpoints.length > shown.length + ? `\n\n${checkpoints.length - shown.length} older checkpoint(s) not shown; use crosshead memory search "" or --json.` + : ""; + return `${shown.join("\n\n")}${more}`; + } if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) { return Object.keys(parsed) .sort((left, right) => left.localeCompare(right)) diff --git a/tests/runtime/handoff-cross-machine.test.ts b/tests/runtime/handoff-cross-machine.test.ts index 7744f74..1b50935 100644 --- a/tests/runtime/handoff-cross-machine.test.ts +++ b/tests/runtime/handoff-cross-machine.test.ts @@ -1,3 +1,4 @@ +import { spawn } from "node:child_process"; import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; import os from "node:os"; import path from "node:path"; @@ -11,7 +12,7 @@ import { CodexRuntimeAdapter } from "../../src/runtime/codex-adapter"; import { HANDOFF_IMPORT_COMMAND, handoffAgeRejection, handoffSignerRejection, parseAllowedSigners } from "../../src/runtime/handoff-import"; import { buildWarmPromotionCandidates } from "../../src/runtime/warm-memory-promotion"; import { LocalRuntimeClient } from "../../src/runtime/local-client"; -import { OnlyBotsLocalRuntimeDaemon, setupRuntimeProfile } from "../../src/runtime/local-runtime"; +import { OnlyBotsLocalRuntimeDaemon, formatHotMemoryForDisplay, setupRuntimeProfile } from "../../src/runtime/local-runtime"; // Each "machine" is a separate runtime home with its own daemon. Profiles point at an address // nothing listens on, so every hosted request fails the way it does with no network. @@ -174,6 +175,89 @@ describe("handoff capsules between machines", () => { }); }); +// A real final response: what was done, the failed approach, then the failing tests and next step. +// The old export kept only its first 280 characters. +const longFinding = [ + "Copied all 41,208 ledger rows into ledger_v2 with the batched copy step; row counts match.", + "Tried computing checksums inside the copy transaction; rejected, it held locks for 40 seconds.", + "x".repeat(600), + "Failing tests: tests/ledger/checksum.test.ts > empty rows and > null memo.", + "Next step: skip rows whose memo is empty before hashing, then rerun npm test -- checksum.", +].join("\n"); + +const waitForHot = async (target: Machine, expected: string): Promise => { + for (let attempt = 0; attempt < 40; attempt++) { + if (JSON.stringify(await target.client.readHotMemory("default", "all")).includes(expected)) return; + await new Promise((resolve) => setTimeout(resolve, 250)); + } + throw new Error(`hot memory never contained ${expected}`); +}; + +describe("what a handoff carries", () => { + it("carries the whole latest finding, not its first 280 characters", async () => { + const key = identity(); + const laptop = await machine(key); + const sandbox = await machine(key); + await laptop.client.emitEvent({ + eventId: "work-turn", runtime: "claude-code", type: "turn.completed", workspaceId, sessionId: "laptop-session", turnId: "t1", + payload: { goal: "Finish the ledger migration", summary: longFinding }, + }); + await waitForHot(laptop, "Next step: skip rows"); + + const exported = await laptop.claude.createHandoff({ ...exportRequest, transcript: undefined, targetRuntime: "claude-code" }); + const hotSummary = exported.record.capsule.continuityIr.memoryReferences.hotMemory.summary ?? ""; + expect(hotSummary).toContain("Request: Finish the ledger migration"); + expect(hotSummary).toContain("Failing tests: tests/ledger/checksum.test.ts"); + expect(hotSummary).toContain("Next step: skip rows whose memo is empty"); + expect(exported.record.capsule.sizeBudget.withinBudget).toBe(true); + + const imported = await sandbox.claude.importHandoff({ capsule: exported.record.capsule, workspaceRoot: project, sessionId: "handoff-import" }); + expect(imported.savedToHotMemory).toBe(true); + const context = await laterSessionContext(sandbox, "claude-code", "Next step: skip rows whose memo is empty"); + expect(context).toContain("Failing tests: tests/ledger/checksum.test.ts"); + expect(context).toContain("Next step: skip rows whose memo is empty"); + + // The shell view an agent is pointed at shows the saved text, not field names and ids. + const shown = formatHotMemoryForDisplay(await laptop.client.readHotMemory("default", "all")); + expect(shown).toContain("Next step: skip rows whose memo is empty"); + expect(shown).not.toContain("[truncated]"); + }, 30_000); + + it("starts the daemon for an import on a fresh machine, as hooks do", async () => { + const key = identity(); + const laptop = await machine(key); + const capsuleFile = path.join(laptop.home, "capsule.json"); + writeFileSync(capsuleFile, JSON.stringify((await laptop.claude.createHandoff({ ...exportRequest, targetRuntime: "claude-code" })).record.capsule)); + // Set up but never started: the order a fresh sandbox uses. + const fresh = mkdtempSync(path.join(os.tmpdir(), "crosshead-handoff-fresh-")); + await setupRuntimeProfile({ home: fresh, profileName: "default", apiBase: "http://127.0.0.1:0", npub: key.npub, nsec: key.nsec, makeDefault: true }); + const hostHome = path.join(fresh, "host"); + mkdirSync(path.join(hostHome, "onlybots"), { recursive: true }); + writeFileSync(path.join(hostHome, "onlybots", "claude-code-adapter.json"), JSON.stringify({ + marker: "__onlybots_claude_code_adapter__", adapterName: "claude-code", adapterVersion: "0.3.0", runtimeHome: fresh, + hostHome, workspaceRoot: project, profileName: "default", claudeBinary: "claude", + installedAt: "2026-11-15T00:00:00.000Z", updatedAt: "2026-11-15T00:00:00.000Z", + })); + const env = { ...process.env, CROSSHEAD_HOME: fresh, CLAUDE_CONFIG_DIR: hostHome, CROSSHEAD_HOOK_AUTOSTART: "1" }; + for (const name of ["CROSSHEAD_PROFILE", "ONLYBOTS_PROFILE", "ONLYBOTS_HOME", "ONLYBOTS_RUNTIME_HOME"]) delete env[name]; + const cli = (...args: string[]) => new Promise<{ status: number | null; output: string }>((resolve, reject) => { + const child = spawn(process.execPath, [path.resolve(__dirname, "../../dist/runtime/cli.js"), ...args, "--home", fresh], { cwd: project, env }); + let output = ""; + child.stdout.on("data", (chunk) => { output += String(chunk); }); + child.stderr.on("data", (chunk) => { output += String(chunk); }); + child.on("error", reject); + child.on("close", (status) => resolve({ status, output })); + }); + cleanups.push(async () => { + await cli("stop"); + rmSync(fresh, { recursive: true, force: true }); + }); + const imported = await cli("handoff", "import", "--target", "claude-code", "--file", capsuleFile, "--workspace-root", project, "--claude-home", hostHome, "--json"); + expect(imported.status, imported.output).toBe(0); + expect(JSON.parse(imported.output)).toMatchObject({ accepted: true, savedToHotMemory: true }); + }, 30_000); +}); + describe("import safeguards", () => { it("refuses stale capsules unless the operator allows them, and saves into the absolute project path", async () => { const key = identity(); From aeaad3d1e8aa0e6aec9490d952d6aba3b7c4804a Mon Sep 17 00:00:00 2001 From: Josh Winters Date: Mon, 16 Nov 2026 12:13:04 -0500 Subject: [PATCH 2/2] Release v0.5.0 Co-Authored-By: Claude Opus 5.5 --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index cd59136..db0a5f8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@crosshead/runtime", - "version": "0.5.0-alpha.15", + "version": "0.5.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@crosshead/runtime", - "version": "0.5.0-alpha.15", + "version": "0.5.0", "license": "Apache-2.0", "dependencies": { "@noble/curves": "^1.9.7", diff --git a/package.json b/package.json index 55d5991..d45be3c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@crosshead/runtime", - "version": "0.5.0-alpha.15", + "version": "0.5.0", "description": "Crosshead local runtime: persistent memory for Claude Code, Codex, Pi, Hermes and OpenCode. CLI, daemon, host adapters and hooks.", "license": "Apache-2.0", "private": true,