feat(sl-hunting): v4e knowledge + session-state durability fix

[DoRmAmMu1997]

Distils Intraday Hunter's 11 Aug 2026 live session (_JXirKMmI58) into the SL Hunting agent's knowledge. Unlike every prior addendum, this session is a loss ? which is why it is worth encoding.

The lesson

He named the disqualifying fact himself, twice, before entering:

"Around here neither the BUYER's stop losses are available nor the SELLER's."

"Here not many traders were seated."

He then traded a forecast of who would arrive ? a sharp drop tempts intraday sellers in, so the market should rise to take them out ? and the selling simply continued.

Hunting inventory that exists is the strategy. Predicting inventory that might arrive is a weaker activity wearing the same vocabulary. When nobody is seated on either side, the output is HOLD.

Knowledge changes (all prose)

• OPENING_DRIVE ? WHICH CROWD THE OPEN RECRUITS DECIDES HOW BIG THE TRAP IS: a gap-down recruits positional sellers who hold overnight; a flat open recruits intraday sellers only, so the same-shaped trap is smaller and perishable. A genuine advance on v4d, independent of the outcome. Plus A FORECAST OF WHO WILL ARRIVE IS NOT EVIDENCE OF WHO IS SEATED and A SHARP FIRST SLIDE BAITS; A SLOW ONE MEANS IT.
• RISK ? NAME THE LAST POINT, NOT ONLY THE STOP and DISCIPLINE IS ASYMMETRIC BETWEEN WINNERS AND LOSERS.

The sharp-slide rule ships as a weak prior with its own counter-example attached ? it is the read that lost him the session, so it is recorded as a tie-breaker and explicitly barred from being a trade premise.

Prompt 96,627 ? 101,087 chars (headroom 18,913).

Tests

Two markers. The second is a drift guard asserting the forecasting rule still resolves to HOLD and still reconciles with v4c's MANUFACTURES MORE, so a later edit cannot quietly turn it into a licence to predict a crowd into existence.

Our agent on the same session

The doc addendum records it: the agent was SHORT all morning ? directionally right where IH was wrong ? and still lost more than any other strategy, because it took four short entries in 47 minutes and released three on premise-stall judgements rather than stops (two held 1 and 2 minutes; a 24400-target trade was let go at 24469?24492 having never been stopped).

That is the inverse of the failure v3y guards against. It is flagged as a lessons-loop candidate, not encoded as IH knowledge, because it is a property of our agent and not of the method.

P&L is marked provisional ? the runner was still live at 13:07 when this was written. SL Hunting's ?2,647.75 cross-checks exactly against its own Result summary; note MIRROR EXIT lines do not contain | EXIT , which under-counted the agent by 948.00 on a first pass.

Gates

SL Hunting pytest 173 passed ? full pytest 1136 passed ? ruff clean.

---

Bugfix: session state was stalling trading threads

41a78f8 ? unrelated to the knowledge work above, but found by running it.

The crash-durable session state added in #115 rewrote the whole JSON document with fsync on every write, including the 30-second supervisor snapshot. The first live session with it (2026-08-11) measured 223 writes over the 250 ms warning threshold:

	n	median	max	>1s
MainThread (30s snapshot)	210	0.830s	8.732s	85
Trading threads	13	0.414s	5.111s	2

The file was only 79 KB, so this is disk contention, not payload size ? shrinking the document would not have helped.

Why the obvious fix is unsafe on its own

Dropping fsync from the snapshot path looks like a one-line win. It isn't: os.replace is atomic for the name, not the data, so a hard kill during an un-fsynced rewrite can publish a present-but-garbage file. Because that single document also held trades[] and the P&L rollup, one torn snapshot could destroy the record ADR-0012 exists to protect ? turning a latency fix into a reintroduction of the original incident.

The split

File	Contents	Written by	fsync
session_state.json	trades[], P&L rollup, session date, shutdown flags	trade events, clean shutdown, construction	yes
session_state.marks.json	live counters, open_position with last_mark_ltp	the 30s supervisor snapshot	no

The supervisor no longer touches the durable file at all, so it cannot corrupt it however it fails, and 210 of the 223 slow writes stop paying fsync ? including the 8.7s outlier. Losing the marks file costs at most one snapshot interval of mark data, which ADR-0012 already documented as acceptable.

load_session_state merges the pair back into the single-document shape, so resumable_open_positions, recorded_realized_pnl and the runner's resume path are unchanged. The merge is deliberately asymmetric: a corrupt durable file means no recovery (None); a corrupt or missing marks file still returns the P&L and simply offers no positions for resume.

Deliberately not done

Moving trade-event writes to a queue and a writer thread. It would remove the remaining 13 stalls, but only by weakening durability from "guaranteed before the call returns" to a sub-second window ? the exact guarantee ADR-0012 was written to provide. At a 0.414s median, 13 times a session, that trade is not worth making.

Two defects found while building it

• A session that never recorded a trade created no durable file at all, so a process dying before its first trade left no document ? losing the session date, the shutdown flags, and any trade book carried forward from a same-day restart. Caught by two existing tests failing. The durable file is now established at construction.
• The slow-write warning blamed "the caller's trading loop" for what was usually a supervisor write. Marks now warn separately at a looser 2s threshold with a message that says which one it is, so the 13 that matter are not buried under 210 that do not.

