agent-standup 0.20.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zaida-3dO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,322 @@
+<p align="right"><a href="https://github.com/Zaida-3dO/agent-standup/releases/latest"><img src="https://img.shields.io/github/v/release/Zaida-3dO/agent-standup?label=latest%20version&logo=github&logoColor=white" alt="Latest version"></a> <a href="https://github.com/Zaida-3dO/agent-standup/actions/workflows/release.yml"><img src="https://img.shields.io/github/commits-since/Zaida-3dO/agent-standup/latest?label=unreleased%20commits&logo=git&logoColor=white" alt="Unreleased commits"></a> <a href="https://github.com/Zaida-3dO/agent-standup/actions/workflows/release.yml"><img src="https://img.shields.io/github/actions/workflow/status/Zaida-3dO/agent-standup/release.yml?label=latest%20build%20status&logo=githubactions&logoColor=white" alt="Latest build status"></a></p>
+
+# Agent Standup
+
+A task tracker for AI coding agents: a database, a rules engine every change goes
+through, an MCP so agents can talk to it, a CLI for the parts MCP can't do, and a
+web front end.
+
+**The point:** the rules live in the backend and are _enforced_ rather than
+requested. An agent can't skip a step, because the server refuses the change.
+
+## Docs
+
+Everything is in [`docs/plans/`](docs/plans/):
+
+| Doc                                       | What it is                                       |
+| ----------------------------------------- | ------------------------------------------------ |
+| [PLAN.md](docs/plans/PLAN.md)             | The readable plan — how it works, in plain terms |
+| [SCHEMA.md](docs/plans/SCHEMA.md)         | Tables, config, MCP tools, HTTP endpoints        |
+| [DECISIONS.md](docs/plans/DECISIONS.md)   | Every decision with its reasoning                |
+| [MILESTONES.md](docs/plans/MILESTONES.md) | The work, broken into pull requests, in order    |
+
+## Stack
+
+Next.js (front end and API in one bundle) · Prisma · Postgres. The image is built
+in CI, pushed to GHCR, and **pulled** wherever it runs — never built on the deploy
+host, no bind mounts.
+
+## Local development
+
+Requires Node 24 and a reachable Postgres. **Docker is one way to get that Postgres, not a
+requirement of the app** — `npm run db:up` is a convenience wrapper around `docker compose up -d db`
+and is the only thing in the repo that shells out to Docker. Nothing under `src/` touches it. The app
+reads one connection string, so a natively installed Postgres (Postgres.app, Homebrew, a distribution
+package, or a userspace `initdb`) works identically: point `DATABASE_URL` at it and skip `db:up`.
+
+```bash
+cp .env.example .env          # fill in DATABASE_URL etc.
+npm install
+npm run db:up                 # OPTIONAL — starts local Postgres in Docker on a non-default port.
+                              # Skip it if you already have a Postgres; just set DATABASE_URL.
+npx prisma migrate deploy     # apply the committed migrations
+npx prisma generate
+npm run dev                   # http://localhost:3000
+```
+
+`PORT` and `HOSTNAME` control what the server listens on, so `http://localhost:3000` above is the
+default rather than a fixed address — see [Configuration](#configuration).
+
+### Configuration
+
+Only what must be known before the process can reach a database is an
+environment variable — `DATABASE_URL`, plus `HOSTNAME` and `PORT` for what
+interface and port the server listens on. `.env.example` lists these and the
+handful of others that are genuinely bootstrap (the local Postgres readiness
+wait, the disposable shadow database the migration drift check uses).
+
+Authentication is the other bootstrap value: `STANDUP_TOKENS` holds one
+bearer token per machine, and clients present theirs as `STANDUP_TOKEN`.
+It has no default — with it unset the server refuses every authenticated
+call, which is deliberate (a gate that switched itself off when its
+configuration was missing would be open exactly when a deployment had gone
+wrong). It is an environment variable rather than a setting for the same
+reason as the rest of this list, plus one specific to it: settings are
+served to the front end and printed by the command line, with no redaction
+path, so a credential cannot live there.
+
+**The front end needs one of those tokens too, and it must be its own.** A
+browser is not a machine: it holds no configuration, and anything handed to a
+page is readable by whoever opens the developer tools, which would make
+revoking one machine's access meaningless. So the browser is never given a
+credential. It calls `/api/ui/*`, a server-side route that attaches the token
+for the machine named `browser` (override with `STANDUP_BROWSER_MACHINE`) and
+forwards to the same authenticated handlers every other client reaches — so
+the call is authenticated by the ordinary gate rather than exempted from it,
+and the token stays in the server process. Configure one alongside the rest:
+
+```
+STANDUP_TOKENS=browser:TOKEN-A,laptop:TOKEN-B
+```
+
+With no token configured for that machine the front end serves a 503 saying
+so, rather than falling back to calling the API without one.
+
+Everything else is a setting: typed, defaulted in code, and readable and
+writable once the app is running, from `/settings` in the front end or
+`standup config set` on the command line. A fresh database boots fully
+working with no settings configured at all — each one has a default. Setting
+an old environment variable that has moved into settings does nothing; a
+startup check catches this — it fails immediately in development, and logs
+loudly (without stopping the process) in production.
+
+Useful scripts:
+
+| Command                           | What it does                                                                                                                                                           |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `npm run dev`                     | Next.js dev server                                                                                                                                                     |
+| `npm run build` / `npm start`     | Production build / run it                                                                                                                                              |
+| `npm run typecheck`               | `tsc --noEmit`                                                                                                                                                         |
+| `npm run lint` / `npm run format` | ESLint / Prettier (`:check` variants exist for CI)                                                                                                                     |
+| `npm test`                        | Vitest, wrapped so a failing run cannot look green — it also fails on the printed summary, so an empty or failing run is caught even through a pipe. **Use this one.** |
+| `npm run test:raw`                | Bare `vitest run`. Careful: `... \| tail` reports the pipe's exit status, not vitest's                                                                                 |
+| `npm run db:migrate`              | Create/apply a dev migration (`prisma migrate dev`)                                                                                                                    |
+| `npm run db:deploy`               | Apply committed migrations without prompting (`prisma migrate deploy`)                                                                                                 |
+| `npm run db:check-drift`          | Fail if `schema.prisma` and `prisma/migrations` disagree — needs `SHADOW_DATABASE_URL` pointed at an empty, disposable Postgres                                        |
+| `npm run db:studio`               | Prisma Studio                                                                                                                                                          |
+
+The initial baseline migration (the whole schema in one shot — see
+[`SCHEMA.md`](docs/plans/SCHEMA.md)) lives in `prisma/migrations/`. CI applies it to a
+throwaway Postgres on every run and fails if `schema.prisma` and the migration history
+have drifted apart.
+
+## Deployment
+
+The image is built by [`.github/workflows/release.yml`](.github/workflows/release.yml)
+on a version tag or manual dispatch, and pushed to `ghcr.io/<owner>/agent-standup`
+tagged `latest` and the version. The package is public, so pulling it needs no
+registry credential. Wherever it runs, pull and run it with
+[`docker-compose.prod.yml`](docker-compose.prod.yml):
+
+```bash
+GHCR_IMAGE=ghcr.io/<owner>/agent-standup:latest
+DATABASE_URL=postgres://user:password@host:5432/agent_standup
+docker compose --env-file .env.production -f docker-compose.prod.yml pull
+docker compose --env-file .env.production -f docker-compose.prod.yml up -d
+```
+
+`docker-compose.prod.yml` has no `build:` block and no bind mounts by design — it
+only ever pulls. It ships a health check on `GET /api/health` (liveness only —
+deliberately doesn't touch the database, so a slow DB doesn't make the process
+report unhealthy).
+
+**Two probes, answering two different questions.** Point each consumer at the
+one it actually needs, because giving either the other's answer is wrong in a
+way that is quiet:
+
+| Endpoint      | Asks                  | Reads the database | For                                                       |
+| ------------- | --------------------- | ------------------ | --------------------------------------------------------- |
+| `/api/health` | Is this process alive | No                 | Restart policies — a container that has stopped serving   |
+| `/api/ready`  | Can I use this yet    | Yes                | Deployment gates, `depends_on` conditions, load balancers |
+
+A process whose Postgres is still starting is **alive and not ready**, which
+is normal and common. Report that as unhealthy and a restart policy kills a
+container that was about to work; report it as ready and a load balancer
+sends traffic to a process that cannot serve it.
+
+`/api/ready` answers `200` when it can query the database and no migration is
+half-applied, and `503` otherwise, with a body carrying the migration counts:
+_connected but two migrations behind_ and _migrated and ready_ are different
+answers, and only one is safe to send traffic to. Both probes are
+unauthenticated — the things that ask them run before an installation is
+configured and hold no credential — and both report only booleans and counts.
+
+### Many machines, one server
+
+The schema is built for a fleet: `machines` is a first-class entity, work is
+claimed per session, and `assignments` records which machine holds what. A
+single-host compose file is the simplest deployment of that design, not the
+limit of it — the usual shape is **one server and its database, and a client
+on every machine doing the work.**
+
+**A remote client talks to the API. It never opens a connection to the
+database.** This is the one deployment rule worth stating outright, because
+the alternative is available and looks equivalent from the outside:
+
+- Every rule this product enforces — a merge needing an approving review at
+  tip, a completion needing a structured summary, a transition needing an
+  approved plan — is **application code in the service layer.** Postgres
+  does not know those rules exist and cannot be taught them: _allowed only
+  with an approving review at tip_ is conditional on state a grant cannot
+  evaluate.
+- So a client on `DATABASE_URL` does not defeat those checks; it never
+  reaches the code that performs them. An item can land in `merged` with no
+  commit, no review and no summary, and nothing in the system is wrong about
+  anything — the rules were simply never consulted.
+- **Database-level permissions are not a substitute.** A restricted role can
+  refuse a write to a table. It cannot express the condition above, which is
+  the one that matters.
+
+Point each machine at the server and give it its own token:
+
+```bash
+STANDUP_URL=https://standup.example.internal
+STANDUP_TOKEN=<this machine's token>
+```
+
+Both the command line and the MCP client use the API when `STANDUP_URL` is
+set. `DATABASE_URL` belongs to the server alone; a client that has one is
+configured as though it were the server.
+
+Tokens are per machine rather than one shared secret, which buys two things:
+a machine can be revoked without rotating every other machine's
+configuration, and the actor a client declares stops being an unverified
+self-report — the server knows which machine presented the token, so an
+attributed write means something.
+
+### The liveness sweep has to be run by something
+
+**A deployment that never runs the sweep leaks claims that can never be handed
+back.** A session takes ownership of an item by claiming it; if that session
+crashes rather than releasing, the claim outlives it and every later claim on
+that item is refused as already-held. The liveness sweep is what notices — it
+ages quiet sessions, releases what died, and escalates what is stuck — and it
+runs only when something invokes it. Measured on an installation running without
+one: the first manual sweep released **174** stale claims that had been sitting
+for three days, every one of them blocking ownership of its item.
+
+**Running it is the deployment's job, and this compose file ships nothing to do
+it.** The application deliberately has no internal timer. It runs as a bundle
+that may be one replica or several, so a timer inside it fires once _per
+replica_ — a multiple of the intended rate on a scaled deployment, or not at all
+if the replica holding it is the one that restarted — and neither mistake
+produces any output to notice. Invoke it from outside the process, where there
+is exactly one of whatever you choose.
+
+Either surface works, and nothing in the application distinguishes the callers:
+
+```bash
+# Host cron, every five minutes — over HTTP:
+*/5 * * * * curl -fsS -X POST -H "Authorization: Bearer $TOKEN" http://localhost:3000/api/sweep >/dev/null
+
+# …or over the command line, which reports what it released:
+*/5 * * * * standup sweep --json
+```
+
+`POST /api/sweep` authenticates like every other route, so a scheduler calling
+it needs a token in `STANDUP_TOKENS` the same as any machine. The endpoint is
+`POST` rather than `GET` on purpose: it writes, and a `GET` that releases other
+sessions' claims is one a crawler or a browser prefetch will invoke without
+anyone asking it to. It takes no input, so an empty body is fine.
+
+**Worth knowing before you automate it.** A timer reclaims on the strength of a
+liveness signal that may not be written — heartbeats are optional, and the
+process check is what usually answers — so a session that claims an item and
+then works for half an hour can look the same as one that crashed. Reclaiming at
+the point of contention, when another session actually wants that item, is a
+safer place to be wrong than a fixed tick. Escalation is the part that genuinely
+needs a push, because nobody is reading by definition.
+
+### Postgres
+
+This app needs its own Postgres reachable via `DATABASE_URL`. Prefer a
+**dedicated Postgres instance** over adding a database to one that already
+serves another app — it keeps credentials, backups, and version upgrades
+independent, and the cost of one more small container is low. Only share an
+existing instance if there's a specific reason to (e.g. a hosting limit on
+how many database services are allowed).
+
+If Postgres runs as its own container next to this one, order startup with
+`depends_on: condition: service_healthy` — the entrypoint runs
+`prisma migrate deploy` at boot, which opens a real database connection even
+when there are zero pending migrations (expect and ignore
+`No migration found in prisma/migrations` until the baseline migration
+ships — see `MILESTONES.md`). Give Postgres's own health check a generous
+`start_period`: a cold first boot (`initdb` plus the official image's own
+internal restart) can take noticeably longer than a short window allows,
+which can make `depends_on` give up right before Postgres would have come up
+healthy on its own.
+
+### Deploying alongside other services
+
+Some hosts run several unrelated apps under one shared Docker Compose
+project rather than one compose file per app — a shared `.env` holding
+per-service location/config variables, one compose file defining every
+service, sub-folders per service holding data only. If that's the target,
+fold this app's service block (and a Postgres block per the section above)
+into the shared file instead of running `docker-compose.prod.yml` standalone
+— the service definitions are the same either way, only which file they live
+in changes. In that setup:
+
+- **Back up the shared compose file first**, before editing it.
+- **Never run a bare `up`, `down`, or `restart` with no service names** in a
+  directory that already has other services running from that file — always
+  name the services you mean to affect explicitly, e.g.
+  `docker compose up -d agent-standup agent-standup-db`. An unscoped command
+  recreates (or stops) everything the file defines, not just what you're
+  deploying.
+- **Pick a host port that isn't already in use** — check what the shared
+  compose file and the host's listening ports already claim before adding
+  `APP_PORT`.
+- Keep real secrets (the generated `DATABASE_URL` password, etc.) only in
+  that host's own `.env` — never copied into this repo.
+
+## What is built
+
+The service layer holds **69 registered operations** (`src/lib/service/registry.ts`). Every rule
+lives there, so an adapter is a thin shell over one service call and adds no rule of its own —
+which is what makes a refusal the same refusal whichever way in you came.
+
+**The four adapters do not all expose the same set, and the difference is worth knowing before you
+pick one.** MCP derives its tools from the registry and so carries 66 of the 69, declining three by
+written waiver (`src/lib/adapters/waivers.ts`). The command line routes 46 and the web API 49,
+because each maps operations through its own table and those tables lag the registry — `service_info`
+and `describe_tool`, for instance, are reachable from MCP and the command line but have no HTTP
+route. Ask a running instance rather than taking any of this on trust:
+
+```bash
+standup service info --json      # the operation catalogue, and the limits a caller must respect
+standup --help                   # every noun and verb, built from the command table itself
+```
+
+| Surface          | What it is                                                                                                                                                                                                                                                             |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Web API**      | 45 operations over JSON routes under `src/app/api` — items, claims, transitions, artifacts, events, settings, admin entities. Three further routes are not part of that surface: a liveness check, the MCP transport below, and one that serves the hook script itself |
+| **MCP**          | The agent-facing surface, over streamable HTTP (`/api/mcp`) and over stdio. Tools are derived from the operation registry, so there is no second list to forget an operation in                                                                                        |
+| **Command line** | `standup <noun> <verb>`, 46 operations, on either of two bindings — over HTTP against a server, or `--direct` against `DATABASE_URL` in-process                                                                                                                        |
+| **Front end**    | The board, an item detail view, a since-your-last-visit ledger, a settings editor and an admin section                                                                                                                                                                 |
+
+An item minted through the product walks the full state machine on service calls alone —
+`plan_review → executing → in_review → merged` — because the artifacts each transition guard reads
+are writable through the service. The rules are enforced in the service layer, so a refusal is the
+same refusal on every surface: a missing approving review at tip, a claim already held, or a
+completion with no structured summary is rejected identically whether it arrived from an agent, a
+terminal or the API.
+
+The schema ships as one baseline migration, and a one-time bulk import (`docs/plans/BACKFILL.md`)
+loads a backlog held in an external file-based store.
+
+**Where the edges are.** [`MILESTONES.md`](docs/plans/MILESTONES.md) is the honest inventory: it
+carries every row with its status, and the queue is worked in dependency order rather than
+front-to-back. One limit is worth knowing before deploying: the liveness sweep only runs when
+something invokes it — see above, because claims leak while nothing does.

