@rubytech/create-sitedesk-code 0.1.514 → 0.1.515

package/payload/platform/docs/superpowers/specs/2026-07-27-task-2016-disabled-agent-routing-design.md

@@ -0,0 +1,139 @@
+# Task 2016 — a disabled agent must leave the admin's routing table, and read as disabled rather than missing
+
+Design, 2026-07-27. Depends on Task 1996 (landed).
+
+## The defect
+
+Task 1996 stops dispatch by moving an agent file out of `<accountDir>/specialists/agents/`,
+the directory `spawn-context.ts` reads to build the spawn manifest. Two surfaces still
+believe the file is there.
+
+`platform/scripts/lib/agents-md-bootstrap.sh:42-47` only ever appends. A line matching
+`^- \*\*specialists:<name>\*\*:` in `agents/admin/AGENTS.md` is preserved verbatim and a
+missing one is appended; nothing is ever removed. So the admin's routing prose keeps
+advertising a specialist the operator switched off, and dispatch fails inside a turn
+against a file that is gone.
+
+`platform/plugins/admin/mcp/src/index.ts:520-533` walks the AGENTS.md entries against
+`specialists/agents/` and calls a name with no file `missing file`. An operator action is
+rendered as an install fault.
+
+## What the fix delivers
+
+1. A name the operator disabled has no routing line.
+2. Re-enabling restores it.
+3. `system-status` reports `disabled` and `missing file` as different things, and counts
+   them separately.
+
+## Surface 1 — `agents-md-bootstrap.sh` reconciles
+
+The store is `<accountDir>/agents-disabled.json`, `{ "disabled": ["<basename>.md", …] }`,
+written whole at 0600 by `platform/ui/server/routes/admin/agents.ts`. The bootstrap reads
+it with the same python3 extractor `provision-account-dir.sh:264-276` already uses, which
+accepts only strings ending `.md` with no `/` and no `..`.
+
+**The name rule.** A store entry maps to a routing line by stripping `.md`. One rule, no
+branch: all twelve files under `platform/templates/specialists/agents/` have `name:` equal
+to their filename, the disable route keys on `slug` equal to the basename, and the status
+walker at `index.ts:526` already maps a name back to `<name>.md`.
+
+**The reconcile rule.** A name in the store gets no routing line. It applies at both points
+in the script: an existing line for that name is removed, and the append loop skips that
+name. Stating it once and applying it uniformly is what makes the invariant hold in the
+drift state the standing `op=agent-parity` check exists to catch (store names it, file is
+still live) rather than only on the happy path.
+
+**An unreadable store withholds nothing.** `provision-account-dir.sh:293` already prints
+`specialists agents-disabled-store-unreadable — withholding nothing` and carries on, so
+the prose posture matches the file-withholding posture that runs immediately before it.
+
+**Observability.** The existing line stays byte-identical, because the current suite
+asserts its counts:
+
+```
+  [admin-bootstrap] AGENTS.md specialists=<n> appended=<m> existing=<k>
+```
+
+A second line is added:
+
+```
+  [agents-md] op=specialist-lines account=<id8> kept=<n> withheld=<comma-list|none|store-unreadable>
+```
+
+`id8` is the first eight characters of the account directory's basename. `kept` counts the
+`- **specialists:` lines in AGENTS.md after the run. `withheld` names the store's entries,
+sorted, as names rather than basenames; `none` when the store is absent or empty; the
+literal `store-unreadable` when it is present but does not parse.
+
+## Surface 2 — `system-status` separates disabled from missing
+
+The classification at `index.ts:520-533` moves into a new
+`platform/plugins/admin/mcp/src/specialist-registry.ts`, beside `skill-resolution.ts` and
+`store-skill-core.ts`, which are the same shape: a module `index.ts` imports and a
+`node:test` suite covers. It exports one function taking the AGENTS.md text, the
+specialists directory, the account directory and whether Chrome is up, and returning the
+per-name lines plus the two counts.
+
+Status, in order:
+
+- the file exists in `specialists/agents/` → `ok`, except `personal-assistant` with Chrome
+  down, which keeps today's `degraded — chrome not running`;
+- otherwise the name is in the store → `disabled (operator)`;
+- otherwise → `missing file`.
+
+The header becomes `<n> registered, missing=<x> disabled=<y>`. An unreadable store is
+tolerated the same way the bootstrap tolerates it: no names classify as disabled, and the
+absent file stays `missing file`, which is the honest answer when the store cannot be read.
+
+With surface 1 in place a disabled agent has no AGENTS.md line at all, so in the steady
+state `disabled=0`. The classification earns its place in the drift window: an account
+disabled before this change carries the stale line until a provisioning run or a
+disable/enable call reconciles it, and that is exactly when the operator needs the line to
+read `disabled` rather than `missing file`.
+
+## Surface 3 — the disable path reconciles immediately
+
+`agents.ts` currently leaves AGENTS.md untouched, so prose is only correct after the next
+provisioning run. After the file move and the store write, both handlers exec
+`bash <PLATFORM_ROOT>/scripts/lib/agents-md-bootstrap.sh <accountDir>` with a timeout.
+`platform/scripts` ships in the payload (`packages/create-maxy-code/scripts/bundle.js:318`
+copies the whole `platform` tree minus the listed exclusions), and `claude-info.ts:33`
+is the precedent for `execFileSync` in an admin route.
+
+Enable needs no separate restore path. The file is live again by the time the script runs,
+so the append loop puts the line back and the store no longer names it.
+
+**Failure posture.** A failed exec does not turn the request into a 500: the file move and
+the store write already happened, and dispatch is already stopped, so reporting the whole
+disable as failed would be false. The handler logs
+`[admin/agents] op=agents-md-reconcile accountId=<id8> slug=<slug> outcome=failed reason="…"`
+and the response carries `routingReconciled: false`, so no caller is told the prose is
+correct when it is not.
+
+## Tests
+
+**Shell, `platform/scripts/__tests__/agents-md-bootstrap.test.sh`.** Against the existing
+three-specialist temp account: a store naming one of them leaves no line for it and keeps
+the other two, and the `op=specialist-lines` line reports `kept=2 withheld=<that name>`;
+clearing the store restores the line on the next run; a malformed store removes nothing and
+reports `withheld=store-unreadable`. The pre-existing cases run unchanged with no store on
+disk.
+
+**Route, `platform/ui/server/routes/admin/__tests__/agents.test.ts`.** The harness mocks
+`PLATFORM_ROOT` to a temp tree; the real bootstrap script is copied into
+`<platformRoot>/scripts/lib/` so the exec runs the shipped code rather than a stub. A
+disable leaves no `specialists:<name>` line in the account's AGENTS.md; the following
+enable puts it back.
+
+**MCP, `platform/plugins/admin/mcp/src/__tests__/specialist-registry.test.ts`
+(`node:test`).** A temp account with three AGENTS.md entries: one live file, one named by
+the store, one neither. Asserts `ok`, `disabled (operator)`, `missing file`, and
+`missing=1 disabled=1`. A `missing file` line for a name in the store is a failure.
+
+## Out of scope
+
+- The disable mechanism, the quarantine directory, and the store format (Task 1996).
+- What AGENTS.md is for, and its append-only posture for anything that is not a specialist
+  routing line.
+- The `op=agent-parity` check, which already covers store-versus-directory drift.
+- `AGENTS.md` write permissions, which is Task 2057.

