@dharma-ai-labs/agent-fabric 0.2.97 → 0.2.98

package/dist/index.js

@@ -37,7 +37,7 @@ import { connectDemoDevice, verifyDemoDevice } from './demoEnrollment.js';
 import { performDemoPeerAction, withDemoDeviceLock } from './demoPeer.js';
 import { demoRepositoryPackage } from './demoPackage.js';
 import { runDemoWatch } from './demoWatch.js';
-const VERSION = '0.2.97';
+const VERSION = '0.2.98';
 const USAGE = CLI_USAGE;
 const execFileAsync = promisify(execFile);
 const LOCAL_PROVIDER_IDS = ['codex', 'claude', 'agy', 'hermes'];
@@ -752,6 +752,30 @@ export async function relayProcessState(home = dharmaHome()) {
         return code === 'EPERM' ? 'unknown' : 'stopped';
     }
 }
+export async function acquireRelayProcessLease(home = dharmaHome()) {
+    const pidPath = resolve(home, 'relay', 'relay.pid');
+    const releaseLock = await acquirePidLock(`${pidPath}.lock`, 250, 'Another relay process is already running for this device.');
+    try {
+        const state = await relayProcessState(home);
+        if (state !== 'stopped')
+            throw new Error(`Cannot start a second relay while process state is ${state}.`);
+        await writeFile(pidPath, `${process.pid}\n`, { mode: 0o600 });
+    }
+    catch (error) {
+        await releaseLock();
+        throw error;
+    }
+    return async () => {
+        try {
+            if ((await readFile(pidPath, 'utf8').catch(() => '')).trim() === String(process.pid)) {
+                await rm(pidPath, { force: true });
+            }
+        }
+        finally {
+            await releaseLock();
+        }
+    };
+}
 export async function materializeWorkspacePolicy(input) {
     const allowedCommands = {};
     try {
@@ -1396,9 +1420,17 @@ export async function waitForRelayReadiness(options = {}) {
         lastState = await processState();
         if (lastState === 'running') {
             try {
-                return { state: 'running', probe: await probe() };
+                const acknowledged = await probe();
+                if (!acknowledged.connected)
+                    throw new Error('Relay session is not connected.');
+                if (options.expectedVersion && acknowledged.relayVersion !== options.expectedVersion) {
+                    throw new Error(`relay_version_mismatch:${acknowledged.relayVersion}:${options.expectedVersion}`);
+                }
+                return { state: 'running', probe: acknowledged };
             }
-            catch {
+            catch (error) {
+                if (String(error.message).startsWith('relay_version_mismatch:'))
+                    throw error;
                 acknowledgementPending = true;
             }
         }
@@ -1419,7 +1451,7 @@ async function startRelayDaemon(policyPath) {
         });
         child.unref();
     }
-    const readiness = await waitForRelayReadiness();
+    const readiness = await waitForRelayReadiness({ expectedVersion: VERSION });
     return { started: !alreadyRunning, ...readiness };
 }
 export function providerHintFromEnvironment(env = process.env) {
@@ -5185,350 +5217,352 @@ async function relayStart(flags) {
     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 pidPath = resolve(dharmaHome(), 'relay', 'relay.pid');
-    await mkdir(resolve(dharmaHome(), 'relay'), { recursive: true, mode: 0o700 });
-    await writeFile(pidPath, `${process.pid}\n`, { mode: 0o600 });
-    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 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);
+    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 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;
-        }
-    }
-    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 });
+                }
+            }
+            catch {
+                repositorySourceBaselineAvailable = false;
+            }
         }
-    }
-    let nextRepositorySourceScanAt = 0;
-    let repositorySourceCandidates = 0;
-    let repositorySourceFailures = 0;
-    let repositorySourceState = 'not_scanned';
-    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))
-                    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();
+        let nextRepositorySourceScanAt = 0;
+        let repositorySourceCandidates = 0;
+        let repositorySourceFailures = 0;
+        let repositorySourceState = 'not_scanned';
+        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))
                         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,
-                            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,
+                    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,
                                 repositoryAgentId,
-                                repositoryBindingId: prepared.workspace.repositoryBindingId ?? null,
+                                repositoryBindingId: prepared.workspace.repositoryBindingId ?? null, provider,
                                 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();
