@guidobuilds/forge-ai 0.7.0 → 0.9.0

package/dist/src/compose.js

@@ -0,0 +1,12 @@
+import { resolveSnippet } from './dispatch-snippets.js';
+// A `{{snippet:id}}` that is the entire content of its line is removed as a whole line when it
+// resolves to '' (e.g. a Codex-only bullet in a shared list), instead of leaving a blank line.
+const wholeLineSnippet = /^[ \t]*\{\{snippet:([a-z0-9-]+)\}\}[ \t]*\n?/gm;
+const inlineSnippet = /\{\{snippet:([a-z0-9-]+)\}\}/g;
+export function composeBody(body, platform) {
+    const withWholeLines = body.replace(wholeLineSnippet, (_match, id) => {
+        const text = resolveSnippet(id, platform);
+        return text === '' ? '' : `${text}\n`;
+    });
+    return withWholeLines.replace(inlineSnippet, (_match, id) => resolveSnippet(id, platform));
+}

package/dist/src/dispatch-snippets.js

@@ -0,0 +1,56 @@
+// Every instance of per-harness dispatch vocabulary in artifacts/*/*.md, found by mechanically
+// grepping for Codex|Claude|OpenCode|Grok|spawn|task|Agent|DELEGATION_REQUESTS and classifying
+// each hit (see .forge/harness-agnostic-adapters/design.md §5.5 / feature-list.json f4-t1). All
+// five are `mechanism`-class: the difference is real (Codex's CLI agents have no spawn tool), not
+// arbitrary wording. There are currently zero `policy`-class snippets — no instance of the
+// invariant itself ("never do worker work inline", "leaves never spawn") varies by platform.
+export const DISPATCH_SNIPPETS = {
+    'worker-spawn-leaf-instruction': {
+        class: 'mechanism',
+        text: {
+            claude: 'Spawn `forge-worker-leaf` via `Agent`, passing `DISPATCH_DEPTH: 2`, `WORKER_ROLE: leaf`, `TASK_ID`, subgoal, constraints, and `files_hint`. Omit `DELEGATION_REQUESTS`.',
+            grok: 'Spawn `forge-worker-leaf` via `task`, passing `DISPATCH_DEPTH: 2`, `WORKER_ROLE: leaf`, `TASK_ID`, subgoal, constraints, and `files_hint`. Omit `DELEGATION_REQUESTS`.',
+            opencode: 'Spawn `forge-worker-leaf` via `task`, passing `DISPATCH_DEPTH: 2`, `WORKER_ROLE: leaf`, `TASK_ID`, subgoal, constraints, and `files_hint`. Omit `DELEGATION_REQUESTS`.',
+            codex: 'Return `DELEGATION_REQUESTS` for the orchestrator to fan out `forge-worker-leaf` dispatches, including `DISPATCH_DEPTH: 2`, `WORKER_ROLE: leaf`, `TASK_ID`, subgoal, constraints, and `files_hint`.'
+        }
+    },
+    'who-spawns-leaf': {
+        class: 'mechanism',
+        text: {
+            claude: 'coordinators spawn it directly',
+            grok: 'coordinators spawn it directly',
+            opencode: 'coordinators spawn it directly',
+            codex: 'you fan out leaves yourself when a coordinator returns `DELEGATION_REQUESTS`, since coordinators cannot self-spawn there'
+        }
+    },
+    'orchestrator-delegation-requests-handling': {
+        class: 'mechanism',
+        text: {
+            codex: 'On `DELEGATION_REQUESTS`, fan out `forge-worker-leaf` dispatches yourself.',
+            default: '`forge-worker` self-spawns `forge-worker-leaf` directly, so `DELEGATION_REQUESTS` should not normally appear here; fan out `forge-worker-leaf` dispatches yourself if it does.'
+        }
+    },
+    'worker-must-spawn-or-delegate': {
+        class: 'mechanism',
+        text: {
+            codex: 'return `DELEGATION_REQUESTS`',
+            default: 'spawn leaves'
+        }
+    },
+    'codex-orchestrator-dispatch-hint': {
+        class: 'mechanism',
+        text: {
+            codex: '- Codex: parse `DELEGATION_REQUESTS` and fan out `forge-worker-leaf` yourself',
+            default: ''
+        }
+    }
+};
+export function resolveSnippet(id, platform) {
+    const snippet = DISPATCH_SNIPPETS[id];
+    if (!snippet)
+        throw new Error(`Unknown dispatch snippet "${id}" referenced in a canonical artifact body`);
+    const text = snippet.text[platform] ?? snippet.text.default;
+    if (text === undefined)
+        throw new Error(`Dispatch snippet "${id}" has no text for platform "${platform}" and no default`);
+    return text;
+}

