# Backend 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:** Costruire il backend ThothII: un orchestratore/traduttore Node+Fastify+TS che avvia Pi in RPC (un processo per sessione), fa da ponte JSONL↔(SSE/REST) verso il frontend, delega a `tht` l'esecuzione del SQL finale, e applica auth pluggabile.

**Architecture:** Backend senza stato persistente proprio (verità su disco harness). Un `RpcClient` (framing LF-only) per ogni processo Pi gestito dal `PiProcessManager` (uno per sessione attiva). Il `SessionBridge` traduce `extension_ui_request`↔`ui_request` correlando per `id` e mantiene il widget pendente per il re-emit su riconnessione SSE. Le interazioni con il modello (prompt/steer/set_model/set_thinking/get_available_models) usano i comandi RPC nativi di Pi. Il SQL finale è delegato a `tht sql preview/export` (nessun client DB nel backend). Tutto testabile in CI contro il **fake-pi-rpc** consegnato dal Piano Harness.

**Tech Stack:** Node ≥ 20, TypeScript (ESM), Fastify 5, vitest (test), tsx (dev run). Pi = `@earendil-works/pi-coding-agent` (`pi --mode rpc`). CLI `tht` (Python, già installato nel venv harness).

## Global Constraints

- **Prerequisito:** il Piano Harness (`2026-06-27-harness-rpc-readiness.md`) deve essere completato — il backend dipende da: gate RPC-ready, `THT_SESSION` id injection, `tht sql preview --json/--offset`, `tht session list/show --json`, campi manifest, `fake-pi-rpc`.
- **Framing RPC: LF-only JSONL** — `JSON.stringify(v)+"\n"`; lettura split su `\n`, strip `\r` finale. MAI `readline`. Riferimento: `@earendil-works/pi-coding-agent/dist/modes/rpc/jsonl.js`.
- **WIRE CONTRACT (corretto post-spike, Piano Harness Task 1):** il gate usa l'API UI nativa di Pi. Sul wire arriva `{type:"extension_ui_request", id, method:"input", title:"<widget-descriptor JSON>"}`; il backend **decodifica `title` → descriptor**, lo espone al FE come `ui_request`, e risponde `{type:"extension_ui_response", id, value:"<ui_response JSON>"}` (o `{id, cancelled:true}`). `ctx.sendRaw` non esiste; non esistono eventi `{ui_request:…}` nidificati. Il contratto verso il FE (`ui_request`/`ui_response`, architettura §4) resta invariato — la traduzione native↔FE è responsabilità del `SessionBridge`.
- **Deployment MVP:** localhost, mono-operatore (D12-B). Auth default `none` (utente `dev@local`).
- **Il backend NON tocca il DB**: ogni esecuzione SQL passa da `tht` (BE-2). Nessun driver `pg`/REST nel backend.
- **Posizione harness:** path configurabile (`THT_HARNESS_DIR`, default `../harness` rispetto al backend); `tht` invocato dal venv harness; spawn di Pi con `cwd = THT_HARNESS_DIR`.
- **Nessun segreto nel codice**: credenziali via `.env`/ambiente, mai committate.
- **Test in CI senza Pi/LLM reali**: si usa `fake-pi-rpc` (Piano Harness, `harness/tests/fake_pi/fake_pi_rpc.mjs`). L2 con Pi reale resta separato e informativo.

---

### Task 1: Scaffold del progetto backend

**Files:**
- Create: `backend/package.json`, `backend/tsconfig.json`, `backend/vitest.config.ts`
- Create: `backend/src/config.ts`, `backend/src/server.ts`, `backend/src/app.ts`
- Test: `backend/test/health.test.ts`

**Interfaces:**
- Produces: `buildApp(config: AppConfig): FastifyInstance` (registra le route, non ascolta); `loadConfig(env): AppConfig` con `{ port, harnessDir, thtBin, piBin, authMode, defaults: {provider?, model?, thinking?}, maxPiProcesses }`.

- [ ] **Step 1: package.json + tsconfig + vitest config**

```json
// backend/package.json
{
  "name": "thothii-backend",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "build": "tsc -p tsconfig.json",
    "test": "vitest run",
    "start": "node dist/server.js"
  },
  "dependencies": { "fastify": "^5.0.0" },
  "devDependencies": { "typescript": "^5.6.0", "tsx": "^4.19.0", "vitest": "^2.1.0", "@types/node": "^22.0.0" }
}
```
```json
// backend/tsconfig.json
{ "compilerOptions": { "target": "ES2022", "module": "ES2022", "moduleResolution": "Bundler",
  "strict": true, "outDir": "dist", "rootDir": "src", "esModuleInterop": true, "skipLibCheck": true },
  "include": ["src"] }
```
```typescript
// backend/vitest.config.ts
import { defineConfig } from "vitest/config";
export default defineConfig({ test: { environment: "node", include: ["test/**/*.test.ts"] } });
```

- [ ] **Step 2: Scrivere il test health**

```typescript
// backend/test/health.test.ts
import { test, expect } from "vitest";
import { buildApp } from "../src/app.js";
import { loadConfig } from "../src/config.js";

test("GET /health ritorna ok", async () => {
  const app = buildApp(loadConfig({ THT_HARNESS_DIR: "/tmp/h" }));
  const res = await app.inject({ method: "GET", url: "/health" });
  expect(res.statusCode).toBe(200);
  expect(res.json()).toEqual({ status: "ok" });
});
```

- [ ] **Step 3: Eseguire (deve fallire)**

Run: `cd backend && npm install && npm test`
Expected: FAIL — `Cannot find module '../src/app.js'`.

- [ ] **Step 4: Implementare config + app + server**

```typescript
// backend/src/config.ts
export interface AppConfig {
  port: number; harnessDir: string; thtBin: string; piBin: string;
  authMode: "none" | "mock" | "oidc";
  defaults: { provider?: string; model?: string; thinking?: string };
  maxPiProcesses: number;
}
export function loadConfig(env: Record<string, string | undefined>): AppConfig {
  return {
    port: Number(env.PORT ?? 8787),
    harnessDir: env.THT_HARNESS_DIR ?? "../harness",
    thtBin: env.THT_BIN ?? "tht",
    piBin: env.PI_BIN ?? "pi",
    authMode: (env.AUTH_MODE as AppConfig["authMode"]) ?? "none",
    defaults: { provider: env.PI_PROVIDER, model: env.PI_MODEL, thinking: env.PI_THINKING },
    maxPiProcesses: Number(env.MAX_PI_PROCESSES ?? 4),
  };
}
```
```typescript
// backend/src/app.ts
import Fastify, { type FastifyInstance } from "fastify";
import type { AppConfig } from "./config.js";
export function buildApp(_config: AppConfig): FastifyInstance {
  const app = Fastify({ logger: false });
  app.get("/health", async () => ({ status: "ok" }));
  return app;
}
```
```typescript
// backend/src/server.ts
import { buildApp } from "./app.js";
import { loadConfig } from "./config.js";
const config = loadConfig(process.env);
const app = buildApp(config);
app.listen({ port: config.port, host: "127.0.0.1" })
  .then((addr) => console.log(`backend listening on ${addr}`));
```

