@cotal-ai/manager 0.102.0 → 0.103.2

package/dist/manager.js

@@ -6,7 +6,7 @@ import { isAbsolute, join, dirname, resolve } from "node:path";
 import Headless from "@xterm/headless";
 import { CotalEndpoint, canonicalJson, MANAGED_HANDOFF_KIND, accountFromCreds, credsClaims, DEFAULT_SERVER, DEV_OWNER, MANAGER_LEASE_RENEW_MS, MANAGER_LEASE_TTL_MS, awaitLeaseExpiry, leaseRemainingMs, STANDING_RENEWABLE_TTL_SEC, assertLifecycleToken, discardLaunchArtifacts, divergentSecretStoreNotice, injectedSecretStoreIdentity, parseDaemonStoreAnswer, parseSecretStoreIdentity, sameSecretStoreIdentity, agentFilePath, clearSpaceHistory, dialerFor, connectorServers, spawnEnvAllow, deprovisionAgent, DeprovisionError, addDeprovisionAccounting, isConcreteChannel, deprovisionTargetPrincipal, firstFreeName, spawnNameError, idFromCreds, identityFromCreds, inspectCredHealth, credsRenewalDelayMs, composeWirePersona, loadAgentFile, listPersonaCatalog, personaCatalogDescription, personaCatalogReadable, loadCotalConfig, modelPolicyRefusal, mintCreds, mintGeneration, mintAcceptedToken, openIssuedStore, acceptedBucket, issuedBucket, mintLifecycleUid, managedRetirementOpId, mkSecretDir, newIdentity, oneLine, actionContext, parsePrincipalKey, principalKey, probeConnect, provisionAgent, provisionAgentDurables, registry, resolveAuthProvider, resolveReadAcl, runAgentBearer, saveAgentFile, subjectMatches, AUTH_ENDPOINT, EP_CMD_RETIRE_LIFECYCLE, controlServiceSubject, eventChannelPrincipal, resolveService, invokeCommand, digestIdToken, } from "@cotal-ai/core";
 import { loadLaunchPersonaFile, PersonaSourceError } from "@cotal-ai/workspace";
-import { agentAuthState, agentCredsDir, agentLifecycleSecretFilePaths, agentSecretFilePaths, agentSecretKeyForFile, authDir, claimIdentityRecord, claimManagerSiblingIdentities, connectorInstallHint, DELIVERY_CREDS_KIND, extensionConnectors, findCotalRoot, getSpaceAuth, hasUserAuthState, loadExtensionsManifest, loadManagerInstanceIdentity, loadMeshes, localTrustOfSpace, manifestExtensionNames, materializeFromManifest, materializeSecretToFile, MEMBERSHIP_RW_CREDS_KIND, mergeLaunchOptions, probeLiveness, remintDaemonCreds, resolveAgentType, resolveOnPath, createManagerInstanceIdentity, spaceKey, spaceMaterialKey, SYSTEM_CREDS_FILES, userAuthStateDir, workspaceSecretStore, writeRenewalRecord } from "@cotal-ai/workspace";
+import { agentAuthState, agentCredsDir, agentLifecycleSecretFilePaths, agentSecretFilePaths, agentSecretKeyForFile, authDir, claimIdentityRecord, claimManagerSiblingIdentities, connectorInstallHint, DEFAULT_SEAT_CAP, DELIVERY_CREDS_KIND, extensionConnectors, findCotalRoot, getSpaceAuth, hasUserAuthState, loadExtensionsManifest, loadManagerInstanceIdentity, loadMeshes, localTrustOfSpace, manifestExtensionNames, materializeFromManifest, materializeSecretToFile, MEMBERSHIP_RW_CREDS_KIND, mergeLaunchOptions, probeLiveness, remintDaemonCreds, resolveAgentType, resolveOnPath, createManagerInstanceIdentity, SEAT_CAP_UNLIMITED, spaceKey, spaceMaterialKey, SYSTEM_CREDS_FILES, userAuthStateDir, workspaceSecretStore, writeRenewalRecord } from "@cotal-ai/workspace";
 import { createRuntime, exitProof, isCustodialRuntime, pollProvedExit, requireRuntimeAdopt, requireRuntimeReap, RuntimeReapUnproven, watchProvedExit, } from "./runtime/index.js";
 import { AttachEndpoint } from "./attach-endpoint.js";
 import { DELIVERY_ADMIN_BOOT_WAIT_MS, isUnansweredDeliveryAdmin, makeManagerEndpointEvictionEvidence, makeManagerEndpointHolderEvictor, untilDeliveryAdminAnswers, withScopedEndpoint } from "./endpoint-evict.js";
