Codex TypeScript MCP: Registry Research

Decision status (2026-09-28 reset): the grill was restarted; every decision below and in earlier sections is retired history, and the active grill now asks Q10–Q20 afresh. Earlier text in this report that reads as accepted is superseded by that reset.

Historical decision status: the active grill supersedes historical recommendations in this report. Accepted: existing TypeScript Pack, exact isolated installation, five host-permitted unattended reads, no incompatible-compiler fallback, automatic config mapping with wiki excluded, management limited to this implementation's Typegraph settings with HI restoring its generated settings, installation retained after repository deselection, and automatic restart with failed recovery reported. Q9's first supported operating-system matrix remains open. These are requirements, not implementation or validation claims.

The merged Registry installer preserves existing Codex configuration as Authored content. It does not yet install, reconcile or verify Typegraph. The earlier full-file-overwrite finding is superseded. Locally, the tested runtime survives and fresh semantic replay succeeds, but the eleven Codex registrations are absent. Their disappearance has no proven cause.

This refresh updates the active grill, not its answers: Q1–Q4 were unanswered at the evidence snapshot; the subsequent decision update below supersedes that state. No configuration restoration, dependency install, policy change or Baseline implementation was performed.

R1 decision update — supersedes earlier recommendations

The user accepted Q1–Q4 after this research: the existing TypeScript Pack supplies Typegraph MCP; a versioned isolated machine runtime uses an exact dependency lock tied to Baseline; five reads support unattended use where host policy permits without global bypass; incompatible/unverified targets are unavailable with a clear reason, never silently substituted. The earlier separate-optional-Pack candidate is superseded, not a previously accepted requirement. Subsequent Q5 accepts automatic mapping with wiki excluded; Q6 limits ownership to this implementation’s Typegraph wiring. Q7 lifecycle and Q6a conflict/removal behavior remain open; excluded hover and other LSP capabilities were not approved. See the current grill status.

Authority and research coverage

The three completed lanes covered current Registry selection/projection, install/update/failure lifecycle, and runtime/upstream replay. Source was compared against merged main, provider items read back, focused tests run and semantic queries replayed. This report retains substantive evidence so temporary research files are optional.

• GitHub main readback: d3f3464c5b165d3261ffdea1ef921b15a31fecb4. Registry 6.0.0 merged at 80a483bc; published fix/CLI 6.0.1 source: 1ca243d3ec5a2ce75d96ffd91a33d5257e31ae2f.
• Local HEAD 4972b5d6dda482634fb54911522a0dad4d30b74d predates the merged source. The working tree had 1,297 pre-existing statuses (311 modified, 922 deleted, 64 untracked). Direct byte comparison found 94 relevant Registry/scaffold source files identical to origin/main; other lanes independently verified their slices. Deleted/untracked status against old HEAD is not evidence that current source is absent.
• Current Registry catalog and immutable catalog report 2026.09.28-1ca243d3, compatible with CLI >=6.0.0 <7.0.0.
• Published hooks item confirms Authored Codex config. Catalog SHA-256 readbacks: hooks 00572d3d98b05ac13bae4582fcd99613463422acfbaa172974bd58b290cc9d42; TypeScript Pack 894b3624e981a28bef90bb172e59887b337eaf2764bf916fd898529be60db674; Effect Pack 083fbcf91be879e6b9f1ef64ac3298e8ddae56f4e42b38dbbbdde00005658f70; tools 5c90bad6d1b79c8369df790c712cc4d35ed1cbd2ba9c0a123cebbb0b0471408e. These catalog hashes establish cache/content integrity, not recipient runtime health.
• No Typegraph, Serena or MCP item exists in that catalog. Tools requirements are agent-browser, opensrc, portless, skills. TypeScript Pack depends on Anti-Slop lint and quality-types; Effect contributes lint, skills and source guidance, not MCP.
• Local hi --version reports 6.0.0. hi check --json reports current, CLI-compatible, installed/latest 2026.09.28-1ca243d3, missingTools: []. This measures Registry version and required-tool PATH state, not MCP registration or semantics.

Current source findings

Source anchors below are relative to apps/cli/src/ unless stated otherwise; line numbers describe this snapshot.

A — Authored configuration changes the ownership problem

registry/publisher/sources/hooks.ts:91–104 publishes .codex/config.toml as Authored; its test at line 54 checks that contract. registry/pipeline.ts:760–778 preserves existing Authored bytes even with --yes; absent files receive the agents/features/hooks starter. registry/migrate.test.ts:34–38,294–302 covers Authored Codex byte preservation and passed in this refresh.