- [ ] **Step 5: Eseguire (deve passare) + commit**

Run: `cd backend && npm test`
Expected: PASS.
```bash
git add backend/package.json backend/tsconfig.json backend/vitest.config.ts backend/src backend/test
git commit -m "feat(backend): scaffold Fastify+TS + /health"
```

---

### Task 2: LineSplitter — lettura JSONL LF-only

**Files:**
- Create: `backend/src/rpc/line-splitter.ts`
- Test: `backend/test/line-splitter.test.ts`

**Interfaces:**
- Produces: `attachJsonlReader(stream: Readable, onLine: (line: string) => void): () => void` — split su `\n`, strip `\r` finale, gestione chunk parziali; ritorna funzione di detach.

- [ ] **Step 1: Scrivere il test**

```typescript
import { test, expect } from "vitest";
import { Readable } from "node:stream";
import { attachJsonlReader } from "../src/rpc/line-splitter.js";

test("riassembla righe spezzate tra chunk, split solo su \\n", async () => {
  const lines: string[] = [];
  const s = new Readable({ read() {} });
  attachJsonlReader(s, (l) => lines.push(l));
  s.push('{"a":1}\n{"b":'); s.push('2}\r\n{"u":"
 in stringa"}\n'); s.push(null);
  await new Promise((r) => s.on("end", r));
  expect(lines).toEqual(['{"a":1}', '{"b":2}', '{"u":"
 in stringa"}']);
});
```

- [ ] **Step 2: Eseguire (deve fallire)**

Run: `cd backend && npm test -- line-splitter`
Expected: FAIL — modulo assente.

- [ ] **Step 3: Implementare (port di jsonl.js)**

```typescript
// backend/src/rpc/line-splitter.ts
import { StringDecoder } from "node:string_decoder";
import type { Readable } from "node:stream";
export function attachJsonlReader(stream: Readable, onLine: (line: string) => void): () => void {
  const decoder = new StringDecoder("utf8");
  let buffer = "";
  const emit = (line: string) => onLine(line.endsWith("\r") ? line.slice(0, -1) : line);
  const onData = (chunk: Buffer | string) => {
    buffer += typeof chunk === "string" ? chunk : decoder.write(chunk);
    for (let nl; (nl = buffer.indexOf("\n")) !== -1; ) {
      emit(buffer.slice(0, nl)); buffer = buffer.slice(nl + 1);
    }
  };
  const onEnd = () => { buffer += decoder.end(); if (buffer) { emit(buffer); buffer = ""; } };
  stream.on("data", onData); stream.on("end", onEnd);
  return () => { stream.off("data", onData); stream.off("end", onEnd); };
}
```

- [ ] **Step 4: Eseguire (deve passare) + commit**

Run: `cd backend && npm test -- line-splitter`
Expected: PASS.
```bash
git add backend/src/rpc/line-splitter.ts backend/test/line-splitter.test.ts
git commit -m "feat(backend): LF-only JSONL line splitter"
```

---

### Task 3: RpcClient — spawn, invio comandi, correlazione risposte

**Files:**
- Create: `backend/src/rpc/rpc-client.ts`
- Test: `backend/test/rpc-client.test.ts`

**Interfaces:**
- Consumes: `attachJsonlReader` (Task 2); `harness/tests/fake_pi/fake_pi_rpc.mjs` (Piano Harness).
- Produces: `class RpcClient`:
  - `constructor(child: ChildProcessWithoutNullStreams)`
  - `send(cmd: object): void` — scrive `JSON.stringify(cmd)+"\n"` su stdin
  - `request(cmd: object & {type:string}): Promise<any>` — invia con `id` generato, risolve sulla `{type:"response"}` correlata
  - `on(event: "event", cb: (evt: any) => void)` — emette ogni messaggio NON-response (eventi: `extension_ui_request`, `text_delta`, `agent_end`, …)
  - `nextId(): string`

- [ ] **Step 1: Scrivere il test (contro fake-pi-rpc)**

```typescript
import { test, expect } from "vitest";
import { spawn } from "node:child_process";
import path from "node:path";
import { RpcClient } from "../src/rpc/rpc-client.js";

const FAKE = path.resolve("../harness/tests/fake_pi/fake_pi_rpc.mjs");
const SCRIPT = path.resolve("../harness/tests/fake_pi/scripts/f1_disambiguation.json");

test("request(get_available_models) correla la response", async () => {
  const child = spawn("node", [FAKE, SCRIPT]);
  const rpc = new RpcClient(child as any);
  const res = await rpc.request({ type: "get_available_models" });
  expect(res.data.models[0].provider).toBe("zai");
  child.stdin.end();
});

test("prompt emette un evento extension_ui_request", async () => {
  const child = spawn("node", [FAKE, SCRIPT]);
  const rpc = new RpcClient(child as any);
  const got = new Promise<any>((resolve) => rpc.on("event", (e) => e.type === "extension_ui_request" && resolve(e)));
  rpc.send({ type: "prompt", message: "/nuova-domanda \"x\"" });
  const evt = await got;
  expect(evt.method).toBe("input");                       // shape nativa di Pi
  expect(JSON.parse(evt.title).widget).toBe("select");    // descriptor nel title
  child.stdin.end();
});
```

- [ ] **Step 2: Eseguire (deve fallire)**

Run: `cd backend && npm test -- rpc-client`
Expected: FAIL — modulo assente.

- [ ] **Step 3: Implementare RpcClient**

```typescript
// backend/src/rpc/rpc-client.ts
import type { ChildProcessWithoutNullStreams } from "node:child_process";
import { attachJsonlReader } from "./line-splitter.js";
type Listener = (evt: any) => void;
export class RpcClient {
  private seq = 0;
  private pending = new Map<string, (resp: any) => void>();
  private listeners = new Set<Listener>();
  constructor(private child: ChildProcessWithoutNullStreams) {
    attachJsonlReader(child.stdout, (line) => {
      if (!line) return;
      let msg: any; try { msg = JSON.parse(line); } catch { return; }
      if (msg.type === "response" && msg.id && this.pending.has(msg.id)) {
        this.pending.get(msg.id)!(msg); this.pending.delete(msg.id); return;
      }
      for (const l of this.listeners) l(msg);
    });
  }
  nextId(): string { return `c${++this.seq}`; }
  send(cmd: object): void { this.child.stdin.write(JSON.stringify(cmd) + "\n"); }
  request(cmd: object & { type: string }): Promise<any> {
    const id = this.nextId();
    return new Promise((resolve) => { this.pending.set(id, resolve); this.send({ ...cmd, id }); });
  }
  on(_event: "event", cb: Listener): void { this.listeners.add(cb); }
}
```

