Agent Session Lifecycle

An agent session is the durable container Tycho supervises. A run is one harness process inside that session. Follow-ups normally reuse the harness’s native session ID, while Tycho keeps its own conversation and run history under ~/.tycho.

Create and Inspect

Create a session without starting it, or add --run to start immediately:

tycho agent create my-project "Inspect the failing test"
tycho agent create my-project "Inspect the failing test" --run

Use the returned key for later commands:

tycho agent status <agent-key>
tycho agent logs <agent-key> --type conversation
tycho agent logs <agent-key> --follow

status --json is the stable automation surface. logs is local-only and can show raw, conversation, or system output.

Run and Follow Up

Start or re-run an idle session with:

tycho agent run <agent-key>

Send a new user message and start the next run with:

tycho agent send <agent-key> "Try the smaller reproduction"

In Remote UI, the conversation updates while the harness runs. Follow-ups submitted during a run enter a durable ordered queue and start continuation runs after the current run stops. An unresolved structured inquiry blocks that queue until the inquiry is answered, dismissed, or replaced by an allowed parent action.

Status and Attention

Tycho separates process state from the structured result returned by the harness.

Operator state	Meaning	Typical next action
Running	A harness process is active.	Watch the live conversation or queue a follow-up.
Needs input	The result is input_required with a structured inquiry.	Answer it in the TUI or Remote UI.
Succeeded	The result is success or no_action_needed.	Review the summary or send a follow-up.
Partial	Useful work completed, but required work remains.	Send the missing direction or start another run.
Failed	The run or structured-result correction failed.	Inspect the summary and logs, then retry.
Blocked	Progress requires an external change.	Resolve the dependency, then send or run again.
Stopped	An operator or scheduler stopped the process.	Inspect partial output before restarting.

no_action_needed is a quiet success for an observational or recurring check that found no new condition. It does not mark the session unread or send a push notification. Completed changes, answers, commits, reviews, and deliverables use success even when nothing remains afterward.

Remote UI can dismiss an inquiry without rewriting conversation history, then restore it later. Dismissal removes the immediate attention state; it does not answer the question.

Stop, Clone, and Archive

Stop a running harness without deleting its session:

tycho agent stop <agent-key>

Clone a local session when new work should start from a copied durable context instead of continuing the same identity:

tycho agent clone <agent-key>
tycho agent clone <agent-key> --run
tycho agent clone <agent-key> --handoff --run

Manual archive moves a session out of active lists and polling. From the CLI, stop a running session first:

tycho agent archive <agent-key>
tycho agent list --archived
tycho agent list --include-archived

Manual archive in Remote UI stops active work and cancels an unresolved inquiry. It does not run queued work. Undelivered user prompts are declined with a reason; protected delegation callbacks are superseded with a reason and kept in read-only history. Delivered or in-flight work is marked aborted with uncertainty. Queue outcomes, inquiry cancellation, and delivery evidence remain in the archive.

Archives retain the transcript, artifacts, run metadata, and delegation references. Typed delegation links and direct archived-agent routes remain readable, but archived sessions do not resume automatically.

Context Pressure and Handoffs

Tycho warns when reliable active harness evidence shows context pressure. A percentage appears only when the harness reports a valid limit. Missing evidence remains unknown.

You can dismiss the warning for its current evidence and keep going. Start New saves a fresh replacement before it archives the source. Start with Handoff adds a concise continuity record and archives the source after the replacement starts. A recurring schedule follows the replacement; check the target instead of creating a second schedule.

Context replacement blocks running agents, unresolved inquiries, and ordinary or mixed queued work. Stop active work, answer or retire the inquiry, and process or remove ordinary queue entries first. Callback-only work can be retained in archived history. Manual archive has the different outcomes described above; do not rely on replacement guards to protect work from manual archive.

Ordinary tycho agent clone <agent-key> --handoff creates a clone and retains its source. It is not the same operation as Remote UI Start with Handoff context replacement.

Durable Queue Work

tycho agent send <agent-key> "Continue the check" --delay 60 stores a follow-up with an earliest delivery time. Tycho claims due work in acceptance order. Future entries do not block due entries. New arrivals stay in the next batch.

tycho queue <agent-key> consumes pending work into one durable batch and records a Read queue conversation block. Repeated reads return the same open batch. The response contains stable entry IDs, attachments, required user instructions, and delegated reports.

success, no_action_needed, and partial automatically settle delivered work: user instructions become completed and delegated reports become incorporated. Partial stays visible as Partial while later work can continue. Failed, blocked, and input-required runs retain unresolved work. Explicit outcomes remain available through queue-work complete.

Failed dispatch claims remain inspectable. Retry them when the cause is fixed, or discard an eligible failed batch with a recorded reason. Protected delegation callbacks must be retried. Exact queue snapshots protect selected-entry process and remove actions from stale controls. See CLI Reference.

Tycho stops a managed run on its third proven blocking wait invocation for supported harnesses and schedules one bounded recovery. A manual send or run cancels that recovery. The stop reason is Stopped due to overusing sleep-like commands.

Remote Lifecycle

create, list, status, run, send, stop, and archive accept --server <key> for a configured peer. logs and clone remain local-only. Every mutation runs on the server that owns the project and session; Remote UI combining several servers does not merge their state.

See Delegating Work Between Agents for child ownership and callbacks, Schedules for recurring runs, and the CLI Reference for command forms.