jg-agent-hq 2.0.0 → 3.0.0

package/dist/plans/documents.js

@@ -1,6 +1,6 @@
 import { hashValue as fingerprintSource } from 'jg-crypto';
 import { Exception } from 'jg-exception';
-import { fingerprintPlan, parseMilestones, parsePlan, preparePlanDocumentWrite, preparePlanUpdate, } from 'jg-plans';
+import { checkPlan, fingerprintPlan, parseMilestones, parsePlan, preparePlanDocumentWrite, preparePlanUpdate, } from 'jg-plans';
 import { z } from 'zod';
 import { PlanMetadataSchema } from '../contracts/index.js';
 const administrativeKeys = ['created_at', 'updated_at', 'revision', 'status'];
@@ -10,13 +10,35 @@ const bindingSchema = z.object({
     plan_content_sha256: z.string().regex(/^[a-f0-9]{64}$/),
 });
 const metadataSchema = z.record(z.string(), z.json());
-const invalid = (cause) => {
+/**
+ * Rejects a plan HQ cannot read or act on.
+ * @param cause The validation failure, when one exists.
+ * @throws
+ * - JG_AGENT_HQ_PLAN_INVALID: The HQ plan is invalid
+ */
+export const invalid = (cause) => {
     throw new Exception('The HQ plan is invalid', {
         code: 'JG_AGENT_HQ_PLAN_INVALID',
         data: { kind: 'invalid-request' },
         cause,
     });
 };
+/**
+ * Checks a protocol 0.2 plan with jg-plans for the stages HQ gates. Plan approval needs plan.md
+ * to conform alone; finalization, sequence approval, authorization, and execution need it to
+ * conform with its milestones. Plans without the 0.2 marker always conform, as before.
+ * @param plan Exact plan.md source.
+ * @param milestones Exact milestones.md source, or null when absent.
+ * @returns The conformance of each stage.
+ */
+export const observePlanConformance = (plan, milestones) => {
+    if (parsePlan(plan).protocol !== '0.2')
+        return { plan: true, sequence: true };
+    return {
+        plan: checkPlan({ plan }).conforms,
+        sequence: checkPlan({ plan, ...(milestones === null ? {} : { milestones }) }).conforms,
+    };
+};
 /** Metadata must be available as plain JSON; absence alone supplies an empty mapping. */
 const metadataOf = (document) => {
     if (!document.frontmatter)

package/dist/plans/files.js

@@ -6,7 +6,7 @@ import { Exception, extractMessage, hasErrorCode, isException } from 'jg-excepti
 import { PlanCoordinationSchema, } from '../contracts/index.js';
 import { resolveWorkspaceTarget } from '../runtime/state/index.js';
 import { computeObservedPlanRevision, hashPlanContent, projectPlanMilestones, } from './utilities.js';
-import { observePlanContract, observeSkillsBinding, observeSequence } from './documents.js';
+import { observePlanConformance, observePlanContract, observeSkillsBinding, observeSequence, } from './documents.js';
 const MAX_PLAN_BYTES = 1_048_576;
 /**
  * Reads one bounded regular artifact without following a file symlink.
@@ -168,6 +168,8 @@ export const readPlanArtifacts = async (target, roots, parseContract) => {
             milestones: milestones === null ? null : hashPlanContent(milestones),
             coordination: coordinationText === null ? null : hashPlanContent(coordinationText),
         },
+        // observed, not enforced: reads and revisions continue while stage gates use the result
+        conformance: observePlanConformance(plan, milestones),
     };
 };
 /** Flushes fixed-name creation/removal before journal completion. */

package/dist/plans/plans.js

@@ -9,7 +9,7 @@ import { resolveWorkspaceTarget } from '../runtime/state/index.js';
 import { canExecutePlanUnit, describePlan, updatePlanAuthority } from './authority.js';
 import { createPlanAdmission } from './admission.js';
 import { readPlanPage } from './projections.js';
-import { prepareAggregateProgress, prepareSequenceMarkers } from './documents.js';
+import { invalid, prepareAggregateProgress, prepareSequenceMarkers } from './documents.js';
 import { finalizeInitialSequence } from './finalization.js';
 import { beginPlanRevision, finishPlanCheckpoint, recordPlanCompletion, refreshPlanBaseline, } from './revisions.js';
 import { capturePlanWorktrees } from './evidence.js';
@@ -594,6 +594,8 @@ export const createPlans = (coordinationRoot, roots, store, runtimeEpoch, parseC
                     }
                 }
                 else if (command.kind === 'finalize') {
+                    if (!artifacts.conformance.sequence)
+                        invalid();
                     if (artifacts.skillsBinding === 'stale')
                         conflict();
                     const workflow = coordination.revision;

package/dist/plans/types.d.ts

@@ -22,12 +22,17 @@ export type IPlanArtifacts = {
         milestones: string | null;
         coordination: string | null;
     };
+    conformance: IPlanConformance;
 };
 export type IPlanContract = {
     body: string;
     metadata: IPlanMetadata;
     milestones: string | null;
 };
+export type IPlanConformance = {
+    plan: boolean;
+    sequence: boolean;
+};
 export declare const PlanWriteIntentSchema: z.ZodObject<{
     id: z.ZodUUID;
     digest: z.ZodString;

package/dist/providers/claude/claude.js

@@ -25,6 +25,8 @@ export const createClaudeProvider = (store) => {
         observedAt: null,
         ordinaryUsageAllowed: null,
         windows: [],
+        credits: null,
+        resetCredits: null,
     });
     let latest = unavailable();
     const connect = async () => {

package/dist/providers/claude/history/types.d.ts

@@ -4285,7 +4285,30 @@ export declare const ClaudeHistoryReadSchema: z.ZodUnion<readonly [z.ZodDiscrimi
             remainingPercent: z.ZodNumber;
             durationMinutes: z.ZodNullable<z.ZodNumber>;
             resetsAt: z.ZodNullable<z.ZodNumber>;
+            period: z.ZodOptional<z.ZodEnum<{
+                "five-hour": "five-hour";
+                "seven-day": "seven-day";
+                other: "other";
+            }>>;
+            nativeKind: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            group: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            scope: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                model: z.ZodNullable<z.ZodObject<{
+                    id: z.ZodNullable<z.ZodString>;
+                    displayName: z.ZodString;
+                }, z.core.$strip>>;
+                surface: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>>;
         }, z.core.$strip>>;
+        credits: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+            bucket: z.ZodString;
+            hasCredits: z.ZodBoolean;
+            isUnlimited: z.ZodBoolean;
+            balance: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>>>;
+        resetCredits: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            availableCount: z.ZodNumber;
+        }, z.core.$strip>>>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"skills">;

package/dist/providers/claude/transformers.js

@@ -27,8 +27,19 @@ export const toClaudeUsageSnapshot = (result, observedAt) => {
             window: row.group === 'session' ? 'primary' : 'secondary',
             usedPercent: row.percent,
             remainingPercent: Math.max(0, 100 - row.percent),
-            durationMinutes: null,
+            durationMinutes: row.group === 'session' ? 300 : row.group === 'weekly' ? 10080 : null,
             resetsAt: row.resets_at === null ? null : Date.parse(row.resets_at),
+            period: row.group === 'session' ? 'five-hour' : row.group === 'weekly' ? 'seven-day' : 'other',
+            nativeKind: row.kind,
+            group: row.group,
+            scope: row.scope
+                ? {
+                    model: row.scope.model
+                        ? { id: row.scope.model.id, displayName: row.scope.model.display_name }
+                        : null,
+                    surface: row.scope.surface,
+                }
+                : null,
         });
     }
     return {
@@ -37,6 +48,8 @@ export const toClaudeUsageSnapshot = (result, observedAt) => {
         observedAt,
         ordinaryUsageAllowed: null,
         windows,
+        credits: null,
+        resetCredits: null,
         state: !result.rate_limits_available || windows.length === 0
             ? 'unavailable'
             : result.rate_limits?.limits.some((row) => row.is_active && row.percent !== null && row.percent >= 100)

package/dist/providers/codex/codex.js

@@ -26,6 +26,8 @@ export const createCodexProvider = async (extraSkillRoots = [], agentTools) => {
         observedAt: null,
         ordinaryUsageAllowed: null,
         windows: [],
+        credits: null,
+        resetCredits: null,
     };
     let rpc;
     let refresh;
@@ -218,6 +220,8 @@ export const createCodexProvider = async (extraSkillRoots = [], agentTools) => {
                     observedAt: null,
                     ordinaryUsageAllowed: null,
                     windows: [],
+                    credits: null,
+                    resetCredits: null,
                 };
             }
             if (method === 'account/rateLimits/updated' &&

package/dist/providers/codex/transformers.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { UsageSnapshotSchema, ThreadSummarySchema, TurnSummarySchema, HistoryItemSchema, } from '../../contracts/index.js';
+import { UsageSnapshotSchema, UsageCreditsSchema, ThreadSummarySchema, TurnSummarySchema, HistoryItemSchema, } from '../../contracts/index.js';
 import { parseNative } from './validations.js';
 import { nativeProvenance } from '../../sessions/evidence/index.js';
 /** Preserves exact native tree identities independently of managed-agent relationships. */
@@ -122,9 +122,25 @@ export const toHistoryItem = ({ turnId, item }, fullBody = false) => {
  * - JG_AGENT_HQ_CODEX_FAILED: The Codex integration failed
  */
 export const toUsageSnapshot = (usage, observedAt) => {
-    const buckets = usage.rateLimitsByLimitId ?? {};
+    const nativeBuckets = usage.rateLimitsByLimitId;
+    const buckets = nativeBuckets && Object.keys(nativeBuckets).length > 0
+        ? nativeBuckets
+        : usage.rateLimits
+            ? { [usage.rateLimits.limitId ?? 'legacy']: usage.rateLimits }
+            : {};
     const windows = [];
-    for (const [bucketId, bucket] of Object.entries(buckets))
+    const credits = [];
+    for (const [bucketId, bucket] of Object.entries(buckets)) {
+        if (bucket.credits) {
+            const observed = UsageCreditsSchema.safeParse({
+                bucket: bucketId,
+                hasCredits: bucket.credits.hasCredits,
+                isUnlimited: bucket.credits.unlimited,
+                balance: bucket.credits.balance,
+            });
+            if (observed.success)
+                credits.push(observed.data);
+        }
         for (const window of ['primary', 'secondary']) {
             const entry = bucket[window];
             if (entry)
@@ -137,8 +153,17 @@ export const toUsageSnapshot = (usage, observedAt) => {
                     remainingPercent: Math.max(0, 100 - entry.usedPercent),
                     durationMinutes: entry.windowDurationMins ?? null,
                     resetsAt: entry.resetsAt == null ? null : entry.resetsAt * 1000,
+                    period: entry.windowDurationMins === 300
+                        ? 'five-hour'
+                        : entry.windowDurationMins === 10080
+                            ? 'seven-day'
+                            : 'other',
+                    nativeKind: null,
+                    group: null,
+                    scope: null,
                 });
         }
+    }
     const reached = Object.values(buckets).some((bucket) => bucket.rateLimitReachedType != null);
     const state = windows.length === 0
         ? 'unavailable'
@@ -152,5 +177,7 @@ export const toUsageSnapshot = (usage, observedAt) => {
         observedAt,
         ordinaryUsageAllowed: usage.ordinaryUsageAllowed ?? null,
         windows,
+        credits: credits.length > 0 ? credits : null,
+        resetCredits: usage.rateLimitResetCredits ?? null,
     });
 };

package/dist/providers/codex/types.d.ts

@@ -99,9 +99,14 @@ export declare const NativeBucketSchema: z.ZodObject<{
         resetsAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strip>>>;
     rateLimitReachedType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    credits: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        hasCredits: z.ZodBoolean;
+        unlimited: z.ZodBoolean;
+        balance: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>>>;
 }, z.core.$strip>;
 export declare const NativeUsageSchema: z.ZodObject<{
-    rateLimitsByLimitId: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodObject<{
+    rateLimitsByLimitId: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodObject<{
         limitId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         limitName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         primary: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -115,7 +120,35 @@ export declare const NativeUsageSchema: z.ZodObject<{
             resetsAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         }, z.core.$strip>>>;
         rateLimitReachedType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        credits: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            hasCredits: z.ZodBoolean;
+            unlimited: z.ZodBoolean;
+            balance: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strip>>>>;
+    rateLimits: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        limitId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        limitName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        primary: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            usedPercent: z.ZodNumber;
+            windowDurationMins: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            resetsAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$strip>>>;
+        secondary: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            usedPercent: z.ZodNumber;
+            windowDurationMins: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            resetsAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$strip>>>;
+        rateLimitReachedType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        credits: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            hasCredits: z.ZodBoolean;
+            unlimited: z.ZodBoolean;
+            balance: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>>>;
     }, z.core.$strip>>>;
+    rateLimitResetCredits: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        availableCount: z.ZodNumber;
+    }, z.core.$strip>>>>;
     ordinaryUsageAllowed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
 }, z.core.$strip>;
 export type INativeThread = z.infer<typeof NativeThreadSchema>;

package/dist/providers/codex/types.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { MAX_PAGE_SIZE, } from '../../contracts/index.js';
+import { MAX_PAGE_SIZE, UsageCreditsSchema, UsageResetCreditsSchema, } from '../../contracts/index.js';
 // additive native responses are narrowed to fields this adapter actually uses
 export const NativeThreadSchema = z.object({
     id: z.string().min(1).max(4096),
@@ -41,15 +41,24 @@ const NativeWindowSchema = z.object({
     windowDurationMins: z.number().int().positive().nullable().optional(),
     resetsAt: z.number().int().safe().nullable().optional(),
 });
+// optional billing metadata may be unavailable without invalidating measured quota windows
+const NativeCreditsSchema = z.object({
+    hasCredits: UsageCreditsSchema.shape.hasCredits,
+    unlimited: UsageCreditsSchema.shape.isUnlimited,
+    balance: UsageCreditsSchema.shape.balance,
+});
 export const NativeBucketSchema = z.object({
     limitId: z.string().nullable().optional(),
     limitName: z.string().nullable().optional(),
     primary: NativeWindowSchema.nullable().optional(),
     secondary: NativeWindowSchema.nullable().optional(),
     rateLimitReachedType: z.string().nullable().optional(),
+    credits: NativeCreditsSchema.nullable().optional().catch(null),
 });
 export const NativeUsageSchema = z.object({
-    rateLimitsByLimitId: z.record(z.string(), NativeBucketSchema).nullable(),
+    rateLimitsByLimitId: z.record(z.string(), NativeBucketSchema).nullable().optional(),
+    rateLimits: NativeBucketSchema.nullable().optional(),
+    rateLimitResetCredits: UsageResetCreditsSchema.nullable().optional().catch(null),
     ordinaryUsageAllowed: z.boolean().nullable().optional(),
 });
 // native discovery is unpaged; limit inventory size and retain only display/invocation metadata

package/dist/runtime/runtime.d.ts

@@ -15,6 +15,8 @@ import { type IAgentHq, type IAgentHqOptions } from './types.js';
  * - JG_AGENT_HQ_RUNTIME_NOT_RUNNING: The HQ runtime is not running
  * - JG_AGENT_HQ_TRANSPORT_FAILED: The HQ transport failed
  * - 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
  */
 export declare const createAgentHq: (options: IAgentHqOptions) => Promise<IAgentHq>;

package/dist/runtime/runtime.js

@@ -39,6 +39,8 @@ const UnconfirmedCleanupSchema = z.object({ cleanupUnconfirmed: z.literal(true)
  * - JG_AGENT_HQ_RUNTIME_NOT_RUNNING: The HQ runtime is not running
  * - JG_AGENT_HQ_TRANSPORT_FAILED: The HQ transport failed
  * - 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
  */
 export const createAgentHq = async (options) => {

package/dist/runtime/state/index.d.ts

@@ -1,2 +1,2 @@
-export { prepareStateRoot, resolveAllowedRoots, isWithinWorkspace, resolveWorkspaceTarget, readRuntimeOwner, claimRuntimeOwner, prepareDatabase, prepareActionKey, } from './state.js';
+export { prepareStateRoot, readExistingState, resolveAllowedRoots, isWithinWorkspace, resolveWorkspaceTarget, readRuntimeOwner, claimRuntimeOwner, prepareDatabase, prepareActionKey, } from './state.js';
 export { RUNTIME_OWNER_FILE, DATABASE_FILE } from './constants.js';

package/dist/runtime/state/index.js

@@ -1,3 +1,3 @@
 // state ownership and trusted paths
-export { prepareStateRoot, resolveAllowedRoots, isWithinWorkspace, resolveWorkspaceTarget, readRuntimeOwner, claimRuntimeOwner, prepareDatabase, prepareActionKey, } from './state.js';
+export { prepareStateRoot, readExistingState, resolveAllowedRoots, isWithinWorkspace, resolveWorkspaceTarget, readRuntimeOwner, claimRuntimeOwner, prepareDatabase, prepareActionKey, } from './state.js';
 export { RUNTIME_OWNER_FILE, DATABASE_FILE } from './constants.js';

package/dist/runtime/state/state.d.ts

@@ -56,7 +56,7 @@ export declare const readRuntimeOwner: (stateRoot: string) => Promise<{
  * - JG_AGENT_HQ_RUNTIME_OWNER_UNVERIFIABLE: The HQ runtime owner is unverifiable
  * - JG_AGENT_HQ_RUNTIME_NOT_RUNNING: The HQ runtime is not running
  */
-export declare const claimRuntimeOwner: (stateRoot: string) => Promise<{
+export declare const claimRuntimeOwner: (stateRoot: string, command?: "serve" | "upgrade-storage") => Promise<{
     owner: {
         pid: number;
         nonce: string;
@@ -72,3 +72,18 @@ export declare const claimRuntimeOwner: (stateRoot: string) => Promise<{
  * - JG_AGENT_HQ_STATE_FILE_UNSAFE: The HQ state file is unsafe
  */
 export declare const prepareDatabase: (stateRoot: string) => Promise<string>;
+/**
+ * Validates existing offline storage without creating directories, database files or keys.
+ * @returns Canonical state and the exact existing private key.
+ * @throws
+ * - JG_AGENT_HQ_LOCK_UNSUPPORTED_PLATFORM: The HQ lock requires Linux or macOS
+ * - 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
+ */
+export declare const readExistingState: (stateRoot: string) => Promise<{
+    stateRoot: string;
+    databasePath: string;
+    actionKey: Uint8Array;
+}>;

package/dist/runtime/state/state.js

@@ -1,7 +1,8 @@
 import { constants } from 'node:fs';
 import { lstat, open, realpath, rm } from 'node:fs/promises';
-import { isAbsolute, join, relative, sep } from 'node:path';
+import { isAbsolute, join, relative, sep, parse, resolve } from 'node:path';
 import { randomBytes, randomUUID } from 'node:crypto';
+import { assertNoLinksBelow } from 'jg-fs';
 import { Exception, extractMessage, hasErrorCode, isException } from 'jg-exception';
 import { ensurePrivateRuntimeDirectory, HqLockOwnerSchema, isPrivateOwner, } from '../../locks/index.js';
 import { ACTION_KEY_FILE, DATABASE_FILE, RUNTIME_OWNER_FILE } from './constants.js';
@@ -215,11 +216,11 @@ export const readRuntimeOwner = async (stateRoot) => {
  * - JG_AGENT_HQ_RUNTIME_OWNER_UNVERIFIABLE: The HQ runtime owner is unverifiable
  * - JG_AGENT_HQ_RUNTIME_NOT_RUNNING: The HQ runtime is not running
  */
-export const claimRuntimeOwner = async (stateRoot) => {
+export const claimRuntimeOwner = async (stateRoot, command = 'serve') => {
     const owner = {
         pid: process.pid,
         nonce: randomUUID(),
-        command: 'serve',
+        command,
         createdAt: new Date().toISOString(),
     };
     const content = `${JSON.stringify(owner)}\n`;
@@ -294,3 +295,93 @@ export const prepareDatabase = async (stateRoot) => {
     }
     return path;
 };
+/**
+ * Validates existing offline storage without creating directories, database files or keys.
+ * @returns Canonical state and the exact existing private key.
+ * @throws
+ * - JG_AGENT_HQ_LOCK_UNSUPPORTED_PLATFORM: The HQ lock requires Linux or macOS
+ * - 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
+ */
+export const readExistingState = async (stateRoot) => {
+    if (process.platform !== 'linux' && process.platform !== 'darwin')
+        throw new Exception('The HQ lock requires Linux or macOS', {
+            code: 'JG_AGENT_HQ_LOCK_UNSUPPORTED_PLATFORM',
+        });
+    if (!isAbsolute(stateRoot) || resolve(stateRoot) !== stateRoot)
+        throw new Exception('The HQ request is invalid', {
+            code: 'JG_AGENT_HQ_REQUEST_INVALID',
+            data: { kind: 'invalid-request' },
+        });
+    try {
+        await assertNoLinksBelow(parse(stateRoot).root, stateRoot);
+        const directory = await lstat(stateRoot);
+        if (!directory.isDirectory() ||
+            !isPrivateOwner(directory) ||
+            (await realpath(stateRoot)) !== stateRoot)
+            throw new Exception('The HQ state directory is unsafe', {
+                code: 'JG_AGENT_HQ_STATE_DIRECTORY_UNSAFE',
+                data: { kind: 'state-conflict' },
+            });
+    }
+    catch (cause) {
+        if (hasErrorCode(cause, 'JG_AGENT_HQ_STATE_DIRECTORY_UNSAFE'))
+            throw cause;
+        throw new Exception(`The HQ state directory is unsafe: ${extractMessage(cause)}`, {
+            code: 'JG_AGENT_HQ_STATE_DIRECTORY_UNSAFE',
+            data: { kind: 'state-conflict' },
+            cause,
+        });
+    }
+    const databasePath = join(stateRoot, DATABASE_FILE);
+    for (const filename of [
+        databasePath,
+        `${databasePath}-wal`,
+        `${databasePath}-shm`,
+        `${databasePath}-journal`,
+    ]) {
+        try {
+            const details = await lstat(filename);
+            if (!details.isFile() ||
+                details.isSymbolicLink() ||
+                details.nlink !== 1 ||
+                !isPrivateOwner(details))
+                throw new Exception('The HQ state file is unsafe', {
+                    code: 'JG_AGENT_HQ_STATE_FILE_UNSAFE',
+                    data: { kind: 'state-conflict' },
+                });
+        }
+        catch (cause) {
+            if (filename !== databasePath && hasErrorCode(cause, 'ENOENT'))
+                continue;
+            if (hasErrorCode(cause, 'JG_AGENT_HQ_STATE_FILE_UNSAFE'))
+                throw cause;
+            throw new Exception(`The HQ state file is unsafe: ${extractMessage(cause)}`, {
+                code: 'JG_AGENT_HQ_STATE_FILE_UNSAFE',
+                data: { kind: 'state-conflict' },
+                cause,
+            });
+        }
+    }
+    let actionKey;
+    try {
+        actionKey = await readPrivateBytes(join(stateRoot, ACTION_KEY_FILE), 32);
+    }
+    catch (cause) {
+        if (isException(cause))
+            throw cause;
+        throw new Exception(`The HQ action key is unavailable: ${extractMessage(cause)}`, {
+            code: 'JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE',
+            data: { kind: 'state-conflict' },
+            cause,
+        });
+    }
+    if (actionKey.length !== 32)
+        throw new Exception('The HQ action key is unavailable', {
+            code: 'JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE',
+            data: { kind: 'state-conflict' },
+        });
+    return { stateRoot, databasePath, actionKey };
+};

package/dist/snapshots/capture.d.ts

@@ -0,0 +1,14 @@
+import { type ISnapshotSource, type IHqSnapshotInspection } from './types.js';
+/**
+ * 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 declare const captureSnapshot: (context: ISnapshotSource, destination: string) => Promise<IHqSnapshotInspection>;