@exaudeus/workrail 3.73.1 → 3.74.0

package/dist/v2/durable-core/schemas/export-bundle/index.d.ts

@@ -2567,6 +2567,62 @@ export declare const SessionContentsV1Schema: z.ZodObject<{
             durationMs?: number | undefined;
         };
         timestampMs: number;
+    }>, z.ZodObject<{
+        v: z.ZodLiteral<1>;
+        eventId: z.ZodString;
+        eventIndex: z.ZodNumber;
+        sessionId: z.ZodString;
+        dedupeKey: z.ZodString;
+        timestampMs: z.ZodNumber;
+    } & {
+        kind: z.ZodLiteral<"delivery_recorded">;
+        scope: z.ZodObject<{
+            runId: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            runId: string;
+        }, {
+            runId: string;
+        }>;
+        data: z.ZodObject<{
+            shas: z.ZodArray<z.ZodString, "many">;
+            prUrl: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            shas: string[];
+            prUrl?: string | undefined;
+        }, {
+            shas: string[];
+            prUrl?: string | undefined;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "delivery_recorded";
+        v: 1;
+        sessionId: string;
+        eventIndex: number;
+        eventId: string;
+        dedupeKey: string;
+        scope: {
+            runId: string;
+        };
+        data: {
+            shas: string[];
+            prUrl?: string | undefined;
+        };
+        timestampMs: number;
+    }, {
+        kind: "delivery_recorded";
+        v: 1;
+        sessionId: string;
+        eventIndex: number;
+        eventId: string;
+        dedupeKey: string;
+        scope: {
+            runId: string;
+        };
+        data: {
+            shas: string[];
+            prUrl?: string | undefined;
+        };
+        timestampMs: number;
     }>]>, "many">;
     manifest: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         v: z.ZodLiteral<1>;
@@ -5311,6 +5367,21 @@ export declare const SessionContentsV1Schema: z.ZodObject<{
             durationMs?: number | undefined;
         };
         timestampMs: number;
+    } | {
+        kind: "delivery_recorded";
+        v: 1;
+        sessionId: string;
+        eventIndex: number;
+        eventId: string;
+        dedupeKey: string;
+        scope: {
+            runId: string;
+        };
+        data: {
+            shas: string[];
+            prUrl?: string | undefined;
+        };
+        timestampMs: number;
     })[];
     manifest: ({
         kind: "segment_closed";
@@ -5925,6 +5996,21 @@ export declare const SessionContentsV1Schema: z.ZodObject<{
             durationMs?: number | undefined;
         };
         timestampMs: number;
+    } | {
+        kind: "delivery_recorded";
+        v: 1;
+        sessionId: string;
+        eventIndex: number;
+        eventId: string;
+        dedupeKey: string;
+        scope: {
+            runId: string;
+        };
+        data: {
+            shas: string[];
+            prUrl?: string | undefined;
+        };
+        timestampMs: number;
     })[];
     manifest: ({
         kind: "segment_closed";
@@ -8504,6 +8590,62 @@ export declare const ExportBundleV1Schema: z.ZodObject<{
                 durationMs?: number | undefined;
             };
             timestampMs: number;
+        }>, z.ZodObject<{
+            v: z.ZodLiteral<1>;
+            eventId: z.ZodString;
+            eventIndex: z.ZodNumber;
+            sessionId: z.ZodString;
+            dedupeKey: z.ZodString;
+            timestampMs: z.ZodNumber;
+        } & {
+            kind: z.ZodLiteral<"delivery_recorded">;
+            scope: z.ZodObject<{
+                runId: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                runId: string;
+            }, {
+                runId: string;
+            }>;
+            data: z.ZodObject<{
+                shas: z.ZodArray<z.ZodString, "many">;
+                prUrl: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                shas: string[];
+                prUrl?: string | undefined;
+            }, {
+                shas: string[];
+                prUrl?: string | undefined;
+            }>;
+        }, "strip", z.ZodTypeAny, {
+            kind: "delivery_recorded";
+            v: 1;
+            sessionId: string;
+            eventIndex: number;
+            eventId: string;
+            dedupeKey: string;
+            scope: {
+                runId: string;
+            };
+            data: {
+                shas: string[];
+                prUrl?: string | undefined;
+            };
+            timestampMs: number;
+        }, {
+            kind: "delivery_recorded";
+            v: 1;
+            sessionId: string;
+            eventIndex: number;
+            eventId: string;
+            dedupeKey: string;
+            scope: {
+                runId: string;
+            };
+            data: {
+                shas: string[];
+                prUrl?: string | undefined;
+            };
+            timestampMs: number;
         }>]>, "many">;
         manifest: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
             v: z.ZodLiteral<1>;