package/dist/bin/standup-hook.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+import {
+  HOOK_EXIT,
+  captureContextFor,
+  createHttpFlush,
+  fileAppendCounter,
+  fileSpool,
+  flushSpool,
+  parseHookPayload,
+  readNudgeContext,
+  readSessionStatus,
+  readStopContext,
+  runHook,
+  spoolEvent,
+  spoolPath
+} from "../chunk-N7G677FC.js";
+import {
+  SHIPPED_HOOK_PROTOCOL_VERSION,
+  buildCaptures
+} from "../chunk-VBXNDGOD.js";
+
+// src/lib/hook/ask-http.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+function property(value, key) {
+  return typeof value === "object" && value !== null ? value[key] : void 0;
+}
+function readFinding(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const record = value;
+  const id = record.id;
+  const level = record.level;
+  const phase = record.phase;
+  const messages = record.messages;
+  const plain = typeof messages === "object" && messages !== null ? messages.plain : void 0;
+  const prominent = typeof messages === "object" && messages !== null ? messages.prominent : void 0;
+  if (typeof id !== "string" || id.length === 0) return void 0;
+  if (typeof level !== "string" || level.length === 0) return void 0;
+  if (typeof phase !== "string" || phase.length === 0) return void 0;
+  if (typeof plain !== "string") return void 0;
+  return {
+    id,
+    // `source` and `audience` are not read by anything on this side of the
+    // wire — `buildCaptures` never asks for either — so they are carried
+    // through when present rather than invented when absent. A cast rather
+    // than a validated enum: an unrecognised value here changes nothing a
+    // capture writes, so rejecting the whole finding over it would lose
+    // real data to protect a property nobody reads.
+    source: typeof record.source === "string" ? record.source : "builtin",
+    phase,
+    audience: typeof record.audience === "string" ? record.audience : "agent",
+    level,
+    timing: typeof record.timing === "string" ? record.timing : "immediate",
+    messages: { plain, prominent: typeof prominent === "string" ? prominent : plain }
+  };
+}
+function readFindings(value) {
+  if (!Array.isArray(value)) return void 0;
+  const findings = [];
+  for (const entry of value) {
+    const finding = readFinding(entry);
+    if (finding !== void 0) findings.push(finding);
+  }
+  return findings;
+}
+function createHttpAsk({
+  baseUrl,
+  fetch,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  timeoutSignal = defaultTimeoutSignal
+}) {
+  const url = `${baseUrl.replace(/\/+$/, "")}/api/hook`;
+  return async function askServer(event) {
+    const signal = timeoutSignal(timeoutMs);
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          eventType: event.eventType,
+          sessionId: event.sessionId,
+          ...event.tool === void 0 ? {} : { tool: event.tool },
+          ...event.command === void 0 ? {} : { command: event.command },
+          ...event.toolResult === void 0 ? {} : { toolResult: event.toolResult }
+        }),
+        ...signal === void 0 ? {} : { signal }
+      });
+    } catch {
+      return void 0;
+    }
+    if (!response.ok) return void 0;
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      return void 0;
+    }
+    if (typeof body !== "object" || body === null || Array.isArray(body)) return void 0;
+    const rawDecision = property(body, "decision");
+    const reason = property(body, "reason");
+    const enforcement = readSessionStatus(property(body, "enforcement"));
+    const stop = readStopContext(property(body, "stop"));
+    const nudge = readNudgeContext(property(body, "nudge"));
+    const findings = readFindings(property(body, "findings"));
+    return {
+      // The one string that refuses. Everything else — including a value
+      // this build does not recognise — is an allow.
+      decision: rawDecision === "block" ? "block" : "allow",
+      ...typeof reason === "string" && reason.length > 0 ? { reason } : {},
+      ...enforcement === void 0 ? {} : { enforcement },
+      ...stop === void 0 ? {} : { stop },
+      ...nudge === void 0 ? {} : { nudge },
+      ...findings === void 0 ? {} : { findings }
+    };
+  };
+}
+function defaultTimeoutSignal(ms) {
+  return typeof AbortSignal?.timeout === "function" ? AbortSignal.timeout(ms) : void 0;
+}
+
+// src/lib/hook/record-intervention-http.ts
+var DEFAULT_RECORD_TIMEOUT_MS = 1500;
+function toWireBatch(batch) {
+  return {
+    sessionId: batch.sessionId,
+    ...batch.rootSessionId === void 0 ? {} : { rootSessionId: batch.rootSessionId },
+    captures: batch.captures.map((capture) => ({
+      entryId: capture.entryId,
+      outcome: capture.outcome,
+      level: capture.level,
+      phase: capture.phase,
+      ...capture.itemId === void 0 ? {} : { itemId: capture.itemId },
+      ...capture.tool === void 0 ? {} : { tool: capture.tool },
+      ...capture.command === void 0 ? {} : { command: capture.command },
+      ...capture.message === void 0 ? {} : { message: capture.message },
+      ...capture.overrideReason === void 0 ? {} : { overrideReason: capture.overrideReason }
+    }))
+  };
+}
+function readRecordedFirings(body) {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) return [];
+  const recorded = body.recorded;
+  if (!Array.isArray(recorded)) return [];
+  return recorded.flatMap((entry) => {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return [];
+    const row = entry;
+    const id = row.id;
+    const entryId = row.entryId;
+    if (typeof id !== "string" || id.trim() === "") return [];
+    if (typeof entryId !== "string" || entryId.trim() === "") return [];
+    return [{ id: id.trim(), entryId: entryId.trim() }];
+  });
+}
+function createRecordInterventionHttp(options) {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_RECORD_TIMEOUT_MS;
+  const makeSignal = options.timeoutSignal ?? ((ms) => typeof AbortSignal?.timeout === "function" ? AbortSignal.timeout(ms) : void 0);
+  return async (batch) => {
+    if (batch.captures.length === 0) return { ok: true, recorded: [] };
+    const signal = makeSignal(timeoutMs);
+    try {
+      const response = await options.fetch(
+        `${options.baseUrl.replace(/\/+$/, "")}/api/interventions`,
+        {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            ...options.token === void 0 || options.token === "" ? {} : { authorization: `Bearer ${options.token}` }
+          },
+          body: JSON.stringify(toWireBatch(batch)),
+          ...signal === void 0 ? {} : { signal }
+        }
+      );
+      if (!response.ok) return { ok: false, recorded: [] };
+      try {
+        return { ok: true, recorded: readRecordedFirings(await response.json()) };
+      } catch {
+        return { ok: true, recorded: [] };
+      }
+    } catch {
+      return { ok: false, recorded: [] };
+    }
+  };
+}
+
+// src/lib/hook/protocol.ts
+var HOOK_PROTOCOL_VERSION = SHIPPED_HOOK_PROTOCOL_VERSION;
+
+// src/lib/hook/build-stamp.ts
+var UNSTAMPED = "unstamped";
+var HOOK_BUILD_COMMIT = typeof __STANDUP_HOOK_BUILD_COMMIT__ === "string" ? __STANDUP_HOOK_BUILD_COMMIT__ : UNSTAMPED;
+function isStamped(commit) {
+  return commit !== UNSTAMPED && commit.trim() !== "";
+}
+function formatBuildStamp(commit) {
+  return isStamped(commit) ? commit : UNSTAMPED;
+}
+
+// src/bin/standup-hook.ts
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+async function main() {
+  const env = process.env;
+  if (process.argv.includes("--protocol-version")) {
+    process.stdout.write(`${HOOK_PROTOCOL_VERSION}
+`);
+    return HOOK_EXIT.ALLOW;
+  }
+  if (process.argv.includes("--build-commit")) {
+    process.stdout.write(`${formatBuildStamp(HOOK_BUILD_COMMIT)}
+`);
+    return HOOK_EXIT.ALLOW;
+  }
+  const baseUrl = env.STANDUP_URL?.trim();
+  const askServer = baseUrl === void 0 || baseUrl === "" ? async () => void 0 : createHttpAsk({ baseUrl, fetch: globalThis.fetch });
+  const stdin = await readStdin();
+  const now = Date.now();
+  const rendered = await runHook({
+    stdin,
+    askServer,
+    now,
+    // MILESTONES.md #128's capture loop. Fires only when `runHook` has
+    // findings to report — see its own header for why this is a callback
+    // rather than a return field. With no server configured there is
+    // nowhere to send a capture either, so this is `undefined` in exactly
+    // the case `askServer` above already degrades to "no answer" for.
+    ...baseUrl === void 0 || baseUrl === "" ? {} : { onFindings: recordFindings(baseUrl, env) }
+  });
+  if (rendered.stdout !== "") process.stdout.write(rendered.stdout);
+  if (rendered.stderr !== "") process.stderr.write(rendered.stderr);
+  const spool = fileSpool(spoolPath(env));
+  spoolEvent(stdin, spool, now, { appendCounter: fileAppendCounter(spoolPath(env)) });
+  if (isStop(stdin)) await drain(spool, baseUrl, env);
+  return rendered.exitCode;
+}
+function isStop(stdin) {
+  const parsed = parseHookPayload(stdin);
+  return parsed.ok && parsed.event.eventType === "Stop";
+}
+async function drain(spool, baseUrl, env) {
+  if (baseUrl === void 0 || baseUrl === "") return;
+  try {
+    const text = spool.read();
+    if (text === void 0 || text.length === 0) return;
+    const result = await flushSpool({
+      spoolText: text,
+      send: createHttpFlush({
+        baseUrl,
+        fetch: globalThis.fetch,
+        // The ingest authenticates unconditionally, so a tokenless flush is
+        // a permanent `401` and the spool would fill to its ceiling in
+        // silence. Read from the environment for the same reason the URL
+        // is: this script is configured by the thing that installs it.
+        ...env.STANDUP_TOKEN === void 0 || env.STANDUP_TOKEN.trim() === "" ? {} : { token: env.STANDUP_TOKEN.trim() },
+        ...flushTimeoutMs(env) === void 0 ? {} : { timeoutMs: flushTimeoutMs(env) }
+      })
+    });
+    if (result.sent === 0 && result.dropped === 0 && result.skipped === 0) return;
+    spool.replace(result.remaining);
+  } catch {
+  }
+}
+function flushTimeoutMs(env) {
+  const raw = env.STANDUP_FLUSH_TIMEOUT_MS?.trim();
+  if (raw === void 0 || raw === "") return void 0;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
+}
+function recordFindings(baseUrl, env) {
+  const send = createRecordInterventionHttp({
+    baseUrl,
+    fetch: globalThis.fetch,
+    ...env.STANDUP_TOKEN === void 0 || env.STANDUP_TOKEN.trim() === "" ? {} : { token: env.STANDUP_TOKEN.trim() }
+  });
+  return async (report) => {
+    try {
+      const captures = buildCaptures(report.findings, captureContextFor(report));
+      if (captures.length === 0) return;
+      await send({ sessionId: report.event.sessionId, captures });
+    } catch {
+    }
+  };
+}
+try {
+  process.exitCode = await main();
+} catch (cause) {
+  process.stderr.write(
+    `the hook failed unexpectedly (${cause instanceof Error ? cause.name : "unknown error"}) and allows rather than refusing a command it never examined
+`
+  );
+  process.exitCode = HOOK_EXIT.ALLOW;
+}