gsd-pi 2.44.0 → 2.45.0-dev.1afbdaa

package/src/resources/extensions/gsd/write-intercept.ts

@@ -0,0 +1,90 @@
+// GSD Extension — Write Intercept for Agent State File Blocks
+// Detects agent attempts to write authoritative state files and returns
+// an error directing the agent to use the engine tool API instead.
+
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Patterns matching authoritative .gsd/ state files that agents must NOT write directly.
+ *
+ * Only STATE.md is blocked — it is purely engine-rendered from DB state.
+ * All other .gsd/ files are agent-authored content that agents create and
+ * update during discuss, plan, and execute phases:
+ * - REQUIREMENTS.md — agents create during discuss, read during planning
+ * - PROJECT.md — agents create during discuss, update at milestone close
+ * - ROADMAP.md / PLAN.md — agents create during planning, engine renders checkboxes
+ * - SUMMARY.md, KNOWLEDGE.md, CONTEXT.md — non-authoritative content
+ */
+const BLOCKED_PATTERNS: RegExp[] = [
+  // STATE.md is the only purely engine-rendered file.
+  // Case-insensitive to prevent bypass on macOS (case-insensitive APFS).
+  // (^|[/\\]) matches both absolute paths (/project/.gsd/…) and bare relative
+  // paths (.gsd/STATE.md) so a path without a leading separator is also blocked.
+  /(^|[/\\])\.gsd[/\\]STATE\.md$/i,
+  // Also match resolved symlink paths under ~/.gsd/projects/ (Pitfall #6)
+  /(^|[/\\])\.gsd[/\\]projects[/\\][^/\\]+[/\\]STATE\.md$/i,
+];
+
+/**
+ * Bash command patterns that target STATE.md.
+ * Covers common shell write patterns: redirect, tee, cp, mv, sed -i, etc.
+ */
+const BASH_STATE_PATTERNS: RegExp[] = [
+  // Redirect/pipe writes: > STATE.md, >> STATE.md, >| STATE.md
+  /[>|]+\s*\S*STATE\.md/i,
+  // tee to STATE.md
+  /\btee\b.*STATE\.md/i,
+  // cp/mv targeting STATE.md
+  /\b(cp|mv)\b.*STATE\.md/i,
+  // sed -i editing STATE.md
+  /\bsed\b.*-i.*STATE\.md/i,
+  // dd output to STATE.md
+  /\bdd\b.*of=\S*STATE\.md/i,
+];
+
+/**
+ * Tests whether the given file path matches a blocked authoritative .gsd/ state file.
+ * Resolves `..` segments via path.resolve() and attempts realpathSync for symlinks.
+ */
+export function isBlockedStateFile(filePath: string): boolean {
+  // Check raw path first
+  if (matchesBlockedPattern(filePath)) return true;
+
+  // Resolve ".." segments (works even for non-existing files)
+  const resolved = resolve(filePath);
+  if (resolved !== filePath && matchesBlockedPattern(resolved)) return true;
+
+  // Also try symlink resolution — file may not exist yet, so wrap in try/catch
+  try {
+    const realpath = realpathSync(filePath);
+    if (realpath !== filePath && realpath !== resolved && matchesBlockedPattern(realpath)) return true;
+  } catch {
+    // File doesn't exist yet — path matching above is sufficient
+  }
+
+  return false;
+}
+
+/**
+ * Tests whether a bash command appears to target STATE.md for writing.
+ */
+export function isBashWriteToStateFile(command: string): boolean {
+  return BASH_STATE_PATTERNS.some((pattern) => pattern.test(command));
+}
+
+function matchesBlockedPattern(path: string): boolean {
+  return BLOCKED_PATTERNS.some((pattern) => pattern.test(path));
+}
+
+/**
+ * Error message returned when an agent attempts to directly write an authoritative .gsd/ state file.
+ * Directs the agent to use engine tool calls instead.
+ */
+export const BLOCKED_WRITE_ERROR = `Direct writes to .gsd/STATE.md are blocked. Use engine tool calls instead:
+- To complete a task: call gsd_complete_task(milestone_id, slice_id, task_id, summary)
+- To complete a slice: call gsd_complete_slice(milestone_id, slice_id, summary, uat_result)
+- To save a decision: call gsd_save_decision(scope, decision, choice, rationale)
+- To start a task: call gsd_start_task(milestone_id, slice_id, task_id)
+- To record verification: call gsd_record_verification(milestone_id, slice_id, task_id, evidence)
+- To report a blocker: call gsd_report_blocker(milestone_id, slice_id, task_id, description)`;

