Codex TypeScript MCP Grill Log

Opened 2026-09-28. Active requirements session for later Baseline support, grounded in the working local installation. This is not an implementation authorization or a release claim. Current status owns the frontier and working glossary; local runbook owns operating instructions.

Registry refresh — superseding evidence

The merged Registry research supersedes E7's old projection/overwrite analysis. Current registry/publisher/sources/hooks.ts:91–104 declares Codex config Authored; registry/pipeline.ts:760–778 preserves existing bytes. No entry-level MCP lifecycle exists. Current config has no Typegraph entries; installed runtime survives and fresh SDK replay passes. Cause of registration disappearance is unknown, not attributed to the Authored-preserving installer.

Current smoke evidence uses packages/contract/src/reports.ts:HarnessReportType; historical baseline.ts:ArtifactKind is gone. Current CLI definition is line 248, not historical 256. E1–E6 retain historical findings; current host availability is not claimed. New anchors and ten failure lenses are in the report. At this evidence refresh Q1–Q4 were unanswered. The later R1 accepted-answer entries below supersede that state; no new glossary terms were accepted.

Imported direction

• C1 — Local choice accepted: the user requested whichever of Serena or Typegraph works best with native TS7, then acknowledged the delivered setup with “ok great.” Preserve Typegraph locally; do not reopen that comparison.
• C2 — Lint coexistence: the user requires compatibility with HI TypeScript and Effect packs, not Effect-specific MCP internals. Existing formatting, lint and typecheck gates remain authoritative.
• C3 — Scope: local setup first; analyze later Baseline integration. The current request explicitly invokes brainstorm and requirements-grill, not Baseline implementation.
• C4 — Existing accepted model: the Registry Baseline glossary fixes Pack as the only selection unit; detection proposes, never selects. This is accepted design, not proof that all corresponding code exists.

These are imported constraints, not answers to Q1–Q9. No authority to auto-pin recommendations was given.

Brainstorm boundary and agent trace

Operator: a Codex agent working in one checkout and asking semantic questions about TypeScript source. Historical tested system: project Codex configuration, local stdio Typegraph runtime, existing compiler projects and on-disk files. The Registry refresh above describes current registration absence. The later installer/projection contract is unresolved. No API service, database, semantic editing or new lint engine is required by the observed local flow.

Live reasoning view: historically verified local wiring

Codex session in intended checkout
  load .codex/config.toml
  start typegraph_<workspace> over stdio
    /bin/sh -c
      git rev-parse --show-toplevel -> TYPEGRAPH_PROJECT_ROOT
      node ~/.local/share/hi-tools/typegraph-mcp/0.9.56/.../server.cjs
      TYPEGRAPH_TSCONFIG -> existing compiler project
  discover available tools
  agent requests a semantic tool -> host approval decision
    allowed call -> lazy native TS7 compiler API + source watcher
      settle observed source changes -> semantic answer

Codex edit -> existing HI formatter/lint hook -> on-disk sources
                                                 -> source watcher

This show-me view derives from historical E1–E6 below; current registrations are absent. Both paths meet at disk; the MCP adds no mandatory on-edit gate. The enabled semantic path uses the compiler API, even though the original request called it “LSP MCP.”

Evidence-grounded findings

E1 — Explicit checkout and compiler-project binding make coverage work

Anchors: .codex/config.toml:mcp_servers.typegraph_*; root tsconfig.json:files; installed Typegraph dist/config.js:inferProjectRoot; API client's getProject(tsconfig).

The launch command exports the result of git rev-parse --show-toplevel as TYPEGRAPH_PROJECT_ROOT, then executes $HOME/.local/share/hi-tools/typegraph-mcp/0.9.56/node_modules/typegraph-mcp/dist/server.cjs. Without explicit root binding, the externally installed package can become the inferred project root. No primary checkout path is hard-coded. Simultaneous/divergent worktrees remain untested.

Each entry sets TYPEGRAPH_TSCONFIG to one existing config: apps api, backoffice, cli, web, wiki; packages auth, contract, db, env, scaffold, ui. Root files: [] yielded zero semantic files. The CLI config covered 333 sources, including imported contract source; an unrelated web source correctly failed. One server is one compiler project, not an automatic monorepo router.

Candidate: derive explicit project bindings from recipient evidence. Tradeoff: overlapping programs, solution roots and exclusions need Q5 decisions; do not equate a package folder with an accepted Software Scope or compiler program.

E2 — An isolated exact dependency graph supplied native TS7

Anchors: local runtime package.json/package-lock.json; project package.json/bun.lock; native process probe.

The verified tuple is Typegraph 0.9.56, TypeScript API 7.0.2, private @effect/tsgo 0.36.5, MCP SDK 1.30.1, installed with npm ci. typescript/unstable/async resolves from that installation. Observed child: @effect/tsgo-darwin-arm64/artifacts/typescript/7.0.2/tsc --api --async --cwd <HI root>, reporting 7.0.2+effect-tsgo.0.36.5. Runtime lock SHA-256: 3bcfab52d4ed1f320469cfe589e0e41392e655b17f45b7a7d676aebdf751d569.

Project @effect/tsgo 0.39.0, TypeScript 6 compatibility API, native TS7 alias, root manifest/lock, lint selection and hooks were unchanged by installation. A top-level npm version pin alone does not pin transitive dependencies.

Candidate: reproduce an exact tested runtime independently of the project compiler/lint tuple. Tradeoff: Q2 installation ownership and Q4 target compatibility; bundled API/binary consistency alone does not establish compatibility with every recipient project.

