jg-agent-hq 2.0.0 → 3.0.0

package/errors/README.md

@@ -26,33 +26,39 @@ Recovery never automatically deletes an inactive, unreadable, incomplete or unve
 
 These contracts use the named codes below. An Exception's `data.kind` classifies its safe wire mapping. Native codes, when present in diagnostic metadata, belong to the native protocol and are not HQ error codes. Claude control error responses carry `nativeRejection: true` internally because that protocol supplies no numeric error code. Internal diagnostic causes are never copied into IPC error responses.
 
-| Code                                   | Stable message                                                   |
-| -------------------------------------- | ---------------------------------------------------------------- |
-| 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_RUNTIME_ALREADY_OWNED      | The HQ runtime is already owned                                  |
-| JG_AGENT_HQ_RUNTIME_OWNER_UNVERIFIABLE | The HQ runtime owner is unverifiable                             |
-| JG_AGENT_HQ_REQUEST_INVALID            | The HQ request is invalid                                        |
-| JG_AGENT_HQ_TARGET_FORBIDDEN           | The HQ target is outside the allowed workspaces                  |
-| JG_AGENT_HQ_CURSOR_INVALID             | The HQ cursor does not match this request                        |
-| JG_AGENT_HQ_CODEX_FAILED               | The Codex integration failed                                     |
-| JG_AGENT_HQ_CLAUDE_FAILED              | The Claude integration failed                                    |
-| JG_AGENT_HQ_CLAUDE_HISTORY_UNAVAILABLE | The Claude history is unavailable                                |
-| JG_AGENT_HQ_TRANSPORT_FAILED           | The HQ transport failed                                          |
-| JG_AGENT_HQ_STORE_FAILED               | The HQ store failed                                              |
-| JG_AGENT_HQ_STORAGE_INVALID            | The HQ storage is invalid                                        |
-| JG_AGENT_HQ_SNAPSHOT_INVALID           | The HQ snapshot is invalid                                       |
-| JG_AGENT_HQ_SNAPSHOT_FAILED            | The HQ snapshot operation failed                                 |
-| JG_AGENT_HQ_PROVIDER_FAILED            | The HQ provider integration failed                               |
-| JG_AGENT_HQ_CAPABILITY_UNAVAILABLE     | The HQ capability is unavailable                                 |
-| JG_AGENT_HQ_RUNTIME_NOT_RUNNING        | The HQ runtime is not running                                    |
-| JG_AGENT_HQ_ACTION_CONFLICT            | The HQ action conflicts with its recorded state                  |
-| JG_AGENT_HQ_COLLABORATION_FORBIDDEN    | The HQ collaboration operation is not authorized                 |
-| JG_AGENT_HQ_COLLABORATION_CONFLICT     | The HQ collaboration operation conflicts with its recorded state |
-| JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE     | The HQ action key is unavailable                                 |
-| JG_AGENT_HQ_SKILL_UNAVAILABLE          | The HQ skill is unavailable                                      |
-| JG_AGENT_HQ_PLAN_INVALID               | The HQ plan is invalid                                           |
-| JG_AGENT_HQ_PLAN_FAILED                | The HQ plan operation failed                                     |
+| Code                                    | Stable message                                                   |
+| --------------------------------------- | ---------------------------------------------------------------- |
+| 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_RUNTIME_ALREADY_OWNED       | The HQ runtime is already owned                                  |
+| JG_AGENT_HQ_RUNTIME_OWNER_UNVERIFIABLE  | The HQ runtime owner is unverifiable                             |
+| JG_AGENT_HQ_REQUEST_INVALID             | The HQ request is invalid                                        |
+| JG_AGENT_HQ_TARGET_FORBIDDEN            | The HQ target is outside the allowed workspaces                  |
+| JG_AGENT_HQ_CURSOR_INVALID              | The HQ cursor does not match this request                        |
+| JG_AGENT_HQ_CODEX_FAILED                | The Codex integration failed                                     |
+| JG_AGENT_HQ_CLAUDE_FAILED               | The Claude integration failed                                    |
+| JG_AGENT_HQ_CLAUDE_HISTORY_UNAVAILABLE  | The Claude history is unavailable                                |
+| JG_AGENT_HQ_TRANSPORT_FAILED            | The HQ transport failed                                          |
+| JG_AGENT_HQ_STORE_FAILED                | The HQ store failed                                              |
+| JG_AGENT_HQ_STORAGE_INVALID             | The HQ storage is invalid                                        |
+| 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_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                                 |
+| JG_AGENT_HQ_PROVIDER_FAILED             | The HQ provider integration failed                               |
+| JG_AGENT_HQ_CAPABILITY_UNAVAILABLE      | The HQ capability is unavailable                                 |
+| JG_AGENT_HQ_RUNTIME_NOT_RUNNING         | The HQ runtime is not running                                    |
+| JG_AGENT_HQ_ACTION_CONFLICT             | The HQ action conflicts with its recorded state                  |
+| JG_AGENT_HQ_COLLABORATION_FORBIDDEN     | The HQ collaboration operation is not authorized                 |
+| JG_AGENT_HQ_COLLABORATION_CONFLICT      | The HQ collaboration operation conflicts with its recorded state |
+| JG_AGENT_HQ_ACTION_KEY_UNAVAILABLE      | The HQ action key is unavailable                                 |
+| JG_AGENT_HQ_SKILL_UNAVAILABLE           | The HQ skill is unavailable                                      |
+| JG_AGENT_HQ_PLAN_INVALID                | The HQ plan is invalid                                           |
+| JG_AGENT_HQ_PLAN_FAILED                 | The HQ plan operation failed                                     |
+
+Storage version/upgrade-required errors use state-conflict. Upgrade failed/uncertain errors use operation-failed. An uncertain upgrade never retries or reverses automatically; trusted Node diagnostics retain the phase and selected verified backup when available. CLI presentation exposes only static canonical messages.
 
 State safety rejects non-private ownership, symlinks and non-regular files. ACTION_KEY_UNAVAILABLE also rejects a valid-length key whose fingerprint differs from the database stamp, before opening a writer. Runtime ownership is never reclaimed automatically. Transport failure includes malformed, oversized or incomplete frames and bounded-request/lifecycle failures. Native history and subscription failures remain unavailable, never successful empty results. Claude control rejects missing or non-idle initialization, invalid native session identities and malformed lifecycle evidence. Failed delivery remains uncertain when no exact native rejection or acknowledgement establishes its outcome.
 
