Skip to content
Wayglass

Session fork

A session is an intent’s code plus its context: goal, reason, declared and changed paths, decisions and approvals so far, overlaps, the intent’s audit history, and handoff notes from the agent that is stopping. Sharing a session freezes that context on the Worker; forking it continues the work somewhere else as a new intent.

Share

Section titled “Share”

From the checkout that holds the intent, after pushing:

Terminal window
wayglass push -m "wip: limiter works, lockout pending"
wayglass session share --note "Limiter works; lockout tests still missing"

share records an append-only snapshot on the Worker, including the fork head the Worker reads from Artifacts, and prints a URL:

https://wayglass.example.com/v1/projects/acme-web/sessions/s3f9c0a12b4

HEAD must already be on the fork, or share fails with not_pushed. Uncommitted changes are not part of the session; share warns about them.

Handoff notes can come from several --note flags (joined by blank lines), from a file, or from standard input, up to 32 KiB:

Terminal window
wayglass session share --notes-file HANDOFF.md --json
git log -3 --format=%B | wayglass session share --notes-file -

--intent shares an intent other than the checkout’s current one.

Fork

Section titled “Fork”

On another machine, logged in to the same Worker:

Terminal window
wayglass session fork https://wayglass.example.com/v1/projects/acme-web/sessions/s3f9c0a12b4 --dir login-work
cd login-work
wayglass session show

fork asks the Worker to fork the session’s fork into a new intent owned by you, with the same goal, reason and declared paths and the original intent recorded as its parent. Then it clones the new fork into --dir (default <project>-<session id>) with a write token scoped to the new fork only. The original fork’s token is never handed out, and the original fork is not touched.

In the new checkout, fork also:

  • fetches refs/notes/wayglass from the fork, so why works for everything that landed before,
  • records the trunk commit the original intent started from as the diff base, so push reports the whole change, not only what is new here,
  • makes the new intent current, and writes the context to .wayglass/state/session.md and .wayglass/state/session.json (git-ignored; the Worker keeps the authoritative copy).

If the source agent pushed again after sharing, you get its latest head; fork warns and reports moved: true with both commits.

The CLI sends your key only to the Worker you are logged in to. A session URL on another Worker fails with wrong_worker until you log in there.

Continue

Section titled “Continue”

wayglass session show prints the context as Markdown: the goal and reason, paths, handoff notes, decisions so far, overlaps at the time of the share, the code (shared head, your checkout, your fork, diff base) and next steps. An agent starting in this checkout should read it first.

From there the loop is the usual one: commit with Wayglass-Intent: <new id>, wayglass push, wayglass propose. Policy decides the new intent on its own. The parent intent is separate and may still land by itself; the overlap between the two is labelled relation: "parent" or "child" in JSON and left out of the human warnings.

wayglass session show <url> reads a shared session from the Worker without forking it.