@interf/compiler 0.9.5 → 0.16.0

package/dist/packages/{agents → engine/agents}/lib/shells.js

@@ -1,14 +1,14 @@
 import { cpSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, symlinkSync, } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, dirname, join, relative } from "node:path";
+import { basename, dirname, join, relative, sep as pathSep } from "node:path";
 import { CHART_APPROXIMATION_NOTES } from "./chart-guidance.js";
-import { projectRawSnapshot } from "../../compiler/raw-snapshot.js";
-import { METHOD_PACKAGE_DIR } from "../../project-model/interf-detect.js";
-import { CONTEXT_INTERFACE_FILE as METHOD_SCHEMA_FILE, contextInterfaceZoneAbsolutePath as compiledZoneAbsolutePath, readContextInterface as readCompiledSchemaFile, resolveContextInterfacePath as resolveMethodSchemaPath, } from "../../method-package/context-interface.js";
-import { stageExecutionShellsRoot, methodImprovementLoopRoot, methodPackagePathForCompiled, compiledInterfConfigPath, compiledRuntimeRoot, } from "../../compiler/compiled-paths.js";
-import { ensureCompiledZoneTargets } from "../../compiler/compiled-schema.js";
-import { listFilesRecursive } from "../../shared/filesystem.js";
-import { resolveMethodImprovementReviewSourcePaths } from "../../method-package/method-review-paths.js";
+import { buildCompiledSourceFiles } from "../../compile/source-files.js";
+import { METHOD_PACKAGE_DIR } from "../../../project/interf-detect.js";
+import { CONTEXT_INTERFACE_FILE as METHOD_SCHEMA_FILE, contextInterfaceZoneAbsolutePath as compiledZoneAbsolutePath, readContextInterface as readCompiledSchemaFile, resolveContextInterfacePath as resolveMethodSchemaPath, } from "../../../methods/package/context-interface.js";
+import { stageExecutionShellsRoot, methodImprovementLoopRoot, methodPackagePathForCompiled, compiledInterfConfigPath, compiledRuntimeRoot, compiledRuntimeSourceSnapshotPath, compiledRuntimeStageInputsPath, } from "../../compile/compiled-paths.js";
+import { ensureCompiledZoneTargets } from "../../compile/compiled-schema.js";
+import { listFilesRecursive } from "../../../contracts/utils/filesystem.js";
+import { resolveMethodImprovementReviewSourcePaths } from "../../../methods/package/method-review-paths.js";
 const LOCAL_SKILL_ROOTS = [
     ".claude/skills",
     ".codex/skills",
@@ -54,12 +54,12 @@ export function renderCompiledAgents(compiledPath, name, methodId, about, option
         "",
         "1. Use the local native `interf-query` skill that Interf generated for this portable context.",
         "2. Let the Method docs and declared output zones guide retrieval instead of assuming a fixed note layout.",
-        "3. Use `raw/` when you need direct quotes, exact chart values, table lookups, or verification.",
+        "3. Use `.interf/runtime/source-snapshot.json` when you need to inspect the source references behind the output.",
         "",
         "## How this portable context works",
         "",
         "- The Method package defines the context interface this portable context implements on disk.",
-        "- `.interf/interf.json` points to the local `raw/` snapshot via `source.path` and back to the Interf Workspace via `source.control_path`.",
+        "- `.interf/interf.json` records the selected source binding and back-reference to the Interf Workspace.",
         `- Method seed: \`${methodOriginSelected}\`.`,
         ...(methodLocalDraft
             ? ["- This portable context now carries a local Method draft improved from that seed. Recompiling this portable context reuses the local `.interf/method/` package."]
@@ -71,36 +71,34 @@ export function renderCompiledAgents(compiledPath, name, methodId, about, option
         "- `.interf/method/use/query/` is the editable source for the generated native query shell.",
         "- `.interf/method/compile/stages/` defines stage-specific docs that Interf projects into native execution shells for automated runs.",
         "- Native local query skills are generated under local agent skill directories such as `.claude/skills/` and `.codex/skills/`.",
-        "- `raw/` contains the local raw snapshot used for evidence and verification.",
+        "- `.interf/runtime/source-snapshot.json` records the source files assigned to the latest runtime snapshot.",
         `- Method zones are declared in \`.interf/method/${METHOD_SCHEMA_FILE}\`.`,
         ...zoneLines,
         "- `.interf/runtime/` holds runtime artifacts written by Interf.",
         "- `.interf/tests/` mirrors the latest saved readiness-check run and keeps detailed target runs plus preserved sandboxes.",
-        "- `.interf/tests/targets/` holds detailed raw and compiled target runs plus preserved test sandboxes.",
+        "- `.interf/tests/targets/` holds detailed source-files and compiled target runs plus preserved test sandboxes.",
         "",
         "## Manual query rules",
         "",
-        "- Prefer the Method-declared context outputs before `raw/`.",
+        "- Prefer the Method-declared context outputs before source re-checks.",
         "- Use the generated native `interf-query` skill for manual querying. The editable source lives at `.interf/method/use/query/SKILL.md`.",
         "- Treat `.interf/` as method/runtime metadata, not answer evidence, unless explicitly asked to inspect Method or test history.",
-        "- Use `raw/` for quotes, verification, ambiguity, or evidence the portable context does not expose well.",
-        "- If exact chart, table, or image-derived evidence matters, inspect the raw source and say whether the answer was text-derived, table-derived, or chart-derived.",
+        "- Use `.interf/runtime/source-snapshot.json` to find source references for quotes, verification, ambiguity, or evidence the portable context does not expose well.",
+        "- If exact chart, table, or image-derived evidence matters, inspect the source reference and say whether the answer was text-derived, table-derived, or chart-derived.",
         "",
         "## Commands",
         "",
         "```",
         "interf compile            build this portable context",
-        "interf test               run checks against this portable context",
-        "interf verify stage <id>  verify one Method stage",
-        "interf verify portable-context    verify the full portable context output",
+        "interf verify               run checks against this portable context",
         "interf status             show deterministic health",
         "```",
         "",
         "## Rules",
         "",
-        "- Do not modify files under `raw/`.",
+        "- Do not modify source files while answering from this portable context.",
         "- Treat prepared notes as working context, not final truth.",
-        "- When confidence is low, verify against `raw/` before answering strongly.",
+        "- When confidence is low, verify against the source references before answering strongly.",
         "",
     ].join("\n");
 }
@@ -112,38 +110,38 @@ export function renderCompiledQuerySkill() {
         "",
         "Default loop:",
         "1. Read `.interf/method/README.md` and this file first.",
-        `2. Use the Method zones declared in \`.interf/method/${METHOD_SCHEMA_FILE}\` before consulting \`raw/\`.`,
-        "3. Use `raw/` for direct quotes, verification, exact lookups, and cases where the portable context is missing the needed evidence or is ambiguous.",
+        `2. Use the Method zones declared in \`.interf/method/${METHOD_SCHEMA_FILE}\` before consulting source references.`,
+        "3. Use `.interf/runtime/source-snapshot.json` for direct quotes, verification, exact lookups, and cases where the portable context is missing the needed evidence or is ambiguous.",
         "",
         "Answering rule:",
-        "- do not modify files under `raw/`",
+        "- do not modify source files while answering",
         "- treat the Method as the portable-context contract and use its zones as the working retrieval surface",
-        "- say explicitly when an answer depends on approximation, bounded inference, or a raw-source re-check",
-        "- use `raw/` to confirm source page, metric family, provenance, or exact wording when the portable context is missing the needed evidence or is ambiguous",
+        "- say explicitly when an answer depends on approximation, bounded inference, or a source re-check",
+        "- use source references to confirm source page, metric family, provenance, or exact wording when the portable context is missing the needed evidence or is ambiguous",
         "- do not invent navigation or note structure beyond what this Method declares",
-        "- when the portable context is insufficient, verify in `raw/` and then answer",
+        "- when the portable context is insufficient, verify against source references and then answer",
         "",
         "You can edit this file to bias manual question-answering behavior for this portable context.",
         "",
     ].join("\n");
 }
-function renderRawTestAgents() {
+function renderSourceFilesTestAgents() {
     const chartNotes = CHART_APPROXIMATION_NOTES.map((note) => `- ${note}`);
     return [
-        "# Raw Test Shell",
+        "# Source Files Test Shell",
         "",
-        "This is an isolated raw-files test shell generated by Interf.",
+        "This is an isolated source-files test shell generated by Interf.",
         "There is no portable context in this shell.",
         "",
         "## How to use this shell",
         "",
         "1. Read this file first.",
         "2. Use the local native `interf-query` skill available in this shell.",
-        "3. Read only from `raw/`.",
+        "3. Read `runtime/source-files.json` and use only the listed source references.",
         "",
         "## Rules",
         "",
-        "- Answer only from the files under `raw/`.",
+        "- Answer only from source files listed in `runtime/source-files.json`.",
         "- There is no portable context here, so do not assume any portable-context output zones exist.",
         "- Do not treat hidden runtime files or test artifacts as evidence.",
         ...chartNotes,
@@ -151,23 +149,23 @@ function renderRawTestAgents() {
         "",
     ].join("\n");
 }
-function renderRawTestQuerySkill() {
+function renderSourceFilesTestQuerySkill() {
     const chartNotes = CHART_APPROXIMATION_NOTES.map((note, index) => `${index + 3}. ${note}`);
     return [
         "---",
         "name: interf-query",
         "description: >",
-        "  Native local query skill for an Interf raw test shell. Use it only",
-        "  to answer source-files readiness checks directly from `raw/`.",
+        "  Native local query skill for an Interf source-files test shell. Use it only",
+        "  to answer source-files readiness checks from `runtime/source-files.json` references.",
         "---",
         "",
-        "# Interf Raw Test Query",
+        "# Interf Source Files Test Query",
         "",
-        "This is the native local query skill for an isolated raw-files test shell.",
+        "This is the native local query skill for an isolated source-files test shell.",
         "",
         "Loop:",
-        "1. Read `raw/` directly.",
-        "2. Verify exact claims against the raw files before answering strongly.",
+        "1. Read `runtime/source-files.json`.",
+        "2. Verify exact claims against the listed source locators before answering strongly.",
         ...chartNotes,
         "8. Do not rely on portable-context artifacts because they do not exist in this shell.",
         "",
@@ -225,6 +223,11 @@ function linkPath(targetPath, linkPathname) {
     mkdirSync(dirname(linkPathname), { recursive: true });
     symlinkSync(targetPath, linkPathname);
 }
+function linkIfExists(targetPath, linkPathname) {
+    if (!existsSync(targetPath))
+        return;
+    linkPath(targetPath, linkPathname);
+}
 function linkRelativePath(targetPath, linkPathname) {
     mkdirSync(dirname(linkPathname), { recursive: true });
     symlinkSync(relative(dirname(linkPathname), targetPath), linkPathname);
@@ -322,15 +325,18 @@ function renderStageExecutionAgents(compiledName, methodId, stage) {
         "## Start Here",
         "",
         "1. Read `runtime/stage-contract.json` now.",
-        "2. Read `runtime/paths.json` now.",
-        "3. Use the local native `interf-stage` skill now.",
-        `4. Execute only the current stage: \`${stage.id}\` (${stage.label}).`,
+        "2. Read `runtime/source-snapshot.json` and `runtime/stage-inputs.json` now.",
+        "3. Read `runtime/paths.json` now.",
+        "4. Use the local native `interf-stage` skill now.",
+        `5. Execute only the current stage: \`${stage.id}\` (${stage.label}).`,
         "",
         "## Shell ABI",
         "",
         "- `inputs/<zone-id>/` = read mounts for the current stage.",
         "- `outputs/<zone-id>/` = write mounts for the current stage.",
         "- For file zones, `runtime/paths.json` points to the exact file path inside those mount roots.",
+        "- `runtime/source-snapshot.json` = source references captured for this run.",
+        "- `runtime/stage-inputs.json` = exact source references assigned to this stage.",
         "- declared compiled zone paths are also projected at the shell root so Method-relative contract paths stay valid.",
         "- `runtime/` = stage contract and machine-readable path map for this shell.",
         "- `method/` = Method metadata, `method.schema.json`, and docs for the current stage only.",
@@ -371,7 +377,8 @@ function renderStageExecutionSkill(stage, stageMethodDoc) {
         "",
         "This local native skill exists for automated Interf stage execution.",
         "Read `runtime/stage-contract.json` first.",
-        "Then read `runtime/paths.json` and use the mounted `inputs/` and `outputs/` zones for this stage.",
+        "Then read `runtime/source-snapshot.json`, `runtime/stage-inputs.json`, and `runtime/paths.json`.",
+        "Use the assigned source references and the mounted `inputs/` and `outputs/` zones for this stage.",
         "Do not switch into manual query mode.",
         "",
         "## Current Stage",
@@ -399,7 +406,7 @@ function renderCompiledQueryNativeSkill(querySkillContent) {
         "name: interf-query",
         "description: >",
         "  Native local query skill for this portable context built by Interf.",
-        "  Use it for manual questions against the portable context and source files under raw/.",
+        "  Use it for manual questions against the portable context and source references.",
         "---",
         "",
         "# Interf Query",
@@ -568,6 +575,44 @@ function shouldSkipFrozenStageShellRelativePath(relativePath) {
         normalized.endsWith("/improvement-loops") ||
         normalized.includes("/improvement-loops/");
 }
+/**
+ * System path prefixes a malicious symlink in a Method package must
+ * never reach. Without this, the freeze-snapshot logic could be
+ * tricked into copying anything the running user has access to —
+ * `/etc/passwd`, `~/.ssh/id_rsa`, etc. (CSO finding).
+ *
+ * We deliberately allow targets that escape the immediate freeze
+ * root: legitimate execution shells contain symlinks pointing back
+ * to the parent workspace's `interf.json`. The threat is only links
+ * that resolve into truly system-level paths.
+ */
+const FORBIDDEN_SYMLINK_TARGET_PREFIXES = [
+    "/etc",
+    "/sys",
+    "/proc",
+    "/dev",
+    "/var/run",
+    "/var/lib",
+    "/usr",
+    "/bin",
+    "/sbin",
+    "/boot",
+    "/root",
+];
+function ensureSymlinkTargetSafe(realTarget, symlinkPath) {
+    for (const prefix of FORBIDDEN_SYMLINK_TARGET_PREFIXES) {
+        if (realTarget === prefix || realTarget.startsWith(`${prefix}${pathSep}`)) {
+            throw new Error(`Refusing to follow symlink ${symlinkPath} → ${realTarget}: ` +
+                `resolves into system directory ${prefix}.`);
+        }
+    }
+    // Also refuse links that escape into another user's SSH directory
+    // even if the path is not on the literal forbidden list.
+    if (/\/\.ssh(\/|$)/.test(realTarget)) {
+        throw new Error(`Refusing to follow symlink ${symlinkPath} → ${realTarget}: ` +
+            `targets a .ssh directory.`);
+    }
+}
 function copyResolvedTree(options) {
     const relativePath = options.relativePath ?? "";
     if (options.shellType === "stage-execution" && shouldSkipFrozenStageShellRelativePath(relativePath)) {
@@ -575,7 +620,24 @@ function copyResolvedTree(options) {
     }
     const stat = lstatSync(options.sourcePath);
     if (stat.isSymbolicLink()) {
+        // existsSync follows symlinks, so a dangling link (target absent)
+        // returns false. Skip those entries: realpathSync would throw
+        // ENOENT, and the freeze step is best-effort review material —
+        // losing one unresolvable link is better than aborting the whole
+        // snapshot. Production trigger: createStageExecutionShell links
+        // runtime/stage-contract.json before writeStageContract runs, so
+        // any failure between those two points leaves a dangling link
+        // that the per-stage finally-block freeze would otherwise hit.
+        if (!existsSync(options.sourcePath)) {
+            return { materializedSymlinks: 0 };
+        }
         const realTarget = realpathSync(options.sourcePath);
+        // Refuse symlinks resolving into system paths (CSO finding). We
+        // deliberately allow links that escape the immediate freeze root
+        // because legitimate execution shells contain links back to the
+        // parent workspace's interf.json — the only thing we care about
+        // is that the realpath does not land in /etc, /sys, /proc, etc.
+        ensureSymlinkTargetSafe(realTarget, options.sourcePath);
         const realStat = statSync(realTarget);
         if (realStat.isDirectory()) {
             const mappedTarget = options.materializedRealPaths?.get(realTarget);
@@ -672,7 +734,7 @@ function renderMethodAuthoringAgents(options) {
         "",
         "1. Read `runtime/authoring-context.json` now.",
         `2. Read \`method/README.md\`, \`method/method.json\`, and \`method/${METHOD_SCHEMA_FILE}\` now.`,
-        "3. Review `artifacts/source-folder/raw/`.",
+        "3. Read `runtime/source-files.json` and review the listed source locators.",
         "4. Use the local native `interf-method-author` skill now.",
         "",
         "## Boundaries",
@@ -712,7 +774,7 @@ function renderMethodAuthoringSkill() {
         "# Interf Method Authoring",
         "",
         "Read `runtime/authoring-context.json` first.",
-        "Then review the neutral Method package scaffold under `method/` and the raw snapshot under `artifacts/source-folder/raw/`.",
+        "Then review the neutral Method package scaffold under `method/`, read `runtime/source-files.json`, and inspect the listed source locators when needed.",
         "",
         "Rules:",
         "- edit only `method/`",
@@ -762,14 +824,7 @@ export function createMethodAuthoringShell(options) {
         },
     };
     writeFileSync(join(shellRoot, "runtime", "authoring-context.json"), `${JSON.stringify(context, null, 2)}\n`);
-    projectRawSnapshot({
-        sourcePath: options.sourceFolderPath,
-        destinationPath: join(shellRoot, "artifacts", "source-folder", "raw"),
-        compiledPath: shellRoot,
-        mode: "copy",
-        prune: true,
-        preserveTimestamps: true,
-    });
+    writeFileSync(join(shellRoot, "runtime", "source-files.json"), `${JSON.stringify(buildCompiledSourceFiles(shellRoot, options.sourceFolderPath), null, 2)}\n`);
     copyResolvedTree({
         sourcePath: options.methodPath,
         targetPath: join(shellRoot, "method"),
@@ -808,7 +863,7 @@ function renderMethodImprovementAgents(compiledName, methodId, loopIndex) {
         `- Method: \`${methodId}\`.`,
         `- Improvement loop: ${loopIndex}.`,
         "- Edit only files under `method/`.",
-        "- Do not edit checks, test specs, raw files, or generated context outputs.",
+        "- Do not edit checks, test specs, source files, or generated context outputs.",
         "- Review context outputs under `artifacts/compiled-view/` and test/runtime evidence under `artifacts/`.",
         "- Keep the Method package valid for the current compiler API and `method.schema.json`.",
         "- For acceptance criteria, use `zone_counts_at_least` for numeric fixed minimums and `zone_counts_at_least_counts` only for runtime count-key strings such as `source_total`.",
@@ -862,7 +917,7 @@ function projectCompiledReviewArtifactsSnapshot(compiledPath, shellRoot, schema)
     const compiledViewRoot = join(shellRoot, "artifacts", "compiled-view");
     mkdirSync(compiledViewRoot, { recursive: true });
     for (const zone of schema.zones) {
-        if (zone.kind === "runtime" || zone.path === "raw")
+        if (zone.kind === "runtime" || zone.path === "source-files")
             continue;
         const sourcePath = compiledZoneAbsolutePath(compiledPath, zone);
         if (!existsSync(sourcePath))
@@ -893,7 +948,9 @@ function projectCompiledRuntimeArtifacts(compiledPath, shellRoot) {
         "state.json",
         "health.json",
         "view-spec.json",
-        "raw-snapshot.json",
+        "source-files.json",
+        "source-snapshot.json",
+        "stages",
         "logs",
     ];
     for (const artifactName of artifactNames) {
@@ -908,8 +965,8 @@ export function projectCompiledQueryShell(compiledPath, compiledName, methodId,
     const querySkillContent = readCompiledQuerySkillSource(compiledPath);
     return writeNativeAgentSurface(compiledPath, agentsContent, "interf-query", renderCompiledQueryNativeSkill(querySkillContent));
 }
-export function projectRawTestQueryShell(rootPath) {
-    return writeNativeAgentSurface(rootPath, renderRawTestAgents(), "interf-query", renderRawTestQuerySkill());
+export function projectSourceFilesTestQueryShell(rootPath) {
+    return writeNativeAgentSurface(rootPath, renderSourceFilesTestAgents(), "interf-query", renderSourceFilesTestQuerySkill());
 }
 export function createStageExecutionShell(compiledPath, compiledName, methodId, stage, writeArtifacts = []) {
     const schema = ensureCompiledExecutionSurface(compiledPath);
@@ -922,6 +979,8 @@ export function createStageExecutionShell(compiledPath, compiledName, methodId,
     mkdirSync(join(shellRoot, "outputs"), { recursive: true });
     linkPath(compiledInterfConfigPath(compiledPath), join(shellRoot, "interf.json"));
     linkPath(join(compiledRuntimeRoot(compiledPath), "stage-contract.json"), shellRuntimePath(shellRoot, "stage-contract.json"));
+    linkIfExists(compiledRuntimeSourceSnapshotPath(compiledPath), shellRuntimePath(shellRoot, "source-snapshot.json"));
+    linkIfExists(compiledRuntimeStageInputsPath(compiledPath, stage.id), shellRuntimePath(shellRoot, "stage-inputs.json"));
     projectCompiledSchemaZones(compiledPath, shellRoot, schema, new Set([...stage.reads, ...stage.writes]), materializedZones);
     projectMethodMetadata(compiledPath, shellRoot, stage);
     projectStageZoneMountAliases(shellRoot, stage, schema);

package/dist/packages/{agents → engine/agents}/lib/user-config.d.ts

@@ -1,6 +1,8 @@
 import { type InterfUserConfig } from "./schema.js";
 export type { InterfUserConfig } from "./schema.js";
-export declare const INTERF_HOME: string;
-export declare const USER_CONFIG_PATH: string;
+/** `~/.interf/` (overridable via `INTERF_USER_HOME`). */
+export declare function interfHome(): string;
+/** `~/.interf/config.json` — local executor preferences. */
+export declare function userConfigPath(): string;
 export declare function loadUserConfig(): InterfUserConfig | null;
 export declare function saveUserConfig(config: InterfUserConfig): void;

package/dist/packages/engine/agents/lib/user-config.js

@@ -0,0 +1,24 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { readJsonFileWithSchema } from "../../../contracts/utils/parse.js";
+import { interfHomeRoot } from "../../../contracts/lib/preparation-paths.js";
+import { InterfUserConfigSchema } from "./schema.js";
+/** `~/.interf/` (overridable via `INTERF_USER_HOME`). */
+export function interfHome() {
+    return interfHomeRoot();
+}
+/** `~/.interf/config.json` — local executor preferences. */
+export function userConfigPath() {
+    return join(interfHome(), "config.json");
+}
+export function loadUserConfig() {
+    const configPath = userConfigPath();
+    if (!existsSync(configPath))
+        return null;
+    return readJsonFileWithSchema(configPath, "user config", InterfUserConfigSchema);
+}
+export function saveUserConfig(config) {
+    const home = interfHome();
+    mkdirSync(home, { recursive: true });
+    writeFileSync(userConfigPath(), JSON.stringify(config, null, 2) + "\n");
+}

package/dist/packages/engine/agents/registry.d.ts

@@ -0,0 +1,91 @@
+import { type AgentRecord, type AgentsRegistry, type RoleMap } from "../../contracts/lib/schema.js";
+export declare const AGENTS_REGISTRY_FILENAME = "agents.json";
+/** `~/.interf/agents.json` — persisted custom agents + role-map. */
+export declare function agentsRegistryPath(): string;
+/**
+ * Load just the persisted on-disk part of the registry. Built-in agents
+ * are NOT included — call `loadAgentsRegistry()` for the merged view.
+ *
+ * Returns `{ agents: [], role_map: {} }` when the file is missing or
+ * unreadable; persisted custom agents always have `source: "user"`.
+ */
+export declare function loadPersistedRegistry(): AgentsRegistry;
+/** Persist the on-disk part of the registry (custom agents + role-map). */
+export declare function savePersistedRegistry(registry: AgentsRegistry): void;
+/**
+ * Detect built-in agents present on this machine. Filtered to agents
+ * whose marker home directory exists; we do NOT require the command
+ * to be on PATH at registry read time — that's a runtime concern.
+ */
+export declare function detectBuiltinAgentRecords(): AgentRecord[];
+/**
+ * Same as `detectBuiltinAgentRecords()` but only includes agents the
+ * current Interf build can fully drive (Claude Code, Codex). Used by
+ * the role-router and the CLI / UI listing as the "available agents"
+ * set.
+ */
+export declare function detectAutomatableBuiltinAgentRecords(): AgentRecord[];
+/**
+ * Full advertisement set — all built-in agents Interf knows about,
+ * regardless of whether they are installed locally. Used by the
+ * "install cards" zero-state surface so the UI / wizard can offer
+ * the user choices to install.
+ */
+export declare function listKnownBuiltinAgents(): AgentRecord[];
+export interface ResolvedRegistry {
+    /** All currently usable agents — built-in detected + persisted custom. */
+    agents: AgentRecord[];
+    /** Role → agent-name. Includes any persisted user edits. */
+    roleMap: RoleMap;
+    /**
+     * The "active" / default agent. This is whatever the role-map's
+     * `general` row points at, falling back to the first available
+     * agent when `general` is unset or maps to something that no longer
+     * exists in `agents`.
+     */
+    activeAgent: AgentRecord | null;
+}
+/**
+ * Public entry point — read the persisted registry, merge with detected
+ * built-ins, and seed the default role-map on first read if needed.
+ *
+ * Does NOT write back to disk. Callers that mutate the registry should
+ * call `savePersistedRegistry()` explicitly with the persisted slice.
+ */
+export declare function loadAgentsRegistry(): ResolvedRegistry;
+/** Pure helper — like `loadAgentsRegistry()` but works off in-memory data. */
+export declare function resolveRegistry(persisted: AgentsRegistry, builtinDetected: AgentRecord[]): ResolvedRegistry;
+/**
+ * Update the role-map (full replace). Returns the persisted slice that
+ * was written.
+ */
+export declare function updateRoleMap(nextRoleMap: RoleMap): AgentsRegistry;
+/**
+ * Patch the role-map with a partial update. Empty-string values clear
+ * the role (it falls back to `general` / active agent at run time).
+ */
+export declare function patchRoleMap(patch: Record<string, string>): AgentsRegistry;
+/**
+ * Register a new custom agent. Throws if `name` collides with a known
+ * built-in or with an already-persisted custom agent.
+ */
+export declare function registerCustomAgent(input: {
+    name: string;
+    display_name: string;
+    command: string;
+}): AgentsRegistry;
+/**
+ * Unregister a custom agent. Throws if `name` matches a built-in or no
+ * custom record exists. Removes any role-map entry pointing at the
+ * removed agent.
+ */
+export declare function unregisterCustomAgent(name: string): AgentsRegistry;
+/**
+ * Set the "active" agent — i.e. the agent the role-map's `general` row
+ * points at. Also updates any role still pointing at the previous
+ * active agent so existing single-active-agent setups don't need
+ * per-role edits when switching agents.
+ *
+ * Throws if `name` is not in the merged agents list.
+ */
+export declare function setActiveAgent(name: string): AgentsRegistry;