@@ -74,7 +80,7 @@ Input-file admission reuses REQUEST_INVALID for invalid media, malformed UTF-8 a
 
 Native form replies reuse REQUEST_INVALID for content outside the exact requested schema or response kind. Stale, expired, cross-thread or already answered request identities use ACTION_CONFLICT. Native writes without matching consumption evidence remain submitted or uncertain; expiry never proves a response was rejected. Unsupported native request variants are denied on their own native channel without granting permission.
 
-Plan validation rejects unsupported framing, duplicate or misplaced milestone IDs, invalid frontmatter boundaries, non-regular artifacts and oversized inputs. Plan operation failures retain safe operation diagnostics inside the trusted host. Document-lock contention uses ACTION_CONFLICT with reason document-locked. Document lock failures use PLAN_FAILED with the observed phase and a truthful not-applied or uncertain outcome. An applied write whose lock release fails keeps its prepared journal payload. A failed ledger acknowledgement is reconciled from durable state; an unavailable observation uses STORE_FAILED and keeps admission closed. Stale revisions, presentation hashes, replay payload conflicts, revoked authority and unresolved writes use the existing action-state conflict contract. Unresolved correspondence, unverified done evidence, live scope changes, stale runtime authority and unproven quiescence also use the action-state conflict contract. Failed native cleanup retains the checkpoint and closes the editing gate. Neither validation nor write recovery can grant native permissions. Whole-plan selection conflicts with a real breakdown, duplicate live implementation ownership, completed contracts and revoked implementation follow-up authority use the same action-state conflict contract. A valid sequence approval request for a plan without a sequence also conflicts.
+Plan validation rejects unsupported framing, duplicate or misplaced milestone IDs, invalid frontmatter boundaries, non-regular artifacts and oversized inputs. Plan approval, finalization, sequence approval and authorization also reject a protocol 0.2 plan that fails the jg-plans check; `jg-plans check --directory <plan>` reports why. Reading such a plan is unaffected. Plan operation failures retain safe operation diagnostics inside the trusted host. Document-lock contention uses ACTION_CONFLICT with reason document-locked. Document lock failures use PLAN_FAILED with the observed phase and a truthful not-applied or uncertain outcome. An applied write whose lock release fails keeps its prepared journal payload. A failed ledger acknowledgement is reconciled from durable state; an unavailable observation uses STORE_FAILED and keeps admission closed. Stale revisions, presentation hashes, replay payload conflicts, revoked authority and unresolved writes use the existing action-state conflict contract. Unresolved correspondence, unverified done evidence, live scope changes, stale runtime authority and unproven quiescence also use the action-state conflict contract. Failed native cleanup retains the checkpoint and closes the editing gate. Neither validation nor write recovery can grant native permissions. Whole-plan selection conflicts with a real breakdown, duplicate live implementation ownership, completed contracts and revoked implementation follow-up authority use the same action-state conflict contract. A valid sequence approval request for a plan without a sequence also conflicts.
 
 Agent-tool admission reuses COLLABORATION_FORBIDDEN for an unknown/revoked bridge credential, stale native/runtime/turn binding or insufficient task membership. COLLABORATION_CONFLICT covers changed spawn identities and exhausted spawn capacity. Private credential parsing discards secret-bearing diagnostic causes. Credential setup/cleanup failures use TRANSPORT_FAILED. Native tool results and MCP failures contain only the existing safe public error classification and code. An admitted native spawn retains its durable failed/uncertain receipt; a tool timeout or lost client connection never proves native creation failed.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jg-agent-hq",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Native coding-agent session control, agent streams and durable collaboration for Node.js apps.",
   "type": "module",
   "license": "MIT",
@@ -51,7 +51,7 @@
     "jg-crypto": "0.3.0",
     "jg-exception": "^1.7.0",
     "jg-fs": "1.7.0",
-    "jg-plans": "0.2.0",
+    "jg-plans": "0.3.0",
     "jg-utilities": "1.7.0",
     "zod": "^4.3.6"
   },