# F4 Propose/Accept Diff Flow Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Claude's edits arrive as pending, anchored, diff-rendered **proposals** the human accepts (applies via the `applyAgentEdit` seam → Claude-attributed) or rejects (document untouched), persisted git-natively in the sidecar's reserved `proposals[]`.

**Architecture:** One new vscode-free model slice (`Proposal` type + `proposalModel.ts` helpers) and one new editor-facing controller (`ProposalController`: second Comments controller `cowriting.proposals` with fenced-diff bodies + ✓/✗ title actions, amber pending-range decoration, resolve-or-flag ladder). The seam, AttributionController, Store, and Anchorer are reused unchanged except the store's anchor-prune learns proposal anchorIds. `editSelection` flips propose-by-default. Spec: `vscode-cowriting-plugin-content/specs/coauthoring-propose-accept.md` (graduated); Feature `#12`.

**Tech Stack:** TypeScript VS Code extension; vitest (unit, vscode-free); `@vscode/test-electron` + mocha (host E2E, no LLM); esbuild.

**Load-bearing invariants (spec §6.1):** INV-10 a proposal never mutates the document; INV-11 accept is fingerprint-guarded (exact-text resolve at decision time; stale/orphaned never applied — and a proposal's anchor is **immutable for its life**: proposals are NOT re-fingerprinted on save, unlike threads); INV-12 accept/reject are human-only; INV-13 `proposals[]` is pending-only.

---

### Task 1: Typed `Proposal` model + stable serialization

**Files:**
- Modify: `src/model.ts` (replace `proposals: unknown[]` with typed array; serialize)
- Test: `test/proposalModel.test.ts` (new)

- [ ] **Step 1: Write the failing round-trip test**

```typescript
// test/proposalModel.test.ts
import { describe, expect, it } from "vitest";
import {
  emptyArtifact,
  serializeArtifact,
  type Artifact,
  type Proposal,
} from "../src/model";

const agent = {
  kind: "agent" as const,
  id: "claude",
  agent: { sdk: "@cline/sdk", model: "sonnet", sessionId: "s1" },
};

describe("Proposal model (spec §6.3, INV-13)", () => {
  it("serializes proposals with stable field order and survives a round-trip", () => {
    const a = emptyArtifact("docs/x.md");
    a.anchors["a_1"] = {
      fingerprint: { text: "old text", before: "", after: "", lineHint: 0 },
    };
    const p: Proposal = {
      id: "pr_1",
      anchorId: "a_1",
      replacement: "new text",
      author: agent,
      createdAt: "2026-06-10T00:00:00.000Z",
      turnId: "turn-1",
      instruction: "tighten",
    };
    a.proposals.push(p);
    const reloaded = JSON.parse(serializeArtifact(a)) as Artifact;
    expect(reloaded.proposals).toHaveLength(1);
    expect(reloaded.proposals[0]).toEqual(p);
    // optional fields are OMITTED (not null) when absent
    const bare: Proposal = {
      id: "pr_2", anchorId: "a_1", replacement: "r", author: agent,
      createdAt: "2026-06-10T00:00:00.000Z",
    };
    a.proposals.push(bare);
    const again = JSON.parse(serializeArtifact(a)) as Artifact;
    expect("turnId" in again.proposals[1]).toBe(false);
    expect("instruction" in again.proposals[1]).toBe(false);
    // serialization is byte-stable (INV-2)
    expect(serializeArtifact(again)).toBe(serializeArtifact(a));
  });
});
```

- [ ] **Step 2: Run it to verify it fails**

Run: `npx vitest run test/proposalModel.test.ts`
Expected: FAIL — `Proposal` is not exported / `toEqual` mismatch (proposals pass through untyped today, so the import of `Proposal` fails compilation).

- [ ] **Step 3: Implement the typed model**

In `src/model.ts`, after the `AttributionRecord` interface, add:

```typescript
/** F4 (spec §6.3, INV-13): a PENDING machine edit — state, not history. */
export interface Proposal {
  id: string;
  /** shared anchors map; fingerprint.text IS the exact target text (INV-11). */
  anchorId: string;
  /** the full proposed text for the anchored range. */
  replacement: string;
  author: Provenance;
  /** ISO-8601. */
  createdAt: string;
  /** groups N proposals born of one live turn. */
  turnId?: string;
  /** what the human asked for (review context). */
  instruction?: string;
}
```

Change the `Artifact` field (and its comment) from `proposals: unknown[]` to:

```typescript
  /** F4 (spec §6.3, INV-13): pending proposals on shared anchors[] + Provenance. */
  proposals: Proposal[];
```

In `serializeArtifact`, replace `proposals: a.proposals,` with:

```typescript
    proposals: a.proposals.map((p) => ({
      id: p.id,
      anchorId: p.anchorId,
      replacement: p.replacement,
      author: serializeProvenance(p.author),
      createdAt: p.createdAt,
      ...(p.turnId !== undefined ? { turnId: p.turnId } : {}),
      ...(p.instruction !== undefined ? { instruction: p.instruction } : {}),
    })),
```

`SCHEMA_VERSION` stays `1` (additive fill of a reserved extension point — F3 precedent). `emptyArtifact` is already correct.

- [ ] **Step 4: Run the test to verify it passes**

Run: `npx vitest run test/proposalModel.test.ts`
Expected: PASS

- [ ] **Step 5: Typecheck + full unit suite (no regressions)**

Run: `npm run typecheck && npm test`
Expected: clean; all existing tests still pass.

- [ ] **Step 6: Commit**

```bash
git add src/model.ts test/proposalModel.test.ts
git commit -m "F4 SLICE-1: typed proposals[] on shared anchors/Provenance (spec §6.3, INV-13) (#12)"
```

---

### Task 2: Store anchor-prune learns proposal anchors

**Files:**
- Modify: `src/store.ts:63-77` (the `update` prune)
- Test: `test/proposalModel.test.ts` (append)

- [ ] **Step 1: Write the failing prune test**

Append to `test/proposalModel.test.ts`:

```typescript
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { CoauthorStore } from "../src/store";

describe("CoauthorStore prune with proposals (spec §6.3)", () => {
  it("retains anchors referenced only by proposals; prunes them after removal", () => {
    const dir = mkdtempSync(join(tmpdir(), "cowriting-prune-"));
    try {
      const store = new CoauthorStore(dir);
      store.update("docs/x.md", (a) => {
        a.anchors["a_p"] = {
          fingerprint: { text: "t", before: "", after: "", lineHint: 0 },
        };
        a.proposals.push({
          id: "pr_1", anchorId: "a_p", replacement: "r", author: agent,
          createdAt: "2026-06-10T00:00:00.000Z",
        });
      });
      expect(store.load("docs/x.md")!.anchors["a_p"]).toBeDefined();
      store.update("docs/x.md", (a) => {
        a.proposals = a.proposals.filter((p) => p.id !== "pr_1");
      });
      expect(store.load("docs/x.md")!.anchors["a_p"]).toBeUndefined();
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });
});
```

- [ ] **Step 2: Run it to verify it fails**

Run: `npx vitest run test/proposalModel.test.ts`
Expected: FAIL — `anchors["a_p"]` is `undefined` after the FIRST update (today's prune doesn't count proposals, so the anchor is pruned immediately).

- [ ] **Step 3: Extend the prune**

In `src/store.ts` `update()`, replace the `referenced` set construction with:

```typescript
    const referenced = new Set<string>([
      ...artifact.threads.map((t) => t.anchorId),
      ...artifact.attributions.map((a) => a.anchorId),
      ...artifact.proposals.map((p) => p.anchorId),
    ]);
```

Also update the method's doc comment: change "(proposals are still empty in F3 — revisit in F4)" to "(threads, attributions, AND proposals all keep their anchors — F4)".

- [ ] **Step 4: Run tests to verify they pass**

Run: `npx vitest run test/proposalModel.test.ts && npm test`
Expected: PASS (all suites).

- [ ] **Step 5: Commit**

```bash
git add src/store.ts test/proposalModel.test.ts
git commit -m "F4 SLICE-1: anchor prune counts proposal anchorIds (closes store.ts F4 TODO) (#12)"
```

---

### Task 3: `proposalModel.ts` pure helpers (add / remove / diff body)

**Files:**
- Create: `src/proposalModel.ts`
- Test: `test/proposalModel.test.ts` (append)

- [ ] **Step 1: Write the failing tests**

Append to `test/proposalModel.test.ts`:

```typescript
import { addProposal, proposalBody, removeProposal } from "../src/proposalModel";

describe("proposalModel helpers (spec §6.4)", () => {
  const fp = { text: "old line one\nold line two", before: "", after: "", lineHint: 3 };

  it("addProposal creates the anchor + pending record; removeProposal deletes by id", () => {
    const a = emptyArtifact("docs/x.md");
    const { proposalId, anchorId } = addProposal(a, fp, "new line", agent, {
      turnId: "turn-9", instruction: "shorten",
    });
    expect(a.anchors[anchorId].fingerprint).toEqual(fp);
    expect(a.proposals).toHaveLength(1);
    expect(a.proposals[0].id).toBe(proposalId);
    expect(a.proposals[0].replacement).toBe("new line");
    expect(a.proposals[0].turnId).toBe("turn-9");
    expect(a.proposals[0].instruction).toBe("shorten");
    expect(removeProposal(a, proposalId)).toBe(true);
    expect(a.proposals).toHaveLength(0);
    expect(removeProposal(a, proposalId)).toBe(false);
  });

  it("proposalBody renders instruction + a fenced unified diff of old → new", () => {
    const a = emptyArtifact("docs/x.md");
    addProposal(a, fp, "new only line", agent, { instruction: "merge the lines" });
    const body = proposalBody(fp.text, a.proposals[0]);
    expect(body).toContain("**Claude proposes** — _merge the lines_");
    expect(body).toContain("```diff");
    expect(body).toContain("- old line one");
    expect(body).toContain("- old line two");
    expect(body).toContain("+ new only line");
  });
});
```

- [ ] **Step 2: Run to verify failure**

Run: `npx vitest run test/proposalModel.test.ts`
Expected: FAIL — module `../src/proposalModel` not found.

- [ ] **Step 3: Implement `src/proposalModel.ts`**

```typescript
/**
 * proposalModel — pure helpers over the F4 `proposals[]` section (spec §6.3,
 * INV-13: pending-only). Mirrors threadModel.ts: vscode-free mutations against
 * an Artifact, used inside CoauthorStore.update() by ProposalController.
 * The diff body is PRESENTATION ONLY — the truth is fingerprint.text →
 * replacement (INV-11); a whole-range -/+ rendering, not an LCS diff (§6.7).
 */
