Journal des versions — chaque sortie de keel, de la plus récente à la plus ancienne

Built from 9b1db8755cf7. Version binds to this hash: keel --version reports keel 0.21.0+9b1db8755cf7 [release].

Install

Download all wheels from this release into one directory, then install the keel_trader wheel by path:

pip install --find-links . ./keel_trader-0.21.0-py3-none-any.whl
keel versions

keel versions — not keel --version — is the check: it reports every keel distribution in the venv and exits non-zero if a sibling was left behind at an older version, which --version cannot see. Upgrading an existing deployment: see “Deploying a new version” in the README.

⚠️ Never install by bare name. The distribution is keel-trader; the name keel on PyPI belongs to an unrelated project, so pip install keel fetches someone else’s package. A build reporting DIRTY or [checkout] is not this release and must not be run against live funds.

Configure

config.yaml is attached to this release: the production config, in auto_trade.mode: confirm — keel previews every order and waits for your approval. Drop it beside the install (or run keel init-config --live), put your CDP key in a git-ignored .env, then:

keel migrate     # existing database: apply schema migrations
keel init        # fresh deployment: write config + seed candidate rules

Seeded rules start as candidate and trade nothing until you promote them.

Features

feat(doctor): ledger.drift and ledger.venue_drift, fed by a per-cycle venue-holdings record (#799, #798) (#898)

P3 of the DCA sleeve sell-side build plan (docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md, Tasks 3.1 and 3.2). It adds two doctor findings that compare the positions ledger with the orders log (ledger.drift) and with the venue’s own holding (ledger.venue_drift). The venue holding comes from a new per-cycle record. It also clears four follow-ups carried over from the P1 and P2 reviews.

Closes #799 Refs #798

What changes

Task 3.1: ledger.drift (#799 proposal 3, plan R2)

• New module keel/execution/sleeve.py:
  • ledger_qty sums open tranche qty.
  • orders_qty(repo, product, mode) nets filled BUY minus SELL in the requested mode. It is deliberately not executor._held_position, which is live-only by design (#881).
• doctor.ledger_drift_findings warns when the two disagree by more than one cached base increment. An unknown increment means exact equality. A product that only the orders log knows (the #799 shape) reads as a ledger of zero.
• Wired into gather_findings from repo reads only:
  • Products: open tranches, plus products with a filled order in this profile’s own mode.
  • Mode: the profile’s own mode (paper reads paper fills).
  • Tolerance: the cached base_increment: record. Doctor never calls a broker.

Task 3.2: ledger.venue_drift (#798, plan R3)

• reconcile.record_venue_holdings(broker, repo, now_ts) makes one get_balances() call and writes venue_holding:<product> = {"total": str, "observed_at": int} for each product with an open tranche.

  • It reads Balance.total, never available (#667).
  • It places and cancels nothing.
  • It makes no call when nothing is held.

• run_once calls it last, after exits, entries and _manage_stops (moved there in review, #899, so a same-cycle buy is recorded), on live cycles only (paper_trader is None). The call is wrapped so that a failed diagnostic write never costs a cycle.

• doctor.venue_drift_findings warns in two cases:

  • the ledger holds more than the recorded venue total (the WARN prints the observation date);
  • a held product has no observation.

  The venue holding more than the ledger is not drift. A paper profile passes an empty ledger and reads OK.

Carried-over items

• (a) A degenerate venue increment can no longer raise out of a bracket leg after a filled entry. Traced:

  • Instrument accepts Decimal('Infinity') (it is > 0).
  • The fresh get_instrument answer skipped _coerce_increment entirely.
  • The cached path let Infinity through, and NaN > 0 raises.
  • quantize_down then raises InvalidOperation, which is an ArithmeticError, not a ValueError.

  Fixed at both levels:

  • _coerce_increment requires a finite increment, and the fresh answer goes through it.
  • The spec-build catches in place_bracket and _roll_stop now include ArithmeticError. A finite increment far finer than the 28-digit context (1E-40) still raises DivisionImpossible, so fixing the cause alone was not enough. In _roll_stop the old bracket is already cancelled, so an escaping exception would have skipped the CRITICAL.

  New tests show that a filled entry keeps its tranche, both at the executor level and through run_once.

• (b) _unlinked_pending_sells reads executor.RESTING_STATUSES, so an unlinked partially_filled SELL also leads to “reconcile first”.

• (c) position.unprotected’s fix line now gives advice per product. When only some unprotected products have an unlinked resting SELL, the others keep “place one at the venue or close the tranche”. The two parts are joined with |.

• Review round 1 also reworded the two new fix lines, which no longer name the unshipped keel positions close; a new test in test_doctor_fix_lines.py scans backtick-quoted invocations.

• (d) Renamed test_unmanaged_matches_on_product_not_on_rule_id to test_unmanaged_matches_on_product_and_kind_not_on_rule_id.

…truncated — full description in #898.

Other changes

docs(plan): DCA sleeve sell-side build — prerequisites, reverse_dca, preview trims and exit monitor (#878)

This PR adds the implementation plan for the DCA sleeve’s sell side: docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md. It builds the design merged in #859 (issue #857) in the order the operator set on 2026-09-28:

1. Prerequisites: #799, #811 and #798.
2. reverse_dca.
3. Trims (keel dca trim --preview, and profit_take in preview) and the exit monitor (sleeve_exit), both preview-only, before any live placement.

Out of scope: steering, band rebalancing as a rule, and rotation or tax-loss harvesting. The spec recommends not building them. This PR is a document only; nothing is built.

PR sequence (merge order)

#	PR	Closes	Size	Schema
P1	fix(execution): a bracket leg that throws after a filled entry downgrades to open-unbracketed	refs #799	S	none
P2	feat(doctor): position.unmanaged and position.unprotected	#811	M	none
P3	feat(doctor): ledger.drift and ledger.venue_drift	#799	M	none
P4	feat(positions): keel positions close <id>	#798	M	none
P5	feat(strategy): sell-side contracts: Holding, Reduction, Action.REDUCE, reduce_signal, book_exit(is_dca=None)	—	M	none
P6	feat(data): the sell_proposals table and keel dca proposals list/show	—	M	v22
P7	feat(execution): executor.reduce in preview	—	M	none
P8	feat(agent): _handle_reductions	—	M	none
P9	feat(rules): reverse_dca, preview-only	—	M	none
P10	feat(dca): keel dca distribute --preview and its doctor findings	—	S	none
P11	feat(sim): the reverse path	—	M	none
P12	feat(promotion): the sleeve_sell gate, proposal replay and proposals review	—	M	none
P13	feat(dca): keel dca trim --preview --view lots and --view bands	—	M	none
P14	feat(rules): profit_take in preview, and --view gain	—	M	none
P15	feat(execution): the sleeve exit monitor	—	M	none
P16	feat(rules): sleeve_exit, preview-only	#857	S	none
P17	feat(autonomy): keel autonomy on --sells	—	M	v23
P18	feat(dca): --confirm <proposal-id> behind the sells window and a typed yes	—	M	none

P17 and P18 are the gated placement path, and they are off by default. They merge only when the operator says so (R28). No PR is size L.

Safety invariants every PR states and tests

• S1: no new sell reaches the venue unless keel autonomy on --sells was armed at a TTY. The live autonomy on flag alone never releases one. An AST inventory of every function that reaches the venue’s order endpoint enforces this, from P1 onward.
• S2: everything is preview-only. Every sleeve_sell kind declares Execution = Literal["preview"], so execution: auto does not exist.
• S3: the rails apply to sells as spec §3.4 says. Rails 1, 2 (as a slicing obligation), 9, 10, 12, 18, 19 and 21 apply to a sell. Rails 13, 17, 20 and 22 are buy-scoped in guards.py, and P7 pins both halves.
• S4: the browser and the MCP server can never increase capability. This is enforced by a name scan plus the existing effect scan.

The research freeze holds. reverse_dca’s sim and replay tests are fidelity checks against hand computations on synthetic candles. The trim preview only reports numbers. Nothing is added to the trials ledger.

Every ruling is recorded as what — why — cost if wrong (R1–R32). The plan also lists where the spec and the issues contradict the code today (C1–C19), and the open questions with the default this plan builds (OQ1–OQ12).

docs(plan): sell-side build plan follow-up — #887, doctor OK findings, P18 exit codes (#888)

Follow-up to #878 (docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md). Plan text only; no code changes.

What changes

• #887 (P18, Task 18.1). executor.reduce’s success path now decides from repo.get_open_positions after book_exit, instead of from the pre-sale protecting_remainder arithmetic. This mirrors agent._handle_exits’s tail (keel/agent.py:950-987):
  • A true full close clears position_rule:, open_stop:, open_target: and unbracketed: together. Before, only unbracketed: was cleared, so a stale open_stop made rail 9 (no_stop_widening, keel/execution/guards.py:657-664) veto the next entry.
  • A full-close SELL that the venue fills short (#446) rewrites the retry record from the ledger and logs CRITICAL. It no longer clears the record.
  • There are two new named tests: test_887_a_full_close_clears_position_rule_and_open_levels_too and test_887_a_short_filled_full_close_rewrites_the_retry_record_from_the_ledger. Step 2 item 5 records how each one fails first.
• P10 / P15 doctor findings. When there is nothing to report, sleeve_rule_findings returns OK for both of its names and exit_watch_findings({}) returns one OK sleeve.exit_watch. This matches P3’s ledger.drift sentinel, so the exact-set test at tests/commands/test_doctor.py:603 keeps every name. Each case has a new test.
• Task 18.1 Step 2 item 1. Only test B (..._partial_confirmed_leg_re_brackets_...) uses _confirm_recording_cancel_state. Test C uses a bare lambda.
• Post-confirm failure comment. A guard veto and the spread gate both run inside _run_order before confirm_fn is called, and the spread gate only applies to BUYs. After a yes, the only way the SELL can fail is a PlaceResult(success=False) from the broker. The failed reason no longer claims a bracket was cancelled for a tranche that never had one.
• R35: P18 exit codes (new). --confirm exits 0 only when the decision is placed. declined and failed both exit 1 through click.ClickException(f"{decision}: {reason}"), which is the convention across keel/commands (_require_interactive_confirmation, orders cancel). Codes 4 and 5 are reserved for the day-stamping wrapper contracts in agent.py. --confirm requires a TTY, so no wrapper ever reads its status, and the message is what tells a decline from a failure. Task 18.2 gains two exit-code tests.

Closes #887

fix(execution): a bracket leg that throws after a filled entry downgrades to open-unbracketed (#799) (#889)

P1 of the DCA sleeve sell-side build (docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md, Tasks 1.1 and 1.2).

What

#799 proposal 2: a filled entry is never lost to a later bracket failure (plan R5). place_bracket runs after the entry has filled. Before this PR, an exception from the bracket leg unwound through execute and run_once past _open_tranche. That is how the August PAXG entry was left with no ledger row, no exit and no stop. place_bracket now returns None for every bracket-leg failure, and the stage it failed at decides what happens next:

Stage	Retry record unbracketed:	orders row	Log
Before the bracket row exists (preview raised; spec build already handled)	written, same as a veto	none	WARNING executor.bracket_not_placed
After it exists (place_order raised, TradeScopeDenied included)	not written, and a leftover one is cleared	stays pending	CRITICAL executor.bracket_state_unknown, naming the row

In the second stage the venue may already be holding the bracket, so a retry could commit the same base twice. Any later exit on the product fails closed on that pending row (_clear_resting_bracket) until someone reconciles it by hand.

The sell-side invariants module, tests/execution/test_sell_side_invariants.py (S1, S4). It pins, by AST scan:

• PLACEMENT_CALLERS, the only function that calls broker.place_order;
• RUN_ORDER_CALLERS, the four functions that call _run_order;
• SECOND_LEVEL_CALLERS, every function under keel that calls executor.execute/place_bracket/scale_out/roll_stop_to/roll_to_break_even/trail_stop_atr;
• WEB_FORBIDDEN_NAMES, together with a check that executor.reduce does not appear in keel/web or keel/mcp.

This PR also closes a gap the plan left in that module. Code can reach those names without writing executor.<name>: through from keel.execution.executor import scale_out, or through a call on an alias of the module such as executor_mod. Both are now pinned shut, and a synthetic test shows the scan catches each one.

Safety invariants

• S1: no new sell reaches the venue without keel autonomy on --sells at a TTY. P1 adds no sell path and no new caller of _run_order, place_order or any executor.* order entry point. The invariants module added here pins the current inventory. executor.reduce does not exist.
• S2: v1 execution is preview-only. Unaffected: no sleeve_sell rule class exists yet.
• S3: rails on sells. No rail is changed. The bracket still goes through guards.check unchanged inside _run_order.
• S4: the browser never increases capability. Pinned by test_the_browser_and_mcp_name_no_sell_side_operation. keel/web and keel/mcp are untouched.

Tests

• tests/execution/test_bracket_downgrade.py: the preview-stage throw and the place-stage throw (TimeoutError, TradeScopeDenied), plus a control case where the bracket places normally. Each fake counts how many SELL previews and places reach the venue, so neither test passes without doing anything.
• tests/test_agent.py::test_799_a_throwing_bracket_preview_still_records_the_tranche: the #799 acceptance test. The tranche is in the ledger with initial_stop=95.00 and a retry record. Without the fix it fails with InvalidOperation out of run_once.
• tests/execution/test_reconcile.py::test_a_retry_whose_placement_state_is_unknown_is_not_retried_again: the sweep does not place a second bracket after a place-stage throw. Without the clear it places twice.
• Mutation checks, each confirmed to have changed the source:
  • dropping the clear kills the reconcile test;
  • forcing the preview-stage branch kills 3 tests.
• Full gate: pytest (7088 passed, 3 skipped), ruff check, ruff format --check, bare mypy.

Deviations from the plan

• The plan’s agent test used _config() unchanged. Rail 2 vetoes that entry at the default 1% risk, so the bracket leg was never reached. The test now uses risk_pct=0.0001 and asserts the SELL preview actually ran.
• The place-stage branch clears an unbracketed: record left from an earlier attempt, as well as not writing a new one. The plan text only said it writes none. Without the clear, the reconcile sweep’s retry would re-place the bracket on the next cycle, which is exactly what R5 says must not happen.
• The import and alias check was added to the invariants module.

Refs #799. This PR does not close it: proposal 3, the doctor check, lands in P3 as ledger.drift (plan R1).

feat(doctor): position.unmanaged and position.unprotected (#811) (#896)

Summary

P2 of the DCA sleeve sell-side build plan (docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md, P2 as revised in #888).

Nothing in keel doctor answered “is anything still watching this held tranche?”. The only channel that reported PAXG tranche 3 was the reconcile sweep, and the sweep is keyed on the unbracketed: retry record. When that record was cleared, the channel went quiet and the exposure stayed. These two findings are computed from the positions ledger, so clearing a record cannot silence them.

• position.unmanaged (WARN): an open tranche with no rule at the profile’s managed status (live, or paper on a paper profile, mirroring agent.py’s rule_status) whose product AND kind match the tranche’s (product_id, rule_name). It does not use rule_id, which is NULL before #803. Product alone is not enough (#897): _handle_exits finds the owner by r.name == rule_name, so a live dca rule cannot exit a turtle tranche on the same product. The detail names the product, the tranche id, and the current status of the newest rule of that (product, kind), or no rule.
• position.unprotected (WARN): an open tranche with initial_stop > 0, no resting bracket (reconcile._has_resting_bracket), and no retry record that still holds an intent. On a paper profile it is skipped and reported OK: a paper fill never gets an exchange bracket, so the check would fire on every stopped paper tranche.
• Fix line under R5 (#799). If a pending live SELL exists on the product and no open tranche names it as its bracket, position.unprotected’s fix line says “reconcile the pending order first” and names the order ids, instead of “place one at the venue”. Such an order’s placement state is unknown, and a second bracket over it would double-commit the base.
• Both are WARN, never FAIL. When they warn, products is populated in --json (#642).
• Both are wired into gather_findings right after ledger.unbooked_exit. The call stays read-only: the change counter is pinned by a test that has rows on the new reads’ path.
• Both names are added to the exact-set assertion in test_gather_findings_covers_every_check_over_a_seeded_db.

Safety invariants

• S1: no new sell reaches the venue without keel autonomy on --sells at a TTY. This PR adds no caller of _run_order, broker.place_order or any executor.* placement function. tests/execution/test_sell_side_invariants.py passes with its pins unchanged.
• S2: v1 execution is preview-only. This PR adds no rule class.
• S3: rails on sells are unchanged. This PR changes no rail.
• S4: the browser never increases capability. No keel/web/ or keel/mcp/ module is touched. The MCP doctor tool inherits two read-only findings through gather_findings.

A doctor finding places nothing.

Acceptance (#811)

• A demoted rule with an open tranche produces position.unmanaged WARN naming the product, the tranche id and the rule’s current status (paper).
• A stopped tranche with no resting bracket and no retry record produces position.unprotected WARN. A pending bracket or a live retry record clears it. A retry record cleared to None does not.
• A DCA tranche (no initial_stop) produces neither.
• Both appear in --json with products == ["PAXG-USD"].
• The ~/keel/keel-live.db bullet is replaced by a fixture of tranche 3’s exact row (this plan may not touch ~/keel). The operator runs keel doctor on the deployment after the release.

Test plan

• tests/commands/test_doctor_position_watch.py (new): the pure function, including the paper-profile skip, the choice of the newest rule’s status, and a check that the resting predicate is consulted for each stopped tranche.
• tests/commands/test_doctor.py: wiring tests for the live-shape WARN pair plus render_json products, read-only with rows present, retry record live vs. cleared, bracket pending vs. cancelled, and paper profile OK with a live-profile control.
• Mutation checks, each proven applied and each killed: 7 mutants in the first commit; product-only membership (#897); the literal “live” in the headline; and 4 mutants on the pending-SELL read (the link filter, the side filter, the status filter, and the wiring).
• uv run pytest -q (7128 passed), ruff check, ruff format --check, bare mypy.

Closes #811

feat(positions): keel positions close — an operator-declared exit the rails can read (#798) (#901)

P4 of the sell-side build plan (docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md, Tasks 4.0–4.2).

What ships

• Task 4.0 (R33): guards._open_exposure_by_asset nets per product. A product whose filled BUY qty minus SELL qty is <= 0 now adds nothing to its asset bucket, whatever its net notional is. Before this, a full close at a loss left a phantom residual. PAXG tranche 3 (0.0132 bought at 4673.23, closed at 4400) kept $3.61 of “exposure” with zero units held. A product that is still net-long nets by notional as before, pinned by test_a_partial_close_still_nets_by_notional. There is one more change, now pinned: a product fully closed at a gain can no longer drive its bucket negative and shrink a sibling product’s figure. That is the closed direction for a cap.
• Task 4.1 (R4): close_declared_position is in the new module keel/commands/positions_close.py. It writes one orders row with mode=live, SELL, order_type=out_of_band, status=filled and confirmation=operator_declared. The row’s qty and filled_quantity both equal the tranche’s ledger qty. It also carries the operator’s price and fee and the tranche’s rule_id. The service then books that one tranche through record_closed_trade, with is_dca taken from the tranche’s own rule_name, and closes it. When it closes the product’s last tranche, it also retires position_rule:, open_stop:, open_target: and unbracketed:. It refuses the following before anything is written:
  • an unknown or already-closed id;
  • a price that is <= 0 or not finite;
  • a fee that is < 0 or not finite;
  • a paper profile.
• Task 4.2 (R30): keel positions close <id> --price P [--fee F] is a new positions group with this one verb. positions_close_gate runs the refusals first, then the typed yes gate, then the write. It has one new capability row.
• Doctor. The fix lines on ledger.venue_drift and position.unmanaged now name keel positions close <id> --price P. The #798-pending allowlist in test_doctor_fix_lines is gone. ledger.unbooked_exit no longer reads an out_of_band SELL as unbooked. Without that change, declaring a close on a newer tranche would WARN for as long as an older tranche is held.

Closes #798. Together with P3 (#898: balance reconciliation and ledger.venue_drift) and Task 4.0, all three of #798’s proposals are delivered.

Safety invariants

• S1: nothing reaches the venue. The command builds no broker at all. The CLI tests monkeypatch every _build_broker seam to raise and count calls, and they assert zero calls. test_sell_side_invariants.py’s PLACEMENT_CALLERS, RUN_ORDER_CALLERS and SECOND_LEVEL_CALLERS pins are unchanged. P4 adds no placement path.
• S2: v1 execution is preview-only. Untouched. P4 adds no rule class.
• S3: rails on sells. Untouched. No intent goes through guards.check here, because nothing is placed. Task 4.0 changes only what rails 4/5/6 measure for a fully closed product.
• S4: the browser never increases capability.
  • close_declared_position joins WEB_FORBIDDEN_NAMES.
  • The gate function calls close_declared_position, so the web effect scan in tests/web/test_server.py derives it as forbidden automatically.
  • close joins the MCP write vocabulary (tests/mcp/test_readonly.py, docs/mcp-server.md).
  • I planted a call to close_declared_position in keel/web/api.py as a check. Both the S4 name scan and the effect scans went red.

Capability row

keel.commands.positions_close.positions_close_gate (cli, tty). Declaring a close shrinks the exposure that rails 4/5/6 measure, and that is headroom for new entries. The prose capability counts move from nine to ten (capabilities.py, keel/web/*, two JS comments; node --check passes on both).

Rulings made here (beyond the plan)

…truncated — full description in #901.

fix(execution): book tranches and brackets at the venue-filled size (#900) (#905)

Refs #900. This PR fixes the problem going forward only. It does not backfill the four existing live rows (orders 1, 2, 4 and 8 and their tranches), because the operator is checking the venue balance first.

Root cause

Nothing ever recorded the venue’s filled_size for a live BUY:

• _upgrade_to_observed_economics read the order status exactly once, in the same instant as place_order.
• A market IOC that is read back that quickly has not settled at Coinbase yet. The answer is PENDING/OPEN with filled_size 0.
• _record_observed_fill_quantity dropped the zero without logging anything.
• The row had already been written as filled (_initial_status), and reconcile only polls RESTING_STATUSES. So nothing ever read the order again.

As a result filled_quantity stayed NULL. The tranche (agent._open_tranche) and the bracket (execute) were both sized from intent.qty = quote / expected price, but the venue delivered (quote − fee) / price.

The four live rows showing actual_fill equal to the expected price, with previewed fees, fits a status read that returned nothing usable.

What changes

1. Venue filled size is observed on both sides. The executor now re-reads the order status up to 3 more times (FILL_OBSERVATION_PAUSES = 0.5/1/2s, 3.5s at most, once per market order) until the venue reports a terminal state. TERMINAL_ORDER_STATUSES is pinned equal to reconcile’s _FILLED ∪ _DEAD. filled_quantity is recorded only from that terminal answer. If no terminal answer comes, it stays NULL, never guessed, and executor.fill_quantity_unobserved logs a WARNING.
2. Tranche booking. agent._open_tranche books filled_quantity when the venue gave one. Otherwise it books the ordered qty and logs agent.tranche_qty_unobserved at WARNING. The warning fires for live rows only.
3. Protective bracket. It is sized from the same delivered quantity (executor.delivered_qty), so its SELL never exceeds what was received. That was the #446 oversized-bracket condition, and it happened on every fee-in-quote entry. The partial-fill warning now keys off the terminal status (CANCELLED/EXPIRED with fills) instead of filled < qty. A quote-sized BUY always has filled < qty, so the old check fired on every entry.
4. Consistency. These now all read filled_quantity or qty: sleeve.orders_qty, executor._held_position, and agent._held_position. R33 (guards._open_exposure_by_asset) already did. A new pin shows that closing every tranche with keel positions close nets the product to exactly zero on every reader, and that R-f admits the close.
5. Paper and sim. Neither is affected. PaperTrader, strategy/backtest and sim/account charge the fee on top of the notional, so their qty is the quantity delivered. sim/accumulation_policy (#831 research) already models fee-in-quote and never writes orders. The new tranche WARNING does not fire for mode='paper'.
6. Spend and exposure counts are unchanged. guards._order_notional adds the fee to a BUY that has an observed filled_quantity. A $50 quote BUY with a $0.45 fee therefore still counts $50 toward rails 3 and 14 (and 4/5/6), which is what the ordered qty × price gave before. The fee is not added on the qty fallback, where the quote already contains it, nor on a SELL.
7. Price and fee come only from the terminal read. actual_fill and fee are upgraded only from the same terminal observation as filled_quantity. Otherwise the estimates stand.
8. doctor ledger.venue_drift. If a product’s gap is above the tolerance but no larger than tolerance + Σ(entry_fee / entry_fill) over its open tranches, its clause names #900 and its fix line no longer sends the operator to keel positions close. For every drift, the explanation now lists fee-in-quote overstatement among the possible causes. The tolerance (one increment) and the WARN status are unchanged.

Review round 1 (#906, #907):

• fill.partial no longer judges a filled market BUY by filled < qty, because that qty is a quote estimate.
• The #900 fee band counts only tranches backed by a live BUY with NULL filled_quantity and an equal qty.
• The fee figure in the clause is quantized up to the base increment.
• fill_quantity_unobserved uses exit wording on a SELL.

Rulings

…truncated — full description in #905.

feat(strategy): sell-side contracts — Holding, Reduction, Action.REDUCE, reduce_signal, book_exit(is_dca=None) (#857) (#908)

Refs #857. P5 of docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md (Tasks 5.1–5.4). It adds contracts only: no placement path, no rule kind, no schema change.

What lands

• keel/strategy/reduction.py (new, pure; R6–R8): Lot, Holding, SellCosts, Reduction.
  • Holding.from_rows keeps the ledger’s FIFO order and filters nothing by rule_name.
  • Cost basis includes the entry fee, prorated by qty / (qty + realized_qty) (spec §3.3, Q4).
  • SellCosts refuses fee plus slippage outside [0, 1).
  • Reduction refuses a non-positive qty or price, and an empty reason.
• Action.REDUCE and Rule.reduce_signal(holding, candles_by_tf, costs) -> None by default (R6). A test checks every kind in RULE_REGISTRY returns None over a real holding.
• promotion.SLEEVE_SELL and promotion.RECOGNISED_CLASSES (R10). The conformance test now reads RECOGNISED_CLASSES. SLEEVE_SELL is deliberately not in _CLASS_FLOORS.
• streak.book_exit(is_dca=None) derives each leg’s flag from its own tranche’s rule_name (R9, spec §3.2, Q10, #860). A bool keeps today’s behaviour exactly, and the existing callers are untouched. Tested on the PAXG shape: the turtle leg counts toward rail 16 and the DCA leg does not.
• sleeve.holding_of(repo, product_id, mark=None). Its qty is pinned equal to ledger_qty over the same rows.
  • Both Holding and holding_of document #900: tranches booked before #905 still carry the ordered qty until a backfill runs, so the ledger can overstate the venue by about a fee.
  • No venue clamp is added. _clamped_sell_qty and ledger.venue_drift already cover that gap.

A REDUCE cannot run through any existing path

executor._build_intent treated every non-ENTER action as an EXIT. So a REDUCE (or NONE) handed to executor.execute would have sold the whole held position. The new red test showed it placing a SELL.

• _build_intent now raises ActionNotExecutable for anything outside EXECUTABLE_ACTIONS = {ENTER, EXIT}, before it reads anything.
• execute and agent._paper_enter both catch it and return not placed.
• The tests, parametrised over set(Action) - {ENTER, EXIT}, assert:
  • no get_balances, cancel, preview or place call, and no new orders row on the live path;
  • on the paper path, zero calls to guards.check and PaperTrader.on_signal (spies count them), and no paper row.

Safety invariants

• S1: no new caller of _run_order or broker.place_order, and no new second-level caller. tests/execution/test_sell_side_invariants.py is unchanged and green. executor.reduce does not exist yet. REDUCE is refused by execute and the paper path (above).
• S2: no sleeve_sell rule kind exists yet. reduce_signal returns None on every registered rule, so nothing here runs on the live cycle.
• S3: unchanged. No rail is touched.
• S4: unchanged. No keel/web/ or keel/mcp/ module is touched.

Verification

• Full uv run pytest -q: 7291 passed, 3 skipped.
• uv run mypy (bare) is clean, and so are ruff check keel tests and ruff format --check.
  • Bare ruff check reports one pre-existing E501 in docs/experiments/2026-09-02-equities-cost-fidelity.py, which is on main and untouched here.
• Every new test was watched failing for its stated reason first.
• Mutation run: 16 mutants across reduction.py, promotion.py, executor.py, agent.py, streak.py and sleeve.py. For each one, the source was asserted to have changed before running and restored from a saved copy afterwards. All 16 were killed.

Deviations from the plan

1. Added the ENTER/EXIT-only chokepoint in executor._build_intent, with its catches in execute and _paper_enter. The plan does not have it, but without it Action.REDUCE would be executable, as a full exit, by an existing path.
2. test_every_registered_rule_proposes_no_reduction_by_default iterates the whole RULE_REGISTRY (six kinds), not the plan’s four hard-coded kinds.
3. Extra tests beyond the plan: from_rows order and decoding, unrealised, the empty Reduction.reason, the SellCosts boundary at exactly 1, a partial is_dca=None sale that stops inside the DCA tranche, and an empty holding_of.

feat(data): sell_proposals, schema v22, and keel dca proposals list/show (#857) (#909)

Refs #857

P6 of docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md (Tasks 6.1–6.3).

[!IMPORTANT] Schema v22. This PR bumps SCHEMA_VERSION 21 → 22. It adds one table, sell_proposals, and one index, idx_sell_proposals_product_ts. The migration is additive only: no existing table, column or row is touched, and nothing is backfilled. At deploy, run keel --db <db> migrate (prints schema 21 -> 22). Until that runs, the read-only keel dca proposals verbs refuse the database with the stale-schema message. They never migrate it themselves.

What

• Task 6.1: v22 migration (keel/data/db.py). The sell_proposals DDL, with the plan’s 21 columns and the (product_id, ts) index that R14’s per-day read uses. _migrate_v22_sell_proposals is a documented no-op in the v17/v19 pattern: IF NOT EXISTS creates the table before the version loop runs. Also in this task:
  • _MIGRATIONS[22] and SCHEMA_VERSION = 22.
  • Schema-version pins:
    • the eight == db.SCHEMA_VERSION == 21 pins in test_migrations.py relax to db.SCHEMA_VERSION;
    • test_trade_outcomes.py’s pin relaxes and is renamed test_schema_is_at_the_current_version;
    • test_db.py’s deliberate tripwire is bumped to test_schema_version_is_22.
  • New asserts use db.SCHEMA_VERSION.
  • One migration-safety test builds a populated v21 file: orders, an order update, a tranche, a journal entry, and a 3-event audit chain, all in WAL mode. It takes the file to v22 through the real keel --db <file> migrate CLI. It then asserts:
    • every pre-existing table is unchanged, compared row by row;
    • sell_proposals is empty;
    • the audit chain still verifies with the same event count.
• Task 6.2: repository and audit events (keel/data/repository.py, keel/data/audit.py).
  • insert_sell_proposal and update_sell_proposal each write the row and its audit event in one write_transaction. The events are sell_proposal_recorded and sell_proposal_updated, in the chain’s closed <store>_<verb> vocabulary. They are added to EVENT_STORES under the store sell_proposals.
  • get_sell_proposal and get_sell_proposals return rows newest first. They filter by product, rule and since_ts, and take a limit. Money comes back as Decimal and trigger/rails as dict. A pre-v22 database reads as [] or None, using the table_present idiom.
• Task 6.3: keel dca proposals list and keel dca proposals show <id> (keel/commands/dca.py, and the new keel/commands/sleeve_report.py).
  • Both verbs are read-only. They always open the database through _common._open_repo_ro, at a TTY and off one.
  • sleeve_report.render_proposal_line and render_proposal are pure renderers that P8 and P18 will reuse.
  • A NULL figure prints as unrecorded, never as $0.00, and the fee is always printed with its source.

Safety invariants

• S1 (unchanged): no new sell reaches the venue without keel autonomy on --sells at a TTY. This PR adds no placement path. PLACEMENT_CALLERS, RUN_ORDER_CALLERS and SECOND_LEVEL_CALLERS in tests/execution/test_sell_side_invariants.py are unchanged and green.
• S2 (unchanged): v1 execution is preview-only. No rule class, execution value or placement branch is added.
• S3 (unchanged): the rails on sells. This PR has no REDUCE intent and does not touch guards.check.
• S4: the browser never gains a capability. insert_sell_proposal and update_sell_proposal join WEB_FORBIDDEN_NAMES. The web/MCP scan is now a helper, _web_offenders, and a new test, test_the_web_scan_catches_the_sell_proposal_writers, proves it catches both writers, whether named as an attribute or as a bare name.

Rulings made while building (what — why — cost if wrong)

• update_sell_proposal’s event takes its timestamp from now. The table has no updated_at, and an update event is a statement that something changed at that moment. Cost if wrong: an event’s ts would differ from a caller-chosen time by seconds.
• The chain test reads events through audit.read_events, not repo.audit_chain().events. The plan’s test sketch used the latter, but ChainState exposes no event list. The plan said to fall back to the reader test_audit_chain.py uses, and the test does that.

Deviations from the plan

…truncated — full description in #909.

feat(execution): executor.reduce in preview — rails, venue preview, sleeve caps, rail-2 slicing (#857) (#910)

Refs #857. Plan P7, Tasks 7.1–7.2 (docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md).

What

• keel/execution/sleeve.py (Task 7.1, R11–R15, spec §3.4/§3.6): sell_costs, slice_qty, proposed_today, last_proposal_ts, sleeve_refusal, record_proposal (the one proposal writer), unverified_fill_orders, and the constants FALLBACK_FEE_SOURCE, VENUE_FEE_SOURCE, SAME_DAY_DCA/MIN_HOLD/COOLDOWN, DEFAULT_MIN_HOLD_DAYS, MIN_HOLD_EXEMPT_KINDS, ARBITRATION_ORDER. The module docstring carries one paragraph per ruling.
• keel/execution/executor.py (Task 7.2, R17): ReduceResult and reduce, preview only. It caps the sale at the ledger’s holding, clamps it to the venue’s holding (_clamped_sell_qty), slices it for rail 2, runs guards.check unmodified, builds the spec, calls preview_order, and records one sell_proposals row. It never cancels, never writes an orders row and never places. A preview failure is recorded on the fallback fee; it is never raised.

Safety invariants

• S1: reduce calls none of _run_order, place_order, insert_order, update_order, _clear_resting_bracket, _cancel_at_exchange, cancel_order or place_bracket.
  • PLACEMENT_CALLERS, RUN_ORDER_CALLERS and SECOND_LEVEL_CALLERS are unchanged.
  • A new AST pin, test_reduce_reaches_no_placement_cancel_or_order_writer, is paired with a false-capable companion test.
  • Spy tests cover all six decision outcomes (test_reduce_never_places_cancels_or_writes_an_order_for_any_decision): venue preview, a preview that raised, a rail veto, below one increment, nothing held, and offline. Each outcome has a seeded resting bracket and spies on the broker, the repository’s order writers and the executor’s cancel and placement helpers.
• S2: preview is the only execution value. reduce has no placement branch.
• S3: proven in tests/execution/test_reduce.py (table below).
• S4: unchanged. The web and MCP scan already names executor.reduce.

S3: which rails bite a sell (checked against guards.py)

Rail	On a reduction	Test
1 allowlist	vetoes	..._vetoes_the_reduction_before_the_venue_quotes[1-halal_allowlist]
2 per-order cap	sliced, not vetoed; a control shows the unsliced order is vetoed	test_rail_2_is_sliced_not_vetoed_and_the_legs_are_recorded
7 min move	not evaluated (stop is None)	test_rails_9_and_10_are_satisfied_by_construction
9 stop widening	not evaluated: no stop or protective_stop, even with a high open_stop	same
10 sell-only-on-rule	satisfied: rule_kind = reduction.reason, never empty	same
12 kill switch / stale feed	vetoes	[12-kill_switch], [12-stale_data]
18 settlement currency	vetoes (BTC-EUR)	[18-settlement_currency]
19 spot shape	vetoes (BTC-PERP-USD)	[19-spot_instrument]
21 base balance	vetoes when the venue affirms 0	test_rail_21_vetoes_when_the_venue_affirms_a_zero_holding
3, 4, 5, 6, 8, 11, 13, 14, 16, 17, 20, 22	do not bite: all are is_buy-gated	test_buy_scoped_rails_do_not_veto_a_sell arms all twelve. A control BUY proves each one fires, and then the reduction previews.

Carried-over items (each test-first)

• (a) Reduction refuses a non-finite qty or expected_price with ValueError. Before this, Infinity passed and NaN raised InvalidOperation.
• (b) insert_sell_proposal refuses a key that is not a column, including id.
  • Ruling: the check sits in the repository method, not the writer. Its sibling update_sell_proposal already refuses unknown keys, and the table reads NULL as “not recorded”, so a misspelt figure would otherwise be stored silently as missing. insert_order drops unknown keys, but it is not this table’s sibling.
• (c) The preview’s sized quantity never exceeds the holding.
  • It is capped at holding.qty, then clamped to the venue’s Balance.total. A below_one_increment veto records that capped sale, not the rule’s ask (#911).
  • Every proposal records rails.unverified_fill_orders: the unsized filled live BUYs that own a currently open lot (#900, refined in #912).
    • Every filled live BUY is a candidate owner. It is matched on its booked size (filled_quantity or qty) against the lot’s original size (qty + realized_qty), within one day before the lot opened.
    • Candidates are taken newest first, and each lot is claimed once.
    • Only the unsized owners are listed.
  • positions has no link to its entry order, so this is a match on size and time, not a stored link.

Rulings

…truncated — full description in #910.

feat(agent): _handle_reductions — arbitration, one proposal per product per day, sleeve.proposal notifications (#857) (#914)

Refs #857 — plan P8 (docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md, Tasks 8.1-8.3).

What

• Task 8.1 — agent._sleeve_rules(repo, config): sleeve-sell rows are sorted out by their registered class before any row is built (R31), loaded at paper + live in a live cycle and paper only in a paper cycle (R16). Their products join the poll set. A sleeve row that fails to build is logged and skipped, never raised out of run_once.
• Task 8.2 — agent._handle_reductions(...) and LoopResult.reduce_results. Per product: nothing held asks nothing; one proposal per product per UTC day (R14, sleeve.already_proposed_today); each rule waits for its own bar; a raising rule costs only itself; fixed arbitration (sleeve.ARBITRATION_ORDER) records losers superseded; the sleeve caps (sleeve_refusal) refuse before any intent and record vetoed with rails.sleeve; then executor.reduce (preview-only), offline with no broker on a paper cycle (R18).
• Task 8.3 — sleeve.proposal (execution, info) in keel_core.notifications.EVENTS, derived by events_from_state(..., sleeve_proposals=result.reduce_results) (R19). preview and vetoed notify; superseded does not. The notification write list is unchanged ([NOTIFIED_WINDOWS_KEY]). Runbook table updated.
• P7 held question, fixed: a sliced proposal now records the sale’s total — rails.total_qty on the row, ReduceResult.total_qty on the result, and “sell over legs” in the notification. The row’s qty is still rail 2’s first leg.

Cycle ordering (the load-bearing change from the plan)

kill switch / session gate -> poll -> reconcile -> equity -> entry pre-pass
  -> main pass per product: exits, then entries (the DCA buy)
  -> stop management -> venue-holdings record
  -> REDUCTIONS (every product, wrapped per product)          <- new, LAST
  -> LoopResult -> notifications

Pinned by tests/test_agent.py::test_reductions_run_after_the_entries_so_a_denied_sell_preview_cannot_stop_todays_buy: the sleeve product is ADA-USD, which sorts before BTC-USD, and its SELL preview raises TradeScopeDenied. The test asserts the BTC BUY is placed before the ADA SELL is quoted, the refutation is recorded, and the next cycle’s BUY is vetoed by rail 20. A mutant that moves the step into the per-product main pass (the plan’s placement: after exits, before entries) fails this test; the test was built so it would, after a first version with an ETH sleeve product did not catch that mutant.

Deviations from the plan

…truncated — full description in #914.

feat(rules): reverse_dca, preview-only (#857) (#918)

Refs #857

P9 of docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md: the first sell-side rule kind, reverse_dca. It is spec §6’s scheduled cash distribution, and it is preview-only.

Safety invariants

• S1: no new sell reaches the venue without keel autonomy on --sells at a TTY. A live reverse_dca only proposes. Its one path is _handle_reductions → executor.reduce (P7/P8), which is preview-only. RUN_ORDER_CALLERS, PLACEMENT_CALLERS, SECOND_LEVEL_CALLERS and REDUCE_CALLERS are unchanged. A new cycle test (test_a_stored_reverse_dca_row_proposes_its_distribution_through_the_real_builder) runs a real stored row through the real builder and asserts no place or cancel.
• S2: v1 execution is preview-only, and the test is no longer vacuous. ReverseDca declares execution: Execution with Execution = Literal["preview"], as a plain assignment so that rules add’s Literal validation sees it. Its constructor refuses anything else. test_every_sleeve_sell_kind_is_preview_only runs over the registry and fails if no sleeve-sell kind is registered. rules add ... "execution": "auto" exits 1 and writes nothing. The kind is registered (so rules add and _build_rule work), but it is excluded from rules seed, the wizard and research.tuning through agent.seedable_kinds() (R20). rules seed --kinds reverse_dca is refused by name.
• S3: unchanged. The same guards.check runs on every REDUCE intent.
• S4: unchanged. No keel/web/ or keel/mcp/ module names a sell-side operation.

The research freeze holds. This PR adds only unit and cycle tests on synthetic candles, and runs no backtest or sweep.

What changed

• keel/strategy/rules/reverse_dca.py (new) implements spec §6:

  • epoch-aligned cadence, the same as dca’s;
  • a price floor and a drawdown gate over the lookback_days high;
  • floor_qty;
  • gross sized from the net target as target / (1 - fee - slippage), at the SellCosts the caller resolved;
  • no carry-forward, and last_rejection names the gate.

  Rail-2 slicing, the same-day-DCA exclusion, min_hold_days and one proposal per day stay in the pipeline (R11–R14).

• agent.RULE_REGISTRY["reverse_dca"] and agent.seedable_kinds(). The callers rules seed, setup.seed_rule_library and research.tuning.SEARCH_SPACES switch to it. The last one runs at import time and would otherwise raise TypeError.

• tests/strategy/rule_conformance.py:

  • a new ReductionConformanceTests mixin, with an anti-tautology firing fixture;
  • minimal_params(kind), so registry-wide contract tests still cover a kind with required params, pinned against each constructor’s signature.

• Review Focus 5 (Task 9.3): test_a_sleeve_sell_rule_does_not_count_as_managing_a_position runs end to end through gather_findings on a live and a paper profile, each with a positive control. No filter was added (R37, below). all_rules stays the full row set, per #885, so #880/#881 are untouched.

• The P8 item carried into this PR is R36. A repeated refusal is recorded daily and notified once. sleeve.repeats_previous_refusal reads sell_proposals, so it needs no new state and the notification layer still writes exactly one key. ReduceResult.repeats_previous is set by agent._flag_repeat and skipped by events_from_state. A 30-day cooldown now sends 1 alert, not 29. The first veto, any change of reason, and every preview still notify. The check fails open.

Rulings (recorded in the plan)

• R36. Notify a vetoed proposal only when its kind or reason differs from the product’s previous non-superseded proposal. The reason is rails.sleeve plus the vetoing rail names (the text before the colon, because the details carry live numbers). A preview always notifies. Cost if wrong: a standing veto is announced once per change of reason, not daily; keel dca proposals list still shows every row.
• R37. Task 9.3 adds no class filter. Since #897, position.unmanaged keys on (product_id, kind), and a sleeve-sell kind never opens a tranche, so a filter would change no output. The plan’s test therefore passes before any production change. Its non-vacuity is proven by the positive controls and by a mutant that reverts membership to product-only, which turns it red. Cost if wrong: if a future path books a tranche under a sleeve kind, the filter becomes a one-line addition with a red test to drive it.
• R38. Every registry-wide caller that builds a rule from product_id alone reads seedable_kinds(), and the tests use minimal_params. Cost if wrong: a future sleeve kind is absent from SEARCH_SPACES, which is correct while research is frozen.

…truncated — full description in #918.

feat(dca): keel dca distribute —preview and the reverse_dca doctor findings (#857) (#920)

Refs #857

P10 of docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md.

What

Task 10.1: keel dca distribute --preview (keel/commands/sleeve_report.py, keel/commands/dca.py)

• DistributionRow plus distribution_rows(repo, config, now_ts): one row per reverse_dca rule that this profile’s cycle runs (agent._sleeve_rules, R16).
• next_cadence_ts is the smallest epoch-aligned day d >= today with d % cadence_days == 0.
• The gates come from the rule’s own reduce_signal. It runs on the cached daily series, with the last bar re-stamped to d. No arithmetic is copied.
• The size is sliced by sleeve.slice_qty, using the executor’s cached increment and never calling the venue. It is priced at the fallback fee, using record_proposal’s and executor.reduce’s definitions.
• dca_collision reads the pipeline’s same_day_dca refusal ahead of time.
• render_distribution produces the output lines.
• The command opens the DB read-only (_common._open_repo_ro) whether or not it runs at a TTY. It builds no broker (R25) and writes nothing. That is proven by PRAGMA data_version, a per-table row count, and a _build_broker spy that raises.

Task 10.2: sleeve.buy_and_sell_same_asset and sleeve.price_floor_stale (keel/commands/doctor.py)

• sleeve_rule_findings(rules, closes, *, managed_status) always returns exactly two findings, OK when there is nothing to report (#888). It is wired into gather_findings, and both names are in the exact-set test.
• The round-trip text is “two taker legs at the venue’s fee”, with no rate.
• The floor finding WARNs strictly below 0.5 x the latest daily close. It is not judged when there is no close.

Carried item from P8 (R42): feed.stale_open_position now distinguishes two cases.

• It lives in the alert layer (keel/notifications.py), not in doctor.
• For a held product that only a sleeve rule watches, it says that rule’s proposals are paused and that no rule exits the product.
• The key, the WARN and the text for rule-managed products are unchanged.
• A new watched_by field and LoopResult.sleeve_only_products carry the distinction.

Rulings (recorded in the plan)

• R39: gates stop at the rule’s first closed gate. Judging the later gates would duplicate the rule’s arithmetic.
• R40: the collision and the doctor finding count only the rules the cycle runs. That is a live dca beside a paper or live reverse_dca on a live profile, and paper rules only on a paper profile. This narrows the plan’s “any non-disabled dca” so that the preview agrees with the pipeline’s _dca_fires_today.
• R41: qty, gross and fee cover the whole sale, and legs gives the day count. This matches the sleeve.proposal notification’s total_qty.
• R42: the stale-feed wording above.

Sample output (paper profile, $100 per-order cap: the $101 gross slices to 2 legs)

rule 1 (paper) BTC-USD next cadence 1970-07-30: sell 0.001013292404198822246898012188 over 2 legs  gross $101.22  fee $1.22 (fallback:config.fees.taker_pct)  gates price_floor=open drawdown=open floor_qty=open
  a dca buy falls on the same day: the pipeline records it vetoed (same_day_dca), and it is not carried forward
preview only: nothing is placed.

Safety invariants

• S1: unchanged. No new sell reaches the venue. The new command calls no executor placement path and builds no broker. tests/execution/test_sell_side_invariants.py is untouched and green, with RUN_ORDER_CALLERS, PLACEMENT_CALLERS and SECOND_LEVEL_CALLERS unchanged.
• S2: unchanged. reverse_dca is still Execution = Literal["preview"], and nothing here adds an execution value.
• S3: unchanged. No rail changed. The preview reads the pipeline’s sleeve refusal ahead of time and changes nothing.
• S4: unchanged. No keel/web/ or keel/mcp/ module was touched. The command is read-only and not gated. Doctor’s gather_findings, which is shared with MCP, stays pinned read-only by its change-counter test, and the new wiring test also asserts total_changes is unchanged.

Verification

• TDD: every test was watched failing for the stated reason (ImportError or missing command, a TypeError on the new kwarg, a missing exact-set name, an AttributeError on LoopResult).
• Mutation: 17 mutants were applied, each confirmed to change the source, run with PYTHONDONTWRITEBYTECODE=1, and restored from a saved copy with the hash checked. All 17 were killed.
• uv run pytest -q passed: 7570 passed, 3 skipped. ruff check keel tests, ruff format --check and bare mypy are all clean.

feat(sim): the reverse path — distributions in the account sim and the accumulation row (#857) (#922)

Refs #857

P11 of docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md: the sim’s reverse path. reverse_dca distributions are now booked in the edge pass’s accumulation row and in the account sim.

What changes

Task 11.1, report.accumulation_table: the FIFO-faithful per-rule row

• The table now processes accumulating rules per asset, over one FIFO pool of lots. Each lot records the key of the rule that bought it.
• Each dca row reports only its own remaining lots: the qty still held, and the cost net of the basis sold from those lots.
• Each reverse_dca row has buys=0, qty=0 and cost_usd=0. It carries the new DcaSleeve columns: distributions, units_sold, distributed_usd (net), sell_fees and a FIFO-exact realised_pnl.
• New parameter max_per_order_usd: Decimal | None = None, which means no cap. keel simulate passes it config.caps.max_per_order_usd, the same cap the account sim and guards.check read.

Task 11.2, the account sim’s reverse path

• SimAccount.reduce_dca(asset, qty, price, ts, fee_pct) -> (net, fee):
  • It refuses a sale larger than the lot (or of zero, or with no lot) with a ValueError.
  • The sale counts as volume (#86).
  • It releases the sold share of the at-open notional. A lot sold in full is removed.
  • Realised P&L is average cost, against the one averaged lot (R32).
• portfolio_sim._process_reductions makes at most one sale per asset per UTC day and books it as a DcaSell in SimResult.dca_sells. dca_sleeve totals the sales into the sell columns, and an asset sold down to nothing keeps its row.
• Parity test (spec §6), in tests/execution/test_reduce.py: the leg the account sim actually fills passes rail 2 in guards.check, and one increment more is vetoed.

Shared decision. portfolio_sim.decide_sleeve_sale is the one decision both sim passes use. It is built from the live pipeline’s own code:

• the arbitration order sleeve.ARBITRATION_ORDER;
• sleeve.sleeve_refusal, which covers same-day DCA, min_hold_days on the lots actually consumed, and cooldown_days;
• sleeve.slice_qty for rail 2, with no venue increment.

Neither slicing nor the refusals are re-implemented. The sim prices a sale at its own configured fee (SIM_FEE_SOURCE = "sim:fee_pct"), and no fee literal is added to keel/.

Rendering. The accumulation and account-sleeve tables add the five sell columns only when something was distributed. A sleeve with no sales renders byte-for-byte as before, which a test pins.

Safety invariants

• S1: no new sell reaches the venue without keel autonomy on --sells at a TTY. It is unchanged: the sim has no broker and places no orders. RUN_ORDER_CALLERS, PLACEMENT_CALLERS and SECOND_LEVEL_CALLERS in tests/execution/test_sell_side_invariants.py are untouched and green.
• S2: v1 execution is preview-only. Unchanged; no rule class or Execution literal is touched.
• S3: rails apply to sells. Unchanged in live. The sim slices with the same sleeve.slice_qty, at the same config cap, and the new parity test shows the sim’s filled leg agrees with guards.check’s rail 2.
• S4: the browser never gains capability. Unchanged; nothing under keel/web/ or keel/mcp/ is touched.

Research freeze (operator decision, 2026-09-27)

• The freeze holds. Every new test is a fidelity check of the harness: a hand-computed expectation on synthetic, gapless candles, checking that the sim books a distribution correctly (spec §6, “Evidence status”).
• No real history is read.
• No sweep or parameter search is run.
• No claim about returns is made.
• Nothing is appended to docs/experiments/trials-ledger.jsonl.

…truncated — full description in #922.

fix(deps): pyjwt 2.13.0 -> 2.14.0 (CVE-2026-102274) (#927)

The `dependencies` check (pip-audit over the exported `uv.lock`) is red on every head since CVE-2026-102274 was published against pyjwt 2.13.0. The fix is in 2.14.0. It blocks PR #922.

• pyjwt comes in through `coinbase-advanced-py`, which signs the live Coinbase JWT.
• I pinned it to 2.14.0, the smallest release that fixes the CVE, rather than the latest 2.15.1, to keep the change to live auth small.
• Only `uv.lock` changes (uv lock --upgrade-package 'pyjwt==2.14.0').
• Locally, the full suite passes on the new lock: 7516 passed, 3 skipped.
• It reaches `~/keel` only at the next release deploy.

feat(promotion): the sleeve_sell gate, proposal replay, proposals review, —allow-concurrent-dca (#857) (#928)

Refs #857. P12 of docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md.

What

• Task 12.1 — promotion.sleeve_sell_gate (spec §3.7, Q2, Q6). Pure. candidate → paper needs only a clean lookahead on reduce_signal. paper → live also needs SLEEVE_SELL_MIN_PAPER_DAYS = 60 since promoted_at, at least one reviewed paper proposal, and, beside a live dca on the product, --allow-concurrent-dca. Every failing reason is reported at once. A NULL promoted_at refuses rather than reading as the epoch.
• Task 12.2 — routing in attempt_promotion plus the R21 adapter _reduction_as_detect. A sleeve-sell rule is never backtested for a trade floor; the test stubs backtest.backtest to raise. The adapter maps entry = expected_price, stop = 0, target = qty over a fixed one-lot holding. A deliberately peeking rule is flagged, the shipped rule is clean over the same bars, and a spy pins that every view gets the same holding. rules promote gains --allow-concurrent-dca. --force is refused for a sleeve-sell rule (spec §3.7, R45).
• Task 12.3 — proposal replay in keel rules backtest for a sleeve-sell rule (sleeve_report.proposal_replay / render_replay). It replays over a synthetic 1-unit lot bought at the first close, using the live pipeline’s own sleeve_refusal (same-day DCA through each dca rule’s own detect, min_hold_days, cooldown) and slice_qty. Each row gets a FIFO realised P&L, and the terminal value is shown with and without the rule. The headline is at config.fees.taker_pct. A second fee line appears only with --fee-sensitivity-pct (no default). A scan asserts \b0\.009\b appears nowhere in keel/ (R29).
• The rules add --kind reverse_dca hint now works. next: keel rules backtest <id> used to fail with “could not determine a granularity”; it now prints the replay. An end-to-end test parses the printed line and runs it. With no cached daily bars it refuses with a named message instead.
• Task 12.4 — keel dca proposals review <id>. A [y/N] via click.confirm at a TTY, not a capability row (R23). Interactivity is decided first. Off a TTY it opens read-only, prints the proposal and “not a terminal: nothing written.”, and writes nothing (pinned by PRAGMA data_version). The write is chained as sell_proposal_updated. A superseded proposal exits 1, and an already-reviewed one keeps its first review.
• The plan gains rulings R44–R48: the sleeve lookahead warmup and the zero-anchor fail-closed rule, the --force/flag refusals, the paper evidence reading, the replay’s first-leg booking, and review’s off-TTY and re-review behaviour.

Research freeze (operator, 2026-09-27)

The proposal replay ships as a fidelity check only. It replays the operator’s one parameter set, runs no search and has no threshold, and appends nothing to docs/experiments/trials-ledger.jsonl. Its output states verbatim that it is “a mechanical replay of this rule’s own proposals over the cached bars — a description, not a pass mark (spec §3.7), and not evidence for choosing parameters”. Every test uses synthetic candles and hand-computed expectations. 0.009 is never written in keel/; the 0.9% row exists only when the operator types --fee-sensitivity-pct 0.009.

Safety invariants

• S1: no new sell reaches the venue without keel autonomy on --sells at a TTY. Unchanged. The RUN_ORDER_CALLERS/PLACEMENT_CALLERS/SECOND_LEVEL_CALLERS pins are untouched, and nothing in this PR places or cancels. A sleeve-sell rule promoted to live still only proposes (S2).
• S2: v1 execution is preview-only. Unchanged. --allow-concurrent-dca weakens nothing, because a live sell rule places nothing in this build. The promotion line says so.
• S3: rails on sells. Unchanged. The replay applies the pipeline’s sleeve caps; it neither bypasses nor models guards.check, and it places nothing.
• S4: the browser never increases capability. Unchanged. review lives in keel/commands/dca.py, and no keel/web/ or keel/mcp/ module names update_sell_proposal. proposals review is not a capability row (R23): it releases no order.

Deviations from the plan

…truncated — full description in #928.

feat(dca): keel dca trim —preview —view lots and —view bands (#857) (#935)

Refs #857

P13 of docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md.

What

Task 13.1: lots_view (spec §8.1, Review Focus 3) (keel/commands/sleeve_report.py)

• LotRow plus lots_view(repo, config, product_id=None): one row per open positions tranche, through sleeve.holding_of. It covers every rule’s tranches (R8), oldest first. That is the order book_exit consumes, so on PAXG turtle tranche 3 is the first row.
• Each row carries entry_fee_share and cost from Lot, the mark (the latest cached daily close), unrealised, and realised_if_sold. The last is priced by record_proposal’s definitions at sleeve.sell_costs (the fallback fee plus per-product slippage).
• With no mark, the mark and both P&L figures are None, never zero.
• render_lots prints a head naming the fee source, the line “FIFO order — a sale consumes these top to bottom”, one heading per product, and “not tax advice” (spec §8.2).

Task 13.2: bands_view (spec §5, read-only)

• BandRow, BandsReport and bands_view(repo, config). Each target asset’s weight is shown against its renormalised target_weights entry, with the band max(15% x target, 1.5%). A weight is only over or under strictly past the band.
• When an asset is over, the row shows the size back to target and its fee drag. The drag counts both legs: the sell at the product’s slippage, and the redeploy buy at the underweights’ shortfall-weighted slippage, both at the fallback fee.
• A held target with no daily close makes the whole report incomplete, with no rows. A held product outside the targets is named on its own line and is not weighed.
• Research freeze. The view is a display only.
  • Every run prints “band trimming was tested and not adopted (#831) … no performance edge is claimed … keel builds no band_rebalance rule”.
  • Every run also prints “a read-only drift display, not a recommendation”.
  • The rail-14/rail-8 redeploy note is printed too.
  • No band_rebalance rule, sweep, trial or ledger entry is added.

Task 13.3: keel dca trim --preview --view {lots,bands} (keel/commands/dca.py)

• The command always opens the database read-only (_common._open_repo_ro), builds no broker (R25), and writes nothing.
• The tests prove this three ways: PRAGMA data_version, per-table row counts, and a _build_broker spy that raises. Each runs for both views, at a TTY and off one.
• A missing --preview is a usage error. It is named first, because the option is eager. A missing --view is a usage error. --view gain is a usage error until P14 (R24).
• A case-colliding target_weights (#848) is a clean error, not a traceback.
• DISTRIBUTE_PREVIEW_FOOTER is renamed PREVIEW_FOOTER and shared by both previews.

Carried items from P12’s held questions (each test-first)

• (a) The web promotion refuses a sleeve-sell rule (R53). The promote_rule action in keel/commands/setup.py now reads the rule’s registered class over a read-only connection. For a sleeve_sell rule at any status it returns a refusal that names keel rules promote <id> and --allow-concurrent-dca. It starts no job and writes nothing, which PRAGMA data_version pins. It fails closed: a database it cannot read refuses too (review round 2). An entry rule, or an unknown id, still reaches the job; that is the positive control. The S4 web scans are green.
• (b) The config=None fallback in the sleeve gate is stricter (R54). It now counts any non-disabled dca on the product, labelled non-disabled on the gate line, instead of reading live. It therefore refuses a candidate, paper or live dca without the flag. A disabled dca, or a dca on another product, is not concurrent; that is the control. The comment is fixed.

Rulings (recorded in the plan)

• R50: both views mark at the latest cached ONE_DAY close, because the sleeve rules decide on that bar. What is absent stays absent.
• R51: the bands sleeve is the positive target_weights assets’ holdings, renormalised. Untargeted holdings are named, not weighed. BandRow gains value_usd.
• R52: the two-leg drag prices both legs at the size back to target. The buy leg uses the shortfall-weighted slippage.
• R53 and R54: the carried items above.

…truncated — full description in #935.

feat(rules): profit_take in preview, and —view gain as trim’s default (#857) (#936)

Refs #857. P14 of docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md: Task 14.1 (profit_take, spec §4) and Task 14.2 (--view gain, the default), plus the two items carried from P13’s held questions.

Safety invariants

• S1: unchanged. No new sell reaches the venue. profit_take proposes only through reduce_signal → _handle_reductions → executor.reduce in preview. RUN_ORDER_CALLERS, PLACEMENT_CALLERS and SECOND_LEVEL_CALLERS are unchanged, and tests/execution/test_sell_side_invariants.py passes as it stands.
• S2: preview-only. profit_take declares Execution = Literal["preview"], and its constructor refuses anything else. The registry-wide test now also asserts profit_take is in the sleeve-sell set, so it is covered and not only present.
• S3: unchanged. No rail is touched. The trim reaches guards.check through executor.reduce, like every REDUCE intent.
• S4: unchanged. No keel/web/ or keel/mcp/ module names anything new. The web promote_rule refuses profit_take through the class it is registered under (R53). The existing refusal test is now parametrized over both sleeve kinds.
• No profit_take promotion is part of this plan (spec §4: “no profit_take rule is promoted”). The kind exists so the trim report and the proposal log can show what a trim would do.

Research freeze (2026-09-27). This PR runs no parameter search and appends no trials-ledger entry. ProfitTake has no param_space(). It claims no performance edge in code, docs or output. The module docstring and the gain report (GAIN_NOT_EVIDENCE, printed every run) both state spec §4’s evidence status: the gain-over-entry trim is untested, and #831 found the drift half no better than static DCA after fees. The tests are hand computations on synthetic candles. There is no 0.009 literal in keel/, and the existing R29 test still pins that.

Task 14.1: ProfitTake

• On the completed daily close:
  • trigger: close >= vwae × (1 + gain_pct/100), where vwae includes each lot’s prorated entry fee (spec Q4);
  • size: trim_pct (10–20) of the holding;
  • fee gate: qty × (close × (1 − slippage) − vwae) − qty × close × fee >= min_net_usd.
• last_rejection names the gate that stopped it: gain, fee_gate, nothing_held or no_daily_candles.
• The drift trigger is not a param. cooldown_days and min_hold_days are read by the pipeline (R15, R12).
• Registered in agent.RULE_REGISTRY and excluded from seeding by class (R61).
• Conformance: TestProfitTakeConformance(ReductionConformanceTests).
• The P12 gate applies through the class alone. Candidate → paper runs the sleeve gate and is never backtested for a floor. A profit_take that never fires is refused (R44). Paper → live needs 60 days and a reviewed proposal. A promotion_class mutant turns all three tests red, and the 4 web-refusal cases too.
• End to end with the real builder: a stored row proposes one preview trim; the next day’s trim is vetoed by its own cooldown_days; a decline logs agent.reduction_declined with the gate (spec §4: “the reason is logged”).

Task 14.2: keel dca trim --preview --view gain (the default)

sleeve_report.gain_view and render_gain. Every verdict and figure comes from ProfitTake.reduce_signal on the cached daily close, at sleeve.sell_costs. The view only picks the params (R56) and prints them:

• would trim takes its figures from the Reduction;
• below fee gate takes them from last_rejection;
• below trigger prints no sale;
• no cached daily close gives no verdict.

legs comes from sleeve.slice_qty. The report says every run that the pipeline’s caps are not applied (R57).

CLI changes:

• --view defaults to gain.
• --product narrows the gain and lots views.
• --gain-pct and --trim-pct are checked by the rule’s own constructor.
• A flag that does not apply to the chosen view is a usage error (R60).

Sample output (the CLI test fixture: synthetic ledger, bars from 1970, so both products are flagged stale):

…truncated — full description in #936.

feat(execution): the sleeve exit monitor — transition alerts, doctor, keel dca exit —preview (#857) (#937)

Refs #857

This is P15 of the sell-side build plan (docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md). It adds the sleeve exit monitor from spec §7. It only alerts and previews: it never places, cancels or writes an order.

What it does

• Task 15.1: keel/execution/sleeve_exit.py. A pure classify that places a product at clear, near, breached or insufficient_history against two arms:

  • drawdown: 35% under the 200-day high;
  • sma: three closes in a row under the 200-day SMA.

  near has hysteresis: a product enters within warn_pct and leaves beyond 2× warn_pct. The default levels are module constants taken from spec §7 (R26). monitor_rule and monitor_params read a sleeve_exit rule’s overrides. P16 registers that kind.

• Task 15.2: agent._watch_sleeve_exits, the last step of run_once.

  • It watches every product that has an open tranche with no resting bracket. It reads the positions ledger, never the unbracketed: retry record, which was #811’s silent channel.
  • It records sleeve_exit:<product> and returns level changes only, on LoopResult.exit_watch_transitions.
  • R27 and R70: a watched product that no rule polls (PAXG tranche 3) gets its own daily history, fetched per product and wrapped. The fetch is a market_feed.backfill over sleeve_exit.history_days (203 days at the defaults), so a cold cache is judged on the history the arms name rather than on one bar. Once the window is full it requests only the newest bar. It never writes last_feed_ts and never joins the products that equity is marked over.

• Task 15.3.

  • A new sleeve.exit_watch notification (WARN, execution), one per transition. The wording follows the level, and a return to clear reads as a recovery (plan OQ10).
  • doctor.exit_watch_findings (sleeve.exit_watch). With no records it returns one OK sentinel (PR #888), and the name joins the exact-set test.
  • keel dca exit --preview: read-only and builds no broker.

• Item carried from P14: every sleeve view (gain, distribute, exit) skips a rule row that fails to build and prints one SKIPPED rule <id> (<kind>, <status>) line naming it. Before this, a bad profit_take row crashed the whole gain view (a ValueError traceback).

• Rulings R63–R71 are added to the plan. R70 and R71 came out of review round 1.

Cycle ordering (pinned)

The cycle runs: reconcile → equity (rail 11) → entries pre-pass → exits and entries (the DCA buy) → _manage_stops → record_venue_holdings → P8’s sleeve-only poll → _handle_reductions → _watch_sleeve_exits (its R27 poll is inside it and wrapped) → notifications.

• test_the_watch_poll_runs_after_the_buy_and_its_failure_costs_nothing: the index of PAXG’s candle request is after the BTC BUY’s. A PAXG poll that raises still leaves the buy placed and the cycle complete, and the level reads insufficient_history. A mutant that runs the watch straight after the entry poll turns this test red.
• test_a_monitor_that_raises_costs_neither_the_cycle_nor_the_dca_buy covers the per-product wrap, and test_a_watch_that_raises_before_any_product_costs_nothing covers the outer wrap in run_once.
• test_a_cold_cache_is_filled_with_the_history_the_arms_need: a cold cache fills to 202 bars, so an SMA break is confirmed in the same cycle. The next day requests only the one new bar.
• test_the_watch_poll_never_writes_the_rail_12_heartbeat: last_feed_ts is written exactly once, by the entry poll. The test counts the writes rather than reading the value back.
• test_paxg_tranche_3_is_watched_although_no_live_rule_polls_paxg: the config polls both ONE_HOUR and ONE_DAY, and the watch still polls only ONE_DAY.

Equity is unchanged (pinned)

test_a_held_product_the_watch_polls_does_not_move_equity: PAXG is held at a cost of 80 and no rule covers it. The watch caches a close of 100. Equity is 1,000,080 on both that cycle and the next one, which runs with the close already cached. That is PAXG at cost, so rail 11 does not move. P8’s test_a_sleeve_rule_does_not_move_equity still passes unchanged.

Safety invariants

…truncated — full description in #937.

feat(rules): sleeve_exit, preview-only (#857) (#939)

Plan P16 (docs/superpowers/plans/2026-09-28-dca-sleeve-sell-side-build.md), Task 16.1. Refs #857: it does not close it (ruling R77, below).

What this does

• SleeveExit (keel/strategy/rules/sleeve_exit.py) is the second layer of spec §7.

  • reduce_signal calls the monitor’s own keel.execution.sleeve_exit.classify at the rule’s params. It returns a Reduction for the whole holding only on breached. near, clear and insufficient_history decline, and last_rejection names the level.
  • Params: dd_pct 35, lookback_days 200, sma_period 200, confirm_days 3, warn_pct 5, arms ("drawdown", "sma"). These are R26’s spec constants, untuned.

• Registration. It is in agent.RULE_REGISTRY and excluded from rules seed and the wizard by class (R20/R38/R61). minimal_params needs no entry because every param has a default, and the pinning test covers that.

• Existing gates reach it by its class alone:

  • conformance (TestSleeveExitConformance);
  • the P12 sleeve_sell promotion gate (candidate→paper via the lookahead, refused when it never fires, and paper→live needing 60 days plus a reviewed proposal);
  • the P13 web refusal (R53).

  A promotion_class mutant and a registry-removal mutant each turn these red.

• R13 is exercised end to end. A tranche bought 2 days ago is still proposed, and a mutant that empties MIN_HOLD_EXEMPT_KINDS turns that red. The same-day-DCA exclusion still applies: a breach on a buy day is recorded vetoed (same_day_dca), and the BUY still goes out.

• R36. The next day’s identical veto carries repeats_previous, and sleeve.proposal skips it.

• Rail 2. A whole sleeve over max_per_order_usd becomes 3 legs in the proposal row.

• R69 is retired (R72). monitor_rule/monitor_params move to the rule module and select isinstance(rule, SleeveExit), using the constructed rule’s validated params. A rule merely named sleeve_exit no longer sets the levels (new agent test). The pure monitor keeps its single import.

Carried items from P15’s held questions

• (a) Constructor validation (R73). The constructor now refuses:

  • arms that is not a list of distinct known arm names. A bare string ("sma") is refused by name. agent.build_rule_from_params no longer splits a JSON string into letters.
  • non-positive or non-int lookback_days, sma_period or confirm_days, bool included;
  • dd_pct outside (0, 100) and warn_pct outside [0, 100), and either one if it is not finite (NaN, sNaN, ±Infinity).

  rules add writes nothing for any of these.

• (b) Per-product wrap in exit_watch_view (R74). A watched product whose sleeve_exit: record is not a mapping, has a non-string level or a non-int observed_at, or whose read raises, prints one SKIPPED <product>: ... line. keel dca exit --preview still prints every other product and exits 0.

• (c) Severity (R75). sleeve.exit_watch is WARN only for near and breached. “Now watched”, “recovered” and insufficient_history are INFO.

  • keel-core fixed severity per key, so notification_event gains a keyword-only severity that may lower an occurrence below its key’s declared ceiling and never raise it. An unknown severity is a ValueError.
  • Delivery routes on the key, not on severity. A test pins a lowered event through send_event.

• (d) Delivery failure: HELD (R76). There is no retry or outbox pattern to reuse.

  • send_event makes one attempt by design, and sleeve.proposal behaves the same way.
  • #793’s ledger works only because attestation events are re-derived from state. Exit-watch events are transitions.
  • Adopting that ledger would need a second write key in the notification layer, which R19 and tests/test_notifications.py pin to exactly one. That is the operator’s design call.
  • The level itself is never lost: keel doctor WARNs on near/breached every run, and the preview prints it.

Safety invariants

…truncated — full description in #939.

fix(rails): exposure resets at the moment a product goes flat (#943) (#946)

Closes #943.

What

R33 zeroed a fully closed product’s exposure only while it STAYED net flat: _open_exposure_by_asset netted the product’s whole order history and tested qty > 0 once at the end, so the closed round-trip’s notional residual — a real gain or loss, which is not exposure in either direction — came straight back with the product’s next BUY. On live PAXG that is ~$6.36 of phantom exposure one DCA cadence after the first keel positions close, counted by rails 4/5/6 for as long as PAXG is held again. A close at a gain had the opposite sign: $100 really held read as $0.

The fix

The walk is now chronological — (created_at, id) order, which matters because the reset fires at a MOMENT and get_orders returns each status group in id order, not the groups in time order — and the bucket’s notional AND quantity reset to zero the moment its running quantity passes through zero. A product still net long that never went flat nets exactly as before (test_a_partial_close_still_nets_by_notional stays green untouched); one that went flat starts its next position from zero, which is R33’s own rule applied at the only moment it can mean anything.

Tests (written first, shown failing for the right reason: {'PAXG': Decimal('23.606636')} vs 20.00)

• test_guards.py: re-entry after a full close at a loss (ids deliberately anti-chronological to pin the sort) and after a full close at a gain.
• test_positions_close.py: the declared-close → next DCA buy integration, the exact path the review reproduced on the live copy.

fix(execution): a watching rule’s fee quote can no longer halt the next day’s buys (#944) (#947)

Closes #944.

What

Two rulings landed together in the build and together they broke the sell side’s own headline guarantee (“nothing added can delay, block or mis-size a buy”):

• R16 handed a paper-STATUS sleeve rule the live broker on a live cycle — “proposals against the real book” — so a rule that only watches asked the venue for a fee quote.
• R-P7-2 wrote the trade-scope refutation when that quote was refused with TradeScopeDenied, and rail 20 then vetoed every live entry from the next cycle.

A watching sell rule on a key whose permissions refuse preview calls could therefore halt the DCA program’s next buys.

The fix (the reviewer’s wording, accepted by the operator)

• R78: a paper-status rule proposes OFFLINE even on a live cycle — offline=True, no broker, fallback fee, offline rails. paper still rides onto the row; the sleeve caps still judge it against the cycle’s own DCA (dca_fires_today keeps the CYCLE’s mode); a LIVE rule’s proposal is still quoted at the venue, unchanged.
• R79: executor.reduce never writes the trade-scope refutation. A refusal on a sell preview stays on the proposal row (rails.preview_error, WARN executor.reduce_preview_denied); #233’s refutation remains a placement-path fact (_run_order), and the ERROR event an operator greps for when entries stop keeps meaning that.

The original R-P7-2 rationale argued the wrong direction: if the trade scope is really gone, the next BUY’s own preview refuses on its own, exactly as it did before any sleeve rule existed.

Tests

• test_reduce.py: the denied preview no longer refutes the credential, and the next DCA buy clears the rails.
• test_agent.py: the cycle-ordering test now pins that a denied sell preview stops NO buy — today’s (ordering) or tomorrow’s (no refutation); the paper-in-live-cycle test pins that the venue is never asked.

Plan doc: R78/R79 with their costs-if-wrong.

fix(execution): a permissions refusal on a bracket leg is definite — rejected and retried, not state-unknown (#945) (#948)

Closes #945.

What

R5 booked every post-row bracket-leg raise the same way: the pending row stayed, the unbracketed: retry was cleared, and a CRITICAL executor.bracket_state_unknown parked the product’s exits on a human — correct for a timeout, where the venue really may be holding the order. TradeScopeDenied was folded into that bucket on purpose, but a permissions refusal is a DEFINITE answer: the venue did not take the order, nothing rests at the exchange, and there is no unknown to reconcile.

The fix (the review’s S-6, R80 in the plan)

A dedicated except TradeScopeDenied ahead of the broad handler:

• the written row is marked rejected — the status a broker-rejected placement already takes in _run_order, and what reconcile’s own docstring says a broker rejection writes;
• the unbracketed: retry record is armed (not cleared), so reconcile_unbracketed_positions re-places next cycle and heals the moment the credential trades again — a rejected row is not a resting one and blocks nothing;
• a CRITICAL executor.bracket_refused names the position: unprotected, loudly, but not unknown.

Timeouts and every other raise keep R5’s state-unknown booking unchanged. _run_order’s refutation write (#233) is untouched — a placement-path refusal is a credential fact; only its row bookkeeping changes. A refusal at the PREVIEW (before any row exists) keeps the pre-row retry path it always had.

Tests

• test_bracket_downgrade.py: the parametrized place-raise test keeps only the ambiguous timeout; a new test pins rejected-row + armed retry + bracket_refused + no unknown event, and a preview-stage refusal still writes no row.
• test_reconcile.py: the sweep-level mirror of the #892 timeout test — first sweep refuses (rejected row, retry survives, escalation says retry_scheduled=True), second sweep with a working broker heals.

Plan doc: R80 (note: this branch and #944 both append after R77 — trivial conflict, keep R78/R79 then R80).

chore(release): 0.21.0 — the sell side in preview, and three review fixes (#949)

Version bump only: every workspace pyproject.toml 0.20.0 -> 0.21.0 plus the refreshed uv.lock, the same nine files every bump moves (tests/test_packaging.py green locally). Merge this, then run the Release workflow with 0.21.0.

MINOR: new preview-only commands and a rail change of scope; schema 21 -> 22, additive (sell_proposals). P17/P18 — live sell placement — are NOT built; every sell rule remains preview-only.

What lands since 0.20.0:

• The sell-side build, P1-P16: #889, #896, #898, #901 (prerequisites #799/#811/#798), #905 (#900 forward fix: book at the venue’s filled size), #908-#914 (contracts, sell_proposals schema v22, executor.reduce in preview, reductions running last in the cycle), #918-#928 (reverse_dca, keel dca distribute --preview, the sim reverse path, the CLI-only sleeve_sell promotion gate), #935-#936 (keel dca trim --preview, profit_take), #937-#939 (the sleeve exit monitor, sleeve_exit).
• #927: pyjwt 2.13.0 -> 2.14.0 (CVE-2026-102274).
• The end-to-end review’s three fixes: #946 (#943 — exposure resets at the moment a product goes flat), #947 (#944 — a watching rule’s fee quote can no longer halt the next day’s buys; R78/R79), #948 (#945 — a permissions refusal on a bracket leg is definite: rejected and retried, not state-unknown; R80).

Live impact (from the review, unchanged by the three fixes): buys cannot be delayed, blocked, mis-sized or moved by anything here; each buy waits up to 3.5s for the venue’s final fill and books at the filled size; one extra balance read per cycle; the 21 -> 22 migration only adds a table (ran clean, idempotent, and reversible on a read-only copy of the live DB); no notifications configured on live.

Deploy note: build from this clean tag/commit only — the current ~/keel 0.20.0 binary self-reports (DIRTY).

Built from a7fe3fab46cf. Version binds to this hash: keel --version reports keel 0.20.0+a7fe3fab46cf [release].

Install

Download all wheels from this release into one directory, then install the keel_trader wheel by path:

pip install --find-links . ./keel_trader-0.20.0-py3-none-any.whl
keel versions

keel versions — not keel --version — is the check: it reports every keel distribution in the venv and exits non-zero if a sibling was left behind at an older version, which --version cannot see. Upgrading an existing deployment: see “Deploying a new version” in the README.

⚠️ Never install by bare name. The distribution is keel-trader; the name keel on PyPI belongs to an unrelated project, so pip install keel fetches someone else’s package. A build reporting DIRTY or [checkout] is not this release and must not be run against live funds.

Configure

config.yaml is attached to this release: the production config, in auto_trade.mode: confirm — keel previews every order and waits for your approval. Drop it beside the install (or run keel init-config --live), put your CDP key in a git-ignored .env, then:

keel migrate     # existing database: apply schema migrations
keel init        # fresh deployment: write config + seed candidate rules

Seeded rules start as candidate and trade nothing until you promote them.

Other changes

feat(dca): keel dca plan — propose a DCA schedule within the venue plan’s cap (#846)

PR 1 of docs/superpowers/plans/2026-09-27-dca-plan.md (Tasks 1–6): the plan service and the keel dca plan CLI. The read-only web card (Tasks 7–8) comes in PR 2.

Behaviour

• keel dca plan --budget <monthly USD> --buffer-pct <fraction> [--cadence-days 7] proposes a weekly DCA schedule.
  • The universe is allowlist ∩ admitted by screen_product ∩ positive target_weights, minus assets that already have a non-disabled dca rule. Weights are renormalised over that set.
  • Every excluded asset is listed with each reason that applies: not_on_allowlist, not_admitted, no_weight, or has_dca_rule. An asset with a DCA rule is shown as “existing, unchanged”.
• Spend is budget × (1 − buffer). It is checked against rail 14’s monthly buy cap for the deployment’s venue, read exactly as guards.check reads it. A parity test drives guards.check at the cap and one cent over it.
• Rail 14 is stated as a monthly BUY cap, never a fee waiver (#836). “fee-free” appears nowhere.
• Fees are estimated at the configured fees.taker_pct and labelled as such. The venue minimum order size is unknown to keel, and the output says so.
• At a TTY the prompt is [Y] Approve / [E] Edit weights / [N] Cancel.
  • [Y] writes one candidate dca rule per asset through rules.add_rule_row, all or nothing (R2).
  • The command never promotes, never writes paper or live, and never touches an existing rule.
  • A blocked plan does not offer [Y].
• Off a TTY it prints the plan, writes nothing, and exits 0 when the plan is approvable or 1 when it is blocked.
• keel/commands/dca_plan.py is a pure service with no click, ready for PR 2’s GET-only reader. keel/commands/dca.py is the thin click front-end.

Rulings in force

R1–R19 as in the plan, with these changes:

• R7 amended (after #843). Each existing live DCA rule’s monthly commitment uses that rule’s own budget_usd, because the executor sizes each DCA buy from the rule’s size_usd. The commitment is added to spend, and the plan warns, without blocking, when the sum exceeds the cap. A live rule with dip_bonus_pct > 0 gets its own warning, since its buys can exceed the listed amount.
• R9 withdrawn. There is no “executor sizes DCA from config.dca.budget_usd” warning, and no executor_budget_usd field. A test pins the warning’s absence.
• #842 note. Nothing in the output describes max_exposure_usd as a DCA limit, and a test pins that.
• R20 (new). Interactivity is decided once, first. Off a TTY the database is opened with _open_repo_ro (mode=ro), so the preview cannot create a missing DB file or migrate an old schema.
• Write-loop sqlite3.Error (new). A locked database mid-write is caught and refused, and the refusal names the rule ids already written. This is R2’s stated cost-if-wrong, now made explicit.

Test evidence

• New files: tests/commands/test_dca_plan.py and tests/commands/test_dca_cli.py. tests/test_rail14_is_a_buy_cap.py gets one test, and SERVICE_MODULES gets two modules.
• Each task was TDD red then green. Mutations were proven applied, then shown to be killed:
  • a write inside select_universe;
  • config budget used instead of each rule’s own in R7;
  • rail 14 note removed from the render;
  • pre-validation loop removed from apply_dca_plan;
  • rail 14 no-record cap changed.
• Fixtures are proven to reach the code under test: the fake screen_fn is called 3 times, the patched build_rule_from_params is called for PAXG, the patched add_rule_row is called twice, and _open_repo_ro is called once off a TTY.
• uv run pytest -q: 6962 passed, 3 skipped, exit 0.
• uv run ruff check keel tests exited 0, uv run ruff format --check keel tests exited 0, and bare uv run mypy exited 0.
• Manual sanity run: the template config against a fresh migrated temp DB, off a TTY. It exits 1 with named blockers: every asset is unadmitted, and rail 14 is at $0 with no attestation, together with the attest command. The DB checksum is unchanged.

guards.py and executor.py are untouched.

feat(web): read-only DCA plan card on /rules (#850)

PR 2 of docs/superpowers/plans/2026-09-27-dca-plan.md (Tasks 7–8). This PR builds on PR 1 (#846) as merged, not on the plan’s snippets.

What it does

• GET /api/dca-plan?budget=&buffer= answers from the same service as keel dca plan (build_dca_plan). The admission screen is resolved per call.
  • It is read-only and writes nothing, which is pinned by a rules-row count after a request. It is GET only; a POST gets a 404.
  • Money crosses the wire as strings, values arrive presentation-ready, and state is an explicit field.
• No budget: the route answers an awaiting_budget payload with the same keys as the ready one, every figure absent, and the command template.
• The worst-month cap check (#847) is on the wire and on the card.
  • cap_check is the worst UTC calendar month rail 14 was compared against, with the checked total as its value.
  • It is judged bad over the cap, good within it, and neutral when the tier is unlimited.
  • The card shows it as “checked against the cap: worst calendar month for a 7-day cadence, 5 buy day(s) x $103.47 per cycle = $517.35”.
• The card on /rules sits under the rule ledger and reads the page’s own address: /rules?budget=500&buffer=0.1.
  • It shows the summary figures, the per-asset schedule, the excluded assets with their reasons, the existing DCA rules (unchanged), the blockers, the notes, and the exact CLI command with --config/--db for the served deployment.
  • It has no button, anchor, form or input, and no event handler.
• A refused read (a bad ?budget=, or a config the service refuses) leaves the ledger standing. The card says it could not read the proposal and places the server’s reason, in the service’s own words.

Rulings

• R21: every DcaPlanError is a 400 ApiRefusal. This includes the ones build_dca_plan raises over the config (target_weights keys colliding by case, a non-finite weight).
  • Why: ApiRefusal is this module’s only way of saying “declined, and here is why”. The CLI refuses the same error as a clean message. A 500 would read “That report could not be built” over a message that already names the fix.
  • Cost if wrong: a config problem is reported with a client-error status. The body still names the config key to fix.
• R22: the worst-month sentence is written once, by a new service function dca_plan.worst_month_text(plan). The CLI’s checked against the cap: line and the payload’s cap_check.display both use it.
  • Why: two front-ends wording, or re-totalling, the figure the blocker compared is the #847 drift.
  • Cost if wrong: a one-function change to PR 1’s module. The CLI line is byte-identical, and a test pins that.
• R23: the card receives the secondary reading’s error as well as its data (rulesView(data, sort, onSort, plan, planError)).
  • Why: with data alone, a 400 would show a bare “could not be read” and throw away the reason, such as the fraction hint for buffer=10.
  • Cost if wrong: one extra parameter.
• R24: no service-worker cache bump. The worker’s cache name is keel-shell-<full_version>, which is <version>+<commit>, so every new commit is a new cache. /api/ is never cached, and a new test pins that every API_ROUTES path sits under API_PREFIX.
  • Why: earlier web PRs changed static JS without a bump for the same reason.
  • Cost if wrong: none; the mechanism is structural.
• R25: the card’s three row collections (buys, excluded, existing) are enrolled in the row-key scan, not exempted. A seeder patches the screen to admit BTC and reject PAXG, and writes an existing ETH DCA rule. The endpoint is asked with a budget, so every collection has a row.
  • Why: the plan said not to use an exemption.
  • Cost if wrong: _seed_for now takes monkeypatch.

Test evidence

• uv run pytest -q: 7021 passed, 3 skipped (exit 0).
• uv run ruff check keel tests: exit 0.
• uv run ruff format --check keel tests: exit 0.
• uv run mypy (bare): exit 0.
• node --check on render.js and main.js: exit 0 for both.
• Structural client tests:
  • The card’s tags are on a closed list, with a scan that sees a mutated-in button.
  • Exactly one code element, paired with plan.command.
  • One table, with no sort pair.
  • Every served key and summary figure is paired with a read.
  • Exactly one figure reads plan.cap_check, under “checked against the cap”.
  • The ROUTES row, and the mount call passing both the reading’s data and its error.
  • The page-address seeding: one location.search read, names budget/buffer only, and the dca-plan bag only.
• Mutations applied and killed, each confirmed to have changed the source before the run:
  • A module-level screen_product import fails the route tests (the patch no longer reaches the reader).
  • Removing the DcaPlanError catch fails the config-refusal test.
  • Renaming row keys (row.fee, item.reasons, rule.per_buy) fails the row-key scan.
  • Dropping the cap_check figure, dropping a table cell, dropping planReading.error, widening the seeded names, and not placing error.detail each fail their test.
• Browser check (Playwright): a real keel serve on a copy of keel/templates/config.yaml with a temp DB, on a free port. The service worker was unregistered and its caches deleted first.
  • /rules?budget=500&buffer=0.1 shows the blocked state with the real screen: nothing admitted on an empty DB, every asset listed as excluded with the screen’s reasons, and the exact command.
  • /rules with no query shows the awaiting state and the command template.
  • Both loads had 0 console errors or warnings, 0 controls in the card, and 1 code element. The rule ledger stays in place.
  • At 390px there is no horizontal scroll.
  • buffer=10 shows the 400 detail (“…0.1 means hold back 10%”) under the standing ledger. The only console entry is the browser’s network log of that 400.
  • A second server with the screen patched to admit everything and a $600 attested cap showed the populated 7-row schedule, “ready to apply from a terminal”, and the worst-month check $517.20 judged good.

Deviations from the plan

• The payload has one more key than the plan’s shape: cap_check, the #847 amendment.
• rulesView takes a fifth parameter, planError (R23).
• The card’s excluded and existing lists are built with .map over explicit keys, so the row-key scan checks them. The plan had one generic list helper that read every key.
• The empty-table text is “No buys planned.” rather than “No asset is eligible.”, which was false in the awaiting state.
• A small .dca-plan .dca-command CSS rule shows the command as a selectable block.

chore(deploy): sync live-rules.json with the live rule set (#855) (#858)

Closes #855

Regenerates deploy/live-rules.json from the live rule set. I made a read-only copy of ~/keel/keel-live.db with Python’s sqlite3 backup API (source opened mode=ro) into a scratch dir, and ran scripts/rule_manifest.py export against that copy. Nothing under ~/keel was written.

Live DCA rules (status live)

id	product	budget per buy	cadence
6	BTC-USD	$40	7 days
8	ETH-USD	$25	7 days
9	PAXG-USD	$25	14 days
10	ADA-USD	$15	14 days
11	XLM-USD	$15	14 days
12	DOGE-USD	$15	14 days
13	FET-USD	$15	14 days

All seven have dip_bonus_pct 0 and lookback_days 90.

The turtles are paper. The six turtle_breakout rules (BTC, ETH, PAXG, ADA, XLM, DOGE) are status: paper. The old manifest listed five of them as live.

Rulings

• Updated test_committed_manifest_is_valid. It pinned exactly one DCA rule and pinned that rule’s params to Dca’s constructor defaults. The regenerated manifest breaks both: there are 7 DCA rules, and none uses the default $50. The test comment itself says to update it when this happens. It now asserts:
  • every DCA rule is live;
  • no rule is candidate;
  • every DCA rule differs from the constructor defaults on at least one param, so a keel init reseed would show as a change in value, not only a change in status.
  • Why: the brief expected the test to pass as-is (#843/#844 dropped the budget pin), but the count pin and the defaults-coincidence pin were still there.
  • Cost if wrong: one test’s assertions need re-tightening. No runtime effect.
• Refreshed one sentence in scripts/rule_manifest.py’s module docstring. It said the live DCA rule is 50 on purpose, matching the default. That is no longer true.
  • Why: keel keeps its rules in docstrings, and a stale one misleads.
  • Cost if wrong: none.

Test evidence

• uv run pytest -q: 7027 passed, 3 skipped (exit 0)
• ruff check keel tests scripts: exit 0
• ruff format --check keel tests scripts: exit 0
• mypy: exit 0
• Mutation checks. For each, I confirmed the file differed from a saved copy before running, then restored it from that copy:
  • set BTC budget_usd to "50", so the rule equals the defaults: the value assertion fails, naming BTC-USD;
  • set one DCA rule’s status to paper: the status assertion fails.

docs(spec): DCA sleeve sell side — trims, rebalancing, reverse DCA, protective exits, rotation (#857) (#859)

Design spec for #857, docs only. The issue stays open for the operator’s review; nothing here is implemented.

Spec: docs/superpowers/specs/2026-09-28-dca-sleeve-sell-side-design.md

What it decides

One architecture for five sell-side features that all sell from the same unbracketed DCA holdings:

• Action.REDUCE and Rule.reduce_signal. Today Rule can only express “buy” or “sell all”, position_rule:<product> has one owner (dca, whose exit is hardcoded False), so no live path can sell a DCA tranche at all. Every sell-side feature becomes a named rule kind (profit_take, band_rebalance, reverse_dca, sleeve_exit, rotation) on a rule row, which is what satisfies rail 10 and gives the audit trail its vocabulary.
• Lots and average entry come from the positions ledger (FIFO, entry fees in the basis), never from orders; two doctor findings surface drift between the two and against the venue.
• Rails per leg. No rail is added, relaxed or DCA-exempted for sells. Rail 2 gates sells too, so a whole-sleeve sale above max_per_order_usd is sliced one leg per cycle. The redeploy BUY leg of a rebalance or rotation meets rails 8 (no averaging into losers) and 14 (the monthly buy cap that now bounds DCA) as a non-DCA buy.
• A separate sells gate. Sell-side rules ship execution: preview; placing needs a typed yes at a TTY per proposal, or execution: auto plus a new keel autonomy on --sells window. The live autonomy flag does not release the new sell class. No web or MCP verb.
• Audit: a sell_proposals table for every evaluated reduction, placed or not, chained into audit_events; trade_outcomes.is_dca derived from the tranches so rail 16 never counts a sleeve sale.
• Promotion: a sleeve_sell class with a proposal-replay description and a 60-day paper period, because these rules have no R for the backtest gate.

Per-feature verdicts

#	Feature	Verdict
1	Profit-taking and trimming	preview-only: keel dca trim --preview; the drift trigger is #831’s arm D (not better); the gain-over-entry trigger is untested and would be accumulation policy’s 4th pre-registered trial
2	Steering and band rebalancing	don’t build (yet): #831 arms C and D, pre-registered and bootstrapped, are not better than static DCA after fees; the read-only bands view is folded into the trim report
3	reverse_dca	build, in preview: a spend plan, not an edge claim; gates on price floor, drawdown, floor quantity, same-day DCA; refuses to go live beside a live dca on the product unless typed
4	Protective exit monitor	preview-only alerts on level transitions, after #811 and #799 land; never an automatic sell, since a structural stop negates the sleeve’s accumulate-through-drawdown thesis
5	Rotation and tax-loss harvesting	don’t build (yet): no jurisdiction anywhere in the repo, so no tax number can be computed; the KB flags sale-and-buyback as a fabricated round trip (§65.11), recorded as a fiqh finding; build keel pnl --lots and #798’s positions close instead

Evidence the requests ran into

• Requests 1 and 2 were measured by #831 (docs/experiments/2026-09-27-accumulation-policy.md): no arm beats static DCA under D6; band trimming’s +13.5% on the one historical path is taken back by the bootstrap (36–43%).
• The request’s 1.20% fee is the sim figure; live pays 0.9% taker. Live gates use the venue’s previewed commission with 1.2% as the recorded fallback.
• Rail 14 is a buy cap and never touches a sell, but the redeploy leg spends it.
• #811’s doctor findings are not implemented yet; #799 is a recording defect, not the monitor gap. Both are prerequisites for feature 4.

Refs #857. Not “Closes”: the operator reviews the recommendations and the twelve open questions in §12.

feat(dca): a cap-blocked plan names the largest passing budget and buffer (#854) (#867)

Closes #854

When rail 14’s worst-calendar-month check blocks a plan, the blocker now names two values:

• the largest --budget that passes at the given buffer;
• the smallest --buffer-pct that passes at the given budget.

One service function, _passing_suggestion_text, builds that clause. plan.blockers carries it, and the CLI (render_dca_plan) and the /rules card (dca_plan_payload) both show it unchanged.

The issue’s worked example ($500 budget, 0.10 buffer, weights .4/.3/.3, 7-day cadence, $500 cap) now reads:

planned spend $450.00/month; the worst calendar month for a 7-day cadence holds 5 buy day(s), which at $103.47 per cycle is $517.35 — that exceeds rail 14’s monthly buy cap $500.00 on coinbase; the largest —budget that would pass is 483.26; the smallest —buffer-pct that would pass is 0.1302

How

• _per_buy_usd is factored out of build_dca_plan’s loop. _worst_month_spend_for is the whole R5 pipeline: spend rounded down, each per-buy rounded down, summed, then multiplied by the worst month’s buy days.
• Two searches find the values: one over cents for the budget, one over 0.0001 steps in [0, 1) for the buffer. Each search calls that same pure function, never a closed-form inverse, so a suggestion cannot drift from what a re-run computes. Each boundary is checked on both sides.
• DcaPlan.max_passing_budget_usd and DcaPlan.min_passing_buffer_pct hold the values (or None). The text is built from those fields, and they are formatted with format(x, 'f'), so they never print with an exponent.
• New ruling R20 is in docs/superpowers/plans/2026-09-27-dca-plan.md and in build_dca_plan’s docstring.

Rulings

• Existing live commitments (R7) are reserved before the search. The searches subtract the existing live DCA rules’ own worst-month commitment from the cap first, and the clause names that reservation whenever it is above zero.
  • Why: the brief says to include R7. The R6 blocker itself compares only this plan against the cap; R7 only warns. So the suggestions are stricter than the blocker.
  • Cost if wrong: when live rules exist, the suggested budget is lower than what would clear the blocker alone. The operator can still go higher and accept the R7 warning.
• Deviation: “one step past is blocked” holds only when there are no live rules. With live rules present, one cent past the suggestion clears the blocker but raises the R7 combined-total warning. The test asserts exactly that.
  • Why: making R7 a blocker would reverse the operator’s R7 ruling (warn, don’t block).
  • Cost if wrong: if the operator wants a strict blocker boundary here, the clause should drop the reservation. That is a one-line change.
• Suggestions also appear on the degraded-cap branch (cap unattested or lapsed, $0).
  • Why: the brief names “cap $0” as a case that must say “no buffer passes”.
  • Cost if wrong: extra text beside the “attest” instruction.
• When nothing passes, the clause says so in words. It reads “no positive —budget would pass” or “no —buffer-pct below 1 would pass” instead of giving a number.
  • Why: this is in the brief.
  • Cost if wrong: none.
• The searches keep internal asserts on their boundary.
  • Why: monotonicity is proven in the docstring. The assert turns any rounding surprise into a loud failure rather than a wrong suggestion.
  • Cost if wrong: a surprise would give the web reader a 500 instead of a slightly-off number.
• payload.py is unchanged.
  • Why: the card already passes plan.blockers through unchanged, so the shared text reaches it for free.
  • Cost if wrong: if the card later wants the values as separate fields, that is a follow-up.

Test evidence

• The worked example pins 483.26 and 0.1302.
• The re-run proof calls build_dca_plan at each suggested value and asserts approvable. At one cent more on the budget, or 0.0001 less on the buffer, it asserts exactly one blocker, and that the plan carries the same suggestion.
• With a live rule: the suggestions pin 434.94 and 0.2172. At the suggested budget, neither the blocker nor the R7 warning fires. One cent more raises the R7 warning. Replaying the suggestion computed without the live rule also raises the R7 warning, which shows the reservation changes the result.
• The two “nothing passes” cases each have a test: existing commitments already over the cap, and a $0 cap with a large budget.
• A test checks that the values never print with an exponent.
• Mutation check: I made the budget search return one cent too many and confirmed with cmp that the file changed. Three tests failed, including the re-run proof (the plan was still blocked at 483.27). I restored from a saved copy and cmp confirmed it was identical.
• Full checks after the final commit:
  • uv run pytest -q: 7033 passed, 3 skipped (exit 0)
  • ruff check keel tests: exit 0
  • ruff format --check keel tests: exit 0
  • mypy: exit 0
  • no JS changed.
• Not strict TDD: the worker got the pinned numbers from a standalone spike instead of watching those tests fail first. The re-run tests don’t depend on those numbers, and the mutation check shows they fail when the search is wrong.

Touches keel/commands/dca_plan.py, which #853’s PR also edits. Expect a small merge conflict near the blocker code.

fix(rails): exempt DCA buys from rail 6; dca plan checks rails 3 and 5 (#853) (#869)

Closes #853

DCA buys are now exempt from rail 6 (per_asset_concentration_cap), just as #842 exempted them from rail 4. Rail 14 (the monthly BUY cap, not a fee waiver) and available cash are now DCA’s aggregate bounds. keel dca plan now checks the rails it can evaluate offline that still bind DCA.

Changes

• keel/execution/guards.py: rail 6 fires only for is_buy and not intent.is_dca, mirroring rail 4. I updated the module docstring and the inline comment block. DCA holdings still count in the exposure that rails 4 and 6 measure for rule trades.
• keel/sim/account.py: SimAccount.can_open has the same exemption, so keel simulate models live, and its docstrings are updated.
• keel/commands/dca_plan.py:
  • Rail 3 (per day) blocker, R21. The busiest day is the planned per-buys plus every existing live DCA rule’s own budget_usd, compared against caps.max_per_day_usd. per_day_cap_text builds the sentence.
  • Rail 5 (correlated) warning, R22. A per-buy above max_per_order_usd x CORRELATED_SIZE_SCALE, for an asset outside UNCORRELATED_ASSETS, raises a warning. Both constants are imported from guards.py. correlated_size_text builds the sentence.
  • The CLI (render_dca_plan) and the /rules card (dca_plan_payload) both show plan.blockers and plan.warnings unchanged.
• Docs:
  • new docs/rails/rail-6-per-asset-concentration.md, in the rail-4 page’s format, with the exemption table and a note that DCA holdings still count;
  • updated the rail 4 and rail 14 pages, docs/operator-runbook.md, and the plan doc (the #842 note amended, R21/R22 added);
  • updated the caps: comments in keel/templates/config.yaml and keel/templates/config.live.yaml;
  • re-synced root config.yaml; cmp shows it is byte-identical to the template.

Rulings

• Rail 6 uses rail 4’s gate exactly.
  • Why: #841/#842 set the operator-approved pattern for this exemption.
  • Cost if wrong: DCA per-asset size is bounded only by rail 14 and cash.
• The rail 3 busiest day is the plain sum of all planned and live per-buys, with no phase search.
  • Why: Dca.detect is epoch_day % cadence_days == 0 with no offset, so on a multiple of the lcm of the cadences, every rule buys.
  • Cost if wrong: if Dca ever gains a phase, this blocker becomes conservative, blocking plans that would actually pass.
• The rail 3 text says “in DCA buys alone” and that rail 3 counts every BUY.
  • Why: the plan knows only DCA rules, so the figure is a lower bound on that day’s spend.
  • Cost if wrong: none.
• Rail 5 is a warning and names each correlated asset. PAXG is never named.
  • Why: the rail binds only while other correlated exposure is open, which a plan cannot see.
  • Cost if wrong: an advisory note.
• The rulings are numbered R21/R22.
  • Why: there is no R22 in the plan doc for the brief to have meant. #854’s PR takes R20. “One service function per sentence” is implemented as per_day_cap_text and correlated_size_text, following worst_month_text.
  • Cost if wrong: numbering churn in a planning doc.
• The existing sim parity tests are unchanged apart from a comment.
  • Why: their $350 boundary is decided by the per-order cap on both sides, so parity still holds.
  • Cost if wrong: those two tests assert less than their old comment claimed, and the comment now says so.

Test evidence

• guards, exact violation sets:
  • a DCA buy over the per-asset limit gives [];
  • the same buy with is_dca=False gives {"per_asset_concentration_cap"}, which also shows DCA holdings still count;
  • a sell gives set() for both classes.
• Still binding a DCA buy: rail 2 → {"per_order_cap"}, rail 3 → {"per_day_cap"}, rail 5 → {"correlation_adjusted_sizing"}, rail 13 → {"usdc_funding"}, rail 14 → {"monthly_subscription_allowance"}.
• SimAccount parity: DCA is exempt; a non-DCA buy is still bound.
• Plan:
  • the busy-day figure for the worked example is $103.47;
  • at the cap exactly, the plan is approvable; one cent over, the blockers tuple equals exactly (per_day_cap_text(...),);
  • existing live rules push the day over the cap;
  • candidate rules are not counted;
  • the rail 5 warnings list exactly BTC then ETH, never PAXG;
  • the CLI renders the blocker line exactly once.
• TDD: the worker wrote the tests first and reverted the gate to show the failures, e.g. Left contains one more item: 'per_asset_concentration_cap: BTC exposure 1005.0 exceeds ...'. The plan tests failed against the pre-#853 dca_plan.py with AttributeError: ... 'worst_day_cycle_usd'.
• Mutation checks. For each, I confirmed with cmp that the file changed, then restored it from a saved copy:
  • dropped and not intent.is_dca from guards and from sim: the new tests failed;
  • changed > to >= on the day-cap boundary: the boundary test failed;
  • removed the UNCORRELATED_ASSETS exclusion: the PAXG assertion failed;
  • passed live_rule_count=0: the existing-live test failed;
  • dropped the rail 5 warnings.append: the warning test failed.
• Full checks on 44c6f1c:
  • uv run pytest -q: 7044 passed, 3 skipped (exit 0)
  • ruff check keel tests: exit 0
  • ruff format --check keel tests: exit 0
  • mypy: exit 0
  • no JS changed.

Conflicts: #854’s PR (#867) and #856’s PR also edit keel/commands/dca_plan.py.

feat(web): cache the DCA plan’s admission screen for 5 minutes (#856) (#870)

Closes #856

GET /api/dca-plan now caches the admission screen (build_screen_report’s result) for 5 minutes, keyed on the served deployment’s (config_path, db_path) plus the screened product ids and quote currency (#873). The payload carries a presentation-ready screen_age field, and the /rules card shows it as a note, e.g. “Asset screen from 2m ago; refreshes every 5m.” (the interval is ScreenCache.TTL_SECONDS, handed through)

Changes

• keel/web/api.py: a new ScreenCache with a lock and TTL_SECONDS = 300. read_dca_plan asks the cache for the screen, then builds the plan from it.
• keel/web/server.py: ServeConfig.screen_cache holds one cache per keel serve process, shared by all of ThreadingHTTPServer’s threads.
• keel/commands/dca_plan.py: select_universe and build_dca_plan accept a screen_report_fn, defaulting to build_screen_report. The CLI’s behaviour is unchanged.
• keel/web/payload.py: screen_age is a Field whose value is the age in seconds and whose display is the sentence. The awaiting-budget state (and any call with no screen age) sends a worded not_screened field (“Asset screen: not run yet — it runs once a budget is entered.”), so the card never shows a lone dash.
• keel/web/static/js/render.js: dcaPlanCard places field(plan.screen_age) in a p.note under the state line.

Rulings

• The cache holds the screen, not the plan.
  • Why: budget and buffer are per-request query params, and a cached plan would serve stale buy amounts.
  • Cost if wrong: none; plan arithmetic is cheap.
• The clock is injected as the reader’s own now_ts, not as a new callable.
  • Why: test_no_reader_reads_the_clock_a_second_time forbids a second clock read in a reader. now_ts is already the injected clock, so the tests drive the TTL through it.
  • Cost if wrong: a reviewer who wanted a Callable[[], int] would need a small signature change.
• The key is (config_path, db_path), even though the cache already lives on the per-process ServeConfig.
  • Why: the cache stays correct even if one instance ever serves two deployments.
  • Cost if wrong: none.
• An entry is fresh while its age is under 300 s; at exactly 300 s it is rebuilt.
  • Why: this matches guards.py’s due <= now convention.
  • Cost if wrong: a one-second difference.
• The lock is held while a miss rebuilds.
  • Why: this prevents a thundering herd when concurrent polls land on a stale entry.
  • Cost if wrong: one poll waits for a few local DB reads.
• The age is clamped at 0. I added this after the worker finished.
  • Why: a request stamped before a later-stamped request built the entry (it waited on the lock) showed “-1s ago”.
  • Cost if wrong: none.
• No service-worker cache bump.
  • Why: sw.js?v=<build> is keyed on the commit, so a new commit already invalidates old clients.
  • Cost if wrong: a stale shell until the next build.

Test evidence

• Each test counts calls to build_screen_report, which also shows the fixture reaches read_dca_plan.
  • A hit within the TTL keeps the count at 1 and reports age 299.
  • Exactly 300 s later the count is 2, and 600 s later it is 2.
  • A different config path at the same instant makes the count 2.
• ScreenCache is also unit-tested directly:
  • the 0/299/300 s boundary;
  • four keys (two config paths × two db paths);
  • 8 threads racing a cold cache build exactly once;
  • a request stamped before the build reads age 0. This test failed first with -1 == 0, and passes after the clamp.
• The payload’s screen_age is asserted as an exact field dict, and the awaiting state as absent.
• The client test asserts the pairing: one el("p","note") that appends field(plan.screen_age) and is appended to the card.
• TDD: the worker’s tests failed first with AttributeError: ... 'screen_cache' / no attribute 'ScreenCache', and the card test failed with “sends screen_age; the card never places it”.
• Mutation checks. For each, cmp confirmed the file changed, and the file was restored from a saved copy:
  • < to <= on the TTL: the two boundary tests failed;
  • key (db_path, db_path): the key-isolation test failed.
• Real browser (Playwright): keel serve ran on a copy of keel/templates/config.yaml with a scratch DB on free port 57711.
  • I unregistered the service worker and cleared its caches first.
  • /rules?budget=500&buffer=0.1 showed “Asset screen from 0s ago; refreshes every 5m.” with 0 console errors and 0 warnings; /rules with no budget shows the not-run-yet line (re-verified at dd5fa82 after unregistering the service worker).
  • A reload 53 s later showed “from 53s ago”, which shows the cache survived in the running server.
  • The server was then killed.
• Full checks on a34c73f:
  • uv run pytest -q: 7038 passed, 3 skipped (exit 0)
  • ruff check keel tests: exit 0
  • ruff format --check keel tests: exit 0
  • mypy: exit 0
  • node --check keel/web/static/js/render.js: exit 0

Conflicts: this PR, #853’s PR and #854’s PR (#867) all touch keel/commands/dca_plan.py, but in different functions.

fix(dca): the passing-value suggestion clears rails 3 and 2 as well as 14 (#874) (#876)

Closes #874

What changed

• _within_budget_rails (new, private) is the passing predicate for both binary searches. A candidate --budget / --buffer-pct now has to clear three rails:
  • rail 14: the worst month within the cap, minus the R20 reservation for live DCA commitments (kept, per the orchestrator ruling);
  • rail 3: worst_day_cycle + existing_live_daily <= max_per_day_usd, the same busiest-day sum #869 uses;
  • rail 2: every per_buy <= max_per_order_usd.
• All three are monotone in budget and buffer, so both searches stay exact, and the boundary asserts are unchanged.
• The _passing_suggestion_text clause is now appended to every budget-driven blocker: rail 14, rail 3 and each rail 2. The CLI and the /rules card both show plan.blockers verbatim, so they share the one text function.
• When no value passes, the clause says so (“no positive —budget would pass …”).
• On an unlimited tier nothing is reserved against a monthly cap.
• Ruling R23 is added to docs/superpowers/plans/2026-09-27-dca-plan.md. No public names change.

Evidence

Red first. All five new tests failed on main. The pre-fix suggestion, re-run through build_dca_plan, is still blocked:

• max_per_day_usd=60: 483.26 / 0.1302 → 1 blocker (rail 3).
• max_per_order_usd=30: 483.26 / 0.1302 → 1 blocker (rail 2, BTC $40.00).

New tests. Each asserts the exact blockers tuple, never substrings.

• test_the_issue_874_suggestion_clears_rail_3_as_well_as_rail_14 and test_the_suggestion_clears_rail_2_as_well_as_rail_14:
  • re-running at the suggested budget and at the suggested buffer gives blockers == ();
  • one cent above the budget, or 0.0001 below the buffer, is blocked by exactly the one rail-3 (or BTC rail-2) blocker.
• test_a_rail_3_blocker_on_its_own_now_names_a_passing_value and test_a_rail_2_blocker_on_its_own_now_names_a_passing_value.
• test_rail_3_says_no_value_passes_when_live_rules_alone_fill_the_day (unlimited tier).
• Three existing rail-3 tests now expect the appended clause.

Mutation check. Each mutant was applied to the source (a 2-line diff, verified), and each was killed:

• rail-3 term removed: 7 tests fail, including all three new rail-3 tests;
• rail-2 term (all(per_buy <= max_per_order_usd ...)) replaced by return True: both new rail-2 tests fail.

Local checks (exit codes): pytest=0 (7074 passed, 3 skipped), ruff check=0, ruff format --check=0, mypy=0.

Live is not affected: per-order is $200, per-day is $200 and the worst day is $150.

chore(release): 0.20.0 — DCA exempt from the per-asset rail; dca plan and its read-only card (#877)

Version bump only: all 8 pyprojects, their == pins, and uv.lock go from 0.19.0 to 0.20.0. That’s 9 files, the same shape as #845. uv lock --check passes, and there’s no schema change since 0.19.0.

MINOR, because rail 6 changes scope for DCA (#869), and a new command and route land (#846, #850).

• #846: keel dca plan
• #850: GET /api/dca-plan and the read-only card on /rules
• #869 (#853): DCA buys are exempt from rail 6; the plan blocks on rail 3 and warns on rail 5
• #867 (#854), #876 (#874): a blocked plan names the values that pass rails 14, 3 and 2
• #870 (#856): the admission screen is cached for 5 minutes
• #858 (#855): the live-rules manifest is synced
• #859: the sell-side design spec

Local: pytest 7074 passed, 3 skipped; ruff and mypy clean.

Built from 71ddba24c1f1. Version binds to this hash: keel --version reports keel 0.19.0+71ddba24c1f1 [release].

Install

Download all wheels from this release into one directory, then install the keel_trader wheel by path:

pip install --find-links . ./keel_trader-0.19.0-py3-none-any.whl
keel versions

keel versions — not keel --version — is the check: it reports every keel distribution in the venv and exits non-zero if a sibling was left behind at an older version, which --version cannot see. Upgrading an existing deployment: see “Deploying a new version” in the README.

⚠️ Never install by bare name. The distribution is keel-trader; the name keel on PyPI belongs to an unrelated project, so pip install keel fetches someone else’s package. A build reporting DIRTY or [checkout] is not this release and must not be run against live funds.

Configure

config.yaml is attached to this release: the production config, in auto_trade.mode: confirm — keel previews every order and waits for your approval. Drop it beside the install (or run keel init-config --live), put your CDP key in a git-ignored .env, then:

keel migrate     # existing database: apply schema migrations
keel init        # fresh deployment: write config + seed candidate rules

Seeded rules start as candidate and trade nothing until you promote them.

Features

research: a 200-day SMA filter on the daily turtle — no arm distinguishable from the baseline (#830) (#833)

Closes #830.

Four commits, in the order that matters:

1. d5e1485 feat(strategy): an optional trend_filter on turtle_breakout (off | above | slope | both, trend_sma_period 200, trend_slope_lookback 5).

   • Default off, so every existing rule behaves exactly as before.
   • Too little history to compute the average declines the entry (trend_filter_history) rather than letting it through.
   • 8 tests, each failing first, using fixtures that assert their own premise. 5 of 5 mutants killed.

2. 696bc5b The pre-registration. The driver’s docstring holds the arms, data, window, statistics, decision rule and my expectation. It was pushed at 00:39 UTC before any arm ran.

3. 37cc6ac fix(research): the trials ledger now refuses two kinds of summary value it could never read back:

   • A non-numeric string raises on read, making the append-only ledger unreadable from that row on.
   • A float breaks the row’s hash, so verify_chain reports it as tampered forever.

   Both were found when the first run’s four rows failed to read back. Those rows were never committed. One test each.

4. 8604e80 The record, data and four ledger rows (ablation, a_priori, diagnostic_only, with R series).

Result (1.20% taker plus per-product slippage, in R, common window)

Arm	N	Win %	E[R]	Δ vs off, 95% CI (cluster bootstrap by entry day)
off	202	26.7%	+0.270	—
above	181	25.4%	+0.218	[−0.641, +0.540]
slope	121	29.8%	+0.419	[−0.515, +0.829]
both	121	28.9%	+0.409	[−0.524, +0.824]

Pre-registered verdict: no arm is promising. Every arm clears the 100-trade floor, and no lower bound is above zero, so nothing goes to walk-forward.

• slope and both point the hypothesised way, but inside an interval about 1.3 R wide.
• above barely binds and does slightly worse.
• The largest effect in the data is the excluded first ~205 days (the 2022 bear-market onset): 18 trades averaging about −1.0 R.
• The baseline itself remains descriptive under ADR 0006: +5 win-rate points over break-even against a 14-point detectable edge.

Honesty notes

• Edits since the pre-registration: the driver changed only in how figures are stored (numeric strings; words moved to params). git diff 696bc5b -- docs/experiments/2026-09-27-turtle-sma200-filter.py shows every line.
• Reproducibility: the run is deterministic (seed 830), and the committed figures equal the first run’s.
• Prediction miss: 90% of entries were retained for above, not the 40–60% I predicted.

Verification

• Full suite: 6785 passed, 3 skipped.
• mypy, ruff check and ruff format --check are clean.
• verify_chain on the tracked ledger: 98 rows, no problems.

research: accumulation policy after fees — no arm beats static DCA (#831) (#835)

Closes #831. Implements the approved design (#834, revision 2).

Three commits, in the order that matters:

1. 7a1e900 feat(sim): keel/sim/accumulation_policy.py. Four allocators; an account with allowance-aware fees and average-cost lots; a joint stationary bootstrap; the D6 decision rule.
   • 47 tests, each seen failing first. 15 of 15 mutants killed; a 16th was equivalent, and its redundant code was removed.
   • Arm A reproduces dca_into_allowlist to the cent under zero fees on gapless candles. It fills at the next open where the benchmark fills at the close, as the design requires, and a second test pins that difference.
2. 4113ed0 The pre-registration. The driver’s docstring is the design’s §3–§8, frozen. It was pushed at 02:04 UTC before the run. git diff 4113ed0 -- docs/experiments/2026-09-27-accumulation-policy.py is empty: the driver hasn’t changed since.
3. bd18cae The record, data and 16 ledger rows (ablation, a_priori, diagnostic_only; chain verified, 114 rows).

Result (headline: 5 years without PAXG, allowance-aware fees, $30,500 deposited)

Arm	Terminal	Sortino	Max DD	P(ΔSortino > 0), 20 / 60-day blocks	Verdict
A static DCA	$46,629	0.523	79.5%	—	baseline
B value averaging	$48,840	0.542	78.5%	0.583 / 0.599	not better
C steered deposits	$47,967	0.564	79.1%	0.365 / 0.407	not better
D selective trimming	$52,919	0.611	79.3%	0.363 / 0.434	not better

No arm is better than static DCA after fees, in either run or fee model.

• Trimming (D) wins the historical path by 13.5% but improves Sortino in only 36–43% of 2,000 resampled paths. That’s a path-specific result, and the record declines to call it a win.
• Value averaging (B) is the most consistent arm: 58–61% of paths, and about 2 points less drawdown. It is still far from the 0.95 bar.
• Prediction misses are recorded. D was expected to do best on the with-PAXG run and was instead the weakest alternative there. PAXG’s slippage is about 100 bp per leg.

Verification

• Full suite: 6832 passed, 3 skipped.
• mypy and ruff are clean.
• verify_chain on the ledger: no problems.
• The record’s computed claims were re-checked against the data. Three were corrected before committing, and a causal story I hadn’t tested was removed.

Fixes

fix(sim): two rules of one kind on one asset get a row each (#829) (#832)

Closes #829.

What was wrong

report.edge_table and report.accumulation_table (#825) keyed each row "{rule.name}:{asset}". When two rules of the same kind sit on the same asset, the later rule’s row overwrote the earlier one’s.

• On the deployment: ~/keel/keel.db has two paper BTC DCA rules, rule 19 at $50/week and rule 20 at $5/week. keel simulate printed a single row, the $5 rule’s, which looked like a ~$5/week DCA. The $50 sleeve was invisible.
• A second, quieter effect: group_trades_by_class looked both rules up by that shared key. G2’s per-class pool counted the surviving rule’s trades twice and the other rule’s not at all. The test below shows a class pool of 0 trades where the pooled row has 1. The pooled row itself was always right, because it extends every rule’s trades before keying.

The fix

One function, report.rule_keys(rules), now keys all three tables:

• A key that is already unique is unchanged ("turtle_breakout:BTC"), so existing readers and tests are untouched.
• Rules that share a key are told apart by their rules.id ("dca#19:BTC", "dca#20:BTC"), or by position when a hand-built rule has no id. No row is ever lost.
• All three tables must be given the same rules list, which simulate already does. The docstrings say so.

Verification

• tests/sim/test_rule_keys.py has 6 tests. Five failed first on the old code; the “unique key unchanged” test is a regression pin that passes throughout. They cover:

  • two DCA rules, each at its own budget
  • two edge rules on one asset, with correct pooled N
  • the class pool counting each rule once (it was 0, now 1)
  • unique keys unchanged
  • colliding rules without ids
  • the rendered section showing both rows

• Five mutants were each checked to have changed the source, and each was killed:

  Mutant	Tests failed
  never disambiguate	5
  class pool uses the old key	1
  accumulation uses the old key	2
  always disambiguate	12
  ignore rule_id	3

• Real data, on a copy of the paper database over the 5-year window:

  Row	Buys	Cost	Value
  dca#19:BTC	261	$13,213.14 ($50.63/buy)	$25,715.00
  dca#20:BTC	261	$1,321.31 ($5.06/buy)	$2,571.50

  Before the fix only the second row printed.

• Full suite: 6775 passed, 3 skipped. mypy, ruff check and ruff format --check are clean.

fix(rails): rail 14 is a monthly buy cap, not a fee-free allowance (#836) (#837)

Closes #836.

What was wrong

keel described rail 14’s cap as the venue’s fee-free allowance, and its research treated “inside the allowance” as a fee-free regime. keel’s orders go through Coinbase Advanced Trade, which has no fee-waiver tier:

• On 2026-09-27 the account reported the Intro tier: 0.9% taker, 0.5% maker, has_promo_fee: false.
• Every live fill had paid a fee: 1.19%, 1.14%, 1.19% and 0.89%.
• Coinbase One’s “zero trading fees up to $500/month” applies on the main Coinbase platform, not Advanced Trade.

What changed (wording only; enforcement untouched)

• keel/execution/guards.py has zero changed lines. The 29 rail 14 guard tests pass unchanged, which proves the cap, its fail-closed behaviour and every number it enforces are the same.
• No schema rename. The free_volume_usd field keeps its historical name. A rename would need a migration and would change no behaviour.
• Operator-facing text:
  • keel subscription set --help now says “Monthly BUY cap … not a fee waiver”.
  • The throughput report says “route WITHIN each venue’s attested buy cap … trades inside it still pay the venue’s fee”.
  • The significance verdict’s zero-fee phrase reads “a zero fee (hypothetical: Advanced Trade orders are never fee-free, #836)”.
  • The simulator’s tier section adds a paragraph saying its within-cap rows are hypothetical for keel’s orders.
• Docs:
  • docs/rails/rail-14-subscription-allowance.md is retitled “the monthly buy cap”. Its “What it bounds” section no longer claims a fee waiver or a “profitability boundary”, and it carries a dated correction. The enforcement, veto and inspection sections are unchanged.
  • The runbook and the research toolkit are corrected in place.
• Records are appended to, never rewritten. Five records that described a fee-free regime each gain a dated Fee note under the title: the 2026-08-21 significance, 2026-08-22 trailing exits and 2026-09-05 restatement records, the quant-lab note cross-verification, and the 2026-09-27 accumulation-policy record. The accumulation note says its flat-taker run is the one matching live, and the verdict is unchanged.
• Code comments and docstrings now call the fee-free tier model hypothetical for keel’s orders.

Tests

tests/test_rail14_is_a_buy_cap.py has 6 tests, all seen failing first:

• the help text,
• the throughput report,
• the significance label,
• the tier section,
• the rail 14 doc making no fee-waiver claim,
• every record that describes a fee-free regime carrying the #836 note.

One existing test that pinned the old “fee-free” wording is rewritten to pin the corrected label.

Not in scope, deliberately

• The keel doctor fee-rate readout (#836 item 4, marked optional there) is left for a follow-up.
• Switching the DCA to limit orders was decided against on 2026-09-27.

Verification

• Full suite: 6838 passed, 3 skipped.
• mypy, ruff check and ruff format --check are clean.

fix(rails): exempt DCA buys from the total-exposure rail; rail 14 bounds DCA (#841) (#842)

Closes #841

The decision (the operator’s, 2026-09-27, final)

DCA is bounded by the venue plan’s cap (rail 14, the attested monthly buy cap), not by caps.max_exposure_usd.

• Exempt DCA BUYs from the total-exposure rail (total_exposure_cap) only.
• Per-asset concentration (per_asset_concentration_cap) still applies to DCA.
• Rail 14 (monthly_subscription_allowance) still applies to DCA, unchanged. It is now the binding DCA limit.
• Every other rail’s treatment of DCA is unchanged.

The reason: the live account accumulates through 7 DCA rules. About $213 is held against the $400 max_exposure_usd cap, so rail 4 would veto the sleeve after about one buy on Oct 9.

Which rails bind DCA now

Rail	Rule-trading BUY	DCA BUY
4: total_exposure_cap	binds	exempt (this PR)
6: per_asset_concentration_cap	binds	binds
14: monthly_subscription_allowance	binds	binds. It is the limit that bounds DCA.
8: no averaging into losers	binds	exempt (unchanged)
11: drawdown breaker	binds	exempt (unchanged)
16: consecutive-loss breaker	binds	exempt (unchanged)
every other rail	binds	binds (unchanged)

• DCA holdings still count in the total exposure that a rule-trading entry sees, so a growing DCA sleeve shrinks the room left for rule trades.
• Rail 6’s per-asset limit is still max_per_asset_pct × max_exposure_usd. max_exposure_usd still bounds DCA per asset, but no longer in total.
• SELLs are unaffected. Rail 4 never read a SELL.

What changed

• keel/execution/guards.py: rail 4 now gates on is_buy and not intent.is_dca. I updated the module docstring’s “DCA exemptions” paragraph, rail 4’s comment and rail 14’s comment. The docstring now also names rail 16, which was already exempt but was missing from that paragraph.
• keel/sim/account.py: SimAccount.can_open applies the same exemption, so keel simulate models what live does. The sim’s DCA path (portfolio_sim._process_dca_signals) goes through can_open, which vetoes and does not clamp. Before this PR it vetoed DCA over max_exposure_usd; now it does not. max_affordable_notional is unchanged because only the rule-slot path calls it.
• docs/rails/rail-4-total-exposure.md is new and holds the exemption table. docs/rails/rail-14-subscription-allowance.md now says rail 14 is what bounds DCA.
• The caps: comment in keel/templates/config.yaml and config.live.yaml says the same. The repo-root config.yaml is re-synced with its template, as test_the_template_stays_in_sync_with_the_repo_config requires.
• keel doctor has no text that lists rails or their DCA exemptions, so nothing changed there.
• executor.py is not touched.

This reaches live only after a release and deploy. Until then, the deployed rail 4 still vetoes DCA over max_exposure_usd.

Tests (written first; each was seen to fail for the stated reason, or is a pin)

Test	Before the fix
(a) test_rail4_dca_buy_over_max_exposure_is_not_vetoed_by_total_exposure	FAIL: total_exposure_cap: open exposure 960.0 + 45 = 1005.0 exceeds max_exposure_usd 1000
(b) test_rail4_the_same_buy_without_is_dca_is_still_vetoed_by_total_exposure	pass (regression pin; kills M3)
(c) test_rail6_dca_buy_over_the_per_asset_cap_is_still_vetoed_by_concentration	FAIL: extra total_exposure_cap beside per_asset_concentration_cap
(d) test_rail14_dca_buy_over_the_monthly_cap_is_still_vetoed_when_exposure_is_also_over	FAIL: extra total_exposure_cap beside monthly_subscription_allowance
(e) test_a_dca_buy_over_max_exposure_is_not_vetoed_by_the_exposure_cap (sim)	FAIL: total_exposure_cap … 1005 exceeds … 1000
(e) test_a_dca_buy_over_the_per_asset_cap_is_vetoed_by_concentration_only (sim)	FAIL: total_exposure_cap listed before per_asset_concentration_cap
(e) test_a_rule_buy_over_max_exposure_is_still_vetoed_by_the_exposure_cap (sim)	pass (regression pin; kills M6)
(e) test_parity_with_guards_check_when_total_exposure_is_the_tightest_cap	FAIL: sim vetoed a 100 DCA buy that the fixed guards allow
(f) test_rail4_never_gates_a_sell_whatever_the_order_class[False/True]	pass (pin)

Two existing sim tests, test_exposure_cap_rejects_over_cap and test_close_frees_up_exposure_for_a_subsequent_open, probed the exposure cap with the sim helper’s default is_dca=True intent. They now probe with a rule-trading intent, which is what they test.

Mutants (each proven applied: the source differed from the saved copy; restored from that copy, never git checkout)

Mutant	Result
M1: drop the guards exemption	killed by (a), (c), (d) and the parity test
M2: exempt DCA from rail 6 instead of rail 4	killed by (a), (c), (d) and the parity test
M3: exempt non-DCA buys too (guards)	killed by (b), test_rail4_total_exposure_cap_rejects_over_cap and test_a_malformed_history_row_still_counts_toward_the_exposure_cap
M4: remove the sim exemption	killed by both (e) DCA tests and the parity test
M5: sim exempts DCA from concentration instead	killed by 5 sim tests
M6: sim exempts rule entries too	killed by the (e) rule pin and 2 existing sim exposure tests

Checks

• uv run pytest -q: 6850 passed, 3 skipped, exit 0
• uv run ruff check keel tests: exit 0
• uv run ruff format --check keel tests: exit 0
• uv run mypy: no issues in 473 files, exit 0

fix(executor): size each DCA buy from the rule’s own amount (#840) (#843)

Closes #840

Milestone: DCA plan — proposal CLI and read-only card

What changed

keel/execution/executor.py _build_intent now sizes a DCA ENTER from the rule’s amount, setup.context["size_usd"] (what Dca.detect computes: budget_usd × (1 + dip bonus)), instead of the config’s single dca.budget_usd.

• A new helper, _dca_budget(context, fallback), returns (amount, "rule" | "config"). It falls back to config.dca.budget_usd only when size_usd is absent or is not a positive, finite number. A bool is refused too. Decimal('Infinity') > 0 is true, which is why the finite check is there: commands/rules.py documents how an infinite budget_usd gets through.
• The source is logged as executor.dca_sized, at INFO for rule and WARNING for config, with product, rule, rule_id and amount.
• Paper: agent._paper_enter sizes through the same executor._build_intent and fills intent.qty, so paper is fixed by the same change. A test pins it. The account sim (sim/portfolio_sim.py) already preferred size_usd, so live, paper and the sim now agree.
• No rail, cap, guard or veto changed, and max_exposure_usd is untouched. intent.notional is still spend(qty, entry) from the new qty, so rail 14 and every other guard see the real order, which is now smaller.
• Docs: the executor’s “CAREFUL” comment is rewritten. It records that the old “config is the operator-facing dial” rationale was reversed by the operator on 2026-09-27. Also updated:
  • the executor module docstring and the _order_spec docstring;
  • a new DcaConfig docstring (in packages/keel-core);
  • the dca: comment in config.yaml, keel/templates/config.yaml and keel/templates/config.live.yaml;
  • equity.sizing_equity’s docstring;
  • docs/operator-runbook.md and docs/RELEASING.md.

Before and after

rule	asset	amount	cadence	buys/month (30.44 d)	before ($50 each)	after (rule’s amount)
6	BTC	$40	7d	4.35	$217.4	$173.9
8	ETH	$25	7d	4.35	$217.4	$108.7
9	PAXG	$25	14d	2.17	$108.7	$54.4
10–13	ADA/XLM/DOGE/FET	$15 each	14d	2.17 each	$434.9 (4 × 108.7)	$130.5 (4 × 32.6)
					≈ $978	≈ $467

Before, the book tried to spend about $978 a month against rail 14’s $500 cap, so rail 14 vetoed the tail of each month. After, it spends the rules’ ~$467, which fits under the cap. Rail 14 is unchanged and still vetoes any buy that would cross it.

This changes live behaviour only after a release and deploy. The live deployment runs installed wheels, not this repo.

Tests (each one seen failing before the implementation)

test	what it pins	red before the fix
(a) test_live_dca_sizes_from_the_rules_size_usd_not_the_config_budget	through the real execute() path, size_usd=25 at 50,000 places qty 0.0005 with quote_size 25, and logs source=rule	0.001 != 0.0005
(b) test_live_dca_falls_back_to_the_config_budget_without_a_usable_size_usd ×8	absent, None, 0, −25, Infinity, NaN, "25" and True all size from the config’s 50 and log source=config	no executor.dca_sized record (fallback sizing already held; recording the source is new)
(c) test_a_dca_rules_detect_feeds_the_live_order_size_end_to_end	Dca(budget_usd=15).detect(...) → execute() → qty 0.0005 at 30,000	0.001666… != 0.0005
(c′) test_a_dip_scaled_dca_buy_spends_size_usd_not_the_rules_base_budget	with a dip, size_usd 18.75 ≠ budget_usd 15, and the order spends 18.75	added after the fix; red against the old code via mutant M1 below
(d) test_paper_dca_fill_is_sized_from_the_rules_amount_not_the_config_budget	_paper_enter with a real Dca(budget_usd=15) fills 0.5 at 30	1.666… != 0.5
(e) test_rail_14_sees_the_rules_true_notional_and_admits_a_25_dollar_buy_that_fits	$460 spent + $25 = $485 against a $485 cap is placed	intent notional 50.000 != 25
(e) test_rail_14_still_vetoes_a_25_dollar_dca_buy_that_would_cross_the_cap	$460 + $25 = $485 against a $480 cap is vetoed, and the veto names 460 + 25 = 485	the veto named 50.000

Mutants (each proven applied by a changed sha256, restored from a saved copy, never git checkout)

mutant	result	killed by
M1: revert to config.dca.budget_usd	KILLED (6 fail)	(a), (c), (c′), (d), both (e)
M2: drop the fallback (use size_usd unconditionally)	KILLED (10 fail)	all 8 (b) cases plus 2 existing DCA tests
M3: read budget_usd instead of size_usd	KILLED (4 fail)	(a), (c′), both (e)
M4: accept size_usd <= 0 (< 0)	KILLED (1 fail)	(b)[zero]
M5: drop the finite check	KILLED (2 fail)	(b)[infinity], (b)[nan]
M6: drop the bool guard	KILLED (1 fail)	(b)[bool]

Checks

• uv run pytest -q: 6854 passed, 3 skipped, exit 0
• uv run ruff check keel tests: exit 0
• uv run ruff format --check keel tests: exit 0
• uv run mypy (bare): no issues in 473 source files, exit 0

Not done here

• deploy/live-rules.json still records a single BTC DCA rule at budget_usd: "50". The brief lists seven live DCA rules, with BTC at $40. Now that the rule’s amount is what spends, that manifest is worth syncing from the deployment in a separate change.
• The sim’s own fallback (size_usd or config.dca.budget_usd) still accepts a negative size_usd. It is not touched here, and Dca refuses a non-positive budget_usd at construction.
• The root config.*.yaml profiles (config.live-sandbox.yaml, the paper profiles) keep their uncommented dca: blocks.

Research & validation

docs(spec): accumulation policy — value averaging and band rebalancing vs static DCA (#831) (#834)

Refs #831. A draft for review. No code and no simulation until it’s approved. Merging this PR is the approval; comments or edits here are the review.

docs/superpowers/specs/2026-09-27-accumulation-policy-design.md covers:

• The formulas.
  • Bounded value averaging: ΔC = clamp(w·D·t − H, C_min·w·D, C_max·w·D), with a zero-growth target path, buy-only, and C_max = 3.
  • Contribution steering: the monthly deposit goes to underweight assets first; it never sells.
  • Band rebalancing: a ±15% band relative to each target weight, checked monthly, trimming and topping up back to target.
• The account model every arm shares.
  • Deposits: identical $500 monthly deposits. Idle cash earns nothing, consistent with the fiqh constraints.
  • Fees: modelled the way this account is actually billed. Buys are fee-free up to the $500/month Basic allowance; sells always pay the 1.20% taker fee. A flat-taker sensitivity run sits beside it.
• Harness requirements.
  • A new pure allocator module, separate from portfolio_sim.
  • Static DCA must reproduce dca_into_allowlist exactly, as the oracle for the whole harness.
  • Tests come first.
• Rails. This phase is simulation only. The spec records what a live version would hit. Most notably, sell_only_on_rule requires a rule_kind on every sale, so rebalancing trims need a policy decision. The two buy-only arms avoid that question entirely.
• The prior it has to answer. The knowledge base (§51) calls fixed-weight rebalancing the wrong paradigm here, because correlated crypto offers little dispersion to harvest. The spec sharpens the hypothesis: any rebalancing benefit should come through PAXG, the one low-correlation leg.

Revision 2 (from review): selective trimming in arm D, a ±1.5-point band floor for the small sleeves, and 20- and 60-day bootstrap blocks reported side by side, with the decision rule required to hold under both.

Decisions for you (§9)

#	Decision	Proposed
D1	Universe and window	PAXG’s Coinbase history starts in May 2025, so: a 5-year PAXG-free primary run plus a 1.4-year with-PAXG secondary run
D2	Monthly deposit	$500
D3	Fee model	allowance-aware, plus a flat-taker sensitivity run
D4	Value averaging	C_min 0, C_max 3, g = 0
D5	Band and trimming	max(0.15·w_i, 0.015), monthly; selective: trim only upper-band breaches, proceeds to underweights
D6	Decision rule	P(ΔSortino > 0) ≥ 0.95 and median Δmax-drawdown not worse, under both 20- and 60-day bootstrap blocks

Once D1–D6 are settled, §3–§8 become the driver’s pre-registered docstring, committed before any run, exactly as for #830.

Other changes

chore(release): 0.19.0 — DCA sized per rule, bounded by the venue plan’s cap (#845)

Version bump only: all 8 pyprojects, their pins, and uv.lock go from 0.18.0 to 0.19.0. Same shape as #828.

MINOR because live DCA sizing changes (#843) and a rail changes scope (#842). No schema change.

• #843 (#840): each DCA buy is sized from its rule’s size_usd
• #842 (#841): DCA buys are exempt from rail 4; rails 14 and 6 still bind them
• #837 (#836): rail 14 relabelled as a monthly buy cap

Local: pytest 6882 passed / 3 skipped, ruff and mypy clean.

Built from af9db817b3c8. Version binds to this hash: keel --version reports keel 0.18.0+af9db817b3c8 [release].

Install

Download all wheels from this release into one directory, then install the keel_trader wheel by path:

pip install --find-links . ./keel_trader-0.18.0-py3-none-any.whl
keel versions

keel versions — not keel --version — is the check: it reports every keel distribution in the venv and exits non-zero if a sibling was left behind at an older version, which --version cannot see. Upgrading an existing deployment: see “Deploying a new version” in the README.

⚠️ Never install by bare name. The distribution is keel-trader; the name keel on PyPI belongs to an unrelated project, so pip install keel fetches someone else’s package. A build reporting DIRTY or [checkout] is not this release and must not be run against live funds.

Configure

config.yaml is attached to this release: the production config, in auto_trade.mode: confirm — keel previews every order and waits for your approval. Drop it beside the install (or run keel init-config --live), put your CDP key in a git-ignored .env, then:

keel migrate     # existing database: apply schema migrations
keel init        # fresh deployment: write config + seed candidate rules

Seeded rules start as candidate and trade nothing until you promote them.

Fixes

fix(sim): DCA buys once per completed day, and the report shows its sleeve (#821) (#825)

What was wrong

keel simulate got the DCA rule wrong in four ways, and the report hid all of them.

• The simulator bought DCA about 24 times per cadence day. It evaluates rules on every hourly bar. A DCA rule decides on daily candles, so its answer is the same on all 24 bars of a day, and each of those bars bought. On a synthetic 60-day repro, 9 cadence days at $50 spent about $10,768 instead of $450. Every earlier keel simulate run with a DCA rule has an oversized DCA sleeve. That inflates or distorts its ending value, return, drawdown, caps headroom and rail-14 trading volume.
• It read the day before the day had happened. The simulator’s daily window includes the day still in progress, and that bar is stored with the completed day’s OHLC. From 00:00 UTC, Dca.detect priced its buy at that day’s close and measured the dip against that day’s high. Live only has closed candles, so live DCA sees yesterday, and the simulator’s cadence day was one day ahead of live. TurtleBreakout already guarded against this with _completed_days; Dca had no guard.
• The edge table showed DCA as N 0. Dca declares no timeframe, so backtest() gave it only hourly candles. It needs daily candles, so it never fired. Declaring a daily timeframe would not have fixed it. Its target=entry / stop=0 sentinels would turn each buy into a fee-only round trip closed on its fill bar, which is a fake loss and not an edge.
• The sleeve was bought but never shown. DCA lots are never closed by design. per_asset_pnl and trade_count come from closed trades only, so the sleeve was inside ending_value and appeared nowhere else in the Markdown report or the HTML artifact.

What changed

• Completed days only. The forming-day guard now lives in keel/strategy/rules/base.py as completed_days, with its docstring. TurtleBreakout imports it under its old private name, so every existing reference still resolves. Dca.detect now uses it. Live behaviour is unchanged: when the last daily bar is closed and the hourly series is past it, that bar is kept. A test pins this.
• One DCA decision per UTC day, per (asset, rule) in portfolio_sim. The day is marked when the decision is taken, whether the buy fills or is vetoed. That matches live, where the agent trades once per UTC day. Each buy is logged in SimResult.dca_buys (decision time, fill time, qty, notional, and cash cost including fees). SimResult.final_prices records each asset’s last close.
• Edge table. Rules with the new Rule.accumulates flag, which today means Dca, are left out of edge_table. So they are not in __pooled__ or group_trades_by_class, and G2 gets neither fake round trips nor a zero-trade sample. The new report.accumulation_table runs them over daily candles, using the same completed-day and once-per-day rules. It reports buys, qty, cost basis including fees, last close, marked value and unrealized P&L. The report renders it as its own section, “DCA accumulation (not round trips)”, right after the edge table. The edge table’s own columns are untouched, so #820’s R-multiple change should merge cleanly.
• Account report. build_account_metrics now returns dca_sleeve, built by portfolio_sim.dca_sleeve: per asset, the buys, qty, cost basis, value at the last close, and unrealized P&L. The Markdown report shows it under “DCA sleeve (accumulation, marked to market)”. The per-asset list is now labelled “Per-asset realized rule P&L (closed round trips; the DCA sleeve is below)”. The HTML artifact gets the same sleeve table, and its chart is retitled “Per-asset realized rule P&L”.
• keel rules promote: nothing changes. Its docstring says a DCA rule produces no backtest trades, so --force is its only path to paper. That is still true. backtest() is unchanged, a test pins N 0, and the promotion path never reads the accumulation row.

Before and after (synthetic repro: 60 days of flat-ish hourly and daily candles, cadence 7, $50)

	Before	After
Account-sim DCA buys	~24 per cadence day	8, one per cadence day
Account-sim DCA spend	~$10,768	$400.00 notional ($405.95 cash with taker fees and slippage)
Day the buy is decided on	the cadence day itself, reading its close from 00:00	the day after the cadence day closes, as live
Edge table	dca:BTC row with N 0	no round-trip row; accumulation row with 8 buys, $400.90 cost, $428.93 value, +$28.03 unrealized
Account report	sleeve absent; per_asset_pnl {}	DCA sleeve table: 8 buys, 3.7572 qty, $405.95 cost, $429.79 value, +$23.84 unrealized

The window has 9 cadence days, but the ninth is its last day. That day’s decision falls on the next day, outside the window, so the result is 8 buys, not 9.

Verification

• TDD: each new test was written first and seen failing for the right reason. The sim test got qty 96, which is 0.5 × 8 cadence days × 24; the forming-day tests got a buy priced off the forming day; the edge test found a dca:BTC round-trip key; the other tests failed on missing names or keys.
  • tests/sim/test_dca_sleeve.py, all using the real Dca: (a) total spend equals budget × cadence days; (d) accumulation row plus a pooled result byte-identical with or without DCA, and group_trades_by_class is empty; (e) sleeve value equals qty × last close and unrealized equals value − cost; (f) the Markdown tables are parsed row by row. Also: the realized-P&L label, and N 0 from backtest().
  • tests/strategy/test_dca.py: (b) at hour 0 the forming day’s close and high are ignored, and a forming cadence day does not fire; (c) live-shaped input still fires on the closed day. (c) is a regression pin, so it passes both before and after the change.
  • tests/sim/test_artifact.py: the sleeve table header and cells, and no table when there is no sleeve.
• Mutation run: each mutant was applied alone, the source was checked to confirm it changed, and the file was restored from a saved copy. All five were killed:
  • once-per-day guard removed (3 tests failed)
  • completed-day drop removed from Dca (5 failed)
  • DCA routed back into edge_table and the pool (2 failed)
  • sleeve marked at cost instead of the last close (1 failed)
  • completed_days drops the last day whenever hourly data exists, the live regression (1 failed)
• uv run pytest -q: 6735 passed, 3 skipped. uv run ruff check keel tests is clean, uv run ruff format --check keel tests is clean, and uv run mypy reports no issues. No baseline fixtures changed.

Closes #821

fix(research): the edge table, G2 and promotion judge R, not price units (#820) (#826)

What was wrong

The simulator’s edge table said its numbers were “unit-less R-multiples”. They weren’t. Every trade already stored the correct R (Trade.r_multiple), but stats.summarize never used it. Expectancy, average win and loss, profit factor, max drawdown and MFE/MAE were all built from pnl, which is price units for a one-coin position. A BTC trade and an XLM trade differ by five orders of magnitude in price, so:

• The pooled row was decided by BTC. One BTC trade that lost 1R (−2000) outweighed any number of XLM trades that won 2R (+0.004 each).
• G2 in keel simulate, and #338’s pooled promotion, read those same numbers. check_floors, _realized_rr, pool_stats and _pooled_floors all worked in price units.
• Two more defects sat on the same path:
  • The R denominator was signed, (entry_fill − stop) × qty. When the fill gapped below the stop, the risk went negative and a losing trade got a positive R. This happened in all three close paths: backtest, paper and portfolio_sim.
  • The pooled max drawdown followed the trades in rule order (rule A’s whole history, then rule B’s). That sequence never happened.

What changed

• Trades carry their risk. Trade.initial_risk and SimTrade.initial_risk hold the per-unit |entry_fill − setup.stop|: the fill the trade actually got, against the setup’s ORIGINAL stop, never a trailed or break-even stop. Both fields are last and default to None, so existing constructors keep working.

• One R formula. rules.base.r_multiple_of(pnl, initial_risk, qty) = pnl / (initial_risk × qty). It returns None when the risk is missing or zero. All three close paths use it, so R’s sign now always matches the P&L’s.

• R versions of the stats, next to the money ones. BacktestResult gains:

  • expectancy_r, avg_win_r, avg_loss_r, profit_factor_r
  • max_drawdown_r: the drawdown of cumulative R
  • avg_mfe_r, avg_mae_r
  • n_excluded_no_risk
  • n_wins_r / n_losses_r, which let pool_stats pool R exactly

  A trade with no risk is left out of the R stats and counted, never treated as 0R. A sample with no R at all gives None for every R field.

  The money fields are unchanged. insights, the web payload, tuning and walk-forward still read them.

• Edge table. The pooled row and the per-class pools (group_trades_by_class) are sorted by exit time before they are summarised. The table shows R columns under a label that is now true, and adds an “Excluded from R” line when any trades were left out.

• Promotion.

  • check_floors, _realized_rr, pool_stats/_pooled_floors, and should_demote (whose docstring says it mirrors check_floors) now judge expectancy and R:R in R.
  • No R at all means a refusal, not a pass. For demotion, no R demotes the rule, following transition’s rule that missing evidence must never block pulling a rule back from real money.
  • min_trades and min_win_rate are unchanged. min_expectancy is now an R threshold; every shipped config has it at 0.0.

• Paper history. paper.track_record recovers initial_risk for exits written before this change from the entry payload’s fill and stop. It then recomputes their R instead of trusting a value the old signed formula stored. New exits record initial_risk in the payload.

• keel rules backtest now prints expectancy_r and max_drawdown_r first, then expectancy_px and max_drawdown_px with a legend “(px = price units, 1-coin notional)”. Before, it printed bare expectancy= and max_drawdown=.

Behaviour changes to know about

• G2 and pooled promotion can change verdict. A multi-asset pool whose sign in price units was set by BTC is now judged by its R. It can flip either way: a pool whose BTC trades lost R while cheaper assets won R now passes, and the reverse now fails. Refusal reasons now read expectancy_r … (in R), rr_r … (in R), or no R: … refusing rather than passing.
• A single-asset rule can also move. R:R was a ratio of average pnl and is now a ratio of average R, and the two differ whenever risk per trade varies.
• insights’ gate distance still displays money expectancy and R:R, as it should. Its pass/block verdict comes from check_floors, which now judges R, so the blocking reasons name R.

Test fixtures that changed

• The hand-built BacktestResult fixtures in test_promotion._stats, test_report._pooled_result and test_cli’s pooled fake_backtest now also fill the R fields with the same numbers. Without R, the floors correctly refuse them.
• test_journal_report_enriches_r_multiple_from_paper_track_record stored r_multiple="2.5" on a trade whose own pnl and stop gave 1.0R. track_record now recomputes R from the journalled fill and stop, so the fixture was made self-consistent (pnl 25 on a risk of 10).
• Baseline: tests/fixtures/baseline_backtest.json and tests/baseline/serialize.py are unchanged, and the baseline test passes. The baseline has no gap-below-stop entries, so every pinned r_multiple is the same value, and the serializer doesn’t emit the new fields.

Verification

• TDD. 34 new tests. Each was run and seen failing before its implementation. Examples of the failure reasons:

  • The backtest, paper and portfolio_sim gap tests failed on the sign: 0.45 != -0.45 and 1.28… != −….
  • The chronological-pool test failed on the order: [18000, 10800, 25200] != [10800, 18000, 25200].
  • The rest failed on the missing fields and helper.

  One exception: test_g2_refuses_a_pooled_sample_with_no_r was written after the implementation. It fails on the old code, where G2 passed on price units, and a mutant kills it (M7 below).

• Mutation. Each mutant was applied alone, checked to have changed the source, run, and restored from a saved copy. All 10 were killed:

  Mutant	Killed by
  M1 signed risk	test_the_shared_r_helper; also, separately, the backtest, paper (×2) and portfolio_sim gap tests
  M2a summarize reads pnl instead of R	test_r_aggregates_are_identical_across_a_btc_scale_and_an_xlm_scale_sample
  M2b check_floors expectancy in price units	test_check_floors_judges_expectancy_and_rr_in_r
  M2c _realized_rr in price units	test_check_floors_judges_expectancy_and_rr_in_r
  M3 no-risk trades counted as 0R (no exclusion)	test_trades_with_no_or_zero_risk_are_excluded_from_r_and_counted
  M4 no sort by exit time	test_edge_table_pools_in_exit_time_order_so_max_drawdown_is_chronological
  M5 risk measured from the managed stop	test_a_managed_stop_still_measures_r_against_the_original_stop
  M6 pool_stats doesn’t pool R	test_pooled_pass_when_the_rule_alone_is_short_but_the_parameter_set_is_not
  M7 no R passes the floors	test_g2_refuses_a_pooled_sample_with_no_r
  M8 paper legacy exit trusts the stored signed R	test_track_record_recovers_initial_risk_for_a_legacy_exit_from_its_entry

• Full suite: uv run pytest -q gives 6755 passed, 3 skipped, including the 34 new tests.

• Lint and types: uv run ruff check keel tests passes. uv run ruff format --check keel tests finds all 426 files formatted. Bare uv run mypy reports no issues in 468 source files.

Closes #820

Compliance & rails

chore(live): per-asset ceiling 0.50 -> 0.75 ($200 -> $300) (#819)

Mirrors a change already live in ~/keel/config.live-sandbox.yaml (applied 2026-09-26 at 01:16 UTC, before that day’s 01:20 run), so the tracked copy stays byte-identical to the deployment. Before this edit the two files were identical.

Why

• The weekly BTC DCA was vetoed on 2026-09-25 by per_asset_concentration_cap. BTC held $151.81 at cost, from three $50 buys. The fourth buy projected to $201.81, over the 0.50 × $400 = $200 limit.
• Exposure is measured at cost, so a falling price never frees room. At 0.50 the DCA was permanently capped at three buys, regardless of the ~$257 in available cash.
• At 0.75 the limit is $300, which admits three more weekly buys. The first projection over it is $301.81.

Unchanged

• max_exposure_usd stays at 400. It’s also the sizing proxy, and the config’s own note says to raise it only alongside rail 14.
• The total exposure after the next buy is about $263.51 (BTC $151.81, PAXG about $61.70 at cost, plus $50), still under $400.

A dated note was added to the caps history comment.

Research & validation

docs(adr): 0006 — daily strategies are evaluated on the pooled sample, never per asset (#822) (#824)

Closes #822.

Adds docs/decisions/0006-pooled-evaluation-of-daily-strategies.md and its index entry.

• Records the owner’s decision of 2026-09-26 on the floor #427 left open: n ≥ 100 pooled.
• Formalizes #338’s pooled unit of evaluation, including its diversity floor of 5 products × 10 trades.
• Per-product statistics become diagnostics only.
• Evidence that per-asset n ≥ 100 is unreachable: a 5-year backtest gives the daily Turtle 5 to 18 trades per product, and 220 pooled.
• Stated as a consequence, not hidden: at n = 100 pooled, n_eff ≈ 39, so any evaluation at the floor is descriptive and can only see an edge of about 20 points or more. A confirmatory claim still needs about 259 pooled.
• Pooled expectancy must be unit-free, which ties this record to #820.

No code or config changes: min_trades: 100 keeps its value, and this record states its unit is the pool.

docs(experiments): the hourly turtle over five years — 4,871 trades, 0 of 19 positive at the fee paid (#823) (#827)

Refs #823 (closed with its result). Records the run with its complete per-trade dataset and the fee-to-risk arithmetic behind it.

Files

• docs/experiments/2026-09-26-hourly-turtle-5year-backtest.md: the record.
• …-5year-backtest.py: the driver. It uses the same code path as keel simulate’s edge pass (report.edge_table, simulate.load_sim_candles, per-product slippage), reads the database read-only, and replays the exact window of the original run.
• …-5year-backtest.jsonl: all 4,871 trades, each with its R at the 1.20%, 0.60% and 0% fee levels, plus per-product and pooled summaries. It’s 1.5 MB, the largest file in docs/experiments/. The README says bulk sweep output isn’t committed; this is the run’s recorded output rather than a sweep, and it was asked for as the complete dataset. Happy to drop it to summaries only if you’d rather not carry the size.
• docs/experiments/README.md: the index entry.

Findings

• The driver reproduces the #823 run exactly: N = 4,871, −1.178 R at 1.20% and −0.696 R at 0.60%. It asserts that the trade set is identical across fee levels.
• 0 of 19 products are positive at 1.20% or 0.60%. At a measured 0% fee, only BTC, ETH and SOL are, the three products with 5–11 bp slippage. Pooled at 0% it’s −0.215 R.
• Mechanism: the 2×ATR hourly stop sits a median 2.75% from entry, so a 2.40% round trip costs about 0.87 R per trade, matching the measured 0%→1.20% difference. The daily stop sits a median 11.6% away, so the same round trip costs about 0.21 R there.
• Relationship to earlier records: consistent with 2026-08-11. It reconciles 2026-08-12’s “profitable at zero fee” (priced at a flat 5 bp) with per-product slippage.

Honesty notes

• Not pre-registered: it records a run already made.
• Corrects an earlier figure. My #823 comment’s zero-fee number (about −0.2 R) was extrapolated; the record replaces it with the measured −0.215 R.
• States what it doesn’t show. Daily strategies have no demonstrated edge either. “Regime-filtered daily strategies” is a hypothesis this record motivates, not one it tests. Weekly DCA is accumulation, not an edge claim.
• Records the decommissioning of the hourly paper account (2026-09-26): both launchd jobs unloaded, 19 rules disabled, one paper BCH position frozen.

Verification

• Full suite: 6769 passed, 3 skipped.
• tests/test_experiment_cost_pointers.py passes: the record points at the per-product restatement.
• ruff is clean on the driver.

Other changes

chore(release): 0.18.0 — evidence in R, DCA simulated once a day, pooled evaluation as policy (#828)

Version bump for 0.18.0: the eight workspace versions, the inter-package == pins, and uv.lock. Same shape as 0.17.0 (#818): 9 files, 25 lines in and 25 out. uv lock --check passes.

Why a minor bump: #826 changes what promotion decides. G2 and #338’s pooled path now judge in R, min_expectancy is an R threshold, and a sample with no R is refused. #825 adds new report sections. No schema change since v0.17.0 (keel/data/ is untouched).

What’s in it

• #826 (#820): the backtest edge table, G2 and promotion work in R rather than price units. A losing trade that gapped below its stop now gets a negative R, and pooled rows are in exit-time order.
• #825 (#821): keel simulate buys DCA once per completed day (it bought 24 times per cadence day), with no forming-day look-ahead, and reports the DCA holdings at market value.
• #824 (#822): ADR 0006, daily strategies are evaluated on the pooled sample.
• #827 (#823): experiment record for the hourly Turtle, 4,871 trades.
• #819: the live per-asset ceiling config mirrored into the repo (0.50 → 0.75).

Live trading is unaffected. These changes touch offline tooling and promotion only. Replaying 14 days of real live candles through the new DCA code gave the same buy days as before.

After merge

1. Run Actions → Release with version 0.18.0.
2. Install into ~/keel using the runbook’s steps: back up each database, install the five wheels, run keel migrate (nothing to apply), then keel versions (must show [release]) and keel status.
3. Restart the three running keel serve consoles. The hourly console is decommissioned.

Built from f9b45962408d. Version binds to this hash: keel --version reports keel 0.17.0+f9b45962408d [release].

Install

Download all wheels from this release into one directory, then install the keel_trader wheel by path:

pip install --find-links . ./keel_trader-0.17.0-py3-none-any.whl
keel versions

keel versions — not keel --version — is the check: it reports every keel distribution in the venv and exits non-zero if a sibling was left behind at an older version, which --version cannot see. Upgrading an existing deployment: see “Deploying a new version” in the README.

⚠️ Never install by bare name. The distribution is keel-trader; the name keel on PyPI belongs to an unrelated project, so pip install keel fetches someone else’s package. A build reporting DIRTY or [checkout] is not this release and must not be run against live funds.

Configure

config.yaml is attached to this release: the production config, in auto_trade.mode: confirm — keel previews every order and waits for your approval. Drop it beside the install (or run keel init-config --live), put your CDP key in a git-ignored .env, then:

keel migrate     # existing database: apply schema migrations
keel init        # fresh deployment: write config + seed candidate rules

Seeded rules start as candidate and trade nothing until you promote them.

Fixes

fix(agent): the cycle line counts rail vetoes and names the rail (#812) (#813)

Closes #812.

What changed

render_loop_result in keel/commands/trading.py now ends each cycle line with a vetoed=N token:

before: ... signals=3 blocked=0 entered=0 exited=0
after:  ... signals=3 blocked=0 entered=0 exited=0 vetoed=3 (account_dd_breaker_weekly)

• N counts entries that were evaluated, not placed, and have a non-empty vetoed_by. It is one per entry, not one per rail (the same one-per-entry rule activity.summarise_cycle uses).
• The overlay’s blocked still differs from this line’s. For one cycle, overlay blocked = line blocked + vetoed + unplaced entries no rail named. Both docstrings now say so; the old summarise_cycle claim that its counts were the line’s is corrected.
• Rail names come from one parse. The new guards.rail_name replaces three copies: activity._first_clause, doctor’s inline split, and this token’s.
• The rail list names each distinct rail once, in first-seen order, using the leading clause of each violation string. The drawdown arithmetic stays in the JSON log. Bare routing-gate tokens such as max_entry_spread are passed through as-is.
• When nothing was vetoed the line prints vetoed=0 with no parentheses, so a missing token never has to be read as zero.
• Existing tokens keep their meaning and order. keel-live-run.sh greps only signals=[0-9]+.

Out of scope

• vetoed= counts entries only. A rail-vetoed exit (for example base_balance refusing a sell) still prints exited=0 with no reason. None has happened in any log yet.
• An unplaced entry with an empty vetoed_by (a paper no-fill, a declined confirm) is still not shown on the line. It isn’t a rail veto, and adding it would mean choosing a separate token.

Verification

• Wrote 4 tests first and confirmed they failed on the missing token. They compare the exact line or its exact tail, not substrings.
• Mutants for “an empty vetoed_by counts as a veto”, “count per rail”, and “no dedupe” were each applied and each killed.
• The cycle-line tests pair each entry result with its signal, as run_once does, so the FET test pins the real line, signals=3 … vetoed=3. guards.rail_name has its own parametrised test.
• Full suite: 6684 passed, 3 skipped. ruff check, ruff format --check and mypy are clean.

fix(web): the console switcher carries no token and sits beside the chip (#815 review) (#816)

Follow-up to #815 (merged, not yet released), from its review. Refs #814.

What was wrong in #815

1. Session tokens reached the page. live_peers returned url_for(record), which is http://host:port/?token=…, for every running console, and /api/config carried the list into <option value>. So the paper console’s page held the live console’s session token, and its own. That breaks security.py (“HttpOnly and must never be written into the page”). On a tunnelled deployment it would also have shipped every local token to the remote viewer.
2. The dropdown was always empty. el(tag, className, text) has no children form, so el("select", …, ...options) set the select’s text to "[object HTMLOptionElement]" and dropped every option.
3. A console with no record could name the wrong console. A console started from a terminal writes no record. It then got a select with no current entry, and once item 2 was fixed the browser would pre-select the first option, which is another console’s name.
4. Each console’s mode was frozen at start-up. It went stale after a config edit, contradicting _auto_trade_mode’s rule of re-reading the config on every request.
5. It turned the session chip into a dropdown, which #704 explicitly forbids. It only got past test_neither_the_chip_nor_the_banner_builds_anything_clickable because select isn’t on that test’s token list.

The fix

• No token on the wire. payload.profile_switcher sends {switchable, choices: [{label, href}], display}. Each href is a token-free /switch/<port> on the current console.
• GET /switch/<port>. This goes through normal admission, then a locality check, then reads the peer’s record at click time. It answers 303 to the peer’s own ?token= hand-off, which is the route keel open already uses. No page script can read a redirect’s Location header.
  • Refusals: no session gives 403; a remote deployment or non-loopback peer gives 403; an unknown, dead or malformed port gives 404; this console’s own port redirects to /.
• One locality rule. security.local_deployment is split out of gated_action_permitted, so the switcher offer and the switch route can’t disagree about what “local” means.
• Service worker. sw.js now sends /switch/ navigations to the network. Otherwise the cached shell would answer them and switching would silently do nothing.
• A separate control. #console-switcher sits beside the chip. It’s a select with a disabled “switch console…” placeholder, listing the other consoles.
  • sessionChip is byte-identical to its pre-#815 code and passes #704’s rule unchanged.
  • The new control has its own rule: navigation only, with no button, link, form, input or handler of its own.
  • The deployment card gains a read-only “running consoles” row.
• Smaller fixes.
  • This console is listed from its own arguments, never from a record.
  • Labels carry no mode, and records no longer store one.
  • serve now calls api._profile_name instead of an inline copy of it.

Verification

• tests/web/test_profile_switcher.py is rewritten (23 tests). The old version asserted the token was present in the URL.
• Six mutants were each killed: spreading children into el, dropping the locality check, removing the service-worker guard, listing this console as a choice, offering switching on a remote deployment, and an extra payload field.
• Full suite: 6711 passed, 3 skipped. ruff check, ruff format --check and mypy are clean.
• Manual check in Chromium. I ran two detached consoles in a throwaway KEEL_HOME (keel-live and keel-paper) with the service worker controlling the page.
  • The chip shows the profile as plain text, and the switcher lists the other console.
  • Switching paper → live → paper works both ways: each lands authenticated (/api/config 200) with no token left in the URL.
  • /api/config contains no token=.
• Known limit: a console started after the page loaded appears on the next reload. Following a stale entry returns a 404 that asks you to reload.

Note: main currently has a JS syntax error from #810 (a duplicate const note in render.js), so every console built from main is blank. It’s fixed separately. For the manual check above I applied that rename locally; it is not in this PR.

fix(web): the refusal view declared note twice, so no page ran (#810 regression) (#817)

Problem

#810 (a1ee344) added const note = el("p") to refusedView in render.js, but that function already declares const note = el("p", "detail"). Declaring the same name twice in one scope is a SyntaxError for the whole module. render.js never loads, main.js imports it, and so every console built from current main shows a blank shell. The browser reports Identifier 'note' has already been declared.

It isn’t released (no tag contains a1ee344), and ~/keel runs 0.16.0, so nothing deployed is affected.

Fix

• Renamed the first note to howNote.
• Added a test: test_no_module_declares_a_name_twice_in_one_scope runs over every module in static/js/. It scans for a const/let/class name declared twice in one block scope, after _code_only strips strings and comments.
• test_the_redeclaration_scan_can_fail pins that the scan catches the #810 shape and doesn’t flag the same name in sibling blocks or loop heads.

Why tests missed it

The repo deliberately has no JavaScript toolchain, so nothing ever parses the client. This scan covers the one class of parse error that got through. It is not a general parser.

Verification

• The new test failed on render.js with ['note'] and passed on the other nine modules before the fix.
• node --check parses the fixed render.js.
• tests/web: 987 passed. ruff is clean.
• I ran the same rename in a real browser while checking #816, and the shell loads.

Other changes

fix(execution): a cache record predating quote_increment is a MISS, not an “unknown” (#807)

#802 shipped inert on the deployment it was cut for. Found in production, 2026-09-17.

What happened

record fetched_at : 2026-09-16 01:20:01   (written by the pre-#802 build, no quote_increment key)
0.16.0 installed  : 2026-09-16 20:21
cycle now_ts      : 2026-09-17 01:20:03
age               : 24.0 h  against a 168 h TTL  ->  counted FRESH

=> _price_increment_for read the absent key as "unknown"
=> prices went out unrounded
=> executor.order_rejected  PAXG-USD SELL  'Too many decimals in order price'

The identical rejection as before the upgrade, on a build that contained the fix. The position stayed unprotected, and would have for up to seven days.

Clearing the row by hand healed it immediately — the venue reports the tick fine (PAXG-USD base=0.00001 quote=0.01) — and the rejection moved on to a different, legitimate one. But no deployment should need that.

The first cut called this correct

“A record written before #802 carries no quote_increment key and reads as unknown until it expires, which is correct: nothing knew the tick when it was written.”

Correct in the narrow sense. Operationally it waits out a TTL on data already known to be incomplete, and does so on precisely the machines that just upgraded to get the fix.

The obvious fix has a worse trap

“Refetch whenever the key is missing” would refetch every cycle, forever, for any product whose venue genuinely reports no tick — putting a venue round-trip back into the order-placement path this cache exists to keep out of. That is the latency get_instrument’s per-product shape was chosen to avoid.

So the writer now records quote_increment always, explicitly null when the venue has none:

record state	meaning	action
key absent	written before anyone asked	refetch once
key present, null	the venue was asked and has none	honour it, don’t re-ask
key present, value	known	use it

force_refresh, not a delete

_base_increment_for grew a keyword rather than having the caller delete the row first. Deleting is the shorter way to force a miss and the wrong one: a venue call that then failed would have discarded a perfectly good base_increment and put SELL sizes back on the wire unquantized, which is #513.

One test changed rather than being deleted

test_a_record_without_a_quote_increment_reads_unknown (from #804) asserted the old behaviour — it pinned the defect. It is now test_an_unparseable_quote_increment_reads_unknown, keeping the narrower claim that survives: a value present and unusable is unknown, and is not repaired by guessing the common tick. The docstring says why it changed.

Verification

Mutation, both halves independently:

• reverting the read guard ("quote_increment" in cached) → 2 tests fail
• writing the key only when non-null → the third fails

ruff check keel tests packages  -> All checks passed!
mypy                            -> clean (466 files; pre-existing PyYAML note)
pytest                          -> 6670 passed, 3 skipped

feat(console): the refusal now says how to GET the address it asks you to paste (#810)

What the operator saw

keel is running, and did not admit this browser

...the token is new every run and is never written to disk -- so if keel has been
restarted since this browser last worked, the address printed THIS time is the one
that admits it. Paste that address into the address bar here...

[ Paste the address keel printed, or just its token ]  [Reconnect]

Cause named well. Remedy named nowhere.

Two failures, and the second is the bad one

1. keel open is never mentioned. It is named in server.py:1125, in the launchd plist (“This process prints its URL… where nobody is reading. Do not grep the log for it. Run keel’s open command”), and in runtime.py’s own module docstring — everywhere except the screen the locked-out operator is looking at.

2. “never written to disk” is no longer true, and it is the sentence that closes the door. Since #756, that holds only for a server attached to a TERMINAL. Detached — launchd, a pipe, a container — runtime.py records the address in a 0600 file precisely so keel open can hand it back. A reader who believes the sentence concludes the token is unrecoverable and restarts the server, which mints a NEW one. refusedView’s own docstring already warns about that move: “sends them to restart the thing that is working… and makes the situation worse.”

Evidence it fails in practice: on 2026-09-16 two people who know this codebase were locked out by a daemon restart. One went to keel open --help; the other asked a colleague.

The change

An instruction block above the paste field — the command produces the value the field consumes, so meeting the field first means being asked for something you do not have:

To get this run’s address, from your keel deployment directory:

keel open --port 8765

It opens the console, and prints the address so you can paste it below. Attached to a terminal keel prints the address and keeps nothing; run as a service it records the address for that command and deletes it on shutdown.

The field’s label moves from “Paste the address keel printed” — past tense about something a daemon wrote to a log the plist says not to grep — to “Paste the address from that command”.

Boxed, monospaced, user-select: all, because its whole purpose is to be copied. The detail paragraph beside it runs five sentences; a command appended as a sixth is a command nobody sees.

Two constraints worth noting

The port comes from window.location, the same source and stated reason as timelineExportUrl and the deployment card: a fact about where this page is, not a claim from a payload that just refused us. Nothing else about the deployment is named — the path in particular. The port is the one fact the reader demonstrably already has (they reached this page on it), so naming it discloses nothing to a request that was not admitted. That begins to matter once #648 lets this console answer beyond loopback.

openCommandNode returns a node and joins nothing. render.js may use neither template literals nor + — test_render_contains_no_arithmetic bans the operator outright rather than try to tell string concatenation from money, and my first attempt tripped exactly that gate. append takes several strings, so the port is placed beside the command instead of joined to it. A default-port URL gives location.port as the empty string and takes the bare command, which keel open defaults correctly.

Verification

Six tests, each naming the mutation it rejects, asserted on code with comments stripped so the prose explaining the change cannot stand in for the change. Mutation-verified:

mutant	result
drop the command	3 failed
hardcode the port	1 failed
revert the label	1 failed

tests/web                       -> 972 passed
ruff check keel tests packages  -> All checks passed!
mypy                            -> clean (467 files; pre-existing PyYAML note)
pytest                          -> 6673 passed, 3 skipped

Not changed: the server-side 403 detail text still carries the stale “never written to disk” sentence for non-browser clients. Worth a follow-up; this PR is the HTML view only.

feat(web): in-app profile switcher dropdown for multi-daemon navigation (#814) (#815)

Summary

Closes #814.

Implements an in-app profile switcher dropdown in Keel’s Honest Cockpit (keel serve / keel open), enabling operators to switch directly between running console daemons (live, paper, hourly, equities) via the browser header without invoking terminal commands.

Changes

• Runtime Peer Discovery (keel/web/runtime.py): Added profile and mode to serving runtime record; added live_peers(current_port) to discover running daemon files in ~/.keel/run/, verify PID liveness and port connectivity, and clean up stale files.
• Server Integration (keel/web/server.py): Supplies active profile name and auto-trade mode when recording serving status.
• Config Payload (keel/web/payload.py, keel/web/api.py): Serializes verified peer metadata with wire-safe types.
• Frontend UI & Event Wiring (keel/web/static/js/render.js, main.js, keel.css):
  • sessionChip: Renders <select class="profile-select"> when multiple active daemons exist, or static text when single.
  • deploymentCard: Lists all active profile peers.
  • main.js: Delegated change event navigates browser to chosen daemon URL.
  • keel.css: Light/dark theme styling for profile selector dropdown.
• Tests (tests/web/test_profile_switcher.py): 5 unit tests covering record writing, peer discovery, stale cleanup, wire types, and DOM structure.

Verification

• uv run pytest tests/web/: 977 passed in 153.91s
• uv run ruff check keel/web/ tests/web/: All checks passed!
• uv run mypy keel/web/: Success: no issues found in 9 source files

chore(release): 0.17.0 — rail vetoes on the cycle line, and a console switcher with no tokens (#818)

Version bump for 0.17.0. It moves the eight workspace versions and the inter-package == pins together, plus uv.lock. Same shape as 0.16.0 (#806): 9 files, 25 lines in and 25 out. uv lock --check passes.

Why a minor bump: #810 and #814/#816 add console features. There is no schema change since v0.16.0 (keel/data/ is untouched), so upgrading needs no new migration.

What’s in it since v0.16.0

• #807: a quote-increment cache record from before quote_increment existed now counts as a cache MISS, not “unknown”.
• #810: the “refused” page now explains how to get the address it asks you to paste. #817 fixes a duplicate const note in that change, which had blanked the whole console on main.
• #813 (#812): the per-cycle log line now ends with vetoed=N (rail, …), so an entry the rails refused no longer reads as a silent drop.
• #815 + #816 (#814): a console switcher next to the session chip. /api/config carries no session tokens; /switch/<port> sends the browser into the chosen console’s own sign-in, on local deployments only.

After merge

1. Run Actions → Release with version 0.17.0.
2. Install into ~/keel using the runbook’s “Deploying a new version” steps: back up each database, install the five wheels, run keel migrate, then keel versions and keel status.
3. Restart the four long-running keel serve consoles, since they keep the build they started with.

Built from c86de7738d05. Version binds to this hash: keel --version reports keel 0.16.0+c86de7738d05 [release].

Install

Download all wheels from this release into one directory, then install the keel_trader wheel by path:

pip install --find-links . ./keel_trader-0.16.0-py3-none-any.whl
keel versions

keel versions — not keel --version — is the check: it reports every keel distribution in the venv and exits non-zero if a sibling was left behind at an older version, which --version cannot see. Upgrading an existing deployment: see “Deploying a new version” in the README.

⚠️ Never install by bare name. The distribution is keel-trader; the name keel on PyPI belongs to an unrelated project, so pip install keel fetches someone else’s package. A build reporting DIRTY or [checkout] is not this release and must not be run against live funds.

Configure

config.yaml is attached to this release: the production config, in auto_trade.mode: confirm — keel previews every order and waits for your approval. Drop it beside the install (or run keel init-config --live), put your CDP key in a git-ignored .env, then:

keel migrate     # existing database: apply schema migrations
keel init        # fresh deployment: write config + seed candidate rules

Seeded rules start as candidate and trade nothing until you promote them.

Other changes

fix(execution): quantize bracket prices to the venue tick, in opposite directions (#802) (#804)

Closes #802.

The bug

Sizes were quantized (#513/#516). Prices were not.

2026-09-16 03:44Z, keel-live.db order id 5
executor.order_rejected  PAXG-USD SELL  error='Too many decimals in order price'

_bracket_spec floored base_size and passed stop/target straight through, so 4521.76390215979454 went on the wire. sizing.quote_increment_for looks like it covers this and does not — its own docstring says “the venue’s finest acceptable quote_size”, it is keyed on the CURRENCY not the product, and it is applied in one place: a BUY’s notional.

Every protective bracket was rejected. All three positions on the live deployment carry bracket_order_id = NULL, and the stop-loss/take-profit machinery has never fired there. Nothing distinguished that from DCA’s legitimate bracket-lessness, in any surface.

Direction is the substance, not a detail

quantize_down is documented as the safe direction for sizes — rounding a size up spends more than guards.check authorised. That reasoning does not transfer to a protective stop: rounding a long’s stop DOWN moves it further from price and widens the loss the position was sized against, silently, on every bracket.

So:

price	direction	why
stop_trigger_price	up	toward safety — never widen the risk the position was sized on
take_profit_price	down	toward reachability

quantize_up is a separate function, not a flag on quantize_down, because the two are justified by different arguments and a flag invites picking the wrong one by habit.

Note Decimal.__floordiv__ truncates toward zero rather than flooring, so the usual -((-v) // i * i) ceiling idiom silently returns the floor. It steps up explicitly instead, with a comment saying why.

A collapsed pair is refused, not sent

The two prices round toward each other, so a coarse tick can invert a pair that was valid before it. That raises BracketPricesUnplaceable rather than reaching the venue.

And the #799 shape is closed while we’re here

_bracket_spec was an inline argument to _run_order, so anything it raised left place_bracket past the if not result.placed recovery — exactly how a filled PAXG entry was stranded for three weeks. It is now built inside a try, and a bracket that cannot be BUILT is the same event as one the venue REFUSES: levels recorded to unbracketed:, a WARNING, a retry next cycle. There is a test asserting the retry record holds the RULE’s unrounded levels.

Where the tick comes from

Instrument.quote_increment, the field its own docstring anticipated (“would sit here naturally, but nothing reads them yet, and a field no caller reads is a field no test meaningfully checks”). It rides the existing per-product fetch and the existing cache record, so no extra venue round-trip enters the order-placement path. A pre-#802 cache record simply reads as unknown until it expires, which is correct — nothing knew the tick when it was written.

Unknown stays unknown: prices go unrounded, never refused. Refusing would leave a filled position with no stop at all, which is the #799 outcome.

Verification

Mutation: reusing quantize_down for the stop — the fix that still puts prices on the tick and would pass a naive “is it rounded?” check — is killed by three tests.

ruff check keel tests packages   -> All checks passed!
ruff format --check .            -> 503 files already formatted
mypy                             -> clean (465 files; pre-existing PyYAML stub note only)
pytest                           -> 6651 passed, 3 skipped

Deployment note

The live PAXG position is currently retrying its bracket every cycle and escalating reconcile.position_unprotected at CRITICAL. This is what lets that retry succeed.

fix(ledger): carry the owning rules.id on a position so exits are attributed (#803) (#805)

Closes #803.

The bug

SELL   PAXG-USD   rejected   unattributed   0.01320427

OrderIntent carries two different facts in two fields (guards.py:194-200): rule_kind, a KIND ("dca", "turtle_breakout"), and rule_id, the rules.id row. Entries thread the id from signal.rule_id. Both exit paths build their intent from a POSITION, not a signal — and positions stored only the kind, so there was no id to thread and every protective SELL was written with orders.rule_id NULL.

Not cosmetic: per-rule accounting reading orders.rule_id sees entries attributed and exits anonymous, which for a trend rule drops precisely the leg the outcome lands on.

Not caused by the demotion, which is the natural first guess — rule 3 went live -> paper shortly before this order, which looks exactly like a lookup that stopped resolving. The id was never on the intent; the row would read unattributed with the rule live. The migration docstring records that, so the next reader doesn’t re-derive it.

The change

• v21: positions.rule_id INTEGER, nullable.
• _open_tranche inherits it from the ENTRY order rather than taking a new argument. That order was already written with signal.rule_id, so every caller gets the attribution without one more parameter to forget.
• place_bracket and scale_out take an optional rule_id and put it on the intent; the four call sites pass position["rule_id"] or signal.rule_id.

No backfill

The call v12 made for initial_stop. A tranche records its bracket order, never its entry order, so there is no join back to the id. Matching on (product_id, rule_name) would re-attribute by guess and be wrong wherever a rule row was replaced. NULL means “nobody recorded it”, and there is a test asserting a pre-v21 row reads NULL rather than acquiring an owner.

rule_id is optional everywhere, deliberately

There is a test for that on its own: a missing id must never cost a position its stop. A pre-v21 tranche has none, and refusing to protect it because the bookkeeping is incomplete would trade a reporting gap for an unprotected position.

Verification

Mutation: dropping rule_id=rule_id from place_bracket’s intent — which puts live order id 5 back in exactly the state that prompted this — fails the end-to-end test and nothing else.

Nine hardcoded SCHEMA_VERSION == 20 pins across three test files moved to 21, and three new migration tests cover the fresh schema, the no-backfill path, and idempotency.

ruff check keel tests packages   -> All checks passed!
mypy                             -> clean (465 files; pre-existing PyYAML stub note only)
pytest                           -> 6643 passed, 3 skipped

Note for the deployment

This is a schema change: keel migrate must run on all four databases before the new build trades. The ALTER is guarded by PRAGMA table_info and adds a nullable column, so it is non-destructive and idempotent.

Stacked behind #804 (#802) in spirit but independent in code — they touch different files and can land in either order.

chore(release): 0.16.0 — brackets reach the venue, and exits name their rule (#806)

Version bump only. No behaviour change in this PR.

Why MINOR and not a patch

#805 ships schema v21 (positions.rule_id). A deployment must run keel migrate on every database before the new build trades, and the version number is the only signal an operator gets before they read the notes. 0.15.1 was a pure bug fix and was numbered accordingly; this is not.

What lands

#804 (#802)	Bracket prices quantized to the venue tick — stop up, target down. Until now every protective bracket was rejected with Too many decimals in order price, so the stop-loss and take-profit machinery had never fired on the live deployment. Nothing distinguished that from DCA’s legitimate bracket-lessness.
#805 (#803)	positions.rule_id, so the protective SELL exiting a tranche names its owning rule. Both exit paths build their intent from a position, so every bracket, roll and scale-out was written unattributed while its entry carried the name.

Both PRs were reviewed and both reviews found a real defect the original missed — an unpatched second _bracket_spec call site in one, an untested inheritance line in the other. Those fixes are included.

What moved

• eight workspace pyproject.toml version fields, 0.15.1 → 0.16.0
• fourteen inter-package ==0.15.1 pins → ==0.16.0 (these are what a keel versions PARTIAL INSTALL comes from when left behind — this deployment has hit that before)
• uv.lock, refreshed via uv lock

Verified locally

grep -rn '0\.15\.1' pyproject.toml packages/*/pyproject.toml  -> (none)
ruff check keel tests packages                                 -> All checks passed!
ruff format --check .                                          -> 504 files already formatted
keel/templates/config.live.yaml                                -> mode: confirm
keel/data/db.py                                                -> SCHEMA_VERSION = 21
pytest tests/execution tests/data tests/test_agent.py          -> 1134 passed

After merge — the order matters

1. Actions → Release → Run workflow, entering 0.16.0
2. Install the five production wheels by path into ~/keel
3. keel migrate on all four databases — new column; the ALTER is guarded and nullable, so it is non-destructive and idempotent, but the build should not trade before it runs
4. Restart the four console daemons

The live deployment has a PAXG position retrying its bracket every cycle and escalating reconcile.position_unprotected at CRITICAL. #804 is what lets that retry finally succeed.

Built from 68656b507b30. Version binds to this hash: keel --version reports keel 0.15.1+68656b507b30 [release].

Install

Download all wheels from this release into one directory, then install the keel_trader wheel by path:

pip install --find-links . ./keel_trader-0.15.1-py3-none-any.whl
keel versions

keel versions — not keel --version — is the check: it reports every keel distribution in the venv and exits non-zero if a sibling was left behind at an older version, which --version cannot see. Upgrading an existing deployment: see “Deploying a new version” in the README.

⚠️ Never install by bare name. The distribution is keel-trader; the name keel on PyPI belongs to an unrelated project, so pip install keel fetches someone else’s package. A build reporting DIRTY or [checkout] is not this release and must not be run against live funds.

Configure

config.yaml is attached to this release: the production config, in auto_trade.mode: confirm — keel previews every order and waits for your approval. Drop it beside the install (or run keel init-config --live), put your CDP key in a git-ignored .env, then:

keel migrate     # existing database: apply schema migrations
keel init        # fresh deployment: write config + seed candidate rules

Seeded rules start as candidate and trade nothing until you promote them.

Other changes

ci(snyk): déclarer le dépôt public au CLI, sinon le scan est facturé comme privé (#796)

Le piège

Les plafonds du plan gratuit Snyk — 200 tests Open Source/mois, par organisation, partagés avec les autres dépôts de CodeGateSoftware — ne s’appliquent qu’aux dépôts privés. keel est public : ses scans devraient être gratuits et illimités.

Sauf que le CLI ne peut pas le deviner. Un checkout actions/checkout n’expose pas de remote exploitable, si bien que Snyk classe par défaut tout scan lancé en CI comme un test privé — y compris sur un dépôt public. --remote-repo-url est le mécanisme documenté pour le lui dire.

Sans lui, ce job consommerait le quota privé de l’organisation à chaque push sur main : ~196 par mois sur la période mesurée, soit à lui seul le plafond entier partagé par tous les dépôts.

Pourquoi maintenant, alors que rien ne casse

Le job est aujourd’hui skipped faute de SNYK_TOKEN/SNYK_ORG — vérifié sur huit exécutions consécutives. C’est justement le bon moment : le drapeau est posé pour que l’activation du scan ne vide pas le quota sans prévenir.

Posé sur snyk test et sur snyk monitor : les deux créent une cible, donc les deux doivent la déclarer publique.

fix(coinbase): guard the adapter’s preview Decimal conversions against empty fields (#799) (#800)

Closes the code half of #799.

The bug

_field(response, key, "0") supplies a default for a missing key. It does nothing for a key that is present and empty, which is what Coinbase sent. Decimal("") raises InvalidOperation.

-  est_base_size=Decimal(_field(response, "base_size", "0")),
+  est_base_size=Decimal(_field(response, "base_size", "0") or "0"),

…and the same for quote_size and commission_total.

Why it mattered

2026-08-25, live, cycle e917fb3d21544dc2:

13:20:20  executor.order_placed    PAXG-USD BUY  order_id=4  status=filled
13:20:21  executor.preview_failed  PAXG-USD SELL
          decimal.InvalidOperation: [<class 'decimal.ConversionSyntax'>]

The entry filled. The protective SELL’s preview then threw, and the exception propagated out of executor._run_order before agent.py’s repo.open_position(...) ran. Three weeks later that holding is still stranded: no positions row, so no channel exit and no 2xATR stop can ever fire; its computed stop of 4521.76 exists only in a log line (PAXG is now ~4312, so the stop was breached and nothing acted); and $61.71 still counts against the exposure caps, because _open_exposure_by_asset reads orders, not positions.

agent.tranche_not_recorded — the warning that exists for “entry filled but not recorded” — did not fire. It only covers a missing actual_fill/qty. This path throws earlier and logs a preview failure, which reads like a harmless pre-trade hiccup.

Why it was still live

The retired keel/data/cb_client.py already carries or "0". The adapter that replaced it does not — #524 flipped _build_broker to the registry-resolved adapter, so the fix landed on the path being retired and not on the path that replaced it. The August failure would recur today.

Test

Parametrized over the three fields. Each case asserts the emptied field reads 0 and that the other two still parse from the fixture, so a blanket try/except zeroing the whole Preview does not pass it. Verified by mutation: restoring the bare conversion for one field fails that field’s case alone, leaving the other two green.

ruff format --check and ruff check clean; mypy clean apart from a pre-existing PyYAML stub note in scripts/release_notes.py; tests/broker_coinbase tests/broker_api tests/execution → 602 passed.

Not in this PR

#799’s other three items are deliberately left open — they are design changes, not a one-line guard:

• a filled entry must survive a later failure (record the position, or downgrade to an explicit UNBRACKETED state the codebase already models)
• preview_failed on a protective leg after order_placed needs its own event and a doctor check for filled BUYs with no position row
• reconciling live order id=4 is an operational decision, not a code one

chore(release): 0.15.1 — the adapter preview guard reaches the live path (#801)

Version bump only. No behaviour change in this PR — it exists so the fix already merged as #800 can actually ship.

Why now, specifically

~/keel reports keel 0.15.0+cd6f0d193bfe [release], and 0.15.0’s wheels predate #800. The deployed adapter still reads:

est_base_size=Decimal(_field(response, "base_size", "0")),   # unguarded

That is the line behind #799: on 2026-08-25 a live PAXG entry filled, the protective SELL’s preview raised decimal.InvalidOperation, and the exception propagated out of executor._run_order (deployed executor.py:979 previews inside it) before the position row was written — stranding funded inventory with no exit for three weeks.

The recovery for that position has now been armed on the live deployment (a positions row plus an unbracketed:PAXG-USD intent, so reconcile_unbracketed_positions re-brackets it). That recovery runs through the same preview path, on the same unguarded code, until this ships.

What moved

• eight workspace pyproject.toml version fields, 0.15.0 → 0.15.1
• fourteen inter-package ==0.15.0 pins → ==0.15.1. These are separate from the version field and easy to miss; left behind they are exactly what makes keel versions report a PARTIAL INSTALL, which this deployment has hit before.
• uv.lock, refreshed via uv lock (keel-trader, keel-core, keel-broker-* → 0.15.1). The release workflow checks the lockfile before anything else and fails if it was left stale.

Verified locally

grep -rn '0\.15\.0' pyproject.toml packages/*/pyproject.toml   -> (none)
ruff check keel tests packages                                  -> All checks passed!
ruff format --check .                                           -> 502 files already formatted
pytest tests/broker_coinbase tests/execution                    -> 559 passed
keel/templates/config.live.yaml                                 -> mode: confirm

The last line is the release asset the workflow refuses to publish in any other mode.

There is one pre-existing E501 in docs/experiments/2026-09-02-equities-cost-fidelity.py. The workflow scopes ruff check to keel tests packages, so it does not gate this release; noted rather than silently fixed in a release PR.

After merge

Actions → Release → Run workflow, entering 0.15.1. Then the five production wheels install into ~/keel by path, and keel versions should report 0.15.1 across all five.

Built from cd6f0d193bfe. Version binds to this hash: keel --version reports keel 0.15.0+cd6f0d193bfe [release].

Install

Download all wheels from this release into one directory, then install the keel_trader wheel by path:

pip install --find-links . ./keel_trader-0.15.0-py3-none-any.whl
keel versions

keel versions — not keel --version — is the check: it reports every keel distribution in the venv and exits non-zero if a sibling was left behind at an older version, which --version cannot see. Upgrading an existing deployment: see “Deploying a new version” in the README.

⚠️ Never install by bare name. The distribution is keel-trader; the name keel on PyPI belongs to an unrelated project, so pip install keel fetches someone else’s package. A build reporting DIRTY or [checkout] is not this release and must not be run against live funds.

Configure

config.yaml is attached to this release: the production config, in auto_trade.mode: confirm — keel previews every order and waits for your approval. Drop it beside the install (or run keel init-config --live), put your CDP key in a git-ignored .env, then:

keel migrate     # existing database: apply schema migrations
keel init        # fresh deployment: write config + seed candidate rules

Seeded rules start as candidate and trade nothing until you promote them.

Other changes

feat(web): the Status and Setup pages, one section at a time (#773) (#774)

Closes #773.

Both pages had grown past the point where an operator could see anything at a glance. Status scrolled through four state cards and four tables; Setup through the deployment card and then every step of both runbook stages, each a full card with its form — about 6,000px, with the go-live steps below the fold of the fold.

Each now shows one section, chosen from a tab bar:

page	sections
Status	Status · Open positions · Rules · Data freshness · Subscriptions
Setup	Setup · To run in paper · To go live

The control is the one scopeSwitch and statusSwitch already establish — nav.scopes / button.scopekey, aria-current carrying both the underline and the announcement, data-focus putting focus back on the pressed tab’s replacement. No CSS was added.

This is not a filter, and that is why it stays in the client

statusSwitch and scopeSwitch both re-ask the server, because both narrow a collection the server capped on the way out — filtering a received page in the browser would present “the rows that happened to arrive” as the whole answer.

This control narrows nothing. /api/status sends every section of the status page in one document and always did; choosing which of them to draw is presentation, and no section is ever unreachable — every one of them has a tab, always. So there is no ?section=, and no “all” tab: the way back to any section is that section’s own tab, and an “all” tab would re-create the page these two views were cut up to stop being.

The sections are a table, not five branches

STATUS_SECTIONS and SETUP_SECTIONS pair a key, a label and a builder, so the bar cannot offer a section the page has no builder for. The label is written once and reaches both the tab and the section’s own heading — each builder is handed the entry it was reached through — which forecloses a tab and a heading disagreeing about which section a reader is looking at.

STAGES is folded into SETUP_SECTIONS for exactly that reason: it carried a second copy of “To run in paper”.

An unwired onSection renders every section with no bar — the page exactly as it read before — rather than one section with no way to reach the others. Same guard as ordersView’s onStatus, and the same reason: a control nobody wired must not cost a reader anything.

The section is kept per route.name in main.js and survives navigation, so the two pages remember their sections independently. The press forces the repaint: unforced, the rebuild is deferred while focus sits on the button that was just clicked, and a control that does nothing is indistinguishable from a broken one.

Tests

tests/web/test_view_sections.py (18 tests) pins the tables as parsed out of the JavaScript rather than restated:

• both tables declare the sections in the page’s own former reading order;
• every section has a builder of its own — a table pointing five entries at one function would satisfy every label assertion and render one section under five tabs;
• every key is distinct, and each of the four status headings is written by the builder its entry names;
• no builder re-spells its label; if it writes a heading, it writes entry.label;
• neither view dropped a payload key in the split (_view_keys against /api/status and /api/setup, pinned);
• one sectionSwitch, one sectioned, and the two bars announce themselves differently;
• the shell keys sections by route.name and forces the repaint.

tests/web is green: 835 passed.

Verified by hand, since the suite cannot

There is no JavaScript runtime in this repository, so what the source-text suite cannot establish was checked against a running keel serve:

• all five status tabs and all three setup tabs render their section and only their section (paper 7 step cards, live 5);
• focus lands back on the pressed tab after the rebuild;
• each table keeps its heading as its aria-labelledby;
• Setup’s “To go live” and Status’s “Rules” are remembered independently across navigating away and back;
• console clean, no errors or warnings.

Page height: Status 1,900px → 619–1,074px. Setup ~6,000px → 930px on its first section.

fix(web): the section tabs had tests that passed on broken code (#775) (#776)

Closes #775. Follow-up to #774.

A post-merge review ran thirteen defects through the client. Twelve passed the suite. The one that failed did so by accident — caught by a payload-key pin, not by any test aimed at it.

The cause was uniform: the assertions were "onSection" in body and "data-focus" in body. A source-text scan passes on a declaration alone; onSection is in the signature. Naming an identifier proves the author typed it, never that it is wired to anything.

Mutation score

	before	after
defects rejected	1 / 13	13 / 13

Each mutation is applied to the client, the mutated bytes are read back off disk (a no-op mutation looks exactly like a killed one), the suite runs, and the file is restored in a finally. Every test below names the mutation it exists to reject and was proved red against it.

target	mutation	what shipped
sectioned	delete the if (!onSection) block	the documented “unwired renders everything” degradation, gone
sectioned	const here = sections[0];	bar renders, presses recorded, the page never changes section
sectioned	drop the sectionSwitch append	section one is the only reachable section
sectionSwitch	one shared data-focus	every keyboard press dumps focus onto tab one
sectionSwitch	unconditional aria-current	a screen reader is told all five sections are current
stageSteps	filter hardcoded to "paper"	the To go live tab renders the paper checklist
stageSteps	delete the blurb / the empty-stage line / hardcode the heading	the paper-is-safe argument disappears
setupLive	forward SETUP_SECTIONS[1]	its neighbour’s stage under its own tab — the mutation its docstring called unspellable
statusFreshness	a second heading("h-positions", …)	two elements share one id; a table announced under the wrong heading
onSectionFor	sections.set("status", key)	Setup’s presses land in Status’s bucket; Setup can never leave section one

stageSteps — the function that draws every Setup step — had no test of any kind.

The regression that shipped

market_data is a Stage.PAPER step, so Fetch market data is pressed from the To run in paper tab — and the panel reporting it was inside the Setup section. The job’s state line, elapsed time, streamed transcript and job.error were all invisible to the person who started it.

jobPanel’s docstring keeps a failure on screen because “the whole point of running something in the background is that nobody was watching when it broke”. The split defeated that structurally. setupSummary’s docstring justified the placement with reasoning that was exactly backwards; the correction is written where the claim was.

The panel is page-level state, like the <h1>. It renders above the switch now.

Two structural traps, named so they are not re-dug

_decl bounds at the next top-level declaration, not at the next \nfunction . The old bound sailed past export function and const — measured, what it called statusSubscriptions’ body swallowed all of setupView and the whole SETUP_SECTIONS table. Every count taken over it was counting the wrong thing.

A test guarded by if "heading(" in body is a test that can skip itself. That guard made the label-to-heading check assert nothing for all three Setup sections, because Setup’s heading is written one hop down in stageSteps — so the page whose duplicate wording motivated the whole table was the page nothing was checking. _delegate follows the hop.

Smaller

• sectioned/sectionSwitch named their Section[] parameter table, shadowing the module’s row renderer. test_every_call_resolves_to_something_the_module_has scopes parameters per function, so it would keep passing while a table(...) added inside either resolved to an array and shipped a runtime TypeError — the miss that test’s own docstring records from #701.
• Their payload parameter is payload, not data: both sit inside activityView’s _view_keys region, where a data.<key> would be checked against /api/activity. The rename makes the mistake unspellable rather than merely unmade.
• onSectionFor now names what the round trip costs — a read that fails replaces the section with stoppedView, for a document the client was holding in full, with no aria-busy while it waits.

Verified

tests/web: 843 passed. In a browser against a running keel serve: the job panel renders above the tab bar on all three Setup sections with its transcript intact, and the sections still show 7 paper steps and 5 live steps.

fix(test): the orders book fixture failed for sixty seconds of every UTC day (#777) (#778)

Closes #777. Fixes the red on main from run 34419113683.

FAILED tests/web/test_orders_view.py::test_the_scope_is_normalised_and_echoed_rather_than_refused
  assert '0' == '1'

Why it failed

?scope=today is a UTC calendar day, not a rolling window: scope_start_ts returns 00:00 UTC of the current day and gather_orders skips a row when created < start_ts. The book fixture placed its live order at now - 60.

That run’s started_at was 1788998401, and 1788998400 is exactly 20706 × 86400 — one second past UTC midnight. The row landed at 23:59:01 on the previous UTC day and fell outside the scope it exists to be inside.

	window	frequency
before	first 60s of every UTC day	~1 run in 1,440
after	fixture/server clock reads straddling midnight	~1 run in 10,000,000

Green on every rerun, which is what makes it the kind of failure that gets rerun rather than read.

Not from #773/#774 — that PR touched render.js, main.js and a new test module. This fixture dates from #659.

The fix

max(now - 60, scope_start_ts("today", now)), extracted into _recent_ts so it can be tested without waiting for midnight.

Still anchored on the real clock, for the reason the fixture already gave — a fixed future instant would put every row inside every scope and make the scope assertion pass without the scope doing anything. Clamped, not replaced: the row stays a minute old on all but one run in 1440. The bound is inclusive (created < start_ts is what skips), so landing exactly on it is inside.

The pin is a real one

Parametrised at five points around the boundary. Reverted to now - 60 it goes red at 00:00:01 and 00:00:59 and stays green at 00:01:00, midday and 23:59:59 — it discriminates the flake window from the rest of the day rather than merely asserting the helper exists.

A second test holds the other half of the pairing: the 90-day-old row must stay outside today. A clamp that dragged both rows into today would make the scope assertion pass while proving the scope does nothing.

What is deliberately left open

The fixture reads the clock and the server reads it again a moment later. Reads that straddle midnight place the row in the old UTC day and judge it against the new one — the setup-to-request gap, order of 100 ms.

Closing it needs a sleep past the boundary in a fixture, or a skip guarded on the echoed scope_start_at. The second is a test that can decide not to run — the failure #775 is about — because were scope_start_at ever wrong, the guard would silently skip forever instead of going red. The residual is written into _recent_ts’s docstring rather than papered over.

Verified

tests/web + tests/commands/test_orders.py: 926 passed.

fix(web): every reader answers on the clock it was handed (#779) (#780)

Closes #779. Step 1 of the two agreed items.

respond reads time.time() once per request and threads it to route.read(cfg, query, state, now_ts). Sixteen readers use it. Two took it as _now_ts and read the clock again for themselves:

read_activity   apply_scope(feed, scope, now_ts=time.time())
read_orders     gather_orders(repo, now_ts=int(time.time()), ...)

What that cost

The document reported two instants. The envelope’s generated_at came from the dispatcher’s reading, the scope boundary from the reader’s a moment later. Across a UTC midnight those are different days, and ?scope=today answers about a day the page does not claim to be showing.

Not theoretical — #777 is the day it cost a red CI run.

And it made those two the only readers a test could not choose a clock for. #778 had to monkeypatch.setattr(web_api.time, "time", …), patching the time module process-wide, to get a deterministic reproduction. That is no longer necessary anywhere on the read surface.

No behaviour change

now_ts is computed per request at the top of respond (api.py:1205) — verified before touching it, because had it been computed at server start, wiring it up would have frozen the clock in production. This is the same instant, read once instead of twice.

read_setup, read_plans, read_rules, read_venues and read_gates keep _now_ts: they are genuinely time-free.

Tests

Each reader is called directly with a now_ts a decade from any wall clock, so a reader that ignores its argument cannot agree by coincidence — the same test at an instant inside today passes either way, which is why both are parametrised. The activity boundary is compared against scope_start_ts’s own answer, not a restated literal.

test_no_reader_reads_the_clock_a_second_time keeps the rule after these two instances are gone.

A bound that lied, caught in passing. My first version of that scan bounded each function at the next def read_, which swept helper functions into the preceding reader and reported five clock reads inside read_gates — which has none. Same region-bounding error _decl carried in #775. The scan bounds at the next top-level statement, and the docstring says why.

mutation	result
read_orders back to int(time.time())	KILLED
read_activity back to time.time()	KILLED
dispatcher’s own now_ts → a constant	KILLED

The third matters: it proves the injection is real end to end rather than shadowed by a reader that would have read the right value anyway.

Verified

tests/web + tests/commands/test_activity.py + tests/commands/test_orders.py: 1112 passed. ruff, format and mypy clean.

fix(test): the clock-injection tests never exercised the seam they were about (#782) (#784)

Closes #782. Follow-up to #780.

#780’s product change was correct — traced and confirmed: float→int loses nothing, now_ts is per-request on every path including SSE, the rename is complete. This PR touches no product code. Its tests were the problem.

	mutations killed
before	2 / 11
after	11 / 11

The seam with no test

respond reads the clock once and threads it to route.read(...). That sentence is the whole of #780 — and all three of its tests called the readers directly. Nothing in the module called respond; generated_at appeared only in docstrings, never in an assertion.

mutation	before
a day-old clock threaded to every reader	204 tests pass
now_ts hoisted to a module constant, read once at import	204 tests pass
the value floored to UTC midnight	204 tests pass

The second would have a long-running keel serve answering every request on its boot instant. test_respond_hands_the_reader_the_same_instant_it_stamped goes through the dispatcher and asserts both halves, because they fail to different mutations: as_of catches a value altered before stamping, scoped_count one altered before being handed down.

A test that passed having scanned nothing

test_no_reader_reads_the_clock_a_second_time built offenders from a loop and asserted it empty — with nothing pinning that the scan found anything. It walks 43 top-level definitions and classifies 18 readers, and passed identically when narrowed to classify zero. The population is now cross-checked against API_ROUTES, the list the server actually dispatches to, so it cannot drift into a number nobody maintains.

The scan is an ast walk now, which fixes four things at once:

• a third offender written int(datetime.now(tz=UTC).timestamp()) escaped — both names are already imported in api.py, so it is a one-line in-idiom defect;
• so did one hidden a call deep in a module helper — the shape the two original offenders take after any extract-method;
• it false-positived on a module constant like _SERVER_STARTED_AT = int(time.time()), blaming whichever reader preceded it;
• and its docstring said “bounded at the next top-level statement” while the code bounded at the next def/class.

A fixture that never reached the reader

The activity test pointed tmp_path at a config and asserted scope_start_at. But resolve_log_path’s default is relative and resolves against the process CWD — verified, it resolves to <checkout>/logs/keel.log. So the config was decoration, the feed was empty, and the only assertion left was on a pure function of now_ts that no feed can influence. Making apply_scope filter on the wall clock while still echoing the injected boundary passed everything.

It owns its log now — a cycle either side of the boundary, an absolute logging.file — and asserts the cycle that survived, not the label.

Two smaller

The orders fixture gains a third row, one second before the boundary. The scope is a lower bound with no upper bound, so a clock shifted backwards only widens the window; with rows only at the boundary and two days out, now_ts - 86_400 changed nothing and escaped.

orders.scope_start_ts is pinned against a literal midnight. + 1 on its return passed the whole suite because _book_at places its boundary row by calling the same function — row and boundary moved together and the mutation cancelled itself out. A test that computes its expectation from the code under test cannot see that code move.

Verified

tests/web + tests/commands/test_activity.py + tests/commands/test_orders.py: 1115 passed. ruff check and mypy (458 files) clean.

No ruff format run this time — see #783, which is about the repo being 40% unformatted with no CI gate. The file happens to be format-clean anyway.

chore: one-shot ruff format across the tree, and gate it (#783) (#785)

Closes #783. Mechanical. No behaviour change, with one syntax change called out below.

ruff format was configured and clearly intended — ruff.toml sets its line-length and target-version and carries a careful note about a hazard someone reasoned through — but nothing ran it, and 197 of 496 files had drifted.

The cost wasn’t aesthetic: a contributor who ran the formatter on a file they touched reformatted regions they hadn’t, and those hunks landed in PRs whose bodies said “no behaviour change”. #780 shipped six of them and a reviewer had to read each to establish it meant nothing.

197 files reformatted, 299 left unchanged
+3427 / -1960

directory	files
tests/	112
keel/	55
docs/	17
packages/	10
scripts/	3

The gate

ruff format --check . in both ci.yml and release.yml. Both, because release.yml is dispatched against whatever main is at the time, which need not be the commit CI went green on — the same argument that file already makes for re-running mypy there.

Whole tree, where ruff check in the same workflows is scoped to keel tests packages. Lint has a debt in docs/ and scripts/; formatting no longer has one anywhere, and scoping the check would re-open the drift this pass closed. It’s its own step, so a formatting failure reads as one instead of being masked by a red lint on the same run.

⚠️ One change is not cosmetic

The pass rewrote 38 occurrences of except (OSError, OverflowError, ValueError): into PEP 758’s unparenthesised except OSError, OverflowError, ValueError:.

That is exactly what ruff.toml’s existing note predicted, and why that note is there: under the old >=3.11 floor the same rewrite emitted a SyntaxError on three interpreters the metadata invited. The floor is >=3.14 now — verified across all eight distributions, and pinned by tests/test_python_floor.py (test_every_distribution_declares_the_same_floor, test_ci_runs_the_suite_on_the_floor_so_it_stays_true). CI runs 3.14 only.

If you’d rather not carry that syntax, say so and I’ll add ruff format’s skip for it — but the floor makes it safe and the note in ruff.toml already anticipated this day.

Verified

The real risk in a mechanical reformat of this repo is its many source-scanning tests — inspect.getsource assertions, _code_only walks, exact-string pins. None broke:

• full suite: 6477 passed, 3 skipped
• ruff check keel tests packages clean
• mypy clean (458 files)

And the gate is checked rather than assumed: both workflows still parse as YAML, both carry the Format step, and ruff format --check . against a single deliberately misformatted line exits 1.

Reviewing this

Not with git diff --ignore-all-space — that was in the first draft of this body, it was never run, and it is wrong twice: it leaves 199 files and 3308 insertions (no useful reduction), and it hides the one change below that is not whitespace.

Instead, the reformat is proved neutral rather than eyeballed. All 197 files were AST-compared against main:

• 186 AST-identical, 0 unparseable
• the 38 except rewrites parse to a byte-identical AST — except (A, B): and except A, B: are the same tree, so that half is neutral by construction
• 11 files differ, all the same way: the formatter inserted a leading space into docstrings that begin with a quote (""""HALTED" → """ "HALTED"). That is a string value change, not whitespace.

Two of the 11 are in keel/ (_rail11_status, _render_tier_section) — both private helpers. No Click command’s help text starts with a quote (checked by AST across keel/), so no --help output moved.

Review follow-up

Five findings, all fixed in 0bcfd4f: the gate is now pinned by three tests (deleting it from either workflow, scoping it, or moving it after Stamp build info all go red), the count is corrected to 38, and CONTRIBUTING.md / the PR template / test_the_gates_a_pr_must_pass_are_stated all carry the new command.

feat(web): the Tier 1 gate’s security primitives, with no action wired (#781) (#786)

Stage 1 of #781. Builds the gate, wires nothing to a rail.

That ordering is deliberate: at no point should a half-built surface exist that can reach disengage_kill_switch. The invariant in keel/web/__init__.py — “not one of the nine capability-increasing actions is reachable from this package” — is still true after this PR, and its AST scan passes untouched.

⚠️ A correction to the brief, found before building

The specified guard was “refuse unless the request originated from 127.0.0.1”. That is necessary and not sufficient.

A Cloudflare Tunnel runs cloudflared on this machine and connects to keel over loopback. So a request that began on the public internet arrives with client_address of 127.0.0.1. A guard reading only the peer answers truthfully and uselessly — and would let whoever can reach the tunnel release a rail, which is the exact population #781 exists to keep out until #648 and #656 land.

gated_action_permitted therefore requires both:

condition	why
the peer is loopback	the socket’s remote address is the one thing in a request an attacker cannot choose
external_hosts is empty	this is how the module already spells “remote posture”

The second isn’t invented for this PR: session_expired_at turns a never-expiring session into a 30-day one on exactly that field, reasoning that a remote origin “changes the population to anyone who can reach the tunnel”. Same signal, same reason, one decision further along.

What’s here

is_loopback_peer reads the peer address, never a header. Host: and X-Forwarded-For: are claims the client writes, and this check exists for the case where the claim is a lie. (HostPolicy.permits reads the header and defends a different thing — DNS rebinding.)

It accepts the whole 127.0.0.0/8 block rather than one address — systemd-resolved answers on 127.0.0.53, and == "127.0.0.1" would refuse a local operator with a false refusal that reads as a broken button — plus ::1 and the IPv4-mapped ::ffff:127.0.0.1 that a dual-stack bind presents for a v4 client. It fails closed on anything it cannot parse.

The parameter is object, not Any, so mypy enforces the narrowing rather than waving it through: what arrives is BaseHTTPRequestHandler.client_address, which typeshed declares a 2-tuple and which is a 4-tuple on IPv6.

gates_token derives the write token for a gated action exactly as csrf_token derives the setup one, under a different label. That difference is the property: the setup token is written into /api/setup’s document, so anything that can read that page holds it — and one value covering both surfaces would make “can create a deployment” and “can release a halt” the same permission. Same secret, two derivations, neither usable as the other, each revocable alone.

This is the “separate token” call from the plan, done the way this codebase already does domain separation rather than by adding a second secret to manage.

Also

tests/web/test_server.py said “eight capability-increasing actions”; there are nine. The three keel/web/ sources say nine correctly and are pinned by test_the_disjointness_comments_state_the_actual_capability_count — which scans keel/web/ only, so it could not see the test’s own prose. Fixed here, since this is the machinery being extended.

Verified

tests/web + tests/test_capabilities.py: 900 passed. ruff, ruff format --check and mypy (458 files) clean. 13 new tests, each parametrised over the cases that matter — the loopback block, the IPv6 forms, the malformed peers, and the tunnel.

Stage 2

Wires the three brake-releases (resume, resume-entries, reset-hwm) behind this gate plus the typed-phrase modal, and the ungated one-click Halt. That stage is where keel/capabilities.py gains its second Gate and where the __init__.py invariant gets rewritten — deliberately, in the PR that earns it.

feat(web): the browser gate and its closed action table, still wired to nothing (#781) (#787)

Stage 2a of #781, on top of the merged #786 primitives.

keel/capabilities.py has said since it was written that “#436’s browser gate would be a second Gate here and a second value in Capability.gate — which is the point of writing the vocabulary down before there are two.” This is that second kind of evidence, as its one implementation, symmetrical to _require_interactive_confirmation being the one implementation of the first.

Nothing routes to it yet. The invariant in keel/web/__init__.py — not one of the nine capability-increasing actions is reachable from this package — is still true, and its AST scan still passes: TIER1_ACTIONS names resume, resume_entries and reset_hwm as strings, never imports or calls them. The dispatch that will call them belongs in server.py, so this module stays a declaration.

The table is closed, and the closure is the property

key	releases	phrase
resume	the kill-switch halt that stopped all trading	RESUME TRADING
resume-entries	rail 16’s consecutive-loss halt on new entries	CLEAR STREAK HALT
reset-hwm	rail 11’s drawdown veto, by re-seeding the high-water mark	RESET HIGH WATER MARK

The other six are refused here as firmly as they are refused to cron — and the tests name autonomy-on, record-flow, withdrawals-attest and update individually, asserting each is absent. Admitting one means deleting a test that states why it was out, rather than adding a line nobody reviews.

Why these three is written where the table is. All three release a brake a rail applied — deliberately not described as risk-reducing, since they increase what keel can do. What makes them Tier 1 is that the capability is bounded and instantly reversible: the rail that fired can fire again, and keel kill undoes all three with no ceremony, because stopping must never be slower than starting. The other six grant standing capability or move a baseline — record-flow rebases the drawdown high-water mark, which capabilities.py calls “the one direction a circuit breaker must not fail in”.

The phrase

Exactly, meant literally: not case-folded, not stripped, not prefix-matched. The operator reproduces one specific sentence, and every loosening turns a deliberate act into a plausible typo. Pinned: resume trading, a trailing space, and a truncation all fail.

Never the action’s own key, and no two share one — a phrase derivable from the URL is evidence of nothing, and a shared phrase would prove a human but not intent. compare_digest because it costs one call and removes the timing question (belt-and-braces; the modal prints the phrase).

phrase_matches fails closed on the key as well: an action absent from the table has no phrase, and “no phrase” must never read as “no phrase required” — which is what a lookup with an empty default would quietly mean.

One of the repo’s own pins caught me

The module’s first title line read “Tier 1 capability-increasing actions”, which test_the_disjointness_comments_state_the_actual_capability_count correctly read as a disjointness claim naming N=1 against nine. It scans every keel/web/ source for that sentence shape because the number “has drifted twice already”. Reworded to “three of the nine capability-increasing actions” — which states the truth and satisfies the pin for the right reason.

Verified

tests/web + tests/test_capabilities.py: 925 passed. ruff, ruff format --check and mypy (460 files) clean. 12 new tests.

What’s next

Stage 2b routes to this — the POST /api/gates/* gauntlet, the three call sites, the second Gate in keel/capabilities.py with three surface="web" rows carrying mirrors to the CLI originals, and the rewrite of both the __init__.py invariant and test_the_only_gate_today_is_the_tty_one. That test’s own docstring says it “is where that change announces itself — so adding one cannot be a quiet edit”, which is why it gets its own PR rather than riding along here.

Stage 3 draws the modal and the ungated one-click Halt.

fix(web): the safety invariant scanned command names, not effects (#788) (#789)

Closes #788. Standalone, off main. No production code changes — this is the guard, not the thing guarded. Nothing in #781 depends on it landing a particular way, but stage 2b should not be built on top of it as it was.

The gap

keel/web/__init__.py states the guarantee the whole package rests on:

“Not one of the nine capability-increasing actions is reachable from this package… The server cannot arm, release or spend.”

It did not assert that. The scan forbade this package from naming any Capability.function — and those are the CLI commands, Click callbacks taking a ctx that no web module would ever call. What releases a rail is the operation underneath:

gated action	scanned	does the work — not scanned
keel resume	keel.cli.resume	trading.disengage_kill_switch
keel resume-entries	keel.cli.resume_entries	trading.clear_consecutive_loss_halt
keel reset-hwm	keel.cli.reset_hwm	trading.reset_high_water_mark

Planting an ungated disengage_kill_switch(repo) into a web module passed the entire safety suite. The guarantee held because nobody had written the line, not because the test would have caught it.

What is asserted now

The effects, derived. For each of the nine, the functions its gated command actually calls, read out of the source — never a hand-written map. keel/capabilities.py exists because “a hand-written list would go stale”, and a table saying “keel resume really means disengage_kill_switch” would be that same list one level down. The derivation asserts it finds ≥6 operations, so it cannot go quietly empty.

And no database write at all. Four of the nine work through a generic repo.set_state(...) that no derivation can tell from any other write. So the third scan states the posture directly: this package calls none of the repository’s 28 writers. Measured — keel/web/ calls five Repository methods and all five are reads. That is also the more honest sentence: keel serve reads, and everything it can change goes through keel.commands.setup.ACTIONS, outside this package.

The original name scan is kept. It’s cheap, it still catches the obvious spelling, and deleting a check because a better one arrived is how the next gap opens.

Measured against the old one

Five real effects planted in keel/web/staticfiles.py:

planted	old scan	new
ungated disengage_kill_switch — the #788 proof	❌ missed	✅ caught
ungated clear_consecutive_loss_halt	❌ missed	✅ caught
ungated record_declared_flow	✅ caught	✅ caught
a raw repo.set_state(…) write	❌ missed	✅ caught
apply_scope_attest	❌ missed	✅ caught

test_the_effect_scan_can_fail proves the derivation and the scan can match — the same shape as the existing test_the_scan_for_capability_increasing_actions_can_fail, which proved the old scan could match a name, which is exactly the thing that turned out not to be enough.

keel/web/__init__.py now says what is checked rather than what was hoped.

Verified

tests/web + tests/test_capabilities.py: 916 passed. ruff, ruff format --check and mypy (458 files) clean.

After this

Stage 2b lands on a scanner that can see the three operations it routes to, so its assertion becomes the precise one: those three reachable only through the gated handler, the other six unreachable anywhere in keel/web/.

fix(web): drop reset-hwm to Tier 2, and bind every phrase to its own action (#790) (#791)

Closes #790. Eleven findings on the gate table merged in #787. Mutation score 11/20 → 17/17.

The Tier boundary argued against itself

reset_high_water_mark is four writes — it clears the mark, zeroes both drawdown scalars, and empties equity_history, the rolling window the weekly peak is computed from. record_declared_flow shifts the mark by a signed amount the operator states.

So Tier 1 admitted the action that erases the drawdown evidence while Tier 2 refused the one that adjusts it, on the stated grounds that the adjusting one “can, with the wrong sign, mask a real trading drawdown”.

Dropped to Tier 2. The alternative — keeping it and rewording the criterion — would have been fitting the rule to the answer. Tier 1 is resume and resume-entries.

Two related corrections went in with it:

• resume doesn’t release a brake a rail applied. guards.check reads get_state("kill_switch", default=True) — unset means engaged — so on a never-resumed deployment it moves a fail-closed default to permissive. It stays, because keel kill re-engages in one gesture, and that is what bounds it. The entry now says so.
• Stop must ship no later than release. The browser has no halt today. Stage 2b ships the ungated one-click halt in the same change as the first release route, not after it. Written into the module rather than left as a plan.

A phrase that released every action

Every test read the expected phrase back out of the table, so the suite was self-consistent under any content. A phrase_matches ignoring action_key and testing against every row passed all twelve — making any Tier 1 phrase a master key, which is the closure this module calls its safety property, defeated. Nothing pinned the literals either: RESUME TRADING → RESUME NOW shipped green, as did swapping two actions’ phrases.

Bound now, and asserted as a cross product: every phrase against every other action. Literals pinned. And no two phrases may share a first word — the near miss is an operator pattern-matching under stress, for whom a future RESUME ENTRIES beside RESUME TRADING would be genuinely confusable.

The same bug I had fixed one PR earlier

secrets.compare_digest raises TypeError on a non-ASCII str and on a non-str. I found and fixed exactly this in tokens_match during #786’s review, then wrote the same pattern here without the guard. The phrase comes off an operator’s keyboard through a JSON body, so a smart quote or a non-breaking space from a phone delivered the correct verdict — refuse — as a 500.

The rest

function named a click.Command. getattr(keel.cli, "resume")() would enter Click standalone mode, re-parse the server’s sys.argv, run the TTY gate with no terminal, and sys.exit inside a request thread. It’s operation now — the state service, module-qualified, pinned by literal and checked to resolve to something callable. Two actions may not reach one operation, which would release the kill-switch when the operator asked to clear a streak halt.

TIER1_ACTIONS is a MappingProxyType — a plain dict let any importer add autonomy-on in one line.

action/detail are imported from keel.commands.trading, not paraphrased. That module holds the wording so “neither re-words them”, and the drift was already visible: the CLI printed “Any real, unrecovered drawdown stops being visible to the rail” where this said “re-seeding the high-water mark”. A test asserts both strings are the module’s own.

All seven non-Tier-1 actions are named individually — scope-attest and posture-attest were missing, so either could have been added for free. And the module no longer describes wiring that doesn’t exist in the present tense.

Two tests that were theatre

The timing test grepped the source for compare_digest; a mutant replaced the call and left the word in a trailing comment. == and compare_digest return identical values for every input, so no black-box test can tell them apart — it reads the AST now and requires the returned value to be that call.

Writing it turned up the same class of bug in my own test: ast.walk is breadth-first, so returns[-1] is not the last return in the source. It passed by luck and failed the moment an import edit shifted the lines. Sorted by line number now, with every earlier return asserted to be a refusal constant.

Six of the twelve original tests were vacuous on an empty table. Every loop and count now asserts its own population first.

Verified

17/17 mutations killed. tests/web + tests/test_capabilities.py: 940 passed. ruff, ruff format --check and mypy (460 files) clean. Still nothing routes here — keel/web/__init__.py’s invariant is unchanged.

feat(web): the browser can release two halts, and stop from anywhere (#781) (#792)

Stage 2b of #781. POST /api/gates/* routes to the gate table, and the browser stops being read-only for the first time.

The gauntlet, and the order is the contract

A release must survive, in order:

_admitted	Host policy, session cookie, expiry
_sec_fetch_site_ok
X-Keel-Client	a header a plain HTML form cannot set
gated_action_permitted	loopback peer and loopback bind and no declared remote origin
gates_token	in a header of its own, derived apart from the setup token
the typed phrase	exact, checked last

Nothing opens a database until the phrase matches. The test that pins it points db_path at a path that does not exist and asserts a wrong phrase still returns rather than raising — the ordering asserted, not described. And no refusal echoes the phrase: a 403 quoting it would put a credential-shaped string into logs and into whatever an operator pastes while asking for help.

Stopping is never gated on locality

/api/gates/halt takes no phrase and no locality check. It needs the session and the gate token, because it is a write; nothing else, because an operator whose keel is behind a tunnel must be able to stop it from the tunnel. A stop refused for being remote is the one failure this surface must not have.

It ships in this change, not after it — a release route landing first would mean starting was available from a phone and stopping was not.

The second gate announces itself

keel/capabilities.py gains BROWSER beside TTY, and two web rows carrying mirrors to their CLI originals — the shape mirrors was kept for, “the moment a second front-end gates anything again”.

test_the_only_gate_today_is_the_tty_one said it “is where that change announces itself — so adding one cannot be a quiet edit”. It is test_the_gate_vocabulary_is_stated_and_bounded now: the assertion moved rather than being deleted, which is the point of having written it that way. Two new tests name which actions the second gate covers and require every browser row to mirror a TTY row.

Three invariant scans are scoped to TTY rows, because a web row’s function is the browser gate’s own implementation and necessarily lives in keel/web/ — forbidding it there would forbid the gate from existing. What the browser reaches is Tier1Action.operation, pinned from both sides by test_the_only_permitted_effects_are_the_ones_the_gate_table_names.

⚠️ One guard was invisible to its own tests

Deleting gated_action_permitted from the route passed the entire suite. Every routing test ran against a loopback server, so the check always passed and removing it changed nothing observable — the single most important guard in the feature, untested at the level it runs.

Fixed by testing the posture that makes it bite: a deployment with --external-host set refuses a release and says the action remains available at the terminal; the halt on that same deployment succeeds, pinning the asymmetry rather than leaving it to a docstring.

mutation	before	after
loopback check removed	❌ escaped	✅ killed
halt branch removed (halt 404s)	❌ escaped	✅ killed
gate token check removed	✅	✅
gate token swapped for the setup token	✅	✅
unknown key not refused	✅	✅
phrase not checked	✅	✅
database opened before the phrase	✅	✅
refusal echoes the phrase	✅	✅

8/8, from 5/8.

Verified

Full suite: 6557 passed, 3 skipped. ruff, ruff format --check and mypy (460 files) clean.

The MCP capabilities tool asserted a single gate; it now reports what the inventory declares, derived rather than spelled.

Reviewing this

This is the PR where a rail opens to a browser, so it deserves the same adversarial pass the four before it got. The places I would look hardest: whether _gated_action’s early returns can be reordered without a test noticing, whether the halt’s exemption from the locality check is exploitable on a tunnelled deployment beyond the DoS-in-the-safe-direction it is meant to be, and whether the TTY-scoping of the three scans widened anything I have not noticed.

Stage 3 draws the modal and the halt button.

feat(attestations): one model, three surfaces, and the four numbers that disagreed (#793) (#794)

Closes #793.

Live stopped placing orders on 2026-08-25 and nobody noticed for 17 days. The exposure caps were the primary cause, but rail 17 expired on 09-08 and stacked on top — and nothing anywhere said so until someone went looking in the veto log.

The model

keel/attestations.py answers, for every attestation keel has: what is it, when was it made, when does it expire, how long is left. It reads each rail’s own constant and restates none of them — rail 17 derives its expiry from executor.WITHDRAWAL_ATTESTATION_TTL_SEC at call time; rail 22 uses the due date stored at attest time, which has no default precisely so a reader cannot cover for a writer that forgot one.

doctor.TTL_SEC = 7 * 86_400 is deleted. Its comment read “Rail 17’s TTL is the executor’s constant; doctor only READS it” and it did not — it redeclared the number. Its ttl_sec= parameter goes with it; both callers used the default.

Three things the issue got wrong

Found by reading the code rather than the issue, and recorded on it:

1. Doctor already had a pre-expiry state. It has warned on rail 17 since it was written. What it did not have was agreement: doctor warned at _days(remaining) <= 2, which truncation makes anything under 72 hours, while the banner’s window is 48. Between the two an operator saw a doctor WARNING and a cockpit calling the same attestation healthy — the exact failure this issue exists to prevent, already shipped.

2. The warning window cannot be one global number. 48 hours is right for rail 17’s 7-day TTL and is no notice at all on rail 22’s 90-day one. Doctor knew that too — it warns rail 22 at ATTESTATION_TTL_SEC // 6 and its comment reasons about being “proportional to” a fixed TTL. The window is now a field on the attestation, and rail 22’s is read from that constant rather than becoming a second opinion about it.

3. Rail 17 reads two keys, and doctor read one. The rail vetoes on enabled is False with its own sentence (“withdrawals are suspended/restricted for this account”). attestation_findings, handed the timestamp alone, reported ok · withdrawal capability attested · 6 day(s) remain for an account whose broker had frozen withdrawals. keel status never had this bug — it resolves through the executor’s own _withdrawals_enabled. The model gains REFUSED, which is not an expiry and not an absence, and all three surfaces read it.

The three surfaces

keel doctor reads the model. Every number in its rail-17 sentence now moves when the executor’s TTL does.

The cockpit grows a sticky banner, carried by the envelope rather than by one endpoint’s data. Rail 17’s expiry was on screen for three days — in a card, below the fold, on one page of eleven. null (nothing was read) stays distinct from [] (someone looked and found all clear). The banner names the remedy, because rails 17 and 22 are attested from a TTY and #781 deliberately left them outside the browser gate.

attestation.expiring fires once per attestation per window. It fired on every cycle, which on this deployment means two rails, hourly, indefinitely; an alert that repeats until it is fixed stops being read on about the third day. A window is the state paired with the expiry, so the halt alerts again after the warning did, a renewal that lapses alerts again, and a rail never attested at all — rail 22, today — alerts once rather than forever.

That last one makes notify_after_cycle write, which its docstring said it never did. The departure is deliberate and documented: one state key that no rail, report or decision reads, and tests/test_notifications.py pins the write list as exactly that key.

Verification

Mutation, not coverage: 14 defects across the model, doctor, the payload, the envelope, the client and the ledger, each proven to reach disk before the suite ran.

Three survived the first pass and are worth naming:

survivor	why the test missed it
ledger replaces instead of merging	invisible until a third cycle reads the evicted entry — the test stopped at two
doctor keeps its own 7 * 86_400	the state came from the model, so the verdict was right; every number in the sentence was still wrong (“expired 0 day(s) ago” on a 3-day TTL)
a tick claiming all clear	the assertion existed — in a file my harness did not run

All three are now killed by tests that name the mutation they exist to reject. 6617 pass, mypy clean, ruff format clean.

Still open on #793

Stage 3 of #781 (the modal and the halt button) is unrelated and untouched. The Status page’s own withdrawal_attestation card is unchanged — it is now the least authoritative of the four surfaces, and folding it into the model is a follow-up rather than part of this.

chore(release): 0.15.0 — the browser can release two halts, and attestations warn before they bite (#795)

Version bump only — eight pyproject.toml files, their == pins, and uv.lock. No code changes.

Minor, not patch. Two features have landed since v0.14.1:

• #792 — the browser gets a real gate. Two Tier 1 halts (resume trading, clear the streak halt) can be released from the cockpit behind a typed phrase, loopback-only, and the kill switch can be engaged from anywhere. The safety invariant was rewritten in #789 to scan derived effects rather than command names, after the name scan passed on a dispatch it could not see.
• #794 — one model of every attestation, read by keel doctor, the cockpit banner and the attestation.expiring webhook. It also closed four places where a surface disagreed with the rail it reported on, including keel doctor reporting ok for an account whose broker had frozen withdrawals.

Also in the range: #785 (one-shot ruff format across the tree, now gated in CI), #780/#784 (every reader answers on the clock it was handed), #789/#791.

Release preconditions, checked locally

gate	result
uv lock --check	clean — the lockfile moved with the bump (#424)
keel/templates/config.live.yaml	mode: confirm
full suite	6633 passed, 3 skipped
mypy	clean, 464 files
ruff format --check	clean

After merge: Actions → Release → Run workflow, entering 0.15.0.

Built from 468a749d0430. Version binds to this hash: keel --version reports keel 0.14.1+468a749d0430 [release].

Install

Download all wheels from this release into one directory, then install the keel_trader wheel by path:

pip install --find-links . ./keel_trader-0.14.1-py3-none-any.whl
keel versions

keel versions — not keel --version — is the check: it reports every keel distribution in the venv and exits non-zero if a sibling was left behind at an older version, which --version cannot see. Upgrading an existing deployment: see “Deploying a new version” in the README.

⚠️ Never install by bare name. The distribution is keel-trader; the name keel on PyPI belongs to an unrelated project, so pip install keel fetches someone else’s package. A build reporting DIRTY or [checkout] is not this release and must not be run against live funds.

Configure

config.yaml is attached to this release: the production config, in auto_trade.mode: confirm — keel previews every order and waits for your approval. Drop it beside the install (or run keel init-config --live), put your CDP key in a git-ignored .env, then:

keel migrate     # existing database: apply schema migrations
keel init        # fresh deployment: write config + seed candidate rules

Seeded rules start as candidate and trade nothing until you promote them.

Other changes

docs(research): the Alpaca options venue reality, marked doc-only where it is (#636) (#753)

Discovery for #636. No code, no rail change, no config — one document under docs/research/.

It does not close #636, and says so first

#636 forbids deciding from documentation alone (#412’s lesson). This session holds no Alpaca credential, so everything here is documentation, and every finding carries a mark: [DOC] quoted from Alpaca, [DOC-GAP] unanswered, [KEEL] verified in this source tree, [ARITH] derived with the arithmetic shown.

The five findings that matter

F1 — the load-bearing question is undocumented. Alpaca offers no cash accounts (“All accounts are set up as margin accounts”); keel already handles that with the multiplier == 1 proxy via max_margin_multiplier. Whether options approval survives that setting is stated nowhere. If enabling options forces the multiplier above 1, verify_cash_account raises and the adapter stops building — options would be a destructive change to the equities trading that already ships.

F5 — rail 19 already refuses an OCC symbol, and says why. SPY250127C00608000 has no hyphen, so parse_spot_product_id returns None. The rail runs in every mode, both sides, DCA included — deliberately outside LIVE_STATE_RAILS, so paper cannot skip it: there is no rehearsal path. No config widens it, and the comment says “Spot-only is this agent’s CHARTER, not an operator preference.” Options aren’t blocked by a missing feature; they’re blocked by the rail that encodes the constitution. That sizes the amendment #637 is considering.

F3 — the venue disposes of inventory by itself. ITM contracts auto-exercise at $0.01, and where buying power is short, “Alpaca will sell-out the position within 1 hour before expiry.” F2 — assignment arrives by polling only: “Options assignments are not delivered through websocket events.” It is also the first inventory event with no originating keel order.

F6 — the fees are negligible, and that is the trap. Round trip ≈ $0.084/contract; a cash-secured put’s opening leg is 4.6 bp of premium. The real cost is the bid-ask spread, which no document states. Arguing this ADR from the fee schedule would repeat exactly the error 2026-09-05-restatement-restated.md corrected for crypto — where the flat 5bp floor turned out to be 52.3bp median and the verdict went to 0 of 240.

F7 — unexecutable today regardless. A cash-secured put is collateralised at strike × 100, unfractionalisable: $1,800 for the cheapest plausible underlying against config.live.yaml’s budget_usd: 50. ~36× the deployment’s clip — decidable with no jurisprudence at all.

One note on method

The fee table is read from the PDF directly (schedule revised 2026-09-01) because an automated extraction of that same file reported OCC at $0.65 against an actual $0.025. The doc-only hazard #636 warns about reproduced itself inside this pass, so it’s recorded in the document.

What’s left

Paper accounts get Level 3 automatically, so the mechanical half (F2’s activity records, F4’s multi-leg payload, real bid-ask on touchable strikes) is verifiable free and needs no options agreement. But paper grants Level 3 to everyone, so it can never answer F1 — that needs Alpaca support in writing, or a live application. The document marks which half is which.

fix(web): the nav may not say where you are until the rows agree (#754) (#757)

Closes #754.

show() set document.title and aria-current="page", then awaited the read. For the length of the fetch every sighted signal said “you are on Balances” over Positions’ rows — a stale figure under a fresh label, the one claim _session_banner refuses to make and the balances tiles carry an as-of stamp to prevent.

The claim waits for the DOM that backs it

commitNavigation is now the single place that says “you are here” — tab title and aria-current together — and paint calls it after rebuildInto, on all three branches. A stopped view and a refused view are outcomes of this navigation too; leaving the nav on the previous route while the content reports this one is the same mismatch in different clothes.

A click is still acknowledged, with a weaker claim

Deferring aria-current removes every immediate signal from a click, which on a slow route reads as a dead link and invites a second one. data-pending is that signal, and it is deliberately not aria-current: dotted rather than solid, muted rather than foreground. A pending link that looked like the current one would restore exactly the confusion the deferral removes.

No is_navigating flag, because one already exists

aria-busy is raised in exactly one place and always was — show, plus index.html’s initial value for the first paint. Neither the 15-second poll nor an SSE repaint raises it, so the visual hangs off it directly; a second flag would be a redundant statement of one fact. Pinned by counting the assignments rather than locating one.

Content dims rather than clears — clearing costs a layout jump and claims more than is true — and takes pointer-events: none, because acting on a figure about to be replaced is the failure mode of a dimmed view left live. The bar is indeterminate: the server sends one response, not a stream, and a percentage would be a claim about something nothing counts.

Two of my own tests were vacuous, and mutation is what found them

The first show() assertion failed against a correct implementation — the new comment explains that it no longer sets aria-current, and a raw substring scan cannot tell an explanation from an assignment. A test a docstring can break is one a docstring can satisfy.

Worse: the CSS assertion was "aria-busy" in _CSS, which survived renaming the selector to #content[data-nope="true"], because the comment above the rule still said the word. Both scans now strip comments first and assert the selector.

Four mutants killed — commit-before-swap, renamed busy selector, dropped pending rule, removed keyframes.

Reduced motion needed no new rule

The blanket query — written before there was any animation to honour — already covers keel-busy, flattening it to a static bar rather than removing the signal. Its comment claimed the file had no animation; updated to say what it now does.

Checks

769 passed (tests/web/ + test_console_thinness.py), ruff clean.

Unchanged and listed in the module docstring: no test here proves the dim is perceptible, that a pending link reads as pending, or that any browser honours the query. Those are hand checks against a running keel serve.

feat(web): the deployment card — the badge’s tooltip, reachable without a pointer (#755) (#758)

Closes #755.

modeBadge writes the identifying --db/--config pair into a title, and title is a hover tooltip. There is no hover on a phone — the device #648/#656 exist for — so the half of the badge that actually identifies a deployment was unreachable exactly where the terminal is least available.

The mode word identifies nothing on its own: two paper deployments both say paper, and a live sandbox and a paper-equities profile can both say confirm.

┌──────────────────────────────────────────────┐
│  deployment   keel-live                      │
│  mode         confirm                        │
│  config       config.live-sandbox.yaml       │
│  database     keel-live.db                   │
│  origin       http://127.0.0.1:8765          │
│  ──────────────────────────────────────────  │
│  Mode and profile switching are terminal     │
│  ceremonies with a runbook. This console     │
│  reports the deployment it was pointed at    │
│  and cannot change it.                       │
└──────────────────────────────────────────────┘

A native disclosure, which is what makes it safe

The badge is now the <summary> of a <details> — keyboard-operable, touch-operable and announced, with no handler to bind and no button to build. That is what lets deploymentCard join sessionChip and paperBanner in test_neither_the_chip_nor_the_banner_builds_anything_clickable rather than be exempted from it. venueCard already uses the element the same way.

That matters more than convenience: this is the surface where a reader looks for the control, which makes it the likeliest place for one to appear later. A “switch to live” affordance arriving through a door marked accessibility is still the growth funnel the chip’s docstring refuses.

The card says so in words too, and the test pins the sentence’s content — refusing four invitation wordings — because a reference-only assertion would pass over a note reworded into a CTA.

Tags changed, layout did not

<span class="right"> and <span id="session-chip"> are <div>s now: <details> is flow content and a <span> may hold only phrasing content. Both already set their own display: inline-flex, so nothing moves. The popover is positioned out of flow — opening it must not reflow the header, which on a narrow screen would push the nav under the reader’s finger mid-tap.

title is kept, per the issue: it works for keyboard and pointer and costs nothing.

Two existing scans caught me

• SWITCHING_NOTE was spelled with +, which test_render_contains_no_arithmetic forbids in render.js — concatenation is .concat throughout that file so the derivation-free scan can stay simple.
• The header test pins the badge’s tag, so <summary> failed it. Updated with the reason: what it protects — the badge exists carrying that id and both classes, which modeBadge and header .mode:empty key on — is unchanged.

Registered in _CONFIG_READERS in the same commit that adds it, which is the rule that table states.

Checks

6,319 passed / 3 skipped, ruff clean. Three mutants killed: card built but never mounted, refusal reworded as an invitation, db path dropped.

Not proven here: that the popover is legible on a real phone, or that a tap opens it. Hand checks against a running keel serve.

feat(cli): keel open — the way back into a console nobody watched start (#756) (#759)

Step 3 of #756. Step 4 — the four com.keel.serve.*.plist files — is unusable without it, which is why it comes first.

$ keel open --port 8765
Opening the keel console at:

    http://127.0.0.1:8765/?token=ab12...

This address carries the running server's session token. Stopping keel revokes it.

⚠️ This writes a session token to disk. Read this part.

security.py layer 3 rests on the token being ephemeral, and serve prints the claim every run: “the token is new every run and is never written to disk.” A lockfile makes that sentence false. So it is written under exactly one condition:

The record exists only when the URL is not being shown to a human.

sys.stdout.isatty() decides.

• Attached to a terminal — nothing is written, the posture is byte-for-byte what it was, and the sentence is still printed because it is still true.
• Detached (launchd, a pipe) — a different sentence is printed, naming the file, its mode and keel open. Telling an operator their live credential is not on disk while writing it there is the class of false safety assurance _session_banner exists to refuse.

The argument is not that persisting a token is fine. It is that on the detached path the token is already in StandardOutPath at the daemon’s umask. The real choice is between that log line and a 0600 file in a 0700 directory, deleted on shutdown and checked for staleness before it is offered. The second is strictly less exposure, and it is the only one that makes unattended serve usable.

security.py layer 3 now says which of the two runs it is describing.

If you’d rather have uniform behaviour — always write, or never write and drop keel open — that is a one-line change and I’d rather you made it deliberately than inherited mine.

The file is a hint, never the authority

forget covers the clean stop; a SIGKILL or power cut does not. live_record re-checks the pid with signal 0 before offering anything — handing over a URL that refuses the browser reads as keel being broken rather than stopped. pid <= 0 is refused before the call, because os.kill(0, 0) signals the process group and would report a bad record as live.

Written through a temporary and renamed, so no reader sees a half-written record. Corrupt JSON reads as absent rather than raising. One file per port — #756 counts four deployments, and one shared file would make the last server to start the only reachable one. The token is never in the filename: a listing is readable by anything that can list the directory, even when the file is not.

Three absences, three sentences

No server, a server started from a terminal, and a server that was killed look identical from here. "not found" would send an operator hunting for a bug in the two cases where nothing is wrong, so each gets its own message — and the interactive one names the terminal that has the URL.

Checks

6,352 passed / 3 skipped, ruff and mypy clean. Four mutants killed: record written while a human watches, record never forgotten, liveness check skipped, file at 0644.

Not covered here: that launchd actually produces a non-tty stdout on your machine. That is step 4’s first observation.

feat(ops): four console daemons, one per profile, surviving reboot and crash (#756) (#760)

Step 4 of #756, and the last piece of the request. Only usable because #759 shipped keel open first.

profile	plist	port	config + database
supervised-live	com.keel.serve.live	8765	config.live-sandbox.yaml + keel-live.db
paper-forward	com.keel.serve.paperforward	8766	config.paperforward.yaml + keel.db
paper-hourly	com.keel.serve.paper-hourly	8767	config.paper-hourly.yaml + keel-paperhourly.db
paper-equities	com.keel.serve.paper-equities	8768	config.paper-equities.yaml + keel-equities.db

cd ~/keel
for job in live paperforward paper-hourly paper-equities; do
  cp "com.keel.serve.$job.plist" ~/Library/LaunchAgents/
  launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/"com.keel.serve.$job.plist"
done
cd ~/keel && ./.venv/bin/keel open --port 8765

The decisions worth reviewing

Ports are pinned, and that is not cosmetic. Unpinned, all four ask for 8765 and three die on a bind error — which from outside looks like a missing console rather than a clash. Asserted per file and across the table, because a collision is invisible to a per-file check.

Every daemon goes through its wrapper, never keel directly. --db defaults to keel.db, so a plist spelling its own arguments could serve the paper ledger under the live profile’s name, convincingly. The wrappers pin config to database as a pair.

RunAtLoad and KeepAlive are two promises. Reboot and crash are different failures. A file carrying only the first is the shape that looks right until something dies at 3am. The cost is stated in the plists rather than discovered: a server that cannot bind exits non-zero at once and launchd retries forever on its throttle.

Separate jobs from the four detector agents, deliberately — a console that crashed must not take the trading agent with it, and an agent mid-cycle must not restart because a browser tab died.

Two things that bit me

The double hyphen, exactly where its own note says it will. XML forbids -- inside a comment. My first draft documented the port and database options by name in the prose and all four files failed to parse. That is the hazard com.keel.live.plist’s style note already records.

My own test tripped on prose, in reverse. test_no_plist_carries_a_token forbade the substring "token" and failed on the plists’ own explanation of what the session token is. It asserts over parsed values now: no EnvironmentVariables at all, and no string shaped like a 32-byte secret.

The runbook was making a claim that is no longer true

“The token is never written to disk” held until #756 made it conditional, and test_the_section_documents_the_one_time_token pinned that exact sentence. Both now draw the distinction. A runbook promising an operator their live credential is nowhere on disk, while a file holds it, is worse than one that says which run is which.

Checks

6,394 passed / 3 skipped, ruff clean. Four mutants killed: shared port, KeepAlive removed, wrong wrapper, browser launch left on.

Not proven here, and it is the assumption everything rests on: that a launchd-started process gets a stdout that is not a tty. That is one observation against a real daemon, and it is the first thing to check after installing these — if it were false, the daemons would run but keel open would find no record.

chore(cli): one name for one idea — —no-browser on serve and open alike (#761)

Finding 2 from the #760 review, decided: --no-browser on both commands.

keel open --no-open is a sentence that argues with itself, and --no-browser is what every comparable local daemon already uses (jupyter notebook, tensorboard) — so it’s the one an operator guesses correctly without reading anything.

The old spelling still parses, and is no longer advertised

--open/--no-open survives as a hidden alias on serve. Not politeness: the four com.keel.serve.*.plist files shipped with --no-open in them and one may already sit in ~/Library/LaunchAgents. Under KeepAlive, an unknown option is not an error message anybody reads — it is a crash loop retried every ten seconds forever. The plists in this repo move to --no-browser; an installed copy keeps working either way.

default=None on the alias, so “not given” is distinguishable from “given as false”. With default=False it would silently override the real flag on every invocation that omitted it — that’s the first mutant below, and it passes every structural test in the file.

keel open does not gain the alias. Nothing ever shipped that spelling there, so there’s no script to keep working, and adding it for symmetry would preserve the contradiction this removes.

The structural tests prove the names and nothing else

Five of them read the commands’ declared options — that says the flags exist and nothing about what they do. A --no-browser that parsed and then opened a browser anyway passes all five, and on a launchd daemon at boot that is a window nobody asked for on a machine that may have no GUI session.

So the sixth runs both spellings through the real command and asserts no launch, then asserts the default still launches — otherwise the first two assertions are vacuous.

One existing call site in test_serve_command.py keeps --no-open deliberately and now says so: it exercises the alias end to end from a test that wasn’t written for it, which is the cheapest regression cover there is.

Checks

6,402 passed / 3 skipped, ruff and mypy clean. Three mutants killed, each verified to have actually applied first: alias overriding unconditionally, --no-browser parsed and ignored, alias removed outright.

docs(ops): the install block copied from the wrong directory, and skipped a wrapper (#762)

Reported from a real install of #760’s daemons: four cp: No such file or directory, then four Bootstrap failed: 5: Input/output error.

It told the operator to copy files from where they are not

The block opened cd ~/keel and copied the plists from there. These files are authored in the dev repo and deployed by copying, exactly as keel-live’s own header says of itself — so on a deployment that has not already been through this, which is every deployment the first time, there is nothing to copy.

And keel-equities had never been deployed at all

The equities detector runs paper-equities-run.sh, so nothing needed that wrapper until the console plist pointed at it. ~/keel had keel-live, keel-paper and keel-paperhourly — not the fourth. A plist naming an absent program is a KeepAlive crash loop, not a message anybody reads.

test_each_serves_its_own_deployment_through_its_own_wrapper asserts the wrapper exists in this repository, which it always does — the wrappers are authored here. Whether it exists in ~/keel is what matters at runtime, and no test can look: the deployment is outside the repo and differs per machine. What is checkable is that the documented install step copies each one, so that is what the new test asserts.

Also added: free the ports first. An interactive keel serve already on 8765 is precisely the bind failure the plists’ own comments describe, and it was the state of the machine that hit this.

Three wrong tests before a right one, all the same shape

1. The block locator matched launchctl bootstrap — and found the detector install block earlier in the file.
2. Anchored on com.keel.serve instead, it matched two blocks: the install and the bootout. Both anchors together select one.
3. Then the wrapper assertion survived deleting keel-equities from the loop, because the block’s own comment explains why that wrapper matters and the scan could not tell prose from a command. It strips # comments now.

That is the third instance this session of a scan answered by its own explanation, and the third found only by mutation.

Checks

6,412 passed / 3 skipped, ruff clean. Two mutants killed: the wrapper dropped from the loop, and the block returned to copying from the deployment.

fix(cli): keel open says WHERE it looked, because that was the missing fact (#763)

Found by an install that worked. Four console daemons bootstrapped, three wrote their records, and keel open --port 8765 answered “no recorded keel server” — so a success read as a failure.

The command had been run from a source checkout, which is itself a deployment root (is_deployment_root is deliberately generous, and the tree has a keel.db and a config.yaml). So it searched the checkout’s run/ while the servers wrote to ~/keel/run/.

The message listed three explanations and the true one was not among them. It could not be — it never said where it had looked.

After

Error: no recorded keel server on port 8765.

  Looked in /Users/…/CodeGate/keel/.claude/worktrees/open-says-where/run, which is the
  deployment this directory belongs to. If your server is a different deployment, run this
  from ITS directory -- `keel open` takes the same bare-invocation path as everything else,
  so a source checkout resolves to the checkout.

  If one is running here, it was started from a terminal …

keel open takes no --db and no --config, so nothing in its signature hints that the answer depends on the working directory. The path is the hint, and --help now says so in one line.

The stale-record branch gets it too — a crashed server and a wrong directory are different problems, and an operator staring at either needs the same fact to tell them apart.

Checks

6,413 passed / 3 skipped, ruff and mypy clean. Three mutants killed: the path dropped from each refusal branch, and the help line removed. Verified by running the command from the wrong tree and reading what it prints.

One thing worth recording for #756

launchd does give keel serve a stdout that is not a tty. Three daemons, three records written. That was the single assumption the whole keel open design rests on and that nothing in CI could test.

docs(decisions): draft ADR 0005 — options, with the verdict line unsigned (#637) (#764)

Drafts #637’s record. The verdict line is unsigned — signing is striking one option, keeping the other, and setting Status. Nothing else needs editing.

#637’s sequencing is satisfied: #370 landed the equities path, and #636’s discovery closed with its findings in #753. The record is due.

Why I didn’t write the verdict

An ADR is a standing rule, and this one turns on whether a cash-secured option is admissible — gharar, the character of the premium, whether full collateralisation changes the contract. Constitution line 5 (“every attestation is human-sourced, or refused”) means no amount of documentation reading settles that, and a machine drafting the verdict would be the exact failure that line names.

The record says so in its own section rather than leaving the omission to be noticed.

Three findings decide the near term without reaching that question

Which is why option A is drafted as “not now, on operational grounds, question expressly not reached” — so signing it commits the project to no jurisprudential position it hasn’t taken.

• F7 — the capital floor. A cash-secured put is collateralised at strike × 100, unfractionalisable: $1,800 for the cheapest plausible underlying against config.live.yaml’s budget_usd: 50. ~36× the deployment’s clip — no compliant position is executable at this size, whatever anyone concludes about permissibility.
• F5 — rail 19 is the charter. It vetoes an OCC symbol in every mode including paper, deliberately outside LIVE_STATE_RAILS, so there is no rehearsal path. Its own comment: “Spot-only is this agent’s CHARTER, not an operator preference.”
• F1 — the venue posture is undocumented, and the downside is asymmetric. Whether options approval survives max_margin_multiplier: 1 is stated nowhere. If it doesn’t, verify_cash_account stops the adapter building — breaking the equities path that already ships.

F3 is flagged as deserving argument rather than triage: the venue auto-exercises, liquidates within an hour of expiry when buying power is short, and reports assignment by polling only. That’s a different relationship to inventory than keel has accepted anywhere.

Reopening triggers

Four, in ADR 0002’s style, each a fact rather than a feeling. 1–3 are necessary together — deployment size, F1 answered on a live account (where a “no” closes it permanently, not provisionally), and the permissibility question answered by a human with sources.

Checks

Every citation verified against this tree — adapter.py:262, guards.py:905, config.live.yaml:82, and the research document. A script asserts every relative link in the record resolves: an ADR citing a path that moved is worse than one citing nothing, because it reads as verified.

6,424 passed / 3 skipped.

docs(decisions): sign ADR 0005 — keel does not trade options (#637) (#765)

Closes #637. The maintainer signed Option A; Status: decided.

What was decided, and what deliberately was not

keel does not trade options. Rail 19, the cash rail and the screen are unamended. The refusal rests on operational grounds — unexecutable at this deployment’s size (F7), no rehearsal path because rail 19 runs in paper too (F5), and a venue posture that may be incompatible and would take the working equities path with it (F1).

The permissibility question is expressly not reached, and Consequences now says so in the strongest terms available:

These are reasons that would hold for a non-Muslim operator running keel on the same account. Anyone citing this record as keel’s jurisprudential answer on options is citing it wrongly — trigger 3 is what would produce that answer.

Both alternatives stay in the record

Option B is not deleted. A decision record showing only the chosen branch records an outcome, not a decision — the reader two years from now needs to see what was weighed. The Decision section names B explicitly as the road not taken.

Two formatting faults caught while signing

• The signed title wrapped onto a second line, which markdown renders as an H1 plus a stray paragraph
• “What this record refuses to do” pointed at “Option A below” — a label that stopped existing the moment the verdict replaced the two branches

Both would have shipped as small lies about the document’s own shape.

Checks

A script asserts every relative link resolves and that all three options remain recorded. 6,424 passed / 3 skipped.

docs: stop offering a console deleted at #541, and pin the rule (#766)

keel tui went at #541 with ~10k lines of curses. The docs kept sending operators to it, in the present tense, for months. Five stale claims, and one of them was doubly false.

File	Was
README.md	“the browser view and the TUI answer” — listed as a current way to read keel
docs/glossary.md	“the TUI’s Help menu renders this file directly”
docs/mcp-server.md	two present-tense references
docs/operator-runbook.md:215	“the Account menu’s update entry in the TUI console (see ‘The TUI console’ for the ceremony)”

The glossary was wrong twice over. The Help menu went at #541 and render_glossary went at #540 — so the file’s entire claim to authority (“defined HERE and nowhere else, because something renders it”) had been hollow for two releases. It now says what’s true: since #539 a term becomes an outbound link to the published copy, built from TERMS in web/static/js/docs.js — so a term added here isn’t linked until it’s added there too.

The runbook line was worse than stale: it cross-referenced a section “The TUI console” that doesn’t exist, telling an operator to use a menu that doesn’t exist. keel update has one front-end now; it had two until #541. (The browser’s “A newer build is ready” button reloads the service worker — it does not replace the binary.)

None of this was catchable. Every statement was prose, and prose has no compiler.

The rule permits the history

A retired surface may be named, provided the paragraph naming it cites the issue that retired it. Mention it, date it.

A repo that scrubbed its own deletions would be worse off than one carrying a stale line — keel update really did have two front-ends, and the runbook explaining why it now has one is doing its job. So all six remaining mentions stay; each is now dated.

Per paragraph, not per line

The first cut required the line naming the surface to cite the issue, and failed on a sentence whose wrap put ​`keel tui`, a command that no longer exists two lines below its own “Until #541”.

Prose wraps at 100 characters here, so a line boundary carries no meaning and a rule keyed to one is a rule about the reflow — the same trap that broke a runbook block locator earlier in this series when its introducing sentence was reworded. A paragraph is the unit a reader takes the claim from.

The scan also asserts its own glob still matches the four documents it names; a glob matching nothing would pass over any wording at all.

Checks

6,426 passed / 3 skipped, ruff clean. Two mutants killed: the README offering the TUI again, and the doc glob going blind.

docs(readme): drop an ordinal that counted the deleted console (#767)

Follow-up to #766. The review finding on that PR was pushed to its branch after it merged, so it never reached main — #766 merged at 761a04d, the fix was b74bdcc. This carries it over unchanged.

The finding

README.md said “There is also a fourth way to read all of this: keel mcp…”.

git log -S "fourth way to read" puts that phrase at #600, in the same sentence as “the browser view and the TUI answer” — so the TUI was one of the three it counted from. The count has been wrong since #541 deleted the command, and #766 removing and the TUI from the next clause took away the last visible trace of what it referred to.

That left a reader an ordinal with no recoverable referent — worse than before, in exactly the way #766 was about.

Dropped, not renumbered

“Third” would rot the same way the moment a surface is added or retired, and nothing in the README enumerates the set, so no number in that position can be checked by the person reading it. The sentence now just introduces keel mcp.

Also carried over

RETIRED entries must be distinctive tokens, as a note in tests/test_retired_surfaces.py. The match is \b<surface>\b over whole documents — safe for tui, useless for something like api, which would fire on every page and lead the next author to loosen the rule rather than fix a document. The note says to match the command form (keel <name>) when the name is common.

Checks

README.ar.md carries no equivalent claim, and no other a <ordinal> way survives in the README. 6,426 passed / 3 skipped, ruff clean.

docs(presentations): a walkthrough for senior engineers, structured a… (#768)

…s one order’s journey

Two files. se.md is the deck: stack, ports-and-adapters topology, the three invariants (fail-closed, ruling-as-data, Decimal-only), and a source walkthrough that follows a single hypothetical BUY through seven files in the order the code touches them — a narrative rather than a file tour. se-speaker-notes.md is the presenter’s copy: per-section timing, a marked 25-minute cut, which files to have open, and the questions this audience actually asks, with answers.

Two things are on the slides rather than hidden in the notes, because a senior room finds them anyway and claiming otherwise costs the whole talk: the broker-port migration is unfinished (_common.py still constructs CoinbaseClient directly, so the live path cannot reach another adapter), and commands/ is 23,188 lines — larger than the engine it drives. Both are also in the open-problems section, which is the point of presenting to engineers at all.

Testing leads with the failure rather than the counts: two defects produced plausible, internally consistent, wrong output for the life of the project while 2,712 tests passed. Figures used are the verifiable ones (766 test functions across 41 top-level files) rather than a round number that cannot be sourced.

Claude-Session: https://claude.ai/code/session_01NyeggYtojNXCTHeD3JHxb6

What & why

Tests-first evidence

• Tests written first, seen failing for the right reason

Gates (all must pass)

• uv run ruff check clean
• uv run mypy clean
• uv run pytest -q green

Scope check

• This PR touches a rail or a default classification — checked means it DOES; leave checked only if true, and if so: cite the source and open the discussion BEFORE review (CONTRIBUTING.md, “Governance: rulings vs. machinery”).
• New dependency added (needs discussion first)

docs(readme): the map omitted three documents the website publishes (#769)

The Documentation map lists nine documents. engine-docs.manifest.json in keeltrading.com mirrors nineteen — and three of the gaps are what a reader arriving at the repository would want most.

Added	Why it matters
docs/decisions/	Five standing rules, each naming what would reopen it — including 0005, signed this week, which refuses options on operational grounds and states that the permissibility question is not reached. The site publishes 0001–0004 as its own decisions section; the README mentioned none of them.
docs/architecture.md	The site’s own summary calls it “the system as verified, not as imagined”. Unlinked here.
docs/glossary.md	The single source for the vocabulary — and the file whose authority rests on being linked rather than restated, so a README that doesn’t link it is part of the problem it names.

The README was strictly less complete than the site built from it, which is the wrong way round: the repository is the source, the site is the mirror.

A check, not just an edit

Every docs/... target the map names is asserted to exist. A map is worth less than nothing when it points at something that moved — it reads as verified.

Checks

6,426 passed / 3 skipped, ruff clean.

docs(readme): the mark, centred, above the title — in both languages (#770)

<p align="center">
  <img src="keel/web/static/icons/keel.svg" alt="keel" width="96" height="96">
</p>

The same 743-byte vector the app ships as its icon — so the README and the running console show one mark, not two that could drift.

Why the SVG and not the PNG

It carries its own background — a teal #0c5d52 rounded square with off-white strokes — so it renders on GitHub’s light theme and its dark theme alike. A mark relying on the page behind it would vanish on one of them, which is the exact failure index.html already records for the favicon: that file is a fixed raster of the light theme, and the header inlines the geometry instead so it can wear each theme’s own colours.

Why a relative path is safe here

pyproject.toml sets readme = "README.md", so the file becomes wheel metadata — and relative image paths break wherever that metadata is rendered. I checked before choosing: release.yml publishes wheels to the GitHub Release only, with no PyPI upload step anywhere, so nothing renders this README off GitHub.

An absolute raw.githubusercontent URL would have pinned a branch name into a file that outlives branches, for no benefit.

Both READMEs

README.ar.md gets it too — one of the two isn’t “the readme”. Placed before its <div dir="rtl"> rather than inside: a centred mark is direction-neutral, and keeping it outside means the RTL context begins exactly where the Arabic text does.

Checks

Asserts the referenced file exists, the alt text is non-empty, and the mark has a <rect … fill=> of its own. 6,426 passed / 3 skipped.

docs(readme): the architecture diagram was missing two venues, and three other claims (#771)

You spotted Alpaca missing. Checking the rest of that block found three more wrong claims in the same eighteen lines.

Claim	Reality
keel-broker-alpaca absent	Shipped — and docs/RELEASING.md puts it in the production install set: a deployment installs five wheels and that is one of them
keel-broker-kraken absent	Shipped (port-complete stub, #313)
~3,000 tests	The suite passed 6,000 some time ago
keel/ tree omits web/, mcp/, research/	The README’s own opening paragraph advertises keel mcp and the browser console; the diagram underneath showed neither

The test count is now absent rather than approximate

~3,000 was wrong by more than double. A count in prose is a promise the suite breaks every time it grows — the honest options were an untested number or no number, and no number cannot be wrong.

And I changed a correct number to a wrong one

The block said “the 21 rails”. I made it 22, taking the highest rail number in guards.py. tests/execution/test_rail_count.py failed, and was right to: rail 15 was retired, so the rails number up to 22 and there are twenty-one. Restored to 21.

That test already derives the count from guards.check and searches every English and numeric spelling repo-wide — it exists because this exact drift happened three times. My first cut of the new file added a second rail check that disagreed with it, which is precisely how a number goes wrong: two sources of truth for one fact. Removed; that test keeps sole ownership.

What the new file checks — the part nothing owned

• every directory under packages/ appears in the diagram
• no package is named that doesn’t exist
• no hardcoded test count creeps back

Four mutants killed, including dropping alpaca — the bug as reported.

Checks

6,429 passed / 3 skipped, ruff clean.

chore(release): 0.14.1 — keel open, four console daemons, and a signed ADR (#772)

Version bump only. Sixteen PRs since 0.14.0.

⚠️ One decision to make before merging: is this a patch?

This release contains three feat: commits, one of them a brand-new command (keel open, #759) plus four launchd daemons (#760). Under conventional semver that is a minor bump — 0.15.0 — not a patch.

docs/RELEASING.md states no versioning policy beyond “the input must be semver”, so I used the number you asked for. Changing it is one line here plus the workflow input, and it is far cheaper to change now than after the tag exists.

No schema migration this time

SCHEMA_VERSION is 20 at v0.14.0 and 20 now. Unlike 0.14.0 — which carried four steps and led with that fact — an upgrade here needs no keel migrate. Said explicitly because the previous notes made the opposite warning prominent, and silence would read as an omission rather than an absence.

What an operator gets

keel open — the way back into a console nobody watched start. A detached keel serve records its address in <deployment>/run/serve-<port>.json at mode 0600, deleted on shutdown; an interactive one still records nothing, so the posture security.py describes is unchanged wherever a human can read the URL.

Four com.keel.serve.*.plist daemons, one per profile on 8765–8768, RunAtLoad + KeepAlive — observed on the deployment surviving kill -9, with the record atomically replaced and a fresh token handed back.

--no-browser on both commands (#761), with --open/--no-open kept as a hidden alias — the shipped plists carry it, and under KeepAlive an unknown option is a crash loop rather than a message anyone reads.

Two console bugs found by running v0.14.0 rather than testing it: navigation showed the previous view’s figures under the new view’s label (#754), and the deployment identity was a hover tooltip — unreachable on the phone Phase B is built for (#755). Plus keel mcp’s doctor raising on an un-migrated database (#751).

And one decision

ADR 0005 is signed: keel does not trade options, refused on operational grounds, permissibility question expressly not reached. This release is what publishes it — keeltrading.com’s manifest resolves latest-release, so the record cannot be mirrored until a tag contains it.

Checks

All eight editable entries in uv.lock at 0.14.1; uv lock --check clean (release.yml runs it first). 6,430 passed / 3 skipped, ruff and mypy clean.

After merge: Actions → Release → Run workflow, entering 0.14.1 (or whatever number you settle on above), and choosing the desktop input.