gsd-pi 2.74.0-dev.b741afb → 2.74.0-dev.b7c5f96

package/dist/resources/extensions/gsd/commands-extract-learnings.js

@@ -0,0 +1,225 @@
+/**
+ * GSD Command — /gsd extract-learnings
+ *
+ * Analyses completed milestone artefacts and dispatches an LLM turn that
+ * extracts structured knowledge into 4 categories:
+ *   Decisions · Lessons · Patterns · Surprises
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, basename } from "node:path";
+import { gsdRoot, resolveMilestonePath } from "./paths.js";
+import { projectRoot } from "./commands/context.js";
+// ─── Pure functions ───────────────────────────────────────────────────────────
+export function parseExtractLearningsArgs(args) {
+    const trimmed = args.trim();
+    return { milestoneId: trimmed || null };
+}
+export function buildLearningsOutputPath(milestoneDir, milestoneId) {
+    return join(milestoneDir, `${milestoneId}-LEARNINGS.md`);
+}
+export function resolvePhaseArtifacts(milestoneDir, milestoneId) {
+    const missingRequired = [];
+    const planFile = `${milestoneId}-PLAN.md`;
+    const summaryFile = `${milestoneId}-SUMMARY.md`;
+    const verificationFile = `${milestoneId}-VERIFICATION.md`;
+    const uatFile = `${milestoneId}-UAT.md`;
+    const planPath = join(milestoneDir, planFile);
+    const summaryPath = join(milestoneDir, summaryFile);
+    const verificationPath = join(milestoneDir, verificationFile);
+    const uatPath = join(milestoneDir, uatFile);
+    const plan = existsSync(planPath) ? planPath : null;
+    const summary = existsSync(summaryPath) ? summaryPath : null;
+    const verification = existsSync(verificationPath) ? verificationPath : null;
+    const uat = existsSync(uatPath) ? uatPath : null;
+    if (!plan)
+        missingRequired.push(planFile);
+    if (!summary)
+        missingRequired.push(summaryFile);
+    return { plan, summary, verification, uat, missingRequired };
+}
+export function buildExtractLearningsPrompt(ctx) {
+    const optionalSections = [];
+    if (ctx.verificationContent) {
+        optionalSections.push(`## Verification Report\n\n${ctx.verificationContent}`);
+    }
+    if (ctx.uatContent) {
+        optionalSections.push(`## UAT Report\n\n${ctx.uatContent}`);
+    }
+    const missingNote = ctx.missingArtifacts.length > 0
+        ? `\nNote: The following optional artefacts were not available: ${ctx.missingArtifacts.join(", ")}\n`
+        : "";
+    return `# Extract Learnings — ${ctx.milestoneId}: ${ctx.milestoneName}
+
+**Project:** ${ctx.projectName}
+**Output file:** ${ctx.outputPath}
+
+## Your Task
+
+Analyse the artefacts below and extract structured knowledge from milestone **${ctx.milestoneId}**.
+
+Write a LEARNINGS document to \`${ctx.outputPath}\` with the following 4 sections:
+
+### Decisions
+Key architectural and design decisions made during this milestone, including the rationale and alternatives considered.
+
+### Lessons
+What the team learned — technical discoveries, process insights, and knowledge gaps that were filled.
+
+### Patterns
+Reusable patterns, approaches, or solutions that emerged and should be applied in future work.
+
+### Surprises
+Unexpected challenges, discoveries, or outcomes — things that deviated from assumptions.
+
+### Source Attribution (REQUIRED)
+
+Every extracted item MUST include a \`Source:\` line immediately after the item text.
+Format: \`Source: {artifact-filename}/{section}\`
+Example: \`Source: M001-PLAN.md/Architecture Decisions\`
+
+Items without a Source attribution are invalid and must not be included in the output.
+
+---
+
+## Artefacts
+
+### Plan
+
+${ctx.planContent}
+
+---
+
+### Summary
+
+${ctx.summaryContent}
+
+${optionalSections.join("\n\n---\n\n")}
+${missingNote}
+---
+
+## Output Format
+
+Write the LEARNINGS file to \`${ctx.relativeOutputPath}\` with YAML frontmatter followed by the 4 sections above.
+Each section should contain concise, actionable bullet points.
+Every bullet point MUST be followed by a source line, for example:
+
+\`\`\`
+### Decisions
+- Chose PostgreSQL over SQLite for concurrent write support.
+  Source: M001-PLAN.md/Architecture Decisions
+\`\`\`
+
+Items without a \`Source:\` line are invalid.
+
+---
+
+## Optional: Capture Individual Learnings
+
+If the \`capture_thought\` tool is available, call it once for each extracted item with:
+- category: "decision" | "lesson" | "pattern" | "surprise"
+- phase: "${ctx.milestoneId}"
+- content: {the learning text}
+- source: {artifact filename}
+
+If \`capture_thought\` is not available, skip this step silently — do not report an error.
+
+---
+
+## Rebuild Knowledge Graph
+
+After writing LEARNINGS.md, call the \`gsd_graph\` tool with \`{ "mode": "build" }\` to rebuild the knowledge graph so the new learnings are immediately queryable by future milestone prompts.
+
+If the \`gsd_graph\` tool is not available, skip this step silently.
+`;
+}
+export function buildFrontmatter(ctx) {
+    const missingList = ctx.missingArtifacts.length > 0
+        ? ctx.missingArtifacts.map((a) => `  - ${a}`).join("\n")
+        : "  []";
+    const missingValue = ctx.missingArtifacts.length > 0
+        ? `\n${missingList}`
+        : " []";
+    return `---
+phase: ${ctx.milestoneId}
+phase_name: ${ctx.milestoneName}
+project: ${ctx.projectName}
+generated: ${ctx.generatedAt}
+counts:
+  decisions: ${ctx.counts.decisions}
+  lessons: ${ctx.counts.lessons}
+  patterns: ${ctx.counts.patterns}
+  surprises: ${ctx.counts.surprises}
+missing_artifacts:${missingValue}
+---`;
+}
+export function extractProjectName(basePath) {
+    const projectMdPath = join(gsdRoot(basePath), "PROJECT.md");
+    if (existsSync(projectMdPath)) {
+        try {
+            const content = readFileSync(projectMdPath, "utf-8");
+            const match = content.match(/^name:\s*(.+)$/m);
+            if (match)
+                return match[1].trim();
+        }
+        catch {
+            // non-fatal
+        }
+    }
+    return basename(basePath);
+}
+// ─── Handler ──────────────────────────────────────────────────────────────────
+export async function handleExtractLearnings(args, ctx, pi) {
+    const { milestoneId } = parseExtractLearningsArgs(args);
+    if (!milestoneId) {
+        ctx.ui.notify("Usage: /gsd extract-learnings <milestoneId>  (e.g. M001)", "warning");
+        return;
+    }
+    // projectRoot() throws GSDNoProjectError if no project found — intentional, handled by dispatcher
+    const basePath = projectRoot();
+    const milestoneDir = resolveMilestonePath(basePath, milestoneId);
+    if (!milestoneDir) {
+        ctx.ui.notify(`Milestone not found: ${milestoneId}`, "error");
+        return;
+    }
+    const artifacts = resolvePhaseArtifacts(milestoneDir, milestoneId);
+    if (artifacts.missingRequired.length > 0) {
+        ctx.ui.notify(`Cannot extract learnings — required artefacts missing: ${artifacts.missingRequired.join(", ")}`, "error");
+        return;
+    }
+    // Read required artefacts
+    const planContent = readFileSync(artifacts.plan, "utf-8");
+    const summaryContent = readFileSync(artifacts.summary, "utf-8");
+    // Read optional artefacts
+    const verificationContent = artifacts.verification
+        ? readFileSync(artifacts.verification, "utf-8")
+        : null;
+    const uatContent = artifacts.uat
+        ? readFileSync(artifacts.uat, "utf-8")
+        : null;
+    // Determine missing optional artefacts for context
+    const missingArtifacts = [];
+    if (!artifacts.verification)
+        missingArtifacts.push(`${milestoneId}-VERIFICATION.md`);
+    if (!artifacts.uat)
+        missingArtifacts.push(`${milestoneId}-UAT.md`);
+    // Extract milestone name from Plan H1 or fall back to milestoneId
+    const h1Match = planContent.match(/^#\s+(.+)$/m);
+    const milestoneName = h1Match?.[1]?.trim() ?? milestoneId;
+    const projectName = extractProjectName(basePath);
+    const outputPath = buildLearningsOutputPath(milestoneDir, milestoneId);
+    const relativeOutputPath = outputPath.replace(basePath + "/", "");
+    const prompt = buildExtractLearningsPrompt({
+        milestoneId,
+        milestoneName,
+        outputPath,
+        relativeOutputPath,
+        planContent,
+        summaryContent,
+        verificationContent,
+        uatContent,
+        missingArtifacts,
+        projectName,
+    });
+    ctx.ui.notify(`Extracting learnings for ${milestoneId}: "${milestoneName}"...`, "info");
+    pi.sendMessage({ customType: "gsd-extract-learnings", content: prompt, display: false }, { triggerTurn: true });
+}

package/dist/resources/extensions/gsd/commands-prefs-wizard.js

@@ -642,8 +642,8 @@ export async function handlePrefsWizard(ctx, scope) {
 export function yamlSafeString(val) {
     if (typeof val !== "string")
         return String(val);
-    if (/[:#{\[\]'"`,|>&*!?@%]/.test(val) || val.trim() !== val || val === "") {
-        return `"${val.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    if (/[:#{\[\]'"`,|>&*!?@%\r\n]/.test(val) || val.trim() !== val || val === "") {
+        return `"${val.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r/g, "\\r").replace(/\n/g, "\\n")}"`;
     }
     return val;
 }
@@ -705,10 +705,10 @@ export function serializePreferencesToFrontmatter(prefs) {
         "budget_ceiling", "budget_enforcement", "context_pause_threshold",
         "notifications", "cmux", "remote_questions", "git",
         "post_unit_hooks", "pre_dispatch_hooks",
-        "dynamic_routing", "token_profile", "phases", "parallel",
+        "dynamic_routing", "uok", "token_profile", "phases", "parallel",
         "auto_visualize", "auto_report",
         "verification_commands", "verification_auto_fix", "verification_max_retries",
-        "search_provider", "context_selection",
+        "search_provider", "context_selection", "language",
     ];
     const seen = new Set();
     for (const key of orderedKeys) {
@@ -739,3 +739,50 @@ export async function ensurePreferencesFile(path, ctx, scope) {
         ctx.ui.notify(`Using existing ${scope} GSD skill preferences at ${path}`, "info");
     }
 }
+/**
+ * Handle `/gsd language [code]` — set or clear the global language preference.
+ * Without an argument, shows the current setting.
+ * Project-level override can be set by editing `.gsd/preferences.md` directly
+ * (project language overrides global when both are set).
+ */
+export async function handleLanguage(args, ctx) {
+    const path = getGlobalGSDPreferencesPath();
+    const lang = args.trim();
+    // Show current setting when called without argument
+    if (!lang) {
+        const loaded = loadGlobalGSDPreferences();
+        const current = loaded?.preferences.language;
+        if (current) {
+            ctx.ui.notify(`Current language preference: ${current}\nUse /gsd language <name> to change, or /gsd language off to clear.`, "info");
+        }
+        else {
+            ctx.ui.notify("No language preference set. Use /gsd language <name> to set one (e.g. /gsd language Chinese).", "info");
+        }
+        return;
+    }
+    // Ensure preferences file exists with the canonical template
+    await ensurePreferencesFile(path, ctx, "global");
+    // Read via the same validated path as other handlers
+    const existing = loadGlobalGSDPreferences();
+    const prefs = existing?.preferences ? { ...existing.preferences } : { version: 1 };
+    if (lang === "off" || lang === "none" || lang === "clear") {
+        delete prefs.language;
+        ctx.ui.notify("Language preference cleared. GSD will use the default language.", "info");
+    }
+    else {
+        // Validate before writing — reject values that would fail on next load
+        if (lang.length > 50 || /[\r\n]/.test(lang)) {
+            ctx.ui.notify("Language value must be 50 characters or fewer with no newlines (e.g. /gsd language Chinese).", "warning");
+            return;
+        }
+        prefs.language = lang;
+        ctx.ui.notify(`Language preference set to: ${lang}\nGSD will now respond in ${lang} across all sessions.`, "info");
+    }
+    const rawContent = existsSync(path) ? readFileSync(path, "utf-8") : `---\nversion: 1\n---\n`;
+    const frontmatter = serializePreferencesToFrontmatter(prefs);
+    const body = extractBodyAfterFrontmatter(rawContent)
+        ?? "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+    await saveFile(path, `---\n${frontmatter}---${body}`);
+    await ctx.waitForIdle();
+    await ctx.reload();
+}

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -102,6 +102,8 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `custom_instructions`: extra durable instructions related to skill use. For operational project knowledge (recurring rules, gotchas, patterns), use `.gsd/KNOWLEDGE.md` instead — it's injected into every agent prompt automatically and agents can append to it during execution.
 
