specguard-mcp 0.1.2 → 0.1.4

package/README.md

@@ -11,9 +11,9 @@ its prompt.
 SpecGuard is built [primarily for AI coding agents](https://github.com/yatfa-ai/specguard); this
 bridge is how an agent reaches it without scraping a web UI.
 
-> **Status: bootstrap.** Three tools ship today, each wrapping a capability that already exists. The
-> toolset **grows gradually** — see [Adding a tool](#adding-a-tool). It is not published to npm yet;
-> install from a checkout.
+> **Status: bootstrap.** A small set of tools ships today, each wrapping a capability that already
+> exists — see [The tools](#the-tools) for what is in it. The toolset **grows gradually** — see
+> [Adding a tool](#adding-a-tool). It is not published to npm yet; install from a checkout.
 
 ## Install
 
@@ -32,9 +32,9 @@ refuses to boot and takes the tools that needed no configuration down with it.
 
 | Variable | Needed by | Default | What it is |
 | --- | --- | --- | --- |
-| `SPECGUARD_ENDPOINT` | `get_repository_overview`, `list_repositories` | — | your SpecGuard instance's root URL, **including the scheme** — e.g. `https://specguard.example.com`, or `http://localhost:3000`. A value with no scheme is refused by name (`SPECGUARD_ENDPOINT is not a usable URL: "sg.example.com"`) rather than surfacing later as an opaque failure. `SPECGUARD_URL` is accepted as an alias, and is the name every message uses when it is the one you set. A blank value counts as unset, so leaving `SPECGUARD_ENDPOINT` empty in a templated config falls through to `SPECGUARD_URL` instead of suppressing it |
+| `SPECGUARD_ENDPOINT` | `get_repository_overview`, `list_repositories`, `add_repository`, `registrable_repositories` | — | your SpecGuard instance's root URL, **including the scheme** — e.g. `https://specguard.example.com`, or `http://localhost:3000`. A value with no scheme is refused by name (`SPECGUARD_ENDPOINT is not a usable URL: "sg.example.com"`) rather than surfacing later as an opaque failure. `SPECGUARD_URL` is accepted as an alias, and is the name every message uses when it is the one you set. A blank value counts as unset, so leaving `SPECGUARD_ENDPOINT` empty in a templated config falls through to `SPECGUARD_URL` instead of suppressing it |
 | `SPECGUARD_API_KEY` | `get_repository_overview` | — | an agent/CI API key (`sgk_…`) issued by that deployment |
-| `SPECGUARD_USER_API_KEY` | `list_repositories` | — | a **user** API key (`sgu_…`), minted from that deployment's account page. A different credential from the one above, not a second place to put the same value: SpecGuard decides which of them a request may use from the token's prefix, before it reads anything, and answers `401` for the other one. Set whichever your tools need — both, if you use both |
+| `SPECGUARD_USER_API_KEY` | `list_repositories`, `add_repository`, `registrable_repositories`, `remove_repository`, `create_repository_api_key`, `revoke_repository_api_key` | — | a **user** API key (`sgu_…`), minted from that deployment's account page. A different credential from the one above, not a second place to put the same value: SpecGuard decides which of them a request may use from the token's prefix, before it reads anything, and answers `401` for the other one. Set whichever your tools need — both, if you use both |
 | `SPECGUARD_LINT_COMMAND` | `lint_intent_annotations` | `specguard-lint` | the command that runs the linter. Most Ruby projects need `bundle exec specguard-lint` |
 | `SPECGUARD_TIMEOUT_MS` | HTTP tools | `30000` | how long a call to SpecGuard may take |
 
@@ -109,7 +109,7 @@ branch window rather than between the last two runs.
 | `repeated_description` | open ONE repeated description and list the examples that all share it |
 | `unstable_test` | open ONE flaky test and list its outcome run by run across the window, newest run first (needs `branch`) |
 | `commit_sha` | anchor the answer on ONE named run instead of the repository's newest one — every run-grain block moves with it, `history` does not |
-| `unannotated_examples` | `true` to list the individual tests SpecGuard cannot see — the examples behind the annotated ratio — and, in the same answer, which areas carry the most of them |
+| `unannotated_examples` | `true` to list the individual tests carrying no `@intent` — the examples behind the annotated ratio, each labelled with what SpecGuard reads of it — and, in the same answer, which areas carry the most of them |
 
 `branch` narrows `history` only — `latest_run` always names the repository's newest run, which on a
 busy repo may be on another branch. That is a property of the endpoint, not of this bridge — and
@@ -210,9 +210,23 @@ description carried by two examples in one run contributes two, so `rows` is not
 and its length is not the window's `run_count`.
 
 `annotated_ratio` is the product's adoption metric and it was the one population on this endpoint
-you could not walk down: the dashboard prints *"SpecGuard cannot see the other N tests"* and could
+you could not walk down: the dashboard printed *"SpecGuard cannot see the other N tests"* and could
 not name one of them either, so an agent told to raise annotation coverage learned how far it had to
-go and not a single test to annotate. `unannotated_examples` is that rung. It is the one argument
+go and not a single test to annotate. `unannotated_examples` is that rung.
+
+**Unannotated is not the same as unreadable, and the difference is on every response.** A test
+called `Invoice#total sums the line items` has an entity, an action and a behavior in its own
+description, so SpecGuard reads it whether or not anybody annotated it.
+`latest_run.intent_readings` splits the run's examples into `authored` (an `@intent` a human wrote),
+`derived` (read from the description) and `unreadable` (neither), with the `recorded` population
+they were counted from — no flag to pass. **`unreadable` is the only figure on this endpoint that
+means tests SpecGuard can say nothing about.** `total_specs - annotated_specs` is annotation debt,
+which on a suite that has never been annotated is the whole suite and almost all of it readable;
+never render that subtraction as blindness. A derived reading is genuinely weaker than an authored
+one — no preconditions, a behavior written for a test runner's output rather than declared, and a
+layer inferred from the directory — so report it as inferred and never as equivalent. And
+`authored` never replaces `annotated_ratio`: "how much of this suite has a human-written intent" is
+still that figure, off the run's own counters. It is the one argument
 here that is a **flag rather than a name** — pass `true`, not a value — because it opens a
 *population* rather than a pick: `total_specs` minus `annotated_specs` is a subtraction, and a
 subtraction has no line to name. Which population is still yours to choose: sent alone the flag
@@ -220,8 +234,10 @@ opens the whole run, and sent **together with** `spec_file` or `spec_directory`
 file, that area, or the AND of the two — those two keep opening their own blocks as well, so
 narrowing this one is additional rather than instead. `latest_run.unannotated_examples` opens with
 up to 100 of the unannotated examples **of whatever you asked for** (`name`, `file_path`,
-`line_number`, `spec_file_path` each — four fields, not the per-example drill-ins' six), plus that
-same population's own `recorded_count`, the `limit` the row list was cut at, and
+`line_number`, `spec_file_path`, `reading` and `derived_intent` each — six fields, and not the
+per-example drill-ins' six: no `duration_seconds` and no `outcome`), plus that
+same population's own `recorded_count`, `derived_count` and `unreadable_count`, the `limit` the row
+list was cut at, and
 `spec_file`/`spec_directory` **echoed back** as the server read them — `null` for each one you did
 not send. Read the echo before the count: the **worklist's** `recorded_count` — and only that one,
 because the map below deliberately does not narrow — is the figure you would reconcile against
@@ -235,13 +251,20 @@ That one ask opens **two** blocks, each in its own grain: `latest_run.unannotate
 *which tests* to go and annotate, and `latest_run.unannotated_directories` for *where the debt is* —
 the run's annotation debt rolled up by code area, which is what you pick the next `spec_directory`
 narrowing **from**. Both come from the one flag; there is no second argument to send and no new
-value. The map's rows carry `path`, `unannotated_count` and the `recorded_count` that area was
-counted against (the operands, never a fraction), plus `directory_count` — **every** area the run
+value. Each worklist row carries `reading` — `"derived"` or `"unreadable"` — and `derived_intent`,
+the `entity`/`action`/`behavior` SpecGuard got from the description or `null`; the **unreadable rows
+come first**, so the 100-row cap cannot hide them. The map's rows carry `path`,
+`unannotated_count`, the `recorded_count` that area was counted against, and the same three-way
+split — `authored_count`, `derived_count` and `unreadable_count`, which sum to `recorded_count`
+while the last two sum to `unannotated_count` (the operands, never a fraction), plus
+`directory_count` — **every** area the run
 touched, not every area with debt, and not `rows.size` — and its **own** `limit`, which is **10 and
 not the worklist's 100**. Two caps under one ask, and the difference is the kind of list: 100 caps a
 *worklist* to work through, 10 caps a *ranking* to pick from. The orders differ for the same reason —
-the worklist is file-navigable, the map is ranked `unannotated_count` descending with `path` as a
-tiebreak only. A fully-annotated area is a real **row** with `unannotated_count: 0`, never an
+the worklist is file-navigable within each reading, the map is ranked `unreadable_count` descending,
+then `unannotated_count` descending, with `path` as a tiebreak only — the areas SpecGuard cannot
+read lead, because a ten-row ranking led by debt on an unannotated suite is a ranking by area size
+and the dark corners never surface. A fully-annotated area is a real **row** with `unannotated_count: 0`, never an
 omission; those rows sort last *collectively*, so on a run with more areas than the cap they are cut
 and never seen, but on a run inside the cap they *are* listed and listed is correct. So `rows.size` is
 not a count of areas *with* debt — read each row's `unannotated_count`. Both blocks are at run grain,
@@ -328,9 +351,152 @@ decides which table is consulted before any of them is read — so the two are n
 setting one does not stand in for the other. Every message this tool produces names the variable
 *it* reads, so a `401` here never sends you to check the key `get_repository_overview` uses.
 
-Registering a repository, revoking keys and the rest of the user-scoped surface are not here yet.
-`POST /api/v1/repositories` exists on the platform; what this bridge does not yet have is a way to
-send a request body, and that arrives with the first tool that writes.
+Registering a repository is `add_repository`, below — it reads the same `sgu_…` key and takes the
+`full_name` this tool reports. Removal and the key lifecycle (`remove_repository`,
+`create_repository_api_key`, `revoke_repository_api_key`) are below too, on the same key; a tool
+here is a promise the agent will act on, so each waits for the capability rather than the other way
+round.
+
+### `add_repository`
+
+Registers a GitHub repository with SpecGuard for the person behind `SPECGUARD_USER_API_KEY`, and
+returns the repository together with its **first CI API key** — the `sgk_…` key that repository's CI
+will use to ingest runs, minted in the same call so a fresh registration is usable without a second
+trip through the browser.
+
+| argument | |
+| --- | --- |
+| `full_name` | the repository to register, as `org/repo` (for example `acme/billing`) — the same handle `list_repositories` reports. Not a URL, not a bare repository name |
+
+The body comes back as SpecGuard serves it: a `repository` block (`id`, `full_name`, `name`,
+`registered_at` — deliberately the same four fields `get_repository_overview` serves in its own
+`repository` block) and an `api_key` block (`name`, `token`, `hint`, `created_at`).
+
+> ⚠️ **`api_key.token` is shown once and never again.** Nothing stores it and no endpoint can
+> re-serve it. Capture it from this response — an agent should hand it straight to the person it is
+> working for. A key that is lost is replaced from SpecGuard's API-keys page in a browser, not from
+> here.
+
+> ⚠️ **This tool is not idempotent, and it writes.** If the call exceeds `SPECGUARD_TIMEOUT_MS` the
+> bridge gives up, but the registration may still have succeeded on the server — taking its one-time
+> token into a response nobody received. The retry is then refused with `has already been taken`,
+> which is the honest answer rather than a bug. Do not retry a timeout blindly; check
+> `list_repositories`, and recover the key in the browser.
+
+**It needs a current record of your GitHub permissions, and only a browser creates one.** SpecGuard
+decides whether you may register a repository from a stored grant, and fails closed when that grant
+is missing or stale — which is every person who has not signed in and connected GitHub recently. That
+refusal arrives as SpecGuard's own sentence, verbatim, naming the fix: *sign in to SpecGuard in a
+browser and reconnect GitHub, then try again*. No argument to this tool substitutes for it. The same
+path carries the other refusals — a repository the SpecGuard GitHub App is not installed on, one you
+do not administer, one already registered.
+
+**The `org/repo` format is not re-checked here.** This bridge verifies only that you passed a
+non-blank string; SpecGuard validates the name and refuses an unusable one in its own words. A second
+format rule on this side would be free to drift from the one that actually decides, and would surface
+as this bridge rejecting a name the platform would have accepted.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and a
+different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `registrable_repositories`
+
+Lists the GitHub repositories the person behind `SPECGUARD_USER_API_KEY` **could** register with
+SpecGuard — the set the registration gate would consult, read out loud in advance, so an agent can
+pick a `full_name` for `add_repository` from a real answer rather than by guessing. `list_repositories`
+reports what *is* registered; this reports what could be, and the two answer different questions.
+
+The body comes back as SpecGuard serves it: `{"repositories": […]}` with each entry carrying
+`full_name` and `registered`, ordered by `full_name` ascending, plus a `grant` block (`captured_at`,
+`expires_at`, `stale`) describing the stored record of this person's GitHub permissions.
+
+**`registered` is asked globally, not just of your own repositories.** An entry marked
+`registered: true` was registered by *somebody* — possibly someone else — and a POST naming it will
+be refused with `has already been taken`. That is exactly why entries are *marked* rather than
+excluded: a reading scoped to what you can open would send you at a name nobody can register.
+
+**A name appearing here is not a promise the write will succeed.** This is the set the gate would
+consult at the moment of the read; the repository may be registered by someone else between this
+call and your POST.
+
+**A missing or stale grant is not an error — it is the modal first answer.** SpecGuard fails closed
+when it has no current record of your GitHub permissions, which is every person who has not opened
+SpecGuard in a browser recently. The call then answers `403` with SpecGuard's own sentence naming
+the fix: *sign in to SpecGuard in a browser and reconnect GitHub, then try again*. On that refusal
+the body still carries `grant`, and it distinguishes the two cases: `grant: null` means there never
+was one (first-time setup), a populated grant with `stale: true` means an existing connection lapsed
+— same remedy, very different urgency. Read it before telling the person what to do.
+
+**This tool takes no arguments** — the credential is the whole of the scope. The endpoint takes no
+parameters; which repositories are in the answer is decided by SpecGuard from the person the key
+speaks for.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `remove_repository`
+
+Removes a repository from SpecGuard — and with it **every key, run and intent on it**. This is the
+destructive gesture in this toolset: irreversible, no undo, and a `204` means the repository and its
+history are gone short of re-registering from scratch. Confirm with the user before calling.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository to remove — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+
+Authorization is the `repo.delete` capability at **either surface** — an owner, or a member granted
+`repo.delete`, may remove the repository. A member without it is refused `403` with SpecGuard's own
+sentence, verbatim. The repository's CI keys stop authenticating the moment it succeeds.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `create_repository_api_key`
+
+Mints a new CI API key (`sgk_…`) for a SpecGuard repository and returns it alongside the
+repository's existing keys. Minting does not disturb existing keys — each key on a repository
+authenticates independently until revoked.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository to mint the key for — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+| `name` | an optional label for the key; omit it to let SpecGuard use its default name |
+
+The body comes back as SpecGuard serves it: an `api_key` block (`name`, `token`, `hint`,
+`created_at`) — the same shape `add_repository` serves.
+
+> ⚠️ **`api_key.token` is shown once and never again.** Nothing stores it and no endpoint can
+> re-serve it. Hand it to the person you are working for in your reply. If it is dropped, the
+> recovery is minting another key with this same tool — the platform has no regenerate — then
+> revoking the orphaned one with `revoke_repository_api_key`.
+
+Authorization is the `keys_manage` capability; a member without it is refused `403` with SpecGuard's
+own sentence, verbatim.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `revoke_repository_api_key`
+
+Revokes one CI API key on a SpecGuard repository. The key stops authenticating immediately; every
+**other** key on the repository keeps working, so CI keeps ingesting if it holds a surviving key.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository the key belongs to — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+| `key_id` | the id of the key to revoke, as served in the `api_key` block of `add_repository` or `create_repository_api_key` |
+
+The `key_id` is scoped to `repository_id`: a key id belonging to a different repository is refused
+`404`, never a cross-repository delete. Authorization is the `keys_manage` capability; a member
+without it is refused `403` with SpecGuard's own sentence, verbatim.
+
+**Key rotation is mint-then-revoke, in that order.** The platform has no regenerate, so mint a
+replacement with `create_repository_api_key` and deploy it BEFORE revoking the old one — revoke
+first and the repository's CI is locked out until a human mints a new key in a browser. A `204`
+means the key is revoked.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
 
 ## How it works
 

package/dist/bin/specguard-mcp.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "../src/server.js";
+import { installTeardown } from "../src/support/teardown.js";
 /**
  * The stdio entrypoint — the only place a transport is named.
  *
@@ -21,6 +22,10 @@ import { createServer } from "../src/server.js";
  * it.
  */
 async function main() {
+    // Installed BEFORE the transport is connected, so there is no window in which
+    // the server is accepting tool calls — and therefore spawning runs — with no
+    // handler to clean them up.
+    installTeardown();
     const server = createServer();
     await server.connect(new StdioServerTransport());
     process.stderr.write("specguard-mcp: ready on stdio\n");

package/dist/bin/specguard-mcp.js.map

@@ -1 +1 @@
-{"version":3,"file":"specguard-mcp.js","sourceRoot":"","sources":["../../bin/specguard-mcp.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;GAkBG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACjD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;AAC1D,CAAC;AAED,4EAA4E;AAC5E,gFAAgF;AAChF,0EAA0E;AAC1E,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,yBAAyB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CACnG,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"specguard-mcp.js","sourceRoot":"","sources":["../../bin/specguard-mcp.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D;;;;;;;;;;;;;;;;;;GAkBG;AACH,KAAK,UAAU,IAAI;IACjB,8EAA8E;IAC9E,6EAA6E;IAC7E,4BAA4B;IAC5B,eAAe,EAAE,CAAC;IAElB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACjD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;AAC1D,CAAC;AAED,4EAA4E;AAC5E,gFAAgF;AAChF,0EAA0E;AAC1E,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,yBAAyB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CACnG,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/src/support/run-command.d.ts

@@ -68,6 +68,48 @@ export declare const DEFAULT_COMMAND_TIMEOUT_MS = 120000;
  * descriptor costs a truncated tail instead of a call that never returns.
  */
 export declare const EXIT_CLOSE_GRACE_MS = 1000;
+/**
+ * The pids of every run currently spawned and not yet reaped.
+ *
+ * Exported for the teardown handler's diagnostics. A PROJECTION, not the set:
+ * it drops entries whose spawn never produced a process, because a `undefined`
+ * pid is not something a diagnostic can name or a caller can signal.
+ *
+ * That filter makes it the WRONG observer for asserting the set does not leak —
+ * see `outstandingRunCount`.
+ */
+export declare function outstandingRunPids(): readonly number[];
+/**
+ * How many runs are registered, counting those whose spawn produced no pid.
+ *
+ * The unfiltered companion to `outstandingRunPids`, and the one a leak test must
+ * use. The distinction is not pedantic: the spawn-failure path registers a child
+ * whose `pid` is `undefined`, so it is invisible to `outstandingRunPids` BY
+ * EXACTLY THE PROPERTY THAT MAKES IT A LEAK. A test asserting that path through
+ * the pid projection holds whether or not the deregistration happens, and would
+ * stay green if a refactor dropped it.
+ *
+ * The leak is memory-only — `killRun` returns `false` for an undefined pid, so a
+ * stranded entry is skipped by the drain rather than mis-signalled — but it is
+ * one entry per failed spawn for the life of the server, and it is only ever
+ * observable from outside. Hence a reader of the set itself.
+ */
+export declare function outstandingRunCount(): number;
+/**
+ * Kills every run still in flight, and answers how many it signalled.
+ *
+ * The teardown path. SYNCHRONOUS AND UNBOUNDED BY NOTHING — it sends signals and
+ * returns, it never waits for a child to die. That is deliberate: this runs from
+ * a SIGINT/SIGTERM handler, where anything that waits is something that can hang
+ * the shutdown it was supposed to perform. SIGKILL is not refusable, so there is
+ * no acknowledgement worth waiting for.
+ *
+ * It reuses `killRun` rather than re-deriving the kill, so the group-vs-child
+ * fallback and the spawn-failure guard have exactly one implementation. The set
+ * is snapshotted before iterating because `killRun` can drive an `exit` that
+ * mutates it.
+ */
+export declare function killOutstandingRuns(): number;
 /**
  * Runs a program with an argument LIST, never through a shell.
  *

package/dist/src/support/run-command.js

@@ -15,6 +15,95 @@ export const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
  * descriptor costs a truncated tail instead of a call that never returns.
  */
 export const EXIT_CLOSE_GRACE_MS = 1_000;
+/**
+ * The runs that are spawned and not yet reaped.
+ *
+ * This exists because `detached: true` below buys the reach of the timeout kill
+ * and PAYS for it: a detached child is in a new session, outside this server's
+ * controlling terminal, so a signal aimed at OUR group — an interactive Ctrl-C,
+ * a supervisor's `kill -- -PGID` — no longer reaches a lint run in flight. The
+ * run is then orphaned, and orphaned WITHOUT A DEADLINE: the 120s ceiling is a
+ * parent-side `setTimeout`, so killing the parent destroys the only thing that
+ * was going to stop it. On a 20k-example suite that is a full lint's worth of
+ * CPU held by a process attached to nothing. `killOutstandingRuns` is the
+ * teardown path that closes it, and this set is what tells it whom to signal.
+ *
+ * MEMBERSHIP MEANS "NOT YET REAPED", and that is load-bearing rather than
+ * descriptive: `killRun` signals a raw negated pid, which has no liveness check
+ * of its own, so a stale entry is a SIGKILL aimed at whatever recycled that pid.
+ * Entries are therefore removed on the child's own `exit` — the reap — and NOT
+ * at settle, which on the grace-backstop path happens up to EXIT_CLOSE_GRACE_MS
+ * later. Deleting at settle would leave exactly the window in which a drain
+ * would signal a freed pid.
+ *
+ * The accepted consequence is the one this file already takes at `killRun`: a
+ * straggler outliving an already-exited child is not killed at teardown. That
+ * trade is deliberate and is not widened here.
+ */
+const liveChildren = new Set();
+/**
+ * The pids of every run currently spawned and not yet reaped.
+ *
+ * Exported for the teardown handler's diagnostics. A PROJECTION, not the set:
+ * it drops entries whose spawn never produced a process, because a `undefined`
+ * pid is not something a diagnostic can name or a caller can signal.
+ *
+ * That filter makes it the WRONG observer for asserting the set does not leak —
+ * see `outstandingRunCount`.
+ */
+export function outstandingRunPids() {
+    const pids = [];
+    for (const child of liveChildren) {
+        if (child.pid !== undefined)
+            pids.push(child.pid);
+    }
+    return pids;
+}
+/**
+ * How many runs are registered, counting those whose spawn produced no pid.
+ *
+ * The unfiltered companion to `outstandingRunPids`, and the one a leak test must
+ * use. The distinction is not pedantic: the spawn-failure path registers a child
+ * whose `pid` is `undefined`, so it is invisible to `outstandingRunPids` BY
+ * EXACTLY THE PROPERTY THAT MAKES IT A LEAK. A test asserting that path through
+ * the pid projection holds whether or not the deregistration happens, and would
+ * stay green if a refactor dropped it.
+ *
+ * The leak is memory-only — `killRun` returns `false` for an undefined pid, so a
+ * stranded entry is skipped by the drain rather than mis-signalled — but it is
+ * one entry per failed spawn for the life of the server, and it is only ever
+ * observable from outside. Hence a reader of the set itself.
+ */
+export function outstandingRunCount() {
+    return liveChildren.size;
+}
+/**
+ * Kills every run still in flight, and answers how many it signalled.
+ *
+ * The teardown path. SYNCHRONOUS AND UNBOUNDED BY NOTHING — it sends signals and
+ * returns, it never waits for a child to die. That is deliberate: this runs from
+ * a SIGINT/SIGTERM handler, where anything that waits is something that can hang
+ * the shutdown it was supposed to perform. SIGKILL is not refusable, so there is
+ * no acknowledgement worth waiting for.
+ *
+ * It reuses `killRun` rather than re-deriving the kill, so the group-vs-child
+ * fallback and the spawn-failure guard have exactly one implementation. The set
+ * is snapshotted before iterating because `killRun` can drive an `exit` that
+ * mutates it.
+ */
+export function killOutstandingRuns() {
+    const children = [...liveChildren];
+    let signalled = 0;
+    for (const child of children) {
+        // Removed FIRST, so the entry is gone even if the kill throws. A registry
+        // that kept a child it had already tried to kill would hand a second drain
+        // the same stale pid.
+        liveChildren.delete(child);
+        if (killRun(child))
+            signalled += 1;
+    }
+    return signalled;
+}
 /**
  * Runs a program with an argument LIST, never through a shell.
  *
@@ -128,6 +217,11 @@ export const runCommand = (argv, options = {}) => {
         child.stdout.on("data", (chunk) => stdout.push(chunk));
         child.stderr.on("data", (chunk) => stderr.push(chunk));
         child.on("error", (error) => {
+            // The spawn-failure path: there is no process, and `child.pid` is
+            // `undefined`, so this entry can never be a legitimate kill target. Dropped
+            // here because `exit` does not always follow an `error` — leaving it would
+            // strand an unkillable entry in the registry for the life of the server.
+            liveChildren.delete(child);
             finish(() => reject(new CommandError(describeSpawnFailure(program, error, options))));
         });
         /**
@@ -153,6 +247,20 @@ export const runCommand = (argv, options = {}) => {
             // on we hold a real `code`/`signal`, so whatever the timer may still find
             // alive in the process group, this is not a run that produced no verdict.
             exited = true;
+            // Deregistered HERE — at the reap, alongside `exited`, and deliberately not
+            // at the settle below. The two are not the same instant: on the grace
+            // backstop `exit` fires and `settleWith` follows up to EXIT_CLOSE_GRACE_MS
+            // later, so a registry keyed on settle would hold a child whose pid the
+            // kernel has already freed, and a teardown drain landing in that window
+            // would fire `process.kill(-pid)` at whatever now owns that number. That
+            // is the unrecoverable, aimed-at-a-stranger hazard `killRun` documents and
+            // refuses to pay; membership must mean "not yet reaped" so its precondition
+            // holds by construction.
+            //
+            // Placed BEFORE the `settled` early-return for the same reason: the
+            // already-settled path is a reap too, and returning first would leak the
+            // entry.
+            liveChildren.delete(child);
             if (settled)
                 return;
             graceTimer = setTimeout(() => {
@@ -224,7 +332,7 @@ function killRun(child) {
  * promise losing the child's type.
  */
 function spawnChild(program, args, options) {
-    return spawn(program, [...args], {
+    const child = spawn(program, [...args], {
         cwd: options.cwd,
         stdio: ["ignore", "pipe", "pipe"],
         // Explicitly off. Stated rather than defaulted, because this is the line
@@ -240,15 +348,23 @@ function spawnChild(program, args, options) {
         // that detaching buys the reach of the kill and PAYS for it here: a new
         // group is also a new session, outside this server's controlling terminal,
         // so a signal aimed at OUR group — an interactive Ctrl-C, a supervisor's
-        // `kill -- -PGID` — no longer reaches a lint run in flight. Nothing in
-        // `bin/specguard-mcp.ts` installs a SIGINT/SIGTERM handler to kill
-        // outstanding children at teardown, so such a run is now orphaned where it
-        // would previously have died alongside us. Worth it, because the failure
-        // being traded away is an agent that never returns rather than a stray
-        // process — but it is a trade, and a teardown handler is what would close
-        // it.
+        // `kill -- -PGID` — no longer reaches a lint run in flight. Such a run would
+        // be orphaned where it would previously have died alongside us, and orphaned
+        // without a deadline, since the ceiling above is a parent-side timer.
+        //
+        // That is the debt this line used to carry, and it is now PAID rather than
+        // merely disclosed: the run is registered in `liveChildren` below, and
+        // `bin/specguard-mcp.ts` installs SIGINT/SIGTERM handlers that call
+        // `killOutstandingRuns` before exiting. The trade the kill's reach was
+        // bought with is closed; do not remove either half without restoring the
+        // other.
         detached: true,
     });
+    // Registered at the single spawn call site, so a run cannot enter the world
+    // unregistered. Removed again on the child's own `exit` — see `liveChildren`
+    // for why the reap, and not the settle, is the moment that matters.
+    liveChildren.add(child);
+    return child;
 }
 /**
  * Which thing failed to run — asked rather than assumed.

package/dist/src/support/run-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-command.js","sourceRoot":"","sources":["../../../src/support/run-command.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"run-command.js","sourceRoot":"","sources":["../../../src/support/run-command.ts"],"names":[],"mappings":"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"}

package/dist/src/support/specguard-api.d.ts

@@ -8,6 +8,56 @@ import { requireApiConfig, requireUserApiConfig, type ApiConfig } from "../confi
  * second place for the permission model to be got wrong.
  */
 export declare function getJson(api: ApiConfig, path: string, query: Record<string, string | undefined>, fetchImpl: typeof globalThis.fetch): Promise<unknown>;
+/**
+ * `POST` with a JSON body — the write half of the transport, and deliberately
+ * the SAME function underneath.
+ *
+ * It shares `fetchWithTimeout` rather than standing beside it. The one-total-
+ * budget deadline, the explicit race, the `unref`'d timer, the abort and the
+ * "reached and stopped" vs "could not reach" split are the expensive part of
+ * this module and every argument for them is written above them — none of it is
+ * about the verb. A second transport re-deriving them is how the two come to
+ * disagree about what `SPECGUARD_TIMEOUT_MS` bounds, and the write path is the
+ * one where a call that never returns costs the most: the agent has already
+ * committed to a registration by the time it hangs.
+ *
+ * The body is serialized HERE rather than taken as a string, so no caller can
+ * send a body whose `Content-Type` says JSON and whose bytes are not.
+ */
+export declare function postJson(api: ApiConfig, path: string, body: Record<string, unknown>, fetchImpl: typeof globalThis.fetch): Promise<unknown>;
+/**
+ * `DELETE` — the destructive half of the transport, and deliberately the SAME
+ * function underneath `postJson` rather than beside it, for the reason
+ * `postJson`'s header states: everything expensive about this module is about
+ * the deadline, not the verb.
+ *
+ * Returns the RAW BODY TEXT rather than a parsed value, because the endpoints
+ * this serves answer `204` with NO body at all — the one response in the `sgu_`
+ * surface that is deliberately not JSON. `requestJson` JSON-parses every 2xx it
+ * sees, so routing a `204` through it would turn a successful delete into
+ * "answered 204 but the body was not JSON" — the trap this verb specifically
+ * introduces, and the reason the DELETE path has its own success handling
+ * instead of sharing `requestJson`'s. The status check and the
+ * "reached and refused" hand-off to `describeFailure` are still shared
+ * verbatim: only what happens to a SUCCESS body differs.
+ */
+export declare function deleteJson(api: ApiConfig, path: string, fetchImpl: typeof globalThis.fetch): Promise<string>;
+/**
+ * `postJson`, narrowed exactly as `getJsonObject` narrows `getJson`.
+ *
+ * The write path needs the same guard for the same reason, and the reason is not
+ * about reading: `ToolResult.structured` is a `Record<string, unknown>`, so a
+ * body that is an array or a bare scalar is not something a tool can pass
+ * through whichever verb fetched it. Shipping only the raw `postJson` would
+ * leave the first write tool to re-type the three-clause check and its sentence
+ * — which is precisely the duplication `getJsonObject`'s header says no tool
+ * should have to repeat.
+ *
+ * The pair is mirrored rather than collapsed for the reason the read pair is:
+ * `postJson` stays exported un-narrowed for an endpoint that legitimately
+ * answers with an array.
+ */
+export declare function postJsonObject(api: ApiConfig, path: string, body: Record<string, unknown>, fetchImpl: typeof globalThis.fetch): Promise<Record<string, unknown>>;
 /**
  * `getJson`, narrowed to the object every tool here actually asks it for.
  *