@exaudeus/workrail 3.35.0 → 3.36.0

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

@@ -60,10 +60,18 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
     }>>;
 } & {
     kind: z.ZodLiteral<"session_created">;
-    data: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    data: z.ZodObject<{
+        parentSessionId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        parentSessionId?: string | undefined;
+    }, {
+        parentSessionId?: string | undefined;
+    }>;
 }, "strip", z.ZodTypeAny, {
     kind: "session_created";
-    data: {};
+    data: {
+        parentSessionId?: string | undefined;
+    };
     v: 1;
     sessionId: string;
     eventIndex: number;
@@ -75,7 +83,9 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
     } | undefined;
 }, {
     kind: "session_created";
-    data: {};
+    data: {
+        parentSessionId?: string | undefined;
+    };
     v: 1;
     sessionId: string;
     eventIndex: number;
@@ -1834,12 +1844,12 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             category: "user_only_dependency";
         }>, z.ZodObject<{
             category: z.ZodLiteral<"contract_violation">;
-            detail: z.ZodEnum<["missing_required_output", "invalid_required_output", "missing_required_notes"]>;
+            detail: z.ZodEnum<["missing_required_output", "invalid_required_output", "missing_required_notes", "assessment_followup_required"]>;
         }, "strip", z.ZodTypeAny, {
-            detail: "invalid_required_output" | "missing_required_output" | "missing_required_notes";
+            detail: "invalid_required_output" | "missing_required_output" | "assessment_followup_required" | "missing_required_notes";
             category: "contract_violation";
         }, {
-            detail: "invalid_required_output" | "missing_required_output" | "missing_required_notes";
+            detail: "invalid_required_output" | "missing_required_output" | "assessment_followup_required" | "missing_required_notes";
             category: "contract_violation";
         }>, z.ZodObject<{
             category: z.ZodLiteral<"capability_missing">;
@@ -1902,7 +1912,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             detail: "needs_user_secret_or_token" | "needs_user_account_access" | "needs_user_artifact" | "needs_user_choice" | "needs_user_approval" | "needs_user_environment_action";
             category: "user_only_dependency";
         } | {
-            detail: "invalid_required_output" | "missing_required_output" | "missing_required_notes";
+            detail: "invalid_required_output" | "missing_required_output" | "assessment_followup_required" | "missing_required_notes";
             category: "contract_violation";
         } | {
             detail: "required_capability_unknown" | "required_capability_unavailable";
@@ -1932,7 +1942,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             detail: "needs_user_secret_or_token" | "needs_user_account_access" | "needs_user_artifact" | "needs_user_choice" | "needs_user_approval" | "needs_user_environment_action";
             category: "user_only_dependency";
         } | {
-            detail: "invalid_required_output" | "missing_required_output" | "missing_required_notes";
+            detail: "invalid_required_output" | "missing_required_output" | "assessment_followup_required" | "missing_required_notes";
             category: "contract_violation";
         } | {
             detail: "required_capability_unknown" | "required_capability_unavailable";
@@ -1965,7 +1975,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             detail: "needs_user_secret_or_token" | "needs_user_account_access" | "needs_user_artifact" | "needs_user_choice" | "needs_user_approval" | "needs_user_environment_action";
             category: "user_only_dependency";
         } | {
-            detail: "invalid_required_output" | "missing_required_output" | "missing_required_notes";
+            detail: "invalid_required_output" | "missing_required_output" | "assessment_followup_required" | "missing_required_notes";
             category: "contract_violation";
         } | {
             detail: "required_capability_unknown" | "required_capability_unavailable";
@@ -2007,7 +2017,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             detail: "needs_user_secret_or_token" | "needs_user_account_access" | "needs_user_artifact" | "needs_user_choice" | "needs_user_approval" | "needs_user_environment_action";
             category: "user_only_dependency";
         } | {
-            detail: "invalid_required_output" | "missing_required_output" | "missing_required_notes";
+            detail: "invalid_required_output" | "missing_required_output" | "assessment_followup_required" | "missing_required_notes";
             category: "contract_violation";
         } | {
             detail: "required_capability_unknown" | "required_capability_unavailable";

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

@@ -102,7 +102,7 @@ const PreferencesChangedDataV1Schema = zod_1.z
     }
 });
 exports.DomainEventV1Schema = zod_1.z.discriminatedUnion('kind', [
-    exports.DomainEventEnvelopeV1Schema.extend({ kind: zod_1.z.literal('session_created'), data: zod_1.z.object({}) }),
+    exports.DomainEventEnvelopeV1Schema.extend({ kind: zod_1.z.literal('session_created'), data: zod_1.z.object({ parentSessionId: zod_1.z.string().optional() }) }),
     exports.DomainEventEnvelopeV1Schema.extend({
         kind: zod_1.z.literal('observation_recorded'),
         scope: zod_1.z.undefined(),

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

@@ -11,12 +11,12 @@ export declare const GapReasonSchema: z.ZodDiscriminatedUnion<"category", [z.Zod
     category: "user_only_dependency";
 }>, z.ZodObject<{
     category: z.ZodLiteral<"contract_violation">;
-    detail: z.ZodEnum<["missing_required_output", "invalid_required_output", "missing_required_notes"]>;
+    detail: z.ZodEnum<["missing_required_output", "invalid_required_output", "missing_required_notes", "assessment_followup_required"]>;
 }, "strip", z.ZodTypeAny, {
-    detail: "invalid_required_output" | "missing_required_output" | "missing_required_notes";
+    detail: "invalid_required_output" | "missing_required_output" | "assessment_followup_required" | "missing_required_notes";
     category: "contract_violation";
 }, {
-    detail: "invalid_required_output" | "missing_required_output" | "missing_required_notes";
+    detail: "invalid_required_output" | "missing_required_output" | "assessment_followup_required" | "missing_required_notes";
     category: "contract_violation";
 }>, z.ZodObject<{
     category: z.ZodLiteral<"capability_missing">;
@@ -86,12 +86,12 @@ export declare const GapRecordedDataV1Schema: z.ZodObject<{
         category: "user_only_dependency";
     }>, z.ZodObject<{
         category: z.ZodLiteral<"contract_violation">;
-        detail: z.ZodEnum<["missing_required_output", "invalid_required_output", "missing_required_notes"]>;
+        detail: z.ZodEnum<["missing_required_output", "invalid_required_output", "missing_required_notes", "assessment_followup_required"]>;
     }, "strip", z.ZodTypeAny, {
-        detail: "invalid_required_output" | "missing_required_output" | "missing_required_notes";
+        detail: "invalid_required_output" | "missing_required_output" | "assessment_followup_required" | "missing_required_notes";
         category: "contract_violation";
     }, {
-        detail: "invalid_required_output" | "missing_required_output" | "missing_required_notes";
+        detail: "invalid_required_output" | "missing_required_output" | "assessment_followup_required" | "missing_required_notes";
         category: "contract_violation";
     }>, z.ZodObject<{
         category: z.ZodLiteral<"capability_missing">;
@@ -154,7 +154,7 @@ export declare const GapRecordedDataV1Schema: z.ZodObject<{
         detail: "needs_user_secret_or_token" | "needs_user_account_access" | "needs_user_artifact" | "needs_user_choice" | "needs_user_approval" | "needs_user_environment_action";
         category: "user_only_dependency";
     } | {
-        detail: "invalid_required_output" | "missing_required_output" | "missing_required_notes";
+        detail: "invalid_required_output" | "missing_required_output" | "assessment_followup_required" | "missing_required_notes";
         category: "contract_violation";
     } | {
         detail: "required_capability_unknown" | "required_capability_unavailable";
@@ -184,7 +184,7 @@ export declare const GapRecordedDataV1Schema: z.ZodObject<{
         detail: "needs_user_secret_or_token" | "needs_user_account_access" | "needs_user_artifact" | "needs_user_choice" | "needs_user_approval" | "needs_user_environment_action";
         category: "user_only_dependency";
     } | {
-        detail: "invalid_required_output" | "missing_required_output" | "missing_required_notes";
+        detail: "invalid_required_output" | "missing_required_output" | "assessment_followup_required" | "missing_required_notes";
         category: "contract_violation";
     } | {
         detail: "required_capability_unknown" | "required_capability_unavailable";

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

@@ -12,7 +12,7 @@ exports.UserOnlyDependencyReasonSchema = zod_1.z.enum([
 ]);
 exports.GapReasonSchema = zod_1.z.discriminatedUnion('category', [
     zod_1.z.object({ category: zod_1.z.literal('user_only_dependency'), detail: exports.UserOnlyDependencyReasonSchema }),
-    zod_1.z.object({ category: zod_1.z.literal('contract_violation'), detail: zod_1.z.enum(['missing_required_output', 'invalid_required_output', 'missing_required_notes']) }),
+    zod_1.z.object({ category: zod_1.z.literal('contract_violation'), detail: zod_1.z.enum(['missing_required_output', 'invalid_required_output', 'missing_required_notes', 'assessment_followup_required']) }),
     zod_1.z.object({
         category: zod_1.z.literal('capability_missing'),
         detail: zod_1.z.enum(['required_capability_unavailable', 'required_capability_unknown']),

package/docs/ideas/backlog.md

@@ -4975,3 +4975,253 @@ Long-term (when mobile exists):
 ```
 
 **Build order:** outbox.jsonl integration (foundation, works everywhere) → generic webhook (covers Slack/Discord/Teams/anything) → platform notifications (macOS/Linux/Windows) → mobile app push (when mobile exists).
+
+---
+
+## 🎉 WorkTrain first confirmed end-to-end autonomous session (Apr 18, 2026)
+
+**Timestamp:** 2026-04-18T15:09:49Z  
+**Commit:** `473f4bd0` (main)  
+**npm version:** v3.34.1 (published, installable by anyone)  
+**What happened:** A real MR review workflow (`mr-review-workflow-agentic`) ran completely autonomously via webhook trigger, advanced through all phases (context gathering, review, synthesis, validation, handoff), self-validated, and produced a structured finding set. 8 step advances, `outcome: success`.
+
+**Trigger:** `POST /webhook/mr-review {"goal": "Review PR #566: fix two minor bugs..."}`  
+**Session:** `sess_3bmjuzf7l2vrqynjtleg5iskm4`  
+**Result:** APPROVE with High confidence. 3 Minor findings, 1 Informational. Correctly decided not to delegate since no Critical/Major issues.
+
+---
+
+### What works at this commit
+
+- ✅ Daemon accepts webhooks, starts sessions, runs workflows end-to-end
+- ✅ Sessions advance through all workflow phases autonomously
+- ✅ `mr-review-workflow-agentic` v2.6 runs fully -- context gathering, review phases, synthesis loop, validation, handoff
+- ✅ `wr.discovery` v3.2.0 runs fully -- with new phase-0-reframe (goal reframing before research)
+- ✅ Console shows live sessions via event log (no daemon connection required)
+- ✅ MCP server is stable (bridge removed, EPIPE fixed, v3.34.1 published)
+- ✅ GitHub + GitLab polling triggers (no webhooks needed)
+- ✅ `worktrain init`, `tell`, `inbox`, `spawn`, `await` CLI commands
+- ✅ Stuck detection + visibility (`worktrain status`, `worktrain logs --follow`)
+- ✅ `complete_step` tool -- daemon manages continueToken, LLM never handles it
+- ✅ Assessment gate circuit breaker (stops at 3 blocked attempts, shows artifact format)
+- ✅ `worktrain daemon --install` creates launchd service (daemon survives MCP reconnects)
+- ✅ Self-configuration (`triggers.yml`, `daemon-soul.md`, `AGENTS.md` for workrail repo)
+
+### Current limitations at this commit
+
+**Blocking reliable complex workflows:**
+1. **`complete_step` not yet tested in production** -- just merged, daemon still using `continue_workflow` in running sessions. Needs daemon restart to take effect.
+2. **Assessment gates still unreliable** -- `complete_step` fixes the token issue; the `artifacts` field (#557) fixes the submission issue. But `coding-task-workflow-agentic` phases with quality gates haven't been tested end-to-end yet.
+3. **Native `spawn_agent` not yet merged** -- implementation in progress. Until it lands, all subagent delegation is via `mcp__nested-subagent__Task` (invisible black box).
+4. **No session identity (parentSessionId)** -- multi-phase work appears as unrelated flat sessions in the console.
+
+**Architecture not yet realized:**
+5. **Coordinator scripts don't exist** -- `worktrain spawn/await` is there but no templates.
+6. **Subagent loop not rethought** -- LLM still decides when to delegate; workflow-as-orchestrator model is spec'd but not built.
+7. **Workflow runtime adapter not built** -- workflows run in daemon mode as-is; no MCP vs daemon adaptation layer.
+8. **Knowledge graph not built** -- context gathering still sweeps files on every session.
+9. **MCP simplification PR-B not done** -- HttpServer still starts with MCP server.
+
+**Missing for production autonomy:**
+10. **No notifications** -- daemon completes work silently. Users have no awareness unless watching console/logs.
+11. **No auto-commit from handoff artifact** -- merged but untested end-to-end.
+12. **Late-bound goals not implemented** -- triggers require static goals; dynamic goals (like PR reviews) need `goalTemplate: "{{$.goal}}"` as default.
+13. **No coordinator script template** -- the multi-phase autonomous pipeline exists as primitives but not as a usable script.
+
+---
+
+### Artifacts as first-class citizens: explorable, accessible, out of the repo (Apr 18, 2026)
+
+**The current mess:** every autonomous session dumps `design-candidates.md`, `implementation_plan.md`, `design-review-findings.md`, `mr-review.md` etc. as files in the repo root or worktrees. They are:
+- Not indexed or searchable
+- Not visible in the console
+- Not accessible to other sessions (agent B can't read agent A's handoff without knowing the exact file path)
+- Polluting the repo with ephemeral working documents
+- Lost when worktrees are cleaned up
+- Scattered across the filesystem with no structure
+
+**The right model:** artifacts are WorkTrain data, not filesystem files.
+
+---
+
+#### What an artifact is
+
+Any structured output from a session that has value beyond the session itself:
+- **Handoff docs** -- what one session produces for the next to consume
+- **Design candidates** -- research output with tradeoffs and recommendation
+- **Implementation plans** -- what to build, how, in what order
+- **Review findings** -- MR review output with findings, severity, recommendation
+- **Spec files** -- behavioral specs, acceptance criteria, API contracts
+- **Investigation summaries** -- bug investigation root cause and reproduction
+- **Context bundles** -- pre-packaged knowledge for subagent consumption
+
+**NOT artifacts:** step notes (stay in WorkRail session store), event logs (stay in daemon events), source code (stays in repo).
+
+---
+
+#### Where artifacts live
+
+`~/.workrail/artifacts/<sessionId>/<artifact-type>-<timestamp>.json`
+
+Structured JSON, not markdown. The display layer (console, `worktrain artifacts`) renders them as human-readable. Other agents query them as structured data.
+
+**Why JSON not markdown:**
+- Queryable by other agents (what are the findings with severity=critical?)
+- Renderable by the console with proper formatting, filtering, search
+- Versionable and diffable in the artifact store
+- Accessible via the knowledge graph (artifacts become nodes with typed edges)
+
+---
+
+#### Console integration
+
+The console session detail view gets an "Artifacts" tab alongside "Steps" and "Notes":
+
+```
+Session: sess_3bmj...  [MR Review: PR #566]
+├── Steps (8)
+├── Notes
+└── Artifacts (3)
+    ├── 📋 review-findings.json    "APPROVE -- 3 Minor, 1 Info"
+    ├── 📄 context-bundle.json     "12 files read, 4 patterns identified"  
+    └── 🔍 investigation-notes.json "Signal 3 dead code in max_turns path"
+```
+
+Click an artifact → full rendered view in the console.
+
+---
+
+#### Accessibility to other agents
+
+Agents can query artifacts from prior sessions via a new tool:
+
+```
+read_artifact({ sessionId: 'sess_3bmj...', type: 'review-findings' })
+→ { verdict: 'APPROVE', findings: [...], recommendation: '...' }
+
+search_artifacts({ type: 'implementation-plan', workflowId: 'coding-task-workflow-agentic', since: '7d' })
+→ [{ sessionId, summary, createdAt }, ...]
+```
+
+This replaces the current pattern where agents `cat design-candidates.md` from a known path -- fragile, path-dependent, breaks across worktrees.
+
+---
+
+#### Workflow integration
+
+Workflow steps declare their artifact output type:
+
+```json
+{
+  "id": "phase-1c-challenge-and-select",
+  "output": {
+    "artifact": "design-candidates",
+    "schema": "wr.artifacts.design-candidates.v1"
+  }
+}
+```
+
+**Both the daemon AND the MCP server** store step artifacts automatically. The artifact store is a WorkRail data layer feature, not daemon-specific. A human using Claude Code with the MCP produces the same artifacts in the same store as an autonomous daemon session. The console shows them for both. Other sessions (human-driven or autonomous) can query them either way.
+
+In MCP mode, the human can explicitly commit an artifact to the repo if desired (e.g. a final spec becomes `docs/specs/feature-x.md`). But the default is the artifact store -- repo is opt-in. The `NEVER COMMIT MARKDOWN FILES` rule in workflow metaGuidance exists because the artifact store doesn't exist yet. Once it does, that rule becomes unnecessary for all runtimes.
+
+---
+
+#### What stays in the repo
+
+Almost nothing from WorkTrain sessions. The only things that belong in the repo:
+- Source code changes (committed via auto-commit or human review)
+- Long-lived spec files that are part of the product (e.g. `docs/ideas/backlog.md`)
+- Workflow definitions (`workflows/*.json`)
+
+Everything else -- design docs, review findings, investigation notes, implementation plans -- lives in `~/.workrail/artifacts/`. If you want a design doc in the repo, you explicitly commit it. The default is: it lives in WorkTrain's data layer.
+
+---
+
+#### Build order
+
+1. **Artifact store** -- `~/.workrail/artifacts/<sessionId>/` directory structure, JSON schema for common types
+2. **Daemon writes artifacts** -- workflow steps with `output.artifact` declaration write to the artifact store automatically
+3. **`worktrain artifacts` CLI** -- list, read, search artifacts by session, type, date
+4. **Console artifacts tab** -- render artifacts in session detail view
+5. **`read_artifact` / `search_artifacts` tools** -- agents can query the artifact store
+6. **Knowledge graph integration** -- artifacts become nodes, sessions link to their artifacts
+
+**The `NEVER COMMIT MARKDOWN FILES` rule in metaGuidance is a symptom of this missing feature.** The rule exists because agents keep dumping files in the wrong place. With a proper artifact store, the rule becomes unnecessary -- artifacts have nowhere to go except the artifact store.
+
+---
+
+### "Add to repo" button in console for artifacts (Apr 18, 2026)
+
+Instead of workflow steps declaring upfront whether an artifact goes to the repo, the human makes that decision after seeing the content -- via a button in the console.
+
+**The flow:**
+1. Agent produces artifact → stored automatically in `~/.workrail/artifacts/`
+2. Human opens it in the console Artifacts tab
+3. Sees action buttons: **📁 Add to repo** | **📋 Copy** | **🔗 Share link**
+4. Clicks "Add to repo" → console prompts: "Save as: `docs/design/design-candidates-<name>.md`" (editable path with sensible default)
+5. Console commits the artifact as markdown to the repo at that path, with a commit message like `docs: add design candidates for <workflow-goal>`
+
+**Why this is better than workflow-level declaration:**
+- Agent doesn't need to know at step time whether output will be repo-worthy
+- Human decides after seeing actual content quality
+- Ephemeral working artifacts stay ephemeral; only promoted ones go to the repo
+- No "NEVER COMMIT MARKDOWN FILES" rule needed -- agents just produce artifacts, humans decide what's repo-worthy
+
+**Button options:**
+- **📁 Add to repo** -- renders artifact as markdown, commits to repo at specified path
+- **📋 Copy** -- copies rendered markdown to clipboard
+- **🔗 Share link** -- generates a URL that opens the artifact in the console. ⚠️ Local-only: only works on the same machine or with shared filesystem access. Requires cloud hosting for true team sharing (see cloud hosting spec in backlog)
+- **📤 Export** -- save to arbitrary filesystem path outside the repo
+
+**The commit WorkTrain creates:**
+```
+docs(design): add design candidates for MCP simplification
+
+Source: WorkTrain session sess_3bmj... (mr-review-workflow-agentic)
+Artifact: design-candidates-stdio-simplification-2026-04-18.md
+```
+
+**Also useful for:** implementation plans the team wants to track, spec files that belong in the repo permanently, investigation summaries that become part of incident post-mortems.
+
+---
+
+## Current state update (Apr 18, 2026 -- later)
+
+**npm version: v3.35.1** (auto-released after spawn_agent merged)
+
+### What additionally shipped since the milestone (commit 473f4bd0)
+
+- ✅ **`complete_step` tool** (#569) -- daemon manages continueToken internally, LLM never handles it. Notes required (min 50 chars). `continue_workflow` deprecated.
+- ✅ **`spawn_agent` tool** (#573) -- native in-process child session spawning. parentSessionId in session_created event. Depth enforcement. Semaphore bypass. All 4 WorkflowRunResult variants handled.
+- ✅ **`complete_step` description fix** (#575) -- removed token-seeking language from deprecated continue_workflow description that would have triggered the LLM to seek a token.
+- ✅ **Discovery ran before both implementations** -- wr.discovery validated complete_step approach (found 1 merge blocker fixed), designed spawn_agent architecture (found semaphore deadlock risk avoided).
+
+### Updated limitations
+
+**Still open from previous list:**
+1. ~~complete_step just merged, untested~~ → ✅ merged, description fixed, discovery validated
+2. ~~spawn_agent not merged~~ → ✅ merged as #573
+3. **No session identity in console UI** -- parentSessionId is NOW in the event store (schema extended in #573) but console doesn't show the tree yet. Data is there; visualization is not.
+4. **No coordinator scripts** -- spawn_agent exists, coordinator templates don't.
+5. **Subagent loop still LLM-driven** -- workflow-as-orchestrator model spec'd but not built.
+6. **Workflow runtime adapter not built** -- one spec, two runtimes model spec'd but not built.
+7. **Knowledge graph not built** -- context still sweeps files every session.
+8. **Artifacts not first-class** -- agents still dump markdown files in repo. Artifact store spec'd but not built.
+9. **No notifications** -- daemon completes silently.
+10. **MCP simplification PR-B** -- HttpServer still starts with MCP server.
+
+### What's now possible that wasn't before
+
+With `complete_step` + `spawn_agent`:
+- Agents can advance workflows without ever touching a token (removes the #1 session failure cause)
+- Workflows can declare delegation and the daemon spawns proper child sessions (all visible in event log)
+- Multi-phase work has a path to becoming a coherent work unit (parentSessionId in data, UI visualization next)
+
+### Next priorities
+
+1. **Console session tree view** -- parentSessionId data is in the store. Build the UI to show it.
+2. **First coordinator script template** -- `coordinator-mr-review.sh` that spawns: discovery → review → (conditional) fix → re-review. Proves the spawn/await loop works end-to-end.
+3. **Notifications** -- macOS notification + generic webhook. ~30 min implementation.
+4. **Late-bound goals** -- default `goalTemplate: "{{$.goal}}"` when no static goal. 10-line fix in trigger-store.ts.
+5. **Artifacts store foundation** -- `~/.workrail/artifacts/` directory structure. Step 1 of the first-class artifacts vision.

package/docs/ideas/design-candidates-spawn-agent-task.md

@@ -0,0 +1,178 @@
+# Design Candidates: spawn_agent Task Implementation
+
+> Full investigative material is in `design-candidates-spawn-agent.md`, `design-spawn-agent.md`,
+> and `design-review-findings-spawn-agent.md`. This file summarizes for the current coding task.
+
+---
+
+## Problem Understanding
+
+### Core Tensions
+
+**T1: Blocking vs. semaphore deadlock**
+`TriggerRouter.dispatch()` is fire-and-forget (non-blocking by design) and uses a global `Semaphore`.
+A parent holding a slot cannot wait for a child to acquire another slot -- deadlock.
+Correct path: call `runWorkflow()` directly, bypassing the semaphore entirely.
+
+**T2: Typed schema extension vs. internalContext injection**
+Adding `parentSessionId` to `session_created.data` is the typed, durable, query-friendly path.
+Injecting via `internalContext` (context_set event) is the proven fast path.
+Both are needed: `internalContext` for the `executeStartWorkflow()` call, AND schema extension for future DAG queries.
+
+**T3: Deterministic childSessionId vs. code simplicity**
+Pre-creating the child session (Candidate 2) gives a deterministic `childSessionId` before the run starts.
+Direct `runWorkflow()` (Candidate 1) is simpler but cannot return `childSessionId` if the run crashes before the AgentLoop starts.
+
+**T4: Depth propagation safety**
+Using `context.spawnDepth` (generic map) is fragile -- any code that overwrites context silently breaks depth enforcement.
+Using `WorkflowTrigger.spawnDepth` (typed `readonly` field) is compiler-enforced and cannot be accidentally lost.
+
+### Likely Seam
+`workflow-runner.ts` -- new `makeSpawnAgentTool()` factory alongside existing tool factories.
+`events.ts` -- one-line additive schema extension for `session_created.data`.
+`start.ts` -- thread `parentSessionId` through `buildInitialEvents()`.
+
+### What Makes It Hard
+- The `runWorkflow()` call inside `execute()` requires capturing `ctx`, `apiKey`, `daemonRegistry?`, `emitter?` in the factory closure.
+- `executeStartWorkflow()` returns `RA<StartWorkflowResult, StartWorkflowError>` -- must be unwrapped asynchronously.
+- `_preAllocatedStartResponse` expects `startResult.value.response` (not the full `StartWorkflowResult`).
+- Junior developer would call `dispatch()` instead of `runWorkflow()` and create a deadlock.
+- `session_created.data` currently hardcodes `data: {}` in `buildInitialEvents()` -- must thread `parentSessionId` into that call.
+
+---
+
+## Philosophy Constraints
+
+From `CLAUDE.md` and repo patterns:
+
+- **Errors as data**: Return `{ outcome: 'error', notes: msg }` JSON, not thrown exceptions, for child failures.
+- **Exhaustiveness**: Handle all 4 `WorkflowRunResult` variants without `as unknown` casts.
+- **Immutability**: New `WorkflowTrigger` fields are `readonly`.
+- **DI for boundaries**: `runWorkflowFn`, `ctx`, `apiKey`, `emitter` all injected at construction time.
+- **YAGNI**: Phase 1 only. No `spawn_session + await_sessions`, no bare-prompt mode, no width guardrails.
+- **Make illegal states unrepresentable**: `childSessionId` always present (pre-create guarantees it).
+
+No philosophy conflicts between stated rules and repo patterns.
+
+---
+
+## Impact Surface
+
+| File | Change | Risk |
+|---|---|---|
+| `src/daemon/workflow-runner.ts` | Add `parentSessionId?`, `spawnDepth?` to `WorkflowTrigger`; add `makeSpawnAgentTool()`; inject in `runWorkflow()`; update `BASE_SYSTEM_PROMPT`; update `_preAllocatedStartResponse` JSDoc | Low -- additive |
+| `src/v2/durable-core/schemas/session/events.ts` | Extend `session_created.data` with `parentSessionId?: z.string().optional()` | Low -- `z.object({})` uses strip mode |
+| `src/mcp/handlers/v2-execution/start.ts` | Thread `parentSessionId` from `internalContext` into `session_created` event via `buildInitialEvents()` | Low -- internal API |
+| `src/trigger/trigger-router.ts` | No change -- new `WorkflowTrigger` fields are optional | None |
+| `src/v2/usecases/console-routes.ts` | No change -- new `WorkflowTrigger` fields are optional | None |
+
+---
+
+## Candidates
+
+### Candidate 1: Direct runWorkflow() call
+
+**Summary**: `makeSpawnAgentTool()` calls `runWorkflow()` directly. No pre-creation. Session ID extracted from result after run.
+
+**Tensions resolved**: YAGNI (fewest lines), blocking (natural await).
+**Tensions accepted**: Crash-before-start has no observable `childSessionId`. `childSessionId` is absent on failure.
+
+**Boundary**: `WorkflowTrigger` + direct `runWorkflow()` call.
+**Why this boundary**: `WorkflowTrigger` is the natural seam -- carries all session config. No new types.
+
+**Failure mode**: `runWorkflow()` crashes before AgentLoop starts -- `childSessionId` is null, parent gets `{ outcome: 'error', childSessionId: null }`.
+
+**Repo-pattern relationship**: Follows factory pattern. No adaptation of `_preAllocatedStartResponse`.
+
+**Gain**: ~10 fewer lines, maximum simplicity.
+**Give up**: No deterministic `childSessionId` on startup failures. Less crash observability.
+
+**Scope**: Best-fit.
+**Philosophy fit**: Honors YAGNI strongest. Slight tension with 'make illegal states unrepresentable' (`childSessionId` can be null).
+
+---
+
+### Candidate 2: Pre-create session with _preAllocatedStartResponse (RECOMMENDED)
+
+**Summary**: `execute()` calls `executeStartWorkflow()` with `parentSessionId` in `internalContext`, decodes `childSessionId` from the returned `continueToken`, then calls `runWorkflow()` with `_preAllocatedStartResponse`.
+
+**Tensions resolved**: Deterministic `childSessionId`, crash-before-start observability, `childSessionId` seeds Phase 2, 'make illegal states unrepresentable'.
+**Tensions accepted**: One extra async call (~10-50ms).
+
+**Boundary**: `WorkflowTrigger._preAllocatedStartResponse` + `internalContext` injection.
+**Why this boundary**: Direct adaptation of the proven `_preAllocatedStartResponse` pattern from `console-routes.ts`. Session store sees the child immediately -- correct observable behavior.
+
+**Failure mode**: `executeStartWorkflow()` succeeds, `runWorkflow()` fails before AgentLoop -- zombie session in store. Accepted for Phase 1.
+
+**Repo-pattern relationship**: Adapts proven `_preAllocatedStartResponse` pattern.
+
+**Gain**: `childSessionId` always known before child runs. Deterministic. Child observable from moment of `execute()`.
+**Give up**: One extra async call. Slightly more setup code.
+
+**Scope**: Best-fit.
+**Philosophy fit**: Honors determinism over cleverness, make illegal states unrepresentable, DI. No conflicts.
+
+---
+
+### Candidate 3: Read depth from session store at execute() time
+
+**Summary**: Instead of passing `currentDepth` as a constructor parameter, read `spawnDepth` from parent session store inside `execute()`.
+
+**Tensions resolved**: Accurate depth for checkpoint-resumed sessions (theoretical edge case).
+**Tensions accepted**: Async I/O in `execute()`, more error paths, session store dependency.
+
+**Boundary**: Session store read inside `execute()`.
+**Why this boundary is NOT best-fit**: Expensive, speculative. Checkpoint-resumed daemon sessions restart AgentLoop from scratch -- constructor parameter is always correctly set.
+
+**Failure mode**: Store read fails -- fail-safe blocks spawn, adds error path complexity.
+
+**Repo-pattern relationship**: Departs from constructor-injection pattern.
+
+**Gain**: Accurate depth for resumed sessions. **Give up**: YAGNI violation, async I/O, extra error paths.
+
+**Scope**: Too broad. **Philosophy fit**: Conflicts with YAGNI.
+
+---
+
+## Comparison and Recommendation
+
+### Comparison Matrix
+
+| Tension | C1 | C2 | C3 |
+|---|---|---|---|
+| Blocking fidelity | Strong | Strong | Strong |
+| Deterministic childSessionId | Weak | Strong | Weak |
+| Semaphore bypass | Strong | Strong | Strong |
+| YAGNI | Strong | Moderate | Weak |
+| Crash observability | Weak | Strong | Weak |
+| Depth accuracy | Adequate | Adequate | Strong (speculative) |
+| Repo pattern | Follows | Adapts proven | Departs |
+| Philosophy | Full | Full | Partial |
+
+### Recommendation: Candidate 2
+
+C2 is best-fit. The `_preAllocatedStartResponse` pattern is proven and stable (`console-routes.ts`).
+The marginal complexity (one extra async call) is small relative to the gain: `childSessionId` is always
+known, crash-before-start is observable, Phase 2 is seeded. C3 is rejected on YAGNI grounds.
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument**: C2 adds a zombie session failure mode that C1 doesn't have. If `executeStartWorkflow()` succeeds but `runWorkflow()` fails immediately, a session exists in the store with no corresponding run. C1 avoids this -- no session is created until the run actually starts.
+
+**C1 as narrower option**: Still satisfies acceptance criteria. Loses crash observability and deterministic `childSessionId`. Would win if we prioritized simplicity over observability.
+
+**C3 as broader option**: Justified only if checkpoint-resumed spawned sessions become a real production use case. No evidence for Phase 1.
+
+**Assumption that would invalidate C2**: If `_preAllocatedStartResponse` is removed in a future refactor. Mitigation: update its JSDoc (Orange finding O2) to list `spawn_agent` as a legitimate caller.
+
+---
+
+## Open Questions for the Main Agent
+
+1. **maxSubagentDepth source**: Design doc says read from `WorkflowTrigger.agentConfig` (default 3). Should this also check global workspace config? Decision: use `trigger.agentConfig?.maxSubagentDepth ?? 3` for Phase 1. Document in tool description.
+
+2. **`session_created.data` strictness**: Confirmed `z.object({})` uses strip mode. Extension is safe. Unverified by migration run -- low risk.
+
+3. **Zombie session cleanup**: Deferred to Phase 2. Document as known edge case in tool description.