# F8 Out-of-Workspace Authoring 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:** Let the human "Ask Claude to Edit Selection" (threads / attribution / propose-accept) on **any** document the editor shows — saved-in-folder, saved-out-of-folder, or untitled — matching the already-universal F6 diff / F7 preview, while keeping in-workspace authoring byte-for-byte unchanged.

**Architecture:** Introduce one `SidecarStore` storage interface and a `SidecarRouter` façade that routes per-document by `#24`'s `isUnderRoot`: in-workspace `file:` docs keep the committable repo `.threads/<repo-rel>.json` sidecar (`CoauthorStore`, **unmodified**, INV-2); out-of-workspace `file:` + `untitled:` docs persist to a global-storage sidecar (`GlobalSidecarStore`, mirroring F6's `BaselineStore`, keyed by `sha256(uri)`; untitled in-memory only). The three authoring controllers depend on the router; their workspace-root gate becomes a shared `isAuthorable` predicate (scheme ∈ {file, untitled}), with `isUnderRoot` demoted from a gate to a routing input. Same `Artifact` shape + `SCHEMA_VERSION=1` either home, so `mergeArtifacts` / the F5 cross-rung contract are untouched (INV-25: global artifacts are single-rung).

**Tech Stack:** TypeScript, VS Code extension API, Node `fs`/`crypto`, vitest (unit), `@vscode/test-electron` + mocha (host E2E). Spec: `specs/coauthoring-out-of-workspace.md`.

**Conventions in this codebase (read before starting):**
- New stores are **vscode-free** (Node `fs`/`crypto` only) so they unit-test under vitest — mirror `src/baselineStore.ts` + `test/baselineStore.test.ts`.
- The document key for an in-workspace file is its **repo-relative path** (`docs/x.md`); for everything else it is the **URI string** (`file:///abs/x.md`, `untitled:Untitled-1`). The router's `keyOf` is the single source of that identity.
- `SidecarStore` is the 4-method storage surface (`load`/`save`/`update`/`consumeSelfWrite`) — `CoauthorStore` already conforms structurally (do **not** add `implements` to it; leave it untouched, INV-2). `SidecarRouter implements SidecarStore` and **adds** `keyOf` + `sidecarPath`; the three controllers + their test-facing surfaces are typed to the concrete `SidecarRouter`.
- Run unit tests with `npm test` (vitest). Run host E2E with `npm run test:e2e` (builds + compiles `tsconfig.e2e.json` + launches two EDH passes: one with the fixture workspace, one with no folder).
- After each task: `npm test` green, `npm run typecheck` clean, then commit.

---

## File Structure

**Create:**
- `src/sidecarStore.ts` — the `SidecarStore` interface (4-method storage surface) + `DocKey`/identity types.
- `src/globalSidecarStore.ts` — `GlobalSidecarStore` (vscode-free): out-of-folder `file:` → `<dir>/sidecars/<sha256(uri)>.json`; `untitled:` → in-memory map; `consumeSelfWrite` ⇒ false; `update` with INV-16 throw + anchor prune.
- `src/sidecarRouter.ts` — `SidecarRouter` (vscode-free): `keyOf(identity)`, per-key routing of `load`/`save`/`update`/`consumeSelfWrite`/`sidecarPath`; plus `docIdentity(doc)` extractor.
- `test/globalSidecarStore.test.ts`, `test/sidecarRouter.test.ts` — unit tests.
- `test/e2e/suite/outOfWorkspace.test.ts` — host E2E (out-of-folder file + untitled + in-workspace regression).
- `docs/MANUAL-SMOKE-F8.md` — live smoke runbook.

**Modify:**
- `src/workspacePath.ts` — add `isAuthorable(scheme)`; rewrite `selectionRejection` to reject only `!isAuthorable` (keep no-editor / empty-selection). `isUnderRoot` retained (router input).
- `src/versionGuard.ts` — `store: CoauthorStore` → `store: SidecarStore`.
- `src/threadController.ts`, `src/attributionController.ts`, `src/proposalController.ts` — constructor `store: CoauthorStore` → `store: SidecarRouter`, `rootDir: string` → `rootDir: string | undefined`; replace `isInRoot`/`isTracked` with `isAuthorable`; replace `docPathOf` with `store.keyOf(docIdentity(document))`; `handleExternalSidecarChange` uses `store.sidecarPath`.
- `src/extension.ts` — construct `GlobalSidecarStore` + `SidecarRouter`; remove the no-root early-return + command stubs (authoring commands live folder-less); `renderIfOpen` gated by `isAuthorable`; widen the seam command lookups; export `sidecarRouter` on `CowritingApi`.
- `test/workspacePath.test.ts` — extend for `isAuthorable` + new `selectionRejection` behavior.
- `test/e2e/suite-no-workspace/noWorkspace.test.ts` — authoring commands are now real (not stubs); `activate` returns an API even with no folder.
- `README.md` — hybrid-persistence + F5 non-shareability note.
- `src/model.ts` — **no change** (Artifact + SCHEMA_VERSION untouched, INV-24).

---

## Task 1: `SidecarStore` interface

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

- [ ] **Step 1: Write the interface**

```typescript
/**
 * SidecarStore — the storage surface the three authoring controllers depend on
 * (F8 spec §6.2/§6.4). One per-document `Artifact` keyed by a string `key` (the
 * document key — repo-relative path in-workspace, URI string otherwise; the
 * router's keyOf is the single source). Two implementations:
 *   - CoauthorStore (src/store.ts) — the committable repo `.threads/` sidecar,
 *     keyed by repo-relative path (INV-2, byte-for-byte unchanged; conforms
 *     structurally — not modified for F8).
 *   - GlobalSidecarStore (src/globalSidecarStore.ts) — out-of-workspace `file:`
 *     and `untitled:` docs, in VS Code GLOBAL storage keyed by sha256(uri)
 *     (INV-19/24/25; untitled in-memory only).
 * SidecarRouter (src/sidecarRouter.ts) implements this AND adds keyOf/sidecarPath;
 * the controllers receive the router.
 */
import type { Artifact } from "./model";

export interface SidecarStore {
  /** Load the artifact for `key`, or null if none persisted. */
  load(key: string): Artifact | null;
  /** Overwrite the artifact for `key` (newest wins, no history). */
  save(key: string, artifact: Artifact): void;
  /**
   * Read-modify-write: load (or empty), apply `mutate`, prune anchors referenced
   * by no thread/attribution/proposal, persist, return the result. MUST be
   * synchronous (the F3 co-ownership contract). Throws on a newer-major sidecar
   * (INV-16 backstop).
   */
  update(key: string, mutate: (artifact: Artifact) => void): Artifact;
  /**
   * Decrement-and-report whether `fsPath` is a sidecar this store just wrote
   * (repo sidecars only; the global store is outside the `.threads/` watcher so
   * its impl is a no-op returning false).
   */
  consumeSelfWrite(fsPath: string): boolean;
}
```

- [ ] **Step 2: Verify it typechecks**

Run: `npm run typecheck`
Expected: clean (no references yet).

- [ ] **Step 3: Commit**

```bash
git add src/sidecarStore.ts
git commit -m "feat(f8): add SidecarStore storage interface (spec §6.4)"
```

---

## Task 2: `GlobalSidecarStore` — round-trip for `file:` URIs

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

- [ ] **Step 1: Write the failing test (file URI round-trip + path + missing + self-write)**

