@phyzess/pappra 0.1.0-beta.13 → 0.1.0-beta.18

package/dist/hosts/integration/service.js

@@ -4,14 +4,19 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createDiagnostic } from '../../schemas/diagnostics.js';
 import { diagnosticCodes } from '../../schemas/errors.js';
-import { hostCapabilitiesSchema, hostInstallManifestSchema, hostIntegrationPlanSchema, hostIntegrationResultSchema, hostNameSchema, hostVerificationSchema, } from '../../schemas/host.js';
+import { hostCapabilitiesSchema, hostInstallManifestSchema, hostIntegrationPlanSchema, hostIntegrationResultSchema, hostNameSchema, hostVerificationSchema, hostUninstallResultSchema, } from '../../schemas/host.js';
 import { observePath, readFileBounded, sha256Digest } from '../../infra/fs.js';
+import { ensurePrivateState } from '../../infra/private-state.js';
+import { updateJsonProperty } from '../../infra/json-property.js';
+import { captureProcessIdentity } from '../../infra/process-identity.js';
+import { inspectPrivateLock, publishPrivateLock, reclaimDeadPrivateLock, } from '../../infra/private-lock.js';
 import { isPathInside } from '../../schemas/paths.js';
-import { ensureStatePathBoundary } from '../../install/ownership.js';
+import { ensureStatePathBoundary, removeOwnedFile, } from '../../install/ownership.js';
 import { getPackageInfo } from '../../package-info.js';
 import { detectPassiveHosts } from '../detect.js';
+import { observeHostVersion } from '../version.js';
 import { installPathForBundleFile, loadHostBundle } from './bundle.js';
-import { hostConfigRelativePath, renderHookConfigPatch } from './templates.js';
+import { hostConfigRelativePath, isManagedHookCommand, MIN_HOOK_TIMEOUT_SECONDS, renderHookConfigPatch, } from './templates.js';
 import { HOST_PLUGIN_HOOKS, HOST_SUPPORT, isSupportedVersion, nativeEventFor, surfaceFor, } from './support.js';
 const LIFECYCLE_EVENTS = [
     'startup',
@@ -199,22 +204,27 @@ function managedGroupHasUserEdits(group, commands) {
     const hookValues = group.hooks;
     if (!Array.isArray(hookValues))
         return false;
-    const hasManaged = hookValues.some((hook) => isExactManagedHook(hook, commands));
+    const hasManaged = hookValues.some((hook) => isManagedHook(hook, commands));
     if (!hasManaged)
         return false;
     const extraGroupKeys = Object.keys(group).filter((key) => key !== 'hooks');
     if (extraGroupKeys.length > 0)
         return true;
     return hookValues.some((hook) => {
-        if (!isExactManagedHook(hook, commands))
+        if (!isManagedHook(hook, commands))
             return false;
         const keys = Object.keys(hook);
+        const validTimeout = typeof hook.timeout === 'number' &&
+            Number.isSafeInteger(hook.timeout) &&
+            hook.timeout >= MIN_HOOK_TIMEOUT_SECONDS;
+        const legacyDefault = hook.timeout === 1 &&
+            typeof hook.command === 'string' &&
+            !commands.has(hook.command);
         return (keys.some((key) => key !== 'type' && key !== 'command' && key !== 'timeout') ||
-            !('timeout' in hook) ||
-            hook.timeout !== 1);
+            (!validTimeout && !legacyDefault));
     });
 }
