Juliusolsson05 · Jul 7, 2026 · Jul 6, 2026 · Jul 6, 2026 · Jul 6, 2026 · Jul 6, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -17,3 +17,10 @@ A good comment answers questions like:
 Don't bother explaining *what* the code does — that's what reading the code is for. Explain *why it exists*, *why it's shaped this way*, and *what would make it wrong*.
 
 Make agentic development and decision-making **transparent in the diff**, not in a doc that drifts.
+
+## Directory conventions
+
+Two top-level folders look superficially similar but mean very different things. Do not mix them.
+
+- `vendor/` — read-only **source code references** kept locally so future-you can grep the original implementation of something we wrap or interoperate with. Never imported, never built, never shipped. Examples: `claude-code-src/`, vendored upstream checkouts for bug-bisection.
+- `third_party/` — pinned **runtime artifacts** that we ship inside packaged Agent Code (or that the release pipeline fetches at build time). Each tool gets its own directory with a `manifest.json` (version + per-arch sha256 + URL template), `README.md`, `LICENSE.md`, and a `.gitignore` that keeps `cache/` and `build/` out of git. Binaries are NEVER committed — the manifest plus `scripts/runtime-tools/<tool>` is the source of truth, and version bumps are one-file PRs against `manifest.json`. Examples: `third_party/mitmproxy/`, `third_party/tmux/`. See issues #119 and #120 for the full bundling plan.
diff --git a/CODEX.md b/CODEX.md
diff --git a/MANIFESTO.md b/MANIFESTO.md
@@ -32,10 +32,6 @@ The whole app is built for efficient development. All terminals are tmux-persist
 
 ## Structure
 
-One of the principles I understood early is that getting open-source contributors on board with something like this is hard. So Agent Code is dependent on 4 separate projects that it imports as packages, all more broadly scoped, which will hopefully attract more open-source attention.
-
-## Structure
-
 One of the principles I understood early is that getting open-source contributors on board with something like this is hard. So Agent Code is dependent on 4 separate projects that it imports as packages — all more broadly scoped, which will hopefully attract more open-source attention.
 
 **1. Headless Claude Code and Codex**

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,27 @@
+# Agent Code docs
+
+Layout and status conventions. Superseded/closed material moves to `archive/`
+and carries a `Status:`/`ARCHIVED` header — a doc without one is meant to be
+live.
+
+## Live
+
+- **`rendering/`** — the current rendering engine. `rendering-rewrite-plan-2026-07.md`
+  is canonical; `residue-plan-2026-07.md` and `session-recording-plan-2026-07.md`
+  are its live follow-ons; `legacy-deletion-manifest.md` is the cutover contract;
+  `rendering-knowledge-dump.md` is the evidence bible. `research-2026-07/` holds
+  the supporting research (rewrite research at the top level, the
+  session-recording research under `session-recording/`).
+- **`design/`** — living subsystem design (conditions, ghost system).
+- **`plans_and_ideas/`** — active/near-term plans and idea notes.
+- **`superpowers/`** — dated planning space: `plans/` (feature/fix plans) and
+  `specs/` (design specs). Accumulates by date; a plan carries a `Status:` header
+  once it ships or is superseded.
+- **`command-style.md`** — command-authoring conventions.
+- **`screenshots/`** — README assets.
+
+## Archived (`archive/`)
+
+- **`codex-rewrite-render/`** — the pre-rewrite rendering notebook (superseded).
+- **`issue-investigations/`** — investigations for issues now closed.
+- **`audit-plans/`** — the deep-audit roadmap and its completed execution logs.
diff --git a/.../audit-plans/deep-audit-master-roadmap.md → .../audit-plans/deep-audit-master-roadmap.md b/.../audit-plans/deep-audit-master-roadmap.md → .../audit-plans/deep-audit-master-roadmap.md
diff --git a/...g-dictation-release-implementation-log.md → ...g-dictation-release-implementation-log.md b/...g-dictation-release-implementation-log.md → ...g-dictation-release-implementation-log.md
diff --git a/...patch-shell-cleanup-implementation-log.md → ...patch-shell-cleanup-implementation-log.md b/...patch-shell-cleanup-implementation-log.md → ...patch-shell-cleanup-implementation-log.md
diff --git a/...onditions-weirdness-implementation-log.md → ...onditions-weirdness-implementation-log.md b/...onditions-weirdness-implementation-log.md → ...onditions-weirdness-implementation-log.md
diff --git a/...pc-shared-contracts-implementation-log.md → ...pc-shared-contracts-implementation-log.md b/...pc-shared-contracts-implementation-log.md → ...pc-shared-contracts-implementation-log.md
diff --git a/...chestration-runtime-implementation-log.md → ...chestration-runtime-implementation-log.md b/...chestration-runtime-implementation-log.md → ...chestration-runtime-implementation-log.md
diff --git a/...headless-boundaries-implementation-log.md → ...headless-boundaries-implementation-log.md b/...headless-boundaries-implementation-log.md → ...headless-boundaries-implementation-log.md
diff --git a/docs/codex-rewrite-render/README.md → docs/archive/codex-rewrite-render/README.md b/docs/codex-rewrite-render/README.md → docs/archive/codex-rewrite-render/README.md
@@ -1,3 +1,10 @@
+> **ARCHIVED / SUPERSEDED (2026-07-07).** This was the first-principles working
+> notebook for the feed-rendering rewrite. It has been fully absorbed into the
+> canonical plan `docs/rendering/rendering-rewrite-plan-2026-07.md` and its
+> research digest `docs/rendering/research-2026-07/rewrite-notebook-extraction.md`.
+> Kept for history; reads present-tense but describes the OLD `deriveFeedRenderModel`
+> approach, which the ownership-ledger pipeline (`src/renderer/src/rendering/`) replaced.
+
 # Codex Render Rewrite Notes
 
 This directory is the working notebook for rebuilding feed rendering from first principles while keeping live streaming.

