geneseed 5.0.1 → 5.0.4

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 (185) hide show
  1. package/CHANGELOG.md +92 -0
  2. package/README.md +4 -4
  3. package/SHIPPED.md +2 -2
  4. package/adapters/claude-code/README.md +11 -5
  5. package/adapters/openclaude/README.md +3 -1
  6. package/adapters/opencode/HOW-OPENCODE-LOADS.md +3 -0
  7. package/adapters/opencode/plugins/geneseed-context.js +12 -1
  8. package/adapters/opencode/plugins/geneseed-guard.js +594 -73
  9. package/adapters/opencode/plugins/geneseed-learn.js +1 -1
  10. package/adapters/opencode/plugins/geneseed-workflow.js +1 -1
  11. package/adapters/opencode/workflows/_runtime.js +1 -1
  12. package/bin/geneseed-cli.mjs +3 -0
  13. package/bin/geneseed-hook.mjs +31 -9
  14. package/docs/PRD.md +1 -1
  15. package/docs/README.md +4 -1
  16. package/docs/concepts/enforcement-table.md +23 -4
  17. package/docs/concepts/exclusions.md +48 -2
  18. package/docs/concepts/factories.md +151 -0
  19. package/docs/concepts/foreman-mode.md +19 -4
  20. package/docs/concepts/hook-gates.md +1 -1
  21. package/docs/concepts/hooks.md +53 -12
  22. package/docs/concepts/host-matrix.md +5 -3
  23. package/docs/concepts/hosts.md +1 -1
  24. package/docs/concepts/kits.md +18 -0
  25. package/docs/concepts/loop-gates.md +3 -0
  26. package/docs/concepts/loops.md +1 -0
  27. package/docs/concepts/rules.md +1 -1
  28. package/docs/concepts/shared-tier.md +1 -1
  29. package/docs/concepts/skills.md +1 -1
  30. package/docs/extending.md +8 -2
  31. package/docs/guides/autostart.md +29 -3
  32. package/docs/guides/choose-your-setup.md +1 -1
  33. package/docs/guides/migrate.md +1 -1
  34. package/docs/guides/run-a-factory.md +88 -0
  35. package/docs/guides/set-up-ownership.md +1 -0
  36. package/docs/guides/uninstall.md +1 -1
  37. package/docs/reference/factory-actions.md +22 -0
  38. package/docs/reference/loop-actions.md +1 -1
  39. package/docs/reference/plugin-activity.md +1 -1
  40. package/docs/reference/plugin-context.md +1 -1
  41. package/docs/reference/plugin-guard.md +24 -5
  42. package/docs/reference/troubleshoot-doctor.md +2 -2
  43. package/docs/understand/a-day.md +9 -5
  44. package/docs/web-ui.md +101 -17
  45. package/harness.config.json +1 -1
  46. package/js/README.md +21 -3
  47. package/js/build/args.mjs +14 -2
  48. package/js/build/emit-claude.mjs +9 -1
  49. package/js/build/emit-opencode.mjs +2 -1
  50. package/js/build/source.mjs +28 -3
  51. package/js/cli-table.json +287 -3
  52. package/js/factory/cli.mjs +153 -0
  53. package/js/factory/graph.mjs +245 -0
  54. package/js/factory/registry.mjs +71 -0
  55. package/js/factory/state.mjs +429 -0
  56. package/js/hosts/activity.mjs +3 -3
  57. package/js/hosts/geneseed-dir.mjs +2 -2
  58. package/js/hosts/gitref.mjs +21 -0
  59. package/js/hosts/hooks-context.mjs +71 -15
  60. package/js/hosts/hooks-done.mjs +3 -1
  61. package/js/hosts/hooks-learn.mjs +1 -1
  62. package/js/hosts/hooks-prims.mjs +271 -1
  63. package/js/hosts/hooks.mjs +409 -151
  64. package/js/hosts/hosts.mjs +22 -0
  65. package/js/hosts/installs.mjs +9 -5
  66. package/js/hosts/settings.mjs +128 -27
  67. package/js/hosts/shim.mjs +155 -7
  68. package/js/hosts/store-watch.mjs +36 -11
  69. package/js/inspect/checks-authoring.mjs +11 -1
  70. package/js/inspect/cost.mjs +91 -5
  71. package/js/inspect/diff.mjs +2 -1
  72. package/js/inspect/doctor.mjs +2 -1
  73. package/js/inspect/inventory.mjs +2 -1
  74. package/js/inspect/validate.mjs +1 -1
  75. package/js/loop/catalog.mjs +24 -12
  76. package/js/loop/cli.mjs +21 -15
  77. package/js/loop/graph.mjs +13 -4
  78. package/js/loop/registry.mjs +65 -28
  79. package/js/loop/state.mjs +18 -8
  80. package/js/maintain/migrate.mjs +2 -2
  81. package/js/maintain/uninstall.mjs +5 -1
  82. package/js/web/actions.mjs +17 -1
  83. package/js/web/api.mjs +52 -11
  84. package/js/web/catalog.mjs +38 -2
  85. package/js/web/daemon.mjs +136 -6
  86. package/js/web/handler.mjs +14 -5
  87. package/js/web/routes.mjs +12 -4
  88. package/js/web/server.mjs +4 -1
  89. package/package.json +1 -1
  90. package/registry.json +35 -0
  91. package/src/AGENT.md.tmpl +18 -24
  92. package/src/agents/_self-improvement.md +7 -6
  93. package/src/agents/developer.md +3 -2
  94. package/src/agents/docker-expert.md +1 -0
  95. package/src/agents/memory-curator.md +3 -2
  96. package/src/bricks/docs-update.md +5 -0
  97. package/src/bricks/holdout-write.md +23 -0
  98. package/src/bricks/holdout.md +25 -0
  99. package/src/bricks/intake.md +18 -0
  100. package/src/bricks/merge-gate.md +22 -0
  101. package/src/bricks/pr-open.md +21 -0
  102. package/src/bricks/retro.md +17 -0
  103. package/src/bricks/test.md +4 -1
  104. package/src/bricks/triage.md +19 -0
  105. package/src/doctrines/comms.md +29 -41
  106. package/src/doctrines/craft.md +3 -10
  107. package/src/doctrines/ops.md +4 -15
  108. package/src/doctrines/process.md +24 -19
  109. package/src/doctrines/rigor.md +1 -5
  110. package/src/factories/analysis-to-build.json +34 -0
  111. package/src/factories/bug-report-to-fix.json +32 -0
  112. package/src/factories/issue-to-pr.json +49 -0
  113. package/src/kits/ci-pipelines/rules.md +10 -0
  114. package/src/kits/ci-pipelines.json +14 -0
  115. package/src/kits/docker/rules.md +11 -0
  116. package/src/kits/docker.json +12 -0
  117. package/src/memory/README.md +5 -4
  118. package/src/modes/foreman.md +23 -10
  119. package/src/notebook/README.md +1 -1
  120. package/src/skills/_checkpoints.md +1 -0
  121. package/src/skills/_self-improvement.md +12 -9
  122. package/src/skills/adhd.md +1 -1
  123. package/src/skills/compose-ops.md +58 -0
  124. package/src/skills/factory-forge.md +97 -0
  125. package/src/skills/factory.md +126 -0
  126. package/src/skills/gitlab-ci.md +51 -0
  127. package/src/skills/jenkins-pipeline.md +56 -0
  128. package/src/skills/parallel-agents.md +1 -1
  129. package/src/skills/pipeline.md +2 -2
  130. package/src/skills/rule.md +24 -18
  131. package/src/skills/skill-forge.md +24 -6
  132. package/src/skills/workflow.md +2 -1
  133. package/themes/_TEMPLATE.json +9 -4
  134. package/themes/biker.json +9 -4
  135. package/themes/commentator.json +9 -4
  136. package/themes/cyberpunk.json +9 -4
  137. package/themes/gamer.json +9 -4
  138. package/themes/imperial.json +9 -4
  139. package/themes/joker.json +9 -4
  140. package/themes/marvin.json +9 -4
  141. package/themes/mean.json +9 -4
  142. package/themes/military.json +9 -4
  143. package/themes/neutral.json +9 -4
  144. package/themes/pirate.json +9 -4
  145. package/themes/sports.json +9 -4
  146. package/themes/verstappen.json +9 -4
  147. package/themes/wizard.json +9 -4
  148. package/web/dist/assets/ActiveLoops-BTHIaRhn.js +1 -0
  149. package/web/dist/assets/Activity-BaoxwVFH.js +1 -0
  150. package/web/dist/assets/ActivityDetail-C_bFD0rW.js +1 -0
  151. package/web/dist/assets/{Bonsai-C1iBAt4v.js → Bonsai-B01lLf0m.js} +1 -1
  152. package/web/dist/assets/{CopyButton-DJ3a4N88.js → CopyButton-Bc66KPyA.js} +1 -1
  153. package/web/dist/assets/Dashboard-X7GZzGJp.js +2 -0
  154. package/web/dist/assets/{Docs-Kffdg5uV.js → Docs-LRYVnGLG.js} +3 -3
  155. package/web/dist/assets/Factories-ARenKBiP.js +1 -0
  156. package/web/dist/assets/{GreenhouseView-k56_cBSF.js → GreenhouseView-CfWR2-sX.js} +1 -1
  157. package/web/dist/assets/{Installs-DtEKLC9h.js → Installs-nfFHnovH.js} +3 -3
  158. package/web/dist/assets/{JournalView-RQnk5l7I.js → JournalView-lpOHcHKK.js} +1 -1
  159. package/web/dist/assets/Kits-Bw5EQl_i.js +1 -0
  160. package/web/dist/assets/Laws-CnZJ0wjZ.js +4 -0
  161. package/web/dist/assets/LibRows-Hqvf1beK.js +1 -0
  162. package/web/dist/assets/Library-JaSsp6Yr.js +3 -0
  163. package/web/dist/assets/Loops-ZaHC5MVl.js +2 -0
  164. package/web/dist/assets/{OperatorHudView-CM5jNPwL.js → OperatorHudView-CggG0_sK.js} +1 -1
  165. package/web/dist/assets/Personal-BObvlb70.js +2 -0
  166. package/web/dist/assets/Settings-BFfPMPc9.js +1 -0
  167. package/web/dist/assets/Tabs-B594Pad_.js +1 -0
  168. package/web/dist/assets/api-DLDVY3K-.js +1 -0
  169. package/web/dist/assets/index-DsLmKHw0.js +6 -0
  170. package/web/dist/assets/index-DvPjphz0.css +1 -0
  171. package/web/dist/index.html +3 -3
  172. package/web/dist/assets/Activity-Ci4PZco3.js +0 -1
  173. package/web/dist/assets/ActivityDetail-C8hroCND.js +0 -1
  174. package/web/dist/assets/Dashboard-C_On4KXw.js +0 -2
  175. package/web/dist/assets/Kits-CXkEBpnf.js +0 -1
  176. package/web/dist/assets/Laws-DhhIVqmh.js +0 -3
  177. package/web/dist/assets/Library-CAUiEoJo.js +0 -3
  178. package/web/dist/assets/Loops-LKD8mF4E.js +0 -2
  179. package/web/dist/assets/Personal-B6Uoly3C.js +0 -2
  180. package/web/dist/assets/RailCats-DQxxYBEP.js +0 -1
  181. package/web/dist/assets/Settings-BTe6-wda.js +0 -1
  182. package/web/dist/assets/Tabs-CbdDWTp_.js +0 -1
  183. package/web/dist/assets/api-D_r0Jtla.js +0 -1
  184. package/web/dist/assets/index-HfGmYXab.js +0 -3
  185. package/web/dist/assets/index-ao3M-Fhm.css +0 -1
