@cotal-ai/manager 0.53.0 → 0.55.0

package/dist/manager.js

@@ -4,7 +4,7 @@ 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, DEFAULT_SERVER, DEV_OWNER, MANAGER_LEASE_RENEW_MS, STANDING_RENEWABLE_TTL_SEC, divergentSecretStoreNotice, parseSecretStoreIdentity, sameSecretStoreIdentity, agentFilePath, clearSpaceHistory, dialerFor, connectorServers, spawnEnvAllow, deprovisionAgent, firstFreeName, spawnNameError, idFromCreds, inspectCredHealth, composeWirePersona, loadAgentFile, listPersonaCatalog, personaCatalogDescription, personaCatalogReadable, loadCotalConfig, 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, epRequestSubject, epCallerReplyFilter, parseEpSubject, controlServiceSubject, eventChannelPrincipal, } from "@cotal-ai/core";
+import { CotalEndpoint, DEFAULT_SERVER, DEV_OWNER, MANAGER_LEASE_RENEW_MS, STANDING_RENEWABLE_TTL_SEC, assertLifecycleToken, divergentSecretStoreNotice, parseDaemonStoreAnswer, parseSecretStoreIdentity, sameSecretStoreIdentity, agentFilePath, clearSpaceHistory, dialerFor, connectorServers, spawnEnvAllow, deprovisionAgent, firstFreeName, spawnNameError, idFromCreds, inspectCredHealth, composeWirePersona, loadAgentFile, listPersonaCatalog, personaCatalogDescription, personaCatalogReadable, loadCotalConfig, 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, epRequestSubject, epCallerReplyFilter, parseEpSubject, controlServiceSubject, eventChannelPrincipal, } 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";
@@ -505,6 +505,13 @@ export class Manager {
     /** A renew is in flight. The tick must not start a second one: both would read the same cached
      *  revision, so whichever lands second CASes against a sequence the first already moved. */
     leaseRenewInFlight = false;
+    /** The promise a currently in-flight `renewLease()` is running, so `stop()` can await it before
+     *  releasing the key instead of racing it: a renew that lands after the cached revision was read
+     *  for release would otherwise move the row out from under a same-cached-revision CAS delete. */
+    leaseRenewTask;
+    /** Set at the top of `stop()`. `renewLease` returns at once once this is set, and its `gone` arm
+     *  does not re-acquire: a manager that is stopping never puts its own key back. */
+    leaseStopping = false;
     /** The class-2 renewal owner's half-TTL schedule (D5 slice 5); armed only on auth meshes. */
     credRenewTimer;
     /** #1634: does THIS manager own the delivery daemon's credential renewal? True only while the
@@ -890,13 +897,27 @@ export class Manager {
         // manager records each agent's read ACL at spawn (`commitAcl`, in provisionAgent) so the daemon can
         // re-authorize it; that is the only Plane-3 state the manager touches, and it rides minting.
     }
+    /** The delivery shard whose lease names the process that reloads the standing credentials.
+     *  Delivery is single-shard today and the endpoint's own responder reads row 0; naming it here
+     *  keeps the manager's binding check and that reply arguing about the same row. */
+    static DELIVERY_SHARD = 0;
     /** Proof that this manager remints into the store the delivery daemon reloads from.
      *  Fingerprint-only `reloadCreds` is safe only after this. Two named, different stores
      *  refuse the pass. A daemon that is not bound yet is not a named store: start and
      *  remint still proceed (tests, delayed delivery), writing this manager's store. The
      *  challenge runs again before every remint, so a later daemon on a foreign store is
      *  refused then rather than certified by an earlier absence. A request timeout is not
-     *  absence: a hung rail would skip the proof, so it fails closed. */
+     *  absence: a hung rail would skip the proof, so it fails closed.
+     *
+     *  ABSENCE IS READ OFF THE LEASE ROW, never off the rail's no-responder shape alone (#1694).
+     *  The rail is queue-grouped, so "no responder answered" is itself something the rail reports,
+     *  and a responder that answers in a shape the client turns into that error makes the pass read
+     *  "absent" while a holder is live on the row — certifying every later remint with no proof at
+     *  all. So a no-responder outcome is decided by the row: a row that names a holder makes the
+     *  pass refuse (undetermined — a live daemon went unanswered, which must not read as "no
+     *  daemon"), and only a row that is absent or holderless settles "absent", the state start()
+     *  treats as not-yet-bound. An unreadable row (a failed read, or a key that exists but does not
+     *  parse) is a genuine unknown and refuses fail-closed, like a hung rail. */
     async daemonStoreRelation() {
         let reply;
         try {
@@ -905,24 +926,77 @@ export class Manager {
         catch (e) {
             const msg = e.message;
             if (isAbsentDeliveryAdmin(msg))
-                return "absent";
+                return this.absentByLeaseRow();
             throw new Error(`could not challenge the delivery daemon's SecretStore: ${msg}`);
         }
         if (!reply.ok)
             throw new Error(reply.error ?? "delivery daemon refused to name the SecretStore it reloads from");
-        let daemon;
+        let answer;
         try {
-            daemon = parseSecretStoreIdentity(reply.data);
+            answer = parseDaemonStoreAnswer(reply.data);
         }
         catch (e) {
-            throw new Error(`delivery daemon named an unreadable SecretStore: ${e.message}`);
-        }
+            throw new Error(`delivery daemon named an unreadable SecretStore: ${e.message}. A daemon older ` +
+                `than #1694 replies with a bare store identity and no answerer binding; this manager ` +
+                `cannot establish which process answered, so nothing reminted - upgrade the delivery daemon`);
+        }
+        // The answerer's own claim first, so an honest non-holder is refused by its own admission and
+        // the operator-facing reason names that. This is the CHEAP half of the test and NOT the binding
+        // one: a responder that does not hold the lease can assert `true` here just as easily.
+        if (!answer.holdsDeliveryLease)
+            throw new Error("the delivery-admin rail was answered by a responder that does not hold this space's " +
+                "delivery lease, so its SecretStore is not the store the daemon reloads from - nothing reminted");
+        // THE BINDING TEST, measured by this manager rather than asserted by the answerer. The lease
+        // row's holder is read here under this manager's own credential; the answerer must BE that
+        // principal. A reply asserting the claim while some other process holds the shard fails here,
+        // which is the case a bare store identity could not see. An unreadable row is an unknown and
+        // refuses too: this test may never be satisfied by failing to run.
+        const holder = await this.ep.deliveryLeaseHolder(Manager.DELIVERY_SHARD);
+        if (holder === undefined)
+            throw new Error("this manager could not read the delivery lease row, so it cannot verify that the answering " +
+                "responder is the process that reloads the standing credentials - nothing reminted");
+        if (holder !== answer.responder)
+            throw new Error(`the delivery-admin rail was answered by ${answer.responder}, which is not the holder of ` +
+                `this space's delivery lease (${holder}), so its SecretStore is not the store the daemon ` +
+                `reloads from - nothing reminted`);
+        const daemon = answer.identity;
         if (!sameSecretStoreIdentity(this.secretStoreIdentity, daemon)) {
             console.error(`! ${divergentSecretStoreNotice(this.secretStoreIdentity, daemon)}`);
             return "divergent";
         }
         return "shared";
     }
+    /** Settle a no-responder challenge outcome from the lease row, never from the rail's own
+     *  reporting shape (#1694). The three cases:
+     *
+     *  1. The row READS but names a holder: a live daemon holds the shard and the rail went
+     *     unanswered. That is undetermined, not "no daemon" — treating it as absent would let this
+     *     manager remint with no proof while a reloading daemon runs, which is exactly what the
+     *     challenge exists to prevent. Refuse.
+     *  2. The row is unreadable — a read that fails (a denied or erroring bucket) OR a key that
+     *     exists but does not parse as a lease record (`readDeliveryLeaseEntry` throws for both):
+     *     undetermined, and it refuses the same fail-closed way a hung rail does. Never a silent
+     *     "absent" over a row the manager could not read.
+     *  3. The row is absent or holderless (no key, a DEL/PURGE tombstone, or a row that names no
+     *     holder): today's "absent", the state start() treats as a daemon that is not bound yet.
+     *
+     *  `deliveryLeaseHolder` swallows its read failures into `undefined`, which would fold case 2
+     *  into case 3 — so this reads the entry directly and lets the read's own failure refuse. */
+    async absentByLeaseRow() {
+        let entry;
+        try {
+            entry = await this.ep.readDeliveryLeaseEntry(Manager.DELIVERY_SHARD);
+        }
+        catch (e) {
+            throw new Error(`could not read the delivery lease row to settle whether the delivery daemon is absent ` +
+                `(${e.message}) - absence is undetermined, nothing reminted`);
+        }
+        const holder = entry?.info.holder;
+        if (holder !== undefined && holder !== "")
+            throw new Error(`the delivery-admin rail reported no responder while the delivery lease names a holder ` +
+                `(${holder}) - absence cannot be read off the rail alone, and nothing reminted`);
+        return "absent";
+    }
     /** Keep this manager's renewal lease alive between credential passes (#1634). The manager bucket
      *  expires keys at MANAGER_LEASE_TTL_MS, far below the credential pass's cadence, so the lease
      *  needs its own heartbeat like the per-instance liveness lease. A non-owner calls this too: the
@@ -955,7 +1029,23 @@ export class Manager {
      *
      *  A manager failing either test serves the space normally and skips only the daemon remint. */
     async claimDaemonRenewalOwnership() {
-        if ((await this.daemonStoreRelation()) === "divergent") {
+        // EVERY refusal outcome drops a held lease, not only "divergent". The refusal paths THROW
+        // (#1694: a non-holder answer, an unbindable answerer, an unreadable or holder-naming row on a
+        // no-responder rail), and a thrown refusal caught by renewDaemonCreds would otherwise leave a
+        // manager that once owned the renewal still holding the lease behind its own heartbeat — the
+        // pass refuses, the log says so, and the space keeps a renewal owner that must not remint.
+        // Deciding here, inside the claim, is what keeps the release on the refusal path itself.
+        let relation;
+        try {
+            relation = await this.daemonStoreRelation();
+        }
+        catch (e) {
+            if (this.daemonRenewalOwner)
+                await this.ep.releaseDaemonRenewalLease().catch(() => { });
+            this.daemonRenewalOwner = false;
+            throw e;
+        }
+        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.
             if (this.daemonRenewalOwner)
@@ -1634,6 +1724,7 @@ export class Manager {
             throw new Error(`manager preservation shutdown incomplete: ${failures.join("; ")}`);
     }
     async stop(options = {}) {
+        this.leaseStopping = true;
         this.staticReconcileStopping = true;
         const starting = this.startTask;
         for (const item of this.staticReconcileItems.values()) {
@@ -1652,6 +1743,10 @@ export class Manager {
             clearInterval(this.daemonRenewalLeaseTimer);
         if (this.sessionKeyRenewTimer)
             clearInterval(this.sessionKeyRenewTimer);
+        // A renew already in flight when the timer was cleared above must be awaited, not raced: it can
+        // still move the key's revision after we clear the timer, and releasing against a cached
+        // revision it has since moved is a CAS the broker correctly refuses, silently, forever.
+        await this.leaseRenewTask?.catch(() => { });
         let releaseFailures = [];
         if (this.maintenanceState === "active" && !this.resumeRequired) {
             if (options.withAgents)
@@ -1663,7 +1758,7 @@ export class Manager {
             // A signal after a partial preservation must never fall back into destructive teardown.
             await this.stopRetainedAgentsOnExit();
         }
-        await this.ep.releaseManagerLease(this.managerInstanceId, this.leaseRevision);
+        await this.releaseOwnManagerLease();
         // #1634: hand the renewal lease back on a clean stop so a sibling picks it up on its next pass
         // rather than waiting out the bucket TTL. A non-owner holds no revision and this is a no-op.
         await this.ep.releaseDaemonRenewalLease();
@@ -1686,6 +1781,30 @@ export class Manager {
         if (releaseFailures.length)
             throw new Error(`manager shutdown could not release every detachable seat: ${releaseFailures.join("; ")}`);
     }
+    /** Release this instance's liveness lease key on a clean stop, at the broker's own revision
+     *  rather than a cached one that a renew still in flight moments ago may have already moved past.
+     *  Re-reads the row and releases only what is PROVABLY this process's (absent, or another pid's,
+     *  is left alone — the same test {@link reconcileLease} uses). Nothing here throws: a stop must
+     *  complete either way, and a row that could not be released is left for the bucket TTL, with one
+     *  line of warning so the cost (a same-root restart waiting out the TTL) is not silent. */
+    async releaseOwnManagerLease() {
+        try {
+            const own = await this.ep.readOwnManagerLease(this.managerInstanceId);
+            if (own !== undefined && own.info.pid === process.pid)
+                await this.ep.releaseManagerLease(this.managerInstanceId, own.revision);
+        }
+        catch {
+            // Best-effort, like the release it wraps: a broker failure here is recovered by the bucket TTL.
+        }
+        try {
+            const stillOurs = await this.ep.readOwnManagerLease(this.managerInstanceId);
+            if (stillOurs !== undefined && stillOurs.info.pid === process.pid)
+                console.error(`! manager instance ${this.managerInstanceId} could not release its liveness lease (space "${this.space}"); a same-root restart inside the bucket TTL will be refused`);
+        }
+        catch {
+            // Could not confirm either way; the warning is best-effort, not a verdict.
+        }
+    }
     /**
      * REMOVE THIS INSTANCE'S SERVICE REGISTRATION on a clean stop (§13.5 deregistration).
      *
@@ -1777,12 +1896,25 @@ export class Manager {
      *  on a live mesh turned a ten-second broker or KV outage into a manager outage that lasted until an
      *  operator noticed. */
     async renewLease() {
+        // A manager that is stopping never puts its own key back: a stop already fenced this loop, and
+        // any tick or explicit call landing after that must be a no-op, not a fresh acquire attempt.
+        if (this.leaseStopping)
+            return;
         // A renew that runs long must not be overlapped by the next tick: both would CAS against the same
         // cached revision, so whichever lands second is refused over a sequence the first legitimately
         // moved, a conflict this instance manufactured itself.
         if (this.leaseRenewInFlight)
             return;
         this.leaseRenewInFlight = true;
+        const task = this.renewLeaseAttempt();
+        this.leaseRenewTask = task;
+        return task;
+    }
+    /** The renew attempt itself, split out from {@link renewLease} only so `stop()` can hold the
+     *  promise a renew already in flight is running ({@link leaseRenewTask}) and await it before
+     *  releasing the key: releasing against a cached revision a live renew has since moved is a CAS
+     *  the broker correctly refuses, silently, forever. */
+    async renewLeaseAttempt() {
         try {
             if (!this.leaseInfo || this.leaseRevision === undefined)
                 return;
@@ -1802,6 +1934,11 @@ export class Manager {
                         this.noteLease("held-unrenewed", `could not renew its liveness lease (${why}) but the key is still its own at revision ${verdict.revision}; serving, retrying`);
                         return;
                     case "gone": {
+                        // A stop that began while this renew was already in flight fences it here too: the
+                        // await above can cross the point where `stop()` set the flag, and a re-acquire past
+                        // that point would put a stopping process's key straight back.
+                        if (this.leaseStopping)
+                            return;
                         // The key being gone is a fact before the re-acquire is attempted, so a successful
                         // re-acquire is a change of state (gone to held) and prints, every time it happens.
                         const before = this.leaseState;
@@ -2232,10 +2369,25 @@ export class Manager {
                 const data = unwrap(await this.opModels(args(ctx)));
                 return { catalogs: Array.isArray(data) ? data : [data] };
             }),
+            goalResult: (ctx) => this.serveGated(ctx, async () => {
+                const gw = this.goalWriter;
+                if (!gw || gw.nc.isClosed())
+                    throw new EpEnvelopeError("unavailable", "the manager goal-reader connection is not standing; the accepted goal is unaffected");
+                const goalId = args(ctx).goalId;
+                // Only the broker-authenticated caller's full incarnation can name this read. The
+                // trusted goal-writer keeps the raw EPF authority; serveEndpoint derives the reply rail.
+                const result = await readGoalResult(gw.ctx, goalRefOf(ctx.subject, goalId));
+                return { goalId, ...(result === undefined ? {} : { result }) };
+            }),
             resolveCwd: (ctx) => this.serveGated(ctx, () => this.resolveSpawnCwd(args(ctx).cwd)),
             // P2 item 2: `spawn` is an ACTION - accept a goal + reply the acceptance floor payload, drive
             // progress + terminal off-handler (no ~30s block). The blocking reply path is gone (pin 8).
-            spawn: (ctx) => this.serveGated(ctx, () => this.serveSpawnGoal(ctx, (h) => this.opStart(args(ctx), callerOf(ctx), h, ctx.subject.route))),
+            // #373: arming the event plane (events: true, or the omission that arms it by default)
+            // is operator reach on a user mesh — the spawn handler resolves the caller's admin tier
+            // ONCE here (opLaunch takes the same signal as a parameter) and opStart's admission gate
+            // decides on it BEFORE connector resolution or any grant mutation. Static meshes resolve
+            // true and nothing changes.
+            spawn: (ctx) => this.serveGated(ctx, async () => this.serveSpawnGoal(ctx, async (h) => this.opStart(args(ctx), callerOf(ctx), await this.epAdminReach(ctx.subject.caller), h, ctx.subject.route))),
             despawn: (ctx) => this.serveGated(ctx, async () => {
                 const a = targetAgent(ctx);
                 const denied = await this.authorizeNamed(a, callerOf(ctx), await this.epAnyModeAdmin(ctx), ctx.subject.caller);
@@ -2542,6 +2694,8 @@ export class Manager {
      *  dead auth plane. Every failure is returned as the refusal sentence, with the grant + files
      *  rolled back. */
     async provisionUserAgent(name, opts) {
+        if (this.remoteAuthority?.enrollManagedAgent)
+            return this.enrollUserAgent(name, opts, this.remoteAuthority.enrollManagedAgent);
         const spawnerPr = opts.spawner ? parsePrincipalKey(opts.spawner) : null;
         const owner = opts.specOwner ?? (spawnerPr && spawnerPr.owner.startsWith("u_") ? spawnerPr.owner : undefined);
         if (!owner)
@@ -2620,7 +2774,7 @@ export class Manager {
                 "--health-file", healthPath,
             ];
             await execBearerPreflight(bearerCmd);
-            return { owner, files, launch: { owner, actor: name, sentinelCredsPath: sentinelPath, bearerCmd } };
+            return { owner, lifecycleUid: opts.lifecycleUid, files, launch: { owner, actor: name, sentinelCredsPath: sentinelPath, bearerCmd } };
         }
         catch (e) {
             // Roll back everything this attempt materialized — a refused spawn must leave no standing
@@ -2637,6 +2791,111 @@ export class Manager {
             return { error: `agent auth preflight failed for "${name}": ${e.message}` };
         }
     }
+    /**
+     * HOSTED user-mode spawn provisioning (#1972): the participant arm of host-owned enrollment.
+     *
+     * A registered participant holds no ledger writer, no JetStream provisioner, and no signing seed,
+     * so every step the local arm above performs itself is the HOST's here. What stays local is the
+     * one thing that must: the standing `actorToken`. This method generates it, writes it at 0600
+     * BEFORE the request, and sends only its SHA-256 digest — so the plaintext never crosses the
+     * network and a host compromise cannot replay an agent's exchange secret.
+     *
+     * The HOST picks the lifecycle UID. It alone can see the retirement tombstones that make a UID
+     * permanently unusable (a retired uid is refused forever by the retirement frontier), so a
+     * participant-chosen uid could aim a fresh grant at a dead incarnation. The uid the host returns
+     * is the one the spawn records and the one the child's durables are keyed by.
+     *
+     * The bearer argv selects `--exchange-url`: the local `--dir` arm reads a state directory this
+     * machine does not have, and a signerless participant must never appear to hold one.
+     */
+    async enrollUserAgent(name, opts, enroll) {
+        let provider;
+        try {
+            provider = resolveAuthProvider();
+        }
+        catch (e) {
+            return { error: e.message };
+        }
+        const secrets = this.secrets;
+        // The token the agent will present to `POST /exchange` for the rest of its life. Generated
+        // here, hashed here, and never sent: the request carries `tokenHash` alone.
+        const actorToken = randomBytes(32).toString("base64url");
+        const tokenHash = createHash("sha256").update(actorToken, "utf8").digest("hex");
+        // Provisional paths under the participant's OWN uid: the token has to be on disk before the
+        // request (a host that granted against a digest whose plaintext was lost would leave an agent
+        // that can never exchange), and the host's uid is not known until the request answers. The
+        // family is re-keyed to the host's uid below.
+        const staged = agentLifecycleSecretFilePaths(this.workspaceRoot, this.space, name, opts.lifecycleUid);
+        let files = staged;
+        let material;
+        try {
+            await secrets.put(agentSecretKeyForFile(staged.actorToken, this.space), actorToken);
+            await materializeSecretToFile(secrets, agentSecretKeyForFile(staged.actorToken, this.space), staged.actorToken);
+            material = await enroll({
+                target: {
+                    actor: name,
+                    tokenHash,
+                    ...(opts.role !== undefined ? { role: opts.role } : {}),
+                    label: opts.label,
+                    ...(opts.capabilities !== undefined ? { capabilities: opts.capabilities } : {}),
+                    ...(opts.subscribe !== undefined ? { subscribe: opts.subscribe } : {}),
+                    allowSubscribe: opts.allowSubscribe,
+                    ...(opts.allowPublish !== undefined ? { allowPublish: opts.allowPublish } : {}),
+                },
+            });
+            if (material.actor !== name)
+                throw new Error(`the host enrolled actor "${material.actor}", not the requested "${name}"`);
+            const specOwner = opts.specOwner ?? (opts.spawner ? parsePrincipalKey(opts.spawner)?.owner : undefined);
+            if (specOwner !== undefined && specOwner.startsWith("u_") && material.owner !== specOwner)
+                throw new Error(`the host enrolled the agent under owner ${material.owner}, not the spawning owner ${specOwner}`);
+            assertLifecycleToken(material.lifecycleUid, "host-enrolled managed agent lifecycleUid");
+            // Re-key the family onto the HOST's uid (SPEC 13.1 name-disjointness on the FS): the child's
+            // credential paths must embed the uid its broker footprint carries, never the provisional one.
+            files = agentLifecycleSecretFilePaths(this.workspaceRoot, this.space, name, material.lifecycleUid);
+            if (files.actorToken !== staged.actorToken) {
+                await secrets.put(agentSecretKeyForFile(files.actorToken, this.space), actorToken);
+                await materializeSecretToFile(secrets, agentSecretKeyForFile(files.actorToken, this.space), files.actorToken);
+                await secrets.delete(agentSecretKeyForFile(staged.actorToken, this.space)).catch(() => { });
+                rmSync(staged.actorToken, { force: true });
+            }
+            await secrets.put(agentSecretKeyForFile(files.sentinelCreds, this.space), material.sentinelCreds);
+            await materializeSecretToFile(secrets, agentSecretKeyForFile(files.sentinelCreds, this.space), files.sentinelCreds);
+            rmSync(files.health, { force: true }); // a fresh start opens a fresh health window
+            const bearerCmd = [
+                process.execPath,
+                ...process.execArgv,
+                process.argv[1],
+                provider.agentBearerCommand,
+                // The signerless arm: the pinned public exchange, never a local state dir.
+                "--exchange-url", material.agentBearerExchangeUrl,
+                "--space", this.space,
+                "--owner", material.owner,
+                "--actor", name,
+                "--token-file", files.actorToken,
+                "--health-file", files.health,
+            ];
+            await execBearerPreflight(bearerCmd);
+            return {
+                owner: material.owner,
+                lifecycleUid: material.lifecycleUid,
+                files,
+                launch: { owner: material.owner, actor: name, sentinelCredsPath: files.sentinelCreds, bearerCmd },
+            };
+        }
+        catch (e) {
+            // Shred every local secret this attempt materialized. The HOST's rows are the host's to
+            // reconcile: a participant holds no writer, so it must not pretend to roll back a grant or a
+            // durable it never authored. A retry with the same requestId re-enters the same enrollment.
+            for (const family of files.actorToken === staged.actorToken ? [staged] : [staged, files]) {
+                await secrets.delete(agentSecretKeyForFile(family.actorToken, this.space)).catch(() => { });
+                await secrets.delete(agentSecretKeyForFile(family.sentinelCreds, this.space)).catch(() => { });
+                rmSync(family.actorToken, { force: true });
+                rmSync(family.sentinelCreds, { force: true });
+                rmSync(family.health, { force: true });
+            }
+            return { error: `agent auth preflight failed for "${name}": ${e.message}` };
+        }
+    }
     /** Drop a live agent's slot. When `floor` is set and the agent died young (lived less than
      *  MIN_LIFETIME), push a cooling stamp so the freed slot still counts toward the ceiling until it
      *  expires — flooring the RECYCLE, not the call, so both free paths (despawn + exit/reap) are
@@ -3161,6 +3420,7 @@ export class Manager {
                     ? { ...restart.opts, resume: undefined, prompt: undefined, continueSession }
                     : { ...restart.opts, resume: undefined, prompt: undefined };
                 const spec = connector.buildLaunch(opts);
+                spec.env = { ...spec.env, COTAL_MANAGER_INSTANCE: this.managerInstanceId };
                 const wanted = this.managedPrincipal(a);
                 const joinedAfter = this.ep.getRoster()
                     .filter((p) => p.card.id === wanted && p.lifecycleUid === a.lifecycleUid)
@@ -3327,7 +3587,7 @@ export class Manager {
         return false;
     }
     /** Parse an untyped control-plane `start` request into {@link StartAgentOpts}. */
-    opStart(args, caller, hooks, route = "inst") {
+    opStart(args, caller, admin, hooks, route = "inst") {
         // `resume`, when present, must be a non-empty session id. An empty/whitespace value is a
         // malformed request, not an implicit "spawn fresh" (no fallbacks). The CLI surfaces reject it,
         // but a raw control message could otherwise slip an empty value through and silently start fresh.
@@ -3374,6 +3634,31 @@ export class Manager {
         catch (e) {
             return Promise.resolve({ ok: false, error: e.message });
         }
+        // #373: the event-plane admission gate. `startAgent` resolves `eventsRequired || opts.events
+        // !== false`, so omission ARMS the plane — a gate on the explicit bit alone is bypassed by
+        // omitting it. The gate is on the DECISION, and it runs before connector resolution and
+        // before `startAgent` (which mints credentials), so a refusal provisions nothing.
+        const requestedEvents = typeof args.events === "boolean" ? args.events : undefined;
+        let eventsNotice;
+        let events = requestedEvents;
+        if (!admin) {
+            if (requestedEvents === true)
+                return Promise.resolve({
+                    ok: false,
+                    error: `spawn is operator reach; the caller's current ledger grant does not carry "admin" (SPEC 13.2): events: arming the event plane needs the admin tier`,
+                });
+            if (this.eventsRequired)
+                return Promise.resolve({
+                    ok: false,
+                    error: `spawn is operator reach; the caller's current ledger grant does not carry "admin" (SPEC 13.2): space "${this.space}" requires the event plane by registration policy, which cannot be met without the admin tier`,
+                });
+            // Omission arms by default in startAgent; serve it DISARMED and say so (never a silent
+            // downgrade). An explicit `false` is already the opt-out — served as-is, no notice.
+            if (requestedEvents === undefined) {
+                events = false;
+                eventsNotice = `event plane not armed: arming it on spawn needs the admin tier; the spawn was served with events: false`;
+            }
+        }
         return this.startAgent({
             name: String(args.name ?? "").trim(),
             agent: args.agent ? String(args.agent) : undefined,
@@ -3385,7 +3670,8 @@ export class Manager {
             variant: args.variant ? String(args.variant) : undefined,
             launchOptions: args.launchOptions,
             resume: args.resume ? String(args.resume) : undefined,
-            events: typeof args.events === "boolean" ? args.events : undefined,
+            events,
+            eventsNotice,
             cwd: args.cwd ? String(args.cwd) : undefined,
             prompt: args.prompt ? String(args.prompt) : undefined,
             subscribe,
@@ -3881,6 +4167,8 @@ export class Manager {
         }
         if (variant && !connector.supportsModelVariant)
             return { ok: false, error: `${agent} connector does not support model variants (variant)` };
+        if (prompt !== undefined && !connector.supportsPrompt)
+            return { ok: false, error: `${agent} connector does not support an initial prompt (prompt)` };
         // #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
@@ -3963,7 +4251,12 @@ export class Manager {
             // The incarnation's lifecycle UID (SPEC 13.1), minted ONCE per spawn: every lifecycle-keyed
             // broker resource (dm_/dlv_/chathist_ durables, ACL row, memberships) and the teardown
             // credential carry it, so a same-name successor's footprint is name-disjoint by construction.
-            const lifecycleUid = mintLifecycleUid();
+            //
+            // On the HOSTED enrollment arm (#1972) this value is PROVISIONAL. The host selects the
+            // authoritative uid, because it alone reads the retirement tombstones that make a uid
+            // permanently unusable, and the enrollment below rebinds this binding to what the host
+            // returned before anything durable is keyed by it.
+            let lifecycleUid = mintLifecycleUid();
             // Reserve the seat's custody reference NOW, before any durable row and long before the
             // launch. Minting it inside `runtime.spawn` (as it used to be) put the processes on disk
             // before anything recorded how to address them, so a crash in that window left a live seat
@@ -4050,6 +4343,12 @@ export class Manager {
                     this.reserved.delete(name);
                     return { ok: false, error: prep.error };
                 }
+                // THE HOST'S UID WINS (#1972). On the local arm this is the value passed in, unchanged. On
+                // the hosted enrollment arm the host selected it, and from here every lifecycle-keyed thing
+                // this spawn records — the slot, the launch, the managed row, the teardown credential — must
+                // carry that value and not the provisional one, or the manager would address a footprint the
+                // host never created.
+                lifecycleUid = prep.lifecycleUid;
                 userLaunch = prep.launch;
                 userOwner = prep.owner;
                 provisioned = { id: principalKey(prep.owner, name).key, name, lifecycleUid, userOwner: prep.owner, secretPaths: prep.files, ...(custody ? { runtime: custody } : {}) };
@@ -4161,6 +4460,7 @@ export class Manager {
                 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);
             hooks?.onLaunched?.(); // P2 item 2: the "launched" progress edge (process spawned, pre-presence)
             const managed = {
@@ -4194,6 +4494,9 @@ export class Manager {
                     cwd,
                     model,
                     variant,
+                    // The kickoff prompt is part of the launch form: a stale-restart re-submits it, so the
+                    // recorded launch must carry it for the restart gate (and preserve) to see it.
+                    prompt,
                     subscribe,
                     allowSubscribe,
                     allowPublish,
@@ -4289,7 +4592,7 @@ export class Manager {
             // canonicalJson (undefined never coerces to null, SPEC 13.6), so a role-less spawn would
             // otherwise fail its succeeded terminal. The CLI/connector already render an absent role as
             // "no role", so dropping the key preserves the reply (P2 item 2, surfaced by readiness:live).
-            const okData = { name, agent, id: managed.id, mode: handle.kind, lifecycleUid, ...(role !== undefined ? { role } : {}) };
+            const okData = { name, agent, id: managed.id, mode: handle.kind, lifecycleUid, ...(role !== undefined ? { role } : {}), ...(opts.eventsNotice !== undefined ? { eventsNotice: opts.eventsNotice } : {}) };
             await hooks?.onOutcome?.({ kind: "succeeded", data: okData });
             return { ok: true, data: okData };
         }
@@ -4640,6 +4943,8 @@ export class Manager {
                 return { ok: false, error: `${connector.name} harness needs ${missing.join(", ")} on PATH - not found` };
             if (entry.launch.variant && !connector.supportsModelVariant)
                 return { ok: false, error: `${connector.name} connector does not support model variants (variant)` };
+            if (entry.launch.prompt !== undefined && !connector.supportsPrompt)
+                return { ok: false, error: `${connector.name} connector does not support an initial prompt (prompt)` };
             let retainedSession;
             try {
                 retainedSession = this.retainedSessionId(entry, connector);
@@ -4720,6 +5025,7 @@ export class Manager {
                     workspaceRoot: this.workspaceRoot,
                 };
                 const spec = connector.buildLaunch(launchOpts);
+                spec.env = { ...spec.env, COTAL_MANAGER_INSTANCE: this.managerInstanceId };
                 const value = { spec, launchOpts, ...authority };
                 prepared?.set(entry.name, value);
                 if (preflightOnly)