- [ ] **Step 4: Eseguire (deve passare) + commit**

Run: `cd backend && npm test -- rpc-client`
Expected: PASS (2 test).
```bash
git add backend/src/rpc/rpc-client.ts backend/test/rpc-client.test.ts
git commit -m "feat(backend): RpcClient (spawn/send/request/event) over JSONL"
```

---

### Task 4: SessionBridge — traduzione widget-descriptor ↔ RPC + widget pendente

**Files:**
- Create: `backend/src/bridge/session-bridge.ts`
- Test: `backend/test/session-bridge.test.ts`

**Interfaces:**
- Consumes: `RpcClient` (Task 3).
- Produces: `class SessionBridge`:
  - `constructor(rpc: RpcClient)`
  - `onClientEvent(cb: (e: ClientEvent) => void)` — emette verso il FE: `{type:"ui_request"|"info"|"text_delta"|"system_event", ...}`
  - `respond(uiResponse: object & {id:string}): void` — invia a Pi `{type:"extension_ui_response", id, value: JSON.stringify(uiResponse)}` (shape NATIVA: il payload va in `value`)
  - `steer(text: string): void` — invia `{type:"steer", message: text}`
  - `pendingWidget(): object | null` — l'ultimo descriptor non ancora risposto (per re-emit)
- **Decodifica della shape nativa (WIRE CONTRACT):** un evento `{type:"extension_ui_request", id, method:"input", title}` → il bridge fa `JSON.parse(title)` → descriptor, lo espone come `ui_request`; `method:"notify"` → `info`; altri `method` (setStatus/setWidget) ignorati in MVP.
- Tipi: `ClientEvent = {type:"ui_request", ui_request:object} | {type:"text_delta", text:string} | {type:"info",...} | {type:"system_event",...}`.

- [ ] **Step 1: Scrivere il test**

```typescript
import { test, expect, vi } from "vitest";
import { SessionBridge } from "../src/bridge/session-bridge.js";

function fakeRpc() {
  const sent: any[] = []; let evcb: any;
  return { rpc: { send: (c:any)=>sent.push(c), on: (_:any,cb:any)=>{evcb=cb}, request: vi.fn() } as any,
           sent, fire: (m:any)=>evcb(m) };
}

test("extension_ui_request nativo (method:input, title=json) diventa ui_request ed è il pendente", () => {
  const { rpc, fire } = fakeRpc();
  const b = new SessionBridge(rpc);
  const seen: any[] = []; b.onClientEvent((e)=>seen.push(e));
  const descriptor = { id:"u1", widget:"select" };
  fire({ type:"extension_ui_request", id:"u1", method:"input", title: JSON.stringify(descriptor) });
  expect(seen[0]).toEqual({ type:"ui_request", ui_request: descriptor });
  expect(b.pendingWidget()).toEqual(descriptor);
});

test("respond invia extension_ui_response con payload in value e azzera il pendente", () => {
  const { rpc, sent, fire } = fakeRpc();
  const b = new SessionBridge(rpc);
  fire({ type:"extension_ui_request", id:"u1", method:"input", title: JSON.stringify({ id:"u1", widget:"select" }) });
  b.respond({ id:"u1", choices:["a"] });
  expect(sent.at(-1)).toEqual({ type:"extension_ui_response", id:"u1", value: JSON.stringify({ id:"u1", choices:["a"] }) });
  expect(b.pendingWidget()).toBeNull();
});

test("steer invia un comando steer", () => {
  const { rpc, sent } = fakeRpc();
  new SessionBridge(rpc).steer("considera solo il 2024");
  expect(sent.at(-1)).toEqual({ type:"steer", message:"considera solo il 2024" });
});
```

- [ ] **Step 2: Eseguire (deve fallire)**

Run: `cd backend && npm test -- session-bridge`
Expected: FAIL — modulo assente.

- [ ] **Step 3: Implementare SessionBridge**

```typescript
// backend/src/bridge/session-bridge.ts
import type { RpcClient } from "../rpc/rpc-client.js";
export type ClientEvent =
  | { type: "ui_request"; ui_request: any }
  | { type: "text_delta"; text: string }
  | { type: "info"; [k: string]: any }
  | { type: "system_event"; [k: string]: any };

export class SessionBridge {
  private pending: any = null;
  private cbs = new Set<(e: ClientEvent) => void>();
  constructor(private rpc: RpcClient) {
    rpc.on("event", (m) => {
      if (m.type === "extension_ui_request" && m.method === "input") {
        let descriptor: any; try { descriptor = JSON.parse(m.title); } catch { return; }
        this.pending = descriptor;
        this.fan({ type: "ui_request", ui_request: descriptor });
      } else if (m.type === "extension_ui_request" && m.method === "notify") {
        this.fan({ type: "info", level: m.notifyType ?? "info", text: m.message ?? "" });
      } else if (m.type === "text_delta") {
        this.fan({ type: "text_delta", text: m.text ?? "" });
      } else if (m.type === "system_event") {
        this.fan(m as ClientEvent);
      }
      // altri method nativi (setStatus/setWidget) e altri eventi Pi (agent_end, tool_call) non inoltrati in MVP
    });
  }
  private fan(e: ClientEvent) { for (const cb of this.cbs) cb(e); }
  onClientEvent(cb: (e: ClientEvent) => void) { this.cbs.add(cb); }
  respond(uiResponse: object & { id: string }) {
    this.rpc.send({ type: "extension_ui_response", id: uiResponse.id, value: JSON.stringify(uiResponse) });
    if (this.pending && uiResponse.id === this.pending.id) this.pending = null;
  }
  steer(text: string) { this.rpc.send({ type: "steer", message: text }); }
  pendingWidget() { return this.pending; }
}
```

- [ ] **Step 4: Eseguire (deve passare) + commit**

Run: `cd backend && npm test -- session-bridge`
Expected: PASS (3 test).
```bash
git add backend/src/bridge/session-bridge.ts backend/test/session-bridge.test.ts
git commit -m "feat(backend): SessionBridge widget-descriptor <-> RPC + pending widget"
```

