# F3 — Live Human/Claude Attribution 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:** Deliver F3 (`benstull/vscode-cowriting-plugin#6`) — live, char-honest human/Claude span attribution rendered in the buffer, persisted in the F2 sidecar's reserved `attributions[]`, with the `applyAgentEdit` seam as the only machine-edit ingress (INV-9) and a minimal live `@cline/sdk` turn on the `claude-code` provider — per spec `vscode-cowriting-plugin-content/specs/coauthoring-attribution.md` §7.2 SLICE-1..6.

**Architecture:** Three new **vscode-free** units (vitest-tested, the F2 pattern) plus thin editor-facing wiring:
- `src/model.ts` (modify) — typed `AttributionRecord` fills the reserved `attributions: unknown[]`; `schemaVersion` stays 1 (additive, parent INV-4).
- `src/attributionTracker.ts` (new) — pure span algebra over offset ranges: `applyChange(spans, edit, author, ctx)` shifts/splits/clips and `coalesce`s (INV-7: char-precise, only adjacent same-author+same-turn merges).
- `src/pendingEdits.ts` (new) — `PendingEditRegistry`: exact (start,end,text) registrations consumed by the change event so a seam edit is attributed to the agent, never to typing (INV-9).
- `src/liveTurn.ts` (new) — vscode-free `@cline/sdk` driver (dynamic `import()`, like `cline.ts`): one `Agent` turn on `providerId: "claude-code"` (zero credentials, INV-8) returning replacement text + model + runId.
- `src/store.ts` (modify) — `CoauthorStore.update(docPath, mutate)`: fresh-load → mutate → prune unreferenced anchors → save, so ThreadController and AttributionController never clobber each other's sidecar sections.
- `src/attributionController.ts` (new) — the vscode layer: change-event wiring (human vs. seam), `applyAgentEdit`, decorations (Claude tint / human gutter border / toggle), save-time fingerprint persistence, load/external-change resolve-or-orphan (Anchorer ladder, INV-1/INV-6), orphan status-bar count + output channel.
- `src/extension.ts` (modify) — wires the controller, the `cowriting.editSelection` command (LiveTurn → seam), exposes the test API.

Extension stays a CJS esbuild bundle (`vscode` + `@cline/sdk` external); esbuild gains a second **ESM** entry `out/liveTurn.mjs` so `scripts/smoke-live-turn.mjs` can drive the real LiveTurn module for the documented manual smoke. **No LLM in CI** — unit + host E2E drive the seam; the live turn gets the scripted/manual smoke.

**Tech Stack:** TypeScript, VS Code Extension API (TextEditorDecorationType, WorkspaceEdit, onDidChangeTextDocument), esbuild, vitest (unit), `@vscode/test-electron` + mocha (host E2E), `@cline/sdk@0.0.46` (`Agent` + `claude-code` provider).

---

## Verified SDK facts (probed in-session against installed 0.0.46)

