loki-mode 11.3.0 → 11.3.1

package/docs/SONNET5-DEFAULT-PLAN.md

@@ -1,157 +0,0 @@
-# Sonnet 5 Default - Implementation Plan
-
-Status: SHIPPED (v7.104.0; kept as design history). Worktree: `../loki-sonnet5-wt` (branch `feat/sonnet5-default`).
-Board decision: `strategy/roadmap/13-BOARD-2026-06-30.md`. Verified facts: `reference-sonnet5-model-ids` memory.
-Release class: MINOR (new default execution model for every user). Full local-ci + council 3/3 + release ladder.
-
-## 1. Goal (founder directive, 2026-06-30)
-
-Make Sonnet 5 the DEFAULT execution model for Loki runs. Advisor stays Opus (opt-in / when needed).
-User can set all tiers to haiku|sonnet|opus from the dashboard at start, and hot-switch mid-run without
-interrupting executions. Protect the "never lies about done" trust moat: the switch must NOT weaken the
-verdict.
-
-## 2. Ground truth (verified against source 2026-06-30)
-
-- Live model resolver: `resolve_model_for_tier()` (providers/claude.sh:390) reads
-  `PROVIDER_MODEL_{PLANNING,DEVELOPMENT,FAST}` (claude.sh:65-67) which chain from `CLAUDE_DEFAULT_*`
-  (claude.sh:55-57). Today: PLANNING=opus, DEVELOPMENT=opus (comment "was sonnet"), FAST=sonnet.
-- `get_provider_tier_param` case block (run.sh:~2447) with hardcoded `development) echo opus` is the
-  INERT legacy fallback, reachable only when claude.sh is unsourced (guard run.sh:2414). Flip anyway
-  for consistency.
-- Trust-gate code-review reviewers: `_dispatch_reviewer()` (run.sh:~10148) sets
-  `_rv_argv=("--dangerously-skip-permissions")` and deliberately passes NO `--model` -> reviewers run
-  on the ACCOUNT DEFAULT model = non-deterministic, config-dependent. The in-code comment (run.sh:~10164)
-  explicitly says a future `--model` here "must be pinned to opus, never fable" (Fable refuses cyber
-  content, ends -p turn with stop_reason refusal). Bun route mirrors this: quality_gates.ts:28 + :1223.
-- Hot-switch mid-run EXISTS: `.loki/state/model-override` read each iteration (run.sh:16007-16070),
-  written by dashboard `POST /api/session/model` (server.py:2852), allowlist haiku|sonnet|opus|fable,
-  clamped by `loki_apply_max_tier_clamp` (claude.sh:347). Fresh `claude -p` per iteration = clean switch.
-- Sonnet 5 = alias `claude-sonnet-5` (CLI resolves aliases to latest; loki passes alias verbatim at
-  claude.sh:334). Opus 4.8 = `claude-opus-4-8`. Pricing (server.py:6174, run.sh:4847/12153): sonnet
-  $3/$15, opus $5/$25, haiku $1/$5, fable $10/$50 - all correct. model_catalog.json has stale IDs
-  opus-4-7, sonnet-4-6.
-- Parity-locked: `tests/test-model-override.sh` + dashboard estimator (`_clamp_to_max_tier`, `_max_tier`)
-  are byte-locked to the resolver. Flipping defaults MOVES the quote -> expected values must update.
-- Dashboard-ui: no start-time model picker (grep empty). mid-run switcher UI also appears absent
-  (POST endpoint exists, no UI consumer found).
-
-## 3. Tier -> model mapping AFTER the change
-
-| Tier (RARV phase)        | Today                    | After                                  |
-|--------------------------|--------------------------|----------------------------------------|
-| planning (REASON)        | opus                     | sonnet (Opus opt-in via advisor path)  |
-| development (ACT/REFLECT)| opus                     | sonnet                                 |
-| fast (VERIFY)            | sonnet                   | sonnet (haiku via LOKI_ALLOW_HAIKU)    |
-| trust gate (council/review)| account default (float)| account default (UNCHANGED); opus via OPT-IN `LOKI_ADVISOR_MODEL` |
-| advisor / reviewer pin    | (does not exist)         | `LOKI_ADVISOR_MODEL` (default unset = today's behavior; set=opus) |
-| Opus-for-execution       | default                  | opt-in (dashboard "all opus" / env)    |
-
-### CORRECTION (advisor review 2026-06-30) - D2 is OPT-IN, not always-on
-
-The original board D2 ("always pin reviewers to --model opus") is REJECTED as written, for four reasons:
-1. NOT causally forced by the Sonnet flip: `_dispatch_reviewer` reads neither `tier_param` nor
-   `CLAUDE_DEFAULT_*`, so flipping the builder default does NOT change the reviewer model. The judge
-   floating with the account default is a PRE-EXISTING condition, not something this PR exposes.
-2. UNCOSTED: pinning 3 reviewers + devil's-advocate + security-sentinel to Opus ADDS Opus-priced tokens
-   on top of the builder savings. Opus ~1.7x sonnet. This could eat or exceed the "~40% cheaper" story.
-   Net cost is UNKNOWN until we measure reviewer-token vs builder-token volume for a typical `loki start`.
-3. CONTRADICTS the founder's words: "advisor will be opus IF NEEDED OR USER OPTED" = conditional/opt-in.
-   Always-on removes the implicit cost control users have today (account default) - opposite of the
-   adoption/cost intent.
-4. "Deterministic verdict" is the wrong framing: LLM reviewers are never deterministic; this is a
-   consistency/quality argument, not determinism.
-
-Moat guarantee (corrected): default behavior of the trust gate is UNCHANGED by this release (no
-cost regression, no surprise). Users who want a strong, consistent Opus judge set `LOKI_ADVISOR_MODEL=opus`
-(or the dashboard "advisor: Opus" toggle), which pins the reviewer/override-judge to Opus. This is the
-founder's "opus if needed or user opted", made real and opt-in. Lane B and Lane C COLLAPSE into this one
-opt-in advisor path.
-
-## 4. Per-file change list (disjoint lanes for parallel principal engineers)
-
-### Lane A - Execution default flip (providers/claude.sh) [engineer 1]
-- claude.sh:56 `CLAUDE_DEFAULT_DEVELOPMENT="opus"` -> `"sonnet"`.
-- claude.sh:55 `CLAUDE_DEFAULT_PLANNING="opus"` -> `"sonnet"` (see open question Q1 - founder may want
-  planning to stay opus; design so this one line is a trivial revert).
-- claude.sh:57 FAST stays sonnet.
-- Trace + document the clamp ripple: `loki_apply_max_tier_clamp` (claude.sh:347) resolves planning/fable
-  DOWN to `PROVIDER_MODEL_DEVELOPMENT`. With dev=sonnet, `LOKI_MAX_TIER=sonnet` now genuinely pins
-  sonnet (previously it clamped to opus). Update the comment block at claude.sh:383-386 which currently
-  documents the opposite. This is a BEHAVIOR clarification, verify against the parity ports (Lane E).
-- run.sh:~2447 legacy fallback `development) echo opus` -> `sonnet` (inert but consistent).
-
-### Lane B+C (COLLAPSED) - OPT-IN advisor/reviewer Opus pin [engineer 2]
-- Introduce `LOKI_ADVISOR_MODEL` (unset default = TODAY'S behavior, no change; set to `opus` = pin).
-- Bash: `_dispatch_reviewer()` (run.sh:~10148): IF `LOKI_ADVISOR_MODEL` is a valid allowlisted alias,
-  add `("--model" "$LOKI_ADVISOR_MODEL")` to `_rv_argv`; else leave unset (current behavior). Honor the
-  existing comment (opus ok, never fable - validate the alias is not fable). The override/architect paths
-  (which rewrite tier_param, NOT this dispatch) still cannot touch it.
-- Bun: `quality_gates.ts` reviewer dispatch (near :1223): mirror the same opt-in read. BOTH routes match.
-- Update the "reviewers deliberately do NOT pass --model" comments to: default no --model; opt-in pin
-  via LOKI_ADVISOR_MODEL; rationale = consistent/strong judge when the user wants it (NOT determinism).
-- Devil's-advocate + security-sentinel inherit the opt-in pin (same dispatch).
-- Dashboard: an "Advisor model" toggle (default: account default; option: Opus) writes LOKI_ADVISOR_MODEL
-  into the run env / a state file the dispatch reads. This IS the founder's "opus if needed or user opted".
-- DO NOT make this always-on. Default behavior of the trust gate is unchanged (no cost regression).
-
-### Lane D - Dashboard model selection [engineer 4] (follows frontend-ui-engineering skill)
-- Backend: confirm `POST /api/session/model` (server.py:2852) writes `.loki/state/model-override`
-  with allowlist haiku|sonnet|opus|fable (already does). Add start-time selection: `start_build`
-  (server.py:3234) accepts an optional `model` that writes the override file BEFORE launch (so iteration
-  1 picks it up). Validate against the same allowlist + clamp.
-- Frontend (legacy-ui/src): add an accessible model selector (haiku/sonnet/opus) on the start/new-run
-  surface AND a mid-run switcher that calls POST /api/session/model. Real design-system tokens, keyboard
-  accessible, no AI-aesthetic. Show current effective model + that switch applies at next iteration.
-  Rebuild legacy-ui-static per CLAUDE.md release step 2.
-
-### Lane E - Catalog IDs, pricing note, parity tests [engineer 5]
-- model_catalog.json: opus-4-7 -> claude-opus-4-8 (3 occurrences), sonnet-4-6 -> claude-sonnet-5
-  (5 occurrences). Keep the alias->tier structure.
-- Pricing: LEAVE the cost NUMBERS at standing $3/$15 for sonnet (over-estimate is the safe direction;
-  avoids date-expiry logic that silently breaks after Aug 31 2026). ADD a one-line intro-price NOTE in
-  the dashboard pricing display / label ("Sonnet 5 intro $2/$10 through Aug 31 2026") - display only,
-  not a computed rate. Update labels "Sonnet (latest)" -> "Sonnet 5".
-- codex gpt-5.3-codex $1.50/$12: UNVERIFIED external number. WebFetch OpenAI pricing to confirm or leave
-  with a "verify" note; do not propagate a guess as fact.
-- Confirm gemini fully absent from pricing (deprecated v7.5.18).
-- Parity tests: update `tests/test-model-override.sh` expected values (dev tier now sonnet). Update
-  dashboard estimator expected quotes. Any Bun parity test for the resolver. Run the parity matrix.
-
-## 5. Test / parity changes enumerated
-- tests/test-model-override.sh: dev-tier resolution + LOKI_MAX_TIER=sonnet clamp expectations flip.
-- Dashboard estimator parity test: per-iteration quote changes (opus->sonnet dev cost).
-- New: a test asserting the trust-gate reviewer dispatch includes `--model opus` on BOTH routes
-  (grep/behavioral) - locks the moat guarantee so a future edit can't silently un-pin.
-- New: start_build with model param writes a valid override; invalid model rejected.
-- CLI-invariance: existing `loki verify` / `loki start` still run (no crash); default model differs
-  (that IS the intended change - do NOT assert byte-identical default output here).
-
-## 6. Calibration protocol (CEO gate - before ship)
-- Pick 5-10 representative specs from benchmarks/ or internal fixtures spanning easy->hard.
-- Run each on Sonnet-default vs current Opus-default (real model calls; NOT in CI - documented manual
-  step). Record: iterations-to-council-APPROVE, BLOCK count, wall-clock, and NET cost (builder tokens +
-  reviewer tokens, so the "~40% cheaper" claim is verified NET, not just on the builder tier). Append to
-  a calibration log under artifacts/sonnet5-calibration/.
-- SHIP criterion: Sonnet-default does not materially increase iterations-to-APPROVE or BLOCK-rate on
-  hard specs AND the net cost genuinely drops. If iterations/BLOCK regress: keep the pre-built escape
-  hatch (planning->opus one-line revert; dev stays sonnet) and re-measure. Never silently keep Opus -
-  make the escalation legible. If net cost does NOT drop as claimed, correct the marketing claim to the
-  measured number - never ship an unverified "~40% cheaper".
-
-## 7. Release (per CLAUDE.md)
-- Version bump all files (MINOR). Loud CHANGELOG entry: "Default execution model changed Opus -> Sonnet 5.
-  ~40% cheaper builds. Trust-gate reviewers pinned to Opus (deterministic verdict). Override any model
-  from the dashboard." Never claim "same accuracy" (no controlled study).
-- bash scripts/local-ci.sh (must be green). Council 3/3 (2 Opus + 1 Sonnet reviewers that RUN tests).
-- Rebuild dashboard frontend (Lane D). Merge worktree to main, tag via CI, verify 4 channels.
-- NEVER run a loki build from the worktree (self-delete trap). Verify engine changes by function
-  extraction to scratch repos.
-
-## 8. Open questions for the founder (do NOT block starting)
-- Q1: Should PLANNING tier also default to Sonnet (full flatten), or stay Opus (architecture quality)?
-  Plan flattens both per plain reading; Lane A makes planning a one-line revert either way.
-- Q2: "advisor" scope - is it the completion-council override judge (recommended, minimal) or a
-  distinct advisory role you envision elsewhere?
-- Q3: Sonnet 5 intro pricing - display-only note (planned) vs actually bill the $2/$10 in estimates
-  (rejected: date-expiry bug risk). Confirm display-only is acceptable.

package/docs/SPEED-AND-FIRST-PASS-PLAN.md

@@ -1,281 +0,0 @@
-# Fastest First-Pass Completion: measured plan
-
-Goal (founder, 2026-08-01): **fastest first-pass full completion** -- highest
-quality output, no waiting through a second iteration, faster than Cursor /
-Cognition / Replit on the axis a user actually feels.
-
-This plan is built on measurement first, competitor research second, and it
-DISCARDS the intuition I started with.
-
----
-
-## 1. What the competition actually does (researched, not assumed)
-
-| Vendor | Speed mechanism | Reachable for us? |
-|---|---|---|
-| **Cursor** | Composer: in-house MoE model, ~250 tok/s (~4x GPT-5/Sonnet). MXFP8 training, no post-train quant. Compaction-in-the-loop RL cuts context errors 50%. | **No.** Custom frontier model. |
-| **Cognition** | SWE-1.6 at ~950 tok/s; SWE-bench 51.5%. | **No.** Custom model. |
-| **Replit** | Agent 3: ~2 min to visual preview, ~10 min to first app version. Design Mode <2 min. 2-3x gains across 2025. | **Partly.** Their edge is product/lifecycle, not model. |
-
-**The strategic conclusion.** Cursor and Cognition bought speed by TRAINING
-THEIR OWN MODELS. We cannot copy that and should stop pretending the gap is
-closable that way. Replit's edge is time-to-first-visible-thing, which IS
-reachable, because it is a product and lifecycle property.
-
-The industry-wide numbers that matter for us, from the latency research:
-
-- **Tool execution is 35-61% of total agent request time.** Harness, not model.
-- Parallel tool calling / speculative execution deliver **2-5x latency
-  reduction while preserving correctness**.
-- Prompt caching turns repeated-prefix attention from O(n^2) to O(n).
-
-That 35-61% is our lane. It is won by architecture, and it does not require a
-frontier lab.
-
-## 2. What we actually cost, MEASURED (this is the surprise)
-
-Real `stage_complete` events from builds on this machine (n=35):
-
-| stage | n | median s | max s | total s |
-|---|---:|---:|---:|---:|
-| **code_review** | 3 | **281** | **504** | **1055** |
-| static_analysis | 5 | 5 | 14 | 26 |
-| security_scan | 5 | 1 | 2 | 4 |
-| lsp_diagnostics | 4 | 1 | 1 | 2 |
-| test_suite | 4 | 0 | 1 | 1 |
-| mutation_integrity | 4 | 0 | 1 | 1 |
-| mock_integrity | 4 | 0 | 0 | 0 |
-| doc_coverage | 3 | 0 | 0 | 0 |
-| magic_debate | 3 | 0 | 0 | 0 |
-| **TOTAL** | | | | **1089** |
-
-**`code_review` is 97% of all measured gate time.** Everything else combined is
-34 seconds.
-
-### Two intuitions this killed
-
-**First:** I was about to propose parallelizing the seven sequential gates at
-`run.sh:22616-22980`. They ARE sequential and mostly independent. The change
-would have been clean, defensible, and worth **about 20 seconds**.
-
-**Second, and worse:** I then proposed parallelizing the reviewer council --
-which was **already parallel**. I had grepped the wrong line range, got no
-match, and treated that silence as evidence. A plan whose headline item was a
-no-op.
-
-Both were caught by going back to data instead of trusting the story. The
-standing rule for this document:
-
-> **No optimization ships without a before-number from this table, and no
-> claim about how the code behaves ships without reading the code that does
-> it.**
-
-An absent grep match is not evidence of absence -- it is evidence the grep did
-not match.
-
-### Where the real time goes
-
-Code review dominates, and the driver is **council size**, not sequential
-dispatch (see the correction in P0 -- my first reading of this was wrong).
-
-Measured: 3 reviewers finish in 31s; 6-7 reviewers take 177-502s. The council
-is already concurrent, so what grows is the max-of-N tail plus contention on a
-single provider.
-
-This explains the founder's "21 minutes for a simple GitHub issue" better than
-any other measurement taken today: a scoped issue was drawing a 7-member
-council containing two overlapping security reviewers.
-
----
-
-## 3. The plan, ranked by measured seconds returned
-
-### P0 -- CORRECTED: the council is ALREADY parallel. The cost is its SIZE.
-
-**This section originally claimed reviewers ran sequentially and proposed
-parallelizing them. That was wrong, and the correction is recorded here rather
-than quietly edited out.**
-
-`run_code_review` forks every reviewer with `) &` (run.sh:14803), collects PIDs,
-and `wait`s on each (run.sh:14880). It has been parallel all along. My first
-grep searched the wrong line range, returned nothing, and I read that silence as
-proof of absence -- the same mistake class this codebase has been punishing all
-session.
-
-**What the data actually says.** Pairing `code_review_start` with
-`code_review_complete` across every recorded review:
-
-| reviewers | seconds | verdict |
-|---:|---:|---|
-| 7 | 502 | 0 pass / 7 fail |
-| 7 | 280 | 1 pass / 6 fail |
-| 6 | 177 | 0 pass / 5 fail |
-| **3** | **31** | 2 pass / 1 fail |
-
-**3 reviewers = 31s. 7 reviewers = 280-502s.** Roughly 2x the council for 9-16x
-the wall clock. Since dispatch is already concurrent, that superlinearity is not
-the count itself -- it is that a larger council pulls in slower reviewers and
-contends for the same provider, so the max-of-N tail dominates.
-
-**And the 7-member council is partly redundant:**
-
-```
-architecture-strategist, maintainer-mergeability,
-security-sentinel, review-security,      <- TWO security reviewers
-performance-oracle, eng-qa, dependency-analyst
-```
-
-`security-sentinel` and `review-security` overlap. `eng-qa` and
-`dependency-analyst` are appended agents, not part of the sized battery.
-
-**The real P0, in priority order:**
-
-1. **Deduplicate overlapping reviewers.** Two security reviewers on one diff is
-   paying the tail cost twice for one signal. Collapse by mandate, not by name.
-2. **Cap the effective council for scoped changes.** The tier map is
-   `{simple: 2, standard: 2, complex: 4}` specialists + 2 mandatory. Appended
-   agents bypass that sizing entirely, which is how 4 becomes 7. Bound the
-   TOTAL, not just the specialist slots.
-3. **Bound the tail, not the mean.** One slow reviewer sets the whole council's
-   latency. A per-reviewer deadline that records a non-vote (never a silent
-   pass) converts a 502s worst case into a bounded one.
-
-Expected: the 6-7 member case moves toward the measured 3-member behaviour
-(31s) for scoped work, while `complex` keeps its deeper battery.
-
-**Fail-safe direction is load-bearing:** a dropped or deadlined reviewer must
-count as a NON-VOTE exactly as today, never as a pass. Shrinking a council must
-never be able to manufacture approval. Guard with a test asserting the verdict
-is identical for the same fixture at any council size, and that a deadlined
-reviewer never contributes a PASS.
-
-### P1 -- Do not run the full council on iteration 1 of a scoped change
-
-The 8-gate council exists to catch regressions in a large build. On a scoped
-GitHub-issue fix, running a 3-reviewer council before the change is even
-verified is spending 281s to review something a test run would disprove in 1s.
-
-- Order: cheap deterministic gates FIRST (test_suite, static_analysis,
-  lsp_diagnostics -- 6s combined), council only if those pass.
-- A failing test means the council would have rejected anyway; running it first
-  is strictly wasted wall-clock.
-- Expected: on a failing first pass, ~281s saved outright.
-
-### P2 -- Time-to-first-signal (the Replit lesson)
-
-Replit shows a visual preview in ~2 minutes. We show nothing until an iteration
-completes. Even when our total time is competitive, the FELT time is worse.
-
-- Emit a first-signal event as soon as the agent's first file write lands.
-- `.loki/app-runner/first-preview.json` already exists (write-once, bash route)
-  -- surface it, and extend to the non-preview case as "first artifact".
-- This is perception, not throughput, and it is cheap.
-
-### P3 -- First-pass correctness (the actual "no second iteration" ask)
-
-Research finding: success now hinges on **specification quality and dynamic
-context**, not static upfront planning. Notably, auto-generated context files
-REDUCED success ~3% while human-written ones improved it ~4%, both raising cost
-20%+. So "generate a big context file" is measurably the wrong move.
-
-What the evidence supports:
-- ACE (ICLR 2026): generate -> reflect -> curate as an evolving context loop:
-  **+10.6% on coding benchmarks**.
-- We already have the seam: `LOKI_INJECT_FINDINGS` feeds structured per-finding
-  records into the next iteration.
-- The lever is making iteration 1's prompt carry what iteration 2 would have
-  learned -- which the existing first-pass-excellence work began and which
-  measured 2.8x cheaper with correctness held.
-
-**Do not** add a static generated context file. The data says it hurts.
-
-### P4 -- Prompt-cache discipline (already partly built, verify it holds)
-
-`[CACHE_BREAKPOINT]` splits a cache-stable prefix from a volatile tail. Cache
-reads price at 0.1x input. Any always-on instruction added to the wrong side
-busts the cache every iteration.
-
-- Add a regression test asserting no volatile content crosses the breakpoint.
-- This is a cost lever primarily, and a TTFT lever secondarily.
-
----
-
-## 4. What we do NOT do
-
-- **Do not train a model.** Cursor and Cognition's speed is bought with custom
-  MoE models at 250-950 tok/s. That is not a gap we close with harness work,
-  and claiming otherwise would be dishonest.
-- **Do not parallelize the seven cheap gates as a headline.** Measured worth:
-  ~20s. Do it opportunistically inside P1's reordering, never sold as the win.
-- **Do not add static generated context files.** Measured -3% success, +20%
-  cost.
-
-## 4b. Shipped, and VERIFIED ON THE REAL CODE PATH
-
-P0-P2 shipped in v8.33.0, v8.34.0 and v8.35.0. Each is default-OFF, so none
-changes behaviour until switched on.
-
-The claim "the knob works" was verified by extracting run.sh's ACTUAL selector
-heredoc and running it -- not by re-implementing it, which is the mistake that
-let three mutations survive across v8.28.0/v8.34.0/v8.35.0:
-
-```
-cap=0 -> 6 reviewers: architecture-strategist, maintainer-mergeability,
-                      security-sentinel, test-coverage-auditor,
-                      performance-oracle, dependency-analyst
-cap=4 -> 4 reviewers: architecture-strategist, maintainer-mergeability,
-                      security-sentinel, test-coverage-auditor
-cap=3 -> 3 reviewers: architecture-strategist, maintainer-mergeability,
-                      security-sentinel
-```
-
-Two things this proves that a unit test could not:
-
-1. The cap reaches the real selector through the real env, at every level.
-2. **The safety property holds in production code**: `architecture-strategist`
-   and `maintainer-mergeability` -- the mandatory pair -- survive at cap=3,
-   cap=4 and uncapped. Only the appended tail is trimmed. A cap can shrink the
-   council but can never remove a mandate.
-
-For the skip knob, `gate_failures` (declared run.sh:22697) and the skip decision
-(run.sh:22962) were confirmed to sit in the SAME function scope
-(`run_autonomous`, run.sh:20842), so the skip genuinely observes the accumulated
-failures rather than an empty shadow.
-
-**Mapping to measured wall clock.** From the table in section 2: 6 reviewers
-took 177s and 3 took 31s. Capping a complex-tier council from 6 to 3 therefore
-targets the 31s regime for scoped work while `complex` keeps its deeper battery
-when uncapped.
-
-**What is still NOT proven:** an end-to-end scoped-issue run with the knobs on.
-That requires a real paid build, and until it is measured, the numbers above are
-selector behaviour plus historical stage timings -- not a demonstrated
-end-to-end improvement. Do not report it as one.
-
-## 5. How we know it worked
-
-Every item ships with a before/after from the same `stage_complete` telemetry
-that produced the table above. The acceptance number for the founder's
-complaint:
-
-> a scoped GitHub issue completes in **under 5 minutes**, first pass,
-> with the council verdict intact.
-
-Current measured critical path for that case is dominated by 281s of
-sequential code review. P0 + P1 target exactly that.
-
-## 6. Honest competitive position after this plan
-
-- **vs Cursor** on raw interactive latency: still behind. Different category.
-- **vs Replit** on time-to-first-visible: reachable with P2.
-- **vs Cognition** on trust: ahead, and that is the moat -- the Evidence
-  Receipt, now that the gates behind it actually run (v8.24.0-v8.31.0).
-
-The wedge is **verified-and-fast**, not fastest-in-absolute. We should say that
-plainly rather than claim a speed crown we cannot hold.
-
----
-
-Sources: Cursor Composer blog, VentureBeat Composer coverage, Cognition
-SWE-1.6 reporting, Replit Agent 3 reviews, Zylos speculative-execution/parallel
-tool-calling research, ACE (ICLR 2026), 2026 context-engineering surveys.

package/docs/STALE-STATE-AUDIT.md

@@ -1,174 +0,0 @@
-# Stale-State Audit
-
-Audit for siblings of the `loki.pgid` session-killer (fixed in 4792b521).
-
-**The shape being hunted:** a file recording a PID, PGID, port, lock, or session
-id, written by one run, NOT removed on abnormal exit, later TRUSTED by another
-run after the OS recycled the identifier.
-
-**Method:** grep for the write, find its `rm -f`, check whether a trap covers
-INT/TERM/crash, then check whether the reader proves the record is still
-current. Every candidate was measured on this host rather than judged by
-reading, because the pgid finding was credible on evidence (155h/202h orphans),
-not on the code looking wrong.
-
-Scope: read-only across the repo; fix applied to one file (`autonomy/run.sh`).
-
----
-
-## Measured state of this host
-
-Run from the repo root on 2026-08-08:
-
-| File | Contents | Live? | Age |
-|---|---|---|---|
-| `~/.loki/dashboard/dashboard.pid` | absent | n/a | n/a |
-| `.loki/dashboard/dashboard.pid` | `87992` | **DEAD** | **mtime Jul 31 (8 days)** |
-| `$TMPDIR/loki-local-ci.lock` | `61876` | LIVE (real local-ci) | current |
-| `.loki/app-runner/app.pid` | absent | n/a | n/a |
-
-The dashboard pid file is the same measured shape as the pgid orphans: a dead
-identifier, days old, still on disk, still trusted by a code path that kills.
-
----
-
-## Findings, ranked by blast radius
-
-### FINDING 1 (HIGH -- fixed here): shared dashboard pid is killed unverified
-
-**Evidence.** `autonomy/run.sh:1597-1600` reads a pid from
-`~/.loki/dashboard/dashboard.pid` and sends it `kill` then `kill -9` with no
-liveness and no identity check.
-
-Removal of that file happens ONLY on explicit stop paths -- `run.sh:16608`,
-`:16658`, `:17399`, and `autonomy/loki:7078-7079`. **No trap covers a crash or
-Ctrl+C.** That is precisely why the measured copy in this checkout is 8 days
-stale with a dead pid.
-
-**Reachable:** yes. Called from `cleanup` on both stop paths (`run.sh:25311`,
-`:25384`).
-
-**Blast radius: the worst class.** The file lives under `~/.loki`, so it is
-machine-global -- the victim need not belong to this project. A recycled pid
-names an unrelated live process and receives `kill -9`.
-
-**Why `kill -0` would not have fixed it:** a recycled pid IS alive, so a
-liveness check passes. This is the identical insufficiency the `loki.pgid`
-self-check had. The guard has to check IDENTITY.
-
-**Fix applied.** `_loki_pid_looks_like_dashboard()` at `autonomy/run.sh:1526`,
-gating the kill at `:1597`. It mirrors `_app_runner_pid_is_ours`
-(`app-runner.sh:242`) and **fails OPEN**: when `ps` reports nothing we signal
-exactly as before, so a legitimate dashboard is never left running by this
-check. The only behavior change is refusing to kill a process positively
-identified as not a dashboard.
-
-Deliberately NOT done: adding a trap to remove the pid file on crash. That is a
-larger change across the dashboard lifecycle, and the identity guard already
-makes a stale file harmless at the point where it does damage. The stale file
-still being present is untidy, not dangerous, once the killer verifies.
-
-**Test:** `tests/test-stale-dashboard-pid.sh`, 6/6, mutation-verified below.
-
-### FINDING 2 (MEDIUM -- reported, not fixed): `app_runner_stop` group-kills unverified
-
-**Evidence.** `app-runner.sh:1407` falls back to reading `app.pid` from disk,
-then `:1456` sends `kill -TERM "-$_APP_RUNNER_PID"` -- a **process-group**
-signal -- without an identity check.
-
-The repo already has the right guard: `_app_runner_pid_is_ours`
-(`app-runner.sh:242`). It is called at `:1657` and `:1829` but **not** on the
-stop path. `app-runner.sh` has **no trap at all** (`grep -n "trap " ` returns
-nothing), so `app.pid` survives a crash exactly like the pgid file did.
-
-**Blast radius:** higher per-hit than Finding 1 (a group signal reaches a whole
-tree) but narrower reach: the file is project-local (`.loki/app-runner/`), not
-machine-global, and was absent on this host. Not fixed because it is a third
-file and the lead scoped this task to one; it needs its own change adding
-`_app_runner_pid_is_ours` to the stop path.
-
-### FINDING 3 (LOW -- reported, not fixed): local-ci lock guard is a no-op under `/bin/bash`
-
-**Evidence.** `scripts/local-ci.sh:104`:
-
-```
-trap '[ "$$" = "$_lci_owner" ] && rm -f "$_lci_lock" 2>/dev/null || true' EXIT
-```
-
-The scar comment above it (`:99-103`) correctly diagnoses that a bare EXIT trap
-fires in every subshell and that a finishing child deleted the parent's lock.
-**But `$$` does not change in a bash subshell, so this guard does not
-discriminate.** Verified:
-
-```
-$ bash -c 'p=$$; ( [ "$$" = "$p" ] && echo same )'
-same
-```
-
-The correct discriminators are `BASHPID` (bash 4+) or `BASH_SUBSHELL` (works in
-3.2). Measured on this host: the script is `#!/usr/bin/env bash` which resolves
-to **bash 5.3**, where `BASHPID` is available. But `/bin/bash` here is **3.2**,
-where `BASHPID` is unset and `BASH_SUBSHELL` is the version-safe choice.
-
-**Blast radius: benign** by the lead's own criterion. Worst case is two
-concurrent local-ci runs starving each other into phantom failures -- costly in
-time and trust, but it kills nothing. Left unfixed as out of scope; the one-line
-change is `[ "${BASH_SUBSHELL:-0}" = 0 ]`.
-
-Note on the sibling fix already shipped: `_loki_remove_pgid_file`
-(`run.sh:25189`) uses `${BASHPID:-$$}`. Under bash 3.2 that collapses to `$$`
-and the guard degrades to the no-op. **The degradation direction is safe** -- a
-subshell deletes the pgid file early, the reap then finds no file and skips, so
-an orphan survives and nobody gets killed. `run.sh` is also `#!/usr/bin/env
-bash` (5.3 here), so this is a portability note, not a live defect. Worth
-knowing: the mutation test for that guard asserts *source text* contains
-`BASHPID`, so it proves the code is present, not that it behaves correctly on a
-3.2 host.
-
----
-
-## Already guarded -- do not re-audit
-
-Checked and found correct. Listed explicitly so this ground is not covered
-twice.
-
-- **`autonomy/lib/lock.sh:56-67`** -- `_loki_lock_is_stale` requires the
-  sentinel PID to be dead **AND** mtime > 30s. Both conditions, not either.
-  Correct.
-- **`cleanup_orphan_pids` (`run.sh:2300+`)** -- reaps only on liveness AND
-  parent death AND (for wrappers) idle-past-budget AND no live engine child.
-  Also self-skips `$$`. Correct, and notably stricter than the pgid reap was.
-- **`_app_runner_pid_is_ours` (`app-runner.sh:242`)** -- a real identity token
-  captured post-exec, failing open on a missing token so a live app is never
-  falsely killed. Correct where it is called; see Finding 2 for where it is not.
-- **`_app_runner_collect_descendants` (`app-runner.sh:289`)** -- refuses pid
-  0/1 and walks parent-child links from our own pid only, so it structurally
-  cannot signal outside our subtree. Correct.
-- **`status.ts:266-270` and the bash status reader (`loki:5092`)** -- both do
-  `os.kill(pid, 0)` before reporting. A wrong answer only mislabels a URL in
-  status output. Benign even when stale.
-- **The `CLEAR`/`KEEP` registry check (`run.sh:1545-1560`)** -- correctly
-  refuses to tear the shared dashboard down while any other project holds a
-  live pid. This gates Finding 1's call site; the defect was the missing check
-  on the pid itself, not this decision.
-
----
-
-## Mutation verification (Finding 1's fix)
-
-Each guard was reverted individually; the test must go red, and only on its own
-assertion.
-
-| Mutation | Before | After | Assertion killed |
-|---|---|---|---|
-| Identity check downgraded to bare `kill -0` | 6 pass / 0 fail | 5 / 1 | "a live non-dashboard process is refused" |
-| Call site ungated (guard present but unused) | 6 / 0 | 5 / 1 | "the kill is gated on the identity guard" |
-| `pid > 1` check removed | 6 / 0 | 5 / 1 | "pid 0/1, empty and malformed inputs refused" |
-
-Restored after each. Final: `bash -n autonomy/run.sh` clean,
-`tests/test-stale-dashboard-pid.sh` 6/6, `tests/test-pgid-stale-reap.sh` 8/8
-(unaffected).
-
-The first mutation is the important one: it replaces the identity check with
-exactly the insufficient guard (`kill -0`) that a reviewer would most likely
-propose, and the test catches it.