@@ -11248,6 +11390,21 @@ export declare const ExportBundleV1Schema: z.ZodObject<{
                 durationMs?: number | undefined;
             };
             timestampMs: number;
+        } | {
+            kind: "delivery_recorded";
+            v: 1;
+            sessionId: string;
+            eventIndex: number;
+            eventId: string;
+            dedupeKey: string;
+            scope: {
+                runId: string;
+            };
+            data: {
+                shas: string[];
+                prUrl?: string | undefined;
+            };
+            timestampMs: number;
         })[];
         manifest: ({
             kind: "segment_closed";
@@ -11862,6 +12019,21 @@ export declare const ExportBundleV1Schema: z.ZodObject<{
                 durationMs?: number | undefined;
             };
             timestampMs: number;
+        } | {
+            kind: "delivery_recorded";
+            v: 1;
+            sessionId: string;
+            eventIndex: number;
+            eventId: string;
+            dedupeKey: string;
+            scope: {
+                runId: string;
+            };
+            data: {
+                shas: string[];
+                prUrl?: string | undefined;
+            };
+            timestampMs: number;
         })[];
         manifest: ({
             kind: "segment_closed";
@@ -12490,6 +12662,21 @@ export declare const ExportBundleV1Schema: z.ZodObject<{
                 durationMs?: number | undefined;
             };
             timestampMs: number;
+        } | {
+            kind: "delivery_recorded";
+            v: 1;
+            sessionId: string;
+            eventIndex: number;
+            eventId: string;
+            dedupeKey: string;
+            scope: {
+                runId: string;
+            };
+            data: {
+                shas: string[];
+                prUrl?: string | undefined;
+            };
+            timestampMs: number;
         })[];
         manifest: ({
             kind: "segment_closed";
@@ -13121,6 +13308,21 @@ export declare const ExportBundleV1Schema: z.ZodObject<{
                 durationMs?: number | undefined;
             };
             timestampMs: number;
+        } | {
+            kind: "delivery_recorded";
+            v: 1;
+            sessionId: string;
+            eventIndex: number;
+            eventId: string;
+            dedupeKey: string;
+            scope: {
+                runId: string;
+            };
+            data: {
+                shas: string[];
+                prUrl?: string | undefined;
+            };
+            timestampMs: number;
         })[];
         manifest: ({
             kind: "segment_closed";

package/dist/v2/durable-core/schemas/session/events.d.ts

@@ -2555,5 +2555,61 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         durationMs?: number | undefined;
     };
     timestampMs: number;
+}>, z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    eventId: z.ZodString;
+    eventIndex: z.ZodNumber;
+    sessionId: z.ZodString;
+    dedupeKey: z.ZodString;
+    timestampMs: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"delivery_recorded">;
+    scope: z.ZodObject<{
+        runId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        runId: string;
+    }, {
+        runId: string;
+    }>;
+    data: z.ZodObject<{
+        shas: z.ZodArray<z.ZodString, "many">;
+        prUrl: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        shas: string[];
+        prUrl?: string | undefined;
+    }, {
+        shas: string[];
+        prUrl?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    kind: "delivery_recorded";
+    v: 1;
+    sessionId: string;
+    eventIndex: number;
+    eventId: string;
+    dedupeKey: string;
+    scope: {
+        runId: string;
+    };
+    data: {
+        shas: string[];
+        prUrl?: string | undefined;
+    };
+    timestampMs: number;
+}, {
+    kind: "delivery_recorded";
+    v: 1;
+    sessionId: string;
+    eventIndex: number;
+    eventId: string;
+    dedupeKey: string;
+    scope: {
+        runId: string;
+    };
+    data: {
+        shas: string[];
+        prUrl?: string | undefined;
+    };
+    timestampMs: number;
 }>]>;
 export type DomainEventV1 = z.infer<typeof DomainEventV1Schema>;