import { newId, type Artifact, type Fingerprint, type Proposal, type Provenance } from "./model";

export function addProposal(
  artifact: Artifact,
  fp: Fingerprint,
  replacement: string,
  author: Provenance,
  opts?: { turnId?: string; instruction?: string },
): { proposalId: string; anchorId: string } {
  const anchorId = newId("a");
  const proposalId = newId("pr");
  artifact.anchors[anchorId] = { fingerprint: fp };
  artifact.proposals.push({
    id: proposalId,
    anchorId,
    replacement,
    author,
    createdAt: new Date().toISOString(),
    ...(opts?.turnId !== undefined ? { turnId: opts.turnId } : {}),
    ...(opts?.instruction !== undefined ? { instruction: opts.instruction } : {}),
  });
  return { proposalId, anchorId };
}

/** Remove a pending proposal (accept and reject both end here — INV-13). */
export function removeProposal(artifact: Artifact, proposalId: string): boolean {
  const before = artifact.proposals.length;
  artifact.proposals = artifact.proposals.filter((p) => p.id !== proposalId);
  return artifact.proposals.length < before;
}

/** Markdown comment body: instruction header + fenced whole-range diff. */
export function proposalBody(targetText: string, p: Proposal): string {
  const header = p.instruction ? `**Claude proposes** — _${p.instruction}_` : "**Claude proposes**";
  const diffLines = [
    ...targetText.split("\n").map((l) => `- ${l}`),
    ...p.replacement.split("\n").map((l) => `+ ${l}`),
  ].join("\n");
  return `${header}\n\n\`\`\`diff\n${diffLines}\n\`\`\`\n\n✓ Accept applies this replacement · ✗ Reject discards it`;
}
```

- [ ] **Step 4: Run tests + typecheck**

Run: `npx vitest run test/proposalModel.test.ts && npm run typecheck`
Expected: PASS / clean.

- [ ] **Step 5: Commit**

```bash
git add src/proposalModel.ts test/proposalModel.test.ts
git commit -m "F4 SLICE-1: proposalModel helpers — add/remove + fenced-diff body (#12)"
```

---

### Task 4: `ProposalController` (propose · render · live-shift · accept · reject)

**Files:**
- Create: `src/proposalController.ts`

This is the editor-facing layer — verified by typecheck/build now, host E2E in Task 7. Key behavioral notes baked into the code: proposals are persisted **at propose time**; their anchors are **never re-fingerprinted** (INV-11 — deliberate deviation from ThreadController's `onDidSave`); accept re-resolves at decision time and refuses on "orphaned"; the seam call carries `expectedVersion: document.version` captured synchronously.

- [ ] **Step 1: Write `src/proposalController.ts`**

```typescript
/**
 * ProposalController — the editor-facing layer for F4 (spec
 * coauthoring-propose-accept §6.2). Owns the proposal lifecycle: the propose
 * ingress (INV-10: NEVER mutates the document), persistence at propose time,
 * resolve-or-flag on load/external change (INV-11 — a proposal's anchor is
 * immutable for its life: no save-time re-fingerprint, unlike threads),
 * rendering (second Comments controller + amber pending-range decoration),
 * and the human-only accept/reject gestures (INV-12). Accept drives the seam
 * (AttributionController.applyAgentEdit, INV-9) so accepted text lands
 * Claude-attributed with zero new attribution code.
 */