```typescript
import { describe, it, expect, beforeEach, afterEach } from "vitest";
import * as fs from "node:fs";
import * as os from "node:os";
import * as path from "node:path";
import { createHash } from "node:crypto";
import { GlobalSidecarStore } from "../src/globalSidecarStore";
import { emptyArtifact, SCHEMA_VERSION, type Artifact } from "../src/model";

let dir: string;
beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), "global-sidecar-")); });
afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });

const FILE_URI = "file:///abs/notes/chapter-1.md";
const hash = (uri: string) => createHash("sha256").update(uri).digest("hex");

function withThread(uri: string): Artifact {
  const a = emptyArtifact(uri);
  a.anchors["an_1"] = { fingerprint: { text: "hi", before: "", after: "", lineHint: 0 } };
  a.threads.push({ id: "t_1", anchorId: "an_1", status: "open", messages: [] });
  return a;
}

describe("GlobalSidecarStore — file: URIs persist to <dir>/sidecars/<sha256(uri)>.json", () => {
  it("returns null for a key with no sidecar", () => {
    expect(new GlobalSidecarStore(dir).load(FILE_URI)).toBeNull();
  });

  it("save then load round-trips the artifact at the hashed path", () => {
    const store = new GlobalSidecarStore(dir);
    const a = withThread(FILE_URI);
    store.save(FILE_URI, a);
    const onDisk = path.join(dir, "sidecars", `${hash(FILE_URI)}.json`);
    expect(fs.existsSync(onDisk)).toBe(true);
    expect(store.load(FILE_URI)).toEqual(a);
  });

  it("sidecarPath returns the hashed disk path for a file: URI", () => {
    const store = new GlobalSidecarStore(dir);
    expect(store.sidecarPath(FILE_URI)).toBe(path.join(dir, "sidecars", `${hash(FILE_URI)}.json`));
  });

  it("overwrites in place (newest wins, no history)", () => {
    const store = new GlobalSidecarStore(dir);
    store.save(FILE_URI, withThread(FILE_URI));
    const empty = emptyArtifact(FILE_URI);
    store.save(FILE_URI, empty);
    expect(store.load(FILE_URI)).toEqual(empty);
  });

  it("consumeSelfWrite is a no-op returning false (outside the .threads watcher)", () => {
    const store = new GlobalSidecarStore(dir);
    store.save(FILE_URI, withThread(FILE_URI));
    expect(store.consumeSelfWrite(store.sidecarPath(FILE_URI)!)).toBe(false);
  });

  it("update applies the mutation, prunes unreferenced anchors, and persists", () => {
    const store = new GlobalSidecarStore(dir);
    const result = store.update(FILE_URI, (a) => {
      a.anchors["orphan"] = { fingerprint: { text: "x", before: "", after: "", lineHint: 0 } };
      a.anchors["kept"] = { fingerprint: { text: "y", before: "", after: "", lineHint: 0 } };
      a.threads.push({ id: "t", anchorId: "kept", status: "open", messages: [] });
    });
    expect(Object.keys(result.anchors)).toEqual(["kept"]); // "orphan" pruned
    expect(store.load(FILE_URI)!.threads.length).toBe(1);
  });

  it("update throws on a newer-major sidecar (INV-16 backstop)", () => {
    const store = new GlobalSidecarStore(dir);
    const future = { ...emptyArtifact(FILE_URI), schemaVersion: SCHEMA_VERSION + 1 };
    store.save(FILE_URI, future as Artifact);
    expect(() => store.update(FILE_URI, () => {})).toThrow(/INV-16/);
  });
});
```

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

Run: `npm test -- globalSidecarStore`
Expected: FAIL ("Cannot find module '../src/globalSidecarStore'").

- [ ] **Step 3: Implement `GlobalSidecarStore` (file: branch first; untitled stub in-memory map)**

```typescript
/**
 * GlobalSidecarStore — the out-of-workspace/untitled authoring sidecar (F8 spec
 * §6.2/§6.4), mirroring BaselineStore (src/baselineStore.ts): vscode-free (Node
 * fs/crypto only), one `Artifact` JSON per document in VS Code's per-extension
 * GLOBAL storage, NEVER the repo (INV-19/24). The key passed in is the DOCUMENT
 * KEY (the URI string for the docs this store serves):
 *   - `file:` URI  → disk at `<dir>/sidecars/<sha256(uri)>.json`.
 *   - `untitled:`  → an in-memory Map only (no durable identity — the F6
 *     degrade); lost on reload, and never read by mergeArtifacts (INV-25).
 * `consumeSelfWrite` is a no-op (these artifacts are outside the `**/.threads/**`
 * watcher, so there is no self-write storm to suppress).
 */
import * as fs from "node:fs";
import * as path from "node:path";
import { createHash } from "node:crypto";
import {
  SCHEMA_VERSION,
  emptyArtifact,
  isNewerMajor,
  serializeArtifact,
  type Artifact,
} from "./model";
import type { SidecarStore } from "./sidecarStore";

export class GlobalSidecarStore implements SidecarStore {
  /** untitled keys live here only — no durable identity to persist against. */
  private readonly memory = new Map<string, Artifact>();

  /** @param storageDir absolute VS Code GLOBAL-storage dir (context.globalStorageUri.fsPath). */
  constructor(private readonly storageDir: string) {}

  private isUntitled(key: string): boolean {
    return key.startsWith("untitled:");
  }

  /** Filesystem-safe storage key for a persistable (file:) doc: sha256 of its URI. */
  private storageKey(key: string): string {
    return createHash("sha256").update(key).digest("hex");
  }

  /** Disk path for a `file:` key, or undefined for an in-memory untitled key. */
  sidecarPath(key: string): string | undefined {
    if (this.isUntitled(key)) return undefined;
    return path.join(this.storageDir, "sidecars", `${this.storageKey(key)}.json`);
  }

  load(key: string): Artifact | null {
    if (this.isUntitled(key)) return this.memory.get(key) ?? null;
    const p = this.sidecarPath(key)!;
    if (!fs.existsSync(p)) return null;
    return JSON.parse(fs.readFileSync(p, "utf8")) as Artifact;
  }

  save(key: string, artifact: Artifact): void {
    if (this.isUntitled(key)) {
      this.memory.set(key, artifact);
      return;
    }
    const p = this.sidecarPath(key)!;
    fs.mkdirSync(path.dirname(p), { recursive: true });
    fs.writeFileSync(p, serializeArtifact(artifact), "utf8");
  }

  /** See CoauthorStore.update — same INV-16 throw + anchor prune, no self-write mark. */
  update(key: string, mutate: (artifact: Artifact) => void): Artifact {
    const artifact = this.load(key) ?? emptyArtifact(key);
    if (isNewerMajor(artifact)) {
      throw new Error(
        `refusing to write ${key}: sidecar schemaVersion ${artifact.schemaVersion} > supported ${SCHEMA_VERSION} (INV-16)`,
      );
    }
    mutate(artifact);
    const referenced = new Set<string>([
      ...artifact.threads.map((t) => t.anchorId),
      ...artifact.attributions.map((a) => a.anchorId),
      ...artifact.proposals.map((p) => p.anchorId),
    ]);
    for (const id of Object.keys(artifact.anchors)) {
      if (!referenced.has(id)) delete artifact.anchors[id];
    }
    this.save(key, artifact);
    return artifact;
  }

