@kontextmind/kxm 0.7.181 → 0.7.183

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.181",
+      "version": "0.7.183",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -6,6 +6,20 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Added
 
+- **The witnessed MG1 Python control-plane foundation is now reproducible from this repository.**
+  `python/kxm-control` provides the pinned Python 3.13 uv workspace, fixed
+  `kxmd` Postgres/Temporal caller, Authentik user and runner verification
+  that requires token expiry, tenant/project/repository registration,
+  owner/admin tenant rename, revision and artifact APIs, and a probe entry
+  point. OpenAPI and the Studio path inventory are derived from the FastAPI
+  app. The checked generator emits the revision helper. Studio exposes the
+  bounded `/api/control/account` relay with a three-second bound and explicit
+  failure states. Removing registration leaves source state untouched and
+  later registry calls return `registration_unavailable` until the schema is
+  installed again. The package does not change host or guest installs. The
+  required CI aggregate runs the Python contracts against PostgreSQL 17. This
+  does not move the hub or Runtime from their existing Node and SQLite owners.
+
 - **KXM configuration now has one owner-validated terminal editor.**
   `kxm config edit --scope project|user` and OMP/Pi `/kxm config` publish the
   same `kxm.config.v1` surface. Accepted writes are saved and re-read; rejected

package/docs/architecture/authentication.md

@@ -1,7 +1,7 @@
 # Authentication
 
-Read from `plugins/kxm/src/harness.ts` and `plugins/kxm/src/cli.ts`.
-
+Read from `plugins/kxm/src/harness.ts`, `plugins/kxm/src/cli.ts`, and
+`python/kxm-control/src/kxm_control/auth.py`.
 `kxm harness list` runs `probeHarnesses` (`cmdHarnessList` in
 `plugins/kxm/src/cli/project.ts`). For each detected harness that has
 `authArgs`, `probeEntry` runs that command and `interpretAuth` reads the
@@ -23,6 +23,15 @@ the harness command's own stdout.
 issues, or clears the local session token file. That token is a KXM session
 token, not a provider key. Provider logins stay in each harness.
 
+The MG1 Python control API uses a separate Authentik boundary. It accepts only
+RS256 tokens whose issuer and audience match its configured values, whose
+`exp` is present and unexpired, and whose `kxm_actor` is `user` or `runner`.
+A token without `exp` is rejected.
+The signed subject and actor kind must match
+an explicit tenant membership; a user membership never authorizes a runner
+token with the same subject. Only a user can create a tenant. The API does not
+store the bearer token.
+
 ## Related
 
 - [Access](access.md)

package/docs/architecture/hosted-direction.md

@@ -52,11 +52,13 @@ roadmap question. The tracker wins.
 proposal is not in this repository. Its delivery position is unchanged:
 none of the delivery is scheduled there.
 
-The tracker names that file. The sentences that can be repeated without a
-hostname, an account name, or a secret are: a first move is recorded as
-installed, Postgres and Temporal are described as loopback only, KXM does not
-write those stores, Redis Streams, NATS, raw WebSockets, and the A2A Python
-SDK stay backlog, there is no S3, and the SQLite write path is unchanged.
+Today the Node hub and Runtime still write local SQLite and local files. The
+checked-in MG1 Python control API is the narrow exception: it owns only central
+registration and bounded tenant artifacts in the fixed `kxmd` PostgreSQL
+account. Temporal is provisioned for `kxmd`, but no production workflow cutover
+is selected. Redis Streams, NATS, raw WebSockets, the A2A Python SDK, and S3
+remain backlog. The rest of this page remains a target, not a live deployment
+description.
 
 ## Related
 

package/docs/architecture/inventory.md

@@ -6,7 +6,8 @@ Read from `plugins/kxm/src/cli.ts`, `plugins/kxm/src/config-editor.ts`,
 `plugins/kxm/src/runtime-paths.ts`, `plugins/kxm/src/mcp-server.ts`,
 `plugins/kxm/src/oneshot-producer.ts`, `plugins/kxm/src/studio-layout.ts`,
 `plugins/kxm/src/cli/types.ts` (`workspaceDirs`),
-`plugins/kxm/src/local-snapshot.ts`, and `scripts/kxm-worker.mjs`.
+`plugins/kxm/src/local-snapshot.ts`, `scripts/kxm-worker.mjs`, and
+`python/kxm-control/src/kxm_control/{api,registry}.py`.
 
 | Surface | Started by | Listener or path | Store it owns | Defining file |
 | --- | --- | --- | --- | --- |
@@ -21,7 +22,8 @@ Read from `plugins/kxm/src/cli.ts`, `plugins/kxm/src/config-editor.ts`,
 | MCP server | Claude plugin or stdio launch | stdio | none | `plugins/kxm/src/mcp-server.ts` |
 | One-shot harness | supervisor producer | child process, no listener | none | `plugins/kxm/src/oneshot-producer.ts` |
 | Pi worker | `kxm agent worker` | no HTTP listener in `scripts/kxm-worker.mjs` | none of its own | `scripts/kxm-worker.mjs` |
-| Studio | `kxm studio serve` | `127.0.0.1:4242` | none | `plugins/kxm/src/studio-layout.ts` |
+| Studio | `kxm studio serve` | `127.0.0.1:4242` | none; `/api/control/account` is a bounded relay to the configured control API | `plugins/kxm/src/studio-layout.ts` |
+| Python control API | ASGI server loading `kxm_control.api:app` | deployment-selected; the package declares no network default | `kxm_registry` in the fixed `kxmd` PostgreSQL database and the configured tenant artifact root | `python/kxm-control/src/kxm_control/api.py` |
 | Workspace config | `workspaceDirs` | `.kxm/config`, or `KXM_CONFIG_DIR` | files in that directory | `plugins/kxm/src/cli/types.ts` |
 | Workspace logs | `workspaceDirs` | `.kxm/logs`, or `KXM_LOGS_DIR` | log files | `plugins/kxm/src/cli/types.ts` |
 | Workspace assets | `workspaceDirs` | `.kxm/assets`, or `KXM_ASSETS_DIR` | asset files | `plugins/kxm/src/cli/types.ts` |

