@luminascale/shepherd 0.0.0-stage → 0.6.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.
Files changed (203) 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 +424 -2
  16. package/docs/README.md +25 -0
  17. package/docs/guides/agent-definitions.md +42 -0
  18. package/docs/guides/diagnostics.md +199 -0
  19. package/docs/guides/tool-reference.md +55 -0
  20. package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
  21. package/docs/plans/agent-labels.md +257 -0
  22. package/docs/plans/architecture.md +110 -0
  23. package/docs/plans/settings-scope.md +163 -0
  24. package/docs/plans/tool-surface-split.md +278 -0
  25. package/docs/reference/dictionary +26 -0
  26. package/docs/releasing.md +47 -0
  27. package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
  28. package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
  29. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
  30. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
  31. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
  32. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
  33. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
  34. package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
  35. package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
  36. package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
  37. package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
  38. package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
  39. package/index.ts +599 -0
  40. package/package.json +112 -4
  41. package/scripts/capture-system-prompt.mjs +45 -0
  42. package/scripts/extract-pi-system-prompt.mjs +277 -0
  43. package/scripts/host-impact.mjs +74 -0
  44. package/scripts/resolve-agent.mjs +43 -0
  45. package/scripts/show-shepherd-orchestrator.mjs +58 -0
  46. package/scripts/show-shepherd-prompt.mjs +96 -0
  47. package/scripts/verify-suites.mjs +67 -0
  48. package/specs/001-artifacts/spec.md +436 -0
  49. package/specs/002-simplify-agent-orchestration/plan.md +287 -0
  50. package/specs/002-simplify-agent-orchestration/spec.md +323 -0
  51. package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
  52. package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
  53. package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
  54. package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
  55. package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
  56. package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
  57. package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
  58. package/specs/005-per-workspace-settings/plan.md +230 -0
  59. package/specs/005-per-workspace-settings/spec.md +368 -0
  60. package/specs/005-per-workspace-settings/tasks.md +178 -0
  61. package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
  62. package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
  63. package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
  64. package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
  65. package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
  66. package/specs/007-unwatched-completion-notice/journal.md +145 -0
  67. package/specs/007-unwatched-completion-notice/plan.md +186 -0
  68. package/specs/007-unwatched-completion-notice/spec.md +284 -0
  69. package/specs/007-unwatched-completion-notice/tasks.md +147 -0
  70. package/specs/008-remote-machine-sheep/intent.md +174 -0
  71. package/specs/008-remote-machine-sheep/journal.md +57 -0
  72. package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
  73. package/specs/009-hc-runtime/intent.md +44 -0
  74. package/specs/009-hc-runtime/plan.md +49 -0
  75. package/specs/009-hc-runtime/spec.md +118 -0
  76. package/specs/009-hc-runtime/tasks.md +62 -0
  77. package/specs/010-unseen-watch-parity/intent.md +57 -0
  78. package/specs/010-unseen-watch-parity/journal.md +172 -0
  79. package/specs/010-unseen-watch-parity/plan.md +74 -0
  80. package/specs/010-unseen-watch-parity/spec.md +191 -0
  81. package/specs/010-unseen-watch-parity/tasks.md +119 -0
  82. package/specs/011-hc-background-poll/intent.md +57 -0
  83. package/specs/011-hc-background-poll/journal.md +95 -0
  84. package/specs/011-hc-background-poll/plan.md +87 -0
  85. package/specs/011-hc-background-poll/spec.md +141 -0
  86. package/specs/011-hc-background-poll/tasks.md +83 -0
  87. package/specs/012-steer-default/intent.md +12 -0
  88. package/specs/012-steer-default/journal.md +40 -0
  89. package/specs/012-steer-default/plan.md +7 -0
  90. package/specs/012-steer-default/spec.md +42 -0
  91. package/specs/012-steer-default/tasks.md +6 -0
  92. package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
  93. package/specs/013-opencode-shepherd/intent.md +59 -0
  94. package/specs/013-opencode-shepherd/plan.md +204 -0
  95. package/specs/013-opencode-shepherd/spec.md +258 -0
  96. package/specs/013-opencode-shepherd/tasks.md +259 -0
  97. package/src/core/artifact-sessions.ts +835 -0
  98. package/src/core/config.ts +329 -0
  99. package/src/core/discovery.ts +342 -0
  100. package/src/core/herdr.ts +1 -0
  101. package/src/core/host.ts +77 -0
  102. package/src/core/ids.ts +78 -0
  103. package/src/core/lifecycle.ts +1 -0
  104. package/src/core/messaging.ts +1 -0
  105. package/src/core/migration.ts +55 -0
  106. package/src/core/orchestration.ts +1 -0
  107. package/src/core/types.ts +143 -0
  108. package/src/core/unseen-completions.ts +114 -0
  109. package/src/extension/cli.ts +417 -0
  110. package/src/extension/config.ts +1 -0
  111. package/src/extension/settings-ui.ts +296 -0
  112. package/src/extension/shepherd-done.ts +768 -0
  113. package/src/extension/shepherd.ts +2548 -0
  114. package/src/extension/system-prompt.ts +38 -0
  115. package/src/extension/unseen-completions.ts +237 -0
  116. package/src/opencode/actions.ts +794 -0
  117. package/src/opencode/bridge.ts +777 -0
  118. package/src/opencode/display.ts +36 -0
  119. package/src/opencode/fieldnotes.ts +60 -0
  120. package/src/opencode/host.ts +62 -0
  121. package/src/opencode/orphans.ts +162 -0
  122. package/src/opencode/server.ts +458 -0
  123. package/src/runtimes/backend.ts +119 -0
  124. package/src/runtimes/detect.ts +102 -0
  125. package/src/runtimes/hc/hc.ts +527 -0
  126. package/src/runtimes/hc/runtime.ts +1898 -0
  127. package/src/runtimes/herdr/herdr.ts +912 -0
  128. package/src/runtimes/herdr/lifecycle.ts +1712 -0
  129. package/src/runtimes/herdr/messaging.ts +703 -0
  130. package/src/runtimes/herdr/orchestration.ts +1583 -0
  131. package/src/runtimes/herdr/runtime.ts +224 -0
  132. package/src/runtimes/runtime.ts +133 -0
  133. package/src/runtimes/settle-observations.ts +114 -0
  134. package/test/fixtures/context-project/AGENTS.md +2 -0
  135. package/test/fixtures/home/.agents/agents/same.md +6 -0
  136. package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
  137. package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
  138. package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
  139. package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
  140. package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
  141. package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
  142. package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
  143. package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
  144. package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
  145. package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
  146. package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
  147. package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
  148. package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
  149. package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
  150. package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
  151. package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
  152. package/test/fixtures/proj/.pi/agents/same.md +6 -0
  153. package/test/helpers/fake-clock.mjs +39 -0
  154. package/test/helpers/feature-contracts.mjs +44 -0
  155. package/test/helpers/test-utils.mjs +44 -0
  156. package/test/verify-artifact-sessions.mjs +258 -0
  157. package/test/verify-backend.mjs +297 -0
  158. package/test/verify-child-mislabel.mjs +135 -0
  159. package/test/verify-child-surface.mjs +321 -0
  160. package/test/verify-cli.mjs +197 -0
  161. package/test/verify-command-ux.mjs +100 -0
  162. package/test/verify-compat.mjs +32 -0
  163. package/test/verify-cross-host-notes.mjs +128 -0
  164. package/test/verify-delegate.mjs +161 -0
  165. package/test/verify-detect.mjs +151 -0
  166. package/test/verify-discovery.mjs +239 -0
  167. package/test/verify-done-nudge.mjs +238 -0
  168. package/test/verify-effective-prompt.mjs +98 -0
  169. package/test/verify-hc-matrix.mjs +246 -0
  170. package/test/verify-hc-poll.mjs +260 -0
  171. package/test/verify-host-docs.mjs +35 -0
  172. package/test/verify-host-impact.mjs +49 -0
  173. package/test/verify-ids.mjs +141 -0
  174. package/test/verify-launch.mjs +183 -0
  175. package/test/verify-message-routing.mjs +560 -0
  176. package/test/verify-messaging.mjs +303 -0
  177. package/test/verify-migration-notice.mjs +69 -0
  178. package/test/verify-multi-wait.mjs +42 -0
  179. package/test/verify-opencode-display.mjs +47 -0
  180. package/test/verify-opencode-fieldnotes.mjs +121 -0
  181. package/test/verify-opencode-notice.mjs +77 -0
  182. package/test/verify-opencode-nudge.mjs +116 -0
  183. package/test/verify-opencode-orphans.mjs +160 -0
  184. package/test/verify-opencode-surface.mjs +107 -0
  185. package/test/verify-packaging.mjs +82 -0
  186. package/test/verify-parent-surface.mjs +118 -0
  187. package/test/verify-phase0.mjs +95 -0
  188. package/test/verify-registry.mjs +124 -0
  189. package/test/verify-rename-migration.mjs +111 -0
  190. package/test/verify-rendering.mjs +379 -0
  191. package/test/verify-session-boundary.mjs +146 -0
  192. package/test/verify-settings.mjs +260 -0
  193. package/test/verify-stale-wait.mjs +339 -0
  194. package/test/verify-status-widget.mjs +377 -0
  195. package/test/verify-status.mjs +172 -0
  196. package/test/verify-task-completion.mjs +156 -0
  197. package/test/verify-task-failures.mjs +201 -0
  198. package/test/verify-task-mislabel.mjs +143 -0
  199. package/test/verify-task-registry.mjs +194 -0
  200. package/test/verify-task-watchers.mjs +217 -0
  201. package/test/verify-tool-schemas.mjs +120 -0
  202. package/test/verify-unseen-completions.mjs +1211 -0
  203. package/test/verify-watchers.mjs +181 -0
