@dsh-enhanced/plugin-control-plane 0.1.32 → 0.1.34

package/lib/cli.js

@@ -1,30 +1,41 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { spawn } from 'node:child_process';
 import { constants as fsConstants, lstatSync } from 'node:fs';
-import { cp, lstat, mkdir, mkdtemp, open, readFile, realpath, rename, rm, stat } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { cp, lstat, mkdir, open, readFile, realpath, rename, rm, stat } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { Ed25519ApprovalAuthority, loadPrivateApprovalInput, parseApprovalReceipt } from './approval.js';
 import { Ed25519HostAttestationAuthority, parseHostAttestationReceipt } from './attestation.js';
 import { invokeConfiguredHostAttestor, prepareConfiguredHostAttestation, prepareManualHostAttestation } from './host-attestor.js';
+import { Ed25519ActivationRetractionAuthority, Ed25519PostActivationObservationAuthority, parseActivationRetraction, parsePostActivationObservation } from './post-activation.js';
 import { discover, loadCatalogWithMetadata, previewCatalogAdmission } from './catalog.js';
+import { fetchRegistryArtifact, RegistryFetchError } from './registry-fetch.js';
 import { verifyApprovedPackagesInLockfile } from './lockfile.js';
 import { Ed25519SourcePublishReconciliationAuthority, Ed25519SourceReleaseAuthority, Ed25519SourceReleaseAuthorizationAuthority, invokeSourcePublishReconciliationAdapter, invokeSourceReleaseAdapter, parseSourcePublishReconciliationReceipt, parseSourceReleaseAuthorization, parseSourceReleaseReceipt } from './release.js';
-import { ControlPlaneStore, expectedSourceRelease } from './store.js';
+import { ControlPlaneStore, controlPlaneDigest, expectedSourceRelease } from './store.js';
+import { ControlPlaneCliError } from './errors.js';
+import { ControlledProcessError, executeControlledProcess } from './adapter-process.js';
+import { changedSourcePaths, checkedSourceSnapshot, gcPreparedModifyWorktrees, runLocalCommand, sourcePathAllowed, verifyPreparedSourceWorktree } from './source-workspace.js';
 import { inheritedEnvironment, loadTrustConfig, openTrustedExecutable, resolveTrustKey, verifyOpenTrustedExecutable } from './trust.js';
 const pluginPattern = /^(?=.{1,64}$)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
 const leaseMs = 30_000;
 const pluginCatalogScope = 'plugins/README.md';
 const maximumActivationArtifactBytes = 268_435_456;