- `Agent` (alias of `AgentRuntime`) is exported from `@cline/sdk` (re-export chain → `@cline/agents/dist/agent-runtime.d.ts:43`). Friendly config form: `{ providerId, modelId, systemPrompt?, sessionId?, maxIterations?, ... }` — no `apiKey` needed for `claude-code`.
- `"claude-code"` is in `BUILT_IN_PROVIDER_IDS`; it shells out to the local `claude` binary via `ai-sdk-provider-claude-code` (rides the operator's Pro/Max login; no key fields).
- Valid `modelId`s for claude-code: `"sonnet" | "opus" | "haiku"` or a full model string (`ai-sdk-provider-claude-code/dist/index.d.ts:430`). Use `"sonnet"`.
- `agent.run(input: string): Promise<AgentRunResult>` where `AgentRunResult = { runId, status: "success"|"failed"|"aborted", outputText, messages, usage, error? }` (`@cline/shared/dist/agent.d.ts:378`). Use `runId` as the provenance `sessionId`.
- The SDK is ESM-only: always `await import("@cline/sdk")` (never static import / never bundle — `esbuild.mjs` keeps it external; same rule as `src/cline.ts`).

## File Structure

| File | Responsibility |
| --- | --- |
| `src/model.ts` (modify) | Add `AttributionRecord`; type `Artifact.attributions`; serialize attributions with stable field order. |
| `src/attributionTracker.ts` (new) | Pure live-span algebra: `LiveSpan`, `applyChange`, `coalesce`. vscode-free. |
| `src/pendingEdits.ts` (new) | `PendingEditRegistry`: `register` / `match`(consume) seam edits. vscode-free. |
| `src/liveTurn.ts` (new) | `runEditTurn(instruction, selectedText)` → `{ replacement, model, sessionId }` via `claude-code`; `extractReplacement` fence-stripper. vscode-free. |
| `src/store.ts` (modify) | Add `update(docPath, mutate)` with anchor pruning. |
| `src/threadController.ts` (modify) | `persist()` switches to section-merge `store.update` (writes only threads + their anchors). |
| `src/attributionController.ts` (new) | vscode layer: tracking, seam, decorations, toggle, persistence, resolve/orphan, status bar. |
| `src/extension.ts` (modify) | Wire AttributionController + `cowriting.editSelection`; extend `CowritingApi`. |
| `esbuild.mjs` (modify) | Second build: `src/liveTurn.ts` → `out/liveTurn.mjs` (ESM). |
| `scripts/smoke-live-turn.mjs` (new) | Scripted live smoke (not run in CI). |
| `docs/MANUAL-SMOKE-F3.md` (new) | Documented manual smoke + failure-path checks. |
| `package.json` (modify) | Commands: `editSelection`, `toggleAttribution`, `applyAgentEdit` (palette-hidden); `smoke:live` script. |
| `test/model.test.ts` (modify) | Attribution round-trip + stable serialization. |
| `test/attributionTracker.test.ts` (new) | Exhaustive span-algebra cases. |
| `test/pendingEdits.test.ts` (new) | Register/match/consume/miss. |
| `test/store.test.ts` (modify) | `update` merge of two writers + anchor pruning. |
| `test/liveTurn.test.ts` (new) | `extractReplacement` cases (pure; no SDK). |
| `test/e2e/fixtures/workspace/docs/attrib.md` (new) | Dedicated E2E fixture (threads tests own `sample.md`). |
| `test/e2e/suite/attribution.test.ts` (new) | Host E2E: type → human span → seam → agent span → save → reload → re-anchor → orphan. |

## Shared design rules (read before any task)

- **Edit normalization.** A VS Code content change `{rangeOffset, rangeLength, text}` maps to the F2 `TextEdit` `{start: rangeOffset, end: rangeOffset + rangeLength, newLength: text.length}` (half-open replace, `src/anchorer.ts:18`).
- **Span algebra (INV-7).** For span `[s,e)` and edit `{start,end,newLength}`, `delta = newLength - (end - start)`:
  1. `e <= start` → unchanged. 2. `s >= end` → shift both by `delta`.
  3. Overlap → keep left remainder `[s, start)` (if `s < start`, keeps original id) and right remainder `[end+delta, e+delta)` (if `e > end`; gets a fresh id only when both remainders survive, i.e. a true split).
  4. If `newLength > 0`, the inserted range `[start, start+newLength)` becomes a **new span** authored by the edit's author (fresh id, `createdAt = now`).
  5. Drop empty spans; sort by start; `coalesce` adjacent (`a.end === b.start`) spans whose `author` is JSON-equal **and** `turnId` is equal (`undefined === undefined`); merged span keeps the earlier `createdAt` and the first span's id.
- **Author equality** = deep equality of the `Provenance` object plus `turnId`. Human provenance comes from the same source as `ThreadController.currentAuthor()` (`src/threadController.ts:80`).
- **Reload-vs-typing rule.** In `onDidChangeTextDocument`, if `e.document.isDirty === false` the change is a disk sync (revert / external reload) → **re-resolve from the persisted artifact** (PUC-4 path); never attribute it. Dirty changes are attributed (seam match → agent, else human).
- **Sidecar co-ownership.** All persistence goes through `CoauthorStore.update`: each controller writes only its own section (threads / attributions) + upserts the anchors its records reference; `update` prunes anchors referenced by neither threads nor attributions (proposals are still `[]` in F3 — revisit in F4).
- **Conventions:** SSH-only git; no inline comments trailing CLI commands; commits cite the spec + `#6` and carry `Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>`.

---

### Task 0: Branch

- [ ] **Step 0.1:** `git -C /Users/benstull/git/benstull.org/benstull/vscode-cowriting-plugin checkout -b feat/f3-live-attribution` (from up-to-date `main`).

### Task 1: SLICE-1 — Typed `attributions[]` model

**Files:**
- Modify: `src/model.ts`
- Test: `test/model.test.ts`

- [ ] **Step 1.1: Write the failing tests** — append to `test/model.test.ts`:

```typescript
describe("attributions[] (F3 SLICE-1)", () => {
  it("round-trips an attribution record through serialize → parse", () => {
    const a = emptyArtifact("docs/x.md");
    a.anchors["a_1"] = { fingerprint: { text: "alpha", before: "", after: " beta", lineHint: 0 } };
    a.attributions.push({
      id: "at_1",
      anchorId: "a_1",
      author: { kind: "agent", id: "claude", agent: { sdk: "@cline/sdk", model: "sonnet", sessionId: "run-1" } },
      createdAt: "2026-06-10T00:00:00.000Z",
      updatedAt: "2026-06-10T00:00:00.000Z",
      turnId: "turn-1",
    });
    const parsed = JSON.parse(serializeArtifact(a)) as Artifact;
    expect(parsed.attributions).toEqual(a.attributions);
  });

  it("omits turnId when undefined and serializes stably", () => {
    const a = emptyArtifact("docs/x.md");
    a.attributions.push({
      id: "at_2",
      anchorId: "a_2",
      author: { kind: "human", id: "ben" },
      createdAt: "2026-06-10T00:00:00.000Z",
      updatedAt: "2026-06-10T00:00:00.000Z",
    });
    const s1 = serializeArtifact(a);
    expect(s1.includes("turnId")).toBe(false);
    const s2 = serializeArtifact(JSON.parse(s1) as Artifact);
    expect(s2).toBe(s1);
  });
});
```

Adjust the file's import line to include anything missing (it already imports `emptyArtifact`, `serializeArtifact`, types from `../src/model`).

- [ ] **Step 1.2:** Run `npx vitest run test/model.test.ts` — expect the new tests FAIL (TS error: `attributions` is `unknown[]`, push of typed record fine but `toEqual` comparison compiles — the real failure is the typecheck once the type is used; if it passes untyped, proceed: the type lands next step).
- [ ] **Step 1.3: Implement** in `src/model.ts`:

Add after the `Thread` interface:

```typescript
/** F3 (spec §6.3): an anchored, author-attributed span — state, not history. */
export interface AttributionRecord {
  id: string;
  /** shared anchors map — same Fingerprint primitive (INV-4). */
  anchorId: string;
  author: Provenance;
  /** ISO-8601. */
  createdAt: string;
  /** ISO-8601; bumped when the span's extent/fingerprint changes. */
  updatedAt: string;
  /** groups all spans applied by one live turn. */
  turnId?: string;
}
```

Change `Artifact.attributions` from `unknown[]` to `AttributionRecord[]` (update the doc comment: "F3: anchored attributed spans (filled since F3)"). In `serializeArtifact`, replace `attributions: a.attributions` with stable field ordering:

```typescript
    attributions: a.attributions.map((at) => ({
      id: at.id,
      anchorId: at.anchorId,
      author: serializeProvenance(at.author),
      createdAt: at.createdAt,
      updatedAt: at.updatedAt,
      ...(at.turnId !== undefined ? { turnId: at.turnId } : {}),
    })),
```

- [ ] **Step 1.4:** `npx vitest run test/model.test.ts` → PASS; `npm run typecheck` → clean.
- [ ] **Step 1.5: Commit** — `git add src/model.ts test/model.test.ts && git commit` message: `F3 SLICE-1: typed attributions[] model (spec §6.3, INV-4) (#6)` + Co-Authored-By trailer.

### Task 2: SLICE-2 — AttributionTracker span algebra

**Files:**
- Create: `src/attributionTracker.ts`
- Test: `test/attributionTracker.test.ts`

- [ ] **Step 2.1: Create `src/attributionTracker.ts`:**

```typescript
/**
 * AttributionTracker — pure span algebra over offset ranges (spec §6.2/§6.5).
 * Char-honest (INV-7): attributes exactly the characters each author produced —
 * split character-precisely, coalesce only adjacent same-author/same-turn
 * spans. vscode-free; the controller converts vscode change events to TextEdit.
 */
import type { TextEdit } from "./anchorer";
import type { Provenance } from "./model";

export interface LiveSpan {
  id: string;
  /** half-open [start, end) character offsets in the live document. */
  start: number;
  end: number;
  author: Provenance;
  turnId?: string;
  /** ISO-8601; survives splits/merges (earliest wins on merge). */
  createdAt: string;
}

/** Injected effects so the algebra stays pure and deterministic in tests. */
export interface TrackerCtx {
  newId: () => string;
  now: () => string;
  turnId?: string;
}

function sameAuthor(a: LiveSpan, b: LiveSpan): boolean {
  return JSON.stringify(a.author) === JSON.stringify(b.author) && a.turnId === b.turnId;
}

/** Merge adjacent same-author/same-turn spans; drop empties; sort by start. */
export function coalesce(spans: LiveSpan[]): LiveSpan[] {
  const sorted = spans.filter((s) => s.end > s.start).sort((a, b) => a.start - b.start);
  const out: LiveSpan[] = [];
  for (const s of sorted) {
    const last = out[out.length - 1];
    if (last && last.end === s.start && sameAuthor(last, s)) {
      last.end = s.end;
      if (s.createdAt < last.createdAt) last.createdAt = s.createdAt;
    } else {
      out.push({ ...s });
    }
  }
  return out;
}

/**
 * Apply one document edit (the half-open range [start,end) replaced by
 * newLength chars) authored by `author`. Existing spans shift/split/clip;
 * inserted chars become a new span of `author` (INV-7).
 */
export function applyChange(
  spans: LiveSpan[],
  edit: TextEdit,
  author: Provenance,
  ctx: TrackerCtx,
): LiveSpan[] {
  const delta = edit.newLength - (edit.end - edit.start);
  const out: LiveSpan[] = [];
  for (const s of spans) {
    if (s.end <= edit.start) {
      out.push({ ...s });
    } else if (s.start >= edit.end) {
      out.push({ ...s, start: s.start + delta, end: s.end + delta });
    } else {
      const left = s.start < edit.start ? { ...s, end: edit.start } : null;
      const right =
        s.end > edit.end ? { ...s, start: edit.end + delta, end: s.end + delta } : null;
      if (left) out.push(left);
      if (right) out.push(left ? { ...right, id: ctx.newId() } : right);
    }
  }
  if (edit.newLength > 0) {
    out.push({
      id: ctx.newId(),
      start: edit.start,
      end: edit.start + edit.newLength,
      author,
      turnId: ctx.turnId,
      createdAt: ctx.now(),
    });
  }
  return coalesce(out);
}
```

- [ ] **Step 2.2: Create `test/attributionTracker.test.ts`** — exhaustive cases, both author directions:

```typescript
import { describe, it, expect } from "vitest";
import { applyChange, coalesce, type LiveSpan, type TrackerCtx } from "../src/attributionTracker";
import type { Provenance } from "../src/model";

const HUMAN: Provenance = { kind: "human", id: "ben" };
const AGENT: Provenance = {
  kind: "agent", id: "claude",
  agent: { sdk: "@cline/sdk", model: "sonnet", sessionId: "run-1" },
};

function ctx(turnId?: string): TrackerCtx {
  let n = 0;
  return { newId: () => `n${++n}`, now: () => "2026-06-10T00:00:00.000Z", turnId };
}
function span(id: string, start: number, end: number, author: Provenance, turnId?: string): LiveSpan {
  return { id, start, end, author, turnId, createdAt: "2026-06-09T00:00:00.000Z" };
}
const ranges = (s: LiveSpan[]) => s.map((x) => [x.start, x.end]);
const authors = (s: LiveSpan[]) => s.map((x) => x.author.kind);

describe("applyChange — insertions", () => {
  it("insertion into empty span list creates one author span", () => {
    const r = applyChange([], { start: 5, end: 5, newLength: 3 }, HUMAN, ctx());
    expect(ranges(r)).toEqual([[5, 8]]);
    expect(r[0].author).toEqual(HUMAN);
  });
  it("insertion before a span shifts it", () => {
    const r = applyChange([span("a", 10, 14, AGENT)], { start: 0, end: 0, newLength: 2 }, HUMAN, ctx());
    expect(ranges(r)).toEqual([[0, 2], [12, 16]]);
    expect(authors(r)).toEqual(["human", "agent"]);
  });
  it("insertion after a span leaves it untouched", () => {
    const r = applyChange([span("a", 0, 4, AGENT)], { start: 10, end: 10, newLength: 2 }, HUMAN, ctx());
    expect(ranges(r)).toEqual([[0, 4], [10, 12]]);
  });
  it("PUC-3: insertion strictly inside a different-author span splits it char-precisely", () => {
    const r = applyChange([span("a", 0, 10, AGENT)], { start: 4, end: 4, newLength: 3 }, HUMAN, ctx());
    expect(ranges(r)).toEqual([[0, 4], [4, 7], [7, 13]]);
    expect(authors(r)).toEqual(["agent", "human", "agent"]);
  });
  it("symmetric: agent insertion inside a human span splits it (INV-7)", () => {
    const r = applyChange([span("a", 0, 10, HUMAN)], { start: 4, end: 4, newLength: 3 }, AGENT, ctx("t1"));
    expect(authors(r)).toEqual(["human", "agent", "human"]);
    expect(r[1].turnId).toBe("t1");
  });
  it("insertion inside a SAME-author span coalesces back to one span", () => {
    const r = applyChange([span("a", 0, 10, HUMAN)], { start: 4, end: 4, newLength: 3 }, HUMAN, ctx());
    expect(ranges(r)).toEqual([[0, 13]]);
  });
  it("insertion at a span boundary does not split; same author coalesces", () => {
    const r = applyChange([span("a", 0, 5, HUMAN)], { start: 5, end: 5, newLength: 2 }, HUMAN, ctx());
    expect(ranges(r)).toEqual([[0, 7]]);
  });
});

describe("applyChange — deletions", () => {
  it("deletion before a span shifts it left", () => {
    const r = applyChange([span("a", 10, 14, HUMAN)], { start: 0, end: 4, newLength: 0 }, HUMAN, ctx());
    expect(ranges(r)).toEqual([[6, 10]]);
  });
  it("deletion entirely inside a span shrinks it (no re-authoring, INV-6)", () => {
    const r = applyChange([span("a", 0, 10, AGENT)], { start: 3, end: 6, newLength: 0 }, HUMAN, ctx());
    expect(ranges(r)).toEqual([[0, 7]]);
    expect(authors(r)).toEqual(["agent"]);
  });
  it("deletion covering a whole span removes it", () => {
    const r = applyChange([span("a", 3, 6, AGENT)], { start: 0, end: 10, newLength: 0 }, HUMAN, ctx());
    expect(r).toEqual([]);
  });
  it("deletion clipping a span head keeps the tail", () => {
    const r = applyChange([span("a", 4, 10, AGENT)], { start: 0, end: 6, newLength: 0 }, HUMAN, ctx());
    expect(ranges(r)).toEqual([[0, 4]]);
  });
  it("deletion clipping a span tail keeps the head", () => {
    const r = applyChange([span("a", 0, 6, AGENT)], { start: 4, end: 10, newLength: 0 }, HUMAN, ctx());
    expect(ranges(r)).toEqual([[0, 4]]);
  });
});

describe("applyChange — replacements", () => {
  it("replacement inside an agent span: human chars in the middle, agent halves keep ids/createdAt", () => {
    const r = applyChange([span("a", 0, 12, AGENT)], { start: 4, end: 8, newLength: 2 }, HUMAN, ctx());
    expect(ranges(r)).toEqual([[0, 4], [4, 6], [6, 10]]);
    expect(authors(r)).toEqual(["agent", "human", "agent"]);
    expect(r[0].id).toBe("a");
    expect(r[0].createdAt).toBe("2026-06-09T00:00:00.000Z");
  });
  it("replacement spanning two spans clips both and inserts the author's span between", () => {
    const r = applyChange(
      [span("a", 0, 6, AGENT), span("b", 6, 12, HUMAN)],
      { start: 4, end: 8, newLength: 5 }, AGENT, ctx("t2"),
    );
    expect(ranges(r)).toEqual([[0, 4], [4, 9], [9, 13]]);
    expect(authors(r)).toEqual(["agent", "agent", "human"]);
    expect(r[1].turnId).toBe("t2");
  });
});

describe("multi-edit sequences", () => {
  it("type, agent-replace, type inside agent span — ends char-honest", () => {
    const c = ctx();
    let s = applyChange([], { start: 0, end: 0, newLength: 20 }, HUMAN, c);
    s = applyChange(s, { start: 5, end: 10, newLength: 8 }, AGENT, { ...c, turnId: "t1" });
    s = applyChange(s, { start: 9, end: 9, newLength: 1 }, HUMAN, c);
    expect(authors(s)).toEqual(["human", "agent", "human", "agent", "human"]);
    expect(ranges(s)).toEqual([[0, 5], [5, 9], [9, 10], [10, 14], [14, 24]]);
  });
});

describe("coalesce", () => {
  it("merges adjacent same-author same-turn spans, keeps earliest createdAt", () => {
    const a = { ...span("a", 0, 3, HUMAN), createdAt: "2026-06-09T00:00:00.000Z" };
    const b = { ...span("b", 3, 6, HUMAN), createdAt: "2026-06-08T00:00:00.000Z" };
    const r = coalesce([a, b]);
    expect(ranges(r)).toEqual([[0, 6]]);
    expect(r[0].id).toBe("a");
    expect(r[0].createdAt).toBe("2026-06-08T00:00:00.000Z");
  });
  it("does NOT merge different authors, different turnIds, or non-adjacent spans", () => {
    expect(coalesce([span("a", 0, 3, HUMAN), span("b", 3, 6, AGENT)])).toHaveLength(2);
    expect(coalesce([span("a", 0, 3, AGENT, "t1"), span("b", 3, 6, AGENT, "t2")])).toHaveLength(2);
    expect(coalesce([span("a", 0, 3, HUMAN), span("b", 4, 6, HUMAN)])).toHaveLength(2);
  });
  it("drops empty spans", () => {
    expect(coalesce([span("a", 5, 5, HUMAN)])).toEqual([]);
  });
});
```

- [ ] **Step 2.3:** `npx vitest run test/attributionTracker.test.ts` → all PASS (write the test first if you prefer strict TDD ordering; both files land in this task either way).
- [ ] **Step 2.4:** `npm run typecheck` → clean.
- [ ] **Step 2.5: Commit** — `F3 SLICE-2: AttributionTracker span algebra (INV-6/INV-7) (#6)` + trailer.

### Task 3: SLICE-3a — PendingEditRegistry + `CoauthorStore.update` (sidecar co-ownership)

**Files:**
- Create: `src/pendingEdits.ts`
- Modify: `src/store.ts`, `src/threadController.ts:85-88` (persist)
- Test: `test/pendingEdits.test.ts`, `test/store.test.ts`

- [ ] **Step 3.1: Create `src/pendingEdits.ts`:**

```typescript
/**
 * PendingEditRegistry — the seam's bookkeeping (spec §6.2, INV-9). Before
 * applyAgentEdit applies a WorkspaceEdit, it registers the exact expected
 * change; the controller's change handler consumes a matching registration to
 * attribute that change to the agent. Anything unmatched is human typing.
 * vscode-free and unit-testable.
 */
import type { Provenance } from "./model";

export interface PendingEdit {
  docPath: string;
  /** half-open [start, end) offsets of the replaced range. */
  start: number;
  end: number;
  newText: string;
  provenance: Provenance;
  turnId?: string;
}

export class PendingEditRegistry {
  private pending: PendingEdit[] = [];

  register(edit: PendingEdit): void {
    this.pending.push(edit);
  }

  /** Remove a registration that failed to apply. */
  unregister(edit: PendingEdit): void {
    this.pending = this.pending.filter((p) => p !== edit);
  }

  /**
   * Find-and-consume the registration exactly matching a change event
   * (same doc, same replaced range, same inserted text). Null → human edit.
   */
  match(docPath: string, change: { start: number; end: number; text: string }): PendingEdit | null {
    const i = this.pending.findIndex(
      (p) =>
        p.docPath === docPath &&
        p.start === change.start &&
        p.end === change.end &&
        p.newText === change.text,
    );
    if (i === -1) return null;
    const [hit] = this.pending.splice(i, 1);
    return hit;
  }
}
```

- [ ] **Step 3.2: Create `test/pendingEdits.test.ts`:**

```typescript
import { describe, it, expect } from "vitest";
import { PendingEditRegistry } from "../src/pendingEdits";
import type { Provenance } from "../src/model";

const AGENT: Provenance = {
  kind: "agent", id: "claude",
  agent: { sdk: "@cline/sdk", model: "sonnet", sessionId: "run-1" },
};

describe("PendingEditRegistry (INV-9)", () => {
  it("matches and consumes an exact registration", () => {
    const reg = new PendingEditRegistry();
    reg.register({ docPath: "d.md", start: 3, end: 7, newText: "new", provenance: AGENT, turnId: "t1" });
    const hit = reg.match("d.md", { start: 3, end: 7, text: "new" });
    expect(hit?.turnId).toBe("t1");
    expect(reg.match("d.md", { start: 3, end: 7, text: "new" })).toBeNull();
  });
  it("does not match a different doc, range, or text (human typing stays human)", () => {
    const reg = new PendingEditRegistry();
    reg.register({ docPath: "d.md", start: 3, end: 7, newText: "new", provenance: AGENT });
    expect(reg.match("other.md", { start: 3, end: 7, text: "new" })).toBeNull();
    expect(reg.match("d.md", { start: 3, end: 8, text: "new" })).toBeNull();
    expect(reg.match("d.md", { start: 3, end: 7, text: "neww" })).toBeNull();
  });
  it("unregister removes a failed application", () => {
    const reg = new PendingEditRegistry();
    const p = { docPath: "d.md", start: 0, end: 0, newText: "x", provenance: AGENT };
    reg.register(p);
    reg.unregister(p);
    expect(reg.match("d.md", { start: 0, end: 0, text: "x" })).toBeNull();
  });
});
```

- [ ] **Step 3.3:** `npx vitest run test/pendingEdits.test.ts` → PASS.
- [ ] **Step 3.4: Add `CoauthorStore.update`** in `src/store.ts` (import `emptyArtifact` from `./model`):

```typescript
  /**
   * Read-modify-write for sidecar co-ownership (spec F3 §6.2): each controller
   * mutates only its own section against a FRESH load, so ThreadController and
   * AttributionController never clobber each other. After the mutation, anchors
   * referenced by neither threads nor attributions are pruned (proposals are
   * still empty in F3 — revisit in F4).
   */
  update(docPath: string, mutate: (artifact: Artifact) => void): Artifact {
    const artifact = this.load(docPath) ?? emptyArtifact(docPath);
    mutate(artifact);
    const referenced = new Set<string>([
      ...artifact.threads.map((t) => t.anchorId),
      ...artifact.attributions.map((a) => a.anchorId),
    ]);
    for (const id of Object.keys(artifact.anchors)) {
      if (!referenced.has(id)) delete artifact.anchors[id];
    }
    this.save(docPath, artifact);
    return artifact;
  }
```

- [ ] **Step 3.5: Switch `ThreadController.persist`** (`src/threadController.ts:85-88`) to section-merge so it stops clobbering `attributions[]`:

```typescript
  private persist(state: DocState): void {
    this.selfWrites.add(this.store.sidecarPath(state.docPath));
    this.store.update(state.docPath, (a) => {
      a.threads = state.artifact.threads;
      for (const t of state.artifact.threads) {
        a.anchors[t.anchorId] = state.artifact.anchors[t.anchorId];
      }
    });
  }
```

- [ ] **Step 3.6: Add tests** to `test/store.test.ts` (two-writer merge + pruning):

```typescript
  it("update(): two writers merge sections instead of clobbering (F3 §6.2)", () => {
    const store = new CoauthorStore(tmp);
    store.update("d.md", (a) => {
      a.anchors["a_t"] = { fingerprint: { text: "t", before: "", after: "", lineHint: 0 } };
      a.threads.push({ id: "t1", anchorId: "a_t", status: "open", messages: [] });
    });
    store.update("d.md", (a) => {
      a.anchors["a_at"] = { fingerprint: { text: "x", before: "", after: "", lineHint: 0 } };
      a.attributions.push({
        id: "at1", anchorId: "a_at", author: { kind: "human", id: "ben" },
        createdAt: "2026-06-10T00:00:00.000Z", updatedAt: "2026-06-10T00:00:00.000Z",
      });
    });
    const loaded = store.load("d.md")!;
    expect(loaded.threads).toHaveLength(1);
    expect(loaded.attributions).toHaveLength(1);
    expect(Object.keys(loaded.anchors).sort()).toEqual(["a_at", "a_t"]);
  });

  it("update() prunes anchors no longer referenced by threads or attributions", () => {
    const store = new CoauthorStore(tmp);
    store.update("d.md", (a) => {
      a.anchors["a_old"] = { fingerprint: { text: "o", before: "", after: "", lineHint: 0 } };
      a.attributions.push({
        id: "at1", anchorId: "a_old", author: { kind: "human", id: "ben" },
        createdAt: "2026-06-10T00:00:00.000Z", updatedAt: "2026-06-10T00:00:00.000Z",
      });
    });
    store.update("d.md", (a) => {
      a.attributions = [];
    });
    expect(Object.keys(store.load("d.md")!.anchors)).toEqual([]);
  });
```

Match the existing file's temp-dir fixture variable name (read `test/store.test.ts` first; it creates a temp root — reuse its pattern, here shown as `tmp`).

- [ ] **Step 3.7:** `npx vitest run` (full unit suite) → PASS; `npm run typecheck` → clean.
- [ ] **Step 3.8: Commit** — `F3 SLICE-3: pending-edit registry + sidecar section-merge update (INV-9 groundwork) (#6)` + trailer.

> **Amendment (post–Task-3 code review).** Two controllers now co-own the
> sidecar, so per-controller FileSystemWatchers + per-controller `selfWrites`
> would make each controller's persist look "external" to the other (comment-UI
> flicker on every save) and the 1-write=1-event assumption is fragile. Task 4
> therefore deviates from the code blocks below in four ways:
> 1. **Self-write suppression moves into `CoauthorStore`** (the single write
>    funnel): `update()` records `sidecarPath` in a store-level `selfWrites`
>    set; new `consumeSelfWrite(fsPath): boolean` removes-and-reports.
> 2. **One shared sidecar watcher in `extension.ts`** replaces the per-
>    controller watchers: on event, `store.consumeSelfWrite(p)` → ignore; else
>    notify BOTH controllers (`threadController.handleExternalSidecarChange`,
>    `attributionController.handleExternalSidecarChange` — the existing private
>    handlers made public, with their own selfWrites checks removed).
>    ThreadController's constructor watcher + `selfWrites` set are removed.
> 3. **`applyAgentEdit` unregisters unconditionally** after `applyEdit`
>    resolves (identity-based `unregister` is a no-op if `match` already
>    consumed it) — prevents the no-op-edit registration leak.
> 4. Doc notes: `update`'s `mutate` must be synchronous; `unregister` is
>    identity-based (callers keep the registered object).