package/dist/src/executable-resolution.js

@@ -0,0 +1,49 @@
+import { accessSync, constants, realpathSync } from 'node:fs';
+import path from 'node:path';
+function canonicalize(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+function safeCandidate(candidate, cwd) {
+    try {
+        accessSync(candidate, constants.F_OK);
+    }
+    catch {
+        return undefined;
+    }
+    if (cwd) {
+        const resolvedCandidate = canonicalize(candidate);
+        const resolvedCwd = canonicalize(cwd);
+        const rel = path.relative(resolvedCwd, resolvedCandidate);
+        // At-or-inside cwd → reject, so a repo-local shim (e.g. node_modules/.bin) cannot shadow the
+        // real binary. Both sides canonicalized (realpath) to cover symlinked PATH entries/dotdirs.
+        if (!rel.startsWith('..') && !path.isAbsolute(rel))
+            return undefined;
+    }
+    return path.resolve(candidate);
+}
+// Portable PATH scan (separator path.delimiter: ':' POSIX, ';' Windows). Returns the absolute path
+// to the first existing executable named `command` on PATH, or undefined — except any candidate
+// that canonicalizes to at-or-inside `cwd`, which is rejected so a repo-local shim cannot shadow
+// the real binary. An already-absolute `command` is treated as a direct candidate (existence + cwd
+// check, no PATH re-scan).
+// Windows note: existence only (access F_OK), NOT PATHEXT (.cmd/.bat/.exe) — by design, fail-closed:
+// a Windows `opencode`/`pnpm` invoked via a .cmd wrapper will not resolve and discovery/self-update
+// degrade to their safe fallback. Full PATHEXT support is a documented follow-up, not this change.
+export function resolveExecutable(command, options = {}) {
+    if (path.isAbsolute(command))
+        return safeCandidate(command, options.cwd);
+    const pathEnv = options.path ?? process.env.PATH ?? '';
+    for (const dir of pathEnv.split(path.delimiter)) {
+        if (dir === '')
+            continue;
+        const resolved = safeCandidate(path.join(dir, command), options.cwd);
+        if (resolved)
+            return resolved;
+    }
+    return undefined;
+}

package/dist/src/index.js

@@ -1,4 +1,3 @@
 export * from './model.js';
 export * from './processor.js';
 export * from './writer.js';
-export * from './adapters/codex-plugin.js';

package/dist/src/manifest.js

@@ -1,46 +1,163 @@
-import { createHash } from 'node:crypto';
-import { constants } from 'node:fs';
-import { access, mkdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, realpathSync } from 'node:fs';
+import { access, cp, mkdir, readdir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+export function legacyStateRoot(home) {
+    return path.join(home, '.forge-ai');
+}
+export function stateRoot(home) {
+    return path.join(home, '.forge', 'state');
+}
+// `~/.forge/state/` is a path nested under Forge's own namespace that nothing else creates, so its
+// mere existence is a safe migration marker — unlike bare `~/.forge/`, which a dogfooded Forge run
+// can create as a project feature ledger (index.md, <slug>/feature-list.json, ...) with no relation
+// to install state. Nesting under `state/` means the two can never collide, migrated or not.
+export async function migrateStateDirectory(home) {
+    const newRoot = stateRoot(home);
+    const oldRoot = legacyStateRoot(home);
+    if (await pathExists(newRoot))
+        return false;
+    if (!(await pathExists(oldRoot)))
+        return false;
+    await cp(oldRoot, newRoot, { recursive: true });
+    await writeFile(path.join(oldRoot, 'MIGRATED'), `Forge migrated its install state to ${newRoot} on ${new Date().toISOString()}.\nThis directory (${oldRoot}) is no longer read by Forge and can be deleted once you've confirmed the new location works.\n`, 'utf8');
+    return true;
+}
+async function pathExists(target) {
+    try {
+        await access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function resolveManifestLocation(scope, cwd = process.cwd(), home) {
-    const stateRoot = path.join(home, '.forge-ai');
+    const migrated = await migrateStateDirectory(home);
+    if (migrated)
+        console.log(`Migrated Forge install state from ${legacyStateRoot(home)} to ${stateRoot(home)}.`);
+    const root = stateRoot(home);
     if (scope === 'user')
-        return { stateRoot, manifestPath: path.join(stateRoot, 'user-manifest.json'), scope };
+        return { stateRoot: root, manifestPath: path.join(root, 'user-manifest.json'), scope };
     const projectPath = await canonicalProjectPath(cwd);
     const projectPathHash = hashProjectPath(projectPath);
-    return { stateRoot, manifestPath: path.join(stateRoot, 'projects', projectPathHash, 'manifest.json'), scope, projectPath, projectPathHash };
+    return { stateRoot: root, manifestPath: path.join(root, 'projects', projectPathHash, 'manifest.json'), scope, projectPath, projectPathHash };
+}
+// A cached old CLI (npx resolves versions independently per invocation) can keep writing to
+// ~/.forge-ai/ after migration while a newer CLI writes to ~/.forge/state/, producing two live
+// checksum ledgers over the same installed files. Detect it by timestamp rather than silently
+// trusting whichever manifest happens to load — the fix is telling the user, not auto-merging.
+export async function detectLegacyStateDrift(location, home) {
+    const legacyPath = location.manifestPath.replace(stateRoot(home), legacyStateRoot(home));
+    if (legacyPath === location.manifestPath)
+        return undefined;
+    const [legacy, current] = await Promise.all([loadManifest(legacyPath), loadManifest(location.manifestPath)]);
+    if (!legacy || !current)
+        return undefined;
+    if (new Date(legacy.updatedAt).getTime() <= new Date(current.updatedAt).getTime())
+        return undefined;
+    return `An older Forge install at ${legacyPath} was updated more recently (${legacy.updatedAt}) than ${location.manifestPath} (${current.updatedAt}). An old cached CLI may still be writing there — re-run install/update with this CLI to resync, or remove ${legacyStateRoot(home)} once you've confirmed it's no longer used.`;
+}
+export async function listInstalls(home) {
+    await migrateStateDirectory(home);
+    const root = stateRoot(home);
+    const summaries = [];
+    const userManifestPath = path.join(root, 'user-manifest.json');
+    const userManifest = await loadManifest(userManifestPath);
+    if (userManifest)
+        summaries.push(await summarize(userManifest, { stateRoot: root, manifestPath: userManifestPath, scope: 'user' }, home));
+    let projectHashes = [];
+    try {
+        projectHashes = await readdir(path.join(root, 'projects'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    for (const hash of projectHashes) {
+        const manifestPath = path.join(root, 'projects', hash, 'manifest.json');
+        const manifest = await loadManifest(manifestPath);
+        if (manifest)
+            summaries.push(await summarize(manifest, { stateRoot: root, manifestPath, scope: 'project', projectPathHash: hash }, home));
+    }
+    return summaries;
+}
+async function summarize(manifest, location, home) {
+    const platforms = [...new Set(manifest.entries.map((entry) => entry.platform))].sort();
+    const driftWarning = await detectLegacyStateDrift(location, home);
+    return { scope: manifest.scope, projectPath: manifest.projectPath, forgeVersion: manifest.forgeVersion, updatedAt: manifest.updatedAt, platforms, fileCount: manifest.entries.length, driftWarning };
 }
 export async function loadManifest(manifestPath) {
+    let raw;
     try {
-        return JSON.parse(await readFile(manifestPath, 'utf8'));
+        raw = JSON.parse(await readFile(manifestPath, 'utf8'));
     }
     catch (error) {
         if (error.code === 'ENOENT')
             return undefined;
+        if (error instanceof SyntaxError) {
+            console.error(`state file corrupt at ${manifestPath}; re-run \`forge-ai install\` to regenerate it.`);
+            return undefined;
+        }
         throw error;
     }
+    // Validate shape BEFORE accessing fields — parseable non-objects ("hi", [1,2], 42, null) throw
+    // TypeError (not SyntaxError) on `raw.schemaVersion`, so shape-mismatch must be caught here.
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw) || !Array.isArray(raw.entries)) {
+        console.error(`state file corrupt at ${manifestPath}; re-run \`forge-ai install\` to regenerate it.`);
+        return undefined;
+    }
+    if (raw.schemaVersion === 1)
+        return upgradeManifestV1(raw);
+    return raw;
 }
-export async function buildManifest(location, files, now = new Date()) {
+function upgradeManifestV1(manifest) {
+    return {
+        ...manifest,
+        schemaVersion: 2,
+        forgeVersion: 'unknown',
+        entries: manifest.entries.map((entry) => ({ ...entry, forgeVersion: 'unknown' }))
+    };
+}
+export async function buildManifest(location, files, forgeVersion, now = new Date(), oldManifest) {
     const entries = await Promise.all(files.map(async (file) => ({
         platform: file.platform,
         kind: file.kind,
         name: file.name,
         path: file.path,
         sourcePath: file.sourcePath,
-        checksum: sha256(await readFile(file.path, 'utf8'))
+        checksum: sha256(await readFile(file.path, 'utf8')),
+        forgeVersion
     })));
+    // Entries for platforms this run didn't touch (e.g. a prior `install --platform claude` run,
+    // followed by `install --platform opencode`) are carried forward rather than dropped, so
+    // previously-installed files never silently reclassify as foreign on a later run.
+    const touchedPlatforms = new Set(files.map((file) => file.platform));
+    const carriedForward = (oldManifest?.entries ?? []).filter((entry) => !touchedPlatforms.has(entry.platform));
     return {
-        schemaVersion: 1,
+        schemaVersion: 2,
         scope: location.scope,
         projectPath: location.projectPath,
         projectPathHash: location.projectPathHash,
+        forgeVersion,
         updatedAt: now.toISOString(),
-        entries
+        entries: [...carriedForward, ...entries]
     };
 }
+export async function writeFileAtomic(filePath, content) {
+    const tmpPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.tmp-${randomUUID()}`);
+    try {
+        await writeFile(tmpPath, content, 'utf8');
+        await rename(tmpPath, filePath);
+    }
+    catch (error) {
+        await rm(tmpPath, { force: true }).catch(() => { });
+        throw error;
+    }
+}
 export async function saveManifest(manifestPath, manifest) {
     await mkdir(path.dirname(manifestPath), { recursive: true });
-    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+    await writeFileAtomic(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
 }
 export function lookupEntryByPath(manifest, filePath) {
     return manifest?.entries.find((entry) => entry.path === filePath);
@@ -51,10 +168,14 @@ export function staleEntries(oldManifest, files) {
     const currentPaths = new Set(files.map((file) => file.path));
     return oldManifest.entries.filter((entry) => !currentPaths.has(entry.path));
 }
-export async function classifyPruneEntries(entries) {
+export async function classifyPruneEntries(entries, roots) {
     const deletable = [];
     const skipped = [];
     for (const entry of entries) {
+        if (!isSafeManifestEntry(entry, roots)) {
+            skipped.push({ ...entry, reason: 'unsafe-path' });
+            continue;
+        }
         let content;
         try {
             content = await readFile(entry.path, 'utf8');
@@ -73,8 +194,10 @@ export async function classifyPruneEntries(entries) {
     }
     return { deletable, skipped };
 }
-export async function pruneEntries(entries) {
+export async function pruneEntries(entries, roots) {
     for (const entry of entries) {
+        if (!isSafeManifestEntry(entry, roots))
+            continue; // defense in depth: never rm an out-of-scope path
         if (entry.backupPath) {
             try {
                 const content = await readFile(entry.path, 'utf8');
@@ -109,6 +232,41 @@ export async function backupFile(backupPath, content) {
 export function sha256(content) {
     return createHash('sha256').update(content).digest('hex');
 }
+const CHECKSUM_PATTERN = /^[0-9a-f]{64}$/;
+function canonicalizePath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+// True when `p` is absolute and canonicalizes (realpath) to inside one of the already-canonical
+// `roots` (canonical→canonical comparison; path.relative resolves `..` internally).
+export function isSafeManifestPath(p, roots) {
+    if (!path.isAbsolute(p))
+        return false;
+    const resolved = canonicalizePath(p);
+    return roots.some((root) => {
+        const rel = path.relative(root, resolved);
+        return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+    });
+}
+function hasValidEntrySchema(entry) {
+    if (typeof entry !== 'object' || entry === null)
+        return false;
+    const e = entry;
+    return (typeof e.platform === 'string' &&
+        typeof e.kind === 'string' &&
+        typeof e.name === 'string' &&
+        typeof e.path === 'string' &&
+        typeof e.sourcePath === 'string' &&
+        typeof e.checksum === 'string' &&
+        CHECKSUM_PATTERN.test(e.checksum));
+}
+export function isSafeManifestEntry(entry, roots) {
+    return hasValidEntrySchema(entry) && isSafeManifestPath(entry.path, roots);
+}
 export function hashProjectPath(projectPath) {
     return sha256(projectPath).slice(0, 32);
 }

package/dist/src/model-discovery.js

@@ -0,0 +1,200 @@
+import { spawnSync } from 'node:child_process';
+import { resolveExecutable } from './executable-resolution.js';
+import { isKnownCodexModel } from './adapters/codex-known.js';
+import { isKnownGrokModel } from './adapters/grok-known.js';
+export const MODEL_DISCOVERY_TIMEOUT_MS = 5000;
+export const MODEL_DISCOVERY_MAX_STDOUT_BYTES = 1024 * 1024; // Codex live is ~327 KB — 1 MB headroom.
+export const MODEL_DISCOVERY_MAX_MODELS = 500;
+// defaultRunner: spawnSync + resolveExecutable (moved here from opencode-discovery so the module graph
+// stays acyclic and the runner/caps live in one place). Binaries are resolved to absolute paths and
+// any candidate inside cwd (a repo-local shim) is rejected by resolveExecutable. On Windows there is
+// no PATHEXT, so `.cmd`/`.bat`/`.exe` wrappers won't resolve and discovery degrades to the curated
+// fallback — fail-closed, documented, not fixed here.
+export const defaultRunner = (command, args, options) => {
+    const resolved = resolveExecutable(command, { cwd: options.cwd });
+    if (!resolved)
+        return { status: null, stdout: '' };
+    try {
+        const result = spawnSync(resolved, args, { timeout: options.timeoutMs, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+        return { status: result.error ? null : result.status, stdout: result.stdout ?? '' };
+    }
+    catch {
+        return { status: null, stdout: '' };
+    }
+};
+function exceedsStdoutCap(stdout) {
+    // Byte-accurate: compare Buffer.byteLength (UTF-8 bytes), not `.length` (UTF-16 code units).
+    return Buffer.byteLength(stdout, 'utf8') > MODEL_DISCOVERY_MAX_STDOUT_BYTES;
+}
+function dedupeStable(values) {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        if (!seen.has(value)) {
+            seen.add(value);
+            out.push(value);
+        }
+    }
+    return out;
+}
+// ============================================================================
+// OpenCode — `opencode` / `opencode2 models` (preserved behavior, caps added)
+// ============================================================================
+// `opencode models` prints exactly the models this user can actually pick — filtered to whichever
+// providers have credentials (env var, stored auth, or a config/plugin-declared provider), not the
+// full models.dev catalog. This is deliberately NOT config-file parsing: OpenCode's config schema
+// differs between v1 (`provider`, singular) and the v2 preview (`providers`, plural), env-var- and
+// credential-connected providers appear in neither file, and OPENCODE_CONFIG_DIR can relocate the
+// whole config tree — the CLI itself is the only thing that resolves all of that correctly.
+// Tries `opencode` (v1) then `opencode2` (v2 preview). v2 gained a real `models` command in
+// `anomalyco/opencode` commit 30d14000 (2026-08-06); any v2 build older than that has no such
+// subcommand and treats `models` as a positional `<directory>` (crash) — caught here regardless.
+const modelLinePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*\/\S+$/;
+export function discoverOpenCodeModels(cwd, timeoutMs = MODEL_DISCOVERY_TIMEOUT_MS, runner = defaultRunner) {
+    for (const command of ['opencode', 'opencode2']) {
+        const result = runner(command, ['models'], { cwd, timeoutMs });
+        if (result.status !== 0)
+            continue;
+        if (exceedsStdoutCap(result.stdout))
+            return undefined;
+        const lines = result.stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => modelLinePattern.test(line));
+        if (lines.length > 0)
+            return lines.slice(0, MODEL_DISCOVERY_MAX_MODELS);
+    }
+    return undefined;
+}
+// ============================================================================
+// Codex — `codex debug models` (merged catalog; `--bundled` deferred, documented)
+// ============================================================================
+// Codex has no stable offline model enum. `codex debug models` prints the *merged* catalog (the
+// remote-refreshed set Codex sees, ~327 KB) as JSON `{ "models": [...] }`; each entry has `slug`,
+// `display_name`, `visibility` (`list` | `hide`), `context_window`, `priority`, `description`, and
+// `supported_reasoning_levels`. User-selectable ids are `visibility === 'list'`; each slug is then
+// trimmed and re-validated through `isKnownCodexModel` so empty/whitespace ids can never leak through.
+//
+// Bundled-vs-merged decision: we default to the MERGED catalog (remote refresh) under the shared
+// timeout because it is closer to what the user can actually select. `--bundled` (offline-deterministic,
+// skips the remote refresh) is a documented follow-up, NOT built: a `--bundled` re-run on timeout would
+// double latency, and the curated `knownCodexModels` offline fallback already covers the deterministic
+// case. Caveat (openai/codex issue 33146): the merged catalog can diverge from the TUI `/model` picker
+// (stale `~/.codex/models_cache.json`) — mitigated by suggestions-only UX + the `Custom…` free-text
+// escape. `supported_reasoning_levels` is deliberately discarded (model-id-only selection).
+export function discoverCodexModels(cwd, timeoutMs = MODEL_DISCOVERY_TIMEOUT_MS, runner = defaultRunner) {
+    const result = runner('codex', ['debug', 'models'], { cwd, timeoutMs });
+    if (result.status !== 0)
+        return undefined;
+    if (exceedsStdoutCap(result.stdout))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return undefined;
+    const models = parsed.models;
+    if (!Array.isArray(models))
+        return undefined;
+    const slugs = [];
+    for (const entry of models) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const candidate = entry;
+        if (candidate.visibility !== 'list')
+            continue;
+        if (typeof candidate.slug !== 'string')
+            continue;
+        // Trim and re-validate each slug through the permissive per-platform validator, mirroring the grok
+        // parser's discipline (explore.md §4): an empty/whitespace-only id must never leak into the choices.
+        const id = candidate.slug.trim();
+        if (!isKnownCodexModel(id))
+            continue;
+        slugs.push(id);
+    }
+    const deduped = dedupeStable(slugs);
+    if (deduped.length === 0)
+        return undefined;
+    return deduped.slice(0, MODEL_DISCOVERY_MAX_MODELS);
+}
+// ============================================================================
+// Grok — `grok models` (banner-ignoring, `isKnownGrokModel`-validated)
+// ============================================================================
+// `grok models` output can carry a `You are not authenticated.` banner before the model list; the list
+// uses `* <model> (default)` for the default and `- <model>` for available. The banner is noise and
+// never a model line.
+//
+// Fusion policy: `grok models` advertises the binary's known catalog (e.g. `grok-4.6`, `grok-4.5`) but
+// does NOT advertise the Forge-specific aliases the curated set carries (`grok-build`, `grok-build-plan`,
+// `grok-composer-2.5-fast`, `inherit`). Those are valid config values today, so on a successful live
+// query they are merged in as extras (live-first, deduped, stable order via `mergeLiveWithCurated`); on
+// failure the curated set is the whole fallback. We must not silently drop them on a live query.
+const grokModelLinePattern = /^[*\-]\s+(\S+)/;
+export function discoverGrokModels(cwd, timeoutMs = MODEL_DISCOVERY_TIMEOUT_MS, runner = defaultRunner) {
+    const result = runner('grok', ['models'], { cwd, timeoutMs });
+    if (result.status !== 0)
+        return undefined;
+    if (exceedsStdoutCap(result.stdout))
+        return undefined;
+    const out = [];
+    const seen = new Set();
+    for (const line of result.stdout.split('\n')) {
+        const match = grokModelLinePattern.exec(line.trim());
+        if (!match)
+            continue;
+        const id = match[1];
+        if (!isKnownGrokModel(id))
+            continue;
+        if (!seen.has(id)) {
+            seen.add(id);
+            out.push(id);
+        }
+    }
+    if (out.length === 0)
+        return undefined;
+    return out.slice(0, MODEL_DISCOVERY_MAX_MODELS);
+}
+// ============================================================================
+// Claude — no dynamic source (honest undefined)
+// ============================================================================
+// Claude Code has NO CLI model-enumeration command: `claude --help` exposes only `--model` /
+// `--fallback-model` flags and a non-scriptable in-TUI `/model`. There is no `claude models` /
+// `claude list`. So this always returns undefined by design — the curated `knownClaudeModels` set plus
+// the free-text `Custom…` escape is the honest fallback. Do NOT add a fake dynamic source here; the
+// `discoverModels` dispatch keeps a `claude` branch so a real source could be added later without
+// touching the caller.
+export function discoverClaudeModels(cwd, timeoutMs = MODEL_DISCOVERY_TIMEOUT_MS, runner = defaultRunner) {
+    return undefined;
+}
+// ============================================================================
+// Dispatcher — one call per platform. Returns undefined on ANY failure → caller falls back.
+// ============================================================================
+export function discoverModels(platform, cwd, runner = defaultRunner, timeoutMs = MODEL_DISCOVERY_TIMEOUT_MS) {
+    switch (platform) {
+        case 'opencode': return discoverOpenCodeModels(cwd, timeoutMs, runner);
+        case 'codex': return discoverCodexModels(cwd, timeoutMs, runner);
+        case 'grok': return discoverGrokModels(cwd, timeoutMs, runner);
+        case 'claude': return discoverClaudeModels(cwd, timeoutMs, runner);
+        default: return undefined;
+    }
+}
+// ============================================================================
+// Fusion helper — live-first, then curated extras not already present, deduped,
+// order preserved. Generic over the curated iterable so this module does not
+// depend on any particular curated set.
+// ============================================================================
+export function mergeLiveWithCurated(live, curated) {
+    const seen = new Set(live);
+    const out = [...live];
+    for (const item of curated) {
+        if (!seen.has(item)) {
+            seen.add(item);
+            out.push(item);
+        }
+    }
+    return out;
+}

package/dist/src/model-preferences.js

@@ -0,0 +1,41 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { writeFileAtomic } from './manifest.js';
+// Lives beside the manifest, not inside it: ManifestEntry is rebuilt from scratch on every
+// install/update run (see buildManifest), so a model choice stored there would be silently lost
+// on the next run. This file is read-modified-written independently and merged into the render
+// pipeline as an override, never derived from the manifest.
+export function modelPreferencesPath(location) {
+    const filename = location.scope === 'user' ? 'user-model-preferences.json' : 'model-preferences.json';
+    return path.join(path.dirname(location.manifestPath), filename);
+}
+export async function loadModelPreferences(prefsPath) {
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(prefsPath, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        if (error instanceof SyntaxError) {
+            console.error(`state file corrupt at ${prefsPath}; re-run \`forge-ai install\` to regenerate it.`);
+            return {};
+        }
+        throw error;
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        console.error(`state file corrupt at ${prefsPath}; re-run \`forge-ai install\` to regenerate it.`);
+        return {};
+    }
+    return raw;
+}
+export async function saveModelPreferences(prefsPath, prefs) {
+    await mkdir(path.dirname(prefsPath), { recursive: true });
+    await writeFileAtomic(prefsPath, `${JSON.stringify(prefs, null, 2)}\n`);
+}
+export function setModelPreference(prefs, platform, name, model) {
+    return { ...prefs, [platform]: { ...prefs[platform], [name]: model } };
+}
+export function getModelPreference(prefs, platform, name) {
+    return prefs[platform]?.[name];
+}

package/dist/src/opencode-discovery.js

@@ -0,0 +1,5 @@
+// Backward-compatible re-export shim. The canonical discovery module is `src/model-discovery.ts`;
+// this file exists only to preserve the stable `src/opencode-discovery.js` import path used by
+// `src/cli.ts` and the tests. The runner abstraction, shared caps, `discoverOpenCodeModels`, and the
+// platform dispatcher now live in `src/model-discovery.ts`.
+export { defaultRunner, discoverOpenCodeModels, MODEL_DISCOVERY_TIMEOUT_MS, MODEL_DISCOVERY_MAX_STDOUT_BYTES, MODEL_DISCOVERY_MAX_MODELS } from './model-discovery.js';