@askdkc/kiokuko 0.1.17 → 0.1.20

package/dist/commands/setup.js

@@ -1,21 +1,26 @@
-import { access, unlink } from 'node:fs/promises';
 import path from 'node:path';
+import { mkdir, rmdir } from 'node:fs/promises';
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
-import { atomicWriteText, readRegularFile } from '../agent-file/atomic-write.js';
-import { getClaudeInstructionsPath, getClaudeMcpConfigPath, getClaudeSkillsDirectory, getCodexConfigPath, getCodexInstructionsPath, getCodexSkillsDirectory, getGlobalDatabasePath, getHermesConfigPath, getHermesSkillsDirectory, getOpenCodeConfigDirectory, getOpenCodeInstructionsPath, getOpenCodeLoopGuardPath, getOpenCodeSkillsDirectory, } from '../config/paths.js';
+import { atomicWriteTextIfUnchanged, assertAtomicCleanupComplete, AtomicCommittedMutationError, AtomicCommittedUnlinkError, assertFileExpectation, readDirectoryIdentity, readRegularFile, unlinkRegularFileIfUnchanged, } from '../agent-file/atomic-write.js';
+import { getClaudeInstructionsPath, getClaudeMcpConfigPath, getClaudeSkillsDirectory, getCodexConfigPath, getCodexInstructionsPath, getCodexSkillsDirectory, getGlobalDatabasePath, getLegacyClaudePromptHookSettingsPath, getLegacyOpenCodeLoopGuardPath, getOpenCodeConfigDirectory, getOpenCodeInstructionsPath, getOpenCodeSkillsDirectory, resolveHermesProfilePaths, } from '../config/paths.js';
 import { initializeDatabase } from './init.js';
 import { openConnection } from '../db/connection.js';
 import { ensureGlobalWorkspace } from '../memory/workspaces.js';
 import { KiokukoError } from '../errors.js';
+import { isSkillDiscoveryMode, normalizeSkillDiscoveryMode, SKILL_DISCOVERY_ENV } from '../skills/config.js';
 import { renderOpenCodeConfig } from '../setup/opencode-config.js';
-import { renderOpenCodeLoopGuard } from '../setup/opencode-loop-guard.js';
 import { renderCodexMcpConfig, renderGlobalInstructions } from '../setup/render.js';
 import { renderClaudeConfig } from '../setup/claude-config.js';
 import { renderHermesConfig } from '../setup/hermes-config.js';
 import { detectInstalledClients } from '../setup/client-detection.js';
-import { loadBundledStandardSkillFiles, renderStandardSkillFile, STANDARD_UI_SKILL_NAME, } from '../setup/standard-skills.js';
+import { assertExactLegacyOpenCodeLoopGuard, cleanupLegacyClaudePromptHook, } from '../setup/legacy-client-cleanup.js';
+import { loadBundledStandardSkillFiles, renderStandardSkillFile, } from '../setup/standard-skills.js';
 export const SETUP_CLIENTS = ['codex', 'opencode', 'claude', 'hermes'];