import * as vscode from "vscode";
import { CoauthorStore } from "./store";
import { emptyArtifact, type Artifact, type Fingerprint, type Proposal, type Provenance } from "./model";
import { resolve, shift, type OffsetRange } from "./anchorer";
import { addProposal, proposalBody, removeProposal } from "./proposalModel";
import type { AttributionController } from "./attributionController";

/** Test-facing snapshot of what is currently rendered for a document. */
export interface RenderedProposal {
  id: string;
  /** true → resolves exactly, decidable; false → stale/orphaned (INV-11). */
  pending: boolean;
  turnId?: string;
  range: { start: number; end: number };
}

interface DocState {
  docPath: string;
  uri: vscode.Uri;
  artifact: Artifact;
  vsThreads: Map<string, vscode.CommentThread>;
  /** proposal id -> live offset range (within-session optimization, INV-3). */
  live: Map<string, OffsetRange>;
  /** proposal ids whose anchor did not resolve at last render (stale/orphaned). */
  unresolved: Set<string>;
}

const PENDING_DECO: vscode.DecorationRenderOptions = {
  backgroundColor: "rgba(245, 158, 11, 0.18)",
  overviewRulerColor: "rgba(245, 158, 11, 0.8)",
  overviewRulerLane: vscode.OverviewRulerLane.Right,
};

