gsd-pi 2.35.0-dev.30eec3f → 2.35.0-dev.34ce717

package/README.md

@@ -455,7 +455,9 @@ auto_report: true
 
 ### Agent Instructions
 
-Create an `agent-instructions.md` file in your project root to inject persistent per-project behavioral guidance into every agent session. This file is loaded automatically and provides project-specific context the LLM should always have — coding standards, architectural decisions, domain terminology, or workflow preferences.
+Place an `AGENTS.md` file in any directory to provide persistent behavioral guidance for that scope. Pi core loads `AGENTS.md` automatically (with `CLAUDE.md` as a fallback) at both user and project levels. Use these files for coding standards, architectural decisions, domain terminology, or workflow preferences.
+
+> **Note:** The legacy `agent-instructions.md` format (`~/.gsd/agent-instructions.md` and `.gsd/agent-instructions.md`) is deprecated and no longer loaded. Migrate any existing instructions to `AGENTS.md` or `CLAUDE.md`.
 
 ### Debug Mode
 

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

@@ -632,6 +632,11 @@ export async function autoLoop(ctx, pi, s, deps) {
                 unitType,
                 unitId,
             });
+            // Detect retry and capture previous tier for escalation
+            const isRetry = !!(s.currentUnit &&
+                s.currentUnit.type === unitType &&
+                s.currentUnit.id === unitId);
+            const previousTier = s.currentUnitRouting?.tier;
             // Closeout previous unit
             if (s.currentUnit) {
                 await deps.closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
@@ -737,8 +742,8 @@ export async function autoLoop(ctx, pi, s, deps) {
                 const msg = reorderErr instanceof Error ? reorderErr.message : String(reorderErr);
                 process.stderr.write(`[gsd] prompt reorder failed (non-fatal): ${msg}\n`);
             }
-            // Select and apply model
-            const modelResult = await deps.selectAndApplyModel(ctx, pi, unitType, unitId, s.basePath, prefs, s.verbose, s.autoModeStartModel);
+            // Select and apply model (with tier escalation on retry)
+            const modelResult = await deps.selectAndApplyModel(ctx, pi, unitType, unitId, s.basePath, prefs, s.verbose, s.autoModeStartModel, { isRetry, previousTier });
             s.currentUnitRouting =
                 modelResult.routing;
             // Start unit supervision

package/dist/resources/extensions/gsd/auto-model-selection.js

@@ -5,7 +5,7 @@
  */
 import { resolveModelWithFallbacksForUnit, resolveDynamicRoutingConfig } from "./preferences.js";
 import { classifyUnitComplexity, tierLabel } from "./complexity-classifier.js";
-import { resolveModelForComplexity } from "./model-router.js";
+import { resolveModelForComplexity, escalateTier } from "./model-router.js";
 import { getLedger, getProjectTotals } from "./metrics.js";
 import { unitPhaseLabel } from "./auto-dashboard.js";
 /**
@@ -15,7 +15,7 @@ import { unitPhaseLabel } from "./auto-dashboard.js";
  *
  * Returns routing metadata for metrics tracking.
  */
-export async function selectAndApplyModel(ctx, pi, unitType, unitId, basePath, prefs, verbose, autoModeStartModel) {
+export async function selectAndApplyModel(ctx, pi, unitType, unitId, basePath, prefs, verbose, autoModeStartModel, retryContext) {
     const modelConfig = resolveModelWithFallbacksForUnit(unitType);
     let routing = null;
     if (modelConfig) {
@@ -37,8 +37,20 @@ export async function selectAndApplyModel(ctx, pi, unitType, unitId, basePath, p
             const isHook = unitType.startsWith("hook/");
             const shouldClassify = !isHook || routingConfig.hooks !== false;
             if (shouldClassify) {
-                const classification = classifyUnitComplexity(unitType, unitId, basePath, budgetPct);
+                let classification = classifyUnitComplexity(unitType, unitId, basePath, budgetPct);
                 const availableModelIds = availableModels.map(m => m.id);
+                // Escalate tier on retry when escalate_on_failure is enabled (default: true)
+                if (retryContext?.isRetry &&
+                    retryContext.previousTier &&
+                    routingConfig.escalate_on_failure !== false) {
+                    const escalated = escalateTier(retryContext.previousTier);
+                    if (escalated) {
+                        classification = { ...classification, tier: escalated, reason: "escalated after failure" };
+                        if (verbose) {
+                            ctx.ui.notify(`Tier escalation: ${retryContext.previousTier} → ${escalated} (retry after failure)`, "info");
+                        }
+                    }
+                }
                 const routingResult = resolveModelForComplexity(classification, modelConfig, routingConfig, availableModelIds);
                 if (routingResult.wasDowngraded) {
                     effectiveModelConfig = {

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

@@ -0,0 +1,31 @@
+/**
+ * /gsd rate — Submit feedback on the last unit's model tier assignment.
+ * Feeds into the adaptive routing history so future dispatches improve.
+ */
+import { loadLedgerFromDisk } from "./metrics.js";
+import { recordFeedback, initRoutingHistory } from "./routing-history.js";
+const VALID_RATINGS = new Set(["over", "under", "ok"]);
+export async function handleRate(args, ctx, basePath) {
+    const rating = args.trim().toLowerCase();
+    if (!rating || !VALID_RATINGS.has(rating)) {
+        ctx.ui.notify("Usage: /gsd rate <over|ok|under>\n" +
+            "  over  — model was overpowered for that task (encourage cheaper)\n" +
+            "  ok    — model was appropriate\n" +
+            "  under — model was too weak (encourage stronger)", "info");
+        return;
+    }
+    const ledger = loadLedgerFromDisk(basePath);
+    if (!ledger || ledger.units.length === 0) {
+        ctx.ui.notify("No completed units found — nothing to rate.", "warning");
+        return;
+    }
+    const lastUnit = ledger.units[ledger.units.length - 1];
+    const tier = lastUnit.tier;
+    if (!tier) {
+        ctx.ui.notify("Last unit has no tier data (dynamic routing was not active). Rating skipped.", "warning");
+        return;
+    }
+    initRoutingHistory(basePath);
+    recordFeedback(lastUnit.type, lastUnit.id, tier, rating);
+    ctx.ui.notify(`Recorded "${rating}" for ${lastUnit.type}/${lastUnit.id} at tier ${tier}.`, "info");
+}

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

@@ -36,6 +36,7 @@ import { computeProgressScore, formatProgressLine } from "./progress-score.js";
 import { runEnvironmentChecks } from "./doctor-environment.js";
 import { handleLogs } from "./commands-logs.js";
 import { handleStart, handleTemplates, getTemplateCompletions } from "./commands-workflow-templates.js";
+import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
 /** Resolve the effective project root, accounting for worktree paths. */
 export function projectRoot() {
     const cwd = process.cwd();
@@ -54,6 +55,38 @@ export function projectRoot() {
     }
     return root;
 }
+/**
+ * Check if another process holds the auto-mode session lock.
+ * Returns the lock data if a remote session is alive, null otherwise.
+ */
+function getRemoteAutoSession(basePath) {
+    const lockData = readSessionLockData(basePath);
+    if (!lockData)
+        return null;
+    if (lockData.pid === process.pid)
+        return null;
+    if (!isSessionLockProcessAlive(lockData))
+        return null;
+    return { pid: lockData.pid };
+}
+/**
+ * Show a steering menu when auto-mode is running in another process.
+ * Returns true if a remote session was detected (caller should return early).
+ */
+function notifyRemoteAutoActive(ctx, basePath) {
+    const remote = getRemoteAutoSession(basePath);
+    if (!remote)
+        return false;
+    ctx.ui.notify(`Auto-mode is running in another process (PID ${remote.pid}).\n` +
+        `Use these commands to interact with it:\n` +
+        `  /gsd status   — check progress\n` +
+        `  /gsd discuss  — discuss architecture decisions\n` +
+        `  /gsd queue    — queue the next milestone\n` +
+        `  /gsd steer    — apply an override to active work\n` +
+        `  /gsd capture  — fire-and-forget thought\n` +
+        `  /gsd stop     — stop auto-mode`, "warning");
+    return true;
+}
 export function registerGSDCommand(pi) {
     pi.registerCommand("gsd", {
         description: "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|dispatch|history|undo|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|update",
@@ -74,6 +107,7 @@ export function registerGSDCommand(pi) {
                 { cmd: "triage", desc: "Manually trigger triage of pending captures" },
                 { cmd: "dispatch", desc: "Dispatch a specific phase directly" },
                 { cmd: "history", desc: "View execution history" },
+                { cmd: "rate", desc: "Rate last unit's model tier (over/ok/under) — improves adaptive routing" },
                 { cmd: "undo", desc: "Revert last completed unit" },
                 { cmd: "skip", desc: "Prevent a unit from auto-mode dispatch" },
                 { cmd: "export", desc: "Export milestone/slice results" },
@@ -459,6 +493,8 @@ export async function handleGSDCommand(args, ctx, pi) {
             await handleDryRun(ctx, projectRoot());
             return;
         }
+        if (notifyRemoteAutoActive(ctx, projectRoot()))
+            return;
         const verboseMode = trimmed.includes("--verbose");
         const debugMode = trimmed.includes("--debug");
         if (debugMode)
@@ -513,6 +549,11 @@ export async function handleGSDCommand(args, ctx, pi) {
         await handleUndo(trimmed.replace(/^undo\s*/, "").trim(), ctx, pi, projectRoot());
         return;
     }
+    if (trimmed === "rate" || trimmed.startsWith("rate ")) {
+        const { handleRate } = await import("./commands-rate.js");
+        await handleRate(trimmed.replace(/^rate\s*/, "").trim(), ctx, projectRoot());
+        return;
+    }
     if (trimmed.startsWith("skip ")) {
         await handleSkip(trimmed.replace(/^skip\s*/, "").trim(), ctx, projectRoot());
         return;
@@ -809,7 +850,8 @@ Examples:
         return;
     }
     if (trimmed === "") {
-        // Bare /gsd defaults to step mode
+        if (notifyRemoteAutoActive(ctx, projectRoot()))
+            return;
         await startAuto(ctx, pi, projectRoot(), false, { step: true });
         return;
     }

package/dist/resources/extensions/gsd/guided-flow.js

@@ -17,6 +17,7 @@ import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdRoot, milestonesDir, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, } from "./paths.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from "node:fs";
+import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
 import { nativeIsRepo, nativeInit } from "./native-git-bridge.js";
 import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
@@ -426,7 +427,12 @@ export async function showDiscuss(ctx, pi, basePath) {
         // If all pending slices are discussed, notify and exit instead of looping
         const allDiscussed = pendingSlices.every(s => discussedMap.get(s.id));
         if (allDiscussed) {
-            ctx.ui.notify(`All ${pendingSlices.length} slices discussed. Run /gsd to start planning.`, "info");
+            const lockData = readSessionLockData(basePath);
+            const remoteAutoRunning = lockData && lockData.pid !== process.pid && isSessionLockProcessAlive(lockData);
+            const nextStep = remoteAutoRunning
+                ? "Auto-mode is already running — use /gsd status to check progress."
+                : "Run /gsd to start planning.";
+            ctx.ui.notify(`All ${pendingSlices.length} slices discussed. ${nextStep}`, "info");
             return;
         }
         // Find the first undiscussed slice to recommend

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

@@ -46,33 +46,21 @@ import { pauseAutoForProviderError, classifyProviderError } from "./provider-err
 import { toPosixPath } from "../shared/mod.js";
 import { isParallelActive, shutdownParallel } from "./parallel-orchestrator.js";
 import { DEFAULT_BASH_TIMEOUT_SECS } from "./constants.js";
-// ── Agent Instructions ────────────────────────────────────────────────────
-// Lightweight "always follow" files injected into every GSD agent session.
-// Global: ~/.gsd/agent-instructions.md   Project: .gsd/agent-instructions.md
-// Both are loaded and concatenated (global first, project appends).
-function loadAgentInstructions() {
-    const parts = [];
-    const globalPath = join(homedir(), ".gsd", "agent-instructions.md");
-    if (existsSync(globalPath)) {
-        try {
-            const content = readFileSync(globalPath, "utf-8").trim();
-            if (content)
-                parts.push(content);
-        }
-        catch { /* non-fatal — skip unreadable file */ }
-    }
-    const projectPath = join(process.cwd(), ".gsd", "agent-instructions.md");
-    if (existsSync(projectPath)) {
-        try {
-            const content = readFileSync(projectPath, "utf-8").trim();
-            if (content)
-                parts.push(content);
+// ── Agent Instructions (DEPRECATED) ──────────────────────────────────────
+// agent-instructions.md is deprecated. Use AGENTS.md or CLAUDE.md instead.
+// Pi core natively supports AGENTS.md (with CLAUDE.md fallback) per directory.
+function warnDeprecatedAgentInstructions() {
+    const paths = [
+        join(homedir(), ".gsd", "agent-instructions.md"),
+        join(process.cwd(), ".gsd", "agent-instructions.md"),
+    ];
+    for (const p of paths) {
+        if (existsSync(p)) {
+            console.warn(`[GSD] DEPRECATED: ${p} is no longer loaded. ` +
+                `Migrate your instructions to AGENTS.md (or CLAUDE.md) in the same directory. ` +
+                `See https://github.com/gsd-build/GSD-2/issues/1492`);
         }
-        catch { /* non-fatal — skip unreadable file */ }
     }
-    if (parts.length === 0)
-        return null;
-    return parts.join("\n\n");
 }
 // ── Depth verification state ──────────────────────────────────────────────
 let depthVerificationDone = false;
@@ -589,12 +577,8 @@ export default function (pi) {
                 newSkillsBlock = formatSkillsXml(newSkills);
             }
         }
-        // Load agent instructions (global + project)
-        let agentInstructionsBlock = "";
-        const agentInstructions = loadAgentInstructions();
-        if (agentInstructions) {
-            agentInstructionsBlock = `\n\n## Agent Instructions\n\nThe following instructions were provided by the user and must be followed in every session:\n\n${agentInstructions}`;
-        }
+        // Warn if deprecated agent-instructions.md files are still present
+        warnDeprecatedAgentInstructions();
         const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
         // Worktree context — override the static CWD in the system prompt
         let worktreeBlock = "";
@@ -637,7 +621,7 @@ export default function (pi) {
                 "Write every .gsd artifact in the worktree path above, never in the main project tree.",
             ].join("\n");
         }
-        const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${agentInstructionsBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
+        const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
         stopContextTimer({
             systemPromptSize: fullSystem.length,
             injectionSize: injection?.length ?? 0,

package/dist/resources/extensions/gsd/milestone-ids.js

@@ -67,8 +67,9 @@ export function findMilestoneIds(basePath) {
             .filter((d) => d.isDirectory())
             .map((d) => {
             const match = d.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/);
-            return match ? match[1] : d.name;
-        });
+            return match ? match[1] : null;
+        })
+            .filter((id) => id !== null);
         // Apply custom queue order if available, else fall back to numeric sort
         const customOrder = loadQueueOrder(basePath);
         return sortByQueueOrder(ids, customOrder);

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

@@ -15,6 +15,7 @@ import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { parse as parseYaml } from "yaml";
 import { normalizeStringArray } from "../shared/mod.js";
+import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
 import { MODE_DEFAULTS, } from "./preferences-types.js";
 import { validatePreferences } from "./preferences-validation.js";
 import { formatSkillRef } from "./preferences-skills.js";
@@ -79,6 +80,17 @@ export function loadEffectiveGSDPreferences() {
             ...(mergedWarnings.length > 0 ? { warnings: mergedWarnings } : {}),
         };
     }
+    // Apply token-profile defaults as the lowest-priority layer so that
+    // `token_profile: budget` sets models and phase-skips automatically.
+    // Explicit user preferences always override profile defaults.
+    const profile = result.preferences.token_profile;
+    if (profile) {
+        const profileDefaults = _resolveProfileDefaults(profile);
+        result = {
+            ...result,
+            preferences: mergePreferences(profileDefaults, result.preferences),
+        };
+    }
     // Apply mode defaults as the lowest-priority layer
     if (result.preferences.mode) {
         result = {

package/dist/resources/extensions/gsd/session-lock.js

@@ -231,6 +231,14 @@ export function acquireSessionLock(basePath) {
                     stale: 1_800_000, // 30 minutes — match primary lock settings
                     update: 10_000,
                     onCompromised: () => {
+                        // Same false-positive suppression as the primary lock (#1512).
+                        // Without this, the retry path fires _lockCompromised unconditionally
+                        // on benign mtime drift (laptop sleep, heavy LLM event loop stalls).
+                        const elapsed = Date.now() - _lockAcquiredAt;
+                        if (elapsed < 1_800_000) {
+                            process.stderr.write(`[gsd] Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — event loop stall, continuing.\n`);
+                            return;
+                        }
                         _lockCompromised = true;
                         _releaseFunction = null;
                     },
@@ -315,6 +323,25 @@ export function updateSessionLock(basePath, unitType, unitId, completedUnits, se
 export function validateSessionLock(basePath) {
     // Lock was compromised by proper-lockfile (mtime drift from sleep, stall, etc.)
     if (_lockCompromised) {
+        // Recovery gate (#1512): Before declaring the lock lost, check if the lock
+        // file still contains our PID. If it does, no other process took over — the
+        // onCompromised fired from benign mtime drift (laptop sleep, event loop stall
+        // beyond the stale window). Attempt re-acquisition instead of giving up.
+        const lp = lockPath(basePath);
+        const existing = readExistingLockData(lp);
+        if (existing && existing.pid === process.pid) {
+            // Lock file still ours — try to re-acquire the OS lock
+            try {
+                const result = acquireSessionLock(basePath);
+                if (result.acquired) {
+                    process.stderr.write(`[gsd] Lock recovered after onCompromised — lock file PID matched, re-acquired.\n`);
+                    return true;
+                }
+            }
+            catch {
+                // Re-acquisition failed — fall through to return false
+            }
+        }
         return false;
     }
     // If we have an OS-level lock, we're still the owner

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

@@ -33,11 +33,12 @@ export function isValidationTerminal(validationContent) {
     const verdict = match[1].match(/verdict:\s*(\S+)/);
     if (!verdict)
         return false;
+    const v = verdict[1] === 'passed' ? 'pass' : verdict[1];
     // 'pass' and 'needs-attention' are always terminal.
     // 'needs-remediation' is treated as terminal to prevent infinite loops
     // when no remediation slices exist in the roadmap (#832). The validation
     // report is preserved on disk for manual review.
-    return verdict[1] === 'pass' || verdict[1] === 'needs-attention' || verdict[1] === 'needs-remediation';
+    return v === 'pass' || v === 'needs-attention' || v === 'needs-remediation';
 }
 const CACHE_TTL_MS = 100;
 let _stateCache = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-pi",
-  "version": "2.35.0-dev.30eec3f",
+  "version": "2.35.0-dev.34ce717",
   "description": "GSD — Get Shit Done coding agent",
   "license": "MIT",
   "repository": {

package/src/resources/extensions/gsd/auto-loop.ts

@@ -456,6 +456,7 @@ export interface LoopDeps {
     prefs: GSDPreferences | undefined,
     verbose: boolean,
     startModel: { provider: string; id: string } | null,
+    retryContext?: { isRetry: boolean; previousTier?: string },
   ) => Promise<{ routing: { tier: string; modelDowngraded: boolean } | null }>;
   startUnitSupervision: (sctx: {
     s: AutoSession;
@@ -1182,6 +1183,14 @@ export async function autoLoop(
         unitId,
       });
 
+      // Detect retry and capture previous tier for escalation
+      const isRetry = !!(
+        s.currentUnit &&
+        s.currentUnit.type === unitType &&
+        s.currentUnit.id === unitId
+      );
+      const previousTier = s.currentUnitRouting?.tier;
+
       // Closeout previous unit
       if (s.currentUnit) {
         await deps.closeoutUnit(
@@ -1335,7 +1344,7 @@ export async function autoLoop(
         );
       }
 
-      // Select and apply model
+      // Select and apply model (with tier escalation on retry)
       const modelResult = await deps.selectAndApplyModel(
         ctx,
         pi,
@@ -1345,6 +1354,7 @@ export async function autoLoop(
         prefs,
         s.verbose,
         s.autoModeStartModel,
+        { isRetry, previousTier },
       );
       s.currentUnitRouting =
         modelResult.routing as AutoSession["currentUnitRouting"];

package/src/resources/extensions/gsd/auto-model-selection.ts

@@ -7,8 +7,9 @@
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import type { GSDPreferences } from "./preferences.js";
 import { resolveModelWithFallbacksForUnit, resolveDynamicRoutingConfig } from "./preferences.js";
+import type { ComplexityTier } from "./complexity-classifier.js";
 import { classifyUnitComplexity, tierLabel } from "./complexity-classifier.js";
-import { resolveModelForComplexity } from "./model-router.js";
+import { resolveModelForComplexity, escalateTier } from "./model-router.js";
 import { getLedger, getProjectTotals } from "./metrics.js";
 import { unitPhaseLabel } from "./auto-dashboard.js";
 
@@ -33,6 +34,7 @@ export async function selectAndApplyModel(
   prefs: GSDPreferences | undefined,
   verbose: boolean,
   autoModeStartModel: { provider: string; id: string } | null,
+  retryContext?: { isRetry: boolean; previousTier?: string },
 ): Promise<ModelSelectionResult> {
   const modelConfig = resolveModelWithFallbacksForUnit(unitType);
   let routing: { tier: string; modelDowngraded: boolean } | null = null;
@@ -60,8 +62,27 @@ export async function selectAndApplyModel(
       const shouldClassify = !isHook || routingConfig.hooks !== false;
 
       if (shouldClassify) {
-        const classification = classifyUnitComplexity(unitType, unitId, basePath, budgetPct);
+        let classification = classifyUnitComplexity(unitType, unitId, basePath, budgetPct);
         const availableModelIds = availableModels.map(m => m.id);
+
+        // Escalate tier on retry when escalate_on_failure is enabled (default: true)
+        if (
+          retryContext?.isRetry &&
+          retryContext.previousTier &&
+          routingConfig.escalate_on_failure !== false
+        ) {
+          const escalated = escalateTier(retryContext.previousTier as ComplexityTier);
+          if (escalated) {
+            classification = { ...classification, tier: escalated, reason: "escalated after failure" };
+            if (verbose) {
+              ctx.ui.notify(
+                `Tier escalation: ${retryContext.previousTier} → ${escalated} (retry after failure)`,
+                "info",
+              );
+            }
+          }
+        }
+
         const routingResult = resolveModelForComplexity(classification, modelConfig, routingConfig, availableModelIds);
 
         if (routingResult.wasDowngraded) {

package/src/resources/extensions/gsd/commands-rate.ts

@@ -0,0 +1,55 @@
+/**
+ * /gsd rate — Submit feedback on the last unit's model tier assignment.
+ * Feeds into the adaptive routing history so future dispatches improve.
+ */
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { loadLedgerFromDisk } from "./metrics.js";
+import { recordFeedback, initRoutingHistory } from "./routing-history.js";
+import type { ComplexityTier } from "./complexity-classifier.js";
+
+const VALID_RATINGS = new Set(["over", "under", "ok"]);
+
+export async function handleRate(
+  args: string,
+  ctx: ExtensionCommandContext,
+  basePath: string,
+): Promise<void> {
+  const rating = args.trim().toLowerCase();
+
+  if (!rating || !VALID_RATINGS.has(rating)) {
+    ctx.ui.notify(
+      "Usage: /gsd rate <over|ok|under>\n" +
+      "  over  — model was overpowered for that task (encourage cheaper)\n" +
+      "  ok    — model was appropriate\n" +
+      "  under — model was too weak (encourage stronger)",
+      "info",
+    );
+    return;
+  }
+
+  const ledger = loadLedgerFromDisk(basePath);
+  if (!ledger || ledger.units.length === 0) {
+    ctx.ui.notify("No completed units found — nothing to rate.", "warning");
+    return;
+  }
+
+  const lastUnit = ledger.units[ledger.units.length - 1];
+  const tier = lastUnit.tier as ComplexityTier | undefined;
+
+  if (!tier) {
+    ctx.ui.notify(
+      "Last unit has no tier data (dynamic routing was not active). Rating skipped.",
+      "warning",
+    );
+    return;
+  }
+
+  initRoutingHistory(basePath);
+  recordFeedback(lastUnit.type, lastUnit.id, tier, rating as "over" | "under" | "ok");
+
+  ctx.ui.notify(
+    `Recorded "${rating}" for ${lastUnit.type}/${lastUnit.id} at tier ${tier}.`,
+    "info",
+  );
+}

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

@@ -48,6 +48,7 @@ import { computeProgressScore, formatProgressLine } from "./progress-score.js";
 import { runEnvironmentChecks } from "./doctor-environment.js";
 import { handleLogs } from "./commands-logs.js";
 import { handleStart, handleTemplates, getTemplateCompletions } from "./commands-workflow-templates.js";
+import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
 
 
 /** Resolve the effective project root, accounting for worktree paths. */
@@ -69,6 +70,39 @@ export function projectRoot(): string {
   return root;
 }
 
+/**
+ * Check if another process holds the auto-mode session lock.
+ * Returns the lock data if a remote session is alive, null otherwise.
+ */
+function getRemoteAutoSession(basePath: string): { pid: number } | null {
+  const lockData = readSessionLockData(basePath);
+  if (!lockData) return null;
+  if (lockData.pid === process.pid) return null;
+  if (!isSessionLockProcessAlive(lockData)) return null;
+  return { pid: lockData.pid };
+}
+
+/**
+ * Show a steering menu when auto-mode is running in another process.
+ * Returns true if a remote session was detected (caller should return early).
+ */
+function notifyRemoteAutoActive(ctx: ExtensionCommandContext, basePath: string): boolean {
+  const remote = getRemoteAutoSession(basePath);
+  if (!remote) return false;
+  ctx.ui.notify(
+    `Auto-mode is running in another process (PID ${remote.pid}).\n` +
+    `Use these commands to interact with it:\n` +
+    `  /gsd status   — check progress\n` +
+    `  /gsd discuss  — discuss architecture decisions\n` +
+    `  /gsd queue    — queue the next milestone\n` +
+    `  /gsd steer    — apply an override to active work\n` +
+    `  /gsd capture  — fire-and-forget thought\n` +
+    `  /gsd stop     — stop auto-mode`,
+    "warning",
+  );
+  return true;
+}
+
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
     description: "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|dispatch|history|undo|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|update",
@@ -89,6 +123,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         { cmd: "triage", desc: "Manually trigger triage of pending captures" },
         { cmd: "dispatch", desc: "Dispatch a specific phase directly" },
         { cmd: "history", desc: "View execution history" },
+        { cmd: "rate", desc: "Rate last unit's model tier (over/ok/under) — improves adaptive routing" },
         { cmd: "undo", desc: "Revert last completed unit" },
         { cmd: "skip", desc: "Prevent a unit from auto-mode dispatch" },
         { cmd: "export", desc: "Export milestone/slice results" },
@@ -511,6 +546,7 @@ export async function handleGSDCommand(
           await handleDryRun(ctx, projectRoot());
           return;
         }
+        if (notifyRemoteAutoActive(ctx, projectRoot())) return;
         const verboseMode = trimmed.includes("--verbose");
         const debugMode = trimmed.includes("--debug");
         if (debugMode) enableDebug(projectRoot());
@@ -566,6 +602,12 @@ export async function handleGSDCommand(
         return;
       }
 
+      if (trimmed === "rate" || trimmed.startsWith("rate ")) {
+        const { handleRate } = await import("./commands-rate.js");
+        await handleRate(trimmed.replace(/^rate\s*/, "").trim(), ctx, projectRoot());
+        return;
+      }
+
       if (trimmed.startsWith("skip ")) {
         await handleSkip(trimmed.replace(/^skip\s*/, "").trim(), ctx, projectRoot());
         return;
@@ -899,7 +941,7 @@ Examples:
       }
 
       if (trimmed === "") {
-        // Bare /gsd defaults to step mode
+        if (notifyRemoteAutoActive(ctx, projectRoot())) return;
         await startAuto(ctx, pi, projectRoot(), false, { step: true });
         return;
       }

package/src/resources/extensions/gsd/guided-flow.ts

@@ -23,6 +23,7 @@ import {
 } from "./paths.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
 import { nativeIsRepo, nativeInit } from "./native-git-bridge.js";
 import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
@@ -516,8 +517,13 @@ export async function showDiscuss(
     // If all pending slices are discussed, notify and exit instead of looping
     const allDiscussed = pendingSlices.every(s => discussedMap.get(s.id));
     if (allDiscussed) {
+      const lockData = readSessionLockData(basePath);
+      const remoteAutoRunning = lockData && lockData.pid !== process.pid && isSessionLockProcessAlive(lockData);
+      const nextStep = remoteAutoRunning
+        ? "Auto-mode is already running — use /gsd status to check progress."
+        : "Run /gsd to start planning.";
       ctx.ui.notify(
-        `All ${pendingSlices.length} slices discussed. Run /gsd to start planning.`,
+        `All ${pendingSlices.length} slices discussed. ${nextStep}`,
         "info",
       );
       return;

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

@@ -66,32 +66,24 @@ import { toPosixPath } from "../shared/mod.js";
 import { isParallelActive, shutdownParallel } from "./parallel-orchestrator.js";
 import { DEFAULT_BASH_TIMEOUT_SECS } from "./constants.js";
 
-// ── Agent Instructions ────────────────────────────────────────────────────
-// Lightweight "always follow" files injected into every GSD agent session.
-// Global: ~/.gsd/agent-instructions.md   Project: .gsd/agent-instructions.md
-// Both are loaded and concatenated (global first, project appends).
-
-function loadAgentInstructions(): string | null {
-  const parts: string[] = [];
-
-  const globalPath = join(homedir(), ".gsd", "agent-instructions.md");
-  if (existsSync(globalPath)) {
-    try {
-      const content = readFileSync(globalPath, "utf-8").trim();
-      if (content) parts.push(content);
-    } catch { /* non-fatal — skip unreadable file */ }
-  }
-
-  const projectPath = join(process.cwd(), ".gsd", "agent-instructions.md");
-  if (existsSync(projectPath)) {
-    try {
-      const content = readFileSync(projectPath, "utf-8").trim();
-      if (content) parts.push(content);
-    } catch { /* non-fatal — skip unreadable file */ }
+// ── Agent Instructions (DEPRECATED) ──────────────────────────────────────
+// agent-instructions.md is deprecated. Use AGENTS.md or CLAUDE.md instead.
+// Pi core natively supports AGENTS.md (with CLAUDE.md fallback) per directory.
+
+function warnDeprecatedAgentInstructions(): void {
+  const paths = [
+    join(homedir(), ".gsd", "agent-instructions.md"),
+    join(process.cwd(), ".gsd", "agent-instructions.md"),
+  ];
+  for (const p of paths) {
+    if (existsSync(p)) {
+      console.warn(
+        `[GSD] DEPRECATED: ${p} is no longer loaded. ` +
+        `Migrate your instructions to AGENTS.md (or CLAUDE.md) in the same directory. ` +
+        `See https://github.com/gsd-build/GSD-2/issues/1492`,
+      );
+    }
   }
-
-  if (parts.length === 0) return null;
-  return parts.join("\n\n");
 }
 
 // ── Depth verification state ──────────────────────────────────────────────
@@ -682,12 +674,8 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    // Load agent instructions (global + project)
-    let agentInstructionsBlock = "";
-    const agentInstructions = loadAgentInstructions();
-    if (agentInstructions) {
-      agentInstructionsBlock = `\n\n## Agent Instructions\n\nThe following instructions were provided by the user and must be followed in every session:\n\n${agentInstructions}`;
-    }
+    // Warn if deprecated agent-instructions.md files are still present
+    warnDeprecatedAgentInstructions();
 
     const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
 
@@ -732,7 +720,7 @@ export default function (pi: ExtensionAPI) {
       ].join("\n");
     }
 
-    const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${agentInstructionsBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
+    const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
     stopContextTimer({
       systemPromptSize: fullSystem.length,
       injectionSize: injection?.length ?? 0,

package/src/resources/extensions/gsd/milestone-ids.ts

@@ -80,8 +80,9 @@ export function findMilestoneIds(basePath: string): string[] {
       .filter((d) => d.isDirectory())
       .map((d) => {
         const match = d.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/);
-        return match ? match[1] : d.name;
-      });
+        return match ? match[1] : null;
+      })
+      .filter((id): id is string => id !== null);
 
     // Apply custom queue order if available, else fall back to numeric sort
     const customOrder = loadQueueOrder(basePath);

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

@@ -15,9 +15,10 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { parse as parseYaml } from "yaml";
-import type { PostUnitHookConfig, PreDispatchHookConfig } from "./types.js";
+import type { PostUnitHookConfig, PreDispatchHookConfig, TokenProfile } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
 import { normalizeStringArray } from "../shared/mod.js";
+import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
 
 import {
   MODE_DEFAULTS,
@@ -141,6 +142,18 @@ export function loadEffectiveGSDPreferences(): LoadedGSDPreferences | null {
     };
   }
 
+  // Apply token-profile defaults as the lowest-priority layer so that
+  // `token_profile: budget` sets models and phase-skips automatically.
+  // Explicit user preferences always override profile defaults.
+  const profile = result.preferences.token_profile as TokenProfile | undefined;
+  if (profile) {
+    const profileDefaults = _resolveProfileDefaults(profile);
+    result = {
+      ...result,
+      preferences: mergePreferences(profileDefaults as GSDPreferences, result.preferences),
+    };
+  }
+
   // Apply mode defaults as the lowest-priority layer
   if (result.preferences.mode) {
     result = {

package/src/resources/extensions/gsd/session-lock.ts

@@ -260,6 +260,16 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
           stale: 1_800_000, // 30 minutes — match primary lock settings
           update: 10_000,
           onCompromised: () => {
+            // Same false-positive suppression as the primary lock (#1512).
+            // Without this, the retry path fires _lockCompromised unconditionally
+            // on benign mtime drift (laptop sleep, heavy LLM event loop stalls).
+            const elapsed = Date.now() - _lockAcquiredAt;
+            if (elapsed < 1_800_000) {
+              process.stderr.write(
+                `[gsd] Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — event loop stall, continuing.\n`,
+              );
+              return;
+            }
             _lockCompromised = true;
             _releaseFunction = null;
           },
@@ -361,6 +371,26 @@ export function updateSessionLock(
 export function validateSessionLock(basePath: string): boolean {
   // Lock was compromised by proper-lockfile (mtime drift from sleep, stall, etc.)
   if (_lockCompromised) {
+    // Recovery gate (#1512): Before declaring the lock lost, check if the lock
+    // file still contains our PID. If it does, no other process took over — the
+    // onCompromised fired from benign mtime drift (laptop sleep, event loop stall
+    // beyond the stale window). Attempt re-acquisition instead of giving up.
+    const lp = lockPath(basePath);
+    const existing = readExistingLockData(lp);
+    if (existing && existing.pid === process.pid) {
+      // Lock file still ours — try to re-acquire the OS lock
+      try {
+        const result = acquireSessionLock(basePath);
+        if (result.acquired) {
+          process.stderr.write(
+            `[gsd] Lock recovered after onCompromised — lock file PID matched, re-acquired.\n`,
+          );
+          return true;
+        }
+      } catch {
+        // Re-acquisition failed — fall through to return false
+      }
+    }
     return false;
   }
 

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

@@ -64,11 +64,12 @@ export function isValidationTerminal(validationContent: string): boolean {
   if (!match) return false;
   const verdict = match[1].match(/verdict:\s*(\S+)/);
   if (!verdict) return false;
+  const v = verdict[1] === 'passed' ? 'pass' : verdict[1];
   // 'pass' and 'needs-attention' are always terminal.
   // 'needs-remediation' is treated as terminal to prevent infinite loops
   // when no remediation slices exist in the roadmap (#832). The validation
   // report is preserved on disk for manual review.
-  return verdict[1] === 'pass' || verdict[1] === 'needs-attention' || verdict[1] === 'needs-remediation';
+  return v === 'pass' || v === 'needs-attention' || v === 'needs-remediation';
 }
 
 // ─── State Derivation ──────────────────────────────────────────────────────

package/src/resources/extensions/gsd/tests/queue-reorder-e2e.test.ts

@@ -244,6 +244,32 @@ console.log('\n=== E2E: backward compat without QUEUE-ORDER.json ===');
   }
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// Test: non-milestone directories are filtered out (#1494)
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== E2E: non-milestone directories filtered from findMilestoneIds (#1494) ===');
+{
+  const base = createFixtureBase();
+  try {
+    writeContext(base, 'M001', '', 'First');
+    writeContext(base, 'M002', '', 'Second');
+    // Create a rogue non-milestone directory
+    mkdirSync(join(base, '.gsd', 'milestones', 'slices'), { recursive: true });
+    mkdirSync(join(base, '.gsd', 'milestones', 'temp-backup'), { recursive: true });
+
+    invalidateStateCache();
+    const ids = findMilestoneIds(base);
+    assertEq(ids.length, 2, 'only M001 and M002 returned');
+    assertTrue(!ids.includes('slices'), 'slices directory excluded');
+    assertTrue(!ids.includes('temp-backup'), 'temp-backup directory excluded');
+    assertTrue(ids.includes('M001'), 'M001 included');
+    assertTrue(ids.includes('M002'), 'M002 included');
+  } finally {
+    cleanup(base);
+  }
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // Test: depends_on inline array format removal
 // ═══════════════════════════════════════════════════════════════════════════

package/src/resources/extensions/gsd/tests/validate-milestone.test.ts

@@ -104,6 +104,11 @@ test("isValidationTerminal returns true for verdict: needs-remediation (#832)",
   assert.equal(isValidationTerminal(content), true);
 });
 
+test("isValidationTerminal returns true for verdict: passed (#1429)", () => {
+  const content = "---\nverdict: passed\nremediation_round: 0\n---\n\n# Validation";
+  assert.equal(isValidationTerminal(content), true);
+});
+
 test("isValidationTerminal returns false for missing frontmatter", () => {
   const content = "# Validation\nNo frontmatter here.";
   assert.equal(isValidationTerminal(content), false);