Plan product development after pivot

CLAUDE.md

@@ -4,7 +4,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What is Igor
 
-Igor is a decentralized runtime for autonomous, survivable software agents. Agents are WASM binaries that checkpoint their state, migrate between peer nodes over libp2p, and pay for execution from internal budgets. Phases 2–4 are complete, Phase 5 (Hardening) is complete — agents run, checkpoint, migrate, resume, meter cost, enforce capability membranes, replay-verify, support multi-node chain migration, sign checkpoint lineage, recover from migration failures, and enforce lease-based authority. Task 15 (Permissionless Hardening) is next. Research-stage, not production-ready.
+Igor is the runtime for portable, immortal software agents. The checkpoint file IS the agent — copy it anywhere, run `igord resume`, it continues exactly where it left off. Every agent has a DID identity (`did:key:z6Mk...`) derived from its Ed25519 keypair, and a signed checkpoint lineage providing cryptographic proof of its entire life history. No infrastructure lock-in.
+
+**Product Phase 1 (Portable Sovereign Agent)** is complete: DID identity, `igord run/resume/verify/inspect` subcommands, checkpoint history archival, lineage chain verification, heartbeat demo agent, portable demo script. Built on a research foundation (Phases 2–5) of WASM sandboxing, P2P migration, budget metering, replay verification, and signed checkpoint lineage.
 
 **Stack:** Go 1.25 · wazero (pure Go WASM, no CGo) · libp2p-go · TinyGo (agent compilation)
 
@@ -14,22 +16,31 @@ Igor is a decentralized runtime for autonomous, survivable software agents. Agen
 make bootstrap       # Install toolchain (Go, golangci-lint, goimports, TinyGo)
 make build           # Build igord → bin/igord
 make agent           # Build example WASM agent → agents/example/agent.wasm
+make agent-heartbeat # Build heartbeat WASM agent → agents/heartbeat/agent.wasm
 make test            # Run tests: go test -v ./...
 make lint            # golangci-lint (5m timeout)
 make vet             # go vet
 make fmt             # gofmt + goimports
 make check           # fmt-check + vet + lint + test (same as precommit)
 make run-agent       # Build + run example agent with budget 1.0
 make demo            # Build + run bridge reconciliation demo
+make demo-portable   # Build + run portable agent demo (run → stop → copy → resume → verify)
 make clean           # Remove bin/, checkpoints/, agent.wasm
 ```
 
 Run a single test: `go test -v -run TestName ./internal/agent/...`
 
-Run the node manually:
+Run manually (new subcommands):
+```bash
+./bin/igord run --budget 1.0 agents/heartbeat/agent.wasm
+./bin/igord resume checkpoints/heartbeat/checkpoint.ckpt agents/heartbeat/agent.wasm
+./bin/igord verify checkpoints/heartbeat/history/
+./bin/igord inspect checkpoints/heartbeat/checkpoint.ckpt
+```
+
+Legacy mode (P2P/migration):
 ```bash
 ./bin/igord --run-agent agents/example/agent.wasm --budget 10.0
