perf(runtime): halve launch fsync work, and doctor stops failing on unused agent profiles

[aviggiano]

Problem

Four launch and lifecycle hygiene problems that came up while costing #921:

1. Launch time goes to fsync. Publishing the sealed execution snapshot fsyncs every file twice. On the runtime test fixture (12,552 files in 1,386 directories), one publication issues 27,876 fsync calls, 25,104 of them on files. Where fsync is slow, as on the loaded host used here, that time dominates (see Verification). An earlier measurement put a production closure at about 51,000 files; I did not re-measure it.
2. doctor fails on agent profiles no node uses. It requires the CLI of every configured model profile. On a fresh ultrafuzz init on a Codex-only host, the verdict is "needs attention" only because the scaffold's opt-in Claude, Kimi and Pi profiles are not installed. doctor also builds DOCTOR_WORKFLOW_ENGINE_* diagnostics and then throws them away. It says nothing about the temporary directory, even though launch and resume install the workflow engine controller there and native resumes leave theirs behind (Re-evaluate sealed execution snapshots: cost/benefit after repeated campaign losses #921 cost 1: a tmpfs /tmp exhausted a host's memory).
3. resume --refresh-controller dirties the governed target. It renders into <project>/.smithers/continuations/<uuid>/, and that path is not controller-owned for governance. Unless the project ignores .smithers, the next launch sees untracked target files, and a private campaign (the default policy) or any cloud launch rejects a dirty target.
4. The control seal can be written but not read back. Runtime documents are parsed with a 100,000-item limit counted across the whole document. The seal's schema admits 100,000 execution files plus three identity arrays of up to 100,000 entries each, and launch writes the seal after schema validation alone.

Root cause

1. writeSnapshotFile created files 0400 and fsynced them. sealSnapshotDirectoryPermissions then reopened every file, fchmoded it (to 0500 for executables, and to the 0400 it already had for everything else) and fsynced it again.
2. diagnoseProject built the command list from configuredAgentRefs(models.profiles), which is every configured profile, and ignored the topology selection it already computed for the OpenRouter credential check. workflowEngineCheck and compatibilityPatchCheck ran, but only their check names were used.
3. controllerOwnedGovernancePaths lists .smithers/workflows and .smithers/node_modules but not .smithers/continuations.
4. parseRuntimeDocumentBytes parsed every runtime document with a 100,000-item limit, below the 400,000 items a seal at its schema's array bounds holds.

Change

• Snapshot publication (workflow-integrity.ts, net −26 lines). Each file is created with its final mode (0500 for executables, otherwise 0400). The mode is also set through the creating descriptor, because the umask can clear creation bits, before the file's single flush, so bytes and mode become durable together. The permission seal now only makes directories read-only. The publication verification that already runs right after it still checks each file's mode, link count and bytes, each link's target, that every directory is read-only, and that no entry is missing or unexpected. This removes the second open, fchmod and fsync per file: per-file flushes are halved exactly, and total fsyncs per publication drop by 45%.
• doctor (doctor.ts, CLI renderer):
  • An agent's CLI is required only if the selected topology or its [retry] agents chain can dispatch to that agent (activeTopologyAgentRefs, the same selection the credential check uses). Other configured profiles' CLIs are still probed and listed with required: false, and the human output marks them (not required). Agents that share a CLI (Codex/OpenRouter, Claude/DeepSeek) require it when any of them is selected. The toolchain summary counts only the required commands.
  • The two discarded check builders are deleted. layout_status and per-patch posture are still reported, and the reference docs drop the five codes that were never emitted.
  • A new temporary-directory check warns (it never fails the verdict) when os.tmpdir() is a tmpfs or has under 2 GiB free. It reports the free space and how many ultrafuzz-controller-* directories the temporary directory holds, with their total size, and never deletes them. The warning's diagnostic code is DOCTOR_TEMPORARY_DIRECTORY_CONSTRAINED.
