gsd-pi 2.26.0 → 2.27.0

package/README.md

@@ -39,6 +39,7 @@ Full documentation is available in the [`docs/`](./docs/) directory:
 - **[Architecture](./docs/architecture.md)** — system design and dispatch pipeline
 - **[Troubleshooting](./docs/troubleshooting.md)** — common issues, doctor, forensics, recovery
 - **[VS Code Extension](./vscode-extension/README.md)** — chat participant, sidebar dashboard, RPC integration
+- **[Visualizer](./docs/visualizer.md)** — workflow visualizer with stats and discussion status
 - **[Migration from v1](./docs/migration.md)** — `.planning` → `.gsd` migration
 
 ---
@@ -67,6 +68,9 @@ GSD v2 solves all of these because it's not a prompt framework anymore — it's
 | Context injection    | "Read this file"             | Pre-inlined into dispatch prompt                        |
 | Roadmap reassessment | Manual                       | Automatic after each slice completes                    |
 | Skill discovery      | None                         | Auto-detect and install relevant skills during research |
+| Verification         | Manual                       | Automated verification commands with auto-fix retries   |
+| Reporting            | None                         | Self-contained HTML reports with metrics and dep graphs  |
+| Parallel execution   | None                         | Multi-worker parallel milestone orchestration            |
 
 ### Migrating from v1
 
@@ -117,7 +121,7 @@ Research → Plan → Execute (per task) → Complete → Reassess Roadmap → N
                                                               Validate Milestone → Complete Milestone
 ```
 
-**Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded. **Complete** writes the summary, UAT script, marks the roadmap, and commits. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
+**Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded — then runs configured verification commands (lint, test, etc.) with auto-fix retries. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
 
 ### `/gsd auto` — The Main Event
 
@@ -137,7 +141,7 @@ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`,
 
 3. **Git worktree isolation** — Each milestone runs in its own git worktree with a `milestone/<MID>` branch. All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit.
 
