specrails-core 6.2.2 → 6.4.0

package/dist/agent-runtime/verification-repair.js

@@ -0,0 +1,88 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { hostPrecondition, installEnvironment } from './compact/environment.js';
+import { guardrailEnabled } from './guardrails.js';
+const BLOCKER_KINDS = new Set(['network', 'credential', 'environment-variable', 'toolchain', 'setup', 'environment', 'scope']);
+const BLOCKER_TEXT_LIMIT = 2_000;
+/** Where a missing dependency install belongs: the nearest directory with a lockfile or manifest above the failing command, else the repository root. */
+const INSTALL_MARKERS = ['package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lock', 'bun.lockb', 'requirements.txt', 'pyproject.toml', 'go.mod', 'Cargo.toml'];
+export function installRoots(context, commands) {
+    const roots = [];
+    for (const command of commands) {
+        const repository = context.repositories.find(repo => repo.id === command.repositoryId);
+        if (!repository)
+            continue;
+        let directory = command.cwd;
+        let chosen = repository.path;
+        for (;;) {
+            const relative = path.relative(repository.path, directory);
+            if (relative.startsWith('..') || path.isAbsolute(relative))
+                break;
+            if (INSTALL_MARKERS.some(name => existsSync(path.join(directory, name)))) {
+                chosen = directory;
+                break;
+            }
+            if (!relative)
+                break;
+            directory = path.dirname(directory);
+        }
+        roots.push(chosen);
+    }
+    // Every repository root stays a candidate: its plan is a no-op when it is already installed.
+    return [...new Set([...roots, ...context.repositories.map(repository => repository.path)])];
+}
+/** A directory as the log should name it: relative to the checkout that contains it. */
+export function checkoutRelative(context, directory) {
+    const repository = context.repositories.find(repo => { const relative = path.relative(repo.path, directory); return !relative.startsWith('..') && !path.isAbsolute(relative); });
+    return repository ? path.relative(repository.path, directory).split(path.sep).join('/') || '.' : directory;
+}
+/** The legacy host-facing sentence for a blocker; engine v2 hosts read the structured blocker instead. */
+export function hostPreconditionMessage(reason, command, args, directory) {
+    return `Verification cannot run in this environment: ${reason} (\`${[command, ...args].join(' ')}\` in ${directory}). This is not a defect in the change, so no correction round was started. Make it available to Specrails (for example in the login shell profile Specrails loads, or with a refreshed registry token), then resume.`;
+}
+/** A failed check the host must unblock (credentials, registry access, a missing variable): no correction round can repair it. */
+export function preconditionBlock(context, receipt) {
+    for (const command of receipt.commands) {
+        if (command.exitCode === 0)
+            continue;
+        const precondition = hostPrecondition(command.output);
+        if (precondition)
+            return boundedBlocker({ kind: precondition.kind, reason: precondition.reason, command: command.command, args: command.args, cwd: checkoutRelative(context, command.cwd),
+                requiredAction: precondition.requiredAction, ...(command.evidenceId ? { evidenceId: command.evidenceId } : {}) });
+    }
+    return undefined;
+}
+/**
+ * Runs the planned installs for the failed commands' roots once, narrating each
+ * step through `note` exactly as the legacy graph logs it (`[environment] npm
+ * install (app)`, `Environment: installed …`). An install the host cannot
+ * complete for a precondition reason becomes `refused`.
+ */
+export function repairEnvironment(context, receipt, guardrails, note, spawn) {
+    const failed = receipt.commands.filter(command => command.exitCode !== 0);
+    const installs = installEnvironment(installRoots(context, failed), { failureOutput: receipt.commands.map(command => command.output).join('\n'), lockfileRepair: guardrailEnabled(guardrails, 'lockfile-repair'),
+        ...(spawn ? { spawn } : {}), onEvent: event => note(event.kind === 'text' ? event.text ?? '' : `[environment] ${event.tool ?? ''} ${event.detail ?? ''}`.trim()) });
+    const refused = installs.find(outcome => outcome.precondition);
+    if (!refused)
+        return { installs };
+    const precondition = hostPrecondition(refused.detail) ?? { kind: 'environment', reason: refused.precondition, requiredAction: 'Repair the verification environment, then retry the run.' };
+    const cwd = checkoutRelative(context, refused.root);
+    const command = [refused.command, ...refused.args].join(' ');
+    return { installs, refused: boundedBlocker({ kind: precondition.kind, reason: `installing its dependencies failed because ${refused.precondition}`, command: refused.command, args: refused.args, cwd,
+            // A network blocker on an install names the exact command to repeat with connectivity; other kinds keep the classifier's action.
+            requiredAction: precondition.kind === 'network' ? `Run \`${command}\` in ${cwd} with network access, then retry the run.` : precondition.requiredAction }) };
+}
+/** A blocker as a durable JSON value: known kind, bounded strings, at most 16 arguments. */
+export function boundedBlocker(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    if (typeof raw.kind !== 'string' || !BLOCKER_KINDS.has(raw.kind))
+        return undefined;
+    const bounded = (field, limit = BLOCKER_TEXT_LIMIT) => typeof field === 'string' ? field.slice(0, limit) : '';
+    const args = Array.isArray(raw.args) ? raw.args.slice(0, 16).map(arg => bounded(arg, 256)) : [];
+    // A correction role reports free-text `evidence` instead of a host reason.
+    const reason = bounded(raw.reason) || bounded(raw.evidence);
+    return { kind: raw.kind, reason, command: bounded(raw.command, 512), args, cwd: bounded(raw.cwd, 512), requiredAction: bounded(raw.requiredAction),
+        ...(typeof raw.evidenceId === 'string' && raw.evidenceId ? { evidenceId: bounded(raw.evidenceId, 128) } : {}) };
+}