• Governance (data-governance.ts). <project>/.smithers/continuations is now controller-owned.
• Runtime document parsing (runtime-document-codec.ts, one number). parseRuntimeDocumentBytes now parses every runtime document with a 400,000-item limit instead of 100,000: the item count of a control seal whose arrays are all at their schema bounds. The seal's property total at those bounds (400,035) was already under the unchanged 500,000 limit, and byte limits are unchanged. The first version gave the seal its own limits; review pointed out that one shared number is the same fix with less code, and it also covers the execution-dependency map. Launch writes that map the same way, after assertRuntimeDocument alone (smithers.ts), and reads it back through this parser, while its schema admits 320,001 items. A map with more than 100,000 items in total (for example 100,001 issuers, within the schema's 110,001) was writable but unreadable under the old limit.
• Docs: docs/reference/cli.md (Doctor section), docs/config.md (OpenCode note) and docs/tutorials/first-campaign.md now describe the selection rule and the temporary-directory check. There is also a CHANGELOG entry.
• Changelog lint. Super-linter's MD013 (400 columns) checks every changed Markdown file in full. The gate landed (chore: adopt external static-analysis gates #1005) after the changelog was last edited, and nearly every entry is a single line longer than 400 columns, so any PR that adds a changelog entry fails "External static analysis" (this PR's first push failed with 43 MD013 errors, almost all on lines it did not touch). CHANGELOG.md now has <!-- markdownlint-disable MD013 --> right after its title. That is the same hunk refactor(artifacts): delete never-dispatched gates, production-dead code, and the unread event index #1181, fix(runtime): name the runner error when a workflow fails with no failed node, and pin same-id recovery #1172 and fix(runtime): resume --retry-failed reopens descendants skipped behind a recovered producer #1169 add, so merging any of them together leaves one directive. The implementer checked locally with super-linter's v8.7.0 markdownlint config that line length is the only rule the file breaks, and "External static analysis" passes on this head with the directive in its new place.

Deliberately not built (and why)

• Per-file fsync is not removed entirely. The earlier analysis measured that as the larger win, but without it a crash mid-publication needs a "republish on verification failure" path to stay safe. This change keeps publication's durability exactly as it was.
• Snapshots are not retired, and node_modules is still copied. That is Re-evaluate sealed execution snapshots: cost/benefit after repeated campaign losses #921's open design decision, not a hygiene fix.
• doctor does not clean up controller roots. A native resume keeps its root for the detached engine, so deleting roots safely would need liveness tracking.
• The controller-root size scan is not bounded. It walks each ultrafuzz-controller-* directory. On this host the reviewers measured 1.3 s (warm cache) for 20 retained roots (495,000 entries, 5.0 GiB) and 1.6 s for 23 roots (585,000 entries, 5.9 GiB). The scan grows with the roots it reports, and I left it as is.
• No write-side size check for the seal. The seal file is still read under the 64 MiB workflow-control file cap. On the test fixture, the seal for 12,551 execution files measured 5.3 MB in the implementer's run and 5.5 MB in a reviewer's (426 to 440 bytes per entry, with long worktree source paths). Extrapolated to the 100,000-entry schema bound, that is about 43 to 44 MB, so only unusually long paths would exceed the cap. I have not seen that happen, and a guard would be one more fail-closed layer.
• The seal test does not pin 400,000. It fills execution_files to its bound (100,005 items in all), which fails on main but would pass with any limit of at least 100,005. Filling the three identity arrays as well would pin the figure, but that test ran for 85 s (see the validation-cost risk below), so the 400,000 figure rests on the schema arithmetic in the code comment.
• The execution-dependency map gets the shared limit and nothing more. Its schema's array total (10,000 + 100,000 + 110,001 + 100,000 = 320,001 items) now fits. Its property total is not bounded by the schema, because issuer dependencies objects have no maxProperties. I did not measure a real map, and I did not audit the other runtime schemas' totals.
• Continuations are still rendered where they were. Moving them under the run root would change paths Smithers records and the adapters' relative imports. Excluding the directory is a one-line change.
• The fsync test keeps its own launch instead of sharing the adjacent recovery test's, so each test checks one property. It costs one more startRun (the test took 13 s here under eatmydata).
• The five doctor tests that start a run first are not converted to init-only fixtures. They do not need a launch, and converting them would save CI time, but that is out of scope.

Verification

Each new test below fails on origin/main (b6dd1da9) and passes on this branch. For the main runs I copied this branch's test files into a main worktree and compiled them against main's sources.

