akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/setup/setup.js

@@ -20,8 +20,10 @@ import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import * as p from "../cli/clack.js";
 import { akmInit } from "../commands/sources/init.js";
-import { DEFAULT_CONFIG, loadUserConfig, mutateConfigWithPrecommit, parseAndValidateConfigText, primaryBundlePath, validateCompleteConfig, } from "../core/config/config.js";
+import { deriveBundleIds } from "../core/bundle-id.js";
+import { bundleEntryToSourceEntry, DEFAULT_CONFIG, loadUserConfig, mutateConfigWithPrecommit, parseAndValidateConfigText, primaryBundlePath, validateCompleteConfig, } from "../core/config/config.js";
 import { readConfigText } from "../core/config/config-io.js";
+import { listTopLevelConfigKeys } from "../core/config/config-schema.js";
 import { deepMergeConfig } from "../core/config/deep-merge.js";
 import { ConfigError, UsageError } from "../core/errors.js";
 import { getConfigPath, getDefaultStashDir, isTransientStashPath } from "../core/paths.js";
@@ -32,7 +34,6 @@ import { detectAgentCliProfiles, pickDefaultAgentProfile } from "../integrations
 import { defaultProfileName } from "../integrations/harnesses/index.js";
 import { readLockfile } from "../integrations/lockfile.js";
 import { probeLlmCapabilities } from "../llm/client.js";
-import { migrateConfigSourcesToBundles } from "../migrate/legacy/config-source-migration.js";
 import { detectEnvironment, detectLMStudio, renderDetectionSummary, } from "./detect.js";
 import { upsertDetectedAgentEngine, upsertDetectedLlmEngine, verifyOpenAiCompatibleEndpoint } from "./detected-engines.js";
 import { readCurrentLlmEngine, writeAgentEngines, writeLlmEngine } from "./engine-config.js";
