gsd-pi 2.46.1 → 2.47.0

package/README.md

@@ -25,40 +25,55 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.44.0
+## What's New in v2.46.0
 
-### New Features
+### Single-Writer State Engine
 
-- **Non-API-key provider extensions** — support for provider extensions like Claude Code CLI that don't require traditional API keys. (#2382)
-- **Docker sandbox template** — official Docker template for running GSD auto mode in an isolated container. (#2360)
-- **Per-prompt token cost display** — opt-in `show_token_cost` preference shows per-prompt and cumulative session cost in the footer. (#2357)
-- **"Change project root" in web UI** — switch project directories from the web interface without restarting. (#2355)
-- **DB-backed planning tools** — write-side state transitions now use atomic SQLite tool calls instead of markdown mutation, improving reliability and enabling structured queries. (#2141)
+The biggest architectural change since DB-backed planning tools. The single-writer engine enforces disciplined state transitions through three iterations:
 
-### Key Fixes
+- **v2 — discipline layer** — adds a write-side discipline layer on top of the DB architecture, ensuring all state mutations flow through controlled tool calls.
+- **v3 — state machine guards, actor identity, reversibility** — introduces formal state machine guards, tracks which actor (human vs agent) initiated each transition, and makes transitions reversible.
+- **Hardened** — closes TOCTOU race conditions, intercepts bypass attempts, and resolves status inconsistencies.
+
+All prompts are now aligned with the single-writer tool API, and a new **workflow-logger** is wired into the engine, tool, manifest, and reconcile paths for full observability. (#2494)
 
-- **Post-migration cleanup** — pragmas, rollbacks, tool gaps, and stale code cleaned up after DB migration. (#2410)
-- **Planning data loss prevention** — destructive upsert and post-unit re-import no longer overwrite planning data. (#2370)
-- **Memory and resource leaks** — fixes across TUI, LSP, DB, and automation subsystems. (#2314)
-- **DECISIONS.md preservation** — freeform content in DECISIONS.md is no longer overwritten on decision save. (#2319)
-- **Auto-stash before squash merge** — dirty files are automatically stashed before merge, with filenames surfaced in errors. (#2298)
-- **Extension TypeScript detection** — `.js` extension files containing TypeScript syntax are detected with a suggestion to rename. (#2386)
+### v2.45.0 — New Commands and Capabilities
 
-### v2.43.0 Highlights
+- **`/gsd rethink`** — conversational project reorganization. Rethink your milestone structure, slice decomposition, or overall approach through guided discussion. (#2459)
+- **`/gsd mcp`** — MCP server status and connectivity. Check which MCP servers are configured, connected, and healthy. (#2362)
+- **Complete offline mode** — GSD now works fully offline with local models. (#2429)
+- **Global KNOWLEDGE.md injection** — `~/.gsd/agent/KNOWLEDGE.md` is injected into the system prompt, so cross-project knowledge persists globally. (#2331)
+- **Mobile-responsive web UI** — the browser interface now works on phones and tablets. (#2354)
+- **DB tool previews** — `renderCall`/`renderResult` previews on DB tools show what each tool call does before and after execution. (#2273)
+- **Message timestamps** — user and assistant messages now include timestamps. (#2368)
 
-- **Forensics dedup** — opt-in duplicate detection before issue creation. (#2105)
-- **Fast service tier outside auto-mode** — `/gsd fast` now applies in interactive sessions too. (#2126)
-- **Startup optimizations** — pre-compiled extensions, compile cache, and batch discovery for faster boot. (#2125)
-- **Stale process cleanup** — web server kills stale process before launch to prevent EADDRINUSE. (#2034)
+### Key Changes
 
-### v2.42.0 Highlights
+- **Default isolation mode changed to `none`** — `git.isolation` now defaults to `none` instead of `worktree`. Projects that rely on worktree isolation should set `git.isolation: worktree` explicitly in preferences. (#2481)
+- **Startup checks** — GSD now validates Node.js version and git availability at startup, with clear error messages. (#2463)
+- **Worktree lifecycle journaling** — worktree create, switch, merge, and remove events are recorded in the event journal. (#2486)
+- **Milestone verification gate** — milestone completion is blocked when verification fails, preventing premature closure. (#2500)
+
+### Key Fixes
 
-- **Declarative workflow engine** — define YAML workflows that execute through auto-loop, enabling repeatable multi-step automations without code. (#2024)
-- **Unified rule registry & event journal** — centralized rule registry, event journal with query tool, and standardized tool naming convention. (#1928)
-- **PR risk checker** — CI classifies changed files by system area and surfaces risk level on pull requests. (#1930)
-- **`/gsd fast`** — toggle service tier for supported models, enabling prioritized API routing for faster responses. (#1862)
-- **Web mode CLI flags** — `--host`, `--port`, and `--allowed-origins` flags give full control over the web server bind address and CORS policy. (#1873)
-- **ADR attribution** — architecture decision records now distinguish human, agent, and collaborative authorship. (#1830)
+- **Auto-mode stability** — recovery attempts reset on unit re-dispatch (#2424), survivor branch recovery handles `phase=complete` (#2427), and auto mode stops on real merge conflicts (#2428).
+- **Supervision timeouts** — now respect task `est:` annotations, so complex tasks get proportionally longer timeouts. (#2434)
+- **`auto_pr: true` fixed** — three interacting bugs prevented auto-PR creation; all three are resolved. (#2433)
+- **Rich task plan preservation** — plans survive DB roundtrip without losing structured content. (#2453)
+- **Artifact truncation prevention** — `saveArtifactToDb` no longer overwrites larger files with truncated content. (#2447)
+- **Worktree teardown** — submodule state is detected and preserved during teardown (#2425), and worktree merge back to main works after `stopAuto` on milestone completion (#2430).
+- **Windows portability** — `retentionDays=0` handling and CRLF fixes on Windows. (#2460)
+- **Voice on Linux** — misleading portaudio error on PEP 668 systems replaced with actionable guidance. (#2407)
+
+### Previous highlights (v2.42–v2.44)
+
+- **Non-API-key provider extensions** — support for Claude Code CLI and similar providers. (#2382)
+- **Docker sandbox template** — official Docker template for isolated auto mode. (#2360)
+- **DB-backed planning tools** — write-side state transitions use atomic SQLite tool calls. (#2141)
+- **Declarative workflow engine** — YAML workflows through auto-loop. (#2024)
+- **`/gsd fast`** — toggle service tier for prioritized API routing. (#1862)
+- **Forensics dedup** — duplicate detection before issue creation. (#2105)
+- **Startup optimizations** — pre-compiled extensions, compile cache, batch discovery. (#2125)
 
 ---
 
@@ -138,7 +153,7 @@ See the full [Changelog](./CHANGELOG.md) for all 70+ fixes in this release.
 
 ## Documentation
 
-Full documentation is available in the [`docs/`](./docs/) directory:
+Full documentation is available at **[gsd.build](https://gsd.build)** (powered by Mintlify) and in the [`docs/`](./docs/) directory:
 
 - **[Getting Started](./docs/getting-started.md)** — install, first run, basic usage
 - **[Auto Mode](./docs/auto-mode.md)** — autonomous execution deep-dive
@@ -260,7 +275,7 @@ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`,
 
 2. **Context pre-loading** — The dispatch prompt includes inlined task plans, slice plans, prior task summaries, dependency summaries, roadmap excerpts, and decisions register. The LLM starts with everything it needs instead of spending tool calls reading files.
 
-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.
+3. **Git isolation** — When `git.isolation` is set to `worktree` or `branch`, each milestone runs on its own `milestone/<MID>` branch (in a worktree or in-place). 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. The default is `none` (work on the current branch), configurable via preferences.
 
 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. In headless mode, crashes trigger automatic restart with exponential backoff (default 3 attempts).
 
@@ -396,6 +411,8 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd stop`             | Stop auto mode gracefully                                       |
 | `/gsd steer`            | Hard-steer plan documents during execution                      |
 | `/gsd discuss`          | Discuss architecture and decisions (works alongside auto mode)  |
+| `/gsd rethink`          | Conversational project reorganization                           |
+| `/gsd mcp`              | MCP server status and connectivity                              |
 | `/gsd status`           | Progress dashboard                                              |
 | `/gsd queue`            | Queue future milestones (safe during auto mode)                 |
 | `/gsd prefs`            | Model selection, timeouts, budget ceiling                       |
@@ -543,7 +560,7 @@ auto_report: true
 | `skill_rules`          | Situational rules for skill routing                                                                   |
 | `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), `branch`, or `none` — disable worktree isolation for projects that don't need it           |
+| `git.isolation`        | `none` (default), `worktree`, or `branch` — enable worktree or branch isolation for milestone work               |
 | `git.manage_gitignore` | Set `false` to prevent GSD from modifying `.gitignore`                                                           |
 | `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)                                                   |

package/dist/resources/extensions/claude-code-cli/index.js

@@ -0,0 +1,25 @@
+/**
+ * Claude Code CLI Provider Extension
+ *
+ * Registers a model provider that delegates inference to the user's
+ * locally-installed Claude Code CLI via the official Agent SDK.
+ *
+ * Users with a Claude Code subscription (Pro/Max/Team) get access to
+ * subsidized inference through GSD's UI — no API key required.
+ *
+ * TOS-compliant: uses Anthropic's official `@anthropic-ai/claude-agent-sdk`,
+ * never touches credentials, never offers a login flow.
+ */
+import { CLAUDE_CODE_MODELS } from "./models.js";
+import { isClaudeCodeReady } from "./readiness.js";
+import { streamViaClaudeCode } from "./stream-adapter.js";
+export default function claudeCodeCli(pi) {
+    pi.registerProvider("claude-code", {
+        authMode: "externalCli",
+        api: "anthropic-messages",
+        baseUrl: "local://claude-code",
+        isReady: isClaudeCodeReady,
+        streamSimple: streamViaClaudeCode,
+        models: CLAUDE_CODE_MODELS,
+    });
+}

package/dist/resources/extensions/claude-code-cli/models.js

@@ -0,0 +1,40 @@
+/**
+ * Model definitions for the Claude Code CLI provider.
+ *
+ * Costs are zero because inference is covered by the user's Claude Code
+ * subscription. The SDK's `result` message still provides token counts
+ * for display in the TUI.
+ *
+ * Context windows and max tokens match the Anthropic API definitions
+ * in models.generated.ts.
+ */
+const ZERO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+export const CLAUDE_CODE_MODELS = [
+    {
+        id: "claude-opus-4-6",
+        name: "Claude Opus 4.6 (via Claude Code)",
+        reasoning: true,
+        input: ["text", "image"],
+        cost: ZERO_COST,
+        contextWindow: 1_000_000,
+        maxTokens: 128_000,
+    },
+    {
+        id: "claude-sonnet-4-6",
+        name: "Claude Sonnet 4.6 (via Claude Code)",
+        reasoning: true,
+        input: ["text", "image"],
+        cost: ZERO_COST,
+        contextWindow: 1_000_000,
+        maxTokens: 64_000,
+    },
+    {
+        id: "claude-haiku-4-5",
+        name: "Claude Haiku 4.5 (via Claude Code)",
+        reasoning: true,
+        input: ["text", "image"],
+        cost: ZERO_COST,
+        contextWindow: 200_000,
+        maxTokens: 64_000,
+    },
+];

package/dist/resources/extensions/claude-code-cli/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@gsd/claude-code-cli",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./index.js"
+    ]
+  }
+}

package/dist/resources/extensions/claude-code-cli/partial-builder.js

@@ -0,0 +1,223 @@
+/**
+ * Content-block mapping helpers and streaming state tracker.
+ *
+ * Translates the Claude Agent SDK's `BetaRawMessageStreamEvent` sequence
+ * into GSD's `AssistantMessageEvent` deltas for incremental TUI rendering.
+ */
+// ---------------------------------------------------------------------------
+// Content-block mapping helpers
+// ---------------------------------------------------------------------------
+/**
+ * Convert a single BetaContentBlock to the corresponding GSD content type.
+ */
+export function mapContentBlock(block) {
+    switch (block.type) {
+        case "text":
+            return { type: "text", text: block.text };
+        case "thinking":
+            return {
+                type: "thinking",
+                thinking: block.thinking,
+                ...(block.signature ? { thinkingSignature: block.signature } : {}),
+            };
+        case "tool_use":
+            return {
+                type: "toolCall",
+                id: block.id,
+                name: block.name,
+                arguments: block.input,
+            };
+        case "server_tool_use":
+            return {
+                type: "serverToolUse",
+                id: block.id,
+                name: block.name,
+                input: block.input,
+            };
+        case "web_search_tool_result":
+            return {
+                type: "webSearchResult",
+                toolUseId: block.tool_use_id,
+                content: block.content,
+            };
+        default: {
+            const unknown = block;
+            return { type: "text", text: `[unknown content block: ${JSON.stringify(unknown)}]` };
+        }
+    }
+}
+export function mapStopReason(reason) {
+    switch (reason) {
+        case "end_turn":
+        case "stop_sequence":
+            return "stop";
+        case "max_tokens":
+            return "length";
+        case "tool_use":
+            return "toolUse";
+        default:
+            return "stop";
+    }
+}
+/**
+ * Convert SDK usage + total_cost_usd into GSD's Usage shape.
+ *
+ * The SDK does not break cost down per-bucket, so all cost is
+ * attributed to `cost.total`.
+ */
+export function mapUsage(sdkUsage, totalCostUsd) {
+    return {
+        input: sdkUsage.input_tokens,
+        output: sdkUsage.output_tokens,
+        cacheRead: sdkUsage.cache_read_input_tokens,
+        cacheWrite: sdkUsage.cache_creation_input_tokens,
+        totalTokens: sdkUsage.input_tokens +
+            sdkUsage.output_tokens +
+            sdkUsage.cache_read_input_tokens +
+            sdkUsage.cache_creation_input_tokens,
+        cost: {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            total: totalCostUsd,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Zero-cost usage constant
+// ---------------------------------------------------------------------------
+export const ZERO_USAGE = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+// ---------------------------------------------------------------------------
+// Streaming partial-message state tracker
+// ---------------------------------------------------------------------------
+/**
+ * Mutable accumulator that tracks the partial AssistantMessage being built
+ * from a sequence of stream_event messages. Produces AssistantMessageEvent
+ * deltas that the TUI can render incrementally.
+ */
+export class PartialMessageBuilder {
+    partial;
+    /** Map from stream-event `index` to our content array index. */
+    indexMap = new Map();
+    /** Accumulated JSON input string per tool_use block (keyed by stream index). */
+    toolJsonAccum = new Map();
+    constructor(model) {
+        this.partial = {
+            role: "assistant",
+            content: [],
+            api: "anthropic-messages",
+            provider: "claude-code",
+            model,
+            usage: { ...ZERO_USAGE },
+            stopReason: "stop",
+            timestamp: Date.now(),
+        };
+    }
+    get message() {
+        return this.partial;
+    }
+    /**
+     * Feed a BetaRawMessageStreamEvent and return the corresponding
+     * AssistantMessageEvent (or null if the event is not mapped).
+     */
+    handleEvent(event) {
+        const streamIndex = event.index ?? 0;
+        switch (event.type) {
+            // ---- Block start ----
+            case "content_block_start": {
+                const block = event.content_block;
+                if (!block)
+                    return null;
+                const contentIndex = this.partial.content.length;
+                this.indexMap.set(streamIndex, contentIndex);
+                if (block.type === "text") {
+                    this.partial.content.push({ type: "text", text: "" });
+                    return { type: "text_start", contentIndex, partial: this.partial };
+                }
+                if (block.type === "thinking") {
+                    this.partial.content.push({ type: "thinking", thinking: "" });
+                    return { type: "thinking_start", contentIndex, partial: this.partial };
+                }
+                if (block.type === "tool_use") {
+                    this.toolJsonAccum.set(streamIndex, "");
+                    this.partial.content.push({
+                        type: "toolCall",
+                        id: block.id,
+                        name: block.name,
+                        arguments: {},
+                    });
+                    return { type: "toolcall_start", contentIndex, partial: this.partial };
+                }
+                if (block.type === "server_tool_use") {
+                    this.partial.content.push({
+                        type: "serverToolUse",
+                        id: block.id,
+                        name: block.name,
+                        input: block.input,
+                    });
+                    return { type: "server_tool_use", contentIndex, partial: this.partial };
+                }
+                return null;
+            }
+            // ---- Block delta ----
+            case "content_block_delta": {
+                const contentIndex = this.indexMap.get(streamIndex);
+                if (contentIndex === undefined)
+                    return null;
+                const delta = event.delta;
+                if (!delta)
+                    return null;
+                if (delta.type === "text_delta" && typeof delta.text === "string") {
+                    const existing = this.partial.content[contentIndex];
+                    existing.text += delta.text;
+                    return { type: "text_delta", contentIndex, delta: delta.text, partial: this.partial };
+                }
+                if (delta.type === "thinking_delta" && typeof delta.thinking === "string") {
+                    const existing = this.partial.content[contentIndex];
+                    existing.thinking += delta.thinking;
+                    return { type: "thinking_delta", contentIndex, delta: delta.thinking, partial: this.partial };
+                }
+                if (delta.type === "input_json_delta" && typeof delta.partial_json === "string") {
+                    const accum = (this.toolJsonAccum.get(streamIndex) ?? "") + delta.partial_json;
+                    this.toolJsonAccum.set(streamIndex, accum);
+                    return { type: "toolcall_delta", contentIndex, delta: delta.partial_json, partial: this.partial };
+                }
+                return null;
+            }
+            // ---- Block stop ----
+            case "content_block_stop": {
+                const contentIndex = this.indexMap.get(streamIndex);
+                if (contentIndex === undefined)
+                    return null;
+                const block = this.partial.content[contentIndex];
+                if (block.type === "text") {
+                    return { type: "text_end", contentIndex, content: block.text, partial: this.partial };
+                }
+                if (block.type === "thinking") {
+                    return { type: "thinking_end", contentIndex, content: block.thinking, partial: this.partial };
+                }
+                if (block.type === "toolCall") {
+                    const jsonStr = this.toolJsonAccum.get(streamIndex) ?? "{}";
+                    try {
+                        block.arguments = JSON.parse(jsonStr);
+                    }
+                    catch {
+                        block.arguments = { _raw: jsonStr };
+                    }
+                    return { type: "toolcall_end", contentIndex, toolCall: block, partial: this.partial };
+                }
+                return null;
+            }
+            default:
+                return null;
+        }
+    }
+}

package/dist/resources/extensions/claude-code-cli/readiness.js

@@ -0,0 +1,26 @@
+/**
+ * Readiness check for the Claude Code CLI provider.
+ *
+ * Verifies the `claude` binary is installed and responsive.
+ * Result is cached for 30 seconds to avoid shelling out on every
+ * model-availability check.
+ */
+import { execSync } from "node:child_process";
+let cachedReady = null;
+let lastCheckMs = 0;
+const CHECK_INTERVAL_MS = 30_000;
+export function isClaudeCodeReady() {
+    const now = Date.now();
+    if (cachedReady !== null && now - lastCheckMs < CHECK_INTERVAL_MS) {
+        return cachedReady;
+    }
+    try {
+        execSync("claude --version", { timeout: 5_000, stdio: "pipe" });
+        cachedReady = true;
+    }
+    catch {
+        cachedReady = false;
+    }
+    lastCheckMs = now;
+    return cachedReady;
+}

package/dist/resources/extensions/claude-code-cli/sdk-types.js

@@ -0,0 +1,8 @@
+/**
+ * Lightweight type mirrors for the Claude Agent SDK.
+ *
+ * These stubs allow the extension to compile without a hard dependency on
+ * `@anthropic-ai/claude-agent-sdk`. The real SDK is imported dynamically
+ * at runtime in stream-adapter.ts.
+ */
+export {};