ADR-0012 gains an amendment section and docs/lld/reporting-and-observability.md is updated in the same commit. .gitignore now globs session_state*.json so a future sidecar cannot be committed by accident.

Verification

10 new tests (45 total in the suite), covering fsync-per-path, the durable file staying byte-identical across five snapshots, corrupt/missing/stale marks, and both files archiving under one timestamp.

CI: session_state.py branch coverage 91.6% against its 90% data-safety budget; total 69.6%; coverage policy gate passed.

Note: the fix takes effect on the next runner start. The session that produced these measurements was still running the old single-file path.

Docs: staleness gates over the committed architecture set

A third, unrelated commit rides along here (8c24fb3). It closes the follow-up recorded in ADR-0011 when docs/ was first filled in, and it is worth reading separately from the two changes above ? it touches no runtime code.

docs/ now holds an HLD, 12 LLDs and 12 ADRs. Nothing enforced that any of it stayed true, and stale architecture documentation is worse than none because it is believed. Three gates in Tests/Dependencies/test_repository_policy.py now cover three distinct ways it rots:

Failure mode	Gate
A doc describes a roster or agent set the code no longer has	docs/hld/system-overview.md joins test_current_architecture_docs_distinguish_core_from_optional_agents
A new ADR/LLD lands unlinked, or the index points at a deleted file	test_every_committed_design_document_is_linked_from_the_docs_index ? checked in both directions
A rename breaks a cross-reference	test_relative_links_inside_the_committed_docs_resolve ? 97 links today

docs/superpowers/ is excluded from all three: gitignored session working material, not product documentation.

The HLD did not actually pass

Worth calling out, because it is a real documentation gap rather than test plumbing. The HLD named the two optional agents only as class names inside an ASCII diagram (SLHuntingAIWorker) and as file links, and said "two independently opt-in AI agents" without naming either one. A reader of the system overview genuinely could not tell what they were. Section 1 now carries a short table ? each agent, its provider, its default-off flag, and its LLD.

Every gate was proven to fail

Each was verified against a deliberate mutation before being committed, then restored: an unlinked ADR, a dangling-only index link, a renamed cross-reference, and an agent dropped from the HLD. All four were caught, with file and line. A policy test that cannot fail is worse than no test, because it reads like coverage.

One caveat for reviewers

test_current_architecture_docs_distinguish_core_from_optional_agents reads architecture files from the working tree, so it is not safe to run while switching branches ? it will read one commit's docs against another's tests and fail spuriously. It is stable in CI and in any single checkout.

Suite goes 11 ? 13 tests. No runtime code touched.

?? Generated with Claude Code

---

CPR AI: R2/S2 continuation boundary

97f9ac6 adds one conservative CPR-agent rule: never enter a bullish TRENDING_VWAP_CONTINUATION above R2 and never enter a bearish continuation below S2.

The rule is enforced in both places that matter:

• Codex knowledge: prompt version cpr-srsi-vwap-context-v3 tells the adviser to return HOLD / NONE instead of chasing price beyond the final CPR boundary.
• Host safety: CPRHostPolicy independently rejects those proposals with continuation_outside_r2_s2, so model reasoning cannot waive the rule.

The comparisons are deliberately strict (close > R2 for longs and close < S2 for shorts). Existing milestone, final-target, stop-width, and minimum-1R geometry remain unchanged, and no sideways, reversal, sizing, order, or broker behavior was modified.

Verification

TDD RED first showed the missing prompt knowledge and generic geometry rejection. GREEN verification: CPR AI 70 passed; master 508 passed / 52 skipped; market health 26 passed; repository suites 1,142 passed; branch coverage 70.1% with every threshold passing; compileall, Ruff, mypy, Bandit, pre-commit, fake order-free smoke, and all four pinned dependency audits passed.

Implemented with Codex; the commit includes the required co-author trailer. No authenticated model or broker call was made.

---

CPR AI bugfix: master lazy imports

6f29e86 fixes the production-master failure that recorded ModuleNotFoundError: No module named 'cpr_ai_prompt' before Codex or MCP could run.

The standalone smoke and focused CPR tests could import sibling modules because Python kept the CPR AI source folder on sys.path. The master loader exposed that spaced-name folder only while each startup module executed, then removed it. The first completed-bar turn therefore could not perform the agent's intentionally lazy prompt/schema import; the delayed Codex runner had the same boundary and could also create incompatible duplicate result classes if loaded naively.

The fix retains only the already collision-checked CPR AI source directory after startup and aliases canonical cpr_ai_agent to the exact module object the master already loaded. Two production-style master tests prove that a delayed turn reaches its injected runner and that the Codex runner reuses the master's exact CPRAgentRunResult and CPRToolCallRecord types.

Combined-tree verification

The import-boundary tests passed 2/2; CPR AI passed 70/70; master passed 510/510 with 52 expected skips; market health passed 26/26; repository suites passed 1,142/1,142. Branch coverage is 70.1% and every threshold passed. Compileall, Ruff, mypy, Bandit, pre-commit, fake order-free smoke, and all four pinned dependency audits passed.

The change does not authenticate Codex, call a broker, or alter execution/risk behavior. Implemented with Codex; the commit retains its co-author trailer.