docs + refactor: fix audit inconsistencies, decouple product from research packages (#26)

* feat(sdk): add effect lifecycle model and treasury sentinel demo agent

The effect model makes crash-safe side effects a runtime primitive.
IntentState machine: Recorded → InFlight → Confirmed, with the "resume
rule" (InFlight → Unresolved on Unmarshal) for safe crash recovery.
Treasury sentinel agent demonstrates the pattern end-to-end.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: fix 10 documentation inconsistencies found in audit

- Fix tick timeout 100ms → 15s across 4 files (matches config.TickTimeout)
- Fix igord resume CLI syntax (positional → --checkpoint/--wasm flags)
- Add HTTP hostcall documentation to HOSTCALL_ABI.md
- Fix IMPLEMENTATION_STATUS.md: flag attribution (igord-lab not igord),
  add HTTP/effects/pricewatcher/sentinel entries, fix stale claims
- Update ROADMAP.md Phase 2 with completed items and current status
- Fix stale phase references and lease version (v0x03 → v0x04)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor(agent): decouple product binary from research-only packages

Break the transitive dependency chain that pulled authority and config
packages into the product igord binary:

- Extract DefaultTickTimeout (15s) into internal/agent, replacing
  config.TickTimeout usage in the product path
- Define EpochData struct in internal/agent to replace authority.Epoch
  in checkpoint headers; Instance.Lease becomes `any` with LeaseInfo
  interface for checkpoint building
- Extract duplicated loadOrGenerateIdentity into pkg/identity/loader.go
  with a minimal Store interface
- Move research agents (example, reconciliation) under agents/research/
- Move cmd/demo-reconciliation into agents/research/reconciliation/cmd/demo/
- Update Makefile, CLAUDE.md, and all doc references for new paths

Verified: `go list -deps ./cmd/igord/ | grep -E 'authority|config'`
returns nothing — product binary is fully decoupled.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: set LICENSE copyright to Janko Simonovic

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(agent): address PR review — checkpoint-before-execute and unmarshal bounds check

- Sentinel: return false (standard 1s tick) after recording a refill
  intent so the runtime persists a checkpoint before executeRefill runs.
  Previously returned true (10ms fast tick), risking intent loss on crash.
- EffectLog.Unmarshal: add bounds check before reading state byte to
  prevent panic on truncated effect-log payloads during resume.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: simonovic86

CLAUDE.md

@@ -15,9 +15,10 @@ Igor is the runtime for portable, immortal software agents. The checkpoint file
 ```bash
 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              # Build example WASM agent → agents/research/example/agent.wasm
 make agent-heartbeat    # Build heartbeat WASM agent → agents/heartbeat/agent.wasm
 make agent-pricewatcher # Build price watcher WASM agent → agents/pricewatcher/agent.wasm
+make agent-sentinel     # Build treasury sentinel WASM agent → agents/sentinel/agent.wasm
 make test            # Run tests: go test -v ./...
 make lint            # golangci-lint (5m timeout)
 make vet             # go vet
@@ -27,6 +28,7 @@ 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 demo-pricewatcher # Build + run price watcher demo (fetch prices → stop → resume → verify)
+make demo-sentinel     # Build + run treasury sentinel demo (effect lifecycle → crash → reconcile)
 make clean           # Remove bin/, checkpoints/, agent.wasm
 ```
 
@@ -35,14 +37,14 @@ Run a single test: `go test -v -run TestName ./internal/agent/...`
 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 resume --checkpoint checkpoints/heartbeat/checkpoint.ckpt --wasm 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/research/example/agent.wasm --budget 10.0
 ./bin/igord --migrate-agent local-agent --to /ip4/127.0.0.1/tcp/4002/p2p/<peerID> --wasm agent.wasm
 ```
 
@@ -79,18 +81,21 @@ Atomic writes via temp file → fsync → rename. Every checkpoint is also archi
 - `pkg/manifest/` — Capability manifest parsing and validation
 - `pkg/protocol/` — Message types: `AgentPackage`, `AgentTransfer`, `AgentStarted`
 - `pkg/receipt/` — Payment receipt data structure, Ed25519 signing, binary serialization
-- `sdk/igor/` — Agent SDK: hostcall wrappers (ClockNow, RandBytes, Log, WalletBalance), lifecycle plumbing (Agent interface), Encoder/Decoder with Raw/FixedBytes/ReadInto for checkpoint serialization
+- `sdk/igor/` — Agent SDK: hostcall wrappers (ClockNow, RandBytes, Log, WalletBalance), lifecycle plumbing (Agent interface), Encoder/Decoder with Raw/FixedBytes/ReadInto for checkpoint serialization, EffectLog for intent tracking across checkpoint/resume
+- `sdk/igor/effects.go` — Effect lifecycle primitives: EffectLog, IntentState (Recorded→InFlight→Confirmed/Unresolved→Compensated), the resume rule (InFlight→Unresolved on Unmarshal)
 - `agents/heartbeat/` — Demo agent: logs heartbeat with tick count and age, milestones every 10 ticks
 - `agents/pricewatcher/` — Demo agent: fetches BTC/ETH prices from CoinGecko, tracks high/low/latest across checkpoint/resume
-- `agents/example/` — Original demo agent (Survivor) from research phases
+- `agents/sentinel/` — Treasury sentinel: monitors simulated treasury balance, triggers refills with effect-safe intent tracking, demonstrates crash recovery and reconciliation
+- `agents/research/example/` — Original demo agent (Survivor) from research phases
+- `agents/research/reconciliation/` — Bridge reconciliation demo agent (research phase)
 - `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.
 
 ### 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 resume --checkpoint <path> --wasm <path>` — resume agent from checkpoint file
 - `igord verify <history-dir>` — verify checkpoint lineage chain
 - `igord inspect <checkpoint.ckpt>` — display checkpoint details with DID identity
 

LICENSE

@@ -186,7 +186,7 @@
       "Refer to the LICENSE file" or similar statement added to each
       source file to indicate the file is part of the licensed work.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2025 Janko Simonovic
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

Makefile

@@ -1,14 +1,15 @@
-.PHONY: help bootstrap build build-lab clean test lint vet fmt fmt-check tidy agent agent-heartbeat agent-reconciliation agent-pricewatcher run-agent demo demo-portable demo-pricewatcher gh-check gh-metadata gh-release
+.PHONY: help bootstrap build build-lab clean test lint vet fmt fmt-check tidy agent agent-heartbeat agent-reconciliation agent-pricewatcher agent-sentinel run-agent demo demo-portable demo-pricewatcher demo-sentinel gh-check gh-metadata gh-release
 
 .DEFAULT_GOAL := help
 
 # Build configuration
 BINARY_NAME := igord
 BINARY_DIR := bin
-AGENT_DIR := agents/example
+AGENT_DIR := agents/research/example
 HEARTBEAT_AGENT_DIR := agents/heartbeat
-RECONCILIATION_AGENT_DIR := agents/reconciliation
+RECONCILIATION_AGENT_DIR := agents/research/reconciliation
 PRICEWATCHER_AGENT_DIR := agents/pricewatcher
+SENTINEL_AGENT_DIR := agents/sentinel
 
 # Go commands
 GOCMD := go
@@ -51,11 +52,12 @@ clean: ## Remove build artifacts
 	$(GOCLEAN)
 	rm -rf $(BINARY_DIR)
 	rm -rf checkpoints
-	rm -f agents/example/agent.wasm
-	rm -f agents/example/agent.wasm.checkpoint
+	rm -f agents/research/example/agent.wasm
+	rm -f agents/research/example/agent.wasm.checkpoint
 	rm -f agents/heartbeat/agent.wasm
-	rm -f agents/reconciliation/agent.wasm
+	rm -f agents/research/reconciliation/agent.wasm
 	rm -f agents/pricewatcher/agent.wasm
+	rm -f agents/sentinel/agent.wasm
 	@echo "Clean complete"
 
 test: ## Run tests (with race detector)
@@ -127,10 +129,17 @@ agent-pricewatcher: ## Build price watcher demo agent WASM
 	cd $(PRICEWATCHER_AGENT_DIR) && $(MAKE) build
 	@echo "Agent built: $(PRICEWATCHER_AGENT_DIR)/agent.wasm"
 
+agent-sentinel: ## Build treasury sentinel demo agent WASM
+	@echo "Building sentinel agent..."
+	@which tinygo > /dev/null || \
+		(echo "tinygo not found. See docs/governance/DEVELOPMENT.md for installation" && exit 1)
+	cd $(SENTINEL_AGENT_DIR) && $(MAKE) build
+	@echo "Agent built: $(SENTINEL_AGENT_DIR)/agent.wasm"
+
 demo: build agent-reconciliation ## Build and run reconciliation demo
 	@echo "Building demo runner..."
 	@mkdir -p $(BINARY_DIR)
-	$(GOBUILD) -o $(BINARY_DIR)/demo-reconciliation ./cmd/demo-reconciliation
+	$(GOBUILD) -o $(BINARY_DIR)/demo-reconciliation ./agents/research/reconciliation/cmd/demo
 	@echo "Running Bridge Reconciliation Demo..."
 	./$(BINARY_DIR)/demo-reconciliation --wasm $(RECONCILIATION_AGENT_DIR)/agent.wasm
 
@@ -144,6 +153,11 @@ demo-pricewatcher: build agent-pricewatcher ## Run the price watcher demo (fetch
 	@chmod +x scripts/demo-pricewatcher.sh
 	@./scripts/demo-pricewatcher.sh
 
+demo-sentinel: build agent-sentinel ## Run the treasury sentinel demo (effect lifecycle, crash recovery)
+	@echo "Running Treasury Sentinel Demo..."
+	@chmod +x scripts/demo-sentinel.sh
+	@./scripts/demo-sentinel.sh
+
 check: fmt-check vet lint test ## Run all checks (formatting, vet, lint, tests)
 	@echo "All checks passed"
 

agents/reconciliation/go.mod

@@ -68,17 +68,17 @@ make agent    # from repo root
 
 ```bash
 make run-agent                    # default budget 1.0
-./bin/igord --run-agent agents/example/agent.wasm --budget 10.0
+./bin/igord --run-agent agents/research/example/agent.wasm --budget 10.0
 ```
 
 ## Demonstrating Survival
 
 ```bash
 # Start the agent
-./bin/igord --run-agent agents/example/agent.wasm --budget 10.0
+./bin/igord --run-agent agents/research/example/agent.wasm --budget 10.0
 
 # Let it tick a few times, then Ctrl-C (checkpoints on shutdown)
 
 # Restart — it resumes from checkpoint, tick count and age continue
-./bin/igord --run-agent agents/example/agent.wasm --budget 10.0
+./bin/igord --run-agent agents/research/example/agent.wasm --budget 10.0
 ```

agents/example/Makefile agents/research/example/Makefileagents/example/Makefile renamed to agents/research/example/Makefile

@@ -0,0 +1,7 @@
+module github.com/simonovic86/igor/agents/research/example
+
+go 1.24
+
+require github.com/simonovic86/igor/sdk/igor v0.0.0
+
+replace github.com/simonovic86/igor/sdk/igor => ../../../sdk/igor