muonroi-cli 1.2.2 → 1.3.1

package/src/pil/layer6-output.ts

@@ -6,15 +6,81 @@
  * Each suffix is tuned to minimize output tokens while preserving quality.
  * Conversational turns (taskType=null) pass through unchanged.
  *
- * PIL-03: When ctx.outputStyle is null and ctx.taskType is not null,
- * calls classifyViaBrain with a 50ms timeout for multilingual output style
- * detection (Vietnamese+code mix that regex cannot handle). Fail-open:
- * if brain returns null/timeout, ctx.outputStyle stays null.
+ * PIL-03: When ctx.outputStyle is null and ctx.taskType is not null:
+ *   a) 50ms brain rescue — classifyViaBrain for multilingual style detection
+ *   b) task-type heuristic — domain-specific default when brain is unavailable
+ * Resolved style is propagated back onto ctx.outputStyle so the orchestrator
+ * picks it up via applyPilSuffix without falling back to the hard "concise" default.
  */
 
 import type { ToolSet } from "ai";
-import type { OutputStyle, PipelineContext } from "./types.js";
+import { classifyViaBrain } from "../ee/bridge.js";
+import { getProviderCapabilities } from "../providers/capabilities.js";
+import type { ProviderId } from "../providers/types.js";
 import { buildResponseTools } from "./response-tools.js";