---

### Task 5: ThtRunner — wrapper dei comandi `tht … --json`

**Files:**
- Create: `backend/src/tht/tht-runner.ts`
- Test: `backend/test/tht-runner.test.ts`

**Interfaces:**
- Produces: `class ThtRunner` (config: `{thtBin, harnessDir, configPath}`):
  - `sessionNew(opts): Promise<{id:string}>` → `tht session new <q> [--provider…] --json`
  - `sessionList(): Promise<SessionRow[]>` → `tht session list --json`
  - `sessionShow(id): Promise<any>` → `tht session show <id> --json`
  - `sqlPreview(id, {limit, offset}): Promise<{columns,rows,execution_ms,truncated}>`
  - `sqlExport(id): Promise<{path:string}>`
  - `run(args: string[]): Promise<{code:number, stdout:string, stderr:string}>` (primitiva, iniettabile per test)

- [ ] **Step 1: Scrivere il test (run iniettabile)**

```typescript
import { test, expect } from "vitest";
import { ThtRunner } from "../src/tht/tht-runner.js";

test("sessionNew parsa l'id dal JSON", async () => {
  const r = new ThtRunner({ thtBin: "tht", harnessDir: "/h", configPath: "config/tht.yaml" });
  r.run = async () => ({ code: 0, stdout: '{"id":"2026-06-27-100000-x"}', stderr: "" });
  expect(await r.sessionNew({ question: "q" })).toEqual({ id: "2026-06-27-100000-x" });
});

test("run con exit != 0 propaga errore con stderr", async () => {
  const r = new ThtRunner({ thtBin: "tht", harnessDir: "/h", configPath: "config/tht.yaml" });
  r.run = async () => ({ code: 1, stdout: "", stderr: "ERRORE: boom" });
  await expect(r.sessionList()).rejects.toThrow(/boom/);
});
```

- [ ] **Step 2: Eseguire (deve fallire)**

Run: `cd backend && npm test -- tht-runner`
Expected: FAIL — modulo assente.

- [ ] **Step 3: Implementare ThtRunner**

```typescript
// backend/src/tht/tht-runner.ts
import { spawn } from "node:child_process";
export interface ThtConfig { thtBin: string; harnessDir: string; configPath: string; }
export interface SessionRow { id: string; status: string; question: string; summary: string | null;
  created_at: string; updated_at: string | null; author: string | null; }
export class ThtRunner {
  constructor(private cfg: ThtConfig) {}
  run(args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
    return new Promise((resolve) => {
      const ch = spawn(this.cfg.thtBin, ["-c", this.cfg.configPath, ...args], { cwd: this.cfg.harnessDir });
      let stdout = "", stderr = "";
      ch.stdout.on("data", (d) => (stdout += d)); ch.stderr.on("data", (d) => (stderr += d));
      ch.on("close", (code) => resolve({ code: code ?? 0, stdout, stderr }));
    });
  }
  private async json<T>(args: string[]): Promise<T> {
    const { code, stdout, stderr } = await this.run(args);
    if (code !== 0) throw new Error(`tht ${args.join(" ")} exit ${code}: ${stderr.trim()}`);
    return JSON.parse(stdout) as T;
  }
  async sessionNew(o: { question: string; provider?: string; model?: string; thinking?: string; name?: string }) {
    const a = ["session", "new", o.question];
    for (const [f, v] of [["--provider", o.provider], ["--model", o.model], ["--thinking", o.thinking], ["--name", o.name]] as const)
      if (v) a.push(f, v);
    a.push("--json");
    return this.json<{ id: string }>(a);
  }
  sessionList() { return this.json<SessionRow[]>(["session", "list", "--json"]); }
  sessionShow(id: string) { return this.json<any>(["session", "show", id, "--json"]); }
  sqlPreview(id: string, p: { limit?: number; offset?: number }) {
    const a = ["sql", "preview", `sessions/${id}/sql_final.sql`, "--session", id, "--json"];
    if (p.limit != null) a.push("--limit", String(p.limit));
    if (p.offset) a.push("--offset", String(p.offset));
    return this.json<{ columns: string[]; rows: unknown[][]; execution_ms: number; truncated: boolean }>(a);
  }
  async sqlExport(id: string) {
    const { code, stdout, stderr } = await this.run(["sql", "export", "--session", id]);
    if (code !== 0) throw new Error(`tht sql export exit ${code}: ${stderr.trim()}`);
    return { path: stdout.trim() };
  }
}
```

- [ ] **Step 4: Eseguire (deve passare) + commit**

Run: `cd backend && npm test -- tht-runner`
Expected: PASS (2 test).
```bash
git add backend/src/tht/tht-runner.ts backend/test/tht-runner.test.ts
git commit -m "feat(backend): ThtRunner wrapper for tht --json (sessions, sql preview/export)"
```

---

### Task 6: PiProcessManager — un Pi per sessione, spawn/teardown/resume + settings

**Files:**
- Create: `backend/src/pi/pi-process-manager.ts`
- Test: `backend/test/pi-process-manager.test.ts`

**Interfaces:**
- Consumes: `RpcClient` (Task 3), `SessionBridge` (Task 4), `AppConfig` (Task 1).
- Produces: `class PiProcessManager`:
  - `spawnFor(sessionId: string, opts: {provider?, model?, thinking?, name?, author?}): Promise<SessionRuntime>` — spawn `pi --mode rpc` con `cwd=harnessDir`, env `{...process.env, THT_SESSION: sessionId, THT_AUTHOR: author, PATH: <venv/bin>:PATH}`, `--approve`; dopo lo spawn applica `set_model`/`set_thinking_level` via RPC; manda `prompt "/nuova-domanda …"` per avviare il workflow.
  - `get(sessionId): SessionRuntime | undefined`
  - `teardown(sessionId): void`
  - `count(): number` — rispetta `maxPiProcesses` (errore esplicito oltre il cap)
- `SessionRuntime = { rpc: RpcClient; bridge: SessionBridge; child: ChildProcess }`
- Iniettabile: `spawnFn` (default `spawn`) per test senza Pi reale.

- [ ] **Step 1: Scrivere il test (spawnFn iniettato = fake-pi-rpc)**