### Task 4: SLICE-3b — AttributionController: seam, human wiring, decorations, toggle

**Files:**
- Create: `src/attributionController.ts`
- Modify: `src/extension.ts`, `package.json`

This is the vscode layer — no unit tests here (host E2E covers it in Task 7); the gate for this task is `npm run typecheck` + `npm run build` + the Task 7 E2E.

- [ ] **Step 4.1: Create `src/attributionController.ts`:**

```typescript
/**
 * AttributionController — the thin editor-facing layer for F3 (spec §6.2).
 * Wires the pure AttributionTracker + PendingEditRegistry + Store/Anchorer to
 * the editor: human typing → human spans, seam edits → agent spans (INV-9),
 * decorations (Claude tint / human gutter border / toggle), save-time
 * persistence, load/external-change resolve-or-orphan (INV-1/INV-6), and the
 * orphan status-bar count.
 */
import * as vscode from "vscode";
import { CoauthorStore } from "./store";
import { newId, type AttributionRecord, type Provenance } from "./model";
import { buildFingerprint, resolve, type OffsetRange } from "./anchorer";
import { applyChange, coalesce, type LiveSpan } from "./attributionTracker";
import { PendingEditRegistry } from "./pendingEdits";

/** Test-facing snapshot of live attribution state for a document. */
export interface RenderedSpan {
  id: string;
  authorKind: "human" | "agent";
  authorId: string;
  turnId?: string;
  range: { start: number; end: number };
}

interface DocAttribution {
  docPath: string;
  spans: LiveSpan[];
  /** persisted records whose fingerprints failed to resolve (PUC-4). */
  orphans: AttributionRecord[];
  /** record metadata per live span id (updatedAt bookkeeping). */
  records: Map<string, AttributionRecord>;
}

const AGENT_DECO: vscode.DecorationRenderOptions = {
  backgroundColor: "rgba(99, 102, 241, 0.18)",
  overviewRulerColor: "rgba(99, 102, 241, 0.8)",
  overviewRulerLane: vscode.OverviewRulerLane.Right,
};
const HUMAN_DECO: vscode.DecorationRenderOptions = {
  borderColor: "rgba(16, 185, 129, 0.8)",
  borderStyle: "solid",
  borderWidth: "0 0 0 2px",
};

export class AttributionController implements vscode.Disposable {
  private readonly disposables: vscode.Disposable[] = [];
  private readonly docs = new Map<string, DocAttribution>();
  private readonly pending = new PendingEditRegistry();
  private readonly agentType = vscode.window.createTextEditorDecorationType(AGENT_DECO);
  private readonly humanType = vscode.window.createTextEditorDecorationType(HUMAN_DECO);
  private readonly statusItem = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Right, 90);
  private readonly output = vscode.window.createOutputChannel("Cowriting Attribution");
  private visible = true;
  /** sidecar paths we just wrote, to ignore our own watcher events. */
  private readonly selfWrites = new Set<string>();

  constructor(private readonly store: CoauthorStore, private readonly rootDir: string) {
    this.disposables.push(this.agentType, this.humanType, this.statusItem, this.output);
    this.disposables.push(
      vscode.commands.registerCommand("cowriting.toggleAttribution", () => this.toggle()),
      vscode.workspace.onDidChangeTextDocument((e) => this.onDidChange(e)),
      vscode.workspace.onDidSaveTextDocument((d) => this.onDidSave(d)),
      vscode.window.onDidChangeActiveTextEditor(() => this.renderActive()),
    );
    const watcher = vscode.workspace.createFileSystemWatcher("**/.threads/**/*.json");
    const onSidecar = (uri: vscode.Uri) => this.onExternalSidecarChange(uri);
    watcher.onDidChange(onSidecar);
    watcher.onDidCreate(onSidecar);
    this.disposables.push(watcher);
  }

  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 currentAuthor(): Provenance {
    const id = vscode.workspace.getConfiguration("git").get<string>("user.name") || process.env.USER || "human";
    return { kind: "human", id };
  }
  private state(docPath: string): DocAttribution {
    let s = this.docs.get(docPath);
    if (!s) {
      s = { docPath, spans: [], orphans: [], records: new Map() };
      this.docs.set(docPath, s);
    }
    return s;
  }

  // ---- PUC-4: load / resolve-or-orphan ---------------------------------------------

  /** Load the sidecar and re-resolve every attribution (live span | orphan). */
  loadAll(document: vscode.TextDocument): void {
    if (!this.isTracked(document)) return;
    const docPath = this.docPathOf(document.uri);
    const s = this.state(docPath);
    const artifact = this.store.load(docPath);
    s.spans = [];
    s.orphans = [];
    s.records.clear();
    if (artifact) {
      const text = document.getText();
      for (const rec of artifact.attributions) {
        const fp = artifact.anchors[rec.anchorId]?.fingerprint;
        const resolved = fp ? resolve(text, fp) : "orphaned";
        if (resolved === "orphaned") {
          s.orphans.push(rec);
        } else {
          s.spans.push({
            id: rec.id, start: resolved.start, end: resolved.end,
            author: rec.author, turnId: rec.turnId, createdAt: rec.createdAt,
          });
          s.records.set(rec.id, rec);
        }
      }
      s.spans = coalesce(s.spans);
    }
    this.render(document);
  }

  private onExternalSidecarChange(uri: vscode.Uri): void {
    const p = uri.fsPath;
    if (this.selfWrites.has(p)) {
      this.selfWrites.delete(p);
      return;
    }
    for (const s of this.docs.values()) {
      if (this.store.sidecarPath(s.docPath) === p) {
        const doc = vscode.workspace.textDocuments.find((d) => this.docPathOf(d.uri) === s.docPath);
        if (doc) this.loadAll(doc);
      }
    }
  }

  // ---- PUC-1/PUC-3: live tracking ---------------------------------------------------

  private onDidChange(e: vscode.TextDocumentChangeEvent): void {
    if (!this.isTracked(e.document) || e.contentChanges.length === 0) return;
    const docPath = this.docPathOf(e.document.uri);
    if (!e.document.isDirty) {
      // Disk sync (revert / reload): re-resolve, never attribute (PUC-4).
      this.loadAll(e.document);
      return;
    }
    const s = this.state(docPath);
    for (const change of e.contentChanges) {
      const edit = {
        start: change.rangeOffset,
        end: change.rangeOffset + change.rangeLength,
        newLength: change.text.length,
      };
      const hit = this.pending.match(docPath, { start: edit.start, end: edit.end, text: change.text });
      const author = hit ? hit.provenance : this.currentAuthor();
      s.spans = applyChange(s.spans, edit, author, {
        newId: () => newId("at"),
        now: () => new Date().toISOString(),
        turnId: hit?.turnId,
      });
    }
    this.render(e.document);
  }

  // ---- the seam (INV-9) ---------------------------------------------------------------

  /**
   * The ONLY machine-edit ingress: register the exact expected change, then
   * apply it as a WorkspaceEdit. Returns false (applying nothing) on a stale
   * document version or a rejected edit — never partial-applies (spec §6.9).
   */
  async applyAgentEdit(
    document: vscode.TextDocument,
    range: vscode.Range,
    newText: string,
    provenance: Provenance,
    opts?: { expectedVersion?: number; turnId?: string },
  ): Promise<boolean> {
    if (!this.isTracked(document)) return false;
    if (opts?.expectedVersion !== undefined && document.version !== opts.expectedVersion) return false;
    const docPath = this.docPathOf(document.uri);
    const pendingEdit = {
      docPath,
      start: document.offsetAt(range.start),
      end: document.offsetAt(range.end),
      newText,
      provenance,
      turnId: opts?.turnId,
    };
    this.pending.register(pendingEdit);
    const we = new vscode.WorkspaceEdit();
    we.replace(document.uri, range, newText);
    const ok = await vscode.workspace.applyEdit(we);
    if (!ok) this.pending.unregister(pendingEdit);
    return ok;
  }

  // ---- PUC-4: persistence on save ----------------------------------------------------

  private onDidSave(document: vscode.TextDocument): void {
    if (!this.isTracked(document)) return;
    const docPath = this.docPathOf(document.uri);
    const s = this.docs.get(docPath);
    if (!s || (s.spans.length === 0 && s.orphans.length === 0)) return;
    const text = document.getText();
    const now = new Date().toISOString();
    const records: AttributionRecord[] = [];
    const anchorOf = new Map<string, OffsetRange>();
    for (const span of s.spans) {
      const prev = s.records.get(span.id);
      const rec: AttributionRecord = {
        id: span.id,
        anchorId: prev?.anchorId ?? newId("a"),
        author: span.author,
        createdAt: span.createdAt,
        updatedAt: prev ? prev.updatedAt : now,
        ...(span.turnId !== undefined ? { turnId: span.turnId } : {}),
      };
      anchorOf.set(rec.anchorId, { start: span.start, end: span.end });
      records.push(rec);
      s.records.set(span.id, rec);
    }
    this.selfWrites.add(this.store.sidecarPath(docPath));
    this.store.update(docPath, (a) => {
      for (const rec of records) {
        const range = anchorOf.get(rec.anchorId)!;
        const fp = buildFingerprint(text, range);
        const prevFp = a.anchors[rec.anchorId]?.fingerprint;
        if (prevFp && JSON.stringify(prevFp) !== JSON.stringify(fp)) rec.updatedAt = now;
        a.anchors[rec.anchorId] = { fingerprint: fp };
      }
      // Orphans ride along unchanged (recoverable, spec §6.9): their records
      // stay in attributions[], so update()'s prune keeps their anchors too.
      a.attributions = [...records, ...s.orphans];
    });
  }

  // ---- PUC-5: rendering ----------------------------------------------------------------

  private toggle(): void {
    this.visible = !this.visible;
    this.renderActive();
  }

  private renderActive(): void {
    const editor = vscode.window.activeTextEditor;
    if (editor) this.render(editor.document);
  }

  private render(document: vscode.TextDocument): void {
    const editor = vscode.window.visibleTextEditors.find((e) => e.document === document);
    if (!editor || !this.isTracked(document)) return;
    const s = this.docs.get(this.docPathOf(document.uri));
    const spans = this.visible && s ? s.spans : [];
    const toRange = (sp: LiveSpan) =>
      new vscode.Range(document.positionAt(sp.start), document.positionAt(sp.end));
    editor.setDecorations(this.agentType, spans.filter((x) => x.author.kind === "agent").map(toRange));
    editor.setDecorations(this.humanType, spans.filter((x) => x.author.kind === "human").map(toRange));
    this.renderStatus(s);
  }

  private renderStatus(s: DocAttribution | undefined): void {
    const n = s?.orphans.length ?? 0;
    if (n === 0) {
      this.statusItem.hide();
      return;
    }
    this.statusItem.text = `$(warning) ${n} orphaned attribution${n === 1 ? "" : "s"}`;
    this.statusItem.tooltip = "Cowriting: attribution anchors that no longer resolve (see output channel)";
    this.statusItem.show();
    this.output.clear();
    for (const o of s!.orphans) this.output.appendLine(`orphaned ${o.id} (${o.author.kind}:${o.author.id})`);
  }

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

  getSpans(docPath: string): RenderedSpan[] {
    const s = this.docs.get(docPath);
    if (!s) return [];
    return s.spans.map((sp) => ({
      id: sp.id,
      authorKind: sp.author.kind,
      authorId: sp.author.id,
      turnId: sp.turnId,
      range: { start: sp.start, end: sp.end },
    }));
  }
  getOrphanCount(docPath: string): number {
    return this.docs.get(docPath)?.orphans.length ?? 0;
  }
  isVisible(): boolean {
    return this.visible;
  }

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

Note the deliberate behaviors: (a) `onDidChange` consults the registry BEFORE falling back to human (INV-9); (b) `!isDirty` changes re-resolve instead of attributing (reload rule); (c) `onDidSave` refreshes fingerprints and bumps `updatedAt` only for changed fingerprints; (d) orphans are carried through saves untouched in `attributions[]` — recoverable (spec §6.9), and `store.update`'s prune keeps their anchors because the records remain referenced.

- [ ] **Step 4.2: Wire into `src/extension.ts`** — extend the API and activation (full replacement of the F2 block):

```typescript
import * as vscode from "vscode";
import { fetchSdkSummary } from "./cline";
import { CoauthorStore } from "./store";
import { ThreadController } from "./threadController";
import { AttributionController } from "./attributionController";