@@ -26,7 +26,8 @@ import {
26
26
  } from './checks-repo.mjs';
27
27
  import { constitutionProblems, leanBlockProblems } from './checks-constitution.mjs';
28
28
  import { countTableProblems, kitProblems } from './checks-counts.mjs';
29
- import { catalogProblems } from '../loop/catalog.mjs';
29
+ import { catalogProblems, loadCatalog } from '../loop/catalog.mjs';
30
+ import { factoryCatalogProblems } from '../factory/graph.mjs';
30
31
  import { globSorted, isDir, isFile, rglob } from './scan.mjs';
31
32
  import { spawnSync } from 'node:child_process';
32
33
 
@@ -126,6 +127,15 @@ export function loopProblems() {
126
127
  return catalogProblems({ projectRoot: null, globalLevel: false });
127
128
  }
128
129
 
130
+ /**
131
+ * The shipped factories parse and pass `checkFactory` against the shipped bricks and loops —
132
+ * `loopProblems`' twin, same scope. `opts` reaches `loadCatalog`, so a test can point the gate
133
+ * at a fixture `srcRoot` and see it redden while no factory ships yet.
134
+ */
135
+ export function factoryProblems(opts = {}) {
136
+ return factoryCatalogProblems(loadCatalog({ projectRoot: null, globalLevel: false, ...opts }));
137
+ }
138
+
129
139
  /**
130
140
  * Author-time gates on the source specs and plugins.
131
141
  *
@@ -25,6 +25,7 @@ import { emittedHost, sessionFiles, tierSessionChars } from '../hosts/hooks-cont
25
25
  import { carriersFor } from '../hosts/installs.mjs';
26
26
  import { frontmatter } from '../hosts/memory-files.mjs';
27
27
  import { listDir } from '../hosts/hooks-prims.mjs';
28
+ import { liveRecordedHooks } from '../hosts/hosts.mjs';
28
29
  import { loadJsonObject, opencodeTarget } from '../hosts/settings.mjs';
29
30
  import { isDict } from '../lib/json.mjs';
30
31
  import { isFile, readText } from '../lib/fs.mjs';
@@ -35,7 +36,7 @@ import { isFile, readText } from '../lib/fs.mjs';
35
36
  * console draws it on the cost chart, so it lives here, once, where both read it. Raise it by
36
37
  * exactly the measured overrun and say why in that test's docblock, which keeps its history.
37
38
  */