  /** No-op: global artifacts are outside the `**/.threads/**` watcher. */
  consumeSelfWrite(_fsPath: string): boolean {
    return false;
  }
}
```

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

Run: `npm test -- globalSidecarStore`
Expected: PASS (all 7).

- [ ] **Step 5: Commit**

```bash
git add src/globalSidecarStore.ts test/globalSidecarStore.test.ts
git commit -m "feat(f8): GlobalSidecarStore for file: URIs (sha256 key, INV-19/24)"
```

---

## Task 3: `GlobalSidecarStore` — untitled in-memory branch

**Files:**
- Test: `test/globalSidecarStore.test.ts` (append)

- [ ] **Step 1: Append the failing test**

```typescript
describe("GlobalSidecarStore — untitled: keys are in-memory only (no disk, lost on reload)", () => {
  const UNTITLED = "untitled:Untitled-1";

  it("save then load round-trips within the same instance (session)", () => {
    const store = new GlobalSidecarStore(dir);
    const a = emptyArtifact(UNTITLED);
    a.threads.push({ id: "t", anchorId: "an", status: "open", messages: [] });
    a.anchors["an"] = { fingerprint: { text: "z", before: "", after: "", lineHint: 0 } };
    store.save(UNTITLED, a);
    expect(store.load(UNTITLED)).toEqual(a);
  });

  it("writes NO disk file for an untitled key", () => {
    const store = new GlobalSidecarStore(dir);
    store.save(UNTITLED, emptyArtifact(UNTITLED));
    expect(store.sidecarPath(UNTITLED)).toBeUndefined();
    expect(fs.existsSync(path.join(dir, "sidecars"))).toBe(false);
  });

  it("a fresh instance (simulated reload) has no untitled state", () => {
    const store = new GlobalSidecarStore(dir);
    store.save(UNTITLED, emptyArtifact(UNTITLED));
    expect(new GlobalSidecarStore(dir).load(UNTITLED)).toBeNull();
  });
});
```

- [ ] **Step 2: Run to verify it passes** (the untitled branch was implemented in Task 2)

Run: `npm test -- globalSidecarStore`
Expected: PASS (all 10). If any untitled test fails, fix the `isUntitled` branches in `globalSidecarStore.ts` until green.

- [ ] **Step 3: Commit**

```bash
git add test/globalSidecarStore.test.ts
git commit -m "test(f8): GlobalSidecarStore untitled in-memory branch"
```

---

## Task 4: `isAuthorable` + widened `selectionRejection`

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

- [ ] **Step 1: Write the failing tests (append to `test/workspacePath.test.ts`)**

```typescript
import { isAuthorable } from "../src/workspacePath";

describe("isAuthorable", () => {
  it("accepts file: and untitled: schemes", () => {
    expect(isAuthorable("file")).toBe(true);
    expect(isAuthorable("untitled")).toBe(true);
  });
  it("rejects read-only / virtual schemes", () => {
    expect(isAuthorable("git")).toBe(false);
    expect(isAuthorable("output")).toBe(false);
    expect(isAuthorable("cowriting-baseline")).toBe(false);
    expect(isAuthorable("")).toBe(false);
  });
});

describe("selectionRejection — F8 widened (accepts out-of-folder + untitled)", () => {
  const ok = { hasEditor: true, selectionEmpty: false, scheme: "file" };

  it("accepts an out-of-workspace file (no longer rejected)", () => {
    expect(selectionRejection({ ...ok, scheme: "file" })).toBeNull();
  });
  it("accepts an untitled buffer (no longer rejected)", () => {
    expect(selectionRejection({ ...ok, scheme: "untitled" })).toBeNull();
  });
  it("still names the missing editor", () => {
    expect(selectionRejection({ ...ok, hasEditor: false })).toMatch(/focus a text editor/i);
  });
  it("still names the empty selection", () => {
    expect(selectionRejection({ ...ok, selectionEmpty: true })).toMatch(/select some text/i);
  });
  it("rejects a non-{file,untitled} scheme with its own message (not 'select some text')", () => {
    const msg = selectionRejection({ ...ok, scheme: "git" });
    expect(msg).toMatch(/can.?t be edited|read-only|not a file/i);
    expect(msg).not.toMatch(/select some text/i);
  });
});
```

Note: the existing `selectionRejection` tests that assert "save this document" for `untitled` and "outside your workspace folder" for an out-of-root file are now **obsolete** — delete those two `it(...)` blocks (the ones at `test/workspacePath.test.ts` matching `/save this document/i` and `/outside your workspace folder/i`). Keep the `isUnderRoot` describe block unchanged.

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

Run: `npm test -- workspacePath`
Expected: FAIL (`isAuthorable` not exported; new selectionRejection expectations unmet).

- [ ] **Step 3: Implement — replace `selectionRejection` + add `isAuthorable` in `src/workspacePath.ts`**

Replace the `SelectionContext` interface and `selectionRejection` function (keep `isUnderRoot` exactly as is) with:

```typescript
/** Documents Cowriting can author on: a saved file OR an unsaved buffer (F8 §6.2). */
export function isAuthorable(scheme: string): boolean {
  return scheme === "file" || scheme === "untitled";
}

export interface SelectionContext {
  /** Is there an active text editor at all? */
  hasEditor: boolean;
  /** Is the active editor's selection empty (no highlight)? */
  selectionEmpty: boolean;
  /** The active document's URI scheme (`file`, `untitled`, …). */
  scheme: string;
}

/**
 * Why a selection can't be sent to Claude — or `null` if it can. F8 widened the
 * membership: any `file:` or `untitled:` document is authorable (in-workspace
 * files persist to the repo `.threads/` sidecar, out-of-workspace/untitled to
 * global storage — the router decides). Only a non-{file,untitled} scheme (a
 * read-only `git:`/`output:` view), a missing editor, or an empty selection is
 * refused — each with its own message (#24's per-condition messaging).
 */
export function selectionRejection(ctx: SelectionContext): string | null {
  if (!ctx.hasEditor) {
    return "Cowriting: focus a text editor with a selection first.";
  }
  if (ctx.selectionEmpty) {
    return "Cowriting: select some text to send to Claude first.";
  }
  if (!isAuthorable(ctx.scheme)) {
    return "Cowriting: this kind of document can't be edited — Cowriting authors on a file or an untitled buffer, not a read-only view.";
  }
  return null;
}
```

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

Run: `npm test -- workspacePath`
Expected: PASS.

- [ ] **Step 5: Commit**

```bash
git add src/workspacePath.ts test/workspacePath.test.ts
git commit -m "feat(f8): isAuthorable + widened selectionRejection (file|untitled)"
```

---

## Task 5: `SidecarRouter` — `keyOf` + per-key routing

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

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

```typescript
import { describe, it, expect, beforeEach, afterEach } from "vitest";
import * as fs from "node:fs";
import * as os from "node:os";
import * as path from "node:path";
import { createHash } from "node:crypto";
import { CoauthorStore } from "../src/store";
import { GlobalSidecarStore } from "../src/globalSidecarStore";
import { SidecarRouter, docIdentity } from "../src/sidecarRouter";
import { emptyArtifact } from "../src/model";

let root: string;
let globalDir: string;
beforeEach(() => {
  root = fs.mkdtempSync(path.join(os.tmpdir(), "router-root-"));
  globalDir = fs.mkdtempSync(path.join(os.tmpdir(), "router-global-"));
});
afterEach(() => {
  fs.rmSync(root, { recursive: true, force: true });
  fs.rmSync(globalDir, { recursive: true, force: true });
});

function makeRouter(withRoot = true): SidecarRouter {
  return new SidecarRouter(
    withRoot ? new CoauthorStore(root) : null,
    new GlobalSidecarStore(globalDir),
    withRoot ? root : undefined,
  );
}
// minimal duck-typed stand-in for a vscode.TextDocument's identity inputs
const docOf = (uriString: string, fsPath: string, scheme: string) => ({
  uri: { toString: () => uriString, fsPath, scheme },
});
const hash = (uri: string) => createHash("sha256").update(uri).digest("hex");

describe("SidecarRouter.keyOf — one identity per document", () => {
  it("an in-root file: doc → its repo-relative path", () => {
    const fsPath = path.join(root, "docs", "x.md");
    const key = makeRouter().keyOf(docIdentity(docOf(`file://${fsPath}`, fsPath, "file")));
    expect(key).toBe(path.join("docs", "x.md"));
  });
  it("an out-of-root file: doc → its URI string", () => {
    const fsPath = "/elsewhere/y.md";
    const uri = `file://${fsPath}`;
    expect(makeRouter().keyOf(docIdentity(docOf(uri, fsPath, "file")))).toBe(uri);
  });
  it("an untitled: doc → its URI string", () => {
    expect(makeRouter().keyOf(docIdentity(docOf("untitled:Untitled-1", "Untitled-1", "untitled")))).toBe(
      "untitled:Untitled-1",
    );
  });
  it("root undefined (no folder) → everything is the URI string", () => {
    const fsPath = "/anything/z.md";
    const uri = `file://${fsPath}`;
    expect(makeRouter(false).keyOf(docIdentity(docOf(uri, fsPath, "file")))).toBe(uri);
  });
});