@@ -47,13 +48,13 @@ import { printCapabilitySummary, stepAgentCliDetection, stepAgentPlatforms, step
 import { stepSemanticSearch } from "./steps/semantic.js";
 import { stepAdditionalSources, stepAddSources, stepRegistries } from "./steps/sources.js";
 import { stepStashDir } from "./steps/stashdir.js";
-import { stepDefaultImproveTasks, stepScheduledTasks } from "./steps/tasks.js";
+import { stepScheduledTasks } from "./steps/tasks.js";
 // ── Setup sandbox guard ─────────────────────────────────────────────────────
 /**
- * Refuse to persist an explicit `--dir /tmp/...` stashDir to the user's
- * config. The OS may reap the directory at any time, and the next run will
- * see a `stashDir` that points at a deleted path (falling back to ~/akm
- * silently). Mirrors the `assertInitSandbox` check in commands/init.ts, but
+ * Refuse to persist an explicit `--dir /tmp/...` as the default bundle path.
+ * The OS may reap the directory at any time, leaving the next run with a
+ * default bundle that points at a deleted path. Mirrors the
+ * `assertInitSandbox` check in commands/init.ts, but
  * fires under all runtimes (not just `bun test`) because `akm setup --dir
  * /tmp/X` is a documented isolation pattern that has been observed to
  * silently clobber the host config (the 2026-05-23 setup-clobbers-user-config
@@ -61,7 +62,7 @@ import { stepDefaultImproveTasks, stepScheduledTasks } from "./steps/tasks.js";
  *
  * Escape hatch: set `AKM_FORCE_SETUP_TMP_STASH=1` to override. When the
  * escape hatch is on, `applyStashIsolationToEnv` below also pre-sets
- * `AKM_STASH_DIR` so that the `getConfigDir` / `getCacheDir` isolation
+ * `AKM_BUNDLE_DIR` so that the `getConfigDir` / `getCacheDir` isolation
  * rules fire and config + cache writes route into `$stashDir/.akm/`
  * instead of the user's host `~/.config/akm`.
  */
@@ -73,7 +74,7 @@ function assertSetupSandbox(stashDir, dirExplicitlyProvided) {
     if (!isTransientStashPath(stashDir))
         return;
     throw new ConfigError(`refusing to run \`akm setup --dir ${stashDir}\`: the path is in a transient/sandbox directory family the OS may reap. ` +
-        "Persisting it as the user's stashDir would leave the next run pointing at a deleted path (silently falling back to ~/akm). " +
+        "Persisting it as the default bundle would leave the next run pointing at a deleted path. " +
         "Use a persistent directory, OR set AKM_FORCE_SETUP_TMP_STASH=1 if you intentionally want a sandbox setup " +
         "(setup will also auto-isolate config + cache writes into $stashDir/.akm/ so the host config is preserved).", "SETUP_TMP_STASH_REFUSED");
 }
@@ -81,11 +82,11 @@ function assertSetupSandbox(stashDir, dirExplicitlyProvided) {
  * Propagate the explicit `--dir <stashDir>` choice to the env so that the
  * `getConfigDir` / `getCacheDir` isolation rules in `src/core/paths.ts`
  * actually fire for the duration of this setup run. Without this, a CLI
- * caller who passes `--dir /tmp/X` but doesn't pre-export `AKM_STASH_DIR`
+ * caller who passes `--dir /tmp/X` but doesn't pre-export `AKM_BUNDLE_DIR`
  * would still write config to the host `~/.config/akm/config.json`. We
  * only set the env var when:
  *   - `--dir` was explicitly provided (we have an operator-stated stash), AND
- *   - `AKM_STASH_DIR` is not already set (caller's explicit env wins).
+ *   - `AKM_BUNDLE_DIR` is not already set (caller's explicit env wins).
  * The set is process-wide; for the CLI that's the right scope (the process
  * is about to do all its work against this stash). For tests, each test
  * already isolates env via beforeEach/afterEach so there is no leak.
@@ -93,12 +94,37 @@ function assertSetupSandbox(stashDir, dirExplicitlyProvided) {
 function applyStashIsolationToEnv(stashDir, dirExplicitlyProvided) {
     if (!dirExplicitlyProvided)
         return;
-    if (process.env.AKM_STASH_DIR?.trim())
+    if (process.env.AKM_BUNDLE_DIR?.trim())
         return;
-    process.env.AKM_STASH_DIR = stashDir;
+    process.env.AKM_BUNDLE_DIR = stashDir;
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
-/** Raw preflight used before setup performs prompts, initialization, or writes. */
+/**
+ * Raw preflight used before setup performs prompts, initialization, or writes.
+ *
+ * `setup` is allowlisted in `shouldBypassConfigStartup` (src/cli.ts) so it
+ * never dies on the CLI's own startup config load — but every entry point
+ * below (`runSetupWizard`, `runSetupWithDefaults`, `runSetupFromConfig`,
+ * `runResetRecommended`) still needs the CURRENT config as its merge base, so
+ * this is the first thing each one calls. When the on-disk config predates
+ * 0.9 (or is otherwise unparseable/invalid), `parseAndValidateConfigText`
+ * throws `ConfigError`; deliberately let that propagate rather than falling
+ * back to a fresh default config here.
+ *
+ * That fallback was considered and rejected: `mutateConfigWithPrecommit`
+ * (src/core/config/config.ts) re-reads and re-validates this SAME file
+ * inside its write lock before saving, so a wizard that "survived" this
+ * preflight by substituting `DEFAULT_CONFIG` would still crash with the
+ * identical error at the final save — after prompting the user through the
+ * entire wizard. Worse, making the save path itself tolerate an old config
+ * would mean writing a freshly-generated 0.9 config over the live 0.8 file
+ * `akm migrate apply` needs to read as ITS OWN input — replacing the user's
+ * real engine/source settings with the wizard's placeholder ones, silently,
+ * on the one path (`akm migrate ...`) the upgrade docs tell users to run
+ * first. Refusing here — before any prompt, detection, or write — is strictly
+ * safer: the file is left byte-for-byte untouched and the error message
+ * below points straight at the real recovery command.
+ */
 export function assertSetupConfigPreflight() {
     const configPath = getConfigPath();
     let text;
@@ -108,8 +134,21 @@ export function assertSetupConfigPreflight() {
     catch (error) {
         throw new ConfigError(`Could not read config at ${configPath}: ${error instanceof Error ? error.message : String(error)}`, "INVALID_CONFIG_FILE");
     }
-    if (text !== undefined)
+    if (text === undefined)
+        return;
+    try {
         parseAndValidateConfigText(text, configPath);
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError))
+            throw error;
+        if (error.code !== "UNSUPPORTED_CONFIG_VERSION" && error.code !== "INVALID_CONFIG_FILE")
+            throw error;
+        throw new ConfigError(`\`akm setup\` cannot run: the config at ${configPath} did not load (${error.message}). ` +
+            "It was left untouched — setup never writes over a config it cannot first read cleanly.", error.code, "Run `akm migrate status` to check what this config needs before continuing, or `akm help migrate 0.9.0` " +
+            "for the full upgrade checklist. To abandon it and start fresh instead, move it aside " +
+            `(e.g. \`mv ${configPath} ${configPath}.bak\`) and re-run \`akm setup\`.`);
+    }
 }
 function isPlainRecord(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
@@ -202,56 +241,104 @@ async function saveSetupConfig(original, desired, precommit) {
     const result = await mutateConfigWithPrecommit((latest) => rebaseSetupChanges(original, desired, latest), precommit);
     return { config: result.config, precommit: result.precommit };
 }
-/** The registry-managed (lock-backed) bundles of a config, preserved through setup. */
-function managedBundles(bundles) {
-    if (!bundles)
-        return {};
-    const lockIds = new Set(readLockfile().map((entry) => entry.id));
-    const out = {};
-    for (const [key, bundle] of Object.entries(bundles)) {
-        if (lockIds.has(key))
-            out[key] = bundle;
-    }
-    return out;
+/** Registry-managed bundles are not editable through setup's source picker. */
+function managedBundleIds() {
+    return new Set(readLockfile().map((entry) => entry.id));
 }
-/**
- * Fold the wizard's flat scratch model (`stashDir` primary + `sources[]`) into
- * the persisted 0.9.0 `bundles` + `defaultBundle` shape (spec §10.1), reusing the
- * shared migrator mapping (D-R5 / Decision E). The registry-managed (lock-backed)
- * bundles from the loaded config are preserved verbatim — the wizard only
- * re-specifies the primary and the plain sources. Returns a config that is never
- * half-migrated (no `stashDir`/`sources`/`installed` leak through).
- */
+function setupSourceDescriptor(source) {
+    switch (source.type) {
+        case "filesystem":
+            return source.path ? { path: source.path } : undefined;
+        case "git":
+            return source.url ? { git: source.url } : undefined;
+        case "website":
+            return source.url ? { website: { url: source.url, ...(source.options ?? {}) } } : undefined;
+        case "npm":
+            return source.path ? { npm: source.path } : undefined;
+        default:
+            return undefined;
+    }
+}
+function selectsExistingBundle(source, id, bundle) {
+    const configured = bundleEntryToSourceEntry(id, bundle);
+    return (configured !== undefined &&
+        configured.type === source.type &&
+        configured.path === source.path &&
+        configured.url === source.url);
+}
+/** Convert only the wizard's private drafts, leaving current bundle entries intact. */
 function finalizeSetupDraft(draft) {
-    const raw = { ...draft };
-    const hasScratch = raw.stashDir !== undefined || raw.sources !== undefined || raw.installed !== undefined;
-    if (!hasScratch)
-        return draft;
-    const preservedManaged = managedBundles(draft.bundles);
-    // When the sources step never ran (non-interactive --yes/--from paths set
-    // only the scratch stashDir), the user made no choice about existing PLAIN
-    // secondary bundles — preserve them rather than silently dropping config.
-    // The interactive flow re-specifies them via the toggle list into scratch
-    // `sources`, so this branch stays empty there.
-    const preservedPlain = {};
-    if (raw.sources === undefined && draft.bundles) {
-        const managedKeys = new Set(Object.keys(preservedManaged));
-        for (const [key, bundle] of Object.entries(draft.bundles)) {
-            if (!managedKeys.has(key) && key !== draft.defaultBundle)
-                preservedPlain[key] = bundle;
+    const { primaryPath, additionalSources, ...canonical } = draft;
+    const finalized = canonical;
+    if (primaryPath === undefined && additionalSources === undefined)
+        return finalized;
+    const bundles = { ...(draft.bundles ?? {}) };
+    const managedIds = managedBundleIds();
+    const newBundles = [];
+    if (additionalSources !== undefined) {
+        const selectedExistingIds = new Set();
+        for (const source of additionalSources) {
+            const existing = source.name ? bundles[source.name] : undefined;
+            if (source.name &&
+                source.name !== draft.defaultBundle &&
+                existing &&
+                selectsExistingBundle(source, source.name, existing)) {
+                selectedExistingIds.add(source.name);
+                continue;
+            }
+            const descriptor = setupSourceDescriptor(source);
+            if (!descriptor)
+                continue;
+            newBundles.push({
+                descriptor,
+                derivationPath: source.path ? path.resolve(source.path) : (source.url ?? ""),
+                preferredId: source.name,
+                primary: false,
+                writable: source.writable,
+            });
+        }
+        for (const id of Object.keys(bundles)) {
+            if (id === draft.defaultBundle || managedIds.has(id) || selectedExistingIds.has(id))
+                continue;
+            delete bundles[id];
         }
     }
-    // Drop the stale bundles so the migrator re-derives the primary + plain
-    // sources cleanly from the scratch fields; then merge the managed bundles back.
-    delete raw.bundles;
-    delete raw.defaultBundle;
-    const derived = migrateConfigSourcesToBundles(raw);
-    const bundles = { ...preservedManaged, ...(derived.bundles ?? {}) };
-    const finalized = { ...derived };
+    let defaultBundle = draft.defaultBundle;
+    const configuredPrimaryPath = primaryBundlePath(draft);
+    if (primaryPath !== undefined &&
+        (configuredPrimaryPath === undefined || path.resolve(configuredPrimaryPath) !== path.resolve(primaryPath))) {
+        if (defaultBundle && !managedIds.has(defaultBundle))
+            delete bundles[defaultBundle];
+        defaultBundle = undefined;
+        newBundles.unshift({
+            descriptor: { path: primaryPath },
+            derivationPath: path.resolve(primaryPath),
+            primary: true,
+            writable: true,
+        });
+    }
+    const reserved = Object.keys(bundles).map((id) => ({ path: id, registryId: id }));
+    const ids = deriveBundleIds([
+        ...reserved,
+        ...newBundles.map((bundle) => ({ path: bundle.derivationPath, registryId: bundle.preferredId })),
+    ]).slice(reserved.length);
+    for (const [index, bundle] of newBundles.entries()) {
+        const id = ids[index];
+        bundles[id] = {
+            ...bundle.descriptor,
+            ...(bundle.writable !== undefined ? { writable: bundle.writable } : {}),
+        };
+        if (bundle.primary)
+            defaultBundle = id;
+    }
     if (Object.keys(bundles).length > 0)
         finalized.bundles = bundles;
     else
         delete finalized.bundles;
+    if (defaultBundle !== undefined)
+        finalized.defaultBundle = defaultBundle;
+    else
+        delete finalized.defaultBundle;
     return finalized;
 }
 /**
@@ -304,14 +391,14 @@ export function buildSetupSteps(options) {
     const steps = [
         {
             id: "stash-dir",
-            label: "Stash Directory",
+            label: "Bundle Directory",
             nonInteractive: true,
             async run(ctx) {
                 const stashDir = await stepStashDir(ctx.config, {
                     nonInteractive: ctx.nonInteractive,
                     preferredDir: options.preferredStashDir,
                 });
-                ctx.apply({ stashDir });
+                ctx.apply({ primaryPath: stashDir });
             },
         },
         {
@@ -359,17 +446,17 @@ export function buildSetupSteps(options) {
         },
         {
             id: "stash-sources",
-            label: "Stash Sources",
+            label: "Bundle Sources",
             async run(ctx) {
                 const stashes = await stepAddSources(ctx.config, { promptForAdditional: false });
-                const platforms = await stepAgentPlatforms({ ...ctx.config, sources: stashes });
+                const platforms = await stepAgentPlatforms({ ...ctx.config, additionalSources: stashes });
                 const merged = [...stashes];
                 for (const ps of platforms) {
                     if (!merged.some((s) => s.path === ps.path))
                         merged.push(ps);
                 }
                 const withAdditional = await stepAdditionalSources(merged);
-                ctx.apply({ sources: withAdditional.length > 0 ? withAdditional : undefined });
+                ctx.apply({ additionalSources: withAdditional });
             },
         },
         {
@@ -431,7 +518,7 @@ export async function runSetupWizard(opts) {
     // API key values.
     const detection = await detectEnvironment({ existingStashDir: primaryBundlePath(current) });
     p.note(renderDetectionSummary(detection), "Detected environment");
-    // Interactive entry point for `--reset-recommended`: offer to apply the
+    // Interactive entry point for `runResetRecommended`: offer to apply the
     // opinionated, detection-derived defaults and skip the step-by-step wizard.
     const useRecommended = await prompt(() => p.confirm({
         message: "Apply recommended defaults from the detected environment (merged into your existing config)?",
@@ -469,26 +556,25 @@ export async function runSetupWizard(opts) {
     // Step 2/2: Agent connection (for agentic features)
     const agentConfig = await stepAgentConnection(ctx.config, smallModelResult);
     ctx.apply(writeAgentEngines(ctx.config, agentConfig));
-    // Registry-managed (lock-backed) bundles are preserved by finalizeSetupDraft.
     const newConfig = { ...ctx.config };
     const semanticSearchMode = outcome.semantic;
-    const stashDir = newConfig.stashDir ?? primaryBundlePath(current) ?? getDefaultStashDir();
+    const stashDir = newConfig.primaryPath ?? primaryBundlePath(current) ?? getDefaultStashDir();
     const embedding = newConfig.embedding;
     const llm = readCurrentLlmEngine(newConfig);
     const registries = newConfig.registries;
-    const allStashes = newConfig.sources ?? [];
+    const allStashes = newConfig.additionalSources ?? [];
     // Feature capability summary
     const agentConfigured = Boolean(agentConfig && !agentConfig.disabled);
     printCapabilitySummary(smallModelResult.skipped, agentConfigured);
     // Confirm before saving
     const effectiveRegistries = registries ?? DEFAULT_CONFIG.registries ?? [];
     p.note([
-        `Stash directory:  ${stashDir}`,
+        `Bundle directory: ${stashDir}`,
         `Embedding:        ${embedding ? `${embedding.provider ?? "remote"} / ${embedding.model}` : "built-in local"}`,
         `LLM:              ${llm ? `${llm.provider ?? "remote"} / ${llm.model}` : "disabled"}`,
         `Semantic search:  ${semanticSearchMode.mode}`,
         `Registries:       ${effectiveRegistries.filter((r) => r.enabled !== false).length} enabled`,
-        `Stash sources:    ${allStashes.length}`,
+        `Bundle sources:   ${allStashes.length}`,
         `Agent default:    ${newConfig.defaults?.engine ?? "disabled"}`,
         `Output:           ${newConfig.output?.format ?? "json"} / ${newConfig.output?.detail ?? "brief"}`,
     ].join("\n"), "Configuration Summary");
@@ -502,19 +588,12 @@ export async function runSetupWizard(opts) {
     validateCompleteConfig(finalConfig);
     const { config: savedConfig } = await saveSetupConfig(current, finalConfig, async () => {
         if (!opts?.noInit)
-            await akmInit({ dir: resolvedStashDir, setDefault: true, persistConfig: false });
+            await akmInit({ dir: stashDir, setDefault: true, persistConfig: false });
     });
-    // Scheduled tasks are the wizard's only externally-visible side effect
-    // (task files + OS scheduler entries). Run them ONLY now that the config is
-    // confirmed and persisted, so cancelling at the final confirm above leaves
-    // nothing behind. The task-setup path re-reads config via `loadConfig()`,
-    // which now returns the just-saved config (the cache is invalidated on
-    // write) — so tasks register against the confirmed engine/connection rather
-    // than the stale pre-wizard config. This is interactive-only: `akm init` /
-    // `--yes` go through the non-interactive entry points, which never reach
-    // here (issue #512).
+    // After config persistence, the task step reviews the plan and asks one
+    // explicit confirmation before changing task files or scheduler state.
+    // Non-interactive setup paths never reach this interactive-only step.
     p.log.step("Scheduled Tasks");
-    await stepDefaultImproveTasks();
     await stepScheduledTasks();
     if (semanticSearchMode.mode === "off") {
         clearSemanticStatus();
@@ -595,7 +674,8 @@ export async function runSetupWizard(opts) {
             p.log.info("Reminder: Set your LLM API key via the AKM_LLM_API_KEY environment variable.");
         }
     }
-    p.outro(`Configuration saved to ${configPath}`);
+    p.outro(`Configuration saved to ${configPath}\n` +
+        'Next: `akm bundle add <source>`, `akm index`, `akm search "<query>"`, `akm help agents`');
 }
 // ── Non-interactive / scripting entry points ─────────────────────────────────
 /**
@@ -605,14 +685,21 @@ export async function runSetupWizard(opts) {
 export async function runSetupWithDefaults(opts) {
     assertSetupConfigPreflight();
     const explicitStashDir = opts.dir != null ? path.resolve(opts.dir) : undefined;
+    // R-066 #4: a second `assertSetupSandbox(stashDir, explicitStashDir != null)`
+    // + `applyStashIsolationToEnv(stashDir, explicitStashDir != null)` pair used
+    // to follow `stashDir`'s resolution below. It was strictly redundant: unlike
+    // `runSetupFromConfig` (which can also derive an explicit stash dir from an
+    // incoming config file's bundle path, a case the early block below can't
+    // see yet), `runSetupWithDefaults` has only one source of an explicit dir —
+    // `opts.dir` — so `stashDir` always equals `explicitStashDir` whenever the
+    // `if` below ran, and always fails `dirExplicitlyProvided` (an immediate
+    // no-op in both helpers) whenever it didn't. Removed rather than duplicated.
     if (explicitStashDir) {
         assertSetupSandbox(explicitStashDir, true);
         applyStashIsolationToEnv(explicitStashDir, true);
     }
     const current = loadUserConfig();
     const stashDir = explicitStashDir ?? primaryBundlePath(current) ?? getDefaultStashDir();
-    assertSetupSandbox(stashDir, explicitStashDir != null);
-    applyStashIsolationToEnv(stashDir, explicitStashDir != null);
     // Run steps in non-interactive mode (applies defaults, skips prompts)
     const ctx = createSetupContext(current, { nonInteractive: true });
     const { steps } = buildSetupSteps({
@@ -621,11 +708,10 @@ export async function runSetupWithDefaults(opts) {
         preferredStashDir: stashDir,
     });
     await runSetupSteps(steps, ctx);
-    // Ensure stashDir is set
-    if (!ctx.config.stashDir)
-        ctx.apply({ stashDir });
+    if (!ctx.config.primaryPath)
+        ctx.apply({ primaryPath: stashDir });
     // Aggregate environment detection — apply detected values directly.
-    const env = await detectEnvironment({ existingStashDir: ctx.config.stashDir });
+    const env = await detectEnvironment({ existingStashDir: ctx.config.primaryPath });
     // Apply a detected LLM (live local server) when the config has none yet.
     if (!readCurrentLlmEngine(ctx.config) && opts.probe) {
         const liveLocal = env.localServers.find((s) => s.available && s.defaultModel);
@@ -677,7 +763,7 @@ export async function runSetupWithDefaults(opts) {
     });
     return {
         configPath: getConfigPath(),
-        stashDir,
+        bundleDir: stashDir,
         stashCreated: initResult?.created ?? false,
         written: true,
         fields: Object.keys(finalConfig).filter((k) => finalConfig[k] !== undefined),
@@ -685,7 +771,7 @@ export async function runSetupWithDefaults(opts) {
 }
 /**
  * Run ONLY environment detection and return the typed result. Performs no
- * config writes and shows no prompts. Backs `akm setup --detect-only`.
+ * config writes and shows no prompts.
  *
  * SAFETY: The returned object carries env var NAMES only — never any API key
  * value.
@@ -699,9 +785,8 @@ export async function runDetectOnly() {
  * - Best harness → agent default (when a profile maps to it).
  * - Fastest live local model, else the first detected cloud key's provider.
  * - `nomic-embed-text` embeddings when a local LLM is live.
- * - improve task `0 2 * * *`, index task `0 4 * * *`.
  *
- * Returns a partial `AkmConfig`-shaped object plus a legacy `llm` block, ready
+ * Returns a partial `AkmConfig`-shaped object plus an LLM connection block, ready
  * to merge. Never includes an API key value.
  */
 export function deriveRecommendedConfig(env) {
@@ -736,14 +821,13 @@ export function deriveRecommendedConfig(env) {
             }
         }
     }
-    result.taskSchedules = { improve: "0 2 * * *", index: "0 4 * * *" };
     return result;
 }
 /**
- * `akm setup --reset-recommended`: merge opinionated, detection-derived
- * defaults into the existing config WITHOUT removing pre-existing custom keys.
- * Uses the same merge path as {@link runSetupFromConfig} so custom keys survive
- * (follows #511 semantics).
+ * Merge opinionated, detection-derived defaults into the existing config
+ * WITHOUT removing pre-existing custom keys. Backs the interactive wizard's
+ * "apply recommended defaults" prompt. Uses the same merge path as
+ * {@link runSetupFromConfig} so custom keys survive (follows #511 semantics).
  */
 export async function runResetRecommended(opts) {
     assertSetupConfigPreflight();
@@ -787,9 +871,6 @@ export async function runResetRecommended(opts) {
     if (recommended.agentDefault) {
         incoming = deepMergeConfig(incoming, writeAgentEngines(incoming, { default: recommended.agentDefault }));
     }
-    if (recommended.taskSchedules) {
-        incoming.setup = { taskSchedules: recommended.taskSchedules };
-    }
     return runSetupFromConfig({
         configJson: JSON.stringify(incoming),
         dir: opts.dir,
@@ -804,35 +885,36 @@ export async function runResetRecommended(opts) {
 export async function runSetupFromConfig(opts) {
     assertSetupConfigPreflight();
     // Phase 1: Parse JSON
-    let incoming;
+    let parsed;
     try {
-        incoming = JSON.parse(opts.configJson);
+        parsed = JSON.parse(opts.configJson);
     }
     catch (e) {
-        throw new Error(`Invalid JSON in --config: ${e.message}`);
+        throw new UsageError(`Invalid JSON in --config: ${e.message}`, "INVALID_FLAG_VALUE");
+    }
+    if (!isPlainRecord(parsed)) {
+        throw new ConfigError("Setup config must contain a top-level object.", "INVALID_CONFIG_FILE");
     }
+    const incoming = parsed;
     // Phase 2: Validate — only allow safe top-level keys
-    const ALLOWED_KEYS = new Set([
-        "configVersion",
-        "engines",
-        "defaults",
-        "improve",
-        "modelAliases",
-        "stashDir",
-        "embedding",
-        "semanticSearchMode",
-        "output",
-        "sources",
-        // 0.9.0 (spec §10.1): the persisted source shape. Old-shape input files
-        // (stashDir/sources) stay accepted and are normalized by finalizeSetupDraft
-        // (Decision E); new-shape input files pass through their bundles directly.
-        "bundles",
-        "defaultBundle",
-        "registries",
-        "defaultWriteTarget",
-        "defaults",
-        "setup",
-    ]);
+    for (const key of ["stashDir", "sources", "installed"]) {
+        if (key in incoming) {
+            throw new ConfigError(`${key} is not supported by the current config schema; run the standalone akm-migrate tool first.`, "INVALID_CONFIG_FILE");
+        }
+    }
+    // Derived from AkmConfigShape (via `listTopLevelConfigKeys`) rather than a
+    // hand-copied set: a hand-copied allowlist silently fell out of sync as the
+    // schema grew (R-017 — `index`, `search`, `feedback`, `archiveRetentionDays`,
+    // `workflow`, and `experimental` were all valid schema keys that this list
+    // forgot, each dropped with only a warning while the command exited 0).
+    // Every key the schema recognizes is a legitimate thing to set via
+    // `--config`/`--from`; there is no key a user can set here that they
+    // couldn't set by hand-editing config.json and letting `akm config set`
+    // validate it. Keys that remain genuinely retired (`profiles`, `llm`,
+    // `agent`, `features`, `stashes`, `bindings`, `writable`) are not part of
+    // the schema shape, so they still fall into the warn-and-drop branch below;
+    // `stashDir`/`sources`/`installed` get the more specific migration error above.
+    const ALLOWED_KEYS = new Set(listTopLevelConfigKeys());
     for (const key of Object.keys(incoming)) {
         if (!ALLOWED_KEYS.has(key)) {
             warn(`[akm setup] Ignoring unknown or restricted config key: "${key}"`);
@@ -847,21 +929,41 @@ export async function runSetupFromConfig(opts) {
             throw new Error("embedding.model is required when embedding is provided");
     }
     // Phase 3: Merge with existing config
-    const incomingStashDir = incoming.stashDir;
-    const explicitStashDir = opts.dir != null ? path.resolve(opts.dir) : incomingStashDir != null ? path.resolve(incomingStashDir) : undefined;
+    //
+    // R-066 #4 (verified, NOT reduced — unlike the `runSetupWithDefaults` pair
+    // above, this one is NOT strictly redundant): the `assertSetupSandbox` +
+    // `applyStashIsolationToEnv` pair below looks like a duplicate of the pair
+    // here, but each guards a case the other cannot:
+    //   - THIS early pair must run before `loadUserConfig()` so an explicit
+    //     `--dir` pointed at a force-escaped transient sandbox isolates the
+    //     config READ too, not just the later write (the isolation env var has
+    //     to be set before `loadUserConfig()` executes, or `current` below is
+    //     read from the host config instead of the sandboxed one — the exact
+    //     failure class the "2026-05-23 setup-clobbers-user-config incident"
+    //     comment on `assertSetupSandbox` describes).
+    //   - The LATER pair below additionally covers a case this one can't see
+    //     yet: an incoming `--config`/`--file` JSON blob that names its own
+    //     bundle path (`incomingPrimaryPath`) with no `--dir` at all — that
+    //     path is only known after the merge, so it cannot be checked early.
+    // When `explicitStashDir` is set both pairs do end up asserting the same
+    // (stashDir, true), but removing either one changes behavior in the case
+    // it uniquely covers, so both stay.
+    const explicitStashDir = opts.dir != null ? path.resolve(opts.dir) : undefined;
     if (explicitStashDir) {
         assertSetupSandbox(explicitStashDir, true);
         applyStashIsolationToEnv(explicitStashDir, true);
     }
     const current = loadUserConfig();
-    const stashDir = explicitStashDir ?? primaryBundlePath(current) ?? getDefaultStashDir();
-    const stashDirExplicit = explicitStashDir != null;
+    let merged = deepMergeConfig(current, incoming);
+    const incomingPrimaryPath = primaryBundlePath(incoming);
+    const configuredPrimaryPath = primaryBundlePath(merged);
+    const stashDir = explicitStashDir ?? configuredPrimaryPath ?? getDefaultStashDir();
+    const stashDirExplicit = explicitStashDir != null || incomingPrimaryPath !== undefined;
     assertSetupSandbox(stashDir, stashDirExplicit);
     applyStashIsolationToEnv(stashDir, stashDirExplicit);
-    let merged = deepMergeConfig(current, {
-        ...incoming,
-        stashDir,
-    });
+    if (explicitStashDir !== undefined || configuredPrimaryPath === undefined) {
+        merged = deepMergeConfig(merged, { primaryPath: stashDir });
+    }
     // Deep-merge canonical keys: nested objects merge key-by-key so a
     // partial `--file` only updates the keys it carries and never drops sibling
     // subkeys (e.g. output.detail survives an output.format-only file). Arrays
@@ -878,8 +980,8 @@ export async function runSetupFromConfig(opts) {
             preferredStashDir: stashDir,
         });
         await runSetupSteps(steps, ctx);
-        if (!ctx.config.stashDir)
-            ctx.apply({ stashDir });
+        if (!ctx.config.primaryPath)
+            ctx.apply({ primaryPath: stashDir });
         if (!ctx.config.defaults?.engine) {
             const detected = detectAgentCliProfiles(undefined);
             const defaultProfile = pickDefaultAgentProfile(detected, undefined);
@@ -889,9 +991,7 @@ export async function runSetupFromConfig(opts) {
         }
         merged = ctx.config;
     }
-    // Fold the flat scratch model (stashDir + sources) into the persisted 0.9.0
-    // bundles shape (Decision E) so old-shape and new-shape input files both land
-    // as bundles; nothing half-migrated is ever validated or written.
+    // Convert the private setup draft to the persisted bundle shape.
     let finalizedMerged = finalizeSetupDraft(merged);
     // Reject an invalid merged engine graph before probing or touching the stash.
     validateCompleteConfig(finalizedMerged);
@@ -922,7 +1022,7 @@ export async function runSetupFromConfig(opts) {
     });
     return {
         configPath: getConfigPath(),
-        stashDir,
+        bundleDir: stashDir,
         stashCreated: initResult?.created ?? false,
         written: true,
         fields: Object.keys(incoming).filter((k) => incoming[k] !== undefined),