@luminascale/shepherd 0.0.0-stage → 0.6.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.
Files changed (204) hide show
  1. package/.agents/agents/README.md +12 -0
  2. package/.agents/agents/planner.md +38 -0
  3. package/.agents/agents/reviewer.md +38 -0
  4. package/.agents/agents/scout.md +43 -0
  5. package/.agents/agents/worker.md +33 -0
  6. package/.agents/skills/smoke-test/SKILL.md +155 -0
  7. package/.agents/skills/smoke-test/references/forensics.md +46 -0
  8. package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
  9. package/.github/workflows/publish.yml +77 -0
  10. package/.pi/prompts/release.md +21 -0
  11. package/.prettierrc +10 -0
  12. package/AGENTS.md +88 -0
  13. package/CONTRIBUTING.md +177 -0
  14. package/LICENSE +201 -0
  15. package/README.md +397 -2
  16. package/docs/README.md +26 -0
  17. package/docs/guides/agent-definitions.md +42 -0
  18. package/docs/guides/diagnostics.md +199 -0
  19. package/docs/guides/installation.md +61 -0
  20. package/docs/guides/tool-reference.md +55 -0
  21. package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
  22. package/docs/plans/agent-labels.md +257 -0
  23. package/docs/plans/architecture.md +110 -0
  24. package/docs/plans/settings-scope.md +163 -0
  25. package/docs/plans/tool-surface-split.md +278 -0
  26. package/docs/reference/dictionary +26 -0
  27. package/docs/releasing.md +47 -0
  28. package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
  29. package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
  30. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
  31. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
  32. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
  33. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
  34. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
  35. package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
  36. package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
  37. package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
  38. package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
  39. package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
  40. package/index.ts +602 -0
  41. package/package.json +112 -4
  42. package/scripts/capture-system-prompt.mjs +45 -0
  43. package/scripts/extract-pi-system-prompt.mjs +277 -0
  44. package/scripts/host-impact.mjs +74 -0
  45. package/scripts/resolve-agent.mjs +43 -0
  46. package/scripts/show-shepherd-orchestrator.mjs +58 -0
  47. package/scripts/show-shepherd-prompt.mjs +96 -0
  48. package/scripts/verify-suites.mjs +67 -0
  49. package/specs/001-artifacts/spec.md +436 -0
  50. package/specs/002-simplify-agent-orchestration/plan.md +287 -0
  51. package/specs/002-simplify-agent-orchestration/spec.md +323 -0
  52. package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
  53. package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
  54. package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
  55. package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
  56. package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
  57. package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
  58. package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
  59. package/specs/005-per-workspace-settings/plan.md +230 -0
  60. package/specs/005-per-workspace-settings/spec.md +368 -0
  61. package/specs/005-per-workspace-settings/tasks.md +178 -0
  62. package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
  63. package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
  64. package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
  65. package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
  66. package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
  67. package/specs/007-unwatched-completion-notice/journal.md +145 -0
  68. package/specs/007-unwatched-completion-notice/plan.md +186 -0
  69. package/specs/007-unwatched-completion-notice/spec.md +284 -0
  70. package/specs/007-unwatched-completion-notice/tasks.md +147 -0
  71. package/specs/008-remote-machine-sheep/intent.md +174 -0
  72. package/specs/008-remote-machine-sheep/journal.md +57 -0
  73. package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
  74. package/specs/009-hc-runtime/intent.md +44 -0
  75. package/specs/009-hc-runtime/plan.md +49 -0
  76. package/specs/009-hc-runtime/spec.md +118 -0
  77. package/specs/009-hc-runtime/tasks.md +62 -0
  78. package/specs/010-unseen-watch-parity/intent.md +57 -0
  79. package/specs/010-unseen-watch-parity/journal.md +172 -0
  80. package/specs/010-unseen-watch-parity/plan.md +74 -0
  81. package/specs/010-unseen-watch-parity/spec.md +191 -0
  82. package/specs/010-unseen-watch-parity/tasks.md +119 -0
  83. package/specs/011-hc-background-poll/intent.md +57 -0
  84. package/specs/011-hc-background-poll/journal.md +95 -0
  85. package/specs/011-hc-background-poll/plan.md +87 -0
  86. package/specs/011-hc-background-poll/spec.md +141 -0
  87. package/specs/011-hc-background-poll/tasks.md +83 -0
  88. package/specs/012-steer-default/intent.md +12 -0
  89. package/specs/012-steer-default/journal.md +40 -0
  90. package/specs/012-steer-default/plan.md +7 -0
  91. package/specs/012-steer-default/spec.md +42 -0
  92. package/specs/012-steer-default/tasks.md +6 -0
  93. package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
  94. package/specs/013-opencode-shepherd/intent.md +59 -0
  95. package/specs/013-opencode-shepherd/plan.md +204 -0
  96. package/specs/013-opencode-shepherd/spec.md +258 -0
  97. package/specs/013-opencode-shepherd/tasks.md +263 -0
  98. package/src/core/artifact-sessions.ts +835 -0
  99. package/src/core/config.ts +329 -0
  100. package/src/core/discovery.ts +342 -0
  101. package/src/core/herdr.ts +1 -0
  102. package/src/core/host.ts +77 -0
  103. package/src/core/ids.ts +78 -0
  104. package/src/core/lifecycle.ts +1 -0
  105. package/src/core/messaging.ts +1 -0
  106. package/src/core/migration.ts +55 -0
  107. package/src/core/orchestration.ts +1 -0
  108. package/src/core/types.ts +143 -0
  109. package/src/core/unseen-completions.ts +114 -0
  110. package/src/extension/cli.ts +417 -0
  111. package/src/extension/config.ts +1 -0
  112. package/src/extension/settings-ui.ts +296 -0
  113. package/src/extension/shepherd-done.ts +768 -0
  114. package/src/extension/shepherd.ts +2548 -0
  115. package/src/extension/system-prompt.ts +38 -0
  116. package/src/extension/unseen-completions.ts +237 -0
  117. package/src/opencode/actions.ts +794 -0
  118. package/src/opencode/bridge.ts +777 -0
  119. package/src/opencode/display.ts +36 -0
  120. package/src/opencode/fieldnotes.ts +60 -0
  121. package/src/opencode/host.ts +62 -0
  122. package/src/opencode/orphans.ts +162 -0
  123. package/src/opencode/server.ts +458 -0
  124. package/src/runtimes/backend.ts +119 -0
  125. package/src/runtimes/detect.ts +102 -0
  126. package/src/runtimes/hc/hc.ts +527 -0
  127. package/src/runtimes/hc/runtime.ts +1898 -0
  128. package/src/runtimes/herdr/herdr.ts +912 -0
  129. package/src/runtimes/herdr/lifecycle.ts +1712 -0
  130. package/src/runtimes/herdr/messaging.ts +703 -0
  131. package/src/runtimes/herdr/orchestration.ts +1583 -0
  132. package/src/runtimes/herdr/runtime.ts +224 -0
  133. package/src/runtimes/runtime.ts +133 -0
  134. package/src/runtimes/settle-observations.ts +114 -0
  135. package/test/fixtures/context-project/AGENTS.md +2 -0
  136. package/test/fixtures/home/.agents/agents/same.md +6 -0
  137. package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
  138. package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
  139. package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
  140. package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
  141. package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
  142. package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
  143. package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
  144. package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
  145. package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
  146. package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
  147. package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
  148. package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
  149. package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
  150. package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
  151. package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
  152. package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
  153. package/test/fixtures/proj/.pi/agents/same.md +6 -0
  154. package/test/helpers/fake-clock.mjs +39 -0
  155. package/test/helpers/feature-contracts.mjs +44 -0
  156. package/test/helpers/test-utils.mjs +44 -0
  157. package/test/verify-artifact-sessions.mjs +258 -0
  158. package/test/verify-backend.mjs +297 -0
  159. package/test/verify-child-mislabel.mjs +135 -0
  160. package/test/verify-child-surface.mjs +321 -0
  161. package/test/verify-cli.mjs +197 -0
  162. package/test/verify-command-ux.mjs +100 -0
  163. package/test/verify-compat.mjs +32 -0
  164. package/test/verify-cross-host-notes.mjs +128 -0
  165. package/test/verify-delegate.mjs +161 -0
  166. package/test/verify-detect.mjs +151 -0
  167. package/test/verify-discovery.mjs +239 -0
  168. package/test/verify-done-nudge.mjs +238 -0
  169. package/test/verify-effective-prompt.mjs +98 -0
  170. package/test/verify-hc-matrix.mjs +246 -0
  171. package/test/verify-hc-poll.mjs +260 -0
  172. package/test/verify-host-docs.mjs +66 -0
  173. package/test/verify-host-impact.mjs +49 -0
  174. package/test/verify-ids.mjs +141 -0
  175. package/test/verify-launch.mjs +183 -0
  176. package/test/verify-message-routing.mjs +560 -0
  177. package/test/verify-messaging.mjs +303 -0
  178. package/test/verify-migration-notice.mjs +74 -0
  179. package/test/verify-multi-wait.mjs +42 -0
  180. package/test/verify-opencode-display.mjs +47 -0
  181. package/test/verify-opencode-fieldnotes.mjs +121 -0
  182. package/test/verify-opencode-notice.mjs +77 -0
  183. package/test/verify-opencode-nudge.mjs +116 -0
  184. package/test/verify-opencode-orphans.mjs +160 -0
  185. package/test/verify-opencode-surface.mjs +107 -0
  186. package/test/verify-packaging.mjs +82 -0
  187. package/test/verify-parent-surface.mjs +118 -0
  188. package/test/verify-phase0.mjs +95 -0
  189. package/test/verify-registry.mjs +124 -0
  190. package/test/verify-rename-migration.mjs +111 -0
  191. package/test/verify-rendering.mjs +379 -0
  192. package/test/verify-session-boundary.mjs +146 -0
  193. package/test/verify-settings.mjs +260 -0
  194. package/test/verify-stale-wait.mjs +339 -0
  195. package/test/verify-status-widget.mjs +377 -0
  196. package/test/verify-status.mjs +172 -0
  197. package/test/verify-task-completion.mjs +156 -0
  198. package/test/verify-task-failures.mjs +201 -0
  199. package/test/verify-task-mislabel.mjs +143 -0
  200. package/test/verify-task-registry.mjs +194 -0
  201. package/test/verify-task-watchers.mjs +217 -0
  202. package/test/verify-tool-schemas.mjs +120 -0
  203. package/test/verify-unseen-completions.mjs +1211 -0
  204. package/test/verify-watchers.mjs +181 -0
