jg-agent-hq 0.5.2 → 1.0.0

package/dist/handoffs/handoffs.js

@@ -1,7 +1,7 @@
 import { execFile } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { promisify } from 'node:util';
-import { Exception, extractMessage } from 'error-message-utils';
+import { Exception, extractMessage } from 'jg-exception';
 import { z } from 'zod';
 import { HandoffPreviewSchema, } from '../contracts/index.js';
 import { resolveWorkspaceTarget } from '../runtime/state/index.js';
@@ -10,8 +10,11 @@ import { hashHandoff, handoffArguments, handoffDelivery } from './utilities.js';
 const run = promisify(execFile);
 const PositionSchema = z.strictObject({ createdAt: z.number().int(), id: z.uuid() });
 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',
+        },
     });
 };
 /**
@@ -23,7 +26,7 @@ export const createHandoffs = (store, actions, skills, plans, readHistory, roots
      * Checks selected Git attribution without staging files or traversing history.
      * @returns Whether the selected commit is still HEAD; omitted attribution requires no Git read.
      * @throws
-     * - -1: The HQ handoff operation failed
+     * - JG_AGENT_HQ_HANDOFF_FAILED: The HQ handoff operation failed
      */
     const checkCommit = async (directory, expected) => {
         if (!expected)
@@ -38,21 +41,28 @@ export const createHandoffs = (store, actions, skills, plans, readHistory, roots
             return result.stdout.trim() === expected;
         }
         catch (cause) {
-            throw new Exception(`The HQ handoff operation failed: ${extractMessage(cause)}`, undefined, { kind: 'operation-failed' }, { cause });
+            throw new Exception(`The HQ handoff operation failed: ${extractMessage(cause)}`, {
+                code: 'JG_AGENT_HQ_HANDOFF_FAILED',
+                data: { kind: 'operation-failed' },
+                cause,
+            });
         }
     };
     /**
      * Reads and authorizes a selected record before exposing its retained evidence.
      * @returns The bounded persisted handoff.
      * @throws
-     * - -1: The HQ handoff is unavailable
-     * - -1: The HQ target is outside the allowed workspaces
-     * - -1: The HQ store failed
+     * - JG_AGENT_HQ_HANDOFF_UNAVAILABLE: The HQ handoff is unavailable
+     * - JG_AGENT_HQ_TARGET_FORBIDDEN: The HQ target is outside the allowed workspaces
+     * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
      */
     const selected = async (id) => {
         const record = await store.getHandoff(id);
         if (!record)
-            throw new Exception('The HQ handoff is unavailable', undefined, { kind: 'not-found' });
+            throw new Exception('The HQ handoff is unavailable', {
+                code: 'JG_AGENT_HQ_HANDOFF_UNAVAILABLE',
+                data: { kind: 'not-found' },
+            });
         await resolveWorkspaceTarget(record.source.workspaceRoot, roots);
         return record;
     };
