A session groups your accepted sync packages for later review. Start one around a feature, an art pass, or an agent task. Your teammate keeps receiving changes while you work; ending a session is a review boundary, not a publish or merge step.
cor session start "Movement behind a flag"
# Keep cor work running. Edit and save normally.
cor session end
These commands work alongside a running worker. If the worker is stopped, the
command performs the transition and its required exchanges itself; run
cor work afterward for continuous sync. Each workspace has
one open session. Different people can have different sessions open at the
same time.
Current assigns authors from authenticated SSH key fingerprints. No author option is needed. Each person uses their own authorized key; only that key can publish into or close its session. Teammates can read its history. Hooks receive the same verified identity.
Wait for start to complete before beginning your feature. Existing unpublished
edits join the new session; an already submitted package retains its original
attribution. Stopping or restarting cor work does not end a
session. Finish your saves before ending it: edits after its final capture
belong to subsequent work.
cor session # local state; works offline
cor session list # sessions from the whole team
cor session show # this workspace's most recent session
cor session show SESSION_ID --json
cor session show SESSION_ID --output ../movement-review
show lists additions, modifications, and deletions per accepted
package. An export contains review.jsonl plus a directory for
each package sequence, with its changed files under before/ and
after/. Open a pair in your editor's comparison tool, or give the
export to a reviewing agent. Binary models and textures retain their exact
bytes; deleted files remain available on the before side.
Each JSONL record includes a package ID, server acceptance time in Unix milliseconds, sequence, and exact before/after manifests. The first line describes the session. An export takes a fixed view of the package count when it starts, even if the session is still open.
Corotation records individual package deltas rather than subtracting two whole-project snapshots. If Alice changes a file, Bob updates it, and Alice changes it again, Alice's review has two separate steps with the actual base for each. Bob's intervening package belongs to Bob's session. Rejected packages do not appear as shared changes.
Review manifests survive automatic baseline compaction and server restarts. They reference existing chunks, so opening or closing a session never copies the project or rehashes all its assets. Exports download the referenced content on demand and require a new output folder. A failed export leaves its partial output for inspection. Historical manifests and chunks remain retained; garbage collection is not implemented.
list returns up to 100 sessions, newest first; pass its
next_before as --before. show returns a
bounded package page; pass next_after as --after.
--output exports the complete session without manual pagination.
Keep exports outside the project or under its private
.laplace/ directory. The CLI rejects other destinations inside
the workspace so exported history cannot feed back into automatic sync.
Hooks run on the originating workspace, with that project as their working directory. Install an argv command for each event:
cor session hooks add feature-flag --on start -- python3 /path/to/prepare-feature.py
cor session hooks add review --on end -- python3 /path/to/review-session.py
cor session hooks
cor session hooks remove review
Use your own foreground script or agent runner. Arguments are passed directly,
without implicit shell interpolation. To use shell syntax, invoke a shell
explicitly. Hooks are native trusted programs: they can modify the working
tree and use your machine's tools, environment, and network. They are not
sandboxed. Corotation removes LAPLACE_TOKEN from their environment.
Hook configuration lives only in .laplace/session-hooks.json; a
synchronized project cannot install hooks on another teammate's machine. The
hook list and arguments are pinned at session start. Adding or removing hooks
affects the next session. Project scripts referenced by a hook remain trusted
executable code and should be reviewed as such.
Hooks run sequentially in installation order. Each has a 300-second default
timeout, configurable with --timeout-seconds from 1 to 3600.
Output is bounded and retained in local session status. Commands must stay in
the foreground; child processes are stopped when their hook finishes or times
out.
The LAPLACE_SESSION_CONTEXT environment variable points to a JSON
file. It contains format, event (start
or end), invocation_id, the session's
id, title, author and
client_id under session, repository,
root, server session metadata under remote, and
review. For end hooks, review points to a JSONL file
containing the packages accepted before those hooks run; it is null at start.
import json
import os
from pathlib import Path
context = json.loads(Path(os.environ["LAPLACE_SESSION_CONTEXT"]).read_text())
session_id = context["session"]["id"]
if context["event"] == "start":
# Ask your agent to prepare a disabled feature flag for this task.
# Return success only when the preparation is complete.
pass
else:
review = Path(context["review"])
# Give these exact package changes to your reviewing agent.
# Keep deployment or flag activation a separate, explicit decision.
pass
LAPLACE_SESSION_ID, LAPLACE_SESSION_EVENT, and
LAPLACE_HOOK_INVOCATION_ID are also available directly. The
invocation ID stays the same across explicit retries. Use it as an idempotency
key when creating an external flag or posting a review.
An end hook can run
cor session show SESSION_ID --output NEW_FOLDER to obtain the
changed bytes. It should not run work, sync, or
another session transition: the parent worker already owns the workspace and
waits for the hook. Write intended file changes directly and return; Corotation
captures and validates them.
Lifecycle hooks briefly occupy the worker; normal exchanges resume when they finish. A failing validation, unresolved conflict, or publication hold prevents closure. Starting and ending a session does not bypass required checks.
A session does not isolate behavior in a running game or deploy code. A start hook can scaffold a disabled flag and instruct an agent to use it for subsequent changes. Your application and deployment process must actually honor that flag. End hooks should review the work without automatically enabling it unless that is the workflow you deliberately install.
cor session --json
# Repair the hook script/environment, failed checks, or conflicts.
cor session retryFailed start hooks keep new changes local. Failed end hooks leave the session open. Successful hooks are not repeated on retry; the failing hook and remaining hooks continue. The pinned arguments stay unchanged, so repair the referenced script or environment before retrying.
If a process stops after a hook begins but before its result is recorded, Corotation cannot know whether an external action completed. It marks the hook interrupted and requires an explicit retry instead of silently repeating it. Make external effects idempotent using the invocation ID.
Session intents and progress are saved before network operations or hook
execution. If the CLI is interrupted, the queued transition remains;
cor work resumes it. An uncertain network retry cannot create
a second session, repeat an accepted package in its history, or reopen a
closed session. A closed session refuses new packages.
cor status --json includes session state. A session
transition exits with code 2 when it needs repair. Review
commands and local status work while the worker runs; conflict resolution
still follows the
existing stop, repair, resolve, restart workflow.