@fastagent-sh/fastagent 0.21.1 → 0.22.0

package/dist/engines/pi/session-control.js

@@ -1,46 +1,75 @@
-import { findCutPoint, getLatestCompactionEntry, sessionEntryToContextMessages, } from "@earendil-works/pi-coding-agent";
+// The L0 rendering payload reads message text the way the engine does — ONE reading, joined without a
+// separator because this payload is a transcript, not a preview line.
+import { contentText } from "@earendil-works/pi-ai";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Queue from "effect/Queue";
+import { PortFailure, port, portAbort, portCleanup, portError, portJoin } from "../../effect-port.js";
+import { acquireSession, acquireSessionLease } from "./session-effects.js";
+import { calculateContextTokens, estimateTokens, getLastAssistantUsage, } from "@earendil-works/pi-coding-agent";
 import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
 import { SESSION_BUSY_CODE } from "../../agent.js";
 import { BOUNDARY_COMMAND_FAILED_CODE, INVALID_COMMAND_CODE, isAddressableSession, NO_ACTIVE_RUN_CODE, NOTHING_TO_COMPACT_CODE, NO_SUCH_SESSION_CODE, PARTIAL_UPDATE_CODE, UPDATE_FIELDS, RUN_COMMAND_FAILED_CODE, UNSUPPORTED_CAPABILITY_CODE, } from "../../session.js";
 import { listModels } from "./config.js";
 import { forkProvenance, isNavigable, publishedLeaf } from "./session-markers.js";
+import { startCompaction } from "./agent-session-factory.js";
 import { toRetryScheduledEvent } from "./retry-event.js";
 import { THINKING_LEVELS, activePath, resolveSessionSettings } from "./session-settings.js";
 import { log } from "../../log.js";