pipeline.ts:860–876 also retains Authored files during stale cleanup. Hooks come from always-installed pack-core (registry/publisher/sources/packs.ts:32–43). Adding MCP text to the starter would affect only missing files; it would not update existing project configuration. There is no owned MCP-entry removal mechanism.

registry/drift.ts:203–215 treats an existing Authored file as current; lines 275–295 make template changes informational. registry/check.ts:77–103 checks version and settings-required tools, not TOML entries or calls. registry/model.ts:117–127 and registry/merge.ts:17–42 support JSON/YAML merges only; merge effects are outside recorded file/symlink ownership (drift.ts:136–142). Duplicate File/Symlink targets are rejected (materialize.ts:268–276), so another full-file producer is not an entry reconciliation solution.

Candidate, Q6: preserve whole-file Authored ownership and define bounded add/update/remove behavior for owned MCP entries, including collisions and user edits. No second scaffold manager, old projection adapter or retired receipt is needed. Former sync-subagents/Context Plan projection machinery is retired; current Registry schemas live in registry/model.ts, with only genuinely shared contracts belonging in packages/scaffold.

B — Pack selection exists; compiler-project inventory does not

Project settings selected Pack ids plus pack-core determine Registry dependency closure (registry/resolve.ts:11–42, init flow lines 139–151 and 238–250, pack source lines 1–5). Recorded Shape includes workspace paths/languages, not a compiler-config inventory. registry/materialize.ts:50–66 expands root, non-root workspaces or selected Software Scopes; none is automatically a valid compiler program.

The previous empty-root failure still matters. Preserve each target tsconfig's options, imported closure, exclusions and overlapping programs. Software Scope remains the lint owner: the tested wiki compiler project is useful even when it is not a selected lint scope.

Candidates, Q1/Q5: at the research snapshot a separate optional Pack was recommended (superseded by accepted Q1: existing TypeScript Pack); derive explicit compiler bindings instead of copying HI's eleven workspaces or treating all package directories as programs. Detection proposes selection; it does not select.

C — Tool bootstrap is not the verified runtime installation

Required-tools metadata carries ids. features/tool-ensure/application.ts:68–72 resolves tools from settings and installed item/skill requirements and requests refresh-latest; integrations/tool-management.ts:393 selects the refresh target and installs globally. hi check examines settings-required tools only, while ensure considers the larger union.

registry/confine.ts:17–37 confines file effects to the repository. Installed Record (registry/model.ts:292–303) records repo-relative paths and dependency names, not machine runtime state or health. pipeline.ts:297 accepts only effect-tsgo patch --no-typescript --oxlint as a postInstall command; arbitrary Typegraph setup is skipped/reported, not a supported shortcut.

Candidates, Q2/Q7: CLI provisions an exact versioned runtime from Registry-declared inputs, retaining its normal dependency lock. Do not mistake a registry item hash or top-level npm pin for the tested transitive graph. Runtime location, platform/offline behavior, repair and removal remain decisions; no API service is justified by local stdio.

D — Install completion is not semantic readiness

Init/update converge on runInstall; diff materializes recorded/planned content without writes; check and tools ensure have separate scopes. Init fetches a proposal catalog and runInstall fetches latest again; consistency during concurrent latest changes is not newly guaranteed.

pipeline.ts:969–1032 resolves, fetches, validates and plans before writes. Then settings/migration (1034), files (1060), merges (1076), links (1083), dependency manifest/install (1088), stale cleanup (1114), migration finalization (1138), Installed Record (1156), lint (1168), result (1186). Conflict/link/dependency failures can yield partial outcomes. The Record can be written after dependency install failure; lint results are separate, not semantic proof.

registry/installed-record.ts:43–60 gives per-file atomic writing, not a transaction across files, subprocesses and machine tools. Interruption tests (pipeline.test.ts:1011) inject named step failures and compare reruns. They were inspected but could not run locally due missing yaml; they do not establish process-kill or concurrency safety. No repository lock/journal/abort cleanup was found in the inspected modules.

Candidates, Q6–Q9: explicit partial results and bounded retry; verify runtime before claiming active registration; preserve user entries during repair. Decide supported concurrency and runtime retention only after Q2. Do not invent rollback, daemon, refcount or general Registry redesign.

