jg-agent-hq 2.0.0 → 3.0.0

package/dist/storage/upgrade/types.js

@@ -0,0 +1,42 @@
+import { isAbsolute, resolve } from 'node:path';
+import { z } from 'zod';
+import { ErrorKindSchema } from '../../contracts/index.js';
+const PathSchema = z
+    .string()
+    .min(1)
+    .max(4096)
+    .refine((path) => isAbsolute(path) && resolve(path) === path);
+const HashSchema = z.string().regex(/^[a-f0-9]{64}$/);
+// explicit offline operator inputs; stored workspace roots never grant authority
+export const UpgradeOptionsSchema = z.strictObject({
+    stateRoot: PathSchema,
+    backupDirectory: PathSchema,
+    allowedRoots: z.array(PathSchema).min(1).max(128),
+    coordinationRoot: PathSchema.optional(),
+});
+// current is an idempotent observation, with no new backup or reconciliation
+export const UpgradeResultSchema = z.object({
+    stateRoot: PathSchema,
+    state: z.enum(['upgraded', 'current']),
+    fromVersion: z.number().int().positive(),
+    toVersion: z.number().int().positive(),
+    fromSchemaHash: HashSchema,
+    toSchemaHash: HashSchema,
+    backupDirectory: PathSchema.nullable(),
+});
+// the parent pins the key observed before lifetime ownership was acquired
+export const UpgradeWorkerInputSchema = UpgradeOptionsSchema.extend({ actionKeyHash: HashSchema });
+export const UpgradeWorkerResponseSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('result'), result: UpgradeResultSchema }),
+    z.object({
+        kind: z.literal('error'),
+        code: z.string().regex(/^JG_AGENT_HQ_[A-Z_]+$/),
+        message: z.string().max(16384),
+        cause: z.instanceof(Error).optional(),
+        data: z.object({
+            kind: ErrorKindSchema,
+            phase: z.string().max(64),
+            backupDirectory: PathSchema.nullable(),
+        }),
+    }),
+]);

package/dist/storage/upgrade/upgrade.d.ts

@@ -0,0 +1,33 @@
+import { type IHqStorageUpgradeOptions, type IHqStorageUpgradeResult } from './types.js';
+/**
+ * Upgrades existing offline storage only after a fully verified local backup.
+ * Stop HQ/native children and all independent database/plan writers first. No owner is reclaimed.
+ * An uncertain error requires explicit reinspection; this operation never reverses or replays DDL.
+ * @returns The committed upgrade or an untouched current-version observation, after worker exit.
+ * @throws
+ * - JG_AGENT_HQ_REQUEST_INVALID: The HQ request is invalid
+ * - JG_AGENT_HQ_STATE_DIRECTORY_UNSAFE: The HQ state directory is unsafe
+ * - JG_AGENT_HQ_STATE_FILE_UNSAFE: The HQ state file is unsafe
+ * - JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE: The HQ action key is unavailable
+ * - JG_AGENT_HQ_RUNTIME_ALREADY_OWNED: The HQ runtime is already owned
+ * - JG_AGENT_HQ_RUNTIME_OWNER_UNVERIFIABLE: The HQ runtime owner is unverifiable
+ * - JG_AGENT_HQ_RUNTIME_NOT_RUNNING: The HQ runtime is not running
+ * - JG_AGENT_HQ_LOCK_UNSUPPORTED_PLATFORM: The HQ lock requires Linux or macOS
+ * - JG_AGENT_HQ_RUNTIME_DIRECTORY_INVALID: The HQ runtime directory must be a real directory
+ * - JG_AGENT_HQ_RUNTIME_DIRECTORY_PERMISSIONS: The HQ runtime directory must be private and owned by the current user
+ * - JG_AGENT_HQ_LOCK_FILE_INVALID: The HQ lock must be a regular file
+ * - JG_AGENT_HQ_LOCK_FILE_PERMISSIONS: The HQ lock must be private and owned by the current user
+ * - JG_AGENT_HQ_LOCK_OWNER_OVERSIZED: The HQ lock owner exceeds the supported size
+ * - JG_AGENT_HQ_LOCK_OWNER_UNREADABLE: The HQ lock owner could not be read. Inspect .runtime/hq.lock
+ * - JG_AGENT_HQ_LOCK_OWNER_INCOMPLETE: The HQ lock owner is incomplete. Inspect .runtime/hq.lock and remove it only after its owner stopped
+ * - JG_AGENT_HQ_LOCK_OWNER_INACTIVE: The HQ lock has an inactive owner
+ * - JG_AGENT_HQ_LOCK_OWNER_UNVERIFIABLE: The HQ lock owner could not be verified
+ * - JG_AGENT_HQ_LOCK_TIMEOUT: Timed out waiting for the HQ lock
+ * - 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_STORAGE_UPGRADE_FAILED: The HQ storage upgrade failed
+ * - JG_AGENT_HQ_STORAGE_UPGRADE_UNCERTAIN: The HQ storage upgrade requires reconciliation
+ * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
+ * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
+ */
+export declare const upgradeHqStorage: (options: IHqStorageUpgradeOptions) => Promise<IHqStorageUpgradeResult>;