E3 — The useful local surface is five compiler-API reads

Anchor: .codex/config.toml:enabled_tools, startup_timeout_sec, tool_timeout_sec.

Enabled: ts_find_symbol, ts_definition, ts_references, ts_type_info, ts_module_exports; startup timeout 20 seconds, tool timeout 60 seconds. LSP hover, graph, mutation and separate Effect diagnostics tools are excluded.

Serena pinned main 7a2968335f2198b966864de1ce3655c8e485a653 worked with its default TS5.9.3/TLS5.1.3 backend. Native TS7 initialization failed because that adapter expects tsserver.js. An earlier GUI error came from the isolated test configuration and was corrected; it is not selection evidence.

Candidate: preserve the proven read surface initially. Tradeoff: adding any other capability needs separate semantics, freshness, approval and hook evidence; more languages/harnesses are outside this active scope.

E4 — Source freshness works within a bounded contract

Anchors: Typegraph server getSemantic; source watcher; LSP syncFile; dependency-edit probes.

The compiler API client and watcher start lazily and settle observed source changes before answering. Changing an imported function return from string to number updated the consumer API type; source addition was reflected. LSP hover instead retained string after two seconds, until the changed dependency was opened. This justified excluding hover.

The watcher skips node_modules and build output. Config/package JSON, installed dependencies, branch changes and watcher loss are not covered by the successful edit probe. Watcher setup failure can be swallowed; a runtime watcher error stops watching. No robust health guarantee was established. References can label a declaration isDefinition: false, so raw counts are not exact impact counts.

Candidate: expose bounded freshness and a restart/reverification contract. Tradeoff: Q8 must decide observable failure/recovery behavior rather than treating any returned answer as fresh.

E5 — Semantic reads and lint feedback are separate responsibilities

Anchors: existing HI TypeScript/Effect pack contracts; project edit hooks; runbook.

In the inspected published snapshot 2026.09.24-84dd3d24, the TypeScript Pack supplies quality-types, edit-hook integration and fifteen vendored Anti-Slop Oxlint rules; it does not select a compiler/server. The Effect Pack supplies its barrel-import rule and @effect/tsgo/oxlint-presets, with the published tuple @effect/tsgo 0.39.0, oxlint-tsgolint 7.0.2001, oxlint 1.80.0, oxfmt 0.66.0, ultracite 7.10.7, patched through effect-tsgo patch --no-typescript --oxlint.

HI edits reach existing format/lint hooks and disk; Typegraph observes disk on demand. MCP output is not equivalent to selected Pack lint findings. Issue #231 hook repair remains separate from this semantic bridge. Enabling MCP mutations would require separate hook and ownership proof.

Candidate: preserve existing quality authorities. Tradeoff: Q1 determines which Pack owns optional semantic capability without silently changing the existing TypeScript Pack contract.

E6 — Real host execution needs approval as well as configuration

Anchors: exact-config SDK probes; real Codex reviewed tool events; current configuration has no approval overrides.

Meaningful type queries passed all eleven compiler projects through the exact configured shell command. Real Codex calls with --approve-for-me through automatic approval review resolved commandRegistry from apps/cli/src/index.ts to apps/cli/src/cli/command-registry.ts, line 256, column 14, and returned ArtifactKind in packages/contract/src/baseline.ts as "archive" | "manifest".

An initial Codex probe with --sandbox read-only and approval_policy=never discovered the tools but denied both calls as requiring approval. The successful --approve-for-me probe could not also use --sandbox read-only because the CLI disallows that combination. These probes do not establish desktop default-policy behavior or failure under every approval-never host configuration. Upstream tools lack annotations. No persistent/global approval policy was changed. Codex schema exposes per-server/per-tool modes, but schema presence does not prove the intended host behavior. Existing chat tools did not hot-load; a new session loaded configuration.

Ordinary SDK shutdown left no tested native children. SIGKILL, crashes, hanging queries, app shutdown and concurrent recovery were not tested. Existing hi check failures concerned CLI version, lint selection and commit-manager state; semantic success is not a repository-wide gate pass.

Candidate: distinguish installed, registered, available and verified. Tradeoff: Q3 must specify allowed unattended operation and test it under the actual host policy.

E7 — Historical projection finding, superseded by Registry refresh

Anchors:

• apps/cli/src/data/scripts/harness-projection/adapters/codex.mjs:108,130: no tool-configuration actions; unsupported capability.
• packages/scaffold/src/context-plan.ts:82: tool identity, not executable MCP payload.
• apps/cli/src/features/context-planning/compiler.ts:395: derives tools from base plus skill requiresTools; this is not authority to revive the retired persisted Context Plan.
• apps/cli/src/data/scripts/sync-subagents.mjs:buildCodexAgentConfig (1085), writeAdapterConfig (2146), legacy materializer (2314): emits agents/features/hooks and replaces the full TOML. The merge-toml label at 2288 does not implement a merge. Local MCP entries can disappear during regeneration.
• apps/cli/src/features/scaffold-state/reconcile.ts:UserModifiedScaffoldEntryConflict (653) is a separate reconciliation seam; it does not prove direct sync preservation.
• apps/cli/src/integrations/tool-management.ts:354,603 and apps/cli/src/features/tool-ensure/application.ts:77: global installs and latest refresh, not an exact isolated runtime graph.
• packages/scaffold/src/catalog/required-tool-contract.ts:8: package/prerequisite/minimum-version fields, not that exact graph.