export class ProposalController implements vscode.Disposable {
  private readonly controller: vscode.CommentController;
  private readonly disposables: vscode.Disposable[] = [];
  private readonly docs = new Map<string, DocState>(); // keyed by docPath
  private readonly pendingType = vscode.window.createTextEditorDecorationType(PENDING_DECO);
  private readonly statusItem = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Right, 89);

  constructor(
    private readonly store: CoauthorStore,
    private readonly attribution: AttributionController,
    private readonly rootDir: string,
  ) {
    // No commentingRangeProvider: humans never open proposal threads by hand —
    // proposals are born of machine turns only (INV-12 keeps decisions human).
    this.controller = vscode.comments.createCommentController("cowriting.proposals", "Claude Proposals");
    this.disposables.push(this.controller, this.pendingType, this.statusItem);
    this.disposables.push(
      vscode.commands.registerCommand("cowriting.acceptProposal", (t: vscode.CommentThread) => this.acceptThread(t)),
      vscode.commands.registerCommand("cowriting.rejectProposal", (t: vscode.CommentThread) => this.rejectThread(t)),
      vscode.workspace.onDidChangeTextDocument((e) => this.onDidChange(e)),
    );
  }

  private isTracked(document: vscode.TextDocument): boolean {
    return document.uri.scheme === "file" && document.uri.fsPath.startsWith(this.rootDir);
  }
  private docPathOf(uri: vscode.Uri): string {
    return vscode.workspace.asRelativePath(uri, false);
  }
  private ensureState(document: vscode.TextDocument): DocState {
    const docPath = this.docPathOf(document.uri);
    let state = this.docs.get(docPath);
    if (!state) {
      state = {
        docPath,
        uri: document.uri,
        artifact: this.store.load(docPath) ?? emptyArtifact(docPath),
        vsThreads: new Map(),
        live: new Map(),
        unresolved: new Set(),
      };
      this.docs.set(docPath, state);
    }
    return state;
  }

  // ---- PUC-1: the propose ingress (INV-10) -----------------------------------------

  /**
   * Record + render a pending proposal. The fingerprint is built by the CALLER
   * at gesture time (editSelection captures it BEFORE the turn, so mid-turn
   * edits can't skew the anchor). Never touches the document.
   */
  async propose(
    document: vscode.TextDocument,
    fp: Fingerprint,
    replacement: string,
    author: Provenance,
    opts?: { turnId?: string; instruction?: string },
  ): Promise<string | undefined> {
    if (!this.isTracked(document)) return undefined;
    const docPath = this.docPathOf(document.uri);
    let proposalId: string | undefined;
    this.store.update(docPath, (a) => {
      proposalId = addProposal(a, fp, replacement, author, opts).proposalId;
    });
    this.renderAll(document);
    return proposalId;
  }

  // ---- PUC-2/PUC-3: accept / reject (INV-11/INV-12) ----------------------------------

  /** Accept by proposal id (test-facing twin of the thread-menu gesture). */
  async acceptById(docPath: string, proposalId: string): Promise<boolean> {
    const hit = this.byId(docPath, proposalId);
    return hit ? this.accept(hit.state, hit.proposal) : false;
  }
  /** Reject by proposal id (test-facing twin of the thread-menu gesture). */
  rejectById(docPath: string, proposalId: string): boolean {
    const hit = this.byId(docPath, proposalId);
    if (!hit) return false;
    this.reject(hit.state, hit.proposal);
    return true;
  }

  private async acceptThread(vsThread: vscode.CommentThread): Promise<void> {
    const hit = this.byThread(vsThread);
    if (hit) await this.accept(hit.state, hit.proposal);
  }
  private rejectThread(vsThread: vscode.CommentThread): void {
    const hit = this.byThread(vsThread);
    if (hit) this.reject(hit.state, hit.proposal);
  }

  private async accept(state: DocState, proposal: Proposal): Promise<boolean> {
    const document = this.openDoc(state);
    if (!document) return false;
    // INV-11: the fingerprint-guard — exact re-resolve at decision time.
    const fp = state.artifact.anchors[proposal.anchorId]?.fingerprint;
    const resolved = fp ? resolve(document.getText(), fp) : "orphaned";
    if (resolved === "orphaned") {
      void vscode.window.showWarningMessage(
        "Cowriting: this proposal's target text changed or is missing — undo to restore it, or reject to discard (it is never applied by guess).",
      );
      this.renderAll(document);
      return false;
    }
    const range = new vscode.Range(document.positionAt(resolved.start), document.positionAt(resolved.end));
    // No awaits between resolve and the seam call: document.version is current.
    const ok = await this.attribution.applyAgentEdit(document, range, proposal.replacement, proposal.author, {
      expectedVersion: document.version,
      turnId: proposal.turnId,
    });
    if (!ok) {
      void vscode.window.showWarningMessage(
        "Cowriting: the editor rejected the accept — the proposal is still pending.",
      );
      return false;
    }
    this.store.update(state.docPath, (a) => removeProposal(a, proposal.id));
    this.renderAll(document);
    return true;
  }

  private reject(state: DocState, proposal: Proposal): void {
    this.store.update(state.docPath, (a) => removeProposal(a, proposal.id));
    const document = this.openDoc(state);
    if (document) this.renderAll(document);
  }

  // ---- PUC-4: load / external change / resolve-or-flag --------------------------------

  /** Load + (re)render every pending proposal at its resolved anchor (or flagged). */
  renderAll(document: vscode.TextDocument): void {
    if (!this.isTracked(document)) return;
    const docPath = this.docPathOf(document.uri);
    const state = this.ensureState(document);
    state.artifact = this.store.load(docPath) ?? emptyArtifact(docPath);
    for (const vsThread of state.vsThreads.values()) vsThread.dispose();
    state.vsThreads.clear();
    state.live.clear();
    state.unresolved.clear();
    const text = document.getText();
    for (const proposal of state.artifact.proposals) {
      const fp = state.artifact.anchors[proposal.anchorId]?.fingerprint;
      const resolved = fp ? resolve(text, fp) : "orphaned";
      if (resolved === "orphaned") {
        const line = fp ? Math.min(fp.lineHint, Math.max(0, document.lineCount - 1)) : 0;
        const off = document.offsetAt(new vscode.Position(line, 0));
        this.renderProposal(document, state, proposal, { start: off, end: off }, false);
      } else {
        this.renderProposal(document, state, proposal, resolved, true);
      }
    }
    this.renderDecorations(document, state);
    this.renderStatus(state);
  }

  /** Shared-watcher entry point (extension.ts): a sidecar changed externally. */
  handleExternalSidecarChange(uri: vscode.Uri): void {
    for (const state of this.docs.values()) {
      if (this.store.sidecarPath(state.docPath) === uri.fsPath) {
        const doc = vscode.workspace.textDocuments.find((d) => this.docPathOf(d.uri) === state.docPath);
        if (doc) this.renderAll(doc);
      }
    }
  }

  private onDidChange(e: vscode.TextDocumentChangeEvent): void {
    const state = this.docs.get(this.docPathOf(e.document.uri));
    if (!state || state.live.size === 0) return;
    for (const change of e.contentChanges) {
      const edit = { start: change.rangeOffset, end: change.rangeOffset + change.rangeLength, newLength: change.text.length };
      for (const [id, range] of state.live) {
        const next = shift(range, edit);
        state.live.set(id, next);
        const vsThread = state.vsThreads.get(id);
        if (vsThread && !state.unresolved.has(id)) {
          vsThread.range = new vscode.Range(e.document.positionAt(next.start), e.document.positionAt(next.end));
        }
      }
    }
    // Live shift keeps the UI following; staleness is judged at decision time
    // (accept re-resolves, INV-11) and at the next renderAll.
    this.renderDecorations(e.document, state);
  }

  // ---- rendering -----------------------------------------------------------------------

  private renderProposal(
    document: vscode.TextDocument,
    state: DocState,
    proposal: Proposal,
    offsets: OffsetRange,
    pending: boolean,
  ): void {
    const fp = state.artifact.anchors[proposal.anchorId]?.fingerprint;
    const range = new vscode.Range(document.positionAt(offsets.start), document.positionAt(offsets.end));
    const vsThread = this.controller.createCommentThread(document.uri, range, [
      {
        body: new vscode.MarkdownString(proposalBody(fp?.text ?? "", proposal)),
        mode: vscode.CommentMode.Preview,
        author: { name: proposal.author.id },
      },
    ]);
    vsThread.label = pending ? "Pending proposal" : "⚠ Stale proposal (target text changed or missing) — accept disabled";
    vsThread.contextValue = pending ? "pending" : "unresolved";
    vsThread.collapsibleState = pending
      ? vscode.CommentThreadCollapsibleState.Expanded
      : vscode.CommentThreadCollapsibleState.Collapsed;
    state.vsThreads.set(proposal.id, vsThread);
    state.live.set(proposal.id, offsets);
    if (!pending) state.unresolved.add(proposal.id);
  }

  private renderDecorations(document: vscode.TextDocument, state: DocState): void {
    const ranges: vscode.Range[] = [];
    for (const [id, off] of state.live) {
      if (state.unresolved.has(id)) continue;
      ranges.push(new vscode.Range(document.positionAt(off.start), document.positionAt(off.end)));
    }
    for (const editor of vscode.window.visibleTextEditors) {
      if (editor.document === document) editor.setDecorations(this.pendingType, ranges);
    }
  }

  private renderStatus(state: DocState): void {
    const n = state.unresolved.size;
    if (n === 0) {
      this.statusItem.hide();
      return;
    }
    this.statusItem.text = `$(warning) ${n} stale proposal${n === 1 ? "" : "s"}`;
    this.statusItem.tooltip = "Cowriting: proposals whose target text changed or is missing — undo to restore, or reject";
    this.statusItem.show();
  }

  // ---- lookups ----------------------------------------------------------------------------

  private openDoc(state: DocState): vscode.TextDocument | undefined {
    return vscode.workspace.textDocuments.find((d) => this.docPathOf(d.uri) === state.docPath);
  }
  private byThread(vsThread: vscode.CommentThread): { state: DocState; proposal: Proposal } | undefined {
    for (const state of this.docs.values()) {
      for (const [id, t] of state.vsThreads) {
        if (t === vsThread) {
          const proposal = state.artifact.proposals.find((p) => p.id === id);
          if (proposal) return { state, proposal };
        }
      }
    }
    return undefined;
  }
  private byId(docPath: string, proposalId: string): { state: DocState; proposal: Proposal } | undefined {
    const state = this.docs.get(docPath);
    const proposal = state?.artifact.proposals.find((p) => p.id === proposalId);
    return state && proposal ? { state, proposal } : undefined;
  }

  // ---- test-facing surface ------------------------------------------------------------------

  getRendered(docPath: string): RenderedProposal[] {
    const state = this.docs.get(docPath);
    if (!state) return [];
    const out: RenderedProposal[] = [];
    for (const [id] of state.vsThreads) {
      const p = state.artifact.proposals.find((x) => x.id === id)!;
      const off = state.live.get(id)!;
      out.push({
        id,
        pending: !state.unresolved.has(id),
        turnId: p.turnId,
        range: { start: off.start, end: off.end },
      });
    }
    return out;
  }
  getStaleCount(docPath: string): number {
    return this.docs.get(docPath)?.unresolved.size ?? 0;
  }

  dispose(): void {
    for (const d of this.disposables) d.dispose();
  }
}
```

- [ ] **Step 2: Typecheck + build**

Run: `npm run typecheck && npm run build`
Expected: clean (the file compiles standalone; nothing imports it yet).

- [ ] **Step 3: Commit**

```bash
git add src/proposalController.ts
git commit -m "F4 SLICE-2/3: ProposalController — propose ingress, resolve-or-flag, diff threads, accept/reject via the seam (#12)"
```

---

### Task 5: Wire it up — `package.json` contributes + `extension.ts`

**Files:**
- Modify: `package.json` (commands + menus)
- Modify: `src/extension.ts` (controller, watcher fan-out, renderIfOpen, hidden propose command, no-workspace stubs, API export)

- [ ] **Step 1: Add commands + menus to `package.json`**

In `contributes.commands`, add (after the `cowriting.editSelection` entry):

```json
      { "command": "cowriting.acceptProposal", "title": "✓ Accept Proposal", "category": "Cowriting" },
      { "command": "cowriting.rejectProposal", "title": "✗ Reject Proposal", "category": "Cowriting" },
      { "command": "cowriting.proposeAgentEdit", "title": "Propose Agent Edit (internal seam)", "category": "Cowriting" }