const CHANNEL_NAME = "Cowriting (Cline SDK)";

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

In `activate`, after the ThreadController wiring:

```typescript
  const attributionController = new AttributionController(store, root);
  context.subscriptions.push(attributionController);

  context.subscriptions.push(
    vscode.commands.registerCommand(
      "cowriting.applyAgentEdit",
      (args: {
        uri: string; start: number; end: number; newText: string;
        model?: string; sessionId?: string; turnId?: string;
      }) => {
        const doc = vscode.workspace.textDocuments.find((d) => d.uri.toString() === args.uri);
        if (!doc) return Promise.resolve(false);
        const range = new vscode.Range(doc.positionAt(args.start), doc.positionAt(args.end));
        const provenance = {
          kind: "agent" as const,
          id: "claude",
          agent: { sdk: "@cline/sdk", model: args.model ?? "sonnet", sessionId: args.sessionId ?? "" },
        };
        return attributionController.applyAgentEdit(doc, range, args.newText, provenance, { turnId: args.turnId });
      },
    ),
  );
```

Update the open/render hook so attributions load alongside threads, and the return value:

```typescript
  const renderIfOpen = (doc: vscode.TextDocument) => {
    if (doc.uri.scheme === "file" && doc.uri.fsPath.startsWith(root)) {
      threadController.renderAll(doc);
      attributionController.loadAll(doc);
    }
  };
  vscode.workspace.textDocuments.forEach(renderIfOpen);
  context.subscriptions.push(vscode.workspace.onDidOpenTextDocument(renderIfOpen));

  return { threadController, attributionController };
```

