herdr-gentle-shell 1.4.0 → 1.5.1

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
@@ -289,7 +289,20 @@ running delegate or a pending launch — neither of which says the
289
289
  principal itself works. The native status keeps that aggregate meaning for
290
290
  Herdr's own pane state; the row's working-vs-idle decision reads only
291
291
  `gentle_principal_v1` (§5.2). It carries no count and alters neither the work
292
- total nor the roles CSV.
292
+ total nor the roles CSV. `agentActive` alone would render that blocked call
293
+ as generic `gentle`.
294
+ The root session additionally emits `gentle_pending_v1` (`<hash>:<role>:<exp>`)
295
+ while a synchronous (task mode) `subagent_run`/`subagent_continue` tool call
296
+ is still in flight: such a call blocks the principal's own turn, so the
297
+ session is executing a tool call and waiting on the child rather than doing
298
+ its own model work. The value is the role word of the OLDEST in-flight
299
+ recognized launch (`agentToRole` of the pending record), republished on every
300
+ beat so a long child run stays covered by the ordinary beat, and cleared to
301
+ null the beat the call resolves, the agent settles, or the session resets.
302
+ It carries no count and alters neither the work total nor the roles CSV. A
303
+ background launch resolves its tool call immediately, so a queued or running
304
+ background delegate never publishes this marker and never changes the
305
+ principal's own display (S3).
293
306
 
294
307
  ### 4.3 Token formats (ABNF-ish, strict)
295
308
 
@@ -330,6 +343,21 @@ gentle_principal_v1 = sessionHash ":" expiry
330
343
  ; principal settles; decides working vs idle in §5.2
331
344
  ; while the native status keeps its aggregate meaning
332
345
  ; (running delegate / pending launch = working)
346
+ ; caveat: a synchronous launch keeps it fresh for the
347
+ ; whole blocked call — gentle_pending_v1 below carries the
348
+ ; child's role for that window
349
+ gentle_pending_v1 = sessionHash ":" role ":" expiry
350
+ ; blocking-delegate marker — fresh while a synchronous
351
+ ; (task mode) subagent_run/subagent_continue tool call is
352
+ ; in flight, carrying the role word of the OLDEST
353
+ ; in-flight recognized launch; republished on every beat
354
+ ; (same TTL discipline as gentle_work_v1) and null (clear)
355
+ ; the beat the call resolves, the agent settles, or the
356
+ ; session resets. Renders at role precedence in §5.2:
357
+ ; below attention and terminal done, above the principal
358
+ ; marker — the principal's turn is blocked on that child.
359
+ ; Background launches resolve immediately and never
360
+ ; publish it, so they never change the principal's row.
333
361
  gentle_done_v1 = sessionHash ":" expiry
334
362
  ; synthesized finish signal, no count — minted ONCE at the
335
363
  ; settled-and-empty edge (principal settled, zero
@@ -392,6 +420,7 @@ pane.report_metadata --source gentle:v1 --token gentle_work_v1=Ab3_xK9q2mZ7QwErT
392
420
  pane.report_metadata --source gentle:v1 --token gentle_roles_v1=worker,explorer
393
421
  pane.report_metadata --source gentle:v1 --token gentle_orchestrating_v1=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:1789000000000
394
422
  pane.report_metadata --source gentle:v1 --token gentle_principal_v1=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:1789000000000
423
+ pane.report_metadata --source gentle:v1 --token gentle_pending_v1=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:worker:1789000000000
395
424
  pane.report_metadata --source gentle:v1 --token gentle_names_v1=planner,code-writer
396
425
  pane.report_metadata --source gentle:v1 --token gentle_changes_v2=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:5:110:22:1789000000000
397
426
  pane.report_metadata --source gentle:v1 --token gentle_error_v1=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:run-failed:1789000000000
@@ -448,7 +477,10 @@ principal marker the pane shows the oldest role word (or `idle`), never
448
477
  new/reloaded session under a different session hash cannot retain the prior
449
478
  session's change token. `gentle_names_v1` clears the same way when the
450
479
  authoritative active TaskStore list has no labels, and `gentle_roles_v1`
451
- clears (null) when no delegation is active. The retired disclosure token is
480
+ clears (null) when no delegation is active. `gentle_pending_v1` clears
481
+ (null) on the first beat after the blocking call resolves, the agent
482
+ settles, or the session resets — the same full-state discipline, never a
483
+ lingering edge. The retired disclosure token is
452
484
  cleared to remove any stale metadata. v2 stays the visible
453
485
  normative source; v1 remains legacy only.
454
486
 
@@ -463,6 +495,9 @@ carry it as a suffix only when above one), `gentle_orchestrating_v1` (root-only
463
495
  + freshness gate for the `orchestrating` display — never rendered as a
464
496
  count), `gentle_principal_v1` (principal-only activity marker + freshness
465
497
  gate for the working-vs-idle decision — never rendered as a count),
