@a5c-ai/krate 5.0.1-staging.f672fe79b

package/docs/README.md

@@ -0,0 +1,61 @@
+# Krate Documentation
+
+Krate is an a5c.ai Kubernetes-native forge project.
+
+Krate is a Kubernetes-native Git forge where repositories, pull requests, CI, hooks, and policy share Kubernetes identity, RBAC, admission, and declarative APIs.
+
+## Reading order
+
+1. [Product requirements](product-requirements.md) — positioning, personas, outcomes, and non-goals.
+2. [System requirements](system-requirements.md) — full-system integration, publish, install, upgrade, security, and release requirements.
+3. [Architecture spec](architecture-spec.md) — control-plane/data-plane decomposition and resource model.
+4. [User stories](user-stories.md) — persona- and workflow-oriented stories with acceptance criteria.
+5. [MVP roadmap](roadmap-mvp.md) — six-week MVP scope and release gates.
+6. [Installation and local development](install.md) — quickstart, Next.js UI, validation, and minikube dry-run.
+
+## Component specs
+
+- [Control plane](components/control-plane.md)
+- [Data plane](components/data-plane.md)
+- [Identity, RBAC, and policy](components/identity-rbac-policy.md)
+- [Runners and CI](components/runners-ci.md)
+- [Hooks and events](components/hooks-events.md)
+- [Web UI](components/web-ui.md) — implemented locally in `../apps/web`
+- [Operations and publishing](components/operations-publishing.md)
+
+## Source of truth
+
+These specs are derived from `krate-design.md`. The key architectural commitments are:
+
+- CRDs are the declarative API contract, not the storage engine for high-cardinality social data.
+- Pull requests, issues, reviews, pipelines, jobs, and runner activity are Kubernetes API resources served by an aggregated API server backed by Postgres.
+- Git repository storage is backed by Gitea plus object storage metadata, not one PVC per repository.
+- Human and CI permissions use Kubernetes identity and RBAC; Krate does not introduce PATs or a parallel authorization system.
+- Every mutating UI action must expose the equivalent YAML and `kubectl` command.
+
+## Package and local lifecycle
+
+- Product home: `https://a5c.ai/krate`
+- Helm-style chart package: `../charts/krate`
+- Next.js UI: `../apps/web` (`npm run dev`, `npm run ui:build`)
+- Minikube setup script: `../scripts/setup-minikube.mjs`
+- Demo resources: `../examples/minikube-demo.yaml`
+- Deterministic gates: `npm run check`, `npm run e2e`, `npm run package:check`, `npm run ui:build`, and `npm run setup:minikube -- --dry-run`
+
+- [KubeVela and OAM Integration](components/kubevela-oam.md)
+- [OAM and KubeVela Ontology Assimilation](ontology/oam-kubevela.md)
+
+## Organization scoping
+
+Krate is org-first: every repository, deployment, runner, agent, memory source, session, workspace, secret, and config grant belongs to an organization, and each organization maps to a Kubernetes namespace. See `docs/gaps.md` and `docs/agents/org-scoping-namespace-spec.md` for the remaining org-scoping requirements and agent memory implications.
+
+## QA and testing
+
+- [QA automation and test strategy](tests/README.md) defines the product-wide test plan, framework, coverage model, E2E/browser/UI/unit strategy, CI gates, fixtures, security checks, reliability tests, and future agent QA plan.
+- The current local all-up gate is `npm run check`; future gates should add browser, coverage, security, chart, and agent-specific suites without weakening the existing scripts.
+
+## External backend integrations
+
+- [External backend integration docs](external/README.md) define GitHub-first integration and future provider support through three independent interfaces: issue tracking, CI/CD, and git forge. The docs cover research, provider model, CRDs, controllers, bidirectional sync, user-facing changes, security, and rollout/testing.
+
+The external backend docs include a provider catalog and UI/CRD/controller specs for pluggable backends beyond GitHub, including issue-only, CI-only, git-forge-only, and full-forge providers.

package/docs/agents/README.md