Historical candidate (module anchors superseded above): CLI owns local provisioning, launch resolution and generated configuration; packaged assets belong to CLI data, stable shared contracts to scaffold. No remote API runtime is justified by this local stdio flow. Tradeoff: Q1/Q2/Q6/Q7 must settle selection, ownership and lifecycle before a contract can be designed.

Evidence retention

The substantive findings above are retained here. Historical raw supplements: /tmp/hi-ts7-eval/config-verification.json, codex-runtime-reviewed-events.jsonl, typegraph/RESULTS.md, serena/RESULTS.md; earlier brainstorm under /var/folders/y8/fw7tz9gn7yx645tf162zwlnr0000gp/T/codex-lsp-brainstorm-esr0zbva/BRAINSTORM.md. These temporary paths are not required to understand the decisions. Runtime/source line anchors describe the 2026-09-28 snapshot and can move.

R1 — Accepted decisions

User response: “q1 typescript with typegraph mcp lsp; q2 ok; q3 agree; q4 agree.” Each answer is pinned below. This accepts requirements, not implementation readiness or excluded LSP hover capabilities.

Q1 — Pack ownership

Prerequisites: none.

Question: Which Pack should provide Codex semantic tools: the existing TypeScript Pack, or a separate optional Pack?

Historical recommendation, superseded by accepted Q1: separate optional Pack initially. The existing TypeScript Pack does not select a compiler; a separate Pack makes the added native runtime explicit while preserving that contract.

Evidence anchor: E5; accepted Registry Baseline Pack-only axiom. Observed constraint: selection belongs to Packs, not a new independent selector. Code consequence: determines registry composition and selection ownership. State: answered.

Accepted answer:

• The existing TypeScript Pack supplies Typegraph MCP for supported TS7/Codex targets. This supersedes the earlier separate-optional-Pack recommendation, which was never accepted. Pack selection carries the capability; activation, compiler-project coverage and platform support remain Q5–Q7 decisions. “LSP” does not expand the five compiler-API reads or approve stale hover.

Q2 — Runtime location and identity

Prerequisites: none.

Question: Where should HI install Typegraph: a versioned machine-level runtime with an exact dependency lock, or project devDependencies?

Recommendation: separate versioned runtime, tested with its lock tied to the selected Baseline. This preserves project compiler/lint dependencies.

Evidence anchor: E2/E7. Observed constraint: current tool-ensure refresh-latest/global installation does not reproduce the verified graph; arbitrary Registry postInstall is not a supported shortcut. See refreshed report C. Code consequence: CLI owns provisioning and launch-path resolution. State: answered.

Accepted answer:

• Use a versioned isolated machine-level runtime with an exact dependency lock tied to the selected Baseline. Preserve project compiler and lint dependencies. CLI provisioning and launch-path resolution must reproduce that graph; platform/offline/repair/removal remain Q7.

Q3 — Unattended semantic reads

Prerequisites: none.

Question: Must the five semantic reads support unattended Codex sessions, including approval_policy=never where host policy permits it, or may they require ordinary approval each time?

Recommendation: unattended support limited to the five explicitly enabled read tools, with global approvals unchanged and host restrictions respected.

Evidence anchor: E3/E6. Observed constraint: approval-never failed while reviewed calls succeeded; read-like names alone grant no permission. Code consequence: requires an explicit, tested per-tool permission contract, not a global bypass. State: answered.

Accepted answer:

• Support unattended use of the five enabled read tools where Codex host policy permits it, including approval-never only when allowed by that host. Do not bypass global policy. This is a required contract still needing actual host proof, not a claim the current configuration implements it.

Q4 — Unsupported compiler behavior

Prerequisites: none.

Question: If the target compiler cannot be matched to a tested native TS7 runtime, should HI report semantic tools unavailable, or allow an identified unverified fallback?

Recommendation: unavailable with a clear reason; existing lint/typecheck continues and the project compiler never changes silently.

Evidence anchor: E2/E6. Observed constraint: the tested bundled runtime does not prove every target compiler compatible. Code consequence: target-compiler compatibility becomes an activation condition; no reliance on the internal API/binary guard alone. Compiler families beyond requested TS7 scope are not reopened. State: answered.

Accepted answer:

• Report semantic tools unavailable with a clear reason when the target compiler is incompatible or unverified. Never silently fall back or replace the project compiler. Existing lint/typecheck remains usable; compatibility acceptance proof remains Q9.

Accepted target view after R1

selected TypeScript Pack
  Baseline-bound isolated runtime (exact dependency lock)
    Codex: five native TS7 compiler-API read tools
existing lint/typecheck authority remains alongside

Q1 changes Pack ownership, not the meaning of Pack. This widens the capability to all installations selecting the TypeScript Pack; Q4 reports incompatible/unverified targets semantic-unavailable while existing lint/typecheck stays usable. It neither converts recipient compilers to TS7 nor introduces another opt-in toggle. Existing ten-lens findings still apply; Q5–Q7 address mapping, ownership and runtime lifecycle. Coverage, config ownership and runtime lifecycle remain R2 candidates. Exact locking and Q4 do not establish arbitrary TS7-version/platform support. “LSP” remains an umbrella label; stale hover stays excluded. Compiler Project, Tool Runtime and Semantic Session remain proposed labels. Current local registration absence is unchanged.

Initial deferred design tree and validation (historical)

Q5 project mapping/names depends on Q1. Q6 configuration ownership, collisions, update and deselection depends on Q1/Q2. Q7 platform, offline operation, repair and removal depends on Q2/Q4. Q8 lifecycle, freshness, restart and observable health depends on Q4/Q5/Q7. Q9 release acceptance, resource limits and version support depends on Q3/Q6/Q8. These IDs are reserved, not asked or answered yet.

