herdr-gentle-shell 0.0.0-stage → 1.0.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 +876 -0
- package/LICENSE +21 -0
- package/README.md +460 -2
- package/bin/.gitkeep +0 -0
- package/bin/gentle-sidebar.js +53 -0
- package/docs/diagnostics.md +64 -0
- package/docs/herdr-session-open.md +160 -0
- package/docs/images/banner.png +0 -0
- package/docs/images/sidebar-example.png +0 -0
- package/docs/performance-trace.md +287 -0
- package/docs/sidebar-control.md +88 -0
- package/docs/supervision.md +96 -0
- package/extensions/.gitkeep +0 -0
- package/extensions/gentle-herdr-state.ts +3891 -0
- package/extensions/herdr-session-open.ts +399 -0
- package/lib/.gitkeep +0 -0
- package/lib/customize-panel.js +541 -0
- package/lib/gentle-sidebar.js +384 -0
- package/lib/herdr-session-notifications.js +320 -0
- package/lib/herdr-session-open.js +664 -0
- package/lib/host-settings.js +70 -0
- package/lib/perf-analyze.js +332 -0
- package/lib/perf-trace.js +684 -0
- package/lib/pi-extension-exclusion.js +405 -0
- package/package.json +39 -4
package/DESIGN.md
ADDED
|
@@ -0,0 +1,876 @@
|
|
|
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-shell/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 repository ships no install script: the
|
|
811
|
+
documented path is the two plain package installs above. The old
|
|
812
|
+
managed-copy install (copying `extensions/gentle-herdr-state.ts` into the
|
|
813
|
+
Pi agent dir) is retired and needs no migration step of its own.
|
|
814
|
+
Ownership split: the Pi package owns the Pi-side helpers (the extension,
|
|
815
|
+
the exclusion helper, the sidebar bridge); the Herdr plugin owns the
|
|
816
|
+
runtime Herdr consumes (manifest, daemon, configure, diagnostics, token
|
|
817
|
+
contract). Cross-package calls resolve the installed plugin root through
|
|
818
|
+
`herdr plugin list --json`, never through a repo-relative path.
|
|
819
|
+
|
|
820
|
+
## 10. Unresolved decisions (do not implement against guesses)
|
|
821
|
+
|
|
822
|
+
- **U1. Notification CLI + dedup:** resolved (v0.3.1 — the consumer emits no
|
|
823
|
+
toast, so its CLI syntax is moot). Herdr-side semantics verified in source
|
|
824
|
+
(`notification_toast_for_state_change`): edge-triggered per state change,
|
|
825
|
+
`Blocked → NeedsAttention`, background `Working|Blocked → Idle` →
|
|
826
|
+
`Finished`, focus-aware suppression, global delivery switch only (no
|
|
827
|
+
per-agent mute, no plugin veto).
|
|
828
|
+
- **U2. Event catalog + poll cadence:** full `[[events]]` catalog of the
|
|
829
|
+
plugin host and the daemon's snapshot poll cadence (must be ≪ TTL).
|
|
830
|
+
Resolved: `pane.agent_detected`, `pane.agent_status_changed`, `pane.exited`,
|
|
831
|
+
and `pane.closed` — all confirmed in the installed 0.9.4 schema (T1 probe)
|
|
832
|
+
— each invoke `node bin/gentle-status.js --refresh` (L6: daemon ensure
|
|
833
|
+
plus one coalesced immediate frame, never a second writer loop), while
|
|
834
|
+
`[[startup]]` (no args) remains the polling-daemon bootstrap and polling
|
|
835
|
+
remains the fallback for every lifecycle signal. `--once` keeps its
|
|
836
|
+
existing one-frame public behavior for manual use and is not wired as a
|
|
837
|
+
hook. Runtime proofs of the `--refresh` contract belong to the lifecycle
|
|
838
|
+
unit's tests, not this protocol record.
|
|
839
|
+
- **U3. pi-tree producer file:** which file in `herdr-pi-tree` emits
|
|
840
|
+
`pi_subagents_work_v1` (only `lib/state.js` consumers were traced); needed
|
|
841
|
+
to confirm no shared writer path.
|
|
842
|
+
- **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.
|
|
843
|
+
- **U5. Changes badge — RESOLVED (two-row contract):** the `±N` vs `~N`
|
|
844
|
+
selection no longer exists — the combined badge is retired in favor of
|
|
845
|
+
independent `+N`/`-N` segments from exact `gentle_changes_v2` added/deleted
|
|
846
|
+
totals, plus the daemon-side `↑N` pull marker (§5.3). The producer mirrors
|
|
847
|
+
the Gentle Shell `SessionChanges` model semantics over the same transcript
|
|
848
|
+
`SESSION_CHANGE_ENTRY` evidence (never git and never an approximate
|
|
849
|
+
reaggregation): files keyed by `(root, path)`, evidence-ID dedup,
|
|
850
|
+
identical before/after records skipped, first `before` preserved with
|
|
851
|
+
latest `after`, unavailable on broken snapshot continuity or any
|
|
852
|
+
`kind: unavailable` snapshot (unavailable files stay in the file count
|
|
853
|
+
with 0 added/0 deleted), and unified-patch line accounting for available
|
|
854
|
+
text/absent snapshots (absent maps to empty text for patch counts).
|
|
855
|
+
Remaining transport note: cross-process delivery of entry facts to the Pi
|
|
856
|
+
producer extension still rides the session transcript.
|
|
857
|
+
- **U6. Gentle source pin:** canonical `gentle-shell` checkout vs versioned
|
|
858
|
+
package pin the producer/consumer build against.
|
|
859
|
+
|
|
860
|
+
## 11. Verification criteria (task 4 close)
|
|
861
|
+
|
|
862
|
+
Docs-only task: no test runner (TDD n/a). Verify by re-reading this file and
|
|
863
|
+
confirming each criterion has a normative section:
|
|
864
|
+
|
|
865
|
+
| # | Criterion (sidebar behavior) | Normative section |
|
|
866
|
+
|---|------------------------------|-------------------|
|
|
867
|
+
| V1 | Sidebar shows the active TaskStore role with live subagents | §4.2 (role source G3 + `gentle_roles_v1`), §5.2–§5.3 |
|
|
868
|
+
| V2 | Sidebar shows `ask` on open question | §4.2 (G4 → `ask:`), §5.2 priority, §7 notify-once |
|
|
869
|
+
| V3 | Sidebar shows `review` during native review | §4.2 (review tool lifecycle → `review:`, incl. capture-group parent call), §5.2 priority |
|
|
870
|
+
| V4 | Change segments render from Gentle session-changes | §4.2/§4.4 (`gentle_changes_v2`), §5.3 `+N`/`-N`/`↑N` |
|
|
871
|
+
| V5 | No collision with pi-tree `↳N` / `state_*` names | §3 O1/O2/O4, §9 rollback |
|
|
872
|
+
| V6 | Stale panes fall back to `idle`, orphans swept on handover | §3 O5, §5.4, §6 |
|
|
873
|
+
|
|
874
|
+
Task closes when V1–V6 are all traceable above and the file re-read reports
|
|
875
|
+
path + line count. Any untraceable cell → `status: partial` with the gap
|
|
876
|
+
list, not silent.
|