E — Current edit-hook ownership stays separate

apps/cli/src/data/hooks/format-edited-file.mjs:47,294 reads .devpunks/installed.json record.paths and protects Copied/Built artifacts. A missing/invalid Record yields an empty protected set: edits still format, but Baseline-file protection is unavailable until valid ownership exists. Source tests at lines 226, 367 and 382 cover tracked-record detached-worktree behavior, absent/invalid records and Codex formatting without a Record; these hook tests were inspected, not executed in this refresh.

format-edited-file.mjs:495 delegates selected quality work to managed-lint; apps/cli/src/data/scripts/managed-lint.mjs:321 resolves Software Scope routes. Its selection/record checks remain separate. The earlier issue #231 managed-hook-paths.json explanation is historical; the current hook does not depend on the semantic MCP bridge.

Runtime replay and historical proof

Current .codex/config.toml contains 18 lines of agents/hooks configuration, byte-identical to the inspected origin/main file. It has no Typegraph entries; neither does the targeted global config search. The cause is unknown. Authored preservation does not explain or prove their removal.

The isolated installation remains at ~/.local/share/hi-tools/typegraph-mcp/0.9.56: Typegraph 0.9.56, TypeScript API 7.0.2, private @effect/tsgo 0.36.5, SDK 1.30.1. The native executable reports 7.0.2+effect-tsgo.0.36.5. Current project versions remain native 7.0.2, compatibility TypeScript 6.0.2 and Effect lint 0.39.0; this research changed no dependencies and makes no claim that the merged migration left every manifest byte unchanged.

Fresh SDK replay used the previous exact shell command with explicit TYPEGRAPH_PROJECT_ROOT and workspace TYPEGRAPH_TSCONFIG:

A fresh two-file fixture changed an imported return string to number; consumer type refreshed after 100ms. All three sessions closed with no remaining owned server/compiler children. This proves ordinary source refresh and normal close, not config/dependency/branch freshness or crash/disconnect recovery.

The former packages/contract/src/baseline.ts:ArtifactKind witness is now absent. Prior eleven-project coverage and actual Codex reviewed calls remain historical proof. The fresh replay does not prove current Codex availability: no registrations were restored and no new Codex host-policy probe ran. All five tools still lack annotations. Earlier read-only/approval-never refusal and --approve-for-me success remain scoped historical results, not a universal approval rule.

Bounded upstream readback: Typegraph latest remains 0.9.56; Serena main remains the evaluated 7a2968335f2198b966864de1ce3655c8e485a653. No comparison rerun was needed. Keep graph, LSP hover, mutations and Effect diagnostics outside the five-read surface pending separate evidence.

Agent trace and ten flow lenses

human/project settings -> selected Pack -> immutable Registry closure
  CLI plan -> materialize by kind/Recorded Shape -> retain Authored Codex config
  [future explicit runtime provisioning + owned-entry reconciliation]
    Codex session -> host permission -> worktree-bound native TS7 read
existing edit hooks -> lint/format -> disk -> source watcher -> answer

Registry installed, runtime installed, MCP registered and host-verified semantics are distinct observations. The missing registration makes that distinction concrete.

These lenses identify bounded MCP decisions, not automatic defects requiring changes to the general installer.

Recommendation and unresolved decisions

Smallest candidate path: selected TypeScript Pack → Registry inputs for launcher/runtime/version/project bindings → CLI provisioning and this implementation’s Typegraph wiring → worktree-native TS7 reads → targeted readiness proof. Keep the whole TOML Authored and preserve existing lint authorities. Preserve actual tsconfig options and avoid the empty root. Expose only the five proven compiler-API reads.

Q1–Q4 are now answered as recorded above; Q1 supersedes the separate-Pack recommendation. Q5 inventory, Q6 config ownership, Q7 runtime lifecycle, Q8 freshness/recovery and Q9 acceptance retain their existing prerequisites. No new immediate frontier or canonical terms were accepted.

Validation and limits

Executed source tests: hooks item 4 passed, migration 24 passed, Registry check 7 passed. Commands: bun run --cwd apps/cli test -- src/registry/publisher/sources/hooks.test.ts src/registry/migrate.test.ts; lifecycle lane bun run test:source src/registry/pipeline.test.ts src/registry/check.test.ts src/features/tool-ensure/application.test.ts. The latter's pipeline and tool-ensure suites failed collection because yaml was missing. No dependencies were installed; 35 passing tests do not imply the broader lifecycle suite passed.