+- `language`: preferred response language for all GSD interactions. Accepts any language name or code — `"Chinese"`, `"zh"`, `"German"`, `"de"`, `"日本語"`, etc. When set, GSD injects "Always respond in \<language\>" into every agent's system prompt, including after `/clear`. Quickest way to set it: `/gsd language <name>`. To clear: `/gsd language off`.
+
 - `models`: per-stage model selection (applies to both auto-mode and guided-flow dispatches). Keys: `research`, `planning`, `discuss`, `execution`, `execution_simple`, `completion`, `validation`, `subagent`. Values can be:
   - Simple string: `"claude-sonnet-4-6"` — single model, no fallbacks
   - Provider-qualified string: `"bedrock/claude-sonnet-4-6"` — targets a specific provider when the same model ID exists across multiple providers
@@ -153,7 +155,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `context_pause_threshold`: number (0-100) — context window usage percentage at which auto-mode should pause to suggest checkpointing. Set to `0` to disable. Default: `0` (disabled).
 
-- `token_profile`: `"budget"`, `"balanced"`, or `"quality"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) skips research/reassessment to reduce token burn; `quality` prefers higher-quality models. See token-optimization docs.
+- `token_profile`: `"budget"`, `"balanced"`, `"quality"`, or `"burn-max"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) skips research/reassessment to reduce token burn; `quality` prefers higher-quality models; `burn-max` keeps full-context defaults, disables downgrade routing, and keeps phase skips off.
 
 - `phases`: fine-grained control over which phases run. Usually set by `token_profile`, but can be overridden. Keys:
   - `skip_research`: boolean — skip milestone-level research. Default: `false`.
