gsd-pi 2.37.0 → 2.37.1-dev.3bbb0a9

package/README.md

@@ -16,7 +16,7 @@ This version is different. GSD is now a standalone CLI built on the [Pi SDK](htt
 
 One command. Walk away. Come back to a built project with clean git history.
 
-<pre><code>npm install -g gsd-pi</code></pre>
+<pre><code>npm install -g gsd-pi@latest</code></pre>
 
 > **📋 NOTICE: New to Node on Mac?** If you installed Node.js via Homebrew, you may be running a development release instead of LTS. **[Read this guide](./docs/node-lts-macos.md)** to pin Node 24 LTS and avoid compatibility issues.
 
@@ -24,19 +24,19 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.33
+## What's New in v2.37
 
-- **Dispatch loop hardening** — defensive guards, reentrancy protection, and 125 new regression tests covering the full `deriveState → resolveDispatch` chain without an LLM
-- **Live regression test harness** — post-build pipeline validation that catches dispatch, parser, and lock lifecycle regressions before promotion
-- **Unified error handling** — `getErrorMessage()` helper replaces 65 inline duplicates across the codebase
-- **Centralized unit ID parsing** — `parseUnitId()` eliminates fragile regex patterns scattered across dispatch, recovery, and metrics code
-- **Milestone merge consolidation** — `tryMergeMilestone()` replaces 4 duplicate merge paths in the auto-mode loop
-- **Lock alignment fix** — retry lock path now matches primary lock settings, preventing `ECOMPROMISED` errors on resume
-- **NixOS/nix-darwin support** — symlinks in `.gsd/` are skipped during `makeTreeWritable` to prevent `EPERM` failures
-- **Windows EPERM fallback** — `.gsd/` migration uses copy+delete when NTFS blocks direct rename
-- **Worktree identity fix** — stable project hash resolved from main repo root, not worktree path
-- **Quick-task branch cleanup** — `/gsd quick` branches auto-merge back to the original branch after completion
-- **Crash recovery guidance** — actionable next-step messages based on what was interrupted and what state survived
+- **cmux integration** — sidebar status, progress bars, and notifications for [cmux](https://cmux.com) terminal multiplexer users
+- **Redesigned dashboard** — two-column layout with redesigned widget
+- **Search budget enforcement** — session-level search budget prevents unbounded native web search
+- **AGENTS.md support** — deprecated `agent-instructions.md` in favor of standard `AGENTS.md` / `CLAUDE.md`
+- **AI-powered triage** — automated issue and PR triage via Claude Haiku
+- **Auto-generated OpenRouter registry** — model registry built from OpenRouter API for always-current model support
+- **Extension manifest system** — user-managed enable/disable for bundled extensions
+- **Pipeline simplification (ADR-003)** — merged research into planning, mechanical completion
+- **Workflow templates** — right-sized workflows for every task type
+- **Health widget** — always-on environment health checks with progress scoring
+- **`/gsd changelog`** — LLM-summarized release notes for any version
 
 See the full [Changelog](./CHANGELOG.md) for details.
 
@@ -49,7 +49,7 @@ Full documentation is available 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
 - **[Configuration](./docs/configuration.md)** — all preferences, models, git, and hooks
-- **[Token Optimization](./docs/token-optimization.md)** — profiles, context compression, complexity routing (v2.17)
+- **[Token Optimization](./docs/token-optimization.md)** — profiles, context compression, complexity routing
 - **[Cost Management](./docs/cost-management.md)** — budgets, tracking, projections
 - **[Git Strategy](./docs/git-strategy.md)** — worktree isolation, branching, merge behavior
 - **[Parallel Orchestration](./docs/parallel-orchestration.md)** — run multiple milestones simultaneously
@@ -463,9 +463,9 @@ Place an `AGENTS.md` file in any directory to provide persistent behavioral guid
 
 Start GSD with `gsd --debug` to enable structured JSONL diagnostic logging. Debug logs capture dispatch decisions, state transitions, and timing data for troubleshooting auto-mode issues.
 
-### Token Optimization (v2.17)
+### Token Optimization
 
-GSD 2.17 introduced a coordinated token optimization system that reduces usage by 40-60% on cost-sensitive workloads. Set a single preference to coordinate model selection, phase skipping, and context compression:
+GSD includes a coordinated token optimization system that reduces usage by 40-60% on cost-sensitive workloads. Set a single preference to coordinate model selection, phase skipping, and context compression:
 
 ```yaml
 token_profile: budget      # or balanced (default), quality
@@ -485,7 +485,7 @@ See the full [Token Optimization Guide](./docs/token-optimization.md) for detail
 
 ### Bundled Tools
 
-GSD ships with 18 extensions, all loaded automatically:
+GSD ships with 19 extensions, all loaded automatically:
 
 | Extension              | What it provides                                                                                                       |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
@@ -495,12 +495,13 @@ GSD ships with 18 extensions, all loaded automatically:
 | **Google Search**      | Gemini-powered web search with AI-synthesized answers                                                                  |
 | **Context7**           | Up-to-date library/framework documentation                                                                             |
 | **Background Shell**   | Long-running process management with readiness detection                                                               |
+| **Async Jobs**         | Background bash commands with job tracking and cancellation                                                            |
 | **Subagent**           | Delegated tasks with isolated context windows                                                                          |
+| **GitHub**             | Full-suite GitHub issues and PR management via `/gh` command                                                           |
 | **Mac Tools**          | macOS native app automation via Accessibility APIs                                                                     |
 | **MCP Client**         | Native MCP server integration via @modelcontextprotocol/sdk                                                            |
 | **Voice**              | Real-time speech-to-text transcription (macOS, Linux — Ubuntu 22.04+)                                                  |
 | **Slash Commands**     | Custom command creation                                                                                                |
-| **LSP**                | Language Server Protocol integration — diagnostics, go-to-definition, references, hover, symbols, rename, code actions |
 | **Ask User Questions** | Structured user input with single/multi-select                                                                         |
 | **Secure Env Collect** | Masked secret collection without manual .env editing                                                                   |
 | **Remote Questions**   | Route decisions to Slack/Discord when human input is needed in headless/CI mode                                         |
@@ -591,7 +592,7 @@ gsd (CLI binary)
           ├─ resource-loader.ts  Syncs bundled extensions + agents to ~/.gsd/agent/
           └─ src/resources/
               ├─ extensions/gsd/    Core GSD extension (auto, state, commands, ...)
-              ├─ extensions/...     12 supporting extensions
+              ├─ extensions/...     18 supporting extensions
               ├─ agents/            scout, researcher, worker
               ├─ AGENTS.md          Agent routing instructions
               └─ GSD-WORKFLOW.md    Manual bootstrap protocol
@@ -628,7 +629,7 @@ GSD isn't locked to one provider. It runs on the [Pi SDK](https://github.com/bad
 
 ### Built-in Providers
 
-Anthropic, OpenAI, Google (Gemini), OpenRouter, GitHub Copilot, Amazon Bedrock, Azure OpenAI, Google Vertex, Groq, Cerebras, Mistral, xAI, HuggingFace, Vercel AI Gateway, and more.
+Anthropic, Anthropic (Vertex AI), OpenAI, Google (Gemini), OpenRouter, GitHub Copilot, Amazon Bedrock, Azure OpenAI, Google Vertex, Groq, Cerebras, Mistral, xAI, HuggingFace, Vercel AI Gateway, and more.
 
 ### OAuth / Max Plans
 

package/dist/onboarding.js

@@ -38,6 +38,7 @@ const TOOL_KEYS = [
 /** Known LLM provider IDs that, if authed, mean the user doesn't need onboarding */
 const LLM_PROVIDER_IDS = [
     'anthropic',
+    'anthropic-vertex',
     'openai',
     'github-copilot',
     'openai-codex',

package/dist/resources/extensions/cmux/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@gsd/cmux",
+  "private": true,
+  "type": "module",
+  "description": "cmux integration library — used by other extensions, not an extension itself",
+  "pi": {}
+}

package/dist/resources/extensions/gsd/auto-dispatch.js

@@ -12,7 +12,7 @@ import { loadFile, loadActiveOverrides, parseRoadmap } from "./files.js";
 import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveTaskFile, relSliceFile, buildMilestoneFileName, } from "./paths.js";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { buildResearchMilestonePrompt, buildPlanMilestonePrompt, buildResearchSlicePrompt, buildPlanSlicePrompt, buildExecuteTaskPrompt, buildCompleteSlicePrompt, buildCompleteMilestonePrompt, buildValidateMilestonePrompt, buildReplanSlicePrompt, buildRunUatPrompt, buildReassessRoadmapPrompt, buildRewriteDocsPrompt, checkNeedsReassessment, checkNeedsRunUat, } from "./auto-prompts.js";
+import { buildResearchMilestonePrompt, buildPlanMilestonePrompt, buildResearchSlicePrompt, buildPlanSlicePrompt, buildExecuteTaskPrompt, buildCompleteSlicePrompt, buildCompleteMilestonePrompt, buildValidateMilestonePrompt, buildReplanSlicePrompt, buildRunUatPrompt, buildReassessRoadmapPrompt, buildRewriteDocsPrompt, buildReactiveExecutePrompt, checkNeedsReassessment, checkNeedsRunUat, } from "./auto-prompts.js";
 function missingSliceStop(mid, phase) {
     return {
         action: "stop",
@@ -223,6 +223,72 @@ const DISPATCH_RULES = [
             };
         },
     },
+    {
+        name: "executing → reactive-execute (parallel dispatch)",
+        match: async ({ state, mid, midTitle, basePath, prefs }) => {
+            if (state.phase !== "executing" || !state.activeTask)
+                return null;
+            if (!state.activeSlice)
+                return null; // fall through
+            // Only activate when reactive_execution is explicitly enabled
+            const reactiveConfig = prefs?.reactive_execution;
+            if (!reactiveConfig?.enabled)
+                return null;
+            const sid = state.activeSlice.id;
+            const sTitle = state.activeSlice.title;
+            const maxParallel = reactiveConfig.max_parallel ?? 2;
+            // Dry-run mode: max_parallel=1 means graph is derived and logged but
+            // execution remains sequential
+            if (maxParallel <= 1)
+                return null;
+            try {
+                const { loadSliceTaskIO, deriveTaskGraph, isGraphAmbiguous, getReadyTasks, chooseNonConflictingSubset, graphMetrics, } = await import("./reactive-graph.js");
+                const taskIO = await loadSliceTaskIO(basePath, mid, sid);
+                if (taskIO.length < 2)
+                    return null; // single task, no point
+                const graph = deriveTaskGraph(taskIO);
+                // Ambiguous graph → fall through to sequential
+                if (isGraphAmbiguous(graph))
+                    return null;
+                const completed = new Set(graph.filter((n) => n.done).map((n) => n.id));
+                const readyIds = getReadyTasks(graph, completed, new Set());
+                // Only activate reactive dispatch when >1 task is ready
+                if (readyIds.length <= 1)
+                    return null;
+                const selected = chooseNonConflictingSubset(readyIds, graph, maxParallel, new Set());
+                if (selected.length <= 1)
+                    return null;
+                // Log graph metrics for observability
+                const metrics = graphMetrics(graph);
+                process.stderr.write(`gsd-reactive: ${mid}/${sid} graph — tasks:${metrics.taskCount} edges:${metrics.edgeCount} ` +
+                    `ready:${metrics.readySetSize} dispatching:${selected.length} ambiguous:${metrics.ambiguous}\n`);
+                // Persist dispatched batch so verification and recovery can check
+                // exactly which tasks were sent.
+                const { saveReactiveState } = await import("./reactive-graph.js");
+                saveReactiveState(basePath, mid, sid, {
+                    sliceId: sid,
+                    completed: [...completed],
+                    dispatched: selected,
+                    graphSnapshot: metrics,
+                    updatedAt: new Date().toISOString(),
+                });
+                // Encode selected task IDs in unitId for artifact verification.
+                // Format: M001/S01/reactive+T02,T03
+                const batchSuffix = selected.join(",");
+                return {
+                    action: "dispatch",
+                    unitType: "reactive-execute",
+                    unitId: `${mid}/${sid}/reactive+${batchSuffix}`,
+                    prompt: await buildReactiveExecutePrompt(mid, midTitle, sid, sTitle, selected, basePath),
+                };
+            }
+            catch (err) {
+                // Non-fatal — fall through to sequential execution
+                process.stderr.write(`gsd-reactive: graph derivation failed: ${err.message}\n`);
+                return null;
+            }
+        },
+    },
     {
         name: "executing → execute-task (recover missing task plan → plan-slice)",
         match: async ({ state, mid, midTitle, basePath }) => {

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

@@ -218,10 +218,24 @@ export async function autoLoop(ctx, pi, s, deps) {
         }
         try {
             // ── Blanket try/catch: one bad iteration must not kill the session
-            if (deps.lockBase() && !deps.validateSessionLock(deps.lockBase())) {
-                deps.handleLostSessionLock(ctx);
-                debugLog("autoLoop", { phase: "exit", reason: "session-lock-lost" });
-                break;
+            const sessionLockBase = deps.lockBase();
+            if (sessionLockBase) {
+                const lockStatus = deps.validateSessionLock(sessionLockBase);
+                if (!lockStatus.valid) {
+                    debugLog("autoLoop", {
+                        phase: "session-lock-invalid",
+                        reason: lockStatus.failureReason ?? "unknown",
+                        existingPid: lockStatus.existingPid,
+                        expectedPid: lockStatus.expectedPid,
+                    });
+                    deps.handleLostSessionLock(ctx, lockStatus);
+                    debugLog("autoLoop", {
+                        phase: "exit",
+                        reason: "session-lock-lost",
+                        detail: lockStatus.failureReason ?? "unknown",
+                    });
+                    break;
+                }
             }
             // ── Phase 1: Pre-dispatch ───────────────────────────────────────────
             // Resource version guard

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -171,6 +171,20 @@ export async function postUnitPreVerification(pctx) {
                 // Non-fatal
             }
         }
+        // Reactive state cleanup on slice completion
+        if (s.currentUnit.type === "complete-slice") {
+            try {
+                const parts = s.currentUnit.id.split("/");
+                const [mid, sid] = parts;
+                if (mid && sid) {
+                    const { clearReactiveState } = await import("./reactive-graph.js");
+                    clearReactiveState(s.basePath, mid, sid);
+                }
+            }
+            catch {
+                // Non-fatal
+            }
+        }
         // Post-triage: execute actionable resolutions
         if (s.currentUnit.type === "triage-captures") {
             try {

package/dist/resources/extensions/gsd/auto-prompts.js

@@ -414,6 +414,35 @@ export async function getPriorTaskSummaryPaths(mid, sid, currentTid, base) {
     })
         .map(f => `${sRel}/tasks/${f}`);
 }
+/**
+ * Get carry-forward summary paths scoped to a task's derived dependencies.
+ *
+ * Instead of all prior tasks (order-based), returns only summaries for task
+ * IDs in `dependsOn`. Used by reactive-execute to give each subagent only
+ * the context it actually needs — not sibling tasks from a parallel batch.
+ *
+ * Falls back to order-based when dependsOn is empty (root tasks still get
+ * any available prior summaries for continuity).
+ */
+export async function getDependencyTaskSummaryPaths(mid, sid, currentTid, dependsOn, base) {
+    // If no dependencies, fall back to order-based for root tasks
+    if (dependsOn.length === 0) {
+        return getPriorTaskSummaryPaths(mid, sid, currentTid, base);
+    }
+    const tDir = resolveTasksDir(base, mid, sid);
+    if (!tDir)
+        return [];
+    const summaryFiles = resolveTaskFiles(tDir, "SUMMARY");
+    const sRel = relSlicePath(base, mid, sid);
+    const depSet = new Set(dependsOn.map((d) => d.toUpperCase()));
+    return summaryFiles
+        .filter((f) => {
+        // Extract task ID from filename: "T02-SUMMARY.md" → "T02"
+        const tid = f.replace(/-SUMMARY\.md$/i, "").toUpperCase();
+        return depSet.has(tid);
+    })
+        .map((f) => `${sRel}/tasks/${f}`);
+}
 // ─── Adaptive Replanning Checks ────────────────────────────────────────────
 /**
  * Check if the most recently completed slice needs reassessment.
@@ -688,8 +717,11 @@ export async function buildPlanSlicePrompt(mid, _midTitle, sid, sTitle, base, le
     });
 }
 export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base, level) {
-    const inlineLevel = level ?? resolveInlineLevel();
-    const priorSummaries = await getPriorTaskSummaryPaths(mid, sid, tid, base);
+    const opts = typeof level === "object" && level !== null && !Array.isArray(level)
+        ? level
+        : { level: level };
+    const inlineLevel = opts.level ?? resolveInlineLevel();
+    const priorSummaries = opts.carryForwardPaths ?? await getPriorTaskSummaryPaths(mid, sid, tid, base);
     const priorLines = priorSummaries.length > 0
         ? priorSummaries.map(p => `- \`${p}\``).join("\n")
         : "- (no prior tasks)";
@@ -1090,6 +1122,63 @@ export async function buildReassessRoadmapPrompt(mid, midTitle, completedSliceId
         commitInstruction: reassessCommitInstruction,
     });
 }
