@guidobuilds/forge-ai 0.7.0 → 0.8.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-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,32 @@
+import { spawnSync } from 'node:child_process';
+import { resolveExecutable } from './executable-resolution.js';
+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: '' };
+    }
+};
+const modelLinePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*\/\S+$/;
+// Returns undefined (not an empty array) on any failure — binary absent, non-zero exit, or no
+// parseable lines — so callers can fall back to a free-text prompt instead of showing an empty
+// choice list.
+export function discoverOpenCodeModels(cwd, timeoutMs = 5000, runner = defaultRunner) {
+    for (const command of ['opencode', 'opencode2']) {
+        const result = runner(command, ['models'], { cwd, timeoutMs });
+        if (result.status !== 0)
+            continue;
+        const lines = result.stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => modelLinePattern.test(line));
+        if (lines.length > 0)
+            return lines;
+    }
+    return undefined;
+}

package/dist/src/paths.js

@@ -1,12 +1,30 @@
+import { realpathSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 export function resolveOutputPath(platform, kind, scope, name, cwd = process.cwd(), home = os.homedir()) {
     const base = scope === 'user' ? userBase(platform, kind, home) : projectBase(platform, kind, cwd);
+    return path.join(base, outputFileName(platform, kind, name));
+}
+function outputFileName(platform, kind, name) {
     return kind === 'agent' && platform === 'codex'
-        ? path.join(base, `${name}.toml`)
+        ? `${name}.toml`
         : kind === 'agent'
-            ? path.join(base, `${name}.md`)
-            : path.join(base, name, 'SKILL.md');
+            ? `${name}.md`
+            : path.join(name, 'SKILL.md');
+}
+// OpenCode v1 (the `opencode` binary) and the v2 preview (`opencode2`) resolve user-scope
+// agents/skills from different directories — v1 from `~/.config/opencode/`, v2 from `~/.opencode/`
+// (confirmed empirically via `opencode2 debug config`; v2 does not read `~/.config/opencode` at
+// all). `userBase` above returns the v1 path, which stays the default single-target path used
+// everywhere else; this returns v2's equivalent so callers can additionally target it when it's
+// actually present (see `resolveOpenCodeUserV2Path` / `openCodeUserRoots` usage in processor.ts —
+// gated on the directory actually existing, not written blindly).
+export function openCodeUserRoots(home) {
+    return { v1: path.join(home, '.config', 'opencode'), v2: path.join(home, '.opencode') };
+}
+export function resolveOpenCodeUserV2Path(kind, name, home) {
+    const base = path.join(openCodeUserRoots(home).v2, kind === 'agent' ? 'agents' : 'skills');
+    return path.join(base, outputFileName('opencode', kind, name));
 }
 function userBase(platform, kind, home) {
     if (platform === 'opencode')
@@ -26,3 +44,37 @@ function projectBase(platform, kind, cwd) {
         return path.join(cwd, '.grok', kind === 'agent' ? 'agents' : 'skills');
     return kind === 'agent' ? path.join(cwd, '.codex', 'agents') : path.join(cwd, '.agents', 'skills');
 }
+const ALL_PLATFORMS = ['opencode', 'claude', 'codex', 'grok'];
+const ALL_KINDS = ['agent', 'skill'];
+function canonicalizePath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+// Single source of truth for the install roots a manifest entry's `path` must live inside.
+// Derived from userBase/projectBase/openCodeUserRoots (never hand-enumerated) so it cannot drift
+// from the real install locations. home/cwd/projectPath are canonicalized (realpath) so a
+// symlinked ~/.claude or project dir does not cause false rejections. Project scope uses the
+// manifest's projectPath (the realpath recorded at install), not the caller's current cwd.
+export function allowedInstallRoots(scope, home, cwd, projectPath) {
+    const roots = [];
+    if (scope === 'user') {
+        const canonicalHome = canonicalizePath(home);
+        for (const platform of ALL_PLATFORMS) {
+            for (const kind of ALL_KINDS)
+                roots.push(userBase(platform, kind, canonicalHome));
+        }
+        roots.push(path.join(openCodeUserRoots(canonicalHome).v2, 'agents'), path.join(openCodeUserRoots(canonicalHome).v2, 'skills'));
+    }
+    else {
+        const canonicalProject = canonicalizePath(projectPath ?? cwd);
+        for (const platform of ALL_PLATFORMS) {
+            for (const kind of ALL_KINDS)
+                roots.push(projectBase(platform, kind, canonicalProject));
+        }
+    }
+    return [...new Set(roots)];
+}

package/dist/src/platform-capabilities.js

@@ -0,0 +1,17 @@
+// Verified per-platform dispatch capability (see .forge/harness-agnostic-adapters/decisions.md).
+// Codex's CLI-installed agents have no spawn tool wired; the coordinator returns DELEGATION_REQUESTS
+// for the orchestrator to fan out instead of self-spawning.
+export const PLATFORM_CAPABILITIES = {
+    claude: { supportsAgentSpawn: true, spawnToolName: 'Agent' },
+    grok: { supportsAgentSpawn: true, spawnToolName: 'task' },
+    opencode: { supportsAgentSpawn: true, spawnToolName: 'task' },
+    codex: { supportsAgentSpawn: false }
+};
+// Every platform's agent-kind renderer emits `model`. Only Claude's skill renderer does
+// (renderClaudeSkill) — Grok/OpenCode/Codex skills silently discard it
+// (GROK_SKILL_MODEL_IGNORED / OPENCODE_SKILL_MODEL_IGNORED / CODEX_SKILL_MODEL_IGNORED). Keyed on
+// *effective* kind, not canonical kind, since effective kind is already per-platform
+// (e.g. `forge` is kind: agent on Claude/OpenCode/Codex but kind: skill on Grok).
+export function supportsModel(platform, effectiveKind) {
+    return effectiveKind === 'agent' || platform === 'claude';
+}