498
+ `gentle_pending_v1` (blocking-delegate role marker + freshness gate for the
499
+ in-flight synchronous launch — renders the child's role word while the
500
+ principal's own turn is blocked on it),
466
501
  `gentle_done_v1` (synthesized finish signal + its own hold freshness gate
467
502
  for the reachable `done` display — the host never reports `done`, §4.3),
468
503
  `gentle_error_v1` (durable run-error signal + freshness gate for the `error`
@@ -484,6 +519,16 @@ error := fresh `gentle_error_v1` (durable per-beat token, §4.3)
484
519
  ask := fresh `gentle_ask_v1` (durable per-beat token, §4.3)
485
520
  OR herdr:blocked has ask:* (fresh)
486
521
  review := herdr:blocked has review:* (fresh)
522
+ blockingRole := fresh gentle_pending_v1 (session-bound, TTL-fresh) whose
523
+ role word is recognized — a synchronous subagent call is in
524
+ flight, so the principal's turn is blocked on that child;
525
+ renders exactly like the role branch below (display +
526
+ label via the role helpers, count suffix unchanged) and
527
+ outranks the principal marker, which stays fresh for the
528
+ whole blocked call. Stale, foreign, malformed, or
529
+ unrecognized evidence falls through. Background launches
530
+ resolve their tool call immediately, so a running background
531
+ delegate never reaches this branch.
487
532
  principalWorking := fresh gentle_principal_v1 (session-bound, TTL-fresh) —
488
533
  the principal's OWN activity, never the delegate count and
489
534
  never the aggregate native status (which reads working for
@@ -520,7 +565,7 @@ done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
520
565
  idle := otherwise (native fallback; also all-gentle-tokens-missing-or-expired)
521
566
  ```
522
567
 
523
- Priority: `error > ask > review > done > principal working > role > orchestrating > working(main) > idle`.
568
+ Priority: `error > ask > review > done > blockingRole > principal working > role > orchestrating > working(main) > idle`.
524
569
  `done` is matched before the principal/role branches in the reducer; it is
525
570
  listed here below the activity branches only so its settled-and-empty
526
571
  precondition reads together.
@@ -533,7 +578,13 @@ principal** renders `gentle` (pink
533
578
  `orchestrating` while a fresh root marker is live) and outranks every
534
579
  delegate role word; an **idle principal** shows the oldest running role word
535
580
  (`explorer`, `worker`, `verify`, `judge`, or `rdd` when it is the oldest)
536
- however many delegates run. The fresh marker is not a principal-working
581
+ however many delegates run. The one exception sits between them and is
582
+ evidence-based, never a precedence guess: while a **synchronous**
583
+ `subagent_run`/`subagent_continue` call is in flight the principal's own turn
584
+ is blocked on the child, so the fresh `gentle_pending_v1` role word decides
585
+ the row (below attention and the terminal `done`, above the principal
586
+ marker). Background launches resolve their tool call immediately, so a queued
587
+ or running background delegate never changes the principal's own display. The fresh marker is not a principal-working
537
588
  signal (it stays live while the principal is idle with queued or running
538
589
  delegates), so it never outranks a role word. An in-flight attention `review`
539
590
  (fresh `review:` label or durable `gentle_review_v1` token) overrides the
@@ -753,6 +804,10 @@ gentle-ai concern and explicitly out of scope for this plugin.
753
804
  the poll after the native one for the same question, a systematic
754
805
  duplication. The ask token still drives the sidebar ask display; sounds,
755
806
  suppression, and delay stay Herdr's.
807
+ - Herdr's own done/ask attention — the finished and needs-attention pop-ups and
808
+ their sound — is Herdr's native behavior, configured in Herdr itself (its
809
+ config and its settings). This package deliberately offers no switch for it;
810
+ its only notification surface is the optional Moshi channel.
756
811
  - `review` and `error` never emit a plugin notification: `review` attention
757
812
  stays in-flow/native; `error` is sidebar state only — our own `error:` label
758
813
  with the pane left on native `working`, so neither the `NeedsAttention`
@@ -881,11 +936,13 @@ applies the focused row and `Esc` closes without a write; a click on a category
881
936
  selects it, a click on a row applies it, and a click outside the panes is
882
937
  ignored (a press only captures the gesture, so a drag never applies a row).
883
938
  Each switch is one row that paints the stored state and carries the opposite
884
- value. The notifications switch appears under both `Herdr Sidebar` (as
885
- `Notifications`, where the plugin's own switches are looked for) and its own
886
- `Moshi notifications` category: a row names the switch it drives, so both
887
- apply the one `gentle-moshi.json` flag through `applyMoshiNotifications` and
888
- whosever change it was is what both rows read on the next render.
939
+ value. Each category owns exactly one switch: `Herdr Sidebar` shows the single
940
+ `Sidebar agent rows` row and its description names the managed agent rows only,
941
+ while the only Moshi switch is the `Notifications` row under
942
+ `Moshi notifications`, which applies the `gentle-moshi.json` flag through
943
+ `applyMoshiNotifications`. The two channels are never mixed: the sidebar-rows
944
+ switch neither reads nor writes that flag, so disabling the agent rows leaves
945
+ the notification channel exactly as it was.
889
946
  An inconclusive sidebar verdict (`unknown`) renders as `● Unknown` with a note
890
947
  instead of hiding the row: toggling still attempts the repair and reports the
891
948
  apply step's own error, exactly like the menu. The plain
package/README.md CHANGED
@@ -15,11 +15,18 @@ subagents — (machine display key
15
15
  (`gentle_principal_v1`, published while the principal session itself works and
16
16
  cleared when it settles) decides the row — never the delegate count, and
17
17
  never Herdr's aggregate native status (which reads `working` whenever any
18
- delegate runs): while the principal is working it
19
- reads `gentle` and no delegate role word wins; while the principal is idle
18
+ delegate runs): the default is still the principal's own state, so while the
19
+ principal works its own turn it reads `gentle` and no delegate role word
20
+ wins; while the principal is idle
20
21
  the oldest running delegate role shows — `explorer`, `worker`, `verify`,
21
22
  `judge`, `rdd` — with the total running count in parentheses when two or
22
- more subagents run, for example `explorer (3)`),
23
+ more subagents run, for example `explorer (3)`). The single exception is a
24
+ blocking synchronous subagent call (`gentle_pending_v1`): a task-mode
25
+ `subagent_run`/`subagent_continue` holds the principal's turn open until the
26
+ child returns, so the principal is waiting on that child rather than working
27
+ and the in-flight child's role renders instead. A queued or running
28
+ background delegate publishes no such marker and leaves the principal's
29
+ display untouched),
23
30
  `ask` (three independent event legs — choice, native questionnaire, legacy rpiv — plus
24
31
  executed `ask_user_question`/`ask_user_choice` tool calls (execution opens, end/result closes;
25
32
  proposals never block), tool-gated `ui_prompt` dialog spans (a `custom` panel — agents view, ODD
@@ -253,12 +260,22 @@ aggregate native status (the work token counts running delegates, and the
253
260
  native status reads `working` for any running delegate or pending launch — so
254
261
  neither can say the principal works): the dedicated
255
262
  `gentle_principal_v1` marker is published while the principal session itself
256
- works and cleared when it settles. A **working principal** reads `gentle` —
257
- pink
263
+ works and cleared when it settles. That is the default: a **working
264
+ principal** reads `gentle` — pink
258
265
  `orchestrating` while a fresh root marker is live — and no delegate role word
259
266
  wins; an **idle principal** shows the oldest running TaskStore role
260
267
  (`explorer`, `worker`, `verify`, `judge`, `rdd`), however many delegates run.
261
- Both yield to `ask`/`rdd`/`blocked` and terminal `done` — where `done` needs
268
+ The one exception is a blocking synchronous subagent call: while a task-mode
269
+ `subagent_run`/`subagent_continue` is in flight the principal's own turn is
270
+ blocked on the child, so the producer publishes that child's role in
271
+ `gentle_pending_v1` and it renders instead of `gentle`, for as long as the
272
+ call lasts. A resume (`subagent_continue`) carries no agent, so its role is
273
+ the tracked task record's agent for its `task_id`; when neither the input nor
274
+ a record names one, the call publishes no role and the row keeps its generic
275
+ display. Background launches resolve their tool call immediately, so a
276
+ queued or running background delegate publishes no such marker and leaves
277
+ the principal's own display untouched. These yield to `ask`/`rdd`/`blocked`
278
+ and terminal `done` — where `done` needs
262
279
  settled-plus-empty (principal settled with no running delegates and no
263
280
  pending launches; a settled principal with running delegates keeps the role
264
281
  word, never `done`). A role word is not a subagent label; it carries the
@@ -267,15 +284,17 @@ work total is a direct projection of the
267
284
  Gentle Shell TaskStore `running` records (only `running` counts as
268
285
  executing; queued/waiting never count), never a calculated
269
286
  pending-call estimate: pending tool calls are role-only display hints (exact
270
- in-flight subagent agent -> role slug, so task-mode launches show the active
287
+ in-flight subagent agent -> role slug, resolved from the tool input or, for a
288
+ resume, from the tracked task record, so task-mode launches show the active
271
289
  role even at count 0) plus label correlation, and
272
290
  true concurrent tasks all count. A live `running` record is never regressed
273
291
  by a racy non-final status read (only the authoritative launch outcomes,
274
292
  completions, and presence terminals move it), so principal activity with
275
293
  live delegates keeps `gentle` while an idle principal keeps the role word; a
276
294
  sanitized unknown slug exactly
277
- equal to `working` degrades to `gentle` (the bare word `working` never
278
- renders).
295
+ equal to `working` or `subagent` degrades to `gentle` (neither bare word ever
296
+ renders; `subagent` is the producer's launch-correlation placeholder, never
297
+ an agent name).
279
298
  Background launches (`subagent_run` with `mode: background`) announce
280
299
  lifecycle over `message_end` custom results: an ACTIVE status promotes the
281
300
  start into the tasks map like a task-mode record, so an active background
@@ -306,8 +325,9 @@ and confirm row 2 shows pink `gentle` (machine key
306
325
  `orchestrating`) while
307
326
  the principal session actively works — even with zero subagents — and keeps
308
327
  `gentle` while its delegates run (a role word such as `worker`, `explorer`,
309
- `verify`, `judge` shows once the principal itself is idle), row 1 shows
310
- the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
328
+ `verify`, `judge` shows once the principal itself is idle — and also while a
329
+ task-mode subagent call blocks the principal's turn, until it returns), row 1
330
+ shows the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
311
331
  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
312
332
  `HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
313
333
 
@@ -353,9 +373,13 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
353
373
  settled-plus-empty)) and the authoritative TaskStore role signal
354
374
  (`explorer` / `worker` / `verify` / `judge` / `rdd` from `TaskRecord.agent`,
355
375
  oldest running first by immutable first-seen, shown while the principal
356
- itself is idle — a working principal keeps `gentle`, asserted by the
357
- principal-only `gentle_principal_v1` marker rather than by the delegate
358
- count or Herdr's aggregate native status; `gentle` (machine
376
+ itself is idle — a working principal's own turn keeps `gentle`, asserted by
377
+ the principal-only `gentle_principal_v1` marker rather than by the delegate
378
+ count or Herdr's aggregate native status, with one exception: a blocking
379
+ synchronous `subagent_run`/`subagent_continue` call holds the principal's
380
+ turn open, so the in-flight child's role shows instead (the
381
+ `gentle_pending_v1` role marker) until that call resolves, while a
382
+ background delegate never takes that path; `gentle` (machine
359
383
  key `working`) for the principal's own working state; an unknown delegation
360
384
  keeps its original sanitized name, 32-char bound — never a generic
361
385
  collapse), with a running-count suffix on role labels when two or more