-/** Admission uses coding-agent's cut point and context rules, including a split-turn prefix.
- *  Its prepareCompaction is private; agent-core's namesake uses a different journal format. */
-function hasCompactableHistory(path, keepRecentTokens) {
-    if (path.at(-1)?.type === "compaction")
-        return false;
-    const previous = getLatestCompactionEntry(path);
-    let start = 0;
-    if (previous) {
-        const kept = path.findIndex((entry) => entry.id === previous.firstKeptEntryId);
-        start = kept >= 0 ? kept : path.indexOf(previous) + 1;
+// ── Usage (read from the record) ─────────────────────────────────────────────
+/**
+ * What the newest answer cost and how full the context is, from the record rather than a live session (a served
+ * session exists only during its run). The numbers are the provider's own, on the newest assistant pi counts as
+ * carrying usage (`getLastAssistantUsage`). The context size adds pi's estimate of what followed that answer, which
+ * after a finished turn is nothing: then it is exactly pi's `getContextUsage()`.
+ *
+ * `contextTokens` is omitted, never guessed, once a compaction or a context edit follows that answer: the provider's
+ * count no longer describes the context (pi's own rule). pi then estimates from characters; this reports unknown
+ * until the next response.
+ */
+function sessionUsage(path, record, contextWindow) {
+    const usage = getLastAssistantUsage(path);
+    if (!usage)
+        return undefined;
+    let at = path.length - 1;
+    while (at >= 0) {
+        const entry = path[at];
+        if (entry?.type === "message" && entry.message.usage === usage)
+            break;
+        at--;
     }
-    const { firstKeptEntryIndex } = findCutPoint(path, start, path.length, keepRecentTokens);
-    return path
-        .slice(start, firstKeptEntryIndex)
-        .some((entry) => entry.type !== "compaction" && sessionEntryToContextMessages(entry).length > 0);
+    const answer = path[at];
+    const stale = path.slice(at + 1).some((entry) => entry.type === "compaction" || entry.type === "context_edit");
+    let contextTokens;
+    if (answer && !stale) {
+        let trailing = 0;
+        let after = false;
+        for (const { sourceEntry, messages } of record.buildSessionProjection().entries) {
+            if (after)
+                for (const message of messages)
+                    trailing += estimateTokens(message);
+            if (sourceEntry.id === answer.id)
+                after = true;
+        }
+        contextTokens = calculateContextTokens(usage) + trailing;
+    }
+    return {
+        inputTokens: usage.input,
+        outputTokens: usage.output,
+        cacheReadTokens: usage.cacheRead,
+        cacheWriteTokens: usage.cacheWrite,
+        cost: usage.cost.total,
+        ...(contextTokens !== undefined ? { contextTokens } : {}),
+        ...(contextWindow !== undefined && contextWindow > 0 ? { contextWindow } : {}),
+    };
 }
 // ── Entry normalization (durable plane) ──────────────────────────────────────
-/** Concatenated plain text of a message's content blocks (the L0 rendering payload). A custom
- *  AgentMessage role may carry no `content` at all — that reads as empty, not a crash. */
-function textOf(content) {
-    if (typeof content === "string")
-        return content;
-    if (!Array.isArray(content))
-        return "";
-    return content
-        .filter((b) => b.type === "text" && typeof b.text === "string")
-        .map((b) => b.text)
-        .join("");
-}
 /**
  * pi `PiSessionEntry` → neutral {@link SessionEntry}. Message entries map onto the guaranteed
  * kind vocabulary (user/assistant/tool) with a minimal render payload; every other engine record
  * keeps its pi type as an open-set kind with an EMPTY payload — present so `parentId` chains and
  * cursors stay intact, skippable by contract, and no pi message class leaks through the adapter.
+ * One exception: `context_edit` carries `{ targetId, omitted }`, never the replacement content.
  */
 function toSessionEntry(entry, parentId) {
     const base = {
@@ -51,12 +80,12 @@ function toSessionEntry(entry, parentId) {
     if (entry.type === "message") {
         const m = entry.message;
         if (m.role === "user")
-            return { ...base, kind: "user", data: { text: textOf(m.content) } };
+            return { ...base, kind: "user", data: { text: contentText(m.content, "") } };
         if (m.role === "assistant") {
             const toolCalls = m.content
                 .filter((b) => b.type === "toolCall")
                 .map((b) => ({ id: b.id ?? "", name: b.name ?? "" }));
-            const data = { text: textOf(m.content) };
+            const data = { text: contentText(m.content, "") };
             if (toolCalls.length > 0)
                 data.toolCalls = toolCalls;
             return { ...base, kind: "assistant", data };
@@ -69,13 +98,21 @@ function toSessionEntry(entry, parentId) {
                     toolCallId: m.toolCallId,
                     toolName: m.toolName,
                     isError: m.isError ?? false,
-                    text: textOf(m.content),
+                    text: contentText(m.content, ""),
                 },
             };
         }
-        // A custom AgentMessage role (channel/extension-defined): open-set kind, skippable.
+        // Not a conversation turn (`isConversationMessage`): the engine's own `system` bookkeeping, or a custom
+        // AgentMessage role a channel/extension defined. Open-set kind with an EMPTY payload, skippable by contract —
+        // which is also what keeps the assembled prompt out of everything this plane publishes.
         return { ...base, kind: `message:${m.role}`, data: {} };
     }
+    // Which transcript entry the model no longer sees as written: `omitted` when it left the model context (pi's own
+    // abandoned retry and overflow attempts, or an extension's edit), otherwise its content was replaced. The target
+    // stays in the transcript either way, and the edit applies only on a path that contains it.
+    if (entry.type === "context_edit") {
+        return { ...base, kind: entry.type, data: { targetId: entry.targetId, omitted: entry.replacement === null } };
+    }
     return { ...base, kind: entry.type, data: {} };
 }
 // ── Live fan-out (events plane) ──────────────────────────────────────────────
@@ -83,9 +120,22 @@ function toSessionEntry(entry, parentId) {
  *  prefix; the reader drains it before seeing done, then reconnects and backfills via entries(). */
 export const SUBSCRIBER_BUFFER_CAP = 10_000;
 export const SUBSCRIBER_BUFFER_BYTES = 8 * 1024 * 1024;
-/** One subscriber's bounded push→pull queue. `close()` settles a
- *  pending pull — an async generator suspended on a quiet stream cannot be ended by `return()`
- *  alone (it queues behind the never-settling await), so teardown needs this explicit door. */
+/**
+ * One subscriber's bounded push→pull queue.
+ *
+ * The mechanics are Effect's, because both halves are things this class hand-rolled and got wrong
+ * once each. `Queue.end` stops accepting offers, lets the reader drain what WAS accepted, and only
+ * then reports done — which is both the overflow policy above and the door teardown needs (an async
+ * generator suspended on a quiet stream cannot be ended by `return()` alone: that queues behind the
+ * never-settling await). And a queue has a SET of takers, so two concurrent `next()` calls — legal,
+ * any wrapper may poll twice — cannot overwrite each other's resolver.
+ *
+ * What stays here is the arithmetic Queue has no opinion on: the two backlog limits, and the JSON
+ * snapshot (taken at push, so a producer that later mutates its event or tool result cannot grow a
+ * queued one). Cost of the swap: one fiber per delivered event instead of an array shift, on a
+ * stream that carries per-token deltas — cheap next to a model call, and paid only while someone is
+ * attached.
+ */
 class Subscriber {
     /** For the overflow diagnostic only — a warn without the session is not actionable on a
      *  multi-session serve. (Explicit assignment: TS parameter properties break Node's strip-only
@@ -94,52 +144,34 @@ class Subscriber {
     constructor(session) {
         this.session = session;
     }
-    // Serialized snapshots cannot grow when a producer later mutates its event or tool result.
-    buffer = [];
+    queue = Effect.runSync(Queue.unbounded());
+    buffered = 0;
     bufferedBytes = 0;
-    // A QUEUE of waiters, not a single slot: concurrent next() calls are contract-legal (any wrapper
-    // may poll twice), and a single `wake` field would let the second await overwrite the first's
-    // resolver — hanging the first next() forever. Every wake flushes all waiters; each re-checks the
-    // buffer and re-queues if another consumer won the event.
-    wakes = [];
-    closed = false;
-    flush() {
-        const wakes = this.wakes;
-        this.wakes = [];
-        for (const wake of wakes)
-            wake();
-    }
+    ended = false;
     push(event) {
-        if (this.closed)
+        if (this.ended)
             return;
         const json = JSON.stringify(event);
         const bytes = Buffer.byteLength(json);
-        if (this.buffer.length >= SUBSCRIBER_BUFFER_CAP || this.bufferedBytes + bytes > SUBSCRIBER_BUFFER_BYTES) {
+        if (this.buffered >= SUBSCRIBER_BUFFER_CAP || this.bufferedBytes + bytes > SUBSCRIBER_BUFFER_BYTES) {
             log.warn(`[fastagent] session-control subscriber for session "${this.session}" exceeded its buffer limit (${SUBSCRIBER_BUFFER_CAP} events / ${SUBSCRIBER_BUFFER_BYTES} bytes; ${this.bufferedBytes} bytes queued, ${bytes} incoming); its stream ends after draining the backlog, then the client resyncs via entries()`);
             this.close();
             return;
         }
-        this.buffer.push({ json, bytes });
+        Queue.offerUnsafe(this.queue, { json, bytes });
+        this.buffered++;
         this.bufferedBytes += bytes;
-        this.flush();
     }
     close() {
-        this.closed = true;
-        this.flush();
+        this.ended = true;
+        Queue.endUnsafe(this.queue);
     }
-    async next() {
-        while (true) {
-            const item = this.buffer.shift();
-            if (item) {
-                this.bufferedBytes -= item.bytes;
-                return { done: false, value: JSON.parse(item.json) };
-            }
-            if (this.closed)
-                return { done: true, value: undefined };
-            await new Promise((resolve) => {
-                this.wakes.push(resolve);
-            });
-        }
+    next() {
+        return Effect.runPromise(Queue.take(this.queue).pipe(Effect.map((item) => {
+            this.buffered--;
+            this.bufferedBytes -= item.bytes;
+            return { done: false, value: JSON.parse(item.json) };
+        }), Effect.catchTag("Done", () => Effect.succeed({ done: true, value: undefined }))));
     }
 }
 /**
@@ -183,7 +215,7 @@ export function createPiSessionControl(options) {
     };
     const observer = (session, event, run) => {
         if (event.type === "run_started" && event.runId) {
-            active.set(session, { runId: event.runId, controls: run, pending: { steering: 0, followUp: 0 } });
+            active.set(session, { runId: event.runId, controls: run, pending: { steering: [], followUp: [] } });
         }
         else if (event.type === "run_settled") {
             active.delete(session);
@@ -194,6 +226,22 @@ export function createPiSessionControl(options) {
                 entry.pending = event.data;
         }
         fanOut(session, event);
+        if (event.type === "run_settled")
+            publishUsage(session);
+    };
+    /**
+     * Report `usage` as the record now reads it: after a run (a new answer) and after a compaction (the context it
+     * described is gone). Read after the fact, so it follows the event that caused it.
+     */
+    const publishUsage = (session) => {
+        // Every serve runs a hub, most with nobody attached (a chat channel): reading the whole record each turn for an
+        // empty audience would cost a full parse per turn, growing with the conversation.
+        if (!subscribers.get(session)?.size && !options.tap)
+            return;
+        reads.state(session).then(({ usage }) => {
+            if (usage)
+                emitOwn(session, { type: "state_changed", timestamp: Date.now(), data: { usage } });
+        }, (error) => log.warn(`[fastagent] session ${session}: usage not published: ${String(error)}`));
     };
     // The reads, plus the two sessionless declarations. Bound onto a handle below.
     const reads = {
@@ -219,7 +267,7 @@ export function createPiSessionControl(options) {
                 // `state().availableThinkingLevels` — a list here could only answer for one model.
                 ...(b ? { allowedModels: listModels(b.models) } : {}),
                 toolProgress: true, // tool_progress IS delivered (replace-semantics snapshots)
-                usage: false,
+                usage: true, // state().usage, and state_changed{usage} after each run and compaction
             };
         },
         async state(session) {
@@ -235,12 +283,16 @@ export function createPiSessionControl(options) {
             // `boundary_command_failed`. Here it is a server-side warn.
             const b = boundary;
             let settings;
-            if (opened && b) {
+            let usage;
+            if (opened) {
                 try {
-                    settings = resolveSessionSettings(activePath(opened), b.models, b.defaults);
+                    const path = activePath(opened);
+                    if (b)
+                        settings = resolveSessionSettings(path, b.models, b.defaults);
+                    usage = sessionUsage(path, opened, settings?.model.contextWindow);
                 }
                 catch (error) {
-                    log.warn(`[fastagent] session ${session}: settings unreadable (entry chain): ${String(error)}`);
+                    log.warn(`[fastagent] session ${session}: state unreadable (entry chain): ${String(error)}`);
                 }
             }
             const name = opened?.getSessionName();
@@ -255,7 +307,10 @@ export function createPiSessionControl(options) {
                         availableThinkingLevels: settings.availableThinkingLevels,
                     }
                     : {}),
-                pending: run ? { ...run.pending } : { steering: 0, followUp: 0 },
+                pending: run
+                    ? { steering: [...run.pending.steering], followUp: [...run.pending.followUp] }
+                    : { steering: [], followUp: [] },
+                ...(usage ? { usage } : {}),
                 ...(leafEntryId ? { leafEntryId } : {}),
             };
         },
@@ -300,16 +355,33 @@ export function createPiSessionControl(options) {
             return { entries, ...(leafEntryId ? { leafEntryId } : {}) };
         },
         events(session) {
-            // EVERY ITERATION IS A FRESH SUBSCRIPTION — the per-subscription state lives inside
-            // asyncIterator(), matching the remote client (one connection per iteration): two concurrent
-            // iterations each get the full stream, and one iteration's end does not poison the next.
-            // Registration happens on the FIRST next(), not at iterator creation: subscription semantics
-            // = you are subscribed while you iterate; an iterator obtained but never driven must not
-            // buffer. Teardown goes through Subscriber.close() so a `return()` on a QUIET stream
-            // resolves promptly instead of queueing behind a never-settling pull — without it every
-            // attach/detach against an idle session would leak a permanently registered subscriber.
+            // ONE CALL IS ONE SUBSCRIPTION, and `ready` is its boundary: the moment after which nothing emitted for this
+            // session can be missed (session.ts, SessionEventStream). A second iteration of the same stream would be a
+            // second subscription inheriting the first one's readiness — a guarantee it never earned — so it is refused
+            // rather than documented. Matching the remote client, which opens one connection per stream.
+            //
+            // Registration happens on the FIRST next(), not at iterator creation: subscription semantics = you are
+            // subscribed while you iterate; an iterator obtained but never driven must not buffer. Teardown goes through
+            // Subscriber.close() so a `return()` on a QUIET stream resolves promptly instead of queueing behind a
+            // never-settling pull — without it every attach/detach against an idle session would leak a permanently
+            // registered subscriber.
+            let registered;
+            let unestablished;
+            const ready = new Promise((resolve, reject) => {
+                registered = resolve;
+                unestablished = reject;
+            });
+            // An awaiter gets the rejection; a consumer that only iterates would otherwise take an unhandled one for a
+            // cancellation it performed itself.
+            ready.catch(() => { });
+            let iterated = false;
             return {
+                ready,
                 [Symbol.asyncIterator]() {
+                    if (iterated) {
+                        throw new Error("session events: this stream is one subscription — call events() again for another");
+                    }
+                    iterated = true;
                     let sub;
                     // `finished` is its own state: `sub === undefined` alone would conflate "not yet
                     // registered" with "terminated", and a post-done next() would silently REGISTER A FRESH
@@ -318,8 +390,12 @@ export function createPiSessionControl(options) {
                     let finished = false;
                     const cleanup = () => {
                         finished = true;
-                        if (!sub)
+                        if (!sub) {
+                            // Cancelled before it registered: `ready` has a promise it cannot keep, and hanging on it is the one
+                            // outcome a caller cannot diagnose. The remote client answers the same way.
+                            unestablished(new Error("session events: cancelled before the subscription was established"));
                             return;
+                        }
                         sub.close();
                         const set = subscribers.get(session);
                         if (set) {
@@ -341,6 +417,7 @@ export function createPiSessionControl(options) {
                                     subscribers.set(session, set);
                                 }
                                 set.add(sub);
+                                registered();
                             }
                             const result = await sub.next();
                             if (result.done)
@@ -386,9 +463,14 @@ export function createPiSessionControl(options) {
         ok: false,
         error: { code: BOUNDARY_COMMAND_FAILED_CODE, message: String(error), retryable: true },
     });
+    const runBoundary = (command) => Effect.runPromise(Effect.scoped(command).pipe(Effect.catchTag("SessionBusy", () => Effect.succeed(busy())), Effect.catchCause((cause) => Effect.succeed(failed(portError(cause))))));
     /** steer / follow_up / abort — the run actions. They reach the LIVE run through the controls
      *  registered with `run_started`; nothing durable is written. */
-    const runAction = async (session, action) => {
+    const runAction = (session, action) => Effect.runPromise(Effect.gen(function* () {
+        // pi dequeues a queued prompt by matching its text when it enters the conversation, and skips an empty one
+        // (`_handleAgentEvent`): an image-only prompt would sit in `pending` for the whole run and then read as dropped.
+        if ((action.type === "steer" || action.type === "follow_up") && action.prompt.text === "")
+            return invalid(`${action.type} needs non-empty text: a queued prompt is reported by its text`);
         const run = active.get(session);
         if (!run) {
             // Run/compaction symmetry: an in-flight compaction is a model call too, and `abort` is its
@@ -425,23 +507,17 @@ export function createPiSessionControl(options) {
                 },
             };
         }
-        try {
-            if (action.type === "steer")
-                await run.controls.steer(action.prompt);
-            else if (action.type === "follow_up")
-                await run.controls.followUp(action.prompt);
-            else
-                await run.controls.abort();
-        }
-        catch (error) {
-            // The run raced us to settlement, failed setup, or the engine refused: still pre-acceptance
-            // (nothing was queued), distinct from "no run existed". retryable: false for the same reason —
-            // the run is gone; consult state() before calling again.
-            return { ok: false, error: { code: RUN_COMMAND_FAILED_CODE, message: String(error), retryable: false } };
-        }
-        // Accepted: joined (or stopped) THIS run. The outcome arrives as run_settled.
+        const controls = run.controls;
+        yield* port(() => action.type === "steer"
+            ? controls.steer(action.prompt)
+            : action.type === "follow_up"
+                ? controls.followUp(action.prompt)
+                : controls.abort());
         return { ok: true, runId: run.runId };
-    };
+    }).pipe(Effect.catchCause((cause) => Effect.succeed({
+        ok: false,
+        error: { code: RUN_COMMAND_FAILED_CODE, message: String(portError(cause)), retryable: false },
+    }))));
     /**
      * {@link Session.update} — validate the whole patch, take the lease once, hand the writes to the
      * store, report what landed.
@@ -450,7 +526,7 @@ export function createPiSessionControl(options) {
      * behind. What a value MEANS is decided here (a model spec against the registry, a level against
      * the model it lands on); how a record takes it is the store's.
      */
-    const updateOf = async (session, patch) => {
+    const updateOf = (session, patch) => runBoundary(Effect.gen(function* () {
         // Keys, not values: a field this runtime does not know must not be silently skipped — that is a
         // client typo, or a newer client talking to an older serve, and both need to hear about it.
         const named = Object.keys(patch);
@@ -483,7 +559,7 @@ export function createPiSessionControl(options) {
         // Sessions are created by invoke or copied by fork, never minted by an update: an unknown id is
         // rejected, not turned into a ghost record. (Read-only handle — the WRITE one is opened under
         // the lease below, and this one is discarded.)
-        const existing = await sessions.openIfExists(session);
+        const existing = yield* port(() => sessions.openIfExists(session));
         if (!existing)
             return noSuchSession(session);
         if (patch.leafEntryId !== undefined) {
@@ -520,30 +596,18 @@ export function createPiSessionControl(options) {
                 return invalid(`thinking level "${patch.thinkingLevel}" is not supported by ${target.provider}/${target.id} (allowed: ${levels.join(", ")})`);
             }
         }
-        // The control plane's writes take the same lease as every run — a write must never race one
-        // (design §9).
-        const release = b.lease.tryAcquire(session);
-        if (!release)
-            return busy();
-        let applied;
-        try {
-            // HOW a record takes a property — order, the leaf pointer, the name pi rewrites — is the
-            // store's to know. This asks for the writes and is told what landed.
-            applied = await sessions.applyProperties(session, {
+        // Release before publishing state_changed: an observer may immediately issue another command.
+        const applied = yield* Effect.scoped(Effect.gen(function* () {
+            yield* acquireSessionLease(b.lease, session);
+            // portJoin, not port: the lease is held for the duration of this write, so an interrupted
+            // fiber must not release it while the store is still writing (effect-port.ts, rule 1).
+            return yield* portJoin(() => sessions.applyProperties(session, {
                 ...(patch.name !== undefined ? { name: patch.name } : {}),
                 ...(model ? { model: { provider: model.provider, id: model.id } } : {}),
                 ...(patch.thinkingLevel !== undefined ? { thinkingLevel: patch.thinkingLevel } : {}),
                 ...(patch.leafEntryId !== undefined ? { leafEntryId: patch.leafEntryId } : {}),
-            });
-        }
-        catch (error) {
-            // Opening the record failed — nothing was written; the same patch may succeed on retry. The
-            // lease is freed by the `finally` on the way out, once.
-            return failed(error);
-        }
-        finally {
-            release();
-        }
+            }));
+        }));
         if (!applied)
             return noSuchSession(session); // vanished in the window: same condition, same code
         if (applied.landed.length > 0) {
@@ -562,6 +626,15 @@ export function createPiSessionControl(options) {
                     log.warn(`[fastagent] session ${session}: updated, settings unresolvable: ${String(error)}`);
                 }
             }
+            // A moved head reads a different newest answer, and another model has another window: the event carries
+            // the usage the session now has, and carries none when it has none. Read back through `state()`, the one
+            // derivation; a read failure only costs the field, since the write has already landed.
+            const usage = applied.landed.some((f) => f === "leafEntryId" || f === "model")
+                ? yield* port(() => reads.state(session)).pipe(Effect.map((state) => state.usage), Effect.catchCause((cause) => Effect.sync(() => {
+                    log.warn(`[fastagent] session ${session}: updated, usage unreadable: ${String(portError(cause))}`);
+                    return undefined;
+                })))
+                : undefined;
             emitOwn(session, {
                 type: "state_changed",
                 timestamp: Date.now(),
@@ -571,6 +644,7 @@ export function createPiSessionControl(options) {
                         ? { model: `${settings.model.provider}/${settings.model.id}`, thinkingLevel: settings.thinkingLevel }
                         : {}),
                     ...(applied.landed.includes("name") && applied.name ? { name: applied.name } : {}),
+                    ...(usage ? { usage } : {}),
                 },
             });
         }
@@ -589,57 +663,47 @@ export function createPiSessionControl(options) {
                 };
         }
         return { ok: true };
-    };
-    /**
-     * ACCEPT-FAST compaction: a full model call (tens of seconds is normal), so holding the call open
-     * until it finishes would make acceptance = outcome — the one exception to §5.2, and what broke
-     * remote clients whose request timeouts are sized for control calls. This answers once the work is
-     * ADMITTED (lease held, session bound); the outcome travels as
-     * `compaction_finished{summary|error|aborted}`.
-     *
-     * Admission is everything cheap and local: binding the session (the ONE canonical resolution of
-     * overrides + auth) plus the compaction PREPARATION, a pure branch read. The boundary between
-     * "reject" and "the outcome travels as an event" sits where the work becomes asynchronous and
-     * expensive: the model call. "Nothing to compact" is therefore a pre-acceptance answer, never a
-     * finished{error} dressed as a failure — pi reports it as a throw from compact(), too late.
-     */
-    const compactOf = async (session, instructions) => {
-        const b = boundary;
-        if (!b)
-            return unsupported("compact()");
-        const existing = await sessions.openIfExists(session);
-        if (!existing)
-            return noSuchSession(session);
-        const release = b.lease.tryAcquire(session);
-        if (!release)
-            return busy();
-        let bound;
-        try {
-            bound = await b.sessionFactory(session);
-        }
-        catch (error) {
-            release();
-            return failed(error);
-        }
-        const teardown = () => {
-            try {
-                bound.dispose();
-            }
-            catch (error) {
-                log.warn(`[fastagent] compaction session teardown failed: ${String(error)}`);
-            }
-        };
-        try {
-            // The SAME settings pi will use inside compact(): asking with different thresholds would
-            // either reject a compaction pi would have run, or admit one it refuses — and its refusal
-            // arrives too late to be a pre-acceptance answer.
-            const path = bound.sessionManager.getBranch();
-            if (!hasCompactableHistory(path, bound.settingsManager.getCompactionSettings().keepRecentTokens)) {
-                teardown();
-                release();
-                // A no-op, not a failure — its OWN code (the NO_ACTIVE_RUN pattern): a client must
-                // machine-distinguish "give up" from "call again once the session grows", and branching on
-                // message prose is forbidden by contract.
+    }));
+    /** Admission waits for binding and pi's own admission (its cut point), not the model call.
+     *  Its execution scope survives the control response; completion is published only after releasing the shared
+     *  lease. */
+    const compactOf = (session, instructions) => {
+        const admitted = Deferred.makeUnsafe();
+        let accepted = false;
+        let aborted = false;
+        const work = Effect.scoped(Effect.gen(function* () {
+            const b = boundary;
+            if (!b)
+                return unsupported("compact()");
+            const existing = yield* port(() => sessions.openIfExists(session));
+            if (!existing)
+                return noSuchSession(session);
+            yield* acquireSessionLease(b.lease, session);
+            const bound = yield* acquireSession(b.sessionFactory, session);
+            yield* Effect.acquireRelease(Effect.try({
+                try: () => bound.subscribe((event) => {
+                    if (event.type !== "summarization_retry_scheduled")
+                        return;
+                    log.warn(`[fastagent] compaction retry ${event.attempt}/${event.maxAttempts} in ${event.delayMs}ms (session ${session}): ${event.errorMessage}`);
+                    emitOwn(session, toRetryScheduledEvent(event));
+                }),
+                catch: (error) => new PortFailure(error),
+            }), (unsubscribe) => portCleanup("unsubscribe", unsubscribe));
+            // Admission is pi's own decision, observed rather than predicted: a prediction has to track pi's private
+            // cut-point rules release by release. It settles before the model call.
+            const compaction = startCompaction(bound, instructions, () => {
+                accepted = true;
+                compacting.set(session, {
+                    abort: () => {
+                        aborted = true;
+                        bound.abortCompaction();
+                    },
+                });
+                emitOwn(session, { type: "compaction_started", timestamp: Date.now(), data: {} });
+                Deferred.doneUnsafe(admitted, Effect.succeed({ ok: true }));
+            });
+            const admission = yield* portAbort("compact admission", () => compaction.admission, () => bound.abortCompaction());
+            if (admission === "nothing_to_compact") {
                 return {
                     ok: false,
                     error: {
@@ -649,54 +713,34 @@ export function createPiSessionControl(options) {
                     },
                 };
             }
-        }
-        catch (error) {
-            teardown();
-            release();
-            return failed(error);
-        }
-        // Pi creates the abort controller after an await and emits compaction_start immediately after.
-        // Retain early cancellation until that event; there is no time limit on session startup.
-        let aborted = false;
-        compacting.set(session, {
-            abort: () => {
-                aborted = true;
-                bound.abortCompaction();
-            },
-        });
-        emitOwn(session, { type: "compaction_started", timestamp: Date.now(), data: {} });
-        void (async () => {
-            let outcome;
-            // Retries are otherwise invisible between compaction_started and _finished — surface each
-            // backoff so a long gap is diagnosable (not confusable with a hang): as a session event for
-            // attached observers, as a warn for server logs.
-            const unsub = bound.subscribe((event) => {
-                if (event.type === "compaction_start" && event.reason === "manual" && aborted)
-                    bound.abortCompaction();
-                if (event.type !== "summarization_retry_scheduled")
-                    return;
-                log.warn(`[fastagent] compaction retry ${event.attempt}/${event.maxAttempts} in ${event.delayMs}ms (session ${session}): ${event.errorMessage}`);
-                emitOwn(session, toRetryScheduledEvent(event));
-            });
-            try {
-                const done = await bound.compact(instructions);
-                outcome = { summary: done.summary };
+            // Any other error pi raises before admission. A served session has no known trigger: it always binds a
+            // model, and pi swallows a credential failure here and meets it at the model call (compaction_finished).
+            // NOT retryable all the same: it is pi's decision on this session, not a transport or lease fault that
+            // clears on its own, so repeating the call would meet it again.
+            if (admission !== "admitted") {
+                return {
+                    ok: false,
+                    error: { code: BOUNDARY_COMMAND_FAILED_CODE, message: String(admission.refused), retryable: false },
+                };
             }
-            catch (error) {
-                // A deliberate stop is not a failure — run/compaction symmetry with run_settled{aborted}:
-                // the intent is the classification, same discipline as run abort attribution (a racing real
-                // failure still reads as aborted).
-                outcome = aborted ? { aborted: true } : { error: String(error) };
+            const done = yield* portAbort("compact", () => compaction.done, () => bound.abortCompaction());
+            return { summary: done.summary };
+        })).pipe(Effect.catchTag("SessionBusy", () => Effect.succeed(busy())), Effect.catchCause((cause) => Effect.succeed(failed(portError(cause)))), Effect.tap((result) => Effect.sync(() => {
+            if (accepted) {
+                compacting.delete(session);
+                emitOwn(session, {
+                    type: "compaction_finished",
+                    timestamp: Date.now(),
+                    data: "summary" in result ? result : aborted ? { aborted: true } : { error: result.error.message },
+                });
+                if ("summary" in result)
+                    publishUsage(session);
             }
-            unsub();
-            teardown();
-            // Release BEFORE emitting finished: a watcher seeing finished may act next — "finished ⇒ the
-            // lease is free and status is no longer compacting" must hold.
-            compacting.delete(session);
-            release();
-            emitOwn(session, { type: "compaction_finished", timestamp: Date.now(), data: outcome });
-        })();
-        return { ok: true };
+            Deferred.doneUnsafe(admitted, Effect.succeed("summary" in result ? { ok: true } : result));
+        })));
+        // The admitted operation, rather than the request waiting on this Deferred, owns the scope.
+        Effect.runFork(work);
+        return Effect.runPromise(Deferred.await(admitted));
     };
     /**
      * Copy a history into a new session. IDEMPOTENT by construction: `into` is the caller's id, so a
@@ -705,7 +749,7 @@ export function createPiSessionControl(options) {
      * safe rather than merely quiet: the same `into` naming a session that came from somewhere else is
      * a rejection, not an overwrite.
      */
-    const forkOf = async (options) => {
+    const forkOf = (options) => runBoundary(Effect.gen(function* () {
         const { from, at, into } = options;
         /** WHICH fork this is: source + branch point. Two forks of one session at different entries are
          *  different requests, so a retry of one must not be answered by the other. */
@@ -719,7 +763,7 @@ export function createPiSessionControl(options) {
         if (!isAddressableSession(into)) {
             return invalid(`${JSON.stringify(into)} cannot be a session id — the control plane could not address it`);
         }
-        const source = await sessions.openIfExists(from);
+        const source = yield* port(() => sessions.openIfExists(from));
         if (!source)
             return noSuchSession(from);
         // The entry predicate is the one `entries()` publishes by, so "everything published is forkable"
@@ -728,7 +772,7 @@ export function createPiSessionControl(options) {
         if (!entry || !isNavigable(entry)) {
             return invalid(`entry "${at}" is not a forkable position in session "${from}" — entries() lists the ids`);
         }
-        const existingTarget = await sessions.openIfExists(into);
+        const existingTarget = yield* port(() => sessions.openIfExists(into));
         if (existingTarget) {
             // Already forked from HERE: the request already happened, so answering ok is the truth rather
             // than a convenience. Anything else under that id is a different history, and saying yes would
@@ -742,60 +786,33 @@ export function createPiSessionControl(options) {
         // `into`, or a second fork from a DIFFERENT source (whose source lease is another key entirely),
         // otherwise lands between that check and this write. tryAcquire never blocks, so taking two
         // cannot deadlock.
-        const release = b.lease.tryAcquire(from);
-        if (!release)
-            return busy();
-        const releaseInto = b.lease.tryAcquire(into);
-        if (!releaseInto) {
-            release();
-            return busy();
-        }
-        try {
-            // Holding the lease is not the same as having looked: re-asked under it, as the update path
-            // re-opens its record, so an id taken inside the window is a payload error rather than a
-            // store failure the client would read as retryable.
-            const raced = await sessions.openIfExists(into);
-            if (raced) {
-                return forkProvenance(raced) === provenance
-                    ? { ok: true }
-                    : invalid(`session "${into}" already exists with a different history — fork mints nothing over it`);
-            }
-            await sessions.fork(from, at, into, provenance);
-        }
-        catch (error) {
-            // Nothing durable landed: the copy is staged and published by rename.
-            return failed(error);
-        }
-        finally {
-            releaseInto();
-            release();
+        yield* acquireSessionLease(b.lease, from);
+        yield* acquireSessionLease(b.lease, into);
+        // Recheck under both leases: another creator may have taken the target since validation.
+        const raced = yield* port(() => sessions.openIfExists(into));
+        if (raced) {
+            return forkProvenance(raced) === provenance
+                ? { ok: true }
+                : invalid(`session "${into}" already exists with a different history — fork mints nothing over it`);
         }
+        // portJoin: both leases are held for this write and must outlive it (effect-port.ts, rule 1).
+        yield* portJoin(() => sessions.fork(from, at, into, provenance));
         return { ok: true };
-    };
-    const deleteOf = async (session) => {
+    }));
+    const deleteOf = (session) => runBoundary(Effect.gen(function* () {
         const b = boundary;
         if (!b)
             return unsupported("delete()");
-        const existing = await sessions.openIfExists(session);
+        const existing = yield* port(() => sessions.openIfExists(session));
         if (!existing)
             return noSuchSession(session);
-        // The same lease as a run: a delete racing one would pull the record out from under it.
-        const release = b.lease.tryAcquire(session);
-        if (!release)
-            return busy();
-        try {
-            // It was there before the lease and is gone now — the same real condition the check above
-            // answers, so the same code.
-            if (!(await sessions.delete(session)))
-                return noSuchSession(session);
-        }
-        catch (error) {
-            // A delete that throws left the record in place.
-            return failed(error);
-        }
-        finally {
-            release();
-        }
+        const removed = yield* Effect.scoped(Effect.gen(function* () {
+            yield* acquireSessionLease(b.lease, session);
+            // portJoin: the lease must outlive the removal (effect-port.ts, rule 1).
+            return yield* portJoin(() => sessions.delete(session));
+        }));
+        if (!removed)
+            return noSuchSession(session);
         // The session is gone, so its live streams have nothing left to report: end them rather than
         // hold connections open on a record that no longer exists. A client's reconnect then reads an
         // empty `state()`, which is the truth.
@@ -803,7 +820,7 @@ export function createPiSessionControl(options) {
             sub.close();
         subscribers.delete(session);
         return { ok: true };
-    };
+    }));
     const control = {
         capabilities: reads.capabilities,
         commands: reads.commands,