@rackbops/ac-plugin-contract 2.0.0-alpha.57 → 2.0.0-alpha.59

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.
@@ -254,6 +272,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 +300,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 +655,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 +744,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 +959,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 +1046,12 @@ 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.
 
 ```ts
 const { jobId } = await execResult // however the plugin's own verb call started the job
@@ -987,7 +1083,7 @@ 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

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;
@@ -53,4 +53,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
@@ -158,9 +162,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;
@@ -326,7 +332,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 +460,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

@@ -253,4 +253,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

@@ -142,7 +142,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 +181,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 +212,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 +241,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 +253,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 +268,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 +287,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.57",
+  "version": "2.0.0-alpha.59",
   "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": {