package/dist/installer/commands/framework.d.ts

@@ -37,7 +37,11 @@ export interface AssembleFlags {
     provider?: string | boolean;
     version?: string | boolean;
     'code-root'?: string | boolean;
-    /** Comma-separated per-project agent allow-list (links a subset of the superset). */
+    /**
+     * Deprecated since Core 6.3: roles are runtime-defined, so there is nothing
+     * to select. Still parsed so older Desktop builds keep working; ignored with
+     * a warning.
+     */
     'selected-agents'?: string | boolean;
 }
 interface InstallFrameworkOutcome {
@@ -77,8 +81,8 @@ export declare function runInstallFramework(flags: InstallFrameworkFlags): Promi
 export declare function runSwapCurrent(flags: SwapCurrentFlags): Promise<SwapCurrentOutcome>;
 /**
  * `specrails-core assemble` — SYMLINK the materialized framework subtrees into a
- * project workspace and seed the per-project layer (agent-memory, manifest,
- * instruction/settings files, gemini acks). NO network, NO openspec init.
+ * project workspace and seed the per-project layer (manifest,
+ * instruction/settings files). NO network, NO openspec init.
  */
 export declare function runAssemble(flags: AssembleFlags): Promise<AssembleOutcome>;
 /** Read the package version (the version the desktop should materialize). */

package/dist/installer/commands/framework.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { assertNoCoreDowngrade, currentFrameworkVersion, withFrameworkLifecycleLock } from '../util/install-transaction.js';
 import { InstallerError } from '../util/errors.js';
-import { ok, step } from '../util/logger.js';
+import { ok, step, warn } from '../util/logger.js';
 import { pathExists, readTextFile } from '../util/fs.js';
 import { derivedPaths } from '../phases/provider-detect.js';
 import { assertFrameworkVersionComplete, resolveRequiredFrameworkProviders, } from '../phases/framework-lifecycle.js';
@@ -129,8 +129,8 @@ export async function runSwapCurrent(flags) {
 }
 /**
  * `specrails-core assemble` — SYMLINK the materialized framework subtrees into a
- * project workspace and seed the per-project layer (agent-memory, manifest,
- * instruction/settings files, gemini acks). NO network, NO openspec init.
+ * project workspace and seed the per-project layer (manifest,
+ * instruction/settings files). NO network, NO openspec init.
  */
 export async function runAssemble(flags) {
     const scriptDir = resolveScriptDir();
@@ -153,10 +153,9 @@ export async function runAssemble(flags) {
             throw new InstallerError(`framework not materialized: ${currentProviderDir} is missing — run install-framework first`, 41);
         }
         assertFrameworkVersionComplete(frameworkDir, version, [provider]);
-        const selectedAgentsFlag = flags['selected-agents'];
-        const selectedAgents = typeof selectedAgentsFlag === 'string' && selectedAgentsFlag.length > 0
-            ? selectedAgentsFlag.split(',').map((s) => s.trim()).filter((s) => s.length > 0)
-            : undefined;
+        if (flags['selected-agents'] !== undefined) {
+            warn('--selected-agents is ignored since Core 6.3: roles are runtime-defined and no role file is installed.');
+        }
         step(`Assembling workspace ${workspace} ← framework ${version} (${provider})`);
         assembleProjectWorkspace({
             workspace,
@@ -166,7 +165,6 @@ export async function runAssemble(flags) {
             version,
             codeRoot,
             scriptDir,
-            selectedAgents,
         });
         ok(`Linked ${providerDir}/ from framework ${version} + seeded project layer`);
         return { workspace, frameworkDir, provider, version, codeRoot, providerDir };

package/dist/installer/commands/init.d.ts

@@ -6,7 +6,8 @@ import { type Provider } from '../phases/install-config.js';
  *   --root-dir <path>     Target repo (default: cwd)
  *   --yes / -y            Non-interactive; auto-init git + accept defaults
  *   --provider <name>     Force provider (claude, codex, gemini, or kimi)
- *   --from-config [<p>]   Read provider + agents from install-config.yaml
+ *   --from-config [<p>]   Read the provider from install-config.yaml (a legacy
+ *                         `agents` section is validated and ignored)
  *   --relocate            Relocate artifacts to the $HOME workspace (symlinked
  *                         from the bundled framework) instead of installing them
  *                         IN-REPO. Default is in-repo so a standalone user's
@@ -31,12 +32,12 @@ interface InitResult {
 }
 type WorkspaceProviderSelections = Partial<Record<Provider, string[]>>;
 /**
- * Snapshot the provider/role inventory exposed by one live workspace before a
- * global framework version swap. This matters on Windows: directory junctions
- * resolve their target when they are created, so a workspace link made through
- * `framework/current` must be recreated after `current` moves. Keeping the
- * exact visible `sr-*` set also avoids widening or narrowing a project's
- * optional role selection during that refresh.
+ * Snapshot the providers exposed by one live workspace before a global
+ * framework version swap. This matters on Windows: directory junctions resolve
+ * their target when they are created, so a workspace link made through
+ * `framework/current` must be recreated after `current` moves. Roles are
+ * runtime-defined since Core 6.3, so every provider reports an empty selection;
+ * the keys are what drive the multi-provider reassembly.
  */
 export declare function snapshotWorkspaceProviderSelections(workspace: string): WorkspaceProviderSelections;
 /**
@@ -45,20 +46,12 @@ export declare function snapshotWorkspaceProviderSelections(workspace: string):
  * on failure.
  */
 export declare function runInit(flags: InitFlags): Promise<InitResult>;
-/**
- * Warn (once per id) about `agents.selected` entries that have no shipped
- * template — typically a pre-v5 install-config.yaml still listing removed
- * agents. They are skipped at placement; the warning tells the user why and
- * points at the v5 extension path.
- */
-export declare function warnUnknownSelectedAgents(selected: string[] | undefined): void;
 interface EnsureFrameworkInput {
     scriptDir: string;
     frameworkDir: string;
     provider: Provider;
     providerDir: string;
     version: string;
-    selectedAgents?: string[];
     /**
      * Additional providers that must remain available through the global
      * `framework/current` pointer after this version transition.

package/dist/installer/commands/init.js

@@ -6,13 +6,13 @@ import { recordSuccessfulInstall } from '../util/registry.js';
 import { fileURLToPath } from 'node:url';
 import { InstallerError } from '../util/errors.js';
 import { runCommand } from '../util/exec.js';
-import { info, ok, step, warn } from '../util/logger.js';
+import { info, ok, step } from '../util/logger.js';
 import { isDir, isSymlink, listDir, pathExists, readTextFile, removePath, writeFileLf, } from '../util/fs.js';
 import { loadInstallConfig, resolveConfigPath, } from '../phases/install-config.js';
 import { checkPrerequisites } from '../phases/prereqs.js';
 import { derivedPaths } from '../phases/provider-detect.js';
 import { materializeFrameworkVersion } from '../phases/framework-lifecycle.js';
-import { CORE_AGENTS, assembleProjectWorkspace, installFramework, } from '../phases/scaffold.js';
+import { assembleProjectWorkspace, installFramework, } from '../phases/scaffold.js';
 import { frameworkRoot, resolveArtifacts } from '../util/registry.js';
 const WORKSPACE_PROVIDER_ORDER = [
     'claude',
@@ -21,12 +21,12 @@ const WORKSPACE_PROVIDER_ORDER = [
     'kimi',
 ];
 /**
- * Snapshot the provider/role inventory exposed by one live workspace before a
- * global framework version swap. This matters on Windows: directory junctions
- * resolve their target when they are created, so a workspace link made through
- * `framework/current` must be recreated after `current` moves. Keeping the
- * exact visible `sr-*` set also avoids widening or narrowing a project's
- * optional role selection during that refresh.
+ * Snapshot the providers exposed by one live workspace before a global
+ * framework version swap. This matters on Windows: directory junctions resolve
+ * their target when they are created, so a workspace link made through
+ * `framework/current` must be recreated after `current` moves. Roles are
+ * runtime-defined since Core 6.3, so every provider reports an empty selection;
+ * the keys are what drive the multi-provider reassembly.
  */
 export function snapshotWorkspaceProviderSelections(workspace) {
     const selections = {};
@@ -36,44 +36,25 @@ export function snapshotWorkspaceProviderSelections(workspace) {
         if (Array.isArray(manifest.providers))
             recorded = manifest.providers.filter((value) => typeof value === 'string');
     }
-    catch { /* Legacy manifests are recognized by the complete Core role trio. */ }
+    catch { /* Legacy manifests: a provider counts only through its managed links. */ }
     for (const provider of WORKSPACE_PROVIDER_ORDER) {
         const { providerDir } = derivedPaths(provider);
         const providerRoot = path.join(workspace, providerDir);
         if (!pathExists(providerRoot) ||
             (!workspaceHasManagedProviderLink(providerRoot, provider)
-                && !(recorded.includes(provider) && hasCopiedCoreArtifacts(providerRoot, provider))
-                && !hasCopiedCoreRoles(providerRoot, provider))) {
+                && !(recorded.includes(provider) && hasCopiedCoreArtifacts(providerRoot, provider)))) {
             continue;
         }
-        const roleRoot = provider === 'codex'
-            ? path.join(workspace, providerDir, 'skills', 'rails')
-            : provider === 'kimi'
-                ? path.join(workspace, providerDir, 'skills')
-                : path.join(workspace, providerDir, 'agents');
-        const ids = listDir(roleRoot)
-            .filter((entry) => provider === 'claude' || provider === 'gemini'
-            ? path.basename(entry).endsWith('.md')
-            : isDir(entry))
-            .map((entry) => {
-            const name = path.basename(entry);
-            return name.endsWith('.md') ? name.slice(0, -3) : name;
-        })
-            .filter((id) => /^sr-[a-z0-9-]+$/.test(id));
-        selections[provider] = [...new Set(ids)].sort();
+        selections[provider] = [];
     }
     return selections;
 }
+/** A copied (in-repo) install is recognised by its workflow commands or runtime, never by role files. */
 function hasCopiedCoreArtifacts(providerRoot, provider) {
-    return hasCopiedCoreRoles(providerRoot, provider) || pathExists(provider === 'codex' ? path.join(providerRoot, 'skills', 'implement', 'SKILL.md')
+    return pathExists(provider === 'codex' ? path.join(providerRoot, 'skills', 'implement', 'SKILL.md')
         : provider === 'kimi' ? path.join(providerRoot, 'specrails', 'run-skill.mjs')
             : path.join(providerRoot, 'commands', 'specrails', provider === 'gemini' ? 'implement.toml' : 'implement.md'));
 }
-function hasCopiedCoreRoles(providerRoot, provider) {
-    return [...CORE_AGENTS].every((id) => pathExists(provider === 'codex' ? path.join(providerRoot, 'skills', 'rails', id, 'SKILL.md')
-        : provider === 'kimi' ? path.join(providerRoot, 'skills', id, 'SKILL.md')
-            : path.join(providerRoot, 'agents', id + '.md')));
-}
 function workspaceHasManagedProviderLink(providerRoot, provider) {
     const directoryLinks = provider === 'claude'
         ? ['commands', 'skills', 'rules']
@@ -85,10 +66,11 @@ function workspaceHasManagedProviderLink(providerRoot, provider) {
     if (directoryLinks.some((relative) => isSymlink(path.join(providerRoot, relative)))) {
         return true;
     }
-    const granularRoot = provider === 'kimi'
-        ? path.join(providerRoot, 'skills')
-        : path.join(providerRoot, 'agents');
-    return listDir(granularRoot).some((entry) => isSymlink(entry));
+    // Kimi links its skills one directory at a time; claude/gemini have no
+    // granular region any more (role files are no longer linked per file).
+    if (provider !== 'kimi')
+        return false;
+    return listDir(path.join(providerRoot, 'skills')).some((entry) => isSymlink(entry));
 }
 /**
  * Refresh every provider already represented in the project plus the provider
@@ -110,9 +92,6 @@ function reassembleWorkspaceProviders(input) {
             version: input.version,
             codeRoot: input.codeRoot,
             scriptDir: input.scriptDir,
-            selectedAgents: provider === input.selectedProvider
-                ? input.selectedAgents ?? input.previousSelections[provider]
-                : input.previousSelections[provider],
             copyStatics: input.copyStatics,
         });
     }
@@ -142,10 +121,10 @@ export async function runInit(flags) {
         }
         explicitProvider = flags.provider;
     }
-    // --from-config: read provider + agents from yaml.
+    // --from-config: read the provider from yaml. The legacy `agents` section is
+    // validated (and warned about) by `loadInstallConfig`; roles are runtime-defined.
     const fromConfigFlag = flags['from-config'];
     let providerHint = explicitProvider;
-    let selectedAgentsHint;
     if (fromConfigFlag !== undefined) {
         const explicitPath = typeof fromConfigFlag === 'string' ? fromConfigFlag : undefined;
         const resolved = resolveConfigPath(repoRoot, explicitPath);
@@ -155,9 +134,7 @@ export async function runInit(flags) {
                 throw new InstallerError(`--provider '${explicitProvider}' conflicts with provider '${config.provider}' in ${resolved}`, 40);
             }
             providerHint = config.provider;
-            selectedAgentsHint = config.agents.selected;
             info(`Loaded install config from ${resolved}`);
-            warnUnknownSelectedAgents(selectedAgentsHint);
         }
         else {
             info(`install-config.yaml not found at ${resolved} — falling back to ${explicitProvider ? `explicit provider '${explicitProvider}'` : 'auto-detection'}`);
@@ -199,7 +176,7 @@ export async function runInit(flags) {
     // Bundled-framework flow: materialize the provider-INVARIANT framework ONCE
     // under `<home>/.specrails/framework/<version>/<providerDir>/`, point `current`
     // at it, then SYMLINK that copy into the workspace and seed the project layer
-    // (agent-memory, manifest, instruction files, gemini acks). The framework
+    // (manifest, instruction files). The framework
     // source for standalone npx is the package's templates/+commands/ (scriptDir).
     step('Phase 2 & 3: Installing specrails artifacts');
     const { providerDir } = derivedPaths(prereqs.provider);
@@ -228,7 +205,6 @@ export async function runInit(flags) {
                 provider: prereqs.provider,
                 providerDir,
                 version,
-                selectedAgents: selectedAgentsHint,
                 requiredProviders: Object.keys(previousSelections),
             });
             reassembleWorkspaceProviders({
@@ -238,7 +214,6 @@ export async function runInit(flags) {
                 codeRoot,
                 scriptDir,
                 selectedProvider: prereqs.provider,
-                selectedAgents: selectedAgentsHint,
                 previousSelections,
                 // In-repo: COPY the framework statics as real, committable files. Relocated:
                 // symlink from the framework store (O(1) update on a version swap).
@@ -255,7 +230,7 @@ export async function runInit(flags) {
             if (artifactRoot !== codeRoot)
                 recordSuccessfulInstall(repoRoot, { home: process.env.SPECRAILS_REGISTRY_HOME, providers: [prereqs.provider], coreVersion: version });
             step('Installation complete');
-            info('Agents, commands, and rules were placed directly — no follow-up step required.');
+            info('Commands and skills were placed directly — no follow-up step required.');
             // Terminal sentinel for programmatic consumers (specrails-desktop's setup
             // wizard matches this exact line via regex to mark the "init complete"
             // checkpoint). The sentinel line below is FROZEN — the downstream setup
@@ -268,22 +243,6 @@ export async function runInit(flags) {
         });
     });
 }
-/**
- * Warn (once per id) about `agents.selected` entries that have no shipped
- * template — typically a pre-v5 install-config.yaml still listing removed
- * agents. They are skipped at placement; the warning tells the user why and
- * points at the v5 extension path.
- */
-export function warnUnknownSelectedAgents(selected) {
-    if (!selected)
-        return;
-    for (const id of selected) {
-        if (!CORE_AGENTS.has(id)) {
-            warn(`install-config.yaml selects agent '${id}', which specrails-core no longer ships — ` +
-                `skipping (removed in v5).`);
-        }
-    }
-}
 /**
  * Materialize the framework for `(version, provider)` if absent and (by default)
  * point `<frameworkDir>/current` at that version. Idempotent — `installFramework`
@@ -304,7 +263,6 @@ export function ensureFramework(input) {
             provider: input.provider,
             providerDir: input.providerDir,
             version: input.version,
-            selectedAgents: input.selectedAgents,
         });
         return;
     }

package/dist/installer/phases/install-config.d.ts

@@ -20,7 +20,12 @@ interface InstallModelConfig {
 interface InstallConfig {
     version: 1;
     provider: Provider;
-    agents: {
+    /**
+     * Deprecated since Core 6.3: roles are runtime-defined, so the selection has
+     * no effect on the installed artifacts. Validated for shape when present and
+     * echoed back for consumers that still read it; absent when not supplied.
+     */
+    agents?: {
         selected: string[];
         excluded?: string[];
         /** Legacy pre-models-section location, accepted for backward compatibility. */
@@ -32,7 +37,8 @@ interface InstallConfig {
  * Resolve a preset into provider-native identifiers. Kimi currently exposes no
  * Core-defined cost/capability tier mapping, so every named preset resolves to
  * its explicit `k3` default. User-supplied exact identifiers are handled later
- * and are never interpreted as Claude aliases.
+ * and are never interpreted as Claude aliases. No preset carries per-role
+ * overrides: Core ships no role ids, so `models.overrides` is Desktop's to fill.
  */
 export declare function resolveProviderModelConfig(provider: Provider, preset?: ModelPreset): InstallModelConfig;
 export declare class InvalidConfigError extends InstallerError {

package/dist/installer/phases/install-config.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import yaml from 'js-yaml';
 import { FilesystemError, InstallerError } from '../util/errors.js';
 import { pathExists, readTextFile, writeFileLf } from '../util/fs.js';
+import { warn } from '../util/logger.js';
 const PROVIDER_DEFAULT_MODELS = {
     claude: 'sonnet',
     codex: 'gpt-5.5-mini',
@@ -25,7 +26,8 @@ const SAFE_KIMI_MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._/:-]{0,127}$/;
  * Resolve a preset into provider-native identifiers. Kimi currently exposes no
  * Core-defined cost/capability tier mapping, so every named preset resolves to
  * its explicit `k3` default. User-supplied exact identifiers are handled later
- * and are never interpreted as Claude aliases.
+ * and are never interpreted as Claude aliases. No preset carries per-role
+ * overrides: Core ships no role ids, so `models.overrides` is Desktop's to fill.
  */
 export function resolveProviderModelConfig(provider, preset = 'balanced') {
     if (provider === 'claude') {
@@ -33,11 +35,7 @@ export function resolveProviderModelConfig(provider, preset = 'balanced') {
             return { preset, defaults: { model: 'haiku' }, overrides: {} };
         }
         if (preset === 'max') {
-            return {
-                preset,
-                defaults: { model: 'sonnet' },
-                overrides: { 'sr-architect': 'opus' },
-            };
+            return { preset, defaults: { model: 'sonnet' }, overrides: {} };
         }
     }
     return {
@@ -109,13 +107,18 @@ export function validateInstallConfig(raw) {
     // NOTE: a legacy `tier` field (`full`/`quick`) may still be present in pre-v5
     // configs. It is intentionally ignored (not rejected and not carried forward)
     // — v5 has no install tiers.
+    // The `agents` section is OPTIONAL and deprecated: roles are runtime-defined
+    // since Core 6.3. When present it is still validated for shape (safe ids, no
+    // overlap, known preset) so a malformed file fails fast, and a non-empty
+    // selection logs one warning instead of being rejected — Desktop builds
+    // paired with an older Core still write it.
     const agents = doc.agents;
     let selectedAgents = [];
     let excludedAgents;
-    if (!agents || typeof agents !== 'object') {
-        errors.push(`missing required 'agents' section with 'selected' list`);
+    if (doc.agents !== undefined && (!agents || typeof agents !== 'object' || Array.isArray(agents))) {
+        errors.push(`'agents' must be a mapping`);
     }
-    else {
+    else if (agents) {
         if (!Array.isArray(agents.selected)) {
             errors.push(`'agents.selected' must be a list`);
         }
@@ -182,6 +185,10 @@ export function validateInstallConfig(raw) {
     if (errors.length > 0) {
         throw new InvalidConfigError(errors);
     }
+    if (selectedAgents.length > 0) {
+        warn(`install-config.yaml 'agents.selected' is ignored since Core 6.3: roles are ` +
+            `runtime-defined and no role file is installed (${selectedAgents.join(', ')}).`);
+    }
     const preset = (modelPreset ?? agents?.preset ?? 'balanced');
     const resolvedModels = resolveProviderModelConfig(provider, preset);
     if (typeof modelDefaults?.model === 'string') {
@@ -193,18 +200,18 @@ export function validateInstallConfig(raw) {
     const result = {
         version: 1,
         provider,
-        agents: {
-            selected: selectedAgents,
-        },
         models: resolvedModels,
     };
     // NOTE: a legacy `agent_teams` field may still be present in older configs.
     // It is intentionally ignored (not rejected) for backward compatibility.
-    if (agents?.preset !== undefined) {
-        result.agents.preset = agents.preset;
-    }
-    if (excludedAgents !== undefined) {
-        result.agents.excluded = excludedAgents;
+    if (agents) {
+        result.agents = { selected: selectedAgents };
+        if (agents.preset !== undefined) {
+            result.agents.preset = agents.preset;
+        }
+        if (excludedAgents !== undefined) {
+            result.agents.excluded = excludedAgents;
+        }
     }
     return result;
 }