@dharma-ai-labs/agent-fabric 0.2.118 → 0.2.120

package/dist/index.js

@@ -17,13 +17,16 @@ import { contentHash, getActiveSkillBundleAuthorization, getExpiredSkillBundleAu
 import { executeTask, FileActionExecutionJournal, FileTaskReceiptStore, providerInstructionsForTask, } from '@dharma-ai-labs/agent-fabric-task-runner';
 import { CLI_USAGE } from './usage.js';
 import { superviseRelay } from './relaySupervisor.js';
-import { disableRelayAutostart, enableRelayAutostart, relayAutostartStatus, startRelayAutostart } from './relayAutostart.js';
+import { repositoryRelayObservationReady, runRegisteredRepositoryRelays, selectRepositoryRelayRegistrations, serializeRelayWork, waitForRelayRefresh } from './repositoryRelaySupervisor.js';
+import { disableRelayAutostart, enableRelayAutostart, inspectOwnedRelayAutostart, relayAutostartStatus, startRelayAutostart, stopRelayAutostart } from './relayAutostart.js';
+import { relayRuntimeObservationReady, upgradeRelayRuntime } from './relayRuntimeUpgrade.js';
 import { assertStudyExactPoll, studyTaskIdFromFlags } from './studyExactTaskSelector.js';
 import { initializeRepositoryKnowledge, readRepositoryKnowledgeSource } from './repositoryKnowledge.js';
 import { inventoryRepositoryPackage, readRepositoryPackageSnapshot, readRepositorySourceBaselineSnapshot, writeRepositoryPackageSnapshot } from './repositoryPackage.js';
 import { validateRepositorySourceAuthorization } from './repositorySourceAuthorization.js';
 import { advanceRepositorySourceBaseline, BlockedRepositorySourceRetry, fetchRepositorySourceAuthorization, recoverPublishedLocalSourceBaseline, RepositorySourceWatcher, scanRepositorySourceChanges, seedRepositorySourceWatcher } from './repositorySourceSync.js';
 import { assertRepositoryInstallerOwnership, writeRepositoryInstallerFile } from './repositoryInstallerFiles.js';
+import { recoverLegacyRepositoryInstaller, selectLegacyInstallerRecoveryWorkspace } from './legacyInstallerRecovery.js';
 import { onboardingResumeCommand, selectDeviceWorkspace, workspaceIdForDevice } from './onboardingWorkspace.js';
 import { receiveRepositoryPackageDelivery } from './repositoryPackageDelivery.js';
 import { selectInstalledRepositoryKnowledge } from './repositoryInstalledKnowledge.js';
@@ -55,7 +58,7 @@ import { openCodexAppServerTransport } from '@dharma-ai-labs/agent-fabric-provid
 import { createNamedSessionTrust, isNamedSessionOwnerReceipt, renewNamedSessionLifetime } from './namedSessionTrust.js';
 import { startNamedCodexThread } from './namedCodexThread.js';
 export { openCooperativeInboxSession } from './cooperativeInboxSession.js';
-const VERSION = '0.2.118';
+const VERSION = '0.2.120';
 const USAGE = CLI_USAGE;
 const execFileAsync = promisify(execFile);
 const LOCAL_PROVIDER_IDS = ['codex', 'claude', 'agy', 'hermes'];
@@ -1302,12 +1305,24 @@ async function registry() {
 }
 async function saveRegistry(items) {
     await mkdir(resolve(dharmaHome(), 'registry'), { recursive: true, mode: 0o700 });
-    await writeFile(workspaceRegistryPath(), `${JSON.stringify(items, null, 2)}\n`, { mode: 0o600 });
+    await writeJsonAtomic(workspaceRegistryPath(), items);
 }
 async function saveWorkspaceRecord(entry) {
-    const items = (await registry()).filter((item) => item.workspaceId !== entry.workspaceId);
-    items.push(entry);
-    await saveRegistry(items);
+    const release = await acquirePidLock(`${workspaceRegistryPath()}.mutation.lock`, 10_000, 'Workspace registry is busy; preserve it for recovery.');
+    try {
+        const value = await readFile(workspaceRegistryPath(), 'utf8').catch(error => {
+            if (error.code === 'ENOENT')
+                return '[]';
+            throw error;
+        });
+        const items = JSON.parse(value);
+        if (!Array.isArray(items))
+            throw new Error('Workspace registry is invalid; preserve it for recovery.');
+        await saveRegistry([...items.filter(item => item.workspaceId !== entry.workspaceId), entry]);
+    }
+    finally {
+        await release();
+    }
 }
 async function gitValue(workspace, argv) {
     try {
@@ -1525,6 +1540,103 @@ async function installStableRepositoryLauncher(workspace) {
     await writeFile(cmdPath, contents.windows, { mode: 0o600 });
     return { shell: '.dharma/bin/dharma', windows: '.dharma/bin/dharma.cmd' };
 }
+async function relayUpgrade(flags) {
+    const config = await readDeviceConfig();
+    if (!config)
+        throw new Error('relay_upgrade_enrollment_required');
+    if (flags.has('dry-run') && flags.has('apply'))
+        throw new Error('relay_upgrade_flags_conflict');
+    const workspace = await realpath(String(flags.get('workspace') || '.'));
+    const selected = selectDeviceWorkspace(await registry(), {
+        organizationId: config.organizationId, deviceId: config.deviceId, path: workspace,
+    });
+    if (!selected)
+        throw new Error('relay_upgrade_workspace_unregistered');
+    const home = dharmaHome();
+    const startup = await inspectOwnedRelayAutostart({ home });
+    const expectedLauncher = resolve(workspace, '.dharma', 'bin', process.platform === 'win32' ? 'dharma.cmd' : 'dharma');
+    if (startup.workspace !== workspace || startup.launcher !== expectedLauncher
+        || startup.policy !== resolve(workspace, '.dharma', 'approved-policy.json')) {
+        throw new Error('relay_upgrade_workspace_conflict');
+    }
+    const assertStopped = async () => {
+        if (await relaySupervisorProcessState(home) !== 'stopped' || await relayProcessState(home) !== 'stopped') {
+            throw new Error('relay_upgrade_runtime_busy: finish current work, then stop the owned relay before upgrading.');
+        }
+        const entries = await readdir(resolve(home, 'sessions'), { withFileTypes: true }).catch(error => {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        });
+        for (const entry of entries) {
+            if (!entry.isDirectory() || !/^[a-z][a-z0-9-]{0,47}$/.test(entry.name))
+                continue;
+            if (await pidProcessState(resolve(home, 'sessions', entry.name, 'service.lock')) !== 'stopped') {
+                throw new Error('relay_upgrade_session_busy: finish and stop the named session before upgrading.');
+            }
+        }
+    };
+    return withRelayStartupMutation(async () => {
+        const receipt = await upgradeRelayRuntime({ home, workspace, version: VERSION,
+            organizationId: config.organizationId, deviceId: config.deviceId, workspaceId: selected.workspaceId,
+            dryRun: !flags.has('apply'), rollback: flags.has('rollback') }, {
+            assertStopped, inspectStartup: async () => {
+                const current = await inspectOwnedRelayAutostart({ home });
+                if (current.launcher !== expectedLauncher || current.policy !== startup.policy
+                    || current.workspace !== workspace)
+                    throw new Error('relay_upgrade_workspace_conflict');
+                return current;
+            },
+            launcherContents: version => stableRepositoryLauncherContents(version, { platform: process.platform, nodeDirectory: dirname(process.execPath) }),
+            legacyLauncherContents: version => stableRepositoryLauncherContents(version),
+            configureStartup: version => enableRelayAutostart({ home, workspace,
+                launcher: startup.launcher, policy: startup.policy, version }),
+            start: () => startRelayAutostart({ home }),
+            stop: async () => {
+                const activationLocks = resolve(home, 'registry', 'skill-activation-locks');
+                const locks = await readdir(activationLocks).catch(error => {
+                    if (error.code === 'ENOENT')
+                        return [];
+                    throw error;
+                });
+                for (const lock of locks) {
+                    if (lock.endsWith('.lock') && await pidProcessState(resolve(activationLocks, lock)) !== 'stopped') {
+                        throw new Error('relay_upgrade_work_in_progress: recovery must wait for a safe task boundary.');
+                    }
+                }
+                const binding = await readFile(resolve(home, 'relay', 'supervisor-workspace.json'), 'utf8')
+                    .then(value => JSON.parse(value)).catch(() => null);
+                if (await relaySupervisorProcessState(home) !== 'stopped'
+                    && binding?.workspaceId !== selected.workspaceId)
+                    throw new Error('relay_upgrade_process_unverified');
+                await stopRelayAutostart({ home });
+                const stopped = await relayStop();
+                if (stopped.ok !== true)
+                    throw new Error('relay_upgrade_stop_unconfirmed');
+            },
+            verify: async (version, since) => {
+                for (let attempt = 0; attempt < 90; attempt++) {
+                    const read = (name) => readFile(resolve(home, 'relay', name), 'utf8').catch(() => 'null');
+                    const supervisorPid = Number((await read('supervisor.pid')).trim());
+                    const relayPid = Number((await read('relay.pid')).trim());
+                    const supervisor = JSON.parse(await read('supervisor-workspace.json'));
+                    const lastPoll = JSON.parse(await read('last-successful-poll.json'));
+                    if (await relaySupervisorProcessState(home) === 'running' && await relayProcessState(home) === 'running'
+                        && relayRuntimeObservationReady({ version, workspaceId: selected.workspaceId, since,
+                            supervisorPid, relayPid, supervisor, lastPoll, allowLegacyPoll: version !== VERSION }))
+                        return;
+                    if (attempt < 89)
+                        await new Promise(resolveWait => setTimeout(resolveWait, 1000));
+                }
+                throw new Error('relay_upgrade_receiver_unconfirmed');
+            },
+        });
+        const validation = await validateContract(resolve(fileURLToPath(new URL('.', import.meta.url)), 'schemas'), 'https://schemas.dharma-ai.io/local-relay-upgrade/v1', receipt);
+        if (!validation.ok)
+            throw new Error('relay_upgrade_receipt_invalid');
+        return receipt;
+    });
+}
 export async function waitForRelayReadiness(options = {}) {
     const processState = options.processState || relayProcessState;
     const probe = options.probe || probeRelayConnection;
@@ -1558,6 +1670,15 @@ export async function waitForRelayReadiness(options = {}) {
     throw new Error(`The outbound relay did not become ready after bootstrap (${reason}).`);
 }
 async function startRelayDaemon(policyPath) {
+    const config = await readDeviceConfig();
+    if (!config)
+        throw new Error('Relay startup requires current device enrollment.');
+    const policy = await loadOrganizationPolicy(policyPath);
+    const workspaceId = policy.serverAuthorization?.workspaceId;
+    const selected = (await registry()).find(row => row.workspaceId === workspaceId
+        && row.organizationId === config.organizationId && resolve(row.path, '.dharma', 'approved-policy.json') === policyPath);
+    if (!selected)
+        throw new Error('Relay policy must belong to this enrolled repository.');
     const alreadyRunning = await relayProcessState() === 'running';
     const supervisorState = await relaySupervisorProcessState();
     if (supervisorState === 'unknown')
@@ -1579,8 +1700,11 @@ async function startRelayDaemon(policyPath) {
             const binding = await readFile(resolve(dharmaHome(), 'relay', 'supervisor-workspace.json'), 'utf8')
                 .then(value => JSON.parse(value)).catch(() => null);
             if (binding?.pid === pid) {
-                if (binding.policyPath !== policyPath) {
-                    throw new Error('relay_workspace_conflict: the active relay supervisor belongs to another workspace.');
+                if (binding.version !== VERSION || !binding.standardRepositories) {
+                    throw new Error('relay_runtime_upgrade_required: safely stop and upgrade the existing startup-anchor relay; do not retarget a working receiver.');
+                }
+                if (binding.organizationId !== config.organizationId || binding.deviceId !== config.deviceId) {
+                    throw new Error('relay_workspace_conflict: the active supervisor belongs to another enrollment.');
                 }
                 supervisorReady = true;
                 break;
@@ -1591,7 +1715,14 @@ async function startRelayDaemon(policyPath) {
     }
     if (!supervisorReady)
         throw new Error('The relay supervisor did not become ready after bootstrap.');
-    const readiness = await waitForRelayReadiness({ expectedVersion: VERSION });
+    const readiness = await waitForRelayReadiness({ expectedVersion: VERSION, attempts: 120, delayMs: 1000, processState: async () => {
+            if (await relayProcessState() !== 'running')
+                return 'stopped';
+            const pid = Number((await readFile(resolve(dharmaHome(), 'relay', 'relay.pid'), 'utf8')).trim());
+            const poll = await readFile(resolve(dharmaHome(), 'relay', 'repositories', selected.workspaceId, 'last-successful-poll.json'), 'utf8').then(value => JSON.parse(value)).catch(() => null);
+            return repositoryRelayObservationReady({ observation: poll, workspaceId: selected.workspaceId,
+                version: VERSION, pid }) ? 'running' : 'stopped';
+        } });
     return { started: !alreadyRunning, supervisor: 'running', ...readiness };
 }
 async function supervisedDemoCycle(registration, signal) {
@@ -1654,7 +1785,8 @@ async function relaySupervise(flags) {
     const health = createDemoWatchHealthRecorder({ home: dharmaHome(), pid: process.pid, version: VERSION });
     try {
         await writeJsonAtomic(bindingPath, { pid: process.pid, workspaceId: selectedWorkspace?.workspaceId ?? null,
-            policyPath, demoWatches: true, version: VERSION });
+            policyPath, demoWatches: true, version: VERSION, standardRepositories: Boolean(policyPath),
+            organizationId: config?.organizationId ?? null, deviceId: config?.deviceId ?? null });
         const demo = runDemoSupervisor({ signal: controller.signal,
             list: () => listDemoWatchRegistrations(dharmaHome()), cycle: (registration, signal) => {
                 if (!health.available(demoWatchRegistrationKey(registration))) {
@@ -1969,6 +2101,33 @@ async function bootstrap(flags) {
         });
         scopes = redeemed.organizationApiTokenScopes;
     }
+    let organizationApiTokenStored = false;
+    let credentialFailure = null;
+    try {
+        organizationApiTokenStored = Boolean(await loadOrganizationApiToken({
+            hqUrl, organizationId, installationId: config.installationId,
+        }));
+        if (!organizationApiTokenStored && !String(process.env.DHARMA_ORG_API_TOKEN || '').trim()) {
+            credentialFailure = 'organization_api_credentials_required';
+        }
+    }
+    catch {
+        // Secure-store diagnostics can contain secrets. Emit only the failed stage.
+        credentialFailure = 'organization_api_credential_store_unavailable';
+    }
+    if (credentialFailure) {
+        return {
+            ok: false,
+            stage: 'organization_api_credentials',
+            code: credentialFailure,
+            message: 'The enrolled device is preserved, but its organization API credential is unavailable. Contact Dharma support for device-bound credential recovery; do not repeat enrollment or use another member\'s token.',
+            sharedRepositoryReady: false,
+            enrollment: {
+                organizationId, deviceId: config.deviceId, status: 'approved', organizationApiTokenStored,
+                scopes, recipientApproval, rebind,
+            },
+        };
+    }
     const onboardFlags = new Map(flags);
     onboardFlags.delete('grant');
     onboardFlags.set('portal-url', hqUrl);
@@ -1987,7 +2146,7 @@ async function bootstrap(flags) {
                 organizationId,
                 deviceId: config.deviceId,
                 status: 'approved',
-                organizationApiTokenStored: true,
+                organizationApiTokenStored,
                 scopes,
                 recipientApproval,
                 rebind,
@@ -1998,11 +2157,36 @@ async function bootstrap(flags) {
     const launcher = await installStableRepositoryLauncher(workspace);
     const autostart = flags.has('no-relay-daemon')
         ? { state: 'disabled', backend: null }
-        : await withOnboardingStage('autostart', String(onboarded.workspaceId || ''), `dharma bootstrap --resume --complete --portal-url ${hqUrl} --organization-id ${organizationId} --workspace . --policy-revision ${policyRevision}`, () => withRelayStartupMutation(() => enableRelayAutostart({
-            home: dharmaHome(), workspace, policy: resolve(workspace, '.dharma', 'approved-policy.json'),
-            launcher: resolve(workspace, process.platform === 'win32' ? launcher.windows : launcher.shell),
-            version: VERSION,
-        })));
+        : await withOnboardingStage('autostart', String(onboarded.workspaceId || ''), `dharma bootstrap --resume --complete --portal-url ${hqUrl} --organization-id ${organizationId} --workspace . --policy-revision ${policyRevision}`, () => withRelayStartupMutation(async () => {
+            const home = dharmaHome();
+            const existing = await relayAutostartStatus({ home });
+            if (existing.backend !== null || existing.state !== 'disabled') {
+                const anchor = await inspectOwnedRelayAutostart({ home });
+                if (anchor.policy !== null) {
+                    const current = await readDeviceConfig();
+                    if (!current || current.organizationId !== organizationId || current.deviceId !== config.deviceId) {
+                        throw new Error('relay_workspace_conflict: startup enrollment changed.');
+                    }
+                    const selected = selectDeviceWorkspace(await registry(), { organizationId,
+                        deviceId: config.deviceId, path: anchor.workspace });
+                    if (!selected)
+                        throw new Error('relay_workspace_conflict: startup anchor is not registered to this device.');
+                    if (anchor.policy !== resolve(anchor.workspace, '.dharma', 'approved-policy.json')) {
+                        throw new Error('relay_workspace_conflict: startup policy is not canonical.');
+                    }
+                    const authorized = await loadOrganizationPolicy(anchor.policy);
+                    const canonical = (await registry()).filter(row => row.workspaceId === authorized.serverAuthorization?.workspaceId
+                        && row.organizationId === organizationId && row.path === anchor.workspace
+                        && row.routeHash === selected.routeHash && row.repositoryRemoteHash === selected.repositoryRemoteHash);
+                    if (canonical.length !== 1)
+                        throw new Error('relay_workspace_conflict: startup policy route changed.');
+                    await loadVerifiedWorkspacePolicy(anchor.policy, authorized.serverAuthorization?.workspaceId ?? '');
+                }
+            }
+            return enableRelayAutostart({ home, workspace, policy: resolve(workspace, '.dharma', 'approved-policy.json'),
+                launcher: resolve(workspace, process.platform === 'win32' ? launcher.windows : launcher.shell),
+                version: VERSION, preserveStandardAnchor: true });
+        }));
     let sharedRepositoryReady = onboarded.sharedRepositoryReady === true;
     const completionRequested = flags.has('complete');
     if (!completionRequested) {
@@ -2015,7 +2199,7 @@ async function bootstrap(flags) {
                 organizationId,
                 deviceId: config.deviceId,
                 status: 'approved',
-                organizationApiTokenStored: true,
+                organizationApiTokenStored,
                 scopes,
                 recipientApproval,
                 rebind,
@@ -2106,7 +2290,7 @@ async function bootstrap(flags) {
             organizationId,
             deviceId: config.deviceId,
             status: 'approved',
-            organizationApiTokenStored: true,
+            organizationApiTokenStored,
             scopes,
             recipientApproval,
             rebind,
@@ -2791,8 +2975,18 @@ async function evidencePreview(flags) {
                 captureProvenance: captureProvenance(session.endedAt),
             });
         });
+        const disclosureFailures = capsules.map((capsule) => {
+            try {
+                return containsDisallowedLocalPath(capsule) ? 'local_path_disclosure_forbidden' : null;
+            }
+            catch {
+                return 'local_path_inspection_depth_exceeded';
+            }
+        }).filter((reason) => reason !== null);
         automaticDisclosure = {
-            ready: true,
+            ready: disclosureFailures.length === 0,
+            blockedCapsuleCount: disclosureFailures.length,
+            reasonCodes: [...new Set(disclosureFailures)].sort(),
             disclosureClass: 'automatic_capsule',
             disclosureMode: capsules[0]?.automaticDisclosureMode ?? policy.evidence.automaticDisclosure?.mode ?? 'local_analysis',
             consentReceiptId: policy.evidence.automaticDisclosure?.consentReceiptId ?? null,
@@ -3750,6 +3944,38 @@ The CLI enrolls this device through browser-confirmed Clerk organization consent
         knowledge,
     };
 }
+async function repositoryInstallerRecoveryCommand(flags) {
+    if (flags.has('apply') === flags.has('dry-run'))
+        throw new Error('Choose exactly one of --apply or --dry-run.');
+    const fromWorkspaceId = required(flags, 'from-workspace-id');
+    const workspaceId = required(flags, 'workspace-id');
+    const workspace = await realpath(String(flags.get('workspace') || '.'));
+    const organizationId = required(flags, 'organization-id');
+    const config = await readDeviceConfig();
+    if (!config || config.organizationId !== organizationId)
+        throw new Error('Recovery requires current organization enrollment.');
+    await loadDeviceEnrollmentAnchor({ config });
+    const identity = await preflightBootstrapWorkspaceIdentity(workspace);
+    const registered = selectLegacyInstallerRecoveryWorkspace(await registry(), { organizationId, deviceId: config.deviceId,
+        path: workspace, repositoryRemoteHash: identity.fingerprint, workspaceId });
+    const repositoryAgentKey = `repo:${identity.fingerprint.slice('sha256:'.length, 'sha256:'.length + 24)}`;
+    if (!registered?.repositoryBindingId || !registered.repositoryAgentId
+        || registered.repositoryAgentKey !== repositoryAgentKey) {
+        throw new Error('Recovery requires the enrolled device canonical repository binding.');
+    }
+    const policy = await loadVerifiedWorkspacePolicy(resolve(workspace, '.dharma', 'approved-policy.json'), registered.workspaceId);
+    if (policy.organizationId !== organizationId || policy.serverAuthorization?.workspaceId !== registered.workspaceId) {
+        throw new Error('Recovery requires a current signed workspace policy.');
+    }
+    await assertWorkspaceAuthorizationCurrent(registered.workspaceId, policy.serverAuthorization);
+    const scope = { organizationId, workspaceId: registered.workspaceId,
+        repositoryBindingId: registered.repositoryBindingId, repositoryAgentId: registered.repositoryAgentId };
+    validateRepositorySourceAuthorization(await fetchRepositorySourceAuthorization(await client(), scope), scope, new Date());
+    const recovery = await recoverLegacyRepositoryInstaller({ workspace, fromWorkspaceId,
+        workspaceId: registered.workspaceId, repositoryAgentKey, apply: flags.has('apply') });
+    return { ok: true, dryRun: !recovery.applied, serverMutation: false, recovery,
+        nextAction: 'Resume pinned onboarding; recovery is not signed skill installation or activation.' };
+}
 async function repositorySnapshotCommand(flags, outputs) {
     if (flags.has('apply') && flags.has('dry-run'))
         throw new Error('Choose --apply or --dry-run, not both.');
@@ -5837,6 +6063,52 @@ async function takeCachedSkillUpdate(input) {
     }
 }
 async function relayStart(flags) {
+    const anchor = resolve(required(flags, 'policy'));
+    const config = await readDeviceConfig();
+    if (!config)
+        throw new Error('Relay requires current enrollment.');
+    const declared = await loadOrganizationPolicy(anchor);
+    const rows = await registry();
+    const selected = rows.find(row => row.workspaceId === declared.serverAuthorization?.workspaceId
+        && row.organizationId === config.organizationId && resolve(row.path, '.dharma', 'approved-policy.json') === anchor);
+    if (!selected)
+        throw new Error('Relay policy must be the canonical policy of one registered workspace.');
+    const authorized = await selectRepositoryRelayRegistrations(rows, config, loadOrganizationPolicy);
+    if (!authorized.some(row => row.workspaceId === selected.workspaceId && row.policyPath === anchor)) {
+        throw new Error('Relay policy is not registered to this enrolled device.');
+    }
+    await loadVerifiedWorkspacePolicy(anchor, selected.workspaceId);
+    const release = await acquireRelayProcessLease();
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    const serialized = serializeRelayWork();
+    try {
+        if (flags.has('once'))
+            return await relayWorkspaceLoop(flags, controller.signal, serialized);
+        await runRegisteredRepositoryRelays({ signal: controller.signal, list: async () => {
+                const currentConfig = await readDeviceConfig();
+                if (currentConfig?.organizationId !== config.organizationId || currentConfig.deviceId !== config.deviceId) {
+                    throw new Error('Relay enrollment changed.');
+                }
+                const records = JSON.parse(await readFile(workspaceRegistryPath(), 'utf8'));
+                if (!Array.isArray(records))
+                    throw new Error('Invalid workspace registry.');
+                return selectRepositoryRelayRegistrations(records, config, loadOrganizationPolicy);
+            }, run: (row, signal) => relayWorkspaceLoop(new Map([...flags, ['policy', row.policyPath]]), signal, serialized),
+            observe: event => process.stderr.write(`${JSON.stringify({ event: 'repository_relay', ...event })}\n`) });
+        return { ok: true, stopped: true };
+    }
+    finally {
+        controller.abort();
+        process.removeListener('SIGINT', stop);
+        process.removeListener('SIGTERM', stop);
+        await release();
+    }
+}
+async function relayWorkspaceLoop(flags, signal, serialized) {
+    signal.throwIfAborted();
     const policyPath = resolve(required(flags, 'policy'));
     const declaredPolicy = await loadOrganizationPolicy(policyPath);
     const declaredWorkspaceId = declaredPolicy.serverAuthorization?.workspaceId;
@@ -5851,400 +6123,411 @@ async function relayStart(flags) {
     }
     let canonicalWorkspace = selectedWorkspace;
     let policy = await loadVerifiedWorkspacePolicy(policyPath, canonicalWorkspace.workspaceId);
+    signal.throwIfAborted();
     const fabric = await client();
     const leaseSeconds = Number(flags.get('lease-seconds') || 120);
     const pollMs = Math.min(Math.max(Number(flags.get('poll-seconds') || 3), 1), 60) * 1_000;
-    const releaseRelayLease = await acquireRelayProcessLease();
-    try {
-        let stopping = false;
-        let stopPreparation;
-        const stop = () => { stopping = true; stopPreparation?.(); };
-        process.once('SIGINT', stop);
-        process.once('SIGTERM', stop);
-        let tasksCompleted = 0;
-        let lastProviderFailureCategory = null;
-        let taskTrajectoriesRecovered = 0;
-        let evidenceResponsesCompleted = 0;
-        let trajectorySyncsCompleted = 0;
-        let nextPolicyRefreshAt = 0;
-        let lastPollReceiptAt = 0;
-        let evidencePolicyFresh = false;
-        const repositorySourceWatcher = new RepositorySourceWatcher();
-        const blockedRepositorySourceRetry = new BlockedRepositorySourceRetry();
-        let repositorySourceBaselineAvailable = true;
-        let publishedLocalSnapshotHash = canonicalWorkspace.repositoryPackage?.publishedLocalSnapshotHash
-            || (canonicalWorkspace.repositoryPackage?.state === 'published'
-                && canonicalWorkspace.repositoryPackage.snapshotHash === canonicalWorkspace.repositoryPackage.localBaselineSnapshotHash
-                ? canonicalWorkspace.repositoryPackage.snapshotHash : null);
-        if (canonicalWorkspace.repositoryPackage && canonicalWorkspace.repositoryBindingId && canonicalWorkspace.repositoryAgentId) {
-            try {
-                const recovered = await recoverPublishedLocalSourceBaseline({
-                    workspace: canonicalWorkspace.path, organizationId: canonicalWorkspace.organizationId,
-                    workspaceId: canonicalWorkspace.workspaceId, repositoryBindingId: canonicalWorkspace.repositoryBindingId,
-                    repositoryAgentId: canonicalWorkspace.repositoryAgentId, record: canonicalWorkspace.repositoryPackage,
-                });
-                if (recovered && recovered !== publishedLocalSnapshotHash) {
-                    publishedLocalSnapshotHash = recovered;
-                    canonicalWorkspace = { ...canonicalWorkspace, repositoryPackage: {
-                            ...canonicalWorkspace.repositoryPackage, localBaselineSnapshotHash: recovered,
-                            publishedLocalSnapshotHash: recovered,
-                        } };
-                    await saveWorkspaceRecord(canonicalWorkspace);
-                }
-            }
-            catch {
-                repositorySourceBaselineAvailable = false;
+    let stopping = signal.aborted;
+    let stopPreparation;
+    const stop = () => { stopping = true; stopPreparation?.(); };
+    let tasksCompleted = 0;
+    let lastProviderFailureCategory = null;
+    let taskTrajectoriesRecovered = 0;
+    let evidenceResponsesCompleted = 0;
+    let trajectorySyncsCompleted = 0;
+    let nextPolicyRefreshAt = 0;
+    let lastPollReceiptAt = 0;
+    let evidencePolicyFresh = false;
+    const repositorySourceWatcher = new RepositorySourceWatcher();
+    const blockedRepositorySourceRetry = new BlockedRepositorySourceRetry();
+    let repositorySourceBaselineAvailable = true;
+    let publishedLocalSnapshotHash = canonicalWorkspace.repositoryPackage?.publishedLocalSnapshotHash
+        || (canonicalWorkspace.repositoryPackage?.state === 'published'
+            && canonicalWorkspace.repositoryPackage.snapshotHash === canonicalWorkspace.repositoryPackage.localBaselineSnapshotHash
+            ? canonicalWorkspace.repositoryPackage.snapshotHash : null);
+    if (canonicalWorkspace.repositoryPackage && canonicalWorkspace.repositoryBindingId && canonicalWorkspace.repositoryAgentId) {
+        try {
+            const recovered = await recoverPublishedLocalSourceBaseline({
+                workspace: canonicalWorkspace.path, organizationId: canonicalWorkspace.organizationId,
+                workspaceId: canonicalWorkspace.workspaceId, repositoryBindingId: canonicalWorkspace.repositoryBindingId,
+                repositoryAgentId: canonicalWorkspace.repositoryAgentId, record: canonicalWorkspace.repositoryPackage,
+            });
+            if (recovered && recovered !== publishedLocalSnapshotHash) {
+                publishedLocalSnapshotHash = recovered;
+                canonicalWorkspace = { ...canonicalWorkspace, repositoryPackage: {
+                        ...canonicalWorkspace.repositoryPackage, localBaselineSnapshotHash: recovered,
+                        publishedLocalSnapshotHash: recovered,
+                    } };
+                await saveWorkspaceRecord(canonicalWorkspace);
             }
         }
-        if (publishedLocalSnapshotHash) {
-            try {
-                await readRepositoryPackageSnapshot(canonicalWorkspace.path, publishedLocalSnapshotHash);
-                const localHash = canonicalWorkspace.repositoryPackage?.localBaselineSnapshotHash;
-                if (localHash && (localHash === publishedLocalSnapshotHash
-                    || canonicalWorkspace.repositoryPackage?.pendingLocalSnapshotHash === localHash)) {
-                    await seedRepositorySourceWatcher({ workspace: canonicalWorkspace.path,
-                        organizationId: canonicalWorkspace.organizationId, workspaceId: canonicalWorkspace.workspaceId,
-                        repositoryBindingId: canonicalWorkspace.repositoryBindingId,
-                        repositoryAgentId: canonicalWorkspace.repositoryAgentId,
-                        publishedHash: publishedLocalSnapshotHash,
-                        localHash,
-                        watcher: repositorySourceWatcher });
-                }
-            }
-            catch {
-                repositorySourceBaselineAvailable = false;
+        catch {
+            repositorySourceBaselineAvailable = false;
+        }
+    }
+    if (publishedLocalSnapshotHash) {
+        try {
+            await readRepositoryPackageSnapshot(canonicalWorkspace.path, publishedLocalSnapshotHash);
+            const localHash = canonicalWorkspace.repositoryPackage?.localBaselineSnapshotHash;
+            if (localHash && (localHash === publishedLocalSnapshotHash
+                || canonicalWorkspace.repositoryPackage?.pendingLocalSnapshotHash === localHash)) {
+                await seedRepositorySourceWatcher({ workspace: canonicalWorkspace.path,
+                    organizationId: canonicalWorkspace.organizationId, workspaceId: canonicalWorkspace.workspaceId,
+                    repositoryBindingId: canonicalWorkspace.repositoryBindingId,
+                    repositoryAgentId: canonicalWorkspace.repositoryAgentId,
+                    publishedHash: publishedLocalSnapshotHash,
+                    localHash,
+                    watcher: repositorySourceWatcher });
             }
         }
-        let nextRepositorySourceScanAt = 0;
-        let repositorySourceCandidates = 0;
-        let repositorySourceFailures = 0;
-        let repositorySourceState = 'not_scanned';
-        let sourceScanFlight = null;
-        let sourceScanReady = null;
-        const { LocalVault, loadOrCreateVaultMasterKey } = await loadVaultModule();
-        const vault = await LocalVault.open({
-            root: resolve(dharmaHome(), 'vault'),
-            masterKey: await loadOrCreateVaultMasterKey(),
-            rawLocalDays: rawLocalRetentionDays(policy),
-        });
-        let skillPreparationsCompleted = 0;
-        let skillPreparationFailures = 0;
-        let skillActivationsCompleted = 0;
-        let skillActivationFailures = 0;
-        const skillActivationFailuresByProvider = {};
-        let nextSkillActivationAt = 0;
-        const skillPreparationPump = startSkillPreparationPump({
-            prepare: async (assertRunning) => {
-                await prepareProvidersIndependently(providerAdapters, assertRunning, async (adapter) => {
-                    assertRunning();
-                    const capability = await adapter.capability();
-                    assertRunning();
-                    if (capability.skillInstall === 'unavailable' || !isLocalProviderId(adapter.providerId))
+        catch {
+            repositorySourceBaselineAvailable = false;
+        }
+    }
+    let nextRepositorySourceScanAt = 0;
+    let repositorySourceCandidates = 0;
+    let repositorySourceFailures = 0;
+    let repositorySourceState = 'not_scanned';
+    let sourceScanFlight = null;
+    let sourceScanReady = null;
+    const { LocalVault, loadOrCreateVaultMasterKey } = await loadVaultModule();
+    const vault = await LocalVault.open({
+        root: resolve(dharmaHome(), 'vault'),
+        masterKey: await loadOrCreateVaultMasterKey(),
+        rawLocalDays: rawLocalRetentionDays(policy),
+    });
+    if (signal.aborted)
+        vault.close();
+    signal.throwIfAborted();
+    signal.addEventListener('abort', stop, { once: true });
+    if (signal.aborted)
+        stop();
+    let skillPreparationsCompleted = 0;
+    let skillPreparationFailures = 0;
+    let skillActivationsCompleted = 0;
+    let skillActivationFailures = 0;
+    const skillActivationFailuresByProvider = {};
+    let nextSkillActivationAt = 0;
+    const skillPreparationPump = startSkillPreparationPump({
+        prepare: async (assertRunning) => {
+            await prepareProvidersIndependently(providerAdapters, assertRunning, async (adapter) => {
+                assertRunning();
+                const capability = await adapter.capability();
+                assertRunning();
+                if (capability.skillInstall === 'unavailable' || !isLocalProviderId(adapter.providerId))
+                    return;
+                const provider = adapter.providerId;
+                await withSkillPreparationTransaction({ home: dharmaHome(), workspaceId: canonicalWorkspace.workspaceId,
+                    provider, assertCurrent: assertRunning }, async () => {
+                    const prepared = await prepareSkillUpdate({ workspaceId: canonicalWorkspace.workspaceId,
+                        provider, policyPath, fabric, automatic: true, assertRunning });
+                    if (!prepared) {
+                        assertRunning();
                         return;
-                    const provider = adapter.providerId;
-                    await withSkillPreparationTransaction({ home: dharmaHome(), workspaceId: canonicalWorkspace.workspaceId,
-                        provider, assertCurrent: assertRunning }, async () => {
-                        const prepared = await prepareSkillUpdate({ workspaceId: canonicalWorkspace.workspaceId,
-                            provider, policyPath, fabric, automatic: true, assertRunning });
-                        if (!prepared) {
-                            assertRunning();
-                            return;
-                        }
-                        let retained = false;
-                        try {
-                            prepared.assertCurrent();
-                            const repositoryAgentId = prepared.workspace.repositoryAgentId;
-                            if (!repositoryAgentId)
-                                throw new Error('Preparation cache requires an enrolled repository agent.');
-                            const pendingRecord = await serializeSkillPreparationRecord({
-                                schema: 'dharma.skill-preparation/v1', organizationId: prepared.config.organizationId,
-                                deviceId: prepared.config.deviceId, workspaceId: prepared.workspace.workspaceId,
+                    }
+                    let retained = false;
+                    try {
+                        prepared.assertCurrent();
+                        const repositoryAgentId = prepared.workspace.repositoryAgentId;
+                        if (!repositoryAgentId)
+                            throw new Error('Preparation cache requires an enrolled repository agent.');
+                        const pendingRecord = await serializeSkillPreparationRecord({
+                            schema: 'dharma.skill-preparation/v1', organizationId: prepared.config.organizationId,
+                            deviceId: prepared.config.deviceId, workspaceId: prepared.workspace.workspaceId,
+                            repositoryAgentId,
+                            repositoryBindingId: prepared.workspace.repositoryBindingId ?? null, provider,
+                            policyHash: sha256(canonicalize(prepared.policy)), rolloutId: prepared.rollout.id,
+                            bundle: prepared.bundle, repositoryPackage: prepared.repositoryDelivery
+                                ? { envelope: prepared.repositoryDelivery.envelope, index: prepared.repositoryDelivery.index } : null,
+                            preparedAt: new Date().toISOString(), activationAuthorized: false,
+                        });
+                        prepared.assertCurrent();
+                        await writeFile(resolve(prepared.sourceRoot, 'PREPARED.json'), pendingRecord, { mode: 0o600, flag: 'wx' });
+                        prepared.assertCurrent();
+                        await publishSkillPreparationCache({ home: dharmaHome(), workspaceId: canonicalWorkspace.workspaceId,
+                            provider, sourceRoot: prepared.sourceRoot, recordBytes: pendingRecord, assertCurrent: prepared.assertCurrent,
+                            expected: { organizationId: prepared.config.organizationId, deviceId: prepared.config.deviceId,
                                 repositoryAgentId,
-                                repositoryBindingId: prepared.workspace.repositoryBindingId ?? null, provider,
+                                repositoryBindingId: prepared.workspace.repositoryBindingId ?? null,
                                 policyHash: sha256(canonicalize(prepared.policy)), rolloutId: prepared.rollout.id,
-                                bundle: prepared.bundle, repositoryPackage: prepared.repositoryDelivery
-                                    ? { envelope: prepared.repositoryDelivery.envelope, index: prepared.repositoryDelivery.index } : null,
-                                preparedAt: new Date().toISOString(), activationAuthorized: false,
-                            });
-                            prepared.assertCurrent();
-                            await writeFile(resolve(prepared.sourceRoot, 'PREPARED.json'), pendingRecord, { mode: 0o600, flag: 'wx' });
-                            prepared.assertCurrent();
-                            await publishSkillPreparationCache({ home: dharmaHome(), workspaceId: canonicalWorkspace.workspaceId,
-                                provider, sourceRoot: prepared.sourceRoot, recordBytes: pendingRecord, assertCurrent: prepared.assertCurrent,
-                                expected: { organizationId: prepared.config.organizationId, deviceId: prepared.config.deviceId,
-                                    repositoryAgentId,
-                                    repositoryBindingId: prepared.workspace.repositoryBindingId ?? null,
-                                    policyHash: sha256(canonicalize(prepared.policy)), rolloutId: prepared.rollout.id,
-                                    bundleId: prepared.bundle.bundleId, bundleHash: prepared.bundle.bundleHash },
-                                onCommitted: () => { retained = true; } });
-                            skillPreparationsCompleted += 1;
-                        }
-                        finally {
-                            if (!retained)
-                                await rm(prepared.sourceRoot, { recursive: true, force: true });
-                        }
-                    });
-                }, () => { skillPreparationFailures += 1; });
-            },
-            onError: () => { skillPreparationFailures += 1; },
-        });
-        stopPreparation = skillPreparationPump.requestStop;
-        if (stopping)
-            stopPreparation();
-        const applyReadySourceScan = async () => {
-            if (!sourceScanReady)
-                return;
-            const ready = sourceScanReady;
-            sourceScanReady = null;
-            sourceScanFlight = null;
-            if ('error' in ready) {
-                repositorySourceWatcher.invalidate();
-                repositorySourceFailures += 1;
-                repositorySourceState = 'blocked';
-                nextRepositorySourceScanAt = performance.now() + 60_000;
-                return;
-            }
-            if ('state' in ready) {
-                repositorySourceState = ready.state;
-                nextRepositorySourceScanAt = performance.now() + 15_000;
-                return;
-            }
-            const sourceCycle = ready.cycle;
-            repositorySourceState = sourceCycle.state;
-            if (sourceCycle.localMutation) {
-                repositorySourceCandidates += 1;
-                if (canonicalWorkspace.repositoryPackage && sourceCycle.persisted) {
-                    canonicalWorkspace.repositoryPackage.localBaselineSnapshotHash = sourceCycle.persisted.snapshotHash;
-                    if (sourceCycle.state === 'source_already_published') {
+                                bundleId: prepared.bundle.bundleId, bundleHash: prepared.bundle.bundleHash },
+                            onCommitted: () => { retained = true; } });
+                        skillPreparationsCompleted += 1;
+                    }
+                    finally {
+                        if (!retained)
+                            await rm(prepared.sourceRoot, { recursive: true, force: true });
+                    }
+                });
+            }, () => { skillPreparationFailures += 1; });
+        },
+        onError: () => { skillPreparationFailures += 1; },
+    });
+    stopPreparation = skillPreparationPump.requestStop;
+    if (stopping)
+        stopPreparation();
+    const applyReadySourceScan = async () => {
+        if (!sourceScanReady)
+            return;
+        const ready = sourceScanReady;
+        sourceScanReady = null;
+        sourceScanFlight = null;
+        if ('error' in ready) {
+            repositorySourceWatcher.invalidate();
+            repositorySourceFailures += 1;
+            repositorySourceState = 'blocked';
+            nextRepositorySourceScanAt = performance.now() + 60_000;
+            return;
+        }
+        if ('state' in ready) {
+            repositorySourceState = ready.state;
+            nextRepositorySourceScanAt = performance.now() + 15_000;
+            return;
+        }
+        const sourceCycle = ready.cycle;
+        repositorySourceState = sourceCycle.state;
+        if (sourceCycle.localMutation) {
+            repositorySourceCandidates += 1;
+            if (canonicalWorkspace.repositoryPackage && sourceCycle.persisted) {
+                canonicalWorkspace.repositoryPackage.localBaselineSnapshotHash = sourceCycle.persisted.snapshotHash;
+                if (sourceCycle.state === 'source_already_published') {
+                    canonicalWorkspace.repositoryPackage.publishedLocalSnapshotHash = sourceCycle.persisted.snapshotHash;
+                    canonicalWorkspace.repositoryPackage.pendingLocalSnapshotHash = null;
+                    canonicalWorkspace.repositoryPackage.pendingLocalOperationId = null;
+                    publishedLocalSnapshotHash = sourceCycle.persisted.snapshotHash;
+                }
+                else if (sourceCycle.candidate) {
+                    const receipt = sourceCycle.candidate;
+                    if (typeof receipt.candidateId === 'string' && typeof receipt.operationId === 'string'
+                        && typeof receipt.snapshotHash === 'string' && sourceCycle.submittedManifestHash) {
+                        Object.assign(canonicalWorkspace.repositoryPackage, {
+                            state: receipt.state, candidateId: receipt.candidateId, operationId: receipt.operationId,
+                            snapshotHash: receipt.snapshotHash, sourceManifestHash: sourceCycle.submittedManifestHash,
+                            releaseId: typeof receipt.releaseId === 'string' ? receipt.releaseId : null,
+                            consolidationMode: 'repository_update',
+                        });
+                    }
+                    if (receipt.state === 'published') {
                         canonicalWorkspace.repositoryPackage.publishedLocalSnapshotHash = sourceCycle.persisted.snapshotHash;
                         canonicalWorkspace.repositoryPackage.pendingLocalSnapshotHash = null;
                         canonicalWorkspace.repositoryPackage.pendingLocalOperationId = null;
                         publishedLocalSnapshotHash = sourceCycle.persisted.snapshotHash;
                     }
-                    else if (sourceCycle.candidate) {
-                        const receipt = sourceCycle.candidate;
-                        if (typeof receipt.candidateId === 'string' && typeof receipt.operationId === 'string'
-                            && typeof receipt.snapshotHash === 'string' && sourceCycle.submittedManifestHash) {
-                            Object.assign(canonicalWorkspace.repositoryPackage, {
-                                state: receipt.state, candidateId: receipt.candidateId, operationId: receipt.operationId,
-                                snapshotHash: receipt.snapshotHash, sourceManifestHash: sourceCycle.submittedManifestHash,
-                                releaseId: typeof receipt.releaseId === 'string' ? receipt.releaseId : null,
-                                consolidationMode: 'repository_update',
-                            });
-                        }
-                        if (receipt.state === 'published') {
-                            canonicalWorkspace.repositoryPackage.publishedLocalSnapshotHash = sourceCycle.persisted.snapshotHash;
-                            canonicalWorkspace.repositoryPackage.pendingLocalSnapshotHash = null;
-                            canonicalWorkspace.repositoryPackage.pendingLocalOperationId = null;
-                            publishedLocalSnapshotHash = sourceCycle.persisted.snapshotHash;
-                        }
-                        else if ((receipt.state === 'accepted' || receipt.state === 'processing')
-                            && typeof receipt.operationId === 'string') {
-                            canonicalWorkspace.repositoryPackage.pendingLocalSnapshotHash = sourceCycle.persisted.snapshotHash;
-                            canonicalWorkspace.repositoryPackage.pendingLocalOperationId = receipt.operationId;
+                    else if ((receipt.state === 'accepted' || receipt.state === 'processing')
+                        && typeof receipt.operationId === 'string') {
+                        canonicalWorkspace.repositoryPackage.pendingLocalSnapshotHash = sourceCycle.persisted.snapshotHash;
+                        canonicalWorkspace.repositoryPackage.pendingLocalOperationId = receipt.operationId;
+                    }
+                    else if (receipt.state === 'blocked') {
+                        canonicalWorkspace.repositoryPackage.localBaselineSnapshotHash = publishedLocalSnapshotHash;
+                        repositorySourceWatcher.invalidate();
+                    }
+                }
+                await saveWorkspaceRecord(canonicalWorkspace);
+            }
+        }
+        nextRepositorySourceScanAt = performance.now() + (sourceCycle.state === 'debouncing' ? 15_000 : 60_000);
+    };
+    const consumeSourceScan = async () => {
+        try {
+            await applyReadySourceScan();
+        }
+        catch {
+            repositorySourceWatcher.invalidate();
+            repositorySourceFailures += 1;
+            repositorySourceState = 'blocked';
+            nextRepositorySourceScanAt = performance.now() + 60_000;
+        }
+    };
+    try {
+        signal.throwIfAborted();
+        const recoveredTaskTrajectories = await deferUnavailableRelayRetention(async () => finalizeRecoveredSignedTaskTrajectories(fabric, policy));
+        if (recoveredTaskTrajectories.state === 'completed') {
+            taskTrajectoriesRecovered += recoveredTaskTrajectories.value.length;
+        }
+        do {
+            if (stopping)
+                break;
+            await consumeSourceScan();
+            if (Date.now() >= nextPolicyRefreshAt) {
+                try {
+                    await syncWorkspacePolicy(fabric, canonicalWorkspace, policy.revision, true);
+                    policy = await loadVerifiedWorkspacePolicy(policyPath, canonicalWorkspace.workspaceId);
+                    evidencePolicyFresh = true;
+                }
+                catch {
+                    evidencePolicyFresh = false;
+                }
+                nextPolicyRefreshAt = Date.now() + 60_000;
+            }
+            if (!sourceScanFlight && canonicalWorkspace.repositoryBindingId && canonicalWorkspace.repositoryAgentId) {
+                try {
+                    const current = await pollRepositoryCandidate({ transport: fabric,
+                        outboxRoot: resolve(dharmaHome(), 'relay', 'repository-candidates'),
+                        scope: { organizationId: canonicalWorkspace.organizationId, workspaceId: canonicalWorkspace.workspaceId,
+                            repositoryBindingId: canonicalWorkspace.repositoryBindingId,
+                            repositoryAgentId: canonicalWorkspace.repositoryAgentId } });
+                    if (current && canonicalWorkspace.repositoryPackage) {
+                        if (current.candidateId !== canonicalWorkspace.repositoryPackage.candidateId
+                            || current.operationId !== canonicalWorkspace.repositoryPackage.operationId) {
+                            throw new Error('Repository candidate status changed identity while polling.');
                         }
-                        else if (receipt.state === 'blocked') {
-                            canonicalWorkspace.repositoryPackage.localBaselineSnapshotHash = publishedLocalSnapshotHash;
+                        const baseline = advanceRepositorySourceBaseline(canonicalWorkspace.repositoryPackage, current);
+                        canonicalWorkspace = { ...canonicalWorkspace, repositoryPackage: { ...canonicalWorkspace.repositoryPackage,
+                                state: current.state, candidateId: current.candidateId, operationId: current.operationId,
+                                snapshotHash: current.snapshotHash, releaseId: current.releaseId,
+                                ...baseline,
+                                generation: current.state === 'published' ? Math.max(1, canonicalWorkspace.repositoryPackage.generation) : canonicalWorkspace.repositoryPackage.generation } };
+                        publishedLocalSnapshotHash = baseline.publishedLocalSnapshotHash;
+                        if (current.state === 'blocked')
                             repositorySourceWatcher.invalidate();
-                        }
+                        await saveWorkspaceRecord(canonicalWorkspace);
                     }
-                    await saveWorkspaceRecord(canonicalWorkspace);
+                }
+                catch {
+                    repositorySourceFailures += 1;
                 }
             }
-            nextRepositorySourceScanAt = performance.now() + (sourceCycle.state === 'debouncing' ? 15_000 : 60_000);
-        };
-        const consumeSourceScan = async () => {
-            try {
-                await applyReadySourceScan();
-            }
-            catch {
-                repositorySourceWatcher.invalidate();
-                repositorySourceFailures += 1;
-                repositorySourceState = 'blocked';
-                nextRepositorySourceScanAt = performance.now() + 60_000;
+            let evidenceRequestId;
+            if (evidencePolicyFresh && !stopping) {
+                const evidenceCycle = await deferUnavailableRelayRetention(async () => {
+                    const synced = await syncPendingRetentionCapsules(vault, fabric, policy, canonicalWorkspace.workspaceId);
+                    const evidence = await processEvidenceRequest(fabric, policy, canonicalWorkspace.workspaceId);
+                    return {
+                        synced,
+                        evidenceRequestId: typeof evidence.requestId === 'string' ? evidence.requestId : undefined,
+                    };
+                });
+                if (evidenceCycle.state === 'deferred') {
+                    evidencePolicyFresh = false;
+                }
+                else {
+                    trajectorySyncsCompleted += evidenceCycle.value.synced;
+                    evidenceRequestId = evidenceCycle.value.evidenceRequestId;
+                    if (evidenceRequestId)
+                        evidenceResponsesCompleted += 1;
+                }
             }
-        };
-        try {
-            const recoveredTaskTrajectories = await deferUnavailableRelayRetention(async () => finalizeRecoveredSignedTaskTrajectories(fabric, policy));
-            if (recoveredTaskTrajectories.state === 'completed') {
-                taskTrajectoriesRecovered += recoveredTaskTrajectories.value.length;
+            const result = await serialized(async () => {
+                if (stopping)
+                    return { taskId: null };
+                return executeOneTask(fabric, leaseSeconds);
+            });
+            if (!stopping && Date.now() - lastPollReceiptAt >= 30_000) {
+                const observation = {
+                    at: new Date().toISOString(), workspaceId: canonicalWorkspace.workspaceId, version: VERSION, pid: process.pid,
+                };
+                await writeJsonAtomic(resolve(dharmaHome(), 'relay', 'repositories', canonicalWorkspace.workspaceId, 'last-successful-poll.json'), observation);
+                const binding = await readFile(resolve(dharmaHome(), 'relay', 'supervisor-workspace.json'), 'utf8')
+                    .then(value => JSON.parse(value)).catch(() => null);
+                if (!binding || binding.workspaceId === canonicalWorkspace.workspaceId) {
+                    await writeJsonAtomic(resolve(dharmaHome(), 'relay', 'last-successful-poll.json'), observation);
+                }
+                lastPollReceiptAt = Date.now();
             }
-            do {
-                await consumeSourceScan();
-                if (Date.now() >= nextPolicyRefreshAt) {
+            if (result.taskId)
+                tasksCompleted += 1;
+            if (typeof result.failureCategory === 'string')
+                lastProviderFailureCategory = result.failureCategory;
+            if (!stopping && !result.taskId && performance.now() >= nextSkillActivationAt) {
+                for (const adapter of providerAdapters) {
                     try {
-                        await syncWorkspacePolicy(fabric, canonicalWorkspace, policy.revision, true);
-                        policy = await loadVerifiedWorkspacePolicy(policyPath, canonicalWorkspace.workspaceId);
-                        evidencePolicyFresh = true;
+                        const capability = await adapter.capability();
+                        if (capability.skillInstall === 'unavailable' || !isLocalProviderId(adapter.providerId))
+                            continue;
+                        const provider = adapter.providerId;
+                        await withWorkspaceSkillActivationLock(canonicalWorkspace.workspaceId, provider, async () => {
+                            await withSkillPreparationTransaction({ home: dharmaHome(), workspaceId: canonicalWorkspace.workspaceId,
+                                provider, assertCurrent: () => { if (stopping)
+                                    throw new Error('Relay is stopping.'); } }, async () => {
+                                const cached = await takeCachedSkillUpdate({ workspaceId: canonicalWorkspace.workspaceId,
+                                    provider, policyPath, fabric });
+                                const prepared = cached || await prepareSkillUpdate({ workspaceId: canonicalWorkspace.workspaceId,
+                                    provider, policyPath, fabric, automatic: true });
+                                if (!prepared)
+                                    return;
+                                if (!cached)
+                                    skillPreparationsCompleted += 1;
+                                await activatePreparedSkillUpdate({ prepared, workspaceId: canonicalWorkspace.workspaceId,
+                                    provider, policyPath, flags: new Map() });
+                                skillActivationsCompleted += 1;
+                            });
+                        });
                     }
                     catch {
-                        evidencePolicyFresh = false;
+                        skillActivationFailures += 1;
+                        skillActivationFailuresByProvider[adapter.providerId] = (skillActivationFailuresByProvider[adapter.providerId] || 0) + 1;
                     }
-                    nextPolicyRefreshAt = Date.now() + 60_000;
                 }
-                if (!sourceScanFlight && canonicalWorkspace.repositoryBindingId && canonicalWorkspace.repositoryAgentId) {
+                nextSkillActivationAt = performance.now() + 60_000;
+            }
+            if (!stopping && !sourceScanFlight && performance.now() >= nextRepositorySourceScanAt) {
+                const sourceWorkspace = canonicalWorkspace;
+                const sourceBaselineHash = publishedLocalSnapshotHash;
+                sourceScanFlight = (async () => {
                     try {
-                        const current = await pollRepositoryCandidate({ transport: fabric,
-                            outboxRoot: resolve(dharmaHome(), 'relay', 'repository-candidates'),
-                            scope: { organizationId: canonicalWorkspace.organizationId, workspaceId: canonicalWorkspace.workspaceId,
-                                repositoryBindingId: canonicalWorkspace.repositoryBindingId,
-                                repositoryAgentId: canonicalWorkspace.repositoryAgentId } });
-                        if (current && canonicalWorkspace.repositoryPackage) {
-                            if (current.candidateId !== canonicalWorkspace.repositoryPackage.candidateId
-                                || current.operationId !== canonicalWorkspace.repositoryPackage.operationId) {
-                                throw new Error('Repository candidate status changed identity while polling.');
-                            }
-                            const baseline = advanceRepositorySourceBaseline(canonicalWorkspace.repositoryPackage, current);
-                            canonicalWorkspace = { ...canonicalWorkspace, repositoryPackage: { ...canonicalWorkspace.repositoryPackage,
-                                    state: current.state, candidateId: current.candidateId, operationId: current.operationId,
-                                    snapshotHash: current.snapshotHash, releaseId: current.releaseId,
-                                    ...baseline,
-                                    generation: current.state === 'published' ? Math.max(1, canonicalWorkspace.repositoryPackage.generation) : canonicalWorkspace.repositoryPackage.generation } };
-                            publishedLocalSnapshotHash = baseline.publishedLocalSnapshotHash;
-                            if (current.state === 'blocked')
-                                repositorySourceWatcher.invalidate();
-                            await saveWorkspaceRecord(canonicalWorkspace);
+                        if (!repositorySourceBaselineAvailable) {
+                            throw new Error('Repository source baseline is unavailable; refusing an unanchored update.');
                         }
-                    }
-                    catch {
-                        repositorySourceFailures += 1;
-                    }
-                }
-                let evidenceRequestId;
-                if (evidencePolicyFresh) {
-                    const evidenceCycle = await deferUnavailableRelayRetention(async () => {
-                        const synced = await syncPendingRetentionCapsules(vault, fabric, policy, canonicalWorkspace.workspaceId);
-                        const evidence = await processEvidenceRequest(fabric, policy, canonicalWorkspace.workspaceId);
-                        return {
-                            synced,
-                            evidenceRequestId: typeof evidence.requestId === 'string' ? evidence.requestId : undefined,
-                        };
-                    });
-                    if (evidenceCycle.state === 'deferred') {
-                        evidencePolicyFresh = false;
-                    }
-                    else {
-                        trajectorySyncsCompleted += evidenceCycle.value.synced;
-                        evidenceRequestId = evidenceCycle.value.evidenceRequestId;
-                        if (evidenceRequestId)
-                            evidenceResponsesCompleted += 1;
-                    }
-                }
-                const result = await executeOneTask(fabric, leaseSeconds);
-                if (Date.now() - lastPollReceiptAt >= 30_000) {
-                    await writeJsonAtomic(resolve(dharmaHome(), 'relay', 'last-successful-poll.json'), {
-                        at: new Date().toISOString(), workspaceId: canonicalWorkspace.workspaceId, version: VERSION,
-                    });
-                    lastPollReceiptAt = Date.now();
-                }
-                if (result.taskId)
-                    tasksCompleted += 1;
-                if (typeof result.failureCategory === 'string')
-                    lastProviderFailureCategory = result.failureCategory;
-                if (!result.taskId && performance.now() >= nextSkillActivationAt) {
-                    for (const adapter of providerAdapters) {
-                        try {
-                            const capability = await adapter.capability();
-                            if (capability.skillInstall === 'unavailable' || !isLocalProviderId(adapter.providerId))
-                                continue;
-                            const provider = adapter.providerId;
-                            await withWorkspaceSkillActivationLock(canonicalWorkspace.workspaceId, provider, async () => {
-                                await withSkillPreparationTransaction({ home: dharmaHome(), workspaceId: canonicalWorkspace.workspaceId,
-                                    provider, assertCurrent: () => { if (stopping)
-                                        throw new Error('Relay is stopping.'); } }, async () => {
-                                    const cached = await takeCachedSkillUpdate({ workspaceId: canonicalWorkspace.workspaceId,
-                                        provider, policyPath, fabric });
-                                    const prepared = cached || await prepareSkillUpdate({ workspaceId: canonicalWorkspace.workspaceId,
-                                        provider, policyPath, fabric, automatic: true });
-                                    if (!prepared)
-                                        return;
-                                    if (!cached)
-                                        skillPreparationsCompleted += 1;
-                                    await activatePreparedSkillUpdate({ prepared, workspaceId: canonicalWorkspace.workspaceId,
-                                        provider, policyPath, flags: new Map() });
-                                    skillActivationsCompleted += 1;
-                                });
-                            });
+                        if (!sourceWorkspace.repositoryBindingId || !sourceWorkspace.repositoryAgentId) {
+                            throw new Error('Repository source synchronization requires a complete repository binding.');
                         }
-                        catch {
-                            skillActivationFailures += 1;
-                            skillActivationFailuresByProvider[adapter.providerId] = (skillActivationFailuresByProvider[adapter.providerId] || 0) + 1;
+                        const installedKnowledge = await installedRepositoryKnowledge(sourceWorkspace);
+                        if (!installedKnowledge && (sourceWorkspace.repositoryPackage?.generation ?? 0) > 0) {
+                            sourceScanReady = { state: 'awaiting_signed_baseline' };
                         }
-                    }
-                    nextSkillActivationAt = performance.now() + 60_000;
-                }
-                if (!sourceScanFlight && performance.now() >= nextRepositorySourceScanAt) {
-                    const sourceWorkspace = canonicalWorkspace;
-                    const sourceBaselineHash = publishedLocalSnapshotHash;
-                    sourceScanFlight = (async () => {
-                        try {
-                            if (!repositorySourceBaselineAvailable) {
-                                throw new Error('Repository source baseline is unavailable; refusing an unanchored update.');
-                            }
-                            if (!sourceWorkspace.repositoryBindingId || !sourceWorkspace.repositoryAgentId) {
-                                throw new Error('Repository source synchronization requires a complete repository binding.');
-                            }
-                            const installedKnowledge = await installedRepositoryKnowledge(sourceWorkspace);
-                            if (!installedKnowledge && (sourceWorkspace.repositoryPackage?.generation ?? 0) > 0) {
-                                sourceScanReady = { state: 'awaiting_signed_baseline' };
-                            }
-                            else {
-                                if (sourceWorkspace.repositoryPackage?.state === 'blocked' && sourceWorkspace.repositoryPackage.snapshotHash) {
-                                    const blocked = await readRepositorySourceBaselineSnapshot(sourceWorkspace.path, sourceWorkspace.repositoryPackage.snapshotHash);
-                                    if (blockedRepositorySourceRetry.consider(sourceWorkspace.repositoryPackage.candidateId ?? '', blocked.manifest.knowledge, installedKnowledge))
-                                        repositorySourceWatcher.invalidate();
-                                }
-                                const sourceCycle = await scanRepositorySourceChanges({
-                                    workspace: sourceWorkspace.path, organizationId: sourceWorkspace.organizationId,
-                                    workspaceId: sourceWorkspace.workspaceId, repositoryBindingId: sourceWorkspace.repositoryBindingId,
-                                    repositoryAgentId: sourceWorkspace.repositoryAgentId, transport: fabric, watcher: repositorySourceWatcher,
-                                    loadRetainedKnowledge: () => installedRepositoryKnowledge(sourceWorkspace),
-                                    loadPublishedLocalBaseline: () => sourceBaselineHash
-                                        ? readRepositoryPackageSnapshot(sourceWorkspace.path, sourceBaselineHash) : Promise.resolve(null),
-                                    submitCandidate: (snapshot, expectedLatestSourceFingerprint) => synchronizeRepositoryCandidate({ transport: fabric,
-                                        outboxRoot: resolve(dharmaHome(), 'relay', 'repository-candidates'),
-                                        scope: { organizationId: sourceWorkspace.organizationId,
-                                            workspaceId: sourceWorkspace.workspaceId,
-                                            repositoryBindingId: sourceWorkspace.repositoryBindingId,
-                                            repositoryAgentId: sourceWorkspace.repositoryAgentId },
-                                        snapshot, initialRepository: false, expectedLatestSourceFingerprint }),
-                                });
-                                sourceScanReady = { cycle: sourceCycle };
+                        else {
+                            if (sourceWorkspace.repositoryPackage?.state === 'blocked' && sourceWorkspace.repositoryPackage.snapshotHash) {
+                                const blocked = await readRepositorySourceBaselineSnapshot(sourceWorkspace.path, sourceWorkspace.repositoryPackage.snapshotHash);
+                                if (blockedRepositorySourceRetry.consider(sourceWorkspace.repositoryPackage.candidateId ?? '', blocked.manifest.knowledge, installedKnowledge))
+                                    repositorySourceWatcher.invalidate();
                             }
+                            const sourceCycle = await scanRepositorySourceChanges({
+                                workspace: sourceWorkspace.path, organizationId: sourceWorkspace.organizationId,
+                                workspaceId: sourceWorkspace.workspaceId, repositoryBindingId: sourceWorkspace.repositoryBindingId,
+                                repositoryAgentId: sourceWorkspace.repositoryAgentId, transport: fabric, watcher: repositorySourceWatcher,
+                                loadRetainedKnowledge: () => installedRepositoryKnowledge(sourceWorkspace),
+                                loadPublishedLocalBaseline: () => sourceBaselineHash
+                                    ? readRepositoryPackageSnapshot(sourceWorkspace.path, sourceBaselineHash) : Promise.resolve(null),
+                                submitCandidate: (snapshot, expectedLatestSourceFingerprint) => synchronizeRepositoryCandidate({ transport: fabric,
+                                    outboxRoot: resolve(dharmaHome(), 'relay', 'repository-candidates'),
+                                    scope: { organizationId: sourceWorkspace.organizationId,
+                                        workspaceId: sourceWorkspace.workspaceId,
+                                        repositoryBindingId: sourceWorkspace.repositoryBindingId,
+                                        repositoryAgentId: sourceWorkspace.repositoryAgentId },
+                                    snapshot, initialRepository: false, expectedLatestSourceFingerprint }),
+                            });
+                            sourceScanReady = { cycle: sourceCycle };
                         }
-                        catch (error) {
-                            sourceScanReady = { error };
-                        }
-                    })();
-                }
-                if (flags.has('once'))
-                    break;
-                if (!result.taskId && !evidenceRequestId)
-                    await new Promise((accept) => setTimeout(accept, pollMs));
-            } while (!stopping);
-        }
-        finally {
-            if (sourceScanFlight)
-                await sourceScanFlight;
-            await consumeSourceScan();
-            await skillPreparationPump.stop();
-            vault.close();
-            process.removeListener('SIGINT', stop);
-            process.removeListener('SIGTERM', stop);
-        }
-        return {
-            ok: true, stopped: true, tasksCompleted, taskTrajectoriesRecovered,
-            lastProviderFailureCategory,
-            evidenceResponsesCompleted, trajectorySyncsCompleted,
-            repositorySourceCandidates, repositorySourceFailures, repositorySourceState,
-            skillPreparationsCompleted, skillPreparationFailures, skillActivationsCompleted, skillActivationFailures,
-            skillActivationFailuresByProvider,
-            sharedRepositoryReady: await repositorySharedReady(canonicalWorkspace),
-        };
+                    }
+                    catch (error) {
+                        sourceScanReady = { error };
+                    }
+                })();
+            }
+            if (flags.has('once'))
+                break;
+            if (!result.taskId && !evidenceRequestId)
+                await waitForRelayRefresh(pollMs, signal);
+        } while (!stopping);
     }
     finally {
-        await releaseRelayLease();
+        if (sourceScanFlight)
+            await sourceScanFlight;
+        await consumeSourceScan();
+        await skillPreparationPump.stop();
+        vault.close();
+        signal.removeEventListener('abort', stop);
     }
+    return {
+        ok: true, stopped: true, tasksCompleted, taskTrajectoriesRecovered,
+        lastProviderFailureCategory,
+        evidenceResponsesCompleted, trajectorySyncsCompleted,
+        repositorySourceCandidates, repositorySourceFailures, repositorySourceState,
+        skillPreparationsCompleted, skillPreparationFailures, skillActivationsCompleted, skillActivationFailures,
+        skillActivationFailuresByProvider,
+        sharedRepositoryReady: await repositorySharedReady(canonicalWorkspace),
+    };
 }
 export async function run(argv) {
     const { positional, flags, repeated } = parseCliOptions(argv);
@@ -6436,6 +6719,8 @@ export async function run(argv) {
     }
     if (command === 'repositories' && subcommand === 'list')
         return repositoriesList(flags);
+    if (command === 'repositories' && subcommand === 'recover-installer')
+        return repositoryInstallerRecoveryCommand(flags);
     if (command === 'repositories' && subcommand === 'snapshot') {
         return repositorySnapshotCommand(flags, repeated.get('approved-output') || []);
     }
@@ -6489,6 +6774,25 @@ export async function run(argv) {
         try {
             const config = JSON.parse(await readFile(configPath(), 'utf8'));
             const status = { version: VERSION, enrolled: true, relay, supervisor, autostart, reconnect };
+            if (flags.has('verbose') || flags.has('diagnostic')) {
+                const relayPid = await readFile(resolve(dharmaHome(), 'relay', 'relay.pid'), 'utf8')
+                    .then(value => Number(value.trim())).catch(() => 0);
+                try {
+                    const registered = await selectRepositoryRelayRegistrations(await registry(), config, loadOrganizationPolicy);
+                    const observations = [];
+                    for (const row of registered) {
+                        const observation = await readFile(resolve(dharmaHome(), 'relay', 'repositories', row.workspaceId, 'last-successful-poll.json'), 'utf8').then(value => JSON.parse(value)).catch(() => null);
+                        observations.push({ workspaceId: row.workspaceId,
+                            state: relay === 'running' && repositoryRelayObservationReady({ observation,
+                                workspaceId: row.workspaceId, version: VERSION, pid: relayPid }) ? 'acknowledged_recently' : 'pending',
+                            lastSuccessfulPollAt: typeof observation?.at === 'string' ? observation.at : null });
+                    }
+                    status.repositoryRelays = { state: 'observed', repositories: observations };
+                }
+                catch {
+                    status.repositoryRelays = { state: 'unavailable', repositories: [] };
+                }
+            }
             if (flags.has('verbose') || flags.has('diagnostic')) {
                 Object.assign(status, { home: dharmaHome(), organizationId: config.organizationId, deviceId: config.deviceId });
             }
@@ -6522,6 +6826,8 @@ export async function run(argv) {
         return probeRelayConnection();
     if (command === 'relay' && subcommand === 'stop')
         return relayStop();
+    if (command === 'relay' && subcommand === 'upgrade')
+        return relayUpgrade(flags);
     if (command === 'relay' && subcommand === 'autostart') {
         if (positional[2] === 'status')
             return relayAutostartStatus({ home: dharmaHome() });