@@ -0,0 +1,83 @@
+# Agent dispatch integration docs
+
+This directory captures the docs-only specification for adding agent orchestration to Krate git workspaces. The focus is a system-wide orchestration model: define agent stacks, bind tools/skills/subagents, connect them to triggers, run them on policy-controlled workspaces, and present each dispatch like a CI pipeline run with live Agent Mux chat/session access.
+
+No controller, UI, API, CRD, runner, or workflow implementation is part of this change.
+
+## What this covers
+
+- How to define reusable agent stacks such as a Claude Code based agent with model, approval mode, tools, MCP servers, skills, subagents, prompts, and runtime policy.
+- How issue/session/workspace/dispatch relationships from Agent Mux kanban should become first-class system capabilities in Krate, not just UI widgets.
+- How CI checks, incoming webhooks, issue/PR comments, labels, schedules, and manual actions should trigger agent dispatches.
+- How agent dispatches should appear beside `Pipeline` and `Job` runs while also exposing Agent Mux transcript, session, runtime surfaces, approvals, artifacts, and workspace lifecycle actions.
+- How context labels should inject reviewed prompt fragments into dispatch context without becoming hidden launch commands or secret channels.
+- How Agent Mux can provide adapters, session streaming, chat, cancellation, run events, plugin/tool discovery, and workspace/session primitives while Krate remains the repository, policy, trigger, and audit source of truth.
+
+## Documents
+
+- [Agent system overview](./system-overview.md) is the short entry point for the complete architecture, MVP target, invariants, and where to read next.
+- [Agent glossary](./glossary.md) standardizes terminology across resources, UI, controllers, and Agent Mux boundaries.
+- [Agent traceability matrix](./traceability-matrix.md) maps requirements to resources, controllers, UI surfaces, docs, implementation files, and validation gates.
+
+- [Agent stack management spec](./agent-stack-management-spec.md) defines agent definitions, subagents, MCP tools, skills, trigger management, policy, and CI-like dispatch visibility.
+- [UI/UX system spec](./ui-ux-system-spec.md) maps agent screens and interactions to app routes, custom resources, aggregated resources, controllers, API actions, and watch streams.
+- [Integration design](./dispatching-design.md) defines the proposed Krate resources, trigger flow, work-item/session/workspace associations, chat/run UX, and implementation phases.
+- [CI orchestration spec](./ci-orchestration-spec.md) keeps the CI-specific failed-check, repair, flaky-test, and release-gate requirements.
+- [Source map](./agent-mux-source-map.md) maps relevant Babysitter Agent Mux paths, Krate CI paths, and repo docs to inspect before implementation.
+- [Implementation blueprint](./implementation-blueprint.md) maps the specs onto concrete Krate source files, controllers, routes, CRDs, API endpoints, rollout order, and tests.
+- [Resource contract examples](./resource-contract-examples.md) provides implementation-ready YAML and JSON examples for stacks, subagents, tools, MCP, skills, triggers, dispatches, approvals, and work-item links.
+- [RBAC, service account, secret, and config management spec](./rbac-secrets-management-spec.md) defines native Kubernetes Roles, RoleBindings, ServiceAccounts, permission review, Secret grants, ConfigMap grants, audit, drift handling, and UI permission management for agents, runners, tools, skills, and users.
+- [Agent CRD schema spec](./crd-schema-spec.md) maps agent resources onto Krate's existing `CONFIG_KINDS`, `AGGREGATED_KINDS`, schemas, labels, status conditions, and storage classes.
+- [Controller reconciliation spec](./controller-reconciliation-spec.md) defines reconciler loops, watches, outputs, idempotency, failure handling, and UI projection integration.
+- [API contract spec](./api-contract-spec.md) defines typed agent endpoints while preserving current controller/resource/watch API boundaries.
+- [UI flow and state spec](./ui-flow-spec.md) defines stack builder, grant wizards, permission review, dispatch composer, run detail, and repository settings flows.
+- [Security threat model](./security-threat-model.md) covers prompt injection, RBAC escalation, secret exfiltration, untrusted forks, MCP/tool abuse, session confusion, and write-back abuse.
+- [Acceptance test matrix](./acceptance-test-matrix.md) maps resources, controllers, APIs, UI, e2e flows, and package/chart validation to concrete acceptance gates.
+- [Storage and migration spec](./storage-migration-spec.md) defines etcd/Postgres/object-storage/native-Kubernetes storage boundaries, snapshots, indexes, retention, and migrations.
+- [Chart and packaging spec](./chart-packaging-spec.md) maps agent features into Helm values, CRDs, RBAC, deployments, NetworkPolicy, examples, and package validation.
+- [Agent Mux adapter contract](./agent-mux-adapter-contract.md) defines the launch/capability/event/session boundary between Krate and Agent Mux.
+- [Implementation rollout slices](./implementation-rollout-slices.md) sequences docs, resources, UI, permission review, stack registry, dispatch, Agent Mux binding, approvals, triggers, workspaces, and hardening.
+- [Context assembly and prompt safety spec](./context-assembly-spec.md) defines prompt layers, source provenance, redaction, context labels, bundle snapshots, and preview requirements.
+- [Observability and audit spec](./observability-audit-spec.md) defines metrics, events, traces, audit records, alerts, and run-detail projections.
+- [Repository page integration spec](./repository-page-integration-spec.md) maps agent affordances into the existing Code, Issues, Pull Requests, Runs, Hooks, Settings, and Inbox pages.
+- [Tools, MCP, and skills spec](./tools-mcp-skills-spec.md) defines tool profiles, MCP servers, skills, capability requirements, health, UI, and launch behavior.
+- [Subagent orchestration spec](./subagent-orchestration-spec.md) defines parent/child agent modes, context slicing, output contracts, permissions, telemetry, and UI lanes.
+- [Artifacts and write-back spec](./artifacts-writeback-spec.md) defines durable artifacts, patch/review outputs, approval-gated write-back, idempotency, and failure handling.
+- [Workspace lifecycle spec](./workspace-lifecycle-spec.md) defines workspace ownership, issue/session/run links, git/runtime state, lifecycle actions, trust isolation, and recovery.
+- [Resource relationship map](./resource-relationship-map.md) shows how agent resources connect to existing Krate repositories, PRs, issues, pipelines, webhooks, identity, RBAC, secrets, and UI pages.
+- [Operator runbook](./operator-runbook.md) explains safe enablement, preflight checks, troubleshooting, rollback, metrics, and support bundles.
+- [Developer implementation checklist](./developer-implementation-checklist.md) maps rollout slices to concrete files, tasks, validation commands, documentation updates, and stop conditions.
+- [MVP vertical slice spec](./mvp-vertical-slice-spec.md) defines the first coherent implementation target, included/deferred scope, acceptance criteria, tests, and non-negotiables.
+- [Decision log and open questions](./decision-log-open-questions.md) records accepted architecture decisions and open implementation questions.
+
+## Current decision
+
+Treat agents as configurable work executors attached to Krate's repository graph, not as a standalone chat dashboard. Krate should own repository-native objects such as repositories, issues, PRs, checks, pipelines, jobs, runner pools, workspaces, labels, trigger rules, context labels, native Kubernetes role/service-account projections, secret/config grants, approvals, artifacts, and audit records. Agent Mux should own adapter-specific execution, session lifecycle, transcript/event streaming, chat continuation, cancellation, plugins/tool surfaces, and runtime state projection.
+
+The first implementation should optimize for these paths:
+
+1. Define an agent stack, for example `claude-code` with selected model, subagents, MCP servers, skills, allowed tools, approval mode, workspace policy, and runner pool.
+2. Connect that agent stack to CI triggers, incoming webhooks, issue/PR mentions, labels, schedules, and manual dispatch buttons.
+3. Dispatch an agent from a failed PR check, webhook, or issue and see it as a CI-like run with queue, runner, logs/events, artifacts, status, and approvals.
+4. Open the linked Agent Mux chat/session from the run to continue, approve, cancel, inspect tools, follow subagents, and manage the associated workspace.
+
+## Company brain memory additions
+
+- [Shared memory company brain spec](./shared-memory-company-brain-spec.md) defines org-level Git-backed shared agent memory, Atlas-style graph/YAML/Markdown storage, memory resources, time-travel refs, update review, and UI requirements.
+- [Memory context integration spec](./memory-context-integration-spec.md) defines how context bundles read graph records, Markdown frontmatter records, free-form grep excerpts, ontology reports, and historical memory snapshots.
+- [Memory ontology and file schema spec](./memory-ontology-schema-spec.md) defines graph YAML, Markdown frontmatter, free-form notes, node/edge vocabulary, IDs, validation, indexes, and governance.
+- [Memory operations runbook](./memory-operations-runbook.md) defines bootstrap, validation, current/historical dispatch, memory update, rollback, migration, dashboards, and alerts.
+
+- [Org scoping and namespace spec](./org-scoping-namespace-spec.md) defines organization-first tenancy, one Kubernetes namespace per org, org-aware routes, labels, RBAC, cross-org rejection, and controller requirements.
+
+- [Agent run memory import spec](./agent-run-memory-import-spec.md) defines how `MEMORY.md`, Agent Mux/Babysitter sessions, curated `.a5c` journals, task results, artifact manifests, and retrospectives become governed org memory.
+- [Org route and resource model spec](./org-route-resource-model-spec.md) defines org-aware UI/API routes, resource refs, deployment scoping, namespace enforcement, and controller behavior.
+
+- [Org memory UI implementation map](./org-memory-ui-implementation-map.md) maps company brain and agent pages onto the current `apps/web/app/orgs/[org]` route tree and API seams.
+- [Org resource model delta spec](./org-resource-model-delta-spec.md) maps new agent/memory resources onto the existing `Organization`, `OrgNamespaceBinding`, `organizationRef`, CRD, and aggregated-resource model.
+
+- [Org memory controller sequence spec](./org-memory-controller-sequence-spec.md) defines org bootstrap, memory bootstrap, dispatch, historical memory, tool calls, Babysitter import, memory update, cross-org denial, and watch/event sequences.
+- [Org memory vertical slice spec](./org-memory-vertical-slice-spec.md) defines the smallest coherent implementation slice for org-scoped company brain memory and run imports.
+
+- [Org memory API payload examples](./org-memory-api-payload-examples.md) provides concrete request/response contracts for summary, ref resolution, memory query, dispatch, run detail, run import, import detail, and stable errors.
+- [Org memory E2E fixture plan](./org-memory-e2e-fixture-plan.md) defines deterministic org/repo/memory/`.a5c` fixtures and expected assertions for the vertical slice.