Scope-derived future branches: other languages/harnesses, semantic editing, graph/Effect diagnostics, repaired LSP hover, shared daemon/router. These are preserved outside active scope, not invented user decisions.

Non-design validation remains: clean-machine reproduction; actual host approval contract; exact target compatibility; isolated divergent worktrees; config/dependency/branch changes; watcher/process failure; update preservation; startup, memory and tool-surface cost. No Baseline readiness claim follows from the local probes.

R2 — proposed questions and recorded answers

Q5–Q7 were presented together after Q1–Q4 were accepted. Recommendations remain candidates; no auto-pinning or implementation authority follows.

Q5 — compiler-project coverage

Prerequisite Q1. State: answered.

Question: Should HI derive Typegraph coverage from source-bearing TypeScript configs across the repository, with an explicit mapping only when discovery is ambiguous? Historical recommendation (wiki inclusion superseded below): yes. One server per resolved compiler project, bound to the current worktree. Include TypeScript workspace projects such as the wiki even when they are absent from lint scopes or Recorded Shape. Skip empty solution-only configs, follow their project references to source-bearing projects, preserve actual compiler options/exclusions/import closure, and report unresolved mappings rather than inventing a root-wide config. Stable server names derive from project/config identity; exact naming syntax belongs implementation planning. Why: existing root gives zero coverage; the wiki previously worked. registry/shape.ts:42–83 computes only a Boolean TypeScript signal; shape.ts:105–110 expressly excludes wiki workspace and records wikiRoot separately. registry/model.ts:258 has no compiler-project inventory; materialize.ts:61 expansions aren't that inventory. Neither selected lint scopes nor Recorded Shape is sufficient. Alternative: explicitly map every compiler project, accepting ongoing manual setup. Code consequence: separate compiler-project discovery/mapping input consumed by MCP contribution; no changes to lint ownership or tsconfig semantics.

Accepted answer:

• Automatic source-bearing tsconfig mapping bound to the current worktree; explicit mapping when discovery is ambiguous; preserve compiler options, exclusions and import semantics. Exclude wiki compiler projects from automatic MCP discovery/registration: no wiki server contribution. Use the configured/detected wiki boundary, not a hard-coded HI path. Preserve ordinary imported closure of included projects; do not rewrite source or compiler options. Historical wiki success is evidence only, not desired coverage.
• User answered only Q5: “yes auto mapping but fuck off wiki porocdio”. This explicitly rejects the candidate wiki inclusion. Q6/Q7 remain unanswered.
• Code consequence: compiler-project discovery/mapping must exclude wiki and avoid changing lint ownership or compiler semantics. Q8 remains blocked on Q7; no new question is unblocked.

Q6 — ownership inside Codex configuration

Prerequisites Q1 Q2. State: answered (ownership scope only).

Question: Should HI reconcile only MCP entries whose ownership it can prove, preserving the rest of Authored Codex configuration and reporting collisions or user edits? Historical recommendation, narrowed by accepted Q6: yes. Add missing owned entries, update unchanged owned entries, remove unchanged owned entries when deselected; preserve unrelated TOML and user-modified/colliding entries, reporting what requires resolution. No full-file replacement or automatic adoption based only on a name prefix, even with --yes. Why: registry/publisher/sources/hooks.ts:91–104 and pipeline.ts:760–778,860–876 preserve Authored config; JSON/YAML merging does not provide entry-level TOML reconciliation. Current absent registration makes repair an explicit need. Code consequence: bounded entry ownership/update/removal/repair contract within Authored config; metadata representation remains planning, not a second scaffold authority.

Accepted answer:

• User: “no it only manages the code to enable typegraph mcp for this impl we are making”. HI manages only this implementation's Typegraph MCP wiring/contribution. No generic MCP-entry ownership/reconciliation framework or management of arbitrary MCP servers. Other Codex configuration remains user-owned.
• Code consequence: bound the contribution to this Typegraph implementation. This does not authorize overwriting user-modified Typegraph entries or accept detailed conflict/removal behavior.
• Q6a reserved, unresolved (prerequisite Q6): behavior for existing user-edited/colliding Typegraph wiring and removal. It enters the next frontier after R2 concludes; Q9 final readiness must account for it. Q7 alone remains unanswered in R2.

Q7 — original compound wording (superseded)

Prerequisites Q2 Q4. State: unanswered.

Question: Should HI reuse immutable, verified runtime installations across repositories, repair the same pinned dependency graph, and retain cached versions when the Pack is removed? Recommendation: yes. CLI provisions/verifies the required tuple during Pack application before claiming readiness; cache identity distinguishes dependency lock and OS/architecture. Reuse a valid installed tuple offline. If absent or invalid offline, report unavailable; never fetch latest or silently substitute. Online repair recreates the same lock; update uses a new tuple without mutating active older tuples. Pack removal does not automatically delete a runtime another repository or session may use. No daemon, reference counter or new pruning command is implied. Platform boundary: only a declared, end-to-end validated OS/architecture matrix can be supported; npm optional-package availability is not proof. Exact release support matrix and minimum supported host versions stay explicitly unresolved under Q9 acceptance, which already depends transitively on Q7. Do not infer macOS-only or promise Windows/Linux support from this question. Why: installed Typegraph0.9.56 requires Node>=22.18; local Darwin arm64/Node22.22.0 is proven. Private Effect tsgo0.36.5 packages exist for Darwin arm64/x64, Linux arm/arm64/x64, Windows arm64/x64, but they have not all been tested. Existing tool-management.ts:165,393 uses global installs/latest refresh with PATH/version checks, no isolated exact-cache lifecycle. registry/client.ts:8 handles catalog/item offline cache, which doesn't establish runtime offline install. Installed runtime package.json/package-lock.json are platform evidence. Code consequence: CLI-owned exact provisioning, health/repair and retention; partial failures remain visible and Q8/Q9 own failure observability and final acceptance proofs.

