@kontextmind/kxm 0.6.0

package/docs/troubleshooting.md

@@ -0,0 +1,249 @@
+# Troubleshooting
+
+Start with the smallest boundary: hub health, authentication, registration, peer discovery, then message delivery.
+
+## Quick diagnostic sequence
+
+1. Confirm the hub terminal still shows `kxm hub listening`.
+2. Request `/health`, then `/ready` to confirm storage access.
+3. Compare the hub URL, token, and project on both agents.
+4. Confirm every agent has a unique name.
+5. Run `/kxm hub` in Pi or call `kxm_list` in Claude.
+6. Inspect hub logs for registration, stale-agent, or server-error events.
+7. If a workflow tool returns `workflow_forbidden`, read `operation`, `assignedCoordinatorName`, and `nextAction`. Do not retry as a peer.
+
+## Common problems
+
+### A continued Pi session rejects every turn
+
+If a worker was stopped during `kxm_await`, `--continue` may leave a `tool_use` without `tool_result`. The worker retries once without `--continue` and writes a project-and-agent identity-keyed recovery envelope under `.kxm/state`. Do not paste agent logs into the journal. Keep the same project and agent name so the hub identity and recovery key resume.
+
+### A model quota or provider error settles the agent
+
+KXM waits until Pi has exhausted its own automatic retries. It then keeps the inbound message in `delivered` state, records an allowlisted `quota` or `provider_error` diagnostic without the provider body, and restarts the RPC child. Configure `KXM_WORKER_FALLBACK_MODELS` (or `--fallback-models`) to rotate immediately; otherwise the worker retries after `KXM_WORKER_PROVIDER_RETRY_MS`. Keep continuation enabled so finished peer calls and tool results survive the model switch. Use `--fresh-start`, not `--no-continue`, when only the first launch must avoid old session state.
+
+### A worker heartbeat is healthy but one tool never finishes
+
+Set `KXM_WORKER_TOOL_TIMEOUT_MS` above the longest legitimate tool call. Its 31-minute default intentionally gives a 30-minute `kxm_await` or `kxm_fanout` time to return durable pending handles before supervision intervenes. When that bound is exceeded, the structured worker log records `worker_tool_timeout` with only the allowlisted tool name and diagnostic class, the delivered hub request stays recoverable, and the RPC process is restarted. If the stuck worker was supposed to be read-only, also set `KXM_WORKER_TOOLS=read,grep,find,ls`; prompt wording alone does not remove shell or write capabilities.
+
+### A hub or worker PID claim is stale
+
+Version 0.4.3 prevents a second wrapper from replacing a live hub or worker claim. `kxm hub stop` ignores an invalid, non-running, or ownership-mismatched record rather than guessing. If a crash or pre-0.4.3 process left one behind, inspect the exact `.pid` JSON and verify that its recorded PID is no longer running; for a hub, also verify the configured port has no listener. Then remove only that exact `.pid` and its recorded `.stop` control file before relaunching once. Worker filenames include a project/agent identity digest and their records include the exact names and generation, so do not substitute a similarly sanitized filename. Never delete the `.kxm/state` directory or SQLite database to clear a claim.
+
+### GitHub checks passed but the workflow is still waiting
+
+The hub does not poll GitHub. Run `kxm gate github watch` with the same `runId`, `stageId`, and `signalKey`. A watcher timeout posts the exact signed `failed` signal, retains bounded check evidence, and exits `4`; it never invents `passed`.
+
+### The hub refuses to start
+
+**`KXM_PORT must be an integer between 0 and 65535`**
+
+Set `KXM_PORT` to a valid integer. Remove the variable to use `7331`.
+
+**`KXM_AUTH_TOKEN is required when binding beyond localhost`**
+
+Either restore `KXM_HOST=127.0.0.1` or configure a token before using a non-loopback interface.
+
+#### Database schema is newer than this runtime supports
+
+Do not delete or rewrite the database. Start the package version that created it, or upgrade this runtime. Restore the pre-upgrade backup when rolling back.
+
+#### Address already in use
+
+Another process owns the port. Stop that process or choose another port, then update every agent's `KXM_SERVER_URL`.
+
+### Pi shows `hub:off`
+
+- Confirm the hub is reachable from the Pi terminal.
+- Verify `KXM_AUTH_TOKEN` exactly matches the hub token.
+- Check whether a live agent already uses the same name in the same project.
+- Restart Pi after changing environment variables.
+- For an exact development load, use `pi --no-extensions -e ./plugins/kxm/src/extension.ts`. Add every required provider extension with another `-e`; otherwise Pi discovery is intentionally disabled.
+- For long-lived workers, set the reviewed `KXM_WORKER_EXTENSION_PATHS` and `KXM_WORKER_SKILL_PATHS` described in [Configuration](configuration.md#long-lived-worker-settings). Invalid paths fail before supervision instead of entering a restart loop.
+
+### Pi update fails looking for `refs/heads/master`
+
+The KXM default branch is `main`. An older Pi git checkout still tracking
+`master` fails with `couldn't find remote ref refs/heads/master`. Remove the
+package and reinstall with an explicit ref:
+
+```text
+pi remove git:github.com/kontextmind/kxm
+pi install git:github.com/kontextmind/kxm@main
+```
+
+### `kxm --help` prints a former flat command list
+
+If the installed `kxm --help` prints `validate | status | hub | worker | stop | …`
+instead of the current Commander groups, the committed `plugins/kxm/dist/cli.js`
+is stale. Run `npm run build` and commit the generated `dist` so the operator
+CLI matches source.
+
+### `kxm` is not recognized
+
+`pi install git:github.com/kontextmind/kxm@main` installs the Pi extension
+and Agent Skill, not a global operator command. Install the versioned `.tgz`
+release asset through the authenticated `gh release download` flow in
+[Getting started](getting-started.md#install-the-operator-command), or run
+`node scripts/kxm.mjs` from a clone after `npm ci`. `npx kxm` and a
+global `git+https` npm install are not supported installation paths.
+
+### An expected peer is missing
+
+The two agents usually have different `KXM_PROJECT` values or one stopped sending heartbeats. Compare settings and check for an `agent_stale` event. Names and projects are case-sensitive for display; live-name uniqueness is case-insensitive.
+
+### A request stays `queued`
+
+The recipient registered but has no active SSE stream. Confirm its process is running and connected. Proxies must disable response buffering for `/v1/events` and allow long-lived connections.
+
+### A request stays `delivered`
+
+The recipient acknowledged it but has not replied. It may still be working, waiting for approval, or blocked. Avoid sending the same request repeatedly. Check the recipient session directly if the wait is unexpected.
+
+If the work is obsolete, the sender can call `kxm_cancel`. This changes hub state only; it cannot reverse file changes or external effects already performed by the peer.
+
+### `kxm_await` times out
+
+The default timeout is 30 minutes. Use `kxm_get` to inspect the state. `cancelled`, `expired`, and `error` are terminal outcomes. Resend only when the task is safe to repeat, and use an idempotency key when retrying after an uncertain network result.
+
+### A message disappears after completion
+
+Terminal records are removed after seven days by default. Increase `KXM_MESSAGE_RETENTION_MS` if operators need a longer diagnostic window. Durable artifacts should live in Git or another system of record.
+
+### Claude tools do not appear
+
+1. Confirm the marketplace and plugin are installed.
+2. Run `/reload-plugins` or restart Claude Code.
+3. Inspect `/mcp` and verify the `kxm` server connected.
+4. Confirm Node.js 22.19 or newer on the 22.x line, or Node.js 24 or newer, is on the `PATH` used by Claude Code.
+5. Reinstall or update the marketplace if the cached plugin predates the `dist/mcp-server.js` bundle.
+
+### Claude does not receive pushed requests
+
+Ordinary MCP tools and channel delivery are separate. During the research preview, start the community channel explicitly:
+
+```text
+claude --dangerously-load-development-channels plugin:kxm@kxm
+```
+
+Accept the trust prompt and check the channel startup notice. Organization policy can still block channels. If pushed delivery remains unavailable, use `kxm_inbox` and `kxm_reply`.
+
+### Jira webhook is rejected
+
+- HTTP 401 means the SHA-256 signature is missing, uses another algorithm, or does not match the raw UTF-8 body. Confirm Jira and `secretEnv` resolve the same secret.
+- HTTP 400 usually means the delivery identifier or JSON body is missing.
+- HTTP 409 means the configured coordinator has never registered. Start it once with the matching project and name; Jira retries 409 responses.
+- HTTP 204 means the event or JSON-path filter did not match, so no workflow was intended.
+- HTTP 200 with `duplicate: true` means a provider retry was safely deduplicated.
+
+### Long-lived worker keeps restarting
+
+Inspect the structured `worker_process_error` and `worker_exited` events. Confirm Pi is installed on the service account's `PATH`, the working directory exists, model credentials are available, the package is enabled, and non-interactive project trust was configured intentionally. Set `KXM_PI_COMMAND` to an explicit executable path when service-manager environments have a reduced `PATH`.
+
+### A workflow message stays queued while the worker restarts once
+
+This is normally the safe session-routing handshake. With `--session-isolation workflow`, a message for a different run is deliberately not acknowledged in the current Pi context. Look for `worker_session_routed`; the old child must close before one replacement starts with the run-specific `--session-dir`, after which the same message ID replays and advances to `delivered`.
+
+If it repeats, inspect `worker_session_request_rejected` and verify:
+
+- the worker was started through `kxm agent worker` with a valid state directory;
+- `KXM_WORKER_SESSION_SCOPE` was not manually set (the supervisor owns it);
+- the state directory is writable by only the service account;
+- the hub and worker are from the same release; and
+- the message has a canonical hub-owned `workflowRunId`, not only a correlation ID.
+
+Do not manually acknowledge the message, edit the route request, copy a run JSONL into `default`, or launch a second worker with the same identity. Those actions defeat context isolation.
+
+### `worker_session_state_recovered` appears
+
+The binding manifest did not match its bounded schema or exact worker owner. The supervisor renamed it to `worker-session-binding-<workerKey>.json.corrupt-<timestamp>` and started the stable default binding rather than guessing a workflow. Read `kxm_workflow_get` for unfinished stages and inspect queued/delivered message IDs. Preserve the quarantined manifest for diagnosis, then re-drive unfinished work from the hub. Repeated corruption suggests disk, antivirus, concurrent-service, or permission problems; confirm only one supervisor owns the exact project/agent PID claim.
+
+### A workflow seems to remember another run
+
+Confirm the worker log says `"sessionIsolation":"workflow"` and the Pi child has a `runs/<exact-runId>` session directory. Isolation is opt-in for upgrade compatibility, and both the CLI and raw supervisor default to `off`. Restart cleanly with `kxm agent worker ... --session-isolation workflow`. The first isolated start intentionally uses fresh scoped storage because KXM cannot safely infer which session in the former shared Pi directory belonged to this worker. Existing content created in a formerly shared Pi session cannot be automatically separated retroactively; treat authoritative workflow journal/assets as the recovery source and start a fresh run-specific history.
+
+### Fanout returns pending before a model replies
+
+`kxm_fanout.timeoutMs` is a local wait, not the message lifetime. A pending result includes the durable `messageId`, current message status, expiry, and whether the wait timed out or was aborted. Use `kxm_get` to inspect that ID, or repeat the exact fanout with the same correlation ID, idempotency prefix, targets, and content. Do not send a replacement with a new prefix while the original remains pending. Normally omit `ttlMs` for model work so time spent queued behind another request does not prematurely expire it. A pending peer has not contributed review or planning evidence and must not be counted toward a workflow checkpoint.
+
+### Workflow cannot advance
+
+Call `kxm_workflow_get` and use only `currentStage`. A passing checkpoint needs
+a keyed, non-empty value for every declared `requiredEvidence` identity; extra
+or unrelated keys do not count. Warnings and failures remain active until
+corrected, and their evidence is journaled but does not satisfy a later passing
+attempt. If attempts are exhausted or the coordinator settles early, the run
+becomes failed and its journal records the reason; start a new provider delivery
+only after deciding whether repeating external effects is safe.
+
+For a requirement with `kind: peer-reply`, inspect
+`resolvedEvidencePolicies`, `verifiedEvidence`, and the current attempt. An
+ordinary evidence string cannot satisfy it. Every eligible agent must have
+registered in the workflow project before the run starts, and a passing
+checkpoint must cite durable replied message IDs in `evidenceRefs` before those
+source messages reach terminal retention.
+
+Common provenance failures are:
+
+- `workflow_context_forbidden`: the sender is not the run's assigned coordinator;
+- `workflow_context_inactive`: the run or stage is not currently running;
+- `workflow_context_attempt_mismatch`: use `stage.attempts + 1` and send fresh work after a retry;
+- `workflow_evidence_producer_forbidden`: the target is not in the run's snapshotted eligible set;
+- `workflow_evidence_policy_missing` or `workflow_evidence_policy_unresolved`: the requirement has no usable resolved peer policy;
+- `workflow_provenance_invalid`: a cited message is missing, pending, ineligible, wrong-direction, or bound to another project, run, stage, requirement, or attempt;
+- `workflow_evidence_incomplete`: there are fewer unique verified producers than the effective minimum.
+
+Multiple replied messages from one peer count once. Correlation IDs and
+idempotency prefixes are retry controls, not provenance. Do not replace a
+rejected reference with an unscoped send.
+
+If policy declares a lower `degradation.minProducers`, an operator can inspect
+and approve it with `kxm gate --dry-run --json degrade ...` followed by
+the same command without `--dry-run`, using the administrative token. Approval
+must target the current stage and attempt and does not advance the workflow;
+the coordinator must still checkpoint with enough verified references. A
+callback, project token, or peer cannot approve degradation.
+
+### `kxm gate degrade` returns HTTP 503 `admin_auth_not_configured`
+
+The hub started without a non-empty `KXM_AUTH_TOKEN`, so no administrative
+credential exists for the degradation route. Project tokens deliberately cannot
+substitute for it, even when the operator holds every project credential. The
+route fails closed and does not create an approval.
+
+Stop the hub gracefully, set a new high-entropy `KXM_AUTH_TOKEN` in the hub
+service, retain the explicit `KXM_PROJECT_TOKENS` mapping for workers, and
+restart against the same `.kxm/state/kxm.db`. Give the administrative token
+only to the operator terminal, never to agents or callbacks. Read the run again
+because the current attempt may have changed, run the exact degradation command
+with `--dry-run --json`, and then approve the current stage, requirement, and
+attempt without `--dry-run`. A restart does not make an earlier-attempt approval
+valid for the new attempt.
+
+### External workflow callback is rejected or does not resume
+
+- HTTP 401 means the callback signature does not match the exact raw body. Use `signalSecretEnv` when configured; the workflow-start secret will not work in that case.
+- HTTP 404 means the workflow definition or run ID does not match this hub.
+- HTTP 409 with `workflow_not_waiting` means the coordinator did not successfully call `kxm_workflow_wait`, the deadline already failed the run, or a prior signal advanced it.
+- HTTP 409 with `workflow_signal_mismatch` means the URL's signal key differs from the active wait. Read the run and use its exact `waiting.signalKey`.
+- HTTP 409 with `workflow_signal_context_mismatch` means a supplied `workflow.run`, `workflow.stage`, or `workflow.signal` evidence value disagrees with the route or active wait. Correct it or omit optional context evidence.
+- HTTP 400 with `workflow_evidence_incomplete` means a passing callback omitted one or more named requirements. Read `missingRequirements`; extra checks and context fields cannot substitute for them.
+- HTTP 400 with `invalid_workflow_evidence` means evidence was not a keyed string object or contained duplicate keys after case/whitespace normalization.
+- HTTP 200 with `duplicate: true` is expected after retrying the same provider delivery ID. Do not generate a new ID for the same callback attempt.
+- A failed or timed-out callback consumes that wait attempt. Re-enter the wait and start a new `github watch` or `signal` command so its default delivery generation is new; reserve an explicit `--delivery-id` for retries of one unchanged callback body.
+
+Inspect `workflow_wait_started`, `workflow_signal_received`, and `workflow_wait_timed_out` logs without copying secrets or full callback bodies. If a run timed out, review whether the external action completed before starting a replacement workflow.
+
+## Collecting a useful bug report
+
+Include:
+
+- operating system and Node.js version;
+- Pi or Claude Code version;
+- package version or Git commit;
+- whether the hub is local or behind a proxy;
+- redacted environment values, excluding the token;
+- the relevant structured hub events;
+- exact reproduction steps and expected behavior.
+
+Never attach authentication tokens, private prompts, credentials, or unrelated repository contents.

package/docs/vnext/README.md

@@ -0,0 +1,62 @@
+# KXM vNext contract package
+
+> **Status: planned normative contract.** This directory describes the target
+> architecture accepted for KXM vNext. Not all commands are implemented.
+> Phase 1 (init/migrate/trust) and Phase 2 (Runtime create/recover) have landed
+> slices. Phase 3 has D3 S1–S4 and D4 U2a-2 implemented (unreleased); it is not
+> only an agent-only simulated loop, and the default/fix driver gate remains
+> open. Operator tracking for the KXM rename, `kxm dash`, hub CLI, and
+> harness YAML lives in the
+> [implementation plan](../../plans/implementation-plan.md#tracking-working-tree-not-a-release).
+> For current hub execution behavior, use [Architecture](../architecture.md) and
+> [Configuration](../configuration.md).
+
+KXM vNext is a convention-over-configuration, local-first orchestration and
+context platform. One local Runtime owns execution; an optional multi-project
+hub coordinates requests, synchronized facts, and aggregate views.
+
+The words **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are normative.
+
+## Package contents
+
+| Contract | Purpose |
+|---|---|
+| [Architecture decision](architecture.md) | Authority, component boundaries, locality, and rejected alternatives |
+| [Terminology](terminology.md) | Canonical names and identity hierarchy |
+| [Lifecycles](lifecycles.md) | Run, step, assignment, attempt, effect, delivery, and synchronization states |
+| [Effects and recovery](effects-and-recovery.md) | Retry, reconciliation, reattachment, and `blocked_uncertain` rules |
+| [Synchronization](synchronization.md) | Sync-safe allowlist and pre-outbox redaction (Phase 8 implementation) |
+| [Routing](routing.md) | Shipped v1 parser/report vs helper telemetry vs planned v2/catalog |
+| [Validation](validation.md) | Parse, schema, reference, semantic, permission, and snapshot validation |
+| [Migration](migration.md) | Compatibility from the current environment/JSON/SQLite surfaces |
+| [Implementation plan](../../plans/implementation-plan.md) | Ordered implementation and release gates |
+| [Examples](../../examples/vnext/README.md) | Complete project and workflow fixture |
+
+Machine-readable schemas live under [`schemas/vnext`](../../schemas/vnext).
+JSON Schema validates the data model after a YAML document has been parsed with
+custom tags disabled and bounded aliases, depth, scalar size, and document size.
+
+## Non-negotiable invariants
+
+1. A project has exactly one authoritative Git-tracked project root.
+2. A run has one immutable `homeRuntimeId`.
+3. A run pins exact configuration, memory, model, and repository revisions.
+4. Hub unavailability does not prevent local or uniquely namespaced work.
+5. Shared mutable actions require an online lease.
+6. An `assignmentId` identifies logical work; an `attemptId` identifies one execution.
+7. Unknown side effects are never replayed automatically.
+8. Agent session history never crosses runs or a narrowing disclosure scope.
+9. Provider credentials and repository contents remain Runtime-local by default.
+10. Only schema-allowlisted, pre-redacted events enter the hub outbox.
+11. Memory and learned content cannot grant tools, secrets, approvals, or policy.
+12. Learned executable behavior activates only through a reviewed Git change.
+
+## Compatibility rule
+
+The current v0.5 contracts remain authoritative until a release explicitly
+activates a vNext schema. Implementations MUST NOT infer vNext behavior merely
+because these documents or examples are present.
+
+Every persisted vNext resource carries an exact schema identity. Additive
+changes require a new compatible schema revision; a semantic breaking change
+requires a new major schema identity and an explicit migration.

package/docs/vnext/architecture.md

@@ -0,0 +1,185 @@
+# ADR-001: Local Runtime, project authority, and aggregate hub
+
+- **Status:** accepted target
+- **Scope:** KXM vNext
+- **Supersedes:** no current contract until migration activation
+
+## Context
+
+The current implementation combines durable peer transport, workflow state,
+and context in one hub-oriented process. KXM vNext must support multiple
+projects and repositories while continuing useful work when a shared hub is
+unavailable. It must also prevent a hub, model, or learned record from silently
+becoming an execution or policy authority.
+
+## Decision
+
+One auto-started **KXM Runtime** per OS user and machine owns execution. A
+Runtime may host many trusted local projects. The optional **KXM hub** accepts
+run requests, coordinates shared-operation leases, synchronizes safe events and
+promoted factual memory, and powers aggregate views. The hub does not execute
+agents and does not receive provider credentials or repository files.
+
+```text
+Git-tracked project root                 machine-local authority
+┌─────────────────────────┐             ┌─────────────────────────┐
+│ .kxm/project.yaml       │             │ KXM Runtime             │
+│ .kxm/agents/*.yaml      │──snapshot──▶│ workflow engine         │
+│ .kxm/models/*.yaml      │             │ Pi/SSH executors        │
+│ .kxm/workflows/*.yaml   │             │ worktrees + secrets     │
+│ project/repo skills, KB │             │ per-project event stores│
+└─────────────────────────┘             └───────────┬─────────────┘
+                                                    │ sync-safe events
+                                                    ▼
+                                         ┌─────────────────────────┐
+                                         │ multi-project hub       │
+                                         │ requests, leases, memory│
+                                         │ aggregate read models   │
+                                         └─────────────────────────┘
+```
+
+## Authority matrix
+
+| Subject | Authority | Replicas or projections |
+|---|---|---|
+| Executable project behavior | Reviewed Git project root | Runtime configuration snapshot; hub immutable snapshot |
+| Repository input | Base commit plus content snapshot hash | Worktree; optional executor bundle |
+| Run execution | Immutable home Runtime event log | Hub synchronized event log and read models |
+| Harness/model capability | Runtime inventory | Bounded hub capability advertisement |
+| Provider credentials | Harness or host secret store | Resolution status only |
+| Secret values | Host secret store | Never replicated |
+| Current factual project state | Promoted temporal state | Pinned local replica by memory revision |
+| Learned executable guidance | Reviewed Git skill/configuration | Runtime snapshot; hub metadata |
+| Human-readable dashboard state | Projection | Rebuildable from events and snapshots |
+
+A projection is never an authority merely because it is easier to query.
+
+## Project and repository boundary
+
+A project MUST have exactly one control Git root containing `.kxm/project.yaml`.
+A project MAY bind multiple member repositories. Logical repository IDs and
+portable remote identities are Git-tracked; absolute machine paths are
+Runtime-local bindings.
+
+Project resources and member-repository resources have explicit path scope.
+When the control root is also a member repository, project and repository
+resources still occupy different directories.
+
+## Run ownership
+
+A run is created only after one Runtime accepts it. The accepted run records an
+immutable `homeRuntimeId`. A hub request is not itself a run and cannot append
+home-owned run events.
+
+A run pins:
+
+- project and workflow identity;
+- configuration revision;
+- promoted memory revision;
+- exact model selections before their first dispatch;
+- repository base commits and dirty snapshot hashes;
+- executor and tool-policy revisions.
+
+An offline-created run receives the same globally unique identity and ownership
+fields as an online-created run. Offline runs may read their pinned memory
+revision and create candidates, but MUST NOT promote hub memory.
+
+## Workflow execution
+
+Top-level workflow steps are ordered. Transitions are typed, declared, and
+bounded. Dynamic assignments exist only inside the active step and cannot
+expand its agent, model, repository, tool, secret, time, cost, or parallelism
+ceilings.
+
+One isolated coordinator Pi session is created per run. Agent sessions are
+identified by `{runId, agentId, instanceNo, scopeEpoch}` and are never reused
+across runs. A narrowing or incompatible repository, secret, tool, model,
+executor, or disclosure scope increments `scopeEpoch` and starts a clean
+physical session.
+
+## Offline operation classes
+
+| Class | Offline behavior | Examples |
+|---|---|---|
+| Local | Allowed | Planning, worktree edits, tests, local commits, candidates |
+| Uniquely namespaced external | Allowed with deterministic key and receipt | Unique run branch, run artifact |
+| Shared mutable | Requires online hub lease | Merge, deploy, shared tag, promotion, shared issue state |
+
+The Runtime classifies the operation. A coordinator or model cannot downgrade
+an operation to avoid a lease.
+
+## Storage topology
+
+Each project has a local event store owned by its home Runtime. The Runtime has
+a separate registry for host bindings, capabilities, enrollment, and process
+state. The hub stores a registry plus isolated project stores. Raw logs,
+repository contents, full prompts, full results, and secret values remain local
+unless a reviewed policy explicitly transfers them.
+
+## Interface strategy
+
+The CLI, standard TUI, Pi extension, and future web dashboard use the same
+Runtime/hub command and read-model APIs. The TUI is first; the web dashboard is
+not a separate workflow implementation.
+
+The primary user path is:
+
+```text
+kxm init
+kxm run <workflow> [prompt]
+```
+
+The Runtime auto-starts when needed. Normal projects rely on built-in
+environment, harness, executor, retention, and synchronization defaults.
+
+## Security scope
+
+The first release is trusted-local: logical project isolation, scoped tools,
+isolated worktrees, explicit secret grants, protected local state, and audited
+permission changes. It is not a sandbox against a hostile process running as
+the same OS user. Container/OS isolation and hostile multi-tenant operation are
+later phases.
+
+## Consequences
+
+Benefits:
+
+- local work survives hub outages;
+- one hub can aggregate many projects without receiving repositories or provider credentials;
+- Git review remains the activation boundary;
+- recovery decisions are made where process and filesystem evidence exists;
+- TUI and web interfaces share durable contracts.
+
+Costs:
+
+- events, projections, and synchronization require explicit versioning;
+- shared external actions need leases and receipts;
+- local bindings and Git configuration must be reconciled;
+- run takeover cannot be added safely without an explicit fencing protocol.
+
+## Rejected alternatives
+
+### Hub-owned execution
+
+Rejected because a hub outage would stop local work and would centralize
+repository and provider credential access.
+
+### Git as the run event log
+
+Rejected because high-frequency lifecycle events, locks, and crash recovery are
+poor Git workloads. Git remains authoritative for reviewed behavior.
+
+### Mutable active-run configuration
+
+Rejected because it destroys reproducibility and can expand permissions during
+execution. Configuration edits affect future runs.
+
+### Automatic learned-policy activation
+
+Rejected because evidence and summaries cannot grant authority. Activation is
+a reviewed Git change.
+
+### Blind retry after a lost process
+
+Rejected because at-least-once replay can duplicate irreversible effects.
+Unknown outcomes enter `blocked_uncertain`.

package/docs/vnext/effects-and-recovery.md

@@ -0,0 +1,172 @@
+# Effects, idempotency, and recovery
+
+KXM provides at-least-once command delivery with effect-aware recovery. It does
+not claim exactly-once external execution.
+
+## Effect declaration
+
+Every Runtime-managed tool or adapter declares an effect class in a trusted,
+versioned adapter/tool-preset registry. A workflow references the adapter or
+preset; it does not declare its own effective class. Model output and workflow
+YAML cannot downgrade the registry classification.
+
+A resolved policy stored in an event or delivery manifest has this shape:
+
+```yaml
+effect:
+  class: external-idempotent
+  idempotencyKey: assignment
+  receiptQuery: github-pull-request-by-head
+  sharedMutable: false
+```
+
+Unknown tools and arbitrary shell commands default to `unknown`. A wrapper may
+provide a stronger declaration only when it owns both dispatch and deterministic
+reconciliation. Registry changes are reviewed permission changes and receive a
+pinned `toolPolicyRevision` or `executorPolicyRevision`.
+
+## Classes and automatic behavior
+
+| Class | Examples | Recovery |
+|---|---|---|
+| `read-only` | Read file, Git status, query API | Retry with bounded policy |
+| `workspace-mutation` | Edit isolated worktree, formatter, generated fixture | Inspect and reconcile workspace; do not blindly reapply |
+| `external-idempotent` | Put by stable key, push exact commit to unique ref | Query stable key/ref; retry only after confirmed absence |
+| `receipt-queryable` | PR by unique head branch, named CI job | Query external system; record found receipt or execute after confirmed absence |
+| `unknown` | Arbitrary shell/API/deploy script | Enter `blocked_uncertain` after a lost acknowledgement |
+| `external-non-idempotent` | Unkeyed payment, irreversible deployment | Enter `blocked_uncertain`; require evidence or human resolution |
+
+A local filesystem mutation outside the assigned isolated workspace is
+`unknown`, even if the command was expected to edit a file.
+
+## Dispatch fence
+
+The Runtime uses this order:
+
+1. Resolve and validate effective permissions.
+2. Allocate `assignmentId`, `attemptId`, and effect ID.
+3. Compute any deterministic idempotency key.
+4. Append the dispatch-intent event.
+5. Commit the event transaction.
+6. Start the process or external call.
+7. Observe completion.
+8. Append the result and receipt.
+9. Advance the assignment/step only after the result transaction commits.
+
+Crashing before step 6 is safe to restart. Crashing between steps 6 and 8 is
+handled according to effect class.
+
+## Crash matrix
+
+| Last durable evidence | Recovery decision |
+|---|---|
+| Intent recorded; process provably never started | Start same planned attempt or mint a new attempt according to executor contract |
+| Exact process/session still alive | Reattach same attempt from its cursor |
+| Process ended; workspace state inspectable | Reconcile expected filesystem/Git postcondition |
+| Stable external receipt found | Record receipt; do not repeat action |
+| Receipt query proves absence | Retry using the same deterministic key where supported |
+| Query unavailable, ambiguous, or non-authoritative | `blocked_uncertain` |
+| Replacement process already exists | Do not reattach old attempt; reconcile or block |
+
+Provider inference is not evidence that a tool effect did or did not happen.
+
+## `blocked_uncertain`
+
+The state records:
+
+- run, step, assignment, attempt, and effect identities;
+- effect classification;
+- last durable transition and cursor;
+- expected postcondition and receipt query;
+- reconciliation attempts and bounded diagnostics;
+- permitted resolution actions.
+
+Automatic execution stops only where dependent work could compound the unknown
+effect. Independent read-only inspection MAY continue in a separate assignment
+if the workflow permits it.
+
+Resolution options:
+
+| Resolution | Required evidence |
+|---|---|
+| Mark completed | Authoritative receipt or verified postcondition |
+| Confirm absent and retry | Authoritative negative query plus new `attemptId` when a process is restarted |
+| Compensate then retry | Compensation receipt and workflow-authorized new attempt |
+| Mark failed | Audited deterministic or human decision |
+| Cancel | Proof no unresolved owned effect remains, otherwise uncertainty remains visible |
+
+A human resolution is an audited control-plane action, not retroactive proof.
+The event records actor, reason, supplied references, and resulting action.
+
+## Workspace reconciliation
+
+For isolated workspaces, recovery compares:
+
+- pinned baseline snapshot;
+- current manifest and Git index/worktree state;
+- expected changed paths or postcondition;
+- child process identity and open file/process handles where available;
+- produced artifacts and hashes.
+
+KXM applies no patch a second time merely because the prior tool result is
+missing. If intent cannot be compared deterministically with state, the effect
+is uncertain.
+
+## Git operations
+
+Safe conventions:
+
+- commits include run/assignment provenance in metadata or notes;
+- run branches are globally unique;
+- pushes target an exact expected object ID;
+- receipt queries compare the remote ref to the expected object ID;
+- shared branches, tags, merges, and releases require an online lease;
+- a force update is never inferred safe from branch uniqueness.
+
+Creating a pull request is queryable only when the adapter uses a deterministic
+head branch and can authoritatively find an existing matching request.
+
+## Remote execution
+
+The SSH helper reports a helper generation, process identity, attempt identity,
+and monotonic event cursor. Connection loss alone does not create a new attempt.
+
+Reattach only when the same remote helper and process can prove continuity. If
+the remote host or helper has been recreated, reconcile workspace and external
+receipts before starting a new attempt. An absent remote process does not prove
+that an external side effect failed.
+
+## Cancellation
+
+Cancellation is a request followed by supervised settlement:
+
+1. append cancellation intent;
+2. stop new dispatches;
+3. request graceful child cancellation;
+4. wait a bounded drain interval;
+5. terminate the owned process group where safe;
+6. reconcile in-flight effects;
+7. mark cancelled only when no unresolved effect remains.
+
+A run with an unresolved effect remains `blocked_uncertain` rather than being
+made cosmetically cancelled.
+
+## Lease failure
+
+A shared mutable operation records lease identity and fencing token with its
+dispatch intent. If the lease expires before dispatch, the operation is not
+started. If it expires after dispatch, recovery queries the receipt; KXM never
+assumes expiry rolled the external action back.
+
+## User interface
+
+The TUI and Pi menu show uncertainty as an attention state with:
+
+- last known operation;
+- why automatic recovery is unsafe;
+- available reconciliation adapter;
+- supplied receipts;
+- actions requiring human authorization.
+
+Normal read, workspace, and queryable operations recover automatically. Manual
+intervention is reserved for genuinely unprovable effects.