package/dist/storage/upgrade/upgrade.js

@@ -0,0 +1,196 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { Worker } from 'node:worker_threads';
+import { hashValue } from 'jg-crypto';
+import { Exception, extractMessage, hasErrorCode } from 'jg-exception';
+import { assertPrivateDirectory } from 'jg-fs';
+import { isPrivateOwner } from '../../locks/index.js';
+import { claimRuntimeOwner, isWithinWorkspace, readExistingState, resolveAllowedRoots, } from '../../runtime/state/index.js';
+import { UpgradeOptionsSchema, UpgradeWorkerResponseSchema, } from './types.js';
+/**
+ * Waits for actual exit, including when a worker reports an error. There is no size-based deadline.
+ * @returns The validated result after confirmed worker shutdown.
+ * @throws
+ * - JG_AGENT_HQ_REQUEST_INVALID: The HQ request is invalid
+ * - JG_AGENT_HQ_STATE_DIRECTORY_UNSAFE: The HQ state directory is unsafe
+ * - JG_AGENT_HQ_STATE_FILE_UNSAFE: The HQ state file is unsafe
+ * - JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE: The HQ action key is unavailable
+ * - JG_AGENT_HQ_LOCK_UNSUPPORTED_PLATFORM: The HQ lock requires Linux or macOS
+ * - JG_AGENT_HQ_RUNTIME_DIRECTORY_INVALID: The HQ runtime directory must be a real directory
+ * - JG_AGENT_HQ_RUNTIME_DIRECTORY_PERMISSIONS: The HQ runtime directory must be private and owned by the current user
+ * - JG_AGENT_HQ_LOCK_FILE_INVALID: The HQ lock must be a regular file
+ * - JG_AGENT_HQ_LOCK_FILE_PERMISSIONS: The HQ lock must be private and owned by the current user
+ * - JG_AGENT_HQ_LOCK_OWNER_OVERSIZED: The HQ lock owner exceeds the supported size
+ * - JG_AGENT_HQ_LOCK_OWNER_UNREADABLE: The HQ lock owner could not be read. Inspect .runtime/hq.lock
+ * - JG_AGENT_HQ_LOCK_OWNER_INCOMPLETE: The HQ lock owner is incomplete. Inspect .runtime/hq.lock and remove it only after its owner stopped
+ * - JG_AGENT_HQ_LOCK_OWNER_INACTIVE: The HQ lock has an inactive owner
+ * - JG_AGENT_HQ_LOCK_OWNER_UNVERIFIABLE: The HQ lock owner could not be verified
+ * - JG_AGENT_HQ_LOCK_TIMEOUT: Timed out waiting for the HQ lock
+ * - 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_STORAGE_UPGRADE_FAILED: The HQ storage upgrade failed
+ * - JG_AGENT_HQ_STORAGE_UPGRADE_UNCERTAIN: The HQ storage upgrade requires reconciliation
+ * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
+ * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
+ */
+const runUpgradeWorker = async (input) => {
+    let worker;
+    try {
+        worker = new Worker(new URL('./upgrade.worker.js', import.meta.url), {
+            execArgv: process.execArgv.filter((argument, index, args) => argument !== '--input-type' &&
+                !argument.startsWith('--input-type=') &&
+                args[index - 1] !== '--input-type'),
+            workerData: input,
+        });
+    }
+    catch (cause) {
+        throw new Exception(`The HQ storage upgrade failed: ${extractMessage(cause)}`, {
+            code: 'JG_AGENT_HQ_STORAGE_UPGRADE_FAILED',
+            data: { kind: 'operation-failed', phase: 'worker-start', backupDirectory: null },
+            cause,
+        });
+    }
+    return new Promise((resolveResult, rejectResult) => {
+        let response;
+        let failure;
+        let hasDuplicateResponse = false;
+        worker.on('message', (message) => {
+            const parsed = UpgradeWorkerResponseSchema.safeParse(message);
+            if (response)
+                hasDuplicateResponse = true;
+            else if (!parsed.success)
+                failure = parsed.error;
+            else
+                response = parsed.data;
+        });
+        worker.once('error', (cause) => {
+            failure = cause;
+        });
+        worker.once('exit', (code) => {
+            if (failure || hasDuplicateResponse || code !== 0 || !response)
+                rejectResult(new Exception(`The HQ storage upgrade requires reconciliation: ${failure ? extractMessage(failure) : hasDuplicateResponse ? 'Duplicate upgrade worker result' : `Worker exited (${code})`}`, {
+                    code: 'JG_AGENT_HQ_STORAGE_UPGRADE_UNCERTAIN',
+                    data: {
+                        kind: 'operation-failed',
+                        phase: 'worker-exit',
+                        backupDirectory: input.backupDirectory,
+                    },
+                    cause: failure,
+                }));
+            else if (response.kind === 'error')
+                rejectResult(new Exception(response.message, {
+                    code: response.code,
+                    data: response.data,
+                    cause: response.cause,
+                }));
+            else
+                resolveResult(response.result);
+        });
+    });
+};
+/**
+ * Upgrades existing offline storage only after a fully verified local backup.
+ * Stop HQ/native children and all independent database/plan writers first. No owner is reclaimed.
+ * An uncertain error requires explicit reinspection; this operation never reverses or replays DDL.
+ * @returns The committed upgrade or an untouched current-version observation, after worker exit.
+ * @throws
+ * - JG_AGENT_HQ_REQUEST_INVALID: The HQ request is invalid
+ * - JG_AGENT_HQ_STATE_DIRECTORY_UNSAFE: The HQ state directory is unsafe
+ * - JG_AGENT_HQ_STATE_FILE_UNSAFE: The HQ state file is unsafe
+ * - JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE: The HQ action key is unavailable
+ * - JG_AGENT_HQ_RUNTIME_ALREADY_OWNED: The HQ runtime is already owned
+ * - JG_AGENT_HQ_RUNTIME_OWNER_UNVERIFIABLE: The HQ runtime owner is unverifiable
+ * - JG_AGENT_HQ_RUNTIME_NOT_RUNNING: The HQ runtime is not running
+ * - JG_AGENT_HQ_LOCK_UNSUPPORTED_PLATFORM: The HQ lock requires Linux or macOS
+ * - JG_AGENT_HQ_RUNTIME_DIRECTORY_INVALID: The HQ runtime directory must be a real directory
+ * - JG_AGENT_HQ_RUNTIME_DIRECTORY_PERMISSIONS: The HQ runtime directory must be private and owned by the current user
+ * - JG_AGENT_HQ_LOCK_FILE_INVALID: The HQ lock must be a regular file
+ * - JG_AGENT_HQ_LOCK_FILE_PERMISSIONS: The HQ lock must be private and owned by the current user
+ * - JG_AGENT_HQ_LOCK_OWNER_OVERSIZED: The HQ lock owner exceeds the supported size
+ * - JG_AGENT_HQ_LOCK_OWNER_UNREADABLE: The HQ lock owner could not be read. Inspect .runtime/hq.lock
+ * - JG_AGENT_HQ_LOCK_OWNER_INCOMPLETE: The HQ lock owner is incomplete. Inspect .runtime/hq.lock and remove it only after its owner stopped
+ * - JG_AGENT_HQ_LOCK_OWNER_INACTIVE: The HQ lock has an inactive owner
+ * - JG_AGENT_HQ_LOCK_OWNER_UNVERIFIABLE: The HQ lock owner could not be verified
+ * - JG_AGENT_HQ_LOCK_TIMEOUT: Timed out waiting for the HQ lock
+ * - 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_STORAGE_UPGRADE_FAILED: The HQ storage upgrade failed
+ * - JG_AGENT_HQ_STORAGE_UPGRADE_UNCERTAIN: The HQ storage upgrade requires reconciliation
+ * - JG_AGENT_HQ_SNAPSHOT_INVALID: The HQ snapshot is invalid
+ * - JG_AGENT_HQ_SNAPSHOT_FAILED: The HQ snapshot operation failed
+ */
+export const upgradeHqStorage = async (options) => {
+    const parsed = UpgradeOptionsSchema.safeParse(options);
+    if (!parsed.success)
+        throw new Exception('The HQ request is invalid', {
+            code: 'JG_AGENT_HQ_REQUEST_INVALID',
+            data: { kind: 'invalid-request' },
+            cause: parsed.error,
+        });
+    const selected = parsed.data;
+    const state = await readExistingState(selected.stateRoot);
+    const allowedRoots = await resolveAllowedRoots(selected.allowedRoots);
+    const coordinationRoot = selected.coordinationRoot
+        ? (await resolveAllowedRoots([selected.coordinationRoot]))[0]
+        : state.stateRoot;
+    try {
+        await assertPrivateDirectory(dirname(selected.backupDirectory));
+        if ((await realpath(dirname(selected.backupDirectory))) !== dirname(selected.backupDirectory) ||
+            !isPrivateOwner(await lstat(dirname(selected.backupDirectory))) ||
+            isWithinWorkspace(state.stateRoot, selected.backupDirectory) ||
+            isWithinWorkspace(selected.backupDirectory, state.stateRoot))
+            throw new Exception('The HQ snapshot is invalid', {
+                code: 'JG_AGENT_HQ_SNAPSHOT_INVALID',
+                data: { kind: 'invalid-request' },
+            });
+    }
+    catch (cause) {
+        if (hasErrorCode(cause, 'JG_AGENT_HQ_SNAPSHOT_INVALID'))
+            throw cause;
+        throw new Exception(`The HQ snapshot is invalid: ${extractMessage(cause)}`, {
+            code: 'JG_AGENT_HQ_SNAPSHOT_INVALID',
+            data: { kind: 'invalid-request' },
+            cause,
+        });
+    }
+    const ownership = await claimRuntimeOwner(state.stateRoot, 'upgrade-storage');
+    let result;
+    let failure;
+    try {
+        const current = await readExistingState(state.stateRoot);
+        if (hashValue(current.actionKey) !== hashValue(state.actionKey))
+            throw new Exception('The HQ action key is unavailable', {
+                code: 'JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE',
+                data: { kind: 'state-conflict' },
+            });
+        result = await runUpgradeWorker({
+            ...selected,
+            allowedRoots,
+            coordinationRoot,
+            actionKeyHash: hashValue(current.actionKey),
+        });
+    }
+    catch (cause) {
+        failure = cause;
+    }
+    try {
+        // runUpgradeWorker settles only after exit; a worker that has not exited keeps this owner
+        await ownership.release();
+    }
+    catch (cause) {
+        throw new Exception(`The HQ storage upgrade requires reconciliation: ${extractMessage(cause)}`, {
+            code: 'JG_AGENT_HQ_STORAGE_UPGRADE_UNCERTAIN',
+            data: {
+                kind: 'operation-failed',
+                phase: 'owner-release',
+                backupDirectory: result?.backupDirectory ?? selected.backupDirectory,
+            },
+            cause: failure
+                ? new AggregateError([failure, cause], 'Upgrade owner release failed')
+                : cause,
+        });
+    }
+    if (failure)
+        throw failure;
+    return result;
+};