+// ─── Reactive Execute Prompt ──────────────────────────────────────────────
+export async function buildReactiveExecutePrompt(mid, midTitle, sid, sTitle, readyTaskIds, base) {
+    const { loadSliceTaskIO, deriveTaskGraph, graphMetrics } = await import("./reactive-graph.js");
+    // Build graph for context
+    const taskIO = await loadSliceTaskIO(base, mid, sid);
+    const graph = deriveTaskGraph(taskIO);
+    const metrics = graphMetrics(graph);
+    // Build graph context section
+    const graphLines = [];
+    for (const node of graph) {
+        const status = node.done ? "✅ done" : readyTaskIds.includes(node.id) ? "🟢 ready" : "⏳ waiting";
+        const deps = node.dependsOn.length > 0 ? ` (depends on: ${node.dependsOn.join(", ")})` : "";
+        graphLines.push(`- **${node.id}: ${node.title}** — ${status}${deps}`);
+        if (node.outputFiles.length > 0) {
+            graphLines.push(`  - Outputs: ${node.outputFiles.map(f => `\`${f}\``).join(", ")}`);
+        }
+    }
+    const graphContext = [
+        `Tasks: ${metrics.taskCount}, Edges: ${metrics.edgeCount}, Ready: ${metrics.readySetSize}`,
+        "",
+        ...graphLines,
+    ].join("\n");
+    // Build individual subagent prompts for each ready task
+    const subagentSections = [];
+    const readyTaskListLines = [];
+    for (const tid of readyTaskIds) {
+        const node = graph.find((n) => n.id === tid);
+        const tTitle = node?.title ?? tid;
+        readyTaskListLines.push(`- **${tid}: ${tTitle}**`);
+        // Build dependency-scoped carry-forward paths for this task
+        const depPaths = await getDependencyTaskSummaryPaths(mid, sid, tid, node?.dependsOn ?? [], base);
+        // Build a full execute-task prompt with dependency-based carry-forward
+        const taskPrompt = await buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base, { carryForwardPaths: depPaths });
+        subagentSections.push([
+            `### ${tid}: ${tTitle}`,
+            "",
+            "Use this as the prompt for a `subagent` call:",
+            "",
+            "```",
+            taskPrompt,
+            "```",
+        ].join("\n"));
+    }
+    const inlinedTemplates = inlineTemplate("task-summary", "Task Summary");
+    return loadPrompt("reactive-execute", {
+        workingDirectory: base,
+        milestoneId: mid,
+        milestoneTitle: midTitle,
+        sliceId: sid,
+        sliceTitle: sTitle,
+        graphContext,
+        readyTaskCount: String(readyTaskIds.length),
+        readyTaskList: readyTaskListLines.join("\n"),
+        subagentPrompts: subagentSections.join("\n\n---\n\n"),
+        inlinedTemplates,
+    });
+}
 export async function buildRewriteDocsPrompt(mid, midTitle, activeSlice, base, overrides) {
     const sid = activeSlice?.id;
     const sTitle = activeSlice?.title ?? "";

package/dist/resources/extensions/gsd/auto-recovery.js

@@ -11,7 +11,7 @@ import { clearUnitRuntimeRecord } from "./unit-runtime.js";
 import { clearParseCache, parseRoadmap, parsePlan } from "./files.js";
 import { isValidationTerminal } from "./state.js";
 import { nativeConflictFiles, nativeCommit, nativeCheckoutTheirs, nativeAddPaths, nativeMergeAbort, nativeResetHard, } from "./native-git-bridge.js";
-import { resolveMilestonePath, resolveSlicePath, resolveSliceFile, resolveTasksDir, relMilestoneFile, relSliceFile, relSlicePath, relTaskFile, buildMilestoneFileName, buildSliceFileName, buildTaskFileName, resolveMilestoneFile, clearPathCache, resolveGsdRootFile, } from "./paths.js";
+import { resolveMilestonePath, resolveSlicePath, resolveSliceFile, resolveTasksDir, resolveTaskFiles, relMilestoneFile, relSliceFile, relSlicePath, relTaskFile, buildMilestoneFileName, buildSliceFileName, buildTaskFileName, resolveMilestoneFile, clearPathCache, resolveGsdRootFile, } from "./paths.js";
 import { markSliceDoneInRoadmap } from "./roadmap-mutations.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, } from "node:fs";
 import { dirname, join } from "node:path";
@@ -73,6 +73,9 @@ export function resolveExpectedArtifactPath(unitType, unitId, base) {
         }
         case "rewrite-docs":
             return null;
+        case "reactive-execute":
+            // Reactive execute produces multiple task summaries — verified separately
+            return null;
         default:
             return null;
     }
