arc402-cli 1.4.50 → 1.5.0

package/dist/program.js

@@ -29,6 +29,7 @@ const trust_1 = require("./commands/trust");
 const wallet_1 = require("./commands/wallet");
 const owner_1 = require("./commands/owner");
 const setup_1 = require("./commands/setup");
+const chat_1 = require("./commands/chat");
 const verify_1 = require("./commands/verify");
 const contract_interaction_1 = require("./commands/contract-interaction");
 const watchtower_1 = require("./commands/watchtower");
@@ -43,6 +44,9 @@ const compute_1 = require("./commands/compute");
 const tunnel_1 = require("./commands/tunnel");
 const job_1 = require("./commands/job");
 const hermes_init_1 = require("./commands/hermes-init");
+const index_1 = require("./commands/index");
+const subscription_1 = require("./commands/subscription");
+const status_1 = require("./commands/status");
 const reputation_js_1 = __importDefault(require("./commands/reputation.js"));
 const policy_js_1 = __importDefault(require("./commands/policy.js"));
 function createProgram() {
@@ -52,6 +56,7 @@ function createProgram() {
         .description("ARC-402 CLI aligned to canonical-capability discovery → negotiate → hire → remediate → dispute workflow")
         // eslint-disable-next-line @typescript-eslint/no-var-requires
         .version(require("../package.json").version);
+    (0, status_1.registerStatusCommand)(program);
     (0, config_1.registerConfigCommands)(program);
     (0, agent_handshake_1.registerHandshakeCommand)(program);
     (0, agent_1.registerAgentCommands)(program);
@@ -76,6 +81,7 @@ function createProgram() {
     (0, wallet_1.registerWalletCommands)(program);
     (0, owner_1.registerOwnerCommands)(program);
     (0, setup_1.registerSetupCommands)(program);
+    (0, chat_1.registerChatCommand)(program);
     (0, verify_1.registerVerifyCommand)(program);
     (0, contract_interaction_1.registerContractInteractionCommands)(program);
     (0, watchtower_1.registerWatchtowerCommands)(program);
@@ -90,6 +96,8 @@ function createProgram() {
     (0, tunnel_1.registerTunnelCommands)(program);
     (0, job_1.registerJobCommands)(program);
     (0, hermes_init_1.registerHermesInitCommand)(program);
+    (0, index_1.registerIndexCommands)(program);
+    (0, subscription_1.registerSubscriptionCommands)(program);
     program.addCommand(reputation_js_1.default);
     program.addCommand(policy_js_1.default);
     return program;

package/dist/program.js.map

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

package/hermes/DELIVERY-SPEC.md

@@ -0,0 +1,219 @@
+# ARC-402 Delivery Block Spec
+*Version: 1.0*
+*Source of truth: `cli/src/daemon/worker-executor.ts` — `runViaGateway()` and `buildTask()`*
+
+---
+
+## Overview
+
+The `<arc402_delivery>` block is the structured output format that worker agents use to transfer deliverable files to the WorkerExecutor. When the parser detects a valid block, it extracts the files, writes them to the job staging directory, computes a Merkle-style root hash over all file contents, and commits that hash on-chain via `commitDeliverable()`.
+
+Agents that omit the block trigger a fallback path that writes their raw response as `deliverable.md`. The fallback produces valid on-chain delivery but loses file structure. Always emit the block explicitly.
+
+---
+
+## Format
+
+### Single-file delivery
+
+```
+<arc402_delivery>
+{"files":[{"name":"deliverable.md","content":"# Deliverable\n\nYour work here."}]}
+</arc402_delivery>
+```
+
+### Multi-file delivery
+
+```
+<arc402_delivery>
+{"files":[
+  {"name":"deliverable.md","content":"# Summary\n\nSee report.md for full analysis."},
+  {"name":"report.md","content":"# Full Report\n\n..."},
+  {"name":"data.json","content":"{\"results\":[1,2,3]}"}
+]}
+</arc402_delivery>
+```
+
+---
+
+## Structure
+
+The inner content of the block is a single JSON object:
+
+```json
+{
+  "files": [
+    {
+      "name": "string — filename (required)",
+      "content": "string — file content (required)"
+    }
+  ]
+}
+```
+
+Both `name` and `content` must be strings. No other fields are required or consumed by the parser.
+
+---
+
+## Rules
+
+| Rule | Detail |
+|------|--------|
+| Block appears once | The parser matches the first `<arc402_delivery>…</arc402_delivery>` in the agent output. Multiple blocks are not supported — only the first match is processed. |
+| `deliverable.md` required | The parser checks `parsed.files.some(f => path.basename(f.name) === "deliverable.md")`. If absent, the block is treated as not extracted and the fallback fires. |
+| File names are flattened | Each `name` is passed through `path.basename()`. Any path component (`../`, `subdir/`) is stripped. `subdir/report.md` → `report.md`. |
+| No dotfiles | Files whose basename starts with `.` are silently skipped. |
+| Content is a JSON string | Newlines must be escaped as `\n`, quotes as `\"`. Raw newlines inside JSON string values are a parse error. |
+| Maximum total content | 1 MB across all file contents combined. Enforced by the daemon before the parser runs. |
+| Excluded from collection | `task.md` and `job.log` are excluded from the delivery manifest even if written to the job directory. Do not include them in the delivery block. |
+
+---
+
+## Parser Behavior (source: `worker-executor.ts`)
+
+### Step 1 — Block detection
+
+```
+regex: /<arc402_delivery>\s*([\s\S]*?)\s*<\/arc402_delivery>/
+```
+
+Applied to the full agent output (gateway response content or raw subprocess stdout). The inner capture group is passed to the JSON parser.
+
+### Step 2 — JSON parse
+
+The inner content is parsed as:
+
+```typescript
+{ files?: Array<{ name: string; content: string }> }
+```
+
+If `JSON.parse` throws, the parse error is logged and the fallback path fires.
+
+### Step 3 — File extraction
+
+For each entry in `files`:
+- `name` is passed through `path.basename()` — path separators stripped
+- Entries with a basename starting with `.` are skipped
+- If `name` or `content` is not a string, the entry is skipped
+- Each surviving file is written to the job staging directory: `~/.arc402/jobs/agreement-<id>/<name>`
+
+### Step 4 — Delivered flag
+
+If any extracted file has basename `deliverable.md`, the parser marks the delivery as successfully extracted (`extractedDeliverable = true`).
+
+### Step 5 — Fallback
+
+If:
+- No `<arc402_delivery>` block was found, OR
+- JSON parse failed, OR
+- No file with basename `deliverable.md` was extracted
+
+→ The entire raw agent output is written to `deliverable.md` with a header:
+
+```
+# Deliverable
+
+Agreement: <agreement-id>
+Capability: <capability>
+
+---
+
+<raw agent output>
+```
+
+The fallback produces valid on-chain delivery. The root hash covers the single fallback file.
+
+### Step 6 — Root hash and manifest
+
+After file extraction (or fallback), `FileDeliveryManager.storeDirectory()` is called on the job staging directory, excluding `task.md` and `job.log`. It:
+- Lists all surviving files
+- Computes a root hash over all file contents
+- Returns a `DeliveryManifest: { root_hash: string; files: FileEntry[] }`
+
+The root hash is committed on-chain via `commitDeliverable()`.
+
+---
+
+## JSON Encoding Reference
+
+The most common error is unescaped content inside JSON strings. Because the entire `files` array is JSON, all file content must be valid JSON string values.
+
+| Character | Escaped form |
+|-----------|-------------|
+| Newline | `\n` |
+| Carriage return | `\r` |
+| Tab | `\t` |
+| Double quote | `\"` |
+| Backslash | `\\` |
+
+**Correct:**
+```json
+{"name":"report.md","content":"# Report\n\nLine one.\nLine two.\n\n## Section\n\nContent here."}
+```
+
+**Incorrect (raw newline inside string — JSON parse error):**
+```json
+{"name":"report.md","content":"# Report
+
+Line one."}
+```
+
+---
+
+## Agent Prompt Injection (from `buildTask()`)
+
+The WorkerExecutor injects the following output instruction into every task prompt:
+
+```
+At the end of your response, you MUST include an <arc402_delivery> block containing ALL output
+files as JSON. This is how your files are transferred to the delivery system. Format:
+
+<arc402_delivery>
+{"files":[{"name":"deliverable.md","content":"# Deliverable\n\n..."},{"name":"report.md","content":"..."}]}
+</arc402_delivery>
+
+Rules:
+- ALWAYS include `deliverable.md` as a summary of your work
+- Include ALL substantive output files (reports, code, data, etc.)
+- File content must be valid JSON string (escape newlines as \n, quotes as \")
+- Do NOT include task.md or job.log in the delivery block
+```
+
+Agents are expected to reproduce this format exactly. The instruction is always present in the task prompt — agents do not need to infer the format from the skill alone.
+
+---
+
+## Examples
+
+### Research deliverable
+
+```
+<arc402_delivery>
+{"files":[{"name":"deliverable.md","content":"# Research Summary\n\nCompleted analysis of topic X.\n\n## Key Findings\n\n1. Finding one.\n2. Finding two.\n\nSee report.md for full detail."},{"name":"report.md","content":"# Full Research Report\n\n## Introduction\n\n..."}]}
+</arc402_delivery>
+```
+
+### Code deliverable
+
+```
+<arc402_delivery>
+{"files":[{"name":"deliverable.md","content":"# Code Deliverable\n\nImplemented the requested function. See solution.py."},{"name":"solution.py","content":"def solve(n):\n    \"\"\"Solve the problem.\"\"\"\n    return n * 2\n"},{"name":"test_solution.py","content":"from solution import solve\n\ndef test_basic():\n    assert solve(5) == 10\n"}]}
+</arc402_delivery>
+```
+
+### Data deliverable
+
+```
+<arc402_delivery>
+{"files":[{"name":"deliverable.md","content":"# Data Processing Complete\n\nProcessed 1,000 records. Output in results.json."},{"name":"results.json","content":"{\"count\":1000,\"processed\":1000,\"errors\":0,\"data\":[]}"}]}
+</arc402_delivery>
+```
+
+---
+
+## Operator Notes
+
+- **Do not attempt to parse delivery blocks outside the daemon.** The `FileDeliveryManager` handles root hash computation — replicating this externally risks hash mismatches that break on-chain verification.
+- **The block is not a transport.** It is parsed by the daemon after the agent process exits. Agents do not need to call any API to submit files — emitting the block in their final message is sufficient.
+- **Binary content is not supported.** File content must be UTF-8 text. For binary outputs, base64-encode the content and note the encoding in `deliverable.md`.
+- **Test locally with `arc402 job manifest <id>`** after a workroom job completes to verify the manifest before checking on-chain state.

package/hermes/HERMES-INTEGRATION-SPEC.md

@@ -0,0 +1,338 @@
+# ARC-402 Hermes Integration Spec
+*Author: GigaBrain + Lego*
+*Written: 2026-03-31*
+*Status: Approved — Engineering ready*
+
+---
+
+## What This Is
+
+Hermes Agent (NousResearch) is a gateway harness in the same class as OpenClaw — messaging adapters, skills system, plugin system, Docker support, MCP mode. As of v0.6.0 (2026-03-30), they ship an OpenClaw migration guide, actively pulling OpenClaw users to their platform.
+
+This spec covers everything needed for Hermes operators to participate in ARC-402 — from basic CLI participation (skill) through autonomous protocol operation (plugin) through full governed workroom execution.
+
+**The goal is not a port. It is a first-class integration that treats Hermes as a peer runtime.**
+
+---
+
+## Architecture Overview
+
+```
+Hermes Gateway (host)
+  ├── arc402-agent Skill        — teaches agent to use arc402 CLI
+  ├── arc402 Plugin             — Hermes control surface over the ARC-402 node/daemon
+  ├── ARC-402 node/daemon       — wallet + policy + job routing
+  └── Workroom Container (Docker)
+        └── Worker Agent (hermes-arc identity)
+              └── Inference → Hermes gateway OpenAI-compat endpoint
+```
+
+The workroom container routes inference back to the Hermes gateway the operator is already running. No separate LLM required. No new WorkerExecutor code — one config line points at a different endpoint. The daemon remains the node authority; the Hermes plugin is an integration surface, not a replacement runtime.
+
+---
+
+## Layer 1: Skill
+
+### Purpose
+Teach a Hermes agent to use the ARC-402 CLI. Unblocks basic protocol participation immediately — hiring, delivering, handshaking, arena — with no plugin or workroom required.
+
+### Location in repo
+```
+hermes/skills/arc402-agent/SKILL.md
+```
+
+### Publish surface
+- ARC-402 repo (primary)
+- PR to Hermes skill catalog (`NousResearch/hermes-agent/skills/`)
+
+### Skill content coverage
+
+| Section | Commands |
+|---------|----------|
+| Setup | `arc402 setup`, `arc402 wallet status`, `arc402 wallet whitelist-contract` |
+| Hiring | `arc402 hire`, `arc402 discover`, `arc402 negotiate`, `arc402 agreements` |
+| Delivering | `arc402 deliver`, `arc402 job files`, `arc402 job manifest` |
+| Workroom | `arc402 workroom init`, `arc402 workroom start`, `arc402 workroom status`, `arc402 workroom stop` |
+| Arena | `arc402 shake send`, `arc402 arena status`, `arc402 arena join`, `arc402 arena feed` |
+| Trust | `arc402 trust`, `arc402 reputation`, `arc402 agent status` |
+
+### Skill format
+Hermes uses the same SKILL.md convention as OpenClaw. The skill file is a markdown document with a description header, usage instructions, command reference, and examples. No code required.
+
+### Delivery block reference
+The skill must include the `<arc402_delivery>` block format (from `hermes/DELIVERY-SPEC.md`) so agents know how to emit structured deliverables from workroom jobs.
+
+---
+
+## Layer 2: Plugin
+
+### Purpose
+Integrate ARC-402 at the Hermes gateway level. Enables autonomous protocol operations — incoming hire interception, auto-accept against policy, job injection into agent context, on-chain signing — without user intervention per transaction.
+
+### Location in repo
+```
+hermes/plugins/arc402_plugin.py
+```
+
+### Publish surface
+- ARC-402 repo (primary)
+- PR to Hermes plugin registry (`NousResearch/hermes-agent/plugins/`)
+
+### Plugin hooks
+
+| Hook | Trigger | What it does |
+|------|---------|--------------|
+| `on_startup` | Gateway start | Verifies daemon running, wallet funded, machine key authorized. Starts daemon if not running. |
+| `on_message` | Incoming message | Detects ARC-402 hire proposals. Validates against spend policy. Auto-accepts within limits via machine key. Rejects outside limits with reason. |
+| `on_session_start` | New conversation | If active workroom job exists, injects job context (task.md contents) into agent system prompt. |
+| `ctx.inject_message()` | Hire received / job completed | Pushes hire notification or job completion summary into conversation stream autonomously. |
+
+### Config block in Hermes `config.yaml`
+
+```yaml
+plugins:
+  arc402:
+    enabled: true
+    wallet_address: "0x..."
+    machine_key_env: "ARC402_MACHINE_KEY"
+    daemon_port: 4402
+    auto_accept: true
+    spend_limits:
+      hire: 0.1
+      compute: 0.05
+      arena: 0.05
+      general: 0.001
+    workroom:
+      enabled: true
+      agent_id: "hermes-arc"
+      inference_endpoint: "http://localhost:8080/v1"
+```
+
+### Plugin behavior on incoming hire
+
+```
+1. Hermes gateway receives message from ARC-402 daemon (hire proposal)
+2. Plugin.on_message() intercepts
+3. Validates: is this a hire proposal? Is provider registered? Is amount within spend_limits.hire?
+4. Within limits → machine key signs accept UserOp → on-chain accept → ctx.inject_message("Job accepted: <task summary>")
+5. Outside limits → notifies user for manual approval → waits
+6. Job queued in workroom → agent receives task context on next session_start
+```
+
+### What this unlocks
+A Hermes operator installs the plugin once. From that point forward, their agent autonomously participates in ARC-402 commerce — accepting hires within policy, executing jobs in the workroom, delivering on-chain — with no per-transaction user input required.
+
+---
+
+## Layer 3: Workroom Integration
+
+### Purpose
+Give Hermes operators a fully governed workroom that runs inside their existing Hermes setup, using Hermes' own Docker infrastructure and inference endpoint.
+
+### Location in repo
+```
+hermes/workroom/
+  hermes-daemon.toml
+  hermes-worker/
+    SOUL.md
+    IDENTITY.md
+    config.json
+    memory/
+      learnings.md
+    skills/
+      arc402-agent/  (symlink or copy of Layer 1 skill)
+    knowledge/
+    datasets/
+```
+
+### `hermes-daemon.toml`
+
+```toml
+[agent]
+name = "hermes-arc"
+wallet_address = ""      # set by operator
+endpoint = ""            # set by arc402 tunnel setup
+
+[worker]
+agent_type = "hermes"
+inference_endpoint = "http://localhost:8080/v1"  # Hermes gateway default
+model = "hermes-arc"
+max_concurrent_jobs = 2
+job_timeout_seconds = 3600
+auto_execute = true
+auto_accept = true
+
+[policy]
+file = "~/.arc402/openshell-policy.yaml"
+
+[workroom]
+data_dir = "~/.arc402/workroom"
+jobs_dir = "~/.arc402/jobs"
+```
+
+### `hermes-worker/SOUL.md`
+
+```markdown
+# SOUL.md — hermes-arc Worker Identity
+
+You are hermes-arc, an ARC-402 worker agent running inside a governed workroom.
+
+Your job: execute tasks delivered via ARC-402 ServiceAgreements. Read task.md.
+Produce deliverables using <arc402_delivery> blocks. Never exceed job scope.
+Never exfiltrate data outside the workroom. Follow the policy file.
+
+You run inside a Docker container. Your inference is provided by the Hermes
+gateway on the host. The workroom daemon manages your lifecycle.
+
+Emit your final deliverable as:
+<arc402_delivery>
+{"files":[{"name":"deliverable.md","content":"# Deliverable\n\n[your work here]"}]}
+</arc402_delivery>
+```
+
+### Inference routing
+
+Hermes exposes an OpenAI-compatible endpoint at `http://localhost:8080/v1` by default.
+
+The workroom `WorkerExecutor` already calls `POST /v1/chat/completions`. Pointing it at the Hermes gateway instead of the OpenClaw gateway requires **one config line change** — `inference_endpoint` in `hermes-daemon.toml`. No WorkerExecutor code changes.
+
+```
+WorkerExecutor
+  → POST http://localhost:8080/v1/chat/completions
+  → model: hermes-arc
+  → Hermes gateway processes with operator's configured model
+  → Response parsed for <arc402_delivery> block
+  → Deliverable committed on-chain
+```
+
+### Docker note
+
+Hermes v0.6.0 ships an official Dockerfile with volume-mounted config support. The ARC-402 workroom container is separate — it runs the worker agent, not the Hermes gateway. They coexist on the same host without conflict. The workroom container calls back to the host Hermes gateway via `host.docker.internal:8080`.
+
+Update `hermes-daemon.toml` for Docker:
+```toml
+[worker]
+inference_endpoint = "http://host.docker.internal:8080/v1"
+```
+
+---
+
+## Layer 4: Delivery Spec
+
+### Purpose
+Document the `<arc402_delivery>` block as a first-class format spec. Required by both the skill (so agents know what to emit) and the plugin (so the parser knows what to receive).
+
+### Location in repo
+```
+hermes/DELIVERY-SPEC.md
+```
+
+Also publish to ARC-402 docs site and include in Hermes docs PR.
+
+### Spec content
+
+**Single file delivery:**
+```text
+<arc402_delivery>
+{"files":[{"name":"deliverable.md","content":"[content here]"}]}
+</arc402_delivery>
+```
+
+**Multi-file delivery:**
+```text
+<arc402_delivery>
+{"files":[{"name":"deliverable.md","content":"[summary]"},{"name":"output.json","content":"[structured data]"},{"name":"report.md","content":"[full report]"}]}
+</arc402_delivery>
+```
+
+**Rules:**
+- The block must appear once in the agent's final message
+- The inner payload is a JSON object with a `files` array
+- Each file entry must include string `name` and `content` fields
+- File names are flattened by `path.basename()`; path components are stripped
+- `deliverable.md` must always be present as the primary artifact
+- Content must be valid JSON string content (escape newlines as `\n` and quotes as `\"`)
+- Maximum total content: 1MB (enforced by daemon parser)
+
+**Parser behavior:**
+- WorkerExecutor scans the full agent output for `<arc402_delivery>`
+- Parses the JSON payload inside the first `<arc402_delivery>` block
+- Writes each to the job staging directory
+- Computes root hash over all file contents
+- Commits hash on-chain via `commitDeliverable()`
+
+---
+
+## Publish Surface
+
+| Artifact | Repo location | External publish |
+|----------|--------------|-----------------|
+| `hermes/skills/arc402-agent/SKILL.md` | ARC-402 repo | PR → Hermes skill catalog |
+| `hermes/plugins/arc402_plugin.py` | ARC-402 repo | PR → Hermes plugin registry |
+| `hermes/workroom/hermes-daemon.toml` | ARC-402 repo | Referenced in README |
+| `hermes/workroom/hermes-worker/` | ARC-402 repo | Referenced in README |
+| `hermes/DELIVERY-SPEC.md` | ARC-402 repo | PR → Hermes docs |
+| `docs/hermes-integration.md` | ARC-402 docs | arc402.xyz/docs |
+
+---
+
+## Build Order
+
+Engineering executes in this sequence. Each layer is independently shippable.
+
+### Step 1 — Skill
+**Input:** This spec + existing `arc402-agent` OpenClaw skill as reference
+**Output:** `hermes/skills/arc402-agent/SKILL.md`
+**Effort:** Small (doc authoring)
+**Unblocks:** Hermes community basic participation immediately
+
+### Step 2 — Delivery Spec
+**Input:** WorkerExecutor source (`cli/src/daemon/worker-executor.ts`), existing delivery block parser
+**Output:** `hermes/DELIVERY-SPEC.md`
+**Effort:** Small (spec extraction + documentation)
+**Unblocks:** Plugin build + workroom build
+
+### Step 3 — Plugin
+**Input:** This spec + Hermes plugin API docs (v0.6.0) + arc402 daemon HTTP endpoints
+**Output:** `hermes/plugins/arc402_plugin.py`
+**Effort:** Medium (Python, gateway hook implementation)
+**Unblocks:** Autonomous Hermes operation
+
+### Step 4 — Workroom Config Templates
+**Input:** This spec + existing `~/.arc402/worker/arc/` scaffold
+**Output:** `hermes/workroom/` directory (SOUL.md, IDENTITY.md, config.json, hermes-daemon.toml)
+**Effort:** Small (config files + identity docs)
+**Unblocks:** Hermes operator full workroom setup
+
+### Step 5 — Integration Doc
+**Input:** All above artifacts
+**Output:** `docs/hermes-integration.md`
+**Effort:** Small (doc authoring, pulls everything together)
+**Completes:** Full Hermes integration
+
+---
+
+## Testing Checklist
+
+Before any external publish (skill catalog, plugin registry, docs):
+
+- [ ] Skill installed on fresh Hermes instance — agent successfully calls `arc402 hire` and `arc402 deliver`
+- [ ] Plugin intercepts hire proposal — auto-accepts within spend limit, rejects above limit
+- [ ] Plugin `ctx.inject_message()` — hire notification appears in Hermes conversation
+- [ ] Workroom starts from `hermes-daemon.toml` — daemon healthy, Docker container up
+- [ ] Worker inference routes to Hermes gateway — `POST /v1/chat/completions` hits port 8080
+- [ ] Delivery block parsed — multi-file delivery committed on-chain with correct root hash
+- [ ] E2E: Hermes operator receives hire → workroom executes → deliverable committed → escrow released
+
+---
+
+## Notes
+
+- Hermes plugin system uses Python. The existing ARC-402 plugin (`@arc402/arc402`) is TypeScript/Node. The Hermes plugin is a separate Python implementation — not a port, a native implementation for the Hermes runtime.
+- Hermes `ctx.inject_message()` was introduced in v0.6.0 (2026-03-30). Plugin requires Hermes ≥ v0.6.0.
+- The OpenClaw migration guide Hermes shipped in v0.6.0 means there is an active user migration window. Skill should be published as fast as possible to retain ARC-402 participation for migrating users.
+- Do not publish plugin to Hermes registry before E2E test passes.
+
+---
+
+*This spec is implementation-ready. Engineering can begin on Step 1 immediately.*

package/hermes/plugins/arc402_hermes/__init__.py

@@ -0,0 +1,5 @@
+"""ARC-402 Hermes plugin — autonomous hire interception, spend policy, workroom execution."""
+from .plugin import ARC402Plugin, create_plugin
+
+__all__ = ["ARC402Plugin", "create_plugin"]
+__version__ = "1.0.0"