@sema-agent/core 7.6.1 → 7.6.3

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 7.6.3 — 2026-09-08
+
+Maintenance patch on the 7.6.x line: one correction to 7.6.2's forwarding drain.
+
+### Fixed
+- **forwardSubagentEvents drain gate** — 7.6.2 gated the drain inside an `async` helper and awaited it unconditionally, so a run that did NOT opt in still yielded one extra microtask before its terminal push (the black-box round measured parent `done` at hop 356 vs 355 on 7.6.1). The gate is now a synchronous predicate at both terminal pushes and the helper is a plain Promise factory; the non-forwarding terminal depth is pinned (ratchet 58, the unconditional-await form reds it at 59). No change for opted-in runs.
+
+## 7.6.2 — 2026-09-08
+
+Backport patch on the 7.6.x line (two field bugs the server 7.64.0 chain found; no store-contract change — that is 7.7.0).
+
+### Fixed
+- **R12 (`forwardSubagentEvents`)** — a run that opted into forwarding did not wait for the frames its BACKGROUND children had already handed to the forward channel before saying `done`; the gap is one microtask ladder deep and moved when #594 split the tool gate into three async stations (a child's gated call went from 24 to 27 microtask hops between `tool_start` and `tool_end`), so a consumer that read the parent to `done` and then inspected the sink lost the child's `tool_end`. The parent now takes one macrotask turn right before its terminal push, only on opted-in runs, on both the success and the failure path. Pin: `test/forward-subagent-events-drain.test.ts`.
+- **R13 (checkpoint)** — the pre-CAS refusal of a pending approval row that carries no `origin` word (a row minted before the ask's origin was persisted on the park) now carries `reason: "origin_missing"` like its three `unsupported_version` siblings, so a host upgrading with parked cards can classify the orphaned row. Pin: `test/backlog-r13-origin-missing-reason.test.ts`.
+
+### Changed
+- `CheckpointError.detail.reason` closed set gains `"origin_missing"` (terminal for the row's bytes; the host decides the orphaned card).
+
 ## 7.6.1 — 2026-09-07
 
 Patch: three bug fixes from the 7.6.0 field and black-box rounds (#608 P1, #609, #610) and the first refactor wave (design/393 S0, #594, #598), all byte-invariant on the runtime except where named. One public d.ts narrowing is called out below.

package/dist/core/checkpoint-store.d.ts

@@ -2093,11 +2093,13 @@ export declare class CheckpointError extends Error {
          *  additive and optional like `field` — `code` remains the only REQUIRED discriminant.
          *   · `unsupported_version` arms: `"version_newer"` (retryable on a newer worker),
          *     `"env_factory_missing"` (retryable on a factory-wired worker), `"governed_unwired"`
-         *     (retryable on an org-wired worker).
+         *     (retryable on an org-wired worker), `"origin_missing"` (a pending approval row minted
+         *     before the ask's origin was persisted on the park — terminal for the row's bytes; the host
+         *     decides the orphaned card itself, no worker version redeems it).
          *   · `invalid_outcome` pre-CAS row-integrity arms: `"real_approval_damaged"`,
          *     `"real_approval_forged"`, `"constraint_chain_missing"` (all terminal for the row's
          *     current bytes — no worker version redeems a damaged row). */
-        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
+        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "origin_missing" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
     } | undefined;
     constructor(code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found"
     /** `runner.resume` was handed an {@link ResumeOutcome} whose `gate` arm does not match the
@@ -2275,11 +2277,13 @@ export declare class CheckpointError extends Error {
          *  additive and optional like `field` — `code` remains the only REQUIRED discriminant.
          *   · `unsupported_version` arms: `"version_newer"` (retryable on a newer worker),
          *     `"env_factory_missing"` (retryable on a factory-wired worker), `"governed_unwired"`
-         *     (retryable on an org-wired worker).
+         *     (retryable on an org-wired worker), `"origin_missing"` (a pending approval row minted
+         *     before the ask's origin was persisted on the park — terminal for the row's bytes; the host
+         *     decides the orphaned card itself, no worker version redeems it).
          *   · `invalid_outcome` pre-CAS row-integrity arms: `"real_approval_damaged"`,
          *     `"real_approval_forged"`, `"constraint_chain_missing"` (all terminal for the row's
          *     current bytes — no worker version redeems a damaged row). */
-        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
+        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "origin_missing" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
     } | undefined);
 }
 /**

package/dist/core/runner/prepare-run-refs.d.ts

@@ -86,4 +86,20 @@ export interface PrepareRunRefsResult {
     worktreeIsolation: SubagentWorktreeIsolation | undefined;
 }
 /** The M3a phase body — prepareTask's run-refs stretch, verbatim (see the module header). */
+/**
+ * A run that opted into `forwardSubagentEvents` may have BACKGROUND children whose frames are forwarded to the
+ * deployment's sink from the child's own run. Those forwards are scheduled on later microtasks than the parent's
+ * turn, so "the parent stream ended" and "the child's already-emitted frames reached the sink" are two different
+ * moments — the gap is one microtask ladder deep and moves whenever the gate's station structure changes (design/393
+ * / #594: the three-layer gate added three async frames to a child's gated call, and a consumer that read the parent
+ * to `done` then inspected the sink lost the child's `tool_end`). The rule is not a tick count: **before the parent
+ * says `done`, every frame a child had already handed to the forward channel is delivered.** One macrotask turn is
+ * the smallest boundary that strictly orders after all pending microtasks; it is taken only on the opted-in run,
+ * only once, right before `done`.
+ */
+export declare function forwardsSubagentEvents(spec: Pick<TaskSpec, "forwardSubagentEvents">): boolean;
+/** The drain itself — one macrotask turn. Callers gate it with {@link forwardsSubagentEvents} SYNCHRONOUSLY so a
+ *  non-forwarding run's terminal push is not one microtask later than it was (an `await` of an early-returning
+ *  async function still yields once; the black-box round measured that tick). */
+export declare function drainForwardedFramesBeforeDone(): Promise<void>;
 export declare function prepareRunRefs(input: PrepareRunRefsInput): PrepareRunRefsResult;

package/dist/core/runner/prepare-run-refs.js

@@ -2,6 +2,12 @@ import { createSubagentWorktreeHelper } from "../../agents/subagent.js";
 import { SubagentRetainLedger } from "../../agents/retain-ledger.js";
 import { ActiveSkillScope } from "./active-skill-scope.js";
 import { createEditedFilesLedger } from "./edited-files-ledger.js";
+export function forwardsSubagentEvents(spec) {
+    return spec.forwardSubagentEvents === true;
+}
+export function drainForwardedFramesBeforeDone() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
 export function prepareRunRefs(input) {
     const { spec, internals, executionEnv, taskRootFinal } = input;
     const { note: noteFileEdited, snapshot: editedFilesSnapshot } = createEditedFilesLedger();

package/dist/core/runner/runtask.js

@@ -39,6 +39,7 @@ import { amendTerminal, terminalProjection } from "./terminal-projection.js";
 import { ATTACHMENT_BYTE_CAP, CHANGED_FILES_MAX, TOTAL_TOKENS_REMINDER_DEFAULT_MODE, AGENT_LISTING_REMOVED_HEADER, SKILLS_LISTING_DELTA_HEADER, SKILLS_LISTING_REMOVED_HEADER, advanceCadenceClock, agentListingDeltaHeader, attachmentEnvelopeTags, agentListingInitialHeader, replayAnnouncedListing, replayAnnouncedModels, clipToBytes, collectDateChange, collectDueAttachments, collectInstructionsChange, commitAgentListing, commitInstructionsChange, commitSkillsListing, createAttachmentState, rebaseCadenceWindows, reduceToolEnd, renderAgentListingDelta, renderMcpDroppedTools, renderMcpInstructionsDelta, renderOrphanedBackgroundTasks, selectMcpDroppedBatch, renderSkillsListingDelta, renderToolsDelta, stampWriteAnchor } from "./turn-attachments.js";
 import { buildWorkingFileAttachments, centerAdoptionOption, contextInstructionFilesOption, emitInputTruncated, forkContextOption } from "./compaction-call-options.js";
 import { effectiveDelegationFacts, prepareTask } from "./prepare-task.js";
+import { drainForwardedFramesBeforeDone, forwardsSubagentEvents } from "./prepare-run-refs.js";
 import { gatedCallIdOf } from "./park-commit.js";
 import { placementValueOrAbsent } from "./checkpoint-scope.js";
 import { SessionReadFileStates } from "./prepare-hands-readface.js";
@@ -1837,6 +1838,8 @@ export class Runner {
                     onError: (f) => console.warn(`[sema-core] ${f.site}: delegation-lifecycle observer threw (contained; further failures counted, not re-disclosed): ${f.error.message}`),
                 }), "runtask.onDelegationLifecycle");
             }
