jg-agent-hq 0.5.2 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.1.0
+
+- Rebuild the homepage around a native-session visual, local setup and three complete source-backed walkthroughs. Show cross-provider reviews and retained revision evidence with explicit host decisions.
+- Queue local metadata-lock acquisitions in order, preventing frequent status reads from starving a revision checkpoint. Preserve exact owner checks, wait deadlines and explicit recovery.
+- Coordinate journaled private writes with public document locks, explicit keep/write/remove intents and durable completion acknowledgement recovery. Prepare aggregate and milestone progress before native admission; preserve exact replay output and completion evidence.
+
+- Use jg-plans for document observations, guarded edit preparation and explicit milestone identity assignment. Preserve complete shared requirements and JSON-safe contract metadata; report skills binding freshness without blocking the revision approval flow; require current bindings for finalization and execution.
+- Keep exact body and requirement bytes in execution digests, with deterministic metadata serialization. Stop regenerating derived Overview tables.
+- Add three complete public-client source examples, packed-consumer contract qualification and fixture-backed native flows. Expose the exact pending correspondence proposal ID for explicit client confirmation.
+
+## 1.0.0
+
+- Use `jg-exception` with named string codes for runtime, lock, plan, provider, client and tooling failures. Preserve codes through SQLite-worker responses and publish browser-safe client codes alongside their safe messages. This changes the Node error contract; callers should handle the documented named codes.
+- Use the shared Astro UI 0.4.0, `jg-site` metadata helpers and `jg-playwright` browser checks. Remove `error-message-utils` from the runtime and website.
+- Redesign the public website around Claude Code and Codex collaboration, a copyable API example, the available runtime capabilities and section navigation for the documentation.
+
 ## 0.5.2
 
 - Resume inactive managed Codex sessions retained as loaded by native unsubscribe, preserving explicit handoff and active/uncertain ownership guards.

package/README.md

@@ -31,6 +31,8 @@ Short metadata operations use `withHqLock`. Long-lived runtime ownership must us
 
 See the [API reference](api/README.md) and [error contracts](errors/README.md).
 
+Intentional failures use `Exception` from `jg-exception`, with the named string codes in the error reference. Local clients use `PUBLIC_ERROR_CODES` and `PUBLIC_ERROR_MESSAGES` from `jg-agent-hq/contracts` for errors translated at the IPC boundary. Safe classifications remain separate from private diagnostic causes.
+
 ## Local controller
 
 Install Codex and sign in through its native CLI, then start `jg-agent-hq serve --state-root .runtime --workspace-root /path/to/workspace`. Run `jg-agent-hq status --state-root .runtime` in a client. `threads`, `thread`, `turns`, `items` and `usage` read native information; `stop` waits for confirmed runtime shutdown.
