maka-agent 0.2.0-dev.26.20260909 → 0.2.0-dev.28.20260911

package/node_modules/@maka/storage/dist/session-bundle-policy.js

@@ -16,15 +16,36 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-import { copyFile, lstat, mkdir, readdir, realpath, rename, rm } from 'node:fs/promises';
+import { copyFile, link, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, unlink, writeFile, } from 'node:fs/promises';
+import { constants } from 'node:fs';
 import { randomUUID } from 'node:crypto';
-import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { decodeArtifactRecordJsons } from './artifact-metadata-codec.js';
-import { withArtifactWriterLock } from './artifact-writer-lock.js';
+import { withArtifactWriterLock, withLeaseBoundArtifactWriterLock, } from './artifact-writer-lock.js';
+import { syncDirectoryChain } from './stable-storage.js';
+import { prepareArtifactWriterLockAuthorityForLease, } from './root-authority.js';
+/**
+ * Holds the Artifact writer lock for the root the caller is authorised over.
+ *
+ * Without a lease the root is named by a path, and the lock is derived from
+ * that path again after the authority was checked. A lease says which root the
+ * authority covers, so deriving the lock from the lease keeps the two from
+ * drifting: an alias or a replaced directory between the two steps would
+ * otherwise bind the operation to one root while the lease names another --
+ * including an unmarked one, which takes no lock at all.
+ */
+async function withBundleArtifactWriterLock(stateRoot, lease, operation) {
+    if (!lease)
+        return withArtifactWriterLock(stateRoot, operation);
+    const authority = await prepareArtifactWriterLockAuthorityForLease(lease, 'interactive');
+    return withLeaseBoundArtifactWriterLock(authority, () => operation(lease.canonicalPath));
+}
+import { runWithContextValueMutation } from './context-value-mutation-gate.js';
 import { withOfflineContextSnapshot, copyContextSnapshot, validateContextSnapshot, planContextSnapshotFiles, } from './context-offload-snapshot.js';
 import { CONTEXT_OFFLOAD_DATABASE_NAME, CONTEXT_OFFLOAD_VALUES_DIRECTORY_NAME, } from './sqlite-context-offload-store.js';