@@ -105,6 +108,39 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
         const content = readFileSync(overridesPath, "utf-8");
         return !content.includes("**Scope:** active");
     }
+    // Reactive-execute: verify that each dispatched task's summary exists.
+    // The unitId encodes the batch: "{mid}/{sid}/reactive+T02,T03"
+    if (unitType === "reactive-execute") {
+        const parts = unitId.split("/");
+        const mid = parts[0];
+        const sidAndBatch = parts[1];
+        const batchPart = parts[2]; // "reactive+T02,T03"
+        if (!mid || !sidAndBatch || !batchPart)
+            return false;
+        const sid = sidAndBatch;
+        const plusIdx = batchPart.indexOf("+");
+        if (plusIdx === -1) {
+            // Legacy format "reactive" without batch IDs — fall back to "any summary"
+            const tDir = resolveTasksDir(base, mid, sid);
+            if (!tDir)
+                return false;
+            const summaryFiles = resolveTaskFiles(tDir, "SUMMARY");
+            return summaryFiles.length > 0;
+        }
+        const batchIds = batchPart.slice(plusIdx + 1).split(",").filter(Boolean);
+        if (batchIds.length === 0)
+            return false;
+        const tDir = resolveTasksDir(base, mid, sid);
+        if (!tDir)
+            return false;
+        const existingSummaries = new Set(resolveTaskFiles(tDir, "SUMMARY").map((f) => f.replace(/-SUMMARY\.md$/i, "").toUpperCase()));
+        // Every dispatched task must have a summary file
+        for (const tid of batchIds) {
+            if (!existingSummaries.has(tid.toUpperCase()))
+                return false;
+        }
+        return true;
+    }
     const absPath = resolveExpectedArtifactPath(unitType, unitId, base);
     // For unit types with no verifiable artifact (null path), the parent directory
     // is missing on disk — treat as stale completion state so the key gets evicted (#313).

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