package/docs/architecture/platform.md

@@ -2,7 +2,8 @@
 
 Read from `plugins/kxm/src/cli.ts`, `plugins/kxm/src/runtime-supervisor.ts`,
 `scripts/kxm-hub.mjs`, `plugins/kxm/src/hub.ts`, `plugins/kxm/src/mcp-server.ts`,
-and `plugins/kxm/src/oneshot-producer.ts`.
+`plugins/kxm/src/oneshot-producer.ts`, and
+`python/kxm-control/src/kxm_control/api.py`.
 
 KXM on this checkout is local-first. The `kxm` CLI is the operator entry
 (`plugins/kxm/src/cli.ts`, launched through `scripts/kxm.mjs`). The hub is an
@@ -18,17 +19,29 @@ requested. The MCP server (`plugins/kxm/src/mcp-server.ts`) uses
 spawned by the producer registered in `plugins/kxm/src/oneshot-producer.ts`.
 That child process is not a listener.
 
+The checked-in MG1 Python control API is additive. It owns central registration
+and bounded tenant artifacts through the fixed `kxmd` account. Only an owner
+or admin membership can rename a tenant. Removing the registration schema
+leaves source state in place, and later registry routes return
+`registration_unavailable` until the schema is installed again. The API does
+not install or change host or guest software. It does not replace the Node
+hub, Runtime, CLI, or their SQLite stores. Studio can relay
+`GET /api/control/account` to this service when `KXM_CONTROL_URL` is configured.
+
 ```mermaid
 flowchart LR
   cli["kxm CLI"]
-  hub["hub"]
-  sup["Runtime supervisor"]
+  hub["Node hub"]
+  sup["Node Runtime supervisor"]
   mcp["MCP server"]
   shot["one-shot harness"]
+  studio["Studio"]
+  control["MG1 Python control API"]
   cli -->|"kxm hub start"| hub
   mcp -->|"HTTP to hub"| hub
   cli -->|"kxm run"| sup
   sup -->|"spawn producer"| shot
+  studio -->|"bounded account read"| control
 ```
 
 ## Listeners
@@ -39,7 +52,8 @@ flowchart LR
 | Supervisor HTTP | `127.0.0.1` and an ephemeral port when the requested port is `0` |
 | MCP | stdio, no TCP port |
 | CLI and one-shot harness | no listener |
-| Studio, when served | `127.0.0.1:4242` from `createStudioServer` in `plugins/kxm/src/studio-layout.ts` |
+| Studio, when served | `127.0.0.1:4242` from `createStudioServer` in `plugins/kxm/src/studio-layout.ts`; its optional control relay targets `KXM_CONTROL_URL` |
+| Python control API | ASGI listener selected by deployment; the package declares no host or port default |
 | Antigravity OAuth callback | loopback port `51121` only during login (`plugins/kxm/src/providers/antigravity/auth/oauth.ts`) |
 
 ## Related

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

@@ -1,7 +1,8 @@
 # CI and release
 
-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.
+Pull requests run lint, typecheck, the Node unit suite on Linux Node 24, and
+the Python control-plane suite against PostgreSQL 17. Pushes to `main` also run
+the Node 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
@@ -15,7 +16,7 @@ release and an npm publish; the nightly job adds the slower suites.
 
 ```mermaid
 flowchart LR
-  PR[Pull request] -->|"unit shards, docs lint, plugin validation"| REQ["CI / required"]
+  PR[Pull request] -->|"Node shards, Python/Postgres, docs lint, plugin validation"| REQ["CI / required"]
   REQ --> MERGE{Merged?}
   MERGE -->|yes| MAIN[main]
   MAIN -->|"unit shards plus validate:pr matrix"| PUSH[Push CI]
@@ -40,6 +41,7 @@ together.
 | 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 |
 | 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`, `runtime.test.ts`, and `package-install.test.ts` one file at a time; every other unit file in two light shards. Typecheck and `check-generated` run on `light-1` |
+| Code pull request and code push | `ci.yml` (Python control plane) | Python 3.13 `unittest` contracts from the frozen uv workspace against PostgreSQL 17 started by `scripts/ci-postgres-17.sh` |
 | Platform-sensitive pull request | `ci.yml` (Unit, Windows Node 24) | The same 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 |
@@ -73,7 +75,8 @@ What moved off the pull-request lane, and what did not:
   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.
+- Python control-plane validation and Plugin validation still run 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.
@@ -82,8 +85,13 @@ blocker: it is the only place the simulation suite and coverage floors run.
 
 Code pull requests run Docs lint, two Linux Node 24 engine shards, a serial
 lane (`permission.test.ts`, then `runtime.test.ts`, then
-`package-install.test.ts`), two light shards for every other unit file, and
-Plugin validation. `light-1` typechecks and checks generated bundles.
+`package-install.test.ts`), two light shards for every other Node unit file,
+the Python 3.13 control-plane suite against PostgreSQL 17, and Plugin
+validation. The Python lane stays on `kontextmind-doks`. That scale set has
+no container-engine socket, so the job starts PostgreSQL 17 with
+`scripts/ci-postgres-17.sh` on `127.0.0.1:5432` and uses the same admin and
+test DSNs as the contributor procedure in [Develop KXM](development.md).
+`light-1` 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 longest files off the light pool,
 which was 268 seconds when every non-engine file shared one job.
@@ -165,9 +173,10 @@ workaround.
 The first job, Classify changes, lists the changed paths and sets `code=false`
 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.
+A non-markdown file under `plans/` is code. Unit lanes, the Python control-plane
+lane, 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,

package/docs/contributing/decisions.md

@@ -198,3 +198,34 @@ Evidence: Evidence: `git diff HEAD origin/main` on the stale branch showed upstr
 - Interim recommendation: use the opt-in installer until OMP exposes a
   first-class transactional status-preset API.
 Evidence: `plugins/kxm/src/cli/plugins.ts`, `plugins/kxm/src/session-work.ts`, and `test/core/cli.test.ts`.
