wiki-viewer 2.12.0 → 2.14.0

package/.next/standalone/specs/changes/collective-agent-review/design.md

@@ -0,0 +1,183 @@
+# Design: collective agent review
+
+## Overview
+
+Turn the fire-and-forget, one-target agent call into **collect → send batch → review batch**,
+sharing one workflow across Markdown and web, while keeping the two write engines separate.
+
+Two annotation kinds share the existing anchoring machinery:
+
+- **comment** — human discussion (existing behavior).
+- **instruction** — an agent work order; accumulates into a per-file queue; dispatched as one
+  **run**.
+
+## Data model
+
+### Markdown annotations (sidecar)
+
+Reuse the existing `Comment` model and its anchoring/reanchor/stale machinery. Add annotation
+kind + queue/run linkage as **additive, nullable** fields (Gap-1 precedent).
+
+`src/lib/proof/types.ts`:
+
+```
+export type AnnotationKind = "comment" | "instruction";
+
+export interface Comment {           // existing; extended
+  id: string;
+  ref?: string;
+  lineAnchor?: LineAnchor;
+  resolved: boolean;
+  createdAt: string;
+  turns: CommentTurn[];
+  stale?: boolean;
+  // NEW (all optional; absent => "comment" for legacy rows)
+  kind?: AnnotationKind;             // "instruction" marks a work order
+  instructionState?: "draft" | "queued" | "sent" | "answered"; // instruction lifecycle
+  runId?: string;                    // the send run this instruction went out in
+  fromCommentId?: string;           // backlink when escalated from a comment
+}
+```
+
+Rationale: one store, one anchoring path (no duplicate subsystem), but `kind` is a required
+*semantic type* to the user (two create actions), not a soft toggle. Legacy rows with no
+`kind` render as comments.
+
+### Web annotations
+
+The web surface has no sidecar comment machinery. Web instructions live in the web-tweak
+preview/live store as a small per-file instruction list keyed by workspace+path (new, small;
+does not touch the Markdown sidecar). Same lifecycle fields (`draft/queued/sent/answered`,
+`runId`).
+
+### Run (the batch dispatch)
+
+A **run** is one agent dispatch carrying N instruction items. Represent it on the existing
+live request:
+
+`src/lib/proof/live/store.ts`:
+
+- Add request kind `generate.batch` (Markdown) and reuse `web.tweak` batching for web, OR
+  keep `kind: "generate"` and add an `items` payload. Chosen: **add `items` to the request**
+  so one row = one run.
+
+```
+export interface LiveInstructionItem {
+  instructionId: string;   // annotation id
+  blockRef: string | null; // markdown block or web selector target
+  baseRevision: number | null;
+  instruction: string;
+  selectionText?: string | null;
+}
+
+export interface LiveRequest {        // extended
+  ...
+  items: LiveInstructionItem[] | null; // NEW: batch payload; null for legacy single requests
+  runId: string | null;                // NEW: correlation id returned on results
+}
+```
+
+The single-instruction fields (`instruction`, `blockRef`, `baseRevision`) stay for backward
+compatibility and for control kinds; batch runs populate `items` + `runId`.
+
+The **one-outstanding-request-per-session** invariant is unchanged: a run is still one
+request row.
+
+## Correlation (run id → changes)
+
+- On send, generate `runId` (e.g. `run:<8hex>`) and stamp it on the request and on each
+  queued instruction (`instruction.runId`).
+- Markdown: the agent's tier-2 ops already carry `inResponseTo`. Extend the request's
+  idempotency/correlation so activity-log provenance produced for this run carry the `runId` (via the
+  existing `ActivityAttrs` provenance). The editor groups activity-log provenance by `runId` to offer
+  "Accept run / Discard run".
+- Web: the preview transaction already binds a `previewId`; associate `previewId` with
+  `runId` so the overlay reviews the whole run.
+
+## Write paths (unchanged engines)
+
+- **Markdown**: agent applies ops through existing `POST /api/agent/files` → `applyOps`
+  (`ops-applier.ts:457`). Each op keeps baseRevision preflight and STALE_REVISION semantics.
+  Batch accept = accept all activity-log provenance tagged with `runId`; batch discard = revert them.
+  All-or-nothing is enforced at the review layer (accept each tagged span; if any fails,
+  surface and stop — v1 keeps the simple path).
+- **Web**: agent replies via existing `web-preview` route with the candidate patch bound to
+  the run's `previewId`; accept commits through existing `commitCandidate` (single-file v1);
+  discard invalidates.
+
+No new write engine. Line-review gate: nothing writes document bytes or provenance outside
+these two paths.
+
+## API surface
+
+### Human-facing
+
+- `POST /api/wiki/live/request` — extend to accept `items[]` + return `runId` for a batch
+  `generate` dispatch. Rejects with 409 if a run is already outstanding. Existing
+  single-instruction body still accepted (legacy/compat).
+- `GET /api/wiki/live/status` — already returns attached + last request; add `runId` and item
+  count so the queue/review UI can render.
+- Web already has `POST /api/wiki/web-tweak/request` and `/resolve`; extend request to carry
+  `items[]` + `runId`; resolve stays per-run (accept/discard).
+
+The instruction *queue itself* (draft instructions not yet sent) is client-side state backed
+by the sidecar (Markdown) or the web instruction list; only **send** hits the live channel.
+
+### Agent-facing
+
+- `GET /api/agent/live/poll` returns the request including `items[]` + `runId`.
+- Agent handler processes items together, applies tier-2 ops for Markdown (or submits web
+  preview), then `reply done`. Correlation/idempotency derived from `runId`/`requestId` at
+  commit time (existing one-engine rule).
+
+## UI
+
+### Markdown editor
+
+- Bubble menu / view-mode affordance: replace single "Ask agent" with **Comment** and
+  **Instruct** actions.
+  - `openCommentForSelection` (existing) stays for comments.
+  - New `openInstructForSelection` creates a `kind:"instruction"` annotation (draft), no
+    dispatch. Retire `AskAgentPopover`'s immediate-send; reuse a lighter instruction editor
+    that writes a draft instruction.
+- Comment card gains a **"Turn into an instruction"** action (creates instruction with
+  `fromCommentId`).
+- A file-level **queue bar**: "N instructions ready · Send to agent" → enumerated confirm
+  dialog → dispatch run.
+- After a run returns, activity-log provenance tagged with `runId` are grouped with **Accept run /
+  Discard run** controls, alongside existing per-span activity tracking.
+
+### Web tweak overlay
+
+- Element picker pins an **instruction** to an element (draft), no dispatch.
+- Same file-level queue bar + enumerated Send.
+- Review the returned preview run with Accept run / Discard run (existing preview overlay,
+  relabeled).
+
+## Backward compatibility
+
+- `kind` absent ⇒ comment. Legacy sidecars unchanged.
+- `items`/`runId` null ⇒ legacy single request path still works.
+- Frozen async `recover` path untouched; event schema additions are ignorable by old
+  consumers.
+
+## Testing
+
+- Sidecar: instruction kind persists; legacy comment loads as comment; escalation creates
+  linked instruction without mutating the comment.
+- Live store: batch request stores `items[]` + `runId`; one-outstanding invariant holds;
+  poll returns items; reply correlates by runId.
+- Review: accept run accepts all tagged spans; discard reverts all; failure leaves no partial
+  state.
+- Web: instruction queue → single send → preview run → accept commits single-file candidate;
+  discard invalidates.
+- Rename: no "Ask agent" string in user-facing surfaces; verb is Instruct / Send to agent.
+- Floor holds; add the above as new tests.
+
+## Rejected alternatives
+
+- **Audience toggle on one note** (model C-as-toggle): makes accidental execution too easy;
+  rejected. Kind is a real type set at creation, escalation is explicit one-way.
+- **Separate second annotation subsystem** (model B-as-duplicate-store): duplicates anchoring
+  machinery on Markdown for one bit of meaning; rejected in favor of one store + `kind`.
+- **Per-item partial accept**: reintroduces multi-file atomicity; deferred.

