@dharma-ai-labs/agent-fabric 0.2.209 → 0.2.210

package/dist/index.js

@@ -12,11 +12,13 @@ import { canonicalize, createActionDecisionPublicKeyResolver, sha256, validateCo
 import { buildTrajectoryCapsule, containsDisallowedLocalPath, redactValue, referencesExcludedPath, trajectoryCapsuleHash } from '@dharma-ai-labs/agent-fabric-evidence-reduction';
 import { assertPolicy, loadOrganizationPolicy, verifyServerAuthorizedPolicy } from '@dharma-ai-labs/agent-fabric-policy';
 import { agyAdapter, claudeAdapter, codexAdapter, hermesAdapter, providerAdapters, providerExecutionRecords, providerProcessEnvironment } from '@dharma-ai-labs/agent-fabric-provider-adapters';
-import { AgentFabricClient, beginEnrollment, loadDeviceIdentity, loadOrCreateDeviceIdentity, normalizeHqUrl, pollEnrollment, assertDeviceEnrollmentAnchorAbsent, deleteActiveSkillAuthorizationAnchor, loadActiveSkillAuthorizationAnchor, loadDeviceEnrollmentAnchor, saveActiveSkillAuthorizationAnchor, isDefinitiveAgentFabricRejection, recoverDeviceEnrollmentConsistency, loadOrganizationApiToken, redeemBootstrapGrant, claimSetupReference, setupClaimSourceRegistration, saveDeviceConfig, saveDeviceEnrollmentAnchor, saveOrganizationApiToken, saveDeviceConnectionPreference, } from '@dharma-ai-labs/agent-fabric-relay-client';
+import { AgentFabricClient, beginEnrollment, loadDeviceIdentity, loadOrCreateDeviceIdentity, normalizeHqUrl, pollEnrollment, assertDeviceEnrollmentAnchorAbsent, deleteActiveSkillAuthorizationAnchor, loadActiveSkillAuthorizationAnchor, loadDeviceEnrollmentAnchor, saveActiveSkillAuthorizationAnchor, isDefinitiveAgentFabricRejection, recoverDeviceEnrollmentConsistency, withDeviceSigningControl, loadOrganizationApiToken, redeemBootstrapGrant, claimSetupReference, setupClaimSourceRegistration, saveDeviceConfig, saveDeviceEnrollmentAnchor, saveOrganizationApiToken, saveDeviceConnectionPreference, } from '@dharma-ai-labs/agent-fabric-relay-client';
 import { AgentFabricClient as AgentFabricApiClient, } from '@dharma-ai-labs/agent-fabric-sdk';
 import { contentHash, getActiveSkillBundleAuthorization, getExpiredSkillBundleAuthorizationForReplacement, getLegacySkillBundleIdForUpgrade, installSkillBundle, readVerifiedRepositoryKnowledge, rollbackUnconfirmedSkillBundle, verifySkillBundle } from '@dharma-ai-labs/agent-fabric-skill-manager';
 import { executeTask, FileActionExecutionJournal, FileTaskReceiptStore, providerInstructionsForTask, } from '@dharma-ai-labs/agent-fabric-task-runner';
 import { CLI_USAGE } from './usage.js';
+import { runDeviceSigningMaintenanceController } from './deviceSigningMaintenanceController.js';
+import { withLegacySigningMaintenanceBoundary } from './legacySigningMaintenanceBoundary.js';
 import { superviseRelay } from './relaySupervisor.js';
 import { currentRepositoryRelayFailure, repositoryRelayObservationReady, runRegisteredRepositoryRelays, selectRepositoryRelayRegistrations, serializeRelayWork, waitForRelayRefresh, withRepositoryRelayStage } from './repositoryRelaySupervisor.js';
 import { assertRelayStartupOwnership, disableRelayAutostart, enableRelayAutostart, inspectOwnedRelayAutostart, relayAutostartStatus, startRelayAutostart, stopRelayAutostart } from './relayAutostart.js';
@@ -100,6 +102,8 @@ import { requestCodexSetupHostPreparation } from './codexSetupPortalPreparation.
 import { readCodexSetupPublicStdin } from './codexSetupPublicStdin.js';
 import { reserveCodexSetupLaunch } from './codexSetupLaunchReservation.js';
 export { startCodexSetupNativeHost } from './codexSetupNativeHost.js';
+export { attachCodexSigningRecoveryNativeHost } from './codexSigningRecoveryNativeHost.js';
+export { openCodexSigningRecoveryOwner } from './codexBoundSession.js';
 export { openCodexSetupVaultJournal } from './codexSetupVaultJournal.js';
 import { createCodexSetupReadinessOwner } from './codexSetupReadiness.js';
 export { createCodexSetupReadinessOwner } from './codexSetupReadiness.js';
@@ -107,7 +111,8 @@ import { assertCodexSetupExecutionLease } from './codexSetupAdmission.js';
 import { parseLocalCodexSetupReadiness } from '@dharma-ai-labs/agent-fabric-local-vault/setup-readiness';
 import { writeBootstrapHostJson, writeBootstrapHostText } from './bootstrapHostFiles.js';
 export { openCooperativeInboxSession } from './cooperativeInboxSession.js';
-const VERSION = '0.2.209';
+import { inspectNamedCodexRecoveryToolDeclaration } from './codexSigningRecoveryTool.js';
+const VERSION = '0.2.210';
 const USAGE = CLI_USAGE;
 const execFileAsync = promisify(execFile);
 const LOCAL_PROVIDER_IDS = ['codex', 'claude', 'agy', 'hermes'];
@@ -161,10 +166,25 @@ export function portalUrl(flags, fallback = 'https://www.dharma-ai.io') {
     return String(flags.get('portal-url') || flags.get('hq-url') || fallback);
 }
 function print(value) {
-    process.stdout.write(typeof value === 'string' ? `${value}\n` : `${JSON.stringify(value, null, 2)}\n`);
+    process.stdout.write(formatCommandOutput(value));
+}
+export function formatCommandOutput(value) {
+    if (typeof value === 'string')
+        return value + '\n';
+    const streaming = value && typeof value === 'object' && !Array.isArray(value)
+        && value.schema === 'dharma.device-signing-maintenance-controller-progress/v1';
+    return JSON.stringify(value, null, streaming ? undefined : 2) + '\n';
 }
 export function commandExitCode(argv, value) {
     const { positional, flags } = parseCliOptions(argv);
+    if (positional[0] === 'signing-recovery') {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return 2;
+        const receipt = value, progress = receipt.progress;
+        return receipt.schema === 'dharma.device-signing-maintenance-controller-progress/v1' && receipt.ok === true
+            && receipt.nativeContinuationAuthorized === false && receipt.ready === false
+            && (flags.get('apply') === true ? progress?.state === 'trust_installed' && progress.clientTrustInstalled === true : receipt.planned === true) ? 0 : 2;
+    }
     if (positional[0] === 'sessions' && positional[1] === 'readiness' && flags.get('diagnostic') === true) {
         const diagnosticResult = value && typeof value === 'object' && !Array.isArray(value)
             ? value : null;
@@ -1044,7 +1064,7 @@ async function pidProcessState(pidPath) {
         const code = error.code;
         if (code === 'ESRCH')
             return 'stopped';
-        return code === 'EPERM' ? 'unknown' : 'stopped';
+        return 'unknown';
     }
 }
 export async function relayProcessState(home = dharmaHome()) {
@@ -1053,6 +1073,42 @@ export async function relayProcessState(home = dharmaHome()) {
 export async function relaySupervisorProcessState(home = dharmaHome()) {
     return pidProcessState(resolve(home, 'relay', 'supervisor.pid'));
 }
+/** A legacy runtime may not participate in the new signing mutex. Require all
+ * registrations belonging to this device disabled and their known owned PID
+ * locks stopped, plus its relay/supervisor, before any maintenance store read.
+ * This check never stops a process or changes startup/registration state. */
+export async function deviceTrustMaintenanceProcessState(home, name) {
+    const selected = await readNamedSession(home, name);
+    if (!selected)
+        return 'unknown';
+    const states = await Promise.all([relayProcessState(home), relaySupervisorProcessState(home)]);
+    let entries;
+    try {
+        entries = await readdir(resolve(home, 'sessions'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            return 'unknown';
+        entries = [];
+    }
+    for (const entry of entries) {
+        if (!/^[a-z][a-z0-9-]{0,47}$/.test(String(entry)))
+            continue;
+        let registration;
+        try {
+            registration = await readNamedSession(home, String(entry));
+        }
+        catch {
+            return 'unknown';
+        }
+        if (!registration)
+            return 'unknown';
+        if (registration.identity.deviceId !== selected.identity.deviceId || registration.identity.organizationId !== selected.identity.organizationId)
+            continue;
+        states.push(registration.enabled ? 'unknown' : await pidProcessState(resolve(namedSessionPaths(home, String(entry)).root, 'service.lock')));
+    }
+    return states.includes('running') ? 'running' : states.includes('unknown') ? '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.');
@@ -1228,6 +1284,35 @@ export async function withRelayStartupMutation(operation, home = dharmaHome()) {
         await release?.();
     }
 }
+export async function acquireNamedSessionStartupAdmission(home = dharmaHome()) {
+    return acquirePidLock(resolve(home, 'autostart-mutation.lock'), 250, 'named_session_startup_busy');
+}
+async function assertSigningMaintenanceManagedCohort(home, workspace) {
+    const startup = await inspectOwnedRelayAutostart({ home });
+    const bin = resolve(workspace, '.dharma', 'bin');
+    if (startup.version !== VERSION || startup.workspace !== workspace
+        || startup.launcher !== resolve(bin, process.platform === 'win32' ? 'dharma.cmd' : 'dharma')
+        || startup.policy !== resolve(workspace, '.dharma', 'approved-policy.json')) {
+        throw Error('device_signing_maintenance_managed_cohort_upgrade_required');
+    }
+    const readLauncher = async (name) => {
+        const path = resolve(bin, name), before = await lstat(path);
+        if (!before.isFile() || before.isSymbolicLink() || before.size > 65536 || await realpath(path) !== path) {
+            throw Error('device_signing_maintenance_managed_cohort_upgrade_required');
+        }
+        const contents = await readFile(path, 'utf8'), after = await lstat(path);
+        if (after.ino !== before.ino || after.dev !== before.dev || after.size !== before.size
+            || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs || after.isSymbolicLink()) {
+            throw Error('device_signing_maintenance_managed_cohort_upgrade_required');
+        }
+        return contents;
+    };
+    const launchers = { shell: await readLauncher('dharma'), windows: await readLauncher('dharma.cmd') };
+    if (!await verifyRecordedRepositoryLaunchers(VERSION, launchers)) {
+        throw Error('device_signing_maintenance_managed_cohort_upgrade_required');
+    }
+    return sha256(JSON.stringify({ schema: 'dharma.managed-signing-maintenance-cohort/v1', startup, launchers }));
+}
 export async function withWorkspacePolicyRefreshLock(workspaceId, operation) {
     if (!workspaceId)
         throw new Error('Content transmission requires a registered workspace ID.');
@@ -5246,498 +5331,522 @@ async function namedSessionCommand(action, flags) {
     if (process.platform !== 'linux')
         throw new Error('codex_session_sandbox_unqualified');
     const workspaceId = required(flags, 'workspace-id');
-    let childMessage;
-    if (flags.has('setup-handoff')) {
-        if (action !== 'serve' || flags.get('setup-handoff') !== true
-            || [...flags.keys()].some(key => !['name', 'workspace-id', 'apply', 'setup-handoff'].includes(key))) {
-            throw new Error('setup_child_unavailable');
-        }
-        childMessage = await receiveCodexSetupChildStart({ process, signal: new AbortController().signal });
-    }
-    const item = (await step(() => registry())).find(row => row.workspaceId === workspaceId);
-    const config = await step(() => readDeviceConfig());
-    if (!item || !config || item.organizationId !== config.organizationId)
-        throw new Error('named_session_scope_mismatch');
-    await assertBootstrapHostSource(item.path, String(item.repositoryRemoteHash || ''));
-    const scope = repositoryRoleScope(item);
-    const existing = await step(() => readNamedSession(dharmaHome(), name));
-    if (setupSessionScope && (name !== setupSessionScope.request.name || workspaceId !== setupSessionScope.request.workspaceId
-        || existing && existing.identity.membershipId !== setupSessionScope.request.membershipId))
-        throw new Error('setup_session_scope_changed');
-    if (existing && (existing.identity.workspaceId !== item.workspaceId
-        || existing.identity.organizationId !== config.organizationId || existing.identity.deviceId !== config.deviceId
-        || existing.identity.endpointId !== scope.endpointId || existing.identity.repositoryBindingId !== scope.repositoryBindingId)) {
-        throw new Error('named_session_scope_mismatch');
-    }
-    if (action === 'status') {
-        try {
-            return await namedSessionRequest(dharmaHome(), name, { action: 'status' });
-        }
-        catch {
-            return { ok: true, name, state: 'stopped', registered: Boolean(existing), enabled: existing?.enabled ?? false,
-                bindingId: existing?.bindingId ?? null };
-        }
-    }
-    if (action === 'readiness') {
-        if (!existing?.enabled)
-            throw new Error('named_session_readiness_unavailable');
-        let result;
-        try {
-            result = await namedSessionRequest(dharmaHome(), name, { action: 'readiness' }, { diagnostic });
-        }
-        catch (error) {
-            if (diagnostic && error instanceof NamedSessionTransportFailure)
-                return namedSessionReadinessDiagnostic(existing, error);
-            throw error;
-        }
-        if (Object.keys(result).sort().join(',') !== 'bindingId,deviceId,endpointId,membershipId,name,nativeSkill,ok,organizationId,provider,repositoryBindingId,schema,sessionId,workspaceId'
-            || result.schema !== 'dharma.named-session-readiness/v1' || result.name !== name || result.bindingId !== existing.bindingId
-            || typeof result.sessionId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$(?![\s\S])/.test(result.sessionId)
-            || Object.entries(existing.identity).some(([key, value]) => result[key] !== value)) {
-            throw new Error('named_session_readiness_scope_mismatch');
+    let startupAdmission;
+    const releaseStartupAdmission = async () => {
+        const release = startupAdmission;
+        startupAdmission = undefined;
+        await release?.();
+    };
+    try {
+        if (['start', 'serve'].includes(action) && flags.has('apply')) {
+            startupAdmission = await step(() => acquireNamedSessionStartupAdmission());
         }
-        return { ...result, nativeSkill: parseNamedCodexSkillObservation(result.nativeSkill) };
-    }
-    if (action === 'work')
-        return namedSessionRequest(dharmaHome(), name, { action: 'work',
-            workId: String(flags.get('work-id') || randomUUID()), prompt: required(flags, 'prompt') });
-    if (['quiesce', 'resume'].includes(action) || action === 'stop' && flags.has('drained')) {
-        const allowed = ['name', 'workspace-id', 'fence-id', 'apply', 'dry-run', 'json',
-            ...(action === 'stop' ? ['drained'] : action === 'resume' ? ['recover-stopped'] : [])];
-        if (hostScope || supervisorOwner || setupSessionScope || !existing
-            || [...flags.keys()].some(key => !allowed.includes(key))
-            || ['apply', 'dry-run', 'drained', 'recover-stopped', 'json'].some(key => flags.has(key) && flags.get(key) !== true)
-            || flags.has('apply') && flags.has('dry-run'))
-            throw new Error('named_session_maintenance_unavailable');
-        const fenceId = required(flags, 'fence-id');
-        if (!UUID_PATTERN.test(fenceId))
-            throw new Error('named_session_fence_invalid');
-        const requestAction = action === 'stop' ? 'stop-drained' : action;
-        if (!flags.has('apply'))
-            return { ok: true, planned: true, name, workspaceId, action: requestAction, fenceId,
-                mode: flags.has('recover-stopped') ? 'stopped_recovery' : 'live' };
-        if (action === 'resume' && flags.has('recover-stopped'))
-            return withRelayStartupMutation(async () => {
-                let vault;
-                try {
-                    return await recoverStoppedNamedSession({ registration: existing, fenceId, workspace: item.path,
-                        processState: () => pidProcessState(resolve(paths.root, 'service.lock')),
-                        readRegistration: () => readNamedSession(dharmaHome(), name),
-                        readBinding: async () => {
-                            vault = await openBootstrapVault({ root: resolve(dharmaHome(), 'vault') });
-                            return vault.getProviderSessionBinding(existing.bindingId, existing.identity);
-                        },
-                        saveRegistration: value => saveNamedSession(dharmaHome(), value) });
-                }
-                finally {
-                    await vault?.close();
-                }
-            });
-        return maintainNamedSession({ action: requestAction, fenceId,
-            registration: existing, request: body => namedSessionRequest(dharmaHome(), name, body) });
-    }
-    if (action === 'audit') {
-        if (!existing?.enabled || [...flags.keys()].some(key => !['name', 'workspace-id', 'work-id'].includes(key))) {
-            throw new Error('named_session_audit_unavailable');
-        }
-        const workId = required(flags, 'work-id');
-        if (!/^[A-Za-z0-9_-]{1,128}$(?![\s\S])/.test(workId))
-            throw new Error('named_session_work_invalid');
-        const result = await namedSessionRequest(dharmaHome(), name, { action: 'audit', workId });
-        if (!(await validateContract(resolve(dirname(fileURLToPath(import.meta.url)), 'schemas'), 'https://schemas.dharma-ai.io/named-session-native-audit/v1', result)).ok
-            || result.bindingId !== existing.bindingId || result.workId !== workId
-            || Object.entries(existing.identity).some(([key, value]) => result[key] !== value)) {
-            throw new Error('named_session_audit_scope_mismatch');
+        let childMessage;
+        if (flags.has('setup-handoff')) {
+            if (action !== 'serve' || flags.get('setup-handoff') !== true
+                || [...flags.keys()].some(key => !['name', 'workspace-id', 'apply', 'setup-handoff'].includes(key))) {
+                throw new Error('setup_child_unavailable');
+            }
+            childMessage = await receiveCodexSetupChildStart({ process, signal: new AbortController().signal });
         }
-        return result;
-    }
-    if (action === 'stop') {
-        if (!flags.has('apply'))
-            return { ok: true, planned: true, name, action: 'stop' };
-        const current = await namedSessionRequest(dharmaHome(), name, { action: 'status' }).catch(() => null);
-        if (current?.admission) {
-            if (!existing || current.bindingId !== existing.bindingId
-                || Object.entries(existing.identity).some(([key, value]) => current[key] !== value)) {
-                throw new Error('named_session_scope_mismatch');
-            }
-            // The capable service rejects an unfenced stop without changing its registration.
-            return namedSessionRequest(dharmaHome(), name, { action: 'stop' });
-        }
-        if (existing)
-            await saveNamedSession(dharmaHome(), { ...existing, enabled: false });
-        try {
-            return await namedSessionRequest(dharmaHome(), name, { action: 'stop' });
+        const item = (await step(() => registry())).find(row => row.workspaceId === workspaceId);
+        const config = await step(() => readDeviceConfig());
+        if (!item || !config || item.organizationId !== config.organizationId)
+            throw new Error('named_session_scope_mismatch');
+        await assertBootstrapHostSource(item.path, String(item.repositoryRemoteHash || ''));
+        const scope = repositoryRoleScope(item);
+        const existing = await step(() => readNamedSession(dharmaHome(), name));
+        if (setupSessionScope && (name !== setupSessionScope.request.name || workspaceId !== setupSessionScope.request.workspaceId
+            || existing && existing.identity.membershipId !== setupSessionScope.request.membershipId))
+            throw new Error('setup_session_scope_changed');
+        if (existing && (existing.identity.workspaceId !== item.workspaceId
+            || existing.identity.organizationId !== config.organizationId || existing.identity.deviceId !== config.deviceId
+            || existing.identity.endpointId !== scope.endpointId || existing.identity.repositoryBindingId !== scope.repositoryBindingId)) {
+            throw new Error('named_session_scope_mismatch');
         }
-        catch {
-            return { ok: true, name, state: 'stopped', enabled: false };
+        if (action === 'status') {
+            try {
+                return await namedSessionRequest(dharmaHome(), name, { action: 'status' });
+            }
+            catch {
+                return { ok: true, name, state: 'stopped', registered: Boolean(existing), enabled: existing?.enabled ?? false,
+                    bindingId: existing?.bindingId ?? null };
+            }
         }
-    }
-    if (!['start', 'serve'].includes(action))
-        throw new Error('named_session_action_invalid');
-    if (!flags.has('apply'))
-        return { ok: true, planned: true, name, workspaceId,
-            provider: 'codex', localWork: 'workspace_write', peerQuestions: 'read_only', network: 'deny' };
-    await step(async () => verifyNamedSessionVisibleSkill(await verifyAgentFabricSkillInstallation({ provider: 'codex', workspace: item.path }), await repositorySharedReady(item)));
-    if (action === 'start') {
-        if (existing && !existing.enabled) {
-            if (existing.maintenanceFence) {
-                if (hostScope || supervisorOwner || setupSessionScope || !flags.has('fence-id') || flags.get('apply') !== true
-                    || [...flags.keys()].some(key => !['name', 'workspace-id', 'fence-id', 'apply', 'json'].includes(key))) {
-                    throw new Error('named_session_quiesced');
-                }
-                await withRelayStartupMutation(() => activateMaintenanceRestart({ registration: existing, fenceId: required(flags, 'fence-id'),
-                    processState: () => pidProcessState(resolve(paths.root, 'service.lock')),
-                    readRegistration: () => readNamedSession(dharmaHome(), name), saveRegistration: value => saveNamedSession(dharmaHome(), value) }));
+        if (action === 'readiness') {
+            if (!existing?.enabled)
+                throw new Error('named_session_readiness_unavailable');
+            let result;
+            try {
+                result = await namedSessionRequest(dharmaHome(), name, { action: 'readiness' }, { diagnostic });
             }
-            else {
-                if (supervisorOwner)
-                    throw new Error('named_session_disabled');
-                const live = await step(() => namedSessionRequest(dharmaHome(), name, { action: 'status' })).catch(() => null);
-                if (live?.admission && live.admission.state !== 'open') {
-                    throw new Error('named_session_quiesced');
-                }
-                await step(() => saveNamedSession(dharmaHome(), { ...existing, enabled: true }));
+            catch (error) {
+                if (diagnostic && error instanceof NamedSessionTransportFailure)
+                    return namedSessionReadinessDiagnostic(existing, error);
+                throw error;
+            }
+            if (Object.keys(result).sort().join(',') !== 'bindingId,deviceId,endpointId,membershipId,name,nativeSkill,ok,organizationId,provider,repositoryBindingId,schema,sessionId,workspaceId'
+                || result.schema !== 'dharma.named-session-readiness/v1' || result.name !== name || result.bindingId !== existing.bindingId
+                || typeof result.sessionId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$(?![\s\S])/.test(result.sessionId)
+                || Object.entries(existing.identity).some(([key, value]) => result[key] !== value)) {
+                throw new Error('named_session_readiness_scope_mismatch');
+            }
+            return { ...result, nativeSkill: parseNamedCodexSkillObservation(result.nativeSkill) };
+        }
+        if (action === 'work')
+            return namedSessionRequest(dharmaHome(), name, { action: 'work',
+                workId: String(flags.get('work-id') || randomUUID()), prompt: required(flags, 'prompt') });
+        if (['quiesce', 'resume'].includes(action) || action === 'stop' && flags.has('drained')) {
+            const allowed = ['name', 'workspace-id', 'fence-id', 'apply', 'dry-run', 'json',
+                ...(action === 'stop' ? ['drained'] : action === 'resume' ? ['recover-stopped'] : [])];
+            if (hostScope || supervisorOwner || setupSessionScope || !existing
+                || [...flags.keys()].some(key => !allowed.includes(key))
+                || ['apply', 'dry-run', 'drained', 'recover-stopped', 'json'].some(key => flags.has(key) && flags.get(key) !== true)
+                || flags.has('apply') && flags.has('dry-run'))
+                throw new Error('named_session_maintenance_unavailable');
+            const fenceId = required(flags, 'fence-id');
+            if (!UUID_PATTERN.test(fenceId))
+                throw new Error('named_session_fence_invalid');
+            const requestAction = action === 'stop' ? 'stop-drained' : action;
+            if (!flags.has('apply'))
+                return { ok: true, planned: true, name, workspaceId, action: requestAction, fenceId,
+                    mode: flags.has('recover-stopped') ? 'stopped_recovery' : 'live' };
+            if (action === 'resume' && flags.has('recover-stopped'))
+                return withRelayStartupMutation(async () => {
+                    let vault;
+                    try {
+                        return await recoverStoppedNamedSession({ registration: existing, fenceId, workspace: item.path,
+                            processState: () => pidProcessState(resolve(paths.root, 'service.lock')),
+                            readRegistration: () => readNamedSession(dharmaHome(), name),
+                            readBinding: async () => {
+                                vault = await openBootstrapVault({ root: resolve(dharmaHome(), 'vault') });
+                                return vault.getProviderSessionBinding(existing.bindingId, existing.identity);
+                            },
+                            saveRegistration: value => saveNamedSession(dharmaHome(), value) });
+                    }
+                    finally {
+                        await vault?.close();
+                    }
+                });
+            return maintainNamedSession({ action: requestAction, fenceId,
+                registration: existing, request: body => namedSessionRequest(dharmaHome(), name, body) });
+        }
+        if (action === 'audit') {
+            if (!existing?.enabled || [...flags.keys()].some(key => !['name', 'workspace-id', 'work-id'].includes(key))) {
+                throw new Error('named_session_audit_unavailable');
+            }
+            const workId = required(flags, 'work-id');
+            if (!/^[A-Za-z0-9_-]{1,128}$(?![\s\S])/.test(workId))
+                throw new Error('named_session_work_invalid');
+            const result = await namedSessionRequest(dharmaHome(), name, { action: 'audit', workId });
+            if (!(await validateContract(resolve(dirname(fileURLToPath(import.meta.url)), 'schemas'), 'https://schemas.dharma-ai.io/named-session-native-audit/v1', result)).ok
+                || result.bindingId !== existing.bindingId || result.workId !== workId
+                || Object.entries(existing.identity).some(([key, value]) => result[key] !== value)) {
+                throw new Error('named_session_audit_scope_mismatch');
             }
+            return result;
         }
-        try {
-            return await step(() => namedSessionRequest(dharmaHome(), name, { action: 'status' }));
-        }
-        catch { /* Start an owned worker below. */ }
-        const args = [fileURLToPath(import.meta.url), 'sessions', 'serve', '--name', name,
-            '--workspace-id', workspaceId, '--apply'];
-        if (setupSessionScope)
-            args.push('--setup-handoff');
-        for (const key of ['session-budget-cents', 'turn-budget-cents']) {
-            if (flags.has(key))
-                args.push(`--${key}`, required(flags, key));
-        }
-        let startupChild;
-        try {
-            await step(async () => {
-                const start = () => {
-                    const child = spawn(process.execPath, args, { cwd: item.path, detached: !hostScope && !supervisorOwner,
-                        stdio: setupSessionScope ? ['ignore', 'ignore', 'pipe', 'ipc'] : ['ignore', 'ignore', 'pipe'], env: process.env });
-                    startupChild = observeNamedSessionStartupChild(child);
-                    return child;
-                };
-                if (supervisorOwner) {
-                    const child = await supervisorOwner.spawn(name, start);
-                    if (setupSessionScope)
-                        await sendCodexSetupChildStart({ owner: supervisorOwner, child, scope: setupSessionScope });
-                    return;
-                }
-                const child = start();
-                if (hostScope)
-                    captureBootstrapHostChild(hostScope, child);
-                else {
-                    child.on('error', () => { });
-                    child.unref();
+        if (action === 'stop') {
+            if (!flags.has('apply'))
+                return { ok: true, planned: true, name, action: 'stop' };
+            const current = await namedSessionRequest(dharmaHome(), name, { action: 'status' }).catch(() => null);
+            if (current?.admission) {
+                if (!existing || current.bindingId !== existing.bindingId
+                    || Object.entries(existing.identity).some(([key, value]) => current[key] !== value)) {
+                    throw new Error('named_session_scope_mismatch');
                 }
-            });
-            return await waitForNamedSessionStartup({ step,
-                assertActive: async () => { await hostScope?.assert(); },
-                observe: () => namedSessionRequest(dharmaHome(), name, { action: 'status' }),
-                readFailure: () => startupChild?.readFailure(),
-                maximumWaitMs: setupSessionScope
-                    ? Math.min(120_000, Date.parse(setupSessionScope.request.expiresAt) - Date.now()) : 120_000 });
-        }
-        finally {
-            startupChild?.dispose();
-        }
-    }
-    await mkdir(paths.root, { recursive: true, mode: 0o700 });
-    const vault = await openBootstrapVault({ root: resolve(dharmaHome(), 'vault') })
-        .catch(error => { throw namedSessionStartupPhaseError('vault', error); });
-    let releaseLock;
-    const controller = new AbortController(), stop = () => controller.abort();
-    process.once('SIGTERM', stop);
-    process.once('SIGINT', stop);
-    if (childMessage)
-        process.once('disconnect', stop);
-    let transport;
-    try {
-        releaseLock = await acquirePidLock(resolve(paths.root, 'service.lock'), 250, 'named_session_already_running')
-            .catch(error => { throw namedSessionStartupPhaseError('lock', error); });
-        // A startup poll may predate quiescence. Recheck durable admission after winning the owner lock.
-        assertNamedSessionStartupRegistration(existing, await step(() => readNamedSession(dharmaHome(), name)));
-        const startProvider = async (childScope) => {
-            let startupPhase = 'client';
+                // The capable service rejects an unfenced stop without changing its registration.
+                return namedSessionRequest(dharmaHome(), name, { action: 'stop' });
+            }
+            if (existing)
+                await saveNamedSession(dharmaHome(), { ...existing, enabled: false });
             try {
-                const startupStep = (operation) => childScope ? childScope.step(operation) : operation();
-                if (childScope && existing && existing.identity.membershipId !== childScope.request.membershipId) {
-                    throw new Error('setup_child_unavailable');
-                }
-                const fabric = await startupStep(() => AgentFabricClient.open({ configPath: configPath(), statePath: resolve(paths.root, 'protocol-state.json'),
-                    hostScope: currentBootstrapHostScope() }));
-                if (fabric.config.organizationId !== config.organizationId || fabric.config.deviceId !== config.deviceId
-                    || fabric.config.publicKeyEd25519 !== config.publicKeyEd25519)
-                    throw new Error('named_session_trust_scope_mismatch');
-                startupPhase = 'trust';
-                const trust = createNamedSessionTrust({ configPath: configPath(), identity: fabric.config });
-                await startupStep(() => trust.refresh());
-                startupPhase = 'session';
-                await startupStep(() => fabric.openSession(VERSION));
-                startupPhase = 'policy';
-                const policyPath = resolve(item.path, '.dharma', 'approved-policy.json');
-                const policy = await startupStep(() => refreshVerifiedWorkspacePolicyForTransmission(policyPath, workspaceId, fabric));
-                const writeRoots = policy.tasks.writePaths.filter(path => /^[a-zA-Z0-9_-]+\/\*\*$/.test(path))
-                    .map(path => path.slice(0, -3));
-                if (!writeRoots.length)
-                    throw new Error('named_session_workspace_write_not_authorized');
-                startupPhase = 'registration';
-                let registration = existing, pending;
-                let ownerReceipt;
-                // Resolve authenticated ownership before opening any provider transport.
-                if (registration) {
-                    const response = await startupStep(() => fabric.signedPost('/agent-fabric/provider-sessions', {
-                        schema: 'dharma.provider-session-registration/v1', action: 'inspect', provider: 'codex', mode: 'bridge_owned',
-                        workspaceId, endpointId: scope.endpointId, repositoryBindingId: scope.repositoryBindingId,
-                        bindingId: registration.bindingId, expectedRevision: 0, leaseSeconds: 60,
-                    }));
-                    if (!isNamedSessionReconnectReceipt(response, registration.bindingId, registration.identity)) {
-                        throw new Error('named_session_registration_invalid');
+                return await namedSessionRequest(dharmaHome(), name, { action: 'stop' });
+            }
+            catch {
+                return { ok: true, name, state: 'stopped', enabled: false };
+            }
+        }
+        if (!['start', 'serve'].includes(action))
+            throw new Error('named_session_action_invalid');
+        if (!flags.has('apply'))
+            return { ok: true, planned: true, name, workspaceId,
+                provider: 'codex', localWork: 'workspace_write', peerQuestions: 'read_only', network: 'deny' };
+        await step(async () => verifyNamedSessionVisibleSkill(await verifyAgentFabricSkillInstallation({ provider: 'codex', workspace: item.path }), await repositorySharedReady(item)));
+        if (action === 'start') {
+            if (existing && !existing.enabled) {
+                if (existing.maintenanceFence) {
+                    if (hostScope || supervisorOwner || setupSessionScope || !flags.has('fence-id') || flags.get('apply') !== true
+                        || [...flags.keys()].some(key => !['name', 'workspace-id', 'fence-id', 'apply', 'json'].includes(key))) {
+                        throw new Error('named_session_quiesced');
                     }
-                    ownerReceipt = response;
+                    await activateMaintenanceRestart({ registration: existing, fenceId: required(flags, 'fence-id'),
+                        processState: () => pidProcessState(resolve(paths.root, 'service.lock')),
+                        readRegistration: () => readNamedSession(dharmaHome(), name), saveRegistration: value => saveNamedSession(dharmaHome(), value) });
                 }
                 else {
-                    const maximumCostCents = boundedInteger(flags.get('session-budget-cents'), 1000, 1, 10000, '--session-budget-cents');
-                    const maximumTurnCostCents = boundedInteger(flags.get('turn-budget-cents'), 25, 1, maximumCostCents, '--turn-budget-cents');
-                    const bindingId = randomUUID();
-                    const response = await startupStep(() => fabric.signedPost('/agent-fabric/provider-sessions', {
-                        schema: 'dharma.provider-session-registration/v1', action: 'attach', provider: 'codex', mode: 'bridge_owned',
-                        workspaceId, endpointId: scope.endpointId, repositoryBindingId: scope.repositoryBindingId,
-                        bindingId, expectedRevision: 0, leaseSeconds: 60,
-                    }));
-                    const remote = response.registration;
-                    if (!remote || !UUID_PATTERN.test(String(remote.membershipId))
-                        || childScope && remote.membershipId !== childScope.request.membershipId || remote.revision !== 1) {
-                        throw new Error('named_session_registration_invalid');
+                    if (supervisorOwner)
+                        throw new Error('named_session_disabled');
+                    const live = await step(() => namedSessionRequest(dharmaHome(), name, { action: 'status' })).catch(() => null);
+                    if (live?.admission && live.admission.state !== 'open') {
+                        throw new Error('named_session_quiesced');
                     }
-                    const identity = { organizationId: config.organizationId, repositoryBindingId: scope.repositoryBindingId,
-                        workspaceId, endpointId: scope.endpointId, membershipId: String(remote.membershipId), deviceId: config.deviceId,
-                        provider: 'codex' };
-                    if (!isNamedSessionOwnerReceipt(response, bindingId, identity))
-                        throw new Error('named_session_registration_invalid');
-                    ownerReceipt = response;
-                    pending = { schema: 'dharma.named-session/v1', name, bindingId, identity,
-                        maximumCostCents, maximumTurnCostCents, enabled: true };
+                    await step(() => saveNamedSession(dharmaHome(), { ...existing, enabled: true }));
                 }
-                startupPhase = 'environment';
-                const environment = namedCodexEnvironment(process.env);
-                const privateRoots = [dharmaHome(), resolve(environment.CODEX_HOME || resolve(homedir(), '.codex'))];
-                if (environment.XDG_RUNTIME_DIR)
-                    privateRoots.push(environment.XDG_RUNTIME_DIR);
-                if (environment.DBUS_SESSION_BUS_ADDRESS)
-                    privateRoots.push(environment.DBUS_SESSION_BUS_ADDRESS.slice('unix:path='.length));
-                startupPhase = 'filesystem';
-                const filesystem = await startupStep(() => namedCodexFilesystem({ environment, workspace: item.path, privateRoots, writeRoots }));
-                startupPhase = 'transport';
-                await startupStep(async () => {
-                    const expectedOwner = registration ?? pending;
-                    const ownerConfirmed = registration
-                        ? isNamedSessionReconnectReceipt(ownerReceipt, expectedOwner.bindingId, expectedOwner.identity)
-                        : isNamedSessionOwnerReceipt(ownerReceipt, expectedOwner.bindingId, expectedOwner.identity);
-                    if (!ownerConfirmed) {
-                        throw new Error('named_session_registration_invalid');
+            }
+            try {
+                return await step(() => namedSessionRequest(dharmaHome(), name, { action: 'status' }));
+            }
+            catch { /* Start an owned worker below. */ }
+            const args = [fileURLToPath(import.meta.url), 'sessions', 'serve', '--name', name,
+                '--workspace-id', workspaceId, '--apply'];
+            if (setupSessionScope)
+                args.push('--setup-handoff');
+            for (const key of ['session-budget-cents', 'turn-budget-cents']) {
+                if (flags.has(key))
+                    args.push(`--${key}`, required(flags, key));
+            }
+            let startupChild;
+            try {
+                // The child takes this same admission lock before private startup. Never
+                // wait for it while holding its parent-side registration/enablement lock.
+                await releaseStartupAdmission();
+                await step(async () => {
+                    const start = () => {
+                        const child = spawn(process.execPath, args, { cwd: item.path, detached: !hostScope && !supervisorOwner,
+                            stdio: setupSessionScope ? ['ignore', 'ignore', 'pipe', 'ipc'] : ['ignore', 'ignore', 'pipe'], env: process.env });
+                        startupChild = observeNamedSessionStartupChild(child);
+                        return child;
+                    };
+                    if (supervisorOwner) {
+                        const child = await supervisorOwner.spawn(name, start);
+                        if (setupSessionScope)
+                            await sendCodexSetupChildStart({ owner: supervisorOwner, child, scope: setupSessionScope });
+                        return;
+                    }
+                    const child = start();
+                    if (hostScope)
+                        captureBootstrapHostChild(hostScope, child);
+                    else {
+                        child.on('error', () => { });
+                        child.unref();
                     }
-                    transport = await openCodexAppServerTransport({ command: filesystem.providerExecutable, cwd: item.path,
-                        environment: filesystem.environment, experimentalApi: true, toolCallTimeoutMs: 60_000,
-                        argv: [...namedCodexNodeOutputArguments(), '-c', 'allow_login_shell=false', '-c', 'default_permissions="dharma_bridge"',
-                            '-c', `permissions.dharma_bridge.filesystem=${filesystem.peer}`,
-                            '-c', 'permissions.dharma_bridge.network={enabled=false}',
-                            '-c', `permissions.dharma_work.filesystem=${filesystem.work}`,
-                            '-c', 'permissions.dharma_work.network={enabled=false}', 'app-server'] });
-                    return transport;
                 });
-                startupPhase = 'account';
-                const account = await startupStep(() => transport.request('account/read', { refreshToken: false }));
-                if (!account.account)
-                    throw new Error('named_session_provider_authentication_required');
-                if (pending) {
-                    startupPhase = 'thread';
-                    const threadId = await startupStep(() => startNamedCodexThread(transport, item.path, name));
-                    startupPhase = 'binding';
-                    await startupStep(async () => vault.saveProviderSessionBinding({ schema: 'dharma.local-provider-session-binding/v1', ...pending.identity,
-                        bindingId: pending.bindingId, owner: 'dharma_bridge', sessionId: threadId, workspaceRoot: item.path,
-                        createdAt: new Date().toISOString(), expiresAt: new Date(Date.now() + 30 * 86400000).toISOString(),
-                        maximumProviderCostCents: pending.maximumTurnCostCents }));
-                    registration = pending;
-                    await startupStep(async () => saveNamedSession(dharmaHome(), registration));
-                }
-                return { registration: registration, filesystem, fabric, trust, policyPath, writeRoots };
-            }
-            catch (error) {
-                throw namedSessionStartupPhaseError(startupPhase, error);
+                return await waitForNamedSessionStartup({ step,
+                    assertActive: async () => { await hostScope?.assert(); },
+                    observe: () => namedSessionRequest(dharmaHome(), name, { action: 'status' }),
+                    readFailure: () => startupChild?.readFailure(),
+                    maximumWaitMs: setupSessionScope
+                        ? Math.min(120_000, Date.parse(setupSessionScope.request.expiresAt) - Date.now()) : 120_000 });
             }
-        };
-        const { registration, filesystem, fabric, trust, policyPath, writeRoots } = childMessage
-            ? await runCodexSetupChildStartup({ vault: vault, message: childMessage, name, workspaceId,
-                signal: controller.signal, authorize: qualifyCodexSetupChildRequest }, startProvider)
-            : await startProvider();
-        const authorizeLifetime = async () => {
-            const current = await refreshVerifiedWorkspacePolicyForTransmission(policyPath, workspaceId, fabric);
-            if (!writeRoots.every(root => current.tasks.writePaths.includes(`${root}/**`)))
-                return false;
-            const response = await fabric.signedPost('/agent-fabric/provider-sessions', {
-                schema: 'dharma.provider-session-registration/v1', action: 'inspect', provider: 'codex', mode: 'bridge_owned',
-                workspaceId, endpointId: scope.endpointId, repositoryBindingId: scope.repositoryBindingId,
-                bindingId: registration.bindingId, expectedRevision: 0, leaseSeconds: 60,
-            });
-            return isNamedSessionOwnerReceipt(response, registration.bindingId, registration.identity);
-        };
-        const refreshLifetime = () => renewNamedSessionLifetime({ vault, bindingId: registration.bindingId,
-            identity: registration.identity, trust, authorize: authorizeLifetime });
-        await refreshLifetime().catch(error => { throw namedSessionStartupPhaseError('lifetime', error); });
-        const channelTransport = { async signedPost(route, body) {
-                await trust.refresh();
-                const response = await fabric.signedPost(route, body);
-                await trust.refresh();
-                return response;
-            } };
-        // Fresh server acceptance and this live-owner claim fence peer execution;
-        // durable reservations retain cost even when delivery or execution is uncertain.
-        const consumed = new Set();
-        let taskState = null;
-        let taskStateFailure = 'source_state_unavailable';
-        const taskSnapshot = async () => {
-            const sourceAuthorization = await fetchRepositorySourceAuthorization(fabric, repositoryRoleScope(item));
-            return inventoryRepositoryPackage({ workspace: item.path, organizationId: item.organizationId,
-                workspaceId, repositoryBindingId: item.repositoryBindingId, repositoryAgentId: item.repositoryAgentId, sourceAuthorization });
-        };
-        const readCurrentRepositoryContext = async (contentMode = 'references', referenceText) => readNamedSessionRepositoryContext({
-            installation: await verifyAgentFabricSkillInstallation({ provider: 'codex', workspace: item.path }),
-            sharedRepositoryReady: await repositorySharedReady(item), scope: repositoryRoleScope(item), workspaceRoot: item.path, contentMode, referenceText,
-            loadAuthority: async () => ({ policy: await refreshVerifiedWorkspacePolicyForTransmission(policyPath, workspaceId, fabric),
-                source: await fetchRepositorySourceAuthorization(fabric, repositoryRoleScope(item)) })
-        });
-        return await runNamedSessionService({ home: dharmaHome(), registration, vault, signal: controller.signal,
-            localWriteRoots: writeRoots, additionalFilesystemRules: filesystem.additionalFilesystemRules,
-            readPeerRepositoryContext: question => readCurrentRepositoryContext('verified_inline', question.question),
-            observeNativeSkill: async () => {
-                const installation = await verifyAgentFabricSkillInstallation({ provider: 'codex', workspace: item.path });
-                const native = await observeNamedCodexSkill(transport, { workspace: item.path, installation,
-                    sharedRepositoryReady: await repositorySharedReady(item) });
-                const current = await verifyAgentFabricSkillInstallation({ provider: 'codex', workspace: item.path });
-                if (!current.signedLifecycleReady || current.activeBundleId !== native.bundleId
-                    || current.activeBundleHash !== native.bundleHash || current.nativeSkillPath !== installation.nativeSkillPath
-                    || !await repositorySharedReady(item))
-                    throw new Error('named_session_native_skill_unavailable');
-                return native;
-            },
-            syncTaskExports: () => syncNamedSessionTaskExports({ vault, bindingId: registration.bindingId,
-                identity: registration.identity,
-                loadPolicy: () => refreshVerifiedWorkspacePolicyForTransmission(policyPath, workspaceId, fabric),
-                send: body => fabric.signedPost('/agent-fabric/codex-task-exports', body) }),
-            withActivationBoundary: (operation, work) => withWorkspaceSkillActivationLock(workspaceId, 'codex', async () => {
-                await refreshLifetime();
-                const skill = await verifyAgentFabricSkillInstallation({ provider: 'codex', workspace: item.path });
-                const sharedReady = await repositorySharedReady(item);
-                const packageContent = await readNamedSessionPackageContent(skill, sharedReady);
-                const bundleId = packageContent.bundleId;
-                taskState = null;
-                taskStateFailure = 'source_state_unavailable';
-                if (work) {
-                    const current = await loadVerifiedWorkspacePolicy(policyPath, workspaceId);
-                    if (current.evidence.automaticDisclosure?.mode === 'customer_authorized_content' && skill.activeBundleHash) {
-                        try {
-                            taskStateFailure = 'public_context_unavailable';
-                            const binding = await vault.getProviderSessionBinding(registration.bindingId, registration.identity);
-                            if (!binding)
-                                throw new Error('named_session_binding_unavailable');
-                            const retained = await readCodexPublicContext(transport, { threadId: binding.sessionId, workspaceRoot: binding.workspaceRoot });
-                            taskStateFailure = 'runtime_version_unavailable';
-                            const version = (await execFileAsync('codex', ['--version'], { timeout: 10_000, maxBuffer: 4096,
-                                env: providerProcessEnvironment(process.env) })).stdout.trim();
-                            if (!/^codex-cli [0-9]+\.[0-9]+\.[0-9]+(?:[-+][a-zA-Z0-9.-]+)?$/.test(version)) {
-                                throw new Error('named_session_runtime_version_unavailable');
-                            }
-                            const contextContentHash = await vault.putBlob(Buffer.from(retained.bytes), 'named-session-public-context');
-                            if (contextContentHash !== retained.contextHash)
-                                throw new Error('named_session_context_integrity_failed');
-                            taskStateFailure = 'source_state_unavailable';
-                            const before = await taskSnapshot();
-                            const sourceContentHash = await vault.putBlob(Buffer.from(serializeRepositoryPackageSnapshot(before)), 'named-session-source-state');
-                            await vault.putBlob(Buffer.from(JSON.stringify({ workId: work.workId, bindingId: registration.bindingId,
-                                sourceContentHash, sourceSnapshotHash: before.manifest.snapshotHash, bundleId, bundleHash: skill.activeBundleHash,
-                                packageContent, contextContentHash, evidenceRevision: current.revision,
-                                consentReceiptId: current.evidence.automaticDisclosure.consentReceiptId })), 'named-session-source-boundary');
-                            taskState = { workId: work.workId, before, bundleId, bundleHash: skill.activeBundleHash, packageContent,
-                                evidenceRevision: current.revision, consentReceiptId: current.evidence.automaticDisclosure.consentReceiptId,
-                                providerContext: { retainedContextHash: retained.contextHash, contextContentHash,
-                                    runtimeVersion: version.slice('codex-cli '.length), requestedModel: retained.context.configuredModel,
-                                    executedModel: null, replayMode: 'task_level' } };
+            finally {
+                startupChild?.dispose();
+            }
+        }
+        await mkdir(paths.root, { recursive: true, mode: 0o700 });
+        const vault = await openBootstrapVault({ root: resolve(dharmaHome(), 'vault') })
+            .catch(error => { throw namedSessionStartupPhaseError('vault', error); });
+        let releaseLock;
+        const controller = new AbortController(), stop = () => controller.abort();
+        process.once('SIGTERM', stop);
+        process.once('SIGINT', stop);
+        if (childMessage)
+            process.once('disconnect', stop);
+        let transport;
+        try {
+            releaseLock = await acquirePidLock(resolve(paths.root, 'service.lock'), 250, 'named_session_already_running')
+                .catch(error => { throw namedSessionStartupPhaseError('lock', error); });
+            // A startup poll may predate quiescence. Recheck durable admission after winning the owner lock.
+            assertNamedSessionStartupRegistration(existing, await step(() => readNamedSession(dharmaHome(), name)));
+            // Once the per-service lock is held, maintenance cannot acquire its stopped
+            // topology. Release home-wide admission before the long-lived provider loop.
+            await releaseStartupAdmission();
+            const startProvider = async (childScope) => {
+                let startupPhase = 'client';
+                try {
+                    const startupStep = (operation) => childScope ? childScope.step(operation) : operation();
+                    if (childScope && existing && existing.identity.membershipId !== childScope.request.membershipId) {
+                        throw new Error('setup_child_unavailable');
+                    }
+                    const fabric = await startupStep(() => AgentFabricClient.open({ configPath: configPath(), statePath: resolve(paths.root, 'protocol-state.json'),
+                        hostScope: currentBootstrapHostScope() }));
+                    if (fabric.config.organizationId !== config.organizationId || fabric.config.deviceId !== config.deviceId
+                        || fabric.config.publicKeyEd25519 !== config.publicKeyEd25519)
+                        throw new Error('named_session_trust_scope_mismatch');
+                    startupPhase = 'trust';
+                    const trust = createNamedSessionTrust({ configPath: configPath(), identity: fabric.config });
+                    await startupStep(() => trust.refresh());
+                    startupPhase = 'session';
+                    await startupStep(() => fabric.openSession(VERSION));
+                    startupPhase = 'policy';
+                    const policyPath = resolve(item.path, '.dharma', 'approved-policy.json');
+                    const policy = await startupStep(() => refreshVerifiedWorkspacePolicyForTransmission(policyPath, workspaceId, fabric));
+                    const writeRoots = policy.tasks.writePaths.filter(path => /^[a-zA-Z0-9_-]+\/\*\*$/.test(path))
+                        .map(path => path.slice(0, -3));
+                    if (!writeRoots.length)
+                        throw new Error('named_session_workspace_write_not_authorized');
+                    startupPhase = 'registration';
+                    let registration = existing, pending;
+                    let ownerReceipt;
+                    // Resolve authenticated ownership before opening any provider transport.
+                    if (registration) {
+                        const response = await startupStep(() => fabric.signedPost('/agent-fabric/provider-sessions', {
+                            schema: 'dharma.provider-session-registration/v1', action: 'inspect', provider: 'codex', mode: 'bridge_owned',
+                            workspaceId, endpointId: scope.endpointId, repositoryBindingId: scope.repositoryBindingId,
+                            bindingId: registration.bindingId, expectedRevision: 0, leaseSeconds: 60,
+                        }));
+                        if (!isNamedSessionReconnectReceipt(response, registration.bindingId, registration.identity)) {
+                            throw new Error('named_session_registration_invalid');
                         }
-                        catch { /* Source capture failure must not replay or rewrite a coding task. */ }
+                        ownerReceipt = response;
                     }
+                    else {
+                        const maximumCostCents = boundedInteger(flags.get('session-budget-cents'), 1000, 1, 10000, '--session-budget-cents');
+                        const maximumTurnCostCents = boundedInteger(flags.get('turn-budget-cents'), 25, 1, maximumCostCents, '--turn-budget-cents');
+                        const bindingId = randomUUID();
+                        const response = await startupStep(() => fabric.signedPost('/agent-fabric/provider-sessions', {
+                            schema: 'dharma.provider-session-registration/v1', action: 'attach', provider: 'codex', mode: 'bridge_owned',
+                            workspaceId, endpointId: scope.endpointId, repositoryBindingId: scope.repositoryBindingId,
+                            bindingId, expectedRevision: 0, leaseSeconds: 60,
+                        }));
+                        const remote = response.registration;
+                        if (!remote || !UUID_PATTERN.test(String(remote.membershipId))
+                            || childScope && remote.membershipId !== childScope.request.membershipId || remote.revision !== 1) {
+                            throw new Error('named_session_registration_invalid');
+                        }
+                        const identity = { organizationId: config.organizationId, repositoryBindingId: scope.repositoryBindingId,
+                            workspaceId, endpointId: scope.endpointId, membershipId: String(remote.membershipId), deviceId: config.deviceId,
+                            provider: 'codex' };
+                        if (!isNamedSessionOwnerReceipt(response, bindingId, identity))
+                            throw new Error('named_session_registration_invalid');
+                        ownerReceipt = response;
+                        pending = { schema: 'dharma.named-session/v1', name, bindingId, identity,
+                            maximumCostCents, maximumTurnCostCents, enabled: true };
+                    }
+                    startupPhase = 'environment';
+                    const environment = namedCodexEnvironment(process.env);
+                    const privateRoots = [dharmaHome(), resolve(environment.CODEX_HOME || resolve(homedir(), '.codex'))];
+                    if (environment.XDG_RUNTIME_DIR)
+                        privateRoots.push(environment.XDG_RUNTIME_DIR);
+                    if (environment.DBUS_SESSION_BUS_ADDRESS)
+                        privateRoots.push(environment.DBUS_SESSION_BUS_ADDRESS.slice('unix:path='.length));
+                    startupPhase = 'filesystem';
+                    const filesystem = await startupStep(() => namedCodexFilesystem({ environment, workspace: item.path, privateRoots, writeRoots }));
+                    startupPhase = 'transport';
+                    await startupStep(async () => {
+                        const expectedOwner = registration ?? pending;
+                        const ownerConfirmed = registration
+                            ? isNamedSessionReconnectReceipt(ownerReceipt, expectedOwner.bindingId, expectedOwner.identity)
+                            : isNamedSessionOwnerReceipt(ownerReceipt, expectedOwner.bindingId, expectedOwner.identity);
+                        if (!ownerConfirmed) {
+                            throw new Error('named_session_registration_invalid');
+                        }
+                        transport = await openCodexAppServerTransport({ command: filesystem.providerExecutable, cwd: item.path,
+                            environment: filesystem.environment, experimentalApi: true, toolCallTimeoutMs: 60_000,
+                            argv: [...namedCodexNodeOutputArguments(), '-c', 'allow_login_shell=false', '-c', 'default_permissions="dharma_bridge"',
+                                '-c', `permissions.dharma_bridge.filesystem=${filesystem.peer}`,
+                                '-c', 'permissions.dharma_bridge.network={enabled=false}',
+                                '-c', `permissions.dharma_work.filesystem=${filesystem.work}`,
+                                '-c', 'permissions.dharma_work.network={enabled=false}', 'app-server'] });
+                        return transport;
+                    });
+                    startupPhase = 'account';
+                    const account = await startupStep(() => transport.request('account/read', { refreshToken: false }));
+                    if (!account.account)
+                        throw new Error('named_session_provider_authentication_required');
+                    if (pending) {
+                        startupPhase = 'thread';
+                        const threadId = await startupStep(() => startNamedCodexThread(transport, item.path, name));
+                        const declaredRecoveryToolHash = inspectNamedCodexRecoveryToolDeclaration(transport, threadId);
+                        if (!declaredRecoveryToolHash)
+                            throw new Error('named_session_thread_invalid');
+                        startupPhase = 'binding';
+                        await startupStep(async () => vault.saveProviderSessionBinding({ schema: 'dharma.local-provider-session-binding/v1', ...pending.identity,
+                            bindingId: pending.bindingId, owner: 'dharma_bridge', sessionId: threadId, workspaceRoot: item.path,
+                            createdAt: new Date().toISOString(), expiresAt: new Date(Date.now() + 30 * 86400000).toISOString(),
+                            maximumProviderCostCents: pending.maximumTurnCostCents }));
+                        await startupStep(async () => vault.saveProviderSessionRecoveryDeclaration(pending.bindingId, pending.identity, declaredRecoveryToolHash));
+                        registration = pending;
+                        await startupStep(async () => saveNamedSession(dharmaHome(), registration));
+                    }
+                    return { registration: registration, filesystem, fabric, trust, policyPath, writeRoots };
                 }
-                try {
-                    const context = work ? await readCurrentRepositoryContext() : undefined;
-                    return await operation(context);
-                }
-                finally {
-                    taskState = null;
-                }
-            }),
-            retainRepositoryState: async (capture) => {
-                const current = await loadVerifiedWorkspacePolicy(policyPath, workspaceId);
-                if (current.evidence.automaticDisclosure?.mode !== 'customer_authorized_content') {
-                    return { state: 'not_authorized', acceptedLearningObservation: false };
-                }
-                if (!taskState)
-                    return { state: 'blocked', code: taskStateFailure, acceptedLearningObservation: false };
-                if (current.revision !== taskState.evidenceRevision
-                    || current.evidence.automaticDisclosure.consentReceiptId !== taskState.consentReceiptId) {
-                    throw new Error('named_session_repository_state_consent_changed');
+                catch (error) {
+                    throw namedSessionStartupPhaseError(startupPhase, error);
                 }
-                const binding = await vault.getProviderSessionBinding(registration.bindingId, registration.identity);
-                if (!binding)
-                    throw new Error('named_session_binding_unavailable');
-                const receipt = await retainNamedSessionRepositoryState({ vault, binding, capture, workId: taskState.workId,
-                    before: taskState.before, after: await taskSnapshot(), activeBundleId: taskState.bundleId, activeBundleHash: taskState.bundleHash,
-                    taskExport: { policy: current, contextBytes: await vault.getBlob(taskState.providerContext.contextContentHash),
-                        contextHash: taskState.providerContext.retainedContextHash } });
-                return { ...receipt, providerContext: taskState.providerContext,
-                    packageContent: { manifestHash: taskState.packageContent.manifestHash,
-                        catalogHash: taskState.packageContent.catalogHash, skillsHash: taskState.packageContent.skillsHash } };
-            },
-            authorizeLocalWork: async () => {
+            };
+            const { registration, filesystem, fabric, trust, policyPath, writeRoots } = childMessage
+                ? await runCodexSetupChildStartup({ vault: vault, message: childMessage, name, workspaceId,
+                    signal: controller.signal, authorize: qualifyCodexSetupChildRequest }, startProvider)
+                : await startProvider();
+            const authorizeLifetime = async () => {
                 const current = await refreshVerifiedWorkspacePolicyForTransmission(policyPath, workspaceId, fabric);
-                return writeRoots.every(root => current.tasks.writePaths.includes(`${root}/**`));
-            },
-            queueEvidence: async (capture) => {
-                const current = await loadVerifiedWorkspacePolicy(policyPath, workspaceId);
-                const binding = await vault.getProviderSessionBinding(registration.bindingId, registration.identity);
-                if (!binding)
-                    throw new Error('named_session_binding_unavailable');
-                // The existing relay rechecks current authority, disclosure limits and device binding before upload.
-                return queueNamedSessionEvidence({ vault, capture, binding, policy: current });
-            },
-            openTransport: async () => transport, channelTransport,
-            verifier: { resolvePublicKey: trust.resolvePublicKey, consume: async (id) => { if (consumed.has(id))
-                    return false; consumed.add(id); return true; } },
-            authorizeContent: createNamedPeerContentAuthorization({ scope: repositoryRoleScope(item), diagnostics: true,
-                loadCurrentPolicy: () => refreshVerifiedWorkspacePolicyForTransmission(policyPath, workspaceId, fabric),
-                loadCurrentSourceAuthorization: () => fetchRepositorySourceAuthorization(fabric, repositoryRoleScope(item)) }) })
-            .catch(error => { throw namedSessionStartupPhaseError('service', error); });
-    }
-    finally {
-        try {
-            if (transport)
-                await transport.close();
+                if (!writeRoots.every(root => current.tasks.writePaths.includes(`${root}/**`)))
+                    return false;
+                const response = await fabric.signedPost('/agent-fabric/provider-sessions', {
+                    schema: 'dharma.provider-session-registration/v1', action: 'inspect', provider: 'codex', mode: 'bridge_owned',
+                    workspaceId, endpointId: scope.endpointId, repositoryBindingId: scope.repositoryBindingId,
+                    bindingId: registration.bindingId, expectedRevision: 0, leaseSeconds: 60,
+                });
+                return isNamedSessionOwnerReceipt(response, registration.bindingId, registration.identity);
+            };
+            const refreshLifetime = () => renewNamedSessionLifetime({ vault, bindingId: registration.bindingId,
+                identity: registration.identity, trust, authorize: authorizeLifetime });
+            await refreshLifetime().catch(error => { throw namedSessionStartupPhaseError('lifetime', error); });
+            const channelTransport = { async signedPost(route, body) {
+                    await trust.refresh();
+                    const response = await fabric.signedPost(route, body);
+                    await trust.refresh();
+                    return response;
+                } };
+            // Fresh server acceptance and this live-owner claim fence peer execution;
+            // durable reservations retain cost even when delivery or execution is uncertain.
+            const consumed = new Set();
+            let taskState = null;
+            let taskStateFailure = 'source_state_unavailable';
+            const taskSnapshot = async () => {
+                const sourceAuthorization = await fetchRepositorySourceAuthorization(fabric, repositoryRoleScope(item));
+                return inventoryRepositoryPackage({ workspace: item.path, organizationId: item.organizationId,
+                    workspaceId, repositoryBindingId: item.repositoryBindingId, repositoryAgentId: item.repositoryAgentId, sourceAuthorization });
+            };
+            const readCurrentRepositoryContext = async (contentMode = 'references', referenceText) => readNamedSessionRepositoryContext({
+                installation: await verifyAgentFabricSkillInstallation({ provider: 'codex', workspace: item.path }),
+                sharedRepositoryReady: await repositorySharedReady(item), scope: repositoryRoleScope(item), workspaceRoot: item.path, contentMode, referenceText,
+                loadAuthority: async () => ({ policy: await refreshVerifiedWorkspacePolicyForTransmission(policyPath, workspaceId, fabric),
+                    source: await fetchRepositorySourceAuthorization(fabric, repositoryRoleScope(item)) })
+            });
+            return await runNamedSessionService({ home: dharmaHome(), registration, vault, signal: controller.signal,
+                localWriteRoots: writeRoots, additionalFilesystemRules: filesystem.additionalFilesystemRules,
+                readPeerRepositoryContext: question => readCurrentRepositoryContext('verified_inline', question.question),
+                observeNativeSkill: async () => {
+                    const installation = await verifyAgentFabricSkillInstallation({ provider: 'codex', workspace: item.path });
+                    const native = await observeNamedCodexSkill(transport, { workspace: item.path, installation,
+                        sharedRepositoryReady: await repositorySharedReady(item) });
+                    const current = await verifyAgentFabricSkillInstallation({ provider: 'codex', workspace: item.path });
+                    if (!current.signedLifecycleReady || current.activeBundleId !== native.bundleId
+                        || current.activeBundleHash !== native.bundleHash || current.nativeSkillPath !== installation.nativeSkillPath
+                        || !await repositorySharedReady(item))
+                        throw new Error('named_session_native_skill_unavailable');
+                    return native;
+                },
+                syncTaskExports: () => syncNamedSessionTaskExports({ vault, bindingId: registration.bindingId,
+                    identity: registration.identity,
+                    loadPolicy: () => refreshVerifiedWorkspacePolicyForTransmission(policyPath, workspaceId, fabric),
+                    send: body => fabric.signedPost('/agent-fabric/codex-task-exports', body) }),
+                withActivationBoundary: (operation, work) => withDeviceSigningControl({ config: fabric.config }, () => withWorkspaceSkillActivationLock(workspaceId, 'codex', async () => {
+                    await refreshLifetime();
+                    const skill = await verifyAgentFabricSkillInstallation({ provider: 'codex', workspace: item.path });
+                    const sharedReady = await repositorySharedReady(item);
+                    const packageContent = await readNamedSessionPackageContent(skill, sharedReady);
+                    const bundleId = packageContent.bundleId;
+                    taskState = null;
+                    taskStateFailure = 'source_state_unavailable';
+                    if (work) {
+                        const current = await loadVerifiedWorkspacePolicy(policyPath, workspaceId);
+                        if (current.evidence.automaticDisclosure?.mode === 'customer_authorized_content' && skill.activeBundleHash) {
+                            try {
+                                taskStateFailure = 'public_context_unavailable';
+                                const binding = await vault.getProviderSessionBinding(registration.bindingId, registration.identity);
+                                if (!binding)
+                                    throw new Error('named_session_binding_unavailable');
+                                const retained = await readCodexPublicContext(transport, { threadId: binding.sessionId, workspaceRoot: binding.workspaceRoot });
+                                taskStateFailure = 'runtime_version_unavailable';
+                                const version = (await execFileAsync('codex', ['--version'], { timeout: 10_000, maxBuffer: 4096,
+                                    env: providerProcessEnvironment(process.env) })).stdout.trim();
+                                if (!/^codex-cli [0-9]+\.[0-9]+\.[0-9]+(?:[-+][a-zA-Z0-9.-]+)?$/.test(version)) {
+                                    throw new Error('named_session_runtime_version_unavailable');
+                                }
+                                const contextContentHash = await vault.putBlob(Buffer.from(retained.bytes), 'named-session-public-context');
+                                if (contextContentHash !== retained.contextHash)
+                                    throw new Error('named_session_context_integrity_failed');
+                                taskStateFailure = 'source_state_unavailable';
+                                const before = await taskSnapshot();
+                                const sourceContentHash = await vault.putBlob(Buffer.from(serializeRepositoryPackageSnapshot(before)), 'named-session-source-state');
+                                await vault.putBlob(Buffer.from(JSON.stringify({ workId: work.workId, bindingId: registration.bindingId,
+                                    sourceContentHash, sourceSnapshotHash: before.manifest.snapshotHash, bundleId, bundleHash: skill.activeBundleHash,
+                                    packageContent, contextContentHash, evidenceRevision: current.revision,
+                                    consentReceiptId: current.evidence.automaticDisclosure.consentReceiptId })), 'named-session-source-boundary');
+                                taskState = { workId: work.workId, before, bundleId, bundleHash: skill.activeBundleHash, packageContent,
+                                    evidenceRevision: current.revision, consentReceiptId: current.evidence.automaticDisclosure.consentReceiptId,
+                                    providerContext: { retainedContextHash: retained.contextHash, contextContentHash,
+                                        runtimeVersion: version.slice('codex-cli '.length), requestedModel: retained.context.configuredModel,
+                                        executedModel: null, replayMode: 'task_level' } };
+                            }
+                            catch { /* Source capture failure must not replay or rewrite a coding task. */ }
+                        }
+                    }
+                    try {
+                        const context = work ? await readCurrentRepositoryContext() : undefined;
+                        return await operation(context);
+                    }
+                    finally {
+                        taskState = null;
+                    }
+                })),
+                retainRepositoryState: async (capture) => {
+                    const current = await loadVerifiedWorkspacePolicy(policyPath, workspaceId);
+                    if (current.evidence.automaticDisclosure?.mode !== 'customer_authorized_content') {
+                        return { state: 'not_authorized', acceptedLearningObservation: false };
+                    }
+                    if (!taskState)
+                        return { state: 'blocked', code: taskStateFailure, acceptedLearningObservation: false };
+                    if (current.revision !== taskState.evidenceRevision
+                        || current.evidence.automaticDisclosure.consentReceiptId !== taskState.consentReceiptId) {
+                        throw new Error('named_session_repository_state_consent_changed');
+                    }
+                    const binding = await vault.getProviderSessionBinding(registration.bindingId, registration.identity);
+                    if (!binding)
+                        throw new Error('named_session_binding_unavailable');
+                    const receipt = await retainNamedSessionRepositoryState({ vault, binding, capture, workId: taskState.workId,
+                        before: taskState.before, after: await taskSnapshot(), activeBundleId: taskState.bundleId, activeBundleHash: taskState.bundleHash,
+                        taskExport: { policy: current, contextBytes: await vault.getBlob(taskState.providerContext.contextContentHash),
+                            contextHash: taskState.providerContext.retainedContextHash } });
+                    return { ...receipt, providerContext: taskState.providerContext,
+                        packageContent: { manifestHash: taskState.packageContent.manifestHash,
+                            catalogHash: taskState.packageContent.catalogHash, skillsHash: taskState.packageContent.skillsHash } };
+                },
+                authorizeLocalWork: async () => {
+                    const current = await refreshVerifiedWorkspacePolicyForTransmission(policyPath, workspaceId, fabric);
+                    return writeRoots.every(root => current.tasks.writePaths.includes(`${root}/**`));
+                },
+                queueEvidence: async (capture) => {
+                    const current = await loadVerifiedWorkspacePolicy(policyPath, workspaceId);
+                    const binding = await vault.getProviderSessionBinding(registration.bindingId, registration.identity);
+                    if (!binding)
+                        throw new Error('named_session_binding_unavailable');
+                    // The existing relay rechecks current authority, disclosure limits and device binding before upload.
+                    return queueNamedSessionEvidence({ vault, capture, binding, policy: current });
+                },
+                openTransport: async () => transport, channelTransport,
+                verifier: { resolvePublicKey: trust.resolvePublicKey, consume: async (id) => { if (consumed.has(id))
+                        return false; consumed.add(id); return true; } },
+                authorizeContent: createNamedPeerContentAuthorization({ scope: repositoryRoleScope(item), diagnostics: true,
+                    loadCurrentPolicy: () => refreshVerifiedWorkspacePolicyForTransmission(policyPath, workspaceId, fabric),
+                    loadCurrentSourceAuthorization: () => fetchRepositorySourceAuthorization(fabric, repositoryRoleScope(item)) }) })
+                .catch(error => { throw namedSessionStartupPhaseError('service', error); });
         }
         finally {
             try {
-                await vault.close();
+                if (transport)
+                    await transport.close();
             }
             finally {
-                await releaseLock?.();
-                process.removeListener('SIGTERM', stop);
-                process.removeListener('SIGINT', stop);
-                if (childMessage)
-                    process.removeListener('disconnect', stop);
+                try {
+                    await vault.close();
+                }
+                finally {
+                    await releaseLock?.();
+                    process.removeListener('SIGTERM', stop);
+                    process.removeListener('SIGINT', stop);
+                    if (childMessage)
+                        process.removeListener('disconnect', stop);
+                }
             }
         }
     }
+    finally {
+        await releaseStartupAdmission();
+    }
 }
 async function workspaceSync(flags, positional) {
     const workspaceId = positional[0] || required(flags, 'workspace-id');
@@ -9162,6 +9271,40 @@ export async function run(argv) {
         return USAGE;
     if (flags.has('version') || command === 'version')
         return { version: VERSION };
+    if (command === 'signing-recovery') {
+        if (positional.length !== 1 || [...repeated.values()].some(values => values.length !== 1)
+            || [...flags.keys()].some(key => !['name', 'workspace-id', 'operation-id', 'apply', 'json'].includes(key))
+            || flags.has('apply') && flags.get('apply') !== true)
+            throw Error('device_signing_maintenance_options_invalid');
+        const home = dharmaHome(), name = required(flags, 'name'), workspaceId = required(flags, 'workspace-id');
+        const controller = new AbortController(), stop = () => controller.abort();
+        process.once('SIGTERM', stop);
+        process.once('SIGINT', stop);
+        const execute = (legacyBoundary) => runDeviceSigningMaintenanceController({ home, configPath: configPath(), name, workspaceId,
+            operationId: typeof flags.get('operation-id') === 'string' ? String(flags.get('operation-id')) : undefined, apply: flags.get('apply') === true,
+            readWorkspace: async () => {
+                const selected = (await registry()).find(value => value.workspaceId === workspaceId);
+                return selected && selected.repositoryBindingId && selected.repositoryRemoteHash ? { organizationId: selected.organizationId, workspaceId: selected.workspaceId,
+                    repositoryBindingId: selected.repositoryBindingId, repositoryRemoteHash: selected.repositoryRemoteHash, path: selected.path } : null;
+            }, processState: legacyBoundary ? async () => { await legacyBoundary.assertHeld(); return 'stopped'; } : () => deviceTrustMaintenanceProcessState(home, name),
+            legacyBoundary,
+            openVault: () => openBootstrapVault({ root: resolve(home, 'vault') }), signal: controller.signal, frames: process.stdin,
+            emit: value => process.stdout.write(JSON.stringify(value) + '\n') });
+        try {
+            return await (flags.get('apply') === true
+                ? withLegacySigningMaintenanceBoundary({ home, name, signal: controller.signal, assertManagedCohort: async () => {
+                        const selected = (await registry()).find(value => value.workspaceId === workspaceId);
+                        if (!selected)
+                            throw Error('device_signing_maintenance_scope_unavailable');
+                        return assertSigningMaintenanceManagedCohort(home, selected.path);
+                    } }, execute) : execute());
+        }
+        finally {
+            controller.abort();
+            process.removeListener('SIGTERM', stop);
+            process.removeListener('SIGINT', stop);
+        }
+    }
     if (command === 'demo' && ['connect', 'status', 'role', 'peers', 'ask', 'reply', 'inbox', 'ack', 'resume',
         'package', 'package-status', 'watch', 'watch-enable', 'watch-status', 'watch-disable',
         'signing-client-proof', 'signing-owner-proof', 'transport-connect']