herdr-gentle-shell 1.6.1 → 1.7.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 CHANGED
@@ -154,13 +154,13 @@ an explicit writer-ownership decision. Rationale follows each choice.
154
154
  absent under single-writer handoff (O1). Gentle renders exactly two rows
155
155
  for the `pi` agent: row 1 is the heading context as exactly one active
156
156
  cell — the active `gentle_heading_*` value holds `<icon> <project>` plus
157
- compact nonempty changes segments (` +N`, ` -N`, ` ↑N`) in that same
158
- cell (e.g. `● myproj +110 -22 ↑3`). Exactly one row-1 cell is nonempty,
157
+ compact nonempty changes segments (` +N`, ` -N`) in that same
158
+ cell (e.g. `● myproj +110 -22`). Exactly one row-1 cell is nonempty,
159
159
  so Herdr inserts zero inter-cell `·` separators. The cell sits on white
160
160
  `#ffffff` (SIDEBAR_PROJECT) so the project text stays white; symbol
161
161
  `contains` rules recolor the icon (unchanged state mapping) plus ` +`
162
- green (added), ` -` red (deleted, leading-space match so hyphens inside
163
- project names never turn red), and ` ↑` blue (pull). `gentle_project`,
162
+ green (added), and ` -` red (deleted, leading-space match so hyphens inside
163
+ project names never turn red). `gentle_project`,
164
164
  `gentle_changes_summary`, and the change-segment tokens stay published
165
165
  and owned for compatibility but are wired into no visible row; row 2 is
166
166
  the agent context (the
@@ -208,7 +208,7 @@ Sidecar only: ships beside `herdr-agent-state.ts`, never modifies it.
208
208
  |---|---|---|
209
209
  | `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 | the pink `gentle` (machine key `orchestrating`, with or without a fresh root marker) while the principal session actively works, even with zero subagents |
210
210
  | TaskStore `running` non-empty (G3; queued/waiting never execute) | `gentle_work_v1=<hash>:<count>:<exp>` (total delegates — snapshot-confirmed running records plus distinct in-flight `subagent_run`/`subagent_continue` calls, §4.2 — 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 |
211
- | `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 `?`) |
211
+ | `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; and a prompt span the agent proves it is not waiting on never counts either — a top-level `tool_execution_start` (never a nested `codemode` call, which starts while a sibling dialog is still awaited) or an assistant `message_end` while the span is open withdraws it until `ui_prompt_end`, because a run genuinely blocked on its own dialog cannot also start new top-level executions or finish assistant messages, while a slash-command option menu such as `/rdd`, the `/warp` list or the `customize` fallback renders through `ctx.ui.select` and keeps the agent working; the host gives no origin signal, so entry stays immediate and only those two signals withdraw, never `tool_execution_update` — live background jobs emit it while a real ask may be open), 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 `?`) |
212
212
  | 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 |
213
213
  | the agent run itself stops on an error (an assistant message whose `stopReason` is `error` — the same signal Pi derives `turn_end.outcome === "error"` from) | durable `gentle_error_v1=<hash>:run-failed:<exp>` on every beat while the leg stands (null/clear the beat it releases, §4.3) + `herdr:blocked` label `error:run-failed`; no native state is derived from it (the pane stays on its lifecycle state — `working` — while the leg stands, so the host raises no NeedsAttention toast or sound) | `error` (row word `blocked`) — never a native `blocked` |
214
214
  | a tool call fails, a delegate record ends `failed`, or a beat transport fails | nothing — detection only (a counter and a debug line under `GENTLE_HERDR_DEBUG=1`) | nothing: no label, no native state, no finish hold, no notification |
@@ -483,7 +483,7 @@ explorers with count 3 → `explorer (3)`; 5 files
483
483
  `● myproj +110 -22` (` +` green for added, ` -` red for deleted with a
484
484
  leading-space match, zero `·` separators because exactly one heading cell
485
485
  is nonempty).
486
- A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer/pull). A
486
+ A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer). A
487
487
  `gentle_orchestrating_v1` marker renders the pink `gentle` (machine display
488
488
  key `orchestrating`, pink palette unchanged): it covers the principal's
489
489
  queued/running subs and pending launches, and it yields to a delegate role
@@ -579,8 +579,7 @@ display — repairs a missed `error:` label edge, §4.3),
579
579
  `gentle_roles_v1` (authoritative activity roles,
580
580
  oldest-first by immutable firstSeen), `gentle_names_v1` (compat transport only — never
581
581
  rendered), `gentle_changes_v2` (normative; a
582
- v1-only pane renders no change segments, §4.3). Pane cwd
583
- (`foreground_cwd` ?? `cwd`) feeds the daemon-side pull marker (§5.3).
582
+ v1-only pane renders no change segments, §4.3).
584
583
  Foreign `pi_subagents_work_v1` / `state_*` / `title_*` are observed only to
585
584
  ignore them under O1 (never parsed for state, never deleted).
586
585
 
@@ -706,7 +705,7 @@ cap has lapsed, does it recede to `idle` (§4.3).
706
705
  `#cba6f7` (distinct from explorer blue, verify teal, orchestrating pink),
