gsd-pi 2.49.0 → 2.50.0-dev.d210a87

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

@@ -450,7 +450,15 @@ export async function runGSDDoctor(basePath, options) {
             }));
         }
         else {
-            slices = parseLegacyRoadmap(roadmapContent).slices;
+            const activeMilestoneId = state.activeMilestone?.id;
+            const activeSliceId = state.activeSlice?.id;
+            slices = parseLegacyRoadmap(roadmapContent).slices.map(s => ({
+                ...s,
+                // Legacy roadmaps only encode done vs not-done. For doctor's
+                // missing-directory checks, treat every undone slice except the
+                // current active slice as effectively pending/unstarted.
+                pending: !s.done && (milestoneId !== activeMilestoneId || s.id !== activeSliceId),
+            }));
         }
         // Wrap in Roadmap-compatible shape for detectCircularDependencies
         const roadmap = { slices };

package/dist/resources/extensions/gsd/extension-manifest.json

@@ -12,7 +12,7 @@
       "gsd_requirement_update", "gsd_milestone_generate_id"
     ],
     "commands": ["gsd", "kill", "worktree", "exit"],
-    "hooks": ["session_start"],
+    "hooks": ["session_start", "session_switch"],
     "shortcuts": ["Ctrl+Alt+G"]
   }
 }

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

@@ -222,6 +222,8 @@ function _parseSummaryImpl(content) {
             whatHappened: nativeResult.whatHappened,
             deviations: nativeResult.deviations,
             filesModified: nativeResult.filesModified,
+            followUps: extractSection(content, 'Follow-ups') ?? '',
+            knownLimitations: extractSection(content, 'Known Limitations') ?? '',
         };
     }
     const [fmLines, body] = splitFrontmatter(content);
@@ -276,7 +278,9 @@ function _parseSummaryImpl(content) {
             }
         }
     }
-    return { frontmatter, title, oneLiner, whatHappened, deviations, filesModified };
+    const followUps = extractSection(body, 'Follow-ups') ?? '';
+    const knownLimitations = extractSection(body, 'Known Limitations') ?? '';
+    return { frontmatter, title, oneLiner, whatHappened, deviations, filesModified, followUps, knownLimitations };
 }
 // ─── Continue Parser ───────────────────────────────────────────────────────
 export function parseContinue(content) {

package/dist/resources/extensions/gsd/git-service.js

@@ -13,7 +13,8 @@ import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { detectWorktreeName, SLICE_BRANCH_RE, } from "./worktree.js";
+import { detectWorktreeName, } from "./worktree.js";
+import { SLICE_BRANCH_RE, QUICK_BRANCH_RE, WORKFLOW_BRANCH_RE } from "./branch-patterns.js";
 import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeBranchExists, nativeHasChanges, nativeAddAllWithExclusions, nativeHasStagedChanges, nativeCommit, nativeRmCached, nativeUpdateRef, } from "./native-git-bridge.js";
 import { GSDError, GSD_MERGE_CONFLICT, GSD_GIT_ERROR } from "./errors.js";
 import { getErrorMessage } from "./error-utils.js";
