@cotal-ai/manager 0.62.0 → 0.64.0

package/dist/manager.js

@@ -4,11 +4,11 @@ import { hostname } from "node:os";
 import { credsAuthenticator } from "@nats-io/transport-node";
 import { existsSync, lstatSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
 import { isAbsolute, join, dirname, resolve } from "node:path";
-import { CotalEndpoint, accountFromCreds, credsClaims, DEFAULT_SERVER, DEV_OWNER, MANAGER_LEASE_RENEW_MS, STANDING_RENEWABLE_TTL_SEC, assertLifecycleToken, discardLaunchArtifacts, divergentSecretStoreNotice, parseDaemonStoreAnswer, parseSecretStoreIdentity, sameSecretStoreIdentity, agentFilePath, clearSpaceHistory, dialerFor, connectorServers, spawnEnvAllow, deprovisionAgent, DeprovisionError, isConcreteChannel, deprovisionTargetPrincipal, firstFreeName, spawnNameError, idFromCreds, inspectCredHealth, credsRenewalDelayMs, composeWirePersona, loadAgentFile, listPersonaCatalog, personaCatalogDescription, personaCatalogReadable, loadCotalConfig, modelPolicyRefusal, mintCreds, mintGeneration, mintAcceptedToken, openIssuedStore, acceptedBucket, issuedBucket, mintLifecycleUid, managedRetirementOpId, mkSecretDir, newIdentity, actionContext, parsePrincipalKey, parseShareSelection, principalKey, probeConnect, provisionAgent, provisionAgentDurables, registry, resolveAuthProvider, saveAgentFile, subjectMatches, AUTH_ENDPOINT, EP_CMD_RETIRE_LIFECYCLE, controlServiceSubject, eventChannelPrincipal, resolveService, invokeCommand, } from "@cotal-ai/core";
+import { CotalEndpoint, MANAGED_HANDOFF_KIND, accountFromCreds, credsClaims, DEFAULT_SERVER, DEV_OWNER, MANAGER_LEASE_RENEW_MS, STANDING_RENEWABLE_TTL_SEC, assertLifecycleToken, discardLaunchArtifacts, divergentSecretStoreNotice, parseDaemonStoreAnswer, parseSecretStoreIdentity, sameSecretStoreIdentity, agentFilePath, clearSpaceHistory, dialerFor, connectorServers, spawnEnvAllow, deprovisionAgent, DeprovisionError, isConcreteChannel, deprovisionTargetPrincipal, firstFreeName, spawnNameError, idFromCreds, inspectCredHealth, credsRenewalDelayMs, composeWirePersona, loadAgentFile, listPersonaCatalog, personaCatalogDescription, personaCatalogReadable, loadCotalConfig, modelPolicyRefusal, mintCreds, mintGeneration, mintAcceptedToken, openIssuedStore, acceptedBucket, issuedBucket, mintLifecycleUid, managedRetirementOpId, mkSecretDir, newIdentity, actionContext, parsePrincipalKey, parseShareSelection, principalKey, probeConnect, provisionAgent, provisionAgentDurables, registry, resolveAuthProvider, saveAgentFile, subjectMatches, AUTH_ENDPOINT, EP_CMD_RETIRE_LIFECYCLE, controlServiceSubject, eventChannelPrincipal, resolveService, invokeCommand, } from "@cotal-ai/core";
 import { agentAuthState, agentCredsDir, agentLifecycleSecretFilePaths, agentSecretFilePaths, agentSecretKeyForFile, authDir, connectorInstallHint, DEFAULT_CONNECTOR, defaultAgentType, DELIVERY_CREDS_KIND, extensionConnectors, findCotalRoot, getSpaceAuth, hasUserAuthState, loadExtensionsManifest, loadManagerInstanceIdentity, loadMeshes, localTrustOfSpace, manifestExtensionNames, materializeFromManifest, materializeSecretToFile, MEMBERSHIP_RW_CREDS_KIND, mergeLaunchOptions, remintDaemonCreds, resolveOnPath, createManagerInstanceIdentity, spaceMaterialKey, SYSTEM_CREDS_FILES, userAuthStateDir, workspaceSecretStore, writeRenewalRecord } from "@cotal-ai/workspace";
 import { createRuntime, isCustodialRuntime, requireRuntimeAdopt, requireRuntimeReap, RuntimeReapUnproven, } from "./runtime/index.js";
 import { AttachEndpoint } from "./attach-endpoint.js";
-import { DELIVERY_ADMIN_BOOT_WAIT_MS, isUnansweredDeliveryAdmin, makeManagerEndpointEvictionEvidence, makeManagerEndpointEvictor, makeManagerEndpointHolderEvictor, untilDeliveryAdminAnswers } from "./endpoint-evict.js";
+import { DELIVERY_ADMIN_BOOT_WAIT_MS, isUnansweredDeliveryAdmin, makeManagerEndpointEvictionEvidence, makeManagerEndpointHolderEvictor, untilDeliveryAdminAnswers } from "./endpoint-evict.js";
 import { makeManagerHolderLivenessProbe } from "./holder-liveness.js";
 import { GateReconcileRefused, reconcileEndpointGate } from "./reconcile-gate.js";
 import { launchSpecForRun, materializePersona, launchAgentToStartOpts, parseLaunchSpec, persistLaunchSpec, readContinuityAssignment, writeContinuityAssignment } from "./launch.js";
@@ -302,6 +302,9 @@ export class Manager {
      *  a reader of that name could not tell the two apart (#382). Never pruned in-process: one string
      *  per numbered spawn. */
     issuedNumberedNames = new Set();
+    /** Lifecycle UIDs already handed to `Runtime.spawnDelegated`: a lifecycle is handed off at most
+     *  once, so a lost create acknowledgement can never become a second create. */
+    delegatedLaunched = new Set();
     /** Expiry stamps (`startedAt + MIN_LIFETIME`) for slots that freed while still young — a
      *  count-only, lazily-pruned recycle floor (P4c). Pruned + summed into the ceiling gate. */
     cooling = [];
@@ -519,6 +522,10 @@ export class Manager {
      *  daemon reloads from this manager's store AND this manager holds the per-space renewal lease.
      *  Starts false: a manager that has not proved both must not remint. */
     daemonRenewalOwner = false;
+    /** #2561: may the lease heartbeat contend at all? Set by every claim, false while the daemon names
+     *  another store or the challenge refused. Without it the heartbeat re-takes the lease the claim
+     *  just released and holds it against every manager and `doctor auth --fix` that can remint. */
+    daemonRenewalEligible = false;
     daemonRenewalLeaseTimer;
     maintenanceState = "active";
     lifecycleInFlight = 0;
@@ -861,8 +868,8 @@ export class Manager {
         // second workspace root) has a distinct id ⇒ a distinct key ⇒ it coexists; the create THROWS only
         // when the SAME instance id is already live (a same-root double-start, or a restart racing the
         // crashed predecessor's not-yet-expired key), and we REFUSE loud. A crashed holder's key auto-expires
-        // (bucket TTL). Losing the key LATER never ends this process: the renew loop puts it back or keeps
-        // retrying ({@link renewLease}).
+        // (bucket TTL). Losing the key LATER ends this process only when another process holds it; otherwise
+        // the renew loop puts it back or keeps retrying ({@link renewLease}).
         this.leaseInfo = { holder: this.ep.ref().id, instanceId: this.managerInstanceId, runtime: this.runtime.kind, root: resolve(this.workspaceRoot), pid: process.pid };
         try {
             this.leaseRevision = await this.ep.acquireManagerLease(this.leaseInfo);
@@ -1150,7 +1157,7 @@ export class Manager {
      *  CAS is how a survivor picks up a dead owner's expired lease with no operator step. Never
      *  throws; a failed heartbeat leaves ownership to the next pass rather than ending the process. */
     async keepDaemonRenewalLease() {
-        if (!this.auth)
+        if (!this.auth || !this.daemonRenewalEligible)
             return;
         try {
             const held = await this.ep.holdDaemonRenewalLease(this.managerInstanceId);
@@ -1189,11 +1196,13 @@ export class Manager {
             relation = await untilDeliveryAdminAnswers(waitMs, (requestMs) => this.daemonStoreRelation(requestMs(STORE_CHALLENGE_TIMEOUT_MS)), (reason, delayMs) => console.error(`! delivery-admin rail did not answer the store challenge (${reason}); retrying in ${delayMs / 1000}s`), (e) => e instanceof DeliveryAdminUnanswered);
         }
         catch (e) {
+            this.daemonRenewalEligible = false;
             if (this.daemonRenewalOwner)
                 await this.ep.releaseDaemonRenewalLease().catch(() => { });
             this.daemonRenewalOwner = false;
             throw e;
         }
+        this.daemonRenewalEligible = relation !== "divergent";
         if (relation === "divergent") {
             // Not our daemon's store: drop any lease we hold rather than sit on it, so the manager that
             // CAN remint is not blocked behind us.
@@ -1666,6 +1675,11 @@ export class Manager {
                     error,
                 });
         }
+        // A later manager does not resume a delegated seat, and its close runs only inside its
+        // retirement, so a cut that holds one is refused before any child stops.
+        for (const a of this.agents.values())
+            if (a.handedOff)
+                failures.push({ name: a.name, id: a.id, error: "a delegated seat is not resumed by a later manager; stop it before preserving" });
         const unverifiedStops = this.unverifiedStops.filter((stopped) => {
             try {
                 if (!stopped.authoritative && stopped.handle.status() === "exited")
@@ -1974,7 +1988,7 @@ export class Manager {
             }
         }));
         // Deprovision EVERY snapshot entry regardless of whether its stop failed (allSettled + a loud log).
-        await Promise.allSettled(managed.filter((a) => !a.suppressCleanup).map((a) => this.deprovision(a).catch((e) => console.error(`deprovision ${a.name} (${a.id}) on shutdown: ${e.message}`))));
+        await Promise.allSettled(managed.filter((a) => !a.suppressCleanup).map((a) => this.deprovision({ ...a, ...(a.handedOff ? { delegatedHandle: a.handle } : {}) }).catch((e) => console.error(`deprovision ${a.name} (${a.id}) on shutdown: ${e.message}`))));
         if (failures.length)
             throw new Error(`manager shutdown could not prove every seat exited: ${failures.join("; ")}`);
     }
@@ -2003,7 +2017,11 @@ export class Manager {
         const failures = [];
         await Promise.all(managed.map(async (a) => {
             try {
-                a.handle.stop({ graceful: false });
+                // No cut holds a delegated seat (runPreparation refuses one), so stopping it is its retirement.
+                if (a.handedOff)
+                    await this.deprovision({ ...a, delegatedHandle: a.handle });
+                else
+                    a.handle.stop({ graceful: false });
             }
             catch (e) {
                 failures.push(`${a.name}: stop failed: ${e.message}`);
@@ -2218,18 +2236,18 @@ export class Manager {
             catch { /* best effort */ }
         }
     }
-    /** Keep this instance's liveness key fresh, and NEVER end the process over it.
+    /** Keep this instance's liveness key fresh, and end the process only when another process holds it.
      *
      *  A renew that throws is a question, not a verdict: the request may have timed out with the write
      *  landed and only its acknowledgement lost, the key may have expired during a stall, or a same-id
      *  process may hold it. The verdict comes from RE-READING the key ({@link reconcileLease}), and each
-     *  answer has one response, none of which is exiting:
+     *  answer has one response:
      *  - `held`: adopt the broker's revision and carry on.
      *  - `gone`: the key expired or was released while this process was still here, so put it back. The
      *    create is atomic, so a same-id process that got there first shows up as `taken` next tick.
-     *  - `taken`: a different process holds this instance's key. Say so, once, and keep serving. The
-     *    registration takeover is what fences a superseded serve family at the broker, and which of the
-     *    two processes goes is the operator's call, not this one's.
+     *  - `taken`: a different process holds this instance's key, so it took this instance over while
+     *    this one stalled. This process is the superseded one and stops serving by exiting (SPEC 13.1).
+     *    An open mesh has no barrier that would evict its serve connection, so nothing else stops it.
      *  - `unknown`: the broker could not be asked. Keep serving and ask again next tick, for as long as it
      *    takes. A manager that cannot reach its broker gains nothing by ending itself, and the seats it
      *    holds lose everything (a pty child dies with its parent).
@@ -2296,8 +2314,12 @@ export class Manager {
                         return;
                     }
                     case "taken":
-                        this.noteLease("taken", `finds its liveness lease key held by ${verdict.by}, not by this process (renew: ${why}); serving, retrying. Two processes claim manager instance ${this.managerInstanceId}: stop one of them`);
-                        return;
+                        // No `stop()` on the way out: its deregistration deletes the instance's current
+                        // registration, which is the other process's now. That process took over on the premise
+                        // that this one was gone, so this exit leaves what a crash would, and seats a custodian or
+                        // multiplexer owns outlive it the same way.
+                        console.error(`! manager instance ${this.managerInstanceId} finds its liveness lease key held by ${verdict.by}, not by this process (renew: ${why}); that process serves this instance now, so this one stops serving and exits (space "${this.space}")`);
+                        process.exit(1);
                     case "unknown":
                         this.noteLease("unknown", `could not renew its liveness lease (${why}) or re-read it (${verdict.why}); serving, retrying until the broker answers`);
                         return;
@@ -2844,12 +2866,12 @@ export class Manager {
             // The workflow-run family (SPEC 14.3): the manager hosts the driver. Reach is the broker's
             // (`run` capability / privileged instrument rows); the serve gate is the maintenance fence.
             runStart: (ctx) => this.serveGated(ctx, () => this.runHost().start(ctx, args(ctx))),
-            runResume: (ctx) => this.serveGated(ctx, () => this.runHost().resume(args(ctx))),
+            runResume: (ctx) => this.serveGated(ctx, () => this.runHost().resume(args(ctx), ctx)),
             runAnswer: (ctx) => this.serveGated(ctx, () => {
                 const input = args(ctx);
                 if (input.amend === true)
-                    return this.runHost().amend(input, this.runAnswerer(ctx), (accepted) => this.authorizeRunAmend(ctx, accepted));
-                return this.runHost().answer(input, this.runAnswerer(ctx), (open) => this.authorizeRunAnswer(ctx, input, open));
+                    return this.runHost().amend(input, this.runAnswerer(ctx), (accepted) => this.authorizeRunAmend(ctx, accepted), ctx);
+                return this.runHost().answer(input, this.runAnswerer(ctx), (open) => this.authorizeRunAnswer(ctx, input, open), ctx);
             }),
             runStatus: (ctx) => this.serveGated(ctx, () => this.runHost().status(args(ctx))),
             runPs: (ctx) => this.serveGated(ctx, () => this.runHost().list(args(ctx))),
@@ -3021,7 +3043,13 @@ export class Manager {
         try {
             if (graceful && process.platform === "win32" && a.control)
                 controlShutdown(a.control);
-            a.handle.stop({ graceful });
+            // A delegated seat's close runs only inside its retirement, after the host revoked its grant,
+            // so stopping it starts that retirement. Every exit wait on a stop path then settles on that
+            // close; the free path's own teardown joins the same flight.
+            if (a.handedOff)
+                this.trackDeprovision({ ...a, delegatedHandle: a.handle });
+            else
+                a.handle.stop({ graceful });
         }
         catch (e) {
             console.error(`stop ${a.name} (${a.id}): ${e.message}`);
@@ -3282,6 +3310,7 @@ export class Manager {
                 lifecycleUid: material.lifecycleUid,
                 files,
                 launch: { owner: material.owner, actor: name, sentinelCredsPath: files.sentinelCreds, bearerCmd },
+                enrolled: { material, actorToken },
             };
         }
         catch (e) {
@@ -3309,6 +3338,43 @@ export class Manager {
             return { error: `agent auth preflight failed for "${name}": ${rejectionText(e)}${leftover}` };
         }
     }
+    /** This manager's registry record for its space, which pins the broker and IdP a delegated seat's
+     *  handoff carries. It must pin the exchange the host enrolls against, or the child would register
+     *  a mesh whose bearers come from somewhere else. */
+    delegatedMeshRecord() {
+        const record = loadMeshes().find((m) => m.space === this.space);
+        if (!record?.userAuth)
+            throw new Error(`a delegated seat needs this manager's user-mode registry record for space "${this.space}", and there is none`);
+        if (record.userAuth.endpoints?.url !== this.remoteAuthority?.agentBearerExchangeUrl)
+            throw new Error(`the registry record for space "${this.space}" pins a different exchange than the host's agentBearerExchangeUrl`);
+        return record;
+    }
+    /** The one handoff a delegated seat receives, built from values this manager holds: the
+     *  enrollment result, the token it generated, and its own registry record. No path crosses. */
+    composeManagedHandoff(enrolled, actorToken) {
+        const record = this.delegatedMeshRecord();
+        if (enrolled.agentBearerExchangeUrl !== record.userAuth.endpoints?.url)
+            throw new Error(`the host enrolled "${enrolled.actor}" against a different exchange than this manager's registry record pins`);
+        const { url, issuer, audience } = record.userAuth.idp;
+        return {
+            kind: MANAGED_HANDOFF_KIND,
+            space: this.space,
+            owner: enrolled.owner,
+            actor: enrolled.actor,
+            lifecycleUid: enrolled.lifecycleUid,
+            server: record.server,
+            tlsRequired: record.tlsRequired === true,
+            authProvider: record.userAuth.provider,
+            idp: { url, issuer, audience },
+            exchangeUrl: enrolled.agentBearerExchangeUrl,
+            sentinelCreds: enrolled.sentinelCreds,
+            actorToken,
+            subscribe: enrolled.subscribe,
+            allowSubscribe: enrolled.allowSubscribe,
+            allowPublish: enrolled.allowPublish,
+            ...(record.policy ? { policy: record.policy } : {}),
+        };
+    }
     /**
      * WHY A SEAT LEFT — one line, at the one place every free path passes through.
      *
@@ -3414,7 +3480,7 @@ export class Manager {
         if (this.userMode) {
             const p = parsePrincipalKey(a.id);
             if (p)
-                this.retiring.set(a.name, { opId: retireOpId(a.lifecycleUid), lifecycleUid: a.lifecycleUid, owner: p.owner, actor: p.actor, agentId: a.id, userOwner: a.userOwner, delegated: a.delegated, secretPaths: a.secretPaths, launch: { allowSubscribe: a.launch.allowSubscribe }, startedAt: Date.now() });
+                this.retiring.set(a.name, { opId: retireOpId(a.lifecycleUid), lifecycleUid: a.lifecycleUid, owner: p.owner, actor: p.actor, agentId: a.id, userOwner: a.userOwner, delegated: a.delegated, secretPaths: a.secretPaths, launch: { allowSubscribe: a.launch.allowSubscribe }, ...(a.handedOff ? { delegatedHandle: a.handle } : {}), startedAt: Date.now() });
         }
         else if (this.auth) {
             // Unit B: a STATIC lifecycle now also holds its name pending its own terminal (the F1
@@ -3431,7 +3497,7 @@ export class Manager {
         // is usually the seat ending, but a stop that could not prove the process gone leaves one the
         // terminal must still address before it frees the alias.
         if (!a.suppressCleanup && (this.maintenanceState === "active" || acceptedBeforeFence))
-            this.trackDeprovision({ ...a, runtime: a.handle?.reference });
+            this.trackDeprovision({ ...a, runtime: a.handle?.reference, ...(a.handedOff ? { delegatedHandle: a.handle } : {}) });
     }
     /** Tear down a departed agent's minted footprint (#159 B2, auth mode): its local-principal durables
      *  (`dm_local-<id>`, `dlv_local-<id>`), its read-ACL row, and its creds file — everything the spawn's
@@ -3483,6 +3549,13 @@ export class Manager {
                 target: { owner: target.owner, actor: target.actor, lifecycleUid: a.lifecycleUid },
                 opId: retireOpId(a.lifecycleUid),
             });
+            // A delegated seat's fenced close runs only now, after the grant is revoked so its child can
+            // obtain no fresh bearer, and before the barrier, which must never run ahead of a create that
+            // could still land. A close that cannot prove that yet throws here and keeps the alias held.
+            if (a.delegatedHandle) {
+                a.delegatedHandle.stop({ graceful: true });
+                await this.awaitHandleExit(a.delegatedHandle);
+            }
             await this.requestRetirement(a);
             return;
         }
@@ -4648,6 +4721,28 @@ export class Manager {
             if (this.userMode)
                 return { ok: false, error: "supervise is a restart policy this host cannot enforce: a user-mode seat has no static slot to keep the incarnation owned across a process death" };
         }
+        // A delegated seat starts outside this host from values alone, so a choice only this host can
+        // honour is refused here, before enrollment, and named rather than dropped.
+        if (this.runtime.spawnDelegated) {
+            const delegatedBy = `runtime "${this.runtime.kind}" starts seats outside this host`;
+            if (!this.remoteAuthority?.enrollManagedAgent)
+                return { ok: false, error: `${delegatedBy}, which needs a host that enrolls managed agents (remoteAuthority.enrollManagedAgent); a delegated seat has no local grant path` };
+            try {
+                this.delegatedMeshRecord();
+            }
+            catch (e) {
+                return { ok: false, error: e.message };
+            }
+            if (opts.resume)
+                return { ok: false, error: `${delegatedBy}, so it cannot resume a session held on this host (resume)` };
+            if (opts.resolved?.continuity === "exact")
+                return { ok: false, error: `${delegatedBy}, so it cannot reopen a session held on this host (continuity: exact)` };
+            if (typeof opts.cwd === "string" && opts.cwd !== "")
+                return { ok: false, error: `${delegatedBy}, so it cannot run in a directory on this host's filesystem (cwd); the seat runs in its runtime resource's own directory` };
+            const shared = Object.keys(connectorServers(loadCotalConfig(this.workspaceRoot), agent, parseShareSelection(opts.shareTools)));
+            if (shared.length)
+                return { ok: false, error: `${delegatedBy}, so it cannot share MCP servers that run on this host (${shared.join(", ")}); pass --share-tools none` };
+        }
         // A placed spawn's cwd is checked on this host BEFORE anything is minted or reserved: an absolute
         // path this manager cannot realpath, or one that is not a directory, is refused here with the
         // asked path, the reason and this host, so a misplaced spawn in a multi-manager space is
@@ -4784,7 +4879,7 @@ export class Manager {
             return { ok: false, error: `the name "${identityName}" is still reconciling at manager startup; its prior lifecycle terminal owns this alias until it completes. Retry shortly.` };
         const held = this.retiring.get(identityName);
         if (held !== undefined) {
-            void this.deprovision({ id: held.agentId, name: identityName, lifecycleUid: held.lifecycleUid, userOwner: held.userOwner, delegated: held.delegated, secretPaths: held.secretPaths, launch: held.launch }).catch(() => { });
+            void this.deprovision({ id: held.agentId, name: identityName, lifecycleUid: held.lifecycleUid, userOwner: held.userOwner, delegated: held.delegated, secretPaths: held.secretPaths, delegatedHandle: held.delegatedHandle, launch: held.launch }).catch(() => { });
             const err = lifecycleBlocked("failed-precondition", `the name "${identityName}" is reserved pending retirement: its previous agent's despawn started that lifecycle's teardown (footprint + standing-authority revoke + auth-side retirement), and the name frees only when all of it completes${held.lastError !== undefined ? ` (last attempt: ${held.lastError})` : ""}. NEXT: wait a moment and retry this spawn (retrying re-drives the whole teardown), or pick another name.`, { blockedOp: "retirement", headState: "retiring", opId: held.opId, remedy: "retry" });
             return { ok: false, error: renderLifecycleBlocked(err.message, err), details: err.details };
         }
@@ -4807,6 +4902,10 @@ export class Manager {
                 return { ok: false, error: e.message };
             }
         }
+        // The child takes launch options as `--opt k=v`, so only string values can cross to it.
+        const unportable = this.runtime.spawnDelegated ? Object.keys(launchOptions ?? {}).filter((k) => typeof launchOptions[k] !== "string") : [];
+        if (unportable.length)
+            return { ok: false, error: `runtime "${this.runtime.kind}" starts seats outside this host, so it cannot pass non-string launch options (${unportable.join(", ")})` };
         // #4 A4 (panel): the roster the allocation consults must reflect the initial presence snapshot,
         // or a spawn immediately after manager boot races an already-live unmanaged peer and re-opens the
         // very collision black-hole this closes. Await the snapshot (bounded internally, fail-safe on an
@@ -4965,6 +5064,7 @@ export class Manager {
             let issued;
             let userLaunch;
             let userOwner;
+            let enrolled;
             if (this.userMode) {
                 const prep = await this.provisionUserAgent(name, {
                     spawner,
@@ -4998,6 +5098,7 @@ export class Manager {
                 lifecycleUid = prep.lifecycleUid;
                 userLaunch = prep.launch;
                 userOwner = prep.owner;
+                enrolled = prep.enrolled;
                 provisioned = { id: principalKey(prep.owner, name).key, name, lifecycleUid, userOwner: prep.owner, ...(opts.delegatedIntent ? { delegated: true } : {}), secretPaths: prep.files, ...(custody ? { runtime: custody } : {}) };
             }
             else if (this.auth) {
@@ -5110,9 +5211,22 @@ export class Manager {
                 // (possibly per-agent) launch cwd below. The cwd itself rides runtime.spawn, not the launch.
                 workspaceRoot: this.workspaceRoot,
             };
-            const spec = connector.buildLaunch(launchOpts);
-            spec.env = { ...spec.env, COTAL_MANAGER_INSTANCE: this.managerInstanceId };
-            const handle = await this.spawnCustodied(name, spec, cwd, custody);
+            // A delegated seat gets no local launch at all: no launch-material file, control token or
+            // manager path is produced for it, only the handoff its runtime writes into the child.
+            let spec;
+            let handle;
+            if (this.runtime.spawnDelegated) {
+                const handoff = this.composeManagedHandoff(enrolled.material, enrolled.actorToken);
+                if (this.delegatedLaunched.has(lifecycleUid))
+                    throw new Error(`lifecycle ${lifecycleUid} was already handed to runtime "${this.runtime.kind}"; a lifecycle is handed off at most once`);
+                this.delegatedLaunched.add(lifecycleUid);
+                handle = this.runtime.spawnDelegated({ agent, persona: readFileSync(configPath, "utf8"), role, model, variant, prompt, launchOptions: launchOptions, events }, handoff);
+            }
+            else {
+                spec = connector.buildLaunch(launchOpts);
+                spec.env = { ...spec.env, COTAL_MANAGER_INSTANCE: this.managerInstanceId };
+                handle = await this.spawnCustodied(name, spec, cwd, custody);
+            }
             hooks?.onLaunched?.(); // P2 item 2: the "launched" progress edge (process spawned, pre-presence)
             const managed = {
                 name,
@@ -5130,7 +5244,8 @@ export class Manager {
                 authorityParent: userLaunch && spawner && parsePrincipalKey(spawner) ? spawner : undefined,
                 startedAt: Date.now(),
                 handle,
-                control: spec.control,
+                control: spec?.control,
+                ...(spec ? {} : { handedOff: true }),
                 launch: {
                     source: opts.resolved
                         ? {
@@ -5156,7 +5271,7 @@ export class Manager {
                     events,
                     shareTools: opts.shareTools,
                     forkSource: opts.resume,
-                    ...(opts.resume !== undefined && spec.resumeRecordPath ? { resumeRecordPath: spec.resumeRecordPath } : {}),
+                    ...(opts.resume !== undefined && spec?.resumeRecordPath ? { resumeRecordPath: spec.resumeRecordPath } : {}),
                     // Opaque values may contain secrets. Preserve only their keys and require the referenced
                     // persona/manifest to resolve the values again; imperative overrides have no safe payload.
                     unresolvedLaunchOptionKeys: opts.launchOptions && Object.keys(opts.launchOptions).length
@@ -5164,7 +5279,7 @@ export class Manager {
                         : undefined,
                 },
                 // A delegated agent is never restarted (SPEC 13.16), so its slot arms no recovery.
-                ...((connector.supportsSessionContinuation || opts.supervise !== undefined) && !opts.delegatedIntent
+                ...(spec && (connector.supportsSessionContinuation || opts.supervise !== undefined) && !opts.delegatedIntent
                     ? {
                         restart: {
                             opts: launchOpts,
@@ -5331,6 +5446,7 @@ export class Manager {
                         userOwner: held.userOwner,
                         delegated: held.delegated,
                         secretPaths: held.secretPaths,
+                        delegatedHandle: held.delegatedHandle,
                     }).catch(() => { });
                     return {
                         ok: false,
@@ -6690,7 +6806,7 @@ export class Manager {
             // error text — a crash-restart never silently skips eviction (no-fallbacks).
             const barrier = endpointRegistrationBarrier(authKv, this.space, {
                 endpoint: MANAGER_ENDPOINT, instanceId: iid, opId: registrationOpId,
-                ...(auth ? { evict: makeManagerEndpointEvictor({ space: this.space, servers: this.servers ?? DEFAULT_SERVER, auth, log: (line) => console.error(line), unreachableWaitMs: DELIVERY_ADMIN_BOOT_WAIT_MS }) } : {}),
+                ...(auth ? { evict: makeManagerEndpointHolderEvictor({ space: this.space, servers: this.servers ?? DEFAULT_SERVER, auth, log: (line) => console.error(line), unreachableWaitMs: DELIVERY_ADMIN_BOOT_WAIT_MS }) } : {}),
             });
             const spec = { endpoint: MANAGER_ENDPOINT, owner: DEV_OWNER, clusterDigests: [artifacts.closureDigest], protocol: { v: 1 } };
             const { registrationRevision } = await registerServiceInstance(recordsKv, {