@phyzess/pappra 0.1.0-beta.1 → 0.1.0-beta.10

package/dist/app/init.js

@@ -1,18 +1,22 @@
 import { randomUUID } from 'node:crypto';
 import { basename, dirname, join, resolve } from 'node:path';
-import { mkdir, open, readFile, rm, rmdir } from 'node:fs/promises';
+import { mkdir, open, readFile, rename, rm, rmdir, writeFile, } from 'node:fs/promises';
 import { createDiagnostic, hasErrors, pointer, } from '../schemas/diagnostics.js';
 import { diagnosticCodes } from '../schemas/errors.js';
-import { initPlanSchema, parseInitChoices, } from '../schemas/init.js';
+import { INIT_CHOICES_SCHEMA, initPlanSchema, parseInitChoices, } from '../schemas/init.js';
 import { machineConfigSchema } from '../schemas/machine.js';
 import { isExternalRepositoryPath, isPathInside, isPortableRelativePath, normalizePortableRelativePath, resolvePortableRelativePath, samePath, } from '../schemas/paths.js';
 import { WORKSPACE_SCHEMA, validateWorkspaceConfigSemantics, workspaceConfigSchema, } from '../schemas/workspace.js';
 import { getPackageInfo } from '../package-info.js';
+import { spawnSync } from 'node:child_process';
+import { executableOnPath } from '../hosts/detect.js';
+import { HOST_SUPPORT } from '../hosts/integration/support.js';
 import { observePath, resolveRealpath, sha256Digest } from '../infra/fs.js';
 import { inspectMachineConfig, inspectWorkspaceConfig, } from '../workspace/config.js';
 import { discoverWorkspace, } from '../workspace/discover.js';
 import { resolveWorkspaceRoot } from '../workspace/resolve.js';
 import { buildInitPlan } from '../install/plan.js';
+import { backupPath, ensureStatePathBoundary, readWorkspaceManifest, writeWorkspaceManifest, } from '../install/ownership.js';
 import { beginManagedApply, completeManagedApply, failManagedApply, recordManagedFile, } from '../install/apply.js';
 const workspaceConfigRelativePath = '.pappra/workspace.json';
 const machineConfigRelativePath = '.pappra/local/machine.json';
@@ -239,6 +243,164 @@ export function listKnowledgeCandidates(discovery) {
     }
     return [...candidates.values()].sort((left, right) => left.path.localeCompare(right.path));
 }
