gsd-pi 2.38.0-dev.eeb3520 → 2.39.0-dev.20aba06

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -0,0 +1,238 @@
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+
+import { findMilestoneIds, nextMilestoneId } from "../guided-flow.js";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { ensureDbOpen } from "./dynamic-tools.js";
+
+export function registerDbTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "gsd_save_decision",
+    label: "Save Decision",
+    description:
+      "Record a project decision to the GSD database and regenerate DECISIONS.md. " +
+      "Decision IDs are auto-assigned — never provide an ID manually.",
+    promptSnippet: "Record a project decision to the GSD database (auto-assigns ID, regenerates DECISIONS.md)",
+    promptGuidelines: [
+      "Use gsd_save_decision when recording an architectural, pattern, library, or observability decision.",
+      "Decision IDs are auto-assigned (D001, D002, ...) — never guess or provide an ID.",
+      "All fields except revisable and when_context are required.",
+      "The tool writes to the DB and regenerates .gsd/DECISIONS.md automatically.",
+    ],
+    parameters: Type.Object({
+      scope: Type.String({ description: "Scope of the decision (e.g. 'architecture', 'library', 'observability')" }),
+      decision: Type.String({ description: "What is being decided" }),
+      choice: Type.String({ description: "The choice made" }),
+      rationale: Type.String({ description: "Why this choice was made" }),
+      revisable: Type.Optional(Type.String({ description: "Whether this can be revisited (default: 'Yes')" })),
+      when_context: Type.Optional(Type.String({ description: "When/context for the decision (e.g. milestone ID)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const dbAvailable = await ensureDbOpen();
+      if (!dbAvailable) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot save decision." }],
+          details: { operation: "save_decision", error: "db_unavailable" } as any,
+        };
+      }
+      try {
+        const { saveDecisionToDb } = await import("../db-writer.js");
+        const { id } = await saveDecisionToDb(
+          {
+            scope: params.scope,
+            decision: params.decision,
+            choice: params.choice,
+            rationale: params.rationale,
+            revisable: params.revisable,
+            when_context: params.when_context,
+          },
+          process.cwd(),
+        );
+        return {
+          content: [{ type: "text" as const, text: `Saved decision ${id}` }],
+          details: { operation: "save_decision", id } as any,
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`gsd-db: gsd_save_decision tool failed: ${msg}\n`);
+        return {
+          content: [{ type: "text" as const, text: `Error saving decision: ${msg}` }],
+          details: { operation: "save_decision", error: msg } as any,
+        };
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "gsd_update_requirement",
+    label: "Update Requirement",
+    description:
+      "Update an existing requirement in the GSD database and regenerate REQUIREMENTS.md. " +
+      "Provide the requirement ID (e.g. R001) and any fields to update.",
+    promptSnippet: "Update an existing GSD requirement by ID (regenerates REQUIREMENTS.md)",
+    promptGuidelines: [
+      "Use gsd_update_requirement to change status, validation, notes, or other fields on an existing requirement.",
+      "The id parameter is required — it must be an existing RXXX identifier.",
+      "All other fields are optional — only provided fields are updated.",
+      "The tool verifies the requirement exists before updating.",
+    ],
+    parameters: Type.Object({
+      id: Type.String({ description: "The requirement ID (e.g. R001, R014)" }),
+      status: Type.Optional(Type.String({ description: "New status (e.g. 'active', 'validated', 'deferred')" })),
+      validation: Type.Optional(Type.String({ description: "Validation criteria or proof" })),
+      notes: Type.Optional(Type.String({ description: "Additional notes" })),
+      description: Type.Optional(Type.String({ description: "Updated description" })),
+      primary_owner: Type.Optional(Type.String({ description: "Primary owning slice" })),
+      supporting_slices: Type.Optional(Type.String({ description: "Supporting slices" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const dbAvailable = await ensureDbOpen();
+      if (!dbAvailable) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot update requirement." }],
+          details: { operation: "update_requirement", id: params.id, error: "db_unavailable" } as any,
+        };
+      }
+      try {
+        const db = await import("../gsd-db.js");
+        const existing = db.getRequirementById(params.id);
+        if (!existing) {
+          return {
+            content: [{ type: "text" as const, text: `Error: Requirement ${params.id} not found.` }],
+            details: { operation: "update_requirement", id: params.id, error: "not_found" } as any,
+          };
+        }
+        const { updateRequirementInDb } = await import("../db-writer.js");
+        const updates: Record<string, string | undefined> = {};
+        if (params.status !== undefined) updates.status = params.status;
+        if (params.validation !== undefined) updates.validation = params.validation;
+        if (params.notes !== undefined) updates.notes = params.notes;
+        if (params.description !== undefined) updates.description = params.description;
+        if (params.primary_owner !== undefined) updates.primary_owner = params.primary_owner;
+        if (params.supporting_slices !== undefined) updates.supporting_slices = params.supporting_slices;
+        await updateRequirementInDb(params.id, updates, process.cwd());
+        return {
+          content: [{ type: "text" as const, text: `Updated requirement ${params.id}` }],
+          details: { operation: "update_requirement", id: params.id } as any,
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`gsd-db: gsd_update_requirement tool failed: ${msg}\n`);
+        return {
+          content: [{ type: "text" as const, text: `Error updating requirement: ${msg}` }],
+          details: { operation: "update_requirement", id: params.id, error: msg } as any,
+        };
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "gsd_save_summary",
+    label: "Save Summary",
+    description:
+      "Save a summary, research, context, or assessment artifact to the GSD database and write it to disk. " +
+      "Computes the file path from milestone/slice/task IDs automatically.",
+    promptSnippet: "Save a GSD artifact (summary/research/context/assessment) to DB and disk",
+    promptGuidelines: [
+      "Use gsd_save_summary to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT).",
+      "milestone_id is required. slice_id and task_id are optional — they determine the file path.",
+      "The tool computes the relative path automatically: milestones/M001/M001-SUMMARY.md, milestones/M001/slices/S01/S01-SUMMARY.md, etc.",
+      "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT.",
+    ],
+    parameters: Type.Object({
+      milestone_id: Type.String({ description: "Milestone ID (e.g. M001)" }),
+      slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
+      task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
+      artifact_type: Type.String({ description: "One of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT" }),
+      content: Type.String({ description: "The full markdown content of the artifact" }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const dbAvailable = await ensureDbOpen();
+      if (!dbAvailable) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot save artifact." }],
+          details: { operation: "save_summary", error: "db_unavailable" } as any,
+        };
+      }
+      const validTypes = ["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT"];
+      if (!validTypes.includes(params.artifact_type)) {
+        return {
+          content: [{ type: "text" as const, text: `Error: Invalid artifact_type "${params.artifact_type}". Must be one of: ${validTypes.join(", ")}` }],
+          details: { operation: "save_summary", error: "invalid_artifact_type" } as any,
+        };
+      }
+      try {
+        let relativePath: string;
+        if (params.task_id && params.slice_id) {
+          relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/tasks/${params.task_id}-${params.artifact_type}.md`;
+        } else if (params.slice_id) {
+          relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/${params.slice_id}-${params.artifact_type}.md`;
+        } else {
+          relativePath = `milestones/${params.milestone_id}/${params.milestone_id}-${params.artifact_type}.md`;
+        }
+        const { saveArtifactToDb } = await import("../db-writer.js");
+        await saveArtifactToDb(
+          {
+            path: relativePath,
+            artifact_type: params.artifact_type,
+            content: params.content,
+            milestone_id: params.milestone_id,
+            slice_id: params.slice_id,
+            task_id: params.task_id,
+          },
+          process.cwd(),
+        );
+        return {
+          content: [{ type: "text" as const, text: `Saved ${params.artifact_type} artifact to ${relativePath}` }],
+          details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type } as any,
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`gsd-db: gsd_save_summary tool failed: ${msg}\n`);
+        return {
+          content: [{ type: "text" as const, text: `Error saving artifact: ${msg}` }],
+          details: { operation: "save_summary", error: msg } as any,
+        };
+      }
+    },
+  });
+
+  const reservedMilestoneIds = new Set<string>();
+  pi.registerTool({
+    name: "gsd_generate_milestone_id",
+    label: "Generate Milestone ID",
+    description:
+      "Generate the next milestone ID for a new GSD milestone. " +
+      "Scans existing milestones on disk and respects the unique_milestone_ids preference. " +
+      "Always use this tool when creating a new milestone — never invent milestone IDs manually.",
+    promptSnippet: "Generate a valid milestone ID (respects unique_milestone_ids preference)",
+    promptGuidelines: [
+      "ALWAYS call gsd_generate_milestone_id before creating a new milestone directory or writing milestone files.",
+      "Never invent or hardcode milestone IDs like M001, M002 — always use this tool.",
+      "Call it once per milestone you need to create. For multi-milestone projects, call it once for each milestone in sequence.",
+      "The tool returns the correct format based on project preferences (e.g. M001 or M001-r5jzab).",
+    ],
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+      try {
+        const basePath = process.cwd();
+        const existingIds = findMilestoneIds(basePath);
+        const uniqueEnabled = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
+        const allIds = [...new Set([...existingIds, ...reservedMilestoneIds])];
+        const newId = nextMilestoneId(allIds, uniqueEnabled);
+        reservedMilestoneIds.add(newId);
+        return {
+          content: [{ type: "text" as const, text: newId }],
+          details: { operation: "generate_milestone_id", id: newId, existingCount: existingIds.length, reservedCount: reservedMilestoneIds.size, uniqueEnabled } as any,
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text" as const, text: `Error generating milestone ID: ${msg}` }],
+          details: { operation: "generate_milestone_id", error: msg } as any,
+        };
+      }
+    },
+  });
+}
+

package/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts

@@ -0,0 +1,90 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent";
+
+import { DEFAULT_BASH_TIMEOUT_SECS } from "../constants.js";
+
+export async function ensureDbOpen(): Promise<boolean> {
+  try {
+    const db = await import("../gsd-db.js");
+    if (db.isDbAvailable()) return true;
+    const dbPath = join(process.cwd(), ".gsd", "gsd.db");
+    if (existsSync(dbPath)) {
+      return db.openDatabase(dbPath);
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export function registerDynamicTools(pi: ExtensionAPI): void {
+  const baseBash = createBashTool(process.cwd(), {
+    spawnHook: (ctx) => ({ ...ctx, cwd: process.cwd() }),
+  });
+  const dynamicBash = {
+    ...baseBash,
+    execute: async (
+      toolCallId: string,
+      params: { command: string; timeout?: number },
+      signal?: AbortSignal,
+      onUpdate?: unknown,
+      ctx?: unknown,
+    ) => {
+      const paramsWithTimeout = {
+        ...params,
+        timeout: params.timeout ?? DEFAULT_BASH_TIMEOUT_SECS,
+      };
+      return (baseBash as any).execute(toolCallId, paramsWithTimeout, signal, onUpdate, ctx);
+    },
+  };
+  pi.registerTool(dynamicBash as any);
+
+  const baseWrite = createWriteTool(process.cwd());
+  pi.registerTool({
+    ...baseWrite,
+    execute: async (
+      toolCallId: string,
+      params: { path: string; content: string },
+      signal?: AbortSignal,
+      onUpdate?: unknown,
+      ctx?: unknown,
+    ) => {
+      const fresh = createWriteTool(process.cwd());
+      return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
+    },
+  } as any);
+
+  const baseRead = createReadTool(process.cwd());
+  pi.registerTool({
+    ...baseRead,
+    execute: async (
+      toolCallId: string,
+      params: { path: string; offset?: number; limit?: number },
+      signal?: AbortSignal,
+      onUpdate?: unknown,
+      ctx?: unknown,
+    ) => {
+      const fresh = createReadTool(process.cwd());
+      return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
+    },
+  } as any);
+
+  const baseEdit = createEditTool(process.cwd());
+  pi.registerTool({
+    ...baseEdit,
+    execute: async (
+      toolCallId: string,
+      params: { path: string; oldText: string; newText: string },
+      signal?: AbortSignal,
+      onUpdate?: unknown,
+      ctx?: unknown,
+    ) => {
+      const fresh = createEditTool(process.cwd());
+      return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
+    },
+  } as any);
+}
+

package/src/resources/extensions/gsd/bootstrap/register-extension.ts

@@ -0,0 +1,46 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { registerGSDCommand } from "../commands.js";
+import { registerExitCommand } from "../exit-command.js";
+import { registerWorktreeCommand } from "../worktree-command.js";
+import { registerDbTools } from "./db-tools.js";
+import { registerDynamicTools } from "./dynamic-tools.js";
+import { registerHooks } from "./register-hooks.js";
+import { registerShortcuts } from "./register-shortcuts.js";
+
+function installEpipeGuard(): void {
+  if (!process.listeners("uncaughtException").some((listener) => listener.name === "_gsdEpipeGuard")) {
+    const _gsdEpipeGuard = (err: Error): void => {
+      if ((err as NodeJS.ErrnoException).code === "EPIPE") {
+        process.exit(0);
+      }
+      if ((err as NodeJS.ErrnoException).code === "ENOENT" && (err as any).syscall?.startsWith("spawn")) {
+        process.stderr.write(`[gsd] spawn ENOENT: ${(err as any).path ?? "unknown"} — command not found\n`);
+        return;
+      }
+      throw err;
+    };
+    process.on("uncaughtException", _gsdEpipeGuard);
+  }
+}
+
+export function registerGsdExtension(pi: ExtensionAPI): void {
+  registerGSDCommand(pi);
+  registerWorktreeCommand(pi);
+  registerExitCommand(pi);
+
+  installEpipeGuard();
+
+  pi.registerCommand("kill", {
+    description: "Exit GSD immediately (no cleanup)",
+    handler: async (_args: string, _ctx: ExtensionCommandContext) => {
+      process.exit(0);
+    },
+  });
+
+  registerDynamicTools(pi);
+  registerDbTools(pi);
+  registerShortcuts(pi);
+  registerHooks(pi);
+}
+

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -0,0 +1,167 @@
+import { join } from "node:path";
+
+import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
+import { isToolCallEventType } from "@gsd/pi-coding-agent";
+
+import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
+import { buildBeforeAgentStartResult } from "./system-context.js";
+import { handleAgentEnd } from "./agent-end-recovery.js";
+import { clearDiscussionFlowState, isDepthVerified, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite } from "./write-gate.js";
+import { getDiscussionMilestoneId } from "../guided-flow.js";
+import { loadToolApiKeys } from "../commands-config.js";
+import { loadFile, saveFile, formatContinue } from "../files.js";
+import { deriveState } from "../state.js";
+import { getAutoDashboardData, isAutoActive, isAutoPaused, markToolEnd, markToolStart } from "../auto.js";
+import { isParallelActive, shutdownParallel } from "../parallel-orchestrator.js";
+import { saveActivityLog } from "../activity-log.js";
+import { maybeRenderGsdHeader } from "./register-shortcuts.js";
+
+export function registerHooks(pi: ExtensionAPI): void {
+  pi.on("session_start", async (_event, ctx) => {
+    resetWriteGateState();
+    maybeRenderGsdHeader(ctx);
+    loadToolApiKeys();
+    try {
+      const [{ getRemoteConfigStatus }, { getLatestPromptSummary }] = await Promise.all([
+        import("../../remote-questions/config.js"),
+        import("../../remote-questions/status.js"),
+      ]);
+      const status = getRemoteConfigStatus();
+      const latest = getLatestPromptSummary();
+      if (!status.includes("not configured")) {
+        const suffix = latest ? `\nLast remote prompt: ${latest.id} (${latest.status})` : "";
+        ctx.ui.notify(`${status}${suffix}`, status.includes("disabled") ? "warning" : "info");
+      }
+    } catch {
+      // ignore
+    }
+  });
+
+  pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
+    return buildBeforeAgentStartResult(event, ctx);
+  });
+
+  pi.on("agent_end", async (event, ctx: ExtensionContext) => {
+    await handleAgentEnd(pi, event, ctx);
+  });
+
+  pi.on("session_before_compact", async () => {
+    if (isAutoActive() || isAutoPaused()) {
+      return { cancel: true };
+    }
+    const basePath = process.cwd();
+    const state = await deriveState(basePath);
+    if (!state.activeMilestone || !state.activeSlice || !state.activeTask) return;
+    if (state.phase !== "executing") return;
+
+    const sliceDir = resolveSlicePath(basePath, state.activeMilestone.id, state.activeSlice.id);
+    if (!sliceDir) return;
+
+    const existingFile = resolveSliceFile(basePath, state.activeMilestone.id, state.activeSlice.id, "CONTINUE");
+    if (existingFile && await loadFile(existingFile)) return;
+    const legacyContinue = join(sliceDir, "continue.md");
+    if (await loadFile(legacyContinue)) return;
+
+    const continuePath = join(sliceDir, `${state.activeSlice.id}-CONTINUE.md`);
+    await saveFile(continuePath, formatContinue({
+      frontmatter: {
+        milestone: state.activeMilestone.id,
+        slice: state.activeSlice.id,
+        task: state.activeTask.id,
+        step: 0,
+        totalSteps: 0,
+        status: "compacted" as const,
+        savedAt: new Date().toISOString(),
+      },
+      completedWork: `Task ${state.activeTask.id} (${state.activeTask.title}) was in progress when compaction occurred.`,
+      remainingWork: "Check the task plan for remaining steps.",
+      decisions: "Check task summary files for prior decisions.",
+      context: "Session was auto-compacted by Pi. Resume with /gsd.",
+      nextAction: `Resume task ${state.activeTask.id}: ${state.activeTask.title}.`,
+    }));
+  });
+
+  pi.on("session_shutdown", async (_event, ctx: ExtensionContext) => {
+    if (isParallelActive()) {
+      try {
+        await shutdownParallel(process.cwd());
+      } catch {
+        // best-effort
+      }
+    }
+    if (!isAutoActive() && !isAutoPaused()) return;
+    const dash = getAutoDashboardData();
+    if (dash.currentUnit) {
+      saveActivityLog(ctx, dash.basePath, dash.currentUnit.type, dash.currentUnit.id);
+    }
+  });
+
+  pi.on("tool_call", async (event) => {
+    if (!isToolCallEventType("write", event)) return;
+    const result = shouldBlockContextWrite(
+      event.toolName,
+      event.input.path,
+      getDiscussionMilestoneId(),
+      isDepthVerified(),
+      isQueuePhaseActive(),
+    );
+    if (result.block) return result;
+  });
+
+  pi.on("tool_result", async (event) => {
+    if (event.toolName !== "ask_user_questions") return;
+    const milestoneId = getDiscussionMilestoneId();
+    if (!milestoneId) return;
+
+    const details = event.details as any;
+    if (details?.cancelled || !details?.response) return;
+
+    const questions: any[] = (event.input as any)?.questions ?? [];
+    for (const question of questions) {
+      if (typeof question.id === "string" && question.id.includes("depth_verification")) {
+        markDepthVerified();
+        break;
+      }
+    }
+
+    const basePath = process.cwd();
+    const milestoneDir = resolveMilestonePath(basePath, milestoneId);
+    if (!milestoneDir) return;
+
+    const discussionPath = join(milestoneDir, buildMilestoneFileName(milestoneId, "DISCUSSION"));
+    const timestamp = new Date().toISOString();
+    const lines: string[] = [`## Exchange — ${timestamp}`, ""];
+    for (const question of questions) {
+      lines.push(`### ${question.header ?? "Question"}`, "", question.question ?? "");
+      if (Array.isArray(question.options)) {
+        lines.push("");
+        for (const opt of question.options) {
+          lines.push(`- **${opt.label}** — ${opt.description ?? ""}`);
+        }
+      }
+      const answer = details.response?.answers?.[question.id];
+      if (answer) {
+        lines.push("");
+        const selected = Array.isArray(answer.selected) ? answer.selected.join(", ") : answer.selected;
+        lines.push(`**Selected:** ${selected}`);
+        if (answer.notes) {
+          lines.push(`**Notes:** ${answer.notes}`);
+        }
+      }
+      lines.push("");
+    }
+    lines.push("---", "");
+    const existing = await loadFile(discussionPath) ?? `# ${milestoneId} Discussion Log\n\n`;
+    await saveFile(discussionPath, existing + lines.join("\n"));
+  });
+
+  pi.on("tool_execution_start", async (event) => {
+    if (!isAutoActive()) return;
+    markToolStart(event.toolCallId);
+  });
+
+  pi.on("tool_execution_end", async (event) => {
+    markToolEnd(event.toolCallId);
+  });
+}
+

package/src/resources/extensions/gsd/bootstrap/register-shortcuts.ts

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Key, Text } from "@gsd/pi-tui";
+
+import { GSDDashboardOverlay } from "../dashboard-overlay.js";
+import { shortcutDesc } from "../../shared/mod.js";
+
+export const GSD_LOGO_LINES = [
+  "   ██████╗ ███████╗██████╗ ",
+  "  ██╔════╝ ██╔════╝██╔══██╗",
+  "  ██║  ███╗███████╗██║  ██║",
+  "  ██║   ██║╚════██║██║  ██║",
+  "  ╚██████╔╝███████║██████╔╝",
+  "   ╚═════╝ ╚══════╝╚═════╝ ",
+];
+
+export function registerShortcuts(pi: ExtensionAPI): void {
+  pi.registerShortcut(Key.ctrlAlt("g"), {
+    description: shortcutDesc("Open GSD dashboard", "/gsd status"),
+    handler: async (ctx) => {
+      if (!existsSync(join(process.cwd(), ".gsd"))) {
+        ctx.ui.notify("No .gsd/ directory found. Run /gsd to start.", "info");
+        return;
+      }
+      await ctx.ui.custom<void>(
+        (tui, theme, _kb, done) => new GSDDashboardOverlay(tui, theme, () => done()),
+        {
+          overlay: true,
+          overlayOptions: {
+            width: "90%",
+            minWidth: 80,
+            maxHeight: "92%",
+            anchor: "center",
+          },
+        },
+      );
+    },
+  });
+}
+
+export function maybeRenderGsdHeader(ctx: { ui: any }): void {
+  try {
+    const theme = ctx.ui.theme;
+    const version = process.env.GSD_VERSION || "0.0.0";
+    const logoText = GSD_LOGO_LINES.map((line) => theme.fg("accent", line)).join("\n");
+    const titleLine = `  ${theme.bold("Get Shit Done")} ${theme.fg("dim", `v${version}`)}`;
+    const headerContent = `${logoText}\n${titleLine}`;
+    ctx.ui.setHeader((_ui: unknown, _theme: unknown) => new Text(headerContent, 1, 0));
+  } catch {
+    // no TUI
+  }
+}
+