docs(maestro): record the activity-detail meta-line slot and report TTL
This commit is contained in:
+10
-4
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user