Inspected only: staged interruption/fixed-point retry contracts and unexecuted lifecycle cases. Fresh runtime evidence is SDK semantic replay, source freshness and normal cleanup; current host usability, clean-machine install, divergent worktrees, concurrent install/removal, config/dependency changes and crash recovery remain unverified.

The prior-run raw supplements and work log under /tmp/hi-mcp-* are no longer present. Substantive findings and validation outcomes are retained in this report; temporary files are not required evidence for its conclusions. No commit, publish, release or runtime/config change belongs to this refresh.

Documentation validation and rule evaluation

• bun run --cwd apps/wiki test: 4 files, 16 tests passed during this docs wave, including public wiki contracts. Subsequent edits clarified evidence wording and synchronized the same runbook only.
• Final bun run --cwd apps/wiki check:content: passed, wiki content current. Preview/sync changed only the Codex runbook projection and its required runbooks metadata; no unrelated deletion.
• Scoped git diff --check: passed. Codex configuration SHA-256 remained 97db764bbd7c961ccd4fab940138c084d099c9d3fbb7f80ea06a76ebd668e36e; no runtime/config/dependency writes.
• HI-DOCS-001 pass: operator truth remains in the source runbook; research and active requirements remain in routed project wiki. HI-WIKI-001 pass: report and runbook registered in their existing route metadata. HI-WIKI-003 pass: project frontmatter, source links, wiki log and passing content/public-contract checks.
• HI-REPO-003 not applicable: no local URL/origin change. HI-UI-001 not applicable: content only, no UI composition changes.
• This docs wave changes no changelog and selects no release; pre-existing changes elsewhere are not classified by that statement. No commit/push/publication, requirement acceptance or canonical glossary promotion.

R2 factual grounding after accepted R1

registry/shape.ts:42–83 detects TypeScript as a Boolean language signal; lines 105–110 exclude wiki workspaces and retain wikiRoot separately. registry/model.ts:258 has no compiler-config/reference/options inventory; materialize.ts:61 expands lint scopes or non-root Recorded Shape workspaces. Thus neither covers every compiler project: historical wiki coverage worked despite both omissions. Q5 subsequently accepted automatic discovery/mapping with ambiguity resolution and explicitly excluded wiki; the successful historical wiki probe does not authorize coverage.

The installed Typegraph 0.9.56 requires Node >=22.18; proven local host is Darwin arm64 / Node 22.22.0. Its private Effect tsgo 0.36.5 has packages for Darwin arm64/x64, Linux arm/arm64/x64 and Windows arm64/x64, but package existence is not end-to-end support. tool-management.ts:165,393 provides global/latest bootstrap, not isolated immutable runtime repair/removal. registry/client.ts:8 caches versioned catalogs/items, not proof of offline runtime installation. Q7 lifecycle is presented, unanswered; Q9 retains exact supported matrix and host-version decisions. No new platform test or dependency installation occurred.

R2 Q5/Q6/Q7 recommendations and stable prerequisites are persisted in the grill. Q5 is now answered with automatic mapping and explicit wiki exclusion; Q6 ownership scope is accepted; Q7 and Q6a remain open. No new canonical glossary term was accepted.

R1 brainstorm delta: the existing TypeScript Pack carries the capability for its selectors; Q4 keeps incompatible/unverified targets semantic-unavailable while lint/typecheck continues. This is neither a compiler conversion nor a new opt-in toggle. The ten-lens findings remain applicable.

Q6 ownership narrowing

The user accepted management only of the code/wiring enabling this Typegraph MCP implementation. Earlier generic MCP-entry reconciliation proposals are superseded: no general MCP manager or management of arbitrary servers is authorized. Other Codex configuration remains user-owned. User-edited/colliding Typegraph wiring and removal policy are still unresolved Q6a; no overwrite permission or deletion policy is inferred. Q7 is the remaining R2 question; Q6a enters the next frontier and Q9 must account for it. This is a requirements decision, not implementation.

Later Q7 answer and R3

The user accepted leaving the machine Typegraph installation in place when one repository stops using it. This follows a plain-language replacement of the original compound Q7; it does not approve every lifecycle proposal above. Q1–Q7 are answered in their recorded scope. The active grill now asks Q6a (manual edits to HI-generated Typegraph settings) and Q8 (automatic restart/freshness failure behavior). Q9 retains platform/version/support acceptance. See the current grill status for authority.