@@ -0,0 +1,38 @@
1
+ /**
2
+ * System-prompt adjustment used by pi-shepherd-launched agents.
3
+ *
4
+ * Pi's default identity paragraph is useful for the main session, but it is
5
+ * misleading when an agent has a more specific system-prompt body. Keep the
6
+ * match exact so custom prompts and future Pi prompt changes are left alone.
7
+ */
8
+
9
+ export const PI_DEFAULT_IDENTITY =
10
+ 'You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.';
11
+
12
+ export function replacePiIdentity(systemPrompt: string, replacement: unknown): string {
13
+ if (typeof replacement !== 'string') return systemPrompt;
14
+ const value = replacement.trim();
15
+ if (!value || !systemPrompt.startsWith(PI_DEFAULT_IDENTITY)) return systemPrompt;
16
+ return value + systemPrompt.slice(PI_DEFAULT_IDENTITY.length);
17
+ }
18
+
19
+ /** Remove only Pi's built-in documentation guidance, not project context. */
20
+ export function omitPiDocumentation(systemPrompt: string): string {
21
+ const marker = '\n\nPi documentation (read only when the user asks about pi itself';
22
+ const start = systemPrompt.indexOf(marker);
23
+ if (start < 0) return systemPrompt;
24
+ const finalBullet = systemPrompt.indexOf(
25
+ '\n- Always read pi .md files completely and follow links to related docs',
26
+ start + marker.length
27
+ );
28
+ if (finalBullet >= 0) {
29
+ const end = systemPrompt.indexOf('\n', finalBullet + 1);
30
+ const suffix = systemPrompt.slice(end < 0 ? systemPrompt.length : end);
31
+ return systemPrompt.slice(0, start) + (suffix.startsWith('\n\n') ? '' : '\n') + suffix;
32
+ }
33
+ // Keep a conservative fallback for a future Pi wording change where the
34
+ // section is still separated from the next prompt section by a blank line.
35
+ const end = systemPrompt.indexOf('\n\n', start + marker.length);
36
+ if (end < 0) return systemPrompt.slice(0, start);
37
+ return systemPrompt.slice(0, start) + systemPrompt.slice(end);
38
+ }
@@ -0,0 +1,237 @@
1
+ /**
2
+ * Parent-side bridge for tracked-task settlements that had no watcher
3
+ * attached.
4
+ *
5
+ * Registers the `shepherd.task.unseen` renderer, subscribes through the
6
+ * active runtime's settlement registry for the duration of a parent pi
7
+ * session (idempotent across repeated `session_start`), and delivers
8
+ * exactly one notice per batch:
9
+ *
10
+ * - while the Shepherd is idle, a debounced
11
+ * `pi.sendMessage(notice, { triggerTurn: true })` wake;
12
+ * - at the `agent_before_settle` boundary of a completed run, one
13
+ * `custom_message` entry plus `continue: true` for a single extra model
14
+ * request. We always offer the continuation and let pi's post-commit
15
+ * `canContinue` check decide; aborted or errored runs never continue,
16
+ * their entries stay pending for the idle wake.
17
+ *
18
+ * Wiring lives in `index.ts` (parent surface only, after the
19
+ * `PI_SHEPHERD_SESSION` guard) so `registerShepherdTools` fake-pi suites are
20
+ * unaffected.
21
+ */
22
+
23
+ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
24
+ import {
25
+ unseenCompletionLedger,
26
+ type UnseenCompletionLedger,
27
+ type UnseenSettlement,
28
+ } from '../core/unseen-completions.ts';
29
+ import { resolveBackend } from '../runtimes/backend.ts';
30
+ import { detectCaller } from '../runtimes/detect.ts';
31
+ import { loadSettings } from '../core/config.ts';
32
+ import { subscribeToTaskSettlements } from '../runtimes/settle-observations.ts';
33
+ import { renderShepherdNotification } from './shepherd.ts';
34
+
35
+ /** Debounce between a recorded settlement and the idle wake. */
36
+ export const UNSEEN_NOTICE_COALESCE_MS = 250;
37
+
38
+ /** Custom message type for the unwatched-completion notice. */
39
+ export const UNSEEN_NOTICE_CUSTOM_TYPE = 'shepherd.task.unseen';
40
+
41
+ export interface UnseenCompletionBridgeOptions {
42
+ coalesceMs?: number;
43
+ ledger?: UnseenCompletionLedger;
44
+ }
45
+
46
+ function settlementIdentity(settlement: UnseenSettlement): string {
47
+ if (settlement.agent && settlement.label) return `${settlement.agent} "${settlement.label}"`;
48
+ return settlement.agent || settlement.label || settlement.agentId;
49
+ }
50
+
51
+ /** Per-entry detail cap; the full result is always one shepherd_watch away. */
52
+ const NOTICE_DETAIL_MAX = 200;
53
+
54
+ function settlementDetail(settlement: UnseenSettlement): string {
55
+ // `||` (not `??`): an empty summary must fall back to the error text.
56
+ const raw = (settlement.text || settlement.error || '').replace(/\s+/g, ' ').trim();
57
+ const detail =
58
+ raw.length > NOTICE_DETAIL_MAX ? `${raw.slice(0, NOTICE_DETAIL_MAX - 1)}…` : raw;
59
+ return detail ? `${settlement.status} — ${detail}` : settlement.status;
60
+ }
61
+
62
+ /**
63
+ * Exact model-facing notice text for one batch of unseen settlements. Kept
64
+ * separate from delivery so the golden text is testable without a pi runtime.
65
+ */
66
+ export function formatUnseenCompletionNotice(settlements: readonly UnseenSettlement[]): string {
67
+ const lines = [
68
+ `Shepherd notice — ${settlements.length} task(s) settled with no watcher attached:`,
69
+ ];
70
+ for (const settlement of settlements) {
71
+ lines.push(
72
+ `- ${settlement.taskId} (${settlementIdentity(settlement)}): ${settlementDetail(settlement)}`
73
+ );
74
+ }
75
+ const ids = settlements.map(settlement => `"${settlement.taskId}"`).join(', ');
76
+ lines.push(`Full results: shepherd_watch({ id: [ ${ids} ] })`);
77
+ return lines.join('\n');
78
+ }
79
+
80
+ function noticeDetails(settlements: readonly UnseenSettlement[]): {
81
+ taskIds: string[];
82
+ settlements: UnseenSettlement[];
83
+ } {
84
+ return {
85
+ taskIds: settlements.map(settlement => settlement.taskId),
86
+ settlements: settlements.map(settlement => ({ ...settlement })),
87
+ };
88
+ }
89
+
90
+ export function configureUnseenCompletionBridge(
91
+ pi: ExtensionAPI,
92
+ options: UnseenCompletionBridgeOptions = {}
93
+ ): void {
94
+ const ledger = options.ledger ?? unseenCompletionLedger;
95
+ const coalesceMs = options.coalesceMs ?? UNSEEN_NOTICE_COALESCE_MS;
96
+
97
+ let idle = true;
98
+ let flushTimer: ReturnType<typeof setTimeout> | undefined;
99
+ let unsubscribe: (() => void) | undefined;
100
+ let capturedContext: any;
101
+
102
+ const clearFlushTimer = (): void => {
103
+ if (flushTimer === undefined) return;
104
+ clearTimeout(flushTimer);
105
+ flushTimer = undefined;
106
+ };
107
+
108
+ const isIdleNow = (): boolean => {
109
+ if (capturedContext && typeof capturedContext.isIdle === 'function') {
110
+ try {
111
+ return capturedContext.isIdle() === true;
112
+ } catch {
113
+ /* fall back to the tracked flag */
114
+ }
115
+ }
116
+ return idle;
117
+ };
118
+
119
+ const flush = (): void => {
120
+ clearFlushTimer();
121
+ if (typeof pi.sendMessage !== 'function') return;
122
+ if (!isIdleNow()) return;
123
+ const settlements = ledger.pending();
124
+ if (settlements.length === 0) return;
125
+ try {
126
+ pi.sendMessage(
127
+ {
128
+ customType: UNSEEN_NOTICE_CUSTOM_TYPE,
129
+ content: formatUnseenCompletionNotice(settlements),
130
+ display: true,
131
+ details: noticeDetails(settlements),
132
+ },
133
+ { triggerTurn: true }
134
+ );
135
+ } catch {
136
+ // Delivery is best effort: a synchronous throw keeps entries pending so
137
+ // a later boundary or idle wake retries them.
138
+ return;
139
+ }
140
+ ledger.drain(settlements.map(settlement => settlement.taskId));
141
+ };
142
+
143
+ const scheduleIdleWake = (): void => {
144
+ if (flushTimer !== undefined) return;
145
+ if (!idle) return;
146
+ if (ledger.pending().length === 0) return;
147
+ flushTimer = setTimeout(flush, coalesceMs);
148
+ (flushTimer as any).unref?.();
149
+ };
150
+
151
+ const subscribe = (): void => {
152
+ if (unsubscribe) return;
153
+ // Resolve the active backend per command (same resolver as doAction).
154
+ // A parent session may settle tasks on either backend across commands,
155
+ // so subscribe to both registries; the resolved backend is diagnostics
156
+ // only and never narrows the subscription. Either way the bridge owns
157
+ // the only `record` call sites: each settlement flows observer → record
158
+ // → scheduleIdleWake, identically on Herdr and hc.
159
+ try {
160
+ const cwd =
161
+ typeof capturedContext?.cwd === 'string' ? capturedContext.cwd : process.cwd();
162
+ void resolveBackend(loadSettings(cwd).backend, detectCaller());
163
+ } catch {
164
+ /* no reachable backend: still subscribe broadly so tests stay green */
165
+ }
166
+ unsubscribe = subscribeToTaskSettlements((result, context) => {
167
+ if (ledger.record(result, context)) scheduleIdleWake();
168
+ });
169
+ };
170
+
171
+ pi.on('session_start', (_event: any, ctx?: any) => {
172
+ if (ctx !== undefined) capturedContext = ctx;
173
+ idle = true;
174
+ clearFlushTimer();
175
+ ledger.clearAll();
176
+ subscribe();
177
+ });
178
+
179
+ pi.on('agent_start', (_event: any, ctx?: any) => {
180
+ if (ctx !== undefined) capturedContext = ctx;
181
+ idle = false;
182
+ });
183
+
184
+ pi.on('agent_settled', (_event: any, ctx?: any) => {
185
+ if (ctx !== undefined) capturedContext = ctx;
186
+ idle = true;
187
+ scheduleIdleWake();
188
+ });
189
+
190
+ pi.on('agent_before_settle', (event: any, ctx?: any) => {
191
+ if (ctx !== undefined) capturedContext = ctx;
192
+ if (event?.outcome !== 'completed') return undefined;
193
+ // No pre-entry canContinue check: `event.context` is projected from the
194
+ // entries that existed before this handler's draft, so it is always
195
+ // `false` here. pi commits the drafts first and then recomputes
196
+ // `finalContext.canContinue`, so a `custom_message` makes it continuable.
197
+ const settlements = ledger.pending();
198
+ if (settlements.length === 0) return undefined;
199
+ const taskIds = settlements.map(settlement => settlement.taskId);
200
+ const entry = {
201
+ type: 'custom_message' as const,
202
+ customType: UNSEEN_NOTICE_CUSTOM_TYPE,
203
+ content: formatUnseenCompletionNotice(settlements),
204
+ display: true,
205
+ details: noticeDetails(settlements),
206
+ };
207
+ // Drained when handed to pi. pi may reject the whole boundary result if
208
+ // any handler's entries fail projection (runner invalid-boundary path);
209
+ // that is not retried (documented residual in spec 007).
210
+ ledger.drain(taskIds);
211
+ return { entries: [entry], continue: true };
212
+ });
213
+
214
+ pi.on('session_shutdown', () => {
215
+ clearFlushTimer();
216
+ ledger.clearAll();
217
+ unsubscribe?.();
218
+ unsubscribe = undefined;
219
+ capturedContext = undefined;
220
+ idle = true;
221
+ });
222
+
223
+ pi.registerMessageRenderer(
224
+ UNSEEN_NOTICE_CUSTOM_TYPE,
225
+ (message: any, renderOptions: any, theme: any) => {
226
+ const settlements = Array.isArray(message?.details?.settlements)
227
+ ? message.details.settlements
228
+ : [];
229
+ return renderShepherdNotification(
230
+ message,
231
+ renderOptions,
232
+ theme,
233
+ settlements.length > 0 ? formatUnseenCompletionNotice(settlements) : undefined
234
+ );
235
+ }
236
+ );
237
+ }