Test	origin/main	this branch
publishing an execution snapshot flushes each file once (runtime.test.ts; counts fsyncs of regular-file descriptors)	fails: 25104 file flushes for 12552 files (27876 flushes in all)	passes: 12552 file flushes for 12552 files (15324 flushes in all)
a control seal at its schema's execution-file bound parses back	fails: StrictJsonError: JSON exceeds the item limit of 100000	passes (~0.5 s)
a refreshed controller rendered into the target leaves its governed identity unchanged	fails: dirty: true, and the worktree digest differs	passes
diagnoseProject requires only the CLIs of agents the selected topology can dispatch to	fails: toolchain 'error' !== 'ok'	passes; also checks a [retry] agents fallback, the toolchain summary count, and codex staying required in both directions (Codex selected beside an unused OpenRouter profile, and OpenRouter selected beside an unused Codex profile)
diagnoseProject reports controller roots in the temporary directory and leaves them in place	fails: no temporary-directory check (empty summary)	passes
diagnoseProject warns, without failing, when the temporary directory is RAM-backed (real tmpfs at /dev/shm; skipped where that is not tmpfs)	fails: check status undefined, expected warning (ran, not skipped)	passes (ran, not skipped)
diagnoseProject warns when the temporary directory has little free space (fs.statfsSync mocked)	fails: check status undefined, expected warning	passes
CLI doctor reports install posture in human and JSON output (adds a (not required) assertion for kimi)	fails: no - kimi: missing from execution environment (not required) line	passes

Mutation checks on this branch's compiled doctor.js, each run against the selection test:

• Restoring the old summary line (${toolchain.length} required commands) fails it: '7 required commands available in the configured execution environment' does not match /^4 required commands available /.
• Making the shared-CLI merge last-writer-wins (requiredByName.set(name, required)) fails it at the new "Codex beside an unused OpenRouter profile" assertion. Review found that the earlier version of the test passed under this mutant.

Also run on this branch, all passing:

• All 10 snapshot tests (the snapshot recovery, materialization, publication and writes tests plus the fsync test). The leaf-swap test is renamed to snapshot writes reject a swapped leaf without touching the outside file, since its hook now fires on the write-time fchmod. The parent-swap test's hook now fires only on a directory fchmod, so the swap lands in the directory seal after every file is written, as it did on main. I confirmed that from its diagnostic, an ENOENT from lstat of the temporary snapshot's .smithers/agents directory, which the seal checks right after its fchmod. Both swap tests also pass on main.
• All 16 diagnoseProject tests, including the five that start a run.
• The target identity tests in data-governance.test.ts, and all 5 runtime document contract tests.
• prettier --check and eslint on the changed files, CI=1 ESLINT_PLUGIN_DIFF_COMMIT=origin/main pnpm -w lint:strict:ci, pnpm --filter typecheck for runtime and cli, pnpm -w knip, and node scripts/docs-check.mjs.

Test runs used eatmydata except where noted.

Wall-clock, from the implementer's runs without eatmydata on this shared host (about 25 other agents' test runs, load average 22 to 41): republishing the fixture snapshot took 2,008 s on origin/main for 27,876 fsyncs and 855 s on this branch for 15,324. The startRun launches inside those two tests took about 21 minutes each, but under different host load, so they are not a controlled comparison. A reviewer's micro-benchmark under eatmydata (6,000 files, 8 alternating samples each) had medians of about 480 ms on main and 320 ms on this branch. On GitHub runners, CI shard 1 logged the fsync test's republish at 17,269 ms on the earlier push and at 10,557 ms on this one (12552 file flushes for 12552 files (15324 flushes in all, 10557 ms)). The release-validation lanes took 23 to 31 minutes on the earlier push and 24.5 to 34 minutes on this one, about the same as the lanes of #1161 and #1157 (23 to 30 minutes). I found no measurable CI speedup on GitHub's runners and do not claim one.

CI on d1cc424c is all green: the build and Node 24 smoke, External static analysis, the five release-validation lanes (runtime.test.ts shards 1 to 4 plus the supporting test files and the Bun adapter contracts) and release-gates.

Not run: the full CLI suite (CI runs it only on pushes to main); locally I ran only the CLI doctor test.

Risk / compatibility

