Feature Reference

Keybindings, header fields, states, exit codes and configuration for ait frozenagent

Maturity:

Experimental

Depth:

Advanced

Keybindings

Every key below can be rebound — press ? for the in-place editor, or open Settings → Shortcuts.

Key	Action	Notes
`r`	Toggle ANSI replay / plain text	Viewer mode only
`m`	Render the capture as Markdown	Selected range if any, else the whole capture
`/`	Open the search box	Viewer mode only
`n`	Jump to the next match	Wraps, and says so
`Escape`	Close the search box, else clear the keyboard range	Every Escape also clears a mouse selection
`shift+↑` / `shift+↓`	Extend a line range from the cursor
`y`	Copy the selection	Keyboard range first, else the mouse selection
`ctrl+c`	Copy the selection	Same as `y`. With nothing selected it shows the quit hint; in the open search box it copies the text selected there. If you rebind it, `ctrl+c` still copies
`g` / `G`	Jump to the top / bottom
`R`	Restore the agent	No confirmation
`P`	Re-pick the task	No confirmation; needs a task id on the record
`k`	Drop the record	Confirms — this deletes the capture
`Enter`	Open the highlighted record	List mode only
`j`	TUI switcher
`?`	Shortcut editor
`q`	Quit

The footer advertises only Keys, Quit, Plain/ANSI, Markdown, Search, Restore, Re-pick and Drop, plus Copy (y and ctrl+c) while something is selected; the rest are bound but unlisted.

While an operation is in flight on a record, that record’s R, P and k are disabled rather than queued.

Header fields

Seven fields joined by ·, in this order:

Field	Empty value
Project root, shortened	—
tmux window name	—
Task (`t<id>` plus its title)	`(no task)`
Agent string	`(agent unknown)`
`frozen <timestamp>`	falls back to the record’s state
`<n> lines`	—
State, or the note currently overriding it	—

Trailing markers: \[plain], \[colour unavailable — showing plain text]. State suffixes: · capture missing, · colour data missing.

In list mode the header is frozen records: <n> instead.

States shown

The viewer prints the record’s state from the session store verbatim. The vocabulary is live, freezing, frozen, restoring and aborting — a frozen record you are reading normally shows frozen, and the transitional values appear while an operation is settling.

Outcomes are sentences rather than states:

Message	Capture	Meaning
`restored`	deleted	the resumed agent confirmed itself
`restored, unverified — capture kept`	kept	running, but unconfirmed — a success
`restore failed: <reason> — capture kept`	kept	the attempt failed; the viewer is back
`restore ended — capture kept`	kept	ended with no recorded reason
`cannot restore: <reason> — re-pick it instead (P)`	kept	the record cannot be resumed (no session, or its CLI is unknown or not the one the restore would launch); nothing was dispatched
`restore did not start — run 'ait frozenagent' or reconcile`	kept	nothing was dispatched
`restore still <state> after the grace — run reconcile; capture kept`	kept	still transitional
`record vanished`	—	the record is gone
`dropped — capture removed`	deleted	drop succeeded
`drop failed — record kept`	kept	nothing was deleted

A viewer that returns after a failed restore shows the store’s memory of it: last restore failed: <reason> — capture kept.

Exit codes

Code	Cause
`0`	Normal quit
`1`	Missing Python packages, or an interpreter older than the framework requires — both say to run `ait setup`
`2`	Bad arguments (`usage: ait frozenagent [--record <id>]`), or `frozenagent: unknown record <id>`

Configuration

Two keys under a frozen: block in aitasks/metadata/project_config.yaml affect frozen agents. No frozen: block ships by default, so both defaults apply unless you add one.

Key	Default	Effect
`capture_max_lines`	`50000`	How far back into the pane’s scrollback a freeze reaches. The capture is the tail of the scrollback, so a pane with more history than this keeps only its most recent lines
`restore_ack_grace`	`20` (seconds)	How long a restore waits to be verified — by the resumed agent’s SessionStart hook, or for a Codex resume on Linux by the transcript its process holds open — before falling back to confirming on liveness alone

restore_ack_grace is read from the record’s own project, not from whichever project you happen to be viewing from, because a freeze-all spans projects.

The same grace sets how long the viewer watches a restore before reporting restore still <state> after the grace — run reconcile; capture kept: 10 seconds for the dispatch, plus restore_ack_grace, plus 10 seconds of slack — 40 seconds at the default. The viewer reads it from the record’s project, so raising the grace never turns a slow but successful restore into a stall report.

It sets a waiting period, not an outcome. Raising it only helps an agent whose acknowledgement is slow to arrive. One that never acknowledges at all within it reaches restored, unverified — capture kept however long the grace is: its CLI reports no session on startup, the session hook is not installed, or it is a Codex resume whose session cannot be read from the process. Nothing is lost in that case: the unverified outcome is the one that keeps the capture.