@code-yeongyu/senpi 2026.10.26-1 → 2026.10.26-2

package/dist/modes/rpc/compact-spool-storage.js

@@ -0,0 +1,162 @@
+import { join } from "node:path";
+import { createSpoolDir, removeSpoolDir } from "./compact-spool-dir.js";
+import { CompactStorageReadError, describeCause, } from "./compact-storage-io.js";
+/**
+ * The spool file path of compact current-state storage (senpi#4272, R3.C6.4): one serial
+ * asynchronous job chain, the private epoch directory, spool file writes, reads and reclamation,
+ * and the failure ledger. `CompactContentStore` adds leaf ownership and spilling on top.
+ */
+export const RECLAIM_WORK_ALLOWANCE_BYTES = 1024 * 1024;
+const RECLAIM_RETRY_DELAYS_MS = [100, 400, 1_600, 6_400, 25_600];
+const FAILURE_HISTORY = 32;
+export class CompactSpoolStorage {
+    constructor(dir, io) {
+        this.failures = [];
+        this.nextFile = 1;
+        this.chain = Promise.resolve();
+        this.queued = 0;
+        this.spillQueued = false;
+        this.halted = false;
+        this.retired = false;
+        this.pendingIoCopyBytes = 0;
+        this.spillBytesWritten = 0;
+        this.reclaimDebtBytes = 0;
+        this.dir = dir;
+        this.io = io;
+    }
+    /** Resolves once every queued storage job, including the ones they queued, has completed. */
+    async idle() {
+        while (this.queued > 0)
+            await this.chain;
+    }
+    /**
+     * Invalidates spilling, joins owned I/O, then removes the epoch directory only when this store
+     * created it and it still passes the ownership checks; otherwise rejects with `CompactSpoolRefusedError`.
+     */
+    async retire() {
+        this.retired = true;
+        await this.idle();
+        const token = this.spoolToken;
+        this.spoolToken = undefined;
+        if (token !== undefined)
+            await removeSpoolDir(this.dir, token);
+    }
+    /** Reads a committed file and rejects a missing, unreadable or short one. */
+    async readFile(path, bytes, operation) {
+        let data;
+        try {
+            data = await this.io.readFile(path);
+        }
+        catch (cause) {
+            throw this.readFailure(operation, path, cause);
+        }
+        if (data.byteLength !== bytes) {
+            throw this.readFailure(operation, path, new Error(`expected ${bytes} bytes, found ${data.byteLength}`));
+        }
+        return data;
+    }
+    /** Writes one new spool file; undefined means the write failed and was reported (a spill write also halts spilling). */
+    async writeFile(data, operation, retainedInMemoryBytes) {
+        const path = await this.ensureDir(retainedInMemoryBytes);
+        if (path === undefined)
+            return undefined;
+        const file = join(path, `${operation === "spill_write" ? "leaf" : "page"}-${this.nextFile++}.bin`);
+        this.pendingIoCopyBytes += data.byteLength;
+        try {
+            await this.io.writeFile(file, data);
+            this.spillBytesWritten += data.byteLength;
+            return file;
+        }
+        catch (cause) {
+            try {
+                this.fail(operation, file, cause, retainedInMemoryBytes);
+            }
+            finally {
+                this.discard(file, data.byteLength);
+            }
+            return undefined;
+        }
+        finally {
+            this.pendingIoCopyBytes -= data.byteLength;
+        }
+    }
+    /**
+     * An unreferenced (or partially written) spool file: reclamation debt until its unlink completes or
+     * finds it gone. Files dropped after retirement started belong to the directory retirement removes.
+     */
+    discard(path, bytes) {
+        if (this.retired)
+            return;
+        this.reclaimDebtBytes += bytes;
+        this.enqueue("reclaim", () => this.reclaim(path, bytes, 0));
+    }
+    /** A failed unlink keeps its debt and is retried with bounded backoff outside the job chain. */
+    async reclaim(path, bytes, attempt) {
+        try {
+            await this.io.unlink(path);
+        }
+        catch (cause) {
+            if (cause.code !== "ENOENT") {
+                this.fail("reclaim", path, cause, 0);
+                const delay = RECLAIM_RETRY_DELAYS_MS[attempt];
+                if (delay !== undefined) {
+                    setTimeout(() => {
+                        if (this.retired)
+                            this.reclaimDebtBytes -= bytes;
+                        else
+                            this.enqueue("reclaim", () => this.reclaim(path, bytes, attempt + 1));
+                    }, delay).unref?.();
+                }
+                return;
+            }
+        }
+        this.reclaimDebtBytes -= bytes;
+        this.scheduleSpill();
+    }
+    get spillAllowed() {
+        return !this.halted && !this.retired;
+    }
+    /** True while a storage failure or unreclaimed debt above the work allowance holds spilling back. */
+    get spillStopped() {
+        return this.halted || this.reclaimDebtBytes > RECLAIM_WORK_ALLOWANCE_BYTES;
+    }
+    enqueue(operation, job) {
+        this.queued++;
+        this.chain = this.chain
+            .then(job)
+            .catch((cause) => {
+            if (operation === "spill_write")
+                this.spillQueued = false;
+            this.fail(operation, this.dir, cause, 0);
+        })
+            .finally(() => {
+            this.queued--;
+        });
+    }
+    /** Creates the private epoch directory once; a refusal or failure halts spilling and is reported. */
+    ensureDir(retained) {
+        this.dirReady ??= createSpoolDir(this.dir).then((token) => {
+            this.spoolToken = token;
+            return this.dir;
+        }, (cause) => {
+            this.fail("spool_create", this.dir, cause, retained);
+            return undefined;
+        });
+        return this.dirReady;
+    }
+    readFailure(operation, path, cause) {
+        this.fail(operation, path, cause, 0);
+        return new CompactStorageReadError(operation, path, cause);
+    }
+    fail(operation, path, cause, retained) {
+        if (operation === "spill_write" || operation === "spool_create")
+            this.halted = true;
+        this.record({ operation, path, cause: describeCause(cause), retainedInMemoryBytes: retained });
+    }
+    record(failure) {
+        this.failures.push(failure);
+        if (this.failures.length > FAILURE_HISTORY)
+            this.failures.shift();
+    }
+}
+//# sourceMappingURL=compact-spool-storage.js.map