• Snapshots. Only new publications change. Already-published generations and their verification are untouched. A umask that masks creation bits is handled by the descriptor fchmod. The seal no longer reopens files, and the verification pass that follows still rejects a swapped or unexpected entry.
• doctor JSON gains a temporary-directory entry in checks. The CLI result schema already allows any check name, and a warning does not change ok. A project that was "needs attention" only because unselected agents' CLIs were missing now reports healthy, which is the intent. doctor still does not know about a one-off ultrafuzz run --agent X.
• Governance. Files under .smithers/continuations no longer count toward the target identity. Only resume --refresh-controller writes there, and the exclusion is read only at launch. No disclosure acknowledgement needs recomputing: acknowledgements are required only for private campaigns, a private campaign already rejected a target dirtied by continuation files, and a target whose only untracked files were continuations now gets its clean-target digest back.
• Runtime document parsing accepts up to 400,000 items in any runtime document instead of 100,000. This does not let an invalid document through: schema validation still applies each schema's own maxItems. It changes how much work happens before an oversized document is rejected. Memory stays bounded by the unchanged 128 MiB parse cap, but the validator runs with allErrors: true, so the quadratic uniqueItems check below still runs on an array that is over its maxItems. A corrupt document with up to 400,000 items in such an array therefore costs more CPU to reject than one cut off at 100,000. The seal needs the 400,000 limit under either design, and its identity arrays are such arrays.
• Seal validation cost (pre-existing, not changed here). While trying to pin the 400,000 figure I found that schema validation of the seal's three identity arrays grows quadratically. With 30,000 identities per array, the runtime's validation took 6.1 s (0.76 s at 10,000). In a plain Ajv 2020 check of the same document, removing uniqueItems from identityArray took it from 6.6 s to 4 ms. The semantic gate already checks those arrays for uniqueness and order in linear time, as it does for execution_files, whose schema dropped uniqueItems in fix(runtime): keep execution-file validation linear #959 ("validate execution file uniqueness linearly"). Changing the schema changes its digest, so I left it. These arrays grow with the workflow's node count (the fixture's one node contributes one state ID, one attempt ID and three task node IDs); I did not measure a real campaign's seal.

Refs #921

🤖 Generated with Claude Code

Confidence Score: 4/5

The PR does not appear ready to merge because removing the changelog exception is expected to fail Markdown validation.

Findings

1.  Unbounded controller size scan ▶
2.  Non-seal item limit increased ▶

Fix with agent prompt

### Issue 1
packages/runtime/src/doctor.ts:undefined-245
Every `doctor` invocation walks all `ultrafuzz-controller-*` directories to total their file sizes, including the installed dependencies in retained controller roots. After several native resumes, this synchronous scan can make a readiness check increasingly slow even when temporary storage has ample space. Consider bounding the scan or making size collection optional.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

### Issue 2
packages/runtime/src/runtime-document-codec.ts:undefined-32
The control seal needs the higher limit, but this shared parser now allows up to 400,000 items for every runtime document instead of 100,000. For example, a dependency map with more than 100,000 issuers can pass parsing and require more work from later validation. Keep the higher limit specific to control seals so other documents retain their previous bound.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR reduces execution-snapshot file flushes, narrows doctor’s required agent CLIs to selected agents, adds temporary-directory diagnostics, excludes refreshed controllers from governed target identity, and raises the runtime-document parse limit.

• The latest changes remove both the changelog’s MD013 exception and this PR’s release note.

_{Reviews (5) · Last reviewed commit: "chore: move the changelog entry to the c..."}

[greptile-apps]

Unbounded controller size scan Every doctor invocation walks all ultrafuzz-controller-* directories to total their file sizes, including the installed dependencies in retained controller roots. After several native resumes, this synchronous scan can make a readiness check increasingly slow even when temporary storage has ample space. Consider bounding the scan or making size collection optional.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/runtime/src/doctor.ts
Line: 245

Comment:
**Unbounded controller size scan** Every `doctor` invocation walks all `ultrafuzz-controller-*` directories to total their file sizes, including the installed dependencies in retained controller roots. After several native resumes, this synchronous scan can make a readiness check increasingly slow even when temporary storage has ample space. Consider bounding the scan or making size collection optional.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

Non-seal item limit increased The control seal needs the higher limit, but this shared parser now allows up to 400,000 items for every runtime document instead of 100,000. For example, a dependency map with more than 100,000 issuers can pass parsing and require more work from later validation. Keep the higher limit specific to control seals so other documents retain their previous bound.

Knowledge Base Used: Execution runtime

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/runtime/src/runtime-document-codec.ts
Line: 32

Comment:
**Non-seal item limit increased** The control seal needs the higher limit, but this shared parser now allows up to 400,000 items for every runtime document instead of 100,000. For example, a dependency map with more than 100,000 issuers can pass parsing and require more work from later validation. Keep the higher limit specific to control seals so other documents retain their previous bound.

**Knowledge Base Used:** [Execution runtime](https://app.greptile.com/monad-foudnation/-/custom-context/knowledge-base/monad-developers/ultrafuzz/-/docs/execution-runtime.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!