@dsh-enhanced/lark-channel 0.1.48 → 0.1.49

package/lib/rsi-setup.js

@@ -1,31 +1,56 @@
-import { constants } from 'node:fs';
-import { chmod, lstat, open, realpath, rename, unlink } from 'node:fs/promises';
+import { constants, realpathSync } from 'node:fs';
+import { chmod, lstat, mkdir, open, realpath, rename, unlink } from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
 import { createHash, createPublicKey, randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { createRequire } from 'node:module';
 import { isDeepStrictEqual } from 'node:util';
-import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
+import { isAlias, isMap, isScalar, isSeq, parseDocument } from 'yaml';
 import { compileRsiProfiles } from './rsi-profile.js';
 import { withDshHomeLifecycleLock } from './setup.js';
-import { supervisedGrowthBindingQuery, supervisedGrowthDatabasePaths } from './supervised-growth-profile.js';
+import { assertRsiSchedulerActivation, captureRsiAutomationInventories, rsiAutomationInventory, rsiOwnerBindingQuery, rsiDatabasePaths } from './rsi-owner-profile.js';
 import { installDshResidentService } from './resident.js';
+import { prepareRsiSourceWorkspace } from './rsi-source.js';
+import { prepareRsiBuildEnvironment, RsiBuildUnavailableError } from './rsi-build.js';
+import { prepareRsiReleaseBuildEnvironment, RsiReleaseBuildUnavailableError } from './rsi-release-build.js';
+import { prepareRsiAuthorityRuntime } from './rsi-authority-runtime.js';
+import { prepareRsiAuthorityResources } from './rsi-authority-resources.js';
+import { version } from './version.js';
+import { renderDshSystemdService, systemdServicePaths } from './systemd.js';
+import { rsiServiceEnvironmentPath } from './rsi-service-environment.js';
+import { resolveRsiServiceEnvironments } from './rsi-service-setup.js';
+import { validateRsiHostAuthorities } from './rsi-host-authorities.js';
+import { validateRsiMemoryLearningSetup } from './rsi-memory-learning.js';
+import { resolveInstalledRsiDsh } from './rsi-install-inputs.js';
 const MAX_BYTES = 2_097_152;
 const profilePattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u;
 const digest = (value) => createHash('sha256').update(value).digest('hex');
 function fail(message) { throw new Error(`rsi setup: ${message}`); }
 // Compare semantic YAML nodes, including executable !!js tags, without depending
 // on comments or formatting retained by the profile patch serializer.
-function yamlValue(node) {
+function yamlValue(node, document, ancestors = new Set()) {
+    if (isAlias(node)) {
+        const resolved = node.resolve(document);
+        if (!resolved || ancestors.has(resolved))
+            fail('cyclic or unresolved YAML alias');
+        return yamlValue(resolved, document, new Set(ancestors).add(resolved));
+    }
     if (isScalar(node))
         return { tag: node.tag, value: node.value };
     if (isSeq(node))
-        return { tag: node.tag, items: node.items.map(yamlValue) };
+        return { tag: node.tag, items: node.items.map(item => yamlValue(item, document, ancestors)) };
     if (isMap(node))
-        return { tag: node.tag, entries: node.items.map(item => [yamlValue(item.key), yamlValue(item.value)])
+        return { tag: node.tag, entries: node.items.map(item => [yamlValue(item.key, document, ancestors), yamlValue(item.value, document, ancestors)])
                 .sort((left, right) => JSON.stringify(left[0]).localeCompare(JSON.stringify(right[0]))) };
     return node;
 }
+function patchValue(source, label) {
+    const document = parseDocument(source, { uniqueKeys: true });
+    if (document.errors.length || !isSeq(document.contents))
+        fail(`invalid ${label} patch`);
+    return yamlValue(document.contents, document);
+}
 export function assertRsiEffectivePatch(patch, effective) {
     const expected = parseDocument(patch), actual = parseDocument(effective);
     if (expected.errors.length || actual.errors.length || !isSeq(expected.contents) || !isSeq(actual.contents))
@@ -36,7 +61,7 @@ export function assertRsiEffectivePatch(patch, effective) {
         const matches = actual.contents.items.filter(item => isMap(item) && item.get('id') === row.get('id'));
         const resolved = matches[0];
         if (matches.length !== 1 || !isMap(resolved) || resolved.get('disabled') === true && row.get('disabled') !== true
-            || !isDeepStrictEqual(yamlValue(row.get('config', true)), yamlValue(resolved.get('config', true))))
+            || !isDeepStrictEqual(yamlValue(row.get('config', true), expected), yamlValue(resolved.get('config', true), actual)))
             fail(`effective profile overrides compiled config for ${String(row.get('id'))}`);
     }
 }
@@ -46,7 +71,7 @@ export function parseRsiSetupArgs(argv) {
     const seen = new Set();
     for (let i = 0; i < argv.length; i++) {
         const key = argv[i];
-        if (seen.has(key))
+        if (key !== '--bundle' && seen.has(key))
             fail(`duplicate option ${key}`);
         seen.add(key);
         if (key === '--help' || key === '-h')
@@ -59,12 +84,42 @@ export function parseRsiSetupArgs(argv) {
             result.start = true;
         else if (key === '--confirm-hosts-stopped')
             result.confirmStopped = true;
-        else if (key === '--manifest' || key === '--dsh-home') {
+        else if (key === '--prepare-source')
+            result.prepareSource = true;
+        else if (key === '--prepare-build')
+            result.prepareBuild = true;
+        else if (key === '--prepare-authorities')
+            result.prepareAuthorities = true;
+        else if (key === '--install-owner')
+            result.installOwner = true;
+        else if (key === '--ack-existing-automations')
+            result.ackExistingAutomations = true;
+        else if (key === '--install-local-cohort')
+            result.installLocalCohort = true;
+        else if (key === '--prepare-local-update')
+            result.prepareLocalUpdate = true;
+        else if (key === '--add-memory-learning')
+            result.addMemoryLearning = true;
+        else if (key === '--bundle') {
+            const value = argv[++i];
+            if (!value || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(value))
+                fail('--bundle requires a plugin slug');
+            (result.bundles ??= []).push(value);
+        }
+        else if (key === '--optional-build')
+            result.optionalBuild = true;
+        else if (key === '--manifest' || key === '--dsh-home' || key === '--profile' || key === '--source-repository' || key === '--docker-path') {
             const value = argv[++i];
             if (!value || value.startsWith('--'))
                 fail(`${key} needs a value`);
             if (key === '--manifest')
                 result.manifestPath = resolve(value);
+            else if (key === '--profile')
+                result.profile = value;
+            else if (key === '--source-repository')
+                result.sourceRepository = value;
+            else if (key === '--docker-path')
+                result.dockerPath = value;
             else
                 result.dshHome = value;
         }
@@ -73,6 +128,63 @@ export function parseRsiSetupArgs(argv) {
     }
     if (result.help)
         return result;
+    if (result.addMemoryLearning && !result.prepareLocalUpdate)
+        fail('--add-memory-learning requires --prepare-local-update');
+    if (result.ackExistingAutomations && (!result.installOwner && !result.apply || result.rollback
+        || result.prepareLocalUpdate || result.installLocalCohort || result.prepareSource || result.prepareBuild || result.prepareAuthorities))
+        fail('--ack-existing-automations requires --install-owner or --apply');
+    if (result.prepareLocalUpdate) {
+        if (result.installLocalCohort || result.installOwner || result.prepareSource || result.prepareBuild
+            || result.prepareAuthorities || result.manifestPath || result.apply || result.rollback || result.start
+            || result.confirmStopped || result.optionalBuild || result.dockerPath || result.bundles)
+            fail('local update preparation cannot be combined with other operations');
+        if (!isAbsolute(result.dshHome) || !result.profile || !profilePattern.test(result.profile))
+            fail('local update preparation requires --profile and absolute DSH_HOME');
+        if (result.sourceRepository && !isAbsolute(result.sourceRepository))
+            fail('--source-repository must be absolute');
+        return result;
+    }
+    if (result.bundles && !result.installLocalCohort)
+        fail('--bundle requires --install-local-cohort');
+    if (result.installLocalCohort) {
+        if (result.installOwner || result.prepareSource || result.prepareBuild || result.prepareAuthorities || result.manifestPath
+            || result.apply || result.rollback || result.start || result.confirmStopped || result.optionalBuild || result.dockerPath)
+            fail('local cohort installation cannot be combined with other operations');
+        if (!isAbsolute(result.dshHome) || !result.profile || !profilePattern.test(result.profile)
+            || !result.sourceRepository || !isAbsolute(result.sourceRepository) || !result.bundles?.length
+            || new Set(result.bundles).size !== result.bundles.length)
+            fail('local cohort installation requires a profile, absolute source repository and unique bundles');
+        return result;
+    }
+    if ((result.optionalBuild || result.dockerPath) && !result.prepareBuild)
+        fail('--optional-build and --docker-path require --prepare-build');
+    if (result.installOwner) {
+        if (result.prepareSource || result.prepareBuild || result.prepareAuthorities || result.manifestPath || result.apply
+            || result.rollback || result.start || result.confirmStopped || result.optionalBuild || result.dockerPath)
+            fail('owner installation cannot be combined with other operations');
+        if (!isAbsolute(result.dshHome) || !result.profile || !profilePattern.test(result.profile))
+            fail('owner installation requires --profile and absolute DSH_HOME');
+        if (result.sourceRepository && !isAbsolute(result.sourceRepository))
+            fail('--source-repository must be absolute');
+        return result;
+    }
+    if (result.prepareSource || result.prepareBuild || result.prepareAuthorities) {
+        if ([result.prepareSource, result.prepareBuild, result.prepareAuthorities].filter(Boolean).length > 1)
+            fail('resource preparation modes cannot be combined');
+        if (result.manifestPath || result.apply || result.rollback || result.start || result.confirmStopped)
+            fail('resource preparation cannot be combined with profile configuration operations');
+        if (!isAbsolute(result.dshHome) || !result.profile || !profilePattern.test(result.profile))
+            fail('resource preparation requires --profile and absolute DSH_HOME');
+        if (result.prepareAuthorities && result.sourceRepository)
+            fail('--source-repository requires --prepare-source or --prepare-build');
+        if (result.sourceRepository && !isAbsolute(result.sourceRepository))
+            fail('--source-repository must be absolute');
+        if (result.dockerPath && !isAbsolute(result.dockerPath))
+            fail('--docker-path must be absolute');
+        return result;
+    }
+    if (result.profile || result.sourceRepository)
+        fail('--profile and --source-repository require --prepare-source, --prepare-build or --prepare-authorities');
     if (!result.manifestPath || !isAbsolute(result.dshHome))
         fail('--manifest and absolute DSH_HOME are required');
     if (result.rollback && (result.apply || result.start))
@@ -151,29 +263,132 @@ async function readJournal(path, expected) {
         throw error;
     }
     const value = JSON.parse(content);
-    if (value.schemaVersion !== 1 || !['prepared', 'applied'].includes(value.stage) || !/^[a-f0-9]{64}$/u.test(value.manifestDigest)
+    if (![1, 2].includes(value.schemaVersion) || !['prepared', 'applied'].includes(value.stage) || !/^[a-f0-9]{64}$/u.test(value.manifestDigest)
         || !Array.isArray(value.entries) || value.entries.length !== 2
         || value.entries.some((entry, index) => entry.profile !== expected[index] || typeof entry.before !== 'string' || typeof entry.after !== 'string'))
         fail('journal does not match this profile pair');
+    if (value.schemaVersion === 2) {
+        for (const entries of [value.environments, value.units]) {
+            if (!Array.isArray(entries) || entries.length !== 2 || entries.some((entry, index) => entry.profile !== expected[index]
+                || (entry.before !== null && typeof entry.before !== 'string') || (entry.after !== null && typeof entry.after !== 'string')))
+                fail('invalid service environment journal');
+        }
+    }
+    else if (value.environments || value.units)
+        fail('legacy journal cannot contain service resources');
     return value;
 }
-async function rollback(home, journalPath, journal) {
-    // Check both files before restoring either. Retry also accepts a half-restored pair.
+async function readOptionalFile(path, privateFile = true) {
+    try {
+        return await readOwnedFile(path, privateFile);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        // realpath also reports ENOENT for dangling links; those are not absent files.
+        try {
+            await lstat(path);
+        }
+        catch (linkedError) {
+            if (linkedError.code === 'ENOENT')
+                return null;
+            throw linkedError;
+        }
+        fail(`unsafe file: ${path}`);
+    }
+}
+async function writeOptionalFile(path, value) {
+    if (value !== null) {
+        await atomicWrite(path, value);
+        return;
+    }
+    try {
+        await unlink(path);
+        await syncDirectory(dirname(path));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+function auxiliary(home, journal, ports) {
+    return [
+        ...(journal.environments ?? []).map(entry => ({ ...entry, path: rsiServiceEnvironmentPath(home, entry.profile), privateFile: true })),
+        ...(journal.units ?? []).map(entry => ({ ...entry, path: ports.serviceUnitPath(entry.profile, home), privateFile: false })),
+    ];
+}
+async function rollback(home, journalPath, journal, ports) {
+    // Check every resource before restoring any. Retry accepts a half-restored transaction.
     for (const entry of journal.entries) {
         const current = await readOwnedFile(patchPath(home, entry.profile), false);
         if (current !== entry.before && current !== entry.after)
             fail('profile changed outside setup; retain journal for reconciliation');
     }
+    const resources = auxiliary(home, journal, ports);
+    for (const entry of resources) {
+        const current = await readOptionalFile(entry.path, entry.privateFile);
+        if (current !== entry.before && current !== entry.after)
+            fail('service resource changed outside setup; retain journal for reconciliation');
+    }
     for (const entry of journal.entries)
         await atomicWrite(patchPath(home, entry.profile), entry.before);
+    for (const entry of resources)
+        await writeOptionalFile(entry.path, entry.before);
+    if (journal.units)
+        ports.reloadServices();
     await unlink(journalPath);
     await syncDirectory(home);
 }
-const defaultPorts = {
+export async function readRsiInstalledBase(profile, home, environment = process.env) {
+    if (!profilePattern.test(profile))
+        fail('invalid profile for installed base');
+    await safeDirectory(join(home, 'profiles', profile));
+    const dsh = await resolveInstalledRsiDsh(environment);
+    const packageName = '@deepseek-ai/dsh-base';
+    const installAnchor = join(dsh.root, 'package.json');
+    let installRoot = dsh.root;
+    for (let directory = dirname(dsh.root); directory !== dirname(directory); directory = dirname(directory)) {
+        if (basename(directory) === 'node_modules')
+            installRoot = directory;
+    }
+    for (const searchPath of createRequire(installAnchor).resolve.paths(packageName) ?? []) {
+        const packageRoot = join(searchPath, packageName);
+        const manifestPath = join(packageRoot, 'package.json');
+        let manifestBytes;
+        try {
+            const physical = await realpath(manifestPath);
+            const child = relative(installRoot, physical);
+            if (!child || child === '..' || child.startsWith(`..${sep}`) || isAbsolute(child))
+                fail('installed DSH base escapes Host installation');
+            manifestBytes = await readOwnedFile(physical, false, true);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        let manifest;
+        try {
+            manifest = JSON.parse(manifestBytes);
+        }
+        catch {
+            fail('installed DSH base manifest is invalid');
+        }
+        const entry = manifest;
+        if (entry?.name !== packageName || entry.version !== dsh.version || entry.dsh?.bundle?.patch !== './cordis.patch.yml') {
+            fail('installed DSH base identity or patch declaration differs from Host');
+        }
+        const patchPath = await realpath(join(packageRoot, 'cordis.patch.yml'));
+        const child = relative(installRoot, patchPath);
+        if (!child || child === '..' || child.startsWith(`..${sep}`) || isAbsolute(child))
+            fail('installed DSH base patch escapes Host installation');
+        return readOwnedFile(patchPath, false, true);
+    }
+    fail('installed DSH base is absent from Host installation');
+}
+export const rsiSetupPorts = {
     async base(profile, home) {
-        // Resolve the installed package symlink, then pin a bounded non-writable file.
-        const path = await realpath(join(home, 'profiles', profile, 'node_modules', '@deepseek-ai', 'dsh-base', 'cordis.patch.yml'));
-        return readOwnedFile(path, false, true);
+        return readRsiInstalledBase(profile, home);
     },
     dump(profile, home) {
         const result = spawnSync('dsh', ['--profile', profile, '--dump-config'], { encoding: 'utf8', timeout: 60_000,
@@ -184,11 +399,21 @@ const defaultPorts = {
     },
     async snapshot(effective, home) {
         const { inspectActiveLarkOwnerBindingsLocally } = await import('@dsh-enhanced/assistant-delivery');
-        return inspectActiveLarkOwnerBindingsLocally({ databasePath: supervisedGrowthDatabasePaths(effective, home).deliveryDatabasePath,
-            ...supervisedGrowthBindingQuery(effective, home) });
+        return inspectActiveLarkOwnerBindingsLocally({ databasePath: rsiDatabasePaths(effective, home).deliveryDatabasePath,
+            ...rsiOwnerBindingQuery(effective, home) });
     },
+    async automationInventory(effective, home) { return rsiAutomationInventory(effective, home); },
     compile: compileRsiProfiles,
     validateAuthorities: validateRsiAuthorities,
+    resolveEnvironments: resolveRsiServiceEnvironments,
+    serviceUnitPath: (profile, home) => systemdServicePaths({ dshHome: home, profile, home: realpathSync(homedir()) }).unitPath,
+    async renderServiceUnit(profile, home, environment) { return (await renderDshSystemdService({ dshHome: home, profile }, { environment })).source; },
+    reloadServices() {
+        const result = spawnSync('systemctl', ['--user', 'daemon-reload'], { encoding: 'utf8', timeout: 10_000, maxBuffer: 65_536 });
+        if (result.status !== 0 || result.error)
+            fail('cannot reload service definitions');
+    },
+    validateServiceUnits: validateRsiServiceUnitEnvironment,
     assertStopped(profile) {
         const result = spawnSync('systemctl', ['--user', 'show', `dsh-profile-${profile}.service`, '--property=ActiveState', '--value'], { encoding: 'utf8', timeout: 10_000, maxBuffer: 65_536 });
         if (result.status !== 0 || result.error || !['inactive', 'failed'].includes(result.stdout.trim()))
@@ -196,8 +421,20 @@ const defaultPorts = {
     },
     async start(profile, home) { await installDshResidentService({ dshHome: home, profile }); },
 };
+/** Read back the loaded unit after daemon-reload, before starting either Host. */
+export async function validateRsiServiceUnitEnvironment(manifest, environment) {
+    const path = environment.DSH_SYSTEMD_HOST_ATTESTOR_CONFIG;
+    if (!path)
+        return;
+    const wrapper = JSON.parse(await readOwnedFile(path));
+    if (wrapper.schemaVersion !== 4)
+        return;
+    const result = spawnSync('systemctl', ['--user', 'show', `dsh-profile-${manifest.targetProfile}.service`, '--property=Environment', '--value'], { encoding: 'utf8', timeout: 10_000, maxBuffer: 65_536 });
+    if (result.status !== 0 || result.error || result.stdout.trimEnd() !== wrapper.template?.unitProperties?.Environment)
+        fail('effective service environment differs from the Host installation grant');
+}
 /** Validate imported finite grants, without calling any signing/authorization method. */
-export async function validateRsiAuthorities(manifest, binding) {
+export async function validateRsiAuthorities(manifest, binding, environment) {
     const cp = await import('@dsh-enhanced/plugin-control-plane');
     const config = manifest.controlPlane;
     if (!config.sourceJobs || !config.sourceApprovals || !config.sourceReleases || !config.sourceAdoptions || !config.taskObservations)
@@ -213,6 +450,11 @@ export async function validateRsiAuthorities(manifest, binding) {
     const expectedOwner = manifest.sourceReviews.owner;
     if (expectedOwner.principalRecordId !== binding.owner.id || expectedOwner.principalVersion !== binding.owner.version)
         fail('grant owner has changed');
+    // compileRsiProfiles first derives and checks all seven owner fields against
+    // effective Delivery. This secondary check binds grants to that owner; it
+    // cannot independently resolve a route from the principal receipt alone.
+    if (manifest.memoryLearning !== undefined)
+        validateRsiMemoryLearningSetup(manifest.memoryLearning, expectedOwner);
     const trust = await cp.loadTrustConfig(config.trustPath);
     if (trust.schemaVersion !== 4 || !trust.hostAttestor || !trust.releaseAdapters
         || ['pr', 'review', 'merge', 'build', 'sign', 'publish', 'registry-verify', 'catalog-admission'].some(phase => !Object.hasOwn(trust.releaseAdapters, phase)))
@@ -229,6 +471,8 @@ export async function validateRsiAuthorities(manifest, binding) {
         || adoptions.grant.target.profile !== manifest.targetProfile || adoptions.grant.target.profilePath !== config.runtimeObserver?.profilePath
         || adoptions.grant.target.profilePath !== join(trust.dshHome, 'profiles', manifest.targetProfile)
         || !isDeepStrictEqual(adoptions.grant.executor, { id, version, path, sha256 })
+        || !isDeepStrictEqual(adoptions.grant.liveQualification, config.sourceAdoptions.liveQualification)
+        || !isDeepStrictEqual(adoptions.grant.hostDeploymentInputs, config.sourceAdoptions.hostDeploymentInputs)
         || adoptions.grant.catalogPath !== config.catalogPath || !isDeepStrictEqual(adoptions.grant.handoff, config.sourceAdoptions.handoff)
         || approvals.grant.repository !== config.sourceJobs.repository || releases.grant.repository !== config.sourceJobs.repository
         || approvals.grant.worktreeRoot !== join(config.statePath, 'source-worktrees') || releases.grant.worktreeRoot !== approvals.grant.worktreeRoot
@@ -257,11 +501,36 @@ export async function validateRsiAuthorities(manifest, binding) {
         if (!configured.equals(registered))
             fail('authority key does not match registered trust');
     }
+    if (config.liveQualification) {
+        const qualification = JSON.parse(await readOwnedFile(config.liveQualification.authority.configPath));
+        cp.validateLiveQualificationAuthorityConfig(qualification);
+        if (qualification.controlDatabasePath !== ledgerPath || !isDeepStrictEqual(qualification.grant.owner, expectedOwner)
+            || !isDeepStrictEqual(qualification.grant.terms, config.sourceAdoptions.liveQualification)
+            || qualification.grant.installationId !== trust.installationId || !isDeepStrictEqual(qualification.grant.ledger, trust.ledger)
+            || qualification.grant.profilePath !== config.liveQualification.profilePath
+            || !isDeepStrictEqual([...qualification.grant.packages].sort(), selected.map(plugin => `@dsh-enhanced/${plugin}`))
+            || qualification.grant.expiresAt <= Date.now())
+            fail('live qualification authority terms mismatch');
+        const trusted = cp.resolveTrustKey(trust, 'host-attestation', qualification.authority, qualification.keyId);
+        const configured = createPublicKey(await readOwnedFile(qualification.keyPath)).export({ type: 'spki', format: 'der' });
+        if (!configured.equals(createPublicKey(trusted.publicKeyPem).export({ type: 'spki', format: 'der' })))
+            fail('live qualification authority key mismatch');
+    }
     if ([approvals.grant.expiresAt, releases.grant.expiresAt, adoptions.grant.expiresAt, observations.grant.policy.expiresAt,
         manifest.sourceReviews.expiresAt].some(value => value <= Date.now()))
         fail('finite authority has expired');
+    await validateRsiHostAuthorities({ trust, adoption: adoptions, owner: expectedOwner, ledgerPath, trustPath: config.trustPath,
+        targetProfile: manifest.targetProfile,
+        liveQualification: config.sourceAdoptions.liveQualification, hostDeploymentInputs: config.sourceAdoptions.hostDeploymentInputs,
+        handoff: config.sourceAdoptions.handoff, ...(environment === undefined ? {} : { environment }), readPrivate: path => readOwnedFile(path) });
+}
+export async function configureRsiSetup(args, ports = rsiSetupPorts) {
+    return withDshHomeLifecycleLock(args.dshHome, () => configureRsiSetupLocked(args, ports));
 }
-export async function configureRsiSetup(args, ports = defaultPorts) {
+/** Internal installer entry: caller already owns the DSH_HOME lifecycle lock. */
+export async function configureRsiSetupLocked(args, ports = rsiSetupPorts) {
+    if (args.prepareLocalUpdate || args.installLocalCohort || args.bundles || args.installOwner || args.prepareSource || args.prepareBuild || args.prepareAuthorities || args.optionalBuild || args.dockerPath || args.profile || args.sourceRepository)
+        fail('resource preparation is a separate setup operation');
     if (args.rollback && (args.apply || args.start) || args.start && !args.apply)
         fail('incompatible setup operations');
     const home = args.dshHome;
@@ -269,7 +538,7 @@ export async function configureRsiSetup(args, ports = defaultPorts) {
     const manifestBytes = await readOwnedFile(args.manifestPath);
     const manifest = JSON.parse(manifestBytes);
     const pair = profiles(manifest);
-    return withDshHomeLifecycleLock(home, async () => {
+    return (async () => {
         for (const profile of pair)
             await safeDirectory(join(home, 'profiles', profile));
         const journalPath = join(home, '.rsi-setup-journal.json');
@@ -283,7 +552,7 @@ export async function configureRsiSetup(args, ports = defaultPorts) {
         if (args.rollback) {
             if (!previous)
                 fail('no setup journal to roll back');
-            await rollback(home, journalPath, previous);
+            await rollback(home, journalPath, previous, ports);
             return { mode: 'rolled-back', profiles: pair };
         }
         if (previous?.stage === 'prepared')
@@ -298,50 +567,90 @@ export async function configureRsiSetup(args, ports = defaultPorts) {
         const input = { manifest, dshHome: home, targetPatch: original[0], coordinatorPatch: original[1],
             targetEffective: effective[0], coordinatorEffective: effective[1], coordinatorBase, owner };
         const compiled = await ports.compile(input);
-        await ports.validateAuthorities(manifest, owner);
+        const inventories = await captureRsiAutomationInventories(ports.automationInventory, effective[0], effective[1], home, pair[1]);
+        if (args.expectedAutomationInventories && !isDeepStrictEqual(inventories, args.expectedAutomationInventories))
+            fail('Automation inventory changed since installer preflight');
+        assertRsiSchedulerActivation(inventories, args.ackExistingAutomations === true);
+        const originalEnvironments = await Promise.all(pair.map(profile => readOptionalFile(rsiServiceEnvironmentPath(home, profile))));
+        const environments = await ports.resolveEnvironments(manifest, home);
+        const originalUnits = environments ? await Promise.all(pair.map(profile => readOptionalFile(ports.serviceUnitPath(profile, home), false))) : undefined;
+        const nextUnits = environments ? await Promise.all(pair.map((profile, index) => ports.renderServiceUnit(profile, home, index === 0 ? environments.target : environments.coordinator))) : undefined;
+        await ports.validateAuthorities(manifest, owner, environments?.target);
         if (!args.apply)
             return { mode: 'checked', profiles: pair };
         if (await readOwnedFile(args.manifestPath) !== manifestBytes || await ports.base(pair[1], home) !== coordinatorBase
             || !isDeepStrictEqual(snapshot, await ports.snapshot(effective[0], home)))
             fail('manifest or owner snapshot changed before write');
+        if (!isDeepStrictEqual(inventories, await captureRsiAutomationInventories(ports.automationInventory, effective[0], effective[1], home, pair[1])))
+            fail('Automation inventory changed before write');
         for (let i = 0; i < pair.length; i++) {
             ports.assertStopped(pair[i]);
             if (await readOwnedFile(patchPath(home, pair[i]), false) !== original[i])
                 fail('profile changed before write');
+            if (environments && (await readOptionalFile(rsiServiceEnvironmentPath(home, pair[i])) !== originalEnvironments[i]
+                || await readOptionalFile(ports.serviceUnitPath(pair[i], home), false) !== originalUnits[i]))
+                fail('service resource changed before write');
         }
         const next = [compiled.targetPatch, compiled.coordinatorPatch];
         if (previous && previous.entries.some((entry, i) => entry.after !== original[i]))
             fail('profile changed since previous setup; reconcile its journal first');
-        const journal = { schemaVersion: 1, manifestDigest: digest(manifestBytes), stage: 'prepared',
-            entries: pair.map((profile, i) => ({ profile, before: original[i], after: next[i] })) };
+        const journal = { schemaVersion: environments ? 2 : 1, manifestDigest: digest(manifestBytes), stage: 'prepared',
+            entries: pair.map((profile, i) => ({ profile, before: original[i], after: next[i] })),
+            ...(environments ? {
+                environments: pair.map((profile, i) => ({ profile, before: originalEnvironments[i], after: JSON.stringify({ schemaVersion: 1,
+                        dshHome: home, profile, environment: i === 0 ? environments.target : environments.coordinator }) + '\n' })),
+                units: pair.map((profile, i) => ({ profile, before: originalUnits[i], after: nextUnits[i] })),
+            } : {}) };
+        if (previous)
+            for (const entry of auxiliary(home, previous, ports)) {
+                if (await readOptionalFile(entry.path, entry.privateFile) !== entry.after)
+                    fail('service resource changed since previous setup; reconcile its journal first');
+            }
         if (Buffer.byteLength(JSON.stringify(journal)) > MAX_BYTES)
             fail('combined profile journal exceeds setup size limit');
-        const unchanged = next.every((value, i) => value === original[i]);
+        const unchanged = next.every((value, i) => value === original[i]) && auxiliary(home, journal, ports).every(entry => entry.before === entry.after);
         if (unchanged)
             for (let i = 0; i < pair.length; i++)
                 assertRsiEffectivePatch(next[i], effective[i]);
         if (!unchanged) {
+            for (const entry of auxiliary(home, journal, ports)) {
+                await mkdir(dirname(entry.path), { recursive: true, mode: 0o700 });
+                await safeDirectory(dirname(entry.path));
+                if (entry.privateFile && ((await lstat(dirname(entry.path))).mode & 0o077) !== 0)
+                    fail('service environment directory must be private');
+            }
             await atomicWrite(journalPath, JSON.stringify(journal));
             try {
                 for (const entry of journal.entries)
                     await atomicWrite(patchPath(home, entry.profile), entry.after);
+                for (const entry of auxiliary(home, journal, ports))
+                    await writeOptionalFile(entry.path, entry.after);
                 const final = pair.map(profile => ports.dump(profile, home));
                 for (let i = 0; i < pair.length; i++)
                     assertRsiEffectivePatch(next[i], final[i]);
                 const recompiled = await ports.compile({ ...input, targetPatch: next[0], coordinatorPatch: next[1],
                     targetEffective: final[0], coordinatorEffective: final[1] });
-                if (!isDeepStrictEqual(recompiled, compiled))
+                if (!isDeepStrictEqual(patchValue(recompiled.targetPatch, 'recompiled target'), patchValue(compiled.targetPatch, 'compiled target'))
+                    || !isDeepStrictEqual(patchValue(recompiled.coordinatorPatch, 'recompiled coordinator'), patchValue(compiled.coordinatorPatch, 'compiled coordinator')))
                     fail('effective profile differs from the compiled deployment');
+                if (environments) {
+                    ports.reloadServices();
+                    await ports.validateServiceUnits(manifest, environments.target);
+                }
                 journal.stage = 'applied';
                 await atomicWrite(journalPath, JSON.stringify(journal));
             }
             catch (error) {
-                await rollback(home, journalPath, journal);
+                await rollback(home, journalPath, journal, ports);
                 if (previous)
                     await atomicWrite(journalPath, JSON.stringify(previous));
                 throw error;
             }
         }
+        if (unchanged && environments) {
+            ports.reloadServices();
+            await ports.validateServiceUnits(manifest, environments.target);
+        }
         // Starting is explicit and follows successful composition of both profiles.
         // A failed start retains the applied journal; it never rewrites a live Host.
         if (args.start) {
@@ -349,12 +658,130 @@ export async function configureRsiSetup(args, ports = defaultPorts) {
             await ports.start(pair[0], home);
         }
         return { mode: args.start ? 'services-started' : 'configured', profiles: pair };
-    });
+    })();
 }
 export async function runRsiSetup(argv = process.argv.slice(2)) {
     const args = parseRsiSetupArgs(argv);
     if (args.help) {
-        process.stdout.write('Usage: dsh-rsi-setup --manifest <private.json> [--dsh-home <absolute>] [--apply --confirm-hosts-stopped [--start] | --rollback --confirm-hosts-stopped]\nDefault: validate installed profiles and finite authority configuration without changing profiles.\n');
+        process.stdout.write('Usage: dsh-rsi-setup --manifest <private.json> [--dsh-home <absolute>] [--apply --confirm-hosts-stopped [--ack-existing-automations] [--start] | --rollback --confirm-hosts-stopped]\n       dsh-rsi-setup --prepare-source --profile <name> [--dsh-home <absolute>] [--source-repository <local-absolute>]\n       dsh-rsi-setup --prepare-build --profile <name> [--dsh-home <absolute>] [--source-repository <local-absolute>] [--docker-path <absolute>] [--optional-build]\n       dsh-rsi-setup --prepare-authorities --profile <name> [--dsh-home <absolute>]\n       dsh-rsi-setup --install-owner --profile <name> [--dsh-home <absolute>] [--source-repository <local-absolute>] [--ack-existing-automations]\n       dsh-rsi-setup --install-local-cohort --profile <name> --source-repository <local-absolute> --bundle <slug> [--bundle <slug> ...] [--dsh-home <absolute>]\n--ack-existing-automations acknowledges active or paused durable rows when enabling or switching an Automation scheduler; accepted only with --install-owner or --apply, and does not bypass inventory drift checks.\nDefault: validate installed profiles and finite authority configuration without changing profiles.\nSource preparation creates a private checkout and release repository for the installed version. Build preparation also prepares private authority tools, signing identities and local release storage on Linux, creates an offline image and exports a pinned native release toolchain/store/cache; --optional-build reports which build prerequisites are unavailable. Authority preparation alone needs neither Docker nor a source checkout and does not issue grants or start Hosts.\n');
+        process.stdout.write('       dsh-rsi-setup --prepare-local-update --profile <name> [--dsh-home <absolute>] [--source-repository <local-absolute>] [--add-memory-learning]\nPrepare local update source and tarballs outside the active Home; does not install or activate them. --add-memory-learning explicitly prepares the disabled learner bundle for a verified pre-owner installation.\n');
+        return;
+    }
+    if (args.prepareLocalUpdate) {
+        const controller = new AbortController();
+        const cancel = () => controller.abort(new Error('local update preparation interrupted'));
+        process.on('SIGINT', cancel);
+        process.on('SIGTERM', cancel);
+        try {
+            const { prepareRsiLocalUpdate } = await import('./rsi-local-update.js');
+            const { readRsiLocalCohort } = await import('./rsi-local-cohort.js');
+            const sourceRepository = args.sourceRepository ?? (await readRsiLocalCohort({ dshHome: args.dshHome, profile: args.profile })).sourceRepository;
+            const prepared = await prepareRsiLocalUpdate({ dshHome: args.dshHome, profile: args.profile, sourceRepository,
+                ...(args.addMemoryLearning ? { rootExtension: 'memory-learning' } : {}), signal: controller.signal });
+            process.stdout.write(`${JSON.stringify({ mode: prepared.mode, root: prepared.root, profile: prepared.profile,
+                sourceCommit: prepared.source.sourceCommit, version: prepared.cohort.version,
+                packages: prepared.cohort.packages.length, receiptDigest: prepared.receiptDigest,
+                ...(prepared.extension ? { extension: prepared.extension } : {}) })}\n`);
+        }
+        finally {
+            process.off('SIGINT', cancel);
+            process.off('SIGTERM', cancel);
+        }
+        return;
+    }
+    if (args.installLocalCohort) {
+        const controller = new AbortController();
+        const cancel = () => controller.abort(new Error('local cohort installation interrupted'));
+        process.once('SIGINT', cancel);
+        process.once('SIGTERM', cancel);
+        try {
+            const { installRsiLocalTarget } = await import('./rsi-local-install.js');
+            process.stdout.write(`${JSON.stringify(await installRsiLocalTarget({ dshHome: args.dshHome, profile: args.profile,
+                sourceRepository: args.sourceRepository, bundles: args.bundles, signal: controller.signal }))}\n`);
+        }
+        finally {
+            process.off('SIGINT', cancel);
+            process.off('SIGTERM', cancel);
+        }
+        return;
+    }
+    if (args.installOwner) {
+        if (process.platform !== 'linux') {
+            process.stdout.write(`${JSON.stringify({ mode: 'not-ready', reason: 'automatic dual Host installation requires Linux systemd user services' })}\n`);
+            process.exitCode = 3;
+            return;
+        }
+        const controller = new AbortController();
+        const cancel = () => controller.abort(new Error('owner installation interrupted'));
+        process.once('SIGINT', cancel);
+        process.once('SIGTERM', cancel);
+        try {
+            const { installRsiOwnerDeployment } = await import('./rsi-install.js');
+            const result = await installRsiOwnerDeployment({ dshHome: args.dshHome, profile: args.profile,
+                sourceRepository: args.sourceRepository, ackExistingAutomations: args.ackExistingAutomations, signal: controller.signal });
+            process.stdout.write(`${JSON.stringify(result)}\n`);
+            process.stderr.write(result.mode === 'ready' ? '自迭代双 Host 已启动并通过就绪检查。\n'
+                : `普通 supervised 安装已保留；自迭代双 Host 未就绪：${result.reason}。\n`);
+            if (result.mode === 'not-ready')
+                process.exitCode = 3;
+        }
+        finally {
+            process.off('SIGINT', cancel);
+            process.off('SIGTERM', cancel);
+        }
+        return;
+    }
+    if (args.prepareSource || args.prepareBuild || args.prepareAuthorities) {
+        await safeDirectory(args.dshHome);
+        const controller = new AbortController();
+        const cancel = () => controller.abort(new Error('resource preparation interrupted'));
+        process.once('SIGINT', cancel);
+        process.once('SIGTERM', cancel);
+        try {
+            const prepared = await withDshHomeLifecycleLock(args.dshHome, async () => {
+                const authorities = async () => ({
+                    authorityRuntime: await prepareRsiAuthorityRuntime({ dshHome: args.dshHome, profile: args.profile, signal: controller.signal }),
+                    authorityResources: await prepareRsiAuthorityResources({ dshHome: args.dshHome, profile: args.profile, signal: controller.signal }),
+                });
+                if (args.prepareAuthorities)
+                    return authorities();
+                const source = await prepareRsiSourceWorkspace({
+                    dshHome: args.dshHome, profile: args.profile, version, sourceRepository: args.sourceRepository, signal: controller.signal,
+                });
+                if (!args.prepareBuild)
+                    return source;
+                const provisioned = { ...source, ...(process.platform === 'linux' ? await authorities()
+                        : { authorityResourcesUnavailable: 'private authority runtime currently requires Linux' }) };
+                try {
+                    const build = await prepareRsiBuildEnvironment({ dshHome: args.dshHome, profile: args.profile, source,
+                        dockerPath: args.dockerPath, signal: controller.signal });
+                    try {
+                        const release = await prepareRsiReleaseBuildEnvironment({ dshHome: args.dshHome, profile: args.profile,
+                            build, signal: controller.signal });
+                        return { ...provisioned, sourceBuild: build.sourceBuild, releaseBuild: release.releaseBuild };
+                    }
+                    catch (error) {
+                        controller.signal.throwIfAborted();
+                        if (!args.optionalBuild || !(error instanceof RsiReleaseBuildUnavailableError))
+                            throw error;
+                        process.stderr.write(`自迭代发布构建环境未就绪：${error.message}。已保留源码与验证镜像。\n`);
+                        return { ...provisioned, sourceBuild: build.sourceBuild, releaseBuildUnavailable: error.message };
+                    }
+                }
+                catch (error) {
+                    controller.signal.throwIfAborted();
+                    if (!args.optionalBuild || !(error instanceof RsiBuildUnavailableError))
+                        throw error;
+                    process.stderr.write(`自迭代构建环境未就绪：${error.message}。已保留源码准备结果。\n`);
+                    return { ...provisioned, buildUnavailable: error.message };
+                }
+            });
+            process.stdout.write(`${JSON.stringify(prepared)}\n`);
+        }
+        finally {
+            process.off('SIGINT', cancel);
+            process.off('SIGTERM', cancel);
+        }
         return;
     }
     // 平台门控只属于 CLI 外壳：事务逻辑经注入的 ports 隔离 systemctl/服务安装，