diff --git a/...x-rewrite-render/feed-render-item-plan.md → ...x-rewrite-render/feed-render-item-plan.md b/...x-rewrite-render/feed-render-item-plan.md → ...x-rewrite-render/feed-render-item-plan.md
diff --git a/...codex-rewrite-render/feed-ui-rendering.md → ...codex-rewrite-render/feed-ui-rendering.md b/...codex-rewrite-render/feed-ui-rendering.md → ...codex-rewrite-render/feed-ui-rendering.md
diff --git a/...e-render/first-principles-render-model.md → ...e-render/first-principles-render-model.md b/...e-render/first-principles-render-model.md → ...e-render/first-principles-render-model.md
diff --git a/...-rewrite-render/headless-channel-model.md → ...-rewrite-render/headless-channel-model.md b/...-rewrite-render/headless-channel-model.md → ...-rewrite-render/headless-channel-model.md
diff --git a/...rite-render/renderer-runtime-ingestion.md → ...rite-render/renderer-runtime-ingestion.md b/...rite-render/renderer-runtime-ingestion.md → ...rite-render/renderer-runtime-ingestion.md
diff --git a/...odex-rewrite-render/submit-queue-debug.md → ...odex-rewrite-render/submit-queue-debug.md b/...odex-rewrite-render/submit-queue-debug.md → ...odex-rewrite-render/submit-queue-debug.md
diff --git a/...ewrite-render/upstream-codex-rendering.md → ...ewrite-render/upstream-codex-rendering.md b/...ewrite-render/upstream-codex-rendering.md → ...ewrite-render/upstream-codex-rendering.md
diff --git a/...vestigations/147-multi-instance-policy.md → ...vestigations/147-multi-instance-policy.md b/...vestigations/147-multi-instance-policy.md → ...vestigations/147-multi-instance-policy.md
@@ -1,3 +1,5 @@
+> **ARCHIVED (2026-07-07).** The investigated issue is closed; kept as history.
+
 # Issue #147: Multiple Agent Code Instances
 
 ## Issue Summary

diff --git a/...-investigations/152-dispatch-terminals.md → ...-investigations/152-dispatch-terminals.md b/...-investigations/152-dispatch-terminals.md → ...-investigations/152-dispatch-terminals.md
@@ -1,3 +1,5 @@
+> **ARCHIVED (2026-07-07).** The investigated issue is closed; kept as history.
+
 # Issue 152: Add terminal sessions to Dispatch Mode
 
 ## Issue summary