- [ ] **Step 4.3: `package.json` contributions** — add to `contributes.commands`:

```json
      { "command": "cowriting.toggleAttribution", "title": "Cowriting: Toggle Attribution", "category": "Cowriting" },
      { "command": "cowriting.applyAgentEdit", "title": "Apply Agent Edit (internal seam)", "category": "Cowriting" }
```

and hide the internal seam from the palette via `contributes.menus`:

```json
    "commandPalette": [
      { "command": "cowriting.applyAgentEdit", "when": "false" }
    ]
```

(`commandPalette` is a new key inside the existing `"menus"` object.)

- [ ] **Step 4.4:** `npm run typecheck` → clean; `npm run build` → bundle OK; `npx vitest run` → still green.
- [ ] **Step 4.5: Commit** — `F3 SLICE-3: applyAgentEdit seam + live tracking + decorations/toggle (INV-7/INV-9) (#6)` + trailer.

### Task 5: SLICE-4 — persistence/reload is already wired; verify the decision logic in unit tests

Task 4 lands the save/load/orphan code paths (they are inseparable from the controller). This task adds the vscode-free unit coverage the spec requires (§6.8 "resolve→orphan for attribution fingerprints") and a tracker↔anchorer integration test.

**Files:**
- Test: `test/attributionPersistence.test.ts` (new)

