@kontextmind/kxm 0.7.95 → 0.7.96

package/docs/troubleshooting.md

@@ -1,322 +0,0 @@
-# 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_fanout` wait 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. A hub claim whose wrapper PID is dead is reclaimed automatically on the next `kxm hub start`; the wrapper also terminates an orphaned hub server child recorded by a dead wrapper (for example after `SIGKILL`) before reclaiming, and `kxm hub stop` can stop such an orphan directly. If a pre-0.4.3 process left a malformed claim 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`.
-
-### CI jobs stay queued and never start
-
-Every Linux workflow targets the ARC runner scale-set name `kontextmind-doks`.
-That name is not a custom label for repository runners. The scale set belongs to
-the selected-repository GitHub runner group `KontextMind DOKS ARC`, which must
-allow this public repository. The legacy `km-gh-rn01` runner must not carry the
-`kontextmind-doks` label; adding it bypasses ARC and serializes the build queue.
-
-Check GitHub routing first:
-
-```bash
-gh api repos/kontextmind/kxm/actions/runners \
-  --jq '.runners[] | {name, status, busy, labels: [.labels[].name]}'
-gh api orgs/kontextmind/actions/runner-groups \
-  --jq '.runner_groups[] | select(.name == "KontextMind DOKS ARC") |
-    {name, visibility, allows_public_repositories}'
-```
-
-Then check ARC in DOKS:
-
-```bash
-kubectl -n arc-runners get autoscalingrunnerset kontextmind-doks
-kubectl -n arc-runners get ephemeralrunners,pods
-```
-
-The normal capacity policy keeps one warm runner, bursts to four, and requests
-three CPUs per runner so the DOKS node-pool autoscaler can add capacity instead of
-packing CPU-bound jobs onto already busy nodes. If repository jobs remain queued
-while the listener is assigned zero jobs, verify the runner group's selected
-repository and public-repository access. If ARC has pending pods, inspect node
-capacity and the cluster autoscaler. Do not relabel `km-gh-rn01` or push an
-empty commit as a routing workaround.
-
-### 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.
-
-**`KXM hub env file is malformed`**
-
-The persisted credential file (`hub-env.json` under the user state root) failed
-validation. It holds only `KXM_AUTH_TOKEN` / `KXM_PROJECT_TOKENS` values in
-`kxm.hub-env.v1` schema; fix its JSON or delete it to have kxm generate a
-fresh admin token on the next start. To rotate the generated token, delete
-the file and run `kxm hub start` again.
-
-#### 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`.
-
-### `kxm harness list` says Claude Code is `not_detected` on Windows
-
-npm installs Claude Code as `claude.cmd` (and an extensionless shim), not
-`claude.exe` on `PATH`. The native binary lives next to the shim at
-`%AppData%\Roaming\npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe`.
-Older probes spawned `claude` without a shell, got `ENOENT` or `EINVAL`, and
-reported the CLI missing even when `claude --version` worked in cmd or Git Bash.
-
-Current `kxm harness list` retries `claude.exe`, then that inner package
-`.exe`, then `claude.cmd` on win32. It sets `issues: ["windows_shim"]` only
-when the npm shim is what answered. If the entry is still `not_detected`,
-confirm `%AppData%\Roaming\npm` is on `PATH` for the same process that runs
-`kxm`, then `claude --version` and `claude auth status`. Assignment dispatch
-(`just assign` / `harness-run`) follows the inner `claude.exe` (and Pi's
-`node.exe` plus `cli.js`) with `shell: false`; unverified `.cmd` launchers
-are still refused.
-
-The same npm-shim miss can appear for `pi` on Windows.
-
-### 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#1-install), 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.
-
-For bash and zsh, `kxm completion install` can add the kxm bin directory to
-`PATH` in the shell rc file when it is missing; restart the shell afterwards.
-
-### Tab completion is not active
-
-Run `kxm completion install` for the detected shell, or pass
-`--shell bash|zsh|fish` explicitly. The install appends one guarded stanza to
-the shell rc file and is idempotent: rerunning never duplicates it. Fish needs
-no rc entry because fish auto-loads `~/.config/fish/completions`. After
-installing, start a new terminal or `source` the rc file. To inspect without
-writing, use `--dry-run`; to suppress the post-`kxm init` offer, set
-`KXM_SKIP_COMPLETION_PROMPT=1`.
-
-### 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
-
-`kxm_await` waits at most 60 seconds; that is both its default and its maximum. A timeout does not end the request. Use `kxm_get` to inspect the state, or `kxm_workflow_wait` for long external work. `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/webhook-workflows.md

@@ -1,240 +0,0 @@
-# Webhook workflows and long-lived agents
-
-KXM can turn a signed Jira, GitHub, or generic webhook into a durable prompt for a long-lived coordinator. The hub verifies the original request body, deduplicates provider retries, records the workflow before acknowledging it, and queues the prompt even when a previously registered coordinator is temporarily offline.
-
-## How the runtime behaves
-
-```text
-Jira webhook ── HMAC + delivery ID ──> Hub ── durable workflow + message
-                                             │
-                                             └── Pi coordinator
-                                                   ├── peer planning/review
-                                                   ├── checkpoints and retries
-                                                   ├── evidence journal
-                                                   ├── external wait ── signed result ──┐
-                                                   └── final result <── resumed prompt ─┘
-```
-
-The coordinator must register at least once before a webhook can target it. An unknown target returns HTTP 409, which causes Jira Cloud to retry. A known but offline target retains the queued workflow until it reconnects.
-
-The hub stores a SHA-256 payload hash and the rendered coordinator prompt, not the complete raw webhook body. Keep prompt templates narrow so they copy only the issue fields the agent needs.
-
-## Configure the Jira example
-
-The included [`jira-development.json`](../.kxm/workflows/default.yaml) workspace configuration models this path:
-
-1. Jira issue enters **In Progress**.
-2. Reproduce the defect and create deterministic evidence.
-3. Plan with one agent or three independent strong planners, then synthesize their best ideas.
-4. Review and revise the plan.
-5. Implement with explicit ownership.
-6. Run lint, build/typecheck, security, and Playwright gates.
-7. Reproduce repository and CodeRabbit-style review gates.
-8. Update documentation.
-9. Push and watch required checks with `kxm gate github watch`; warnings and failures retry the same stage for correction until its attempt limit is exhausted.
-10. Merge only when policy and authorization allow it.
-11. Update Jira with links and evidence.
-12. Produce an evidence-backed improvement backlog.
-
-Load it without storing its secret in the JSON file:
-
-```powershell
-$env:JIRA_WEBHOOK_SECRET = "replace-with-a-high-entropy-secret"
-$env:WORKFLOW_SIGNAL_SECRET = "replace-with-a-separate-callback-secret"
-$env:KXM_WEBHOOK_WORKFLOWS_FILE = ".kxm/workflows/default.yaml"
-kxm hub start
-```
-
-Configure Jira to send `jira:issue_updated` to:
-
-```text
-https://your-kxm-host.example/v1/webhooks/jira-development
-```
-
-Set the same secret when creating the Jira webhook. The endpoint requires `X-Hub-Signature` using SHA-256 and `X-Atlassian-Webhook-Identifier`. The stable delivery identifier makes Jira retries idempotent. Terminate TLS and restrict ingress before exposing the endpoint beyond a trusted network.
-
-Webhook authentication authorizes only workflow creation. The Jira-update stage requires a separate authorized Jira tool, MCP server, CLI, or automation callback in the coordinator's harness. Do not place Jira API credentials in the workflow definition or prompt.
-
-## Run a long-lived Pi coordinator
-
-Install the Pi package, then configure a stable identity that matches the workflow target:
-
-```powershell
-$env:KXM_SERVER_URL = "http://127.0.0.1:7331"
-$env:KXM_AUTH_TOKEN = "product-project-token"
-$env:KXM_PROJECT = "product"
-$env:KXM_AGENT_NAME = "coordinator"
-$env:KXM_AGENT_PURPOSE = "Coordinates Jira development workflows and quality gates"
-$env:KXM_WORKDIR = "D:\work\product-repository"
-kxm agent worker --session-isolation workflow
-```
-
-Workflow isolation is explicit during the upgrade-compatible release and begins fresh scoped storage on first use. The worker launches Pi in headless RPC mode, keeps stdin open, preserves its active bound session by default, and restarts with bounded exponential backoff. Run the worker itself under the operating system's service manager for boot startup, resource limits, log collection, and crash policy. Set `KXM_WORKER_CONTINUE=false` only when every process restart should create a fresh Pi session.
-
-## Workflow definition fields
-
-| Field | Meaning |
-|---|---|
-| `id` | URL-safe workflow identifier |
-| `source` | `jira`, `github`, or `generic` |
-| `project` | Hub project containing the coordinator |
-| `target` | Stable coordinator name or durable agent ID |
-| `secretEnv` | Environment variable containing the HMAC secret |
-| `signalSecretEnv` | Optional separate HMAC secret for external result callbacks |
-| `event` | Optional provider event filter |
-| `filter.path` / `filter.equals` | Optional exact JSON-path value filter |
-| `delivery` | `followUp` or `steer` |
-| `ttlMs` | Time allowed for the coordinator prompt |
-| `promptTemplate` | Prompt with `{{nested.payload.path}}` substitutions |
-| `stages` | Ordered gates with instructions, evidence requirements, and attempt limits |
-| `stages[].evidencePolicies` | Optional per-requirement peer provenance and quorum rules |
-
-Each stage may set `area` to route automatic warnings and failures into `harness`, `gates`, `implementation`, `workflow`, `documentation`, `security`, or `other`. It defaults to `workflow`.
-
-An `evidencePolicies` key must match one canonical `requiredEvidence` identity.
-A `peer-reply` policy declares a `minProducers`, one or more
-`eligibleAgents`, and `acceptedStatuses: ["replied"]`. Eligible names or IDs
-must already be known in the workflow project. The hub resolves them to stable
-producer IDs when the run starts and fails closed if the coordinator is
-included or the unique resolved set cannot satisfy the configured minimum.
-See [Peer provenance and quorum gates](provenance-gates.md) for the complete
-schema and command-first example.
-
-Use `KXM_WEBHOOK_WORKFLOWS` for inline JSON or `KXM_WEBHOOK_WORKFLOWS_FILE` for a file, never both. Prefer `secretEnv` over a literal `secret`.
-
-## Pause for CI, review, merge, or Jira
-
-A coordinator should not hold an agent turn open while an external system runs for minutes or hours. On the active stage, call `kxm_workflow_wait` with:
-
-- the run and active stage IDs;
-- a stable `signalKey`, such as `github-pr-42-checks`;
-- a concise description of the expected result;
-- optional local evidence keyed by its declared requirement identity;
-- an optional timeout from one second through 30 days; the default is 24 hours.
-
-The hub changes the run and stage to `waiting`. The coordinator may then settle its current prompt without triggering the premature-settlement failure. If the deadline passes first, the run fails and records a harness error.
-
-The external system reports its result to:
-
-```text
-POST /v1/webhooks/:definitionId/runs/:runId/signals/:signalKey
-```
-
-The JSON body is:
-
-```json
-{
-  "status": "passed",
-  "summary": "All required GitHub checks passed",
-  "evidence": {
-    "github.check:ci": "conclusion:success url:https://github.example/org/repo/actions/runs/123"
-  }
-}
-```
-
-Sign the exact body bytes with SHA-256 HMAC. Supply the signature in `X-Hub-Signature-256` and a stable retry identifier in `X-GitHub-Delivery`, `X-Atlassian-Webhook-Identifier`, or `X-Mesh-Delivery-ID`. Repeating the same delivery ID and body returns minimal receipt metadata instead of checkpointing twice. Reusing a delivery ID for a different signal or body returns HTTP 409.
-
-Use `signalSecretEnv` so CI and merge reporters do not need the secret that creates new workflows. If it is omitted, callbacks fall back to `secretEnv` for compatibility. A valid callback can checkpoint only the named run's current wait and must match its signal key.
-
-Context evidence is optional. When a callback supplies `workflow.run`,
-`workflow.stage`, or `workflow.signal`, each value must exactly match the route
-run, active waiting stage, or route signal key respectively. A mismatch returns
-HTTP 409 without advancing the run or recording a delivery receipt. Adapters
-that do not need these diagnostic keys may omit them.
-
-`passed` applies the normal evidence rule and advances or completes the run. `warning` or `failed` consumes an attempt, records an error, and queues a correction prompt when attempts remain. The run, signal receipt, optional journal entry, and optional resume message commit in one SQLite transaction before delivery. A terminal result does not create another prompt. Only the validated summary and evidence are retained; the complete callback body is not stored.
-
-Callback responses deliberately expose only status, stage, retry, completion, resumption, and duplicate metadata. They never return the workflow record, coordinator prompt, message routing, journal, or evidence. Those remain behind project and agent authentication.
-
-The repository includes a small callback sender for smoke tests and automation adapters:
-
-```powershell
-$env:KXM_SERVER_URL = "https://your-hub-host.example"
-$env:KXM_WORKFLOW_ID = "jira-development"
-$env:KXM_WORKFLOW_SIGNAL_SECRET = "replace-with-the-callback-secret"
-$env:KXM_SIGNAL_DELIVERY_ID = "github-check-run-123-attempt-1"
-node --experimental-strip-types examples/workflow-signal.ts `
-  run_123 github-pr-42-checks passed "All required checks passed" `
-  "github.check:ci=https://github.example/org/repo/actions/runs/123"
-```
-
-`examples/workflow-signal.ts` reads `KXM_SIGNAL_DELIVERY_ID` and sends it as
-`x-kxm-delivery-id`. The CLI equivalent is `kxm gate signal --delivery-id`.
-
-In a real integration, store the `runId` and `signalKey` in Jira, pull-request metadata, or the external job's inputs when the coordinator starts the wait. Treat them as routing identifiers rather than secrets.
-
-To watch GitHub checks and post that same signal, use the command-first adapter:
-
-```powershell
-$env:KXM_WORKFLOW_ID = "jira-development"
-$env:KXM_WORKFLOW_SIGNAL_SECRET = "replace-with-the-callback-secret"
-$env:GITHUB_TOKEN = "replace-with-a-checks-read-token"
-kxm gate github watch --run-id run_123 --stage-id watch --signal-key github-pr-42-checks --repo org/repo --pr 42 --required ci --timeout-ms 3600000
-```
-
-The watcher binds every result to the exact run, stage, and signal key, requests
-up to 100 check runs per GitHub page, and follows every reported page. Each
-check is reported as `github.check:<check-name>`; diagnostic context such as
-`workflow.run` never satisfies an unrelated requirement. GitHub
-`startup_failure` is a failed result. On timeout the watcher posts a signed
-`failed` signal with summary `github_watch_timeout`, then exits `4`; it never
-invents a `passed` result.
-
-Each watcher invocation creates a new bounded delivery generation and includes
-the pull-request head SHA when GitHub returned one. Transport retries within
-that invocation reuse the exact `x-kxm-delivery-id`. After a failed or timed
-out result, start a new watcher for the new workflow wait; do not reuse the old
-generated ID. Supply `--delivery-id` only when an external supervisor must
-retry the same callback attempt with a stable provider identifier. The standalone
-`kxm gate signal` command follows the same rule.
-
-## Checkpoint contract
-
-Only the assigned coordinator can read, journal, checkpoint, or wait a run. A
-passing checkpoint must provide a non-empty value for every exact
-`requiredEvidence` identity. Evidence is a JSON object rather than a list, so
-extra GitHub checks or generic context cannot replace an unrelated review,
-artifact, or retrospective requirement. Identities are normalized by trimming,
-collapsing repeated whitespace, and case-folding; normalized aliases in one
-submission are rejected as duplicates.
-
-When a requirement has a peer policy, caller-authored evidence text cannot
-satisfy it. The coordinator must create peer messages with an authorized,
-immutable `workflowContext` for the exact run, active stage, canonical
-requirement, and current 1-based attempt. A passing checkpoint or wait cites the
-resulting durable message IDs in `evidenceRefs`. The hub verifies project,
-direction, eligible target, context, correlation, non-empty replied status,
-and coherent timestamps, then counts unique producer IDs. Old, pending,
-duplicate-producer, coordinator-authored, or cross-context messages do not
-count.
-
-Evidence supplied when entering `waiting` is accumulated with a later passing
-callback. `warning` and `failed` evidence is retained in the journal for
-diagnosis but intentionally does not satisfy a later passing attempt. Those
-results remain on the active stage and return a correction instruction.
-Reaching `maxAttempts` fails the run. Settling the coordinator prompt before all
-stages pass also fails the run and records a workflow error unless the
-coordinator deliberately placed the active stage in `waiting` first.
-
-If a policy declares `degradation.minProducers`, an operator may use
-`kxm gate degrade` with the administrative token to approve that exact
-lower minimum for only the current stage attempt. The coordinator, peer agents,
-and callback secret cannot authorize degradation. Approval alone never passes
-the stage; the coordinator must still provide the required verified references.
-The reason, policy minimum, approved minimum, attempt, and any eventual degraded
-pass are retained for audit.
-
-The hub enforces stage order and requirement identity; agents remain responsible
-for the truth of submitted evidence. Repository rules, human approvals, and
-harness permissions remain authoritative for push, merge, Jira mutation, and
-other external effects.
-
-Peer quorum proves provenance inside the hub project credential boundary. It
-does not prove answer quality, truth, distinct underlying models, independent
-inference, non-collusion, or human approval.
-
-## Platform references
-
-- [Pi extension lifecycle and message injection](https://pi.dev/docs/latest/extensions)
-- [Pi headless RPC mode](https://pi.dev/docs/latest/rpc)
-- [Jira Cloud webhook signing and retry behavior](https://developer.atlassian.com/cloud/jira/software/webhooks/)