package/.next/standalone/specs/changes/collective-agent-review/proposal.md

@@ -0,0 +1,138 @@
+# Proposal: collective agent review (instruct → send batch → review batch)
+
+## Problem
+
+Both agent surfaces share the same disease: **scattered, fire-and-forget, one-at-a-time
+agent calls**, and the way "Comment" and "Ask agent" coexist is confusing.
+
+- **Markdown "Ask agent"** (`ask-agent-popover.tsx`): select a block, type an instruction,
+  hit Send, popover auto-closes in ~900ms. The result later materializes as a `activity record`
+  with no visible tie back to what you asked. Only one request may be outstanding per session.
+  No way to annotate several blocks and dispatch them together.
+- **Web "Tweak"** (`web-tweak-overlay.tsx`): each element tweak is its own immediate request.
+  Same serialization and scatter, and the agent never sees the whole page at once, so
+  multi-element changes drift out of sync.
+- **Comment vs Ask agent is muddled.** A comment is a passive note to humans; Ask agent is an
+  invisible fire-and-forget command. They look similar but behave completely differently, and
+  nothing tells the user which one will change their file.
+
+## The model (in UX terms)
+
+**Two things you can pin to a target (a Markdown block or an HTML element):**
+
+- **Comment** — a note to humans. It sits there. It never changes the file.
+- **Instruction** — a work order for the agent. Something you intend to get done.
+
+They share the same pin gesture and anchoring, but read as clearly different objects
+(distinct icon + color). A user must never wonder "will this one change my file?"
+
+**No audience toggle.** We do not put a "for humans / for agent" switch on one note. A toggle
+turns every comment into "might this secretly be a command?" and invites accidental
+execution. Instead there are two things you deliberately create.
+
+**Explicit escalation.** A comment has one action, **"Turn into an instruction"** — one
+direction, deliberate, with a backlink to the original comment. The comment is never silently
+reinterpreted.
+
+**Collect, then send once.** You leave instructions across the document; nothing fires. When
+ready, one file-level button:
+
+> **3 instructions ready · Send to agent**
+
+Before sending, a dialog enumerates exactly which instructions on which blocks are going. You
+confirm. The agent processes them together with whole-file context and returns **one coherent
+change set tied to that send** (a "run"), so each returned change is visibly correlated to the
+instruction it answers.
+
+**Review as a batch.** Accept the whole run or discard it (all-or-nothing in v1). New
+instructions start the next run.
+
+**Retire the verb "Ask agent."** "Ask" implies an immediate conversational reply; this is a
+queued work order reviewed later. The action is **Instruct** / **Send to agent** (mirrors
+Cursor's Ask-vs-Agent split).
+
+## Desired outcome
+
+One rhythm on both surfaces: **pin your intent → send when ready → review as a batch.**
+
+The only thing that differs between surfaces is how a result *looks while you review it*
+(clean markdown suggestion in Markdown vs a staged preview on the HTML page). That is
+the medium, not the workflow.
+
+## Scope (this change — step 1)
+
+- **Two annotation kinds** on the shared anchoring machinery: `comment` (human) and
+  `instruction` (agent work order). Instruction is a first-class kind, not a flag on a
+  comment.
+- **Comment → instruction escalation** as an explicit one-way action with a backlink.
+- **A per-file instruction queue** with an enumerated **"Send N to agent"** dispatch. Nothing
+  dispatches on creation.
+- **One run per send**: the batch of instructions goes as a single agent dispatch carrying
+  whole-file context; returned changes correlate to that run and to each instruction.
+- **Batch review, all-or-nothing** for v1: Accept applies the whole run, Discard drops it.
+  - Markdown: changes land as `activity record`s (existing tier-2 path), reviewed inline, tagged
+    with the run id.
+  - Web: agent returns a staged preview set bound to one previewId, reviewed in the overlay.
+- **Rename the user-facing verb** from "Ask agent"/"Tweak" to Instruct / Send to agent, with
+  matching review vocabulary across both surfaces.
+
+## Non-goals (this change)
+
+- **Generate variants** (N alternatives for one target, switch-and-accept). High value,
+  documented as **step 2**, built after this lands. Out of scope here.
+- **Per-item / partial batch accept.** v1 is all-or-nothing. Per-item accept reintroduces
+  multi-file atomicity / partial-commit rollback that were deliberately deferred.
+- **Merging the two write engines.** Markdown keeps write-first-then-review (tier-2
+  activity/audit provenance); web keeps write-on-accept (tier-1 candidate patch). This change unifies the
+  *surface language and workflow*, not the engines. Line reviewers must enforce that no code
+  path writes disk/provenance outside the two canonical commit paths.
+- Multi-file candidate writes for web (still single-file per v1 web-tweak constraint).
+- Real LLM handler wiring (separate track); the passthrough/dev runner remains the reference.
+- Comment *replies/resolve* threading changes beyond what already exists.
+
+## Risks
+
+- **Annotation chrome.** Two similar pin types can clutter the document. Mitigate with one
+  unified annotation presentation, restrained visual distinction, and filters, not two
+  separate-looking subsystems.
+- **Instruction-as-comment by habit.** Users type a work order into a comment. Mitigate with
+  the explicit "Turn into an instruction" action and clear iconography.
+- **Scope creep toward a unified Accept abstraction.** Rejected earlier. Keep two review
+  mechanisms; unify only wording/affordances.
+- **Correlation UX.** Users must see which returned change answers which instruction. Needs a
+  run id threaded from send → each resulting activity/audit provenance / preview item.
+- **Outstanding-request invariant.** Today one request is outstanding per session. Collective
+  send is still one dispatch, so the invariant holds; the request now carries N instruction
+  items instead of one.
+
+## Acceptance criteria
+
+1. A user can create a **comment** (human, never mutates the file) and an **instruction**
+   (agent work order) on a Markdown block, visually distinct.
+2. A user can create instructions on 2+ blocks with **no agent request firing**, then trigger
+   a single file-level **"Send N to agent"** that dispatches them in one run.
+3. The **send dialog enumerates** exactly which instructions/targets are going.
+4. A **comment can be escalated** to an instruction via an explicit one-way action; the
+   original comment is not silently changed.
+5. The same collect → send → batch-review rhythm works in **web tweak** (instructions on
+   elements, one Send, one preview run).
+6. The agent receives whole-file context plus the instruction set in one dispatch.
+7. The batched response is reviewable as a set; **Accept applies the whole run, Discard drops
+   it** (all-or-nothing), with no partial writes on failure.
+8. Each returned change is **visibly correlated** to the instruction it answers (run id +
+   per-item linkage).
+9. **No new write path**: Markdown via tier-2 `applyOps`; web via existing candidate-patch
+   accept. Verified by test + review.
+10. The user-facing verb is **Instruct / Send to agent** (no "Ask agent"), with matching
+    review controls/wording on both surfaces.
+11. Test floor holds; new tests cover: two kinds, escalation, collective dispatch, batch
+    review, all-or-nothing failure.
+
+## Sequencing
+
+1. **This change** — two kinds (comment/instruction) + escalation + per-file instruction
+   queue + single Send + all-or-nothing batch review, on both surfaces, sharing vocabulary.
+   Also the moment the weak Markdown "Ask agent" fire-and-forget UX is replaced by the
+   collect/send/review loop.
+2. **Step 2 (separate proposal): generate variants** — single target, N staged candidates,
+   in-frame/inline switcher, Accept the selected one. The impeccable-native differentiator.

package/.next/standalone/specs/changes/collective-agent-review/requirements.md

@@ -0,0 +1,100 @@
+# Requirements: collective agent review
+
+Each requirement is observable behavior. Scenarios use GIVEN / WHEN / THEN.
+
+## R1 — Two annotation kinds on a Markdown block
+
+A block-anchored annotation is either a **comment** (human) or an **instruction** (agent work
+order). They are visually distinct and behave differently.
+
+- GIVEN a selected Markdown block
+- WHEN the user opens the annotation affordance
+- THEN they can create a **Comment** (human discussion) or an **Instruction** (agent work
+  order), each with distinct icon/label
+- AND creating either one does **not** dispatch any agent request
+
+## R2 — Comment never mutates the file
+
+- GIVEN a comment exists on a block
+- WHEN the user sends instructions to the agent (R5)
+- THEN the comment is **not** included and never causes a file edit
+
+## R3 — Explicit comment → instruction escalation
+
+- GIVEN an existing comment
+- WHEN the user chooses "Turn into an instruction"
+- THEN a new instruction is created for the same block, carrying the comment's text, with a
+  backlink to the original comment
+- AND the original comment is left unchanged (not silently retyped or deleted)
+- AND there is no persistent audience toggle that flips a note between kinds
+
+## R4 — Instructions accumulate without firing
+
+- GIVEN the user creates instructions on 2+ different blocks
+- WHEN each instruction is created
+- THEN no agent request is dispatched
+- AND a per-file indicator shows the count, e.g. "3 instructions ready"
+
+## R5 — Single enumerated batch send
+
+- GIVEN 1+ unsent instructions exist for the current file
+- WHEN the user clicks "Send N to agent"
+- THEN a confirmation lists exactly which instructions (text + target block) will be sent
+- AND on confirm, all listed instructions are dispatched as **one run** (single live request
+  carrying N instruction items) with whole-file context
+- AND while a run is outstanding, a second send is refused with a clear message (one
+  outstanding run per session)
+
+## R6 — Batch response correlates to instructions
+
+- GIVEN a run was sent with N instructions
+- WHEN the agent responds
+- THEN the returned changes are associated with that run id
+- AND each returned change is linked to the instruction it answers (so the UI can show
+  "this change answers instruction X")
+
+## R7 — All-or-nothing batch review (Markdown)
+
+- GIVEN an agent run produced M activity/audit provenance changes for the current file
+- WHEN the user Accepts the run
+- THEN all M changes are accepted together
+- WHEN the user Discards the run
+- THEN all M changes are reverted together
+- AND if applying any change fails, no partial state is committed (existing tier-2
+  baseRevision / STALE_REVISION semantics still hold per change)
+
+## R8 — Same rhythm on web tweak
+
+- GIVEN a static-HTML page in Tweak mode
+- WHEN the user pins instructions to 2+ elements
+- THEN no request fires per element
+- WHEN the user clicks "Send N to agent"
+- THEN the instructions dispatch as one run
+- AND the agent returns a staged preview set (write-on-accept, source clean) reviewed as a
+  batch: Accept commits the run, Discard drops it
+
+## R9 — Verb rename
+
+- GIVEN either surface
+- THEN the user-facing action is **Instruct** / **Send to agent** (no "Ask agent" wording)
+- AND Markdown and web use matching review vocabulary (e.g. "Accept run" / "Discard run")
+
+## R10 — No new write path
+
+- THEN Markdown changes are written only through the existing tier-2 `applyOps`
+- AND web changes are written only through the existing web-tweak candidate-patch accept
+- AND no code path writes document bytes or provenance outside those two commit paths
+
+## R11 — Backward compatibility
+
+- GIVEN existing files with only legacy comments (no instructions)
+- THEN they load and render unchanged
+- AND the additive annotation-kind field is nullable/defaulted so old sidecars and old event
+  consumers are unaffected
+- AND the frozen async `recover` path is untouched
+
+## R12 — Non-goals stay out
+
+- THEN there is no variant generation (N alternatives per target) in this change
+- AND there is no per-item partial accept of a run
+- AND the two persistence engines are not merged

package/.next/standalone/specs/changes/collective-agent-review/tasks.md

@@ -0,0 +1,62 @@
+# Tasks: collective agent review
+
+Ordered, checkable. Mark complete only after verification.
+
+## Phase 1 — Data model (Markdown)
+
+- [ ] T1. Add `AnnotationKind` + optional `kind`, `instructionState`, `runId`, `fromCommentId`
+  to `Comment` in `src/lib/proof/types.ts`.
+- [ ] T2. Sidecar read/write: persist and load new fields; legacy rows (no `kind`) load as
+  comments. Add test.
+
+## Phase 2 — Live store run model
+
+- [ ] T3. Extend `LiveRequest` with `items: LiveInstructionItem[] | null` and
+  `runId: string | null`; add columns (nullable) + migration-safe CREATE.
+- [ ] T4. `enqueueRequest` accepts `items[]` + `runId`; keep single-instruction path. Preserve
+  one-outstanding invariant (BEGIN IMMEDIATE). Add test.
+- [ ] T5. Poll response + `toRequest` include `items` + `runId`.
+
+## Phase 3 — Human API
+
+- [ ] T6. `POST /api/wiki/live/request`: accept `items[]`, generate/echo `runId`, 409 on
+  outstanding run. Legacy body still works.
+- [ ] T7. `GET /api/wiki/live/status`: include `runId` + item count.
+
+## Phase 4 — Markdown UI
+
+- [ ] T8. Bubble menu + view-mode: split into **Comment** and **Instruct** actions; add
+  `openInstructForSelection` that creates a draft instruction (no dispatch).
+- [ ] T9. Replace `AskAgentPopover` immediate-send with a draft-instruction editor.
+- [ ] T10. Comment card: **"Turn into an instruction"** action (sets `fromCommentId`).
+- [ ] T11. File-level queue bar: "N instructions ready · Send to agent" + enumerated confirm
+  dialog → POST run.
+- [ ] T12. Group activity-log provenance by `runId`; add **Accept run / Discard run** controls (all-or-
+  nothing) alongside existing per-span controls.
+
+## Phase 5 — Web tweak parity
+
+- [ ] T13. Per-file web instruction list (draft) keyed by workspace+path.
+- [ ] T14. Picker pins an instruction to an element (no dispatch); same queue bar + Send.
+- [ ] T15. Associate `previewId` with `runId`; overlay reviews the run (Accept run / Discard
+  run), relabeled.
+
+## Phase 6 — Rename + correlation
+
+- [ ] T16. Retire "Ask agent"/"Tweak" verbs in user-facing UI → **Instruct / Send to agent**;
+  matching review vocabulary both surfaces.
+- [ ] T17. Thread `runId` into activity/audit provenance provenance (ActivityAttrs) so results correlate to the
+  run and to each instruction item.
+
+## Phase 7 — Agent runtime
+
+- [ ] T18. `wiki-viewer-mcp` LiveClient/runLiveLoop: handle `items[]` batch requests; apply
+  tier-2 ops per item; correlation/idempotency derived from `runId`/`requestId`.
+- [ ] T19. Passthrough reference handler processes batch items.
+
+## Phase 8 — Verify
+
+- [ ] T20. Tests: kinds persist, escalation, batch enqueue, poll items, run correlation,
+  accept/discard run all-or-nothing, web parity, no "Ask agent" string.
+- [ ] T21. `pnpm typecheck`, `pnpm lint`, `pnpm test` (floor holds), mcp `npm test`.
+- [ ] T22. reviewer pass on the diff (security, backward compat, no new write path).

package/.next/standalone/specs/changes/live-collab/design.md

@@ -0,0 +1,141 @@
+# Design: Live agent collaboration
+
+## Key realization from code exploration
+
+The existing tier-2 commit path (`applyOps` in `src/lib/proof/ops-applier.ts:457`) already
+IS the `exact` preflight policy for the parts that matter:
+
+- It compares `baseRevision` to `sidecar.revision` and returns `409 STALE_REVISION` on mismatch
+  (`ops-applier.ts:509-523`).
+- It resolves the target `blockRef` via `resolveRef`; a vanished ref fails the op.
+- AI writers (`by: "ai:<id>"`) already get `activity record` wrapping (`cleanMarkdownCommit`,
+  `ops-applier.ts:94-160`) with a `ActivityAttrs` that already carries `inResponseTo`.
+- The HTTP route `POST /api/agent/files/[...path]` already enforces `Idempotency-Key`
+  (route.ts:96-132): same key + same payload returns the cached response; same key + different
+  payload returns `409 IDEMPOTENCY_KEY_REUSED`.
+
+Therefore the live channel adds **no new write path and no schema change to the commit
+engine**. It is a control plane that:
+
+1. carries a human's intent (selected block + instruction) to an attached agent, and
+2. tracks the session/request lifecycle,
+
+while the agent performs the edit through the existing `POST /api/agent/files/[...path]` with:
+
+- `Idempotency-Key: live:<requestId>` (deterministic replay safety), and
+- op `inResponseTo: "live:<requestId>"` (provenance correlation into `ActivityAttrs.inResponseTo`).
+
+The editor already reloads snapshot+sidecar via the browser SSE filesystem watch
+(`use-document-watch.ts:55-77`) when `applyOps` writes the `.md`, so the live channel does
+**not** push edits to the client. It only carries intent to the agent and lifecycle to both.
+
+This keeps us strictly in "stance 1": one commit engine, live path is exact-fail-closed by
+reusing `applyOps` as-is. The `recover` machinery stays for async/MCP and is untouched.
+
+## Components
+
+### 1. Live store — `src/lib/proof/live/store.ts`
+
+SQLite, following `src/lib/shared-docs/db.ts` (lazy singleton, WAL, inline
+`CREATE TABLE IF NOT EXISTS`). New db file `~/.wiki-viewer/live.db`.
+
+```
+live_session(
+  id TEXT PRIMARY KEY,           -- session id
+  workspace_id TEXT NOT NULL,
+  agent_id TEXT,                 -- attached agent, null until attach
+  state TEXT NOT NULL,           -- 'open' | 'closed'
+  created_at INTEGER NOT NULL,
+  agent_last_seen INTEGER        -- updated each long-poll; presence/lease
+)
+
+live_request(
+  id TEXT PRIMARY KEY,           -- request id -> Idempotency-Key live:<id>
+  session_id TEXT NOT NULL,
+  workspace_id TEXT NOT NULL,
+  path TEXT NOT NULL,            -- relative md path
+  block_ref TEXT,               -- selected block (null for steer/accept/discard)
+  base_revision INTEGER,        -- revision at selection time
+  kind TEXT NOT NULL,           -- 'generate' | 'steer' | 'accept' | 'discard' | 'exit'
+  instruction TEXT,             -- freeform prompt (generate/steer)
+  state TEXT NOT NULL,          -- 'pending' | 'delivered' | 'working' | 'resolved' | 'stale' | 'error'
+  outcome TEXT,                 -- 'accepted' | 'reverted' | null
+  seq INTEGER NOT NULL,         -- monotonic per workspace for ordered delivery
+  created_at INTEGER NOT NULL,
+  delivered_at INTEGER,
+  resolved_at INTEGER
+)
+```
+
+Store API (sync, better-sqlite3-style wrapper `src/lib/sqlite.ts`):
+`openOrGetSession`, `attachAgent`, `touchAgent`, `closeSession`, `enqueueRequest`,
+`nextPendingRequest(workspaceId, afterSeq)`, `markDelivered`, `markState`, `getSession`,
+`getRequest`, `latestOpenSessionForWorkspace`.
+
+Presence rule: an agent is "attached" if a session has `agent_id` set and
+`agent_last_seen` within a lease TTL (e.g. 45s). No separate heartbeat; the held long-poll
+updates `agent_last_seen`.
+
+### 2. Agent-facing transport — `src/app/api/agent/live/`
+
+All routes: `checkAuth(req)` -> `resolveWorkspaceForAgent(req)` -> `enforceScope(...)`.
+
+- `POST /api/agent/live/attach` — body `{ sessionId? }`. Creates/attaches a session for the
+  agent+workspace, returns `{ sessionId }`. Idempotent per agent+workspace (reuses latest open
+  session).
+- `GET /api/agent/live/poll?sessionId=&afterSeq=` — **long-poll**. Held open up to ~25s using
+  a `ReadableStream`-free promise+interval loop (mirrors the heartbeat pattern of
+  `/api/wiki/watch/route.ts:274`). On each tick, `touchAgent` and check
+  `nextPendingRequest`; when found, `markDelivered` and return the event JSON `{ type, request }`;
+  on timeout return `{ type: "timeout" }`. This held request IS presence.
+- `POST /api/agent/live/reply` — body `{ requestId, status }` where status is
+  `working | done | error`. Updates `live_request.state`. `done` on a generate/steer means the
+  agent finished committing (the actual edit already landed via tier-2).
+
+The agent commits the edit itself via existing `POST /api/agent/files/[...path]` with the
+deterministic idempotency key and `inResponseTo`. The live channel never writes files.
+
+### 3. Human-facing dispatch — `src/app/api/wiki/live/`
+
+Session-authed (Better Auth), CSRF-checked like other `/api/wiki/*` mutations.
+
+- `POST /api/wiki/live/request` — body `{ path, blockRef?, baseRevision?, kind, instruction? }`.
+  Resolves the workspace for the user, finds/creates the open session, enqueues a
+  `live_request`. Returns `{ requestId, seq }`.
+- `GET /api/wiki/live/status?path=` — returns `{ attached: boolean, session, lastRequest }`
+  so the editor can show whether an agent is on the line and the current turn state.
+
+Accept/revert are dispatched here too (`kind: 'accept' | 'discard'`) purely as notifications
+to the session; the actual activity tracking of the activity/audit provenance happens through the existing editor
+suggestion/proof UI and its normal API.
+
+### 4. Editor UI — `src/components/editor/`
+
+- Add `onAskAgent` to `EditorBubbleMenu` (bubble-menu.tsx) beside `onSuggestEdit`/`onComment`.
+- In `editor.tsx`, implement `openAskAgentForSelection()` using existing `resolveSelectionBlock()`
+  (editor.tsx:236) to get `{ blockRef, markdown }`, plus `currentPath` and current snapshot
+  `revision`. Open a small popover to type the instruction, then
+  `POST /api/wiki/live/request { kind: 'generate', path, blockRef, baseRevision, instruction }`.
+- A minimal "Live" status indicator (attached / waiting / working) driven by
+  `GET /api/wiki/live/status`. Steer = same popover again while a turn is open.
+- Proof-span appears through the existing SSE-watch reload; activity tracking use existing UI.
+
+## Correctness
+
+- **Stale intent:** the request stores `base_revision` at selection time. The agent must POST
+  with that `baseRevision`. If the human edited meanwhile, `applyOps` returns `STALE_REVISION`;
+  the agent replies `error`, the request is marked `stale`, UI asks for a fresh selection. No
+  silent re-interpretation.
+- **Replay:** `Idempotency-Key = live:<requestId>` makes a re-POST after agent crash return the
+  cached result; no duplicate edit. The request id is stable in `live_request`, so recovery
+  reuses it.
+- **One outstanding request per session:** `enqueueRequest` rejects a new `generate` while the
+  session has a non-terminal request. Reviewer-approved v1 constraint.
+- **Presence ambiguity:** `agent_last_seen` + TTL. Timeout => not attached. Reconnect resumes
+  from `afterSeq` (last delivered seq).
+
+## What we deliberately do NOT build
+
+Restated from proposal non-goals; enforced in review: no helper server, no injected JS, no HMR,
+no variants, no second write path / `applyLiveEdit`, no async-machinery deletion, no fuzzy
+recovery on the live path.