-function isExactManagedHook(value, commands) {
+function isManagedHook(value, commands) {
     return (typeof value === 'object' &&
         value !== null &&
         !Array.isArray(value) &&
@@ -222,7 +232,7 @@ function isExactManagedHook(value, commands) {
         value.type === 'command' &&
         'command' in value &&
         typeof value.command === 'string' &&
-        commands.has(value.command));
+        isManagedHookCommand(value.command, commands));
 }
 function managedConfig(host, existing, hookExpression, path) {
     let base = {};
@@ -256,6 +266,7 @@ function managedConfig(host, existing, hookExpression, path) {
         const groups = current === undefined ? [] : current;
         const commands = managedHookCommands(entries);
         const preserved = [];
+        let managedTimeout = MIN_HOOK_TIMEOUT_SECONDS;
         for (const group of groups) {
             if (typeof group !== 'object' ||
                 group === null ||
@@ -268,27 +279,108 @@ function managedConfig(host, existing, hookExpression, path) {
             if (managedGroupHasUserEdits(group, commands)) {
                 return {
                     ok: false,
-                    diagnostic: diagnostic(diagnosticCodes.host_install_conflict, `Managed host hook entry was edited by the user: ${path}`, path, 'Review the edited matcher, timeout, or handler fields explicitly; Pappra preserves the edited group and does not reinstall it.'),
+                    diagnostic: diagnostic(diagnosticCodes.host_install_conflict, `Managed host hook entry was edited by the user: ${path}`, path, `Review the matcher and handler fields, and use an integer timeout of at least ${MIN_HOOK_TIMEOUT_SECONDS} seconds. Pappra preserves invalid or unsupported edits.`),
                 };
             }
-            const remaining = group.hooks.filter((hook) => !isExactManagedHook(hook, commands));
+            if (!group.hooks.some((hook) => isManagedHook(hook, commands))) {
+                preserved.push(group);
+                continue;
+            }
+            for (const hook of group.hooks) {
+                if (isManagedHook(hook, commands) &&
+                    typeof hook === 'object' &&
+                    hook !== null &&
+                    'timeout' in hook &&
+                    typeof hook.timeout === 'number') {
+                    managedTimeout = Math.max(managedTimeout, hook.timeout);
+                }
+            }
+            const remaining = group.hooks.filter((hook) => !isManagedHook(hook, commands));
             if (remaining.length > 0) {
                 preserved.push({ ...group, hooks: remaining });
             }
         }
-        nextHooks[event] = [...preserved, ...entries];
+        nextHooks[event] = [
+            ...preserved,
+            ...entries.map((entry) => ({
+                ...entry,
+                hooks: entry.hooks.map((hook) => ({
+                    ...hook,
+                    timeout: managedTimeout,
+                })),
+            })),
+        ];
     }
     const next = { ...base, hooks: nextHooks };
     return {
         ok: true,
-        bytes: Buffer.from(`${JSON.stringify(next, null, 2)}\n`),
+        bytes: updateJsonProperty(existing, 'hooks', next['hooks']),
+    };
+}
+function removeManagedConfig(host, existing, expression, file) {
+    const parsed = parseJsonObject(existing, file);
+    if (!parsed.ok)
+        return parsed;
+    const hooks = parsed.value['hooks'];
+    if (hooks === undefined)
+        return { ok: true, bytes: existing };
+    if (typeof hooks !== 'object' || hooks === null || Array.isArray(hooks))
+        return {
+            ok: false,
+            diagnostic: diagnostic(diagnosticCodes.host_config_invalid, 'Host hooks must be an object.', file, 'Inspect the configuration; no hook was removed.'),
+        };
+    const next = { ...hooks };
+    for (const [event, entries] of Object.entries(renderHookConfigPatch(host, expression).hooks)) {
+        const groups = next[event];
+        if (groups === undefined)
+            continue;
+        if (!Array.isArray(groups))
+            return {
+                ok: false,
+                diagnostic: diagnostic(diagnosticCodes.host_config_invalid, 'Host event hooks must be an array.', file, 'Inspect the configuration; no hook was removed.'),
+            };
+        const commands = managedHookCommands(entries);
+        const kept = [];
+        for (const value of groups) {
+            if (typeof value !== 'object' ||
+                value === null ||
+                Array.isArray(value) ||
+                !('hooks' in value) ||
+                !Array.isArray(value.hooks)) {
+                kept.push(value);
+                continue;
+            }
+            if (managedGroupHasUserEdits(value, commands))
+                return {
+                    ok: false,
+                    diagnostic: diagnostic(diagnosticCodes.host_install_conflict, 'An edited managed hook was preserved.', file, 'Review the edited hook explicitly before uninstalling its assets.'),
+                };
+            const remaining = value.hooks.filter((hook) => !isManagedHook(hook, commands));
+            if (remaining.length === value.hooks.length)
+                kept.push(value);
+            else if (remaining.length > 0)
+                kept.push({ ...value, hooks: remaining });
+        }
+        if (kept.length > 0)
+            next[event] = kept;
+        else
+            delete next[event];
+    }
+    return {
+        ok: true,
+        bytes: JSON.stringify(next) === JSON.stringify(hooks)
+            ? existing
+            : updateJsonProperty(existing, 'hooks', next),
     };
 }
 function validateManifestIdentity(manifest, host, hostRoot, configPath, hookExpression, migrate) {
+    const portable = host === 'pi' ||
+        (manifest.runtimeEntry === hookExpression &&
+            hookExpression.startsWith('${CLAUDE_PROJECT_DIR}/'));
     if (manifest.host !== host ||
-        resolve(manifest.hostRoot) !== hostRoot ||
+        (!portable && resolve(manifest.hostRoot) !== hostRoot) ||
         manifest.configPath !== configPath ||
-        (!migrate && manifest.runtimeEntry !== hookExpression)) {
+        (!migrate && host !== 'pi' && manifest.runtimeEntry !== hookExpression)) {
         return diagnostic(diagnosticCodes.host_install_conflict, `Host manifest identity does not match the selected target: ${hostRoot}`, join(hostRoot, BUNDLE_FILE), 'Inspect the manifest and target; Pappra does not adopt a foreign installation.');
     }
     const seen = new Set();
@@ -326,13 +418,20 @@ function configHasExpectedHooks(host, bytes, hookExpression, path) {
                 !Array.isArray(group.hooks)) {
                 continue;
             }
+            if (managedGroupHasUserEdits(group, commands))
+                return false;
             for (const hook of group.hooks) {
-                if (!isExactManagedHook(hook, commands))
+                if (!isManagedHook(hook, commands))
                     continue;
                 if (typeof hook === 'object' &&
                     hook !== null &&
                     'command' in hook &&
                     typeof hook.command === 'string') {
+                    // A stale runner or duplicate entry requires reinstalling, while
+                    // unrelated user configuration has no bearing on managed wiring.
+                    if (!commands.has(hook.command) || found.has(hook.command)) {
+                        return false;
+                    }
                     found.add(hook.command);
                 }
             }
@@ -651,6 +750,11 @@ async function writeAtomic(path, bytes, options) {
         await mkdir(dirname(path), { recursive: true, mode: 0o700 });
         const handle = await open(temporary, 'wx', 0o600);
         try {
+            if (options.replace) {
+                const before = await observePath(path);
+                if (before.kind === 'file' && before.stats)
+                    await handle.chmod(before.stats.mode & 0o777);
+            }
             const stats = await handle.stat();
             if (!stats.isFile())
                 throw new Error('temporary is not a regular file');
@@ -734,7 +838,77 @@ async function writeAtomic(path, bytes, options) {
         };
     }
 }
-async function acquireHostInstallLock(hostRoot) {
+/** CLI force is an explicit stop-all-host-writers assertion, not asset ownership. */
+async function quarantineUnknownHostLock(workspaceRoot, hostRoot) {
+    const file = join(hostRoot, '.pappra-host.lock');
+    if (await assertSafeTarget(hostRoot, file))
+        return null;
+    const owner = await inspectPrivateLock(file);
+    if (owner.state !== 'unknown')
+        return null;
+    const observed = await observePath(file);
+    const bytes = await readFileBounded(file, 64 * 1024);
+    if (observed.kind !== 'file' || !observed.stats || !bytes.ok)
+        return null;
+    const privateState = await ensurePrivateState(workspaceRoot);
+    if (!privateState.ok)
+        return null;
+    const directory = join(workspaceRoot, '.pappra', 'local', 'host-lock-archive');
+    const id = randomUUID();
+    const archive = join(directory, `${id}.lock`);
+    if (!(await ensureStatePathBoundary(workspaceRoot, archive)).ok)
+        return null;
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const saved = await writeAtomic(archive, bytes.value.bytes, {
+        replace: false,
+        beforeDigest: null,
+        root: directory,
+    });
+    if (!saved.ok)
+        return null;
+    const receiptFile = `${archive}.receipt.json`;
+    const receipt = Buffer.from(`${JSON.stringify({
+        schema: 'pappra/host-lock-quarantine/1',
+        source: file,
+        archive,
+        digest: bytes.value.digest,
+        identity: { dev: observed.stats.dev, ino: observed.stats.ino },
+        owner: 'unknown',
+        operator_assertion: { all_host_writers_stopped: true },
+        copy_fsynced_before_removal: true,
+        created_at: now(),
+    }, null, 2)}\n`);
+    if (!(await writeAtomic(receiptFile, receipt, {
+        replace: false,
+        beforeDigest: null,
+        root: directory,
+    })).ok)
+        return null;
+    const archiveDirectory = await open(directory, 'r');
+    try {
+        await archiveDirectory.sync();
+    }
+    finally {
+        await archiveDirectory.close();
+    }
+    const freshOwner = await inspectPrivateLock(file);
+    if (freshOwner.state !== 'unknown')
+        return null;
+    const removed = await removeOwnedFile(hostRoot, {
+        path: '.pappra-host.lock',
+        installId: id,
+        operation: 'create',
+        beforeDigest: null,
+        afterDigest: bytes.value.digest,
+        backupRef: null,
+        backupDigest: null,
+        identity: { dev: observed.stats.dev, ino: observed.stats.ino },
+        owner: 'pappra',
+        verifiedAt: now(),
+    });
+    return removed.ok ? archive : null;
+}
+async function acquireHostInstallLock(hostRoot, host) {
     const path = join(hostRoot, '.pappra-host.lock');
     const safe = await assertSafeTarget(hostRoot, path);
     if (safe !== null)
@@ -749,21 +923,36 @@ async function acquireHostInstallLock(hostRoot) {
         };
     }
     try {
-        const token = randomUUID();
         const rootReal = await realpath(hostRoot);
-        const handle = await open(path, 'wx', 0o600);
+        const token = `${JSON.stringify({ schema: 'pappra/host-install-lock/1', token: randomUUID(), pid: process.pid, process_identity: captureProcessIdentity() ?? undefined })}\n`;
+        const revalidate = async () => {
+            if ((await realpath(hostRoot)) !== rootReal ||
+                (await assertSafeTarget(hostRoot, path)) !== null)
+                throw new Error('Host lock namespace changed.');
+        };
         try {
-            const stats = await handle.stat();
-            await handle.writeFile(token);
-            await handle.sync();
-            return {
-                ok: true,
-                lock: { path, token, dev: stats.dev, ino: stats.ino, rootReal },
-            };
+            await publishPrivateLock(path, Buffer.from(token), revalidate);
         }
-        finally {
-            await handle.close().catch(() => undefined);
+        catch (error) {
+            if (error.code !== 'EEXIST' ||
+                (await inspectPrivateLock(path)).state !== 'dead')
+                throw error;
+            await reclaimDeadPrivateLock(path, revalidate);
+            await publishPrivateLock(path, Buffer.from(token), revalidate);
         }
+        const observed = await observePath(path);
+        if (observed.kind !== 'file' || !observed.stats)
+            throw new Error('Host lock identity unavailable.');
+        return {
+            ok: true,
+            lock: {
+                path,
+                token,
+                dev: observed.stats.dev,
+                ino: observed.stats.ino,
+                rootReal,
+            },
+        };
     }
     catch (error) {
         const code = typeof error === 'object' &&
@@ -776,7 +965,7 @@ async function acquireHostInstallLock(hostRoot) {
             ok: false,
             diagnostic: diagnostic(code === 'EEXIST'
                 ? diagnosticCodes.host_install_conflict
-                : diagnosticCodes.host_install_partial, `Cannot acquire host install lock ${path}: ${error instanceof Error ? error.message : String(error)}`, path, 'Inspect the lock; stale locks require explicit manual resolution.'),
+                : diagnosticCodes.host_install_partial, `Cannot acquire host install lock ${path}: ${error instanceof Error ? error.message : String(error)}`, path, `A live or unverified owner is preserved. Stop all writers for this host root, then use pappra host uninstall --host ${host} --host-root ${JSON.stringify(hostRoot)} --force --apply to quarantine an unknown legacy lock. Verified live owners are never overridden.`),
         };
     }
 }
@@ -819,6 +1008,7 @@ export class HostIntegrationService {
     #hostVersion;
     #selectedHosts;
     #observedAt;
+    #versionProbe;
     constructor(options) {
         this.#root = resolve(options.root);
         this.#homeDir = resolve(options.homeDir);
@@ -827,6 +1017,9 @@ export class HostIntegrationService {
         this.#hostVersion = options.hostVersion ?? null;
         this.#selectedHosts = options.selectedHosts ?? ['pi', 'codex', 'claude'];
         this.#observedAt = options.observedAt ?? now();
+        this.#versionProbe =
+            options.versionProbe ??
+                ((host) => observeHostVersion(host, this.#pathEnv));
     }
     detect() {
         const observations = detectPassiveHosts({
@@ -870,7 +1063,7 @@ export class HostIntegrationService {
     async plan(host, options = {}) {
         const hostRoot = resolve(options.hostRoot ?? join(this.#root, '.pappra', 'local', 'hosts', host));
         const hookSource = resolve(options.runtimeEntry ?? this.#runtimeEntry);
-        const version = options.hostVersion ?? this.#hostVersion;
+        const version = this.#versionProbe(host);
         if (!isSupportedVersion(host, version)) {
             throw new Error(`Host ${host} version ${version ?? '(unknown)'} is outside the pinned support matrix.`);
         }
@@ -910,7 +1103,7 @@ export class HostIntegrationService {
         try {
             const hostRoot = resolve(options.hostRoot ?? join(this.#root, '.pappra', 'local', 'hosts', host));
             const hookSource = resolve(options.runtimeEntry ?? this.#runtimeEntry);
-            const version = options.hostVersion ?? this.#hostVersion;
+            const version = this.#versionProbe(host);
             if (!isSupportedVersion(host, version)) {
                 return hostIntegrationResultSchema.parse({
                     schema: 'pappra/host-integration/1',
@@ -980,7 +1173,24 @@ export class HostIntegrationService {
         const applied = [];
         const residualPaths = [];
         const diagnostics = [];
-        const lockResult = await acquireHostInstallLock(plan.hostRoot);
+        if (isPathInside(join(this.#root, '.pappra', 'local'), plan.hostRoot)) {
+            const privateState = await ensurePrivateState(this.#root);
+            if (!privateState.ok) {
+                return hostIntegrationResultSchema.parse({
+                    schema: 'pappra/host-integration/1',
+                    ok: false,
+                    status: 'failed',
+                    plan,
+                    appliedFiles: [],
+                    residualPaths: [],
+                    diagnostics: [
+                        diagnostic(privateState.code, privateState.message, this.#root, privateState.nextAction ??
+                            'Protect private workspace state before installing the host.'),
+                    ],
+                });
+            }
+        }
+        const lockResult = await acquireHostInstallLock(plan.hostRoot, host);
         if (!lockResult.ok) {
             return hostIntegrationResultSchema.parse({
                 schema: 'pappra/host-integration/1',
@@ -1131,7 +1341,7 @@ export class HostIntegrationService {
     }
     async verify(host, options = {}) {
         const hostRoot = resolve(options.hostRoot ?? join(this.#root, '.pappra', 'local', 'hosts', host));
-        const version = options.hostVersion ?? this.#hostVersion;
+        const version = this.#versionProbe(host);
         const capabilities = this.describe(host);
         const checks = [];
         if (!isSupportedVersion(host, version)) {
@@ -1323,6 +1533,10 @@ export class HostIntegrationService {
         }
         let status = 'verified';
         for (const file of manifest.files) {
+            // Native settings are shared with the user. Their complete digest is a
+            // write-plan pin, not an ownership claim over unrelated configuration.
+            if (file.path === manifest.configPath)
+                continue;
             const path = join(hostRoot, ...file.path.split('/'));
             const digest = await fileDigest(path);
             if (digest !== file.digest) {
@@ -1345,13 +1559,12 @@ export class HostIntegrationService {
             const configPath = join(hostRoot, ...manifest.configPath.split('/'));
             const config = await readFileBounded(configPath, DEFAULT_MAX_CONFIG_BYTES);
             if (!config.ok ||
-                manifestFiles.get(manifest.configPath) !== config.value.digest ||
                 !configHasExpectedHooks(host === 'codex' ? 'codex' : 'claude', config.value.bytes, target.expression, configPath)) {
                 status = 'conflict';
                 checks.push({
                     id: 'host.config',
                     status: 'error',
-                    detail: 'Host config is missing, differs from its manifest digest, or lacks the exact expected Pappra entries.',
+                    detail: 'Host config is missing or its managed Pappra hook entries changed, are duplicated, or are incomplete.',
                 });
             }
             else {
@@ -1380,6 +1593,243 @@ export class HostIntegrationService {
             residualPaths: [],
         });
     }
+    async uninstall(host, options) {
+        const hostRoot = resolve(options.hostRoot ?? join(this.#root, '.pappra', 'local', 'hosts', host));
+        const plannedFiles = [];
+        const removedFiles = [];
+        const retainedPaths = [];
+        const quarantinedLocks = [];
+        const diagnostics = [];
+        const result = (status, ok) => {
+            if (!ok && diagnostics.length === 0)
+                diagnostics.push(diagnostic(diagnosticCodes.host_install_conflict, 'Host uninstall preserved edited, unsafe or unreadable content.', retainedPaths[0] ?? hostRoot, 'Inspect the reported preserved paths; no unknown user content is removed automatically.'));
+            return hostUninstallResultSchema.parse({
+                schema: 'pappra/host-uninstall/1',
+                host,
+                hostRoot,
+                ok,
+                status,
+                plannedFiles,
+                removedFiles,
+                retainedPaths: [...new Set(retainedPaths)],
+                quarantinedLocks,
+                diagnostics: diagnostics.slice(0, 32),
+            });
+        };
+        const manifestPath = join(hostRoot, BUNDLE_FILE);
+        const boundary = await assertSafeTarget(hostRoot, manifestPath);
+        if (boundary) {
+            diagnostics.push(boundary);
+            return result('conflict', false);
+        }
+        const lockPath = join(hostRoot, '.pappra-host.lock');
+        const lockOwner = await inspectPrivateLock(lockPath);
+        const lockFile = await observePath(lockPath);
+        if (lockOwner.state === 'alive' ||
+            (lockFile.kind !== 'missing' &&
+                lockOwner.state === 'unknown' &&
+                !options.force)) {
+            retainedPaths.push(lockPath);
+            diagnostics.push(diagnostic(diagnosticCodes.host_install_conflict, lockOwner.state === 'alive'
+                ? 'A verified live host writer holds this lock; --force cannot override it.'
+                : 'The host lock owner is unknown; it was preserved.', lockPath, `Stop all host writers, then use pappra host uninstall --host ${host} --host-root ${JSON.stringify(hostRoot)} --force --apply to archive an unknown lock. --force asserts all host writers are stopped and never permits deleting edited assets.`));
+            return result('conflict', false);
+        }
+        if (lockFile.kind !== 'missing' &&
+            lockOwner.state === 'unknown' &&
+            options.force) {
+            plannedFiles.push('.pappra-host.lock');
+            if (options.apply) {
+                const archived = await quarantineUnknownHostLock(this.#root, hostRoot).catch(() => null);
+                if (!archived) {
+                    retainedPaths.push(lockPath);
+                    return result('conflict', false);
+                }
+                quarantinedLocks.push(archived);
+                removedFiles.push('.pappra-host.lock');
+            }
+        }
+        const manifestRead = await readFileBounded(manifestPath, 256 * 1024);
+        if (!manifestRead.ok) {
+            if (manifestRead.code === diagnosticCodes.fileNotFound)
+                return result(removedFiles.length > 0
+                    ? 'removed'
+                    : plannedFiles.length > 0
+                        ? 'planned'
+                        : 'unchanged', true);
+            retainedPaths.push(manifestPath);
+            return result('conflict', false);
+        }
+        const manifest = await this.readManifest(hostRoot);
+        const expression = hookTarget(host, this.#root, hostRoot, this.#runtimeEntry).expression;
+        if (!manifest) {
+            retainedPaths.push(manifestPath);
+            return result('conflict', false);
+        }
+        const identity = validateManifestIdentity(manifest, host, hostRoot, hostConfigRelativePath(host), expression, false);
+        if (identity) {
+            diagnostics.push(identity);
+            return result('conflict', false);
+        }
+        let payload;
+        try {
+            payload = await loadHostBundle(host, getPackageInfo().version, {
+                hookExpression: expression,
+            });
+        }
+        catch {
+            retainedPaths.push(manifestPath);
+            return result('failed', false);
+        }
+        const allowed = new Set([...payload.contents.keys()].map((file) => installPathForBundleFile(host, file)));
+        const configRelative = hostConfigRelativePath(host);
+        let config = null;
+        if (host !== 'pi' && configRelative) {
+            const file = join(hostRoot, configRelative);
+            const unsafe = await assertSafeTarget(hostRoot, file);
+            if (unsafe) {
+                diagnostics.push(unsafe);
+                retainedPaths.push(file);
+                return result('conflict', false);
+            }
+            const read = await readFileBounded(file, DEFAULT_MAX_CONFIG_BYTES);
+            if (read.ok) {
+                const patch = removeManagedConfig(host, read.value.bytes, expression, file);
+                if (!patch.ok) {
+                    diagnostics.push(patch.diagnostic);
+                    retainedPaths.push(file);
+                    return result('conflict', false);
+                }
+                if (!patch.bytes.equals(read.value.bytes)) {
+                    plannedFiles.push(configRelative);
+                    config = {
+                        path: file,
+                        before: read.value.digest,
+                        bytes: patch.bytes,
+                    };
+                }
+            }
+            else if (read.code !== diagnosticCodes.fileNotFound) {
+                retainedPaths.push(file);
+                return result('conflict', false);
+            }
+        }
+        const candidates = [];
+        for (const entry of manifest.files) {
+            if (entry.path === configRelative)
+                continue;
+            const file = join(hostRoot, ...entry.path.split('/'));
+            if (!allowed.has(entry.path)) {
+                retainedPaths.push(file);
+                continue;
+            }
+            const unsafe = await assertSafeTarget(hostRoot, file);
+            if (unsafe) {
+                diagnostics.push(unsafe);
+                retainedPaths.push(file);
+                continue;
+            }
+            const read = await readFileBounded(file, 8 * 1024 * 1024);
+            if (!read.ok && read.code === diagnosticCodes.fileNotFound)
+                continue;
+            if (!read.ok || read.value.digest !== entry.digest) {
+                retainedPaths.push(file);
+                continue;
+            }
+            plannedFiles.push(entry.path);
+            candidates.push({ path: entry.path, digest: entry.digest });
+        }
+        if (host === 'pi' &&
+            retainedPaths.some((file) => isPathInside(join(hostRoot, 'extensions'), file))) {
+            // An edited entrypoint may still import its runtime companion.
+            for (let index = candidates.length - 1; index >= 0; index -= 1) {
+                const entry = candidates[index];
+                if (!entry.path.startsWith('extensions/'))
+                    continue;
+                retainedPaths.push(join(hostRoot, ...entry.path.split('/')));
+                plannedFiles.splice(plannedFiles.indexOf(entry.path), 1);
+                candidates.splice(index, 1);
+            }
+        }
+        if (retainedPaths.length === 0)
+            plannedFiles.push(BUNDLE_FILE);
+        if (!options.apply)
+            return result(retainedPaths.length ? 'partial' : 'planned', retainedPaths.length === 0);
+        const lock = await acquireHostInstallLock(hostRoot, host);
+        if (!lock.ok) {
+            diagnostics.push(lock.diagnostic);
+            return result('conflict', false);
+        }
+        let status = 'removed';
+        try {
+            const freshManifest = await readFileBounded(manifestPath, 256 * 1024);
+            if (!freshManifest.ok ||
+                freshManifest.value.digest !== manifestRead.value.digest) {
+                retainedPaths.push(manifestPath);
+                status = 'conflict';
+            }
+            else {
+                if (config) {
+                    const written = await writeAtomic(config.path, config.bytes, {
+                        replace: true,
+                        beforeDigest: config.before,
+                        root: hostRoot,
+                    });
+                    if (!written.ok) {
+                        diagnostics.push(written.diagnostic);
+                        retainedPaths.push(config.path);
+                        status = 'conflict';
+                    }
+                }
+                const remove = async (entry) => {
+                    const file = join(hostRoot, ...entry.path.split('/'));
+                    const observed = await observePath(file);
+                    if (observed.kind === 'missing')
+                        return;
+                    if (observed.kind !== 'file' || !observed.stats) {
+                        retainedPaths.push(file);
+                        return;
+                    }
+                    const removed = await removeOwnedFile(hostRoot, {
+                        path: entry.path,
+                        installId: randomUUID(),
+                        operation: 'create',
+                        beforeDigest: null,
+                        afterDigest: entry.digest,
+                        backupRef: null,
+                        backupDigest: null,
+                        identity: { dev: observed.stats.dev, ino: observed.stats.ino },
+                        owner: 'pappra',
+                        verifiedAt: now(),
+                    });
+                    if (removed.ok)
+                        removedFiles.push(entry.path);
+                    else
+                        retainedPaths.push(file);
+                };
+                if (status !== 'conflict') {
+                    for (const entry of candidates)
+                        await remove(entry);
+                    if (retainedPaths.length === 0)
+                        await remove({
+                            path: BUNDLE_FILE,
+                            digest: manifestRead.value.digest,
+                        });
+                }
+            }
+        }
+        catch {
+            status = 'failed';
+            retainedPaths.push(manifestPath);
+        }
+        finally {
+            if (!(await releaseHostInstallLock(lock.lock)))
+                retainedPaths.push(lock.lock.path);
+        }
+        if (status === 'removed' && retainedPaths.length > 0)
+            status = 'partial';
+        return result(status, status === 'removed');
+    }
     async readManifest(hostRoot) {
         const path = join(hostRoot, BUNDLE_FILE);
         const safe = await assertSafeTarget(hostRoot, path);