jg-agent-hq 0.2.0 → 0.4.0

package/dist/plans/authority.js

@@ -12,9 +12,7 @@ export const describePlan = (artifacts, pendingActionId = null) => {
     const isPlanApproved = !!coordination.planApproval &&
         !coordination.planApproval.revokedBy &&
         coordination.planApproval.revision.planDigest === revision.planDigest;
-    const isFinalized = !!coordination.finalized &&
-        revision.breakdownDigest !== null &&
-        isSamePlanRevision(coordination.finalized.revision, revision);
+    const isFinalized = !!coordination.finalized && isSamePlanRevision(coordination.finalized.revision, revision);
     const isSequenceApproved = isPlanApproved &&
         isFinalized &&
         !!coordination.sequenceApproval &&
@@ -22,6 +20,12 @@ export const describePlan = (artifacts, pendingActionId = null) => {
         isSamePlanRevision(coordination.sequenceApproval.revision, revision);
     const verified = createCompletionLookup(coordination.completions, coordination.correspondences);
     const workflow = coordination.revision;
+    const invalidated = new Set(coordination.correspondences.flatMap((record) => record.invalidatedReceiptIds));
+    const isWholePlanComplete = artifacts.milestones === null &&
+        coordination.completions.some((receipt) => receipt.milestoneId === null &&
+            receipt.contractDigest === revision.planDigest &&
+            receipt.revision.breakdownDigest === null &&
+            !invalidated.has(receipt.id));
     const state = coordination.observedConflict ||
         pendingActionId ||
         workflow?.phase === 'blocked' ||
@@ -38,10 +42,11 @@ export const describePlan = (artifacts, pendingActionId = null) => {
                 ? 'plan-approval-required'
                 : !isFinalized
                     ? 'breakdown-required'
-                    : !isSequenceApproved
+                    : artifacts.milestones !== null && !isSequenceApproved
                         ? 'sequence-approval-required'
-                        : artifacts.parsed.length > 0 &&
-                            artifacts.parsed.every((milestone) => milestone.status === 'done' && verified(milestone))
+                        : isWholePlanComplete ||
+                            (artifacts.parsed.length > 0 &&
+                                artifacts.parsed.every((milestone) => milestone.status === 'done' && verified(milestone)))
                             ? 'completed'
                             : artifacts.parsed.some((milestone) => milestone.status === 'in progress')
                                 ? 'in-progress'
@@ -89,6 +94,26 @@ export const describePlan = (artifacts, pendingActionId = null) => {
         },
     };
 };
+/**
+ * Checks the current approved unfinished unit, with null identifying an undivided plan.
+ * Runtime epoch, action identity and mode remain the caller's separate admission checks.
+ * @returns Whether the exact unit is selected by current execution authority.
+ */
+export const canExecutePlanUnit = (artifacts, milestoneId) => {
+    const status = describePlan(artifacts);
+    const execution = artifacts.coordination.execution;
+    if (!execution ||
+        !status.isPlanApproved ||
+        !status.isFinalized ||
+        ['blocked', 'completed', 'revising'].includes(status.state))
+        return false;
+    return artifacts.milestones === null
+        ? milestoneId === null && execution.milestoneIds.length === 0
+        : status.isSequenceApproved &&
+            milestoneId !== null &&
+            execution.milestoneIds.includes(milestoneId) &&
+            artifacts.parsed.some((milestone) => milestone.id === milestoneId && milestone.status !== 'done');
+};
 /** Revocation records operator provenance without granting any replacement authority. */
 const revokeExecution = (coordination, action) => {
     if (coordination.execution)
@@ -104,7 +129,8 @@ export const updatePlanAuthority = (artifacts, command, runtimeEpoch) => {
     const coordination = structuredClone(artifacts.coordination);
     if (command.kind === 'approve') {
         const status = describePlan(artifacts);
-        if (command.scope === 'sequence' && (!status.isFinalized || !status.isPlanApproved))
+        if (command.scope === 'sequence' &&
+            (artifacts.milestones === null || !status.isFinalized || !status.isPlanApproved))
             conflict();
         const presentation = command.scope === 'plan' ? artifacts.hashes.plan : artifacts.hashes.milestones;
         if (presentation !== command.presentationHash)
@@ -139,7 +165,12 @@ export const updatePlanAuthority = (artifacts, command, runtimeEpoch) => {
             coordination.revision.phase !== 'finished')
             conflict();
         if (status.state === 'blocked' ||
-            !status.isSequenceApproved ||
+            status.state === 'completed' ||
+            !status.isPlanApproved ||
+            !status.isFinalized ||
+            (artifacts.milestones === null
+                ? command.milestoneIds.length !== 0
+                : !status.isSequenceApproved || command.milestoneIds.length === 0) ||
             command.milestoneIds.some((id) => !artifacts.parsed.some((milestone) => milestone.id === id && milestone.status !== 'done')))
             conflict();
         if (coordination.revision)

package/dist/plans/finalization.d.ts

@@ -8,6 +8,6 @@ import type { IPlanArtifacts } from './types.js';
  * - -1: The HQ plan is invalid
  */
 export declare const finalizeInitialSequence: (artifacts: IPlanArtifacts) => {
-    content: string;
+    content: string | null;
     revision: IPlanRevision;
 };

package/dist/plans/finalization.js

@@ -14,10 +14,11 @@ const conflict = () => {
  * - -1: The HQ plan is invalid
  */
 export const finalizeInitialSequence = (artifacts) => {
-    if (artifacts.milestones === null ||
-        (artifacts.coordination.finalized &&
-            !isSamePlanRevision(artifacts.coordination.finalized.revision, artifacts.revision)))
+    if (artifacts.coordination.finalized &&
+        !isSamePlanRevision(artifacts.coordination.finalized.revision, artifacts.revision))
         conflict();
+    if (artifacts.milestones === null)
+        return { content: null, revision: artifacts.revision };
     let milestones = artifacts.milestones.replace(/\r\n?/g, '\n');
     // insertion offsets are applied backwards so original positions stay valid
     for (const milestone of [...artifacts.parsed].reverse())

package/dist/plans/plans.d.ts

@@ -116,7 +116,7 @@ export declare const createPlans: (coordinationRoot: string, roots: string[], st
      * - -1: HQ lock ownership changed before release
      */
     checkpoint(target: IPlanCommand["target"], revisionId: string, phaseActionId: string): Promise<void>;
-    admitNative(action: import("../contracts/index.js").IActionEnvelope, prepared: import("../store/control/types.js").IAdmission["prepared"]): Promise<{
+    admitNative(action: import("../contracts/index.js").IActionEnvelope, prepared: import("../store/control/types.ts").IAdmission["prepared"]): Promise<{
         receipt: {
             id: string;
             digest: string;
@@ -134,7 +134,7 @@ export declare const createPlans: (coordinationRoot: string, roots: string[], st
                 scope: {
                     kind: "execution";
                     authorizationId: string;
-                    milestoneId: string;
+                    milestoneId: string | null;
                     mode: "supervised" | "auto";
                     revision: {
                         planDigest: string;
@@ -192,7 +192,7 @@ export declare const createPlans: (coordinationRoot: string, roots: string[], st
                 scope: {
                     kind: "execution";
                     authorizationId: string;
-                    milestoneId: string;
+                    milestoneId: string | null;
                     mode: "supervised" | "auto";
                     revision: {
                         planDigest: string;

package/dist/plans/plans.js

@@ -4,7 +4,7 @@ import { PlanMilestoneSchema, } from '../contracts/index.js';
 import { getErrorKind } from '../errors/index.js';
 import { withHqLock } from '../locks/index.js';
 import { resolveWorkspaceTarget } from '../runtime/state/index.js';
-import { describePlan, updatePlanAuthority } from './authority.js';
+import { canExecutePlanUnit, describePlan, updatePlanAuthority } from './authority.js';
 import { createPlanAdmission } from './admission.js';
 import { readPlanPage } from './projections.js';
 import { finalizeInitialSequence } from './finalization.js';
@@ -340,16 +340,14 @@ export const createPlans = (coordinationRoot, roots, store, runtimeEpoch, parseC
                     const execution = artifacts.coordination.execution;
                     if (pendingActionId ||
                         status.state === 'blocked' ||
-                        !status.isSequenceApproved ||
                         !execution ||
                         execution.runtimeEpoch !== runtimeEpoch ||
                         execution.revokedBy ||
                         execution.action.id !== command.authorizationId ||
                         execution.mode !== command.mode ||
-                        !execution.milestoneIds.includes(command.milestoneId) ||
+                        !canExecutePlanUnit(artifacts, command.milestoneId) ||
                         !isSamePlanRevision(command.expected, artifacts.revision) ||
-                        !isSamePlanRevision(execution.revision, artifacts.revision) ||
-                        !artifacts.parsed.some((milestone) => milestone.id === command.milestoneId && milestone.status !== 'done'))
+                        !isSamePlanRevision(execution.revision, artifacts.revision))
                         conflict();
                     return {
                         kind: 'execution-check',
@@ -367,9 +365,7 @@ export const createPlans = (coordinationRoot, roots, store, runtimeEpoch, parseC
                     await apply(previous);
                     artifacts = await readPlanArtifacts(command.target, roots, parseContract);
                     const current = describeCurrent(artifacts, await store.getPendingPlanOperationId(artifacts.directory));
-                    return command.kind === 'finalize' &&
-                        current.isFinalized &&
-                        artifacts.milestones !== null
+                    return command.kind === 'finalize' && current.isFinalized
                         ? { kind: 'finalized', result: current, content: artifacts.milestones }
                         : { kind: 'status', result: current };
                 }
@@ -449,7 +445,7 @@ export const createPlans = (coordinationRoot, roots, store, runtimeEpoch, parseC
                             conflict();
                         if ((await store.getPlanThreads(artifacts.directory)).length)
                             conflict();
-                        if (!workflow.checkpoint?.isQuiescent || artifacts.milestones === null)
+                        if (!workflow.checkpoint?.isQuiescent)
                             conflict();
                         const proposal = workflow.proposal ?? proposeReconciliation(artifacts, command.action);
                         if (proposal.inspectionHash !== artifacts.hashes.milestones ||
@@ -475,7 +471,9 @@ export const createPlans = (coordinationRoot, roots, store, runtimeEpoch, parseC
                             }
                             else if (command.confirmation)
                                 conflict();
-                            const content = renderReconciledSequence(artifacts.milestones, drafts);
+                            const content = artifacts.milestones === null
+                                ? null
+                                : renderReconciledSequence(artifacts.milestones, drafts);
                             const revision = computePlanRevision({
                                 ...artifacts.contract,
                                 milestones: content,
@@ -498,7 +496,7 @@ export const createPlans = (coordinationRoot, roots, store, runtimeEpoch, parseC
                         coordination.finalized = {
                             action: command.action,
                             revision: finalized.revision,
-                            fileHash: hashPlanContent(milestones),
+                            fileHash: milestones === null ? null : hashPlanContent(milestones),
                             createdAt: Date.now(),
                         };
                         coordination.baseline = refreshPlanBaseline(artifacts, milestones, finalized.revision);

package/dist/plans/reconciliation.js

@@ -22,7 +22,7 @@ export const createCompletionLookup = (completions, records) => {
     });
     const direct = new Set(completions
         .filter((receipt) => !invalidated.has(receipt.id) &&
-        receipt.reopenActionId === (reopened.get(receipt.milestoneId)?.id ?? null))
+        receipt.reopenActionId === (reopened.get(receipt.milestoneId ?? '')?.id ?? null))
         .map((receipt) => JSON.stringify([receipt.milestoneId, receipt.contractDigest])));
     const links = new Map();
     for (const [recordIndex, record] of records.entries()) {
@@ -67,7 +67,7 @@ export const createCompletionLookup = (completions, records) => {
  */
 export const proposeReconciliation = (artifacts, action) => {
     const checkpoint = artifacts.coordination.revision?.checkpoint;
-    if (!checkpoint || artifacts.milestones === null)
+    if (!checkpoint)
         conflict();
     const sources = checkpoint.entries;
     const oldByContract = new Map();
@@ -186,7 +186,7 @@ export const confirmReconciliation = (artifacts, proposal, action, decisions) =>
         }
         const invalidatedReceiptIds = decision.relation === 'reopened'
             ? artifacts.coordination.completions
-                .filter((receipt) => decision.sourceIds.includes(receipt.milestoneId))
+                .filter((receipt) => receipt.milestoneId !== null && decision.sourceIds.includes(receipt.milestoneId))
                 .map((receipt) => receipt.id)
             : [];
         records.push({

package/dist/plans/revisions.d.ts

@@ -37,7 +37,7 @@ export declare const finishPlanCheckpoint: (artifacts: IPlanArtifacts, revisionI
  */
 export declare const recordPlanCompletion: (artifacts: IPlanArtifacts, input: {
     action: IPlanOperatorAction;
-    milestoneId: string;
+    milestoneId: string | null;
     checks: IPlanCompletion["checks"];
 }, checkouts: IPlanWorktreeProof[]) => IPlanCompletion;
 /**
@@ -46,6 +46,6 @@ export declare const recordPlanCompletion: (artifacts: IPlanArtifacts, input: {
  * @throws
  * - -1: The HQ plan is invalid
  */
-export declare const refreshPlanBaseline: (artifacts: IPlanArtifacts, content: string, revision: IPlanCheckpoint["revision"]) => IPlanCheckpoint;
+export declare const refreshPlanBaseline: (artifacts: IPlanArtifacts, content: string | null, revision: IPlanCheckpoint["revision"]) => IPlanCheckpoint;
 /** Builds indexed retained evidence without exposing whole coordination collections to clients. */
 export declare const projectPlanRevision: (artifacts: IPlanArtifacts) => IPlanRevisionProjection;

package/dist/plans/revisions.js

@@ -24,8 +24,6 @@ export const capturePlanCheckpoint = (artifacts, threadIds) => {
             isQuiescent: false,
             capturedAt: Date.now(),
         };
-    if (artifacts.milestones === null || !artifacts.revision.breakdownDigest)
-        conflict();
     return {
         revision: artifacts.revision,
         plan: artifacts.plan,
@@ -120,6 +118,24 @@ export const finishPlanCheckpoint = (artifacts, revisionId, checkouts) => {
  * - -1: The HQ action conflicts with its recorded state
  */
 export const recordPlanCompletion = (artifacts, input, checkouts) => {
+    if (input.milestoneId === null) {
+        if (artifacts.milestones !== null)
+            conflict();
+        return {
+            id: input.action.id,
+            action: input.action,
+            milestoneId: null,
+            revision: artifacts.revision,
+            contractDigest: artifacts.revision.planDigest,
+            title: 'Whole plan',
+            contract: artifacts.contract.body,
+            sharedDigest: null,
+            checkouts,
+            checks: input.checks,
+            completedAt: Date.now(),
+            reopenActionId: null,
+        };
+    }
     const milestone = artifacts.parsed.find((entry) => entry.id === input.milestoneId) ??
         artifacts.coordination.revision?.checkpoint?.entries.find((entry) => entry.id === input.milestoneId);
     if (!milestone?.id || !milestone.contractDigest)
@@ -155,7 +171,9 @@ export const refreshPlanBaseline = (artifacts, content, revision) => {
         revision,
         plan: artifacts.plan,
         milestones: content,
-        entries: parsePlanMilestones(content).map((entry) => PlanSnapshotMilestoneSchema.parse(entry)),
+        entries: content === null
+            ? []
+            : parsePlanMilestones(content).map((entry) => PlanSnapshotMilestoneSchema.parse(entry)),
         checkouts: previous?.checkouts ?? [],
         threadIds: previous?.threadIds ?? [],
         isQuiescent: previous?.isQuiescent ?? true,

package/dist/plans/types.d.ts

@@ -156,7 +156,7 @@ export declare const PlanRevisionProjectionSchema: z.ZodObject<{
                         reference: z.ZodString;
                     }, z.core.$strict>;
                 }, z.core.$strict>;
-                milestoneId: z.ZodUUID;
+                milestoneId: z.ZodNullable<z.ZodUUID>;
                 revision: z.ZodObject<{
                     planDigest: z.ZodString;
                     breakdownDigest: z.ZodNullable<z.ZodString>;
@@ -164,7 +164,7 @@ export declare const PlanRevisionProjectionSchema: z.ZodObject<{
                 contractDigest: z.ZodString;
                 title: z.ZodString;
                 contract: z.ZodString;
-                sharedDigest: z.ZodString;
+                sharedDigest: z.ZodNullable<z.ZodString>;
                 checkouts: z.ZodArray<z.ZodObject<{
                     repository: z.ZodString;
                     directory: z.ZodString;
@@ -290,7 +290,7 @@ export declare const PlanRevisionPageResultSchema: z.ZodObject<{
                     reference: z.ZodString;
                 }, z.core.$strict>;
             }, z.core.$strict>;
-            milestoneId: z.ZodUUID;
+            milestoneId: z.ZodNullable<z.ZodUUID>;
             revision: z.ZodObject<{
                 planDigest: z.ZodString;
                 breakdownDigest: z.ZodNullable<z.ZodString>;
@@ -298,7 +298,7 @@ export declare const PlanRevisionPageResultSchema: z.ZodObject<{
             contractDigest: z.ZodString;
             title: z.ZodString;
             contract: z.ZodString;
-            sharedDigest: z.ZodString;
+            sharedDigest: z.ZodNullable<z.ZodString>;
             checkouts: z.ZodArray<z.ZodObject<{
                 repository: z.ZodString;
                 directory: z.ZodString;

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

@@ -47,7 +47,7 @@ export declare const createClaudeControl: (additionalDirectories?: string[]) =>
      * @throws
      * - -1: The Claude integration failed
      */
-    readSkills(nativeId: string): Promise<import("../../types.js").IProviderSkills>;
+    readSkills(nativeId: string): Promise<import("../../types.ts").IProviderSkills>;
     /**
      * Names only the native session selected by the admitted action.
      * @returns Native acknowledgement of the name change.

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

@@ -1,5 +1,31 @@
 import { z } from 'zod';
 export declare const ClaudeHistoryReadSchema: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"thread-plan">;
+    result: z.ZodNullable<z.ZodObject<{
+        directory: z.ZodString;
+        scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"execution">;
+            authorizationId: z.ZodUUID;
+            milestoneId: z.ZodNullable<z.ZodUUID>;
+            mode: z.ZodEnum<{
+                supervised: "supervised";
+                auto: "auto";
+            }>;
+            revision: z.ZodObject<{
+                planDigest: z.ZodString;
+                breakdownDigest: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"planning">;
+            revisionId: z.ZodUUID;
+            invocationId: z.ZodUUID;
+        }, z.core.$strict>], "kind">>;
+        observedRevision: z.ZodObject<{
+            planDigest: z.ZodString;
+            breakdownDigest: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"status">;
     result: z.ZodObject<{
         runtimeEpoch: z.ZodUUID;
@@ -110,7 +136,7 @@ export declare const ClaudeHistoryReadSchema: z.ZodUnion<readonly [z.ZodDiscrimi
                         planDigest: z.ZodString;
                         breakdownDigest: z.ZodNullable<z.ZodString>;
                     }, z.core.$strict>;
-                    fileHash: z.ZodString;
+                    fileHash: z.ZodNullable<z.ZodString>;
                     createdAt: z.ZodNumber;
                 }, z.core.$strict>>;
                 planApproval: z.ZodNullable<z.ZodObject<{
@@ -330,7 +356,7 @@ export declare const ClaudeHistoryReadSchema: z.ZodUnion<readonly [z.ZodDiscrimi
                         planDigest: z.ZodString;
                         breakdownDigest: z.ZodNullable<z.ZodString>;
                     }, z.core.$strict>;
-                    fileHash: z.ZodString;
+                    fileHash: z.ZodNullable<z.ZodString>;
                     createdAt: z.ZodNumber;
                 }, z.core.$strict>>;
                 planApproval: z.ZodNullable<z.ZodObject<{
@@ -518,7 +544,7 @@ export declare const ClaudeHistoryReadSchema: z.ZodUnion<readonly [z.ZodDiscrimi
                             reference: z.ZodString;
                         }, z.core.$strict>;
                     }, z.core.$strict>;
-                    milestoneId: z.ZodUUID;
+                    milestoneId: z.ZodNullable<z.ZodUUID>;
                     revision: z.ZodObject<{
                         planDigest: z.ZodString;
                         breakdownDigest: z.ZodNullable<z.ZodString>;
@@ -526,7 +552,7 @@ export declare const ClaudeHistoryReadSchema: z.ZodUnion<readonly [z.ZodDiscrimi
                     contractDigest: z.ZodString;
                     title: z.ZodString;
                     contract: z.ZodString;
-                    sharedDigest: z.ZodString;
+                    sharedDigest: z.ZodNullable<z.ZodString>;
                     checkouts: z.ZodArray<z.ZodObject<{
                         repository: z.ZodString;
                         directory: z.ZodString;
@@ -674,7 +700,7 @@ export declare const ClaudeHistoryReadSchema: z.ZodUnion<readonly [z.ZodDiscrimi
                         planDigest: z.ZodString;
                         breakdownDigest: z.ZodNullable<z.ZodString>;
                     }, z.core.$strict>;
-                    fileHash: z.ZodString;
+                    fileHash: z.ZodNullable<z.ZodString>;
                     createdAt: z.ZodNumber;
                 }, z.core.$strict>>;
                 planApproval: z.ZodNullable<z.ZodObject<{
@@ -813,7 +839,7 @@ export declare const ClaudeHistoryReadSchema: z.ZodUnion<readonly [z.ZodDiscrimi
                 }, z.core.$strict>>;
             }, z.core.$strict>;
         }, z.core.$strip>;
-        content: z.ZodString;
+        content: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"milestones">;
         result: z.ZodObject<{
@@ -894,7 +920,7 @@ export declare const ClaudeHistoryReadSchema: z.ZodUnion<readonly [z.ZodDiscrimi
                     scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
                         kind: z.ZodLiteral<"execution">;
                         authorizationId: z.ZodUUID;
-                        milestoneId: z.ZodUUID;
+                        milestoneId: z.ZodNullable<z.ZodUUID>;
                         mode: z.ZodEnum<{
                             supervised: "supervised";
                             auto: "auto";
@@ -1027,7 +1053,7 @@ export declare const ClaudeHistoryReadSchema: z.ZodUnion<readonly [z.ZodDiscrimi
                     scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
                         kind: z.ZodLiteral<"execution">;
                         authorizationId: z.ZodUUID;
-                        milestoneId: z.ZodUUID;
+                        milestoneId: z.ZodNullable<z.ZodUUID>;
                         mode: z.ZodEnum<{
                             supervised: "supervised";
                             auto: "auto";
@@ -1364,7 +1390,7 @@ export declare const ClaudeHistoryReadSchema: z.ZodUnion<readonly [z.ZodDiscrimi
             scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
                 kind: z.ZodLiteral<"execution">;
                 authorizationId: z.ZodUUID;
-                milestoneId: z.ZodUUID;
+                milestoneId: z.ZodNullable<z.ZodUUID>;
                 mode: z.ZodEnum<{
                     supervised: "supervised";
                     auto: "auto";
@@ -1440,7 +1466,7 @@ export declare const ClaudeHistoryReadSchema: z.ZodUnion<readonly [z.ZodDiscrimi
             scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
                 kind: z.ZodLiteral<"execution">;
                 authorizationId: z.ZodUUID;
-                milestoneId: z.ZodUUID;
+                milestoneId: z.ZodNullable<z.ZodUUID>;
                 mode: z.ZodEnum<{
                     supervised: "supervised";
                     auto: "auto";
@@ -1628,7 +1654,7 @@ export declare const ClaudeHistoryReadSchema: z.ZodUnion<readonly [z.ZodDiscrimi
                 scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
                     kind: z.ZodLiteral<"execution">;
                     authorizationId: z.ZodUUID;
-                    milestoneId: z.ZodUUID;
+                    milestoneId: z.ZodNullable<z.ZodUUID>;
                     mode: z.ZodEnum<{
                         supervised: "supervised";
                         auto: "auto";
@@ -1719,6 +1745,8 @@ export declare const ClaudeHistoryReadSchema: z.ZodUnion<readonly [z.ZodDiscrimi
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"live-items">;
     result: z.ZodObject<{
+        revision: z.ZodNumber;
+        unchanged: z.ZodBoolean;
         data: z.ZodArray<z.ZodObject<{
             nativeId: z.ZodString;
             turnId: z.ZodString;

package/dist/runtime/browser/browser.d.ts

@@ -0,0 +1,8 @@
+import { type IBrowserAction, type IBrowserReceipt } from '../../contracts/index.js';
+import type { IStore } from '../../store/index.js';
+/** Serializes host admission and owns effects independently of an HTTP connection. */
+export declare const createBrowserActions: (store: IStore) => {
+    read: (id: string, operatorId: string) => Promise<IBrowserReceipt | null>;
+    perform: (input: IBrowserAction, operatorId: string, execute: (action: IBrowserAction, nativeActionId: string) => Promise<void>) => Promise<IBrowserReceipt>;
+    close: () => Promise<void>;
+};

package/dist/runtime/browser/browser.js

@@ -0,0 +1,55 @@
+import { Exception } from 'error-message-utils';
+import { z } from 'zod';
+import { BrowserActionSchema, } from '../../contracts/index.js';
+const OperatorSchema = z.string().min(1).max(256);
+/** Serializes host admission and owns effects independently of an HTTP connection. */
+export const createBrowserActions = (store) => {
+    const pending = new Set();
+    let isClosing = false;
+    const read = async (id, operatorId) => {
+        const parsed = z
+            .object({ id: z.uuid(), operatorId: OperatorSchema })
+            .safeParse({ id, operatorId });
+        if (!parsed.success)
+            throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' });
+        const receipt = await store.getBrowserAction(id, operatorId);
+        if (receipt?.kind === 'native')
+            receipt.native = await store.getAction(receipt.nativeActionId);
+        return receipt;
+    };
+    const perform = (input, operatorId, execute) => {
+        if (isClosing || pending.size >= 32)
+            return Promise.reject(new Exception('The HQ action conflicts with its recorded state', undefined, {
+                kind: 'state-conflict',
+            }));
+        const task = (async () => {
+            const action = BrowserActionSchema.safeParse(input);
+            if (!action.success || !OperatorSchema.safeParse(operatorId).success)
+                throw new Exception('The HQ request is invalid', undefined, { kind: 'invalid-request' });
+            const admission = await store.admitBrowserAction(action.data, operatorId);
+            if (admission.isNew) {
+                try {
+                    await execute(action.data, admission.receipt.nativeActionId);
+                    await store.settleBrowserAction(action.data.id, operatorId, 'acknowledged');
+                }
+                catch (cause) {
+                    // effects may have committed before an error; only reconciliation can establish their outcome
+                    await store.settleBrowserAction(action.data.id, operatorId, 'uncertain');
+                    throw cause;
+                }
+            }
+            return (await read(action.data.id, operatorId));
+        })();
+        pending.add(task);
+        void task.finally(() => pending.delete(task)).catch(() => undefined);
+        return task;
+    };
+    return {
+        read,
+        perform,
+        close: async () => {
+            isClosing = true;
+            await Promise.allSettled([...pending]);
+        },
+    };
+};

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

@@ -0,0 +1 @@
+export { createBrowserActions } from './browser.js';

package/dist/runtime/browser/index.js

@@ -0,0 +1,2 @@
+// host-action lifecycle
+export { createBrowserActions } from './browser.js';

package/dist/runtime/runtime.js

@@ -12,6 +12,7 @@ import { createSkills } from '../skills/index.js';
 import { createStore } from '../store/index.js';
 import { createPlans } from '../plans/index.js';
 import { claimRuntimeOwner, prepareDatabase, prepareActionKey, prepareStateRoot, resolveAllowedRoots, resolveWorkspaceTarget, } from './state/index.js';
+import { createBrowserActions } from './browser/index.js';
 import { AgentHqOptionsSchema } from './types.js';
 const UnconfirmedCleanupSchema = z.object({ cleanupUnconfirmed: z.literal(true) });
 /**
@@ -67,6 +68,7 @@ export const createAgentHq = async (options) => {
             await ownership.release();
         throw error;
     }
+    const browser = createBrowserActions(store);
     const native = provider;
     const projection = store;
     const claude = createClaudeProvider(projection);
@@ -137,6 +139,7 @@ export const createAgentHq = async (options) => {
     });
     const close = () => (closing ??= (async () => {
         try {
+            await browser.close();
             await Promise.allSettled([...revisionJobs.values()]);
             const results = await Promise.allSettled([ipc?.close(), actions.close(), claude.close()]);
             const storeCleanup = await Promise.allSettled([projection.close()]);
@@ -213,6 +216,7 @@ export const createAgentHq = async (options) => {
                     kind: command.kind,
                     result: { name: await projection.suggestThreadName(suggestThreadName(command.topic)) },
                 };
+            case 'thread-plan':
             case 'managed-thread-name':
             case 'receipt':
             case 'managed-threads':
@@ -264,5 +268,12 @@ export const createAgentHq = async (options) => {
         await close();
         throw error;
     }
-    return { stateRoot, closed, request, close };
+    return {
+        stateRoot,
+        closed,
+        request,
+        close,
+        performBrowserAction: browser.perform,
+        readBrowserAction: browser.read,
+    };
 };

package/dist/runtime/types.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { IHqRequestInput, IHqResponse } from '../contracts/index.js';
+import type { IHqRequestInput, IHqResponse, IBrowserAction, IBrowserReceipt } from '../contracts/index.js';
 import type { IPlanContractParser } from '../plans/index.js';
 export declare const AgentHqOptionsSchema: z.ZodObject<{
     stateRoot: z.ZodString;
@@ -11,6 +11,24 @@ export declare const AgentHqOptionsSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type IAgentHqOptions = z.infer<typeof AgentHqOptionsSchema>;
 export type IAgentHq = {
+    /**
+     * Runs one trusted host dispatcher after durable admission. Never expose the callback as RPC.
+     * Dispatcher failures propagate after the receipt becomes uncertain.
+     * @returns Its receipt; replays do not execute the dispatcher.
+     * @throws
+     * - -1: The HQ request is invalid
+     * - -1: The HQ action conflicts with its recorded state
+     * - -1: The HQ store failed
+     */
+    performBrowserAction(input: IBrowserAction, operatorId: string, execute: (action: IBrowserAction, nativeActionId: string) => Promise<void>): Promise<IBrowserReceipt>;
+    /**
+     * Reconciles a selected receipt for its authenticated operator without repeating effects.
+     * @returns The receipt, or null for another operator or unknown ID.
+     * @throws
+     * - -1: The HQ request is invalid
+     * - -1: The HQ store failed
+     */
+    readBrowserAction(id: string, operatorId: string): Promise<IBrowserReceipt | null>;
     stateRoot: string;
     closed: Promise<void>;
     /**