package/dist/storage/upgrade/upgrade.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/storage/upgrade/upgrade.worker.js

@@ -0,0 +1,220 @@
+import { readFile } from 'node:fs/promises';
+import { DatabaseSync, backup } from 'node:sqlite';
+import { parentPort, workerData } from 'node:worker_threads';
+import { hashValue } from 'jg-crypto';
+import { Exception, extractMessage, isException } from 'jg-exception';
+import { z } from 'zod';
+import { getErrorKind } from '../../errors/index.js';
+import { acquireHqLock } from '../../locks/index.js';
+import { isWithinWorkspace, readExistingState } from '../../runtime/state/index.js';
+import { captureSnapshot, verifySnapshot } from '../../snapshots/index.js';
+import { CURRENT_SCHEMA_VERSION, STORAGE_MIGRATIONS, STORAGE_SCHEMAS, readStorageSchema, } from '../schema/index.js';
+import { STORAGE_CONNECTION_SETTINGS } from '../constants.js';
+import { UpgradeWorkerInputSchema, UpgradeResultSchema, } from './types.js';
+const port = parentPort;
+if (!port)
+    throw new Exception('The HQ storage upgrade failed', {
+        code: 'JG_AGENT_HQ_STORAGE_UPGRADE_FAILED',
+    });
+let phase = 'preflight';
+let verifiedBackup = null;
+let database;
+let release;
+let hasCommitted = false;
+let result;
+let failure;
+try {
+    const input = UpgradeWorkerInputSchema.parse(workerData);
+    const state = await readExistingState(input.stateRoot);
+    if (hashValue(state.actionKey) !== input.actionKeyHash)
+        throw new Exception('The HQ action key is unavailable', {
+            code: 'JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE',
+            data: { kind: 'state-conflict' },
+        });
+    database = new DatabaseSync(state.databasePath, {
+        readOnly: true,
+        enableForeignKeyConstraints: true,
+        timeout: STORAGE_CONNECTION_SETTINGS.busyTimeoutMs,
+    });
+    const observed = readStorageSchema(database, input.actionKeyHash);
+    if (!observed)
+        throw new Exception('The HQ storage is invalid', {
+            code: 'JG_AGENT_HQ_STORAGE_INVALID',
+            data: { kind: 'state-conflict' },
+        });
+    const target = STORAGE_SCHEMAS.find((entry) => entry.version === CURRENT_SCHEMA_VERSION);
+    const base = {
+        stateRoot: state.stateRoot,
+        fromVersion: observed.schema.version,
+        toVersion: target.version,
+        fromSchemaHash: observed.schema.hash,
+        toSchemaHash: target.hash,
+    };
+    if (observed.schema.version === target.version) {
+        result = { ...base, state: 'current', backupDirectory: null };
+    }
+    else {
+        // validate every selected source before reserving output; pages remain bounded for growing registries
+        let after = '';
+        for (;;) {
+            const page = database
+                .prepare('SELECT directory FROM hq_plan_registration WHERE directory > ? ORDER BY directory LIMIT 128')
+                .all(after);
+            for (const row of page) {
+                const directory = z.string().parse(row.directory);
+                if (isWithinWorkspace(input.backupDirectory, directory) ||
+                    isWithinWorkspace(directory, input.backupDirectory))
+                    throw new Exception('The HQ snapshot is invalid', {
+                        code: 'JG_AGENT_HQ_SNAPSHOT_INVALID',
+                        data: { kind: 'invalid-request' },
+                    });
+                after = directory;
+            }
+            if (page.length < 128)
+                break;
+        }
+        database.close();
+        database = undefined;
+        phase = 'metadata-lock';
+        release = await acquireHqLock(input.coordinationRoot ?? state.stateRoot, 'upgrade-storage', {
+            waitTimeoutMs: 0,
+        });
+        const checkpoint = await readExistingState(state.stateRoot);
+        if (hashValue(checkpoint.actionKey) !== input.actionKeyHash)
+            throw new Exception('The HQ action key is unavailable', {
+                code: 'JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE',
+                data: { kind: 'state-conflict' },
+            });
+        database = new DatabaseSync(state.databasePath, {
+            enableForeignKeyConstraints: true,
+            timeout: STORAGE_CONNECTION_SETTINGS.busyTimeoutMs,
+        });
+        database.exec(`PRAGMA journal_mode = ${STORAGE_CONNECTION_SETTINGS.journalMode}; PRAGMA synchronous = ${STORAGE_CONNECTION_SETTINGS.synchronous}; BEGIN IMMEDIATE`);
+        const locked = readStorageSchema(database, input.actionKeyHash);
+        if (locked?.schema.version !== observed.schema.version ||
+            locked.schema.hash !== observed.schema.hash)
+            throw new Exception('The HQ storage is invalid', {
+                code: 'JG_AGENT_HQ_STORAGE_INVALID',
+                data: { kind: 'state-conflict' },
+            });
+        phase = 'backup';
+        const writer = database;
+        await captureSnapshot({
+            stateRoot: state.stateRoot,
+            coordinationRoot: input.coordinationRoot ?? state.stateRoot,
+            allowedRoots: input.allowedRoots,
+            actionKeyHash: input.actionKeyHash,
+            schemaHash: observed.schema.hash,
+            readPlans: async (cursor) => writer
+                .prepare('SELECT directory FROM hq_plan_registration WHERE directory > ? ORDER BY directory LIMIT 128')
+                .all(cursor)
+                .map((row) => z.string().parse(row.directory)),
+            backupDatabase: async (destination) => {
+                // an active writer cannot be the source of sqlite3_backup; readers see the locked committed state
+                const source = new DatabaseSync(state.databasePath, {
+                    readOnly: true,
+                    enableForeignKeyConstraints: true,
+                });
+                try {
+                    await backup(source, destination);
+                }
+                finally {
+                    source.close();
+                }
+                const copy = new DatabaseSync(destination);
+                try {
+                    copy.exec('PRAGMA journal_mode = DELETE');
+                }
+                finally {
+                    copy.close();
+                }
+            },
+            verify: verifySnapshot,
+        }, input.backupDirectory);
+        verifiedBackup = input.backupDirectory;
+        phase = 'migration';
+        const edge = STORAGE_MIGRATIONS.find((entry) => entry.fromVersion === observed.schema.version && entry.toVersion === target.version);
+        if (!edge)
+            throw new Exception('The HQ storage version is unsupported', {
+                code: 'JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED',
+                data: { kind: 'state-conflict' },
+            });
+        database.exec(await readFile(edge.source, 'utf8'));
+        database
+            .prepare('UPDATE hq_schema SET schema_version = ?, schema_hash = ? WHERE id = 1')
+            .run(target.version, target.hash);
+        const migrated = readStorageSchema(database, input.actionKeyHash);
+        if (migrated?.schema.version !== target.version || migrated.schema.hash !== target.hash)
+            throw new Exception('The HQ storage is invalid', {
+                code: 'JG_AGENT_HQ_STORAGE_INVALID',
+                data: { kind: 'state-conflict' },
+            });
+        const integrity = database.prepare('PRAGMA integrity_check').all();
+        if (integrity.length !== 1 ||
+            integrity[0]?.integrity_check !== 'ok' ||
+            database.prepare('PRAGMA foreign_key_check').get())
+            throw new Exception('The HQ storage is invalid', {
+                code: 'JG_AGENT_HQ_STORAGE_INVALID',
+                data: { kind: 'state-conflict' },
+            });
+        phase = 'commit';
+        database.exec('COMMIT');
+        hasCommitted = true;
+        result = { ...base, state: 'upgraded', backupDirectory: verifiedBackup };
+    }
+}
+catch (cause) {
+    failure = cause;
+    // a post-COMMIT exception can precede the assignment above; autocommit distinguishes that uncertainty
+    if (phase === 'commit' && database && !database.isTransaction)
+        hasCommitted = true;
+    if (database?.isTransaction) {
+        try {
+            database.exec('ROLLBACK');
+        }
+        catch (cleanup) {
+            hasCommitted = true;
+            failure = new AggregateError([cause, cleanup], 'Upgrade rollback could not be confirmed');
+        }
+    }
+}
+finally {
+    try {
+        database?.close();
+        await release?.();
+    }
+    catch (cause) {
+        hasCommitted = true;
+        failure = failure ? new AggregateError([failure, cause], 'Upgrade cleanup failed') : cause;
+        phase = 'cleanup';
+    }
+}
+try {
+    if (failure) {
+        const error = hasCommitted
+            ? new Exception(`The HQ storage upgrade requires reconciliation: ${extractMessage(failure)}`, {
+                code: 'JG_AGENT_HQ_STORAGE_UPGRADE_UNCERTAIN',
+                data: { kind: 'operation-failed' },
+                cause: failure,
+            })
+            : isException(failure) && failure.code.startsWith('JG_AGENT_HQ_')
+                ? failure
+                : new Exception(`The HQ storage upgrade failed: ${extractMessage(failure)}`, {
+                    code: 'JG_AGENT_HQ_STORAGE_UPGRADE_FAILED',
+                    data: { kind: 'operation-failed' },
+                    cause: failure,
+                });
+        port.postMessage({
+            kind: 'error',
+            code: error.code,
+            message: extractMessage(error),
+            cause: failure instanceof Error ? failure : undefined,
+            data: { kind: getErrorKind(error), phase, backupDirectory: verifiedBackup },
+        });
+    }
+    else
+        port.postMessage({ kind: 'result', result: UpgradeResultSchema.parse(result) });
+}
+finally {
+    port.close();
+}

