@pruddiman/hem 0.0.1-beta-1aff12a → 0.0.1-beta-1ec07ab

package/dist/agents/base-agent.js

@@ -14,7 +14,7 @@
  *   - Low-level session ops (`promptAsync`, `session.abort`, `event.subscribe`)
  *     are accessed via `this.provider.session.*` and `this.provider.event.*`.
  */
-import { isAuthExpired, AuthExpiredError } from "../auth.js";
+import { wrapAuthError } from "../auth.js";
 // ── Base Agent ──────────────────────────────────────────────────────────
 /**
  * Abstract base class providing shared session lifecycle management
@@ -44,14 +44,6 @@ export class BaseAgent {
      * @throws {Error} If creation fails for any other reason.
      */
     async createSession(_title) {
-        try {
-            return await this.provider.createSession();
-        }
-        catch (err) {
-            if (isAuthExpired(err)) {
-                throw new AuthExpiredError("the configured provider", err);
-            }
-            throw err;
-        }
+        return wrapAuthError(() => this.provider.createSession());
     }
 }

package/dist/agents/base-arbiter.js

@@ -21,7 +21,7 @@
  * `BaseArbiter` factors out the lifecycle skeleton; subclasses provide
  * the four configuration values above.
  */
-import { isAuthExpired, AuthExpiredError } from "../auth.js";
+import { wrapAuthError } from "../auth.js";
 import { BaseAgent } from "./base-agent.js";
 /**
  * Abstract base for arbiter coordinator agents. Concrete subclasses
@@ -51,21 +51,13 @@ export class BaseArbiter extends BaseAgent {
         if (verbose) {
             verbose(`[${this.tag}] session ${sessionId}`);
         }
-        try {
-            await this.provider.session.promptAsync({
-                path: { id: sessionId },
-                body: {
-                    parts: [{ type: "text", text: prompt }],
-                    agent: this.agentField,
-                },
-            });
-        }
-        catch (err) {
-            if (isAuthExpired(err)) {
-                throw new AuthExpiredError("the configured provider", err);
-            }
-            throw err;
-        }
+        await wrapAuthError(() => this.provider.session.promptAsync({
+            path: { id: sessionId },
+            body: {
+                parts: [{ type: "text", text: prompt }],
+                agent: this.agentField,
+            },
+        }));
         if (verbose) {
             verbose(`[${this.tag}] initial prompt sent (listening for broadcasts)`);
         }

package/dist/auth.d.ts

@@ -162,6 +162,14 @@ export declare class AuthExpiredError extends Error {
     readonly providerName: string;
     constructor(providerName: string, cause?: unknown);
 }
+/**
+ * Run an async operation, converting auth-expiry failures into
+ * {@link AuthExpiredError}. Other errors propagate unchanged.
+ *
+ * Used by call sites that perform a single provider API call and want
+ * uniform auth-error handling.
+ */
+export declare function wrapAuthError<T>(op: () => Promise<T>): Promise<T>;
 /**
  * Determine whether an error indicates expired or invalid authentication.
  *
@@ -364,7 +372,12 @@ export declare function handleAuthLogin(client: OpencodeClient, configDir?: stri
  *
  * Reference: FR-021, contracts/cli-interface.md lines 132-143.
  */
