---
source-of-truth: true
owner: API Governance Lead
last-verified: 2026-05-30
doc-type: architecture
---

# DashClaw Project Details (Governance Runtime)

DashClaw is decision infrastructure for AI agents. It provides the governance layer between agents and external systems: policy evaluation before execution, human approval when needed, durable action records, terminal outcome tracking, and evidence that operators can audit later.

DashClaw is not an agent framework and not an observability-only product. It does not try to help agents do work. It governs work that agents are about to do or claim they completed.

## What this file is authoritative for

This file is the source of truth for DashClaw's product boundary, runtime architecture, primary surfaces, and integration model.

Generated inventories remain authoritative for generated facts:

| Fact | Source |
|:---|:---|
| Complete API route inventory | `docs/api-inventory.md` and `docs/api-inventory.json` generated from `app/api/**/route.js` |
| Stable OpenAPI contract | `docs/openapi/critical-stable.openapi.json` generated by `npm run openapi:generate` |
| Livingcode codebase snapshot | `public/livingcode/` generated by `npm run livingcode:refresh` |
| SDK parity by domain | `docs/sdk-parity.md` |
| Durable execution finality spec | `docs/architecture/durable-execution-finality.md` |

As of this verification, generated API inventory reports **259 routes**: **46 stable**, **24 beta**, **189 experimental**.

## Product boundary

### DashClaw owns

- **Attribution**: which agent attempted which action, with `agent_id`, optional `agent_name`, and org scoping.
- **Policy decisions**: allow, block, or require approval before an action proceeds.
- **Human-in-the-loop approval**: approval queues and chat/native approval bridges.
- **Action ledger**: durable `action_records` rows with status, risk, reasoning, assumptions, costs, tokens, and trace data.
- **Terminal outcomes**: one-shot action outcome finality through `GET/POST /api/actions/:actionId/outcome`.
- **Operational signals**: stale actions, drift, lost confirmations, degraded integrations, and policy-relevant alerts.
- **Evidence**: replayable action detail, traces, graphs, artifacts, and evidence bundles.

### DashClaw does not own

- Agent planning or task execution.
- Wallets, chain anchoring, or on-chain proof systems.
- Tool/provider-specific business logic.
- Cross-project canonical key standards, except as caller-supplied fields that DashClaw can store and enforce, such as `idempotency_key`.

## Primary UI surfaces

| Surface | Path | Purpose |
|:---|:---|:---|
| Mission Control | `/mission-control` | Strategic posture, interventions, live decision stream, runtime summary, and operations feed. |
| Decisions | `/decisions` | Visual ledger of governed actions with outcome status and replay links. |
| Replay | `/replay/[actionId]` | Action-level evidence view for a single governed decision. |
| Setup | `/setup` | Readiness verification, instance health, setup proof, and migration helper entry points. |
| Connect | `/connect` | Path to first governed action, including hosted trial provisioning when `DASHCLAW_HOSTED=true`. |
| Agent Profiles | `/agents/[agentId]` | Governance-focused agent profile with trust posture, decision history, assumptions, signals, and policies. |
| Policy Builder | `/policies` | Policy management, policy generation, simulation, import/proof surfaces, and guard activity. |
| Analytics | `/analytics` | Cost trends, action volume, agent/type breakdowns, policy enforcement stats, and token efficiency. |
| Workflows | `/workflows` | Workflow template management and governed workflow execution surfaces. |
| Capabilities | `/capabilities` | Governed HTTP capability registry, health, access rules, testing, and invocation. |
| Knowledge | `/knowledge` | Knowledge collection metadata, ingestion, chunking, embedding, sync, and search surfaces. |
| Model Strategies | `/model-strategies` | BYOK model/provider strategy configuration, fallback chains, and budget controls. |
| Livingcode Dashboard | `/livingcode/` | Static snapshot of routes, env vars, tables, adapters, events, signals, setting keys, health strip, history, and diffs. Regenerated by `npm run livingcode:refresh`. |

## Runtime architecture

DashClaw is organized into three layers to keep the governance boundary clear.

### Tier 1: Core governance runtime

These routes define the minimum DashClaw category. They are stable or runtime-critical and should remain small, well-documented, and backward compatible.

| Route | Purpose | Notes |
|:---|:---|:---|
| `/api/guard` | Policy evaluation before execution | Returns allow, block, or require approval. |
| `/api/actions` | Create, list, and delete action records | `POST` accepts `idempotency_key`; duplicate `(org_id, idempotency_key)` creates return the existing row with `idempotent_replay: true`. |
| `/api/actions/:actionId` | Read or PATCH legacy lifecycle outcome fields | Legacy completion/update path. Durable finality uses the separate `/outcome` route. |
| `/api/actions/:actionId/outcome` | Durable terminal outcome | One-shot `pending -> completed/partial/failed`; `lost_confirmation` is system-owned. |
| `/api/actions/:actionId/trace` | Action trace | Read-only evidence path. |
| `/api/actions/:actionId/graph` | Execution graph | Nodes and edges around an action, assumptions, loops, and trace data. |
| `/api/approvals/:actionId` | Human approval decision | Also reachable via legacy rewrite `/api/actions/:id/approve`. |
| `/api/assumptions` | Reasoning integrity records | Assumption tracking linked to actions. |
| `/api/signals` | Runtime/anomaly signals | Signal listing and detection outputs. |
| `/api/policies` | Policy CRUD | Guard policy management. |
| `/api/policies/generate` | Natural-language policy generator | Supports dry-run preview. |
| `/api/health` | System readiness | Public health/readiness surface. |
| `/api/keys` | API key management | Stable key lifecycle and reveal path. |
| `/api/messages` | Agent/system messages | Stable messaging surface used by agent coordination paths. |
| `/api/mcp` | Streamable HTTP MCP endpoint | Remote MCP transport for DashClaw tool calls and resources. |

Route aliases in `next.config.js` preserve legacy paths such as `/api/actions/signals`, `/api/actions/assumptions`, and `/api/actions/:id/approve`. New integrations should prefer the canonical routes above.

### Tier 2: Governance extensions

These modules consume core runtime data and add operator value without changing the category boundary.

| Domain | Representative routes or surfaces | Purpose |
|:---|:---|:---|
| Workflows | `/api/workflows/templates/*` | Governed reusable workflow templates, launch, execute, runs, resume, and cancel. |
| Capabilities | `/api/capabilities/*` | Governed HTTP capability registry, access rules, health, test, and invoke. |
| Knowledge | `/api/knowledge/collections/*` | Collection metadata, item ingestion, embedding, sync, and semantic search. |
| Model strategies | `/api/model-strategies/*` | Provider/model routing, fallback chains, BYOK credentials, budgets, and completions. |
| Artifacts | `/api/artifacts/*` | Durable artifacts linked to actions and workflow steps, plus evidence bundles. |
| Operations | `/api/operations/feed`, `/api/operations/summary` | Mission Control operational feed and runtime metrics. |
| Compliance | `/api/compliance/*` | Evidence, mappings, gaps, reports, schedules, and exports. |
| Evaluations | `/api/evaluations/*` | Scorers, runs, stats, and evaluation outputs. |
| Scoring | `/api/scoring/*` | Risk profiles, dimensions, templates, calibration, and scoring. |
| Learning | `/api/learning/*` | Lessons, analytics, recommendations, maturity, and velocity. |
| Drift | `/api/drift/*` | Drift metrics, snapshots, alerts, and stats. |
| Prompts | `/api/prompts/*` | Prompt templates, versions, rendering, stats, and raw setup/connect prompts. |
| Billing and usage | `/api/billing/*`, `/api/usage/*`, `/api/cron/reset-meters` | Stripe checkout/portal, usage readout, and meter reset. |
| Code Sessions | `/api/code-sessions/*`, `/code-sessions` UI, `/api/cron/code-session-{cache-crater,weekly-memo}` | Multi-agent transcript ingest: Claude Code (Stop hook + JSONL backfill), Codex (JSONL parser + `dashclaw code ingest-codex`), and Hermes Agent (per-turn live ingest via `POST /api/code-sessions/ingest-live` with optional `finalize: true` to run optimizer + alerts pass on session close). 4-column cache-aware pricing, 7-rule optimizer, repeated-run detection, signals/alerts, weekly memo, /goal autopsy, Subagent ROI, and Optimal Files bundle generator (root CLAUDE.md, path-scoped rules, hooks, skill packs). Tables: `code_projects`, `code_sessions`, `code_session_messages`, `code_session_tool_uses`, `code_session_signals`, `code_session_alerts`, `code_session_memos`, `code_optimal_file_manifests`. Path B CLI: `dashclaw code ingest|ingest-codex|memo|apply`. MCP: `dashclaw_optimal_files_{preview,manifest}` tools and `dashclaw://code-sessions/*` resources. |
| Session handoffs | `POST/GET /api/handoffs`, `GET /api/handoffs/latest`, `GET /api/handoffs/{id}`, `POST /api/handoffs/{id}/consume` | Bridges agent sessions of the same agent: prior session writes a `{summary, open_loops, decisions_made, state_snapshot}` bundle on `on_session_end`; next session reads it via `on_session_start` and injects on first `pre_llm_call`. Hermes hooks wire this automatically; agents on Claude Code / Codex pick up via MCP (`dashclaw_handoff_create/latest/consume`). Table: `code_session_handoffs`. |
| Operator-tracked secrets | `GET/POST /api/secrets`, `PATCH/DELETE /api/secrets/{id}`, `GET /api/secrets/rotation-due` | Operator-owned credential rotation tracker. Stores metadata only — no values. Agents call `dashclaw_secret_due` before acting on credentials and `dashclaw_secret_mark_rotated` only when an operator confirms a rotation. Table: `governed_secrets`. |
| Skill safety scan | `POST /api/skills/scan`, `GET /api/skills/scans/{id}` | Static safety detector (11 rules across credential exfil, command injection, multi-line exfil, dangerous evals; false-positive avoidance via `(?<![.\w])` lookbehind). Agents call `dashclaw_skill_scan` before loading an untrusted skill; identical-content scans are deduped by hash. Table: `skill_scan_results`. |

### Tier 3: Archived platform-era routes

Legacy platform features that help agents perform work rather than govern work live under `app/api/_archive/`. They remain physically present for historical compatibility and migration safety, but they are not part of DashClaw's current product identity.

Examples include archived calendar, workspace, old routing, old messages, snippets, preferences, schedules, and older feedback/onboarding paths. Do not promote archived routes in new product copy unless they are intentionally restored to the governance runtime.

## Durable execution finality (v2.13.3)

Durable finality closes the gap between "this action was approved" and "this action definitely completed."

| Primitive | Detail |
|:---|:---|
| State column | `action_records.outcome_status` with `pending`, `completed`, `partial`, `failed`, `lost_confirmation`. |
| Agent endpoint | `POST /api/actions/:actionId/outcome` records `completed`, `partial`, or `failed`. |
| Poll endpoint | `GET /api/actions/:actionId/outcome` returns current outcome plus `elapsed_ms`. |
| One-shot rule | First terminal outcome wins. Later POSTs return `409 { error: "outcome already set", current_status }`. |
| Lost confirmation | `/api/cron/outcome-sweep` marks stale pending outcomes as `lost_confirmation`. |
| Timeout | Per-org `DASHCLAW_OUTCOME_TIMEOUT_MINUTES` setting, default 15, clamped `[1, 1440]`. |
| Idempotency | `POST /api/actions` accepts caller-supplied `idempotency_key`; duplicates replay the existing row. |
| SDKs | Node and Python expose report/get outcome helpers plus idempotency-key derivation helpers. |

Vercel Hobby cron runs the sweep daily. Operators who need tighter detection can run the same endpoint externally at their own cadence with `Authorization: Bearer $CRON_SECRET`, or use Vercel Pro with an hourly cron.

## Agent identity (Phase 2 / 2b / 2c)

`/api/guard` resolves agent identity on three independent axes, each recorded on
its own column of `guard_decisions` and returned on the guard response. None
overloads `verification_status`; an absent or invalid token always fails soft to
the Phase 1 trust-on-assertion path (body `agent_id`), never blocking on
infrastructure failure. Full setup guide: `docs/agent-identity.md`.

| Phase | Question | Column | Mechanism |
|:---|:---|:---|:---|
| **2 — verification** | *Who* signed the token? | `verification_status` | `app/lib/jwks-verifier.js` verifies an `Authorization: Bearer <JWT>` against the issuer's JWKS (`{iss}/.well-known/jwks.json`, cached 1 h, 30 s circuit breaker, SSRF-guarded). EdDSA / RS256–512 / ES256–512. On `verified`, JWT `sub` overrides body `agent_id`. Values: `verified | unverified | expired | failed | unknown_issuer | exp_too_far`. |
| **2b — replay** | Has this token been *reused*? | `replay_status` | `app/lib/repositories/jti-replay.repository.js` records `(issuer, jti)` in `jwt_replay_log` (race-free `ON CONFLICT DO NOTHING`). First use `unique`, second `replayed`. Values: `not_applicable | disabled | unique | replayed | not_present | unavailable | exp_too_far`. |
| **2c — binding** | Is this token bound to *this* call? | `act_status` | `app/lib/act-binding.js` recomputes a SHA-256 over the canonical `(action, target, goal)` tuple and compares it to the token's `urn:dashclaw:act-binding` claim. Values: `not_applicable | match | mismatch | not_present | unsupported_typ | ctx_incomplete`. |

Enforcement is mode-gated and fails open by default so the runtime records before
it blocks:

| Env var | Modes | Default | Blocks on |
|:---|:---|:---|:---|
| `DASHCLAW_ALLOWED_ISSUER` / `DASHCLAW_JWT_AUDIENCE` | (set / unset) | unset = any | restrict trusted issuers / validate `aud` |
| `DASHCLAW_JTI_REPLAY_PROTECTION` | `off` / `best_effort` / `required` | `best_effort` | `replayed`/`exp_too_far` always; `unavailable`/`not_present` only under `required` |
| `DASHCLAW_JTI_MAX_TTL_SECONDS` | integer | `86400` | rejects tokens whose `exp` exceeds the cap (`exp_too_far`) |
| `DASHCLAW_ACT_BINDING` | `off` / `best_effort` / `required` | `off` | `mismatch` under `best_effort`+`required`; `not_present`/`unsupported_typ`/`ctx_incomplete` only under `required` |
| `DASHCLAW_ACT_BINDING_TYP` | csv | `action-binding/v1` | accepted binding `typ` allowlist |

Schema: `drizzle/0008` (verification), `0010`/`0011` (replay), `0012` (action
binding). The legacy public-key pairing flow (`/api/pairings`, RSA) remains for
older integrations but is no longer the primary identity surface.

## Integration model

DashClaw is intentionally multi-surface. Claude Code hooks are one strong integration path, not the product identity.

| Path | Best for | Artifact |
|:---|:---|:---|
| MCP server | MCP-capable agents, Claude Desktop/Code, managed agents, remote tool access | `@dashclaw/mcp-server`, `POST /api/mcp` |
| Node SDK | JavaScript/TypeScript agents and apps | `sdk/dashclaw.js`, npm package `dashclaw` version `2.13.0` |
| Python SDK | Python agents and backend workflows | `sdk-python/dashclaw/client.py` |
| Claude Code hooks | Coding-agent tool governance without per-call SDK code | `hooks/`, `npm run hooks:install`, `plugins/dashclaw/.claude-plugin/` |
| Codex plugin | Codex coding-agent governance via field-compatible hook schema | `cli/lib/codex/`, `dashclaw install codex`, `plugins/dashclaw/.codex-plugin/` |
| Hermes Agent plugin | Per-turn governance context injection, secret redaction, subagent ROI, live session ingest | `.hermes/hooks/`, `plugins/dashclaw/.hermes-plugin/`, `scripts/install-hermes-plugin.{sh,ps1}` |
| OpenClaw plugin | OpenClaw lifecycle-native governance | `packages/openclaw-plugin/` |
| Platform intelligence skills | Agent self-instrumentation and platform reference | `public/downloads/dashclaw-platform-intelligence/` and zip bundle |
| REST API | Custom frameworks and direct integrations | `app/api/**/route.js`, generated inventory/OpenAPI docs |
| Webhooks and approvals | Operator notification and external systems | Slack/Discord/Telegram adapters, webhook routes, approval bridges |

Framework examples exist for OpenAI, Anthropic, LangGraph, CrewAI, AutoGen, Claude Managed Agents custom tools, Claude Managed Agents MCP, and Claude Managed Agents MCP plus Governance Skill. See `examples/README.md`.

## SDK surface area

DashClaw ships two Node SDK entry points and a Python SDK.

| Surface | Entry point | Version or role |
|:---|:---|:---|
| Canonical Node SDK | `import { DashClaw } from 'dashclaw'` from `sdk/dashclaw.js` | npm package `dashclaw` version `2.13.0`; primary SDK for new work. |
| Legacy Node SDK | `import { DashClaw } from 'dashclaw/legacy'` from `sdk/legacy/dashclaw-v1.js` | Compatibility layer for older integrations. |
| Python SDK | `sdk-python/dashclaw/client.py` | Broad Python surface with route-contract parity for critical domains. |

The canonical Node SDK currently exposes **87 public methods** in `sdk/dashclaw.js` and the Python SDK **227** in `sdk-python/dashclaw/client.py` (both reproducible via `npm run sdk:count` — excludes the constructor and `_`-private methods). The Node surface includes:

- core governance: `guard`, `createAction`, `updateOutcome`, `getAction`, `approveAction`, `waitForApproval`, `recordAssumption`
- durable finality: `reportActionOutcome`, `getActionOutcome`, `reportActionSuccess`, `reportActionFailure`, `reportActionPartial`, `deriveIdempotencyKey`
- action graph, loops, signals, learning, scoring, messaging, handoffs, security scan, feedback, threads, sync, sessions
- workflow templates, model strategies, knowledge collections, and capability registry/runtime methods

Use `docs/sdk-parity.md` for domain-level parity and consolidation status.

## Operations and deployment

### Required local commands

| Command | Purpose |
|:---|:---|
| `npm run lint` | ESLint. |
| `npm run docs:check` | Validate source-of-truth doc metadata and generated-doc expectations. |
| `npm run route-sql:check` | Guard against direct route SQL growth. |
| `npm run openapi:check` | Ensure stable OpenAPI artifact is current. |
| `npm run api:inventory:check` | Ensure generated API inventory is current. |
| `npm test -- --run` | Full Vitest suite in CI mode. |
| `npm run sdk:integration:python` | Python SDK integration harness, live-network cases skipped by default. |
| `PYTHONPATH=sdk-python python -m unittest discover -s sdk-python/tests -p "test_sdk_v2_surface.py"` | Targeted Python v2 surface test. |
| `npm run livingcode:refresh` | Regenerate livingcode dashboard and platform-intelligence bundles. |

### CI/CD expectations

Every PR to `main` should keep these clean:

1. `npm run lint`
2. `npm run docs:check`
3. `npm run route-sql:check`
4. `npm run openapi:check`
5. `npm run api:inventory:check`
6. `npm test -- --run`

Release-readiness passes may additionally run SDK integration checks, startup smoke checks, and migration checks when the target environment is safe.

### Deployment runbooks

- `docs/ops/hosted-deployment.md` - hosted-mode deployment with Neon, Vercel, Cloudflare Turnstile, DNS, cron, and rollback.
- `docs/hosted-deployment-runbook.md` - hosted trial mode and operator-managed infrastructure notes.
- `scripts/setup.mjs` and `scripts/init-self-host-env.mjs` - local/self-host setup helpers.
- `scripts/auto-migrate.mjs` - idempotent migration runner used by deploy/setup paths.
- `npm run doctor` / `dashclaw doctor` - local and remote diagnostic entry points backed by `app/lib/doctor/`.

## Core libraries

| Library | Role |
|:---|:---|
| `app/lib/db.js` | Neon/Postgres connection. |
| `app/lib/org.js` | Org resolution, scoping, and roles. |
| `app/lib/guard.js` | Policy evaluation engine. |
| `app/lib/repositories/actions.repository.js` | Action ledger, durable outcome, idempotency, trace/graph data access. |
| `app/lib/security.js` | Sensitive-data scanning and redaction. |
| `app/lib/events.js` | Org-scoped event publish layer. |
| `app/lib/signals.js` | Runtime signal/anomaly computation. |
| `app/lib/readiness.mjs` | Setup/readiness checks. |
| `app/lib/doctor/` | Shared diagnostic engine for API, CLI, and local doctor scripts. |
| `app/lib/integration-health.js` | Integration credential health checks. |
| `app/lib/notification-adapters/` | Slack, Discord, Linear, GitHub, Email notification adapters. |
| `app/lib/telegramApprovals.js` | Telegram approval messages and inline callbacks. |
| `app/lib/discordApprovals.js` | Discord approval messages and interaction bridge. |
| `app/lib/capability-invoke.js` | Governed HTTP capability invocation. |
| `app/lib/workflow-executor.js` | Sequential governed workflow execution. |
| `app/lib/step-handlers.js` | Workflow step handlers. |
| `app/lib/template-vars.js` | Template variable substitution. |
| `app/lib/usage.js` | Plan limits, quota enforcement, metering, and cost estimation. |
| `app/lib/billing.js` | Token-cost pricing helpers. |
| `app/lib/policy-generator.js` | Natural-language policy generation. |
| `app/lib/predictive-risk.js` | Statistical and optional LLM-assisted risk scoring. |

## Category enforcement

DashClaw is **decision infrastructure**, not an agent framework.

Rule: if a feature helps an agent achieve a goal, it is outside the core runtime unless it is explicitly framed as a governed capability. If a feature helps an operator govern, approve, verify, audit, or recover agent actions, it belongs in DashClaw.