@@ -32,7 +32,7 @@ import { ManagerSessionPlane, openSessionLedgerKv } from "./session/index.js";
 // The manager as an ordinary v0.4 `service` endpoint — the §13.1
 // endpoint-serve credential subsystem (gate provisioning, registration barrier, mint fence) plus
 // the register/authorize/serve seams, all driven over a scoped one-shot executor connection.
-import { provisionEndpointGateOpen, endpointRegistrationBarrier, serveIssuanceGateKv, commitSiblingIssuance, markLedgerRowRevoked, epcredRowKey, epgateKey, parseEndpointGate, readEndpointGateGeneration, registerServingInstance, deregisterServiceInstance, serveEndpoint, bindGoal, createGoal, transitionGoal, commitGoalResult, requestGoalCancel, goalAlreadyTerminal, settleGoalUncertain, readGoalResult, readGoalStatus, readGoalSpec, recordGoalIndex, readGoalIndex, clearGoalIndex, listGoalIndex, mintCheckpoint, resumeCheckpoint, readCheckpointSettle, readCheckpointSpec, expireCheckpoint, GOAL_TERMINAL_STATES, goalRefOf, goalProgressTopic, turnNoticeSubject, epeSubject, submissionFingerprint, EpEnvelopeError, lifecycleBlocked, lifecycleBlockedFrom, renderLifecycleBlocked, } from "@cotal-ai/core";
+import { provisionEndpointGateOpen, endpointRegistrationBarrier, serveIssuanceGateKv, commitSiblingIssuance, markLedgerRowRevoked, epcredRowKey, epgateKey, parseEndpointGate, readEndpointGateGeneration, registerServingInstance, deregisterServiceInstance, serveEndpoint, bindGoal, createGoal, transitionGoal, commitGoalResult, requestGoalCancel, goalAlreadyTerminal, settleGoalUncertain, readGoalResult, readGoalStatus, readGoalSpec, recordGoalIndex, readGoalIndex, clearGoalIndex, listGoalIndex, mintCheckpoint, resumeCheckpoint, readCheckpointSettle, readCheckpointSpec, expireCheckpoint, GOAL_TERMINAL_STATES, goalRefOf, goalProgressTopic, turnNoticeSubject, epeSubject, submissionFingerprint, EpEnvelopeError, lifecycleBlocked, seatCapRefused, lifecycleBlockedFrom, renderLifecycleBlocked, controlReplyFromThrown, } from "@cotal-ai/core";
 import { MANAGER_ENDPOINT, managerClusterArtifacts, managerCommandDefs, managerContractArtifactValues } from "./manager-service-contract.js";
 import { measureManagerVitals } from "./vitals.js";
 import { staticLifecycleTransport, activateStaticLifecycle, runStaticTerminal, readStaticSlot, casStaticSlot, recordSlotCredential, appendStaticCredentialRow, planStaticSlotResume, ownedBySibling, observeStaticSlot, listStaticSlotObservations, walkStaticSlots, renderStaticSlotObservation, StaticSlotReadError, STATIC_SLOT_READ_FAILED_DETAIL, } from "./static-lifecycle.js";
@@ -136,6 +136,12 @@ const STATIC_RECONCILE_MAX_ATTEMPTS = STATIC_RECONCILE_RETRY_DELAYS_MS.length +
 function retireOpId(lifecycleUid) {
     return managedRetirementOpId(lifecycleUid);
 }