```typescript
import { test, expect } from "vitest";
import { spawn } from "node:child_process";
import path from "node:path";
import { PiProcessManager } from "../src/pi/pi-process-manager.js";
import { loadConfig } from "../src/config.js";

const FAKE = path.resolve("../harness/tests/fake_pi/fake_pi_rpc.mjs");
const SCRIPT = path.resolve("../harness/tests/fake_pi/scripts/f1_disambiguation.json");

test("spawnFor avvia un runtime e il bridge emette il widget F1", async () => {
  const cfg = loadConfig({ THT_HARNESS_DIR: "../harness" });
  const mgr = new PiProcessManager(cfg, { spawnFn: () => spawn("node", [FAKE, SCRIPT]) as any });
  const rt = await mgr.spawnFor("2026-06-27-100000-x", {});
  const widget = await new Promise<any>((res) => rt.bridge.onClientEvent((e) => e.type === "ui_request" && res(e)));
  expect(widget.ui_request.widget).toBe("select");
  mgr.teardown("2026-06-27-100000-x");
  expect(mgr.count()).toBe(0);
});

test("oltre maxPiProcesses solleva errore", async () => {
  const cfg = { ...loadConfig({}), maxPiProcesses: 1 };
  const mgr = new PiProcessManager(cfg, { spawnFn: () => spawn("node", [FAKE, SCRIPT]) as any });
  await mgr.spawnFor("a", {});
  await expect(mgr.spawnFor("b", {})).rejects.toThrow(/max/i);
  mgr.teardown("a");
});
```

- [ ] **Step 2: Eseguire (deve fallire)**

Run: `cd backend && npm test -- pi-process-manager`
Expected: FAIL — modulo assente.

- [ ] **Step 3: Implementare PiProcessManager**

```typescript
// backend/src/pi/pi-process-manager.ts
import { spawn as nodeSpawn, type ChildProcessWithoutNullStreams } from "node:child_process";
import type { AppConfig } from "../config.js";
import { RpcClient } from "../rpc/rpc-client.js";
import { SessionBridge } from "../bridge/session-bridge.js";

export interface SessionRuntime { rpc: RpcClient; bridge: SessionBridge; child: ChildProcessWithoutNullStreams; }
type SpawnFn = (cfg: AppConfig, sessionId: string, env: NodeJS.ProcessEnv) => ChildProcessWithoutNullStreams;

export class PiProcessManager {
  private runtimes = new Map<string, SessionRuntime>();
  private spawnFn: SpawnFn;
  constructor(private cfg: AppConfig, opts?: { spawnFn?: (...a: any[]) => ChildProcessWithoutNullStreams }) {
    this.spawnFn = opts?.spawnFn
      ? () => opts.spawnFn!()
      : (cfg, sessionId, env) => nodeSpawn(cfg.piBin, ["--mode", "rpc", "--approve"], { cwd: cfg.harnessDir, env });
  }
  count() { return this.runtimes.size; }
  get(id: string) { return this.runtimes.get(id); }
  async spawnFor(sessionId: string, o: { provider?: string; model?: string; thinking?: string; author?: string }) {
    if (this.runtimes.size >= this.cfg.maxPiProcesses) throw new Error("max Pi processes reached");
    const env = { ...process.env, THT_SESSION: sessionId, THT_AUTHOR: o.author ?? "dev@local" };
    const child = this.spawnFn(this.cfg, sessionId, env);
    const rpc = new RpcClient(child); const bridge = new SessionBridge(rpc);
    const rt: SessionRuntime = { rpc, bridge, child };
    this.runtimes.set(sessionId, rt);
    child.on("exit", () => this.runtimes.delete(sessionId));
    const provider = o.provider ?? this.cfg.defaults.provider;
    const model = o.model ?? this.cfg.defaults.model;
    const thinking = o.thinking ?? this.cfg.defaults.thinking;
    if (provider && model) await rpc.request({ type: "set_model", provider, modelId: model });
    if (thinking) await rpc.request({ type: "set_thinking_level", level: thinking });
    rpc.send({ type: "prompt", message: `/nuova-domanda "kickoff"` });
    return rt;
  }
  teardown(id: string) { const rt = this.runtimes.get(id); if (rt) { rt.child.kill(); this.runtimes.delete(id); } }
}
```

