Live lane coordination for pi sessions. Makes same-session, multi-terminal pi safe: multiple pi runtimes attach to one live lane, wait their turn, refresh the session file, and extend the lane instead of accidentally forking parallel sibling branches from a stale leaf.
pi install npm:pi-laneFor full lane correctness, also apply the companion pi core patch via pi-patches:
cd /path/to/pi-patches
bash apply.sh
bash test.shThe patch refreshes pi's agent transcript after input hooks so pi-lane can move a runtime to the current lane head before the model request is built — without injecting hidden context.
No command is required. Every persisted pi session gets a default lane named main. When two pi instances submit prompts against the same session at the same time, pi-lane serializes the turns and makes the second runtime attach to the path produced by the first runtime. Lane metadata is not injected into model context.
Lane commands inside pi:
/lane Show current lane
/lane new [name] Create and join a new live lane from the current point
/lane join [name] Join a lane (defaults to main)
/lane list List lanes and compact instance status
/lane instances Show connected instances for this session
/lane identity Show this runtime's session/lane identity
/lane self Alias for /lane identity
/lane debug Show the debug log path
The package also installs pil, a small CLI for lane/runtime introspection that companion tools can reuse:
pil self # this runtime's identity
pil instances # connected runtimes
pil lanes # lanes for this session
pil status # combined overview
pil <subcommand> --json # machine-readable outputFor child tools and companion CLIs, pi-lane exports active runtime identity into the pi process environment before turns run:
PI_LANE_INSTANCE_ID
PI_LANE_SESSION_ID
PI_LANE_SESSION_KEY
PI_LANE_SESSION_FILE
PI_LANE_CURRENT_LANE
PI_LANE_ROOT
Bash/tool subprocesses inherit these, so companion CLIs can discover the current pi runtime without duplicating identity logic.
- leaf — an actual persisted session entry.
- lane — an intended live path from a leaf, created before the next leaf exists.
- attach — join an existing lane so new turns extend that lane.
- pi's session JSONL DAG is the source of truth.
- Lane metadata is only a cursor for where a live lane intends to continue.
pi-lanemust never rewrite session history from lane metadata.- Lane heads move only on explicit lifecycle events: turn completion, tree navigation, session replacement/fork initialization, or an explicit lane command.
State lives under ~/.pi/lane/sessions/{sessionKey}/ by default:
lanes/{lane}.json lane head + headEpoch
lanes/{lane}.lock/owner.json active lease owner + leaseEpoch + expectedHeadEntryId
instances/{instanceId}.json connected runtime heartbeat/discovery
debug.jsonl lock/recovery/tree-navigation events
Set PI_LANE_ROOT to override the root (useful for tests). The lock is only for lane turn ownership; it prevents two runtimes from extending the same live lane at once. Instance heartbeat files are separate and durable.
Companion tools can import shared path/identity helpers instead of reimplementing pi-lane logic:
import {
stableSessionKey,
sanitizeLaneName,
laneRoot,
laneSessionDir,
laneInstancesDir,
} from "pi-lane/runtime";The core session-parallelism problem is covered by pi-mock tests:
test/session-parallelism.test.mjsproves the bug without pi-lane.test/pi-lane.test.mjsproves synced linear lane behaviour with pi-lane, including tree navigation, session replacement, reusable runtime helpers, inherited identity env vars for bash children, durable instance discovery, simple commands, stale-lock crash recovery, ownerless-lock acquisition race handling, real SIGKILL recovery, epoch-tracked lane heads, no public repair/reconcile mutation commands, corrupt instance/lane-file tolerance, session isolation, and explicit lane creation.
MIT