```

In `contributes.menus.commandPalette`, add:

```json
        { "command": "cowriting.proposeAgentEdit", "when": "false" },
        { "command": "cowriting.acceptProposal", "when": "false" },
        { "command": "cowriting.rejectProposal", "when": "false" }
```

In `contributes.menus["comments/commentThread/title"]`, add:

```json
        {
          "command": "cowriting.acceptProposal",
          "group": "inline@1",
          "when": "commentController == cowriting.proposals && commentThread =~ /^pending$/"
        },
        {
          "command": "cowriting.rejectProposal",
          "group": "inline@2",
          "when": "commentController == cowriting.proposals"
        }
```

(Accept is offered only on `pending` threads — the menu mirrors the INV-11 guard the code enforces; reject is always available, including for stale ones.)

- [ ] **Step 2: Wire `extension.ts`**

Add imports:

```typescript
import { ProposalController } from "./proposalController";
import { buildFingerprint } from "./anchorer";
```

Extend the API type:

```typescript
export interface CowritingApi {
  threadController: ThreadController;
  attributionController: AttributionController;
  proposalController: ProposalController;
}
```

In the no-workspace stub list, add the three new commands (every contributed command must exist — #8):

```typescript
      "cowriting.acceptProposal",
      "cowriting.rejectProposal",
      "cowriting.proposeAgentEdit",
```

After the AttributionController construction, add:

```typescript
  // --- F4: propose/accept (Feature #12) ---
  const proposalController = new ProposalController(store, attributionController, root);
  context.subscriptions.push(proposalController);
```

In the shared-watcher `onSidecar` fan-out, add:

```typescript
    proposalController.handleExternalSidecarChange(uri);
```

After the `cowriting.applyAgentEdit` command registration, add the propose ingress command (the E2E entry point — INV-10):

```typescript
  // The propose ingress as a command (spec §6.4): records a pending proposal,
  // NEVER touches the document (INV-10) — for the host E2E harness.
  context.subscriptions.push(
    vscode.commands.registerCommand(
      "cowriting.proposeAgentEdit",
      (args: {
        uri: string; start: number; end: number; newText: string;
        model?: string; sessionId?: string; turnId?: string; instruction?: string;
      }) => {
        const doc = vscode.workspace.textDocuments.find((d) => d.uri.toString() === args.uri);
        if (!doc) return Promise.resolve(undefined);
        const fp = buildFingerprint(doc.getText(), { start: args.start, end: args.end });
        const provenance = {
          kind: "agent" as const,
          id: "claude",
          agent: { sdk: "@cline/sdk", model: args.model ?? "sonnet", sessionId: args.sessionId ?? "" },
        };
        return proposalController.propose(doc, fp, args.newText, provenance, {
          turnId: args.turnId,
          instruction: args.instruction,
        });
      },
    ),
  );
