docs(maestro): record the activity-detail meta-line slot and report TTL

This commit is contained in:
Miguel Palhas
2026-08-24 21:39:15 +01:00
parent 5a594b2b7f
commit 015f2be5fb
2 changed files with 14 additions and 4 deletions
+10 -4
View File
@@ -41,7 +41,7 @@ Otherwise line 2 is absent — never an empty placeholder row.
When present, line 2 reads left to right:
```
<dot> <duration> [<blocked work> | exited] [<command>]
<dot> <duration> [<detail>] [<blocked work> | exited] [<command>]
```
`<dot>` is a single filled glyph (`●` on both clients) carrying the activity
@@ -52,6 +52,11 @@ and duration are unconditional parts of line 2; the bracketed fragments appear
only when their trigger holds. A payload that predates #102 (no usable
`activity_since`) contributes no duration — the dot still renders.
`<detail>` is an agent-reported string (#105) — e.g. why a session is in
`Error`. It sits right after the duration, in the muted style, and shows only
while an agent-reported state is in force (see Precedence): when the report
lapses at its TTL or is replaced, the detail goes with it.
`<command>` is optional and muted: the session's command line, shown only when
the rendered name came from `metadata.name` and differs from the command (the
web has always surfaced this; the TUI may omit it).
@@ -94,9 +99,10 @@ cutover points land within one tick.
## Precedence
An agent-reported `ActivityState` (#105) overrides the daemon's inference for
the TTL the report carries; when the TTL expires, inference resumes. Clients
never blend the two: whichever source is in force supplies both the colour and
the clock for `activity_since`.
**five minutes** (the TTL is fixed by the daemon; re-reporting extends it).
When the TTL expires, inference resumes and the session's reported detail —
if any — clears with the report. Clients never blend the two: whichever source
is in force supplies both the colour and the clock for `activity_since`.
If a client receives an `ActivityState` variant it does not know, it must not
fail rendering: treat it as `Idle` (neutral/dim, line-2 rules apply as usual)
+4
View File
@@ -26,6 +26,10 @@ export interface Session {
foreground?: string | null;
/** Inferred activity. Defaults to `Idle` on the wire when omitted. */
activity?: ActivityState;
/** Short human string an agent reported alongside its state (#105) — e.g.
* why it is in `Error`. Shown on a sidebar card's meta line while the
* report is in force; cleared when the report lapses or is replaced. */
activity_detail?: string | null;
/** Wall-clock of the most recent observed PTY output (NAP-340). */
last_activity_at?: IsoTimestamp;
/** Wall-clock of when the session entered its current `activity` state