@cotal-ai/manager 0.16.0 → 0.17.0

package/dist/manager.d.ts

@@ -1,5 +1,6 @@
 import type { ControlReply, MeshLaunchAgent, SecretStore } from "@cotal-ai/core";
 import { type RuntimeMode } from "./runtime/index.js";
+import { type Identity } from "@cotal-ai/core";
 /** Backstop for the detached-launch readiness race (#159 B1). `startAgent` waits on two REAL outcomes —
  *  the assigned id joining the mesh (presence) = started, the child process exiting = failed — NOT a
  *  liveness-inferring timer. This is only the last-resort bound for "neither happened in time": the launch
@@ -18,12 +19,15 @@ export interface ManagerOptions {
     workspaceRoot?: string;
     /** Port for the console + attach HTTP/WS endpoint. 0 → ephemeral. */
     consolePort?: number;
-    /** Bind address for that endpoint, and the host it advertises in attach/console URLs. Defaults to
-     *  loopback, which keeps the endpoint reachable only from this machine. `cotal up` passes the
-     *  address it bound the broker to, so `cotal attach` can reach a manager on another machine; set
-     *  it yourself only if you intend to expose terminal access (see the security note on
-     *  {@link AttachEndpoint}). A wildcard here binds every interface and still advertises loopback,
-     *  since a wildcard is not an address a client can dial. */
+    /** P2 item 6: the broker's WebSocket listener port (loopback), allocated by `cotal up`. When set,
+     *  the console page becomes a mesh §13.6 session client — `POST /session/<name>` returns the grant +
+     *  a per-session cred + this ws URL. Absent ⇒ no console session client (the route 503s). */
+    wsPort?: number;
+    /** Bind address for the console endpoint, and the host it advertises in {@link Manager.consoleUrl}.
+     *  Defaults to loopback, which keeps the console reachable only from this machine. Set it only if
+     *  you intend to expose the console (see the security note on {@link AttachEndpoint}). A wildcard
+     *  here binds every interface and still advertises loopback, since a wildcard is not an address a
+     *  client can dial. The TERMINAL is unaffected either way: it rides the mesh session, not this face. */
     attachHost?: string;
     /** Internal/test override for the preservation child-exit deadline. */
     preserveStopTimeoutMs?: number;
