@pellux/goodvibes-sdk 0.38.0 → 1.0.0

package/dist/platform/core/plan-decomposition.js

@@ -0,0 +1,417 @@
+/**
+ * Agent-driven goal decomposition for the planner.
+ *
+ * This module is the model-decomposition counterpart to the deterministic
+ * heuristic path in `plan-proposal.ts`. Given a goal, it drives a bounded,
+ * READ-ONLY planning agent (through the injected `DecompositionRunner` seam —
+ * this module never imports the agent machinery, so it stays in `core` and is
+ * fully unit-testable with a stubbed runner), parses and STRICTLY validates
+ * the agent's structured output, and produces a `PlanProposal` tagged with
+ * honest provenance.
+ *
+ * Failure honesty is the whole point: a spawn error, a timeout/cancellation,
+ * or output that is still malformed after ONE repair attempt all fall back to
+ * the existing heuristic `singleItemProposal` path, tagged
+ * `decomposedBy: 'heuristic'` with a `fallbackReason`. The heuristic path is
+ * reused verbatim — `singleItemProposal`/`assemblePlanProposal` are never
+ * modified — so their existing byte-for-byte test expectations are preserved;
+ * provenance is layered on afterward.
+ *
+ * The module NEVER performs surgery on agent output to force it to validate:
+ * a proposal is accepted only when `assemblePlanProposal` reports ZERO issues
+ * (no dangling dependency, no dependency cycle, no unresolved phase). Anything
+ * short of that is one repair attempt and then an honest fallback — never a
+ * silent edit that drops or rewrites the agent's work items.
+ */
+import { AdaptivePlanner } from './adaptive-planner.js';
+import { assemblePlanProposal, singleItemProposal, } from './plan-proposal.js';
+/** Pull the first balanced JSON object out of arbitrary agent text (fenced or not). */
+function extractJsonObject(text) {
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const haystack = fenced?.[1] ?? text;
+    const start = haystack.indexOf('{');
+    if (start === -1)
+        return null;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < haystack.length; i++) {
+        const ch = haystack[i];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+            }
+            else if (ch === '\\') {
+                escaped = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === '{')
+            depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0)
+                return haystack.slice(start, i + 1);
+        }
+    }
+    return null;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * Parse + strictly validate a planning agent's output text into a
+ * `RawDecomposition` the assembler can consume. Never throws; every problem is
+ * accumulated into `errors` so a single repair prompt can address them all at
+ * once. Structural rejects: unparseable JSON, empty/absent items array, empty
+ * item title/brief, non-finite ordinal, empty phase title.
+ */
+export function parseDecomposition(text) {
+    const errors = [];
+    const json = extractJsonObject(text ?? '');
+    if (!json) {
+        return { ok: false, errors: ['Output did not contain a JSON object.'] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (err) {
+        return { ok: false, errors: [`Output was not valid JSON: ${err.message}`] };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, errors: ['Top-level value must be a JSON object.'] };
+    }
+    const obj = parsed;
+    const rawItems = obj.items;
+    if (!Array.isArray(rawItems) || rawItems.length === 0) {
+        return { ok: false, errors: ['"items" must be a non-empty array.'] };
+    }
+    // Validate phases (optional).
+    const rawPhases = Array.isArray(obj.phases) ? obj.phases : [];
+    rawPhases.forEach((p, i) => {
+        if (typeof p !== 'object' || p === null || !isNonEmptyString(p.title)) {
+            errors.push(`phases[${i}] must have a non-empty "title".`);
+        }
+    });
+    // Validate items.
+    const items = [];
+    rawItems.forEach((raw, i) => {
+        if (typeof raw !== 'object' || raw === null) {
+            errors.push(`items[${i}] must be an object.`);
+            return;
+        }
+        const item = raw;
+        if (!isNonEmptyString(item.title))
+            errors.push(`items[${i}].title must be a non-empty string.`);
+        if (!isNonEmptyString(item.brief))
+            errors.push(`items[${i}].brief must be a non-empty string.`);
+        if (typeof item.ordinal !== 'number' || !Number.isFinite(item.ordinal)) {
+            errors.push(`items[${i}].ordinal must be a finite number.`);
+        }
+        if (item.phase !== undefined && !isNonEmptyString(item.phase)) {
+            errors.push(`items[${i}].phase, when present, must be a non-empty string.`);
+        }
+        if (isNonEmptyString(item.title) && isNonEmptyString(item.brief) && typeof item.ordinal === 'number' && Number.isFinite(item.ordinal)) {
+            items.push({
+                title: item.title,
+                brief: item.brief,
+                ordinal: item.ordinal,
+                ...(isNonEmptyString(item.phase) ? { phase: item.phase } : {}),
+                ...(Array.isArray(item.dependsOn) ? { dependsOn: item.dependsOn.filter((d) => typeof d === 'string' || typeof d === 'number') } : {}),
+                ...(isNonEmptyString(item.suggestedArchetype) ? { suggestedArchetype: item.suggestedArchetype } : {}),
+                ...(Array.isArray(item.likelyFiles) ? { likelyFiles: item.likelyFiles.filter(isNonEmptyString) } : {}),
+                ...(Array.isArray(item.verification) ? { verification: item.verification.filter(isNonEmptyString) } : {}),
+                ...(typeof item.canRunConcurrently === 'boolean' ? { canRunConcurrently: item.canRunConcurrently } : {}),
+                ...(typeof item.needsReview === 'boolean' ? { needsReview: item.needsReview } : {}),
+            });
+        }
+    });
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    const notes = [];
+    if (Array.isArray(obj.notes))
+        notes.push(...obj.notes.filter(isNonEmptyString));
+    if (Array.isArray(obj.risks))
+        notes.push(...obj.risks.filter(isNonEmptyString));
+    const output = {
+        items,
+        ...(rawPhases.length > 0 ? { phases: rawPhases } : {}),
+        ...(Array.isArray(obj.dependencies) ? { dependencies: obj.dependencies } : {}),
+    };
+    return { ok: true, raw: toRawDecomposition(output), ...(notes.length > 0 ? { notes } : {}), errors: [] };
+}
+const DEFAULT_PHASE_TITLE = 'Execute';
+/**
+ * Map a validated `DecompositionAgentOutput` into the `RawDecomposition` shape
+ * `assemblePlanProposal` consumes. Items are ordered by `ordinal` (stable on
+ * ties). Every referenced phase is materialized so the assembler never has to
+ * synthesize an "Unphased" bucket — an unresolved phase from here would be a
+ * real bug, not agent sloppiness. Ordinal-based dependency references are
+ * resolved to titles so the assembler's title resolver handles them uniformly.
+ */
+export function toRawDecomposition(output) {
+    const ordered = [...output.items].sort((a, b) => a.ordinal - b.ordinal);
+    const ordinalToTitle = new Map();
+    for (const item of ordered) {
+        if (!ordinalToTitle.has(item.ordinal))
+            ordinalToTitle.set(item.ordinal, item.title);
+    }
+    const resolveRef = (ref) => {
+        if (typeof ref === 'number')
+            return ordinalToTitle.get(ref) ?? String(ref);
+        const asNum = Number(ref);
+        if (ref.trim() !== '' && Number.isFinite(asNum) && ordinalToTitle.has(asNum))
+            return ordinalToTitle.get(asNum);
+        return ref;
+    };
+    // Phase set: explicit phases first, then any item phase titles not covered,
+    // then the default shared phase if any item lacks one.
+    const phaseTitles = [];
+    const seenPhase = new Set();
+    const addPhase = (title) => {
+        const key = title.toLowerCase().trim();
+        if (!seenPhase.has(key)) {
+            seenPhase.add(key);
+            phaseTitles.push(title);
+        }
+    };
+    const explicit = new Map();
+    for (const p of output.phases ?? []) {
+        explicit.set(p.title.toLowerCase().trim(), p);
+        addPhase(p.title);
+    }
+    let needsDefault = false;
+    for (const item of ordered) {
+        if (item.phase)
+            addPhase(item.phase);
+        else
+            needsDefault = true;
+    }
+    if (needsDefault)
+        addPhase(DEFAULT_PHASE_TITLE);
+    const phases = phaseTitles.map((title) => {
+        const meta = explicit.get(title.toLowerCase().trim());
+        return meta?.description ? { title, description: meta.description } : { title };
+    });
+    // Accumulate dependencies: inline dependsOn plus explicit edges.
+    const depsByTitle = new Map();
+    const addDep = (from, to) => {
+        const key = from.toLowerCase().trim();
+        if (!depsByTitle.has(key))
+            depsByTitle.set(key, new Set());
+        depsByTitle.get(key).add(to);
+    };
+    for (const item of ordered) {
+        for (const dep of item.dependsOn ?? [])
+            addDep(item.title, resolveRef(dep));
+    }
+    for (const edge of output.dependencies ?? [])
+        addDep(resolveRef(edge.from), resolveRef(edge.to));
+    const workItems = ordered.map((item) => {
+        const deps = depsByTitle.get(item.title.toLowerCase().trim());
+        return {
+            title: item.title,
+            brief: item.brief,
+            phase: item.phase ?? DEFAULT_PHASE_TITLE,
+            ...(deps && deps.size > 0 ? { dependsOn: [...deps] } : {}),
+            ...(item.suggestedArchetype ? { suggestedArchetype: item.suggestedArchetype } : {}),
+            ...(item.likelyFiles ? { likelyFiles: item.likelyFiles } : {}),
+            ...(item.verification ? { verification: item.verification } : {}),
+            ...(item.canRunConcurrently !== undefined ? { canRunConcurrently: item.canRunConcurrently } : {}),
+            ...(item.needsReview !== undefined ? { needsReview: item.needsReview } : {}),
+        };
+    });
+    return { phases, workItems };
+}
+// ---------------------------------------------------------------------------
+// Planner agent prompt
+// ---------------------------------------------------------------------------
+/**
+ * Build the system prompt for the read-only planning agent. It is explicit
+ * about the exact JSON contract and about the read-only posture (the agent's
+ * tool set already excludes write/edit/exec; this reinforces intent).
+ */
+export function buildPlannerSystemPrompt() {
+    return [
+        'You are a READ-ONLY planning agent. You may read, search, and analyze the codebase',
+        'to understand it, but you MUST NOT modify anything and you have no write/edit/exec tools.',
+        '',
+        'Decompose the given goal into an ordered set of work items. Respond with a SINGLE JSON',
+        'object and NOTHING else (no prose, no markdown outside a single optional ```json fence).',
+        '',
+        'Schema:',
+        '{',
+        '  "phases": [{ "title": string, "description"?: string }],   // optional; shared phase template',
+        '  "items": [{',
+        '    "title": string,            // required, non-empty, unique',
+        '    "brief": string,            // required, non-empty: what this item does',
+        '    "ordinal": number,          // required: execution order (0-based or 1-based, ascending)',
+        '    "phase"?: string,           // phase title this item belongs to',
+        '    "dependsOn"?: (string|number)[],  // item titles or ordinals this item depends on',
+        '    "suggestedArchetype"?: "engineer"|"reviewer"|"tester"|"researcher"|"integrator",',
+        '    "likelyFiles"?: string[],',
+        '    "verification"?: string[],',
+        '    "canRunConcurrently"?: boolean,',
+        '    "needsReview"?: boolean',
+        '  }],',
+        '  "dependencies"?: [{ "from": string|number, "to": string|number }],  // "from depends on to"',
+        '  "notes"?: string[],',
+        '  "risks"?: string[]',
+        '}',
+        '',
+        'Rules: dependencies must reference real items and must be acyclic. Every brief must be',
+        'non-empty. Keep the decomposition honest — if the goal is genuinely a single unit of work,',
+        'return exactly one item.',
+    ].join('\n');
+}
+function buildUserPrompt(request, repairErrors) {
+    const lines = [`Goal: ${request.goal}`, `Working directory: ${request.workingDir}`];
+    if (request.constraints?.capacity !== undefined)
+        lines.push(`Concurrency capacity: ${request.constraints.capacity}`);
+    if (request.constraints?.budgetUsd !== undefined)
+        lines.push(`Budget (USD): ${request.constraints.budgetUsd}`);
+    if (request.userContext)
+        lines.push('', 'Additional context:', request.userContext);
+    if (repairErrors && repairErrors.length > 0) {
+        lines.push('', 'Your previous response was rejected for these reasons. Fix ALL of them and respond again', 'with a single corrected JSON object:', ...repairErrors.map((e) => `  - ${e}`));
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// The service
+// ---------------------------------------------------------------------------
+/**
+ * Decompose a goal into a `PlanProposal`, honestly tagged with provenance.
+ *
+ * Control flow:
+ *  1. `config.mode === 'heuristic'` → the configured heuristic path (no agent).
+ *  2. The planner's decompose gate declines → honest single-item (no agent).
+ *  3. No runner available → heuristic fallback (reason: no runtime).
+ *  4. Agent path: run → parse → strict-validate → (assemble; issues===0 ?
+ *     accept : ONE repair attempt) → accept-or-fallback. Spawn error,
+ *     cancellation (kill / wall-timeout / token ceiling), or still-invalid
+ *     output after repair all fall back to the heuristic path with a reason.
+ */
+export async function decomposeGoal(request, planner, inputs, config, runner, deps = {}) {
+    const gate = planner.shouldDecompose(inputs);
+    const heuristicResult = (outcome) => {
+        const base = singleItemProposal(request.goal);
+        const fallbackReason = outcome.kind === 'fallback' ? outcome.reason : undefined;
+        const usage = outcome.kind === 'fallback' ? outcome.usage : undefined;
+        const elapsedMs = outcome.kind === 'fallback' ? outcome.elapsedMs : undefined;
+        const proposal = {
+            ...base,
+            decomposedBy: 'heuristic',
+            ...(fallbackReason ? { fallbackReason } : {}),
+            ...(usage ? { agentUsage: usage } : {}),
+            ...(elapsedMs !== undefined ? { elapsedMs } : {}),
+        };
+        deps.onOutcome?.(outcome);
+        return { proposal, gate, issues: [], outcome };
+    };
+    if (config.mode === 'heuristic') {
+        return heuristicResult({ kind: 'heuristic-configured' });
+    }
+    if (!gate.decompose) {
+        return heuristicResult({ kind: 'gate-declined', reasonCode: gate.reasonCode });
+    }
+    if (!runner) {
+        return heuristicResult({ kind: 'fallback', reason: 'no planning agent runtime available' });
+    }
+    const systemPrompt = buildPlannerSystemPrompt();
+    let lastUsage;
+    let totalElapsedMs = 0;
+    const runOnce = async (attempt, repairErrors) => {
+        const result = await runner.run({
+            goal: request.goal,
+            workingDir: request.workingDir,
+            systemPrompt,
+            userPrompt: buildUserPrompt(request, repairErrors),
+            bounds: config.bounds,
+            attempt,
+        });
+        lastUsage = result.usage ?? lastUsage;
+        totalElapsedMs += result.elapsedMs;
+        return result;
+    };
+    // --- initial attempt ---
+    let run;
+    try {
+        run = await runOnce('initial');
+    }
+    catch (err) {
+        return heuristicResult({ kind: 'fallback', reason: `spawn error: ${err.message}`, usage: lastUsage, elapsedMs: totalElapsedMs });
+    }
+    if (run.status === 'cancelled') {
+        return heuristicResult({ kind: 'fallback', reason: `cancelled${run.detail ? ` (${run.detail})` : ''}`, usage: lastUsage, elapsedMs: totalElapsedMs });
+    }
+    if (run.status === 'failed') {
+        return heuristicResult({ kind: 'fallback', reason: `agent error: ${run.detail ?? 'unknown'}`, usage: lastUsage, elapsedMs: totalElapsedMs });
+    }
+    const accept = (proposal, issues, repaired) => {
+        const costUsd = lastUsage ? deps.estimateCostUsd?.(lastUsage) : undefined;
+        const decorated = {
+            ...proposal,
+            decomposedBy: 'agent',
+            elapsedMs: totalElapsedMs,
+            ...(lastUsage ? { agentUsage: lastUsage } : {}),
+            ...(costUsd !== undefined ? { agentCostUsd: costUsd } : {}),
+        };
+        const outcome = {
+            kind: 'agent',
+            itemCount: decorated.workItems.length,
+            repaired,
+            ...(lastUsage ? { usage: lastUsage } : {}),
+            ...(costUsd !== undefined ? { costUsd } : {}),
+            elapsedMs: totalElapsedMs,
+        };
+        deps.onOutcome?.(outcome);
+        return { proposal: decorated, gate, issues, outcome };
+    };
+    // --- validate the initial output ---
+    const first = parseDecomposition(run.output);
+    if (first.ok && first.raw) {
+        const { proposal, issues } = assemblePlanProposal(request.goal, gate.strategy, first.raw);
+        if (issues.length === 0)
+            return accept(proposal, issues, false);
+        // Not clean — fall through to a single repair with the assembler's issues.
+        const repairErrors = issues.map((i) => i.message);
+        const repaired = await tryRepair(repairErrors);
+        if (repaired)
+            return repaired;
+        return heuristicResult({ kind: 'fallback', reason: `invalid agent decomposition after repair: ${issues.map((i) => i.kind).join(', ')}`, usage: lastUsage, elapsedMs: totalElapsedMs });
+    }
+    // Malformed structure — one repair attempt with the parser's errors.
+    const repaired = await tryRepair(first.errors);
+    if (repaired)
+        return repaired;
+    return heuristicResult({ kind: 'fallback', reason: `malformed agent output after repair: ${first.errors.slice(0, 3).join('; ')}`, usage: lastUsage, elapsedMs: totalElapsedMs });
+    // --- one repair attempt: returns an accepted result, or null to fall back ---
+    async function tryRepair(repairErrors) {
+        let repairRun;
+        try {
+            repairRun = await runOnce('repair', repairErrors);
+        }
+        catch {
+            return null;
+        }
+        if (repairRun.status !== 'completed')
+            return null;
+        const parsed = parseDecomposition(repairRun.output);
+        if (!parsed.ok || !parsed.raw)
+            return null;
+        const { proposal, issues } = assemblePlanProposal(request.goal, gate.strategy, parsed.raw);
+        if (issues.length !== 0)
+            return null;
+        return accept(proposal, issues, true);
+    }
+}

package/dist/platform/core/plan-proposal.d.ts

@@ -50,6 +50,26 @@ export interface Phase {
 }
 /** Where a proposal's decomposition came from. */
 export type PlanProposalSource = 'planner-agent' | 'single-item-fallback' | 'caller-supplied';
+/**
+ * Honest provenance for how a proposal's work items were produced.
+ *
+ * - `'agent'`     — a read-only planning agent decomposed the goal, and its
+ *   output validated cleanly (possibly after one repair attempt).
+ * - `'heuristic'` — the deterministic single-item path produced the proposal,
+ *   either because `planner.decomposition` is configured to `'heuristic'`, the
+ *   planner's gate declined to decompose, or the agent path failed and fell
+ *   back. `fallbackReason` is set only in the failure case, never when the
+ *   heuristic path was chosen deliberately by config or gate.
+ */
+export type DecomposedBy = 'agent' | 'heuristic';
+/** Token usage reported by a planning-decomposition agent run. */
+export interface DecompositionAgentUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens?: number | undefined;
+    readonly cacheWriteTokens?: number | undefined;
+    readonly totalTokens: number;
+}
 export interface PlanProposal {
     id: string;
     task: string;
@@ -59,6 +79,25 @@ export interface PlanProposal {
     workItems: WorkItem[];
     createdAt: number;
     source: PlanProposalSource;
+    /**
+     * Provenance overlay set by the decomposition service (plan-decomposition.ts).
+     * Absent on proposals produced directly by `assemblePlanProposal` /
+     * `singleItemProposal`, which stay byte-compatible with pre-provenance tests.
+     */
+    decomposedBy?: DecomposedBy | undefined;
+    /** Token usage of the planning agent (present when the agent path ran, even on fallback). */
+    agentUsage?: DecompositionAgentUsage | undefined;
+    /** Estimated dollar cost of the planning agent run, when a pricing lookup was available. */
+    agentCostUsd?: number | undefined;
+    /** Wall-clock time the planning agent ran, in ms (present when the agent path ran). */
+    elapsedMs?: number | undefined;
+    /**
+     * Why the agent path fell back to the heuristic path. Set ONLY on honest
+     * failure fallbacks (spawn error, timeout, cancellation, or output that was
+     * still malformed after one repair attempt) — never when `'heuristic'` was
+     * chosen by config or by the planner's decompose gate.
+     */
+    fallbackReason?: string | undefined;
 }
 /** The loose JSON shape a planning agent (or a caller) emits, pre-validation. */
 export interface RawDecompositionPhase {

package/dist/platform/core/plan-proposal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-proposal.d.ts","sourceRoot":"","sources":["../../../src/platform/core/plan-proposal.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plan-proposal.d.ts","sourceRoot":"","sources":["../../../src/platform/core/plan-proposal.ts"],"names":[],"mappings":"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"}

package/dist/platform/core/wrfc-routing.d.ts

@@ -1,5 +1,6 @@
 import type { ToolResult } from '../types/tools.js';
 export declare function isWrfcWorkflowRequest(text: string): boolean;
+export declare function userProhibitsDelegation(text: string): boolean;
 export declare function buildWrfcWorkflowRoutingPrompt(text: string): string | null;
 export declare function toolResultIndicatesAuthoritativeWrfcChain(result: ToolResult): boolean;
 //# sourceMappingURL=wrfc-routing.d.ts.map

package/dist/platform/core/wrfc-routing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wrfc-routing.d.ts","sourceRoot":"","sources":["../../../src/platform/core/wrfc-routing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAM3D;AAED,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG1E;AAsBD,wBAAgB,yCAAyC,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAQrF"}
+{"version":3,"file":"wrfc-routing.d.ts","sourceRoot":"","sources":["../../../src/platform/core/wrfc-routing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAM3D;AAqCD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAI7D;AAED,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAa1E;AAsBD,wBAAgB,yCAAyC,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAQrF"}

package/dist/platform/core/wrfc-routing.js

@@ -8,10 +8,60 @@ export function isWrfcWorkflowRequest(text) {
     return /\bwrfc\b.{0,80}\b(review|agent|build|make|implement|fix|test|verify|for)\b/.test(normalized)
         || /\b(review|agent|build|make|implement|fix|test|verify)\b.{0,80}\bwrfc\b/.test(normalized);
 }
+/**
+ * High-precision detector for an EXPLICIT user instruction not to delegate on this turn — do not
+ * spawn agents, do not start a WRFC/owner chain, or do the work directly/yourself. When true, the
+ * routing directive is suppressed entirely: the harness must never inject a "start a WRFC chain"
+ * nudge against a user who explicitly forbade it.
+ *
+ * Deliberately conservative. Every pattern pairs an explicit negation (do not / don't / never /
+ * no / without) with a delegation concept (spawn / agent(s) / delegate / wrfc / chain), or pairs a
+ * direct-action verb with "yourself"/"directly". A plain "build X with WRFC" request contains no
+ * such negation and is NOT treated as a prohibition. Precision over recall on purpose: a rare false
+ * positive only drops an advisory suggestion (the safe direction — never coerce), whereas a false
+ * negative would re-introduce the exact coercion this fixes.
+ *
+ * The documented pattern set:
+ *   - "do not / don't / never spawn"                          → forbids spawning
+ *   - "no agents" / "without agents" / "no sub-agents"         → forbids agents
+ *   - "no delegation" / "do not / don't / never delegate"      → forbids delegation
+ *   - "do not / don't / never start a wrfc|chain" / "no wrfc"  → forbids starting a chain
+ *   - "do not / don't / never use the agent tool|agents"       → forbids the agent tool
+ *   - "do|handle|implement|write|answer … yourself|directly"   → asks for direct, non-delegated work
+ */
+const DELEGATION_PROHIBITION_PATTERNS = [
+    /\b(?:do not|don't|never) spawn\b/,
+    /\bno (?:sub-?)?agents?\b/,
+    /\bwithout (?:spawning )?(?:sub-?)?agents?\b/,
+    /\bno delegation\b/,
+    /\b(?:do not|don't|never) delegate\b/,
+    /\b(?:do not|don't|never) start (?:a |an )?(?:new )?wrfc\b/,
+    /\bno wrfc (?:chain|owner)\b/,
+    /\b(?:do not|don't|never) start (?:a |an )?(?:new )?chain\b/,
+    /\b(?:do not|don't|never) use (?:the )?agents?\b/,
+    /\b(?:do not|don't|never) use the agent tool\b/,
+    /\b(?:do|handle|implement|write|answer)(?: it| this)?(?: the \w+)? (?:yourself|directly)\b/,
+];
+export function userProhibitsDelegation(text) {
+    // Normalize curly apostrophes and whitespace so "don't"/"don’t"/"do  not" all match one pattern.
+    const normalized = text.toLowerCase().replace(/[‘’]/g, "'").replace(/\s+/g, ' ');
+    return DELEGATION_PROHIBITION_PATTERNS.some((pattern) => pattern.test(normalized));
+}
 export function buildWrfcWorkflowRoutingPrompt(text) {
     if (!isWrfcWorkflowRequest(text))
         return null;
-    return '[WRFC routing] The user is asking for WRFC-owned work. Use the agent tool to start exactly one WRFC owner chain with mode=spawn, template=engineer, reviewMode=wrfc. Do not answer by describing WRFC, and do not spawn reviewer/tester/verifier roots.';
+    // The user's explicit intent for THIS turn wins over routing: if they forbade delegation, inject
+    // nothing at all rather than nudging them toward a chain they told us not to start.
+    if (userProhibitsDelegation(text))
+        return null;
+    // Advisory, not imperative: suggest the pipeline and, if chosen, how to enter it, while asserting
+    // that the user's explicit instructions always win. mode=spawn/template/reviewMode are retained
+    // as the how-to for when the model does choose the pipeline.
+    return '[WRFC routing] This looks like work the WRFC pipeline handles well. If you choose to use it, '
+        + 'start exactly one WRFC owner chain via the agent tool (mode=spawn, template=engineer, reviewMode=wrfc) '
+        + 'rather than spawning reviewer/tester/verifier roots directly. This is a suggestion, not a command — '
+        + "the user's explicit instructions always win; if they asked you to do the work yourself or not to "
+        + 'delegate, do that instead.';
 }
 function parseToolOutput(output) {
     if (!output)

package/dist/platform/daemon/boot.d.ts

@@ -0,0 +1,63 @@
+/**
+ * boot.ts
+ *
+ * A thin public factory that wraps the daemon construction graph in ONE call.
+ *
+ * `DaemonServer` already self-composes its full runtime graph
+ * (ConfigManager → RuntimeEventBus → runtime store → createRuntimeServices →
+ * gateway/brokers/router) from a `DaemonConfig`, and installs the network
+ * transport + folds legacy session stores during `start()`. This factory just
+ * threads the caller's overrides in, enables the daemon with the given token,
+ * starts it, and hands back a stop handle — composition, not new behavior.
+ *
+ * It exists so embedders and tests do not have to hand-mirror cli.ts's graph to
+ * stand up a real daemon (isolated home, ephemeral port, auth round-trip).
+ */
+import type { ApprovalBroker } from '../control-plane/index.js';
+import { DaemonServer } from './facade.js';
+export interface BootDaemonOptions {
+    /** Injected home directory — the daemon stays entirely inside it. */
+    readonly homeDirectory: string;
+    /** Working directory (project root) the daemon operates against. */
+    readonly workingDir: string;
+    /** TCP port to bind. Default 0 → an OS-assigned ephemeral port. */
+    readonly port?: number | undefined;
+    /** Host/interface to bind. Default resolved from config (127.0.0.1). */
+    readonly host?: string | undefined;
+    /** Bearer token required by every route. Omit for session-based auth. */
+    readonly token?: string | undefined;
+    /** Daemon home dir (identity state). Defaults to the runtime resolution. */
+    readonly daemonHomeDir?: string | undefined;
+    /** Optional preconfigured ConfigManager; otherwise one is built from the dirs. */
+    readonly configManager?: import('../config/manager.js').ConfigManager | undefined;
+    /** Optional custom serve factory (tests inject Bun.serve stand-ins). */
+    readonly serveFactory?: typeof Bun.serve | undefined;
+}
+export interface BootedDaemon {
+    /** The running daemon server. */
+    readonly server: DaemonServer;
+    /**
+     * The daemon's shared approval broker (same instance the HTTP approvals routes
+     * resolve through). Lets a proof test seed a pending approval and then exercise
+     * approve/deny — including per-hunk selection — over the live wire.
+     */
+    readonly approvals: ApprovalBroker;
+    /** The bound host. */
+    readonly host: string;
+    /** The bound TCP port (resolves an ephemeral 0 to the real port). */
+    readonly port: number;
+    /** Base URL for the daemon's HTTP surface. */
+    readonly url: string;
+    /** Stop the daemon and release the port. Idempotent. */
+    stop(): Promise<void>;
+}
+/**
+ * Boot a fully-composed daemon in one call and return a stop handle.
+ *
+ * @example
+ *   const daemon = await bootDaemon({ homeDirectory, workingDir, port: 0, token });
+ *   // ... hit `${daemon.url}/api/...` with `Authorization: Bearer ${token}`
+ *   await daemon.stop();
+ */
+export declare function bootDaemon(options: BootDaemonOptions): Promise<BootedDaemon>;
+//# sourceMappingURL=boot.d.ts.map

package/dist/platform/daemon/boot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot.d.ts","sourceRoot":"","sources":["../../../src/platform/daemon/boot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,kFAAkF;IAClF,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,sBAAsB,EAAE,aAAa,GAAG,SAAS,CAAC;IAClF,wEAAwE;IACxE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,CAAC,KAAK,GAAG,SAAS,CAAC;CACtD;AAED,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAqClF"}