+const derivedExcludes = [
+    'node_modules',
+    'dist',
+    'coverage',
+    'tmp',
+    'test-results',
+];
+const derivedValidationScripts = ['lint', 'typecheck', 'test'];
+function detectedHostVersion(command, pathEnv) {
+    const executable = executableOnPath(command, pathEnv);
+    if (executable === null)
+        return null;
+    const probe = spawnSync(executable, ['--version'], {
+        encoding: 'utf8',
+        shell: false,
+        timeout: 3_000,
+        maxBuffer: 256 * 1024,
+    });
+    if (probe.error !== undefined || probe.status !== 0)
+        return null;
+    const output = `${probe.stdout ?? ''}\n${probe.stderr ?? ''}`;
+    const match = /(\d+\.\d+\.\d+)/.exec(output);
+    return match?.[1] ?? null;
+}
+/**
+ * Derives deterministic init selections from discovery alone. Every value is
+ * reported with the rule that produced it so a caller can audit the choice
+ * before applying it; nothing here writes, installs or prompts.
+ */
+export async function deriveInitChoices(discovery, options = {}) {
+    const pathEnv = options.pathEnv ?? process.env['PATH'] ?? '';
+    const rules = [];
+    const repositories = discovery.repositories.map((repository) => {
+        const path = repositoryKey(repository);
+        const access = samePath(repository.root, discovery.root)
+            ? 'write'
+            : 'read';
+        rules.push({
+            field: 'repositories',
+            value: path,
+            reason: access === 'write'
+                ? 'workspace-root checkout is selected for write access'
+                : 'discovered checkout outside the workspace root is read-only',
+        });
+        return { path, access };
+    });
+    const knowledgeCandidates = listKnowledgeCandidates(discovery);
+    const rootRuleFiles = ['AGENTS.md', 'CLAUDE.md'];
+    const knowledgeSources = [];
+    for (const name of rootRuleFiles) {
+        const candidate = knowledgeCandidates.find((entry) => entry.path.toLowerCase() === name.toLowerCase());
+        if (candidate === undefined)
+            continue;
+        knowledgeSources.push(candidate.path);
+        rules.push({
+            field: 'knowledge.sources',
+            value: candidate.path,
+            reason: 'workspace-root rule file reported by discovery',
+        });
+    }
+    const docs = knowledgeCandidates.find((entry) => entry.path === 'docs');
+    if (docs !== undefined) {
+        knowledgeSources.push(docs.path);
+        rules.push({
+            field: 'knowledge.sources',
+            value: docs.path,
+            reason: 'documentation directory reported by discovery',
+        });
+    }
+    const codegraphDetected = executableOnPath('codegraph', pathEnv) !== null &&
+        (await Promise.all(discovery.repositories.map(async (repository) => observePath(join(repository.root, '.codegraph'))))).some((observation) => observation.kind !== 'missing');
+    const graph = codegraphDetected ? 'codegraph' : 'none';
+    rules.push({
+        field: 'code.graph',
+        value: graph,
+        reason: codegraphDetected
+            ? 'codegraph executable and .codegraph index were both observed'
+            : 'no codegraph executable plus .codegraph index pair was observed',
+    });
+    rules.push({
+        field: 'code.symbols',
+        value: 'auto',
+        reason: 'symbol providers are detected passively at use time',
+    });
+    rules.push({
+        field: 'code.prepare',
+        value: 'on-demand',
+        reason: 'index preparation stays an explicit, bounded action',
+    });
+    const validation = [];
+    for (const script of derivedValidationScripts) {
+        const candidate = discovery.validationCandidates.find((entry) => entry.id.endsWith(`:${script}`) && !validation.includes(entry.id));
+        if (candidate === undefined)
+            continue;
+        validation.push(candidate.id);
+        rules.push({
+            field: 'validation',
+            value: candidate.id,
+            reason: `package script "${script}" reported by discovery`,
+        });
+    }
+    rules.push({
+        field: 'excludes',
+        value: derivedExcludes.join(', '),
+        reason: 'built-in defaults keep generated and dependency trees out of scope',
+    });
+    const hosts = [];
+    for (const host of ['claude', 'codex', 'pi']) {
+        const command = host;
+        const version = detectedHostVersion(command, pathEnv);
+        if (version === null || version !== HOST_SUPPORT[host].version) {
+            rules.push({
+                field: 'hosts',
+                value: host,
+                reason: version === null
+                    ? 'host executable was not observed on PATH'
+                    : `observed version ${version} is outside the pinned support matrix`,
+            });
+            continue;
+        }
+        hosts.push(host);
+        rules.push({
+            field: 'hosts',
+            value: host,
+            reason: `host executable reports the pinned version ${version}`,
+        });
+    }
+    const name = basename(discovery.root);
+    rules.push({
+        field: 'name',
+        value: name,
+        reason: 'workspace name derived from the workspace root directory',
+    });
+    const choices = {
+        schema: INIT_CHOICES_SCHEMA,
+        name,
+        repositories,
+        knowledge: {
+            sources: knowledgeSources,
+            newDocuments: '.pappra/knowledge',
+            taskVisibility: 'private',
+        },
+        code: { graph, symbols: 'auto', prepare: 'on-demand' },
+        validation,
+        excludes: [...derivedExcludes],
+        hosts,
+    };
+    return {
+        choices,
+        rules,
+        candidates: {
+            repositories: listRepositoryCandidates(discovery).map((candidate) => candidate.key),
+            knowledge: knowledgeCandidates.map((candidate) => candidate.path),
+            validation: discovery.validationCandidates.map((candidate) => candidate.id),
+            hosts,
+        },
+    };
+}
 function selectRepositories(choices, discovery, root) {
     const diagnostics = [];
     const byKey = new Map();
@@ -505,22 +667,38 @@ function scopeRepositories(config, discovery) {
         };
     });
 }