package/src/resources/extensions/mcp-client/index.ts

@@ -213,6 +213,26 @@ function formatToolList(serverName: string, tools: McpToolSchema[]): string {
 	return lines.join("\n");
 }
 
+// ─── Status helper (consumed by /gsd mcp) ─────────────────────────────────────
+
+/**
+ * Return the live connection status for a named MCP server.
+ * Safe to call even when the server has never been connected.
+ */
+export function getConnectionStatus(name: string): {
+	connected: boolean;
+	tools: string[];
+	error?: string;
+} {
+	const conn = connections.get(name);
+	const cached = toolCache.get(name);
+	return {
+		connected: !!conn,
+		tools: cached ? cached.map((t) => t.name) : [],
+		error: undefined,
+	};
+}
+
 // ─── Extension ────────────────────────────────────────────────────────────────
 
 export default function (pi: ExtensionAPI) {

package/src/resources/extensions/voice/index.ts

@@ -4,9 +4,9 @@ import type { AssistantMessage } from "@gsd/pi-ai";
 import { isKeyRelease, Key, matchesKey, truncateToWidth, visibleWidth } from "@gsd/pi-tui";
 import { spawn, execFileSync, type ChildProcess } from "node:child_process";
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import * as readline from "node:readline";
+import { linuxPython, diagnoseSounddeviceError, ensureVoiceVenv, VOICE_VENV_PYTHON } from "./linux-ready.js";
 
 const __extensionDir = import.meta.dirname!;
 const SWIFT_SRC = path.join(__extensionDir, "speech-recognizer.swift");
@@ -15,19 +15,6 @@ const PYTHON_SCRIPT = path.join(__extensionDir, "speech-recognizer.py");
 
 const IS_DARWIN = process.platform === "darwin";
 const IS_LINUX = process.platform === "linux";
-const VOICE_VENV_PYTHON = path.join(
-	process.env.HOME || process.env.USERPROFILE || os.homedir(),
-	".gsd",
-	"voice-venv",
-	"bin",
-	"python3",
-);
-
-/** Return the python3 binary path — prefer venv if it exists, else system. */
-function linuxPython(): string {
-	if (fs.existsSync(VOICE_VENV_PYTHON)) return VOICE_VENV_PYTHON;
-	return "python3";
-}
 
 function ensureBinary(): boolean {
 	if (fs.existsSync(RECOGNIZER_BIN)) return true;
@@ -69,17 +56,20 @@ function ensureLinuxReady(ctx: ExtensionContext): boolean {
 		});
 	} catch (err: unknown) {
 		const stderr = (err as { stderr?: Buffer })?.stderr?.toString() ?? "";
-		if (stderr.includes("sounddevice") || stderr.includes("PortAudio") || stderr.includes("portaudio")) {
-			ctx.ui.notify("Voice: install libportaudio2 with: sudo apt install libportaudio2", "error");
-		} else if (stderr.includes("No module") || stderr.includes("ModuleNotFoundError")) {
-			// Deps missing — the Python script handles auto-install on first run,
-			// so we let it through. The script's own ensure_deps() will pip install.
-			ctx.ui.notify("Voice: installing dependencies on first run — this may take a moment", "info");
+		const diagnosis = diagnoseSounddeviceError(stderr);
+
+		if (diagnosis === "missing-module") {
+			// Module not installed — auto-create venv (handles PEP 668 systems
+			// where system pip is blocked). See #2403.
+			if (!ensureVoiceVenv({ notify: (msg, level) => ctx.ui.notify(msg, level) })) {
+				return false;
+			}
 			linuxReady = true;
 			return true;
+		} else if (diagnosis === "missing-portaudio") {
+			ctx.ui.notify("Voice: install libportaudio2 with: sudo apt install libportaudio2", "error");
 		} else {
 			ctx.ui.notify(`Voice: dependency check failed — ${stderr.split("\n")[0] || "unknown error"}`, "error");
-			return false;
 		}
 		return false;
 	}

package/src/resources/extensions/voice/linux-ready.ts

@@ -0,0 +1,87 @@
+/**
+ * linux-ready.ts — Linux voice readiness logic (extracted for testability).
+ *
+ * Handles:
+ *   - Detecting system vs venv python3
+ *   - Diagnosing sounddevice import errors (portaudio vs missing module)
+ *   - Auto-creating venv on PEP 668 systems
+ */
+
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export const VOICE_VENV_DIR = path.join(
+	process.env.HOME || process.env.USERPROFILE || os.homedir(),
+	".gsd",
+	"voice-venv",
+);
+export const VOICE_VENV_PYTHON = path.join(VOICE_VENV_DIR, "bin", "python3");
+
+/** Return the python3 binary path — prefer venv if it exists, else system. */
+export function linuxPython(): string {
+	if (fs.existsSync(VOICE_VENV_PYTHON)) return VOICE_VENV_PYTHON;
+	return "python3";
+}
+
+/**
+ * Diagnose a sounddevice import error from its stderr output.
+ *
+ * Returns:
+ *   - "missing-module"  — sounddevice python package not installed
+ *   - "missing-portaudio" — libportaudio2 native library not found
+ *   - "unknown"         — unrecognized error
+ *
+ * IMPORTANT: Check "No module" / "ModuleNotFoundError" BEFORE checking for the
+ * word "sounddevice", because `ModuleNotFoundError: No module named 'sounddevice'`
+ * contains both strings. The more specific check must come first.
+ */
+export function diagnoseSounddeviceError(stderr: string): "missing-module" | "missing-portaudio" | "unknown" {
+	// Check for missing Python module FIRST — the error message
+	// "ModuleNotFoundError: No module named 'sounddevice'" contains the word
+	// "sounddevice", so the old order (checking "sounddevice" first) was wrong.
+	if (stderr.includes("No module") || stderr.includes("ModuleNotFoundError")) {
+		return "missing-module";
+	}
+	// Now check for native portaudio library issues.
+	if (stderr.includes("PortAudio") || stderr.includes("portaudio")) {
+		return "missing-portaudio";
+	}
+	return "unknown";
+}
+
+export interface ReadinessCallbacks {
+	notify: (message: string, level: "info" | "error") => void;
+	/** Override for execFileSync — for testing. Uses execFileSync (safe, no shell). */
+	execFile?: typeof execFileSync;
+	/** Override for fs.existsSync — for testing */
+	exists?: typeof fs.existsSync;
+}
+
+/**
+ * Auto-create the voice venv if it doesn't exist.
+ * Uses execFileSync internally (no shell, safe from injection).
+ *
+ * Returns true on success, false on failure.
+ */
+export function ensureVoiceVenv(cb: ReadinessCallbacks): boolean {
+	const exists = cb.exists ?? fs.existsSync;
+	const execFile = cb.execFile ?? execFileSync;
+
+	if (exists(VOICE_VENV_PYTHON)) return true;
+
+	cb.notify("Voice: setting up Python environment — one-time setup", "info");
+	try {
+		execFile("python3", ["-m", "venv", VOICE_VENV_DIR], { timeout: 30000 });
+		execFile(
+			path.join(VOICE_VENV_DIR, "bin", "pip"),
+			["install", "sounddevice", "requests", "--quiet"],
+			{ timeout: 120000 },
+		);
+		return true;
+	} catch {
+		cb.notify("Voice: failed to create Python venv — run: python3 -m venv ~/.gsd/voice-venv", "error");
+		return false;
+	}
+}

package/src/resources/extensions/voice/tests/linux-ready.test.ts

@@ -0,0 +1,124 @@
+/**
+ * linux-ready.test.ts — Tests for Linux voice readiness logic (#2403).
+ *
+ * Covers:
+ *   - diagnoseSounddeviceError branch ordering (ModuleNotFoundError must NOT
+ *     match the portaudio branch, even though it contains "sounddevice")
+ *   - ensureVoiceVenv auto-creation
+ *   - linuxPython venv detection
+ */
+
+import { createTestContext } from "../../gsd/tests/test-helpers.ts";
+import { diagnoseSounddeviceError, ensureVoiceVenv } from "../linux-ready.ts";
+
+const { assertEq, assertTrue, report } = createTestContext();
+
+function main(): void {
+	// ── diagnoseSounddeviceError ──────────────────────────────────────────
+
+	// The critical regression: "ModuleNotFoundError: No module named 'sounddevice'"
+	// contains the word "sounddevice", so the old code matched the portaudio branch.
+	console.log("\n=== diagnoseSounddeviceError: ModuleNotFoundError must return missing-module ===");
+	{
+		const stderr = "Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nModuleNotFoundError: No module named 'sounddevice'";
+		assertEq(diagnoseSounddeviceError(stderr), "missing-module",
+			"ModuleNotFoundError for sounddevice should be 'missing-module', not 'missing-portaudio'");
+	}
+
+	console.log("\n=== diagnoseSounddeviceError: 'No module named sounddevice' variant ===");
+	{
+		const stderr = "ImportError: No module named sounddevice";
+		assertEq(diagnoseSounddeviceError(stderr), "missing-module",
+			"'No module' substring should return missing-module");
+	}
+
+	console.log("\n=== diagnoseSounddeviceError: actual portaudio error ===");
+	{
+		const stderr = "OSError: PortAudio library not found";
+		assertEq(diagnoseSounddeviceError(stderr), "missing-portaudio",
+			"PortAudio library error should return missing-portaudio");
+	}
+
+	console.log("\n=== diagnoseSounddeviceError: lowercase portaudio error ===");
+	{
+		const stderr = "OSError: libportaudio.so.2: cannot open shared object file: No such file or directory";
+		assertEq(diagnoseSounddeviceError(stderr), "missing-portaudio",
+			"lowercase portaudio error should return missing-portaudio");
+	}
+
+	console.log("\n=== diagnoseSounddeviceError: unrelated error ===");
+	{
+		const stderr = "SyntaxError: invalid syntax";
+		assertEq(diagnoseSounddeviceError(stderr), "unknown",
+			"unrelated error should return unknown");
+	}
+
+	console.log("\n=== diagnoseSounddeviceError: empty stderr ===");
+	{
+		assertEq(diagnoseSounddeviceError(""), "unknown",
+			"empty stderr should return unknown");
+	}
+
+	// ── ensureVoiceVenv ──────────────────────────────────────────────────
+
+	console.log("\n=== ensureVoiceVenv: returns true when venv already exists ===");
+	{
+		const notifications: string[] = [];
+		const result = ensureVoiceVenv({
+			notify: (msg) => notifications.push(msg),
+			exists: () => true,
+			execFile: (() => Buffer.from("")) as any,
+		});
+		assertTrue(result, "should return true when venv exists");
+		assertEq(notifications.length, 0, "should not notify when venv exists");
+	}
+
+	console.log("\n=== ensureVoiceVenv: creates venv when missing ===");
+	{
+		const notifications: string[] = [];
+		const commands: string[][] = [];
+		let existsCalled = false;
+
+		const result = ensureVoiceVenv({
+			notify: (msg) => notifications.push(msg),
+			exists: () => { existsCalled = true; return false; },
+			execFile: ((cmd: string, args: string[]) => {
+				commands.push([cmd, ...args]);
+				return Buffer.from("");
+			}) as any,
+		});
+
+		assertTrue(result, "should return true after venv creation");
+		assertTrue(existsCalled, "should check if venv exists");
+		assertEq(commands.length, 2, "should run 2 commands (venv + pip)");
+		assertTrue(commands[0][0] === "python3", "first command is python3");
+		assertTrue(commands[0].includes("-m") && commands[0].includes("venv"),
+			"first command creates venv");
+		assertTrue(commands[1][0].endsWith("bin/pip"), "second command is pip");
+		assertTrue(commands[1].includes("sounddevice"), "pip installs sounddevice");
+		assertTrue(commands[1].includes("requests"), "pip installs requests");
+		assertTrue(notifications[0].includes("one-time setup"),
+			"notifies about one-time setup");
+	}
+
+	console.log("\n=== ensureVoiceVenv: returns false and notifies on failure ===");
+	{
+		const notifications: Array<{ msg: string; level: string }> = [];
+
+		const result = ensureVoiceVenv({
+			notify: (msg, level) => notifications.push({ msg, level }),
+			exists: () => false,
+			execFile: (() => { throw new Error("externally-managed-environment"); }) as any,
+		});
+
+		assertTrue(!result, "should return false on failure");
+		const errorNotif = notifications.find(n => n.level === "error");
+		assertTrue(errorNotif !== undefined, "should emit error notification");
+		assertTrue(errorNotif!.msg.includes("python3 -m venv"),
+			"error message should suggest manual venv creation");
+	}
+
+	report();
+}
+
+main();