@rackbops/ac-plugin-contract 2.0.0-alpha.58 → 2.0.0-alpha.60

package/AUTHORING.md

@@ -39,6 +39,7 @@ key is itself a hard validation error, not a silently-ignored field.
   "kind": "in-process",
   "server": "dist/server.js",
   "frontend": "dist/ui.js",
+  "capabilities": ["agent.git.read"],
   "contributes": {
     "panels": [{ "id": "hello-panel", "title": "Hello", "route": "/hello", "export": "HelloPanel" }],
     "cards": [{ "id": "hello-card", "title": "Hello", "sizes": ["2x1"], "export": "HelloCard" }],
@@ -56,8 +57,7 @@ key is itself a hard validation error, not a silently-ignored field.
       { "id": "hello.machines", "schedule": "17 3 * * *", "timeoutSec": 30, "runOn": "agent" }
     ],
     "routes": [{ "method": "GET", "path": "/ping" }],
-    "settings": [{ "key": "greeting", "type": "string", "default": "hello" }],
-    "attention": true
+    "settings": [{ "key": "greeting", "type": "string", "default": "hello" }]
   }
 }
 ```
@@ -69,24 +69,28 @@ missing any of them fails `pnpm run check`. The complete shape (the `acPlugin` b
 ```jsonc
 {
   "name": "@ac/plugin-hello",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": true,
   "type": "module",
   "exports": { ".": { "default": "./dist/server.js" } },
   "acPlugin": { /* the block shown above */ },
   "scripts": {
     "typecheck": "tsc --noEmit && tsc -p tsconfig.ui.json --noEmit",
-    "build": "tsc && tsc -p tsconfig.ui.json",
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.ui.build.json",
     "test": "vitest run"
   },
   "dependencies": {
     "@ac/contract": "workspace:*",
-    "@rackbops/ui-react": "^0.2.36",
+    "@rackbops/ui-react": "^0.2.43",
     "react": "^19.2.0"
   },
   "devDependencies": {
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.1.0",
     "@types/node": "catalog:",
     "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "jsdom": "^30.1.1",
     "typescript": "catalog:",
     "vitest": "catalog:"
   }
@@ -144,12 +148,26 @@ no host I/O, so the host can construct every plugin before any side effect. All
 
 ```ts
 import type { CreatePlugin } from "@ac/contract"
+import { checkRow } from "./stored-row.js"
+
+export const DEFAULT_GREETING = "hello"
+
+function isString(value: unknown): value is string {
+  return typeof value === "string"
+}
 
 export const createPlugin: CreatePlugin = (host) => ({
   activate() {
     // GET /api/x/hello/ping → the greeting setting (its default comes from the manifest `settings[]`).
+    // A stored greeting that is not a string reads as unset (#900; see "Setting" below).
     host.routes.register("GET", "/ping", async () => {
-      const greeting = (await host.settings.get("greeting")) ?? "hello"
+      const greeting =
+        checkRow(await host.settings.get("greeting"), isString, {
+          log: host.log,
+          store: "plugin-settings",
+          key: "greeting",
+          expected: "string",
+        }) ?? DEFAULT_GREETING
       return Response.json({ greeting })
     })
     // An action: the button, its flags and the fields come from the manifest; the handler is here.
@@ -180,7 +198,12 @@ is never left open). Register last whatever must not exist when a later step fai
 
 - **Route** — `host.routes.register(method, path, handler)`. The handler is a web-standard
   `(request: Request) => Response | Promise<Response>`, mounted at `/api/x/<id><path>`. You may only register a
-  `(method, path)` you declared in `contributes.routes` — an undeclared route throws. **Never answer `502` or
+  `(method, path)` you declared in `contributes.routes` — an undeclared route throws.
+  `operator: true` on the route (#867): With the admin kill switch off (`admin_enabled = false`), the host
+  refuses this route for its declared method with `403 admin disabled`, as it refuses the admin plugin's own
+  surface. Mark an action or route an operator would expect the switch to shut: one that runs a job the job-run
+  route refuses, writes to GitHub or the store on the operator's behalf, or changes the console's configuration.
+  Additive; a host released before this field refuses a manifest that declares it. **Never answer `502` or
   `504` yourself** (#474): the production console is reached through Cloudflare, and Cloudflare's own
   documentation says it "returns a Cloudflare-branded HTTP 502 or 504 error when your origin web server responds
   with a standard HTTP 502 bad gateway or 504 gateway timeout error" — so on the production console (default
@@ -219,6 +242,11 @@ is never left open). Register last whatever must not exist when a later step fai
   same action again while that locked modal is up reuses it and does not re-run it. After a failed result the
   primary is enabled again and a retry runs, so a double-click whose first run fails fast can run the action
   twice (the second a retry): an action whose failure may have partly applied should tolerate that.
+  `operator: true` (#867): With the admin kill switch off (`admin_enabled = false`), the host refuses this
+  action (`POST /api/actions/<plugin>/<id>`) with `403 admin disabled`, as it refuses the admin plugin's own
+  surface. Mark an action or route an operator would expect the switch to shut: one that runs a job the job-run
+  route refuses, writes to GitHub or the store on the operator's behalf, or changes the console's configuration.
+  Additive; a host released before this field refuses a manifest that declares it.
   `confirm` stays a valid manifest flag, so an existing manifest keeps loading, but neither the modal nor the
   palette acts on it.
 - **Job** — implement `runJob(ctx)` and dispatch on `ctx.jobId`. The host runs only jobs you declared in
@@ -254,6 +282,27 @@ is never left open). Register last whatever must not exist when a later step fai
   carries it. See §7.
 - **Setting** — read/write with `host.settings.get(key)` / `host.settings.set(key, value)`. Both are async;
   `get` returns the manifest `default` when unset.
+- **Storage** — `host.storage.get(key)` / `host.storage.set(key, value)` / `host.storage.delete(key)`, async,
+  any JSON value, scoped to your plugin.
+- **Check the shape of what you read back** (#900). `get<T>` on either store is only a cast: the host
+  guarantees a row is valid JSON (a row that is not reads as unset, #879), never that it is the shape your
+  code expects. A hand edit, a restore from a damaged copy or an older version of your plugin can leave a
+  number where you wrote an object. So read untyped (`get(key)` answers `unknown`), check the fields you
+  dereference at the read site, and treat a row of the wrong shape as unset: your default applies (for a
+  setting, the manifest default), and log a warn line naming the key, never the value. Two refinements:
+  - if unset would **widen** what your plugin acts on (a deny list, a guard, a limit), refuse the row
+    instead and fail closed: an unreadable exclusion list must never mean "exclude nothing";
+  - for a row that keeps a list (a queue, a history), keep the good entries and drop only the bad ones,
+    and before you write such a row back over a value you could not read whole, keep the raw value
+    somewhere (`<key>/unreadable`), or one malformed entry, or a history saved in another shape, is lost
+    for good. Never write over a kept copy: if it already holds a different value, refuse the write
+    (fail the job or action, naming both keys) until the operator repairs the row or deletes the copy.
+
+  `plugins/hello`'s `/ping` is the worked example, and its `src/stored-row.ts` (`checkRow`, `requireRow`,
+  `checkList`, `checkMap`, `preserveUnreadable`) is the helper every bundled plugin copies: copy it into
+  yours, since plugins share no runtime code. It writes each line at most once an hour per row, so a
+  polled route over a bad row does not flood the log. The bundled plugins' lines and fields are in
+  `docs/identifiers.md` (#900's entry).
 - **Console settings** (#506) — `host.consoleSettings?.get(key)`, read-only, optional. Unlike `Setting`
   above (per-plugin), this reads the console-WIDE settings an operator edits in Admin's Settings card
   (`repo_owners`, `layout_file`, `tab_order`, `plan_default_machine`, `repo_pins`) -- but only a key on
@@ -261,7 +310,7 @@ is never left open). Register last whatever must not exist when a later step fai
   is the reference consumer (`repo_owners`/`repo_pins`, its own repo-set resolution).
 
 `createPlugin` must import from `@ac/contract` **type-only** (`import type`), so the compiled `dist/server.js`
-has no runtime imports — see §6.
+has no runtime import of it — see §6 (a sibling module of your own, such as `./stored-row.js`, is fine).
 
 ### Rejecting a bad action input — `ActionInputError` (#440)
 
@@ -616,6 +665,16 @@ A `hint` (optional, e.g. a category or the plugin id) is searched the same as `l
 `>hel` finds an item whose label doesn't contain "hel" but whose hint does — and renders as muted secondary
 text in the row.
 
+**What the chrome tolerates (#761).** A plugin bundle is built separately, so the shell does not trust the
+shapes it hands to the chrome. A quickcast source that throws or returns a non-array is skipped, and an item
+without a string `label` (or a `custom` item without a function `run`) is dropped, each logged with
+`console.warn` at most once a minute per source. A toast message that is not a string is shown as its
+`message` (an `Error`) or its `String()` form, and an unknown `severity` shows as `info`. A header button
+label is shown as `String(label)`, and a button whose `onClick` is not a function is not added. If one of the
+command palette, the toasts or the header buttons still fails to render, only that piece is replaced by a
+one-line note and the rest of the console stays. The types in `@ac/contract` remain the contract; this is a
+backstop, not a license.
+
 **Ctrl/Cmd+K from inside a same-origin iframe (#369).** A key pressed while an iframe has focus lands in the
 iframe's own document, never the shell's, so the palette does not open by itself. A panel that hosts a
 same-origin iframe (the Artifacts report preview does) forwards the hotkey: bind a `keydown` listener on the
@@ -695,34 +754,70 @@ Build it with `tsc` and `"jsx": "react-jsx"` — `tsc` under `nodenext` preserve
 import and injects `import { jsx } from "react/jsx-runtime"`, emitting exactly the servable ESM the import map
 resolves. Do **not** bundle (no rollup/esbuild bundling of React) — that would ship a second React copy.
 
-hello uses two tsconfigs so the server (no JSX) and the frontend (JSX) build separately:
+hello uses four tsconfigs. The server (no JSX) and the frontend (JSX) build separately, and each has a typecheck config that covers its tests and a build-only config that does not, so `build` never emits a compiled test into `dist/` (#350; `pnpm run check`'s `check-no-test-emit.mjs` fails otherwise, and `check-typecheck-covers-tests.mjs` fails if a test file is in no typecheck config):
 
-`tsconfig.json` (server):
+`tsconfig.json` (typecheck, server):
 
 ```json
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": { "rootDir": "src", "outDir": "dist" },
-  "include": ["src/server.ts", "src/server.test.ts"]
+  "include": [
+    "src/server.ts",
+    "src/server.test.ts",
+    "src/stored-row.ts",
+    "src/stored-row.test.ts",
+    "src/ac-host-drift.test.ts"
+  ]
 }
 ```
 
-`tsconfig.ui.json` (frontend):
+`tsconfig.ui.json` (typecheck, frontend):
 
 ```json
 {
   "extends": "../../tsconfig.base.json",
-  "compilerOptions": { "rootDir": "src", "outDir": "dist", "jsx": "react-jsx" },
-  "include": ["src/ui.tsx", "src/ui.test.tsx"]
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "jsx": "react-jsx",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"]
+  },
+  "include": ["src/ui.tsx", "src/ui.test.tsx", "src/quickcast.test.tsx", "src/ac-host.d.ts"]
 }
 ```
 
-and `package.json` builds + typechecks both:
+`tsconfig.build.json` (build, server):
+
+```json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "rootDir": "src", "outDir": "dist" },
+  "include": ["src/server.ts", "src/stored-row.ts"]
+}
+```
+
+`tsconfig.ui.build.json` (build, frontend):
+
+```json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "jsx": "react-jsx",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"]
+  },
+  "include": ["src/ui.tsx", "src/ac-host.d.ts"]
+}
+```
+
+and `package.json` builds with the build-only pair and typechecks with the other two:
 
 ```json
 "scripts": {
   "typecheck": "tsc --noEmit && tsc -p tsconfig.ui.json --noEmit",
-  "build": "tsc && tsc -p tsconfig.ui.json",
+  "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.ui.build.json",
   "test": "vitest run"
 }
 ```
@@ -874,12 +969,21 @@ if (outcome.ok) {
 }
 ```
 
+**Treat every string union in the contract as open** (`error.kind` here, `ToastSeverity`, `TaskStatus`,
+`PreflightStatus`, `OverviewOwner`, `ActionFieldType`, a filter token's `kind`): a later minor release may add a
+member, which the contract calls additive. Keep a default branch (no `assertNever`) in any `switch` over one.
+The unions most likely to grow carry a `MAY GROW` tag in their doc comment (`ActionFieldType` has grown before, #463, and may again; its doc comment is in the published schema, so it carries no tag).
+
 `outcome.error.kind === "grant"` is the one worth showing to the person almost verbatim -- it
 carries the agent's own refusal text (`"<capability> is not granted to <plugin> on <machine>"`). The
 others are the console's problem to describe differently: `unknown-machine` (a stale machine id),
-`refused` (the path isn't a `/v1/*` verb, or is `/v1/pair`/`/v1/grants` -- the control plane, never
+`refused` (the path isn't a `/v1/*` verb, or is `/v1/pair`/`/v1/grants`/`/v1/preflight`/`/v1/update` -- the control plane, never
 reachable this way, whatever the path spelling), `pin` (the agent's certificate changed since
-pairing), `network`, `http` (an unexpected status the console doesn't special-case).
+pairing), `network`, `http` (an unexpected status the console doesn't special-case). `ok: true` means the
+agent answered a 2xx and its body was read (#778): a 2xx whose body could not be read (a timeout or a reset
+mid-body, a body that is not JSON) is `ok: false`, `kind: "http"`, with that 2xx as `status` and the reason
+`agent answered <status> but its body could not be read: <cause>`. The agent may have acted on such a call,
+so a verb that starts something should not be retried blindly. A `204` is `ok: true` with no body.
 
 An agent job declares the capabilities its own verbs need, in the job's `capabilities` (#843). Each one
 must also be in the top-level list and match the capability grammar (`agent.` and lowercase segments).
@@ -952,10 +1056,20 @@ drawer shows: `{ status: "done" }` only for the agent's `done` frame with `statu
 `stream ended before done: <message>`, the drawer's last line without its brackets, when the stream
 closed or errored first or the `done` frame did not parse, so the job's own failure and a lost stream
 read differently. It never rejects. It never settles when the relay sees no end at all: the host
-stopping while the job runs (the relay stops with the process), or a hung job. It does not settle
-while the connection is silently gone, and never if it does not come back (a reboot, a lost NAT
-mapping): no FIN or RST reaches the host, and the stream has no body timeout, no keepalive and no
-agent heartbeat.
+stopping while the job runs (the relay stops with the process), or a hung job (the stream has no body
+timeout and the agent sends no heartbeat). A connection silently gone (no FIN or RST reaches the host:
+the machine asleep or off the network, a reboot, a lost NAT mapping) settles `failed` with
+`stream ended before done: terminated` once TCP keep-alive's probes go unanswered (#777), about 70 s
+after the last byte on the console's Linux host; a machine asleep for longer than that mid-job reads
+`failed` even if the job finishes after it wakes.
+
+A host restart mid-job is the one end the relay cannot report from inside the new process (#911): the
+host records each relay it opens and forgets it when the relay sees its end, and
+`host.agent.unfinishedStreams?()` (optional, like `finished`) returns, once, the calling plugin's relays
+that an earlier host process opened and never saw end, each `{ taskId, jobId, machineId, machineName,
+label, openedAt }` (the `taskId` is the earlier process's and no longer exists). Call it once in
+`activate()` and report each run as ended with an unknown outcome; `plugins/claude-runner` emits
+`claude.run` `status: "unknown"` for each. `ac jobs run` keeps no record and returns none.
 
 ```ts
 const { jobId } = await execResult // however the plugin's own verb call started the job
@@ -987,13 +1101,13 @@ by `${source}:${id}`.
 interface AttentionItem {
   id: string                 // unique within YOUR plugin; the rollup's dedupe key is `${source}:${id}`
   severity: "danger" | "warn" | "info"
-  source: string              // your own plugin id -- the rollup shows it as the row's source
+  source: string              // your own plugin id -- the dedupe key and draft scope; the rollup does not display it
   text: string                 // always a counted sentence: "3 open actions in the ledger", never "some actions"
   badge?: string
   href?: string                // an external link; wins over `target` when both are set. Linked only
                                // when its scheme is http:, https:, mailto: or tel: (#722); any other
                                // href is not linked and `target` is used instead
-  target?: string               // an in-app destination: "widget:<cardId>" or "panel:<pluginId>"
+  target?: string               // an in-app destination: "widget:<cardId>" (a home card: scrolls to and flashes it; text when the card is not on the page) or "panel:<pluginId>"
   hint?: string                  // the exact command to run, or the reason -- shown as a tooltip/expander
   action?: { kind: "issue"; repo?: string; title: string; body: string }  // opens provider-github's issue.create, seeded
 }
@@ -1129,9 +1243,9 @@ what it's for.
 |---|---|---|
 | Panel | `panels[]` (`id`, `title`, `route`, `export`, `nav?`, `order?`, `isolation?`) | a component export in `ui.js` |
 | Card | `cards[]` (`id`, `title`, `sizes`, `export`) | a component export in `ui.js` |
-| Action | `actions[]` (`id`, `scope`, `title?`, `confirm?`, `danger?`, `fields?`) | `host.actions.register({ id, run })` |
+| Action | `actions[]` (`id`, `scope`, `title?`, `confirm?`, `danger?`, `operator?`, `fields?`) | `host.actions.register({ id, run })` |
 | Job | `jobs[]` (`id`, `schedule`, `timeoutSec`, `runOn`, `minAgentVersion?`, `capabilities?`) | `runJob(ctx)` dispatching on `ctx.jobId` |
-| Route | `routes[]` (`method`, `path`) | `host.routes.register(method, path, handler)` |
+| Route | `routes[]` (`method`, `path`, `operator?`) | `host.routes.register(method, path, handler)` |
 | Setting | `settings[]` (`key`, `type`, `default?`) | read via `host.settings.get/set` |
 | Attention | `attention: true` | `host.routes.register("GET", "/attention", handler)` -> `{ ok: true, items }` |
 
@@ -1197,6 +1311,9 @@ bound for a slot, or `null` when none is. It throws unless the plugin's own mani
 `{slot, version}` in `contributes.consumes`, and an installed plugin may not resolve `auth` at all. Call
 it at request time (inside a route handler or job), never in `activate()`: providers bind during
 activation in load order, so a consumer that activates first would read `null` there for good.
+`host.slots.providerId?.(slot, version)` (#866, optional: a host older than #866 has none) answers the id of the
+plugin bound to a slot, or `null`, without the provider itself and without a `consumes` entry; an installed
+plugin may not read `auth`'s.
 `ac-artifacts-weft` (`artifacts@1`) is the reference consumer: the second plugin to declare `consumes`
 for it, after `artifacts`, which reads `provider-artifacts`' HTTP routes from the browser, and the first to
 call `resolve`. `hello` contributes none of the six points above via a slot (nor `attention` -- its own manifest

package/README.md

@@ -18,11 +18,20 @@ convention.
 
 - `import type { HostApi, Plugin, ... } from "@rackbops/ac-plugin-contract"` — the server-side types.
 - `@rackbops/ac-plugin-contract/schema.json` — the manifest JSON Schema, for a vendored drift check
-  against the live console (§5 of AUTHORING.md).
+  (§9 of AUTHORING.md, "Vendoring `schema.json` with a drift check"). The check compares your
+  committed copy with the one in the installed package, so it detects a version bump that changed
+  the schema; it does not look at a running console.
 - `@rackbops/ac-plugin-contract/host` — a types-only ambient declaration of `@ac/host` (the browser
   API a plugin's frontend imports at runtime, resolved through the console's own import map). Add it
   to your tsconfig's `"types"` array or a triple-slash reference — it carries no runtime export.
 
+## Unions are open
+
+Treat every string union this package exports (`AgentCallOutcome`'s `error.kind`, `ToastSeverity`,
+`TaskStatus`, `PreflightStatus`, `OverviewOwner`, `ActionFieldType` and the like) as open: a later minor
+release may add a member, so keep a default branch in any `switch` over one. The unions most likely to grow
+carry a `MAY GROW` tag in their doc comment.
+
 ## Version
 
 This package's version always equals the published `artifact-console` host's own version — pin your

package/dist/action-options.d.ts

@@ -46,4 +46,3 @@ export type ActionOptionsResponse = {
     ok: false;
     error: string;
 };
-//# sourceMappingURL=action-options.d.ts.map

package/dist/action-options.js

@@ -6,4 +6,3 @@
  * nothing here changes an existing field.
  */
 export {};
-//# sourceMappingURL=action-options.js.map

package/dist/attention.d.ts

@@ -3,8 +3,8 @@
  * `contributes.attention: true` in its manifest and serves `GET /api/x/<id>/attention` ->
  * `{ ok: true, items: AttentionItem[] }`. The `overview` plugin's rollup card polls every
  * contributor (discovered via `GET /api/plugins`'s `PluginView.attention`), merges, sorts by
- * severity, and dedupes by `${source}:${id}`. Ported from 1.x's `attentionRows` (`R:\repos\
- * artifacts-console\artifact-console\frontend\src\overview\attention.ts`) -- "own the fact, own
+ * severity, and dedupes by `${source}:${id}`. Ported from 1.x's `attentionRows` (the `artifacts-console`
+ * repo's overview `attention.ts`) -- "own the fact, own
  * the row": each plugin knows its own facts best, so the rollup itself derives nothing, it only
  * merges what contributors already computed.
  */
@@ -28,7 +28,7 @@ export interface AttentionItem {
     /** Unique within the contributing plugin; the rollup's dedupe key is `${source}:${id}`. */
     id: string;
     severity: AttentionSeverity;
-    /** The contributing plugin's id, e.g. "scans" -- the rollup shows it as the row's source. */
+    /** The contributing plugin's id, e.g. "scans" -- identifies the contributing plugin (dedupe key, draft scope); the rollup does not display it. */
     source: string;
     /** Always a counted sentence (1.x's `attCount`, e.g. "1 scheduled job run failed"). */
     text: string;
@@ -39,8 +39,9 @@ export interface AttentionItem {
      *  custom scheme, one that does not parse) renders no link, and the row uses `target` instead, as
      *  if `href` were absent. */
     href?: string;
-    /** An in-app destination: `widget:<cardId>` flashes/scrolls to a sibling card on Overview,
-     *  `panel:<pluginId>` navigates to that plugin's panel (its first panel route, or `/<pluginId>`
+    /** An in-app destination: `widget:<cardId>` scrolls to the home card whose `data-card-id` is
+     *  `<cardId>` or ends `:<cardId>`, and flashes it (when no such card is on the page the row is
+     *  plain text), `panel:<pluginId>` navigates to that plugin's panel (its first panel route, or `/<pluginId>`
      *  when the console knows none). A value that is not a string is ignored. */
     target?: string;
     /** The exact command to run, or the reason, shown as a tooltip/expander (1.x's `hint`). */
@@ -53,4 +54,3 @@ export interface AttentionResponse {
     ok: true;
     items: AttentionItem[];
 }
-//# sourceMappingURL=attention.d.ts.map

package/dist/attention.js

@@ -3,10 +3,9 @@
  * `contributes.attention: true` in its manifest and serves `GET /api/x/<id>/attention` ->
  * `{ ok: true, items: AttentionItem[] }`. The `overview` plugin's rollup card polls every
  * contributor (discovered via `GET /api/plugins`'s `PluginView.attention`), merges, sorts by
- * severity, and dedupes by `${source}:${id}`. Ported from 1.x's `attentionRows` (`R:\repos\
- * artifacts-console\artifact-console\frontend\src\overview\attention.ts`) -- "own the fact, own
+ * severity, and dedupes by `${source}:${id}`. Ported from 1.x's `attentionRows` (the `artifacts-console`
+ * repo's overview `attention.ts`) -- "own the fact, own
  * the row": each plugin knows its own facts best, so the rollup itself derives nothing, it only
  * merges what contributors already computed.
  */
 export {};
-//# sourceMappingURL=attention.js.map

package/dist/host-api.d.ts

@@ -28,7 +28,9 @@ export interface SettingsService {
 export interface ConsoleSettingsService {
     get<T = unknown>(key: string): Promise<T | undefined>;
 }
-/** Per-plugin durable storage: a SQLite table scoped to the plugin, with atomic JSON helpers. */
+/** Per-plugin durable storage: the plugin's rows in the host's shared `plugin_storage` table, keyed by
+ *  (plugin id, key), with plain `get`/`set`/`delete` over JSON values (an `undefined` value is stored as
+ *  `null`). */
 export interface StorageService {
     get<T = unknown>(key: string): Promise<T | undefined>;
     set(key: string, value: unknown): Promise<void>;
@@ -73,7 +75,9 @@ export interface JobDeclaration {
     id: string;
     runOn: "host" | "agent";
 }
-/** The typed event bus (e.g. `issue.changed`, `job.finished`, `artifact.rendered`). */
+/** The event bus: `emit(type: string, payload: unknown)` is untyped, so a type name is a convention between
+ * emitter and subscriber (the host emits `job.finished`; core plugins emit `artifacts.rendered` and
+ * `claude.run`; `issue.changed` is the documented example of a plugin-to-plugin event). */
 export interface EventsService {
     /** Calls every subscriber of `type` synchronously, in subscription order, and never awaits one.
      *  A subscriber that throws, or returns a promise that rejects, is logged by the host and stops
@@ -94,7 +98,10 @@ export interface GithubService {
     /** The one shared Octokit REST client — consumers make all GitHub calls through this. It
      *  authenticates with the console's PAT (`AC_GITHUB_TOKEN`), and `octokit().auth()` returns that
      *  token to whichever plugin asks: no `env[]` declaration is needed, and nothing hides it (#784;
-     *  in-process plugins are trusted code, not sandboxed). */
+     *  in-process plugins are trusted code, not sandboxed). Since #753 the client caps requests at 10 in
+     *  flight, retries a GET's 5xx (GraphQL and writes are POSTs and are not) and a short secondary limit once, gives each attempt 20 s, and rejects a
+     *  request at once with `GitHub rate limit exhausted until <ISO>` while a 403/429 has reported that
+     *  request's budget spent. */
     octokit(): Octokit;
     /** Remaining primary-rate-limit budget from the last response whose three `x-ratelimit-*` headers
      *  are all finite numbers (and the reset a valid time), a failed response's included (#784: a 403 or
@@ -158,9 +165,11 @@ export interface AgentService {
      * tasks drawer's last line without its brackets, when the stream closed or errored before its
      * `done` frame, or that frame did not parse. It never rejects. It never settles when the relay sees
      * no end at all: when the host stops while the job runs (the relay stops with the process), or when
-     * the job hangs. It does not settle while the connection is silently gone, and never if it does not
-     * come back (a reboot, a lost NAT mapping): with the machine asleep or the network gone, no FIN or
-     * RST reaches the host, and the stream has no body timeout, no keepalive and no agent heartbeat.
+     * the job hangs (the stream has no body timeout and the agent sends no heartbeat). A connection
+     * silently gone (the machine asleep or off the network, so no FIN or RST reaches the host) settles
+     * `failed` with `stream ended before done: terminated` once TCP keep-alive's probes go unanswered
+     * (#777), about 70 s after the last byte on the console's Linux host; a machine asleep for longer than
+     * that mid-job reads `failed` even if the job finishes after it wakes.
      */
     streamJob(machineId: string, jobId: string, opts: {
         label: string;
@@ -174,6 +183,22 @@ export interface AgentService {
             reason: string;
         }>;
     }>;
+    /**
+     * The relays this plugin opened with `streamJob` in an earlier host process whose end that process
+     * never saw (#911): a host restart mid-job. Each is returned once, then forgotten. A process that
+     * keeps no relay record (`ac jobs run`) and a host older than #911 return none or lack the method.
+     * `taskId` is the earlier process's task id, which no longer exists.
+     */
+    unfinishedStreams?(): Promise<UnfinishedStream[]>;
+}
+/** A `streamJob` relay whose end an earlier host process never saw (#911). */
+export interface UnfinishedStream {
+    taskId: string;
+    jobId: string;
+    machineId: string;
+    machineName: string;
+    label: string;
+    openedAt: string;
 }
 /** Proxy to a sidecar plugin's HTTP surface (the host handles health + base URL). */
 export interface SidecarService {
@@ -223,7 +248,8 @@ export type ActionInputErrorName = "ActionInputError";
  * know their callers' payload shapes either. Two providers for the same `slot@version` is a boot
  * error (auth/notify are singletons) -- surfaced by the host-side registry `provide` throws from, not
  * this interface, since this is the plugin's OWN scoped view (pre-bound to its id, so the error can
- * name the real offending plugin without a pluginId parameter here). */
+ * name the real offending plugin without a pluginId parameter here). `providerId` (#866) reads which
+ * plugin holds a binding without exposing it (the admin Security card reads `auth@1`'s). */
 export interface SlotRegistry {
     /** Register this plugin's provider instance for `slot@version`. Throws if that slot already has a
      *  provider (from this plugin or another) -- auth/notify are singletons, never a last-write-wins. */
@@ -238,6 +264,13 @@ export interface SlotRegistry {
      *  during activation in load order, so a consumer that activates before its provider would read `null`
      *  there for good (#97). */
     resolve<T = unknown>(slot: string, version: number): T | null;
+    /** The id of the plugin bound to `slot@version`, or `null` when nothing is bound (#866). Never the
+     *  provider itself, so it opens no way to the impl. Unlike `resolve` it needs no `contributes.consumes`
+     *  entry. An installed plugin may not read the `auth` slot's (it throws, naming the plugin), as it may
+     *  not resolve it. Optional: a host older than #866 has no such method, so check for it before calling
+     *  (`host.slots.providerId?.(slot, version)`). Call it at request time, never in `activate()`, for the
+     *  same load-order reason as `resolve`. */
+    providerId?(slot: string, version: number): string | null;
 }
 /** A logger prefixed with the plugin id. A plain-object first arg is the line's structured fields; an
  *  `Error` first arg is logged as its own enumerable properties (`code`, `status`, ...) plus
@@ -288,6 +321,11 @@ export interface HostApi {
     /** #506: see `ConsoleSettingsService`. Optional so an out-of-repo plugin's own test fake still
      *  compiles. */
     consoleSettings?: ConsoleSettingsService;
+    /** #875: `true` only in the process that serves HTTP and owns the plugins' on-disk state (`main.ts`);
+     *  absent in a one-shot CLI process (`ac jobs run`), which loads every plugin too. Work that must run
+     *  once per server boot, and must never run beside a live server (clearing a stale lock file under a
+     *  git clone, say), is gated on it. Optional so an out-of-repo plugin's own test fake still compiles. */
+    serving?: boolean;
 }
 /**
  * The context the host passes to `Plugin.runJob` for one job run (#31). `jobId` selects which
@@ -326,7 +364,7 @@ export interface Plugin {
 }
 /** A plugin's server entry: `dist/server.js` exports this as `createPlugin`. */
 export type CreatePlugin = (host: HostApi) => Plugin;
-/** Toast severity, matching notify. */
+/** Toast severity, matching notify. MAY GROW: keep a default branch. */
 export type ToastSeverity = "info" | "warning" | "error";
 /**
  * The browser-side `@ac/host` a frontend bundle imports. v1 (implemented in #32) is `theme` tokens +
@@ -454,4 +492,3 @@ export interface ActionSettledEvent {
     ok: boolean;
     error?: string;
 }
-//# sourceMappingURL=host-api.d.ts.map

package/dist/host-api.js

@@ -7,4 +7,3 @@
  * `HOST_API_VERSION`.
  */
 export {};
-//# sourceMappingURL=host-api.js.map

package/dist/index-envelope.d.ts

@@ -33,4 +33,3 @@ export interface PluginIndex {
     generatedAt?: string;
     plugins: PluginIndexEntry[];
 }
-//# sourceMappingURL=index-envelope.d.ts.map

package/dist/index-envelope.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=index-envelope.js.map

package/dist/index.d.ts

@@ -13,4 +13,3 @@ export * from "./ov-widgets.js";
 export type * from "./slots.js";
 export { HOST_API_VERSION, SLOTS } from "./version.js";
 export type * from "./views.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -6,4 +6,3 @@
 export * from "./issue-filter.js";
 export * from "./ov-widgets.js";
 export { HOST_API_VERSION, SLOTS } from "./version.js";
-//# sourceMappingURL=index.js.map

package/dist/issue-filter.d.ts

@@ -76,8 +76,9 @@ export interface AgeFilter {
  * Every axis is optional; an absent axis imposes no constraint. `priority`/`effort`/`type`/`tags` are
  * all "the record has a label whose name is in the set" -- the UI groups labels into these ladders
  * (from `labels.json`, #58), but for a plain value the predicate treats all four identically: a plain
- * label-name test. A token (#464a) adds `@any` and `@upto:<rung>` on the ladder axes, resolved against
- * `MatchContext.ladders`; `tags` has no ladder, so a token there matches nothing.
+ * label-name test. A token (#464a) adds `@any` (any ladder axis) and `@upto:<rung>` (priority and effort
+ * only; it matches nothing on `type`), resolved against `MatchContext.ladders`; `tags` has no ladder, so
+ * a token there matches nothing.
  */
 export interface IssueFilter {
     priority?: SetFilter;
@@ -119,4 +120,3 @@ export interface SavedView {
  * exactly as it always did, while a token that needs `ctx` matches nothing.
  */
 export declare function matchesIssue(record: IssueRecord, filter: IssueFilter, now: number, ctx?: MatchContext): boolean;
-//# sourceMappingURL=issue-filter.d.ts.map

package/dist/issue-filter.js

@@ -149,4 +149,3 @@ export function matchesIssue(record, filter, now, ctx) {
         matchesAge(ageBucket(record.updatedAt, now), filter.activity) &&
         matchesSearch(record, filter.search));
 }
-//# sourceMappingURL=issue-filter.js.map

package/dist/manifest.d.ts

@@ -103,6 +103,14 @@ export interface ActionContribution {
      *  asks for a second click. */
     confirm?: boolean;
     danger?: boolean;
+    /**
+     * With the admin kill switch off (`admin_enabled = false`), the host refuses this action (`POST /api/actions/<plugin>/<id>`) with
+     * `403 admin disabled`, as it refuses the admin plugin's own surface. Mark an action or route an operator
+     * would expect the switch to shut: one that runs a job the job-run route refuses, writes to GitHub or the
+     * store on the operator's behalf, or changes the console's configuration. Additive; a host released before
+     * this field refuses a manifest that declares it (#867).
+     */
+    operator?: true;
     /** The form the shell builds the action's modal from; omit for a no-input action. */
     fields?: ActionField[];
 }
@@ -149,6 +157,14 @@ export interface RouteContribution {
     method: HttpMethod;
     /** Path under the plugin's namespace, e.g. "/feed". */
     path: string;
+    /**
+     * With the admin kill switch off (`admin_enabled = false`), the host refuses this route for its declared method with
+     * `403 admin disabled`, as it refuses the admin plugin's own surface. Mark an action or route an operator
+     * would expect the switch to shut: one that runs a job the job-run route refuses, writes to GitHub or the
+     * store on the operator's behalf, or changes the console's configuration. Additive; a host released before
+     * this field refuses a manifest that declares it (#867).
+     */
+    operator?: true;
 }
 /** JSON scalar type of a plugin setting (rendered by Admin). */
 export type SettingType = "string" | "integer" | "number" | "boolean";
@@ -253,4 +269,3 @@ export interface PluginStateEntry {
         state: "healthy" | "degraded";
     };
 }
-//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.js

@@ -6,4 +6,3 @@
  * (`hostApiVersion`, `env[]`).
  */
 export {};
-//# sourceMappingURL=manifest.js.map

package/dist/ov-widgets.d.ts

@@ -8,6 +8,7 @@
  * to round-trip. RENAMING an `id` here orphans every stored layout that references it, the same as
  * 1.x's own comment warns; adding/reordering rows is safe.
  */
+/** MAY GROW: keep a default branch. */
 export type OverviewOwner = "overview" | "metrics-claude" | "repos" | "artifacts" | "provider-github";
 export interface OverviewWidget {
     id: string;
@@ -18,4 +19,3 @@ export interface OverviewWidget {
 export declare const OV_WIDGETS: readonly OverviewWidget[];
 /** The registry id `HomeCards` actually renders for one `OV_WIDGETS` row: `plugin:<owner>:<id>`. */
 export declare function ovRegistryId(widget: OverviewWidget): string;
-//# sourceMappingURL=ov-widgets.d.ts.map

package/dist/ov-widgets.js

@@ -30,4 +30,3 @@ export const OV_WIDGETS = [
 export function ovRegistryId(widget) {
     return `plugin:${widget.owner}:${widget.id}`;
 }
-//# sourceMappingURL=ov-widgets.js.map

package/dist/slots.d.ts

@@ -214,4 +214,3 @@ export interface NotifyProvider {
         signal?: AbortSignal;
     }): Promise<void>;
 }
-//# sourceMappingURL=slots.d.ts.map

package/dist/slots.js

@@ -14,4 +14,3 @@
  * built later in E5), so completing the v1 shape here is not a breaking change.
  */
 export {};
-//# sourceMappingURL=slots.js.map

package/dist/version.d.ts

@@ -28,4 +28,3 @@ export declare const SLOTS: {
         readonly version: 1;
     };
 };
-//# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -16,4 +16,3 @@ export const SLOTS = {
     auth: { name: "auth", version: 1 },
     notify: { name: "notify", version: 1 },
 };
-//# sourceMappingURL=version.js.map

package/dist/views.d.ts

@@ -82,6 +82,10 @@ export type PluginOrigin = "bundled" | "installed";
 export interface PluginView {
     id: string;
     enabled: boolean;
+    /** The enable state the next restart applies, when it differs from `enabled` (#767): an operator's persisted
+     *  choice (`POST /api/plugins/:id/enabled`) not yet applied, with `AC_PLUGINS_FORCE_ENABLED` winning as it does
+     *  at boot. Absent when the two agree. Additive. */
+    pendingEnabled?: boolean;
     /** Required even on an errored entry — it is a property of where the plugin came from, not of loading. */
     origin: PluginOrigin;
     error?: string;
@@ -142,7 +146,8 @@ export interface DeclarativeCardDef {
 }
 /** What started a task: a manually-triggered job (#31), an agent run (E4), or a sidecar run (E4/E6). */
 export type TaskKind = "job" | "agent" | "sidecar";
-/** `queued` (#51): an agent-job task waiting on an unreachable machine, badged red in the drawer. */
+/** `queued` (#51): an agent-job task waiting on an unreachable machine, badged red in the drawer.
+ *  MAY GROW: keep a default branch. */
 export type TaskStatus = "running" | "done" | "failed" | "queued";
 /**
  * The `GET /api/tasks` list item (#42) — the host's in-memory task registry's view of one run. Not a
@@ -180,9 +185,11 @@ export interface JobMachineRun {
      *  plugin every capability the job declares (#843; reason `not granted: <capability>[, ...]`, the
      *  missing ones in declared order), or its paired agent version compares lower than the job's
      *  declared `minAgentVersion` (#372, #80; reason `agent <version> < <min>`). A missing grant wins
-     *  when both hold. Computed live every call from the machine's CURRENT grants and version, never
-     *  persisted, so it always reflects "would a dispatch right now skip this machine", not a stale
-     *  historical fact. Independent of `lastRun`/`queued`. Either can be set from before the skip
+     *  when both hold. Computed on every read, never persisted: the grant half from the machine's
+     *  CURRENT grants, the version half from the LAST RECORDED agent version (what the last probe, ping,
+     *  preflight or update poll stored). A dispatch re-probes the agent and judges the floor on the version
+     *  that probe just reported, so after an upgrade or downgrade this field can differ from what a dispatch
+     *  right now would do until the stored version is refreshed. Independent of `lastRun`/`queued`. Either can be set from before the skip
      *  applied, and a `queued` row with a version cause can also be written WHILE the skip applies: an
      *  unreachable machine is queued before any floor is judged, since the floor is judged only on a
      *  version a probe just reported. A grant skip is judged before the unreachable branch, so it never
@@ -209,7 +216,8 @@ export interface DashLayout {
 /**
  * `GET /api/agents` (#48): one paired machine, as the console's `machines` table sees it. Never
  * carries the bearer token the console sends it (`packages/host/src/agents/store.ts`'s `list`/`get`
- * don't select it) -- the row is safe to render straight into the Agents panel.
+ * read the whole row, but `toView` is the allow-list that builds this shape and leaves the token out)
+ * -- the row is safe to render straight into the Agents panel.
  */
 export interface MachineView {
     id: string;
@@ -237,7 +245,10 @@ export interface MachineView {
  * The outcome of `HostApi.agent.call` (#50). `kind` tells a plugin which refusals are its own to
  * show verbatim (`grant`: the agent's 403 text) from ones that are the console's problem to
  * describe differently (`unknown-machine`; `refused`: not a verb the service will forward; `pin`:
- * the agent's certificate no longer matches; `network`; `http`: an unexpected status).
+ * the agent's certificate no longer matches; `network`; `http`: an unexpected status). `ok: true` means
+ * the agent answered a 2xx and its body was read (#778): a 2xx whose body could not be read (a timeout
+ * or reset mid-body, a body that is not JSON) is `ok: false` with `kind: "http"` and that 2xx `status`,
+ * since the agent may have acted on the call. A `204` is `ok: true` with `body` undefined.
  */
 export type AgentCallOutcome<T> = {
     ok: true;
@@ -246,6 +257,7 @@ export type AgentCallOutcome<T> = {
 } | {
     ok: false;
     error: {
+        /** MAY GROW: a new kind is an additive change, so keep a default branch. */
         kind: "unknown-machine" | "refused" | "grant" | "pin" | "network" | "http";
         status?: number;
         reason: string;
@@ -260,7 +272,7 @@ export type AgentCallOutcome<T> = {
  * reinstall. `unauthenticated` is `gh`-only: present and running, but `gh auth status` failed.
  * Independently defined here from the agent's own (identically-shaped) internal type -- the host
  * never depends on `@rackbops/ac-agent` at runtime, only as a devDependency for its integration
- * tests, matching `grants.ts`'s own id/capability pattern.
+ * tests, matching `grants.ts`'s own id/capability pattern. MAY GROW: keep a default branch.
  */
 export type PreflightStatus = "ok" | "missing" | "broken" | "off-path" | "unauthenticated";
 export interface PreflightRow {
@@ -279,4 +291,3 @@ export interface PreflightReport {
     searchPath: "registry" | "process";
     rows: PreflightRow[];
 }
-//# sourceMappingURL=views.d.ts.map

package/dist/views.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=views.js.map

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@rackbops/ac-plugin-contract",
-  "version": "2.0.0-alpha.58",
+  "version": "2.0.0-alpha.60",
   "private": false,
+  "license": "Apache-2.0",
   "type": "module",
   "description": "The artifact-console plugin ABI for out-of-repo plugin authors: HostApi, the acPlugin manifest contribution points, the generated manifest JSON Schema, and the @ac/host ambient browser declaration.",
   "repository": {

package/schema.json

@@ -235,6 +235,11 @@
         "danger": {
           "type": "boolean"
         },
+        "operator": {
+          "type": "boolean",
+          "const": true,
+          "description": "With the admin kill switch off (`admin_enabled = false`), the host refuses this action (`POST /api/actions/<plugin>/<id>`) with `403 admin disabled`, as it refuses the admin plugin's own surface. Mark an action or route an operator would expect the switch to shut: one that runs a job the job-run route refuses, writes to GitHub or the store on the operator's behalf, or changes the console's configuration. Additive; a host released before this field refuses a manifest that declares it (#867)."
+        },
         "fields": {
           "type": "array",
           "items": {
@@ -394,6 +399,11 @@
         "path": {
           "type": "string",
           "description": "Path under the plugin's namespace, e.g. \"/feed\"."
+        },
+        "operator": {
+          "type": "boolean",
+          "const": true,
+          "description": "With the admin kill switch off (`admin_enabled = false`), the host refuses this route for its declared method with `403 admin disabled`, as it refuses the admin plugin's own surface. Mark an action or route an operator would expect the switch to shut: one that runs a job the job-run route refuses, writes to GitHub or the store on the operator's behalf, or changes the console's configuration. Additive; a host released before this field refuses a manifest that declares it (#867)."
         }
       },
       "required": [