- [ ] **Step 5.1: Create `test/attributionPersistence.test.ts`:**

```typescript
import { describe, it, expect } from "vitest";
import { buildFingerprint, resolve } from "../src/anchorer";
import { applyChange, type LiveSpan } from "../src/attributionTracker";
import type { Provenance } from "../src/model";

const HUMAN: Provenance = { kind: "human", id: "ben" };
const DOC = "intro\nClaude wrote this sentence here.\noutro\n";

function liveSpan(): LiveSpan {
  const start = DOC.indexOf("Claude wrote this sentence");
  return {
    id: "at_1", start, end: start + "Claude wrote this sentence".length,
    author: { kind: "agent", id: "claude", agent: { sdk: "@cline/sdk", model: "sonnet", sessionId: "r1" } },
    createdAt: "2026-06-10T00:00:00.000Z",
  };
}

describe("attribution persistence decision logic (SLICE-4, spec §6.5 PUC-4)", () => {
  it("save → reload: fingerprint built from the live span resolves to the same range", () => {
    const s = liveSpan();
    const fp = buildFingerprint(DOC, { start: s.start, end: s.end });
    expect(resolve(DOC, fp)).toEqual({ start: s.start, end: s.end });
  });

  it("external edit above: fingerprint re-resolves at the moved range", () => {
    const s = liveSpan();
    const fp = buildFingerprint(DOC, { start: s.start, end: s.end });
    const edited = "a new line\n" + DOC;
    const moved = edited.indexOf("Claude wrote this sentence");
    expect(resolve(edited, fp)).toEqual({ start: moved, end: moved + (s.end - s.start) });
  });

  it("anchored text mangled: orphaned, never guessed (INV-1/INV-6)", () => {
    const s = liveSpan();
    const fp = buildFingerprint(DOC, { start: s.start, end: s.end });
    const mangled = DOC.replace("Claude wrote this sentence", "Someone rewrote everything");
    expect(resolve(mangled, fp)).toBe("orphaned");
  });

  it("in-session edits keep the live span fingerprint-able (tracker → anchorer round trip)", () => {
    let spans = [liveSpan()];
    let doc = DOC;
    const insertAt = DOC.indexOf("intro") + "intro".length;
    const inserted = " (note)";
    doc = doc.slice(0, insertAt) + inserted + doc.slice(insertAt);
    spans = applyChange(spans, { start: insertAt, end: insertAt, newLength: inserted.length }, HUMAN, {
      newId: () => "n1", now: () => "2026-06-10T01:00:00.000Z",
    });
    const agent = spans.find((x) => x.author.kind === "agent")!;
    expect(doc.slice(agent.start, agent.end)).toBe("Claude wrote this sentence");
    const fp = buildFingerprint(doc, { start: agent.start, end: agent.end });
    expect(resolve(doc, fp)).toEqual({ start: agent.start, end: agent.end });
  });
});
```

- [ ] **Step 5.2:** `npx vitest run test/attributionPersistence.test.ts` → PASS.
- [ ] **Step 5.3: Commit** — `F3 SLICE-4: persistence/re-anchor/orphan decision-logic tests (INV-1/INV-6) (#6)` + trailer.

### Task 6: SLICE-5 — Live `claude-code` turn + documented manual smoke

**Files:**
- Create: `src/liveTurn.ts`, `scripts/smoke-live-turn.mjs`, `docs/MANUAL-SMOKE-F3.md`
- Modify: `src/extension.ts`, `esbuild.mjs`, `package.json`
- Test: `test/liveTurn.test.ts`

- [ ] **Step 6.1: Create `src/liveTurn.ts`:**

```typescript
/**
 * LiveTurn — the minimal machine-edit ingress (spec §6.2): one @cline/sdk
 * Agent turn on the built-in `claude-code` provider, which rides the
 * operator's local Claude Code Pro/Max login — the extension holds NO
 * credentials of any kind (INV-8). vscode-free; the editSelection command
 * (extension.ts) feeds the result into the applyAgentEdit seam (INV-9).
 *
 * Like src/cline.ts: @cline/sdk is ESM-only, loaded via dynamic import(),
 * never bundled (esbuild keeps it external).
 */

export interface EditTurnResult {
  replacement: string;
  model: string;
  /** the SDK run id — recorded as provenance sessionId. */
  sessionId: string;
}

const SYSTEM_PROMPT = [
  "You are a precise text editor embedded in VS Code.",
  "You will be given a piece of text and an instruction.",
  "Respond with ONLY the edited replacement text — no explanation, no preamble,",
  "no markdown code fences. Preserve the original's leading/trailing whitespace",
  "unless the instruction says otherwise.",
].join(" ");

/** Strip a wrapping markdown code fence if the model added one anyway. */
export function extractReplacement(outputText: string): string {
  const m = outputText.match(/^\s*```[^\n]*\n([\s\S]*?)\n?```\s*$/);
  return m ? m[1] : outputText;
}

export async function runEditTurn(
  instruction: string,
  selectedText: string,
  opts?: { modelId?: string },
): Promise<EditTurnResult> {
  const sdk = await import("@cline/sdk");
  const modelId = opts?.modelId ?? "sonnet";
  const agent = new sdk.Agent({
    providerId: "claude-code",
    modelId,
    systemPrompt: SYSTEM_PROMPT,
  });
  const result = await agent.run(
    `<instruction>\n${instruction}\n</instruction>\n<text>\n${selectedText}\n</text>`,
  );
  if (result.status !== "success") {
    throw new Error(
      `claude-code turn ${result.status}: ${result.error?.message ?? "unknown error"} ` +
        "(is Claude Code installed and signed in?)",
    );
  }
  return { replacement: extractReplacement(result.outputText), model: modelId, sessionId: result.runId };
}
```

