geneseed 4.32.0 → 5.0.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 (245) hide show
  1. package/CHANGELOG.md +85 -0
  2. package/DESIGN.md +2 -2
  3. package/README.md +6 -5
  4. package/SHIPPED.md +4 -3
  5. package/adapters/bob/README.md +6 -5
  6. package/adapters/claude-code/README.md +4 -3
  7. package/adapters/claude-code/skills/geneseed/SKILL.md +1 -1
  8. package/adapters/openclaude/README.md +4 -3
  9. package/adapters/opencode/GLOBAL-HARNESS-SPEC.md +3 -1
  10. package/adapters/opencode/HOW-OPENCODE-LOADS.md +2 -1
  11. package/adapters/opencode/README.md +18 -18
  12. package/adapters/opencode/plugins/geneseed-activity.js +57 -1
  13. package/adapters/opencode/plugins/geneseed-context.js +85 -18
  14. package/adapters/opencode/plugins/geneseed-guard.js +437 -76
  15. package/adapters/opencode/plugins/geneseed-learn.js +97 -23
  16. package/bin/geneseed-cli.mjs +17 -25
  17. package/bin/geneseed-hook.mjs +23 -8
  18. package/docs/DESIGN.md +175 -0
  19. package/docs/PRD.md +111 -0
  20. package/docs/README.md +3 -2
  21. package/docs/architecture.md +145 -0
  22. package/docs/concepts/agents.md +1 -1
  23. package/docs/concepts/collaboration.md +1 -1
  24. package/docs/concepts/enforcement-table.md +1 -1
  25. package/docs/concepts/exclusions.md +5 -5
  26. package/docs/concepts/footprint.md +1 -1
  27. package/docs/concepts/foreman-mode.md +2 -2
  28. package/docs/concepts/hooks.md +22 -8
  29. package/docs/concepts/host-matrix.md +2 -2
  30. package/docs/concepts/hosts.md +1 -1
  31. package/docs/concepts/kits.md +3 -1
  32. package/docs/concepts/ownership.md +1 -1
  33. package/docs/concepts/rules.md +15 -2
  34. package/docs/concepts/shared-tier.md +73 -0
  35. package/docs/concepts/skills.md +2 -2
  36. package/docs/concepts/themes.md +1 -1
  37. package/docs/extending.md +13 -12
  38. package/docs/guides/install-claude-code.md +1 -1
  39. package/docs/guides/install-opencode.md +1 -1
  40. package/docs/guides/migrate.md +4 -2
  41. package/docs/guides/project-context.md +2 -2
  42. package/docs/guides/setup-footprint.md +1 -1
  43. package/docs/guides/uninstall.md +2 -1
  44. package/docs/guides/upgrade-to-5.md +116 -0
  45. package/docs/guides/upgrade.md +21 -9
  46. package/docs/guides/wiki.md +3 -3
  47. package/docs/reference/env-context.md +5 -3
  48. package/docs/reference/environment.md +1 -1
  49. package/docs/reference/glossary.md +2 -0
  50. package/docs/reference/opencode-plugins.md +3 -3
  51. package/docs/reference/plugin-activity.md +1 -1
  52. package/docs/reference/plugin-context.md +1 -0
  53. package/docs/reference/plugin-guard.md +14 -6
  54. package/docs/reference/plugin-learn.md +13 -6
  55. package/docs/reference/troubleshoot-hooks.md +3 -3
  56. package/docs/reference/troubleshoot-update.md +14 -0
  57. package/docs/token-footprint.md +4 -3
  58. package/docs/understand/a-day.md +2 -2
  59. package/docs/understand/design-choices-install.md +2 -1
  60. package/docs/understand/enforced-vs-asked.md +1 -1
  61. package/docs/understand/machine-bob.md +2 -0
  62. package/docs/understand/machine-claude.md +7 -5
  63. package/docs/understand/machine-opencode.md +7 -5
  64. package/docs/understand/on-your-machine.md +4 -0
  65. package/docs/understand/take-it-out.md +1 -1
  66. package/docs/web-ui.md +126 -68
  67. package/harness.config.json +1 -1
  68. package/js/README.md +10 -6
  69. package/js/build/args.mjs +10 -8
  70. package/js/build/bundle.mjs +11 -13
  71. package/js/build/driver.mjs +66 -65
  72. package/js/build/emit-claude.mjs +22 -16
  73. package/js/build/emit-common.mjs +4 -5
  74. package/js/build/emit-opencode.mjs +22 -22
  75. package/js/build/fold.mjs +515 -0
  76. package/js/build/generate.mjs +41 -52
  77. package/js/build/render.mjs +115 -29
  78. package/js/build/source.mjs +4 -1
  79. package/js/build/stubs.mjs +70 -9
  80. package/js/build/version.mjs +10 -10
  81. package/js/cli-table.json +23 -83
  82. package/js/hosts/activity.mjs +2 -2
  83. package/js/hosts/geneseed-dir.mjs +1 -1
  84. package/js/hosts/hooks-context.mjs +389 -99
  85. package/js/hosts/hooks-learn.mjs +38 -7
  86. package/js/hosts/hooks-prims.mjs +4 -2
  87. package/js/hosts/hooks.mjs +114 -39
  88. package/js/hosts/hosts.mjs +150 -51
  89. package/js/hosts/installs.mjs +55 -167
  90. package/js/hosts/link.mjs +3 -5
  91. package/js/hosts/mcp.mjs +1 -1
  92. package/js/hosts/memory-files.mjs +219 -17
  93. package/js/hosts/ownership-gate.mjs +1 -1
  94. package/js/hosts/settings.mjs +18 -13
  95. package/js/hosts/shim.mjs +4 -33
  96. package/js/hosts/store-watch.mjs +189 -0
  97. package/js/inspect/checks-authoring.mjs +3 -3
  98. package/js/inspect/checks-build.mjs +45 -18
  99. package/js/inspect/checks-counts.mjs +4 -4
  100. package/js/inspect/checks-repo.mjs +13 -14
  101. package/js/inspect/cost.mjs +24 -2
  102. package/js/inspect/diff.mjs +123 -123
  103. package/js/inspect/doctor.mjs +22 -27
  104. package/js/inspect/excludes.mjs +181 -62
  105. package/js/inspect/inventory.mjs +22 -27
  106. package/js/inspect/registry.mjs +106 -30
  107. package/js/inspect/scan.mjs +5 -5
  108. package/js/inspect/status.mjs +141 -119
  109. package/js/inspect/validate.mjs +22 -24
  110. package/js/lib/fs.mjs +47 -50
  111. package/js/lib/json.mjs +10 -17
  112. package/js/lib/machine-dir.mjs +73 -0
  113. package/js/lib/paths.mjs +22 -33
  114. package/js/lib/proc.mjs +1 -1
  115. package/js/lib/prompt.mjs +19 -27
  116. package/js/lib/text.mjs +8 -12
  117. package/js/lib/udiff.mjs +11 -15
  118. package/js/loop/catalog.mjs +2 -3
  119. package/js/maintain/memory.mjs +17 -17
  120. package/js/maintain/migrate.mjs +79 -89
  121. package/js/maintain/setup.mjs +43 -32
  122. package/js/maintain/uninstall.mjs +43 -61
  123. package/js/maintain/update.mjs +200 -93
  124. package/js/ui/anim.mjs +21 -35
  125. package/js/ui/cli.mjs +36 -58
  126. package/js/ui/menu.mjs +22 -45
  127. package/js/ui/tui.mjs +27 -67
  128. package/js/web/actions.mjs +34 -34
  129. package/js/web/api.mjs +130 -74
  130. package/js/web/catalog.mjs +175 -46
  131. package/js/web/docs.mjs +33 -12
  132. package/js/web/doctor-worker.mjs +14 -0
  133. package/js/web/handler.mjs +14 -5
  134. package/js/web/routes.mjs +17 -19
  135. package/js/web/state.mjs +78 -19
  136. package/js/web/update-check.mjs +25 -10
  137. package/js/web/user-files.mjs +50 -105
  138. package/package.json +7 -4
  139. package/registry.json +48 -55
  140. package/src/AGENT.md.tmpl +13 -14
  141. package/src/agents/_self-improvement.md +1 -1
  142. package/src/agents/_template.md +1 -1
  143. package/src/agents/advocate.md +1 -1
  144. package/src/agents/architect.md +1 -1
  145. package/src/agents/developer.md +1 -1
  146. package/src/agents/devops-engineer.md +1 -1
  147. package/src/agents/docker-expert.md +1 -1
  148. package/src/agents/docs.md +1 -1
  149. package/src/agents/empiricist.md +1 -1
  150. package/src/agents/explorer.md +1 -1
  151. package/src/agents/framer.md +1 -1
  152. package/src/agents/historian.md +1 -1
  153. package/src/agents/kubernetes-specialist.md +1 -1
  154. package/src/agents/memory-curator.md +2 -2
  155. package/src/agents/operator.md +1 -1
  156. package/src/agents/performance.md +1 -1
  157. package/src/agents/pragmatist.md +1 -1
  158. package/src/agents/react-engineer.md +1 -1
  159. package/src/agents/react-reviewer.md +1 -1
  160. package/src/agents/researcher.md +1 -1
  161. package/src/agents/reviewer.md +1 -1
  162. package/src/agents/security.md +1 -1
  163. package/src/agents/skeptic.md +1 -1
  164. package/src/agents/spring-boot-engineer.md +1 -1
  165. package/src/agents/spring-reviewer.md +1 -1
  166. package/src/agents/spring-security.md +1 -1
  167. package/src/agents/steward.md +1 -1
  168. package/src/agents/tester.md +1 -1
  169. package/src/agents/user-advocate.md +1 -1
  170. package/src/agents/visionary.md +1 -1
  171. package/src/memory/README.md +1 -1
  172. package/src/skills/_self-improvement.md +2 -2
  173. package/src/skills/daydream/SKILL.md +2 -2
  174. package/src/skills/daydream/instructions.md +1 -1
  175. package/src/skills/geneseed.md +1 -1
  176. package/src/skills/learn-mode.md +1 -2
  177. package/src/skills/profile.md +2 -2
  178. package/src/skills/rule/approve.md +69 -0
  179. package/src/skills/rule/consolidate.md +3 -3
  180. package/src/skills/rule.md +13 -5
  181. package/src/skills/skill-forge.md +1 -1
  182. package/src/skills/teach.md +29 -12
  183. package/src/skills/wiki.md +1 -1
  184. package/themes/_TEMPLATE.json +1 -2
  185. package/themes/biker.json +1 -2
  186. package/themes/commentator.json +1 -2
  187. package/themes/cyberpunk.json +1 -2
  188. package/themes/gamer.json +1 -2
  189. package/themes/imperial.json +1 -2
  190. package/themes/joker.json +1 -2
  191. package/themes/marvin.json +1 -2
  192. package/themes/mean.json +1 -2
  193. package/themes/military.json +1 -2
  194. package/themes/neutral.json +1 -2
  195. package/themes/pirate.json +1 -2
  196. package/themes/sports.json +1 -2
  197. package/themes/verstappen.json +1 -2
  198. package/themes/wizard.json +1 -2
  199. package/web/dist/assets/Activity-D8G4eClY.js +1 -0
  200. package/web/dist/assets/ActivityDetail-BtOBYk3M.js +1 -0
  201. package/web/dist/assets/AgentGlyph-k6o3gCM1.js +1 -0
  202. package/web/dist/assets/Bonsai-B_y20b3i.js +1 -0
  203. package/web/dist/assets/{CopyButton-C5Li6awl.js → CopyButton-CHQte7Ap.js} +1 -1
  204. package/web/dist/assets/Dashboard-B8uXeJZ_.js +2 -0
  205. package/web/dist/assets/Docs-Dgv_MWfT.js +5 -0
  206. package/web/dist/assets/GreenhouseView-CSzTMSl_.js +1 -0
  207. package/web/dist/assets/Installs-BDk9lqBI.js +3 -0
  208. package/web/dist/assets/JournalView-CvRk1-m5.js +1 -0
  209. package/web/dist/assets/Kits-CoITzxWM.js +1 -0
  210. package/web/dist/assets/Laws-Ctf5r9rE.js +3 -0
  211. package/web/dist/assets/Library-DNwHYVXt.js +3 -0
  212. package/web/dist/assets/{Loops-CzitjxGV.js → Loops-S85PMQ8m.js} +2 -2
  213. package/web/dist/assets/{Markdown-C4S4tTA7.js → Markdown-0ORz7tAc.js} +21 -21
  214. package/web/dist/assets/OperatorHudView-DuGz_sTk.js +1 -0
  215. package/web/dist/assets/Personal-afJNwvRS.js +2 -0
  216. package/web/dist/assets/{RailCats-D5weYPCS.js → RailCats-AW92uhsX.js} +1 -1
  217. package/web/dist/assets/Settings-CGDFz-6j.js +1 -0
  218. package/web/dist/assets/Tabs-1qLrnqmn.js +1 -0
  219. package/web/dist/assets/api-C46vAuqp.js +1 -0
  220. package/web/dist/assets/controls-D4wmg_pl.js +1 -0
  221. package/web/dist/assets/index-COTd4TRZ.js +3 -0
  222. package/web/dist/assets/index-CtorA7uK.css +1 -0
  223. package/web/dist/assets/motion-RlUl1osO.js +1 -0
  224. package/web/dist/assets/{sections-ChwaobfW.js → sections-CtFz7HFH.js} +1 -1
  225. package/web/dist/index.html +5 -5
  226. package/src/skills/quiz.md +0 -44
  227. package/web/dist/assets/Activity-Bjy64wHC.js +0 -1
  228. package/web/dist/assets/ActivityDetail-B0AaipP8.js +0 -1
  229. package/web/dist/assets/Bonsai-CJniRqaH.js +0 -1
  230. package/web/dist/assets/Dashboard-B-6DTmae.js +0 -2
  231. package/web/dist/assets/Docs-LRc30XL9.js +0 -5
  232. package/web/dist/assets/GreenhouseView-CcoYlaWo.js +0 -1
  233. package/web/dist/assets/Installs-dp1epTcE.js +0 -3
  234. package/web/dist/assets/JournalView-nFP4poCf.js +0 -1
  235. package/web/dist/assets/KitApply-DwyZUj57.js +0 -1
  236. package/web/dist/assets/Kits-C0IEdZXe.js +0 -1
  237. package/web/dist/assets/Laws-CkykmQWu.js +0 -3
  238. package/web/dist/assets/Library-Guh9HBZU.js +0 -2
  239. package/web/dist/assets/OperatorHudView-DLGNulIY.js +0 -1
  240. package/web/dist/assets/Personal-BMtberL8.js +0 -2
  241. package/web/dist/assets/Tabs-uYJqfuQt.js +0 -1
  242. package/web/dist/assets/api-BxjLd7Qd.js +0 -1
  243. package/web/dist/assets/index-DA7BiaE5.js +0 -3
  244. package/web/dist/assets/index-dbbDGFDq.css +0 -1
  245. package/web/dist/assets/motion-Bccx3zE8.js +0 -1
