@sema-agent/core 7.48.0 → 7.49.1

package/dist/engine/execution-env/node-execution-env.js

@@ -3,13 +3,13 @@ import { randomUUID } from "node:crypto";
 import { closeSync, constants, createReadStream, mkdtempSync, openSync, readSync, statSync, truncateSync, unlinkSync } from "node:fs";
 import { access, appendFile, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rename, rm, stat, unlink, writeFile, } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { ExecutionError, err, FileError, ok, toError, } from "../harness/types.js";
 import { killProcessTree, shutdownDebug } from "./kill-tree.js";
 import { __resetSecretEnvScrubNoticeAnnouncement, announceSecretEnvScrub, inheritEnvPolicyProblem, inheritedHostEnv, scrubSecretEnv } from "../../core/secret-env.js";
 import { physicalPathOfAsync } from "../../core/physical-path.js";
-import { isUncSpelling } from "../../tools/fs/safety.js";
+import { walkSymlinkChain } from "./symlink-chain.js";
 import { RollingTailBuffer, markTruncated, newStreamCursorState, sliceStreamIncrement, } from "../../core/exec-output-tail.js";
 import { BackgroundShellError } from "../../core/background-shell.js";
 import { SchedulerError } from "../../core/scheduler.js";
@@ -42,11 +42,6 @@ function fileKindFromStats(stats) {
     return undefined;
 }
 const HAS_POSIX_MODE_FACE = process.platform !== "win32";
