fix: keep Codex MCP responsive during startup

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to the TypeScript package will be documented in this file.
 
+## [0.31.2] - 2026-07-16
+
+### Fixed
+
+- **Codex no longer times out while Madar performs the initial automatic refresh**: the MCP transport becomes responsive immediately while graph reconciliation runs in a background worker, and graph-backed calls remain fail-closed until the watcher reports a ready graph. Worker startup and reconciliation failures remain visible through watcher state, stderr, and MCP freshness errors. Closes #559.
+- **Managed Codex profiles now allow large workspaces enough time to start**: new and updated `.codex/config.toml` entries set `startup_timeout_sec = 180` without overwriting unrelated user configuration.
+
+### Notes
+
+- After upgrading, rerun `madar codex install` in each Codex workspace to migrate the managed MCP block to the extended startup timeout.
+
 ## [0.31.1] - 2026-07-15
 
 ### Changed

README.md

@@ -71,7 +71,9 @@ Madar supports these project-local installers:
 
 Installer details are in the [CLI and MCP reference](https://github.com/mohanagy/madar/blob/main/docs/reference/cli-and-mcp.md). Step-by-step setup and smoke tests are in the [agent quickstarts](https://github.com/mohanagy/madar/blob/main/docs/tutorials/agent-quickstarts.md).
 
-If you upgrade from a version earlier than `0.30.0`, rerun your agent's install command to add automatic refresh to its managed MCP entry.
+After upgrading Madar, rerun your agent's install command so its managed profile receives current runtime settings. Older profiles may lack automatic refresh; older Codex profiles may also lack the extended MCP startup window needed by large or synchronized workspaces.
+
+Starting with `0.31.2`, Codex installs set `startup_timeout_sec = 180`. Madar makes the MCP transport available while the initial graph reconciliation runs in a background worker. Graph-backed calls resume only after startup completes, watcher health is non-blocking with complete coverage, and the idle watcher's policy matches the published graph and manifest; `idle` alone is not a readiness guarantee.
 
 ## What Changes for the Agent
 
@@ -185,13 +187,15 @@ Read the [benchmark suite and all dated receipts](https://github.com/mohanagy/ma
 
 ## Current Release
 
-Current version: `0.31.1`.
+Current version: `0.31.2`.
+
+`0.31.2` keeps the Codex MCP connection responsive while its initial automatic graph refresh runs, adds an explicit 180-second Codex startup window, and keeps graph-backed answers unavailable until the refreshed graph is ready.
 
-`0.31.1` rebuilds the public onboarding path and clarifies what each benchmark experiment proves. Runtime behavior is unchanged from `0.31.0`.
+`0.31.1` rebuilt the public onboarding path and clarified what each benchmark experiment proves. Runtime behavior was unchanged from `0.31.0`.
 
 `0.31.0` made code graphs directed by default, separated evidence strength from answer readiness, added bounded context recovery, made indexing completeness explicit, preserved generation policy during automatic refresh, isolated linked-worktree artifacts, and removed benchmark expectations from production retrieval.
 
-Read the full notes in the [0.31.1 changelog](https://github.com/mohanagy/madar/blob/main/CHANGELOG.md#0311---2026-07-15).
+Read the full notes in the [0.31.2 changelog](https://github.com/mohanagy/madar/blob/main/CHANGELOG.md#0312---2026-07-16).
 
 ## Documentation
 

docs/auto-refresh.md

@@ -1,6 +1,6 @@
 # Auto-refresh and generation policy
 
-Installed MCP profiles run `madar serve --stdio --auto-refresh`. The server starts a recursive filesystem listener before its initial graph reconciliation, marks the graph pending as soon as a relevant event arrives, and performs an authoritative source snapshot before publishing the graph as usable again.
+Installed MCP profiles run `madar serve --stdio --auto-refresh`. The stdio transport becomes available immediately while automatic refresh runs in a background worker. Before that worker starts, Madar publishes a `starting` watcher state so graph-backed requests fail closed instead of reading an older graph. The worker then starts a recursive filesystem listener before its initial graph reconciliation, marks the graph pending as soon as a relevant event arrives, and performs an authoritative source snapshot before publishing the graph as usable again.
 
 Filesystem events provide low-latency invalidation; they are not the correctness boundary. Madar also performs full reconciliations on an adaptive schedule. Idle intervals back off from 30 seconds to at most 5 minutes when recursive events are available. Platforms without recursive events use adaptive polling from 1 second to at most 30 seconds. The lower-level `pollIntervalMs` option is an internal/test override rather than a CLI setting.
 
@@ -36,7 +36,9 @@ The local `watcher-state.json` beside `graph.json` is written atomically and inc
 - pending/failure details; and
 - stored/current policy fingerprints and match state.
 
-`madar doctor` and `madar status` render those fields. During an auto-refresh MCP session, graph-backed prompts, resources, completions, and tool calls are refused while state is pending, reconciling, failed, incomplete, or policy-mismatched. Retry after the state returns to `idle`; if it remains failed, run `madar generate . --update` and inspect `madar status`.
+`madar doctor` and `madar status` render those fields. During an auto-refresh MCP session, graph-backed prompts, resources, completions, and tool calls are refused while state is starting, pending, reconciling, failed, incomplete, or policy-mismatched. Retry after the state returns to `idle`; if it remains failed, run `madar generate . --update` and inspect `madar status`.
+
+MCP initialization, ping, and list/discovery requests remain responsive during `starting` and `reconciling`. This lets an agent connect without waiting for a cold large-repository build while preserving the same freshness boundary for every graph answer.
 
 The refresh lease serializes multiple MCP processes that target the same workspace. Graph, source-manifest, indexing-manifest, report, and watcher-state publications use same-filesystem atomic renames. A post-build reconciliation detects edits made while generation was running and queues another rebuild before the state can return to `idle`.
 

docs/mcp-registry/server.json

@@ -9,13 +9,13 @@
         "source": "github",
         "url": "https://github.com/mohanagy/madar"
     },
-    "version": "0.31.1",
+    "version": "0.31.2",
     "packages": [
         {
             "registryType": "npm",
             "registryBaseUrl": "https://registry.npmjs.org",
             "identifier": "@lubab/madar",
-            "version": "0.31.1",
+            "version": "0.31.2",
             "runtimeHint": "npx",
             "transport": {
                 "type": "stdio"

docs/reference/cli-and-mcp.md

@@ -33,7 +33,7 @@ For Claude, Cursor, Copilot, and Gemini, `--profile strict` writes `MADAR_TOOL_P
 
 Aider and OpenCode are intentionally context-pack-first: run `madar generate .`, install the profile, and start broad codebase work with `madar pack "<task>" --task explain` before raw file search. `madar aider install` writes an AGENTS.md profile only; remove it with `madar aider uninstall`. `madar opencode install` writes the AGENTS.md profile, `.opencode/plugins/madar.js`, and a strict-profile Madar MCP entry in `opencode.json` or `opencode.jsonc`; remove only Madar-owned content with `madar opencode uninstall`.
 
-Codex is intentionally context-pack-first too: run `madar generate .`, install with `madar codex install`, and start broad codebase work with `madar pack "<task>" --task explain` before raw file search. The install writes the Madar-owned AGENTS.md section, `.codex/hooks.json`, `.codex/madar-user-prompt-submit.cjs`, and a marker-owned strict-profile `[mcp_servers.madar]` block in `.codex/config.toml`. Its `UserPromptSubmit` hook provides model-visible guidance only for local code tasks; it is guidance, not enforcement. Enable it only in a trusted repository, restart or start a new Codex session, use `/hooks` to review and trust the project hook, then verify the server through `/mcp` or `codex mcp list`. `madar doctor` and `madar status` validate on-disk install state only, not live Codex trust or activation. To remove the profile, run `madar codex uninstall`; it removes only Madar-owned AGENTS, hook, script, and marked TOML content while preserving unrelated content.
+Codex is intentionally context-pack-first too: run `madar generate .`, install with `madar codex install`, and start broad codebase work with `madar pack "<task>" --task explain` before raw file search. The install writes the Madar-owned AGENTS.md section, `.codex/hooks.json`, `.codex/madar-user-prompt-submit.cjs`, and a marker-owned strict-profile `[mcp_servers.madar]` block in `.codex/config.toml`. That block includes `startup_timeout_sec = 180` for cold large-repository and synchronized-filesystem startup. Re-run the install after upgrading to migrate an older Madar-owned block; user-managed MCP declarations remain untouched. Its `UserPromptSubmit` hook provides model-visible guidance only for local code tasks; it is guidance, not enforcement. Enable it only in a trusted repository, restart or start a new Codex session, use `/hooks` to review and trust the project hook, then verify the server through `/mcp` or `codex mcp list`. `madar doctor` and `madar status` validate on-disk install state only, not live Codex trust or activation. To remove the profile, run `madar codex uninstall`; it removes only Madar-owned AGENTS, hook, script, and marked TOML content while preserving unrelated content.
 
 ## MCP Registry metadata
 
@@ -79,6 +79,8 @@ Cached `context_pack` explain responses still refresh the current freshness rece
 
 With `--auto-refresh`, filesystem events invalidate the graph immediately and adaptive authoritative reconciliations verify the full watched corpus. Graph-backed MCP requests fail closed while reconciliation is pending/failed or watcher coverage/policy is not trustworthy. Generation policy is versioned and fingerprinted in both `graph.json` and `manifest.json`, so automatic refresh reuses direction, SPI, Git-ignore, symlink, document/non-code, exclusion, extractor, and indexing-threshold settings. Policy drift forces a full rebuild. `madar doctor` and `madar status` expose the local `watcher-state.json` health record. Full behavior and legacy migration are documented in [Auto-refresh and generation policy](../auto-refresh.md).
 
+The stdio transport and MCP discovery stay responsive while initial reconciliation runs in a background worker. Until the watcher reaches `idle` with matching published policy, graph-backed calls return a bounded freshness error that tells the caller to wait or run `madar generate . --update`.
+
 ## Common commands
 
 ```bash

docs/release.md

@@ -46,7 +46,7 @@ Recommended follow-up checks:
 - confirm `madar --version` prints the version you are about to publish
 - confirm `madar generate .` completes and refreshes `out/graph.json`
 - confirm install commands write the expected project files and instructions
-- for Codex, confirm `.codex/hooks.json`, `.codex/madar-user-prompt-submit.cjs`, and `.codex/config.toml` exist; only in a trusted repository, restart or open a new session, use `/hooks` to review/trust the project hook, then use `/mcp` or `codex mcp list` to verify the local MCP server
+- for Codex, confirm `.codex/hooks.json`, `.codex/madar-user-prompt-submit.cjs`, and `.codex/config.toml` exist, and that the managed MCP block contains `startup_timeout_sec = 180`; only in a trusted repository, restart or open a new session, use `/hooks` to review/trust the project hook, then use `/mcp` or `codex mcp list` to verify the local MCP server
 - uninstall any agent profile you enabled during the smoke test so the workspace returns to a clean state
 
 ## 4. Publish and tag

docs/tutorials/agent-quickstarts.md

@@ -109,6 +109,7 @@ This installs the Madar-owned AGENTS.md section, a task-applicable `UserPromptSu
 Common failure modes:
 
 - If `madar status` marks Codex as partial, inspect `.codex/hooks.json`, `.codex/madar-user-prompt-submit.cjs`, and `.codex/config.toml`, then rerun the install.
+- If Codex reports that the Madar MCP client timed out after 30 seconds, rerun `madar codex install` and confirm its managed block contains `startup_timeout_sec = 180`. Then run `madar doctor` and `madar status`; if reconciliation remains failed, run `madar generate . --update`.
 - If Codex ignores the guidance, confirm `AGENTS.md` still contains the Madar-owned rules and that the project hook is trusted in `/hooks`.
 - `madar codex uninstall` removes only the Madar-owned AGENTS section, hook, script, and marked TOML block; unrelated hooks and TOML configuration remain.
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lubab/madar",
-    "version": "0.31.1",
+    "version": "0.31.2",
     "description": "Stop AI coding agents from rediscovering large TypeScript/Node repos. Madar compiles task-aware local context packs from what runs for this task.",
     "license": "MIT",
     "author": "mohanagy",

sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:456acc7e-1276-4f2d-8b8c-5ae91a55c9b0",
+  "serialNumber": "urn:uuid:184d19a4-cdcf-4d54-bdb2-7948c1d2c353",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-15T15:18:39.220Z",
+    "timestamp": "2026-07-16T05:07:00.859Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@lubab/madar@0.31.1",
+      "bom-ref": "@lubab/madar@0.31.2",
       "type": "library",
       "name": "@lubab/madar",
-      "version": "0.31.1",
+      "version": "0.31.2",
       "scope": "required",
       "author": "mohanagy",
       "description": "Stop AI coding agents from rediscovering large TypeScript/Node repos. Madar compiles task-aware local context packs from what runs for this task.",
-      "purl": "pkg:npm/%40lubab/madar@0.31.1",
+      "purl": "pkg:npm/%40lubab/madar@0.31.2",
       "properties": [],
       "externalReferences": [
         {
@@ -3296,7 +3296,7 @@
   ],
   "dependencies": [
     {
-      "ref": "@lubab/madar@0.31.1",
+      "ref": "@lubab/madar@0.31.2",
       "dependsOn": [
         "@vscode/tree-sitter-wasm@0.3.1",
         "fflate@0.8.3",