gsd-pi 2.79.0 → 2.80.0-dev.0aaa4fc17

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -1,7 +1,9 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { minimatch } from "minimatch";
+import { getIsolationMode } from "../preferences.js";
 import { logWarning } from "../workflow-logger.js";
+import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
  * and unique M001-abc123 formats. Exported so regex-hardening tests
@@ -298,8 +300,8 @@ export function getPendingGate(basePath = process.cwd()) {
  * Returns { block: true, reason } if the tool should be blocked.
  * ask_user_questions itself is allowed so the model can re-ask the gate.
  */
-export function shouldBlockPendingGate(toolName, milestoneId, queuePhaseActive) {
-    return shouldBlockPendingGateInSnapshot(currentWriteGateSnapshot(), toolName, milestoneId, queuePhaseActive);
+export function shouldBlockPendingGate(toolName, milestoneId, queuePhaseActive, basePath = process.cwd()) {
+    return shouldBlockPendingGateInSnapshot(currentWriteGateSnapshot(basePath), toolName, milestoneId, queuePhaseActive);
 }
 export function shouldBlockPendingGateInSnapshot(snapshot, toolName, _milestoneId, _queuePhaseActive) {
     if (!snapshot.pendingGateId)
@@ -322,8 +324,8 @@ export function shouldBlockPendingGateInSnapshot(snapshot, toolName, _milestoneI
  * Check whether a bash command should be blocked because a discussion gate is pending.
  * All bash is blocked while waiting for confirmation so the question stays visible.
  */
-export function shouldBlockPendingGateBash(command, milestoneId, queuePhaseActive) {
-    return shouldBlockPendingGateBashInSnapshot(currentWriteGateSnapshot(), command, milestoneId, queuePhaseActive);
+export function shouldBlockPendingGateBash(command, milestoneId, queuePhaseActive, basePath = process.cwd()) {
+    return shouldBlockPendingGateBashInSnapshot(currentWriteGateSnapshot(basePath), command, milestoneId, queuePhaseActive);
 }
 export function shouldBlockPendingGateBashInSnapshot(snapshot, command, _milestoneId, _queuePhaseActive) {
     if (!snapshot.pendingGateId)
@@ -363,7 +365,7 @@ export function isDepthConfirmationAnswer(selected, options) {
     // Returning false prevents any free-form string from unlocking the gate.
     return false;
 }
-export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queuePhaseActive) {
+export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queuePhaseActive, basePath = process.cwd()) {
     if (toolName !== "write")
         return { block: false };
     if (!MILESTONE_CONTEXT_RE.test(inputPath))
@@ -379,7 +381,7 @@ export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queue
             ].join(" "),
         };
     }
-    if (isMilestoneDepthVerified(targetMilestoneId))
+    if (isMilestoneDepthVerified(targetMilestoneId, basePath))
         return { block: false };
     return {
         block: true,
@@ -397,8 +399,8 @@ export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queue
  * Slice-level CONTEXT artifacts are allowed; milestone-level CONTEXT writes
  * require the milestone to be depth-verified first.
  */
-export function shouldBlockContextArtifactSave(artifactType, milestoneId, sliceId) {
-    return shouldBlockContextArtifactSaveInSnapshot(currentWriteGateSnapshot(), artifactType, milestoneId, sliceId);
+export function shouldBlockContextArtifactSave(artifactType, milestoneId, sliceId, basePath = process.cwd()) {
+    return shouldBlockContextArtifactSaveInSnapshot(currentWriteGateSnapshot(basePath), artifactType, milestoneId, sliceId);
 }
 export function shouldBlockContextArtifactSaveInSnapshot(snapshot, artifactType, milestoneId, sliceId) {
     if (artifactType !== "CONTEXT")
@@ -728,3 +730,129 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
     // avoids breaking gsd_* MCP tools or future safe additions.
     return { block: false };
 }
+// ─── Worktree isolation write gate (#5199) ────────────────────────────────
+//
+// When `git.isolation: worktree` is configured, the per-unit commit pipeline
+// only runs inside the auto-mode loop (`auto-post-unit.ts`). If the LLM
+// authors code at the project root before auto-mode is started, those writes
+// land in the working tree but never reach a commit — they're silently
+// orphaned outside git history. This guard blocks those writes at the
+// tool_call seam so the agent receives a clear error instead.
+const WORKTREE_GATE_BOOTSTRAP_UNITS = new Set([
+    "discuss-milestone",
+    "plan-milestone",
+    "init",
+]);
+function realpathOrResolve(p) {
+    const abs = resolve(p);
+    try {
+        return realpathSync(abs);
+    }
+    catch {
+        // Path doesn't exist (yet) — realpath the deepest existing ancestor so
+        // platforms where /tmp -> /private/tmp don't break containment checks.
+        let dir = abs;
+        const tail = [];
+        while (dir && dir !== resolve(dir, "..")) {
+            try {
+                const real = realpathSync(dir);
+                return tail.length ? join(real, ...tail.reverse()) : real;
+            }
+            catch {
+                const idx = dir.lastIndexOf(sep);
+                if (idx <= 0)
+                    break;
+                tail.push(dir.slice(idx + 1));
+                dir = dir.slice(0, idx) || sep;
+            }
+        }
+        return abs;
+    }
+}
+function isPathContained(target, container) {
+    if (target === container)
+        return true;
+    return target.startsWith(container.endsWith(sep) ? container : container + sep);
+}
+/**
+ * Block planning-write tool calls that would land code at the project root
+ * while `git.isolation: worktree` is in effect and auto-mode hasn't created
+ * (or flipped cwd into) the milestone worktree.
+ *
+ * Pure / unit-testable. Callers in `register-hooks.ts` supply the resolved
+ * project root and current auto liveness; this function does no I/O beyond
+ * realpath resolution.
+ *
+ * Allow rules (in order):
+ *   1. Tool isn't a planning-write (write/edit/multi_edit/notebook_edit).
+ *   2. `GSD_DISABLE_WORKTREE_WRITE_GUARD=1` self-hosting bypass.
+ *   3. Isolation mode is not "worktree".
+ *   4. Active unit is a bootstrap unit (discuss-milestone/plan-milestone/init).
+ *   5. Target is inside `<projectRoot>/.gsd/worktrees/` (a real worktree).
+ *   6. Target is inside `<projectRoot>/.gsd/` and isn't masquerading as a
+ *      worktrees sibling (rejects the `.gsd/worktrees-extra/…` prefix trick).
+ *   7. Auto is live AND `effectiveBasePath` is itself a `.gsd/worktrees/…` path.
+ *
+ * Otherwise: block with a message that points the agent at `/gsd` to start
+ * auto-mode.
+ */
+export function shouldBlockWorktreeWrite(toolName, targetPath, effectiveBasePath, isAutoLive, currentUnitType) {
+    const tool = canonicalToolName(toolName);
+    if (!PLANNING_WRITE_TOOLS.has(tool))
+        return { block: false };
+    if (process.env.GSD_DISABLE_WORKTREE_WRITE_GUARD === "1")
+        return { block: false };
+    if (getIsolationMode(effectiveBasePath) !== "worktree")
+        return { block: false };
+    if (currentUnitType && WORKTREE_GATE_BOOTSTRAP_UNITS.has(currentUnitType))
+        return { block: false };
+    if (!targetPath) {
+        return {
+            block: true,
+            reason: [
+                `HARD BLOCK: ${tool} called with empty path while \`git.isolation: worktree\` is configured`,
+                `and auto-mode is not active. Refusing to allow writes that cannot be located.`,
+            ].join(" "),
+        };
+    }
+    // Resolve the target relative to the project root, then realpath to defeat
+    // symlink-based escapes and prefix tricks (e.g. .gsd/worktrees-extra/).
+    const projectRoot = resolveWorktreeProjectRoot(effectiveBasePath);
+    const absTarget = isAbsolute(targetPath) ? targetPath : resolve(projectRoot, targetPath);
+    const realTarget = realpathOrResolve(absTarget);
+    const realRoot = realpathOrResolve(projectRoot);
+    const realGsd = realpathOrResolve(join(projectRoot, ".gsd"));
+    const realWorktreesDir = realpathOrResolve(join(projectRoot, ".gsd", "worktrees"));
+    // Allow writes inside the legitimate worktrees subtree.
+    if (isPathContained(realTarget, realWorktreesDir))
+        return { block: false };
+    // Allow writes to .gsd/ planning artifacts, but reject siblings whose name
+    // starts with "worktrees" (the worktrees-extra prefix trick — case 4).
+    if (isPathContained(realTarget, realGsd)) {
+        const rel = relative(realGsd, realTarget);
+        const firstSeg = rel.split(/[\/\\]/)[0] ?? "";
+        if (!firstSeg.startsWith("worktrees"))
+            return { block: false };
+        // fall through: looks like worktrees<something> sibling — block
+    }
+    // Auto is live and the caller is operating inside a worktree path —
+    // host tool's write happens in worktree context; let it through.
+    if (isAutoLive && isGsdWorktreePath(effectiveBasePath))
+        return { block: false };
+    // Block. Provide enough context that the agent can self-correct.
+    const displayTarget = isPathContained(realTarget, realRoot)
+        ? relative(realRoot, realTarget) || "."
+        : realTarget;
+    return {
+        block: true,
+        reason: [
+            `HARD BLOCK: Worktree isolation is configured (\`git.isolation: worktree\`) but auto-mode is`,
+            `not running and the target "${displayTarget}" is not inside \`.gsd/worktrees/<MID>/\`.`,
+            `Code edits at the project root would be lost — only the auto-mode commit pipeline`,
+            `(auto-post-unit) commits work, and it never runs outside the loop.`,
+            `Required action: start auto-mode with \`/gsd\` so the milestone worktree is created,`,
+            `then write inside it. To disable this guard for self-hosting development, set`,
+            `GSD_DISABLE_WORKTREE_WRITE_GUARD=1.`,
+        ].join(" "),
+    };
+}

package/dist/resources/extensions/gsd/clean-root-preflight.js

@@ -16,6 +16,31 @@ import { execFileSync } from "node:child_process";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { logWarning } from "./workflow-logger.js";
 import { nativeHasChanges } from "./native-git-bridge.js";
+function findPreflightStashRef(basePath, milestoneId, stashMarker) {
+    const markerPrefix = `gsd-preflight-stash:${milestoneId}:`;
+    let fallbackRef = null;
+    try {
+        const list = execFileSync("git", ["stash", "list", "--format=%gd%x00%s"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+            env: GIT_NO_PROMPT_ENV,
+        });
+        for (const line of list.split("\n")) {
+            const [ref, subject] = line.split("\x00");
+            if (!ref || !subject)
+                continue;
+            if (stashMarker && subject.includes(stashMarker))
+                return ref;
+            if (!fallbackRef && subject.includes(markerPrefix))
+                fallbackRef = ref;
+        }
+    }
+    catch (err) {
+        logWarning("preflight", `stash list failed before restore: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return fallbackRef;
+}
 /**
  * Check the working tree for dirty files before a milestone merge.
  *
@@ -47,7 +72,8 @@ export function preflightCleanRoot(basePath, milestoneId, notify) {
     notify(warnMsg, "warning");
     // Push the stash
     try {
-        execFileSync("git", ["stash", "push", "--include-untracked", "-m", "gsd-preflight-stash"], {
+        const stashMarker = `gsd-preflight-stash:${milestoneId}:${process.pid}:${Date.now()}:${process.hrtime.bigint().toString(36)}`;
+        execFileSync("git", ["stash", "push", "--include-untracked", "-m", `gsd-preflight-stash [${stashMarker}]`], {
             cwd: basePath,
             stdio: ["ignore", "pipe", "pipe"],
             encoding: "utf-8",
@@ -55,6 +81,7 @@ export function preflightCleanRoot(basePath, milestoneId, notify) {
         });
         return {
             stashPushed: true,
+            stashMarker,
             summary: `Stashed uncommitted changes before merge (milestone ${milestoneId}).`,
         };
     }
@@ -73,9 +100,17 @@ export function preflightCleanRoot(basePath, milestoneId, notify) {
  * Any pop error (e.g. conflict) is logged and notified but does NOT throw —
  * the merge already completed successfully.
  */
-export function postflightPopStash(basePath, milestoneId, notify) {
+export function postflightPopStash(basePath, milestoneId, stashMarker, notify) {
+    let stashRef = null;
     try {
-        execFileSync("git", ["stash", "pop"], {
+        stashRef = findPreflightStashRef(basePath, milestoneId, stashMarker);
+        if (!stashRef) {
+            const msg = `No matching GSD preflight stash found for milestone ${milestoneId}; leaving stash list untouched.`;
+            logWarning("preflight", msg);
+            notify(msg, "warning");
+            return;
+        }
+        execFileSync("git", ["stash", "pop", stashRef], {
             cwd: basePath,
             stdio: ["ignore", "pipe", "pipe"],
             encoding: "utf-8",
@@ -86,7 +121,10 @@ export function postflightPopStash(basePath, milestoneId, notify) {
     catch (err) {
         // Pop conflicts mean the merged code collides with the stashed changes.
         // Log a warning — the user needs to resolve manually, but the merge succeeded.
-        const msg = `git stash pop failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. Run "git stash pop" manually to restore your changes.`;
+        const restoreHint = stashRef
+            ? `Run "git stash pop ${stashRef}" or "git stash apply ${stashRef}" manually to restore the correct stash.`
+            : `Run "git stash list" to find the matching GSD preflight stash before restoring manually.`;
+        const msg = `git stash pop ${stashRef ?? ""}`.trim() + ` failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. ${restoreHint}`;
         logWarning("preflight", msg);
         notify(msg, "warning");
     }

package/dist/resources/extensions/gsd/commands/context.js

@@ -57,7 +57,7 @@ export function currentDirectoryRoot() {
             cwd = process.cwd();
         }
         catch {
-            cwd = process.env.HOME ?? "/";
+            cwd = homedir();
         }
     }
     const result = validateDirectory(cwd);

package/dist/resources/extensions/gsd/commands/dispatcher.js

@@ -33,5 +33,10 @@ export async function handleGSDCommand(args, ctx, pi) {
     }
     if (handled)
         return;
+    if (trimmed.includes(" ")) {
+        const { handleDo } = await import("../commands-do.js");
+        await handleDo(trimmed, ctx, pi);
+        return;
+    }
     ctx.ui.notify(`Unknown: /gsd ${trimmed}. Run /gsd help for available commands.`, "warning");
 }

package/dist/resources/extensions/gsd/commands-extract-learnings.js

@@ -114,14 +114,19 @@ Using the \`write\` tool, persist the full structured report to
 LEARNINGS.md is the full, cited audit trail. Write it first — subsequent steps
 feed from its content.
 
-### Step 3 — Optionally pre-query the memory store for semantic duplicates
+### Step 3 — Run one bounded duplicate check
 
-Before persisting any extracted item in Steps 4–6, you may call
-\`memory_query\` with 2–3 keywords from the item to check whether the
-memory store already holds a semantically equivalent entry at high
-confidence. Skip those items in their respective steps. The memory store
-is the single source of truth for cross-session durable knowledge — no
-other persistence call is part of this flow.
+Before persisting extracted items in Steps 4–6, do at most one duplicate-check
+pass for the durable Decisions, Lessons, and Patterns from this milestone. Use
+the already-written LEARNINGS.md content and call \`memory_query\` once with a
+compact keyword summary for the whole batch. If that result clearly shows a
+semantically equivalent high-confidence memory for an item, mark only that item
+as already captured and skip it in its respective persistence step.
+
+Do not re-read milestone artefacts or repeat memory queries category-by-category
+after this point. The memory store is the single source of truth for
+cross-session durable knowledge — no other persistence call is part of this
+flow.
 
 ### Step 4 — Persist Patterns via \`capture_thought\`
 
@@ -160,11 +165,11 @@ later projection back to a human-visible decisions register stays lossless
 
 ### Step 7 — Deduplication rule (applies to Steps 4, 5, 6)
 
-Before each \`capture_thought\` call, optionally call \`memory_query\` with 2–3
-keywords from the entry. If a semantically equivalent memory is returned at
-high confidence, skip the capture entirely. Prefer skipping a near-duplicate
-over creating a second slightly-different row — redundancy degrades the
-signal.
+Use only the duplicate-check result from Step 3. If that bounded check returned
+a semantically equivalent memory at high confidence for an extracted item, skip
+the capture entirely. Otherwise, persist the item once via \`capture_thought\`.
+Prefer skipping a near-duplicate over creating a second slightly-different row
+— redundancy degrades the signal.
 
 ### Step 8 — Surprises stay only in LEARNINGS.md
 

package/dist/resources/extensions/gsd/commands-ship.js

@@ -1,9 +1,5 @@
-/**
- * GSD Command — /gsd ship
- *
- * Creates a PR from milestone artifacts: generates title + body from
- * roadmap, slice summaries, and metrics, then opens via `gh pr create`.
- */
+// Project/App: GSD-2
+// File Purpose: Ship command for creating pull requests from GSD milestone evidence.
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { readFile } from "node:fs/promises";
@@ -14,6 +10,7 @@ import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bri
 import { formatDuration } from "../shared/format-utils.js";
 import { parseEvalReviewFrontmatter } from "./eval-review-schema.js";
 import { currentDirectoryRoot } from "./commands/context.js";
+import { buildPrEvidence } from "./pr-evidence.js";
 function git(basePath, args) {
     return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
 }
@@ -114,66 +111,46 @@ export async function checkSliceEvalReview(basePath, milestoneId, sliceId) {
     };
 }
 function generatePRContent(basePath, milestoneId, milestoneTitle) {
-    const title = `feat: ${milestoneTitle || milestoneId}`;
-    const sections = [];
-    // TL;DR
-    sections.push("## TL;DR\n");
-    sections.push(`**What:** Ship milestone ${milestoneId} — ${milestoneTitle || "(untitled)"}`);
-    sections.push(`**Why:** Milestone work complete, ready for review.`);
-    sections.push(`**How:** See slice summaries below.\n`);
-    // What — slice summaries
     const summaries = collectSliceSummaries(basePath, milestoneId);
-    if (summaries.length > 0) {
-        sections.push("## What\n");
-        sections.push(summaries.join("\n\n"));
-        sections.push("");
-    }
-    // Roadmap status
+    const roadmapItems = [];
     const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
     if (roadmapPath && existsSync(roadmapPath)) {
         try {
             const roadmap = readFileSync(roadmapPath, "utf-8");
             const checkboxLines = roadmap.split("\n").filter((l) => /^\s*-\s*\[[ x]\]/.test(l));
-            if (checkboxLines.length > 0) {
-                sections.push("## Roadmap\n");
-                sections.push(checkboxLines.join("\n"));
-                sections.push("");
-            }
+            roadmapItems.push(...checkboxLines);
         }
         catch {
             // non-fatal
         }
     }
-    // Metrics
+    const metrics = [];
     const ledger = getLedger();
     const units = ledger?.units ?? loadLedgerFromDisk(basePath)?.units ?? [];
     if (units.length > 0) {
         const totals = getProjectTotals(units);
         const byModel = aggregateByModel(units);
-        sections.push("## Metrics\n");
-        sections.push(`- **Units executed:** ${units.length}`);
-        sections.push(`- **Total cost:** ${formatCost(totals.cost)}`);
-        sections.push(`- **Tokens:** ${formatTokenCount(totals.tokens.input)} input / ${formatTokenCount(totals.tokens.output)} output`);
+        metrics.push(`**Units executed:** ${units.length}`);
+        metrics.push(`**Total cost:** ${formatCost(totals.cost)}`);
+        metrics.push(`**Tokens:** ${formatTokenCount(totals.tokens.input)} input / ${formatTokenCount(totals.tokens.output)} output`);
         if (totals.duration > 0) {
-            sections.push(`- **Duration:** ${formatDuration(totals.duration)}`);
+            metrics.push(`**Duration:** ${formatDuration(totals.duration)}`);
         }
         if (byModel.length > 0) {
-            sections.push(`- **Models:** ${byModel.map((m) => `${m.model} (${m.units} units)`).join(", ")}`);
+            metrics.push(`**Models:** ${byModel.map((m) => `${m.model} (${m.units} units)`).join(", ")}`);
         }
-        sections.push("");
-    }
-    // Change type checklist
-    sections.push("## Change type\n");
-    sections.push("- [x] `feat` — New feature or capability");
-    sections.push("- [ ] `fix` — Bug fix");
-    sections.push("- [ ] `refactor` — Code restructuring");
-    sections.push("- [ ] `test` — Adding or updating tests");
-    sections.push("- [ ] `docs` — Documentation only");
-    sections.push("- [ ] `chore` — Build, CI, or tooling changes\n");
-    // AI disclosure
-    sections.push("---\n");
-    sections.push("*This PR was prepared with AI assistance (GSD auto-mode).*");
-    return { title, body: sections.join("\n") };
+    }
+    return buildPrEvidence({
+        milestoneId,
+        milestoneTitle,
+        changeType: "feat",
+        summaries,
+        roadmapItems,
+        metrics,
+        testsRun: ["Run `npm run verify:pr` before marking this PR ready."],
+        rollbackNotes: ["Revert the merge commit or close the PR before merge if review finds a regression."],
+        how: "Generated from GSD milestone slice summaries, roadmap status, and local metrics.",
+    });
 }
 export async function handleShip(args, ctx, _pi) {
     const basePath = currentDirectoryRoot();

package/dist/resources/extensions/gsd/commands-workflow-templates.js

@@ -1,12 +1,8 @@
-/**
- * GSD Workflow Template Commands — /gsd start, /gsd templates
- *
- * Handles the `/gsd start [template] [description]` and `/gsd templates` commands.
- * Resolves templates by name or auto-detection, then dispatches the workflow prompt.
- */
+// Project/App: GSD-2
+// File Purpose: Workflow template commands for starting, listing, and dispatching workflows.
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { resolveByName, autoDetect, listTemplates, getTemplateInfo, loadWorkflowTemplate, loadRegistry, } from "./workflow-templates.js";
+import { resolveByName, autoDetect, listTemplates, getTemplateInfo, loadWorkflowTemplate, loadRegistry, isLegacyWorkflowMode, } from "./workflow-templates.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
 import { createGitService, runGit } from "./git-service.js";
@@ -14,6 +10,8 @@ import { isAutoActive, isAutoPaused } from "./auto.js";
 import { getErrorMessage } from "./error-utils.js";
 import { resolvePlugin } from "./workflow-plugins.js";
 import { currentDirectoryRoot } from "./commands/context.js";
+import { formatRecommendedProcessPaths } from "./process-task-path.js";
+import { incrementLegacyTelemetry } from "./legacy-telemetry.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 /**
  * Generate a URL-friendly slug from text.
@@ -244,6 +242,9 @@ export async function handleStart(args, ctx, pi) {
                 "  /gsd start bugfix fix login button not responding\n" +
                 "  /gsd start spike evaluate auth libraries\n" +
                 "  /gsd start hotfix critical: API returns 500\n\n" +
+                "Recommended task paths:\n" +
+                formatRecommendedProcessPaths() +
+                "\n\n" +
                 "Flags:\n" +
                 "  --dry-run       Preview what would happen without executing\n" +
                 "  --issue <ref>   Link to a GitHub issue\n\n" +
@@ -364,6 +365,9 @@ export async function handleStart(args, ctx, pi) {
         infoLines.push(`Artifacts: ${artifactDir}`);
     infoLines.push(`Branch: ${actualBranch}`);
     ctx.ui.notify(infoLines.join("\n"), "info");
+    if (isLegacyWorkflowMode(template.mode)) {
+        incrementLegacyTelemetry("legacy.workflowEngineUsed");
+    }
     const prompt = loadPrompt("workflow-start", {
         templateId,
         templateName: template.name,
@@ -491,6 +495,7 @@ export function dispatchMarkdownPhasePlugin(plugin, description, ctx, pi) {
         infoLines.push(`Artifacts: ${artifactDir}`);
     infoLines.push(`Branch: ${actualBranch}`);
     ctx.ui.notify(infoLines.join("\n"), "info");
+    incrementLegacyTelemetry("legacy.workflowEngineUsed");
     const prompt = loadPrompt("workflow-start", {
         templateId,
         templateName: plugin.meta.displayName,

package/dist/resources/extensions/gsd/component-loader.js

@@ -1,18 +1,10 @@
-/**
- * Component Loader
- *
- * Multi-format loader that handles:
- * 1. New format: component.yaml + SKILL.md/AGENT.md
- * 2. Legacy skill format: SKILL.md with YAML frontmatter
- * 3. Legacy agent format: .md with YAML frontmatter (name, description, tools, model)
- *
- * Auto-detects format by checking for component.yaml first, then falling back
- * to legacy formats based on file naming conventions.
- */
+// Project/App: GSD-2
+// File Purpose: Loads modern component.yaml definitions and legacy skill/agent formats.
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { parseFrontmatter } from '@gsd/pi-coding-agent';
+import { incrementLegacyTelemetry } from './legacy-telemetry.js';
 import { validateComponentName, validateComponentDescription, computeComponentId, } from './component-types.js';
 const SUPPORTED_COMPONENT_KINDS = ['skill', 'agent'];
 const SUPPORTED_API_VERSIONS = ['gsd/v1'];
@@ -183,6 +175,7 @@ function loadFromLegacySkill(filePath, dir, source) {
         format: 'skill-md',
         enabled: true,
     };
+    incrementLegacyTelemetry('legacy.componentFormatUsed');
     return { component, diagnostics };
 }
 function loadFromLegacyAgent(filePath, source) {
@@ -235,6 +228,7 @@ function loadFromLegacyAgent(filePath, source) {
         format: 'agent-md',
         enabled: true,
     };
+    incrementLegacyTelemetry('legacy.componentFormatUsed');
     return { component, diagnostics };
 }
 // ============================================================================

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

@@ -29,6 +29,7 @@ import { _getAdapter, isDbAvailable } from "./gsd-db.js";
 import { gsdRoot, normalizeRealPath } from "./paths.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { effectiveLockFile } from "./session-lock.js";
+import { isInFlightRuntimePhase, listUnitRuntimeRecords } from "./unit-runtime.js";
 const SESSION_FILE_KV_KEY = "session_file";
 function lockPath(basePath) {
     return join(gsdRoot(basePath), effectiveLockFile());
@@ -72,9 +73,37 @@ function getLatestDispatchForWorker(workerId) {
      LIMIT 1`).get({ ":worker_id": workerId });
     return row ?? null;
 }
-function workerToLockData(worker) {
+function latestInFlightRuntimeRecord(basePath) {
+    const records = listUnitRuntimeRecords(basePath).filter((record) => isInFlightRuntimePhase(record.phase));
+    if (records.length === 0)
+        return null;
+    return records.sort((a, b) => {
+        const bTime = b.updatedAt || b.startedAt || 0;
+        const aTime = a.updatedAt || a.startedAt || 0;
+        return bTime - aTime;
+    })[0] ?? null;
+}
+function runtimeRecordToLockData(worker, record, sessionFile) {
+    const startedAt = Number.isFinite(record.startedAt)
+        ? new Date(record.startedAt).toISOString()
+        : worker.started_at;
+    return {
+        pid: worker.pid,
+        startedAt: worker.started_at,
+        unitType: record.unitType,
+        unitId: record.unitId,
+        unitStartedAt: startedAt,
+        sessionFile,
+    };
+}
+function workerToLockData(basePath, worker) {
     const dispatch = getLatestDispatchForWorker(worker.worker_id);
     const sessionFile = getRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY) ?? undefined;
+    if (!dispatch) {
+        const runtimeRecord = latestInFlightRuntimeRecord(basePath);
+        if (runtimeRecord)
+            return runtimeRecordToLockData(worker, runtimeRecord, sessionFile);
+    }
     return {
         pid: worker.pid,
         startedAt: worker.started_at,
@@ -172,7 +201,7 @@ export function readCrashLock(basePath) {
             const projectRoot = normalizeRealPath(basePath);
             const stale = findStaleWorkerForProject(projectRoot);
             if (stale)
-                return workerToLockData(stale);
+                return workerToLockData(basePath, stale);
         }
         catch {
             // Fall through to the legacy lock-file compatibility path.
@@ -232,18 +261,32 @@ export function formatCrashInfo(lock) {
 export function emitCrashRecoveredUnitEnd(basePath, lock) {
     if (!lock.unitType || !lock.unitId || lock.unitType === "starting")
         return;
+    emitOpenUnitEndForUnit(basePath, lock.unitType, lock.unitId, "crash-recovered");
+}
+export function emitOpenUnitEndForUnit(basePath, unitType, unitId, status, errorContext) {
     try {
         const all = queryJournal(basePath);
-        const starts = all.filter((e) => e.eventType === "unit-start" && e.data?.unitId === lock.unitId);
+        const starts = all.filter((e) => e.eventType === "unit-start" &&
+            e.data?.unitType === unitType &&
+            e.data?.unitId === unitId);
         if (starts.length === 0)
-            return;
-        const lastStart = starts[starts.length - 1];
+            return false;
+        const lastStart = [...starts].reverse().find((start) => {
+            return !all.some((e) => e.eventType === "unit-end" &&
+                e.data?.unitType === unitType &&
+                e.data?.unitId === unitId &&
+                e.causedBy?.flowId === start.flowId &&
+                e.causedBy?.seq === start.seq);
+        });
+        if (!lastStart)
+            return false;
         const alreadyClosed = all.some((e) => e.eventType === "unit-end" &&
-            e.data?.unitId === lock.unitId &&
+            e.data?.unitType === unitType &&
+            e.data?.unitId === unitId &&
             e.causedBy?.flowId === lastStart.flowId &&
             e.causedBy?.seq === lastStart.seq);
         if (alreadyClosed)
-            return;
+            return false;
         const maxSeq = all
             .filter((e) => e.flowId === lastStart.flowId)
             .reduce((max, e) => Math.max(max, e.seq), lastStart.seq);
@@ -253,16 +296,19 @@ export function emitCrashRecoveredUnitEnd(basePath, lock) {
             seq: maxSeq + 1,
             eventType: "unit-end",
             data: {
-                unitType: lock.unitType,
-                unitId: lock.unitId,
-                status: "crash-recovered",
+                unitType,
+                unitId,
+                status,
                 artifactVerified: false,
+                ...(errorContext ? { errorContext } : {}),
             },
             causedBy: { flowId: lastStart.flowId, seq: lastStart.seq },
         });
+        return true;
     }
     catch {
         // Never throw from crash recovery path.
+        return false;
     }
 }
 /**