+            if (forwardsSubagentEvents(spec))
+                await drainForwardedFramesBeforeDone();
             queue.push({ type: "done", result: resultValue });
             queue.close();
         });
@@ -4276,6 +4279,8 @@ export class Runner {
                 drainManualCompact("mooted");
             }
             manualCompactRef.emitMooted = undefined;
+            if (forwardsSubagentEvents(spec))
+                await drainForwardedFramesBeforeDone();
             queue.push({ type: "done", result });
             queue.close();
             await prepared.fileHistoryBoundary?.settle();
@@ -4983,7 +4988,7 @@ export class Runner {
         if (plainPolicyOutcome !== undefined) {
             const parkedOrigin = cp.pendingAction.kind === "tool_approval" ? cp.pendingAction.origin : undefined;
             if (!isAskOrigin(parkedOrigin)) {
-                throw new CheckpointError("checkpoint.unsupported_version", "this checkpoint's pending approval carries no origin word (a row minted before the ask's origin was persisted on the park) — its settlement cannot be recorded; the checkpoint stays pending");
+                throw new CheckpointError("checkpoint.unsupported_version", "this checkpoint's pending approval carries no origin word (a row minted before the ask's origin was persisted on the park) — its settlement cannot be recorded; the checkpoint stays pending", { reason: "origin_missing" });
             }
             const facts = plainPolicyOutcome.hostDecision;
             const approverCell = facts.approver !== undefined ? { approver: facts.approver } : {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.6.1",
+  "version": "7.6.3",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",