707
706
  ask orange `#fab387`, blocked red `#f38ba8`, done green `#a6e3a1`,
708
707
  idle grey `#7c7f93` (recedes), review blue `#89b4fa` (same as
709
- explorer/pull; internal TaskStore role slug stays `rdd`, machine display
708
+ explorer; internal TaskStore role slug stays `rdd`, machine display
710
709
  key stays `review`). Native separators on row 2 are acceptable. The
711
710
  `gentle_state_*` / `gentle_agent_*` / `gentle_icon_*` /
712
711
  `gentle_row_*` combined names stay published for compatibility but are
@@ -735,20 +734,17 @@ cap has lapsed, does it recede to `idle` (§4.3).
735
734
  running delegates and no pending launches; a settled principal with
736
735
  running delegates keeps the role word) | `idle`. Role labels append the
737
736
  total count when at least two delegates run.
738
- - Row-2 changes: the nonempty `+N`/`-N`/`↑N` segments ride as their own
737
+ - Row-2 changes: the nonempty `+N`/`-N` segments ride as their own
739
738
  structural row-2 cells after the eleven title cells (each its own color
740
- cell with no rules — added green, deleted red, pull blue, never
739
+ cell with no rules — added green, deleted red, never
741
740
  swapped; empty segments collapse so nothing renders). `+N`/`-N` come
742
741
  from fresh `gentle_changes_v2`
743
- (exact SessionChanges evidence totals, never git status); `↑N` (blue)
744
- marks the pane branch behind its upstream. The pull marker is derived by the daemon from fixed-argv,
745
- bounded `git status --porcelain=2 --branch` (the `# branch.ab` line
746
- only — no shell, no diff, no fetch), cached/deduped per cwd over a short
747
- TTL so panes sharing a worktree cost ~1 call per window. Any pull failure
748
- resolves to absent (fail-closed).
749
- - Each `+N`/`-N`/`↑N` segment renders only when its total is > 0; each
750
- rides its own structural row-2 cell (added green, deleted red, pull
751
- blue, no rules, never swapped; empty segments collapse). `gentle_project`,
742
+ (exact SessionChanges evidence totals, never git status). The row carries
743
+ no ahead/behind marker relative to the branch: only the exact added and
744
+ deleted line counts.
745
+ - Each `+N`/`-N` segment renders only when its total is > 0; each
746
+ rides its own structural row-2 cell (added green, deleted red,
747
+ no rules, never swapped; empty segments collapse). `gentle_project`,
752
748
  `gentle_heading_*`, `gentle_agent` (both the single and per-display
753
749
  forms), and `gentle_changes_summary` stay published for compatibility
754
750
  but render no visible row. The retired
@@ -756,11 +752,11 @@ cap has lapsed, does it recede to `idle` (§4.3).
756
752
  badge is never emitted (see the §4.3 versioning rule).
757
753
  - Placement: exactly two pi-only rows — row 1 the native `state_icon` +
758
754
  `workspace` + `agent` strings (3 cells, no custom wiring, no plugin
759
- colors), row 2 the eleven `gentle_title_*` state cells plus the three
760
- change-segment cells (14 cells: 11 state + 3 changes), each row within
755
+ colors), row 2 the eleven `gentle_title_*` state cells plus the two
756
+ change-segment cells (13 cells: 11 state + 2 changes), each row within
761
757
  Herdr's 16-token per-row ceiling — with the
762
758
  herdr-pi-tree palette (added green `#a6e3a1`,
763
- removed red `#f38ba8`, pull blue `#89b4fa`, working golden `#f9e2af`, ask
759
+ removed red `#f38ba8`, working golden `#f9e2af`, ask
764
760
  orange `#fab387`, orchestrating pink fuchsia `#f5c2e7`, explorer/rdd blue `#89b4fa` (same color; internal role slug stays `rdd`,
765
761
  visible word is `rdd`, machine key stays `review`), judge purple `#cba6f7` (distinct),
766
762
  blocked/error red `#f38ba8`,
@@ -1057,11 +1053,11 @@ exactly one mechanism writes each piece of state.
1057
1053
  `gentle_orchestrating_v1`, `gentle_principal_v1`, `gentle_done_v1`,
1058
1054
  `gentle_ask_v1`, `gentle_review_v1`, `gentle_error_v1`,
1059
1055
  `gentle_changes_v2`,
1060
- `gentle_changes_v1`) and the daemon publishes its 72-token owned family
1056
+ `gentle_changes_v1`) and the daemon publishes its 71-token owned family
1061
1057
  chunked ≤ 16 per report (row 1 is the 3 native tokens
1062
1058
  `state_icon`/`workspace`/`agent`; the legacy 11 `gentle_heading_*` compat
1063
1059
  family stays published but wired into no visible row. Row 2 wires 11
1064
- title + 3 change cells = 14 — each within the per-row ceiling). Names are
1060
+ title + 2 change cells = 13 — each within the per-row ceiling). Names are
1065
1061
  advisory; roles are authoritative for display and role labels carry the
