@ngockhoale/ukit 3.5.3 → 3.5.5

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 (70) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/manifests/documentation.yaml +12 -1
  3. package/manifests/platform.full.yaml +12 -0
  4. package/package.json +29 -2
  5. package/src/cli/commands/doctor.js +41 -0
  6. package/src/cli/commands/indexTools.js +10 -4
  7. package/src/cli/commands/memory.js +88 -6
  8. package/src/core/memory/episodes.js +106 -7
  9. package/src/core/memory/memoryCheck.js +241 -0
  10. package/src/core/memory/memoryCheckRun.js +39 -0
  11. package/src/core/memory/memoryHit.js +31 -15
  12. package/src/core/memory/mutateMemory.js +37 -1
  13. package/src/core/memory/observations.js +192 -0
  14. package/src/core/memory/recallEngine.js +159 -10
  15. package/src/core/memory/recallLanes.js +182 -0
  16. package/src/core/memory/records.js +23 -0
  17. package/src/core/memory/retrieval.js +13 -1
  18. package/src/core/memory/topicCommand.js +75 -0
  19. package/src/core/memory/topicPages.js +545 -0
  20. package/src/core/memory/writeGate.js +137 -0
  21. package/src/core/runtimeConfig.js +56 -1
  22. package/src/decision/registry.js +17 -0
  23. package/src/index/buildIndex.js +312 -5
  24. package/src/index/languageTools.js +100 -0
  25. package/src/index/paths.js +4 -1
  26. package/src/index/queryIndex.js +356 -14
  27. package/src/index/resolveContext.js +1 -1
  28. package/template_project/.claude/hooks/edit-hint.mjs +64 -17
  29. package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
  30. package/template_project/.claude/hooks/session-episode.sh +9 -4
  31. package/template_project/.claude/settings.json +2 -2
  32. package/template_project/.claude/ukit/index/lib/index-core.mjs +769 -18
  33. package/template_project/.claude/ukit/index/query-index.mjs +14 -3
  34. package/template_project/.claude/ukit/index/refresh-index.mjs +11 -0
  35. package/template_project/.claude/ukit/index/route-task.mjs +4 -1
  36. package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
  37. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +9 -2
  38. package/template_project/.claude/ukit/runtime/memory-recall.mjs +159 -10
  39. package/template_project/.claude/ukit/runtime/memory-topics.mjs +545 -0
  40. package/template_project/.claude/ukit/runtime/memory-validity.mjs +28 -1
  41. package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
  42. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  43. package/template_project/ukit/storage/config.json +21 -2
  44. package/manifests/instructionRules.yaml +0 -442
  45. package/src/core/agentRuntime/completionGate.js +0 -179
  46. package/src/core/agentRuntime/context.js +0 -571
  47. package/src/core/agentRuntime/qualityComparison.js +0 -112
  48. package/src/core/agentRuntime/resourcePolicy.js +0 -78
  49. package/src/core/agentRuntime/runtimeSupport.js +0 -255
  50. package/src/core/codeintel/manifest.js +0 -176
  51. package/src/core/experiments/deliberation.js +0 -327
  52. package/src/core/experiments/dynamicWorkflow.js +0 -507
  53. package/src/core/handoffDocValidator.js +0 -154
  54. package/src/core/memory/deltaOverlays.js +0 -493
  55. package/src/core/memory/learningCandidates.js +0 -347
  56. package/src/core/observability/emit/sessionBoot.js +0 -407
  57. package/src/core/observability/evaluation/replay.js +0 -149
  58. package/src/core/observability/evaluation/scorecard.js +0 -465
  59. package/src/core/observability/schema/compatibility.js +0 -180
  60. package/src/core/observability/support/renderer.js +0 -130
  61. package/src/core/reviewPanelAggregate.js +0 -204
  62. package/src/core/taskBudgetValidator.js +0 -251
  63. package/src/core/taskProgressGuard.js +0 -227
  64. package/src/decision/reviewVerdict.js +0 -339
  65. package/src/decision/runtimeFilter.js +0 -150
  66. package/src/decision/runtimeScheduler.js +0 -239
  67. package/src/index/contextPack.js +0 -285
  68. package/src/index/impactContext.js +0 -360
  69. package/src/index/reviewPolicy.js +0 -368
  70. package/src/index/sensitivePath.js +0 -21
package/CHANGELOG.md CHANGED
@@ -2,6 +2,42 @@
2
2
 
3
3
  All notable changes to UKit are documented here.
4
4
 
