feat(agent-003): implement full Market Monitor workflow mirroring AGENT-002

[brawlaphant]

Summary

Gives AGENT-003 Market Monitor the same full standalone TypeScript implementation that AGENT-002 Governance Analyst already has. AGENT-003's character definition was merged in #64; this PR adds the workflow code that runs against Regen Ledger.

• Lands in: `agent-003-market-monitor/`, `.github/workflows/ci.yml`
• Changes: new standalone AGENT-003 process implementing WF-MM-01 / WF-MM-02 / WF-MM-03 from `phase-2/2.2-agentic-workflows.md`, wired into the `agents` CI job for typecheck on every PR
• Validate: `cd agent-003-market-monitor && npm ci && npx tsc --noEmit`

Structure — mirrors AGENT-002

File	Purpose
`src/index.ts`	Banner, cycle runner, polling vs single-run
`src/config.ts`	Config + thresholds mirrored from the character
`src/types.ts`	Ecocredit marketplace types + per-workflow shapes
`src/ledger.ts`	LCD client for ecocredit + marketplace endpoints
`src/store.ts`	SQLite state: trades, anomaly dedupe, liquidity, retirements, executions
`src/ooda.ts`	Generic OODA executor (same shape as agent-002)
`src/monitor.ts`	Claude narrative layer — one function per workflow
`src/output.ts`	Console + optional Discord webhook dispatcher
`src/workflows/price-anomaly-detection.ts`	WF-MM-01
`src/workflows/liquidity-monitor.ts`	WF-MM-02
`src/workflows/retirement-tracking.ts`	WF-MM-03

Design decisions

1. Deterministic numbers, narrative-only LLM calls. All severity classification, z-score computation, liquidity health scoring, and demand index derivation happen locally in plain TypeScript. Claude is only invoked to write the report from those numbers. Keeps the agent cheap, reproducible, and auditable — and makes the hard parts trivially unit-testable in a follow-up PR.

2. Sell-order-as-trade proxy for the MVP. Until Ledger MCP exposes filled-trade events, the agent treats open sell orders as trade observations for the z-score baseline. An unusually high or low ask price is still a market structure signal worth surfacing, and the code path swaps cleanly once real trade events are available.

3. Batch-supply delta as retirement source for the MVP. WF-MM-03 reads `retired_amount` from each batch supply and aggregates per class. Capped at the 100 most recent batches per cycle so the agent doesn't hammer the LCD on a mainnet with thousands of historical batches. A follow-up PR will plug in a real `MsgRetire` tx-stream client.

4. Alert dedupe by (trade_id, severity). WF-MM-01 only alerts once per `(trade_id, severity)` tuple. A trade that later escalates from WARNING to CRITICAL still fires a new alert; a same-severity re-alert does not.

5. Thresholds single-sourced from the character. `config.market.*` mirrors the threshold constants exported from `agents/packages/agents/src/characters/market-monitor.ts`. The system prompt is interpolated from the same config so the deterministic pipeline and the narrative layer can never drift.

Layer boundary

This agent operates at Layer 1 only — read-only, informational output, cannot submit proposals, create/modify/cancel sell orders, or execute transactions. Matches the framework principle of starting with the lowest-risk, highest-value capability. Raising the automation layer is a separate governance decision.

Test plan

