@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.5fc22c6f

package/README.md

@@ -19,7 +19,7 @@ It combines a terminal agent, project workflow tools, worktree-aware Git automat
 - **Autonomous project workflow** — Break work into milestones, slices, and tasks, then let auto mode plan, implement, verify, and advance.
 - **Worktree-aware Git automation** — Keep implementation work isolated while preserving a reviewable main checkout.
 - **Local project memory** — Store project requirements, decisions, runtime notes, generated plans, summaries, and validation evidence under `.gsd/`.
-- **Multi-provider model routing** — Use the provider your team already has, with configurable defaults and per-phase model preferences.
+- **Multi-provider model routing** — Use the provider your team already has, including API keys, OAuth providers, and external CLI providers such as Claude Code and Cursor Agent.
 - **Extension surface** — Add project-specific commands, tools, skills, and UI integrations through bundled or community extensions.
 - **Terminal and web surfaces** — Use the TUI by default, or launch `gsd --web` when a visual control plane fits the work better than a terminal.
 
@@ -28,16 +28,16 @@ See [CHANGELOG.md](./CHANGELOG.md) for release-by-release fixes and [Legacy Rele
 ## Latest Release Highlights
 
 <!-- release-highlights:start -->
-Latest release: **v1.3.0**
+Latest release: **v1.4.0**
 
-- **update:** Reconcile stale PATH gsd-browser binary after install.
-- **gsd:** Route UAT sign-off and worktree-degradation blockers through the guidance catalog.
-- **gsd:** Fix shell-tool selection — uncapped sync bash, interruptible await, graceful kills.
-- **browser-tools:** Proven engine resolution — gsd-browser primary for web apps (ADR-037).
-- **gsd:** Add the Unit Closeout module with the Interactive Closeout adapter (ADR-032).
-- **gsd:** Tool Surface Readiness gate — verify live tool surface at SDK init before the first model turn.
-- **claude-code-cli:** Expose Claude Fable 5 as an Opus-tier model.
-- **pi-ai:** Add Claude Fable 5 with Opus-tier thinking.
+- **models:** Add Claude Sonnet 5.
+- **Added:** Add Hermes plugin installer.
+- **compat:** Report .planning/ drift in /gsd sync and doctor.
+- **compat:** Project to .planning/ inside renderAllFromDb.
+- **compat:** Add external-planning-edit drift handler.
+- **compat:** Add DB → .planning/ projection writer.
+- **compat:** Extract .planning/ layout detector.
+- **compat:** Extend marker schema 1→2 with planning field.
 
 <!-- release-highlights:end -->
 
@@ -158,7 +158,7 @@ Need help choosing settings? Use the [GSD Pi web configurator](https://pi.opengs
 gsd
 ```
 
-Run the setup flow, choose your preferred model provider, and open a project directory. GSD stores project planning and runtime state in `.gsd/`.
+Run the setup flow, choose your preferred model provider, and open a project directory. Cursor Agent users can choose the `cursor-agent` provider after installing and authenticating the local `cursor-agent` CLI; its default model is `composer-2.5`, and `CURSOR_API_KEY` is supported as an auth signal. GSD stores project planning and runtime state in `.gsd/`, with gitignored sibling runtime directories such as `.gsd-backups/` for migration snapshots. Stale `.gsd-backups/migrate-*` snapshots are pruned after 30 days once the flat-phase `.gsd/phases/` migration is complete.
 
 For a full first-run walkthrough, see [Getting Started With gsd-pi](./docs/user-docs/getting-started.md).
 

package/dist/cli.js

@@ -22,15 +22,23 @@ import { markStartup, printStartupTimings } from './startup-timings.js';
 import { applyRtkProcessEnv, GSD_RTK_DISABLED_ENV, isTruthy } from './rtk-shared.js';
 let piCodingAgentModulePromise;
 let agentCoreModulePromise;
-let agentModesModulePromise;
+let interactiveModeModulePromise;
+let printModeModulePromise;
+let rpcModeModulePromise;
 function loadPiCodingAgentModule() {
     return (piCodingAgentModulePromise ??= import('@gsd/pi-coding-agent'));
 }
 function loadAgentCoreModule() {
     return (agentCoreModulePromise ??= import('@gsd/agent-core'));
 }
-function loadAgentModesModule() {
-    return (agentModesModulePromise ??= import('@gsd/agent-modes'));
+function loadInteractiveModeModule() {
+    return (interactiveModeModulePromise ??= import('@gsd/agent-modes/modes/interactive/interactive-mode.js'));
+}
+function loadPrintModeModule() {
+    return (printModeModulePromise ??= import('@gsd/agent-modes/modes/print-mode.js'));
+}
+function loadRpcModeModule() {
+    return (rpcModeModulePromise ??= import('@gsd/agent-modes/modes/rpc/rpc-mode.js'));
 }
 // ---------------------------------------------------------------------------
 // V8 compile cache — Node 22+ can cache compiled bytecode across runs,
@@ -194,6 +202,14 @@ if (shouldBypassManagedResourceMismatchGate(cliFlags.messages[0])) {
     process.exit(0);
 }
 // ---------------------------------------------------------------------------
+// Hermes integration subcommand — `gsd hermes install`
+// ---------------------------------------------------------------------------
+if (cliFlags.messages[0] === 'hermes') {
+    const { runHermesIntegrationCommand } = await import('./hermes-integration-install.js');
+    const exitCode = await runHermesIntegrationCommand(process.argv);
+    process.exit(exitCode);
+}
+// ---------------------------------------------------------------------------
 // Graph subcommand — `gsd graph build|status|query|diff`
 // ---------------------------------------------------------------------------
 if (cliFlags.messages[0] === 'graph') {
@@ -291,6 +307,8 @@ const subcommandsExemptFromEarlyTtyCheck = new Set([
     'config',
     'graph',
     'headless',
+    'hermes',
+    'read',
     'install',
     'list',
     'remove',
@@ -409,6 +427,11 @@ if (cliFlags.messages[0] === 'sessions') {
     cliFlags.continue = true;
     cliFlags._selectedSessionPath = selected.path;
 }
+// `gsd read` — JSON read seam for integrations (Hermes 6c)
+if (cliFlags.messages[0] === 'read') {
+    const { runReadCli } = await import('./read-cli.js');
+    process.exit(await runReadCli(process.argv));
+}
 // `gsd headless` — run auto-mode without TUI
 if (cliFlags.messages[0] === 'headless') {
     await ensureRtkBootstrap();
@@ -496,7 +519,6 @@ if (!isPrintMode &&
 }
 const { AuthStorage, DefaultResourceLoader, ModelRegistry, SettingsManager, SessionManager, } = await loadPiCodingAgentModule();
 const { createAgentSession } = await loadAgentCoreModule();
-const { InteractiveMode, runPrintMode, runRpcMode } = await loadAgentModesModule();
 markStartup('loadPiCodingAgent');
 // Pi's tool bootstrap can mis-detect already-installed fd/rg on some systems
 // because spawnSync(..., ["--version"]) returns EPERM despite a zero exit code.
@@ -515,6 +537,9 @@ markStartup('ModelRegistry');
 const settingsManager = SettingsManager.create(process.cwd(), agentDir);
 applySecurityOverrides(settingsManager);
 markStartup('SettingsManager.create');
+const { configureHttpDispatcher } = await import('@gsd/pi-coding-agent/core/http-dispatcher.js');
+configureHttpDispatcher(settingsManager.getHttpIdleTimeoutMs());
+markStartup('configureHttpDispatcher');
 // Run onboarding wizard on first launch (no LLM provider configured)
 if (!isPrintMode && shouldRunOnboarding(authStorage, settingsManager.getDefaultProvider())) {
     await runOnboarding(authStorage);
@@ -636,6 +661,7 @@ if (isPrintMode) {
     applyModelOverride(session, modelRegistry, cliFlags.model);
     const mode = cliFlags.mode || 'text';
     if (mode === 'rpc') {
+        const { runRpcMode } = await loadRpcModeModule();
         printStartupTimings();
         await runRpcMode(session);
         process.exit(0);
@@ -659,6 +685,7 @@ if (isPrintMode) {
         // MCP server runs until the transport closes; keep alive
         await new Promise(() => { });
     }
+    const { runPrintMode } = await loadPrintModeModule();
     printStartupTimings();
     await runPrintMode(session, {
         mode: mode,
@@ -794,6 +821,7 @@ if (!process.stdin.isTTY || !process.stdout.isTTY) {
             : 'stdout is';
     printNonTtyErrorAndExit(missing, true);
 }
+const { InteractiveMode } = await loadInteractiveModeModule();
 const interactiveMode = new InteractiveMode(session);
 markStartup('InteractiveMode');
 printStartupTimings();

package/dist/headless-answers.js

@@ -6,7 +6,7 @@
  * default auto-responder or supervised mode.
  */
 import { readFileSync } from 'node:fs';
-import { serializeJsonLine } from '@gsd/agent-modes';
+import { serializeJsonLine } from '@gsd/agent-modes/modes/rpc/jsonl.js';
 import { canonicalHeadlessToolName } from './headless-events.js';
 export function normalizeQuestionId(id) {
     return id.trim().toLowerCase().replace(/[-\s]+/g, '_').replace(/_confirm$/, '');

package/dist/headless-context.js

@@ -39,6 +39,5 @@ export async function loadContext(options) {
  */
 export function bootstrapGsdProject(basePath) {
     const gsdDir = join(basePath, '.gsd');
-    mkdirSync(join(gsdDir, 'milestones'), { recursive: true });
     mkdirSync(join(gsdDir, 'runtime'), { recursive: true });
 }

package/dist/headless-ui.d.ts

@@ -5,7 +5,7 @@
  * formats progress events for stderr output, and reads orchestrator
  * commands from stdin in supervised mode.
  */
-import { RpcClient } from '@gsd/agent-modes';
+import type { RpcClient } from '@gsd/agent-modes/modes/rpc/rpc-client.js';
 interface ExtensionUIRequest {
     type: 'extension_ui_request';
     id: string;

package/dist/headless-ui.js

@@ -5,7 +5,7 @@
  * formats progress events for stderr output, and reads orchestrator
  * commands from stdin in supervised mode.
  */
-import { attachJsonlLineReader } from '@gsd/agent-modes';
+import { attachJsonlLineReader } from '@gsd/agent-modes/modes/rpc/jsonl.js';
 // ---------------------------------------------------------------------------
 // ANSI Color Helpers
 // ---------------------------------------------------------------------------

package/dist/headless.js

@@ -14,7 +14,7 @@
 import { existsSync, mkdirSync, writeFileSync, writeSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolve } from 'node:path';
-import { RpcClient } from '@gsd/agent-modes';
+import { RpcClient } from '@gsd/agent-modes/modes/rpc/rpc-client.js';
 import { SessionManager } from '@gsd/pi-coding-agent';
 import { getProjectSessionsDir } from './project-sessions.js';
 import { loadAndValidateAnswerFile, AnswerInjector } from './headless-answers.js';

package/dist/help-text.js

@@ -122,6 +122,34 @@ const SUBCOMMAND_HELP = {
         '  gsd graph query auth                   Find nodes related to "auth"',
         '  gsd graph diff                         Show changes since last snapshot',
     ].join('\n'),
+    hermes: [
+        'Usage: gsd hermes install [options]',
+        '',
+        'Install the bundled open-gsd-hermes plugin into Hermes Agent.',
+        '',
+        'Options:',
+        '  --hermes-home <path>    Hermes home (default: $HERMES_HOME or ~/.hermes)',
+        '  --project <path>        Default GSD project to write into gsd.yaml',
+        '  --plugin-source <path>  Override bundled integrations/hermes source',
+        '  --skip-pip             Copy plugin only; do not pip install editable package',
+        '  --skip-enable          Do not run hermes plugins enable',
+        '  --dry-run              Print intended actions without writing',
+        '',
+        'Examples:',
+        '  gsd hermes install --project ~/code/myapp',
+        '  HERMES_HOME=~/.hermes gsd hermes install --skip-enable',
+    ].join('\n'),
+    read: [
+        'Usage: gsd read <progress|roadmap|memory> --json --project <path>',
+        '',
+        'JSON read seam for external integrations (e.g. open-gsd-hermes).',
+        'Emits envelope: { integration_version, kind, projectDir, data }.',
+        '',
+        'Examples:',
+        '  gsd read progress --json --project ~/code/myapp',
+        '  gsd read roadmap --json --project ~/code/myapp --milestone M001',
+        '  gsd read memory --json --project ~/code/myapp --query auth',
+    ].join('\n'),
     headless: [
         'Usage: gsd headless [flags] [command] [args...]',
         '',
@@ -211,6 +239,7 @@ export function printHelp(version) {
     process.stdout.write('  auto [args]              Run auto-mode without TUI (pipeable)\n');
     process.stdout.write('  headless [cmd] [args]    Run /gsd commands without TUI (default: auto)\n');
     process.stdout.write('  graph <subcommand>       Manage knowledge graph (build, query, status, diff)\n');
+    process.stdout.write('  hermes install           Install the Hermes Agent plugin\n');
     process.stdout.write('\nRun gsd <subcommand> --help for subcommand-specific help.\n');
 }
 export function printSubcommandHelp(subcommand, version) {

package/dist/hermes-integration-install.d.ts

@@ -0,0 +1,17 @@
+export interface HermesInstallOptions {
+    hermesHome: string;
+    pluginSource: string;
+    project?: string;
+    dryRun: boolean;
+    skipPip: boolean;
+    skipEnable: boolean;
+}
+export interface HermesInstallResult {
+    pluginTarget: string;
+    configPath: string;
+    actions: string[];
+    warnings: string[];
+}
+export declare function runHermesIntegrationCommand(argv: string[]): Promise<number>;
+export declare function parseHermesInstallArgs(args: string[]): HermesInstallOptions;
+export declare function installHermesPlugin(options: HermesInstallOptions): HermesInstallResult;

package/dist/hermes-integration-install.js

@@ -0,0 +1,199 @@
+import { existsSync, mkdirSync, rmSync, cpSync, writeFileSync, readFileSync } from 'node:fs';
+import { dirname, resolve, join, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+const PLUGIN_NAME = 'open-gsd-hermes';
+export async function runHermesIntegrationCommand(argv) {
+    const hermesIndex = argv.indexOf('hermes', 2);
+    if (hermesIndex === -1) {
+        printHermesHelp();
+        return 0;
+    }
+    const sub = argv[hermesIndex + 1];
+    if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
+        printHermesHelp();
+        return 0;
+    }
+    if (sub !== 'install') {
+        process.stderr.write(`[gsd] Unknown hermes command: ${sub}\n`);
+        printHermesHelp(process.stderr);
+        return 1;
+    }
+    let options;
+    try {
+        options = parseHermesInstallArgs(argv.slice(hermesIndex + 2));
+    }
+    catch (err) {
+        process.stderr.write(`[gsd] hermes install: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    try {
+        const result = installHermesPlugin(options);
+        for (const action of result.actions)
+            process.stdout.write(`✓ ${action}\n`);
+        for (const warning of result.warnings)
+            process.stderr.write(`[gsd] Warning: ${warning}\n`);
+        process.stdout.write(`\nHermes plugin installed at: ${result.pluginTarget}\n`);
+        process.stdout.write(`Config path: ${result.configPath}\n`);
+        process.stdout.write('Next: restart Hermes/gateway, then run `hermes plugins list` and `/gsd status`.\n');
+        return 0;
+    }
+    catch (err) {
+        process.stderr.write(`[gsd] hermes install failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+}
+export function parseHermesInstallArgs(args) {
+    let hermesHome = process.env.HERMES_HOME || join(homedir(), '.hermes');
+    let pluginSource = process.env.GSD_HERMES_PLUGIN_SOURCE || findBundledHermesPluginSource();
+    let project;
+    let dryRun = false;
+    let skipPip = false;
+    let skipEnable = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const next = () => {
+            const value = args[++i];
+            if (!value)
+                throw new Error(`${arg} requires a value`);
+            return value;
+        };
+        if (arg === '--hermes-home')
+            hermesHome = next();
+        else if (arg === '--plugin-source')
+            pluginSource = next();
+        else if (arg === '--project')
+            project = next();
+        else if (arg === '--dry-run')
+            dryRun = true;
+        else if (arg === '--skip-pip')
+            skipPip = true;
+        else if (arg === '--skip-enable')
+            skipEnable = true;
+        else
+            throw new Error(`unknown option: ${arg}`);
+    }
+    return {
+        hermesHome: expandHome(hermesHome),
+        pluginSource: expandHome(pluginSource),
+        project: project ? resolve(expandHome(project)) : undefined,
+        dryRun,
+        skipPip,
+        skipEnable,
+    };
+}
+export function installHermesPlugin(options) {
+    const source = resolve(options.pluginSource);
+    if (!existsSync(join(source, 'plugin.yaml'))) {
+        throw new Error(`plugin source does not contain plugin.yaml: ${source}`);
+    }
+    const hermesHome = resolve(options.hermesHome);
+    const pluginRoot = join(hermesHome, 'plugins');
+    const pluginTarget = join(pluginRoot, PLUGIN_NAME);
+    const configPath = join(hermesHome, 'gsd.yaml');
+    const actions = [];
+    const warnings = [];
+    if (!options.dryRun) {
+        mkdirSync(pluginRoot, { recursive: true });
+        if (existsSync(pluginTarget)) {
+            rmSync(pluginTarget, { recursive: true, force: true });
+        }
+        cpSync(source, pluginTarget, {
+            recursive: true,
+            filter: (src) => !src.includes('__pycache__') && !src.includes('.pytest_cache'),
+        });
+    }
+    actions.push(`${options.dryRun ? 'Would copy' : 'Copied'} ${PLUGIN_NAME} into Hermes plugin directory`);
+    const config = renderGsdYaml(options.project);
+    if (!existsSync(configPath)) {
+        if (!options.dryRun)
+            writeFileSync(configPath, config, 'utf8');
+        actions.push(`${options.dryRun ? 'Would create' : 'Created'} ${configPath}`);
+    }
+    else if (!readFileSync(configPath, 'utf8').includes('gsd:')) {
+        warnings.push(`${configPath} exists but does not contain a gsd: section; merge the sample config from ${pluginTarget}/docs/setup.md`);
+    }
+    else {
+        actions.push(`Left existing ${configPath} unchanged`);
+    }
+    if (!options.skipPip) {
+        const python = findHermesPython(hermesHome);
+        const pipArgs = ['-m', 'pip', 'install', '-e', pluginTarget];
+        if (options.dryRun) {
+            actions.push(`Would run ${python} ${pipArgs.join(' ')}`);
+        }
+        else {
+            const pip = spawnSync(python, pipArgs, { stdio: 'pipe', encoding: 'utf8' });
+            if (pip.status !== 0) {
+                warnings.push(`Python package install failed with ${python}; Hermes may not import the plugin until you run: ${python} ${pipArgs.join(' ')}`);
+                if (pip.stderr.trim())
+                    warnings.push(pip.stderr.trim().split('\n').slice(-3).join(' | '));
+            }
+            else {
+                actions.push('Installed Python package into Hermes environment');
+            }
+        }
+    }
+    if (!options.skipEnable) {
+        if (options.dryRun) {
+            actions.push(`Would run HERMES_HOME=${hermesHome} hermes plugins enable ${PLUGIN_NAME}`);
+        }
+        else {
+            const enable = spawnSync('hermes', ['plugins', 'enable', PLUGIN_NAME], {
+                stdio: 'pipe',
+                encoding: 'utf8',
+                env: { ...process.env, HERMES_HOME: hermesHome },
+            });
+            if (enable.status !== 0) {
+                warnings.push(`Could not auto-enable plugin; run manually: HERMES_HOME=${hermesHome} hermes plugins enable ${PLUGIN_NAME}`);
+            }
+            else {
+                actions.push('Enabled plugin in Hermes');
+            }
+        }
+    }
+    return { pluginTarget, configPath, actions, warnings };
+}
+function quoteYamlScalar(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function renderGsdYaml(project) {
+    const defaultProject = project ?? '~/code/myapp';
+    return `# open-gsd-hermes configuration. Edit paths for your machine.\ngsd:\n  cli_path: gsd\n  mcp_server_path: gsd-mcp-server\n  credential_source: gsd\n  default_project: ${quoteYamlScalar(defaultProject)}\n  poll_interval_seconds: 12\n  cache_ttl_seconds: 45\n  notification_level: normal\n  bindings: {}\n`;
+}
+function findHermesPython(hermesHome) {
+    const suffix = process.platform === 'win32' ? join('Scripts', 'python.exe') : join('bin', 'python');
+    const bundled = join(hermesHome, 'hermes-agent', 'venv', suffix);
+    if (existsSync(bundled))
+        return bundled;
+    return process.env.PYTHON || 'python3';
+}
+function findBundledHermesPluginSource() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(process.cwd(), 'integrations/hermes'),
+        resolve(here, '../integrations/hermes'),
+        resolve(here, '../../integrations/hermes'),
+    ];
+    const found = candidates.find((candidate) => existsSync(join(candidate, 'plugin.yaml')));
+    return found ?? candidates[0];
+}
+function expandHome(value) {
+    if (value === '~')
+        return homedir();
+    if (value.startsWith('~/'))
+        return join(homedir(), value.slice(2));
+    return isAbsolute(value) ? value : resolve(value);
+}
+function printHermesHelp(stream = process.stdout) {
+    stream.write('Usage: gsd hermes install [options]\n');
+    stream.write('\nInstall the bundled open-gsd-hermes plugin into a Hermes Agent home.\n\n');
+    stream.write('Options:\n');
+    stream.write('  --hermes-home <path>    Hermes home (default: $HERMES_HOME or ~/.hermes)\n');
+    stream.write('  --project <path>        Default GSD project to write into gsd.yaml\n');
+    stream.write('  --plugin-source <path>  Override bundled integrations/hermes source\n');
+    stream.write('  --skip-pip             Copy plugin only; do not pip install editable package\n');
+    stream.write('  --skip-enable          Do not run hermes plugins enable\n');
+    stream.write('  --dry-run              Print intended actions without writing\n');
+}

package/dist/jiti-workspace-aliases.d.ts

@@ -1,2 +1,11 @@
-/** jiti alias map for @gsd/* workspace packages (CJS require cannot load ESM file:// URLs). */
-export declare function getJitiWorkspaceAliases(importUrl: string): Record<string, string>;
+export type FileExists = (path: string) => boolean;
+/**
+ * jiti alias map for @gsd/* workspace packages (CJS require cannot load ESM file:// URLs).
+ *
+ * In the monorepo the canonical entry points are raw TypeScript under `packages/<name>/src/`,
+ * which jiti loads directly. The published tarball ships only the compiled `packages/<name>/dist/`
+ * (see each package's `files` field) — `src/` is absent. Resolve each alias to the `src/*.ts`
+ * entry when present, otherwise fall back to the compiled `dist/*.js`, so the merge CLI loads in
+ * both layouts instead of crashing with MODULE_NOT_FOUND on the missing source path.
+ */
+export declare function getJitiWorkspaceAliases(importUrl: string, fileExists?: FileExists): Record<string, string>;

package/dist/jiti-workspace-aliases.js

@@ -1,9 +1,25 @@
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { resolvePackageRoot } from "./bundled-resource-path.js";
-/** jiti alias map for @gsd/* workspace packages (CJS require cannot load ESM file:// URLs). */
-export function getJitiWorkspaceAliases(importUrl) {
+/**
+ * jiti alias map for @gsd/* workspace packages (CJS require cannot load ESM file:// URLs).
+ *
+ * In the monorepo the canonical entry points are raw TypeScript under `packages/<name>/src/`,
+ * which jiti loads directly. The published tarball ships only the compiled `packages/<name>/dist/`
+ * (see each package's `files` field) — `src/` is absent. Resolve each alias to the `src/*.ts`
+ * entry when present, otherwise fall back to the compiled `dist/*.js`, so the merge CLI loads in
+ * both layouts instead of crashing with MODULE_NOT_FOUND on the missing source path.
+ */
+export function getJitiWorkspaceAliases(importUrl, fileExists = existsSync) {
     const root = resolvePackageRoot(importUrl);
-    const pkg = (dir, ...segments) => join(root, "packages", dir, "src", ...segments);
+    // Prefer the source `.ts` entry (monorepo); fall back to the compiled `.js` (published tarball).
+    const pkg = (dir, ...segments) => {
+        const srcEntry = join(root, "packages", dir, "src", ...segments);
+        if (fileExists(srcEntry))
+            return srcEntry;
+        const distSegments = segments.map((s) => s.replace(/\.ts$/, ".js"));
+        return join(root, "packages", dir, "dist", ...distSegments);
+    };
     const piAi = pkg("pi-ai", "index.ts");
     const piAiOauth = pkg("pi-ai", "utils", "oauth", "index.ts");
     const piAgentCore = pkg("pi-agent-core", "index.ts");

package/dist/onboarding.js

@@ -16,6 +16,7 @@ import { renderGsdPiLogo, GSD_PI_BRAND, GSD_WEBSITE } from './logo.js';
 import { agentDir } from './app-paths.js';
 import { isClaudeCliReady } from './claude-cli-check.js';
 import { isAntigravityCliReady, isGeminiCliReady } from './resources/extensions/google-cli/readiness.js';
+import { isCursorAgentReady } from './resources/extensions/cursor-cli/readiness.js';
 import { markOnboardingComplete, markStepCompleted, markStepSkipped, isOnboardingComplete, } from './resources/extensions/gsd/onboarding-state.js';
 import { getLlmProviderIds } from './resources/extensions/gsd/setup-catalog.js';
 // ─── Constants ────────────────────────────────────────────────────────────────
@@ -359,6 +360,9 @@ export async function runLlmStep(p, pc, authStorage) {
     if (isClaudeCliReady()) {
         authOptions.push({ value: 'claude-cli', label: 'Use Claude Code CLI', hint: 'uses your existing Claude subscription' });
     }
+    if (isCursorAgentReady()) {
+        authOptions.push({ value: 'cursor-agent-cli', label: 'Use Cursor Agent', hint: 'uses your existing Cursor subscription' });
+    }
     if (isAntigravityCliReady()) {
         authOptions.push({ value: 'antigravity-cli', label: 'Use Antigravity CLI', hint: 'recommended — replaces Gemini CLI for individuals' });
     }
@@ -388,6 +392,13 @@ export async function runLlmStep(p, pc, authStorage) {
         persistDefaultProvider('claude-code');
         return true;
     }
+    if (method === 'cursor-agent-cli') {
+        p.log.success('Cursor Agent detected — routing through local CLI');
+        p.log.info('Your Cursor subscription will be used for inference. No API key needed.');
+        authStorage.set('cursor-agent', { type: 'api_key', key: 'cli' });
+        persistDefaultProvider('cursor-agent');
+        return true;
+    }
     if (method === 'gemini-cli') {
         p.log.warn('Google Gemini CLI is deprecated for individual users — install Antigravity: https://antigravity.google');
         p.log.success('Google Gemini CLI detected — routing through local CLI');

package/dist/read-cli.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `gsd read` — JSON read seam for integrations (Hermes 6c).
+ *
+ *   gsd read progress --json --project /path
+ *   gsd read roadmap --json --project /path [--milestone M001]
+ *   gsd read memory --json --project /path --query "auth"
+ */
+export declare const INTEGRATION_VERSION = 1;
+export type ReadKind = 'progress' | 'roadmap' | 'memory';
+export interface ReadEnvelope<T = unknown> {
+    integration_version: number;
+    kind: ReadKind;
+    projectDir: string;
+    data: T;
+}
+export interface ReadCliOptions {
+    kind: ReadKind;
+    project: string;
+    milestone?: string;
+    query?: string;
+    json: boolean;
+}
+export declare function runReadCli(argv: string[]): Promise<number>;

package/dist/read-cli.js

@@ -0,0 +1,90 @@
+/**
+ * `gsd read` — JSON read seam for integrations (Hermes 6c).
+ *
+ *   gsd read progress --json --project /path
+ *   gsd read roadmap --json --project /path [--milestone M001]
+ *   gsd read memory --json --project /path --query "auth"
+ */
+import { resolve } from 'node:path';
+import { graphQuery } from '@opengsd/mcp-server/readers/graph';
+import { resolveGsdRoot } from '@opengsd/mcp-server/readers/paths';
+import { readRoadmap } from '@opengsd/mcp-server/readers/roadmap';
+import { readProgress } from '@opengsd/mcp-server/readers/state';
+export const INTEGRATION_VERSION = 1;
+function parseReadArgs(argv) {
+    const readIndex = argv.indexOf('read', 2);
+    if (readIndex === -1)
+        return null;
+    const args = argv.slice(readIndex + 1);
+    if (args.length < 1)
+        return null;
+    const kind = args[0];
+    if (!['progress', 'roadmap', 'memory'].includes(kind))
+        return null;
+    let project;
+    let milestone;
+    let query;
+    let json = false;
+    for (let i = 1; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--json')
+            json = true;
+        else if (a === '--project' && i + 1 < args.length)
+            project = args[++i];
+        else if (a === '--milestone' && i + 1 < args.length)
+            milestone = args[++i];
+        else if (a === '--query' && i + 1 < args.length)
+            query = args[++i];
+    }
+    if (!project)
+        return null;
+    return { kind, project, milestone, query, json };
+}
+export async function runReadCli(argv) {
+    const opts = parseReadArgs(argv);
+    if (!opts) {
+        process.stderr.write('Usage: gsd read <progress|roadmap|memory> --json --project <path> [--milestone M001] [--query text]\n');
+        return 1;
+    }
+    const projectDir = resolve(opts.project);
+    try {
+        resolveGsdRoot(projectDir);
+    }
+    catch (err) {
+        process.stderr.write(`[gsd read] ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    let data;
+    switch (opts.kind) {
+        case 'progress':
+            data = readProgress(projectDir);
+            break;
+        case 'roadmap':
+            data = readRoadmap(projectDir, opts.milestone);
+            break;
+        case 'memory': {
+            const term = opts.query?.trim() || '';
+            if (term.length < 2) {
+                process.stderr.write('[gsd read] memory requires --query with at least 2 characters\n');
+                return 1;
+            }
+            data = await graphQuery(projectDir, term);
+            break;
+        }
+        default:
+            return 1;
+    }
+    const envelope = {
+        integration_version: INTEGRATION_VERSION,
+        kind: opts.kind,
+        projectDir,
+        data,
+    };
+    if (opts.json) {
+        process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+    }
+    else {
+        process.stdout.write(JSON.stringify(envelope.data, null, 2) + '\n');
+    }
+    return 0;
+}