```

In `renderIfOpen`, add:

```typescript
      proposalController.renderAll(doc);
```

And return the extended API:

```typescript
  return { threadController, attributionController, proposalController };
```

- [ ] **Step 3: Typecheck + build + unit suite**

Run: `npm run typecheck && npm run build && npm test`
Expected: clean.

- [ ] **Step 4: Commit**

```bash
git add package.json src/extension.ts
git commit -m "F4 SLICE-3: wire ProposalController — contributes, watcher fan-out, propose command, stubs, API (#12)"
```

---

### Task 6: Flip `editSelection` propose-by-default (SLICE-4)

**Files:**
- Modify: `src/extension.ts` (the `cowriting.editSelection` handler only)

- [ ] **Step 1: Retarget the live turn**

Replace the `cowriting.editSelection` handler body from `const document = editor.document;` down through the end of the `withProgress` block with:

```typescript
      const document = editor.document;
      const selection = editor.selection;
      const selectedText = document.getText(selection);
      // Capture the anchor BEFORE the turn (spec §6.5 PUC-1): mid-turn edits
      // can't skew it — the proposal renders wherever the target re-resolves.
      const fp = buildFingerprint(document.getText(), {
        start: document.offsetAt(selection.start),
        end: document.offsetAt(selection.end),
      });
      const turnId = `turn-${Date.now().toString(36)}`;
      try {
        await vscode.window.withProgress(
          { location: vscode.ProgressLocation.Notification, title: "Cowriting: asking Claude…" },
          async () => {
            const { runEditTurn } = await import("./liveTurn");
            const turn = await runEditTurn(instruction, selectedText);
            if (turn.replacement === "") {
              void vscode.window.showWarningMessage(
                "Cowriting: Claude returned an empty replacement — nothing was proposed.",
              );
              return;
            }
            if (turn.replacement === selectedText) {
              void vscode.window.showInformationMessage(
                "Cowriting: Claude proposed no change to the selection.",
              );
              return;
            }
            // F4 (INV-10): the turn ends in a PROPOSAL, not a buffer mutation.
            // The seam now fires only on accept (ProposalController, INV-9).
            const id = await proposalController.propose(
              document,
              fp,
              turn.replacement,
              {
                kind: "agent",
                id: "claude",
                agent: { sdk: "@cline/sdk", model: turn.model, sessionId: turn.sessionId },
              },
              { turnId, instruction },
            );
            if (id) {
              void vscode.window.showInformationMessage(
                "Cowriting: Claude proposed an edit — review the diff at the highlighted range (✓ accept / ✗ reject).",
              );
            }
          },
        );
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        void vscode.window.showErrorMessage(`Cowriting: Claude edit failed — ${message}`);
      }
```

(The old `expectedVersion` capture is gone — propose applies nothing, so there is no version race at propose time. The dropped variable was only used by the removed `applyAgentEdit` call. The comment above the command registration should also change from "→ the applyAgentEdit seam (INV-9)" to "→ a pending proposal (F4, INV-10); the seam fires on accept".)

- [ ] **Step 2: Typecheck + build + unit suite**

Run: `npm run typecheck && npm run build && npm test`
Expected: clean — F3's E2E entry points (`applyAgentEdit` API + command) are untouched; only the live-turn tail moved.

- [ ] **Step 3: Commit**

```bash
git add src/extension.ts
git commit -m "F4 SLICE-4: editSelection is propose-by-default — the turn ends in a proposal, the seam fires on accept (#12)"
```

---

### Task 7: Host E2E (SLICE-5) — propose/accept/reject/persist/stale/coexist, no LLM

**Files:**
- Create: `test/e2e/fixtures/workspace/docs/proposal.md`
- Create: `test/e2e/suite/proposals.test.ts`

- [ ] **Step 1: Add the fixture document** (this suite OWNS `docs/proposal.md`; the F2 suite owns `docs/sample.md`, F3 owns `docs/attrib.md` — keep fixtures disjoint)

```markdown
# Proposal fixture

A stable opening paragraph.

The propose target sentence lives here.

A second target for coexistence checks.

A stable closing paragraph.
```

- [ ] **Step 2: Write `test/e2e/suite/proposals.test.ts`**

```typescript
import * as assert from "assert";
import * as fs from "fs";
import * as path from "path";
import * as vscode from "vscode";
import type { CowritingApi } from "../../../src/extension";
import type { Artifact } from "../../../src/model";

const WS = process.env.E2E_WORKSPACE!;
const DOC_REL = "docs/proposal.md";

function sidecarPath(): string {
  return path.join(WS, ".threads", "docs", "proposal.md.json");
}
function readSidecar(): Artifact {
  return JSON.parse(fs.readFileSync(sidecarPath(), "utf8")) as Artifact;
}
async function openDoc(): Promise<vscode.TextDocument> {
  const uri = vscode.Uri.file(path.join(WS, DOC_REL));
  const doc = await vscode.workspace.openTextDocument(uri);
  await vscode.window.showTextDocument(doc);
  return doc;
}
async function getApi(): Promise<CowritingApi> {
  const ext = vscode.extensions.getExtension("benstull.vscode-cowriting-plugin")!;
  const api = (await ext.activate()) as CowritingApi;
  assert.ok(api?.proposalController, "extension exports proposalController");
  return api;
}
async function proposeViaCommand(
  doc: vscode.TextDocument,
  target: string,
  newText: string,
  turnId: string,
): Promise<string> {
  const start = doc.getText().indexOf(target);
  assert.ok(start >= 0, `fixture contains "${target}"`);
  const id = await vscode.commands.executeCommand<string>("cowriting.proposeAgentEdit", {
    uri: doc.uri.toString(),
    start,
    end: start + target.length,
    newText,
    model: "sonnet",
    sessionId: "e2e-prop",
    turnId,
    instruction: "e2e instruction",
  });
  assert.ok(id, "propose returns the proposal id");
  return id!;
}
async function externalWriteAndReload(uri: vscode.Uri, content: string): Promise<vscode.TextDocument> {
  fs.writeFileSync(uri.fsPath, content, "utf8");
  const doc = await vscode.workspace.openTextDocument(uri);
  await vscode.window.showTextDocument(doc);
  await vscode.commands.executeCommand("workbench.action.files.revert");
  return doc;
}
const settle = () => new Promise((r) => setTimeout(r, 300));