@@ -191,6 +193,19 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `hooks`: boolean — enable routing hooks. Default: `true`.
   - `capability_routing`: boolean — enable capability-profile scoring for model selection within a tier. Requires `enabled: true`. Default: `false`.
 
+- `uok`: Unified Orchestration Kernel controls. Keys:
+  - `enabled`: boolean — enable kernel wrappers and contract observers. Default: `true`.
+  - `legacy_fallback.enabled`: boolean — emergency release fallback that forces legacy orchestration behavior even when `uok.enabled` is `true`. Default: `false`.
+    - Runtime override: set `GSD_UOK_FORCE_LEGACY=1` (or `GSD_UOK_LEGACY_FALLBACK=1`) to force legacy behavior for the current process.
+  - `gates.enabled`: boolean — route checks through the unified gate runner and persist `gate_runs`.
+  - `model_policy.enabled`: boolean — enforce policy filtering before model capability scoring.
+  - `execution_graph.enabled`: boolean — enable DAG scheduler facade/adapters for execution.
+  - `gitops.enabled`: boolean — persist turn-level git transaction records.
+  - `gitops.turn_action`: `"commit"` | `"snapshot"` | `"status-only"` — turn transaction mode.
+  - `gitops.turn_push`: boolean — whether turn transactions should include push intent metadata.
+  - `audit_unified.enabled`: boolean — dual-write unified audit envelope events.
+  - `plan_v2.enabled`: boolean — enable bounded clarify/research/draft/compile planning flow.
+
 - `context_management`: configures context hygiene for auto-mode sessions. Keys:
   - `observation_masking`: boolean — mask old tool results to reduce context bloat. Default: `true`.
   - `observation_mask_turns`: number — keep this many recent turns verbatim (1-50). Default: `8`.

