pmx-canvas 0.8.2 → 0.9.0

package/docs/plans/plan-009-tech-debt-backlog.md

@@ -8,6 +8,12 @@ Each item is tagged by shape: **project** (multi-day, own plan/PR), **decision**
 
 ## Decision analysis (2026-07-08, maintainer-approved)
 
+**SDK clarification, 2026-10-15:** the historical "no further collapse" conclusion below is
+superseded by [vision move 6b](../product-vision-2026-09.md#6b-generate-every-surface-from-the-registry-l-two-releases--pending-the-maintainers-decision).
+The local SDK may remain synchronous while sharing mutation-policy checks. All supported
+writers must converge on the relevant policy and commit guarantees; asynchronous durable
+completion is a separate contract decision, not a prerequisite for fixing lock parity.
+
 The remaining items were re-analyzed with pros/cons and tiered; the maintainer approved this ordering:
 
 - **Tier 1 (do):** CLI raw fetches → operation invoker **together with** the H3 parser/module split (same file, one project); H7 test coverage **as a prerequisite** for any client refactor; M2 AX-bridge dedup (first client task after H7); the M8 flake subset (mock the Excalidraw network tests, share `getAvailablePort`, Playwright `retries`/`forbidOnly`, `e2e-cli` into CI). *C1b done (2026-07-08):* all 60 raw `api()` calls migrated onto the invoker (9-agent verified mapping; `webartifact.build` gained `errorBodyAsResult`; batch failure prints the envelope + exits 1; the `api()` helper is deleted; two deliberate raw `fetch` sites remain — binary screenshot, SSE watch). *H3 module split done (2026-07-09):* `agent.ts` is a 227-line entry over `src/cli/shared.ts` (cycle-free core: registry, parser, transport) + 11 `src/cli/commands/*` domain modules, moved byte-identically; ax-parity reads the whole cli tree. **Parser sub-item reshaped:** `parseFlags`/`BOOL_FLAGS` is now single-sited in shared.ts; `index.ts` keeps its intentionally tiny fixed-flag launcher reader (different domain — server launch, not agent commands). The spec-driven per-command flag parser (`defineCommand`) remains the ideal but is a redesign of all 83 command surfaces — deferred to a future CLI UX change, not worth manufactured churn now.
@@ -92,3 +98,376 @@ Recorded while the redesign's phases land so nothing rides in silently. The rede
 | Agents can resolve their own gates | Pre-existing design question surfaced by the session panel: `ax.approval.resolve` accepts any caller, so an agent could approve its own gate over HTTP/MCP. The panel and the `held` TTL path assume the human answers. Either gate `resolve` on the workbench marker (like the scope fence) or document it as a cooperating-agent contract; decide before the next adapter ships. |
 | Batch never carries `fromWorkbench` | `canvas.batch` inner dispatches are always agent writes (the browser never uses batch), so the scope fence and presence treat them as such. Holds by construction today; if the client ever adopts batch, the marker must thread through `ops/batch.ts`. Comment at the dispatch site. |
 | Presence registry is a second single-slot listener family | `setSessionStartListener` / `setSessionEndListener` / `setEmitter` on `agentPresence` follow architecture rule 8 (owned by `server.ts`). If a third consumer ever needs session lifecycle (e.g. an audit log), fan out inside the existing registration — do not add a competing one. |
+
+## Wave 3 maintainability review (2026-10-11)
+
+Scope: remaining Wave 3 changes against the published foundation, the preceding
+`Sweep tech debt before 0.9.0` commit, and the next stages in `docs/design.md` and
+`docs/product-vision-2026-09.md`. This is a source/data-flow review with disposable
+scale measurements, not an exhaustive re-audit of every historical row above.
+The owner requested self-review, not Oracle. Stabilization evidence is in plan 018.
+
+**Fixed in this batch:** AX context computed the same library qualification three times
+for pins and focus. It now shares one request-local result. Fit also reuses its captured
+layout rather than loading the whole layout again just to inspect edges. The initial
+resetting preset menu and its orphaned highlight-menu state are gone. The vision's
+“planned, not implemented” lifecycle status is corrected. No dependency or cache was added.
+
+Measurement: Bun 1.4.2 in the Linux orb, nine warm samples per case, short Markdown cards,
+no review history or dependencies. At 30 boards × 150 cards, AX context median falls from
+138.6 to 48.3 ms; at 10 × 150, from 44.0 to 13.6 ms. Single-card reads remain approximately
+46 ms at 4,500 cards. The qualification object is 1,302,961 JSON characters. These are
+lower-bound server measurements, not browser latency or a supported capacity guarantee.
+Logs: `/tmp/pmx-w3-debt-baseline.zPoaEM/log` and `/tmp/pmx-w3-debt-after.iXN2fq/log`.
+
+| Priority / boundary | Evidence and disposition |
+|---|---|
+| Before larger-library scaling | `lifecycle-status.ts` reads every board and each card's full review history even for one-card requests. `KnowledgeSync` reloads workspace qualifications after board changes. Bound narrow reads to the dependency closure, batch/index review summaries, and separate folder aggregates from card detail when scaling this path. Measure populated review histories and long dependency chains as well as empty history. Avoid a TTL cache: cadence, sessions, retirement and source changes have different invalidation clocks. |
+| Wave 4, frame host | `ExtAppFrame.tsx` still owns 1,597 lines of bridge/recovery behavior. Consolidate mount budget, theme delivery and visible fallback with the planned frame host, preserving working draft/refresh behavior. Do not start another recovery ladder or infer native WebKit paint from Chromium tests. |
+| Wave 5, groups and agent output | Keep board-qualified relation/provenance identities when moving cards into or out of a board. Review records currently outlive snapshots and are keyed by board + card; define their move semantics before adding make-board/inline-board. Do not clone validation as if a new claim had been checked. |
+| Journal and shared/hosted stages | The due evaluator still reads the local `canvasState` singleton. Separate runtime acquisition from qualification when a second runtime needs it, not by speculative package splitting now. Filter authorized sources before summaries, titles and lifecycle reasons are computed. Categories are not permissions. Keep validation audit distinct from an undoable content journal and finish the authoritative mutation-path decision before event sourcing. |
+| Test maintenance | Large integration files remain (`server-api.test.ts`, `canvas.pw.ts`). Split by owning domain when those domains next change, preserving isolation and race cases. Do not replace human browser or real transport checks with source-string assertions to make the suite cheaper. |
+
+The earlier gate-resolution question is superseded by vision move 7 and plan 010:
+approvals are attributed coordination, not a human-only security boundary. Tour cleanup
+remains explicitly deferred in vision move 12. Neither is reopened in this batch.
+The codebase supports continued staged vision work; this review is not release approval.
+
+### Home acceptance integration review (2026-10-12)
+
+The combined Home and acceptance review keeps one server graph projection and one set of
+board-qualified writes. `memory-layout.ts` owns Map geometry and D3 view particles; the
+simulation never changes saved board coordinates, content or validation. D3 is now a direct
+dependency rather than an accidental transitive one. Live reads coalesce while a request is
+running, discard responses from superseded views and preserve camera/selection. Library
+browsing unmounts the canvas and gates board controls so a paste or shortcut cannot mutate
+the agent's hidden active board.
+
+Real transport review found the MCP node-type enum duplicated the canonical list and omitted
+board portals. Both now use `NODE_TYPES`, with a discriminating MCP regression. Live visual
+review also caught the library context chip omitting a pinned active board; it now lists all
+board pins without exposing hidden-board card controls. Neither finding justifies another
+adapter or graph store. Category deletion refuses explicit assignments even to empty folders;
+the simplified review form retains captured content/source revision guards.
+
+The live-library checkpoint in the vision records the next boundaries: explicit per-tab
+editor ownership before concurrent board editing, and measured fetch/force/paint costs before
+workers or culling. The 13-board/101-card browser fixture is acceptance evidence, not a large
+library capacity claim. Map and Graph now have separate view owners, sharing discovery loading
+and inspector docking only; the superseded combined view and Graph layouts are removed. The codebase is
+healthy enough for staged vision work with these constraints, not debt-free or fully validated
+in native hosts. The reported Amp embedded-portal context-pill opening failure is still
+unverified and distinct from the fixed pin count.
+
+## Private wiki-import findings (2026-10-18, locally fixed and retested)
+
+Source: [private import-test handoff](https://ampcode.com/threads/T-01a14f43-f513-7397-8ec4-f6a85551dff0).
+Reported environment: PMX Canvas 0.8.2 at
+[`92c2930`](https://github.com/pskoett/pmx-canvas/commit/92c293029e98a5fc1c04f43821470eb35fe500c6),
+Bun 1.4.2, headed Chromium in a Linux orb. Synthetic MCP reproductions subsequently
+confirmed the findings. Local fixes build on the pushed Graph candidate
+[`150aeba`](https://github.com/pskoett/pmx-canvas/commit/150aebad08c03909a0170660d12bd33f558735a9).
+After-fix checks use the official SDK Client and StdioClientTransport attached to a
+disposable source daemon, plus headed Chromium for rendered effects. This is not a
+native-host or published-package claim. The source database and private documents
+were not imported; the owner's running workbench was not changed.
+
+Private evidence remains in the source thread's workspace: `wiki-load-before.json`,
+`wiki-load-after.json`, `wiki-backlog-cards.png` and `wiki-linkedin-cards.png` under
+`.amp/in/artifacts/`, plus `.learnings/wiki-load-probe.js` and `.learnings/ERRORS.md`.
+Screenshots and full notes contain private wiki content. Keep them within authorized private
+work; use synthetic fixtures or redaction for any public reproduction or report.
+
+### WI-01, high: embedded base64 Markdown images make parsing and board loading slow
+
+**Status:** locally fixed and retested with identical inline image content, not a data conversion.
+Marked's long destination and unmatched setext scans caused the reproduced parser cost.
+The wiki parser now avoids those scans while preserving reference and rendered-image output.
+Controlled 1,106,157-character parser runs changed from 1245–1503 ms to 17–31 ms;
+the short-reference control changed from 7–10 ms to 3–4 ms. These synthetic parser
+measurements are not end-to-end load or universal speedup claims. MCP-created inline
+and file-reference boards both render and decode the same SHA-256-checked 800×600 image.
+Payload duplication, offscreen render requests and full-layout SSE remain possible
+amplifiers, not solved or independently established causes of all loading outliers.
+
+The source test measured board-open request through ready card bodies and loaded pictures
+(including natural image dimensions), not just HTTP response time. Each cell lists three
+runs in milliseconds. The workaround changed import data, not product code: seven embedded
+images became file-backed image nodes on their owning boards, referenced through
+`/api/canvas/image/<id>`. Served bytes matched the originals by SHA-256. The documents and
+pictures were retained, with extra figure cards; this is not an identical-card-count comparison.
+
+| Workload | Before workaround | After data-only workaround | State payload, before → after |
+|---|---|---|---|
+| 9 Markdown cards, 5 pictures originally | 5329 / 5609 / 5714 | 782 / 879 / 817 | 3,195,186 → 649,194 bytes |
+| 12 cards, 2 pictures originally | 9364 / 4011 / 7403 | 710 / 904 / 759 | Not reported → 211,414 bytes |
+| 29-card text-only control | 1566 / 1419 / 1643 | 1372 / 1021 / 1275 | Not reported |
+
+Direct isolation on one 924,640-character card measured `wikiReferences` at
+1422 / 1194 / 1170 ms and `renderWikiMarkdown` at 1183 / 1187 / 1189 ms. Replacing only base64
+URLs with short URLs reduced the source to 11,728 characters and parsing to 2–11 ms, retaining
+11 wiki references and four image tags. This isolates parsing cost, not image downloading.
+The server was already running, caches were not cleared, and transport was local to the orb.
+Small-board transitions also occasionally took about three seconds. No universal speedup or
+single cause for every outlier is established. File-backed assets must accompany the database.
+
+Reported amplifiers to inspect at reproduction: `src/server/wiki-links.ts`;
+`handleRender` in `src/server/server.ts` lexing persisted Markdown twice and rendering again;
+`src/server/canvas-serialization.ts` duplicating source at top level and `data.content`;
+`MarkdownNode.tsx` posting each mounted card's entire source to `/api/render`, including
+offscreen cards; and full-layout SSE payloads. These are investigation leads from the tested
+revision, not independently verified causes on the candidate.
+
+**Next:** measure remaining payload/paint costs separately if large real boards still stall.
+Retain reference/image-preservation checks before changing parser or transport behavior again.
+
+### WI-02, medium: relative image creation ignores the configured workspace root
+
+**Status:** locally fixed and retested through MCP. Relative paths now resolve against
+the configured workspace root. A daemon launched outside that root creates the synthetic
+relative-path image successfully, and served bytes match the original hash. The serving
+route's realpath confinement is unchanged.
+
+Launch from directory A with `PMX_CANVAS_WORKSPACE_ROOT=B`, with a valid picture at
+`B/wiki/assets/diagram.png`. `POST /api/canvas/node` with
+`{type:"image",content:"wiki/assets/diagram.png"}` returned 400,
+`Invalid image node: diagram.png does not exist`. The absolute path succeeded, as did all
+seven image imports using that workaround.
+
+The source investigation identified `buildImageNodeData` in
+`src/server/canvas-operations.ts` using `resolve(src)`, unlike file-node creation's
+`resolve(canvasState.getWorkspaceRoot(), rawPath)`.
+
+**Guardrail:** keep separate launch/workspace coverage and realpath confinement; relative
+creation must not weaken the file-serving boundary.
+
+### WI-03, low: review/lifecycle badge protrudes beside grouped cards
+
+**Status:** locally fixed and visually retested independently of freshness noise removal.
+The group's sole body child was stretched by the content flex rule. Its footer now lives
+in the bottom frame chrome. A deliberately due, zero-review group has a 22.44 CSS px footer
+at 68% zoom, versus 259.76 px in the source reproduction. All 36 width/theme cases hit-test
+the footer, and a real pointer click opens that group's Review drawer. Fresh children stay
+unmarked. This does not resolve or identify the separately reported Updates badge.
+
+With Knowledge lifecycle enabled, a dense group at 68% zoom showed a partly obscured amber
+review badge beside a middle-left card; a similar artifact appeared on another board.
+Capture conditions were 1600 × 1100 CSS pixels, DPR 2. All nine cards in the dense group fit
+and rendered. This is not established as the separately reported floating Updates badge.
+
+**Guardrail:** test explicit group due/source warnings as well as fresh content, so removing
+inherited policy noise cannot conceal a broken badge layout.
+
+**Not counted as product bugs:** source-draft chronology, poor initial import board
+granularity, and unescaped wiki-alias pipes in Markdown tables. An unescaped table alias can
+produce zero parsed references, so zero unresolved links alone is not a preservation check.
+The initial handoff's wiki-import guidance was local-only. A later handoff reports it pushed
+to `origin/main` in
+[`48013e1`](https://github.com/pskoett/pmx-canvas/commit/48013e1346ea34f107c11f93dca3f4cace1f7a23).
+It has not been integrated into this checkout.
+
+### WI-04, priority pending: incomplete provenance is silently discarded on node creation
+
+**Status:** locally fixed and retested through MCP. Explicit incomplete/invalid provenance
+is rejected with field-specific errors; valid source dependencies survive readback. Omitted
+provenance still uses normal inference for sourced node types.
+
+The source test submitted `data.provenance` with `sourceKind:'agent'`,
+`snapshotContent:true`, `sources:[{boardId,cardId,contentRevision,availability:'cached'}]`
+and `recipe:{tool,prompt}`, omitting `sourceUri` and `refreshStrategy`. Creation succeeded,
+but a subsequent GET returned `provenance:null`, losing the submitted source dependencies.
+The payload was incomplete and `agent` is not an advertised source kind. This does not claim
+that valid provenance was rejected or lost.
+
+The source investigation points to `normalizeExistingProvenance` in
+`src/server/canvas-provenance.ts` returning null for missing required fields, after which
+the ensure path deletes provenance. The data-only repair supplied `sourceKind:'recipe'`,
+`sourceUri` and `refreshStrategy:'agent-request'`; the source thread verified all 20 repaired
+cards, 54 source references/revisions and persistence after restart. That repair was data-only.
+
+**Guardrail:** keep the rejected incomplete payload and valid source-preservation control.
+
+### WI-05, usability: short library queries rank picture filenames above content
+
+**Status:** locally improved and retested through MCP. Exact and whole-term match tiers
+precede embedded substrings; field weights only break ties within a tier. `V2 platform`
+ranks above `TV2 pictures` for `V2`, while the latter remains discoverable. Search scope,
+filters and stable tie ordering are covered by regression tests.
+
+A short query ranked picture filenames containing the token ahead of the intended platform
+content. No private content is needed to investigate this. Use synthetic titles, body content
+and overlapping filename tokens to assess relevance; establish the intended ranking before
+calling matching results incorrect.
+
+### WI-06, product requirement: schedule new content's first review by type and decay
+
+**Status:** locally implemented and retested through MCP and browser. New authored content
+starts fresh without a review record. Medium first expires at creation plus cadence;
+Fast/Slow at a later use/resumed session. Imports and existing undated content gain no
+synthetic freshness. Edits preserve the baseline. Group/portal nodes skip inherited factual
+decay unless explicitly assigned a card override; source/dependency warnings still apply.
+
+The source inspection used local and remote `main` at
+[`676fd1d`](https://github.com/pskoett/pmx-canvas/commit/676fd1d37727e0e4cc8d393b450500ef658ac052).
+A new work overview inherited a fast category policy and returned `records:[]`,
+`lastValidation:null`, `unknown:false`, `due:true`, with reason "Fast: check at use."
+A new planning overview inherited medium/90 days and reported
+"Review every 90 days; never validated." The snapshot contained 258 review-queue items,
+including group frames. The importing agent assigned the broad policy, amplifying the noise;
+this is not a measurement of the current candidate's queue.
+
+The source investigation reports that `src/server/lifecycle-status.ts` evaluates all node
+types: medium cadence treats `checked === null` as immediately due, while fast cadence
+requires current-session validation on the active board. `LifecycleChrome.tsx` presents both
+as the same amber review-due badge. Null per-card lifecycle inherits policy, rather than
+opting out. Source log: `ERR-20261018-005`, pattern `canvas.review_policy_import_noise`.
+
+**Required behavior, superseding the earlier emphasis on badge distinctions:** newly authored
+content must not enter the review queue solely because it has no validation record. Schedule
+its first review later according to its effective content type/decay policy, including the
+new work overview. Relabeling an immediate warning alone does not satisfy this requirement.
+Freshness and evidence validation remain distinct; creation does not establish validation.
+Imported historical content and edit-reset semantics need separate treatment, not a blanket
+reset that treats every import or edit as freshly established evidence.
+
+**Guardrail:** server-owned initial freshness is persisted independently of validation.
+Tests cover cadence boundaries, inherited policies, later sessions, imports, edits,
+undo/redo and snapshot restore. Historical text creation must declare
+`data.contentOrigin: "imported"`; origin is immutable. Do not fabricate review records or
+blanket-reclassify facts as durable. This remains separate from WI-03's layout fix.
+
+### WI-07, capability: create on an inactive board without switching the human's board
+
+**Status:** static node creation is delivered; the follow-up extends destination creation to
+groups and edges, completing the multi-card + frame + relations import workflow. Explicit
+board/folder search filters now intersect before ranking/limits. `destinationBoardId` selects
+the stored owner; `expectedBoardId` remains an active-board guard and `toBoardId` is an
+independent foreign endpoint. The singleton commits without temporarily opening the
+destination, altering active undo or creating ghosts. Scope fences and human edit locks
+remain enforced. Runtime-backed node creation, generated primitives, intents and inactive
+update/remove operations remain unsupported, not silently redirected. The two new
+capabilities require independent validation of this follow-up candidate.
+
+### WI-08, retry safety: distinguish retries from intentional identical creations
+
+**Status:** locally implemented and MCP-retested. Optional `requestId` persists an atomic
+creation receipt with the node, group or edge. Same input/destination replays the original receipt; mismatched
+reuse conflicts. New ids preserve intentional identical creations. Regression tests exercise
+restart, removal, rollback at receipt failure, endpoint clocks and named batch references.
+Receipts survive individual node deletion but are deleted with the owning board. Existing
+named batch edge/group references already worked and remain a passing control.
+
+### WI-09, high: many cross-board reference footers obstruct Markdown body links
+
+**Status:** reproduced with disposable synthetic cards and fixed after the
+completed review of pushed
+[`706f989b`](https://github.com/pskoett/pmx-canvas/commit/706f989befcc2277bfbf607598040c59cb5a80c7).
+The unchanged implementation failed the body-link hit test. One bounded, focusable
+scroll region now retains all reference rows without covering the document or actions.
+This is separate from WI-03's fixed group lifecycle footer.
+
+A strict-size 640 × 480 Markdown index card with 103 outgoing cross-board references
+rendered reference rows over its body. A real pointer click on a rendered Markdown link
+was intercepted by `div.node-memory-link`. The source thread inspected its screenshot at
+`.amp/in/artifacts/knowledge-rerun/reference-footer-overflow.png`. That evidence remains in
+the [source thread's workspace](https://ampcode.com/threads/T-01a14f43-f513-7397-8ec4-f6a85551dff0),
+not this checkout; do not publish private import content.
+
+The synthetic reproduction confirmed that every outgoing remote edge became a
+nonshrinking `.node-memory-link` row inside `.node-body`. The wrapper now caps the
+list at 40% of the body and 132 world pixels. Wheel and navigation keys scroll that
+region rather than the canvas. The design source and contract are updated together.
+Browser checks cover body-link hit testing, actions, all 103 references and navigation;
+the nine-theme, 600/1024/1920 px matrix also passes. WI-11 separately fixes untouched
+expanded Markdown source preservation rather than treating focus mode as a workaround.
+
+Independent acceptance on the frozen 13-file candidate also passes actual source stdio
+MCP, headed browser and restart checks. All 103 rows remain reachable in the 132 px
+scroll region. The full local browser run remains 312/313; the unchanged failing
+external-steering case and three affected/control cases pass in isolation. This split
+evidence is not an entirely green full-suite run.
+
+After integrating the right-click/pan change and updated import skills, the combined
+build, typecheck, 1,484 unit tests, 318 client tests and 20 targeted headed checks pass.
+The browser run repeats ten affected/control scenarios twice, not the full suite.
+A fresh source stdio MCP/browser fixture retains all 103 references in a 132 px region
+with hit-testable body links at desktop and 600 px. Exact Markdown and revision 1 survive
+read-only expanded navigation and an actual disposable-daemon restart. The served bundle
+matches the rebuilt distribution; screenshots and a pointer recording were inspected.
+
+**Acceptance:** create a fictional 640 × 480 Markdown card with roughly 100 remote
+references, including a body link. Assert that the body link remains hit-testable and a
+real pointer click navigates correctly, without enlarging the card to hide the defect.
+Keep references accessible and verify the destination card is visible. Retain an expanded
+focus-mode control and test independently of lifecycle warnings.
+
+The source assessment also reports 508 background static card creations plus background
+groups/edges across 38 boards, 518 Markdown cards, seven byte-identical images and 783
+rendered internal anchors, with no validation collisions. These are corpus-specific
+observations from the source thread, not a local rerun or a claim that all UI/loading
+friction is cleared.
+
+### WI-10, documentation: import skill guidance lags delivered path and destination behavior
+
+**Status:** fixed in the bundled `skills/pmx-canvas/SKILL.md` and
+`skills/pmx-canvas/references/importing-context.md` after explicit owner approval.
+The two files were checked against the current HTTP/MCP contracts and image-path
+implementation. Bundled-skill checks pass. No installed copies or pipeline skills
+were changed.
+
+The source thread found launch-directory relative-image resolution and foreground-only
+creation guidance. The refresh documents workspace-root-relative image paths and
+background static card/group/edge creation using
+`destinationBoardId`, while retaining active-board stale guards, retry identities and the
+documented runtime/intents/background-update restrictions. This describes the bundled
+source, not every installed copy, and does not advertise general inactive-board CRUD.
+
+The update also documents intersecting `boardId`/`folder` search filters, opening a
+suitable board when Home is active, and placing task/item content before retained
+ancestor/source context. This layout advice applies to folders, repositories and
+documents generally, not only one source corpus. Library discovery and background static
+creation do not require leaving Home. The main skill's existing oversized-body issue is
+not resolved by this scoped contract refresh.
+
+### WI-11, high: expanded Markdown link navigation rewrites untouched source
+
+**Status:** independently reproduced here with fictional Markdown, then fixed.
+The original implementation failed exact-content/revision checks after read-only link
+navigation. Untouched rich editors now flush the exact caller draft, and unchanged
+clean drafts do not persist. Actual rich edits still serialize and finish before
+navigation, including pending drafts carried from Source mode.
+
+Expanding a Markdown card and following a wiki link without typing changed its persisted
+source from 32,873 to 33,160 characters. The reported differences include `- ` becoming
+`-   `, normalized table delimiter spacing and removal of the trailing newline. A full
+post-restart comparison detected the changes, but the browser had already saved the
+normalized source before restart. This is an unintended write during navigation, not
+restart-related persistence loss.
+
+The [source thread](https://ampcode.com/threads/T-01a14f43-f513-7397-8ec4-f6a85551dff0)
+reports `browser-mutated-state.json` in its sibling fresh workspace and an inspected
+`.amp/in/artifacts/knowledge-rerun/navigation.mp4`. Those files have not been transferred
+here; preserve private source content. Only the source thread's test-created index was
+restored from its import manifest; its subsequent exact restart comparison passed.
+No original wiki or owner service was changed.
+
+The local red test confirmed the reported path: blur serialized an untouched rich DOM,
+then `handleInlineSave` marked it dirty and persisted. The disconnected/empty DOM guard
+remains. The updated editor distinguishes input from reading; a save without input uses
+the exact caller draft so a genuine pending Source-mode edit can still flush. Synthetic
+source MCP checks confirm exact content/revision after reading and a real daemon restart,
+and a separate real edit persists before link navigation. Browser regression checks also
+cover close, Ctrl+S and navigation without input. Evidence is under
+`.amp/in/artifacts/review-fixes/`; native-host and published-package checks are not claimed.
+
+Independent acceptance on the exact candidate confirms byte-identical Markdown and
+revision 1 after no-input close, Ctrl+S, body/expanded wiki navigation and daemon restart.
+A genuine heading edit persists before navigation and advances the revision. Its
+318 client tests and four isolated headed browser cases pass; the full-run qualification
+recorded under WI-09 remains unchanged.
+
+**Acceptance:** use fictional Markdown containing list spacing, a table, a trailing newline
+and an internal link. Mount/expand and follow that link without input; assert exact source
+content and `contentRevision` remain unchanged before and after navigation/restart. In a
+separate control, make a real edit and immediately follow the link; the edit must persist
+before navigation. Do not fix the unintended write by dropping genuine pending saves.

package/docs/plans/plan-016-context-made-visible-wave-1.md

@@ -1,6 +1,85 @@
 # Plan 016 — Context made visible (wave 1)
 
-**Status:** Slices 1–3 and 4a done (2026-10-05); 4b (tethers, drag preview, Updates entry) next.
+**Status (2026-10-10):** built on `main`, not released. Slices 1–5 and 7 are done, with the
+receipt extras, edit descriptions and the live session lens (slice 3) and Home (slice 7). Slice 6
+(the curation evaluation) moved to [plan 019](plan-019-post-0.9-roadmap.md) step 6 on 2026-10-19. Suggested cards were dropped
+(2026-10-10: the agent changes the canvas directly; asks and suggestions go through the composer).
+
+**Handoff (2026-10-10, end of session).**
+- **Drag performance, done:** on a 306-card board every card re-rendered on every drag frame. Cards
+  now render through a memoised `WorldNode` (CanvasViewport.tsx), `useHeaderFold` measures only
+  when its key changes, and `App` subscribes to "board is empty" instead of the node map. Profiled
+  (Chrome CPU profile, 90-frame drag): Preact diff ~700 → ~70 ms, GC 385 → 20 ms, p95 frame 37 →
+  21 ms; long tasks 4 → 2.
+- **Next, drag:** the two remaining long tasks (~50–65 ms) are at pickup and drop, not per frame.
+  Suspects to profile: pickup — `bringToFront`, `buildSnapCache` (O(n)), `reportHumanGrab`,
+  `takeOverNode`, `noteNearAtGrab`; drop — `persistLayout`, `settleNearAfterDrop`, attention
+  entries. Profiler script approach: Playwright + CDP `Profiler` on an unminified
+  `bun build src/client/index.tsx --outdir dist/canvas` (rebuild minified after).
+- **Next, design:** build to [`SeeChange.dc.html`](../design/SeeChange.dc.html) (drawn 2026-10-10,
+  33a853d8): stack Before/After; mark removed (line-through, muted) and added (violet tint +
+  underline) words with a word-level diff; captions under Undo ("puts back the text from before",
+  "the card shows Before again", "undo would lose your edit"); "Open its board to undo" becomes a
+  button naming the board; the row Undo's "Kept your edits" caption; one change open at a time.
+  At ≤ 760 px the live counts move into the agent avatar's popover (with the dim switch and "Open
+  session panel"), and the avatar gets a violet ring and phase dot (ContextChip600 wins over
+  Pane600).
+- **Not run this session:** the curation evaluation (maintainer, later); a full browser suite on
+  a quiet machine (the presentation-record tests failed under load at 261e7c0f and its parent).
+
+**Resumed (2026-10-10; not released).**
+- **See change built:** stacked Before/After with Unicode word marks, one change open, the
+  drawing's Undo captions and shared per-card/bulk restored state. Long scroll boxes start at
+  the first marked word. The receipt is opaque so underlying violet marks do not bleed through.
+  The ≤ 760 px avatar has its ring, phase dot, counts, dim switch and Open session panel.
+- **Board safety:** receipt touches carry their board ID, and merge/row identities use board +
+  card. Direct board switches retain the receipt, with a working Open <board> to undo button;
+  Home still dismisses it. Undo/Unpin cannot affect another board, and receipt marks/lens only
+  apply to the active board. Later human edits are retained on per-card and bulk Undo.
+- **Pickup/drop profiled and one cost removed:** headed Chromium, 1440×960 at 100%, 306 Markdown
+  cards (230×150, 260×190 pitch), 90 moves per drag, three runs with 20 pins and three without.
+  Hit-tested titlebars and visible card displacement verify actual drags. An initial 25% probe
+  hit a port instead and was discarded. The named pickup/drop helpers were not the dominant
+  sampled cost; a timeline trace found page-wide style recalculation from the universal drag
+  cursor/selection selector. A single transparent drag curtain preserves pointer delivery across
+  frames without changing every descendant. It belongs to the canvas so collaborator cursors
+  still follow the pointer, and intercepts only after the 4 px threshold so double-click menus
+  keep working. In the no-pin trace, UpdateLayoutTree totals fell from 120/75 ms at pickup/drop
+  to 12/5 ms with the final built source. These are individual measured runs,
+  not a device-independent latency guarantee. Layerization/GC still produce occasional long
+  tasks (the final pickup had a 157 ms task including GC); do not claim all drag pauses are fixed.
+- **Design checks:** all nine themes at 600/1024/1920; inspected Harbor, narrow Daylight,
+  avatar popover, long change, human-protected change, other-board and restored/bulk-kept states.
+- **Still deferred:** the maintainer's curation evaluation. Relation-label spacing feedback is
+  separate guidance work; this change does not alter auto-arrange or validation.
+- **Baseline gates:** the four presentation/tour cases also fail on a fresh unmodified
+  [26dc70a](https://github.com/pskoett/pmx-canvas/commit/26dc70ac46490d567750aa46b3449263b520613d)
+  build (1 passed / 4 failed in `presentation-record.pw.ts`). Repo-wide lint also failed there
+  with two formatting errors (`context-chip-store.ts`, `ax-timeline.ts`); the maintainer then
+  requested those fixes. Biome formatted only those two lines, and `bun run lint` now exits 0
+  (62 warnings, 12 infos). The presentation failures remain acknowledged, not described as green.
+- **Review completed:** the requested review found short-window clipping, a retained receipt's
+  foreign-board comparison action, and row Undo still enabled after every individual restore.
+  Each was reproduced and fixed; the follow-up review found no remaining findings in that scope.
+  Final visual inspection also caught History's invisible tooltip widening the receipt; aligning
+  it to the end removed horizontal overflow, with a regression assertion shown red then green.
+- **Final verification:** full build and typecheck pass; 1,379 unit tests and 247 client tests
+  pass. The final headed browser rerun has 232 passed and the same four baseline presentation
+  failures. The first run's three double-click regressions were fixed by gating the drag curtain
+  at the movement threshold; targeted interactions and the final full rerun pass those cases.
+  All five receipt browser cases pass, including short-window scrolling and created-only
+  cross-board comparison. Final DOM checks cover all nine themes at 600/1024/1920, with no
+  horizontal overflow. One interim client rerun caught a leaked debounced brief request in the
+  iframe test's fetch spy; that test passed alone and the full unchanged rerun passed 247/247.
+  First-failure evidence, rerun results and the unchanged-baseline reproduction are retained.
+
+**Later combined checkpoint (2026-10-11; not released).** Wave 2 and the Wave 3 foundation
+now pass 1,437 unit, 302 client and all 266 headed browser cases, including the presentation
+and receipt cases. Live human/agent checks and final focused Oracle review are complete;
+the earlier red runs above remain historical evidence, not relabelled passes. See the
+[combined stabilization record](plan-018-connected-memory-wave-2.md#combined-stabilization).
+The maintainer's curation evaluation remains deferred.
+
 **Date:** 2026-10-05
 **Source:** [design.md](../design.md#build-plan) wave 1; vision Part 1 bet (item 4), moves 0a, 2, 7.
 Drawings: [`AgentContext`](../design/AgentContext.dc.html), [`Context`](../design/Context.dc.html),
@@ -88,8 +167,20 @@ with their actions (Unpin, Undo). Data from presence activity, revisions and sli
   on a board with two agents at once, each receipt includes the other's reads.
   The receipt also reads the board open when the session ends; a session whose board the person
   switched away from mid-session reports the newly open board (known limit, 0.8.0 review).
-- **Not built:** per-row Undo of an edit (needs stored previous content); the pre-session snapshot
-  restore still undoes the whole session. The drawn bottom-bar placement of the lens is folded into
+- **Receipt extras, done (2026-10-10, gap 18).** A single session's receipt reads "What <agent>
+  did" with "This session · start–end · saved as a snapshot · ended by …"; the amber line has
+  "Tell <agent>" (a steering message to reread the changed pins); the Edited row has Undo, which
+  puts each edited card back to its pre-session content through the new
+  `snapshot.restore-node` operation (`canvas_snapshot { action: "restore-node" }`,
+  `POST /api/canvas/snapshots/:id/restore-node`) — one undoable edit per card, position, links
+  and pins kept.
+- **Edits and the live lens, done (2026-10-10).** Each Edited line says what the edit did
+  (`describeEdit`: "rewrote the second paragraph", "added 2 paragraphs", "renamed it …"), from the
+  pre-session snapshot against the card now; "See change" shows Before / Now with Undo for that
+  card. Cards the session edited carry the violet title-bar bar while it is live or its receipt is
+  up. Presence carries the session's touches (`session`: read, created, edited, pinned ids), shown
+  as "2 read · 1 edited" in the agent chip; pressing it dims untouched cards, and that lens carries
+  on as the receipt's when the session ends. The drawn bottom-bar placement of the lens is folded into
   the receipt card, which already sits where session results appear.
 
 ### 4. Near a pin: neighbours in the brief, and the near mark
@@ -105,7 +196,17 @@ with their actions (Unpin, Undo). Data from presence activity, revisions and sli
   that changed since the cursor arrives in full as `changed` instead; a first read delivers every
   node in full, so it has no near entries. The client computes the same `findNeighborhoods` and
   shows the dotted "near" / "near N" chip on unpinned nodes, with the pins and distances on hover.
-- **4b, next.** Tethers and the 600 px radius when hovering a pin, the drag preview, the single
+- **4b, done (2026-10-10).** Hovering, selecting or dragging a pin, or "Show pins" in a near
+  chip's card, draws numbered tethers (nearest first) and the 600 px radius in one screen-space
+  layer; dragging an unpinned card rings its nearest pin and previews its chip; a drop inside
+  pulses the chip once, a drop outside fades it; one Updates entry names the card and the pin
+  ("out of the agent's brief" only when it is near no pin). The near chip's card lists the pins
+  with distances and offers "Pin to put it first" (the drawing's wording, replacing "Pin to send
+  content") and "Show pins"; it draws over the canvas because a card paints contained. Perf
+  check (2026-10-10, 306 nodes / 20 pins, in-app pane): drag frames showed long tasks with and
+  without pins (8 vs 13), so none are attributable to near-a-pin; the drag itself is slow at
+  that size.
+- **4b, as planned.** Tethers and the 600 px radius when hovering a pin, the drag preview, the single
   Updates entry that replaces "Neighborhood changed", the context chip's "N cards · M near" count,
   and "Pin to send content" in the chip's hover. The maintainer agreed the design (2026-10-06) on
   the condition that performance stays good:
@@ -120,19 +221,63 @@ with their actions (Unpin, Undo). Data from presence activity, revisions and sli
   - **Check.** A headed drag on a 300-node board with 20 pins records no long task (> 50 ms)
     attributable to near-a-pin.
 
+### 4c. Links changed in the brief (LinksChanged.dc.html, gap 15)
+
+- **Done (2026-10-10).** On a later read, `changed` and `pinned` entries carry `changes`
+  (`["text"]`, `["links"]` or both; a pinned card stays `pinned`), and each relation drawn or
+  changed since the cursor ends "(new, by codex)" / "(changed, by a person)". First and reset
+  reads mark nothing; generated code-graph and board-map links are never stamped, so never
+  marked. A removed link writes one Updates entry naming both cards. Deviation: a person is
+  "by a person", not by name — edges record no human name until shared boards (hosted version, vision Part 4).
+
 ### 5. Board pins
 
+**5a done, 2026-10-07.** `board_pins` table (who, when, why; removed with its board),
+`board.pin` / `board.unpin` across `canvas_board`, HTTP `POST /api/canvas/boards/:id/pin|unpin`,
+`pmx-canvas board pin|unpin` and `pinBoard()` / `unpinBoard()`; every board carries `pin`.
+The brief adds pinned boards after the open board's pins (README and pinned cards in full,
+else a discovery summary, reported in `delivery.pinnedBoards`), and a full delivery records a
+read on that board. `canvas://pinned-context` lists `pinnedBoards`. **5b next:** the pin on
+Home cards, the board switcher, portal cards and the top bar; Home's pinned section; the
+context chip's "N cards · M boards" and its fallback note.
+
+**5b, part 1 done, 2026-10-07.** One `BoardPinButton` (the card pin's mark on a 22 px target)
+on Home rows (blue edge and "in context" when pinned), board switcher rows, portal cards and
+the top bar; human pins carry the workbench marker. Left for part 2: Home's pinned-boards
+panel and preview cards (`Home.dc.html`, a Home redesign), and the context chip shared with
+4b. Open: a portal shows both its card pin (header) and its board pin (body).
+
 Per vision move 0a and `BoardPins.dc.html`: `board_pins` table (board, who, when); `canvas_board`
 `pin`/`unpin` across PmxCanvas, HTTP, MCP and CLI; the tiered brief (active board's pins, then each
 pinned board's README + pinned cards, then discovery); the context chip counts "N cards · M boards";
 Home's pinned-boards section per `Home.dc.html`. Read status per board from slice 1.
 
+### 7. Home (Folders) — Home.dc.html, Pane600.dc.html (gaps 19, 20)
+
+- **Done (2026-10-10).** Home is a library: a folder tree (counts, a pin dot on folders holding a
+  pinned board, "+ New folder"), the pinned boards with their ≈ token cost, the open folder's
+  breadcrumb, subfolder cards and board cards (thumbnail from the board list's new `preview`,
+  README line, cards, ↔ links, last opened), and a details pane for the selected board
+  (in-context switch, README, pinned cards, links, Open board, ⋯ move / rename / create from /
+  delete). A card selects; Open board (or a double-click) opens. At ≤ 760 px the tree is a folder
+  picker, pins a banner, subfolders chips, boards rows and details a bottom sheet.
+- **Deviations:** folders carry no colour (decided 2026-10-07, superseding the drawing's hues); the
+  folder's README line is left out until folders have a README; the Map and Graph tabs wait for
+  wave 2; links are board portals only ("wiki link" has no data yet). The ≈ token cost per pinned
+  board is the board list's `mapChars` (README + pinned card summaries) / 4, an estimate.
+
 ### 6. The curation evaluation
 
+**Ready, 2026-10-07.** Board, seed script, protocol, rubric and how results are used are in
+[`docs/evals/curation-effect.md`](../evals/curation-effect.md); the fixture test guards that
+pins change delivery at the default budget. Building it found that a first read larger than
+the budget returned one clipped card forever; fixed so a first read pages (pins first, then
+whole cards oldest first). Runs need the maintainer's agent sessions.
+
 `docs/evals/curation-effect.md`: one fixed task, run with the brief delivered on a curated and an
 uncurated board, scored on criteria written before the first run (vision Part 1, item 4). It reads
 the same `context_reads` data as slice 1 to confirm delivery before scoring effect. Running it
-needs the maintainer's real agent sessions; the decision rule is the vision's.
+needs the maintainer's real agent sessions; from plan 019 step 6 onward it is a benchmark rerun per release (vision Part 1, item 4).
 
 ## Out of wave 1