-import { acquireOperationalStateDatabase, OPERATIONAL_STATE_DATABASE_NAME, } from './operational-state-store.js';
+import { acquireOperationalStateDatabase, inspectOperationalStateSchema, OPERATIONAL_STATE_DATABASE_NAME, OperationalStateMigrationBlockedError, } from './operational-state-store.js';
+import { TERMINAL_RUNTIME_EVENT_SQL } from './runtime-transcript-query.js';
 import { isSafeStorageId } from './storage-id.js';
 export const SESSION_BUNDLE_STATE_ENTRIES = [
     'artifacts',
@@ -54,10 +75,18 @@ export async function planSessionBundleExport(input) {
     assertRootsSeparate(stateRoot, configRoot, input.allowShared === true);
     assertRootsSeparate(stateRoot, destinationRoot, false);
     assertRootsSeparate(configRoot, destinationRoot, false);
-    const databasePath = resolve(stateRoot, OPERATIONAL_STATE_DATABASE_NAME);
+    // Everything below is derived from `input.databasePath` -- the private copy
+    // the caller has already taken -- and never from the live database. The
+    // artifact and context locks do not fence ordinary Session and runtime
+    // writers, so a subtree, an artifact list and a manifest read from the live
+    // file would describe a different moment than the database that ships.
+    const databasePath = input.databasePath ?? resolve(stateRoot, OPERATIONAL_STATE_DATABASE_NAME);
     await assertRegularFile(databasePath, OPERATIONAL_STATE_DATABASE_NAME);
     const database = new DatabaseSync(databasePath, { readOnly: true });
     let artifacts;
+    let sessionIds;
+    let sourceSchema;
+    let connection;
     try {
         const session = database
             .prepare('SELECT 1 AS present FROM session_metadata WHERE session_id = ?')
@@ -65,10 +94,23 @@ export async function planSessionBundleExport(input) {
         if (!session) {
             throw new SessionBundleExportError('invalid_root', `Session bundle session does not exist: ${input.sessionId}`);
         }
+        sourceSchema = assertPortableSourceSchema(database);
+        sessionIds =
+            input.includeSubtree === true
+                ? collectSubagentSessionTree(database, input.sessionId)
+                : [input.sessionId];
+        const placeholders = sessionIds.map(() => '?').join(', ');
         const rows = database
-            .prepare('SELECT record_json FROM artifact_records WHERE session_id = ? ORDER BY created_at, artifact_id')
-            .all(input.sessionId);
+            .prepare(`SELECT record_json FROM artifact_records WHERE session_id IN (${placeholders}) ORDER BY created_at, artifact_id`)
+            .all(...sessionIds);
         artifacts = decodeArtifactRecordJsons(rows.map((row) => row.record_json));
+        const route = database
+            .prepare('SELECT llm_connection_slug, model FROM session_metadata WHERE session_id = ?')
+            .get(input.sessionId);
+        connection = {
+            llmConnectionSlug: String(route?.llm_connection_slug ?? ''),
+            model: String(route?.model ?? ''),
+        };
     }
     finally {
         database.close();
@@ -84,16 +126,24 @@ export async function planSessionBundleExport(input) {
     if (artifacts.length > 0) {
         entries.push({ relativePath: 'artifacts', kind: 'directory', source: 'copy' });
         for (const artifact of artifacts) {
-            if (!isArtifactPathForSession(artifact.relativePath, input.sessionId)) {
-                throw new SessionBundleExportError('path_escape', `Artifact path does not belong to session ${input.sessionId}: ${artifact.relativePath}`);
+            if (!sessionIds.some((id) => isArtifactPathForSession(artifact.relativePath, id))) {
+                throw new SessionBundleExportError('path_escape', `Artifact path does not belong to the exported subtree: ${artifact.relativePath}`);
             }
             const relativePath = `artifacts/${artifact.relativePath}`;
-            await assertRegularFile(resolve(stateRoot, relativePath), relativePath);
+            // A record naming bytes the workspace does not have would produce a
+            // bundle whose own metadata points at nothing. Reported apart from a
+            // missing state root, which is a different mistake entirely.
+            await assertRegularFile(resolve(stateRoot, relativePath), relativePath).catch((error) => {
+                if (error instanceof SessionBundleExportError && error.code === 'invalid_root') {
+                    throw new SessionBundleExportError('missing_entry', error.message, { cause: error });
+                }
+                throw error;
+            });
             entries.push({ relativePath, kind: 'file', source: 'copy' });
         }
         includedEntries.push('artifacts');
     }
-    const contextFiles = await planContextSnapshotFiles(stateRoot, input.sessionId);
+    const contextFiles = await planContextSnapshotFiles(stateRoot, sessionIds);
     for (const relativePath of contextFiles) {
         entries.push({ relativePath, kind: 'file', source: 'context_snapshot' });
     }
@@ -108,35 +158,45 @@ export async function planSessionBundleExport(input) {
         configRoot,
         destinationRoot,
         sessionId: input.sessionId,
+        sessionIds,
+        sourceSchema,
+        connection,
         includedEntries,
         excludedEntries,
         entries,
     };
 }
 export async function exportSessionBundleState(input) {
-    return withOfflineContextSnapshot(input.stateRoot, (contextLocked) => withArtifactWriterLock(input.stateRoot, async (stateRoot) => {
-        const plan = await planSessionBundleExport({ ...input, stateRoot });
-        await assertDestinationMissing(plan.destinationRoot);
-        const stagingRoot = `${plan.destinationRoot}.${process.pid}.${randomUUID()}.tmp`;
+    return withOfflineContextSnapshot(input.stateRoot, (contextLocked) => withBundleArtifactWriterLock(input.stateRoot, input.lease, async (stateRoot) => {
+        const destinationRoot = resolve(input.destinationRoot);
+        await assertDestinationMissing(destinationRoot);
+        const stagingRoot = `${destinationRoot}.${process.pid}.${randomUUID()}.tmp`;
         try {
             await mkdir(stagingRoot, { recursive: true, mode: 0o700 });
+            // Take the private copy BEFORE anything is read. `lease.backup()` is
+            // what freezes the content; every decision after this -- schema, the
+            // subtree, the artifact list, quiescence, the manifest -- is made
+            // against this one file, so the bundle cannot describe two moments.
+            const databasePath = resolveInside(stagingRoot, OPERATIONAL_STATE_DATABASE_NAME);
+            await backupOperationalState(stateRoot, databasePath);
+            const plan = await planSessionBundleExport({ ...input, stateRoot, databasePath });
             for (const entry of plan.entries) {
-                if (entry.source === 'context_snapshot')
+                if (entry.source === 'context_snapshot' || entry.source === 'filtered_runtime_sqlite') {
                     continue;
+                }
                 const destination = resolveInside(stagingRoot, entry.relativePath);
                 if (entry.kind === 'directory') {
                     await mkdir(destination, { recursive: true });
                     continue;
                 }
                 await mkdir(dirname(destination), { recursive: true });
-                if (entry.source === 'copy') {
-                    await copyFile(resolveInside(plan.stateRoot, entry.relativePath), destination);
-                }
-                else {
-                    await exportFilteredDatabase(plan.stateRoot, destination, plan.sessionId);
-                }
+                await copyArtifactFile(plan.stateRoot, entry.relativePath, destination);
             }
-            await copyContextSnapshot(stateRoot, stagingRoot, contextLocked, plan.sessionId);
+            await filterBackedUpDatabase(databasePath, plan.sessionIds, {
+                omitDiagnostics: input.omitDiagnostics === true,
+                requireQuiescent: input.requireQuiescent === true,
+            });
+            await copyContextSnapshot(stateRoot, stagingRoot, contextLocked, plan.sessionIds);
             await validateContextSnapshot(stagingRoot);
             await mkdir(dirname(plan.destinationRoot), { recursive: true });
             await rename(stagingRoot, plan.destinationRoot);
@@ -146,18 +206,100 @@ export async function exportSessionBundleState(input) {
             await rm(stagingRoot, { recursive: true, force: true }).catch(() => { });
             throw error;
         }
-    }));
+    }), input.lease ? { lease: input.lease } : {});
 }
-async function exportFilteredDatabase(stateRoot, destinationPath, sessionId) {
-    const lease = acquireOperationalStateDatabase(stateRoot);
+/**
+ * Take the private copy the whole export is derived from.
+ *
+ * `require_current` because an export must not migrate what it reads: opening
+ * the live database the ordinary way upgrades it in place, which turns a
+ * read-only operation into a write to someone else's workspace and leaves the
+ * manifest describing a version the source no longer has.
+ */
+/**
+ * Copy one artifact without leaving the state root.
+ *
+ * Checking the final component is not enough: `artifacts/<sessionId>` can
+ * itself be a symlink, and `copyFile` follows ancestors — an artifact record
+ * that decodes perfectly can then pull in a file from outside the workspace.
+ * Every segment is checked, the final open refuses to follow a link, and the
+ * bytes are read from that descriptor rather than from the name.
+ *
+ * Node has no `openat`, so a segment swapped between its check and the open is
+ * not closed here. That window is narrowed, not eliminated; closing it needs a
+ * directory-relative open this runtime does not expose.
+ */
+async function copyArtifactFile(stateRoot, relativePath, destination) {
+    const segments = relativePath.split('/').filter((segment) => segment.length > 0);
+    let walked = stateRoot;
+    for (const segment of segments) {
+        if (segment === '.' || segment === '..') {
+            throw new SessionBundleExportError('path_escape', `Artifact path segment is not safe`);
+        }
+        walked = resolveInside(walked, segment);
+        const metadata = await lstat(walked).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (!metadata) {
+            throw new SessionBundleExportError('missing_entry', `Missing ${relativePath}`);
+        }
+        if (metadata.isSymbolicLink()) {
+            throw new SessionBundleExportError('symlink', `Artifact path crosses a symlink at ${segment}`);
+        }
+    }
+    const handle = await open(walked, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stats = await handle.stat();
+        if (!stats.isFile()) {
+            throw new SessionBundleExportError('unsupported_entry', `${relativePath} is not a regular file`);
+        }
+        await writeFile(destination, handle.createReadStream());
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}
+async function backupOperationalState(stateRoot, destinationPath) {
+    // A directory with no state database is not a workspace, which is a different
+    // mistake from a workspace whose schema this build cannot read.
+    await assertRegularFile(resolveInside(stateRoot, OPERATIONAL_STATE_DATABASE_NAME), OPERATIONAL_STATE_DATABASE_NAME);
+    let lease;
+    try {
+        lease = acquireOperationalStateDatabase(stateRoot, { schemaMigration: 'require_current' });
+    }
+    catch (error) {
+        // Only a blocked migration means "this build cannot read that schema".
+        // A permission, busy or I/O failure is the environment talking, and the
+        // operational store preserves it deliberately -- flattening those into a
+        // schema verdict tells the caller to upgrade when the real answer is that
+        // the file could not be opened.
+        if (error instanceof OperationalStateMigrationBlockedError) {
+            throw new SessionBundleExportError('schema_unsupported', 'Session bundle source is not at the current schema', { cause: error });
+        }
+        throw error;
+    }
     try {
         await lease.backup(destinationPath);
     }
     finally {
         lease.close();
     }
+}
+async function filterBackedUpDatabase(destinationPath, sessionIds, options) {
     const database = new DatabaseSync(destinationPath);
     try {
+        // Quiescence is asserted here, on the copy, not on the live database.
+        // `lease.backup()` is what freezes the content; a check made before it
+        // describes a state the bundle may no longer carry, and the artifact and
+        // context locks held around this do not keep a turn from starting. This is
+        // the only place where "what was checked" and "what ships" are the same
+        // bytes.
+        if (options.requireQuiescent) {
+            for (const sessionId of sessionIds)
+                assertSessionQuiescent(database, sessionId);
+        }
         database.exec('PRAGMA foreign_keys = OFF; BEGIN IMMEDIATE');
         const tables = database
             .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'")
@@ -171,19 +313,47 @@ async function exportFilteredDatabase(stateRoot, destinationPath, sessionId) {
             const names = new Set(columns
                 .map((column) => column.name)
                 .filter((name) => typeof name === 'string'));
-            const sessionColumns = ['session_id', 'source_session_id', 'target_session_id'].filter((name) => names.has(name));
+            const sessionColumns = names.has(SESSION_ROW_OWNER_COLUMN)
+                ? [SESSION_ROW_OWNER_COLUMN]
+                : SESSION_LINK_COLUMNS.filter((name) => names.has(name));
             if (sessionColumns.length > 0) {
+                // Delete what the subtree does not own, keeping the original
+                // predicate's shape: a row survives only when EVERY session column it
+                // has names an exported Session. A link table row with one end outside
+                // the bundle would otherwise arrive pointing at a Session that is not
+                // there -- the reference is what makes it a link.
+                const placeholders = sessionIds.map(() => '?').join(', ');
                 const predicate = sessionColumns
-                    .map((name) => `${quoteIdentifier(name)} <> ?`)
+                    .map((name) => name === SESSION_ROW_OWNER_COLUMN
+                    ? // An owner that is NULL owns nothing. Such a row cannot be
+                        // attributed to any Session, so it is not this bundle's to
+                        // carry -- keeping it shipped an unattributed usage row.
+                        `(${quoteIdentifier(name)} IS NULL OR ${quoteIdentifier(name)} NOT IN (${placeholders}))`
+                    : // A link endpoint that is NULL names no counterpart, which is
+                        // not the same as naming one outside the bundle.
+                        `(${quoteIdentifier(name)} IS NOT NULL AND ${quoteIdentifier(name)} NOT IN (${placeholders}))`)
                     .join(' OR ');
                 database
                     .prepare(`DELETE FROM ${quoteIdentifier(row.name)} WHERE ${predicate}`)
-                    .run(...sessionColumns.map(() => sessionId));
+                    .run(...sessionColumns.flatMap(() => sessionIds));
             }
             else if (!PORTABLE_DERIVED_TABLES.has(row.name)) {
                 database.exec(`DELETE FROM ${quoteIdentifier(row.name)}`);
             }
         }
+        // Operational rows that describe a REQUEST rather than the conversation.
+        // None of them reach the model, and in a real Session they are the large
+        // majority of this table. The two record kinds that do decide what the
+        // model reads -- history_compact_checkpoint_recorded and
+        // model_projection_transition_recorded -- are deliberately not here.
+        if (options.omitDiagnostics) {
+            database
+                .prepare(`
+        DELETE FROM core_agent_run_events
+        WHERE event_type IN (${SESSION_BUNDLE_OMITTED_EVENT_TYPES.map(() => '?').join(', ')})
+      `)
+                .run(...SESSION_BUNDLE_OMITTED_EVENT_TYPES);
+        }
         database
             .prepare(`
       DELETE FROM tool_journal_events
@@ -224,11 +394,17 @@ async function exportFilteredDatabase(stateRoot, destinationPath, sessionId) {
         const foreignKeyViolation = database.prepare('PRAGMA foreign_key_check').get();
         if (foreignKeyViolation)
             throw new Error('Filtered session database has dangling references');
-        const session = database
-            .prepare('SELECT 1 AS present FROM session_metadata WHERE session_id = ?')
-            .get(sessionId);
-        if (!session)
-            throw new Error(`Filtered session is missing: ${sessionId}`);
+        // DELETE frees pages, it does not erase them. Without this the bundle ships
+        // a file whose freelist still holds the excluded Sessions' bytes -- readable
+        // by anyone who opens it with something other than SQL.
+        database.exec('VACUUM');
+        for (const sessionId of sessionIds) {
+            const session = database
+                .prepare('SELECT 1 AS present FROM session_metadata WHERE session_id = ?')
+                .get(sessionId);
+            if (!session)
+                throw new Error(`Filtered session is missing: ${sessionId}`);
+        }
         database.exec('PRAGMA journal_mode = DELETE');
     }
     catch (error) {
@@ -242,6 +418,67 @@ async function exportFilteredDatabase(stateRoot, destinationPath, sessionId) {
         database.close();
     }
 }
+/**
+ * `core_agent_run_events` types the bundle drops.
+ *
+ * They record how a request was shaped and how a stream behaved -- diagnostics
+ * for the machine that produced them, not the conversation. Any type absent
+ * from this list is carried, including one a later build introduces: an export
+ * moves rows, it does not interpret them.
+ */
+export const SESSION_BUNDLE_OMITTED_EVENT_TYPES = [
+    'provider_request_attempt_recorded',
+    'provider_request_captured',
+    'model_call_attempt_recorded',
+    'model_stream_started',
+    'model_stream_completed',
+    'model_stream_failed',
+    'send_diagnostics_recorded',
+    'plan_context_resolved',
+    'skill_catalog_built',
+    'skill_searched',
+    'skill_loaded',
+    'skill_load_failed',
+    'tool_searched',
+    'request_composition_resolved',
+    'trace_write_failed',
+];
+/**
+ * Ownership, which is not the same thing as naming a Session.
+ *
+ * `session_id` says whose row this is. Everything else in this list is a
+ * Session column only on tables that have no `session_id` -- link tables, whose
+ * whole content is the pair they join, and which are meaningless when one end
+ * is outside the bundle.
+ *
+ * Keeping the two apart matters. `session_metadata.parent_session_id` is a
+ * lineage POINTER, not ownership: treating it as ownership deleted the very
+ * Session being exported whenever its branch source lay outside the subtree.
+ * And a link table whose columns are spelled `parent_session_id` /
+ * `child_session_id` -- `subagent_spawns`, the record of which tool call
+ * spawned each child -- looked Session-less and was emptied wholesale.
+ *
+ * Nullable columns count only when set, so a row that names no counterpart is
+ * not deleted for failing to name one.
+ */
+const SESSION_ROW_OWNER_COLUMN = 'session_id';
+const SESSION_LINK_COLUMNS = [
+    'source_session_id',
+    'target_session_id',
+    'parent_session_id',
+    'child_session_id',
+    'root_session_id',
+];
+/**
+ * Tables the target writes for itself.
+ *
+ * `session_metadata` carries triggers that maintain the catalog projection, so
+ * inserting the bundle's copy of it and then the Session row makes the trigger
+ * collide with what was just inserted. The projection is derived; letting the
+ * target derive it is both simpler and the only way it stays correct when the
+ * derivation changes.
+ */
+const TRIGGER_MAINTAINED_TABLES = new Set(['session_catalog_projection']);
 const PORTABLE_GLOBAL_TABLES = new Set([
     'operational_schema_migrations',
     'session_metadata_schema',
@@ -254,6 +491,109 @@ const PORTABLE_DERIVED_TABLES = new Set([
     'runtime_partial_segments',
     'core_interaction_outcomes',
 ]);
+/**
+ * The Session and its subagent descendants, root first, siblings by id.
+ *
+ * `subagent_parent_session_id` is an ordinary column, not a constrained tree:
+ * nothing stops a row naming itself or an ancestor. Membership is tracked
+ * rather than assumed, so a cycle ends the walk instead of hanging it, and a
+ * Session reachable twice is exported once.
+ */
+/**
+ * Refuse a source whose schema this build does not read.
+ *
+ * The filter runs `DELETE` over whatever tables the database happens to have,
+ * so a schema this build cannot read produces a bundle whose shape will not
+ * match what its manifest claims. The operational store is the authority on
+ * what "current" means -- a private list here went stale the moment a scope was
+ * added, and reported versions the source did not have.
+ */
+function assertPortableSourceSchema(database) {
+    // The inspector validates every scope and says whether a migration is owed.
+    // It reports only some of them, so the manifest's numbers come from the
+    // registry the database keeps -- validated by the authority, reported from
+    // the source, and neither of them this build's constants.
+    const inspection = inspectOperationalStateSchema(database);
+    if (inspection.status !== 'current') {
+        throw new SessionBundleExportError('schema_unsupported', 'Session bundle source schema is not current');
+    }
+    const registered = {};
+    for (const row of database
+        .prepare('SELECT scope, version FROM operational_schema_migrations ORDER BY scope')
+        .all()) {
+        if (typeof row.scope === 'string' && typeof row.version === 'number') {
+            registered[row.scope] = row.version;
+        }
+    }
+    return registered;
+}
+/**
+ * Refuse a Session that is mid-turn.
+ *
+ * The writer locks around this export keep other writers out from here on, but
+ * they say nothing about work that was already in flight when it started. A
+ * partial stream snapshot, a tool dispatched without a settled result, or an
+ * invocation that never reached a terminal event each mean the bundle would
+ * carry half of something -- and half a turn is not a Session.
+ */
+function assertSessionQuiescent(database, sessionId) {
+    const partials = database
+        .prepare('SELECT COUNT(*) AS count FROM runtime_partial_snapshots WHERE session_id = ?')
+        .get(sessionId);
+    if (Number(partials.count ?? 0) > 0) {
+        throw new SessionBundleExportError('session_active', `Session has a partial stream snapshot: ${sessionId}`);
+    }
+    // A tool that crossed the dispatch boundary and never settled. Its
+    // invocation can carry a terminal event -- the run failed -- while the
+    // operation itself is still prepared, so an invocation check does not see it.
+    // Same predicate the runtime store uses, so "unsettled" means one thing.
+    const unsettledOperations = database
+        .prepare(`
+      SELECT COUNT(*) AS count FROM tool_operations
+      WHERE current_state = 'prepared'
+        AND result_event_id IS NULL
+        AND dispatch_event_id IS NOT NULL
+        AND call_event_id IN (SELECT event_id FROM runtime_events WHERE session_id = ?)
+    `)
+        .get(sessionId);
+    if (Number(unsettledOperations.count ?? 0) > 0) {
+        throw new SessionBundleExportError('session_active', `Session has an unsettled tool operation: ${sessionId}`);
+    }
+    const openInvocations = database
+        .prepare(`
+      SELECT COUNT(*) AS count FROM (
+        SELECT DISTINCT invocation_id FROM runtime_events AS invocations
+        WHERE session_id = ?
+          AND NOT EXISTS (
+            SELECT 1 FROM runtime_events AS terminal
+            WHERE terminal.invocation_id = invocations.invocation_id
+              AND ${TERMINAL_RUNTIME_EVENT_SQL}
+          )
+      )
+    `)
+        .get(sessionId);
+    if (Number(openInvocations.count ?? 0) > 0) {
+        throw new SessionBundleExportError('session_active', `Session has an invocation with no terminal event: ${sessionId}`);
+    }
+}
+function collectSubagentSessionTree(database, rootSessionId) {
+    const ordered = [];
+    const seen = new Set([rootSessionId]);
+    const queue = [rootSessionId];
+    const children = database.prepare('SELECT session_id FROM session_metadata WHERE subagent_parent_session_id = ? ORDER BY session_id');
+    while (queue.length > 0) {
+        const sessionId = queue.shift();
+        ordered.push(sessionId);
+        for (const row of children.all(sessionId)) {
+            const childId = row.session_id;
+            if (typeof childId !== 'string' || seen.has(childId))
+                continue;
+            seen.add(childId);
+            queue.push(childId);
+        }
+    }
+    return ordered;
+}
 export function isArtifactPathForSession(relativePath, sessionId) {
     const parts = relativePath.split(/[\\/]+/);
     return (parts.length >= 2 &&
@@ -333,3 +673,538 @@ function assertSafeSessionId(sessionId) {
 function quoteIdentifier(value) {
     return `"${value.replaceAll('"', '""')}"`;
 }
+export class SessionBundleImportError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'SessionBundleImportError';
+    }
+}
+/**
+ * Merge a hydrated bundle into a workspace.
+ *
+ * The mirror of the export, and the asymmetry is the whole design: the export
+ * owns a private copy and can DELETE what is not the subtree, while the import
+ * writes into a live workspace holding other people's Sessions and can only
+ * ADD. What keeps that from needing a table list is that the bundle's database
+ * already contains nothing else -- so this copies every table it has, and a
+ * table added to the schema later travels in both directions without anyone
+ * updating a list.
+ *
+ * Write order is the safety argument. Artifact bytes land first and the
+ * database transaction commits last, so a failure between them leaves files
+ * nothing points at -- reclaimable -- rather than rows pointing at files that
+ * are not there.
+ */
+export async function importSessionBundleState(input) {
+    const bundleStateRoot = await canonicalRoot(input.bundleStateRoot, 'bundle state');
+    const bundleDatabasePath = resolveInside(bundleStateRoot, OPERATIONAL_STATE_DATABASE_NAME);
+    await assertRegularFile(bundleDatabasePath, OPERATIONAL_STATE_DATABASE_NAME);
+    // The authority is decided by what is being written, not by what the target
+    // already has. A bundle carrying context needs it even for a fresh workspace
+    // with no context store yet -- which is exactly the case that would otherwise
+    // run unprotected, and the common one.
+    const bundleCarriesContext = await pathExists(resolveInside(bundleStateRoot, CONTEXT_OFFLOAD_DATABASE_NAME));
+    return withOfflineContextSnapshot(input.stateRoot, (contextLocked) => withBundleArtifactWriterLock(input.stateRoot, input.lease, async (stateRoot) => {
+        const sessionIds = readBundleSessionIds(bundleDatabasePath);
+        if (sessionIds.length === 0) {
+            throw new SessionBundleImportError('invalid_root', 'Bundle carries no Session');
+        }
+        // The export refuses to migrate its source because it only reads. An
+        // import is a write the user asked for, and the target is often a
+        // workspace with no database yet -- moving to a new machine is the whole
+        // point -- so this opens the ordinary way and lets it be initialised.
+        let lease;
+        try {
+            lease = acquireOperationalStateDatabase(stateRoot);
+        }
+        catch (error) {
+            // A target this build cannot open is a schema verdict, not an IO one;
+            // everything else the operational store raises is the environment.
+            if (error instanceof OperationalStateMigrationBlockedError) {
+                throw new SessionBundleImportError('schema_unsupported', 'Workspace schema cannot be opened by this build', { cause: error });
+            }
+            throw error;
+        }
+        try {
+            assertBundleSchemaMatches(lease.database, bundleDatabasePath);
+            assertImportableInto(lease.database, sessionIds);
+            // Everything the Session will reference lands first; the Session rows
+            // are the last thing written. A failure before that leaves artifacts
+            // and context nothing points at, which the store reclaims, rather than
+            // a Session already visible whose bytes never arrived -- and which a
+            // retry could not fix, because the ids are now taken.
+            const artifacts = await copyBundleArtifacts(bundleStateRoot, stateRoot);
+            try {
+                const contextRefs = await mergeBundleContext(bundleStateRoot, stateRoot, contextLocked, sessionIds);
+                const inserted = mergeBundleDatabase(lease, bundleDatabasePath);
+                return { sessionIds: inserted, artifactFiles: artifacts.copied, contextRefs };
+            }
+            catch (error) {
+                // Take back only what this attempt created. Anything already there
+                // belongs to someone else, or to an earlier attempt that the next
+                // one will recognise.
+                for (const path of artifacts.created)
+                    await rm(path, { force: true }).catch(() => { });
+                throw error;
+            }
+        }
+        finally {
+            lease.close();
+        }
+    }), {
+        requireAuthority: bundleCarriesContext,
+        ...(input.lease ? { lease: input.lease } : {}),
+    });
+}
+/**
+ * Refuse a bundle written against a different schema.
+ *
+ * The merge copies rows with `INSERT ... SELECT *`, which maps by position. A
+ * bundle whose tables have a different column ORDER but the same count would
+ * be inserted silently transposed -- rows that read as data and are not. The
+ * export only ever writes a bundle at its own current schema, so any mismatch
+ * here means the two builds disagree, and the honest answer is to say so
+ * rather than to guess a mapping.
+ */
+function assertBundleSchemaMatches(target, bundleDatabasePath) {
+    const bundle = new DatabaseSync(bundleDatabasePath, { readOnly: true });
+    try {
+        const bundleVersions = readSchemaRegistry(bundle);
+        const targetVersions = readSchemaRegistry(target);
+        for (const [scope, version] of Object.entries(bundleVersions)) {
+            if (targetVersions[scope] !== version) {
+                throw new SessionBundleImportError('schema_unsupported', `Bundle schema ${scope} is ${version}; this workspace is ${targetVersions[scope] ?? 'absent'}`);
+            }
+        }
+        const bundleUserVersion = readUserVersionPragma(bundle);
+        const targetUserVersion = readUserVersionPragma(target);
+        if (bundleUserVersion !== targetUserVersion) {
+            throw new SessionBundleImportError('schema_unsupported', `Bundle runtime schema is ${bundleUserVersion}; this workspace is ${targetUserVersion}`);
+        }
+    }
+    finally {
+        bundle.close();
+    }
+}
+function readSchemaRegistry(database) {
+    const versions = {};
+    for (const row of database
+        .prepare('SELECT scope, version FROM operational_schema_migrations')
+        .all()) {
+        if (typeof row.scope === 'string' && typeof row.version === 'number') {
+            versions[row.scope] = row.version;
+        }
+    }
+    return versions;
+}
+function readUserVersionPragma(database) {
+    const row = (database.prepare('PRAGMA user_version').get() ?? {});
+    return Number(Object.values(row)[0] ?? -1);
+}
+/** The same question the export asks before deleting a table wholesale. */
+function describesASession(target, table) {
+    if (PORTABLE_DERIVED_TABLES.has(table))
+        return true;
+    const columns = new Set(target.prepare(`PRAGMA bundle.table_info(${quoteIdentifier(table)})`).all()
+        .map((column) => column.name)
+        .filter((name) => typeof name === 'string'));
+    if (columns.has(SESSION_ROW_OWNER_COLUMN))
+        return true;
+    return SESSION_LINK_COLUMNS.some((column) => columns.has(column));
+}
+function readBundleSessionIds(bundleDatabasePath) {
+    const database = new DatabaseSync(bundleDatabasePath, { readOnly: true });
+    try {
+        return database
+            .prepare('SELECT session_id FROM session_metadata ORDER BY session_id')
+            .all().map((row) => String(row.session_id));
+    }
+    finally {
+        database.close();
+    }
+}
+/**
+ * Refuse before writing anything.
+ *
+ * Session ids are generated, not chosen, so one already present means this
+ * Session is already here -- not that two of them collided. Importing over it
+ * would merge two histories that share ids and agree about nothing else.
+ */
+function assertImportableInto(target, sessionIds) {
+    const existing = target.prepare('SELECT 1 FROM session_metadata WHERE session_id = ?');
+    const present = sessionIds.filter((sessionId) => existing.get(sessionId) !== undefined);
+    if (present.length > 0) {
+        throw new SessionBundleImportError('session_exists', `Session already present in this workspace: ${present.join(', ')}`);
+    }
+}
+/**
+ * Stage the bundle's artifact bytes, and be able to take them back.
+ *
+ * Publishing the Session last stops a broken Session from becoming visible, but
+ * it does not by itself make the import retryable: bytes written before a later
+ * failure stay behind, and a second attempt then trips over its own leftovers.
+ *
+ * Two rules make a retry work without overwriting anything. A destination that
+ * is byte-identical to what the bundle carries is this import's own leftover,
+ * or the same content by another route, and is accepted. A destination holding
+ * something else is a real conflict. Files this attempt actually created are
+ * remembered, so a failure can remove exactly those and nothing else.
+ */
+async function copyBundleArtifacts(bundleStateRoot, stateRoot) {
+    const source = resolveInside(bundleStateRoot, 'artifacts');
+    const created = [];
+    if (!(await pathExists(source)))
+        return { copied: 0, created };
+    let copied = 0;
+    const walk = async (relative) => {
+        const absolute = relative ? resolveInside(source, relative) : source;
+        for (const entry of await readdir(absolute, { withFileTypes: true })) {
+            const next = relative ? `${relative}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await walk(next);
+                continue;
+            }
+            if (!entry.isFile()) {
+                throw new SessionBundleImportError('io_failed', `Bundle artifact is not a regular file: ${next}`);
+            }
+            const from = resolveInside(source, next);
+            const destination = resolveInside(resolveInside(stateRoot, 'artifacts'), next);
+            await mkdir(dirname(destination), { recursive: true });
+            try {
+                await copyFile(from, destination, constants.COPYFILE_EXCL);
+                created.push(destination);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                if (!(await sameFileContent(from, destination))) {
+                    throw new SessionBundleImportError('conflict', `Artifact already present: ${next}`);
+                }
+            }
+            copied += 1;
+        }
+    };
+    await walk('');
+    return { copied, created };
+}
+async function sameFileContent(left, right) {
+    const [a, b] = await Promise.all([readFile(left), readFile(right)]);
+    return a.equals(b);
+}
+/**
+ * Copy every table the bundle has, in one transaction.
+ *
+ * No allow-list: the bundle's database was already filtered down to its own
+ * Sessions, so "everything it has" is exactly what belongs. Only the tables
+ * describing the WORKSPACE rather than a Session are skipped -- the target has
+ * its own, and they are not the bundle's to bring.
+ */
+function mergeBundleDatabase(lease, bundleDatabasePath) {
+    const target = lease.database;
+    // Read-only, so a bundle is never written by the act of reading it -- and so
+    // a hydrated staging tree cannot pick up a journal beside it.
+    const uri = `file:${encodeURI(bundleDatabasePath)}?mode=ro`;
+    target.exec(`ATTACH DATABASE '${uri.replaceAll("'", "''")}' AS bundle`);
+    try {
+        // The lease owns a shared, reference-counted connection with its own
+        // transaction depth. Driving BEGIN/COMMIT directly would step around that,
+        // and the foreign-key pragma it needs must be put back: leaving it off
+        // would silently disarm constraint checking for every later user of this
+        // connection.
+        const restoreForeignKeys = Number(Object.values((target.prepare('PRAGMA foreign_keys').get() ?? {}))[0] ?? 0) === 1;
+        target.exec('PRAGMA foreign_keys = OFF');
+        try {
+            return lease.transaction('write', () => mergeAttachedBundle(target));
+        }
+        finally {
+            if (restoreForeignKeys)
+                target.exec('PRAGMA foreign_keys = ON');
+        }
+    }
+    finally {
+        target.exec('DETACH DATABASE bundle');
+    }
+}
+function mergeAttachedBundle(target) {
+    {
+        {
+            const tables = target
+                .prepare("SELECT name FROM bundle.sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name")
+                .all();
+            for (const row of tables) {
+                const name = row.name;
+                if (typeof name !== 'string' ||
+                    PORTABLE_GLOBAL_TABLES.has(name) ||
+                    TRIGGER_MAINTAINED_TABLES.has(name)) {
+                    continue;
+                }
+                // Mirror the export's own classification instead of trusting that it
+                // ran: a table with no Session column and no referential rule describes
+                // the WORKSPACE, and the target has its own. The export empties those,
+                // so in practice this inserts nothing -- but an import that depends on
+                // the other side having tidied up is one bundle away from writing a
+                // workspace singleton into somebody else's workspace.
+                if (!describesASession(target, name))
+                    continue;
+                const quoted = quoteIdentifier(name);
+                target.exec(`INSERT INTO main.${quoted} SELECT * FROM bundle.${quoted}`);
+            }
+            const violation = target.prepare('PRAGMA foreign_key_check').get();
+            if (violation) {
+                throw new SessionBundleImportError('conflict', 'Imported Sessions would leave dangling references');
+            }
+            return target
+                .prepare('SELECT session_id FROM bundle.session_metadata ORDER BY session_id')
+                .all().map((entry) => String(entry.session_id));
+        }
+    }
+}
+async function pathExists(path) {
+    return lstat(path)
+        .then(() => true)
+        .catch(() => false);
+}
+/**
+ * Merge the bundle's offloaded context into the workspace.
+ *
+ * Without this an imported Session arrives with its read-image references
+ * intact and none of the bytes behind them, which is the same hole the export
+ * had before it learned to carry the closure.
+ *
+ * Blobs are content-addressed, so an id already present is the same bytes and
+ * the insert is skipped rather than treated as a conflict.
+ */
+async function mergeBundleContext(bundleStateRoot, stateRoot, contextLocked, sessionIds) {
+    const bundleContext = resolveInside(bundleStateRoot, CONTEXT_OFFLOAD_DATABASE_NAME);
+    if (!(await pathExists(bundleContext)))
+        return 0;
+    if (!contextLocked) {
+        throw new SessionBundleImportError('io_failed', 'Context import requires an offline Storage Root; stop the Runtime Host first');
+    }
+    // An archive digest authenticates the archive, not the state inside it: it
+    // says the bytes arrived as sent, and nothing about whether a row claiming a
+    // hash names a file that actually hashes to it. Validated here, against the
+    // hydrated copy, before anything is written to the target -- a payload that
+    // fails is a bundle nobody can use, and importing it publishes a reference to
+    // content that cannot be read back.
+    await validateContextSnapshot(bundleStateRoot);
+    // Everything below is one turn in the Storage Root's context mutation queue,
+    // shared with the Context Store's own publication and collection. Those
+    // operations read database state, await, and only then act on files --
+    // collection decides a payload is unreferenced, awaits, unlinks it -- so an
+    // import that commits a reference inside that await leaves the reference
+    // pointing at a file that is about to disappear. The re-check collection does
+    // cannot see it, because the check and the unlink straddle the await.
+    return runWithContextValueMutation(stateRoot, async () => {
+        // Managed payloads live at `sha256/<prefix>/<hash>`, so a copy that visited
+        // only immediate children saw one directory, skipped it, and reported a
+        // successful import whose referenced bytes were all absent.
+        const destination = resolveInside(stateRoot, CONTEXT_OFFLOAD_VALUES_DIRECTORY_NAME);
+        await mkdir(destination, { recursive: true, mode: 0o700 });
+        await copyContextValueTree(resolveInside(bundleStateRoot, CONTEXT_OFFLOAD_VALUES_DIRECTORY_NAME), destination, stateRoot);
+        return mergeBundleContextDatabase(bundleContext, stateRoot, sessionIds);
+    });
+}
+async function mergeBundleContextDatabase(bundleContext, stateRoot, sessionIds) {
+    const targetContext = resolveInside(stateRoot, CONTEXT_OFFLOAD_DATABASE_NAME);
+    if (!(await pathExists(targetContext))) {
+        await copyFile(bundleContext, targetContext);
+        return countContextRefs(targetContext, sessionIds);
+    }
+    const database = new DatabaseSync(targetContext);
+    try {
+        database.exec(`ATTACH DATABASE '${bundleContext.replaceAll("'", "''")}' AS bundle`);
+        try {
+            database.exec('BEGIN IMMEDIATE');
+            try {
+                database.exec('INSERT OR IGNORE INTO main.context_blobs SELECT * FROM bundle.context_blobs');
+                // A retry re-inserts the same rows. Skipping an identical one is what
+                // makes the second attempt work; skipping a DIFFERENT row that happens
+                // to share an id would hide a real collision, so the two are separated.
+                const colliding = database
+                    .prepare(`
+            SELECT b.ref_id FROM bundle.context_refs b
+            JOIN main.context_refs m USING(ref_id)
+            WHERE m.session_id <> b.session_id OR m.blob_id <> b.blob_id
+          `)
+                    .all();
+                if (colliding.length > 0) {
+                    throw new SessionBundleImportError('conflict', `Context reference already names different content: ${String(colliding[0]?.ref_id)}`);
+                }
+                database.exec('INSERT OR IGNORE INTO main.context_refs SELECT * FROM bundle.context_refs');
+                // A blob the target already held may have been queued for collection
+                // while nothing referenced it. It is referenced again now, and leaving
+                // the candidate behind makes the next collection fail outright --
+                // `Context garbage candidate is still referenced or missing` -- and
+                // keep failing. Ordinary insertion in the Store clears it the same way.
+                database.exec(`
+          DELETE FROM main.context_gc_candidates
+          WHERE blob_id IN (SELECT blob_id FROM main.context_refs)
+        `);
+                // The context store maintains its usage tables explicitly -- no trigger
+                // does it. Inserting blobs and refs without them leaves quotas and the
+                // cleanup consistency checks reading numbers that describe a store that
+                // no longer exists. Recomputed from what is actually there, which is
+                // the same thing the export does when it filters.
+                database.exec(`
+          DELETE FROM context_session_usage;
+          INSERT INTO context_session_usage
+            SELECT r.session_id, count(*), sum(b.size_bytes)
+            FROM context_refs r JOIN context_blobs b USING(blob_id) GROUP BY r.session_id;
+          UPDATE context_store_usage SET
+            blob_count = (SELECT count(*) FROM context_blobs),
+            -- Bytes queued for deletion are still on disk and still charged:
+            -- the store drops a blob row before draining its file and subtracts
+            -- them when the drain completes. Recomputing from live blobs alone
+            -- makes that later subtraction underflow. The export can use the
+            -- simpler sum because it empties the queue on its private copy;
+            -- a live target keeps it.
+            physical_bytes =
+              (SELECT coalesce(sum(size_bytes), 0) FROM context_blobs) +
+              (SELECT coalesce(sum(size_bytes), 0) FROM context_file_deletions)
+          WHERE singleton = 1;
+        `);
+                database.exec('COMMIT');
+            }
+            catch (error) {
+                try {
+                    database.exec('ROLLBACK');
+                }
+                catch { }
+                throw error;
+            }
+        }
+        finally {
+            database.exec('DETACH DATABASE bundle');
+        }
+    }
+    finally {
+        database.close();
+    }
+    return countContextRefs(targetContext, sessionIds);
+}
+/**
+ * Copy a managed-payload tree, structure and all.
+ *
+ * Content-addressed names mean an existing file is the same file, so an
+ * already-present payload is left alone rather than treated as a conflict.
+ */
+async function copyContextValueTree(source, destination, stateRoot) {
+    if (!(await pathExists(source)))
+        return;
+    await assertManagedDestinationDirectory(destination, stateRoot);
+    for (const entry of await readdir(source, { withFileTypes: true })) {
+        const from = resolveInside(source, entry.name);
+        const to = resolveInside(destination, entry.name);
+        if (entry.isDirectory()) {
+            await mkdir(to, { recursive: true, mode: 0o700 });
+            await copyContextValueTree(from, to, stateRoot);
+            continue;
+        }
+        if (!entry.isFile()) {
+            throw new SessionBundleImportError('io_failed', `Bundle context payload is not a regular file: ${entry.name}`);
+        }
+        await publishContextValue(from, to, stateRoot);
+    }
+}
+/**
+ * Refuses a destination directory that does not really live inside the Storage
+ * Root.
+ *
+ * `resolveInside` compares strings, which says nothing about what the path
+ * resolves to: a `context-offload-values` replaced by a symlink passes it and
+ * then receives the payloads somewhere else entirely. The Context Store already
+ * holds this invariant over its own managed directories, and a directory it
+ * would refuse to publish into is not one an import may publish into either.
+ */
+async function assertManagedDestinationDirectory(directory, stateRoot) {
+    let entry;
+    let resolved;
+    try {
+        [entry, resolved] = await Promise.all([lstat(directory), realpath(directory)]);
+    }
+    catch (error) {
+        if (error.code === 'ENOTDIR') {
+            throw new SessionBundleImportError('io_failed', `Context payload directory is not a directory: ${directory}`);
+        }
+        throw error;
+    }
+    const fromRoot = relative(stateRoot, resolved);
+    if (!entry.isDirectory() ||
+        entry.isSymbolicLink() ||
+        fromRoot === '..' ||
+        fromRoot.startsWith(`..${sep}`) ||
+        isAbsolute(fromRoot)) {
+        throw new SessionBundleImportError('io_failed', `Context payload directory escapes the Storage Root: ${directory}`);
+    }
+}
+/**
+ * Publishes one payload the way the Context Store publishes its own: the bytes
+ * are assembled under a staging name and become visible at the final path by a
+ * single `link`.
+ *
+ * `copyFile` fills its destination progressively, so the final path is
+ * observable half-written -- measured at 38 distinct intermediate sizes while
+ * copying 64 MiB. Payloads are content-addressed, so a bundle and its target
+ * routinely name the same path, and that path is one another Session may be
+ * reading. It also decides what a retry sees: a copy interrupted midway leaves
+ * a truncated file AT the final path, and the previous `EEXIST`-is-fine rule
+ * accepted it as already present.
+ *
+ * The staging name is the Store's with a different suffix. Two imports cannot
+ * race -- both need the write authority, and it is exclusive -- but an import
+ * and the Store publishing the same blob can, and they must not share a name.
+ */
+async function publishContextValue(from, to, stateRoot) {
+    const staging = join(dirname(to), `.${basename(to)}.import.tmp`);
+    await rm(staging, { force: true });
+    try {
+        await copyFile(from, staging, constants.COPYFILE_EXCL);
+        // 'r+' rather than 'r': Windows flushes through the handle and refuses a
+        // read-only one, so a read handle would make this fail only on Windows.
+        const handle = await open(staging, 'r+');
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        try {
+            await link(staging, to);
+            // The bytes were synced; the directory entry naming them was not. A crash
+            // here otherwise keeps the committed reference and loses the name, which
+            // reads exactly like a payload that never arrived.
+            await syncDirectoryChain(dirname(to), stateRoot);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            // Reaching the final path now means the payload was already there, not
+            // that this import put it there. Content addressing says it should be
+            // byte-identical; if it is not, the store holds something this bundle
+            // cannot explain and overwriting it would destroy the other Session's
+            // payload.
+            if (!(await sameFileContent(from, to))) {
+                throw new SessionBundleImportError('conflict', `Context payload already names different content: ${basename(to)}`);
+            }
+        }
+    }
+    finally {
+        await unlink(staging).catch(() => { });
+    }
+}
+function countContextRefs(databasePath, sessionIds) {
+    const database = new DatabaseSync(databasePath, { readOnly: true });
+    try {
+        const placeholders = sessionIds.map(() => '?').join(', ');
+        const row = database
+            .prepare(`SELECT COUNT(*) AS count FROM context_refs WHERE session_id IN (${placeholders})`)
+            .get(...sessionIds);
+        return Number(row.count ?? 0);
+    }
+    finally {
+        database.close();
+    }
+}