// Tests are ORDER-DEPENDENT (F2/F3 pattern): later tests consume earlier state.
suite("F4 propose/accept (host E2E — programmatic ingress, no LLM)", () => {
  const TARGET = "The propose target sentence lives here.";
  const REPLACEMENT = "PROPOSED-BY-CLAUDE replacement sentence.";

  test("propose records + renders a pending proposal and does NOT touch the document (INV-10)", async () => {
    const doc = await openDoc();
    const api = await getApi();
    const before = doc.getText();
    await proposeViaCommand(doc, TARGET, REPLACEMENT, "turn-p1");
    await settle();
    assert.strictEqual(doc.getText(), before, "document text unchanged (INV-10)");
    const rendered = api.proposalController.getRendered(DOC_REL);
    assert.strictEqual(rendered.length, 1);
    assert.strictEqual(rendered[0].pending, true);
    assert.strictEqual(rendered[0].turnId, "turn-p1");
    const art = readSidecar();
    assert.strictEqual(art.proposals.length, 1, "proposal persisted at propose time");
    assert.strictEqual(art.anchors[art.proposals[0].anchorId].fingerprint.text, TARGET);
  });

  test("accept applies via the seam: text replaced, Claude-attributed, proposal removed (INV-9/11/13)", async () => {
    const doc = await openDoc();
    const api = await getApi();
    const id = api.proposalController.getRendered(DOC_REL)[0].id;
    const ok = await api.proposalController.acceptById(DOC_REL, id);
    assert.strictEqual(ok, true, "accept applies");
    await settle();
    assert.ok(doc.getText().includes(REPLACEMENT), "replacement landed");
    assert.ok(!doc.getText().includes(TARGET), "target gone");
    const spans = api.attributionController.getSpans(DOC_REL);
    const agent = spans.find((s) => s.turnId === "turn-p1");
    assert.ok(agent, "accepted text is Claude-attributed with the proposal's turnId");
    assert.strictEqual(agent!.authorKind, "agent");
    assert.strictEqual(api.proposalController.getRendered(DOC_REL).length, 0, "proposal gone (INV-13)");
    assert.strictEqual(readSidecar().proposals.length, 0, "removed from the sidecar");
  });

  test("reject leaves the document untouched and removes the proposal (PUC-3)", async () => {
    const doc = await openDoc();
    const api = await getApi();
    const before = doc.getText();
    const id = await proposeViaCommand(doc, "A second target for coexistence checks.", "WOULD-BE replacement.", "turn-p2");
    await settle();
    assert.strictEqual(api.proposalController.rejectById(DOC_REL, id), true);
    await settle();
    assert.strictEqual(doc.getText(), before, "document untouched");
    assert.strictEqual(api.proposalController.getRendered(DOC_REL).length, 0);
    assert.strictEqual(readSidecar().proposals.length, 0);
  });

  test("a pending proposal persists, survives reload, and re-anchors after an external move (PUC-4)", async () => {
    let doc = await openDoc();
    const api = await getApi();
    const anchor = "A stable closing paragraph.";
    await proposeViaCommand(doc, anchor, "A PROPOSED closing paragraph.", "turn-p3");
    await settle();
    const uri = vscode.Uri.file(path.join(WS, DOC_REL));
    doc = await externalWriteAndReload(uri, "PREPENDED LINE\n\n" + doc.getText());
    await settle();
    api.proposalController.renderAll(doc);
    const rendered = api.proposalController.getRendered(DOC_REL);
    assert.strictEqual(rendered.length, 1, "proposal survived reload");
    assert.strictEqual(rendered[0].pending, true, "still decidable");
    const moved = doc.getText().indexOf(anchor);
    assert.strictEqual(rendered[0].range.start, moved, "re-anchored after the move");
  });

  test("editing the target text makes the proposal stale: flagged, accept refused, doc untouched (INV-11)", async () => {
    let doc = await openDoc();
    const api = await getApi();
    const id = api.proposalController.getRendered(DOC_REL)[0].id;
    const mangled = doc.getText().replace("A stable closing paragraph.", "A reworded closing paragraph.");
    doc = await externalWriteAndReload(vscode.Uri.file(path.join(WS, DOC_REL)), mangled);
    await settle();
    api.proposalController.renderAll(doc);
    assert.strictEqual(api.proposalController.getStaleCount(DOC_REL), 1, "flagged stale");
    const before = doc.getText();
    const ok = await api.proposalController.acceptById(DOC_REL, id);
    assert.strictEqual(ok, false, "accept refused (INV-11)");
    assert.strictEqual(doc.getText(), before, "document untouched");
    assert.strictEqual(readSidecar().proposals.length, 1, "proposal still pending (recoverable)");
    // discard the husk so later suites see a clean sidecar
    assert.strictEqual(api.proposalController.rejectById(DOC_REL, id), true);
  });

  test("multiple pending proposals coexist and are decidable out of order (PUC-5)", async () => {
    const doc = await openDoc();
    const api = await getApi();
    const id1 = await proposeViaCommand(doc, "A stable opening paragraph.", "An ACCEPTED opening paragraph.", "turn-p4");
    const id2 = await proposeViaCommand(doc, "PROPOSED-BY-CLAUDE replacement sentence.", "A REPLACED-AGAIN sentence.", "turn-p5");
    await settle();
    assert.strictEqual(api.proposalController.getRendered(DOC_REL).length, 2);
    // decide the SECOND first, then the first — order independence
    assert.strictEqual(await api.proposalController.acceptById(DOC_REL, id2), true);
    await settle();
    assert.strictEqual(await api.proposalController.acceptById(DOC_REL, id1), true);
    await settle();
    assert.ok(doc.getText().includes("An ACCEPTED opening paragraph."));
    assert.ok(doc.getText().includes("A REPLACED-AGAIN sentence."));
    assert.strictEqual(api.proposalController.getRendered(DOC_REL).length, 0);
  });
});
```

- [ ] **Step 3: Check the no-workspace pass** — read `test/e2e/suite/` for the #8 regression test; if it enumerates contributed commands, add `cowriting.acceptProposal`, `cowriting.rejectProposal`, `cowriting.proposeAgentEdit` to its list (the stubs were added in Task 5).

- [ ] **Step 4: Run the full E2E suite**

Run: `npm run pretest:e2e && npm run test:e2e`
Expected: all suites pass (F2 threads, F3 attribution, F4 proposals, no-workspace pass).

- [ ] **Step 5: Commit**

```bash
git add test/e2e/fixtures/workspace/docs/proposal.md test/e2e/suite/proposals.test.ts
git commit -m "F4 SLICE-5: host E2E — propose/accept/reject/persist/re-anchor/stale/coexist, no LLM in CI (#12)"
```

---

### Task 8: Docs + full gate

**Files:**
- Modify: `docs/MANUAL-SMOKE-F3.md` (the live flow now ends in a proposal)
- Create: `docs/MANUAL-SMOKE-F4.md`
- Modify: `README.md` (features)
- Modify: `sandbox/playground.md` (step 2 of the play loop now reviews a proposal)

- [ ] **Step 1: Update the smoke + README docs.** In `docs/MANUAL-SMOKE-F3.md`, add a note at the top: "As of F4 (#12), the edit-selection turn ends in a **proposal** — the F3 direct-apply behavior now happens on ✓ Accept. The full propose→accept smoke is `MANUAL-SMOKE-F4.md`." Create `docs/MANUAL-SMOKE-F4.md`:

```markdown
# Manual smoke — F4 propose/accept (live turn)