-    try {
-        const recoveredTaskTrajectories = await deferUnavailableRelayRetention(async () => finalizeRecoveredSignedTaskTrajectories(fabric, policy));
-        if (recoveredTaskTrajectories.state === 'completed') {
-            taskTrajectoriesRecovered += recoveredTaskTrajectories.value.length;
-        }
-        do {
-            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 (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.');
+                                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;
                         }
-                        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);
-                    }
-                }
-                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;
-                }
+                        finally {
+                            if (!retained)
+                                await rm(prepared.sourceRoot, { recursive: true, force: true });
+                        }
+                    });
+                }, () => { skillPreparationFailures += 1; });
+            },
+            onError: () => { skillPreparationFailures += 1; },
+        });
+        stopPreparation = skillPreparationPump.requestStop;
+        if (stopping)
+            stopPreparation();
+        try {
+            const recoveredTaskTrajectories = await deferUnavailableRelayRetention(async () => finalizeRecoveredSignedTaskTrajectories(fabric, policy));
+            if (recoveredTaskTrajectories.state === 'completed') {
+                taskTrajectoriesRecovered += recoveredTaskTrajectories.value.length;
             }
-            const result = await executeOneTask(fabric, leaseSeconds);
-            if (result.taskId)
-                tasksCompleted += 1;
-            if (typeof result.failureCategory === 'string')
-                lastProviderFailureCategory = result.failureCategory;
-            if (!result.taskId && performance.now() >= nextSkillActivationAt) {
-                for (const adapter of providerAdapters) {
+            do {
+                if (Date.now() >= nextPolicyRefreshAt) {
                     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;
-                            });
-                        });
+                        await syncWorkspacePolicy(fabric, canonicalWorkspace, policy.revision, true);
+                        policy = await loadVerifiedWorkspacePolicy(policyPath, canonicalWorkspace.workspaceId);
+                        evidencePolicyFresh = true;
                     }
                     catch {
-                        skillActivationFailures += 1;
-                        skillActivationFailuresByProvider[adapter.providerId] = (skillActivationFailuresByProvider[adapter.providerId] || 0) + 1;
+                        evidencePolicyFresh = false;
                     }
+                    nextPolicyRefreshAt = Date.now() + 60_000;
                 }
-                nextSkillActivationAt = performance.now() + 60_000;
-            }
-            if (performance.now() >= nextRepositorySourceScanAt) {
-                try {
-                    if (!repositorySourceBaselineAvailable) {
-                        throw new Error('Repository source baseline is unavailable; refusing an unanchored update.');
+                if (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.');
+                            }
+                            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 (!canonicalWorkspace.repositoryBindingId || !canonicalWorkspace.repositoryAgentId) {
-                        throw new Error('Repository source synchronization requires a complete repository binding.');
+                    catch {
+                        repositorySourceFailures += 1;
                     }
-                    const installedKnowledge = await installedRepositoryKnowledge(canonicalWorkspace);
-                    if (!installedKnowledge && (canonicalWorkspace.repositoryPackage?.generation ?? 0) > 0) {
-                        repositorySourceState = 'awaiting_signed_baseline';
-                        nextRepositorySourceScanAt = performance.now() + 15_000;
+                }
+                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 {
-                        if (canonicalWorkspace.repositoryPackage?.state === 'blocked' && canonicalWorkspace.repositoryPackage.snapshotHash) {
-                            const blocked = await readRepositorySourceBaselineSnapshot(canonicalWorkspace.path, canonicalWorkspace.repositoryPackage.snapshotHash);
-                            if (blockedRepositorySourceRetry.consider(canonicalWorkspace.repositoryPackage.candidateId ?? '', blocked.manifest.knowledge, installedKnowledge))
-                                repositorySourceWatcher.invalidate();
+                        trajectorySyncsCompleted += evidenceCycle.value.synced;
+                        evidenceRequestId = evidenceCycle.value.evidenceRequestId;
+                        if (evidenceRequestId)
+                            evidenceResponsesCompleted += 1;
+                    }
+                }
+                const result = await executeOneTask(fabric, leaseSeconds);
+                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;
+                                });
+                            });
                         }