-4. **Crash recovery** — A lock file tracks the current unit. If the session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context.
+4. **Crash recovery** — A lock file tracks the current unit. If the session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. Parallel orchestrator state is persisted to disk with PID liveness detection, so multi-worker sessions survive crashes too.
 
 5. **Stuck detection** — If the same unit dispatches twice (the LLM didn't produce the expected artifact), it retries once with a deep diagnostic. If it fails again, auto mode stops with the exact file it expected.
 
@@ -147,7 +151,11 @@ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`,
 
 8. **Adaptive replanning** — After each slice completes, the roadmap is reassessed. If the work revealed new information that changes the plan, slices are reordered, added, or removed before continuing.
 
-9. **Escape hatch** — Press Escape to pause. The conversation is preserved. Interact with the agent, inspect what happened, or just `/gsd auto` to resume from disk state.
+9. **Verification enforcement** — Configure shell commands (`npm run lint`, `npm run test`, etc.) that run automatically after task execution. Failures trigger auto-fix retries before advancing. Configurable via `verification_commands`, `verification_auto_fix`, and `verification_max_retries` preferences.
+
+10. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.
+
+11. **Escape hatch** — Press Escape to pause. The conversation is preserved. Interact with the agent, inspect what happened, or just `/gsd auto` to resume from disk state.
 
 ### `/gsd` and `/gsd next` — Step Mode
 
@@ -233,17 +241,22 @@ Both terminals read and write the same `.gsd/` files on disk. Your decisions in
 # Run auto mode in CI
 gsd headless --timeout 600000
 
+# Create and execute a milestone end-to-end
+gsd headless new-milestone --context spec.md --auto
+
 # One unit at a time (cron-friendly)
 gsd headless next
 
-# Machine-readable status
+# Machine-readable JSONL event stream
 gsd headless --json status
 
 # Force a specific pipeline phase
 gsd headless dispatch plan
 ```
 
-Headless auto-responds to interactive prompts, detects completion, and exits with structured codes: `0` complete, `1` error/timeout, `2` blocked. Pair with [remote questions](./docs/remote-questions.md) to route decisions to Slack or Discord when human input is needed.
+Headless auto-responds to interactive prompts, detects completion, and exits with structured codes: `0` complete, `1` error/timeout, `2` blocked. Auto-restarts on crash with exponential backoff. Pair with [remote questions](./docs/remote-questions.md) to route decisions to Slack or Discord when human input is needed.
+
+**Multi-session orchestration** — headless mode supports file-based IPC in `.gsd/parallel/` for coordinating multiple GSD workers across milestones. Build orchestrators that spawn, monitor, and budget-cap a fleet of GSD workers.
 
 ### First launch
 
@@ -269,6 +282,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd forensics`        | Post-mortem investigation of auto-mode failures                 |
 | `/gsd cleanup`          | Archive phase directories from completed milestones             |
 | `/gsd doctor`           | Runtime health checks with auto-fix for common issues           |
+| `/gsd export --html`    | Generate HTML report for current or completed milestone         |
 | `/worktree` (`/wt`)     | Git worktree lifecycle — create, switch, merge, remove          |
 | `/voice`                | Toggle real-time speech-to-text (macOS, Linux)                  |
 | `/exit`                 | Graceful shutdown — saves session state before exiting          |
@@ -277,6 +291,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `Ctrl+Alt+G`            | Toggle dashboard overlay                                        |
 | `Ctrl+Alt+V`            | Toggle voice transcription                                      |
 | `Ctrl+Alt+B`            | Show background shell processes                                 |
+| `Alt+V`                 | Paste clipboard image (macOS)                                   |
 | `gsd config`            | Re-run the setup wizard (LLM provider + tool keys)              |
 | `gsd update`            | Update GSD to the latest version                                |
 | `gsd headless [cmd]`    | Run `/gsd` commands without TUI (CI, cron, scripts)             |
@@ -321,7 +336,7 @@ gsd/M001/S01 (deleted after merge):
   feat(S01/T01): core types and interfaces
 ```
 
-One squash commit per milestone on main (or whichever branch you started from). The worktree is torn down after merge. Git bisect works. Individual milestones are revertable.
+One squash commit per milestone on main (or whichever branch you started from). The worktree is torn down after merge. Git bisect works. Individual milestones are revertable. Commit messages are generated from task summaries — no more generic "complete task" messages.
 
 ### Verification
 
@@ -343,6 +358,15 @@ The verification ladder: static checks → command execution → behavioral test
 - Cost projections based on completed work
 - Completed and in-progress units
 
+### HTML Reports
+
+After a milestone completes, GSD auto-generates a self-contained HTML report in `.gsd/reports/`. Each report includes project summary, progress tree, slice dependency graph (SVG DAG), cost/token metrics with bar charts, execution timeline, changelog, and knowledge base sections. No external dependencies — all CSS and JS are inlined, printable to PDF from any browser.
+
+An auto-generated `index.html` shows all reports with progression metrics across milestones.
+
+- **Automatic** — generated after milestone completion (configurable via `auto_report` preference)
+- **Manual** — run `/gsd export --html` anytime
+
 ---
 
 ## Configuration
@@ -370,6 +394,10 @@ auto_supervisor:
   hard_timeout_minutes: 30
 budget_ceiling: 50.00
 unique_milestone_ids: true
+verification_commands:
+  - npm run lint
+  - npm run test
+auto_report: true
 ---
 ```
 
@@ -387,6 +415,11 @@ unique_milestone_ids: true
 | `skill_staleness_days` | Skills unused for N days get deprioritized (default: 60, 0 = disabled)                                |
 | `unique_milestone_ids` | Uses unique milestone names to avoid clashes when working in teams of people                          |
 | `git.isolation`        | `worktree` (default) or `none` — disable worktree isolation for projects that don't need it           |
+| `verification_commands`| Array of shell commands to run after task execution (e.g., `["npm run lint", "npm run test"]`)        |
+| `verification_auto_fix`| Auto-retry on verification failures (default: true)                                                   |
+| `verification_max_retries` | Max retries for verification failures (default: 2)                                               |
+| `require_slice_discussion` | Pause auto-mode before each slice for human discussion review                                    |
+| `auto_report`          | Auto-generate HTML reports after milestone completion (default: true)                                 |
 
 ### Agent Instructions
 
@@ -471,6 +504,10 @@ The best practice for working in teams is to ensure unique milestone names acros
 .gsd/runtime/
 # Git worktree working copies
 .gsd/worktrees/
+# Parallel orchestration IPC and worker status
+.gsd/parallel/
+# Generated HTML reports (regenerable via /gsd export --html)
+.gsd/reports/
 # Session-specific interrupted-work markers
 .gsd/milestones/**/continue.md
 .gsd/milestones/**/*-CONTINUE.md

package/dist/cli.js

@@ -239,7 +239,9 @@ const configuredExists = configuredProvider && configuredModel &&
     allModels.some((m) => m.provider === configuredProvider && m.id === configuredModel);
 const configuredAvailable = configuredProvider && configuredModel &&
     availableModels.some((m) => m.provider === configuredProvider && m.id === configuredModel);
-if (!configuredModel || !configuredExists || !configuredAvailable) {
+if (!configuredModel || !configuredExists) {
+    // Model not configured at all, or removed from registry — pick a fallback.
+    // Only fires when the model is genuinely unknown (not just temporarily unavailable).
     const piDefault = getPiDefaultModelAndProvider();
     const preferred = (piDefault
         ? availableModels.find((m) => m.provider === piDefault.provider && m.id === piDefault.model)
@@ -254,7 +256,7 @@ if (!configuredModel || !configuredExists || !configuredAvailable) {
         settingsManager.setDefaultModelAndProvider(preferred.provider, preferred.id);
     }
 }
-if (settingsManager.getDefaultThinkingLevel() !== 'off' && (!configuredExists || !configuredAvailable)) {
+if (settingsManager.getDefaultThinkingLevel() !== 'off' && !configuredExists) {
     settingsManager.setDefaultThinkingLevel('off');
 }
 // GSD always uses quiet startup — the gsd extension renders its own branded header

package/dist/headless.d.ts

@@ -20,6 +20,9 @@ export interface HeadlessOptions {
     contextText?: string;
     auto?: boolean;
     verbose?: boolean;
+    maxRestarts?: number;
+    supervised?: boolean;
+    responseTimeout?: number;
 }
 export declare function parseHeadlessArgs(argv: string[]): HeadlessOptions;
 export declare function runHeadless(options: HeadlessOptions): Promise<void>;

package/dist/headless.js

@@ -15,6 +15,7 @@ import { join, resolve } from 'node:path';
 // RpcClient is not in @gsd/pi-coding-agent's public exports — import from dist directly.
 // This relative path resolves correctly from both src/ (via tsx) and dist/ (compiled).
 import { RpcClient } from '../packages/pi-coding-agent/dist/modes/rpc/rpc-client.js';
+import { attachJsonlLineReader, serializeJsonLine } from '../packages/pi-coding-agent/dist/modes/rpc/jsonl.js';
 // ---------------------------------------------------------------------------
 // CLI Argument Parser
 // ---------------------------------------------------------------------------
@@ -58,6 +59,24 @@ export function parseHeadlessArgs(argv) {
             else if (arg === '--verbose') {
                 options.verbose = true;
             }
+            else if (arg === '--max-restarts' && i + 1 < args.length) {
+                options.maxRestarts = parseInt(args[++i], 10);
+                if (Number.isNaN(options.maxRestarts) || options.maxRestarts < 0) {
+                    process.stderr.write('[headless] Error: --max-restarts must be a non-negative integer\n');
+                    process.exit(1);
+                }
+            }
+            else if (arg === '--supervised') {
+                options.supervised = true;
+                options.json = true; // supervised implies json
+            }
+            else if (arg === '--response-timeout' && i + 1 < args.length) {
+                options.responseTimeout = parseInt(args[++i], 10);
+                if (Number.isNaN(options.responseTimeout) || options.responseTimeout <= 0) {
+                    process.stderr.write('[headless] Error: --response-timeout must be a positive integer (milliseconds)\n');
+                    process.exit(1);
+                }
+            }
         }
         else if (!positionalStarted) {
             positionalStarted = true;
@@ -70,12 +89,6 @@ export function parseHeadlessArgs(argv) {
     return options;
 }
 // ---------------------------------------------------------------------------
-// JSONL Helper
-// ---------------------------------------------------------------------------
-function serializeJsonLine(obj) {
-    return JSON.stringify(obj) + '\n';
-}
-// ---------------------------------------------------------------------------
 // Extension UI Auto-Responder
 // ---------------------------------------------------------------------------
 function handleExtensionUIRequest(event, writeToStdin) {
@@ -177,6 +190,7 @@ function isMilestoneReadyNotification(event) {
 // ---------------------------------------------------------------------------
 // Quick Command Detection
 // ---------------------------------------------------------------------------
+const FIRE_AND_FORGET_METHODS = new Set(['notify', 'setStatus', 'setWidget', 'setTitle', 'set_editor_text']);
 const QUICK_COMMANDS = new Set([
     'status', 'queue', 'history', 'hooks', 'export', 'stop', 'pause',
     'capture', 'skip', 'undo', 'knowledge', 'config', 'prefs',
@@ -187,6 +201,42 @@ function isQuickCommand(command) {
     return QUICK_COMMANDS.has(command);
 }
 // ---------------------------------------------------------------------------
+// Supervised Stdin Reader
+// ---------------------------------------------------------------------------
+function startSupervisedStdinReader(stdinWriter, client, onResponse) {
+    return attachJsonlLineReader(process.stdin, (line) => {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            process.stderr.write(`[headless] Warning: invalid JSON from orchestrator stdin, skipping\n`);
+            return;
+        }
+        const type = String(msg.type ?? '');
+        switch (type) {
+            case 'extension_ui_response':
+                stdinWriter(line + '\n');
+                if (typeof msg.id === 'string') {
+                    onResponse(msg.id);
+                }
+                break;
+            case 'prompt':
+                client.prompt(String(msg.message ?? ''));
+                break;
+            case 'steer':
+                client.steer(String(msg.message ?? ''));
+                break;
+            case 'follow_up':
+                client.followUp(String(msg.message ?? ''));
+                break;
+            default:
+                process.stderr.write(`[headless] Warning: unknown message type "${type}" from orchestrator stdin\n`);
+                break;
+        }
+    });
+}
+// ---------------------------------------------------------------------------
 // Main Orchestrator
 // ---------------------------------------------------------------------------
 // ---------------------------------------------------------------------------
@@ -220,8 +270,38 @@ function bootstrapGsdProject(basePath) {
     mkdirSync(join(gsdDir, 'runtime'), { recursive: true });
 }
 export async function runHeadless(options) {
+    const maxRestarts = options.maxRestarts ?? 3;
+    let restartCount = 0;
+    while (true) {
+        const result = await runHeadlessOnce(options, restartCount);
+        // Success or blocked — exit normally
+        if (result.exitCode === 0 || result.exitCode === 2) {
+            process.exit(result.exitCode);
+        }
+        // Crash/error — check if we should restart
+        if (restartCount >= maxRestarts) {
+            process.stderr.write(`[headless] Max restarts (${maxRestarts}) reached. Exiting.\n`);
+            process.exit(result.exitCode);
+        }
+        // Don't restart if SIGINT/SIGTERM was received
+        if (result.interrupted) {
+            process.exit(result.exitCode);
+        }
+        restartCount++;
+        const backoffMs = Math.min(5000 * restartCount, 30_000);
+        process.stderr.write(`[headless] Restarting in ${(backoffMs / 1000).toFixed(0)}s (attempt ${restartCount}/${maxRestarts})...\n`);
+        await new Promise(resolve => setTimeout(resolve, backoffMs));
+    }
+}
+async function runHeadlessOnce(options, restartCount) {
+    let interrupted = false;
     const startTime = Date.now();
     const isNewMilestone = options.command === 'new-milestone';
+    // Supervised mode cannot share stdin with --context -
+    if (options.supervised && options.context === '-') {
+        process.stderr.write('[headless] Error: --supervised cannot be used with --context - (both require stdin)\n');
+        process.exit(1);
+    }
     // For new-milestone, load context and bootstrap .gsd/ before spawning RPC child
     if (isNewMilestone) {
         if (!options.context && !options.contextText) {
@@ -297,6 +377,17 @@ export async function runHeadless(options) {
     }
     // Stdin writer for sending extension_ui_response to child
     let stdinWriter = null;
+    // Supervised mode state
+    const pendingResponseTimers = new Map();
+    let supervisedFallback = false;
+    let stopSupervisedReader = null;
+    const onStdinClose = () => {
+        supervisedFallback = true;
+        process.stderr.write('[headless] Warning: orchestrator stdin closed, falling back to auto-response\n');
+    };
+    if (options.supervised) {
+        process.stdin.on('close', onStdinClose);
+    }
     // Completion promise
     let resolveCompletion;
     const completionPromise = new Promise((resolve) => {
@@ -315,6 +406,8 @@ export async function runHeadless(options) {
             }, effectiveIdleTimeout);
         }
     }
+    // Precompute supervised response timeout
+    const responseTimeout = options.responseTimeout ?? 30_000;
     // Overall timeout
     const timeoutTimer = setTimeout(() => {
         process.stderr.write(`[headless] Timeout after ${options.timeout / 1000}s\n`);
@@ -349,7 +442,22 @@ export async function runHeadless(options) {
             if (isTerminalNotification(eventObj)) {
                 completed = true;
             }
-            handleExtensionUIRequest(eventObj, stdinWriter);
+            const method = String(eventObj.method ?? '');
+            const shouldSupervise = options.supervised && !supervisedFallback
+                && !FIRE_AND_FORGET_METHODS.has(method);
+            if (shouldSupervise) {
+                // Interactive request in supervised mode — let orchestrator respond
+                const eventId = String(eventObj.id ?? '');
+                const timer = setTimeout(() => {
+                    pendingResponseTimers.delete(eventId);
+                    handleExtensionUIRequest(eventObj, stdinWriter);
+                    process.stdout.write(JSON.stringify({ type: 'supervised_timeout', id: eventId, method }) + '\n');
+                }, responseTimeout);
+                pendingResponseTimers.set(eventId, timer);
+            }
+            else {
+                handleExtensionUIRequest(eventObj, stdinWriter);
+            }
             // If we detected a terminal notification, resolve after responding
             if (completed) {
                 exitCode = blocked ? 2 : 0;
@@ -369,6 +477,7 @@ export async function runHeadless(options) {
     // Signal handling
     const signalHandler = () => {
         process.stderr.write('\n[headless] Interrupted, stopping child process...\n');
+        interrupted = true;
         exitCode = 1;
         client.stop().finally(() => {
             clearTimeout(timeoutTimer);
@@ -399,6 +508,18 @@ export async function runHeadless(options) {
     stdinWriter = (data) => {
         internalProcess.stdin.write(data);
     };
+    // Start supervised stdin reader for orchestrator commands
+    if (options.supervised) {
+        stopSupervisedReader = startSupervisedStdinReader(stdinWriter, client, (id) => {
+            const timer = pendingResponseTimers.get(id);
+            if (timer) {
+                clearTimeout(timer);
+                pendingResponseTimers.delete(id);
+            }
+        });
+        // Ensure stdin is in flowing mode for JSONL reading
+        process.stdin.resume();
+    }
     // Detect child process crash
     internalProcess.on('exit', (code) => {
         if (!completed) {
@@ -451,6 +572,10 @@ export async function runHeadless(options) {
     clearTimeout(timeoutTimer);
     if (idleTimer)
         clearTimeout(idleTimer);
+    pendingResponseTimers.forEach((timer) => clearTimeout(timer));
+    pendingResponseTimers.clear();
+    stopSupervisedReader?.();
+    process.stdin.removeListener('close', onStdinClose);
     process.removeListener('SIGINT', signalHandler);
     process.removeListener('SIGTERM', signalHandler);
     await client.stop();
@@ -460,6 +585,9 @@ export async function runHeadless(options) {
     process.stderr.write(`[headless] Status: ${status}\n`);
     process.stderr.write(`[headless] Duration: ${duration}s\n`);
     process.stderr.write(`[headless] Events: ${totalEvents} total, ${toolCallCount} tool calls\n`);
+    if (restartCount > 0) {
+        process.stderr.write(`[headless] Restarts: ${restartCount}\n`);
+    }
     // On failure, print last 5 events for diagnostics
     if (exitCode !== 0) {
         const lastFive = recentEvents.slice(-5);
@@ -470,5 +598,5 @@ export async function runHeadless(options) {
             }
         }
     }
-    process.exit(exitCode);
+    return { exitCode, interrupted };
 }

package/dist/help-text.js

@@ -38,6 +38,8 @@ const SUBCOMMAND_HELP = {
         '  --timeout N          Overall timeout in ms (default: 300000)',
         '  --json               JSONL event stream to stdout',
         '  --model ID           Override model',
+        '  --supervised           Forward interactive UI requests to orchestrator via stdout/stdin',
+        '  --response-timeout N   Timeout (ms) for orchestrator response (default: 30000)',
         '',
         'Commands:',
         '  auto                 Run all queued units continuously (default)',
@@ -59,6 +61,7 @@ const SUBCOMMAND_HELP = {
         '  gsd headless new-milestone --context spec.md    Create milestone from file',
         '  cat spec.md | gsd headless new-milestone --context -   From stdin',
         '  gsd headless new-milestone --context spec.md --auto    Create + auto-execute',
+        '  gsd headless --supervised auto                     Supervised orchestrator mode',
         '',
         'Exit codes: 0 = complete, 1 = error/timeout, 2 = blocked',
     ].join('\n'),

package/dist/loader.js

@@ -3,7 +3,7 @@
 // Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 import { fileURLToPath } from 'url';
 import { dirname, resolve, join, delimiter } from 'path';
-import { existsSync, readFileSync, readdirSync, mkdirSync, symlinkSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, mkdirSync, symlinkSync, cpSync } from 'fs';
 // Fast-path: handle --version/-v and --help/-h before importing any heavy
 // dependencies. This avoids loading the entire pi-coding-agent barrel import
 // (~1s) just to print a version string.
@@ -137,8 +137,12 @@ if (process.env.HTTP_PROXY || process.env.HTTPS_PROXY || process.env.http_proxy
     const { EnvHttpProxyAgent, setGlobalDispatcher } = await import('undici');
     setGlobalDispatcher(new EnvHttpProxyAgent());
 }
-// Ensure workspace packages are linked before importing cli.js (which imports @gsd/*).
+// Ensure workspace packages are linked (or copied on Windows) before importing
+// cli.js (which imports @gsd/*).
 // npm postinstall handles this normally, but npx --ignore-scripts skips postinstall.
+// On Windows without Developer Mode or admin rights, symlinkSync will throw even for
+// 'junction' type — so we fall back to cpSync (a full directory copy) which works
+// everywhere without elevated permissions.
 const gsdScopeDir = join(gsdNodeModules, '@gsd');
 const packagesDir = join(gsdRoot, 'packages');
 const wsPackages = ['native', 'pi-agent-core', 'pi-ai', 'pi-coding-agent', 'pi-tui'];
@@ -148,14 +152,39 @@ try {
     for (const pkg of wsPackages) {
         const target = join(gsdScopeDir, pkg);
         const source = join(packagesDir, pkg);
-        if (existsSync(source) && !existsSync(target)) {
+        if (!existsSync(source) || existsSync(target))
+            continue;
+        try {
+            symlinkSync(source, target, 'junction');
+        }
+        catch {
+            // Symlink failed (common on Windows without Developer Mode / admin).
+            // Fall back to a directory copy — slower on first run but universally works.
             try {
-                symlinkSync(source, target, 'junction');
+                cpSync(source, target, { recursive: true });
             }
             catch { /* non-fatal */ }
         }
     }
 }
 catch { /* non-fatal */ }
+// Validate critical workspace packages are resolvable. If still missing after the
+// symlink+copy attempts, emit a clear diagnostic instead of a cryptic
+// ERR_MODULE_NOT_FOUND from deep inside cli.js.
+const criticalPackages = ['pi-coding-agent'];
+const missingPackages = criticalPackages.filter(pkg => !existsSync(join(gsdScopeDir, pkg)));
+if (missingPackages.length > 0) {
+    const missing = missingPackages.map(p => `@gsd/${p}`).join(', ');
+    process.stderr.write(`\nError: GSD installation is broken — missing packages: ${missing}\n\n` +
+        `This is usually caused by one of:\n` +
+        `  • An outdated version installed from npm (run: npm install -g gsd-pi@latest)\n` +
+        `  • The packages/ directory was excluded from the installed tarball\n` +
+        `  • A filesystem error prevented linking or copying the workspace packages\n\n` +
+        `Fix it by reinstalling:\n\n` +
+        `  npm install -g gsd-pi@latest\n\n` +
+        `If the issue persists, please open an issue at:\n` +
+        `  https://github.com/gsd-build/gsd-2/issues\n`);
+    process.exit(1);
+}
 // Dynamic import defers ESM evaluation — config.js will see PI_PACKAGE_DIR above
 await import('./cli.js');