@@ -133,8 +134,8 @@ export function readIntegrationBranch(basePath, milestoneId) {
  *
  * The file is committed immediately so the metadata is persisted in git.
  */
-/** Regex matching GSD quick-task branches: gsd/quick/<num>-<slug> */
-export const QUICK_BRANCH_RE = /^gsd\/quick\//;
+/** Re-export for backward compatibility — canonical definitions in branch-patterns.ts */
+export { QUICK_BRANCH_RE, WORKFLOW_BRANCH_RE } from "./branch-patterns.js";
 export function writeIntegrationBranch(basePath, milestoneId, branch) {
     // Don't record slice branches as the integration target
     if (SLICE_BRANCH_RE.test(branch))
@@ -144,6 +145,11 @@ export function writeIntegrationBranch(basePath, milestoneId, branch) {
     // target causes milestone merges to land on the wrong branch (#1293).
     if (QUICK_BRANCH_RE.test(branch))
         return;
+    // Don't record workflow-template branches (hotfix, bugfix, spike, etc.) —
+    // same root cause as quick-task branches (#2498). All templates create
+    // gsd/<templateId>/<slug> branches that are ephemeral.
+    if (WORKFLOW_BRANCH_RE.test(branch))
+        return;
     // Validate
     if (!VALID_BRANCH_NAME.test(branch))
         return;
@@ -299,10 +305,6 @@ export class GitServiceImpl {
     setMilestoneId(milestoneId) {
         this._milestoneId = milestoneId;
     }
-    /** Convenience wrapper: run git in this repo's basePath. */
-    git(args, options = {}) {
-        return runGit(this.basePath, args, options);
-    }
     /**
      * Smart staging: `git add -A` excluding GSD runtime paths via pathspec.
      * Falls back to plain `git add -A` if the exclusion pathspec fails.
@@ -442,9 +444,6 @@ export class GitServiceImpl {
     getCurrentBranch() {
         return nativeGetCurrentBranch(this.basePath);
     }
-    /** True if currently on a GSD slice branch. */
-    // ─── Branch Lifecycle ──────────────────────────────────────────────────
-    // ─── S05 Features ─────────────────────────────────────────────────────
     /**
      * Create a snapshot ref for the given label (typically a slice branch name).
      * Gated on prefs.snapshots === true. Ref path: refs/gsd/snapshots/<label>/<timestamp>

package/dist/resources/extensions/gsd/gsd-db.js

@@ -109,7 +109,7 @@ function openRawDb(path) {
     const Database = providerModule;
     return new Database(path);
 }
-const SCHEMA_VERSION = 11;
+const SCHEMA_VERSION = 12;
 function initSchema(db, fileBacked) {
     if (fileBacked)
         db.exec("PRAGMA journal_mode=WAL");
@@ -302,6 +302,22 @@ function initSchema(db, fileBacked) {
         created_at TEXT NOT NULL DEFAULT '',
         FOREIGN KEY (milestone_id) REFERENCES milestones(id)
       )
+    `);
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS quality_gates (
+        milestone_id TEXT NOT NULL,
+        slice_id TEXT NOT NULL,
+        gate_id TEXT NOT NULL,
+        scope TEXT NOT NULL DEFAULT 'slice',
+        task_id TEXT NOT NULL DEFAULT '',
+        status TEXT NOT NULL DEFAULT 'pending',
+        verdict TEXT NOT NULL DEFAULT '',
+        rationale TEXT NOT NULL DEFAULT '',
+        findings TEXT NOT NULL DEFAULT '',
+        evaluated_at TEXT DEFAULT NULL,
+        PRIMARY KEY (milestone_id, slice_id, gate_id, task_id),
+        FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id)
+      )
     `);
         db.exec("CREATE INDEX IF NOT EXISTS idx_memories_active ON memories(superseded_by)");
         db.exec("CREATE INDEX IF NOT EXISTS idx_replan_history_milestone ON replan_history(milestone_id, created_at)");
@@ -561,6 +577,28 @@ function migrateSchema(db) {
                 ":applied_at": new Date().toISOString(),
             });
         }
+        if (currentVersion < 12) {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS quality_gates (
+          milestone_id TEXT NOT NULL,
+          slice_id TEXT NOT NULL,
+          gate_id TEXT NOT NULL,
+          scope TEXT NOT NULL DEFAULT 'slice',
+          task_id TEXT DEFAULT NULL,
+          status TEXT NOT NULL DEFAULT 'pending',
+          verdict TEXT NOT NULL DEFAULT '',
+          rationale TEXT NOT NULL DEFAULT '',
+          findings TEXT NOT NULL DEFAULT '',
+          evaluated_at TEXT DEFAULT NULL,
+          PRIMARY KEY (milestone_id, slice_id, gate_id, COALESCE(task_id, '')),
+          FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id)
+        )
+      `);
+            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
+                ":version": 12,
+                ":applied_at": new Date().toISOString(),
+            });
+        }
         db.exec("COMMIT");
     }
     catch (err) {
@@ -1396,3 +1434,88 @@ export function getAssessment(path) {
     const row = currentDb.prepare(`SELECT * FROM assessments WHERE path = :path`).get({ ":path": path });
     return row ?? null;
 }
+// ─── Quality Gates ───────────────────────────────────────────────────────
+function rowToGate(row) {
+    return {
+        milestone_id: row["milestone_id"],
+        slice_id: row["slice_id"],
+        gate_id: row["gate_id"],
+        scope: row["scope"],
+        task_id: row["task_id"] ?? "",
+        status: row["status"],
+        verdict: row["verdict"] || "",
+        rationale: row["rationale"] || "",
+        findings: row["findings"] || "",
+        evaluated_at: row["evaluated_at"] ?? null,
+    };
+}
+export function insertGateRow(g) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    currentDb.prepare(`INSERT OR IGNORE INTO quality_gates (milestone_id, slice_id, gate_id, scope, task_id, status)
+     VALUES (:mid, :sid, :gid, :scope, :tid, :status)`).run({
+        ":mid": g.milestoneId,
+        ":sid": g.sliceId,
+        ":gid": g.gateId,
+        ":scope": g.scope,
+        ":tid": g.taskId ?? "",
+        ":status": g.status ?? "pending",
+    });
+}
+export function saveGateResult(g) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    currentDb.prepare(`UPDATE quality_gates
+     SET status = 'complete', verdict = :verdict, rationale = :rationale,
+         findings = :findings, evaluated_at = :evaluated_at
+     WHERE milestone_id = :mid AND slice_id = :sid AND gate_id = :gid
+       AND task_id = :tid`).run({
+        ":mid": g.milestoneId,
+        ":sid": g.sliceId,
+        ":gid": g.gateId,
+        ":tid": g.taskId ?? "",
+        ":verdict": g.verdict,
+        ":rationale": g.rationale,
+        ":findings": g.findings,
+        ":evaluated_at": new Date().toISOString(),
+    });
+}
+export function getPendingGates(milestoneId, sliceId, scope) {
+    if (!currentDb)
+        return [];
+    const sql = scope
+        ? `SELECT * FROM quality_gates WHERE milestone_id = :mid AND slice_id = :sid AND scope = :scope AND status = 'pending'`
+        : `SELECT * FROM quality_gates WHERE milestone_id = :mid AND slice_id = :sid AND status = 'pending'`;
+    const params = { ":mid": milestoneId, ":sid": sliceId };
+    if (scope)
+        params[":scope"] = scope;
+    return currentDb.prepare(sql).all(params).map(rowToGate);
+}
+export function getGateResults(milestoneId, sliceId, scope) {
+    if (!currentDb)
+        return [];
+    const sql = scope
+        ? `SELECT * FROM quality_gates WHERE milestone_id = :mid AND slice_id = :sid AND scope = :scope`
+        : `SELECT * FROM quality_gates WHERE milestone_id = :mid AND slice_id = :sid`;
+    const params = { ":mid": milestoneId, ":sid": sliceId };
+    if (scope)
+        params[":scope"] = scope;
+    return currentDb.prepare(sql).all(params).map(rowToGate);
+}
+export function markAllGatesOmitted(milestoneId, sliceId) {
+    if (!currentDb)
+        return;
+    currentDb.prepare(`UPDATE quality_gates SET status = 'omitted', verdict = 'omitted', evaluated_at = :now
+     WHERE milestone_id = :mid AND slice_id = :sid AND status = 'pending'`).run({
+        ":mid": milestoneId,
+        ":sid": sliceId,
+        ":now": new Date().toISOString(),
+    });
+}
+export function getPendingSliceGateCount(milestoneId, sliceId) {
+    if (!currentDb)
+        return 0;
+    const row = currentDb.prepare(`SELECT COUNT(*) as cnt FROM quality_gates
+     WHERE milestone_id = :mid AND slice_id = :sid AND scope = 'slice' AND status = 'pending'`).get({ ":mid": milestoneId, ":sid": sliceId });
+    return row ? row["cnt"] : 0;
+}

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

@@ -186,11 +186,20 @@ export async function buildExistingMilestonesContext(basePath, milestoneIds, sta
             sections.push(`### Decisions Register\nSource: \`${relGsdRootFile("DECISIONS")}\`\n\n${decisionsContent.trim()}`);
         }
     }
-    // For each milestone, include context and status
+    // For each milestone, include context and status.
+    // Completed milestones get a compact summary line only — loading their full
+    // CONTEXT.md + SUMMARY.md files is expensive and triggers 429 rate limits on
+    // projects with many completed milestones (#2379).
     for (const mid of milestoneIds) {
         const registryEntry = state.registry.find(m => m.id === mid);
         const status = registryEntry?.status ?? "unknown";
         const title = registryEntry?.title ?? mid;
+        // Completed milestones: emit a one-liner — the LLM only needs to know
+        // they exist for dedup/dependency purposes, not their full content.
+        if (status === "complete") {
+            sections.push(`### ${mid}: ${title}\n**Status:** complete`);
+            continue;
+        }
         const parts = [];
         parts.push(`### ${mid}: ${title}\n**Status:** ${status}`);
         // Include context file — this is the primary content for understanding scope
@@ -211,16 +220,6 @@ export async function buildExistingMilestonesContext(basePath, milestoneIds, sta
                 }
             }
         }
-        // For completed milestones, include the summary if it exists
-        if (status === "complete") {
-            const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (summaryFile) {
-                const content = await loadFile(summaryFile);
-                if (content) {
-                    parts.push(`\n**Summary:**\n${content.trim()}`);
-                }
-            }
-        }
         // For active/pending/parked milestones, include the roadmap if it exists
         // (shows what's planned but not yet built)
         if (status === "active" || status === "pending" || status === "parked") {

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

@@ -353,7 +353,10 @@ async function buildDiscussSlicePrompt(mid, sid, sTitle, base, options) {
         }
     }
     // Completed slice summaries — what was already built that this slice builds on
+    // Ensure DB is open so getMilestoneSlices returns real data (#2560).
     {
+        const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
+        await ensureDbOpen();
         let normSlices = [];
         if (isDbAvailable()) {
             normSlices = getMilestoneSlices(mid).map(s => ({ id: s.id, done: s.status === "complete" }));
@@ -476,6 +479,13 @@ export async function showDiscuss(ctx, pi, basePath) {
         }
         return;
     }
+    // Ensure DB is open before querying slices (#2560).
+    // showDiscuss() is a command handler — unlike tool handlers, it has no
+    // automatic ensureDbOpen() call. Without this, isDbAvailable() returns
+    // false on cold-start sessions and normSlices falls to [] → false
+    // "All slices complete" exit.
+    const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
+    await ensureDbOpen();
     // Guard: no roadmap yet (unless DB has slices)
     const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
     const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null;

package/dist/resources/extensions/gsd/init-wizard.js

@@ -12,6 +12,7 @@ import { nativeInit } from "./native-git-bridge.js";
 import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
 import { gsdRoot } from "./paths.js";
 import { assertSafeDirectory } from "./validate-directory.js";
+import { runSkillInstallStep } from "./skill-catalog.js";
 // ─── Defaults ───────────────────────────────────────────────────────────────────
 const DEFAULT_PREFS = {
     mode: "solo",
@@ -176,7 +177,14 @@ export async function showProjectInit(ctx, pi, basePath, detection) {
     if (advancedChoice === "customize") {
         await customizeAdvancedPrefs(ctx, prefs);
     }
-    // ── Step 8: Bootstrap .gsd/ ────────────────────────────────────────────────
+    // ── Step 8: Skill Installation ─────────────────────────────────────────────
+    try {
+        await runSkillInstallStep(ctx, signals);
+    }
+    catch {
+        // Non-fatal — skill installation failure should never block project init
+    }
+    // ── Step 9: Bootstrap .gsd/ ────────────────────────────────────────────────
     bootstrapGsdDirectory(basePath, prefs, signals);
     // Ensure .gitignore
     ensureGitignore(basePath);

package/dist/resources/extensions/gsd/markdown-renderer.js

@@ -10,7 +10,7 @@
 import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, relative } from "node:path";
 import { createRequire } from "node:module";
-import { getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getTask, getSlice, getArtifact, insertArtifact, } from "./gsd-db.js";
+import { getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getTask, getSlice, getArtifact, insertArtifact, getGateResults, } from "./gsd-db.js";
 import { resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveTasksDir, gsdRoot, buildTaskFileName, buildSliceFileName, } from "./paths.js";
 import { saveFile, clearParseCache } from "./files.js";
 import { invalidateStateCache } from "./state.js";
@@ -127,7 +127,7 @@ function renderRoadmapMarkdown(milestone, slices) {
     }
     return `${lines.join("\n").trimEnd()}\n`;
 }
-function renderTaskPlanMarkdown(task) {
+function renderTaskPlanMarkdown(task, taskGates = []) {
     const estimatedSteps = Math.max(1, task.description.trim().split(/\n+/).filter(Boolean).length || 1);
     const estimatedFiles = task.files.length > 0
         ? task.files.length
@@ -186,9 +186,20 @@ function renderTaskPlanMarkdown(task) {
         lines.push(task.observability_impact.trim());
         lines.push("");
     }
+    // ── Quality Gate Sections (Q5/Q6/Q7) ──────────────────────────────────
+    const gateLabels = { Q5: "Failure Modes", Q6: "Load Profile", Q7: "Negative Tests" };
+    for (const [gid, label] of Object.entries(gateLabels)) {
+        const gate = taskGates.find(g => g.gate_id === gid && g.status === "complete");
+        if (gate && gate.verdict !== "omitted") {
+            lines.push(`## ${label}`);
+            lines.push("");
+            lines.push(gate.findings.trim() || `- **Verdict:** ${gate.verdict}\n- **Rationale:** ${gate.rationale}`);
+            lines.push("");
+        }
+    }
     return `${lines.join("\n").trimEnd()}\n`;
 }
-function renderSlicePlanMarkdown(slice, tasks) {
+function renderSlicePlanMarkdown(slice, tasks, gates = []) {
     const lines = [];
     lines.push(`# ${slice.id}: ${slice.title || slice.id}`);
     lines.push("");
@@ -206,6 +217,21 @@ function renderSlicePlanMarkdown(slice, tasks) {
         lines.push("- Complete the planned slice outcomes.");
     }
     lines.push("");
+    // ── Quality Gate Sections (Q3/Q4) ────────────────────────────────────
+    const q3 = gates.find(g => g.gate_id === "Q3" && g.status === "complete");
+    if (q3 && q3.verdict !== "omitted") {
+        lines.push("## Threat Surface");
+        lines.push("");
+        lines.push(q3.findings.trim() || `- **Verdict:** ${q3.verdict}\n- **Rationale:** ${q3.rationale}`);
+        lines.push("");
+    }
+    const q4 = gates.find(g => g.gate_id === "Q4" && g.status === "complete");
+    if (q4 && q4.verdict !== "omitted") {
+        lines.push("## Requirement Impact");
+        lines.push("");
+        lines.push(q4.findings.trim() || `- **Verdict:** ${q4.verdict}\n- **Rationale:** ${q4.rationale}`);
+        lines.push("");
+    }
     if (slice.proof_level.trim()) {
         lines.push("## Proof Level");
         lines.push("");
@@ -275,7 +301,8 @@ export async function renderPlanFromDb(basePath, milestoneId, sliceId) {
     const absPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN")
         ?? join(slicePath, `${sliceId}-PLAN.md`);
     const artifactPath = toArtifactPath(absPath, basePath);
-    const content = renderSlicePlanMarkdown(slice, tasks);
+    const sliceGates = getGateResults(milestoneId, sliceId, "slice");
+    const content = renderSlicePlanMarkdown(slice, tasks, sliceGates);
     await writeAndStore(absPath, artifactPath, content, {
         artifact_type: "PLAN",
         milestone_id: milestoneId,
@@ -298,7 +325,8 @@ export async function renderTaskPlanFromDb(basePath, milestoneId, sliceId, taskI
     mkdirSync(tasksDir, { recursive: true });
     const absPath = join(tasksDir, buildTaskFileName(taskId, "PLAN"));
     const artifactPath = toArtifactPath(absPath, basePath);
-    const content = task.full_plan_md.trim() ? task.full_plan_md : renderTaskPlanMarkdown(task);
+    const taskGates = getGateResults(milestoneId, sliceId, "task").filter(g => g.task_id === taskId);
+    const content = task.full_plan_md.trim() ? task.full_plan_md : renderTaskPlanMarkdown(task, taskGates);
     await writeAndStore(absPath, artifactPath, content, {
         artifact_type: "PLAN",
         milestone_id: milestoneId,

package/dist/resources/extensions/gsd/model-router.js

@@ -68,6 +68,20 @@ export function resolveModelForComplexity(classification, phaseConfig, routingCo
     const configuredPrimary = phaseConfig.primary;
     const configuredTier = getModelTier(configuredPrimary);
     const requestedTier = classification.tier;
+    // If the configured model is unknown (not in MODEL_CAPABILITY_TIER),
+    // honor the user's explicit choice — don't downgrade based on a guess.
+    // Unknown models default to "heavy" in getModelTier, which makes every
+    // standard/light unit get downgraded to tier_models, silently ignoring
+    // the user's configuration. (#2192)
+    if (!isKnownModel(configuredPrimary)) {
+        return {
+            modelId: configuredPrimary,
+            fallbacks: phaseConfig.fallbacks,
+            tier: requestedTier,
+            wasDowngraded: false,
+            reason: `configured model "${configuredPrimary}" is not in the known tier map — honoring explicit config`,
+        };
+    }
     // Downgrade-only: if requested tier >= configured tier, no change
     if (tierOrdinal(requestedTier) >= tierOrdinal(configuredTier)) {
         return {
@@ -141,6 +155,17 @@ function getModelTier(modelId) {
     // Unknown models are assumed heavy (safest assumption)
     return "heavy";
 }
+/** Check if a model ID has a known capability tier mapping. (#2192) */
+function isKnownModel(modelId) {
+    const bareId = modelId.includes("/") ? modelId.split("/").pop() : modelId;
+    if (MODEL_CAPABILITY_TIER[bareId])
+        return true;
+    for (const knownId of Object.keys(MODEL_CAPABILITY_TIER)) {
+        if (bareId.includes(knownId) || knownId.includes(bareId))
+            return true;
+    }
+    return false;
+}
 function findModelForTier(tier, config, availableModelIds, crossProvider) {
     // 1. Check explicit tier_models config
     const explicitModel = config.tier_models?.[tier];

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

@@ -49,6 +49,17 @@ export function buildDesktopNotificationCommand(platform, title, message, level
     const normalizedTitle = normalizeNotificationText(title);
     const normalizedMessage = normalizeNotificationText(message);
     if (platform === "darwin") {
+        // Prefer terminal-notifier: registers as its own Notification Center app,
+        // so it gets a proper permission entry in System Settings → Notifications.
+        // osascript notifications are silently swallowed when the calling terminal
+        // (Ghostty, iTerm2, etc.) lacks notification permissions — exits 0, no error.
+        // See: https://github.com/gsd-build/gsd-2/issues/2632
+        const tnPath = findExecutable("terminal-notifier");
+        if (tnPath) {
+            const sound = level === "error" ? "Basso" : "Glass";
+            return { file: tnPath, args: ["-title", normalizedTitle, "-message", normalizedMessage, "-sound", sound] };
+        }
+        // Fallback: osascript (works if terminal app has notification permissions)
         const sound = level === "error" ? 'sound name "Basso"' : 'sound name "Glass"';
         const script = `display notification "${escapeAppleScript(normalizedMessage)}" with title "${escapeAppleScript(normalizedTitle)}" ${sound}`;
         return { file: "osascript", args: ["-e", script] };
@@ -65,3 +76,15 @@ function normalizeNotificationText(s) {
 function escapeAppleScript(s) {
     return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
+/**
+ * Locate an executable on PATH. Returns absolute path or null.
+ * Non-fatal — returns null on any error.
+ */
+function findExecutable(name) {
+    try {
+        return execFileSync("which", [name], { timeout: 2000, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || null;
+    }
+    catch {
+        return null;
+    }
+}