Q8 depends on Q4/Q5/Q7; Q9 depends on Q3/Q6/Q8. Q9 retains the exact OS/architecture/Node/compiler support matrix, host-policy proof and resource acceptance. No platform promise is inferred from package availability.

Round persistence validation

Q1–Q6 answered (Q6 ownership scope only); R2 frontier Q7 unanswered. Q6a conflict/removal policy unresolved for the next frontier. No new glossary terms, runtime/config edits, release or implementation authorization. bun run --cwd apps/wiki check:content and scoped git diff --check passed after this persistence. Existing public wiki contract is unchanged; the prior docs-wave suite passed 16 tests. HI-DOCS-001 pass (routed decision authority and docs index aligned); HI-WIKI-001 pass (existing routes retained); HI-WIKI-003 pass (frontmatter, links, wiki log and content check); HI-REPO-003/HI-UI-001 not applicable (no URL/runtime UI changes).

Q7 clarification and accepted answer

Prerequisites: Q2, Q4. State: answered.

The user requested $wait-what because the compound question was unclear. That was not an answer. The simplified question was: “When one repository stops using Typegraph, should HI leave Typegraph installed on your computer?”

Accepted answer: yes (“yes ofc”). Leave the machine installation in place; other repositories may still need it. This settles retention, not every proposal in the original compound question. Exact dependency locking follows Q2. Offline installation, automatic repair mechanisms and a cache manager were not accepted. Failure recovery remains Q8; declared platform/Node/compiler support remains Q9. Repository wiring remains governed by Q6/Q6a.

R3 — Typegraph settings and recovery

Q6a — manual edits to HI-generated Typegraph settings

Prerequisite: Q6. State: answered.

Question: If you manually edit the Typegraph configuration that HI generated, should the next HI update restore its expected settings or leave your edits?

Recommendation: HI restores its own Typegraph settings; other Codex settings stay untouched. Alternative: keep the edits and report the difference.

Evidence: registry/pipeline.ts:760–778,860–876 preserves Authored configuration but provides no Typegraph-entry lifecycle. Q6 limits management to this implementation. Code consequence: distinguish generated Typegraph settings from unrelated content and apply the chosen edit policy during update/repair/deselection. Do not adopt unowned entries merely because their names match. This is Typegraph-specific, not a general MCP manager.

Q8 — freshness and automatic recovery

Prerequisites: Q4, Q5, Q7. State: answered.

Question: Should Typegraph restart automatically when compiler settings, dependencies or branches change, or when its process fails?

Recommendation: automatic recovery; if a fresh answer still cannot be obtained, report failure rather than return an old result. Alternative: require a manual restart.

Evidence: E4 and the Registry research distinguish successful ordinary source refresh from unproven config/dependency/branch/watcher/process recovery. Code consequence: explicit invalidation, restart and failure behavior for this Typegraph integration; no shared daemon is implied. Acceptance cannot substitute for actual recovery tests.

R2 is complete. R3 frontier: Q6a, Q8. Q9 remains dependent on Q3, Q6, Q6a and Q8. No implementation or final shared-understanding approval is implied.

Accepted Q6a

Accepted answer: HI restores its Typegraph settings. The user selected the recommended option. An HI update restores its generated Typegraph settings after manual edits; other Codex configuration stays untouched. This does not authorize adopting or overwriting unowned entries. Q8 remains unanswered.

Accepted Q8

Accepted answer: Restart automatically; report failed recovery. The user selected the recommended option. Compiler-setting, dependency or branch changes and process failure require automatic recovery. If a fresh answer cannot be obtained, report failure rather than knowingly serve a stale result. Ordinary source watching remains the normal path; recovery implementation and proof are still required.

R4 — Q9 support and release acceptance

Prerequisites: Q3, Q6, Q6a, Q8. State: unanswered.

Question: Which operating systems should the first version support?

Recommendation: macOS, Linux and Windows on arm64/x64, with tests required before claiming support for each. Alternatives: macOS and Linux first, or macOS only first.

Evidence: installed Typegraph requires Node >=22.18; private tsgo packages exist for these targets, but actual runtime proof is macOS arm64 only. Package availability is not end-to-end support. Code consequence: a portable launcher and install path plus validation on each chosen target. Other architectures are outside this proposed first support matrix. Exact native compiler/dependency tuple remains tied to Baseline and verified under Q2/Q4.

Release evidence must exercise the accepted requirements: clean install, automatic project mapping with wiki excluded, preserving actual tsconfig semantics, Typegraph-only settings updates and unrelated-config preservation, host-permitted unattended five-tool calls, source/config/dependency/branch freshness and failed recovery, independent worktrees, and retention when one repo stops using Typegraph. Measure startup, memory and tool-surface cost; no unasked numeric performance promise or new feature follows. No support claim precedes passing its relevant tests.

Round persistence verification