package/dist/modes/rpc/compact-storage-io.d.ts

@@ -2,7 +2,7 @@
  * The asynchronous file seam of compact current-state storage (senpi#4272) and the failures it
  * reports. Every spool access goes through `CompactStorageIo`; nothing here blocks the host loop.
  */
-export type CompactStorageOperation = "spool_create" | "spill_write" | "leaf_read" | "reclaim";
+export type CompactStorageOperation = "spool_create" | "spill_write" | "page_write" | "leaf_read" | "page_read" | "reclaim";
 export interface CompactStorageFailure {
     readonly operation: CompactStorageOperation;
     readonly path: string;
@@ -17,6 +17,7 @@ export interface CompactStorageIo {
     unlink(path: string): Promise<void>;
 }
 export declare const nodeCompactStorageIo: CompactStorageIo;
+/** Never throws: a host-supplied cause that cannot be described must not abort the failure report. */
 export declare function describeCause(cause: unknown): string;
 /** Committed storage that can no longer be read: a real error, never empty content. */
 export declare class CompactStorageReadError extends Error {

package/dist/modes/rpc/compact-storage-io.js

@@ -4,8 +4,14 @@ export const nodeCompactStorageIo = {
     readFile: (path) => readFile(path),
     unlink: (path) => unlink(path),
 };
+/** Never throws: a host-supplied cause that cannot be described must not abort the failure report. */
 export function describeCause(cause) {
-    return cause instanceof Error ? cause.message : String(cause);
+    try {
+        return cause instanceof Error ? cause.message : String(cause);
+    }
+    catch {
+        return "unprintable failure cause";
+    }
 }
 /** Committed storage that can no longer be read: a real error, never empty content. */
 export class CompactStorageReadError extends Error {

package/dist/modes/rpc/compact-transition.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The typed transitions compact current state accepts (senpi#4272, R3.C6.4) and the typed
+ * rejection `CompactSessionState.accept` throws when one fails validation.
+ */
+export type CompactBlockKind = "text" | "thinking" | "tool_arguments";
+export type CompactPersistence = "pending" | "appended" | "failed";
+export interface BlockAddress {
+    readonly messageId: string;
+    readonly contentIndex: number;
+}
+export type CompactTransition = (BlockAddress & {
+    readonly type: "block_start";
+    readonly kind: CompactBlockKind;
+    readonly seed: string;
+    /**
+     * The whole seed when later deltas replay it from offset 0, or 0 when they continue after it. Partial
+     * coverage is refused: the uncovered seed tail would make every later delta overlap or leave a gap.
+     */
+    readonly coveredCodeUnits: number;
+}) | (BlockAddress & {
+    readonly type: "block_delta";
+    readonly offset: number;
+    readonly text: string;
+}) | (BlockAddress & {
+    readonly type: "block_replace";
+    readonly text: string;
+}) | {
+    readonly type: "message_status";
+    readonly messageId: string;
+    readonly persistence: CompactPersistence;
+} | {
+    readonly type: "message_remove";
+    readonly messageId: string;
+};
+type CompactRejection = "unknown_block" | "duplicate_block" | "invalid_coverage" | "non_contiguous" | "conflicting_overlap" | "unknown_message";
+export declare class CompactTransitionError extends Error {
+    readonly reason: CompactRejection;
+    constructor(reason: CompactRejection, detail: string);
+}
+export {};
+//# sourceMappingURL=compact-transition.d.ts.map

package/dist/modes/rpc/compact-transition.js

@@ -0,0 +1,12 @@
+/**
+ * The typed transitions compact current state accepts (senpi#4272, R3.C6.4) and the typed
+ * rejection `CompactSessionState.accept` throws when one fails validation.
+ */
+export class CompactTransitionError extends Error {
+    constructor(reason, detail) {
+        super(`compact transition rejected (${reason}): ${detail}`);
+        this.name = "CompactTransitionError";
+        this.reason = reason;
+    }
+}
+//# sourceMappingURL=compact-transition.js.map

package/dist/modes/rpc/connection-handler.d.ts

@@ -50,6 +50,8 @@ export interface RpcConnectionSink {
     writeRaw(chunk: string): void;
     /** Shared bindings accept correlated records synchronously, before JSONL buffering. */
     writeRecord?(record: object): void;
+    /** The internal structured lane (senpi#4272): seeded records and block controls, never a legacy destination. */
+    writeStructured?(record: object): void;
     waitForBackpressure(): Promise<void>;
     /** Tears the transport down once its event queue can no longer deliver (overflow, write failure). */
     close?(): void;

package/dist/modes/rpc/connection-handler.js

@@ -47,7 +47,7 @@ import { runAbort, runGetEffectStatus, runQueuedInputChange, runSetModel, runSet
 import { EffectLedger } from "./effect-ledger.js";
 import { EFFECT_LEDGER_CAPABILITY } from "./effect-record.js";
 import { createRpcEventOutputBuffer } from "./event-output-buffer.js";
-import { settleExtensionUiResponse } from "./extension-ui-response.js";
+import { answeredUiRequestId, settleExtensionUiResponse } from "./extension-ui-response.js";
 import { answerGetEntries } from "./get-entries-command.js";
 import { runHoldInput } from "./held-input-commands.js";
 import { HostSessionControl } from "./host-session-control.js";
@@ -64,6 +64,7 @@ import { runPauseForRun, runResumeForRun } from "./run-hold-commands.js";
 import { availableModelsData, interruptRunningTurn } from "./session-control-actions-data.js";
 import { SessionExtensionUiRequests, sessionDialogRequests } from "./session-extension-ui-requests.js";
 import { subscribeSessionRecords } from "./session-record-stream.js";
+import { subscribeStructuredSessionRecords } from "./structured-session-records.js";
 import { RpcSessionRelocation } from "./session-relocation.js";
 import { answerHostResponse, isHostResponse, relocationChannel, } from "./session-relocation-channel.js";
 export { buildRpcSessionState } from "./rpc-session-state.js";
@@ -190,6 +191,7 @@ export function createRpcConnectionHandler(runtimeHost, sink, options = {}) {
     // Set by the first command that asks this session for a turn; `set_retry_fallback` is refused after it.
     let turnRequested = false;
     let unsubscribe;
+    let unsubscribeStructured;
     let unsubscribeBackpressure;
     let unsubscribeLoadedSurfaces;
     let unsubscribeExtensionEvents;
@@ -762,6 +764,10 @@ export function createRpcConnectionHandler(runtimeHost, sink, options = {}) {
             unsubscribe = subscribeSessionRecords(session, outputEvent, (abortSource) => {
                 lastAbortSource = abortSource;
             });
+            unsubscribeStructured?.();
+            unsubscribeStructured = sink.writeStructured
+                ? subscribeStructuredSessionRecords(session, (record) => sink.writeStructured?.(tagSessionRecord(record)))
+                : undefined;
             unsubscribeBackpressure = session.agent.subscribe(async () => {
                 await waitForRpcBackpressure();
             });
@@ -1704,15 +1710,13 @@ export function createRpcConnectionHandler(runtimeHost, sink, options = {}) {
             parsed !== null &&
             "type" in parsed &&
             parsed.type === "extension_ui_response") {
-            if (!options.workerSecurityBridge &&
-                "id" in parsed &&
-                typeof parsed.id === "string" &&
-                grantRequests.has(parsed.id)) {
+            const requestId = answeredUiRequestId(parsed);
+            if (!options.workerSecurityBridge && requestId !== undefined && grantRequests.has(requestId)) {
                 const sender = options.clientInfo?.connectionId();
                 const capable = sender === undefined
                     ? clientCapabilities?.includes("grant_select") === true
                     : options.clientInfo?.hasCapability?.(sender, "grant_select") === true;
-                if (grantRequests.get(parsed.id) !== sender || !capable)
+                if (grantRequests.get(requestId) !== sender || !capable)
                     return;
             }
             const reply = settleExtensionUiResponse(parsed, {
@@ -1767,10 +1771,12 @@ export function createRpcConnectionHandler(runtimeHost, sink, options = {}) {
         pendingExtensionRequests.close();
         unsubscribeProviderAccountEvents();
         unsubscribe?.();
+        unsubscribeStructured?.();
         unsubscribeBackpressure?.();
         unsubscribeLoadedSurfaces?.();
         unsubscribeExtensionEvents?.();
         unsubscribe = undefined;
+        unsubscribeStructured = undefined;
         unsubscribeBackpressure = undefined;
         unsubscribeLoadedSurfaces = undefined;
         unsubscribeExtensionEvents = undefined;

package/dist/modes/rpc/host-ensure-start.js

@@ -16,7 +16,7 @@ import { keepOwnerPipe, OWNER_WATCH_FD } from "./host-lifecycle-launch.js";
 import { pollProtocolInfo } from "./host-readiness.js";
 import { initialHostEnvironment } from "./host-spawn-environment.js";
 import { hostLaunchProfile } from "./protocol-identity.js";
-import { createSocketSecret, socketSecretPath } from "./socket-transport.js";
+import { ensureSocketSecret, socketSecretPath } from "./socket-transport.js";
 import { relayPresenterBootstrap } from "./mcp-presenter-bootstrap.js";
 export const DEFAULT_READINESS_TIMEOUT_MS = 10_000;
 export { DEFAULT_STOP_TIMEOUT_MS };
@@ -38,9 +38,11 @@ export async function startHost(paths, socket, options, generation = 0) {
         reason,
     });
     // The settings file must exist before the supervisor reads it at boot, so it
-    // records the policy before the spawn instead of beside the pidfile.
+    // records the policy before the spawn instead of beside the pidfile. A valid public
+    // secret belongs to the endpoint, not to this start: clients that already read it
+    // derive the pipe name from it, so a start reuses it and never rotates it.
     if (process.platform === "win32")
-        await createSocketSecret(socketSecretPath(socket));
+        await ensureSocketSecret(socketSecretPath(socket));
     await writeHostSettings(paths, {
         socket,
         capabilities: PINNED_HOST_CLIENT_CAPABILITIES,

package/dist/modes/rpc/security-presentations.js

@@ -109,7 +109,8 @@ export class RpcSecurityPresentations {
         if (pending.connection !== connection ||
             (connection !== undefined && !this.fanout.connectionHas(connection, "grant_select")))
             return false;
-        state?.grants.delete(requestId);
+        // The entry stays until the worker reports the grant settled (settleGrant): a frame the worker
+        // refuses leaves the grant pending, and it must stay answerable only by its recipient.
         return true;
     }
     settleGrant(sessionId, requestId) {

package/dist/modes/rpc/session-binding.js

@@ -1,6 +1,7 @@
 import { bindToProviderScope, runWithProviderScope } from "@earendil-works/pi-ai/node/provider-scope";
 import { createRpcConnectionHandler, } from "./connection-handler.js";
 import { createToolAttributionSpans } from "./session-attribution.js";
+import { structuredLaneEnabled } from "./structured-session-records.js";
 /**
  * Creates the extension UI bridge and subscriptions within the entry's provider
  * scope. The classic handler remains the single source of command semantics.
@@ -54,8 +55,17 @@ export async function createRpcSessionBinding(sessionId, entry, writer, requestC
                 return dropAfterClose();
             writeInScope(record);
         };
+        const writeStructuredInScope = bindToProviderScope((record) => writer.structuredLanes.accept(sessionId, record));
         const taggedSink = {
             writeRecord,
+            ...(structuredLaneEnabled()
+                ? {
+                    writeStructured: (record) => {
+                        if (entry.scope.state !== "closed")
+                            writeStructuredInScope(record);
+                    },
+                }
+                : {}),
             // A late raw reply after the scope closed is dropped like any record (senpi#2871); while the scope is
             // open, records arrive only through writeRecord, so a raw write is a wiring bug.
             writeRaw: () => {

package/dist/modes/rpc/session-event-writer.d.ts

@@ -2,6 +2,7 @@ import type { ExtensionUIContext, SessionKind } from "../../core/extensions/type
 import { type McpFormBinding } from "../../core/mcp-form-types.ts";
 import { McpPresenterAuthority, type McpPresenterConnection } from "./mcp-presenter-authority.ts";
 import type { SecurityNoticeSnapshot, SecurityNoticeState } from "../../core/security-notices.ts";
+import { SessionStructuredLanes } from "./session-structured-lanes.ts";
 import { type MediaPersister } from "./media-placeholders.ts";
 import type { RpcHostLifecycleEvent, RpcOpenQueuedEvent, RpcSessionClosedEvent, RpcSessionClosedReason, RpcSessionParkedEvent } from "./rpc-types.ts";
 import { type SessionEventWriterConnection } from "./session-event-fanout.ts";
@@ -23,6 +24,7 @@ export declare const MAX_SHARED_STDIO_QUEUE_RECORDS = 4096;
  * scheduling boundary and violate D9.
  */
 export declare class SessionEventWriter {
+    readonly structuredLanes: SessionStructuredLanes;
     private presenterAuthority?;
     private readonly presenterConnections;
     private readonly presenterBindings;

package/dist/modes/rpc/session-event-writer.js

@@ -3,6 +3,7 @@ import { bindPrivateMcpForms } from "../../core/mcp-form-types.js";
 import { McpPresenterAuthority } from "./mcp-presenter-authority.js";
 import { MEDIA_PLACEHOLDERS_CAPABILITY } from "./custom-capability.js";
 import { normalizeJsonValue } from "./json-normal-value.js";
+import { SessionStructuredLanes } from "./session-structured-lanes.js";
 import { serializeJsonLine } from "./jsonl.js";
 import { omitNormalInlineMedia } from "./media-placeholders.js";
 import { RpcSecurityPresentations } from "./security-presentations.js";
@@ -141,6 +142,7 @@ export class SessionEventWriter {
         return this.reservedCloseBytes;
     }
     constructor(writeRaw, waitOrSchedule, scheduleFlush) {
+        this.structuredLanes = new SessionStructuredLanes();
         this.presenterConnections = new Map();
         this.presenterBindings = new Map();
         this.records = new SessionRecordAccounting();

package/dist/modes/rpc/session-record-stream.d.ts

@@ -7,7 +7,7 @@
  * reads the same records from either.
  */
 import type { AgentAbortSource } from "../../core/agent-abort-provenance.ts";
-import type { AgentSession } from "../../core/agent-session.ts";
-/** Subscribes `output` to the session's records; returns the unsubscribe. */
-export declare function subscribeSessionRecords(session: AgentSession, output: (record: object) => void, onAbortSource?: (source: AgentAbortSource) => void): () => void;
+import type { AgentSession, AgentSessionEventListener } from "../../core/agent-session.ts";
+/** Subscribes `output` to the session's records (from `source`, by default `session.subscribe`); returns the unsubscribe. */
+export declare function subscribeSessionRecords(session: AgentSession, output: (record: object) => void, onAbortSource?: (source: AgentAbortSource) => void, source?: (listener: AgentSessionEventListener) => () => void): () => void;
 //# sourceMappingURL=session-record-stream.d.ts.map

package/dist/modes/rpc/session-record-stream.js

@@ -1,10 +1,10 @@
 import { clientFacingIdentity } from "./client-admission-record.js";
 import { ClientAdmissions } from "./client-admissions.js";
 import { ClientMessageEvents } from "./client-message-events.js";
-/** Subscribes `output` to the session's records; returns the unsubscribe. */
-export function subscribeSessionRecords(session, output, onAbortSource = () => { }) {
+/** Subscribes `output` to the session's records (from `source`, by default `session.subscribe`); returns the unsubscribe. */
+export function subscribeSessionRecords(session, output, onAbortSource = () => { }, source = (listener) => session.subscribe(listener)) {
     const correlatedEvents = new ClientMessageEvents(output, () => ClientAdmissions.forSession(session).hasIdentities);
-    return session.subscribe((event) => {
+    return source((event) => {
         if (event.type === "session_lifecycle") {
             // The connection adds the routing handle; classic stdio has no envelope.
             const { sessionId: _sessionId, ...record } = event;

package/dist/modes/rpc/session-structured-lanes.d.ts

@@ -0,0 +1,12 @@
+type StructuredReceiver = (record: object) => void;
+/**
+ * Per-session receivers of the internal structured lane (senpi#4272): the host-side owner of seeded records and
+ * block controls (S03/S04) registers here. Legacy sockets, stdout and the replay snapshot never read it.
+ */
+export declare class SessionStructuredLanes {
+    private readonly receivers;
+    observe(sessionId: string, receiver: StructuredReceiver): () => void;
+    accept(sessionId: string, record: object): void;
+}
+export {};
+//# sourceMappingURL=session-structured-lanes.d.ts.map

package/dist/modes/rpc/session-structured-lanes.js

@@ -0,0 +1,24 @@
+/**
+ * Per-session receivers of the internal structured lane (senpi#4272): the host-side owner of seeded records and
+ * block controls (S03/S04) registers here. Legacy sockets, stdout and the replay snapshot never read it.
+ */
+export class SessionStructuredLanes {
+    constructor() {
+        this.receivers = new Map();
+    }
+    observe(sessionId, receiver) {
+        const receivers = this.receivers.get(sessionId) ?? new Set();
+        receivers.add(receiver);
+        this.receivers.set(sessionId, receivers);
+        return () => {
+            receivers.delete(receiver);
+            if (receivers.size === 0 && this.receivers.get(sessionId) === receivers)
+                this.receivers.delete(sessionId);
+        };
+    }
+    accept(sessionId, record) {
+        for (const receiver of [...(this.receivers.get(sessionId) ?? [])])
+            receiver(record);
+    }
+}
+//# sourceMappingURL=session-structured-lanes.js.map

package/dist/modes/rpc/session-worker-client.js

@@ -5,6 +5,7 @@ import { ownProcessStartedAtMs } from "../../core/extensions/builtin/terminal/pr
 import { isSecurityNoticeState } from "../../core/security-notices.js";
 import { createWebViewBroker } from "../../core/webview/webview-broker.js";
 import { roleConnection } from "./connection-roles.js";
+import { answeredUiRequestId } from "./extension-ui-response.js";
 import { subscriptionLimits } from "../../core/subscription-limits/limit-store.js";
 import { SessionWorkerRequests } from "./session-worker-requests.js";
 import { acknowledge, acknowledgeGrant } from "./session-worker-signals.js";
@@ -125,11 +126,11 @@ export class SessionWorkerClient {
                 if (writer.handleMcpForm(command))
                     return;
                 const connection = writer.currentConnection();
-                if ("type" in command &&
-                    command.type === "extension_ui_response" &&
-                    "id" in command &&
-                    typeof command.id === "string" &&
-                    writer.acceptWorkerGrantResponse(sessionId, command.id, connection) === false)
+                const grantAnswer = "type" in command && command.type === "extension_ui_response"
+                    ? answeredUiRequestId(command)
+                    : undefined;
+                if (grantAnswer !== undefined &&
+                    writer.acceptWorkerGrantResponse(sessionId, grantAnswer, connection) === false)
                     return;
                 await this.request({
                     type: "command",

package/dist/modes/rpc/structured-session-records.d.ts

@@ -0,0 +1,12 @@
+import type { AgentSession } from "../../core/agent-session.ts";
+/**
+ * The engine-socket compact-updates rollout flag (`<brand>_ENGINE_SOCKET_COMPACT_UPDATES`), explicit-true only.
+ * Off, no session holds a structured subscription and every destination keeps its existing bytes.
+ */
+export declare function structuredLaneEnabled(): boolean;
+/**
+ * The session's internal structured lane, correlated like its legacy records: seeded `toJsonEvent` projections of
+ * every session event plus the three block controls, in session order. Never a legacy destination.
+ */
+export declare function subscribeStructuredSessionRecords(session: AgentSession, output: (record: object) => void): () => void;
+//# sourceMappingURL=structured-session-records.d.ts.map

package/dist/modes/rpc/structured-session-records.js

@@ -0,0 +1,88 @@
+import { getAssistantCapture } from "@earendil-works/pi-ai";
+import { envValue } from "../../core/brand.js";
+import { toJsonEvent } from "../json-event.js";
+import { subscribeSessionRecords } from "./session-record-stream.js";
+/**
+ * The engine-socket compact-updates rollout flag (`<brand>_ENGINE_SOCKET_COMPACT_UPDATES`), explicit-true only.
+ * Off, no session holds a structured subscription and every destination keeps its existing bytes.
+ */
+export function structuredLaneEnabled() {
+    const value = envValue("ENGINE_SOCKET_COMPACT_UPDATES");
+    return value === "1" || value === "true";
+}
+const SEEDS = { blockSeeds: 1 };
+/**
+ * Admits a block's records only after its own seed or insert reached this subscriber, so a subscriber that attached
+ * mid-message gets no seed, delta or control for that message, never a wrong one. A started block whose next record
+ * has no capture, or that has no accepted end when the message ends, is invalid: its later records are dropped and
+ * the assistant `message_end` names it in `invalidatedBlocks`, so a reader rebuilds it from the terminal message.
+ * A terminal that rewrote blocks from `rewrittenFrom` on invalidates every block at or above that index, and a
+ * `message_end` with no interpretable terminal capture (cancel, idle timeout) invalidates every block of the message.
+ * Blocks are addressed by the capture's own index (`capture.contentIndex ?? event.contentIndex`), never a drifted public one.
+ */
+class SeededBlockGate {
+    accept(record) {
+        if (record.type === "message_block_state" || record.type === "message_block_metadata")
+            return this.control(record, record.type === "message_block_state" ? record.phase : undefined);
+        if (record.type === "message_tool_arguments_reset")
+            return this.control(record);
+        if (record.type === "message_start" && record.message.role === "assistant") {
+            const seeded = toJsonEvent(record, SEEDS);
+            this.blocks = seeded && new Map();
+            return seeded;
+        }
+        if (record.type === "message_end" && record.message.role === "assistant")
+            return this.end(record);
+        if (record.type !== "message_update")
+            return toJsonEvent(record, SEEDS);
+        if (!this.blocks)
+            return undefined;
+        const seeded = toJsonEvent(record, SEEDS);
+        const update = record.assistantMessageEvent;
+        if (!("contentIndex" in update))
+            return seeded;
+        const index = getAssistantCapture(record)?.contentIndex ?? update.contentIndex;
+        const starts = update.type === "text_start" || update.type === "thinking_start" || update.type === "toolcall_start";
+        if (!starts && this.blocks.get(index) !== "open")
+            return undefined;
+        const ends = update.type === "text_end" || update.type === "thinking_end" || update.type === "toolcall_end";
+        this.blocks.set(index, seeded ? (ends ? "ended" : "open") : "invalid");
+        return seeded;
+    }
+    control(record, phase) {
+        const state = this.blocks?.get(record.contentIndex);
+        if (!this.blocks || state === "invalid")
+            return undefined;
+        if (phase === "insert")
+            this.blocks.set(record.contentIndex, "open");
+        else if (state === undefined || (phase === "end" && state !== "open"))
+            return undefined;
+        else if (phase === "end")
+            this.blocks.set(record.contentIndex, "ended");
+        return record;
+    }
+    end(record) {
+        const capture = getAssistantCapture(record);
+        const rewrittenFrom = capture?.message === undefined ? 0 : (capture.rewrittenFrom ?? Number.POSITIVE_INFINITY);
+        const invalidatedBlocks = [...(this.blocks ?? [])].flatMap(([index, state]) => state === "ended" && index < rewrittenFrom ? [] : [index]);
+        this.blocks = undefined;
+        const seeded = toJsonEvent(record, SEEDS) ?? record;
+        return invalidatedBlocks.length === 0
+            ? seeded
+            : { ...seeded, invalidatedBlocks: invalidatedBlocks.sort((a, b) => a - b) };
+    }
+}
+/**
+ * The session's internal structured lane, correlated like its legacy records: seeded `toJsonEvent` projections of
+ * every session event plus the three block controls, in session order. Never a legacy destination.
+ */
+export function subscribeStructuredSessionRecords(session, output) {
+    const gate = new SeededBlockGate();
+    return subscribeSessionRecords(session, output, undefined, (listener) => session.subscribeStructured((record) => {
+        const accepted = gate.accept(record);
+        // Correlation reads only `type`, `role` and outer fields, which seeded records and controls keep.
+        if (accepted)
+            listener(accepted);
+    }));
+}
+//# sourceMappingURL=structured-session-records.js.map

package/docs/extensions.md

@@ -2170,7 +2170,13 @@ session-notice identity. Restart redelivers unconsumed queued messages once, but
 never replays a consumed result or reruns an interrupted tool.
 
 `pi.lifecycle.reportChild({ taskId, childSessionId, runEpoch, generation, state,
-waitingOn?, terminal? })` persists runner-owned child state. Stale epoch/generation
+label?, since?, waitingOn?, terminal? })` persists runner-owned child state. `label`
+is a producer-authored name and `since` is the child's own state-entry time (ISO);
+an unparseable `since` is dropped. `waitingOn` takes the `SessionLifecycle.waitingOn`
+shape described in [RPC session lifecycle](rpc.md#session-lifecycle), named lists
+included; its counts stay authoritative and the child's human waits are not kept.
+A nonterminal report appears in the parent's `waitingOn.childReports` as
+`{ taskId, childSessionId, runEpoch, state, label?, since? }`. Stale epoch/generation
 pairs are ignored; a higher `runEpoch` clears the old terminal status. Terminal
 values are `completed`, `error`, `lost`, `interrupted`, and `cancelled`. Child UI
 requests remain automatically answered by their runners, not routed to a person.