@opengsd/gsd-pi 1.0.2-dev.235ebf3 → 1.0.2-dev.2c204d3

package/README.md

@@ -13,6 +13,28 @@ GSD Pi is a local-first coding agent for planning, implementing, verifying, and
 
 It combines a terminal agent, project workflow tools, worktree-aware Git automation, and optional UI integrations so a project can move from idea to reviewed implementation with less manual coordination.
 
+## Screenshots
+
+GSD runs as a terminal-first TUI with optional browser dashboard controls.
+
+![GSD TUI running an agent workflow](./docs/assets/screenshots/gsd-tui-agent-run.png)
+
+![GSD TUI progress dashboard](./docs/assets/screenshots/gsd-tui-progress-dashboard.png)
+
+![GSD TUI metrics dashboard](./docs/assets/screenshots/gsd-tui-metrics-dashboard.png)
+
+## Feature Roll-Up
+
+- **Guided terminal agent** — Start with `gsd`, configure providers, and run planned or quick coding sessions from your shell.
+- **Autonomous project workflow** — Break work into milestones, slices, and tasks, then let auto mode plan, implement, verify, and advance.
+- **Worktree-aware Git automation** — Keep implementation work isolated while preserving a reviewable main checkout.
+- **Local project memory** — Store project requirements, decisions, runtime notes, generated plans, summaries, and validation evidence under `.gsd/`.
+- **Multi-provider model routing** — Use the provider your team already has, with configurable defaults and per-phase model preferences.
+- **Extension surface** — Add project-specific commands, tools, skills, and UI integrations through bundled or community extensions.
+- **Terminal and web surfaces** — Use the TUI by default, or launch `gsd --web` when a visual control plane fits the work better than a terminal.
+
+See [CHANGELOG.md](./CHANGELOG.md) for release-by-release fixes and [Legacy Release History](./docs/archive/legacy-release-history.md) for archived history before the `open-gsd/gsd-pi` baseline.
+
 ## Status
 
 This repository is starting a new development baseline at version `1.0.0` under the `open-gsd/gsd-pi` project.
@@ -27,41 +49,63 @@ Recommended — guided installer:
 npx @opengsd/gsd-pi@latest
 ```
 
-Alternative — direct global install:
+For CI or scripted installs:
+
+```bash
+npx @opengsd/gsd-pi@latest --yes
+```
+
+Alternative — direct npm global install:
 
 ```bash
 npm install -g @opengsd/gsd-pi@latest
 ```
 
-For CI or scripted installs:
+If you want pnpm to own the global install, use pnpm's runner:
 
 ```bash
-npx @opengsd/gsd-pi@latest --yes
+pnpm setup
+exec $SHELL -l
+pnpm dlx @opengsd/gsd-pi@latest
 ```
 
 Source: [`open-gsd/gsd-pi`](https://github.com/open-gsd/gsd-pi).
 
 ## Migrate From Older Installs
 
-GSD Pi now installs from the scoped npm package `@opengsd/gsd-pi`. If you previously installed the older unscoped `gsd-pi` package, remove it first so the old global binary does not shadow the new package.
+GSD Pi now installs from the scoped package `@opengsd/gsd-pi`. If you previously installed the older unscoped `gsd-pi` package, remove it first so the old global binary does not shadow the new package.
 
-macOS / Linux:
+Recommended migration with the guided `npx` installer:
 
 ```bash
-npm uninstall -g gsd-pi
+npm uninstall -g gsd-pi @opengsd/gsd-pi
 rm -f ~/.gsd/.update-check ~/.gsd/agent/managed-resources.json
-npm install -g @opengsd/gsd-pi@latest
-which gsd
+npx @opengsd/gsd-pi@latest
+command -v gsd
 gsd --version
 ```
 
-Windows PowerShell:
+If the old package was installed with `sudo npm install -g`, use `sudo npm uninstall -g gsd-pi` for the old package removal.
+
+To migrate from old npm globals to a pnpm-owned global install:
+
+```bash
+npm uninstall -g gsd-pi @opengsd/gsd-pi
+rm -f ~/.gsd/.update-check ~/.gsd/agent/managed-resources.json
+pnpm setup
+exec $SHELL -l
+pnpm dlx @opengsd/gsd-pi@latest
+command -v gsd
+gsd --version
+```
+
+Windows PowerShell with the guided `npx` installer:
 
 ```powershell
-npm uninstall -g gsd-pi
+npm uninstall -g gsd-pi @opengsd/gsd-pi
 Remove-Item "$env:USERPROFILE\.gsd\.update-check" -Force -ErrorAction SilentlyContinue
 Remove-Item "$env:USERPROFILE\.gsd\agent\managed-resources.json" -Force -ErrorAction SilentlyContinue