Q1–Q8 including Q6a have recorded answers; Q9 is unanswered. bun run --cwd apps/wiki check:content passed, all 16 wiki tests passed, and scoped git diff --check passed. HI-DOCS-001 pass: decision authority stays in the routed grill with the docs index linked. HI-WIKI-001 pass: existing routes retained. HI-WIKI-003 pass: frontmatter, links, wiki log and content/public-contract checks. HI-REPO-003 and HI-UI-001 not applicable: no endpoint or UI changes. No product/configuration/runtime edits, release or implementation approval.

R5 reset — grill restarted 2026-09-28

User instruction: "restart grilling. clear out the questions. re-ask and re-brainstorm everything." This entry supersedes the answered state of Q1–Q9 and Q6a. Their recorded answers above remain history only; none is an accepted requirement any more. Ids Q1–Q9 are retired and are not reused. Fresh questions start at Q10. Imported constraints C1–C4 stay as premises until the user says otherwise; they are listed again below so they can be vetoed. No configuration, runtime, dependency or product change accompanies this reset.

Live state re-checked at reset: isolated runtime present at ~/.local/share/hi-tools/typegraph-mcp/0.9.56 (209 MB, Typegraph 0.9.56, @effect/tsgo 0.36.5 darwin-arm64); host Node 22.22.0; .codex/config.toml and ~/.codex/config.toml contain zero Typegraph entries; twelve tsconfig.json files exist (root plus eleven workspaces); 1,299 dirty Git statuses preserved untouched.

Brainstorm v2 — from the agent's seat

1. Boundary

• System: one Codex session in one checkout of a TypeScript repository that has the HI Baseline installed. Parts: Codex host (MCP registration, tool discovery, approval), one or more Typegraph stdio processes, the isolated Typegraph runtime on the machine, the repository's tsconfig.json files and sources, the HI CLI (scaffold/update/check), the Registry (Packs, Authored Codex config), existing HI format/lint hooks.
• Operator: the Codex agent asking semantic questions. Secondary: the human running hi commands.
• Premises kept (vetoable): C1 Typegraph over Serena for native TS7; C2 existing lint/format/typecheck stay authoritative; C3 local proof first, Baseline later; C4 Pack is the only selection unit, detection proposes.
• Evidence: E1–E6 historical probes; fresh SDK replay in the Registry research; live state above.
• Unknowns marked explicitly: cause of registration disappearance; per-session startup and memory cost of many servers; whether Typegraph's bundled TS 7.0.2 loads every recipient tsconfig (TS7 removed or changed some legacy options; not probed); actual Codex per-tool approval behavior on desktop defaults; behaviour on any target other than macOS arm64; config/dependency/branch freshness; crash recovery.

2. Agent trace

3. Smallest candidate changes

Each candidate: evidence, consequence, unresolved tradeoff. All remain candidates until accepted.

• K1 Pinned machine runtime provisioned by CLI. Evidence: the exact lock is what made TS7 work; global/latest tool-ensure cannot reproduce it. Consequence: CLI owns install path, lock, and health probe. Tradeoff: 209 MB per pinned version per machine; several Baselines may pin different versions.
• K2 HI writes Typegraph entries into Codex config and restores them on update. Evidence: entries vanished with unknown cause; Registry preserves Authored bytes only. Consequence: Typegraph-scoped entry ownership inside an otherwise user-owned file. Tradeoff: needs a stable way to tell generated entries from user entries.
• K3 Derive compiler projects from source-bearing tsconfigs. Evidence: root config has no files; eleven workspace configs cover source; wiki config exists. Consequence: mapping step separate from lint Software Scopes. Tradeoff: which configs to exclude by default; ambiguity reporting.
• K4 Server topology. Evidence: per-project servers are proven; a router is not. Consequence: per-project keeps HI free of MCP code but costs the agent a server choice and the host N processes; a single HI-owned router server that picks the tsconfig from the file path is agent-intuitive but is new software HI must maintain, and it is also the only place automatic recovery (K7) could live. Tradeoff: proof versus ergonomics.
• K5 Activation probe instead of version matching. Evidence: Typegraph analyses with its own bundled TS 7.0.2 regardless of the project's TypeScript; the real failure mode is a tsconfig or program that the bundled compiler rejects. Consequence: activation gated by a real load probe per compiler project, with a clear reason on failure. Tradeoff: probe cost at scaffold/update time.
• K6 Per-tool unattended approval for the five reads. Evidence: approval-never refused reads; Codex schema shows per-server/per-tool modes but behaviour is unproven. Consequence: generated config states the approval intent; global policy untouched. Tradeoff: must be proven on real desktop defaults, not just the CLI.
• K7 Recovery contract. Evidence: only ordinary source edits refresh; nothing restarts on config/dependency/branch change. Consequence: either document "new session after such changes" or build a wrapper. Tradeoff: honesty now versus code later.
• K8 hi check reports installed / registered / probe passes separately. Evidence: check says current while tools are absent. Consequence: one cheap witness the agent and human can both read. Tradeoff: adds a live subprocess probe to a command that is currently static.
• K9 Support matrix by proof. Evidence: macOS arm64 is the only end-to-end proof; Linux x64 is what CI can prove; package metadata covers more. Consequence: support claims follow tests. Tradeoff: narrower first claim.
• K10 Deselection. Evidence: retention preference earlier; runtime is machine-level. Consequence: remove this repo's entries, keep the runtime. Tradeoff: no pruning story.

4. Fresh questions — Q10–Q20 (all unanswered)

Recommendations are candidates. Only supplied answers count. One decision per question.

Q10 — who gets it

Prerequisites: none. Question: Does every project that selects the TypeScript Pack get Typegraph, or is it a separate opt-in Pack? Recommendation: TypeScript Pack carries it, provided Q13 keeps session cost bounded. Alternative: separate Pack. Evidence: K1/K4; C4. Code consequence: Pack composition and Registry dependency closure. State: unanswered.