1066
1062
  running total as a suffix when at least two delegates run.
1067
1063
  - TTL: `expiry <= now + 60000` at write; readers use `now` at read.
@@ -1078,8 +1074,8 @@ exactly one mechanism writes each piece of state.
1078
1074
  (`GENTLE_STATUS_FAST_QUIET_FRAMES`) or a TTL-bounded window
1079
1075
  (`GENTLE_STATUS_FAST_WINDOW_MS`), 250 ms floor, single dynamic
1080
1076
  `setTimeout` chain. The active-display trigger exists because the row data
1081
- the daemon derives by itself — the `+N/-N` changes summary and the `↑N`
1082
- pull marker, read from local git plus `agent.list` — cannot be driven by a
1077
+ the daemon refreshes by a frame rather than from a producer report —
1078
+ `agent.list` plus the presence prefix — cannot be driven by a
1083
1079
  producer report; only `idle` counts as settled, so an idle pane keeps the
1084
1080
  baseline exactly.
1085
1081
  Drawing is event-synchronized; polling is only the fallback. Every landed
@@ -1112,10 +1108,9 @@ exactly one mechanism writes each piece of state.
1112
1108
  Shutdown closes the socket and its retry timer, and neither keeps the process
1113
1109
  alive. Idle cost with no events is exactly today's: an idle subscription is
1114
1110
  silent and the loop sleeps as before.
1115
- What the subscription can never drive stays poll-only: the row data the
1116
- daemon derives by itself — the `+N/-N` changes summary and the `↑N` pull
1117
- marker, read from local git plus `agent.list` — plus the presence prefix,
1118
- because Herdr emits no event for either. That is why the fast cycle is armed
1111
+ What the subscription can never drive stays poll-only: the daemon's own
1112
+ `agent.list` snapshot and the presence prefix, because Herdr emits no event
1113
+ for either. That is why the fast cycle is armed
1119
1114
  by a rendered non-idle display, and why polling is never removed.
1120
1115
  The sleep is also capped at the nearest live `gentle_done_v1` expiry AND the
1121
1116
  nearest pending view-dwell deadline (`DONE_VIEW_DWELL_MS`) among
@@ -1145,7 +1140,7 @@ exactly one mechanism writes each piece of state.
1145
1140
  `gentle_heading_*`, `gentle_project`, `gentle_row_*` (each family now
1146
1141
  includes the `judge` display alongside the original ten), plus display-only
1147
1142
  `gentle_changes_added`, `gentle_changes_deleted`,
1148
- `gentle_changes_pull`, `gentle_changes_summary`); no change to `pi_subagents_work_v1`, `state_*`,
1143
+ `gentle_changes_summary`); no change to `pi_subagents_work_v1`, `state_*`,
1149
1144
  `title_*`, or native `working`/`blocked`/`idle` semantics.
1150
1145
  `gentle_title_error` keeps its machine-key-derived token name; only its
1151
1146
  user-facing value is `blocked` (§5.3). `gentle_title_review` likewise
@@ -1155,7 +1150,9 @@ exactly one mechanism writes each piece of state.
1155
1150
  likewise keeps its machine-key-derived token name; its user-facing value is
1156
1151
  a non-contemplated subagent's own sanitized name, never the word `working`.
1157
1152
  The retired `*_working_subs` token family (the old `working (n)`
1158
- count display) is swept, never written.
1153
+ count display) is swept, never written. The retired
1154
+ `gentle_changes_pull` name (the removed behind-upstream `↑N` marker) is
1155
+ swept the same way, never written.
1159
1156
  - Coexistence: `herdr-pi-tree` stays installed but disabled for gentle-owned
1160
1157
  panes (O1). No uninstall, no token migration, no dual-run merge — ownership
1161
1158
  handoff is by enable/disable switch, reversible at any time.
@@ -1223,7 +1220,7 @@ exactly one mechanism writes each piece of state.
1223
1220
  - **U5. Changes badge — RESOLVED (two-row contract):** the `±N` vs `~N`