@@ -31,7 +31,7 @@
31
31
  * run and varied in none. The phase filter is gated over a recorded transcript in
32
32
  * `tests/unit/update_git.test.mjs`; the heartbeat and the hard deadline are gated by nothing.
33
33
  *
34
- * ALSO HERE, SINCE P8b: `syncSelf`/`cmdSyncSelf` and the bootstrap step runner
34
+ * ALSO HERE, SINCE P8b: the bootstrap step runner
35
35
  * (`cmdBootstrap`, `bootstrapPlain`) at the bottom of this file. Still NOT here: `main`, the
36
36
  * launchers' self-heal entry. Every web action row crosses — see `js/web/jobs.mjs`.
37
37
  * `parseOrigin` is ported in full here even though only `upgrade`
@@ -39,14 +39,13 @@
39
39
  * pure function across two phases is how a second classifier gets written.
40
40
  */
41
41
  import { spawn, spawnSync } from 'node:child_process';
42
- import { cpSync, existsSync, mkdirSync, rmSync, statSync } from 'node:fs';
42
+ import { cpSync, existsSync, mkdirSync, realpathSync, renameSync, rmSync, statSync } from 'node:fs';
43
43
  import os from 'node:os';
44
44
  import path from 'node:path';
45
45
 
46
46
  import { ROOT } from '../build/source.mjs';
