@modelprofile.com/flexharness 9.4.0 → 9.6.0

package/ts/errors.ts

@@ -44,6 +44,17 @@ export class FlexHarnessSessionBusyError extends FlexHarnessError {
   }
 }
 
+/** An operation would change the history or model context of an imported, read-only session. */
+export class FlexHarnessImportedSessionError extends FlexHarnessError {
+  public readonly sessionId: string;
+
+  constructor(sessionId: string) {
+    super('FLEX_SESSION_READ_ONLY', `Session "${sessionId}" is an imported conversation and is read-only.`);
+    this.name = 'FlexHarnessImportedSessionError';
+    this.sessionId = sessionId;
+  }
+}
+
 export class FlexHarnessSlashCommandUnavailableError extends FlexHarnessError {
   public readonly commandName: string;
   public readonly unavailableReason: string;

package/ts/interfaces.ts

@@ -169,8 +169,129 @@ export interface IFlexSession {
   parentToolCallId?: string;
   agent?: string;
   depth?: number;
+  /** Set only on a session the staged session import created; such a session is read-only. */
+  origin?: IFlexSessionOrigin;
 }
 
+/** The position of an imported session when one source conversation was split into several sessions. */
+export interface IFlexSessionImportPart {
+  /** Zero-based position of this session among the parts. */
+  index: number;
+  /** The number of parts the source was split into. */
+  count: number;
+}
+
+/** What an import caller states about the source of the history it imports. */
+export interface IFlexSessionImportSource {
+  /** The kind of source, for example `claude-code-transcript`. */
+  source: string;
+  /** The source's own identifier of the conversation. */
+  sourceId: string;
+  /** The caller's digest of the source content; a changed source has a changed digest. */
+  digest: string;
+  part?: IFlexSessionImportPart;
+  /** Source-specific metadata, for example the source working directory or what the conversion lost. */
+  details?: IJsonObject;
+}
+
+/** Where an imported session's history came from. */
+export interface IFlexSessionOrigin extends IFlexSessionImportSource {
+  kind: 'import';
+  /** When FlexHarness committed the import. */
+  importedAt: string;
+}
+
+/** The imported parent session, run and tool call an imported child session belongs to. */
+export interface IFlexSessionImportParent {
+  sessionId: string;
+  runId: string;
+  toolCallId: string;
+  agent: string;
+}
+
+export interface IFlexBeginSessionImportOptions {
+  /** Caller-chosen and deterministic, so a repeated import finds the earlier one. */
+  sessionId: string;
+  title?: string;
+  /** When the source conversation started, as `Date.prototype.toISOString()` renders it. */
+  createdAt: string;
+  /** When the source conversation last changed; defaults to `createdAt`. */
+  updatedAt?: string;
+  origin: IFlexSessionImportSource;
+  parent?: IFlexSessionImportParent;
+}
+
+export interface IFlexSessionImportHandle {
+  importId: string;
+  scopeId: string;
+  sessionId: string;
+}
+
+export interface IFlexSessionImportStarted {
+  status: 'started';
+  handle: IFlexSessionImportHandle;
+}
+
+/**
+ * A session with the same source, source id and part already exists. `already_imported` means its
+ * digest equals the requested one; `digest_mismatch` means the source changed since that import.
+ */
+export interface IFlexSessionImportExisting {
+  status: 'already_imported' | 'digest_mismatch';
+  session: IFlexSession;
+}
+
+export type TFlexBeginSessionImportResult = IFlexSessionImportStarted | IFlexSessionImportExisting;
+
+/** One imported run: a user message and the assistant message that answered it. */
+export interface IFlexImportedRun {
+  user: IFlexMessage;
+  assistant: IFlexMessage;
+}
+
+export interface IFlexSessionImportProgress {
+  runs: number;
+  messages: number;
+  bytes: number;
+}
+
+export interface IFlexSessionImportLimits {
+  /** Staged imports open at once in one FlexHarness. */
+  maxOpenImports?: number;
+  /** Messages in one imported session, two per run. */
+  maxMessagesPerSession?: number;
+  /** JSON bytes of all messages of one imported session. */
+  maxSessionBytes?: number;
+  /** JSON bytes of the runs one `appendImportedRuns()` call carries. */
+  maxPageBytes?: number;
+  /**
+   * Milliseconds a staged import may stay without an `appendImportedRuns()` call. An expired
+   * import is discarded as if it were aborted, which frees its slot and its staged memory.
+   */
+  stagedImportIdleTimeoutMs?: number;
+}
+
+/** JSON bytes of one imported message; a larger message could not be read back whole. */
+export const FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES = 480 * 1024;
+export const FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES = 16 * 1024;
+export const FLEX_SESSION_IMPORT_MAX_DEPTH = 8;
+
+export const FLEX_SESSION_IMPORT_DEFAULT_LIMITS = Object.freeze({
+  maxOpenImports: 2,
+  maxMessagesPerSession: 2048,
+  maxSessionBytes: 64 * 1024 * 1024,
+  maxPageBytes: 1024 * 1024,
+  stagedImportIdleTimeoutMs: 5 * 60 * 1000,
+});
+
+export const FLEX_SESSION_IMPORT_MAXIMUM_LIMITS = Object.freeze({
+  maxOpenImports: 64,
+  maxMessagesPerSession: 20_000,
+  maxSessionBytes: 256 * 1024 * 1024,
+  maxPageBytes: 1536 * 1024,
+  stagedImportIdleTimeoutMs: 60 * 60 * 1000,
+});
+
 export interface IFlexCreateSessionOptions {
   sessionId?: string;
   sessionGenerationId?: string;
@@ -349,6 +470,12 @@ export interface IFlexMessagePageOptions {
 
 export interface IFlexMessagePage {
   messages: IFlexMessage[];
+  /**
+   * Zero-based index of `messages[0]` in the session's visible history; for an empty page, the
+   * index the page ends at. Appending messages leaves it unchanged, while a branch after an undo
+   * reuses the positions of the history it replaces (`session.history.changed`).
+   */
+  startIndex: number;
   nextCursor?: string;
 }
 
@@ -460,6 +587,8 @@ export interface IFlexSessionTombstone {
   depth?: number;
   parentSessionId?: string;
   subagent?: IFlexSubagentProvenance;
+  /** Set when the session was imported; its deletion then writes no project-management tombstone. */
+  imported?: true;
 }
 
 export interface IFlexScopeSnapshot {
@@ -1134,6 +1263,7 @@ export interface IFlexHarnessOptions<TScope> {
   callbackLimits?: IFlexCallbackLimits;
   promptQueueLimits?: IFlexPromptQueueLimits;
   reversionLimits?: IFlexReversionLimits;
+  sessionImportLimits?: IFlexSessionImportLimits;
   /**
    * Bounds each turn-reversion maintenance operation. Falls back to
    * agentSessionPolicy.generationLeaseCleanupTimeoutMs, then 30 seconds.

package/ts/readme.md

@@ -235,6 +235,13 @@ const harness = new FlexHarness<IProjectScope>({
     maxExcludedRunIds: 1000,
     maxPendingReversionReleases: 1000,
   },
+  sessionImportLimits: {
+    maxOpenImports: 2,
+    maxMessagesPerSession: 2048,
+    maxSessionBytes: 64 * 1024 * 1024,
+    maxPageBytes: 1024 * 1024,
+    stagedImportIdleTimeoutMs: 5 * 60 * 1000,
+  },
   subagents: [
     {
       name: 'researcher',
@@ -601,9 +608,9 @@ Queue payloads, status records, and `prompt.*` queue events are process-local. T
 
 The reservation save is the admission point. A save failure produces no start events or active audit. If disposal begins while that save is in flight and the save commits, admission still resolves and its completion settles as cancelled; disposal waits for terminal finalization.
 
-`listMessagePage()` returns the newest contiguous page in chronological order. `limit` must be an integer from 1 through 50 and defaults to 50. `nextCursor` is opaque, limited to 4096 UTF-8 bytes, bound to the resolved storage namespace and session, and remains stable when newer messages are appended. Mismatched and stale cursors fail validation. `getMessage()` performs an exact lookup. Transfer identifiers are limited to 512 bytes, text and reasoning parts to 96 KiB, complete messages to 480 KiB, and complete page envelopes to 512 KiB. A page may therefore contain fewer messages than requested. Oversized text is truncated and an otherwise oversized parts collection is replaced with an explicit elision marker; metadata that still cannot fit fails validation. Canonical private Agent events are unchanged.
+`listMessagePage()` returns the newest contiguous page in chronological order. `limit` must be an integer from 1 through 50 and defaults to 50. `nextCursor` is opaque, limited to 4096 UTF-8 bytes, bound to the resolved storage namespace and session, and remains stable when newer messages are appended. Mismatched and stale cursors fail validation. Each page carries `startIndex`, the zero-based index of its first message in the session's visible history (for an empty page, the index the page ends at), so a consumer can order and page by absolute position. Appending messages leaves every index unchanged; a branch after an undo reuses the positions of the history it replaces, so a consumer re-reads its pages after `session.history.changed`. `getMessage()` performs an exact lookup. Transfer identifiers are limited to 512 bytes, text and reasoning parts to 96 KiB, complete messages to 480 KiB, and complete page envelopes to 512 KiB. A page may therefore contain fewer messages than requested. Oversized text is truncated and an otherwise oversized parts collection is replaced with an explicit elision marker; metadata that still cannot fit fails validation. Canonical private Agent events are unchanged.
 
-`updateSession()` supports title replacement, explicit title clearing with `null`, and archive state through `archived`. Title-only updates remain available while prompts are queued or running, while permission is pending, and after archival. Requests containing `archived` are rejected while the session has any outstanding prompt or pending permission; a mixed title-and-archive request is rejected atomically without changing the title. Archived sessions expose `archivedAt`. Deleting a session cascades through its complete descendant subtree. One durable root-keyed tombstone group hides every newly affected live session, and the delete also joins any already-separate descendant cleanup groups without rewriting their roots. FlexHarness then cancels queued and active subtree work, emits terminal queue events, waits for admitted initialization, and purges runtime queue status while cleaning runtime and persisted domains child-first. The requested root tombstone is removed last after every domain confirms cleanup; project-management cleanup confirmation is a retained durable project tombstone rather than physical removal. A successful live `deleteSession()` call emits `session.deleted` for each session it newly tombstoned; retries of an existing tombstone and automatic load, retirement, or disposal cleanup emit no deletion events. Direct deletion of a descendant cascades only through that descendant's subtree. Cleanup authority follows the resolved storage namespace, so scope aliases share the same groups. A partial failure retains durable ownership for retry by a later `deleteSession()`, namespace load, `retireScope()`, or `dispose()` call.
+`updateSession()` supports title replacement, explicit title clearing with `null`, and archive state through `archived`. Title-only updates remain available while prompts are queued or running, while permission is pending, and after archival. Requests containing `archived` are rejected while the session has any outstanding prompt or pending permission; a mixed title-and-archive request is rejected atomically without changing the title. Archived sessions expose `archivedAt`. Deleting a session cascades through its complete descendant subtree. One durable root-keyed tombstone group hides every newly affected live session, and the delete also joins any already-separate descendant cleanup groups without rewriting their roots. FlexHarness then cancels queued and active subtree work, emits terminal queue events, waits for admitted initialization, and purges runtime queue status while cleaning runtime and persisted domains child-first. The requested root tombstone is removed last after every domain confirms cleanup; project-management cleanup confirmation is a retained durable project tombstone rather than physical removal. An imported session can hold no project-management state, so its deletion writes no project tombstone. A successful live `deleteSession()` call emits `session.deleted` for each session it newly tombstoned; retries of an existing tombstone and automatic load, retirement, or disposal cleanup emit no deletion events. Direct deletion of a descendant cascades only through that descendant's subtree. Cleanup authority follows the resolved storage namespace, so scope aliases share the same groups. A partial failure retains durable ownership for retry by a later `deleteSession()`, namespace load, `retireScope()`, or `dispose()` call.
 
 `deleteSessionGenerationCohort()` is the generation-fenced destructive form for controllers. Its `root` and every `authorizedCohort` entry use the exact `{ sessionId, sessionGenerationId, sessionGenerationSequence }` shape. The cohort contains unique entries in strictly ascending `sessionId` order and is limited by `FLEX_SESSION_GENERATION_COHORT_MAX_ENTRIES` (2048). FlexHarness atomically validates the matching root, its complete live subtree, and every retained descendant tombstone group before reserving deletion. A missing or different root generation returns `{ matched: false }` without touching a newer generation; a missing or mismatched cascade entry throws before new tombstoning or cleanup. Extra valid entries do not expand the cascade. A matched partial cleanup remains retryable with the same authority and resolves to `{ matched: true }` when cleanup completes. The existing `deleteSession()` method remains available for callers that intentionally own the complete reusable-ID namespace.
 
@@ -783,7 +790,7 @@ Workspace reversion is generic and application-defined. It does not reverse netw
 
 Every configured value must be an integer from 1 through its hard maximum. Pruning removes complete prefixes rather than splitting an undo unit. Excluded run IDs prevent a committed branch from re-entering model context, while pending releases retain provider ownership until acknowledgement.
 
-`retireScope()` stops runtime ownership for the complete resolved storage namespace without deleting its durable snapshot. It does not load a namespace that has no cached or in-flight state. For loaded state, it preserves and waits for persistence that has already started, while later queued reads, writes, and run admissions reject with `FlexHarnessAbortError`. It cancels queued prompts and cancellable runs, rejects pending permissions, emits queue terminal events, waits for committing runs, terminal persistence, queue drains, tool-handle closure, and detached tool-provider cleanup, then purges queue status and clears and evicts the cached state. Failed cleanup ownership remains cached so a later `retireScope()` or `dispose()` call can retry it. Calls through storage-key aliases share the same retirement drain. A later call can load the durable namespace again after successful retirement if the application still resolves it.
+`retireScope()` stops runtime ownership for the complete resolved storage namespace without deleting its durable snapshot. It does not load a namespace that has no cached or in-flight state. For loaded state, it preserves and waits for persistence that has already started, while later queued reads, writes, and run admissions reject with `FlexHarnessAbortError`. It cancels queued prompts and cancellable runs, rejects pending permissions, emits queue terminal events, waits for committing runs, terminal persistence, queue drains, tool-handle closure, and detached tool-provider cleanup, then purges queue status and clears and evicts the cached state. Failed cleanup ownership remains cached so a later `retireScope()` or `dispose()` call can retry it. Calls through storage-key aliases share the same retirement drain. A later call can load the durable namespace again after successful retirement if the application still resolves it. A loaded namespace keeps every session's messages in memory, so `retireScope()` is also the supported way for a host to evict a scope it has stopped using, such as an opened archive of imported sessions. Retirement releases every staged session import and cancels queued prompts and runs, so a host retires only a scope with no open import and no work it still wants.
 
 Normal retirement-induced cancellation does not make `retireScope()` reject. Unexpected failures observed through run finalization or scoped cleanup are surfaced without dropping the resources that still require cleanup. One such failure is thrown directly; multiple failures are reported through `FlexHarnessRunError`. Calling retirement or disposal again retries retained cleanup ownership.
 
@@ -805,6 +812,82 @@ Public audit history is safe to send to controllers: attachment parts contain so
 
 Sessions expose `idle`, `scheduled`, `running`, `waiting_permission`, `failed`, and `cancelled` status. Persisted non-terminal activity is repaired from canonical Agent generation outcomes after process restart; incomplete messages and parts normalize to `cancelled` unless an accepted hidden terminal stage can be promoted.
 
+## Conversation Import
+
+A finished conversation from another tool can be imported as an archived, read-only session. The import is staged in three steps, so a large conversation crosses a process boundary in bounded pages. Turning a source format into Flex messages is the importer's job; the core validates, bounds, persists and protects the result.
+
+```typescript
+const started = await harness.beginSessionImport('project:billing', {
+  sessionId: 'claude-7f3c2a',
+  title: 'Fix the billing export',
+  createdAt: '2026-09-01T09:00:00.000Z',
+  updatedAt: '2026-09-01T11:00:00.000Z',
+  origin: {
+    source: 'claude-code-transcript',
+    sourceId: '7f3c2a',
+    digest: 'sha256:9b1d…',
+    details: { cwd: '/workspace' },
+  },
+});
+
+if (started.status === 'started') {
+  try {
+    for (const page of pages) {
+      await harness.appendImportedRuns(started.handle, page);
+    }
+    const session = await harness.commitSessionImport(started.handle);
+  } finally {
+    await harness.abortSessionImport(started.handle);
+  }
+}
+```
+
+- **`beginSessionImport(scopeId, options)`** validates the options and reserves the caller-chosen `sessionId`. Choose a deterministic id, derived from the source. The result is one of three:
+  - `started`, with a handle `{ importId, scopeId, sessionId }`;
+  - `already_imported`, with the existing session;
+  - `digest_mismatch`, with the existing session.
+
+  A scope holds at most one import per `origin.source`, `origin.sourceId` and `origin.part.index`, whatever its session id. `already_imported` means that session has the same `origin.digest`, so the caller skips it. `digest_mismatch` means the source changed since; the caller deletes that session and imports again. A staged import of the same session id or source identity throws `FlexHarnessSessionBusyError`. Until the commit completes, `listSessions()` omits the session and `createSession()` refuses its id. While the import is staged, `getSession()` throws `FlexHarnessSessionBusyError`. While its commit runs, `getSession()` throws `FlexHarnessNotFoundError`, because a deletion tombstone reserves the id.
+- **`appendImportedRuns(handle, runs)`** stages one page of runs, in order. A run is `{ user, assistant }`, two messages of the exact `IFlexMessage` shape. Both belong to the imported session, share one `runId` and one terminal status (`completed`, `failed` or `cancelled`), and have no `running` reasoning or tool part. Timestamps are ISO 8601 as `Date.prototype.toISOString()` renders them. Run ids and message ids are unique within the import. A page that breaks a rule or a bound stages nothing, and the import stays open. The result reports the staged `runs`, `messages` and `bytes`.
+- **`commitSessionImport(handle)`** persists the runs and publishes the session, with one `session.created` event:
+  - `origin` is `{ kind: 'import', source, sourceId, digest, part?, details?, importedAt }`, and `archivedAt` equals `importedAt`;
+  - `createdAt` and `updatedAt` are the ones passed to `beginSessionImport()`, and the status is `idle`.
+
+  The commit first persists a deletion tombstone for the id, then writes the projection, then replaces the tombstone with the session in one scope save. A failed commit removes what it persisted through the normal tombstone cleanup. After a crash, or a save whose outcome is uncertain, the next load of the namespace resolves it: a surviving tombstone is cleaned up, and a published session is kept. A commit needs at least one run.
+- **`abortSessionImport(handle)`** discards a staged import. Nothing of it was persisted. An unknown or finished handle is ignored, so the call is safe in a `finally`. A staged import that receives no `appendImportedRuns()` call for `stagedImportIdleTimeoutMs` expires and is discarded the same way; its handle then reports `FlexHarnessNotFoundError`.
+- **Child sessions.** `parent: { sessionId, runId, toolCallId, agent }` imports a child session, such as a subagent's conversation. The parent must be a committed imported session in the same scope. Its assistant message of `runId` must hold the tool call `toolCallId` whose `childSessionId` names the child. No other session may claim that tool call. The child gets `depth` one below its parent, at most `FLEX_SESSION_IMPORT_MAX_DEPTH` (8). Deleting the parent deletes its children.
+
+**Read-only.** An imported session never runs, and nothing writes model context for it: it has no Agent events and no tool jobs. Every operation that would change its history or model context throws `FlexHarnessImportedSessionError` (code `FLEX_SESSION_READ_ONLY`):
+
+- `prompt`, `startPrompt`, `enqueuePrompt` and `schedulePrompt`;
+- `executeSlashCommand` and `compactSession`;
+- `undoSession` and `redoSession`;
+- `pushRuntimeEvent`, `reconcileToolExecution` and `archiveSessionEvents`;
+- the project-management writes: tasks, goal and scratchpad.
+
+`listSlashCommands()` reports every command unavailable with the reason `Session is an imported conversation and is read-only.` Reads work: sessions, messages, message pages, reversion info and project state. So do `updateSession()` (title and archived flag), `deleteSession()` and `deleteSessionGenerationCohort()`. A load never repairs an imported session's runs from Agent generation outcomes, because it has none.
+
+**Bounds.** `sessionImportLimits` sets the bounds; each must be an integer from 1 through its maximum:
+
+| Limit | Default | Maximum |
+|---|---|---|
+| `maxOpenImports` (staged imports at once, per harness) | 2 | 64 |
+| `maxMessagesPerSession` | 2048 | 20000 |
+| `maxSessionBytes` (JSON bytes of all messages) | 64 MiB | 256 MiB |
+| `maxPageBytes` (JSON bytes of one `appendImportedRuns()` page) | 1 MiB | 1.5 MiB |
+| `stagedImportIdleTimeoutMs` (idle time before a staged import expires) | 5 minutes | 1 hour |
+
+Some bounds are fixed:
+
+- one message is at most `FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES` (480 KiB), and must read back through the message transfer limits;
+- `origin.details` is a JSON object of at most `FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES` (16 KiB);
+- `origin.source` is at most 128 UTF-8 bytes, `origin.sourceId` 512 and `origin.digest` 256, none with control characters;
+- `origin.part` has a `count` from 1 through 1024 and a zero-based `index` below it.
+
+Staged runs are held in memory until the commit, so the memory of open imports is bounded by `maxOpenImports` × `maxSessionBytes`. Retiring the scope, disposing the harness or the idle expiry discards staged imports. The expiry timer does not keep the process alive.
+
+**Stores.** The import adds no store method. Scope snapshots carry the optional session `origin`, and a store that validates session keys exactly must accept it. The commit writes the whole projection in one save at revision 1. FlexHarness versions before 9.5.0 reject the new key under their strict reader, so a downgrade over imported sessions is unsupported. The tombstone that reserves an import, or that deletes an imported session, carries the optional `imported: true`, and a store that validates tombstone keys exactly must accept it. FlexHarness 9.5.x rejects a scope snapshot that holds such a tombstone; one exists only while an import commits or an imported session is deleted, or after either was interrupted.
+
 ## Permissions
 
 Tools request permission through the run-scoped provider context:

package/ts/utils.json.ts

@@ -494,10 +494,12 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
       'parentToolCallId',
       'agent',
       'depth',
+      'origin',
     ],
     path,
   );
   requireString(session.scopeId, `${path}.scopeId`);
+  if (session.origin !== undefined) validateSessionOrigin(session.origin, `${path}.origin`);
   const sessionId = requireString(session.sessionId, `${path}.sessionId`);
   const generation = validateOptionalSessionGeneration(session, path);
   requireOptionalString(session.title, `${path}.title`);
@@ -555,6 +557,41 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   };
 }
 
+function validateSessionOrigin(value: unknown, path: string): void {
+  const origin = requireRecord(value, path);
+  requireOnlyKeys(
+    origin,
+    ['kind', 'source', 'sourceId', 'digest', 'importedAt', 'part', 'details'],
+    path,
+  );
+  if (origin.kind !== 'import') {
+    throw new FlexHarnessStoreFormatError(`${path}.kind is invalid.`);
+  }
+  requireString(origin.source, `${path}.source`);
+  requireString(origin.sourceId, `${path}.sourceId`);
+  requireString(origin.digest, `${path}.digest`);
+  requireString(origin.importedAt, `${path}.importedAt`);
+  if (origin.part !== undefined) {
+    const part = requireRecord(origin.part, `${path}.part`);
+    requireOnlyKeys(part, ['index', 'count'], `${path}.part`);
+    requireNonNegativeInteger(part.index, `${path}.part.index`);
+    requireNonNegativeInteger(part.count, `${path}.part.count`);
+    if (Number(part.index) >= Number(part.count)) {
+      throw new FlexHarnessStoreFormatError(`${path}.part.index must be below part.count.`);
+    }
+  }
+  if (origin.details !== undefined) requireRecord(origin.details, `${path}.details`);
+}
+
+/**
+ * Asserts the exact stored shape of one public message: its keys, part kinds and field types.
+ * Throws `FlexHarnessStoreFormatError`.
+ */
+export function assertFlexMessageRecord(value: unknown, path: string): void {
+  assertJsonSerializable(value, path);
+  validateMessage(value, path);
+}
+
 function validateSubagentProvenance(
   value: unknown,
   path: string,
@@ -905,6 +942,7 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
         'depth',
         'parentSessionId',
         'subagent',
+        'imported',
       ],
       path,
     );
@@ -930,6 +968,9 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
         `${path}.subagent does not match its parentSessionId.`,
       );
     }
+    if (tombstone.imported !== undefined && tombstone.imported !== true) {
+      throw new FlexHarnessStoreFormatError(`${path}.imported must be true when present.`);
+    }
     const hasRoot = tombstone.rootSessionId !== undefined;
     const hasDepth = tombstone.depth !== undefined;
     if (hasRoot !== hasDepth) {