1224
1221
  selection no longer exists — the combined badge is retired in favor of
1225
1222
  independent `+N`/`-N` segments from exact `gentle_changes_v2` added/deleted
1226
- totals, plus the daemon-side `↑N` pull marker (§5.3). The producer mirrors
1223
+ totals, plus the daemon-side change cells (§5.3). The producer mirrors
1227
1224
  the Gentle Shell `SessionChanges` model semantics over the same transcript
1228
1225
  `SESSION_CHANGE_ENTRY` evidence (never git and never an approximate
1229
1226
  reaggregation): files keyed by `(root, path)`, evidence-ID dedup,
@@ -1247,7 +1244,7 @@ confirming each criterion has a normative section:
1247
1244
  | V1 | Sidebar shows the active TaskStore role with live subagents | §4.2 (role source G3 + `gentle_roles_v1`), §5.2–§5.3 |
1248
1245
  | V2 | Sidebar shows `ask` on open question | §4.2 (G4 → `ask:`), §5.2 priority, §7 notify-once |
1249
1246
  | V3 | Sidebar shows `review` during native review | §4.2 (review tool lifecycle → `review:`, incl. capture-group parent call), §5.2 priority |
1250
- | V4 | Change segments render from Gentle session-changes | §4.2/§4.4 (`gentle_changes_v2`), §5.3 `+N`/`-N`/`↑N` |
1247
+ | V4 | Change segments render from Gentle session-changes | §4.2/§4.4 (`gentle_changes_v2`), §5.3 `+N`/`-N` |
1251
1248
  | V5 | No collision with pi-tree `↳N` / `state_*` names | §3 O1/O2/O4, §9 rollback |
1252
1249
  | V6 | Stale panes fall back to `idle`, orphans swept on handover | §3 O5, §5.4, §6 |
1253
1250
 
package/README.md CHANGED
@@ -35,11 +35,14 @@ display untouched),
35
35
  executed `ask_user_question`/`ask_user_choice` tool calls (execution opens, end/result closes;
36
36
  proposals never block), tool-gated `ui_prompt` dialog spans (a `custom` panel — agents view, ODD
37
37
  viewer, changes view, design canvas — never counts: opening a panel is navigation, not a
38
- question), and
38
+ question; a span the agent proves it is not waiting on — a new top-level tool execution (never a
39
+ nested `codemode` call, which starts while a sibling dialog is still awaited) or a finished
40
+ assistant message arriving while it is open — never counts either, so a Gentle Shell command
41
+ menu opened mid-work leaves the row on the agent's real activity), and
39
42
  permission waiting; `gentle_review` starts never speculate ask, amber/orange `?`), `blocked`, `done`, `idle`) plus compact
40
- changes segments folded into the single row-1 heading cell (nonempty ` +N`/` -N`/` ↑N`
43
+ changes segments (nonempty ` +N`/` -N`
41
44
  with leading spaces, symbols color-distinguished by `contains` rules: ` +` green for added,
42
- ` -` red for deleted, ` ↑` blue for pull — added stays green, deleted stays red),
45
+ ` -` red for deleted — added stays green, deleted stays red),
43
46
  reduced from `gentle_*`
44
47
  pane-metadata tokens. It coexists with `herdr-pi-tree` through a single-writer handoff: while
45
48
  this plugin owns a pane, `herdr-pi-tree` stays disabled for that pane, so the
@@ -203,11 +206,11 @@ the native `state_icon`, is Herdr-native and not plugin-controlled); row 2
203
206
  wires the eleven presence-encoded `gentle_title_*` state cells (state word
204
207
  only, one current title per frame, each in its state's semantic color as
205
208
  base fg with no rules; role words carry a running-count suffix above one)