package/dist/store/schema.d.ts

@@ -4,6 +4,8 @@ import { DatabaseSync } from 'node:sqlite';
  * Fresh schema and stamp creation share one transaction; application objects are not converted.
  * @returns The worker-owned connection and complete HQ schema hash.
  * @throws
+ * - JG_AGENT_HQ_STORAGE_UPGRADE_REQUIRED: The HQ storage requires an explicit upgrade
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_STORAGE_INVALID: The HQ storage is invalid
  * - JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE: The HQ action key is unavailable
  */

package/dist/store/schema.js

@@ -1,49 +1,40 @@
 import { DatabaseSync } from 'node:sqlite';
 import { hashValue } from 'jg-crypto';
 import { Exception, isException } from 'jg-exception';
-import { STORAGE_CONNECTION_SETTINGS, StorageStampSchema } from '../storage/index.js';
+import { STORAGE_CONNECTION_SETTINGS } from '../storage/index.js';
+import { CURRENT_SCHEMA_VERSION, readStorageSchema } from '../storage/schema/index.js';
 /**
  * Recognizes an empty schema or validates its singleton stamp without issuing writes.
  * @returns Whether initialization is required.
  * @throws
+ * - JG_AGENT_HQ_STORAGE_UPGRADE_REQUIRED: The HQ storage requires an explicit upgrade
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_STORAGE_INVALID: The HQ storage is invalid
  * - JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE: The HQ action key is unavailable
  */
 const validateSchemaStamp = (database, schemaHash, actionKeyHash) => {
-    try {
-        if (!database.prepare('SELECT 1 FROM sqlite_schema LIMIT 1').get())
-            return true;
-        const rows = database
-            .prepare('SELECT id, schema_hash, action_key_hash FROM hq_schema LIMIT 2')
-            .all();
-        const stamp = StorageStampSchema.safeParse(rows.length === 1 ? rows[0] : null);
-        if (!stamp.success || stamp.data.schema_hash !== schemaHash)
-            throw new Exception('The HQ storage is invalid', {
-                code: 'JG_AGENT_HQ_STORAGE_INVALID',
-                data: { kind: 'state-conflict' },
-            });
-        if (stamp.data.action_key_hash !== actionKeyHash)
-            throw new Exception('The HQ action key is unavailable', {
-                code: 'JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE',
-                data: { kind: 'state-conflict' },
-            });
-        return false;
-    }
-    catch (cause) {
-        if (isException(cause))
-            throw cause;
+    const observed = readStorageSchema(database, actionKeyHash);
+    if (!observed)
+        return true;
+    if (observed.schema.version !== CURRENT_SCHEMA_VERSION)
+        throw new Exception('The HQ storage requires an explicit upgrade', {
+            code: 'JG_AGENT_HQ_STORAGE_UPGRADE_REQUIRED',
+            data: { kind: 'state-conflict' },
+        });
+    if (observed.schema.hash !== schemaHash)
         throw new Exception('The HQ storage is invalid', {
             code: 'JG_AGENT_HQ_STORAGE_INVALID',
             data: { kind: 'state-conflict' },
-            cause,
         });
-    }
+    return false;
 };
 /**
  * Validates through a read-only connection before opening a writer that can checkpoint a WAL.
  * Fresh schema and stamp creation share one transaction; application objects are not converted.
  * @returns The worker-owned connection and complete HQ schema hash.
  * @throws
+ * - JG_AGENT_HQ_STORAGE_UPGRADE_REQUIRED: The HQ storage requires an explicit upgrade
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_STORAGE_INVALID: The HQ storage is invalid
  * - JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE: The HQ action key is unavailable
  */

