jg-agent-hq 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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.
+
+## 0.5.0
+
+- Add safe publication observations for the host's System view, with separate pending, blocked, failed and uncertain states, timestamps and exact commit identity.
+- Bind publication retries to a receipt UUID and nullable expected commit, including failures that happened before a commit existed. The host continues to own scheduling, Git operations and storage.
+
 ## 0.4.0
 
 - Add closed browser host commands and bounded session/repository/plan read contracts, without exposing private handlers through standalone IPC.

package/README.md

@@ -39,9 +39,9 @@ The Node API exposes `createAgentHq({ stateRoot, allowedRoots })` and `requestAg
 
 The controller owns its SQLite worker and native connections independently of client connections. Private state contains the lifetime owner, Unix socket and SQLite discovery metadata. Conversation bodies remain in the native providers' storage. Browsing never resumes an external session or starts inference. Quota windows come from native account observations, with explicit stale and unavailable states.
 
-The current read contracts were exercised against Codex 0.163.0 and Claude Code 2.1.304 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.
+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 supports the qualified 2.1.304 format only, 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 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).
 
 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.
 

package/api/README.md

@@ -48,7 +48,7 @@ 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. Both CLI and versioned transcript records must match 2.1.304. 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 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.
 
 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.
 
@@ -100,7 +100,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 exact-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. 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.
 
@@ -266,6 +266,8 @@ SQLite records an HMAC digest and receipt before invoking the dispatcher. The sa
 
 The dispatcher receives a server-owned `nativeActionId`; use this ID for a native child action, preserving the validated runtime and command. `readBrowserAction(id, operatorId)` returns only that operator's receipt and joins its exact native receipt. Host acknowledgement means the handler completed, not that a native turn completed. An unknown or differently owned ID returns null. Receipts retain metadata rather than message bodies or arbitrary handler output. Subsequent domain reads provide the result. At most 32 host jobs are admitted concurrently. Runtime close rejects new host work and waits for admitted work before closing its worker.
 
+`PublicationStatusSchema` is a browser-safe observation supplied by the host, independent of native execution and quota states. It contains the receipt UUID, state/reason, due/attempt/success timestamps, nullable pending and published commit hashes, and bounded queued/selected file counts. It contains no artifact bodies, paths, credentials or deployment configuration. `publication-retry` requires `publicationId` and `expectedCommit` (null before a commit exists). The host must compare both against its current receipt before acting and reconcile or retry only its recorded verified commit. The public runtime supplies no Git publisher, service installer or publication storage.
+
 Live reads accept `afterRevision`. A matching revision returns `unchanged: true` with an empty data array; retain the displayed window. A changed revision returns the complete bounded window. Revisions belong to one runtime. After reconnect to a new runtime, discard the revision and refresh native history. Token bodies stay in the existing bounded memory window and are never copied into lifecycle or browser-action tables.
 
 `thread-plan` accepts a managed `threadId` and returns its nullable `ActionPlanContextSchema`. The host verifies the thread's registered checkout before exposing it. It is read-only and grants no execution authority.

package/dist/contracts/browser/index.d.ts

@@ -1,4 +1,5 @@
 export { BrowserCommandSchema, BrowserActionSchema, BrowserReceiptSchema } from './types.js';
 export type { IBrowserAction, IBrowserReceipt } from './types.js';
 export { BrowserRepositorySchema, BrowserPlanSummarySchema, BrowserPlanPageSchema, BrowserPlanDetailSchema, BrowserSessionSchema, } from './types.js';
-export { BrowserRepositoryPageSchema, BrowserSystemSchema, BrowserThreadDetailSchema, } from './types.js';
+export { BrowserRepositoryPageSchema, BrowserSystemSchema, BrowserThreadDetailSchema, PublicationStatusSchema, } from './types.js';
+export type { IPublicationStatus } from './types.js';

package/dist/contracts/browser/index.js

@@ -3,4 +3,4 @@ export { BrowserCommandSchema, BrowserActionSchema, BrowserReceiptSchema } from
 // host read models
 export { BrowserRepositorySchema, BrowserPlanSummarySchema, BrowserPlanPageSchema, BrowserPlanDetailSchema, BrowserSessionSchema, } from './types.js';
 // bounded host views
-export { BrowserRepositoryPageSchema, BrowserSystemSchema, BrowserThreadDetailSchema, } from './types.js';
+export { BrowserRepositoryPageSchema, BrowserSystemSchema, BrowserThreadDetailSchema, PublicationStatusSchema, } from './types.js';

package/dist/contracts/browser/types.d.ts

@@ -479,7 +479,8 @@ export declare const BrowserCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     release: z.ZodBoolean;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"publication-retry">;
-    expectedCommit: z.ZodString;
+    publicationId: z.ZodUUID;
+    expectedCommit: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>], "kind">;
 export declare const BrowserActionSchema: z.ZodObject<{
     id: z.ZodUUID;
@@ -964,7 +965,8 @@ export declare const BrowserActionSchema: z.ZodObject<{
         release: z.ZodBoolean;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"publication-retry">;
-        expectedCommit: z.ZodString;
+        publicationId: z.ZodUUID;
+        expectedCommit: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>], "kind">;
 }, z.core.$strict>;
 export type IBrowserAction = z.infer<typeof BrowserActionSchema>;
@@ -2244,6 +2246,43 @@ export declare const BrowserRepositoryPageSchema: z.ZodObject<{
     }, z.core.$strip>>;
     nextCursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
+export declare const PublicationStatusSchema: z.ZodObject<{
+    id: z.ZodNullable<z.ZodUUID>;
+    state: z.ZodEnum<{
+        pending: "pending";
+        blocked: "blocked";
+        uncertain: "uncertain";
+        failed: "failed";
+        idle: "idle";
+        publishing: "publishing";
+        published: "published";
+    }>;
+    reason: z.ZodNullable<z.ZodEnum<{
+        owner: "owner";
+        editing: "editing";
+        clean: "clean";
+        enrolled: "enrolled";
+        changed: "changed";
+        git: "git";
+        signing: "signing";
+        verification: "verification";
+        transport: "transport";
+        rejected: "rejected";
+        "remote-changed": "remote-changed";
+        unpublished: "unpublished";
+        staged: "staged";
+        configuration: "configuration";
+        cleanup: "cleanup";
+    }>>;
+    dueAt: z.ZodNumber;
+    attemptedAt: z.ZodNullable<z.ZodNumber>;
+    succeededAt: z.ZodNullable<z.ZodNumber>;
+    commit: z.ZodNullable<z.ZodString>;
+    publishedCommit: z.ZodNullable<z.ZodString>;
+    queuedFiles: z.ZodNumber;
+    selectedFiles: z.ZodNumber;
+}, z.core.$strip>;
+export type IPublicationStatus = z.infer<typeof PublicationStatusSchema>;
 export declare const BrowserSystemSchema: z.ZodObject<{
     runtime: z.ZodObject<{
         runtimeEpoch: z.ZodUUID;
@@ -2272,7 +2311,40 @@ export declare const BrowserSystemSchema: z.ZodObject<{
         }, z.core.$strip>;
     }, z.core.$strip>;
     publication: z.ZodObject<{
-        state: z.ZodLiteral<"unavailable">;
+        id: z.ZodNullable<z.ZodUUID>;
+        state: z.ZodEnum<{
+            pending: "pending";
+            blocked: "blocked";
+            uncertain: "uncertain";
+            failed: "failed";
+            idle: "idle";
+            publishing: "publishing";
+            published: "published";
+        }>;
+        reason: z.ZodNullable<z.ZodEnum<{
+            owner: "owner";
+            editing: "editing";
+            clean: "clean";
+            enrolled: "enrolled";
+            changed: "changed";
+            git: "git";
+            signing: "signing";
+            verification: "verification";
+            transport: "transport";
+            rejected: "rejected";
+            "remote-changed": "remote-changed";
+            unpublished: "unpublished";
+            staged: "staged";
+            configuration: "configuration";
+            cleanup: "cleanup";
+        }>>;
+        dueAt: z.ZodNumber;
+        attemptedAt: z.ZodNullable<z.ZodNumber>;
+        succeededAt: z.ZodNullable<z.ZodNumber>;
+        commit: z.ZodNullable<z.ZodString>;
+        publishedCommit: z.ZodNullable<z.ZodString>;
+        queuedFiles: z.ZodNumber;
+        selectedFiles: z.ZodNumber;
     }, z.core.$strip>;
     resources: z.ZodObject<{
         state: z.ZodLiteral<"unavailable">;

package/dist/contracts/browser/types.js

@@ -24,7 +24,11 @@ export const BrowserCommandSchema = z.discriminatedUnion('kind', [
     }),
     z.strictObject({
         kind: z.literal('publication-retry'),
-        expectedCommit: z.string().regex(/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/),
+        publicationId: z.uuid(),
+        expectedCommit: z
+            .string()
+            .regex(/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/)
+            .nullable(),
     }),
 ]);
 export const BrowserActionSchema = z
@@ -91,9 +95,46 @@ export const BrowserRepositoryPageSchema = z.object({
     data: z.array(BrowserRepositorySchema).max(128),
     nextCursor: z.string().nullable(),
 });
+// publication state is independent of native execution, account quota and repository resources
+export const PublicationStatusSchema = z.object({
+    id: z.uuid().nullable(),
+    state: z.enum(['idle', 'pending', 'publishing', 'published', 'blocked', 'failed', 'uncertain']),
+    reason: z
+        .enum([
+        'clean',
+        'enrolled',
+        'editing',
+        'changed',
+        'git',
+        'signing',
+        'verification',
+        'transport',
+        'rejected',
+        'remote-changed',
+        'unpublished',
+        'staged',
+        'configuration',
+        'owner',
+        'cleanup',
+    ])
+        .nullable(),
+    dueAt: z.number().int().nonnegative(),
+    attemptedAt: z.number().int().nonnegative().nullable(),
+    succeededAt: z.number().int().nonnegative().nullable(),
+    commit: z
+        .string()
+        .regex(/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/)
+        .nullable(),
+    publishedCommit: z
+        .string()
+        .regex(/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/)
+        .nullable(),
+    queuedFiles: z.number().int().min(0).max(1024),
+    selectedFiles: z.number().int().min(0).max(1024),
+});
 export const BrowserSystemSchema = z.object({
     runtime: RuntimeStatusSchema,
-    publication: z.object({ state: z.literal('unavailable') }),
+    publication: PublicationStatusSchema,
     resources: z.object({ state: z.literal('unavailable') }),
     service: z.object({ state: z.literal('unavailable') }),
 });

package/dist/contracts/index.d.ts

@@ -20,4 +20,5 @@ export type { IHandoffCommand, IHandoffPhase, IHandoffSource, IHandoffFindings,
 export { BrowserCommandSchema, BrowserActionSchema, BrowserReceiptSchema, } from './browser/index.js';
 export type { IBrowserAction, IBrowserReceipt } from './browser/index.js';
 export { BrowserRepositorySchema, BrowserPlanSummarySchema, BrowserPlanPageSchema, BrowserPlanDetailSchema, BrowserSessionSchema, } from './browser/index.js';
-export { BrowserRepositoryPageSchema, BrowserSystemSchema, BrowserThreadDetailSchema, } from './browser/index.js';
+export { BrowserRepositoryPageSchema, BrowserSystemSchema, BrowserThreadDetailSchema, PublicationStatusSchema, } from './browser/index.js';
+export type { IPublicationStatus } from './browser/index.js';

package/dist/contracts/index.js

@@ -23,4 +23,4 @@ export { BrowserCommandSchema, BrowserActionSchema, BrowserReceiptSchema, } from
 // host read models
 export { BrowserRepositorySchema, BrowserPlanSummarySchema, BrowserPlanPageSchema, BrowserPlanDetailSchema, BrowserSessionSchema, } from './browser/index.js';
 // bounded host views
-export { BrowserRepositoryPageSchema, BrowserSystemSchema, BrowserThreadDetailSchema, } from './browser/index.js';
+export { BrowserRepositoryPageSchema, BrowserSystemSchema, BrowserThreadDetailSchema, PublicationStatusSchema, } from './browser/index.js';

package/dist/providers/claude/claude.js

@@ -2,7 +2,7 @@ import { Exception } from 'error-message-utils';
 import { scheduler } from 'node:timers/promises';
 import { z } from 'zod';
 import { createClaudeRpc } from './rpc.js';
-import { CLAUDE_HISTORY_VERSION, ClaudeUsageSchema } from './types.js';
+import { ClaudeHistoryVersionSchema, ClaudeUsageSchema } from './types.js';
 import { toClaudeUsageSnapshot } from './transformers.js';
 /**
  * Lazily connects read-only Claude capabilities; Codex needs no Claude installation.
@@ -61,7 +61,7 @@ export const createClaudeProvider = (store) => {
         async readHistory(command) {
             const deadline = Date.now() + 30_000;
             const native = await open();
-            if (native.version !== CLAUDE_HISTORY_VERSION)
+            if (!ClaudeHistoryVersionSchema.safeParse(native.version).success)
                 throw new Exception('The Claude history is unavailable', undefined, {
                     kind: 'agent-unavailable',
                 });

package/dist/providers/claude/history/history.model.js

@@ -4,7 +4,7 @@ import { Exception, extractMessage, hasErrorCode } from 'error-message-utils';
 import { z } from 'zod';
 import { HqResponseSchema, } from '../../../contracts/index.js';
 import { decodeHistoryCursor, encodeHistoryCursor, } from '../../../sessions/index.js';
-import { CLAUDE_HISTORY_VERSION } from '../types.js';
+import { ClaudeHistoryVersionSchema } from '../types.js';
 import { EntryRowSchema, EntrySeekSchema, FileRowSchema, RecordSchema, SeekSchema, } from './types.js';
 import { openTranscript, projectDirectory, toClaudeItem } from './utilities.js';
 const MAX_RECORD_BYTES = 1_048_576;
@@ -189,7 +189,7 @@ export class ClaudeHistoryModel {
                     this.__unavailable();
                 const record = RecordSchema.parse(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)));
                 if (record.uuid !== entry.uuid ||
-                    record.version !== CLAUDE_HISTORY_VERSION ||
+                    !ClaudeHistoryVersionSchema.safeParse(record.version).success ||
                     record.cwd !== root)
                     this.__unavailable();
                 const item = toClaudeItem(record, entry.turn_id);
@@ -403,14 +403,15 @@ export class ClaudeHistoryModel {
             row.name = record.customTitle;
             return;
         }
-        if (record.version !== undefined && record.version !== CLAUDE_HISTORY_VERSION)
+        if (record.version !== undefined &&
+            !ClaudeHistoryVersionSchema.safeParse(record.version).success)
             this.__unavailable();
         if (record.isSidechain || !record.uuid)
             return;
         if ((record.type === 'user' || record.type === 'assistant') &&
             record.message?.role !== record.type)
             this.__unavailable();
-        if (record.version !== CLAUDE_HISTORY_VERSION ||
+        if (!ClaudeHistoryVersionSchema.safeParse(record.version).success ||
             record.sessionId !== nativeId ||
             record.cwd !== root ||
             record.timestamp === undefined ||

package/dist/providers/claude/types.d.ts

@@ -1,5 +1,8 @@
 import { z } from 'zod';
-export declare const CLAUDE_HISTORY_VERSION = "2.1.304";
+export declare const ClaudeHistoryVersionSchema: z.ZodEnum<{
+    "2.1.304": "2.1.304";
+    "2.1.306": "2.1.306";
+}>;
 export declare const ClaudeInitializeSchema: z.ZodObject<{
     claude_code_version: z.ZodString;
     commands: z.ZodOptional<z.ZodUnknown>;

package/dist/providers/claude/types.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-// the local reader is qualified against this exact CLI transcript capability
-export const CLAUDE_HISTORY_VERSION = '2.1.304';
+// only explicitly qualified CLI and transcript versions may use the local reader
+export const ClaudeHistoryVersionSchema = z.enum(['2.1.304', '2.1.306']);
 export const ClaudeInitializeSchema = z.object({
     claude_code_version: z.string().min(1).max(128),
     commands: z.unknown().optional(),

package/dist/store/types.d.ts

@@ -494,7 +494,8 @@ export declare const StoreCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             release: z.ZodBoolean;
         }, z.core.$strict>, z.ZodObject<{
             kind: z.ZodLiteral<"publication-retry">;
-            expectedCommit: z.ZodString;
+            publicationId: z.ZodUUID;
+            expectedCommit: z.ZodNullable<z.ZodString>;
         }, z.core.$strict>], "kind">;
     }, z.core.$strict>;
     operatorId: z.ZodString;
@@ -2590,7 +2591,8 @@ export declare const StoreRequestSchema: z.ZodObject<{
                 release: z.ZodBoolean;
             }, z.core.$strict>, z.ZodObject<{
                 kind: z.ZodLiteral<"publication-retry">;
-                expectedCommit: z.ZodString;
+                publicationId: z.ZodUUID;
+                expectedCommit: z.ZodNullable<z.ZodString>;
             }, z.core.$strict>], "kind">;
         }, z.core.$strict>;
         operatorId: z.ZodString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jg-agent-hq",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Native coding-agent workspace primitives.",
   "type": "module",
   "license": "MIT",