@cotal-ai/manager 0.65.0 → 0.67.0

package/dist/manager.js

@@ -2,10 +2,10 @@ import { execFile } from "node:child_process";
 import { createHash, randomUUID, randomBytes } from "node:crypto";
 import { hostname } from "node:os";
 import { credsAuthenticator } from "@nats-io/transport-node";
-import { existsSync, lstatSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
 import { isAbsolute, join, dirname, resolve } from "node:path";
 import { CotalEndpoint, MANAGED_HANDOFF_KIND, accountFromCreds, credsClaims, DEFAULT_SERVER, DEV_OWNER, MANAGER_LEASE_RENEW_MS, STANDING_RENEWABLE_TTL_SEC, assertLifecycleToken, discardLaunchArtifacts, divergentSecretStoreNotice, parseDaemonStoreAnswer, parseSecretStoreIdentity, sameSecretStoreIdentity, agentFilePath, clearSpaceHistory, dialerFor, connectorServers, spawnEnvAllow, deprovisionAgent, DeprovisionError, isConcreteChannel, deprovisionTargetPrincipal, firstFreeName, spawnNameError, idFromCreds, inspectCredHealth, credsRenewalDelayMs, composeWirePersona, loadAgentFile, listPersonaCatalog, personaCatalogDescription, personaCatalogReadable, loadCotalConfig, modelPolicyRefusal, mintCreds, mintGeneration, mintAcceptedToken, openIssuedStore, acceptedBucket, issuedBucket, mintLifecycleUid, managedRetirementOpId, mkSecretDir, newIdentity, actionContext, parsePrincipalKey, parseShareSelection, principalKey, probeConnect, provisionAgent, provisionAgentDurables, registry, resolveAuthProvider, saveAgentFile, subjectMatches, AUTH_ENDPOINT, EP_CMD_RETIRE_LIFECYCLE, controlServiceSubject, eventChannelPrincipal, resolveService, invokeCommand, } from "@cotal-ai/core";
-import { agentAuthState, agentCredsDir, agentLifecycleSecretFilePaths, agentSecretFilePaths, agentSecretKeyForFile, authDir, connectorInstallHint, DEFAULT_CONNECTOR, defaultAgentType, DELIVERY_CREDS_KIND, extensionConnectors, findCotalRoot, getSpaceAuth, hasUserAuthState, loadExtensionsManifest, loadManagerInstanceIdentity, loadMeshes, localTrustOfSpace, manifestExtensionNames, materializeFromManifest, materializeSecretToFile, MEMBERSHIP_RW_CREDS_KIND, mergeLaunchOptions, remintDaemonCreds, resolveOnPath, createManagerInstanceIdentity, spaceMaterialKey, SYSTEM_CREDS_FILES, userAuthStateDir, workspaceSecretStore, writeRenewalRecord } from "@cotal-ai/workspace";
+import { agentAuthState, agentCredsDir, agentLifecycleSecretFilePaths, agentSecretFilePaths, agentSecretKeyForFile, authDir, claimManagerSiblingIdentities, connectorInstallHint, DEFAULT_CONNECTOR, defaultAgentType, DELIVERY_CREDS_KIND, extensionConnectors, findCotalRoot, getSpaceAuth, hasUserAuthState, loadExtensionsManifest, loadManagerInstanceIdentity, loadMeshes, localTrustOfSpace, manifestExtensionNames, materializeFromManifest, materializeSecretToFile, MEMBERSHIP_RW_CREDS_KIND, mergeLaunchOptions, remintDaemonCreds, resolveOnPath, createManagerInstanceIdentity, spaceMaterialKey, SYSTEM_CREDS_FILES, userAuthStateDir, workspaceSecretStore, writeRenewalRecord } from "@cotal-ai/workspace";
 import { createRuntime, isCustodialRuntime, requireRuntimeAdopt, requireRuntimeReap, RuntimeReapUnproven, } from "./runtime/index.js";
 import { AttachEndpoint } from "./attach-endpoint.js";
 import { DELIVERY_ADMIN_BOOT_WAIT_MS, isUnansweredDeliveryAdmin, makeManagerEndpointEvictionEvidence, makeManagerEndpointHolderEvictor, untilDeliveryAdminAnswers } from "./endpoint-evict.js";
@@ -17,11 +17,12 @@ import { controlShutdown } from "./control-shutdown.js";
 import { RunHosting } from "./run-hosting.js";
 import { controlSession } from "./control-session.js";
 import { MAX_AGENTS, parseResumeCommitArgs, parseResumeControlArgs, parseResumeFinalizeArgs } from "./resume.js";
+import { TranscriptReceiver } from "./transcript-receive.js";
 // Unit B (the static §13.1 lifecycle executor): the shared grammar/stores from core plus the
 // manager-side adapter (transport + slot orchestration + the F1 terminal) — see static-lifecycle.ts.
 import { jetstream, jetstreamManager } from "@nats-io/jetstream";
 import { Kvm } from "@nats-io/kv";
-import { recordsBucket, epAuthBucket, ensureAuthorityStores, ensureContractStore, createEndpointStreams, contractStoreContext, publishContractArtifact, contractArtifactCanonicalBytes, standaloneConnectOpts, STATIC_SLOT_PREFIX, rawDigest, STANDING_RENEWABLE_TTL_SEC as MANAGED_STATIC_TTL_SEC, newArtifactSigner, RotatingSigner, generationAnchor, sessionsBucket, SESSION_GRANT_MAX_TTL_MS, } from "@cotal-ai/core";
+import { recordsBucket, epAuthBucket, ensureAuthorityStores, ensureContractStore, createEndpointStreams, contractStoreContext, publishContractArtifact, contractArtifactCanonicalBytes, standaloneConnectOpts, STATIC_SLOT_PREFIX, rawDigest, STANDING_RENEWABLE_TTL_SEC as MANAGED_STATIC_TTL_SEC, newArtifactSigner, RotatingSigner, generationAnchor, sessionsBucket, SESSION_GRANT_MAX_TTL_MS, REMOTE_MANAGER_IDENTITY_NAMES, } from "@cotal-ai/core";
 // P2 item 6: the manager's ONE §13.6 session plane — offer mint + one-use redeem + PTY-bridge
 // standup for `attach`, over a dedicated standing session-LEDGER connection (the byte rails ride
 // per-session credentials on their own short-lived connections).
@@ -29,7 +30,7 @@ import { ManagerSessionPlane, openSessionLedgerKv } from "./session/index.js";
 // P2 item 1 (1a-serve): 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, registerServiceInstance, deregisterServiceInstance, authorizeServeGrant, writeServiceStatus, SERVICE_READY, serveEndpoint, bindGoal, createGoal, transitionGoal, commitGoalResult, settleGoalUncertain, readGoalResult, readGoalStatus, readGoalSpec, recordGoalIndex, readGoalIndex, clearGoalIndex, listGoalIndex, mintCheckpoint, resumeCheckpoint, readCheckpointSettle, readCheckpointSpec, expireCheckpoint, GOAL_TERMINAL_STATES, goalRefOf, goalProgressTopic, 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, settleGoalUncertain, readGoalResult, readGoalStatus, readGoalSpec, recordGoalIndex, readGoalIndex, clearGoalIndex, listGoalIndex, mintCheckpoint, resumeCheckpoint, readCheckpointSettle, readCheckpointSpec, expireCheckpoint, GOAL_TERMINAL_STATES, goalRefOf, goalProgressTopic, epeSubject, submissionFingerprint, EpEnvelopeError, lifecycleBlocked, lifecycleBlockedFrom, renderLifecycleBlocked, } from "@cotal-ai/core";
 import { MANAGER_ENDPOINT, managerClusterArtifacts, managerCommandDefs, managerContractArtifactValues } from "./manager-service-contract.js";
 import { staticLifecycleTransport, activateStaticLifecycle, runStaticTerminal, readStaticSlot, casStaticSlot, recordSlotCredential, appendStaticCredentialRow, planStaticSlotResume, observeStaticSlot, listStaticSlotObservations, renderStaticSlotObservation, StaticSlotReadError, STATIC_SLOT_READ_FAILED_DETAIL, } from "./static-lifecycle.js";
 /** Minimum slot lifetime for rate-flooring (P4c). A slot freed (by despawn OR natural exit/reap)
@@ -172,6 +173,8 @@ const FREE_SLOT_CAUSE_TEXT = {
     "supervise-recovery-failed": "this manager retired it after a supervised restart failed",
     "session-bind-failed": "this manager stopped it: its host session could not be bound at launch",
     "resume-session-rebind-failed": "this manager stopped it: its host session could not be rebound on resume",
+    "carried-fork-refused": "this manager stopped it: it recorded no fork of the carried transcript",
+    "resume-custody-unrecorded": "this manager stopped it: its custody reference could not be recorded on resume",
 };
 /** The stop family's sentences — the same job {@link FREE_SLOT_CAUSE_TEXT} does for the string
  *  causes, beside it so both stay the single place a cause becomes a sentence. A requested stop's
@@ -467,6 +470,8 @@ export class Manager {
     /** The complete boot task. stop() joins it after fencing static reconciliation, so a registration
      * already past an earlier shutdown check cannot finish after stop() returns. */
     startTask;
+    /** This instance's side of a carried resume transcript (#1499); absent where it has no transfer reader. */
+    transcripts;
     /** The one stop this manager runs, with the agent policy it was asked for. A stop takes seats out
      *  of `agents` before they have exited, so a second teardown would find none and report success
      *  while the first still waits on a live seat. */
@@ -877,11 +882,11 @@ export class Manager {
         catch (e) {
             // Our OWN instance id already holds a live key ⇒ refuse. Anything else (e.g. a KV/JS error) is a
             // real failure to surface, not a silent "held" — keep the cause so it isn't misread as a conflict.
-            const held = await this.ep.readManagerLease().catch(() => undefined);
+            const held = (await this.ep.readOwnManagerLease(this.managerInstanceId).catch(() => undefined))?.info;
             await this.ep.stop();
             await this.attach.stop();
             throw new Error(held
-                ? `manager instance ${this.managerInstanceId} already serves space "${this.space}" from this workspace root (${held.runtime}, pid ${held.pid}, root ${held.root}) - stop it first before restarting the same instance`
+                ? `manager instance ${this.managerInstanceId} already serves space "${this.space}" from ${held.root === this.leaseInfo.root ? "this" : "another"} workspace root (${held.runtime}, pid ${held.pid}, root ${held.root}) - stop it first before restarting the same instance`
                 : `could not acquire the manager lease for space "${this.space}": ${e.message}`);
         }
         this.leaseTimer = setInterval(() => { void this.renewLease(); }, MANAGER_LEASE_RENEW_MS);
@@ -1042,6 +1047,18 @@ export class Manager {
             });
             await this.runHosting.reconcile();
         }