-export declare function handleAuthList(client: OpencodeClient, configDir?: string, writeFn?: (msg: string) => void): Promise<void>;
+/** Per-backbone availability map injected into {@link handleAuthList}. */
+export interface AuthListBackboneAvailability {
+    opencode: boolean;
+    copilot: boolean;
+}
+export declare function handleAuthList(client: OpencodeClient, configDir?: string, writeFn?: (msg: string) => void, availability?: AuthListBackboneAvailability): Promise<void>;
 /**
  * Handle `hem auth logout` — remove credentials.
  *

package/dist/auth.js

@@ -430,6 +430,24 @@ export class AuthExpiredError extends Error {
         }
     }
 }
+/**
+ * Run an async operation, converting auth-expiry failures into
+ * {@link AuthExpiredError}. Other errors propagate unchanged.
+ *
+ * Used by call sites that perform a single provider API call and want
+ * uniform auth-error handling.
+ */
+export async function wrapAuthError(op) {
+    try {
+        return await op();
+    }
+    catch (err) {
+        if (isAuthExpired(err)) {
+            throw new AuthExpiredError("the configured provider", err);
+        }
+        throw err;
+    }
+}
 /**
  * Determine whether an error indicates expired or invalid authentication.
  *
@@ -1007,29 +1025,7 @@ function formatAuthMethod(authMethod) {
             return "(env var)";
     }
 }
-/**
- * Handle `hem auth list` — show connected providers with status.
- *
- * Calls `client.config.providers()`, formats and prints connected providers
- * with status (checkmark + name + auth method) per `contracts/cli-interface.md`
- * lines 132-143, also shows the default model from preferences.
- *
- * Output format:
- * ```
- *   Connected providers:
- *     ✓ anthropic    Claude Pro/Max (OAuth)
- *     ✓ opencode     Zen API Key
- *
- *   Default model: anthropic/claude-sonnet-4
- * ```
- *
- * @param client — OpenCode SDK client instance.
- * @param configDir — Override for the config directory (used in tests).
- * @param writeFn — Override for the output function (used in tests).
- *
- * Reference: FR-021, contracts/cli-interface.md lines 132-143.
- */
-export async function handleAuthList(client, configDir, writeFn = (msg) => process.stdout.write(msg)) {
+export async function handleAuthList(client, configDir, writeFn = (msg) => process.stdout.write(msg), availability) {
     // Query the SDK for connected providers.
     const result = await client.config.providers();
     const sdkProviders = result.data?.providers ?? [];
@@ -1057,7 +1053,17 @@ export async function handleAuthList(client, configDir, writeFn = (msg) => proce
         for (const provider of connectedProviders) {
             const padding = " ".repeat(Math.max(1, maxIdLen - provider.id.length + 4));
             const method = formatAuthMethod(provider.authMethod);
-            writeFn(`    \u2713 ${provider.id}${padding}${provider.name} ${method}\n`);
+            // Annotate copilot-backed providers as ✗ when the copilot CLI is
+            // missing so the user knows the credential alone won't get them
+            // through generation. Opencode-backed providers are always reachable
+            // here because handleAuthList only runs when opencode is present.
+            const isCopilot = provider.id === "github-copilot" || provider.id === "copilot";
+            const reachable = !isCopilot || availability?.copilot !== false;
+            const icon = reachable ? "\u2713" : "\u2717";
+            const suffix = reachable
+                ? ""
+                : "  (copilot CLI not installed — npm install -g @github/copilot)";
+            writeFn(`    ${icon} ${provider.id}${padding}${provider.name} ${method}${suffix}\n`);
         }
     }
     writeFn("\n");

package/dist/grouping.js

@@ -66,7 +66,9 @@ export function matchDocFolder(filePath, priors) {
     if (priors.length === 0)
         return null;
     const segments = filePath.split("/").map((s) => s.toLowerCase());
-    const fileStem = extractStem(segments[segments.length - 1] ?? "");
+    const lastSegment = segments[segments.length - 1] ?? "";
+    const dotIndex = lastSegment.indexOf(".");
+    const fileStem = (dotIndex === -1 ? lastSegment : lastSegment.substring(0, dotIndex)).toLowerCase();
     // Prefer the prior with the longest key match to avoid `auth` stealing
     // files that should go to `authentication`.
     let best = null;
@@ -90,10 +92,6 @@ export function normalizeFolderKey(name) {
         .replace(/-+/g, "-")
         .replace(/^-|-$/g, "");
 }
-function extractStem(basename) {
-    const dotIndex = basename.indexOf(".");
-    return (dotIndex === -1 ? basename : basename.substring(0, dotIndex)).toLowerCase();
-}
 /**
  * Scoring:
  *   - 3 for a directory-segment match (strongest signal).
@@ -244,17 +242,6 @@ export function commonDirectory(files) {
     }
     return common.length === 0 ? "." : common.join("/");
 }
-/**
- * Returns the "name" portion of the file without known layer suffixes
- * and without the actual file extension.
- * E.g. `user.controller.ts` → the layer suffix is `.controller` → stem `user`.
- * `helpers.ts` → no layer suffix → stem `helpers`.
- */
-function fileNameWithoutExtension(relativePath) {
-    const base = relativePath.split("/").pop() ?? "";
-    const lastDot = base.lastIndexOf(".");
-    return lastDot === -1 ? base : base.substring(0, lastDot);
-}
 /**
  * Detects the architectural layer for a file by checking its name
  * against known suffixes.
@@ -262,7 +249,9 @@ function fileNameWithoutExtension(relativePath) {
  * @returns The layer label (e.g., "Controllers") or `undefined`.
  */
 function detectLayer(relativePath) {
-    const nameNoExt = fileNameWithoutExtension(relativePath).toLowerCase();
+    const base = relativePath.split("/").pop() ?? "";
+    const lastDot = base.lastIndexOf(".");
+    const nameNoExt = (lastDot === -1 ? base : base.substring(0, lastDot)).toLowerCase();
     for (const { suffix, label } of LAYER_SUFFIXES) {
         if (nameNoExt.endsWith(suffix)) {
             return label;

package/dist/helpers/parsing.d.ts

@@ -1,20 +1,6 @@
 /**
  * Text extraction and parsing utilities for Hem.
- *
- * Provides helpers for extracting structured content (Markdown, JSON,
- * file lists, concepts) from LLM response text.
  */
-import type { MessagePart } from "../session.js";
-/**
- * Extracts the Markdown content from the OpenCode prompt response.
- *
- * Concatenates all text parts from the response, stripping any wrapping
- * code fences if the LLM returned the content inside a fenced block.
- *
- * @param parts - The response parts from `promptAndWait()`.
- * @returns The extracted Markdown string.
- */
-export declare function extractMarkdown(parts: Array<MessagePart>): string;
 /**
  * Extracts a JSON string from an LLM response that may contain preamble text.
  *
@@ -31,22 +17,3 @@ export declare function extractMarkdown(parts: Array<MessagePart>): string;
  * @returns The extracted JSON substring (not yet parsed).
  */
 export declare function extractJSON(response: string): string;
-/**
- * Extracts `relatedFiles` from generated Markdown content.
- *
- * Looks for the "Source Files" or "Related Files" section and extracts file
- * paths from backtick-quoted entries (e.g., `` `src/user/controller.ts` ``).
- *
- * @param content - The generated Markdown content.
- * @returns Array of relative file paths found in the Source Files section.
- */
-export declare function parseRelatedFiles(content: string): string[];
-/**
- * Extracts key concept names from section content.
- *
- * Looks for backtick-quoted identifiers as a heuristic for concepts.
- *
- * @param content - The section body text.
- * @returns Array of unique concept strings.
- */
-export declare function extractConcepts(content: string): string[];

package/dist/helpers/parsing.js

@@ -1,36 +1,6 @@
 /**
  * Text extraction and parsing utilities for Hem.
- *
- * Provides helpers for extracting structured content (Markdown, JSON,
- * file lists, concepts) from LLM response text.
  */
-/**
- * Extracts the Markdown content from the OpenCode prompt response.
- *
- * Concatenates all text parts from the response, stripping any wrapping
- * code fences if the LLM returned the content inside a fenced block.
- *
- * @param parts - The response parts from `promptAndWait()`.
- * @returns The extracted Markdown string.
- */
-export function extractMarkdown(parts) {
-    const textParts = parts.filter((p) => p.type === "text" && typeof p.text === "string");
-    let content = textParts.map((p) => p.text).join("\n");
-    // Strip wrapping ```markdown ... ``` fences if present
-    const fencePattern = /^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/;
-    const match = content.match(fencePattern);
-    if (match) {
-        content = match[1];
-    }
-    // Strip preamble text before the first Markdown heading.
-    // LLMs sometimes produce commentary like "Now I have a thorough
-    // understanding of the codebase..." before the actual document.
-    const h1Match = content.search(/^# .+/m);
-    if (h1Match > 0) {
-        content = content.slice(h1Match);
-    }
-    return content.trim();
-}
 /**
  * Extracts a JSON string from an LLM response that may contain preamble text.
  *
@@ -76,53 +46,3 @@ export function extractJSON(response) {
     // Strategy 3: return full string (caller's JSON.parse will validate)
     return response;
 }
-/**
- * Extracts `relatedFiles` from generated Markdown content.
- *
- * Looks for the "Source Files" or "Related Files" section and extracts file
- * paths from backtick-quoted entries (e.g., `` `src/user/controller.ts` ``).
- *
- * @param content - The generated Markdown content.
- * @returns Array of relative file paths found in the Source Files section.
- */
-export function parseRelatedFiles(content) {
-    const files = [];
-    const lines = content.split("\n");
-    let inSection = false;
-    for (const line of lines) {
-        // Detect start of Source Files / Related Files section
-        if (/^##\s+(Source|Related) Files/i.test(line)) {
-            inSection = true;
-            continue;
-        }
-        // End section at next heading
-        if (inSection && /^##\s+/.test(line)) {
-            break;
-        }
-        // Extract file paths from backtick-quoted list items
-        if (inSection) {
-            const match = line.match(/`([^`]+)`/);
-            if (match) {
-                files.push(match[1]);
-            }
-        }
-    }
-    return files;
-}
-/**
- * Extracts key concept names from section content.
- *
- * Looks for backtick-quoted identifiers as a heuristic for concepts.
- *
- * @param content - The section body text.
- * @returns Array of unique concept strings.
- */
-export function extractConcepts(content) {
-    const matches = content.match(/`([^`]+)`/g);
-    if (!matches)
-        return [];
-    const unique = new Set(matches
-        .map((m) => m.slice(1, -1))
-        .filter((c) => c.length > 0 && !/^\s|\s$/.test(c) && !c.includes("  ")));
-    return Array.from(unique);
-}

package/dist/helpers/paths.d.ts

@@ -29,13 +29,3 @@ export declare function isPathWithin(child: string, parent: string): boolean;
  * @throws If the resolved path falls outside the destination directory.
  */
 export declare function resolveOutputPath(destinationPath: string, relativePath: string): string;
-/**
- * Validates the relationship between destination and source paths.
- *
- * When the destination directory is inside the source directory, logs
- * a note that destination files will be excluded from scanning.
- *
- * @param destinationPath - Path to the destination directory.
- * @param sourcePath - Path to the source directory.
- */
-export declare function validateDestinationPath(destinationPath: string, sourcePath: string): void;

package/dist/helpers/paths.js

@@ -48,20 +48,3 @@ export function resolveOutputPath(destinationPath, relativePath) {
     }
     return resolved;
 }
-/**
- * Validates the relationship between destination and source paths.
- *
- * When the destination directory is inside the source directory, logs
- * a note that destination files will be excluded from scanning.
- *
- * @param destinationPath - Path to the destination directory.
- * @param sourcePath - Path to the source directory.
- */
-export function validateDestinationPath(destinationPath, sourcePath) {
-    const absoluteDestination = resolve(destinationPath);
-    const absoluteSource = resolve(sourcePath);
-    if (isPathWithin(absoluteDestination, absoluteSource)) {
-        console.log(`Note: Destination "${absoluteDestination}" is inside source "${absoluteSource}". ` +
-            `Destination files will be excluded from scanning.`);
-    }
-}

package/dist/helpers/strings.d.ts

@@ -13,13 +13,6 @@
  * @returns kebab-cased string.
  */
 export declare function toKebabCase(input: string): string;
-/**
- * Converts a heading string to a URL-friendly slug.
- *
- * @param heading - The heading text.
- * @returns A kebab-case slug (e.g., "Related Files" → "related-files").
- */
-export declare function toSlug(heading: string): string;
 /**
  * Converts a directory name to a section heading.
  *

package/dist/helpers/strings.js

@@ -21,20 +21,6 @@ export function toKebabCase(input) {
         .replace(/-+/g, "-")
         .replace(/^-|-$/g, "");
 }
-/**
- * Converts a heading string to a URL-friendly slug.
- *
- * @param heading - The heading text.
- * @returns A kebab-case slug (e.g., "Related Files" → "related-files").
- */
-export function toSlug(heading) {
-    return heading
-        .toLowerCase()
-        .replace(/[^a-z0-9\s-]/g, "")
-        .replace(/\s+/g, "-")
-        .replace(/-+/g, "-")
-        .replace(/^-|-$/g, "");
-}
 /**
  * Converts a directory name to a section heading.
  *

package/dist/import-graph.d.ts

@@ -45,19 +45,6 @@ export declare function buildImportGraph(files: FileInfo[]): Promise<ImportAnaly
  * isolated nodes appear as singleton components.
  */
 export declare function connectedComponents(universe: readonly string[], localEdges: Map<string, string[]>): string[][];
-/**
- * Compute fan-in (how many files import this file) and fan-out (how many
- * files this file imports) for every node in `universe`.
- */
-export declare function computeDegrees(universe: readonly string[], localEdges: Map<string, string[]>): Map<string, {
-    fanIn: number;
-    fanOut: number;
-}>;
-/**
- * Identify files participating in an import cycle. Uses iterative Tarjan's
- * SCC; any SCC with ≥2 members or a self-loop marks its members as cyclic.
- */
-export declare function nodesInCycles(localEdges: Map<string, string[]>): Set<string>;
 /**
  * Yield every import specifier found in `content` along with the 1-based
  * line number it appears on.

package/dist/import-graph.js

@@ -130,110 +130,6 @@ export function connectedComponents(universe, localEdges) {
     }
     return [...components.values()].map((c) => c.slice().sort((a, b) => a.localeCompare(b)));
 }
-/**
- * Compute fan-in (how many files import this file) and fan-out (how many
- * files this file imports) for every node in `universe`.
- */
-export function computeDegrees(universe, localEdges) {
-    const degrees = new Map();
-    for (const node of universe) {
-        degrees.set(node, { fanIn: 0, fanOut: 0 });
-    }
-    for (const [from, tos] of localEdges) {
-        const d = degrees.get(from);
-        if (!d)
-            continue;
-        d.fanOut = tos.length;
-        for (const to of tos) {
-            const td = degrees.get(to);
-            if (td)
-                td.fanIn += 1;
-        }
-    }
-    return degrees;
-}
-/**
- * Identify files participating in an import cycle. Uses iterative Tarjan's
- * SCC; any SCC with ≥2 members or a self-loop marks its members as cyclic.
- */
-export function nodesInCycles(localEdges) {
-    const index = new Map();
-    const lowlink = new Map();
-    const onStack = new Set();
-    const stack = [];
-    const result = new Set();
-    let counter = 0;
-    const nodes = new Set();
-    for (const [from, tos] of localEdges) {
-        nodes.add(from);
-        for (const to of tos)
-            nodes.add(to);
-    }
-    const strongConnect = (start) => {
-        const frames = [];
-        index.set(start, counter);
-        lowlink.set(start, counter);
-        counter++;
-        stack.push(start);
-        onStack.add(start);
-        frames.push({
-            node: start,
-            iter: (localEdges.get(start) ?? [])[Symbol.iterator](),
-        });
-        while (frames.length > 0) {
-            const frame = frames[frames.length - 1];
-            const next = frame.iter.next();
-            if (next.done) {
-                // Finished with frame.node — check if it's an SCC root.
-                if (lowlink.get(frame.node) === index.get(frame.node)) {
-                    const component = [];
-                    let w;
-                    do {
-                        w = stack.pop();
-                        onStack.delete(w);
-                        component.push(w);
-                    } while (w !== frame.node);
-                    const neighbours = localEdges.get(frame.node) ?? [];
-                    const hasSelfLoop = neighbours.includes(frame.node);
-                    if (component.length >= 2 || hasSelfLoop) {
-                        for (const m of component)
-                            result.add(m);
-                    }
-                }
-                frames.pop();
-                // Propagate lowlink to parent.
-                if (frames.length > 0) {
-                    const parentFrame = frames[frames.length - 1];
-                    const pl = lowlink.get(parentFrame.node);
-                    const cl = lowlink.get(frame.node);
-                    if (cl < pl)
-                        lowlink.set(parentFrame.node, cl);
-                }
-                continue;
-            }
-            const w = next.value;
-            if (!index.has(w)) {
-                index.set(w, counter);
-                lowlink.set(w, counter);
-                counter++;
-                stack.push(w);
-                onStack.add(w);
-                frames.push({ node: w, iter: (localEdges.get(w) ?? [])[Symbol.iterator]() });
-            }
-            else if (onStack.has(w)) {
-                const cur = lowlink.get(frame.node);
-                const wIndex = index.get(w);
-                if (wIndex < cur)
-                    lowlink.set(frame.node, wIndex);
-            }
-        }
-    };
-    for (const node of nodes) {
-        if (!index.has(node))
-            strongConnect(node);
-    }
-    return result;
-}
 // ── Internal helpers ────────────────────────────────────────────────────
 /**
  * Yield every import specifier found in `content` along with the 1-based

package/dist/index.d.ts

@@ -28,6 +28,7 @@ import { findFreePort, startWithRetry } from "./server-utils.js";
 import { discoverFiles, detectProjectName } from "./discovery.js";
 import { groupFiles } from "./grouping.js";
 import type { Provider } from "./providers/types.js";
+import { getBackboneAvailability } from "./providers/index.js";
 import { generateDocumentation, getExitCode } from "./orchestrator.js";
 export { getExitCode };
 import { renderDashboard } from "./progress.js";
@@ -78,15 +79,16 @@ export interface Dependencies {
     detectChangedDocs: typeof detectChangedDocs;
     writeChangelogEntry: typeof writeChangelogEntry;
     scopeToChangedFiles: typeof scopeToChangedFiles;
+    getBackboneAvailability: typeof getBackboneAvailability;
 }
 /**
  * Subset of {@link Dependencies} actually needed by `handleAuth`.
  * Narrower types document what each entry-point actually depends on
  * and let test mocks omit unrelated fields without TypeScript errors.
  */
-export type AuthDeps = Pick<Dependencies, "startWithRetry" | "findFreePort" | "createOpencode" | "handleAuthLogin" | "handleAuthList" | "handleAuthLogout">;
+export type AuthDeps = Pick<Dependencies, "startWithRetry" | "findFreePort" | "createOpencode" | "handleAuthLogin" | "handleAuthList" | "handleAuthLogout" | "getBackboneAvailability">;
 /** Subset of {@link Dependencies} actually needed by `handleConfig`. */
-export type ConfigDeps = Pick<Dependencies, "startWithRetry" | "findFreePort" | "createOpencode" | "detectAuthState" | "handleFirstRun" | "saveProjectConfig" | "renderAndWait" | "listProviderModels">;
+export type ConfigDeps = Pick<Dependencies, "startWithRetry" | "findFreePort" | "createOpencode" | "detectAuthState" | "handleFirstRun" | "saveProjectConfig" | "renderAndWait" | "listProviderModels" | "getBackboneAvailability">;
 /** Default (production) dependency bag. */
 export declare const defaultDeps: Dependencies;
 /**
@@ -132,13 +134,29 @@ export declare function handleGenerate(opts: {
 }, deps?: Dependencies): Promise<GenerateCLIOptions | null>;
 /**
  * Handle the `auth` subcommand.
+ *
+ * Gracefully degrades when the opencode CLI is missing: rather than
+ * crashing with `spawn opencode ENOENT`, prints a backbone-availability
+ * report so the user knows what to install. Login/logout require opencode
+ * today (the auth flows are opencode-managed); copilot uses GitHub
+ * authentication outside hem (`$GITHUB_TOKEN` or `gh auth login`).
  */
 export declare function handleAuth(action: string | undefined, target: string | undefined, deps?: AuthDeps): Promise<AuthCLIOptions | null>;
 /**
  * Handle the `config` subcommand.
  *
- * Interactively prompts the user to select a provider/model and saves
- * the configuration to `{cwd}/.hem/config.json`.
+ * Always opens with a backbone picker that lists every supported
+ * provider backbone (currently opencode and copilot) with a green \u2713
+ * "installed" or red \u2717 "not installed" indicator alongside an
+ * install hint. The user picks an installed backbone; uninstalled ones
+ * are visible but not selectable.
+ *
+ *   - Pick `opencode` → start the opencode server, run the existing
+ *     auth-detect + sub-provider/model selection flow.
+ *   - Pick `copilot`  → save `{providerID: "github-copilot", modelID: "default"}`
+ *     directly (no opencode server needed).
+ *   - No backbones installed → print install hints for all of them and
+ *     exit non-zero.
  */
 export declare function handleConfig(deps?: ConfigDeps): Promise<ConfigCLIOptions | null>;
 /**

package/dist/index.js

@@ -41,7 +41,7 @@ import { IndexAgent } from "./agents/index-agent.js";
 import { OrganizationAgent } from "./agents/organization-agent.js";
 import { CrossRefAgent } from "./agents/crossref-agent.js";
 import { ExplorationAgent } from "./agents/exploration-agent.js";
-import { createProviderFromConfig } from "./providers/index.js";
+import { BACKBONES, backboneForProviderID, createProviderFromConfig, getBackboneAvailability, } from "./providers/index.js";
 import { generateDocumentation, getExitCode } from "./orchestrator.js";
 import { SearchIndex } from "./search-index.js";
 import { computeMaxConcurrency, describeResourceLimits, LARGE_PROJECT_THRESHOLD, computeAgentsPerGroup } from "./resources.js";
@@ -93,6 +93,7 @@ export const defaultDeps = {
     detectChangedDocs,
     writeChangelogEntry,
     scopeToChangedFiles,
+    getBackboneAvailability,
 };
 // ── Search index helpers ────────────────────────────────────────────────
 /**
@@ -272,6 +273,24 @@ export async function handleGenerate(opts, deps = defaultDeps) {
         resolvedModel = preferences.model;
         modelFromPreferences = true;
     }
+    // ── Step 3.5: Backbone pre-flight ──────────────────────────────────
+    //
+    // Before starting the opencode server (which spawns the `opencode`
+    // binary), make sure the backbone for the resolved model is reachable.
+    // If the user explicitly picked a model whose CLI is missing, surface
+    // a clean error with an install hint instead of `spawn ENOENT`.
+    const availability = deps.getBackboneAvailability();
+    const requiredBackbone = resolvedModel
+        ? backboneForProviderID(resolvedModel.providerID)
+        : "opencode";
+    if (!availability[requiredBackbone]) {
+        process.stderr.write(`\n  \u2717 The ${requiredBackbone} CLI is required for the configured ` +
+            `model (${resolvedModel?.providerID ?? "default"}/` +
+            `${resolvedModel?.modelID ?? "default"}) but was not found on PATH.\n` +
+            `    Install: ${BACKBONES[requiredBackbone].installHint}\n\n`);
+        process.exitCode = 2;
+        return null;
+    }
     // ── Step 4: Start OpenCode server ──────────────────────────────────
     const { client, server } = await deps.startWithRetry(async () => {
         const port = await deps.findFreePort();
@@ -854,6 +873,12 @@ export async function handleGenerate(opts, deps = defaultDeps) {
 }
 /**
  * Handle the `auth` subcommand.
+ *
+ * Gracefully degrades when the opencode CLI is missing: rather than
+ * crashing with `spawn opencode ENOENT`, prints a backbone-availability
+ * report so the user knows what to install. Login/logout require opencode
+ * today (the auth flows are opencode-managed); copilot uses GitHub
+ * authentication outside hem (`$GITHUB_TOKEN` or `gh auth login`).
  */
 export async function handleAuth(action, target, deps = defaultDeps) {
     const validActions = ["login", "list", "logout"];
@@ -868,19 +893,40 @@ export async function handleAuth(action, target, deps = defaultDeps) {
         authAction: action ?? undefined,
         authTarget: target,
     };
+    const resolvedAction = cliOptions.authAction ?? "login";
+    const availability = deps.getBackboneAvailability();
+    // Without opencode, none of the SDK-driven auth flows can run. Surface a
+    // useful report instead of letting cross-spawn raise ENOENT.
+    if (!availability.opencode) {
+        if (resolvedAction === "list") {
+            process.stdout.write("\n  Backbones:\n");
+            for (const [id, meta] of Object.entries(BACKBONES)) {
+                const ok = availability[id];
+                const icon = ok ? "\u2713" : "\u2717";
+                const tag = ok ? "installed" : `not installed (${meta.installHint})`;
+                process.stdout.write(`    ${icon} ${id}  ${tag}\n`);
+            }
+            process.stdout.write("\n");
+        }
+        else {
+            process.stderr.write(`\n  \u2717 \`hem auth ${resolvedAction}\` requires the opencode CLI, which was not found on PATH.\n` +
+                `    Install: ${BACKBONES.opencode.installHint}\n\n`);
+            process.exitCode = 2;
+        }
+        return cliOptions;
+    }
     const { client, server } = await deps.startWithRetry(async () => {
         const port = await deps.findFreePort();
         return deps.createOpencode({ port });
     });
     trackServer(() => server.close());
     try {
-        const resolvedAction = cliOptions.authAction ?? "login";
         switch (resolvedAction) {
             case "login":
                 await deps.handleAuthLogin(client);
                 break;
             case "list":
-                await deps.handleAuthList(client);
+                await deps.handleAuthList(client, undefined, undefined, availability);
                 break;
             case "logout":
                 await deps.handleAuthLogout(client, cliOptions.authTarget);
@@ -899,12 +945,21 @@ export async function handleAuth(action, target, deps = defaultDeps) {
  * Step 2: If the provider has models, select one; otherwise use "default".
  * @internal
  */
-async function selectProviderAndModel(deps, client, providers) {
-    const providerOptions = providers.map((p) => ({
-        value: { providerID: p.id, modelID: "default" },
-        label: p.id === "opencode" ? "OpenCode" : p.name,
-        description: `(${p.authMethod})`,
-    }));
+async function selectProviderAndModel(deps, client, providers, availability) {
+    const providerOptions = providers.map((p) => {
+        const backbone = backboneForProviderID(p.id);
+        const reachable = availability[backbone];
+        const baseLabel = p.id === "opencode" ? "OpenCode" : p.name;
+        const label = reachable ? baseLabel : `${baseLabel} \u2717 (not installed)`;
+        const description = reachable
+            ? `(${p.authMethod})`
+            : `(${p.authMethod}) — install: ${BACKBONES[backbone].installHint}`;
+        return {
+            value: { providerID: p.id, modelID: "default" },
+            label,
+            description,
+        };
+    });
     const providerSelection = await deps.renderAndWait((resolve) => React.createElement(ConfigPrompt, {
         options: providerOptions,
         onSelect: resolve,
@@ -943,14 +998,78 @@ async function selectProviderAndModel(deps, client, providers) {
 /**
  * Handle the `config` subcommand.
  *
- * Interactively prompts the user to select a provider/model and saves
- * the configuration to `{cwd}/.hem/config.json`.
+ * Always opens with a backbone picker that lists every supported
+ * provider backbone (currently opencode and copilot) with a green \u2713
+ * "installed" or red \u2717 "not installed" indicator alongside an
+ * install hint. The user picks an installed backbone; uninstalled ones
+ * are visible but not selectable.
+ *
+ *   - Pick `opencode` → start the opencode server, run the existing
+ *     auth-detect + sub-provider/model selection flow.
+ *   - Pick `copilot`  → save `{providerID: "github-copilot", modelID: "default"}`
+ *     directly (no opencode server needed).
+ *   - No backbones installed → print install hints for all of them and
+ *     exit non-zero.
  */
 export async function handleConfig(deps = defaultDeps) {
     const cliOptions = {
         command: "config",
         verbose: false,
     };
+    const availability = deps.getBackboneAvailability();
+    if (!availability.opencode && !availability.copilot) {
+        const lines = [
+            "No model backbone is available. Install at least one of:",
+            ...Object.entries(BACKBONES).map(([id, b]) => `  ${id}\t${b.installHint}`),
+            "",
+        ];
+        process.stderr.write(lines.join("\n") + "\n");
+        process.exitCode = 2;
+        return null;
+    }
+    // Step 1 — top-level backbone picker. Always shows every supported
+    // backbone with an availability indicator so the user can see what's
+    // installed without having to inspect their PATH. Each option's
+    // value.providerID is the canonical opencode-side identifier
+    // (e.g. `github-copilot`, not the backbone slug `copilot`).
+    const PROVIDER_FOR_BACKBONE = {
+        opencode: "opencode",
+        copilot: "github-copilot",
+    };
+    const LABEL_FOR_BACKBONE = {
+        opencode: "OpenCode",
+        copilot: "GitHub Copilot",
+    };
+    const backbonePickerOptions = Object.keys(BACKBONES).map((id) => {
+        const meta = BACKBONES[id];
+        const installed = availability[id];
+        const icon = installed ? "\u2713" : "\u2717";
+        const label = `${icon} ${LABEL_FOR_BACKBONE[id]} (${id})`;
+        const description = installed
+            ? "installed"
+            : `not installed — install with: ${meta.installHint}`;
+        return {
+            value: { providerID: PROVIDER_FOR_BACKBONE[id], modelID: "default" },
+            label,
+            description,
+            disabled: !installed,
+        };
+    });
+    const backboneSelection = await deps.renderAndWait((resolve) => React.createElement(ConfigPrompt, {
+        options: backbonePickerOptions,
+        onSelect: resolve,
+        title: "Select a provider backbone:",
+    }));
+    // Copilot path — no opencode server needed.
+    if (backboneSelection.providerID === "github-copilot") {
+        await deps.saveProjectConfig({ model: backboneSelection });
+        console.log(`\n  \u2713 Configuration saved to .hem/config.json\n`);
+        console.log(`    Provider: ${backboneSelection.providerID}`);
+        console.log(`    Model:    ${backboneSelection.modelID} (copilot picks a default)\n`);
+        return cliOptions;
+    }
+    // Opencode path — start the server and continue with the existing
+    // auth-detect + sub-provider/model selection flow.
     const { client, server } = await deps.startWithRetry(async () => {
         const port = await deps.findFreePort();
         return deps.createOpencode({ port });
@@ -976,7 +1095,7 @@ export async function handleConfig(deps = defaultDeps) {
             }
         }
         // Present config prompt with connected providers.
-        const model = await selectProviderAndModel(deps, client, authState.connectedProviders);
+        const model = await selectProviderAndModel(deps, client, authState.connectedProviders, availability);
         await deps.saveProjectConfig({ model });
         console.log(`\n  \u2713 Configuration saved to .hem/config.json\n`);
         console.log(`    Provider: ${model.providerID}`);

package/dist/orchestrator.d.ts

@@ -22,15 +22,17 @@ import type { GenerateCLIOptions, FileGroup, GenerationContext, GenerationResult
 import { DocumentationAgent } from "./agents/documentation-agent.js";
 import { ExplorationAgent } from "./agents/exploration-agent.js";
 import type { SearchIndex } from "./search-index.js";
-export { READ_ONLY_BASH, ORG_AGENT_BASH } from "./providers/index.js";
 /**
  * Total file count threshold above which multi-agent exploration is activated.
  * Below this threshold, the existing 1-agent-per-group behavior is used.
+ * Single source of truth lives in resources.ts; re-exported here for
+ * orchestrator-local callers and tests that reference it through this module.
  */
-export declare const LARGE_PROJECT_THRESHOLD = 200;
+import { LARGE_PROJECT_THRESHOLD } from "./resources.js";
+export { LARGE_PROJECT_THRESHOLD };
 /**
  * Hard ceiling on exploration sub-agents per group.
- * Actual count is computed by `computeAgentsPerGroup()`.
+ * Actual count is computed by `computeExplorationAgentsPerGroup()`.
  */
 export declare const MAX_EXPLORATION_AGENTS_PER_GROUP = 8;
 /**
@@ -38,8 +40,13 @@ export declare const MAX_EXPLORATION_AGENTS_PER_GROUP = 8;
  * total file count. Returns 1 (no splitting) when below the threshold.
  *
  * Scaling: starts at 4 agents at the threshold, grows to MAX at 2x the threshold.
+ *
+ * Distinct from {@link import("./resources.js").computeAgentsPerGroup} —
+ * resources.ts has a different formula clamped to the system resource ceiling
+ * and is used by the verbose CLI scaling log; this exploration-specific
+ * version drives orchestrator-internal partitioning.
  */
-export declare function computeAgentsPerGroup(totalFiles: number): number;
+export declare function computeExplorationAgentsPerGroup(totalFiles: number): number;
 /**
  * Partition a group's files into N sub-groups for parallel exploration.
  * Uses round-robin assignment (files sorted by path for determinism).

package/dist/orchestrator.js

@@ -23,17 +23,18 @@ import pLimit from "p-limit";
 import fg from "fast-glob";
 import { AuthExpiredError } from "./auth.js";
 import { computeMaxConcurrency, describeResourceLimits } from "./resources.js";
-// Re-export permission constants from provider module for backward compatibility.
-export { READ_ONLY_BASH, ORG_AGENT_BASH } from "./providers/index.js";
 // ── Multi-Agent Exploration Constants ────────────────────────────────
 /**
  * Total file count threshold above which multi-agent exploration is activated.
  * Below this threshold, the existing 1-agent-per-group behavior is used.
+ * Single source of truth lives in resources.ts; re-exported here for
+ * orchestrator-local callers and tests that reference it through this module.
  */
-export const LARGE_PROJECT_THRESHOLD = 200;
+import { LARGE_PROJECT_THRESHOLD } from "./resources.js";
+export { LARGE_PROJECT_THRESHOLD };
 /**
  * Hard ceiling on exploration sub-agents per group.
- * Actual count is computed by `computeAgentsPerGroup()`.
+ * Actual count is computed by `computeExplorationAgentsPerGroup()`.
  */
 export const MAX_EXPLORATION_AGENTS_PER_GROUP = 8;
 /**
@@ -46,8 +47,13 @@ const MIN_FILES_PER_AGENT = 3;
  * total file count. Returns 1 (no splitting) when below the threshold.
  *
  * Scaling: starts at 4 agents at the threshold, grows to MAX at 2x the threshold.
+ *
+ * Distinct from {@link import("./resources.js").computeAgentsPerGroup} —
+ * resources.ts has a different formula clamped to the system resource ceiling
+ * and is used by the verbose CLI scaling log; this exploration-specific
+ * version drives orchestrator-internal partitioning.
  */
-export function computeAgentsPerGroup(totalFiles) {
+export function computeExplorationAgentsPerGroup(totalFiles) {
     if (totalFiles < LARGE_PROJECT_THRESHOLD)
         return 1;
     const ratio = totalFiles / LARGE_PROJECT_THRESHOLD;
@@ -394,7 +400,7 @@ export async function runExploration(explorationAgent, groups, options, onProgre
     }));
     // Compute total file count to determine if multi-agent exploration is needed
     const totalFiles = groups.reduce((sum, g) => sum + g.files.length, 0);
-    const agentsPerGroup = computeAgentsPerGroup(totalFiles);
+    const agentsPerGroup = computeExplorationAgentsPerGroup(totalFiles);
     const isMultiAgent = agentsPerGroup > 1;
     if (verbose && isMultiAgent) {
         verbose(`[orchestrator] Large project detected: ${totalFiles} files → ${agentsPerGroup} agents per group`);
@@ -841,7 +847,7 @@ export async function generateDocumentation(agent, groups, options, onProgress,
     });
     // ── Multi-agent documentation detection ──────────────────────────
     const totalFiles = groups.reduce((sum, g) => sum + g.files.length, 0);
-    const docAgentsPerGroup = computeAgentsPerGroup(totalFiles);
+    const docAgentsPerGroup = computeExplorationAgentsPerGroup(totalFiles);
     const isMultiAgentDoc = docAgentsPerGroup > 1;
     if (verbose) {
         verbose(`[orchestrator] Starting documentation: ${groups.length} groups, concurrency=${sharedConcurrency} (shared with exploration)` +

package/dist/progress.d.ts

@@ -94,6 +94,15 @@ export interface ConfigOption {
     label: string;
     /** Optional description shown below the label. */
     description?: string;
+    /**
+     * When true, the option is rendered in red (with a leading red marker
+     * supplied by the label) and is **not selectable** — arrow-key
+     * navigation skips over it and Enter does nothing while it is the
+     * "logical" selection. Used for backbones whose CLI is not installed
+     * so the user sees what's missing without being able to pick a broken
+     * choice.
+     */
+    disabled?: boolean;
 }
 /** Props for the ConfigPrompt component. */
 export interface ConfigPromptProps {

package/dist/progress.js

@@ -209,7 +209,15 @@ export function FreeModelPicker({ models, onSelect, }) {
  * following the same navigation pattern as AuthPrompt.
  */
 export function ConfigPrompt({ options, onSelect, title, maxVisible, }) {
-    const [navState, setNavState] = useState({ selectedIndex: 0, viewportStart: 0 });
+    // Find the first selectable (non-disabled) option to use as the initial
+    // cursor position. If every option is disabled, fall back to 0 so the
+    // picker renders without crashing — Enter will simply be a no-op.
+    const firstSelectable = options.findIndex((o) => !o.disabled);
+    const initialIndex = firstSelectable === -1 ? 0 : firstSelectable;
+    const [navState, setNavState] = useState({
+        selectedIndex: initialIndex,
+        viewportStart: 0,
+    });
     const { selectedIndex, viewportStart } = navState;
     const { stdout } = useStdout();
     // Mirror selectedIndex into a ref so the ENTER branch below reads the latest
@@ -219,28 +227,42 @@ export function ConfigPrompt({ options, onSelect, title, maxVisible, }) {
     // Fixed overhead: header(2) + footer(2) + up-indicator(1) + down-indicator(1) = 6
     const terminalRows = stdout?.rows ?? 24;
     const maxVis = maxVisible ?? Math.max(3, Math.floor((terminalRows - 6) / 2));
+    // Skip disabled entries while navigating with arrow keys so the cursor
+    // never lands on an unselectable option.
+    const nextSelectable = (from, dir) => {
+        let i = from + dir;
+        while (i >= 0 && i < options.length) {
+            if (!options[i].disabled)
+                return i;
+            i += dir;
+        }
+        return null;
+    };
     // Use functional updater form so rapid key presses don't read stale state.
     useInput((input, key) => {
         if (key.upArrow) {
             setNavState((prev) => {
-                if (prev.selectedIndex <= 0)
+                const next = nextSelectable(prev.selectedIndex, -1);
+                if (next === null)
                     return prev;
-                const next = prev.selectedIndex - 1;
                 const newViewport = next < prev.viewportStart ? next : prev.viewportStart;
                 return { selectedIndex: next, viewportStart: newViewport };
             });
         }
         else if (key.downArrow) {
             setNavState((prev) => {
-                if (prev.selectedIndex >= options.length - 1)
+                const next = nextSelectable(prev.selectedIndex, 1);
+                if (next === null)
                     return prev;
-                const next = prev.selectedIndex + 1;
                 const newViewport = next >= prev.viewportStart + maxVis ? next - maxVis + 1 : prev.viewportStart;
                 return { selectedIndex: next, viewportStart: newViewport };
             });
         }
         else if (key.return && options.length > 0) {
-            onSelect(options[selectedIndexRef.current].value);
+            const current = options[selectedIndexRef.current];
+            if (current && !current.disabled) {
+                onSelect(current.value);
+            }
         }
     });
     const visibleOptions = options.slice(viewportStart, viewportStart + maxVis);
@@ -250,7 +272,14 @@ export function ConfigPrompt({ options, onSelect, title, maxVisible, }) {
                 const index = viewportStart + i;
                 const isSelected = index === selectedIndex;
                 const pointer = isSelected ? "\u276F" : " ";
-                return (_jsxs(Box, { flexDirection: "column", marginLeft: 2, children: [_jsx(Text, { children: _jsxs(Text, { color: isSelected ? "cyan" : undefined, bold: isSelected, children: [pointer, " ", option.label] }) }), option.description && (_jsx(Text, { children: _jsxs(Text, { dimColor: true, children: ["      ", option.description] }) })), i < visibleOptions.length - 1 && _jsx(Text, { children: "" })] }, `${option.value.providerID}/${option.value.modelID}`));
+                // Disabled options always render dim red regardless of cursor
+                // position so they read as "informational, not selectable".
+                const labelColor = option.disabled
+                    ? "red"
+                    : isSelected
+                        ? "cyan"
+                        : undefined;
+                return (_jsxs(Box, { flexDirection: "column", marginLeft: 2, children: [_jsx(Text, { children: _jsxs(Text, { color: labelColor, bold: isSelected && !option.disabled, dimColor: option.disabled, children: [pointer, " ", option.label] }) }), option.description && (_jsx(Text, { children: _jsxs(Text, { dimColor: true, color: option.disabled ? "red" : undefined, children: ["      ", option.description] }) })), i < visibleOptions.length - 1 && _jsx(Text, { children: "" })] }, `${option.value.providerID}/${option.value.modelID}`));
             }), hasBelow && (_jsx(Box, { marginLeft: 2, children: _jsxs(Text, { dimColor: true, children: ["  ", "\u2193 ", options.length - viewportStart - maxVis, " more below"] }) })), _jsx(Box, { marginTop: 1, marginLeft: 2, children: _jsxs(Text, { dimColor: true, children: ["  ", "Use arrow keys to navigate, Enter to confirm."] }) })] }));
 }
 /** Ordered pipeline phases for display. */

package/dist/providers/copilot.js

@@ -171,7 +171,7 @@ export class CopilotProvider {
         this._config = config;
         this._factory = factory ?? (async (token) => {
             const { CopilotClient } = await import("@github/copilot-sdk");
-            const copilot = new CopilotClient(token ? { githubToken: token } : {});
+            const copilot = new CopilotClient(token ? { gitHubToken: token } : {});
             await copilot.start();
             return {
                 client: copilot,

package/dist/providers/index.d.ts

@@ -9,9 +9,6 @@
  * functions.  Adding a new provider only requires registering it here —
  * call sites use {@link createProviderFromConfig} and never branch on
  * provider IDs.
- *
- * Note: SessionClient, SessionTracker, CopilotSessionAdapter are no longer
- * exported — they are internal implementation details of the providers.
  */
 import type { Provider, ProviderConfig } from "./types.js";
 export type { Provider, ProviderConfig, SseEvent, } from "./types.js";
@@ -44,3 +41,39 @@ export declare const PROVIDER_REGISTRY: Readonly<Record<string, ProviderFactory>
  * `defaultDeps.createProvider` so provider selection lives in one place.
  */
 export declare function createProviderFromConfig(config: ProviderConfig): Promise<Provider>;
+/**
+ * Backbone identifier — the underlying CLI that ultimately runs a model.
+ *
+ * Hem currently has two: `opencode` (covers most third-party model providers
+ * via the OpenCode server) and `copilot` (the @github/copilot CLI used by
+ * {@link CopilotProvider}).
+ */
+export type Backbone = "opencode" | "copilot";
+/**
+ * Map of backbone → `{ cli, installHint }`. The `cli` field is the bare
+ * binary name expected on `PATH`; `installHint` is the suggested install
+ * command surfaced when the CLI is missing.
+ */
+export declare const BACKBONES: Readonly<Record<Backbone, {
+    cli: string;
+    installHint: string;
+}>>;
+/** Result of {@link getBackboneAvailability}: which backbones are usable. */
+export type BackboneAvailability = Record<Backbone, boolean>;
+/**
+ * Probe each known backbone CLI and return a presence map. Pure, cheap,
+ * synchronous — safe to call before any UI or server-startup decision so
+ * hem can degrade gracefully when, e.g., `opencode` is not installed but
+ * `copilot` is.
+ *
+ * @param check - Override for testing (defaults to {@link isCliAvailable}).
+ */
+export declare function getBackboneAvailability(check?: (name: string) => boolean): BackboneAvailability;
+/**
+ * Determine which backbone an opencode-style provider ID belongs to.
+ *
+ * Provider IDs in {@link PROVIDER_REGISTRY} (currently `github-copilot` and
+ * `copilot`) map to the copilot backbone; everything else flows through
+ * the opencode server.
+ */
+export declare function backboneForProviderID(providerID: string): Backbone;

package/dist/providers/index.js

@@ -9,12 +9,10 @@
  * functions.  Adding a new provider only requires registering it here —
  * call sites use {@link createProviderFromConfig} and never branch on
  * provider IDs.
- *
- * Note: SessionClient, SessionTracker, CopilotSessionAdapter are no longer
- * exported — they are internal implementation details of the providers.
  */
 import { OpenCodeProvider } from "./opencode.js";
 import { CopilotProvider } from "./copilot.js";
+import { isCliAvailable } from "../server-utils.js";
 export { OpenCodeProvider, READ_ONLY_BASH, ORG_AGENT_BASH } from "./opencode.js";
 export { CopilotProvider } from "./copilot.js";
 /**
@@ -44,3 +42,42 @@ export function createProviderFromConfig(config) {
     const factory = PROVIDER_REGISTRY[config.model.providerID] ?? DEFAULT_PROVIDER_FACTORY;
     return factory(config);
 }
+/**
+ * Map of backbone → `{ cli, installHint }`. The `cli` field is the bare
+ * binary name expected on `PATH`; `installHint` is the suggested install
+ * command surfaced when the CLI is missing.
+ */
+export const BACKBONES = Object.freeze({
+    opencode: {
+        cli: "opencode",
+        installHint: "npm install -g opencode-ai  (https://opencode.ai)",
+    },
+    copilot: {
+        cli: "copilot",
+        installHint: "npm install -g @github/copilot",
+    },
+});
+/**
+ * Probe each known backbone CLI and return a presence map. Pure, cheap,
+ * synchronous — safe to call before any UI or server-startup decision so
+ * hem can degrade gracefully when, e.g., `opencode` is not installed but
+ * `copilot` is.
+ *
+ * @param check - Override for testing (defaults to {@link isCliAvailable}).
+ */
+export function getBackboneAvailability(check = isCliAvailable) {
+    return {
+        opencode: check(BACKBONES.opencode.cli),
+        copilot: check(BACKBONES.copilot.cli),
+    };
+}
+/**
+ * Determine which backbone an opencode-style provider ID belongs to.
+ *
+ * Provider IDs in {@link PROVIDER_REGISTRY} (currently `github-copilot` and
+ * `copilot`) map to the copilot backbone; everything else flows through
+ * the opencode server.
+ */
+export function backboneForProviderID(providerID) {
+    return providerID in PROVIDER_REGISTRY ? "copilot" : "opencode";
+}

package/dist/providers/types.d.ts

@@ -13,9 +13,15 @@
  * Also exposes low-level `session` and `event` properties for agents that
  * need direct session control (OrganizationAgent, CrossRefAgent, etc.).
  */
-import type { SseEvent } from "../session.js";
 import type { ModelSelection, AgentPermissionConfig } from "../types.js";
-export type { SseEvent };
+/**
+ * Minimal SSE event type for broadcast interception.
+ * We only need to match `message.part.updated` and `session.created` events.
+ */
+export interface SseEvent {
+    type: string;
+    properties: Record<string, unknown>;
+}
 /**
  * Configuration for initializing an LLM provider.
  *

package/dist/server-utils.d.ts

@@ -9,6 +9,31 @@
  *     (SIGINT, SIGTERM, SIGHUP, uncaughtException, unhandledRejection),
  *     preventing zombie child processes.
  */
+/** Injectable lookup function for {@link requireCli}; defaults to `execFileSync`. */
+export type CliLookup = (cmd: string, args: readonly string[]) => unknown;
+/**
+ * Probe whether a CLI is reachable on `PATH` without throwing.
+ *
+ * The opencode and copilot SDKs both `spawn(name)` without first checking
+ * that the binary is reachable, so a missing install surfaces as the
+ * cryptic `spawn <name> ENOENT`. Callers use this to gate UI behaviour
+ * (e.g. mark a provider as "not installed") before invoking the SDK.
+ *
+ * @param name   - Bare CLI name (no path components).
+ * @param lookup - Override for testing (defaults to `execFileSync`).
+ */
+export declare function isCliAvailable(name: string, lookup?: CliLookup): boolean;
+/**
+ * Like {@link isCliAvailable} but throws an actionable error when the CLI
+ * is missing. Use at the boundary where a CLI MUST be present (e.g. just
+ * before spawning it) to surface a clean message instead of `spawn ENOENT`.
+ *
+ * @param name   - Bare CLI name (no path components).
+ * @param hint   - Optional install instruction appended to the message.
+ * @param lookup - Override for testing (defaults to `execFileSync`).
+ * @throws Error with a descriptive message when the CLI is not found.
+ */
+export declare function requireCli(name: string, hint?: string, lookup?: CliLookup): void;
 /**
  * Find a free TCP port on 127.0.0.1.
  *

package/dist/server-utils.js

@@ -9,7 +9,49 @@
  *     (SIGINT, SIGTERM, SIGHUP, uncaughtException, unhandledRejection),
  *     preventing zombie child processes.
  */
+import { execFileSync } from "node:child_process";
 import { createServer } from "node:net";
+const defaultLookup = (cmd, args) => execFileSync(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
+/** Platform-appropriate `which`/`where` binary name for CLI lookup. */
+function pathFinder() {
+    return process.platform === "win32" ? "where" : "which";
+}
+/**
+ * Probe whether a CLI is reachable on `PATH` without throwing.
+ *
+ * The opencode and copilot SDKs both `spawn(name)` without first checking
+ * that the binary is reachable, so a missing install surfaces as the
+ * cryptic `spawn <name> ENOENT`. Callers use this to gate UI behaviour
+ * (e.g. mark a provider as "not installed") before invoking the SDK.
+ *
+ * @param name   - Bare CLI name (no path components).
+ * @param lookup - Override for testing (defaults to `execFileSync`).
+ */
+export function isCliAvailable(name, lookup = defaultLookup) {
+    try {
+        lookup(pathFinder(), [name]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Like {@link isCliAvailable} but throws an actionable error when the CLI
+ * is missing. Use at the boundary where a CLI MUST be present (e.g. just
+ * before spawning it) to surface a clean message instead of `spawn ENOENT`.
+ *
+ * @param name   - Bare CLI name (no path components).
+ * @param hint   - Optional install instruction appended to the message.
+ * @param lookup - Override for testing (defaults to `execFileSync`).
+ * @throws Error with a descriptive message when the CLI is not found.
+ */
+export function requireCli(name, hint, lookup = defaultLookup) {
+    if (isCliAvailable(name, lookup))
+        return;
+    const suffix = hint ? `\n${hint}` : "";
+    throw new Error(`Required CLI "${name}" was not found on PATH.${suffix}`);
+}
 // ── Free port discovery ─────────────────────────────────────────────
 /**
  * Find a free TCP port on 127.0.0.1.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pruddiman/hem",
-  "version": "0.0.1-beta-1aff12a",
+  "version": "0.0.1-beta-1ec07ab",
   "type": "module",
   "bin": {
     "hem": "./dist/index.js"
@@ -21,9 +21,10 @@
     "publish:beta": "node scripts/publish-beta.mjs"
   },
   "dependencies": {
-    "@github/copilot-sdk": "^0.2.2",
+    "@github/copilot-sdk": "^0.3.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@opencode-ai/sdk": "^1.14.19",
+    "@opencode-ai/sdk": "^1.14.48",
+    "@pruddiman/hem": "^0.0.1-beta-1aff12a",
     "better-sqlite3": "^12.8.0",
     "commander": "^14.0.3",
     "fast-glob": "^3.3.3",