gsd-pi 2.77.0 → 2.78.0-dev.aeeb2ca00

package/README.md

@@ -27,51 +27,69 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.76
+## What's New in v2.78
 
-### Memory System
+### Worktree Lifecycle & Forensics
 
-- **Persistent agent memory** — new `capture_thought`, `memory_query`, and `gsd_graph` tools let GSD store, retrieve, and relate thoughts across sessions (Phase 1).
-- **Ingestion + scopes/tags** — memories can be scoped (project, milestone, slice) and tagged for filtering (Phase 2).
-- **Hybrid retrieval** — keyword + semantic search over stored memory for higher-recall lookup (Phase 3).
-- **Knowledge graph relationships** — memories link into a queryable graph, feeding planning and dispatch context (Phase 4).
-- **Maintenance & observability** — cap cascade, decay metrics, and export/import for memory stores (Phase 5).
+- **Slice-cadence worktree collapse (#4765)** — new `git.collapse_cadence: "milestone" | "slice"` preference. With `slice`, each validated slice squash-merges to main immediately, shrinking the orphan window from milestone-size to slice-size. Pair with `git.milestone_resquash: true` to collapse per-slice commits into one milestone commit at completion.
+- **Worktree telemetry (#4764)** — new journal events (`worktree-created`, `worktree-merged`, `worktree-orphaned`, `auto-exit`, `canonical-root-redirect`, `slice-merged`, `milestone-resquash`) and a `summarizeWorktreeTelemetry` aggregator that reports orphan breakdowns, merge durations, conflict counts, exit reasons, and unmerged-exit metrics.
+- **`/gsd forensics` worktree section** — surfaces the telemetry above with two new anomalies: `worktree-orphan` and `worktree-unmerged-exit`.
+- **Worktree-aware canonical milestone root (#4761)** — `resolveCanonicalMilestoneRoot` routes validators and cross-session readers through the live worktree, so milestone validation no longer silently reads stale project-root state.
+- **Bootstrap orphan audit (#4762)** — in-progress milestones with commits ahead of main no longer get skipped; the audit emits a warning with commit count and worktree location so interrupted auto-runs are visible.
 
-### Progressive Planning (ADR-011)
+### Auto Pipeline & Component System
 
-- **Sketch-then-refine planning** — Phase 1 introduces progressive plan elaboration so GSD drafts a lightweight sketch before locking a full plan (#3789).
-- **Mid-execution escalation** — Phase 2 lets tasks escalate complexity mid-run with compensating rollback on write failure (#3789).
+- **Unified component system** — skills, agents, pipelines, and marketplace are now one component model wired through runtime, dispatch, and telemetry, replacing per-surface plumbing.
+- **UnitContextManifest v2 (#4924, #4934)** — auto dispatch runs through a typed manifest with declarative tools-policy and typed computed artifacts. CI guards the schema so drift fails fast.
+- **Composer migration phase 3 (#4782)** — `complete-slice`, `research-milestone`, `run-uat`, and `reassess-roadmap` now build context through the manifest composer for a consistent shape across units.
+- **Milestone scope classifier + pipeline variants (#4781)** — auto picks a pipeline variant from milestone shape, so research-heavy and execution-heavy milestones no longer share a one-size dispatch path.
+- **Per-unit-type skill manifest resolver (#4779)** — skills wire into specific unit types instead of being globally on, with manifests expanded across the remaining types.
+- **Single-writer-v3 control plane** — closes outstanding gaps in the durable-state writer model so concurrent writers can't desync workflow state.
+- **Opt-in `reassess-roadmap` (#4778)** — gated behind the `skip_clean_reassess` preference per ADR-003 §4; auto no longer triggers reassessment unprompted.
 
-### Workflow & Onboarding
+### Extensions Framework
 
-- **Unified workflow plugin system** — new plugin architecture with modes and remote install. Manage via `/gsd workflow list|run|install|info|validate`.
-- **`/gsd onboarding` re-entry** — revisit setup without restarting the TUI; setup hub disambiguation prevents duplicate banners.
-- **`/gsd scan`** — new lightweight command for rapid codebase assessment, writing to `.gsd/codebase/`.
+- **Extension lifecycle commands** — `gsd extensions install / update / uninstall / list / info / validate` for npm, git, and local sources, with dependency warnings and user-metadata tracking.
+- **Topological extension load order** — Kahn's-algorithm sort with surfaced `ExtensionLoadWarning`s, so dependent extensions resolve deterministically and misconfigurations are visible instead of silent.
+- **cmux ↔ gsd decoupling** — static cross-imports replaced with a shared `cmux-events` contract and dynamic imports, isolating extension boundaries.
+- **Extracted `@gsd-extensions/google-search` workspace** — first reference extension carved out of core; legacy in-tree source replaced with a deprecation stub.
 
-### Remote Control & TUI
+### Models, Agent, and UX
 
-- **Telegram command interface** — control auto-mode remotely via Telegram alongside existing Slack/Discord routes.
-- **Chat, footer, and welcome refresh** — TUI visuals updated; onboarding no longer hangs on re-entry.
-- **New themes** — `tui-classic` and web `classic`/`vivid` palettes added (#4301).
+- **GPT-5.5 Codex support** — added across `gsd` and `pi-ai`, including `xhigh` thinking level for custom GPT-5.5 models.
+- **Auth mode in `/model`** — providers display alongside auth mode for clearer routing.
+- **Permission granularity picker** — Claude Code "Always Allow" prompts let you scope the grant instead of approving the broad case.
+- **Headless auto default → `bypassPermissions` (#4657)** — Claude Code CLI headless auto-mode runs without permission prompts by default.
+- **`skillFilter` for system prompts** — `pi-coding-agent` filters which skills are surfaced in `buildSystemPrompt`, with consumer exceptions guarded.
+- **Visual postinstall (#4641)** — install shows a spinner/banner UX so first-run state is legible.
+- **PR-risk verification** — risk prompt emits a copy-pasteable code block to make follow-up commands one step.
 
-### Models & Providers
+### Reliability & Safety
 
-- **Claude Opus 4.7** — added across Anthropic, Bedrock, Antigravity, and OpenRouter (#4348).
-- **GPT-5.4-mini** — added to the OpenAI Codex model list (#1215).
-- **Anthropic proxy support** — `ANTHROPIC_BASE_URL` env var honored for custom proxy endpoints (#4140).
-- **Flat-rate provider opt-in** — `allow_flat_rate_providers` routing toggle (#4386).
-- **Ask User Questions** — optional markdown preview panel with side-by-side layout.
+- **Major git-safety pass** — clarified TOCTOU ancestry guard, atomic sync-lock acquire with PID-verified stale override, `.git/index.lock` force-removal gated by 5-min age, `GIT_DIR`/`GIT_WORK_TREE`/`GIT_INDEX_FILE` stripped from env overlays, rebase/cherry-pick/revert state detected and aborted in recovery, working tree stashed before `reset --hard` in self-heal/rollback, worktree create guarded against unborn branches, and user hooks + `commit.gpgsign` honored on auto-commits.
+- **Atomic `.gsd/` state writes** — file-locks now actually lock and throw on contention; appends are lock-wrapped to prevent interleaved writes.
+- **Compaction correctness (#4665)** — fixed chunker/truncation mismatch and silent chunk-drops that produced degenerate or empty summaries.
+- **Write-gate (#4950)** — fail-closed depth confirmation, EXDEV-safe snapshot rename, opt-out persistence default, off-by-one max-attempts fix, exception capture in `gate.execute`, and audit/DB rows for unknown gate ids.
+- **Auto state machine** — deterministic policy errors classified non-retriable (#4973), depth-verification bypass for non-interactive sessions, baseline restored between units (#4961), `restoreToolBaseline` gated by `isAutoMode` (#4966).
+- **Slice + crash recovery** — slice orchestrator state persists across crashes; ancestry-guarded force-reset, detached-HEAD refusal, and stash-by-ref recovery.
+- **Empty-turn recovery** — Claude Code CLI tool-block shape canonicalized so empty-turn recovery matches real provider output.
 
-### Auto-Mode & Reliability
+See the full [Changelog](./CHANGELOG.md) for details on every release.
 
-- **Stuck-loop hardening** — repeated units detected across the stuck window; research-dispatch stuck loop fixed (#4414).
-- **Branch isolation** — milestone branch is created on entry in `isolation: branch` mode with `main_branch` validation (#4389).
-- **Model fallback on limits** — auto-mode limit errors now trigger model fallback (#4373).
-- **Python/Windows verification** — python invocations normalized on Windows in the verification gate (#4416).
-- **Self-healing `.gsd/`** — symlinked `.gsd` staging self-heals to prevent silent data loss (#4423); `.gsd.migrating` healed on resume.
-- **Stale OAuth recovery** — stale Anthropic OAuth credentials self-heal (#4399).
+<details>
+<summary>v2.77 highlights</summary>
+
+- **Context Mode** — dispatch builds task-ready context automatically (artifacts, prior session, milestone/slice signals, execution metadata); enabled by default for new projects
+- **Sandboxed execution tools** — `gsd_exec_search`, `gsd_resume`, and sandboxed tool-output paths for context-mode flows
+- **Memory architecture (ADR-013)** — `memories` table is now authoritative; `structured_fields` adds typed metadata; dual-write migration landed with decisions backfill
+- **Skill coverage** — 9 gap-closing skills landed plus 6 planning/design skills surfaced
+- **Hook stack** — Layer 0 shell hooks and additional Layer 2 lifecycle events
+- **TUI polish** — dedicated chat-frame style for skill invocations; active-row overflow fixes
+- **Worktree + dispatch resilience** — crash-recovery dispatch hardened, safer path derivation, improved worktree context fallback
+- **DB/schema guardrails** — migration/index ordering and schema version stamping tightened
+- **Preflight hardening** — milestone completion enforces stricter clean-root checks with auto-stash
 
-See the full [Changelog](./CHANGELOG.md) for details on every release.
+</details>
 
 <details>
 <summary>v2.75 highlights</summary>
@@ -306,7 +324,7 @@ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`,
 
 5. **Provider error recovery** — Transient provider errors (rate limits, 500/503 server errors, overloaded) auto-resume after a delay. Permanent errors (auth, billing) pause for manual review. The model fallback chain retries transient network errors before switching models.
 
-6. **Stuck detection** — A sliding-window detector identifies repeated dispatch patterns (including multi-unit cycles). On detection, it retries once with a deep diagnostic. If it fails again, auto mode stops with the exact file it expected.
+6. **Stuck and artifact detection** — A sliding-window detector identifies repeated dispatch patterns (including multi-unit cycles). Missing expected artifacts use a separate bounded path: GSD retries artifact verification up to 3 times with failure context, then pauses auto mode with the missing artifact error instead of looping indefinitely.
 
 7. **Timeout supervision** — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout pauses auto mode. Recovery steering nudges the LLM to finish durable output before giving up.
 

package/dist/claude-cli-check.js

@@ -20,33 +20,71 @@ export const CLAUDE_COMMAND = process.platform === 'win32' ? 'claude.cmd' : 'cla
  * expose a bare `claude` shim. Try all three so no valid install is missed.
  */
 const CLAUDE_COMMAND_CANDIDATES = process.platform === 'win32' ? [CLAUDE_COMMAND, 'claude.exe', 'claude'] : [CLAUDE_COMMAND];
+// Codes treated as "this candidate didn't run — try the next one" rather than
+// fatal failures. ETIMEDOUT/EAGAIN cover slow-spawn cases on Windows where
+// cmd.exe wrapping plus the Claude CLI startup path together exceed the
+// per-attempt timeout (Issue #4997 regression on Windows + Node 25).
+const SOFT_FAIL_CODES = new Set(['ENOENT', 'EINVAL', 'ETIMEDOUT', 'EAGAIN']);
+const VERSION_TIMEOUT_MS = 5_000;
+// Auth probe needs more headroom on Windows because the spawn goes through
+// cmd.exe → claude.cmd → node → Claude CLI.
+const AUTH_TIMEOUT_MS = 15_000;
 /**
  * Try to run `args` against each candidate binary.
  * Returns the output buffer on first success, throws the last error if all fail.
  */
-function execClaudeCheck(args) {
+function execClaudeCheck(args, timeoutMs) {
     let lastError;
     for (const command of CLAUDE_COMMAND_CANDIDATES) {
         try {
-            return execFileSync(command, args, { timeout: 5_000, stdio: 'pipe' });
+            return execFileSync(command, args, {
+                timeout: timeoutMs,
+                stdio: 'pipe',
+                shell: process.platform === 'win32',
+            });
         }
         catch (error) {
             lastError = error;
             const code = error?.code;
-            // EINVAL can surface on Windows Git Bash for .cmd spawn failures.
-            if (code === 'ENOENT' || code === 'EINVAL')
+            if (code && SOFT_FAIL_CODES.has(code))
                 continue;
             throw error;
         }
     }
     throw lastError ?? new Error(`Claude CLI not found (tried: ${CLAUDE_COMMAND_CANDIDATES.join(', ')})`);
 }
+/**
+ * Decide auth state from `claude auth status` output.
+ *
+ * Newer Claude CLI builds emit JSON with a `loggedIn` boolean. Older builds
+ * emit free-form text. Prefer the structured signal; fall back to a text
+ * heuristic. The text heuristic only covers English phrasing.
+ */
+function parseAuthStatus(output) {
+    const trimmed = output.trim();
+    if (trimmed.startsWith('{')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed.loggedIn === 'boolean') {
+                return parsed.loggedIn;
+            }
+        }
+        catch {
+            // Fall through to text heuristic.
+        }
+    }
+    const lower = trimmed.toLowerCase();
+    if (/not logged in|no credentials|unauthenticated|not authenticated/.test(lower)) {
+        return false;
+    }
+    return true;
+}
 /**
  * Check if the `claude` binary is installed (regardless of auth state).
  */
 export function isClaudeBinaryInstalled() {
     try {
-        execClaudeCheck(['--version']);
+        execClaudeCheck(['--version'], VERSION_TIMEOUT_MS);
         return true;
     }
     catch {
@@ -58,16 +96,14 @@ export function isClaudeBinaryInstalled() {
  */
 export function isClaudeCliReady() {
     try {
-        execClaudeCheck(['--version']);
+        execClaudeCheck(['--version'], VERSION_TIMEOUT_MS);
     }
     catch {
         return false;
     }
     try {
-        const output = execClaudeCheck(['auth', 'status'])
-            .toString()
-            .toLowerCase();
-        return !(/not logged in|no credentials|unauthenticated|not authenticated/i.test(output));
+        const output = execClaudeCheck(['auth', 'status', '--json'], AUTH_TIMEOUT_MS).toString();
+        return parseAuthStatus(output);
     }
     catch {
         return false;

package/dist/cli-web-branch.d.ts

@@ -34,6 +34,7 @@ export interface RunWebCliBranchDeps {
     webPreferencesPath?: string;
 }
 export declare function parseCliArgs(argv: string[]): CliFlags;
+export declare function buildHeadlessAutoArgs(flags: Pick<CliFlags, 'messages' | 'model'>): string[];
 export { getProjectSessionsDir } from './project-sessions.js';
 export declare function migrateLegacyFlatSessions(baseSessionsDir: string, projectSessionsDir: string): void;
 /**

package/dist/cli-web-branch.js

@@ -73,6 +73,9 @@ export function parseCliArgs(argv) {
     }
     return flags;
 }
+export function buildHeadlessAutoArgs(flags) {
+    return flags.model ? ['--model', flags.model, ...flags.messages] : [...flags.messages];
+}
 export { getProjectSessionsDir } from './project-sessions.js';
 export function migrateLegacyFlatSessions(baseSessionsDir, projectSessionsDir) {
     if (!existsSync(baseSessionsDir))

package/dist/cli.js

@@ -12,7 +12,8 @@ import { checkForUpdates } from './update-check.js';
 import { printHelp, printSubcommandHelp } from './help-text.js';
 import { applySecurityOverrides } from './security-overrides.js';
 import { validateConfiguredModel } from './startup-model-validation.js';
-import { parseCliArgs, runWebCliBranch, migrateLegacyFlatSessions, } from './cli-web-branch.js';
+import { migrateAnthropicDefaultToClaudeCode } from './provider-migrations.js';
+import { buildHeadlessAutoArgs, parseCliArgs, runWebCliBranch, migrateLegacyFlatSessions, } from './cli-web-branch.js';
 import { stopWebMode } from './web-mode.js';
 import { getProjectSessionsDir } from './project-sessions.js';
 import { markStartup, printStartupTimings } from './startup-timings.js';
@@ -74,6 +75,18 @@ function printExtensionErrors(errors) {
         process.stderr.write(`[gsd] ${prefix}: ${err.error}\n`);
     }
 }
+/**
+ * Print extension load warnings (non-fatal, e.g. missing declared deps from
+ * the topological sort). Complements printExtensionErrors — fatal errors go
+ * there, advisory warnings go here.
+ */
+function printExtensionWarnings(warnings) {
+    if (!warnings)
+        return;
+    for (const w of warnings) {
+        process.stderr.write(`[gsd] Extension warning: ${w.message}\n`);
+    }
+}
 /**
  * Re-apply the validated model to the session when `createAgentSession()`
  * reports that it had to use a fallback. Prevents silently overriding the
@@ -354,11 +367,18 @@ async function runHeadlessFromAuto(headlessArgs) {
     await runHeadless(parseHeadlessArgs(argv));
     process.exit(0);
 }
+function flushPendingProviderRegistrations(resourceLoader, modelRegistry) {
+    const { runtime } = resourceLoader.getExtensions();
+    for (const { name, config } of runtime.pendingProviderRegistrations) {
+        modelRegistry.registerProvider(name, config);
+    }
+    runtime.pendingProviderRegistrations = [];
+}
 // `gsd auto [args...]` — shorthand for `gsd headless auto [args...]` (#2732)
 // Without this, `gsd auto` falls through to the interactive TUI which hangs
 // when stdin/stdout are piped (non-TTY environments).
 if (cliFlags.messages[0] === 'auto') {
-    await runHeadlessFromAuto(cliFlags.messages);
+    await runHeadlessFromAuto(buildHeadlessAutoArgs(cliFlags));
 }
 // Pi's tool bootstrap can mis-detect already-installed fd/rg on some systems
 // because spawnSync(..., ["--version"]) returns EPERM despite a zero exit code.
@@ -492,6 +512,13 @@ if (isPrintMode) {
     });
     await resourceLoader.reload();
     markStartup('resourceLoader.reload');
+    flushPendingProviderRegistrations(resourceLoader, modelRegistry);
+    migrateAnthropicDefaultToClaudeCode({
+        authStorage,
+        isClaudeCodeReady: modelRegistry.isProviderRequestReady('claude-code'),
+        settingsManager,
+        modelRegistry,
+    });
     const { session, extensionsResult, modelFallbackMessage } = await createAgentSession({
         authStorage,
         modelRegistry,
@@ -507,6 +534,7 @@ if (isPrintMode) {
     validateConfiguredModel(modelRegistry, settingsManager);
     await reapplyValidatedModelOnFallback(session, modelRegistry, settingsManager, modelFallbackMessage);
     printExtensionErrors(extensionsResult.errors);
+    printExtensionWarnings(extensionsResult.warnings);
     // Apply --model override if specified
     if (cliFlags.model) {
         const available = modelRegistry.getAvailable();
@@ -629,6 +657,13 @@ const resourceLoadPromise = resourceLoader.reload();
 // Then await the resource promise before creating the agent session.
 await resourceLoadPromise;
 markStartup('resourceLoader.reload');
+flushPendingProviderRegistrations(resourceLoader, modelRegistry);
+migrateAnthropicDefaultToClaudeCode({
+    authStorage,
+    isClaudeCodeReady: modelRegistry.isProviderRequestReady('claude-code'),
+    settingsManager,
+    modelRegistry,
+});
 const { session, extensionsResult, modelFallbackMessage: interactiveFallbackMsg } = await createAgentSession({
     authStorage,
     modelRegistry,
@@ -644,6 +679,7 @@ markStartup('createAgentSession');
 validateConfiguredModel(modelRegistry, settingsManager);
 await reapplyValidatedModelOnFallback(session, modelRegistry, settingsManager, interactiveFallbackMsg);
 printExtensionErrors(extensionsResult.errors);
+printExtensionWarnings(extensionsResult.warnings);
 // Restore scoped models from settings on startup.
 // The upstream InteractiveMode reads enabledModels from settings when /scoped-models is opened,
 // but doesn't apply them to the session at startup — so Ctrl+P cycles all models instead of

package/dist/extension-discovery.d.ts

@@ -16,3 +16,9 @@ export declare function resolveExtensionEntries(dir: string): string[];
  *   pi.extensions, then index.ts/index.js fallback).
  */
 export declare function discoverExtensionEntryPaths(extensionsDir: string): string[];
+/**
+ * Merge bundled and installed extension entry paths.
+ * Installed extensions with the same manifest ID as a bundled extension take precedence (D-14).
+ * Loader stays dumb — receives a pre-merged path list (D-15).
+ */
+export declare function mergeExtensionEntryPaths(bundledPaths: string[], installedExtDir: string): string[];

package/dist/extension-discovery.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { readManifest, readManifestFromEntryPath } from './extension-registry.js';
 function isExtensionFile(name) {
     return name.endsWith('.ts') || name.endsWith('.js');
 }
@@ -69,3 +70,39 @@ export function discoverExtensionEntryPaths(extensionsDir) {
     }
     return discovered;
 }
+/**
+ * Merge bundled and installed extension entry paths.
+ * Installed extensions with the same manifest ID as a bundled extension take precedence (D-14).
+ * Loader stays dumb — receives a pre-merged path list (D-15).
+ */
+export function mergeExtensionEntryPaths(bundledPaths, installedExtDir) {
+    if (!existsSync(installedExtDir))
+        return bundledPaths;
+    // Build map: manifest ID → entry paths for installed extensions
+    const installedById = new Map();
+    for (const entry of readdirSync(installedExtDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = join(installedExtDir, entry.name);
+        const manifest = readManifest(dir);
+        const entries = resolveExtensionEntries(dir);
+        if (manifest && entries.length > 0) {
+            installedById.set(manifest.id, entries);
+        }
+    }
+    if (installedById.size === 0)
+        return bundledPaths;
+    // Filter bundled paths: skip any whose manifest id is shadowed by installed
+    const merged = [];
+    for (const entryPath of bundledPaths) {
+        const manifest = readManifestFromEntryPath(entryPath);
+        if (manifest && installedById.has(manifest.id))
+            continue; // shadowed by installed
+        merged.push(entryPath);
+    }
+    // Append all installed entries
+    for (const entries of installedById.values()) {
+        merged.push(...entries);
+    }
+    return merged;
+}

package/dist/extension-registry.d.ts

@@ -31,6 +31,9 @@ export interface ExtensionRegistryEntry {
     source: "bundled" | "user" | "project";
     disabledAt?: string;
     disabledReason?: string;
+    version?: string;
+    installedFrom?: string;
+    installType?: "npm" | "git" | "local";
 }
 export interface ExtensionRegistry {
     version: 1;

package/dist/extension-sort.d.ts

@@ -0,0 +1,18 @@
+export interface SortWarning {
+    declaringId: string;
+    missingId: string;
+    message: string;
+}
+export interface SortResult {
+    sortedPaths: string[];
+    warnings: SortWarning[];
+}
+/**
+ * Sort extension entry paths in topological dependency-first order using Kahn's BFS algorithm.
+ *
+ * - Extensions without manifests are prepended in input order.
+ * - Missing dependencies produce a structured warning but do not block loading.
+ * - Cycles produce warnings; cycle participants are appended alphabetically.
+ * - Self-dependencies are silently ignored.
+ */
+export declare function sortExtensionPaths(paths: string[]): SortResult;

package/dist/extension-sort.js

@@ -0,0 +1,114 @@
+// GSD-2 — Extension Sort: Topological dependency ordering
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+import { readManifestFromEntryPath } from './extension-registry.js';
+/**
+ * Sort extension entry paths in topological dependency-first order using Kahn's BFS algorithm.
+ *
+ * - Extensions without manifests are prepended in input order.
+ * - Missing dependencies produce a structured warning but do not block loading.
+ * - Cycles produce warnings; cycle participants are appended alphabetically.
+ * - Self-dependencies are silently ignored.
+ */
+export function sortExtensionPaths(paths) {
+    const warnings = [];
+    const pathsWithoutId = [];
+    const idToPath = new Map();
+    // Step 1: Build ID map
+    for (const path of paths) {
+        const manifest = readManifestFromEntryPath(path);
+        if (!manifest) {
+            pathsWithoutId.push(path);
+        }
+        else {
+            idToPath.set(manifest.id, path);
+        }
+    }
+    // Step 2: Build graph — inDegree and dependents adjacency
+    const inDegree = new Map();
+    const dependents = new Map(); // dep → [ids that depend on dep]
+    for (const id of idToPath.keys()) {
+        if (!inDegree.has(id))
+            inDegree.set(id, 0);
+        if (!dependents.has(id))
+            dependents.set(id, []);
+    }
+    for (const [id, path] of idToPath) {
+        const manifest = readManifestFromEntryPath(path);
+        const rawDeps = manifest?.dependencies?.extensions ?? [];
+        const deps = Array.isArray(rawDeps) ? rawDeps : [];
+        for (const depId of deps) {
+            // Silently ignore self-deps
+            if (depId === id)
+                continue;
+            if (!idToPath.has(depId)) {
+                // Missing dependency — warn and skip edge
+                warnings.push({
+                    declaringId: id,
+                    missingId: depId,
+                    message: `Extension '${id}' declares dependency '${depId}' which is not installed — loading anyway`,
+                });
+                continue;
+            }
+            // Valid edge: id depends on depId → increment inDegree[id], add id to dependents[depId]
+            inDegree.set(id, (inDegree.get(id) ?? 0) + 1);
+            const depDependents = dependents.get(depId) ?? [];
+            depDependents.push(id);
+            dependents.set(depId, depDependents);
+        }
+    }
+    // Step 3: Kahn's algorithm — start with nodes that have inDegree 0
+    const sorted = [];
+    // Ready queue: IDs with inDegree 0, maintained in alphabetical order
+    const ready = [...idToPath.keys()]
+        .filter(id => inDegree.get(id) === 0)
+        .sort();
+    while (ready.length > 0) {
+        const id = ready.shift();
+        sorted.push(idToPath.get(id));
+        const deps = dependents.get(id) ?? [];
+        for (const depId of deps) {
+            const newDegree = (inDegree.get(depId) ?? 0) - 1;
+            inDegree.set(depId, newDegree);
+            if (newDegree === 0) {
+                // Insert into ready queue maintaining alphabetical order
+                const insertIdx = ready.findIndex(r => r > depId);
+                if (insertIdx === -1) {
+                    ready.push(depId);
+                }
+                else {
+                    ready.splice(insertIdx, 0, depId);
+                }
+            }
+        }
+    }
+    // Step 4: Cycle handling — any remaining IDs with inDegree > 0
+    const cycleIds = [...idToPath.keys()]
+        .filter(id => (inDegree.get(id) ?? 0) > 0)
+        .sort();
+    if (cycleIds.length > 0) {
+        const cycleSet = new Set(cycleIds);
+        for (const id of cycleIds) {
+            const path = idToPath.get(id);
+            const manifest = readManifestFromEntryPath(path);
+            const rawDeps = manifest?.dependencies?.extensions ?? [];
+            const deps = Array.isArray(rawDeps) ? rawDeps : [];
+            for (const depId of deps) {
+                if (depId === id)
+                    continue;
+                if (!cycleSet.has(depId))
+                    continue;
+                // Both id and depId are in cycle — emit warning
+                warnings.push({
+                    declaringId: id,
+                    missingId: depId,
+                    message: `Extension '${id}' and '${depId}' form a dependency cycle — loading both anyway (alphabetical order)`,
+                });
+            }
+            sorted.push(path);
+        }
+    }
+    return {
+        sortedPaths: [...pathsWithoutId, ...sorted],
+        warnings,
+    };
+}

package/dist/extension-validator.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Install-time validator for GSD extension packages. Called by the install command
+ * (Phase 8) before writing files. Not called on bundled extensions — they are
+ * discovered at load time, not installed.
+ */
+export interface ValidationError {
+    code: string;
+    message: string;
+    field?: string;
+}
+export interface ValidationWarning {
+    code: string;
+    message: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+export interface ValidationOptions {
+    allowGsdNamespace?: boolean;
+    extensionId?: string;
+}
+/**
+ * Per D-03: Check that pkg.gsd.extension === true with STRICT equality (not truthiness).
+ * Packages without this marker are not recognized as GSD extensions.
+ */
+export declare function checkInstallDiscriminator(pkg: unknown): ValidationError | null;
+/**
+ * Per D-04/D-05: Check that the extension ID does not use the reserved gsd.* namespace,
+ * unless allowGsdNamespace is explicitly set to true.
+ * Per D-06: Only checks extension manifest ID — not pkg.name.
+ */
+export declare function checkNamespaceReservation(extensionId: string, opts: ValidationOptions): ValidationError | null;
+/**
+ * Per D-07/D-08/D-09/D-10: Scan both `dependencies` and `devDependencies` for @gsd/* packages.
+ * peerDependencies is the correct placement and is NOT flagged.
+ * Returns an error per violation naming the exact field and package.
+ */
+export declare function checkDependencyPlacement(pkg: unknown): ValidationError[];
+/**
+ * Run all validation checks for a GSD extension package.json.
+ * - If opts.extensionId is provided, runs namespace reservation check.
+ * - If opts.extensionId is not provided, skips namespace check and adds a warning.
+ * - valid is ALWAYS derived as errors.length === 0.
+ */
+export declare function validateExtensionPackage(pkg: unknown, opts?: ValidationOptions): ValidationResult;