feat(m3): ledger query helpers + reporter banners + strategy decision sidecar

[suzuke]

Summary

Stacked on #10 (M3 PR 16 SubscriptionCLIBackend). Polish PR. Three focused, additive improvements landing as a single coherent PR per spec §1 M3 module table:

• StateStore extend — Ledger query helpers
• Reporter polish — Truth-in-labeling banners (single source of truth)
• SearchStrategy polish — Decision sidecar log + crucible postmortem --strategy-decisions

What's new

StateStore — Ledger query helpers (ledger.py)

TrialLedger.kept_path(node_id, *, include_self=True) -> list[AttemptNode]
TrialLedger.descendants_of(node_id) -> list[AttemptNode]
TrialLedger.find_by_outcome(outcome: str) -> list[AttemptNode]

• kept_path walks parent chain, filters to outcome=="keep". include_self=False drops the queried node from the result regardless of its outcome. Reviewer Q2 pin: no baked heuristics — caller controls semantics via the kwarg.
• descendants_of returns all transitive children, DFS-by-parent + siblings sorted by id. Iteration order matches _render_tree for consistency. Cycle defense via visited set.
• find_by_outcome exact-string filter, plain str for forward-compat with custom outcomes.

Reporter — Banner SSOT (reporter/_banners.py NEW)

Single source of truth for warning banner copy. Reviewer Q3 pin: both html_tree.py (static) and interactive.py (d3) import the same render_banners_html() helper. §INV-1 wording compliance — uses "degraded ACL" / "diagnostic only" / "do NOT constitute a containment claim", deliberately avoids "secure" / "isolated" / "no bypass observed in N trials" (no N to ground it).

Two banner triggers:

• isolation == "cli_subscription_unsandboxed" → unsandboxed banner
• compliance_report_path is None AND isolation set → stale-compliance banner

SearchStrategy — Decision sidecar (strategy_decisions.py NEW)

Reviewer Q4 pin: SIDECAR file (logs/run-<tag>/strategy-decisions.jsonl), NOT a new ledger event type. Why not ledger:

• Ledger is safety-critical (POSIX flock, single-writer, schema-versioned, seal HMAC); a schema bump invalidates parallel append safety per spec §4.2.
• Mixing safety-critical data with debug data violates separation of concerns.

Why not in-memory: lost on crash exactly when most needed.

@dataclass
class StrategyDecision:
    timestamp: str       # ISO-8601 UTC
    iteration: int
    kept_candidates: list[str]
    pruned_candidates: list[str]
    chosen_action: str   # e.g. "Continue", "BranchFrom", "Stop"
    rationale: str
    extras: dict[str, Any]  # adapter-specific

Orchestrator hook: _log_strategy_decision(sctx, action) runs immediately after strategy.decide(sctx) in _run_loop_serial. Best-effort — any failure is logged at DEBUG and never raises, so a logging hiccup never blocks the run loop.

CLI: crucible postmortem --tag X --strategy-decisions prints the recorded sequence.

AttemptNode schema additions (ledger.py)

isolation: Optional[str] = None          # truth-in-labeling tag
compliance_report_path: Optional[str] = None  # audit trail

Both default None for backward compat with M1a/M1b/M2 ledgers. Populated from AgentResult.backend_metadata via the new _extract_backend_metadata() helper in orchestrator.py, used at both AttemptNode construction sites.

Reviewer trail

Round	Verdict	Findings
1 (design)	ACCEPT	4 steers (Q2 helper signature, Q3 banner SSOT, Q4 sidecar not ledger, Q6 property assertion + edge cases) — all blocking-lite, none REJECT-level
2 (impl)	VERIFIED	All 4 steers landed correctly. Numbers accurate (third round in a row). Reviewer flagged bonus quality: proactive XSS test on banner content + _extract_backend_metadata helper reused at both AttemptNode construction sites (avoids drift). Deferred dedup pass for compare.py/html_tree.py inline walks confirmed correct judgment — patterns don't match new helper shapes.

Stats

• 1 commit (5365098)
• 8 files changed, +882 / -3 LOC
• 29 new tests in test_m3_polish.py
• Full suite: 2761 passed + 1 pre-existing failure (test_create_agent_unknown_raises — exists at PR 16 baseline) + 4 skipped. 0 regressions from PR 17.

Test plan

Q2 ledger helpers

• kept_path linear chain
• kept_path filters out discards
• kept_path(include_self=False) drops self
• kept_path root kept / root discard
• kept_path orphan node terminates cleanly (no infinite loop)
• descendants_of DFS order (matches _render_tree)
• descendants_of leaf returns []
• descendants_of cycle defense (large chain canary)
• find_by_outcome exact match + unknown returns []

Q3 banner SSOT

• No metadata = no output
• Unsandboxed banner renders correctly
• Stale-compliance banner gated on isolation set first
• Both renderers import same module (structural assertion)
• §INV-1 wording compliance (no "secure" / "no bypass observed in N")
• HTML escape on body text (defensive)

Q4 sidecar

• Round-trip: append then load yields equal records
• Missing file → empty list (reporter calls on every run dir)
• Malformed lines tolerated (mirror ledger reader)
• Sidecar filename matches documented constant

Q6 property assertion + integration

• N decide() calls → exactly N sidecar entries (Q6 counter assertion)
• Static reporter renders banner when isolation set
• Interactive reporter renders banner when isolation set
• Neither renders banner for normal (non-CLI) runs

AttemptNode schema

• isolation defaults to None
• compliance_report_path defaults to None
• Both can be set to specific tag values

Known limitations / non-blockers

• Inline-walk dedup deferred — reviewer round 1 suggested deduplicating walks in compare.py / html_tree.py after helpers landed. Inspection showed those walks (DFS-from-None-root with depth/orphan handling) don't match the new helper signatures (specific node_id queries). Forcing a dedup would create abstractions-for-abstraction's-sake. Defer until a concrete caller needs both shapes.
• Strategy decision logging is best-effort — failures are logged at DEBUG and swallowed. A logging hiccup never blocks the run loop.
• extras dict is free-form — adapter-specific details go here. No schema enforcement; reader uses .get() defaults.

🤖 Generated with Claude Code