@@ -0,0 +1,339 @@
1
+ #!/usr/bin/env node
2
+ /** Phase 8 verification for stale-wait monitoring and reminders. */
3
+ import assert from 'node:assert/strict';
4
+ import { LifecycleRegistry, lifecycleRegistry } from '../src/core/orchestration.ts';
5
+ import { StaleWaitMonitor } from '../src/core/lifecycle.ts';
6
+ import { withFakeDateNow } from './helpers/fake-clock.mjs';
7
+ import { registerShepherdTools, setStaleWaitSessionActive } from '../src/extension/shepherd.ts';
8
+
9
+ const ONE_MIN = 60_000;
10
+
11
+ // Keep this test independent of the developer's persisted Shepherd settings.
12
+ // In particular, a user-configured staleWaitThreshold must not change the
13
+ // test's documented thirty-minute default.
14
+ const { createTempDirectory } = await import('./helpers/test-utils.mjs');
15
+ const { rmSync } = await import('node:fs');
16
+ const isolatedAgentDir = createTempDirectory('pi-shepherd-stale-wait-');
17
+ const previousAgentDir = process.env.PI_CODING_AGENT_DIR;
18
+ process.env.PI_CODING_AGENT_DIR = isolatedAgentDir;
19
+
20
+ try {
21
+ function makeMonitor(registry) {
22
+ const infos = [];
23
+ const monitor = new StaleWaitMonitor(registry, info => infos.push(info), 1_000);
24
+ return { monitor, infos };
25
+ }
26
+
27
+ /** Put an agent's task into `waiting` on an outstanding reply. */
28
+ function enterWaiting(registry, agent, target, question) {
29
+ const task = registry.createTask(agent, 'Investigate the authentication failure.');
30
+ registry.setTaskRunning(task.id);
31
+ registry.openPendingRequest(task.id, {
32
+ messageId: 'msg-question-1',
33
+ targetAgentId: target.id,
34
+ text: question,
35
+ });
36
+ return task.id;
37
+ }
38
+
39
+ await withFakeDateNow(0, async clock => {
40
+ const registry = new LifecycleRegistry();
41
+ const scout = registry.registerAgent({ agent: 'scout', label: 'stale-scout' });
42
+ const planner = registry.registerAgent({ agent: 'planner', label: 'stale-planner' });
43
+ const { monitor, infos } = makeMonitor(registry);
44
+ registry.setAgentState(planner, 'working');
45
+ const taskId = enterWaiting(registry, scout, planner, 'What is the retry backoff?');
46
+
47
+ // 29.9 min in: under the default 30-min threshold -> no notification yet.
48
+ clock.advance(29.9 * ONE_MIN);
49
+ await monitor.poll();
50
+ assert.equal(infos.length, 0, 'no stale notification before the threshold is crossed');
51
+ console.log('PASS no stale notification while below the threshold');
52
+
53
+ // Cross the threshold: exactly one notification.
54
+ clock.advance(0.2 * ONE_MIN);
55
+ await monitor.poll();
56
+ assert.equal(infos.length, 1, 'one notification after crossing the threshold');
57
+ console.log('PASS a waiting task crossing the threshold produces one stale-wait notification');
58
+
59
+ // One notification per episode: advancing further does not repeat it.
60
+ clock.advance(ONE_MIN);
61
+ await monitor.poll();
62
+ assert.equal(infos.length, 1, 'the same episode does not notify again');
63
+ console.log('PASS no repeated notification while the episode is still open');
64
+
65
+ // Notification content.
66
+ const info = infos[0];
67
+ assert.equal(info.taskId, taskId);
68
+ assert.equal(info.agentId, scout.id);
69
+ assert.equal(info.agent, 'scout');
70
+ assert.equal(info.label, 'stale-scout');
71
+ assert.match(info.description, /authentication failure/);
72
+ assert.equal(typeof info.waitingSince, 'number');
73
+ assert.ok(info.elapsedMs >= 30 * ONE_MIN, 'elapsed wait reflects the threshold crossing');
74
+ assert.equal(info.requestMessageId, 'msg-question-1');
75
+ assert.equal(info.question, 'What is the retry backoff?');
76
+ assert.equal(info.recipientId, planner.id);
77
+ assert.equal(info.recipientState, 'working');
78
+ assert.equal(info.thresholdMinutes, 30, 'default threshold is 30 minutes');
79
+ console.log(
80
+ 'PASS the stale-wait notification carries task, owner, question, recipient, and elapsed time'
81
+ );
82
+
83
+ // A reply clears the stale condition; a new episode re-notifies.
84
+ registry.setAgentState(planner, 'idle');
85
+ clock.advance(ONE_MIN);
86
+ registry.resolveReplyForTask(taskId, 'msg-question-1');
87
+ assert.equal(registry.getTask(taskId).state, 'running');
88
+ assert.equal(
89
+ registry.getTask(taskId).staleNotifiedAt,
90
+ undefined,
91
+ 'reply clears the stale flag'
92
+ );
93
+ registry.openPendingRequest(taskId, {
94
+ messageId: 'msg-question-2',
95
+ targetAgentId: planner.id,
96
+ text: 'And the max attempts?',
97
+ });
98
+ clock.advance(30.5 * ONE_MIN);
99
+ await monitor.poll();
100
+ assert.equal(infos.length, 2, 'a new waiting episode produces its own notification');
101
+ assert.equal(infos[1].requestMessageId, 'msg-question-2');
102
+ console.log('PASS a reply clears the stale condition and a new episode re-notifies');
103
+ monitor.shutdown();
104
+ });
105
+
106
+ {
107
+ // A completed task never raises a stale notification.
108
+ const registry = new LifecycleRegistry();
109
+ const scout = registry.registerAgent({ agent: 'scout', label: 'done-scout' });
110
+ const { monitor, infos } = makeMonitor(registry);
111
+ const task = registry.createTask(scout, 'Will finish quickly.');
112
+ registry.setTaskRunning(task.id);
113
+ registry.settleTask(task.id, { status: 'completed', ok: true, text: 'done' });
114
+ await withFakeDateNow(0, async clock => {
115
+ clock.advance(60 * ONE_MIN);
116
+ await monitor.poll();
117
+ });
118
+ assert.equal(infos.length, 0, 'a completed task never raises a stale notification');
119
+ monitor.shutdown();
120
+ console.log('PASS a completed task has no stale notification');
121
+ }
122
+
123
+ {
124
+ // An idle agent with no waiting task raises nothing.
125
+ const registry = new LifecycleRegistry();
126
+ const idle = registry.registerAgent({ agent: 'planner', label: 'just-idle' });
127
+ registry.setAgentState(idle, 'idle');
128
+ const { monitor, infos } = makeMonitor(registry);
129
+ await withFakeDateNow(0, async clock => {
130
+ clock.advance(60 * ONE_MIN);
131
+ await monitor.poll();
132
+ });
133
+ assert.equal(infos.length, 0, 'an idle agent with no waiting task raises nothing');
134
+ monitor.shutdown();
135
+ console.log('PASS an idle agent without a waiting task produces no stale notification');
136
+ }
137
+
138
+ {
139
+ // Stale-wait is information only; it never settles the task.
140
+ const registry = new LifecycleRegistry();
141
+ const scout = registry.registerAgent({ agent: 'scout', label: 'keep-waiting' });
142
+ const planner = registry.registerAgent({ agent: 'planner', label: 'keep-waiting-2' });
143
+ const { monitor, infos } = makeMonitor(registry);
144
+ const task = registry.createTask(scout, 'Still waiting.');
145
+ registry.setTaskRunning(task.id);
146
+ await withFakeDateNow(0, async clock => {
147
+ registry.openPendingRequest(task.id, {
148
+ messageId: 'msg-1',
149
+ targetAgentId: planner.id,
150
+ text: 'q?',
151
+ });
152
+ clock.advance(60 * ONE_MIN);
153
+ await monitor.poll();
154
+ });
155
+ assert.equal(infos.length, 1, 'one stale notification was emitted');
156
+ assert.equal(registry.getTask(task).state, 'waiting', 'stale-wait does not settle the task');
157
+ registry.settleTask(task, {
158
+ status: 'blocked',
159
+ ok: false,
160
+ error: 'Tracked reply deadline reached.',
161
+ });
162
+ assert.equal(registry.getTask(task).state, 'blocked');
163
+ monitor.shutdown();
164
+ console.log(
165
+ 'PASS stale-wait is information only; the reply deadline settles the task separately'
166
+ );
167
+ }
168
+
169
+ {
170
+ // Monitor starts only while a task is waiting and stops when none remain.
171
+ const registry = new LifecycleRegistry();
172
+ const scout = registry.registerAgent({ agent: 'scout', label: 'timer' });
173
+ const planner = registry.registerAgent({ agent: 'planner', label: 'timer-2' });
174
+ const { monitor } = makeMonitor(registry);
175
+ assert.ok(!monitor['timer'], 'no timer while there are no waiting tasks');
176
+ await withFakeDateNow(0, async clock => {
177
+ const task = registry.createTask(scout, 'Waiting for the timer.');
178
+ registry.setTaskRunning(task.id);
179
+ registry.openPendingRequest(task.id, {
180
+ messageId: 'm1',
181
+ targetAgentId: planner.id,
182
+ text: 'q?',
183
+ });
184
+ monitor.kick();
185
+ assert.ok(monitor['timer'], 'timer starts once a task is waiting');
186
+ // Let the episode elapse so a poll finds a waiting task, then settle it.
187
+ clock.advance(ONE_MIN);
188
+ registry.settleTask(task.id, { status: 'completed', ok: true, text: 'done' });
189
+ await monitor.poll();
190
+ });
191
+ assert.ok(!monitor['timer'], 'monitor stops when no waiting tasks remain');
192
+ monitor.shutdown();
193
+ console.log('PASS monitor starts only while waiting tasks exist and stops when none remain');
194
+ }
195
+
196
+ {
197
+ // Disabled timeout handling: a 0-minute threshold disables reminders.
198
+ const { withTempDirectory } = await import('./helpers/test-utils.mjs');
199
+ await withTempDirectory(undefined, async dir => {
200
+ const prev = process.env.PI_CODING_AGENT_DIR;
201
+ process.env.PI_CODING_AGENT_DIR = dir;
202
+ try {
203
+ const fs = await import('node:fs');
204
+ const path = await import('node:path');
205
+ const dir2 = path.join(dir, 'pi-shepherd');
206
+ fs.mkdirSync(dir2, { recursive: true });
207
+ fs.writeFileSync(path.join(dir2, 'config.json'), JSON.stringify({ staleWaitThreshold: 0 }));
208
+
209
+ const registry = new LifecycleRegistry();
210
+ const scout = registry.registerAgent({ agent: 'scout', label: 'disabled' });
211
+ const planner = registry.registerAgent({ agent: 'planner', label: 'disabled-2' });
212
+ const { monitor, infos } = makeMonitor(registry);
213
+ const task = registry.createTask(scout, 'Should not remind.');
214
+ registry.setTaskRunning(task.id);
215
+ await withFakeDateNow(0, async clock => {
216
+ registry.openPendingRequest(task.id, {
217
+ messageId: 'msg-1',
218
+ targetAgentId: planner.id,
219
+ text: 'q?',
220
+ });
221
+ clock.advance(60 * ONE_MIN);
222
+ await monitor.poll();
223
+ });
224
+ assert.equal(infos.length, 0, 'a disabled (0-minute) threshold raises no notification');
225
+ monitor.shutdown();
226
+ } finally {
227
+ if (prev === undefined) delete process.env.PI_CODING_AGENT_DIR;
228
+ else process.env.PI_CODING_AGENT_DIR = prev;
229
+ }
230
+ });
231
+ console.log('PASS a disabled stale-wait threshold raises no notification');
232
+ }
233
+
234
+ {
235
+ // Workspace-specific threshold must use the waiting task's cwd rather than
236
+ // the parent process cwd or a different registry's global state.
237
+ const fs = await import('node:fs');
238
+ const path = await import('node:path');
239
+ const workspace = path.join(isolatedAgentDir, 'workspace-with-settings');
240
+ fs.mkdirSync(path.join(workspace, '.shepherd'), { recursive: true });
241
+ fs.writeFileSync(
242
+ path.join(workspace, '.shepherd', 'config.json'),
243
+ JSON.stringify({ projectScope: true, staleWaitThreshold: 0 })
244
+ );
245
+ const registry = new LifecycleRegistry();
246
+ const scout = registry.registerAgent({ agent: 'scout', label: 'cwd-specific', cwd: workspace });
247
+ const planner = registry.registerAgent({
248
+ agent: 'planner',
249
+ label: 'cwd-target',
250
+ cwd: workspace,
251
+ });
252
+ const { monitor, infos } = makeMonitor(registry);
253
+ const task = registry.createTask(scout, 'Workspace-specific stale wait.');
254
+ registry.setTaskRunning(task.id);
255
+ await withFakeDateNow(0, async clock => {
256
+ registry.openPendingRequest(task.id, {
257
+ messageId: 'cwd-msg',
258
+ targetAgentId: planner.id,
259
+ text: 'q?',
260
+ });
261
+ clock.advance(60 * ONE_MIN);
262
+ await monitor.poll();
263
+ });
264
+ assert.equal(infos.length, 0, 'task cwd threshold disables the reminder');
265
+ assert.equal(
266
+ registry.getTask(task.id).cwd,
267
+ workspace,
268
+ 'task snapshot retains its workspace cwd'
269
+ );
270
+ monitor.shutdown();
271
+ console.log('PASS stale-wait resolves settings from the waiting task cwd');
272
+ }
273
+
274
+ {
275
+ // Bridge delivery + suppression once the parent session is inactive.
276
+ const { staleWaitMonitor } = await import('../src/core/lifecycle.ts');
277
+ const sent = [];
278
+ let renderRegistered = false;
279
+ registerShepherdTools({
280
+ registerTool() {},
281
+ registerMessageRenderer(customType) {
282
+ if (customType === 'shepherd.stale.wait') renderRegistered = true;
283
+ },
284
+ sendMessage(_message, options) {
285
+ sent.push(options);
286
+ },
287
+ });
288
+ assert.ok(renderRegistered, 'the shepherd.stale.wait renderer was registered');
289
+
290
+ const scout = lifecycleRegistry.registerAgent({ agent: 'scout', label: 'bridge-scout' });
291
+ const planner = lifecycleRegistry.registerAgent({ agent: 'planner', label: 'bridge-planner' });
292
+ setStaleWaitSessionActive(true);
293
+ const sentCountAfterActive = await withFakeDateNow(0, async clock => {
294
+ const task = lifecycleRegistry.createTask(scout, 'Bridge stale wait.');
295
+ lifecycleRegistry.setTaskRunning(task.id);
296
+ lifecycleRegistry.openPendingRequest(task.id, {
297
+ messageId: 'bridge-msg-1',
298
+ targetAgentId: planner.id,
299
+ text: 'q?',
300
+ });
301
+ clock.advance(60 * ONE_MIN);
302
+ await staleWaitMonitor.poll();
303
+ return sent.length;
304
+ });
305
+ assert.ok(sentCountAfterActive >= 1, 'one stale notification delivered as a custom follow-up');
306
+ assert.deepEqual(sent[sent.length - 1], { deliverAs: 'followUp', triggerTurn: false });
307
+
308
+ // With the parent session inactive, a new waiting episode is not delivered.
309
+ const secondAgent = lifecycleRegistry.registerAgent({
310
+ agent: 'scout',
311
+ label: 'bridge-scout-2',
312
+ });
313
+ setStaleWaitSessionActive(false);
314
+ const sentCountBefore = sent.length;
315
+ await withFakeDateNow(0, async clock => {
316
+ const secondTask = lifecycleRegistry.createTask(secondAgent, 'Second.');
317
+ lifecycleRegistry.setTaskRunning(secondTask.id);
318
+ lifecycleRegistry.openPendingRequest(secondTask.id, {
319
+ messageId: 'bridge-msg-2',
320
+ targetAgentId: planner.id,
321
+ text: 'q?',
322
+ });
323
+ clock.advance(60 * ONE_MIN);
324
+ await staleWaitMonitor.poll();
325
+ });
326
+ assert.equal(sent.length, sentCountBefore, 'no delivery once the parent session is inactive');
327
+ setStaleWaitSessionActive(true);
328
+ staleWaitMonitor.shutdown();
329
+ console.log(
330
+ 'PASS stale-wait is delivered as a follow-up and suppressed after the parent session goes inactive'
331
+ );
332
+ }
333
+
334
+ console.log('All stale-wait assertions passed.');
335
+ } finally {
336
+ if (previousAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
337
+ else process.env.PI_CODING_AGENT_DIR = previousAgentDir;
338
+ rmSync(isolatedAgentDir, { recursive: true, force: true });
339
+ }