package/dist/v2/durable-core/schemas/session/events.js

@@ -274,4 +274,12 @@ exports.DomainEventV1Schema = zod_1.z.discriminatedUnion('kind', [
             }
         }),
     }),
+    exports.DomainEventEnvelopeV1Schema.extend({
+        kind: zod_1.z.literal('delivery_recorded'),
+        scope: zod_1.z.object({ runId: zod_1.z.string().min(1) }),
+        data: zod_1.z.object({
+            shas: zod_1.z.array(zod_1.z.string()),
+            prUrl: zod_1.z.string().optional(),
+        }),
+    }),
 ]);

package/dist/v2/infra/local/git-snapshot/index.d.ts

@@ -0,0 +1,6 @@
+import type { GitEndSnapshot, GitSnapshotPortV2 } from '../../../ports/git-snapshot.port.js';
+export declare class LocalGitSnapshotV2 implements GitSnapshotPortV2 {
+    resolveEndSnapshot(repoRoot: string | null, startSha: string | null): Promise<GitEndSnapshot>;
+    private resolveEndSha;
+    private resolveCommitRange;
+}

package/dist/v2/infra/local/git-snapshot/index.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalGitSnapshotV2 = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+const GIT_TIMEOUT_MS = 2000;
+class LocalGitSnapshotV2 {
+    async resolveEndSnapshot(repoRoot, startSha) {
+        if (!repoRoot)
+            return { endSha: null, commitShas: [] };
+        const [endSha, commitShas] = await Promise.all([
+            this.resolveEndSha(repoRoot),
+            this.resolveCommitRange(repoRoot, startSha),
+        ]);
+        return { endSha, commitShas };
+    }
+    async resolveEndSha(repoRoot) {
+        try {
+            const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: repoRoot, timeout: GIT_TIMEOUT_MS });
+            return stdout.trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async resolveCommitRange(repoRoot, startSha) {
+        if (!startSha)
+            return [];
+        try {
+            const { stdout } = await execFileAsync('git', ['log', '--no-merges', '--first-parent', `${startSha}..HEAD`, '--format=%H'], { cwd: repoRoot, timeout: GIT_TIMEOUT_MS });
+            return stdout.trim().split('\n').filter(s => s.length > 0);
+        }
+        catch {
+            return [];
+        }
+    }
+}
+exports.LocalGitSnapshotV2 = LocalGitSnapshotV2;

package/dist/v2/ports/git-snapshot.port.d.ts

@@ -0,0 +1,10 @@
+export interface GitEndSnapshot {
+    readonly endSha: string | null;
+    readonly commitShas: readonly string[];
+}
+export interface GitSnapshotPortV2 {
+    resolveEndSnapshot(repoRoot: string | null, startSha: string | null): Promise<GitEndSnapshot>;
+}
+export declare class NullGitSnapshotV2 implements GitSnapshotPortV2 {
+    resolveEndSnapshot(): Promise<GitEndSnapshot>;
+}

package/dist/v2/ports/git-snapshot.port.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NullGitSnapshotV2 = void 0;
+class NullGitSnapshotV2 {
+    async resolveEndSnapshot() {
+        return { endSha: null, commitShas: [] };
+    }
+}
+exports.NullGitSnapshotV2 = NullGitSnapshotV2;

package/dist/v2/projections/session-metrics.js

@@ -52,6 +52,18 @@ function projectSessionMetricsV2(events) {
             }
         }
     }