38
- export const CARRIER_CEILING = { full: 66_432, lean: 41_612 };
39
+ export const CARRIER_CEILING = { full: 66_432, lean: 40_312 };
39
40
 
40
41
  /**
41
42
  * THE TRADE OF `--shared-tier on`, stated once. `--help` (js/cli-table.json), the console's toggle
@@ -111,10 +112,25 @@ function userOnlyTest(host, root) {
111
112
  * carrier answers `null` for the whole cost, so the console shows "not measured", not a tiny bar.
112
113
  */
113
114
  export function alwaysOnCost({ host, root, dir, footprint }) {
114
- const carrierPath = carriersFor(host).map((rel) => path.join(root, rel)).find(isFile);
115
+ const carrierPath = carrierOf(host, root);
115
116
  if (!carrierPath) return null;
116
117
  const carrier = readText(carrierPath).length;
118
+ const { skills, agents } = catalogueChars(host, root, dir);
119
+ let context = 0;
120
+ for (const s of sessionLayers(dir, host)) context += s.text.length;
121
+ return { carrier, skills, agents, context, ceiling: CARRIER_CEILING[footprint] ?? null };
122
+ }
123
+
124
+ /** The install's root instruction file, or undefined: the first of the host's carriers on disk. */
125
+ const carrierOf = (host, root) => carriersFor(host).map((rel) => path.join(root, rel)).find(isFile);
126
+
127
+ /** The session files the context hook injects, `[]` when none can be read. */
128
+ function sessionLayers(dir, host) {
129
+ try { return sessionFiles(dir, emittedHost(host)); } catch { return []; }
130
+ }
117
131
 
132
+ /** The skill and agent catalogues the model lists, in characters: `alwaysOnCost`'s two parts. */
133
+ function catalogueChars(host, root, dir) {
118
134
  let skills = 0;
119
135
  const skillsDir = path.join(dir, 'skills');
120
136
  const userOnly = userOnlyTest(host, root);
@@ -129,8 +145,78 @@ export function alwaysOnCost({ host, root, dir, footprint }) {
129
145
  if (name.endsWith('.md')) agents += listedChars(path.join(agentsDir, name), name.slice(0, -3));
130
146
  }
131
147
  }
132
- let context = 0;
133
- try { for (const s of sessionFiles(dir, emittedHost(host))) context += s.text.length; } catch { /* none */ }
148
+ return { skills, agents };
149
+ }
134
150
 