package/docs/agents/acceptance-test-matrix.md

@@ -0,0 +1,193 @@
+# Agent acceptance test matrix
+
+## Purpose
+
+This matrix turns the docs into validation work for implementation. It follows existing Krate validation style: start with resource/controller unit tests, then API route tests, UI validation, package/chart checks, and e2e flows.
+
+## Existing validation anchors
+
+Current commands to preserve:
+
+- `npm run validate:docs`
+- `npm run package:check`
+- `npm run ui:validate`
+- `npm test`
+- `npm run e2e`
+- `npm run check`
+
+## Resource/schema tests
+
+| Scenario | Expected proof |
+| --- | --- |
+| Agent config kinds appear in `CONFIG_KINDS` | `resourceSchemaForKind()` returns plural, storage, required fields. |
+| Agent execution kinds appear in `AGGREGATED_KINDS` | list schema returns postgres/object-storage intent. |
+| Conditions use stable fields | schema accepts type/status/reason/message/observedGeneration. |
+| `AgentSecretGrant` never stores values | schema rejects value-like fields. |
+| `AgentDispatchAttempt` identity snapshot immutable | update attempts cannot mutate runtime identity after launch. |
+
+## Controller tests
+
+| Controller | Scenario | Expected proof |
+| --- | --- | --- |
+| stack | missing tool Secret grant | `SecretsAdmitted=False`, `Ready=False`. |
+| stack | all requirements satisfied | stack `Ready=True`. |
+| rbac | role escalation attempted | no native binding apply; condition false; audit event. |
+| secret/config | Secret key deleted | dependent stacks blocked; active runs marked stale. |
+| trigger | duplicate failed check | second execution coalesces. |
+| dispatch | Agent Mux unavailable | attempt remains queued/starting with retry condition. |
+| dispatch | launch option rejected | attempt failed with adapter rejection reason. |
+| workspace | missing worktree path | workspace missing state and recover/archive actions. |
+| approval | artifact digest changed | approval decision rejected. |
+
+## API tests
+
+| Route | Scenario | Expected proof |
+| --- | --- | --- |
+| `POST /api/agents/permissions/review` | missing Secret grant | `decision=denied`, reason includes missing grant, no secret value. |
+| `POST /api/agents/runs` | valid manual dispatch | creates run + attempt before Agent Mux launch. |
+| `POST /api/agents/runs` | denied RBAC | returns `403 POLICY_DENIED`. |
+| `POST /api/agents/rules/:rule/dry-run` | matching CI event | returns prompt/context/dedupe/permission preview. |
+| `POST /api/agents/approvals/:approval/decision` | valid approver | approval updated and write-back accepted. |
+| `GET /api/watch/orgs/[org]/agentdispatchruns` | watch connected | emits initial SYNC event and resource updates. |
+
+## UI validation
+
+| Surface | Scenario | Expected proof |
+| --- | --- | --- |
+| stack builder | missing Secret grant | blocking warning with suggested fix. |
+| stack builder | ready stack | save/dispatch actions enabled by server state. |
+| repo code page | manual dispatch | composer prefilled with repo/ref/path. |
+| repo runs page | agent run exists | dispatch appears beside pipeline/job rows. |
+| run detail | session pending | handoff state shown until session bound. |
+| run detail | approval blocked | approval card and disabled write-back controls shown. |
+| settings agents tab | ServiceAccount selected | RBAC/grants/runner policy visible. |
+| secrets page | Secret listed | key names and consumers visible, no values. |
+| permissions page | drifted RoleBinding | drift warning and fix path visible. |
+
+## E2E flows
+
+### Manual dispatch from code
+
+1. Create `AgentStack`, ServiceAccount, grants, and workspace policy.
+2. Open repository code page.
+3. Dispatch agent with selected path.
+4. Verify `AgentDispatchRun`, attempt, context bundle, permission snapshot, and run detail link.
+
+### Failed CI repair
+
+1. Create failed `Pipeline`/`Job` event.
+2. Trigger rule matches and creates `AgentTriggerExecution`.
+3. Dispatch appears beside pipeline.
+4. Agent produces patch artifact.
+5. Write-back requires approval.
+
+### Missing secret remediation
+
+1. Enable tool requiring Secret.
+2. Stack builder shows missing grant.
+3. Create `AgentSecretGrant` from wizard.
+4. Stack readiness turns ready.
+5. Dispatch proceeds.
+
+### Untrusted fork denial
+
+1. Simulate fork PR event.
+2. Rule selects repair stack.
+3. Permission review denies privileged ServiceAccount/Secret.
+4. UI shows untrusted-fork reason and no launch occurs.
+
+### Approval write-back
+
+1. Agent creates PR comment request.
+2. Approval inbox shows action.
+3. Maintainer approves comment only.
+4. Controller posts comment idempotently and records audit.
+
+## Package/chart tests
+
+| Scenario | Expected proof |
+| --- | --- |
+| Agent CRDs in chart | `package:check` includes required CRDs and examples. |
+| Helm values include feature gates | values validation covers Agent Mux URL, default ServiceAccount, grants. |
+| Examples stay valid | examples use known kinds and required fields. |
+| Docs stay linked | `validate:docs` sees all agent docs in README index. |
+
+## Done gate for first implementation slice
+
+The first implementation slice is not complete until these are green:
+
+- resource/schema tests for `AgentStack`, `AgentServiceAccount`, `AgentSecretGrant`, `AgentDispatchRun`;
+- permission review API tests;
+- stack builder missing-grant UI validation;
+- manual dispatch API test;
+- run detail pending-session UI validation;
+- docs/package validation.
+
+## Company brain memory acceptance
+
+| Area | Acceptance gate |
+| --- | --- |
+| Memory repository | can create/adopt `AgentMemoryRepository` and validate layout. |
+| Ontology | invalid node kinds, edge kinds, dangling edges, and missing owners fail validation. |
+| Context | dispatch bundle records requested ref, resolved commit, selected records, grep excerpts, and digests. |
+| Historical refs | `refAt` resolves to the latest approved commit before timestamp and retries stay pinned. |
+| Permissions | denied memory paths/kinds never leak content into preview, prompt, tools, or audit. |
+| Tools | memory tools operate against dispatch snapshot and require explicit grants. |
+| Updates | agent memory proposals become validated PR/update records before merge. |
+| UI | `/agents/memory`, dispatch composer, run detail, and repository settings expose memory state and warnings. |
+
+## Org scoping acceptance
+
+| Area | Acceptance gate |
+| --- | --- |
+| Namespace | creating an org creates or binds one Kubernetes namespace. |
+| Repositories | repositories cannot be created without org scope. |
+| Deployments | deployment/environment resources are org-scoped and namespace-bound. |
+| Agents | stacks, triggers, runs, sessions, workspaces, and runners stay inside org scope. |
+| Memory | company brain query/update/import cannot cross org boundaries. |
+| Babysitter imports | `MEMORY.md`, sessions, journals, task results, and artifact manifests import only after redaction and org permission review. |
+| UI | routes, breadcrumbs, search, and YAML panels show org and namespace. |
+
+## Run memory import acceptance details
+
+| Scenario | Expected result |
+| --- | --- |
+| Import completed run with summary tier | creates normalized run/session/task files and opens review. |
+| Import active run without policy | blocks with clear condition. |
+| Import run from another org | fails with `CROSS_ORG_REF_DENIED`. |
+| Import journal containing secret-like content | redacts or blocks before PR creation. |
+| Import duplicate source digest | no duplicate PR; status points to existing memory commit. |
+| Import with ontology error | branch may exist, merge blocked, validation report shown. |
+| Query imported run memory from dispatch | selected content is pinned to memory commit and shown in context preview. |
+
+## Current app seam acceptance
+
+| Area | Acceptance gate |
+| --- | --- |
+| Org navigation | `Agents` appears under existing org navigation and preserves current org switcher behavior. |
+| Agent routes | `/orgs/[org]/agents/*` pages render only with org context and never use a global unscoped agent root as canonical. |
+| Repository integration | existing repo Code, Issues, Pull Requests, Runs, Hooks, and Settings pages link to agent/memory flows with org and repo context. |
+| Resource API | new agent/memory resources can be listed through `/api/orgs/[org]/resources` after resource model support. |
+| Watch API | agent runs and memory imports can stream through org-scoped watch filters without cross-org leakage. |
+| Route guard | run/memory detail pages reject resources whose org label or namespace does not match the route. |
+| Advanced YAML | generated resource YAML includes namespace, org label, and `organizationRef`. |
+
+## Org memory vertical slice acceptance
+
+| Flow | Acceptance gate |
+| --- | --- |
+| Bootstrap | org has namespace binding and memory repo health visible. |
+| Configure | repository settings can attach an `AgentMemorySource`. |
+| Dispatch | manual dispatch creates memory snapshot and context bundle. |
+| Run detail | run shows memory commit, query manifest, selected excerpts, and digests. |
+| Import | summary-only run import creates redacted, validated memory update. |
+| Reuse | later dispatch can query imported run/session summary. |
+| Isolation | another org receives `CROSS_ORG_REF_DENIED` and no memory content. |
+
+## E2E fixture reference
+
+The deterministic fixture set for org memory is defined in [Org memory E2E fixture plan](./org-memory-e2e-fixture-plan.md). Acceptance tests should include duplicate repository slugs across orgs, a seed company brain repo, a redaction-bearing `.a5c` run, manual dispatch with memory, summary-only import, cross-org denial, and historical memory pinning.
+
+## QA matrix reference
+
+Product-wide test coverage expectations live in `docs/tests/product-test-matrix.md`. Agent-specific rows in this matrix should be treated as future required coverage once agent resources, Agent Mux integration, company brain memory, and `.a5c` imports move from docs to implementation.