47
47
  import { exportImprovements, flushExportNotes } from '../inspect/diff.mjs';
48
48
  import { opencodeConfigDir } from '../hosts/hosts.mjs';
49
- import { legacyProcessCarrierOfDir } from '../hosts/installs.mjs';
50
49
  import { appendText, copyFile, printOut, printErr, readText, writeText } from '../lib/fs.mjs';
51
50
  import { comparePaths, toPlatformPath, which } from '../lib/paths.mjs';
52
51
  import { WHITESPACE, parseIntStrict, stripWhitespace } from '../lib/text.mjs';
@@ -106,10 +105,8 @@ export function gitRun(args, { timeout = 10, network = false } = {}) {
106
105
  const r = spawnSync(exe, cmd, {
107
106
  encoding: 'utf8', timeout: timeout * 1000, env, maxBuffer: 64 * 1024 * 1024, ...NO_WINDOW,
108
107
  });
109
- // `except Exception` — a spawn error, an OS error, or the timeout Python raises on. A
110
- // signal-killed git has `status === null` too and Python would report a negative code for
111
- // it; no call site here distinguishes the two, and treating it as "git did not answer" is
112
- // the arm the reference reaches for every other failure.
108
+ // A spawn error, an OS error or a timeout. A signal-killed git has `status === null` too;
109
+ // no call site distinguishes the two, so both mean "git did not answer".
113
110
  if (r.error || r.status === null) return [null, '', ''];
114
111
  return [r.status,
115
112
  redactUrlCreds(stripWhitespace(universal(r.stdout))),
@@ -204,6 +201,18 @@ function pre(code) {
204
201
  return { ok: code === 'ready', code, kind, message };
205
202
  }
206
203
 
204
+ /**
205
+ * Is ROOT itself a git checkout, even one whose git cannot answer? An npm install under a
206
+ * project's `node_modules` is INSIDE someone else's work tree and is not a checkout: only ROOT's
207
+ * own top level, or its own `.git` entry (a damaged repository or a missing binary), says so.
208
+ */
209
+ function isGitCheckout() {
210
+ if (existsSync(path.join(String(ROOT), '.git'))) return true;
211
+ const [rc, top] = gitRun(['rev-parse', '--show-toplevel']);
212
+ if (rc !== 0 || !top) return false;
213
+ try { return realpathSync(top) === realpathSync(String(ROOT)); } catch { return false; }
214
+ }
215
+
207
216
  /** `_preflight()` — Phase A, local only, no network. Never raises. */
208
217
  export function preflight() {
209
218
  let [rc, out] = gitRun(['rev-parse', '--is-inside-work-tree']);
@@ -235,7 +244,7 @@ export function fetchTimeout() {
235
244
  * (`rev-list --count` prints ASCII). Reproducing the crash would be reproducing a bug; the
236
245
  * divergence is confined to input git cannot emit and is recorded rather than matched.
237
246
  */
238
- export function countOccurrences(s) {
247
+ function countOccurrences(s) {
239
248
  const t = stripWhitespace(s || '');
240
249
  return /^[0-9]+$/.test(t) ? Number(t) : 0;
241
250
  }
@@ -396,6 +405,8 @@ export async function measureUpstream(log = null) {
396
405
  return ['ready', behind, ''];
397
406
  }
398
407
 
408
+ const DOCTOR_TIMEOUT_MS = 300 * 1000;
409
+
399
410
  const DOCTOR_LEGEND = [
400
411
  '[geneseed] doctor problem legend — what the lines above mean / how to fix:',
401
412
  " • 'dead link' → a skill/agent body links a sibling as <dir>/<name>.md; use the BARE <name>.md (source bug)",
@@ -408,19 +419,27 @@ const DOCTOR_LEGEND = [
408
419
 
409
420
  /**
410
421
  * `_run_doctor(cand)` — validate a source tree with its OWN `doctor --all --no-bundle`.
411
- * Fail-closed: any nonzero exit, timeout or spawn error is a failure.
422
+ * Returns `[passed, output]`. A nonzero exit is a failure. `passed` is `null` when the doctor
423
+ * gave no verdict at all (timeout, kill or spawn error): a busy machine can outrun the deadline,
424
+ * and that says nothing about the pulled source. The deadline is judged by this process's clock
425
+ * too, since a kill can read as exit 1 on Windows. A kill from outside, inside the deadline,
426
+ * cannot be told from a real exit 1.
412
427
  *
413
428
  * THE SPAWN THAT CANNOT BE AN IMPORT. `cand` is the tree as it exists AFTER the merge, and
414
429
  * this process's module graph was loaded before it. `cmdDoctor` in-process would validate the
415
430
  * source this program started with and pass, which is the one answer that must never be
416
431
  * given here — the gate exists to catch a bad upstream commit.
417
432
  */
418
- export function runDoctor(cand) {
433
+ export function runDoctor(cand, timeoutMs = DOCTOR_TIMEOUT_MS) {
434
+ const started = Date.now();
419
435
  const r = spawnSync(process.execPath,
420
436
  [path.join(String(cand), 'bin', 'geneseed-cli.mjs'), 'doctor', '--all', '--no-bundle'],
421
- { encoding: 'utf8', timeout: 300 * 1000, maxBuffer: 256 * 1024 * 1024, ...NO_WINDOW });
437
+ { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 256 * 1024 * 1024, ...NO_WINDOW });
422
438
  if (r.error || r.status === null) {
423
- return [false, `[geneseed] doctor gate could not run: ${r.error || 'no exit status'}`];
439
+ return [null, `[geneseed] doctor gate could not run: ${r.error || 'no exit status'}`];
440
+ }
441
+ if (r.status !== 0 && Date.now() - started >= timeoutMs) {
442
+ return [null, `[geneseed] doctor gate could not run: stopped at its ${timeoutMs} ms deadline`];
424
443
  }
425
444
  // `stderr=subprocess.STDOUT` — the reference gives the child ONE handle, so its two
426
445
  // streams are interleaved in write order and arrive as `proc.stdout`. `spawnSync` has no
@@ -444,10 +463,25 @@ export function runDoctor(cand) {
444
463
  * `--keep` refuses instead when such an edit touches a file the rollback must change; that
445
464
  * refusal is reported as itself — the user is left on the pulled commit, with the command to
446
465
  * finish the rollback — rather than as a rollback that did not happen.
466
+ *
467
+ * The doctor and what follows it are `gatePulled`. A new pull over an unchecked one takes its
468
+ * rollback point from `pendingGate`, since HEAD is then a commit no verdict covers.
469
+ *
470
+ * THE RECORD GOES DOWN BEFORE THE MERGE, so an update killed during the doctor leaves one too. A
471
+ * record that cannot be written stops the pull: nothing could hold a later rebuild back. A merge
472
+ * that then fails leaves it naming HEAD, which `pendingGate` drops.
447
473
  */
448
- export function pullAndValidate(log) {
474
+ export function pullAndValidate(log, doctorTimeoutMs = DOCTOR_TIMEOUT_MS) {
449
475
  const [rc0, old] = gitRun(['rev-parse', 'HEAD']);
450
476
  if (rc0 !== 0 || !old) return [false, 'not_git', 'could not read HEAD'];
477
+ const pending = pendingGate();
478
+ if (pending?.blocked) return [false, 'gate_unknown', pending.blocked];
479
+ const verified = pending?.verified ?? old;
480
+ if (!setPendingGate(verified)) {
481
+ return [false, 'gate_unrecorded',
482
+ 'Update stopped before the pull: it could not write its record under .git, so an '
483
+ + 'unfinished doctor could not hold the rebuild back. Nothing changed.'];
484
+ }
451
485
  log('[geneseed] fast-forwarding to upstream ...');
452
486
  const [rc1, , err] = gitRun(['merge', '--ff-only', '@{u}'], { timeout: 60 });
453
487
  if (rc1 !== 0) {
@@ -463,23 +497,125 @@ export function pullAndValidate(log) {
463
497
  log('[geneseed] pulled:');
464
498
  for (const line of pulled.split('\n')) log(` ${line}`);
465
499
  }
500
+ return gatePulled(verified, log, doctorTimeoutMs);
501
+ }
502
+
503
+ /**
504
+ * Where the unchecked state lives: under `.git`, so it dirties nothing. One record per branch, so
505
+ * a rollback can only ever move the branch the pull landed on. Null when git cannot say.
506
+ *
507
+ * KNOWN GAP, STATED RATHER THAN CLOSED: a record belongs to a branch NAME, so a branch the user
508
+ * creates (and sets to track) at a commit that an unfinished doctor never judged starts with no
509
+ * record, and nothing holds its rebuild back. Closing it means keying the record by commit, and a
510
+ * pull would then need a record per ancestor; the doctor gate is a guard for the pull `update`
511
+ * itself made, not an audit of every tree a user checks out.
512
+ */
513
+ function pendingGateFile() {
514
+ const [rc0, branch] = gitRun(['rev-parse', '--abbrev-ref', 'HEAD']);
515
+ if (rc0 !== 0 || !branch) return null;
516
+ const name = `geneseed-doctor-pending-${encodeURIComponent(branch)}`;
517
+ const [rc1, rel] = gitRun(['rev-parse', '--git-path', name]);
518
+ return rc1 === 0 && rel ? path.resolve(String(ROOT), rel) : null;
519
+ }
520
+
521
+ function setPendingGate(verified) {
522
+ const file = pendingGateFile();
523
+ if (!file) return false;
524
+ try {
525
+ writeText(file, `${verified}\n`);
526
+ return true;
527
+ } catch { return false; }
528
+ }
529
+
530
+ /** Failing here is safe: a record left behind only asks the doctor once more. */
531
+ function clearPendingGate() {
532
+ const file = pendingGateFile();
533
+ try { if (file) rmSync(file, { force: true }); } catch { /* the next update asks again */ }
534
+ }
535
+
536
+ /**
537
+ * `null` when this branch has nothing unchecked, `{ verified }` with the last commit a verdict
538
+ * covers while HEAD is ahead of it, `{ blocked }` with a message when nobody can tell.
539
+ *
540
+ * ONLY TWO ANSWERS DROP A RECORD: git saying the commit is not an ancestor (rc 1), and HEAD back
541
+ * on it. Both mean the user moved on. A timeout, an empty record or any other failure says
542
+ * nothing about the tree, so it refuses the rebuild and the record stays.
543
+ */
544
+ export function pendingGate() {
545
+ // A repository with no commits has no pull to have left a record on: nothing to honour.
546
+ const [rcHead, , errHead] = gitRun(['rev-parse', '--verify', '-q', 'HEAD']);
547
+ if (rcHead === 1 && !errHead) return null;
548
+ const blocked = (why) => ({
549
+ blocked: `Update stopped: the record of an unfinished doctor cannot be trusted (${why}), so this `
550
+ + 'source may be unchecked. Run `geneseed doctor --all`. If it is clean, delete the '
551
+ + 'geneseed-doctor-pending-* file under .git, then update.',
552
+ });
553
+ const file = pendingGateFile();
554
+ if (!file) return blocked('git did not answer');
555
+ let verified;
556
+ try {
557
+ if (!existsSync(file)) return null;
558
+ verified = stripWhitespace(readText(file));
559
+ } catch (e) { return blocked(e.message); }
560
+ if (!verified) return blocked('it is empty');
561
+ const [rc0, head] = gitRun(['rev-parse', 'HEAD']);
562
+ const [rc1] = gitRun(['merge-base', '--is-ancestor', verified, 'HEAD']);
563
+ if (rc0 !== 0 || (rc1 !== 0 && rc1 !== 1)) return blocked(`git cannot place ${verified}`);
564
+ if (rc1 === 1 || head === verified) {
565
+ clearPendingGate();
566
+ return null;
567
+ }
568
+ return { verified };
569
+ }
570
+
571
+ /**
572
+ * Why a direct `setup` or `rebuild-all` must not run now, or null. Both render this source, and an
573
+ * unfinished doctor (a record under `.git`) means nothing has judged it: `upgrade` and `bootstrap`
574
+ * hold back for the record, and a direct call used to walk around it. An npm install has no record.
575
+ */
576
+ export function gateRefusal() {
577
+ if (!isGitCheckout()) return null;
578
+ const g = pendingGate();
579
+ if (!g) return null;
580
+ return g.blocked ?? 'the source has no doctor verdict yet. Run `geneseed update` (it runs the '
581
+ + 'doctor first), then retry.';
582
+ }
583
+
584
+ /**
585
+ * The doctor gate over HEAD, with `verified` as the commit to roll back to.
586
+ *
587
+ * `doctor_unfinished` IS NOT A FAILED GATE, AND NOT A PASS. With no verdict the pull stays, because
588
+ * rolling back called a healthy pull bad. But the record under `.git` holds the rebuild back: the
589
+ * next update finds nothing to pull, and without it would rebuild from a tree nothing has judged.
590
+ * It asks here again, and only a verdict clears the record. A refused rollback keeps it too. The
591
+ * caller wrote the record, or found it, so nothing here needs to.
592
+ */
593
+ export function gatePulled(verified, log, doctorTimeoutMs = DOCTOR_TIMEOUT_MS) {
466
594
  log('[geneseed] validating the pulled source (doctor — can take a minute) ...');
467
- const [passed, output] = runDoctor(ROOT);
595
+ const [passed, output] = runDoctor(ROOT, doctorTimeoutMs);
468
596
  log(output.replace(/\n+$/, ''));
597
+ if (passed === null) {
598
+ return [false, 'doctor_unfinished',
599
+ 'the doctor did not finish, so the pulled source is UNCHECKED: nothing says it is bad. '
600
+ + 'You stay on the pulled commit and nothing was rebuilt. Run `geneseed update` again when '
601
+ + 'the machine is quieter: it runs the doctor first and rebuilds only on a pass.'];
602
+ }
469
603
  if (!passed) {
470
- const [rc3, , rerr] = gitRun(['reset', '--keep', old], { timeout: 60 });
604
+ const [rc3, , rerr] = gitRun(['reset', '--keep', verified], { timeout: 60 });
471
605
  for (const line of DOCTOR_LEGEND) log(line);
472
606
  if (rc3 !== 0) {
473
607
  return [false, 'doctor_fail',
474
608
  'the pulled source FAILS validation, and the rollback was REFUSED — a file it must '
475
609
  + 'restore was edited while the doctor ran, and those edits were kept. You are still '
476
- + `on the pulled commit; save your edits, then roll back with: git reset --keep ${old}\n`
610
+ + `on the pulled commit; save your edits, then roll back with: git reset --keep ${verified}\n`
477
611
  + rerr];
478
612
  }
613
+ clearPendingGate();
479
614
  return [false, 'doctor_fail',
480
615
  'the pulled source FAILS validation — rolled back to the previous commit. '
481
616
  + 'Fix the problems listed above.'];
482
617
  }
618
+ clearPendingGate();
483
619
  return [true, 'ready', ''];
484
620
  }
485
621
 
@@ -552,15 +688,21 @@ export function configTheme(here) {
552
688
  }
553
689
 
554
690
  /**
555
- * `_migrate_stray_bundle` — move host state (context.json, memory/) from an OLD in-folder
556
- * bundle to the canonical sibling `out` BEFORE rebuilding, then drop the stray.
691
+ * `_migrate_stray_bundle` — copy host state (context.json, memory/) from an OLD in-folder
692
+ * bundle to the canonical sibling `out` BEFORE rebuilding, then set the stray ASIDE.
693
+ *
694
+ * THE STRAY IS RENAMED, NEVER DELETED (B9). The rescue covers context.json and memory/ only, and
695
+ * memory/ only when `out` has none; the old `rmSync` took everything else with it (user-rules.md,
696
+ * PROFILE.md, notebook/, a wiki manifest) from a folder `.gitignore` hides, so git could not
697
+ * bring it back. It now moves whole to `archived-Harness/<stamp>` beside it, also git-ignored.
698
+ * With the stray gone the next run returns at the stat, which is what makes this idempotent.
557
699
  *
558
700
  * "IS `out` THE STRAY ITSELF?" IS A PATH COMPARISON, NOT A STRING ONE. `GENESEED_OUT` is typed
559
701
  * by a user, so on Windows `c:\x\Geneseed\harness` is the same directory as the stray and was a
560
702
  * different string: the rescue was skipped as "nothing to move into", and the `rmSync` at the
561
703
  * bottom then deleted the LIVE bundle — memory/ and context.json with it.
562
704
  */
563
- export function migrateStrayBundle(here, out, log) {
705
+ export function migrateStrayBundle(here, out, log, now = new Date()) {
564
706
  const stray = path.join(String(here), 'Harness');
565
707
  const outStr = String(out);
566
708
  if (comparePaths(path.resolve(outStr), path.resolve(stray)) === 0) return;
@@ -581,8 +723,13 @@ export function migrateStrayBundle(here, out, log) {
581
723
  log(`[geneseed] rescued ${mem}/ from ${stray} -> ${outStr}`);
582
724
  }
583
725
  }
584
- log(`[geneseed] removing stray in-folder bundle ${stray} (canonical: ${outStr})`);
585
- rmSync(stray, { recursive: true, force: true });
726
+ const archive = path.join(String(here), 'archived-Harness');
727
+ const stamp = now.toISOString().replace(/[:.]/g, '-');
728
+ let dest = path.join(archive, stamp);
729
+ for (let n = 2; existsSync(dest); n += 1) dest = path.join(archive, `${stamp}-${n}`);
730
+ mkdirSync(archive, { recursive: true });
731
+ renameSync(stray, dest);
732
+ log(`[geneseed] stray in-folder bundle ${stray} set aside in ${dest} (canonical: ${outStr}); delete it when you are done with it`);
586
733
  }
587
734
 
588
735
  /**
@@ -618,18 +765,9 @@ async function drainStdout() {
618
765
  * Only the TAIL of the argv is kept: theme and emit are `upgrade`'s to decide (a theme argument
619
766
  * may override the marker), and `setupBuildArgs` opens with exactly those four tokens when it
620
767
  * is given no out and no root.
621
- *
622
- * `null` — distinct from `[]`'s "never built, nothing to carry over" — means `dir` carries a
623
- * pre-comms carrier (same guard as `rebuild-all`/`migrate`/the web console, reusing
624
- * `legacyProcessCarrierOfDir`): `installProfile` would read it exactly as written, and feeding
625
- * that into a rebuild would write the loss back PERMANENTLY. `[]` here would be WORSE, not
626
- * neutral — it resets every axis to the generator's config default, the exact failure this
627
- * function exists to prevent, on top of the comms/process-address loss. `upgrade` must skip the
628
- * bundle rebuild entirely on `null`, never fall through to an empty axes list.
629
768
  */
630
769
  export async function installAxes(dir, { installProfile, setupBuildArgs }, notify = null) {
631
770
  if (!existsSync(path.join(String(dir), '.geneseed-emit'))) return [];
632
- if (legacyProcessCarrierOfDir(String(dir), 'opencode')) return null;
633
771
  const p = installProfile('opencode', 'global', String(dir), notify);
634
772
  return setupBuildArgs('', 'files', null, null, p.footprint, p.posture, p.mode, p.doctrines,
635
773
  undefined, p.excludeRules, p.trust, p.excludeSkills, p, p.kits).slice(4);
@@ -678,18 +816,13 @@ async function rebuildInstalls(here, log) {
678
816
  }
679
817
 
680
818
  /**
681
- * `upgrade(ref, theme_arg, zip_arg)` — update from the install's own git origin
819
+ * `upgrade(themeArg)` — update from the install's own git origin
682
820
  * (fast-forward only), doctor-gate, and rebuild the bundle plus every registered install.
683
- * `ref`/`zip_arg` are accepted for back-compat but IGNORED. Returns a process exit code:
684
- * 0 ok/up-to-date, 3 info precondition, 1 error.
821
+ * Returns a process exit code: 0 ok/up-to-date, 3 info precondition, 1 error.
685
822
  */
686
- export async function upgrade(ref = null, themeArg = null) {
823
+ export async function upgrade(themeArg = null) {
687
824
  const logger = new Log();
688
825
  const log = (m) => logger.call(m);
689
- if (ref) {
690
- log(`[geneseed] ⚠️ ref '${ref}' is IGNORED — updates follow the checkout's `
691
- + 'current branch (tag/branch pinning was removed with the zip path).');
692
- }
693
826
  const here = String(ROOT);
694
827
  // `Path(os.environ.get(...) or ...)`, and `toPlatformPath` is the `Path(str)` half of it: the
695
828
  // reference stringifies with the PLATFORM separator, so a `GENESEED_OUT` spelled
@@ -756,6 +889,19 @@ export async function upgrade(ref = null, themeArg = null) {
756
889
  }
757
890
  } else { // uptodate
758
891
  log('[geneseed] already up to date.');
892
+ const pending = pendingGate();
893
+ if (pending?.blocked) {
894
+ log(`[geneseed] ${pending.blocked}`);
895
+ return 1;
896
+ }
897
+ if (pending) {
898
+ log('[geneseed] the last doctor did not finish — this source has no verdict yet.');
899
+ const [ok, , msg] = gatePulled(pending.verified, log);
900
+ if (!ok) {
901
+ log(`[geneseed] ${msg}`);
902
+ return 1;
903
+ }
904
+ }
759
905
  }
760
906
 
761
907
  const theme = themeArg || markerTheme(cfg, out) || cfgTheme;
@@ -766,18 +912,7 @@ export async function upgrade(ref = null, themeArg = null) {
766
912
  } catch (e) {
767
913
  log(`[geneseed] ⚠️ could not migrate the old in-folder bundle (${e && e.message ? e.message : e}) — continuing.`);
768
914
  }
769
- let rc = 0;
770
- if (axes === null) {
771
- // `installAxes` found a pre-comms carrier at this bundle's own target — skip the rebuild
772
- // entirely rather than fall through with no axes (which would reset it to the generator's
773
- // config default, worse than the loss this guard exists to stop). `rebuildInstalls` below
774
- // reaches the same directory through `rebuild-all`'s own, identically-reasoned skip.
775
- log(`[geneseed] SKIPPED bundle rebuild: pre-comms carrier at `
776
- + `${emit === 'opencode-global' ? cfg : out} (names 'process 8') — run `
777
- + '`geneseed setup` for it.');
778
- } else {
779
- rc = await rebuildBundle(here, out, theme, emit, rootDir, log, axes, bounceDaemonIfRunning);
780
- }
915
+ let rc = await rebuildBundle(here, out, theme, emit, rootDir, log, axes, bounceDaemonIfRunning);
781
916
  if (rc !== 0) {
782
917
  log(`[geneseed][E-BUILD] ✗ the bundle build FAILED (theme: ${theme || 'default'}, emit: ${emit}).`);
783
918
  return 1;
@@ -793,7 +928,7 @@ export async function upgrade(ref = null, themeArg = null) {
793
928
  }
794
929
 
795
930
  /**
796
- * `_harness_lifecycle.cmd_upgrade` — the harness verb, which is `export_improvements()` and
931
+ * The harness verb, which is `export_improvements()` and
797
932
  * then `upgrade()`.
798
933
  *
799
934
  * THE EXPORT RUNS FIRST AND MUST NEVER BLOCK. A deployed harness can carry in-place edits (by
@@ -812,43 +947,7 @@ export async function cmdUpgrade(args) {
812
947
  printErr(`[upgrade] ⚠️ could not export local edits (${e && e.message ? e.message : e}) — `
813
948
  + 'run `geneseed diff --out FILE` before upgrading to keep them.\n');
814
949
  }
815
- let { ref } = args;
816
- let theme = args.theme;
817
- // Back-compat: the legacy hidden `ref` positional eats the FIRST argument, so
818
- // `geneseed upgrade imperial` lands in `ref` (which `upgrade` ignores) and the theme
819
- // silently drops. `ref` is dead — reinterpret it as the theme when it names one.
820
- if (theme === null && ref && existsSync(path.join(String(ROOT), 'themes', `${ref}.json`))) {
821
- theme = ref;
822
- ref = null;
823
- }
824
- return upgrade(ref, theme);
825
- }
826
-
827
- /**
828
- * `_update.sync_self` — an ALIAS of `upgrade`, and the argument it drops is the behaviour.
829
- *
830
- * One `git pull` refreshes the launchers AND the factory, so the two verbs became one
831
- * operation; the separate subcommand is kept for the stable contract. `ref` is bound by the
832
- * parser for back-compat and then dropped HERE — this calls `upgrade()` with no arguments
833
- * rather than forwarding anything.
834
- *
835
- * "IGNORED" IS NOT SILENT, which is what makes the dropping observable and is a correction the
836
- * mutations made to this docblock. `upgrade(ref)` does not quietly disregard a ref — it opens by
837
- * LOGGING `⚠️ ref '<x>' is IGNORED — updates follow the checkout's current branch`. So
838
- * `syncSelf` forwarding its argument would make `sync-self v1.2.3` print a warning the reference
839
- * never prints (mutation M22), and wiring the verb table's row straight at `cmdUpgrade` would
840
- * additionally make `sync-self cyberpunk` rebuild in cyberpunk, because `cmdUpgrade` re-reads
841
- * the dead positional as a THEME when `themes/<ref>.json` exists (M21). Two different defects
842
- * behind one plausible-looking shortcut, and
843
- * `sync-self/the-ref-positional-is-accepted-and-never-re-read-as-a-theme` is the cell for both.
844
- */
845
- export function syncSelf(_ref = null) {
846
- return upgrade();
847
- }
848
-
849
- /** `_harness_lifecycle.cmd_sync_self`. */
850
- export function cmdSyncSelf(args) {
851
- return syncSelf(args.ref);
950
+ return upgrade(args.theme);
852
951
  }
853
952
 
854
953
  // ---------------------------------------------------------------------------------------
@@ -897,7 +996,7 @@ function updateStepCmd(sub) {
897
996
  }
898
997
 
899
998
  /**
900
- * `_harness_lifecycle._diagnose_failed_step` — the diagnosis for a failed update step, PERSISTED
999
+ * The diagnosis for a failed update step, PERSISTED
901
1000
  * before it is printed.
902
1001
  *
903
1002
  * The persistence is the point rather than a nicety: the curses log pane is ephemeral and the
@@ -929,7 +1028,7 @@ export function diagnoseFailedStep(n, total, title, cmd, rc, output) {
929
1028
  }
930
1029
 
931
1030
  /**
932
- * `_harness_lifecycle._bootstrap_plain` — run the update step with plain output, never fatally.
1031
+ * Run the update step with plain output, never fatally.
933
1032
  *
934
1033
  * EXIT 3 IS NOT A FAILURE. `upgrade` returns 3 for an info precondition — a dirty tree, no
935
1034
  * upstream, already up to date — and a bootstrap that reported those as failures would tell
@@ -949,7 +1048,7 @@ async function bootstrapPlain() {
949
1048
  // which was written for `_flush_export_notes` and found this instead.
950
1049
  /** @type {Array<[string, string[], () => Promise<number>]>} */
951
1050
  const steps = [['Update & rebuild', updateStepCmd('upgrade'),
952
- () => cmdUpgrade({ ref: null, theme: null })]];
1051
+ () => cmdUpgrade({ theme: null })]];
953
1052
  let failed = false;
954
1053
  for (let i = 0; i < steps.length; i += 1) {
955
1054
  const [title, cmd, step] = steps[i];
@@ -968,7 +1067,7 @@ async function bootstrapPlain() {
968
1067
  }
969
1068
 
970
1069
  /**
971
- * `_harness_lifecycle._reexec` — hand off to a FRESH process so the just-updated code on disk
1070
+ * Hand off to a FRESH process so the just-updated code on disk
972
1071
  * runs, not the modules this one loaded before the pull.
973
1072
  *
974
1073
  * Node has no `execv`, so this is always the reference's WINDOWS branch: run the child normally
@@ -983,7 +1082,7 @@ function reexec(argv) {
983
1082
  }
984
1083
 
985
1084
  /**
986
- * `_harness_lifecycle.cmd_bootstrap` — update everything, then hand off to a fresh `setup`.
1085
+ * Update everything, then hand off to a fresh `setup`.
987
1086
  *
988
1087
  * `flushExportNotes()` runs BEFORE the handoff, deliberately: the re-exec replaces this process
989
1088
  * and the update step's own improvements notice has scrolled past (or, under the reference's
@@ -993,10 +1092,18 @@ function reexec(argv) {
993
1092
  * and it can repair what the update could not — but its exit code used to become bootstrap's,
994
1093
  * so a script saw 0 over an update that never happened. `handoff` is the seam a test needs:
995
1094
  * the real `setup` exits 1 off a terminal, which would make the two answers indistinguishable.
1095
+ *
1096
+ * AN UNCHECKED SOURCE IS THE EXCEPTION: `setup` renders, and no doctor has judged this tree.
1097
+ * An npm install has no record to hold, so it is not asked.
996
1098
  */
997
1099
  export async function cmdBootstrap(args, { handoff = reexec } = {}) {
998
1100
  const failed = await bootstrapPlain();
999
1101
  flushExportNotes();
1102
+ if (isGitCheckout() && pendingGate()) {
1103
+ printOut('[geneseed] setup not started: the source has no doctor verdict yet. '
1104
+ + 'Run `geneseed update`, then `geneseed setup`.\n');
1105
+ return 1;
1106
+ }
1000
1107
  if (!args.noSetup) {
1001
1108
  const rc = handoff([process.execPath,
1002
1109
  path.join(String(ROOT), 'bin', 'geneseed-cli.mjs'), 'setup']);
package/js/ui/anim.mjs CHANGED
@@ -1,32 +1,21 @@
1
1
  /**
2
2
  * The per-theme install animation the LINE wizard plays.
3
3
  *
4
- * P7c, and the one leftover of that phase that is NOT the declared curses panel. P5i ported
5
- * `_setup_lines` and left this out with a note — "belongs to P7 with the rest of the terminal
6
- * layer" — and the rest of the terminal layer turned out to be the panel, which was rejected
7
- * (`tests/unit/no_panel.test.mjs` asserts it stays gone). This module is the part
8
- * that has nothing to do with curses: it draws on the ORDINARY terminal, with cursor-up
9
- * escapes and a sleep, and its only caller is a function that already crossed.
4
+ * It draws on the ORDINARY terminal, with cursor-up escapes and a sleep, and its only
5
+ * caller is a function that already crossed. There is no full-screen panel
6
+ * (`tests/unit/no_panel.test.mjs` asserts it stays gone).
10
7
  *
11
- * SO IT IS NOT IN `js/ui/tui.mjs`, DELIBERATELY. That module carries a structural assertion that
8
+ * IT IS NOT IN `js/ui/tui.mjs`, DELIBERATELY. That module carries a structural assertion that
12
9
  * it contains no escape sequence at all — the thing that makes "the panel is declared" a
13
10
  * measurement instead of a promise. This file necessarily contains `\x1b[{n}A`, so putting it
14
- * there would have turned that assertion red and invited someone to weaken it. A line-mode
15
- * animation and a full-screen panel are different subsystems in the reference too: they live
16
- * in different files there and they do here.
11
+ * there would have turned that assertion red and invited someone to weaken it.
17
12
  *
18
- * WHAT THE PYTHON DOES THAT THIS DOES NOT, and it is one line. `_anim_ok` calls
19
- * `os.system("")` on Windows, whose only purpose is the side effect of making the console
20
- * enable VT/ANSI processing; it is not a probe and its return value is discarded. Node's
21
- * console writer already enables virtual-terminal processing on Windows when stdout is a TTY
22
- * (libuv does it when the stream is opened), so the effect is present and the call is not
23
- * needed — which is fortunate, because it is a `child_process` spawn and this port is barred
24
- * from those. The consequence is that the reference's `except Exception: return False` arm
25
- * around it has no counterpart here. That arm needs `cmd.exe` to be unlaunchable on a machine
26
- * that has already reached an interactive wizard.
13
+ * NO VT/ANSI ENABLING CALL. Node's console writer already enables virtual-terminal
14
+ * processing on Windows when stdout is a TTY (libuv does it when the stream is opened), so
15
+ * nothing needs to spawn a process to switch it on — and this module is barred from
16
+ * `child_process`.
27
17
  *
28
- * WHAT GATES IT. Little, now: the recorded snapshot corpus that replayed `art_for`, `_place`,
29
- * `_tile`, `_height`, `anim_ok` and `play_line` is gone with the reference.
18
+ * WHAT GATES IT. Little:
30
19
  * `tests/unit/wizard.test.mjs` asserts the wizard still plays the animation, and in the right
31
20
  * place; `tests/unit/no_panel.test.mjs` that this file is the one allowed its cursor escapes.
32
21
  */
@@ -168,11 +157,10 @@ export const DEFAULT = 'neutral';
168
157
  *
169
158
  * `Object.hasOwn`, not `ART[theme] ?? ART[DEFAULT]`. `ART['constructor']` is a function on
170
159
  * the prototype chain and therefore not nullish, so the `??` spelling would hand a Function
171
- * back to `play_line` where the reference hands back the neutral theme. The third table in
172
- * this port to carry the trap — `_icon` and `_mark` were the first two — and the corpus
173
- * names all four inherited keys.
160
+ * back to `playLine` where the neutral theme is wanted. `_icon` and `_mark` carry the same
161
+ * trap.
174
162
  */
175
- export function artFor(theme) {
163
+ function artFor(theme) {
176
164
  return Object.hasOwn(ART, theme) ? ART[theme] : ART[DEFAULT];
177
165
  }
178
166
 
@@ -182,10 +170,9 @@ const cut = (s, a, b) => Array.from(s).slice(a, b).join('');
182
170
  /**
183
171
  * `shutil.get_terminal_size((80, 24)).columns`.
184
172
  *
185
- * `parseIntStrict` and not `parseInt`, and the corpus has a case for exactly that: Python's `int()`
186
- * refuses `'80x'` outright and `get_terminal_size` swallows the ValueError into the fallback,
187
- * where `parseInt('80x')` is a cheerful 80. A width one column off is invisible in a terminal
188
- * and loud in a byte comparison. `<= 0` is the reference's own guard, which is why `'0'` and
173
+ * `parseIntStrict` and not `parseInt`: a strict parse refuses `'80x'` outright and the
174
+ * fallback applies, where `parseInt('80x')` is a cheerful 80. A width one column off is
175
+ * invisible in a terminal and loud in a byte comparison. `<= 0` is the guard, which is why `'0'` and
189
176
  * `'-5'` fall through to the fallback rather than producing a zero-width canvas.
190
177
  */
191
178
  function terminalColumns() {
@@ -206,14 +193,14 @@ function terminalColumns() {
206
193
  * unconditional refusal would disable the animation on the only platform whose users get the
207
194
  * line wizard by default.
208
195
  */
209
- export function animOk() {
196
+ function animOk() {
210
197
  if (process.env.GENESEED_NO_ANIM || process.env.GENESEED_TUI_PLAIN) return false;
211
198
  if (!process.stdout.isTTY) return false;
212
199
  const term = (process.env.TERM || '').toLowerCase();
213
200
  if (term === 'dumb' || term === '') {
214
201
  if (process.platform !== 'win32') return false;
215
202
  }
216
- // The reference's `os.system("")` goes here; see the module header for why it does not.
203
+ // No VT-enabling call is needed; see the module header.
217
204
  return true;
218
205
  }
219
206
 
@@ -270,10 +257,9 @@ const sleep = (ms) => {
270
257
  /**
271
258
  * `theme_anim.play_line` — scroll the themed sprite, then settle on the static card.
272
259
  *
273
- * Never raises: the reference wraps the animation in `except Exception` and degrades to the
274
- * static card, and `_setup_lines` wraps the whole call again in a bare `except: pass` marked
275
- * "cosmetic only — never block a successful install". Both layers are kept. A failed
276
- * animation must not be able to fail an install that already succeeded.
260
+ * Never raises: the animation degrades to the static card, and the caller wraps the whole
261
+ * call again ("cosmetic only — never block a successful install"). Both layers are kept. A
262
+ * failed animation must not be able to fail an install that already succeeded.
277
263
  */
278
264
  export function playLine(theme, ok = true) {
279
265
  const art = artFor(theme);