@pithy-sh/core 0.9.0 → 0.11.0

package/src/cli/commandFacts.ts

@@ -0,0 +1,220 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * **What the catalog cannot say about a `pithy` command, written down once (#711).**
+ *
+ * `commandCatalog.generated.ts` is the parser's own account of every command: its arguments, its flags, which
+ * are required, which have defaults, which go together. Four facts are not in any parser, and each was the
+ * fault behind a line that did not run as written:
+ *
+ * - **Which commands act on one Worker**, and are refused `input/required` without `--worker` where a project
+ *   has several. `packages/cli/src/ci/runnableCommands.test.ts` proves every entry by running it in a
+ *   two-Worker project, and fails on a command that takes `--worker` and is not classified here.
+ * - **Which flag's default changes what the command acts on.** `pithy vector provision` with no `--env`
+ *   provisions `dev`, so a line about staging that leaves it off sends the reader to the wrong environment.
+ * - **Which commands destroy something**, and are never a remedy for a smaller fault. `pithy feature destroy`
+ *   was offered as the fix for one mis-shaped vector index.
+ * - **Which flag needs another beside it** that the parser does not enforce: `pithy provision --env` is refused
+ *   without `--yes`, at run time.
+ *
+ * `command.ts` builds every command a line names from these and the catalog, and refuses one that breaks them.
+ * Nothing here imports anything, so a Worker that names a command pays for two tables and nothing more.
+ */
+
+/**
+ * The commands that act on exactly one Worker, and refuse `input/required` without `--worker` when a project
+ * has several and the run cannot ask. Every line that names one names the Worker, by its `apps/` directory.
+ */
+export const WORKER_SCOPED = [
+  "add",
+  "dashboard connect",
+  "email provision",
+  "media provision",
+  "payments provision",
+  "storage provision",
+  "support provision",
+  "testers provision",
+  "turnstile deprovision",
+  "turnstile provision",
+  "ui add",
+  "ui sync",
+  "vector provision",
+  "vector reprocess",
+  "vector reset",
+  "worker sync",
+] as const;
+
+/** A command that acts on one Worker. */
+export type WorkerScopedPath = (typeof WORKER_SCOPED)[number];
+
+/**
+ * The commands that take `--worker` and do not need it: each fans out over every Worker, or falls back to the
+ * first that answers, and the flag narrows.
+ */
+export const WORKER_NARROWS = [
+  "contract",
+  "dashboard disconnect",
+  "dashboard revoke-key",
+  "dashboard rotate",
+  "dashboard status",
+  "doctor",
+  "env",
+  "init",
+  "migrate",
+  "secrets tables",
+  "seed",
+  "support deprovision",
+  "upgrade",
+] as const;
+
+/**
+ * A command only a person runs, at a terminal, where the Worker is asked for. `pithy remove` refuses every run
+ * that cannot ask (`core/person_required`).
+ */
+export const PERSON_ONLY = ["remove"] as const;
+
+/** A flag that turns a Worker-scoped command into one that acts on no Worker: `pithy add --list` reads the catalog. */
+export const NO_WORKER_MODES: Readonly<Record<string, readonly string[]>> = { add: ["--list"] };
+
+/**
+ * **A flag whose default decides what the command acts on.** Left off a line, the command still runs — on the
+ * default, which is rarely the environment the line was about. Every `--env` with a default is one: `dev` for
+ * `vector provision`, `migrate` and `testers list`, `staging` for `payments reconcile`. A line names it, always.
+ */
+export const MEANING_FLAGS = ["--env"] as const;
+
+/**
+ * The commands whose `--env` decides nothing until another flag asks it to: `pithy remove` touches no database
+ * without `--drop`, and `pithy upgrade` migrates none without `--migrate`. Without that flag a line need not
+ * name the environment; with it, it must.
+ */
+export const MEANING_ONLY_WITH = { remove: "--drop", upgrade: "--migrate" } as const;
+
+/**
+ * **The commands that destroy something, by what they destroy.** None is ever built as a remedy: a line that
+ * names one says it is a person's decision and what it deletes (`command.ts`'s `personDecision`), and carries
+ * no `fix`. `packages/core/src/cli/command.test.ts` holds every command the catalog has to this list or to
+ * {@link NOT_DESTRUCTIVE}, so a new one cannot arrive unexamined.
+ */
+export const DESTRUCTIVE_COMMANDS = {
+  "dashboard disconnect": "the environment's dashboard connection and the key it signs with",
+  "dashboard revoke-key": "a signing key the dashboard holds",
+  "email deprovision": "the email Workers, and with --suppression the suppression database",
+  "feature destroy": "the feature's worktree, its branch and every resource it provisioned",
+  "media deprovision": "the media Worker, and with --storage its bucket",
+  remove: "a capability's wiring",
+  "secrets deprovision": "the secrets manager, and with --keys the store's keys",
+  "secrets rm": "a stored secret",
+  "storage deprovision": "the storage Worker, and with --storage its bucket",
+  "support deprovision": "the support Workers, and with --storage its attachments",
+  "testers deprovision": "the testers Worker",
+  "token revoke": "an API token",
+  "turnstile deprovision": "the Turnstile widget, whose sitekey every client embeds",
+  "vector reset": "every vector in the index",
+  "worker remove": "a Worker's directory",
+} as const;
+
+/** A command that destroys something. */
+export type DestructivePath = keyof typeof DESTRUCTIVE_COMMANDS;
+
+/**
+ * **The flags that make a command destroy something**, on any command that declares them. Each is refused by
+ * the builder; a line that needs one is a person's decision.
+ */
+export const DESTRUCTIVE_FLAGS = {
+  "--destroy-retained": "a resource kept for recovery",
+  "--drop": "a capability's tables",
+  "--redo": "the data a seed wrote",
+  "--rollback": "the schema a migration group applied",
+} as const;
+
+/** A flag that makes a command destroy something. */
+export type DestructiveFlag = keyof typeof DESTRUCTIVE_FLAGS;
+
+/**
+ * The commands whose name reads as destructive and which are not, and why. A command named here is built like
+ * any other.
+ */
+export const NOT_DESTRUCTIVE: Readonly<Record<string, string>> = {
+  "cloudflare disconnect": "revokes a sign-in and deletes no data, which `cloudflare connect` gives back",
+  "docs disconnect": "removes the docs server from an editor's config, which `docs connect` restores",
+  "feature prune": "forgets worktrees that are already gone",
+  "testers close": "stops a cohort accruing, and keeps its history",
+  "testers remove": "takes one tester off a roster, which `testers invite` reverses",
+};
+
+/**
+ * **A flag whose value is a person's confirmation**, never written into a line an agent reads: a phrase spelled
+ * in a remedy is a confirmation nobody gave. A person's decision names the flag and leaves the phrase to them.
+ */
+export const CONFIRM_FLAGS = ["--confirm", "--confirm-production", "--confirm-reset", "--confirm-rollback"] as const;
+
+/**
+ * When a command asks for a confirmation: always, when a flag is passed (`when`), or in every environment but the
+ * ones it trusts (`unlessEnv`) — `vector reset` asks nothing of `dev`, whose index is a laptop's.
+ */
+export const CONFIRMATIONS: readonly { path: string; when?: string; unlessEnv?: readonly string[]; flag: string }[] = [
+  { path: "vector reset", unlessEnv: ["dev"], flag: "--confirm-reset" },
+  { path: "migrate", when: "--rollback", flag: "--confirm-rollback" },
+  { path: "seed", when: "--redo", flag: "--confirm-reset" },
+];
+
+/**
+ * **A flag whose value is a credential**, never written into a line: an error's action reaches logs, a terminal
+ * scrollback and a `--json` consumer, none of which should hold a key. A run named again carries the flag's name
+ * and leaves its value to whoever passed it.
+ */
+export const CREDENTIAL_FLAGS = [
+  "--api-token",
+  "--r2-access-key-id",
+  "--r2-api-token",
+  "--r2-secret-access-key",
+] as const;
+
+/**
+ * The environments every project treats as production. A project can name more in `seed.productionEnvironments`;
+ * a builder that has them passes them.
+ */
+export const PRODUCTION_ENVIRONMENTS = ["prod", "production"] as const;
+
+/**
+ * **What a production run of a command needs from a person**, by command: the confirmation it asks for, or `null`
+ * for one that asks none. A production provision or seed is never a remedy — a line names it as a person's
+ * decision either way, and names a confirmation only when the command declares it: `testers provision` and
+ * `vector provision` take no `--confirm`, and a line that told a person to pass one would be refused.
+ */
+export const PRODUCTION_CONFIRMS = {
+  provision: "--confirm",
+  seed: "--confirm-production",
+  "secrets provision": null,
+  "testers provision": null,
+  "vector provision": null,
+} as const satisfies Readonly<Record<string, string | null>>;
+
+/** A command whose production run is a person's decision. */
+export type ProductionPath = keyof typeof PRODUCTION_CONFIRMS;
+
+/**
+ * **A command that acts on every environment when its `--env` is left off (#711)**, production among them. `pithy
+ * testers provision` with no `--env` provisions every declared environment, so the bare line touches production as
+ * surely as `--env prod` does, and is a person's decision for the same reason. Each declares `--env` with no
+ * default; `command.test.ts` holds that against the catalog.
+ */
+export const EVERY_ENVIRONMENT_WITHOUT_ENV = ["testers provision"] as const satisfies readonly ProductionPath[];
+
+/**
+ * **A command that acts on every environment on every run (#711)**, production among them, with no `--env` to narrow
+ * it. `pithy secrets provision` deploys each declared environment's manager and mints its store entries, so every line
+ * naming it touches production and is a person's decision — never the fix for one binding, one database or one
+ * setting. None declares `--env`; `command.test.ts` holds that against the catalog.
+ */
+export const EVERY_ENVIRONMENT_ALWAYS = ["secrets provision"] as const satisfies readonly ProductionPath[];
+
+/**
+ * A flag a command refuses to run without, beside another, that the parser does not enforce. `pithy provision
+ * --env <env>` with no `--yes` is refused before it does anything; a dry run needs neither.
+ */
+export const REQUIRED_BESIDE: readonly { path: string; with: string; needs: string; unless: string }[] = [
+  { path: "provision", with: "--env", needs: "--yes", unless: "--dry-run" },
+];

package/src/controlPlane/capability.ts

@@ -13,11 +13,18 @@ import { ControlPlaneConfig, type ControlPlaneConfigInput } from "./config/confi
 import { ControlPlaneConnection } from "./data/connection";
 import { CONTROL_PLANE_CONNECTIONS_TABLE, type ControlPlaneDatabase, controlPlaneTables } from "./data/tables";
 import type { CapabilityDeclaration } from "./discovery/adminRoute";
-import { type CapabilityHealthSource, capabilityHealthSources } from "./discovery/health";
+import { type CapabilityHealthSource, capabilityHealthSources, defineCapabilityHealth } from "./discovery/health";
 import { createControlPlaneVerifier } from "./http/guard";
 import { controlPlaneRouteDescriptors, registerControlPlaneRoutes } from "./http/routes";
+import {
+  type ComposedMigrationDatabase,
+  composeMigrationDatabases,
+  MIGRATION_HEALTH_KEYS,
+  readMigrationHealth,
+} from "./migrationState/migrationState";
 import { controlplane_0001_init } from "./migrations/0001_init";
 import { controlplane_0002_management_origin } from "./migrations/0002_management_origin";
+import { controlplane_0003_connection_principal } from "./migrations/0003_connection_principal";
 import { d1ReplayGuard } from "./replay/d1Guard";
 import type { ReplayGuard } from "./replay/guard";
 import {
@@ -79,6 +86,7 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
   const migrations: Record<string, Migration> = {
     "0001_init": controlplane_0001_init,
     "0002_management_origin": controlplane_0002_management_origin,
+    "0003_connection_principal": controlplane_0003_connection_principal,
   };
   const requiredBindings: BindingSpecInput[] = [
     // The app database — the connections table lives here, beside auth's and audit's. Not the secrets
@@ -132,6 +140,12 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
   // assembly, because an adopter is never offered such a scope and the number could never be granted.
   let health: ReadonlyMap<string, CapabilityHealthSource> = new Map();
 
+  // Every database this Worker binds and what this build declares for it (#729), composed by the same hook
+  // through `collectMigrationSets` — the function `pithy migrate` uses, so the route and `pithy doctor`
+  // compose the same way. The inputs differ on a D1 two Workers share: the CLI merges every co-bound
+  // Worker's sets and this Worker holds only its own, so `pending` and `undeclared` can differ there.
+  let migrationDatabases: readonly ComposedMigrationDatabase[] = [];
+
   const capability = defineCapability({
     name: "controlplane",
     // `@pithy-sh/core`'s version, stamped by `scripts/stampVersions.ts` — a Worker cannot read its own
@@ -164,6 +178,14 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
     // The seam describes itself too. Built from the same resolved `basePath` the routes mount on, so a
     // moved mount point is reported rather than becoming a lie a client believes.
     adminRoutes: controlPlaneRouteDescriptors(config.basePath),
+    // Two counts on the seam's own manifest entry, so a client sees *this environment is behind* on the read
+    // it already makes and calls the route only to see what. Behind `migrations:read`, which the route above
+    // requires — a connection without it gets no number rather than a zero. A database that cannot be read
+    // fails the producer, and the seam reports the summary unavailable rather than a partial total.
+    health: defineCapabilityHealth({
+      keys: MIGRATION_HEALTH_KEYS,
+      read: (c) => readMigrationHealth(c.env as Record<string, unknown>, migrationDatabases),
+    }),
     compose: ({ capabilities }) => {
       // Every capability, including those exposing nothing. A client rendering a capability it cannot
       // act on is useful; a client that cannot tell "no admin surface" from "not installed" is not.
@@ -186,6 +208,7 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
         config: { ...(cap.manifestConfig?.values ?? {}) },
       }));
       health = capabilityHealthSources(capabilities);
+      migrationDatabases = composeMigrationDatabases(capabilities);
     },
     middleware: [
       (app) => {
@@ -228,6 +251,7 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
         database,
         composedCapabilities: () => composed,
         composedHealth: () => health,
+        composedMigrations: () => migrationDatabases,
         now,
       });
     },

package/src/controlPlane/context.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { ControlPlaneActorKind } from "./data/connection";
 import { ControlPlaneScope } from "./scope/scope";
 
 /**
@@ -56,6 +57,9 @@ export const ControlPlaneContext = z
     tokenId: z
       .string()
       .describe("The token's `jti`, already claimed in the replay set. Recorded to tie one audit event to one call."),
+    actorKind: ControlPlaneActorKind.nullable().describe(
+      "What kind of client the connection is for — `agent`, `dashboard` or `script` — read from the adopter's own row, never from the token. The gate stamps it onto every control-plane audit row this call writes. Null for a connection registered before the kind was recorded (#721).",
+    ),
   })
   .describe(
     "The verified control-plane caller for one request. Never an AuthContext: a management client is not a user of the adopter's app.",

package/src/controlPlane/data/connection.ts

@@ -66,6 +66,81 @@ export const RegisteredKey = z
   .describe("One registered public key with its validity window. Two live at once during a rotation overlap.");
 export type RegisteredKey = z.output<typeof RegisteredKey>;
 
+/**
+ * What kind of client a connection is for (#721): `agent`, `dashboard` or `script`.
+ *
+ * The audit trail's `actorType: "control-plane"` names all three identically, and the questions asked
+ * after an incident are exactly the ones that tell them apart — was it a person at the dashboard, a
+ * script somebody wrote, or an agent running unattended. So the kind is recorded on the connection when
+ * it is registered and stamped from there onto every row its calls write.
+ *
+ * It follows the path, never a guess: the device-code flow is a dashboard, always, and a key the
+ * operator registered themselves is whichever of the other two they say, out loud, with `--kind`.
+ */
+export const ControlPlaneActorKind = z
+  .enum(["agent", "dashboard", "script"])
+  .describe(
+    "What kind of client a connection is for: `agent` (an automated client acting on its own judgment, often unattended), `dashboard` (a management dashboard a person drives, registered through the device-code flow), or `script` (an operator's own automation, doing one fixed thing).",
+  );
+export type ControlPlaneActorKind = z.output<typeof ControlPlaneActorKind>;
+
+/**
+ * Who sanctioned a connection: the email address of the signed-in Cloudflare session that registered it.
+ *
+ * **A plain string, deliberately not a reference.** An adopter's `pithy_auth_users` are their customers,
+ * and the operator who registers a connection is their staff, so a join into the organization model would
+ * be empty for most of them. A string is readable by anybody, and matchable against a directory where the
+ * operator is in one.
+ *
+ * **Derived, never asserted.** No flag supplies it; the CLI reads it from `GET /user` under the session.
+ */
+export const ConnectionPrincipal = z
+  .email()
+  .max(254)
+  .describe(
+    "The email address of the person who sanctioned this connection, read from their signed-in Cloudflare session at registration. Never typed, so never asserted.",
+  );
+export type ConnectionPrincipal = z.output<typeof ConnectionPrincipal>;
+
+/** The longest purpose a connection may carry. One line on a review screen, with room to say what it does. */
+export const MAX_CONNECTION_PURPOSE = 200;
+
+/**
+ * Characters a purpose may not carry: every C0 and C1 control (so no terminal escape, no newline and no
+ * carriage return), the Unicode line and paragraph separators, every `Bidi_Control` character — the
+ * embeddings, overrides and isolates, and the LRM, RLM and ALM marks — that lets text render in a
+ * different order from the one it is stored in, and the invisible zero-width space, word joiner and
+ * byte-order mark that split a word without showing it. The zero-width joiner and non-joiner stay: Persian
+ * and the Indic scripts cannot be written without them.
+ *
+ * Each of those is a way for a sentence to look like something else once it reaches a renderer: a line
+ * in `pithy dashboard status` forged beneath the real one, a screen cleared, a scope name read backwards.
+ * Escaping them at every renderer is a promise each renderer has to keep. Refusing them at the boundary
+ * is one promise, kept here.
+ */
+const UNRENDERABLE = /[\p{Cc}\p{Bidi_Control}\u2028\u2029\u200B\u2060\uFEFF]/u;
+
+/**
+ * What a connection is for, in the words of whoever registered it (#721).
+ *
+ * **Required at registration, and refused when absent**, because a review listing credentials by key id
+ * cannot support the decision it exists for. **Untrusted input**: a customer writes it and something else
+ * renders it, so it is validated on the way in, and again on every read of the row.
+ */
+export const ConnectionPurpose = z
+  .string()
+  .trim()
+  .min(1, "Say what this client is for.")
+  .max(MAX_CONNECTION_PURPOSE, `A purpose is ${MAX_CONNECTION_PURPOSE} characters at most.`)
+  .refine(
+    (purpose) => !UNRENDERABLE.test(purpose),
+    "A purpose is one line of plain text: no control, bidi or invisible characters.",
+  )
+  .describe(
+    `What this connection's client is for, in the registering operator's words — one line of plain text, ${MAX_CONNECTION_PURPOSE} characters at most, with no control, bidi or invisible characters. Written by a customer and rendered elsewhere, so validated at the boundary.`,
+  );
+export type ConnectionPurpose = z.output<typeof ConnectionPurpose>;
+
 /**
  * One management-client connection — the row in `pithy_controlplane_connections`.
  *
@@ -112,6 +187,21 @@ export const ControlPlaneConnection = z
       .describe(
         "Where the management client that registered this connection answers — the origin the CLI calls for a verify, a rotation or a disconnect. Stored because it is not derivable: `issuer` is what that client *signs as*, and nothing says a dashboard's API answers at its own `iss`. Null for a connection registered before this column, which reads as the issuer rather than as the hosted dashboard — an older row is still a row about somebody's own deployment. Nothing on the Worker's side reads it; verification cares about `issuer` alone.",
       ),
+    authorizedBy: ConnectionPrincipal.nullable()
+      .default(null)
+      .describe(
+        "Who sanctioned this connection: the email of the signed-in Cloudflare session that registered it, never a flag. Null for a connection registered before principals were recorded (#721), which keeps working and reads as exactly that; registering again is the only way to set it.",
+      ),
+    actorKind: ControlPlaneActorKind.nullable()
+      .default(null)
+      .describe(
+        "What kind of client this connection is for — `agent`, `dashboard` or `script` — stamped onto every audit row its calls write so the trail can tell them apart. Null for a connection registered before it was recorded.",
+      ),
+    purpose: ConnectionPurpose.nullable()
+      .default(null)
+      .describe(
+        "What this connection's client is for, in the registering operator's words. Required at registration and editable with `pithy dashboard connect --update --purpose`; null only for a connection registered before it was recorded.",
+      ),
     scopes: sqliteJson(z.array(ControlPlaneScope)).describe(
       "The operations this connection was granted, stored and enforced on the adopter's side. Enforced only by the caller, a scope would not be a limit at all.",
     ),

package/src/controlPlane/error/errors.ts

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import { commandName } from "../../cli/command";
 import { PithyError } from "../../error/pithyError";
 import type { MessageParams } from "../../i18n/catalog";
 
@@ -40,7 +41,9 @@ export class ControlPlaneNotConnectedError extends PithyError {
         code: "controlplane/not_connected",
         status: 403,
         message: args.message ?? "No management client is connected to this environment.",
-        action: args.action ?? "Run pithy dashboard connect --env <environment> to register one.",
+        action:
+          args.action ??
+          `Register one for this environment with ${commandName("dashboard connect")}, naming it with --env.`,
         detail: args.detail,
         params: args.params,
       },
@@ -60,7 +63,9 @@ export class ControlPlaneInvalidCredentialError extends PithyError {
         code: "controlplane/invalid_credential",
         status: 401,
         message: args.message ?? "That credential is not valid here.",
-        action: args.action ?? "Rotate the connection's key, or re-run pithy dashboard connect --update.",
+        action:
+          args.action ??
+          `Rotate the connection's key, or update this environment's connection with ${commandName("dashboard connect")} and its --update flag.`,
         detail: args.detail,
         params: args.params,
       },
@@ -77,7 +82,9 @@ export class ControlPlaneInsufficientScopeError extends PithyError {
         code: "controlplane/insufficient_scope",
         status: 403,
         message: args.message ?? "This connection is not scoped for that operation.",
-        action: args.action ?? "Re-run pithy dashboard connect --update and grant the scope this call needs.",
+        action:
+          args.action ??
+          `Update this environment's connection with ${commandName("dashboard connect")} and its --update flag, granting the scope this call needs.`,
         detail: args.detail,
         params: args.params,
       },

package/src/controlPlane/http/cors.ts

@@ -217,10 +217,10 @@ export function corsMiddleware(
 /**
  * Mount one `app.use(path, …)` per entry.
  *
- * **Called from the capability's `middleware` hook, never its `routes` hook, and that is load-bearing.**
- * `createBackend` runs every capability's `middleware` hook before **any** capability's `routes` hook
- * (`createBackend.ts:262-267`), which is what makes this independent of the order an adopter happens to
- * list their capabilities in.
+ * **Called from `createBackend` ahead of every capability's `middleware`, never from a `routes` hook,
+ * and that is load-bearing.** Registered there, it is independent of the order an adopter happens to
+ * list their capabilities in, and it can put a header on whatever a capability's middleware or a
+ * readiness guard short-circuits.
  *
  * From `routes` it looks like it works and does not. The preflight still answers — an `OPTIONS` has no
  * route handler to lose to, so this `use` is the only thing that matches it — but a capability composed

package/src/controlPlane/http/guard.ts

@@ -2,11 +2,15 @@
 // SPDX-License-Identifier: MIT
 
 import type { MiddlewareHandler } from "hono";
+import type { AuditEmit } from "../../audit/recorder";
 import type { PithyHonoEnv } from "../../capability/capability";
+import { commandName, remedy } from "../../cli/command";
+import { type AmbientEnv, compositionEnvironment } from "../../env/ambient";
 import { PithyError } from "../../error/pithyError";
 import { workerVersionMetadata } from "../../worker/identity";
 import { ControlPlaneAuditActions, safeEmit } from "../audit/actions";
 import type { ControlPlaneContext } from "../context";
+import type { ControlPlaneActorKind } from "../data/connection";
 import { ControlPlaneNotConnectedError } from "../error/errors";
 import type { ControlPlaneRequirement } from "../scope/scope";
 import { CONTROL_PLANE_HEADER, CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER } from "../wire";
@@ -55,7 +59,7 @@ export type ControlPlaneVerifier = (
  */
 export function createControlPlaneVerifier(deps: ControlPlaneVerifyDeps): ControlPlaneVerifier {
   return async (request, requirement) => {
-    // Clone before reading. The handler still has to parse this body through `zValidator`, and a stream
+    // Clone before reading. The handler still has to parse this body through `validate`, and a stream
     // consumed here would reach it empty — the digest check would pass and the request would then fail
     // validation for no visible reason.
     const body = new Uint8Array(await request.clone().arrayBuffer());
@@ -138,7 +142,7 @@ export function requireControlPlane(requirement: ControlPlaneRequirement): Middl
     if (!verify) {
       const denial = new ControlPlaneNotConnectedError({
         message: "This deployment does not accept management-client calls.",
-        action: "Add `controlplane()` to this Worker's pithy.config.ts, then run pithy dashboard connect.",
+        action: `Add \`controlplane()\` to this Worker's pithy.config.ts, then ${connectStep(compositionEnvironment(c.env as unknown as AmbientEnv))}.`,
         detail: "no control-plane verifier on the request — the controlplane capability is not composed",
       });
       await auditDenial(c, requirement, denial);
@@ -154,6 +158,11 @@ export function requireControlPlane(requirement: ControlPlaneRequirement): Middl
     }
 
     c.set("controlPlane", context);
+    // Every control-plane row this call writes says which kind of client wrote it (#721). Stamped here,
+    // once, rather than at each of the dozens of emit sites across the capabilities, because a rule kept
+    // at the call sites regrows the moment someone adds one — and `actorType` alone names an agent, the
+    // dashboard and a script identically.
+    c.set("emit", stampActorKind(c.var.emit, context.actorKind));
     await safeEmit(
       c.var.emit,
       {
@@ -183,6 +192,20 @@ export function requireControlPlane(requirement: ControlPlaneRequirement): Middl
   return guard;
 }
 
+/**
+ * The recorder a verified call's handlers write through: the request's own, with the connection's actor
+ * kind added to every `control-plane` event that does not already carry one.
+ *
+ * Only `control-plane` events, because the kind describes a management client and nothing else — a
+ * handler recording what happened to a user is recording a user. An event that states a kind keeps it.
+ * A connection with no recorded kind adds nothing, so its rows read exactly as they did before.
+ */
+export function stampActorKind(emit: AuditEmit, actorKind: ControlPlaneActorKind | null): AuditEmit {
+  if (actorKind === null) return emit;
+  return (event) =>
+    emit(event.actorType === "control-plane" && event.actorKind == null ? { ...event, actorKind } : event);
+}
+
 /**
  * Record a refused call.
  *
@@ -221,3 +244,13 @@ async function auditDenial(
     c.var.log,
   );
 }
+
+/**
+ * The step that connects a management client, as this deployed Worker can name it: with its own environment when
+ * it knows it, and never with a Worker — it cannot know the `apps/` directory that provisioned it (#711).
+ */
+function connectStep(env: string | undefined): string {
+  if (env === undefined)
+    return `connect one with ${commandName("dashboard connect")}, naming this environment with --env`;
+  return remedy("dashboard connect", { flags: { "--env": env } }, { runtime: true }).say((command) => `run ${command}`);
+}

package/src/controlPlane/http/handlers.ts

@@ -3,6 +3,7 @@
 
 import type { Context } from "hono";
 import type { PithyHonoEnv } from "../../capability/capability";
+import { causeMessage } from "../../error/cause";
 import { workerVersion } from "../../worker/identity";
 import { ControlPlaneAuditActions, safeEmit } from "../audit/actions";
 import type { ControlPlaneConfig } from "../config/config";
@@ -14,8 +15,10 @@ import type { CapabilityDeclaration, ControlPlaneManifestWire } from "../discove
 import { type CapabilityHealthSource, readCapabilityHealth } from "../discovery/health";
 import { healthWire } from "../discovery/healthSummary";
 import { ControlPlaneInvalidCredentialError, ControlPlaneKeyConflictError } from "../error/errors";
+import { type ComposedMigrationDatabase, readDatabaseMigrations } from "../migrationState/migrationState";
 import type {
   ControlPlaneKeysResponse,
+  ControlPlaneMigrationsResponse,
   ControlPlanePingResponse,
   ExpireKeyResponse,
   PublicKeyView,
@@ -68,6 +71,11 @@ export interface ControlPlaneHandlerDeps {
    * value is not: the numbers are resolved per request, behind the scope each one is declared under.
    */
   composedHealth: () => ReadonlyMap<string, CapabilityHealthSource>;
+  /**
+   * Every database this Worker binds, with the provider this build composes for it — captured by the same
+   * `compose` hook through `collectMigrationSets`, the function `pithy migrate` composes with (#729).
+   */
+  composedMigrations: () => readonly ComposedMigrationDatabase[];
   /** The clock, injected so a test can stand at any instant. */
   now: () => Date;
 }
@@ -203,6 +211,34 @@ export function manifestHandler(deps: ControlPlaneHandlerDeps) {
   };
 }
 
+/**
+ * `GET /control-plane/migrations` — where each database this Worker binds stands (#729).
+ *
+ * Read-only: it reports, and nothing over the seam runs, reverses or resets a migration.
+ *
+ * **One unreadable ledger costs one database its answer.** Each read catches its own failure and lands on
+ * `unreadable`, so `Promise.all` still resolves and the route answers 200 with what it has. The cause is
+ * logged here, for the operator, and never projected: a D1 error can name a table or a query.
+ */
+export function migrationsHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>) => {
+    const context = caller(c);
+    const env = c.env as Record<string, unknown>;
+    const databases = await Promise.all(
+      deps.composedMigrations().map((entry) =>
+        readDatabaseMigrations(env, entry, (failed, cause) =>
+          c.var.log.warn("migration ledger unreadable", {
+            database: failed.database,
+            binding: failed.binding,
+            reason: causeMessage(cause) ?? String(cause),
+          }),
+        ),
+      ),
+    );
+    return c.json({ environment: context.environment, databases } satisfies ControlPlaneMigrationsResponse);
+  };
+}
+
 /** `GET /control-plane/keys` — the registration state, so a client can surface a stale key. */
 export function listKeysHandler(deps: ControlPlaneHandlerDeps) {
   return async (c: Context<PithyHonoEnv>) => {
@@ -212,6 +248,11 @@ export function listKeysHandler(deps: ControlPlaneHandlerDeps) {
       connectionId: connection.id,
       environment: connection.environment,
       keys: connection.keys.map(publicKeyView),
+      // The review a credential listing exists for needs these, and it is the adopter's to perform —
+      // on their own side, from their own row (#721).
+      authorizedBy: connection.authorizedBy,
+      actorKind: connection.actorKind,
+      purpose: connection.purpose,
     } satisfies ControlPlaneKeysResponse);
   };
 }