describe("SidecarRouter routing — load/save/update dispatch by key home", () => {
  it("an in-root key writes to the repo .threads/ sidecar, not global storage", () => {
    const router = makeRouter();
    const key = path.join("docs", "x.md");
    router.save(key, emptyArtifact(key));
    expect(fs.existsSync(path.join(root, ".threads", "docs", "x.md.json"))).toBe(true);
    expect(fs.existsSync(path.join(globalDir, "sidecars"))).toBe(false);
    expect(router.sidecarPath(key)).toBe(path.join(root, ".threads", "docs", "x.md.json"));
  });
  it("an out-of-root file: key writes to global storage, not the repo", () => {
    const router = makeRouter();
    const key = "file:///elsewhere/y.md";
    router.save(key, emptyArtifact(key));
    expect(fs.existsSync(path.join(globalDir, "sidecars", `${hash(key)}.json`))).toBe(true);
    expect(fs.existsSync(path.join(root, ".threads"))).toBe(false);
    expect(router.sidecarPath(key)).toBe(path.join(globalDir, "sidecars", `${hash(key)}.json`));
  });
  it("an untitled: key is in-memory (global store), no disk anywhere", () => {
    const router = makeRouter();
    const key = "untitled:Untitled-1";
    router.update(key, (a) => a.threads.push({ id: "t", anchorId: "an", status: "open", messages: [] }));
    expect(router.load(key)!.threads.length).toBe(1);
    expect(router.sidecarPath(key)).toBeUndefined();
    expect(fs.existsSync(path.join(globalDir, "sidecars"))).toBe(false);
  });
  it("round-trips through load after update on an in-root key", () => {
    const router = makeRouter();
    const key = path.join("docs", "x.md");
    router.update(key, (a) => a.threads.push({ id: "t", anchorId: "an", status: "open", messages: [] }));
    expect(router.load(key)!.threads.length).toBe(1);
  });
});
```

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

Run: `npm test -- sidecarRouter`
Expected: FAIL ("Cannot find module '../src/sidecarRouter'").

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

```typescript
/**
 * SidecarRouter — the per-document persistence façade the three authoring
 * controllers depend on (F8 spec §6.2/§6.4). Implements SidecarStore and OWNS
 * the routing: it computes the single document key (keyOf) and dispatches
 * load/save/update/consumeSelfWrite/sidecarPath to the right implementation:
 *   - an in-workspace `file:` doc → CoauthorStore, keyed by its repo-relative
 *     path → `.threads/<path>.json` (committable, INV-2; the only home F5's
 *     cross-rung ever sees).
 *   - an out-of-workspace `file:` or `untitled:` doc → GlobalSidecarStore, keyed
 *     by its URI string → global storage (INV-19/24/25; untitled in-memory).
 * The membership predicate is `#24`'s isUnderRoot — here a ROUTING input, never
 * an authoring gate (that became isAuthorable). vscode-free (takes the extracted
 * identity, not a vscode.TextDocument) so it unit-tests.
 */
import * as path from "node:path";
import { isUnderRoot } from "./workspacePath";
import type { Artifact } from "./model";
import type { SidecarStore } from "./sidecarStore";

/** The minimal document identity the router routes on (extracted from a TextDocument). */
export interface DocIdentity {
  /** `document.uri.toString()` — the URI string. */
  uri: string;
  /** `document.uri.fsPath`. */
  fsPath: string;
  /** `document.uri.scheme`. */
  scheme: string;
}

/** Extract the routing identity from anything URI-shaped (a real vscode.TextDocument fits). */
export function docIdentity(doc: { uri: { toString(): string; fsPath: string; scheme: string } }): DocIdentity {
  return { uri: doc.uri.toString(), fsPath: doc.uri.fsPath, scheme: doc.uri.scheme };
}

export class SidecarRouter implements SidecarStore {
  constructor(
    private readonly repo: SidecarStore | null,
    private readonly global: SidecarStore & { sidecarPath(key: string): string | undefined },
    private readonly root: string | undefined,
  ) {}

  /**
   * The single document key: an in-workspace `file:` doc → its repo-relative
   * path (cross-rung-meaningful, the existing sidecar key, INV-2); everything
   * else → its URI string (machine-local, self-consistent — INV-25).
   */
  keyOf(id: DocIdentity): string {
    if (id.scheme === "file" && this.root !== undefined && isUnderRoot(id.fsPath, this.root)) {
      return path.relative(this.root, id.fsPath);
    }
    return id.uri;
  }

  /** A key is a global (URI-string) key iff it carries a URI scheme prefix. */
  private isGlobalKey(key: string): boolean {
    return key.startsWith("file://") || key.startsWith("untitled:");
  }
  private storeFor(key: string): SidecarStore {
    if (this.isGlobalKey(key) || this.repo === null) return this.global;
    return this.repo;
  }

  load(key: string): Artifact | null {
    return this.storeFor(key).load(key);
  }
  save(key: string, artifact: Artifact): void {
    this.storeFor(key).save(key, artifact);
  }
  update(key: string, mutate: (artifact: Artifact) => void): Artifact {
    return this.storeFor(key).update(key, mutate);
  }
  /** Only the repo store self-writes (the `.threads/` watcher); global is a no-op. */
  consumeSelfWrite(fsPath: string): boolean {
    return this.repo?.consumeSelfWrite(fsPath) ?? false;
  }

  /**
   * The sidecar's on-disk path: `.threads/<key>.json` for a repo key, the hashed
   * global path for an out-of-folder `file:` key, undefined for untitled. Used by
   * the controllers' external-change handler (only repo sidecars are watched) and
   * by the E2E to assert the storage home.
   */
  sidecarPath(key: string): string | undefined {
    if (this.isGlobalKey(key)) return this.global.sidecarPath(key);
    if (this.repo === null) return undefined;
    // CoauthorStore exposes sidecarPath(docPath): string (structural).
    return (this.repo as unknown as { sidecarPath(k: string): string }).sidecarPath(key);
  }
}
```

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

Run: `npm test -- sidecarRouter`
Expected: PASS.

- [ ] **Step 5: Commit**

```bash
git add src/sidecarRouter.ts test/sidecarRouter.test.ts
git commit -m "feat(f8): SidecarRouter — keyOf + per-document routing (spec §6.2)"
```

---

## Task 6: `VersionGuard` onto `SidecarStore`

**Files:**
- Modify: `src/versionGuard.ts`

- [ ] **Step 1: Re-point the store type**

In `src/versionGuard.ts`, change the import and field type from `CoauthorStore` to `SidecarStore`:

```typescript
import type { SidecarStore } from "./sidecarStore";
// ...
export class VersionGuard {
  private readonly warned = new Set<string>();

