agentcorp-broker 0.1.0-alpha.1

package/dist/types.js

@@ -0,0 +1,85 @@
+import { z } from "zod";
+export const MessageTypeSchema = z.enum([
+    "proposal",
+    "question",
+    "answer",
+    "report",
+    "review",
+    "verdict",
+    "status_update",
+]);
+export const MessageStatusSchema = z.enum([
+    "draft",
+    "pending_approval",
+    "approved",
+    "edited",
+    "rejected",
+    "delivered",
+    "acknowledged",
+]);
+export const TaskStatusSchema = z.enum([
+    "proposed",
+    "assigned",
+    "in_progress",
+    "blocked",
+    "awaiting_review",
+    "completed",
+    "failed",
+    "cancelled",
+]);
+export const PolicyActionSchema = z.enum([
+    "auto_approve",
+    "require_human",
+    "delegate_to_role",
+]);
+export const PolicySubjectSchema = z.enum(["message", "task"]);
+export const RoleSchema = z.object({
+    id: z.string().min(1).regex(/^[a-z][a-z0-9_-]*$/),
+    display_name: z.string().min(1).optional(),
+    model: z.string().min(1).optional(),
+    interface: z.literal("mcp").default("mcp"),
+    capabilities: z.array(z.string().min(1)).default([]),
+    allowed_peers: z.array(z.string().min(1)).default([]),
+    artifact_visibility: z.union([z.literal("all"), z.array(z.string().min(1))]),
+});
+export const InitialPolicySchema = z.object({
+    id: z.string().min(1).optional(),
+    subject: PolicySubjectSchema,
+    priority: z.number().int().default(0),
+    from_role: z.string().min(1).optional(),
+    to_role: z.string().min(1).optional(),
+    message_type: MessageTypeSchema.optional(),
+    risk_tags: z.array(z.string().min(1)).optional(),
+    from_status: TaskStatusSchema.optional(),
+    to_status: TaskStatusSchema.optional(),
+    action: PolicyActionSchema,
+    delegate_role: z.string().min(1).optional(),
+});
+export const LimitsConfigSchema = z
+    .object({
+    max_request_body_bytes: z.number().int().positive().optional(),
+    max_message_payload_bytes: z.number().int().positive().optional(),
+    max_artifact_bytes: z.number().int().positive().optional(),
+    max_payload_size_bytes: z.number().int().positive().optional(),
+    max_artifact_size_bytes: z.number().int().positive().optional(),
+    default_page_size: z.number().int().positive().optional(),
+    max_page_size: z.number().int().positive().optional(),
+    max_audit_payload_bytes: z.number().int().positive().optional(),
+})
+    .refine((data) => {
+    if (data.default_page_size && data.max_page_size) {
+        return data.default_page_size <= data.max_page_size;
+    }
+    return true;
+}, {
+    message: "default_page_size cannot be greater than max_page_size",
+    path: ["default_page_size"],
+});
+export const DEFAULT_MAX_AUDIT_PAYLOAD_BYTES = 65536; // 64 KB
+export const OrgConfigSchema = z.object({
+    company: z.object({ name: z.string().min(1) }),
+    roles: z.array(RoleSchema).min(1),
+    policies: z.array(InitialPolicySchema).default([]),
+    limits: LimitsConfigSchema.optional(),
+});
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,119 @@
+# AgentCorp Architecture Specification
+
+This document details the architectural topology, security boundaries, domain invariants, and runtime mechanics of AgentCorp.
+
+---
+
+## 1. System Topology & Process Boundaries
+
+![AgentCorp Architecture Blueprint](./images/architecture.jpg)
+
+AgentCorp follows a **single-writer local daemon** model designed to bridge heterogeneous AI clients while enforcing strict role boundaries and transactional data integrity:
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                    Heterogeneous Agents                     │
+│  ┌───────────────────────┐       ┌───────────────────────┐  │
+│  │   Antigravity / IDE   │       │   Codex / Extension   │  │
+│  │   (Role: developer)   │       │   (Role: architect)   │  │
+│  └───────────┬───────────┘       └───────────┬───────────┘  │
+└──────────────┼───────────────────────────────┼──────────────┘
+               │ stdio                         │ stdio
+┌──────────────▼───────────────────────────────▼──────────────┐
+│                 Role-Bound Stdio Adapters                   │
+│         (agentcorp mcp --role developer / architect)         │
+│  • Auto-spawns daemon if offline                            │
+│  • Binds identity via local bearer token                     │
+└──────────────┬───────────────────────────────┬──────────────┘
+               │ Streamable HTTP               │ Streamable HTTP
+               │ (Bearer <roleToken>)          │ (Bearer <roleToken>)
+┌──────────────▼───────────────────────────────▼──────────────┐
+│       AgentCorp Central Daemon (localhost, dynamic port)      │
+│                                                             │
+│  ┌──────────────────┐  ┌────────────────┐  ┌─────────────┐  │
+│  │ Streamable HTTP  │  │ Admin REST API │  │ SSE Stream  │  │
+│  │  MCP Transport   │  │  (/api/*)      │  │ /api/events │  │
+│  └────────┬─────────┘  └────────┬───────┘  └──────┬──────┘  │
+│           │                     │                 │         │
+│  ┌────────▼─────────────────────▼─────────────────▼──────┐  │
+│  │               AgentCorp Broker Engine                 │  │
+│  │ • Connection-enforced identity                        │  │
+│  │ • Deterministic policy evaluator (priority/subset)    │  │
+│  │ • EventEmitter domain pipeline                        │  │
+│  └──────────────────────────┬────────────────────────────┘  │
+│                             │                               │
+│  ┌──────────────────────────▼────────────────────────────┐  │
+│  │         Transactional SQLite Engine (WAL Mode)        │  │
+│  │ • Versioned migrations (schema_migrations)            │  │
+│  │ • Durable messages, tasks, approvals, and artifacts   │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────▲───────────────────────────────┘
+                              │
+┌─────────────────────────────┴───────────────────────────────┐
+│                   Human Oversight Consoles                  │
+│                                                             │
+│   ┌─────────────────────────────┐  ┌─────────────────────┐  │
+│   │ Terminal Review Loop (TUI)  │  │ Web Dashboard (SSE) │  │
+│   │ (agentcorp review)          │  │ (GET /console)      │  │
+│   └─────────────────────────────┘  └─────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Authentication & Identity Enforcement
+
+1. **Role Tokens**:
+   - Each role configured in `org.toml` is assigned a high-entropy cryptographically random bearer token stored in `.agentcorp/credentials.json` (`mode 0600`).
+   - Tokens never live in `org.toml` or git-tracked directories.
+2. **Connection-Enforced Identity**:
+   - The caller's role is established strictly during HTTP handshake via `Authorization: Bearer <roleToken>`.
+   - Tool arguments like `sender` or `caller` are **never** accepted from the client; identity spoofing is impossible.
+3. **Admin Token**:
+   - Administrative endpoints (`/api/approvals`, `/api/policies`, `/api/events`, `/api/audit/export`) require the separate `adminToken`.
+
+---
+
+## 3. Policy Evaluation & Human-in-the-Loop (HITL)
+
+AgentCorp operates on a **safe-by-default** security posture:
+
+```text
+Incoming Request (Message / Task Transition)
+   │
+   ├── 1. Verify Allowed Peers (is recipient in sender.allowed_peers?)
+   │        └── NO  ──> REJECT (NOT_AN_ALLOWED_PEER)
+   │
+   ├── 2. Evaluate Runtime Policies (Ordered by DESC priority)
+   │        ├── Match Subject ("message" / "task")
+   │        ├── Match Optional Criteria (from_role, to_role, message_type, to_status)
+   │        └── Match Risk Tags (Subset matching: all rule tags must be present)
+   │
+   ├── 3. Decision
+   │        ├── Match found with action="auto_approve" ──> PROCEED (Delivered / Updated)
+   │        └── NO match found OR action="require_human"
+   │              └── QUEUE in pending_approval
+   │                    ├── Recipient cannot see message
+   │                    ├── Event emitted over SSE
+   │                    └── Awaits Human Sign-off in Terminal / Web Console
+```
+
+---
+
+## 4. Real-Time Event Architecture (SSE)
+
+The broker daemon maintains an event-driven pub/sub architecture:
+* **Domain Events**: `message_created`, `message_delivered`, `approval_created`, `approval_decided`, `task_status_changed`, `policy_changed`.
+* **Server-Sent Events (`/api/events`)**: Pushes events to connected terminal observers and web consoles in real-time.
+* **Resilience**: Includes automatic 15-second keep-alive heartbeats and clean connection teardown on client disconnect.
+* **Agent work discovery**: `get_work_queue` projects unread messages, active tasks, and prioritized next actions from the same transactional state, avoiding client-side reconciliation races.
+* **Approved handoffs**: An intended assignee cannot observe a proposed task until its linked proposal is delivered. Proposal approval activates the assignment; `accept_handoff` then acknowledges and starts it idempotently.
+
+---
+
+## 5. Storage & Persistence
+
+* **Database Engine**: Built-in `node:sqlite` in WAL (Write-Ahead Logging) mode.
+* **Zero Native Dependencies**: No native compilation (`node-gyp`), ensuring universal cross-platform execution on Windows, macOS, and Linux.
+* **Migrations**: Automated forward schema migrations tracked in `schema_migrations`.
+* **Git Observability**: Complete state can be exported at any time into human-readable Markdown (`coord/audit.md`) and structured JSON (`coord/audit.json`).

package/docs/README.md

@@ -0,0 +1,37 @@
+# AgentCorp Documentation
+
+Welcome to the official AgentCorp documentation. AgentCorp is an open-source, local-first coordination broker designed to orchestrate teams of heterogeneous AI agents (such as Google Antigravity/Gemini, OpenAI Codex/ChatGPT, Anthropic Claude, Cursor, and more) over the Model Context Protocol (MCP) with Human-in-the-Loop (HITL) oversight.
+
+---
+
+## Documentation Navigation
+
+### Start Here
+
+* **[Beginner Setup & First Workflow](getting-started.md)**: Install AgentCorp, configure two agents, approve a handoff, and troubleshoot the connection without assuming prior MCP experience.
+
+### 1. Architecture & Design
+* **[Architecture Blueprint](ARCHITECTURE.md)**: Single-writer local daemon topology, Streamable HTTP MCP transport, role-bound stdio proxy adapters, transactional SQLite persistence, deterministic policy engine, and Server-Sent Events (SSE).
+* **[Build Roadmap](ROADMAP.md)**: Milestones, completed phases, and upcoming capabilities.
+
+### 2. Integration & Setup Guides
+* **[Google Antigravity Setup Guide](guides/antigravity-setup.md)**: Step-by-step guide to configuring Google Antigravity IDE as an AgentCorp role (e.g. Developer / Implementer).
+* **[OpenAI Codex Setup Guide](guides/codex-setup.md)**: Step-by-step guide to configuring OpenAI Codex desktop and extension as an AgentCorp role (e.g. Planner & Reviewer).
+* **[Claude Code & Cursor Setup Guide](guides/claude-cursor-setup.md)**: Universal instructions for connecting Claude Desktop, Claude Code, Cursor, Windsurf, and VS Code.
+* **[Human Oversight Console Guide](guides/human-console.md)**: Operating the terminal-native interactive review loop (`agentcorp review`) and the dark glassmorphic web dashboard (`agentcorp console --browser`).
+
+### 3. Core References
+* **[MCP Tools Reference](mcp-tools-reference.md)**: Exhaustive reference for all 15 MCP tools exposed to agents, including the prioritized `get_work_queue` view and idempotent `accept_handoff` operation.
+* **[CLI Reference](cli-reference.md)**: Complete command-line interface manual (`init`, `validate`, `start`, `stop`, `status`, `console`, `review`, `approvals`, `policies`, `audit`, `mcp`).
+* **[Policy & Safety Guide](policy-guide.md)**: Authoring safety rules, priority cascades, subset risk tag matching, and approval enforcement.
+* **[Release Guide](RELEASING.md)**: Prepare GitHub and npm, publish a preview safely, verify it, and recover from release mistakes.
+* **[Dogfooding Report](dogfooding-report.md)**: Findings from using AgentCorp itself for Codex-Gemini collaboration and the proposed direction for agent invocation.
+
+---
+
+## Core Principles
+
+1. **Heterogeneous Interoperability**: AI agents from different providers (Google Gemini, OpenAI GPT, Anthropic Claude) collaborate seamlessly without custom glue code or vendor lock-in.
+2. **Local-First & Single-Writer**: All coordination runs entirely on your local machine using SQLite with WAL mode. Agent state never leaves your workstation without your consent.
+3. **Safe by Default (HITL)**: Any message or task transition not explicitly granted an auto-approve policy is halted in a pending state until a human signs off.
+4. **Terminal-Native Workflow**: Designed by and for developers who live in the terminal, featuring instantaneous interactive keyboard reviews and live status summaries.

package/docs/RELEASING.md

@@ -0,0 +1,228 @@
+# AgentCorp Maintainer Release Guide
+
+This is the maintainer runbook for publishing `agentcorp-broker` to GitHub and
+npm. Publishing is intentionally a human-owned action. CI and agents may verify
+a release, but they must not create a public repository, push tags, or publish
+the package without explicit maintainer authorization.
+
+AgentCorp is currently an alpha developer preview. A GitHub repository is the
+source project; npm distributes the installable package built from it. A GitHub
+release and an npm release normally point to the same Git tag and version.
+
+## 1. One-time account and repository setup
+
+1. Create a public GitHub repository without adding a README, license, or
+   `.gitignore`; those files already exist locally.
+2. Decide whether it belongs to your personal account or an organization.
+3. Replace every placeholder project URL in `package.json` and `SECURITY.md`
+   with that repository's exact URL.
+4. Add the remote and use the conventional `main` branch:
+
+   ```sh
+   git remote add origin https://github.com/<owner>/AgentCorp.git
+   git branch -M main
+   git push -u origin main
+   ```
+
+5. Enable GitHub branch protection after the first push: require the CI checks
+   and prevent accidental force pushes to `main`.
+6. Create an npm account, verify its email address, and enable two-factor
+   authentication for publishing and account changes.
+7. Log in locally and confirm the account:
+
+   ```sh
+   npm login
+   npm whoami
+   ```
+
+GitHub's official instructions for an existing local repository are
+[here](https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github).
+
+## 2. Choose and verify the npm package name
+
+The manifest currently uses the unscoped name `agentcorp-broker`. Check the
+registry immediately before publication:
+
+```sh
+npm view agentcorp-broker name version dist-tags --json
+```
+
+An npm `E404` means no package is currently returned for that name, but it does
+not reserve the name. If the name is unavailable or you want ownership tied to
+your npm account or organization, use a scope such as
+`@<npm-account>/agentcorp` and update all install examples. A scoped public
+package is published with `--access public`.
+
+Do not rename the package after users depend on it unless you are prepared to
+publish a migration release. npm package scope guidance is
+[here](https://docs.npmjs.com/misc/scope/).
+
+## 3. Automated release gates
+
+Run these commands from a clean release branch:
+
+```sh
+npm ci
+npm run check
+npm run build
+npm test
+node dist/cli.js validate --config org.toml
+node dist/cli.js validate --config examples/org.toml
+npm audit --omit=dev
+npm pack --dry-run --ignore-scripts
+node dist/cli.js doctor --config org.toml
+git status --short
+```
+
+On Windows PowerShell, use `npm.cmd` if script execution policy blocks
+`npm.ps1`. The last command must print nothing. CI repeats the build and test
+gates on Ubuntu, Windows, and macOS with supported Node versions.
+
+Inspect the dry-run package listing. It should contain compiled `dist/` files,
+the public documentation, examples, license, changelog, security policy, and
+contribution guide. It must not contain `.agentcorp/`, `coord/`, `scratch/`,
+source tests, credentials, databases, logs, internal design notes, or binary
+documentation images.
+
+For the strongest install check, the test suite packs the project, installs it
+into a temporary directory outside the checkout, and runs the CLI there.
+
+## 4. Prepare the release commit
+
+Use [Semantic Versioning](https://docs.npmjs.com/about-semantic-versioning/).
+During the preview, versions look like `0.1.0-alpha.1`,
+`0.1.0-alpha.2`, and then `0.1.0-beta.1`. Once the API is stable, use regular
+major, minor, and patch versions.
+
+1. Choose a version that has never been published. npm does not allow the same
+   package name and version to be reused, even after unpublishing.
+2. Update `package.json` and `package-lock.json` together:
+
+   ```sh
+   npm version 0.1.0-alpha.1 --no-git-tag-version
+   ```
+
+3. Change the matching changelog heading from `Unreleased` to the publication
+   date and add a new `Unreleased` section for future work.
+4. Run every release gate again.
+5. Commit the exact candidate:
+
+   ```sh
+   git add --all
+   git commit -m "release: prepare v0.1.0-alpha.1"
+   ```
+
+## 5. Create and push the tag
+
+Create a signed tag if a signing identity is configured:
+
+```sh
+git tag -s v0.1.0-alpha.1 -m "Release v0.1.0-alpha.1"
+```
+
+Otherwise use an annotated, non-cryptographic tag:
+
+```sh
+git tag -a v0.1.0-alpha.1 -m "Release v0.1.0-alpha.1"
+```
+
+Push the release commit and that exact tag:
+
+```sh
+git push origin main
+git push origin v0.1.0-alpha.1
+```
+
+Avoid `--tags`; pushing only the intended tag reduces accidental publication
+of local tags.
+
+## 6. Publish the npm preview
+
+First inspect the final tarball without running lifecycle scripts:
+
+```sh
+npm pack --dry-run --ignore-scripts
+```
+
+Publish an alpha under the `alpha` distribution tag:
+
+```sh
+npm publish --access public --tag alpha
+```
+
+The tag matters. Without `--tag alpha`, npm assigns the release to `latest`,
+which makes ordinary installs select an unstable preview. npm's publish and
+distribution-tag behavior is documented in the
+[publish command](https://docs.npmjs.com/cli/commands/npm-publish/) and
+[dist-tag guide](https://docs.npmjs.com/adding-dist-tags-to-packages/).
+
+Complete the one-time-password prompt yourself. Never place an npm password,
+token, recovery code, or `.agentcorp/credentials.json` in the repository or an
+agent message.
+
+For later automated releases, prefer npm
+[trusted publishing](https://docs.npmjs.com/trusted-publishers/) from a tightly
+protected GitHub Actions environment. It uses short-lived OIDC credentials
+instead of a long-lived npm token and can add provenance for a public package
+from a public repository. Follow npm's current Node/npm version requirements,
+configure the exact repository and workflow filename in npm, and keep the
+release environment protected. Do not claim provenance for a local 2FA publish.
+
+## 7. Verify before announcing
+
+Read the registry metadata:
+
+```sh
+npm view agentcorp-broker@0.1.0-alpha.1 name version dist-tags repository --json
+```
+
+Then install into a new temporary directory or clean machine:
+
+```sh
+npm install --global agentcorp-broker@alpha
+agentcorp --version
+agentcorp --help
+```
+
+Initialize a disposable project and verify the actual first-run path:
+
+```sh
+mkdir agentcorp-release-check
+cd agentcorp-release-check
+agentcorp init
+agentcorp validate
+agentcorp start --daemon
+agentcorp doctor
+agentcorp stop
+```
+
+Finally, create a GitHub release for `v0.1.0-alpha.1`, copy the matching
+changelog entry into the notes, and mark it as a **pre-release**. GitHub releases
+are based on Git tags; see GitHub's
+[release documentation](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases).
+
+Announce the package only after both the npm installation and GitHub release
+are visible.
+
+## 8. Recovery rules
+
+- If publication fails before npm accepts it, fix the cause and retry the same
+  version only after confirming it is absent with `npm view`.
+- If npm accepted a broken release, do not overwrite it. Fix the code, increment
+  the prerelease number, rerun all gates, and publish the new version.
+- If the wrong dist-tag was used, correct the tag with npm dist-tag commands;
+  do not republish identical contents under the same version.
+- If credentials may have leaked, revoke or rotate them before any other work.
+- Never rewrite a public release tag. Add a new version and tag so users can
+  reproduce what was published.
+
+## 9. Release safety invariants
+
+- Policy evaluation and errors remain fail closed.
+- Artifact access checks are enforced by the authenticated broker role.
+- Runtime credentials, databases, logs, and audit exports are never packaged.
+- `package.json`, the Git tag, the changelog, GitHub release, and npm registry
+  all report the same version.
+- Alpha limitations are stated plainly: local trusted-user deployment, no shell
+  sandbox, no independent security audit, and no automatic wake-up of idle IDE
+  agents.

package/docs/ROADMAP.md

@@ -0,0 +1,112 @@
+# AgentCorp build roadmap
+
+This roadmap turns the v0.1 design specification into small, independently
+releasable vertical slices. Security and interoperability gates are release
+criteria, not follow-up polish.
+
+## Milestone 0 — repository foundation (complete)
+
+- Publishable TypeScript package and global CLI shape
+- Strict configuration validation for roles and role graphs
+- Transactional SQLite schema
+- Broker domain API for tasks, messages, approvals, policies, and artifacts
+- Role-bound stdio MCP server
+- Human approval CLI
+- Core behavior tests and open-source contribution files
+
+## Milestone 1 — central local broker (complete)
+
+Goal: match the design spec's single-writer topology without losing the easy
+stdio integration.
+
+- Long-lived broker daemon over MCP Streamable HTTP
+- Thin role-bound stdio adapter for hosts that only spawn local commands
+- Per-role credentials stored outside `org.toml`
+- Admin credential and separate approval endpoints
+- Database migrations with schema version enforcement
+- Graceful shutdown, health check, structured logs, and audit export
+- End-to-end MCP client tests using two simultaneous role connections
+
+Exit criteria met: agents cannot access the database directly through the
+AgentCorp package path; two real MCP clients exchange an approved message
+through one broker process; restart preserves all state.
+
+## Milestone 2 — seamless human console (complete)
+
+Goal: provide developer-first human oversight with terminal-native workflows
+and a real-time dark glassmorphic web dashboard.
+
+- Real-time event-driven broker domain events (`EventEmitter` over mutations)
+- Long-lived Server-Sent Events stream (`GET /api/events`) with live push updates
+- Terminal-native console (`agentcorp console`) and interactive review loop (`agentcorp review`, `agentcorp approvals review`)
+- Single-page dark glassmorphic web dashboard (`/console`) with no external framework dependencies
+- Side-by-side JSON diff viewer & payload editor with live validation
+- Role inboxes, task threads, artifact viewer, and runtime policy toggle controls
+- Prioritized per-role work queue and idempotent approved-handoff acceptance
+- Approval-bound assignment visibility so agents cannot act on proposed work early
+- Zero extra runtime dependencies, preserving ultra-fast startup
+
+Exit criteria met: A user can operate, monitor, and sign off multi-agent workflows
+either completely inside their terminal or via an intuitive live web dashboard without raw SQL.
+
+## Milestone 2.5 — bounded storage, self-healing sessions & observability (complete)
+
+Goal: ensure bounded memory and disk usage, auto-recovering stdio adapters, and complete operational transparency.
+
+- Hard memory & disk bounds: 2 MB HTTP body, 1 MB message payload, 5 MB artifact content, configurable 64 KB audit payload budget
+- Opaque cursor pagination across tasks, messages, inboxes, artifacts, and approvals
+- Safe history pruning (`agentcorp prune`) with dry-run simulation, foreign-key reply chain detachment, and SQLite WAL compaction (`agentcorp compact`)
+- Resilient Stdio MCP Proxy with auto-reconnection and bounded exponential backoff across daemon crashes/restarts
+- Cross-process startup locking with active PID checking and stale lock recovery
+- Working directory isolation automatically deriving project-scoped runtime paths from `org.toml`
+- Mutation idempotency keys (`idempotency_key`) and operation lookup (`get_operation`) guaranteeing zero duplicate mutations
+- Role presence tracking (`online`, `idle`, `offline`) and activity freshness telemetry (`fresh`, `idle`, `stale`) across `get_work_queue`, `/health`, and Web Console
+- Bounded rotating daemon logs (`.agentcorp/daemon.log`, 5 MB max with 3 backups) and crash forensics (`.agentcorp/crash.log`)
+- Diagnostic tool `agentcorp doctor` for comprehensive subsystem verification
+- Audit export explicit semantics distinguishing row-limit truncation from field-level clipping
+
+Exit criteria met: Chaos E2E kills daemon mid-session and proves same client recovery, durable state, zero duplicate mutation, bounded logs, clean package smoke test outside checkout, and verified doctor diagnostics.
+
+## Release Candidate 0.1.0-alpha.1 (complete)
+
+Goal: deliver a reproducible, high-standard open-source developer preview release candidate.
+
+- Cross-platform GitHub CI across Ubuntu, Windows, and macOS on supported Node 22 and 24 releases
+- Outside-checkout temporary-install package smoke test leaving zero workspace debris
+- Curated npm package manifest (< 200 KB packed) retaining declarations, source maps, console assets, and docs while excluding binary images and internal design specs
+- Open source community templates (Contributor Covenant Code of Conduct, GitHub Issue & PR templates)
+- Complete maintainer release guide (`docs/RELEASING.md`) separating automated checks from maintainer-owned npm publishing
+- Beginner setup and first-workflow guide plus a public dogfooding report
+- Strict typechecking for production and test sources with a production-only build configuration
+- Package-boundary regression assertions for the npm tarball
+
+## Milestone 3 — adapters and interoperability (next)
+
+- Tested setup guides for Codex, Gemini, Claude Code, VS Code, and Cursor
+- Agent Card export and an A2A compatibility adapter
+- HTTP artifact content store with size limits and streaming
+- Pluggable policy match dimensions
+- OpenTelemetry traces and metrics
+- Host-specific notification or runner adapters that can wake idle agents when approved work arrives
+
+Exit criteria: three vendor-distinct agents complete the same workflow without
+custom broker code.
+
+## Milestone 4 — stable public release
+
+- Threat model and independent security review
+- Protocol conformance suite
+- Backward-compatible database and API migration policy
+- Signed releases, SBOM, provenance, and automated npm publishing
+- Performance tests for concurrent roles and large task histories
+- `1.0.0` API stability commitment
+
+## Decisions to resolve before v0.2
+
+1. Authentication: local bearer tokens versus OS-bound credentials.
+2. Transport: HTTP-only daemon versus HTTP plus a local socket.
+3. Package identity: retain `agentcorp-broker` or publish under an owned npm
+   scope. The unscoped `agentcorp` package is already occupied.
+4. Task model: retain separate task/message records until A2A adapter work
+   produces evidence that unification reduces complexity.
+5. Artifact storage: maximum inline content size and URI scheme allowlist.