> Nota PATH (rischio L2 #1): in produzione `env.PATH` deve includere `harness/.venv/bin` perché Pi spawni `tht`. Aggiungere alla composizione `env`: `PATH: \`${harnessVenvBin}:${process.env.PATH}\``. Coperto in Task 11 (wiring reale).

- [ ] **Step 4: Eseguire (deve passare) + commit**

Run: `cd backend && npm test -- pi-process-manager`
Expected: PASS (2 test).
```bash
git add backend/src/pi/pi-process-manager.ts backend/test/pi-process-manager.test.ts
git commit -m "feat(backend): PiProcessManager (one Pi per session, cap, set_model/thinking)"
```

---

### Task 7: SSE hub + re-emit del widget pendente

**Files:**
- Create: `backend/src/sse/sse-hub.ts`
- Test: `backend/test/sse-hub.test.ts`

**Interfaces:**
- Produces: `class SseHub`:
  - `subscribe(sessionId, send: (event: string, data: object) => void, pending?: object | null): () => void` — alla sottoscrizione, se `pending` è presente, invia subito `send("ui_request", {ui_request: pending})`; ritorna unsubscribe.
  - `publish(sessionId, event: string, data: object): void` — a tutti i subscriber della sessione.

- [ ] **Step 1: Scrivere il test**

```typescript
import { test, expect } from "vitest";
import { SseHub } from "../src/sse/sse-hub.js";

test("re-emette il widget pendente alla sottoscrizione", () => {
  const hub = new SseHub(); const sent: any[] = [];
  hub.subscribe("s1", (ev, data) => sent.push({ ev, data }), { id: "u1", widget: "select" });
  expect(sent[0]).toEqual({ ev: "ui_request", data: { ui_request: { id: "u1", widget: "select" } } });
});

test("publish raggiunge i subscriber e unsubscribe li stacca", () => {
  const hub = new SseHub(); const sent: any[] = [];
  const off = hub.subscribe("s1", (ev, data) => sent.push({ ev, data }));
  hub.publish("s1", "text_delta", { text: "x" });
  off(); hub.publish("s1", "text_delta", { text: "y" });
  expect(sent).toEqual([{ ev: "text_delta", data: { text: "x" } }]);
});
```

- [ ] **Step 2: Eseguire (deve fallire)**

Run: `cd backend && npm test -- sse-hub`
Expected: FAIL — modulo assente.

- [ ] **Step 3: Implementare SseHub**

```typescript
// backend/src/sse/sse-hub.ts
type Send = (event: string, data: object) => void;
export class SseHub {
  private subs = new Map<string, Set<Send>>();
  subscribe(sessionId: string, send: Send, pending?: object | null): () => void {
    if (!this.subs.has(sessionId)) this.subs.set(sessionId, new Set());
    this.subs.get(sessionId)!.add(send);
    if (pending) send("ui_request", { ui_request: pending });
    return () => this.subs.get(sessionId)?.delete(send);
  }
  publish(sessionId: string, event: string, data: object): void {
    for (const s of this.subs.get(sessionId) ?? []) s(event, data);
  }
}
```

- [ ] **Step 4: Eseguire (deve passare) + commit**

Run: `cd backend && npm test -- sse-hub`
Expected: PASS (2 test).
```bash
git add backend/src/sse/sse-hub.ts backend/test/sse-hub.test.ts
git commit -m "feat(backend): SSE hub with pending-widget re-emit on (re)subscribe"
```

---

### Task 8: Auth middleware pluggabile (none/mock/oidc)

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

**Interfaces:**
- Produces: `authPreHandler(mode)`→ Fastify preHandler che imposta `req.user = {id}`: `none`→`dev@local`; `mock`→header `x-mock-user`; `oidc`→verifica bearer (stub MVP: `501` se non configurato). `getUser(req): {id:string}`.

- [ ] **Step 1: Scrivere il test**

```typescript
import { test, expect } from "vitest";
import Fastify from "fastify";
import { authPreHandler, getUser } from "../src/auth/auth.js";

test("mode none assegna dev@local", async () => {
  const app = Fastify(); app.addHook("preHandler", authPreHandler("none"));
  app.get("/me", async (req) => getUser(req));
  expect((await app.inject({ method: "GET", url: "/me" })).json()).toEqual({ id: "dev@local" });
});

test("mode mock legge l'header", async () => {
  const app = Fastify(); app.addHook("preHandler", authPreHandler("mock"));
  app.get("/me", async (req) => getUser(req));
  const res = await app.inject({ method: "GET", url: "/me", headers: { "x-mock-user": "alice" } });
  expect(res.json()).toEqual({ id: "alice" });
});
```

- [ ] **Step 2: Eseguire (deve fallire)**

Run: `cd backend && npm test -- auth`
Expected: FAIL — modulo assente.

- [ ] **Step 3: Implementare auth**

```typescript
// backend/src/auth/auth.ts
import type { FastifyRequest, FastifyReply } from "fastify";
export function authPreHandler(mode: "none" | "mock" | "oidc") {
  return async (req: FastifyRequest, reply: FastifyReply) => {
    if (mode === "none") (req as any).user = { id: "dev@local" };
    else if (mode === "mock") (req as any).user = { id: (req.headers["x-mock-user"] as string) ?? "mock" };
    else { reply.code(501); throw new Error("OIDC non configurato (MVP: usa none/mock)"); }
  };
}
export function getUser(req: FastifyRequest): { id: string } { return (req as any).user ?? { id: "dev@local" }; }
```

- [ ] **Step 4: Eseguire (deve passare) + commit**

Run: `cd backend && npm test -- auth`
Expected: PASS (2 test).
```bash
git add backend/src/auth/auth.ts backend/test/auth.test.ts
git commit -m "feat(backend): pluggable auth (none/mock/oidc seam)"
```

---

### Task 9: Route sessioni + SSE + response/steer (wiring)

**Files:**
- Modify: `backend/src/app.ts` (registra le route, costruisce i singleton)
- Create: `backend/src/routes/sessions.ts`
- Test: `backend/test/routes-sessions.test.ts`

**Interfaces:**
- Consumes: `PiProcessManager` (6), `ThtRunner` (5), `SseHub` (7), `auth` (8).
- Produces (route, tutte sotto `authPreHandler`):
  - `POST /sessions {workspace, question, provider?, model?, thinking?, name?}` → `tht session new` (con author dall'auth) → `mgr.spawnFor(id)` → `{id}`
  - `GET /sessions` → `tht session list --json`
  - `GET /sessions/:id` → `tht session show --json`
  - `GET /sessions/:id/events` → SSE; sottoscrive `SseHub` con `bridge.pendingWidget()`; collega `bridge.onClientEvent` → `hub.publish`
  - `POST /sessions/:id/response {ui_response}` → `bridge.respond`
  - `POST /sessions/:id/steer {text}` → `bridge.steer`
  - `POST /sessions/:id/close` → `mgr.teardown`

- [ ] **Step 1: Scrivere il test (inietta ThtRunner + spawnFn fake)**

```typescript
import { test, expect } from "vitest";
import { spawn } from "node:child_process";
import path from "node:path";
import { buildApp } from "../src/app.js";
import { loadConfig } from "../src/config.js";

const FAKE = path.resolve("../harness/tests/fake_pi/fake_pi_rpc.mjs");
const SCRIPT = path.resolve("../harness/tests/fake_pi/scripts/f1_disambiguation.json");

test("POST /sessions crea e avvia, GET /sessions lista", async () => {
  const app = buildApp(loadConfig({ THT_HARNESS_DIR: "../harness" }), {
    thtRunner: { sessionNew: async () => ({ id: "s1" }), sessionList: async () => [{ id: "s1" }] } as any,
    spawnFn: () => spawn("node", [FAKE, SCRIPT]) as any,
  });
  const created = await app.inject({ method: "POST", url: "/sessions", payload: { workspace: "w", question: "q" } });
  expect(created.json()).toEqual({ id: "s1" });
  const list = await app.inject({ method: "GET", url: "/sessions" });
  expect(list.json()).toEqual([{ id: "s1" }]);
});

test("POST /sessions/:id/response inoltra al bridge (no error)", async () => {
  const app = buildApp(loadConfig({ THT_HARNESS_DIR: "../harness" }), {
    thtRunner: { sessionNew: async () => ({ id: "s1" }) } as any,
    spawnFn: () => spawn("node", [FAKE, SCRIPT]) as any,
  });
  await app.inject({ method: "POST", url: "/sessions", payload: { workspace: "w", question: "q" } });
  const res = await app.inject({ method: "POST", url: "/sessions/s1/response",
    payload: { ui_response: { id: "u1", choices: ["a"] } } });
  expect(res.statusCode).toBe(204);
});
```

- [ ] **Step 2: Eseguire (deve fallire)**

Run: `cd backend && npm test -- routes-sessions`
Expected: FAIL — `buildApp` non accetta deps / route assenti.

- [ ] **Step 3: Rendere buildApp iniettabile e registrare le route**

In `app.ts` accettare `deps?: { thtRunner?, spawnFn? }`, costruire `ThtRunner`/`PiProcessManager`/`SseHub`, applicare `authPreHandler(config.authMode)`, e registrare `sessionRoutes`.

```typescript
// backend/src/routes/sessions.ts (estratto load-bearing)
import type { FastifyInstance } from "fastify";
import type { PiProcessManager } from "../pi/pi-process-manager.js";
import type { ThtRunner } from "../tht/tht-runner.js";
import type { SseHub } from "../sse/sse-hub.js";
import { getUser } from "../auth/auth.js";

export function sessionRoutes(app: FastifyInstance, d: { mgr: PiProcessManager; tht: ThtRunner; hub: SseHub }) {
  app.post("/sessions", async (req, reply) => {
    const b = req.body as any;
    const { id } = await d.tht.sessionNew({ question: b.question, provider: b.provider, model: b.model, thinking: b.thinking, name: b.name });
    const rt = await d.mgr.spawnFor(id, { provider: b.provider, model: b.model, thinking: b.thinking, author: getUser(req).id });
    rt.bridge.onClientEvent((e) => d.hub.publish(id, e.type, e));
    return { id };
  });
  app.get("/sessions", async () => d.tht.sessionList());
  app.get("/sessions/:id", async (req) => d.tht.sessionShow((req.params as any).id));
  app.post("/sessions/:id/response", async (req, reply) => {
    const id = (req.params as any).id; const rt = d.mgr.get(id);
    if (!rt) return reply.code(404).send({ error: "sessione non attiva" });
    rt.bridge.respond((req.body as any).ui_response); return reply.code(204).send();
  });
  app.post("/sessions/:id/steer", async (req, reply) => {
    const rt = d.mgr.get((req.params as any).id);
    if (!rt) return reply.code(404).send({ error: "sessione non attiva" });
    rt.bridge.steer((req.body as any).text); return reply.code(204).send();
  });
  app.post("/sessions/:id/close", async (req) => { d.mgr.teardown((req.params as any).id); return { closed: true }; });
  app.get("/sessions/:id/events", (req, reply) => {
    const id = (req.params as any).id; const rt = d.mgr.get(id);
    reply.raw.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive" });
    const send = (event: string, data: object) => reply.raw.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
    const off = d.hub.subscribe(id, send, rt?.bridge.pendingWidget() ?? null);
    req.raw.on("close", off);
  });
}
```

- [ ] **Step 4: Eseguire (deve passare) + commit**

Run: `cd backend && npm test -- routes-sessions`
Expected: PASS (2 test).
```bash
git add backend/src/app.ts backend/src/routes/sessions.ts backend/test/routes-sessions.test.ts
git commit -m "feat(backend): session routes + SSE + response/steer wiring"
```

---

### Task 10: Route SQL (preview/export) + models + workspaces

**Files:**
- Create: `backend/src/routes/sql.ts`, `backend/src/routes/meta.ts`
- Modify: `backend/src/app.ts` (registra)
- Test: `backend/test/routes-sql-meta.test.ts`

**Interfaces:**
- Produces:
  - `POST /sessions/:id/sql/preview {limit?, offset?}` → `tht.sqlPreview` → `{columns, rows, execution_ms, truncated}`
  - `POST /sessions/:id/sql/export` → `tht.sqlExport` → `{path}`
  - `GET /models` → `rpc.request({type:"get_available_models"})` da un Pi effimero, OR set statico dai default se nessun Pi attivo (MVP: legge da un processo Pi effimero via `mgr`); ritorna `{models:[...]}`
  - `GET /workspaces` → lista da `harnessDir/workspaces/*.yaml` (solo nomi + path, no secret)

- [ ] **Step 1: Scrivere il test**

```typescript
import { test, expect } from "vitest";
import { buildApp } from "../src/app.js";
import { loadConfig } from "../src/config.js";

test("POST sql/preview ritorna le righe da ThtRunner", async () => {
  const app = buildApp(loadConfig({ THT_HARNESS_DIR: "../harness" }), {
    thtRunner: { sqlPreview: async () => ({ columns: ["a"], rows: [[1]], execution_ms: 2, truncated: false }) } as any,
  });
  const res = await app.inject({ method: "POST", url: "/sessions/s1/sql/preview", payload: { limit: 10, offset: 0 } });
  expect(res.json()).toEqual({ columns: ["a"], rows: [[1]], execution_ms: 2, truncated: false });
});

test("GET /workspaces elenca gli yaml senza secret", async () => {
  const app = buildApp(loadConfig({ THT_HARNESS_DIR: "../harness" }), { thtRunner: {} as any });
  const res = await app.inject({ method: "GET", url: "/workspaces" });
  expect(res.statusCode).toBe(200);
  expect(Array.isArray(res.json())).toBe(true);
});
```

- [ ] **Step 2: Eseguire (deve fallire)**

Run: `cd backend && npm test -- routes-sql-meta`
Expected: FAIL — route assenti.

- [ ] **Step 3: Implementare le route**

```typescript
// backend/src/routes/sql.ts
import type { FastifyInstance } from "fastify";
import type { ThtRunner } from "../tht/tht-runner.js";
export function sqlRoutes(app: FastifyInstance, d: { tht: ThtRunner }) {
  app.post("/sessions/:id/sql/preview", async (req) => {
    const b = (req.body ?? {}) as any;
    return d.tht.sqlPreview((req.params as any).id, { limit: b.limit, offset: b.offset });
  });
  app.post("/sessions/:id/sql/export", async (req) => d.tht.sqlExport((req.params as any).id));
}
```
```typescript
// backend/src/routes/meta.ts
import type { FastifyInstance } from "fastify";
import { readdirSync } from "node:fs";
import { join } from "node:path";
export function metaRoutes(app: FastifyInstance, d: { harnessDir: string; listModels: () => Promise<any> }) {
  app.get("/workspaces", async () => {
    const dir = join(d.harnessDir, "workspaces");
    return readdirSync(dir).filter((f) => f.endsWith(".yaml"))
      .map((f) => ({ name: f.replace(/\.ya?ml$/, ""), file: f }));
  });
  app.get("/models", async () => d.listModels());
}
```
In `app.ts`, `listModels` fa spawn di un Pi effimero, `rpc.request({type:"get_available_models"})`, poi teardown; in caso di errore ritorna `{ models: [] }`.

- [ ] **Step 4: Eseguire (deve passare) + commit**

Run: `cd backend && npm test -- routes-sql-meta`
Expected: PASS (2 test).
```bash
git add backend/src/routes/sql.ts backend/src/routes/meta.ts backend/src/app.ts backend/test/routes-sql-meta.test.ts
git commit -m "feat(backend): sql preview/export + models + workspaces routes"
```

---

### Task 11: Resume + PATH venv + smoke end-to-end F1 (fake-pi-rpc)

**Files:**
- Modify: `backend/src/pi/pi-process-manager.ts` (env PATH venv; `resume(sessionId)` legge il manifest via ThtRunner)
- Modify: `backend/src/routes/sessions.ts` (`POST /sessions/:id/resume`)
- Test: `backend/test/e2e-f1.test.ts`

**Interfaces:**
- Produces: `mgr.resume(sessionId, tht)` — rilegge `provider/model/thinking` da `tht.sessionShow` e fa `spawnFor` con quei valori; PATH dello spawn reale include `harnessDir/.venv/bin`.

- [ ] **Step 1: Scrivere lo smoke end-to-end**

```typescript
import { test, expect } from "vitest";
import { spawn } from "node:child_process";
import path from "node:path";
import { buildApp } from "../src/app.js";
import { loadConfig } from "../src/config.js";

const FAKE = path.resolve("../harness/tests/fake_pi/fake_pi_rpc.mjs");
const SCRIPT = path.resolve("../harness/tests/fake_pi/scripts/f1_disambiguation.json");

test("loop F1: crea sessione → SSE riceve il widget → risponde → 204", async () => {
  const app = buildApp(loadConfig({ THT_HARNESS_DIR: "../harness" }), {
    thtRunner: { sessionNew: async () => ({ id: "s1" }) } as any,
    spawnFn: () => spawn("node", [FAKE, SCRIPT]) as any,
  });
  await app.listen({ port: 0, host: "127.0.0.1" });
  const base = `http://127.0.0.1:${(app.server.address() as any).port}`;
  await fetch(`${base}/sessions`, { method: "POST", headers: { "content-type": "application/json" },
    body: JSON.stringify({ workspace: "w", question: "q" }) });
  // SSE: leggi il primo evento ui_request
  const es = await fetch(`${base}/sessions/s1/events`);
  const reader = es.body!.getReader(); const chunk = await reader.read();
  const text = new TextDecoder().decode(chunk.value);
  expect(text).toContain("ui_request");
  await reader.cancel();
  const resp = await fetch(`${base}/sessions/s1/response`, { method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ ui_response: { id: "u1", choices: ["a"] } }) });
  expect(resp.status).toBe(204);
  await app.close();
});
```

- [ ] **Step 2: Eseguire (deve fallire)**

Run: `cd backend && npm test -- e2e-f1`
Expected: FAIL inizialmente (race sull'ordine widget/SSE o resume assente). Diagnosticare con systematic-debugging se necessario.

- [ ] **Step 3: Implementare resume + PATH venv + fix ordine eventi**

- In `pi-process-manager.ts` (spawn reale): `PATH: \`${join(cfg.harnessDir, ".venv/bin")}:${process.env.PATH}\``.
- Aggiungere `async resume(id, tht)` che legge `sessionShow(id)` → `{provider, model, thinking}` e chiama `spawnFor`.
- Garantire che la route `POST /sessions` colleghi `bridge.onClientEvent → hub.publish` PRIMA di mandare il `prompt`, così l'evento widget non si perde; il `pendingWidget()` + re-emit (Task 7) copre comunque il caso SSE sottoscritto dopo.
- Aggiungere `POST /sessions/:id/resume` → `mgr.resume(id, tht)` + ricollegamento bridge→hub.

