gsd-pi 2.74.0 → 2.75.0-dev.2203010a0

package/src/resources/extensions/gsd/bootstrap/provider-error-resume.ts

@@ -6,6 +6,7 @@ import type {
 
 import { getAutoDashboardData, startAuto, type AutoDashboardData } from "../auto.js";
 import { resetTransientRetryState } from "./agent-end-recovery.js";
+import { resetSessionTimeoutState } from "../auto/phases.js";
 
 type AutoResumeSnapshot = Pick<AutoDashboardData, "active" | "paused" | "stepMode" | "basePath">;
 
@@ -43,10 +44,11 @@ export async function resumeAutoAfterProviderDelay(
     return "missing-base";
   }
 
-  // Reset the transient retry counter before restarting — without this,
-  // consecutiveTransientCount accumulates across pause/resume cycles and
-  // permanently locks out auto-resume after MAX_TRANSIENT_AUTO_RESUMES errors.
+  // Reset retry counters before restarting — without this, counters
+  // accumulate across pause/resume cycles and permanently lock out
+  // auto-resume after their respective MAX thresholds.
   resetTransientRetryState();
+  resetSessionTimeoutState();
 
   await deps.startAuto(
     ctx as ExtensionCommandContext,

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

@@ -4,6 +4,7 @@ import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { ensureDbOpen } from "./dynamic-tools.js";
 import { executeMilestoneStatus } from "../tools/workflow-tool-executors.js";
+import { checkpointDatabase } from "../gsd-db.js";
 
 export function registerQueryTools(pi: ExtensionAPI): void {
   pi.registerTool({
@@ -31,4 +32,34 @@ export function registerQueryTools(pi: ExtensionAPI): void {
       return executeMilestoneStatus(params);
     },
   });
+
+  pi.registerTool({
+    name: "gsd_checkpoint_db",
+    label: "Checkpoint GSD Database",
+    description:
+      "Flush the SQLite WAL (Write-Ahead Log) into the base gsd.db file. " +
+      "Call this before `git add .gsd/gsd.db` to ensure the committed database " +
+      "contains current milestone/slice/task state rather than stale pre-session content. " +
+      "Safe to call at any time while GSD is running.",
+    promptSnippet: "Flush WAL into gsd.db so git add stages current state",
+    promptGuidelines: [
+      "Call gsd_checkpoint_db immediately before staging .gsd/gsd.db with git add.",
+      "Do not use sqlite3 or shell commands to checkpoint — they are blocked. Use this tool instead.",
+    ],
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+      const dbAvailable = await ensureDbOpen();
+      if (!dbAvailable) {
+        return {
+          content: [{ type: "text", text: "Error: GSD database is not available. Cannot checkpoint." }],
+          details: { operation: "checkpoint_db", error: "db_unavailable" },
+        };
+      }
+      checkpointDatabase();
+      return {
+        content: [{ type: "text", text: "WAL checkpoint complete. gsd.db is now up to date and safe to stage with git add." }],
+        details: { operation: "checkpoint_db", status: "ok" },
+      };
+    },
+  });
 }

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

@@ -2,9 +2,10 @@
 
 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 type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-extension-api.js";
+import { loadEcosystemExtensions } from "../ecosystem/loader.js";
 import { registerDbTools } from "./db-tools.js";
 import { registerDynamicTools } from "./dynamic-tools.js";
 import { registerJournalTools } from "./journal-tools.js";
@@ -12,6 +13,7 @@ import { registerQueryTools } from "./query-tools.js";
 import { registerHooks } from "./register-hooks.js";
 import { registerShortcuts } from "./register-shortcuts.js";
 import { writeCrashLog } from "./crash-log.js";
+import { logWarning } from "../workflow-logger.js";
 
 export { writeCrashLog } from "./crash-log.js";
 
@@ -58,12 +60,17 @@ function installEpipeGuard(): void {
 }
 
 export function registerGsdExtension(pi: ExtensionAPI): void {
-  registerGSDCommand(pi);
+  // Note: registerGSDCommand is called by index.ts before this function,
+  // so we intentionally skip it here to avoid double-registration.
   registerWorktreeCommand(pi);
   registerExitCommand(pi);
 
   installEpipeGuard();
 
+  // Ecosystem handlers captured by the GSDExtensionAPI wrapper for the
+  // GSD-owned `before_agent_start` dispatch step (#3338).
+  const ecosystemHandlers: GSDEcosystemBeforeAgentStartHandler[] = [];
+
   pi.registerCommand("kill", {
     description: "Exit GSD immediately (no cleanup)",
     handler: async (_args: string, _ctx: ExtensionCommandContext) => {
@@ -71,10 +78,33 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
     },
   });
 
-  registerDynamicTools(pi);
-  registerDbTools(pi);
-  registerJournalTools(pi);
-  registerQueryTools(pi);
-  registerShortcuts(pi);
-  registerHooks(pi);
+  // Wrap non-critical registrations individually so one failure
+  // doesn't prevent the others from loading.
+  const nonCriticalRegistrations: Array<[string, () => void]> = [
+    ["dynamic-tools", () => registerDynamicTools(pi)],
+    ["db-tools", () => registerDbTools(pi)],
+    ["journal-tools", () => registerJournalTools(pi)],
+    ["query-tools", () => registerQueryTools(pi)],
+    ["shortcuts", () => registerShortcuts(pi)],
+    ["hooks", () => registerHooks(pi, ecosystemHandlers)],
+    ["ecosystem", () => {
+      void loadEcosystemExtensions(pi, ecosystemHandlers).catch((err) => {
+        logWarning(
+          "ecosystem",
+          `loader failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+    }],
+  ];
+
+  for (const [name, register] of nonCriticalRegistrations) {
+    try {
+      register();
+    } catch (err) {
+      logWarning(
+        "bootstrap",
+        `Failed to register ${name}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
 }

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

@@ -3,6 +3,10 @@ import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import { isToolCallEventType } from "@gsd/pi-coding-agent";
 
+import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-extension-api.js";
+import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
+import { getEcosystemReadyPromise } from "../ecosystem/loader.js";
+
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
 import { buildBeforeAgentStartResult } from "./system-context.js";
 import { handleAgentEnd } from "./agent-end-recovery.js";
@@ -14,6 +18,7 @@ import { loadToolApiKeys } from "../commands-config.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
 import { deriveState } from "../state.js";
 import { getAutoDashboardData, isAutoActive, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError } from "../auto.js";
+import { hideFooter } from "../auto-dashboard.js";
 import { isParallelActive, shutdownParallel } from "../parallel-orchestrator.js";
 import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { saveActivityLog } from "../activity-log.js";
@@ -35,7 +40,10 @@ async function syncServiceTierStatus(ctx: ExtensionContext): Promise<void> {
   ctx.ui.setStatus("gsd-fast", formatServiceTierFooterStatus(getEffectiveServiceTier(), ctx.model?.id));
 }
 
-export function registerHooks(pi: ExtensionAPI): void {
+export function registerHooks(
+  pi: ExtensionAPI,
+  ecosystemHandlers: GSDEcosystemBeforeAgentStartHandler[],
+): void {
   pi.on("session_start", async (_event, ctx) => {
     initNotificationStore(process.cwd());
     installNotifyInterceptor(ctx);
@@ -45,8 +53,12 @@ export function registerHooks(pi: ExtensionAPI): void {
     resetToolCallLoopGuard();
     resetAskUserQuestionsCache();
     await syncServiceTierStatus(ctx);
-    const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
-    prepareWorkflowMcpForProject(ctx, process.cwd());
+    // Skip MCP auto-prep when running inside an auto-worktree (see session_switch below).
+    const { isInAutoWorktree } = await import("../auto-worktree.js");
+    if (!isInAutoWorktree(process.cwd())) {
+      const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
+      prepareWorkflowMcpForProject(ctx, process.cwd());
+    }
 
     // Apply show_token_cost preference (#1515)
     try {
@@ -77,6 +89,9 @@ export function registerHooks(pi: ExtensionAPI): void {
       } catch { /* non-fatal */ }
     }
     loadToolApiKeys();
+    if (isAutoActive()) {
+      ctx.ui.setFooter(hideFooter);
+    }
   });
 
   pi.on("session_switch", async (_event, ctx) => {
@@ -87,13 +102,66 @@ export function registerHooks(pi: ExtensionAPI): void {
     resetAskUserQuestionsCache();
     clearDiscussionFlowState();
     await syncServiceTierStatus(ctx);
-    const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
-    prepareWorkflowMcpForProject(ctx, process.cwd());
+    // Skip MCP auto-prep when running inside an auto-worktree. The worktree
+    // already has .mcp.json from createAutoWorktree, and re-running the writer
+    // post-chdir rewrites the file mid-run (non-idempotent due to cwd-relative
+    // CLI path resolution), dirtying the tree and breaking the milestone merge.
+    const { isInAutoWorktree } = await import("../auto-worktree.js");
+    if (!isInAutoWorktree(process.cwd())) {
+      const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
+      prepareWorkflowMcpForProject(ctx, process.cwd());
+    }
     loadToolApiKeys();
+    if (isAutoActive()) {
+      ctx.ui.setFooter(hideFooter);
+    }
   });
 
   pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
-    return buildBeforeAgentStartResult(event, ctx);
+    // Wait for ecosystem loader to finish (no-op after first turn).
+    await getEcosystemReadyPromise();
+
+    // GSD's own context injection (existing behavior — unchanged).
+    const gsdResult = await buildBeforeAgentStartResult(event, ctx);
+
+    // Refresh the snapshot used by ecosystem getPhase()/getActiveUnit().
+    // deriveState has its own ~100ms cache so this is cheap on repeat calls.
+    try {
+      const state = await deriveState(process.cwd());
+      updateSnapshot(state);
+    } catch {
+      updateSnapshot(null);
+    }
+
+    // Chain ecosystem handlers using pi's runner.ts chaining protocol:
+    // each handler sees the systemPrompt mutated by prior handlers.
+    let currentSystemPrompt = gsdResult?.systemPrompt ?? event.systemPrompt;
+    // `any` because pi's BeforeAgentStartEventResult.message uses an internal
+    // CustomMessage type that's not re-exported (see ecosystem/gsd-extension-api.ts).
+    let lastMessage: any = gsdResult?.message;
+
+    for (const handler of ecosystemHandlers) {
+      try {
+        const r = await handler(
+          { ...event, systemPrompt: currentSystemPrompt },
+          ctx,
+        );
+        if (r?.systemPrompt !== undefined) currentSystemPrompt = r.systemPrompt;
+        if (r?.message) lastMessage = r.message;
+      } catch (err) {
+        safetyLogWarning(
+          "ecosystem",
+          `before_agent_start handler failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+
+    // Compose result. Return undefined if nothing changed (preserves runner contract).
+    if (currentSystemPrompt === event.systemPrompt && !lastMessage) return undefined;
+    return {
+      systemPrompt: currentSystemPrompt !== event.systemPrompt ? currentSystemPrompt : undefined,
+      message: lastMessage,
+    };
   });
 
   pi.on("agent_end", async (event, ctx: ExtensionContext) => {
@@ -125,7 +193,10 @@ export function registerHooks(pi: ExtensionAPI): void {
     await ensureDbOpen();
     const state = await deriveState(basePath);
     if (!state.activeMilestone || !state.activeSlice || !state.activeTask) return;
-    if (state.phase !== "executing") return;
+    // Write checkpoint for ALL phases, not just "executing" — discuss, research,
+    // and planning also carry in-memory state (user answers, gate verification)
+    // that would be lost on compaction (#4258).
+    // if (state.phase !== "executing") return;
 
     const sliceDir = resolveSlicePath(basePath, state.activeMilestone.id, state.activeSlice.id);
     if (!sliceDir) return;
@@ -261,7 +332,8 @@ export function registerHooks(pi: ExtensionAPI): void {
   // ── Safety harness: evidence collection + destructive command warnings ──
   pi.on("tool_call", async (event, ctx) => {
     if (!isAutoActive()) return;
-    safetyRecordToolCall(event.toolName, event.input as Record<string, unknown>);
+    markToolStart(event.toolCallId, event.toolName);
+    safetyRecordToolCall(event.toolCallId, event.toolName, event.input as Record<string, unknown>);
 
     // Destructive command classification (warn only, never block)
     if (isToolCallEventType("bash", event)) {
@@ -279,6 +351,20 @@ export function registerHooks(pi: ExtensionAPI): void {
   });
 
   pi.on("tool_result", async (event) => {
+    if (isAutoActive() && typeof event.toolCallId === "string") {
+      markToolEnd(event.toolCallId);
+    }
+    if (isAutoActive() && event.isError && event.toolName.startsWith("gsd_")) {
+      const resultPayload = ("result" in event ? event.result : undefined) as any;
+      const errorText = typeof resultPayload === "string"
+        ? resultPayload
+        : (typeof resultPayload?.content?.[0]?.text === "string"
+            ? resultPayload.content[0].text
+            : (typeof (event as any).content === "string"
+                ? (event as any).content
+                : String(resultPayload ?? "")));
+      recordToolInvocationError(event.toolName, errorText);
+    }
     if (event.toolName !== "ask_user_questions") return;
     const milestoneId = getDiscussionMilestoneId(process.cwd());
     const queueActive = isQueuePhaseActive();

package/src/resources/extensions/gsd/cache.ts

@@ -1,6 +1,6 @@
 // GSD Extension — Unified Cache Invalidation
 //
-// Three module-scoped caches exist across the GSD extension:
+// Three module-scoped read caches exist across the GSD extension:
 //   1. State cache (state.ts)  — memoized deriveState() result
 //   2. Path cache  (paths.ts)  — directory listing results (readdirSync)
 //   3. Parse cache (files.ts)  — parsed markdown file results
@@ -8,22 +8,33 @@
 // After any file write that changes .gsd/ contents, all three must be
 // invalidated together to prevent stale reads. This module provides a
 // single function that clears all three atomically.
+//
+// NOTE: The DB `artifacts` table is NOT included here. Earlier versions
+// called clearArtifacts() as part of this bundle (#793), intending to
+// force deriveState() to re-parse from disk when files were edited
+// out-of-band. But invalidateAllCaches() fires on every post-unit pass,
+// so bundling a DESTRUCTIVE `DELETE FROM artifacts` with routine cache
+// invalidation meant every row written by saveArtifactToDb / writeAndStore
+// was wiped within seconds — leaving the milestone completed on disk but
+// the `artifacts` table empty and the agent looping on "file exists but
+// DB record missing" recovery calls. If a call site genuinely needs the
+// artifact table cleared after an out-of-band file mutation, it should
+// invoke clearArtifacts() from gsd-db.js explicitly — do not add it back
+// here.
 
 import { invalidateStateCache } from './state.js';
 import { clearPathCache } from './paths.js';
 import { clearParseCache } from './files.js';
-import { clearArtifacts } from './gsd-db.js';
 
 /**
- * Invalidate all GSD runtime caches in one call.
+ * Invalidate all GSD runtime read caches in one call.
  *
  * Call this after file writes, milestone transitions, merge reconciliation,
  * or any operation that changes .gsd/ contents on disk. Forgetting to clear
- * any single cache causes stale reads (see #431, #793).
+ * any single cache causes stale reads (see #431).
  */
 export function invalidateAllCaches(): void {
   invalidateStateCache();
   clearPathCache();
   clearParseCache();
-  clearArtifacts();
 }

package/src/resources/extensions/gsd/commands/catalog.ts

@@ -15,7 +15,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 export const GSD_COMMAND_DESCRIPTION =
-  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications";
+  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -44,7 +44,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "model", desc: "Switch the active session model or open a picker" },
   { cmd: "mode", desc: "Switch workflow mode (solo/team)" },
   { cmd: "prefs", desc: "Manage preferences (model selection, timeouts, etc.)" },
-  { cmd: "config", desc: "Set API keys for external tools" },
+  { cmd: "config", desc: "(deprecated) Set tool API keys — use /gsd keys instead" },
   { cmd: "keys", desc: "API key manager — list, add, remove, test, rotate, doctor" },
   { cmd: "hooks", desc: "Show configured post-unit and pre-dispatch hooks" },
   { cmd: "run-hook", desc: "Manually trigger a specific hook" },
@@ -52,9 +52,11 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "notifications", desc: "View, filter, and clear persistent notification history" },
   { cmd: "doctor", desc: "Runtime health checks with auto-fix" },
   { cmd: "logs", desc: "Browse activity logs, debug logs, and metrics" },
+  { cmd: "debug", desc: "Create and inspect persistent /gsd debug sessions" },
   { cmd: "forensics", desc: "Examine execution logs" },
   { cmd: "init", desc: "Project init wizard — detect, configure, bootstrap .gsd/" },
-  { cmd: "setup", desc: "Global setup status and configuration" },
+  { cmd: "setup", desc: "Configuration hub: status + sub-routes (llm, model, search, remote, keys, prefs, onboarding)" },
+  { cmd: "onboarding", desc: "Re-run the setup wizard  [--resume|--reset|--step <name>]" },
   { cmd: "migrate", desc: "Migrate a v1 .planning directory to .gsd format" },
   { cmd: "remote", desc: "Control remote auto-mode" },
   { cmd: "steer", desc: "Hard-steer plan documents during execution" },
@@ -72,8 +74,16 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "fast", desc: "Toggle OpenAI service tier (on/off/flex/status)" },
   { cmd: "mcp", desc: "MCP server status, connectivity, and local config bootstrap (status, check, init)" },
   { cmd: "rethink", desc: "Conversational project reorganization — reorder, park, discard, add milestones" },
-  { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, validate, pause, resume)" },
+  { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, info, install, uninstall, validate, pause, resume) or run <name> directly" },
   { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache (.gsd/CODEBASE.md)" },
+  { cmd: "ship", desc: "Create PR from milestone artifacts and open for review" },
+  { cmd: "do", desc: "Route freeform text to the right GSD command" },
+  { cmd: "session-report", desc: "Session cost, tokens, and work summary" },
+  { cmd: "backlog", desc: "Manage backlog items (add, promote, remove, list)" },
+  { cmd: "pr-branch", desc: "Create clean PR branch filtering .gsd/ commits" },
+  { cmd: "add-tests", desc: "Generate tests for completed slices" },
+  { cmd: "scan", desc: "Rapid codebase assessment — lightweight alternative to full map (--focus tech|arch|quality|concerns|tech+arch)" },
+  { cmd: "language", desc: "Set or clear the global response language (e.g. /gsd language Chinese)" },
 ];
 
 const NESTED_COMPLETIONS: CompletionMap = {
@@ -106,11 +116,18 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "watch", desc: "Live TUI dashboard monitoring all workers" },
   ],
   setup: [
-    { cmd: "llm", desc: "Configure LLM provider settings" },
+    { cmd: "llm", desc: "Configure LLM provider & auth" },
+    { cmd: "model", desc: "Pick default model for the active provider" },
     { cmd: "search", desc: "Configure web search provider" },
-    { cmd: "remote", desc: "Configure remote integrations" },
-    { cmd: "keys", desc: "Manage API keys" },
-    { cmd: "prefs", desc: "Configure global preferences" },
+    { cmd: "remote", desc: "Configure remote integrations (Discord/Slack/Telegram)" },
+    { cmd: "keys", desc: "Manage API keys (alias for /gsd keys)" },
+    { cmd: "prefs", desc: "Global preferences wizard (alias for /gsd prefs)" },
+    { cmd: "onboarding", desc: "Run the full onboarding wizard (alias for /gsd onboarding)" },
+  ],
+  onboarding: [
+    { cmd: "--resume", desc: "Resume from the last completed step" },
+    { cmd: "--reset", desc: "Reset onboarding state and start over (does not clear API keys)" },
+    { cmd: "--step", desc: "Run a single step: llm|model|search|remote|tool-keys|prefs|skills|doctor|project" },
   ],
   notifications: [
     { cmd: "clear", desc: "Clear all notifications" },
@@ -122,6 +139,12 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "tail", desc: "Show last N activity log summaries" },
     { cmd: "clear", desc: "Remove old activity and debug logs" },
   ],
+  debug: [
+    { cmd: "list", desc: "List persisted debug sessions" },
+    { cmd: "status", desc: "Show status for one debug session slug" },
+    { cmd: "continue", desc: "Resume an existing debug session slug" },
+    { cmd: "--diagnose", desc: "Inspect malformed artifacts and session health" },
+  ],
   keys: [
     { cmd: "list", desc: "Show key status dashboard" },
     { cmd: "add", desc: "Add a key for a provider" },
@@ -228,8 +251,11 @@ const NESTED_COMPLETIONS: CompletionMap = {
   ],
   workflow: [
     { cmd: "new", desc: "Create a new workflow definition (via skill)" },
-    { cmd: "run", desc: "Create a run and start auto-mode" },
+    { cmd: "run", desc: "Create a YAML run and start auto-mode" },
     { cmd: "list", desc: "List workflow runs" },
+    { cmd: "info", desc: "Show plugin details (source, mode, phases)" },
+    { cmd: "install", desc: "Install a plugin from a URL / gist: / gh:" },
+    { cmd: "uninstall", desc: "Remove an installed plugin" },
     { cmd: "validate", desc: "Validate a workflow definition YAML" },
     { cmd: "pause", desc: "Pause custom workflow auto-mode" },
     { cmd: "resume", desc: "Resume paused custom workflow auto-mode" },
@@ -244,6 +270,36 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "stats", desc: "Show file count, description coverage, and generation time" },
     { cmd: "help", desc: "Show usage and available subcommands" },
   ],
+  ship: [
+    { cmd: "--dry-run", desc: "Preview PR without creating" },
+    { cmd: "--draft", desc: "Open as draft PR" },
+    { cmd: "--base", desc: "Override target branch (default: main)" },
+    { cmd: "--force", desc: "Ship even with pending tasks" },
+  ],
+  "session-report": [
+    { cmd: "--json", desc: "Machine-readable JSON output" },
+    { cmd: "--save", desc: "Save report to .gsd/reports/" },
+  ],
+  backlog: [
+    { cmd: "add", desc: "Add item to backlog" },
+    { cmd: "promote", desc: "Promote backlog item to active slice" },
+    { cmd: "remove", desc: "Remove backlog item" },
+  ],
+  "pr-branch": [
+    { cmd: "--dry-run", desc: "Preview what would be filtered" },
+    { cmd: "--name", desc: "Custom branch name" },
+  ],
+  scan: [
+    { cmd: "--focus tech", desc: "Technology stack and external integrations" },
+    { cmd: "--focus arch", desc: "Architecture patterns and directory structure" },
+    { cmd: "--focus quality", desc: "Coding conventions and testing patterns" },
+    { cmd: "--focus concerns", desc: "Technical debt and risk areas" },
+    { cmd: "--focus tech+arch", desc: "Tech + Architecture (default)" },
+  ],
+  language: [
+    { cmd: "off",   desc: "Clear the language preference (revert to default)" },
+    { cmd: "clear", desc: "Alias for off — clear the language preference" },
+  ],
 };
 
 function filterOptions(
@@ -369,6 +425,45 @@ export function getGsdArgumentCompletions(prefix: string) {
     return [];
   }
 
+  // Completion for `/gsd workflow info <name>` — list all discoverable plugins (project + global).
+  if (command === "workflow" && subcommand === "info" && parts.length <= 3) {
+    const results: GsdCommandDefinition[] = [];
+    const seen = new Set<string>();
+    const scanDir = (dir: string, source: string) => {
+      if (!existsSync(dir)) return;
+      try {
+        for (const f of readdirSync(dir)) {
+          if (!/\.(ya?ml|md)$/i.test(f)) continue;
+          const name = f.replace(/\.(ya?ml|md)$/i, "");
+          if (!name.startsWith(third)) continue;
+          if (seen.has(name)) continue;
+          seen.add(name);
+          results.push({ cmd: name, desc: `Workflow plugin (${source})` });
+        }
+      } catch { /* ignore */ }
+    };
+    try {
+      const base = resolveProjectRoot(process.cwd());
+      scanDir(join(base, ".gsd", "workflows"), "project");
+      scanDir(join(base, ".gsd", "workflow-defs"), "project-legacy");
+      scanDir(join(gsdHome, "workflows"), "global");
+    } catch { /* ignore */ }
+    // Also include bundled template names.
+    try {
+      const registry = loadRegistry();
+      for (const id of Object.keys(registry.templates)) {
+        if (seen.has(id) || !id.startsWith(third)) continue;
+        seen.add(id);
+        results.push({ cmd: id, desc: "Workflow plugin (bundled)" });
+      }
+    } catch { /* ignore */ }
+    return results.map((r) => ({
+      value: `workflow info ${r.cmd}`,
+      label: r.cmd,
+      description: r.desc,
+    }));
+  }
+
   const nested = NESTED_COMPLETIONS[command];
   if (nested && parts.length <= 2) {
     return filterOptions(subcommand, nested, command);