+    let deliveryShas = [];
+    for (const e of events) {
+        if (e.kind !== constants_js_1.EVENT_KIND.DELIVERY_RECORDED)
+            continue;
+        if (e.scope?.runId !== runCompletedRunId)
+            continue;
+        const shasRaw = e.data.shas;
+        if (Array.isArray(shasRaw)) {
+            deliveryShas = shasRaw.filter((s) => typeof s === 'string');
+        }
+        break;
+    }
     const commitShasRaw = metricsContext['metrics_commit_shas'];
     const metricCommitShas = [];
     if (Array.isArray(commitShasRaw)) {
@@ -60,19 +72,22 @@ function projectSessionMetricsV2(events) {
                 metricCommitShas.push(sha);
         }
     }
-    const finalAgentCommitShas = metricCommitShas.length > 0 ? metricCommitShas : agentCommitShas;
+    const finalAgentCommitShas = deliveryShas.length > 0 ? deliveryShas :
+        metricCommitShas.length > 0 ? metricCommitShas :
+            agentCommitShas;
     const filesChangedRaw = metricsContext['metrics_files_changed'];
     const filesChanged = typeof filesChangedRaw === 'number' && Number.isFinite(filesChangedRaw) ? filesChangedRaw : null;
     const linesAddedRaw = metricsContext['metrics_lines_added'];
     const linesAdded = typeof linesAddedRaw === 'number' && Number.isFinite(linesAddedRaw) ? linesAddedRaw : null;
     const linesRemovedRaw = metricsContext['metrics_lines_removed'];
     const linesRemoved = typeof linesRemovedRaw === 'number' && Number.isFinite(linesRemovedRaw) ? linesRemovedRaw : null;
