Skip to content

Make handoff capsules work offline and across machines - #23

Merged
jbwinters merged 6 commits into
mainfrom
fix/handoff-offline-20261115
Nov 15, 2026
Merged

jbwinters merged 6 commits into
mainfrom
fix/handoff-offline-20261115

Conversation

@jbwinters

@jbwinters jbwinters commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

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

  • Export works with no network. Warm memory references and continuity judgment are optional; if they cannot be read, the capsule is built without them and the export prints a warning. --output <file> writes the capsule (mode 0600); an existing file is not replaced without --force.
  • Same-host handoff is allowed. A capsule may target the host it came from (Claude Code on a laptop to Claude Code in a sandbox). Without --target, export still addresses the other host.
  • An accepted import is saved for the next session. It is stored in hot memory for the project containing the current directory (or of --workspace-root). It is saved before the handoff is acknowledged, and saved: 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.
  • Imported text is not treated as the user's own. It uses its own operator command (handoff.import), not remember: 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.
  • The signer and age are checked. Import accepts a capsule signed by the profile's own key; any other key needs --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.
  • Claude Code can run the commands it is told about. The bridge answers memory_hot, memory_warm and memory_search (and hyphenated names). The capability line names crosshead memory hot|warm|search, with --profile for a non-default profile.
  • Smaller: help lists handoff import --file, --allow-stale and --force; import no longer needs a session id.

Things to know

  • Older clients reject a same-host capsule ("sourceRuntime and targetRuntime must differ"), so both machines need this version.
  • Codex↔Claude Code imports between profiles with different keys now need --allow-signer.
  • The hot-sync document format is unchanged: imports are recognised by a handoff- turn id prefix, which older clients already sync and treat as an ordinary finding.
  • Workspace ids are path-based, so the project needs the same path on both machines or an explicit --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:check and npm run check:boundary pass.
  • Built CLI in a throwaway home: --output refuses an existing file, --force replaces it as 0600, import from a project subdirectory lands on the project root, a re-import leaves one checkpoint per scope, a malformed --allow-signer is 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).

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
jbwinters force-pushed the fix/handoff-offline-20261115 branch from 24636df to 3325f29 Compare November 15, 2026 18:48
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.
@jbwinters
jbwinters merged commit 29b3ea7 into main Nov 15, 2026
8 checks passed
@jbwinters
jbwinters deleted the fix/handoff-offline-20261115 branch November 15, 2026 20:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant