@bradheitmann/odin-sentinel 0.2.1

package/docs/guides/quick-start.md

@@ -0,0 +1,74 @@
+# Quick Start
+
+ODIN Sentinel runs as a local MCP server over stdio.
+
+It does not provide model inference. It does not host a backend. Your MCP client
+starts the process, calls ODIN tools, and reads ODIN protocol resources.
+
+## From Source
+
+```bash
+pnpm install
+pnpm run build
+node dist/src/bin/index.js
+```
+
+## Client Configuration
+
+Use the built server as a stdio command:
+
+```json
+{
+  "mcpServers": {
+    "odin-sentinel": {
+      "command": "node",
+      "args": ["/absolute/path/to/odin-sentinel/dist/src/bin/index.js"]
+    }
+  }
+}
+```
+
+For local development:
+
+```json
+{
+  "mcpServers": {
+    "odin-sentinel": {
+      "command": "pnpm",
+      "args": ["exec", "tsx", "/absolute/path/to/odin-sentinel/src/bin/index.ts"]
+    }
+  }
+}
+```
+
+## First Calls
+
+Ask the client to call:
+
+1. `odin.get_version`
+2. `odin.get_runtime_notice`
+3. `odin.get_startup_packet`
+
+Then read:
+
+1. `odin://protocol/main`
+2. `odin://protocol/roles`
+3. `odin://protocol/topology`
+4. `odin://protocol/delegation`
+
+That is enough for a client to understand the default team shape and how to
+start cleanly.
+
+For a suggested starter team, see
+[recommended-starter-team.md](recommended-starter-team.md).
+
+## Local State
+
+ODIN may point agents at these project-local locations:
+
+- `docs/handoffs/`
+- `.odin/handoffs/`
+- `.odin/audit/`
+
+They are not bundled state. Create them in the project where your agents are
+working if you want persistent handoffs or audit notes.

package/docs/guides/recommended-starter-team.md

@@ -0,0 +1,35 @@
+# Recommended Starter Team
+
+ODIN is opinionated, but not rigid.
+
+The profiles below are a good starting point for a visible multi-agent session.
+They are not bundled dependencies. Install and configure the harnesses you want,
+then point them at ODIN Sentinel through MCP.
+
+## Executive Office
+
+| Role | Suggested Harness | Suggested Model Class | Why |
+| --- | --- | --- | --- |
+| `A/EXEC-PM` | Codex CLI | GPT-5.5-class frontier reasoning model | Stable coordination, claim-bound reporting, and careful instruction handling. |
+| `A/EXEC-ODIN` | Codex CLI | GPT-5.5-class frontier reasoning model | Sentinel work: staying awake, polling, quality control, and closeout hygiene. |
+| `A/EXEC-ASST` | Claude Code | Claude Haiku-class fast assistant model | Low-latency ledger work, reminders, artifact indexing, and simple checks. |
+| `A/EXEC-RSCH` | Droid | Kimi K2.6-class orchestration model | Research, alternatives, synthesis, and context recovery. |
+| `A/EXEC-QA` | Droid | Kimi K2.6-class review model | Independent process review, evidence checks, and drift detection. |
+
+## Development Pod
+
+| Role | Suggested Harness | Suggested Model Class | Why |
+| --- | --- | --- | --- |
+| `<TEAM>/TEAM-PM` | Claude Code | Claude Opus/Sonnet-class coding model | Pod orchestration, task decomposition, dispatch, and worker follow-up. |
+| `<TEAM>/ODIN` | Codex CLI | GPT-5.5-class frontier reasoning model | Lightweight pod sentinel duties, blocker detection, and quality reminders. |
+| `<TEAM>/DEV-1` | Droid | Kimi K2.6-class coding model | Bounded implementation work. |
+| `<TEAM>/QA-1` | Crush | GLM-5.1-class independent review model | Independent QA with a different review style from the implementer. |
+| `<TEAM>/SHADOW-1` | Droid | Kimi K2.6-class review model | Second-pass critique, architectural concerns, and risk surfacing. |
+
+## Notes
+
+Use faster models for ledger work, routine research, and low-risk monitoring.
+Use stronger models for coordination, implementation, QA, and places where the
+cost of a missed detail is high.
+
+The defaults live in `protocol/model-profiles.yaml`. Change them freely.

package/docs/reference/client-compatibility.md

@@ -0,0 +1,59 @@
+# Client Compatibility
+
+ODIN Sentinel is implemented in TypeScript and runs on Node.js, but MCP clients
+do not need to be TypeScript or JavaScript. Clients interact with the server
+through MCP over stdio, which is JSON-RPC framed over standard input/output.
+
+## Compatibility Contract
+
+The server keeps the MCP boundary language-neutral:
+
+- tools accept and return JSON-compatible values
+- resources return text, JSON, Markdown, or YAML content
+- no tool requires a JavaScript object prototype, class instance, or local Node-specific object
+- no tool requires filesystem access from the client
+- fallback protocol snapshots are returned as plain filename-to-text maps
+
+## Rust, Zig, Go, And Native Clients
+
+Native clients that can spawn stdio subprocesses should launch the server as a
+subprocess:
+
+```text
+command: node
+args: [/path/to/odin-sentinel/dist/src/bin/index.js]
+transport: stdio
+```
+
+Then call normal MCP methods:
+
+- `tools/list`
+- `tools/call`
+- `resources/list`
+- `resources/read`
+
+## WebAssembly Clients
+
+WASM runtimes vary. Some can spawn subprocesses through a host capability; many
+cannot. If the WASM client cannot spawn a stdio process, use one of these
+patterns:
+
+1. Host bridge: native host process runs `odin-sentinel` and exposes MCP calls
+   to the WASM guest.
+2. Sidecar bridge: an external local process runs `odin-sentinel` and the WASM
+   client talks to the host through its supported bridge channel.
+3. Snapshot fallback: call `odin.export_protocol_snapshot` from a capable host and
+   provide the generated text files to the WASM agent as static context.
+
+## Portability Limits
+
+The current server runtime requires Node.js 20 or newer. This does not restrict
+the client implementation language; it only means the machine hosting the MCP
+server needs Node available.
+
+Future options if a pure native server is needed:
+
+- Rust MCP server using the same `protocol/` data files.
+- Go MCP server using the same `protocol/` data files.
+- Single-file generated JSON protocol bundle for embedded clients.
+- WASI-compatible read-only server if the target runtime supports stdio.

package/docs/reference/cost-and-privacy.md

@@ -0,0 +1,35 @@
+# Cost And Privacy
+
+ODIN Sentinel does not provide inference.
+
+It does not proxy model calls, host a backend, phone home, collect telemetry, or
+ship credentials. It is a local MCP server that returns protocol resources,
+startup packets, validation results, delegation envelopes, closeout checklists,
+and fallback text snapshots.
+
+## Who Pays For What
+
+The maintainer does not pay when another person runs ODIN Sentinel locally.
+
+Users are responsible for their own harness setup and any model calls those
+harnesses make. ODIN Sentinel only returns coordination data over MCP.
+
+ODIN Sentinel only names preferred harness slots and model capability profiles.
+Those are dispatch preferences, not hosted compute.
+
+## Network Boundary
+
+The server is stdio-only by default:
+
+```text
+MCP client  <->  local stdio process  <->  protocol files
+```
+
+No network call is required for normal operation.
+
+## Standalone Boundary
+
+ODIN Sentinel is standalone.
+
+The default handoff search list uses `.odin/` paths. A fresh repo does not need
+any separate orchestration system installed for ODIN Sentinel to work.

package/docs/reference/distribution.md

@@ -0,0 +1,74 @@
+# Distribution
+
+ODIN Sentinel is a local stdio MCP server. The simplest public distribution is
+an npm package that ships prebuilt JavaScript and protocol files.
+
+## Recommended Install Path
+
+After publishing:
+
+```bash
+pnpm dlx odin-sentinel
+```
+
+MCP client configuration can then use:
+
+```json
+{
+  "mcpServers": {
+    "odin-sentinel": {
+      "command": "pnpm",
+      "args": ["dlx", "odin-sentinel"]
+    }
+  }
+}
+```
+
+`npx -y odin-sentinel` is also viable for npm-first clients.
+
+## Local Clone Path
+
+For source builds:
+
+```bash
+pnpm install
+pnpm run build
+node dist/src/bin/index.js
+```
+
+Then point the client at the built file:
+
+```json
+{
+  "mcpServers": {
+    "odin-sentinel": {
+      "command": "node",
+      "args": ["/absolute/path/to/odin-sentinel/dist/src/bin/index.js"]
+    }
+  }
+}
+```
+
+## Advanced Root Override
+
+The server normally finds its bundled `protocol/` directory automatically.
+
+Advanced deployments can set `ODIN_SENTINEL_ROOT` to point at another checked-out
+ODIN Sentinel root that contains the full `protocol/` tree. Most users do not
+need this.
+
+## Binary Strategy
+
+A native binary is possible, but it should not be the first distribution path.
+The server is small, stdio-only, and already fits the package manager workflow
+most MCP clients expect.
+
+Good future binary routes:
+
+- Rust or Go implementation over the same `protocol/` files.
+- Generated single-file protocol bundle for embedded clients.
+- Homebrew formula once the public package name and release cadence are stable.
+
+Avoid a bundled Node executable unless users ask for it. Those bundles tend to
+make asset paths, source maps, and platform support more awkward than the code
+deserves.

package/docs/reference/public-surface-audit.md

@@ -0,0 +1,133 @@
+# Public Surface Audit
+
+This document records the current public-release audit scope for ODIN Sentinel.
+
+## Current Tree Result
+
+Current tracked source, docs, protocol files, tests, and package metadata pass
+the public-surface audit:
+
+```bash
+pnpm run audit:public
+```
+
+The audit checks for:
+
+- local home-directory paths
+- local agent configuration paths
+- legacy extension terminology from adjacent agent systems
+- secret-looking assignments
+
+## Named External Concepts
+
+ODIN Sentinel intentionally names these external concepts:
+
+- MCP / Model Context Protocol
+- stdio
+- Node.js
+- TypeScript / JavaScript
+- pnpm / npm / npx
+- Codex CLI
+- Claude Code
+- Droid
+- Crush
+- Goose
+- Zed
+- OpenCode
+- Cursor
+- Rust
+- Go
+- Zig
+- WebAssembly / WASM
+- Homebrew
+
+These are examples, runtimes, package managers, languages, or harnesses. They
+are not bundled dependencies unless listed in `package.json`.
+
+## Named ODIN Concepts
+
+- ODIN Sentinel
+- ODIN
+- SCP / Sentinel Coordination Protocol
+- CMUX-compatible terminal-pane teams
+- EXEC PM
+- EXEC ODIN
+- EXEC ASST
+- EXEC RSCH
+- EXEC QA
+- TEAM PM
+- TEAM ODIN
+- DEV WORKER
+- QA WORKER
+- SHADOW REVIEWER
+
+## Local Paths
+
+ODIN Sentinel intentionally mentions these project-local paths:
+
+- `docs/handoffs/`
+- `.odin/handoffs/`
+- `.odin/audit/`
+
+These are caller-created paths for projects that use ODIN. They are not bundled
+private state.
+
+Docs also use placeholder install paths such as:
+
+- `/absolute/path/to/odin-sentinel/dist/src/bin/index.js`
+- `/path/to/odin-sentinel/dist/src/bin/index.js`
+
+These are examples, not real local paths.
+
+## Scripts Mentioned
+
+Repo scripts in `package.json`:
+
+- `pnpm run clean`
+- `pnpm run build`
+- `pnpm run dev`
+- `pnpm run audit:public`
+- `pnpm run test:package`
+- `pnpm test`
+- `pnpm run typecheck`
+- `pnpm run validate`
+
+Referenced local script files:
+
+- `scripts/audit/public-surface.mjs`
+- `scripts/audit/verify-pack.mjs`
+
+No missing repo-local scripts are known.
+
+External commands mentioned in docs:
+
+- `node`
+- `pnpm`
+- `npm`
+- `npx`
+- `codex mcp add`
+- `droid mcp add`
+
+These are external user-installed tools, not files this repository must provide.
+
+## Snapshot Tools
+
+Current MCP snapshot tool:
+
+- `odin.export_protocol_snapshot`
+
+No external local extension is required for ODIN Sentinel to work.
+
+## Git History Warning
+
+The current tree is sanitized, but this private development repository has older
+commits that contain removed terminology and experimental paths.
+
+Do not make this private development history public as-is. For an open-source
+release, publish from a fresh repository, a squashed root commit, or a sanitized
+history rewrite after re-running:
+
+```bash
+pnpm run validate
+pnpm run audit:public
+```

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@bradheitmann/odin-sentinel",
+  "version": "0.2.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Multi-harness terminal-pane team builder and orchestrator over MCP.",
+  "type": "module",
+  "main": "./dist/src/protocol/index.js",
+  "types": "./dist/src/protocol/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/protocol/index.d.ts",
+      "import": "./dist/src/protocol/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/src/mcp/server.d.ts",
+      "import": "./dist/src/mcp/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "odin-sentinel": "./dist/src/bin/index.js",
+    "odin-sentinel-mcp": "./dist/src/bin/index.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "protocol",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "agent-orchestration",
+    "multi-agent",
+    "sentinel"
+  ],
+  "author": "ODIN Sentinel contributors",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "4.1.5",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.5"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "dev": "tsx src/bin/index.ts",
+    "audit:public": "node scripts/audit/public-surface.mjs",
+    "test:package": "node scripts/audit/verify-pack.mjs",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "validate": "pnpm run audit:public && pnpm run typecheck && pnpm test && pnpm run build && pnpm run test:package"
+  }
+}

package/protocol/SCP.md

@@ -0,0 +1,34 @@
+# ODIN Sentinel Coordination Protocol
+
+Version: 0.2.1
+
+ODIN Sentinel is a portable coordination layer for visible multi-agent teams.
+SCP means Sentinel Coordination Protocol in this repository. It is not Secure
+Copy.
+It provides generic role contracts, startup packets, receipt validation, team
+manifest validation, native visible-role delegation packets, closeout
+checklists, and fallback protocol snapshots through an MCP server.
+
+## Principles
+
+- Visible role slots are the audit surface.
+- ODIN roles are meta-control roles accountable to user authority.
+- PM roles coordinate delivery but do not own ODIN oversight.
+- Worker roles implement bounded scope and produce evidence.
+- QA roles verify independently and do not accept their own work.
+- Handoffs, closeout, and restart packets must be explicit.
+- Secrets are never printed or embedded in receipts.
+- Delegation is native to the server and must not require an external extension.
+
+## Startup Defaults
+
+Fresh startup creates an executive office and one development pod unless the
+user or a handoff requests another topology.
+
+## Closeout Defaults
+
+Closeout supports two modes:
+
+- `PARK_FOR_CONTINUITY`: keep role slots open and park occupants.
+- `FULL_SESSION_SHUTDOWN`: quit occupants, verify exit, and close panes except
+  the final user-designated surface.

package/protocol/closeout.yaml

@@ -0,0 +1,20 @@
+version: 0.2.1
+modes:
+  PARK_FOR_CONTINUITY:
+    description: Keep role slots open, park occupants, save handoffs, and preserve continuity.
+    required_steps:
+      - collect_handoffs
+      - classify_worktree
+      - record_metrics
+      - park_or_reset_occupants
+      - verify_restart_path
+  FULL_SESSION_SHUTDOWN:
+    description: Save handoffs, quit occupants, verify exit, close panes, and leave only the final user-designated surface.
+    required_steps:
+      - collect_handoffs
+      - classify_worktree
+      - record_metrics
+      - quit_each_agent_occupant
+      - verify_agent_exit
+      - close_agent_panes
+      - deliver_final_report

package/protocol/delegation.yaml

@@ -0,0 +1,38 @@
+version: 0.2.1
+delegation_contract:
+  required_fields:
+    - receipt_type
+    - source_role
+    - target_role_slot
+    - task
+    - scope
+    - authority
+    - report_back
+    - visibility
+  authority_fields:
+    - may_implement
+    - may_qa_accept
+    - write_scope
+    - read_scope
+    - prohibited_paths
+  visibility_fields:
+    - requires_visible_role_slot
+    - hidden_agents_allowed
+    - delivery_proof_required
+  receipt_types:
+    - SCP-DELEGATE
+    - SCP-TERMINAL-DELIVERY
+    - SCP-CMUX-DELIVERY
+    - SCP-COORDINATION
+  delivery_states:
+    - DELIVERED_ACKED
+    - DELIVERED_NO_ACK
+    - INPUT_BAR_ONLY
+    - PANE_BLOCKED_ON_PERMISSION
+    - PANE_STILL_THINKING
+  rules:
+    - Delegation must target a visible role slot.
+    - Delegation must not create hidden agents or off-ledger workers.
+    - Delegation must include exact authority and scope.
+    - Terminal text left in an input bar is not delivery.
+    - QA acceptance cannot be delegated to the same role that implemented the deliverable.

package/protocol/model-profiles.yaml

@@ -0,0 +1,63 @@
+version: 0.2.1
+policy:
+  semantics: Recommended starter profiles, not bundled dependencies or availability guarantees.
+  runtime_requirement: Users must install and configure their own harnesses. Launchers must verify local harness/model availability before dispatch and apply fallbacks when unavailable.
+profiles:
+  A/EXEC-PM:
+    model: GPT-5.5-class frontier reasoning model
+    harness: Codex CLI
+    reasoning: high
+    rationale: "Use for steady executive coordination, careful instruction following, and claim-bound status control."
+  A/EXEC-ODIN:
+    model: GPT-5.5-class frontier reasoning model
+    harness: Codex CLI
+    reasoning: xhigh
+    rationale: "Use for sentinel work: staying awake, polling, quality control, closeout hygiene, and follow-up."
+  A/EXEC-ASST:
+    model: Claude Haiku-class fast assistant model
+    harness: Claude Code
+    reasoning: default_or_high_if_supported
+    rationale: "Use for low-latency ledger, reminders, artifact indexing, and assistant chores."
+  A/EXEC-RSCH:
+    model: Kimi K2.6-class orchestration model
+    harness: Droid
+    reasoning: high
+    rationale: "Use for broad research, alternatives, synthesis, and context recovery."
+  A/EXEC-QA:
+    model: Kimi K2.6-class review model
+    harness: Droid
+    reasoning: high
+    rationale: "Use for independent process review, evidence checks, and drift detection."
+  TEAM_PM:
+    model: Claude Opus/Sonnet-class coding model
+    harness: Claude Code
+    reasoning: high_if_supported
+    rationale: "Use for pod orchestration, task decomposition, dispatch, and worker follow-up."
+  TEAM_ODIN:
+    model: GPT-5.5-class frontier reasoning model
+    harness: Codex CLI
+    reasoning: low
+    rationale: "Use for lightweight pod sentinel duties, polling, blocker detection, and quality reminders."
+  DEV_WORKER:
+    model: Kimi K2.6-class coding model
+    harness: Droid
+    reasoning: high
+    rationale: "Use for bounded implementation work when the task benefits from strong local execution."
+  QA_WORKER:
+    model: GLM-5.1-class independent review model
+    harness: Crush
+    reasoning: high
+    rationale: "Use for independent QA so the reviewer differs from the implementer."
+  SHADOW_REVIEWER:
+    model: Kimi K2.6-class review model
+    harness: Droid
+    reasoning: high
+    rationale: "Use for second-pass critique, architectural concerns, and risk surfacing."
+fallbacks:
+  worker:
+    - harness: Droid
+      model: Kimi K2.6-class coding model
+      reasoning: high
+    - harness: Claude Code
+      model: Claude Sonnet-class balanced coding model
+      reasoning: high_if_supported

package/protocol/receipts/boot-receipt.yaml

@@ -0,0 +1,23 @@
+required_fields:
+  - role
+  - authority_layer
+  - team
+  - terminal_locator
+  - branch
+  - cwd
+  - model_harness
+  - permission_mode
+  - may_implement
+  - may_qa_accept
+  - reports_to
+  - write_scope
+  - evidence_path
+  - current_task
+recommended_fields:
+  - upstream
+  - head_sha
+  - cost_tier
+  - capability_profile
+  - delegates_to
+  - prohibited_paths
+  - proof_source

package/protocol/receipts/team-manifest.yaml

@@ -0,0 +1,9 @@
+required_fields:
+  - session_id
+  - topology
+  - executive_office
+  - development_pods
+  - odin_mesh
+  - model_profile
+  - handoff_sources
+  - startup_objectives