-./bin/igord --run-agent agents/example/agent.wasm --budget 10.0 --manifest agents/example/agent.manifest.json
 ./bin/igord --migrate-agent local-agent --to /ip4/127.0.0.1/tcp/4002/p2p/<peerID> --wasm agent.wasm
 ```
 
@@ -43,34 +54,44 @@ Current version is v0x04 (209-byte header). Supports reading v0x02 (57 bytes) an
 
 `[version: 1 byte (0x04)][budget: 8 bytes int64 microcents][pricePerSecond: 8 bytes int64 microcents][tickNumber: 8 bytes uint64][wasmHash: 32 bytes SHA-256][majorVersion: 8 bytes uint64][leaseGeneration: 8 bytes uint64][leaseExpiry: 8 bytes uint64][prevHash: 32 bytes SHA-256][agentPubKey: 32 bytes Ed25519][signature: 64 bytes Ed25519][agent state: N bytes]`
 
-Header is 209 bytes. Budget uses int64 microcents (1 currency unit = 1,000,000 microcents). WASM hash binds the checkpoint to the binary that created it; mismatch on resume is rejected. prevHash chains checkpoints into a tamper-evident lineage. Signature covers everything except the signature field itself.
+Header is 209 bytes. Budget uses int64 microcents (1 currency unit = 1,000,000 microcents). WASM hash binds the checkpoint to the binary that created it; mismatch on resume is rejected. prevHash chains checkpoints into a tamper-evident lineage. Signature covers everything except the signature field itself. AgentPubKey encodes as DID: `did:key:z` + base58btc(0xed01 + pubkey).
 
-Atomic writes via temp file → fsync → rename.
+Atomic writes via temp file → fsync → rename. Every checkpoint is also archived to `history/{agentID}/{tickNumber}.ckpt` for lineage verification.
 
 ### Key packages
-- `cmd/igord/` — CLI entry point, flag parsing, tick loop orchestration
+- `cmd/igord/` — CLI entry point, subcommand dispatch (`run`, `resume`, `verify`, `inspect`), tick loop
 - `internal/agent/` — Agent lifecycle: load WASM, init, tick, checkpoint, resume, budget deduction
 - `internal/runtime/` — wazero sandbox: 64MB memory limit, WASI with fs/net disabled
 - `internal/hostcall/` — `igor` host module: clock, rand, log, wallet hostcall implementations
+- `internal/inspector/` — Checkpoint inspection and lineage chain verification (`chain.go`: `VerifyChain`)
+- `internal/storage/` — `CheckpointProvider` interface + filesystem impl + checkpoint history archival
 - `internal/eventlog/` — Per-tick observation event log for deterministic replay
 - `internal/replay/` — Deterministic replay verification: single-tick (`ReplayTick`) and chain (`ReplayChain`)
 - `internal/runner/` — Tick loop orchestration, divergence escalation policies, lease management
 - `internal/authority/` — Lease-based authority epochs, state machine (Active→Expired→RecoveryRequired)
 - `internal/migration/` — P2P migration over libp2p stream protocol `/igor/migrate/1.0.0`, retry with backoff
 - `internal/registry/` — Peer registry with health tracking for migration target selection
-- `internal/storage/` — `CheckpointProvider` interface + filesystem implementation
 - `internal/p2p/` — libp2p host setup, bootstrap peers, protocol handlers
+- `pkg/identity/` — Agent Ed25519 keypair management, DID encoding (`did:key:z6Mk...`), DID parsing
+- `pkg/lineage/` — Signed checkpoint types, content hashing, signature verification
 - `pkg/manifest/` — Capability manifest parsing and validation
 - `pkg/protocol/` — Message types: `AgentPackage`, `AgentTransfer`, `AgentStarted`
 - `pkg/receipt/` — Payment receipt data structure, Ed25519 signing, binary serialization
-- `pkg/identity/` — Agent Ed25519 keypair management for signed checkpoint lineage
-- `pkg/lineage/` — Signed checkpoint types, content hashing, signature verification
 - `sdk/igor/` — Agent SDK: hostcall wrappers (ClockNow, RandBytes, Log, WalletBalance), lifecycle plumbing (Agent interface), Encoder/Decoder with Raw/FixedBytes/ReadInto for checkpoint serialization
+- `agents/heartbeat/` — Demo agent: logs heartbeat with tick count and age, milestones every 10 ticks
+- `agents/example/` — Original demo agent (Survivor) from research phases
+- `scripts/demo-portable.sh` — End-to-end portable agent demo
 
 ### Migration flow
 Source checkpoints → packages (WASM + checkpoint + budget) → transfers over libp2p → target instantiates + resumes → target confirms → source terminates + deletes local checkpoint. Single-instance invariant maintained throughout. Failures classified as retriable/fatal/ambiguous; ambiguous transfers enter RECOVERY_REQUIRED state (EI-6). Retry with exponential backoff; peer registry tracks health for target selection.
 
-### Key CLI flags
+### CLI subcommands (Product Phase 1)
+- `igord run [flags] <agent.wasm>` — run agent with new identity (`--budget`, `--checkpoint-dir`, `--agent-id`)
+- `igord resume <checkpoint.ckpt> <agent.wasm>` — resume agent from checkpoint file
+- `igord verify <history-dir>` — verify checkpoint lineage chain
+- `igord inspect <checkpoint.ckpt>` — display checkpoint details with DID identity
+
+### Legacy CLI flags (research/P2P mode)
 - `--replay-mode off|periodic|on-migrate|full` — when to run replay verification (default: full)
 - `--replay-on-divergence log|pause|intensify|migrate` — escalation policy on divergence (default: log)
 - `--verify-interval N` — ticks between verification passes (default: 5)

Makefile

@@ -1,11 +1,12 @@
-.PHONY: help bootstrap build clean test lint vet fmt fmt-check tidy agent agent-reconciliation run-agent demo gh-check gh-metadata gh-release
+.PHONY: help bootstrap build clean test lint vet fmt fmt-check tidy agent agent-heartbeat agent-reconciliation run-agent demo demo-portable gh-check gh-metadata gh-release
 
 .DEFAULT_GOAL := help
 
 # Build configuration
 BINARY_NAME := igord
 BINARY_DIR := bin
 AGENT_DIR := agents/example
+HEARTBEAT_AGENT_DIR := agents/heartbeat
 RECONCILIATION_AGENT_DIR := agents/reconciliation
 
 # Go commands
@@ -45,6 +46,7 @@ clean: ## Remove build artifacts
 	rm -rf checkpoints
 	rm -f agents/example/agent.wasm
 	rm -f agents/example/agent.wasm.checkpoint
+	rm -f agents/heartbeat/agent.wasm
 	rm -f agents/reconciliation/agent.wasm
 	@echo "Clean complete"
 
@@ -96,6 +98,13 @@ run-agent: build agent ## Build and run example agent locally
 	@echo "Running agent with default budget (1.0)..."
 	./$(BINARY_DIR)/$(BINARY_NAME) --run-agent $(AGENT_DIR)/agent.wasm --budget 1.0
 
+agent-heartbeat: ## Build heartbeat demo agent WASM
+	@echo "Building heartbeat agent..."
+	@which tinygo > /dev/null || \
+		(echo "tinygo not found. See docs/governance/DEVELOPMENT.md for installation" && exit 1)
+	cd $(HEARTBEAT_AGENT_DIR) && $(MAKE) build
+	@echo "Agent built: $(HEARTBEAT_AGENT_DIR)/agent.wasm"
+
 agent-reconciliation: ## Build reconciliation agent WASM
 	@echo "Building reconciliation agent..."
 	@which tinygo > /dev/null || \
@@ -110,6 +119,11 @@ demo: build agent-reconciliation ## Build and run reconciliation demo
 	@echo "Running Bridge Reconciliation Demo..."
 	./$(BINARY_DIR)/demo-reconciliation --wasm $(RECONCILIATION_AGENT_DIR)/agent.wasm
 
+demo-portable: build agent-heartbeat ## Run the portable agent demo (run, stop, resume, verify)
+	@echo "Running Portable Agent Demo..."
+	@chmod +x scripts/demo-portable.sh
+	@./scripts/demo-portable.sh
+
 check: fmt-check vet lint test ## Run all checks (formatting, vet, lint, tests)
 	@echo "All checks passed"