@@ -43,6 +47,13 @@ export interface ManagerOptions {
      *  unchanged. It must be the SAME store the delivery daemon reads (`runDelivery(args, store)`), or a
      *  hosted remint writes one store while the daemon reads another and rides to expiry. */
     secretStore?: SecretStore;
+    /** P2 item 6: the global ceiling on concurrently live §13.6 sessions this manager will serve.
+     *  Defaults to {@link MAX_LIVE_SESSIONS_DEFAULT}. Each session mints a credential and opens its
+     *  own connection, and establishment is caller-triggered, so this is the process-level resource
+     *  bound; exceeding it refuses `resource-exhausted` before either happens. Operator-set because
+     *  the right number is deployment-shaped — the browser console holds one session per open pane.
+     *  {@link ManagerSessionPlaneDeps.maxSessions} carries the per-caller-scoping residual. */
+    maxSessions?: number;
 }
 export type ManagerMaintenanceState = "active" | "preserving" | "preserved";
 export type ManagerResumeIdentity = {
@@ -230,11 +241,66 @@ export interface StartAgentOpts {
  * through a pluggable {@link Runtime} (pty by default). It does NOT proxy agent
  * mesh traffic — terminal I/O streams over its own attach endpoint instead.
  */
+/** Runtime hooks the spawn-as-action serve path (P2 item 2) injects into {@link Manager.startAgent}.
+ *  Roster boot and the blocking callers pass none (unchanged behavior). */
+export interface SpawnHooks {
+    /** Fires synchronously AFTER the incarnation identity (nkey + lifecycleUid) is minted but BEFORE
+     *  any provision/side-effect — the accept seam: it binds the goal and replies the acceptance. A
+     *  THROW here aborts the spawn before provisioning (the existing catch returns the failure and the
+     *  finally releases the reserve, so no footprint leaks) — this is the bind-conflict refusal path. */
+    onAccepted?: (allocated: {
+        name: string;
+        identity: Identity;
+        lifecycleUid: string;
+        agentTriple: {
+            owner: string;
+            actor: string;
+            uid: string;
+        };
+    }) => Promise<void> | void;
+    /** Fires once the child process has been launched (the "launched" progress edge). */
+    onLaunched?: () => void;
+    /** Fires at the readiness verdict (presence join → succeeded / process exit → failed / window
+     *  elapsed → uncertain), carrying the succeeded reply data — the async serve body commits the goal
+     *  terminal + emits the final progress event here. Awaited, but the caller swallows its own errors
+     *  so a terminal-commit failure never disrupts the (already-replied) spawn. */
+    onOutcome?: (outcome: {
+        kind: "succeeded" | "failed" | "uncertain";
+        data?: unknown;
+    }) => Promise<void> | void;
+    /** Fires when this spawn ends with its goal's terminal owned by ANOTHER path — today only a
+     *  despawn/stop that lands inside the readiness window, whose own handler commits `cancel`.
+     *  It commits nothing; it only claims the terminal so the post-accept fallback does not
+     *  manufacture a `failed` from the non-ok reply and race the real `cancel`. Without it, a
+     *  deliberate stop mid-launch reports the agent as having died on launch. */
+    onTerminalDeferred?: () => void;
+}
+/** The spawn-as-action acceptance (P2 item 2 floor): the ALLOCATED agent identity (name + the
+ *  addressing triple item-1 addresses by) plus the goal coordinates (goalId = the request id) and
+ *  the executor coordinate (the manager incarnation its terminal fences on). Carries NO secret
+ *  material (pin 7); it names what was actually allocated, never a requested-but-unallocated name. */
+export interface SpawnAcceptance {
+    name: string;
+    owner: string;
+    actor: string;
+    uid: string;
+    goalId: string;
+    fingerprint: string;
+    executor: {
+        lifecycleUid: string;
+        epoch: number;
+    };
+}
 export declare class Manager {
     private readonly space;
     private readonly servers;
+    /** P2 item 6: the broker ws listener port (loopback) `cotal up` allocated, for the console session
+     *  client's wsUrl. Undefined ⇒ no console session client (POST /session 503s). */
+    private readonly wsPort?;
     private readonly name;
     private readonly workspaceRoot;
+    /** P2 item 6: the operator-set global live-session ceiling (see {@link ManagerOptions.maxSessions}). */
+    private readonly maxSessions?;
     /** The ONE secret store for every kind this manager touches (daemon-cred remint + agent kinds).
      *  See {@link ManagerOptions.secretStore}. */
     private readonly secrets;
@@ -264,6 +330,82 @@ export declare class Manager {
      *  same-name SUCCESSOR (which can spawn after the hold clears but before this flight's `nc.close`
      *  yield settles) never joins the predecessor's rail request and skips its own retirement. */
     private retiringFlight;
+    /** Wire principals of RETIRED static incarnations (Unit B, F5(a)): populated at every completed
+     *  static terminal and from the boot sweep's retired slot rows, so a copied credential of a
+     *  retired incarnation is refused at the control surface even across a manager restart. The
+     *  durable truth is the slot row + principal-keyed head; this set is the in-memory index of it
+     *  (one string per retired incarnation — bounded by lifecycle count, never pruned in-process). */
+    private readonly retiredPrincipals;
+    /** This manager process's own incarnation uid (SPEC 13.1; minted once per supervisor process,
+     *  never reused across restarts) — the endpoint's presence key AND the `managerInstance` audit
+     *  coordinate every static activation records. */
+    private readonly managerLifecycleUid;
+    /** The persisted LOGICAL instance id (SPEC 13.6 item 7, P2 item 3): STABLE across restart, so a
+     *  restart re-registers the SAME id with an ADVANCED epoch through the §13.1 gate (the successor
+     *  fences the predecessor's epoch — the (i) fence bites on a real restart). It is the registration
+     *  instanceId, the served-status id, the goal spec's executor.instanceId, the epe route, and the
+     *  resolveExecutorEpoch key — DISTINCT from {@link managerLifecycleUid} (per-process: the presence
+     *  node uid + the managerInstance audit coordinate every static activation records). Set in start(). */
+    private managerInstanceId;
+    /** The persisted serve nkey identity: reusing the SAME principal across restart keeps
+     *  {@link provisionEndpointGateOpen} idempotent (no core barrier change) and gives verified
+     *  eviction a stable target (the predecessor's connections under this principal). Set in start(). */
+    private managerServeIdentity;
+    /** P2 item 1 (1a-serve): the manager's v0.4 service-endpoint serve state — the serve handle +
+     *  its dedicated connection, the STABLE serve identity (renewals re-mint the same nkey), the
+     *  branded serve grant, and the CURRENT credential (the connection's authenticator reads it on
+     *  every (re)connect, so a renewal is adopted without re-registration). Absent on open meshes,
+     *  in user mode (the named 1a follow-up), and before registration completes. */
+    private serviceServe?;
+    /** P2 item 2 (spawn-as-action): the SELF-MEDIATED goal-writer connection + ActionContext — a
+     *  standing connection DISJOINT from the serve credential (Q2), scoped to exactly this endpoint's
+     *  goal bind/terminal facts + goal-record writes ({@link goalWriterGrants}). Auth mode mints the
+     *  `goal-writer` cred; an open mesh uses a bare connection (no credential system to mint from).
+     *  `gate` (auth mode) is the own-issuance-gate READER for the must-5 (a) currency belt — the
+     *  manager reads its OWN `epgate.<e>.<iid>` epoch over this connection before a terminal commit
+     *  and skips a superseded commit (the fast-fail belt paired with the (b) barrier-revoke fence). */
+    private goalWriter?;
+    /** P2 item 2 must-5 (b): the STABLE goal-writer identity (auth mode) — minted once at
+     *  registration alongside the serve identity; a renewal re-mints the SAME nkey with a fresh
+     *  bounded exp and re-stages its distinct credId into the §13.1 revocation family. The current
+     *  goal-writer credential is minted INSIDE {@link registerManagerService}'s run block (fence
+     *  live) and stashed here for {@link startGoalWriter} to build the standing connection from. */
+    private goalWriterIdentity?;
+    private goalWriterCreds?;
+    /** P2 item 6: the manager's ONE §13.6 session plane — offer mint + one-use redeem + PTY-bridge
+     *  standup for `attach`. The face's establisher and the CLI attach handler both call THIS one
+     *  plane; the manager never constructs a second. Undefined until {@link startSessionPlane}. */
+    private sessionPlane?;
+    /** P2 item 6: the standing session-LEDGER connection + its mutable creds holder (the authenticator
+     *  presents the refreshed cred on the next reconnect after a half-TTL renewal — the goal-writer
+     *  precedent). Auth mode only; an open mesh runs the plane over a bare connection. */
+    private sessionLedgerConn?;
+    /** P2 item 6: credentialId → the nkey that credential was minted for, for the live per-session
+     *  SERVING credentials. The §13.1 ledger row records the holder principal, and the row is written
+     *  at stage time (after the mint), so the two steps need this one hop. Entries are dropped at
+     *  revoke; a session that never staged drops its entry when the manager exits. */
+    private readonly sessionServingKeys;
+    /** P2 item 6: the STABLE session-LEDGER identity (auth mode) — minted once at registration
+     *  alongside the serve + goal-writer identities; a renewal re-mints the SAME nkey with a fresh
+     *  bounded exp and re-stages its distinct credId into the §13.1 revocation family. The current
+     *  credential is minted INSIDE {@link registerManagerService}'s run block and stashed here. */
+    private sessionLedgerIdentity?;
+    private sessionLedgerCreds?;
+    /** P2 item 2: the acceptance replied for each in-flight goalId this incarnation accepted, so an
+     *  idempotent same-goalId retry serves the IDENTICAL acceptance (same allocated name/triple) without
+     *  a second spawn. Durable cross-incarnation reconstruction rides the must-5 goal-index; here the
+     *  live map covers same-incarnation retries, with the committed result fact as the fallback. */
+    private goalAcceptances;
+    /** P2 item 2 must-5 Q-B: the boot reconcile of the durable goal index runs ONCE at start (a
+     *  fresh incarnation inherits the endpoint's accepted-but-unterminal goals from any predecessor).
+     *  Spawn-as-action REFUSES to accept until it completes, so the sweep never races a live goal's
+     *  acceptance (settling one mid-flight would steal its real terminal). */
+    private goalReconcileDone;
+    /** P2 item 2 (M4): the live spawn goal ref for each managed agent name, so a despawn MID-GOAL
+     *  drives the cancel path (transition -> cancel terminal). Cleared when the goal terminalizes. */
+    private agentGoals;
+    /** Process start, for the served `status` uptime. */
+    private readonly startedAtMs;
     /** SINGLE-FLIGHT guard for {@link deprovision} (INT-2/C): one in-flight teardown per
      *  (name, lifecycleUid). The detached freeSlot teardown and every same-name-spawn nudge that
      *  re-drives it JOIN one promise instead of launching a SECOND, concurrent teardown. Without it,
@@ -324,6 +466,20 @@ export declare class Manager {
      *  (no responder) is recorded honestly: each daemon's own 75% renewal timer remains the adoption backstop.
      *  Never throws — renewal failure must be LOUD (log + record), not fatal to the supervisor. */
     private renewDaemonCreds;
+    /** Warn, on every renewal pass, when a $SYS credential is at or past its renewal point.
+     *
+     *  The manager is the renewal owner for every credential it CAN re-sign, and these two are the ones
+     *  it cannot: they are `rotation-renewed`, so no resident process re-mints them and they simply die
+     *  on their 30-day horizon. Before this, a mesh that never ran `doctor auth` got no signal at all,
+     *  it discovered the expiry as an "Authorization Violation" in the delivery log and a refused
+     *  membership adoption, weeks after the warning would have been actionable (#338). The pass runs
+     *  every half-TTL of the 24h class, so this repeats about twice a day for the ~7 days between the
+     *  renewal point and expiry: loud enough to be seen, bounded enough not to be noise.
+     *
+     *  Diagnostic only, and deliberately non-fatal: renewal is an operator action (`cotal down` then
+     *  `cotal up --rotate-sys`, which needs a broker restart), so the manager must report it, never
+     *  attempt it. An absent file is the unprovisioned space, reported by the daemon that needs it. */
+    private warnOnSystemCredExpiry;
     /** Admit one lifecycle/control operation while active. The synchronous increment is the fence:
      * preserveState flips state before its first await, so work is either counted or rejected. */
     private beginLifecycle;
@@ -365,19 +521,89 @@ export declare class Manager {
     private teardownManagedAgents;
     private stopRetainedAgentsOnExit;
     stop(): Promise<void>;
-    /** Refresh the singleton lease before the bucket TTL expires it. On loss (missed the TTL, or another
-     *  manager took over after a gap) FAIL CLOSED: stop serving control at once so we can't double-process
-     *  with the new holder, and exit. We deliberately do NOT re-acquire (a replacement may already be live
-     *  while we'd still be serving) and do NOT release the key — it now belongs to that replacement. */
+    /** Stop the v0.4 service-endpoint serve loop (drain subscriptions, await in-flight handlers)
+     *  and drop its dedicated connection. Best-effort by design — both exit paths (graceful stop,
+     *  lease-loss fail-close) must complete their remaining teardown even if the broker is gone. */
+    private stopServiceServe;
+    /** Refresh THIS instance's liveness lease before the bucket TTL expires it. On loss (missed the TTL —
+     *  this instance stalled past the renew window) FAIL CLOSED for THIS INSTANCE ONLY: stop serving +
+     *  tear down OUR managed agents + exit, so a stalled instance can't keep double-processing under a key
+     *  a same-id restart may re-acquire. Keyed per instance, so this NEVER frees or touches a sibling
+     *  manager's key and NEVER freezes the space (security pin 6) — the sibling keeps serving. We do NOT
+     *  re-acquire (a same-id restart may already be live) and do NOT release the key (it may be the
+     *  restart's). A DIFFERENT instance losing ITS key is a separate, independent event. */
     private renewLease;
-    private handle;
+    private opFinalizeResume;
+    private opCommitResume;
+    private opResumePreserved;
+    private opPreservationCtl;
+    /** The ONE shared control-admission chokepoint (P2 item 1, checklist 3/8) BOTH dispatch doors
+     *  run — the v0.3 `ctl` door ({@link handle}) and the v0.4 `ep` service handlers
+     *  ({@link serveGated}): the maintenance/resume fence (`beginLifecycle`: a resume-pending or
+     *  non-active manager accepts no ordinary control work) and then the F5(a) membership gate
+     *  ({@link lifecycleMembershipRefusal}: a retiring/terminalizing/retired managed incarnation's
+     *  AUTHENTICATED principal holds no control authority even with a valid JWT). Refusal carries
+     *  WHICH fence refused so the ep door can map onto the §13.3 catalog; admission returns the
+     *  accepted-work release. Never re-implemented per door — a fence on one door is a bypass. */
+    private admitControl;
+    /** Run one v0.4 service-command handler through the SHARED admission chokepoint
+     *  ({@link admitControl}) on the broker-authenticated caller principal, mapping the two fences
+     *  onto the §13.3 catalog: maintenance/resume → `unavailable`, F5(a) membership →
+     *  `permission-denied`. The serve boundary publishes the structured error reply. */
+    private serveGated;
+    /** The ep door's ADMIN flag for a caller (the 1c tier refinement). Static mesh: `true` — the
+     *  admin-grade rows (any-mode despawn/attach, the `manager.admin` family, `launch`) are minted
+     *  only into operator instruments (§13.2: `any` is operator-policy-mintable; the agent/spawn
+     *  rollups never carry them), so REACHING the handler is holding the admin tier, exactly as
+     *  holding `ctl.<admin>` is today. User mesh: the caller's CURRENT ledger scope must carry
+     *  `admin` — the same fresh-read authority {@link psOwnerFilter} consults, so a revoked scope
+     *  demotes the very next call even on a still-valid bearer. Fail-closed: an unreadable ledger
+     *  authorizes nothing. NAMED RESIDUAL (critic, 1c.2b): the static `true` has no serve-time
+     *  re-check — a LEAKED static admin instrument keeps its reach until the credential's bounded
+     *  TTL (the one-shot 5-minute profile), the same static-revoke≠reconnect-death class ruled
+     *  across this campaign; static revocation is the TTL, not a ledger. */
+    private epAdminReach;
+    /** A targeted request's admin flag: mode `any` (the operator instrument's cross-agent form,
+     *  rev 3) resolves through {@link epAdminReach}; a user-mode any-mode caller whose CURRENT
+     *  ledger row lost `admin` since its rows were minted refuses loud rather than silently
+     *  downgrading to the owner path (the request's declared mode is honored or denied, never
+     *  reinterpreted). Owner mode is always the privileged (own-domain) path. */
+    private epAnyModeAdmin;
+    /** The v0.4 typed command table (P2 item 1, slice 1b): every ordinary handler runs the SHARED
+     *  admission chokepoint ({@link serveGated}) and then delegates to the SAME op core the ctl
+     *  door dispatches (checklist 8: one core, two thin doors). The resume/preservation family
+     *  deliberately BYPASSES serveGated — exactly as it sits before {@link admitControl} on the ctl
+     *  door (those ops must run while `resumeRequired` fences ordinary work) — riding its own state
+     *  fences; its ep gate is the admin-grade `manager.admin` capability grant (the 1b rule: static
+     *  admin-class commands are capability-gated + untargeted, never a fabricated ledger mode).
+     *
+     *  TIER SEMANTICS on the ep door (the 1c grant-migration table): the tier lives in the CALLER'S
+     *  GRANT, refined per-op exactly as the ctl doors refine their subject tier. Owner-mode
+     *  `despawn`/`attach` keep the privileged semantics (`admin=false`, own-domain via
+     *  {@link authorizeNamed}) — every spawn-capable agent holds those rows. ANY-mode requests are
+     *  the operator instrument's cross-agent reach (rev 3): the any-mode subject row is mintable
+     *  only under operator policy (§13.2), so on a static mesh holding it IS the admin tier, and in
+     *  user mode the caller's CURRENT ledger scope must still carry `admin`
+     *  ({@link epAdminReach}, the same fresh-read authority `psOwnerFilter` consults). The
+     *  `manager.admin` family (purge + the resume/preservation ops) is capability-gated at mint AND
+     *  re-checked at serve time via {@link epAdminReach} (the `adminGated` wrapper) so a user's
+     *  revoked scope demotes the next call. `launch` is OWNER-EQUALITY on this door for everyone
+     *  (freelance HIGH #2): the deploy path is its only consumer and stamps the caller's own owner,
+     *  so cross-owner launch was a ctl-tier incidental never exercised, and keying it on the actor's
+     *  ledger scope broke the deployer-view attenuation - uniform owner-equality is the safe tier.
+     *  TWO DELIBERATE NARROWINGS vs the ctl doors (NOT bit-exact parity, panel-accepted): (1)
+     *  `define-persona` is `admin=false` for everyone (own-persona discipline; no ep consumer needs
+     *  cross-owner persona writes - an operator redefines via config, not the wire), where the ctl
+     *  admin tier allowed operator cross-owner redefine; (2) launch is owner-equality-only, above.
+     *  Both are least-privilege reductions, never widenings. */
+    private managerServiceDefs;
     private commitResumeActivation;
-    private handleActive;
-    /** Collapsed despawn/attach authorization (P4b). The caller already reached the privileged or
-     *  admin tier (cred-gated). On the admin tier any named target is allowed (operator). On the
-     *  privileged tier a named target is allowed if it's the caller's OWN child (`spawner ==
-     *  caller`) — and, on a user mesh, if it runs under the CALLER'S OWNER (owner-domain) or the
-     *  caller's ledger row holds `admin`, read fresh. The policy is the pure
+    /** Collapsed despawn/attach authorization (P4b). The caller already reached the command's ep
+     *  row (cred-gated: owner-mode rows via the spawn capability, any-mode rows only in admin
+     *  instruments). With admin=true (any-mode) any named target is allowed (operator). Otherwise
+     *  a named target is allowed if it's the caller's OWN child (`spawner == caller`) — and, on a
+     *  user mesh, if it runs under the CALLER'S OWNER (owner-domain) or the caller's ledger row
+     *  holds `admin`, read fresh. The policy is the pure
      *  {@link authorizeNamedControl}; this wrapper only binds the manager's state (the mode flag +
      *  the provider-backed ledger read — a build with no provider authorizes nothing extra,
      *  fail-closed via the policy's catch). Error string when denied, `undefined` when allowed. */
@@ -476,9 +702,26 @@ export declare class Manager {
     /** Agent names become `.cotal/agents/<name>.md` paths and mesh identities, so they must be bare
      *  tokens, never a path — blocks traversal / arbitrary writes from a model-supplied name. */
     private nameError;
-    /** First free name in the series `base`, `base-2`, `base-3`, … — checked against both live and
-     *  in-flight (reserved) slots. Lets a colliding spawn auto-number instead of being rejected, so
-     *  callers never have to invent a unique name. */
+    /** First free name in the series `base`, `base-2`, `base-3`, … — checked against live slots,
+     *  in-flight (reserved) slots, names held pending retirement, AND the live mesh roster. The
+     *  roster check covers occupants this manager does not manage (a foreground `cotal spawn`, a
+     *  connector session, another manager's agent): allocating their name would mint a sibling the
+     *  broker/auth then refuses to admit, surfacing as a 30s launch-uncertain black hole instead of
+     *  the auto-number the join path gives. Presence is ADVISORY (SPEC §6) — this is an availability
+     *  choice at allocation, never an authority check (the broker still enforces): a stale
+     *  still-live-looking row only costs a numbered suffix, and a missed freshly-joined occupant is
+     *  still refused downstream exactly as before. Offline rows do NOT occupy — a properly retired
+     *  name stays reusable. */
+    /** The roster's LIVE occupant names (status !== offline) — occupants this manager may NOT manage
+     *  (a foreground `cotal spawn`, a connector session, ANOTHER manager's agent). Allocating over any
+     *  of them mints a sibling the broker/auth then refuses to admit, surfacing as the 30s launch-
+     *  uncertain black hole. */
+    private liveRosterNames;
+    /** THE single name-liveness predicate both the hard-pinned collision refuse (M6, P2 item 2) and
+     *  uniqueName's numbering consult, so they can never drift: a name is taken if this manager
+     *  reserves/manages/retires it OR a roster-live occupant already holds it. Pass a pre-built
+     *  {@link liveRosterNames} set when checking many names in one allocation. */
+    private nameInUse;
     private uniqueName;
     /** Spawn a teammate by persona ref (`name` loads `.cotal/agents/<name>.md`; the peer presents
      *  under that file's own `name:`), as if a peer asked via the control plane. Used to pre-spawn the
@@ -532,7 +775,7 @@ export declare class Manager {
      *  `spawner` is the authenticated id of the peer that requested the spawn (`req.from.id`),
      *  defaulting to the manager's own id for roster/pre-spawn — recorded for the spawner
      *  ledger (own-children despawn + reap-on-parent-exit). */
-    startAgent(opts: StartAgentOpts, spawner?: string): Promise<ControlReply>;
+    startAgent(opts: StartAgentOpts, spawner?: string, hooks?: SpawnHooks): Promise<ControlReply>;
     private startAgentActive;
     /** Preflight the whole inventory before launching its first process, then adopt each exact retained
      * principal without provisioning. A later runtime launch failure is reported per-agent, but malformed
@@ -579,11 +822,237 @@ export declare class Manager {
      *  recycle floor's contribution to the ceiling (P4c). Lazy: pruned only when the gate consults it. */
     private coolingCount;
     private opStop;
+    /** The ONE named-terminal core both doors share (P2 item 1, checklist 8): the ctl named `stop`
+     *  and the v0.4 targeted `despawn` are the same terminal — authorize by the shared policy
+     *  ({@link authorizeNamed}: own-child / owner-domain on privileged, any on admin), stop, track.
+     *  The ep door runs the SAME two pieces separately so a policy denial surfaces as the §13.3
+     *  `permission-denied` (never a generic failure). */
+    private despawnCore;
+    /** The post-authorization terminal effect (both doors). `trackNonAdmin` mirrors the ctl door's
+     *  `trackStoppedHandle(a, !admin)` disposition. */
+    private despawnAuthorized;
+    /** Resolve a v0.4 TARGET triple (owner, actor, lifecycleUid — broker-validated subject/body
+     *  agreement, currency re-checked by the serve boundary's resolver) to the live managed agent it
+     *  names. Static agents key `(DEV_OWNER, nkey)`; user-mode agents store the principal dot-form
+     *  in `id`. A uid mismatch is a superseded incarnation — never resolved to its successor. */
+    private findManagedByTarget;
     /** Open a short-lived PROVISIONER connection, run the onboarding ops on it, and drain it (closure (ii),
      *  residual 2). The DM/DLV consumer-create surface — the irreducible onboarding power — lives only for
      *  this window, never as a standing grant on the long-lived supervisor. A provision-only endpoint
      *  (no presence/consume/channel-watch) connected with memory-only `provisioner` creds; it sets its own
      *  `inboxPrefix` so JS-API replies land on the `_INBOX_<id>.>` the provisioner cred subscribes. */
+    /** Run one static §13.1 lifecycle OPERATION over an ephemeral, key-pinned `lifecycle-executor`
+     *  connection (Unit B): the credential's grants name exactly ONE incarnation's head/uid/gate/
+     *  cred-family/slot keys, so the write authority exists only for this operation's window and
+     *  can move nothing else. The transport is the direct-KV binding the shared core saga drives. */
+    private withLifecycleExecutor;
+    /** Run one §13.1 ENDPOINT-SERVE credential operation (P2 item 1, 1a-serve) over an ephemeral,
+     *  key-pinned `endpoint-serve-executor` connection: the credential's grants name exactly the
+     *  manager instance's `epgate`/`epcred` keys plus its registration's two records keys, so the
+     *  gate CAS, the mint fence, and the spec/governance writes ride a one-shot scoped authority —
+     *  NEVER the manager's standing seed/supervisor connection (the panel's "no seed shortcut"). */
+    private withEndpointServeExecutor;
+    /** 1d open-mesh counterpart of {@link withEndpointServeExecutor}: an OPEN mesh has no
+     *  credential system, so there is no scoped executor to mint - the same §13.1 gate/records
+     *  writes ride a bare one-shot connection (the broker enforces nothing on an open mesh; the
+     *  ceremony still produces the real gate, epoch, and registration the serve rails run on). */
+    private withOpenServeConnection;
+    /** The served manager-level health summary (1a's one read-only command). */
+    private managerStatusData;
+    /** P2 item 1: register the manager as an ordinary v0.4 `service` endpoint and serve its typed
+     *  command surface on the ep rails - since 1d the manager's ONLY control door. On an AUTH mesh
+     *  the whole credential path is the SAME one an ordinary endpoint traverses (the enforcement
+     *  test that keeps "ordinary" honest): provision the §13.1 issuance gate, drive the
+     *  registration BARRIER's gate CAS, then release the serve credential only on the mint FENCE's
+     *  revision-pinned CAS win — all over the scoped one-shot executor ({@link
+     *  withEndpointServeExecutor}), never a seed-signed shortcut. Holding the signing seed only
+     *  AUTHORIZES the reserved single-label name (`manager`, operator name authority, DEV_OWNER).
+     *  On an OPEN mesh the same gate/registration/serve-grant ceremony runs over bare one-shot
+     *  connections and NO credential is ever minted: there is no credential system to issue from,
+     *  so the gate legitimately keeps an empty `epcred` family (the §13.1 fence is issuance-only)
+     *  and the serve connection is bare — the broker enforces nothing on an open mesh, exactly the
+     *  old open-mesh ctl trust ("open = single-trusted-host"). */
+    private registerManagerService;
+    /** P2 item 2 must-5 (b): mint the standing `goal-writer` credential and STAGE it into this
+     *  instance's §13.1 revocation family (`epcred.<e>.<iid>`), over the passed executor's `authKv`
+     *  (the scoped `endpoint-serve-executor`, which holds the epcred write grant). The GRANT profile
+     *  stays goal-writer-only (Q2 — disjoint from the serve credential); only the FAMILY membership
+     *  is shared, so the registration barrier's existing enumerate+revoke+evict catches the
+     *  goal-writer on takeover/retire with NO barrier code change. Used both at registration (the run
+     *  block's `authKv`) and at renewal (a fresh executor's), re-minting the SAME stable nkey with a
+     *  fresh bounded exp — each issuance writes a DISTINCT ledger row (per-JWT credentialId digest). */
+    private mintAndStageGoalWriter;
+    /** P2 item 2 (spawn-as-action): stand up the standing self-mediated goal-writer connection +
+     *  ActionContext. Mode-dual, mirroring {@link registerManagerService}: an AUTH mesh uses the
+     *  scoped `goal-writer` credential already minted + family-STAGED inside registration's run block
+     *  ({@link mintAndStageGoalWriter} — DISJOINT grant from the serve cred, SHARED §13.1 revocation
+     *  family); an OPEN mesh uses a bare connection (no credential system to mint from - the broker
+     *  enforces nothing). The connection presents the CURRENT credential on every (re)connect (a
+     *  renewal is adopted without reconnecting the whole endpoint); the ActionContext bonds its
+     *  KV + JS + JSM to this one connection and space (SPEC 13.4), so a composition mixup cannot splice
+     *  goal state across brokers. */
+    private startGoalWriter;
+    /** Drain the goal-writer connection (best-effort, both exit paths). */
+    private stopGoalWriter;
+    /** P2 item 6: mint the standing `session-ledger` credential and STAGE it into this instance's
+     *  §13.1 revocation family (`epcred.<e>.<iid>`), over the passed executor's `authKv` — EXACTLY the
+     *  {@link mintAndStageGoalWriter} pattern, under the same open-and-commit fence.
+     *
+     *  This credential carries the DEDICATED sessions-bucket ledger rows and no session rail at all.
+     *  It therefore takes no epoch pin: §13.6 makes it the durable revocation authority that must
+     *  outlive the serving endpoint, so scoping it to one serving epoch would defeat its purpose. The
+     *  epoch lives where it belongs, on the per-session serving credentials, which are minted per
+     *  redemption into this same family. Re-minting the SAME nkey on renewal writes a DISTINCT ledger
+     *  row (per-JWT credentialId digest). */
+    private mintAndStageSessionLedger;
+    /** P2 item 6: stand up the ONE §13.6 session plane on its own standing connection. Mode-dual,
+     *  mirroring {@link startGoalWriter}: an AUTH mesh presents the scoped `session-ledger` cred
+     *  already minted + family-staged inside registration's run block ({@link mintAndStageSessionLedger});
+     *  an OPEN mesh uses a bare connection (no credential system to mint from). The connection presents
+     *  the CURRENT credential on every (re)connect, so a half-TTL renewal is adopted without reconnecting.
+     *
+     *  The offer SIGNER is a per-incarnation in-memory keypair: the static collapsed path mints AND
+     *  redeems the offer in one call ({@link ManagerSessionPlane.establishAttach}), so the manager
+     *  self-signs and self-verifies its own §13.6 grants and the keypair never leaves the process — a
+     *  holder never verifies the signature (it presents the grant back over the rail; the broker's
+     *  per-session caller cred is the holder's real fence). The plane's ledger lives in the DEDICATED
+     *  sessions bucket (createEndpointStreams provisioned it at registration). */
+    private startSessionPlane;
+    /**
+     * The per-session SERVING credential seam (P2 item 6, SPEC 13.6): the manager mints, gate-stages,
+     * connects and revokes ONE credential per live session, replacing a standing credential that held
+     * `eps.manager.*.<epoch>.{in,out}` and so reached every live session's bytes at its epoch.
+     *
+     * Each session gets its OWN nkey identity, so the §13.1 barrier's evict-by-holderPrincipal reaches
+     * it individually, and each is staged into `epcred.manager.<instanceId>` — the SAME family the
+     * ledger and goal-writer creds join. That is how manager takeover still kills a deposed manager's
+     * sessions: the barrier enumerates the family, revokes every row, and evicts every holder, so the
+     * per-session creds die with the incarnation exactly as the standing one did, with the blast
+     * radius of a leaked credential cut from "every session at this epoch" to "one dead session".
+     *
+     * OPEN MESH: no credential system exists to mint from, so the seam mints nothing and opens a bare
+     * connection. That is not a degraded auth path — an open mesh has no broker enforcement at all —
+     * and it is still per-session: the connection and the ledger row are still one-per-session, so
+     * teardown behaves identically in both modes.
+     */
+    private sessionServingCredentials;
+    /** Tear the session plane down (best-effort, both exit paths): end every live bridge with the
+     *  honest `manager-restart` reason (this incarnation is going away; any successor takes a new epoch
+     *  and refuses these grants), then drain each session's own connection and the ledger connection. */
+    private stopSessionPlane;
+    /** P2 item 2 must-5 Q-B — the boot reconcile: a fresh incarnation (a manager restart takes a NEW
+     *  instanceId, so the in-memory acceptance map starts empty) inherits the endpoint's accepted-but-
+     *  unterminal goals from any predecessor. Enumerate the durable index over a scoped PROVISIONER
+     *  (records CONSUMER.CREATE; the goal-writer holds NO enumeration grant, exactly the ruling) and
+     *  settle each orphan so an accepted goal is NEVER dropped across a restart. Open mesh: a bare
+     *  connection (the broker enforces nothing). Runs ONCE at start, BEFORE spawn-as-action begins
+     *  accepting (the `goalReconcileDone` gate), so it never races a live goal's acceptance. Never
+     *  fatal — a reconcile failure is logged and the gate opens either way. */
+    private reconcileGoalIndex;
+    /** Settle ONE inherited goal by evidence: no goal record (a crash between the index write and the
+     *  goal-record create) leaves the pointer untouched (never settle a goal that was never accepted,
+     *  and clearing it would race a live goal mid-creation); a TERMINAL goal clears the index
+     *  (converged — the predecessor committed but died before clearing); a NON-TERMINAL goal settles
+     *  `uncertain` (the accepting incarnation is gone, so the success signal will never reach us — the
+     *  bounded readiness outcome the plan maps the window to). Within the readiness window it arms a
+     *  bounded, unref'd timer to settle at the deadline (an early uncertain would steal a still-possible
+     *  success the substrate guards against). */
+    private reconcileOneGoal;
+    /** P2 item 2: publish a goal PROGRESS event on the caller-scoped epe subtree, over the SERVE
+     *  connection (which holds the `epe.<e>.<iid>.<epoch>.>` egress grant; the goal-writer deliberately
+     *  does not). The terminal rides a final event `phase:"terminal"` (Q1 — the caller follows epe to
+     *  the terminal; the durable result fact + inspect/ps are the reconcile authority). A dropped event
+     *  is non-fatal (the terminal is authoritative in the journal). */
+    private emitGoalProgress;
+    /** The own-gate currency belt: before the goal-writer commits a terminal fact, the manager reads
+     *  its OWN issuance gate epoch and REFUSES the commit if superseded. This NARROWS the window; it
+     *  is not the fence. Layer 1 below is closed by the sibling-mint fence; layers 2 and 3 are not
+     *  closed by any planned slice and must not be described as temporary.
+     *
+     *  THE RESIDUAL, STACKED:
+     *   1. SIBLING-MINT INJECTION. A §13.1 barrier's revoke/evict loop closes only over the family
+     *      SNAPSHOT IT ENUMERATED, so a sibling mint that observes the gate and stages a ledger row
+     *      WITHOUT the observe/open/commit fence can be staged and released AFTER that enumerate and
+     *      never be revoked. This layer is closed exactly where BOTH sibling mint sites
+     *      ({@link mintAndStageGoalWriter}, {@link mintAndStageSessionLedger}) route their stage
+     *      through `commitSiblingIssuance` (the revision-pinned CAS that makes a losing mint release
+     *      nothing), and open exactly where they do not — state the mechanism, never the branch.
+     *   2. THE BARRIER WINDOW. A gate FREEZE neither kills this connection nor advances the epoch,
+     *      and this belt compares `processEpoch` alone, so it still PASSES from barrier start until
+     *      the reopen. A ledger revoke marks a row; it does not re-check a live JWT mid-publish. The
+     *      durable kill is the CLUSTER-VERIFIED EVICTION, so a deposed manager can INITIATE new
+     *      terminal publishes from barrier start until eviction is verified — not merely finish bytes
+     *      already on the wire. Successor EXISTENCE and corpse DEATH are different phases, so the
+     *      barrier's ordering licenses no conclusion about when the corpse stops being able to write.
+     *   3. OPEN MESH. No credential family exists, so the revoke/evict loop is vacuous and this belt
+     *      is COOPERATIVE only: a non-conformant process simply does not run it.
+     *  The named follow-up that would close 2 and 3 is the gate-linearized commit (routing the
+     *  terminal through the issuance gate's own CAS), deliberately deferred as substrate territory.
+     *  An earlier revision of this comment claimed the residual was "closed by item-3 slice 3.0,
+     *  never a permanent residual". That asserted a closure that does not exist. */
+    private assertGoalWriterEpochCurrent;
+    /** Serve `spawn`/`launch` as an ACTION (P2 item 2). Authz already ran in {@link serveGated}. The
+     *  accept path runs INLINE on the handler ({@link startAgent} with hooks): the goal binds + the
+     *  acceptance replies the moment the identity is minted, BEFORE any provision (pin 1); progress and
+     *  the terminal are driven OFF-handler, so the ~30s readiness wait no longer blocks the reply.
+     *  Returns the acceptance floor payload {name, owner, actor, uid, goalId, fingerprint, executor}
+     *  (the ALLOCATED identity). goalId = the request id (env.id, Q3). */
+    private serveSpawnGoal;
+    /** H2: an acceptance served from a WINNER'S durable acceptance floor (the goal-index entry it
+     *  wrote before its own ack). Refuses `unavailable` rather than inventing one — see
+     *  {@link cachedSpawnAcceptance} for why an empty identity is never an acceptable answer. */
+    private acceptanceFromIndex;
+    /** Reconstruct a cached acceptance for a same-goalId retry NOT in the live map (a prior incarnation
+     *  accepted it, or a concurrent winner whose map write this reader has not yet observed).
+     *
+     *  H2 — WHY THIS PREFERS THE INDEX OVER THE TERMINAL. It used to read only the committed terminal
+     *  and fall back to `{name:"", actor:"", uid:""}` when there was none. That is the common case,
+     *  not a corner: a client retry over ANYCAST reaches a sibling while the winner is still
+     *  provisioning, so no terminal exists yet, and the caller was handed an ACCEPTED reply naming an
+     *  empty agent it can never address. The acceptance floor in the goal index exists from the moment
+     *  of acceptance, so it answers precisely the window the terminal cannot. Where neither is
+     *  readable the honest answer is a REFUSAL: an accepted goal whose identity nobody can name is
+     *  `unavailable`, never a hollow success. */
+    private cachedSpawnAcceptance;
+    /** M4 (settle race): a despawn MID-GOAL drives the goal's cancel terminal - transition to
+     *  `cancelling`, then commit the `cancel` cause on the goal-writer connection. First-terminal-fact
+     *  wins: if the readiness outcome already committed (succeeded/failed/uncertain) the transition or
+     *  the create-only commit loses gracefully and the readiness terminal stands. Fire-and-forget from
+     *  despawn (the process teardown is authoritative for the agent; this settles the GOAL honestly).
+     *  Cancel rides the despawn's own authorizeNamed reach (pin 5) - there is no cancel-by-goalId. */
+    private cancelAgentGoal;
+    /** The static F1 terminal for one departed incarnation (Unit B): delegates the gate/head CAS
+     *  sequence to the shared core saga over the executor transport; the footprint teardown (creds
+     *  file + broker durables/ACL) runs INSIDE the barrier as its cleanup step. On completion the
+     *  wire principal joins {@link retiredPrincipals} (the F5 refusal index) and the name hold
+     *  clears (ABA-guarded by uid). A PRE-UNIT-B lifecycle (no slot row — spawned before the
+     *  durable registry existed) has nothing to terminalize: its footprint teardown runs directly
+     *  and the hold clears, the honest upgrade path. */
+    private driveStaticRetirement;
+    /** F5(b) push renewal of ONE live managed-static credential (Unit B): re-mint the SAME nkey
+     *  identity with the SAME scope (recorded on the managed row at spawn) and a fresh bounded
+     *  exp, ledger the new credentialId (slot record first, then the row, then the file — a
+     *  credential is never materialized before its ledger row exists), and re-sign the SAME
+     *  lifecycle-keyed file the agent endpoint's source seam re-reads. Never advances the epoch,
+     *  never routes through any barrier (renewal is the THIRD transition). */
+    private renewManagedStaticCred;
+    /** The Unit B reconciliation (F3 "no active orphan"): ensure the authority stores, then sweep
+     *  every durable slot row and act by the TOTAL resume table — `provisioning`/`terminalizing`
+     *  re-drive the exact-op terminal; an `active` row survives ONLY when a LIVE managed agent this
+     *  process owns backs it at the same uid (`adopted`), else its process is gone and it
+     *  terminalizes; `retired` rows seed the F5 refusal index. Two call sites: the BOOT sweep
+     *  (`postAdoption=false`, under the lease before control serving) DEFERS active-non-adopted
+     *  slots while a resume is still pending (adoption runs after it); the POST-ADOPTION sweep
+     *  (`postAdoption=true`, inside finalizeResume while `resumeRequired` still fences ordinary
+     *  spawns) terminalizes any active slot the resume did not claim. */
+    private reconcileStaticLifecycles;
+    /** The F5(a) membership gate (Unit B, the F5-bind design): decide a control caller by its
+     *  AUTHENTICATED wire principal. A LIVE managed slot passes (unless terminalizing); a RETIRING
+     *  hold or a RETIRED static incarnation refuses even with a tier-valid JWT (the
+     *  copied-credential vector — its subject can never collide with a successor's, so this match
+     *  is non-forgeable); any OTHER principal is not a managed lifecycle (an operator instrument:
+     *  the credential tier governs, exactly as before). Never name alone, never a payload field. */
+    private lifecycleMembershipRefusal;
     private withProvisioner;
     /** Purge the space's retained message backlog (chat, optionally DMs). Privileged — the manager mints a
      *  short-lived "purger" cred (same destructive grant as `cotal history clear`, isolated off the
@@ -600,7 +1069,20 @@ export declare class Manager {
      *  preserves everything else — and is allowed on the privileged tier only if `file.owner == caller`,
      *  else admin is required. Fail-closed: an ownerless file (legacy / operator-written) is admin-only. */
     private opDefinePersona;
-    private opAttach;
+    /** The post-authorization attach effect (P2 item 6): mint the holder-bound §13.6 offer, redeem it
+     *  through the ONE session plane (one-use CAS + presenter-equality), and stand up the PTY bridge —
+     *  atomically. The reply is the SIGNED grant (no ws:// URL, non-bearer, never logged); the caller
+     *  redeems it over the mesh with a per-session rails-only cred it mints itself. Only streamable
+     *  backends (pty/host) attach; an external runtime's attach() throws with per-runtime guidance. */
+    private attachAuthorized;
+    /** P2 item 6: the console's mesh §13.6 session establisher (backing `POST /session/<name>` on the
+     *  loopback face). Drives THE ONE plane — same establishAttach as the ep `attach` command — with
+     *  the loopback OPERATOR as holder (same-host trust boundary), then hands the browser everything it
+     *  needs to open the caller rail over the broker ws listener: the holder-bound grant, a per-session
+     *  RAILS-ONLY caller cred (static mints from the seed, TTL-bound to the session; an open mesh has no
+     *  credential system so the browser connects bare), and the ws URL. NO 127.0.0.1 terminal transport
+     *  — the terminal rides the mesh session. Injected only when a wsPort exists (see the constructor). */
+    private establishConsoleSession;
     /** Managed agents cross-referenced with live presence (the manager sees the roster). */
     /** `ownerFilter`: restrict to agents whose spawn-time stored `userOwner` equals it (the ps/status
      *  owner-domain bound); undefined = unbounded. {@link NO_OWNER_MATCHES} matches nothing. */