@@ -426,10 +450,17 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
426
450
  it is a key the panel answers to, and a narrow card compacts it instead of
427
451
  wrapping. Pointer input still works without being advertised — a click on a
428
452
  category selects it, a click on a row applies it, and a click outside the
429
- panes is ignored. The notifications switch appears twice — as its own
430
- `Moshi notifications` category and as a `Notifications` row inside
431
- `Herdr Sidebar` — and both rows read the one flag below, so the state they
432
- show can never disagree. The plain two-step menu stays as the fallback
453
+ panes is ignored. Each category owns exactly one switch: `Herdr Sidebar`
454
+ shows the single `Sidebar agent rows` row, and the only Moshi switch is the
455
+ `Notifications` row under `Moshi notifications`. The two are never mixed —
456
+ `Sidebar agent rows` neither reads nor writes `gentle-moshi.json`, so turning
457
+ the agent rows off never turns the notification channel off. Herdr's own
458
+ done/ask attention (the finished and needs-attention pop-ups and their
459
+ sound) is Herdr's native behavior, configured in Herdr itself — its config
460
+ and its settings — and this package deliberately offers no switch for it:
461
+ the optional Moshi channel below is the only notification surface the
462
+ package owns. The plain
463
+ two-step menu stays as the fallback
433
464
  when the TUI helpers or `ctx.ui.custom` are unavailable.
