jg-agent-hq 0.5.0 → 0.5.2

package/CHANGELOG.md

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

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 qualified transcript versions 2.1.296, 2.1.299, 2.1.304 and 2.1.306, including transcripts spanning these versions, keeps byte locations rather than conversation bodies in SQLite, and reports unsupported history as unavailable. File history cannot establish current execution state. See the [reader limits and freshness contract](api/README.md#claude-history).
 
 Explicit actions create, name, adopt, resume and close threads; send idle messages; steer an exact running turn; queue the next message; interrupt; and answer native questions or permissions. Actions have stable UUIDs and durable receipts. Repeating the same request returns its receipt; changing that UUID's payload conflicts. A lost acknowledgement stays uncertain until the exact native response arrives or the operator makes an explicit recovery choice. HQ never resends uncertain input.
 
@@ -105,4 +105,6 @@ Tests consume built public exports. Unit tests cover application-owned decisions
 
 The website's README and `docs/website.md` define its build-once check composition, category-specific scripts and owned preview/browser lifecycle. Root and website checks must both pass for task completion when workspace configuration or canonical site content changes.
 
+The runtime fixture teardown is registered with the test runner as well as the callback, so a test timeout cannot restore environment variables during the next test.
+
 Current local checks establish the tested host only. Release qualification must include the Node engines floor and current LTS; macOS operation requires its own runtime evidence.

package/api/README.md

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

package/dist/actions/actions.js

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

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 { ClaudeHistoryCliVersionSchema, 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 (!ClaudeHistoryCliVersionSchema.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,9 +4,11 @@ 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 { ClaudeHistoryRecordVersionSchema } from '../types.js';
 import { EntryRowSchema, EntrySeekSchema, FileRowSchema, RecordSchema, SeekSchema, } from './types.js';
-import { openTranscript, projectDirectory, toClaudeItem } from './utilities.js';
+import { isClaudeWorkspaceCwd, openTranscript, projectDirectory, toClaudeItem, } from './utilities.js';
+// identifies the path and record interpretation used by persisted projection entries
+const HISTORY_PROJECTION_VERSION = 1;
 const MAX_RECORD_BYTES = 1_048_576;
 const MAX_REFRESH_BYTES = 4_194_304;
 const CHAIN = `WITH RECURSIVE current_chain AS (
@@ -189,8 +191,8 @@ 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 ||
-                    record.cwd !== root)
+                    !ClaudeHistoryRecordVersionSchema.safeParse(record.version).success ||
+                    !isClaudeWorkspaceCwd(record.cwd, root))
                     this.__unavailable();
                 const item = toClaudeItem(record, entry.turn_id);
                 const itemSize = Buffer.byteLength(JSON.stringify(item));
@@ -251,7 +253,7 @@ export class ClaudeHistoryModel {
             this.__unavailable();
         const bytes = Buffer.alloc(Math.min(stat.size, 256));
         readSync(fd, bytes, 0, bytes.length, 0);
-        return `${stat.dev}:${stat.ino}:${stat.birthtimeMs}:${createHash('sha256').update(bytes).digest('hex')}`;
+        return `${HISTORY_PROJECTION_VERSION}:${ClaudeHistoryRecordVersionSchema.options.join(',')}:${stat.dev}:${stat.ino}:${stat.birthtimeMs}:${createHash('sha256').update(bytes).digest('hex')}`;
     }
     __refresh(directory, root) {
         let scan = this.__scans.get(root);
@@ -391,7 +393,7 @@ export class ClaudeHistoryModel {
     __record(root, nativeId, row, bytes, offset) {
         const record = RecordSchema.parse(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)));
         if (record.cwd !== undefined) {
-            if (record.cwd !== root || record.sessionId !== nativeId) {
+            if (!isClaudeWorkspaceCwd(record.cwd, root) || record.sessionId !== nativeId) {
                 row.workspace_state = 'foreign';
                 this.__unavailable();
             }
@@ -403,16 +405,17 @@ export class ClaudeHistoryModel {
             row.name = record.customTitle;
             return;
         }
-        if (record.version !== undefined && record.version !== CLAUDE_HISTORY_VERSION)
+        if (record.version !== undefined &&
+            !ClaudeHistoryRecordVersionSchema.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 (!ClaudeHistoryRecordVersionSchema.safeParse(record.version).success ||
             record.sessionId !== nativeId ||
-            record.cwd !== root ||
+            !isClaudeWorkspaceCwd(record.cwd, root) ||
             record.timestamp === undefined ||
             !Number.isFinite(Date.parse(record.timestamp)))
             this.__unavailable();

package/dist/providers/claude/history/utilities.d.ts

@@ -7,6 +7,11 @@ import type { IRecord } from './types.js';
  * - -1: The Claude history is unavailable
  */
 export declare const projectDirectory: (workspaceRoot: string) => string;
+/**
+ * Verifies a native cwd within its selected workspace, including removed subdirectories.
+ * @returns Whether existing path ancestors remain inside the workspace without excluded segments.
+ */
+export declare const isClaudeWorkspaceCwd: (cwd: string | undefined, workspaceRoot: string) => boolean;
 /**
  * Opens only one direct native UUID transcript, refusing links and traversal.
  * @returns The descriptor, which its caller must close.

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

@@ -1,7 +1,7 @@
 import { constants, lstatSync, openSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { Exception } from 'error-message-utils';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { Exception, hasErrorCode } from 'error-message-utils';
 import { z } from 'zod';
 const EXCLUDED = new Set(['_archive', '_archives', '_backup', '_backups']);
 /**
@@ -37,6 +37,39 @@ export const projectDirectory = (workspaceRoot) => {
         });
     return directory;
 };
+/**
+ * Verifies a native cwd within its selected workspace, including removed subdirectories.
+ * @returns Whether existing path ancestors remain inside the workspace without excluded segments.
+ */
+export const isClaudeWorkspaceCwd = (cwd, workspaceRoot) => {
+    if (cwd === workspaceRoot)
+        return true;
+    if (!cwd ||
+        cwd.length > 4096 ||
+        !isAbsolute(cwd) ||
+        resolve(cwd) !== cwd ||
+        cwd.split(sep).some((part) => EXCLUDED.has(part)))
+        return false;
+    const child = relative(workspaceRoot, cwd);
+    if (isAbsolute(child) || child === '..' || child.startsWith(`..${sep}`))
+        return false;
+    let ancestor = cwd;
+    while (ancestor !== workspaceRoot) {
+        try {
+            const canonical = realpathSync(ancestor);
+            if (canonical.split(sep).some((part) => EXCLUDED.has(part)))
+                return false;
+            const resolved = relative(workspaceRoot, canonical);
+            return !isAbsolute(resolved) && resolved !== '..' && !resolved.startsWith(`..${sep}`);
+        }
+        catch (cause) {
+            if (!hasErrorCode(cause, 'ENOENT') && !hasErrorCode(cause, 'ENOTDIR'))
+                throw cause;
+            ancestor = dirname(ancestor);
+        }
+    }
+    return true;
+};
 /**
  * Opens only one direct native UUID transcript, refusing links and traversal.
  * @returns The descriptor, which its caller must close.

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

@@ -1,5 +1,14 @@
 import { z } from 'zod';
-export declare const CLAUDE_HISTORY_VERSION = "2.1.304";
+export declare const ClaudeHistoryCliVersionSchema: z.ZodEnum<{
+    "2.1.304": "2.1.304";
+    "2.1.306": "2.1.306";
+}>;
+export declare const ClaudeHistoryRecordVersionSchema: z.ZodEnum<{
+    "2.1.304": "2.1.304";
+    "2.1.306": "2.1.306";
+    "2.1.296": "2.1.296";
+    "2.1.299": "2.1.299";
+}>;
 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,11 @@
 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 ClaudeHistoryCliVersionSchema = z.enum(['2.1.304', '2.1.306']);
+export const ClaudeHistoryRecordVersionSchema = z.enum([
+    '2.1.296',
+    '2.1.299',
+    ...ClaudeHistoryCliVersionSchema.options,
+]);
 export const ClaudeInitializeSchema = z.object({
     claude_code_version: z.string().min(1).max(128),
     commands: z.unknown().optional(),

package/package.json

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