refactor(kernel): rename the ./loops subpath to ./kernel

[drewstone]

What

Renames the public subpath @tangle-network/agent-runtime/loops → @tangle-network/agent-runtime/kernel, and surfaces the kernel's headline types from the root entry point.

Hard rename: no alias, no deprecation shim, no compatibility export. The old subpath is gone from the exports map.

$ node -e "await import('@tangle-network/agent-runtime/loops')"   # against the packed 0.108.1 tarball
old subpath: ERR_PACKAGE_PATH_NOT_EXPORTED

Why

The subpath outweighs the root entry on both denominators — 204 runtime value exports vs the root's 138, and 594 catalogued symbols vs the root's 413 (measured: Object.keys() on each ESM namespace from the packed tarball, and docs/api/primitive-catalog.md). What it carries is supervise, Scope, Supervisor, the executor registry, the finalizer seam, conserved budgets, and analyst wiring. That is the organism-level execution kernel. runAgentRounds is a loop; a Supervisor is not — the old name described one implementation shape, not the capability.

The cost was measurable: two separate audits this week concluded the supervisor was unused, because they read the root export and the single most important primitive in the package was invisible from the main entry point.

Changes

• tsdown.config.ts entry loops → kernel; package.json exports key ./loops → ./kernel (dist/kernel.js / dist/kernel.d.ts).
• Every internal import and in-repo consumer updated: src/, bench/src/, examples/, tests/, scripts/, tsconfig.examples.json, bench/tsconfig.json, vitest.config.ts. tests/loops/ → tests/kernel/.
• src/runtime/strategy-author.ts — the authored-strategy import allowlist regex and the strategy-author contract text now name /kernel, so generated strategy modules compile.
• Root src/index.ts now type-only re-exports the kernel's headline types (Supervisor, Scope, Executor, ExecutorRegistry, AgentSpec, Budget, Spend, Settled, SupervisedResult, SupervisorFinalizer, FinalizeContext, CoordinationEvent, AnalystRegistry, Driver, LoopResult) with a comment naming the subpath. Type-only, so dist/index.js gains no runtime weight. This is the discoverability fix and the point of the change: catalogued root symbols 398 → 413, and the primitive catalog now lists supervision on the root surface.
• scripts/check-docs-freshness.mjs — the subpath↔typedoc-entryPoint check resolves ./kernel through a curated map (./kernel → src/runtime/index.ts) instead of an exemption set, so the subpath is now actively verified rather than skipped.
• scripts/gen-primitive-catalog.mjs — relabelled; dead ownSubpathAliases guard removed.
• README, docs/canonical-api.md, docs/glossary.md, docs/MAINTAINING.md, docs/learning-flywheel.md, docs/agent-managed-compute/*, bench/HARNESS.md, CLAUDE.md, and regenerated docs/api/.

Verification (exit codes read inline)

Check	Exit	Tail
pnpm build	0	130 files, total: 6.87 MB · ✔ Build complete in 2166ms · emits dist/kernel.js + dist/kernel.d.ts, no dist/loops.*
pnpm test	0	Test Files 173 passed | 2 skipped (175) · Tests 1856 passed | 6 skipped (1862)
pnpm typecheck	0	$ tsc --noEmit && pnpm run typecheck:examples — clean
pnpm lint	0	Checked 502 files in 146ms. No fixes applied.
pnpm docs:check	0	docs freshness: OK — no drift detected in the curated docs (run after committing regenerated docs/api/)
pnpm verify:package	0	publint + attw green; "@tangle-network/agent-runtime/kernel" → node16 (from ESM): 🟢
pnpm --filter @tangle-network/agent-bench run typecheck:public	0	clean
pnpm --filter @tangle-network/agent-bench test	0	package tests passed: 62/62 TypeScript files

Baseline control: docs/api/ regenerates byte-identical on origin/main, so the whole docs/api diff here is caused by this change (the root re-export moves those type definitions onto index.md).

Consumer proof against the packed tarball (not the source tree) — every symbol discovery imports:

require.resolve: .../node_modules/@tangle-network/agent-runtime/dist/kernel.js
supervise: function | createExecutor: function | pollFor: function | FileSpawnJournal: function | exportCount: 204
old subpath: ERR_PACKAGE_PATH_NOT_EXPORTED
tsc --noEmit  →  exit 0

Downstream

Breaking for every consumer of ./loops; they move to ./kernel after this publishes.

• drewstone/discovery — updated on branch refactor/loops-to-kernel (12 files: packages/discovery-pi, packages/discovery-agent, the dependency-direction guard strings, docs/13-pi-agent.md). It cannot merge until a runtime release carries ./kernel; its installed 0.108.0 does not, and its typecheck reports exactly 8 TS2307: Cannot find module '@tangle-network/agent-runtime/kernel' plus 6 knock-on inference errors and nothing else.
• Other repos still on ./loops, by file count: agent-lab 241, supervisor-lab 145, drewstone/loops 15, agent-dev-container 12, bazaar 8, blueprint-agent 7, physim 7, gtm-agent 3, legal-agent 3, tax-agent 3, tangle-website 2 (blog prose), agent-app 1 (doc), agent-knowledge 1 (doc), creative-agent 1, insurance-agent 1, redteam 1.

Not fixed here

bench/tsconfig.json full-project tsc reports 20 pre-existing errors (CampaignAggregates.totalCostUsd, readonly-array assignment in swe-arena/). Identical 20 on origin/main — substrate drift, unrelated to this rename, and not run by any package script (typecheck:public is the gated one and is green).

[tangletools]

✅ Auto-approved drewstone PR — 6a056c8b

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-07-28T18:28:11Z}

[tangletools]

🟡 Value Audit — sound-with-nits

Verdict	sound-with-nits
Concerns	1 (1 weak-concern)
Heuristic	0.0s
Duplication	0.0s
Interrogation	87.2s (2 bridge agents)
Total	87.2s

💰 Value — sound

Renames the public subpath ./loops → ./kernel and surfaces the kernel's headline types at the root entry; a clean, in-grain discoverability fix with no materially better alternative.

• What it does: Mechanical hard rename of the package's largest public subpath: the tsdown entry key (tsdown.config.ts:10), the package.json exports key (package.json:42), every internal/importer path (151 files, ~145 are one-line import swaps across src/, bench/, examples/, tests/, scripts/), the tests/loops/ → tests/kernel/ directory, and the strategy-author allowlist regex + contract text (src/runtime/strategy
• Goals it achieves: (1) Fix a naming defect: the subpath carried supervise/Scope/Supervisor/executor-registry/conserved-budgets — an organism-level execution kernel, not 'loops' (runAgentRounds is a loop; a Supervisor is not). The old name described one implementation shape, not the capability. (2) Fix a discoverability defect the PR body measures directly: the subpath outweighs root (594 vs 413 catalogued symbols; 2
• Assessment: Good change, built in the codebase's grain. The rename is complete (grep confirms zero residual /loops references in code, docs, or configs) and internally consistent (tsdown entry ↔ package.json exports ↔ strategy-author regex/contract all agree on /kernel). The root type re-exports are type-only by design — values still come from /kernel — so it aids discoverability without collapsing the subpat
• Better / existing approach: none — this is the right approach. Searched for an existing equivalent (git grep for agent-runtime/loops residuals, checked src/runtime/index.ts as the kernel source, checked docs/api/primitive-catalog.md for prior naming) — the kernel is this surface; there is nothing to reuse or extend. A deprecation alias would only defer cleanup and add a maintenance seam; for a pre-1.0 package the hard rename
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 2
• Bridge warning: opencode/kimi-for-coding/k2p7: bridge stream ended without value-audit content

🎯 Usefulness — sound-with-nits

A clean, well-motivated rename that aligns the public subpath with the codebase's own 'kernel' vocabulary and surfaces headline types at root; all 121 in-repo consumers are updated, but 13 files in the concurrent agent-dev-container PR still import the old ./loops path and will break on next runtime

• Integration: Fully wired and heavily reachable. tsdown entry renamed (tsdown.config.ts:10), exports map updated with ./loops gone and ./kernel present (package.json:42-46), the strategy-author allowlist regex now matches /kernel (src/runtime/strategy-author.ts:117) and its own import updated (line 72), and src/index.ts:202-218 type-only re-exports 15 kernel headline types (Supervisor, Scope, Executor, etc.) —
• Fit with existing patterns: Excellent — the rename matches the codebase's own terminology. src/runtime/run-loop.ts:3 calls runAgentRounds 'the topology-agnostic kernel'; src/runtime/types.ts:5-7 says 'The loop kernel orchestrates'; src/runtime/util.ts:3 names itself 'Internal loop-kernel utilities'. The old name ('loops') described one implementation shape; 'kernel' is the term the source already uses for this surface. The r
• Real-world viability: Internally robust: the rename is mechanical and exhaustive, and the hard-break semantics are explicit in the PR body ('no alias, no deprecation shim'). The realistic risk is external: agent-dev-container PR #4120 (concurrent, in-flight) imports @tangle-network/agent-runtime/loops in 13 production and test files (packages/workflow-script-runtime/src/loops.ts:30,46; products/intelligence/api/src/lib
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

🎯 Usefulness Audit

🟡 Concurrent agent-dev-container PR + skills docs still import ./loops; coordinate publish ordering [integration] ``

13 files in agent-dev-container PR #4120 (rg'd live) import @tangle-network/agent-runtime/loops — e.g. packages/workflow-script-runtime/src/loops.ts:30, products/intelligence/api/src/lib/fix-engine.ts:24, products/platform/api/src/lib/workflow-agent-run.ts:45, products/sandbox/cli/src/commands/supervisor.ts. With no compatibility shim, publishing this runtime breaks those builds. This is a deliberate hard rename (stated in the PR body) and the consumers are in-flight concurrent work, so it is ex

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260728T183227Z}

[tangletools]

✅ No Blockers — 6a056c8b

Review health 100/100 · Reviewer score 92/100 · Confidence 95/100 · 1 finding (1 low)

glm: Correctness 92 · Security 92 · Testing 92 · Architecture 92

Reviewer score is advisory once the run is complete and the verdict has no blockers.

Full multi-shot audit completed 8/8 planned shots over 171 changed files. Global verifier still owns final merge decision.

🟡 LOW Stale comment references renamed loops barrel — bench/src/sandbox-run.ts

Line 19 comment reads it is not re-exported from the loops barrel, but the import on line 17 was just changed to @tangle-network/agent-runtime/kernel. The comment now contradicts the code it sits next to and will mislead readers about where BackendType lives. Rename loops barrel -> kernel barrel. Cosmetic only; no runtime impact.

---

_{tangletools · 2026-07-28T18:46:01Z · trace}

[tangletools]

✅ Approved — 1 non-blocking finding — 6a056c8b

Full multi-shot audit completed 8/8 planned shots over 171 changed files. Global verifier still owns final merge decision.

Full immutable report for this review: trace

Summary comment for this run: full summary

---

_{tangletools · 2026-07-28T18:46:01Z · immutable trace}