206
- followed by the three
207
- change-segment tokens (added green `+N`, deleted red `-N`, pull blue `↑N`,
209
+ followed by the two
210
+ change-segment tokens (added green `+N`, deleted red `-N`,
208
211
  each its own color cell with no rules, never swapped). The review leg
209
212
  renders the user-facing word `rdd` in blue `#89b4fa` (same as
210
- explorer/pull; internal TaskStore role slug stays `rdd`, machine display key
213
+ explorer; internal TaskStore role slug stays `rdd`, machine display key
211
214
  and token names stay `review` — review execution is silent, never a
212
215
  notification; only an actual waiting prompt renders `ask` (desktop attention
213
216
  is Herdr's native `blocked` toast); the judge delegate role renders `judge` in
@@ -231,8 +234,8 @@ for compatibility but are wired into no visible row.
231
234
  Only one `gentle_title_*` token carries a value per frame (presence
232
235
  encoding), so row 2 shows the current state word plus any nonempty change
233
236
  segments while the rest render empty; native separators on row 2 are
234
- acceptable. Row 1 holds 3 native cells and row 2 holds 14 cells (11 state
235
- + 3 changes), each within Herdr's 16-token per-row ceiling (full block below).
237
+ acceptable. Row 1 holds 3 native cells and row 2 holds 13 cells (11 state
238
+ + 2 changes), each within Herdr's 16-token per-row ceiling (full block below).
236
239
  The `gs` label of an isolated Gentle Shell pane needs no key here: `gs` is not
237
240
  one of Herdr's canonical agents, so `rows_by_agent.gs` is a configuration error
238
241
  rather than an inert key. Only the daemon's label ladder (DESIGN.md §5.5)
@@ -244,7 +247,7 @@ makes that row appear, and `rows_by_agent` stays keyed by the canonical `pi`.
244
247
  # row 1 native state_icon + workspace + agent, row 2 state word + changes.
245
248
  # The parent [ui.sidebar.agents] table is user-owned and never touched here.
246
249
  [ui.sidebar.agents.rows_by_agent]
247
- pi = [["state_icon", "workspace", "agent"], [{ token = "$gentle_title_working", fg = "#f9e2af" }, { token = "$gentle_title_orchestrating", fg = "#f5c2e7" }, { token = "$gentle_title_explorer", fg = "#89b4fa" }, { token = "$gentle_title_worker", fg = "#f9e2af" }, { token = "$gentle_title_verify", fg = "#94e2d5" }, { token = "$gentle_title_judge", fg = "#cba6f7" }, { token = "$gentle_title_ask", fg = "#fab387" }, { token = "$gentle_title_review", fg = "#89b4fa" }, { token = "$gentle_title_error", fg = "#f38ba8" }, { token = "$gentle_title_done", fg = "#a6e3a1" }, { token = "$gentle_title_idle", fg = "#7c7f93" }, { token = "$gentle_changes_added", fg = "#a6e3a1" }, { token = "$gentle_changes_deleted", fg = "#f38ba8" }, { token = "$gentle_changes_pull", fg = "#89b4fa" }]]
250
+ pi = [["state_icon", "workspace", "agent"], [{ token = "$gentle_title_working", fg = "#f9e2af" }, { token = "$gentle_title_orchestrating", fg = "#f5c2e7" }, { token = "$gentle_title_explorer", fg = "#89b4fa" }, { token = "$gentle_title_worker", fg = "#f9e2af" }, { token = "$gentle_title_verify", fg = "#94e2d5" }, { token = "$gentle_title_judge", fg = "#cba6f7" }, { token = "$gentle_title_ask", fg = "#fab387" }, { token = "$gentle_title_review", fg = "#89b4fa" }, { token = "$gentle_title_error", fg = "#f38ba8" }, { token = "$gentle_title_done", fg = "#a6e3a1" }, { token = "$gentle_title_idle", fg = "#7c7f93" }, { token = "$gentle_changes_added", fg = "#a6e3a1" }, { token = "$gentle_changes_deleted", fg = "#f38ba8" }]]
248
251
  # END herdr-gentle-agents
249
252
  ```
250
253
 
@@ -252,11 +255,11 @@ The
252
255
  single row-1 heading cell mirrors the Gentle Shell SessionChanges model semantics
253
256
  (write/edit tool outcomes, never `git status`, never an approximate
254
257
  reaggregation): files keyed by `(root, path)` with snapshot-continuity and
255
- unavailable counts (unavailable files stay in the file count with 0/0); `↑N` shows when the pane
256
- branch is behind its upstream (branch-ab status only, no diff). `gentle_project`,
258
+ unavailable counts (unavailable files stay in the file count with 0/0). `gentle_project`,
257
259
  `gentle_changes_summary`, and the segment
258
- tokens (`gentle_changes_added`/`_deleted`/`_pull`) stay published for
259
- compatibility but render no visible row. Pink `gentle` (machine key
260
+ tokens (`gentle_changes_added`/`_deleted`) stay published for
261
+ compatibility but render no visible row. The changes row carries no
262
+ ahead/behind marker relative to the branch. Pink `gentle` (machine key
260
263
  `orchestrating`, pink palette unchanged) is the
261
264
  only user-facing `gentle`: it renders while the principal session actively
262
265
  works — even with zero subagents, with or without a fresh root marker — and
@@ -354,8 +357,8 @@ role word such as `worker`, `explorer`,
354
357
  once the principal itself is idle — and also while a
355
358
  task-mode subagent call blocks the principal's turn, until it returns), that
356
359
  a row never reads `gentle` on an idle pane; row 1
357
- shows the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
358
- question (choice / native-questionnaire / legacy event legs, executed `ask_user_question`/`ask_user_choice`, tool-gated `ui_prompt` dialog spans (a `custom` panel — agents view, ODD viewer, changes view, design canvas — never counts, because opening a panel is navigation, not a question), or permission waiting; `gentle_review` starts never speculate ask, and no failed tool ever does either: a tool error changes nothing, see the error rule below). `rdd` (machine key `review`) applies during acknowledged native capture/group execution only (`reviewerRunAcknowledged: true` at execution start — never proposal, never forecast-only, never `correctionLines` planning, never `gentle_review`/`gentle_review_scope` in any operation; no hook/sidebar signal observed; unknown legacy shapes stay dark; call-id tracked so thrown/cancelled calls still clear, read-only `assess` excluded). Bounded approximation: the acknowledged interval contains preparation and admission; no exact reviewer internal events exist today. The orchestrator-host `ask_user_choice` prompt emits no Pi tool/event observable by this extension and stays covered only by the event legs above. Never point the fixture commands at the live config: keep
360
+ shows the single heading cell (`● <project>` plus ` +N`/` -N` inline, zero `·`) after edits; then `ask` on an open
361
+ question (choice / native-questionnaire / legacy event legs, executed `ask_user_question`/`ask_user_choice`, tool-gated `ui_prompt` dialog spans (a `custom` panel — agents view, ODD viewer, changes view, design canvas — never counts, because opening a panel is navigation, not a question; neither does a span the agent proves it is not waiting on, since a run blocked on its own dialog cannot start a new top-level tool execution (a nested `codemode` call proves nothing: it starts while a sibling dialog is still awaited) or finish an assistant message, so a Gentle Shell command menu opened mid-work keeps the row on the agent's real activity), or permission waiting; `gentle_review` starts never speculate ask, and no failed tool ever does either: a tool error changes nothing, see the error rule below). `rdd` (machine key `review`) applies during acknowledged native capture/group execution only (`reviewerRunAcknowledged: true` at execution start — never proposal, never forecast-only, never `correctionLines` planning, never `gentle_review`/`gentle_review_scope` in any operation; no hook/sidebar signal observed; unknown legacy shapes stay dark; call-id tracked so thrown/cancelled calls still clear, read-only `assess` excluded). Bounded approximation: the acknowledged interval contains preparation and admission; no exact reviewer internal events exist today. The orchestrator-host `ask_user_choice` prompt emits no Pi tool/event observable by this extension and stays covered only by the event legs above. Never point the fixture commands at the live config: keep
359
362
  `HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
360
363
 
361
364
  ## Core Workflow
@@ -397,7 +400,7 @@ producer's own beat is 15 s by default and
397
400
  TTL. Reports in one window collapse into one frame, and refresh-driven frames
398
401
  are floored at 250 ms, so a burst can never spin the daemon. Polling stays the
399
402
  fallback for every lifecycle signal and the only source for what no Herdr event
400
- carries (the git-derived `+N/-N` and `↑N` row data and the presence prefix), so a
403
+ carries (the presence prefix), so a
401
404
  missed, undelivered, or rejected event never sticks. Read-only
402
405
  supervision triage ships beside it: the `doctor` and `whois` plugin actions
403
406
  (`node bin/gentle-doctor.js`, `node bin/gentle-whois.js`) plus the explicit-pane
@@ -437,13 +440,14 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
437
440
  NeedsAttention toast and sound, so the sidebar carries the error on the
438
441
  durable `gentle_error_v1` token while the pane stays quiet on `working`,
439
442
  and no phone envelope is sent).
440
- - Single-cell row-1 heading (`<icon> <project>` plus ` +N`/` -N`/` ↑N`
443
+ - Single-cell row-1 heading (`<icon> <project>` plus ` +N`/` -N`
441
444
  inline, exactly one nonempty cell so zero `·` separators; white base with
442
445
  `contains` rules keeping ` +` green (added), ` -` red (deleted,
443
- leading-space match), ` ↑` blue (pull)) mirroring the Gentle Shell
446
+ leading-space match)) mirroring the Gentle Shell
444
447
  SessionChanges model semantics over Gentle tool outcomes, never `git`
445
448
  status and never an approximate reaggregation (root+path continuity and
446
- unavailable counts); behind-upstream `↑N` from branch-ab status only.
449
+ unavailable counts). The changes row carries no ahead/behind marker
450
+ relative to the branch.
447
451
  Session-change tokens are refreshed/cleared from the current Gentle Shell
