@infinitedusky/indusk-mcp 1.64.0 → 1.65.1

package/dist/lib/telemetry/daemon.js

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { createServer } from "node:net";
@@ -24,11 +24,13 @@ import { join } from "node:path";
  * immediately after `daemonStart` resolves — the PID/meta files are the
  * durable handoff to subsequent `telemetry status`/`telemetry stop` invocations.
  *
- * PID-reuse hardening: `verifyIdentity(pid, port)` composes `isAlive(pid)`
- * with `isPortListening(port)` to guard against reporting a recycled PID as
- * "running" (admin-UI Phase 7 lesson — applied here).
+ * PID-reuse hardening: `status` composes `isAlive(pid)` with
+ * `isPortListening(port)` (`verifyIdentity`) so a recycled PID is not reported
+ * running. `stop` judges ownership by the process's command line instead
+ * (`stop.ts`): a slow port must never make it skip its own processes.
  */
-import { cleanupFiles, daemonStatus, induskHome, isAlive, isPortListening, metaFilePath, pidFilePath, verifyIdentity, } from "./status.js";
+import { cleanupFiles, daemonStatus, induskHome, isAlive, isPortListening, metaFilePath, pidFilePath, } from "./status.js";
+import { stopDaemon } from "./stop.js";
 export { daemonMetaPath, daemonStatus, isPortListening, liveOtlpEndpointSync, } from "./status.js";
 function logFilePath() {
     return join(induskHome(), "telemetry.log");
@@ -419,63 +421,29 @@ export async function daemonStop() {
         cleanupFiles();
         return { stopped: false };
     }
-    // Identity gate for stop: if the recorded PIDs aren't ours anymore
-    // (PID-reuse), clean up files but don't SIGTERM a stranger.
-    const jaegerOk = await verifyIdentity(meta.jaegerPid, meta.uiPort);
-    const otelcolOk = await verifyIdentity(meta.otelcolPid, meta.otelcolHealthPort);
-    if (!jaegerOk && !otelcolOk) {
+    // Ownership is the command line, never the port (telemetry-stop-stops-what-it-started):
+    // a slow port once made stop signal nothing, delete the record and report success.
+    const result = await stopDaemon(meta, induskHome(), {
+        alive: isAlive,
+        command: processCommand,
+        kill: (pid, signal) => process.kill(pid, signal),
+        sleep,
+    });
+    if (result.clearRecord)
         cleanupFiles();
-        return {
-            stopped: true,
-            signaledJaegerPid: meta.jaegerPid,
-            signaledOtelcolPid: meta.otelcolPid,
-        };
-    }
-    // Signal both; poll for exit up to 3s; SIGKILL fallback
-    const targets = [];
-    if (jaegerOk)
-        targets.push(meta.jaegerPid);
-    if (otelcolOk)
-        targets.push(meta.otelcolPid);
-    for (const pid of targets) {
-        try {
-            process.kill(pid, "SIGTERM");
-        }
-        catch {
-            // already gone
-        }
-    }
-    for (let i = 0; i < 30; i++) {
-        await sleep(100);
-        if (targets.every((pid) => !isAlive(pid))) {
-            cleanupFiles();
-            return {
-                stopped: true,
-                signaledJaegerPid: meta.jaegerPid,
-                signaledOtelcolPid: meta.otelcolPid,
-            };
-        }
-    }
-    let usedSigkill = false;
-    for (const pid of targets) {
-        if (isAlive(pid)) {
-            try {
-                process.kill(pid, "SIGKILL");
-                usedSigkill = true;
-            }
-            catch {
-                // best-effort
-            }
-        }
-    }
-    cleanupFiles();
     return {
         stopped: true,
         signaledJaegerPid: meta.jaegerPid,
         signaledOtelcolPid: meta.otelcolPid,
-        usedSigkill,
+        stillRunning: result.stillRunning,
     };
 }
