@cotal-ai/manager 0.41.3 → 0.42.0

package/dist/manager.js

@@ -18,7 +18,7 @@ import { controlSession } from "./control-session.js";
 import { parseResumeCommitArgs, parseResumeControlArgs, parseResumeFinalizeArgs } from "./resume.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 { jetstreamManager } from "@nats-io/jetstream";
+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";
 // P2 item 6: the manager's ONE §13.6 session plane — offer mint + one-use redeem + PTY-bridge
@@ -28,7 +28,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, registerServiceInstance, deregisterServiceInstance, authorizeServeGrant, writeServiceStatus, SERVICE_READY, serveEndpoint, bindGoal, createGoal, transitionGoal, commitGoalResult, settleGoalUncertain, readGoalResult, readGoalStatus, readGoalSpec, recordGoalIndex, readGoalIndex, clearGoalIndex, listGoalIndex, GOAL_TERMINAL_STATES, goalRefOf, goalProgressTopic, epeSubject, submissionFingerprint, EpEnvelopeError, lifecycleBlocked, renderLifecycleBlocked, } from "@cotal-ai/core";
+import { provisionEndpointGateOpen, endpointRegistrationBarrier, serveIssuanceGateKv, commitSiblingIssuance, markLedgerRowRevoked, epcredRowKey, epgateKey, parseEndpointGate, 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, 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, } from "./static-lifecycle.js";
 /** Concurrency ceiling — the manager refuses to hold more than this many live + in-flight +
@@ -38,6 +38,14 @@ const MAX_AGENTS = 50;
  *  before living this long leaves a cooling stamp that still counts toward the ceiling until it
  *  expires — so churn (spawn↔despawn or spawn↔fast-exit) can't outrun the concurrency bound. */
 const MIN_LIFETIME = 10_000;
+/** Cadence of the turn-deadline sweep while turns are pending: the poll that turns an elapsed
+ *  hold's fire into its expired settle and commits the deadline terminal. Deadlines are
+ *  minutes-scale; a few seconds of lateness on the commit is invisible to the run. */
+const TURN_SWEEP_MS = 5_000;
+/** How long a settled turn's answer is kept so a RETRIED yield hears it instead of `not-found`.
+ *  The window a lost reply is retried in is seconds; five minutes is generous for that and short
+ *  enough that the map drains between bursts rather than growing for the process lifetime. */
+const TURN_ANSWER_RETENTION_MS = 5 * 60_000;
 /** 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
@@ -131,6 +139,29 @@ const FREE_SLOT_CAUSE_TEXT = {
     "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",
 };
+function parseTurnNote(raw) {
+    let o;
+    try {
+        o = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (o === null || typeof o !== "object")
+        return undefined;
+    const n = o;
+    if (typeof n.payload !== "string" || typeof n.deadlineAt !== "number"
+        || typeof n.holdEpoch !== "number" || typeof n.owner !== "string")
+        return undefined;
+    if (n.handoffFrom !== undefined && typeof n.handoffFrom !== "string")
+        return undefined;
+    return { payload: n.payload, deadlineAt: n.deadlineAt, holdEpoch: n.holdEpoch, owner: n.owner, ...(typeof n.handoffFrom === "string" ? { handoffFrom: n.handoffFrom } : {}) };
+}
+/** A turn hold's token, DERIVED from the goal id (same recipe as the runtime's pause tokens): a
+ *  same-goalId retry or a successor incarnation re-derives the identical token with no lookup. */
+function turnHoldToken(goalId) {
+    return createHash("sha256").update(`${goalId}:turn-deadline`, "utf8").digest("base64url").slice(0, 43);
+}
 /** One ep request/reply round-trip on the caller's OWN reply-plane filter (§13.2). The responder
  *  derives the reply subject from the authenticated request, so there is no caller-selected reply
  *  target to honour; the caller binds the answer off the reply SUBJECT — endpoint and nonce, both
@@ -330,6 +361,27 @@ export class Manager {
     /** 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. */
     agentGoals = new Map();