5
+ ## 3.5.5 - 2026-11-15
6
+
7
+ Module pages for memory, symbols for eight more languages, and a Vietnamese-to-code vocabulary for index search. Every number below was measured on this repository only. Finding a file from an ordinary question is still weak, and this entry says so with numbers.
8
+
9
+ - **Module pages (`ukit memory topic build|list|show|check`).** `ukit memory topic build <dir>` writes `docs/memory/topics/<dir>.md`: the directory's key files, what they export and the memory notes that name them. Recall reads the pages (`memory.topics.recall`, default on) and labels a page whose directory changed since it was built; the edit hint names the page of the file being edited (`memory.topics.hint`, default on). Nothing happens until a page exists. An index refresh rebuilds existing pages that went stale (`UKIT_MEMORY_TOPICS=0` turns the feature off). Measured on 12 questions about a module: 0 answered in the top 3 without pages, 10 with pages; under the stricter scoring 7. The main memory gold set is unchanged (37/38 answered, 10/10 no-answer questions stay silent). Pages are never read or written through a symbolic link, a module directory that is a link or leaves the project is refused, and a page is written to a temporary file and renamed. The rebuild on index refresh is covered by tests and was not exercised through a real git hook.
10
+ - **Symbols for Python, Go, Java, C#, PHP, Ruby, Rust and Svelte.** Functions, classes, methods and types in these files are now indexed (line-based parsers, no new dependency), their test files are recognised (`_test.go`, `test_*.py`, `*Test.java`, `_spec.rb` and similar), and the error-text search reads them. Covered by unit tests on small fixtures; in this repository only Python files exist (219 symbols). No real project in the other languages was indexed. These parsers skip files over 512 KB and lines over 2,000 characters, so a hostile file cannot stall the build. Known limit: a C# method whose attribute is on the same line as its declaration (`[HttpGet] public Task<IActionResult> Get(…)`) is not indexed as a symbol; put the attribute on its own line, as most C# code does. Java annotations on the same line are indexed. The index schema version is now 11: the first build after the update re-parses every file once.
11
+ - **Fewer wrong `callable` symbols.** `const x = (…)` expressions that are not functions are no longer marked callable (465 → 16 by the build's own count), and about 50 real functions the old rule missed are now found.
12
+ - **Vietnamese questions map to code words.** About 60 Vietnamese phrases and words (diacritics optional) expand to the English terms used in code, and questions of five or more words also match word stems. On the 67-query gold set (floor now `scripts/bench/baselines/index-gold-3.5.5.json`): right file first 86.6% → 89.5%, top 3 unchanged at 92.5%; English sentence first 72.7 → 81.8, Vietnamese sentence first 50 → 60; no group lower.
13
+ - **Honest limit: ordinary questions still rarely find the file.** On a sealed set of 40 questions written by a separate agent and never shown to the people tuning the search (`scripts/bench/indexBlind.json`, 20 English + 20 Vietnamese), the right file is in the top 3 for English 3/20 in 3.5.4 → 2/20 now, for Vietnamese 2/20 → 4/20 (5/20 on an earlier state of this tree: one question sits at the edge of the top 3). The gold-set gain above is therefore partly fitted to its own questions. Searching by symbol name, path or error text is unaffected (100 / 100 / 90% first).
14
+ - **Built, measured, not shipped:** a per-file description text (leading comments) used to re-rank results changed nothing on the sealed set, and 144 ways of letting it propose files lowered the gold set — the code was removed. Adding symbol evidence to test hints moved recall from 0.072 to 0.079, which is noise — no change.
15
+ - **Shipped off by default, because the numbers did not rise:** index lane fusion (`index.fusion`, `UKIT_INDEX_FUSION=1`); a hashed vector lane for memory recall (`memory.recall.vector.enabled`; with it on, memory gold fell from 37/38 to 35/38); re-ranking recall with the local `unic-decision` model (`memory.recall.rerank.stage`, registry entry `memory.relevance.v1`; no change in results, measured in one live batch before the final recall code). No embedding endpoint is configured, so no real semantic lane was measured.
16
+ - **Recall understands a file name in the question.** A question that names a file only returns notes about that file, and camelCase words in a question are split. On 12 questions that name a file or symbol: 11 answered, and all 4 with no answer stay silent.
17
+ - Package: `manifests/instructionRules.yaml` (read only by tests) is no longer packed; 728 files, 3.46 MB packed, 11.22 MB unpacked (limits unchanged, about 80 KB of headroom).
18
+ - Engines: pages, recall and index code are shared runtime and CLI code used by Claude Code, omp (through the bridge) and Codex (through the CLI helpers). None of the three hosts was run live for this release, and nothing was run on Windows.
19
+
20
+ ## 3.5.4 - 2026-11-15
21
+
22
+ The index now knows almost every function and can search file contents for error text; memory writes pass a gate and `docs/MEMORY.md` becomes a capped core. Every number below was measured on this repository only.
23
+
24
+ - **The index covers functions that are not exported.** Non-exported functions, arrow-function constants, class methods and TypeScript `interface` / `type` / `enum` declarations are now symbols. Function declarations under `src/` that the index knows: 745 of 2,289 (32.5%, the frozen 3.5.3 baseline) → 2,334 of 2,336 (99.9%). An unexported symbol weighs slightly less than an exported one, and the outline of a file now always shows the symbols the query matched.
25
+ - **Error text is searched in file contents.** When no symbol or path matches well and the query is three or more plain words, `query-index` scans source files for the text (at most 1,500 files, 512 KB per file, 5 s; a cut-off scan prints `content-lane: truncated (<reason>)`). The scan order is fixed, so the same query gives the same answer under load. Edit-time hooks do not run it.
26
+ - **Measured on the 67-query gold set** (`scripts/bench/index-gold.mjs`; before = 3.5.3, frozen in `scripts/bench/baselines/index-gold-3.5.3.json`; after frozen in `index-gold-3.5.4.json`, three identical runs): right file first 61.2% → 86.6%, in the top 3 65.7% → 92.5%, the right line 47.1% → 100% of the 34 queries that have one. Per group, first / top 3: unexported symbol 8.3 → 100 / 16.7 → 100; error string 40 → 90 / 50 → 100; English sentence 63.6 → 72.7 / 72.7 → 81.8; Vietnamese sentence 50 → 50 / 50 → 70; exported symbol and path stay 100 / 100. No group got worse. A mirror outranks its original in 2 of 12 queries (was 3). Median query 3.3 → 6.9 ms, p95 6 → 38 ms (the content scan); median result size 3,735 → 5,457 bytes. A test holds every group at these numbers.
27
+ - **Cost:** `symbols.json` for this repository grows from 1,062,577 to 2,319,331 bytes and a full index build went from 1.30 s to 1.45 s (one clean build each of the 3.5.3 tree and this tree in temporary copies, by the maintainer; not part of the frozen baselines).
28
+ - **`docs/MEMORY.md` is a capped core.** One line per decision, at most 150 lines and 12 KB, each line pointing at a detail file under `docs/memory/`. Recall reads the core and every `docs/memory/*.md` (`memory.sources`, default `docs/MEMORY.md` + `docs/memory/*.md`); when a core line and its detail both match, only the detail is returned. On this repository recall output got 14% smaller with the same gold result. Existing projects keep working unchanged: a `docs/MEMORY.md` over the cap is reported, never rewritten.
29
+ - **`ukit memory check`** reports a core over its cap, a `Detail:` pointer to a missing file, and notes that name no existing file (warning only). After an edit to a memory file the edit hint carries the same findings (Claude Code and omp; Codex runs the command).
30
+ - **A note can replace another:** tag the old bullet `[id: <slug>]` and the new one `[supersedes: <slug>]`; recall drops the old one.
31
+ - **Memory writes pass a gate** (`memory.writeGate`, default `strict`; `off` disables). `ukit memory --user add/update`, `ukit memory v2 promote/stale` and `ukit memory propose` reject text over 1,200 characters, text containing a secret, and a near-duplicate of an existing entry; project record changes also need evidence (an existing file, a commit, an episode). A rejection prints `[UKit] rejected: <code>: <reason> (to pass: <fix>)` and exits 1 — secret rejections included, which used to exit 0. Every write to the user store is gated while the gate is on, because that store is shared across projects; `off` disables the gate there too. Not gated: records written by hooks and generators, and other library callers (size cap only). There is no project-level `memory add` command; the agent's project write path is editing the markdown files, which `ukit memory check` covers.
32
+ - **Episodes are written during long sessions, not only at session end.** A session-start step (Claude Code: startup, resume, clear, compact; omp: session start and compact; Codex: on a routed prompt, at most every 10 minutes) records finished tasks' episodes in the background, at most 25 per run. Three causes of empty stores are fixed: episodes waited for SessionEnd, paths were dropped when the project root was spelled differently, and only the newest 25 ledgers were scanned. An episode without a real project file is not recorded. On this repository the first run recorded 11 episodes (37 with content in total).
33
+ - **A stale global `ukit` is refused for episode writes.** If the `ukit` on PATH is older than the installed runtime, the step does not use it and `ukit doctor` says why. On Windows the PATH lookup follows `PATHEXT` (`ukit.cmd`, `ukit.exe`); that path is covered by tests with an injected platform and was not run on Windows. A project deleted while the step runs is not recreated.
34
+ - **`ukit memory observe`** proposes observations from episodes (files written together, a repeated failing check, a follow-up task), each citing its episodes; an observation whose evidence is gone is labelled. Proposals only — nothing is written. With the default minimum of 3 supporting episodes it proposes nothing on this repository's 37 episodes; at 2 it proposes two pairs, both correct. It has no measured value yet.
35
+ - **A long episode no longer answers on common words alone.** An episode must cover at least half of the question's weighted words. Found when the new episodes made one no-answer question return unrelated release tasks. Memory gold: answer in the top 3 stays 37/38, no-answer questions that stay silent 10/10.
36
+ - **The npm package drops 26 unused modules (about 270 KB).** Modules under `src/` that nothing in the shipped runtime imports (kept in the repository for tests and benchmarks) are no longer packed; a new test fails if a packed file ever imports one of them. Package: 725 files, 3.42 MB packed.
37
+ - Engines: index, recall, gate and check are shared runtime and CLI code used by Claude Code, omp (through the bridge) and Codex (through the CLI helpers). None of the three hosts was run live for this release, including the new session-start step; coverage is the tests and benches above.
38
+ - Correction to the 3.5.3 entry below: its "752 of 2,299 (32.7%)" coverage, "3,788 bytes" median result and "3.8 ms" median query do not match the frozen 3.5.3 baseline file, which holds 745 of 2,289 (32.5%), 3,735 bytes and 3.3 ms. The baseline file is the measurement; the ranking percentages in that entry do match it.
39
+ - Still weak: Vietnamese sentences (right file first 50%); test hints per source file (unchanged); 403 of the index's 2,713 `callable` symbols are `const x = (…)` expressions, not functions (an older rule, not new here).
40
+
5
41
  ## 3.5.3 - 2026-11-15
6
42
 
7
43
  Source index ranking, and memory that knows when the code it describes has changed. Every number below was measured on this repository only.
@@ -223,7 +223,18 @@ entries:
223
223
  validation: [manual]
224
224
  archive_policy: never
225
225
  budget: { max_lines: 110, enforcement: warning }
226
- notes: 'recalibrated TASK-217: actual 82 lines; 200 was ~2.4× actual — 110 leaves ~34% headroom'
226
+ notes: 'recalibrated TASK-217: actual 82 lines; 200 was ~2.4× actual — 110 leaves ~34% headroom. 3.5.4: the core is capped at 150 lines / 12000 bytes by `ukit memory check`; this warning budget stays tighter'
227
+ - id: docs-memory-detail
228
+ path: docs/memory/
229
+ class: canonical
230
+ audience: [agent, maintainer]
231
+ owner: product
232
+ source_of_truth: docs/memory/
233
+ merge_strategy: none
234
+ load_policy: on-demand
235
+ validation: [manual]
236
+ archive_policy: never
237
+ notes: '3.5.4: verbatim detail for the one-line items in docs/MEMORY.md; listed in memory.sources so recall still reaches it'
227
238
  - id: docs-project
228
239
  path: docs/PROJECT.md
229
240
  class: canonical
@@ -1654,6 +1654,18 @@ items:
1654
1654
  packs:
1655
1655
  - core
1656
1656
 
1657
+ - id: hook-session-episode-start-module
1658
+ type: hook
1659
+ sourceTemplate: .claude/hooks/session-episode-start.mjs
1660
+ targetPath: .claude/hooks/session-episode-start.mjs
1661
+ requires:
1662
+ - ukit-runtime-scripts
1663
+ mergeStrategy: overwrite_with_backup
1664
+ variables: []
1665
+ enabledByDefault: true
1666
+ packs:
1667
+ - core
1668
+
1657
1669
  - id: hook-session-episode
1658
1670
  type: hook
1659
1671
  sourceTemplate: .claude/hooks/session-episode.sh
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ngockhoale/ukit",
3
- "version": "3.5.3",
3
+ "version": "3.5.5",
4
4
  "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -59,6 +59,32 @@
59
59
  "!src/skill/auditSkill.js",
60
60
  "!src/core/observability/evaluation/perturbation.js",
61
61
  "!src/core/observability/evaluation/experimentPlan.js",
62
+ "!src/core/agentRuntime/context.js",
63
+ "!src/core/agentRuntime/runtimeSupport.js",
64
+ "!src/core/agentRuntime/completionGate.js",
65
+ "!src/core/agentRuntime/qualityComparison.js",
66
+ "!src/core/agentRuntime/resourcePolicy.js",
67
+ "!src/core/memory/deltaOverlays.js",
68
+ "!src/core/memory/learningCandidates.js",
69
+ "!src/core/experiments/dynamicWorkflow.js",
70
+ "!src/core/experiments/deliberation.js",
71
+ "!src/core/observability/evaluation/scorecard.js",
72
+ "!src/core/observability/evaluation/replay.js",
73
+ "!src/core/observability/emit/sessionBoot.js",
74
+ "!src/core/observability/schema/compatibility.js",
75
+ "!src/core/observability/support/renderer.js",
76
+ "!src/core/reviewPanelAggregate.js",
77
+ "!src/core/taskBudgetValidator.js",
78
+ "!src/core/taskProgressGuard.js",
79
+ "!src/core/handoffDocValidator.js",
80
+ "!src/core/codeintel/manifest.js",
81
+ "!src/index/reviewPolicy.js",
82
+ "!src/index/impactContext.js",
83
+ "!src/index/contextPack.js",
84
+ "!src/index/sensitivePath.js",
85
+ "!src/decision/reviewVerdict.js",
86
+ "!src/decision/runtimeScheduler.js",
87
+ "!src/decision/runtimeFilter.js",
62
88
  "!scripts/bench/**",
63
89
  "scripts/bench/decision-runtime-metrics.mjs",
64
90
  "!scripts/perf/**",
@@ -71,7 +97,8 @@
71
97
  "!template_project/**/skill-router-state.json",
72
98
  "CHANGELOG.md",
73
99
  "template_project/.gitignore",
74
- "manifests/"
100
+ "manifests/",
101
+ "!manifests/instructionRules.yaml"
75
102
  ],
