gsd-pi 2.50.0 → 2.51.0-dev.7d435fe

package/dist/resources/extensions/gsd/tools/replan-slice.js

@@ -46,46 +46,54 @@ export async function handleReplanSlice(rawParams, basePath) {
     catch (err) {
         return { error: `validation failed: ${err.message}` };
     }
-    // ── Verify parent slice exists and is not closed ─────────────────
-    const parentSlice = getSlice(params.milestoneId, params.sliceId);
-    if (!parentSlice) {
-        return { error: `missing parent slice: ${params.milestoneId}/${params.sliceId}` };
-    }
-    if (parentSlice.status === "complete" || parentSlice.status === "done") {
-        return { error: `cannot replan a closed slice: ${params.sliceId} (status: ${parentSlice.status})` };
-    }
-    // ── Verify blocker task exists and is complete ────────────────────
-    const blockerTask = getTask(params.milestoneId, params.sliceId, params.blockerTaskId);
-    if (!blockerTask) {
-        return { error: `blockerTaskId not found: ${params.milestoneId}/${params.sliceId}/${params.blockerTaskId}` };
-    }
-    if (blockerTask.status !== "complete" && blockerTask.status !== "done") {
-        return { error: `blockerTaskId ${params.blockerTaskId} is not complete (status: ${blockerTask.status}) — the blocker task must be finished before a replan is triggered` };
-    }
-    // ── Structural enforcement ────────────────────────────────────────
-    const existingTasks = getSliceTasks(params.milestoneId, params.sliceId);
-    const completedTaskIds = new Set();
-    for (const task of existingTasks) {
-        if (task.status === "complete" || task.status === "done") {
-            completedTaskIds.add(task.id);
-        }
-    }
-    // Reject updates to completed tasks
-    for (const updatedTask of params.updatedTasks) {
-        if (completedTaskIds.has(updatedTask.taskId)) {
-            return { error: `cannot modify completed task ${updatedTask.taskId}` };
-        }
-    }
-    // Reject removal of completed tasks
-    for (const removedId of params.removedTaskIds) {
-        if (completedTaskIds.has(removedId)) {
-            return { error: `cannot remove completed task ${removedId}` };
-        }
-    }
-    // ── Transaction: DB mutations ─────────────────────────────────────
-    const existingTaskIds = new Set(existingTasks.map((t) => t.id));
+    // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
+    // Guards must be inside the transaction so the state they check cannot
+    // change between the read and the write (#2723).
+    let guardError = null;
+    let existingTaskIds = new Set();
     try {
         transaction(() => {
+            // Verify parent slice exists and is not closed
+            const parentSlice = getSlice(params.milestoneId, params.sliceId);
+            if (!parentSlice) {
+                guardError = `missing parent slice: ${params.milestoneId}/${params.sliceId}`;
+                return;
+            }
+            if (parentSlice.status === "complete" || parentSlice.status === "done") {
+                guardError = `cannot replan a closed slice: ${params.sliceId} (status: ${parentSlice.status})`;
+                return;
+            }
+            // Verify blocker task exists and is complete
+            const blockerTask = getTask(params.milestoneId, params.sliceId, params.blockerTaskId);
+            if (!blockerTask) {
+                guardError = `blockerTaskId not found: ${params.milestoneId}/${params.sliceId}/${params.blockerTaskId}`;
+                return;
+            }
+            if (blockerTask.status !== "complete" && blockerTask.status !== "done") {
+                guardError = `blockerTaskId ${params.blockerTaskId} is not complete (status: ${blockerTask.status}) — the blocker task must be finished before a replan is triggered`;
+                return;
+            }
+            // Structural enforcement — reject modifications/removal of completed tasks
+            const existingTasks = getSliceTasks(params.milestoneId, params.sliceId);
+            const completedTaskIds = new Set();
+            for (const task of existingTasks) {
+                if (task.status === "complete" || task.status === "done") {
+                    completedTaskIds.add(task.id);
+                }
+            }
+            for (const updatedTask of params.updatedTasks) {
+                if (completedTaskIds.has(updatedTask.taskId)) {
+                    guardError = `cannot modify completed task ${updatedTask.taskId}`;
+                    return;
+                }
+            }
+            for (const removedId of params.removedTaskIds) {
+                if (completedTaskIds.has(removedId)) {
+                    guardError = `cannot remove completed task ${removedId}`;
+                    return;
+                }
+            }
+            existingTaskIds = new Set(existingTasks.map((t) => t.id));
             // Record replan history
             insertReplanHistory({
                 milestoneId: params.milestoneId,
@@ -138,6 +146,9 @@ export async function handleReplanSlice(rawParams, basePath) {
     catch (err) {
         return { error: `db write failed: ${err.message}` };
     }
+    if (guardError) {
+        return { error: guardError };
+    }
     // ── Render artifacts ──────────────────────────────────────────────
     try {
         const renderResult = await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);

package/dist/resources/extensions/gsd/tools/validate-milestone.js

@@ -5,7 +5,7 @@
  * renders VALIDATION.md to disk, and invalidates caches.
  */
 import { join } from "node:path";
-import { transaction, _getAdapter, } from "../gsd-db.js";
+import { transaction, insertAssessment, deleteAssessmentByScope, } from "../gsd-db.js";
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
@@ -45,7 +45,7 @@ export async function handleValidateMilestone(params, basePath) {
     if (!isValidMilestoneVerdict(params.verdict)) {
         return { error: `verdict must be one of: ${VALIDATION_VERDICTS.join(", ")}` };
     }
-    // ── Filesystem render ──────────────────────────────────────────────────
+    // ── Resolve paths and render markdown ────────────────────────────────
     const validationMd = renderValidationMarkdown(params);
     let validationPath;
     const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
@@ -57,26 +57,33 @@ export async function handleValidateMilestone(params, basePath) {
         const manualDir = join(gsdDir, "milestones", params.milestoneId);
         validationPath = join(manualDir, `${params.milestoneId}-VALIDATION.md`);
     }
+    // ── DB write first — matches complete-task/complete-slice pattern ───
+    // Write DB before disk so a crash between the two leaves a recoverable
+    // state: the DB row exists but the file is missing, which projection
+    // rendering can regenerate. The inverse (file exists, no DB row) is
+    // harder to detect and recover from (#2725).
+    const validatedAt = new Date().toISOString();
+    transaction(() => {
+        insertAssessment({
+            path: validationPath,
+            milestoneId: params.milestoneId,
+            sliceId: null,
+            taskId: null,
+            status: params.verdict,
+            scope: 'milestone-validation',
+            fullContent: validationMd,
+        });
+    });
+    // ── Filesystem render (outside transaction) ────────────────────────────
+    // If disk render fails, roll back the DB row so state stays consistent.
     try {
         await saveFile(validationPath, validationMd);
     }
     catch (renderErr) {
-        process.stderr.write(`gsd-db: validate_milestone — disk render failed: ${renderErr.message}\n`);
+        process.stderr.write(`gsd-db: validate_milestone — disk render failed, rolling back DB row: ${renderErr.message}\n`);
+        deleteAssessmentByScope(params.milestoneId, 'milestone-validation');
         return { error: `disk render failed: ${renderErr.message}` };
     }
-    // ── DB write — store in assessments table ──────────────────────────────
-    const validatedAt = new Date().toISOString();
-    transaction(() => {
-        const adapter = _getAdapter();
-        adapter.prepare(`INSERT OR REPLACE INTO assessments (path, milestone_id, slice_id, task_id, status, scope, full_content, created_at)
-       VALUES (:path, :mid, NULL, NULL, :verdict, 'milestone-validation', :content, :created_at)`).run({
-            ":path": validationPath,
-            ":mid": params.milestoneId,
-            ":verdict": params.verdict,
-            ":content": validationMd,
-            ":created_at": validatedAt,
-        });
-    });
     invalidateStateCache();
     clearPathCache();
     clearParseCache();

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

@@ -5,6 +5,7 @@
 import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { nativeRevertCommit, nativeRevertAbort } from "./native-git-bridge.js";
+import { parseUnitId } from "./unit-id.js";
 import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { gsdRoot, resolveTasksDir, resolveSlicePath, resolveTaskFile, buildTaskFileName, buildSliceFileName } from "./paths.js";
@@ -52,11 +53,11 @@ export async function handleUndo(args, ctx, _pi, basePath) {
         return;
     }
     // 1. Delete summary artifact
-    const parts = unitId.split("/");
+    const { milestone, slice, task } = parseUnitId(unitId);
     let summaryRemoved = false;
-    if (parts.length === 3) {
+    if (task !== undefined && slice !== undefined) {
         // Task-level: M001/S01/T01
-        const [mid, sid, tid] = parts;
+        const [mid, sid, tid] = [milestone, slice, task];
         const tasksDir = resolveTasksDir(basePath, mid, sid);
         if (tasksDir) {
             const summaryFile = join(tasksDir, buildTaskFileName(tid, "SUMMARY"));
@@ -66,9 +67,9 @@ export async function handleUndo(args, ctx, _pi, basePath) {
             }
         }
     }
-    else if (parts.length === 2) {
+    else if (slice !== undefined) {
         // Slice-level: M001/S01
-        const [mid, sid] = parts;
+        const [mid, sid] = [milestone, slice];
         const slicePath = resolveSlicePath(basePath, mid, sid);
         if (slicePath) {
             for (const suffix of ["SUMMARY", "COMPLETE"]) {
@@ -82,8 +83,8 @@ export async function handleUndo(args, ctx, _pi, basePath) {
     }
     // 2. Uncheck task in PLAN if execute-task
     let planUpdated = false;
-    if (unitType === "execute-task" && parts.length === 3) {
-        const [mid, sid, tid] = parts;
+    if (unitType === "execute-task" && task !== undefined && slice !== undefined) {
+        const [mid, sid, tid] = [milestone, slice, task];
         planUpdated = uncheckTaskInPlan(basePath, mid, sid, tid);
     }
     // 3. Try to revert git commits from activity log

package/dist/resources/extensions/gsd/unit-runtime.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlink
 import { join } from "node:path";
 import { gsdRoot, relSliceFile, relTaskFile, resolveSliceFile, resolveTaskFile, } from "./paths.js";
 import { loadFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
+import { parseUnitId } from "./unit-id.js";
 function runtimeDir(basePath) {
     return join(gsdRoot(basePath), "runtime", "units");
 }
@@ -75,7 +76,7 @@ export function listUnitRuntimeRecords(basePath) {
     return results;
 }
 export async function inspectExecuteTaskDurability(basePath, unitId) {
-    const [mid, sid, tid] = unitId.split("/");
+    const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
     if (!mid || !sid || !tid)
         return null;
     const planAbs = resolveSliceFile(basePath, mid, sid, "PLAN");

package/dist/resources/extensions/gsd/verification-gate.js

@@ -6,6 +6,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join, basename } from "node:path";
 import { DEFAULT_COMMAND_TIMEOUT_MS } from "./constants.js";
+import { rewriteCommandWithRtk } from "../shared/rtk.js";
 /** Maximum bytes of stdout/stderr to retain per command (10 KB). */
 const MAX_OUTPUT_BYTES = 10 * 1024;
 /** Truncate a string to maxBytes, appending a marker if truncated. */
@@ -210,10 +211,11 @@ export function runVerificationGate(options) {
     const checks = [];
     for (const command of commands) {
         const start = Date.now();
+        const rewrittenCommand = rewriteCommandWithRtk(command);
         // Pass the command string as an argument to the shell explicitly
         // to avoid Node.js DEP0190 (spawnSync with shell: true and no args).
         const shellBin = process.platform === "win32" ? "cmd" : "sh";
-        const shellArgs = process.platform === "win32" ? ["/c", command] : ["-c", command];
+        const shellArgs = process.platform === "win32" ? ["/c", rewrittenCommand] : ["-c", rewrittenCommand];
         const result = spawnSync(shellBin, shellArgs, {
             cwd: options.cwd,
             stdio: "pipe",

package/dist/resources/extensions/gsd/workflow-logger.js

@@ -158,7 +158,6 @@ export function readAuditLog(basePath) {
  */
 export function _resetLogs() {
     _buffer = [];
-    _auditBasePath = null;
 }
 // ─── Internal ───────────────────────────────────────────────────────────
 function _push(severity, component, message, context) {

package/dist/resources/extensions/remote-questions/config.js

@@ -43,7 +43,7 @@ function hydrateRemoteTokensFromAuth() {
         for (const [providerId, envVar] of needed) {
             try {
                 const creds = auth.getCredentialsForProvider(providerId);
-                const apiKeyCred = creds.find((c) => c.type === "api_key");
+                const apiKeyCred = creds.find((c) => c.type === "api_key" && !!c.key);
                 if (apiKeyCred?.key) {
                     process.env[envVar] = apiKeyCred.key;
                 }

package/dist/resources/extensions/remote-questions/remote-command.js

@@ -301,7 +301,7 @@ function saveProviderToken(provider, token) {
 }
 function removeProviderToken(provider) {
     const auth = getAuthStorage();
-    auth.set(provider, { type: "api_key", key: "" });
+    auth.remove(provider);
 }
 export function saveRemoteQuestionsConfig(channel, channelId) {
     const prefsPath = getGlobalGSDPreferencesPath();

package/dist/resources/extensions/search-the-web/native-search.js

@@ -22,7 +22,7 @@ const THINKING_TYPES = new Set(["thinking", "redacted_thinking"]);
 export const MAX_NATIVE_SEARCHES_PER_SESSION = 15;
 /** When true, skip native web search injection and keep Brave/custom tools active on Anthropic. */
 export function preferBraveSearch() {
-    // preferences.md takes priority over env var
+    // PREFERENCES.md takes priority over env var
     const prefsPref = resolveSearchProviderFromPreferences();
     if (prefsPref === "brave" || prefsPref === "tavily" || prefsPref === "ollama")
         return true;

package/dist/resources/extensions/search-the-web/provider.js

@@ -91,7 +91,7 @@ export function resolveSearchProvider(overridePreference) {
         pref = overridePreference;
     }
     else {
-        // preferences.md takes priority over auth.json
+        // PREFERENCES.md takes priority over auth.json
         const mdPref = resolveSearchProviderFromPreferences();
         if (mdPref && mdPref !== 'auto' && mdPref !== 'native') {
             pref = mdPref;

package/dist/resources/extensions/shared/rtk-session-stats.js

@@ -0,0 +1,189 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "../gsd/paths.js";
+import { formatTokenCount } from "./format-utils.js";
+import { buildRtkEnv, isRtkEnabled, resolveRtkBinaryPath } from "./rtk.js";
+const SESSION_BASELINES_FILE = "rtk-session-baselines.json";
+const CURRENT_SUMMARY_TTL_MS = 15_000;
+const CURRENT_SUMMARY_TIMEOUT_MS = 5_000;
+const MAX_BASELINE_SESSIONS = 200;
+let cachedSummary = null;
+function getRuntimeDir(basePath) {
+    return join(gsdRoot(basePath), "runtime");
+}
+function getBaselinesPath(basePath) {
+    return join(getRuntimeDir(basePath), SESSION_BASELINES_FILE);
+}
+function defaultStore() {
+    return { version: 1, sessions: {} };
+}
+function loadBaselineStore(basePath) {
+    const path = getBaselinesPath(basePath);
+    if (!existsSync(path))
+        return defaultStore();
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (parsed.version !== 1 || typeof parsed.sessions !== "object" || parsed.sessions === null) {
+            return defaultStore();
+        }
+        return {
+            version: 1,
+            sessions: parsed.sessions,
+        };
+    }
+    catch {
+        return defaultStore();
+    }
+}
+function saveBaselineStore(basePath, store) {
+    const runtimeDir = getRuntimeDir(basePath);
+    mkdirSync(runtimeDir, { recursive: true });
+    const entries = Object.entries(store.sessions)
+        .sort((left, right) => right[1].updatedAt.localeCompare(left[1].updatedAt))
+        .slice(0, MAX_BASELINE_SESSIONS);
+    const normalized = {
+        version: 1,
+        sessions: Object.fromEntries(entries),
+    };
+    writeFileSync(getBaselinesPath(basePath), JSON.stringify(normalized, null, 2), "utf-8");
+}
+function normalizeSummary(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const summary = raw;
+    return {
+        totalCommands: Number(summary.total_commands ?? 0),
+        totalInput: Number(summary.total_input ?? 0),
+        totalOutput: Number(summary.total_output ?? 0),
+        totalSaved: Number(summary.total_saved ?? 0),
+        avgSavingsPct: Number(summary.avg_savings_pct ?? 0),
+        totalTimeMs: Number(summary.total_time_ms ?? 0),
+        avgTimeMs: Number(summary.avg_time_ms ?? 0),
+    };
+}
+export function readCurrentRtkGainSummary(env = process.env) {
+    if (!isRtkEnabled(env))
+        return null;
+    const binaryPath = resolveRtkBinaryPath({ env });
+    if (!binaryPath)
+        return null;
+    if (cachedSummary &&
+        cachedSummary.binaryPath === binaryPath &&
+        Date.now() - cachedSummary.at < CURRENT_SUMMARY_TTL_MS) {
+        return cachedSummary.summary;
+    }
+    const result = spawnSync(binaryPath, ["gain", "--all", "--format", "json"], {
+        encoding: "utf-8",
+        env: buildRtkEnv(env),
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: CURRENT_SUMMARY_TIMEOUT_MS,
+        // .cmd/.bat wrappers (used by fake-rtk in tests) require shell:true on Windows
+        shell: /\.(cmd|bat)$/i.test(binaryPath),
+    });
+    if (result.error || result.status !== 0) {
+        cachedSummary = { at: Date.now(), binaryPath, summary: null };
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(result.stdout ?? "{}");
+        const summary = normalizeSummary(parsed.summary ?? null);
+        cachedSummary = { at: Date.now(), binaryPath, summary };
+        return summary;
+    }
+    catch {
+        cachedSummary = { at: Date.now(), binaryPath, summary: null };
+        return null;
+    }
+}
+function computeSavingsDelta(current, baseline) {
+    const commands = Math.max(0, current.totalCommands - baseline.totalCommands);
+    const inputTokens = Math.max(0, current.totalInput - baseline.totalInput);
+    const outputTokens = Math.max(0, current.totalOutput - baseline.totalOutput);
+    const savedTokens = Math.max(0, current.totalSaved - baseline.totalSaved);
+    const totalTimeMs = Math.max(0, current.totalTimeMs - baseline.totalTimeMs);
+    const avgTimeMs = commands > 0 ? Math.round(totalTimeMs / commands) : 0;
+    const savingsPct = inputTokens > 0 ? (savedTokens / inputTokens) * 100 : 0;
+    return {
+        commands,
+        inputTokens,
+        outputTokens,
+        savedTokens,
+        savingsPct,
+        totalTimeMs,
+        avgTimeMs,
+        updatedAt: new Date().toISOString(),
+    };
+}
+export function ensureRtkSessionBaseline(basePath, sessionId, env = process.env) {
+    if (!sessionId)
+        return null;
+    const current = readCurrentRtkGainSummary(env);
+    if (!current)
+        return null;
+    const store = loadBaselineStore(basePath);
+    const existing = store.sessions[sessionId];
+    if (existing)
+        return existing.summary;
+    const now = new Date().toISOString();
+    store.sessions[sessionId] = {
+        summary: current,
+        createdAt: now,
+        updatedAt: now,
+    };
+    saveBaselineStore(basePath, store);
+    return current;
+}
+export function getRtkSessionSavings(basePath, sessionId, env = process.env) {
+    if (!sessionId)
+        return null;
+    const current = readCurrentRtkGainSummary(env);
+    if (!current)
+        return null;
+    const store = loadBaselineStore(basePath);
+    const existing = store.sessions[sessionId];
+    if (!existing) {
+        const now = new Date().toISOString();
+        store.sessions[sessionId] = {
+            summary: current,
+            createdAt: now,
+            updatedAt: now,
+        };
+        saveBaselineStore(basePath, store);
+        return computeSavingsDelta(current, current);
+    }
+    if (current.totalCommands < existing.summary.totalCommands ||
+        current.totalInput < existing.summary.totalInput ||
+        current.totalSaved < existing.summary.totalSaved) {
+        const now = new Date().toISOString();
+        store.sessions[sessionId] = {
+            summary: current,
+            createdAt: existing.createdAt,
+            updatedAt: now,
+        };
+        saveBaselineStore(basePath, store);
+        return computeSavingsDelta(current, current);
+    }
+    existing.updatedAt = new Date().toISOString();
+    saveBaselineStore(basePath, store);
+    return computeSavingsDelta(current, existing.summary);
+}
+export function clearRtkSessionBaseline(basePath, sessionId) {
+    if (!sessionId)
+        return;
+    const store = loadBaselineStore(basePath);
+    if (!(sessionId in store.sessions))
+        return;
+    delete store.sessions[sessionId];
+    saveBaselineStore(basePath, store);
+}
+export function formatRtkSavingsLabel(savings) {
+    if (!savings)
+        return null;
+    if (savings.commands <= 0)
+        return "rtk: waiting for shell usage";
+    if (savings.inputTokens <= 0 && savings.outputTokens <= 0) {
+        return `rtk: active (${savings.commands} cmd${savings.commands === 1 ? "" : "s"})`;
+    }
+    return `rtk: ${formatTokenCount(savings.savedTokens)} saved (${Math.round(savings.savingsPct)}%)`;
+}

package/dist/resources/extensions/shared/rtk.js

@@ -0,0 +1,100 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+const GSD_RTK_PATH_ENV = "GSD_RTK_PATH";
+const GSD_RTK_DISABLED_ENV = "GSD_RTK_DISABLED";
+const RTK_TELEMETRY_DISABLED_ENV = "RTK_TELEMETRY_DISABLED";
+const RTK_REWRITE_TIMEOUT_MS = 5_000;
+function isTruthy(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+export function isRtkEnabled(env = process.env) {
+    return !isTruthy(env[GSD_RTK_DISABLED_ENV]);
+}
+export function buildRtkEnv(env = process.env) {
+    return {
+        ...env,
+        [RTK_TELEMETRY_DISABLED_ENV]: "1",
+    };
+}
+function getManagedRtkDir(env = process.env) {
+    return join(env.GSD_HOME || join(homedir(), ".gsd"), "agent", "bin");
+}
+function getRtkBinaryName(platform = process.platform) {
+    return platform === "win32" ? "rtk.exe" : "rtk";
+}
+function getPathValue(env) {
+    const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path");
+    return pathKey ? env[pathKey] : env.PATH;
+}
+function resolvePathCandidates(pathValue) {
+    if (!pathValue)
+        return [];
+    return pathValue
+        .split(delimiter)
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
+function resolveSystemRtkPath(pathValue, platform = process.platform) {
+    const candidates = platform === "win32"
+        ? ["rtk.exe", "rtk.cmd", "rtk.bat", "rtk"]
+        : ["rtk"];
+    for (const dir of resolvePathCandidates(pathValue)) {
+        for (const candidate of candidates) {
+            const fullPath = join(dir, candidate);
+            if (existsSync(fullPath)) {
+                return fullPath;
+            }
+        }
+    }
+    return null;
+}
+export function resolveRtkBinaryPath(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const explicitPath = options.binaryPath ?? env[GSD_RTK_PATH_ENV];
+    if (explicitPath && existsSync(explicitPath)) {
+        return explicitPath;
+    }
+    const managedDir = getManagedRtkDir(env);
+    const managedPath = join(managedDir, getRtkBinaryName(platform));
+    if (existsSync(managedPath)) {
+        return managedPath;
+    }
+    // On Windows, also check for rtk.cmd in the managed dir (used by test fake RTK
+    // and any wrapper-style installs where a .cmd launcher accompanies the binary).
+    if (platform === "win32") {
+        const managedCmd = join(managedDir, "rtk.cmd");
+        if (existsSync(managedCmd)) {
+            return managedCmd;
+        }
+    }
+    return resolveSystemRtkPath(options.pathValue ?? getPathValue(env), platform);
+}
+export function rewriteCommandWithRtk(command, env = process.env) {
+    if (!command.trim())
+        return command;
+    if (!isRtkEnabled(env))
+        return command;
+    const binaryPath = resolveRtkBinaryPath({ env });
+    if (!binaryPath)
+        return command;
+    const result = spawnSync(binaryPath, ["rewrite", command], {
+        encoding: "utf-8",
+        env: buildRtkEnv(env),
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: RTK_REWRITE_TIMEOUT_MS,
+        // .cmd/.bat wrappers (used by fake-rtk in tests) require shell:true on Windows
+        shell: /\.(cmd|bat)$/i.test(binaryPath),
+    });
+    if (result.error)
+        return command;
+    if (result.status !== 0 && result.status !== 3)
+        return command;
+    const rewritten = (result.stdout ?? "").trimEnd();
+    return rewritten || command;
+}

package/dist/rtk.d.ts

@@ -0,0 +1,52 @@
+import { spawnSync } from "node:child_process";
+export declare const RTK_VERSION = "0.33.1";
+export declare const GSD_RTK_DISABLED_ENV = "GSD_RTK_DISABLED";
+export declare const GSD_SKIP_RTK_INSTALL_ENV = "GSD_SKIP_RTK_INSTALL";
+export declare const GSD_RTK_PATH_ENV = "GSD_RTK_PATH";
+export declare const RTK_TELEMETRY_DISABLED_ENV = "RTK_TELEMETRY_DISABLED";
+export interface EnsureRtkOptions {
+    targetDir?: string;
+    allowDownload?: boolean;
+    env?: NodeJS.ProcessEnv;
+    pathValue?: string;
+    releaseVersion?: string;
+    log?: (message: string) => void;
+}
+export interface EnsureRtkResult {
+    enabled: boolean;
+    supported: boolean;
+    available: boolean;
+    source: "disabled" | "unsupported" | "managed" | "system" | "downloaded" | "missing";
+    binaryPath?: string;
+    reason?: string;
+}
+export declare function isRtkEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function getManagedRtkDir(env?: NodeJS.ProcessEnv): string;
+export declare function getRtkBinaryName(platform?: NodeJS.Platform): string;
+export declare function getManagedRtkPath(platform?: NodeJS.Platform, targetDir?: string): string;
+export declare function prependPathEntry(env: NodeJS.ProcessEnv, entry: string): NodeJS.ProcessEnv;
+export declare function applyRtkProcessEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function buildRtkEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function resolveRtkAssetName(platform: NodeJS.Platform, arch: string, version?: string): string | null;
+export interface ResolveRtkBinaryPathOptions {
+    binaryPath?: string;
+    env?: NodeJS.ProcessEnv;
+    pathValue?: string;
+    platform?: NodeJS.Platform;
+    targetDir?: string;
+}
+export declare function resolveRtkBinaryPath(options?: ResolveRtkBinaryPathOptions): string | null;
+export interface RewriteCommandOptions {
+    binaryPath?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    spawnSyncImpl?: typeof spawnSync;
+}
+export declare function rewriteCommandWithRtk(command: string, options?: RewriteCommandOptions): string;
+export interface ValidateRtkBinaryOptions {
+    spawnSyncImpl?: typeof spawnSync;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function validateRtkBinary(binaryPath: string, options?: ValidateRtkBinaryOptions): boolean;
+export declare function ensureRtkAvailable(options?: EnsureRtkOptions): Promise<EnsureRtkResult>;
+export declare function bootstrapRtk(options?: EnsureRtkOptions): Promise<EnsureRtkResult>;