package/dist/resources/extensions/gsd/ecosystem/gsd-extension-api.js

@@ -0,0 +1,144 @@
+// GSD2 — Ecosystem Extension API wrapper
+// Wraps pi's ExtensionAPI to expose typed GSD context (phase + active unit)
+// to extensions loaded from `./.gsd/extensions/`. The wrapper intercepts only
+// `on("before_agent_start", ...)` so GSD can dispatch ecosystem handlers AFTER
+// refreshing state — fixing the load-order race where third-party
+// `.pi/extensions/` handlers see a stale module-level snapshot (#3338).
+//
+// SINGLE-SESSION INVARIANT: the module-level `_snapshot` is per-process.
+// Worktree or project switches do NOT reload extensions, matching pi's
+// `.pi/extensions/` behavior. Only re-launching the CLI rebinds the snapshot.
+import { isGSDActive, getCurrentPhase } from "../../shared/gsd-phase-state.js";
+import { logWarning } from "../workflow-logger.js";
+// ─── Auto-loop phase mapping ────────────────────────────────────────────
+const AUTO_LOOP_PHASE_MAP = {
+    "plan-milestone": "planning",
+    "plan-slice": "planning",
+    "research": "researching",
+    "discuss": "discussing",
+    "execute-task": "executing",
+    "verify": "verifying",
+    "summarize-task": "summarizing",
+    "summarize-slice": "summarizing",
+    "advance": "advancing",
+    "validate-milestone": "validating-milestone",
+    "complete-milestone": "completing-milestone",
+    "replan-slice": "replanning-slice",
+};
+/** Exposed for unit tests. Returns null for unknown keys (does NOT default). */
+export function mapAutoLoopPhase(raw) {
+    return AUTO_LOOP_PHASE_MAP[raw] ?? null;
+}
+function resolvePhase(state) {
+    if (!state)
+        return null;
+    if (isGSDActive()) {
+        const raw = getCurrentPhase();
+        if (raw != null) {
+            const mapped = AUTO_LOOP_PHASE_MAP[raw];
+            if (mapped)
+                return mapped;
+            logWarning("ecosystem", `unknown auto-loop phase: ${raw}`);
+            // FALL THROUGH to state.phase rather than defaulting to "executing".
+        }
+    }
+    return state.phase;
+}
+function resolveActiveUnit(state) {
+    if (!state)
+        return null;
+    const m = state.activeMilestone;
+    const s = state.activeSlice;
+    const t = state.activeTask;
+    if (!m || !s || !t)
+        return null;
+    return {
+        milestoneId: m.id,
+        milestoneTitle: m.title,
+        sliceId: s.id,
+        sliceTitle: s.title,
+        taskId: t.id,
+        taskTitle: t.title,
+    };
+}
+let _snapshot = { phase: null, activeUnit: null };
+/** Refresh the snapshot from a freshly derived GSDState (or null on failure). */
+export function updateSnapshot(state) {
+    _snapshot = {
+        phase: resolvePhase(state),
+        activeUnit: resolveActiveUnit(state),
+    };
+}
+export function getSnapshotPhase() {
+    return _snapshot.phase;
+}
+export function getSnapshotActiveUnit() {
+    return _snapshot.activeUnit;
+}
+/** Test-only: reset the snapshot to its initial empty state. */
+export function _resetSnapshot() {
+    _snapshot = { phase: null, activeUnit: null };
+}
+// ─── Wrapper factory ────────────────────────────────────────────────────
+/**
+ * Build a GSDExtensionAPI by manually delegating every ExtensionAPI method
+ * to the underlying pi instance, except `on("before_agent_start", ...)`
+ * which is captured into `sharedHandlers` for GSD-owned dispatch.
+ *
+ * Uses `satisfies GSDExtensionAPI` (NOT `as`) so TypeScript catches drift
+ * when pi adds new ExtensionAPI methods.
+ */
+export function createGSDExtensionAPI(pi, sharedHandlers) {
+    const wrapper = {
+        // ── Event subscription (single intercept point) ────────────────────
+        on(event, handler) {
+            if (event === "before_agent_start") {
+                sharedHandlers.push(handler);
+                return;
+            }
+            pi.on(event, handler);
+        },
+        // ── Event emission ─────────────────────────────────────────────────
+        emitBeforeModelSelect: (...args) => pi.emitBeforeModelSelect(...args),
+        emitAdjustToolSet: (...args) => pi.emitAdjustToolSet(...args),
+        // ── Tool / command / shortcut / flag registration ──────────────────
+        registerTool: ((tool) => pi.registerTool(tool)),
+        registerCommand: (...args) => pi.registerCommand(...args),
+        registerBeforeInstall: (...args) => pi.registerBeforeInstall(...args),
+        registerAfterInstall: (...args) => pi.registerAfterInstall(...args),
+        registerBeforeRemove: (...args) => pi.registerBeforeRemove(...args),
+        registerAfterRemove: (...args) => pi.registerAfterRemove(...args),
+        registerShortcut: (...args) => pi.registerShortcut(...args),
+        registerFlag: (...args) => pi.registerFlag(...args),
+        getFlag: (...args) => pi.getFlag(...args),
+        // ── Message rendering ──────────────────────────────────────────────
+        registerMessageRenderer: ((customType, renderer) => pi.registerMessageRenderer(customType, renderer)),
+        // ── Actions ────────────────────────────────────────────────────────
+        sendMessage: ((message, options) => pi.sendMessage(message, options)),
+        sendUserMessage: (...args) => pi.sendUserMessage(...args),
+        retryLastTurn: () => pi.retryLastTurn(),
+        appendEntry: ((customType, data) => pi.appendEntry(customType, data)),
+        // ── Session metadata ───────────────────────────────────────────────
+        setSessionName: (...args) => pi.setSessionName(...args),
+        getSessionName: () => pi.getSessionName(),
+        setLabel: (...args) => pi.setLabel(...args),
+        exec: (...args) => pi.exec(...args),
+        getActiveTools: () => pi.getActiveTools(),
+        getAllTools: () => pi.getAllTools(),
+        setActiveTools: (...args) => pi.setActiveTools(...args),
+        getCommands: () => pi.getCommands(),
+        // ── Model & thinking ───────────────────────────────────────────────
+        setModel: (...args) => pi.setModel(...args),
+        getThinkingLevel: () => pi.getThinkingLevel(),
+        setThinkingLevel: (...args) => pi.setThinkingLevel(...args),
+        // ── Provider registration ──────────────────────────────────────────
+        registerProvider: (...args) => pi.registerProvider(...args),
+        unregisterProvider: (...args) => pi.unregisterProvider(...args),
+        // ── Shared event bus (passthrough property) ────────────────────────
+        events: pi.events,
+        // ── GSD-specific additions ─────────────────────────────────────────
+        getPhase: () => _snapshot.phase,
+        getActiveUnit: () => _snapshot.activeUnit,
+    };
+    return wrapper;
+}