448
452
  session model and never carried across sessions.
449
453
  - Single-writer coexistence with `herdr-pi-tree`: no shared token names, no
@@ -179,7 +179,21 @@
179
179
  // ask only when it opens while at least one tool
180
180
  // execution is active, so commands/widgets that prompt
181
181
  // while idle never become ask; nested/duplicate
182
- // lifecycle coalesces into one boolean leg.
182
+ // lifecycle coalesces into one boolean leg. A command
183
+ // menu (`/rdd`, `/warp` list, the `customize` fallback)
184
+ // renders through `ctx.ui.select` -> `kind: "select"`,
185
+ // the same kind a real question uses, and the host
186
+ // gives no origin signal — so the span withdraws the
187
+ // moment the agent proves it was never waiting on it:
188
+ // a top-level `tool_execution_start` (never a nested
189
+ // `codemode` call, which starts while a sibling dialog
190
+ // is still awaited) or an assistant-role `message_end`
191
+ // while the span is open, and only then
192
+ // (`tool_execution_update` never withdraws: live
193
+ // background jobs emit it while a real ask may be
194
+ // open). Entry stays immediate so a real ask is never
195
+ // missed; `ui_prompt_end` clears both flags, so the
196
+ // next span starts fresh.
183
197
  // Boundary: this leg observes only what Pi emits as a