diff --git a/docs/issue-investigations/154-undo-close.md → ...ve/issue-investigations/154-undo-close.md b/docs/issue-investigations/154-undo-close.md → ...ve/issue-investigations/154-undo-close.md
@@ -1,3 +1,5 @@
+> **ARCHIVED (2026-07-07).** The investigated issue is closed; kept as history.
+
 # Issue 154: Extend Undo Close History and Retention
 
 ## Issue Summary

diff --git a/...tions/180-181-rendered-link-activation.md → ...tions/180-181-rendered-link-activation.md b/...tions/180-181-rendered-link-activation.md → ...tions/180-181-rendered-link-activation.md
@@ -1,3 +1,5 @@
+> **ARCHIVED (2026-07-07).** The investigated issue is closed; kept as history.
+
 # Issues #180 and #181: Rendered Link Activation
 
 ## Issue Summaries

diff --git a/docs/rendering/legacy-deletion-manifest.md b/docs/rendering/legacy-deletion-manifest.md
@@ -0,0 +1,92 @@
+# Legacy Rendering — Deletion Manifest
+
+The contract for the complete strip-out of the old rendering system. The old
+code is NOT deleted early: Stage 2 shadow mode diffs the new ledger against
+the live legacy renderer, so the legacy path must keep working until cutover.
+This manifest is what "starting fresh" means in practice — every legacy file
+is enumerated with its fate and its deletion point, so nothing survives by
+accident. LOC figures from the knowledge dump's Blast Radius appendix
+(measured 2026-05-22; drifted slightly since, fates unchanged).
+
+Legend: **DELETE** = removed entirely · **GUT** = file stays, ownership logic
+removed (becomes dumb/plumbing) · **ABSORB** = behavior re-encoded in the
+ledger, then source deleted · **KEEP** = not ownership code, survives as-is.
+
+## Cutover status — 2026-07 (the ledger is now the sole decision core)
+
+The cutover shipped in two slices because a late discovery split it: the
+**remote phone client** (`src/remote-client/`) is a SECOND `<Feed>` consumer
+that was mounting the legacy `deriveFeedRenderModel` path. The manifest below
+was written assuming one consumer, so "delete deriveFeedRenderModel" was
+blocked until the phone also fed the ledger.
+
+**DONE (this cutover PR):**
+- The ledger producer (`useLedgerFeedItems`) is UNCONDITIONAL. The
+  `AGENT_CODE_RENDER_PIPELINE` flag + its whole probe are gone; so is
+  `AGENT_CODE_RENDER_SHADOW` and the `renderShadowEnabled`/
+  `renderPipelineEnabled` dev-debug plumbing.
+- **The phone was migrated**: `remote/ui/SessionView.tsx` builds a minimal
+  SessionRuntime view (empty ghost plane — the phone has no optimistic echo)
+  and drives the SAME `useLedgerFeedItems`, so it now passes
+  `renderItemsOverride` like the desktop.
+- `deriveFeedRenderModel` + its sort/visibility helpers + `FeedRenderModelInput`
+  **DELETED** from `renderModel.ts`. Feed's legacy branch **DELETED** — it maps
+  the ledger's items unconditionally.
+- Shadow subsystem **DELETED**: `shadow/useRenderShadow.ts` and the
+  `shadowParity.test.ts` CI diff. `shadow/shadowDiff.ts` KEPT (pure diff util —
+  bundleCorpus/recordingCorpus still assert ledger output through it).
+
+**STILL ALIVE — the block-level un-collapse slice (next PR):** the view bridge
+still COLLAPSES the ledger's block-level semantic rows back into turn-level
+items so `SemanticStreamingTurn` can render them. Killing that component (and
+with it ghost rule 3, `selectMergedEntries` as Feed's entries source, and
+`committedClaudeMessageTurnIds`) requires the ledger to own live turns
+block-by-block through the shared registry dispatch — the hardest slice, and
+the one that needs live visual verification the turn-grain corpus can't give.
+Until then the completeness grep below still returns `SemanticStreamingTurn` /
+`selectMergedEntries` / `committedClaudeMessageTurnIds` hits BY DESIGN;
+`deriveFeedRenderModel` / `buildSemanticRenderUnits` are already clean.
+
+## Deleted at Stage 3 cutover (the big reviewed PR)
+
+| file | phys LOC | fate | notes |
+|---|---:|---|---|
+| `features/feed/ui/semantic/StreamingTurn.tsx` | 149 | **DELETE** | atomically with ghost rule 3 (plan D6) — never one without the other |
+| `features/feed/model/renderModel.ts` | 430 | **DELETE** | replaced by ledger + view model; `committedClaudeMessageTurnIds` naming lie dies with it |
+| `features/feed/ui/semantic/renderUnits.ts` | 359 | **ABSORB** | committed-ownership skips → ledger reasons; collapsed-activity policy → view layer |
+| `workspace/mergedEntries.ts` | ~200 | **ABSORB** | five-rule predicate → ledger ghost decisions; the entries pre-pass merge dies |
+| `workspace/semantic/foldEvent.ts` | 987 | **GUT→ABSORB** | reducer stays (events→turn state); ALL ownership/suppression gates + fold policies move to ledger candidate rules; yield hatches become policy |
+| `features/feed/ui/semantic/BlockRow.tsx` | 495 | **GUT** | becomes dumb rows; hardcoded provider dispatch replaced by the registry (same one committed rows use); all suppression branches deleted |
+| `features/feed/ui/Feed.tsx` | 946 | **GUT** | maps view-model rows once; all plane/ownership/debug-derivation logic deleted; scroll/lazy stay per migration hazards |
+| `features/feed/ui/rows/Block.tsx` | 204 | **GUT** | dispatch stays, ownership guards deleted |
+| `workspace/ghosts.ts` | ~530 | **GUT** | minting/reconcile/persist stay (bookkeeping); render-side selection is ledger's |
+| legacy `visible_rows`-only debug derivation | — | **DELETE** | replaced by ownership_decision serialization (visible_rows stays as aggregate) |
+
+## Deleted during Stage 1 (already superseded, no shadow value)
+
+- old fold-policy literals already replaced on main (#415) — nothing to do
+- `workspace/queueInvariants.ts` — **ABSORB** into ledger queue-handoff rules
+  at cutover, not before (echo providers still run through it live)
+
+## KEEP (not ownership code)
+
+| file | LOC | why it lives |
+|---|---:|---|
+| `markdown/Prose.tsx`, `MarkdownComponents.tsx`, remark plugins | ~250 | TextProse/StreamingProse split is load-bearing (migration hazard) |
+| `lib/streamingWriteInput.ts` | 206 | Write-scanner, pure detector — feeds the view layer |
+| `WorkIndicator.tsx` + hints | 305 | phase surface; consumes work candidates |
+| row components (ToolUseRow/ToolResultRow/ConversationRow/Claude+Codex+OpenCode rows) | ~1600 | become dumb rows; only their embedded ownership guards die (counted under GUT above) |
+| `lib/helpers.ts` committed text/tool index builders | 386 | logic ABSORBED into ownership.ts; file gutted at cutover |
+| headless packages | ~11k | contract-tested, never rewritten (plan §10) |
+
+## Verification of completeness at cutover
+
+FULL completeness (the final block-level un-collapse PR) is reached when:
+`grep -rn "SemanticStreamingTurn\|selectMergedEntries\|deriveFeedRenderModel\|committedClaudeMessageTurnIds\|buildSemanticRenderUnits" src/` returns only
+hits inside `src/renderer/src/rendering/` history comments — i.e. every entry
+in the DELETE/ABSORB tables above is gone or gutted, with its fixture green.
+
+As of the 2026-07 cutover (see status section up top) `deriveFeedRenderModel`
+and `buildSemanticRenderUnits` are already clean; the remaining three tokens
+(`SemanticStreamingTurn`, `selectMergedEntries`, `committedClaudeMessageTurnIds`)
+stay until the block-level un-collapse slice retires `SemanticStreamingTurn`.
diff --git a/docs/rendering/rendering-rewrite-plan-2026-07.md b/docs/rendering/rendering-rewrite-plan-2026-07.md
@@ -11,6 +11,65 @@ wins; where this one is silent, the dump's Non-Negotiable Rules apply.
 
 Read this first. Then read `research-2026-07/` for the receipts.
 
+## Stage 1 progress (updated 2026-07-06, integration branch)
+
+Landed (slices 1-11, PRs #424-#437 into `integration/rendering-pipeline`):
+ledger core (types / ordering law / ownership / identity stability), committed
+collector with the #338 synthetic-user filter, ghost five-rule predicate with
+the 10-case matrix and failed-fix regressions, semantic collector with the
+#345 compaction kill, local collectors + optimistic→committed handoff,
+unknown-behavior registry with structural redaction, ghost plane wired into
+the ledger pass (#435), the runtime→collector adapter — the shadow seam —
+with ghost collector, optimistic partition, plane-level reference stability,
+and compile-time seam assertions against real runtime types (#436), the
+fold-policy yield-hatch absorption (`policy/foldPolicy.ts` — the two
+proxy-literal hatches from legacy foldEvent encoded as policy data with
+parity tests) and six end-to-end fixtures: buried-prompt-239,
+dead-committed-channel-159, opencode-interleave-87f0eeef, the ghost matrix,
+sidecar-tail-ghost, and queue-handoff-race (#437). Suite: 67 pipeline tests.
+
+**Stage 1 is COMPLETE.** (Unknowns plumbing note: the registry exists and
+`LedgerInput.unknowns` passes through; POPULATING it from real IPC events
+is a shadow-seam concern — unknowns are discovered live, not in fixtures.)
+
+### Stage 2/3 progress (updated 2026-07-07, through PR #447)
+
+Landed since the Stage 1 wrap (slices 12-17 + triage, PRs #439-#447):
+- **Shadow mode** (#439): `AGENT_CODE_RENDER_SHADOW=1` runs adapter+ledger
+  beside the legacy renderer in TileLeaf; `shadow/shadowDiff.ts` normalizes
+  both to comparable units (rows by id, turns by turnId); divergences land
+  on `globalThis.__agentCodeRenderShadow` (ring of 50) + one console.warn
+  per signature. Shadow parity suite (#441) runs the same diff in CI.
+- **Bundle corpus** (#444-#445, #447): 46 fixtures extracted from the
+  manual debug-bundle archive (`scripts/extract-rendering-fixtures.mjs`,
+  triage rules in `scripts/triage-rendering-fixtures.mjs`) — each is a
+  real captured rendering failure with the legacy renderer's ACTUAL
+  painted rows as ground truth. `bundleCorpus.test.ts` asserts the diff
+  matches checked-in triage exactly (bless via AGENT_CODE_CORPUS_BLESS=1).
+  State: 0 untriaged. Corpus catches so far: opencode blockless-text turns
+  invisible (fixed #444); system/compact_boundary rows dropped (fixed
+  #445); committed tool-ownership mining gap + dangling tool chip
+  (confirmed #447, fixes queued).
+- **View bridge** (#443): `view/ledgerFeedItems.ts` maps ledger rows to
+  legacy FeedRenderItems — cutover swaps the decision core, row components
+  survive. **Cutover flag** (#446): `AGENT_CODE_RENDER_PIPELINE=1` makes
+  Feed paint from the ledger via `renderItemsOverride`; flag off is
+  byte-identical legacy.
+
+**Soak instructions (the current gate):** run daily work on this branch
+with `AGENT_CODE_RENDER_PIPELINE=1 AGENT_CODE_RENDER_SHADOW=1` across all
+three providers. Watch for `[render-shadow] divergence` and
+`[render-pipeline] dropped candidates` in the console; every divergence
+class gets triaged into the corpus. Exit = a week of real use with no
+untriaged class.
+
+Remaining before the main merge: the two #447-confirmed collector fixes
+(committed tool-ownership mining; dangling tool chip), extractor v2
+(codex rollout→Entry mapping unlocks the 122 extraction-gap verdicts),
+the soak above, then the final cutover slice — SemanticStreamingTurn +
+ghost rule 3 deleted atomically, deletion-manifest grep sweep, flag
+default-on — and the reviewed integration→main PR (draft #442).
+
 ---
 
 ## 0. Why this plan exists and what it refuses to be