• `cd agent-003-market-monitor && npm ci && npx tsc --noEmit` — passes locally on Node 22
• CI `agents` job runs `npx tsc --noEmit` for the new agent
• CI `agents` job runs the existing typecheck for `agents/` and `agent-002-governance-analyst/` unchanged
• Manual smoke test against `https://regen.api.chandrastation.com\` (WF-MM-01 / 02 / 03 each run one cycle without throwing)

Scope not included (deliberate follow-ups)

• Unit tests for `median`, `stddev`, `classifyAnomaly`, `scoreHealth`, `computeDemandIndex` — planned as a separate test-only PR so this PR stays a single-concern "add the agent" change
• Real MsgRetire tx-stream client for WF-MM-03 (see design decision docs: Add semantic data and claims engine integration specifications #3)
• Real filled-trade source for WF-MM-01 (see design decision docs: Add phased agentic governance framework with PACTO/OPAL alignment #2)
• WF-MM-04 Curation Quality Monitoring — deliberately scoped to a future release in the character definition and unchanged here

Refs `phase-2/2.2-agentic-workflows.md` §WF-MM-01, §WF-MM-02, §WF-MM-03
Refs `agents/packages/agents/src/characters/market-monitor.ts` (#64)

[gemini-code-assist]

Code Review

This pull request introduces AGENT-003, a market monitor for the Regen ecocredit marketplace. It implements three OODA-based workflows: price anomaly detection, liquidity monitoring, and retirement tracking, using a standalone Node.js process with SQLite for state and Claude for narrative reporting. Feedback focused on correcting statistical inconsistencies in Z-score calculations, improving the accuracy of retirement tracking by using deltas instead of cumulative totals, handling non-USD denominations, and addressing potential issues with pagination, concurrency, and overlapping execution cycles.

[gemini-code-assist]

The current implementation aggregates the absolute retired_amount from the top 100 batches. Since retired_amount is a cumulative total for each batch, the resulting totalRetired and demandIndex reflect the static state of those batches rather than recent retirement activity. Furthermore, as batches fall out of the "top 100" list, the aggregated total will fluctuate based on batch creation frequency rather than actual demand. To accurately track "patterns" and "demand signals" as intended by WF-MM-03, the agent should compute the delta between the current and previously observed retirement amounts.

[gemini-code-assist]

The Z-score calculation is statistically inconsistent because it uses the classMedian as the center but divides by the classStd (which is calculated relative to the classMean). For a standard Z-score, you should use (value - mean) / stddev. Alternatively, for a more robust "Modified Z-score", you could use the Median Absolute Deviation (MAD). This inconsistency also applies to the zBatch calculation on line 177.

Suggested change

	const zClass = classStd > 0 ? (trade.pricePerCredit - classMedian) / classStd : 0;
	const zClass = classStd > 0 ? (trade.pricePerCredit - classMean) / classStd : 0;

[gemini-code-assist]

Similar to the zClass calculation, the zBatch calculation is statistically inconsistent as it uses batchMedian with batchStd (derived from batchMean).

Suggested change

	const zBatch = batchStd > 0 ? (trade.pricePerCredit - batchMedian) / batchStd : 0;
	const zBatch = batchStd > 0 ? (trade.pricePerCredit - batchMean) / batchStd : 0;

[gemini-code-assist]

The usdPerAskUnit is hardcoded to 1 for all denominations. This will result in incorrect price calculations and false anomaly alerts for any sell orders listed in non-USD denominations (e.g., REGEN tokens). While the PR notes this as an MVP limitation, it is recommended to at least skip orders with unknown denominations to prevent polluting the baseline with incorrect data.

Suggested change

	const usdPerAskUnit = isUsdStableDenom(order.ask_denom) ? 1 : 1;
	const pricePerCredit = (ask * usdPerAskUnit) / qty;
	const usdPerAskUnit = isUsdStableDenom(order.ask_denom) ? 1 : null;
	if (usdPerAskUnit === null) return null;
	const pricePerCredit = (ask * usdPerAskUnit) / qty;

[gemini-code-assist]

Using setInterval can lead to overlapping execution cycles if a cycle takes longer than the polling interval (e.g., due to network latency or slow LLM responses). It is safer to use a recursive setTimeout pattern to ensure that the next cycle only starts after the previous one has finished.

Suggested change

	const interval = setInterval(() => {
	runCycle(ledger).catch((err) =>
	console.error(`Cycle failed:`, err)
	);
	}, config.pollIntervalMs);
	const shutdown = () => {
	console.log("\nShutting down gracefully...");
	clearInterval(interval);
	store.close();
	process.exit(0);
	};
	let timeoutId: NodeJS.Timeout;
	const runNext = () => {
	runCycle(ledger)
	.catch((err) => console.error(`Cycle failed:`, err))
	.finally(() => {
	timeoutId = setTimeout(runNext, config.pollIntervalMs);
	});
	};
	runNext();
	const shutdown = () => {
	console.log("\nShutting down gracefully...");
	clearTimeout(timeoutId);
	store.close();
	process.exit(0);
	};

[gemini-code-assist]

The getCreditClasses method uses a hardcoded pagination limit of 200 without iterating through subsequent pages. As the number of credit classes on the Regen Ledger grows, the agent will only monitor the oldest 200 classes, potentially missing significant market activity in newer classes.

[gemini-code-assist]

Firing 100 concurrent requests to the LCD endpoint via Promise.all may trigger rate limits or cause timeouts on public infrastructure. Consider processing these in smaller batches or using a concurrency-limited pool.

[brawlaphant]

Superseded by #103 — the real MsgRetire tx-stream implementation fully replaces the batch-supply-delta approach here, and all four non-delta fixes from this PR's gemini fixup commit (LedgerClient pagination walk, liquidity-monitor sort optimization + USD-stable filter, setInterval→setTimeout main loop, z-score numerator) have been ported forward onto #103 in commit 63113f7. Closing as superseded.