76
103
  "publishConfig": {
77
104
  "access": "public"
@@ -318,6 +318,39 @@ async function inspectCodexSurface({ projectRoot, packageRoot }) {
318
318
  };
319
319
  }
320
320
 
321
+ // Lines for `ukit doctor`: cli.json missing / invalid / older than the installed runtime,
322
+ // plus the last reason a hook refused to write episodes (episode-cli.json).
323
+ export async function inspectEpisodeCli({ projectRoot, runtimeVersion = null }) {
324
+ const readJson = async (rel) => {
325
+ try { return JSON.parse(await fs.readFile(path.join(projectRoot, rel), 'utf8')); } catch { return null; }
326
+ };
327
+ const lines = [];
328
+ const loc = await readJson(path.join('.ukit', 'storage', 'cli.json'));
329
+ const vnum = (v) => (/(\d+)\.(\d+)\.(\d+)/.exec(String(v ?? '')) ?? []).slice(1).map(Number);
330
+ const older = (a, b) => {
331
+ const x = vnum(a); const y = vnum(b);
332
+ if (x.length !== 3 || y.length !== 3) return false;
333
+ for (let i = 0; i < 3; i += 1) if (x[i] !== y[i]) return x[i] < y[i];
334
+ return false;
335
+ };
336
+ if (!loc || typeof loc.node !== 'string' || typeof loc.bin !== 'string') {
337
+ lines.push('WARN episode CLI locator (.ukit/storage/cli.json) missing or invalid - rerun ukit install');
338
+ } else if (!(await pathExists(loc.bin)) || !(await pathExists(loc.node))) {
339
+ lines.push('WARN episode CLI locator points at a missing node/bin - rerun ukit install');
340
+ } else if (runtimeVersion && older(loc.version, runtimeVersion)) {
341
+ lines.push(`WARN episode CLI locator is stale (cli.json ${loc.version} < runtime ${runtimeVersion}) - rerun ukit install`);
342
+ }
343
+ const state = await readJson(path.join('.ukit', 'storage', 'learning', 'episode-cli.json'));
344
+ if (state && state.ok === false && state.reason) lines.push(`WARN episodes not written by hooks: ${state.reason} (${state.at ?? 'unknown time'})`);
345
+ const last = await readJson(path.join('.ukit', 'storage', 'learning', 'episode-start-result.json'));
346
+ if (last) {
347
+ if (last.ok === true) lines.push(`episode start trigger: last run ok (recorded=${last.recorded} skipped=${last.skipped} failed=${last.failed}) at ${last.at}`);
348
+ else if (last.ok === false) lines.push(`WARN episode start trigger: last run failed - ${last.reason} (${last.at})`);
349
+ else lines.push(`WARN episode start trigger: last worker never finished (started ${last.at})`);
350
+ }
351
+ return lines;
352
+ }
353
+
321
354
  function printCodexSurfaceSection(surface) {
322
355
  const mark = (v) => (v ? '✓' : '✗');
323
356
  console.log('[UKit] Codex surface checks (advisory — never affects exit code):');
@@ -779,6 +812,14 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
779
812
  // enters `checks` or `projectChecks` and cannot move the exit code.
780
813
  printCodexSurfaceSection(await inspectCodexSurface({ projectRoot, packageRoot }));
781
814
 
815
+ // 3.5.4 — episode CLI locator. Advisory: a missing/stale cli.json makes episode hooks
816
+ // fall back to a PATH `ukit` (refused when older than the runtime).
817
+ if (installMeta) {
818
+ for (const line of await inspectEpisodeCli({ projectRoot, runtimeVersion: installMeta.version })) {
819
+ console.log(`[UKit] ${line}`);
820
+ }
821
+ }
822
+
782
823
 
783
824
  // TASK-C85-014 (BL-014) — verification-map recipe check. Advisory only:
784
825
  // warn rows never enter the blocking set and never fabricate a command —
@@ -8,7 +8,7 @@ import {
8
8
  import { resolveContext } from '../../index/resolveContext.js';
9
9
  import { deriveVerificationPlan } from '../../index/verificationPlan.js';
10
10
  import { deriveTaskRoute } from '../../index/taskRouting.js';
11
- import { queryCodeIndex, getFileOutline } from '../../index/queryIndex.js';
11
+ import { queryCodeIndex, getFileOutline, queryMatchedSymbolNames } from '../../index/queryIndex.js';
12
12
  import { triageBug } from '../../bug/triageBug.js';
13
13
  import { installIndexRefreshHooks, removeIndexRefreshHooks } from '../../index/gitHooks.js';
14
14
  import fs from 'node:fs/promises';
@@ -72,8 +72,13 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
72
72
  limit: Number.isNaN(limit) ? 5 : limit,
73
73
  });
