Session lifecycle

Session lifecycle describes how a coding session moves through Jarvis over time, including launch, active work, human intervention, follow-up, and completion.

Definition

The session lifecycle is the ordered sequence of states and control transitions that a coding session goes through after Jarvis launches it or discovers it from a local runtime.

Why It Exists

Without a clear lifecycle, session management becomes guesswork. Operators need to know:

whether a session is new, active, waiting, blocked, or reusable
when a worker needs human help
when it is better to dispatch more work versus start a fresh session
how to recover supervision after a page reload or temporary disconnect

The lifecycle model gives those decisions a consistent frame.

How It Works

Most sessions move through a variation of this loop:

Created A managed session is launched from Jarvis, or a local runtime session is discovered.
Active The worker is producing output, editing code, running commands, or otherwise moving the task forward.
Waiting The runtime is idle on a tool call, model response, or external process.
Blocked or decision-needed The worker raises a blocker, asks a human question, or requests more context.
Follow-up A human answers, dispatches more work, or decides to inspect the full session before proceeding.
Settled The task branch is complete, paused, or no longer the best session to continue from.

The exact runtime mechanics differ, but the supervisory lifecycle is the same: work starts, signals are observed, human intervention happens only when necessary, and follow-up work can continue from the same session when it is still the best context holder.

Typical User-Facing States

Running: Agent is actively producing output or executing work.
Waiting: Agent is waiting for a tool, model, or external process.
Blocked: Agent needs human input or cannot proceed safely.
Idle: Session is available but not currently progressing.
Human: A user decision or remote response is needed.
Agent: A worker or brain session reported state through MCP.

Managed and Local Session Entry Points

Managed sessions enter the lifecycle at launch.
Local runtime sessions enter the lifecycle at discovery.

From that point on, both can appear in the same session list and be inspected through the same supervisory UI, even when their control options are different.

Failure Modes

Orphaned state: a session exists in the runtime, but supervision is temporarily stale until Jarvis refreshes it.
Wrong reuse decision: dispatching to an old session can be less effective than starting fresh if the context has drifted too far.
Human queue buildup: several workers can reach decision-needed states at once, creating an operator bottleneck.
False completion assumptions: a worker may stop emitting updates before the actual task branch is cleanly finished.

The lifecycle view helps reduce these errors by making intervention points explicit.