+    const finalCaptureConfidence = deliveryShas.length > 0 ? 'high' : captureConfidence;
     return {
         startGitSha,
         endGitSha,
         gitBranch,
         agentCommitShas: finalAgentCommitShas,
-        captureConfidence,
+        captureConfidence: finalCaptureConfidence,
         durationMs,
         outcome,
         prNumbers,

package/docs/authoring.md

@@ -761,6 +761,28 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 
 
 ## Artifacts and planning surfaces
+### coordinator-result-artifact-schema
+- **Level**: required
+- **Status**: active
+- **Scope**: artifact.coordinator-result
+- **Rule**: When a workflow step signals coordinator phase completion, emit a `wr.coordinator_result` artifact with exactly 4 fields: `outcome` (enum: success|failed|timed_out|await_degraded), `summary` (string), `sessionId` (string), `error` (string|null). No additional fields allowed.
+- **Why**: Coordinators read this artifact to determine whether to proceed, retry, or escalate. Extra fields pollute the schema boundary and break forward compatibility. The 4-field constraint is a hard limit, not a guideline.
+- **Enforced by**: advisory
+
+**Checks**
+- Exactly 4 fields present: outcome, summary, sessionId, error.
+- outcome is one of: success, failed, timed_out, await_degraded.
+- error is string|null -- null when outcome is success, non-null string when outcome is failed.
+- No workflow-specific fields (prUrl, branchName, commitSha, etc.) in wr.coordinator_result. Those belong in workflow-specific artifacts.
+
+**Anti-patterns**
+- Adding prUrl, branchName, or commitSha to wr.coordinator_result
+- Using a free-form notes string instead of the typed outcome enum
+- Omitting sessionId (required for coordinator tracing and console parent-child display)
+
+**Source refs**
+- `src/coordinators/types.ts` (runtime) — ChildSessionResult discriminated union -- the runtime type that wr.coordinator_result maps to.
+
 ### artifact-canonicality
 - **Level**: recommended
 - **Status**: active
@@ -913,6 +935,7 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 - `artifact.plan`: Implementation-planning artifacts
 - `artifact.spec`: Behavior/specification artifacts
 - `artifact.verification`: Verification or handoff artifacts
+- `artifact.coordinator-result`: wr.coordinator_result artifact emitted by coordinator-phase workflows to signal phase completion to the coordinator
 - `delegation.context-packet`: Structured context passed to subagents
 - `delegation.result-envelope`: Structured result shape returned by subagents
 - `legacy.patterns`: Older authoring patterns that should now be discouraged or avoided

package/docs/design/engine-boundary-discovery.md

@@ -0,0 +1,123 @@
+# Engine Boundary Discovery: SHA Tracking and Layer Architecture
+
+**Date:** 2026-04-30
+**Status:** Discovery complete -- recommendation: A now (PR #903), C next
+**Goal:** Determine the right architecture for commit SHA tracking and clarify engine/coordinator/delivery layer boundaries
+
+---
+
+## Problem Understanding
+
+### The Real Problem
+The engine emits `run_completed` at step T. The delivery pipeline commits to git at step T+1. There is no mechanism to communicate back from T+1 to T. Agent self-reporting of `metrics_commit_shas` was the broken workaround.
+
+### Core Tensions
+1. **Information completeness vs engine purity**: commits only exist after delivery, which is after `run_completed`
+2. **YAGNI vs architectural completeness**: MCP sessions may not need SHA tracking right now
+3. **Port purity vs pragmatism**: `outcome-success.ts` already calls `execFile` directly for `endGitSha` -- known violation
+4. **Atomic delivery vs distributed write-back**: appending after `run_completed` requires the session gate to remain open
+
+### What Makes This Hard
+The gap is temporal. Information that belongs to session T becomes available at T+1. The event log is append-only but NOT closed after `run_completed` -- `ExecutionSessionGateV2` gates on `healthy` vs `corrupt`, not on completion state. Post-completion appends ARE valid.
+
+---
+
+## Architecture Contract (what exists, what's missing)
+
+### Engine owns (src/v2/durable-core/ + src/mcp/handlers/):
+- Session lifecycle (start, advance, checkpoint, resume)
+- HMAC token protocol -- cryptographic enforcement
+- Append-only event log with crash-safe writes
+- Port abstractions for all I/O (no direct fs/git/network calls in engine)
+- Projections: reads event log, produces typed views
+- **Records observations it can make directly**: git_branch, git_head_sha (via WorkspaceContextResolverPortV2 at START); endGitSha (via execFile direct call at END -- known port violation)
+
+### Coordinator/delivery layer owns (src/trigger/ + src/daemon/):
+- Git commits, pushes, PR creation
+- Delivery pipeline stages
+- SHA extraction from `git commit` output
+- Proof records, pipeline orchestration (future)
+- Agent loop, context injection, crash recovery
+
+### The gap:
+No mechanism for the delivery layer to record its observations (what it committed) back into the session event log.
+
+---
+
+## Philosophy Constraints
+
+- **Architectural fixes over patches**: always-empty is a patch; extending the port is the fix
+- **Dependency injection for boundaries**: git I/O must be behind a port in the engine layer
+- **Make illegal states unrepresentable**: `captureConfidence: 'high'` with `agentCommitShas: []` is already schema-enforced as invalid
+- **Validate at boundaries, trust inside**: SHA derivation must happen at the git boundary, never from agent memory
+- **YAGNI with discipline**: don't build write-back infrastructure until coordinators actually consume it
+
+---
+
+## Candidates
+
+### A: Always-empty (current PR #903)
+Engine emits `agentCommitShas: []` and `captureConfidence: 'none'` always. Console shows no SHAs. Coordinator scripts derive SHAs from `git log startSha..endSha` themselves.
+
+- **Tensions resolved**: engine purity, illegal states, YAGNI
+- **Tensions accepted**: information completeness, worktree-after-cleanup risk
+- **Failure mode**: worktree cleaned up before coordinator script runs `git log`
+- **Scope**: best-fit immediate fix; patch not architectural fix
+- **Philosophy**: honors YAGNI, make-illegal-states-unrepresentable. Conflicts with architectural-fixes-over-patches.
+
+### B: Delivery write-back via DeliveryStage
+New 5th DeliveryStage appends `observation_recorded` event with `git_commit_shas` to session event log after successful `git commit`. Requires injecting `SessionEventLogAppendStorePortV2` into `DeliveryPipeline`.
+
+- **Tensions resolved**: information completeness (daemon sessions), crash safety (stage before sidecar delete)
+- **Tensions accepted**: delivery-action API change (new session store dependency); MCP sessions still get no SHAs
+- **Failure mode**: append fails silently if session health degraded (must be best-effort, never abort delivery)
+- **Scope**: best-fit for daemon/autoCommit sessions; accepted gap for MCP
+- **Philosophy**: honors architectural-fixes-over-patches, dependency-injection. Mild YAGNI tension.
+
+### C: Extend WorkspaceContextResolverPortV2 with end-state (port-correct fix)
+Add `resolveEndState(repoRoot, startSha) -> { endSha, commitShas }` to the workspace anchor port (or create `GitSnapshotPortV2`). Inject into `outcome-success.ts`. Runs `git rev-parse HEAD` + `git log startSha..HEAD --format=%H` in parallel. `run_completed` event gets `commitShas: string[]` field.
+
+- **Tensions resolved**: engine purity (eliminates execFile violation), information completeness (all session types), MCP + daemon covered
+- **Tensions accepted**: run_completed schema gets new field; old sessions project `commitShas: []` (non-breaking)
+- **Failure mode**: `git log startSha..HEAD` may include merge commits or upstream advances; use `--no-merges --first-parent` to scope
+- **Scope**: slightly broader than needed (touches port contract) but correct -- each piece is load-bearing
+- **Philosophy**: honors architectural-fixes-over-patches, dependency-injection-for-boundaries, make-illegal-states-unrepresentable.
+
+### D: Delivery sidecar store (reframe -- REJECTED)
+Delivery writes `delivery-result-<sessionId>.json` sidecar. Session-metrics reads from both event log and sidecar. REJECTED: violates single-source-of-truth principle for the event log. Two truth sources for SHA data is architecturally unsound for this codebase.
+
+---
+
+## Comparison and Recommendation
+
+**Recommendation: A now (PR #903 as-is), C next.**
+
+C is the architectural ideal because:
+1. Solves both problems simultaneously: SHA gap AND the existing execFile violation in outcome-success.ts
+2. Works for ALL session types (MCP + daemon) without special-casing
+3. Follows the port pattern the codebase is designed around
+4. run_completed is the correct home -- startGitSha is already there, endGitSha is already there, commitShas belongs alongside them
+
+B is viable but inferior: adds a session store dependency to the delivery layer (which currently has none), only covers daemon/autoCommit sessions, and has a semantic question (delivery artifacts vs session truth).
+
+A is correct as the IMMEDIATE state. PR #903 should merge. It makes the illegal state (high confidence + empty SHAs) impossible, and clears the field for C.
+
+**The original question -- do we need to split the engine? -- is NO.** The current architecture is sound. The fix is a port extension, not a structural split.
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument against C**: run_completed schema migration. Existing stored events lack `commitShas`. Rebuttal: session-metrics projection already handles absent fields (defaults to []). Adding `commitShas?: string[]` is non-breaking additive.
+
+**What would tip to B**: if daemon sessions with autoCommit dominate and MCP sessions never need SHAs. Currently autoCommit is daemon-only, so B's coverage gap is acceptable. But if MCP sessions start running in worktrees with autoCommit, B becomes wrong.
+
+**Invalidating assumption**: if `git log startSha..HEAD` includes upstream merge commits, SHAs from unrelated PRs land in the session's record. Mitigation: `--no-merges --first-parent` in the port implementation.
+
+---
+
+## Open Questions
+
+1. Should `GitSnapshotPortV2` be a new port or an extension of `WorkspaceContextResolverPortV2`? New port has cleaner separation; extension avoids proliferating ports.
+2. What is the right git log filter for commit SHAs: `--no-merges`, `--first-parent`, both? Depends on whether merge commits from squash-merge PRs should be included.
+3. Should Candidate C be implemented now (before PR #903 merges) or after? After is safer -- PR #903 is already in CI, touching outcome-success.ts again would create a dirty merge.

package/docs/design/engine-boundary-review-findings.md

@@ -0,0 +1,72 @@
+# Engine Boundary Discovery: Design Review Findings
+
+**Date:** 2026-04-30
+**Decision:** A now (PR #903), C next (GitSnapshotPortV2)
+**Confidence:** HIGH
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Acceptable? | Invalidating condition |
+|---|---|---|
+| Console shows empty SHAs until C is built | Yes -- empty is honest, no current consumer needs populated SHAs | Proof records feature built before C |
+| MCP sessions get no SHAs under A-only | Yes -- human can check git; MCP is not the autonomous use case | MCP sessions start requiring attribution for proof records |
+| run_completed schema gets optional field | Yes -- non-breaking additive change; old sessions project [] | Schema versioning feature enforces strict field presence |
+
+All tradeoffs acceptable under current conditions.
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Coverage | Risk |
+|---|---|---|
+| git log includes upstream merge commits | Mitigate with `--no-merges --first-parent` in port implementation | MEDIUM -- must be in the implementation spec |
+| outcome-success.ts partial failure (endGitSha or commitShas fails) | Promise.all + best-effort; both degrade to null/[] independently | LOW -- same behavior as current resolveEndGitSha |
+
+**Highest-risk**: FM1. Must specify `--no-merges --first-parent` explicitly in Candidate C implementation.
+
+---
+
+## Runner-up / Simpler Alternative Review
+
+- B (delivery write-back): no elements worth borrowing. Its coupling (session store injected into delivery layer) is the problem C avoids.
+- Simpler C variant (fix execFile violation only, skip commitShas): would require a second port extension later. Marginal cost of doing both at once is low. Not simpler enough to justify the incompleteness.
+- No hybrid warranted. A-then-C sequencing is correct.
+
+---
+
+## Philosophy Alignment
+
+**Satisfied**: make-illegal-states-unrepresentable, validate-at-boundaries, errors-as-data, dependency-injection-for-boundaries, architectural-fixes-over-patches.
+
+**Under acceptable tension**: YAGNI (building port before proof records consume it -- justified by dual purpose: also fixes execFile violation). Immutability (appending to completed session -- design-correct, session gate confirms).
+
+---
+
+## Findings
+
+### YELLOW: git log filter not specified
+The implementation of Candidate C's `resolveCommitShaRange` must use `--no-merges --first-parent` to avoid including upstream merge commits. This is not currently specified anywhere. Without it, sessions on branches with merge commits from main would record incorrect SHAs.
+**Action**: add explicit filter spec to the Candidate C implementation ticket.
+
+### YELLOW: No forcing function to build C after A merges
+PR #903 will merge. C is the architectural fix. Without a ticket, C may never get built and the console SHA display stays empty indefinitely.
+**Action**: create a GitHub issue for Candidate C immediately after PR #903 merges.
+
+---
+
+## Recommended Revisions to Selected Design
+
+1. Before implementing C: specify `--no-merges --first-parent` as the required git log filter in the issue description
+2. New port name: `GitSnapshotPortV2` is cleaner than extending `WorkspaceContextResolverPortV2` -- keeps the end-state capture concern separate from the start-state anchor concern
+3. New method signature: `resolveEndSnapshot(repoRoot: string, startSha: string): Promise<{ endSha: string | null, commitShas: string[] }>`
+4. In `outcome-success.ts`: replace `resolveEndGitSha` with `resolveEndSnapshot` -- single port call that returns both `endGitSha` and `commitShas` in parallel
+
+---
+
+## Residual Concerns
+
+- **Architecture contract not written**: the meta-fix (documenting what the engine layer owns vs coordinator/delivery) has not been done. This is the most important long-term outcome from this discovery. Without it, future contributors will make the same boundary violations. Should be added to `docs/design/v2-core-design-locks.md`.
+- **C has open design question**: `GitSnapshotPortV2` vs extension of `WorkspaceContextResolverPortV2`. Both work. `GitSnapshotPortV2` is slightly cleaner (separate port, separate concern). Decision can be made at implementation time.