@sema-agent/core 7.54.0 → 7.55.0

package/dist/engine/loop/agent-loop.js

@@ -118,11 +118,12 @@ async function settleTrailingBatchTurn(state, signal, emit, settle) {
         terminalEmitted = ended;
     }
     else if (!ended) {
+        state.hasMoreToolCalls = !batch.terminate;
         const boundary = { message: tail, toolResults: batch.messages, context: state.context, newMessages: state.newMessages };
-        adoptNextTurnSnapshot(state, await state.config.prepareNextTurn?.(boundary));
+        adoptNextTurnSnapshot(state, await state.config.prepareNextTurn?.({ ...boundary, continues: state.hasMoreToolCalls }));
         ended = (await state.config.shouldStopAfterTurn?.(boundary)) === true || signal?.aborted === true;
         if (!ended)
-            state.pendingMessages.push(...((await state.config.getSteeringMessages?.()) || []));
+            state.pendingMessages.push(...((await state.config.getSteeringMessages?.(state.hasMoreToolCalls)) || []));
     }
     settle.report({ assistantMessage: tail, settled: batch.messages.length, aborted: ended });
     if (ended && !terminalEmitted)
@@ -242,7 +243,7 @@ async function createLoopState(context, config, newMessages) {
         config,
         newMessages,
         firstTurn: true,
-        pendingMessages: (await config.getSteeringMessages?.()) || [],
+        pendingMessages: (await config.getSteeringMessages?.(true)) || [],
         hasMoreToolCalls: true,
         truncatedOutputContinues: 0,
         staticReasoningCutRecoveries: context.messages.filter((m) => m.role === "assistant" && m.staticReasoningCut === true).length,
@@ -258,7 +259,7 @@ async function runLoop(state, signal, emit, streamFn, runtime, trace) {
             const followUpMessages = (await state.config.getFollowUpMessages?.()) || [];
             if (followUpMessages.length === 0) {
                 if ((state.config.pendingInjectionCount?.() ?? 0) > 0) {
-                    state.pendingMessages = (await state.config.getSteeringMessages?.()) || [];
+                    state.pendingMessages = (await state.config.getSteeringMessages?.(false)) || [];
                     if (state.pendingMessages.length > 0) {
                         trace?.({ kind: "continue", reason: "steer_injected" });
                     }
@@ -448,7 +449,7 @@ async function runTurnPhases(state, signal, turnController, publishSeat, retract
             retractSeat();
             state.degenerateContinues++;
             await emit({ type: "turn_end", message, toolResults: [] });
-            const drained = (await state.config.getSteeringMessages?.()) || [];
+            const drained = (await state.config.getSteeringMessages?.(false)) || [];
             state.pendingMessages = drained.length > 0 ? drained : [createDegenerateRecoveryNudge()];
             return { kind: "ran", recovered: "degenerate_output_recovery" };
         }
@@ -493,7 +494,7 @@ async function runTurnPhases(state, signal, turnController, publishSeat, retract
         context: state.context,
         newMessages: state.newMessages,
     };
-    const nextTurnSnapshot = await state.config.prepareNextTurn?.(nextTurnContext);
+    const nextTurnSnapshot = await state.config.prepareNextTurn?.({ ...nextTurnContext, continues: state.hasMoreToolCalls });
     adoptNextTurnSnapshot(state, nextTurnSnapshot);
     if (await state.config.shouldStopAfterTurn?.({
         message,
@@ -504,7 +505,7 @@ async function runTurnPhases(state, signal, turnController, publishSeat, retract
         await emit({ type: "agent_end", messages: state.newMessages });
         return { kind: "terminal", reason: "stop_requested" };
     }
-    state.pendingMessages = (await state.config.getSteeringMessages?.()) || [];
+    state.pendingMessages = (await state.config.getSteeringMessages?.(state.hasMoreToolCalls)) || [];
     const truncated = state.config.recovery?.truncatedOutput;
     if (message.stopReason === "length") {
         if (truncated && toolCalls.length === 0 && state.pendingMessages.length === 0) {
@@ -653,6 +654,7 @@ async function settleInterruptedTurn(state, message, executor, committedResults,
         toolResults,
         context: state.context,
         newMessages: state.newMessages,
+        continues: state.hasMoreToolCalls,
     });
     adoptNextTurnSnapshot(state, nextTurnSnapshot);
     if (await state.config.shouldStopAfterTurn?.({
@@ -664,7 +666,7 @@ async function settleInterruptedTurn(state, message, executor, committedResults,
         await emit({ type: "agent_end", messages: state.newMessages });
         return { kind: "terminal", reason: "stop_requested" };
     }
-    state.pendingMessages = (await state.config.getSteeringMessages?.()) || [];
+    state.pendingMessages = (await state.config.getSteeringMessages?.(state.hasMoreToolCalls)) || [];
     return { kind: "ran" };
 }
 async function streamAssistantResponse(context, config, signal, emit, streamFn, runtime, executor, staticReasoningCutDowngrade) {

package/dist/engine/loop/types.d.ts

@@ -176,6 +176,8 @@ export interface AgentLoopTurnUpdate {
     thinkingLevel?: ThinkingLevel;
 }
 export interface PrepareNextTurnContext extends ShouldStopAfterTurnContext {
+    /** `hasMoreToolCalls`: the turn's tool results go back to the model as the next request (its batch neither ended the run nor was cut by an interjection; a recovery nudge is not one). */
+    continues: boolean;
 }
 /**
  * Prompt-too-long recovery seam (design/118 ④b, the CC reactive-compact chain adapted to sema's
@@ -214,8 +216,8 @@ export interface LoopPromptTooLongRecovery {
     maxRetries?: number;
     /**
      * M1 (docs/PARITY-CONTEXT-TRANSACTIONS-2026-07-10 §4): withhold the failed assistant's
-     * message_start/message_end stream events while a recovery attempt is pending — CC 198 holds
-     * these errors inside its stream decoder (`claude-cli-2.1.198.pretty.js:473371-473374`) and only
+     * message_start/message_end stream events while a recovery attempt is pending — the reference holds
+     * these errors inside its stream decoder and only
      * leaks them once recovery's outcome is known. Recovery succeeded ⇒ the failure stays invisible
      * to event consumers; failed/declined ⇒ the events leak at that point (terminal truth unchanged).
      * Default true (CC-aligned). `false` restores the pre-M1 live leak of the interim error.
@@ -239,7 +241,7 @@ export interface LoopTruncatedOutputRecovery {
     maxContinues?: number;
 }
 /**
- * Malformed-tool-use retry (design/119 S2, CC 2.1.198 :473745-473785). A turn that stops with
+ * Malformed-tool-use retry (design/119 S2). A turn that stops with
  * `toolUse` but carries ZERO parseable tool calls (the brain dropped truncated/invalid ones) used to
  * end the run silently mid-task. When enabled, inject a synthetic retry nudge and run another turn,
  * up to `maxRetries` per run (CC: once). Absent ⇒ OFF (pre-S2 behavior).
@@ -249,7 +251,7 @@ export interface LoopMalformedToolUseRecovery {
     maxRetries?: number;
 }
 /**
- * Thinking-only retry (design/119 S2, CC 2.1.198 :473786-473825 — the adaptive-thinking era
+ * Thinking-only retry (design/119 S2 — the adaptive-thinking era
  * companion). A turn that stops normally with thinking block(s) but NO visible text and NO tool
  * calls used to end the run as a silent empty success. When enabled, inject a "respond with visible
  * output" nudge and run another turn, up to `maxRetries` per run (CC: once). Absent ⇒ OFF.
@@ -345,7 +347,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      */
     stallTimeoutsPerCall?: () => import("../llm/types.js").StallTimeouts | undefined;
     /**
-     * design/120 P1: concurrency cap inside a parallel tool batch. Default 10 (CC 198's production
+     * design/120 P1: concurrency cap inside a parallel tool batch. Default 10 (the reference's production
      * default — its knob is the CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY env; sema takes config).
      */
     maxToolConcurrency?: number;
@@ -473,11 +475,11 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * If messages are returned, they are added to the context before the next LLM call.
      * Tool calls from the current assistant message are not skipped.
      *
-     * Use this for "steering" the agent while it's working.
+     * Use this for "steering" the agent while it's working. `continuing`: {@link PrepareNextTurnContext.continues} here.
      *
      * Contract: must not throw or reject. Return [] when no steering messages are available.
      */
-    getSteeringMessages?: () => Promise<AgentMessage[]>;
+    getSteeringMessages?: (continuing: boolean) => Promise<AgentMessage[]>;
     /**
      * Returns follow-up messages to process after the agent would otherwise stop.
      *
@@ -520,7 +522,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
     /**
      * design/373 S1 — the FINAL COMMIT POINT's synchronous double-check: how many queued injection
      * frames a boundary drain could deliver right now (steer + follow-up, excluding frames a live
-     * hold or an unwinding run would refuse to drain). Consulted SYNCHRONOUSLY after the follow-up
+     * hold, an unwinding run or the advisory rule would refuse to drain). Consulted SYNCHRONOUSLY after the follow-up
      * drain (and stop gate) answered empty, with zero awaits between the check and the terminal
      * commit — a frame that arrived during the stop gate's await window is therefore served by this
      * run instead of being stranded behind an already-decided terminal. Absent ⇒ the pre-373 commit
@@ -759,17 +761,17 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unk
      * - "parallel": this tool can execute concurrently with other tool calls.
      *
      * If omitted, the tool is treated as NOT concurrency-safe unless its input-level
-     * `isConcurrencySafe` hook opts a call in (fail-closed; CC 2.1.206 TOOL_DEFAULTS parity).
+     * `isConcurrencySafe` hook opts a call in (fail-closed).
      */
     executionMode?: ToolExecutionMode;
     /**
-     * MCP server self-declared result-size threshold (CC 198 `_meta["anthropic/maxResultSizeChars"]`,
-     * pretty.js:320015/:320061 — consumer caps at 500K). Set by the MCP materializer when the server
+     * MCP server self-declared result-size threshold (`_meta["anthropic/maxResultSizeChars"]`,
+     * consumer caps at 500K). Set by the MCP materializer when the server
      * declares it; consulted by the offload mount in prepare-task. Absent on non-MCP tools.
      */
     mcpMaxResultSizeChars?: number;
     /**
-     * RB-400-a — MCP server-declared inline pin (CC 220 `_meta["anthropic/alwaysLoad"]`): set by the
+     * RB-400-a — MCP server-declared inline pin (`_meta["anthropic/alwaysLoad"]`): set by the
      * MCP materializer when the server's tools/list entry declares it; prepare-task folds these names
      * into the defer classification's exemption set, ahead of the MCP constant-defer arm — the
      * server's own channel for keeping one tool's full schema inlined. Absent on non-MCP tools.
@@ -803,7 +805,7 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unk
      * partitioner for every tool WITHOUT an explicit `executionMode:"parallel"` (a statically-parallel
      * tool needs no refinement); `true` = treat THIS CALL as concurrency-safe. A throw = false
      * (fail-closed, CC same). The partitioner validates the call's args against the tool schema FIRST
-     * (schema-invalid ⇒ unsafe, CC 206 safeParse parity) and hands the hook the validated+coerced
+     * (schema-invalid ⇒ unsafe) and hands the hook the validated+coerced
      * args — still treat defensively (a direct caller may pass raw args). Omitted ⇒ the static mode stands.
      */
     isConcurrencySafe?: (args: unknown) => boolean;

package/dist/engine/lsp/node-lsp-manager.d.ts

@@ -127,12 +127,12 @@ export declare class NodeLspManager implements LspServerManager {
 }
 /** Resolve a file path to a languageId via its extension (undefined = no mapping → degrade). */
 export declare function languageFor(filePath: string): string | undefined;
-/** CC 2.1.220's LSP file cap — single-sourced in core (`src/core/lsp.ts`), where the tool-layer check
+/** The LSP file cap — single-sourced in core (`src/core/lsp.ts`), where the tool-layer check
  *  enforces it model-visibly; re-exported here so engine-path importers keep working. */
 export { MAX_LSP_FILE_BYTES } from "../../core/lsp.js";
 /**
  * RB-232: the local default {@link LspReadText}, hardened with a stat-first precondition (CC
- * 2.1.220 validateInput does the same before ever reading — "Path is not a file", (pretty220.js:474700, historical; not relocated in 250 — see cc-250 anchors)).
+ * the reference's validateInput does the same before ever reading — "Path is not a file").
  * The stat check is the LOAD-BEARING part, do not "simplify" it away: a plain `readFile` on a FIFO/socket
  * blocks forever on the FIRST read and PINS a libuv threadpool thread (default pool = 4) for the process
  * lifetime — measured: `readFile(fifo, { signal })` with an abort fired at 2s was still unsettled at 10s,

package/dist/engine/session/memory-repo.d.ts

@@ -1,22 +1,21 @@
-import { type Session, type SessionForkOptions, type SessionMetadata, type SessionRepo, type SessionTreeEntry } from "../harness/types.js";
-export declare class InMemorySessionRepo implements SessionRepo<SessionMetadata, {
-    id?: string;
-}> {
+import { type Session, type SessionCreateOptions, type SessionForkOptions, type SessionHead, type SessionMetadata, type SessionRepo, type SessionTreeEntry } from "../harness/types.js";
+export declare class InMemorySessionRepo implements SessionRepo<SessionMetadata, SessionCreateOptions> {
     private sessions;
-    create(options?: {
-        id?: string;
-    }): Promise<Session>;
+    create(options?: SessionCreateOptions): Promise<Session>;
     open(metadata: SessionMetadata): Promise<Session>;
+    /** The row's head off the one session object that IS the row: every cell comes from that object, so a delete and re-create of the
+     *  id while this reads cannot mix two generations. */
+    headOf(sessionId: string): Promise<SessionHead | undefined>;
     list(): Promise<SessionMetadata[]>;
     delete(metadata: SessionMetadata): Promise<void>;
-    fork(sourceMetadata: SessionMetadata, options: SessionForkOptions): Promise<Session>;
+    fork(sourceMetadata: SessionMetadata, options: SessionForkOptions & SessionCreateOptions): Promise<Session>;
     /** 2c session-sync: the FULL log for export. InMemory holds everything (no F3 floor), so
      *  `getEntries()` IS the full oldest-first log with `id`/`parentId` verbatim. */
     exportEntries(sessionId: string): Promise<SessionTreeEntry[]>;
     /** 2c session-sync: import a verbatim log into `sessionId`. The single invariant gate runs first
-     *  ({@link validateEntriesForImport}, fail-closed); `owner` is a durable multi-tenant concept that the local
-     *  in-memory backend has no field for, so it is accepted but unused here. design/171: the operator's
-     *  trusted-import flag is forwarded to the gate that persists — see SessionRepo.importEntries. */
+     *  ({@link validateEntriesForImport}, fail-closed); a new row records `owner`, an existing row keeps its metadata whole.
+     *  design/171: the operator's trusted-import flag is forwarded to the gate that persists — see
+     *  SessionRepo.importEntries. */
     importEntries(sessionId: string, owner: string | undefined, entries: SessionTreeEntry[], options?: {
         preserveActorAssertions?: boolean;
     }): Promise<void>;

package/dist/engine/session/memory-repo.js

@@ -1,7 +1,7 @@
 import { SessionError } from "../harness/types.js";
 import { validateEntriesForImport } from "./import-validate.js";
 import { InMemorySessionStorage } from "./memory-storage.js";
-import { assertForkTarget, createSessionId, createTimestamp, forkRowCells, getEntriesToFork, incarnationCell, toSession } from "./repo-utils.js";
+import { assertForkTarget, createSessionId, createTimestamp, forkRowCells, frozenRow, getEntriesToFork, headOfSession, importRowCells, incarnationCell, ownerCell, toSession } from "./repo-utils.js";
 export class InMemorySessionRepo {
     sessions = new Map();
     async create(options = {}) {
@@ -10,11 +10,12 @@ export class InMemorySessionRepo {
             if (existing)
                 return existing;
         }
-        const metadata = {
+        const metadata = frozenRow({
             id: options.id ?? createSessionId(),
             createdAt: createTimestamp(),
             ...incarnationCell(undefined),
-        };
+            ...ownerCell(options.owner),
+        });
         const storage = new InMemorySessionStorage({ metadata });
         const session = toSession(storage);
         this.sessions.set(metadata.id, session);
@@ -27,6 +28,10 @@ export class InMemorySessionRepo {
         }
         return session;
     }
+    async headOf(sessionId) {
+        const row = this.sessions.get(sessionId);
+        return row === undefined ? undefined : headOfSession(row);
+    }
     async list() {
         return Promise.all([...this.sessions.values()].map((session) => session.getMetadata()));
     }
@@ -37,11 +42,11 @@ export class InMemorySessionRepo {
         assertForkTarget(sourceMetadata.id, options.id);
         const source = await this.open(sourceMetadata);
         const forkedEntries = await getEntriesToFork(source.getStorage(), options);
-        const metadata = {
+        const metadata = frozenRow({
             id: options.id ?? createSessionId(),
             createdAt: createTimestamp(),
-            ...forkRowCells(await source.getMetadata()),
-        };
+            ...forkRowCells(await source.getMetadata(), options.owner),
+        });
         const storage = new InMemorySessionStorage({ metadata, entries: forkedEntries });
         const session = toSession(storage);
         this.sessions.set(metadata.id, session);
@@ -52,7 +57,7 @@ export class InMemorySessionRepo {
         return session.getStorage().getEntries();
     }
     async importEntries(sessionId, owner, entries, options) {
-        void owner;
+        ownerCell(owner);
         const validated = validateEntriesForImport(entries, options);
         let prior = this.sessions.get(sessionId);
         let header = prior !== undefined ? await prior.getMetadata() : undefined;
@@ -60,7 +65,7 @@ export class InMemorySessionRepo {
             prior = this.sessions.get(sessionId);
             header = prior !== undefined ? await prior.getMetadata() : undefined;
         }
-        const metadata = { id: sessionId, createdAt: createTimestamp(), ...incarnationCell(header) };
+        const metadata = frozenRow(importRowCells(sessionId, owner, header, createTimestamp()));
         this.sessions.set(sessionId, toSession(new InMemorySessionStorage({ metadata, entries: validated })));
     }
 }

package/dist/engine/session/parent-chain-guard.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The memory of one walk up a session log's parent chain, shared by `getPathToRoot`, the resume-at ancestry scan and the fork-point judge `settledForkOptions` (the import validator still keeps its own loop — #2253). An entry the
+ * walk stands on twice means the parent links loop, which no ancestry can contain: the walk is refused
+ * `invalid_session` naming that entry instead of being followed again, and saying what a person can do (start a new session, or fork from an entry the
+ * loop does not touch). One guard per walk.
+ */
+export declare class ParentChainGuard {
+    private readonly stepped;
+    /** Records that the walk now stands on `id`; throws `invalid_session` when it already stood there. */
+    stepOnto(id: string): void;
+}

package/dist/engine/session/parent-chain-guard.js

@@ -0,0 +1,10 @@
+import { SessionError } from "../harness/types.js";
+export class ParentChainGuard {
+    stepped = new Set();
+    stepOnto(id) {
+        if (this.stepped.has(id)) {
+            throw new SessionError("invalid_session", `Entry ${id} is its own ancestor (parent chain cycles at ${id}) — start a new session, or fork from an entry above the loop`);
+        }
+        this.stepped.add(id);
+    }
+}

package/dist/engine/session/repo-utils.d.ts

@@ -1,4 +1,4 @@
-import { type SessionMetadata, type SessionStorage, type SessionTreeEntry } from "../harness/types.js";
+import { type SessionHead, type SessionMetadata, type SessionStorage, type SessionTreeEntry } from "../harness/types.js";
 import type { Session } from "../harness/types.js";
 export declare function createSessionId(): string;
 /** The {@link SessionMetadata.incarnation} cell for a write laying a row's metadata down — the bundled repos' ONE mint point.
@@ -10,10 +10,38 @@ export declare function incarnationCell(existing: Pick<SessionMetadata, "incarna
  *  occupant, silently; a cell that is there but is not a token (`""`, a non-string) is an unknown occupant too and `disclose`
  *  is told once with the cell's shape (never its value). The cell never makes this throw; a throw from `disclose` propagates. */
 export declare function readIncarnationCell(raw: unknown, disclose: (detail: string) => void): string | undefined;
+/**
+ * Whether two heads of one session id name the same occupant (each side a {@link SessionHead}, or a row's {@link SessionMetadata}).
+ * `"unknown"` whenever either side has no row or no occupant token — unknown is never `"same"`, so a caller that may only proceed on the
+ * same occupant refuses on it.
+ */
+export declare function compareOccupants(before: {
+    readonly incarnation?: SessionHead["incarnation"];
+} | undefined, after: {
+    readonly incarnation?: SessionHead["incarnation"];
+} | undefined): "same" | "different" | "unknown";
+/** The {@link SessionHead} a session object shows: its metadata's owner and occupant and its storage's leaf, off that one object. */
+export declare function headOfSession(session: Session): Promise<SessionHead>;
+/** The {@link SessionMetadata.owner} cell the write creating a row records: `owner` (a string, or `null`; `undefined` = none named =
+ *  `null`). An `owner` that is neither is refused before the write, so no row ever holds an owner cell that reads as neither. */
+export declare function ownerCell(owner: unknown): Pick<SessionMetadata, "owner">;
+/** The metadata an import lays down. An import replaces the log, never the row: an existing row keeps its metadata whole (its creation
+ *  time, lineage, placement, occupant and owner were recorded by the write that created it); an absent id is a new row recording `owner`
+ *  and a fresh occupant. `owner` is judged either way. */
+export declare function importRowCells(sessionId: string, owner: unknown, existing: SessionMetadata | undefined, createdAt: string): SessionMetadata;
+/** The one decoding of a stored owner cell: a string is the owner; absence (`undefined`, `null`) is anonymous. A cell that is there
+ *  but is neither cannot be read as anyone's, and reading it as anonymous would admit every principal — the row is refused as
+ *  `corrupt_session` instead (a read fault, never an answer). */
+export declare function readOwnerCell(raw: unknown, sessionId: string): string | null;
 /** A fork lands on a row OTHER than its source: onto its own id it would mint a new occupant over the source's transcript and erase the lineage that carries the source's records. */
 export declare function assertForkTarget(sourceId: string, targetId: string | undefined): void;
-/** A fork row's cells, minted from the SOURCE row as it stands at fork time: the lineage (`forkedFrom` + the occupant copied) and a fresh occupant of its own. */
-export declare function forkRowCells(source: SessionMetadata): Pick<SessionMetadata, "forkedFrom" | "forkedFromIncarnation" | "incarnation">;
+/** A fork row's cells, minted from the SOURCE row as it stands at fork time — the same row the fork copies its history from: the lineage
+ *  (`forkedFrom` + the occupant copied), a fresh occupant of its own, and its owner — `owner` when one is named, otherwise (absent or `null`)
+ *  the source row's, so a copy of an owned history is never anonymous and never another generation's. */
+export declare function forkRowCells(source: SessionMetadata, owner?: string | null): Pick<SessionMetadata, "forkedFrom" | "forkedFromIncarnation" | "incarnation" | "owner">;
+/** A row's metadata as the bundled repos hold it: frozen (its placement tuple too), so a caller holding the object `getMetadata()` or
+ *  `list()` returns cannot rewrite the row's identity cells — the owner, the occupant, the placement, the lineage — without a write. */
+export declare function frozenRow<T extends SessionMetadata>(meta: T): T;
 export declare function createTimestamp(): string;
 export declare function toSession<TMetadata extends SessionMetadata>(storage: SessionStorage<TMetadata>): Session<TMetadata>;
 export declare function getEntriesToFork(storage: SessionStorage, options: {

package/dist/engine/session/repo-utils.js

@@ -11,20 +11,57 @@ export function incarnationCell(existing) {
     return existing.incarnation !== undefined ? { incarnation: existing.incarnation } : {};
 }
 export function readIncarnationCell(raw, disclose) {
-    if (typeof raw === "string" && raw !== "")
+    if (isOccupantToken(raw))
         return raw;
     if (raw === undefined || raw === null)
         return undefined;
-    const shape = raw === "" ? "an empty string" : Array.isArray(raw) ? "a non-string value (array)" : `a non-string value (${typeof raw})`;
-    disclose(`the incarnation cell holds ${shape} — read as an unknown occupant`);
+    disclose(`the incarnation cell holds ${raw === "" ? "an empty string" : nonStringShape(raw)} — read as an unknown occupant`);
     return undefined;
 }
+function isOccupantToken(raw) {
+    return typeof raw === "string" && raw !== "";
+}
+function nonStringShape(raw) {
+    return Array.isArray(raw) ? "a non-string value (array)" : `a non-string value (${typeof raw})`;
+}
+export function compareOccupants(before, after) {
+    const a = before?.incarnation;
+    const b = after?.incarnation;
+    if (!isOccupantToken(a) || !isOccupantToken(b))
+        return "unknown";
+    return a === b ? "same" : "different";
+}
+export async function headOfSession(session) {
+    const meta = await session.getMetadata();
+    return { owner: meta.owner ?? null, incarnation: meta.incarnation, leafId: await session.getStorage().getLeafId() };
+}
+export function ownerCell(owner) {
+    if (owner !== undefined && owner !== null && typeof owner !== "string")
+        throw new TypeError(`session owner must be a string (owned) or null (anonymous), got ${nonStringShape(owner)}`);
+    return { owner: owner ?? null };
+}
+export function importRowCells(sessionId, owner, existing, createdAt) {
+    const named = ownerCell(owner);
+    return existing ?? { id: sessionId, createdAt, ...incarnationCell(undefined), ...named };
+}
+export function readOwnerCell(raw, sessionId) {
+    if (typeof raw === "string")
+        return raw;
+    if (raw === undefined || raw === null)
+        return null;
+    throw new SessionError("corrupt_session", `session ${sessionId}'s owner cell holds ${nonStringShape(raw)} — neither an owner nor anonymous; refusing to read the row`);
+}
 export function assertForkTarget(sourceId, targetId) {
     if (targetId === sourceId)
         throw new SessionError("invalid_fork_target", `cannot fork session ${sourceId} onto its own id — fork into a new id`);
 }
-export function forkRowCells(source) {
-    return { forkedFrom: source.id, ...(source.incarnation !== undefined ? { forkedFromIncarnation: source.incarnation } : {}), ...incarnationCell(undefined) };
+export function forkRowCells(source, owner) {
+    return { forkedFrom: source.id, ...(source.incarnation !== undefined ? { forkedFromIncarnation: source.incarnation } : {}), ...incarnationCell(undefined), ...ownerCell(owner ?? source.owner) };
+}
+export function frozenRow(meta) {
+    if (meta.placement !== undefined)
+        Object.freeze(meta.placement);
+    return Object.freeze(meta);
 }
 export function createTimestamp() {
     return new Date().toISOString();

package/dist/engine/session/storage-base.js

@@ -1,4 +1,5 @@
 import { SessionError, } from "../harness/types.js";
+import { ParentChainGuard } from "./parent-chain-guard.js";
 import { uuidv7 } from "./uuid.js";
 function updateLabelCache(labelsById, entry) {
     if (entry.type !== "label") {
@@ -111,11 +112,13 @@ export class BaseSessionStorage {
             return [];
         }
         const path = [];
+        const chain = new ParentChainGuard();
         let current = this.byId.get(leafId);
         if (!current) {
             throw new SessionError("not_found", `Entry ${leafId} not found`);
         }
         while (current) {
+            chain.stepOnto(current.id);
             path.push(current);
             if (current.id === this.floorId) {
                 break;