herdr-gentle-shell 0.0.0-stage → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/DESIGN.md ADDED
@@ -0,0 +1,875 @@
1
+ # herdr-gentle-shell — DESIGN.md (Task 4, as implemented)
2
+
3
+ Status protocol for the Herdr sidebar: producer (Pi sidecar extension) →
4
+ pane-metadata tokens → consumer (plugin daemon) → sidebar state + badges.
5
+
6
+ Scope note: despite the filename, this file is the normative *protocol*
7
+ authority (token grammar, lifecycle, ownership), not an Impeccable visual
8
+ DESIGN.md (no design-token frontmatter by design — sidebar colors live as
9
+ hardcoded hex in the manifest/docs). Status: implemented; the file is the
10
+ normative protocol record. Unresolved product/policy decisions are listed
11
+ explicitly in §10 and are not decided here.
12
+
13
+ ## 1. Context
14
+
15
+ ### Consumers
16
+
17
+ - Herdr sidebar (`[ui.sidebar.agents]` + `[ui.sidebar.spaces]` blocks): shows
18
+ one state label per pane plus an optional session-changes badge.
19
+ - The human operator watching Pi + Gentle Shell agents: needs to distinguish
20
+ generic activity (`gentle`, machine key `working`) vs the active TaskStore role (`explorer`,
21
+ `worker`, `verify`, `rdd`), `ask` (blocked on user input), `blocked`
22
+ (error), `done`, and `idle` at a glance. No visible text ever carries
23
+ a subagent count, and generic activity never reads `working`.
24
+
25
+ ### Current boundary and interaction
26
+
27
+ - Transport already exists and is not redesigned: Pi extensions publish
28
+ per-pane key=value tokens via `pane.report_metadata` /
29
+ `workspace.report_metadata` over `HERDR_SOCKET_PATH`, with a CLI fallback
30
+ (`herdr pane report-metadata <pane> --source <src> --token name=value`).
31
+ - The consumer is a poller, not a subscriber: the plugin daemon reads the
32
+ Herdr snapshot on a cadence and reduces pane tokens to sidebar state.
33
+ No new socket, webhook, broker, or persistent connection is introduced.
34
+ - The existing native producer `herdr-agent-state.ts` (managed-by-herdr, v9,
35
+ source `herdr:pi`) already reports main-agent `working`/`blocked`/`idle` +
36
+ session ref. It is **read-only evidence**: never edited, reinstalled, or
37
+ removed by this plugin.
38
+
39
+ ### Style choice and reason
40
+
41
+ - Style: **polled token sidecar** (same style as `herdr-pi-tree`): short-TTL
42
+ `name=value` tokens on the pane, reduced by a snapshot poller.
43
+ - Reason (smallest fitting style): the transport, snapshot source, 16-token
44
+ budget, TTL/expiry convention, and sidebar token-name mapping already exist
45
+ and are deployed. A new push channel (SSE/WebSocket/webhook) or a new RPC
46
+ would add infrastructure without changing the authoritative outcome, which
47
+ remains "what does the sidebar show for this pane right now". The design
48
+ therefore **extends the established boundary** (new `gentle_*` token names,
49
+ same value grammar, same report path) instead of introducing another style.
50
+
51
+ ### Non-goals (tasks 5–8 scope excluded — all shipped since Task 4)
52
+
53
+ - Task-5+ scope (now shipped: `herdr-plugin/herdr-plugin.toml`, `README.md`,
54
+ the `extensions/` producer, the `herdr-plugin/bin/` + `herdr-plugin/lib/`
55
+ consumer, directory scaffold) was
56
+ excluded from the Task-4 design pass, not from the repo.
57
+ - No fork or modification of `herdr-pi-tree`; no edit of
58
+ `~/.pi/agent/extensions/herdr-agent-state.ts`.
59
+ - No toast/notification UI design beyond exactly-once ownership rules (§7).
60
+ - No deep security, performance, or observability design beyond contract
61
+ properties (trust expectations, limits, failure semantics).
62
+
63
+ ## 2. Existing API evidence
64
+
65
+ All paths verified read-only by scout `mu8wojpu-1-aia3` (2026-09-19).
66
+ Do-not-edit sources are marked.
67
+
68
+ | # | File | Lines | Observable fact (contract surface) |
69
+ |---|------|-------|-------------------------------------|
70
+ | E1 | `~/.pi/agent/extensions/herdr-agent-state.ts` (DO NOT EDIT, managed-by-herdr) | v9 header; `HERDR_INTEGRATION_ID=pi`, source `herdr:pi` | Publishes main-agent `working`/`blocked`/`idle` + session ref only; transport `HERDR_SOCKET_PATH` via `pane.report_agent_session` / `pane.report_agent` |
71
+ | E2 | `~/.config/herdr/plugins/github/herdr-pi-tree-41b1ee3237d2/lib/state.js` | 356–358 | Token `pi_subagents_work_v1` grammar verbatim `/^([A-Za-z0-9_-]{43}):(0\|[1-9]\d{0,15}):([1-9]\d{0,15})$/` = `<sessionHash>:<count>:<expiry>` |
72
+ | E3 | same `lib/state.js` | `sessionHash` def | `sessionHash = sha256(agent_session path).base64url` (43 chars) |
73
+ | E4 | same plugin | expiry rule | `expiry <= now + 60000` (60 s TTL horizon) |
74
+ | E5 | same plugin | reducer | `delegatedStatus = working` when native in `{idle, done}` and `count > 0` |
75
+ | E6 | same plugin | `composeBadge` | Badge = indent + delegated glyph `↳` (U+21B3) + count, e.g. `↳3`, default heading placement |
76
+ | E7 | same plugin | token-name encoding | State encoded in token NAMES `state_working` / `state_done` / `state_blocked` / `state_idle_fresh` / `state_idle` / `state_idle_stale` / `state_unknown` + `title_<state>` |
77
+ | E8 | same plugin | `MAX_TOKENS_PER_REPORT=16` | Reports chunked to fit 16 tokens per report; transport `pane.report_metadata` / `workspace.report_metadata` via socket IPC with CLI fallback `herdr pane report-metadata <pane> --source <src> --token name=value` |
78
+ | E9 | same plugin | attention rule | NO toast from plugin side; Herdr fires native attention on `blocked` |
79
+ | E10 | Herdr sidebar config | `[ui.sidebar.agents]` + `[ui.sidebar.spaces]` | Sidebar consumes managed blocks; token-name → label/badge mapping is configuration |
80
+ | G1 | `/home/jona/repos/gentle-shell/lib/session-changes.ts` | `SESSION_CHANGE_ENTRY`, `gentle-pi.session-change/v1` | `SessionChanges` model: `files[{path,status,added,deleted}]` + `added`/`deleted` totals |
81
+ | G2 | `/home/jona/repos/gentle-shell/lib/session-change-capture.ts` | capture rule | Captured ONLY from explicit `write`\|`edit` tool outcomes; never `git status` |
82
+ | G3 | `/home/jona/repos/gentle-shell/lib/agents-protocol.ts` | `TASK_STATUS`, `TaskStore` | `queued`/`running`/`waiting`/`finished` + `TaskStore` `list`/`summary` (`running`, `queued`, `waiting`, `finished`); labels = `TaskRecord.label`/`agent` |
83
+ | G4 | `/home/jona/repos/gentle-shell/extensions/ask-user-choice.ts` | `ASK_USER_CHOICE_BLOCKED_EVENT`, `gentle-pi:ask-user-choice:blocked` | Authoritative in-process `ask` signal |
84
+ | G5 | `/home/jona/repos/gentle-shell/extensions/gentle-ai.ts` | review tools | Registers `gentle_review` tools; contract `gentle-ai.review-integration/v2` |
85
+
86
+ ## 3. Overlap reconciliation (chosen modes)
87
+
88
+ Prefixing with `gentle_` is necessary but not sufficient. Each overlap gets
89
+ an explicit writer-ownership decision. Rationale follows each choice.
90
+
91
+ ### O1. Pane-token namespace + 16-token budget → SINGLE-WRITER HANDOFF
92
+
93
+ - **Chosen:** while this plugin is installed and enabled for a pane, it is
94
+ the sole writer of subagent/work/changes tokens for that pane;
95
+ `herdr-pi-tree` must be disabled (`enabled:false`, its current state) for
96
+ the same panes. The consumer never writes `pi_subagents_work_v1`,
97
+ `state_*`, or `title_*` names owned by pi-tree.
98
+ - **Budget rule:** the gentle producer keeps its own per-report token count
99
+ ≤ 16 (same chunking discipline as E8) so a single writer can never overflow
100
+ the budget; two concurrent writers could, which is why dual-write is banned.
101
+ - **Why not dual-write:** two writers sharing one namespace and one budget
102
+ produce badge collisions (`↳N` vs changes suffix) and silent token eviction
103
+ on chunking. Single-writer makes the budget a local invariant.
104
+ - **Fallback:** if foreign `pi_subagents_work_v1` tokens are observed while
105
+ gentle owns the pane, the consumer ignores them (read-only, never deletes
106
+ foreign tokens). If gentle is disabled, it writes nothing and leaves
107
+ pi-tree output untouched.
108
+
109
+ ### O2. Reuse vs replace `pi_subagents_work_v1` → REPLACE (do not reuse count)
110
+
111
+ - **Chosen:** the gentle producer publishes its own `gentle_work_v1` token;
112
+ the consumer treats it as source of truth and ignores
113
+ `pi_subagents_work_v1` while gentle owns the pane.
114
+ - **Why not reuse:** the two counts have different name sources that will
115
+ disagree — `TaskStore.label`/`agent` (G3, authoritative for Gentle
116
+ delegation) vs pi-tree's session-file scan. Reusing the foreign count would
117
+ show names the Gentle orchestrator never assigned. Same value grammar, new
118
+ token name, authoritative local source.
119
+
120
+ ### O3. `blocked` → notification ownership → NATIVE ONLY; CONSUMER NEVER (v0.3.1)
121
+
122
+ - **Chosen:** producer signals via `herdr:blocked` labels (`ask:`/`review:`/
123
+ `error:`) plus the native `pane.report_agent` state; desktop attention is
124
+ native Herdr exclusively (E9 unchanged): `Blocked` fires the `NeedsAttention`
125
+ toast and background `Working|Blocked → Idle` fires `Finished`, both
126
+ Herdr-owned. The consumer emits `herdr notification` for nothing — its
127
+ former ask toast fired on the poll after the native one for the same
128
+ question, a systematic duplication, so the toast path, its copy, the
129
+ notification ledger and the send machinery were removed in v0.3.1. The ask
130
+ token still drives the sidebar ask display; sounds, suppression, and delay
131
+ stay Herdr's. `review` never notifies (the user is already engaged in the
132
+ review flow; review attention stays native).
133
+ - **Why:** `ask` needs an out-of-band nudge (the run cannot proceed without
134
+ the user); `review` does not (the user is mid-ritual). Dedup is Herdr's
135
+ native edge-triggered toast semantics, not a plugin ledger.
136
+ See §7 for ownership semantics.
137
+
138
+ ### O4. Badge slot (`↳` taken) → TWO-ROW PI LAYOUT, NO SLOT SHARING
139
+
140
+ - **Chosen:** the `↳N` leading-badge slot stays owned by pi-tree and MUST be
141
+ absent under single-writer handoff (O1). Gentle renders exactly two rows
142
+ for the `pi` agent: row 1 is the heading context as exactly one active
143
+ cell — the active `gentle_heading_*` value holds `<icon> <project>` plus
144
+ compact nonempty changes segments (` +N`, ` -N`, ` ↑N`) in that same
145
+ cell (e.g. `● myproj +110 -22 ↑3`). Exactly one row-1 cell is nonempty,
146
+ so Herdr inserts zero inter-cell `·` separators. The cell sits on white
147
+ `#ffffff` (SIDEBAR_PROJECT) so the project text stays white; symbol
148
+ `contains` rules recolor the icon (unchanged state mapping) plus ` +`
149
+ green (added), ` -` red (deleted, leading-space match so hyphens inside
150
+ project names never turn red), and ` ↑` blue (pull). `gentle_project`,
151
+ `gentle_changes_summary`, and the change-segment tokens stay published
152
+ and owned for compatibility but are wired into no visible row; row 2 is
153
+ the agent context (the
154
+ dedicated `gentle_agent` identity cell plus the presence-encoded
155
+ `gentle_title_*` state labels — Herdr's native `·` separator renders the
156
+ visible `pi · worker`). The consumer never writes
157
+ `↳`, never parses it, never arithmetically combines segments, and never
158
+ emits the retired combined `~N` badge (no subtraction, no merging).
159
+ - **Why:** sharing one glyph slot between "delegated count" and "files
160
+ changed" makes the badge unreadable and couples two independent facts.
161
+ Two fixed rows keep each fact independently observable and match the
162
+ herdr-pi-tree tree shape.
163
+
164
+ ### O5. `done`/`idle` freshness vs pi-tree done-hold + idle grace → TTL WINS; SWEEP OWN TOKENS ONLY
165
+
166
+ - **Chosen:** every gentle token carries an absolute `expiry <= now + 60000`
167
+ (same 60 s horizon as E4). The consumer treats missing or expired gentle
168
+ tokens as `unknown → idle` fallback (never holds `done` past expiry).
169
+ On handover (gentle disabled/uninstalled) the consumer sweeps only token
170
+ names it wrote (`gentle_*`, `herdr:blocked` labels it set); it never deletes
171
+ pi-tree or native tokens.
172
+ - **Why:** holding `done` past TTL shows a finished state for a pane that may
173
+ have started new work; expiring to `idle` (native fallback) is the safe
174
+ direction. Scoped sweep prevents orphan `gentle_*` badges without
175
+ destroying a successor writer's state.
176
+
177
+ ## 4. Producer contract (Pi sidecar extension; events → tokens)
178
+
179
+ Sidecar only: ships beside `herdr-agent-state.ts`, never modifies it.
180
+
181
+ ### 4.1 Identity and trust
182
+
183
+ - Source id: `gentle:v1` (token `--source` value and `herdr:blocked` origin).
184
+ - Session binding: `sessionHash = base64url(sha256(agent_session path))`,
185
+ 43 chars `[A-Za-z0-9_-]{43}` (same derivation as E3 so pane correlation
186
+ matches pi-tree conventions without reusing its tokens).
187
+ - Trust: producer runs in-process with the Pi agent; it reports only facts
188
+ from Gentle tool outcomes and protocol stores (G1–G5). It never reports
189
+ `git status` diffs (G2) and never invents review state (see §10 U4).
190
+
191
+ ### 4.2 Events → tokens mapping
192
+
193
+ | Producer event (source) | Tokens written | v1 state contribution |
194
+ |---|---|---|
195
+ | `agent_start` / `isIdle=false` (main actively working, incl. 0 active subs) | `gentle_work_v1=<hash>:0:<exp>` + `gentle_principal_v1=<hash>:<exp>` (principal-only activity marker) + `gentle_orchestrating_v1=<hash>:<exp>` (root marker while main actively works) + clear `herdr:blocked` labels | `gentle` (machine key `working`, or `orchestrating` while the root marker is fresh) while the principal session actively works, even with zero subagents |
196
+ | TaskStore `running` non-empty (G3; queued/waiting never execute) | `gentle_work_v1=<hash>:<count>:<exp>` (running total of delegates — never a principal-working signal) + `gentle_roles_v1=<csv>` (roles from `TaskRecord.agent`, authoritative, oldest-first) + `gentle_names_v1=<csv>` (compat transport only, never rendered) + `gentle_orchestrating_v1=<hash>:<exp>` (root-only marker, §4.3) | the oldest running role word (known short word or unknown sanitized name) whenever the principal itself is not working; a working principal reads `gentle` instead; role labels show the total when two or more delegates run |
197
+ | `ASK_USER_CHOICE_BLOCKED_EVENT` / `gentle-pi:ask-user-choice:blocked` (G4), incl. questionnaire + tool-gated `ui_prompt` dialog spans (`kind` other than `custom` — a panel or overlay such as the agents view, ODD viewer, changes view or design canvas never counts, because opening a panel is navigation, not a question), plus direct Pi in-process `tool_execution_start` opens / `tool_execution_end` / `tool_result` closes for the exact tools `ask_user_question` and `ask_user_choice`, tracked by `toolCallId` in a call-id set (a `tool_call` proposal alone never opens; an abort/error end with no result still closes; overlapping calls correct; cleared on result/end/reset/shutdown; event legs and error > ask > review precedence unchanged; boundary: only what Pi emits as execution events is observable — a host ask UI that never emits one stays covered by the event legs only). `gentle_review` starts (any operation) never enter ask: the former consent-eligible pending signal fired before any outcome/UI and falsely blocked pre-granted sessions | `herdr:blocked` label `ask:<intentId>` + durable `gentle_ask_v1=<hash>:<intentId>:<exp>` on every beat while ask is active (null/clear when inactive — repairs a missed label edge; §4.3) | `ask` (existing machine key, user-facing `ask`, amber/orange, native `?`) |
198
+ | Pi in-process `tool_execution_start` opens / `tool_execution_end` / `tool_result` closes (by `toolCallId`; a `tool_call` proposal alone never opens) for the exact tools `gentle_review_capture`, `gentle_review_capture_group` with `reviewerRunAcknowledged: true` in the runtime args; `correctionLines` (native planning, never a reviewer), forecast-only calls, `gentle_review` (any operation), `gentle_review_scope`, and all sidebar/hook signals never enter — unknown legacy shapes stay dark (conservative) | `herdr:blocked` label `review:<reviewId>` | `review` (machine key `review`) — during a capture-group run the single parent capture-group call stays in flight across the whole multi-reviewer span, so that one call alone holds the label. Bounded approximation: the acknowledged capture interval contains preparation and admission; no exact reviewer internal events exist today |
199
+ | agent error / task failed / transport failure | `herdr:blocked` label `error:<code>` | `blocked` (machine key `error`) |
200
+ | `agent_settled` + 0 active subs | `gentle_work_v1=<hash>:0:<exp>`; clear `blocked` labels | `done` |
201
+ | `SESSION_CHANGE_ENTRY` `gentle-pi.session-change/v1` tool outcome (G1/G2) | `gentle_changes_v2=<hash>:<files>:<added>:<deleted>:<exp>` (+ legacy `gentle_changes_v1` dual-emit, §4.3) | change segments only (orthogonal to state) |
202
+
203
+ `waiting`/`finished` TaskStore entries never count as active, and `queued`
204
+ never counts as executing for the visible role + total (T2b): only `running`
205
+ feeds `gentle_work_v1` and `gentle_roles_v1`. Liveness/marker coverage
206
+ retains `running`/`queued`/pending (the root marker still covers a queued
207
+ subagent or a pending launch). The count is a direct projection of the
208
+ Gentle Shell TaskStore `running` records carried in
209
+ `event.details.gentleAgents` — never a calculated pending-call estimate.
210
+ Background launches (`subagent_run` with `mode: background`) announce their
211
+ lifecycle over `message_end` custom results instead of `tool_result`
212
+ details: an ACTIVE status (running|queued) there promotes the background
213
+ start into the tasks map exactly like a task-mode record (settle-safe,
214
+ oldest-first, cleared by its FINAL), so a background delegate keeps the pane
215
+ on the delegate's role word instead of settling to `idle`/`done`.
216
+ The visible activity state
217
+ is the bounded `gentle_roles_v1` CSV derived from `TaskRecord.agent`
218
+ (oldest-first by immutable firstSeen): exact `gentle-ai-explore` (actual
219
+ package agent name, verified in the project registry alongside
220
+ `gentle-ai-worker` / `gentle-ai-verify` / review agents; the legacy
221
+ `gentle-ai-explorer` alias is preserved for compatibility) → `explorer`,
222
+ exact `gentle-ai-worker` → `worker`, exact `gentle-ai-verify` → `verify`,
223
+ `jd-judge-a` / `jd-judge-b` / `jd-fix-agent` (plus the `jd-judge-` /
224
+ `jd-fix-` families) → the distinct `judge` slug (never `rdd`), and a
225
+ review agent / `gentle-ai-review*` / any role containing `review` → `rdd`;
226
+ any other agent keeps its original sanitized name (lowercase `[a-z0-9_-]`
227
+ slug, 32-char bound — never a generic collapse; unsalvageable shapes read
228
+ generic `gentle`, machine key `working`).
229
+ The consumer displays the oldest role word (known short word or unknown
230
+ sanitized name) whenever the principal itself is not working, regardless of
231
+ how many delegates run; a working principal renders `gentle` instead.
232
+ Role labels carry the total running-delegate count in parentheses when greater
233
+ than one. Role order is immutable first-seen (progress reads never reorder;
234
+ sound same-session presence createdAt/startedAt may correct a late local
235
+ first-sighting, otherwise the local firstSeen stands).
236
+ Pending subagent tool calls are label correlation state for a later
237
+ `gentleAgents.taskId` result and a role-only display hint while the call is
238
+ in flight — never a count. WHY role-only: task-mode `subagent_run` stays in
239
+ flight with no TaskStore record until it returns `tool_result`, so the exact
240
+ agent name in the pending `tool_call` input is the only live role evidence;
241
+ counting it would inflate the normative `gentle_work_v1` total with an
242
+ estimate, while publishing its role slug as a bounded-CSV hint keeps the
243
+ sidebar on the active role (`worker`, never bare `working` — generic activity reads `gentle`) with the count
244
+ authoritative at 0. The hint merges with authoritative active TaskStore roles
245
+ (oldest-first) and clears when the tool result arrives, the call is
246
+ cancelled, or the agent settles. On a tool
247
+ result the producer reads the pending record before deleting it and uses it
248
+ only to preserve the task label on the authoritative task record; no task
249
+ record is created when `details.gentleAgents` is missing. A live `running`
250
+ record is never regressed by a racy non-final read: status observations via
251
+ any tool other than the authoritative `subagent_run`/`subagent_continue`
252
+ launch outcomes keep `running` (and its agent) against `queued`/`waiting`/
253
+ `unknown`, while FINAL statuses still apply as completion truth and
254
+ re-resolve oldest-first — so a working principal with live delegates keeps
255
+ `gentle`, and a settle with running delegates keeps the oldest role word
256
+ instead of settling to `idle`/`done`. A sanitized unknown slug exactly equal to
257
+ `working` degrades to no role (generic `gentle`) on both the producer
258
+ (`agentToRole`) and the consumer (`roleToDisplay`) sides. No local
259
+ age/staleness timeout is applied — Gentle Shell owns lifecycle/status truth.
260
+ Finished/failed/cancelled records may linger in the map but never count;
261
+ old records are dropped only on session reset (plus the bounded-map guard).
262
+ The root session emits `gentle_orchestrating_v1` while the main session is
263
+ actively working (`agentActive`, even with zero subagents), retaining
264
+ coverage while the authoritative active list is non-empty or any
265
+ `subagent_run`/`subagent_continue` launch is pending, and clears it (null)
266
+ once the main session settles — settled, or any non-root session. The marker carries no
267
+ count and changes neither the work total nor the roles CSV: it is a pure
268
+ freshness-bound presence flag (`<hash>:<exp>`, same binding/TTL style as
269
+ gentle_work_v1) that the consumer reduces to `orchestrating` only with no
270
+ delegation active (§5.2): below attention (error/ask/review),
271
+ terminal `done`/native-`blocked`, and role words; ahead of generic
272
+ activity only.
273
+ The root session also emits `gentle_principal_v1` while its own agent is
274
+ active (`agentActive`) and clears it (null) the moment the principal
275
+ settles, keeping the same binding/TTL discipline. This is the principal-only
276
+ signal: it carries exactly the principal input of `computeNativeState`, never
277
+ the delegate aggregate, because the native status answers `working` for a
278
+ running delegate, a pending launch, or a live job — none of which say the
279
+ principal itself works. The native status keeps that aggregate meaning for
280
+ Herdr's own pane state; the row's working-vs-idle decision reads only
281
+ `gentle_principal_v1` (§5.2). It carries no count and alters neither the work
282
+ total nor the roles CSV.
283
+
284
+ ### 4.3 Token formats (ABNF-ish, strict)
285
+
286
+ ```text
287
+ sessionHash = 43*[A-Za-z0-9_-] ; base64url(sha256(agent_session path))
288
+ expiry = 1*15DIGIT ; unix-ms, MUST satisfy expiry <= now+60000 at write
289
+ count = "0" / [1-9] 0*15DIGIT
290
+ gentle_work_v1 = sessionHash ":" count ":" expiry
291
+ gentle_changes_v1 = sessionHash ":" count ":" count ":" expiry
292
+ ; <hash>:<files>:<added+deleted>:<expiry> — LEGACY, see below
293
+ gentle_changes_v2 = sessionHash ":" count ":" count ":" count ":" expiry
294
+ ; <hash>:<files>:<added>:<deleted>:<expiry>
295
+ ; normative: exact added/deleted totals kept separate so
296
+ ; the sidebar renders +N/-N without a guessed split
297
+ gentle_names_v1 = label *("," label) ; label = TaskRecord.label/agent, 1*64 chars
298
+ ; total <= 512 UTF-8 bytes (see §4.5)
299
+ ; compat transport only — never rendered
300
+ role = "explorer" / "worker" / "verify" / "judge" / "rdd" / passthrough
301
+ ; known TaskRecord.agent derivations, oldest-first
302
+ ; (`review` accepted as a legacy alias of `rdd`; `judge`
303
+ ; stays distinct, never `rdd`)
304
+ ; passthrough = 1*32 lowercase [a-z0-9_-], leading [a-z0-9]
305
+ ; (unknown delegation keeps its sanitized original name —
306
+ ; never a generic collapse; producer truncates to 32)
307
+ gentle_roles_v1 = role *("," role) ; total <= 512 UTF-8 bytes; null (clear)
308
+ ; when no delegation is active (no role words)
309
+ gentle_orchestrating_v1 = sessionHash ":" expiry
310
+ ; root-only presence marker, no count — fresh while the
311
+ ; root main session actively works (even with zero subs),
312
+ ; retaining running/queued-sub or pending-launch coverage;
313
+ ; null (clear) once the main session settles
314
+ gentle_principal_v1 = sessionHash ":" expiry
315
+ ; principal-only activity marker, no count — fresh while
316
+ ; the principal session's own agent is active
317
+ ; (agentActive: the principal input of computeNativeState,
318
+ ; never its delegate aggregate), null (clear) once the
319
+ ; principal settles; decides working vs idle in §5.2
320
+ ; while the native status keeps its aggregate meaning
321
+ ; (running delegate / pending launch / live job = working)
322
+ gentle_ask_v1 = sessionHash ":" intentId ":" expiry
323
+ ; durable ask signal, session-bound + TTL-fresh like
324
+ ; gentle_orchestrating_v1 — emitted on every beat while
325
+ ; ask is active, null (clear) when inactive; repairs a
326
+ ; missed edge-triggered herdr:blocked ask label
327
+ gentle_review_v1 = sessionHash ":" reviewId ":" expiry
328
+ ; durable review signal, session-bound + TTL-fresh —
329
+ ; emitted on every beat while acknowledged capture/group
330
+ ; execution is in flight, null (clear) otherwise; silent
331
+ ; working natively, never a notification (full def:
332
+ ; extensions/gentle-herdr-state.ts, herdr-plugin/lib/gentle-tokens.js)
333
+ herdr:blocked = "ask:" intentId / "review:" reviewId / "error:" code
334
+ ```
335
+
336
+ Versioning rule: v2 is a new token name, not a grammar change to v1 (§9).
337
+ The producer dual-emits v1 (combined delta, for rollback consumers) and v2
338
+ (exact split, normative). The consumer reduces ONLY v2 for display: a
339
+ v1-only pane renders no change segments (fail-closed — the split cannot be
340
+ recovered from the sum). The retired combined `~N` badge is never emitted;
341
+ the sweeper clears the legacy `gentle_badge` name where a previous install
342
+ left it.
343
+
344
+ Validation: consumers MUST reject tokens failing the grammar (wrong hash
345
+ length, `expiry` in the past or `> now+60000` at read, non-numeric counts)
346
+ and treat the pane as `unknown → idle` for that signal (§7).
347
+
348
+ ### 4.4 Examples
349
+
350
+ ```text
351
+ pane.report_metadata --source gentle:v1 --token gentle_work_v1=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:2:1789000000000
352
+ pane.report_metadata --source gentle:v1 --token gentle_roles_v1=worker,explorer
353
+ pane.report_metadata --source gentle:v1 --token gentle_orchestrating_v1=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:1789000000000
354
+ pane.report_metadata --source gentle:v1 --token gentle_principal_v1=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:1789000000000
355
+ pane.report_metadata --source gentle:v1 --token gentle_names_v1=planner,code-writer
356
+ pane.report_metadata --source gentle:v1 --token gentle_changes_v2=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:5:110:22:1789000000000
357
+ herdr:blocked labels: ["ask:q-7f3a"] | ["review:r-42"] | ["error:transport-timeout"]
358
+ ```
359
+
360
+ Example reads: worker oldest + explorer active with count 2 → sidebar
361
+ `worker (2)` while the principal is idle (the oldest role word and total)
362
+ and `gentle` while it works (the principal's own activity marker wins); three
363
+ explorers with count 3 → `explorer (3)`; 5 files
364
+ / +110/−22 session delta → the single row-1 heading cell
365
+ `● myproj +110 -22` (` +` green for added, ` -` red for deleted with a
366
+ leading-space match, zero `·` separators because exactly one heading cell
367
+ is nonempty).
368
+ A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer/pull). A fresh root
369
+ `gentle_orchestrating_v1` marker renders pink `gentle` (machine display key
370
+ `orchestrating`, pink palette unchanged) while the principal session actively
371
+ works — even with zero subagents — and yields to a delegate role word and to
372
+ attention (`ask`/`review`/`blocked`) and terminal `done` states. While the
373
+ principal is working the marker colors that working state pink rather than
374
+ competing with it. The marker is not a principal-working signal: it stays
375
+ live while the principal is idle with queued or running delegates. The
376
+ working state itself comes from `gentle_principal_v1`: with no fresh
377
+ principal marker the pane shows the oldest role word (or `idle`), never
378
+ `gentle` merely because delegates run.
379
+
380
+ ### 4.5 Publication and chunking
381
+
382
+ - Same transport as E8: socket IPC `pane.report_metadata` /
383
+ `workspace.report_metadata`, CLI fallback
384
+ `herdr pane report-metadata <pane> --source gentle:v1 --token name=value`.
385
+ - One report carries at most 16 tokens; `gentle_names_v1` never chunks:
386
+ excess advisory names are dropped whole at 512 UTF-8 bytes total
387
+ (fail-closed).
388
+ The `#p=<i>/<m>` suffix form is retired and never emitted; a consumer
389
+ must not expect reassembly.
390
+ - Token values are bounded in UTF-8 BYTES, never in JS characters: Herdr
391
+ rejects the WHOLE `pane.report_metadata` beat when a single value exceeds
392
+ 512 bytes, so nothing in that report lands and the pane falls back to its
393
+ 60 s TTL. A character count is not a substitute — eight 64-character
394
+ Japanese labels stay inside every character cap and are ~1.3 KB on the
395
+ wire. Every published value (work, names, roles, changes, markers,
396
+ ask, review) is measured with `Buffer.byteLength(value, 'utf8')`, and the
397
+ publisher clamps any value that ever escapes its builder on a character
398
+ boundary (never splitting a surrogate pair) so one token can never take
399
+ its siblings down with it.
400
+ - Writes are idempotent full-state snapshots per pane (all gentle tokens
401
+ re-emitted each beat), never deltas — a lost report is repaired by the next
402
+ beat.
403
+ - Session-change tokens are refreshed/cleared from the current Gentle Shell
404
+ session model every beat and never carried across sessions: zero changed
405
+ files publishes a clear (null over socket metadata, `--clear-token <name>`
406
+ on the CLI fallback) for `gentle_changes_v1` and `gentle_changes_v2`, so a
407
+ new/reloaded session under a different session hash cannot retain the prior
408
+ session's change token. `gentle_names_v1` clears the same way when the
409
+ authoritative active TaskStore list has no labels, and `gentle_roles_v1`
410
+ clears (null) when no delegation is active. The retired disclosure token is
411
+ cleared to remove any stale metadata. v2 stays the visible
412
+ normative source; v1 remains legacy only.
413
+
414
+ ## 5. Consumer contract (daemon; snapshot → sidebar)
415
+
416
+ ### 5.1 Snapshot inputs (read-only)
417
+
418
+ Per pane: native `working`/`blocked`/`idle` + session ref (E1), `herdr:blocked`
419
+ labels (§4.2), `gentle_ask_v1` (durable ask signal + freshness gate for `ask` — repairs a missed `ask:` label edge, §4.3), `gentle_work_v1` (running total + freshness
420
+ gate — the total counts running delegates, not the principal; role labels
421
+ carry it as a suffix only when above one), `gentle_orchestrating_v1` (root-only presence marker
422
+ + freshness gate for the `orchestrating` display — never rendered as a
423
+ count), `gentle_principal_v1` (principal-only activity marker + freshness
424
+ gate for the working-vs-idle decision — never rendered as a count),
425
+ `gentle_roles_v1` (authoritative activity roles,
426
+ oldest-first by immutable firstSeen), `gentle_names_v1` (compat transport only — never
427
+ rendered), `gentle_changes_v2` (normative; a
428
+ v1-only pane renders no change segments, §4.3). Pane cwd
429
+ (`foreground_cwd` ?? `cwd`) feeds the daemon-side pull marker (§5.3).
430
+ Foreign `pi_subagents_work_v1` / `state_*` / `title_*` are observed only to
431
+ ignore them under O1 (never parsed for state, never deleted).
432
+
433
+ ### 5.2 Reducer (priority order, first match wins)
434
+
435
+ ```text
436
+ error := herdr:blocked has error:* (fresh, §5.4)
437
+ ask := fresh `gentle_ask_v1` (durable per-beat token, §4.3)
438
+ OR herdr:blocked has ask:* (fresh)
439
+ review := herdr:blocked has review:* (fresh)
440
+ principalWorking := fresh gentle_principal_v1 (session-bound, TTL-fresh) —
441
+ the principal's OWN activity, never the delegate count and
442
+ never the aggregate native status (which reads working for
443
+ any running delegate, pending launch, or live job); renders
444
+ `orchestrating` while a fresh gentle_orchestrating_v1 is
445
+ live, otherwise working(main); outranks every delegate role
446
+ word; stale, foreign, or absent falls through to the
447
+ branches below
448
+ role := gentle_work_v1 fresh AND gentle_roles_v1 yields a
449
+ recognized role (oldest first, incl. the in-flight pending
450
+ role hint at count = 0 for task-mode launches with no
451
+ TaskStore record yet) — the principal is not working, so the
452
+ delegate word wins; role labels append the total when at
453
+ least two delegates run. Tool-only review has no suffix.
454
+ orchestrating := gentle_orchestrating_v1 fresh with no role word above
455
+ (root-only per §4.2: fresh while the main session actively
456
+ works, even with zero subagents, retaining running/queued-sub
457
+ or pending-launch coverage; absent/stale falls through to the
458
+ branches below; attention, terminal `done`/native-`blocked`,
459
+ a working principal, and role words stay higher)
460
+ working(main) := gentle_work_v1 fresh AND count > 0 with no role word
461
+ OR (gentle_work_v1 fresh AND count = 0 AND agent not settled)
462
+ done := native done AND gentle_work_v1 fresh with count = 0
463
+ (no running delegates) AND no roles AND no fresh
464
+ gentle_orchestrating_v1 — count 0 alone never implies
465
+ empty, since the running-only count excludes queued subs
466
+ the fresh marker still covers; a fresh marker or any roles
467
+ veto terminal (queued cover, pending-launch hint)
468
+ idle := otherwise (native fallback; also all-gentle-tokens-missing-or-expired)
469
+ ```
470
+
471
+ Priority: `error > ask > review > done > principal working > role > orchestrating > working(main) > idle`.
472
+ `blocked` labels are namespaced, so simultaneous
473
+ `ask:` + `review:` resolves deterministically to `ask`. Attention states
474
+ (error/ask/review) and the terminal `done` state always outrank principal
475
+ status and activity roles. Below them the principal's own activity decides,
476
+ never the delegate count and never the aggregate native status: a **working
477
+ principal** renders `gentle` (pink
478
+ `orchestrating` while a fresh root marker is live) and outranks every
479
+ delegate role word; an **idle principal** shows the oldest running role word
480
+ (`explorer`, `worker`, `verify`, `judge`, or `rdd` when it is the oldest)
481
+ however many delegates run. The fresh marker is not a principal-working
482
+ signal (it stays live while the principal is idle with queued or running
483
+ delegates), so it never outranks a role word. An in-flight attention `review`
484
+ (fresh `review:` label or durable `gentle_review_v1` token) overrides the
485
+ role list; a settled session renders `done` even against a stale-fresh
486
+ marker.
487
+
488
+ ### 5.3 Publication (sidebar tokens)
489
+
490
+ - The consumer publishes its reduced state under `gentle_`-prefixed token
491
+ names only (never bare `state_*`/`title_*`). The visible first row is
492
+ native and carries no plugin wiring: `state_icon`, `workspace`, `agent`
493
+ in that order as plain native token strings. Row-1 glyph and identity
494
+ coloring, including the native `state_icon`, is Herdr-native and not
495
+ plugin-controlled, so no plugin icon/color claim is made for row 1. The
496
+ custom `$gentle_heading_*` / `$gentle_project` / `$gentle_agent` cells
497
+ stay published and owned for compatibility but are wired into no visible
498
+ row. Deleted lines stay red and added lines stay green (never swapped).
499
+ The visible second row is structural, with no rules: the eleven
500
+ presence-encoded
501
+ `gentle_title_<working|orchestrating|explorer|worker|verify|judge|ask|review|error|done|idle>`
502
+ state tokens (state word only: `working` / `gentle` (machine key
503
+ `orchestrating`) / `explorer` / `worker` /
504
+ `verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review`;
505
+ role words carry a running-count suffix above one).
506
+ Only the current display's title token carries a value; the rest are null.
507
+ Each state cell carries its state's semantic color as its base fg with
508
+ no rules — working/worker golden `#f9e2af`, orchestrating pink fuchsia
509
+ `#f5c2e7`, explorer blue `#89b4fa`, verify teal `#94e2d5`, judge purple
510
+ `#cba6f7` (distinct from explorer blue, verify teal, orchestrating pink),
511
+ ask orange `#fab387`, blocked red `#f38ba8`, done green `#a6e3a1`,
512
+ idle grey `#7c7f93` (recedes), review blue `#89b4fa` (same as
513
+ explorer/pull; internal TaskStore role slug stays `rdd`, machine display
514
+ key stays `review`). Native separators on row 2 are acceptable. The
515
+ `gentle_state_*` / `gentle_agent_*` / `gentle_icon_*` /
516
+ `gentle_row_*` combined names stay published for compatibility but are
517
+ not wired into any visible row. Sidebar config maps the native row-1
518
+ tokens plus the row-2 title and change-segment tokens to
519
+ the pi-only `rows_by_agent` override (E10); exact block wiring is
520
+ install configuration, not protocol.
521
+ - Label shapes: `gentle` (generic activity, machine key `working` — the
522
+ principal's own working state, as asserted by a fresh `gentle_principal_v1`,
523
+ with or without delegated roles; also a positive count with no role word, or only
524
+ unsalvageable role shapes) |
525
+ `gentle` (user-facing word for the `orchestrating` machine key — fresh
526
+ root-session marker while the principal works, with or without active
527
+ delegation, even with zero subagents; pink palette unchanged) | `explorer` / `worker` / `verify` / `judge` (oldest
528
+ TaskStore role word while the principal itself is idle, however many
529
+ delegates run) | `ask` | `rdd` (user-facing word for the `review`
530
+ machine key; a delegated rdd and a tool-only review both render `rdd` —
531
+ review execution is silent, never a notification; only
532
+ a waiting `ask` intent notifies once) | `blocked` (user-facing word for the `error`
533
+ machine key) | `done` (settled-plus-empty only: principal settled with no
534
+ running delegates and no pending launches; a settled principal with
535
+ running delegates keeps the role word) | `idle`. Role labels append the
536
+ total count when at least two delegates run.
537
+ - Row-2 changes: the nonempty `+N`/`-N`/`↑N` segments ride as their own
538
+ structural row-2 cells after the eleven title cells (each its own color
539
+ cell with no rules — added green, deleted red, pull blue, never
540
+ swapped; empty segments collapse so nothing renders). `+N`/`-N` come
541
+ from fresh `gentle_changes_v2`
542
+ (exact SessionChanges evidence totals, never git status); `↑N` (blue)
543
+ marks the pane branch behind its upstream. The pull marker is derived by the daemon from fixed-argv,
544
+ bounded `git status --porcelain=2 --branch` (the `# branch.ab` line
545
+ only — no shell, no diff, no fetch), cached/deduped per cwd over a short
546
+ TTL so panes sharing a worktree cost ~1 call per window. Any pull failure
547
+ resolves to absent (fail-closed).
548
+ - Each `+N`/`-N`/`↑N` segment renders only when its total is > 0; each
549
+ rides its own structural row-2 cell (added green, deleted red, pull
550
+ blue, no rules, never swapped; empty segments collapse). `gentle_project`,
551
+ `gentle_heading_*`, `gentle_agent` (both the single and per-display
552
+ forms), and `gentle_changes_summary` stay published for compatibility
553
+ but render no visible row. The retired
554
+ combined `~N`
555
+ badge is never emitted (see the §4.3 versioning rule).
556
+ - Placement: exactly two pi-only rows — row 1 the native `state_icon` +
557
+ `workspace` + `agent` strings (3 cells, no custom wiring, no plugin
558
+ colors), row 2 the eleven `gentle_title_*` state cells plus the three
559
+ change-segment cells (14 cells: 11 state + 3 changes), each row within
560
+ Herdr's 16-token per-row ceiling — with the
561
+ herdr-pi-tree palette (added green `#a6e3a1`,
562
+ removed red `#f38ba8`, pull blue `#89b4fa`, working golden `#f9e2af`, ask
563
+ orange `#fab387`, orchestrating pink fuchsia `#f5c2e7`, explorer/rdd blue `#89b4fa` (same color; internal role slug stays `rdd`,
564
+ visible word is `rdd`, machine key stays `review`), judge purple `#cba6f7` (distinct),
565
+ blocked/error red `#f38ba8`,
566
+ done green `#a6e3a1`, idle grey `#7c7f93` (recedes)). The rows stay pi-keyed (pi-only by
567
+ intent); each row value still carries the snapshot-provided identity,
568
+ with no vendor colors invented. The consumer never emits `↳` (O4).
569
+
570
+ ### 5.4 Freshness
571
+
572
+ A signal is *fresh* iff its token parses (§4.3) and `expiry > now`. Stale or
573
+ unparseable signals are dropped individually (one bad token never poisons the
574
+ other two). All gentle signals stale/missing → `idle` (native fallback, O5).
575
+
576
+ ## 6. Failure, retry, idempotency
577
+
578
+ - Delivery is at-least-once snapshots over an unreliable beat: producer
579
+ re-emits full pane state every beat; consumer reduces the latest snapshot.
580
+ There is no commit/ack; a timeout or lost report never implies the pane
581
+ stopped — only TTL expiry changes the reduced state.
582
+ - Retry: producer retries a failed `report_metadata` via CLI fallback once
583
+ per beat, then drops the beat (next beat re-sends full state). No unbounded
584
+ queue; no backlog replay past TTL.
585
+ - Duplicate suppression: identical consecutive snapshots are a no-op for the
586
+ consumer (no sidebar rewrite; desktop toasts are Herdr's native
587
+ edge-triggered semantics, never re-fired by the plugin).
588
+ - Idempotency keys: ask intents carry `intentId` (`ask:<intentId>`); review
589
+ spans carry `reviewId`. Re-emitting the same intent is safe; a new intent
590
+ id is a new sidebar ask episode (and a new native toast edge). The
591
+ `intentId` doubles as the Moshi `approval_required` action id when the
592
+ phone channel is enabled (§7).
593
+ - Error containment: transport failure surfaces as `herdr:blocked`
594
+ `error:<code>` (itself a token, subject to the same TTL), never as an
595
+ exception path that stops the producer beat. `error` state clears only on a
596
+ fresh non-error snapshot, not on silence.
597
+ - No exactly-once end-to-end claim: at-least-once beats + TTL expiry is the
598
+ engineered scope (consistent with the async/events guidance: never claim
599
+ exactly-once without a deliberate mechanism). Desktop toast dedup is
600
+ Herdr's native edge-triggered semantics; the phone channel dedups
601
+ per ask episode producer-side (§7).
602
+
603
+ ## 7. Notification ownership (native desktop, plugin phone)
604
+
605
+ - Desktop attention is native Herdr exclusively: `Blocked` fires the
606
+ `NeedsAttention` toast (`<agent> needs attention`, request sound) and a
607
+ background `Working|Blocked → Idle` transition fires the `Finished` toast
608
+ (`<agent> finished`, done sound), both with Herdr's own focus-aware
609
+ suppression and delay. The consumer daemon emits `herdr notification` for
610
+ nothing — since v0.3.1 it owns no toast path: its former ask toast fired on
611
+ the poll after the native one for the same question, a systematic
612
+ duplication. The ask token still drives the sidebar ask display; sounds,
613
+ suppression, and delay stay Herdr's.
614
+ - `review` and `error` never emit a plugin notification: `review` attention
615
+ stays in-flow/native; `error` is visible as sidebar state (native `blocked`
616
+ attention on `herdr:blocked` already fires per E9 — the plugin adds no
617
+ toast path).
618
+ - Optional Moshi replacement (off by default): one flag file,
619
+ `gentle-moshi.json` in the plugin state root, holding
620
+ `{"enabled":true}` and re-read per event by the producer extension. While
621
+ `extensions/moshi-hooks.ts` is installed, enabling also means adding
622
+ `-extensions/moshi-hooks.ts` to the Pi settings `extensions` list by hand so
623
+ the Moshi-managed hook cannot notify in parallel; that edit preserves every
624
+ other key and entry and is reverted by removing the entry again. With it
625
+ on, the producer extension replaces the Moshi-managed Pi hook entirely: it
626
+ speaks the same wire protocol (category-less `session.update` carriers plus
627
+ categorized events over the Moshi daemon socket), so Chat View, Live
628
+ Activity, the session row, the terminal context and Moshi's own approval
629
+ routing keep working, while notifications follow this plugin's policy —
630
+ `approval_required` once per real ask episode (`actionId` = the ask
631
+ `intentId`, subtitle `Answer in terminal`, title `Gentle ask: <project>`,
632
+ message `<project> has a question and is waiting for your answer. Return
633
+ to Pi to respond.`) and
634
+ `task_complete` once per real finish (the native transition into `idle`:
635
+ settled plus zero running/queued plus zero pending plus zero live
636
+ background jobs plus no human wait),
637
+ never per prompt and never per turn. A `session.closed` (`session_ended`)
638
+ envelope closes the row on shutdown, and the host-awaited handler flushes
639
+ in-flight sends. `task_complete` carries title `Gentle finished: <project>`
640
+ and names the last finished task: `<project> finished — <label>. Return to
641
+ Pi for what's next.`, falling back to `<project> finished and is waiting
642
+ for your next instruction.` with no tracked task. `<label>` is the most
643
+ recent completed/cancelled TaskStore label only — short work names,
644
+ sanitized and bounded to 80 characters, failing closed to the fallback;
645
+ never ids, paths, or prompt content. `<project>` here is the
646
+ multiplexer-session/cwd name (the extension never sees the Herdr workspace
647
+ group), failing closed to `Gentle`. Lineage child sessions (transcript header
648
+ `parentSession`/`parentSessionId`) are never published. Enabling mid-session
649
+ still opens the row: the carrier is sent on demand, once per session.
650
+ `enable`/`disable` also add/remove the `-extensions/moshi-hooks.ts` entry
651
+ in the Pi `settings.json` `extensions` list so the original hook cannot
652
+ notify in parallel (and is restored on disable); both settings edits happen
653
+ only while `extensions/moshi-hooks.ts` exists, preserve every other key and
654
+ entry, write atomically, and fail closed on an unreadable or invalid
655
+ settings file (reported, never rewritten). The consumer daemon never
656
+ publishes to Moshi (single emitter). Moshi owns pairing and credentials
657
+ (host secret in its own store); the plugin never reads or stores a token,
658
+ and an absent daemon or unpaired host is a silent no-op that never
659
+ interrupts Pi. `review` and `error` never notify. Limits (host-owned,
660
+ unverified): the phone-side approval round-trip through Moshi's TUI bridge,
661
+ the Live Activity lifecycle, and whether a `task_complete` renders as a
662
+ separate banner or only updates a running Live Activity are Moshi's.
663
+ - The flag is re-read per event, so flipping it silences or activates our
664
+ sender immediately; a settings-exclusion edit only takes effect on the next
665
+ Pi extension load, so a running session needs `/reload` after that one edit.
666
+ Fresh sessions are single-emitter by construction (exclusion entry + flag).
667
+ - Gentle mode is enabled by default: while selected, the gentle producer is the single publisher of native `pane.report_agent` (`working`/`blocked`/`idle`) alongside its metadata beats (session path-or-id binding, monotonic seq seeded from the clock as
668
+ `Date.now() * 1000` exactly like Herdr's own plugin SDK, serial latest-wins
669
+ coalesced queue, bounded retries; never `done`/`finished`, never a
670
+ notification method). The clock seed is load-bearing: Herdr ignores a report
671
+ whose `seq` loses to the stored one, so a zero-based counter makes every
672
+ report after a Pi restart or `/new` (both recreate the extension runtime)
673
+ lose, freezing the pane's `agent_session` binding at the old session while
674
+ the producer keeps beating for the new one — the consumer then rejects those
675
+ fresh tokens as a session-hash mismatch and the pane stays on `idle` until a
676
+ report with a higher seq lands. Parity contract: `working` carries the specific working role in the message (oldest running role word from the same roles resolution — known short word, unknown sanitized name, or `gentle` with no delegation; never bare generic `working`; machine keys unchanged); terminal `idle` only on a truly empty settle (principal settled plus zero running/queued plus zero pending plus zero live background jobs plus no human-wait prompt; settle-with-delegates/pending/jobs stays `working`, emitted once with no re-emit on repeat settles). Live background jobs come from Gentle Shell's own bus event `gentle-ai:jobs-sidebar` (`bash_background` / `monitor`), session-scoped; an absent Gentle Shell simply reports none (today's behavior). `blocked` only for a real principal-stopped error or an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent). The native status keeps its aggregate meaning (it reads `working` while any delegate runs, which is what Herdr's own pane state means): the sidebar row's working-vs-idle decision reads the principal-only `gentle_principal_v1` instead (§5.2), so an idle principal with a running delegate shows the delegate role word rather than `gentle`. Single publisher by design: the managed native extension file is excluded
677
+ reversibly (`-extensions/herdr-agent-state.ts` in Pi settings, bytes
678
+ preserved on disk, never auto-loaded next to ours). `node
679
+ bin/gentle-sidebar.js (enable|disable|status|toggle)` selects the
680
+ publisher: native gates
681
+ our producer/daemon, removes only our ownership-bound native exclusion and
682
+ managed sidebar rows, and reports that the running session needs `/reload`
683
+ (the exclusion and the native sidebar only take effect on the next Pi
684
+ extension load). Its shared
685
+ `gentle-sidebar-mode.json` uses `{version:1,enabled:boolean}`; missing means
686
+ enabled, malformed fails closed. Never run both publishers on the same pane
687
+ (dual publishers collide). See [docs/sidebar-control.md](docs/sidebar-control.md). Limits (unverified, host-owned): the host `idle`->`done`->`finished` mapping (finished text, toast/sound) and unknown-state handling are owned by Herdr.
688
+
689
+ ### Command surface
690
+
691
+ The package ships one CLI switch command,
692
+ `node bin/gentle-sidebar.js (enable|disable|status|toggle)` (§7), and one in-Pi
693
+ command, `/herdr-gentle:customize`, with exactly two switches: the managed
694
+ sidebar agent rows and the Moshi notification channel. The command registers
695
+ before the `enabled()` pane gate, so both switches stay reachable from a plain
696
+ Pi session outside a Herdr pane. It owns no state of its own and reimplements
697
+ nothing:
698
+
699
+ - `Sidebar agent rows` drives the Herdr plugin's own `bin/configure.js` —
700
+ `--check` to read the current state, `--apply --reload` /
701
+ `--uninstall --reload` to change it — and re-reads `--check` as the
702
+ completion proof. The extension never edits the Herdr config itself.
703
+ - `Moshi notifications` writes `gentle-moshi.json` and, while
704
+ `extensions/moshi-hooks.ts` is installed, adds or removes the
705
+ `-extensions/moshi-hooks.ts` entry in Pi's `settings.json`. Enabling runs the
706
+ `moshi-hook` prerequisite gate first (exact-name PATH scan plus
707
+ `moshi-hook status --json` reporting `paired: true`) and a refusal writes
708
+ nothing at all; disabling skips the gate. Pi is reloaded only when the
709
+ settings entry actually changed, because that entry is the only part that
710
+ waits for the next Pi extension load.
711
+
712
+ `/herdr-gentle:customize status` prints one read-only line; an unknown
713
+ argument, Esc, or a cancelled menu writes nothing. With no argument the
714
+ command opens the recovered floating two-pane panel
715
+ (`lib/customize-panel.js`, painted through its own palette)
716
+ over `ctx.ui.custom`: `←/→` or `Tab` moves between the category and value panes,
717
+ `↑/↓` or `j/k` moves the cursor, `Enter` toggles the focused switch and `Esc`
718
+ closes without a write. Each switch renders exactly one row that reads its
719
+ stored state and carries the opposite value, so `Enter` is the whole toggle.
720
+ An inconclusive sidebar verdict (`unknown`) renders as `Unknown` with a note
721
+ instead of hiding the row: toggling still attempts the repair and reports the
722
+ apply step's own error, exactly like the menu. The plain
723
+ two-step `ctx.ui.select` menu remains the
724
+ fallback when the TUI helpers or `ctx.ui.custom` are unavailable. The removed
725
+ `Plugin tools` and `Reset` sections and the in-process provider slot
726
+ `globalThis[Symbol.for("herdr-gentle.customize.v1")]` are not restored: they
727
+ switched worktree/ODD/issues surfaces this package no longer contains, so
728
+ exactly one mechanism writes each piece of state.
729
+
730
+ ## 8. Limits
731
+
732
+ - Token budget: ≤ 16 tokens per report per pane (E8 discipline); the
733
+ producer emits at most 10 tokens per beat (including the retired-token clear) (`gentle_work_v1`,
734
+ `gentle_roles_v1`, `gentle_names_v1`,
735
+ `gentle_orchestrating_v1`, `gentle_principal_v1`,
736
+ `gentle_ask_v1`, `gentle_review_v1`, `gentle_changes_v2`,
737
+ `gentle_changes_v1`) and the daemon publishes its 72-token owned family
738
+ chunked ≤ 16 per report (row 1 is the 3 native tokens
739
+ `state_icon`/`workspace`/`agent`; the legacy 11 `gentle_heading_*` compat
740
+ family stays published but wired into no visible row. Row 2 wires 11
741
+ title + 3 change cells = 14 — each within the per-row ceiling). Names are
742
+ advisory; roles are authoritative for display and role labels carry the
743
+ running total as a suffix when at least two delegates run.
744
+ - TTL: `expiry <= now + 60000` at write; readers use `now` at read.
745
+ Clock skew assumption ≤ 5 s (documented; not compensated).
746
+ - Field bounds: `count` ≤ 16 digits; `label` ≤ 64 chars; names/roles
747
+ CSV totals ≤ 512 UTF-8 bytes each; `intentId`/`reviewId`/`code` ≤ 64 chars,
748
+ `[A-Za-z0-9_-]+`.
749
+ - Poll cadence: resolved — must be ≪ 60 s TTL to avoid flapping
750
+ (see §10 U2). The daemon runs an adaptive poll (10 s baseline,
751
+ `GENTLE_STATUS_POLL_MS`-overridable, 2 s fast cycle
752
+ (`GENTLE_STATUS_FAST_POLL_MS`) while recent ask activity or send/publish
753
+ failures are observed, recovering after N quiet frames
754
+ (`GENTLE_STATUS_FAST_QUIET_FRAMES`) or a TTL-bounded window
755
+ (`GENTLE_STATUS_FAST_WINDOW_MS`), 250 ms floor, single dynamic
756
+ `setTimeout` chain.
757
+ The four lifecycle hooks (`pane.agent_detected`, `pane.agent_status_changed`,
758
+ `pane.exited`, `pane.closed`) each run `node bin/gentle-status.js --refresh`
759
+ (daemon ensure plus one coalesced immediate frame), not the cadence itself;
760
+ `[[startup]]` (no args) remains the polling-daemon bootstrap and polling
761
+ remains the fallback for every lifecycle signal.
762
+ - Scale: one producer per Pi pane; one consumer daemon per host; no
763
+ cross-pane aggregation in v1.
764
+
765
+ ## 9. Compatibility and migration
766
+
767
+ - Additive only in v1: new token names (`gentle_work_v1`,
768
+ `gentle_roles_v1`, `gentle_names_v1`,
769
+ `gentle_orchestrating_v1`, `gentle_principal_v1`,
770
+ `gentle_ask_v1`, `gentle_review_v1`, `gentle_changes_v1`, `gentle_changes_v2`,
771
+ `gentle_state_*`, `gentle_title_*`, `gentle_agent_*`, `gentle_agent`,
772
+ `gentle_icon_*`,
773
+ `gentle_heading_*`, `gentle_project`, `gentle_row_*` (each family now
774
+ includes the `judge` display alongside the original ten), plus display-only
775
+ `gentle_changes_added`, `gentle_changes_deleted`,
776
+ `gentle_changes_pull`, `gentle_changes_summary`); no change to `pi_subagents_work_v1`, `state_*`,
777
+ `title_*`, or native `working`/`blocked`/`idle` semantics.
778
+ `gentle_title_error` keeps its machine-key-derived token name; only its
779
+ user-facing value is `blocked` (§5.3). `gentle_title_review` likewise
780
+ keeps its machine-key-derived token name; only its user-facing value is
781
+ now `rdd` (aligned from `review` by the native-owner T1). `gentle_title_orchestrating` likewise keeps its machine-key-derived
782
+ token name; only its user-facing value is `gentle`. The retired `*_working_subs` token family (the old `working (n)`
783
+ count display) is swept, never written.
784
+ - Coexistence: `herdr-pi-tree` stays installed but disabled for gentle-owned
785
+ panes (O1). No uninstall, no token migration, no dual-run merge — ownership
786
+ handoff is by enable/disable switch, reversible at any time.
787
+ - Removed surfaces: the worktree tools (`worktree_create` / `worktree_list` /
788
+ `worktree_close` / `worktree_session_open` / `worktree_warp`), the warp
789
+ panel, the ODD and Issues readers, and the `Plugin tools` toggles no longer
790
+ ship. This package publishes the Herdr producer sidecar and the Moshi channel
791
+ only; `bin/gentle-sidebar.js` is its one CLI and `/herdr-gentle:customize`
792
+ its one in-Pi command, carrying just the sidebar-rows and Moshi switches.
793
+ Its provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]` stays
794
+ removed, so no other extension renders those two switches.
795
+ - Rollback: disable this plugin → producer stops writing; consumer sweeps
796
+ only `gentle_*` tokens + labels it set (O5); pi-tree re-enable restores
797
+ `↳N` behavior with zero data migration.
798
+ - Future breaking changes (grammar change, TTL change, badge-slot change)
799
+ require a new token version suffix (`_v2`) with a dual-emit period; old
800
+ names are removed only after observed zero-read evidence. Token-name
801
+ versioning (not sidebar-config versioning) is the compatibility mechanism.
802
+ - Packaging (two-package split): the repository ships two independently
803
+ versioned packages — the Pi package at the repository root (published to
804
+ npm as `herdr-gentle-shell`, installed with
805
+ `pi install`, updated with `pi update --extensions`) and the Herdr plugin
806
+ in `herdr-plugin/` (installed with `herdr plugin install
807
+ jonasotoaguilar/herdr-gentle-agents/herdr-plugin`, updated with
808
+ `herdr plugin update herdr-gentle-shell`). Releases run on two tag
809
+ series, `pi-vX.Y.Z` and `herdr-vX.Y.Z`; the Herdr side is not bumped when
810
+ it carries no change. The old managed-copy install (the installer copying
811
+ `extensions/gentle-herdr-state.ts` into the Pi agent dir) is retired: the
812
+ installer installs both packages and migrates an owned legacy copy aside.
813
+ Ownership split: the Pi package owns the Pi-side helpers (the extension,
814
+ the exclusion helper, the sidebar bridge); the Herdr plugin owns the
815
+ runtime Herdr consumes (manifest, daemon, configure, diagnostics, token
816
+ contract). Cross-package calls resolve the installed plugin root through
817
+ `herdr plugin list --json`, never through a repo-relative path.
818
+
819
+ ## 10. Unresolved decisions (do not implement against guesses)
820
+
821
+ - **U1. Notification CLI + dedup:** resolved (v0.3.1 — the consumer emits no
822
+ toast, so its CLI syntax is moot). Herdr-side semantics verified in source
823
+ (`notification_toast_for_state_change`): edge-triggered per state change,
824
+ `Blocked → NeedsAttention`, background `Working|Blocked → Idle` →
825
+ `Finished`, focus-aware suppression, global delivery switch only (no
826
+ per-agent mute, no plugin veto).
827
+ - **U2. Event catalog + poll cadence:** full `[[events]]` catalog of the
828
+ plugin host and the daemon's snapshot poll cadence (must be ≪ TTL).
829
+ Resolved: `pane.agent_detected`, `pane.agent_status_changed`, `pane.exited`,
830
+ and `pane.closed` — all confirmed in the installed 0.9.4 schema (T1 probe)
831
+ — each invoke `node bin/gentle-status.js --refresh` (L6: daemon ensure
832
+ plus one coalesced immediate frame, never a second writer loop), while
833
+ `[[startup]]` (no args) remains the polling-daemon bootstrap and polling
834
+ remains the fallback for every lifecycle signal. `--once` keeps its
835
+ existing one-frame public behavior for manual use and is not wired as a
836
+ hook. Runtime proofs of the `--refresh` contract belong to the lifecycle
837
+ unit's tests, not this protocol record.
838
+ - **U3. pi-tree producer file:** which file in `herdr-pi-tree` emits
839
+ `pi_subagents_work_v1` (only `lib/state.js` consumers were traced); needed
840
+ to confirm no shared writer path.
841
+ - **U4. Review-in-progress matcher — RESOLVED (task 8), narrowed (L2, corrected):** Pi in-process `tool_execution_start` opens / `tool_execution_end` / `tool_result` closes (by `toolCallId`; a `tool_call` proposal alone never opens) for the exact tools `gentle_review_capture`, `gentle_review_capture_group` (G5) with `reviewerRunAcknowledged: true` in the runtime args — the sole reviewer-capable predicate. `correctionLines` is native correction planning (captureCorrectionPlan), never a reviewer, and disqualifies (including combinations invalid upstream). Sidebar `reviewing` fires at any bound capture entry BEFORE the forecast branch, so no sidebar/event signal proves a legacy reviewer route: unknown legacy shapes stay dark (documented conservative limitation; bindings stay opaque, never parsed). The reserved `gentle-pi:review:blocked` hook has no producer and is not observed. `gentle_review` in any operation (inspect / status / start / ack / assess / select-intended-untracked), `gentle_review_scope`, and forecast-only calls never enter. Fail-safe semantics: `review:` label only while acknowledged capture/group execution is in flight; `reviewId` is a sanitized correlation id, never a provider verdict. During a capture-group run the single parent capture-group call stays in flight across the whole multi-reviewer span, so that one call alone holds `review:` — no per-reviewer tracking. The consumer renders this leg as user-facing `rdd` (machine key stays `review`); execution never implies human waiting and never notifies. Exact limitation: the acknowledged capture interval contains preparation and admission; no exact reviewer internal events exist today, so the span is a bounded approximation, never exact interval proof.
842
+ - **U5. Changes badge — RESOLVED (two-row contract):** the `±N` vs `~N`
843
+ selection no longer exists — the combined badge is retired in favor of
844
+ independent `+N`/`-N` segments from exact `gentle_changes_v2` added/deleted
845
+ totals, plus the daemon-side `↑N` pull marker (§5.3). The producer mirrors
846
+ the Gentle Shell `SessionChanges` model semantics over the same transcript
847
+ `SESSION_CHANGE_ENTRY` evidence (never git and never an approximate
848
+ reaggregation): files keyed by `(root, path)`, evidence-ID dedup,
849
+ identical before/after records skipped, first `before` preserved with
850
+ latest `after`, unavailable on broken snapshot continuity or any
851
+ `kind: unavailable` snapshot (unavailable files stay in the file count
852
+ with 0 added/0 deleted), and unified-patch line accounting for available
853
+ text/absent snapshots (absent maps to empty text for patch counts).
854
+ Remaining transport note: cross-process delivery of entry facts to the Pi
855
+ producer extension still rides the session transcript.
856
+ - **U6. Gentle source pin:** canonical `gentle-shell` checkout vs versioned
857
+ package pin the producer/consumer build against.
858
+
859
+ ## 11. Verification criteria (task 4 close)
860
+
861
+ Docs-only task: no test runner (TDD n/a). Verify by re-reading this file and
862
+ confirming each criterion has a normative section:
863
+
864
+ | # | Criterion (sidebar behavior) | Normative section |
865
+ |---|------------------------------|-------------------|
866
+ | V1 | Sidebar shows the active TaskStore role with live subagents | §4.2 (role source G3 + `gentle_roles_v1`), §5.2–§5.3 |
867
+ | V2 | Sidebar shows `ask` on open question | §4.2 (G4 → `ask:`), §5.2 priority, §7 notify-once |
868
+ | V3 | Sidebar shows `review` during native review | §4.2 (review tool lifecycle → `review:`, incl. capture-group parent call), §5.2 priority |
869
+ | V4 | Change segments render from Gentle session-changes | §4.2/§4.4 (`gentle_changes_v2`), §5.3 `+N`/`-N`/`↑N` |
870
+ | V5 | No collision with pi-tree `↳N` / `state_*` names | §3 O1/O2/O4, §9 rollback |
871
+ | V6 | Stale panes fall back to `idle`, orphans swept on handover | §3 O5, §5.4, §6 |
872
+
873
+ Task closes when V1–V6 are all traceable above and the file re-read reports
874
+ path + line count. Any untraceable cell → `status: partial` with the gap
875
+ list, not silent.