  constructor(private readonly store: SidecarStore) {}
  // isReadOnly / wasWarned unchanged — they only call store.load(key).
}
```

(Replace `import type { CoauthorStore } from "./store";` and `constructor(private readonly store: CoauthorStore)`. The `docPath` params are now document keys — no logic change.)

- [ ] **Step 2: Verify typecheck**

Run: `npm run typecheck`
Expected: clean (controllers still pass `CoauthorStore`, which conforms to `SidecarStore` structurally — Task 7 switches them to the router).

- [ ] **Step 3: Commit**

```bash
git add src/versionGuard.ts
git commit -m "refactor(f8): VersionGuard depends on SidecarStore not CoauthorStore"
```

---

## Task 7: Re-point the three controllers onto the router

**Files:**
- Modify: `src/threadController.ts`, `src/attributionController.ts`, `src/proposalController.ts`

This task changes three controllers the same way. Each currently: imports `CoauthorStore`, takes `store: CoauthorStore` + `rootDir: string`, gates on `isInRoot`/`isTracked` (`scheme==="file" && isUnderRoot(fsPath, rootDir)`), and computes its per-doc key via `docPathOf(uri) = vscode.workspace.asRelativePath(uri, false)`. After F8 each: takes `store: SidecarRouter` + `rootDir: string | undefined`, gates on `isAuthorable(document.uri.scheme)`, and computes its key via `this.store.keyOf(docIdentity(document))`.

- [ ] **Step 1: ThreadController — imports + constructor + gate + key**

In `src/threadController.ts`:

Replace the imports:
```typescript
import { CoauthorStore } from "./store";
// ...
import { isUnderRoot } from "./workspacePath";
```
with:
```typescript
import { SidecarRouter, docIdentity } from "./sidecarRouter";
// ...
import { isAuthorable } from "./workspacePath";
```

Change the constructor signature:
```typescript
  constructor(
    private readonly store: SidecarRouter,
    private readonly rootDir: string | undefined,
    private readonly guard: VersionGuard,
  ) {
```

Replace `isInRoot` and `docPathOf`:
```typescript
  private isInRoot(uri: vscode.Uri): boolean {
    return uri.scheme === "file" && isUnderRoot(uri.fsPath, this.rootDir);
  }

  private docPathOf(uri: vscode.Uri): string {
    return vscode.workspace.asRelativePath(uri, false);
  }
```
with a single key helper (the controller keys on the document key now):
```typescript
  private keyOf(document: vscode.TextDocument): string {
    return this.store.keyOf(docIdentity(document));
  }
```

Now update every caller in this file:
- `commentingRangeProvider`: `if (!this.isInRoot(document.uri)) return [];` → `if (!isAuthorable(document.uri.scheme)) return [];`
- `currentAuthor()`: `const email = gitUserEmail(this.rootDir);` → `const email = this.rootDir !== undefined ? gitUserEmail(this.rootDir) : undefined;`
- `persist(state)` calls `this.store.update(state.docPath, …)` — leave as is; `state.docPath` now holds the key (see DocState note below).
- `ensureState(document)`: replace `const docPath = this.docPathOf(document.uri);` with `const docPath = this.keyOf(document);` (everywhere `docPathOf(...)` appears in this file, use `this.keyOf(doc)` when a `TextDocument` is available; `state.docPath` already holds the key).
- `createThreadOnSelection`: `!this.isInRoot(editor.document.uri)` → `!isAuthorable(editor.document.uri.scheme)`; and `this.guard.isReadOnly(this.docPathOf(editor.document.uri))` → `this.guard.isReadOnly(this.keyOf(editor.document))`.
- `renderAll(document)`: `const docPath = this.docPathOf(document.uri);` → `const docPath = this.keyOf(document);`
- `handleExternalSidecarChange`: the body compares `this.store.sidecarPath(state.docPath) === p` and finds the doc by `this.docPathOf(d.uri) === state.docPath`. Replace with:
  ```typescript
  handleExternalSidecarChange(uri: vscode.Uri): void {
    const p = uri.fsPath;
    for (const state of this.docs.values()) {
      if (this.store.sidecarPath(state.docPath) === p) {
        const doc = vscode.workspace.textDocuments.find((d) => this.keyOf(d) === state.docPath);
        if (doc) this.renderAll(doc);
      }
    }
  }
  ```
- `onDidChange`: `this.docs.get(this.docPathOf(e.document.uri))` → `this.docs.get(this.keyOf(e.document))`.
- `onDidSave`: `this.docs.get(this.docPathOf(document.uri))` → `this.docs.get(this.keyOf(document))`.

Leave `DocState.docPath`'s field name as `docPath` (it now holds the document key — renaming it ripples needlessly; the comment on the field already says "keyed by docPath"). The `getRendered(docPath)` test surface keeps its name and still accepts the key (the repo-relative path for in-workspace docs, exactly as today).

- [ ] **Step 2: AttributionController — same transform**

In `src/attributionController.ts`:
- Imports: `import { CoauthorStore } from "./store";` → `import { SidecarRouter, docIdentity } from "./sidecarRouter";`; `import { isUnderRoot } from "./workspacePath";` → `import { isAuthorable } from "./workspacePath";`
- Constructor: `private readonly store: CoauthorStore,` → `private readonly store: SidecarRouter,`; `private readonly rootDir: string,` → `private readonly rootDir: string | undefined,`
- `isTracked(document)`:
  ```typescript
  private isTracked(document: vscode.TextDocument): boolean {
    return isAuthorable(document.uri.scheme);
  }
  ```
- Replace `docPathOf`:
  ```typescript
  private docPathOf(uri: vscode.Uri): string {
    return vscode.workspace.asRelativePath(uri, false);
  }
  ```
  with:
  ```typescript
  private keyOf(document: vscode.TextDocument): string {
    return this.store.keyOf(docIdentity(document));
  }
  ```
- `currentAuthor()`: `const email = gitUserEmail(this.rootDir);` → `const email = this.rootDir !== undefined ? gitUserEmail(this.rootDir) : undefined;`
- Every `this.docPathOf(<doc>.uri)` where a `TextDocument` is in scope → `this.keyOf(<doc>)`. Specifically:
  - `loadAll`: `const docPath = this.docPathOf(document.uri);` → `const docPath = this.keyOf(document);`
  - `handleExternalSidecarChange`:
    ```typescript
    handleExternalSidecarChange(uri: vscode.Uri): void {
      for (const s of this.docs.values()) {
        if (this.store.sidecarPath(s.docPath) === uri.fsPath) {
          const doc = vscode.workspace.textDocuments.find((d) => this.keyOf(d) === s.docPath);
          if (doc) this.loadAll(doc);
        }
      }
    }
    ```
  - `onDidChange`: `const docPath = this.docPathOf(e.document.uri);` → `const docPath = this.keyOf(e.document);`
  - `applyAgentEdit`: `const docPath = this.docPathOf(document.uri);` → `const docPath = this.keyOf(document);`
  - `onDidSave`: both `this.docPathOf(document.uri)` occurrences → `this.keyOf(document)`.
  - `render`: `this.docs.get(this.docPathOf(document.uri))` → `this.docs.get(this.keyOf(document))`.
- `matchesDisk(document)` reads `document.uri.fsPath` via `fs.statSync` — for an untitled buffer that path is not a real file, `statSync` throws, the `catch` returns `false` (treated as a real edit). Leave unchanged.

- [ ] **Step 3: ProposalController — same transform**

In `src/proposalController.ts`:
- Imports: `import { CoauthorStore } from "./store";` → `import { SidecarRouter, docIdentity } from "./sidecarRouter";`; `import { isUnderRoot } from "./workspacePath";` → `import { isAuthorable } from "./workspacePath";`
- Constructor: `private readonly store: CoauthorStore,` → `private readonly store: SidecarRouter,`; `private readonly rootDir: string,` → `private readonly rootDir: string | undefined,`
- `isTracked(document)`:
  ```typescript
  private isTracked(document: vscode.TextDocument): boolean {
    return isAuthorable(document.uri.scheme);
  }
  ```
- Replace `docPathOf` with `keyOf` (same as the other two):
  ```typescript
  private keyOf(document: vscode.TextDocument): string {
    return this.store.keyOf(docIdentity(document));
  }
  ```
- Update callers:
  - `ensureState`: `const docPath = this.docPathOf(document.uri);` → `const docPath = this.keyOf(document);`
  - `propose`: both `this.docPathOf(document.uri)` (the `guard.isReadOnly` guard and `const docPath`) → `this.keyOf(document)`.
  - `renderAll`: `const docPath = this.docPathOf(document.uri);` → `const docPath = this.keyOf(document);`
  - `handleExternalSidecarChange`:
    ```typescript
    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.keyOf(d) === state.docPath);
          if (doc) this.renderAll(doc);
        }
      }
    }
    ```
  - `onDidChange`: `this.docs.get(this.docPathOf(e.document.uri))` → `this.docs.get(this.keyOf(e.document))`.
  - `openDoc(state)`: `vscode.workspace.textDocuments.find((d) => this.docPathOf(d.uri) === state.docPath)` → `vscode.workspace.textDocuments.find((d) => this.keyOf(d) === state.docPath)`.

- [ ] **Step 4: Verify typecheck (extension.ts still passes `CoauthorStore` — expected to fail here)**

Run: `npm run typecheck`
Expected: errors ONLY in `src/extension.ts` (it still constructs controllers with a `CoauthorStore` + non-optional root). Those are fixed in Task 8. The three controller files themselves must typecheck clean — if any controller file reports an error, fix it before proceeding.

- [ ] **Step 5: Commit**

```bash
git add src/threadController.ts src/attributionController.ts src/proposalController.ts
git commit -m "refactor(f8): controllers depend on SidecarRouter + isAuthorable (key via keyOf)"
```

---

## Task 8: Wire the router in `extension.ts`; authoring works folder-less

**Files:**
- Modify: `src/extension.ts`

- [ ] **Step 1: Imports + API surface**

Add imports near the top:
```typescript
import { GlobalSidecarStore } from "./globalSidecarStore";
import { SidecarRouter } from "./sidecarRouter";
```
Change `import { isUnderRoot, selectionRejection } from "./workspacePath";` to:
```typescript
import { isAuthorable, selectionRejection } from "./workspacePath";
```
Add `sidecarRouter` to the API interface:
```typescript
export interface CowritingApi {
  threadController: ThreadController;
  attributionController: AttributionController;
  proposalController: ProposalController;
  versionGuard: VersionGuard;
  diffViewController: DiffViewController;
  trackChangesPreviewController: TrackChangesPreviewController;
  sidecarRouter: SidecarRouter;
}
```

- [ ] **Step 2: Construct the global store next to the baseline store**

Right after the `baselineStore` construction (the F6 block), add:
```typescript
  // F8: the out-of-workspace/untitled authoring sidecar — same GLOBAL storage
  // home as the F6 baseline, keyed by sha256(uri) (INV-19/24). Constructed
  // workspace-independently; the router falls back to it for any non-in-folder doc.
  const globalSidecarStore = new GlobalSidecarStore(baselineStorageDir ?? "");