+
+## 2026-10-11 — Bring the witnessed MG1 Python foundation onto main (migration)
+
+- Context: the tracker records MG1 as passed off-repo while the operator's
+  primary checkout holds the matching untracked Python workspace, MG0 evidence,
+  and Studio control-account proxy. Leaving the implementation outside Git
+  makes the recorded gate irreproducible and blocks MG2 from a reviewed base.
+- Options:
+  - Keep MG1 off-repo and start the roadmap's role-authority work — weight 0.2.
+    Avoids a CI change, but preserves the tracker/source contradiction and risks
+    losing the only implementation matching the deployed witness.
+  - Import MG1 at `python/kxm-control`, keep Node as the current product owner,
+    and add a required Python/PostgreSQL contract lane — weight 0.9. Makes the
+    accepted foundation reproducible without claiming a Python cutover.
+  - Replace the Node CLI and Runtime with the Python package now — weight 0.1.
+    MG2 through MG8 are still open, so this would skip import, bridge, runner,
+    parity, and retirement gates.
+- Selected: import the bounded MG1 foundation and its evidence, harden the
+  Studio proxy, and make the Python unit/contract suite part of `CI / required`.
+  SQLite and the Node Runtime remain authoritative. OpenAPI and the Studio
+  path inventory are derived from the FastAPI app; the checked generator emits
+  the revision helper. The package does not change host or guest installs.
+  After registration removal, registry routes return `registration_unavailable`
+  until the schema is installed again.
+- Solid recommendation: keep every accepted migration wave in Git with its
+  generated contracts and a required service-backed test lane.
+- Interim recommendation: if the service lane is unavailable, do not merge the
+  Python source; retain the off-repo tracker wording rather than claiming an
+  unverified gate.
+Evidence: `plans/implementation-plan.md`, `plans/plan-python-migration.md`,
+`python/kxm-control/tests/test_mg1.py`, and `.github/workflows/ci.yml`.

package/docs/contributing/development.md

@@ -23,7 +23,10 @@ extension, the Claude Code plugin, or the bundled skills.
     `kxm lane run <unit> --brief <file> --workflow implement-only`.
     The read-only critic workflows on the same command are
     `review-arch-only` and `review-cli-only`.