+    /** The turn relay's same-incarnation idempotency map ({@link goalAcceptances}'s twin): a
+     *  same-goalId retry serves the identical acceptance; cross-incarnation retries rebuild from
+     *  the goal-index entry (its acceptance floor + note). */
+    /**
+     * One entry per turn this incarnation accepted: the acceptance a duplicate submission is served
+     * from, and — once the turn settles — the answer a RETRIED yield is served from.
+     *
+     * A yield's reply can be lost, and the retry used to find the pending turn already deleted and
+     * hear `not-found`, which a seat reads as "drop it": failure reported for work that committed.
+     * The settled answer lives here for a bounded window instead, and the sweep drops it after,
+     * which is also what keeps this map from being one entry per turn for the process lifetime.
+     */
+    turnAcceptances = new Map();
+    /** Every relayed turn awaiting its seat's yield, by goal id. The seat's `turn-pending` pull
+     *  scans it; the deadline sweep drives expiry; a seat reap stamps its entries `seatDiedAt`, which
+     *  the deadline terminal carries as `agentDownAt` so the run reads that death as L4002.
+     *  Rebuilt at boot from goal-index entries carrying a turn note. */
+    pendingTurns = new Map();
+    /** The deadline sweep behind {@link pendingTurns}: takes the hold's fire into an expired
+     *  settle and commits the deadline terminal. Unref'd; idle when no turn is pending. */
+    turnSweepTimer;
     /** Process start, for the served `status` uptime. */
     startedAtMs = Date.now();
     /** Connector harness paths resolved ONCE at boot. Missing binaries do not stop unrelated manager
@@ -1755,6 +1807,20 @@ export class Manager {
                     throw new EpEnvelopeError("permission-denied", denied);
                 return this.inputAuthorized(a, args(ctx));
             }),
+            // The turn relay (§8 durable actions): `turn` shares despawn/input's reach policy — the
+            // caller must hold owner-equality or admin over the TARGET seat — written out for the same
+            // reason `input` is (a shared policy, not a shared body).
+            turn: (ctx) => this.serveGated(ctx, async () => {
+                const a = targetAgent(ctx);
+                const denied = await this.authorizeNamed(a, callerOf(ctx), await this.epAnyModeAdmin(ctx));
+                if (denied)
+                    throw new EpEnvelopeError("permission-denied", denied);
+                return this.serveTurnGoal(ctx, a);
+            }),
+            // The seat's own half of the relay (`manager.self`, stop-self's tier): a seat pulls the
+            // turns addressed to ITS incarnation and yields them; no reach beyond itself exists here.
+            turnPending: (ctx) => this.serveGated(ctx, () => this.turnPendingFor(ctx.subject.caller)),
+            turnYield: (ctx) => this.serveGated(ctx, () => this.serveTurnYield(ctx.subject.caller, args(ctx))),
             stopSelf: (ctx) => this.serveGated(ctx, () => unwrap(this.opStopSelf(callerOf(ctx), args(ctx)))),
             definePersona: (ctx) => this.serveGated(ctx, () => unwrap(this.opDefinePersona(args(ctx), callerOf(ctx), false))),
             listPersonas: (ctx) => this.serveGated(ctx, () => unwrap(this.opListPersonas(callerOf(ctx), false))),
@@ -2138,6 +2204,10 @@ export class Manager {
         // `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.
         this.sessionPlane?.endForTarget(a.name, a.lifecycleUid, "target-despawn");
+        // The turn relay's reap hook: every pending turn addressed to THIS incarnation is stamped
+        // with the death, and its deadline terminal carries it as `agentDownAt`. The addressee is gone
+        // and no successor may answer for it; the terminal is still the deadline's, not a new reason.
+        this.failSeatTurns(a.name, a.lifecycleUid);
         if (floor && Date.now() - a.startedAt < MIN_LIFETIME)
             this.cooling.push(a.startedAt + MIN_LIFETIME);
         // #29 piece 3: on a USER mesh the name is RESERVED PENDING RETIREMENT — despawn started this
@@ -5045,14 +5115,19 @@ export class Manager {
             // Single-manager item 2: EVERY inherited entry belongs to a DEAD predecessor (only one manager
             // at a time), so all are reconciled. The `iid` field is the hook item-3's multi-instance sweep
             // filters on (skip a goal whose accepting `iid` is a still-LIVE sibling — never settle its goal).
-            for (const { ref, iid } of entries) {
-                if (this.goalAcceptances.has(ref.goalId))
+            for (const entry of entries) {
+                if (this.goalAcceptances.has(entry.ref.goalId) || this.turnAcceptances.has(entry.ref.goalId))
                     continue; // never settle a goal THIS incarnation drives
                 try {
-                    await this.reconcileOneGoal(ref, iid);
+                    // A note marks a TURN entry: its relay is rebuilt (the hold is its bounded ending), never
+                    // settled uncertain — the spawn arm's readiness window is the wrong ending for a relay.
+                    if (entry.note !== undefined)
+                        await this.adoptTurnGoal(entry);
+                    else
+                        await this.reconcileOneGoal(entry.ref, entry.iid);
                 }
                 catch (e) {
-                    console.error(`! goal reconcile for ${ref.goalId}: ${e.message}`);
+                    console.error(`! goal reconcile for ${entry.ref.goalId}: ${e.message}`);
                 }
             }
             if (entries.length)
@@ -5399,6 +5474,423 @@ export class Manager {
             return { name: d.name, owner: DEV_OWNER, actor: d.id, uid: d.lifecycleUid, goalId, fingerprint, readinessDeadlineMs, executor };
         throw new EpEnvelopeError("unavailable", `goal "${goalId}" is already accepted but its allocated identity is not readable (no acceptance floor, and no terminal carrying one); retry (SPEC 13.6)`);
     }
+    // ---- the turn relay (§8 durable actions) ------------------------------------------------------
+    //
+    // A seat is NOT an endpoint: a run's `turn(agent, payload)` rides the manager, which accepts it
+    // as a goal (the spawn-as-action pattern minus the launch closure), parks the payload durably on
+    // the goal-index entry's note, and lets the seat PULL it (`turn-pending`) and answer it
+    // (`turn-yield`) under its own `manager.self` reach. The deadline is a goal-bound HOLD minted at
+    // accept: the delivery daemon's timer writer pumps its schedule, the fire settles it `expired`,
+    // and THIS manager commits the deny (`hold-expired` is the predicate core verifies). Three
+    // endings, one each: yield -> succeeded (the TurnResult rides the terminal's data), deadline ->
+    // failed `turn-deadline`, and a seat death before that is stamped by the reap hook so the same
+    // terminal carries `agentDownAt` (the run reads it as L4002). The adoption sweep stamps nothing.
+    /** Accept one `turn` goal against a live managed seat. Mirrors {@link serveSpawnGoal}'s accept
+     *  path (idempotent retry map, index-CAS-before-bind, create-only bindGoal) but runs it INLINE:
+     *  there is no launch to hand off, so the accept either completes durably or unwinds its own
+     *  bound goal with a `failed` terminal before refusing. */
+    async serveTurnGoal(ctx, a) {
+        const gw = this.goalWriter;
+        if (!gw)
+            throw new EpEnvelopeError("unavailable", "the manager goal-writer connection is not standing; turn-as-action cannot accept (SPEC 13.6)");
+        const serve = this.serviceServe;
+        if (!serve)
+            throw new EpEnvelopeError("unavailable", "the manager service endpoint is not serving; a turn's deadline hold is armed over its connection (SPEC 13.9)");
+        if (!this.goalReconcileDone)
+            throw new EpEnvelopeError("unavailable", "the manager is still reconciling accepted goals at boot; retry shortly (SPEC 13.6)");
+        const t = ctx.request.target; // targeted command: the serve boundary enforced presence + currency
+        const goalId = ctx.request.id;
+        const { fingerprint } = submissionFingerprint(ctx.request, ctx.subject);
+        const ref = goalRefOf(ctx.subject, goalId);
+        const executor = { lifecycleUid: this.managerInstanceId, epoch: this.serviceServe?.grant.epoch ?? 0 };
+        const acceptedAt = Date.now();
+        const prior = this.turnAcceptances.get(goalId)?.acceptance;
+        if (prior !== undefined) {
+            if (prior.fingerprint !== fingerprint)
+                throw new EpEnvelopeError("failed-precondition", `goal "${goalId}" was accepted under a different submission; one goalId never carries two specs (SPEC 13.6)`);
+            return prior;
+        }
+        const raw = (ctx.request.args ?? {});
+        const payload = String(raw.payload);
+        const deadlineMs = Number(raw.deadlineMs);
+        const handoffFrom = raw.handoffFrom === undefined ? undefined : String(raw.handoffFrom);
+        const deadlineAt = acceptedAt + deadlineMs;
+        const note = JSON.stringify({ payload, deadlineAt, holdEpoch: executor.epoch, owner: t.owner, ...(handoffFrom !== undefined ? { handoffFrom } : {}) });
+        // A goal that already ENDED is never accepted again, whatever the retry carries: the bind is
+        // create-only and outlives an unwind (the failed terminal, the cleared index), so a retry of an
+        // unwound accept would otherwise re-record an index entry over a tombstone and, before that
+        // check existed, be served an acceptance rebuilt from it — a live deadline on a turn no seat
+        // would ever be shown. The terminal is the durable answer, and it is read before anything is
+        // written.
+        const ended = await readGoalResult(gw.ctx, ref);
+        if (ended !== undefined)
+            throw new EpEnvelopeError("failed-precondition", `goal "${goalId}" already ended ${ended.state}; a bound goal is never accepted again (SPEC 13.6)`);
+        // Index-CAS-before-bind, exactly as spawn: the entry (floor + note) is the durable relay
+        // record a successor rebuilds from, so it must exist before the acceptance is servable.
+        const idx = await recordGoalIndex(gw.ctx, ref, executor.lifecycleUid, { name: a.name, actor: t.actor, uid: t.lifecycleUid, readinessDeadlineMs: deadlineMs }, note);
+        if (!idx.recorded && idx.existing.iid !== executor.lifecycleUid)
+            throw new EpEnvelopeError("failed-precondition", `goal "${goalId}" was accepted by instance "${idx.existing.iid}"; that instance owns its relay and this attempt provisions nothing (SPEC 13.6)`);
+        const b = await bindGoal(gw.ctx, ref, fingerprint);
+        if (!b.bound) {
+            if (b.existing.fingerprint !== fingerprint)
+                throw new EpEnvelopeError("failed-precondition", `goal "${goalId}" is already bound to a different submission; one goalId never carries two specs (SPEC 13.6)`);
+            // Same submission, bound, not ended, and not in the acceptance map. Every relay this
+            // incarnation holds is in that map (the accept path and the boot sweep both write it), so
+            // this is a goal nobody is relaying: an earlier attempt bound it and could not finish its
+            // unwind, or a predecessor's relay was left unadopted. Nothing here can rebuild a relay a
+            // seat will be shown, so the caller is refused rather than served an acceptance no pending
+            // entry backs; the index entry this attempt recorded is withdrawn with it.
+            if (idx.recorded)
+                await clearGoalIndex(gw.ctx, ref);
+            throw new EpEnvelopeError("unavailable", `goal "${goalId}" is bound but no relay of it is pending on this instance; retry (SPEC 13.6)`);
+        }
+        try {
+            await createGoal(gw.ctx, ref, {
+                fingerprint,
+                command: ctx.subject.command,
+                caller: { id: `${ctx.subject.caller.owner}.${ctx.subject.caller.actor}`, lifecycleUid: ctx.subject.caller.uid },
+                acceptedEpoch: executor.epoch,
+                requestId: goalId,
+                sourceSeq: 0,
+                acceptedAt,
+                readinessDeadlineMs: deadlineMs,
+                // The §13.6 target pin: the seat INCARNATION this payload is addressed to. A successor
+                // under the same name is a different addressee; its uid differs and the pin holds that.
+                target: { owner: t.owner, actor: t.actor, lifecycleUid: t.lifecycleUid, mappingRevision: 0 },
+            });
+            // The deadline, as a goal-bound hold on the plane: its EXPIRED settle is the one predicate
+            // `commitGoalResult` accepts for the deny. The record rides the goal-writer's KV; the
+            // `.schedule` request rides the SERVE connection, because the timer row is the serving
+            // instance's own (`ept.<e>.<iid>.<epoch>.*.schedule`, SPEC 13.9) and the goal-writer holds
+            // none. Measured on an auth mesh: minted over the goal-writer, the schedule publish was
+            // broker-denied and every accept unwound.
+            await mintCheckpoint(gw.ctx.kv, jetstream(serve.nc), this.space, {
+                ref: { endpoint: ref.endpoint, token: turnHoldToken(goalId) },
+                instanceId: this.managerInstanceId,
+                epoch: executor.epoch,
+                goal: { caller: { owner: ctx.subject.caller.owner, actor: ctx.subject.caller.actor, uid: ctx.subject.caller.uid }, goalId },
+                holder: { id: MANAGER_ENDPOINT, lifecycleUid: this.managerInstanceId },
+                deadline: deadlineAt,
+                now: acceptedAt,
+            });
+        }
+        catch (e) {
+            // The accept is inline (no launch closure to fail later), so a post-bind throw unwinds HERE:
+            // commit the failed terminal this attempt owns, clear the index, and refuse the accept — an
+            // accepted-but-unanswered goal must never be left for the boot sweep to find (H1's rule).
+            const msg = e?.message ?? String(e);
+            try {
+                await this.assertGoalWriterEpochCurrent(executor.epoch);
+                // The goal is TARGET-PINNED, so its completion proves the seat's currency exactly as the
+                // yield's does (managed-seat epochs are 0 within an incarnation; the resolver answers from
+                // the live agents map). Committed without it, core refused the terminal and the unwind
+                // left a bound goal with no ending for every retry to find.
+                await commitGoalResult(gw.ctx, {
+                    ref, now: Date.now(), cause: "complete", state: "failed", data: { error: msg },
+                    committer: { instanceId: this.managerInstanceId, epoch: executor.epoch },
+                    executor: { lifecycleUid: t.lifecycleUid, epoch: 0 },
+                    resolveCurrentEpoch: (target) => this.agents.get(a.name)?.lifecycleUid === target.lifecycleUid ? 0 : null,
+                });
+                await clearGoalIndex(gw.ctx, ref);
+            }
+            catch (e2) {
+                console.error(`! turn accept unwind for ${goalId}: ${e2.message}`);
+            }
+            throw e instanceof EpEnvelopeError ? e : new EpEnvelopeError("internal", `turn accept for ${goalId} failed: ${msg}`);
+        }
+        const pending = {
+            ref, goalId,
+            seat: { name: a.name, owner: t.owner, actor: t.actor, uid: t.lifecycleUid },
+            payload, acceptedAt, deadlineAt,
+            holdToken: turnHoldToken(goalId), holdEpoch: executor.epoch,
+            ...(handoffFrom !== undefined ? { handoffFrom } : {}),
+        };
+        this.pendingTurns.set(goalId, pending);
+        this.ensureTurnSweep();
+        const acceptance = { name: a.name, owner: t.owner, actor: t.actor, uid: t.lifecycleUid, goalId, fingerprint, deadlineAt, executor };
+        this.turnAcceptances.set(goalId, { acceptance });
+        this.emitGoalProgress(ref, executor.epoch, { phase: "relayed" });
+        return acceptance;
+    }
+    /** The seat's pull: every pending turn addressed to the CALLER's incarnation, oldest first.
+     *  The uid is part of the address — a successor seat never receives a predecessor's turn. */
+    turnPendingFor(c) {
+        // AN EMPTY LIST IS AN ANSWER, so it must not be given before the index is rebuilt. Between
+        // registration and `reconcileGoalIndex`, `pendingTurns` holds nothing a predecessor accepted,
+        // and a seat that pulls in that window is told authoritatively that it has no turn. The seat
+        // treats a refusal as "keep what you hold" and an empty list as "you hold nothing", so the
+        // window has to refuse, the same way `serveTurnGoal` does.
+        if (!this.goalReconcileDone)
+            throw new EpEnvelopeError("unavailable", "the manager is still reconciling accepted goals at boot; the pending-turn index is not rebuilt yet, retry (SPEC 13.6)");
+        // Two turns on one seat are serialized at the dispatch (cotal-lang 6.5): only the oldest
+        // unsettled one is served, and the next surfaces once it yields or its deadline denies, so a
+        // seat is never shown two turns at once.
+        // An ELAPSED turn is not servable: its hold is expirable and its run has already thrown from
+        // its own pause, so handing it to the seat buys work whose yield is refused. It also cannot be
+        // allowed to stay the head, or one expired turn dams every later turn for that seat.
+        const now = Date.now();
+        const turns = [...this.pendingTurns.values()]
+            .filter((p) => p.seat.owner === c.owner && p.seat.actor === c.actor && p.seat.uid === c.uid)
+            .filter((p) => now < p.deadlineAt)
+            .sort((x, y) => x.acceptedAt - y.acceptedAt)
+            .slice(0, 1)
+            .map((p) => ({ goalId: p.goalId, payload: p.payload, acceptedAt: p.acceptedAt, deadlineAt: p.deadlineAt }));
+        return { turns };
+    }
+    /** The seat's yield: claim the hold (one-use; expiry fails closed), then commit the goal
+     *  `succeeded` carrying the TurnResult. A yield AFTER the deadline drives the deadline terminal
+     *  instead and refuses — the expiry outcome stands, never a late success over it. */
+    async serveTurnYield(c, raw) {
+        // Same boot window as the pull, and checked first because it is the earlier boot phase: before
+        // the index is rebuilt a predecessor's accepted turn is not in `pendingTurns`, and `not-found`
+        // would tell the seat to drop work it is holding.
+        if (!this.goalReconcileDone)
+            throw new EpEnvelopeError("unavailable", "the manager is still reconciling accepted goals at boot; this yield's turn may not be indexed yet, retry (SPEC 13.6)");
+        const gw = this.goalWriter;
+        if (!gw)
+            throw new EpEnvelopeError("unavailable", "the manager goal-writer connection is not standing (SPEC 13.6)");
+        const goalId = String(raw.goalId);
+        const status = String(raw.status);
+        const to = raw.to === undefined ? undefined : String(raw.to);
+        const yieldNote = raw.note === undefined ? undefined : String(raw.note);
+        if (status === "handoff" && (to === undefined || to.length === 0))
+            throw new EpEnvelopeError("failed-precondition", `a handoff yield names its addressee ("to"); a handoff to nobody relays nothing`);
+        const p = this.pendingTurns.get(goalId);
+        if (!p) {
+            // A YIELD WHOSE REPLY WAS LOST IS NOT A YIELD THAT FAILED. The commit deleted the pending
+            // turn, so a retry found nothing and heard `not-found` — which a seat reads as "drop it",
+            // reporting failure for work the run already has. The answer the first reply carried is
+            // served again instead, to the addressee it was addressed to and nobody else.
+            const settled = this.turnAcceptances.get(goalId);
+            if (settled?.settled !== undefined) {
+                const a = settled.acceptance;
+                if (a.owner !== c.owner || a.actor !== c.actor || a.uid !== c.uid)
+                    throw new EpEnvelopeError("permission-denied", `turn "${goalId}" was addressed to ${a.owner}.${a.actor}/${a.uid}; a yield is the addressee's own (SPEC 13.6)`);
+                return { goalId, state: settled.settled.state };
+            }
+            throw new EpEnvelopeError("not-found", `no pending turn "${goalId}" on this manager`);
+        }
+        if (p.seat.owner !== c.owner || p.seat.actor !== c.actor || p.seat.uid !== c.uid)
+            throw new EpEnvelopeError("permission-denied", `turn "${goalId}" is addressed to ${p.seat.owner}.${p.seat.actor}/${p.seat.uid}; a yield is the addressee's own (SPEC 13.6)`);
+        const cpRef = { endpoint: p.ref.endpoint, token: p.holdToken };
+        try {
+            await resumeCheckpoint(gw.ctx.kv, gw.ctx.js, gw.ctx.jsm, this.space, { ref: cpRef, presenter: { id: MANAGER_ENDPOINT, lifecycleUid: this.managerInstanceId }, now: Date.now() });
+        }
+        catch (e) {
+            const settle = await readCheckpointSettle(gw.ctx.jsm, this.space, cpRef).catch(() => undefined);
+            if (settle?.settle === "expired") {
+                await this.commitTurnDeadline(p);
+                throw new EpEnvelopeError("failed-precondition", `turn "${goalId}" elapsed its deadline before the yield; the deadline terminal stands (SPEC 13.6)`);
+            }
+            // Already resumed BY THIS MANAGER (the hold is holder-bound): a prior yield attempt claimed
+            // it and then failed to commit. Fall through and commit — the claim is ours to finish.
+            if (settle?.settle !== "resumed")
+                throw e;
+        }
+        const epoch = this.serviceServe?.grant.epoch ?? 0;
+        await this.assertGoalWriterEpochCurrent(epoch);
+        const at = Date.now();
+        const data = { status, ...(to !== undefined ? { to } : {}), ...(yieldNote !== undefined ? { note: yieldNote } : {}), ...(p.handoffFrom !== undefined ? { handoffFrom: p.handoffFrom } : {}), at };
+        // The goal is TARGET-PINNED, so this completion proves the EXECUTOR's (the seat's) fresh
+        // currency, not the manager's: managed-seat epochs are 0 within an incarnation (the same
+        // convention resolveTarget serves), and the resolver answers from the live agents map — a
+        // seat that died between its yield call and this commit refuses `expired` here.
+        const { fact } = await commitGoalResult(gw.ctx, {
+            ref: p.ref, now: at, cause: "complete", state: "succeeded", data,
+            committer: { instanceId: this.managerInstanceId, epoch },
+            executor: { lifecycleUid: p.seat.uid, epoch: 0 },
+            resolveCurrentEpoch: (target) => this.agents.get(p.seat.name)?.lifecycleUid === target.lifecycleUid ? 0 : null,
+        });
+        this.emitGoalProgress(p.ref, epoch, { phase: "terminal", state: fact.state, ...(fact.data !== undefined ? { data: fact.data } : {}) });
+        await clearGoalIndex(gw.ctx, p.ref);
+        this.pendingTurns.delete(goalId);
+        this.rememberSettledTurn(goalId, fact.state, at);
+        this.maybeStopTurnSweep();
+        return { goalId, state: fact.state };
+    }
+    /** Commit the deadline terminal for one pending turn whose hold settled EXPIRED: the deny's
+     *  predicate is that recorded settle, verified by core against the spec's goal binding. The map
+     *  delete is the idempotency latch (yield-loss and sweep race here); a commit failure after it
+     *  converges through the goal index at the next boot, the same narrow leg spawn leaves open. */
+    async commitTurnDeadline(p) {
+        const gw = this.goalWriter;
+        if (!gw)
+            return;
+        if (!this.pendingTurns.delete(p.goalId))
+            return;
+        const epoch = this.serviceServe?.grant.epoch ?? 0;
+        try {
+            await this.assertGoalWriterEpochCurrent(epoch);
+            const { fact } = await commitGoalResult(gw.ctx, { ref: p.ref, now: Date.now(), cause: "deny", denial: { kind: "hold-expired", token: p.holdToken }, data: { reason: "turn-deadline", ...(p.seatDiedAt !== undefined ? { agentDownAt: p.seatDiedAt } : {}), ...(p.handoffFrom !== undefined ? { handoffFrom: p.handoffFrom } : {}) }, committer: { instanceId: this.managerInstanceId, epoch } });
+            this.emitGoalProgress(p.ref, epoch, { phase: "terminal", state: fact.state, ...(fact.data !== undefined ? { data: fact.data } : {}) });
+            await clearGoalIndex(gw.ctx, p.ref);
+            // The SAME order the yield path keeps: remember, then ask whether the sweep may stop. Asked
+            // first, the stop saw no pending turn and no settled answer, cleared the acceptance map, and
+            // the remember below found nothing to write to; a yield whose reply was lost then heard
+            // `not-found` for the last expired turn, which the seat reads as "drop it".
+            this.rememberSettledTurn(p.goalId, fact.state, Date.now());
+        }
+        catch (e) {
+            console.error(`! turn deadline terminal for ${p.goalId}: ${e.message}`);
+        }
+        this.maybeStopTurnSweep();
+    }
+    /** The reap hook: a pending turn addressed to the reaped INCARNATION is MARKED dead, never
+     *  settled early — no honest terminal exists for it (a completion must prove the executor's
+     *  live currency, and the hold is only expirable once due), so the entry rides to its deadline
+     *  and the deny then records both facts. The addressee's own client observes the death from
+     *  presence long before that, which is the run's L4002. */
+    failSeatTurns(name, uid) {
+        for (const p of this.pendingTurns.values()) {
+            if (p.seat.name !== name || p.seat.uid !== uid || p.seatDiedAt !== undefined)
+                continue;
+            p.seatDiedAt = Date.now();
+            console.error(`turn ${p.goalId}: addressed seat ${name}/${uid} died before yielding; the deadline terminal will record it`);
+        }
+    }
+    /** Settle one DUE hold as its owner: the manager minted it, so once the deadline has passed it
+     *  expires the pause itself ({@link expireCheckpoint}, the guard-hold precedent) rather than
+     *  waiting on the broker's fire — which it holds no grant to read, and which a hold minted under
+     *  a predecessor's epoch would carry on a subject this incarnation never subscribes. Idempotent
+     *  by the plane: a yield that claimed the hold first is observed as `resumed` and left to its
+     *  own commit, and an already-expired hold returns its recorded settle. */
+    async expireTurnHold(p) {
+        const gw = this.goalWriter;
+        if (!gw)
+            return undefined;
+        return expireCheckpoint(gw.ctx.kv, gw.ctx.js, gw.ctx.jsm, this.space, { ref: { endpoint: p.ref.endpoint, token: p.holdToken }, now: Date.now() });
+    }
+    ensureTurnSweep() {
+        if (this.turnSweepTimer !== undefined)
+            return;
+        const t = setInterval(() => { void this.sweepTurnDeadlines().catch((e) => console.error(`! turn deadline sweep: ${e.message}`)); }, TURN_SWEEP_MS);
+        t.unref?.();
+        this.turnSweepTimer = t;
+    }
+    /** The answer a retried yield is served, held for {@link TURN_ANSWER_RETENTION_MS}. Only for a
+     *  turn this incarnation accepted: an entry it has no acceptance for is one it cannot vouch for. */
+    rememberSettledTurn(goalId, state, at) {
+        const entry = this.turnAcceptances.get(goalId);
+        if (entry === undefined)
+            return;
+        entry.settled = { state, at };
+    }
+    /** Stop the sweep only when it has nothing left to do. It drives elapsed turns to their deadline
+     *  terminals AND drops settled answers once their retry window has passed, so a stop while the
+     *  second is still owed would leave one entry per turn for the process lifetime. */
+    maybeStopTurnSweep() {
+        if (this.pendingTurns.size > 0)
+            return;
+        for (const e of this.turnAcceptances.values())
+            if (e.settled !== undefined)
+                return;
+        this.turnAcceptances.clear();
+        this.stopTurnSweep();
+    }
+    stopTurnSweep() {
+        if (this.turnSweepTimer === undefined)
+            return;
+        clearInterval(this.turnSweepTimer);
+        this.turnSweepTimer = undefined;
+    }
+    /** Drive every elapsed pending turn to its deadline terminal. Only entries at/past their own
+     *  `deadlineAt` are read at all; a `resumed` settle is a yield mid-commit and is left alone. */
+    async sweepTurnDeadlines() {
+        const now = Date.now();
+        // A settled answer is kept only as long as a lost reply could still be retried under it.
+        for (const [goalId, e] of [...this.turnAcceptances.entries()])
+            if (e.settled !== undefined && now - e.settled.at >= TURN_ANSWER_RETENTION_MS)
+                this.turnAcceptances.delete(goalId);
+        // The prune above is the one event after which the sweep may have nothing left to do, and
+        // the settle-time callers cannot see it: they run when an answer has just been remembered.
+        this.maybeStopTurnSweep();
+        for (const p of [...this.pendingTurns.values()]) {
+            if (now < p.deadlineAt)
+                continue;
+            try {
+                const settle = await this.expireTurnHold(p);
+                if (settle?.settle === "expired")
+                    await this.commitTurnDeadline(p);
+            }
+            catch (e) {
+                console.error(`! turn deadline sweep for ${p.goalId}: ${e.message}`);
+            }
+        }
+    }
+    /** Adopt one inherited TURN goal at boot (the reconcile sweep's turn branch): a non-terminal
+     *  entry carrying a parseable note rebuilds its pending relay — never an `uncertain` settle,
+     *  because the deadline hold IS this goal's bounded ending and it survived the restart. No
+     *  liveness verdict is made here (the agents map is empty during reconcile, so absence means
+     *  "not yet re-registered", never "dead"); a garbled note or a missing floor is logged and
+     *  left, the dead-pointer honesty rule. */
+    async adoptTurnGoal(entry) {
+        const gw = this.goalWriter;
+        if (!gw)
+            return;
+        const status = await readGoalStatus(gw.ctx, entry.ref);
+        if (status === undefined)
+            return; // index points at no goal record: a dead pointer, left for honesty
+        if (GOAL_TERMINAL_STATES.includes(status.value.state)) {
+            await clearGoalIndex(gw.ctx, entry.ref);
+            return;
+        }
+        if (entry.iid !== this.managerInstanceId) {
+            console.error(`turn reconcile ${entry.ref.goalId}: accepted by instance "${entry.iid}", not this incarnation "${this.managerInstanceId}"; left for its owner (never a cross-instance settle)`);
+            return;
+        }
+        const parsed = entry.note !== undefined ? parseTurnNote(entry.note) : undefined;
+        if (entry.allocated === undefined || parsed === undefined) {
+            console.error(`turn reconcile ${entry.ref.goalId}: the relay record is garbled (no floor, or an unparseable note); left unsettled`);
+            return;
+        }
+        const spec = await readGoalSpec(gw.ctx, entry.ref);
+        if (spec === undefined) {
+            // NOW IS NOT WHEN THIS WAS ACCEPTED. `acceptedAt` is what orders a seat's queue, and a turn
+            // stamped with the boot instant sorts BEHIND every turn accepted since — a predecessor's
+            // oldest turn served last, which is the one thing the ordering exists to prevent. A goal
+            // with an index entry and no spec is a relay record that is not readable, and this is the
+            // same verdict the garbled-note branch above reaches: left unsettled, said out loud.
+            console.error(`turn reconcile ${entry.ref.goalId}: the goal spec is unreadable, so its acceptance time is unknown; left unsettled rather than re-stamped with the boot instant`);
+            return;
+        }
+        const p = {
+            ref: entry.ref, goalId: entry.ref.goalId,
+            seat: { name: entry.allocated.name, owner: parsed.owner, actor: entry.allocated.actor, uid: entry.allocated.uid },
+            payload: parsed.payload,
+            acceptedAt: spec.value.acceptedAt,
+            deadlineAt: parsed.deadlineAt,
+            holdToken: turnHoldToken(entry.ref.goalId), holdEpoch: parsed.holdEpoch,
+            ...(parsed.handoffFrom !== undefined ? { handoffFrom: parsed.handoffFrom } : {}),
+        };
+        // The hold is the relay's bounded ending, minted AFTER the index entry and the goal record,
+        // so a crash between them leaves a goal with no hold: nothing could ever settle it, and the
+        // sweep would report the same missing pause every tick. Left unsettled, said once.
+        if ((await readCheckpointSpec(gw.ctx.kv, { endpoint: p.ref.endpoint, token: p.holdToken })) === undefined) {
+            console.error(`turn reconcile ${p.goalId}: its deadline hold was never minted (the accept crashed before it); left unsettled`);
+            return;
+        }
+        this.pendingTurns.set(p.goalId, p);
+        // THE ACCEPTANCE TOO, or the adopted turn's answer is never remembered: `rememberSettledTurn`
+        // writes only against an acceptance this incarnation holds, and adoption rebuilt the pending
+        // relay without one, so a yield whose reply was lost after a restart still heard `not-found`
+        // on the very path adoption exists for. The acceptance is rebuilt from the same records the
+        // relay was: the spec holds the fingerprint, the index holds the seat, the note the deadline.
+        this.turnAcceptances.set(p.goalId, {
+            acceptance: {
+                name: p.seat.name, owner: p.seat.owner, actor: p.seat.actor, uid: p.seat.uid, goalId: p.goalId,
+                fingerprint: spec.value.fingerprint, deadlineAt: p.deadlineAt,
+                executor: { lifecycleUid: this.managerInstanceId, epoch: p.holdEpoch },
+            },
+        });
+        // NO LIVENESS VERDICT AT BOOT. The agents map is empty here: seats are re-registered later,
+        // by the resume path, so `not in the map` at this moment means "not yet re-registered", never
+        // "dead". Stamping death from it marked EVERY adopted turn as a dead seat, and its deadline
+        // terminal then carried `agentDownAt`, so the run raised L4002 for a seat that was alive the
+        // whole time where the reference says L4003. The reap hook is the only honest writer of that
+        // fact: it fires when a managed seat actually dies.
+        console.error(`turn reconcile ${p.goalId}: pending relay to ${p.seat.name}/${p.seat.uid} adopted (deadline ${p.deadlineAt})`);
+        this.ensureTurnSweep();
+    }
     /** 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