jg-agent-hq 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 3.0.0
+
+- Check protocol 0.2 plans with jg-plans 0.3.0 at each stage that grants authority: plan approval requires plan.md to conform, and finalization, sequence approval, authorization and execution require plan.md and milestones.md to conform together. Reading, status and revision workflows are unaffected, and plans without the 0.2 marker keep their current behavior.
+
+- Version HQ storage independently of host user_version. Add explicit offline Node/CLI upgrades with a verified pre-upgrade backup, transactional rollback and uncertainty handling, retaining published 2.0.0 snapshots and version-specific restore fences.
+
+- Expose native Codex credit balances and available earned resets without consuming them. Preserve valid single-bucket quota responses when the multi-bucket view is absent.
+- Identify Claude five-hour and seven-day usage meters with explicit model/surface scopes, preserving independent windows, reset times and account-bound freshness. Keep older provider observations compatible.
+
 ## 2.0.0
 
 - Add provider-neutral session capabilities, native lifecycle/configuration, file inputs, structured results, permissions, account observations and extension controls. Detect usable native contracts instead of restricting CLI version labels; isolate unavailable providers.

package/README.md

@@ -41,13 +41,13 @@ Install the providers you want and sign in through their native CLIs, then start
 
 The Node API exposes `createAgentHq({ stateRoot, allowedRoots })` and `requestAgentHq(stateRoot, command)`. Configuration comes from these trusted operator inputs. Coding-instruction files are not runtime configuration.
 
