gsd-pi 2.78.0 → 2.78.1-dev.8a893322c

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

@@ -0,0 +1 @@
+868d22f3f04d038e

package/dist/resources/extensions/claude-code-cli/readiness.js

@@ -5,10 +5,30 @@
  * Results are cached for 30 seconds to avoid shelling out on every
  * model-availability check.
  *
- * Auth verification follows the T3 Code pattern: run `claude auth status`
- * and check the exit code + output for an authenticated session.
+ * Auth verification runs `claude auth status --json` and inspects the
+ * `loggedIn` field, falling back to plain `claude auth status` and a text
+ * heuristic when the JSON shape is unavailable (older Claude CLI builds).
+ *
+ * Set GSD_CLAUDE_DEBUG=1 to print the probe's binary selection and auth
+ * outputs to stderr — useful when diagnosing platform-specific detection
+ * failures (Issue #4997).
  */
 import { execFileSync } from "node:child_process";
+/**
+ * Spawn the Claude CLI without triggering Node's DEP0190.
+ *
+ * Passing `args` together with `shell: true` is deprecated in Node 22+
+ * because the args are concatenated into the command string without
+ * escaping. On Windows we still need a shell to resolve `.cmd` shims, so
+ * we invoke `cmd /c <command> <args...>` explicitly. On POSIX we don't
+ * need a shell at all.
+ */
+function spawnClaude(command, args, opts) {
+    if (process.platform === "win32") {
+        return execFileSync("cmd", ["/c", command, ...args], opts);
+    }
+    return execFileSync(command, args, opts);
+}
 /**
  * Candidate executable names for the Claude Code CLI.
  *
@@ -23,33 +43,114 @@ const CLAUDE_COMMAND = process.platform === "win32" ? "claude.cmd" : "claude";
  * installed" results in readiness checks.
  */
 const CLAUDE_COMMAND_CANDIDATES = process.platform === "win32" ? [CLAUDE_COMMAND, "claude.exe", "claude"] : [CLAUDE_COMMAND];
-function execClaude(args) {
-    let lastError;
+// Keep the version probe snappy — `claude --version` is a quick path.
+const VERSION_TIMEOUT_MS = 5_000;
+// Auth status can be much slower on Windows because the spawn goes through
+// cmd.exe → claude.cmd → node → Claude CLI. 15s leaves headroom on cold spawns
+// without making startup feel hung when the CLI is genuinely missing.
+const AUTH_TIMEOUT_MS = 15_000;
+function debugLog(...parts) {
+    if (process.env.GSD_CLAUDE_DEBUG) {
+        process.stderr.write(`[claude-readiness] ${parts.map((p) => (typeof p === "string" ? p : JSON.stringify(p))).join(" ")}\n`);
+    }
+}
+/**
+ * Find the first candidate that responds to `--version`. Returns the
+ * candidate name on success, null if none worked.
+ *
+ * On Windows with `cmd /c`, a missing candidate surfaces as a
+ * non-zero exit from cmd.exe rather than ENOENT — so we cannot rely on
+ * the error code to decide "try next". Treat any failure as "try next"
+ * for the version probe; the only thing that matters for binary
+ * detection is whether *some* candidate produces a `claude --version`
+ * line.
+ */
+function findWorkingCommand() {
     for (const command of CLAUDE_COMMAND_CANDIDATES) {
         try {
-            return execFileSync(command, args, {
-                timeout: 5_000,
+            spawnClaude(command, ["--version"], {
+                timeout: VERSION_TIMEOUT_MS,
                 stdio: "pipe",
-                shell: process.platform === "win32",
             });
+            debugLog("version probe ok via", command);
+            return command;
         }
         catch (error) {
-            lastError = error;
-            const code = error?.code;
-            // Windows Git Bash can surface `.cmd` spawn failures as EINVAL instead
-            // of ENOENT. Treat both as "try next candidate".
-            if (code === "ENOENT" || code === "EINVAL") {
-                continue;
+            debugLog("version probe failed for", command, "code=", error?.code);
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Decide auth state from `claude auth status` output.
+ *
+ * Newer Claude CLI builds emit JSON by default with a `loggedIn` boolean.
+ * Older builds emit free-form text. We prefer the structured signal and fall
+ * back to a text heuristic. Note: the text heuristic only covers English
+ * phrasing — the JSON path is the durable signal.
+ */
+function parseAuthStatus(output) {
+    const trimmed = output.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.startsWith("{")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed.loggedIn === "boolean") {
+                return parsed.loggedIn;
             }
-            throw error;
         }
+        catch {
+            // Fall through to text heuristic.
+        }
+    }
+    const lower = trimmed.toLowerCase();
+    if (/not logged in|no credentials|unauthenticated|not authenticated/.test(lower)) {
+        return false;
+    }
+    if (/logged in|authenticated|signed in|email|subscription/.test(lower)) {
+        return true;
+    }
+    return null;
+}
+function probeAuth(command) {
+    // Try --json first (newer CLIs).
+    try {
+        const out = spawnClaude(command, ["auth", "status", "--json"], {
+            timeout: AUTH_TIMEOUT_MS,
+            stdio: "pipe",
+        }).toString();
+        debugLog("auth status --json output:", out.slice(0, 200));
+        const parsed = parseAuthStatus(out);
+        if (parsed !== null)
+            return parsed;
+    }
+    catch (error) {
+        debugLog("auth status --json threw:", error.message?.slice(0, 200));
+    }
+    // Fallback: plain `auth status` (older CLIs that don't accept --json).
+    try {
+        const out = spawnClaude(command, ["auth", "status"], {
+            timeout: AUTH_TIMEOUT_MS,
+            stdio: "pipe",
+        }).toString();
+        debugLog("auth status output:", out.slice(0, 200));
+        return parseAuthStatus(out);
+    }
+    catch (error) {
+        debugLog("auth status threw:", error.message?.slice(0, 200));
+        return null;
     }
-    throw lastError ?? new Error(`Claude CLI executable not found (tried: ${CLAUDE_COMMAND_CANDIDATES.join(", ")})`);
 }
 let cachedBinaryPresent = null;
 let cachedAuthed = null;
 let lastCheckMs = 0;
 const CHECK_INTERVAL_MS = 30_000;
+/**
+ * Refresh the cached binary/auth state when the cache window has expired.
+ * Preserves a known auth state across soft-fail auth probes.
+ */
 function refreshCache() {
     const now = Date.now();
     if (cachedBinaryPresent !== null && now - lastCheckMs < CHECK_INTERVAL_MS) {
@@ -57,28 +158,23 @@ function refreshCache() {
     }
     // Set timestamp first to prevent re-entrant checks during the same window
     lastCheckMs = now;
-    // Check binary presence
-    try {
-        execClaude(["--version"]);
-        cachedBinaryPresent = true;
-    }
-    catch {
+    const command = findWorkingCommand();
+    if (!command) {
         cachedBinaryPresent = false;
         cachedAuthed = false;
         return;
     }
-    // Check auth status — exit code 0 with non-error output means authenticated
-    try {
-        const output = execClaude(["auth", "status"])
-            .toString()
-            .toLowerCase();
-        // The CLI outputs "not logged in", "no credentials", or similar when unauthenticated
-        cachedAuthed = !(/not logged in|no credentials|unauthenticated|not authenticated/i.test(output));
-    }
-    catch {
-        // Non-zero exit code means not authenticated
-        cachedAuthed = false;
+    cachedBinaryPresent = true;
+    const authed = probeAuth(command);
+    if (authed === null) {
+        // Couldn't determine auth state from CLI output. Don't clobber a
+        // previously known-good cache; otherwise default to false so we don't
+        // silently route requests to an unauthenticated CLI.
+        if (cachedAuthed === null)
+            cachedAuthed = false;
+        return;
     }
+    cachedAuthed = authed;
 }
 /**
  * Whether the `claude` binary is installed (regardless of auth state).

package/dist/resources/extensions/google-search/index.js

@@ -1,7 +1,3 @@
-export default function (pi) {
-    pi.on("session_start", async (_event, ctx) => {
-        ctx.ui.notify("google_search is being extracted to @gsd-extensions/google-search " +
-            "(not yet published to npm). This stub will be replaced once the " +
-            "package is available. No action needed for now.", "warning");
-    });
+export default function (_pi) {
+    // Deprecation notice intentionally suppressed until @gsd-extensions/google-search ships.
 }

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

@@ -163,6 +163,17 @@ function resolveDispatchNodeKind(unitType, sidecarItem) {
     }
     return "unit";
 }
+async function enforceMinRequestInterval(s, prefs) {
+    const minInterval = prefs?.min_request_interval_ms ?? 0;
+    if (minInterval > 0 && s.lastRequestTimestamp > 0) {
+        const elapsed = Date.now() - s.lastRequestTimestamp;
+        if (elapsed < minInterval) {
+            const waitMs = minInterval - elapsed;
+            debugLog("autoLoop", { phase: "rate-limit-wait", waitMs });
+            await new Promise(r => setTimeout(r, waitMs));
+        }
+    }
+}
 async function runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState, sidecarItem) {
     if (dispatchContract === "legacy-direct") {
         return runUnitPhase(ic, iterData, loopState, sidecarItem);
@@ -392,7 +403,13 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                     break;
                 }
                 // ── Unit execution (shared with dev path) ──
+                await enforceMinRequestInterval(s, prefs);
                 const unitPhaseResult = await runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState);
+                if (unitPhaseResult.action === "next") {
+                    const requestTimestamp = unitPhaseResult.data.requestDispatchedAt ?? unitPhaseResult.data.unitStartedAt;
+                    if (typeof requestTimestamp === "number")
+                        s.lastRequestTimestamp = requestTimestamp;
+                }
                 deps.uokObserver?.onPhaseResult("unit", unitPhaseResult.action, {
                     unitType: iterData.unitType,
                     unitId: iterData.unitId,
@@ -555,7 +572,13 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                     sidecarKind: sidecarItem.kind,
                 });
             }
+            await enforceMinRequestInterval(s, prefs);
             const unitPhaseResult = await runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState, sidecarItem);
+            if (unitPhaseResult.action === "next") {
+                const requestTimestamp = unitPhaseResult.data.requestDispatchedAt ?? unitPhaseResult.data.unitStartedAt;
+                if (typeof requestTimestamp === "number")
+                    s.lastRequestTimestamp = requestTimestamp;
+            }
             deps.uokObserver?.onPhaseResult("unit", unitPhaseResult.action, {
                 unitType: iterData.unitType,
                 unitId: iterData.unitId,

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

@@ -11,6 +11,7 @@ import { MAX_RECOVERY_CHARS, BUDGET_THRESHOLDS, MAX_FINALIZE_TIMEOUTS, } from ".
 import { detectStuck } from "./detect-stuck.js";
 import { runUnit } from "./run-unit.js";
 import { debugLog } from "../debug-logger.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { PROJECT_FILES, hasProjectFileInAncestor } from "../detection.js";
 import { MergeConflictError } from "../git-service.js";
 import { setCurrentPhase, clearCurrentPhase } from "../../shared/gsd-phase-state.js";
@@ -48,11 +49,7 @@ export function resetSessionTimeoutState() {
  * Exported for testing as _resolveReportBasePath.
  */
 export function _resolveReportBasePath(s) {
-    // Strip /.gsd/worktrees/ suffix when basePath is itself a worktree path and
-    // originalBasePath is falsy — prevents reports landing in the worktree (#3729).
-    const resolved = s.originalBasePath || s.basePath;
-    const markerIdx = resolved.indexOf("/.gsd/worktrees/");
-    return markerIdx !== -1 ? resolved.slice(0, markerIdx) : resolved;
+    return resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
 }
 /**
  * Resolve the authoritative project base for dispatch guards.
@@ -60,12 +57,7 @@ export function _resolveReportBasePath(s) {
  * unit is running inside an auto worktree.
  */
 export function _resolveDispatchGuardBasePath(s) {
-    // Strip /.gsd/worktrees/ suffix when basePath is itself a worktree path and
-    // originalBasePath is falsy — prevents guard checks running against the
-    // worktree instead of the project root (#3729).
-    const resolved = s.originalBasePath || s.basePath;
-    const markerIdx = resolved.indexOf("/.gsd/worktrees/");
-    return markerIdx !== -1 ? resolved.slice(0, markerIdx) : resolved;
+    return resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
 }
 const PLAN_V2_GATE_PHASES = new Set([
     "executing",
@@ -1365,7 +1357,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
                 ctx.ui.notify(`${unitType} ${unitId} completed with 0 tool calls — context exhaustion, will retry`, "warning");
                 // Fall through to next iteration where dispatch will re-derive
                 // and re-dispatch this unit.
-                return { action: "next", data: { unitStartedAt: s.currentUnit?.startedAt } };
+                return { action: "next", data: { unitStartedAt: s.currentUnit?.startedAt, requestDispatchedAt: unitResult.requestDispatchedAt } };
             }
         }
     }
@@ -1418,7 +1410,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
         }
         s.checkpointSha = null;
     }
-    return { action: "next", data: { unitStartedAt: s.currentUnit?.startedAt } };
+    return { action: "next", data: { unitStartedAt: s.currentUnit?.startedAt, requestDispatchedAt: unitResult.requestDispatchedAt } };
 }
 // ─── runFinalize ──────────────────────────────────────────────────────────────
 /**

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

@@ -138,6 +138,7 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
     const capturedTurnGen = getCurrentTurnGeneration();
     // ── Send the prompt ──
     debugLog("runUnit", { phase: "send-message", unitType, unitId });
+    const requestDispatchedAt = Date.now();
     pi.sendMessage({ customType: "gsd-auto", content: prompt, display: s.verbose }, { triggerTurn: true });
     // ── Await agent_end with absolute timeout (H4 fix) ──
     // If supervision fails to resolve unitPromise within 30s, treat as cancelled.
@@ -160,6 +161,7 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
         unitId,
         status: result.status,
     });
+    const finalResult = { ...result, requestDispatchedAt };
     // Discard trailing follow-up messages (e.g. async_job_result notifications)
     // from the completed unit. Without this, queued follow-ups trigger wasteful
     // LLM turns before the next session can start (#1642).
@@ -174,5 +176,5 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
     catch (e) {
         logWarning("engine", "clearQueue failed after unit completion", { error: String(e) });
     }
-    return result;
+    return finalResult;
 }

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

@@ -15,6 +15,7 @@
  * auto-session-encapsulation.test.ts enforce that auto.ts has no module-level
  * `let` or `var` declarations.
  */
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
 export const STUB_RECOVERY_THRESHOLD = 2;
 export const NEW_SESSION_TIMEOUT_MS = 120_000;
@@ -118,6 +119,8 @@ export class AutoSession {
     lastPromptCharCount;
     lastBaselineCharCount;
     pendingQuickTasks = [];
+    /** Timestamp of the last LLM request dispatch (ms since epoch). Used for proactive rate limiting. */
+    lastRequestTimestamp = 0;
     // ── Safety harness ───────────────────────────────────────────────────────
     /** SHA of the pre-unit git checkpoint ref. Cleared on success or rollback. */
     checkpointSha = null;
@@ -153,12 +156,7 @@ export class AutoSession {
         this.unitLifetimeDispatches.clear();
     }
     get lockBasePath() {
-        // Prefer originalBasePath (project root); fall back to basePath.
-        // Strip /.gsd/worktrees/ suffix if basePath is itself a worktree path
-        // to avoid reading/writing the lock inside the worktree (#3729).
-        const resolved = this.originalBasePath || this.basePath;
-        const markerIdx = resolved.indexOf("/.gsd/worktrees/");
-        return markerIdx !== -1 ? resolved.slice(0, markerIdx) : resolved;
+        return resolveWorktreeProjectRoot(this.basePath, this.originalBasePath);
     }
     reset() {
         this.clearTimers();
@@ -215,6 +213,7 @@ export class AutoSession {
         this.lastPromptCharCount = undefined;
         this.lastBaselineCharCount = undefined;
         this.pendingQuickTasks = [];
+        this.lastRequestTimestamp = 0;
         this.sidecarQueue = [];
         this.rewriteAttemptCount = 0;
         this.consecutiveCompleteBootstraps = 0;

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

@@ -10,6 +10,7 @@ import { getActiveHook } from "./post-unit-hooks.js";
 import { getLedger, getProjectTotals } from "./metrics.js";
 import { getErrorMessage } from "./error-utils.js";
 import { nativeIsRepo } from "./native-git-bridge.js";
+import { getHomeDir } from "./home-dir.js";
 import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { execFileSync } from "node:child_process";
@@ -461,8 +462,8 @@ export function updateProgressWidget(ctx, unitType, unitId, state, accessors, ti
     let widgetPwd;
     {
         let fullPwd = process.cwd();
-        const widgetHome = process.env.HOME || process.env.USERPROFILE;
-        if (widgetHome && fullPwd.startsWith(widgetHome)) {
+        const widgetHome = getHomeDir();
+        if (widgetHome && (fullPwd === widgetHome || fullPwd.startsWith(widgetHome + "/") || fullPwd.startsWith(widgetHome + "\\"))) {
             fullPwd = `~${fullPwd.slice(widgetHome.length)}`;
         }
         const parts = fullPwd.split("/");

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

@@ -655,14 +655,25 @@ export const DISPATCH_RULES = [
                 return null;
             if (!state.activeSlice)
                 return null; // fall through
-            // Only activate when reactive_execution is explicitly enabled
+            // Reactive dispatch is on by default when there are enough ready tasks to
+            // benefit from parallelism. Users opt out explicitly via
+            // `reactive_execution.enabled: false`. The downstream safety checks
+            // (graph ambiguity, ready-task count, conflict-free selection) still gate
+            // every actual dispatch, so the worst-case "default-on" outcome is the
+            // same fall-through to sequential execution as before.
             const reactiveConfig = prefs?.reactive_execution;
-            if (!reactiveConfig?.enabled)
+            if (reactiveConfig?.enabled === false)
                 return null;
             const sid = state.activeSlice.id;
             const sTitle = state.activeSlice.title;
-            const maxParallel = reactiveConfig.max_parallel ?? 2;
-            const subagentModel = reactiveConfig.subagent_model ?? resolveModelWithFallbacksForUnit("subagent")?.primary;
+            const maxParallel = reactiveConfig?.max_parallel ?? 2;
+            const subagentModel = reactiveConfig?.subagent_model ?? resolveModelWithFallbacksForUnit("subagent")?.primary;
+            // Default-on safety threshold: only activate reactive dispatch when at
+            // least N tasks are ready. Users who explicitly enabled reactive_execution
+            // keep the legacy threshold of 2 (matches the prior "any parallelism is
+            // better than none" intent). Default-on installs require >=3 to avoid
+            // surprising users with parallelism on small slices.
+            const minReadyTasksForReactive = reactiveConfig?.enabled === true ? 2 : 3;
             // Dry-run mode: max_parallel=1 means graph is derived and logged but
             // execution remains sequential
             if (maxParallel <= 1)
@@ -678,8 +689,9 @@ export const DISPATCH_RULES = [
                     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)
+                // Only activate reactive dispatch when enough tasks are ready.
+                // Threshold is 2 when explicitly opted in, 3 when default-on.
+                if (readyIds.length < minReadyTasksForReactive)
                     return null;
                 const uokFlags = resolveUokFlags(prefs);
                 const selected = uokFlags.executionGraph

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

@@ -23,7 +23,7 @@ import { composeInlinedContext } from "./unit-context-composer.js";
 import { logWarning } from "./workflow-logger.js";
 import { inlineGraphSubgraph } from "./graph-context.js";
 import { buildExtractionStepsBlock } from "./commands-extract-learnings.js";
-import { warnIfManifestHasMissingSkills } from "./skill-manifest.js";
+import { resolveSkillManifest, warnIfManifestHasMissingSkills } from "./skill-manifest.js";
 // ─── Preamble Cap ─────────────────────────────────────────────────────────────
 /**
  * Historical static ceiling for the preamble cap. Kept as an upper bound even
@@ -675,6 +675,26 @@ function formatSkillActivationBlock(skillNames) {
     const calls = safe.map(name => `Call Skill({ skill: '${name}' })`).join('. ');
     return `<skill_activation>${calls}.</skill_activation>`;
 }
+/**
+ * Manifest-driven recommendations block — informational only, does NOT
+ * auto-invoke. Lists per-unit-type skills that are installed but not already
+ * activated by explicit user intent (always_use_skills / prefer_skills /
+ * skill_rules / task-plan skills_used). Surfaces relevant skills to the
+ * model so they can be invoked when the model judges them useful.
+ *
+ * This is the additive complement to the existing activation directive:
+ * activation force-invokes (explicit intent), recommendations remind
+ * (manifest defaults). User intent is preserved as the stronger signal
+ * (RFC #4779 design principle); this block only adds visibility.
+ */
+function formatSkillRecommendationsBlock(unitType, skillNames) {
+    if (!unitType)
+        return "";
+    const safe = skillNames.filter(name => SAFE_SKILL_NAME.test(name));
+    if (safe.length === 0)
+        return "";
+    return `<skill_recommendations unit="${unitType}">For this unit type, also consider invoking: ${safe.join(", ")}. Use Skill({ skill: 'name' }) when relevant — these are recommendations, not requirements.</skill_recommendations>`;
+}
 export function buildSkillActivationBlock(params) {
     const prefs = params.preferences ?? loadEffectiveGSDPreferences(params.base)?.preferences;
     const contextTokens = tokenizeSkillContext(params.milestoneId, params.milestoneTitle, params.sliceId, params.sliceTitle, params.taskId, params.taskTitle);
@@ -717,10 +737,51 @@ export function buildSkillActivationBlock(params) {
             logWarning("prompt", `parseTaskPlanFile failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    // Heuristic auto-match (gated on skill_discovery: "auto").
+    // For each installed skill, check if its name or description appears in the
+    // unit's context tokens (milestone/slice/task titles). Only consider skills
+    // already on the unit-type manifest allowlist — this keeps the heuristic
+    // narrow and avoids wildly off-topic activations.
+    // Users who set `skill_discovery: "off"` or "suggest" do not get
+    // auto-matched skills (the recommendations block still surfaces manifest
+    // skills passively); only "auto" actually adds them to the activation
+    // directive set. Default `skill_discovery` is "suggest", so this is opt-in.
+    if ((prefs?.skill_discovery ?? "suggest") === "auto") {
+        const manifestAllow = resolveSkillManifest(params.unitType);
+        const allowSet = manifestAllow ? new Set(manifestAllow) : null;
+        for (const skill of visibleSkills) {
+            const normalized = normalizeSkillReference(skill.name);
+            if (matched.has(normalized) || avoided.has(normalized))
+                continue;
+            // Respect the manifest allowlist when present; wildcard (null) lets all
+            // installed skills compete for keyword match.
+            if (allowSet && !allowSet.has(normalized))
+                continue;
+            if (skillMatchesContext(skill, contextTokens)) {
+                matched.add(normalized);
+            }
+        }
+    }
     const ordered = [...matched]
         .filter(name => installedNames.has(name) && !avoided.has(name))
         .sort();
-    return formatSkillActivationBlock(ordered);
+    const activationBlock = formatSkillActivationBlock(ordered);
+    // Manifest-driven recommendations (additive, does not override explicit intent).
+    // Only surface skills the manifest declares for this unit type that are
+    // installed and not already in matched/avoided.
+    const matchedSet = new Set(ordered);
+    const manifestList = resolveSkillManifest(params.unitType);
+    const recommendations = (manifestList ?? [])
+        .filter(name => installedNames.has(name) && !avoided.has(name) && !matchedSet.has(name))
+        .sort();
+    const recommendationsBlock = formatSkillRecommendationsBlock(params.unitType, recommendations);
+    if (!activationBlock && !recommendationsBlock)
+        return "";
+    if (!activationBlock)
+        return recommendationsBlock;
+    if (!recommendationsBlock)
+        return activationBlock;
+    return `${activationBlock}\n${recommendationsBlock}`;
 }
 /**
  * Build the skill discovery template variables for research prompts.

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

@@ -7,6 +7,7 @@
  * globals or AutoContext dependency.
  */
 import { parseUnitId } from "./unit-id.js";
+import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { appendEvent } from "./workflow-events.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { clearParseCache } from "./files.js";
@@ -168,8 +169,35 @@ function getChangedFilesSinceBranch(basePath, targetBranch) {
     }
 }
 function getChangedFilesFromMilestoneTaggedCommits(basePath, milestoneId) {
+    // Primary: path-scoped log against .gsd/milestones/<id>. Fast and unbounded
+    // by depth when .gsd/ is tracked in git.
+    const scoped = scanGsdTaggedCommits(basePath, milestoneId, [
+        "log", "--format=%H%x1f%B%x1e", "HEAD", "--", `.gsd/milestones/${milestoneId}`,
+    ]);
+    if (!scoped.ok)
+        return scoped;
+    if (scoped.matched)
+        return scoped;
+    // Fallback (#5033): when .gsd/ is gitignored / external / untracked, the
+    // path-scoped scan matches no commits even though GSD-tagged commits
+    // referencing the milestone exist on the integration branch. Re-scan all
+    // of HEAD's history and rely on commitMatchesMilestone to bind by
+    // explicit milestone mention in the message body.
+    //
+    // Intentionally unbounded — symmetric with the primary scan, and avoids
+    // reintroducing the rolling-depth failure class removed in #4699 where
+    // milestone evidence aged out behind unrelated activity.
+    return scanGsdTaggedCommits(basePath, milestoneId, [
+        "log", "--format=%H%x1f%B%x1e", "HEAD",
+    ]);
+}
+function scanGsdTaggedCommits(basePath, milestoneId, gitArgs) {
     try {
-        const logOutput = execFileSync("git", ["log", "--format=%H%x1f%B%x1e", "HEAD", "--", `.gsd/milestones/${milestoneId}`], { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" });
+        const logOutput = execFileSync("git", [...gitArgs], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
         const records = logOutput
             .split("\x1e")
             .map((record) => record.trim())
@@ -213,13 +241,24 @@ function commitMatchesMilestone(message, milestoneId, files) {
     if (commitTrailerStartsWithMilestone(message, milestoneId))
         return true;
     // Meaningful execute-task commits currently store task scope as Sxx/Tyy
-    // rather than Mxx/Sxx/Tyy. Bind those commits back to the milestone only
-    // when the commit also touched this milestone's artifacts.
+    // rather than Mxx/Sxx/Tyy. Bind those commits back to the milestone when
+    // either the commit touched this milestone's artifacts, or — for projects
+    // where .gsd/ is gitignored/external (#5033) — the message explicitly
+    // names the milestone.
     if (/^GSD-Task:\s*S[^/\s]+\/T\S+/m.test(message)) {
-        return files.some((file) => isMilestoneArtifactPath(file, milestoneId));
+        if (files.some((file) => isMilestoneArtifactPath(file, milestoneId)))
+            return true;
+        if (commitMessageMentionsMilestone(message, milestoneId))
+            return true;
     }
     return false;
 }
+function commitMessageMentionsMilestone(message, milestoneId) {
+    if (!MILESTONE_ID_RE.test(milestoneId))
+        return false;
+    const escapedMilestone = milestoneId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`\\b${escapedMilestone}\\b`).test(message);
+}
 function commitTrailerStartsWithMilestone(message, milestoneId) {
     const escapedMilestone = milestoneId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const trailerPattern = new RegExp(`^GSD-(?:Task|Unit):\\s*${escapedMilestone}(?:$|[\\s/])`, "m");

package/dist/resources/extensions/gsd/auto-runtime-state.js

@@ -0,0 +1,31 @@
+// GSD auto-mode runtime state
+import { AutoSession } from "./auto/session.js";
+import { isDeterministicPolicyError, isQueuedUserMessageSkip, isToolInvocationError, markToolEnd as markTrackedToolEnd, markToolStart as markTrackedToolStart, } from "./auto-tool-tracking.js";
+export const autoSession = new AutoSession();
+export function getAutoRuntimeSnapshot() {
+    return {
+        active: autoSession.active,
+        paused: autoSession.paused,
+        currentUnit: autoSession.currentUnit ? { ...autoSession.currentUnit } : null,
+        basePath: autoSession.basePath,
+    };
+}
+export function isAutoActive() {
+    return autoSession.active;
+}
+export function isAutoPaused() {
+    return autoSession.paused;
+}
+export function markToolStart(toolCallId, toolName) {
+    markTrackedToolStart(toolCallId, autoSession.active, toolName);
+}
+export function markToolEnd(toolCallId) {
+    markTrackedToolEnd(toolCallId);
+}
+export function recordToolInvocationError(toolName, errorMsg) {
+    if (!autoSession.active)
+        return;
+    if (isToolInvocationError(errorMsg) || isQueuedUserMessageSkip(errorMsg) || isDeterministicPolicyError(errorMsg)) {
+        autoSession.lastToolInvocationError = `${toolName}: ${errorMsg}`;
+    }
+}

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

@@ -208,7 +208,7 @@ export function auditOrphanedMilestoneBranches(basePath, isolationMode) {
         else {
             // Branch is NOT merged — preserve for safety, warn the user
             warnings.push(`Branch ${branch} exists for completed milestone ${milestoneId} but is NOT merged into ${mainBranch}. ` +
-                `This may contain unmerged work. Merge manually or run \`/gsd health --fix\` to resolve.`);
+                `This may contain unmerged work. Merge manually or run \`/gsd doctor fix\` to resolve.`);
             // #4764 telemetry
             try {
                 emitWorktreeOrphaned(basePath, milestoneId, {

package/dist/resources/extensions/gsd/auto-tool-tracking.js

@@ -139,6 +139,6 @@ export const DETERMINISTIC_POLICY_ERROR_STRINGS = [
 export function isDeterministicPolicyError(errorMsg) {
     if (!errorMsg)
         return false;
-    return (DETERMINISTIC_POLICY_ERROR_RE.test(errorMsg) ||
-        DETERMINISTIC_POLICY_ERROR_STRINGS.some(s => errorMsg.includes(s)));
+    return DETERMINISTIC_POLICY_ERROR_RE.test(errorMsg)
+        || DETERMINISTIC_POLICY_ERROR_STRINGS.some(s => errorMsg.includes(s));
 }