+        // A carried resume (#1499) needs this instance's transfer reader: minted from the space's signing
+        // seed, issued by the host to a remote manager, or none on an open mesh.
+        if (!this.remoteAuthority || this.remoteAuthority.mintTransferReader) {
+            this.transcripts = new TranscriptReceiver({
+                space: this.space,
+                instanceId: this.managerInstanceId,
+                workspaceRoot: this.workspaceRoot,
+                withReader: (fn) => this.withTransferReader(fn),
+                log: (line) => console.error(line),
+            });
+            await this.transcripts.start();
+        }
         // Plane-3 (durable backstop) is NOT the manager's job — the manager only manages agent lifecycle.
         // The server-side delivery daemon hosts the fan-out writer + trusted reader, owns the durable
         // membership registry, and serves the runtime durable join/leave/list ops (on `ctl.delivery`). The
@@ -1483,10 +1500,9 @@ export class Manager {
         let candidate;
         try {
             candidate = await remote.renewStandingBundle(processEpoch);
-            const names = ["supervisor", "executor", "serve", "goalWriter", "sessionLedger"];
-            if (Object.keys(candidate).sort().join(",") !== [...names].sort().join(","))
+            if (Object.keys(candidate).sort().join(",") !== [...REMOTE_MANAGER_IDENTITY_NAMES].sort().join(","))
                 throw new Error("host returned an incomplete or widened standing credential family");
-            for (const name of names) {
+            for (const name of REMOTE_MANAGER_IDENTITY_NAMES) {
                 if (typeof candidate[name] !== "string" || inspectCredHealth(candidate[name]).state === "unreadable")
                     throw new Error(`host returned an unreadable ${name} credential`);
                 if (!remote.accountPublicKey || accountFromCreds(candidate[name]) !== remote.accountPublicKey)
@@ -1676,10 +1692,14 @@ export class Manager {
                 });
         }
         // A later manager does not resume a delegated seat, and its close runs only inside its
-        // retirement, so a cut that holds one is refused before any child stops.
-        for (const a of this.agents.values())
+        // retirement, so a cut that holds one is refused before any child stops. A carried resume seat's
+        // private home is removed when its slot is freed, so a later manager would find nothing to fork.
+        for (const a of this.agents.values()) {
             if (a.handedOff)
                 failures.push({ name: a.name, id: a.id, error: "a delegated seat is not resumed by a later manager; stop it before preserving" });
+            if (a.seatHome)
+                failures.push({ name: a.name, id: a.id, error: "a carried resume seat's private home is not kept for a later manager; stop it before preserving" });
+        }
         const unverifiedStops = this.unverifiedStops.filter((stopped) => {
             try {
                 if (!stopped.authoritative && stopped.handle.status() === "exited")
@@ -2049,6 +2069,7 @@ export class Manager {
     }
     async stopOnce(withAgents) {
         this.leaseStopping = true;
+        this.transcripts?.stop();
         this.staticReconcileStopping = true;
         const starting = this.startTask;
         for (const item of this.staticReconcileItems.values()) {
@@ -2554,8 +2575,13 @@ export class Manager {
     async epAdminReach(caller) {
         if (!this.userMode)
             return true;
-        if (this.remoteAuthority)
-            return this.remoteAuthority.authorizeAdmin({ owner: caller.owner, actor: caller.actor, lifecycleUid: caller.uid });
+        if (this.remoteAuthority) {
+            // A hosted run's own caller is derived from its id and holds no ledger row: it acts for the
+            // caller its run was admitted for, so that caller's current grant decides, and a revoked
+            // login demotes the run's next spawn.
+            const asked = this.runHosting?.admittedCaller(caller) ?? caller;
+            return this.remoteAuthority.authorizeAdmin({ owner: asked.owner, actor: asked.actor, lifecycleUid: asked.uid });
+        }
         try {
             const scope = await resolveAuthProvider().actorScope({
                 dir: userAuthStateDir(this.workspaceRoot, this.space),
@@ -2878,6 +2904,11 @@ export class Manager {
             preparePreservation: (ctx) => adminGated(ctx, async () => unwrap(await this.opPreservationCtl("preparePreservation", args(ctx)))),
             commitPreservation: (ctx) => adminGated(ctx, async () => unwrap(await this.opPreservationCtl("commitPreservation", args(ctx)))),
             abortPreservation: (ctx) => adminGated(ctx, async () => unwrap(await this.opPreservationCtl("abortPreservation", args(ctx)))),
+            transcriptReceive: (ctx) => this.serveGated(ctx, () => adminGated(ctx, () => {
+                if (!this.transcripts)
+                    throw new EpEnvelopeError("failed-precondition", "transcript-receive: this manager does not receive carried transcripts (its remote authority issues no transfer reader)");
+                return this.transcripts.receive(args(ctx));
+            })),
         });
     }
     async commitResumeActivation(attemptId) {
@@ -3459,6 +3490,8 @@ export class Manager {
         this.recordContinuityAtStop(a, "stop");
         if (a.restart?.sessionStatePath)
             rmSync(a.restart.sessionStatePath, { force: true });
+        if (a.seatHome)
+            rmSync(a.seatHome, { recursive: true, force: true });
         // P2 item 6 (pin 4): end any live §13.6 attach session bound to THIS incarnation with the honest
         // `target-despawn` reason. Fires once per agent on every free path (despawn / self-stop / reap /
         // exit) via the `agents` guard above; a no-op when no plane or no live session for the target.
@@ -3929,8 +3962,15 @@ export class Manager {
      *  record cannot be read or does not name this seat's source, it is absent: `ps` then shows the
      *  source id alone rather than failing the listing for every other seat. */
     forkProvenance(a) {
-        if (a.launch.resumed || !a.launch.resumeRecordPath || !a.launch.forkSource)
+        // A carried seat's provenance is set only by refuseCarriedFork, once its record names the claim.
+        if (a.launch.resumed || a.launch.carried)
             return a.launch.resumed;
+        a.launch.resumed = this.readForkRecord(a);
+        return a.launch.resumed;
+    }
+    readForkRecord(a) {
+        if (!a.launch.resumeRecordPath || !a.launch.forkSource)
+            return undefined;
         let record;
         try {
             record = JSON.parse(readFileSync(a.launch.resumeRecordPath, "utf8"));
@@ -3942,8 +3982,43 @@ export class Manager {
         if (r.source !== a.launch.forkSource || typeof r.transcriptSha256 !== "string" || !/^[a-f0-9]{64}$/.test(r.transcriptSha256) ||
             !(r.title === undefined || r.title === null || (typeof r.title === "string" && r.title.length <= 1024)))
             return undefined;
-        a.launch.resumed = { source: r.source, ...(typeof r.title === "string" && r.title ? { title: r.title } : {}), transcriptSha256: r.transcriptSha256 };
-        return a.launch.resumed;
+        return { source: r.source, ...(typeof r.title === "string" && r.title ? { title: r.title } : {}), transcriptSha256: r.transcriptSha256 };
+    }
+    /** Design section 9: a carried seat must fork the bytes the operator carried. Wait for its fork
+     *  record and hold it to the claim; on a match it becomes the seat's provenance, otherwise the
+     *  refusal is returned. A seat that writes no record cannot be shown to have forked the claim. */
+    async refuseCarriedFork(a, timeoutMs) {
+        const claim = a.launch.carried;
+        const deadline = Date.now() + timeoutMs;
+        let record;
+        while (!(record = this.readForkRecord(a))) {
+            if (a.terminalizing || a.handle.status() === "exited")
+                return `${a.name} stopped before it wrote a fork record`;
+            if (Date.now() >= deadline)
+                return `${a.name} wrote no fork record within ${timeoutMs} ms, so it cannot be shown to have forked the carried transcript`;
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        if (record.transcriptSha256 !== claim.transcriptSha256)
+            return `${a.name} forked a transcript with sha256:${record.transcriptSha256}, not the carried sha256:${claim.transcriptSha256}`;
+        a.launch.resumed = { ...record, host: claim.host, transferredAt: claim.transferredAt };
+        return undefined;
+    }
+    /** A carried seat whose launch was uncertain is held to the claim once it joins, as a started one
+     *  is; the wait ends when the seat stops or exits, which its exit watcher reaps. */
+    async refuseLateCarriedFork(a, timeoutMs) {
+        for (;;) {
+            const late = await this.awaitReadiness(a, timeoutMs, { reapOnExit: false });
+            if (late.ok)
+                break;
+            if (!late.uncertain || a.terminalizing)
+                return;
+        }
+        const refused = await this.refuseCarriedFork(a, timeoutMs);
+        if (refused === undefined || a.terminalizing || a.handle.status() === "exited")
+            return;
+        console.error(`! ${refused}; stopping it`);
+        this.stopHandle(a, false);
+        this.freeSlot(a, true, "carried-fork-refused");
     }
     readManagedSession(a) {
         return this.readManagedSessionState(a).sessionId;
@@ -4096,10 +4171,10 @@ export class Manager {
                 }
                 a.handle = handle;
                 a.control = spec.control;
+                await this.recordSlotRuntime(a);
                 replacement = undefined;
                 restart.opts = opts;
                 restart.recovering = false;
-                await this.recordSlotRuntime(a);
                 if (continueSession !== undefined)
                     console.error(`! ${a.name}: recovered Pi session ${continueSession} after crash (${restart.crashes.length}/${limit})`);
                 else
@@ -4316,6 +4391,8 @@ export class Manager {
             variant: args.variant ? String(args.variant) : undefined,
             launchOptions: args.launchOptions,
             resume: args.resume ? String(args.resume) : undefined,
+            resumeClaim: args.resumeClaim !== undefined ? String(args.resumeClaim) : undefined,
+            resumeAgent: args.resumeAgent !== undefined ? String(args.resumeAgent) : undefined,
             events,
             eventsNotice,
             cwd: args.cwd ? String(args.cwd) : undefined,
@@ -4711,6 +4788,25 @@ export class Manager {
         // reject-before-side-effects window as the harness preflight above; buildLaunch stays the backstop.
         if (opts.resume && !connector.supportsResume)
             return { ok: false, error: `${agent} connector does not support resuming an existing session (resume)` };
+        // A carried resume (#1499) is checked here too, before anything is minted. The claim is only
+        // looked at: the connector may still refuse the launch, and a refused launch leaves it unspent.
+        let carried;
+        if (opts.resumeClaim !== undefined) {
+            if (opts.resume === undefined)
+                return { ok: false, error: "resumeClaim: names carried bytes of a resume; the launch carries no resume" };
+            if (!connector.resumeTranscript)
+                return { ok: false, error: `${agent} connector does not take a carried transcript (resumeClaim)` };
+            if (opts.resumeAgent !== agent)
+                return { ok: false, error: `resumeClaim: the session was carried for agent "${opts.resumeAgent ?? "<none>"}", and this launch resolves agent "${agent}"` };
+            if (!this.transcripts)
+                return { ok: false, error: "resumeClaim: this manager does not receive carried transcripts" };
+            try {
+                carried = this.transcripts.peek(opts.resumeClaim, opts.resume);
+            }
+            catch (e) {
+                return { ok: false, error: e.message };
+            }
+        }
         // A restart policy this host cannot honour is refused at accept, never accepted and ignored.
         // External runtimes (tmux/cmux/orca/herdr) attach to a process they do not own and stream no
         // exit, so a name cannot be respawned in place. User-mode seats have no static slot that
@@ -4880,7 +4976,7 @@ export class Manager {
         const held = this.retiring.get(identityName);
         if (held !== undefined) {
             void this.deprovision({ id: held.agentId, name: identityName, lifecycleUid: held.lifecycleUid, userOwner: held.userOwner, delegated: held.delegated, secretPaths: held.secretPaths, delegatedHandle: held.delegatedHandle, launch: held.launch }).catch(() => { });
-            const err = lifecycleBlocked("failed-precondition", `the name "${identityName}" is reserved pending retirement: its previous agent's despawn started that lifecycle's teardown (footprint + standing-authority revoke + auth-side retirement), and the name frees only when all of it completes${held.lastError !== undefined ? ` (last attempt: ${held.lastError})` : ""}. NEXT: wait a moment and retry this spawn (retrying re-drives the whole teardown), or pick another name.`, { blockedOp: "retirement", headState: "retiring", opId: held.opId, remedy: "retry" });
+            const err = lifecycleBlocked("failed-precondition", `the name "${identityName}" is reserved pending retirement: its previous agent's despawn started that lifecycle's teardown (footprint + standing-authority revoke + auth-side retirement), and the name frees only when all of it completes${held.lastError !== undefined ? ` (last attempt: ${held.lastError})` : ""}. NEXT: wait a moment and retry this spawn (retrying re-drives the whole teardown), or pick another name.`, { blockedOp: "retirement", opId: held.opId, remedy: "retry" });
             return { ok: false, error: renderLifecycleBlocked(err.message, err), details: err.details };
         }
         if (variant && !connector.supportsModelVariant)
@@ -4981,6 +5077,8 @@ export class Manager {
         // and retires over a live process. The slot row holds the same reference; this is the copy the
         // in-process rollback can actually read.
         let provisioned;
+        // A carried resume's seat-private home, removed by the finally unless a live seat took it.
+        let seatHome;
         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.
@@ -5223,7 +5321,14 @@ export class Manager {
                 handle = this.runtime.spawnDelegated({ agent, persona: readFileSync(configPath, "utf8"), role, model, variant, prompt, launchOptions: launchOptions, events }, handoff);
             }
             else {
+                if (carried) {
+                    seatHome = join(this.workspaceRoot, ".cotal", "seat-homes", lifecycleUid);
+                    mkdirSync(seatHome, { recursive: true, mode: 0o700 });
+                    launchOpts.carried = { home: seatHome, transcript: carried.path, cwd };
+                }
                 spec = connector.buildLaunch(launchOpts);
+                if (carried)
+                    this.transcripts.consume(opts.resumeClaim, opts.resume);
                 spec.env = { ...spec.env, COTAL_MANAGER_INSTANCE: this.managerInstanceId };
                 handle = await this.spawnCustodied(name, spec, cwd, custody);
             }
@@ -5232,6 +5337,7 @@ export class Manager {
                 name,
                 role,
                 agent,
+                ...(seatHome ? { seatHome } : {}),
                 id: userLaunch ? principalKey(userLaunch.owner, name).key : identity.id,
                 lifecycleUid,
                 // The lifecycle-keyed family this spawn just materialized (absent on an open mesh) — the
@@ -5272,6 +5378,7 @@ export class Manager {
                     shareTools: opts.shareTools,
                     forkSource: opts.resume,
                     ...(opts.resume !== undefined && spec?.resumeRecordPath ? { resumeRecordPath: spec.resumeRecordPath } : {}),
+                    ...(carried ? { carried: { transcriptSha256: carried.sha256, host: carried.sourceHost, transferredAt: carried.stagedAt } } : {}),
                     // Opaque values may contain secrets. Preserve only their keys and require the referenced
                     // persona/manifest to resolve the values again; imperative overrides have no safe payload.
                     unresolvedLaunchOptionKeys: opts.launchOptions && Object.keys(opts.launchOptions).length
@@ -5311,6 +5418,7 @@ export class Manager {
             // The live slot now owns teardown — freeSlot deprovisions this identity on exit — so the
             // orphan-rollback in `finally` no longer applies to it.
             provisioned = undefined;
+            seatHome = undefined;
             // #159 B1: reply on a REAL outcome, not a timer. Wait for the agent to actually join the mesh
             // (presence) → started, the child to exit → failed (with its last output; already reaped), or
             // neither in time → uncertain. `✓ started` therefore means "it joined", never just "a process
@@ -5336,9 +5444,24 @@ export class Manager {
             // death — including one that follows an `uncertain` verdict, which deliberately does NOT deprovision).
             if (!readiness.ok) {
                 this.watchExit(managed);
+                if (managed.launch.carried)
+                    void this.refuseLateCarriedFork(managed, readinessTimeoutMs);
                 await hooks?.onOutcome?.({ kind: "uncertain", data: { reason: readiness.detail } });
                 return { ok: false, error: readiness.detail };
             }
+            if (managed.launch.carried) {
+                const refused = await this.refuseCarriedFork(managed, readinessTimeoutMs);
+                if (refused !== undefined && managed.terminalizing) {
+                    hooks?.onTerminalDeferred?.();
+                    return { ok: false, error: refused };
+                }
+                if (refused !== undefined) {
+                    this.stopHandle(managed, false);
+                    this.freeSlot(managed, true, "carried-fork-refused");
+                    await hooks?.onOutcome?.({ kind: "failed", data: { error: refused } });
+                    return { ok: false, error: refused };
+                }
+            }
             if (managed.restart) {
                 if (connector.supportsSessionContinuation) {
                     try {
@@ -5393,6 +5516,8 @@ export class Manager {
         finally {
             this.reserved.delete(name);
             this.reservedLive.delete(name);
+            if (seatHome)
+                rmSync(seatHome, { recursive: true, force: true });
             // Minted but never handed to a live slot (buildLaunch / runtime.spawn threw after mint) → tear the
             // orphan down (detached, fail-loud) so a failed spawn leaves no creds/durables behind (#159 B).
             if (provisioned) {
@@ -5981,7 +6106,24 @@ export class Manager {
             this.reservedLive.add(entry.name);
             if (this.resumeAttemptId)
                 this.resumedAgentNames.add(entry.name);
-            await this.recordSlotRuntime(managed);
+            try {
+                await this.recordSlotRuntime(managed);
+            }
+            catch (error) {
+                const detail = `${managed.name} resumed, but ${error.message}`;
+                this.stopHandle(managed, false);
+                try {
+                    await this.awaitHandleExit(managed.handle);
+                }
+                catch (exit) {
+                    // A resumed seat keeps its retained credentials, so freeing it runs no deprovision and
+                    // nothing would reap it: it stays managed until it exits or the manager stops it.
+                    this.watchExit(managed);
+                    return { ok: false, error: `${detail}; it stays managed because its stop is unproven: ${exit.message}` };
+                }
+                this.freeSlot(managed, true, "resume-custody-unrecorded", true);
+                return { ok: false, error: detail };
+            }
             const readiness = await this.awaitReadiness(managed, readinessTimeoutMs);
             if (!readiness.ok && !readiness.uncertain)
                 return { ok: false, error: readiness.detail };
@@ -6752,13 +6894,15 @@ export class Manager {
         // with a fresh bounded exp; a restart re-provisions the same (idempotent) gate + re-registers.
         const serveIdentity = this.managerServeIdentity;
         const servePrincipal = principalKey(DEV_OWNER, serveIdentity.id).key;
+        // An open mesh mints no credentials, so it has no family for a fresh pair to grow.
+        const siblings = auth ? claimManagerSiblingIdentities(this.workspaceRoot, this.space) : { goalWriter: newIdentity(), sessionLedger: newIdentity() };
         // must-5 (b): the STABLE goal-writer identity — a SIBLING credential in the same §13.1 family
-        // (not the gate's bound serving principal), minted here so the run block can family-stage it.
-        this.goalWriterIdentity = newIdentity();
+        // (not the gate's bound serving principal), so the run block can family-stage it.
+        this.goalWriterIdentity = siblings.goalWriter;
         // P2 item 6: the STABLE session-LEDGER identity — another SIBLING in the SAME §13.1 family, so
         // the takeover barrier revokes a deposed manager's ledger cred alongside its goal-writer. The
         // per-session serving creds join the same family, each with its own fresh identity.
-        this.sessionLedgerIdentity = newIdentity();
+        this.sessionLedgerIdentity = siblings.sessionLedger;
         // One registration operation for this boot. Fresh executors may replace a dead connection, but
         // they must resume THIS freeze rather than minting a new op that discards Phase-2 progress.
         const registrationOpId = mintLifecycleUid();
@@ -6809,7 +6953,7 @@ export class Manager {
                 ...(auth ? { evict: makeManagerEndpointHolderEvictor({ space: this.space, servers: this.servers ?? DEFAULT_SERVER, auth, log: (line) => console.error(line), unreachableWaitMs: DELIVERY_ADMIN_BOOT_WAIT_MS }) } : {}),
             });
             const spec = { endpoint: MANAGER_ENDPOINT, owner: DEV_OWNER, clusterDigests: [artifacts.closureDigest], protocol: { v: 1 } };
-            const { registrationRevision, processEpoch } = await registerServiceInstance(recordsKv, {
+            const { grant } = await registerServingInstance(recordsKv, {
                 space: this.space, spec, instanceId: iid, registrant: { owner: DEV_OWNER }, authority, barrier, readClusterArtifact,
                 // #1393: when a FOREIGN instance holds the endpoint governance slot, let core tell an
                 // in-flight registration from one abandoned by a predecessor that died between its
@@ -6817,43 +6961,9 @@ export class Manager {
                 // grant (no new grant, no new writer); core refuses on anything but a gate provably
                 // reopened past the slot's stamp.
                 observeHolderGeneration: (holderInstanceId) => readEndpointGateGeneration(authKv, { endpoint: MANAGER_ENDPOINT, instanceId: holderInstanceId }),
+                status: { connectors: this.connectorStatuses.map((row) => ({ ...row, binaries: { ...row.binaries } })) },
             });
-            // processEpoch is the one this registration's reopen committed (checklist 4: never derived
-            // from the uid string). A gate read here could already show a successor's epoch; the fences
-            // below refuse that successor instead of serving at it. The fence is also the mint's §13.1
-            // release CAS.
             const fence = serveIssuanceGateKv(authKv, this.space, { endpoint: MANAGER_ENDPOINT, instanceId: iid });
-            const grant = await authorizeServeGrant(recordsKv, {
-                space: this.space, endpoint: MANAGER_ENDPOINT, instanceId: iid, epoch: processEpoch,
-                holder: { owner: DEV_OWNER }, authority, readClusterArtifact,
-                readProcessEpoch: async () => {
-                    const g = await fence.observe();
-                    if (g === null)
-                        throw new Error(`no issuance gate for ${MANAGER_ENDPOINT}/${iid}`);
-                    return g.processEpoch;
-                },
-            });
-            // P2 item 3 (class scatter): write this instance's CONVERGED svc status so it is a §13.5
-            // scatter member — `freezeExpectedSet` skips any instance whose status is absent or lags the
-            // current registration. Instance-side `ready` at the just-registered spec revision, epoch-fenced
-            // to the gate's processEpoch (the same leader-served reader `authorizeServeGrant` used); on a
-            // restart it CAS-updates the predecessor's status forward (the advanced epoch supersedes the old
-            // one). Key-pinned to this instance's own status key on the SAME executor.
-            await writeServiceStatus(recordsKv, {
-                endpoint: MANAGER_ENDPOINT, instanceId: iid, epoch: processEpoch,
-                status: {
-                    state: SERVICE_READY,
-                    epoch: processEpoch,
-                    observedSpecRevision: registrationRevision,
-                    connectors: this.connectorStatuses.map((row) => ({ ...row, binaries: { ...row.binaries } })),
-                },
-                readProcessEpoch: async () => {
-                    const g = await fence.observe();
-                    if (g === null)
-                        throw new Error(`no issuance gate for ${MANAGER_ENDPOINT}/${iid}`);
-                    return g.processEpoch;
-                },
-            });
             // Open mesh: NO mint - the §13.1 fence is issuance-only and nothing is ever issued, so the
             // gate keeps an empty `epcred` family; the serve connection below stays bare.
             const creds = auth ? await mintCreds(auth, serveIdentity, "endpoint-serve", { serveIssuance: fence, endpointServe: grant }) : undefined;
@@ -7502,9 +7612,7 @@ export class Manager {
      *   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. */
+     *  terminal through the issuance gate's own CAS), deliberately deferred as substrate territory. */
     async assertGoalWriterEpochCurrent(epoch) {
         const gate = this.goalWriter?.gate;
         if (!gate)
@@ -8227,8 +8335,7 @@ export class Manager {
     /** Re-record the custody reference of a managed agent's CURRENT handle on its active slot: a
      *  same-lifecycle restart or a resume binds a new custody under the old uid, and the successor's
      *  reap must address the live one. Static auth only; a runtime without durable custody records
-     *  nothing (there is nothing to reap by reference). Loud on failure, never fatal to the bind: the
-     *  handle is already live and a stale reference is refused by identity at reap time. */
+     *  nothing (there is nothing to reap by reference). */
     async recordSlotRuntime(a) {
         if (a.handle.reference === undefined)
             return;
@@ -8236,7 +8343,9 @@ export class Manager {
     }
     /** Record one custody reference on an agent's ACTIVE slot. Split from {@link recordSlotRuntime}
      *  so a restart or a resume can record the reference it RESERVED before spawning, while no
-     *  handle exists yet. Static auth only; a runtime without durable custody reserves nothing. */
+     *  handle exists yet. Static auth only; a runtime without durable custody reserves nothing.
+     *  Throws when the slot does not take the reference: a slot left on the previous one reaps that
+     *  seat, already gone, so a successor would retire the lifecycle over the new one. */
     async recordSlotCustody(a, runtime) {
         if (!this.auth || this.userMode)
             return;
@@ -8244,14 +8353,14 @@ export class Manager {
             await this.withLifecycleExecutor({ owner: DEV_OWNER, actor: a.id, lifecycleUid: a.lifecycleUid, alias: a.name }, async (t) => {
                 const slot = await readStaticSlot(t, DEV_OWNER, a.name);
                 if (slot === undefined || slot.row.lifecycleUid !== a.lifecycleUid || slot.row.phase !== "active")
-                    return;
+                    throw new Error(`the slot is ${slot === undefined ? "absent" : `${slot.row.phase} at uid ${slot.row.lifecycleUid}`}`);
                 if (slot.row.runtime?.kind === runtime.kind && slot.row.runtime.id === runtime.id)
                     return;
                 await casStaticSlot(t, { ...slot.row, runtime }, slot.revision);
             });
         }
         catch (e) {
-            console.error(`! ${a.name}: could not record the custody reference ${runtime.kind}:${runtime.id} on its static slot: ${e.message} - a successor reaps this seat only by an up-to-date reference`);
+            throw new Error(`could not record the custody reference ${runtime.kind}:${runtime.id} on the static slot of "${a.name}": ${e.message}`);
         }
     }
     /** Mint the custody reference for a seat this manager is about to spawn, BEFORE the processes
@@ -8939,6 +9048,28 @@ export class Manager {
             await prov.stop();
         }
     }
+    /** A connection holding this instance's transfer reader grants (docs/design/resume-transfer.md
+     *  section 6) for this one receive or sweep: minted from the space's signing seed, or issued by the
+     *  host to a remote manager. An open mesh enforces no grants, so a bare one-shot connection is that
+     *  reader there. */
+    async withTransferReader(fn) {
+        const issue = this.remoteAuthority?.mintTransferReader;
+        if (this.remoteAuthority && !issue)
+            throw new Error("withTransferReader: this manager's remote authority issues no transfer reader");
+        const identity = newIdentity();
+        const creds = issue
+            ? await issue(identity)
+            : this.auth && await mintCreds(this.auth, identity, "transfer-reader", { transferReader: { instanceId: this.managerInstanceId } });
+        const nc = await this.dial(creds
+            ? { ...standaloneConnectOpts({ creds, /* not yet wired to a recorded transport */ tls: false }), maxReconnectAttempts: 0 }
+            : { maxReconnectAttempts: 0 });
+        try {
+            return await fn(nc);
+        }
+        finally {
+            await nc.drain().catch(() => nc.close());
+        }
+    }
     /** 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
      *  supervisor); regular agents are denied STREAM.PURGE under auth. Cleanup only: leaves live agents and
@@ -9234,7 +9365,8 @@ export class Manager {
         }
         // establishAttach releases the claim it was handed on every exit; nothing to unwind here.
         const { grant } = await this.sessionPlane.establishAttach(caller, { name: a.name, lifecycleUid: a.lifecycleUid }, session, slot);
-        return { ok: true, data: { grant } };
+        const carried = a.launch.resumed?.host;
+        return { ok: true, data: { grant, ...(carried ? { resumedFrom: { host: carried, source: a.launch.resumed.source } } : {}) } };
     }
     /** 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