If `new sdk.Agent(...)` upsets TypeScript under `moduleResolution: Bundler` (the SDK's types resolve through re-exports), fall back to `const { Agent } = sdk as { Agent: new (c: object) => { run(i: string): Promise<{ runId: string; status: string; outputText: string; error?: Error }> } };` — but try the typed path first; the d.ts chain was verified to exist.

- [ ] **Step 6.2: Create `test/liveTurn.test.ts`** (pure helper only — no SDK, no LLM):

```typescript
import { describe, it, expect } from "vitest";
import { extractReplacement } from "../src/liveTurn";

describe("extractReplacement", () => {
  it("returns plain text untouched", () => {
    expect(extractReplacement("Hello world.")).toBe("Hello world.");
  });
  it("strips a wrapping fence", () => {
    expect(extractReplacement("```\nHello world.\n```")).toBe("Hello world.");
  });
  it("strips a language-tagged fence", () => {
    expect(extractReplacement("```markdown\nHello.\n```\n")).toBe("Hello.");
  });
  it("leaves inner fences alone", () => {
    const inner = "before\n```js\ncode\n```\nafter";
    expect(extractReplacement(inner)).toBe(inner);
  });
});
```

- [ ] **Step 6.3:** `npx vitest run test/liveTurn.test.ts` → PASS.
- [ ] **Step 6.4: The `cowriting.editSelection` command** — in `src/extension.ts` `activate`, after the `applyAgentEdit` command registration:

```typescript
  context.subscriptions.push(
    vscode.commands.registerCommand("cowriting.editSelection", async () => {
      const editor = vscode.window.activeTextEditor;
      if (!editor || editor.selection.isEmpty || !editor.document.uri.fsPath.startsWith(root)) {
        void vscode.window.showWarningMessage("Cowriting: select some text in a workspace document first.");
        return;
      }
      const instruction = await vscode.window.showInputBox({
        prompt: "What should Claude do with the selection?",
        placeHolder: "e.g. tighten this paragraph",
      });
      if (!instruction) return;
      const document = editor.document;
      const selection = editor.selection;
      const expectedVersion = document.version;
      const selectedText = document.getText(selection);
      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);
            const ok = await attributionController.applyAgentEdit(
              document,
              new vscode.Range(selection.start, selection.end),
              turn.replacement,
              {
                kind: "agent",
                id: "claude",
                agent: { sdk: "@cline/sdk", model: turn.model, sessionId: turn.sessionId },
              },
              { expectedVersion, turnId },
            );
            if (!ok) {
              void vscode.window.showWarningMessage(
                "Cowriting: the document changed while Claude was editing — nothing was applied.",
              );
            }
          },
        );
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        void vscode.window.showErrorMessage(`Cowriting: Claude edit failed — ${message}`);
      }
    }),
  );
```

NOTE: `await import("./liveTurn")` from the CJS bundle is fine — esbuild bundles relative dynamic imports; only `@cline/sdk` stays external (the inner `import("@cline/sdk")` is preserved, same as `cline.ts`).

- [ ] **Step 6.5: `package.json`** — add the command + script:

```json
      { "command": "cowriting.editSelection", "title": "Cowriting: Ask Claude to Edit Selection", "category": "Cowriting" }
```

and in `"scripts"`: `"smoke:live": "npm run build && node scripts/smoke-live-turn.mjs"`.

- [ ] **Step 6.6: `esbuild.mjs` second entry** — after the existing build options, build LiveTurn as ESM for the smoke script. Replace the bottom `if (watch) … else …` block with:

```javascript
/** @type {import('esbuild').BuildOptions} */
const liveTurnOptions = {
  entryPoints: ["src/liveTurn.ts"],
  outfile: "out/liveTurn.mjs",
  bundle: true,
  platform: "node",
  format: "esm",
  target: "node22",
  sourcemap: true,
  external: ["vscode", "@cline/sdk"],
  logLevel: "info",
};

if (watch) {
  const ctx = await context(options);
  const ctxLive = await context(liveTurnOptions);
  await Promise.all([ctx.watch(), ctxLive.watch()]);
  console.log("esbuild: watching…");
} else {
  await build(options);
  await build(liveTurnOptions);
  console.log("esbuild: build complete → out/extension.cjs + out/liveTurn.mjs");
}
```

- [ ] **Step 6.7: Create `scripts/smoke-live-turn.mjs`:**

```javascript
#!/usr/bin/env node
// Scripted half of the F3 manual smoke (docs/MANUAL-SMOKE-F3.md). Drives the
// REAL LiveTurn module against the local Claude Code login. Not run in CI.
import { runEditTurn } from "../out/liveTurn.mjs";

const instruction = process.argv[2] ?? "Replace this sentence with exactly: The smoke test passed.";
const text = process.argv[3] ?? "This sentence is the smoke-test input.";

console.log(`instruction: ${instruction}`);
console.log(`text:        ${text}`);
try {
  const t0 = Date.now();
  const result = await runEditTurn(instruction, text);
  console.log(`replacement: ${JSON.stringify(result.replacement)}`);
  console.log(`model:       ${result.model}`);
  console.log(`sessionId:   ${result.sessionId}`);
  console.log(`elapsed:     ${((Date.now() - t0) / 1000).toFixed(1)}s`);
  process.exit(0);
} catch (err) {
  console.error(`live turn failed (expected when Claude Code is absent/signed out): ${err.message}`);
  process.exit(1);
}
```

- [ ] **Step 6.8: Create `docs/MANUAL-SMOKE-F3.md`:**

```markdown
# F3 manual smoke — live `claude-code` turn (spec §6.8)

The live turn is deliberately NOT in CI (unit + host E2E drive the seam). It
gets this documented smoke, run once per machine that has Claude Code
installed and signed in (Pro/Max). The extension itself holds no credentials
(INV-8) — auth is entirely the local Claude Code login.

## 1. Scripted smoke (the quick check)

    npm run smoke:live

Expected: prints a `replacement:` line containing "The smoke test passed.",
the model id, a non-empty `sessionId`, and exits 0.

## 2. In-editor smoke (the real PUC-2)

1. `npm run build`, then F5 (Extension Development Host) opening this repo.
2. Open any markdown file in the workspace; type a sentence — it renders with
   the human gutter border (left edge) as you type.
3. Select the sentence → run **“Cowriting: Ask Claude to Edit Selection”** →
   instruction: `rewrite this more formally`.
4. Expected: progress notification; on completion the replacement text lands
   **tinted** (Claude-attributed), the human border remains on your other
   edits, and after **save** the sidecar
   `.threads/<doc>.json` has an `attributions[]` entry with
   `author.kind: "agent"`, `agent.model`, `agent.sessionId`, and a `turnId`.
5. **Cowriting: Toggle Attribution** hides/shows both decorations (PUC-5).

## 3. Failure paths (INV-8 — graceful, tracking unaffected)

- Signed out / no Claude Code: `PATH="" npm run smoke:live` (or sign out) →
  the script exits 1 with a clear error; in-editor, the command shows an
  error notification and NO edit is applied.
- Buffer edited mid-turn: start an edit-selection turn, type elsewhere in the
  document before it completes → warning notification "document changed", no
  partial application (stale `expectedVersion`, spec §6.9).

## Smoke log

| Date | Machine | Result |
| --- | --- | --- |
| (fill on first run) | | |
```

- [ ] **Step 6.9:** `npm run typecheck` && `npm run build` && `npx vitest run` → all green.
- [ ] **Step 6.10: Run the scripted smoke once** (this machine has Claude Code signed in): `npm run smoke:live` → record the result row in `docs/MANUAL-SMOKE-F3.md`'s Smoke log table. Also run the failure path `PATH="" node scripts/smoke-live-turn.mjs` → confirm clean exit-1 error. (If the live call is unexpectedly slow, give it ~2 min before judging.)
- [ ] **Step 6.11: Commit** — `F3 SLICE-5: live claude-code turn via applyAgentEdit seam + manual smoke (INV-8) (#6)` + trailer.

> **Amendment 2 (post–Task-7 host-E2E findings).** The host E2E exposed two
> real product bugs invisible to the unit suite (both host-only behaviors):
> 1. **`isDirty` cannot classify disk syncs.** VS Code delivers the content
>    change BEFORE flipping the dirty flag, so the first edit on a clean
>    document arrives with `isDirty === false` — identical signature to a
>    revert. Fix: on a `!isDirty` change event, compare `document.getText()`
>    to the file's on-disk content — equal → disk sync (re-resolve via
>    `loadAll`); different → real edit (attribute). Read errors → attribute.
> 2. **VS Code diff-minimizes WorkspaceEdits**, so the seam's exact
>    `(start,end,text)` match misses whenever `newText` shares a prefix/suffix
>    with the replaced text (the agent edit then mis-attributes to the human —
>    an INV-9 break). Fix: `applyAgentEdit` minimizes the replace itself
>    (greedy common-prefix then common-suffix trim, non-overlapping) and both
>    registers and applies the minimized triple; an edit that minimizes to
>    nothing is a no-op returning true without applying. New vscode-free
>    helper `minimizeReplace(oldText, newText)` in `src/pendingEdits.ts` +
>    unit tests. Minimization is TRANSPORT-only: the registration carries the
>    pre-minimization extent (`PendingEdit.full`) and the tracker attributes
>    the agent's FULL intended replacement (intent-honest reading of
>    INV-7/PUC-2 — the turn's whole replacement is the unit of machine
>    authorship), not just the minimized delta.