-  - Docker for the clean-container install smoke.
+  - Docker for the clean-container install smoke and the Python control-plane
+    contract suite.
+  - Python 3.13 and [`uv`](https://docs.astral.sh/uv/) for the Python
+    control-plane contract suite.
 
 ## Set up a checkout
 
@@ -255,6 +258,41 @@ It runs three scripts in order:
 | 2 | `npm run check` | `tsc --noEmit`, `markdownlint-cli2`, and version surfaces |
 | 3 | `npm run check:generated` | Generated artifacts are tracked and match the staged copy |
 
+Changes to the Python control plane also run its frozen-workspace contract
+suite before the npm gate. The suite drops and recreates `kxm_mg1_test`, so
+the admin DSN account needs database create and drop privilege. The `postgres`
+superuser in the container below is that account. Run PostgreSQL 17 in a
+disposable container published only on loopback `127.0.0.1:5432`, with
+`POSTGRES_PASSWORD=postgres`. Leave port `5432` on loopback free. Wait until
+`pg_isready` succeeds, export the two DSNs CI uses, run the frozen suite, and
+remove the container afterward:
+
+```bash
+docker rm -f kxm-mg1-pg >/dev/null 2>&1 || true
+docker run --detach --name kxm-mg1-pg \
+  --publish 127.0.0.1:5432:5432 \
+  --env POSTGRES_PASSWORD=postgres \
+  postgres:17
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30; do
+  docker exec kxm-mg1-pg pg_isready -U postgres && break
+  sleep 1
+done
+docker exec kxm-mg1-pg pg_isready -U postgres
+export KXM_MG1_ADMIN_DSN='host=127.0.0.1 port=5432 dbname=postgres user=postgres password=postgres'
+export KXM_MG1_TEST_DSN='host=127.0.0.1 port=5432 dbname=kxm_mg1_test user=postgres password=postgres'
+uv run --project python --frozen python -m unittest discover -s python/kxm-control/tests
+suite_status=$?
+docker rm -f kxm-mg1-pg
+(exit "$suite_status")
+```
+
+The required CI aggregate repeats that suite against PostgreSQL 17 with the
+same two DSNs and the same `postgres` superuser. On the `kontextmind-doks`
+runners, `scripts/ci-postgres-17.sh` starts that server on `127.0.0.1:5432`
+from a pinned PostgreSQL 17 binary. Contributors use the `postgres:17`
+container procedure above, which publishes the same port and DSNs. The suite
+remains a CI lane rather than a third root gate script.
+
 Every suite script passes `--test-force-exit`, and `scripts/run-bounded.mjs` stops the run if the suite is still going after its wall-clock limit (20 minutes, or 40 for the complete and coverage suites). The bound is that wall clock per script. A per-test timeout is not used because under `node --test` each file is itself a test, so a per-test timeout also bounds each file.
 
 Other scripts you will use:

package/docs/reference/configuration.md

@@ -30,6 +30,7 @@ Names that start with `KXM_` are not all operator settings. This map covers ever
 | Agents | `KXM_SERVER_URL`, `KXM_AUTH_TOKEN`, `KXM_PROJECT`, `KXM_AGENT_NAME`, `KXM_AGENT_PURPOSE` | [Agent settings](#agent-settings) |
 | Long-lived Pi workers | `KXM_PI_COMMAND`, `KXM_WORKER_*` (operator settings), `KXM_AGENT_LOG_PATH` | [Long-lived worker settings](#long-lived-worker-settings) |
 | Runtime supervisor | `KXM_STATE_HOME`, `KXM_RUNTIME_SYNC_INTERVAL_MS`, `KXM_RUNTIME_STOP_GRACE_MS` | [Runtime supervisor settings](#runtime-supervisor-settings) |
+| Studio and Python control plane | `KXM_CONTROL_URL`, `KXM_KXMD_*`, `KXM_AUTHENTIK_*`, `KXM_POSTGRES_*`, `KXM_DATABASE`, `KXM_DB_USER`, `KXM_TEMPORAL_*` | [Studio and Python control-plane settings](#studio-and-python-control-plane-settings) |
 | Operator CLI and sessions | `KXM_USER_CONFIG_DIR`, `KXM_USER_TELEMETRY_DIR`, `KXM_SESSION_TOKEN`, `KXM_SESSION_BRIEF`, `KXM_WORKFLOW_*`, `GITHUB_TOKEN`, and others | [CLI and session settings](#cli-and-session-settings) |
 | Nous model providers | `KXM_NOUS_PROVIDERS`, `KXM_NOUS_PROXY_URL`, `KXM_NOUS_DISCOVERY_TIMEOUT_MS`, `KXM_NOUS_CATALOG_FILE`, `NOUS_API_KEY` | [Nous providers](../guides/nous-providers.md) |
 | Browser automation | `KXM_BROWSER`, `OBSCURA_CDP_URL`, `OBSCURA_PORT`, `STEEL_API_URL`, `STEEL_UI_URL`, `STEEL_AUTH_HEADER`, `STEEL_AUTH_BASIC`, `STEEL_AUTH_USER`, `STEEL_AUTH_TOKEN`, `STEEL_API_KEY` (legacy), `USE_PASS_CLI` | [Browser settings](#browser-automation) |
@@ -187,6 +188,27 @@ The Runtime supervisor runs `kxm run` workflows and syncs their summaries to the
 | `KXM_RUNTIME_SYNC_INTERVAL_MS` | `10000` | How often the supervisor heartbeats and pushes its outbox, clamped to `250` through `60000` |
 | `KXM_RUNTIME_STOP_GRACE_MS` | `30000` | How long a stopping supervisor waits for open drives, `0` to `600000`; an invalid value warns and uses the default |
 
+## Studio and Python control-plane settings
+
+The MG1 Python service is additive: these values do not redirect the Node hub
+or Runtime from SQLite. Requests cannot override its database host, database,
+role, Temporal target, or namespace.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `KXM_CONTROL_URL` | Unset | Python control API base URL used by Studio's `GET /api/control/account` relay. The relay returns `control_unconfigured` when absent, and aborts a nonresponding upstream after three seconds with `control_unreachable` |
+| `KXM_KXMD_PASSWORD` | None; required | PostgreSQL password for the fixed `kxmd` role. Keep it in the deployment secret manager |
+| `KXM_POSTGRES_HOST` | `127.0.0.1` | PostgreSQL host selected by the service deployment, including an operator-owned tunnel |
+| `KXM_POSTGRES_PORT` | `5432` | PostgreSQL port, from 1 through 65535 |
+| `KXM_DATABASE` | `kxmd` | Fixed database assertion. Any other value refuses startup-time account resolution |
+| `KXM_DB_USER` | `kxmd` | Fixed PostgreSQL role assertion. Any other value is refused |
+| `KXM_TEMPORAL_TARGET` | `127.0.0.1:7233` | Temporal endpoint selected by the service deployment |
+| `KXM_TEMPORAL_NAMESPACE` | `kxmd` | Fixed Temporal namespace assertion. Any other value is refused |
+| `KXM_KXMD_ARTIFACTS` | `/var/lib/kxm/artifacts/kxmd` | Root for bounded per-tenant artifacts |
+| `KXM_AUTHENTIK_ISSUER` | None; required for authenticated routes | Exact token issuer |
+| `KXM_AUTHENTIK_AUDIENCE` | None; required for authenticated routes | Exact token audience |
+| `KXM_AUTHENTIK_JWKS_URL` | None; required for authenticated routes | JWKS endpoint used to verify RS256 user and runner tokens |
+
 ## CLI and session settings
 
 | Variable | Default | Effect |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.181",
+  "version": "0.7.183",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",
@@ -77,9 +77,9 @@
     ]
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.289",
-    "@earendil-works/pi-tui": "1.0.2",
-    "@modelcontextprotocol/sdk": "1.32.0",
+    "@anthropic-ai/claude-agent-sdk": "0.3.296",
+    "@earendil-works/pi-tui": "1.1.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
     "yaml": "^2.9.0"
   },
   "peerDependencies": {
@@ -95,17 +95,17 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.0.2",
-    "@modelcontextprotocol/sdk": "1.32.0",
-    "@playwright/test": "1.63.0",
-    "@types/node": "26.6.4",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@playwright/test": "1.64.0",
+    "@types/node": "26.6.5",
     "ajv": "8.20.0",
     "commander": "15.0.0",
     "esbuild": "0.28.2",
     "markdownlint-cli2": "0.23.3",
-    "nx": "23.2.1",
+    "nx": "23.3.0",
     "tsx": "^4.23.13",
-    "typebox": "1.3.34",
+    "typebox": "1.3.36",
     "typescript": "7.0.2"
   },
   "files": [

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.181",
+  "version": "0.7.183",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/cli.js

@@ -38995,6 +38995,11 @@ function generateStudioLayout(plan, state) {
   };
 }
 var DEFAULT_STUDIO_PORT = 4242;
+function isKxmdAccountView(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const account = value;
+  return account.account === "kxmd" && account.database === "kxmd" && account.namespace === "kxmd" && account.role === "kxmd";
+}
 function createStudioServer(options = {}) {
   const targetPort = options.port ?? DEFAULT_STUDIO_PORT;
   const host = options.host ?? "127.0.0.1";
@@ -39013,6 +39018,46 @@ function createStudioServer(options = {}) {
       res.end(JSON.stringify({ ok: true, studio: true, port: targetPort }));
       return;
     }
+    if (url.pathname === "/api/control/account" && req.method === "GET") {
+      const base = options.controlUrl ?? process.env.KXM_CONTROL_URL;
+      if (!base) {
+        res.writeHead(503, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: "control_unconfigured" }));
+        return;
+      }
+      let upstream;
+      try {
+        upstream = await fetch(new URL("/v1/account", base), {
+          signal: AbortSignal.timeout(3e3)
+        });
+      } catch {
+        res.writeHead(502, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: "control_unreachable" }));
+        return;
+      }
+      const contentType = upstream.headers.get("content-type");
+      if (!contentType?.toLowerCase().startsWith("application/json")) {
+        res.writeHead(502, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: "control_response_invalid" }));
+        return;
+      }
+      let body;
+      try {
+        body = await upstream.json();
+      } catch {
+        res.writeHead(502, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: "control_response_invalid" }));
+        return;
+      }
+      if (upstream.ok && !isKxmdAccountView(body)) {
+        res.writeHead(502, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: "control_response_invalid" }));
+        return;
+      }
+      res.writeHead(upstream.status, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(body));
+      return;
+    }
     if (url.pathname === "/api/layout" && req.method === "GET") {
       const plan = options.planProvider?.();
       if (!plan) {
@@ -45197,6 +45242,9 @@ function detectCapabilitiesFromEnvironment(tmuxForwardsHyperlink) {
   if (term.startsWith("screen")) {
     return { images: null, trueColor: hasTrueColorHint, hyperlinks: false };
   }
+  if (termProgram === "herdr") {
+    return { images: null, trueColor: hasTrueColorHint, hyperlinks: true };
+  }
   if (process.env.KITTY_WINDOW_ID || termProgram === "kitty") {
     return { images: "kitty", trueColor: true, hyperlinks: true };
   }
@@ -46352,6 +46400,10 @@ var Box = class {
   setBgFn(bgFn) {
     this.bgFn = bgFn;
   }
+  setPaddingX(paddingX) {
+    this.paddingX = paddingX;
+    this.invalidateCache();
+  }
   invalidateCache() {
     this.cache = void 0;
   }
@@ -46461,11 +46513,11 @@ var TUI_KEYBINDINGS = {
     description: "Move cursor word right"
   },
   "tui.editor.cursorLineStart": {
-    defaultKeys: ["home", "ctrl+home", "ctrl+a"],
+    defaultKeys: ["home", "ctrl+a"],
     description: "Move to line start"
   },
   "tui.editor.cursorLineEnd": {
-    defaultKeys: ["end", "ctrl+end", "ctrl+e"],
+    defaultKeys: ["end", "ctrl+e"],
     description: "Move to line end"
   },
   "tui.editor.jumpForward": {
@@ -46570,8 +46622,8 @@ var TUI_KEYBINDINGS = {
     defaultKeys: "escape",
     description: "Close transcript search"
   },
-  "tui.altScreen.top": { defaultKeys: "home", description: "Scroll viewport to top" },
-  "tui.altScreen.bottom": { defaultKeys: "end", description: "Scroll viewport to bottom" }
+  "tui.altScreen.top": { defaultKeys: "ctrl+home", description: "Scroll viewport to top" },
+  "tui.altScreen.bottom": { defaultKeys: "ctrl+end", description: "Scroll viewport to bottom" }
 };
 function normalizeKeys(keys) {
   if (keys === void 0)
@@ -46692,6 +46744,10 @@ var Text = class {
     this.cachedWidth = void 0;
     this.cachedLines = void 0;
   }
+  setPaddingX(paddingX) {
+    this.paddingX = paddingX;
+    this.invalidate();
+  }
   invalidate() {
     this.cachedText = void 0;
     this.cachedWidth = void 0;
@@ -47805,6 +47861,40 @@ function getNativePlatformHelper() {
   return loadNativePlatformHelper(process.platform);
 }
 
+// node_modules/@earendil-works/pi-tui/dist/program-status.js
+var PROGRAM_STATUS_QUERY = "\x1B]7501;?\x1B\\";
+function isProgramStatusReply(sequence) {
+  return /^\x1b\]7501;\?[^\x07\x1b]*(?:\x07|\x1b\\)$/.test(sequence);
+}
+var APP_PATTERN = /^[A-Za-z0-9_.+-]{1,32}$/;
+var CONTROL_CHARACTERS2 = /[\u0000-\u001f\u007f-\u009f]+/g;
+var MAX_MESSAGE_BYTES = 2048;
+function truncateUtf8(text, maxBytes) {
+  if (Buffer.byteLength(text, "utf8") <= maxBytes)
+    return text;
+  let bytes = 0;
+  let end = 0;
+  for (const char of text) {
+    const size = Buffer.byteLength(char, "utf8");
+    if (bytes + size > maxBytes)
+      break;
+    bytes += size;
+    end += char.length;
+  }
+  return text.slice(0, end);
+}
+function formatProgramStatus(status) {
+  const pairs = [`state=${status.state}`];
+  if (status.app !== void 0 && APP_PATTERN.test(status.app))
+    pairs.push(`app=${status.app}`);
+  if (status.state === "blocked" && status.kind)
+    pairs.push(`kind=${status.kind}`);
+  const message = truncateUtf8((status.message ?? "").replace(CONTROL_CHARACTERS2, " ").trim(), MAX_MESSAGE_BYTES);
+  if (message)
+    pairs.push(`msg=${Buffer.from(message, "utf8").toString("base64")}`);
+  return `\x1B]7501;${pairs.join(":")}\x1B\\`;
+}
+
 // node_modules/@earendil-works/pi-tui/dist/stdin-buffer.js
 import { EventEmitter as EventEmitter2 } from "events";
 var ESC = "\x1B";
@@ -48106,7 +48196,8 @@ var TERMINAL_PROGRESS_CLEAR_SEQUENCE = "\x1B]9;4;0\x07";
 var NATIVE_SHIFT_ENTER_SEQUENCE = "\x1B[13;2u";
 var DESIRED_KITTY_KEYBOARD_PROTOCOL_FLAGS = 7;
 var KEYBOARD_PROTOCOL_RESPONSE_FRAGMENT_TIMEOUT_MS = 150;
-var KITTY_KEYBOARD_PROTOCOL_QUERY = `\x1B[>${DESIRED_KITTY_KEYBOARD_PROTOCOL_FLAGS}u\x1B[?u\x1B[c`;
+var KITTY_KEYBOARD_PROTOCOL_QUERY = `\x1B[>${DESIRED_KITTY_KEYBOARD_PROTOCOL_FLAGS}u\x1B[?u`;
+var DEVICE_ATTRIBUTES_QUERY = "\x1B[c";
 function parseKeyboardProtocolNegotiationSequence(sequence) {
   const kittyFlags = sequence.match(/^\x1b\[\?(\d+)u$/);
   if (kittyFlags) {
@@ -48162,6 +48253,12 @@ var ProcessTerminal = class {
   stdinBuffer;
   stdinDataHandler;
   progressInterval;
+  /** Latest program status, kept across stop() so start() can report it again. */
+  programStatus;
+  /** Whether the terminal confirmed OSC 7501 support since the last start(), or `PI_PROGRAM_STATUS=1`. */
+  programStatusSupported = false;
+  /** The support query was sent and its DA1 sentinel has not arrived yet. */
+  programStatusQueryPending = false;
   writeLogPath = (() => {
     const env = process.env.PI_TUI_WRITE_LOG || "";
     if (!env)
@@ -48208,6 +48305,14 @@ var ProcessTerminal = class {
   setupStdinBuffer() {
     this.stdinBuffer = new StdinBuffer({ escapeTimeout: resolveEscapeTimeoutMs() });
     this.stdinBuffer.on("data", (sequence) => {
+      if (isProgramStatusReply(sequence)) {
+        if (this.programStatusQueryPending) {
+          this.programStatusQueryPending = false;
+          this.programStatusSupported = true;
+          this.writeProgramStatus();
+        }
+        return;
+      }
       const negotiation = this.readKeyboardProtocolNegotiationSequence(sequence);
       if (negotiation === "pending") {
         this.scheduleKeyboardProtocolNegotiationBufferFlush();
@@ -48239,6 +48344,9 @@ var ProcessTerminal = class {
    * - 1 = disambiguate escape codes
    * - 2 = report event types (press/repeat/release)
    * - 4 = report alternate keys (shifted key, base layout key)
+   *
+   * The OSC 7501 program status query shares the DA sentinel: a terminal that supports it replies
+   * before DA. `PI_PROGRAM_STATUS=1` or `0` skips the query.
    */
   queryAndEnableKittyProtocol() {
     this.setupStdinBuffer();
@@ -48246,7 +48354,12 @@ var ProcessTerminal = class {
     this.keyboardProtocolPushed = true;
     this.pendingKeyboardProtocolDeviceAttributes += 1;
     this.clearKeyboardProtocolNegotiationBuffer();
-    process.stdout.write(KITTY_KEYBOARD_PROTOCOL_QUERY);
+    const programStatusOverride = process.env.PI_PROGRAM_STATUS;
+    this.programStatusSupported = programStatusOverride === "1";
+    this.programStatusQueryPending = programStatusOverride !== "1" && programStatusOverride !== "0";
+    const programStatusQuery = this.programStatusQueryPending ? PROGRAM_STATUS_QUERY : "";
+    process.stdout.write(`${KITTY_KEYBOARD_PROTOCOL_QUERY}${programStatusQuery}${DEVICE_ATTRIBUTES_QUERY}`);
+    this.writeProgramStatus();
   }
   handleKeyboardProtocolNegotiationSequence(negotiationSequence) {
     this.clearKeyboardProtocolNegotiationBuffer();
@@ -48254,6 +48367,8 @@ var ProcessTerminal = class {
       if (this.pendingKeyboardProtocolDeviceAttributes === 0)
         return false;
       this.pendingKeyboardProtocolDeviceAttributes -= 1;
+      if (this.pendingKeyboardProtocolDeviceAttributes === 0)
+        this.programStatusQueryPending = false;
     }
     if (negotiationSequence.type === "kitty-flags") {
       if (negotiationSequence.flags !== 0) {
@@ -48395,6 +48510,11 @@ var ProcessTerminal = class {
     if (this.clearProgressInterval()) {
       process.stdout.write(TERMINAL_PROGRESS_CLEAR_SEQUENCE);
     }
+    if (this.programStatusSupported && this.programStatus) {
+      process.stdout.write(formatProgramStatus({ state: "clear" }));
+    }
+    this.programStatusSupported = false;
+    this.programStatusQueryPending = false;
     process.stdout.write("\x1B[?2004l");
     const shouldDisableKittyProtocol = this.keyboardProtocolPushed || this._kittyProtocolActive;
     this.clearKeyboardProtocolNegotiationBuffer();
@@ -48463,6 +48583,16 @@ var ProcessTerminal = class {
   setTitle(title) {
     process.stdout.write(`\x1B]0;${title}\x07`);
   }
+  setProgramStatus(status) {
+    this.programStatus = status.state === "clear" ? void 0 : status;
+    if (this.programStatusSupported)
+      process.stdout.write(formatProgramStatus(status));
+  }
+  writeProgramStatus() {
+    if (this.programStatusSupported && this.programStatus) {
+      process.stdout.write(formatProgramStatus(this.programStatus));
+    }
+  }
   setProgress(active) {
     if (active) {
       process.stdout.write(TERMINAL_PROGRESS_ACTIVE_SEQUENCE);
@@ -49280,6 +49410,11 @@ var TuiAltScreen = class extends TuiBase {
       return false;
     return this.copyTextToClipboard(text);
   }
+  /** Drop the text selection and multi-click history, e.g. before the host replaces the transcript. */
+  resetTextSelection() {
+    this.clearTextSelection();
+    this.lastClick = void 0;
+  }
   /** The lines of the last rendered frame, one per terminal row, as written to the terminal. */
   getScreenLines() {
     return [...this.previousScreen];

package/plugins/kxm/dist/extension.js

@@ -41853,6 +41853,9 @@ function detectCapabilitiesFromEnvironment(tmuxForwardsHyperlink) {
   if (term.startsWith("screen")) {
     return { images: null, trueColor: hasTrueColorHint, hyperlinks: false };
   }
+  if (termProgram === "herdr") {
+    return { images: null, trueColor: hasTrueColorHint, hyperlinks: true };
+  }
   if (process.env.KITTY_WINDOW_ID || termProgram === "kitty") {
     return { images: "kitty", trueColor: true, hyperlinks: true };
   }
@@ -43008,6 +43011,10 @@ var Box = class {
   setBgFn(bgFn) {
     this.bgFn = bgFn;
   }
+  setPaddingX(paddingX) {
+    this.paddingX = paddingX;
+    this.invalidateCache();
+  }
   invalidateCache() {
     this.cache = void 0;
   }
@@ -43117,11 +43124,11 @@ var TUI_KEYBINDINGS = {
     description: "Move cursor word right"
   },
   "tui.editor.cursorLineStart": {
-    defaultKeys: ["home", "ctrl+home", "ctrl+a"],
+    defaultKeys: ["home", "ctrl+a"],
     description: "Move to line start"
   },
   "tui.editor.cursorLineEnd": {
-    defaultKeys: ["end", "ctrl+end", "ctrl+e"],
+    defaultKeys: ["end", "ctrl+e"],
     description: "Move to line end"
   },
   "tui.editor.jumpForward": {
@@ -43226,8 +43233,8 @@ var TUI_KEYBINDINGS = {
     defaultKeys: "escape",
     description: "Close transcript search"
   },
-  "tui.altScreen.top": { defaultKeys: "home", description: "Scroll viewport to top" },
-  "tui.altScreen.bottom": { defaultKeys: "end", description: "Scroll viewport to bottom" }
+  "tui.altScreen.top": { defaultKeys: "ctrl+home", description: "Scroll viewport to top" },
+  "tui.altScreen.bottom": { defaultKeys: "ctrl+end", description: "Scroll viewport to bottom" }
 };
 function normalizeKeys(keys) {
   if (keys === void 0)
@@ -43348,6 +43355,10 @@ var Text = class {
     this.cachedWidth = void 0;
     this.cachedLines = void 0;
   }
+  setPaddingX(paddingX) {
+    this.paddingX = paddingX;
+    this.invalidate();
+  }
   invalidate() {
     this.cachedText = void 0;
     this.cachedWidth = void 0;
@@ -44422,7 +44433,7 @@ var cjsRequire = createRequire4(import.meta.url);
 
 // node_modules/@earendil-works/pi-tui/dist/terminal.js
 var DESIRED_KITTY_KEYBOARD_PROTOCOL_FLAGS = 7;
-var KITTY_KEYBOARD_PROTOCOL_QUERY = `\x1B[>${DESIRED_KITTY_KEYBOARD_PROTOCOL_FLAGS}u\x1B[?u\x1B[c`;
+var KITTY_KEYBOARD_PROTOCOL_QUERY = `\x1B[>${DESIRED_KITTY_KEYBOARD_PROTOCOL_FLAGS}u\x1B[?u`;
 
 // node_modules/@earendil-works/pi-tui/dist/alt-screen-search.js
 var segmenter2 = getGraphemeSegmenter();
@@ -45219,6 +45230,11 @@ var TuiAltScreen = class extends TuiBase {
       return false;
     return this.copyTextToClipboard(text);
   }
+  /** Drop the text selection and multi-click history, e.g. before the host replaces the transcript. */
+  resetTextSelection() {
+    this.clearTextSelection();
+    this.lastClick = void 0;
+  }
   /** The lines of the last rendered frame, one per terminal row, as written to the terminal. */
   getScreenLines() {
     return [...this.previousScreen];

package/plugins/kxm/dist/mcp-server.js

@@ -25462,7 +25462,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.181";
+var VERSION = "0.7.183";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.181",
+  "version": "0.7.183",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.181";
+const VERSION = "0.7.183";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/plugins/kxm/src/studio-layout.ts

@@ -290,6 +290,7 @@ export interface StudioServerOptions {
   planProvider?: (() => KxmCompiledPlan | undefined) | undefined;
   stateProvider?: (() => KxmRunState | undefined) | undefined;
   onMutation?: ((command: string, args: Record<string, unknown>) => Promise<{ ok: boolean; result?: unknown; error?: string }> | { ok: boolean; result?: unknown; error?: string }) | undefined;
+  controlUrl?: string | undefined;
 }
 
 export interface StudioServerHandle {
@@ -299,6 +300,15 @@ export interface StudioServerHandle {
   close: () => Promise<void>;
 }
 
+function isKxmdAccountView(value: unknown): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  const account = value as Record<string, unknown>;
+  return account.account === "kxmd"
+    && account.database === "kxmd"
+    && account.namespace === "kxmd"
+    && account.role === "kxmd";
+}
+
 /**
  * Embedded Web Studio Local Server (Decision Q8 & D14).
  * Serves the visual DAG, form stepper, and Temporal swimlane dashboards on http://localhost:4242.
@@ -328,6 +338,46 @@ export function createStudioServer(options: StudioServerOptions = {}): StudioSer
       return;
     }
 
+    if (url.pathname === "/api/control/account" && req.method === "GET") {
+      const base = options.controlUrl ?? process.env.KXM_CONTROL_URL;
+      if (!base) {
+        res.writeHead(503, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: "control_unconfigured" }));
+        return;
+      }
+      let upstream: Response;
+      try {
+        upstream = await fetch(new URL("/v1/account", base), {
+          signal: AbortSignal.timeout(3_000),
+        });
+      } catch {
+        res.writeHead(502, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: "control_unreachable" }));
+        return;
+      }
+      const contentType = upstream.headers.get("content-type");
+      if (!contentType?.toLowerCase().startsWith("application/json")) {
+        res.writeHead(502, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: "control_response_invalid" }));
+        return;
+      }
+      let body: unknown;
+      try {
+        body = await upstream.json();
+      } catch {
+        res.writeHead(502, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: "control_response_invalid" }));
+        return;
+      }
+      if (upstream.ok && !isKxmdAccountView(body)) {
+        res.writeHead(502, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: "control_response_invalid" }));
+        return;
+      }
+      res.writeHead(upstream.status, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(body));
+      return;
+    }
     if (url.pathname === "/api/layout" && req.method === "GET") {
       const plan = options.planProvider?.();
       if (!plan) {

package/scripts/ci-postgres-17.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+# Start PostgreSQL 17 on 127.0.0.1:5432 for the Python MG1 lane.
+# The kontextmind-doks scale set has a client binary and no engine socket, so
+# this job provisions the server from a pinned archive instead of a workflow
+# service. A second call in the same job returns once that server is ready.
+
+set -euo pipefail
+
+version=17.11.0
+triple=x86_64-unknown-linux-gnu
+sha256=b7a1ba6bae6499d8296e3e81b0171eecfd1766ca9aaa0057e41ad3e844e5e2e0
+archive_name="postgresql-${version}-${triple}.tar.gz"
+url="https://github.com/theseus-rs/postgresql-binaries/releases/download/${version}/${archive_name}"
+
+if [[ "$(uname -s)" != "Linux" || "$(uname -m)" != "x86_64" ]]; then
+  echo "PostgreSQL 17 CI archive is linux/x86_64 only (got $(uname -s)/$(uname -m))" >&2
+  exit 1
+fi
+
+work="${RUNNER_TEMP:-${TMPDIR:-/tmp}}/kxm-mg1-postgres"
+prefix="${work}/postgresql-${version}-${triple}"
+pgdata="${work}/data"
+pglog="${work}/postgres.log"
+pwfile="${work}/pwfile"
+mkdir -p "$work"
+
+package_for_library() {
+  case "$1" in
+    libzstd.so.*) echo libzstd1 ;;
+    liblz4.so.*) echo liblz4-1 ;;
+    libxml2.so.*) echo libxml2 ;;
+    liblzma.so.*) echo liblzma5 ;;
+    libssl.so.3 | libcrypto.so.3) echo libssl3 ;;
+    libicuuc.so.74 | libicui18n.so.74 | libicudata.so.74) echo libicu74 ;;
+    libgssapi_krb5.so.*) echo libgssapi-krb5-2 ;;
+    libkrb5.so.* | libk5crypto.so.* | libkrb5support.so.*) echo libkrb5-3 ;;
+    libcom_err.so.*) echo libcom-err2 ;;
+    libkeyutils.so.*) echo libkeyutils1 ;;
+    libstdc++.so.*) echo libstdc++6 ;;
+    libgcc_s.so.*) echo libgcc-s1 ;;
+    libz.so.*) echo zlib1g ;;
+    *) return 1 ;;
+  esac
+}
+
+server_version_num() {
+  PGPASSWORD=postgres "${prefix}/bin/psql" \
+    -h 127.0.0.1 -p 5432 -U postgres -d postgres \
+    -Atqc "SHOW server_version_num"
+}
+
+postgres_17_ready() {
+  [[ -x "${prefix}/bin/pg_isready" ]] || return 1
+  "${prefix}/bin/pg_isready" -h 127.0.0.1 -p 5432 -U postgres >/dev/null 2>&1 || return 1
+  local num
+  num="$(server_version_num 2>/dev/null)" || return 1
+  [[ "$num" -ge 170000 && "$num" -lt 180000 ]]
+}
+
+install_missing_libraries() {
+  local -a missing=()
+  local line
+  while IFS= read -r line; do
+    [[ -n "$line" ]] && missing+=("$line")
+  done < <(ldd "${prefix}/bin/postgres" | awk '/not found$/ { print $1 }')
+  if [[ ${#missing[@]} -eq 0 ]]; then
+    return 0
+  fi
+
+  local -a packages=()
+  local lib pkg
+  for lib in "${missing[@]}"; do
+    if ! pkg="$(package_for_library "$lib")"; then
+      echo "PostgreSQL 17 needs ${lib}, which has no package mapping on this runner" >&2
+      ldd "${prefix}/bin/postgres" >&2 || true
+      exit 1
+    fi
+    packages+=("$pkg")
+  done
+  mapfile -t packages < <(printf '%s\n' "${packages[@]}" | awk '!seen[$0]++')
+  echo "Installing shared libraries for PostgreSQL 17: ${packages[*]}"
+  sudo -n apt-get update
+  sudo -n DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends "${packages[@]}"
+
+  local -a still=()
+  while IFS= read -r line; do
+    [[ -n "$line" ]] && still+=("$line")
+  done < <(ldd "${prefix}/bin/postgres" | awk '/not found$/ { print $1 }')
+  if [[ ${#still[@]} -gt 0 ]]; then
+    echo "PostgreSQL 17 still needs: ${still[*]}" >&2
+    exit 1
+  fi
+}
+
+if postgres_17_ready; then
+  echo "PostgreSQL 17 already ready on 127.0.0.1:5432 (server_version_num=$(server_version_num))"
+  exit 0
+fi
+
+if [[ ! -x "${prefix}/bin/postgres" ]]; then
+  echo "Downloading PostgreSQL ${version}"
+  curl --fail --silent --show-error --location --retry 5 --retry-delay 2 \
+    --output "${work}/${archive_name}" \
+    "$url"
+  echo "${sha256}  ${work}/${archive_name}" | sha256sum -c -
+  tar -xzf "${work}/${archive_name}" -C "$work"
+fi
+install_missing_libraries
+
+if [[ ! -s "${pgdata}/PG_VERSION" ]]; then
+  printf '%s\n' postgres >"$pwfile"
+  chmod 600 "$pwfile"
+  "${prefix}/bin/initdb" \
+    --username=postgres \
+    --pwfile="$pwfile" \
+    --auth-host=scram-sha-256 \
+    --auth-local=trust \
+    --encoding=UTF8 \
+    --locale=C \
+    --set listen_addresses=127.0.0.1 \
+    --set port=5432 \
+    --set shared_buffers=16MB \
+    --set max_connections=20 \
+    --set shared_memory_type=mmap \
+    --set dynamic_shared_memory_type=mmap \
+    --set huge_pages=off \
+    --set fsync=off \
+    --set synchronous_commit=off \
+    --set full_page_writes=off \
+    --pgdata="$pgdata"
+fi
+
+if ! "${prefix}/bin/pg_ctl" -D "$pgdata" -l "$pglog" -w -t 30 start; then
+  echo "PostgreSQL 17 failed to start" >&2
+  cat "$pglog" >&2 || true
+  exit 1
+fi
+
+num="$(server_version_num)"
+if [[ "$num" -lt 170000 || "$num" -ge 180000 ]]; then
+  echo "PostgreSQL 17 required, server_version_num=${num}" >&2
+  exit 1
+fi
+echo "PostgreSQL 17 ready on 127.0.0.1:5432 (server_version_num=${num})"