jg-agent-hq 2.0.0 → 3.0.0

package/dist/snapshots/capture.js

@@ -0,0 +1,142 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, open, realpath, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { hashValue } from 'jg-crypto';
+import { hasErrorCode } from 'jg-exception';
+import { writePrivateFile } from 'jg-fs';
+import { withPlanDocumentLocks } from 'jg-plans';
+import { isWithinWorkspace } from '../runtime/state/index.js';
+import { observeSnapshotPlan } from './artifacts.js';
+import { SNAPSHOT_COMPLETE, SNAPSHOT_COMPANIONS, SNAPSHOT_LINE_BYTES, SNAPSHOT_MANIFEST, } from './constants.js';
+import { copySnapshotFile, invalidSnapshot, reserveSnapshotDirectory, syncSnapshotDirectory, } from './files.js';
+import { SnapshotHeaderSchema, SnapshotRecordSchema, } from './types.js';
+/**
+ * Copies one plan under its shared document locks; corrupt or missing source evidence stays explicit.
+ * @returns One fixed-size inventory record, with no repaired or invented authority.
+ * @throws
+ * - JG_PLANS_LOCK_BUSY: The plan document is locked
+ * - JG_PLANS_LOCK_FAILED: The plan document lock operation failed
+ * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
+ * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
+ */
+const capturePlan = async (context, directory, snapshot) => {
+    const record = {
+        kind: 'plan',
+        key: hashValue(directory),
+        sourceDirectory: directory,
+        planId: null,
+        revision: null,
+        plan: null,
+        milestones: null,
+        coordination: null,
+        diagnostics: [],
+    };
+    if (!context.allowedRoots.some((root) => isWithinWorkspace(root, directory))) {
+        record.diagnostics.push('plan-unavailable');
+        return record;
+    }
+    let exists = true;
+    try {
+        if ((await realpath(directory)) !== directory || !(await lstat(directory)).isDirectory())
+            invalidSnapshot();
+    }
+    catch (cause) {
+        if (hasErrorCode(cause, 'ENOENT'))
+            exists = false;
+        else
+            throw cause;
+    }
+    const output = join(snapshot, 'plans', record.key);
+    await mkdir(output, { mode: 0o700 });
+    if (exists)
+        await withPlanDocumentLocks(directory, ['plan', 'milestones'], async () => {
+            for (const [field, filename, maximumBytes] of SNAPSHOT_COMPANIONS)
+                record[field] = await copySnapshotFile(join(directory, filename), join(output, filename), maximumBytes, false, true);
+        });
+    Object.assign(record, await observeSnapshotPlan(output, record));
+    await syncSnapshotDirectory(output);
+    return record;
+};
+/**
+ * Streams the shared format-1 capture and verifies it before transferring destination ownership.
+ * The caller must hold its database/metadata checkpoint; no cache or full inventory is retained.
+ * @returns The fully verified snapshot, retained by the caller after this resolves.
+ * @throws
+ * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
+ * - JG_PLANS_LOCK_BUSY: The plan document is locked
+ * - JG_PLANS_LOCK_FAILED: The plan document lock operation failed
+ * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
+ * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
+ */
+export const captureSnapshot = async (context, destination) => {
+    let owned;
+    try {
+        owned = await reserveSnapshotDirectory(destination);
+        await mkdir(join(owned, 'plans'), { mode: 0o700 });
+        const manifest = await open(join(owned, SNAPSHOT_MANIFEST), 'wx', 0o600);
+        const hash = createHash('sha256');
+        let records = 0;
+        const append = async (record) => {
+            const bytes = Buffer.from(JSON.stringify(SnapshotRecordSchema.parse(record)) + '\n');
+            if (bytes.length > SNAPSHOT_LINE_BYTES)
+                invalidSnapshot();
+            await manifest.writeFile(bytes);
+            hash.update(bytes);
+            records++;
+        };
+        try {
+            await append(SnapshotHeaderSchema.parse({
+                kind: 'header',
+                format: 1,
+                createdAt: new Date().toISOString(),
+                schemaHash: context.schemaHash,
+                sourceStateRoot: context.stateRoot,
+                sourceCoordinationRoot: context.coordinationRoot,
+                sourceAllowedRoots: context.allowedRoots,
+            }));
+            const database = await open(join(owned, 'hq.sqlite'), 'wx', 0o600);
+            await database.close();
+            await context.backupDatabase(join(owned, 'hq.sqlite'));
+            const capturedDatabase = await copySnapshotFile(join(owned, 'hq.sqlite'), null);
+            if (!capturedDatabase)
+                invalidSnapshot();
+            await append({ kind: 'database', file: capturedDatabase });
+            const key = await copySnapshotFile(join(context.stateRoot, 'action.key'), join(owned, 'action.key'), 32);
+            if (key?.bytes !== 32 || key.sha256 !== context.actionKeyHash)
+                invalidSnapshot();
+            await append({ kind: 'action-key', file: key });
+            let after = '';
+            for (;;) {
+                const page = await context.readPlans(after);
+                for (const directory of page) {
+                    await append(await capturePlan(context, directory, owned));
+                    after = directory;
+                }
+                if (page.length < 128)
+                    break;
+            }
+            await manifest.sync();
+            await syncSnapshotDirectory(join(owned, 'plans'));
+            await writePrivateFile(join(owned, SNAPSHOT_COMPLETE), JSON.stringify({ manifestSha256: hash.digest('hex'), records }) + '\n', { rootPath: owned, isExclusive: true });
+            await syncSnapshotDirectory(owned);
+            await syncSnapshotDirectory(dirname(owned));
+        }
+        finally {
+            await manifest.close();
+        }
+        return await context.verify(owned);
+    }
+    catch (cause) {
+        if (owned) {
+            try {
+                await rm(owned, { recursive: true });
+                await syncSnapshotDirectory(dirname(owned));
+            }
+            catch (cleanup) {
+                throw new AggregateError([cause, cleanup], 'Snapshot cleanup failed');
+            }
+        }
+        throw cause;
+    }
+};