-export function anchorAtLinkDir(linkDir, target, separator) {
-    const endsInSeparator = linkDir.endsWith(separator) || (separator === "\\" && linkDir.endsWith("/"));
-    return endsInSeparator ? `${linkDir}${target}` : `${linkDir}${separator}${target}`;
-}
-const SYMLINK_CHAIN_HOP_BOUND = 64;
 function fileInfoFromStats(path, stats) {
     const kind = fileKindFromStats(stats);
     if (!kind) {
@@ -94,6 +89,14 @@ function toFileError(error, path) {
     }
     return new FileError("unknown", cause.message, path, cause);
 }
+async function readLinkTarget(resolved) {
+    try {
+        return ok(await readlink(resolved));
+    }
+    catch (error) {
+        return err(toFileError(error, resolved));
+    }
+}
 function abortResult(signal, path) {
     return signal?.aborted ? err(new FileError("aborted", "aborted", path)) : undefined;
 }
@@ -279,6 +282,10 @@ export class NodeExecutionEnv {
     get homeDir() {
         return getShellEnv(this.inheritEnv, this.shellEnv, undefined, () => { }).HOME;
     }
+    get cdPath() {
+        const value = getShellEnv(this.inheritEnv, this.shellEnv, undefined, () => { }).CDPATH;
+        return value === undefined || value === "" ? [] : value.split(":");
+    }
     shellPath;
     shellEnv;
     inheritEnv;
@@ -1024,39 +1031,10 @@ export class NodeExecutionEnv {
         }
     }
     async readLink(path) {
-        const resolved = resolvePath(this.cwd, path);
-        try {
-            return ok(await readlink(resolved));
-        }
-        catch (error) {
-            return err(toFileError(error, resolved));
-        }
+        return readLinkTarget(resolvePath(this.cwd, path));
     }
     async canonicalChain(path) {
-        const resolved = resolvePath(this.cwd, path);
-        const hops = [];
-        const seen = new Set([resolved]);
-        let cur = resolved;
-        for (let hop = 0; hop < SYMLINK_CHAIN_HOP_BOUND; hop++) {
-            let target;
-            try {
-                target = await readlink(cur);
-            }
-            catch (error) {
-                if (isNodeError(error) && (error.code === "EINVAL" || error.code === "ENOENT" || error.code === "ENOTDIR"))
-                    return ok({ hops });
-                return err(toFileError(error, cur));
-            }
-            const next = isAbsolute(target) ? target : anchorAtLinkDir(dirname(cur), target, sep);
-            if (seen.has(next))
-                break;
-            hops.push(next);
-            if (process.platform === "win32" && isUncSpelling(next))
-                break;
-            seen.add(next);
-            cur = next;
-        }
-        return ok({ hops });
+        return walkSymlinkChain(resolvePath(this.cwd, path), readLinkTarget);
     }
     async exists(path) {
         const result = await this.fileInfo(path);

package/dist/engine/execution-env/symlink-chain.d.ts

@@ -0,0 +1,23 @@
+import { type FileError, type Result, type SymlinkChain } from "../harness/types.js";
+/**
+ * Anchor a RELATIVE symlink target at its link's own directory, UNFOLDED, with exactly one separator between the two.
+ * A root directory (`/`, `C:\`, `\\host\share\`) already ends in its own separator, and a second one mints a spelling
+ * (`//private/tmp`) that no guarded row matches; `path.resolve`/`join` would fix the separator and fold `..`, which
+ * this walk may not do. `separator` is the one the caller's `dirname` writes (a pure function of its inputs); a
+ * backslash terminates only where it IS a separator — on a POSIX tree `/a/b\` is an ordinary name.
+ */
+export declare function anchorAtLinkDir(linkDir: string, target: string, separator: string): string;
+/** The walk's bound (the reference CLI's own); the terminal canonicalizer refuses at 16, so this only bounds what is REPORTED. */
+export declare const SYMLINK_CHAIN_MAX_HOPS = 64;
+/** The one-hop primitive (`FileSystem.readLink`'s signature): the target a symlink NAMES, not followed. The walk reads `invalid` / `not_found` / `not_directory` as the end of the chain. */
+export type SymlinkHopReader = (path: string) => Promise<Result<string, FileError>>;
+/**
+ * THE leaf symlink chain walk ({@link import("../harness/types.js").FileSystem.canonicalChain}'s answer) over the
+ * smallest primitive: `readLink` on `start` (resolved, absolute), then on each target, until a hop is not a link, is
+ * absent, repeats, or the bound is reached. A relative target is anchored at its link's directory and never folded
+ * (`..` is the filesystem's to resolve in the next lookup: a lexical fold reads `bridge/../next` as `next` and misses
+ * every link behind `bridge`). The addressed spelling seeds the cycle table, so it is never a hop of its own chain;
+ * on win32 a share-shaped hop is kept and ends the walk unprobed. Any other failure is `err`, never a shortened chain.
+ * `NodeExecutionEnv.canonicalChain` is this function over its own read; a non-`node:fs` host supplies its own.
+ */
+export declare function walkSymlinkChain(start: string, readLink: SymlinkHopReader): Promise<Result<SymlinkChain, FileError>>;

package/dist/engine/execution-env/symlink-chain.js

@@ -0,0 +1,32 @@
+import { dirname, isAbsolute, sep } from "node:path";
+import { isUncSpelling } from "../../tools/fs/safety.js";
+import { err, ok } from "../harness/types.js";
+export function anchorAtLinkDir(linkDir, target, separator) {
+    const endsInSeparator = linkDir.endsWith(separator) || (separator === "\\" && linkDir.endsWith("/"));
+    return endsInSeparator ? `${linkDir}${target}` : `${linkDir}${separator}${target}`;
+}
+export const SYMLINK_CHAIN_MAX_HOPS = 64;
+export async function walkSymlinkChain(start, readLink) {
+    const hops = [];
+    const seen = new Set([start]);
+    let cur = start;
+    for (let hop = 0; hop < SYMLINK_CHAIN_MAX_HOPS; hop++) {
+        const read = await readLink(cur);
+        if (!read.ok) {
+            const code = read.error.code;
+            if (code === "invalid" || code === "not_found" || code === "not_directory")
+                return ok({ hops });
+            return err(read.error);
+        }
+        const target = read.value;
+        const next = isAbsolute(target) ? target : anchorAtLinkDir(dirname(cur), target, sep);
+        if (seen.has(next))
+            break;
+        hops.push(next);
+        if (process.platform === "win32" && isUncSpelling(next))
+            break;
+        seen.add(next);
+        cur = next;
+    }
+    return ok({ hops });
+}

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

@@ -518,6 +518,8 @@ export interface ExecutionEnv extends FileSystem, Shell {
      * an absolute path is refused at prepare (`config.execution_env_home_dir_invalid`), never read as absent.
      */
     readonly homeDir?: string;
+    /** #1554 — the `CDPATH` entries the shell child receives (`[]` = none), or `"unknown"` when the adapter cannot say. */
+    readonly cdPath: readonly string[] | "unknown";
 }
 /** Base fields shared by append-only session tree entries. */
 export interface SessionTreeEntryBase {
@@ -868,6 +870,10 @@ export interface SessionMetadata {
      *  {@link SessionPlacementRecord}). Absent on every ordinary (host-lane) session; a repo that does
      *  not understand placement never surfaces it (additive, old readers tolerate). */
     placement?: SessionPlacementRecord;
+    /** WHICH occupant this row is: minted by the repo once when the row comes into existence (create / fork / import onto an absent id), carried by every other write; only compared; absent = UNKNOWN, never backfilled; not wire / model-context material. */
+    incarnation?: string;
+    /** Fork lineage's OCCUPANT half: the source row's `incarnation` at fork time (the occupant copied, not whoever holds `forkedFrom` later); absent = unknown. */
+    forkedFromIncarnation?: string;
 }
 export interface JsonlSessionMetadata extends SessionMetadata {
     cwd: string;
@@ -1030,6 +1036,7 @@ export interface SessionRepo<TMetadata extends SessionMetadata = SessionMetadata
     open(metadata: TMetadata): Promise<Session<TMetadata>>;
     list(options?: TListOptions): Promise<TMetadata[]>;
     delete(metadata: TMetadata): Promise<void>;
+    /** A fork is a NEW row: `options.id` equal to the source's id is refused (`invalid_fork_target`) — onto its source it would mint a new occupant over the source's own transcript. */
     fork(source: TMetadata, options: SessionForkOptions & TCreateOptions): Promise<Session<TMetadata>>;
     /**
      * 2c session-sync: the FULL durable entry log for `sessionId`, oldest-first, with

package/dist/engine/llm/tool-turns.d.ts

@@ -83,6 +83,9 @@ export declare const TOOL_TURN_INCOMPLETE_CAUSES: readonly ["truncated", "unname
 export type ToolTurnIncompleteCause = (typeof TOOL_TURN_INCOMPLETE_CAUSES)[number];
 /** The causes a brain's stream parse finds — what a turn's own message can report. */
 export type StreamDropCause = Exclude<ToolTurnIncompleteCause, "missing_result_synthesized">;
+/** The drop causes that can FAIL a turn (dropped calls; a dropped frame only notes a gap): `modelOutputInvalid.cause`. */
+export declare const MODEL_OUTPUT_INVALID_CAUSES: readonly ["truncated", "unnamed"];
+export type ModelOutputInvalidCause = (typeof MODEL_OUTPUT_INVALID_CAUSES)[number];
 /** One cause a turn's stream dropped content for, and how many calls (or frames) it dropped. */
 export interface StreamDrop {
     readonly cause: StreamDropCause;

package/dist/engine/llm/tool-turns.js

@@ -9,6 +9,7 @@ export const TOOL_TURN_REPAIR_DROPS = {
     orphan_result: true,
 };
 export const TOOL_TURN_INCOMPLETE_CAUSES = Object.freeze(["truncated", "unnamed", "bad_frame", "missing_result_synthesized"]);
+export const MODEL_OUTPUT_INVALID_CAUSES = Object.freeze(["truncated", "unnamed"]);
 const STREAM_DROPS_DIAGNOSTIC = "stream_drops";
 const STREAM_DROP_CAUSES = new Set(["truncated", "unnamed", "bad_frame"]);
 export function stampStreamDrops(message, drops) {

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

@@ -1,6 +1,10 @@
 export type { AssistantMessageDiagnostic, DiagnosticErrorInfo } from "./diagnostics.js";
 import type { AssistantMessageDiagnostic } from "./diagnostics.js";
 import type { RepetitionEvent } from "../../brain/repetition.js";
+import type { ProviderCondition, ProviderConditionSource } from "../../brain/provider-dialect.js";
+import type { RequestRoute, RouteCarrierBag, RouteCredentialSource } from "../../brain/request-route.js";
+export type { RouteCredentialSource } from "../../brain/request-route.js";
+import type { ModelOutputInvalidCause } from "./tool-turns.js";
 export type KnownApi = "openai-completions" | "mistral-conversations" | "openai-responses" | "azure-openai-responses" | "openai-chatgpt-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-vertex";
 export type Api = KnownApi | (string & {});
 export type KnownImagesApi = "openrouter-images";
@@ -383,6 +387,19 @@ export interface UserMessage {
      */
     actor?: ActorAssertion;
 }
+/** A cut turn's output-cap facts: the lane's own cap stop fired, the output the provider counted, the cap the request
+ *  carried. The cap cut the call when `capStop` or `outputTokens >= capTokens`. */
+export interface OutputLimit {
+    capStop: boolean;
+    outputTokens?: number;
+    capTokens?: number;
+}
+/** Why a turn's tool calls could not be executed: the drop cause (`truncated` wins over `unnamed`); `outputLimit` rides
+ *  with `truncated`. */
+export interface ModelOutputInvalid {
+    cause: ModelOutputInvalidCause;
+    outputLimit?: OutputLimit;
+}
 export interface AssistantMessage {
     role: "assistant";
     content: (TextContent | ThinkingContent | ToolCall)[];
@@ -439,12 +456,24 @@ export interface AssistantMessage {
      * `error.type`) — e.g. `invalid_request_error`, `context_length_exceeded`. Only meaningful together with
      * {@link isApiErrorMessage}; provider vocabulary, never an engine closed set.
      *
-     * PRESENCE: only beside a 4xx {@link apiErrorStatus} (the provider refused the request as sent) whose envelope stated
-     * such a word in the provider echo shape (visible ASCII, 1–128 characters). ABSENT otherwise — any other status, a
-     * plain-text or torn body, an envelope with neither member, or a word outside the shape (dropped whole, never
-     * truncated). The run's `terminal.detail.code` is this value.
+     * PRESENCE: beside a 4xx {@link apiErrorStatus} (the provider refused the request as sent) or an in-band error
+     * frame (no status), whose envelope stated such a word in the provider echo shape (visible ASCII, 1–128
+     * characters). ABSENT otherwise — any other status, a plain-text or torn body, an envelope with neither member, or
+     * a word outside the shape (dropped whole, never truncated). The run's `terminal.detail.code` is this value.
      */
     apiErrorCode?: string;
+    /** The provider-condition verdict of this failure (`PROVIDER_CONDITIONS`, judged off `brain/provider-dialect.ts`),
+     *  with {@link isApiErrorMessage}; on a 4xx it is also `terminal.detail.providerCondition`. PRESENCE: every failure
+     *  the provider stated (an HTTP failure status, an in-band error frame); absent ⇒ not judged, read as `unknown`. */
+    providerCondition?: ProviderCondition;
+    /** Its evidence word, beside it. */
+    providerConditionSource?: ProviderConditionSource;
+    /** With `quota_exhausted` whose evidence stated it: when the quota lifts (wall-clock epoch ms). */
+    providerResetAtMs?: number;
+    /** The failing request's route as its brain stated it ({@link RequestRoute}; never a key value or a URL); on a 4xx also
+     *  `terminal.detail.route`. PRESENCE: beside {@link isApiErrorMessage} on an engine-minted provider failure whose
+     *  committed request stated one; absent on success, an abort, a refusal minted before any request was built. */
+    apiErrorRoute?: RequestRoute;
     diagnostics?: AssistantMessageDiagnostic[];
     usage: Usage;
     /** TB 尸检 T1-5: the provider never delivered a usage frame for this message (e.g. a
@@ -483,15 +512,21 @@ export interface AssistantMessage {
      *  stamping obligation above extends to this member for cuts a Brain can classify structurally,
      *  but unlike the two cut kinds there is no retired fallback: prose detection still works). */
     errorKind?: "length_empty" | "degenerate" | "input_too_long";
-    /** design/374 slice 2, the AUTHORITATIVE-NEGATIVE twin of `errorKind: "input_too_long"`: the
-     *  brain's provenance-checked classifier RAN and ruled this failure NOT input-too-long (wrong
-     *  status family, or the provider's own diagnostic envelope states a different error). The
-     *  loop's prompt-too-long recovery treats it as a hard negative and SKIPS its prose fallback —
-     *  a "prompt is too long" sentence reflected inside an unrelated error body must never drive a
-     *  context-shrinking recovery (adversarial-review r1). Absent = classification could not
-     *  establish provenance (prose-only gateway, truncated body, non-classifying custom Brain), and
-     *  the historic prose fallback keeps its reach. Mutually exclusive with the positive stamp. */
+    /** The AUTHORITATIVE-NEGATIVE twin of `errorKind: "input_too_long"`: the brain's provenance-checked
+     *  classifier RAN and ruled this failure NOT input-too-long (wrong status family, or the provider's
+     *  own envelope states a different error). The loop's prompt-too-long recovery treats it as a hard
+     *  negative and skips its prose fallback — a "prompt is too long" sentence reflected inside an
+     *  unrelated error body must never shrink a context. Absent = no provenance (prose-only gateway,
+     *  non-classifying custom Brain): the prose fallback keeps its reach unless `errorBodyIncomplete`.
+     *  Mutually exclusive with the positive stamp. */
     inputTooLongRuledOut?: true;
+    /** The provider's error body did not end (cut at the read bound, torn): nothing was read from it — no verdict,
+     *  `apiErrorCode` or context-limit reading, nor the loop's prose fallback over `errorMessage`; a status reading stands. */
+    errorBodyIncomplete?: true;
+    /** The turn failed because its tool calls could not be executed ({@link ModelOutputInvalid}) — the structured twin of
+     *  that `errorMessage` sentence; `terminal.detail` `model_output_invalid` when the turn names the run's result.
+     *  PRESENCE: only on that `stopReason: "error"` turn (no louder cause won it); never beside {@link isApiErrorMessage}. */
+    modelOutputInvalid?: ModelOutputInvalid;
     /**
      * design/124 tier A: this final message was PARTIALLY FINALIZED after a mid-stream connection
      * loss/stall — the substantive streamed prefix (text and/or completed tool calls) was promoted to
@@ -505,6 +540,17 @@ export interface AssistantMessage {
      * trailing call was already dropped by the finalize malformed path). Additive — absent everywhere else.
      */
     partialFinalized?: true;
+    /** A stream-end word (`finish_reason`) outside the set the brain reads, in the echo shape (`?` past it): the turn
+     *  is kept, the Runner announces it (`route.finish_reason_unknown`), a completed run states it on `terminal.detail`. */
+    finishReasonUnknown?: string;
+    /** Frames after the stream's first terminal statement (which decided this turn) that were not acted on — a later
+     *  ending (finish / stop reason), error or content — announced by the Runner (`route.stream_end_ignored`): the
+     *  first one's kind and word (echo shape, `?` past it; for content, its kind), and how many came. */
+    streamEndIgnored?: {
+        statement: "ending" | "error" | "content";
+        word: string;
+        frames: number;
+    };
     /**
      * Degenerate-repetition telemetry for THIS call (2026-07-10: counts + detected segment, not just
      * a boolean). `cut` = the event that cancelled the stream (always paired with the DEGENERATE_MESSAGE
@@ -884,16 +930,6 @@ export interface ImagesModel<TApi extends ImagesApi = ImagesApi> extends Omit<Mo
     provider: ImagesProvider;
     output: ("text" | "image")[];
 }
-/** Where the credential a request would carry came from.
- *  - `"per-model"` — resolved FOR this model: a per-call key/headers from the per-model auth hook
- *    (`getApiKeyAndHeaders`), or an auth-bearing header declared on `Model.headers`. Paired by
- *    construction (the resolver was asked about THIS entry), so the adjudicator never refuses it.
- *  - `"deployment-config"` — the brain construction-time fallback (`config.apiKey` / an auth header
- *    in `config.headers`). Paired only with the deployment's own declared root (`config.baseUrl`).
- *  - `"absent"` — no credential anywhere. Legal for keyless gateways; refused only where an entry
- *    declares its OWN URL away from a declared deployment root (a distinct endpoint with no
- *    credential route is a configuration hole, not a keyless deployment). */
-export type RouteCredentialSource = "per-model" | "deployment-config" | "absent";
 /** The resolved credential a request would carry, tagged with its source (see {@link RouteCredentialSource}). */
 export interface RouteCredential {
     source: RouteCredentialSource;
@@ -906,7 +942,7 @@ export interface RouteCredential {
     /** Which header bag carries a headers-borne credential (resolution precedence:
      *  options > model > config; the apiKey knob outranks headers within options, while the config's
      *  knob+header pair counts as ONE deployment credential — see `resolveRouteCredential`). */
-    carrierBag?: "options" | "model" | "config";
+    carrierBag?: RouteCarrierBag;
 }
 /** The deployment half of the pairing judgment: the brain construction config's DECLARED root.
  *  Absent/empty ⇒ the deployment did not declare its credential's URL half (the unpinned

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

@@ -1,5 +1,6 @@
 import { findToolByName, validateToolArguments } from "../llm/index.js";
 import { truncateError } from "../../core/tool-errors.js";
+import { judgeToolNameMiss, mountedToolNames } from "../../core/tool-name-aliases.js";
 import { INTERRUPTED_BY_USER_FOR_TOOL_USE_MARKER, INTERRUPTED_BY_USER_MARKER, } from "../../core/session-reconcile.js";
 import { resolveAgentCoreStreamFn } from "./runtime-deps.js";
 import { isErrorLike, readMember, thrownMarksOf, thrownText } from "../../core/thrown-value.js";
@@ -137,6 +138,8 @@ function defaultDetectPromptTooLong(message) {
         return true;
     if (message.inputTooLongRuledOut === true)
         return false;
+    if (message.errorBodyIncomplete === true)
+        return false;
     return PROMPT_TOO_LONG_RE.test(message.errorMessage ?? "");
 }
 function createPtlWithholdBuffer(emit, detect) {
@@ -1296,10 +1299,21 @@ function validationRefusedOutcome(tool, refusal) {
 async function prepareToolCall(currentContext, assistantMessage, toolCall, config, signal) {
     const tool = findToolByName(currentContext.tools, toolCall.name);
     if (!tool) {
-        const availableTools = (currentContext.tools ?? []).map((t) => t.name);
+        const tools = currentContext.tools ?? [];
+        const availableTools = tools.map((t) => t.name);
+        const miss = judgeToolNameMiss(toolCall.name, mountedToolNames(tools));
+        const retiredClause = miss.kind === "expected-absent" ? ` That name is retired: ${miss.detail}.` : "";
         return {
             kind: "immediate",
-            result: createErrorToolResult(`Tool ${toolCall.name} not found.${formatRosterRecovery(availableTools)}`, { details: { code: "tool.not_found", toolName: toolCall.name, availableTools } }),
+            result: createErrorToolResult(`Tool ${toolCall.name} not found.${retiredClause}${formatRosterRecovery(availableTools)}`, {
+                details: {
+                    code: "tool.not_found",
+                    toolName: toolCall.name,
+                    availableTools,
+                    absence: miss.kind,
+                    ...(miss.kind === "expected-absent" ? { detail: miss.detail, ...(miss.successor !== undefined ? { successor: miss.successor } : {}) } : {}),
+                },
+            }),
             isError: true,
         };
     }

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 { createSessionId, createTimestamp, getEntriesToFork, toSession } from "./repo-utils.js";
+import { assertForkTarget, createSessionId, createTimestamp, forkRowCells, getEntriesToFork, incarnationCell, toSession } from "./repo-utils.js";
 export class InMemorySessionRepo {
     sessions = new Map();
     async create(options = {}) {
@@ -13,6 +13,7 @@ export class InMemorySessionRepo {
         const metadata = {
             id: options.id ?? createSessionId(),
             createdAt: createTimestamp(),
+            ...incarnationCell(undefined),
         };
         const storage = new InMemorySessionStorage({ metadata });
         const session = toSession(storage);
@@ -33,12 +34,13 @@ export class InMemorySessionRepo {
         this.sessions.delete(metadata.id);
     }
     async fork(sourceMetadata, options) {
+        assertForkTarget(sourceMetadata.id, options.id);
         const source = await this.open(sourceMetadata);
         const forkedEntries = await getEntriesToFork(source.getStorage(), options);
         const metadata = {
             id: options.id ?? createSessionId(),
             createdAt: createTimestamp(),
-            forkedFrom: sourceMetadata.id,
+            ...forkRowCells(await source.getMetadata()),
         };
         const storage = new InMemorySessionStorage({ metadata, entries: forkedEntries });
         const session = toSession(storage);
@@ -52,7 +54,13 @@ export class InMemorySessionRepo {
     async importEntries(sessionId, owner, entries, options) {
         void owner;
         const validated = validateEntriesForImport(entries, options);
-        const metadata = { id: sessionId, createdAt: createTimestamp() };
+        let prior = this.sessions.get(sessionId);
+        let header = prior !== undefined ? await prior.getMetadata() : undefined;
+        while (this.sessions.get(sessionId) !== prior) {
+            prior = this.sessions.get(sessionId);
+            header = prior !== undefined ? await prior.getMetadata() : undefined;
+        }
+        const metadata = { id: sessionId, createdAt: createTimestamp(), ...incarnationCell(header) };
         this.sessions.set(sessionId, toSession(new InMemorySessionStorage({ metadata, entries: validated })));
     }
 }

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

@@ -1,6 +1,14 @@
 import { 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.
+ *  `existing` = the row before the write (`undefined`: none). A new row gets a fresh random v4 token (no time, no host); an
+ *  existing row keeps exactly what it had, including nothing (no token is minted for an occupant that predates the cell). */
+export declare function incarnationCell(existing: Pick<SessionMetadata, "incarnation"> | undefined): Pick<SessionMetadata, "incarnation">;
+/** 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">;
 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

@@ -1,9 +1,22 @@
 import { SessionError, } from "../harness/types.js";
 import { StoredSession } from "./session.js";
 import { uuidv7 } from "./uuid.js";
+import { randomUUID } from "node:crypto";
 export function createSessionId() {
     return uuidv7();
 }
+export function incarnationCell(existing) {
+    if (existing === undefined)
+        return { incarnation: randomUUID() };
+    return existing.incarnation !== undefined ? { incarnation: existing.incarnation } : {};
+}
+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 createTimestamp() {
     return new Date().toISOString();
 }