+/** A process's command line, or null when it is gone or cannot be read. */
+function processCommand(pid) {
+    const r = spawnSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf-8" });
+    const out = r.status === 0 ? r.stdout.trim() : "";
+    return out === "" ? null : out;
+}
 export async function daemonRestart(opts = {}) {
     // Restart means "same daemon, fresh processes" — inherit the previously
     // bound ports before stopping so the new spawn rebinds the same addresses

package/dist/lib/telemetry/stop.d.ts

@@ -0,0 +1,33 @@
+import type { DaemonMeta } from "./status.js";
+/**
+ * Stopping the telemetry daemon (telemetry-stop-stops-what-it-started).
+ *
+ * A recorded process is this daemon's when it is alive and its command line
+ * runs the recorded binary with this home's own config file. Its port is not
+ * asked: under load a port can be slow, and judging by it once made stop
+ * signal nothing, delete the record and report the daemon stopped (the 1.65.0
+ * release left nine processes that way). A PID now held by another program,
+ * or by the same binary from another home, is never signalled. Stop reports
+ * stopped only when none of its own is left, and keeps the record otherwise.
+ *
+ * promise: telemetry-stop-stops-what-it-started
+ */
+/** What stopping reads and does, given as inputs so the decision is a unit test. */
+export interface StopDeps {
+    alive(pid: number): boolean;
+    command(pid: number): string | null;
+    kill(pid: number, signal: NodeJS.Signals): void;
+    sleep(ms: number): Promise<void>;
+}
+export interface StopResult {
+    /** None of the daemon's own processes is left running. */
+    stopped: boolean;
+    /** The record may be deleted: nothing of its own still runs. */
+    clearRecord: boolean;
+    signaled: number[];
+    strangers: number[];
+    stillRunning: number[];
+}
+/** Whether `pid` is this daemon's process: alive, and running `binary` with `config`. */
+export declare function isOwnProcess(pid: number, binary: string, config: string, deps: StopDeps): boolean;
+export declare function stopDaemon(meta: DaemonMeta, home: string, deps: StopDeps): Promise<StopResult>;

package/dist/lib/telemetry/stop.js

@@ -0,0 +1,45 @@
+import { join } from "node:path";
+const GRACE_MS = 3000;
+const POLL_MS = 100;
+/** Whether `pid` is this daemon's process: alive, and running `binary` with `config`. */
+export function isOwnProcess(pid, binary, config, deps) {
+    if (!deps.alive(pid))
+        return false;
+    const cmd = deps.command(pid);
+    return cmd !== null && cmd.includes(binary) && cmd.includes(config);
+}
+export async function stopDaemon(meta, home, deps) {
+    const recorded = [
+        { pid: meta.jaegerPid, binary: meta.jaegerBinary, config: join(home, "telemetry-jaeger.yaml") },
+        {
+            pid: meta.otelcolPid,
+            binary: meta.otelcolBinary,
+            config: join(home, "telemetry-collector.yaml"),
+        },
+    ];
+    const own = recorded
+        .filter((p) => isOwnProcess(p.pid, p.binary, p.config, deps))
+        .map((p) => p.pid);
+    const strangers = recorded
+        .filter((p) => deps.alive(p.pid) && !own.includes(p.pid))
+        .map((p) => p.pid);
+    for (const pid of own)
+        signal(deps, pid, "SIGTERM");
+    for (let waited = 0; waited < GRACE_MS && own.some((pid) => deps.alive(pid)); waited += POLL_MS) {
+        await deps.sleep(POLL_MS);
+    }
+    for (const pid of own.filter((p) => deps.alive(p)))
+        signal(deps, pid, "SIGKILL");
+    await deps.sleep(POLL_MS);
+    const stillRunning = own.filter((pid) => deps.alive(pid));
+    const stopped = stillRunning.length === 0;
+    return { stopped, clearRecord: stopped, signaled: own, strangers, stillRunning };
+}
+function signal(deps, pid, sig) {
+    try {
+        deps.kill(pid, sig);
+    }
+    catch {
+        // already gone
+    }
+}

package/dist/lib/version-state.d.ts

@@ -3,7 +3,7 @@
  * A deliberate mirror of `PACKAGED_PATHS` in `scripts/release-guard.sh` — bash
  * cannot import this, so `version-state.test.ts` pins the two lists equal.
  */
-export declare const PACKAGED_PATHS: readonly ["apps/indusk-mcp/src", "apps/indusk-mcp/skills", "apps/indusk-mcp/templates", "apps/indusk-mcp/hooks", "apps/indusk-mcp/lessons", "apps/indusk-mcp/extensions", "apps/indusk-mcp/package.json", "apps/indusk-admin"];
+export declare const PACKAGED_PATHS: readonly ["apps/indusk-mcp/src", "apps/indusk-mcp/skills", "apps/indusk-mcp/templates", "apps/indusk-mcp/hooks", "apps/indusk-mcp/lessons", "apps/indusk-mcp/extensions", "apps/indusk-mcp/package.json", "apps/indusk-admin", "examples/seat-holds"];
 export interface RepoVersionState {
     /** `apps/indusk-mcp/package.json` version in the working tree. */
     version: string;

package/dist/lib/version-state.js

@@ -42,6 +42,7 @@ export const PACKAGED_PATHS = [
     "apps/indusk-mcp/extensions",
     "apps/indusk-mcp/package.json",
     "apps/indusk-admin",
+    "examples/seat-holds",
 ];
 function readPackageVersion(pkgJsonPath) {
     return JSON.parse(readFileSync(pkgJsonPath, "utf-8")).version;

package/examples/seat-holds/.dockerignore

@@ -0,0 +1,3 @@
+node_modules
+.indusk
+npm-debug.log

package/examples/seat-holds/.indusk/config.json

@@ -0,0 +1,5 @@
+{
+	"promises": {
+		"domains": ["seats"]
+	}
+}

package/examples/seat-holds/.indusk/planning/archive/seat-holds/brief.md

@@ -0,0 +1,36 @@
+---
+title: "Seat holds — the first promise"
+date: 2026-10-07
+status: accepted
+workflow: feature
+---
+
+# Seat holds — Brief
+
+The plan this example starts from: a seat page whose holds are released on
+time, and that answers once deployed. It shipped with the example, already built; the next plans are yours.
+
+## Expectations
+
+None — this is the starting point of a demo, not a change to measure.
+
+## Promises
+
+### This plan makes
+
+1. **`a-held-seat-is-released-in-time`** (behaviour). A seat that is held and not booked is released when its hold window passes, never late.
+2. **`the-deployed-demo-page-answers`** (state). After the seat-holds example is deployed to Fly from its own config, its page answers at the deployed address.
+
+### Existing promises
+
+**Must not break**
+
+None.
+
+**Changes**
+
+None.
+
+**Replaces**
+
+None.

package/examples/seat-holds/.indusk/promises/a-held-seat-is-released-in-time.md

@@ -0,0 +1,18 @@
+---
+name: a-held-seat-is-released-in-time
+kind: behaviour
+lifetime: holds
+state: enforced
+domain: seats
+owner: seat-holds
+sites:
+  - src/telemetry.ts
+tests:
+  - src/seats.test.ts
+incidents: []
+---
+
+A seat that is held and not booked is released when its hold window passes, never late.
+
+## History
+- 2026-10-07 — shipped with the seat-holds example (InDusk demo-app-template), enforced: its rules are tested in `src/seats.test.ts`, and every release is marked in `src/telemetry.ts`.

package/examples/seat-holds/.indusk/promises/the-deployed-demo-page-answers.md

@@ -0,0 +1,19 @@
+---
+name: the-deployed-demo-page-answers
+kind: state
+lifetime: holds
+state: enforced
+domain: seats
+owner: seat-holds
+sites:
+  - Dockerfile
+  - fly.toml
+tests:
+  - scripts/smoke-deployed.mjs
+incidents: []
+---
+
+After the seat-holds example is deployed to Fly from its own config, its page answers at the deployed address.
+
+## History
+- 2026-10-07 — shipped with the seat-holds example (InDusk demo-app-template), enforced: `npm run smoke` against the deployed address proves it, at every deploy.

package/examples/seat-holds/Dockerfile

@@ -0,0 +1,14 @@
+# promise: the-deployed-demo-page-answers
+# The seat-holds example as a container: the page on 8080, its spans sent to
+# whatever OTEL_EXPORTER_OTLP_ENDPOINT names (your project's InDusk server).
+FROM node:24-slim
+WORKDIR /app
+COPY package.json ./
+# Node 24 for npm 11: npm 10 fails to install this tree ("Cannot read
+# properties of null (reading 'edgesOut')").
+RUN npm install --omit=dev --no-audit --no-fund --loglevel=error
+COPY src ./src
+COPY public ./public
+ENV NODE_ENV=production PORT=8080 SEAT_HOLDS_ENV=production
+EXPOSE 8080
+CMD ["npm", "start", "--silent"]

package/examples/seat-holds/README.md

@@ -0,0 +1,87 @@
+# Seat holds
+
+A small app with one promise you can break on cue. It is the example InDusk's
+demo starts from.
+
+Hold a seat on the page and it is yours for a few seconds. If you don't book
+it, it is released, and the app promises that release is never late:
+
+> **`a-held-seat-is-released-in-time`** — A seat that is held and not booked is released when its hold window passes, never late.
+
+Every release is marked with plain OpenTelemetry on the span that does the
+work: `indusk.promise = a-held-seat-is-released-in-time` and
+`indusk.promise.outcome = upheld` or `violated`, with a symptom like
+`seat 2 released 3.2 s late`. Nothing else in the app knows InDusk exists.
+InDusk reads those marks from your local telemetry daemon (or your project's
+server) and shows the promise holding, or broken.
+
+## Run it
+
+The quickest way is from InDusk:
+
+```bash
+npx @infinitedusky/indusk-mcp demo
+```
+
+That copies this example into `./seat-holds`, sets it up as an InDusk project,
+starts the local telemetry daemon and the app, and prints the page's address
+and the admin's.
+
+To run it by hand instead:
+
+```bash
+pnpm install
+SEAT_HOLDS_FAULT_TOGGLE=1 \
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
+pnpm start
+```
+
+## Break it
+
+With `SEAT_HOLDS_FAULT_TOGGLE=1`, the page shows a **Break it** switch. Turn it
+on and releases come late on purpose: the next lapsed hold is marked
+`violated`, and InDusk shows the promise broken with the span that broke it.
+Press **Stop the fault** and releases come on time again, but the promise
+stays broken: it said *never*. It holds again once the break is recorded as an
+incident and fixed.
+
+## Configuration
+
+| Variable | Default | What it does |
+|---|---|---|
+| `PORT` | `8080` | the page and the API |
+| `SEAT_HOLDS_SEATS` | `8` | how many seats |
+| `SEAT_HOLDS_WINDOW_MS` | `5000` | how long a hold lasts |
+| `SEAT_HOLDS_TOLERANCE_MS` | `1500` | how late a release may be and still keep the promise |
+| `SEAT_HOLDS_FAULT_TOGGLE` | unset | `1` shows the Break it switch |
+| `SEAT_HOLDS_FAULT` | unset | `slow-release` starts with releases late |
+| `SEAT_HOLDS_ENV` | `local` | `deployment.environment` on every span |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | where spans go: the InDusk daemon, or your project's server |
+
+## Deploy it
+
+`fly.toml` and the `Dockerfile` run it on Fly.io as one machine that never
+sleeps, sending its spans to your project's InDusk server:
+
+```bash
+fly apps create <app>
+fly secrets set \
+  OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-indusk-server>" \
+  OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic%20<base64 of user:password>"
+fly deploy --app <app> --ha=false
+```
+
+The deployed page has no Break it switch. To break the promise in production
+on purpose, set `SEAT_HOLDS_FAULT=slow-release` and deploy; unset it and deploy
+again to fix it.
+
+## What's in it
+
+- `src/seats.ts` — the rules: hold, book, release, and whether a release was on time. The clock is an argument, so the tests never wait.
+- `src/telemetry.ts` — OpenTelemetry, and one mark per release.
+- `src/server.ts` — the page, the API, the fault switch, and the sweeper that releases lapsed holds once a second.
+- `public/index.html` — the page.
+- `.indusk/` — the example's promise and the plan it came from.
+
+Seats live in memory, so a restart frees them all. That is fine for a demo and
+wrong for anything else.

package/examples/seat-holds/fly.toml

@@ -0,0 +1,32 @@
+# promise: the-deployed-demo-page-answers
+# The seat-holds example on Fly.io (demo-app-template D7). One machine that
+# never sleeps: the sweeper releases holds once a second, and a stopped
+# machine marks nothing.
+#
+#   fly apps create <app>                      # not `fly launch`: it rewrites this file
+#   fly secrets set \
+#     OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-indusk-server>:4318" \
+#     OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <base64 of user:password>"
+#   fly deploy --ha=false
+#
+# The page has no Break it switch here. To break the promise in production on
+# purpose, deploy with SEAT_HOLDS_FAULT=slow-release, and deploy again without
+# it to fix it.
+
+app = "seat-holds"
+primary_region = "iad"
+
+[env]
+  PORT = "8080"
+  SEAT_HOLDS_ENV = "production"
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+  auto_stop_machines = "off"
+  auto_start_machines = true
+  min_machines_running = 1
+
+[[vm]]
+  size = "shared-cpu-1x"
+  memory = "256mb"

package/examples/seat-holds/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "seat-holds",
+	"version": "0.1.0",
+	"private": true,
+	"description": "A small app with one promise you can break on cue — the InDusk demo example",
+	"type": "module",
+	"scripts": {
+		"start": "tsx src/server.ts",
+		"test": "vitest run",
+		"smoke": "node scripts/smoke-deployed.mjs"
+	},
+	"dependencies": {
+		"@opentelemetry/api": "^1.9.0",
+		"@opentelemetry/exporter-trace-otlp-http": "^0.214.0",
+		"@opentelemetry/resources": "^2.6.0",
+		"@opentelemetry/sdk-trace-base": "^2.6.0",
+		"@opentelemetry/sdk-trace-node": "^2.6.0",
+		"@opentelemetry/semantic-conventions": "^1.40.0",
+		"tsx": "^4.19.0"
+	},
+	"devDependencies": {
+		"typescript": "^5.7.0",
+		"vitest": "^4.1.11"
+	}
+}

package/examples/seat-holds/public/index.html

@@ -0,0 +1,85 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Seat holds</title>
+<style>
+  :root { --bg:#f7f6f2; --ink:#1c1b19; --muted:#6b675f; --line:#dedad0; --held:#c98a14; --booked:#2f6f4f; --bad:#b3261e; }
+  * { box-sizing: border-box; }
+  body { margin:0; padding:2rem 1rem; background:var(--bg); color:var(--ink); font:15px/1.5 system-ui, sans-serif; }
+  main { max-width: 40rem; margin: 0 auto; }
+  h1 { font-size: 1.4rem; margin: 0 0 .25rem; }
+  p.lede { color: var(--muted); margin: 0 0 1.5rem; }
+  .grid { display:grid; grid-template-columns: repeat(auto-fill, minmax(8.5rem, 1fr)); gap:.75rem; }
+  .seat { background:#fff; border:1px solid var(--line); border-radius:.6rem; padding:.75rem; min-height:7rem; display:flex; flex-direction:column; gap:.4rem; }
+  .seat h2 { font-size:1rem; margin:0; }
+  .state { font-size:.85rem; color:var(--muted); }
+  .seat.held { border-color: var(--held); }
+  .seat.held .state { color: var(--held); }
+  .seat.booked { border-color: var(--booked); }
+  .seat.booked .state { color: var(--booked); }
+  button { font:inherit; padding:.35rem .7rem; border-radius:.4rem; border:1px solid var(--ink); background:var(--ink); color:#fff; cursor:pointer; }
+  button.secondary { background:#fff; color:var(--ink); }
+  .fault { margin: 1.5rem 0 0; padding: .75rem; border:1px dashed var(--line); border-radius:.6rem; display:flex; gap:.75rem; align-items:center; flex-wrap:wrap; }
+  .fault.on { border-color: var(--bad); color: var(--bad); }
+  .fault button.on { background: var(--bad); border-color: var(--bad); }
+</style>
+</head>
+<body>
+<main>
+  <h1>Seat holds</h1>
+  <p class="lede">Hold a seat and it is yours for a few seconds. If you don't book it, it is released, and this app promises that release is never late.</p>
+  <div class="grid" id="seats"></div>
+  <div class="fault" id="fault" hidden>
+    <button id="toggle" type="button">Break it</button>
+    <span id="fault-text">Releases come on time. Break it to make them late, and watch the promise break.</span>
+  </div>
+</main>
+<script>
+  const who = "you";
+  const el = (id) => document.getElementById(id);
+  async function post(path, body) {
+    await fetch(path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+    render();
+  }
+  async function render() {
+    const { seats, fault, toggle } = await (await fetch("/seats")).json();
+    el("seats").replaceChildren(...seats.map((s) => {
+      const card = document.createElement("div");
+      card.className = `seat ${s.state}`;
+      const title = document.createElement("h2");
+      title.textContent = `Seat ${s.seat}`;
+      const state = document.createElement("div");
+      state.className = "state";
+      state.textContent = s.state === "held" ? `held · ${Math.ceil(s.remainingMs / 1000)} s left`
+        : s.state === "booked" ? "booked" : "free";
+      card.append(title, state);
+      if (s.state === "free") {
+        const b = document.createElement("button");
+        b.textContent = "Hold";
+        b.onclick = () => post("/hold", { seat: s.seat, who });
+        card.append(b);
+      } else if (s.state === "held" && s.who === who) {
+        const b = document.createElement("button");
+        b.className = "secondary";
+        b.textContent = "Book";
+        b.onclick = () => post("/book", { seat: s.seat, who });
+        card.append(b);
+      }
+      return card;
+    }));
+    el("fault").hidden = !toggle;
+    el("fault").className = `fault${fault ? " on" : ""}`;
+    el("toggle").className = fault ? "on" : "";
+    el("toggle").textContent = fault ? "Stop the fault" : "Break it";
+    el("toggle").onclick = () => post("/fault", { on: !fault });
+    el("fault-text").textContent = fault
+      ? "Releases are late on purpose, and every late one breaks the promise. Stopping the fault does not mend it: the promise stays broken until the break is recorded and fixed."
+      : "Releases come on time. Break it to make them late, and watch the promise break.";
+  }
+  render();
+  setInterval(render, 500);
+</script>
+</body>
+</html>

package/examples/seat-holds/scripts/smoke-deployed.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// promise: the-deployed-demo-page-answers
+//
+// After the seat-holds example is deployed, its page answers at the deployed
+// address. Run at deploy: SEAT_HOLDS_URL=https://<app>.fly.dev npm run smoke
+// Exit 0 only on a 200 whose body is the seat page; otherwise say why and exit 1.
+
+const url = process.env.SEAT_HOLDS_URL;
+if (!url) {
+	console.error("smoke: SEAT_HOLDS_URL is not set — name the deployed address to check");
+	process.exit(1);
+}
+
+try {
+	const res = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+	const body = await res.text();
+	if (res.status !== 200) {
+		console.error(`smoke: ${url} answered ${res.status}`);
+		process.exit(1);
+	}
+	if (!body.includes("<title>Seat holds</title>")) {
+		console.error(`smoke: ${url} answered 200, but not with the seat page`);
+		process.exit(1);
+	}
+	console.log(`smoke: ${url} answers with the seat page`);
+} catch (err) {
+	console.error(`smoke: ${url} did not answer — ${err.message}`);
+	process.exit(1);
+}

package/examples/seat-holds/src/seats.test.ts

@@ -0,0 +1,45 @@
+// promise: a-held-seat-is-released-in-time
+// The rules behind this example's one promise. (In InDusk's repository these
+// are rows A1, A2 and A6 of the demo-app-template plan.)
+import { describe, expect, it } from "vitest";
+import { createSeats } from "./seats.js";
+
+// The clock is an argument: every rule here runs in microseconds, never waits.
+const opts = { seats: 4, windowMs: 3000, toleranceMs: 1000, faultDelayMs: 3000 };
+
+describe("seat holds", () => {
+	it("A1: a held seat comes free when its window passes; a booked one never does; a held seat is not anyone else's", () => {
+		const s = createSeats(opts);
+		expect(s.hold(1, "ann", 0).ok).toBe(true);
+		expect(s.hold(1, "bob", 10).ok).toBe(false);
+		expect(s.hold(2, "bob", 0).ok).toBe(true);
+		expect(s.book(2, "bob", 100).ok).toBe(true);
+		expect(s.book(1, "bob", 100).ok, "only the holder books").toBe(false);
+		expect(s.sweep(2900, { fault: false })).toEqual([]);
+		expect(s.sweep(3100, { fault: false }).map((r) => r.seat)).toEqual([1]);
+		expect(s.sweep(60_000, { fault: false }), "a booked seat never comes free").toEqual([]);
+		expect(s.hold(1, "bob", 3200).ok, "a released seat can be held again").toBe(true);
+	});
+
+	it("A2: a release on time is held; a late one is broken, naming the seat and how late", () => {
+		const s = createSeats(opts);
+		s.hold(1, "ann", 0);
+		expect(s.sweep(3500, { fault: false })[0]).toMatchObject({ seat: 1, outcome: "upheld" });
+		s.hold(2, "bob", 0);
+		expect(s.sweep(6200, { fault: false })[0]).toMatchObject({
+			seat: 2,
+			outcome: "violated",
+			lateMs: 3200,
+			symptom: "seat 2 released 3.2 s late",
+		});
+	});
+
+	it("A6: with the fault on, a release waits past its window and is broken; off, it is on time", () => {
+		const s = createSeats(opts);
+		s.hold(1, "ann", 0);
+		expect(s.sweep(3100, { fault: true }), "the fault holds the release back").toEqual([]);
+		expect(s.sweep(6100, { fault: true })[0]).toMatchObject({ seat: 1, outcome: "violated" });
+		s.hold(2, "bob", 7000);
+		expect(s.sweep(10_100, { fault: false })[0]).toMatchObject({ seat: 2, outcome: "upheld" });
+	});
+});