Q11 — where the runtime lives

Prerequisites: none. Question: Pinned machine-level install owned by the CLI, project devDependency, or fetched on demand? Recommendation: pinned machine-level install with the exact lock, as proven. Evidence: K1/E2. Code consequence: CLI provisioning and launch-path resolution. State: unanswered.

Q12 — which compiler projects

Prerequisites: none. Question: Auto-discover source-bearing tsconfigs with an explicit override for ambiguity, or an explicit list only? Recommendation: auto-discover, exclude wiki and solution-only configs by default, report ambiguity. Evidence: K3/E1. Code consequence: mapping input separate from lint scopes. State: unanswered.

Q13 — server topology

Prerequisites: none. Question: One Typegraph server per compiler project (proven, eleven here) or one HI-owned router server that picks the project from the file path (new code)? Recommendation: per-project for the first version, measured; router as a later extension unless you want automatic recovery (Q17) now. Evidence: K4/K7. Code consequence: whether HI ships an MCP process at all. State: unanswered.

Q14 — Codex config ownership

Prerequisites: none. Question: Should HI write its Typegraph entries into .codex/config.toml and restore them on every update, leaving everything else untouched, or only print instructions? Recommendation: write and restore. Evidence: K2; research A. Code consequence: entry-scoped ownership inside an Authored file. State: unanswered.

Q15 — approval

Prerequisites: none. Question: Should HI configure the five reads to run without per-call approval where Codex allows it, or leave Codex defaults? Recommendation: configure unattended reads, prove on real desktop policy, never touch global policy. Evidence: K6/E6. Code consequence: approval fields in generated entries plus a host-policy test. State: unanswered.

Q16 — when the bundled compiler rejects a project

Prerequisites: none. Question: Gate activation by an actual load probe of each tsconfig under the bundled TS7, by project TypeScript version, or not at all? Recommendation: load probe; on failure, tools unavailable with the reason and lint/typecheck untouched. Evidence: K5. Code consequence: probe at scaffold/update, activation flag per compiler project. State: unanswered.

Q17 — recovery

Prerequisites: Q13. Question: After tsconfig, dependency or branch changes, is "start a new Codex session" an acceptable documented limitation, or must HI recover automatically? Recommendation: documented limitation for the first version; automatic recovery only if Q13 chooses the router. Evidence: K7/E4. Code consequence: none versus a wrapper process. State: unanswered.

Q18 — health witness

Prerequisites: none. Question: Should hi check report Typegraph installed, registered, and probe-passing as three separate facts? Recommendation: yes. Evidence: K8; research lens 10. Code consequence: live probe in check. State: unanswered.

Q19 — first supported platforms

Prerequisites: Q11. Question: macOS arm64 only, macOS arm64 plus Linux x64, or all of macOS/Linux/Windows on arm64/x64? Recommendation: macOS arm64 plus Linux x64 first, because those are the two targets that can actually be tested (local and CI); others follow proof. Evidence: K9. Code consequence: portable launcher and a per-target acceptance test. State: unanswered.

Q20 — deselection

Prerequisites: Q11, Q14. Question: When a repo stops using it, remove that repo's entries and keep the machine runtime? Recommendation: yes. Evidence: K10. Code consequence: entry removal only; no pruning. State: unanswered.

Working glossary after reset

Compiler Project, Tool Runtime and Semantic Session return to proposed status. Existing canonical terms (Pack, Baseline, Registry, Installed Record, Recorded Shape, Built Artifact, Software Scope, Effective Lint Policy) are unchanged.

Persistence

Round R5 opened; frontier Q10–Q16 and Q18 (no prerequisites); Q17, Q19, Q20 follow. No implementation, spec, release or configuration change.

R5 — Accepted decisions

User response: "agree all but 15 always approved, 19 we are not testing individual platforms, 20 ok." Each answer is pinned separately below. Q15 and Q19 diverge from the recommendation; all others accept it. This accepts requirements, not implementation readiness.

Q10

Prerequisites: none. Question: Does every project that selects the TypeScript Pack get Typegraph, or is it a separate opt-in Pack?

Accepted answer:

• The existing TypeScript Pack carries Typegraph. No separate Pack, no second selector. Activation per compiler project is still gated by Q16.

Q11

Prerequisites: none. Question: Where does the runtime live?

Accepted answer:

• Pinned machine-level install with the exact dependency lock, owned by the CLI, outside project dependencies. Project compiler and lint dependencies stay untouched.

Q12

Prerequisites: none. Question: Which compiler projects get a server?

Accepted answer:

• Auto-discover source-bearing tsconfig.json files in the current worktree. Exclude wiki and solution-only (no-source) configs by default. Explicit override when discovery is ambiguous; report ambiguity, never invent a root-wide config. Preserve each project's real options, exclusions and import closure.

Q13

Prerequisites: none. Question: One server per compiler project, or one HI router server?

Accepted answer:

• One Typegraph server per compiler project for the first version. HI ships no MCP process of its own. Router remains a deferred extension. Session cost (server count, startup, memory) is measured, not capped.

Q14

Prerequisites: none. Question: Does HI write and restore its Codex entries?

Accepted answer:

• Yes. HI writes its Typegraph entries into .codex/config.toml and restores them on every update. Everything else in that file stays user-owned and byte-preserved. Generated entries must be distinguishable from user entries; the mechanism is planning.

Q15

Prerequisites: none. Question: Should the five reads run unattended where Codex allows, or leave defaults?