-                        const sourceCycle = await scanRepositorySourceChanges({
-                            workspace: canonicalWorkspace.path, organizationId: canonicalWorkspace.organizationId,
-                            workspaceId: canonicalWorkspace.workspaceId, repositoryBindingId: canonicalWorkspace.repositoryBindingId,
-                            repositoryAgentId: canonicalWorkspace.repositoryAgentId, transport: fabric, watcher: repositorySourceWatcher,
-                            loadRetainedKnowledge: () => installedRepositoryKnowledge(canonicalWorkspace),
-                            loadPublishedLocalBaseline: () => publishedLocalSnapshotHash
-                                ? readRepositoryPackageSnapshot(canonicalWorkspace.path, publishedLocalSnapshotHash) : Promise.resolve(null),
-                            submitCandidate: (snapshot, expectedLatestSourceFingerprint) => synchronizeRepositoryCandidate({ transport: fabric,
-                                outboxRoot: resolve(dharmaHome(), 'relay', 'repository-candidates'),
-                                scope: { organizationId: canonicalWorkspace.organizationId,
-                                    workspaceId: canonicalWorkspace.workspaceId,
-                                    repositoryBindingId: canonicalWorkspace.repositoryBindingId,
-                                    repositoryAgentId: canonicalWorkspace.repositoryAgentId },
-                                snapshot, initialRepository: false, expectedLatestSourceFingerprint }),
-                        });
-                        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') {
+                        catch {
+                            skillActivationFailures += 1;
+                            skillActivationFailuresByProvider[adapter.providerId] = (skillActivationFailuresByProvider[adapter.providerId] || 0) + 1;
+                        }
+                    }
+                    nextSkillActivationAt = performance.now() + 60_000;
+                }
+                if (performance.now() >= nextRepositorySourceScanAt) {
+                    try {
+                        if (!repositorySourceBaselineAvailable) {
+                            throw new Error('Repository source baseline is unavailable; refusing an unanchored update.');
+                        }
+                        if (!canonicalWorkspace.repositoryBindingId || !canonicalWorkspace.repositoryAgentId) {
+                            throw new Error('Repository source synchronization requires a complete repository binding.');
+                        }
+                        const installedKnowledge = await installedRepositoryKnowledge(canonicalWorkspace);
+                        if (!installedKnowledge && (canonicalWorkspace.repositoryPackage?.generation ?? 0) > 0) {
+                            repositorySourceState = 'awaiting_signed_baseline';
+                            nextRepositorySourceScanAt = performance.now() + 15_000;
+                        }
+                        else {
+                            if (canonicalWorkspace.repositoryPackage?.state === 'blocked' && canonicalWorkspace.repositoryPackage.snapshotHash) {
+                                const blocked = await readRepositorySourceBaselineSnapshot(canonicalWorkspace.path, canonicalWorkspace.repositoryPackage.snapshotHash);
+                                if (blockedRepositorySourceRetry.consider(canonicalWorkspace.repositoryPackage.candidateId ?? '', blocked.manifest.knowledge, installedKnowledge))
+                                    repositorySourceWatcher.invalidate();
+                            }
+                            const sourceCycle = await scanRepositorySourceChanges({
+                                workspace: canonicalWorkspace.path, organizationId: canonicalWorkspace.organizationId,
+                                workspaceId: canonicalWorkspace.workspaceId, repositoryBindingId: canonicalWorkspace.repositoryBindingId,
+                                repositoryAgentId: canonicalWorkspace.repositoryAgentId, transport: fabric, watcher: repositorySourceWatcher,
+                                loadRetainedKnowledge: () => installedRepositoryKnowledge(canonicalWorkspace),
+                                loadPublishedLocalBaseline: () => publishedLocalSnapshotHash
+                                    ? readRepositoryPackageSnapshot(canonicalWorkspace.path, publishedLocalSnapshotHash) : Promise.resolve(null),
+                                submitCandidate: (snapshot, expectedLatestSourceFingerprint) => synchronizeRepositoryCandidate({ transport: fabric,
+                                    outboxRoot: resolve(dharmaHome(), 'relay', 'repository-candidates'),
+                                    scope: { organizationId: canonicalWorkspace.organizationId,
+                                        workspaceId: canonicalWorkspace.workspaceId,
+                                        repositoryBindingId: canonicalWorkspace.repositoryBindingId,
+                                        repositoryAgentId: canonicalWorkspace.repositoryAgentId },
+                                    snapshot, initialRepository: false, expectedLatestSourceFingerprint }),
+                            });
+                            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 ((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();
+                                    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 === 'blocked') {
+                                            canonicalWorkspace.repositoryPackage.localBaselineSnapshotHash = publishedLocalSnapshotHash;
+                                            repositorySourceWatcher.invalidate();
+                                        }
                                     }
+                                    await saveWorkspaceRecord(canonicalWorkspace);
                                 }
-                                await saveWorkspaceRecord(canonicalWorkspace);
                             }
+                            nextRepositorySourceScanAt = performance.now() + (sourceCycle.state === 'debouncing' ? 15_000 : 60_000);
                         }
-                        nextRepositorySourceScanAt = performance.now() + (sourceCycle.state === 'debouncing' ? 15_000 : 60_000);
+                    }
+                    catch {
+                        repositorySourceWatcher.invalidate();
+                        repositorySourceFailures += 1;
+                        repositorySourceState = 'blocked';
+                        nextRepositorySourceScanAt = performance.now() + 60_000;
                     }
                 }
-                catch {
-                    repositorySourceWatcher.invalidate();
-                    repositorySourceFailures += 1;
-                    repositorySourceState = 'blocked';
-                    nextRepositorySourceScanAt = performance.now() + 60_000;
-                }
-            }
-            if (flags.has('once'))
-                break;
-            if (!result.taskId && !evidenceRequestId)
-                await new Promise((accept) => setTimeout(accept, pollMs));
-        } while (!stopping);
+                if (flags.has('once'))
+                    break;
+                if (!result.taskId && !evidenceRequestId)
+                    await new Promise((accept) => setTimeout(accept, pollMs));
+            } while (!stopping);
+        }
+        finally {
+            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),
+        };
     }
     finally {
-        await skillPreparationPump.stop();
-        vault.close();
-        process.removeListener('SIGINT', stop);
-        process.removeListener('SIGTERM', stop);
-        await rm(pidPath, { force: true });
+        await releaseRelayLease();
     }
-    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);