@@ -59,7 +61,7 @@ Use `jg-agent-hq request --state-root <directory>` with a closed HQ command on s
 
 `plan-status --directory <path>` and `plan-milestones --directory <path>` inspect a selected ordinary planning directory. No project registry is required. Mutations use the existing `request` JSON command with `kind: 'plan'`; see the [plan command reference](api/README.md#plan-coordination).
 
-Finalization assigns milestone UUIDs and returns the complete canonical sequence when a breakdown exists. A plan without a breakdown remains one unit: finalization returns null content, plan approval suffices, and whole-plan execution uses an empty milestone selection with a null milestone ID. No milestone file is created merely to make a small plan executable. Plan approval, sequence approval and scoped execution authorization are separate explicit operator actions. None sends native input or answers tool permissions. `coordination.json` holds current records beside the plan. SQLite retains write replay identities and a replaceable, paged milestone projection. Keep both when recovering interrupted writes. A pending write blocks further mutation until its original action is reconciled.
+HQ uses jg-plans to observe and prepare ordinary Markdown plans. The default profile retains unknown contractual metadata and all shared requirement sections while excluding only declared administrative fields. Status reports skills bindings as absent, current or stale. A stale binding keeps the plan readable and approvable during revision, but closes finalization and execution until jg-breakdown refreshes coverage; bindings never grant HQ approval. Finalization assigns milestone UUIDs and returns the complete canonical sequence when a breakdown exists. A plan without a breakdown remains one unit: finalization returns null content, plan approval suffices, and whole-plan execution uses an empty milestone selection with a null milestone ID. No milestone file is created merely to make a small plan executable. Plan approval, sequence approval and scoped execution authorization are separate explicit operator actions. None sends native input or answers tool permissions. `coordination.json` holds current records beside the plan. SQLite retains write replay identities and a replaceable, paged milestone projection. Keep both when recovering interrupted writes. Document locks release before the write journal is completed. Checked replacements are private (0600), and progress preserves revision while recording one prepared updated_at. A pending write blocks further mutation until its original action is reconciled.
 
 Coordinators can retain revision-bound compatibility reviews in that same file. Core operations preserve the records without assessing them or granting authority. The integrating coordinator owns review freshness and conflict gates.
 
@@ -73,6 +75,14 @@ Collect one completed reviewer message by its exact native turn/item reference.
 
 `handoff-show --id <uuid>` reads one handoff; `handoffs --workspace-root <path>` pages the inbox. The [handoff reference](api/README.md#cross-provider-handoffs) describes creation, preview, send and native findings collection through the same CLI's JSON request interface.
 
+## Source examples
+
+Follow the [three complete walkthroughs](https://jg-agent-hq.jesusgraterol.dev/examples/), with copyable source, visual results and explicit host decisions.
+
+`examples/control-session.ts` creates a native session and reads its actual delivery, output, permission and usage observations. `examples/review-handoff.ts` presents exact cross-provider review/feedback previews and delivers selected findings. `examples/revise-plan.ts` runs the planning skills through the revision lease, retains verified work through explicit correspondence, and obtains fresh approvals and execution scope.
+
+These complete TypeScript examples use the public client and contracts. Start the local controller, sign in to the native CLIs, and install the required skills and supported project-local jg-plans CLI first. The host supplies actual user decisions and keeps native permission handling separate. Retain request identities before submission; after an interrupted client call, inspect those receipts instead of rerunning a whole example. Examples are development sources, not package exports or automatic website actions.
+
 ## Project blueprint
 
 - `src/index.ts`: the explicit public package boundary.

package/api/README.md

@@ -2,9 +2,11 @@
 
 Import the named exports from `jg-agent-hq`. Internal module paths are private.
 
+Intentional Node API failures use `Exception` from `jg-exception`. The [error reference](../errors/README.md) defines their named string codes and stable messages. `PUBLIC_ERROR_CODES` and `PUBLIC_ERROR_MESSAGES` are available from `jg-agent-hq/contracts` for the seven safe client classifications. SQLite-worker responses retain the originating application code; arbitrary worker failures become `JG_AGENT_HQ_STORE_FAILED`. Browser and IPC error bodies expose only their established safe classification and message.
+
 ## Lock lifecycle
 
-- `acquireHqLock(root, command, options?)` acquires `.runtime/hq.lock` and returns an asynchronous release function. The caller owns the trusted state root and supplies a non-empty, single-line operation label. Surrounding whitespace is trimmed. The returned release function is idempotent and refuses a replaced owner.
+- `acquireHqLock(root, command, options?)` acquires `.runtime/hq.lock` and returns an asynchronous release function. The caller owns the trusted state root and supplies a non-empty, single-line operation label. Surrounding whitespace is trimmed. The returned release function is idempotent and refuses a replaced owner. Acquisitions in one process queue by their normalized lock path, so later status polling cannot overtake a waiting checkpoint. Cross-process exclusion still uses the same file and exact owner; no cross-process ordering is promised. Timed-out or failed waiters leave the local queue.
 - `withHqLock(root, command, operation, options?)` runs an asynchronous operation under the lock. It releases on success or failure; operation failures propagate unchanged. If cleanup also fails, the original operation error stays primary and cleanup failure is reported on stderr.
 - `readHqLockState(root, now?)` reports free, held or unreadable without acquiring or reclaiming the lock. Held state includes the owner, liveness and age.
 - `getOwnerLiveness(pid)` reports alive, dead or unknown. An unverifiable owner is not evidence that recovery is safe.
@@ -166,13 +168,17 @@ Output is one JSON line with `schemaVersion: 1`. Read output includes the comman
 
 ## Plan coordination
 
-`computePlanRevision({ body, metadata, milestones })` is the pure Node API for execution identity. `metadata` contains `scope`, `repositories` and `errorReservations`. 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. Plan bodies normalize line endings only. Private coordinators supply the body after parsing their own frontmatter; ordinary planning directories use the entire plan file.
+`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. A private host supplies `parsePlanContract({ directory, content })` when constructing the runtime. It returns the exact body after frontmatter and its contract metadata from the current file. The core validates that exclusion boundary and metadata while leaving private frontmatter policy with its owner. With no parser, the whole ordinary plan is contractual. The private server resolves operator identity itself and never forwards browser-supplied roots, contract exclusions or metadata.
+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.
+
+Milestone contracts retain every requirement byte outside observed status/identity lines, plus preamble and all intervening/trailing shared sections. Only recognized Overview table spans and the three valid `jg_skills` binding fields are excluded; other milestone metadata remains contractual. HQ does not regenerate Overview tables. Statuses must be exactly pending, in progress or done, and milestone IDs/order participate in sequence identity. Ordinal renumbering alone does not change a milestone's identity. Missing IDs are assigned explicitly by jg-plans and saved before application. When present, a skills binding must match the current plan id, revision and fingerprint excluding exactly the four administrative keys. A matching binding never grants HQ approval or execution permission.
 
 | Command kind      | Required fields and result                                                                                                                                                                                                                               |
 | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `status`          | `target`. Returns current execution revisions, full inspection hashes, approval state and a bounded coordination summary and retained-evidence counts.                                                                                                   |
+| `status`          | `target`. Returns current execution revisions, full inspection hashes, `skillsBinding` (`absent`, `current` or `stale`), approval state and a bounded coordination summary and retained-evidence counts.                                                 |
 | `milestones`      | `target`, optional `limit` (default 32, maximum 128) and `cursor`. Returns a bounded ordered seek page.                                                                                                                                                  |
 | `finalize`        | `target`, `action`, `expected`. Assigns initial UUIDs or reconciles a checkpoint. Returns the complete canonical file, or a saved proposal needing one confirmation. Optional `confirmation: { proposalId, decisions }` resolves every unmatched source. |
 | `begin-revision`  | `target`, `action`, `expected`, `intent: 'plan' \| 'breakdown'`, `threadIds`, `checkouts`. Closes execution admission and starts owned interruption/checkpoint work.                                                                                     |
@@ -188,13 +194,23 @@ Send `{ kind: 'plan', command }` through the existing local request API. Every c
 
 Milestones are optional. Finalizing a plan with no milestone file returns `content: null` and does not create a file. That unit needs plan approval and explicit execution authorization, with `milestoneIds: []`; execution checks, completion and native execution scopes select it with `milestoneId: null`. A real breakdown requires a nonempty selection of its stable IDs and its separate sequence approval. Null cannot select a milestone or bypass sequence approval. Whole-plan completion retains its exact plan contract/digest, actual check references and checkout evidence, with null shared-sequence digest. Completed work cannot be authorized again under that unchanged contract.
 
-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 refreshes existing Overview status rows 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.
+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.
 
-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 normalized execution revisions. Administrative frontmatter excluded by the trusted contract parser, session labels, status advancement and coordination receipts do not change execution digests.
+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.
 
 Plan and milestone artifacts are bounded to 1 MiB each; coordination evidence is bounded to 8 MiB and a sequence to 1,024 milestones. Reads do not scan planning trees. Milestone pages use ordinal seek ordering with unique ascending ordinals. Cursors bind the selected directory, page size, execution revisions and exact milestone inspection hash. Any changed artifact requires a fresh page; renumbering or status-only edits still preserve approval. A SQLite projection is rebuilt only when the selected milestone file's full hash changes. Every read verifies its source file; the projection is replaceable and never grants authority.
 
-Mutations hold the shared metadata lock at `<coordinationRoot>/.runtime/hq.lock` (`coordinationRoot` defaults to `stateRoot`), retain a durable action identity and intended write before changing files, sync temporary files and atomically replace each artifact. Use `serve --coordination-root <directory>` when the canonical coordination lock is separate from runtime storage. Repeating an action UUID with the identical payload never reapproves revoked work. A changed payload conflicts. An interrupted write remains blocked and can be retried with its original action only when files match the recorded baseline or exact intended output. Conflicting edits are preserved. Completed write bodies are removed from SQLite while replay identity remains. The current finalization receipt retains the operator event, execution revision, nullable canonical file hash and timestamp independently of write recovery bodies. Status reads expose `pendingActionId` for unresolved writes; they never approve or resume work.
+Mutations acquire the HQ metadata lock at `<coordinationRoot>/.runtime/hq.lock` (`coordinationRoot` defaults to `stateRoot`), then the public jg-plans document locks in plan-before-milestones order. Use `serve --coordination-root <directory>` when coordination ownership is separate from runtime storage. Locks cover bounded observation, preparation, journaling and file application; no model turn or native stop wait holds them. A busy document lock becomes `JG_AGENT_HQ_ACTION_CONFLICT` with the safe `document-locked` reason. There is no automatic stale-lock takeover.
+
+SQLite persists exact prepared plan/milestone sources, assigned IDs and timestamps before application. A plan source of null means keep; milestone operations are explicitly keep, write with source, or remove. A null recorded before-plan hash permits only coordination work. Replay accepts only each recorded baseline or its exact desired state. Markdown is applied before coordination. Every HQ replacement uses jg-fs checked atomic writes with explicit 0600; absent targets are created exclusively and privately before content is written. Strict bounded, same-handle, single-link reads remain in HQ. Inspection alone never changes file permissions.
+
+After file durability succeeds, document locks must release successfully before SQLite marks the intent completed and clears its write bodies; HQ metadata ownership remains held through completion. A write, sync or release failure retains the prepared payload and closes admission. A crash after release and before completion is replayable. A failed completion acknowledgement is reconciled against the durable ledger: confirmed completion succeeds, an uncommitted intent stays pending, and an unknown outcome remains closed. Retry only the same original action and payload after inspection; changed files or payloads conflict. Nonparticipating writers still have a final comparison-to-replacement/removal race; these operations are not a multi-file transaction.
+
+Accepted implementation input prepares aggregate and selected pending milestone progress before native admission. Message, queue and steering requests record accepted implementation scope; an in-progress marker does not assert that a provider has started or completed a turn. Progress is journaled and released before current authority is checked again for native admission. A retry of the same native action can finish its retained progress intent without regenerating timestamps; it still needs current runtime/authorization checks. Native control and permission actions do not advance progress.
+
+Only accepted completion evidence advances a milestone to done. Aggregate done requires the complete current execution contract, applicable current approval/finalization and verified completion; administrative done markers alone do not provide them. Progress-only plan changes preserve revision and set updated_at once in the saved prepared source. An unchanged plan preserves its timestamp. The current finalization receipt retains the operator event, semantic revision, nullable canonical file hash and timestamp independently of write recovery bodies. Status reads expose pendingActionId for unresolved writes and never approve or resume work.
 
 `coordination.json` includes required `comparisons`, an array bounded to 1,024 records validated by `PlanComparisonSchema`. Each record binds `sourceRevision`, `targetDirectory`, `targetRevision`, a `compatible` or `contradiction` verdict, `reason`, `reviewedAt` and reviewer provenance (`provider`, `cliVersion`, nullable observed `model`, and native message `reference`). A trusted coordinator writes these records while holding the same metadata lock. Core operations preserve them; status exposes only `comparisonCount`. They never change execution digests or grant authority. The coordinator owns relevance, freshness, semantic judgments, bounded review reads and any execution gate, including contradictions. The standalone core does not assess compatibility.
 
@@ -206,7 +222,7 @@ Begin revision before invoking a planning skill. Execution admission closes unde
 
 The local host supplies checkout evidence as `{ repository, directory, claimReference, paths }`. Paths are exact relative task paths. The core streams their contents, records link targets without following them, includes missing paths as deletions, and captures the current Git branch/HEAD. It does not stage or reset files and rejects traversal, parent-link escapes, `.git` and excluded archive/backup directories. Check commands and references are trusted operator evidence; this primitive does not execute arbitrary submitted commands or treat an imported agent claim as verification.
 
-After native `jg-plan` revises the contract and an explicitly requested `jg-breakdown` regenerates a needed sequence, close the planning controller before finalization. Only unique exact normalized title and complete-contract matches retain identity automatically. Every unmatched checkpoint source, including done and partial work, appears in one saved proposal. Confirmation decisions use `sourceIds`, `targetIds`, `relation` (`equivalent`, `requirements-changed`, `omitted`, `reopened`) and explicit one-to-one `retainedPairs`. One source ID cannot be assigned to multiple targets. Grouped decisions retain split/merged evidence. A complete equivalent mapping preserves verified completion or partial status; rewording does not create new checks. A changed requirement gets fresh pending identity. Explicit reopening preserves evidence while invalidating its completion credit. Unverified done markers cannot become verified through an equivalent mapping.
+After native `jg-plan` revises the contract and an explicitly requested `jg-breakdown` regenerates a needed sequence, close the planning controller before finalization. Only unique exact title and complete-contract matches retain identity automatically. Every unmatched checkpoint source, including done and partial work, appears in one saved proposal. Status exposes its nullable `coordination.revision.proposalId`; clients use the paged reconciliation reads to present correspondence and confirm that exact saved identity. Confirmation decisions use `sourceIds`, `targetIds`, `relation` (`equivalent`, `requirements-changed`, `omitted`, `reopened`) and explicit one-to-one `retainedPairs`. One source ID cannot be assigned to multiple targets. Grouped decisions retain split/merged evidence. A complete equivalent mapping preserves verified completion or partial status; rewording does not create new checks. A changed requirement gets fresh pending identity. Explicit reopening preserves evidence while invalidating its completion credit. Unverified done markers cannot become verified through an equivalent mapping.
 
 A whole-plan checkpoint retains null milestones and an empty milestone inventory. If a revision removes a sequence because the remaining scope no longer needs one, every unmatched checkpoint milestone still requires explicit omission confirmation. Its verified evidence remains available; absence alone never resets progress or authorizes whole-plan execution.
 

package/dist/actions/actions.d.ts

@@ -14,14 +14,14 @@ export declare const createActions: (native: ICodexProvider, claude: ReturnType<
      * Returns after durable admission; the native operation outlives this client request.
      * @returns The durable admission receipt after validation.
      * @throws
-     * - -1: The HQ action conflicts with its recorded state
-     * - -1: The HQ skill is unavailable
-     * - -1: The HQ request is invalid
-     * - -1: The HQ target is outside the allowed workspaces
-     * - -1: The Codex integration failed
-     * - -1: The Claude integration failed
-     * - -1: The Claude history is unavailable
-     * - -1: The HQ store failed
+     * - JG_AGENT_HQ_ACTION_CONFLICT: The HQ action conflicts with its recorded state
+     * - JG_AGENT_HQ_SKILL_UNAVAILABLE: The HQ skill is unavailable
+     * - 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_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_STORE_FAILED: The HQ store failed
      */
     submit(action: IActionEnvelope): Promise<IActionReceipt>;
     /** Reads only current in-memory prompts for the selected managed thread. */
@@ -30,21 +30,21 @@ export declare const createActions: (native: ICodexProvider, claude: ReturnType<
      * Quiesces the selected managed cohort without stopping unrelated controllers.
      * @returns A promise resolved only after interruption, background cleanup and release evidence.
      * @throws
-     * - -1: The HQ action conflicts with its recorded state
-     * - -1: The HQ target is outside the allowed workspaces
-     * - -1: The HQ store failed
-     * - -1: The Codex integration failed
-     * - -1: The Claude integration failed
+     * - JG_AGENT_HQ_ACTION_CONFLICT: The HQ action conflicts with its recorded state
+     * - JG_AGENT_HQ_TARGET_FORBIDDEN: The HQ target is outside the allowed workspaces
+     * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
+     * - JG_AGENT_HQ_CODEX_FAILED: The Codex integration failed
+     * - JG_AGENT_HQ_CLAUDE_FAILED: The Claude integration failed
      */
     quiescePlan(controls: IPlanRevisionWorkflow["controls"]): Promise<void>;
     /**
      * Stops admission, interrupts active work, cleans native terminals and confirms shutdown.
      * @returns A promise resolved after native exit and release of durable control ownership.
      * @throws
-     * - -1: The Codex integration failed
-     * - -1: The Claude integration failed
-     * - -1: The HQ transport failed
-     * - -1: The HQ store failed
+     * - JG_AGENT_HQ_CODEX_FAILED: The Codex integration failed
+     * - JG_AGENT_HQ_CLAUDE_FAILED: The Claude integration failed
+     * - JG_AGENT_HQ_TRANSPORT_FAILED: The HQ transport failed
+     * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
      */
     close(): Promise<void>;
 };

package/dist/actions/actions.js

@@ -1,5 +1,5 @@
 import { createHmac, randomUUID } from 'node:crypto';
-import { Exception, extractMessage } from 'error-message-utils';
+import { Exception, extractMessage, isException } from 'jg-exception';
 import { z } from 'zod';
 import { setTimeout as wait } from 'node:timers/promises';
 import { getErrorKind } from '../errors/index.js';
@@ -40,12 +40,18 @@ export const createActions = (native, claude, readClaudeThread, store, roots, ep
     let unavailable = false;
     let eventFailure;
     const conflict = () => {
-        throw new Exception('The HQ action conflicts with its recorded state', undefined, {
-            kind: 'state-conflict',
+        throw new Exception('The HQ action conflicts with its recorded state', {
+            code: 'JG_AGENT_HQ_ACTION_CONFLICT',
+            data: {
+                kind: 'state-conflict',
+            },
         });
     };
     const agentUnavailable = () => {
-        throw new Exception('The Codex integration failed', undefined, { kind: 'agent-unavailable' });
+        throw new Exception('The Codex integration failed', {
+            code: 'JG_AGENT_HQ_CODEX_FAILED',
+            data: { kind: 'agent-unavailable' },
+        });
     };
     /** Quarantines controls after a lifecycle gap and stops the native transport. */
     const failEvents = (cause) => {
@@ -111,7 +117,10 @@ export const createActions = (native, claude, readClaudeThread, store, roots, ep
         if (unavailable)
             return;
         if (eventCount >= 128) {
-            failEvents(new Exception('The Codex integration failed', undefined, { kind: 'agent-unavailable' }));
+            failEvents(new Exception('The Codex integration failed', {
+                code: 'JG_AGENT_HQ_CODEX_FAILED',
+                data: { kind: 'agent-unavailable' },
+            }));
             return;
         }
         eventCount += 1;
@@ -179,8 +188,8 @@ export const createActions = (native, claude, readClaudeThread, store, roots, ep
      * Dispatches one admitted intent once and records delivery without replaying it.
      * @returns A promise resolved after delivery evidence or uncertainty is persisted.
      * @throws
-     * - -1: The HQ action conflicts with its recorded state
-     * - -1: The HQ store failed
+     * - JG_AGENT_HQ_ACTION_CONFLICT: The HQ action conflicts with its recorded state
+     * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
      */
     const dispatch = async (initial, originalThread, command, input) => {
         let receipt = initial;
@@ -295,7 +304,7 @@ export const createActions = (native, claude, readClaudeThread, store, roots, ep
         }
         catch (error) {
             // Only a matching native error response proves rejection. Transport loss and malformed results remain uncertain.
-            const explicit = error instanceof Exception && NativeRejectionSchema.safeParse(error.data).success;
+            const explicit = isException(error) && NativeRejectionSchema.safeParse(error.data).success;
             const kind = getErrorKind(error);
             const failure = kind === 'state-conflict' || kind === 'access-denied' || kind === 'agent-unavailable'
                 ? kind
@@ -620,14 +629,14 @@ export const createActions = (native, claude, readClaudeThread, store, roots, ep
      * Validates the current target and separates new dispatch from idempotent receipt reads.
      * @returns The durable admission receipt; native work runs independently.
      * @throws
-     * - -1: The HQ action conflicts with its recorded state
-     * - -1: The HQ skill is unavailable
-     * - -1: The HQ request is invalid
-     * - -1: The HQ target is outside the allowed workspaces
-     * - -1: The Codex integration failed
-     * - -1: The Claude integration failed
-     * - -1: The Claude history is unavailable
-     * - -1: The HQ store failed
+     * - JG_AGENT_HQ_ACTION_CONFLICT: The HQ action conflicts with its recorded state
+     * - JG_AGENT_HQ_SKILL_UNAVAILABLE: The HQ skill is unavailable
+     * - 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_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_STORE_FAILED: The HQ store failed
      */
     const admitAndDispatch = async (action) => {
         // The worker verifies the complete digest before returning any existing receipt.
@@ -810,14 +819,14 @@ export const createActions = (native, claude, readClaudeThread, store, roots, ep
          * Returns after durable admission; the native operation outlives this client request.
          * @returns The durable admission receipt after validation.
          * @throws
-         * - -1: The HQ action conflicts with its recorded state
-         * - -1: The HQ skill is unavailable
-         * - -1: The HQ request is invalid
-         * - -1: The HQ target is outside the allowed workspaces
-         * - -1: The Codex integration failed
-         * - -1: The Claude integration failed
-         * - -1: The Claude history is unavailable
-         * - -1: The HQ store failed
+         * - JG_AGENT_HQ_ACTION_CONFLICT: The HQ action conflicts with its recorded state
+         * - JG_AGENT_HQ_SKILL_UNAVAILABLE: The HQ skill is unavailable
+         * - 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_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_STORE_FAILED: The HQ store failed
          */
         async submit(action) {
             const admission = admitAndDispatch(action);
@@ -839,11 +848,11 @@ export const createActions = (native, claude, readClaudeThread, store, roots, ep
          * Quiesces the selected managed cohort without stopping unrelated controllers.
          * @returns A promise resolved only after interruption, background cleanup and release evidence.
          * @throws
-         * - -1: The HQ action conflicts with its recorded state
-         * - -1: The HQ target is outside the allowed workspaces
-         * - -1: The HQ store failed
-         * - -1: The Codex integration failed
-         * - -1: The Claude integration failed
+         * - JG_AGENT_HQ_ACTION_CONFLICT: The HQ action conflicts with its recorded state
+         * - JG_AGENT_HQ_TARGET_FORBIDDEN: The HQ target is outside the allowed workspaces
+         * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
+         * - JG_AGENT_HQ_CODEX_FAILED: The Codex integration failed
+         * - JG_AGENT_HQ_CLAUDE_FAILED: The Claude integration failed
          */
         async quiescePlan(controls) {
             const failures = [];
@@ -860,10 +869,10 @@ export const createActions = (native, claude, readClaudeThread, store, roots, ep
          * Stops admission, interrupts active work, cleans native terminals and confirms shutdown.
          * @returns A promise resolved after native exit and release of durable control ownership.
          * @throws
-         * - -1: The Codex integration failed
-         * - -1: The Claude integration failed
-         * - -1: The HQ transport failed
-         * - -1: The HQ store failed
+         * - JG_AGENT_HQ_CODEX_FAILED: The Codex integration failed
+         * - JG_AGENT_HQ_CLAUDE_FAILED: The Claude integration failed
+         * - JG_AGENT_HQ_TRANSPORT_FAILED: The HQ transport failed
+         * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
          */
         async close() {
             closing = true;
@@ -902,7 +911,11 @@ export const createActions = (native, claude, readClaudeThread, store, roots, ep
                 await lane.catch(() => undefined);
                 const failedExit = nativeExit.find((result) => result.status === 'rejected');
                 if (failedExit?.status === 'rejected')
-                    throw new Exception(`The HQ transport failed: ${extractMessage(failedExit.reason)}`, undefined, { kind: 'operation-failed' }, { cause: cleanupFailure ?? failedExit.reason });
+                    throw new Exception(`The HQ transport failed: ${extractMessage(failedExit.reason)}`, {
+                        code: 'JG_AGENT_HQ_TRANSPORT_FAILED',
+                        data: { kind: 'operation-failed' },
+                        cause: cleanupFailure ?? failedExit.reason,
+                    });
             }
             if (cleanupFailure)
                 throw cleanupFailure;

package/dist/actions/reads.d.ts

@@ -8,10 +8,10 @@ type IControlRead = Extract<IHqRequest, {
  * Authorizes bounded control reads and binds seek positions to their exact query.
  * @returns The selected record or bounded page.
  * @throws
- * - -1: The HQ action conflicts with its recorded state
- * - -1: The HQ cursor does not match this request
- * - -1: The HQ target is outside the allowed workspaces
- * - -1: The HQ store failed
+ * - JG_AGENT_HQ_ACTION_CONFLICT: The HQ action conflicts with its recorded state
+ * - JG_AGENT_HQ_CURSOR_INVALID: The HQ cursor does not match this request
+ * - JG_AGENT_HQ_TARGET_FORBIDDEN: The HQ target is outside the allowed workspaces
+ * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
  */
 export declare const readControl: (command: IControlRead, store: IStore, actions: ReturnType<typeof createActions>, roots: string[]) => Promise<IHqResponse>;
 export {};

package/dist/actions/reads.js

@@ -1,4 +1,4 @@
-import { Exception } from 'error-message-utils';
+import { Exception } from 'jg-exception';
 import { z } from 'zod';
 import { resolveWorkspaceTarget } from '../runtime/state/index.js';
 import { decodeHistoryCursor, encodeHistoryCursor } from '../sessions/index.js';
@@ -6,7 +6,7 @@ const PositionSchema = z.strictObject({ createdAt: z.number().int(), id: z.uuid(
 /**
  * Validates the application-owned seek position after the shared query-binding check.
  * @throws
- * - -1: The HQ cursor does not match this request
+ * - JG_AGENT_HQ_CURSOR_INVALID: The HQ cursor does not match this request
  */
 const readPosition = (cursor, filters) => {
     const decoded = decodeHistoryCursor(cursor, filters);
@@ -16,7 +16,11 @@ const readPosition = (cursor, filters) => {
         return PositionSchema.parse(JSON.parse(decoded));
     }
     catch (cause) {
-        throw new Exception('The HQ cursor does not match this request', undefined, { kind: 'invalid-request' }, { cause });
+        throw new Exception('The HQ cursor does not match this request', {
+            code: 'JG_AGENT_HQ_CURSOR_INVALID',
+            data: { kind: 'invalid-request' },
+            cause,
+        });
     }
 };
 /** Encodes the final row's complete ordering tuple only when another page exists. */
@@ -28,10 +32,10 @@ const nextPageCursor = (page, filters) => {
  * Authorizes bounded control reads and binds seek positions to their exact query.
  * @returns The selected record or bounded page.
  * @throws
- * - -1: The HQ action conflicts with its recorded state
- * - -1: The HQ cursor does not match this request
- * - -1: The HQ target is outside the allowed workspaces
- * - -1: The HQ store failed
+ * - JG_AGENT_HQ_ACTION_CONFLICT: The HQ action conflicts with its recorded state
+ * - JG_AGENT_HQ_CURSOR_INVALID: The HQ cursor does not match this request
+ * - JG_AGENT_HQ_TARGET_FORBIDDEN: The HQ target is outside the allowed workspaces
+ * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
  */
 export const readControl = async (command, store, actions, roots) => {
     const authorize = async (thread) => {
@@ -80,8 +84,11 @@ export const readControl = async (command, store, actions, roots) => {
     if (command.kind === 'managed-thread')
         return { kind: command.kind, result: thread };
     if (!thread)
-        throw new Exception('The HQ action conflicts with its recorded state', undefined, {
-            kind: 'state-conflict',
+        throw new Exception('The HQ action conflicts with its recorded state', {
+            code: 'JG_AGENT_HQ_ACTION_CONFLICT',
+            data: {
+                kind: 'state-conflict',
+            },
         });
     if (command.kind === 'events')
         return {