@pasko70/pibo 3.1.3 → 3.2.0

package/dist/sessions/pibo-data-store.js

@@ -150,7 +150,7 @@ export class PiboDataSessionStore {
     claimOrAttachOutputPart(input) {
         return this.dataStore.transaction(() => {
             const indexAttribute = outputPartIndexAttribute(input.kind);
-            const eventTypes = outputPartEventTypes(input.kind);
+            const eventTypes = [...outputPartEventTypes(input.kind), "message_finished"];
             const placeholders = eventTypes.map(() => "?").join(", ");
             const rows = this.db.prepare(`
 				SELECT type, attributes_json
@@ -159,26 +159,33 @@ export class PiboDataSessionStore {
 				ORDER BY stream_id ASC
 			`).all(input.piboSessionId, input.eventId, ...eventTypes);
             let maximum = -1;
-            const latestTypeByIndex = new Map();
+            let turnCompleted = false;
+            const persistedParts = [];
             for (const row of rows) {
+                if (row.type === "message_finished") {
+                    turnCompleted = true;
+                    continue;
+                }
                 const attributes = parseJsonObject(row.attributes_json);
                 const index = attributes[indexAttribute];
                 if (typeof index !== "number" || !Number.isSafeInteger(index) || index < 0)
                     continue;
                 maximum = Math.max(maximum, index);
-                if (attributes.outputPartFingerprint === input.fingerprint
-                    || attributes.identityFingerprint === input.identityFingerprint) {
-                    this.observeOutputPartIndex(input, index);
-                    return index;
-                }
-                latestTypeByIndex.set(index, row.type);
+                persistedParts.push({ index, attributes });
             }
-            const latestOpen = [...latestTypeByIndex.entries()]
-                .filter(([, eventType]) => !outputPartEventIsTerminal(eventType))
-                .sort(([left], [right]) => right - left)[0]?.[0];
-            if (latestOpen !== undefined) {
-                this.observeOutputPartIndex(input, latestOpen);
-                return latestOpen;
+            // An unfinished durable part may still belong to another process. Only a
+            // completed turn provides enough evidence to reattach an exact replay.
+            if (turnCompleted) {
+                const matchesReplay = ({ attributes }) => attributes.outputPartFingerprint === input.fingerprint
+                    || attributes.identityFingerprint === input.identityFingerprint;
+                const replay = (input.suppliedIndex === undefined
+                    ? undefined
+                    : persistedParts.find((part) => part.index === input.suppliedIndex && matchesReplay(part)))
+                    ?? persistedParts.find(matchesReplay);
+                if (replay) {
+                    this.observeOutputPartIndex(input, replay.index);
+                    return replay.index;
+                }
             }
             const minimum = Math.max(input.proposedIndex, maximum + 1);
             const row = this.db.prepare(`
@@ -193,6 +200,11 @@ export class PiboDataSessionStore {
             return row.part_index;
         });
     }
+    observeOutputPart(input) {
+        this.dataStore.transaction(() => {
+            this.observeOutputPartIndex(input, input.index);
+        });
+    }
     observeOutputPartIndex(input, index) {
         this.db.prepare(`
 			INSERT INTO session_output_part_counters (
@@ -639,12 +651,6 @@ function outputPartEventTypes(kind) {
         case "compaction": return ["compaction_start", "compaction_end"];
     }
 }
-function outputPartEventIsTerminal(eventType) {
-    return eventType === "assistant_message"
-        || eventType === "thinking_finished"
-        || eventType === "assistant_usage"
-        || eventType === "compaction_end";
-}
 function parseJsonObject(json) {
     if (!json)
         return {};

package/dist/setup/cli.js

@@ -128,7 +128,7 @@ export function createUserHostSetupPlan(options = {}) {
     if (!options.domain)
         warnings.push("No production domain was provided; generated Caddy/Auth examples use placeholders.");
     if (process.platform === "win32" && !isWsl()) {
-        warnings.push("Pibo host setup targets Linux. Native Windows is not supported. Install WSL2 (https://aka.ms/wsl) and run setup inside the WSL distribution. See docs/guides/pibo-on-windows-via-wsl.md.");
+        warnings.push("Pibo host setup targets Linux. Native Windows is not supported. Install WSL2 (https://aka.ms/wsl) and run setup inside the WSL distribution. See docs/project/guides/pibo-on-windows-via-wsl.md.");
     }
     const generatedFiles = [
         {
@@ -201,7 +201,7 @@ export function createDeveloperHostSetupPlan(options = {}) {
     if (!options.prodDomain || !options.devDomain)
         warnings.push("Production and dev domains should both be configured before requesting HTTPS certificates.");
     if (process.platform === "win32" && !isWsl()) {
-        warnings.push("Pibo developer-host setup targets Linux. Native Windows is not supported. Install WSL2 (https://aka.ms/wsl) and run setup inside the WSL distribution. See docs/guides/pibo-on-windows-via-wsl.md.");
+        warnings.push("Pibo developer-host setup targets Linux. Native Windows is not supported. Install WSL2 (https://aka.ms/wsl) and run setup inside the WSL distribution. See docs/project/guides/pibo-on-windows-via-wsl.md.");
     }
     const generatedFiles = [
         {
@@ -496,13 +496,13 @@ async function createDoctorStatus(options) {
     if (wslInfo.isWsl) {
         const versionLabel = wslInfo.version ? `WSL${wslInfo.version}` : "WSL";
         const distroLabel = wslInfo.distro ? ` (${wslInfo.distro})` : "";
-        checks.push({ name: "platform.wsl", status: "ok", detail: `Running inside ${versionLabel}${distroLabel}; Pibo is fully supported here. See docs/guides/pibo-on-windows-via-wsl.md.` });
+        checks.push({ name: "platform.wsl", status: "ok", detail: `Running inside ${versionLabel}${distroLabel}; Pibo is fully supported here. See docs/project/guides/pibo-on-windows-via-wsl.md.` });
     }
     else if (process.platform === "win32") {
         checks.push({
             name: "platform.wsl",
             status: "fail",
-            detail: "Native Windows is not supported. Install WSL2 (https://aka.ms/wsl) and run Pibo inside the WSL distribution. See docs/guides/pibo-on-windows-via-wsl.md.",
+            detail: "Native Windows is not supported. Install WSL2 (https://aka.ms/wsl) and run Pibo inside the WSL distribution. See docs/project/guides/pibo-on-windows-via-wsl.md.",
         });
     }
     checks.push(...swapCheck(options.minSwapGb));
@@ -610,7 +610,7 @@ async function createDoctorStatus(options) {
         recommendations.push("Browser-Use and Agent-Browser work directly under WSLg on Windows 11. On Windows 10, install an X server (e.g. VcXsrv) and export DISPLAY=:0 inside WSL.");
     }
     else if (process.platform === "win32") {
-        recommendations.push("Pibo does not run natively on Windows. Install WSL2 with `wsl --install` and follow docs/guides/pibo-on-windows-via-wsl.md.");
+        recommendations.push("Pibo does not run natively on Windows. Install WSL2 with `wsl --install` and follow docs/project/guides/pibo-on-windows-via-wsl.md.");
     }
     return {
         node: process.versions.node,

package/dist/shared/trace-engine.js

@@ -1,5 +1,5 @@
 import { reconcileAsyncAgentRunStatuses } from "./trace-async-agent-runs.js";
-import { applySingleEventToNodes, dedupeTraceEvents, findOpenTranscriptEventIds, latestTraceStreamId, mergeMessageTurnTimings, messageTurnTimingsFromEvents, reconcileTranscriptUserMessages, } from "./trace-event-projection.js";
+import { applySingleEventToNodes, dedupeTraceEvents, findOpenTranscriptEventIds, latestTraceStreamId, markIncompletePersistedTurns, mergeMessageTurnTimings, messageTurnTimingsFromEvents, reconcileTranscriptUserMessages, } from "./trace-event-projection.js";
 import { flattenTraceNodes, mapTraceNodesById, nestTraceNodes } from "./trace-nodes.js";
 import { mapTraceChildSessionsByParent, mapTraceSubagentSessionLinks, } from "./trace-subagent-links.js";
 import { projectHistoryEntries, traceNodesFromHistoryEntries } from "./trace-history.js";
@@ -18,7 +18,8 @@ export function buildTraceViewFromEvents(input) {
     const openHistoryEventIds = findOpenTranscriptEventIds(events, sessionStatus);
     const suppliedTurnTimings = input.turnTimings ?? [];
     const eventTurnTimings = messageTurnTimingsFromEvents(events);
-    const timingOverflow = suppliedTurnTimings.length + eventTurnTimings.length > TRACE_RECONCILIATION_TIMING_CAP;
+    const timingOverflow = input.turnTimingOverflow === true
+        || suppliedTurnTimings.length + eventTurnTimings.length > TRACE_RECONCILIATION_TIMING_CAP;
     const turnTimings = timingOverflow
         ? []
         : mergeMessageTurnTimings(suppliedTurnTimings, eventTurnTimings);
@@ -42,11 +43,13 @@ export function buildTraceViewFromEvents(input) {
     for (const storedEvent of events) {
         applySingleEventToNodes(nodes, byId, input.session.id, storedEvent, childByParent, linkedChildByToolCallId, historyCoverage, openHistoryEventIds, sessionStatus);
     }
+    const hasIncompleteTurns = markIncompletePersistedTurns(nodes, byId, input.session.id, events, turnTimings, sessionStatus);
     const nestedNodes = nestTraceNodes(nodes);
     reconcileAsyncAgentRunStatuses(nestedNodes);
     return {
         piboSessionId: input.session.id,
         piSessionId: input.session.piSessionId,
+        ...(hasIncompleteTurns ? { integrityStatus: "incomplete" } : {}),
         title: input.session.title ?? "Untitled Session",
         version: "",
         latestStreamId: latestTraceStreamId(events, input.latestStreamId),

package/dist/shared/trace-event-projection.js

@@ -232,6 +232,80 @@ function turnClosedAt(turn, byId) {
         .at(0);
     return error?.startedAt;
 }
+const INCOMPLETE_TURN_SUMMARY = "Incomplete output lifecycle";
+const INCOMPLETE_TURN_ERROR = "Persisted output has message_started but no message_finished or session_error event.";
+export function markIncompletePersistedTurns(nodes, byId, piboSessionId, events, turnTimings, sessionStatus) {
+    const lifecycleByEventId = new Map();
+    for (const timing of turnTimings) {
+        const lifecycle = lifecycleByEventId.get(timing.eventId) ?? { started: false, completed: false };
+        lifecycle.started ||= timing.startedAt !== undefined;
+        lifecycle.completed ||= timing.completedAt !== undefined;
+        lifecycleByEventId.set(timing.eventId, lifecycle);
+    }
+    const incompleteEventIds = new Set([...lifecycleByEventId].flatMap(([eventId, lifecycle]) => lifecycle.started && !lifecycle.completed ? [eventId] : []));
+    if (sessionStatus === "running") {
+        const currentTurn = [...turnTimings].reverse().find((timing) => timing.userMessageType !== "message_steered" &&
+            timing.startedAt !== undefined);
+        if (currentTurn?.startedAt !== undefined && currentTurn.completedAt === undefined) {
+            incompleteEventIds.delete(currentTurn.eventId);
+        }
+    }
+    if (incompleteEventIds.size === 0)
+        return false;
+    const startByEventId = new Map();
+    const lastByEventId = new Map();
+    for (const storedEvent of events) {
+        const event = storedEvent.payload;
+        const eventId = "eventId" in event && typeof event.eventId === "string" ? event.eventId : undefined;
+        if (!eventId || !incompleteEventIds.has(eventId))
+            continue;
+        if (event.type === "message_started" && !startByEventId.has(eventId))
+            startByEventId.set(eventId, storedEvent);
+        lastByEventId.set(eventId, storedEvent);
+    }
+    for (const eventId of incompleteEventIds) {
+        const start = startByEventId.get(eventId);
+        if (!start)
+            continue;
+        const startEvent = start.payload;
+        const turnId = messageTurnNodeId(eventId);
+        let turn = byId.get(turnId);
+        if (!turn) {
+            turn = traceNodeFromEvent(piboSessionId, startEvent, new Map(), new Map(), sessionStatus, start.createdAt, start.eventSequence, start.streamId, start.streamFrameIndex, start.traceSource, start.id);
+            if (!turn)
+                continue;
+            nodes.push(turn);
+            byId.set(turn.id, turn);
+        }
+        turn.status = "error";
+        turn.summary = INCOMPLETE_TURN_SUMMARY;
+        turn.error = INCOMPLETE_TURN_ERROR;
+        const markerId = `event:incomplete-turn:${eventId}`;
+        if (byId.has(markerId))
+            continue;
+        const last = lastByEventId.get(eventId) ?? start;
+        const marker = {
+            id: markerId,
+            parentId: turnId,
+            piboSessionId,
+            eventId,
+            type: "error",
+            title: "Incomplete Turn",
+            status: "error",
+            startedAt: last.createdAt,
+            summary: INCOMPLETE_TURN_SUMMARY,
+            error: INCOMPLETE_TURN_ERROR,
+            output: INCOMPLETE_TURN_ERROR,
+            source: "event-log",
+            stableKey: `incomplete-turn:${eventId}`,
+            orderKey: eventTraceNodeOrder(last.eventSequence, "session_error", last.streamId, last.streamFrameIndex, last.traceSource, undefined, last.createdAt),
+            children: [],
+        };
+        nodes.push(marker);
+        byId.set(marker.id, marker);
+    }
+    return [...incompleteEventIds].some((eventId) => byId.has(`event:incomplete-turn:${eventId}`));
+}
 export function eventsCanAffectAsyncAgentRunStatus(events) {
     return events.some((event) => {
         const type = event.payload.type;

package/dist/shared/trace-page-merge.js

@@ -4,10 +4,12 @@ export function mergeOlderTracePage(current, older) {
     if (current.piboSessionId !== older.piboSessionId)
         return current;
     const rawEvents = mergeTraceRawEvents(older.rawEvents, current.rawEvents, false);
+    const nodes = mergeTraceNodes(older.nodes, current.nodes);
     return {
         ...current,
         version: current.version,
-        nodes: mergeTraceNodes(older.nodes, current.nodes),
+        integrityStatus: traceIntegrityStatus(nodes) ?? current.integrityStatus ?? older.integrityStatus,
+        nodes,
         rawEvents,
         beforeCursor: older.beforeCursor ?? current.beforeCursor,
         firstEventSequence: older.firstEventSequence ?? current.firstEventSequence,
@@ -20,9 +22,11 @@ export function mergeOlderTracePage(current, older) {
 export function mergeRefreshedTracePage(current, refreshed) {
     if (current.piboSessionId !== refreshed.piboSessionId)
         return refreshed;
+    const nodes = mergeRefreshedTraceNodes(current.nodes, refreshed);
     return {
         ...refreshed,
-        nodes: mergeRefreshedTraceNodes(current.nodes, refreshed),
+        integrityStatus: traceIntegrityStatus(nodes) ?? refreshed.integrityStatus,
+        nodes,
         rawEvents: mergeTraceRawEvents(current.rawEvents, refreshed.rawEvents, true),
         beforeCursor: current.beforeCursor,
         firstEventSequence: current.firstEventSequence ?? refreshed.firstEventSequence,
@@ -36,10 +40,13 @@ function mergeRefreshedTraceNodes(currentNodes, refreshed) {
     const flattenedCurrentNodes = flattenTraceNodes([...currentNodes]);
     const refreshedNodes = flattenTraceNodes([...refreshed.nodes]);
     const refreshedIds = new Set(refreshedNodes.map((node) => node.id));
+    const refreshedTerminalEventIds = terminalEventIds(refreshedNodes);
     const canonicalTranscriptEventIds = transcriptEventIds([...flattenedCurrentNodes, ...refreshedNodes]);
     const refreshedOrderBoundaries = earliestTraceNodeOrdersBySource(refreshedNodes);
     const refreshedStartedAt = earliestTraceNodeTimestamp(refreshedNodes);
     const retainedOlderNodes = flattenedCurrentNodes.filter((node) => {
+        if (isIncompleteTurnMarker(node) && node.eventId && refreshedTerminalEventIds.has(node.eventId))
+            return false;
         if (refreshedIds.has(node.id))
             return true;
         if (node.type === "agent.turn" &&
@@ -71,9 +78,28 @@ function mergeRefreshedTraceNodes(currentNodes, refreshed) {
     return mergeTraceNodes(clearRemovedParentIds(retainedOlderNodes, removedCurrentIds), clearRemovedParentIds(refreshedNodes, removedCurrentIds));
 }
 function clearRemovedParentIds(nodes, removedIds) {
-    return nodes.map((node) => node.parentId && removedIds.has(node.parentId)
-        ? { ...node, parentId: undefined }
-        : node);
+    return nodes.map((node) => ({
+        ...node,
+        ...(node.parentId && removedIds.has(node.parentId) ? { parentId: undefined } : {}),
+        children: [],
+    }));
+}
+function traceIntegrityStatus(nodes) {
+    return flattenTraceNodes([...nodes]).some(isIncompleteTurnMarker) ? "incomplete" : undefined;
+}
+function isIncompleteTurnMarker(node) {
+    return node.id.startsWith("event:incomplete-turn:") || node.stableKey?.startsWith("incomplete-turn:") === true;
+}
+function terminalEventIds(nodes) {
+    return new Set(nodes.flatMap((node) => {
+        if (!node.eventId)
+            return [];
+        if (node.type === "agent.turn" && node.completedAt)
+            return [node.eventId];
+        if (node.type === "error" && node.title === "Session Error")
+            return [node.eventId];
+        return [];
+    }));
 }
 function transcriptEventIds(nodes) {
     const eventIds = new Set();

package/docs/project/guides/pibo-on-windows-via-wsl.md

@@ -0,0 +1,292 @@
+---
+type: "Guide"
+title: "Pibo on Windows via WSL"
+description: "Guides Windows users through installing Pibo and the VS Code extension inside WSL2."
+tags: ["installation", "windows", "wsl", "vscode"]
+status: "draft"
+authority: "directive"
+generated:
+  by: "openai/codex"
+  at: "2026-08-30T15:47:50Z"
+sources:
+  - id: "foundation-relocation-source"
+    resource: "https://github.com/Pascapone/pibo/blob/2aef244301f5d181624662fdad53e18e83e80bd9/docs/guides/pibo-on-windows-via-wsl.md"
+    title: "Original byte-preserved Pibo on Windows via WSL guide"
+    commit: "2aef244301f5d181624662fdad53e18e83e80bd9"
+    path: "docs/guides/pibo-on-windows-via-wsl.md"
+    sha256: "132f00469edcfa8915525bff4d0c9d82573ae53868a74db81d5224d354ce1d25"
+    relation: "Byte-identical body lineage before Foundation relocation."
+---
+# Pibo on Windows via WSL
+
+Pibo is a Linux-first tool. Native Windows is **not** supported, but Pibo runs unmodified inside **WSL2** because WSL2 is a real Linux kernel with full filesystem, symlink, and process semantics. This guide walks a Windows user from a fresh machine to a working `pibo` install, including the Pibo VSCode extension.
+
+Total setup time: **15–25 minutes** on Windows 11 with WSLg enabled.
+
+## Why WSL and not native Windows?
+
+| | Native Windows | WSL2 |
+|---|---|---|
+| **Code changes** | 12+ POSIX assumptions would need workarounds | 0 — Pibo already runs on Linux |
+| **Docker workers** | Docker Desktop only, paths are awkward | Docker Desktop integrates with WSL2, no friction |
+| **Browser-Use / Agent-Browser** | Need WSL or WSLg anyway | Works directly under WSLg |
+| **`pibo setup` (systemd, caddy)** | Would need a Windows port | Works as on Linux |
+| **Symlinks, file modes, line endings** | Pain | Native |
+| **Long-term maintenance** | Two code paths | One code path |
+
+Microsoft itself recommends WSL for Linux-style development on Windows. The VSCode "WSL" extension, Docker Desktop's WSL2 backend, and Windows 11's WSLg GUI integration make WSL a first-class dev environment.
+
+## Prerequisites
+
+- **Windows 10 version 2004+** or **Windows 11** (any edition)
+- Administrator access for the WSL install
+- About 5 GB free disk space (WSL image + Pibo + node_modules)
+
+## Step 1 — Install WSL (5 min, one-time)
+
+Open **PowerShell as Administrator** and run:
+
+```powershell
+wsl --install
+```
+
+Default settings install Ubuntu. Reboot when prompted. On first boot, Ubuntu sets a username and password.
+
+Verify the install:
+
+```powershell
+wsl --status
+# Default Distribution: Ubuntu
+# Default Version: 2
+```
+
+> **Tip:** If you want a different distro (Debian, openSUSE, Alpine…), run `wsl --install -d <DistroName>`. The rest of this guide works for any of them.
+
+## Step 2 — Verify the WSL version (1 min)
+
+Inside the WSL shell (run `wsl` in PowerShell to enter it), confirm WSL2:
+
+```bash
+cat /proc/sys/kernel/osrelease
+# Look for "microsoft-standard-WSL2" or "WSL2" in the output.
+```
+
+If you see "Microsoft" without the WSL2 marker, your distro is on WSL1. Convert it:
+
+```powershell
+# PowerShell
+wsl --set-version Ubuntu 2
+```
+
+WSL1 cannot run Docker well and lacks the full Linux kernel Pibo expects. Use WSL2.
+
+## Step 3 — Install Node.js 24+ inside WSL (3 min)
+
+The Ubuntu default Node is often too old. Use NodeSource:
+
+```bash
+# Inside WSL
+sudo apt update
+sudo apt install -y ca-certificates curl gnupg
+curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
+sudo apt install -y nodejs build-essential
+node --version    # must print v24.x.x or higher
+npm --version
+```
+
+## Step 4 — Install Pibo inside WSL (1 min)
+
+```bash
+# Inside WSL
+npm install -g @pasko70/pibo
+pibo --version
+```
+
+Pibo's data lives in `~/.pibo` inside the WSL filesystem. This is intentional: WSL-native paths are fast, while `/mnt/c/...` mounts are slow. Keep Pibo's working data inside WSL.
+
+## Step 5 — Install VSCode and the WSL extension (3 min)
+
+1. Install **VSCode for Windows** from <https://code.visualstudio.com/> (the standard Windows .exe, not the .deb).
+2. In VSCode, open the **Extensions** panel (Ctrl+Shift+X) and install **WSL** by Microsoft.
+3. **Open your project folder inside WSL.** In the WSL terminal:
+   ```bash
+   cd ~/projects/my-app    # or wherever your project lives
+   code .
+   ```
+   VSCode opens a second VSCode window. Title bar shows the distro name in green (`[WSL: Ubuntu]`). File editing, terminal, and extensions all run inside WSL.
+
+> **Why this step matters:** when you run `code .` from inside WSL, VSCode installs its Linux server binary inside the WSL distro, the integrated terminal becomes a WSL bash, and `code` is added to WSL's `PATH`. That is what makes `pibo vscode install` work seamlessly.
+
+## Step 6 — Configure Pibo auth (3 min)
+
+Pibo uses [Better Auth](https://www.better-auth.com/) with Google OAuth. Set the keys once:
+
+```bash
+# Inside WSL
+pibo config set auth.baseURL http://127.0.0.1:4788
+pibo config set auth.secret "$(openssl rand -hex 32)"
+pibo config set auth.googleClientId <your-google-oauth-client-id>
+pibo config set auth.googleClientSecret <your-google-oauth-client-secret>
+pibo config set auth.allowedEmails you@example.com
+```
+
+To get Google OAuth credentials, create a Web Application client at <https://console.cloud.google.com/apis/credentials>. The redirect URI is `http://127.0.0.1:4788/api/auth/callback/google`. See the [Quick Start Guide](./pibo-vscode-ext-quickstart.md) for the full walkthrough.
+
+## Step 7 — Start the Pibo gateway (1 min)
+
+```bash
+# Inside WSL, leave this running in a terminal
+pibo gateway:web
+```
+
+The gateway listens on `127.0.0.1:4788` **inside WSL**. Windows can reach this URL because WSL2 forwards localhost from Windows to the WSL2 VM by default.
+
+Open a **second** WSL terminal and verify:
+
+```bash
+curl -s http://127.0.0.1:4788/api/health
+# or open in your Windows browser:
+# http://127.0.0.1:4788/apps/chat
+```
+
+> **If localhost does not work in the Windows browser:** the WSL2 localhost forwarder is disabled or blocked. See [Troubleshooting](#localhost-forwarding-not-working) below.
+
+## Step 8 — Install the Pibo VSCode extension (2 min)
+
+### Option A — from the WSL terminal (recommended)
+
+```bash
+# Inside the WSL VSCode terminal (Ctrl+`)
+pibo vscode install
+```
+
+This downloads the latest VSIX from GitHub Releases and runs `code --install-extension` against the WSL `code` binary.
+
+### Option B — from the Marketplace
+
+Search **Pibo** by publisher `pibo` in the Extensions panel. Install the one named **Pibo** by `pibo`.
+
+### Verify
+
+```bash
+pibo vscode status
+# Should print the installed extension ID and the gateway URL.
+```
+
+Click the **Pibo** icon in the VSCode sidebar (left rail). A web view opens. Sign in with Google. The status bar at the bottom should show the room you are in.
+
+## Step 9 — Optional — Docker workers
+
+Pibo's compute workers run as Docker containers. To enable them on WSL:
+
+1. Install **Docker Desktop for Windows**: <https://www.docker.com/products/docker-desktop/>
+2. Open Docker Desktop → **Settings** → **Resources** → **WSL Integration**.
+3. Enable the toggle for **Ubuntu** (or whichever distro you use).
+4. Click **Apply & Restart**.
+
+Test from WSL:
+
+```bash
+docker run --rm hello-world
+# Should print "Hello from Docker!"
+```
+
+Pibo will detect Docker automatically. `pibo compute dev spawn --worktree <name>` now works.
+
+## Step 10 — Optional — Browser-Use and Agent-Browser
+
+Both tools need a graphical browser under the hood.
+
+- **Windows 11 with WSLg** (default on fresh installs): no extra setup. Browser windows appear as regular Windows windows.
+- **Windows 10 or older Windows 11 without WSLg**: install an X server in Windows (e.g. [VcXsrv](https://sourceforge.net/projects/vcxsrv/)) and export the display in WSL:
+  ```bash
+  # Inside WSL ~/.bashrc
+  export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0
+  ```
+  Launch VcXsrv in Windows with "Disable access control" ticked.
+
+To install the tools:
+
+```bash
+pibo tools install browser-use
+pibo tools install agent-browser
+pibo tools env browser-use
+```
+
+## Where Pibo stores things on WSL
+
+| Path (inside WSL) | What |
+|---|---|
+| `~/.pibo/config.json` | Pibo configuration (auth, ports, etc.) |
+| `~/.pibo/pibo.sqlite` | Sessions, rooms, signals |
+| `~/.pibo/vscode/cache/` | VSIX cache for `pibo vscode install` |
+| `<workspace>/.pibo/` | Per-workspace room state |
+
+> Keep these inside the WSL filesystem (not under `/mnt/c/...`). Cross-FS access is slow and breaks symlinks.
+
+## Troubleshooting
+
+### Localhost forwarding not working
+
+WSL2 forwards `localhost` from Windows to the WSL VM by default. If the gateway at `http://127.0.0.1:4788` is unreachable from a Windows browser:
+
+1. **Check Windows version.** Localhost forwarding works on Windows 11 and on Windows 10 22H2+. Older builds had bugs.
+2. **Check the WSL version.** Run `wsl --status` — `Default Version: 2`.
+3. **Check Windows Firewall.** Allow inbound to WSL. Run in PowerShell as Admin:
+   ```powershell
+   New-NetFirewallRule -DisplayName "WSL" -Direction Inbound -InterfaceAlias "vEthernet (WSL)" -Action Allow
+   ```
+4. **Fallback:** use the WSL2 VM's IP. Inside WSL run:
+   ```bash
+   hostname -I
+   # e.g. prints 172.21.123.45
+   ```
+   Then in your Windows browser use `http://172.21.123.45:4788`. The IP changes on each WSL boot, so this is a workaround, not a permanent solution.
+5. **Last resort:** set up `netsh interface portproxy`:
+   ```powershell
+   # PowerShell as Admin
+   $wslIp = wsl hostname -I
+   netsh interface portproxy add v4tov4 listenport=4788 listenaddress=0.0.0.0 connectport=4788 connectaddress=$wslIp
+   ```
+
+### `pibo setup doctor` warns about native Windows
+
+You are running Pibo from a Windows PowerShell or `cmd.exe`, not from inside WSL. Open the **WSL** terminal (or run `wsl` from PowerShell) and try again.
+
+### Browser-Use opens a blank window
+
+The DISPLAY is not set or the X server is not running. On Windows 11 with WSLg, `echo $DISPLAY` should print something like `:0` or `wayland-0`. On Windows 10, start VcXsrv and export `DISPLAY` as shown above.
+
+### `pibo vscode install` cannot find `code`
+
+This means VSCode's WSL server is not active in the current VSCode window. Run `code .` from inside WSL once, restart VSCode, then try again. If you opened VSCode directly from the Start Menu (not via `code .` in WSL), you are in the Windows VSCode instance, not the WSL one.
+
+### File edits are slow
+
+You are editing files on `/mnt/c/...` (the Windows drive). Move the project into the WSL filesystem (`/home/<you>/projects/...`). NTFS access from WSL is slow because of `metadata` and `umask` differences.
+
+### Docker commands fail inside WSL
+
+Open Docker Desktop → Settings → Resources → WSL Integration → enable your distro → **Apply & Restart**. Verify with `docker run --rm hello-world`.
+
+## Verifying everything works
+
+Run the following inside WSL:
+
+```bash
+pibo --version                          # 1.3.0 or higher
+pibo setup doctor                       # all checks should be OK or WARN
+pibo vscode status                      # extension should be installed
+pibo tools list                         # should list browser-use, agent-browser, etc.
+```
+
+Open the VSCode sidebar → Pibo icon → web view loads → sign in with Google → create a new session → send a message. The status bar at the bottom should show a green dot and your room name.
+
+If all of that works, you are fully set up.
+
+## What we deliberately do not support
+
+- **Native Windows** (no WSL). Pibo will print a clear error pointing you back to this guide.
+- **WSL1.** WSL1 lacks the full Linux kernel Pibo expects. Use WSL2.
+- **Cygwin, MSYS2, Git Bash.** These are POSIX shims, not real Linux. Pibo will not work; use WSL2.
+- **Windows Containers in Docker.** Pibo compute workers target Linux containers.