-The controller owns its SQLite worker and native connections independently of client connections. Its provider registry starts each native integration only when selected. Storage and managed-session reads work without an installed coding CLI; an unavailable provider does not disable another provider. Private state contains the lifetime owner, Unix socket and SQLite discovery metadata. Conversation histories remain in native storage; HQ retains complete bounded final results on their action receipts. Browsing never resumes an external session or starts inference. Quota windows come from native account observations, with explicit stale and unavailable states.
+The controller owns its SQLite worker and native connections independently of client connections. Its provider registry starts each native integration only when selected. Storage and managed-session reads work without an installed coding CLI; an unavailable provider does not disable another provider. Private state contains the lifetime owner, Unix socket and SQLite discovery metadata. Conversation histories remain in native storage; HQ retains complete bounded final results on their action receipts. Browsing never resumes an external session or starts inference. Quota windows come from native account observations, with explicit stale and unavailable states. Usage reads include Codex credit balances and available earned-reset counts when reported, plus Claude five-hour and seven-day meters with their model/surface scopes and reset times.
 
 Use `sessions` for discovery and `session-evidence` for newest-first historical evidence. These reads fit within 65,536 serialized bytes, retain exact native identities and content hashes, and continue large bodies in UTF-8 chunks. Select an item, turn or item kinds with filters. Matching names remain separate sessions. Provenance distinguishes native evidence from exact host submissions; historical text and quoted feedback never grant approval. See [bounded session evidence](api/README.md#bounded-session-evidence).
 
-Trusted Node hosts can open the database described by `hq.storage` and keep application tables under their own prefix. HQ reserves `hq_`, validates its current schema stamp on startup, and leaves application schema ownership and `user_version` with the host. Use `hq.withStorageMaintenance(callback)` for host schema changes; it drains admitted work and rejects active native execution before the callback. Start with a fresh development state root when the HQ schema changes. See the [shared storage contract](api/README.md#shared-storage).
+Trusted Node hosts can open the database described by `hq.storage` and keep application tables under their own prefix. HQ reserves `hq_`, validates its current schema stamp on startup, and leaves application schema ownership and `user_version` with the host. Use `hq.withStorageMaintenance(callback)` for host schema changes; it drains admitted work and rejects active native execution before the callback. Fresh state starts at HQ storage version 2. Published 2.0.0 state requires an explicit offline upgrade; startup never migrates. Stop HQ and independent database/plan writers, then run `jg-agent-hq upgrade-storage --state-root /path/to/state --backup-directory /private/backups/before-upgrade --workspace-root /path/to/workspace`. The backup destination must be absent under an existing private canonical parent. Keep the verified backup. Trusted Node hosts use `upgradeHqStorage(options)` for the same operation. See the [shared storage contract](api/README.md#shared-storage).
 
-`createHqSnapshot(hq, destination)` captures quiescent local state through SQLite's backup API, including host tables, stored reports, action.key and registered plan companions. Busy checkpoints return a conflict without interrupting work. `inspectHqSnapshot(directory)` verifies the complete snapshot; `restoreHqSnapshot({ snapshotDirectory, destination })` validates and stages it into a new private recovery workspace. Restored automation is paused, skill grants are revoked, native ownership needs reconciliation and allowed roots must be selected explicitly. Hosts own remote backups; a failed disk can lose changes since the last successful off-machine backup. See [snapshot and restore](api/README.md#snapshot-and-restore) and [recovery](docs/recovery.md).
+`createHqSnapshot(hq, destination)` captures quiescent local state through SQLite's backup API, including host tables, stored reports, action.key and registered plan companions. Busy checkpoints return a conflict without interrupting work. `inspectHqSnapshot(directory)` verifies the complete snapshot; `restoreHqSnapshot({ snapshotDirectory, destination })` validates and stages it into a new private recovery workspace. Version 1 and version 2 snapshots remain supported. Restored version 1 storage requires the explicit offline upgrade before startup. Restored automation is paused, skill grants are revoked, native ownership needs reconciliation and allowed roots must be selected explicitly. Hosts own remote backups; a failed disk can lose changes since the last successful off-machine backup. See [snapshot and restore](api/README.md#snapshot-and-restore) and [recovery](docs/recovery.md).
 
 Provider IDs are bounded lowercase identifiers. Codex and Claude are built in; trusted Node hosts can register additional `IAgentProviderFactory` implementations through `providerFactories`. Capabilities report current operation support, provider/session scope and unavailable reasons. Native version labels are diagnostic metadata and never determine admission. Unknown essential control data fails explicitly. `jg-agent-hq/contracts` contains browser-safe schemas and types; importing it does not import the host runtime.
 
@@ -127,7 +127,7 @@ The [qualification matrix](api/README.md#qualification) records native journeys,
 - `src/collaboration/identity/` and `src/agent-tools/`: native-bound identity, private bridge credentials, shared agent tools and the stdio MCP entry.
 - `src/actions/`: durable action dispatch, native input routing and bounded live presentation.
 - `src/store/`: SQLite discovery metadata, collaboration streams and the action/control ledger in one worker.
-- `src/storage/`: trusted host connection metadata and exclusive maintenance admission.
+- `src/storage/`: trusted host metadata, exclusive maintenance, schema lineage and offline upgrades.
 - `src/snapshots/`: quiescent capture, streamed inventory validation and offline recovery with execution paused.
 - `src/contracts/`: browser-safe command and response contracts.
 - `scripts/package/`: build-output cleanup and packed-consumer checks.

package/api/README.md

@@ -22,12 +22,49 @@ All operations may expose the relevant intentional contracts in [errors](../erro
 
 `hq.storage` returns an independent `IStorageDescriptor` containing the canonical `databasePath`, `schemaHash`, `reservedPrefix` (`hq_`), and required `connectionSettings`: `foreignKeys` true, `busyTimeoutMs` 5000, `journalMode` wal, and `synchronous` full. Exported Node types are `IStorageDescriptor` and `IStorageMaintenanceOperation<T>`. No database handle, storage callback, raw SQL command or storage path is exposed by browser contracts or IPC.
 
-For node:sqlite, open the host connection with `new DatabaseSync(storage.databasePath, { timeout: storage.connectionSettings.busyTimeoutMs, enableForeignKeyConstraints: storage.connectionSettings.foreignKeys })`. These options enable foreign keys and a 5,000 ms busy timeout; the descriptor itself is not a DatabaseSync options object. See the [Node 24 SQLite API](https://nodejs.org/download/release/v24.15.0/docs/api/sqlite.html#new-databasesyncpath-options). Keep WAL mode and FULL synchronization; do not change database-wide settings while HQ is running. Hosts own their table prefix, definitions, connection lifetime and user_version. HQ-owned tables and indexes are reserved. A nonempty database requires the matching singleton hq_schema stamp; otherwise startup throws JG_AGENT_HQ_STORAGE_INVALID without changing the database. The stamp also binds the SHA-256 fingerprint of action.key; a different valid-length key fails with JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE before a writer opens. Fresh initialization is transactional.
+For node:sqlite, open the host connection with `new DatabaseSync(storage.databasePath, { timeout: storage.connectionSettings.busyTimeoutMs, enableForeignKeyConstraints: storage.connectionSettings.foreignKeys })`. These options enable foreign keys and a 5,000 ms busy timeout; the descriptor itself is not a DatabaseSync options object. See the [Node 24 SQLite API](https://nodejs.org/download/release/v24.15.0/docs/api/sqlite.html#new-databasesyncpath-options). Keep WAL mode and FULL synchronization; do not change database-wide settings while HQ is running. Hosts own their table prefix, definitions, connection lifetime and user_version. HQ-owned tables and indexes are reserved. A nonempty database requires a recognized singleton hq_schema stamp. Fresh state uses version 2. Exact published 2.0.0 state is version 1 and startup throws JG_AGENT_HQ_STORAGE_UPGRADE_REQUIRED before opening a writer. Unknown well-formed versions/hashes use JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED; malformed stamps and conflicting known version/hash pairs use JG_AGENT_HQ_STORAGE_INVALID. Rejected storage remains unchanged. The stamp also binds the SHA-256 fingerprint of action.key; a different valid-length key fails with JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE before a writer opens. Fresh initialization is transactional.
 
 `await hq.withStorageMaintenance(operation)` passes the storage descriptor to the async operation and returns its result. It closes admission before draining accepted HQ operations, allows their awaited nested calls and required native evidence to finish, and checks for active native execution or prepared plan writes before invoking the callback. Concurrent maintenance, new HQ requests, browser host effects and shutdown conflict while maintenance is held. During the callback, native event persistence waits in its existing bounded lane, and an already accepted scheduled stop waits for release. The callback must not call HQ, start native work or leave transactions open. Its errors propagate unchanged; it owns rollback and reconciliation for its SQL effects. After success or failure, HQ admission resumes. Calls after shutdown use JG_AGENT_HQ_RUNTIME_NOT_RUNNING.
 
 The host must coordinate every application connection that can write during maintenance. A shared file gives SQLite transaction isolation, not an atomic transaction spanning host SQL and HQ API calls. HQ does not expose its worker connection. Snapshot scheduling and remote backup operations belong to the host application.
 
+## Offline storage upgrade
+
+Import `upgradeHqStorage`, `IHqStorageUpgradeOptions` and `IHqStorageUpgradeResult` from the Node root. This operation is absent from browser contracts, IPC and agent tools.
+
+```ts
+interface IHqStorageUpgradeOptions {
+  stateRoot: string;
+  backupDirectory: string;
+  allowedRoots: string[];
+  coordinationRoot?: string;
+}
+interface IHqStorageUpgradeResult {
+  stateRoot: string;
+  state: 'upgraded' | 'current';
+  fromVersion: number;
+  toVersion: number;
+  fromSchemaHash: string;
+  toSchemaHash: string;
+  backupDirectory: string | null;
+}
+// upgradeHqStorage(options): Promise<IHqStorageUpgradeResult>
+```
+
+Stop HQ and its native children, close independent application database writers and pause independent plan writers first. Supply existing canonical absolute state/workspace paths and an absent backup directory beneath an existing private canonical parent. The backup must not overlap the source state or any registered plan source. coordinationRoot defaults to stateRoot. A separate coordinationRoot may be a normal project directory; its .runtime lock directory remains private. Inputs are trusted operator selections; stored roots never grant access. Existing live, dead, incomplete or unverifiable lifetime owners block the operation and are never automatically reclaimed.
+
+The installed CLI invokes the same API directly without a controller, listening socket or provider:
+
+```sh
+jg-agent-hq upgrade-storage --state-root /path/to/state --backup-directory /private/backups/before-upgrade --workspace-root /path/to/workspace --workspace-root /path/to/other-workspace --coordination-root /path/to/coordination
+```
+
+At least one --workspace-root is required; --coordination-root is optional. Other command flags are rejected, and --backup-directory is rejected on other commands. Success writes one stdout JSON line `{ schemaVersion: 1, kind: 'upgrade-storage', result }`. Failure retains exit 1 and stderr `{ schemaVersion: 1, success: false, error: { kind, message } }`. Only the four canonical storage upgrade/version messages bypass generic CLI classifications; private causes, paths and diagnostic suffixes are removed. `serve` presents the same explicit-upgrade-required message on legacy state. Help documents this operator path.
+
+Read-only classification rejects unsupported/corrupt state before a writer or backup reservation. A current version returns current with backupDirectory null, without DDL, backup reservation or startup reconciliation. For version 1, lifetime ownership and the metadata lock protect a BEGIN IMMEDIATE checkpoint. A separate read-only connection captures the same complete format-1 snapshot as createHqSnapshot, including host tables, the private key, exact reports and registered companions. Full verification precedes DDL. Migration updates version/hash in one transaction, verifies integrity/foreign keys and preserves application objects, user_version, keys, receipts, queues, grants and collaboration state. Migration grants no authority and starts no native work.
+
+The dedicated worker has no whole-operation size deadline. The caller waits for actual exit before lifetime ownership is released. A pre-commit failure rolls back; once a backup verifies, it remains the operator's recovery deliverable even if migration fails. Post-commit, acknowledgement or cleanup uncertainty uses JG_AGENT_HQ_STORAGE_UPGRADE_UNCERTAIN with trusted Node phase/backup diagnostics. A lost worker result may identify only the requested backup path; inspect its completion evidence before using it. Never automatically reverse or replay it. An explicit retry reads the durable stamp and returns current if committed. Process death can leave ownership requiring deliberate inspection. Keep the verified backup and follow the [recovery procedure](../docs/recovery.md); no down-migration is supplied.
+
 ## Snapshot and restore
 
 Import createHqSnapshot, inspectHqSnapshot and restoreHqSnapshot from jg-agent-hq in a trusted Node host. They are absent from browser contracts, IPC and agent tools. The exported types are IHqSnapshotInspection, IHqRestoreOptions and IHqRestoreResult.
@@ -44,15 +81,15 @@ SQLite's worker-owned backup API includes committed WAL data and every table in
 
 The one inventory format is manifest.jsonl: header, database, action-key and ordered plan records. Each plan's generated directory is `plans/<SHA-256 of source directory>`. Records retain exact source directory, observed plan ID/revision, companion byte counts/hashes and bounded diagnostics. Missing source plans, parser observations and corrupt coordination remain visible evidence; capture does not repair them or require checker conformance. Registered plans outside the runtime's current allowed roots retain an unavailable record without reading their files. A final complete.json binds the complete manifest hash and record count. Directories are private (0700), files are private (0600), and destinations are created exclusively. Runtime sockets, owner records, process IDs, bridge credentials and provider authentication are excluded.
 
-Inspection streams the inventory, verifies each listed regular file and every expected/absent companion, rejects links and unsafe paths, checks the current HQ schema stamp and database/key pairing, SQLite integrity/foreign keys, exact report hashes and complete registered-plan coverage. It rechecks captured plan identities and diagnostics. Full database verification runs in a dedicated worker. Inspection returns bounded directory/header/hash/count metadata; it does not load a growing inventory into memory. Hashes detect corruption and bind content; they do not authenticate a snapshot supplied by an untrusted party.
+Inspection streams the inventory, verifies each listed regular file and every expected/absent companion, rejects links and unsafe paths, checks an exact supported HQ schema stamp (version 1 or 2) and database/key pairing, SQLite integrity/foreign keys, exact report hashes and complete registered-plan coverage. It rechecks captured plan identities and diagnostics. Full database verification runs in a dedicated worker. Inspection returns bounded directory/header/hash/count metadata; it does not load a growing inventory into memory. Hashes detect corruption and bind content; they do not authenticate a snapshot supplied by an untrusted party.
 
 Restore leaves every existing destination untouched, including an empty directory, repository or live state root. Use a new directory. It validates the source before reserving that directory and validates the staged copy independently against the initially inspected manifest hash before changing recovery authority. On success, stateRoot points to destination/state, recoveryRoot to destination/plans, recovery.jsonl retains the source inventory and recovered.json records completion. Caught failures remove only the operation's newly created output. A crash can leave incomplete output; do not open it as a recovered runtime.
 
 Restored task and agent lifecycles are paused unless already stopped, automatic dispatch is disabled, all skill grants are revoked, live approvals expire and queued input loses readiness. Submitted actions retain uncertainty. Managed native identities become uncertain and require explicit ownership reconciliation. IDs, stored reports, waiting child sets/continuation reservations, delivery links, historical receipts and exact prepared document intents remain intact. No native operation runs during restore.
 
-Call createAgentHq with the returned stateRoot and an explicitly selected allowedRoots array. Runtime construction never imports source root permissions from the snapshot and always assigns a new epoch; stored execution and revision leases cannot authorize work in it. Native source workspace paths and plan bindings remain evidence and are not rewritten. Recover repository/native files separately. Inspect recovery.jsonl and copy selected companions into explicitly chosen plan locations only after comparing current files; restore never overwrites a source repository. Rebind task plan references and obtain fresh plan/execution authority where needed, reconcile pending document writes using their exact IDs/baselines, and make explicit current-revision lifecycle/native ownership decisions before enabling dispatch. Source paths outside the newly selected roots remain unavailable.
+Restore never upgrades storage. Both supported versions explicitly select restore fence version 1; a registered version without a compatible fence is refused before output is reserved. A version 1 restore remains version 1 and requires upgradeHqStorage before startup. Call createAgentHq with the returned stateRoot and an explicitly selected allowedRoots array. Runtime construction never imports source root permissions from the snapshot and always assigns a new epoch; stored execution and revision leases cannot authorize work in it. Native source workspace paths and plan bindings remain evidence and are not rewritten. Recover repository/native files separately. Inspect recovery.jsonl and copy selected companions into explicitly chosen plan locations only after comparing current files; restore never overwrites a source repository. Rebind task plan references and obtain fresh plan/execution authority where needed, reconcile pending document writes using their exact IDs/baselines, and make explicit current-revision lifecycle/native ownership decisions before enabling dispatch. Source paths outside the newly selected roots remain unavailable.
 
-These exports use SNAPSHOT_INVALID for incomplete, corrupt, unsafe or occupied snapshot/recovery selections and SNAPSHOT_FAILED for operational copy, backup, lock-release, worker or cleanup failures. Capture additionally exposes ACTION_CONFLICT for a busy checkpoint. Operational messages retain private diagnostic causes; no snapshot exception is exposed through public RPC.
+These exports use SNAPSHOT_INVALID for incomplete, corrupt, unsafe or occupied snapshot/recovery selections and SNAPSHOT_FAILED for operational copy, backup, lock-release, worker or cleanup failures. Capture additionally exposes ACTION_CONFLICT for a busy checkpoint. Inspection/restore expose STORAGE_VERSION_UNSUPPORTED for an unsupported lineage or missing compatible restore fence. Operational messages retain private diagnostic causes; no snapshot exception is exposed through public RPC.
 
 Snapshots are plaintext local state. The host owns encryption/key recovery, scheduling, uploads, retention and last-success status. A disk failure can lose every change after the last successful off-machine backup. A local snapshot alone provides no remote durability. See the [recovery workflow](../docs/recovery.md).
 
@@ -317,11 +354,17 @@ Items expose only normalized presentation fields. User/agent text, commands and
 
 ## Subscription observations
 
+The additive usage metadata is optional for compatibility with older providers and clients. Built-in adapters populate unknown metadata with null. Windows expose period (five-hour, seven-day or other), nativeKind, group and scope. Scope contains a nullable model with id/displayName and a nullable surface. Codex derives period from the actual duration; Claude normalizes recognized session and weekly groups to 300 and 10080 minutes. Primary/secondary remains the native position, not the period's identity. Existing bucket and window IDs remain stable.
+
+credits contains independent bucket observations with hasCredits, isUnlimited and an exact nullable balance string. Its null value means unknown, never zero; do not add balances across buckets or assume a currency. resetCredits contains a nonnegative safe availableCount, independent of the provider's potentially capped reset detail list. Native account IDs and reset detail rows are not exposed. Credit/reset metadata can be available even when quota windows are unavailable; it grants no permission and provides no reset-redemption or purchase operation.
+
+Codex prefers a valid nonempty rateLimitsByLimitId map and falls back to rateLimits when the map is absent, null or empty, without merging both views. A legacy bucket without a native limitId uses legacy as its bucket ID. Missing or malformed optional credit/reset metadata becomes unknown while valid windows remain visible. Invalid quota-map content does not bypass boundary validation through the fallback.
+
 Usage retains actual bucket/window identities, optional native labels, reported used percentage, remaining percentage, window duration and reset time. Percentages are never estimated from token counts or summed across sessions. Reported usage above 100 is preserved; remaining percentage floors at zero. `ordinaryUsageAllowed` is nullable when the native response does not report permission.
 
-`available` means a usable observation exists. `exhausted` requires Codex's native permission/reached signal or a fully used Claude meter that the native response marks active. Neither label authorizes a model operation. `unavailable` covers missing windows or an observation that could not be obtained. Failed refreshes preserve a measured snapshot as `stale`, with its original `observedAt`. Observations older than 60 seconds or past a reported reset are stale. Codex account/rate-limit notifications trigger a coalesced refresh. Claude auth notifications discard account measurements and invalidate responses started for that account; rate-limit events mark the observation stale until the current or next structured refresh succeeds.
+`available` means a usable observation exists. `exhausted` requires Codex's native permission/reached signal or a fully used Claude meter that the native response marks active. Neither label authorizes a model operation. `unavailable` covers missing windows or an observation that could not be obtained. Failed refreshes preserve a measured snapshot as `stale`, with its original `observedAt`. The complete prior observation, including credit/reset metadata and scopes, shares this freshness; an account change clears every field and invalidates responses started for the prior account. Observations older than 60 seconds or past a reported reset are stale. Codex account/rate-limit notifications trigger a coalesced refresh. Claude auth notifications discard account measurements and invalidate responses started for that account; rate-limit events mark the observation stale until the current or next structured refresh succeeds.
 
-Claude uses the experimental `get_usage` control with `skip_behaviors: true`, and validates the native `rate_limits.limits` rows rather than inferring quotas from session costs or reading credentials. The [published provider control types](https://app.unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.301/files/sdk.d.ts) describe this protocol; HQ invokes the installed CLI directly. Independent model/surface windows stay separate. Null percentages are omitted; zero is retained when reported. Unsupported shapes are unavailable. Claude does not report a duration or ordinary-usage permission in this contract, so those fields remain null. No private OAuth endpoint, credential scrape or status-line execution is used.
+Claude uses the experimental `get_usage` control with `skip_behaviors: true`, and validates the native `rate_limits.limits` rows rather than inferring quotas from session costs or reading credentials. The [published provider control types](https://app.unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.301/files/sdk.d.ts) describe this protocol; HQ invokes the installed CLI directly. Independent model/surface windows stay separate. Null percentages are omitted; zero is retained when reported. Unsupported shapes are unavailable. Claude does not report ordinary-usage permission, so it remains null. Recognized session and weekly groups have normalized five-hour and seven-day periods; unknown groups retain their native identity with period other and a null duration. No private OAuth endpoint, credential scrape or status-line execution is used.
 
 Every usage read requests current native observations; the last successful snapshot is retained only to explain freshness after a failure. There is no TTL cache that suppresses a native refresh. Multiple simultaneous reads share one pending refresh.
 
@@ -337,7 +380,7 @@ Output is one JSON line with `schemaVersion: 1`. Read output includes the comman
 
 `computePlanRevision({ body, metadata, milestones })` is the pure Node API for execution identity. `metadata` contains `scope`, `repositories`, `errorReservations` and JSON-safe `extensions`. Reservation entries contain `repository`, `namespace`, inclusive `start`/`end`, `registryPath` and `purpose`; this API hashes them and does not allocate codes. Repository and reservation order is canonicalized; object keys use strict deterministic JSON. The exact parsed body, including its line endings, is contractual.
 
-Send `{ kind: 'plan', command }` through the existing local request API. Every command selects `target: { directory }`, an absolute directory inside an allowed workspace. The default profile uses jg-plans observations: absent HQ fields default to local scope and empty repository/reservation lists; unknown fields, including plan `id`, remain in `extensions`. Only `created_at`, `updated_at`, `revision` and `status` are administrative. Malformed, non-mapping or non-JSON metadata fails closed. No preferred-document conformance gate is imposed.
+Send `{ kind: 'plan', command }` through the existing local request API. Every command selects `target: { directory }`, an absolute directory inside an allowed workspace. The default profile uses jg-plans observations: absent HQ fields default to local scope and empty repository/reservation lists; unknown fields, including plan `id`, remain in `extensions`. Only `created_at`, `updated_at`, `revision` and `status` are administrative. Malformed, non-mapping or non-JSON metadata fails closed. Plans without `protocol: "0.2"` get no preferred-document conformance gate. A plan that declares protocol 0.2 must pass the jg-plans check at each stage that grants authority: plan approval needs plan.md to conform on its own, while finalization, sequence approval, authorization and execution checks need plan.md and milestones.md to conform together. A nonconforming plan stays readable, so `status`, inspection and revision workflows continue. `approve`, `finalize` and `authorize` reject it with `JG_AGENT_HQ_PLAN_INVALID`, and `check-execution` and admission stay closed.
 
 A trusted private host may supply `parsePlanContract({ directory, content })`. It must return exactly the body observed by jg-plans and valid HQ metadata. That host owns its alternative metadata profile and must put its contractual extension fields in `extensions`. It cannot exclude body prose. The private server resolves operator identity itself and never forwards browser-supplied roots, contract exclusions or metadata.
 
@@ -363,7 +406,7 @@ Milestones are optional. Finalizing a plan with no milestone file returns `conte
 
 Skills bindings are optional for generic HQ plans. When present, their syntax must be valid and their plan ID, revision and structural fingerprint must match before finalization or execution. A valid but stale binding remains visible in status: plan approval and explicit revision invocations remain available so jg-plan can retain the old sequence until jg-breakdown refreshes its coverage. Malformed bindings fail as invalid artifacts. A stale binding never supplies sequence approval or completion, even when semantic execution digests are unchanged.
 
-A first-use sequence has one `**Milestone ID:** <uuid>` immediately below each `**Status:**` line. Blank lines may separate the heading from its status; no intervening requirement prose is allowed. The initial finalizer rejects duplicate, malformed or misplaced IDs and inconsistent framing. It preserves existing Overview text and returns the complete canonical file for presentation before approval. A changed finalized contract goes through checkpoint reconciliation. A raw or changed sequence cannot inherit finalized status or sequence authority. A done marker remains visible but blocks execution without completion evidence.
+A first-use sequence has one `**Milestone ID:** <uuid>` immediately below each `**Status:**` line. Blank lines may separate the heading from its status; no intervening requirement prose is allowed. In a protocol 0.2 sequence, a milestone's `**Acceptance criteria:**` coverage line follows its ID line and is milestone contract prose. The initial finalizer rejects duplicate, malformed or misplaced IDs and inconsistent framing. It preserves existing Overview text and returns the complete canonical file for presentation before approval. A changed finalized contract goes through checkpoint reconciliation. A raw or changed sequence cannot inherit finalized status or sequence authority. A done marker remains visible but blocks execution without completion evidence.
 
 The milestone contract includes its stable UUID, title without its ordinal, all requirement prose, shared sequence requirements and the approval statement. Status and identity marker lines are excluded from the prose; only the derived Overview table is excluded from shared text. Prose next to that table remains contractual. Sequence order is significant. Renumbering preserves execution identity; changed requirements, dependencies, scope, reservations or order require applicable approval. Full-file hashes preserve exact UTF-8 bytes and are distinct from semantic execution revisions. Administrative frontmatter excluded by the trusted contract parser, session labels, status advancement and coordination receipts do not change execution digests.
 

package/dist/cli/cli.js

@@ -4,12 +4,13 @@ import { parseArgs } from 'node:util';
 import { setTimeout as wait } from 'node:timers/promises';
 import { Exception, hasErrorCode, isException } from 'jg-exception';
 import { HqRequestSchema } from '../contracts/index.js';
-import { toPublicError } from '../errors/index.js';
+import { upgradeHqStorage } from '../storage/upgrade/index.js';
 import { requestAgentHq } from '../ipc/index.js';
 import { createAgentHq } from '../runtime/index.js';
 import { readRuntimeOwner } from '../runtime/state/index.js';
 import { serveAgentBridge } from '../agent-tools/mcp/index.js';
 import { AGENT_BRIDGE_FILE_ENV } from '../agent-tools/index.js';
+import { toCliError } from './utilities.js';
 /** Runs the installed CLI without creating provider work merely to read history. */
 const main = async () => {
     if (process.argv[2] === 'agent-bridge') {
@@ -26,6 +27,7 @@ const main = async () => {
         allowPositionals: true,
         options: {
             'state-root': { type: 'string' },
+            'backup-directory': { type: 'string' },
             'coordination-root': { type: 'string' },
             directory: { type: 'string' },
             'workspace-root': { type: 'string', multiple: true },
@@ -50,7 +52,7 @@ const main = async () => {
     });
     const [kind] = positionals;
     if (values.help || !kind || kind === 'help') {
-        process.stdout.write('jg-agent-hq serve|status|stop|capabilities|threads|thread|turns|items|sessions|session-evidence|usage|account|models|configuration|mcp-servers|mcp-tools|mcp-resources|managed-thread-name|suggest-thread-name|skills|skill-preview|plan-status|plan-milestones|request --state-root <path> [--provider <provider-id>] [--workspace-root <path>] [--native-id <id>] [--limit <1..128>] [--cursor <cursor>] [--name <name>] [--topic <topic>] [--thread-id <id>] [--server-name <name>] [--skill-id <id>] [--arguments <text>] [--directory <path>]\nserve accepts repeated --codex-extra-skill-root and --claude-additional-directory.\nsession-evidence accepts --native-item-id and repeated --evidence-kind.\nrequest reads one validated HQ command as JSON from stdin.\n');
+        process.stdout.write('jg-agent-hq serve|upgrade-storage|status|stop|capabilities|threads|thread|turns|items|sessions|session-evidence|usage|account|models|configuration|mcp-servers|mcp-tools|mcp-resources|managed-thread-name|suggest-thread-name|skills|skill-preview|plan-status|plan-milestones|request --state-root <path> [--provider <provider-id>] [--workspace-root <path>] [--native-id <id>] [--limit <1..128>] [--cursor <cursor>] [--name <name>] [--topic <topic>] [--thread-id <id>] [--server-name <name>] [--skill-id <id>] [--arguments <text>] [--directory <path>]\nserve accepts repeated --codex-extra-skill-root and --claude-additional-directory.\nsession-evidence accepts --native-item-id and repeated --evidence-kind.\nrequest reads one validated HQ command as JSON from stdin.\nupgrade-storage --state-root <existing-path> --backup-directory <absent-path> --workspace-root <path> [--workspace-root <path> ...] [--coordination-root <path>]\nStop HQ/native children and independent database/plan writers first. Existing owners are never reclaimed.\nLegacy serve errors require upgrade-storage; startup never migrates. Keep the verified backup. Uncertain outcomes require explicit reconciliation; retry inspects the durable stamp.\n');
         return;
     }
     if (positionals.length !== 1 || !values['state-root'])
@@ -60,6 +62,36 @@ const main = async () => {
         });
     const stateRoot = resolve(values['state-root']);
     const roots = (values['workspace-root'] ?? []).map((root) => resolve(root));
+    if (kind === 'upgrade-storage') {
+        const allowed = new Set([
+            'state-root',
+            'backup-directory',
+            'workspace-root',
+            'coordination-root',
+        ]);
+        if (!values['backup-directory'] ||
+            roots.length === 0 ||
+            Object.keys(values).some((key) => !allowed.has(key)))
+            throw new Exception('The HQ request is invalid', {
+                code: 'JG_AGENT_HQ_REQUEST_INVALID',
+                data: { kind: 'invalid-request' },
+            });
+        const result = await upgradeHqStorage({
+            stateRoot,
+            backupDirectory: resolve(values['backup-directory']),
+            allowedRoots: roots,
+            coordinationRoot: values['coordination-root']
+                ? resolve(values['coordination-root'])
+                : undefined,
+        });
+        process.stdout.write(`${JSON.stringify({ schemaVersion: 1, kind: 'upgrade-storage', result })}\n`);
+        return;
+    }
+    if (values['backup-directory'] !== undefined)
+        throw new Exception('The HQ request is invalid', {
+            code: 'JG_AGENT_HQ_REQUEST_INVALID',
+            data: { kind: 'invalid-request' },
+        });
     if (kind === 'request') {
         if (Object.keys(values).some((key) => key !== 'state-root'))
             throw new Exception('The HQ request is invalid', {
@@ -281,6 +313,6 @@ try {
     await main();
 }
 catch (error) {
-    process.stderr.write(`${JSON.stringify({ schemaVersion: 1, success: false, error: toPublicError(error) })}\n`);
+    process.stderr.write(`${JSON.stringify({ schemaVersion: 1, success: false, error: toCliError(error) })}\n`);
     process.exitCode = 1;
 }

package/dist/cli/utilities.d.ts

@@ -0,0 +1,3 @@
+import { toPublicError } from '../errors/index.js';
+/** Presents static storage instructions without exposing diagnostic paths, suffixes or causes. */
+export declare const toCliError: (error: unknown) => ReturnType<typeof toPublicError>;

package/dist/cli/utilities.js

@@ -0,0 +1,30 @@
+import { isException } from 'jg-exception';
+import { toPublicError } from '../errors/index.js';
+// only these operator-facing storage diagnoses bypass the generic IPC presentation
+const STORAGE_MESSAGES = {
+    JG_AGENT_HQ_STORAGE_UPGRADE_REQUIRED: {
+        kind: 'state-conflict',
+        message: 'The HQ storage requires an explicit upgrade',
+    },
+    JG_AGENT_HQ_STORAGE_VERSION_UNSUPPORTED: {
+        kind: 'state-conflict',
+        message: 'The HQ storage version is unsupported',
+    },
+    JG_AGENT_HQ_STORAGE_UPGRADE_FAILED: {
+        kind: 'operation-failed',
+        message: 'The HQ storage upgrade failed',
+    },
+    JG_AGENT_HQ_STORAGE_UPGRADE_UNCERTAIN: {
+        kind: 'operation-failed',
+        message: 'The HQ storage upgrade requires reconciliation',
+    },
+};
+/** Presents static storage instructions without exposing diagnostic paths, suffixes or causes. */
+export const toCliError = (error) => {
+    if (isException(error)) {
+        for (const [code, presentation] of Object.entries(STORAGE_MESSAGES))
+            if (error.code === code)
+                return presentation;
+    }
+    return toPublicError(error);
+};

package/dist/contracts/index.d.ts

@@ -3,10 +3,10 @@ export type { IAccountControlCommand, ILoginObservation, INativeControlResult, }
 export { ExtensionControlCommandSchema } from './extensions/index.js';
 export type { IExtensionControlCommand } from './extensions/index.js';
 export { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, PUBLIC_ERROR_CODES, PUBLIC_ERROR_MESSAGES, } from './constants.js';
-export { HqRequestSchema, ThreadSummarySchema, TurnSummarySchema, HistoryItemSchema, LiveItemsSchema, UsageWindowSchema, UsageSnapshotSchema, RuntimeStatusSchema, HqResponseSchema, ErrorKindSchema, IpcRequestSchema, IpcResponseSchema, } from './types.js';
+export { HqRequestSchema, ThreadSummarySchema, TurnSummarySchema, HistoryItemSchema, LiveItemsSchema, UsageWindowSchema, UsageSnapshotSchema, UsageCreditsSchema, UsageResetCreditsSchema, UsageWindowScopeSchema, RuntimeStatusSchema, HqResponseSchema, ErrorKindSchema, IpcRequestSchema, IpcResponseSchema, } from './types.js';
 export { ProviderIdSchema, ProviderCapabilitySchema, ProviderCapabilitySetSchema, ProviderCapabilitiesSchema, ProviderStatusSchema, MAX_PROVIDERS, } from './providers/index.js';
 export type { IProviderId, IProviderCapability, IProviderCapabilitySet, IProviderCapabilities, IProviderStatus, } from './providers/index.js';
-export type { IHqRequest, IHqRequestInput, IThreadSummary, ITurnSummary, IHistoryItem, IUsageSnapshot, IRuntimeStatus, IHqResponse, IErrorKind, IIpcResponse, } from './types.js';
+export type { IHqRequest, IHqRequestInput, IThreadSummary, ITurnSummary, IHistoryItem, IUsageSnapshot, IUsageCredits, IUsageResetCredits, IUsageWindowScope, IRuntimeStatus, IHqResponse, IErrorKind, IIpcResponse, } from './types.js';
 export { NativeLineageSchema } from './identities/index.js';
 export type { INativeLineage } from './identities/index.js';
 export { ProviderModelSchema, ProviderModelsRequestSchema, ProviderModelPageSchema, } from './models/index.js';

package/dist/contracts/index.js

@@ -4,7 +4,7 @@ export { ExtensionControlCommandSchema } from './extensions/index.js';
 // constants
 export { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, PUBLIC_ERROR_CODES, PUBLIC_ERROR_MESSAGES, } from './constants.js';
 // wire contracts
-export { HqRequestSchema, ThreadSummarySchema, TurnSummarySchema, HistoryItemSchema, LiveItemsSchema, UsageWindowSchema, UsageSnapshotSchema, RuntimeStatusSchema, HqResponseSchema, ErrorKindSchema, IpcRequestSchema, IpcResponseSchema, } from './types.js';
+export { HqRequestSchema, ThreadSummarySchema, TurnSummarySchema, HistoryItemSchema, LiveItemsSchema, UsageWindowSchema, UsageSnapshotSchema, UsageCreditsSchema, UsageResetCreditsSchema, UsageWindowScopeSchema, RuntimeStatusSchema, HqResponseSchema, ErrorKindSchema, IpcRequestSchema, IpcResponseSchema, } from './types.js';
 // provider identity and capability discovery
 export { ProviderIdSchema, ProviderCapabilitySchema, ProviderCapabilitySetSchema, ProviderCapabilitiesSchema, ProviderStatusSchema, MAX_PROVIDERS, } from './providers/index.js';
 // native identities

package/dist/contracts/types.d.ts

@@ -1684,6 +1684,25 @@ export declare const LiveItemsSchema: z.ZodObject<{
     }, z.core.$strip>>;
     hasGap: z.ZodBoolean;
 }, z.core.$strip>;
+export declare const UsageCreditsSchema: z.ZodObject<{
+    bucket: z.ZodString;
+    hasCredits: z.ZodBoolean;
+    isUnlimited: z.ZodBoolean;
+    balance: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type IUsageCredits = z.infer<typeof UsageCreditsSchema>;
+export declare const UsageResetCreditsSchema: z.ZodObject<{
+    availableCount: z.ZodNumber;
+}, z.core.$strip>;
+export type IUsageResetCredits = z.infer<typeof UsageResetCreditsSchema>;
+export declare const UsageWindowScopeSchema: 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>;
+export type IUsageWindowScope = z.infer<typeof UsageWindowScopeSchema>;
 export declare const UsageWindowSchema: z.ZodObject<{
     id: z.ZodString;
     bucket: z.ZodString;
@@ -1696,6 +1715,20 @@ export declare const UsageWindowSchema: z.ZodObject<{
     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>;
 export declare const UsageSnapshotSchema: z.ZodObject<{
     provider: z.ZodString;
@@ -1720,7 +1753,30 @@ export declare const UsageSnapshotSchema: z.ZodObject<{
         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>;
 export type IUsageSnapshot = z.infer<typeof UsageSnapshotSchema>;
 export declare const RuntimeStatusSchema: z.ZodObject<{
@@ -6028,7 +6084,30 @@ export declare const HqResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             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">;
@@ -12603,7 +12682,30 @@ export declare const IpcResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 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/contracts/types.js

@@ -143,6 +143,24 @@ export const LiveItemsSchema = z.object({
     data: z.array(HistoryItemSchema.extend({ state: z.enum(['active', 'awaiting-flush']) })).max(128),
     hasGap: z.boolean(),
 });
+// exact native credit observations; balances have no assumed currency or arithmetic semantics
+export const UsageCreditsSchema = z.object({
+    bucket: z.string().max(256),
+    hasCredits: z.boolean(),
+    isUnlimited: z.boolean(),
+    balance: z.string().max(256).nullable(),
+});
+// availability is independent of the provider's potentially capped reset-credit detail list
+export const UsageResetCreditsSchema = z.object({
+    availableCount: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+});
+// native model/surface scope identifies independent account meters
+export const UsageWindowScopeSchema = z.object({
+    model: z
+        .object({ id: z.string().max(256).nullable(), displayName: z.string().max(256) })
+        .nullable(),
+    surface: z.string().max(256).nullable(),
+});
 export const UsageWindowSchema = z.object({
     id: z.string(),
     bucket: z.string(),
@@ -152,6 +170,10 @@ export const UsageWindowSchema = z.object({
     remainingPercent: z.number().min(0).max(100),
     durationMinutes: z.number().int().positive().nullable(),
     resetsAt: z.number().int().nullable(),
+    period: z.enum(['five-hour', 'seven-day', 'other']).optional(),
+    nativeKind: z.string().max(256).nullable().optional(),
+    group: z.string().max(256).nullable().optional(),
+    scope: UsageWindowScopeSchema.nullable().optional(),
 });
 export const UsageSnapshotSchema = z.object({
     provider: ProviderIdSchema,
@@ -160,6 +182,8 @@ export const UsageSnapshotSchema = z.object({
     observedAt: z.number().int().nullable(),
     ordinaryUsageAllowed: z.boolean().nullable(),
     windows: z.array(UsageWindowSchema).max(MAX_PAGE_SIZE),
+    credits: z.array(UsageCreditsSchema).max(MAX_PAGE_SIZE).nullable().optional(),
+    resetCredits: UsageResetCreditsSchema.nullable().optional(),
 });
 export const RuntimeStatusSchema = z.object({
     runtimeEpoch: z.uuid(),

package/dist/index.d.ts

@@ -8,6 +8,8 @@ export type { IProviderId, IProviderCapability, IProviderCapabilitySet, IProvide
 export type { IProviderModel, IProviderModelPage, IProviderModelsRequest, } from './contracts/models/index.js';
 export type { ITurnSettings, ISessionSettings, IConfigurationRequest, IConfigurationChoice, ISessionConfiguration, } from './contracts/configuration/index.js';
 export type { INativeLineage } from './contracts/identities/index.js';
+export { upgradeHqStorage } from './storage/upgrade/index.js';
+export type { IHqStorageUpgradeOptions, IHqStorageUpgradeResult } from './storage/upgrade/index.js';
 export type { IStorageDescriptor, IStorageMaintenanceOperation } from './storage/index.js';
 export { createHqSnapshot, inspectHqSnapshot, restoreHqSnapshot } from './snapshots/index.js';
 export type { IHqSnapshotInspection, IHqRestoreOptions, IHqRestoreResult, } from './snapshots/index.js';

package/dist/index.js

@@ -3,6 +3,8 @@ export { RUNTIME_DIRECTORY, HQ_LOCK_FILE, getOwnerLiveness, acquireHqLock, withH
 // native runtime and local client
 export { createAgentHq } from './runtime/index.js';
 export { requestAgentHq } from './ipc/index.js';
+// trusted offline storage upgrades
+export { upgradeHqStorage } from './storage/upgrade/index.js';
 // trusted host snapshot and offline recovery
 export { createHqSnapshot, inspectHqSnapshot, restoreHqSnapshot } from './snapshots/index.js';
 // pure execution revision contracts

package/dist/plans/authority.d.ts

@@ -10,9 +10,11 @@ export declare const describePlan: (artifacts: IPlanArtifacts, pendingActionId?:
 export declare const canExecutePlanUnit: (artifacts: IPlanArtifacts, milestoneId: string | null) => boolean;
 /**
  * Applies one explicit operator decision without native dispatch or filesystem mutation.
+ * A protocol 0.2 plan must pass the jg-plans check for the decision's stage.
  * @returns Updated current authority records.
  * @throws
  * - JG_AGENT_HQ_ACTION_CONFLICT: The HQ action conflicts with its recorded state
+ * - JG_AGENT_HQ_PLAN_INVALID: The HQ plan is invalid
  */
 export declare const updatePlanAuthority: (artifacts: IPlanArtifacts, command: Extract<IPlanCommand, {
     kind: "approve" | "revoke" | "authorize";

package/dist/plans/authority.js

@@ -1,6 +1,7 @@
 import { Exception } from 'jg-exception';
 import { isSamePlanRevision } from './utilities.js';
 import { createCompletionLookup } from './reconciliation.js';
+import { invalid } from './documents.js';
 const conflict = () => {
     throw new Exception('The HQ action conflicts with its recorded state', {
         code: 'JG_AGENT_HQ_ACTION_CONFLICT',
@@ -110,6 +111,7 @@ export const canExecutePlanUnit = (artifacts, milestoneId) => {
     const status = describePlan(artifacts);
     const execution = artifacts.coordination.execution;
     if (!execution ||
+        !artifacts.conformance.sequence ||
         !status.isPlanApproved ||
         !status.isFinalized ||
         ['blocked', 'completed', 'revising'].includes(status.state))
@@ -128,13 +130,17 @@ const revokeExecution = (coordination, action) => {
 };
 /**
  * Applies one explicit operator decision without native dispatch or filesystem mutation.
+ * A protocol 0.2 plan must pass the jg-plans check for the decision's stage.
  * @returns Updated current authority records.
  * @throws
  * - JG_AGENT_HQ_ACTION_CONFLICT: The HQ action conflicts with its recorded state
+ * - JG_AGENT_HQ_PLAN_INVALID: The HQ plan is invalid
  */
 export const updatePlanAuthority = (artifacts, command, runtimeEpoch) => {
     const coordination = structuredClone(artifacts.coordination);
     if (command.kind === 'approve') {
+        if (!artifacts.conformance[command.scope])
+            invalid();
         const status = describePlan(artifacts);
         if (command.scope === 'sequence' &&
             (artifacts.milestones === null || !status.isFinalized || !status.isPlanApproved))
@@ -166,6 +172,8 @@ export const updatePlanAuthority = (artifacts, command, runtimeEpoch) => {
         revokeExecution(coordination, command.action);
     }
     else {
+        if (!artifacts.conformance.sequence)
+            invalid();
         const status = describePlan(artifacts);
         if (coordination.revision &&
             coordination.revision.phase !== 'awaiting-approval' &&

package/dist/plans/documents.d.ts

@@ -1,5 +1,22 @@
 import { z } from 'zod';
 import { type IPlanMetadata, type IPlanStatus } from '../contracts/index.js';
+import type { IPlanConformance } from './types.js';
+/**
+ * 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 declare const invalid: (cause?: unknown) => never;
+/**
+ * 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 declare const observePlanConformance: (plan: string, milestones: string | null) => IPlanConformance;
 /**
  * Reads the persisted identity independently of an optional consumer metadata projection.
  * @throws