package/payload/platform/plugins/admin/mcp/dist/index.js

@@ -21,6 +21,7 @@ import QRCode from "qrcode";
 import { getSession, closeDriver } from "./lib/neo4j.js";
 import { findSkillOwners, searchSkills, computePluginReadHint, loadSkill, parseRequiredInputs, adminAuthoringSkillBlock, skillSlugFromReadArgs, AUTHORING_DISPATCH_HINT } from "./skill-resolution.js";
 import { storeSkillToAccount } from "./store-skill-core.js";
+import { classifySpecialists } from "./specialist-registry.js";
 import { resolvePublicHostname } from "./lib/public-hostname.js";
 import { resolveAdminHostname } from "./lib/admin-hostname.js";
 import { publishSite } from "./tools/publish-site.js";
@@ -434,25 +435,22 @@ eagerTool(server, "system-status", "Check health of all SiteDesk platform servic
         }
         else {
             const content = readFileSync(agentsMdPath, "utf-8");
-            const entries = content.match(/^- \*\*specialists:([^*]+)\*\*/gm);
-            if (!entries || entries.length === 0) {
+            // Task 2016 — `missing` and `disabled` are different answers. An agent
+            // the operator switched off has no file here by design, and reporting
+            // that as a fault trains the operator to ignore the real ones.
+            const report = classifySpecialists({
+                agentsMd: content,
+                specialistsAgentsDir,
+                accountDir,
+                chromeUp,
+            });
+            if (report.registered === 0) {
                 checks.specialists = "not configured (AGENTS.md empty)";
             }
             else {
-                const lines = [];
-                for (const entry of entries) {
-                    const nameMatch = entry.match(/specialists:([^*]+)/);
-                    if (!nameMatch)
-                        continue;
-                    const name = nameMatch[1];
-                    const fileExists = existsSync(join(specialistsAgentsDir, `${name}.md`));
-                    let status = fileExists ? "ok" : "missing file";
-                    if (name === "personal-assistant" && !chromeUp) {
-                        status = "degraded — chrome not running";
-                    }
-                    lines.push(`  ${name}: ${status}`);
-                }
-                checks.specialists = `${entries.length} registered\n${lines.join("\n")}`;
+                checks.specialists =
+                    `${report.registered} registered, missing=${report.missing} disabled=${report.disabled}\n` +
+                        report.lines.join("\n");
             }
         }
     }