@kontextmind/kxm 0.7.146 → 0.7.148

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.146",
+      "version": "0.7.148",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -142,6 +142,37 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Changed
 
+- **Pull-request CI runs the unit suite on Linux Node 24, and `CI / required` is the aggregate check.**
+  Docs and plan markdown skip the code jobs. `engine.test.ts` is split by
+  test name. `permission.test.ts` and `runtime.test.ts` run one file at a
+  time, and every other unit file runs in one light lane. Pushes to `main`
+  still run `validate:pr` on Linux and Windows for Node 22.19.0 and Node 24.
+  A pull request that touches path, process, shell, spawn, package, lockfile,
+  or workflow files also runs the unit lanes on Windows. Playwright stays on
+  Obscura. See [CI and release](docs/contributing/ci-and-release.md).
+
+- **Docs match the 2026-09-27 Steel and machine-account infrastructure.**
+  Steel (`steel.kontextmind.com`, alias `steel.theneuro.me`) is reached only
+  through Caddy on `kxmd-proxy` (VM 230) and Authentik forward auth. Direct
+  LAN, tailnet, and host-forward access is blocked. Sessions return
+  `websocketUrl` `wss://steel.kontextmind.com/` (previously
+  `ws://steel-browser/`). The CDP path is `/v1/devtools` with an
+  `Authorization` header. Allowed groups are `steel-users`, `kxmd-users`,
+  `kxmd-admins`, and `kxmd-owners`. `STEEL_API_URL` defaults to
+  `https://steel.kontextmind.com`. `STEEL_API_KEY` is deprecated and is not
+  enforced by Steel or Caddy. Migrate to `STEEL_AUTH_HEADER`, then
+  `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`; those
+  override the key. The `svc-steel` credential is 1Password vault
+  `kontextmind`, item `Steel (svc-steel)`, field `basic_auth`, read with
+  `op read` and never written to disk. Steel requires `kxm` 0.7.135 or
+  newer. Playwright stays on Obscura ([ADR-0005](docs/adr/ADR-0005-obscura-default-playwright.md)).
+  The Proxmox boot order and VM names are in
+  [Deploy KXM](docs/operations/deploy.md#boot-the-kxmd-proxmox-host).
+  Machine accounts follow
+  [ADR-0006](docs/adr/ADR-0006-machine-account-names.md). The DOKS deployment
+  record is superseded by
+  [ADR-0007](docs/adr/ADR-0007-steel-caddy-authentik.md).
+
 - **Workforce ids use one convention, and old ids still resolve.**
   Role ids stay `planner`, `writer`, `reviewer-arch`, and `reviewer-cli`.
   Agent ids and agent-step ids use those same names. Route ids are
@@ -158,6 +189,7 @@ All notable user-facing changes are documented here. The project follows [Semant
   `opus` because the justfile recipe review-arch hardcoded that model while
   `reviewer-arch` listed only `fable-claude`. That recipe is gone; a request
   for `opus` fails closed.
+
 - **Dispatch reads role and model files, and agents bind a role.**
   `scripts/roster-policy.mjs` builds the developer policy from
   `.kxm/models/*.yaml` and `.kxm/roles/*.yaml` at `refs/remotes/origin/main`.
@@ -472,9 +504,10 @@ All notable user-facing changes are documented here. The project follows [Semant
   into `chromium.connectOverCDP`. Obscura stays the default and sends no Steel
   headers. `STEEL_AUTH_HEADER` overrides the value. The CDP URL omits the credential when
   those variables are set. A 302 to the identity provider fails closed and does
-  not follow the login redirect. `STEEL_API_KEY` still sends the legacy
-  `x-steel-api-key` header and `apiKey` query parameter for the temporary proxy
-  shim, and warns once. See
+  not follow the login redirect. `STEEL_API_KEY` is deprecated. Steel and
+  Caddy do not enforce it. `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then
+  `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN` override it. A client that still
+  has only the legacy key warns once and is not authenticated. See
   [Browser automation](docs/guides/browser-automation.md).
 
 ### Removed
@@ -495,6 +528,8 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **Dry-run ship status no longer rewrites `.git/index`.** `git status` refreshes the index under an optional lock. The ship-status read passes `--no-optional-locks`, so a dry run leaves the checkout untouched.
+
 - **A committed checkout counts as authored work, and a one-shot outcome must be a standalone JSON object.** The authoring witness includes `HEAD` with porcelain status and both diffs, so a write that commits its edits is `changed` and can stay `passed`. A `rev-parse` failure keeps that empty head term only when the repository has no commits; any other git failure is `unwitnessed`. A one-shot outcome is accepted when the whole reply is one JSON object, or when that object stands alone on the final line. A closing code fence around the final object is allowed. An object followed by prose, a truncated reply, and an ambiguous tail settle `failed`.
 
 - **The test suite no longer passes `--test-timeout`.** Under `node --test` that flag bounds each file, so coverage on CI timed out `test/core/engine.test.ts` at three minutes. The wall clock in `scripts/run-bounded.mjs` still bounds each script.

package/docs/README.md

@@ -76,7 +76,7 @@ KXM connects coding agents through a durable, authenticated [hub](glossary.md#hu
 | [Architecture](concepts/architecture.md) | Integrators, maintainers | The components, message and workflow lifecycles, and KXM's limits |
 | [Trust model](concepts/trust-model.md) | Operators, security reviewers | Who holds which credential, project boundaries, and what provenance proves |
 | [Data and storage](concepts/data-and-storage.md) | Operators, security reviewers | What each store holds, where it lives and how long it is kept |
-| [Architecture decision records](adr/README.md) | Maintainers | The decision records: [browser automation](adr/ADR-0002-browser-automation-steel-doks.md), [Obscura for Playwright](adr/ADR-0005-obscura-default-playwright.md), [SQLite-only store](adr/ADR-0003-sqlite-only-store.md), [edge identity](adr/ADR-0004-edge-identity-authentik.md) |
+| [Architecture decision records](adr/README.md) | Maintainers | The decision records: [browser automation](adr/ADR-0002-browser-automation-steel-doks.md), [Steel through Caddy](adr/ADR-0007-steel-caddy-authentik.md), [Obscura for Playwright](adr/ADR-0005-obscura-default-playwright.md), [machine account names](adr/ADR-0006-machine-account-names.md), [SQLite-only store](adr/ADR-0003-sqlite-only-store.md), [edge identity](adr/ADR-0004-edge-identity-authentik.md) |
 | [KXM contract package](contracts/README.md) | Maintainers, reviewers | The normative specifications for the local-first architecture, listed below |
 
 ### Contracts

package/docs/adr/ADR-0002-browser-automation-steel-doks.md

@@ -4,13 +4,13 @@ id: "ADR-0002"
 type: "adr"
 title: "Self-hosted Steel on DOKS for reusable browser automation and human takeover"
 project: "kxm"
-status: "accepted"
+status: "superseded"
 owner: "@operator"
 created: "2026-09-14"
 updated: "2026-09-27"
 authority: "decision"
 confidence: "verified"
-summary: "Adopt self-hosted Steel on DigitalOcean Kubernetes (DOKS) with agent-browser and Playwright as KXM's primary browser automation infrastructure."
+summary: "The 2026-09-14 choice of self-hosted Steel. The DOKS deployment in this record was superseded on 2026-09-27 by ADR-0007. Obscura is the Playwright default (ADR-0005)."
 tags: ["architecture", "decision", "browser", "steel", "doks", "playwright"]
 related: ["docs/guides/browser-automation.md", "docs/guides/agent-skills.md", "docs/adr/ADR-0005-obscura-default-playwright.md"]
 details:
@@ -20,11 +20,15 @@ details:
     - "Provide dual exploratory (agent-browser) and regression (Playwright) interfaces"
     - "Enforce strict credential isolation via pass-cli"
   supersedes: null
-  superseded_by: null
+  superseded_by: "ADR-0007"
 ---
 
 # ADR-0002: Self-hosted Steel on DOKS for reusable browser automation
 
+## Status
+
+Superseded on 2026-09-27 by [ADR-0007](ADR-0007-steel-caddy-authentik.md) for where Steel runs and how clients authenticate. [ADR-0005](ADR-0005-obscura-default-playwright.md) keeps Obscura as the Playwright default. The sections below are the 2026-09-14 decision. They are not the current deployment. Steel and Caddy do not enforce `STEEL_API_KEY`.
+
 ## Context and problem statement
 
 AI coding agents and orchestration workflows in KXM require browser interaction for UI exploration, DOM mapping, bug reproduction, and end-to-end regression testing. Existing approaches suffered from three core issues:
@@ -100,8 +104,7 @@ AI coding agents and orchestration workflows in KXM require browser interaction
 
 - **Verification**: Health endpoint `$STEEL_API_URL/v1/health` verified with HTTP 200 and Let's Encrypt TLS.
 - **Integration Test**: `test/core/browser.test.ts` validates session lifecycle, CDP endpoint formatting, takeover transitions, and secret redaction.
-- **Security Check**: `pass-cli` verified as the authoritative store for Steel credentials in the operators' password manager.
-- **Edge auth (2026-09-27)**: `steel.kontextmind.com` and `steel.theneuro.me`, including the CDP WebSocket, are behind Authentik forward auth. Steel does not check `STEEL_API_KEY`. Clients send `Authorization: Basic`. Unauthenticated requests are redirected to `id.kxmd.dev`. The legacy `x-steel-api-key` header and `apiKey` query parameter remain a temporary proxy shim.
+- **Security Check**: `pass-cli` was the credential store named in this 2026-09-14 decision. Current clients read the `svc-steel` credential with `op read`, as [ADR-0007](ADR-0007-steel-caddy-authentik.md) records.
 
 ## Related
 

package/docs/adr/ADR-0005-obscura-default-playwright.md

@@ -12,7 +12,7 @@ authority: "decision"
 confidence: "verified"
 summary: "Playwright testing and verification connect to pinned Obscura v0.2.3 over CDP. Steel stays the browser for human takeover, MFA, and the live session viewer."
 tags: ["architecture", "decision", "browser", "obscura", "playwright", "cdp"]
-related: ["docs/adr/ADR-0002-browser-automation-steel-doks.md", "docs/guides/browser-automation.md", "docs/kb/how-to-connect-playwright-to-obscura.md"]
+related: ["docs/adr/ADR-0002-browser-automation-steel-doks.md", "docs/adr/ADR-0007-steel-caddy-authentik.md", "docs/guides/browser-automation.md", "docs/kb/how-to-connect-playwright-to-obscura.md"]
 details:
   decision_drivers:
     - "Playwright tests must run without a Steel cluster or a Playwright-managed browser download"
@@ -26,7 +26,7 @@ details:
 
 ## Status
 
-Accepted on 2026-09-27. This record does not supersede [ADR-0002](ADR-0002-browser-automation-steel-doks.md). Steel remains the browser for human takeover, MFA, and the live session viewer.
+Accepted on 2026-09-27. This record does not supersede [ADR-0002](ADR-0002-browser-automation-steel-doks.md). [ADR-0007](ADR-0007-steel-caddy-authentik.md) is the current Steel deployment. Steel remains the browser for remote and hosted sessions, human takeover, MFA, and the live session viewer.
 
 ## Context
 
@@ -79,7 +79,8 @@ Obscura v0.2.3 is a headless Chromium build that speaks the Chrome DevTools Prot
 
 ## Related
 
-- [ADR-0002: Self-hosted Steel on DOKS](ADR-0002-browser-automation-steel-doks.md)
+- [ADR-0002: Self-hosted Steel on DOKS (superseded deployment)](ADR-0002-browser-automation-steel-doks.md)
+- [ADR-0007: Steel through Caddy and Authentik](ADR-0007-steel-caddy-authentik.md)
 - [Browser automation](../guides/browser-automation.md)
 - [How do I connect Playwright to Obscura?](../kb/how-to-connect-playwright-to-obscura.md)
 - [Environment variables and limits](../reference/configuration.md#browser-automation)

package/docs/adr/ADR-0006-machine-account-names.md

@@ -0,0 +1,90 @@
+---
+schema: "kxm.doc.v1"
+id: "ADR-0006"
+type: "adr"
+title: "Machine account names"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-27"
+updated: "2026-09-27"
+authority: "decision"
+confidence: "verified"
+summary: "New machine accounts use svc-<system>-<purpose>, or svc-<tenant>-<system>-<purpose> when they belong to one tenant. Test accounts add a test- prefix and stay out of production groups."
+tags: ["architecture", "decision", "authentik", "accounts"]
+related: ["docs/adr/ADR-0004-edge-identity-authentik.md", "docs/operations/deploy.md", "docs/contributing/operating-rules.md"]
+details:
+  decision_drivers:
+    - "One readable pattern for platform and tenant machine accounts"
+    - "Test and witness accounts must be unable to enter production groups"
+    - "Existing names stay until an approved inventory authorizes a rename"
+  supersedes: null
+  superseded_by: null
+---
+
+# ADR-0006: Machine account names
+
+## Status
+
+Accepted on 2026-09-27.
+
+## Context
+
+Authentik machine accounts were created with local names such as `kxm-agent`, `kxm-witness-*`, `witness9`, `kxmdproof`, `kxm-provisioner`, and `agent-ilo-asus`. Those names do not say whether the account is platform-wide, tenant-scoped, or a test identity. Renaming them without an inventory would drop grants that still point at the old name.
+
+## Decision drivers
+
+1. A reader can tell the scope of an account from its name.
+2. Test, witness, and proof accounts must not sit in production groups.
+3. Authentik's own accounts keep the names Authentik assigns.
+4. A rename of an account that already exists waits for an approved inventory.
+
+## Considered options
+
+1. **`svc-` names, with a `test-` prefix for non-production accounts.**
+2. **Keep creating ad hoc names.**
+3. **Put every machine account under Authentik's `ak-*` prefix.**
+
+### Option 1: `svc-` names (chosen)
+
+- Good, because platform and tenant scope are visible in the name.
+- Good, because a `test-` prefix can be excluded from production groups.
+- Bad, because accounts that already exist keep their old names until an inventory is approved.
+
+### Option 2: ad hoc names (rejected)
+
+- Good, because nothing already issued has to change.
+- Bad, because the next account repeats the same ambiguity.
+
+### Option 3: `ak-*` for every machine account (rejected)
+
+- Good, because one prefix would match Authentik-managed users.
+- Bad, because `ak-*` is Authentik's own namespace for outposts and internal users.
+
+## Decision
+
+Create machine accounts with these shapes. `<tenant>` is the tenant slug.
+
+| Scope | Name |
+|---|---|
+| Platform-wide | `svc-<system>-<purpose>` |
+| Tenant-scoped | `svc-<tenant>-<system>-<purpose>` |
+| Test, witness, or proof | The same shapes with a `test-` prefix |
+
+A `test-` account is never a member of a production group.
+
+Authentik-managed accounts are exempt. That includes outposts and any account whose name starts with `ak-`.
+
+The `svc-steel` credential that reaches the Steel server is the account operators use today. This record does not rename it. Names already recorded in plans and handoffs, including `kxm-agent`, `kxm-witness-*`, `witness9`, `kxmdproof`, `kxm-provisioner`, and `agent-ilo-asus`, stay as written until an approved inventory lists each rename. Do not invent a replacement for a specific account.
+
+## Consequences
+
+- New accounts follow the table above.
+- This repository does not assign new names to the recorded accounts.
+- Group names such as `kxmd-owners` are groups, not machine accounts, and this record does not rename them.
+
+## Related
+
+- [Edge identity](ADR-0004-edge-identity-authentik.md)
+- [Deploy KXM](../operations/deploy.md#name-machine-accounts)
+- [Operating rules](../contributing/operating-rules.md)

package/docs/adr/ADR-0007-steel-caddy-authentik.md

@@ -0,0 +1,97 @@
+---
+schema: "kxm.doc.v1"
+id: "ADR-0007"
+type: "adr"
+title: "Steel is reached only through Caddy and Authentik"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-27"
+updated: "2026-09-27"
+authority: "decision"
+confidence: "verified"
+summary: "The Steel server steel.kontextmind.com is an LXC behind Caddy and Authentik forward auth. Clients use the svc-steel credential. STEEL_API_KEY is not enforced. Playwright stays on Obscura."
+tags: ["architecture", "decision", "browser", "steel", "authentik"]
+related: ["docs/adr/ADR-0002-browser-automation-steel-doks.md", "docs/adr/ADR-0005-obscura-default-playwright.md", "docs/guides/browser-automation.md", "docs/adr/ADR-0006-machine-account-names.md"]
+details:
+  decision_drivers:
+    - "Steel must not be reachable on the LAN, the tailnet, or a host forward"
+    - "Authentik groups are the access list"
+    - "Credentials stay in 1Password and are read into the process only"
+  supersedes: "ADR-0002"
+  superseded_by: null
+---
+
+# ADR-0007: Steel is reached only through Caddy and Authentik
+
+## Status
+
+Accepted on 2026-09-27. This record supersedes the DigitalOcean Kubernetes deployment in [ADR-0002](ADR-0002-browser-automation-steel-doks.md). [ADR-0005](ADR-0005-obscura-default-playwright.md) still makes Obscura the Playwright default. Steel remains the browser for remote and hosted sessions, human takeover, MFA, and the live session viewer.
+
+## Context
+
+Steel now runs as LXC 240 on the Proxmox host, at startup order 40. Its public name is `steel.kontextmind.com`. `steel.theneuro.me` is an alias of that same server. Caddy on VM 230 (`kxmd-proxy`) is the only listener, and it forwards authentication to Authentik. Direct LAN, tailnet, and host-forward access is blocked.
+
+Sessions return `websocketUrl` `wss://steel.kontextmind.com/`. The previous value was `ws://steel-browser/`. Clients connect Chrome DevTools Protocol at `/v1/devtools` and send `Authorization` on the handshake. The URL does not carry a credential.
+
+Steel and Caddy do not enforce `STEEL_API_KEY`. Clients authenticate as the Authentik user `svc-steel`.
+
+## Decision drivers
+
+1. The browser host is not a second network entrance beside the proxy.
+2. Membership in a known Authentik group is the allow list.
+3. The credential is read at runtime and is not written to disk.
+4. Playwright tests keep the Obscura default from ADR-0005.
+
+## Considered options
+
+1. **Caddy plus Authentik forward auth, with direct paths blocked.**
+2. **Keep the DOKS ingress and a Steel API key.**
+3. **Publish the LXC on the tailnet or a host forward.**
+
+### Option 1: Caddy and Authentik only (chosen)
+
+- Good, because one proxy terminates TLS and applies the group check.
+- Good, because a client that still sends `STEEL_API_KEY` does not get a session.
+- Bad, because clients older than `kxm` 0.7.135 still expect `ws://steel-browser/`.
+
+### Option 2: DOKS and `STEEL_API_KEY` (rejected)
+
+- Good, because existing scripts that sent `x-steel-api-key` would keep working.
+- Bad, because that cluster is no longer where Steel runs, and neither Steel nor Caddy checks the key.
+
+### Option 3: tailnet or host-forward access (rejected)
+
+- Good, because an operator on the tailnet could open the API without the proxy.
+- Bad, because it bypasses Authentik and the group check.
+
+## Decision
+
+Reach Steel only at `https://steel.kontextmind.com` (alias `steel.theneuro.me`) through Caddy and Authentik forward auth. `STEEL_API_URL` defaults to `https://steel.kontextmind.com`.
+
+Authenticate with the `svc-steel` credential. Precedence is `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` together with `STEEL_AUTH_TOKEN`. Those variables override `STEEL_API_KEY`. `STEEL_API_KEY` is deprecated: Steel and Caddy do not enforce it, and a value in the URL is not accepted. Migrate by setting one of the three Authentik variables and dropping the key from the environment.
+
+Read the credential from 1Password at runtime. The vault is `kontextmind`, the item is `Steel (svc-steel)`, and the field is `basic_auth`. Use `op read`. Do not write the value to disk.
+
+```bash
+export STEEL_AUTH_BASIC="$(op read 'op://kontextmind/Steel (svc-steel)/basic_auth')"
+```
+
+The CDP path is `/v1/devtools` with an `Authorization` header.
+
+These Authentik groups may use the server: `steel-users`, `kxmd-users`, `kxmd-admins`, and `kxmd-owners`.
+
+`kxm` 0.7.135 or newer is required. Playwright testing stays on Obscura unless `KXM_BROWSER=steel`.
+
+## Consequences
+
+- A connection to the LXC by LAN address, tailnet address, or host forward fails.
+- A client that only sets `STEEL_API_KEY` is not authenticated.
+- The `svc-steel` name is the live account. [ADR-0006](ADR-0006-machine-account-names.md) does not rename it ahead of an approved inventory.
+
+## Related
+
+- [ADR-0002](ADR-0002-browser-automation-steel-doks.md)
+- [ADR-0005](ADR-0005-obscura-default-playwright.md)
+- [Browser automation](../guides/browser-automation.md)
+- [Deploy KXM](../operations/deploy.md#boot-the-kxmd-proxmox-host)

package/docs/adr/README.md

@@ -7,10 +7,12 @@ An architecture decision record (ADR) captures one significant decision about KX
 | ADR | Decision | Status | Date |
 |---|---|---|---|
 | [ADR-001](../contracts/architecture.md) | Local Runtime, project authority, and aggregate hub | Accepted target | — |
-| [ADR-0002](ADR-0002-browser-automation-steel-doks.md) | Self-hosted Steel for reusable browser automation and human takeover | Accepted | 2026-09-14 |
+| [ADR-0002](ADR-0002-browser-automation-steel-doks.md) | Self-hosted Steel on DOKS (deployment superseded) | Superseded by ADR-0007 | 2026-09-14 |
 | [ADR-0003](ADR-0003-sqlite-only-store.md) | SQLite as the only store | Accepted | 2026-09-17 |
 | [ADR-0004](ADR-0004-edge-identity-authentik.md) | Edge identity with Authentik; the hub owns no browser identity | Accepted | 2026-09-20 |
 | [ADR-0005](ADR-0005-obscura-default-playwright.md) | Obscura is the default browser for Playwright; Steel stays for takeover | Accepted | 2026-09-27 |
+| [ADR-0006](ADR-0006-machine-account-names.md) | Machine account names (`svc-` shapes, `test-` prefix, Authentik exemptions) | Accepted | 2026-09-27 |
+| [ADR-0007](ADR-0007-steel-caddy-authentik.md) | Steel is reached only through Caddy and Authentik | Accepted | 2026-09-27 |
 
 ADR-001 is the original decision record for the local Runtime. It lives with the contracts in [`docs/contracts/architecture.md`](../contracts/architecture.md) because it is the root of those contracts, and it keeps its original three-digit number. Records in this directory continue the sequence from 0002. There is no ADR-0001.
 

package/docs/contributing/ci-and-release.md

@@ -1,11 +1,12 @@
 # CI and release
 
-Every pull request and every push to `main` that changes code runs a
-three-minute merge-safety gate, the complete suite with coverage floors runs
-nightly, every merge to `main` cuts a patch release, and every release is
-verified before it reaches npm. This
-page explains which checks run where, how a merge becomes a published version,
-and which smoke tests stay manual. It is for contributors and maintainers.
+Pull requests run lint, typecheck, and the unit suite on Linux Node 24.
+Pushes to `main` also run that suite and the full OS × Node matrix.
+The complete suite with coverage floors runs nightly, every merge to `main`
+cuts a patch release, and every release is verified before it reaches npm.
+This page explains which checks run where, how a merge becomes a published
+version, and which smoke tests stay manual. It is for contributors and
+maintainers.
 
 ## The pipeline at a glance
 
@@ -14,9 +15,10 @@ release and an npm publish; the nightly job adds the slower suites.
 
 ```mermaid
 flowchart LR
-  PR[Pull request] -->|"validate:pr, docs lint, plugin validation"| MERGE{Merged?}
+  PR[Pull request] -->|"unit shards, docs lint, plugin validation"| REQ["CI / required"]
+  REQ --> MERGE{Merged?}
   MERGE -->|yes| MAIN[main]
-  MAIN -->|"same three-minute validate:pr"| PUSH[Push CI]
+  MAIN -->|"unit shards plus validate:pr matrix"| PUSH[Push CI]
   MAIN -->|"Auto-Release: next patch tag"| TAG[Tag vX.Y.Z]
   TAG -->|dispatch| REL[Release workflow]
   REL -->|"verify, stamp version, pack"| GH[GitHub release<br/>kxm-X.Y.Z.tgz]
@@ -35,46 +37,75 @@ together.
 | Trigger | Workflow (job) | What it runs |
 |---|---|---|
 | Before you push | Local | `npm run verify` |
-| Pull request and push to `main` | `ci.yml` (Validate, two Node legs) | `validate:pr`, the three-minute gate; skipped for documentation-only changes |
+| Pull request, push to `main`, or manual | `ci.yml` (`required`) | Aggregates the lanes below into one pass/fail check named `CI / required` |
 | Pull request and push | `ci.yml` (Docs lint) | `lint:docs` and `check:versions`, always |
-| Pull request and push | `ci.yml` (Plugin validation) | `claude plugin validate --strict` on the marketplace and the plugin; skipped for documentation-only changes |
+| Code pull request and code push | `ci.yml` (Unit engine and Unit, Linux Node 24) | `engine.test.ts` split by test name; `permission.test.ts` and `runtime.test.ts` one file at a time; every other unit file together. Typecheck and `check-generated` run on the light lane |
+| Platform-sensitive pull request | `ci.yml` (Unit, Windows Node 24) | The same four unit lanes on `windows-latest` |
+| Push to `main`, or manual | `ci.yml` (Validate matrix) | `validate:pr` on Linux and Windows for Node 22.19.0 and Node 24; not on a pull request |
+| Code pull request and code push | `ci.yml` (Plugin validation) | `claude plugin validate --strict` on the marketplace and the plugin |
 | Daily at 04:00 UTC, or manual | `nightly.yml` | `test:coverage:complete`, `check`, `check:generated`, `npm pack --dry-run` |
 | Merged pull request | `auto-release.yml` | Tags the merge commit and dispatches `release.yml` |
 | Tag push or dispatch | `release.yml` | Verifies, packs and publishes (see [Release flow](#release-flow)) |
 | Manual only | `smoke.yml` | Real Pi smoke, currently disabled (see [Smoke tests](#smoke-tests)) |
-| Pull request, or manual | `e2e.yml` | `npm run e2e` on `ubuntu-latest`: Obscura v0.2.3 plus the Playwright smoke test. This workflow does not enable CI, Nightly, or Real Pi smoke |
+| Pull request, or manual | `e2e.yml` | `npm run e2e` on `ubuntu-latest`: Obscura v0.2.3 plus the Playwright smoke test. Separate from `ci.yml` |
 
 The npm scripts behind those rows:
 
 | Script | Composition |
 |---|---|
 | `verify` | `npm test` (core and package unit tests), `check`, `check:generated` |
+| `test:ci-shard` | One unit lane: build, then `engine <index> <total>`, `serial`, or `light` over `test/core/*.test.ts` and `packages/core/*/tests/unit/*.test.ts` |
 | `validate:pr` | `build`, `typecheck`, a compact contract and smoke set of nine `test/core` files, `check:versions`, and the generated-`dist` check |
-| `validate:ci` | `test:coverage` (core and package tests, 91/80/92 floors), `check`, `npm pack --dry-run`; not run by CI today, available locally |
+| `validate:ci` | `test:coverage` (core and package tests, 91/80/92 floors), `check`, `npm pack --dry-run`; the Release workflow runs it, and it stays available locally |
 | `test:coverage:complete` | Core, simulation and package tests with 93/80/93 floors |
 | `check` | `typecheck`, `lint:docs`, `check:versions` |
 
-Three differences matter when a check fails on one side only:
-
-- CI runs a compact contract and smoke set, not the core suite. The full core
-  suite and the package unit tests under `packages/core/*/tests` run in your
-  local `npm run verify`; run it before every push.
-- Coverage and `test/simulations` run only in the nightly complete suite, never
-  on a pull request or a push to `main`.
-- A regression the compact set misses can reach `main` and show up in the
-  nightly run, so treat a nightly failure as a release blocker.
-
-### Validate matrix and required checks
-
-The Validate job runs on Node 22.19.0 and Node 24, on Linux and Windows. Linux
-uses the ARC scale set `kontextmind-doks` with a three-minute job timeout.
-Windows uses GitHub-hosted `windows-latest` with a fifteen-minute timeout so
-`npm ci` can finish. The branch ruleset requires the job names
-`Validate (linux, Node 22.19.0)` and `Validate (linux, Node 24)` only; the
-Windows names are reported but not required, so a Windows-only failure does not
-block merge. Renaming a required Linux job or the matrix means updating the
-ruleset in the same change. A newer push cancels an older pull request run;
-runs on `main` are never cancelled.
+What moved off the pull-request lane, and what did not:
+
+- The four `validate:pr` cells — Linux and Windows, Node 22.19.0 and Node 24 —
+  run on a push to `main` and on `workflow_dispatch`. They do not run on a
+  pull request. The nine files inside `validate:pr` still run on a code pull
+  request, because they are part of the Linux Node 24 unit suite.
+- Node 22.19.0 does not run the unit suite on a pull request. It runs
+  `validate:pr` on `main`.
+- Windows runs the unit suite on a pull request only when the classifier marks
+  the change platform-sensitive. Every push to `main` that changes code still
+  runs `validate:pr` on Windows.
+- Coverage, `test/simulations`, and `npm pack --dry-run` stay in the nightly
+  complete suite. They were not part of pull-request CI before this split.
+- Plugin validation still runs on code pull requests and code pushes.
+
+Run `npm run verify` locally before every push. A nightly failure is a release
+blocker: it is the only place the simulation suite and coverage floors run.
+
+### Lanes and the required check
+
+Code pull requests run Docs lint, two Linux Node 24 engine shards, a serial
+lane (`permission.test.ts` then `runtime.test.ts`), a light lane for every
+other unit file, and Plugin validation. The light lane typechecks and checks
+generated bundles. `engine.test.ts` is split by test name because that file
+alone was 174 seconds; the serial lane keeps the next two longest files off
+the light pool, which was 268 seconds when every non-engine file shared one
+job. Linux jobs use the npm cache from
+`actions/setup-node`. Restoring a `node_modules` tarball was slower than
+`npm ci` on the Linux runners (about 24s versus 17s on 2026-09-24), so that
+cache stays on the Windows jobs, where `npm ci` is the slow step.
+
+The job `required` always runs. Its check name is `CI / required`. It fails
+when a lane fails or is cancelled, and it passes when a lane was skipped
+because the change did not need it. Add `CI / required` as a required status
+check in the `protect-main` ruleset. Skipped matrix legs are not required
+names, so they do not block auto-merge. This repository change does not edit
+that ruleset.
+
+A newer push cancels an older pull request run. Runs on `main` are never
+cancelled. Unit and Validate matrices use `fail-fast`.
+
+The Validate matrix still runs on Node 22.19.0 and Node 24, on Linux and
+Windows, for pushes to `main` and for `workflow_dispatch`. Linux uses the ARC
+scale set `kontextmind-doks` with a three-minute job timeout. Windows uses
+GitHub-hosted `windows-latest` with a fifteen-minute timeout so `npm ci` can
+finish. Those four job names are not the required check anymore.
 
 ### CI jobs stay queued while a runner is online
 
@@ -111,20 +142,26 @@ autoscaler. Do not relabel `km-gh-rn01` or push an empty commit as a routing
 workaround.
 
 > [!NOTE]
-> Windows Validate uses GitHub-hosted `windows-latest`, not a self-hosted
-> homelab runner and not the ARC scale set. Do not add a `kontextmind-doks`
-> label to a Windows runner. Nightly complete coverage and release stay on
-> Linux. Windows-specific fixtures (for example the `pi.cmd` worker launch in
-> `test/core/worker.test.ts`) also run in the hosted Windows Validate legs.
+> Windows jobs use GitHub-hosted `windows-latest`, not a self-hosted homelab
+> runner and not the ARC scale set. Do not add a `kontextmind-doks` label to a
+> Windows runner. Nightly complete coverage and release stay on Linux.
+> Platform-sensitive pull requests run the unit suite on Windows, which
+> includes `test/core/worker.test.ts`. The main Validate legs run the compact
+> `validate:pr` gate.
 
 ### The docs-only classifier
 
 The first job, Classify changes, lists the changed paths and sets `code=false`
-when every path matches `*.md`, `docs/*`, `.kxm/assets/*`, `LICENSE`, the issue
-and PR templates, or `dependabot.yml`. Validate and Plugin validation read it:
-for a documentation-only change they report success without checking out the
-code, so the required job names still pass. Docs lint always runs.
-`ci-contract.test.ts` pins this behavior.
+when every path matches `*.md` (including `plans/**/*.md`), `docs/**`,
+`.kxm/assets/**`, `LICENSE`, the issue and PR templates, or `dependabot.yml`.
+A non-markdown file under `plans/` is code. Unit lanes, Plugin validation,
+and the Validate matrix are skipped. Docs lint runs, and `CI / required`
+passes. `scripts/ci-classify.mjs` and `ci-contract.test.ts` pin this behavior.
+
+`platform=true` when a path is a package manifest, the lockfile, a file under
+`scripts/` or `.github/workflows/`, or a filename that names path, process,
+shell, spawn, worker, supervisor, repo-root, or ssh-remote behavior. A
+platform-sensitive pull request also runs the Windows Node 24 unit lanes.
 
 > [!WARNING]
 > Several tests and code paths read documentation files by path. A pull request

package/docs/contributing/operating-rules.md

@@ -2,7 +2,7 @@
 title: "Operating rules"
 description: "Standing instructions from the operator that every agent session on this repository follows, with the date each was given. Read before planning, dispatching, landing, or editing the roadmap."
 audience: "agents and maintainers"
-updated: "2026-09-26"
+updated: "2026-09-27"
 ---
 
 # Operating rules
@@ -58,6 +58,18 @@ replacement.
   `impl-bg`) retire last, after one real unit has run through the one-step
   workflows. (2026-09-26.)
 
+## Accounts
+
+- **Machine account names follow [ADR-0006](../adr/ADR-0006-machine-account-names.md).**
+  Platform-wide accounts are `svc-<system>-<purpose>`. Tenant-scoped accounts
+  are `svc-<tenant>-<system>-<purpose>`, where `<tenant>` is the tenant slug.
+  Test, witness, and proof accounts use those shapes with a `test-` prefix
+  and are never members of production groups. Authentik-managed accounts
+  (outposts and `ak-*`) are exempt. Recorded names such as `kxm-agent`,
+  `kxm-witness-*`, `witness9`, and `kxmdproof` stay until an approved
+  inventory. Do not invent a replacement for a specific account.
+  (2026-09-27.)
+
 ## Decisions and debt
 
 - **Every option comes with pros and cons and two recommendations**, the

package/docs/guides/agent-skills.md

@@ -68,7 +68,7 @@ Tools map the same way: peer tools to `kxm-peer`, workflow tools to `kxm-workflo
 
 ## Browser automation skills
 
-Playwright testing and verification use Obscura ([ADR-0005](../adr/ADR-0005-obscura-default-playwright.md)). The Steel skills cover human takeover, MFA, and the live session viewer. Those hosts sit behind Authentik forward auth: send `Authorization: Basic` (`STEEL_AUTH_BASIC`, or `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`) and keep the credential out of URLs. `kxm-browser-verify` owns `vision`. The other browser skills own no `kxm` command. See [Browser automation](browser-automation.md) and [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md).
+Playwright testing and verification use Obscura ([ADR-0005](../adr/ADR-0005-obscura-default-playwright.md)). The Steel skills cover remote and hosted browsing, human takeover, MFA, and the live session viewer. Steel is `https://steel.kontextmind.com`, reached only through Caddy and Authentik ([ADR-0007](../adr/ADR-0007-steel-caddy-authentik.md)). Send `Authorization: Basic` (`STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`) and keep the credential out of URLs. `STEEL_API_KEY` is deprecated and is not enforced. `kxm` 0.7.135 or newer is required for Steel. `kxm-browser-verify` owns `vision`. The other browser skills own no `kxm` command. See [Browser automation](browser-automation.md).
 
 | Skill | Use it to |
 |---|---|