Repository navigation
Make handoff capsules work offline and across machines - #23
Merged
Merged
Conversation
A reviewer building the client in a sandbox with no route to the hosted service found that the handoff file could not carry work to a second machine. This fixes the five problems behind that. - Export no longer needs the hosted service. Warm memory references and continuity judgment are optional enrichment; when they cannot be read the capsule is built without them and the export says so. `--output <file>` writes the capsule for transfer. - A capsule may target the same host it came from, so Claude Code on one machine can hand off to Claude Code on another. Without `--target`, export still addresses the other host. - An accepted import is saved to hot memory for the workspace, so the next session there starts with it. Before, import printed the state and stored nothing. - Import accepts only capsules signed by the profile's own key unless the operator passes `--allow-signer <npub>`. A valid signature from an unknown key used to be enough. A refused import now exits non-zero and prints why. - The Claude Code bridge answers memory_hot, memory_warm and memory_search (and the hyphenated names), which the injected context advertises but only the Codex bridge handled. The capability line also names the `crosshead memory` commands, which exist on every host. Help text now lists `handoff import --file`. Import defaults the workspace to the current directory and no longer requires a session id.
jbwinters
force-pushed
the
fix/handoff-offline-20261115
branch
from
November 15, 2026 18:48
24636df to
3325f29
Compare
An accepted import is saved with its own operator command instead of 'remember': it is shown as an imported handoff, never as the user's own save, is not promoted to warm memory, and does not displace the latest explicit save. It is saved before the handoff is acknowledged, and the result reports whether hot memory was actually written. Ids derived from the capsule make a repeated import a no-op. Import defaults to the project root of the current directory and resolves a relative --workspace-root. Capsules older than 30 days need --allow-stale. A malformed --allow-signer is an error. A refused capsule keeps its real verification details, marked invalid with the reason. --output refuses to replace an existing file without --force and always leaves it mode 0600. The shell memory hint names a non-default profile.
…eats Until a newer checkpoint exists in the workspace, the latest imported handoff is included even when the first prompt matches other memory better. It is identified by its turn id prefix, which every client already syncs, so the hot-sync document format is unchanged. Each import now uses a new event id, so an import made while memory mode wrote nothing still saves when retried; the stable, profile-scoped turn id makes the repeat replace the earlier entry.
…s save With hot sync on (hosted profiles), each import was a new synced record, so repeats piled up and pushed session history out of the bounded document. A capture now supersedes earlier synced records with the same import turn id. New test runs an offline hosted profile with hot sync on; it fails without the fix. Import output names the workspace it saved to and, when nothing was written, the actual reason (memory mode, pause or policy). An explicit --workspace-root maps to its project root like the default. The import pin applies only to imports dated within ten minutes ahead and seven days back, so a fast clock on another machine cannot pin one indefinitely.
…were not saved - A new import replaces any earlier import in the workspace, locally and in the synced document, whatever the capsule or session id. Imported text is capped at 6,000 characters so it cannot crowd out workspace history. - The pinned import is placed first, so a page or budget cut cannot push it out, and stays pinned until the workspace records three newer checkpoints (a turn finishing in the session that ran the import no longer ends it). - The 'reference only, not instructions' framing is also in the request line, which survives compaction. - An accepted capsule that could not be saved (memory mode, pause, policy) is refused, so the record and exit status no longer claim success. - --allow-stale skips only the age check, never a future or missing date. - --allow-signer and --output with no value are errors; --force narrows an existing file's permissions before writing the capsule.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
An outside reviewer built the client in a sandbox that could not reach the hosted service and tried to carry a task to a second machine with a handoff file. Five things stopped it. This fixes them, plus the issues a follow-up review found in the first version of this PR.
What changes
--output <file>writes the capsule (mode 0600); an existing file is not replaced without--force.--target, export still addresses the other host.--workspace-root). It is saved before the handoff is acknowledged, andsaved:names the workspace it was written to. If nothing could be written (memory mode, a continuity pause or policy), the import is refused with that reason and exits 1.handoff.import), notremember: shown as a finding headed "Imported handoff from …", never as "Explicitly saved memory", never promoted to warm memory or archived, and it does not displace the latest explicit save. It is placed first and always included until the workspace records three newer checkpoints (for at most seven days, ignoring imports dated more than ten minutes ahead), so a first prompt that matches other memory better still gets it. A workspace holds one imported handoff: a new import, or the same capsule again, replaces the earlier one locally and in the hot-sync document. Imported text is capped at 6,000 characters, and the request line also says it is reference only, not instructions.--allow-signer <npub>(a malformed value is an error). Capsules older than 30 days need--allow-stale(which never accepts a future or missing date). A refused import exits 1, and its JSON verification is marked invalid with the reason.memory_hot,memory_warmandmemory_search(and hyphenated names). The capability line namescrosshead memory hot|warm|search, with--profilefor a non-default profile.handoff import --file,--allow-staleand--force; import no longer needs a session id.Things to know
--allow-signer.handoff-turn id prefix, which older clients already sync and treat as an ordinary finding.--workspace-id. Older-style unscoped hooks key on the session's exact directory, so a session started in a subdirectory or through a symlink may not see an import saved at the project root; the output names the workspace used.Verification
npm test: 64 files, 563 tests pass.tests/runtime/handoff-cross-machine.test.ts(9) uses real in-process daemons in separate homes, including a workspace with competing memory and an explicit save.tests/runtime/handoff-import-hot-sync.test.ts(2) runs an offline hosted profile with hot sync on: repeated imports, a different session id and a second capsule all leave one synced import beside the workspace's own history, shown first; plus the pin's time and newer-work bounds. A manual-mode profile refuses the import.npm run plugins:checkandnpm run check:boundarypass.--outputrefuses an existing file,--forcereplaces it as 0600, import from a project subdirectory lands on the project root, a re-import leaves one checkpoint per scope, a malformed--allow-signeris rejected.Not tested: the paged session-start render with an import (the import is placed first), real Claude Code or Codex sessions, a hosted profile, hot sync carrying an imported handoff to a third machine, and CLI-level automated tests (the CLI paths were checked by hand).