Pre-req: Claude Code installed + signed in (the `claude-code` provider rides
that login — the extension holds no credentials, INV-8). Run on a real machine,
not CI.

1. `npm run build`, then F5 (the EDH opens the committed `sandbox/` playground).
2. Open `playground.md`, select a sentence → right-click → **Ask Claude to Edit
   Selection** → give an instruction.
3. ✅ A **proposal** appears: the selection gets an amber tint and a "Claude
   proposes" comment thread shows a `diff` of current → proposed. **The document
   text is unchanged** (INV-10).
4. Click **✓ Accept Proposal** in the thread title. ✅ The replacement lands and
   renders Claude-tinted (the F3 attribution substrate); the proposal disappears.
5. Repeat with another selection and click **✗ Reject Proposal**. ✅ The document
   is untouched; the proposal disappears.
6. Propose again, then save and reload the window. ✅ The pending proposal is
   restored at its re-resolved range.
7. Failure path: edit the proposed-on text, then try Accept. ✅ Refused with a
   warning ("target text changed"); undo your edit → Accept works.
```

In `README.md`, find the features list (the F2/F3 entries) and add: "**F4 — propose/accept**: Claude's edits arrive as pending diff proposals (amber tint + comment thread); ✓ accept applies via the attribution seam, ✗ reject discards — the document never changes without your say-so." In `sandbox/playground.md`, update step 2 ("Ask Claude to Edit Selection — the replacement lands Claude-tinted") to: "Ask Claude to Edit Selection — Claude **proposes** a diff (amber tint + thread); ✓ accept and it lands Claude-tinted."

- [ ] **Step 2: Run the FULL verification gate**

Run: `npm run typecheck && npm test && npm run build && npm run pretest:e2e && npm run test:e2e`
Expected: everything green. (Live smoke is a manual, documented step — perform it once per `docs/MANUAL-SMOKE-F4.md` before calling #12 done.)

- [ ] **Step 3: Commit**

```bash
git add docs/MANUAL-SMOKE-F3.md docs/MANUAL-SMOKE-F4.md README.md sandbox/playground.md
git commit -m "F4: document propose/accept — manual smoke, README, playground loop (#12)"
```

---

## Amendments (during execution)

- **AMENDMENT 1 (Task 7):** the F4 accept E2E exposed a latent F3 seam
  limitation — the host word-diffs one applied WorkspaceEdit into SEVERAL
  minimal hunks when old/new share interior tokens (F4's realistic
  replacements do; F3's test strings never did), so the registry's per-hunk
  exact match missed and the edit fell through as fragmented HUMAN spans.
  Fix: `PendingEditRegistry.match` (per-change equality) is replaced by
  `matchEvent` (event-level net-effect match: every hunk inside the
  registered full pre-edit range + equal net length delta — sound because one
  applyEdit is one change event), and `AttributionController.onDidChange`
  matches the event once, applying the full intended replacement as ONE
  algebra edit on a hit. Unit tests rewritten accordingly
  (`test/pendingEdits.test.ts`); INV-9's miss-warning path unchanged.

## Self-review notes

- **Spec coverage:** §6.3 model → Task 1/3; store prune → Task 2; §6.4 controller contracts (propose/acceptById/rejectById/getRendered/getStaleCount, hidden command) → Tasks 4/5; §6.5 PUC-1..5 → Tasks 4/6/7; §5 UX (amber deco, second comments controller, ✓/✗ title actions, status-bar stale count) → Tasks 4/5; INV-10..13 asserted in E2E (Task 7); §6.8 testing strategy → Tasks 1–3 (unit) + 7 (host E2E) + 8 (manual smoke); §7.3 done-bar → Task 8 gate + smoke.
- **Type consistency:** `Proposal`/`Fingerprint`/`Provenance` from `src/model.ts`; `resolve`/`shift`/`buildFingerprint`/`OffsetRange` from `src/anchorer.ts`; `propose(document, fp, replacement, author, opts)` used identically in Tasks 4/5/6; `acceptById`/`rejectById`/`getRendered`/`getStaleCount` used identically in Tasks 4/7.
- **Known presentation caveat (per spec §6.7/§7.4):** the fenced-diff body is whole-range -/+ (no LCS) and may render oddly if the target text itself contains ``` fences — presentation-only; truth is `fingerprint.text` → `replacement`.