```
(When `baselineStorageDir` is undefined — global storage genuinely unavailable — file writes will throw and authoring degrades to errors-on-write, the F6-equivalent edge; untitled in-memory still works. This matches PUC-5.)

- [ ] **Step 3: Replace the no-root early-return block with folder-less wiring**

Replace the entire block from `const root = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;` through the `return undefined;` and its closing brace (the `if (!root) { … stubs … return undefined; }`) — i.e. lines that early-return on no folder — with:

```typescript
  // --- F8: authoring on ANY document (in-folder, out-of-folder, untitled) ---
  // The router routes per-document: in-workspace file: → the committable repo
  // `.threads/` sidecar (CoauthorStore); out-of-folder file: + untitled: → the
  // global-storage sidecar. Constructed even with NO folder open (everything
  // then routes global) — the F6 #19 precedent, now extended to authoring.
  const root = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
  const coauthorStore = root ? new CoauthorStore(root) : null;
  const sidecarRouter = new SidecarRouter(coauthorStore, globalSidecarStore, root);
  // F5 (INV-16): one shared guard — newer-major sidecars are read-only.
  const versionGuard = new VersionGuard(sidecarRouter);
  const threadController = new ThreadController(sidecarRouter, root, versionGuard);
  context.subscriptions.push(threadController);

  // --- F3: live attribution (Feature #6) ---
  const attributionController = new AttributionController(sidecarRouter, root, versionGuard);
  context.subscriptions.push(attributionController);

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

  // --- F6 machine-landing wiring — now for ANY authorable doc ---
  // The seam's single machine-landing signal advances the F6 baseline (INV-18);
  // the seam can now fire on out-of-folder files too, so wire it unconditionally.
  context.subscriptions.push(
    attributionController.onDidApplyAgentEdit((e) => diffViewController.advance(e.document)),
  );

  // One SHARED sidecar watcher for both controllers; self-writes are suppressed
  // centrally in the repo store (only repo `.threads/` sidecars are watched —
  // global artifacts live outside the workspace). Harmless when no folder is open.
  const watcher = vscode.workspace.createFileSystemWatcher("**/.threads/**/*.json");
  const onSidecar = (uri: vscode.Uri) => {
    if (sidecarRouter.consumeSelfWrite(uri.fsPath)) return;
    threadController.handleExternalSidecarChange(uri);
    attributionController.handleExternalSidecarChange(uri);
    proposalController.handleExternalSidecarChange(uri);
  };
  watcher.onDidChange(onSidecar);
  watcher.onDidCreate(onSidecar);
  context.subscriptions.push(watcher);
```

(Note: the F6/F7 controllers are constructed ABOVE this block, unchanged. Delete the old `const store = new CoauthorStore(root);`/`new VersionGuard(store)`/`new ThreadController(store, root, …)` etc. lines that this block replaces — they are now superseded.)

- [ ] **Step 4: Fix the `editSelection` rejection call (it passed `fsPath`/`root`, now gone)**

The `selectionRejection({...})` call inside `cowriting.editSelection` passes `scheme`, `fsPath`, `root`. Update it to the slimmed context:
```typescript
      const reason = selectionRejection({
        hasEditor: !!editor,
        selectionEmpty: editor?.selection.isEmpty ?? true,
        scheme: editor?.document.uri.scheme ?? "",
      });
```

- [ ] **Step 5: Widen `renderIfOpen` to any authorable doc**

Replace:
```typescript
  const renderIfOpen = (doc: vscode.TextDocument) => {
    if (doc.uri.scheme === "file" && isUnderRoot(doc.uri.fsPath, root)) {
      threadController.renderAll(doc);
      attributionController.loadAll(doc);
      proposalController.renderAll(doc);
    }
  };
```
with:
```typescript
  const renderIfOpen = (doc: vscode.TextDocument) => {
    if (isAuthorable(doc.uri.scheme)) {
      threadController.renderAll(doc);
      attributionController.loadAll(doc);
      proposalController.renderAll(doc);
    }
  };
```

- [ ] **Step 6: Return the full API (including the router)**

At the end of `activate`, the `return { … }` now always runs (no early `return undefined`). Add `sidecarRouter`:
```typescript
  return {
    threadController,
    attributionController,
    proposalController,
    versionGuard,
    diffViewController,
    trackChangesPreviewController,
    sidecarRouter,
  };
