@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,296 @@
1
+ /**
2
+ * Settings menu for pi-shepherd, rendered inline like pi's own `/settings`.
3
+ * Project scope is per-workspace; the project file is self-contained and the
4
+ * project-agent confirmation gate plus the backend pin remain user-owned.
5
+ */
6
+
7
+ import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
8
+ import { DynamicBorder, getSettingsListTheme } from '@earendil-works/pi-coding-agent';
9
+ import { Container, type SettingItem, SettingsList } from '@earendil-works/pi-tui';
10
+ import * as fs from 'node:fs';
11
+ import * as path from 'node:path';
12
+ import {
13
+ deactivateProjectScope,
14
+ loadProjectFileValues,
15
+ loadSettings,
16
+ projectConfigFile,
17
+ saveSettings,
18
+ type ShepherdSettings,
19
+ } from '../core/config.ts';
20
+
21
+ const TIMEOUT_CHOICES = [1, 2, 5, 10, 20, 30, 60];
22
+ const STALE_WAIT_CHOICES = [0, 1, 2, 5, 10, 15, 30];
23
+ const BACKEND_CHOICES = ['auto', 'herdr', 'hc'] as const;
24
+ const TIMEOUT_DISPLAY = (minutes: number) => `${minutes} min`;
25
+ const STALE_WAIT_DISPLAY = (minutes: number) =>
26
+ minutes === 0 ? 'off (no reminders)' : `${minutes} min`;
27
+
28
+ function booleans(value: boolean): [string, string[]] {
29
+ return value ? ['on', ['on', 'off']] : ['off', ['on', 'off']];
30
+ }
31
+
32
+ /** Translate a SettingsList value back into the typed settings object. */
33
+ function applyValue(settings: ShepherdSettings, id: string, value: string): ShepherdSettings {
34
+ const next = { ...settings };
35
+ switch (id) {
36
+ case 'projectScope':
37
+ next.projectScope = value === 'project';
38
+ break;
39
+ case 'agentScope':
40
+ next.agentScope = value as ShepherdSettings['agentScope'];
41
+ break;
42
+ case 'includeBundledAgents':
43
+ next.includeBundledAgents = value === 'on';
44
+ break;
45
+ case 'confirmProjectAgents':
46
+ next.confirmProjectAgents = value === 'on';
47
+ break;
48
+ case 'keepOpen':
49
+ next.keepOpen = value === 'on';
50
+ break;
51
+ case 'stayOpen':
52
+ next.stayOpen = value === 'on';
53
+ break;
54
+ case 'fieldnotes':
55
+ next.fieldnotes = value === 'on';
56
+ break;
57
+ case 'emojiSheep':
58
+ next.emojiSheep = value === 'on';
59
+ break;
60
+ case 'timeout': {
61
+ const minutes = Number.parseInt(value, 10);
62
+ if (Number.isFinite(minutes) && minutes > 0) next.timeout = minutes;
63
+ break;
64
+ }
65
+ case 'staleWaitThreshold': {
66
+ const minutes = value.startsWith('off') ? 0 : Number.parseInt(value, 10);
67
+ if (Number.isFinite(minutes) && minutes >= 0) next.staleWaitThreshold = minutes;
68
+ break;
69
+ }
70
+ case 'backend': {
71
+ if (value === 'auto' || value === 'herdr' || value === 'hc') {
72
+ next.backend = value;
73
+ }
74
+ break;
75
+ }
76
+ }
77
+ return next;
78
+ }
79
+
80
+ function refreshItems(items: SettingItem[], settings: ShepherdSettings, cwd: string): void {
81
+ const scopeItem = items[0];
82
+ if (settings.projectScope) {
83
+ scopeItem.currentValue = 'project';
84
+ scopeItem.values = ['project', 'user'];
85
+ } else if (fs.existsSync(projectConfigFile(cwd))) {
86
+ scopeItem.currentValue = 'user (project file dormant)';
87
+ scopeItem.values = ['user (project file dormant)', 'project'];
88
+ } else {
89
+ scopeItem.currentValue = 'user';
90
+ scopeItem.values = ['user', 'project'];
91
+ }
92
+
93
+ const [bundledValue, bundledValues] = booleans(settings.includeBundledAgents);
94
+ const [confirmValue, confirmValues] = booleans(settings.confirmProjectAgents);
95
+ const [keepOpenValue, keepOpenValues] = booleans(settings.keepOpen);
96
+ const [stayOpenValue, stayOpenValues] = booleans(settings.stayOpen);
97
+ const [fieldnotesValue, fieldnotesValues] = booleans(settings.fieldnotes);
98
+ const [emojiSheepValue, emojiSheepValues] = booleans(settings.emojiSheep);
99
+ items[1].currentValue = settings.agentScope;
100
+ items[2].currentValue = bundledValue;
101
+ items[2].values = bundledValues;
102
+ items[3].currentValue = confirmValue;
103
+ items[3].values = confirmValues;
104
+ items[4].currentValue = keepOpenValue;
105
+ items[4].values = keepOpenValues;
106
+ items[5].currentValue = stayOpenValue;
107
+ items[5].values = stayOpenValues;
108
+ items[6].currentValue = fieldnotesValue;
109
+ items[6].values = fieldnotesValues;
110
+ items[7].currentValue = emojiSheepValue;
111
+ items[7].values = emojiSheepValues;
112
+ items[8].currentValue = TIMEOUT_DISPLAY(settings.timeout);
113
+ items[9].currentValue = STALE_WAIT_DISPLAY(settings.staleWaitThreshold);
114
+ items[10].currentValue = settings.backend;
115
+ }
116
+
117
+ /** Render and drive the settings menu. */
118
+ export async function openSettings(ctx: ExtensionCommandContext): Promise<void> {
119
+ const cwd = ctx.cwd;
120
+ let settings = loadSettings(cwd);
121
+
122
+ await ctx.ui.custom((_tui, theme, _kb, done) => {
123
+ const container = new Container();
124
+ container.addChild(new DynamicBorder((s: string) => theme.fg('accent', s)));
125
+
126
+ const items: SettingItem[] = [
127
+ {
128
+ id: 'projectScope',
129
+ label: 'Settings scope',
130
+ description:
131
+ 'Choose the settings source for this workspace. Project files are repository-controlled and self-contained.',
132
+ currentValue: 'user',
133
+ values: ['user', 'project'],
134
+ },
135
+ {
136
+ id: 'agentScope',
137
+ label: 'Agent scope',
138
+ description: 'Which agent directories to search. Project agents are repository-controlled.',
139
+ currentValue: settings.agentScope,
140
+ values: ['user', 'project', 'both'],
141
+ },
142
+ {
143
+ id: 'includeBundledAgents',
144
+ label: 'Include bundled agents',
145
+ description: 'Add built-in agents (scout, planner, worker, reviewer).',
146
+ currentValue: 'on',
147
+ values: ['on', 'off'],
148
+ },
149
+ {
150
+ id: 'confirmProjectAgents',
151
+ label: 'Confirm project agents',
152
+ description: 'User-only security gate; project files cannot disable confirmation.',
153
+ currentValue: 'on',
154
+ values: ['on', 'off'],
155
+ },
156
+ {
157
+ id: 'keepOpen',
158
+ label: 'Keep tab open after done',
159
+ description: 'Leave the Herdr tab open after completion for inspection.',
160
+ currentValue: 'on',
161
+ values: ['on', 'off'],
162
+ },
163
+ {
164
+ id: 'stayOpen',
165
+ label: 'Keep agent alive after done',
166
+ description: "Keep the agent's pi process alive after completion.",
167
+ currentValue: 'off',
168
+ values: ['on', 'off'],
169
+ },
170
+ {
171
+ id: 'fieldnotes',
172
+ label: 'Enable fieldnotes',
173
+ description: 'Create durable notes for delegated prompts; takes effect next session.',
174
+ currentValue: 'on',
175
+ values: ['on', 'off'],
176
+ },
177
+ {
178
+ id: 'emojiSheep',
179
+ label: 'Use sheep emoji',
180
+ description: 'Show the animated sheep marker beside active agents.',
181
+ currentValue: 'on',
182
+ values: ['on', 'off'],
183
+ },
184
+ {
185
+ id: 'timeout',
186
+ label: 'Default run timeout',
187
+ description: 'Time limit in minutes before a Herdr run is reported timed out.',
188
+ currentValue: TIMEOUT_DISPLAY(settings.timeout),
189
+ values: TIMEOUT_CHOICES.map(TIMEOUT_DISPLAY),
190
+ },
191
+ {
192
+ id: 'staleWaitThreshold',
193
+ label: 'Stale wait reminder',
194
+ description:
195
+ 'Minutes before one reminder for a task waiting on a required reply; off disables reminders.',
196
+ currentValue: STALE_WAIT_DISPLAY(settings.staleWaitThreshold),
197
+ values: STALE_WAIT_CHOICES.map(STALE_WAIT_DISPLAY),
198
+ },
199
+ {
200
+ id: 'backend',
201
+ label: 'Backend',
202
+ description:
203
+ 'Execution backend. auto runs where called from (Herdr TUI or hc app). App-side only; the model never decides.',
204
+ currentValue: settings.backend,
205
+ values: [...BACKEND_CHOICES],
206
+ },
207
+ ];
208
+
209
+ refreshItems(items, settings, cwd);
210
+ let list: SettingsList;
211
+ list = new SettingsList(
212
+ items,
213
+ Math.min(items.length + 2, 12),
214
+ getSettingsListTheme(),
215
+ (id, value) => {
216
+ try {
217
+ const next = applyValue(settings, id, value);
218
+ if (id === 'projectScope') {
219
+ if (value === 'project') {
220
+ const parked = loadProjectFileValues(cwd);
221
+ settings = { ...settings, ...parked, projectScope: true };
222
+ const result = saveSettings(settings, 'project', cwd);
223
+ if (result.created) {
224
+ ctx.ui?.notify?.(
225
+ `Config created at ${path.relative(cwd, result.file) || result.file}`,
226
+ 'info'
227
+ );
228
+ } else {
229
+ ctx.ui?.notify?.('Project settings activated for this workspace.', 'info');
230
+ }
231
+ } else {
232
+ const result = deactivateProjectScope(cwd);
233
+ ctx.ui?.notify?.(
234
+ result.changed
235
+ ? 'Project settings deactivated; user settings are active.'
236
+ : 'Project settings are already inactive.',
237
+ 'info'
238
+ );
239
+ }
240
+ } else if (id === 'confirmProjectAgents' || id === 'backend') {
241
+ // These fields are always persisted in the trusted user layer,
242
+ // even when the menu is showing active project settings. A
243
+ // project file can never force a trust gate or a runtime.
244
+ const userSettings = loadSettings();
245
+ saveSettings(
246
+ {
247
+ ...userSettings,
248
+ confirmProjectAgents:
249
+ id === 'confirmProjectAgents'
250
+ ? next.confirmProjectAgents
251
+ : userSettings.confirmProjectAgents,
252
+ backend: id === 'backend' ? next.backend : userSettings.backend,
253
+ },
254
+ 'user'
255
+ );
256
+ } else {
257
+ const targetScope = settings.projectScope ? 'project' : 'user';
258
+ settings = next;
259
+ saveSettings(settings, targetScope, cwd);
260
+ }
261
+
262
+ settings = loadSettings(cwd);
263
+ refreshItems(items, settings, cwd);
264
+ list.invalidate();
265
+
266
+ const note =
267
+ id === 'agentScope' && settings.agentScope !== 'user'
268
+ ? `${id} = ${value} (project agents are repository-controlled)`
269
+ : id === 'fieldnotes'
270
+ ? `${id} = ${value} (takes effect next pi session)`
271
+ : id === 'confirmProjectAgents'
272
+ ? `${id} = ${value} (user-only security setting)`
273
+ : id === 'backend'
274
+ ? `${id} = ${value} (user-only; model never decides)`
275
+ : `${id} = ${value}`;
276
+ ctx.ui?.notify?.(note, 'info');
277
+ } catch (error) {
278
+ ctx.ui?.notify?.(
279
+ `pi-shepherd: could not save ${id}: ${String((error as Error)?.message ?? error)}`,
280
+ 'error'
281
+ );
282
+ }
283
+ },
284
+ () => done(undefined),
285
+ { enableSearch: true }
286
+ );
287
+ container.addChild(list);
288
+ container.addChild(new DynamicBorder((s: string) => theme.fg('accent', s)));
289
+
290
+ return {
291
+ render: (width: number) => container.render(width),
292
+ invalidate: () => container.invalidate(),
293
+ handleInput: (data: string) => list.handleInput?.(data),
294
+ };
295
+ });
296
+ }