loki-mode 7.129.5 → 8.0.1

package/docs/V8-COMPLEXITY-AUDIT-2026-07-24.md

@@ -0,0 +1,45 @@
+# v8 complexity audit: delete-list candidates
+
+Date: 2026-07-24. Read-only. **Zero deletions performed** (founder decision).
+
+## Why this audit exists
+
+The competitive research corpus (source 12) proposed deleting `voice.sh`,
+cockpit image rendering, `web-app/`, Managed Agents, and the "41 static roles"
+to reduce single-maintainer load. VALIDATION.md marks that source's "unused"
+label as an **assumption it never verified**, and the same source was already
+caught undercounting `autonomy/loki` by 10k lines. So each candidate needed
+positive proof, not a confident assertion.
+
+**Method:** positive proof of non-reference. An absent grep hit is not evidence
+(memory: grep-absence-false-green). A component counts as live if anything
+references it, dispatches it, or ships it.
+
+## Findings
+
+| Candidate | Verdict | Evidence |
+|---|---|---|
+| `autonomy/voice.sh` (501 lines) | **ORPHANED (only true positive)** | Referenced by NOTHING except itself: a repo-wide search across `autonomy/`, `loki-ts/`, `scripts/`, `tests/`, `mcp/`, `dashboard/` returns only the file. Meanwhile `cmd_voice()` (`autonomy/loki:22751`) is dispatched (`:17884`) but is a 4-line stub that prints "Voice mode is planned for a future release" and points at issue #85. So the COMMAND is live and honest; the 501-line SCRIPT behind it is dead weight shipped in the npm tarball (`package.json` includes `autonomy/`). |
+| cockpit rendering | **LIVE** | Real module with 5 source files (`loki-ts/src/cockpit/{raster,cli,capability,svg,render}.ts`). Not an orphan. Source 12 cited `loki-ts/src/commands/cockpit.ts`, which does NOT exist: its path was wrong, its conclusion untested. |
+| `web-app/` | **LIVE AND SHIPPED** | 12 explicit entries in `package.json` `files` (`web-app/dist/`, `server.py`, `auth.py`, `models.py`, ...). Deleting it would break the published package. |
+| Managed Agents | **NOT SUBSTANTIATED** | The claimed "NOT TESTED against live Anthropic API" marker in SKILL.md was not found. The premise of the delete recommendation could not be reproduced. |
+| "41 static roles" | **MISCHARACTERIZED** | `references/agent-types.md:9` already documents these precisely: "prompt-defined specifications the orchestrator adopts per phase, **not separate processes**", with "typically 5-10 for simple projects" activated. They are a catalog, not 41 running agents. There is no static-role runtime cost to delete. |
+
+## Conclusion
+
+**One of five candidates survived.** Four were live, mis-pathed, unsubstantiated,
+or mischaracterized. This is consistent with the pattern across this whole
+planning pass: the research corpus's confident specifics do not survive contact
+with the repo, and the plan's "audit before deleting anything" rule was load
+bearing rather than cautious.
+
+`autonomy/voice.sh` is a genuine 501-line orphan. Even so, **no deletion is
+performed here** per the founder decision. Recommended follow-up, separately and
+evidence-gated: either delete `voice.sh` and keep the honest `cmd_voice` stub, or
+keep the script if issue #85 will build on it. That is a small, isolated call
+with no dependents by definition.
+
+## What this does NOT claim
+
+This audit covers only the five named candidates. It is not a repo-wide dead-code
+sweep, and it makes no claim about the rest of the tree.

package/docs/V8-MAJOR-RELEASE-PLAN.md

