Session Rebind
Return a paused-but-alive interactive session to active after a relay restart or transient blip strands its platform metadata.
Coming soon. rensei session rebind is merged into rensei-tui's main branch and code-complete, but it has not shipped in a tagged release yet (the latest release as of this page is v0.14.27). This page documents the shipped behavior in advance; check rensei --version once a release carries it.
rensei session rebind <session-id> is the operator's manual fix for a session left stuck paused even though its harness never stopped. A relay restart (or any transient blip) can drop a session's host binding past the interactive-session reaper's grace window; the reaper correctly degrades the platform row to the non-terminal paused status rather than failed (degrade, don't destroy), but nothing on the platform side re-binds it on its own. If the session-shim on this host kept the harness alive the whole time - only the relay room went away, not the process - the platform metadata is simply stuck and the session is fully recoverable.
The PTY session host, the session-shim registry, and the wire protocol are OSS, documented at donmai.dev/docs/sessions. This page covers the platform CLI's rebind verb.
Two steps, in order
The command never touches the platform without first proving the session is alive on this exact host:
- Verify local truth. It reads the on-disk session-shim registry record for this session id on this host, and refuses loudly - without ever contacting the platform - unless BOTH hold:
- the record's phase is
running, and - the harness pid it names is still that same process (a start-time-checked liveness test, not a bare
kill -0, which a reused pid would pass wrongly).
- the record's phase is
- Ask the platform to rebind, only once step 1 passes. The platform performs its own independent CAS-guarded status flip back to
activeand refuses a session with recorded terminal evidence even if local truth said otherwise (a stale or reused local record racing a real, already-reported death always loses).
Single-session granularity only. This command takes exactly one session id and touches exactly one platform row - never host-wide, per the resilience program's per-session rebind doctrine.
Idempotent. Rebinding an already-active session is a no-op success, not an error.
Auth precondition
Same posture as rensei session launch and rensei session attach: a human user login only.
rensei auth add --userAn org API key (rsk_*) or a project-scoped token carries no user identity, so it cannot rebind a session - the platform route rejects it 403 (there is no userId to attribute the rebind to, and this is a human-operator recovery action, not an automation).
Usage
rensei session rebind <session-id>There are no command-specific flags beyond --json (always emits the typed outcome; the flag exists for discoverability, not to toggle behavior). See Global flags for --auth, --org, --project, --url, and the rest.
Output
rensei session rebind a1b2c3d4e5f6a7b8On success, two lines to stdout (plus the JSON outcome object):
VERIFIED - local session-shim registry (<dir>): org=<id> shim=<id> phase=running pid=<pid>
REBOUND - session a1b2c3d4e5f6a7b8 is now active (was paused)If the session was already active, the second line reads NO-OP - session <id> is already active; nothing changed instead, and the process still exits 0.
Troubleshooting
| Stage | Cause | Message |
|---|---|---|
| Local refusal (no request sent) | No session-shim registry record on this host matches the id | no local session-shim record for this session |
| Local refusal (no request sent) | Multiple records match (ambiguous) | ambiguous: multiple local session-shim registry records match session id "…" (orgs "…" and "…") - refusing |
| Local refusal (no request sent) | Record's phase is not running | session-shim registry record for … reports phase "…", not "running" - refusing to rebind a session this host cannot prove is running |
| Local refusal (no request sent) | Harness pid is not alive (exited, or reused by an unrelated process) | session-shim registry record for … reports phase running with harness pid …, but that process is not alive … - refusing to rebind |
| 401 | Not authenticated | not authenticated - run 'rensei auth add --user' first |
| 403 | Non-user token (org API key / OAuth-agent token) reached the platform | Platform message surfaced verbatim: interactive sessions require a human user identity - API keys and OAuth-agent tokens cannot rebind a session. |
| 404 | Session not found, in a different org, or the caller lacks project access / the driver role | Not found. |
| 409 | session_terminal | The session is already ended/failed - a terminal session can never be rebound. |
| 409 | terminal_evidence_recorded | The platform has recorded positive terminal evidence for this session's shim lineage (its process group was proven reaped) - rebinding would resurrect a session that is provably dead. Evidence (host id, shim id, obligation revision, resolved-at) is printed when present. |
| 409 | race_lost | A concurrent lifecycle write raced this rebind. Retry. |
Related pages
- Session Launch - the CLI verb that spawns the interactive sessions this command recovers
- Interactive Sessions - the session lifecycle, presence/driver model, and status semantics
- donmai.dev - Sessions - the OSS PTY host, wire protocol, and session-shim registry canonical reference