```

- [ ] **Step 7: Verify typecheck + unit tests**

Run: `npm run typecheck && npm test`
Expected: typecheck clean; all unit tests PASS (130 prior + the new global/router/workspacePath tests).

- [ ] **Step 8: Commit**

```bash
git add src/extension.ts
git commit -m "feat(f8): wire SidecarRouter; authoring commands live folder-less (#19 precedent)"
```

---

## Task 9: Update the no-workspace E2E suite

**Files:**
- Modify: `test/e2e/suite-no-workspace/noWorkspace.test.ts`

After F8, with no folder open, `activate()` returns a real API and the authoring commands are real (they route to global storage), not warning stubs.

- [ ] **Step 1: Rewrite the suite's expectations**

Replace the body of the three authoring-related tests so they assert the new behavior. Keep the "EDH really has no workspace folder" test and the F6 test unchanged. Replace the two stub tests with:

```typescript
  test("activate returns a real API even with no workspace folder (F8)", async () => {
    const ext = vscode.extensions.getExtension("benstull.vscode-cowriting-plugin")!;
    const api = await ext.activate();
    assert.ok(api?.proposalController, "no-folder activation returns the authoring API (F8)");
    assert.ok(api?.sidecarRouter, "router exposed");
  });

  test("all contributed coauthoring commands are registered (real, not stubs)", async () => {
    const all = await vscode.commands.getCommands(true);
    for (const command of [
      "cowriting.createThread",
      "cowriting.reply",
      "cowriting.resolveThread",
      "cowriting.reopenThread",
      "cowriting.editSelection",
      "cowriting.toggleAttribution",
      "cowriting.applyAgentEdit",
      "cowriting.acceptProposal",
      "cowriting.rejectProposal",
      "cowriting.proposeAgentEdit",
    ]) {
      assert.ok(all.includes(command), `${command} is registered`);
    }
  });

  test("authoring works folder-less: propose→accept on an untitled buffer routes to global storage (F8)", async () => {
    const ext = vscode.extensions.getExtension("benstull.vscode-cowriting-plugin")!;
    const api = await ext.activate();
    const untitled = await vscode.workspace.openTextDocument({ content: "Edit this scratch sentence please.\n", language: "markdown" });
    await vscode.window.showTextDocument(untitled);
    await new Promise((r) => setTimeout(r, 300));
    const key = untitled.uri.toString();
    const target = "Edit this scratch sentence please.";
    const start = untitled.getText().indexOf(target);
    const id = await vscode.commands.executeCommand<string>("cowriting.proposeAgentEdit", {
      uri: key, start, end: start + target.length, newText: "REPLACED scratch sentence.", model: "sonnet", sessionId: "e2e-nf", turnId: "turn-nf",
    });
    assert.ok(id, "propose returns an id for an untitled buffer with no folder");
    assert.ok(await api.proposalController.acceptById(key, id!), "accept applies");
    await new Promise((r) => setTimeout(r, 300));
    assert.ok(untitled.getText().includes("REPLACED scratch sentence."), "replacement landed in the untitled buffer");
    assert.strictEqual(api.sidecarRouter.sidecarPath(key), undefined, "untitled artifact is in-memory only (no disk)");
  });
```

Also remove the now-obsolete top-of-file comment claim that the commands are "warning stubs" (replace with a one-line note that F8 made them real).

- [ ] **Step 2: Verify (built by the E2E run in Task 11; typecheck via the e2e tsconfig)**

Run: `npm run pretest:e2e`
Expected: builds + `tsc -p tsconfig.e2e.json` compiles clean.

- [ ] **Step 3: Commit**

```bash
git add test/e2e/suite-no-workspace/noWorkspace.test.ts
git commit -m "test(f8): no-folder suite — authoring commands are real, route to global"
```

---

## Task 10: Host E2E — out-of-workspace file + untitled + in-workspace regression

**Files:**
- Create: `test/e2e/suite/outOfWorkspace.test.ts`

- [ ] **Step 1: Write the E2E suite**

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

const WS = process.env.E2E_WORKSPACE!;
const settle = () => new Promise((r) => setTimeout(r, 300));

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 && api?.sidecarRouter, "extension exports the authoring API + router");
  return api;
}
async function proposeViaCommand(uri: string, text: string, target: string, newText: string, turnId: string): Promise<string> {
  const start = text.indexOf(target);
  assert.ok(start >= 0, `text contains "${target}"`);
  const id = await vscode.commands.executeCommand<string>("cowriting.proposeAgentEdit", {
    uri, start, end: start + target.length, newText, model: "sonnet", sessionId: "e2e-oow", turnId,
  });
  assert.ok(id, "propose returns the proposal id");
  return id!;
}

// F8 host E2E (no LLM): authoring on a file OUTSIDE the workspace folder and on
// an untitled buffer, plus an in-workspace byte-for-byte regression. Runs in the
// WITH-workspace EDH pass (a folder is open; the out-of-folder file lives in a
// temp dir outside it — exactly like diffView's out-of-folder test).
suite("F8 out-of-workspace authoring (host E2E — programmatic seam, no LLM)", () => {
  test("out-of-folder file: propose→accept lands Claude-attributed; persisted in GLOBAL storage, no .threads (PUC-1, INV-9/24/25)", async () => {
    const outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), "cowriting-oow-"));
    const outsidePath = path.join(outsideDir, "sibling.md");
    const TARGET = "The sibling-repo sentence Claude edits.";
    fs.writeFileSync(outsidePath, `# Sibling\n\n${TARGET}\n`, "utf8");
    const uri = vscode.Uri.file(outsidePath);
    const doc = await vscode.workspace.openTextDocument(uri);
    await vscode.window.showTextDocument(doc);
    await settle();
    const api = await getApi();
    const key = uri.toString();

    const id = await proposeViaCommand(key, doc.getText(), TARGET, "The sibling sentence CLAUDE REWROTE.", "turn-oow1");
    await settle();
    // routed to global storage, never the repo
    const sidecar = api.sidecarRouter.sidecarPath(key)!;
    assert.ok(sidecar && fs.existsSync(sidecar), `global sidecar exists at ${sidecar}`);
    assert.ok(sidecar.includes(`${path.sep}sidecars${path.sep}`), "lives under <globalStorage>/sidecars/");
    assert.ok(!sidecar.includes(`${path.sep}.threads${path.sep}`), "NOT in a .threads/ tree (INV-25)");
    assert.ok(!fs.existsSync(path.join(outsideDir, ".threads")), "no .threads/ written beside the out-of-folder file");

    assert.ok(await api.proposalController.acceptById(key, id), "accept applies via the seam");
    await settle();
    assert.ok(doc.getText().includes("The sibling sentence CLAUDE REWROTE."), "replacement landed");
    const agent = api.attributionController.getSpans(key).find((s) => s.turnId === "turn-oow1");
    assert.ok(agent && agent.authorKind === "agent", "accepted text is Claude-attributed");
    assert.strictEqual(api.proposalController.getRendered(key).length, 0, "proposal gone (INV-13)");

    // a thread can be opened on the out-of-folder doc
    await vscode.window.showTextDocument(doc);
    const editor = vscode.window.activeTextEditor!;
    editor.selection = new vscode.Selection(doc.positionAt(0), doc.positionAt(8));
    const threadId = await api.threadController.createThreadOnSelection("thread on a sibling file");
    assert.ok(threadId, "a thread opens on the out-of-folder doc");

    // reload-restore from the GLOBAL sidecar (re-anchor content-based)
    fs.writeFileSync(outsidePath, "PREPENDED\n\n" + doc.getText(), "utf8");
    const reloaded = await vscode.workspace.openTextDocument(uri);
    await vscode.window.showTextDocument(reloaded);
    await vscode.commands.executeCommand("workbench.action.files.revert");
    await settle();
    api.threadController.renderAll(reloaded);
    assert.strictEqual(api.threadController.getRendered(key).length, 1, "thread restored from the global sidecar after reload");

    fs.rmSync(outsideDir, { recursive: true, force: true });
  });

  test("untitled buffer: propose→accept works in-session, state in-memory only (PUC-2)", async () => {
    const TARGET = "The untitled draft sentence.";
    const untitled = await vscode.workspace.openTextDocument({ content: `${TARGET}\n`, language: "markdown" });
    await vscode.window.showTextDocument(untitled);
    await settle();
    const api = await getApi();
    const key = untitled.uri.toString();
    assert.strictEqual(untitled.uri.scheme, "untitled", "really untitled");

    const id = await proposeViaCommand(key, untitled.getText(), TARGET, "The untitled draft, CLAUDE-EDITED.", "turn-oow2");
    await settle();
    assert.strictEqual(api.sidecarRouter.sidecarPath(key), undefined, "untitled artifact is in-memory only (no disk)");
    assert.ok(await api.proposalController.acceptById(key, id), "accept applies");
    await settle();
    assert.ok(untitled.getText().includes("The untitled draft, CLAUDE-EDITED."), "replacement landed in the untitled buffer");
    const agent = api.attributionController.getSpans(key).find((s) => s.turnId === "turn-oow2");
    assert.ok(agent && agent.authorKind === "agent", "untitled accepted text is Claude-attributed");
  });

  test("in-workspace regression: artifact still lands at <root>/.threads/<repo-rel>.json with the repo-relative document.path (INV-2)", async () => {
    const DOC_REL = "docs/f8regression.md";
    const TARGET = "An in-folder sentence for the F8 regression.";
    const abs = path.join(WS, DOC_REL);
    fs.mkdirSync(path.dirname(abs), { recursive: true });
    fs.writeFileSync(abs, `# F8 regression\n\n${TARGET}\n`, "utf8");
    const uri = vscode.Uri.file(abs);
    const doc = await vscode.workspace.openTextDocument(uri);
    await vscode.window.showTextDocument(doc);
    await settle();
    const api = await getApi();

    // the in-workspace key is the repo-relative path, not the URI string
    assert.strictEqual(api.sidecarRouter.keyOf({ uri: uri.toString(), fsPath: abs, scheme: "file" }), DOC_REL, "in-folder key is the repo-relative path");
    const id = await proposeViaCommand(uri.toString(), doc.getText(), TARGET, "An in-folder sentence, EDITED.", "turn-oow3");
    await settle();
    assert.ok(await api.proposalController.acceptById(DOC_REL, id), "accept by the repo-relative key");
    await settle();
    const sidecar = api.sidecarRouter.sidecarPath(DOC_REL)!;
    assert.strictEqual(sidecar, path.join(WS, ".threads", "docs", "f8regression.md.json"), "committable .threads/ path unchanged (INV-2)");
    assert.ok(fs.existsSync(sidecar), "sidecar written in the repo");
    const onDisk = JSON.parse(fs.readFileSync(sidecar, "utf8"));
    assert.strictEqual(onDisk.document.path, DOC_REL, "document.path is the repo-relative path (byte-for-byte)");
  });
});
```

- [ ] **Step 2: Commit**

```bash
git add test/e2e/suite/outOfWorkspace.test.ts
git commit -m "test(f8): host E2E — out-of-folder file + untitled + in-workspace regression"
```

---

## Task 11: Run the full host E2E suite

**Files:** none (verification).

- [ ] **Step 1: Run the E2E**

Run: `npm run test:e2e`
Expected: BOTH EDH passes green — the with-workspace suite (F2–F7 + the new F8 out-of-workspace suite) and the no-workspace suite (updated for real folder-less authoring). If a test fails, debug per `superpowers:systematic-debugging` (do not weaken assertions to pass).

- [ ] **Step 2: Commit any fixes**

```bash
git add -A
git commit -m "fix(f8): make host E2E green"
```
(Skip if no fixes were needed.)

---

## Task 12: Docs — manual smoke + README hybrid-model note

**Files:**
- Create: `docs/MANUAL-SMOKE-F8.md`
- Modify: `README.md`

- [ ] **Step 1: Write `docs/MANUAL-SMOKE-F8.md`** (mirror the F6/F7 smoke docs' structure)

```markdown
# Manual smoke — F8 out-of-workspace authoring