@@ -0,0 +1,137 @@
+# v8 Major Release - Costed Decision Plan
+
+Status: PROPOSAL (founder review before any implementation spend). 2026-07-24.
+Author: this session, grounded in the actual repo state (not aspirational).
+
+## TL;DR (the honest headline)
+
+**v8 is ~80% built and tested, but uncommitted.** The hard engineering - a 12,300-line
+parity-locked TypeScript runner, the Anthropic SDK route (`sdk_invoker.ts`, `sdk_mode.ts`,
+stream parser), and ~18,000 lines of *working, test-passing* feature work (supervised builds,
+deadline confinement, honesty/no-mock hardening, code-review calibration) - already exists in
+the working tree. The V8-AGENT-SDK-PLAN and RARV-C-100X-PLAN both say so explicitly:
+"much of this is already shipped."
+
+So "the v8 major release" is NOT a build-from-scratch effort. It is, in order of cost:
+1. **CONSOLIDATE + VERIFY + SHIP** what already works (cheap, high-value, the bulk of the win).
+2. **A bounded net-new layer** the founder asked for: jcode-informed harness-intelligence,
+   PostHog analytics, the otel 2.x upgrade.
+
+This plan costs each phase so the founder funds them selectively, not as one open-ended blob.
+
+---
+
+## Where v8 actually stands (verified this session)
+
+| Component | State | Evidence |
+|---|---|---|
+| TS runner (autonomous loop, council, gates, prompt) | Built, parity-locked | `loki-ts/src/runner/` 12.3k lines, 22 modules |
+| Anthropic SDK route (judges = raw SDK, loop = Agent SDK) | Built + tested | `sdk_invoker.ts`, `sdk_mode.ts`, `sdk_stream_parser.ts`; tests: sdk_invoker, sdk_stream_parser, sdk_query_provider, sdk_loop_e2e |
+| One-switch `LOKI_SDK_MODE` (off/judges/full) + rollback | Built | CHANGELOG v8.1; byte-mirrored bash+TS, shared parity fixture |
+| Supervised builds / deadline confinement | Built + tests PASS | `deadline.py`, `build_supervisor.py`, `dependency-setup.sh` + `test-hard-deadline-confinement`, `test-supervised-*` (verified passing) |
+| Honesty / no-mock hardening | Built + tests PASS | `no_mock_scan.py`, `test-harness-false-green`, `test-honest-gate-status`, `test-nomock-data-render` (verified passing) |
+| Code-review calibration | Built | `test-review-severity-calibration`, `-assurance-tail`, `-lockfile-context` + council/quality_gates mods |
+| ~18k LOC uncommitted total | Working, not committed | `git diff`: 46 files +7173/-1296; 25 new files +11057 LOC |
+| Published to npm as 8.x | NO | npm latest = 7.129.4; v8 never published, never merged to main |
+| PostHog analytics | **BUILT** (`5dcc88c6`) | opt-in `build_verified` event behind a strict second gate (`LOKI_ANALYTICS=on`, default OFF even when telemetry is on), fixed allowlist reader emits proof scalars only |
+| otel 2.x (the deferred CVE fix) | **DONE** (`159dc7f4`) | clears GHSA-45rx-2jwx-cxfr at source |
+| Phase 3 harness intelligence | **BUILT** (`9e596e9a`, `889bd52a`, `500e74f6`) | 3a prompt-cache discipline already existed (verified, not rebuilt); 3b confidence-spike, 3c goal scoring, 3d smart retry landed 2026-07-25 |
+| Release identity (VERSION vs CHANGELOG) | **RESOLVED** (`a749ee54`) | folded the drafted `v8.1.0` block into one `v8.0.0` entry; no 8.x was ever published, so a first-ever 8.x as 8.1.0 would have described a release history that does not exist |
+
+**Releasability gate:** full `local-ci.sh` on the WIP tree - RESULT PENDING (running at write time;
+this plan's Phase 1 cost depends on how clean it is).
+
+---
+
+## The CHANGELOG-vs-WIP question (must resolve first)
+
+The `## v8.1.0 (unreleased)` CHANGELOG entry documents ONLY the SDK one-switch/rollback/packaging
+gate. But the ~18k uncommitted lines are mostly OTHER efforts (supervised builds, deadline,
+honesty, review calibration). **The documented release scope and the actual WIP do not match.**
+
+Resolution needed from founder: is the v8 MAJOR release =
+- (A) the SDK route ONLY (commit just the SDK-related files, ship a focused v8.0.0), OR
+- (B) EVERYTHING in the tree (SDK + supervised + honesty + review work) as one big v8.0.0?
+
+Recommendation: **(B)**, because the extra work is on-thesis (all deepens the trust moat), already
+tested, and shipping it piecemeal means more release cycles. But it requires per-theme commit
+curation (never one `git add -A`), so it costs more review time than (A). This is the single
+biggest scope decision and it changes Phase 1's cost.
+
+---
+
+## Phased plan (each phase independently fundable)
+
+### Phase 1 - CONSOLIDATE + SHIP what's built  [CHEAPEST, HIGHEST VALUE]
+The bulk of v8's value is already written. This phase makes it real.
+- Resolve the scope question (A vs B above).
+- Curate the WIP into coherent, themed commits (per-theme, individually staged - the same
+  isolation discipline used for the v7.129.4 doc-gen commit; NEVER `git add -A`).
+- Get full local-ci green on the committed tree (prime deps + rebuild dist - the lesson from
+  v7.129.4: most "failures" are environmental).
+- Reconcile the release identity: VERSION 8.0.0 vs CHANGELOG's 8.1.0; first-ever 8.x publish; a
+  genuine MAJOR. Decide the number, write the CHANGELOG major entry.
+- **Do NOT publish yet** - land it green + reviewed on the branch, PR-ready. Publishing 8.0.0 is a
+  separate, explicit, irreversible founder go (like the v7.129.4 push).
+- Cost: MODERATE (review/curation of 18k LOC + CI greening). Mostly verification, little new code.
+- Deliverable: v8 branch green, committed, coherent, PR-ready. The trust moat + SDK route SHIPPED.
+
+### Phase 2 - PostHog analytics  [NET-NEW, founder-requested]
+"log/monitor/get analytics as much as possible in PostHog."
+- Wire a PostHog sink alongside the existing OTLP/crash telemetry (opt-in, privacy-preserving -
+  loki's zero-egress posture is a documented moat; PostHog must be explicit-opt-in, never covert).
+- The SDK route already surfaces rich typed telemetry (total_cost_usd, usage, cache read/creation,
+  modelUsage, num_turns, duration_ms) - these become PostHog events cheaply.
+- Instrument: build lifecycle, gate outcomes, RARV iterations, provider/model, cost/tokens, council
+  verdicts, receipt facts, per-stage latency, failure modes.
+- Cost: MODERATE (one new sink + event mapping; reuses existing telemetry seams).
+- Deliverable: opt-in PostHog analytics across the v8 build lifecycle.
+
+### Phase 3 - jcode-informed harness intelligence  [NET-NEW, "better than jcode"]
+Adopt jcode's measured-harness discipline onto loki's trust moat (see the jcode analysis in
+[[project-v8-major-release-mandate]]). Ranked by impact/effort:
+- 3a. **Prompt-cache discipline** (HIGH impact on latency+cost, MED effort): append-only context,
+  stable prefix, MCP tools advertised up-front. The SDK route makes cache metrics visible already.
+- 3b. **Confidence-stepping / spike re-check** (HIGH, MED): force re-verify when agent confidence
+  jumps to 100 (jcode's finding: confident-after is not signal). Layers onto the completion council.
+- 3c. **Hill-climbable goal scoring** (MED, MED): score each goal's quantifiability, push back on
+  un-measurable goals. Complements the evidence gate.
+- 3d. **Auto-poke persistence** (MED, LOW): poke the loop back on incomplete todos; smart retry
+  (transient retry, non-retryable stop-to-save-tokens). Partially exists (never-stop directive).
+- Cost: LARGE (each is a real feature). Fund individually; 3a is the best first (direct latency/cost win).
+- Deliverable: measurably faster/cheaper/more-persistent loop, trust moat intact.
+
+### Phase 4 - otel 2.x + dependency modernization  [DEFERRED FROM v7.129.4]
+- The breaking @opentelemetry 2.x major bump that clears GHSA-45rx-2jwx-cxfr for real (the v7.129.4
+  patch waived it as not-reachable; here it gets genuinely fixed since major bumps belong in a major).
+- Re-verify tracing still works after the bump.
+- Founder standing directive: "always latest code, api, libraries" - audit + modernize other deps here.
+- Cost: SMALL-MODERATE (mechanical but needs tracing re-verification).
+
+### Phase 5 - MAJOR RELEASE  [IRREVERSIBLE, explicit founder go]
+- Full CLAUDE.md release workflow: 14-file version bump, CHANGELOG major entry, dashboard rebuild,
+  pre-publish validation, merge to main -> publish npm/Docker/Homebrew.
+- Post-release validation across all channels + both routes (as done for v7.129.4).
+- Cost: SMALL (mechanical, proven process from v7.129.4). The GO is the founder's.
+
+---
+
+## Recommended sequence + why
+
+1. **Phase 1 first, always.** It converts existing work into a shipped, reviewed, green branch -
+   the highest value for the least new spend, and it de-risks everything else.
+2. Then the founder picks Phase 2 (PostHog) and/or Phase 3 items (harness intelligence) to fund -
+   these are the "better in every direction" asks and each is independently costed.
+3. Phase 4 (otel/deps) bundles into whichever phase touches CI next.
+4. Phase 5 (publish) only when the founder says the accumulated phases are worth a major release.
+
+## Cost discipline (per the standing directives)
+- Ultrathink each phase's plan + advisor review before its implementation.
+- Ultracode (surgical workflow) for the implementation where parallelism pays - NOT for planning.
+- Every phase ends in a SHIPPED/committed/verified artifact, never another doc.
+- No `git add -A`; per-theme individual staging; repo-local asklokesh identity; explicit go before
+  any irreversible publish.
+
+## The one thing to decide now
+The founder's call that unblocks everything: **the CHANGELOG-vs-WIP scope question (A vs B) + confirm
+Phase 1 as the start.** Everything downstream flows from that.

package/docs/V8-OVERNIGHT-PLAN-2026-07-25.md

@@ -0,0 +1,82 @@
+# v8 overnight execution plan (2026-07-25)
+
+Autonomous session. Founder asleep ~8h. Standing authorization: make the
+architectural calls, validate everything, commit and push verified increments.
+
+## Governing principles
+
+1. **Already-exists check FIRST on every item.** It has been right 5 times out
+   of 5 this session (evidence-in-PR, offline verifier, stuck signals, signing,
+   fail-closed SDK). The research corpus is consistently more confident than
+   correct.
+2. **"Don't overwhelm users" is an architectural constraint, not a preference.**
+   Every new env var is user-facing complexity. Prefer: safe default, honest
+   degradation, structured event for operators, NO new knob. If the safe
+   behavior can be the default, make it the default.
+3. **Never mark done what is not verified.** A test that passes against the
+   pre-change code proves nothing; every behavioral change gets the
+   revert-and-confirm-it-fails treatment.
+4. **Gate on the CI verdict line, never the exit code.**
+5. **`bun run build` after every `loki-ts/src` edit** - the shipped package runs
+   `dist`, not `src`.
+
+## Order (by reversibility, not task number)
+
+| # | Item | Shape | Status |
+|---|---|---|---|
+| 11 | SDK capability-degradation event | small increment | premise mostly satisfied |
+| 10 | Phase-0 runtime-truth audit | docs from source | gates 12 |
+| 12 | Flip SDK default | TESTS first, flip only if green | conditional |
+| 18 | Typed run journal | MEASURE first | may collapse |
+| 20 | First-4-min preview | MEASURE first | may collapse |
+| 17 | Workspace isolation | interface + Local adapter | Docker = design only |
+| 23 | Helm/RBAC/SSO | real, testable offline | helm lint / kubeval |
+| 15 | npm SDK | build fully, DO NOT PUBLISH | founder gate |
+| 22 | Managed cloud | design doc only | blocked on P0 results |
+| 24 | SWE-bench RESOLUTION | DO NOT RUN | ~$950 spend, deferred |
+
+## Hard stops (will NOT do autonomously)
+
+- **#15 npm publish.** Building the package is in scope; `npm publish` is
+  outward-facing and irreversible. "Commit and push" authorized the feature
+  branch, not the public registry. The publish command is left for the founder.
+- **#24 SWE-bench RESOLUTION run.** 119 pinned instances at
+  `LOKI_BUDGET_LIMIT=8` is up to ~$950 of real spend, on a benchmark the
+  approved plan already marks DEFERRED by founder decision.
+- **Merge to main / publish 8.0.0.** Standing hard founder gate.
+
+## #12 authorization, stated precisely
+
+The approved plan says: do not flip until parity AND recovery tests pass. That
+is a CONDITIONAL authorization, so #12's real content is writing those tests
+(acceptance #1 SDK-full with the claude binary absent, #7 SIGKILL recovery, #8
+resume does not repeat irreversible actions, plus both-route parity). If they
+pass, flipping executes the founder's decision. If any fail, do not flip and
+name the blocker.
+
+## Findings that reshaped the queue
+
+**#11 is nearly done already.** `autonomous.ts:356 requireModule()` is fail-fast
+(a load-bearing module that cannot load is a fatal contract violation, not a
+silent stub). `providers.ts:559-640` is fail-closed: no CLI fallback,
+`exitCode=1` on throw, and `sawResult ? res.exitCode : 1` so a stream that never
+produced a terminal result cannot be counted as success. The SDK path's MAIN
+LOOP has no `claude`-binary dependency.
+
+**Scope stated exactly, 2026-07-26.** `providers.ts:570` delegates every
+non-mainLoop call back to `claudeProvider()`, which reaches the binary via
+`ensureClaudeHelpCache()`. But that is the `LOKI_SDK_MODE=off` path, and
+reading it alone to mean "the judge path shells out to claude" is wrong:
+under `judges`/`full`, `sdkModeDefaults()` enables all seven `JUDGE_VARS` and
+those sites have their own raw-SDK bridges. `completion-council.sh:2910` says
+so directly -- the raw-SDK vote path "needs no claude binary" (its precondition
+is bun plus the bridge), falling closed to `claude` only on an SDK miss.
+
+So under `LOKI_SDK_MODE=full` BOTH the loop and the judges have binary-free
+paths; the residual CLI dependency is off-mode delegation plus the fail-closed
+fallback. Pinned by
+`loki-ts/tests/runner/acceptance_sdk_binary_absent.test.ts`.
+
+The genuine remaining gap is OBSERVABILITY: an SDK load/stream failure is
+written into captured text, not emitted as a structured capability-degradation
+event an operator can alert on. That is the increment.

package/docs/V8-RUNTIME-TRUTH-2026-07-25.md

@@ -0,0 +1,232 @@
+# V8 Runtime Truth Audit (Phase 0)
+
+Date: 2026-07-25. Source-verified. Gates the SDK-default flip (task #12).
+
+Method: read the actual code paths, not the comments describing them. Where a
+claim concerns the Agent SDK's own capabilities, it is checked against the
+primary docs (code.claude.com), not inferred.
+
+## Executive summary
+
+The v8 SDK route is **better engineered than the competitive research assumed**
+on the two properties that matter most for trust. After the section-4 correction
+(2026-07-25) **no known capability regression blocks the flip** - what remains
+is three untested acceptance items. The gating work is TESTS, not a port.
+
+| Property | Status |
+|---|---|
+| Fail-closed on error | **SOUND** |
+| No silent CLI fallback | **SOUND** |
+| Module-resolution fail-fast | **SOUND** |
+| Rollback escape hatch | **SOUND** |
+| Structured degradation event | **ADDED 2026-07-25** |
+| Stagnation / done-signal valves | **PORTED 2026-07-24** |
+| Session continuity across iterations | **NOT A GAP** (corrected 2026-07-25; opt-in recovery parity only) |
+| Acceptance #1 / #7 / #8 | **TESTED 2026-07-26** (28 assertions, each with a verified negative control) |
+
+## 1. Route resolution (verified)
+
+`selectClaudeInvokerKind()` (`loki-ts/src/runner/providers.ts`) is pure over env,
+so the rollback path is unit-testable without spawning a process:
+
+1. `LOKI_LEGACY_BASH` truthy -> `legacy`. **The rollback always wins**, even if
+   the loop is opted-on or later becomes default-on.
+2. else `LOKI_SDK_LOOP` truthy -> `sdk`.
+3. else -> `legacy` (default-off; byte-identical to v8 as shipped).
+
+`LOKI_SDK_MODE` normalizes to `off|judges|full` on both routes with a fail-safe:
+an unknown value falls back to `off`, so the SDK can never be switched on by a
+typo. Mirrored byte-for-byte in `autonomy/lib/sdk-mode.sh` and
+`loki-ts/src/runner/sdk_mode.ts`.
+
+## 2. Fail-closed behavior (verified, and stronger than claimed)
+
+The research asserted the SDK path might "silently fall back to the CLI". It
+does not. In `providers.ts`:
+
+- The SDK is loaded by a **lazy dynamic import**, so the default-off path never
+  pays to load it.
+- A load failure (SDK missing, platform binary absent) sets `exitCode = 1`.
+  There is no CLI fallback branch to take.
+- A thrown `query()` is caught, appends the error to captured text, and leaves
+  `exitCode = 1`.
+- **`exitCode = res.sawResult ? res.exitCode : 1`** - a stream that never
+  produced a terminal result is a FAILED iteration, never counted as success.
+  This is the property that stops a broken SDK run from being read as a green
+  build.
+
+Module resolution is equally strict. `requireModule()`
+(`loki-ts/src/runner/autonomous.ts:356`) throws on an unloadable helper rather
+than substituting a stub, and the surrounding comment documents why the previous
+stubs were removed: they "degraded SILENTLY to WRONG results rather than safe
+no-ops".
+
+**Conclusion: acceptance item #3 (no silent SDK-full fallback to legacy) is
+SATISFIED in behavior.** What was missing was observability, addressed below.
+
+## 3. Capability degradation is now observable (added this session)
+
+Before: an SDK load or stream failure existed only as prose inside the captured
+output. An operator running unattended had nothing to alert on, and no way to
+distinguish "the SDK could not load" from "the model did poor work".
+
+Now: `emitSdkDegradationEvent()` appends a structured record to the SAME
+append-only `.loki/events.jsonl` stream the hook events use, with the same
+`{type, source, timestamp, payload}` envelope, so every existing consumer picks
+it up for free:
+
+```json
+{"type":"capability_degraded","source":"sdk_loop","timestamp":"...",
+ "payload":{"capability":"sdk_query","fail_closed":true,"reason":"...",
+            "tier":"...","model":"...","iteration":"..."}}
+```
+
+`fail_closed: true` is stated in the record rather than left for a reader to
+assume. Deliberately **no new env var**: this is signal an operator always
+wants, and a knob to enable your own error reporting is a knob nobody finds.
+Guarded by `loki-ts/tests/runner/sdk_degradation_event.test.ts` (5 tests),
+including the load-bearing property that it NEVER throws - a diagnostic that
+breaks the run it describes is worse than no diagnostic.
+
+## 4. Session continuity: an OPT-IN recovery gap, NOT a default regression
+
+**CORRECTED 2026-07-25.** The first version of this section called this "THE GAP
+that blocks the flip" and claimed the default route "would silently lose
+cross-iteration context that the legacy route preserves." **That claim was
+false**, and it is recorded here rather than quietly deleted because the way it
+was wrong is the same trap this audit exists to catch: it asserted a parity gap
+without first checking whether the legacy side was even turned on.
+
+What the source actually says:
+
+- `sessionStampEnabled()` returns false unless `LOKI_SESSION_STAMP=1`
+  (`claude_flags.ts:378`). **Default OFF.**
+- `resumeSessionEnabled()` returns false unless `LOKI_RESUME_SESSION=1`
+  (`claude_flags.ts:452`). **Default OFF.**
+- No shipped default sets either to `1` (grep across `*.sh`, `*.ts`, `*.json`,
+  `Dockerfile*`, excluding tests: only definitions and comments).
+- Decisively: `sessionStampArgv()` emits
+  `claudeIterationSessionUuid()` = `uuidv5("${runId}:${iteration}")`
+  (`claude_flags.ts:363-372`) - **derived from the iteration number, so a
+  DISTINCT id every iteration.** `tests/test-cli-session-v734.sh:11` states the
+  same in its own words: "a PER-ITERATION DISTINCT" session id.
+
+A per-iteration distinct `--session-id` is **correlation/tracing metadata, not
+conversation continuity.** It gives each iteration its own session rather than
+threading one. And `sessionResumeArgv()` is documented at `claude_flags.ts:445`
+as "Recovery only, never a per-iteration chain" - one resume on the first call
+of a restarted run.
+
+**Therefore: on the default path the legacy `claude -p` route is ALSO stateless
+per iteration. The SDK route loses nothing by default, and flipping it does not
+regress cross-iteration context.**
+
+The real, much smaller gap: **under opt-in `LOKI_RESUME_SESSION=1`, legacy
+performs one recovery resume after a restart and the SDK path does nothing.**
+That is opt-in recovery parity, not a default-path capability regression. It
+does not block the flip; it is a follow-up for anyone using that knob.
+
+The platform supports it whenever that port is done. Per the primary Agent SDK
+docs (code.claude.com/docs/en/agent-sdk/sessions), `query()` accepts
+`resume: <session_id>`, `forkSession: true`, and `continue: true`; session ids
+are readable from `SDKResultMessage.session_id`.
+
+Two traps for that future port, both load-bearing:
+
+1. **Do not reuse `resumeSessionEnabled()` on the SDK path.** It ends in
+   `claudeFlagSupported("--resume")`, which probes the `claude` **binary**.
+   Acceptance #1 is "SDK-full works with the binary absent" - reusing that
+   predicate makes resume silently unavailable in precisely the scenario the SDK
+   exists for. The SDK path needs the env check WITHOUT the CLI probe.
+2. **Do not write an SDK `session_id` into `.loki/state/claude-session.json`.**
+   `resumeTargetUuid()` reads `claude_session_uuid` and regex-validates it as a
+   CLI-stamped uuid; an SDK session id is a different id space from a different
+   mechanism. Sharing the field lets a restart hand one route the other's id.
+
+**And the cwd caveat** (docs, verbatim): a `resume` call from a different
+directory looks in the wrong place and silently returns a FRESH session rather
+than erroring. Any port must pin cwd and assert the resumed id EQUALS the stored
+one - a test that only checks "the call did not throw" passes against a port
+that starts fresh every time.
+
+## 5. Flip prerequisites (task #12)
+
+The approved plan authorizes the flip conditionally: only once parity AND
+recovery tests pass. Current state:
+
+| Prerequisite | Status |
+|---|---|
+| Stagnation + done-signal valves on TS route | **DONE** (2026-07-24, 10 tests, 9 fail against the pre-port stub) |
+| No silent fallback | **DONE** (verified sound; degradation event added) |
+| Session continuity parity | **NOT A BLOCKER** (corrected - see section 4; both legacy knobs default OFF and the stamp is per-iteration distinct, so there is no default-path continuity to regress) |
+| Acceptance #1 (SDK-full works with `claude` binary absent) | **DONE 2026-07-26** - `loki-ts/tests/runner/acceptance_sdk_binary_absent.test.ts` (9). Scope corrected below. |
+| Acceptance #7 (SIGKILL recoverable without corruption) | **DONE 2026-07-26** - `loki-ts/tests/runner/acceptance_sigkill_recovery.test.ts` (10). |
+| Acceptance #8 (resume does not repeat irreversible actions) | **DONE 2026-07-26** - `tests/test-acceptance-resume-idempotence.sh` (9, incl. a mutation check). **Naming collision** flagged at `claude_flags.ts:438`: Loki's own checkpoint `--resume` is a different layer from the claude-CLI session resume. #8 is the CHECKPOINT layer, so it was testable now and was never downstream of session continuity. |
+
+### What the three test files established (2026-07-26)
+
+Each has a **verified negative control** - the implementation was temporarily
+broken and the test confirmed RED before being committed - because all three
+premises already looked satisfied in source, which is precisely the condition
+under which a new test passes vacuously and proves nothing.
+
+- **#1, with the scope stated exactly.** The main agentic loop is genuinely
+  binary-free: route resolution is pure over env, the SDK loads by lazy dynamic
+  import, and no spawn/shell/flag-probe appears anywhere in
+  `sdkQueryProvider`'s own body.
+
+  **Two corrections, in opposite directions, both recorded rather than
+  quietly fixed.** The `providers.ts:570` delegation IS real: every non-mainLoop
+  call goes back to `claudeProvider()`, which reaches the binary via
+  `ensureClaudeHelpCache()`. But reading that line alone and concluding "the
+  judge path shells out to claude" was ALSO wrong, in the same way section 4's
+  original error was wrong: it described one route while a second, enabled by a
+  different switch, was sitting next to it.
+
+  `:570` is the **`LOKI_SDK_MODE=off` path**. Under `judges` or `full`,
+  `sdkModeDefaults()` turns on all seven `JUDGE_VARS`
+  (`LOKI_SDK_COUNCIL_VOTE`, `LOKI_SDK_CODE_REVIEW`, `LOKI_SDK_DONE_RECOG`,
+  `LOKI_SDK_COUNCIL_V2`, `LOKI_SDK_VOTER_AGENTS`, `LOKI_SDK_GRILL`,
+  `LOKI_SDK_PRD_ENRICH`), and those sites have their own raw-SDK bridges.
+  `completion-council.sh:2910` states it directly: the raw-SDK vote path
+  "needs no claude binary", and the precondition check is satisfied by
+  bun plus the bridge instead. It falls closed to `claude` only on an SDK miss.
+
+  **So: under `LOKI_SDK_MODE=full` both the loop and the judges have
+  binary-free paths.** The residual CLI dependency is the `off`-mode
+  delegation and the fail-closed fallback, not a hole in SDK-full. The
+  delegation boundary is pinned by a test so a future edit cannot silently
+  redefine what "SDK-full" means in either direction.
+- **#7.** Truncated state is reported `corrupted: true`, never as a clean
+  start, and the bad file is preserved for forensics - the same
+  empty-vs-invalid trap as the v7.129.5 receipt bug. A state left at `running`
+  is correctly treated as a crash and reset rather than resumed, while the
+  genuinely resumable statuses (`paused`, `interrupted`, `budget_exceeded`,
+  `stopped`) keep their counters. Orphaned `*.tmp.*` files are swept, and a
+  RECENT tmp file is deliberately left alone so the sweep cannot race a live
+  writer. No test kills a real process: the states a SIGKILL produces are
+  constructed directly, so nothing depends on winning a race.
+- **#8.** The PR guard keys on REMOTE state (`gh pr list --head --state open`),
+  not a local marker - so it survives the case that matters, a resume on a
+  fresh container where local `.loki/` is gone. The test simulates exactly that
+  wipe and asserts exactly one `gh pr create` across two completion passes;
+  the mutation check removes the guard and confirms a duplicate PR appears.
+
+**Recommendation: the test prerequisites for the flip are now MET.** All three
+acceptance items are covered with non-vacuous tests, the valves are ported, and
+no known capability regression remains. The one scope correction above (judges
+still take the CLI route) does not block the flip, because the flip changes the
+main loop only - but it does mean "SDK-full runs with no `claude` binary
+installed" is not yet true end-to-end, and should not be claimed in user-facing
+docs until the judge path is ported too.
+
+The flip itself remains a one-line change whose safety is entirely supplied by
+the tests around it, and is left as a deliberate, separately-reviewable commit.
+
+## 6. What this audit deliberately does not claim
+
+This covers the claude-provider SDK path, route resolution, fail-closed
+semantics, and session continuity. It does NOT cover: the judge/subcall path in
+detail, MCP tool loading under SDK-full, budget/effort propagation, or the
+Codex/Cline/Aider adapters. Those remain untriaged and are the natural next
+slice.

package/docs/V8-SDK-RESEARCH-RAW.md

@@ -0,0 +1,129 @@
+# Claude Agent SDK Research (TypeScript) - for the v8 Loki migration
+
+Sources: live docs `code.claude.com/docs/en/agent-sdk` + `/agent-sdk/typescript` (WebFetch, today); installed `claude` v2.1.207 `--help`; and the **actual unpacked `@anthropic-ai/claude-agent-sdk@0.3.207` tarball** (published 3 days ago) - `sdk.d.ts` (6923 lines), `package.json`, `sdk.mjs`. Every API shape below was verified against the real `.d.ts`, not just docs (WebFetch invented a few types - those are flagged UNVERIFIED). Package repo: `github.com/anthropics/claude-agent-sdk-typescript`.
+
+## THE ONE FINDING THAT REFRAMES THE FOUNDER'S PREMISE (verified, load-bearing)
+
+**The Claude Agent SDK does NOT remove the `claude` binary dependency. It IS the `claude` binary, wrapped as a subprocess.**
+
+Primary-source evidence from the 0.3.207 tarball:
+- `package.json`: `"dependencies": {}` but `"optionalDependencies"` ships **8 platform-specific native Claude Code binaries** (`@anthropic-ai/claude-agent-sdk-{linux,darwin,win32}-{x64,arm64}[-musl]@0.3.207`).
+- `sdk.mjs` imports `node:child_process` and calls `spawn()` (2 call sites, 291 refs to `claude`, 13 to `claude-code`).
+- `Options` exposes `executable?: 'bun'|'deno'|'node'`, `pathToClaudeCodeExecutable?: string`, `executableArgs`, and `spawnClaudeCodeProcess?: (o) => SpawnedProcess` - all subprocess-management knobs. There's even an `extractFromBunfs()` export whose only job is to locate the embedded `claude` binary when you `bun build --compile`.
+- Docs confirm: *"The TypeScript SDK bundles a native Claude Code binary for your platform as an optional dependency."* README: *"The Claude Code SDK is now the Claude Agent SDK."* - it's a rename of the Claude Code SDK.
+
+**Implication for the founder requirements.** Adopting `@anthropic-ai/claude-agent-sdk` gives Loki a first-class TS library, structured messages, in-process tools, and the full Claude Code harness - but it does **not** deliver the stated KEY strategic win (removing the CLI binary / "just an API key" containers). The binary is bundled instead of PATH-installed (so: no interactive login, no separate `claude` install step, no user-managed version drift - the SDK pins its own binary), but a native Claude Code executable still runs as a child process in every container. It's still "Claude Code," just vendored and spawned by your code instead of shelled out to on PATH.
+
+If "NO claude binary at all, pure API calls" is a hard requirement, the surface that actually delivers it is **`@anthropic-ai/sdk` (the Client SDK, v0.111.0)** - pure HTTPS to `api.anthropic.com`, zero binary - but then Loki owns the agent loop, tools, context management, and permissions itself (which RARV-C/run.sh largely already does). Or **Managed Agents** (Anthropic hosts the loop + sandbox; REST only). This is the real architectural fork; recommend surfacing it to the founder before committing.
+
+---
+
+## 1. Core primitives (verified against `sdk.d.ts`)
+
+**Entry point - `query()` (sdk.d.ts:2527):**
+```ts
+export declare function query(_params: {
+ prompt: string | AsyncIterable<SDKUserMessage>;
+ options?: Options;
+}): Query;
+```
+- `prompt: string` = one-shot. `prompt: AsyncIterable<SDKUserMessage>` = streaming-input mode (enables mid-session control methods).
+- Returns a `Query` (below); you `for await (const message of query(...))` to drive the agentic loop. The SDK runs the whole Reason→Act tool-use loop internally - you don't write the `while stop_reason === 'tool_use'` loop (that's the explicit contrast the docs draw vs the Client SDK).
+
+**`Query` interface (sdk.d.ts:2230) - `extends AsyncGenerator<SDKMessage, void>`** with control methods (all verified present):
+`interrupt()`, `setPermissionMode(mode)`, `setModel(model?)`, `setMaxThinkingTokens(n, display?)`, `applyFlagSettings(settings)`, `supportedModels()`, `supportedAgents()`, `supportedCommands()`, `mcpServerStatus()`, `setMcpServers()`, `reconnectMcpServer()`, `toggleMcpServer()`, `rewindFiles(userMessageId, {dryRun?})`, `streamInput(stream)`, `initializationResult()`, `reinitialize()`, `close()`. Mid-session setters (`setModel`, `setPermissionMode`, `applyFlagSettings`) work **only in streaming-input mode**.
+
+**Custom tools - `tool()` (sdk.d.ts:6745) + `createSdkMcpServer()` (sdk.d.ts:467):**
+```ts
+export declare function tool<Schema extends AnyZodRawShape>(
+ _name, _description, _inputSchema: Schema,
+ _handler: (args: InferShape<Schema>, extra) => Promise<CallToolResult>,
+ _extras?: { annotations?: ToolAnnotations }
+): SdkMcpToolDefinition<Schema>;
+
+export declare function createSdkMcpServer(_options: CreateSdkMcpServerOptions): McpSdkServerConfigWithInstance;
+```
+Tools are **in-process** (Zod-schema'd TS functions), bundled into an SDK MCP server, passed via `options.mcpServers`. This is how Loki would expose its own tools (queue, memory, council) to the agent without a separate MCP process - a genuine enhancement over shelling out.
+
+**Built-in tools (no implementation needed):** Read, Write, Edit, Bash, Monitor, Glob, Grep, WebSearch, WebFetch, AskUserQuestion, Agent (subagent invocation), + MCP. Gated by `allowedTools`/`disallowedTools`/`tools`.
+
+**Subagents / multi-agent - `options.agents: Record<string, AgentDefinition>` (sdk.d.ts:1327):**
+```ts
+type AgentDefinition = {
+ description: string; prompt: string;
+ tools?: string[]; disallowedTools?: string[];
+ model?: string; // alias, full id, or "inherit"
+ mcpServers?: AgentMcpServerSpec[]; skills?: string[];
+ maxTurns?: number; background?: boolean;
+ memory?: 'user'|'project'|'local';
+ effort?: 'low'|'medium'|'high'|'xhigh'|'max'|number;
+ permissionMode?: PermissionMode;
+ initialPrompt?: string; /* + experimental fields */
+};
+```
+Subagents invoked via the `Agent` tool (include `"Agent"` in `allowedTools` to auto-approve). Messages from a subagent carry `parent_tool_use_id` so you can attribute them. This maps cleanly onto Loki's dev-fleet/council pattern - but note it's **one level deep** and runs subagents within the same host process, unlike Loki's current parallel-Task fan-out.
+
+**Memory/context:** three layers. (a) `CLAUDE.md`/`.claude/` loaded via `settingSources` (`'user'|'project'|'local'`). (b) Automatic context compaction is built into the Claude Code harness the SDK spawns. (c) `AgentDefinition.memory` + Skills (`.claude/skills/*/SKILL.md`, `options.skills`). There is no separate vector-memory primitive - Loki's `memory/` Python package has no SDK equivalent; you'd wire it in as SDK MCP tools or hooks.
+
+**Hooks:** `options.hooks` - `PreToolUse`, `PostToolUse`, `Stop`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, etc., as in-process callbacks (validate/block/transform/log). Good fit for Loki's quality gates and telemetry.
+
+## 2. Session continuity (verified)
+- `options.resume?: string` (session id), `options.continue?: boolean` (most recent), `options.forkSession?: boolean`, `options.resumeSessionAt?: string` (resume at a specific message UUID), `options.sessionId?: string` (pin a UUID), `options.persistSession?: boolean`.
+- Session id comes from the `system`/`init` message (`message.session_id`) on the first query; pass it as `resume` on the next.
+- Storage: **JSONL on your filesystem** (docs confirm; helpers `listSessions()`, `getSessionMessages()`, `getSessionInfo()`, `renameSession()`, `tagSession()`). `options.sessionStore` can mirror transcripts to an external backend.
+- Maps to the CLI's `--resume`/`--session-id`/`--continue`/`--fork-session`/`--resume-session-at` (all present in `claude --help`). This is a strict superset of Loki's current CLI-flag resume usage.
+
+## 3. Structured output (verified - direct CLI `--json-schema` equivalent)
+```ts
+outputFormat?: OutputFormat; // sdk.d.ts:1686
+type OutputFormat = JsonSchemaOutputFormat; // :2016
+type JsonSchemaOutputFormat = { type: 'json_schema'; schema: Record<string, unknown> }; // :898
+```
+Result lands on **`SDKResultSuccess.structured_output?: unknown`** (sdk.d.ts). There's a dedicated error subtype `error_max_structured_output_retries`, so the harness retries to satisfy the schema. This is the exact analog of the CLI's `--json-schema` flag. **Yes, fully supported.**
+
+## 4. Budget / effort / model / fallback (verified - direct CLI-flag parity)
+| Need | Agent SDK option | CLI flag |
+|---|---|---|
+| Budget cap | `maxBudgetUsd?: number` → error subtype `error_max_budget_usd` | `--max-budget-usd` |
+| Effort | `effort?: 'low'\|'medium'\|'high'\|'xhigh'\|'max' \| number` (also runtime `applyFlagSettings({effortLevel})`) | `--effort` |
+| Model | `model?: string` (alias/full id; runtime `setModel()`) | `--model` |
+| Fallback | `fallbackModel?: string` | `--fallback-model` |
+| Turn cap | `maxTurns?: number` → `error_max_turns` | (SDK/`--max-turns`) |
+| Task budget | `taskBudget?: { total: number }` → sent as API `output_config.task_budget` + beta header `task-budgets-2026-03-13` | - |
+| Thinking | `thinking?: ThinkingConfig` (`maxThinkingTokens` deprecated) | - |
+| Betas | `betas?: SdkBeta[]` - only `'context-1m-2025-08-07'` is valid | `--betas` |
+
+Result message carries `total_cost_usd`, `usage` (NonNullableUsage), `modelUsage: Record<string, ModelUsage>`, `num_turns`, `duration_ms/api_ms`, `permission_denials` - richer cost/telemetry than parsing CLI stdout. **Every CLI control Loki uses has a typed SDK option.**
+
+## 5. The "outcome" / Managed-Agents primitive vs RARV-C (honest assessment)
+There is **no `outcome` primitive in the Agent SDK.** The closest thing is the SDK's built-in agent loop bounded by `maxTurns` / `maxBudgetUsd` / `taskBudget` / structured-output retries - an *effort/budget-bounded* loop, **not** an iterate-until-a-grader-says-done loop.
+
+The grader-driven "iterate until an independent rubric passes" primitive is **Managed Agents' Outcomes** (`user.define_outcome` + rubric + `max_iterations`, with `span.outcome_evaluation_*` events and a separate grader model) - a **different product** (hosted REST API, `client.beta.sessions.*` on `@anthropic-ai/sdk`), not the Agent SDK. Per the docs' own comparison table, Managed Agents runs the loop + sandbox on Anthropic infra; the Agent SDK runs in your process.
+
+**Honest verdict:** RARV-C already *is* Loki's home-grown Outcomes equivalent (iterate → grade via council → close). Neither the Agent SDK nor Managed Agents Outcomes maps onto it 1:1. Do **not** fabricate a wiring where the SDK "provides" RARV-C - the SDK provides a bounded tool-use loop; the grader/council closure stays Loki's. Managed Agents Outcomes is the nearest hosted analog but would mean re-platforming completion onto Anthropic's grader (out of scope, and would cede Loki's council).
+
+## 6. Runtime / auth / cost (verified)
+- **Runtime:** Node, Bun, or Deno - `executable?: 'bun'|'deno'|'node'`. TS SDK bundles the native binary per platform (no separate `claude` install). Python variant (`claude-agent-sdk`) needs Python ≥3.10.
+- **Auth:** `ANTHROPIC_API_KEY` (docs). Also Bedrock (`CLAUDE_CODE_USE_BEDROCK=1`), Claude Platform on AWS (`CLAUDE_CODE_USE_ANTHROPIC_AWS=1` + `ANTHROPIC_AWS_WORKSPACE_ID`), Vertex (`CLAUDE_CODE_USE_VERTEX=1`), Foundry (`CLAUDE_CODE_USE_FOUNDRY=1`). **Anthropic explicitly prohibits third-party products from using claude.ai login / subscription rate limits via the Agent SDK - API-key auth only.** No interactive login (a real improvement over the CLI's OAuth `claude auth`).
+- **Cost:** standard per-token API billing (surfaced live as `total_cost_usd` on the result). Same underlying `/v1/messages` cost as the CLI - the CLI's cost is API cost; the SDK doesn't change the cost model, it just reports it structurally.
+
+## 7. Honest gaps (what each does that the other doesn't)
+
+**Agent SDK gains over Loki's `claude -p` wrapper:**
+- Typed streaming messages (`SDKMessage` union) instead of stdout parsing; structured `SDKResultSuccess`/`SDKResultError` with cost/usage/`structured_output`.
+- In-process custom tools (`tool()`), in-process hooks, programmatic subagents (`agents`), programmatic MCP.
+- Mid-session control (`interrupt`, `setModel`, `setPermissionMode`, `applyFlagSettings`, `streamInput`, `rewindFiles`) - no equivalent when you shell out to `claude -p`.
+- `startup()`/`WarmQuery` for low-latency warm spares.
+
+**Provider-agnostic caveat (per founder's constraint):** the Agent SDK is Anthropic/Claude-Code-specific. It does NOT give Loki Codex/Cline/Aider. Those routes need their own story (the OpenAI-compatible layer, explicitly out of scope here). Note the Agent SDK *can* target Bedrock/Vertex/Foundry via env vars, but that's still Claude models.
+
+**What the Agent SDK does NOT do / gaps vs the premise:**
+- **Does not remove the native binary** (finding above) - it spawns a bundled Claude Code executable per platform. "Library, just an API key, no binary" is only true of `@anthropic-ai/sdk` (Client SDK).
+- No grader/Outcomes primitive (RARV-C stays Loki's; §5).
+- No built-in vector memory (Loki's `memory/` package has no SDK analog; wire via MCP/hooks).
+- Only one valid `SdkBeta` (`context-1m-2025-08-07`) - other API betas (fast-mode, compaction, etc.) aren't first-class SDK options.
+- WebFetch-only claims I could NOT verify in the `.d.ts` and mark **UNVERIFIED**: the exact `SDKAssistantMessage`/`SDKPartialAssistantMessage` content-block shapes, `ThinkingConfig` as a 3-variant union, and `CanUseTool`'s full options object. The `thinking?: ThinkingConfig` field, `includePartialMessages?: boolean`, and `canUseTool?: CanUseTool` fields **are** confirmed present; their inner shapes should be re-read from `sdk.d.ts` before you write code against them.
+
+Verified type-def file (kept for the implementer): `/private/tmp/claude-501/-Users-lokesh-git-lokimode-anthropic/8db286db-3006-49f5-9dc6-cb241e559d45/scratchpad/package/sdk.d.ts` (line refs above are from this file, v0.3.207).
+
+**Recommendation to fold into the v8 plan:** the migration decision is not "Agent SDK vs bash" - it's a three-way fork (Agent SDK = bundled binary + full harness; Client SDK = pure API, Loki owns the loop; Managed Agents = hosted loop+sandbox+Outcomes). Only the Client SDK path delivers the founder's stated "no binary, API-key-only container" win, at the cost of re-owning the loop Loki mostly already owns. Surface this explicitly before locking scope.