package/dist/resources/extensions/bg-shell/index.ts

@@ -52,6 +52,7 @@ import {
 	getGroupStatus,
 	pruneDeadProcesses,
 	cleanupAll,
+	cleanupSessionProcesses,
 	persistManifest,
 	loadManifest,
 	pushAlert,
@@ -71,7 +72,7 @@ import { toPosixPath } from "../shared/path-display.js";
 // ── Re-exports for consumers ───────────────────────────────────────────────
 
 export type { ProcessStatus, ProcessType, BgProcess, BgProcessInfo, OutputDigest, OutputLine, ProcessEvent } from "./types.js";
-export { processes, startProcess, killProcess, restartProcess, cleanupAll } from "./process-manager.js";
+export { processes, startProcess, killProcess, restartProcess, cleanupAll, cleanupSessionProcesses } from "./process-manager.js";
 export { generateDigest, getHighlights, getOutput, formatDigestText } from "./output-formatter.js";
 export { waitForReady, probePort } from "./readiness-detector.js";
 export { sendAndWait, runOnSession, queryShellEnv } from "./interaction.js";
@@ -136,7 +137,13 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	// Session switch resets the agent's context.
-	pi.on("session_switch", async () => {
+	pi.on("session_switch", async (event, ctx) => {
+		latestCtx = ctx;
+		if (event.reason === "new" && event.previousSessionFile) {
+			await cleanupSessionProcesses(event.previousSessionFile);
+			syncLatestCtxCwd();
+			if (latestCtx) persistManifest(latestCtx.cwd);
+		}
 		buildProcessStateAlert("Session was switched.");
 	});
 
@@ -232,6 +239,7 @@ export default function (pi: ExtensionAPI) {
 			"Use 'run' to execute a command on a persistent shell session and block until it completes — returns structured output + exit code. Shell state (env vars, cwd, virtualenvs) persists across runs.",
 			"Use 'send_and_wait' for interactive CLIs: send input and wait for expected output pattern.",
 			"Use 'env' to check the current working directory and active environment variables of a shell session — useful after cd, source, or export commands.",
+			"Background processes are session-scoped by default: a new session reaps them unless you set persist_across_sessions:true.",
 			"Use 'restart' to kill and relaunch with the same config — preserves restart count.",
 			"Background processes are auto-classified (server/build/test/watcher) based on the command.",
 			"Process crashes and errors are automatically surfaced as alerts at the start of your next turn — you don't need to poll.",
@@ -300,6 +308,12 @@ export default function (pi: ExtensionAPI) {
 			group: Type.Optional(
 				Type.String({ description: "Group name for related processes (for start, group_status)" }),
 			),
+			persist_across_sessions: Type.Optional(
+				Type.Boolean({
+					description: "Keep this process running after a new session starts. Default: false.",
+					default: false,
+				}),
+			),
 		}),
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
@@ -318,6 +332,8 @@ export default function (pi: ExtensionAPI) {
 					const bg = startProcess({
 						command: params.command,
 						cwd: ctx.cwd,
+						ownerSessionFile: ctx.sessionManager.getSessionFile() ?? null,
+						persistAcrossSessions: params.persist_across_sessions ?? false,
 						label: params.label,
 						type: params.type as ProcessType | undefined,
 						readyPattern: params.ready_pattern,
@@ -341,6 +357,7 @@ export default function (pi: ExtensionAPI) {
 					text += `  cwd: ${toPosixPath(bg.cwd)}`;
 
 					if (bg.group) text += `\n  group: ${bg.group}`;
+					if (bg.persistAcrossSessions) text += `\n  persist_across_sessions: true`;
 					if (bg.readyPort) text += `\n  ready_port: ${bg.readyPort}`;
 					if (bg.readyPattern) text += `\n  ready_pattern: ${bg.readyPattern}`;
 					if (bg.ports.length > 0) text += `\n  detected ports: ${bg.ports.join(", ")}`;

package/dist/resources/extensions/bg-shell/process-manager.ts

@@ -67,6 +67,8 @@ export function getInfo(p: BgProcess): BgProcessInfo {
 		label: p.label,
 		command: p.command,
 		cwd: p.cwd,
+		ownerSessionFile: p.ownerSessionFile,
+		persistAcrossSessions: p.persistAcrossSessions,
 		startedAt: p.startedAt,
 		alive: p.alive,
 		exitCode: p.exitCode,
@@ -138,6 +140,8 @@ export function startProcess(opts: StartOptions): BgProcess {
 		label: opts.label || command.slice(0, 60),
 		command,
 		cwd: opts.cwd,
+		ownerSessionFile: opts.ownerSessionFile ?? null,
+		persistAcrossSessions: opts.persistAcrossSessions ?? false,
 		startedAt: Date.now(),
 		proc,
 		output: [],
@@ -170,6 +174,8 @@ export function startProcess(opts: StartOptions): BgProcess {
 			cwd: opts.cwd,
 			label: opts.label || command.slice(0, 60),
 			processType,
+			ownerSessionFile: opts.ownerSessionFile ?? null,
+			persistAcrossSessions: opts.persistAcrossSessions ?? false,
 			readyPattern: opts.readyPattern || null,
 			readyPort: opts.readyPort || null,
 			group: opts.group || null,
@@ -312,6 +318,8 @@ export async function restartProcess(id: string): Promise<BgProcess | null> {
 		cwd: config.cwd,
 		label: config.label,
 		type: config.processType,
+		ownerSessionFile: config.ownerSessionFile,
+		persistAcrossSessions: config.persistAcrossSessions,
 		readyPattern: config.readyPattern || undefined,
 		readyPort: config.readyPort || undefined,
 		group: config.group || undefined,
@@ -367,6 +375,41 @@ export function cleanupAll(): void {
 	processes.clear();
 }
 
+async function waitForProcessExit(bg: BgProcess, timeoutMs: number): Promise<boolean> {
+	if (!bg.alive) return true;
+	await new Promise<void>((resolve) => {
+		const done = () => resolve();
+		const timer = setTimeout(done, timeoutMs);
+		bg.proc.once("exit", () => {
+			clearTimeout(timer);
+			resolve();
+		});
+	});
+	return !bg.alive;
+}
+
+export async function cleanupSessionProcesses(
+	sessionFile: string,
+	options?: { graceMs?: number },
+): Promise<string[]> {
+	const graceMs = Math.max(0, options?.graceMs ?? 300);
+	const matches = Array.from(processes.values()).filter(
+		(bg) => bg.alive && !bg.persistAcrossSessions && bg.ownerSessionFile === sessionFile,
+	);
+	if (matches.length === 0) return [];
+
+	for (const bg of matches) {
+		killProcess(bg.id, "SIGTERM");
+	}
+	if (graceMs > 0) {
+		await Promise.all(matches.map((bg) => waitForProcessExit(bg, graceMs)));
+	}
+	for (const bg of matches) {
+		if (bg.alive) killProcess(bg.id, "SIGKILL");
+	}
+	return matches.map((bg) => bg.id);
+}
+
 // ── Persistence ────────────────────────────────────────────────────────────
 
 export function getManifestPath(cwd: string): string {
@@ -384,6 +427,8 @@ export function persistManifest(cwd: string): void {
 				label: p.label,
 				command: p.command,
 				cwd: p.cwd,
+				ownerSessionFile: p.ownerSessionFile,
+				persistAcrossSessions: p.persistAcrossSessions,
 				startedAt: p.startedAt,
 				processType: p.processType,
 				group: p.group,