74
74
 
75
+ const contentLaneNotice = results.contentLaneTruncated?.length
76
+ ? `content-lane: truncated (${results.contentLaneTruncated.join(',')}) — results may be incomplete`
77
+ : null;
78
+
75
79
  if (results.length === 0) {
76
80
  console.log('[UKit] No index matches found.');
81
+ if (contentLaneNotice) console.log(contentLaneNotice);
77
82
  return;
78
83
  }
79
84
 
@@ -88,9 +93,10 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
88
93
  console.log(` reasons: ${item.reasons.join(', ')}`);
89
94
  }
90
95
  if (showOutline && idx < OUTLINE_TOP_FILES_LIMIT) {
91
- await printOutlineForFile(projectRoot, item.filePath);
96
+ await printOutlineForFile(projectRoot, item.filePath, queryMatchedSymbolNames(item));
92
97
  }
93
98
  }
99
+ if (contentLaneNotice) console.log(contentLaneNotice);
94
100
  return;
95
101
  }
96
102
 
@@ -418,8 +424,8 @@ async function refreshIndexIfStale(rootDir) {
418
424
  return true;
419
425
  }
420
426
 
421
- async function printOutlineForFile(rootDir, filePath) {
422
- const outline = await getFileOutline({ rootDir, filePath, limit: Infinity });
427
+ async function printOutlineForFile(rootDir, filePath, focus = null) {
428
+ const outline = await getFileOutline({ rootDir, filePath, limit: Infinity, focus });
423
429
  if (outline.length === 0) {
424
430
  return;
425
431
  }
@@ -22,6 +22,7 @@ import { runMigration } from '../../core/memory/migrate.js';
22
22
  import { createBackup, restoreBackup, diagnoseStore } from '../../core/memory/storeBackup.js';
23
23
  import { mutateMemory } from '../../core/memory/mutateMemory.js';
24
24
  import { redactWritePayload } from '../../core/memory/writeGuard.js';
25
+ import { checkProposalText } from '../../core/memory/writeGate.js';
25
26
  import { deletePromptCacheEntries } from '../../core/token/index.js';
26
27
  import { expand, getContextInjection, search } from '../../core/memory/retrieval.js';
27
28
  import { inspectRuntimeConfig } from '../../core/runtimeConfig.js';
@@ -29,7 +30,7 @@ import { buildRuntimePaths } from '../../core/runtimePaths.js';
29
30
  import { buildUserPaths } from '../../core/userPaths.js';
30
31
  import { pathExists } from '../../core/fileOps.js';
31
32
  import { detectProjectContext } from '../../context/detectProjectContext.js';
32
- import { episodeText, readRouteState, resolveLedger, writeEpisode } from '../../core/memory/episodes.js';
33
+ import { backfillEpisodes, episodeText, readRouteState, resolveLedger, writeEpisode } from '../../core/memory/episodes.js';
33
34
  import { archiveLegacyEpisodes, purgeArchivedEpisode, restoreArchivedEpisodes } from '../../core/memory/episodeArchive.js';
34
35
  import { loadMarkdownDocs, normalizeMemorySources } from '../../core/memory/recallEngine.js';
35
36
  import { captureAnchors } from '../../../template_project/.claude/ukit/runtime/memory-validity.mjs';
@@ -99,11 +100,25 @@ async function listAllPendingPatternCandidates(projectRoot, runtimePaths, { home
99
100
  }
100
101
  // FR-025: guard rejections surface labels only — never the matched value or
101
102
  // record body. Returns true when the result was a handled rejection.
103
+ const GATE_FIXES = {
104
+ 'too-large': 'shorten the text (one line); put detail in docs/memory/',
105
+ 'no-evidence': 'name an existing file, a commit sha or an episode id as evidence',
106
+ 'near-duplicate': 'update the existing record instead, or replace it with supersedes',
107
+ };
102
108
  function printGuardRejection(res) {
109
+ // Write-gate rejections (3.5.4): one line with the typed reason and what makes
110
+ // it pass, and a non-zero exit so an agent cannot mistake it for success.
111
+ if (res.code && GATE_FIXES[res.code]) {
112
+ console.log(`[UKit] rejected: ${res.reason} (to pass: ${GATE_FIXES[res.code]})`);
113
+ process.exitCode = 1;
114
+ return;
115
+ }
103
116
  const labels = Array.isArray(res.labels) && res.labels.length > 0
104
117
  ? res.labels.join(', ')
105
118
  : 'unknown';
106
119
  console.log(`[UKit] rejected: ${res.reason ?? 'secret-detected'} (${labels})`);
120
+ // Secret rejections are failures too: a non-zero exit on every CLI write path.
121
+ if ((res.reason ?? 'secret-detected') === 'secret-detected') process.exitCode = 1;
107
122
  }
108
123
 
109
124
  // Shared mutateMemory error mapping for CLI write ops: conflict/not-found/
@@ -219,6 +234,7 @@ async function runMemoryV2(projectRoot, homeDir, args) {
219
234
  { kind: 'project', projectRoot, homeDir },
220
235
  {
221
236
  op: 'update',
237
+ actor: 'agent',
222
238
  payload: {
223
239
  id,
224
240
  patch: {
@@ -254,6 +270,7 @@ async function runMemoryV2(projectRoot, homeDir, args) {
254
270
  { kind: 'project', projectRoot, homeDir },
255
271
  {
256
272
  op: 'update',
273
+ actor: 'agent',
257
274
  payload: { id, patch: { status: 'stale' } },
258
275
  expectedRevision: record.revision,
259
276
  },
@@ -315,7 +332,17 @@ async function runMemoryV2(projectRoot, homeDir, args) {
315
332
 
316
333
  const USER_MEMORY_OPS = new Set(['list', 'add', 'get', 'update', 'forget', 'purge', 'stats']);
317
334
 
318
- async function runUserMemory(homeDir, args) {
335
+ // The user store has no project config; honour the current project's memory.writeGate.
336
+ async function userWriteGate(projectRoot, homeDir) {
337
+ try {
338
+ const { config } = await inspectRuntimeConfig(projectRoot, { homeDir });
339
+ return config?.memory?.writeGate;
340
+ } catch {
341
+ return undefined;
342
+ }
343
+ }
344
+
345
+ async function runUserMemory(homeDir, args, projectRoot = process.cwd()) {
319
346
  const rest = (args[0] ?? '').toLowerCase() === 'v2' ? args.slice(1) : args;
320
347
  const op = (rest[0] ?? 'list').toLowerCase();
321
348
  const opArgs = rest.slice(1);
@@ -358,6 +385,8 @@ async function runUserMemory(homeDir, args) {
358
385
  { kind: 'user', homeDir },
359
386
  {
360
387
  op: 'add',
388
+ actor: 'agent',
389
+ writeGate: await userWriteGate(projectRoot, homeDir),
361
390
  payload: {
362
391
  type: typeFlag.value ?? 'derived_fact',
363
392
  scope: scopeFlag.value ?? 'user',
@@ -414,7 +443,7 @@ async function runUserMemory(homeDir, args) {
414
443
  }
415
444
  const res = await mutateMemory(
416
445
  { kind: 'user', homeDir },
417
- { op: 'update', payload: { id, patch } },
446
+ { op: 'update', actor: 'agent', writeGate: await userWriteGate(projectRoot, homeDir), payload: { id, patch } },
418
447
  );
419
448
  const handled = handleMutationResult(res, {
420
449
  notFoundMessage: `User memory record not found: ${id}`,
@@ -582,6 +611,14 @@ async function runMemoryEpisode(projectRoot, homeDir, args) {
582
611
  return;
583
612
  }
584
613
 
614
+ // SessionStart trigger: finished tasks of earlier ledgers (idle) and of the open session
615
+ // (spool only), bounded to the newest 25 ledgers. Same dedupe keys as SessionEnd.
616
+ if (args.includes('--start')) {
617
+ const s = await backfillEpisodes(projectRoot, { config, homeDir, limit: 25, spoolsOnly: true });
618
+ console.log(`[UKit] episode --start: recorded=${s.recorded} skipped=${s.skipped} failed=${s.failed}${s.reason ? ` reason=${s.reason}` : ''}`);
619
+ return;
620
+ }
621
+
585
622
  const { ledger, ledgerKey } = await resolveLedger(projectRoot, sessionFlag ?? process.env.UKIT_SESSION_ID);
586
623
  if (!ledger) {
587
624
  console.log('[UKit] episode: nothing to record');
@@ -710,6 +747,27 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
710
747
  return;
711
748
  }
712
749
 
750
+ // 3.5.4: `check` only reads the markdown memory sources (cap, size, secrets,
751
+ // near-duplicates, supersession), so it runs without the runtime gate too.
752
+ // Exit 1 on violations; --json for machines.
753
+ if (subcommand === 'check') {
754
+ const { runMemoryCheck } = await import('../../core/memory/memoryCheckRun.js');
755
+ const res = await runMemoryCheck(projectRoot, rest);
756
+ console.log(res.output);
757
+ if (!res.ok) process.exitCode = 1;
758
+ return;
759
+ }
760
+
761
+ // 3.5.5: topic pages (docs/memory/topics/*.md) are generated from the index and
762
+ // the edit graph; build/list/show/check need no runtime gate.
763
+ if (subcommand === 'topic') {
764
+ const { runTopicCommand } = await import('../../core/memory/topicCommand.js');
765
+ const res = await runTopicCommand(projectRoot, rest);
766
+ console.log(res.output);
767
+ if (!res.ok) process.exitCode = 1;
768
+ return;
769
+ }
770
+
713
771
  // --user operates on ~/.ukit and does not require the project runtime.
714
772
  if (!isUser && !(await pathExists(runtimePaths.runtimeRoot))) {
715
773
  throw new Error('Shared UKit runtime not found. Run `ukit install` first.');
@@ -720,7 +778,7 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
720
778
 
721
779
 
722
780
  if (isUser) {
723
- await runUserMemory(homeDir, argvRest);
781
+ await runUserMemory(homeDir, argvRest, projectRoot);
724
782
  return;
725
783
  }
726
784
 
@@ -764,6 +822,25 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
764
822
  }
765
823
 
766
824
  const projectId = projectFlag.value ?? (await detectProjectContext(projectRoot, { homeDir })).project.name;
825
+ // 3.5.4 gate: size, secrets, near-duplicate of pending/approved candidates.
826
+ const { config: gateConfig } = await inspectRuntimeConfig(projectRoot, { homeDir });
827
+ const pending = await listPendingPatternCandidates(projectRoot, projectId, { homeDir });
828
+ const exported = await exportMemory(projectRoot, { homeDir });
829
+ const approved = (exported.projects.find((p) => p.id === projectId)?.conventions ?? [])
830
+ .map((t, i) => ({ id: `approved convention #${i + 1}`, text: t }));
831
+ const gate = checkProposalText({
832
+ text,
833
+ existing: [...pending.map((c) => ({ id: c.id, text: c.text })), ...approved],
834
+ config: gateConfig,
835
+ projectId,
836
+ });
837
+ if (!gate.ok) {
838
+ printGuardRejection(gate.code === 'secret-detected'
839
+ ? { reason: gate.reason, labels: gate.labels }
840
+ : gate);
841
+ process.exitCode = 1;
842
+ return;
843
+ }
767
844
  const candidate = await proposePatternCandidate(projectRoot, projectId, {
768
845
  text,
769
846
  category: categoryFlag.value,
@@ -964,6 +1041,8 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
964
1041
  return;
965
1042
  }
966
1043
 
1044
+ if (subcommand === 'observe') { await (await import('../../core/memory/observations.js')).runObserve(projectRoot, rest); return; }
1045
+
967
1046
  if (subcommand === 'archive-episodes') {
968
1047
  if (rest.includes('--restore')) {
969
1048
  const r = await restoreArchivedEpisodes(projectRoot, { homeDir });
@@ -1035,7 +1114,7 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
1035
1114
 
1036
1115
  export function printMemoryHelp() {
1037
1116
  console.log('UKit Memory Commands');
1038
- console.log('Usage: ukit memory <list|search|expand|recall|forget|purge|export|propose|approve|reject|learn|promote|episode|archive-episodes|hygiene|backup|restore|doctor> [args]');
1117
+ console.log('Usage: ukit memory <list|search|expand|recall|forget|purge|export|propose|approve|reject|learn|promote|episode|observe|archive-episodes|check|hygiene|backup|restore|doctor> [args]');
1039
1118
  console.log('');
1040
1119
  console.log('Subcommands:');
1041
1120
  console.log(' list List memory items in shared .ukit/storage/memory');
@@ -1051,7 +1130,10 @@ export function printMemoryHelp() {
1051
1130
  console.log(' reject <id> [--project <id>] Reject a pending pattern candidate');
1052
1131
  console.log(' learn [--apply] [--min <n>] [--project <id>] Propose pending candidates from mined failure patterns (dry-run by default)');
1053
1132
  console.log(' promote [--dry-run] Render approved rules/procedures into the ## ukit-learned block in docs/MEMORY.md');
1054
- console.log(' episode [--dry-run] [--session <id>] Write a session episode record from the exec-ledger');
1133
+ console.log(' episode [--dry-run] [--session <id>|--start] Write a session episode record from the exec-ledger');
1134
+ console.log(' topic build <dir>|list|show <dir>|check Module pages under docs/memory/topics (generated skeleton; stale when the directory changed)');
1135
+ console.log(' observe [--min <n>] [--json] Propose observations from repeated content-bearing episodes (proposals only; nothing is written)');
1136
+ console.log(' check [--json] [--file <rel>] Check docs/MEMORY.md + memory.sources against the memory rules (core cap, size, secrets, near-duplicates, supersession); exit 1 on violations');
1055
1137
  console.log(' archive-episodes [--dry-run|--restore] Move content-free legacy episodes to episodes-archive.json (backup first; --restore re-adds them)');
1056
1138
  console.log(' hygiene [--project <id>] Run decision-conflict resolution + session archiving now');
1057
1139
  console.log(' backup [--out <dir>] [--user] Snapshot v2 store(s) + sha256 manifest into a backup dir');
@@ -10,6 +10,7 @@
10
10
  // differ, and Codex has no stop event at all.
11
11
 
12
12
  import fs from 'node:fs/promises';
13
+ import { realpathSync } from 'node:fs';
13
14
  import path from 'node:path';
14
15
 
15
16
  import { loadRecords } from './storeV2.js';
@@ -60,6 +61,24 @@ const LINE_MAX = 160;
60
61
 
61
62
  const oneLine = (value, max) => String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
62
63
 
64
+ // Orchestrator envelopes that precede the real task: `[ukit-task <id>]`, a bare leading
65
+ // `TASK-xxx:` tag, "Complete assignment thoroughly:". Stripped (repeatedly) BEFORE the length
66
+ // cut so the stored summary carries the actual task. A prompt that is only boilerplate is kept.
67
+ const BOILERPLATE_PREFIX_RES = [
68
+ /^\[ukit-task[^\]]*\]\s*/i,
69
+ /^(?:TASK|C\d+)-[A-Za-z0-9-]*\s*[:\-–]\s+/,
70
+ /^complete assignment thoroughly\s*[:.\-–]?\s*/i,
71
+ ];
72
+ export function stripPromptBoilerplate(value) {
73
+ let text = String(value ?? '').replace(/\s+/g, ' ').trim();
74
+ for (let guard = 0; guard < 8; guard += 1) {
75
+ const next = BOILERPLATE_PREFIX_RES.reduce((acc, re) => acc.replace(re, ''), text);
76
+ if (next === text) break;
77
+ text = next;
78
+ }
79
+ return text || String(value ?? '').replace(/\s+/g, ' ').trim();
80
+ }
81
+
63
82
  export async function readRouteState(projectRoot, sessionKey) {
64
83
  if (!sessionKey) return null;
65
84
  return readJsonIfExists(path.join(
@@ -71,10 +90,50 @@ export async function readRouteState(projectRoot, sessionKey) {
71
90
  // project (keeps home-directory paths out of the store).
72
91
  function relativeWritten(projectRoot, file) {
73
92
  if (typeof file !== 'string' || !file.trim()) return null;
93
+ // Ledger receipts also carry pseudo targets (`agent:/Main`, `bash-workspace:<h>:<h>`):
94
+ // a scheme-like prefix (2+ chars, so a Windows drive letter still passes) is not a file.
95
+ if (/^[A-Za-z][A-Za-z0-9._-]+:/.test(file.trim())) return null;
74
96
  const abs = path.isAbsolute(file) ? file : path.join(projectRoot, file);
75
- const rel = path.relative(projectRoot, abs);
76
- if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
77
- return rel.split(path.sep).join('/');
97
+ // A receipt may hold the unresolved spelling of the root (macOS /var vs /private/var,
98
+ // symlinked checkouts) while the CLI runs from the resolved one: accept either.
99
+ const candidates = [abs];
100
+ const resolved = realpathLoose(abs);
101
+ if (resolved !== abs) candidates.push(resolved);
102
+ for (const root of rootSpellings(projectRoot)) {
103
+ for (const candidate of candidates) {
104
+ const rel = path.relative(root, candidate);
105
+ if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) return rel.split(path.sep).join('/');
106
+ }
107
+ }
108
+ return null;
109
+ }
110
+
111
+ // realpath of the nearest existing ancestor + the unresolved tail (the file may be gone).
112
+ function realpathLoose(file) {
113
+ let head = file;
114
+ let tail = '';
115
+ for (let i = 0; i < 64; i += 1) {
116
+ try { return path.join(realpathSync(head), tail); } catch { /* climb */ }
117
+ const parent = path.dirname(head);
118
+ if (parent === head) return file;
119
+ tail = tail ? path.join(path.basename(head), tail) : path.basename(head);
120
+ head = parent;
121
+ }
122
+ return file;
123
+ }
124
+
125
+ const rootSpellingCache = new Map();
126
+ function rootSpellings(projectRoot) {
127
+ let spellings = rootSpellingCache.get(projectRoot);
128
+ if (!spellings) {
129
+ spellings = [projectRoot];
130
+ try {
131
+ const real = realpathSync(projectRoot);
132
+ if (real !== projectRoot) spellings.push(real);
133
+ } catch { /* root vanished: the literal spelling is all there is */ }
134
+ rootSpellingCache.set(projectRoot, spellings);
135
+ }
136
+ return spellings;
78
137
  }
79
138
 
80
139
  // Strips a leading `cd <root>;|&&` and rewrites remaining occurrences of the
@@ -108,6 +167,9 @@ export function buildEpisode(ledger, { routeState = null, projectRoot = '' } = {
108
167
  const rel = relativeWritten(projectRoot, r.file);
109
168
  if (rel && !files.includes(rel)) files.push(rel);
110
169
  }
170
+ // No real project file (only pseudo targets or paths outside the project): nothing
171
+ // verifiable to remember. A content-free record would only crowd the store.
172
+ if (files.length === 0) return null;
111
173
  const verifications = receipts.filter((r) => r.kind === 'verification');
112
174
  const lastVerification = verifications.length > 0 ? verifications[verifications.length - 1] : null;
113
175
  const command = oneLine(normalizeCommand(lastVerification?.command, projectRoot), LINE_MAX) || null;
@@ -130,8 +192,10 @@ export function buildEpisode(ledger, { routeState = null, projectRoot = '' } = {
130
192
  && routeState.taskInstanceId === ledger.taskInstanceId;
131
193
  const legacyMatch = routeState && !ledger.taskInstanceId && !routeState.taskInstanceId;
132
194
  const task = oneLine(
133
- ledger.taskPrompt
134
- ?? (provenMatch || legacyMatch ? routeState?.routingContext?.lastExplicitUserPromptText : ''),
195
+ stripPromptBoilerplate(
196
+ ledger.taskPrompt
197
+ ?? (provenMatch || legacyMatch ? routeState?.routingContext?.lastExplicitUserPromptText : ''),
198
+ ),
135
199
  PROMPT_MAX,
136
200
  );
137
201
 
@@ -276,23 +340,54 @@ export async function backfillEpisodes(projectRoot, {
276
340
  idleMs = 10 * 60 * 1000,
277
341
  limit = 50,
278
342
  now = Date.now(),
343
+ // Start-trigger mode (3.5.4): a ledger that is not idle belongs to an open session.
344
+ // Its finished tasks (the spool) are recorded; its live task never is.
345
+ spoolsOnly = false,
279
346
  } = {}) {
280
347
  const summary = { scanned: 0, recorded: 0, skipped: 0, failed: 0 };
281
348
  try {
282
349
  if (config?.memoryV2?.enabled === false || config?.learning?.episodes?.autoWrite === false) {
283
350
  return { ...summary, reason: 'disabled' };
284
351
  }
352
+ // A deleted project must stay deleted: every store write below uses recursive mkdir, so
353
+ // refuse up front and re-check between ledgers (a background run outlives its project).
354
+ const storageDir = path.join(projectRoot, '.ukit', 'storage');
355
+ const storageExists = async () => { try { await fs.stat(storageDir); return true; } catch { return false; } };
356
+ if (!(await storageExists())) return { ...summary, reason: 'project gone' };
285
357
  const dir = path.join(projectRoot, LEDGER_DIR_REL);
286
- const names = await listLedgerFiles(dir, limit);
358
+ // Start mode scans deeper than `limit` (already-recorded ledgers are free) and bounds the
359
+ // WRITE work instead, so ledgers beyond the newest `limit` are reached on later runs.
360
+ const names = await listLedgerFiles(dir, spoolsOnly ? Math.max(limit, 400) : limit);
361
+ let writeBudget = limit;
287
362
  const existingKeys = recordedEpisodeKeys(await loadRecords(projectRoot, { homeDir }));
288
363
  const projectId = (await detectProjectContext(projectRoot, { homeDir })).project.name;
289
364
  for (const name of names) {
365
+ if (spoolsOnly && writeBudget <= 0) break;
366
+ if (summary.scanned > 0 && !(await storageExists())) { summary.reason = 'project gone'; break; }
290
367
  summary.scanned += 1;
291
368
  let stat;
292
369
  try { stat = await fs.stat(path.join(dir, name)); } catch { summary.skipped += 1; continue; }
293
- if (now - stat.mtimeMs < idleMs) { summary.skipped += 1; continue; }
370
+ const live = now - stat.mtimeMs < idleMs;
371
+ const before = summary.recorded;
372
+ try {
373
+ if (live && !spoolsOnly) { summary.skipped += 1; continue; }
294
374
  const ledger = await readJsonIfExists(path.join(dir, name));
295
375
  if (!ledger) { summary.skipped += 1; continue; }
376
+ if (live) {
377
+ let any = false;
378
+ for (const entry of await readSpool(projectRoot, name)) {
379
+ if (entry.taskInstanceId === ledger.taskInstanceId) continue;
380
+ any = true;
381
+ const res = await writeTaskEpisode(projectRoot, {
382
+ ledger: entry, ledgerKey: name, config, homeDir, projectId, existingKeys,
383
+ });
384
+ if (res.status === 'recorded') summary.recorded += 1;
385
+ else if (res.status === 'duplicate' || res.status === 'empty') summary.skipped += 1;
386
+ else summary.failed += 1;
387
+ }
388
+ if (!any) summary.skipped += 1;
389
+ continue;
390
+ }
296
391
  const res = await writeEpisode(projectRoot, {
297
392
  ledger, ledgerKey: name, config, homeDir, projectId, existingKeys,
298
393
  });
@@ -300,10 +395,14 @@ export async function backfillEpisodes(projectRoot, {
300
395
  if (res.status === 'recorded') summary.recorded += 1;
301
396
  else if (res.status === 'duplicate' || res.status === 'empty') summary.skipped += 1;
302
397
  else summary.failed += 1;
398
+ } finally {
399
+ writeBudget -= summary.recorded - before;
400
+ }
303
401
  }
304
402
  // Orphan spools: the ledger file was evicted by the dir sweep but its spool
305
403
  // survived. Same dedupe keys, same idle rule (on the spool's mtime).
306
404
  let dirNames = [];
405
+ if (summary.reason === 'project gone' || !(await storageExists())) return { ...summary, reason: 'project gone' };
307
406
  try { dirNames = await fs.readdir(dir); } catch { /* none */ }
308
407
  const present = new Set(dirNames);
309
408
  for (const spoolName of dirNames) {