+import type { OutputStyle, PipelineContext, TaskType } from "./types.js";
+
+const VALID_STYLES = ["concise", "balanced", "detailed"] as const;
+
+// Per-task-type fallback style when brain is unavailable.
+// Reflects the information density each task type genuinely needs.
+const TASK_TYPE_DEFAULT_STYLE: Record<TaskType, OutputStyle> = {
+  debug: "balanced", // needs root cause + fix context
+  plan: "balanced", // balanced by default; user requests detail explicitly
+  analyze: "balanced", // findings need brief evidence
+  documentation: "balanced", // examples + explanation
+  generate: "concise", // code speaks for itself
+  refactor: "concise", // diff is the output
+  general: "balanced",
+};
+
+// PIL-04 Tier 1.1: response-tool gating.
+//
+// Structural enforcement (JSON schema via tool call) is the root-cause fix for
+// cheap-model verbosity: the model CANNOT add preamble/epilogue/padding because
+// there is no surface outside the schema to write into. Text-based OUTPUT RULES
+// rely on instruction compliance which budget models (DeepSeek/Qwen/Llama)
+// frequently ignore.
+//
+// Activation gate: enable when the schema's payload is bounded enough that JSON
+// escaping (\n → \\n, " → \") doesn't outweigh the eliminated padding cost.
+//   - analyze: list of findings — repeated keys, no large strings → big win
+//   - plan:    numbered steps    — same shape → big win
+//   - debug:   {hypothesis, root_cause, fix:{file,diff}, verify} — diff is
+//              normally one small hunk, escaping overhead <5%; structural
+//              enforcement of the hypothesis→root_cause→fix→verify format is
+//              exactly what cheap models drift away from in prose mode
+//   - general: {response, reasoning} — pure text, zero structural overhead;
+//              this task type has the weakest text suffix today and suffers the
+//              most from verbose padding
+//
+// Disabled at task-type level (escaping cost dominates):
+//   - generate (large file contents in JSON strings)
+//   - refactor (multi-file diffs)
+//   - documentation (large markdown blocks)
+// For these, the orchestrator falls back to the markdown OUTPUT RULES suffix.
+// Per-PROVIDER disabling is layered on top via ProviderCapabilities — see
+// `src/providers/capabilities.ts`. A task type listed here may still be
+// dropped at runtime if the active provider's capability returns false.
+const RESPONSE_TOOL_TASK_TYPES = new Set<TaskType>(["analyze", "plan", "debug", "general"]);
+
+// PIL-04 Tier 1.2: per-task output token budget.
+// Hint to model. Empirically derived from interaction_logs avg output sizes;
+// ~20% below mean to nudge brevity without truncating real answers.
+const TASK_OUTPUT_BUDGET: Record<TaskType, number> = {
+  refactor: 800,
+  debug: 500,
+  plan: 700,
+  analyze: 600,
+  documentation: 900,
+  generate: 1200,
+  general: 200,
+};
+
+// PIL-04 Tier 1.3: ban preamble openers.
+// Measured ~30 tokens/turn wasted on "I'll help you...", "Sure, let me..." etc.
+// Bilingual EN+VN. Skipped for response-tools path (JSON has no preamble surface).
+const NO_PREAMBLE_RULE = `\nFORBIDDEN OPENERS: do not start with "I'll", "I will", "Let me", "Here's", "Sure", "Of course", "Tôi sẽ", "Để tôi", "Vâng". Start directly with the answer content.`;
 
 const SUFFIXES: Record<string, Record<OutputStyle, string>> = {
   refactor: {
@@ -54,25 +120,73 @@ const SUFFIXES: Record<string, Record<OutputStyle, string>> = {
   },
 };
 
+// TODO(WhoAmI-L6): when EE v4.0 Who Am I profile is available, skip
+// NO_PREAMBLE_RULE for users with feedback_style="explicit" who prefer
+// preamble. Also source TASK_TYPE_DEFAULT_STYLE from profile communication.brevity
+// instead of the hardcoded heuristic map above.
+
 export function applyPilSuffix(systemPrompt: string, ctx: PipelineContext, responseToolsActive = false): string {
+  // Chitchat: layer6Output already skipped suffix work; mirror that here so
+  // direct callers (e.g. orchestrator) don't accidentally re-inject rules.
+  if (ctx.intentKind === "chitchat") return systemPrompt;
   if (!ctx.taskType || !SUFFIXES[ctx.taskType]) return systemPrompt;
+
   if (responseToolsActive) {
     return (
       systemPrompt +
       `\nOUTPUT FORMAT: When you finish your work, use the respond_${ctx.taskType} tool to structure your final answer. You may write free-form text to explain your reasoning during the process. Use action tools (bash, read_file, edit_file, etc.) as needed, then summarize your result via respond_${ctx.taskType}.`
     );
   }
+
   const style: OutputStyle = ctx.outputStyle ?? "concise";
-  return systemPrompt + SUFFIXES[ctx.taskType][style];
+  const baseSuffix = SUFFIXES[ctx.taskType][style];
+
+  // PIL-04 Tier 1.2: output-budget hint.
+  const budget = TASK_OUTPUT_BUDGET[ctx.taskType as TaskType] ?? 600;
+  const budgetHint = `\nOUTPUT BUDGET: aim for ≤${budget} tokens. Stop when the answer is complete; do not pad.`;
+
+  // PIL-04 Tier 1.3: ban preamble (~30 tokens saved/turn).
+  let result = systemPrompt + baseSuffix + budgetHint + NO_PREAMBLE_RULE;
+
+  // T1 behavioral rules (proven-tier EE points set by Layer 3). These are
+  // project-specific reflexes the model MUST follow — injected as instructions,
+  // not as context hints, so they carry imperative weight rather than suggestion weight.
+  if (ctx.t1Rules && ctx.t1Rules.length > 0) {
+    const mandatoryLines = ctx.t1Rules.map((r) => `- ${r}`).join("\n");
+    result += `\nMANDATORY RULES (from experience — must follow):\n${mandatoryLines}`;
+  }
+
+  return result;
 }
 
-export function getResponseToolSet(ctx: PipelineContext): ToolSet {
+export function getResponseToolSet(ctx: PipelineContext, providerId?: ProviderId): ToolSet {
   if (!ctx.taskType) return {};
+  // PIL-04 Tier 1.1: gate JSON-structured output to list-shaped tasks where it
+  // wins on tokens. Code-heavy tasks fall through to markdown OUTPUT RULES.
+  if (!RESPONSE_TOOL_TASK_TYPES.has(ctx.taskType)) return {};
+  // Provider-aware gating: a provider may report it can't reliably emit
+  // valid JSON tool input for this task type (e.g. DeepSeek leaks special
+  // tokens into `general` responses). Drop the tool to avoid retry storms.
+  if (providerId) {
+    const caps = getProviderCapabilities(providerId);
+    if (!caps.supportsResponseTool(ctx.taskType)) return {};
+  }
   return buildResponseTools(ctx.taskType);
 }
 
 export async function layer6Output(ctx: PipelineContext): Promise<PipelineContext> {
   try {
+    // Chitchat short-circuit: greetings/small-talk don't need OUTPUT RULES
+    // suffixes — the model already produces a short reply for "hi" without
+    // being told to. Aligns with L4/L5 chitchat skips so the fast-path stays
+    // clean end-to-end (no GSD, no context, no suffix, no MCP).
+    if (ctx.intentKind === "chitchat") {
+      return {
+        ...ctx,
+        layers: [...ctx.layers, { name: "output-optimization", applied: false, delta: "skip:chitchat" }],
+      };
+    }
+
     if (ctx.taskType === null) {
       return {
         ...ctx,
@@ -80,14 +194,46 @@ export async function layer6Output(ctx: PipelineContext): Promise<PipelineContex
       };
     }
 
-    // Style already resolved by L1 (brain detection) + L2 (config fallback)
-    const style: OutputStyle = ctx.outputStyle ?? "concise";
+    // PIL-03: rescue outputStyle when L1 couldn't determine it (brain timeout / EE disabled).
+    let outputStyle = ctx.outputStyle;
+    let styleSource = "inherited";
+
+    if (outputStyle === null) {
+      // Pass a: 50ms brain rescue — catches multilingual prompts that regex/L1 missed.
+      // Skip when ctx._brainData is already populated: L1's unified brain call had its
+      // chance to set style; a second classifyViaBrain here is redundant work.
+      if (!ctx._brainData) {
+        try {
+          const brainRaw = await classifyViaBrain(
+            `Task type: ${ctx.taskType}. Reply ONE word only: concise | balanced | detailed\nPrompt: "${ctx.raw.slice(0, 150)}"`,
+            50,
+          );
+          if (brainRaw) {
+            const matched = VALID_STYLES.find((s) => brainRaw.toLowerCase().includes(s));
+            if (matched) {
+              outputStyle = matched;
+              styleSource = "brain-rescue";
+            }
+          }
+        } catch {
+          // fall through to pass b
+        }
+      }
+
+      // Pass b: task-type heuristic — fires when brain is also unavailable
+      if (outputStyle === null) {
+        outputStyle = TASK_TYPE_DEFAULT_STYLE[ctx.taskType as TaskType] ?? "concise";
+        styleSource = "task-heuristic";
+      }
+    }
 
+    const style: OutputStyle = outputStyle;
     const taskKey = ctx.taskType as string;
     const suffixEntry = SUFFIXES[taskKey];
     if (!suffixEntry) {
       return {
         ...ctx,
+        outputStyle,
         layers: [...ctx.layers, { name: "output-optimization", applied: false, delta: "no-suffix-entry" }],
       };
     }
@@ -95,12 +241,13 @@ export async function layer6Output(ctx: PipelineContext): Promise<PipelineContex
     const suffix = suffixEntry[style];
     return {
       ...ctx,
+      outputStyle, // propagate resolved style to orchestrator's applyPilSuffix
       layers: [
         ...ctx.layers,
         {
           name: "output-optimization",
           applied: true,
-          delta: `suffix=${ctx.taskType},style=${style},chars=${suffix.trim().length}`,
+          delta: `suffix=${ctx.taskType},style=${style},src=${styleSource},chars=${suffix.trim().length}`,
         },
       ],
     };

package/src/pil/pipeline.ts

@@ -1,14 +1,24 @@
 /**
  * src/pil/pipeline.ts
  *
- * runPipeline() entry point: orchestrates 6 sequential layers with a 200ms timeout.
- * Fail-open: any unhandled error or timeout returns the original fallback context.
+ * runPipeline() entry point: orchestrates 6 sequential layers with an
+ * adaptive timeout. Fail-open: any unhandled error or timeout returns the
+ * original fallback context.
+ *
+ * Timeout budget:
+ *   - 200ms when EE is disabled / not reachable (fast regex-only path).
+ *   - 3000ms when EE thin/thin-degraded mode is active so Layer 1 can hit
+ *     the remote `/api/brain` endpoint and Layer 6 can refine output style.
  *
  * CRITICAL: fallback is captured BEFORE runLayers() starts to ensure the timeout
  * path returns a pristine context (Pitfall 4 from RESEARCH.md).
  */
 
+import { getCachedServerBaseUrl } from "../ee/auth.js";
+import { getCachedEEClientMode } from "../ee/client-mode.js";
+import { classifyEeError, logEeFailure } from "../utils/ee-logger.js";
 import { DEFAULT_TOKEN_BUDGET } from "./budget.js";
+import { appendPilLog } from "./budget-log.js";
 import { layer1Intent } from "./layer1-intent.js";
 import { layer2Personality } from "./layer2-personality.js";
 import { layer3EeInjection } from "./layer3-ee-injection.js";
@@ -20,21 +30,66 @@ import { setPilLastResult } from "./store.js";
 import { resolveAfter } from "./timeout.js";
 import type { PipelineContext } from "./types.js";
 
-const SKIPPED_LAYERS = [
-  "personality-adaptation",
-  "ee-experience-injection",
-  "gsd-workflow-structuring",
-  "context-enrichment",
+const PIPELINE_TIMEOUT_FAST_MS = 200;
+// Sized from measured /api/pil-context distribution after server-side
+// classify+embed parallelization (commit 5b77bab in experience-engine).
+// 120-call sample: p50=1155ms, p95=2171ms, p99=2734ms, max=3105ms. 3500ms
+// gives ~800ms margin over p99. Drop further only after another infra win.
+const PIPELINE_TIMEOUT_BRAIN_MS = 3500;
+
+function pipelineTimeoutMs(): number {
+  // Allow test environments to override the timeout to avoid flaky races when
+  // the test process is under load (e.g., running 1600+ tests concurrently).
+  const envOverride = process.env.MUONROI_TEST_PIPELINE_TIMEOUT_MS;
+  if (envOverride) {
+    const parsed = parseInt(envOverride, 10);
+    if (!isNaN(parsed) && parsed > 0) return parsed;
+  }
+  const mode = getCachedEEClientMode();
+  if (mode && (mode.mode === "thin" || mode.mode === "thin-degraded" || mode.mode === "fat")) {
+    return PIPELINE_TIMEOUT_BRAIN_MS;
+  }
+  // Boot race fallback: detectEEClientMode() is fire-and-forget at startup
+  // (src/index.ts) and its /health probe can take up to 1500ms. Any prompt
+  // submitted before the probe resolves saw mode=null and fell through to the
+  // 200ms FAST budget, killing the brain call. loadEEAuthToken() IS awaited
+  // at boot, so a configured serverBaseUrl is a reliable signal that the user
+  // intends thin mode — use BRAIN budget optimistically. If the probe later
+  // fails, mode becomes "thin-degraded" which the branch above also covers.
+  if (getCachedServerBaseUrl()) {
+    return PIPELINE_TIMEOUT_BRAIN_MS;
+  }
+  return PIPELINE_TIMEOUT_FAST_MS;
+}
+
+const SKIPPED_LAYERS: Array<{ timingName: string; deltaName: string }> = [
+  { timingName: "layer2-personality", deltaName: "personality-adaptation" },
+  { timingName: "layer3-ee-injection", deltaName: "ee-experience-injection" },
+  { timingName: "layer4-gsd-structuring", deltaName: "gsd-workflow-structuring" },
+  { timingName: "layer5-context-enrichment", deltaName: "context-enrichment" },
 ];
 
 async function runLayers(ctx: PipelineContext): Promise<PipelineContext> {
   const pipelineStart = Date.now();
   const timings: Array<{ name: string; ms: number }> = [];
+  // Track each layer's contribution to the enriched-prompt size so the
+  // PIL budget log can attribute system-prompt bloat to a specific layer.
+  const layerSnapshots: Array<{
+    name: string;
+    charsBefore: number;
+    charsAfter: number;
+    charsDelta: number;
+    durationMs: number;
+  }> = [];
 
   async function timed(name: string, fn: (c: PipelineContext) => Promise<PipelineContext>): Promise<void> {
     const start = Date.now();
+    const charsBefore = ctx.enriched.length;
     ctx = await fn(ctx);
-    timings.push({ name, ms: Date.now() - start });
+    const ms = Date.now() - start;
+    const charsAfter = ctx.enriched.length;
+    timings.push({ name, ms });
+    layerSnapshots.push({ name, charsBefore, charsAfter, charsDelta: charsAfter - charsBefore, durationMs: ms });
   }
 
   await timed("layer1-intent", layer1Intent);
@@ -45,14 +100,18 @@ async function runLayers(ctx: PipelineContext): Promise<PipelineContext> {
     await timed("layer4-gsd-structuring", layer4Gsd);
     await timed("layer5-context-enrichment", layer5Context);
   } else {
-    for (const name of SKIPPED_LAYERS) {
-      timings.push({ name: `layer-${name}`, ms: 0 });
+    for (const { timingName } of SKIPPED_LAYERS) {
+      timings.push({ name: timingName, ms: 0 });
     }
     ctx = {
       ...ctx,
       layers: [
         ...ctx.layers,
-        ...SKIPPED_LAYERS.map((name) => ({ name, applied: false, delta: "skipped:null-taskType" })),
+        ...SKIPPED_LAYERS.map(({ deltaName }) => ({
+          name: deltaName,
+          applied: false,
+          delta: "skipped:null-taskType",
+        })),
       ],
     };
   }
@@ -71,11 +130,31 @@ async function runLayers(ctx: PipelineContext): Promise<PipelineContext> {
       layerTimings: timings,
       inputChars: ctx.raw.length,
       outputChars: ctx.enriched.length,
-      estimatedTokensSaved: Math.round(suffixChars / 4),
+      suffixInstructionTokens: Math.round(suffixChars / 4),
       enrichmentTokensAdded: Math.round(enrichmentCharsAdded / 4),
     },
   };
 
+  // Best-effort PIL budget log — attributes prompt-size growth to each layer.
+  // Fire-and-forget; never await on the hot path.
+  appendPilLog({
+    ts: pipelineStart,
+    sessionId: ctx.sessionId ?? null,
+    taskType: ctx.taskType ?? null,
+    domain: ctx.domain ?? null,
+    confidence: ctx.confidence ?? 0,
+    rawChars: ctx.raw.length,
+    enrichedChars: ctx.enriched.length,
+    totalDeltaChars: ctx.enriched.length - ctx.raw.length,
+    totalMs: Date.now() - pipelineStart,
+    layers: layerSnapshots,
+    fallbackReason: ctx.fallbackReason ?? null,
+    intentDetection: ctx._intentTrace ?? null,
+  }).catch((err) => {
+    logEeFailure("pil.pipeline.logInteraction", classifyEeError(err), err);
+    return undefined;
+  });
+
   return ctx;
 }
 
@@ -83,6 +162,7 @@ export interface PipelineOptions {
   gsdPhase?: string | null;
   resumeDigest?: string | null;
   activeRunId?: string | null;
+  sessionId?: string | null;
 }
 
 export async function runPipeline(raw: string, options?: PipelineOptions): Promise<PipelineContext> {
@@ -99,14 +179,29 @@ export async function runPipeline(raw: string, options?: PipelineOptions): Promi
     gsdPhase: options?.gsdPhase ?? null,
     resumeDigest: options?.resumeDigest ?? null,
     activeRunId: options?.activeRunId ?? null,
+    sessionId: options?.sessionId ?? null,
+    fallbackReason: null,
   };
   try {
-    const result = await Promise.race([runLayers({ ...fallback }), resolveAfter(200, fallback)]);
-    const validated = PipelineContextSchema.safeParse(result).success ? result : fallback;
-    setPilLastResult(validated);
-    return validated;
-  } catch {
-    setPilLastResult(fallback);
-    return fallback;
+    const result = await Promise.race([
+      runLayers({ ...fallback }),
+      resolveAfter(pipelineTimeoutMs(), { ...fallback, fallbackReason: "pipeline-timeout" } as PipelineContext),
+    ]);
+    const parse = PipelineContextSchema.safeParse(result);
+    if (!parse.success) {
+      const validated: PipelineContext = {
+        ...fallback,
+        fallbackReason: `schema-reject:${parse.error.issues[0]?.path?.join(".") ?? "unknown"}`,
+      } as PipelineContext;
+      setPilLastResult(validated);
+      return validated;
+    }
+    setPilLastResult(result);
+    return result;
+  } catch (err) {
+    const reason = err instanceof Error ? `exception:${err.name}` : "exception:unknown";
+    const failed = { ...fallback, fallbackReason: reason } as PipelineContext;
+    setPilLastResult(failed);
+    return failed;
   }
 }

package/src/pil/response-tools.ts

@@ -1,5 +1,5 @@
-import { z } from "zod";
 import type { ToolSet } from "ai";
+import { z } from "zod";
 
 const RefactorSchema = z.object({
   summary: z.string().describe("One-line summary of what changed"),
@@ -107,4 +107,4 @@ export function buildResponseTools(taskType: string): ToolSet {
   };
 }
 
-export { RefactorSchema, DebugSchema, PlanSchema, AnalyzeSchema, DocsSchema, GenerateSchema, GeneralSchema };
+export { AnalyzeSchema, DebugSchema, DocsSchema, GeneralSchema, GenerateSchema, PlanSchema, RefactorSchema };

package/src/pil/schema.ts

@@ -7,7 +7,7 @@
 
 import { z } from "zod";
 
-export const TaskTypeSchema = z.enum(["refactor", "debug", "plan", "analyze", "documentation", "generate"]);
+export const TaskTypeSchema = z.enum(["refactor", "debug", "plan", "analyze", "documentation", "generate", "general"]);
 
 export const OutputStyleSchema = z.enum(["concise", "detailed", "balanced"]);
 
@@ -27,7 +27,7 @@ export const PipelineMetricsSchema = z.object({
   layerTimings: z.array(LayerTimingSchema),
   inputChars: z.number().min(0),
   outputChars: z.number().min(0),
-  estimatedTokensSaved: z.number().min(0),
+  suffixInstructionTokens: z.number().min(0),
   enrichmentTokensAdded: z.number().min(0),
 });
 
@@ -46,4 +46,58 @@ export const PipelineContextSchema = z.object({
   resumeDigest: z.string().nullable().optional(),
   activeRunId: z.string().nullable().optional(),
   digestAgeMs: z.number().nullable().optional(),
+  sessionId: z.string().nullable().optional(),
+  complexityTier: z.enum(["quick", "standard", "heavy"]).nullable().optional(),
+  grayAreas: z
+    .array(
+      z.object({
+        dimension: z.enum(["scope", "target", "format", "convention", "depth", "audience"]),
+        id: z.string(),
+        question: z.string(),
+        options: z.array(z.string()),
+      }),
+    )
+    .optional(),
+  fallbackReason: z.string().nullable().optional(),
+  // T1 behavioral rules from EE proven-tier points, injected as mandatory suffix by Layer 6.
+  t1Rules: z.array(z.string()).optional(),
+  _brainData: z
+    .object({
+      t0_principles: z.array(z.object({ text: z.string(), score: z.number() })),
+      t1_rules: z.array(z.string()),
+      t2_patterns: z.array(z.object({ text: z.string(), score: z.number() })),
+      retrieval_skipped_reason: z.string().nullable(),
+    })
+    .nullable()
+    .optional(),
 });
+
+const ScoredText = z.object({ text: z.string(), score: z.number() });
+
+export const PilContextResponseSchema = z
+  .object({
+    // Classification
+    taskType: TaskTypeSchema.nullable(),
+    intentKind: z.enum(["task", "chitchat"]).nullable(),
+    outputStyle: OutputStyleSchema,
+    confidence: z.number().min(0).max(1),
+    domain: z.string().nullable(),
+
+    // GSD routing hint
+    gsd_phase: z.enum(["discuss", "execute"]).nullable(),
+    gsd_route_source: z.enum(["ee", "preset", "none"]),
+
+    // Experience retrieval
+    t0_principles: z.array(ScoredText),
+    t1_rules: z.array(z.string()),
+    t2_patterns: z.array(ScoredText),
+    retrieval_skipped_reason: z.string().nullable(),
+
+    // Meta
+    cache_hit: z.boolean(),
+    inference_ms: z.number().min(0),
+    schema_version: z.string(),
+  })
+  .passthrough(); // forward-compat: ignore unknown fields from future server versions
+
+export type PilContextResponse = z.infer<typeof PilContextResponseSchema>;

package/src/pil/types.ts

@@ -4,10 +4,15 @@
  * Core type definitions for the Prompt Intelligence Layer (PIL) pipeline.
  */
 
-export type TaskType = "refactor" | "debug" | "plan" | "analyze" | "documentation" | "generate";
+import type { ComplexityTier } from "../gsd/complexity.js";
+import type { GrayAreaQuestion } from "../gsd/gray-areas.js";
+
+export type TaskType = "refactor" | "debug" | "plan" | "analyze" | "documentation" | "generate" | "general";
 
 export type OutputStyle = "concise" | "detailed" | "balanced";
 
+export type { ComplexityTier, GrayAreaQuestion };
+
 export interface LayerResult {
   name: string;
   applied: boolean;
@@ -19,7 +24,8 @@ export interface PipelineMetrics {
   layerTimings: Array<{ name: string; ms: number }>;
   inputChars: number;
   outputChars: number;
-  estimatedTokensSaved: number;
+  /** Tokens added to system prompt input by the L6 suffix instruction. NOT tokens saved in output. */
+  suffixInstructionTokens: number;
   enrichmentTokensAdded: number;
 }
 
@@ -39,4 +45,106 @@ export interface PipelineContext {
   resumeDigest?: string | null;
   activeRunId?: string | null;
   digestAgeMs?: number | null;
+  sessionId?: string | null;
+  /** GSD-native triage tier (set by layer4). */
+  complexityTier?: ComplexityTier | null;
+  /** Heuristic gray-area questions surfaced by layer4 when tier === "heavy". */
+  grayAreas?: GrayAreaQuestion[];
+  /**
+   * Coarse intent: "chitchat" for greetings/small-talk/no-coding-intent,
+   * "task" when there is a coding intent, null when undetermined. Set by
+   * layer1; respected by layer4 (skip GSD directive) and layer5 (skip
+   * heavy context like recent-files / flow-state). Distinct from taskType
+   * "general", which conflates chitchat with low-confidence fallback.
+   */
+  intentKind?: "task" | "chitchat" | null;
+  /**
+   * Diagnostic: when the pipeline returns the fallback context, this records
+   * the reason (timeout / schema-reject / exception). Null on the happy path.
+   * Helps distinguish "fallback because brain unreachable" from "fallback
+   * because schema validation failed" when reading interaction_logs.
+   */
+  fallbackReason?: string | null;
+  /**
+   * T1 behavioral rules extracted by Layer 3 from EE proven-tier points.
+   * These are high-hitCount / tier=proven entries that have been promoted to
+   * behavioral reflex status. Layer 6 appends them as MANDATORY RULES to the
+   * output suffix so the model treats them as instructions, not just context.
+   *
+   * TODO(WhoAmI): when EE v4.0 Who Am I is implemented, merge project-level
+   * t1Rules with user-level personality directives from the profile model.
+   */
+  t1Rules?: string[];
+  /**
+   * Brain-derived data populated by Layer 1 when the unified /api/pil-context
+   * call succeeds. Layers 3, 5, 6 read from here instead of issuing their own
+   * brain calls. Null when L1 took the legacy path (brain unreachable, low
+   * pipeline budget, or feature flag disabled).
+   */
+  _brainData?: BrainData | null;
+  /**
+   * Step-by-step task detection trace from Layer 1. Captures which Pass set
+   * the final taskType + style, so cost reports can answer "are we wasting
+   * brain calls when regex would have answered?". Optional — `pipeline.ts`
+   * forwards it to the PIL budget log when present.
+   */
+  _intentTrace?: IntentDetectionTrace | null;
+}
+
+/**
+ * One-shot snapshot of Layer 1's three-pass intent detection cascade.
+ * Cheaper passes hit first; later passes only run when earlier ones abstain.
+ * Each `*Hit` flag answers "did this pass decide the final taskType/style?"
+ * — at most one of `pass1/2/3` should be true for `*Hit` fields.
+ */
+export interface IntentDetectionTrace {
+  /**
+   * Detected target framework for BB-aware retrieval.
+   * "muonroi-building-block" when Directory.Build.props + *.sln + src/Muonroi.* heuristic matches.
+   * Undefined when no framework-specific signals detected.
+   */
+  targetFramework?: "muonroi-building-block" | string;
+  /** Classifier reason string (e.g. "regex:debug", "tree-sitter:typescript"). */
+  pass1Reason: string;
+  /** Confidence reported by the classifier (0..1). */
+  pass1Confidence: number;
+  /** taskType derived from pass1Reason via REASON_TO_TASK_TYPE; null if no map. */
+  pass1TaskType: string | null;
+  /** Pass 1 alone decided the final taskType (no later pass overrode it). */
+  pass1Hit: boolean;
+  /** Pass 2 keyword fallback matched. */
+  pass2Hit: boolean;
+  /** Which keyword pattern matched (string repr of regex source) — only set when pass2Hit. */
+  pass2Pattern?: string;
+  /** Pass 2.5 hot-path chitchat short-circuit fired (≤10 chars + ≤2 words). */
+  pass25ChitchatHit: boolean;
+  /** Unified /api/pil-context attempted (feature flag on + weak local signal). */
+  pass3UnifiedAttempted: boolean;
+  /** Unified call returned a non-null response. */
+  pass3UnifiedSucceeded: boolean;
+  /** Legacy brain call attempted for TASK classification (1500ms budget). */
+  pass3LegacyTaskAttempted: boolean;
+  /** Legacy task-classification call returned a non-null response. */
+  pass3LegacyTaskSucceeded: boolean;
+  /** Legacy brain call attempted for STYLE detection (800ms budget). */
+  pass3LegacyStyleAttempted: boolean;
+  /** Legacy style-detection call returned a non-null response. */
+  pass3LegacyStyleSucceeded: boolean;
+  /** How the final outputStyle was resolved. */
+  styleSource: "explicit-regex" | "brain-unified" | "brain-legacy" | "chitchat-default" | "classifier-default" | "none";
+  /** Final taskType emitted by Layer 1. */
+  finalTaskType: string | null;
+  /** Final confidence emitted by Layer 1. */
+  finalConfidence: number;
+  /** Heuristic complexity routing decision: low / medium / high. */
+  complexity: "low" | "medium" | "high";
+  /** Raw score that produced complexity (-3..+10 range). */
+  complexityScore: number;
+}
+
+export interface BrainData {
+  t0_principles: Array<{ text: string; score: number }>;
+  t1_rules: string[];
+  t2_patterns: Array<{ text: string; score: number }>;
+  retrieval_skipped_reason: string | null;
 }