[dobleuber]

Document the matching N|Solid Console MCP contract: tenantless tools, bounded list results and omission metadata, app-scoped reads, cursor-page retries, the settings/config alias and expression limits.

The skill updates stay limited to those contract changes. Runtime and crash guidance is concise; broader advisory-platform, REST-inventory, replacement-authorization and uncertain-save procedures are deferred to separate review.

The macOS process-group fix is separated into #84 (fix/macos-runtime-reaping) so it can merge independently. This documentation branch is based on that fix to keep its own diff limited to skill guides.

Requires the matching N|Solid Console MCP server release before merging.

Validation: unchanged skill frontmatter and original Guardrails, plugin and marketplace asset synchronization, whitespace checks, lint, build and the complete local test suite. Native Claude /review high and codex review completed on the full documentation layer and its final clarification delta; the coordinator independently checked their findings. Local validation includes 738 passing tests; remote CI is checked on the published HEAD.

[ns-control-tower]

Walkthrough

This revision is documentation-only: 18 N|Solid skill guides (+48/−38 across 14 commits) now describe the matching Console MCP contract — bounded list results (read total, returned, truncated, more, totalAtLeast, appsOmitted and any outputCut/cut notice before concluding; an omission is never proof of absence or health), app-scoped reads when the app is known, cursor-page retry at a lower limit, the tools that take no tenant (list_tenants, expression_help, vulnerability_data, list_alert_starters), the settings/config alias, byApp's 25-app default and refused arguments, list_runtimes capping at 20 apps per version, and partial-result caveats for list_vulnerabilities and list_alert_rules.

The macOS cancelManagedTree fix and its tests are no longer part of this diff — they now live in #84 (fix/macos-runtime-reaping), which this branch is stacked on as its base. Commit dd97a8c trimmed the previously out-of-scope additions back to the list/tenant contract; 1f970f3 tightened the omission and partial-result wording.

PR-Lens: the earlier overview/termination-flow diagrams described a head that still included the macOS runtime fix; that fix now lives in #84 and this revision is documentation-only, so no flow diagram is attached.

Assessment

Addressed since the last review round (verified in the diff):

• ✔ Scope trimmed to the requested items — tenant lines, the Bounded Lists section (skills/ns-fleet-health/SKILL.md:12), omitted-app notes (skills/ns-analyze-tracing/SKILL.md:16, skills/ns-generate-sbom/SKILL.md:16), one-line caveats (skills/ns-fleet-health/SKILL.md:24-25, skills/ns-node-upgrade/SKILL.md:39, skills/ns-analyze-vulnerabilities/SKILL.md:12, skills/ns-manage-alerts/SKILL.md:9), the cursor-page retry, and the settings/config alias (skills/ns-configure-agents/SKILL.md:17).
• ✔ macOS fix split out — now PR fix: wait for macOS process group reaping before runtime cleanup #84; this PR's base is fix/macos-runtime-reaping, and the fix and its tests are unchanged from the previously reviewed revision (git diff c4772216 eb30b9a -- packages/ is empty).
• ✔ PR description rewritten — documents the split, the stack, and the server-release gate; the stale "no runtime code changed"/draft wording is gone.
• ✔ Previous inline suggestions adopted — the two ns-fleet-health suggestions from the last round are reflected in the current wording (skills/ns-fleet-health/SKILL.md:21-25; both threads are outdated at this head).

Validation at this head:

• ✔ CI: test run #180 — ubuntu-latest, macos-latest and windows-latest jobs all passed (lint, build, full test suite, marketplace-install script).
• ✔ git diff --check clean; skill frontmatter untouched (all hunks are body-only); no runtime code, workflows, dependencies or data in the diff.
• ℹ️ The guides describe the N|Solid Console MCP contract; that contract cannot be verified from this repository, so the claims were checked for internal consistency only. The PR is gated on the matching server release.
• ℹ️ This PR is stacked on fix: wait for macOS process group reaping before runtime cleanup #84 (currently a draft): sequence the merges with fix: wait for macOS process group reaping before runtime cleanup #84 first.

Verdict: APPROVE — no blocking correctness, security or performance findings. A clean, documentation-only head with all follow-ups from the previous review round addressed and CI green on all three OS jobs.

[brycebaril]

Thanks, this gets the server's list limits and its stricter tenant argument into the skills. I checked the facts it states against the server change, and they hold:

• list_tenants, expression_help, vulnerability_data and list_alert_starters take no tenant.
• list_apps defaults to 50 apps, and byApp to 25.
• List results stay within 20,000 bytes, and outputCut names what was left out.
• list_alert_rules returns a bare array.
• The expression limits and the settings-or-config alias are right.

Requesting changes for scope, in two parts.

The skills. The PR adds about 2,800 words to the skills, and most of it isn't about the list limits:

• ns-fleet-health goes from 716 words to 1,607. Its Node.js runtimes bullet grows from one line to 476 words: platform qualifiers, pooled advisories, paging through the REST agent inventory, and a task budget. Its crashes bullet is 270 words.
• ns-node-upgrade gets the same runtime procedure, about 500 words.
• ns-configure-agents (about 660 words) and ns-manage-alerts (about 560) get new rules: when a name counts as free, what counts as a go-ahead to replace a config or rule, and what to claim after a timeout.

These are new policies, not follow-ups to the list cap, and each deserves a review of its own. They also load on every run, and ns-fleet-health is usually the first skill people run.

Please keep this PR to what the server change does:

• the tenant lines, as they are;
• the Bounded Lists section in ns-fleet-health;
• the notes on omitted apps in ns-analyze-tracing and ns-generate-sbom;
• one sentence each for:
  • byApp's limits and refusals;
  • list_runtimes' 20 apps;
  • partial list_vulnerabilities results;
  • a cut list_alert_rules: a name it doesn't show isn't proof the name is free;
  • the cursor-page retry;
• the settings-or-config alias.

The rest can go in PRs of their own.

The macOS fix. The two cancelManagedTree commits are right. On macOS, probing a process group whose members are all zombies returns EPERM until they're reaped. The fix keeps polling for ESRCH within the same deadline and never confirms on EPERM, and the new tests cover both cases.

But the fix is independent of this change, and it's needed now. The same EPERM failure, in "terminates the whole managed tree (grandchild included) before resolving", failed the macOS job twice here. It also failed main on 10-26 (run 40378567904) and #78. This PR has to wait for the server change, but the fix doesn't. Please open it as its own fix: PR so it can merge first, then rebase this one on it.

The description says no runtime code or bundled scripts changed, but mcp-runtime-runner.ts does until the fix moves out. It also says the PR stays a draft until the server contract is ready. It's out of draft now, but the server change hasn't merged, so this still has to wait for it.

[brycebaril]

Thanks, this now covers what the server change does, and nothing more. It adds about 580 words instead of 2,800, and ns-fleet-health grows by 255 words instead of 891. Both suggestions are in.

I checked the new sentences against the server, and they hold:

• byApp's arguments and its 25-app default;
• list_apps' default of 50;
• the settings/config alias;
• the expression limits.

It merges after #84, and after the server change ships.