Recommendation was "unattended where the host allows, proven on desktop policy." User overrode: "always approved."

Accepted answer:

• The five reads (ts_find_symbol, ts_definition, ts_references, ts_type_info, ts_module_exports) are configured always approved in HI's generated Typegraph entries: no per-call prompt. Only those generated entries carry approval settings; HI does not change the user's global approval policy because that was not asked. Whether Codex honors per-tool approval on every host is validation, not a reason to weaken this requirement. If the host still prompts or refuses, that is reported as a limitation, not silently accepted.

Q16

Prerequisites: none. Question: How is activation gated?

Accepted answer:

• Load probe. Each discovered tsconfig is loaded under the bundled TS 7.0.2 at scaffold/update time. On failure that compiler project's tools are unavailable with the reason; lint and typecheck are untouched; the project compiler is never changed. No version-string matching.

Q17

Prerequisites: Q13 (per-project accepted). Question: Is "new session after tsconfig/dependency/branch change" acceptable, or must HI recover automatically?

Accepted answer:

• Documented limitation. After tsconfig, dependency or branch changes the operator starts a new Codex session. No wrapper, no automatic recovery in the first version. Ordinary source edits keep refreshing through Typegraph's watcher. This supersedes retired Q8's automatic-restart answer.

Q18

Prerequisites: none. Question: Does hi check report Typegraph health?

Accepted answer:

• Yes, as three separate facts per machine/repo: runtime installed, Codex entries registered, load probe passing per compiler project. PATH or Registry currency alone never implies semantic readiness.

Q19

Prerequisites: Q11. Question: First supported platforms?

Recommendation was "macOS arm64 plus Linux x64 first, others after proof." User overrode: "we are not testing individual platforms."

Accepted answer:

• No per-platform acceptance test matrix. Supported platforms follow the pinned runtime's upstream package availability (at the tested lock: macOS arm64/x64, Linux arm/arm64/x64, Windows arm64/x64; Node >=22.18). HI does not run target-specific end-to-end tests before claiming availability. Platform failures surface at runtime through the Q11 install step, the Q16 load probe and the Q18 health facts, each with a reason. Assumption recorded: "not testing individual platforms" means no dedicated per-target proof, not a claim that every platform is known to work.

Q20

Prerequisites: Q11, Q14. Question: On deselection?

Accepted answer:

• Remove that repository's generated Typegraph entries; keep the machine runtime. No pruning of runtime versions.

Consistency pass after R5

• Q10 widens the capability to every TypeScript Pack selector. Q16 and Q18 make that safe without Q19 platform tests: a project or platform the bundled compiler cannot serve becomes "unavailable with reason", visible in hi check, with lint/typecheck unaffected.
• Q13 per-project topology makes Q17's documented limitation the only honest recovery answer; automatic recovery would require the deferred router.
• Q15 always-approved applies to the five generated entries only. It does not touch global policy and does not enable hover, graph, mutation or Effect diagnostics tools.
• Q14 restore-on-update plus Q20 removal are the full entry lifecycle; nothing else in the Codex file is managed.
• Q12 exclusions (wiki, solution-only) are defaults inside auto-discovery, not a separate selection unit; C4 Pack-only selection holds.
• Retired Q1–Q9 answers that happen to match (Pack, pinned install, auto-mapping, entry ownership, retention) are re-accepted here on their own ids; the retired automatic-restart (Q8) and platform-proof (Q9) directions are replaced by Q17 and Q19.

Accepted target view after R5

project selects TypeScript Pack
  CLI installs pinned Typegraph runtime on the machine (exact lock)
  CLI discovers source-bearing tsconfigs (wiki, solution-only excluded)
    load probe under bundled TS 7.0.2 -> pass: one server entry
                                      -> fail: unavailable, reason recorded
  CLI writes/restores its entries in .codex/config.toml
    five reads always approved; rest of file untouched
  hi check: installed | registered | probe per project
Codex session -> per-project server -> native TS7 read
  tsconfig/deps/branch change -> new session (documented)
repo deselects -> its entries removed, runtime stays

Glossary Q21 — proposed for closure

Question: Accept the three working terms as canonical?

• Compiler Project — the source program and options selected by one tsconfig.json. Avoid: package folder, workspace, Software Scope.
• Tool Runtime — the pinned Typegraph installation and its exact dependency graph on one machine. Avoid: project compiler, lint toolchain.
• Semantic Session — one live Typegraph process answering for one Compiler Project in one worktree. Avoid: installation, registration.
• Relationship: a Semantic Session uses one Tool Runtime to answer about one Compiler Project; a Software Scope may span several Compiler Projects.
• Axiom: installed, registered, probe-passing and answered are four distinct facts.

State: unanswered.

Persistence

Q10–Q20 answered; frontier empty; shared-understanding confirmation pending. Glossary Q21 open for closure. No implementation, spec, release or configuration change.

Closure — 2026-09-28

User: "i confirm your understanding on overrides. i agree with shared understanding. good", then invoked create-architecture and create-spec. Shared understanding is confirmed; the grill is closed with Q10–Q20 accepted as recorded in R5.

Glossary Q21 was not answered separately. Disposition: parked. Compiler Project, Tool Runtime and Semantic Session remain working labels in the published glossary, architecture and spec; they are not canonical terms. Owner: user. Resume trigger: any later grill round on this capability.

Synthesis: glossary published with existing canonical terms, the three working labels, and the axioms. Architecture and spec compile under apps/wiki/content/docs/project/specs/cli/codex-typescript-mcp/.