gsd-pi 2.50.0 → 2.51.0-dev.ae8f7cb

package/dist/resources/extensions/gsd/skill-discovery.js

@@ -9,8 +9,9 @@
  */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { getAgentDir } from "@gsd/pi-coding-agent";
-const SKILLS_DIR = join(getAgentDir(), "skills");
+import { homedir } from "node:os";
+/** Industry-standard skills.sh global skills directory */
+const SKILLS_DIR = join(homedir(), ".agents", "skills");
 /** Snapshot of skill names at auto-mode start */
 let baselineSkills = null;
 /**

package/dist/resources/extensions/gsd/skill-health.js

@@ -14,7 +14,7 @@
  */
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { getAgentDir } from "@gsd/pi-coding-agent";
+import { homedir } from "node:os";
 import { formatCost, formatTokenCount, loadLedgerFromDisk } from "./metrics.js";
 import { detectStaleSkills } from "./skill-telemetry.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
@@ -141,7 +141,7 @@ export function formatSkillDetail(basePath, skillName) {
         lines.push(`  ${date}  ${u.id.padEnd(20)}  ${formatTokenCount(u.tokens.total).padStart(8)} tokens  ${formatCost(u.cost)}`);
     }
     // Check for SKILL.md existence
-    const skillPath = join(getAgentDir(), "skills", skillName, "SKILL.md");
+    const skillPath = join(homedir(), ".agents", "skills", skillName, "SKILL.md");
     if (existsSync(skillPath)) {
         const stat = require("node:fs").statSync(skillPath);
         lines.push("");

package/dist/resources/extensions/gsd/skill-telemetry.js

@@ -12,7 +12,7 @@
  */
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { getAgentDir } from "@gsd/pi-coding-agent";
+import { homedir } from "node:os";
 // ─── In-memory state ──────────────────────────────────────────────────────────
 /** Skills available in the system prompt for the current unit */
 let availableSkills = [];
@@ -24,8 +24,14 @@ const activelyLoadedSkills = new Set();
  * Called before each unit starts.
  */
 export function captureAvailableSkills() {
-    const skillsDir = join(getAgentDir(), "skills");
-    availableSkills = listSkillNames(skillsDir);
+    const skillsDir = join(homedir(), ".agents", "skills");
+    const legacyDir = join(homedir(), ".gsd", "agent", "skills");
+    const names = listSkillNames(skillsDir);
+    // Include skills still in the legacy directory only if migration hasn't completed
+    const legacyMigrated = existsSync(join(legacyDir, ".migrated-to-agents"));
+    const legacyNames = legacyMigrated ? [] : listSkillNames(legacyDir);
+    const all = new Set([...names, ...legacyNames]);
+    availableSkills = [...all];
     activelyLoadedSkills.clear();
 }
 /**
@@ -85,8 +91,12 @@ export function detectStaleSkills(units, thresholdDays) {
     const cutoff = Date.now() - (thresholdDays * 24 * 60 * 60 * 1000);
     const stale = [];
     // Check all installed skills, not just those with usage data
-    const skillsDir = join(getAgentDir(), "skills");
-    const installed = listSkillNames(skillsDir);
+    const skillsDir = join(homedir(), ".agents", "skills");
+    const legacyDir = join(homedir(), ".gsd", "agent", "skills");
+    const legacyMigrated = existsSync(join(legacyDir, ".migrated-to-agents"));
+    const legacyNames = legacyMigrated ? [] : listSkillNames(legacyDir);
+    const installedSet = new Set([...listSkillNames(skillsDir), ...legacyNames]);
+    const installed = [...installedSet];
     for (const skill of installed) {
         const lastTs = lastUsed.get(skill);
         if (lastTs === undefined || lastTs < cutoff) {

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

@@ -4,7 +4,8 @@
 import { parseRoadmap, parsePlan, } from './parsers-legacy.js';
 import { parseSummary, loadFile, parseRequirementCounts, parseContextDependsOn, } from './files.js';
 import { resolveMilestoneFile, resolveSlicePath, resolveSliceFile, resolveTaskFile, resolveTasksDir, resolveGsdRootFile, gsdRoot, } from './paths.js';
-import { milestoneIdSort, findMilestoneIds } from './milestone-ids.js';
+import { findMilestoneIds } from './milestone-ids.js';
+import { loadQueueOrder, sortByQueueOrder } from './queue-order.js';
 import { nativeBatchParseGsdFiles } from './native-parser-bridge.js';
 import { join, resolve } from 'path';
 import { existsSync, readdirSync } from 'node:fs';
@@ -84,8 +85,14 @@ export async function getActiveMilestoneId(basePath) {
     if (isDbAvailable()) {
         const allMilestones = getAllMilestones();
         if (allMilestones.length > 0) {
-            const sorted = [...allMilestones].sort((a, b) => a.id.localeCompare(b.id));
-            for (const m of sorted) {
+            // Respect queue-order.json so /gsd queue reordering is honored (#2556).
+            // Without this, the DB path uses lexicographic sort while the dispatch
+            // guard uses queue order — causing a deadlock.
+            const customOrder = loadQueueOrder(basePath);
+            const sortedIds = sortByQueueOrder(allMilestones.map(m => m.id), customOrder);
+            const byId = new Map(allMilestones.map(m => [m.id, m]));
+            for (const id of sortedIds) {
+                const m = byId.get(id);
                 if (m.status === "complete" || m.status === "done" || m.status === "parked")
                     continue;
                 return m.id;
@@ -233,8 +240,13 @@ export async function deriveStateFromDb(basePath) {
             });
         }
     }
-    // Re-sort so milestones are in canonical order after injection
-    allMilestones.sort((a, b) => milestoneIdSort(a.id, b.id));
+    // Re-sort so milestones follow queue order (same as dispatch guard) (#2556)
+    const customOrder = loadQueueOrder(basePath);
+    const sortedIds = sortByQueueOrder(allMilestones.map(m => m.id), customOrder);
+    const byId = new Map(allMilestones.map(m => [m.id, m]));
+    allMilestones.length = 0;
+    for (const id of sortedIds)
+        allMilestones.push(byId.get(id));
     // Parallel worker isolation: when locked, filter to just the locked milestone
     const milestoneLock = process.env.GSD_MILESTONE_LOCK;
     const milestones = milestoneLock

package/dist/resources/extensions/gsd/templates/milestone-validation.md

@@ -35,6 +35,18 @@ validated_at: {{date}}
 
 - **{{requirementId}}**: {{status}} — {{disposition: covered by remediation slice / acceptable gap / needs attention}}
 
+## Verification Class Compliance
+
+<!-- If verification classes were defined during planning, document whether each
+     was addressed. Use N/A for classes that were empty or "none" in planning. -->
+
+| Class | Planned | Evidence | Status |
+|-------|---------|----------|--------|
+| Contract | {{planned_or_none}} | {{evidence_or_none}} | {{MET / NOT MET / N/A}} |
+| Integration | {{planned_or_none}} | {{evidence_or_none}} | {{MET / NOT MET / N/A}} |
+| Operational | {{planned_or_none}} | {{evidence_or_none}} | {{MET / NOT MET / N/A}} |
+| UAT | {{planned_or_none}} | {{evidence_or_none}} | {{MET / NOT MET / N/A}} |
+
 ## Remediation Slices
 
 <!-- New slices appended to the roadmap to address auto-remediable gaps.

package/dist/resources/extensions/gsd/templates/preferences.md

@@ -71,6 +71,8 @@ remote_questions:
 uat_dispatch:
 post_unit_hooks: []
 pre_dispatch_hooks: []
+# experimental:
+#   rtk: false
 ---
 
 # GSD Skill Preferences

package/dist/resources/extensions/gsd/tests/dist-redirect.mjs

@@ -7,17 +7,28 @@ const require = createRequire(import.meta.url);
 const ROOT = new URL("../../../../../", import.meta.url);
 
 export function resolve(specifier, context, nextResolve) {
-  // 1. Direct redirects to dist/ for specific packages
+  // 1. Redirect all workspace package bare imports to source.
+  //    CI portability runs don't build any packages/ dist artifacts, so every
+  //    @gsd/* specifier (including transitive ones pulled in by pi-coding-agent
+  //    source itself) must resolve to the TypeScript source entrypoint.
   if (specifier === "../../packages/pi-coding-agent/src/index.js") {
-    specifier = new URL("packages/pi-coding-agent/dist/index.js", ROOT).href;
+    specifier = new URL("packages/pi-coding-agent/src/index.ts", ROOT).href;
+  } else if (specifier === "@gsd/pi-coding-agent") {
+    specifier = new URL("packages/pi-coding-agent/src/index.ts", ROOT).href;
   } else if (specifier === "@gsd/pi-ai/oauth") {
-    specifier = new URL("packages/pi-ai/dist/utils/oauth/index.js", ROOT).href;
+    specifier = new URL("packages/pi-ai/src/utils/oauth/index.ts", ROOT).href;
   } else if (specifier === "@gsd/pi-ai") {
-    specifier = new URL("packages/pi-ai/dist/index.js", ROOT).href;
+    specifier = new URL("packages/pi-ai/src/index.ts", ROOT).href;
   } else if (specifier === "@gsd/pi-agent-core") {
-    specifier = new URL("packages/pi-agent-core/dist/index.js", ROOT).href;
+    specifier = new URL("packages/pi-agent-core/src/index.ts", ROOT).href;
   } else if (specifier === "@gsd/pi-tui") {
-    specifier = new URL("packages/pi-tui/dist/index.js", ROOT).href;
+    specifier = new URL("packages/pi-tui/src/index.ts", ROOT).href;
+  } else if (specifier === "@gsd/native") {
+    specifier = new URL("packages/native/src/index.ts", ROOT).href;
+  } else if (specifier.startsWith("@gsd/native/")) {
+    // Sub-path imports like @gsd/native/fd, @gsd/native/text, etc.
+    const subpath = specifier.slice("@gsd/native/".length);
+    specifier = new URL(`packages/native/src/${subpath}/index.ts`, ROOT).href;
   }
   // 2. Redirect packages/*/dist/ → packages/*/src/ with .js→.ts for strip-types
   //    Also handles local imports — skip rewrite for dist/ paths that are real compiled artifacts.
@@ -54,9 +65,15 @@ export function resolve(specifier, context, nextResolve) {
 }
 
 export function load(url, context, nextLoad) {
-  // Node's --experimental-strip-types handles .ts but not .tsx (which may contain JSX).
-  // Use TypeScript to transpile .tsx → JS with react-jsx transform, then serve as module.
-  if (url.endsWith('.tsx')) {
+  // Node's --experimental-strip-types handles plain .ts but not .tsx and not
+  // all TypeScript syntax used by workspace packages (parameter properties,
+  // decorators, etc.). Transpile all workspace package source files and .tsx
+  // files through TypeScript's transpileModule to avoid those crashes.
+  const shouldTranspileWithTypeScript =
+    url.endsWith('.tsx') ||
+    (url.endsWith('.ts') && url.includes('/packages/') && url.includes('/src/'));
+
+  if (shouldTranspileWithTypeScript) {
     const ts = require('typescript');
     const source = readFileSync(fileURLToPath(url), 'utf-8');
     const { outputText } = ts.transpileModule(source, {
@@ -66,6 +83,8 @@ export function load(url, context, nextLoad) {
         module: ts.ModuleKind.ESNext,
         target: ts.ScriptTarget.ESNext,
         esModuleInterop: true,
+        experimentalDecorators: true,
+        emitDecoratorMetadata: true,
       },
     });
     return { format: 'module', source: outputText, shortCircuit: true };

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/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>;