@@ -18,7 +18,7 @@ import { invalidateAllCaches } from "./cache.js";
 import { clearActivityLogState } from "./activity-log.js";
 import { synthesizeCrashRecovery, getDeepDiagnostic, } from "./session-forensics.js";
 import { writeLock, clearLock, readCrashLock, isLockProcessAlive, } from "./crash-recovery.js";
-import { acquireSessionLock, validateSessionLock, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
+import { acquireSessionLock, getSessionLockStatus, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
 import { clearUnitRuntimeRecord, readUnitRuntimeRecord, writeUnitRuntimeRecord, } from "./unit-runtime.js";
 import { resolveAutoSupervisorConfig, loadEffectiveGSDPreferences, getIsolationMode, } from "./preferences.js";
 import { sendDesktopNotification } from "./notifications.js";
@@ -209,6 +209,29 @@ export function stopAutoRemote(projectRoot) {
         return { found: false, error: err.message };
     }
 }
+/**
+ * Check if a remote auto-mode session is running (from a different process).
+ * Reads the crash lock, checks PID liveness, and returns session details.
+ * Used by the guard in commands.ts to prevent bare /gsd, /gsd next, and
+ * /gsd auto from stealing the session lock.
+ */
+export function checkRemoteAutoSession(projectRoot) {
+    const lock = readCrashLock(projectRoot);
+    if (!lock)
+        return { running: false };
+    if (!isLockProcessAlive(lock)) {
+        // Stale lock from a dead process — not a live remote session
+        return { running: false };
+    }
+    return {
+        running: true,
+        pid: lock.pid,
+        unitType: lock.unitType,
+        unitId: lock.unitId,
+        startedAt: lock.startedAt,
+        completedUnits: lock.completedUnits,
+    };
+}
 export function isStepMode() {
     return s.stepMode;
 }
@@ -243,14 +266,28 @@ function buildSnapshotOpts(unitType, unitId) {
         ...(runtime?.continueHereFired ? { continueHereFired: true } : {}),
     };
 }