@@ -60,7 +70,7 @@ export const createHandoffs = (store, actions, skills, plans, readHistory, roots
      * Resolves the original native creation receipt; discovery never creates another controller.
      * @returns The current control record, or null before creation admission.
      * @throws
-     * - -1: The HQ store failed
+     * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
      */
     const target = async (record) => {
         const creation = await store.getAction(record.creation.id);
@@ -70,7 +80,7 @@ export const createHandoffs = (store, actions, skills, plans, readHistory, roots
      * Projects delivery from the action ledger, with no mirrored acknowledgement state.
      * @returns Selected findings and current native receipts, preserving the original reviewer identity.
      * @throws
-     * - -1: The HQ store failed
+     * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
      */
     const show = async (record) => {
         const [creation, reviewDispatch, feedbackDispatch] = await Promise.all([
@@ -103,24 +113,24 @@ export const createHandoffs = (store, actions, skills, plans, readHistory, roots
      * Checks that feedback still concerns the selected repository and execution contracts.
      * @returns Whether source identity, selected commit and current contracts still match.
      * @throws
-     * - -1: The HQ handoff operation failed
-     * - -1: The HQ store failed
-     * - -1: The HQ target is outside the allowed workspaces
-     * - -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_FAILED: The HQ handoff operation failed
+     * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
+     * - JG_AGENT_HQ_TARGET_FORBIDDEN: The HQ target is outside the allowed workspaces
+     * - 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
      */
     const isSourceCurrent = async (record) => {
         const source = await store.getThread(record.source.threadId);
@@ -147,25 +157,25 @@ export const createHandoffs = (store, actions, skills, plans, readHistory, roots
      * Resolves native skill metadata and exact invocation text without sending it.
      * @returns A digest-bound preview with explicit unavailable states.
      * @throws
-     * - -1: The HQ handoff operation failed
-     * - -1: The HQ action conflicts with its recorded state
-     * - -1: The HQ store failed
-     * - -1: The HQ target is outside the allowed workspaces
-     * - -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_FAILED: The HQ handoff operation failed
+     * - JG_AGENT_HQ_ACTION_CONFLICT: The HQ action conflicts with its recorded state
+     * - JG_AGENT_HQ_STORE_FAILED: The HQ store failed
+     * - JG_AGENT_HQ_TARGET_FORBIDDEN: The HQ target is outside the allowed workspaces
+     * - 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
      */
     const preview = async (record, phase) => {
         const reviewer = await target(record);
@@ -226,31 +236,31 @@ export const createHandoffs = (store, actions, skills, plans, readHistory, roots
          * 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
          */
         async handle(command) {
             if (command.kind === 'list') {
@@ -264,14 +274,20 @@ export const createHandoffs = (store, actions, skills, plans, readHistory, roots
                         value = JSON.parse(continuation);
                     }
                     catch {
-                        throw new Exception('The HQ cursor does not match this request', undefined, {
-                            kind: 'invalid-request',
+                        throw new Exception('The HQ cursor does not match this request', {
+                            code: 'JG_AGENT_HQ_CURSOR_INVALID',
+                            data: {
+                                kind: 'invalid-request',
+                            },
                         });
                     }
                     const parsed = PositionSchema.safeParse(value);
                     if (!parsed.success)
-                        throw new Exception('The HQ cursor does not match this request', undefined, {
-                            kind: 'invalid-request',
+                        throw new Exception('The HQ cursor does not match this request', {
+                            code: 'JG_AGENT_HQ_CURSOR_INVALID',
+                            data: {
+                                kind: 'invalid-request',
+                            },
                         });
                     after = parsed.data;
                 }

package/dist/ipc/client.d.ts

@@ -3,18 +3,18 @@ import { type IHqRequestInput, type IHqResponse } from '../contracts/index.js';
  * Runs one validated local command and closes only its client connection.
  * @returns The matching normalized response; stopping requires subsequent shutdown confirmation.
  * @throws
- * - -1: The HQ request is invalid
- * - -1: The HQ state directory is unsafe
- * - -1: The HQ state file is unsafe
- * - -1: The HQ runtime owner is unverifiable
- * - -1: The HQ runtime is not running
- * - -1: The HQ transport failed
- * - -1: Request is invalid.
- * - -1: Sign in to continue.
- * - -1: Access is denied.
- * - -1: Requested resource was not found.
- * - -1: State changed. Refresh before continuing.
- * - -1: Coding agent is unavailable.
- * - -1: Operation could not be completed.
+ * - JG_AGENT_HQ_REQUEST_INVALID: The HQ request is invalid
+ * - JG_AGENT_HQ_STATE_DIRECTORY_UNSAFE: The HQ state directory is unsafe
+ * - JG_AGENT_HQ_STATE_FILE_UNSAFE: The HQ state file is unsafe
+ * - JG_AGENT_HQ_RUNTIME_OWNER_UNVERIFIABLE: The HQ runtime owner is unverifiable
+ * - JG_AGENT_HQ_RUNTIME_NOT_RUNNING: The HQ runtime is not running
+ * - JG_AGENT_HQ_TRANSPORT_FAILED: The HQ transport failed
+ * - JG_AGENT_HQ_CLIENT_INVALID_REQUEST: Request is invalid.
+ * - JG_AGENT_HQ_CLIENT_AUTHENTICATION_REQUIRED: Sign in to continue.
+ * - JG_AGENT_HQ_CLIENT_ACCESS_DENIED: Access is denied.
+ * - JG_AGENT_HQ_CLIENT_NOT_FOUND: Requested resource was not found.
+ * - JG_AGENT_HQ_CLIENT_STATE_CONFLICT: State changed. Refresh before continuing.
+ * - JG_AGENT_HQ_CLIENT_AGENT_UNAVAILABLE: Coding agent is unavailable.
+ * - JG_AGENT_HQ_CLIENT_OPERATION_FAILED: Operation could not be completed.
  */
 export declare const requestAgentHq: (stateRoot: string, command: IHqRequestInput) => Promise<IHqResponse>;

package/dist/ipc/client.js

@@ -2,8 +2,8 @@ import { randomUUID } from 'node:crypto';
 import { lstat } from 'node:fs/promises';
 import { createConnection } from 'node:net';
 import { isAbsolute, join } from 'node:path';
-import { Exception, extractMessage } from 'error-message-utils';
-import { HqRequestSchema, IpcResponseSchema, PUBLIC_ERROR_MESSAGES, } from '../contracts/index.js';
+import { Exception, extractMessage } from 'jg-exception';
+import { HqRequestSchema, IpcResponseSchema, PUBLIC_ERROR_CODES, PUBLIC_ERROR_MESSAGES, } from '../contracts/index.js';
 import { isPrivateOwner } from '../locks/index.js';
 import { readRuntimeOwner } from '../runtime/state/index.js';
 import { CONTROL_SOCKET, IPC_TIMEOUT_MS, MAX_FRAME_BYTES, MAX_REQUEST_BYTES } from './constants.js';
@@ -12,53 +12,78 @@ import { createLineDecoder } from './framing.js';
  * Runs one validated local command and closes only its client connection.
  * @returns The matching normalized response; stopping requires subsequent shutdown confirmation.
  * @throws
- * - -1: The HQ request is invalid
- * - -1: The HQ state directory is unsafe
- * - -1: The HQ state file is unsafe
- * - -1: The HQ runtime owner is unverifiable
- * - -1: The HQ runtime is not running
- * - -1: The HQ transport failed
- * - -1: Request is invalid.
- * - -1: Sign in to continue.
- * - -1: Access is denied.
- * - -1: Requested resource was not found.
- * - -1: State changed. Refresh before continuing.
- * - -1: Coding agent is unavailable.
- * - -1: Operation could not be completed.
+ * - JG_AGENT_HQ_REQUEST_INVALID: The HQ request is invalid
+ * - JG_AGENT_HQ_STATE_DIRECTORY_UNSAFE: The HQ state directory is unsafe
+ * - JG_AGENT_HQ_STATE_FILE_UNSAFE: The HQ state file is unsafe
+ * - JG_AGENT_HQ_RUNTIME_OWNER_UNVERIFIABLE: The HQ runtime owner is unverifiable
+ * - JG_AGENT_HQ_RUNTIME_NOT_RUNNING: The HQ runtime is not running
+ * - JG_AGENT_HQ_TRANSPORT_FAILED: The HQ transport failed
+ * - JG_AGENT_HQ_CLIENT_INVALID_REQUEST: Request is invalid.
+ * - JG_AGENT_HQ_CLIENT_AUTHENTICATION_REQUIRED: Sign in to continue.
+ * - JG_AGENT_HQ_CLIENT_ACCESS_DENIED: Access is denied.
+ * - JG_AGENT_HQ_CLIENT_NOT_FOUND: Requested resource was not found.
+ * - JG_AGENT_HQ_CLIENT_STATE_CONFLICT: State changed. Refresh before continuing.
+ * - JG_AGENT_HQ_CLIENT_AGENT_UNAVAILABLE: Coding agent is unavailable.
+ * - JG_AGENT_HQ_CLIENT_OPERATION_FAILED: Operation could not be completed.
  */
 export const requestAgentHq = async (stateRoot, command) => {
     const input = HqRequestSchema.safeParse(command);
     if (!input.success || !isAbsolute(stateRoot))
-        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 { owner } = await readRuntimeOwner(stateRoot);
     const path = join(stateRoot, CONTROL_SOCKET);
     const socketDetails = await lstat(path);
     if (!socketDetails.isSocket() || socketDetails.isSymbolicLink() || !isPrivateOwner(socketDetails))
-        throw new Exception('The HQ state file is unsafe', undefined, { kind: 'state-conflict' });
+        throw new Exception('The HQ state file is unsafe', {
+            code: 'JG_AGENT_HQ_STATE_FILE_UNSAFE',
+            data: { kind: 'state-conflict' },
+        });
     const id = randomUUID();
     const content = `${JSON.stringify({ schemaVersion: 1, id, runtimeEpoch: owner.nonce, command: input.data })}\n`;
     if (Buffer.byteLength(content) > MAX_REQUEST_BYTES)
-        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 socket = createConnection(path);
     try {
         return await new Promise((resolve, reject) => {
-            socket.setTimeout(IPC_TIMEOUT_MS, () => reject(new Exception('The HQ transport failed', undefined, { kind: 'agent-unavailable' })));
-            socket.once('error', (cause) => reject(new Exception(`The HQ transport failed: ${extractMessage(cause)}`, undefined, { kind: 'agent-unavailable' }, { cause })));
+            socket.setTimeout(IPC_TIMEOUT_MS, () => reject(new Exception('The HQ transport failed', {
+                code: 'JG_AGENT_HQ_TRANSPORT_FAILED',
+                data: { kind: 'agent-unavailable' },
+            })));
+            socket.once('error', (cause) => reject(new Exception(`The HQ transport failed: ${extractMessage(cause)}`, {
+                code: 'JG_AGENT_HQ_TRANSPORT_FAILED',
+                data: { kind: 'agent-unavailable' },
+                cause,
+            })));
             let received = false;
             const decoder = createLineDecoder(MAX_FRAME_BYTES, (message) => {
                 const parsed = IpcResponseSchema.safeParse(message);
                 if (!parsed.success || parsed.data.id !== id)
-                    throw new Exception('The HQ transport failed', undefined, { kind: 'agent-unavailable' });
+                    throw new Exception('The HQ transport failed', {
+                        code: 'JG_AGENT_HQ_TRANSPORT_FAILED',
+                        data: { kind: 'agent-unavailable' },
+                    });
                 received = true;
                 const response = parsed.data;
                 if (!response.success) {
-                    reject(new Exception(PUBLIC_ERROR_MESSAGES[response.error.kind], undefined, {
-                        kind: response.error.kind,
+                    reject(new Exception(PUBLIC_ERROR_MESSAGES[response.error.kind], {
+                        code: PUBLIC_ERROR_CODES[response.error.kind],
+                        data: {
+                            kind: response.error.kind,
+                        },
                     }));
                     return;
                 }
                 if (response.response.kind !== input.data.kind)
-                    throw new Exception('The HQ transport failed', undefined, { kind: 'agent-unavailable' });
+                    throw new Exception('The HQ transport failed', {
+                        code: 'JG_AGENT_HQ_TRANSPORT_FAILED',
+                        data: { kind: 'agent-unavailable' },
+                    });
                 resolve(response.response);
             });
             socket.on('data', (chunk) => {
@@ -73,7 +98,10 @@ export const requestAgentHq = async (stateRoot, command) => {
                 try {
                     decoder.end();
                     if (!received)
-                        reject(new Exception('The HQ transport failed', undefined, { kind: 'agent-unavailable' }));
+                        reject(new Exception('The HQ transport failed', {
+                            code: 'JG_AGENT_HQ_TRANSPORT_FAILED',
+                            data: { kind: 'agent-unavailable' },
+                        }));
                 }
                 catch (error) {
                     reject(error);

package/dist/ipc/framing.d.ts

@@ -4,7 +4,7 @@
  * @param receive The owner of each decoded message.
  * @returns A decoder whose end operation rejects incomplete tails.
  * @throws
- * - -1: The HQ transport failed
+ * - JG_AGENT_HQ_TRANSPORT_FAILED: The HQ transport failed
  */
 export declare const createLineDecoder: (maxBytes: number, receive: (message: unknown) => void) => {
     push(chunk: Buffer): void;

package/dist/ipc/framing.js

@@ -1,11 +1,11 @@
-import { Exception } from 'error-message-utils';
+import { Exception } from 'jg-exception';
 /**
  * Decodes bounded JSON lines with amortized linear copying across fragmented input.
  * @param maxBytes Maximum bytes in one JSON frame.
  * @param receive The owner of each decoded message.
  * @returns A decoder whose end operation rejects incomplete tails.
  * @throws
- * - -1: The HQ transport failed
+ * - JG_AGENT_HQ_TRANSPORT_FAILED: The HQ transport failed
  */
 export const createLineDecoder = (maxBytes, receive) => {
     let buffer = Buffer.alloc(Math.min(1024, maxBytes));
@@ -19,7 +19,10 @@ export const createLineDecoder = (maxBytes, receive) => {
                 const end = newline < 0 ? chunk.length : newline;
                 const length = end - offset;
                 if (used + length > maxBytes)
-                    throw new Exception('The HQ transport failed', undefined, { kind: 'invalid-request' });
+                    throw new Exception('The HQ transport failed', {
+                        code: 'JG_AGENT_HQ_TRANSPORT_FAILED',
+                        data: { kind: 'invalid-request' },
+                    });
                 if (used + length > buffer.length) {
                     const expanded = Buffer.alloc(Math.min(maxBytes, Math.max(buffer.length * 2, used + length)));
                     buffer.copy(expanded, 0, 0, used);
@@ -33,7 +36,11 @@ export const createLineDecoder = (maxBytes, receive) => {
                         message = JSON.parse(decoder.decode(buffer.subarray(0, used)));
                     }
                     catch (cause) {
-                        throw new Exception('The HQ transport failed', undefined, { kind: 'invalid-request' }, { cause });
+                        throw new Exception('The HQ transport failed', {
+                            code: 'JG_AGENT_HQ_TRANSPORT_FAILED',
+                            data: { kind: 'invalid-request' },
+                            cause,
+                        });
                     }
                     used = 0;
                     receive(message);
@@ -43,7 +50,10 @@ export const createLineDecoder = (maxBytes, receive) => {
         },
         end() {
             if (used)
-                throw new Exception('The HQ transport failed', undefined, { kind: 'invalid-request' });
+                throw new Exception('The HQ transport failed', {
+                    code: 'JG_AGENT_HQ_TRANSPORT_FAILED',
+                    data: { kind: 'invalid-request' },
+                });
         },
     };
 };

package/dist/ipc/server.d.ts

@@ -3,7 +3,7 @@ import { type IHqRequest, type IHqResponse } from '../contracts/index.js';
  * Serves closed HQ commands over an owner-only Unix socket. Disconnects do not own host lifetime.
  * @returns An owned server with deterministic connection teardown.
  * @throws
- * - -1: The HQ transport failed
+ * - JG_AGENT_HQ_TRANSPORT_FAILED: The HQ transport failed
  */
 export declare const createIpcServer: (path: string, runtimeEpoch: string, handle: (command: IHqRequest) => Promise<IHqResponse>) => Promise<{
     readonly isAvailable: boolean;

package/dist/ipc/server.js

@@ -1,7 +1,7 @@
 import { createServer } from 'node:net';
 import { chmod } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
-import { Exception, extractMessage } from 'error-message-utils';
+import { Exception, extractMessage } from 'jg-exception';
 import { HqResponseSchema, IpcRequestSchema, PUBLIC_ERROR_MESSAGES, } from '../contracts/index.js';
 import { toPublicError } from '../errors/index.js';
 import { IPC_TIMEOUT_MS, MAX_CONNECTIONS, MAX_FRAME_BYTES, MAX_REQUEST_BYTES, } from './constants.js';
@@ -10,7 +10,7 @@ import { createLineDecoder } from './framing.js';
  * Serves closed HQ commands over an owner-only Unix socket. Disconnects do not own host lifetime.
  * @returns An owned server with deterministic connection teardown.
  * @throws
- * - -1: The HQ transport failed
+ * - JG_AGENT_HQ_TRANSPORT_FAILED: The HQ transport failed
  */
 export const createIpcServer = async (path, runtimeEpoch, handle) => {
     const sockets = new Set();
@@ -36,14 +36,24 @@ export const createIpcServer = async (path, runtimeEpoch, handle) => {
             const id = input.success ? input.data.id : randomUUID();
             try {
                 if (!input.success)
-                    throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' }, { cause: input.error });
+                    throw new Exception('The HQ request is invalid', {
+                        code: 'JG_AGENT_HQ_REQUEST_INVALID',
+                        data: { kind: 'invalid-request' },
+                        cause: input.error,
+                    });
                 if (input.data.runtimeEpoch !== 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',
+                        },
                     });
                 const response = HqResponseSchema.safeParse(await handle(input.data.command));
                 if (!response.success || response.data.kind !== input.data.command.kind)
-                    throw new Exception('The HQ transport failed', undefined, { kind: 'operation-failed' });
+                    throw new Exception('The HQ transport failed', {
+                        code: 'JG_AGENT_HQ_TRANSPORT_FAILED',
+                        data: { kind: 'operation-failed' },
+                    });
                 send({ schemaVersion: 1, id, success: true, response: response.data });
             }
             catch (error) {
@@ -90,7 +100,11 @@ export const createIpcServer = async (path, runtimeEpoch, handle) => {
             socket.destroy();
         if (server.listening)
             await new Promise((resolve) => server.close(() => resolve()));
-        throw new Exception(`The HQ transport failed: ${extractMessage(cause)}`, undefined, { kind: 'operation-failed' }, { cause });
+        throw new Exception(`The HQ transport failed: ${extractMessage(cause)}`, {
+            code: 'JG_AGENT_HQ_TRANSPORT_FAILED',
+            data: { kind: 'operation-failed' },
+            cause,
+        });
     }
     let closing;
     return {
@@ -101,7 +115,11 @@ export const createIpcServer = async (path, runtimeEpoch, handle) => {
             for (const socket of sockets)
                 socket.destroy();
             server.close((error) => error
-                ? reject(new Exception(`The HQ transport failed: ${extractMessage(error)}`, undefined, { kind: 'operation-failed' }, { cause: error }))
+                ? reject(new Exception(`The HQ transport failed: ${extractMessage(error)}`, {
+                    code: 'JG_AGENT_HQ_TRANSPORT_FAILED',
+                    data: { kind: 'operation-failed' },
+                    cause: error,
+                }))
                 : resolve());
         })),
     };