184
198
  // `tool_execution_start` event in this root extension.
185
199
  // A host-side ask UI that emits no execution for those names
@@ -2799,8 +2813,26 @@ export default function (pi) {
2799
2813
  // and a false ask on every panel open is worse than missing one dialog.
2800
2814
  // Nested or duplicate prompt lifecycle coalesces into one boolean leg,
2801
2815
  // cleared on the matching `ui_prompt_end`, session reset, and shutdown.
2816
+ // Withdrawal (odd/tasks/ui-prompt-ask-origin): the host emits no origin
2817
+ // signal, so a Gentle Shell slash command rendering its option menu through
2818
+ // `ctx.ui.select` (`/rdd`, `/warp` list, the `customize` fallback — all
2819
+ // `kind: "select"`) is indistinguishable from a real question at entry.
2820
+ // Entry therefore stays immediate (a real ask is never missed), and the leg
2821
+ // withdraws on the asymmetry a run genuinely blocked on its own dialog
2822
+ // cannot produce: starting new TOP-LEVEL tool executions, or finishing
2823
+ // assistant messages. A top-level `tool_execution_start` or an
2824
+ // assistant-role `message_end` proves the span was never waited on, so
2825
+ // `uiPromptWithdrawn` stands for the rest of that span and only
2826
+ // `ui_prompt_end` clears it. A nested call (`parentToolCallId`) never
2827
+ // withdraws: codemode's `ctx.executeTool` starts a sibling execution while
2828
+ // another tool's dialog is still awaited, so it proves nothing.
2829
+ // `tool_execution_update` never withdraws: live
2830
+ // background jobs (`bash_background` / `monitor`) emit updates while a real
2831
+ // ask may legitimately be open. The rule keys on signals only — no
2832
+ // command-name list and no title matching.
2802
2833
  const runningTools = new Set(); // toolCallId -> in-flight tool execution
2803
2834
  let uiPromptActive = false;
2835
+ let uiPromptWithdrawn = false;
2804
2836
  let askIntentId;
2805
2837
  let askCounter = 0;
2806
2838
 
@@ -3258,6 +3290,13 @@ export default function (pi) {
3258
3290
  } catch { /* best effort: a failure here is non-fatal */ }
3259
3291
  }
3260
3292
 