434
465
  `Sidebar agent rows` drives the Herdr plugin's own `bin/configure.js`
435
466
  (`--check` to read, `--apply --reload` / `--uninstall --reload` to change) and
@@ -454,8 +485,8 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
454
485
  mkdir -p "$dir" && echo '{"enabled":true}' > "$dir/gentle-moshi.json"
455
486
  ```
456
487
 
457
- `/herdr-gentle:customize` → `Moshi notifications` (or the `Notifications` row
458
- inside `Herdr Sidebar`) writes this flag for you, and enabling there first
488
+ `/herdr-gentle:customize` → `Moshi notifications` writes this flag for you,
489
+ and enabling there first
459
490
  requires the `moshi-hook` CLI on `PATH` with `moshi-hook status --json`
460
491
  reporting `paired: true` (an unpaired host is refused and nothing is
461
492
  written).
@@ -50,6 +50,22 @@
50
50
  // busy. The consumer uses it for the working-vs-idle
51
51
  // decision; the aggregate native status keeps its own
52
52
  // meaning. Never alters the work count or roles CSV.)
53
+ // gentle_pending_v1 = <hash>:<role>:<expiry>
54
+ // (blocking-delegate marker, session-bound + TTL-fresh
55
+ // like gentle_work_v1: the role word of the oldest
56
+ // in-flight `subagent_run`/`subagent_continue` call,
57
+ // republished on every beat while the call blocks, null
58
+ // / clear the beat it settles, the agent settles, or
59
+ // the session resets. A synchronous launch blocks the
60
+ // principal's own turn, so agentActive stays true and
61
+ // the principal marker would paint generic `gentle`
62
+ // while the child runs; this marker is the evidence
63
+ // that the row must show the child's role instead.
64
+ // Background launches resolve their tool call
65
+ // immediately, so they never leave a marker: a running
66
+ // background delegate never changes the principal's
67
+ // own display. Never alters the work count or roles
68
+ // CSV.)
53
69
  // gentle_changes_v2 = <hash>:<files>:<added>:<deleted>:<expiry>
54
70
  // (normative; exact added/deleted totals kept separate)
55
71
  // gentle_changes_v1 = <hash>:<files>:<added+deleted>:<expiry>
@@ -57,10 +73,13 @@
57
73
  // gentle_names_v1 = CSV of TaskRecord.label/agent (sanitized, ≤64 chars
58
74
  // each, oldest-first, total ≤ 512 UTF-8 BYTES; excess
59
75
  // advisory names are dropped whole, never chunked — the
60
- // §4.5 #p= overflow form never triggers by construction)
76
+ // §4.5 #p= overflow form never triggers by construction;
77
+ // a record whose label and agent are both absent has no
78
+ // identity to publish and is skipped, never replaced by a
79
+ // placeholder or a stringified absent value)
61
80
  // Compatibility transport only: the consumer renders
62
81
  // roles, never names. Null (clear) when the active
63
- // TaskStore list has no labels; null change tokens when the session model has
82
+ // TaskStore list has no names; null change tokens when the session model has
64
83
  // zero changed files — refreshed/cleared from the live
65
84
  // session model, never carried across sessions.
66
85
  // gentle_ask_v1 = <hash>:<intentId>:<expiry>
@@ -839,6 +858,13 @@ const ERROR_TOKEN = "gentle_error_v1";
839
858
  // computeNativeState alone — the aggregate native status answers `working`
840
859
  // for any delegate, so the consumer cannot use it to decide the row.
841
860
  const PRINCIPAL_TOKEN = "gentle_principal_v1";
861
+ // Blocking-delegate marker: session-bound + TTL-fresh `<hash>:<role>:<expiry>`,
862
+ // the role word of the oldest in-flight synchronous
863
+ // `subagent_run`/`subagent_continue` call. It exists because such a call
864
+ // blocks the principal's turn (agentActive stays true) while the child runs,
865
+ // so the principal marker alone renders generic `gentle`. Recognized roles
866
+ // only; null / clear when no blocking call is in flight.
867
+ const PENDING_TOKEN = "gentle_pending_v1";
842
868
 
843
869
  const HASH_RE = /^[A-Za-z0-9_-]{43}$/;
844
870
  const COUNT_RE = /^(0|[1-9]\d{0,15})$/;
@@ -2415,18 +2441,21 @@ async function applyCustomizeSwitch(id, value, ctx) {
2415
2441
  if (result.needsReload && typeof ctx?.reload === "function") await ctx.reload();
2416
2442
  }
2417
2443
 
2418
- // The single apply path shared by the overlay and the menu fallback. An
2419
- // inconclusive sidebar verdict is never a refusal: choosing On still attempts
2420
- // the repair and reports the apply step's own error, exactly like the baseline
2421
- // menu did. `switchId` names the switch a row drives when it lives under
2422
- // another category — the notifications row inside `Herdr Sidebar` applies the
2423
- // same `moshi` switch as the `Moshi notifications` category, so the one flag
2424
- // file stays the single source of truth.
2425
- async function applyCustomizeChoice(categoryId, valueId, ctx, switchId) {
2426
- const target = switchId === "sidebar" || switchId === "moshi" ? switchId : categoryId;
2427
- if (target !== "sidebar" && target !== "moshi") return;
2444
+ // The single apply path shared by the overlay and the menu fallback. The choice
2445
+ // the panel resolves names the switch it drives (`switchId`) and the value to
2446
+ // apply; that switch id is the only thing read here, so a row can never apply a
2447
+ // switch its category does not own. An inconclusive sidebar verdict is never a
2448
+ // refusal: choosing On still attempts the repair and reports the apply step's
2449
+ // own error, exactly like the baseline menu did.
2450
+ const CUSTOMIZE_SWITCH_IDS = ["sidebar", "moshi"];
2451
+
2452
+ async function applyCustomizeChoice(choice, ctx) {
2453
+ if (!isRecord(choice)) return;
2454
+ const switchId = choice.switchId;
2455
+ const valueId = choice.valueId;
2456
+ if (!CUSTOMIZE_SWITCH_IDS.includes(switchId)) return;
2428
2457
  if (valueId !== "on" && valueId !== "off") return;
2429
- await applyCustomizeSwitch(target, valueId, ctx);
2458
+ await applyCustomizeSwitch(switchId, valueId, ctx);
2430
2459
  }
2431
2460
 
2432
2461
  // The former plain menu, kept as the fallback when the TUI helpers or
@@ -2455,7 +2484,7 @@ async function runCustomizeFallback(ctx) {
2455
2484
  choice = undefined;
2456
2485
  }
2457
2486
  if (choice !== CUSTOMIZE_ON && choice !== CUSTOMIZE_OFF) return;
2458
- await applyCustomizeChoice(id, choice === CUSTOMIZE_ON ? "on" : "off", ctx);
2487
+ await applyCustomizeChoice({ switchId: id, valueId: choice === CUSTOMIZE_ON ? "on" : "off" }, ctx);
2459
2488
  }
2460
2489
 
2461
2490
  async function executeCustomize(rawArgs, ctx) {
@@ -2526,7 +2555,7 @@ async function executeCustomize(rawArgs, ctx) {
2526
2555
  // Esc (null) does nothing at all: no notification, no write, no reload.
2527
2556
  // Anything else runs the single apply path once the overlay is disposed.
2528
2557
  if (!choice || typeof choice !== "object") return;
2529
- await applyCustomizeChoice(choice.categoryId, choice.valueId, ctx, choice.switchId);
2558
+ await applyCustomizeChoice(choice, ctx);
2530
2559
  return;
2531
2560
  }
2532
2561
  await runCustomizeFallback(ctx);
@@ -2568,7 +2597,7 @@ export default function (pi) {
2568
2597
  // Finished/failed/cancelled/waiting entries may linger in the map but
2569
2598
  // never count; the map is cleared only on session reset (plus the
2570
2599
  // bounded-map guard) — never by a local staleness timeout.
2571
- const pendingCalls = new Map(); // toolCallId -> { agent, label, at }
2600
+ const pendingCalls = new Map(); // toolCallId -> { agent, label, at }; agent/label are undefined when no agent is resolvable
2572
2601
  const tasks = new Map(); // taskId -> { agent, label, status, at }
2573
2602
 
2574
2603
  // Blocker legs. ask combines choice + native questionnaire + legacy
@@ -3032,6 +3061,16 @@ export default function (pi) {
3032
3061
  return out;
3033
3062
  }
3034
3063
 
3064
+ // Role word of the OLDEST in-flight blocking launch, or undefined when no
3065
+ // recognized role is pending. `pendingRoleSubs` is already oldest-first by
3066
+ // call time, so the first entry is the one the row must show; recognized
3067
+ // filtering there means an unsalvageable agent name yields no role (the
3068
+ // consumer then stays on its own evidence instead of guessing).
3069
+ function pendingRole() {
3070
+ const oldest = pendingRoleSubs()[0];
3071
+ return oldest === undefined ? undefined : agentToRole(oldest.agent);
3072
+ }
3073
+
3035
3074
  // Merged role sources, oldest-first by first-seen: authoritative running
3036
3075
  // TaskStore subs plus pending role hints. Authoritative entries win on
3037
3076
  // duplicates via rolesCsv dedup (first wins = oldest wins).
@@ -3050,7 +3089,20 @@ export default function (pi) {
3050
3089
  const parts = [];
3051
3090
  let length = 0;
3052
3091
  for (const sub of subs) {
3053
- const name = sanitizeLabel(sub.label, sub.agent);
3092
+ // An entry whose label and agent are both absent has no name to publish:
3093
+ // a record can carry no identity at all (an observation without an agent
3094
+ // and no previous record), and `sanitizeLabel` stringifies whatever
3095
+ // fallback it is handed, so passing the absence through would put the
3096
+ // literal `undefined` on the wire as a name.
3097
+ const label =
3098
+ typeof sub.label === "string" && sub.label.length > 0 ? sub.label : undefined;
3099
+ const subAgent =
3100
+ typeof sub.agent === "string" && sub.agent.length > 0 ? sub.agent : undefined;
3101
+ if (label === undefined && subAgent === undefined) continue;
3102
+ // Label first, agent as fallback, unchanged for every entry that has
3103
+ // either; the fallback is never absent here, so the sanitizer always has
3104
+ // a real string to fall back to.
3105
+ const name = sanitizeLabel(label, subAgent ?? label);
3054
3106
  if (parts.includes(name)) continue;
3055
3107
  const add = (parts.length === 0 ? 0 : 1) + utf8Bytes(name);
3056
3108
  if (length + add > MAX_TOKEN_BYTES) break;
@@ -3098,11 +3150,13 @@ export default function (pi) {
3098
3150
  ) {
3099
3151
  return "rdd";
3100
3152
  }
3101
- // The bare visible word `working` is banned: a sanitized unknown slug
3102
- // exactly equal to `working` degrades to no role (generic `gentle`)
3103
- // in metadata roles and the native message alike.
3153
+ // The bare visible words `working` and `subagent` are banned: a sanitized
3154
+ // unknown slug exactly equal to either degrades to no role (generic
3155
+ // `gentle`) in metadata roles and the native message alike. `subagent` is
3156
+ // the launch-correlation placeholder, never an agent name, so it must
3157
+ // never reach the wire as a role word.
3104
3158
  const slug = sanitizeAgentSlug(agent);
3105
- return slug === "working" ? undefined : slug;
3159
+ return slug === "working" || slug === "subagent" ? undefined : slug;
3106
3160
  }
3107
3161
 
3108
3162
  // Bounded CSV of role words, oldest-first (subs already arrive
@@ -3215,6 +3269,17 @@ export default function (pi) {
3215
3269
  // how many delegates keep running.
3216
3270
  if (agentActive) tokens[PRINCIPAL_TOKEN] = `${sessionHash}:${expiry}`;
3217
3271
  else tokens[PRINCIPAL_TOKEN] = null;
3272
+ // Blocking-delegate marker (same binding/TTL discipline): a synchronous
3273
+ // launch keeps the principal's agent active for the whole child run, so
3274
+ // the principal marker above is fresh while the row should instead show
3275
+ // the child's role. This carries that evidence per beat (never
3276
+ // edge-only), so a long child run stays covered by the ordinary beat and
3277
+ // a missed beat cannot strand the row. Cleared to null the beat the call
3278
+ // settles; background launches resolve their tool call immediately and so
3279
+ // never publish it.
3280
+ const pending = pendingRole();
3281
+ if (pending !== undefined) tokens[PENDING_TOKEN] = `${sessionHash}:${pending}:${expiry}`;
3282
+ else tokens[PENDING_TOKEN] = null;
3218
3283
  // Synthesized finish signal (S2/D2): minted once at the settled-and-empty
3219
3284
  // edge — principal settled with no running/queued delegate, no pending
3220
3285
  // launch, no live background job, and no human-wait, review, or error leg
@@ -3880,11 +3945,23 @@ export default function (pi) {
3880
3945
 
3881
3946
  // -- subagent activity -----------------------------------------------------
3882
3947
 
3948
+ // `subagent_run` carries the agent in its input, but `subagent_continue`
3949
+ // carries only `task_id`/`prompt`/`label`/`mode`: a resume names the task
3950
+ // whose record already holds the child's agent. Neither source means no
3951
+ // role evidence at all — the pending call still covers the blocking/
3952
+ // orchestrating marker, but it contributes no role and no name, and it
3953
+ // must never publish the launch-correlation placeholder as a role word.
3883
3954
  function launchInput(input) {
3884
3955
  if (!isRecord(input)) return undefined;
3885
- const agent = typeof input.agent === "string" ? input.agent : "subagent";
3886
- const label = sanitizeLabel(typeof input.label === "string" ? input.label : agent, agent);
3887
- return { agent: truncateChars(agent, MAX_LABEL_CHARS), label };
3956
+ const taskId = typeof input.task_id === "string" ? input.task_id : undefined;
3957
+ const inputAgent =
3958
+ typeof input.agent === "string" && input.agent.length > 0 ? input.agent : undefined;
3959
+ const agent =
3960
+ inputAgent ?? (taskId !== undefined ? tasks.get(taskId)?.agent : undefined);
3961
+ const labelSource =
3962
+ typeof input.label === "string" && input.label.length > 0 ? input.label : agent;
3963
+ const label = labelSource === undefined ? undefined : sanitizeLabel(labelSource, labelSource);
3964
+ return { agent: agent === undefined ? undefined : truncateChars(agent, MAX_LABEL_CHARS), label };
3888
3965
  }
3889
3966
 
3890
3967
  pi.on("tool_call", (event) => {
@@ -3926,7 +4003,12 @@ export default function (pi) {
3926
4003
  }
3927
4004
  const pending =
3928
4005
  typeof event.toolCallId === "string" ? pendingCalls.get(event.toolCallId) : undefined;
3929
- if (typeof event.toolCallId === "string") pendingCalls.delete(event.toolCallId);
4006
+ const pendingResolved =
4007
+ typeof event.toolCallId === "string" ? pendingCalls.delete(event.toolCallId) : false;
4008
+ // A resolved launch releases the blocking-delegate marker on THIS beat,
4009
+ // not on the next periodic one: a failed/aborted launch carries no
4010
+ // gentleAgents details, so the record path below never publishes.
4011
+ if (pendingResolved) schedulePublish();
3930
4012
  // A launch resolution retires the settle-time pending guard: the
3931
4013
  // outcome is now covered by the task record (working via activeSubs),
3932
4014
  // the error latch (blocked), or genuine emptiness (idle on next beat).
@@ -4003,10 +4085,13 @@ export default function (pi) {
4003
4085
  : undefined;
4004
4086
  // A stale read's agent is distrusted with its status, and a missing
4005
4087
  // agent keeps the previous record's agent (never reset to a guess).
4088
+ // With neither source the record has no agent at all: `subagent` is the
4089
+ // launch-correlation placeholder, never an identity, so inventing it here
4090
+ // would publish that word as the record's name.
4006
4091
  const agent =
4007
4092
  staleRead && previous?.agent
4008
4093
  ? previous.agent
4009
- : (incomingAgent ?? previous?.agent ?? "subagent");
4094
+ : (incomingAgent ?? previous?.agent);
4010
4095
  const now = Date.now();
4011
4096
  tasks.set(details.taskId, {
4012
4097
  agent,
@@ -4057,10 +4142,13 @@ export default function (pi) {
4057
4142
  if (typeof details.status !== "string") return;
4058
4143
  if (!FINAL_TASK.has(details.status) && !ACTIVE_TASK.has(details.status)) return;
4059
4144
  const previous = tasks.get(details.taskId);
4145
+ // Same rule as the tool_result path: an observation without an agent keeps
4146
+ // the previous record's agent, and with neither there is no agent at all —
4147
+ // the launch-correlation placeholder must never become a record identity.
4060
4148
  const agent =
4061
4149
  typeof details.agent === "string" && details.agent.length > 0
4062
4150
  ? truncateChars(details.agent, MAX_LABEL_CHARS)
4063
- : (previous?.agent ?? "subagent");
4151
+ : previous?.agent;
4064
4152
  // Record identity is immutable per taskId: firstSeen never moves (T2b
4065
4153
  // ordering only) whether this observation promotes a background start
4066
4154
  // or replaces the record with its terminal status; completion still
@@ -174,16 +174,15 @@ const CUSTOMIZE_SWITCHES = [
174
174
  },
175
175
  ];
176
176
 
177
- // Categories only group rows for display. Notifications appears under both
178
- // headings on purpose: `Herdr Sidebar` is where the plugin's own switches are
179
- // looked for, and `Moshi notifications` keeps the switch the user already
180
- // knows. Both rows read the one flag, so they can never disagree.
177
+ // Two categories, one row each. `Herdr Sidebar` owns the managed agent rows the
178
+ // plugin publishes and nothing else: the Moshi notification channel lives only
179
+ // under `Moshi notifications`, so the sidebar switch can never toggle it.
181
180
  const CUSTOMIZE_CATEGORIES = [
182
181
  {
183
182
  id: "sidebar",
184
183
  title: "Herdr Sidebar",
185
- description: "Sidebar agent rows plus the Moshi notification channel.",
186
- switches: ["sidebar", "moshi"],
184
+ description: "The managed agent rows this plugin hands to the Herdr sidebar.",
185
+ switches: ["sidebar"],
187
186
  },
188
187
  {
189
188
  id: "moshi",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "herdr-gentle-shell",
3
- "version": "1.4.0",
3
+ "version": "1.5.1",
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",