jg-agent-hq 0.5.2 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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.

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.

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.

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 {

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.',

package/dist/contracts/index.d.ts

@@ -1,4 +1,4 @@
-export { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, PUBLIC_ERROR_MESSAGES } from './constants.js';
+export { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, PUBLIC_ERROR_CODES, PUBLIC_ERROR_MESSAGES, } from './constants.js';
 export { HqRequestSchema, ThreadSummarySchema, TurnSummarySchema, HistoryItemSchema, LiveItemsSchema, UsageWindowSchema, UsageSnapshotSchema, RuntimeStatusSchema, HqResponseSchema, ErrorKindSchema, IpcRequestSchema, IpcResponseSchema, } from './types.js';
 export type { IHqRequest, IHqRequestInput, IThreadSummary, ITurnSummary, IHistoryItem, IUsageSnapshot, IRuntimeStatus, IHqResponse, IErrorKind, IIpcResponse, } from './types.js';
 export { ActionCommandSchema, ActionEnvelopeSchema, ActionReceiptSchema, ActionSummarySchema, ManagedThreadSchema, NativeApprovalSchema, LifecycleEventSchema, } from './actions/index.js';

package/dist/contracts/index.js

@@ -1,5 +1,5 @@
 // constants
-export { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, PUBLIC_ERROR_MESSAGES } from './constants.js';
+export { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, PUBLIC_ERROR_CODES, PUBLIC_ERROR_MESSAGES, } from './constants.js';
 // wire contracts
 export { HqRequestSchema, ThreadSummarySchema, TurnSummarySchema, HistoryItemSchema, LiveItemsSchema, UsageWindowSchema, UsageSnapshotSchema, RuntimeStatusSchema, HqResponseSchema, ErrorKindSchema, IpcRequestSchema, IpcResponseSchema, } from './types.js';
 // managed control and durable delivery

package/dist/errors/utilities.js

@@ -1,10 +1,10 @@
-import { Exception } from 'error-message-utils';
+import { isException } from 'jg-exception';
 import { z } from 'zod';
 import { ErrorKindSchema, PUBLIC_ERROR_MESSAGES } from '../contracts/index.js';
 const ErrorMetadataSchema = z.object({ kind: ErrorKindSchema });
 /** Reads only the supported classification from an application exception. */
 export const getErrorKind = (error) => {
-    const metadata = ErrorMetadataSchema.safeParse(error instanceof Exception ? error.data : null);
+    const metadata = ErrorMetadataSchema.safeParse(isException(error) ? error.data : null);
     return metadata.success ? metadata.data.kind : 'operation-failed';
 };
 /** Maps recognized classifications to static client-safe messages. */

package/dist/handoffs/handoffs.d.ts

@@ -13,31 +13,31 @@ export declare const createHandoffs: (store: IStore, actions: ReturnType<typeof
      * Creates, previews, explicitly sends or collects one handoff without an automatic reply loop.
      * @returns A bounded handoff, native invocation preview or seek page.
      * @throws
-     * - -1: The HQ handoff is unavailable
-     * - -1: The HQ handoff operation failed
-     * - -1: The HQ action conflicts with its recorded state
-     * - -1: The HQ skill is unavailable
-     * - -1: The HQ target is outside the allowed workspaces
-     * - -1: The HQ cursor does not match this request
-     * - -1: The HQ store failed
-     * - -1: The Codex integration failed
-     * - -1: The Claude integration failed
-     * - -1: The Claude history is unavailable
-     * - -1: The HQ plan is invalid
-     * - -1: The HQ plan operation failed
-     * - -1: The HQ lock acquisition arguments are invalid
-     * - -1: The HQ lock requires Linux or macOS
-     * - -1: The HQ runtime directory must be a real directory
-     * - -1: The HQ runtime directory must be private and owned by the current user
-     * - -1: The HQ lock must be a regular file
-     * - -1: The HQ lock must be private and owned by the current user
-     * - -1: The HQ lock owner exceeds the supported size
-     * - -1: The HQ lock owner could not be read. Inspect .runtime/hq.lock
-     * - -1: The HQ lock owner is incomplete. Inspect .runtime/hq.lock and remove it only after its owner stopped
-     * - -1: The HQ lock has an inactive owner
-     * - -1: The HQ lock owner could not be verified
-     * - -1: Timed out waiting for the HQ lock
-     * - -1: HQ lock ownership changed before release
+     * - JG_AGENT_HQ_HANDOFF_UNAVAILABLE: The HQ handoff is unavailable
+     * - JG_AGENT_HQ_HANDOFF_FAILED: The HQ handoff operation 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_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_STORE_FAILED: 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_CLAUDE_HISTORY_UNAVAILABLE: The Claude history is unavailable
+     * - JG_AGENT_HQ_PLAN_INVALID: The HQ plan is invalid
+     * - JG_AGENT_HQ_PLAN_FAILED: The HQ plan operation failed
+     * - JG_AGENT_HQ_LOCK_INVALID_ARGUMENTS: The HQ lock acquisition arguments are invalid
+     * - JG_AGENT_HQ_LOCK_UNSUPPORTED_PLATFORM: The HQ lock requires Linux or macOS
+     * - JG_AGENT_HQ_RUNTIME_DIRECTORY_INVALID: The HQ runtime directory must be a real directory
+     * - JG_AGENT_HQ_RUNTIME_DIRECTORY_PERMISSIONS: The HQ runtime directory must be private and owned by the current user
+     * - JG_AGENT_HQ_LOCK_FILE_INVALID: The HQ lock must be a regular file
+     * - JG_AGENT_HQ_LOCK_FILE_PERMISSIONS: The HQ lock must be private and owned by the current user
+     * - JG_AGENT_HQ_LOCK_OWNER_OVERSIZED: The HQ lock owner exceeds the supported size
+     * - JG_AGENT_HQ_LOCK_OWNER_UNREADABLE: The HQ lock owner could not be read. Inspect .runtime/hq.lock
+     * - JG_AGENT_HQ_LOCK_OWNER_INCOMPLETE: The HQ lock owner is incomplete. Inspect .runtime/hq.lock and remove it only after its owner stopped
+     * - JG_AGENT_HQ_LOCK_OWNER_INACTIVE: The HQ lock has an inactive owner
+     * - JG_AGENT_HQ_LOCK_OWNER_UNVERIFIABLE: The HQ lock owner could not be verified
+     * - JG_AGENT_HQ_LOCK_TIMEOUT: Timed out waiting for the HQ lock
+     * - JG_AGENT_HQ_LOCK_OWNERSHIP_CHANGED: HQ lock ownership changed before release
      */
     handle(command: IHandoffCommand): Promise<IHandoffResult>;
 };