3293
+ // A generic UI prompt span contributes to ask only until the agent proves
3294
+ // it is not waiting on it (see the withdrawal rule next to
3295
+ // `uiPromptWithdrawn`); every other leg below is untouched.
3296
+ function uiPromptAskActive() {
3297
+ return uiPromptActive && !uiPromptWithdrawn;
3298
+ }
3299
+
3261
3300
  function askActiveNow() {
3262
3301
  return (
3263
3302
  choiceActive ||
@@ -3265,10 +3304,22 @@ export default function (pi) {
3265
3304
  questionnaireActive ||
3266
3305
  permissionPending.size > 0 ||
3267
3306
  askToolCalls.size > 0 ||
3268
- uiPromptActive
3307
+ uiPromptAskActive()
3269
3308
  );
3270
3309
  }
3271
3310
 
3311
+ // Withdrawal of the generic prompt leg (odd/tasks/ui-prompt-ask-origin):
3312
+ // called from the two signals that prove the run was never blocked on the
3313
+ // open span — a new top-level tool execution and a finished assistant
3314
+ // message. The span stops contributing to ask and to the beat until
3315
+ // `ui_prompt_end`.
3316
+ function withdrawUiPromptAsk() {
3317
+ if (!uiPromptAskActive()) return;
3318
+ uiPromptWithdrawn = true;
3319
+ updateBlocker();
3320
+ schedulePublish();
3321
+ }
3322
+
3272
3323
  function desiredLabel() {
3273
3324
  if (errorCode) return `error:${errorCode}`;
3274
3325
  if (askActiveNow()) return `ask:${askIntentId}`;
@@ -3814,7 +3865,9 @@ export default function (pi) {
3814
3865
  // task-mode role publishes even while the authoritative count is 0.
3815
3866
  // A pending ask tool call likewise keeps the beat alive so `ask:`
3816
3867
  // publishes while the call is in flight; the generic UI prompt leg
3817
- // holds the beat the same way while its span is open. Effective
3868
+ // holds the beat the same way while its span is open and has not been
3869
+ // withdrawn (a withdrawn span proves the agent is working, so the
3870
+ // ordinary activity legs keep the beat). Effective
3818
3871
  // review (executing acknowledged capture/group calls) keeps the beat
3819
3872
  // alive so `review:` and the durable review token publish — NO GRACE:
3820
3873
  // the leg drops when the last execution ends or resolves. A live
@@ -3827,7 +3880,7 @@ export default function (pi) {
3827
3880
  pendingCalls.size > 0 ||
3828
3881
  freshRunningJobCount() > 0 ||
3829
3882
  askToolCalls.size > 0 ||
3830
- uiPromptActive ||
3883
+ uiPromptAskActive() ||
3831
3884
  reviewActive ||
3832
3885
  // The standing run error keeps a beat alive so its durable token stays
3833
3886
  // republished (and TTL-fresh) until the leg releases, even after the
@@ -4305,6 +4358,7 @@ export default function (pi) {
4305
4358
  askToolCalls.clear();
4306
4359
  runningTools.clear();
4307
4360
  uiPromptActive = false;
4361
+ uiPromptWithdrawn = false;
4308
4362
  askIntentId = undefined;
4309
4363
  reviewCalls.clear();
4310
4364
  reviewActive = false;
@@ -4390,6 +4444,15 @@ export default function (pi) {
4390
4444
  if (!rootSession || !isRecord(event) || typeof event.toolCallId !== "string") return;
4391
4445
  noteActivity();
4392
4446
  runningTools.add(event.toolCallId);
4447
+ // A new TOP-LEVEL execution cannot start inside a run blocked on a
4448
+ // dialog: if a generic UI prompt span is open, it was never waited on (a
4449
+ // Gentle Shell command menu keeps the agent working), so the span
4450
+ // withdraws for the rest of its life. A nested call proves the opposite of
4451
+ // nothing: codemode's `ctx.executeTool` emits its start immediately, even
4452
+ // before its own queue wait, while a sibling tool's dialog is still
4453
+ // awaited (verified: 1 finding, false negative on a real confirmation), so
4454
+ // nested starts never withdraw.
4455
+ if (event.parentToolCallId === undefined) withdrawUiPromptAsk();
4393
4456
  // Structured ask tools open ONLY on genuine execution (never on
4394
4457
  // `tool_call` proposal), keyed by call id so the matching end or
4395
4458
  // result closes them.
@@ -4463,6 +4526,9 @@ export default function (pi) {
4463
4526
  pi.on("ui_prompt_end", () => {
4464
4527
  if (!rootSession || !uiPromptActive) return;
4465
4528
  uiPromptActive = false;
4529
+ // A fresh span (nested or later) starts un-withdrawn: the withdrawal is
4530
+ // per-span evidence, never session-wide.
4531
+ uiPromptWithdrawn = false;
4466
4532
  updateBlocker();
4467
4533
  });
4468
4534
 
@@ -4698,6 +4764,11 @@ export default function (pi) {
4698
4764
  const message = event.message;
4699
4765
  if (!isRecord(message)) return;
4700
4766
  if (message.role === "assistant") {
4767
+ // A finished assistant message while a generic UI prompt span is open
4768
+ // proves the run was never blocked on it (same asymmetry as a new
4769
+ // top-level tool execution), so the span withdraws for the rest of its
4770
+ // life.
4771
+ withdrawUiPromptAsk();
4701
4772
  // The one real error state. Pi derives `turn_end.outcome === "error"`
4702
4773
  // from exactly this stopReason, so a run that stopped on an error is
4703
4774
  // visible here without a second handler; any other assistant message
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "herdr-gentle-shell",
3
- "version": "1.6.1",
3
+ "version": "1.7.0",
4
4
  "description": "Pi package for Herdr sidebar states: the Pi extension sidecar that publishes session facts as Herdr pane-metadata tokens, the optional Moshi notification channel, and the Pi-side helpers the Herdr Gentle Shell plugin drives.",
5
5
  "keywords": [
6
6
  "pi-package",