@opengsd/gsd-pi 1.3.0 → 1.4.0

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

@@ -6,9 +6,11 @@
  */
 
 import { randomInt } from "node:crypto";
+import { join } from "node:path";
 import { logWarning } from "./workflow-logger.js";
 import { readdirSync, existsSync } from "node:fs";
-import { milestonesDir } from "./paths.js";
+import { milestonesDir, gsdProjectionRoot } from "./paths.js";
+import { LAYOUT_SEGMENTS } from "./layout-policy.js";
 import { loadQueueOrder, sortByQueueOrder } from "./queue-order.js";
 import { getErrorMessage } from "./error-utils.js";
 
@@ -139,26 +141,83 @@ export function clearReservedMilestoneIds(): void {
 
 // ─── Discovery ──────────────────────────────────────────────────────────────
 
-/** Scan the milestones directory and return IDs sorted by queue order (or numeric fallback). */
-export function findMilestoneIds(basePath: string): string[] {
-  const dir = milestonesDir(basePath);
+function scanMilestoneIdsFromDir(basePath: string, dir: string): string[] {
+  const legacyNumericIds = idsWithLegacyNumericDirs(basePath);
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => {
+      // Legacy layout: exact M001 or M001-abcdef directory name
+      if (MILESTONE_ID_RE.test(d.name)) {
+        return d.name;
+      }
+      // Legacy recovery/imports may contain bare numeric milestone directories
+      // (for example `milestones/15/15-ROADMAP.md`). The DB can preserve that
+      // id, and rebuild renders it, so drift scans must see it too.
+      if (/^\d+$/.test(d.name)) {
+        return d.name;
+      }
+      // Legacy layout: M001-abcdef-slug descriptor directories
+      const legacyMatch = d.name.match(/^(M\d{3}(?:-[a-z0-9]{6})?)-/);
+      if (legacyMatch) {
+        return legacyMatch[1]!;
+      }
+      // Flat-phase layout: NN-slug → M00N (slug may encode M00N or M00N-abcdef)
+      const flatMatch = d.name.match(/^(\d+)-(.+)$/);
+      if (flatMatch) {
+        const phaseNum = parseInt(flatMatch[1]!, 10);
+        const fromSlug = normalizeDiscussMilestoneId(flatMatch[2]!);
+        if (MILESTONE_ID_RE.test(fromSlug)) {
+          return fromSlug;
+        }
+        const numericId = String(phaseNum);
+        if (legacyNumericIds.has(numericId)) {
+          return numericId;
+        }
+        return `M${String(phaseNum).padStart(3, "0")}`;
+      }
+      return null;
+    })
+    .filter((id): id is string => id !== null);
+}
+
+function idsWithLegacyNumericDirs(basePath: string): Set<string> {
+  const legacyDir = join(gsdProjectionRoot(basePath), "milestones");
+  const ids = new Set<string>();
   try {
-    const ids = readdirSync(dir, { withFileTypes: true })
-      .filter((d) => d.isDirectory())
-      .map((d) => {
-        const match = d.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/);
-        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);
-    return sortByQueueOrder(ids, customOrder);
+    for (const entry of readdirSync(legacyDir, { withFileTypes: true })) {
+      if (entry.isDirectory() && /^\d+$/.test(entry.name)) ids.add(entry.name);
+    }
   } catch (err) {
-    // Log why milestone scanning failed — silent [] here causes infinite loops (#456)
-    if (existsSync(dir)) {
-      logWarning("engine", `findMilestoneIds: .gsd/milestones/ exists but readdirSync failed — ${getErrorMessage(err)}`);
+    // A missing legacy directory is the common, benign case (nothing to
+    // consult). Only surface a real failure when the directory exists but
+    // could not be read.
+    if (existsSync(legacyDir)) {
+      logWarning("engine", `idsWithLegacyNumericDirs: ${legacyDir} exists but readdirSync failed — ${getErrorMessage(err)}`);
+    }
+  }
+  return ids;
+}
+
+/** Scan the milestones directory and return IDs sorted by queue order (or numeric fallback). */
+export function findMilestoneIds(basePath: string): string[] {
+  const root = gsdProjectionRoot(basePath);
+  const dirs = [milestonesDir(basePath)];
+  const legacyDir = join(root, "milestones");
+  if (legacyDir !== dirs[0] && existsSync(legacyDir)) dirs.push(legacyDir);
+  const phasesDir = join(root, LAYOUT_SEGMENTS.level1);
+  if (phasesDir !== dirs[0] && existsSync(phasesDir)) dirs.push(phasesDir);
+
+  const ids = new Set<string>();
+  for (const dir of dirs) {
+    try {
+      for (const id of scanMilestoneIdsFromDir(basePath, dir)) ids.add(id);
+    } catch (err) {
+      if (existsSync(dir)) {
+        logWarning("engine", `findMilestoneIds: ${dir} exists but readdirSync failed — ${getErrorMessage(err)}`);
+      }
     }
-    return [];
   }
+
+  const customOrder = loadQueueOrder(basePath);
+  return sortByQueueOrder([...ids], customOrder);
 }

package/src/resources/extensions/gsd/milestone-implementation-evidence.ts

@@ -19,6 +19,16 @@ import { resolveTasksDir } from "./paths.js";
 
 /** Large enough for unbounded milestone-history git log scans in big repos. */
 const GIT_LOG_MAX_BUFFER = 16 * 1024 * 1024;
+const LOG_FIELD_SEPARATOR = "\x1f";
+const LOG_RECORD_SEPARATOR = "\x1e";
+
+type CommitRecord = {
+  hash: string;
+  parents: string;
+  committedAt: string;
+  message: string;
+  files: string[];
+};
 
 /**
  * Check whether a milestone produced implementation artifacts (non-`.gsd/`
@@ -198,7 +208,7 @@ function getChangedFilesFromMilestoneTaggedCommits(
   // 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}`,
+    "log", "--full-diff", "--name-only", "--format=%x1e%H%x1f%B%x1f", "HEAD", "--", `.gsd/milestones/${milestoneId}`,
   ]);
   if (!scoped.ok) return scoped;
   if (scoped.matched && classifyImplementationFiles(scoped.files) === "present") return scoped;
@@ -213,7 +223,7 @@ function getChangedFilesFromMilestoneTaggedCommits(
   // reintroducing the rolling-depth failure class removed in #4699 where
   // milestone evidence aged out behind unrelated activity.
   const unscoped = scanGsdTaggedCommits(basePath, milestoneId, [
-    "log", "--format=%H%x1f%B%x1e", "HEAD",
+    "log", "--name-only", "--format=%x1e%H%x1f%B%x1f", "HEAD",
   ]);
   if (!unscoped.ok) return scoped.matched ? scoped : unscoped;
   if (!unscoped.matched) return scoped;
@@ -299,8 +309,7 @@ function backfillChangedFilesFromUntaggedMilestoneCommits(
       if (record.parents.trim().split(/\s+/).filter(Boolean).length > 1) continue;
       if (commitMessageHasGsdTrailer(record.message)) continue;
 
-      const commitFiles = getChangedFilesForCommit(basePath, record.hash);
-      const implementationFiles = commitFiles.map(normalizeRepoPath).filter(isImplementationPath);
+      const implementationFiles = record.files.map(normalizeRepoPath).filter(isImplementationPath);
       if (implementationFiles.length === 0) continue;
       if (!implementationFiles.some((file) => hintSet.has(file))) continue;
 
@@ -323,25 +332,30 @@ function backfillChangedFilesFromUntaggedMilestoneCommits(
   }
 }
 
-function getCommitRecords(basePath: string): Array<{ hash: string; parents: string; committedAt: string; message: string }> {
-  const logOutput = execFileSync("git", ["log", "--format=%H%x1f%P%x1f%cI%x1f%B%x1e", "HEAD"], {
+function getCommitRecords(basePath: string): CommitRecord[] {
+  const logOutput = execFileSync("git", ["log", "--name-only", "--format=%x1e%H%x1f%P%x1f%cI%x1f%B%x1f", "HEAD"], {
     cwd: basePath,
     stdio: ["ignore", "pipe", "pipe"],
     encoding: "utf-8",
     maxBuffer: GIT_LOG_MAX_BUFFER,
   });
   return logOutput
-    .split("\x1e")
-    .map((record) => record.trim())
+    .split(LOG_RECORD_SEPARATOR)
     .filter(Boolean)
     .flatMap((record) => {
-      const parts = record.split("\x1f");
-      if (parts.length < 4) return [];
-      const [hash, parents, committedAt, ...messageParts] = parts;
-      return [{ hash: hash.trim(), parents: parents.trim(), committedAt: committedAt.trim(), message: messageParts.join("\x1f") }];
+      const parts = record.split(LOG_FIELD_SEPARATOR);
+      if (parts.length < 5) return [];
+      const [hash, parents, committedAt] = parts;
+      const files = parseNameOnlyFiles(parts.at(-1) ?? "");
+      const message = parts.slice(3, -1).join(LOG_FIELD_SEPARATOR);
+      return [{ hash: hash.trim(), parents: parents.trim(), committedAt: committedAt.trim(), message, files }];
     });
 }
 
+function parseNameOnlyFiles(rawFiles: string): string[] {
+  return rawFiles.split(/\r?\n/).map((file) => file.trim()).filter(Boolean);
+}
+
 function isFullCommitSha(value: string): boolean {
   return /^[0-9a-f]{40}$/i.test(value);
 }
@@ -359,23 +373,23 @@ function scanGsdTaggedCommits(
       maxBuffer: GIT_LOG_MAX_BUFFER,
     });
     const records = logOutput
-      .split("\x1e")
-      .map((record) => record.trim())
+      .split(LOG_RECORD_SEPARATOR)
       .filter(Boolean)
       .flatMap((record) => {
-        const sep = record.indexOf("\x1f");
-        if (sep === -1) return [];
-        const hash = record.slice(0, sep).trim();
-        const message = record.slice(sep + 1);
-        return [{ hash, message }];
+        const parts = record.split(LOG_FIELD_SEPARATOR);
+        if (parts.length < 3) return [];
+        const hash = parts[0].trim();
+        if (!hash) return [];
+        const files = parseNameOnlyFiles(parts.at(-1) ?? "");
+        const message = parts.slice(1, -1).join(LOG_FIELD_SEPARATOR);
+        return [{ message, files }];
       });
 
     const files = new Set<string>();
     let matched = false;
-    for (const { hash, message } of records) {
+    for (const { message, files: commitFiles } of records) {
       if (!commitMessageHasGsdTrailer(message)) continue;
 
-      const commitFiles = getChangedFilesForCommit(basePath, hash);
       if (!commitMatchesMilestone(basePath, message, milestoneId, commitFiles)) continue;
 
       matched = true;

package/src/resources/extensions/gsd/milestone-planning-persistence.ts

@@ -161,6 +161,14 @@ async function renderPlanArtifacts(
 ): Promise<string | { error: string }> {
   try {
     const renderResult = await renderRoadmapFromDb(basePath, params.milestoneId);
+    // renderRoadmapFromDb only skips for unplanned milestones (zero slices +
+    // empty vision); persistMilestonePlan always populates both via writePlanRows
+    // before this render, so the skipped branch is unreachable here. Fall back to
+    // resolving the projected path so a future invariant still surfaces a clear
+    // render failure rather than an undefined dereference.
+    if ("skipped" in renderResult) {
+      return { error: `render skipped: milestone ${params.milestoneId} has no planned slices` };
+    }
     return renderResult.roadmapPath;
   } catch (renderErr) {
     logWarning("tool", `plan_milestone — render failed (DB rows preserved for debugging): ${(renderErr as Error).message}`);

package/src/resources/extensions/gsd/milestone-validation-verdict.ts

@@ -7,7 +7,7 @@ import { join } from "node:path";
 import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
 import { loadFile } from "./files.js";
 import { getLatestAssessmentByScope, isDbAvailable } from "./gsd-db.js";
-import { gsdProjectionRoot } from "./paths.js";
+import { relMilestoneFile } from "./paths.js";
 import {
   extractVerdict,
   isValidMilestoneVerdict,
@@ -68,13 +68,11 @@ export async function resolveMilestoneValidationVerdict(
     if (projectVerdict) return projectVerdict;
   }
 
-  // Last resort: direct canonical projection path even when resolveDir helpers
-  // have not materialized the milestone directory yet.
-  const directPath = join(
-    gsdProjectionRoot(canonicalBase),
-    "milestones",
-    milestoneId,
-    `${milestoneId}-VALIDATION.md`,
-  );
+  // Last resort: layout-aware fallback path when resolveDir helpers
+  // haven't materialized the milestone directory yet. relMilestoneFile()
+  // builds the canonical NN-VALIDATION.md path for flat-phase and the
+  // legacy MID-VALIDATION.md path for projects that haven't migrated.
+  // See open-gsd/gsd-pi#876.
+  const directPath = join(canonicalBase, relMilestoneFile(canonicalBase, milestoneId, "VALIDATION"));
   return verdictFromValidationPath(directPath);
 }

package/src/resources/extensions/gsd/model-router.ts

@@ -312,6 +312,8 @@ export function scoreEligibleModels(
 
 /**
  * Return all models eligible for a given tier, sorted cheapest first.
+ * A runtime preferred model (the user's selected/session model) is returned
+ * first when it is available and satisfies the requested tier.
  * If routingConfig.tier_models[tier] is set and available, returns only that
  * model. Otherwise filters availableModelIds by tier from MODEL_CAPABILITY_TIER.
  */
@@ -319,6 +321,7 @@ export function getEligibleModels(
   tier: ComplexityTier,
   availableModelIds: string[],
   routingConfig: DynamicRoutingConfig,
+  preferredModelId?: string,
 ): string[] {
   // 1. Check explicit tier_models config
   const explicitModel = routingConfig.tier_models?.[tier];
@@ -332,13 +335,17 @@ export function getEligibleModels(
   }
 
   // 2. Auto-detect: filter by tier, sort cheapest first
-  return availableModelIds
+  const tierMatches = availableModelIds
     .filter(id => getModelTier(id) === tier)
     .sort((a, b) => {
       const costA = getModelCost(a);
       const costB = getModelCost(b);
       return costA - costB;
     });
+
+  const preferred = findPreferredModelForTier(tier, availableModelIds, preferredModelId);
+  if (!preferred) return tierMatches;
+  return [preferred, ...tierMatches.filter(id => id !== preferred)];
 }
 
 /**
@@ -398,6 +405,7 @@ export function resolveModelForComplexity(
   unitType?: string,
   taskMetadata?: TaskMetadata,
   capabilityOverrides?: Record<string, Partial<ModelCapabilities>>,
+  preferredModelId?: string,
 ): RoutingDecision {
   // If no phase config or routing disabled, pass through
   if (!phaseConfig || !routingConfig.enabled) {
@@ -453,6 +461,7 @@ export function resolveModelForComplexity(
       routingConfig,
       availableModelIds,
       routingConfig.cross_provider !== false,
+      preferredModelId,
     );
 
     return {
@@ -470,7 +479,7 @@ export function resolveModelForComplexity(
   }
 
   // STEP 1: Get all eligible models for the requested tier
-  const eligible = getEligibleModels(requestedTier, availableModelIds, routingConfig);
+  const eligible = getEligibleModels(requestedTier, availableModelIds, routingConfig, preferredModelId);
 
   if (eligible.length === 0) {
     // No suitable model found — use configured primary
@@ -484,6 +493,19 @@ export function resolveModelForComplexity(
     };
   }
 
+  const preferred = findPreferredModelForTier(requestedTier, availableModelIds, preferredModelId);
+  if (preferred && eligible.includes(preferred)) {
+    const fallbacks = buildFallbackChain(preferred, phaseConfig);
+    return {
+      modelId: preferred,
+      fallbacks,
+      tier: requestedTier,
+      wasDowngraded: !isModelAvailable(configuredPrimary, [preferred]),
+      reason: `preferred session model ${preferred} satisfies ${requestedTier} tier`,
+      selectionMethod: "tier-only",
+    };
+  }
+
   // STEP 2: Capability scoring (when enabled and multiple eligible models exist)
   if (routingConfig.capability_routing !== false && eligible.length > 1 && unitType) {
     const requirements = computeTaskRequirements(unitType, taskMetadata);
@@ -551,15 +573,15 @@ export function defaultRoutingConfig(): DynamicRoutingConfig {
 // ─── Tier-Based Model Resolution (for profile defaults) ─────────────────────
 
 /**
- * Fallback-only canonical model IDs per tier. Returned when the
+ * Fallback-only canonical model IDs per tier. Returned only when the
  * available-model list is empty (e.g., preferences are loaded before the
- * model registry is populated at bootstrap), or when a non-empty registry has
- * no model at the requested tier.
+ * model registry is populated at bootstrap).
  *
  * Precedence (resolveModelForTier):
  *   1. configured `tier_models[tier]` (via getEligibleModels) — exact/bare match
- *   2. cheapest available model whose tier matches `tier`
- *   3. CANONICAL_TIER_MODELS[tier] as last-resort fallback
+ *   2. preferred/session model when it is available and satisfies `tier`
+ *   3. cheapest available model whose tier matches `tier`
+ *   4. CANONICAL_TIER_MODELS[tier] when the registry is empty
  */
 const CANONICAL_TIER_MODELS: Record<ComplexityTier, string> = {
   light: "claude-haiku-4-5",
@@ -573,9 +595,10 @@ export function canonicalModelForTier(tier: ComplexityTier): string {
 
 /**
  * Single source of truth for tier-based model selection.
- * Returns the cheapest available model whose capability tier matches `tier`,
- * honoring `routingConfig.tier_models[tier]` when set. Returns undefined when
- * no available model matches the tier.
+ * Returns the preferred/session model when it satisfies `tier`, otherwise the
+ * cheapest available model whose capability tier matches `tier`, honoring
+ * `routingConfig.tier_models[tier]` when set. Returns undefined when no
+ * available model satisfies the tier.
  *
  * `crossProvider`: when false, restricts the search to models that share the
  * canonical (Anthropic) provider for the tier. When true, any provider is
@@ -586,8 +609,9 @@ function findModelForTier(
   routingConfig: DynamicRoutingConfig,
   availableModelIds: string[],
   crossProvider: boolean,
+  preferredModelId?: string,
 ): string | undefined {
-  const eligible = getEligibleModels(tier, availableModelIds, routingConfig);
+  const eligible = getEligibleModels(tier, availableModelIds, routingConfig, preferredModelId);
   if (eligible.length === 0) return undefined;
 
   if (crossProvider) {
@@ -600,6 +624,13 @@ function findModelForTier(
     const bare = bareModelId(id);
     return MODEL_CAPABILITY_TIER[bare] === tier && bare.startsWith("claude-");
   });
+
+  // Honor the preferred/session model only when it is itself a same-provider
+  // (Anthropic/Claude) model. A non-Anthropic session model must not bypass
+  // the cross_provider:false restriction.
+  const preferred = findPreferredModelForTier(tier, availableModelIds, preferredModelId);
+  if (preferred && sameProvider.includes(preferred)) return preferred;
+
   return sameProvider[0];
 }
 
@@ -610,9 +641,11 @@ function findModelForTier(
  *
  * Precedence:
  *   1. configured `tier_models[tier]`, if provided and available
- *   2. tier-matching model from any provider in `availableModelIds`
- *   3. canonical Anthropic ID as a fallback only when nothing else matches
- *      (or `availableModelIds` is empty, e.g., during early bootstrap)
+ *   2. preferred/session model when available and satisfying the tier
+ *   3. tier-matching model from any provider in `availableModelIds`
+ *   4. preferred/session model, then first available model, when the registry
+ *      is non-empty but has no tier match
+ *   5. canonical Anthropic ID only when `availableModelIds` is empty
  *
  * @param tier              The capability tier to resolve
  * @param availableModelIds List of available model IDs (REQUIRED for
@@ -620,6 +653,7 @@ function findModelForTier(
  *                          the model registry is genuinely unavailable)
  * @param routingConfig     Optional routing config, or legacy crossProvider boolean
  * @param crossProvider     Whether to consider models from other providers
+ * @param preferredModelId  Optional selected/session model ID to prefer
  */
 export function resolveModelForTier(
   tier: ComplexityTier,
@@ -631,12 +665,14 @@ export function resolveModelForTier(
   availableModelIds: string[],
   routingConfig?: DynamicRoutingConfig,
   crossProvider?: boolean,
+  preferredModelId?: string,
 ): string;
 export function resolveModelForTier(
   tier: ComplexityTier,
   availableModelIds: string[],
   routingConfigOrCrossProvider: DynamicRoutingConfig | boolean = defaultRoutingConfig(),
   crossProvider?: boolean,
+  preferredModelId?: string,
 ): string {
   const routingConfig = typeof routingConfigOrCrossProvider === "boolean"
     ? defaultRoutingConfig()
@@ -645,24 +681,68 @@ export function resolveModelForTier(
     ? routingConfigOrCrossProvider
     : crossProvider ?? routingConfig.cross_provider !== false;
 
-  // No available models known — return canonical fallback
+  // No available models known — prefer the session model when provided, else canonical
   if (availableModelIds.length === 0) {
+    if (preferredModelId) {
+      return normalizeResolvedTierModelId(preferredModelId, tier, routingConfig);
+    }
     incrementLegacyTelemetry("legacy.providerDefaultUsed");
     return canonicalModelForTier(tier);
   }
 
   // Cross-provider tier search
-  const resolved = findModelForTier(tier, routingConfig, availableModelIds, allowCrossProvider);
+  const resolved = findModelForTier(tier, routingConfig, availableModelIds, allowCrossProvider, preferredModelId);
   if (resolved) {
     return normalizeResolvedTierModelId(resolved, tier, routingConfig);
   }
 
-  incrementLegacyTelemetry("legacy.providerDefaultUsed");
-  return canonicalModelForTier(tier);
+  const providerLocalFallback = findAvailableModelId(preferredModelId, availableModelIds)
+    ?? availableModelIds[0]
+    ?? canonicalModelForTier(tier);
+  return normalizeResolvedTierModelId(providerLocalFallback, tier, routingConfig);
 }
 
 // ─── Internal ────────────────────────────────────────────────────────────────
 
+function modelProvider(modelId: string): string | undefined {
+  const slash = modelId.indexOf("/");
+  return slash > 0 ? modelId.slice(0, slash) : undefined;
+}
+
+function findAvailableModelId(
+  preferredModelId: string | undefined,
+  availableModelIds: string[],
+): string | undefined {
+  if (!preferredModelId) return undefined;
+  if (availableModelIds.includes(preferredModelId)) return preferredModelId;
+
+  const preferredBare = bareModelId(preferredModelId);
+  if (!preferredBare) return undefined;
+  const preferredProvider = modelProvider(preferredModelId)?.toLowerCase();
+  if (preferredProvider) {
+    const providerMatch = availableModelIds.find(id =>
+      modelProvider(id)?.toLowerCase() === preferredProvider && bareModelId(id) === preferredBare
+    );
+    if (providerMatch) return providerMatch;
+  }
+
+  return availableModelIds.find(id => bareModelId(id) === preferredBare);
+}
+
+function modelSatisfiesTier(modelId: string, tier: ComplexityTier): boolean {
+  return tierOrdinal(getModelTier(modelId)) >= tierOrdinal(tier);
+}
+
+function findPreferredModelForTier(
+  tier: ComplexityTier,
+  availableModelIds: string[],
+  preferredModelId: string | undefined,
+): string | undefined {
+  const preferred = findAvailableModelId(preferredModelId, availableModelIds);
+  if (!preferred) return undefined;
+  return modelSatisfiesTier(preferred, tier) ? preferred : undefined;
+}
+
 /**
  * Check whether a model ID is present in the available models list.
  * Handles bare IDs ("claude-opus-4-6") and provider-prefixed IDs ("anthropic/claude-opus-4-6").

package/src/resources/extensions/gsd/notification-store.ts

@@ -310,40 +310,29 @@ function _atomicWrite(basePath: string, content: string): void {
 /**
  * Acquire an exclusive lockfile for rewrite operations.
  * Uses O_CREAT|O_EXCL for atomic creation — if the file exists, another
- * process holds the lock. Retries briefly, then proceeds anyway (best-effort)
- * to avoid deadlocking the UI on a stale lock.
+ * process holds the lock. Clears stale locks, then proceeds anyway
+ * (best-effort) to avoid blocking the UI.
  */
 function _withLock<T>(basePath: string, fn: () => T): T {
   const lockPath = join(basePath, ".gsd", LOCKFILE);
   let fd: number | null = null;
-  const maxAttempts = 5;
-  const retryMs = 20;
 
-  for (let i = 0; i < maxAttempts; i++) {
-    try {
-      mkdirSync(join(basePath, ".gsd"), { recursive: true });
-      fd = openSync(lockPath, "wx");
-      break;
-    } catch (err: any) {
-      if (err?.code === "EEXIST") {
-        // Check if lock is stale (older than 5s)
-        try {
-          const stat = readFileSync(lockPath, "utf-8");
-          const lockTime = parseInt(stat, 10);
-          if (Date.now() - lockTime > 5000) {
-            try { unlinkSync(lockPath); } catch { /* race ok */ }
-            continue;
-          }
-        } catch { /* can't read lock, retry */ }
-
-        // Wait and retry
-        const start = Date.now();
-        while (Date.now() - start < retryMs) { /* spin */ }
-        continue;
-      }
-      // Other error — proceed without lock
-      break;
+  try {
+    mkdirSync(join(basePath, ".gsd"), { recursive: true });
+    fd = openSync(lockPath, "wx");
+  } catch (err: any) {
+    if (err?.code === "EEXIST") {
+      // Check if lock is stale (older than 5s)
+      try {
+        const stat = readFileSync(lockPath, "utf-8");
+        const lockTime = parseInt(stat, 10);
+        if (Date.now() - lockTime > 5000) {
+          try { unlinkSync(lockPath); } catch { /* race ok */ }
+          try { fd = openSync(lockPath, "wx"); } catch { /* race ok */ }
+        }
+      } catch { /* proceed without lock */ }
     }
+    // Any lock acquisition error leaves fd null; proceed without lock.
   }
 
   // Best-effort: mutation runs regardless of lock status (idempotent overwrites).

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

@@ -1,7 +1,9 @@
 // GSD Extension — Desktop Notification Helper
 // Cross-platform desktop notifications for auto-mode events.
 
-import { execFileSync } from "node:child_process";
+import childProcess from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { delimiter, resolve } from "node:path";
 import type { NotificationPreferences } from "./types.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { sendRemoteNotification as _sendRemoteNotification } from "../remote-questions/notify.js";
@@ -25,6 +27,8 @@ interface BellStream {
   write(chunk: string): unknown;
 }
 
+const executablePathCache = new Map<string, string | null>();
+
 /**
  * Send a native desktop notification. Non-blocking, non-fatal.
  * macOS: osascript, Linux: notify-send, Windows: skipped.
@@ -73,13 +77,26 @@ export function sendDesktopNotification(
     try {
       const command = buildDesktopNotificationCommand(process.platform, title, message, level);
       if (!command) return;
-      execFileSync(command.file, command.args, { timeout: 3000, stdio: "ignore" });
+      launchDesktopNotification(command);
     } catch {
       // Non-fatal — desktop notifications are best-effort
     }
   }).catch(() => {});
 }
 
+export function launchDesktopNotification(command: NotificationCommand): void {
+  try {
+    const child = childProcess.spawn(command.file, command.args, {
+      detached: true,
+      stdio: "ignore",
+    });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    // Non-fatal — desktop notifications are best-effort
+  }
+}
+
 export function shouldSendDesktopNotification(
   kind: NotificationKind,
   preferences: NotificationPreferences | undefined = loadEffectiveGSDPreferences()?.preferences.notifications,
@@ -194,11 +211,25 @@ function escapeAppleScript(s: string): string {
  * Non-fatal — returns null on any error.
  */
 function findExecutable(name: string): string | null {
-  try {
-    return execFileSync("which", [name], { timeout: 2000, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || null;
-  } catch {
-    return null;
+  if (executablePathCache.has(name)) return executablePathCache.get(name) ?? null;
+
+  let resolved: string | null = null;
+  const path = process.env.PATH;
+  if (path) {
+    for (const dir of path.split(delimiter)) {
+      const candidate = resolve(dir || ".", name);
+      try {
+        accessSync(candidate, constants.X_OK);
+        resolved = candidate;
+        break;
+      } catch {
+        // keep searching PATH
+      }
+    }
   }
+
+  executablePathCache.set(name, resolved);
+  return resolved;
 }
 
 function resolveBellStream(): BellStream | null {