- [ ] **Step 4: Eseguire (deve passare) + commit**

Run: `cd backend && npm test`
Expected: PASS (tutta la suite).
```bash
git add backend/src/pi/pi-process-manager.ts backend/src/routes/sessions.ts backend/test/e2e-f1.test.ts
git commit -m "feat(backend): resume + venv PATH + end-to-end F1 smoke (fake-pi-rpc)"
```

- [ ] **Step 5: Validazione L2 con Pi reale (informativo, non-CI)**

Con harness configurato (`.env` + VPN) e `config/tht.yaml` valido: avviare `npm run dev`, fare `POST /sessions` con una domanda reale, aprire l'SSE e confermare che il widget F1 arriva dal Pi reale e che la risposta avanza il workflow. Annotare l'esito (questo è il primo loop end-to-end reale BE↔harness).

---

## Self-Review

**Spec coverage** (vs `2026-06-27-backend-design.md`):
- BE-1 (un Pi per sessione, resume): Task 6 + Task 11 ✓
- BE-2 (delega SQL): Task 5 (ThtRunner) + Task 10 (route) ✓
- BE-3 (re-emit widget pendente): Task 7 + Task 4 (`pendingWidget`) ✓
- BE-4 (test fake-Pi + unit TS): tutti i task usano vitest; fake-pi-rpc in Task 3/6/9/11 ✓
- BE-5 (id pre-creato): Task 9 (`tht session new` poi `spawnFor` con `THT_SESSION`) ✓ (dipende dal Piano Harness Task 5)
- BE-6 (model/thinking/provider per-sessione, persistiti, resume): Task 6 (`set_model`/`set_thinking`) + Task 11 (resume legge manifest) ✓
- BE-7 (settings Pi MVP): `--name`/provider/model/thinking via `sessionNew` (Task 5) + `GET /models` (Task 10); `--approve` nello spawn (Task 6); `quietStartup`/`trust`/`systemPrompt` sono harness-side (Piano Harness Task 9) ✓
- API §4 (tutti gli endpoint): Task 9 (sessions/events/response/steer/close) + Task 10 (sql/models/workspaces) + Task 1 (health) ✓
- Auth D6: Task 8 ✓
- Componenti §5 (PiProcessManager, RpcClient, SessionBridge, SseHub, ThtRunner, auth, config): Task 1–9 ✓
- Rischio PATH `tht` (§9): Task 6 (nota) + Task 11 (fix) ✓

**Placeholder scan:** nessun TBD. Le note implementative (PATH venv, `listModels` effimero) sono concretizzate nel task che le richiede (11, 10).

**Type consistency:** `ThtRunner.sqlPreview` ritorna `{columns, rows, execution_ms, truncated}` usato identico in Task 10. `SessionRuntime = {rpc, bridge, child}` coerente tra Task 6 e Task 9. `SessionBridge.respond(uiResponse)`/`steer(text)`/`pendingWidget()` coerenti tra Task 4, 7, 9. Comandi RPC (`set_model {provider, modelId}`, `set_thinking_level {level}`, `steer {message}`, `prompt {message}`, `get_available_models`) coerenti con `rpc-types.d.ts` di Pi. Envelope `{type:"extension_ui_request", ui_request}` coerente con il gate (Piano Harness Task 4) e il fake-pi-rpc (Piano Harness Task 10).

**Nota di sequenza:** Task 1–8 sono indipendenti dal Pi reale (CI puro con fake-pi-rpc). Le validazioni L2 (Task 11 Step 5) richiedono harness configurato + VPN.