package/dist/resources/extensions/gsd/ecosystem/loader.js

@@ -0,0 +1,145 @@
+// GSD2 — Ecosystem extension loader for ./.gsd/extensions/
+// Discovers and registers single-file extensions that consume GSDExtensionAPI.
+// Trust-gated (mirrors pi's `.pi/extensions/` model) and isolated from pi's
+// own loader chain — handlers run in GSD's own dispatch step, not pi's.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import { getAgentDir } from "@gsd/pi-coding-agent";
+import { logWarning } from "../workflow-logger.js";
+import { createGSDExtensionAPI, } from "./gsd-extension-api.js";
+// ─── Trust check (inlined; pi does not export isProjectTrusted from its
+// package root, and constraint forbids modifying packages/pi-coding-agent/) ─
+const TRUSTED_PROJECTS_FILE = "trusted-projects.json";
+function isProjectTrusted(projectPath, agentDir) {
+    const canonical = path.resolve(projectPath);
+    const trustedPath = path.join(agentDir, TRUSTED_PROJECTS_FILE);
+    try {
+        const content = fs.readFileSync(trustedPath, "utf-8");
+        const parsed = JSON.parse(content);
+        if (Array.isArray(parsed)) {
+            return parsed.includes(canonical);
+        }
+    }
+    catch {
+        // missing or malformed — treat as untrusted
+    }
+    return false;
+}
+// ─── Ready-promise singleton ────────────────────────────────────────────
+let _readyPromise = null;
+let _untrustedWarned = false;
+/**
+ * Discover and register ecosystem extensions from `./.gsd/extensions/`.
+ * Idempotent: subsequent calls with the same arguments return the same
+ * pending promise (no double-load).
+ */
+export function loadEcosystemExtensions(pi, sharedHandlers, cwd = process.cwd()) {
+    if (_readyPromise)
+        return _readyPromise;
+    _readyPromise = _loadEcosystemExtensionsImpl(pi, sharedHandlers, cwd);
+    return _readyPromise;
+}
+/**
+ * Returns a promise that resolves when ecosystem loading has completed.
+ * If loading was never kicked off this returns a resolved promise so the
+ * `before_agent_start` handler can `await` unconditionally.
+ */
+export function getEcosystemReadyPromise() {
+    return _readyPromise ?? Promise.resolve();
+}
+/** Test-only: clear the singleton so tests can re-run loading. */
+export function _resetEcosystemLoader() {
+    _readyPromise = null;
+    _untrustedWarned = false;
+}
+// ─── Implementation ─────────────────────────────────────────────────────
+async function _loadEcosystemExtensionsImpl(pi, sharedHandlers, cwd) {
+    const extDir = path.join(cwd, ".gsd", "extensions");
+    if (!fs.existsSync(extDir))
+        return;
+    // Trust gate: refuse to load arbitrary code from untrusted project dirs.
+    if (!isProjectTrusted(cwd, getAgentDir())) {
+        if (!_untrustedWarned) {
+            _untrustedWarned = true;
+            logWarning("ecosystem", ".gsd/extensions present but project is not trusted — skipping ecosystem extensions. Run `pi trust` to opt in.");
+        }
+        return;
+    }
+    // Resolve realpath ONCE so symlink-escape detection has a stable anchor.
+    let realExtDir;
+    try {
+        realExtDir = fs.realpathSync(extDir);
+    }
+    catch (err) {
+        logWarning("ecosystem", `failed to resolve extensions dir: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    let entries;
+    try {
+        entries = fs
+            .readdirSync(extDir)
+            .filter((f) => f.endsWith(".js") || f.endsWith(".ts"))
+            .sort(); // deterministic load order
+    }
+    catch (err) {
+        logWarning("ecosystem", `failed to read extensions dir: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    // The wrapper api is built once per loader run and shared by all extensions
+    // so they all read from the same module-level snapshot.
+    const api = createGSDExtensionAPI(pi, sharedHandlers);
+    for (const entry of entries) {
+        await _loadOne(extDir, realExtDir, entry, api);
+    }
+}
+async function _loadOne(extDir, realExtDir, entry, api) {
+    const fullPath = path.join(extDir, entry);
+    // Symlink-escape guard: reject entries whose realpath is not under realExtDir.
+    let realFullPath;
+    try {
+        realFullPath = fs.realpathSync(fullPath);
+    }
+    catch (err) {
+        logWarning("ecosystem", `failed to resolve ${entry}: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    const realExtDirWithSep = realExtDir.endsWith(path.sep) ? realExtDir : realExtDir + path.sep;
+    if (realFullPath !== realExtDir &&
+        !realFullPath.startsWith(realExtDirWithSep)) {
+        logWarning("ecosystem", `rejecting ${entry}: realpath escapes extensions dir`);
+        return;
+    }
+    // For .ts files, require a sibling compiled .js — we do not run a TS loader
+    // in production. Drop mtime heuristics: if .js exists, prefer it; otherwise warn.
+    let importPath = realFullPath;
+    if (entry.endsWith(".ts")) {
+        const jsSibling = realFullPath.slice(0, -3) + ".js";
+        if (fs.existsSync(jsSibling)) {
+            importPath = jsSibling;
+        }
+        else {
+            logWarning("ecosystem", `${entry}: TypeScript source has no compiled .js sibling — compile it first`);
+            return;
+        }
+    }
+    let mod;
+    try {
+        mod = await import(pathToFileURL(importPath).href);
+    }
+    catch (err) {
+        logWarning("ecosystem", `failed to import ${entry}: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    const factory = mod?.default;
+    if (typeof factory !== "function") {
+        logWarning("ecosystem", `${entry}: default export is not a function`);
+        return;
+    }
+    try {
+        await factory(api);
+    }
+    catch (err) {
+        logWarning("ecosystem", `factory threw for ${entry}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}