@exaudeus/workrail 3.35.1 → 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

@@ -5121,7 +5121,9 @@ Workflow steps declare their artifact output type:
 }
 ```
 
-The daemon automatically stores the step's notes as a typed artifact. Other steps and other sessions can query it by type rather than by file path.
+**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.
 
 ---
 
@@ -5146,3 +5148,80 @@ Everything else -- design docs, review findings, investigation notes, implementa
 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.

package/docs/ideas/design-review-findings-spawn-agent-task.md

@@ -0,0 +1,139 @@
+# Design Review Findings: spawn_agent Tool Implementation
+
+_Concise, actionable findings for main-agent synthesis. Design: Candidate 2 (pre-create session with _preAllocatedStartResponse, then blocking runWorkflow())._
+
+> Note: Full discovery-phase review is in `design-review-findings-spawn-agent.md`. This file is for the current coding task review pass.
+
+---
+
+## Tradeoff Review
+
+### T1: Parent clock keeps ticking while child runs
+- Confirmed acceptable. Success criterion 2 ('parent does not advance until child completes') is satisfied even on timeout (parent aborts, not advances).
+- When parent times out, child continues as orphaned session. Work is preserved in session store. Session tree preserves the parent-child link.
+- Mitigation needed: document in tool description.
+- **Status: ACCEPTED.**
+
+### T2: _preAllocatedStartResponse comment needs update
+- Current comment: 'set only by the dispatch HTTP handler.' spawn_agent will be another legitimate internal caller.
+- If not updated, future developer may remove spawn_agent support as accidental usage.
+- **Status: REQUIRED FIX (low effort, Step 1.1).**
+
+### T3: One extra async call in execute()
+- executeStartWorkflow() is ~10-50ms (no LLM call). Negligible for a tool that blocks 1-30 minutes.
+- **Status: ACCEPTED.**
+
+### T4: session_created.data extension
+- Confirmed `z.object({})` uses strip mode (not `.strict()`). Extension with `parentSessionId?: z.string().optional()` is backward-compatible.
+- `buildInitialEvents()` currently hardcodes `data: {}` -- requires threading `parentSessionId` parameter.
+- **Status: REQUIRED, LOW RISK.**
+
+---
+
+## Failure Mode Review
+
+### FM1: Parent timeout while child is running
+- Severity: LOW. Child completes normally, work preserved, session tree intact.
+- Design coverage: adequate. Orphaned child traceable via parentSessionId.
+- **No revision required.**
+
+### FM2: executeStartWorkflow() succeeds, runWorkflow() fails before AgentLoop starts
+- Severity: MEDIUM. Zombie session in store (shows as 'running' indefinitely).
+- Design coverage: partial. Parent gets `{ childSessionId, outcome: 'error', notes: errorMessage }` -- child session is observable. But zombie cleanup is deferred.
+- Mitigation for Phase 1: document as known edge case. Phase 2: session timeout/zombie cleanup.
+- **Status: ACCEPTED for Phase 1.**
+
+### FM3: spawnDepth propagation failure
+- Severity: HIGH if unmitigated. FULLY MITIGATED by using typed `readonly spawnDepth?: number` field on `WorkflowTrigger`.
+- After fix: severity drops to LOW (depth is typed, cannot be accidentally lost).
+- **Status: MITIGATED.**
+
+### FM4: Depth bypass via width (sequential spawning)
+- Severity: LOW for Phase 1. `maxSessionMinutes` on parent is the practical limit.
+- **Status: ACCEPTED, deferred to Phase 2.**
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Candidate 1 (direct runWorkflow, no pre-create):** Close alternative. Simpler execute() -- no executeStartWorkflow() call. Loses: `childSessionId` is unknown until after runWorkflow() starts; crash-before-start has no childSessionId to return.
+
+**No elements worth borrowing from Candidate 1.** C2 already does everything C1 does plus the session-ID-upfront guarantee.
+
+**Could skip session_created.data extension?** Technically yes -- `parentSessionId` in `context_set` events is still durable and queryable. But the extension is ~8 lines total and future-proofs DAG queries. Keep it.
+
+---
+
+## Philosophy Alignment
+
+### Clearly satisfied
+- Errors as data: discriminated union return, no throws
+- DI for boundaries: ctx, apiKey, emitter all injected at construction time
+- Immutability: WorkflowTrigger fully readonly, new fields also readonly
+- Exhaustiveness: WorkflowRunResult match handles all 4 variants
+- Validate at boundaries: depth check at start of execute()
+- YAGNI: Phase 1 only; non-blocking spawn deferred
+- Make illegal states unrepresentable: childSessionId always present (pre-create guarantees it)
+
+### Under tension (acceptable)
+- Architectural fixes over patches: parentSessionId via internalContext is somewhat patch-like. Acceptable because internalContext is an established pattern for daemon-internal injection (is_autonomous, workspacePath). Tension is low.
+- Compose with small pure functions: execute() has two async operations (~50 lines). Complexity is necessary and bounded.
+
+---
+
+## Findings
+
+### Red (blocking)
+_None._
+
+### Orange (required before implementation)
+
+**O1: Use `readonly spawnDepth?: number` on WorkflowTrigger (not `context.spawnDepth`)**
+Rationale: generic context map can be silently overwritten by trigger system or other callers, breaking depth enforcement. Typed field makes the invariant explicit and compiler-checked.
+Files: `src/daemon/workflow-runner.ts` (WorkflowTrigger type definition)
+**Status: Design already incorporates this fix.**
+
+**O2: Update `_preAllocatedStartResponse` comment to list spawn_agent as legitimate caller**
+Rationale: current comment misleads future developers. Without this update, spawn_agent support could be removed as accidental.
+Files: `src/daemon/workflow-runner.ts` (WorkflowTrigger._preAllocatedStartResponse JSDoc)
+**Status: Must be applied during implementation.**
+
+**O3: Thread parentSessionId into buildInitialEvents() for session_created.data**
+Rationale: the `internalContext` injection only reaches `context_set` events, not `session_created.data`. For the typed schema extension to work, `buildInitialEvents()` needs a new optional parameter.
+Files: `src/mcp/handlers/v2-execution/start.ts` (`buildInitialEvents()` signature and call site)
+**Status: Required -- not in original design review, discovered during implementation analysis.**
+
+### Yellow (should-fix, not blocking)
+
+**Y1: Document parent-clock behavior in tool description**
+The spawn_agent tool description should note that the parent session's maxSessionMinutes clock runs while the child executes. Workflow authors must configure the parent's timeout to be longer than the expected child duration.
+
+**Y2: Document zombie session edge case**
+The spawn_agent tool description should note that if runWorkflow() fails before the AgentLoop starts, a zombie session may exist in the store. Phase 2 will add cleanup.
+
+**Y3: maxSubagentDepth source**
+For Phase 1, default to 3 if `WorkflowTrigger.agentConfig?.maxSubagentDepth` is not set. Document in tool description.
+
+---
+
+## Recommended Revisions
+
+1. Use `readonly spawnDepth?: number` on WorkflowTrigger (O1 -- design already incorporates)
+2. Update `_preAllocatedStartResponse` JSDoc to list spawn_agent as a legitimate internal caller (O2)
+3. Add `parentSessionId?: string` parameter to `buildInitialEvents()` and thread it into `session_created.data` (O3)
+4. Add parent-clock behavior documentation to spawn_agent tool description (Y1)
+5. Add zombie session documentation to spawn_agent tool description (Y2)
+6. Use `trigger.agentConfig?.maxSubagentDepth ?? 3` as maxDepth (Y3)
+
+---
+
+## Residual Concerns
+
+**RC1: Session tree query infrastructure deferred to Phase 2**
+`parentSessionId` is written to the session store but no query path exists to read 'all children of session X'. The console DAG view cannot render the tree until Phase 2. This is by design -- Phase 1 writes the data; Phase 2 builds the reader.
+
+**RC2: Zod strictness on session_created.data**
+Confirmed that `z.object({})` uses strip mode (not strict). Extension with `parentSessionId?: z.string().optional()` is backward-compatible. Unverified by an actual migration run -- low risk but unvalidated.
+
+**RC3: maxTotalAgentsPerTask guardrail deferred**
+Phase 1 enforces depth only. Wide spawning is not caught by depth limits. Phase 2 adds the concurrency registry. For Phase 1, `maxSessionMinutes` on the parent session is the practical limit on total work done.