-function handleLostSessionLock(ctx) {
-    debugLog("session-lock-lost", { lockBase: lockBase() });
+function handleLostSessionLock(ctx, lockStatus) {
+    debugLog("session-lock-lost", {
+        lockBase: lockBase(),
+        reason: lockStatus?.failureReason,
+        existingPid: lockStatus?.existingPid,
+        expectedPid: lockStatus?.expectedPid,
+    });
     s.active = false;
     s.paused = false;
     clearUnitTimeout();
     deregisterSigtermHandler();
     clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences);
-    ctx?.ui.notify("Session lock lost — another GSD process appears to have taken over. Stopping gracefully.", "error");
+    const message = lockStatus?.failureReason === "pid-mismatch"
+        ? lockStatus.existingPid
+            ? `Session lock moved to PID ${lockStatus.existingPid} — another GSD process appears to have taken over. Stopping gracefully.`
+            : "Session lock moved to a different process — another GSD process appears to have taken over. Stopping gracefully."
+        : lockStatus?.failureReason === "missing-metadata"
+            ? "Session lock metadata disappeared, so ownership could not be confirmed. Stopping gracefully."
+            : lockStatus?.failureReason === "compromised"
+                ? "Session lock was compromised or invalidated during heartbeat checks; takeover was not confirmed. Stopping gracefully."
+                : "Session lock lost. Stopping gracefully.";
+    ctx?.ui.notify(message, "error");
     ctx?.ui.setStatus("gsd-auto", undefined);
     ctx?.ui.setWidget("gsd-progress", undefined);
     ctx?.ui.setFooter(undefined);
@@ -473,7 +510,7 @@ function buildLoopDeps() {
         // Resource version guard
         checkResourcesStale,
         // Session lock
-        validateSessionLock,
+        validateSessionLock: getSessionLockStatus,
         updateSessionLock,
         handleLostSessionLock,
         // Milestone transition