-export class ControlPlaneCliError extends Error {
-    code;
-    constructor(code, message) {
-        super(`plugin-control-plane[${code}]: ${message}`);
-        this.code = code;
-        this.name = 'ControlPlaneCliError';
-    }
+class ActivationCancelledError extends Error {
+    constructor() { super('plugin activation was cancelled'); this.name = 'ActivationCancelledError'; }
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw new ActivationCancelledError();
+}
+async function checked(signal, work) {
+    throwIfAborted(signal);
+    const value = await work();
+    throwIfAborted(signal);
+    return value;
 }
+// checkedSourceSnapshot stays importable from this module for the CLI test
+// suite; the implementation now lives in source-workspace.ts.
+export { checkedSourceSnapshot };
 function option(argv, name) {
     const index = argv.indexOf(name);
     const value = index === -1 ? undefined : argv[index + 1];
@@ -109,6 +120,59 @@ async function readSafeFile(path, maximum) {
     }
     return readFile(path, 'utf8');
 }
+const rollbackCoreFiles = ['package.json', 'pnpm-lock.yaml', 'cordis.patch.yml'];
+async function captureRollbackBaseline(plan) {
+    if (!plan.activation?.targetOriginallyExisted)
+        return [];
+    return Promise.all(rollbackCoreFiles.map(async (name) => {
+        const path = join(plan.target.profilePath, name);
+        let observed = false;
+        try {
+            const pathname = await lstat(path, { bigint: true });
+            observed = true;
+            const uid = process.getuid?.();
+            if (!pathname.isFile() || pathname.nlink !== 1n || pathname.size > 16n * 1024n * 1024n || (pathname.mode & 18n) !== 0n
+                || (uid !== undefined && pathname.uid !== 0n && pathname.uid !== BigInt(uid)) || await realpath(path) !== path) {
+                throw new ControlPlaneCliError('FILESYSTEM_STATE', 'rollback baseline file is unsafe');
+            }
+            const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
+            try {
+                const before = await handle.stat({ bigint: true });
+                if (!before.isFile() || before.dev !== pathname.dev || before.ino !== pathname.ino || before.size !== pathname.size
+                    || before.mtimeNs !== pathname.mtimeNs || before.ctimeNs !== pathname.ctimeNs) {
+                    throw new ControlPlaneCliError('FILESYSTEM_STATE', 'rollback baseline pathname changed');
+                }
+                const bytes = await handle.readFile();
+                const after = await handle.stat({ bigint: true });
+                const finalPath = await lstat(path, { bigint: true });
+                if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeNs !== after.mtimeNs
+                    || before.ctimeNs !== after.ctimeNs || BigInt(bytes.length) !== before.size || before.dev !== finalPath.dev
+                    || before.ino !== finalPath.ino || await realpath(path) !== path) {
+                    throw new ControlPlaneCliError('FILESYSTEM_STATE', 'rollback baseline file changed during read');
+                }
+                return { path, sha256: createHash('sha256').update(bytes).digest('hex') };
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            if (!observed && typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT')
+                return { path, sha256: null };
+            throw error;
+        }
+    }));
+}
+async function verifyRollbackBaseline(plan) {
+    const baseline = plan.activation?.targetBaselineFiles;
+    if (baseline === undefined || baseline.length !== (plan.activation?.targetOriginallyExisted ? 3 : 0)) {
+        throw new ControlPlaneCliError('FILESYSTEM_STATE', 'activation rollback baseline is missing');
+    }
+    const actual = await captureRollbackBaseline(plan);
+    if (JSON.stringify(actual) !== JSON.stringify(baseline)) {
+        throw new ControlPlaneCliError('FILESYSTEM_STATE', 'restored profile does not match its durable rollback baseline');
+    }
+}
 async function readOwnerPrivateFile(path, maximum) {
     const value = await lstat(path);
     const uid = process.getuid?.();
@@ -214,6 +278,34 @@ function assertPlanTrust(plan, trust) {
         throw new ControlPlaneCliError('ACTIVATION_BINDING', 'plan does not match the registered installation, ledger, target, and executor');
     }
 }
+const profilePattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u;
+// Mirrors the service-layer canonical target rule: the profiles directory and
+// the target profile must be one canonical non-symlinked directory tree under
+// the owner-bound DSH_HOME (a still-missing profile is accepted only when its
+// parent directory is itself canonical).
+async function canonicalProfileTarget(trust, profile) {
+    if (!profilePattern.test(profile) || profile.normalize('NFC').trim() !== profile) {
+        throw new ControlPlaneCliError('INVALID_ARGUMENT', 'profile must already be bounded canonical text');
+    }
+    const profiles = join(trust.dshHome, 'profiles');
+    if (await realpath(profiles) !== resolve(profiles))
+        throw new ControlPlaneCliError('FILESYSTEM_STATE', 'profiles directory is not canonical');
+    const profilePath = join(profiles, profile);
+    try {
+        const metadata = await lstat(profilePath);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink() || await realpath(profilePath) !== resolve(profilePath)) {
+            throw new ControlPlaneCliError('FILESYSTEM_STATE', 'target profile must be a canonical directory');
+        }
+    }
+    catch (error) {
+        if (!(typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+        if (await realpath(dirname(profilePath)) !== resolve(dirname(profilePath)) || basename(profilePath) !== profile) {
+            throw new ControlPlaneCliError('FILESYSTEM_STATE', 'missing target profile parent is not canonical');
+        }
+    }
+    return Object.freeze({ dshHome: trust.dshHome, profile, profilePath });
+}
 async function openCurrentTrustedExecutable(path, trustedRunningNode) {
     const canonical = await realpath(path);
     const metadata = await lstat(canonical);
@@ -288,16 +380,25 @@ async function executorInterpreter(executable) {
 }
 async function runBounded(input) {
     const execute = async () => {
-        const ownedExecutable = input.plan === undefined || input.pinnedExecutable !== undefined ? undefined
-            : await openTrustedExecutable(input.executable, input.plan.executor.sha256);
-        const executable = input.pinnedExecutable ?? ownedExecutable;
+        const activationPlan = input.plan;
+        let ownedExecutable;
+        let executable;
         let interpreter = input.pinnedInterpreter;
         let result = '';
         let failure;
         try {
-            if (executable !== undefined && interpreter === undefined)
+            throwIfAborted(input.signal);
+            if (activationPlan !== undefined && input.pinnedExecutable === undefined) {
+                ownedExecutable = await openTrustedExecutable(input.executable, activationPlan.executor.sha256);
+                throwIfAborted(input.signal);
+            }
+            executable = input.pinnedExecutable ?? ownedExecutable;
+            if (executable !== undefined && interpreter === undefined) {
                 interpreter = await executorInterpreter(executable);
-            result = await new Promise((resolvePromise, reject) => {
+                throwIfAborted(input.signal);
+            }
+            throwIfAborted(input.signal);
+            result = await executeControlledProcess((() => {
                 let command = input.executable;
                 let stdio = ['ignore', 'pipe', 'ignore'];
                 if (executable !== undefined) {
@@ -316,36 +417,11 @@ async function runBounded(input) {
                 if (executable !== undefined && interpreter !== undefined) {
                     commandArguments = [...interpreter.arguments, `/proc/self/fd/${3}`, ...commandArguments];
                 }
-                const child = spawn(command, commandArguments, { cwd: input.cwd, env: input.environment, stdio, shell: false });
-                const chunks = [];
-                let bytes = 0;
-                let outputLimit = false;
-                let timedOut = false;
-                child.stdout.on('data', (chunk) => {
-                    if (!input.capture)
-                        return;
-                    bytes += chunk.length;
-                    if (bytes > (input.maximumOutput ?? 65_536)) {
-                        outputLimit = true;
-                        child.kill('SIGKILL');
-                    }
-                    else
-                        chunks.push(chunk);
-                });
-                const timeout = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, 60_000);
-                child.once('error', () => { clearTimeout(timeout); reject(new ControlPlaneCliError('EXECUTOR_FAILED', 'registered executor could not start')); });
-                child.once('close', code => {
-                    clearTimeout(timeout);
-                    if (timedOut)
-                        reject(new ControlPlaneCliError('EXECUTOR_TIMEOUT', 'registered executor exceeded its deadline'));
-                    else if (outputLimit)
-                        reject(new ControlPlaneCliError('EXECUTOR_OUTPUT_LIMIT', 'registered executor exceeded its output bound'));
-                    else if (code !== 0)
-                        reject(new ControlPlaneCliError('EXECUTOR_FAILED', 'registered executor returned a non-zero status'));
-                    else
-                        resolvePromise(input.capture ? Buffer.concat(chunks).toString('utf8') : '');
-                });
-            });
+                return { command, args: commandArguments, env: input.environment, stdio,
+                    stdin: '', timeoutMs: 60_000, maximumOutput: input.maximumOutput ?? 65_536,
+                    ...(input.signal === undefined ? {} : { signal: input.signal }) };
+            })());
+            throwIfAborted(input.signal);
         }
         catch (error) {
             failure = error;
@@ -364,9 +440,20 @@ async function runBounded(input) {
                 await interpreter.executable.handle.close();
             await ownedExecutable?.handle.close();
         }
+        throwIfAborted(input.signal);
+        if (failure instanceof ControlledProcessError) {
+            if (failure.code === 'ABORTED')
+                throw new ActivationCancelledError();
+            if (failure.code === 'TIMEOUT')
+                throw new ControlPlaneCliError('EXECUTOR_TIMEOUT', 'registered executor exceeded its deadline');
+            if (failure.code === 'OUTPUT_LIMIT')
+                throw new ControlPlaneCliError('EXECUTOR_OUTPUT_LIMIT', 'registered executor exceeded its output bound');
+            throw new ControlPlaneCliError('EXECUTOR_FAILED', failure.code === 'NON_ZERO'
+                ? 'registered executor returned a non-zero status' : 'registered executor could not start or be safely reclaimed');
+        }
         if (failure !== undefined)
             throw failure;
-        return result;
+        return input.capture ? result : '';
     };
     return input.store !== undefined && input.plan !== undefined
         ? input.store.withActivationFileSystemGuard({ planId: input.plan.id, expectedRevision: input.plan.revision,
@@ -482,6 +569,14 @@ async function snapshotLocalArtifact(plan, item) {
     const integrity = `sha512-${createHash('sha512').update(bytes).digest('base64')}`;
     if (integrity !== item.integrity)
         throw new ControlPlaneCliError('ACTIVATION_BINDING', 'local artifact bytes do not match the approved integrity');
+    return await pinActivationArtifactBytes(plan, item, registry, bytes);
+}
+// Shared terminus for both artifact source paths (a local file URL and a
+// downloaded registry object): the approved bytes are materialized into an
+// owner-private 0400 cache, then reopened through a pinned file descriptor so
+// the package manager only ever reads /proc/self/fd/N while the control plane
+// re-verifies the bytes after the executor returns.
+async function pinActivationArtifactBytes(plan, item, registry, bytes) {
     const cacheRoot = join(plan.target.dshHome, 'plugin-control', 'activation-artifacts');
     await mkdir(cacheRoot, { recursive: true, mode: 0o700 });
     await assertDirectory(cacheRoot);
@@ -554,12 +649,48 @@ async function snapshotLocalArtifact(plan, item) {
         throw error;
     }
 }
-async function activationPackages(plan) {
+// Remote counterpart of snapshotLocalArtifact. The catalog-approved package
+// is fetched from the single owner-bound release registry over pinned TLS,
+// authorized with a bearer token read from the owner process (never from the
+// trust file or the executor allowlist), and accepted solely on equality with
+// the catalog-approved sha512 integrity. The verified bytes then take the
+// identical 0400-cache + file-descriptor path as a local artifact.
+async function downloadRegistryArtifact(trust, plan, item) {
+    const registry = item.registry;
+    if (registry === undefined)
+        throw new ControlPlaneCliError('ACTIVATION_BINDING', 'package registry binding is missing');
+    const bound = trust.releaseRegistry;
+    if (bound === undefined || bound.id !== registry.id || bound.locator !== registry.locator) {
+        throw new ControlPlaneCliError('ACTIVATION_BINDING', 'package registry is not the owner-bound release registry');
+    }
+    let bytes;
+    try {
+        const fetched = await fetchRegistryArtifact({ registry: bound, packageName: item.package, version: item.version, expectedIntegrity: item.integrity }, process.env);
+        bytes = fetched.bytes;
+        if (registry.reference.startsWith('https:') && fetched.reference !== registry.reference) {
+            throw new ControlPlaneCliError('ACTIVATION_BINDING', 'remote artifact reference does not match the approved exact HTTPS reference');
+        }
+    }
+    catch (error) {
+        if (error instanceof ControlPlaneCliError)
+            throw error;
+        if (error instanceof RegistryFetchError)
+            throw new ControlPlaneCliError('ACTIVATION_BINDING', error.message);
+        throw error;
+    }
+    const integrity = `sha512-${createHash('sha512').update(bytes).digest('base64')}`;
+    if (integrity !== item.integrity)
+        throw new ControlPlaneCliError('ACTIVATION_BINDING', 'remote artifact bytes do not match the approved integrity');
+    return await pinActivationArtifactBytes(plan, item, registry, bytes);
+}
+async function activationPackages(trust, plan) {
     const snapshots = [];
     try {
         for (const item of exactPackages(plan)) {
             if (localArtifactReference(item) !== undefined)
                 snapshots.push(await snapshotLocalArtifact(plan, item));
+            else if (item.registry !== undefined)
+                snapshots.push(await downloadRegistryArtifact(trust, plan, item));
         }
         const byPackage = new Map(snapshots.map(snapshot => [snapshot.package.package, snapshot]));
         return { packages: exactPackages(plan).map(item => byPackage.get(item.package)?.package ?? item), snapshots };
@@ -641,12 +772,155 @@ function advance(store, plan, to, failureCode) {
 }
 async function finishRollback(store, plan, lock) {
     const activationPaths = paths(plan);
-    await restoreTarget(store, plan, activationPaths.backupPath);
-    await fencedMutation(store, plan, () => rm(activationPaths.stagePath, { recursive: true, force: true }));
-    const terminal = advance(store, plan, 'rolled-back');
+    const observed = plan.activation?.failureCode?.startsWith('post-activation-') === true;
+    if (observed) {
+        await restoreObservedTarget(store, plan);
+    }
+    else
+        await restoreTarget(store, plan, activationPaths.backupPath);
+    await fencedMutation(store, plan, () => verifyRollbackBaseline(plan));
+    if (!observed)
+        await fencedMutation(store, plan, () => rm(activationPaths.stagePath, { recursive: true, force: true }));
+    const terminal = plan.activation?.hostRecoveryRequired
+        ? store.markRollbackProfileRestored({ planId: plan.id, expectedRevision: plan.revision, fence: plan.activation.fence })
+        : advance(store, plan, 'rolled-back');
+    if (observed)
+        await cleanupRestoredStage(store, terminal);
     await releaseProfileLock(store, lock);
     return terminal;
 }
+async function profileFilesAt(plan, path) {
+    await assertDirectory(path);
+    const files = await captureRollbackBaseline({ ...plan, target: { ...plan.target, profilePath: path },
+        activation: { ...plan.activation, targetOriginallyExisted: true } });
+    return files.map((file, index) => ({ path: join(plan.target.profilePath, rollbackCoreFiles[index]), sha256: file.sha256 }));
+}
+/** A closed quality watch may restore only the exact deployment it observed. */
+async function restoreObservedTarget(store, plan) {
+    const { backupPath, stagePath } = paths(plan);
+    await fencedMutation(store, plan, async () => {
+        const installed = store.getActivationInstalledBaseline(plan.id);
+        const baseline = plan.activation?.targetBaselineFiles;
+        if (installed === undefined || baseline === undefined) {
+            throw new ControlPlaneCliError('FILESYSTEM_STATE', 'post-activation rollback checkpoints are unavailable');
+        }
+        const matches = async (path, expected) => {
+            if (JSON.stringify(await profileFilesAt(plan, path)) !== JSON.stringify(expected)) {
+                throw new ControlPlaneCliError('FILESYSTEM_STATE', 'post-activation profile files changed; rollback requires reconciliation');
+            }
+        };
+        const backupExists = await directoryExists(backupPath);
+        const targetExists = await directoryExists(plan.target.profilePath);
+        const staged = await directoryExists(stagePath);
+        // The old target is moved aside before its replacement. A crash between
+        // either rename can resume without deleting an unverified profile.
+        if (plan.activation.targetOriginallyExisted) {
+            if (!backupExists) {
+                if (!targetExists || !staged)
+                    throw new ControlPlaneCliError('FILESYSTEM_STATE', 'retained rollback backup is missing');
+                await matches(plan.target.profilePath, baseline);
+                if (staged)
+                    await matches(stagePath, installed);
+                await syncDirectory(join(plan.target.dshHome, 'profiles'));
+                return;
+            }
+            await matches(backupPath, baseline);
+        }
+        else if (backupExists)
+            throw new ControlPlaneCliError('FILESYSTEM_STATE', 'unexpected rollback backup for an absent baseline');
+        if (staged)
+            await matches(stagePath, installed);
+        if (targetExists) {
+            await matches(plan.target.profilePath, installed);
+            if (staged)
+                throw new ControlPlaneCliError('FILESYSTEM_STATE', 'both rollback target and staged candidate exist');
+            await rename(plan.target.profilePath, stagePath);
+        }
+        else if (!staged) {
+            throw new ControlPlaneCliError('FILESYSTEM_STATE', 'observed deployment and recovery stage are both missing');
+        }
+        if (plan.activation.targetOriginallyExisted)
+            await rename(backupPath, plan.target.profilePath);
+        await syncDirectory(join(plan.target.dshHome, 'profiles'));
+    });
+}
+async function cleanupRestoredStage(store, plan) {
+    await store.withExclusiveWrite(async () => {
+        store.assertNoClaimedHostAttestation(plan.id);
+        const current = store.getPlan(plan.id);
+        if (!current.activation?.rollbackProfileRestored || current.activation.fence !== plan.activation?.fence) {
+            throw new ControlPlaneCliError('FILESYSTEM_STATE', 'rollback restoration marker changed before stage cleanup');
+        }
+        const { stagePath } = paths(current);
+        if (!await directoryExists(stagePath))
+            return;
+        const installed = store.getActivationInstalledBaseline(current.id);
+        if (installed === undefined || JSON.stringify(await profileFilesAt(current, stagePath)) !== JSON.stringify(installed)) {
+            throw new ControlPlaneCliError('FILESYSTEM_STATE', 'restored rollback stage changed; cleanup requires reconciliation');
+        }
+        await rm(stagePath, { recursive: true, force: true });
+    });
+}
+async function cleanupRetiredBackups(store, plan) {
+    await store.withExclusiveWrite(async () => {
+        for (const retired of store.listRetiredActivationBackups(plan.id)) {
+            const { backupPath } = paths(retired);
+            if (await directoryExists(backupPath))
+                await rm(backupPath, { recursive: true, force: true });
+        }
+    });
+}
+async function finishCommit(store, plan) {
+    const baselineFiles = await fencedMutation(store, plan, () => profileFilesAt(plan, plan.target.profilePath));
+    store.recordActivationInstalledBaseline({ planId: plan.id, expectedRevision: plan.revision, fence: plan.activation.fence, baselineFiles });
+    await fencedMutation(store, plan, () => rm(paths(plan).stagePath, { recursive: true, force: true }));
+    const committed = advance(store, plan, 'activated');
+    await cleanupRetiredBackups(store, committed);
+    return committed;
+}
+/**
+ * Complete physical recovery after a closed post-activation watch. The caller
+ * owns the Store lifetime. Once recovery has claimed the activation, rollback
+ * deliberately drains its filesystem work even when the caller is cancelled;
+ * cancellation only interrupts the configured attestor subprocess.
+ */
+export async function rollbackPluginWatch(input) {
+    const { store, trust, planId, signal } = input;
+    throwIfAborted(signal);
+    let plan = store.getPlan(planId);
+    assertPlanTrust(plan, trust);
+    plan = store.beginPostActivationRollback({ planId, expectedRevision: plan.revision });
+    if (plan.activation?.rollbackProfileRestored)
+        await cleanupRestoredStage(store, plan);
+    if (plan.status === 'rolled-back')
+        return plan;
+    if (!plan.activation?.rollbackProfileRestored) {
+        plan = await store.claimActivation({ planId, expectedRevision: plan.revision, leaseMs,
+            resolveApprovalAuthority: receipt => activationClaimAuthority(trust, plan, receipt) });
+        let lock = await acquireProfileLock(store, plan);
+        try {
+            plan = await finishRollback(store, plan, lock);
+            lock = undefined;
+        }
+        finally {
+            if (lock !== undefined)
+                await releaseProfileLock(store, lock);
+        }
+    }
+    if (trust.hostAttestor === undefined)
+        return plan;
+    throwIfAborted(signal);
+    const operation = prepareConfiguredHostAttestation(store, plan, trust);
+    const resolveAuthority = (receipt) => {
+        const key = resolveTrustKey(trust, 'host-attestation', receipt.authority, receipt.keyId);
+        return new Ed25519HostAttestationAuthority(key.publicKeyPem, key.authority, key.keyId);
+    };
+    const receipt = await store.runHostAttestationOperation({ operationId: operation.operationId,
+        expectedRevision: plan.revision, expectedFence: plan.activation.fence,
+        execute: request => invokeConfiguredHostAttestor(trust, request, signal), resolveAuthority });
+    return (await store.applyHostAttestation({ planId, expectedRevision: plan.revision, expectedFence: plan.activation.fence,
+        receipt, idempotencyKey: `host-attestation:${operation.operationId}`, resolveAuthority })).result;
+}
 async function approve(argv) {
     if (argv.includes('--approved-by')) {
         throw new ControlPlaneCliError('INVALID_ARGUMENT', 'approval trust roots cannot be supplied by the approving command');
@@ -669,89 +943,119 @@ async function approve(argv) {
 }
 function activationApprovalAuthority(trust, receipt) {
     const key = resolveTrustKey(trust, 'approval', receipt.authority, receipt.keyId);
+    return new Ed25519ApprovalAuthority(key.publicKeyPem, key.authority, key.keyId);
+}
+function recoveryActivationApprovalAuthority(trust, receipt) {
+    const key = resolveTrustKey(trust, 'approval', receipt.authority, receipt.keyId);
+    // A rollback is physical recovery for a previously admitted activation. It
+    // verifies the original bounded receipt at its decision time and does not
+    // authorize a new forward deployment after that receipt has expired.
     return new Ed25519ApprovalAuthority(key.publicKeyPem, key.authority, key.keyId, () => receipt.decidedAt);
 }
-async function activate(argv) {
-    const trust = await commandTrust(argv);
-    const store = new ControlPlaneStore({ path: trust.ledger.path });
+function activationClaimAuthority(trust, plan, receipt) {
+    return plan.status === 'rollback-pending'
+        ? recoveryActivationApprovalAuthority(trust, receipt)
+        : activationApprovalAuthority(trust, receipt);
+}
+export async function activatePluginPlan(input) {
+    const { store, trust, planId, expectedRevision, signal } = input;
     let lock;
     try {
-        let plan = store.getPlan(option(argv, '--plan-id'));
+        throwIfAborted(signal);
+        let plan = store.getPlan(planId);
         assertPlanTrust(plan, trust);
         if (plan.status === 'activated') {
-            process.stdout.write(`${JSON.stringify(plan)}\n`);
-            return;
+            await checked(signal, () => cleanupRetiredBackups(store, plan));
+            return plan;
+        }
+        if (plan.status === 'rollback-pending' && plan.activation?.rollbackProfileRestored) {
+            if (plan.revision !== expectedRevision)
+                throw new ControlPlaneCliError('ACTIVATION_BINDING', 'activation targets a stale revision');
+            return plan;
         }
-        plan = await store.claimActivation({ planId: plan.id, expectedRevision: integerOption(argv, '--expected-revision'), leaseMs,
-            resolveApprovalAuthority: receipt => activationApprovalAuthority(trust, receipt) });
+        // Claim and lock form one durable recovery boundary.  Do not let an abort
+        // between their awaits escape before the staging try/catch owns rollback.
+        plan = await store.claimActivation({ planId: plan.id, expectedRevision, leaseMs,
+            resolveApprovalAuthority: receipt => activationClaimAuthority(trust, plan, receipt) });
         lock = await acquireProfileLock(store, plan);
         const activationPaths = paths(plan);
         if (plan.status === 'rollback-pending') {
-            process.stdout.write(`${JSON.stringify(await finishRollback(store, plan, lock))}\n`);
+            const output = await finishRollback(store, plan, lock);
             lock = undefined;
-            return;
+            return output;
         }
         if (plan.status === 'commit-pending') {
-            await fencedMutation(store, plan, () => rm(activationPaths.backupPath, { recursive: true, force: true }));
-            await fencedMutation(store, plan, () => rm(activationPaths.stagePath, { recursive: true, force: true }));
-            process.stdout.write(`${JSON.stringify(advance(store, plan, 'activated'))}\n`);
-            return;
+            return await finishCommit(store, plan);
         }
         if (plan.status !== 'staging')
             throw new ControlPlaneCliError('HOST_ATTESTATION_REQUIRED', 'activation is awaiting a signed Host attestation');
-        await assertDirectory(trust.dshHome);
-        await assertDirectory(join(trust.dshHome, 'profiles'));
-        await assertDirectory(plan.target.profilePath, true);
-        const environment = inheritedEnvironment(trust);
         try {
+            await checked(signal, () => assertDirectory(trust.dshHome));
+            await checked(signal, () => assertDirectory(join(trust.dshHome, 'profiles')));
+            await checked(signal, () => assertDirectory(plan.target.profilePath, true));
+            const environment = inheritedEnvironment(trust);
             if (plan.activation?.targetOriginallyExisted === undefined) {
-                if (await directoryExists(activationPaths.backupPath) || await directoryExists(activationPaths.stagePath)) {
+                if (await checked(signal, () => directoryExists(activationPaths.backupPath)) || await checked(signal, () => directoryExists(activationPaths.stagePath))) {
                     throw new ControlPlaneCliError('FILESYSTEM_STATE', 'unbound activation residue requires owner recovery');
                 }
+                const existed = await checked(signal, () => directoryExists(plan.target.profilePath));
+                const baselineFiles = existed ? await checked(signal, () => fencedMutation(store, plan, () => captureRollbackBaseline({ ...plan, activation: { ...plan.activation, targetOriginallyExisted: true } }))) : [];
                 plan = store.recordActivationTargetBaseline({ planId: plan.id, expectedRevision: plan.revision,
-                    fence: plan.activation.fence, existed: await directoryExists(plan.target.profilePath) });
+                    fence: plan.activation.fence, existed, baselineFiles });
             }
-            await restoreTarget(store, plan, activationPaths.backupPath);
-            await fencedMutation(store, plan, () => rm(activationPaths.stagePath, { recursive: true, force: true }));
+            await checked(signal, () => restoreTarget(store, plan, activationPaths.backupPath));
+            await checked(signal, () => fencedMutation(store, plan, () => rm(activationPaths.stagePath, { recursive: true, force: true })));
             if (plan.activation.targetOriginallyExisted) {
-                await stat(plan.target.profilePath);
-                await fencedMutation(store, plan, () => cp(plan.target.profilePath, activationPaths.stagePath, { recursive: true, force: false, errorOnExist: true }));
+                await checked(signal, () => stat(plan.target.profilePath));
+                await checked(signal, () => fencedMutation(store, plan, () => cp(plan.target.profilePath, activationPaths.stagePath, { recursive: true, force: false, errorOnExist: true })));
             }
-            const activationArtifacts = await fencedMutation(store, plan, () => activationPackages(plan));
+            let activationArtifacts;
             let pinnedExecutor;
             let pinnedInterpreter;
             try {
+                // Retain newly opened artifact descriptors before the post-await abort
+                // check so this disposer owns them on cancellation.
+                throwIfAborted(signal);
+                await fencedMutation(store, plan, async () => { activationArtifacts = await activationPackages(trust, plan); });
+                throwIfAborted(signal);
+                throwIfAborted(signal);
                 pinnedExecutor = await openTrustedExecutable(trust.executor.path, plan.executor.sha256);
+                throwIfAborted(signal);
                 pinnedInterpreter = await executorInterpreter(pinnedExecutor);
+                throwIfAborted(signal);
                 const executor = { pinnedExecutable: pinnedExecutor, pinnedInterpreter };
-                const version = (await runBounded({ executable: trust.executor.path, args: ['--version'], environment, store, plan, capture: true, ...executor })).trim();
+                const version = (await runBounded({ executable: trust.executor.path, args: ['--version'], environment, store, plan, capture: true, signal, ...executor })).trim();
                 if (version !== plan.candidate.dshBaseline)
                     throw new ControlPlaneCliError('ACTIVATION_BINDING', 'registered executor baseline differs from the approved dossier');
                 await runBounded({ executable: trust.executor.path, args: ['plugin', '--profile', activationPaths.stageProfile, 'add',
-                        ...activationArtifacts.packages.map(installSpec)], environment, store, plan, ...executor });
-                await Promise.all(activationArtifacts.snapshots.map(verifyActivationArtifactSnapshot));
-                const lockfileSource = await readSafeFile(join(activationPaths.stagePath, 'pnpm-lock.yaml'), 8 * 1024 * 1024);
+                        ...activationArtifacts.packages.map(installSpec)], environment, store, plan, signal, ...executor });
+                await checked(signal, () => Promise.all(activationArtifacts.snapshots.map(verifyActivationArtifactSnapshot)));
+                const lockfileSource = await checked(signal, () => readSafeFile(join(activationPaths.stagePath, 'pnpm-lock.yaml'), 8 * 1024 * 1024));
                 verifyApprovedPackagesInLockfile(lockfileSource, activationArtifacts.packages, activationPaths.stagePath);
-                await verifyInstalledPackages(activationPaths.stagePath, activationArtifacts.packages);
+                await checked(signal, () => verifyInstalledPackages(activationPaths.stagePath, activationArtifacts.packages));
                 // Configuration materialization is a staging integrity check only. It is
                 // deliberately not called readiness, reload, shadow, canary or health.
                 await runBounded({ executable: trust.executor.path, args: ['--profile', activationPaths.stageProfile, '--dump-config'],
-                    environment, store, plan, ...executor });
+                    environment, store, plan, signal, ...executor });
             }
             finally {
-                await closeActivationArtifactSnapshots(activationArtifacts.snapshots);
+                if (activationArtifacts !== undefined)
+                    await closeActivationArtifactSnapshots(activationArtifacts.snapshots);
                 if (pinnedInterpreter !== undefined)
                     await pinnedInterpreter.executable.handle.close();
                 await pinnedExecutor?.handle.close();
             }
+            plan = store.markActivationHostExposure({ planId: plan.id, expectedRevision: plan.revision, fence: plan.activation.fence });
+            throwIfAborted(signal);
             if (plan.activation.targetOriginallyExisted)
-                await fencedMutation(store, plan, () => rename(plan.target.profilePath, activationPaths.backupPath));
-            await fencedMutation(store, plan, () => rename(activationPaths.stagePath, plan.target.profilePath));
+                await checked(signal, () => fencedMutation(store, plan, () => rename(plan.target.profilePath, activationPaths.backupPath)));
+            await checked(signal, () => fencedMutation(store, plan, () => rename(activationPaths.stagePath, plan.target.profilePath)));
             plan = advance(store, plan, 'awaiting-reload');
-            process.stdout.write(`${JSON.stringify(plan)}\n`);
+            return plan;
         }
         catch (error) {
-            plan = advance(store, plan, 'rollback-pending', error instanceof ControlPlaneCliError ? error.code.toLowerCase().replaceAll('_', '-') : 'activation-failed');
+            plan = advance(store, plan, 'rollback-pending', error instanceof ActivationCancelledError ? 'activation-cancelled'
+                : error instanceof ControlPlaneCliError ? error.code.toLowerCase().replaceAll('_', '-') : 'activation-failed');
             await finishRollback(store, plan, lock);
             lock = undefined;
             throw error;
@@ -760,6 +1064,16 @@ async function activate(argv) {
     finally {
         if (lock !== undefined)
             await releaseProfileLock(store, lock);
+    }
+}
+async function activate(argv) {
+    const trust = await commandTrust(argv);
+    const store = new ControlPlaneStore({ path: trust.ledger.path });
+    try {
+        const result = await activatePluginPlan({ store, trust, planId: option(argv, '--plan-id'), expectedRevision: integerOption(argv, '--expected-revision') });
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+    }
+    finally {
         store.close();
     }
 }
@@ -774,29 +1088,29 @@ async function attest(argv) {
         const expectedFence = integerOption(argv, '--expected-fence');
         const initial = store.getPlan(planId);
         assertPlanTrust(initial, trust);
+        if (receipt.planId !== planId || receipt.planDigest !== initial.digest) {
+            throw new ControlPlaneCliError('ACTIVATION_BINDING', 'Host receipt does not target the requested activation plan');
+        }
         const resolveAuthority = (value) => {
             const key = resolveTrustKey(trust, 'host-attestation', value.authority, value.keyId);
             return new Ed25519HostAttestationAuthority(key.publicKeyPem, key.authority, key.keyId);
         };
-        await store.runHostAttestationOperation({ operationId: receipt.operationId, expectedRevision, expectedFence,
-            execute: async () => receipt, resolveAuthority });
+        await store.acceptHostAttestationReceipt({ operationId: receipt.operationId, expectedRevision, expectedFence,
+            receipt, resolveAuthority });
         const result = await store.applyHostAttestation({ planId, expectedRevision, expectedFence, receipt,
             idempotencyKey: `host-attestation:${receipt.operationId}`, resolveAuthority });
         let plan = store.getPlan(result.result.id);
         assertPlanTrust(plan, trust);
         if (plan.status === 'rollback-pending' || plan.status === 'commit-pending') {
             plan = await store.claimActivation({ planId: plan.id, expectedRevision: plan.revision, leaseMs,
-                resolveApprovalAuthority: receipt => activationApprovalAuthority(trust, receipt) });
+                resolveApprovalAuthority: receipt => activationClaimAuthority(trust, plan, receipt) });
             lock = await acquireProfileLock(store, plan);
             if (plan.status === 'rollback-pending') {
                 plan = await finishRollback(store, plan, lock);
                 lock = undefined;
             }
             else {
-                const activationPaths = paths(plan);
-                await fencedMutation(store, plan, () => rm(activationPaths.backupPath, { recursive: true, force: true }));
-                await fencedMutation(store, plan, () => rm(activationPaths.stagePath, { recursive: true, force: true }));
-                plan = advance(store, plan, 'activated');
+                plan = await finishCommit(store, plan);
             }
         }
         process.stdout.write(`${JSON.stringify({ ...result, result: plan })}\n`);
@@ -822,113 +1136,145 @@ async function hostRequest(argv) {
         store.close();
     }
 }
-async function probe(argv) {
-    const trust = await commandTrust(argv);
+async function probePluginPlanResult(input) {
+    const { store, trust, planId, expectedRevision, expectedFence, signal } = input;
     if (trust.hostAttestor === undefined)
         throw new ControlPlaneCliError('HOST_ATTESTOR_NOT_CONFIGURED', 'deployment has no owner-configured Host attestor; activation remains awaiting its current phase');
-    const store = new ControlPlaneStore({ path: trust.ledger.path });
     let lock;
     try {
-        const plan = store.getPlan(option(argv, '--plan-id'));
+        throwIfAborted(signal);
+        const plan = store.getPlan(planId);
         assertPlanTrust(plan, trust);
-        const expectedRevision = integerOption(argv, '--expected-revision');
-        const expectedFence = integerOption(argv, '--expected-fence');
         if (plan.revision !== expectedRevision || plan.activation?.fence !== expectedFence) {
             throw new ControlPlaneCliError('ACTIVATION_BINDING', 'configured Host probe targets a stale revision/fence');
         }
         const operation = prepareConfiguredHostAttestation(store, plan, trust);
+        throwIfAborted(signal);
         const resolveAuthority = (value) => {
             const key = resolveTrustKey(trust, 'host-attestation', value.authority, value.keyId);
             return new Ed25519HostAttestationAuthority(key.publicKeyPem, key.authority, key.keyId);
         };
-        const receipt = await store.runHostAttestationOperation({ operationId: operation.operationId, expectedRevision, expectedFence,
-            execute: request => invokeConfiguredHostAttestor(trust, request), resolveAuthority });
-        const result = await store.applyHostAttestation({ planId: plan.id, expectedRevision, expectedFence, receipt,
-            idempotencyKey: `host-attestation:${operation.operationId}`, resolveAuthority });
+        const receipt = await checked(signal, () => store.runHostAttestationOperation({ operationId: operation.operationId, expectedRevision, expectedFence,
+            execute: request => invokeConfiguredHostAttestor(trust, request, signal), resolveAuthority }));
+        const result = await checked(signal, () => store.applyHostAttestation({ planId: plan.id, expectedRevision, expectedFence, receipt,
+            idempotencyKey: `host-attestation:${operation.operationId}`, resolveAuthority }));
         let output = result.result;
-        if (output.status === 'rollback-pending' || output.status === 'commit-pending') {
+        if (output.status === 'rollback-pending' || (output.status === 'commit-pending' && !input.deferCommit)) {
+            // Once physical recovery/commit is durable, complete it under the
+            // profile lock instead of leaving a claimed plan on a late abort.
             output = await store.claimActivation({ planId: output.id, expectedRevision: output.revision, leaseMs,
-                resolveApprovalAuthority: receipt => activationApprovalAuthority(trust, receipt) });
+                resolveApprovalAuthority: receipt => activationClaimAuthority(trust, output, receipt) });
             lock = await acquireProfileLock(store, output);
             if (output.status === 'rollback-pending') {
                 output = await finishRollback(store, output, lock);
                 lock = undefined;
             }
             else {
-                const activationPaths = paths(output);
-                await fencedMutation(store, output, () => rm(activationPaths.backupPath, { recursive: true, force: true }));
-                await fencedMutation(store, output, () => rm(activationPaths.stagePath, { recursive: true, force: true }));
-                output = advance(store, output, 'activated');
+                output = await finishCommit(store, output);
             }
         }
-        process.stdout.write(`${JSON.stringify({ ...result, result: output })}\n`);
+        return { plan: output, result };
     }
     finally {
         if (lock !== undefined)
             await releaseProfileLock(store, lock);
-        store.close();
     }
 }
-async function executable(command, environment) {
-    const candidates = command === 'git' ? ['/usr/bin/git', '/bin/git'] : [join(dirname(process.execPath), 'pnpm'),
-        ...(environment.PATH ?? '').split(delimiter).filter(isAbsolute).map(directory => join(directory, 'pnpm'))];
-    const uid = process.getuid?.();
-    for (const candidate of candidates) {
-        try {
-            const canonical = await realpath(candidate);
-            const value = await lstat(canonical);
-            const directory = await lstat(dirname(canonical));
-            if (value.isFile() && !value.isSymbolicLink() && (value.mode & 0o111) !== 0 && (value.mode & 0o022) === 0
-                && (uid === undefined || value.uid === 0 || value.uid === uid) && directory.isDirectory() && (directory.mode & 0o002) === 0)
-                return canonical;
+export async function probePluginPlan(input) {
+    return (await probePluginPlanResult(input)).plan;
+}
+async function probe(argv) {
+    const trust = await commandTrust(argv);
+    if (trust.hostAttestor === undefined)
+        throw new ControlPlaneCliError('HOST_ATTESTOR_NOT_CONFIGURED', 'deployment has no owner-configured Host attestor; activation remains awaiting its current phase');
+    const store = new ControlPlaneStore({ path: trust.ledger.path });
+    try {
+        const planId = option(argv, '--plan-id');
+        const expectedRevision = integerOption(argv, '--expected-revision');
+        const expectedFence = integerOption(argv, '--expected-fence');
+        if (argv.includes('--prepare-only')) {
+            const plan = store.getPlan(planId);
+            assertPlanTrust(plan, trust);
+            if (plan.revision !== expectedRevision || plan.activation?.fence !== expectedFence) {
+                throw new ControlPlaneCliError('ACTIVATION_BINDING', 'configured Host probe targets a stale revision/fence');
+            }
+            process.stdout.write(`${JSON.stringify(prepareConfiguredHostAttestation(store, plan, trust).request)}\n`);
+            return;
         }
-        catch { /* next */ }
+        const outcome = await probePluginPlanResult({ store, trust, planId, expectedRevision, expectedFence });
+        process.stdout.write(`${JSON.stringify({ ...outcome.result, result: outcome.plan })}\n`);
     }
-    throw new ControlPlaneCliError('SOURCE_BOUNDARY', `registered local ${command} executable is unavailable`);
-}
-async function localCommand(command, args, cwd, environment, capture = false, maximumOutput) {
-    return runBounded({ executable: await executable(command, environment), args, cwd, environment, capture,
-        ...(maximumOutput === undefined ? {} : { maximumOutput }) });
-}
-function sourceScope(name) { return [pluginCatalogScope, `plugins/${name}`].sort(); }
-function assertExactSourceScope(plan) {
-    const expected = sourceScope(plan.name);
-    if (plan.scope.length !== expected.length || plan.scope.some((value, index) => value !== expected[index])) {
-        throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'source plan scope does not match the exact generator outputs');
+    finally {
+        store.close();
     }
 }
-async function changedSourcePaths(worktree, baseCommit, environment) {
-    const tracked = await localCommand('git', ['--literal-pathspecs', '-c', 'core.quotepath=false', 'diff', '--no-renames',
-        '--name-only', '-z', baseCommit, '--'], worktree, environment, true, 8_388_608);
-    const untracked = await localCommand('git', ['--literal-pathspecs', '-c', 'core.quotepath=false', 'ls-files', '--others',
-        '--exclude-standard', '-z'], worktree, environment, true, 8_388_608);
-    return [...new Set(`${tracked}${untracked}`.split('\0').filter(Boolean))].sort();
+async function watchObserve(argv) {
+    const trust = await commandTrust(argv);
+    const store = new ControlPlaneStore({ path: trust.ledger.path });
+    try {
+        const receipt = parsePostActivationObservation(JSON.parse(await loadPrivateApprovalInput(resolve(option(argv, '--receipt')), 32_768)));
+        assertPlanTrust(store.getPlan(receipt.planId), trust);
+        const result = await store.recordPostActivationObservation({
+            receipt,
+            ...(argv.includes('--expected-revision') ? { expectedRevision: integerOption(argv, '--expected-revision') } : {}),
+            resolveAuthority: (value) => {
+                const key = resolveTrustKey(trust, 'host-attestation', value.authority, value.keyId);
+                return new Ed25519PostActivationObservationAuthority(key.publicKeyPem, key.authority, key.keyId);
+            },
+            idempotencyKey: `post-activation-observation:${receipt.observationId}`
+        });
+        const activation = receipt.disposition === 'regressed' ? await rollbackPluginWatch({ store, trust, planId: receipt.planId }) : undefined;
+        process.stdout.write(`${JSON.stringify({ ...result, ...(activation === undefined ? {} : { activation }) })}\n`);
+    }
+    finally {
+        store.close();
+    }
 }
-function sourcePathAllowed(path, plan) {
-    const pluginRoot = `plugins/${plan.name}`;
-    return path === pluginCatalogScope || path === pluginRoot || path.startsWith(`${pluginRoot}/`);
+async function watchRetract(argv) {
+    const trust = await commandTrust(argv);
+    const store = new ControlPlaneStore({ path: trust.ledger.path });
+    try {
+        const receipt = parseActivationRetraction(JSON.parse(await loadPrivateApprovalInput(resolve(option(argv, '--receipt')), 32_768)));
+        assertPlanTrust(store.getPlan(receipt.planId), trust);
+        const result = await store.retractActivation({
+            receipt,
+            ...(argv.includes('--expected-revision') ? { expectedRevision: integerOption(argv, '--expected-revision') } : {}),
+            resolveAuthority: (value) => {
+                const key = resolveTrustKey(trust, 'approval', value.authority, value.keyId);
+                return new Ed25519ActivationRetractionAuthority(key.publicKeyPem, key.authority, key.keyId);
+            },
+            idempotencyKey: `activation-retraction:${receipt.retractionId}`
+        });
+        const activation = await rollbackPluginWatch({ store, trust, planId: receipt.planId });
+        process.stdout.write(`${JSON.stringify({ ...result, activation })}\n`);
+    }
+    finally {
+        store.close();
+    }
 }
-export async function checkedSourceSnapshot(worktree, baseCommit, scopeInput, environment) {
-    const temporary = await mkdtemp(join(tmpdir(), 'dsh-plugin-control-index-'));
+async function watchShow(argv) {
+    const trust = await commandTrust(argv);
+    const store = new ControlPlaneStore({ path: trust.ledger.path });
     try {
-        const scope = [...new Set(scopeInput.map(value => value.normalize('NFC').trim()))].sort();
-        if (scope.length === 0 || scope.some(value => value === ''))
-            throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'checked source scope is invalid');
-        const snapshotEnvironment = { ...environment, GIT_INDEX_FILE: join(temporary, 'index') };
-        await localCommand('git', ['read-tree', baseCommit], worktree, snapshotEnvironment);
-        await localCommand('git', ['--literal-pathspecs', 'add', '--all', '--', ...scope], worktree, snapshotEnvironment);
-        const tree = await localCommand('git', ['--literal-pathspecs', '-c', 'core.quotepath=false', 'ls-files', '--stage', '-z',
-            '--', ...scope], worktree, snapshotEnvironment, true, 8_388_608);
-        const patch = await localCommand('git', ['--literal-pathspecs', '-c', 'core.quotepath=false', 'diff', '--cached', '--binary',
-            '--full-index', '--no-color', baseCommit, '--', ...scope], worktree, snapshotEnvironment, true, 8_388_608);
-        const binding = `${baseCommit}\0${JSON.stringify(scope)}\0`;
-        return {
-            checkedTreeDigest: createHash('sha256').update('dsh-source-tree-v2\0').update(binding).update(tree).digest('hex'),
-            checkedPatchDigest: createHash('sha256').update('dsh-source-patch-v2\0').update(binding).update(patch).digest('hex'),
-        };
+        const planId = optionalOption(argv, '--plan-id');
+        if (planId !== undefined) {
+            assertPlanTrust(store.getPlan(planId), trust);
+            process.stdout.write(`${JSON.stringify({ watch: store.getActivationWatch(planId),
+                evidence: store.listActivationWatchEvidence(planId) })}\n`);
+        }
+        else {
+            process.stdout.write(`${JSON.stringify({ watches: store.listActivationWatches(argv.includes('--limit') ? integerOption(argv, '--limit') : undefined) })}\n`);
+        }
     }
     finally {
-        await rm(temporary, { recursive: true, force: true });
+        store.close();
+    }
+}
+function sourceScope(name) { return [pluginCatalogScope, `plugins/${name}`].sort(); }
+function assertExactSourceScope(plan) {
+    const expected = sourceScope(plan.name);
+    if (plan.scope.length !== expected.length || plan.scope.some((value, index) => value !== expected[index])) {
+        throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'source plan scope does not match the exact generator outputs');
     }
 }
 async function sourcePlan(argv) {
@@ -941,11 +1287,11 @@ async function sourcePlan(argv) {
         if (!pluginPattern.test(name))
             throw new ControlPlaneCliError('INVALID_ARGUMENT', 'plugin name is invalid');
         const environment = inheritedEnvironment(trust);
-        const worktrees = (await localCommand('git', ['worktree', 'list', '--porcelain'], repository, environment, true)).split('\n')
+        const worktrees = (await runLocalCommand('git', ['worktree', 'list', '--porcelain'], repository, environment, { capture: true })).split('\n')
             .filter(line => line.startsWith('worktree ')).map(line => resolve(line.slice('worktree '.length)));
         if (worktrees.length < 2 || worktrees[0] === worktree || !worktrees.includes(worktree))
             throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'source plan requires a linked non-primary worktree');
-        const baseCommit = (await localCommand('git', ['rev-parse', 'HEAD'], worktree, environment, true)).trim();
+        const baseCommit = (await runLocalCommand('git', ['rev-parse', 'HEAD'], worktree, environment, { capture: true })).trim();
         const generator = join(repository, 'scripts', 'create-plugin.mjs');
         const generatorDigest = createHash('sha256').update(await readSafeFile(generator, 1_048_576)).digest('hex');
         const output = store.createSourcePlan({ gapId: option(argv, '--gap-id'), repository, worktree, baseCommit, name,
@@ -964,22 +1310,26 @@ async function scaffold(argv) {
     let plan;
     try {
         plan = store.getSourcePlan(option(argv, '--plan-id'));
+        if (plan.mode !== 'create')
+            throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'scaffold only serves create source plans; modify plans are verified, not locally scaffolded');
         if (plan.status !== 'approved' || plan.revision !== integerOption(argv, '--expected-revision'))
             throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'exact approved source plan revision is required');
         assertExactSourceScope(plan);
         if (await realpath(plan.repository) !== plan.repository || await realpath(plan.worktree) !== plan.worktree)
             throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'source paths changed');
         const environment = inheritedEnvironment(trust);
-        if ((await localCommand('git', ['rev-parse', 'HEAD'], plan.worktree, environment, true)).trim() !== plan.baseCommit
+        if ((await runLocalCommand('git', ['rev-parse', 'HEAD'], plan.worktree, environment, { capture: true })).trim() !== plan.baseCommit
             || createHash('sha256').update(await readSafeFile(join(plan.repository, 'scripts', 'create-plugin.mjs'), 1_048_576)).digest('hex') !== plan.generatorDigest
-            || (await localCommand('git', ['status', '--porcelain'], plan.worktree, environment, true)).trim() !== '')
+            || (await runLocalCommand('git', ['status', '--porcelain'], plan.worktree, environment, { capture: true })).trim() !== '')
             throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'source plan base, generator or clean-worktree binding changed');
         plan = store.beginSourceChecks({ planId: plan.id, expectedRevision: plan.revision });
         try {
-            await localCommand('pnpm', ['create:plugin', plan.name], plan.worktree, environment);
-            await localCommand('pnpm', ['check'], plan.worktree, environment);
+            // Uncaptured commands: stdout is drained and discarded without a byte
+            // bound, exactly like the legacy localCommand scaffold path.
+            await runLocalCommand('pnpm', ['create:plugin', plan.name], plan.worktree, environment);
+            await runLocalCommand('pnpm', ['check'], plan.worktree, environment);
             const changes = await changedSourcePaths(plan.worktree, plan.baseCommit, environment);
-            const outsideScope = changes.find(path => !sourcePathAllowed(path, plan));
+            const outsideScope = changes.find(path => !sourcePathAllowed(path, plan.name, plan.mode));
             if (outsideScope !== undefined)
                 throw new ControlPlaneCliError('SOURCE_BOUNDARY', `source generator changed files outside its approved scope: ${JSON.stringify(outsideScope)}`);
             const checked = await checkedSourceSnapshot(plan.worktree, plan.baseCommit, plan.scope, environment);
@@ -995,6 +1345,43 @@ async function scaffold(argv) {
         store.close();
     }
 }
+async function sourceVerifyPrepared(argv) {
+    const trust = await commandTrust(argv);
+    const store = new ControlPlaneStore({ path: trust.ledger.path });
+    try {
+        const planId = option(argv, '--plan-id');
+        const expectedRevision = integerOption(argv, '--expected-revision');
+        const plan = store.getSourcePlan(planId);
+        if (plan.mode !== 'modify')
+            throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'verify-prepared only serves modify source plans; create plans are locally scaffolded');
+        if (plan.status !== 'approved' || plan.revision !== expectedRevision) {
+            throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'exact approved modify source plan revision is required');
+        }
+        if (plan.sourceCheck === undefined)
+            throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'approved modify plan is missing its bound checked digests');
+        const checked = await verifyPreparedSourceWorktree(plan, inheritedEnvironment(trust));
+        const receipt = store.verifyPreparedSourcePlan({ planId: plan.id, expectedRevision: plan.revision,
+            recheckedTreeDigest: checked.checkedTreeDigest, recheckedPatchDigest: checked.checkedPatchDigest });
+        process.stdout.write(`${JSON.stringify(receipt)}\n`);
+    }
+    finally {
+        store.close();
+    }
+}
+async function sourceGc(argv) {
+    const trust = await commandTrust(argv);
+    const store = new ControlPlaneStore({ path: trust.ledger.path });
+    try {
+        // The ledger path is owner-bound to <statePath>/control.sqlite; command
+        // callers are forbidden from supplying a state root, so derive it here.
+        const result = await gcPreparedModifyWorktrees({ store, statePath: dirname(trust.ledger.path),
+            environment: inheritedEnvironment(trust), now: Date.now() });
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+    }
+    finally {
+        store.close();
+    }
+}
 function assertReleaseCommand(argv) {
     if (argv.includes('--phase'))
         throw new ControlPlaneCliError('INVALID_ARGUMENT', 'release phase is derived from durable plan status');
@@ -1039,12 +1426,22 @@ async function prepareRelease(store, trust, plan) {
         interpreter: adapter.interpreter, authority: adapter.authority, keyId: adapter.keyId };
     let catalog = { id: trust.catalog.id, path: trust.catalog.path };
     if (expected.phase === 'catalog-admission') {
-        const loaded = await loadCatalogWithMetadata(trust.catalog.path);
-        const preview = previewCatalogAdmission(loaded.catalog, store.sourceReleaseCandidate(plan.id));
-        catalog = { ...catalog, expectedBeforeDigest: preview.beforeCatalogDigest, expectedAfterDigest: preview.afterCatalogDigest };
+        const prior = store.findSourceReleaseOperation(plan.id, expected.phase, plan.release.fence);
+        if (prior?.request.phase === 'catalog-admission') {
+            catalog = { ...catalog, expectedBeforeDigest: prior.request.input.expectedBeforeCatalogDigest,
+                expectedAfterDigest: prior.request.input.expectedAfterCatalogDigest };
+        }
+        else {
+            const loaded = await loadCatalogWithMetadata(trust.catalog.path);
+            const preview = previewCatalogAdmission(loaded.catalog, store.previewSourceReleaseCandidate(plan.id));
+            catalog = { ...catalog, expectedBeforeDigest: preview.beforeCatalogDigest, expectedAfterDigest: preview.afterCatalogDigest };
+        }
     }
+    // Only {id, locator} leaves the owner host: caPins/tokenEnvironment are
+    // activation-side local trust roots and must never reach a release adapter.
+    const releaseRegistry = { id: trust.releaseRegistry.id, locator: trust.releaseRegistry.locator };
     return store.prepareSourceReleaseOperation({ planId: plan.id, expectedRevision: plan.revision, expectedFence: plan.release.fence,
-        installationId: trust.installationId, ledger: trust.ledger, registry: trust.releaseRegistry, catalog, adapter: adapterIdentity,
+        installationId: trust.installationId, ledger: trust.ledger, registry: releaseRegistry, catalog, adapter: adapterIdentity,
         receiptTtlMs: trust.releaseReceiptTtlMs, resolveAuthorizationAuthority: value => releaseAuthorizationAuthority(trust, value) });
 }
 async function releaseStart(argv) {
@@ -1113,7 +1510,7 @@ async function releaseAttest(argv) {
         const receipt = parseSourceReleaseReceipt(JSON.parse(await readOwnerPrivateFile(resolve(option(argv, '--receipt')), 262_144)));
         if (receipt.operationId !== operation.operationId)
             throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'release receipt does not target the durable operation');
-        await store.runSourceReleaseOperation({ operationId: operation.operationId, expectedRevision, expectedFence, execute: async () => receipt,
+        await store.acceptSourceReleaseReceipt({ operationId: operation.operationId, expectedRevision, expectedFence, receipt,
             resolveAuthority: value => releaseAuthority(trust, value),
             resolveAuthorizationAuthority: value => releaseAuthorizationAuthority(trust, value) });
         const result = await store.applySourceRelease({ planId: plan.id, expectedRevision, expectedFence, receipt,
@@ -1144,7 +1541,8 @@ async function releaseReconcile(argv) {
         const adapterIdentity = { id: adapter.id, version: adapter.version, path: adapter.path, sha256: adapter.sha256,
             interpreter: adapter.interpreter, authority: adapter.authority, keyId: adapter.keyId };
         const operation = await store.prepareSourcePublishReconciliation({ planId: plan.id, expectedRevision, expectedFence,
-            installationId: trust.installationId, ledger: trust.ledger, registry: trust.releaseRegistry, adapter: adapterIdentity,
+            installationId: trust.installationId, ledger: trust.ledger,
+            registry: { id: trust.releaseRegistry.id, locator: trust.releaseRegistry.locator }, adapter: adapterIdentity,
             receiptTtlMs: trust.releaseReceiptTtlMs, resolveAuthorizationAuthority: value => releaseAuthorizationAuthority(trust, value) });
         const receiptPath = optionalOption(argv, '--receipt');
         const supplied = receiptPath === undefined ? undefined : parseSourcePublishReconciliationReceipt(JSON.parse(await readOwnerPrivateFile(resolve(receiptPath), 262_144)));
@@ -1163,6 +1561,39 @@ async function releaseReconcile(argv) {
         store.close();
     }
 }
+async function activationPlan(argv) {
+    const trust = await commandTrust(argv);
+    const store = new ControlPlaneStore({ path: trust.ledger.path });
+    try {
+        const sourcePlanId = option(argv, '--source-plan');
+        const profile = option(argv, '--profile');
+        const idempotencyKey = option(argv, '--idempotency-key');
+        const ttlMs = optionalOption(argv, '--ttl-ms') === undefined ? 900_000 : integerOption(argv, '--ttl-ms');
+        const source = store.getSourcePlan(sourcePlanId);
+        if (source.status !== 'release-complete') {
+            throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'activation plan requires a release-complete source plan');
+        }
+        const released = store.sourceReleaseCandidate(sourcePlanId);
+        const loaded = await loadCatalogWithMetadata(trust.catalog.path);
+        const admitted = loaded.catalog.entries.find(entry => entry.id === released.id);
+        if (admitted === undefined
+            || controlPlaneDigest({ schemaVersion: 1, entries: [admitted] }) !== controlPlaneDigest({ schemaVersion: 1, entries: [released] })) {
+            throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'released candidate is not the exact admitted owner catalog entry');
+        }
+        if (!discover(loaded.catalog, source.gapSnapshot.capability).some(entry => entry.id === released.id)) {
+            throw new ControlPlaneCliError('SOURCE_BOUNDARY', 'admitted candidate does not match the released gap capability');
+        }
+        const target = await canonicalProfileTarget(trust, profile);
+        const receipt = store.createPlan({ candidate: admitted, catalog: { digest: loaded.digest, provenance: loaded.provenance },
+            matchedCapabilities: admitted.capabilities, profile, target, installationId: trust.installationId, ledger: trust.ledger,
+            executor: { id: trust.executor.id, version: trust.executor.version, path: trust.executor.path, sha256: trust.executor.sha256 },
+            ttlMs, gapId: source.gapId, idempotencyKey });
+        process.stdout.write(`${JSON.stringify(receipt)}\n`);
+    }
+    finally {
+        store.close();
+    }
+}
 export async function runPluginControl(argv = process.argv.slice(2)) {
     rejectCommandSuppliedTrust(argv);
     const command = argv[0];
@@ -1192,10 +1623,23 @@ export async function runPluginControl(argv = process.argv.slice(2)) {
         return probe(argv);
     if (command === 'attest')
         return attest(argv);
+    if (command === 'watch-observe')
+        return watchObserve(argv);
+    if (command === 'watch-retract')
+        return watchRetract(argv);
+    if (command === 'watch-show')
+        return watchShow(argv);
     if (command === 'source-plan')
         return sourcePlan(argv);
     if (command === 'scaffold')
         return scaffold(argv);
+    if (command === 'source') {
+        if (argv[1] === 'verify-prepared')
+            return sourceVerifyPrepared(argv);
+        if (argv[1] === 'gc')
+            return sourceGc(argv);
+        throw new ControlPlaneCliError('INVALID_ARGUMENT', 'usage: dsh-plugin-control source <verify-prepared|gc>');
+    }
     if (command === 'release-start')
         return releaseStart(argv);
     if (command === 'release-request')
@@ -1206,6 +1650,8 @@ export async function runPluginControl(argv = process.argv.slice(2)) {
         return releaseAttest(argv);
     if (command === 'release-reconcile')
         return releaseReconcile(argv);
-    throw new ControlPlaneCliError('INVALID_ARGUMENT', 'usage: dsh-plugin-control <discover|show|approve|activate|host-request|probe|attest|source-plan|scaffold|release-start|release-request|release-step|release-attest|release-reconcile>');
+    if (command === 'activation-plan')
+        return activationPlan(argv);
+    throw new ControlPlaneCliError('INVALID_ARGUMENT', 'usage: dsh-plugin-control <discover|show|approve|activate|host-request|probe|attest|watch-observe|watch-retract|watch-show|source-plan|scaffold|source verify-prepared|source gc|release-start|release-request|release-step|release-attest|release-reconcile|activation-plan>');
 }
 //# sourceMappingURL=cli.js.map