package/dist/store/schema.sql

@@ -1,7 +1,8 @@
 CREATE TABLE hq_schema (
   id INTEGER NOT NULL CONSTRAINT hq_pk_schema__id PRIMARY KEY CHECK (id = 1),
   schema_hash TEXT NOT NULL CHECK (length(schema_hash) = 64),
-  action_key_hash TEXT NOT NULL CHECK (length(action_key_hash) = 64)
+  action_key_hash TEXT NOT NULL CHECK (length(action_key_hash) = 64),
+  schema_version INTEGER NOT NULL DEFAULT 2 CHECK (schema_version > 0)
 ) STRICT;
 
 CREATE TABLE hq_native_history_index (

package/dist/store/store.d.ts

@@ -4,6 +4,8 @@ import { type IStore } from './types.js';
  * @returns A store whose close waits for worker exit.
  * @throws
  * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
+ * - JG_AGENT_HQ_STORAGE_UPGRADE_REQUIRED: The HQ storage requires an explicit upgrade
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_STORAGE_INVALID: The HQ storage is invalid
  * - JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE: The HQ action key is unavailable
  */

package/dist/store/store.js

@@ -15,6 +15,8 @@ import { StoreRequestSchema, StoreResponseSchema, } from './types.js';
  * @returns A store whose close waits for worker exit.
  * @throws
  * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
+ * - JG_AGENT_HQ_STORAGE_UPGRADE_REQUIRED: The HQ storage requires an explicit upgrade
+ * - JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: The HQ storage version is unsupported
  * - JG_AGENT_HQ_STORAGE_INVALID: The HQ storage is invalid
  * - JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE: The HQ action key is unavailable
  */

package/docs/recovery.md

@@ -12,10 +12,24 @@ A successful snapshot has exact file hashes and a final completion marker. The d
 
 Stop all connections to the proposed destination and choose a new recovery workspace. Restore validates source and staged copies and refuses every existing target. It creates separate state and plan recovery directories, a streamed recovery.jsonl inventory and recovered.json completion record. Never use output left incomplete by a crash. Caught failures clean only the output that operation created.
 
-Start HQ with the returned stateRoot and explicit allowedRoots. Source root permissions are not imported. The runtime gets a new epoch; automation stays paused, dispatch is disabled, skill grants are revoked, approvals expire and native ownership is uncertain. Read stored reports without native histories. Inspect wait sets, continuation reservations and uncertain receipts without replaying input.
+Inspect the snapshot schema version. A restored published 2.0.0 database remains version 1; upgrade it explicitly while offline before starting current HQ. Start HQ with the returned stateRoot and explicit allowedRoots. Source root permissions are not imported. The runtime gets a new epoch; automation stays paused, dispatch is disabled, skill grants are revoked, approvals expire and native ownership is uncertain. Read stored reports without native histories. Inspect wait sets, continuation reservations and uncertain receipts without replaying input.
 
 Recover repositories and native files separately. Source paths and plan bindings are retained as evidence. Compare the selected plan companions against current files before copying them into an explicitly chosen location; never blindly replace repository files. Rebind plan references and obtain fresh authority where needed. Reconcile a pending document intent only using its original ID and unchanged/desired byte guards. Reconcile native ownership and make current-revision host lifecycle decisions before enabling execution. The snapshot does not promise path translation or restore authentication.
 
+## Upgrade and rollback
+
+Stop HQ and its native children, close every independent application database writer and pause independent plan writers. Keep the existing database and 32-byte action.key together. Normal startup never upgrades them. Choose an absent backup destination beneath an existing private canonical parent:
+
+```sh
+jg-agent-hq upgrade-storage --state-root /path/to/state --backup-directory /private/backups/before-upgrade --workspace-root /path/to/workspace
+```
+
+Repeat --workspace-root for additional trusted roots; pass --coordination-root only when the installation uses a separate existing coordination directory. The Node upgradeHqStorage API performs the same operation. Both produce a fully verified format-1 backup before migration, preserving host tables, exact reports and registered plan companions. The operation does not start a runtime, resume automation or redeem any usage reset.
+
+Retain a verified backup even after a later migration failure. Before commit, a confirmed rollback preserves logical state; WAL files need not remain byte-identical after opening a writer. An uncertain commit, lost result or cleanup error requires explicit reconciliation. Confirm workers and all independent writers have stopped, inspect the retained owner/backup evidence, then explicitly retry against the durable stamp. Current returns without another backup or reconciliation. Never blindly delete an owner or replay a migration. A current-version call leaves the supplied backup destination untouched.
+
+Rollback uses the pre-upgrade snapshot restored into a new recovery workspace with compatible software. Do not overwrite the upgraded state root. Version 1 restores need the old compatible package or the explicit upgrade before current startup. Downgrade accepts losing every change made after that snapshot, including host changes and later HQ receipts. Reconcile native ownership and obtain fresh authority before enabling work. No down-migration or automatic reverse operation exists.
+
 ## Off-machine durability
 
 The development helper examples/shared-storage.ts demonstrates a host-owned application table, maintenance, capture and offline restore using public exports. Capture already returns verified metadata, so the helper avoids an immediate extra full-database inspection. Its application transaction commits independently of capture. Inspect the restored values before starting a recovered runtime with explicitly chosen roots.