package/dist/snapshots/database.d.ts

@@ -4,6 +4,7 @@ import { type IHqSnapshotInspection } from './types.js';
  * Memory stays bounded by one manifest line, one plan page and one report payload.
  * @returns Validated metadata without loading the growing inventory into the caller.
  * @throws
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
  */
 export declare const verifySnapshot: (directory: string) => Promise<IHqSnapshotInspection>;
@@ -12,6 +13,7 @@ export declare const verifySnapshot: (directory: string) => Promise<IHqSnapshotI
  * Only this operation's exclusively created destination is removed on a caught failure.
  * @returns The source inspection; the caller derives the fixed state/plans output paths.
  * @throws
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
  * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
  */

package/dist/snapshots/database.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { lstat, mkdir, readFile, rename, rm } from 'node:fs/promises';
+import { lstat, mkdir, rename, rm } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { hashValue } from 'jg-crypto';
@@ -7,7 +7,8 @@ import { Exception, hasErrorCode, isException, extractMessage } from 'jg-excepti
 import { readPrivateFile, writePrivateFile } from 'jg-fs';
 import { z } from 'zod';
 import { isWithinWorkspace } from '../runtime/state/index.js';
-import { StorageStampSchema } from '../storage/index.js';
+import { readStorageSchema } from '../storage/schema/index.js';
+import { applyRestoreFences, requireRestoreFence } from './fences.js';
 import { observeSnapshotPlan } from './artifacts.js';
 import { SNAPSHOT_COMPLETE, SNAPSHOT_COMPANIONS, SNAPSHOT_MANIFEST } from './constants.js';
 import { copySnapshotFile, invalidSnapshot, readSnapshotRecords, reserveSnapshotDirectory, syncSnapshotDirectory, } from './files.js';
@@ -17,6 +18,7 @@ import { SnapshotCompletionSchema, } from './types.js';
  * Memory stays bounded by one manifest line, one plan page and one report payload.
  * @returns Validated metadata without loading the growing inventory into the caller.
  * @throws
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
  */
 export const verifySnapshot = async (directory) => {
@@ -26,7 +28,6 @@ export const verifySnapshot = async (directory) => {
             maxBytes: 4096,
             rootPath: directory,
         })).toString('utf8')));
-        const schemaHash = hashValue(await readFile(new URL('../store/schema.sql', import.meta.url), 'utf8'));
         const hash = createHash('sha256');
         let records = 0;
         let header;