-function planFilesFor(config, machine, needWorkspaceConfig, needMachineConfig) {
+function planFilesFor(config, machine, needWorkspaceConfig, needMachineConfig, existing) {
     const workspaceBytes = needWorkspaceConfig ? jsonBytes(config) : null;
     const machineBytes = needMachineConfig ? jsonBytes(machine) : null;
     const files = [];
-    if (workspaceBytes !== null) {
+    if (workspaceBytes !== null &&
+        existing.workspaceDigest !== sha256Digest(workspaceBytes)) {
         files.push({
             path: workspaceConfigRelativePath,
             bytes: workspaceBytes,
             beforeText: null,
+            ...(existing.workspaceDigest === null
+                ? {}
+                : {
+                    operation: 'replace-managed',
+                    expectedBeforeDigest: existing.workspaceDigest,
+                    backupRequired: true,
+                }),
         });
     }
-    if (machineBytes !== null) {
+    if (machineBytes !== null &&
+        existing.machineDigest !== sha256Digest(machineBytes)) {
         files.push({
             path: machineConfigRelativePath,
             bytes: machineBytes,
             beforeText: null,
+            ...(existing.machineDigest === null
+                ? {}
+                : {
+                    operation: 'replace-managed',
+                    expectedBeforeDigest: existing.machineDigest,
+                    backupRequired: true,
+                }),
         });
     }
     return { files, workspaceBytes, machineBytes };
@@ -626,14 +804,16 @@ export async function planWorkspaceInit(options) {
     const existingMachine = context.machineInspection.value;
     const diagnostics = [...context.diagnostics];
     const runtimeVersion = options.runtimeVersion ??
-        existingConfig?.runtimeVersion ??
+        (options.reconfigure === true
+            ? undefined
+            : existingConfig?.runtimeVersion) ??
         getPackageInfo().version;
     let config;
     let machine;
     let needWorkspaceConfig = false;
     let needMachineConfig = false;
     let selected = [];
-    if (existingConfig !== null) {
+    if (existingConfig !== null && options.reconfigure !== true) {
         config = existingConfig;
         if (choices !== null) {
             diagnostics.push(info(diagnosticCodes.initExistingConfigReused, 'Existing valid workspace configuration is reused; init selections do not overwrite it.', context.workspaceInspection.path, 'Use a future configure flow to change existing workspace policy.'));
@@ -655,7 +835,10 @@ export async function planWorkspaceInit(options) {
         if (choices === null) {
             return failure('needs_input', diagnosticCodes.initInputRequired, 'Workspace configuration is missing; init selections are required.', diagnostics, 'Provide --config with pappra/init-choices/1 selections, or run the interactive wizard.');
         }
-        const built = buildWorkspaceConfig(context.root, choices, context.discovery, runtimeVersion);
+        const effectiveChoices = existingConfig !== null && choices.workspaceId === undefined
+            ? { ...choices, workspaceId: existingConfig.workspaceId }
+            : choices;
+        const built = buildWorkspaceConfig(context.root, effectiveChoices, context.discovery, runtimeVersion);
         diagnostics.push(...built.diagnostics);
         if (built.config === null) {
             return failureFromDiagnostics('invalid', diagnostics, diagnosticCodes.initInvalidInput, 'Init selections do not form a valid workspace configuration.');
@@ -685,7 +868,10 @@ export async function planWorkspaceInit(options) {
             machine = parsedMachine.data;
         }
     }
-    const filePlan = planFilesFor(config, machine, needWorkspaceConfig, needMachineConfig);
+    const filePlan = planFilesFor(config, machine, needWorkspaceConfig, needMachineConfig, {
+        workspaceDigest: context.workspaceInspection.digest,
+        machineDigest: context.machineInspection.digest,
+    });
     const configurationDigest = filePlan.workspaceBytes !== null
         ? sha256Digest(filePlan.workspaceBytes)
         : (context.workspaceInspection.digest ??
@@ -734,7 +920,9 @@ export async function planWorkspaceInit(options) {
         workspaceId: config.workspaceId,
         name: config.name,
         runtimeVersion: config.runtimeVersion,
-        configSource: existingConfig !== null ? 'existing' : 'planned',
+        configSource: existingConfig !== null && options.reconfigure !== true
+            ? 'existing'
+            : 'planned',
         repositories: scopeRepos,
         knowledge: config.knowledge,
         code: config.code,
@@ -863,13 +1051,23 @@ async function verifyBundleWrites(bundle) {
                 hint: 'Regenerate the plan.',
             }));
         }
-        if (file.operation !== 'create') {
+        if (file.operation !== 'create' && file.operation !== 'replace-managed') {
             diagnostics.push(createDiagnostic({
                 code: diagnosticCodes.initApplyUnsupported,
                 severity: 'error',
-                message: `P03 apply supports only create operations; ${file.path} is ${file.operation}.`,
+                message: `Init apply does not support operation ${file.operation} for ${file.path}.`,
                 source: 'init plan',
-                hint: 'P04 will implement managed replacement with a journal and rollback.',
+                hint: 'Regenerate the plan with create or replace-managed operations.',
+            }));
+        }
+        if (file.operation === 'replace-managed' &&
+            file.expectedBeforeDigest === null) {
+            diagnostics.push(createDiagnostic({
+                code: diagnosticCodes.initPlanInvalid,
+                severity: 'error',
+                message: `Managed replacement for ${file.path} has no expected before digest.`,
+                source: 'init plan',
+                hint: 'Regenerate the plan; Pappra does not replace an unverified file.',
             }));
         }
         if (sha256Digest(write.bytes) !== file.nextDigest) {
@@ -944,16 +1142,22 @@ export async function applyInitPlan(bundle, options = {}) {
     const workspaceInspection = await inspectWorkspaceConfig(root, {
         missing: 'info',
     });
-    const workspaceFilePlanned = bundle.plan.files.some((file) => file.path === workspaceConfigRelativePath);
-    if (workspaceFilePlanned) {
-        if (workspaceInspection.exists) {
+    const workspaceFileIndex = bundle.plan.files.findIndex((file) => file.path === workspaceConfigRelativePath);
+    const workspaceFile = workspaceFileIndex === -1 ? null : bundle.plan.files[workspaceFileIndex];
+    if (workspaceFile === null &&
+        (!workspaceInspection.exists ||
+            workspaceInspection.value === null ||
+            workspaceInspection.digest !== bundle.plan.configurationDigest)) {
+        return planDiagnostics('Workspace configuration changed since planning.', diagnosticCodes.initPlanStale);
+    }
+    if (workspaceFile !== null) {
+        if (workspaceFile.operation === 'create' && workspaceInspection.exists) {
             return applyFailure('conflict', diagnosticCodes.initTargetExists, 'Workspace configuration appeared after planning.', 'Remove or relocate the unexpected file, then retry init.');
         }
-    }
-    else if (!workspaceInspection.exists ||
-        workspaceInspection.value === null ||
-        workspaceInspection.digest !== bundle.plan.configurationDigest) {
-        return planDiagnostics('Workspace configuration changed since planning.', diagnosticCodes.initPlanStale);
+        if (workspaceFile.operation === 'replace-managed' &&
+            workspaceInspection.digest !== workspaceFile.expectedBeforeDigest) {
+            return planDiagnostics('Workspace configuration changed since planning.', diagnosticCodes.initPlanStale);
+        }
     }
     for (const file of bundle.plan.files) {
         const target = await safeTarget(root, file.path);
@@ -961,29 +1165,28 @@ export async function applyInitPlan(bundle, options = {}) {
             return applyFailure('conflict', diagnosticCodes.initTargetUnsafe, `Planned target is not a safe workspace-relative path: ${file.path}`, 'Regenerate the plan; Pappra does not follow symlinked parents outside the workspace.');
         }
         const observation = await observePath(target.absolutePath);
-        if (observation.kind !== 'missing') {
-            return applyFailure('conflict', diagnosticCodes.initTargetExists, `Planned target already exists: ${file.path}`, 'Remove or relocate the unexpected file, then retry init.');
+        if (file.operation === 'create') {
+            if (observation.kind !== 'missing') {
+                return applyFailure('conflict', diagnosticCodes.initTargetExists, `Planned target already exists: ${file.path}`, 'Remove or relocate the unexpected file, then retry init.');
+            }
+            continue;
+        }
+        if (observation.kind !== 'file' || observation.stats === null) {
+            return applyFailure('conflict', diagnosticCodes.initTargetExists, `Planned replacement target is not a regular file: ${file.path}`, 'Inspect the target; Pappra does not replace directories or special files.');
+        }
+        const before = await readFile(target.absolutePath);
+        if (file.expectedBeforeDigest === null ||
+            sha256Digest(before) !== file.expectedBeforeDigest) {
+            return planDiagnostics(`Planned replacement target changed since planning: ${file.path}`, diagnosticCodes.initPlanStale);
         }
     }
-    const managedStart = await beginManagedApply(root, bundle.plan, bundle.writes, bundle.rootIdentity);
-    if (!managedStart.ok) {
-        const status = managedStart.status === 'invalid'
-            ? 'stale'
-            : managedStart.status === 'locked'
-                ? 'conflict'
-                : 'failed';
-        return {
-            ok: false,
-            status,
-            appliedFiles: [],
-            pendingExternalActions: [],
-            residualPaths: managedStart.residualPaths,
-            diagnostics: managedStart.diagnostics,
-        };
-    }
-    const managed = managedStart.context;
-    let created = [];
-    let createdDirectories = [];
+    const createIndexes = bundle.plan.files.flatMap((file, index) => file.operation === 'create' ? [index] : []);
+    const replaceIndexes = bundle.plan.files.flatMap((file, index) => file.operation === 'replace-managed' ? [index] : []);
+    let managed = null;
+    const created = [];
+    const createdDirectories = [];
+    const replacements = [];
+    let originalManifest = null;
     const ensureDirectory = async (directory) => {
         const missing = [];
         let current = directory;
@@ -1008,6 +1211,19 @@ export async function applyInitPlan(bundle, options = {}) {
             createdDirectories.push(path);
         }
     };
+    const restoreReplacements = async () => {
+        for (const replacement of [...replacements].reverse()) {
+            try {
+                await writeFile(replacement.absolutePath, replacement.beforeBytes);
+            }
+            catch {
+                // The residual list below and the failure diagnostic report this case.
+            }
+        }
+        if (originalManifest !== null) {
+            await writeWorkspaceManifest(root, originalManifest).catch(() => undefined);
+        }
+    };
     const rootBeforeWrite = await observePath(root);
     if (rootBeforeWrite.kind !== 'directory' ||
         rootBeforeWrite.stats === null ||
@@ -1016,73 +1232,169 @@ export async function applyInitPlan(bundle, options = {}) {
         return applyFailure('stale', diagnosticCodes.initPlanStale, 'Workspace root identity changed before writing.', 'Retry init from the current workspace root; no files were written.');
     }
     try {
-        for (const [index, file] of bundle.plan.files.entries()) {
+        for (const index of replaceIndexes) {
+            const file = bundle.plan.files[index];
             const write = bundle.writes[index];
-            if (write === undefined) {
-                throw new Error(`Missing planned bytes for ${file.path}.`);
+            await options.beforeWrite?.(file.path, index);
+            const absolutePath = resolvePortableRelativePath(root, file.path);
+            const backupRef = backupPath(root, bundle.plan.planId, file.path);
+            const stateBoundary = await ensureStatePathBoundary(root, backupRef);
+            if (!stateBoundary.ok)
+                throw new Error(stateBoundary.message);
+            const beforeBytes = await readFile(absolutePath);
+            if (file.expectedBeforeDigest === null ||
+                sha256Digest(beforeBytes) !== file.expectedBeforeDigest) {
+                throw new Error(`Replacement target changed again: ${file.path}`);
             }
-            const target = await safeTarget(root, file.path);
-            if (target === null) {
-                throw new Error(`Unsafe target: ${file.path}`);
+            const observation = await observePath(absolutePath);
+            const mode = observation.stats === null ? 0o644 : observation.stats.mode & 0o777;
+            await mkdir(dirname(backupRef), { recursive: true });
+            await writeFile(backupRef, beforeBytes, { mode: 0o600, flag: 'wx' });
+            const temporary = `${absolutePath}.pappra-replace-${randomUUID().slice(0, 8)}`;
+            await writeFile(temporary, write.bytes, { mode });
+            await rename(temporary, absolutePath);
+            const after = await observePath(absolutePath);
+            if (after.kind !== 'file' || after.stats === null) {
+                throw new Error(`Replacement target is unreadable after writing: ${file.path}`);
             }
-            await options.beforeWrite?.(file.path, index);
-            await ensureDirectory(dirname(target.absolutePath));
-            const handle = await open(target.absolutePath, 'wx');
-            const record = {
+            replacements.push({
                 path: file.path,
-                digest: file.nextDigest,
-                dev: -1,
-                ino: -1,
-            };
-            created.push(record);
-            try {
-                const stats = await handle.stat();
-                record.dev = stats.dev;
-                record.ino = stats.ino;
-                await handle.writeFile(write.bytes);
+                absolutePath,
+                beforeBytes,
+                backupRef,
+                backupDigest: sha256Digest(beforeBytes),
+                afterDigest: file.nextDigest,
+                identity: { dev: after.stats.dev, ino: after.stats.ino },
+            });
+        }
+        if (replacements.length > 0) {
+            const manifestRead = await readWorkspaceManifest(root);
+            if (manifestRead.diagnostics.length > 0) {
+                throw new Error(manifestRead.diagnostics[0]?.message ??
+                    'Workspace install manifest is unreadable.');
             }
-            finally {
-                await handle.close().catch(() => undefined);
+            if (manifestRead.value === null) {
+                throw new Error('Workspace install manifest is missing; Pappra does not adopt an unowned replacement.');
             }
-            const written = await readFile(target.absolutePath);
-            if (sha256Digest(written) !== file.nextDigest) {
-                throw new Error(`Written digest mismatch for ${file.path}.`);
+            originalManifest = manifestRead.value;
+            const entries = [...manifestRead.value.entries];
+            const verifiedAt = new Date().toISOString();
+            for (const replacement of replacements) {
+                const entry = {
+                    path: replacement.path,
+                    installId: bundle.plan.planId,
+                    operation: 'replace-managed',
+                    beforeDigest: replacement.backupDigest,
+                    afterDigest: replacement.afterDigest,
+                    backupRef: replacement.backupRef,
+                    backupDigest: replacement.backupDigest,
+                    identity: replacement.identity,
+                    owner: 'pappra',
+                    verifiedAt,
+                };
+                const existingIndex = entries.findIndex((item) => item.path === replacement.path);
+                if (existingIndex === -1)
+                    entries.push(entry);
+                else
+                    entries[existingIndex] = entry;
             }
-            const recorded = await recordManagedFile(managed, file.path, file.nextDigest, {
-                dev: record.dev,
-                ino: record.ino,
+            const written = await writeWorkspaceManifest(root, {
+                ...manifestRead.value,
+                entries,
             });
-            if (!recorded.ok) {
-                throw new Error(recorded.diagnostics[0]?.message ?? `Cannot record ${file.path}.`);
-            }
+            if (!written.ok)
+                throw new Error(written.message);
         }
-        const completed = await completeManagedApply(managed);
-        if (!completed.ok) {
-            const residual = await cleanupCreatedFiles(root, created);
-            const failed = await failManagedApply(managed, 'Cannot finalize managed installation manifest.', residual);
-            return {
-                ok: false,
-                status: 'failed',
-                appliedFiles: [],
-                pendingExternalActions: [],
-                residualPaths: failed.residualPaths,
-                diagnostics: failed.diagnostics,
+        if (createIndexes.length > 0) {
+            const createPlan = {
+                ...bundle.plan,
+                files: createIndexes.map((index) => bundle.plan.files[index]),
             };
+            const createWrites = createIndexes.map((index) => bundle.writes[index]);
+            const managedStart = await beginManagedApply(root, createPlan, createWrites, bundle.rootIdentity);
+            if (!managedStart.ok) {
+                const status = managedStart.status === 'invalid'
+                    ? 'stale'
+                    : managedStart.status === 'locked'
+                        ? 'conflict'
+                        : 'failed';
+                await restoreReplacements();
+                return {
+                    ok: false,
+                    status,
+                    appliedFiles: [],
+                    pendingExternalActions: [],
+                    residualPaths: managedStart.residualPaths,
+                    diagnostics: managedStart.diagnostics,
+                };
+            }
+            managed = managedStart.context;
+            for (const index of createIndexes) {
+                const file = bundle.plan.files[index];
+                const write = bundle.writes[index];
+                const target = await safeTarget(root, file.path);
+                if (target === null) {
+                    throw new Error(`Unsafe target: ${file.path}`);
+                }
+                await options.beforeWrite?.(file.path, index);
+                await ensureDirectory(dirname(target.absolutePath));
+                const handle = await open(target.absolutePath, 'wx');
+                const record = {
+                    path: file.path,
+                    digest: file.nextDigest,
+                    dev: 0,
+                    ino: 0,
+                };
+                try {
+                    await handle.writeFile(write.bytes);
+                    await handle.sync();
+                    const stats = await handle.stat();
+                    record.dev = stats.dev;
+                    record.ino = stats.ino;
+                }
+                finally {
+                    await handle.close();
+                }
+                created.push(record);
+                const recorded = await recordManagedFile(managed, file.path, file.nextDigest, { dev: record.dev, ino: record.ino });
+                if (!recorded.ok) {
+                    throw new Error(recorded.diagnostics[0]?.message ?? `Cannot record ${file.path}.`);
+                }
+            }
+            const completed = await completeManagedApply(managed);
+            if (!completed.ok) {
+                const residual = await cleanupCreatedFiles(root, created);
+                const failed = await failManagedApply(managed, 'Cannot finalize managed installation manifest.', residual);
+                await restoreReplacements();
+                return {
+                    ok: false,
+                    status: 'failed',
+                    appliedFiles: [],
+                    pendingExternalActions: [],
+                    residualPaths: failed.residualPaths,
+                    diagnostics: failed.diagnostics,
+                };
+            }
         }
+        const appliedFiles = [
+            ...created.map((file) => file.path),
+            ...replacements.map((replacement) => replacement.path),
+        ];
         return {
             ok: true,
             status: bundle.plan.externalActions.length > 0
                 ? 'external-actions-pending'
-                : created.length === 0
+                : appliedFiles.length === 0
                     ? 'no-changes'
                     : 'applied',
-            appliedFiles: created.map((file) => file.path),
+            appliedFiles,
             pendingExternalActions: bundle.plan.externalActions,
-            residualPaths: completed.residualPaths,
-            diagnostics: completed.diagnostics,
+            residualPaths: [],
+            diagnostics: [],
         };
     }
     catch (error) {
+        await restoreReplacements();
         const residual = await cleanupCreatedFiles(root, created);
         for (const directory of createdDirectories.reverse()) {
             await rmdir(directory).catch(() => undefined);
@@ -1098,6 +1410,25 @@ export async function applyInitPlan(bundle, options = {}) {
         const residualNote = residual.length === 0
             ? 'No planned file from this attempt remains.'
             : `Residual planned files require manual inspection: ${residual.join(', ')}`;
+        if (managed === null) {
+            return {
+                ok: false,
+                status,
+                appliedFiles: [],
+                pendingExternalActions: [],
+                residualPaths: residual,
+                diagnostics: [
+                    createDiagnostic({
+                        code,
+                        severity: 'error',
+                        message: `${base}. ${residualNote}`,
+                        source: 'init apply',
+                        pointer: null,
+                        hint: 'Inspect the workspace state; backups from this attempt were restored when possible.',
+                    }),
+                ],
+            };
+        }
         const failed = await failManagedApply(managed, `${base}. ${residualNote}`, residual);
         return {
             ok: false,

package/dist/cli/commands/docs.d.ts

@@ -7,5 +7,6 @@ export interface DocsCommandOptions {
     readonly json: boolean;
     readonly includePrivate: boolean;
     readonly includeArchived: boolean;
+    readonly apply: boolean;
 }
 export declare function runDocsCommand(options: DocsCommandOptions, output: CliOutput): Promise<number>;