+function setupPathJoin(options, ...segments) {
+    const platform = options.platform ?? process.platform;
+    return platform === 'win32' ? path.win32.join(...segments) : path.posix.join(...segments);
+}
 export function parseSetupClients(value) {
     const clients = [...new Set(value.split(',').map((client) => client.trim()).filter(Boolean))];
     if (clients.length === 0 || clients.some((client) => !SETUP_CLIENTS.includes(client))) {
@@ -23,6 +28,12 @@ export function parseSetupClients(value) {
     }
     return clients;
 }
+export function parseSetupSkillDiscoveryMode(value) {
+    if (!isSkillDiscoveryMode(value)) {
+        throw new KiokukoError('VALIDATION_ERROR', 'skill discovery must be off, official, or community');
+    }
+    return value;
+}
 function setupClientLabel(client) {
     if (client === 'codex')
         return 'Codex';
@@ -32,92 +43,316 @@ function setupClientLabel(client) {
         return 'Claude Code';
     return 'Hermes Agent';
 }
+async function askSetupClients(prompt, output, detected) {
+    const defaultSelection = detected.length === 0 ? 'none' : detected.join(',');
+    output.write('Select clients to configure (detected clients are preselected):\n');
+    for (const [index, client] of SETUP_CLIENTS.entries()) {
+        const checked = detected.includes(client) ? 'x' : ' ';
+        const status = detected.includes(client) ? 'detected' : 'not detected';
+        output.write(`  ${index + 1}. [${checked}] ${setupClientLabel(client)} (${status})\n`);
+    }
+    output.write('Enter client names or numbers separated by commas. Press Enter to accept the checked clients; type none to skip all.\n');
+    while (true) {
+        const answer = (await prompt.question(`Clients [${defaultSelection}]: `)).trim();
+        if (answer.length === 0)
+            return detected;
+        if (/^(?:none|なし)$/iu.test(answer))
+            return [];
+        const selected = [];
+        let invalid = false;
+        for (const token of answer.split(',').map((value) => value.trim()).filter(Boolean)) {
+            const index = Number(token);
+            const indexedClient = Number.isInteger(index) && index >= 1 && index <= SETUP_CLIENTS.length
+                ? SETUP_CLIENTS[index - 1]
+                : undefined;
+            const client = indexedClient ?? token.toLowerCase();
+            if (!SETUP_CLIENTS.includes(client)) {
+                invalid = true;
+                break;
+            }
+            selected.push(client);
+        }
+        if (!invalid)
+            return [...new Set(selected)];
+        output.write(`Invalid selection. Choose names or numbers for: ${SETUP_CLIENTS.join(', ')}.\n`);
+    }
+}
+async function askCommunitySkillDiscovery(prompt, output) {
+    output.write('Official external Skill discovery is enabled by default and uses validated content only as untrusted references. It never installs or executes Skills.\n');
+    output.write('Community discovery can also use audited community Skills as untrusted references when relevant.\n');
+    const answer = (await prompt.question('Enable community Skill discovery? [y/N] ')).trim();
+    return /^(?:y|yes|はい)$/iu.test(answer) ? 'community' : 'official';
+}
+async function askReplaceConflictingMcp(prompt, output, client) {
+    const label = setupClientLabel(client);
+    output.write(`${label} already has a non-canonical or unmanaged Kiokuko MCP identity.\n`);
+    output.write('Kiokuko can remove that identity, install the managed configuration, and continue setup.\n');
+    const answer = (await prompt.question(`Replace the existing ${label} Kiokuko MCP identity and continue? [y/N] `)).trim();
+    return /^(?:y|yes|はい)$/iu.test(answer);
+}
 /** Ask which supported clients should receive configuration in an interactive terminal. */
 export async function promptSetupClients(detected, options = {}) {
     const input = options.input ?? stdin;
     const output = options.output ?? stdout;
     const prompt = createInterface({ input, output });
-    const defaultSelection = detected.length === 0 ? 'none' : detected.join(',');
     try {
-        output.write('Select clients to configure (detected clients are preselected):\n');
-        for (const [index, client] of SETUP_CLIENTS.entries()) {
-            const checked = detected.includes(client) ? 'x' : ' ';
-            const status = detected.includes(client) ? 'detected' : 'not detected';
-            output.write(`  ${index + 1}. [${checked}] ${setupClientLabel(client)} (${status})\n`);
-        }
-        output.write('Enter client names or numbers separated by commas. Press Enter to accept the checked clients; type none to skip all.\n');
-        while (true) {
-            const answer = (await prompt.question(`Clients [${defaultSelection}]: `)).trim();
-            if (answer.length === 0)
-                return detected;
-            if (/^(?:none|なし)$/iu.test(answer))
-                return [];
-            const selected = [];
-            let invalid = false;
-            for (const token of answer.split(',').map((value) => value.trim()).filter(Boolean)) {
-                const index = Number(token);
-                const indexedClient = Number.isInteger(index) && index >= 1 && index <= SETUP_CLIENTS.length
-                    ? SETUP_CLIENTS[index - 1]
-                    : undefined;
-                const client = indexedClient ?? token.toLowerCase();
-                if (!SETUP_CLIENTS.includes(client)) {
-                    invalid = true;
-                    break;
-                }
-                selected.push(client);
-            }
-            if (!invalid)
-                return [...new Set(selected)];
-            output.write(`Invalid selection. Choose names or numbers for: ${SETUP_CLIENTS.join(', ')}.\n`);
-        }
+        return await askSetupClients(prompt, output, detected);
     }
     finally {
         prompt.close();
     }
 }
-async function exists(filePath) {
+/** Ask whether audited community Skill discovery should be enabled. */
+export async function promptCommunitySkillDiscovery(options = {}) {
+    const input = options.input ?? stdin;
+    const output = options.output ?? stdout;
+    const prompt = createInterface({ input, output });
     try {
-        await access(filePath);
-        return true;
+        return await askCommunitySkillDiscovery(prompt, output);
     }
-    catch (error) {
-        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
-            return false;
-        throw error;
+    finally {
+        prompt.close();
+    }
+}
+/** Ask before replacing a client Kiokuko MCP identity that setup does not own. */
+export async function promptReplaceConflictingMcp(client, options = {}) {
+    const input = options.input ?? stdin;
+    const output = options.output ?? stdout;
+    const prompt = createInterface({ input, output });
+    try {
+        return await askReplaceConflictingMcp(prompt, output, client);
+    }
+    finally {
+        prompt.close();
+    }
+}
+function replacementClientSet(value) {
+    if (value === undefined)
+        return new Set();
+    if (!Array.isArray(value)
+        || value.some((client) => !SETUP_CLIENTS.includes(client))
+        || new Set(value).size !== value.length) {
+        throw new KiokukoError('VALIDATION_ERROR', `replaceConflictingMcpServers must be a unique subset of: ${SETUP_CLIENTS.join(', ')}`);
+    }
+    return new Set(value);
+}
+/** Ask both setup questions through one readline session so buffered input remains intact. */
+export async function promptSetupConfiguration(detected, options = {}) {
+    const input = options.input ?? stdin;
+    const output = options.output ?? stdout;
+    const prompt = createInterface({ input, output });
+    try {
+        const clients = await askSetupClients(prompt, output, detected);
+        const skillDiscoveryMode = clients.length === 0
+            ? 'official'
+            : await askCommunitySkillDiscovery(prompt, output);
+        return { clients, skillDiscoveryMode };
+    }
+    finally {
+        prompt.close();
+    }
+}
+function sameFileIdentity(left, right) {
+    return left.device === right.device && left.inode === right.inode;
+}
+function setupDirectoryChanged(directoryPath) {
+    return new KiokukoError('CONFLICT', 'Setup directory changed after planning', { target: directoryPath });
+}
+function plannedDirectoryIdentity(directory) {
+    return directory.original ?? directory.created;
+}
+function directoryLineage(directory) {
+    const lineage = [];
+    let current = directory;
+    while (current !== undefined) {
+        lineage.push(current);
+        current = current.parent;
+    }
+    return lineage.reverse();
+}
+async function assertPlannedDirectory(directory) {
+    for (const planned of directoryLineage(directory)) {
+        const current = await readDirectoryIdentity(planned.path);
+        const expected = plannedDirectoryIdentity(planned);
+        if ((current === undefined) !== (expected === undefined)
+            || (current !== undefined && expected !== undefined && !sameFileIdentity(current, expected))) {
+            throw setupDirectoryChanged(planned.path);
+        }
+    }
+}
+async function planDirectory(planning, directoryPath) {
+    const resolved = path.resolve(directoryPath);
+    const existing = planning.directories.get(resolved);
+    if (existing !== undefined)
+        return existing;
+    const original = await readDirectoryIdentity(resolved);
+    const parentPath = path.dirname(resolved);
+    const parent = original !== undefined || parentPath === resolved
+        ? undefined
+        : await planDirectory(planning, parentPath);
+    const planned = {
+        path: resolved,
+        parent,
+        original,
+        created: undefined,
+    };
+    planning.directories.set(resolved, planned);
+    return planned;
+}
+async function readPlannedRegularFile(planning, filePath) {
+    const parentDirectory = await planDirectory(planning, path.dirname(filePath));
+    await assertPlannedDirectory(parentDirectory);
+    const snapshot = await readRegularFile(filePath);
+    await assertPlannedDirectory(parentDirectory);
+    return { parentDirectory, snapshot };
+}
+function errno(error) {
+    return error instanceof Error && 'code' in error
+        ? String(error.code)
+        : undefined;
+}
+async function preparePlannedDirectories(files, createdDirectories) {
+    const required = new Set();
+    for (const file of files) {
+        if (file.action === 'unchanged')
+            continue;
+        for (const directory of directoryLineage(file.parentDirectory))
+            required.add(directory);
+    }
+    const ordered = [...required].sort((left, right) => directoryLineage(left).length - directoryLineage(right).length);
+    for (const directory of ordered) {
+        const expected = plannedDirectoryIdentity(directory);
+        if (expected !== undefined) {
+            await assertPlannedDirectory(directory);
+            continue;
+        }
+        if (directory.parent === undefined) {
+            throw new KiokukoError('INTEGRITY_ERROR', 'Setup cannot create a missing filesystem root');
+        }
+        await assertPlannedDirectory(directory.parent);
+        if (await readDirectoryIdentity(directory.path) !== undefined) {
+            throw setupDirectoryChanged(directory.path);
+        }
+        try {
+            await mkdir(directory.path, { mode: 0o700 });
+        }
+        catch (error) {
+            if (errno(error) === 'EEXIST')
+                throw setupDirectoryChanged(directory.path);
+            throw error;
+        }
+        const created = await readDirectoryIdentity(directory.path);
+        if (created === undefined) {
+            throw new KiokukoError('INTEGRITY_ERROR', 'Setup directory disappeared immediately after creation', {
+                target: directory.path,
+            });
+        }
+        directory.created = created;
+        createdDirectories.push(directory);
+        await assertPlannedDirectory(directory);
     }
 }
-async function planFile(filePath, client, purpose, render) {
-    const original = await readRegularFile(filePath);
+async function removeCreatedDirectories(createdDirectories) {
+    const failures = [];
+    for (const directory of [...createdDirectories].reverse()) {
+        try {
+            await assertPlannedDirectory(directory);
+            await rmdir(directory.path);
+            if (await readDirectoryIdentity(directory.path) !== undefined) {
+                throw setupDirectoryChanged(directory.path);
+            }
+            directory.created = undefined;
+            if (directory.parent !== undefined)
+                await assertPlannedDirectory(directory.parent);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    return failures;
+}
+async function planFile(planning, filePath, client, purpose, render, mustRemainAbsent = []) {
+    const { parentDirectory, snapshot: original } = await readPlannedRegularFile(planning, filePath);
     const rendered = render(original?.content);
     const action = original === undefined
         ? 'created'
         : rendered.content === original.content ? 'unchanged' : 'updated';
     return {
         path: filePath,
+        parentDirectory,
         content: rendered.content,
         mode: original?.mode ?? 0o600,
-        original: original?.content,
+        original,
+        ...(mustRemainAbsent.length === 0 ? {} : { mustRemainAbsent }),
         action,
         purpose,
         client,
+        report: true,
     };
 }
-async function openCodeConfigPath(options) {
+async function planLegacyClaudeHookCleanup(planning, options) {
+    const filePath = getLegacyClaudePromptHookSettingsPath(options);
+    const { parentDirectory, snapshot: original } = await readPlannedRegularFile(planning, filePath);
+    const content = original === undefined ? undefined : cleanupLegacyClaudePromptHook(original.content);
+    const changed = original !== undefined && content !== original.content;
+    return {
+        path: filePath,
+        parentDirectory,
+        content,
+        mode: original?.mode ?? 0o600,
+        original,
+        action: changed ? 'updated' : 'unchanged',
+        purpose: 'legacy-cleanup',
+        client: 'claude',
+        report: changed,
+    };
+}
+async function planLegacyOpenCodeGuardCleanup(planning, options) {
+    const filePath = getLegacyOpenCodeLoopGuardPath(options);
+    const { parentDirectory, snapshot: original } = await readPlannedRegularFile(planning, filePath);
+    if (original !== undefined)
+        assertExactLegacyOpenCodeLoopGuard(original.content);
+    return {
+        path: filePath,
+        parentDirectory,
+        content: undefined,
+        mode: original?.mode ?? 0o600,
+        original,
+        action: original === undefined ? 'unchanged' : 'deleted',
+        purpose: 'legacy-cleanup',
+        client: 'opencode',
+        report: original !== undefined,
+    };
+}
+async function openCodeConfigPath(planning, options) {
     const directory = getOpenCodeConfigDirectory(options);
-    const jsonc = path.join(directory, 'opencode.jsonc');
-    if (await exists(jsonc))
-        return jsonc;
-    return path.join(directory, 'opencode.json');
+    const jsonc = setupPathJoin(options, directory, 'opencode.jsonc');
+    if ((await readPlannedRegularFile(planning, jsonc)).snapshot !== undefined) {
+        return { path: jsonc, mustRemainAbsent: [] };
+    }
+    return { path: setupPathJoin(options, directory, 'opencode.json'), mustRemainAbsent: [jsonc] };
 }
-async function restoreFiles(files) {
-    for (const file of [...files].reverse()) {
-        if (file.action === 'unchanged')
-            continue;
-        if (file.original === undefined)
-            await unlink(file.path).catch(() => undefined);
-        else
-            await atomicWriteText(file.path, file.original, file.mode).catch(() => undefined);
+async function restoreFiles(mutations, dependencies) {
+    const failures = [];
+    for (const mutation of [...mutations].reverse()) {
+        const { file, installed } = mutation;
+        try {
+            if (file.original === undefined) {
+                if (installed === undefined)
+                    throw new KiokukoError('INTEGRITY_ERROR', 'Setup rollback record is invalid');
+                const outcome = await dependencies.unlinkRegularFileIfUnchanged(file.path, fileExpectation(file, installed, false));
+                assertAtomicCleanupComplete(outcome);
+            }
+            else {
+                const outcome = await dependencies.atomicWriteTextIfUnchanged(file.path, file.original.content, fileExpectation(file, installed, false), file.original.mode);
+                assertAtomicCleanupComplete(outcome);
+            }
+        }
+        catch (error) {
+            failures.push(error);
+        }
     }
+    return failures;
 }
 function setupNextStep(clients, standardSkills) {
     return clients.map((client) => {
@@ -130,55 +365,119 @@ function setupNextStep(clients, standardSkills) {
         return `Restart ${label} so it reloads global MCP and instruction configuration${standardSkills ? ' and standard skills' : ''}.`;
     }).join(' ');
 }
-async function standardSkillDirectory(client, options) {
+async function standardSkillDirectory(client, options, hermesProfile) {
     if (client === 'codex')
         return getCodexSkillsDirectory(options);
     if (client === 'opencode')
         return getOpenCodeSkillsDirectory(options);
     if (client === 'claude')
         return getClaudeSkillsDirectory(options);
-    return getHermesSkillsDirectory(options);
+    if (hermesProfile === undefined)
+        throw new KiokukoError('INTEGRITY_ERROR', 'Hermes profile was not bound during setup planning');
+    return hermesProfile.skillsDirectory;
+}
+function fileExpectation(file, expected, includeAlternatePaths = true) {
+    const expectedParentDirectory = plannedDirectoryIdentity(file.parentDirectory);
+    if (expectedParentDirectory === undefined) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Setup file parent was not created or bound before mutation', {
+            target: file.parentDirectory.path,
+        });
+    }
+    return {
+        expected,
+        expectedParentDirectory,
+        ...(includeAlternatePaths && file.mustRemainAbsent !== undefined
+            ? { mustRemainAbsent: file.mustRemainAbsent }
+            : {}),
+    };
 }
-export async function setupGlobalClients(options = {}) {
+async function assertPlannedFile(file, expected) {
+    await assertPlannedDirectory(file.parentDirectory);
+    if (plannedDirectoryIdentity(file.parentDirectory) === undefined) {
+        if (expected !== undefined || await readRegularFile(file.path) !== undefined) {
+            throw setupDirectoryChanged(file.parentDirectory.path);
+        }
+        for (const absentPath of file.mustRemainAbsent ?? []) {
+            if (await readRegularFile(absentPath) !== undefined) {
+                throw new KiokukoError('CONFLICT', 'Setup target changed after planning', { target: absentPath });
+            }
+        }
+    }
+    else {
+        await assertFileExpectation(file.path, fileExpectation(file, expected));
+    }
+    await assertPlannedDirectory(file.parentDirectory);
+}
+async function assertPlannedFiles(files, applied = []) {
+    const installedByPath = new Map(applied.map((mutation) => [mutation.file.path, mutation.installed]));
+    for (const file of files) {
+        const expected = installedByPath.has(file.path) ? installedByPath.get(file.path) : file.original;
+        await assertPlannedFile(file, expected);
+    }
+}
+export async function setupGlobalClients(options = {}, dependencyOverrides = {}) {
+    const dependencies = {
+        atomicWriteTextIfUnchanged: dependencyOverrides.atomicWriteTextIfUnchanged ?? atomicWriteTextIfUnchanged,
+        unlinkRegularFileIfUnchanged: dependencyOverrides.unlinkRegularFileIfUnchanged ?? unlinkRegularFileIfUnchanged,
+        beforeCommit: dependencyOverrides.beforeCommit ?? (() => undefined),
+        openConnection: dependencyOverrides.openConnection ?? openConnection,
+        ensureGlobalWorkspace: dependencyOverrides.ensureGlobalWorkspace ?? ensureGlobalWorkspace,
+    };
     const pathEnvironment = {
         ...(options.platform === undefined ? {} : { platform: options.platform }),
         ...(options.env === undefined ? {} : { env: options.env }),
     };
+    if (options.skillDiscoveryMode !== undefined && !isSkillDiscoveryMode(options.skillDiscoveryMode)) {
+        throw new KiokukoError('VALIDATION_ERROR', 'skill discovery must be off, official, or community');
+    }
+    const replaceConflictingMcpServers = replacementClientSet(options.replaceConflictingMcpServers);
     const clients = options.clients ?? await detectInstalledClients(pathEnvironment);
-    if (clients.some((client) => !SETUP_CLIENTS.includes(client))) {
+    if (!Array.isArray(clients) || clients.some((client) => !SETUP_CLIENTS.includes(client))) {
         throw new KiokukoError('VALIDATION_ERROR', `clients must be a subset of: ${SETUP_CLIENTS.join(', ')}`);
     }
     const command = options.command ?? 'kiokuko';
-    if (command.trim().length === 0 || command.includes('\0'))
+    if (typeof command !== 'string' || command.trim().length === 0 || command.includes('\0')) {
         throw new KiokukoError('VALIDATION_ERROR', 'command must be a non-empty executable path or name');
+    }
     const databasePath = options.databasePath ?? getGlobalDatabasePath(pathEnvironment);
     const standardSkills = options.standardSkills ?? true;
+    const environment = options.env ?? process.env;
+    const environmentSkillDiscoveryMode = options.skillDiscoveryMode === undefined
+        && Object.prototype.hasOwnProperty.call(environment, SKILL_DISCOVERY_ENV)
+        ? normalizeSkillDiscoveryMode(environment[SKILL_DISCOVERY_ENV])
+        : undefined;
+    const skillDiscoveryMode = options.skillDiscoveryMode ?? environmentSkillDiscoveryMode;
     const files = [];
+    const planning = { directories: new Map() };
+    const hermesProfile = clients.includes('hermes')
+        ? await resolveHermesProfilePaths(pathEnvironment)
+        : undefined;
     if (clients.includes('codex')) {
-        files.push(await planFile(getCodexConfigPath(pathEnvironment), 'codex', 'mcp-config', (existing) => renderCodexMcpConfig(existing ?? '', command)));
-        files.push(await planFile(getCodexInstructionsPath(pathEnvironment), 'codex', 'instructions', (existing) => renderGlobalInstructions(existing ?? '')));
+        files.push(await planFile(planning, getCodexConfigPath(pathEnvironment), 'codex', 'mcp-config', (existing) => renderCodexMcpConfig(existing ?? '', command, skillDiscoveryMode, { replaceConflictingIdentity: replaceConflictingMcpServers.has('codex') })));
+        files.push(await planFile(planning, getCodexInstructionsPath(pathEnvironment), 'codex', 'instructions', (existing) => renderGlobalInstructions(existing ?? '')));
     }
     if (clients.includes('opencode')) {
-        files.push(await planFile(await openCodeConfigPath(pathEnvironment), 'opencode', 'mcp-config', (existing) => renderOpenCodeConfig(existing, command)));
-        files.push(await planFile(getOpenCodeInstructionsPath(pathEnvironment), 'opencode', 'instructions', (existing) => renderGlobalInstructions(existing ?? '')));
-        files.push(await planFile(getOpenCodeLoopGuardPath(pathEnvironment), 'opencode', 'runtime-guard', (existing) => renderOpenCodeLoopGuard(existing, {
-            ...(options.opencodeCapture === undefined ? {} : { captureProfile: options.opencodeCapture }),
-            ...(options.opencodeMode === undefined ? {} : { mode: options.opencodeMode }),
-        })));
+        const selectedConfig = await openCodeConfigPath(planning, pathEnvironment);
+        files.push(await planFile(planning, selectedConfig.path, 'opencode', 'mcp-config', (existing) => renderOpenCodeConfig(existing, command, skillDiscoveryMode, { replaceConflictingIdentity: replaceConflictingMcpServers.has('opencode') }), selectedConfig.mustRemainAbsent));
+        files.push(await planFile(planning, getOpenCodeInstructionsPath(pathEnvironment), 'opencode', 'instructions', (existing) => renderGlobalInstructions(existing ?? '')));
+        files.push(await planLegacyOpenCodeGuardCleanup(planning, pathEnvironment));
     }
     if (clients.includes('claude')) {
-        files.push(await planFile(getClaudeMcpConfigPath(pathEnvironment), 'claude', 'mcp-config', (existing) => renderClaudeConfig(existing, command)));
-        files.push(await planFile(getClaudeInstructionsPath(pathEnvironment), 'claude', 'instructions', (existing) => renderGlobalInstructions(existing ?? '')));
+        files.push(await planFile(planning, getClaudeMcpConfigPath(pathEnvironment), 'claude', 'mcp-config', (existing) => renderClaudeConfig(existing, command, skillDiscoveryMode, { replaceConflictingIdentity: replaceConflictingMcpServers.has('claude') })));
+        files.push(await planFile(planning, getClaudeInstructionsPath(pathEnvironment), 'claude', 'instructions', (existing) => renderGlobalInstructions(existing ?? '')));
+        files.push(await planLegacyClaudeHookCleanup(planning, pathEnvironment));
     }
     if (clients.includes('hermes')) {
-        files.push(await planFile(await getHermesConfigPath(pathEnvironment), 'hermes', 'mcp-config', (existing) => renderHermesConfig(existing, command)));
+        if (hermesProfile === undefined)
+            throw new KiokukoError('INTEGRITY_ERROR', 'Hermes profile was not bound during setup planning');
+        files.push(await planFile(planning, hermesProfile.configPath, 'hermes', 'mcp-config', (existing) => renderHermesConfig(existing, command, skillDiscoveryMode, { replaceConflictingIdentity: replaceConflictingMcpServers.has('hermes') })));
     }
     if (standardSkills) {
         const bundledFiles = await loadBundledStandardSkillFiles();
         for (const client of clients) {
-            const destination = path.join(await standardSkillDirectory(client, pathEnvironment), STANDARD_UI_SKILL_NAME);
+            const skillsDirectory = await standardSkillDirectory(client, pathEnvironment, hermesProfile);
             for (const bundled of bundledFiles) {
-                files.push(await planFile(path.join(destination, bundled.relativePath), client, 'standard-skill', (existing) => renderStandardSkillFile(existing, bundled)));
+                files.push(await planFile(planning, setupPathJoin(pathEnvironment, skillsDirectory, bundled.skillName, bundled.relativePath), client, 'standard-skill', (existing) => renderStandardSkillFile(existing, bundled)));
             }
         }
     }
@@ -188,7 +487,9 @@ export async function setupGlobalClients(options = {}) {
         databaseAction: options.dryRun ? 'planned' : 'initialized',
         databaseBackupPath: null,
         appliedMigrations: [],
-        files: files.map(({ path: filePath, action, purpose, client }) => ({ path: filePath, action, purpose, client })),
+        files: files
+            .filter((file) => file.report)
+            .map(({ path: filePath, action, purpose, client }) => ({ path: filePath, action, purpose, client })),
         standardSkills,
         dryRun: options.dryRun ?? false,
         nextStep: setupNextStep(clients, standardSkills),
@@ -201,24 +502,85 @@ export async function setupGlobalClients(options = {}) {
     });
     result.databaseBackupPath = initialized.backupPath;
     result.appliedMigrations = initialized.applied;
-    const database = openConnection(databasePath);
+    const database = dependencies.openConnection(databasePath);
+    let workspaceInitializationFailed = false;
+    let workspaceInitializationError;
     try {
-        ensureGlobalWorkspace(database);
+        dependencies.ensureGlobalWorkspace(database);
     }
-    finally {
+    catch (error) {
+        workspaceInitializationFailed = true;
+        workspaceInitializationError = error;
+    }
+    try {
         database.close();
     }
-    const written = [];
+    catch (closeError) {
+        if (workspaceInitializationFailed) {
+            throw new AggregateError([workspaceInitializationError, closeError], 'Global workspace initialization failed and closing the database connection also failed');
+        }
+        throw closeError;
+    }
+    if (workspaceInitializationFailed)
+        throw workspaceInitializationError;
+    const applied = [];
+    const createdDirectories = [];
     try {
+        await dependencies.beforeCommit();
+        await preparePlannedDirectories(files, createdDirectories);
+        await assertPlannedFiles(files);
         for (const file of files) {
             if (file.action === 'unchanged')
                 continue;
-            await atomicWriteText(file.path, file.content, file.mode);
-            written.push(file);
+            // Record a committed mutation before inspecting its cleanup outcome so
+            // rollback never loses ownership of a target that already changed.
+            let installed;
+            if (file.action === 'deleted') {
+                if (file.original === undefined)
+                    throw new KiokukoError('INTEGRITY_ERROR', 'Setup deletion plan is missing original content');
+                let outcome;
+                try {
+                    outcome = await dependencies.unlinkRegularFileIfUnchanged(file.path, fileExpectation(file, file.original));
+                }
+                catch (error) {
+                    if (error instanceof AtomicCommittedUnlinkError) {
+                        applied.push({ file, installed: undefined });
+                    }
+                    throw error;
+                }
+                applied.push({ file, installed: undefined });
+                assertAtomicCleanupComplete(outcome);
+            }
+            else {
+                if (file.content === undefined)
+                    throw new KiokukoError('INTEGRITY_ERROR', 'Setup file plan is missing rendered content');
+                let outcome;
+                try {
+                    outcome = await dependencies.atomicWriteTextIfUnchanged(file.path, file.content, fileExpectation(file, file.original), file.mode);
+                }
+                catch (error) {
+                    if (error instanceof AtomicCommittedMutationError) {
+                        applied.push({ file, installed: error.outcome.installed });
+                    }
+                    else if (error instanceof AtomicCommittedUnlinkError) {
+                        applied.push({ file, installed: undefined });
+                    }
+                    throw error;
+                }
+                installed = outcome.installed;
+                applied.push({ file, installed });
+                assertAtomicCleanupComplete(outcome);
+            }
         }
+        await assertPlannedFiles(files, applied);
     }
     catch (error) {
-        await restoreFiles(written);
+        const restorationFailures = await restoreFiles(applied, dependencies);
+        const directoryRestorationFailures = await removeCreatedDirectories(createdDirectories);
+        const failures = [...restorationFailures, ...directoryRestorationFailures];
+        if (failures.length > 0) {
+            throw new AggregateError([error, ...failures], 'Setup failed and filesystem restoration also failed');
+        }
         throw error;
     }
     return result;