jg-agent-hq 0.5.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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.
+- Qualify Claude transcript formats 2.1.296 and 2.1.299, preserve in-workspace working-directory changes, and refresh reader projections when their interpretation changes. Keep executable qualification separate and reject workspace/symlink escapes.
+- Await native-fixture cleanup after test timeouts and give the full 1,024-milestone revision workflow a focused CI budget. Add a real child-runner timeout/isolation regression.
+
 ## 0.5.1
 
 - Qualify Claude Code 2.1.306 history alongside 2.1.304, including transcripts spanning both versions. Continue to reject unqualified CLI and transcript versions.

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.
@@ -41,7 +43,7 @@ The controller owns its SQLite worker and native connections independently of cl
 
 The current read contracts were exercised against Codex 0.163.0 and Claude Code versions 2.1.304 and 2.1.306 on Linux. Unsupported native responses fail explicitly. `jg-agent-hq/contracts` contains browser-safe schemas and types; importing it does not import the host runtime.
 
-Use `--provider claude` for Claude history and usage; the default is `codex`. Claude connects lazily through its native structured CLI, with normal settings enabled and no user prompt. Usage requests explicitly disable the optional transcript-behavior scan. Its local history reader accepts only the qualified 2.1.304 and 2.1.306 versions, including transcripts containing both, keeps byte locations rather than conversation bodies in SQLite, and reports unsupported history as unavailable. File history cannot establish current execution state. See the [reader limits and freshness contract](api/README.md#claude-history).
+Use `--provider claude` for Claude history and usage; the default is `codex`. Claude connects lazily through its native structured CLI, with normal settings enabled and no user prompt. Usage requests explicitly disable the optional transcript-behavior scan. Its local history reader accepts only qualified transcript versions 2.1.296, 2.1.299, 2.1.304 and 2.1.306, including transcripts spanning these versions, keeps byte locations rather than conversation bodies in SQLite, and reports unsupported history as unavailable. File history cannot establish current execution state. See the [reader limits and freshness contract](api/README.md#claude-history).
 
 Explicit actions create, name, adopt, resume and close threads; send idle messages; steer an exact running turn; queue the next message; interrupt; and answer native questions or permissions. Actions have stable UUIDs and durable receipts. Repeating the same request returns its receipt; changing that UUID's payload conflicts. A lost acknowledgement stays uncertain until the exact native response arrives or the operator makes an explicit recovery choice. HQ never resends uncertain input.
 
@@ -105,4 +107,6 @@ Tests consume built public exports. Unit tests cover application-owned decisions
 
 The website's README and `docs/website.md` define its build-once check composition, category-specific scripts and owned preview/browser lifecycle. Root and website checks must both pass for task completion when workspace configuration or canonical site content changes.
 
+The runtime fixture teardown is registered with the test runner as well as the callback, so a test timeout cannot restore environment variables during the next test.
+
 Current local checks establish the tested host only. Release qualification must include the Node engines floor and current LTS; macOS operation requires its own runtime evidence.

package/api/README.md

@@ -2,6 +2,8 @@
 
 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.
@@ -48,11 +50,11 @@ Threads expose native state, `historyState` (`available` or `unavailable`), owne
 
 Claude connects on its first read through `claude --print --input-format stream-json --output-format stream-json --verbose`. No user prompt, bare mode, permission bypass or SDK dependency is used. Runtime status reports this adapter as `idle`, `ready` or `unavailable`, with its observed CLI version. An unavailable native lane requires restarting the host after resolving the native problem.
 
-The qualified CLI interface has no session-history listing operation. The Claude-owned reader therefore uses direct UUID JSONL files in the native project's directory beneath `CLAUDE_CONFIG_DIR`, or the normal `.claude` directory. The CLI and each versioned transcript record must independently match a qualified version: 2.1.304 or 2.1.306. A transcript may contain both qualified versions. Other formats, encoded project keys longer than 200 characters, directory/file links, malformed records and records larger than 1 MiB report unavailable. Discovery never recurses into subdirectories, including excluded directories. Unsupported discovered sessions have `historyState: unavailable`; they do not prevent supported sessions from being listed.
+The qualified CLI interface has no session-history listing operation. The Claude-owned reader therefore uses direct UUID JSONL files in the native project's directory beneath `CLAUDE_CONFIG_DIR`, or the normal `.claude` directory. The running CLI must match 2.1.304 or 2.1.306. Transcript records may independently use the qualified formats 2.1.296, 2.1.299, 2.1.304 and 2.1.306, including multiple qualified formats within one session. Qualifying a stored record format does not qualify that executable version. Other formats, encoded project keys longer than 200 characters, directory/file links, malformed records and records larger than 1 MiB report unavailable. Discovery never recurses into subdirectories, including excluded directories. Unsupported discovered sessions have `historyState: unavailable`; they do not prevent supported sessions from being listed.
 
-Discovery verifies the workspace recorded inside each transcript before returning its identity or title. A matching native directory name alone is insufficient because punctuation replacement can produce colliding directory keys. Foreign workspaces are omitted. If a file's workspace cannot be established, discovery reports unavailable rather than inventing an empty result.
+Discovery verifies the workspace recorded inside each transcript before returning its identity or title. A matching native directory name alone is insufficient because punctuation replacement can produce colliding directory keys. Native working directories may be the selected workspace or its subdirectories, including removed subdirectories. The nearest existing path ancestor must resolve inside the workspace without excluded segments; sibling paths and symlink escapes are rejected. Foreign workspaces are omitted. If a file's workspace cannot be established, discovery reports unavailable rather than inventing an empty result.
 
-The existing SQLite worker incrementally records file identity, complete-line offsets, message identities and parent links. It does not save message bodies. Each worker batch inspects at most 128 directory entries and reads at most 4 MiB of new transcript bytes, one file at a time. The adapter continues batches with a host-event-loop yield between them, within a 30-second operation budget. If that budget is reached, the read reports unavailable and subsequent reads continue indexing. At most four incomplete discovery iterators remain open. Shutdown closes them. Discovery continuations use that projection without starting another directory scan; start a fresh first page to refresh discovery. Removed files are discarded from the projection after a complete refresh. No additional cache infrastructure or browser cache is used.
+The existing SQLite worker incrementally records file identity, complete-line offsets, message identities and parent links. It does not save message bodies. File identity includes the reader projection revision and qualified record formats, so a reader capability change refreshes rejected or obsolete projections from native files. Each worker batch inspects at most 128 directory entries and reads at most 4 MiB of new transcript bytes, one file at a time. The adapter continues batches with a host-event-loop yield between them, within a 30-second operation budget. If that budget is reached, the read reports unavailable and subsequent reads continue indexing. At most four incomplete discovery iterators remain open. Shutdown closes them. Discovery continuations use that projection without starting another directory scan; start a fresh first page to refresh discovery. Removed files are discarded from the projection after a complete refresh. No additional cache infrastructure or browser cache is used.
 
 Current-chain membership and turn starts are indexed as metadata. Ordinary item and turn continuations seek those indexes; they do not walk the full chain per page. A changed branch rebuilds membership before exposing that revision. Repeated native message identities can replace content while retaining their parent; a changed parent for the same identity is an unsupported format.
 
@@ -84,6 +86,8 @@ Message and queue input is a closed union: `{ kind: 'text', text }` or `{ kind:
 
 Names use lowercase ASCII letters, digits and hyphens, start with a letter or digit, and have at most 32 characters. Names are unique without regard to case in one state directory. Creation and adoption resolve collisions atomically with ordinal suffixes such as `build-usage-2`, truncating the base to keep the complete name within 32 characters. Explicit rename rejects an occupied or pending name. Provider/native-session pairs remain unique. At most 32 native sessions are controlled concurrently; close idle sessions to release capacity. Native discovery remains independent of that limit. Confirm that other native CLI controllers are closed before adoption, resume or recovery. An unloaded native status cannot prove another CLI has stopped. HQ provides exclusive coordination within one canonical state directory; it does not impose a global lock on independent CLIs. Recovery is permitted only after the producing runtime has stopped and its ownership evidence has been inspected.
 
+Codex may keep an idle native thread loaded after `thread/unsubscribe`. An explicitly confirmed resume may reacquire that thread only when its known HQ control is inactive and managed. Active native threads, uncertain HQ ownership and already controlled idle sessions remain blocked. Other adoption and recovery checks are unchanged.
+
 Receipts separate `delivery` (`queued`, `submitted`, `acknowledged`, `uncertain`, `failed`, `canceled`) from nullable native turn `completion` (`completed`, `failed`, `interrupted`). Acknowledgement means the exact native request was accepted, not that the turn or tool completed. Permission replies remain submitted after a pipe write and become acknowledged only when Codex resolves the exact native request or Claude returns a tool-result block for the exact tool-use identity. Claude cancellation expires the prompt and leaves an unacknowledged written reply uncertain. Resolution does not prove a tool ran. The receipt includes HQ/native identity, request phase, digest, timestamps, safe failure classification and optional related action. Only selected receipts expose undelivered `queuedText` and `queuedSkill`; collection reads omit both. Queued native skill selections contain a native name and nullable source path, never skill content. Both are cleared after delivery acknowledgement or cancellation.
 
 A missing acknowledgement never triggers an automatic resend. Exact late responses reconcile delivery, including completion that arrived first. Native output loss marks the affected provider controls and submitted work uncertain. A Claude process failure affects its own session; a Codex transport failure affects its Codex cohort. Restart quarantines controls from an interrupted runtime; explicit recovery preserves the HQ identity and name. Successful shutdown proves native process-group exit before marking controls inactive. Unknown creation without a native identity remains uncertain.
@@ -100,7 +104,7 @@ Prompts expose `replyActionId` as soon as a reply is admitted, so reconnecting c
 
 ### Claude native control
 
-Each controlled session has one persistent native `claude` process in the authorized workspace. HQ adds structured input/output, replayed user-message acknowledgements, partial-message output and `--permission-prompt-tool=stdio`. It does not set a model, replace instructions/settings, disable session persistence, bypass permissions or enable a bare mode. Native skills remain available. Control was exercised against CLI 2.1.304. Native idle initialization, session identity and matching acknowledgements establish capability; a changed version label alone does not disable compatible controls. File history retains its separate qualified-version check.
+Each controlled session has one persistent native `claude` process in the authorized workspace. HQ adds structured input/output, replayed user-message acknowledgements, partial-message output and `--permission-prompt-tool=stdio`. It does not set a model, replace instructions/settings, disable session persistence, bypass permissions or enable a bare mode. Native skills remain available. Control was exercised against CLI 2.1.304 and 2.1.306. Native idle initialization, session identity and matching acknowledgements establish capability; a changed version label alone does not disable compatible controls. File history retains its separate qualified-version check.
 
 Creation chooses a native UUID without inference, then names that exact session. Resume uses native `--resume` and verifies the session-id fence on the name control before marking the session idle. The operator's handoff confirmation establishes that another CLI controller is closed; file timestamps and file-backed unknown states do not establish this. Independently running CLIs are outside HQ's state-directory coordination boundary.
 

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.
@@ -690,9 +699,15 @@ export const createActions = (native, claude, readClaudeThread, store, roots, ep
                 const target = provider === 'codex'
                     ? await native.readThread(nativeId)
                     : await readClaudeThread(nativeId, thread.workspaceRoot);
-                if ((provider === 'codex'
-                    ? target.nativeState !== 'notLoaded'
-                    : target.historyState !== 'available') ||
+                // native unsubscribe may retain an idle thread after its managed control is closed
+                const canResume = provider === 'codex'
+                    ? target.nativeState === 'notLoaded' ||
+                        (command.kind === 'thread-resume' &&
+                            thread.state === 'inactive' &&
+                            thread.ownership === 'managed' &&
+                            target.nativeState === 'idle')
+                    : target.historyState === 'available';
+                if (!canResume ||
                     (await resolveWorkspaceTarget(target.workspaceRoot, roots)) !== thread.workspaceRoot)
                     conflict();
                 prepared.nativeId = nativeId;
@@ -804,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);
@@ -833,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 = [];
@@ -854,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;
@@ -896,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 {

package/dist/cli/cli.js

@@ -2,7 +2,7 @@
 import { resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { setTimeout as wait } from 'node:timers/promises';
-import { Exception, hasErrorCode } from 'error-message-utils';
+import { Exception, hasErrorCode, isException } from 'jg-exception';
 import { HqRequestSchema } from '../contracts/index.js';
 import { toPublicError } from '../errors/index.js';
 import { requestAgentHq } from '../ipc/index.js';
@@ -40,20 +40,32 @@ const main = async () => {
         return;
     }
     if (positionals.length !== 1 || !values['state-root'])
-        throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' });
+        throw new Exception('The HQ request is invalid', {
+            code: 'JG_AGENT_HQ_REQUEST_INVALID',
+            data: { kind: 'invalid-request' },
+        });
     const stateRoot = resolve(values['state-root']);
     const roots = (values['workspace-root'] ?? []).map((root) => resolve(root));
     if (kind === 'request') {
         if (Object.keys(values).some((key) => key !== 'state-root'))
-            throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' });
+            throw new Exception('The HQ request is invalid', {
+                code: 'JG_AGENT_HQ_REQUEST_INVALID',
+                data: { kind: 'invalid-request' },
+            });
         const chunks = [];
         let bytes = 0;
         for await (const chunk of process.stdin) {
             if (!Buffer.isBuffer(chunk))
-                throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' });
+                throw new Exception('The HQ request is invalid', {
+                    code: 'JG_AGENT_HQ_REQUEST_INVALID',
+                    data: { kind: 'invalid-request' },
+                });
             bytes += chunk.length;
             if (bytes > 65_536)
-                throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' });
+                throw new Exception('The HQ request is invalid', {
+                    code: 'JG_AGENT_HQ_REQUEST_INVALID',
+                    data: { kind: 'invalid-request' },
+                });
             chunks.push(chunk);
         }
         let input;
@@ -61,11 +73,19 @@ const main = async () => {
             input = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks, bytes)));
         }
         catch (cause) {
-            throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' }, { cause });
+            throw new Exception('The HQ request is invalid', {
+                code: 'JG_AGENT_HQ_REQUEST_INVALID',
+                data: { kind: 'invalid-request' },
+                cause,
+            });
         }
         const parsed = HqRequestSchema.safeParse(input);
         if (!parsed.success)
-            throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' }, { cause: parsed.error });
+            throw new Exception('The HQ request is invalid', {
+                code: 'JG_AGENT_HQ_REQUEST_INVALID',
+                data: { kind: 'invalid-request' },
+                cause: parsed.error,
+            });
         process.stdout.write(`${JSON.stringify({ schemaVersion: 1, ...(await requestAgentHq(stateRoot, parsed.data)) })}\n`);
         return;
     }
@@ -83,7 +103,10 @@ const main = async () => {
             values.limit ||
             values.search ||
             values.provider)
-            throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' });
+            throw new Exception('The HQ request is invalid', {
+                code: 'JG_AGENT_HQ_REQUEST_INVALID',
+                data: { kind: 'invalid-request' },
+            });
         const runtime = await createAgentHq({
             stateRoot,
             coordinationRoot: values['coordination-root']
@@ -117,9 +140,15 @@ const main = async () => {
     if (values['codex-extra-skill-root'] ||
         values['claude-additional-directory'] ||
         values['coordination-root'])
-        throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' });
+        throw new Exception('The HQ request is invalid', {
+            code: 'JG_AGENT_HQ_REQUEST_INVALID',
+            data: { kind: 'invalid-request' },
+        });
     if (roots.length > 1)
-        throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' });
+        throw new Exception('The HQ request is invalid', {
+            code: 'JG_AGENT_HQ_REQUEST_INVALID',
+            data: { kind: 'invalid-request' },
+        });
     if (kind === 'plan-status' || kind === 'plan-milestones') {
         const allowed = new Set([
             'state-root',
@@ -127,7 +156,10 @@ const main = async () => {
             ...(kind === 'plan-milestones' ? ['limit', 'cursor'] : []),
         ]);
         if (!values.directory || Object.keys(values).some((key) => !allowed.has(key)))
-            throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' });
+            throw new Exception('The HQ request is invalid', {
+                code: 'JG_AGENT_HQ_REQUEST_INVALID',
+                data: { kind: 'invalid-request' },
+            });
         const parsed = HqRequestSchema.safeParse({
             kind: 'plan',
             command: {
@@ -139,7 +171,11 @@ const main = async () => {
             },
         });
         if (!parsed.success)
-            throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' }, { cause: parsed.error });
+            throw new Exception('The HQ request is invalid', {
+                code: 'JG_AGENT_HQ_REQUEST_INVALID',
+                data: { kind: 'invalid-request' },
+                cause: parsed.error,
+            });
         process.stdout.write(`${JSON.stringify({ schemaVersion: 1, ...(await requestAgentHq(stateRoot, parsed.data)) })}\n`);
         return;
     }
@@ -149,7 +185,10 @@ const main = async () => {
             ...(kind === 'handoff-show' ? ['id'] : ['workspace-root', 'thread-id', 'limit', 'cursor']),
         ]);
         if (Object.keys(values).some((key) => !allowed.has(key)))
-            throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' });
+            throw new Exception('The HQ request is invalid', {
+                code: 'JG_AGENT_HQ_REQUEST_INVALID',
+                data: { kind: 'invalid-request' },
+            });
         const parsed = HqRequestSchema.safeParse({
             kind: 'handoff',
             command: kind === 'handoff-show'
@@ -163,14 +202,24 @@ const main = async () => {
                 },
         });
         if (!parsed.success)
-            throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' }, { cause: parsed.error });
+            throw new Exception('The HQ request is invalid', {
+                code: 'JG_AGENT_HQ_REQUEST_INVALID',
+                data: { kind: 'invalid-request' },
+                cause: parsed.error,
+            });
         process.stdout.write(`${JSON.stringify({ schemaVersion: 1, ...(await requestAgentHq(stateRoot, parsed.data)) })}\n`);
         return;
     }
     if (values.id)
-        throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' });
+        throw new Exception('The HQ request is invalid', {
+            code: 'JG_AGENT_HQ_REQUEST_INVALID',
+            data: { kind: 'invalid-request' },
+        });
     if (values.directory)
-        throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' });
+        throw new Exception('The HQ request is invalid', {
+            code: 'JG_AGENT_HQ_REQUEST_INVALID',
+            data: { kind: 'invalid-request' },
+        });
     const payload = Object.fromEntries([
         ['kind', kind],
         [
@@ -193,7 +242,11 @@ const main = async () => {
     ].filter(([, entry]) => entry !== undefined));
     const parsed = HqRequestSchema.safeParse(payload);
     if (!parsed.success)
-        throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' }, { cause: parsed.error });
+        throw new Exception('The HQ request is invalid', {
+            code: 'JG_AGENT_HQ_REQUEST_INVALID',
+            data: { kind: 'invalid-request' },
+            cause: parsed.error,
+        });
     const command = parsed.data;
     const response = await requestAgentHq(stateRoot, command);
     if (response.kind === 'stop') {
@@ -203,12 +256,15 @@ const main = async () => {
             try {
                 const { owner } = await readRuntimeOwner(stateRoot);
                 if (owner.nonce !== response.result.runtimeEpoch)
-                    throw new Exception('The HQ runtime owner is unverifiable', undefined, {
-                        kind: 'state-conflict',
+                    throw new Exception('The HQ runtime owner is unverifiable', {
+                        code: 'JG_AGENT_HQ_RUNTIME_OWNER_UNVERIFIABLE',
+                        data: {
+                            kind: 'state-conflict',
+                        },
                     });
             }
             catch (error) {
-                if (error instanceof Exception && hasErrorCode(error.cause, 'ENOENT')) {
+                if (isException(error) && hasErrorCode(error.cause, 'ENOENT')) {
                     stopped = true;
                     break;
                 }
@@ -217,7 +273,10 @@ const main = async () => {
             await wait(100);
         }
         if (!stopped)
-            throw new Exception('The HQ transport failed', undefined, { kind: 'state-conflict' });
+            throw new Exception('The HQ transport failed', {
+                code: 'JG_AGENT_HQ_TRANSPORT_FAILED',
+                data: { kind: 'state-conflict' },
+            });
         process.stdout.write(`${JSON.stringify({ schemaVersion: 1, kind: 'stop', result: { state: 'stopped', runtimeEpoch: response.result.runtimeEpoch } })}\n`);
     }
     else

package/dist/contracts/constants.d.ts

@@ -1,5 +1,14 @@
 export declare const DEFAULT_PAGE_SIZE = 32;
 export declare const MAX_PAGE_SIZE = 128;
+export declare const PUBLIC_ERROR_CODES: {
+    readonly 'invalid-request': "JG_AGENT_HQ_CLIENT_INVALID_REQUEST";
+    readonly 'authentication-required': "JG_AGENT_HQ_CLIENT_AUTHENTICATION_REQUIRED";
+    readonly 'access-denied': "JG_AGENT_HQ_CLIENT_ACCESS_DENIED";
+    readonly 'not-found': "JG_AGENT_HQ_CLIENT_NOT_FOUND";
+    readonly 'state-conflict': "JG_AGENT_HQ_CLIENT_STATE_CONFLICT";
+    readonly 'agent-unavailable': "JG_AGENT_HQ_CLIENT_AGENT_UNAVAILABLE";
+    readonly 'operation-failed': "JG_AGENT_HQ_CLIENT_OPERATION_FAILED";
+};
 export declare const PUBLIC_ERROR_MESSAGES: {
     readonly 'invalid-request': "Request is invalid.";
     readonly 'authentication-required': "Sign in to continue.";

package/dist/contracts/constants.js

@@ -1,6 +1,16 @@
 // trusted-boundary page sizes for growing collections
 export const DEFAULT_PAGE_SIZE = 32;
 export const MAX_PAGE_SIZE = 128;
+// stable client codes for failures translated at IPC and browser boundaries
+export const PUBLIC_ERROR_CODES = {
+    'invalid-request': 'JG_AGENT_HQ_CLIENT_INVALID_REQUEST',
+    'authentication-required': 'JG_AGENT_HQ_CLIENT_AUTHENTICATION_REQUIRED',
+    'access-denied': 'JG_AGENT_HQ_CLIENT_ACCESS_DENIED',
+    'not-found': 'JG_AGENT_HQ_CLIENT_NOT_FOUND',
+    'state-conflict': 'JG_AGENT_HQ_CLIENT_STATE_CONFLICT',
+    'agent-unavailable': 'JG_AGENT_HQ_CLIENT_AGENT_UNAVAILABLE',
+    'operation-failed': 'JG_AGENT_HQ_CLIENT_OPERATION_FAILED',
+};
 // safe messages at IPC and browser boundaries
 export const PUBLIC_ERROR_MESSAGES = {
     'invalid-request': 'Request is invalid.',