Confirms "Ask Claude to Edit Selection" (+ threads/attribution) work on a file
**outside** the workspace folder and on an **untitled** buffer, while in-workspace
authoring is unchanged. One live turn hits the SDK (the only LLM step).

## Prereqs
- Build: `npm run build`.
- Launch the Extension Development Host (F5 in VS Code) with this repo's `sandbox/`
  opened as the workspace folder.

## A. Out-of-folder file (PUC-1)
1. Open a markdown file from a DIFFERENT directory (outside `sandbox/`) — e.g. a
   sibling repo, or `File > Open` a scratch file under `/tmp`.
2. Select a sentence → Command Palette → **Cowriting: Ask Claude to Edit Selection**
   → type an instruction → wait for the proposal (amber range + ✓/✗).
3. Accept (✓). Expect: the text is replaced and shows the Claude attribution tint.
4. Add a coauthoring thread on a selection (**Add Coauthoring Thread on Selection**).
5. Close and reopen the file (or revert). Expect: the thread + attribution are
   restored. There is **no** `.threads/` folder beside the file — its state lives
   in VS Code global storage (`<globalStorage>/sidecars/<hash>.json`).

## B. Untitled buffer (PUC-2)
1. `File > New File` (don't save) → type a few sentences.
2. Select → **Ask Claude to Edit Selection** → instruct → accept. Expect: it works
   exactly like A, in-session.
3. Reload the window (Developer: Reload Window). Expect: the untitled buffer's
   coauthoring state is **gone** (in-memory only — documented limitation, §6.7).

## C. In-workspace unchanged (PUC-3)
1. Open a file UNDER `sandbox/`. Repeat the propose→accept→thread loop.
2. Expect: a committable `sandbox/.threads/<path>.json` sidecar is written, exactly
   as before F8 (byte-for-byte, INV-2).

## D. Read-only view declines (PUC-5)
1. Open a Git diff / Output view, select text, run **Ask Claude to Edit Selection**.
2. Expect: a warning that this kind of document can't be edited (not "select some
   text").
```

- [ ] **Step 2: Add a README note**

Find the section of `README.md` that lists the coauthoring features (F2–F7) and add an F8 entry. Append this paragraph in the appropriate features area (match the surrounding heading style):

```markdown
### F8 — Out-of-workspace authoring

"Ask Claude to Edit Selection" (and threads / attribution / propose-accept) work on
**any** document the editor shows — saved in the workspace folder, saved outside it,
or untitled — matching the universal F6 diff / F7 preview. Persistence is **hybrid**:
an in-workspace file keeps its committable `.threads/<repo-rel>.json` sidecar
(byte-for-byte unchanged, INV-2); an out-of-workspace file or untitled buffer stores
its coauthoring artifact in VS Code **global storage** keyed by `sha256(uri)` (untitled
is in-memory only). A global-storage artifact is **not a committed file**, so it is
**never cross-rung-shareable** (INV-25) and renaming the file orphans its artifact —
both stated as design contract (spec `specs/coauthoring-out-of-workspace.md`).
```

- [ ] **Step 3: Verify build still clean + commit**

Run: `npm run typecheck && npm test`
Expected: clean + green.

```bash
git add docs/MANUAL-SMOKE-F8.md README.md
git commit -m "docs(f8): manual smoke runbook + README hybrid-model/non-shareability note"
```

---

## Self-Review checklist (run after execution, before PR)

- **Spec coverage:** §6.2 (SidecarStore+router+isAuthorable) → Tasks 1/4/5; §6.3 (GlobalSidecarStore, document key table) → Tasks 2/3/5; §6.4 (interfaces, selectionRejection, controllers, activation) → Tasks 4/6/7/8/9; §6.8 (unit + host E2E) → Tasks 2/3/4/5/10/11; §6.7 untitled in-memory + non-migration → Tasks 2/3 + docs; INV-24 (hybrid routing) → Tasks 5/7/8 + E2E Task 10; INV-25 (single-rung) → E2E Task 10 (no `.threads/`, no merge); §9 docs → Task 12.
- **`mergeArtifacts` / model.ts:** untouched (verify `git diff --stat` shows no change to `src/model.ts`, `src/mergeArtifacts.ts`, `src/store.ts`).
- **Acceptance (spec §7.3):** out-of-folder + untitled authoring succeed; in-workspace byte-for-byte (Task 10 regression); global artifacts by URI hash (Tasks 2/10); re-anchor + reload restore (Task 10); unit + host E2E green (Task 11).
```