+/** The owner a retained seat resumes under: its inventory identity's, which is the same value the
+ *  adopted seat records as `userOwner`, so a resumed seat is counted against the owner that held
+ *  it before the restart ({@link Manager.ownerSeats}) and not against the mesh's default one. */
+function resumeOwner(entry) {
+    return entry.identity.mode === "user" ? entry.identity.owner : DEV_OWNER;
+}
 /** Sentinel owner-filter value that matches NO agent's `userOwner` (owner tokens never contain a
  *  dash) — what {@link Manager.psOwnerFilter} returns for an unparseable caller so a malformed
  *  principal fail-closes to an empty `ps` instead of an unbounded one. */
@@ -355,6 +361,8 @@ export class Manager {
     eventsRequired;
     /** The operator-set global live-session ceiling (see {@link ManagerOptions.maxSessions}). */
     maxSessions;
+    /** The operator-set per-owner seat ceiling (see {@link ManagerOptions.seatCap}). */
+    seatCap;
     /** The ONE secret store for every kind this manager touches (daemon-cred remint + agent kinds).
      *  See {@link ManagerOptions.secretStore}. */
     secrets;
@@ -371,8 +379,11 @@ export class Manager {
     agents = new Map();
     /** Names whose spawn is in flight (reserved synchronously before the provision await) — counted
      *  toward the ceiling (once per name, see {@link Manager.occupancy}) so two concurrent same-name
-     *  spawns can't both pass the gate (P4a). */
-    reserved = new Set();
+     *  spawns can't both pass the gate (P4a). Each name carries the OWNER its launch was admitted
+     *  for, so the per-owner ceiling ({@link Manager.ownerSeats}) counts a launch from the moment it
+     *  is reserved; a cap read only off `agents` would let a burst of concurrent spawns overshoot it,
+     *  because none of them has a seat yet when the next one checks. */
+    reserved = new Map();
     /** Reserved names whose launch already put its seat in `agents`. The name stays reserved until
      *  the launch settles, so no other spawn can take it, but the ceiling counts that seat through
      *  `agents` and, if it frees young, its cooling stamp, never through the reservation (#906). */
@@ -687,6 +698,7 @@ export class Manager {
         this.onServiceIdentity = opts.onServiceIdentity;
         this.eventsRequired = opts.eventsRequired === true;
         this.maxSessions = opts.maxSessions;
+        this.seatCap = opts.seatCap ?? DEFAULT_SEAT_CAP;
         this.remoteAuthority = opts.remoteAuthority;
         this.remoteExecutorCreds = opts.remoteAuthority?.executorCreds;
         this.remoteSupervisorCreds = opts.remoteAuthority?.supervisorCreds;
@@ -3048,7 +3060,7 @@ export class Manager {
         // only — the action model gives failures a typed channel.
         const unwrap = (r) => {
             if (!r.ok)
-                throw new EpEnvelopeError("failed-precondition", r.error ?? "the operation failed");
+                throw new EpEnvelopeError((r.code ?? "failed-precondition"), r.error ?? "the operation failed", r.details);
             return r.data;
         };
         // The admin-family serve gate: every `manager.admin`-class
@@ -5531,6 +5543,16 @@ export class Manager {
         // collision, a manifest name and a `--name` override all meet it, and before the reservation.
         if (name.startsWith(CHAT_ALIAS_PREFIX))
             return { ok: false, error: `the name "${name}" starts with "${CHAT_ALIAS_PREFIX}", which is reserved for chat sessions; pick another name` };
+        // THE PER-OWNER CEILING, read in the same synchronous window as the reserve below rather than
+        // beside the host capacity gate higher up: the count it takes must be the one the reservation
+        // lands against, or a burst of concurrent launches for one owner each reads a count taken
+        // before any of the others reserved, and they all pass. Nothing between here and the reserve
+        // awaits. It refuses BEFORE `onEffect`, so the launch states `not-executed` and leaves no
+        // name, no mint and no footprint behind.
+        const owner = this.launchOwner(opts, spawner);
+        const overCap = this.seatCapRefusal(owner);
+        if (overCap)
+            return { ok: false, code: overCap.code, error: overCap.message, ...(overCap.details ? { details: overCap.details } : {}) };
         // Set once the agent's footprint (durables + creds, or the user-mode grant + secret files)
         // exists; cleared when a live slot takes ownership. If it survives to `finally`, the spawn threw
         // AFTER provisioning (buildLaunch / runtime.spawn) — the orphan-rollback tears it down. Carries
@@ -5547,7 +5569,7 @@ export class Manager {
         // Taken right before the try so its finally is the only release; a refusal belongs above the
         // allocation, where there is no name to give back.
         hooks?.onEffect?.();
-        this.reserved.add(name);
+        this.reserved.set(name, owner);
         try {
             // A stable nkey identity assigned at spawn: the public key is the agent's card.id (threaded via
             // COTAL_ID); the seed is retained to mint matching creds later.
@@ -5577,8 +5599,8 @@ export class Manager {
             // freshly-minted nkey; user mode keys on the derived owner (opts.owner, else a u_-owner spawner)
             // + the alias — derived HERE where the mode and owner source are in scope.
             const agentTriple = this.userMode
-                ? { owner: opts.owner ?? (spawner && parsePrincipalKey(spawner)?.owner.startsWith("u_") ? parsePrincipalKey(spawner).owner : DEV_OWNER), actor: name, uid: lifecycleUid }
-                : { owner: DEV_OWNER, actor: identity.id, uid: lifecycleUid };
+                ? { owner, actor: name, uid: lifecycleUid }
+                : { owner, actor: identity.id, uid: lifecycleUid };
             // THE EVENT GRANT, derived from the principal that was actually ALLOCATED and never from the
             // display name. A display name is UI convenience: this mesh permits two live agents to carry
             // one, so a name-keyed channel fuses two principals onto one subject and, in auth mode,
@@ -5661,7 +5683,7 @@ export class Manager {
                 if ("error" in prep) {
                     if (prep.refused !== undefined)
                         hooks?.onUndone?.(prep.refused);
-                    return { ok: false, error: prep.error, ...(prep.details ? { details: prep.details } : {}) };
+                    return { ok: false, error: prep.error, ...(prep.refused !== undefined ? { code: prep.refused } : {}), ...(prep.details ? { details: prep.details } : {}) };
                 }
                 // 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
@@ -6000,15 +6022,15 @@ export class Manager {
         catch (e) {
             // Failure after reserve (provision / launch threw): the slot was never live, so no cold-start
             // was paid — the reserved rollback (finally) is enough, no cooling stamp.
-            // A lifecycle-blocked envelope already named the barrier; keep its details on the ControlReply
-            // so follow/CLI/cotal_spawn do not collapse it to a generic string (#873). An extension can throw
+            // Keep the envelope's code and lifecycle details on the ControlReply so the serve boundary
+            // can carry the refusal's classification and barrier to the caller. An extension can throw
             // any value, and an envelope's `message` is only typed as a string, so the refusal text always
             // comes from rejectionText; telling an envelope apart is guarded because a thrown Proxy can
             // throw from `instanceof` or from its own fields.
             const error = rejectionText(e);
             try {
                 if (e instanceof EpEnvelopeError)
-                    return { ok: false, error: renderLifecycleBlocked(error, e), ...(e.details ? { details: e.details } : {}) };
+                    return controlReplyFromThrown(e, error);
             }
             catch { /* not a readable envelope */ }
             return { ok: false, error };
@@ -6108,7 +6130,7 @@ export class Manager {
                     return { ok: false, agents: [], error: `retained agent "${entry.name}" is already managed or reserved` };
             }
             for (const entry of entries) {
-                this.reserved.add(entry.name);
+                this.reserved.set(entry.name, resumeOwner(entry));
                 batchReservations.push(entry.name);
             }
             const preflight = [];
@@ -6528,7 +6550,7 @@ export class Manager {
     }
     async launchPreparedResume(entry, prepared, batchReserved, supervised) {
         if (!batchReserved)
-            this.reserved.add(entry.name);
+            this.reserved.set(entry.name, resumeOwner(entry));
         try {
             // Unit B F5(b): recover the STATIC identity's nkey seed from the adopted credential (the
             // creds file embeds it) so the manager stays this incarnation's RENEWAL OWNER across a
@@ -6932,7 +6954,7 @@ export class Manager {
         const cooling = this.coolingCount();
         let reserved = 0;
         let launching = 0;
-        for (const name of this.reserved) {
+        for (const name of this.reserved.keys()) {
             const placed = this.reservedLive.has(name);
             if (!placed)
                 reserved++;
@@ -6963,6 +6985,59 @@ export class Manager {
                 : "waiting frees no slot; despawn one";
         return `at capacity (${this.occupancyText(o)}); ${remedy}`;
     }
+    /**
+     * The owner a launch belongs to, read ONCE so the per-owner ceiling, the agent's addressing
+     * triple and the user-mode provisioner cannot charge three different owners for one seat. A
+     * static or open mesh has one owner by construction; a user-auth mesh takes the spec's owner,
+     * else the owner of the principal that asked, which is what {@link provisionUserAgent} resolves
+     * from the same two values (it refuses outright where this falls back, so the two never disagree
+     * on an admitted launch).
+     */
+    launchOwner(opts, spawner) {
+        if (!this.userMode)
+            return DEV_OWNER;
+        const asked = spawner === undefined ? undefined : parsePrincipalKey(spawner)?.owner;
+        return opts.owner ?? (asked?.startsWith("u_") ? asked : DEV_OWNER);
+    }
+    /** The owner of a seat this manager supervises, by the same rule {@link launchOwner} admitted it
+     *  under: a user-mode seat records its derived owner, and every other seat is the mesh's one owner. */
+    seatOwner(a) {
+        return a.userOwner ?? DEV_OWNER;
+    }
+    /**
+     * Live seats this manager holds for one owner: the seats it supervises, plus the launches it has
+     * reserved for that owner and not yet placed. It deliberately does NOT count cooling stamps — a
+     * cooling slot is a seat that already freed, and the recycle floor it holds is a global
+     * fork-bomb bound (P4c), not one tenant's occupancy. Mirrors {@link occupancy}'s reserved rule,
+     * so a reservation stops being counted twice the moment its seat reaches `agents`.
+     */
+    ownerSeats(owner) {
+        let seats = 0;
+        for (const a of this.agents.values())
+            if (this.seatOwner(a) === owner)
+                seats++;
+        for (const [name, reservedFor] of this.reserved)
+            if (reservedFor === owner && !this.reservedLive.has(name))
+                seats++;
+        return seats;
+    }
+    /**
+     * The per-owner ceiling, consulted at accept: `undefined` admits the launch, and a refusal
+     * carries the owner's count and the cap so a caller can render a remedy and a script can decide
+     * without re-reading prose. Distinct from {@link capacityRefusal}, which bounds the HOST: that
+     * one frees when anyone stops a seat or a cooling slot expires, this one frees only when THIS
+     * owner stops one of its own, or the operator raises the cap, so they cannot share a sentence.
+     */
+    seatCapRefusal(owner) {
+        const cap = this.seatCap;
+        if (cap === SEAT_CAP_UNLIMITED)
+            return undefined;
+        const seats = this.ownerSeats(owner);
+        if (seats < cap)
+            return undefined;
+        return seatCapRefused(`owner ${owner} holds ${seats} of the ${cap} seat${cap === 1 ? "" : "s"} manager ${this.managerInstanceId} admits per owner; ` +
+            `stop one of that owner's seats, or ask the operator who runs this manager for a higher seat cap`, { owner, seats, cap });
+    }
     async opStop(args, caller, admin) {
         const name = String(args.name ?? "").trim();
         const a = this.agents.get(name);
@@ -8434,8 +8509,7 @@ export class Manager {
             // outcome unknown.
             if (acceptance === undefined) {
                 const details = reply.details;
-                // A hard-pinned name a live incarnation holds is the one refusal here that names its own code.
-                const code = undone ?? (reply.code === "already-exists" ? "already-exists" : "failed-precondition");
+                const code = undone ?? reply.code ?? "failed-precondition";
                 rejectAccept(new EpEnvelopeError(code, reply.error ?? "spawn refused at accept", details, effectStarted && undone === undefined ? undefined : "not-executed"));
                 return;
             }