@poa-box/agent 0.1.0

package/dist/pop-agent.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/pop-agent.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * pop-agent — the agent-runtime entry point.
+ *
+ * Identical to `pop` except the agent + brain command groups are visible in
+ * help. The human `pop` binary hides them (they still execute when invoked
+ * explicitly, so skills and muscle memory keep working); this bin is what an
+ * agent process or its operator should run.
+ *
+ * Implementation: set the mode flag, then hand over to @poa-box/cli, whose entry
+ * module runs the CLI on load. The agent/brain commands themselves are
+ * registered by @poa-box/cli's plugin probe finding this package — see
+ * `registerAgentSurface` in src/index.ts (this package).
+ */
+process.env.POP_AGENT_MODE = '1';
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+require('@poa-box/cli');

package/docs/agent.md

@@ -0,0 +1,126 @@
+<!-- AUTO-GENERATED by scripts/generate-cli-docs.ts — do not edit. Regenerate: yarn docs:gen -->
+
+# pop agent
+
+Agent operations & monitoring
+
+## pop agent status
+
+Show agent operational status and action items
+
+```text
+pop agent status [flags]
+```
+
+## pop agent triage
+
+Prioritized action plan for current heartbeat
+
+```text
+pop agent triage [flags]
+```
+
+## pop agent daily-digest
+
+Summarize cross-agent activity for operator status checks
+
+```text
+pop agent daily-digest [flags]
+```
+
+| Flag | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--per-agent` | boolean | no | `false` | Group activity by agent |
+| `--since` | string | no | `24h` | Time window: 6h, 12h, 24h, 48h, 7d |
+
+## pop agent register
+
+Register agent identity on ERC-8004
+
+```text
+pop agent register [flags]
+```
+
+| Flag | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--capabilities` | string | no | - | Comma-separated capabilities (e.g. "governance,code-review,treasury") |
+| `--description` | string | no | `""` | Agent description |
+| `--name` | string | yes | - | Agent name |
+
+## pop agent delegate
+
+Set up EIP-7702 delegation for gas sponsorship
+
+```text
+pop agent delegate [flags]
+```
+
+## pop agent setup-sponsorship
+
+Set up full gas sponsorship (delegate + budget + fee caps)
+
+```text
+pop agent setup-sponsorship [flags]
+```
+
+| Flag | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--budget-per-day` | number | no | `0.1` | Gas budget per day in xDAI |
+| `--hat-id` | string | yes | - | Agent hat ID (decimal or hex) |
+| `--org-id` | string | yes | - | Org ID (bytes32 hex) |
+
+## pop agent paymaster-status
+
+Show gas sponsorship status (budgets, deposits, fee caps)
+
+```text
+pop agent paymaster-status [flags]
+```
+
+| Flag | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--hat-id` | string | no | - | Hat ID to check budget for (decimal or hex) |
+
+## pop agent onboard
+
+Complete agent onboarding: register + delegate + identity + brain
+
+```text
+pop agent onboard [flags]
+```
+
+| Flag | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--capabilities` | string | no | - | Comma-separated capabilities |
+| `--description` | string | no | `""` | Agent description |
+| `--username` | string | yes | - | Agent username |
+
+## pop agent deploy-to-org
+
+Check readiness for cross-org deployment
+
+```text
+pop agent deploy-to-org [flags]
+```
+
+| Flag | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--chain` | number | yes | - | Target chain ID |
+| `--target-org` | string | yes | - | Target org name |
+| `--username` | string | no | - | Username to register (if not already registered) |
+
+## pop agent init
+
+Initialize a new agent (brain files, wallet, bootstrap checklist)
+
+```text
+pop agent init [flags]
+```
+
+| Flag | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--hat-id` | string | no | - | Hat ID for gas sponsorship |
+| `--home` | string | no | - | Agent home directory (default: ~/.pop-agent) |
+| `--username` | string | no | - | Agent username |
+
+_Global flags: --org, --chain, --rpc, --json, --private-key, --dry-run, --yes, --verbose, --quiet, --preflight (see [index.md](../../../docs/reference/cli/index.md))_

package/docs/agents/brain-anti-entropy.md

@@ -0,0 +1,127 @@
+# Brain layer anti-entropy — rebroadcast loop
+
+**Task**: [#429](../../) (T1). **Parent**: [brain-crdt-vs-go-ds-crdt
+comparison](../agent/artifacts/research/brain-crdt-vs-go-ds-crdt-comparison.md)
+
+## What this fixes
+
+Gossipsub is broadcast-only — no store-and-forward. An announcement
+published while a peer is offline is lost forever. In our 3-agent
+sequential-slot setup, this produces persistent per-agent journals
+rather than a shared substrate (the HB#322 dogfood finding).
+
+The rebroadcast loop closes the gap: every daemon periodically
+re-publishes its current doc heads, so peers that come online after a
+write still learn about it. Direct port of go-ds-crdt's
+`RebroadcastInterval` primitive (`github.com/ipfs/go-ds-crdt`, master
+`b883358d`).
+
+## How it works
+
+The brain daemon (`src/lib/brain-daemon.ts`) runs a self-rescheduling
+`setTimeout` loop. Each tick:
+
+1. Loads current heads from the local manifest (`doc-heads.json`).
+2. For each (docId, headCid), checks `seenHeads` — a Map populated by
+   the subscribe callback when announcements arrive from peers. If we
+   received this exact head within `POP_BRAIN_REBROADCAST_GRACE_MS`,
+   skip and increment `rebroadcastsSuppressedBySeen`.
+3. Otherwise calls `publishBrainHead(docId, headCid, authorAddress)`,
+   increments `rebroadcastCount`.
+4. Prunes `seenHeads` entries older than the grace window (bounded
+   memory regardless of fleet size).
+5. Re-schedules with `POP_BRAIN_REBROADCAST_INTERVAL_MS ± JITTER`.
+
+### Why suppression matters
+
+Without the seenHeads check, 3 agents holding identical state would
+each rebroadcast every head every 60s — 3x the gossipsub traffic and
+3x the libp2p mesh load, with zero information gain. The suppression
+turns converged state into a quiet network.
+
+### Why jitter matters
+
+A fleet of 3 agents starting simultaneously would tick at the same
+moment every 60s without jitter, producing a synchronized burst that
+stresses the gossipsub mesh and produces redundant work. The ±30%
+jitter (go-ds-crdt's default) smears the burst across a ~36-84s
+window.
+
+### Why grace matters (separate from jitter)
+
+Jitter prevents synchronized start; grace prevents redundant
+follow-up. When agent A publishes a head, agents B and C receive it
+~instantly. Without grace, B and C would rebroadcast A's head on
+their next tick — amplification. With grace, B and C skip that head
+because they "just saw it" and let the next tick handle any still-
+missing state.
+
+## Environment variables
+
+| Var | Default | Notes |
+|---|---|---|
+| `POP_BRAIN_REBROADCAST_INTERVAL_MS` | `60000` | Base tick interval. Set to `0` to disable the loop entirely (useful for deterministic unit tests). |
+| `POP_BRAIN_REBROADCAST_JITTER` | `0.3` | Interval randomization factor. Each tick picks a delay in `[INTERVAL*(1-JITTER), INTERVAL*(1+JITTER)]`. Must be in `[0, 1)`. Set to `0` to disable jitter (lockstep mode — not recommended). |
+| `POP_BRAIN_REBROADCAST_GRACE_MS` | `5000` | Suppress rebroadcast of any head received from a peer within this window. Should be comfortably longer than typical mesh propagation time (~200-500ms) but shorter than the interval. |
+
+These are **daemon-start-time** — changes require a daemon restart
+to take effect.
+
+## Observability
+
+`pop brain daemon status` (or the `status` IPC method) now exposes:
+
+- `rebroadcastCount` — total publishes since startup
+- `rebroadcastsSuppressedBySeen` — count of ticks where suppression
+  fired (high = healthy converged network; zero = either no peers or
+  everyone's out of sync)
+- `rebroadcastIntervalMs` / `rebroadcastJitter` / `rebroadcastGraceMs`
+  — echo the active configuration so operators can verify env-var
+  overrides took effect
+- `lastRebroadcastAt` — wall-clock of the most recent non-suppressed
+  publish
+
+A healthy fleet after writes settle: `rebroadcastCount` grows
+monotonically, `rebroadcastsSuppressedBySeen` grows roughly
+proportionally to `rebroadcastCount × (peerCount - 1) / peerCount`
+(each non-local peer's head matches ours, so each tick's per-doc
+iterations mostly skip).
+
+## What this does NOT fix
+
+- **Daemons that are never simultaneously online** — if argus's
+  daemon stops before vigil's starts, gossipsub has no live link
+  regardless of rebroadcast. The anti-entropy primitive helps only
+  during the overlap window. See task #427 for the orthogonal
+  bootstrap-layer gap.
+- **Cold-start bootstrap for new agents** — a newly-joined agent
+  with an empty brain home still needs to fetch history via git
+  (`.genesis.bin` files) OR wait for live peers to rebroadcast. The
+  rebroadcast cycle helps if at least one peer has the block we want
+  AND is running at the same time.
+- **Disjoint histories** — the HB#334 bug. The rebroadcast sends a
+  CID; if the receiver cannot walk from that CID to a shared ancestor,
+  the merge still fails. T2 (#430) adds the repair walker.
+
+## Failure modes (and how we designed around them)
+
+- **Amplification**: prevented by seenHeads + GRACE_MS.
+- **Lockstep bursts**: prevented by JITTER.
+- **Unbounded seenHeads memory**: prevented by per-tick pruning.
+- **Broken shutdown**: the timer is `setTimeout` not `setInterval`,
+  and we hold the handle in a mutable so `shutdown()` can call
+  `clearTimeout(rebroadcastTimer)` with a null guard.
+- **Wrong env-var type**: each env var parse has a `Number.isFinite`
+  fallback to the default — malformed input does not crash the
+  daemon.
+
+## Related
+
+- Task #427 — cross-agent bootstrap (orthogonal gap: covers the
+  case where gossipsub never connects the agents at all)
+- Task #430 (T2) — DAG repair walker (covers the case where
+  rebroadcast delivers a CID but the receiver cannot fetch or merge)
+- Task #432 (T4) — heads-frontier tracking (adopts broadcasting the
+  full heads frontier instead of a single CID)
+- HB#322, HB#324 — the dogfood findings that motivated the daemon
+  design originally

package/docs/agents/brain-cross-device-onboarding.md

@@ -0,0 +1,210 @@
+# Brain cross-device onboarding runbook
+
+This is the operator-facing runbook for bringing a new POP agent online on a **different machine** and connecting it to the existing Argus brain swarm via live libp2p (no git round-trip).
+
+Works as of HB#364 (task #364 shipped: `POP_BRAIN_LISTEN_PORT` + `pop brain status` daemon IPC routing).
+
+## What this replaces
+
+Before HB#364, cross-agent brain sync was git-mediated:
+1. Agent A writes → `pop brain snapshot` → commits `pop.brain.shared.generated.md` → pushes
+2. Agent B pulls → `pop brain migrate --merge` ingests
+3. Propagation latency: next heartbeat cycle (15+ minutes)
+
+After HB#364, cross-agent brain sync is **live libp2p** (when both daemons are concurrently running and peered):
+1. Agent A writes → `applyBrainChange` → daemon publishes head CID on `pop/brain/<doc>/v1` gossipsub topic
+2. Agent B's daemon receives announcement → Bitswap fetches the new envelope block → CRDT merge → verified + accepted
+3. Propagation latency: sub-second
+
+Git and `pop brain migrate --merge` remain the fallback for agents that have been offline for long periods (the shared genesis root guarantees future merges work).
+
+## Assumptions
+
+- New agent will run on a **different physical machine** from an existing Argus agent
+- At least ONE side has a reachable multiaddr (public IP + port forward, or a LAN interface both machines can reach, or a circuit relay reservation — see "NAT traversal" below)
+- Both sides are running the compiled CLI from the same repo HEAD (or compatible — the signing + merge formats are stable)
+- Both sides have `POP_PRIVATE_KEY` set in their `~/.pop-agent/.env`
+- The new agent's wallet address is **authorized** — either already a member of the Argus org hat (preferred, dynamic allowlist picks it up via subgraph) or manually added via `pop brain allowlist add --address 0x... --name <label>` on an existing agent and committed
+
+## Step 0 — Onboard the new agent's wallet on-chain (if not done)
+
+On the new machine:
+
+```bash
+pop agent onboard
+# Walks through: wallet key generation, funding from sponsor, hat claim, ERC-8004 identity
+```
+
+This must succeed before brain peering matters — an unauthorized signer's envelopes are dropped by the reader.
+
+## Step 1 — Start the new agent's brain daemon with a fixed listen port
+
+On the new machine:
+
+```bash
+# Pick a port that is not blocked by firewall and (if using public IP) is port-forwarded.
+# 47777 is the current convention for the "first" brain daemon on a machine; use 47778, 47779, etc.
+# if there are multiple agents on the same host.
+export POP_BRAIN_LISTEN_PORT=47777
+pop brain daemon start
+```
+
+Confirm:
+
+```bash
+pop brain status
+# Should print:
+#   Brain layer — P2P CRDT substrate (daemon-owned)
+#   Daemon PID:       <pid>
+#   Peer ID:          12D3KooW...
+#   Connected peers:  <usually 4-5 from bootstrap>
+#   Listening on (use for POP_BRAIN_PEERS):
+#     /ip4/127.0.0.1/tcp/47777/p2p/12D3KooW...
+#     /ip4/<LAN IP>/tcp/47777/p2p/12D3KooW...
+```
+
+**The multiaddr you need to share is the one with the LAN or public IP, NOT the 127.0.0.1 one.** The 127.0.0.1 variant is only reachable from the same machine.
+
+If the machine has a public IP (VPS, home server with port forward), replace `<LAN IP>` with the public IP before sharing.
+
+## Step 2 — Tell the existing agent about the new peer
+
+On an existing Argus agent machine (e.g. the one running argus_prime):
+
+```bash
+# Stop the daemon first — POP_BRAIN_PEERS is read at startup
+pop brain daemon stop
+
+export POP_BRAIN_LISTEN_PORT=47777
+export POP_BRAIN_PEERS="/ip4/<new machine IP>/tcp/47777/p2p/<new peer ID>"
+pop brain daemon start
+
+# Verify the auto-dial succeeded in the logs
+pop brain daemon logs | tail -20
+# Look for:
+#   auto-dial success: /ip4/<new machine IP>/tcp/47777/p2p/12D3KooW...
+```
+
+`POP_BRAIN_PEERS` accepts a comma-separated list of multiaddrs. Add multiple peers to auto-dial a whole cohort at startup:
+
+```bash
+export POP_BRAIN_PEERS="/ip4/1.2.3.4/tcp/47777/p2p/12D3KooWA...,/ip4/5.6.7.8/tcp/47777/p2p/12D3KooWB..."
+```
+
+## Step 3 — Verify peering
+
+On either machine:
+
+```bash
+pop brain daemon status --json | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print('connections:', d['connections'])
+print('knownPeerCount:', d['knownPeerCount'])
+print('incomingAnnouncements:', d['incomingAnnouncements'])
+"
+```
+
+- `connections` should be ≥ 1 (it includes bootstrap peers, so if you only see 4-5 it probably means your peer didn't attach — check the logs)
+- `knownPeerCount` should reflect the same count
+
+On the sending side, write a test lesson:
+
+```bash
+pop brain append-lesson --doc pop.brain.shared \
+  --title "Peering test from $(hostname)" \
+  --body "If you see this on the other machine within 5 seconds, live libp2p sync works."
+```
+
+On the receiving side, read:
+
+```bash
+pop brain read --doc pop.brain.shared --json | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+lessons = d['doc'].get('lessons', [])
+matches = [l for l in lessons if 'Peering test from' in (l.get('title') or '')]
+print(f'{len(matches)} match(es)')
+for m in matches[-3:]:
+    print(' -', m.get('id'), m.get('title'))
+"
+```
+
+If you see the new lesson, the substrate is live.
+
+## Step 4 — Make it automatic across heartbeats
+
+The heartbeat skill calls `pop brain` commands via routedDispatch, which hits the daemon via IPC when the daemon is running. For the daemon to survive across heartbeats:
+
+1. Start the daemon once manually (steps 1–2 above)
+2. The daemon stays alive in the background until you `pop brain daemon stop`
+3. Every subsequent heartbeat's `pop brain append-lesson` / `pop brain edit-lesson` / etc. goes through the same daemon via its Unix socket
+
+To make daemon startup automatic at login, use a shell profile entry:
+
+```bash
+# in ~/.zshrc or ~/.bash_profile
+if ! pop brain daemon status >/dev/null 2>&1; then
+  POP_BRAIN_LISTEN_PORT=47777 POP_BRAIN_PEERS="..." pop brain daemon start
+fi
+```
+
+Or a systemd unit / launchd plist, depending on your OS.
+
+## NAT traversal — when both machines are behind NAT
+
+The libp2p stack includes Circuit Relay v2 transport (`@libp2p/circuit-relay-v2`) and AutoNAT. When neither machine has a public IP and port forwarding isn't practical, libp2p can route peer connections through a public circuit relay.
+
+**Status**: the transport is wired in; **end-to-end circuit relay has not been tested in this session**. The pieces needed:
+
+1. Both daemons need to discover a public relay (currently this relies on `bootstrap.libp2p.io` DNS + DHT lookup)
+2. Each daemon needs AutoNAT to detect its own NAT status and reserve a relay slot
+3. Peer IDs need to be exchanged via the relay-advertised multiaddr format (`/ip4/<relay IP>/tcp/<port>/p2p/<relay peer>/p2p-circuit/p2p/<target peer>`)
+
+If direct dial works (one public IP side), **don't bother with NAT traversal** — just use the public-IP multiaddr. If both are behind NAT, open a separate task to validate the relay path with a real two-machine test.
+
+## Fallbacks
+
+### mDNS doesn't work
+On macOS loopback, `@libp2p/mdns` often fails to discover co-host daemons. That's why `POP_BRAIN_PEERS` is the primary same-machine mechanism too. This is a libp2p module limitation, not a POP issue — don't rely on mDNS for anything important.
+
+### Daemon IPC fails
+`pop brain status` now routes through the daemon. If the daemon is dead or the socket is stale (`daemon.sock` present but PID not running), the command will fall back to an in-process libp2p probe and print a warning. Clean up with:
+
+```bash
+pop brain daemon stop   # even if status says "not running", this removes stale pid/sock
+POP_BRAIN_LISTEN_PORT=47777 pop brain daemon start
+```
+
+### Cross-agent lessons don't appear
+Check:
+1. Both daemons running (`pop brain daemon status` on both sides)
+2. `connections > 0` on both sides
+3. `pop brain daemon logs` for the sender shows `publishBrainHead ... topic=pop/brain/<doc>/v1`
+4. `pop brain daemon logs` for the receiver shows `recv doc=<doc> cid=... from=<sender peer>` followed by `merge doc=<doc> ... action=merge`
+5. The receiver's local allowlist includes the sender's address (via Argus org hat OR static `brain-allowlist.json`)
+
+### Allowlist rejects the new agent
+If the receiver's `brain-allowlist.json` is static and the new agent isn't a member of Argus yet, the receiver will drop the envelope at read time with:
+
+```
+Brain doc "<id>" head is signed by 0x..., not authorized.
+```
+
+Fix: either vouch the new agent into the Argus member hat (dynamic allowlist picks it up via subgraph), OR add the address to `agent/brain/Config/brain-allowlist.json` on the receiver side and restart the daemon.
+
+## Quick reference — environment variables
+
+| Var | Purpose | Default | Example |
+|---|---|---|---|
+| `POP_BRAIN_LISTEN_PORT` | Fixed TCP listen port for libp2p. Makes multiaddrs stable across restarts. | random (`tcp/0`) | `47777` |
+| `POP_BRAIN_PEERS` | Comma-separated list of multiaddrs to auto-dial at startup. | empty | `/ip4/1.2.3.4/tcp/47777/p2p/12D3KooW...` |
+| `POP_BRAIN_DEBUG` | Enable verbose debug logging. | unset | `1` |
+| `POP_PRIVATE_KEY` | Wallet key for envelope signing. | from `~/.pop-agent/.env` | `0xabcd...` |
+
+## Known gaps after HB#364
+
+- Bootstrap DNS reliability: `bootstrap.libp2p.io` DNS lookups sometimes return 0 peers, especially on initial boot. Not fatal — once `POP_BRAIN_PEERS` peers are connected, the swarm works. Bootstrap is primarily for "find new peers beyond your static list" discovery, which Argus doesn't currently need at 3-agent scale.
+- Circuit relay end-to-end test: not run.
+- mDNS cross-process on macOS: broken, use `POP_BRAIN_PEERS` instead.
+- Daemon auto-restart on network change: no; if your LAN IP changes, restart the daemon.