package/docs/agents/agent-mux-adapter-contract.md

@@ -0,0 +1,167 @@
+# Agent Mux adapter contract spec
+
+## Purpose
+
+Krate should integrate Agent Mux without copying its whole UI or owning adapter internals. This document defines the boundary between Krate controllers and Agent Mux gateway/session/runtime capabilities.
+
+## Ownership split
+
+| Concern | Krate | Agent Mux |
+| --- | --- | --- |
+| Repository graph | source of truth | receives context only |
+| Agent stack policy | source of truth | validates adapter-specific launch options |
+| RBAC/Secret/Config grants | source of truth | receives admitted references only |
+| Runner/workspace policy | source of truth | may use provided cwd/runtime metadata |
+| Session/chat transcript | projection/link | source of truth |
+| Tool/runtime events | normalizes into run events | source of truth |
+| Cancellation/resume/fork/continue | policy gate and audit | execution primitive |
+| Subagents | stack definitions and telemetry projection | native or emulated dispatch mechanism |
+
+## Required client module
+
+Future file:
+
+- `src/agent-mux-client.js`
+
+Responsibilities:
+
+- discover adapter capabilities;
+- validate launch options before dispatch;
+- launch a run/session;
+- bind Agent Mux run/session IDs to `AgentDispatchAttempt`;
+- subscribe to events/transcript updates;
+- submit continuation messages;
+- cancel, retry, resume, or fork where supported;
+- forward approved tool/secret/network decisions;
+- normalize runtime surfaces into Krate event/artifact/workspace projections.
+
+The module should be a thin adapter. It should not contain repository policy, RBAC decisions, trigger matching, or write-back logic.
+
+## Capability handshake
+
+Krate should request capabilities for:
+
+- supported base agents;
+- models/providers;
+- session persistence;
+- structured event stream;
+- continuation/cancel/resume/fork support;
+- approval modes;
+- native tools;
+- MCP support;
+- skill loading;
+- subagent dispatch;
+- workspace/cwd support;
+- transcript export;
+- cost/token reporting.
+
+Capability result should be snapshotted into `AgentStack.status.capabilities` and `AgentDispatchAttempt.spec.agentStackSnapshot`.
+
+## Launch request contract
+
+Krate sends only admitted, redacted launch options:
+
+```json
+{
+  "agent": "claude-code",
+  "adapter": "agent-mux.claude-code",
+  "model": "claude-sonnet-4-5",
+  "approvalMode": "prompt",
+  "prompt": {
+    "system": "...",
+    "developer": "...",
+    "task": "..."
+  },
+  "cwd": "/workspaces/krate-pr-42",
+  "contextBundle": {
+    "digest": "sha256:...",
+    "attachments": []
+  },
+  "tools": [],
+  "mcpServers": [],
+  "skills": [],
+  "subagents": [],
+  "runtimeIdentity": {
+    "serviceAccountRef": "agent-claude-code-ci-repair"
+  },
+  "secretRefs": [
+    {
+      "grant": "claude-code-anthropic-api-key",
+      "secretRef": "krate-secrets/anthropic-provider",
+      "keys": ["api-key"],
+      "mountPolicy": "env"
+    }
+  ],
+  "configRefs": [],
+  "metadata": {
+    "krateDispatchRun": "adr-01hx",
+    "krateAttempt": "ada-01hx-1",
+    "repository": "krate",
+    "sourceRef": "pullrequest/42"
+  }
+}
+```
+
+Secret values are never in the request body unless the Agent Mux deployment mode explicitly requires value materialization inside a trusted server-side process; even then values must not pass through browser/UI APIs.
+
+## Launch response contract
+
+```json
+{
+  "agentMuxRunId": "run_01hx",
+  "agentMuxSessionId": "ses_01hx",
+  "status": "running",
+  "eventCursor": "0000001",
+  "capabilitiesSnapshotDigest": "sha256:..."
+}
+```
+
+Krate persists these IDs in `AgentDispatchAttempt.status` and renders links into run/session pages.
+
+## Event normalization
+
+Agent Mux events should map into Krate event types:
+
+| Agent Mux event | Krate projection |
+| --- | --- |
+| run queued/started | attempt phase, queue timing |
+| session created | `AgentSession` link and `AgentMuxSessionBound=True` |
+| assistant/user message | transcript projection only |
+| tool call started/completed | event timeline and optional `AgentApproval` |
+| subagent started/completed | child subagent lane/event/artifact |
+| file changed/patch produced | `AgentArtifact` |
+| runtime preview/dev server | `AgentWorkspace.status.runtime` |
+| approval requested | `AgentApproval` |
+| cost/tokens | `AgentDispatchRun.status.cost` |
+| terminal result | attempt/run terminal phase |
+
+## Error handling
+
+| Error | Krate behavior |
+| --- | --- |
+| gateway unavailable | keep attempt queued/starting with retry condition. |
+| capability unavailable | stack `CapabilitiesResolved=False`. |
+| launch rejected | fail attempt with adapter rejection and snapshot request digest. |
+| session binding missing | show pending handoff and retry binding. |
+| event stream disconnect | mark stream stale and reconnect from cursor when possible. |
+| unsupported action | disable action based on capability, not UI-only logic. |
+
+## Security requirements
+
+- Agent Mux receives only resources admitted by Krate policy.
+- Krate stores Agent Mux IDs but does not treat Agent Mux storage as repository source of truth.
+- Continuation messages must run permission review if they request new tools, files, secrets, configs, or write-back targets.
+- Agent Mux transcript must not expose Secret values.
+- Agent Mux approval prompts must map back to `AgentApproval` for audit when they affect Krate-owned actions.
+
+## UI embedding
+
+Krate should embed Agent Mux primitives as panels:
+
+- transcript/conversation panel;
+- event/observability timeline;
+- runtime/workspace panel;
+- approval/tool activity panel;
+- subagent tree/lane panel.
+
+Krate navigation, breadcrumbs, permissions, and source-object hierarchy remain native Krate UI.