@@ -45,7 +46,7 @@ export const verifySnapshot = async (directory) => {
             hash.update(bytes);
             records++;
             if (records === 1) {
-                if (record.kind !== 'header' || record.schemaHash !== schemaHash)
+                if (record.kind !== 'header')
                     invalidSnapshot();
                 header = record;
                 continue;
@@ -68,13 +69,10 @@ export const verifySnapshot = async (directory) => {
                     readOnly: true,
                     enableForeignKeyConstraints: true,
                 });
-                const stamps = database
-                    .prepare('SELECT id, schema_hash, action_key_hash FROM hq_schema LIMIT 2')
-                    .all();
-                const stamp = StorageStampSchema.safeParse(stamps.length === 1 ? stamps[0] : null);
-                if (!stamp.success || stamp.data.schema_hash !== schemaHash)
+                const recognized = readStorageSchema(database);
+                if (!recognized || recognized.schema.hash !== header?.schemaHash)
                     invalidSnapshot();
-                actionKeyHash = stamp.data.action_key_hash;
+                actionKeyHash = recognized.actionKeyHash;
                 const integrity = database.prepare('PRAGMA integrity_check').all();
                 if (integrity.length !== 1 ||
                     integrity[0].integrity_check !== 'ok' ||
@@ -167,7 +165,8 @@ export const verifySnapshot = async (directory) => {
         };
     }
     catch (cause) {
-        if (isException(cause) && cause.code === 'JG_AGENT_HQ_SNAPSHOT_INVALID')
+        if (isException(cause) &&
+            ['JG_AGENT_HQ_SNAPSHOT_INVALID', 'JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED'].includes(cause.code))
             throw cause;
         throw new Exception('The HQ snapshot is invalid', {
             code: 'JG_AGENT_HQ_SNAPSHOT_INVALID',
@@ -179,54 +178,18 @@ export const verifySnapshot = async (directory) => {
         database?.close();
     }
 };
-/**
- * Invalidates current execution authority while retaining immutable receipts, IDs and write intents.
- * Source paths remain evidence and require explicit host root selection on startup.
- */
-const pauseRestoredDatabase = (filename) => {
-    const database = new DatabaseSync(filename, { enableForeignKeyConstraints: true });
-    try {
-        database.exec('PRAGMA synchronous = FULL; BEGIN IMMEDIATE');
-        try {
-            const now = Date.now();
-            database
-                .prepare("UPDATE hq_collaboration_task SET state = CASE WHEN state = 'stopped' THEN state ELSE 'paused' END, lifecycle_revision = lifecycle_revision + 1, policy_revision = policy_revision + 1, policy = json_set(policy, '$.automaticDispatch', json('false'))")
-                .run();
-            database
-                .prepare("UPDATE hq_task_agent SET state = CASE WHEN state = 'stopped' THEN state ELSE 'paused' END, revision = revision + 1")
-                .run();
-            database.prepare('UPDATE hq_skill_grant SET revoked_at = COALESCE(revoked_at, ?)').run(now);
-            database
-                .prepare("UPDATE hq_thread SET ownership = 'uncertain', state = 'unknown', updated_at = ?")
-                .run(now);
-            database
-                .prepare("UPDATE hq_action SET delivery = 'uncertain', updated_at = ? WHERE delivery = 'submitted'")
-                .run(now);
-            database.exec('UPDATE hq_action SET queue_ready = 0');
-            database
-                .prepare("UPDATE hq_native_approval SET state = 'expired', updated_at = ? WHERE state = 'pending'")
-                .run(now);
-            database.exec('COMMIT');
-        }
-        catch (cause) {
-            database.exec('ROLLBACK');
-            throw cause;
-        }
-    }
-    finally {
-        database.close();
-    }
-};
 /**
  * Validates before reserving a new recovery workspace, then validates the staged copy again.
  * Only this operation's exclusively created destination is removed on a caught failure.
  * @returns The source inspection; the caller derives the fixed state/plans output paths.
  * @throws
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
  * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
  */
 export const restoreSnapshot = async (directory, destination) => {
     const inspection = await verifySnapshot(directory);
+    requireRestoreFence(inspection.header.schemaHash);
     if (isWithinWorkspace(directory, destination))
         invalidSnapshot();
     let owned;
@@ -259,7 +222,7 @@ export const restoreSnapshot = async (directory, destination) => {
         if (staged.manifestSha256 !== inspection.manifestSha256)
             invalidSnapshot();
         // the copied manifest remains source evidence; the recovered database deliberately has new fences
-        pauseRestoredDatabase(join(staging, 'hq.sqlite'));
+        applyRestoreFences(join(staging, 'hq.sqlite'), staged.header.schemaHash);
         await mkdir(join(owned, 'state'), { mode: 0o700 });
         for (const name of ['hq.sqlite', 'action.key'])
             await rename(join(staging, name), join(owned, 'state', name));
@@ -287,7 +250,8 @@ export const restoreSnapshot = async (directory, destination) => {
             }
         }
         if (hasErrorCode(cause, 'JG_AGENT_HQ_SNAPSHOT_INVALID') ||
-            hasErrorCode(cause, 'JG_AGENT_HQ_SNAPSHOT_FAILED'))
+            hasErrorCode(cause, 'JG_AGENT_HQ_SNAPSHOT_FAILED') ||
+            hasErrorCode(cause, 'JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED'))
             throw cause;
         throw new Exception(`The HQ snapshot operation failed: ${extractMessage(cause)}`, {
             code: 'JG_AGENT_HQ_SNAPSHOT_FAILED',

package/dist/snapshots/fences.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Requires a fence implementation explicitly selected by this exact registered schema.
+ * @throws
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
+ */
+export declare const requireRestoreFence: (schemaHash: string) => void;
+/**
+ * Invalidates current execution authority while retaining immutable receipts, IDs and write intents.
+ * Source paths remain evidence and require explicit host root selection on startup.
+ * @throws
+ * - JG_AGENT_HQ_STORAGE_INVALID: The HQ storage is invalid
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
+ * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
+ */
+export declare const applyRestoreFences: (filename: string, schemaHash: string) => void;

package/dist/snapshots/fences.js

@@ -0,0 +1,64 @@
+import { DatabaseSync } from 'node:sqlite';
+import { Exception } from 'jg-exception';
+import { STORAGE_SCHEMAS, readStorageSchema } from '../storage/schema/index.js';
+import { invalidSnapshot } from './files.js';
+/**
+ * Requires a fence implementation explicitly selected by this exact registered schema.
+ * @throws
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
+ */
+export const requireRestoreFence = (schemaHash) => {
+    const schema = STORAGE_SCHEMAS.find((entry) => entry.hash === schemaHash);
+    if (schema?.restoreFenceVersion !== 1)
+        throw new Exception('The HQ storage version is unsupported', {
+            code: 'JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED',
+            data: { kind: 'state-conflict' },
+        });
+};
+/**
+ * Invalidates current execution authority while retaining immutable receipts, IDs and write intents.
+ * Source paths remain evidence and require explicit host root selection on startup.
+ * @throws
+ * - JG_AGENT_HQ_STORAGE_INVALID: The HQ storage is invalid
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
+ * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
+ */
+export const applyRestoreFences = (filename, schemaHash) => {
+    requireRestoreFence(schemaHash);
+    const database = new DatabaseSync(filename, { enableForeignKeyConstraints: true });
+    try {
+        const observed = readStorageSchema(database);
+        if (!observed || observed.schema.hash !== schemaHash)
+            invalidSnapshot();
+        requireRestoreFence(observed.schema.hash);
+        database.exec('PRAGMA synchronous = FULL; BEGIN IMMEDIATE');
+        try {
+            const now = Date.now();
+            database
+                .prepare("UPDATE hq_collaboration_task SET state = CASE WHEN state = 'stopped' THEN state ELSE 'paused' END, lifecycle_revision = lifecycle_revision + 1, policy_revision = policy_revision + 1, policy = json_set(policy, '$.automaticDispatch', json('false'))")
+                .run();
+            database
+                .prepare("UPDATE hq_task_agent SET state = CASE WHEN state = 'stopped' THEN state ELSE 'paused' END, revision = revision + 1")
+                .run();
+            database.prepare('UPDATE hq_skill_grant SET revoked_at = COALESCE(revoked_at, ?)').run(now);
+            database
+                .prepare("UPDATE hq_thread SET ownership = 'uncertain', state = 'unknown', updated_at = ?")
+                .run(now);
+            database
+                .prepare("UPDATE hq_action SET delivery = 'uncertain', updated_at = ? WHERE delivery = 'submitted'")
+                .run(now);
+            database.exec('UPDATE hq_action SET queue_ready = 0');
+            database
+                .prepare("UPDATE hq_native_approval SET state = 'expired', updated_at = ? WHERE state = 'pending'")
+                .run(now);
+            database.exec('COMMIT');
+        }
+        catch (cause) {
+            database.exec('ROLLBACK');
+            throw cause;
+        }
+    }
+    finally {
+        database.close();
+    }
+};

package/dist/snapshots/index.d.ts

@@ -1,2 +1,4 @@
 export { createHqSnapshot, inspectHqSnapshot, restoreHqSnapshot, registerSnapshotContext, } from './snapshots.js';
 export type { IHqSnapshotInspection, IHqRestoreOptions, IHqRestoreResult, ISnapshotContext, } from './types.js';
+export { captureSnapshot } from './capture.js';
+export { verifySnapshot } from './database.js';

package/dist/snapshots/index.js

@@ -1,2 +1,5 @@
 // trusted Node snapshot operations
 export { createHqSnapshot, inspectHqSnapshot, restoreHqSnapshot, registerSnapshotContext, } from './snapshots.js';
+// shared capture and offline verification
+export { captureSnapshot } from './capture.js';
+export { verifySnapshot } from './database.js';

package/dist/snapshots/snapshots.d.ts

@@ -8,15 +8,17 @@ export declare const registerSnapshotContext: (context: ISnapshotContext) => voi
  * The destination must be absent under an existing canonical parent.
  * @returns A fully verified local snapshot; remote durability remains the host's responsibility.
  * @throws
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
  * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
  * - JG_AGENT_HQ_ACTION_CONFLICT: The HQ action conflicts with its recorded state
  */
 export declare const createHqSnapshot: (runtime: IAgentHq, destination: string) => Promise<IHqSnapshotInspection>;
 /**
- * Validates private files, manifest hashes, current schema, SQLite integrity and exact report payloads.
+ * Validates private files, manifest hashes, supported schema, SQLite integrity and exact report payloads.
  * @returns Bounded metadata; recovery.jsonl retains the streamed plan mapping after restore.
  * @throws
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
  * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
  */
@@ -27,6 +29,7 @@ export declare const inspectHqSnapshot: (directory: string) => Promise<IHqSnapsh
  * createAgentHq requires the host's explicit allowedRoots and a fresh native ownership decision.
  * @returns The new state root and separate plan recovery directory, with source snapshot metadata.
  * @throws
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
  * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
  */

package/dist/snapshots/snapshots.js

@@ -1,17 +1,11 @@
-import { createHash } from 'node:crypto';
-import { lstat, mkdir, open, realpath, rm } from 'node:fs/promises';
+import { rm } from 'node:fs/promises';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { Worker } from 'node:worker_threads';
-import { hashValue } from 'jg-crypto';
 import { Exception, extractMessage, hasErrorCode } from 'jg-exception';
-import { writePrivateFile } from 'jg-fs';
-import { withPlanDocumentLocks } from 'jg-plans';
-import { isWithinWorkspace } from '../runtime/state/index.js';
 import { acquireHqLock } from '../locks/index.js';
-import { observeSnapshotPlan } from './artifacts.js';
-import { SNAPSHOT_COMPLETE, SNAPSHOT_COMPANIONS, SNAPSHOT_LINE_BYTES, SNAPSHOT_MANIFEST, } from './constants.js';
-import { copySnapshotFile, invalidSnapshot, reserveSnapshotDirectory, syncSnapshotDirectory, } from './files.js';
-import { RestoreOptionsSchema, SnapshotHeaderSchema, SnapshotRecordSchema, SnapshotWorkerResponseSchema, } from './types.js';
+import { captureSnapshot } from './capture.js';
+import { invalidSnapshot, syncSnapshotDirectory } from './files.js';
+import { RestoreOptionsSchema, SnapshotWorkerResponseSchema, } from './types.js';
 const contexts = new WeakMap();
 /** Binds trusted Node runtime state without adding worker handles or backup commands to RPC. */
 export const registerSnapshotContext = (context) => {
@@ -21,6 +15,7 @@ export const registerSnapshotContext = (context) => {
  * Runs full SQLite verification/restoration off the caller's event loop and confirms worker exit.
  * @returns The validated snapshot metadata.
  * @throws
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
  * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
  */
@@ -60,7 +55,9 @@ const runSnapshotWorker = async (input) => {
                     data: {
                         kind: response.code === 'JG_AGENT_HQ_SNAPSHOT_INVALID'
                             ? 'invalid-request'
-                            : 'operation-failed',
+                            : response.code === 'JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED'
+                                ? 'state-conflict'
+                                : 'operation-failed',
                     },
                 }));
             else
@@ -68,57 +65,13 @@ const runSnapshotWorker = async (input) => {
         });
     });
 };
-/**
- * Copies one plan under its shared document locks; corrupt or missing source evidence stays explicit.
- * @returns One fixed-size inventory record, with no repaired or invented authority.
- * @throws
- * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
- * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
- */
-const capturePlan = async (context, directory, snapshot) => {
-    const record = {
-        kind: 'plan',
-        key: hashValue(directory),
-        sourceDirectory: directory,
-        planId: null,
-        revision: null,
-        plan: null,
-        milestones: null,
-        coordination: null,
-        diagnostics: [],
-    };
-    if (!context.allowedRoots.some((root) => isWithinWorkspace(root, directory))) {
-        record.diagnostics.push('plan-unavailable');
-        return record;
-    }
-    let exists = true;
-    try {
-        if ((await realpath(directory)) !== directory || !(await lstat(directory)).isDirectory())
-            invalidSnapshot();
-    }
-    catch (cause) {
-        if (hasErrorCode(cause, 'ENOENT'))
-            exists = false;
-        else
-            throw cause;
-    }
-    const output = join(snapshot, 'plans', record.key);
-    await mkdir(output, { mode: 0o700 });
-    if (exists)
-        await withPlanDocumentLocks(directory, ['plan', 'milestones'], async () => {
-            for (const [field, filename, maximumBytes] of SNAPSHOT_COMPANIONS)
-                record[field] = await copySnapshotFile(join(directory, filename), join(output, filename), maximumBytes, false, true);
-        });
-    Object.assign(record, await observeSnapshotPlan(output, record));
-    await syncSnapshotDirectory(output);
-    return record;
-};
 /**
  * Captures a quiescent running HQ, host tables, private key and registered plan companions.
  * The host must pause all of its writers. Busy checkpoints never interrupt native work.
  * The destination must be absent under an existing canonical parent.
  * @returns A fully verified local snapshot; remote durability remains the host's responsibility.
  * @throws
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
  * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
  * - JG_AGENT_HQ_ACTION_CONFLICT: The HQ action conflicts with its recorded state
@@ -133,64 +86,23 @@ export const createHqSnapshot = async (runtime, destination) => {
         invalidSnapshot();
     let owned;
     try {
-        await context.maintenance(async (storage) => {
+        return await context.maintenance(async (storage) => {
             let release;
             let failure;
             try {
                 release = await acquireHqLock(context.coordinationRoot, 'snapshot', { waitTimeoutMs: 0 });
-                owned = await reserveSnapshotDirectory(destination);
-                await mkdir(join(owned, 'plans'), { mode: 0o700 });
-                const manifest = await open(join(owned, SNAPSHOT_MANIFEST), 'wx', 0o600);
-                const hash = createHash('sha256');
-                let records = 0;
-                const append = async (record) => {
-                    const bytes = Buffer.from(JSON.stringify(SnapshotRecordSchema.parse(record)) + '\n');
-                    if (bytes.length > SNAPSHOT_LINE_BYTES)
-                        invalidSnapshot();
-                    await manifest.writeFile(bytes);
-                    hash.update(bytes);
-                    records++;
-                };
-                try {
-                    await append(SnapshotHeaderSchema.parse({
-                        kind: 'header',
-                        format: 1,
-                        createdAt: new Date().toISOString(),
-                        schemaHash: storage.schemaHash,
-                        sourceStateRoot: context.stateRoot,
-                        sourceCoordinationRoot: context.coordinationRoot,
-                        sourceAllowedRoots: context.allowedRoots,
-                    }));
-                    const database = await open(join(owned, 'hq.sqlite'), 'wx', 0o600);
-                    await database.close();
-                    await context.store.snapshotBackup(join(owned, 'hq.sqlite'));
-                    const capturedDatabase = await copySnapshotFile(join(owned, 'hq.sqlite'), null);
-                    if (!capturedDatabase)
-                        invalidSnapshot();
-                    await append({ kind: 'database', file: capturedDatabase });
-                    const key = await copySnapshotFile(join(context.stateRoot, 'action.key'), join(owned, 'action.key'), 32);
-                    if (key?.bytes !== 32 || key.sha256 !== context.actionKeyHash)
-                        invalidSnapshot();
-                    await append({ kind: 'action-key', file: key });
-                    let after = '';
-                    for (;;) {
-                        const page = await context.store.snapshotPlans(after);
-                        for (const directory of page) {
-                            await append(await capturePlan(context, directory, owned));
-                            after = directory;
-                        }
-                        if (page.length < 128)
-                            break;
-                    }
-                    await manifest.sync();
-                    await syncSnapshotDirectory(join(owned, 'plans'));
-                    await writePrivateFile(join(owned, SNAPSHOT_COMPLETE), JSON.stringify({ manifestSha256: hash.digest('hex'), records }) + '\n', { rootPath: owned, isExclusive: true });
-                    await syncSnapshotDirectory(owned);
-                    await syncSnapshotDirectory(dirname(owned));
-                }
-                finally {
-                    await manifest.close();
-                }
+                const result = await captureSnapshot({
+                    stateRoot: context.stateRoot,
+                    coordinationRoot: context.coordinationRoot,
+                    allowedRoots: context.allowedRoots,
+                    actionKeyHash: context.actionKeyHash,
+                    schemaHash: storage.schemaHash,
+                    backupDatabase: (path) => context.store.snapshotBackup(path),
+                    readPlans: (after) => context.store.snapshotPlans(after),
+                    verify: inspectHqSnapshot,
+                }, destination);
+                owned = result.directory;
+                return result;
             }
             catch (cause) {
                 failure = cause;
@@ -207,7 +119,6 @@ export const createHqSnapshot = async (runtime, destination) => {
                 }
             }
         }, true);
-        return await inspectHqSnapshot(owned);
     }
     catch (cause) {
         if (owned) {
@@ -221,7 +132,8 @@ export const createHqSnapshot = async (runtime, destination) => {
         }
         if (hasErrorCode(cause, 'JG_AGENT_HQ_ACTION_CONFLICT') ||
             hasErrorCode(cause, 'JG_AGENT_HQ_SNAPSHOT_INVALID') ||
-            hasErrorCode(cause, 'JG_AGENT_HQ_SNAPSHOT_FAILED'))
+            hasErrorCode(cause, 'JG_AGENT_HQ_SNAPSHOT_FAILED') ||
+            hasErrorCode(cause, 'JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED'))
             throw cause;
         if (hasErrorCode(cause, 'JG_PLANS_LOCK_BUSY') ||
             hasErrorCode(cause, 'JG_AGENT_HQ_LOCK_TIMEOUT'))
@@ -238,9 +150,10 @@ export const createHqSnapshot = async (runtime, destination) => {
     }
 };
 /**
- * Validates private files, manifest hashes, current schema, SQLite integrity and exact report payloads.
+ * Validates private files, manifest hashes, supported schema, SQLite integrity and exact report payloads.
  * @returns Bounded metadata; recovery.jsonl retains the streamed plan mapping after restore.
  * @throws
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
  * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
  */
@@ -255,6 +168,7 @@ export const inspectHqSnapshot = async (directory) => {
  * createAgentHq requires the host's explicit allowedRoots and a fresh native ownership decision.
  * @returns The new state root and separate plan recovery directory, with source snapshot metadata.
  * @throws
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
  * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
  */

package/dist/snapshots/snapshots.worker.js

@@ -14,7 +14,11 @@ try {
 }
 catch (cause) {
     const error = isException(cause) &&
-        ['JG_AGENT_HQ_SNAPSHOT_INVALID', 'JG_AGENT_HQ_SNAPSHOT_FAILED'].includes(cause.code)
+        [
+            'JG_AGENT_HQ_SNAPSHOT_INVALID',
+            'JG_AGENT_HQ_SNAPSHOT_FAILED',
+            'JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED',
+        ].includes(cause.code)
         ? cause
         : new Exception(`The HQ snapshot operation failed: ${extractMessage(cause)}`, {
             code: 'JG_AGENT_HQ_SNAPSHOT_FAILED',