135
- return { carrier, skills, agents, context, ceiling: CARRIER_CEILING[footprint] ?? null };
151
+ /**
152
+ * The carrier cut into its `## ` sections, by index, so the slices add up to the whole file: the
153
+ * text above the first heading is a block of its own. `id` is the heading's slug.
154
+ */
155
+ function rootSections(text) {
156
+ const starts = [0, ...[...text.matchAll(/^## .*$/gm)].map((m) => m.index).filter((i) => i > 0)];
157
+ return starts.map((at, i) => {
158
+ const slice = text.slice(at, starts[i + 1] ?? text.length);
159
+ const head = /^## (.*)/.exec(slice);
160
+ const label = head ? head[1].trim() : 'Preamble';
161
+ const id = `root:${label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'preamble'}`;
162
+ return { id, label, chars: slice.length, source: 'root', loadedBy: 'host' };
163
+ });
164
+ }
165
+
166
+ /**
167
+ * Is the user-rules hook wired for a sub-agent of this install? `'wired'` when the emitted settings
168
+ * run `context` on SubagentStart, `'not-wired'` for an install emitted before (it runs `activity`
169
+ * there: re-emit), `'no-event'` for a host with no SubagentStart wiring at all (OpenCode until its
170
+ * slice lands, and Bob, whose strict schema has no such event).
171
+ */
172
+ export function subagentDelivery(host, dir) {
173
+ if (host !== 'claude' && host !== 'openclaude') return 'no-event';
174
+ return liveRecordedHooks(dir).some(([event, h]) => event === 'SubagentStart' && h.command.includes(' context --'))
175
+ ? 'wired' : 'not-wired';
176
+ }
177
+
178
+ /**
179
+ * WHAT ONE AGENT LOADS, block by block, in load order (spec 2026-11-08, agent loadout, D10–D11):
180
+ * the root file by section, the session files (the primary) or the user rules (a sub-agent), the
181
+ * two catalogues, and an Adept's own spec. THE SAME MEASUREMENTS AS `alwaysOnCost`, through the
182
+ * same helpers, so the console can never claim a load the emit does not produce: the root
183
+ * sections add up to `carrier`, the session block is `context`, the catalogues are `skills` and
184
+ * `agents` (tests/unit/agent_loadout.test.mjs holds the sums equal).
185
+ *
186
+ * `agent` is `'primary'` or an agent file's stem in `<dir>/agents/`; a stem with no file answers
187
+ * null, as does a missing carrier ("not measured"). The user-rules block counts the tier and the
188
+ * install's raw file sizes; the project root's own `user-rules.md` depends on the session's working
189
+ * dir and is listed under `notCounted`, as is everything the host loads that Geneseed did not write.
190
+ * Rules (`rules`) are the console's to add: they come from the install's inventory, not its files.
191
+ */
192
+ export function agentLoadout({ host, root, dir, agent = 'primary' }) {
193
+ const carrierPath = carrierOf(host, root);
194
+ if (!carrierPath) return null;
195
+ const primary = agent === 'primary';
196
+ let spec = null;
197
+ if (!primary) {
198
+ const f = path.join(dir, 'agents', `${agent}.md`);
199
+ if (host === 'bob' || !isFile(f)) return null;
200
+ spec = frontmatter(readText(f))[1];
201
+ }
202
+ /** @type {Array<{ id: string, label: string, chars: number, source: string, loadedBy: string, delivery?: string }>} */
203
+ const blocks = rootSections(readText(carrierPath));
204
+ const session = sessionLayers(dir, host);
205
+ const sum = (list) => list.reduce((n, s) => n + s.text.length, 0);
206
+ const delivery = primary ? null : subagentDelivery(host, dir);
207
+ if (primary) {
208
+ blocks.push({ id: 'session-files', label: 'session files (project context not counted)',
209
+ chars: sum(session), source: 'session', loadedBy: 'session-hook' });
210
+ } else {
211
+ blocks.push({ id: 'user-rules', label: 'user rules', delivery,
212
+ chars: delivery === 'wired' ? sum(session.filter((s) => s.rel === 'user-rules.md')) : 0,
213
+ source: 'user-rules', loadedBy: 'subagent-hook' });
214
+ }
215
+ const { skills, agents } = catalogueChars(host, root, dir);
216
+ blocks.push({ id: 'skills', label: 'skill catalogue', chars: skills, source: 'catalogue', loadedBy: 'host' });
217
+ blocks.push({ id: 'agents', label: 'agent catalogue', chars: agents, source: 'catalogue', loadedBy: 'host' });
218
+ if (spec !== null) blocks.push({ id: 'spec', label: `${agent} spec`, chars: spec.length, source: 'spec', loadedBy: 'host' });
219
+ const notCounted = ['host system prompt and tools', 'files outside Geneseed (other CLAUDE.md content)'];
220
+ if (!primary) notCounted.push("the project root's own user-rules.md (it depends on the working dir)");
221
+ return { agent, host, blocks, notCounted };
136
222
  }
@@ -420,7 +420,8 @@ export function improvementsMd(target, theme, allFiles, when, notes = []) {
420
420
  if (notes.length) {
421
421
  lines.push('# Self-improvement notes', '',
422
422
  'Corrections the agent recorded against a skill or agent instead of editing it.',
423
- 'Fold each one into the matching file under `src/`, then clear the note. Judge it by',
423
+ 'Folding one into the matching file under `src/` is the user\'s call: run the skill-forge',
424
+ 'probe first (unless it is a trivial wording fix), then clear the note. Judge it by',
424
425
  'its `seen:` evidence — a line without one is a claim, not a lesson — and weigh a',
425
426
  '`[general]` line as a law, doctrine or memory rather than an edit to that one file.', '');
426
427
  for (const n of notes) {
@@ -39,7 +39,7 @@ import {
39
39
  } from '../hosts/installs.mjs';
40
40
  import { validateIsVendored } from '../hosts/native.mjs';
41
41
  import { printOut } from '../lib/fs.mjs';
42
- import { authoringProblems, loopProblems } from './checks-authoring.mjs';
42
+ import { authoringProblems, factoryProblems, loopProblems } from './checks-authoring.mjs';
43
43
  import { gateProbe, guardProbe } from './checks-probe.mjs';
44
44
  import {
45
45
  checkBuild, colorThemeProblems, renderedPathNotes, renderedProblems, themeParityProblems,
@@ -239,6 +239,7 @@ export function doctorCollect({
239
239
  problems = problems.concat(ran('colors', 'Colour themes', colorThemeProblems()));
240
240
  problems = problems.concat(ran('authoring', 'Authoring gates', authoringProblems()));
241
241
  problems = problems.concat(ran('loops', 'Loop catalogue', loopProblems()));
242
+ problems = problems.concat(ran('factories', 'Factory catalogue', factoryProblems()));
242
243
  problems = problems.concat(ran('shim', 'Hook shim', shimProbs));
243
244
  // Windows: a Claude install's hooks emitted for Git Bash on a machine that no longer has it
244
245
  // misbehave under PowerShell — context/learn fail open, and the two gates fail CLOSED
@@ -87,13 +87,14 @@ export const LAW_CLASSES = ['security', 'process', 'verify', 'craft', 'context',
87
87
  export const SKILL_CLASS = {
88
88
  brainstorm: 'design', plan: 'design', council: 'design',
89
89
  workflow: 'design', 'parallel-agents': 'design', pipeline: 'design',
90
- loop: 'design', 'brick-forge': 'design',
90
+ loop: 'design', factory: 'design', 'brick-forge': 'design', 'factory-forge': 'design',
91
91
  'codebase-design': 'design', wayfinder: 'design',
92
92
  develop: 'build', refactor: 'build', debug: 'build', dependencies: 'build',
93
93
  'frontend-design': 'build', prototype: 'build', deck: 'build',
94
94
  'forge-mcp': 'build', bruno: 'build', worktree: 'build', ownership: 'build',
95
95
  'spring-boot': 'build', 'spring-data-jpa': 'build', 'spring-testing': 'build',
96
96
  react: 'build', 'react-testing': 'build',
97
+ 'jenkins-pipeline': 'build', 'gitlab-ci': 'build', 'compose-ops': 'build',
97
98
  'geneseed-code-review': 'review', 'fresh-eyes': 'review', 'security-audit': 'review',
98
99
  'roast-me': 'review', 'review-response': 'review', ponytail: 'review',
99
100
  commit: 'ship', ship: 'ship', release: 'ship', handoff: 'ship',
@@ -35,7 +35,7 @@ export const VALIDATE_USAGE = [
35
35
  ' [--footprint {lean,full}] [--posture POSTURE] [--mode MODE]',
36
36
  ' [--trust TRUST] [--doctrines DOCTRINES] [--exclude-rules RULES]',
37
37
  ' [--exclude-skills SKILLS] [--kits KITS] [--shared-tier on|off] [--no-secrets-gate]',
38
- ' [--no-done-gate] [--no-deletion-gate] [-v]',
38
+ ' [--no-done-gate] [--no-deletion-gate] [--no-external-gate] [--no-test-note] [-v]',
39
39
  '',
40
40
  "Render and emit into a throwaway sandbox, run the doctor's checks, and write nothing real.",
41
41
  "Takes the generator's render flags (see geneseed-build --help) except --sync-themes and",
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Where bricks and loop templates come from, and which one wins.
2
+ * Where bricks, loop templates and factories come from, and which one wins.
3
3
  *
4
4
  * THREE ORIGINS, ONE LADDER. Shipped (this package's own `src/`), global (the user's, beside
5
5
  * `installs.json` under XDG) and project (`<repo>/.geneseed/`, committed, shared with a team).
@@ -86,17 +86,16 @@ function availability(brick, srcRoot) {
86
86
  export function loadCatalog({
87
87
  projectRoot = process.cwd(), srcRoot = SRC, globalLevel = true,
88
88
  } = {}) {
89
- const levels = [
90
- ['shipped', path.join(srcRoot, 'bricks'), path.join(srcRoot, 'loops')],
91
- ];
92
- if (globalLevel) {
93
- levels.push(['global', path.join(userLoopsDir(), 'bricks'), path.join(userLoopsDir(), 'loops')]);
94
- }
95
- if (projectRoot) {
96
- levels.push(['project', path.join(projectRoot, '.geneseed', 'bricks'), path.join(projectRoot, '.geneseed', 'loops')]);
97
- }
89
+ const levels = [['shipped', srcRoot]];
90
+ if (globalLevel) levels.push(['global', userLoopsDir()]);
91
+ if (projectRoot) levels.push(['project', path.join(projectRoot, '.geneseed')]);
98
92
  const bricks = new Map(); const templates = new Map(); const problems = []; const overridden = [];
99
- for (const [origin, brickDir, loopDir] of levels) {
93
+ // Factories (`js/factory/`) are a third directory per level, same stem rule. Their parse
94
+ // problems stay apart from `problems`: that list is `catalogProblems`' and so `loop check`'s,
95
+ // and a broken factory file must not fail a loop.
96
+ const factories = new Map(); const factoryProblems = [];
97
+ for (const [origin, dir] of levels) {
98
+ const brickDir = path.join(dir, 'bricks'); const loopDir = path.join(dir, 'loops');
100
99
  for (const f of listFiles(brickDir, '.md')) {
101
100
  const { brick, problems: p } = parseBrick(readText(path.join(brickDir, f)), origin);
102
101
  problems.push(...p.map((x) => `bricks/${f} (${origin}): ${x}`));
@@ -117,8 +116,21 @@ export function loadCatalog({
117
116
  }
118
117
  templates.set(stem, { ...graph, origin });
119
118
  }
119
+ const factoryDir = path.join(dir, 'factories');
120
+ for (const f of listFiles(factoryDir, '.json')) {
121
+ let factory;
122
+ try { factory = JSON.parse(readText(path.join(factoryDir, f))); } catch {
123
+ factoryProblems.push(`factories/${f}: not JSON`); continue;
124
+ }
125
+ const stem = f.slice(0, -'.json'.length);
126
+ if (factory?.name !== stem) {
127
+ factoryProblems.push(`factories/${f}: name ${JSON.stringify(factory?.name)} does not match the file name`);
128
+ continue;
129
+ }
130
+ factories.set(stem, { ...factory, origin });
131
+ }
120
132
  }
121
- return { bricks, templates, problems, overridden: overridden.sort() };
133
+ return { bricks, templates, problems, overridden: overridden.sort(), factories, factoryProblems };
122
134
  }
123
135
 
124
136
  /** `catalog`: an already-loaded `loadCatalog(opts)`, for a caller that needs the catalogue
package/js/loop/cli.mjs CHANGED
@@ -82,6 +82,23 @@ function resolveGraph(spec, catalog) {
82
82
  return graph;
83
83
  }
84
84
 
85
+ /**
86
+ * The note of `init` or `record`: `--note`, or `--note-file`'s content. A note too long for a
87
+ * shell argument, or one that mentions `git … commit`/`push` (and would otherwise sit inside the
88
+ * command line GIT_GATE_RE matches whole), goes through a file instead — never through the shell
89
+ * at all. CRLF-folded and trimmed the same way the porcelain stdin is, so a Windows-authored file
90
+ * round-trips identically.
91
+ */
92
+ function noteOf(args, action) {
93
+ if (args.note && args.noteFile) throw new Error(`${action} takes --note or --note-file, not both`);
94
+ if (!args.noteFile) return args.note ?? '';
95
+ let raw;
96
+ try { raw = readText(path.resolve(args.noteFile)); } catch (e) {
97
+ throw new Error(`cannot read --note-file ${args.noteFile}: ${e.message}`, { cause: e });
98
+ }
99
+ return raw.replace(/\r\n/g, '\n').trimEnd();
100
+ }
101
+
85
102
  const ACTIONS = {
86
103
  check(args) {
87
104
  // The project level of the catalogue is `<git root>/.geneseed/`, as for `init` and `next`,
@@ -116,18 +133,19 @@ const ACTIONS = {
116
133
  const file = path.join(root, LOOP_FILE);
117
134
  if (isFile(file)) throw new Error(`${file} already exists — a loop is already running here`);
118
135
  if (!args.title || !args.requirement || !args.graph) throw new Error('init needs --title, --requirement and --graph');
136
+ const note = noteOf(args, 'init');
119
137
  const catalog = loadCatalog({ projectRoot: root });
120
138
  const graph = resolveGraph(args.graph, catalog);
121
139
  const problems = checkGraph(graph, catalog.bricks);
122
140
  if (problems.length) return { error: 'the graph does not pass loop check', problems };
123
141
  const state = initState({
124
142
  title: args.title, requirement: args.requirement, graph, preset: args.preset || DEFAULT_PRESET,
125
- contracts: list(args.contracts) ?? [],
143
+ contracts: list(args.contracts) ?? [], notes: note ? [note] : [],
126
144
  });
127
145
  writeLoopFile(file, state);
128
146
  // Best-effort: the registry is how the Active tab discovers this loop, but a registry
129
147
  // hiccup must never fail the init the loop itself just succeeded at.
130
- recordLoop({ root, branch: currentBranch(root), title: args.title });
148
+ recordLoop({ root, branch: currentBranch(root), title: args.title, factory: args.factory ?? null });
131
149
  return { file, graph: graph.name, preset: state.preset, status: state.status };
132
150
  },
133
151
  next: () => withState((s, b) => nextStep(s, b), { write: false }),
@@ -146,19 +164,7 @@ const ACTIONS = {
146
164
  },
147
165
  record(args) {
148
166
  if (!args.outcome) throw new Error('record needs --outcome');
149
- if (args.note && args.noteFile) throw new Error('record takes --note or --note-file, not both');
150
- let note = args.note ?? '';
151
- if (args.noteFile) {
152
- // A note too long for a shell argument, or one that mentions `git … commit`/`push` (and
153
- // would otherwise sit inside the command line GIT_GATE_RE matches whole), goes through a
154
- // file instead — never through the shell at all. CRLF-folded and trimmed the same way the
155
- // porcelain stdin below is, so a Windows-authored file round-trips identically.
156
- let raw;
157
- try { raw = readText(path.resolve(args.noteFile)); } catch (e) {
158
- throw new Error(`cannot read --note-file ${args.noteFile}: ${e.message}`, { cause: e });
159
- }
160
- note = raw.replace(/\r\n/g, '\n').trimEnd();
161
- }
167
+ const note = noteOf(args, 'record');
162
168
  let card = null;
163
169
  if (args.card) {
164
170
  try { card = JSON.parse(args.card); } catch (e) {
package/js/loop/graph.mjs CHANGED
@@ -53,6 +53,18 @@ function components(nodes, edges) {
53
53
  return out;
54
54
  }
55
55
 
56
+ /**
57
+ * Rule 4 on its own: every cycle (strongly connected component) whose nodes no single declared
58
+ * `loops` entry holds, each as its sorted node names joined by `, `. Exported for the factory
59
+ * graph (`js/factory/graph.mjs`), whose `cycles` follow the same rule; each caller words the
60
+ * problem itself, so a loop's message stays byte-identical.
61
+ */
62
+ export function undeclaredCycles(nodes, edges, loops) {
63
+ return components(nodes, edges)
64
+ .filter((comp) => !loops.some((l) => comp.every((n) => (l.nodes ?? []).includes(n))))
65
+ .map((comp) => comp.join(', '));
66
+ }
67
+
56
68
  export function checkGraph(graph, bricks) {
57
69
  const problems = [];
58
70
  const nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
@@ -112,10 +124,7 @@ export function checkGraph(graph, bricks) {
112
124
  const iterations = loops.filter((l) => l.iteration === true).length;
113
125
  if (iterations !== 1) problems.push(`${iterations} loops are marked iteration; exactly one must be`);
114
126
  // rule 4 — every cycle is inside a declared loop
115
- for (const comp of components(nodes, edges)) {
116
- const covered = loops.some((l) => comp.every((n) => (l.nodes ?? []).includes(n)));
117
- if (!covered) problems.push(`cycle ${comp.join(', ')} has no declared loop around it`);
118
- }
127
+ for (const cycle of undeclaredCycles(nodes, edges, loops)) problems.push(`cycle ${cycle} has no declared loop around it`);
119
128
  // rule 4b — a cycle that never reaches the iteration head needs its own non-iteration loop
120
129
  const iterationLoops = loops.filter((l) => l.iteration === true);
121
130
  if (iterationLoops.length === 1) {
@@ -1,8 +1,9 @@
1
1
  /**
2
2
  * The loop registry — `<userLoopsDir()>/loops.json` — the list of worktrees `geneseed loop init`
3
3
  * has launched a loop in. `LOOP.md` stays the only source of loop STATE; this file stores
4
- * identity only (root, branch, title, started, finishedAt), so the Active tab can discover a
5
- * loop without scanning every worktree on the machine.
4
+ * identity only (root, branch, title, started, initAt, finishedAt, and `factory` for a loop that
5
+ * is a factory stage), so the Active tab can discover
6
+ * a loop without scanning every worktree on the machine.
6
7
  *
7
8
  * WRITER CONVENTIONS, mirrored from `js/inspect/registry.mjs` (`installs.json`'s own registry)
8
9
  * on purpose rather than invented fresh: `jsonDumpsIndent` because these rows are absolute
@@ -51,32 +52,39 @@ export function registryPath() {
51
52
  return path.join(userLoopsDir(), 'loops.json');
52
53
  }
53
54
 
54
- function load() {
55
+ /**
56
+ * The rows under `key` in the registry `file`, `[]` when it is missing or corrupt. Exported with
57
+ * `saveRows`, `normalize`, `sameRoot` and `sweepRows` for `js/factory/registry.mjs`: its
58
+ * `factories.json` follows every convention of this file, so the two share the code, not a copy.
59
+ */
60
+ export function loadRows(file, key) {
55
61
  try {
56
- const data = parseJson(readFileSync(registryPath(), 'utf8'));
57
- return Array.isArray(data?.loops) ? data.loops.filter((l) => l && typeof l.root === 'string') : [];
62
+ const data = parseJson(readFileSync(file, 'utf8'));
63
+ return Array.isArray(data?.[key]) ? data[key].filter((l) => l && typeof l.root === 'string') : [];
58
64
  } catch {
59
65
  return [];
60
66
  }
61
67
  }
62
68
 
63
- function save(loops) {
69
+ export function saveRows(file, key, rows) {
64
70
  try {
65
- const file = registryPath();
66
71
  mkdirSync(path.dirname(file), { recursive: true });
67
72
  const tmp = `${file}.tmp`;
68
- writeText(tmp, `${jsonDumpsIndent({ loops })}\n`);
73
+ writeText(tmp, `${jsonDumpsIndent({ [key]: rows })}\n`);
69
74
  renameWithRetry(tmp, file);
70
75
  } catch {
71
76
  /* best-effort: a registry hiccup must never fail init or a read */
72
77
  }
73
78
  }
74
79
 
75
- function normalize(dir) {
80
+ const load = () => loadRows(registryPath(), 'loops');
81
+ const save = (loops) => saveRows(registryPath(), 'loops', loops);
82
+
83
+ export function normalize(dir) {
76
84
  try { return realpathSync.native(dir); } catch { return path.resolve(dir); }
77
85
  }
78
86
 
79
- const sameRoot = (a, b) => normcase(a) === normcase(b);
87
+ export const sameRoot = (a, b) => normcase(a) === normcase(b);
80
88
 
81
89
  function runningRow(entry, state) {
82
90
  return {
@@ -89,27 +97,43 @@ function runningRow(entry, state) {
89
97
 
90
98
  /**
91
99
  * Upsert `root`'s identity row. Called by `geneseed loop init` right after `LOOP.md` is
92
- * written — `started` is set once, on insert, and never moved by a later call. An update never
100
+ * written — `started` is set once, on insert, and never moved by a later call. `initAt` is set on
101
+ * EVERY call: `init` refuses while a LOOP.md exists, so each call starts a fresh loop, and
102
+ * `initAt` is the time of the latest one (`loopInitAt`, the factory's R2 evidence). An update never
93
103
  * touches `finishedAt` either way: `activeLoops` is the only writer of that field, and it will
94
104
  * clear it on the very next poll once it sees LOOP.md present again. Never throws: an `init`
95
105
  * must succeed even when the registry itself cannot be written.
96
106
  */
97
- export function recordLoop({ root, branch, title, now = new Date() }) {
107
+ export function recordLoop({ root, branch, title, factory = null, now = new Date() }) {
98
108
  try {
99
109
  const key = normalize(root);
100
110
  const loops = load();
101
111
  const idx = loops.findIndex((l) => sameRoot(l.root, key));
102
- if (idx >= 0) {
103
- loops[idx] = { ...loops[idx], root: key, branch, title };
104
- } else {
105
- loops.push({ root: key, branch, title, started: now.toISOString() });
106
- }
112
+ const initAt = now.toISOString();
113
+ const row = idx >= 0
114
+ ? { ...loops[idx], root: key, branch, title, initAt }
115
+ : { root: key, branch, title, started: initAt, initAt };
116
+ // The factory run this loop is a stage of (`loop init --factory <slug>`). A later plain
117
+ // `loop init` in the same worktree is a stage of no run, so the field drops.
118
+ if (factory) row.factory = factory; else delete row.factory;
119
+ if (idx >= 0) loops[idx] = row; else loops.push(row);
107
120
  save(loops);
108
121
  } catch {
109
122
  /* a registry hiccup must never fail loop init */
110
123
  }
111
124
  }
112
125
 
126
+ /**
127
+ * The `initAt` of `root`'s row, or null (no row, a row from before the field, an unreadable
128
+ * registry). READ-ONLY, unlike `activeLoops`: `geneseed factory record` calls it, and a record
129
+ * must not prune or stamp rows.
130
+ */
131
+ export function loopInitAt(root) {
132
+ const key = normalize(root);
133
+ const row = load().find((l) => sameRoot(l.root, key));
134
+ return typeof row?.initAt === 'string' ? row.initAt : null;
135
+ }
136
+
113
137
  /**
114
138
  * The rows the Active tab renders, read fresh off every registered worktree's `LOOP.md` —
115
139
  * never off the registry's own stale copy of a loop's state. Four outcomes per row; the
@@ -128,19 +152,33 @@ export function recordLoop({ root, branch, title, now = new Date() }) {
128
152
  * that frozen `finishedAt`, at which point the row is dropped (and the drop is saved).
129
153
  */
130
154
  export function activeLoops({ now = new Date() } = {}) {
131
- const loops = load();
155
+ const { kept, rows, changed } = sweepRows(load(), {
156
+ stateFile: LOOP_FILE, parse: parseLoopFile, project: runningRow, now,
157
+ identity: (e) => ({ root: e.root, branch: e.branch, title: e.title, started: e.started }),
158
+ });
159
+ if (changed) save(kept);
160
+ return rows;
161
+ }
162
+
163
+ /**
164
+ * `activeLoops`' four outcomes, over any registry whose rows name a state file at their root:
165
+ * `parse` reads that file, `project(entry, state)` builds a running row, `identity(entry)` the row
166
+ * of an unreadable or finished one. Returns the rows, the entries to keep, and whether keeping
167
+ * them differs from what was loaded — the only case in which the caller saves.
168
+ */
169
+ export function sweepRows(entries, { stateFile, parse, project, identity, now }) {
132
170
  const kept = [];
133
171
  const rows = [];
134
172
  let changed = false;
135
- for (const entry of loops) {
173
+ for (const entry of entries) {
136
174
  if (!isDir(entry.root)) { changed = true; continue; }
137
- const file = path.join(entry.root, LOOP_FILE);
138
- const identity = { root: entry.root, branch: entry.branch, title: entry.title, started: entry.started };
175
+ const file = path.join(entry.root, stateFile);
176
+ const id = identity(entry);
139
177
  if (isFile(file)) {
140
178
  let state;
141
- try { state = parseLoopFile(readText(file)); } catch {
179
+ try { state = parse(readText(file)); } catch {
142
180
  kept.push(entry);
143
- rows.push({ ...identity, status: 'unreadable' });
181
+ rows.push({ ...id, status: 'unreadable' });
144
182
  continue;
145
183
  }
146
184
  let next = entry;
@@ -148,23 +186,22 @@ export function activeLoops({ now = new Date() } = {}) {
148
186
  next = { ...entry }; delete next.finishedAt; changed = true;
149
187
  }
150
188
  kept.push(next);
151
- rows.push(runningRow(next, state));
189
+ rows.push(project(next, state));
152
190
  continue;
153
191
  }
154
192
  if (entry.finishedAt === undefined) {
155
193
  const next = { ...entry, finishedAt: now.toISOString() };
156
194
  changed = true;
157
195
  kept.push(next);
158
- rows.push({ ...identity, status: 'finished' });
196
+ rows.push({ ...id, status: 'finished' });
159
197
  continue;
160
198
  }
161
199
  const age = now.getTime() - new Date(entry.finishedAt).getTime();
162
200
  if (age > SEVEN_DAYS_MS) { changed = true; continue; }
163
201
  kept.push(entry);
164
- rows.push({ ...identity, status: 'finished' });
202
+ rows.push({ ...id, status: 'finished' });
165
203
  }
166
- if (changed) save(kept);
167
- return rows;
204
+ return { kept, rows, changed };
168
205
  }
169
206
 
170
207
  /**
package/js/loop/state.mjs CHANGED
@@ -35,6 +35,12 @@
35
35
  * that window is the one case it lingers), and `LOOP_FILE_TMP` joins `LOOP_FILE` in both
36
36
  * `filterPorcelain` and `scoreDiff`'s exclusion below for exactly that case: a lingering
37
37
  * `LOOP.md.tmp` is the engine's own bookkeeping too, never scored work.
38
+ *
39
+ * `ENGINE_FILES` is that exclusion, one list for both filters, and it holds `FACTORY.md` (and its
40
+ * `.tmp`) too: a factory run keeps its own state file beside LOOP.md in the same worktree
41
+ * (`js/factory/state.mjs`), rewritten by every `geneseed factory` action, so to a child loop it is
42
+ * bookkeeping exactly as LOOP.md is: scoring it would charge every loop unit for the factory's
43
+ * transitions, and a read brick would "write" whenever the factory moved.
38
44
  */
39
45
  import { renameSync, unlinkSync } from 'node:fs';
40
46
  import { writeText } from '../lib/fs.mjs';
@@ -46,6 +52,7 @@ const END = '<!-- loop-state:end -->';
46
52
  const VERIFY_COMMAND = 'git add -A && git diff --cached --numstat | geneseed loop score --diff';
47
53
  export const LOOP_FILE = 'LOOP.md';
48
54
  const LOOP_FILE_TMP = `${LOOP_FILE}.tmp`;
55
+ export const ENGINE_FILES = new Set([LOOP_FILE, LOOP_FILE_TMP, 'FACTORY.md', 'FACTORY.md.tmp']);
49
56
  const slash = (p) => String(p).replaceAll('\\', '/');
50
57
 
51
58
  export function renderLoopFile(state) {
@@ -104,9 +111,10 @@ const fmt = (n) => Number(n).toFixed(1);
104
111
  /**
105
112
  * `contracts`: extra globs (`loop init --contracts`), appended after the graph's own. Every
106
113
  * field the engine ever writes is listed here, `gateAmends` included (`decideGate` still reads
107
- * it with `?.`, for a LOOP.md written before it was listed).
114
+ * it with `?.`, for a LOOP.md written before it was listed). `notes`: the notes the loop starts
115
+ * with, for a loop a factory re-enters after a failure (its `carry`, D16) — empty otherwise.
108
116
  */
109
- export function initState({ title, requirement, graph, preset = DEFAULT_PRESET, contracts = [] }) {
117
+ export function initState({ title, requirement, graph, preset = DEFAULT_PRESET, contracts = [], notes = [] }) {
110
118
  if (!Object.hasOwn(PRESETS, preset)) throw new Error(`unknown preset ${JSON.stringify(preset)}`);
111
119
  const loop = iterationLoop(graph);
112
120
  const state = {
@@ -115,7 +123,7 @@ export function initState({ title, requirement, graph, preset = DEFAULT_PRESET,
115
123
  iteration: loop.nodes.includes(graph.start) ? 1 : 0,
116
124
  card: null, validated: false, pendingVerify: false, closing: false, counters: {},
117
125
  resplit: false, emptyStreak: 0, snapshot: '', visited: [], tests: 'n/a', current: {},
118
- notes: [], history: [], gateAmends: {},
126
+ notes: [...notes], history: [], gateAmends: {},
119
127
  };
120
128
  if (preset === 'prudent') { state.status = 'awaiting'; state.awaiting = { kind: 'launch' }; }
121
129
  return state;
@@ -237,7 +245,7 @@ export function scoreDiff(state, files) {
237
245
  if (!Array.isArray(state.contracts) || state.contracts.some((c) => typeof c !== 'string')) {
238
246
  throw new Error('LOOP.md: contracts must be a list of file paths or globs');
239
247
  }
240
- const scored = files.filter((f) => slash(f.file) !== LOOP_FILE && slash(f.file) !== LOOP_FILE_TMP);
248
+ const scored = files.filter((f) => !ENGINE_FILES.has(slash(f.file)));
241
249
  if (!scored.length) {
242
250
  // A closing unit (reached $close with a mutate already visited) finishes as done even
243
251
  // when this is its second empty diff in a row: there is nothing left to retry into.
@@ -305,13 +313,15 @@ function repairRing(graph, from, to) {
305
313
  }
306
314
 
307
315
  // Porcelain lines are `XY <path>`; strip the 2-char status + space, slash-normalise, drop
308
- // LOOP.md rows (the engine rewrites it on every action — it is never part of the scored work)
309
- // and a lingering LOOP.md.tmp (the atomic writer's own sibling — see `writeLoopFile`'s docblock).
310
- function filterPorcelain(porcelain) {
316
+ // the `ENGINE_FILES` rows: LOOP.md (the engine rewrites it on every action — it is never part of
317
+ // the scored work), a lingering LOOP.md.tmp (the atomic writer's own sibling — see
318
+ // `writeLoopFile`'s docblock) and the factory's FACTORY.md pair. Exported: the factory engine's
319
+ // clean-tree check (J5) filters with this same list, never a copy of it.
320
+ export function filterPorcelain(porcelain) {
311
321
  const lines = porcelain.split(/\r?\n/).filter((line) => {
312
322
  if (!line) return false;
313
323
  const path = line.slice(3).replace(/^"|"$/g, '');
314
- return slash(path) !== LOOP_FILE && slash(path) !== LOOP_FILE_TMP;
324
+ return !ENGINE_FILES.has(slash(path));
315
325
  });
316
326
  return lines.join('\n').trimEnd();
317
327
  }
@@ -301,8 +301,8 @@ export function cmdMigrate(args = {}, { root = ROOT } = {}) {
301
301
 
302
302
  printOut(`[migrate] migrated ${rows.length} install(s).\n`);
303
303
 
304
- // Step 5 — what could NOT be fixed automatically. Reported, never rewritten: nothing in
305
- // this repository has ever written an autostart entry, so migrate does not own the file.
304
+ // Step 5 — what could NOT be fixed automatically. Reported, never rewritten: the file may be
305
+ // the user's own, and the one Settings writes is updated from Settings, not by migrate.
306
306
  // The `start` ACTION is load-bearing, not decoration: bare `web` runs `serve()` in the
307
307
  // FOREGROUND with `daemon=false`, which never writes the daemon record, so `web stop`,
308
308
  // `web restart` and `web status` stay blind to the server this note just told someone to