-npm install -g @opengsd/gsd-pi@latest
+npx @opengsd/gsd-pi@latest
 where.exe gsd
 gsd --version
 ```
@@ -85,6 +129,14 @@ npm uninstall -g @opengsd/gsd-pi gsd-pi
 rm -rf ~/.gsd
 ```
 
+If you installed GSD with pnpm, use pnpm for the pnpm-owned package. If pnpm reports that its global bin directory is not on `PATH`, run `pnpm setup`, restart your shell, then retry.
+
+```bash
+pnpm remove -g @opengsd/gsd-pi
+npm uninstall -g gsd-pi
+rm -rf ~/.gsd
+```
+
 Windows PowerShell:
 
 ```powershell
@@ -139,7 +191,6 @@ Then use slash commands inside the GSD session:
 | `native/` | Native engine packaging and platform binaries |
 | `studio/` | Desktop studio app |
 | `web/` | Web UI and API surface |
-| `vscode-extension/` | VS Code integration |
 | `docs/` | User and developer documentation |
 | `scripts/` | Build, release, migration, and maintenance scripts |
 

package/dist/resource-loader.d.ts

@@ -33,6 +33,11 @@ export declare function getNewerManagedResourceVersion(agentDir: string, current
  * 4. Makes the result writable for the next upgrade cycle.
  */
 export declare function syncResourceDir(srcDir: string, destDir: string): void;
+export declare function resolvePackageNodeModulesLayout(root: string): {
+    internalNodeModules: string;
+    hoistedNodeModules: string | null;
+};
+export declare function findNearestNodeModulesAncestor(startPath: string): string | null;
 /** Check if any GSD workspace scopes exist in internal but not in hoisted node_modules */
 export declare function hasMissingWorkspaceScopes(hoisted: string, internal: string): boolean;
 /**
@@ -47,6 +52,7 @@ export declare function mergedFingerprint(hoisted: string, internal: string): st
  * Syncs all bundled resources to agentDir (~/.gsd/agent/) on every launch.
  *
  * - extensions/ → ~/.gsd/agent/extensions/   (overwrite when version changes)
+ * - shared/     → ~/.gsd/agent/shared/       (overwrite when version changes)
  * - agents/     → ~/.gsd/agent/agents/        (overwrite when version changes)
  * - skills/     → ~/.gsd/agent/skills/        (overwrite when version changes)
  * - GSD-WORKFLOW.md → ~/.gsd/agent/GSD-WORKFLOW.md (fallback for env var miss)
@@ -60,6 +66,7 @@ export declare function mergedFingerprint(hoisted: string, internal: string): st
  */
 export declare function initResources(agentDir: string, skillsDir?: string): void;
 export declare function hasStaleCompiledExtensionSiblings(extensionsDir: string, sourceDir?: string): boolean;
+export declare function hasMissingBundledResourceFiles(destDir: string, sourceDir: string): boolean;
 interface BuildResourceLoaderOptions {
     additionalExtensionPaths?: string[];
 }

package/dist/resource-loader.js

@@ -311,16 +311,15 @@ function copyDirRecursive(src, dest) {
  * them without requiring every call site to use jiti.
  *
  * Layout differences by install method:
- * - Source/monorepo: packageRoot/node_modules has everything → simple symlink
- * - Global install (npm/bun/pnpm): merge hoisted dirname(packageRoot)/node_modules with
- *   packageRoot/node_modules so package-local deps like @sinclair/typebox resolve (#3529, #3564)
+ * - Source/monorepo: packageRoot/node_modules has everything -> simple symlink
+ * - Global install (npm/bun/pnpm): merge the nearest ancestor node_modules
+ *   with packageRoot/node_modules so both hoisted deps like yaml and
+ *   package-local deps like @sinclair/typebox resolve (#3529, #3564).
  */
 function ensureNodeModulesSymlink(agentDir) {
     const agentNodeModules = join(agentDir, 'node_modules');
-    const internalNodeModules = join(packageRoot, 'node_modules');
-    const hoistedNodeModules = dirname(packageRoot);
-    const isGlobalInstall = basename(hoistedNodeModules) === 'node_modules';
-    if (!isGlobalInstall) {
+    const { internalNodeModules, hoistedNodeModules } = resolvePackageNodeModulesLayout(packageRoot);
+    if (!hoistedNodeModules) {
         // Source/monorepo: internal node_modules has everything
         reconcileSymlink(agentNodeModules, internalNodeModules);
         return;
@@ -330,6 +329,23 @@ function ensureNodeModulesSymlink(agentDir) {
     // @gsd/* scopes are hoisted — a hoisted-only symlink breaks extension imports.
     reconcileMergedNodeModules(agentNodeModules, hoistedNodeModules, internalNodeModules);
 }
+export function resolvePackageNodeModulesLayout(root) {
+    return {
+        internalNodeModules: join(root, 'node_modules'),
+        hoistedNodeModules: findNearestNodeModulesAncestor(root),
+    };
+}
+export function findNearestNodeModulesAncestor(startPath) {
+    let current = resolve(startPath);
+    while (true) {
+        if (basename(current) === 'node_modules')
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
 /** Check if any GSD workspace scopes exist in internal but not in hoisted node_modules */
 export function hasMissingWorkspaceScopes(hoisted, internal) {
     if (!existsSync(internal))
@@ -544,6 +560,7 @@ function pruneRemovedBundledExtensions(manifest, agentDir) {
  * Syncs all bundled resources to agentDir (~/.gsd/agent/) on every launch.
  *
  * - extensions/ → ~/.gsd/agent/extensions/   (overwrite when version changes)
+ * - shared/     → ~/.gsd/agent/shared/       (overwrite when version changes)
  * - agents/     → ~/.gsd/agent/agents/        (overwrite when version changes)
  * - skills/     → ~/.gsd/agent/skills/        (overwrite when version changes)
  * - GSD-WORKFLOW.md → ~/.gsd/agent/GSD-WORKFLOW.md (fallback for env var miss)
@@ -584,12 +601,17 @@ export function initResources(agentDir, skillsDir = join(agentDir, 'skills')) {
         // Version matches — check content fingerprint for same-version staleness.
         const currentHash = getCurrentResourceFingerprint();
         const hasStaleExtensionFiles = hasStaleCompiledExtensionSiblings(extensionsDir, bundledExtensionsDir);
-        if (manifest.contentHash && manifest.contentHash === currentHash && !hasStaleExtensionFiles) {
+        const hasMissingSharedFiles = hasMissingBundledResourceFiles(join(agentDir, 'shared'), join(resourcesDir, 'shared'));
+        if (manifest.contentHash &&
+            manifest.contentHash === currentHash &&
+            !hasStaleExtensionFiles &&
+            !hasMissingSharedFiles) {
             return;
         }
     }
     // Sync bundled resources — overwrite so updates land on next launch.
     syncResourceDir(bundledExtensionsDir, join(agentDir, 'extensions'));
+    syncResourceDir(join(resourcesDir, 'shared'), join(agentDir, 'shared'));
     syncResourceDir(join(resourcesDir, 'agents'), join(agentDir, 'agents'));
     syncResourceDir(join(resourcesDir, 'skills'), skillsDir);
     // Sync GSD-WORKFLOW.md to agentDir as a fallback for when GSD_WORKFLOW_PATH
@@ -627,7 +649,7 @@ function cleanupBundledSkillsFromEcosystemDir() {
                 makeTreeWritable(targetPath);
                 rmSync(targetPath, { recursive: true, force: true });
             }
-            else {
+            else if (process.env.GSD_RESOURCE_LOADER_DEBUG === '1') {
                 console.warn(`[GSD] Leaving ambiguous skill collision in ${targetPath}; ` +
                     `the bundled copy will be used from ~/.gsd/agent/skills/${entry.name}.`);
             }
@@ -675,6 +697,17 @@ export function hasStaleCompiledExtensionSiblings(extensionsDir, sourceDir = bun
     }
     return false;
 }
+export function hasMissingBundledResourceFiles(destDir, sourceDir) {
+    const sourceFiles = collectRelativeFiles(sourceDir);
+    if (sourceFiles.size === 0)
+        return false;
+    const installedFiles = collectRelativeFiles(destDir);
+    for (const relPath of sourceFiles) {
+        if (!installedFiles.has(relPath))
+            return true;
+    }
+    return false;
+}
 function collectRelativeFiles(rootDir) {
     const files = new Set();
     if (!existsSync(rootDir))

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-f796c99ee5d78c73
+e7fbf7aae3d3457c

package/dist/resources/extensions/context7/index.js

@@ -92,6 +92,16 @@ function formatLibraryList(libs, query) {
     lines.push("\nUse the ID (e.g. /websites/react_dev) with get_library_docs to fetch documentation.");
     return lines.join("\n");
 }
+function getFirstTextContent(result) {
+    const content = result.content;
+    if (!Array.isArray(content))
+        return undefined;
+    const textBlock = content.find((block) => typeof block === "object" &&
+        block !== null &&
+        block.type === "text" &&
+        typeof block.text === "string");
+    return textBlock?.text.trim() || undefined;
+}
 // ─── Extension ───────────────────────────────────────────────────────────────
 export default function (pi) {
     // ── resolve_library ──────────────────────────────────────────────────────
@@ -164,7 +174,7 @@ export default function (pi) {
             if (isPartial)
                 return new Text(theme.fg("warning", "Searching Context7..."), 0, 0);
             if (result.isError || d?.error) {
-                return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+                return new Text(theme.fg("error", `Error: ${d?.error ?? getFirstTextContent(result) ?? "unknown"}`), 0, 0);
             }
             let text = theme.fg("success", `${d?.resultCount ?? 0} ${d?.resultCount === 1 ? "library" : "libraries"} found`);
             if (d?.cached)
@@ -303,7 +313,7 @@ export default function (pi) {
             if (isPartial)
                 return new Text(theme.fg("warning", "Fetching documentation..."), 0, 0);
             if (result.isError || d?.error) {
-                return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+                return new Text(theme.fg("error", `Error: ${d?.error ?? getFirstTextContent(result) ?? "unknown"}`), 0, 0);
             }
             let text = theme.fg("success", `${(d?.charCount ?? 0).toLocaleString()} chars`);
             text += theme.fg("dim", ` · ${d?.tokens ?? 5000} token budget`);

package/dist/resources/extensions/gsd/auto/loop.js

@@ -50,6 +50,7 @@ import { handleCustomEngineVerifyPause, handleCustomEngineVerifyRetryOutcome, }
 import { handleCustomEngineReconcile } from "./workflow-custom-engine-reconcile.js";
 import { handleCustomEngineReconcileOutcome } from "./workflow-custom-engine-reconcile-outcome.js";
 import { formatLeaseConflictNotice } from "./lease-conflict-notice.js";
+import { setAutoOutcomeWidget, unitVerb } from "../auto-dashboard.js";
 /**
  * Returns true if workerId is an active worker in this project whose OS
  * process no longer exists. Used to detect dead lease holders before
@@ -690,6 +691,24 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 });
                 if (reconcileFlow.action === "break")
                     break;
+                if (s.stepMode) {
+                    if (ctx.hasUI) {
+                        ctx.ui.setWidget?.("gsd-progress", undefined);
+                        setAutoOutcomeWidget(ctx, {
+                            status: "step",
+                            title: "Step complete",
+                            detail: `Completed ${unitVerb(iterData.unitType)} ${iterData.unitId}.`,
+                            unitLabel: `${unitVerb(iterData.unitType)} ${iterData.unitId}`,
+                            nextAction: "Advance one step, or resume automatic mode.",
+                            commands: ["/gsd next", "/gsd auto", "/gsd status for overview"],
+                            startedAt: s.autoStartTime,
+                        });
+                    }
+                    ctx.ui.setStatus("gsd-auto", "next");
+                    ctx.ui.notify(`Step complete: ${unitVerb(iterData.unitType)} ${iterData.unitId}. Run /gsd next for the next step, or /gsd auto to continue automatically.`, "info");
+                    s.preserveStepSurfaceAfterLoopExit = true;
+                    break;
+                }
                 continue;
             }
             if (!sidecarItem) {

package/dist/resources/extensions/gsd/auto/phases.js

@@ -1568,7 +1568,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     const dispatchKey = `${unitType}/${unitId}`;
     const nextDispatchCount = (s.unitDispatchCount.get(dispatchKey) ?? 0) + 1;
     // Status bar (widget + preconditions deferred until after model selection — see #2899)
-    ctx.ui.setStatus("gsd-auto", "auto");
+    ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
     if (mid)
         deps.updateSliceProgressCache(s.basePath, mid, state.activeSlice?.id);
     // ── Safety harness: reset evidence + create checkpoint ──

package/dist/resources/extensions/gsd/auto/session.js

@@ -132,6 +132,8 @@ export class AutoSession {
     // ── Isolation degradation ────────────────────────────────────────────
     /** Set to true when worktree creation fails; prevents merge of nonexistent branch. */
     isolationDegraded = false;
+    /** Temporary recovery mode for stranded work adopted from physical git evidence. */
+    strandedRecoveryIsolationMode = null;
     /** Project-root dirty snapshot captured before an isolated worktree unit runs. */
     rootWriteBaseline = null;
     // ── Merge guard ──────────────────────────────────────────────────────
@@ -285,6 +287,7 @@ export class AutoSession {
         this.lastGitActionFailure = null;
         this.lastGitActionStatus = null;
         this.isolationDegraded = false;
+        this.strandedRecoveryIsolationMode = null;
         this.rootWriteBaseline = null;
         this.milestoneMergedInPhases = false;
         this.milestoneStartShas = new Map();