### Task 7: SLICE-6 — Host E2E (no LLM in CI)

**Files:**
- Create: `test/e2e/fixtures/workspace/docs/attrib.md`, `test/e2e/suite/attribution.test.ts`

- [ ] **Step 7.1: Create the fixture** `test/e2e/fixtures/workspace/docs/attrib.md`:

```markdown
# Attribution fixture

A stable first paragraph that predates tracking.

The target sentence lives here for seam edits.
```

- [ ] **Step 7.2: Create `test/e2e/suite/attribution.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/attrib.md";

function sidecarPath(): string {
  return path.join(WS, ".threads", "docs", "attrib.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?.attributionController, "extension exports attributionController");
  return api;
}
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));

suite("F3 live attribution (host E2E — seam-driven, no LLM)", () => {
  const TYPED = "A human-typed sentence. ";

  test("typing produces a live human span", async () => {
    const doc = await openDoc();
    const api = await getApi();
    const editor = vscode.window.activeTextEditor!;
    const insertAt = doc.getText().length;
    await editor.edit((eb) => eb.insert(doc.positionAt(insertAt), TYPED));
    await settle();
    const spans = api.attributionController.getSpans(DOC_REL);
    assert.strictEqual(spans.length, 1);
    assert.strictEqual(spans[0].authorKind, "human");
    assert.strictEqual(doc.getText().slice(spans[0].range.start, spans[0].range.end), TYPED);
  });

  test("a seam edit produces an agent span; mixed edits stay char-honest (INV-7/INV-9)", async () => {
    const doc = await openDoc();
    const api = await getApi();
    const target = "target sentence";
    const start = doc.getText().indexOf(target);
    const ok = await api.attributionController.applyAgentEdit(
      doc,
      new vscode.Range(doc.positionAt(start), doc.positionAt(start + target.length)),
      "REWRITTEN-BY-CLAUDE sentence",
      { kind: "agent", id: "claude", agent: { sdk: "@cline/sdk", model: "sonnet", sessionId: "e2e-run" } },
      { turnId: "turn-e2e-1" },
    );
    assert.strictEqual(ok, true, "seam edit applies");
    await settle();
    const spans = api.attributionController.getSpans(DOC_REL);
    const agent = spans.find((s) => s.authorKind === "agent");
    assert.ok(agent, "agent span exists");
    assert.strictEqual(agent!.turnId, "turn-e2e-1");
    assert.strictEqual(
      doc.getText().slice(agent!.range.start, agent!.range.end),
      "REWRITTEN-BY-CLAUDE sentence",
    );
    assert.ok(spans.some((s) => s.authorKind === "human"), "human span still tracked");
  });

  test("stale expectedVersion refuses to apply (spec §6.9)", async () => {
    const doc = await openDoc();
    const api = await getApi();
    const ok = await api.attributionController.applyAgentEdit(
      doc,
      new vscode.Range(doc.positionAt(0), doc.positionAt(1)),
      "X",
      { kind: "agent", id: "claude", agent: { sdk: "@cline/sdk", model: "sonnet", sessionId: "e2e" } },
      { expectedVersion: doc.version - 1 },
    );
    assert.strictEqual(ok, false);
  });

  test("save persists attributions[]; reload restores spans at re-resolved anchors (PUC-4)", async () => {
    const doc = await openDoc();
    const api = await getApi();
    await doc.save();
    await settle();
    const art = readSidecar();
    assert.ok(art.attributions.length >= 2, "human + agent records persisted");
    const agentRec = art.attributions.find((a) => a.author.kind === "agent")!;
    assert.strictEqual(art.anchors[agentRec.anchorId].fingerprint.text, "REWRITTEN-BY-CLAUDE sentence");
    assert.strictEqual(agentRec.turnId, "turn-e2e-1");

    api.attributionController.loadAll(doc);
    const spans = api.attributionController.getSpans(DOC_REL);
    assert.ok(spans.some((s) => s.authorKind === "agent"), "agent span restored from sidecar");
    assert.strictEqual(api.attributionController.getOrphanCount(DOC_REL), 0);
  });

  test("external move re-anchors; mangling the text orphans (INV-1/INV-6)", async () => {
    const uri = vscode.Uri.file(path.join(WS, DOC_REL));
    const original = fs.readFileSync(uri.fsPath, "utf8");
    const api = await getApi();

    let doc = await externalWriteAndReload(uri, "PREPENDED LINE\n\n" + original);
    await settle();
    api.attributionController.loadAll(doc);
    let spans = api.attributionController.getSpans(DOC_REL);
    const agent = spans.find((s) => s.authorKind === "agent")!;
    const moved = doc.getText().indexOf("REWRITTEN-BY-CLAUDE sentence");
    assert.strictEqual(agent.range.start, moved, "agent span re-anchored after move");
    assert.strictEqual(api.attributionController.getOrphanCount(DOC_REL), 0);

    const mangled = doc.getText().replace("REWRITTEN-BY-CLAUDE sentence", "now something else entirely");
    doc = await externalWriteAndReload(uri, mangled);
    await settle();
    api.attributionController.loadAll(doc);
    spans = api.attributionController.getSpans(DOC_REL);
    assert.ok(!spans.some((s) => s.authorKind === "agent"), "mangled agent span not rendered");
    assert.ok(api.attributionController.getOrphanCount(DOC_REL) >= 1, "…it is orphaned instead (INV-1)");
  });
});
```

- [ ] **Step 7.3:** `npm run test:e2e` → BOTH suites green (F2 threads + F3 attribution). Debugging notes: the `settle()` waits exist because decorations/change events are async-dispatched; if the human-span count flakes, check whether the `revert` in earlier tests left `attrib.md` dirty. The fixture doc is dedicated to this suite — do not touch `sample.md` (the threads suite owns it).
- [ ] **Step 7.4: Commit** — `F3 SLICE-6: host E2E — type/seam/persist/re-anchor/orphan, no LLM in CI (#6)` + trailer.

### Task 8: Ship

- [ ] **Step 8.1: Full gate:** `npm run typecheck && npx vitest run && npm run build && npm run test:e2e` → all green (the §9 pipeline's localhost+E2E stage; this app has no PPE/prod — non-shippable, spec §7.3).
- [ ] **Step 8.2: README** — add an F3 section beside the F2 one: what attribution is, the three commands, sidecar `attributions[]`, link to `docs/MANUAL-SMOKE-F3.md`, and the test commands (`npx vitest run`, `npm run test:e2e`, `npm run smoke:live`).
- [ ] **Step 8.3: Push branch** (SSH remote, push before PR per convention): `git push -u origin feat/f3-live-attribution`.
- [ ] **Step 8.4: PR** to `main`: title `F3: live human/Claude attribution on @cline/sdk claude-code (Feature #6)`, body citing spec `coauthoring-attribution.md` §7.2 SLICE-1..6 + acceptance (#6), and `Fixes #6` if the tracker convention closes features on merge (F2's PR #5 precedent — mirror it). Merge (autonomous posture).
- [ ] **Step 8.5:** Verify `main` green post-merge (`git pull` + Step 8.1 gate), then hand off to `wgl-session-finalize` (archives this plan to the content repo `plans/`, publishes the transcript, updates memory).

---

## Self-review notes (spec → task traceability)

| Spec requirement | Task |
| --- | --- |
| SLICE-1 typed `attributions[]` + round-trip (§6.3) | Task 1 |
| SLICE-2 span algebra + exhaustive units (INV-7) | Task 2 |
| SLICE-3 seam + registry + human wiring + decorations/toggle (INV-9, PUC-1/2/3/5) | Tasks 3–4 |
| SLICE-4 save/reload/external-change/orphan (INV-1/INV-6, PUC-4) | Task 4 (code) + Task 5 (unit coverage) + Task 7 (E2E) |
| SLICE-5 live turn + manual smoke + graceful failure (INV-8) | Task 6 |
| SLICE-6 host E2E, no LLM in CI (§6.8) | Task 7 |
| Sidecar co-ownership (Thread + Attribution writers) | Task 3 (`store.update`) |
| `schemaVersion` stays 1; unattributed = absence of span | Task 1 / by construction |
| Status-bar orphan count + output channel (§5 UX) | Task 4 |