gsd-pi 2.59.0 → 2.60.0-dev.d9052f5

package/src/resources/extensions/gsd/model-router.ts

@@ -10,6 +10,7 @@ import type { ResolvedModelConfig } from "./preferences.js";
 
 export interface DynamicRoutingConfig {
   enabled?: boolean;
+  capability_routing?: boolean;    // default: false — enable capability profile scoring
   tier_models?: {
     light?: string;
     standard?: string;
@@ -32,6 +33,12 @@ export interface RoutingDecision {
   wasDowngraded: boolean;
   /** Human-readable reason for this decision */
   reason: string;
+  /** How the model was selected. */
+  selectionMethod?: "tier-only" | "capability-scored";
+  /** Capability scores per model (when capability-scored). */
+  capabilityScores?: Record<string, number>;
+  /** Task requirement vector (when capability-scored). */
+  taskRequirements?: Partial<Record<string, number>>;
 }
 
 // ─── Known Model Tiers ───────────────────────────────────────────────────────
@@ -114,6 +121,91 @@ const MODEL_COST_PER_1K_INPUT: Record<string, number> = {
   "deepseek-chat": 0.00014,
 };
 
+// ─── Capability Profiles (ADR-004 Phase 2) ──────────────────────────────────
+// 7-dimension profiles, 0–100 normalized. Models without a profile
+// score 50 uniformly — capability scoring is a no-op for them.
+
+export interface ModelCapabilities {
+  coding: number;
+  debugging: number;
+  research: number;
+  reasoning: number;
+  speed: number;
+  longContext: number;
+  instruction: number;
+}
+
+export const MODEL_CAPABILITY_PROFILES: Record<string, ModelCapabilities> = {
+  "claude-opus-4-6":     { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
+  "claude-sonnet-4-6":   { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
+  "claude-haiku-4-5":    { coding: 60, debugging: 50, research: 45, reasoning: 50, speed: 95, longContext: 50, instruction: 75 },
+  "gpt-4o":              { coding: 80, debugging: 75, research: 70, reasoning: 75, speed: 65, longContext: 70, instruction: 80 },
+  "gpt-4o-mini":         { coding: 55, debugging: 45, research: 40, reasoning: 45, speed: 90, longContext: 45, instruction: 70 },
+  "gemini-2.5-pro":      { coding: 75, debugging: 70, research: 85, reasoning: 75, speed: 55, longContext: 90, instruction: 75 },
+  "gemini-2.0-flash":    { coding: 50, debugging: 40, research: 50, reasoning: 40, speed: 95, longContext: 60, instruction: 65 },
+  "deepseek-chat":       { coding: 75, debugging: 65, research: 55, reasoning: 70, speed: 70, longContext: 55, instruction: 65 },
+  "o3":                  { coding: 80, debugging: 85, research: 80, reasoning: 92, speed: 25, longContext: 70, instruction: 85 },
+};
+
+const BASE_REQUIREMENTS: Record<string, Partial<Record<keyof ModelCapabilities, number>>> = {
+  "execute-task":       { coding: 0.9, instruction: 0.7, speed: 0.3 },
+  "research-milestone": { research: 0.9, longContext: 0.7, reasoning: 0.5 },
+  "research-slice":     { research: 0.9, longContext: 0.7, reasoning: 0.5 },
+  "plan-milestone":     { reasoning: 0.9, coding: 0.5 },
+  "plan-slice":         { reasoning: 0.9, coding: 0.5 },
+  "replan-slice":       { reasoning: 0.9, debugging: 0.6, coding: 0.5 },
+  "reassess-roadmap":   { reasoning: 0.9, research: 0.5 },
+  "complete-slice":     { instruction: 0.8, speed: 0.7 },
+  "run-uat":            { instruction: 0.7, speed: 0.8 },
+  "discuss-milestone":  { reasoning: 0.6, instruction: 0.7 },
+  "complete-milestone": { instruction: 0.8, reasoning: 0.5 },
+};
+
+/**
+ * Compute a task requirement vector from unit type and optional metadata.
+ */
+export function computeTaskRequirements(
+  unitType: string,
+  metadata?: { tags?: string[]; complexityKeywords?: string[]; fileCount?: number; estimatedLines?: number },
+): Partial<Record<keyof ModelCapabilities, number>> {
+  const base = { ...(BASE_REQUIREMENTS[unitType] ?? { reasoning: 0.5 }) };
+
+  if (unitType === "execute-task" && metadata) {
+    if (metadata.tags?.some(t => /^(docs?|readme|comment|config|typo|rename)$/i.test(t))) {
+      return { ...base, instruction: 0.9, coding: 0.3, speed: 0.7 };
+    }
+    if (metadata.complexityKeywords?.some(k => k === "concurrency" || k === "compatibility")) {
+      return { ...base, debugging: 0.9, reasoning: 0.8 };
+    }
+    if (metadata.complexityKeywords?.some(k => k === "migration" || k === "architecture")) {
+      return { ...base, reasoning: 0.9, coding: 0.8 };
+    }
+    if ((metadata.fileCount ?? 0) >= 6 || (metadata.estimatedLines ?? 0) >= 500) {
+      return { ...base, coding: 0.9, reasoning: 0.7 };
+    }
+  }
+
+  return base;
+}
+
+/**
+ * Score a model against a task requirement vector.
+ * Returns weighted average in range 0–100. Returns 50 for empty requirements.
+ */
+export function scoreModel(
+  capabilities: ModelCapabilities,
+  requirements: Partial<Record<keyof ModelCapabilities, number>>,
+): number {
+  let weightedSum = 0;
+  let weightSum = 0;
+  for (const [dim, weight] of Object.entries(requirements)) {
+    const capability = capabilities[dim as keyof ModelCapabilities] ?? 50;
+    weightedSum += weight * capability;
+    weightSum += weight;
+  }
+  return weightSum > 0 ? weightedSum / weightSum : 50;
+}
+
 // ─── Public API ──────────────────────────────────────────────────────────────
 
 /**
@@ -132,6 +224,8 @@ export function resolveModelForComplexity(
   phaseConfig: ResolvedModelConfig | undefined,
   routingConfig: DynamicRoutingConfig,
   availableModelIds: string[],
+  unitType?: string,
+  metadata?: { tags?: string[]; complexityKeywords?: string[]; fileCount?: number; estimatedLines?: number },
 ): RoutingDecision {
   // If no phase config or routing disabled, pass through
   if (!phaseConfig || !routingConfig.enabled) {
@@ -175,25 +269,40 @@ export function resolveModelForComplexity(
   }
 
   // Find the best model for the requested tier
-  const targetModelId = findModelForTier(
-    requestedTier,
-    routingConfig,
-    availableModelIds,
-    routingConfig.cross_provider !== false,
-  );
+  const useCapabilityScoring = routingConfig.capability_routing && unitType;
+
+  let targetModelId: string | null;
+  let capabilityScores: Record<string, number> | undefined;
+  let taskRequirements: Partial<Record<string, number>> | undefined;
+  let selectionMethod: "tier-only" | "capability-scored" = "tier-only";
+
+  if (useCapabilityScoring) {
+    const result = findModelForTierWithCapability(
+      requestedTier, routingConfig, availableModelIds,
+      routingConfig.cross_provider !== false, unitType, metadata,
+    );
+    targetModelId = result.modelId;
+    capabilityScores = Object.keys(result.scores).length > 0 ? result.scores : undefined;
+    taskRequirements = Object.keys(result.requirements).length > 0 ? result.requirements : undefined;
+    selectionMethod = capabilityScores ? "capability-scored" : "tier-only";
+  } else {
+    targetModelId = findModelForTier(
+      requestedTier, routingConfig, availableModelIds,
+      routingConfig.cross_provider !== false,
+    );
+  }
 
   if (!targetModelId) {
-    // No suitable model found — use configured primary
     return {
       modelId: configuredPrimary,
       fallbacks: phaseConfig.fallbacks,
       tier: requestedTier,
       wasDowngraded: false,
       reason: `no ${requestedTier}-tier model available`,
+      selectionMethod,
     };
   }
 
-  // Build fallback chain: [downgraded_model, ...configured_fallbacks, configured_primary]
   const fallbacks = [
     ...phaseConfig.fallbacks.filter(f => f !== targetModelId),
     configuredPrimary,
@@ -205,6 +314,9 @@ export function resolveModelForComplexity(
     tier: requestedTier,
     wasDowngraded: true,
     reason: classification.reason,
+    selectionMethod,
+    capabilityScores,
+    taskRequirements,
   };
 }
 
@@ -226,6 +338,7 @@ export function escalateTier(currentTier: ComplexityTier): ComplexityTier | null
 export function defaultRoutingConfig(): DynamicRoutingConfig {
   return {
     enabled: true,
+    capability_routing: false,
     escalate_on_failure: true,
     budget_pressure: true,
     cross_provider: true,
@@ -298,6 +411,56 @@ function findModelForTier(
   return candidates[0] ?? null;
 }
 
+function findModelForTierWithCapability(
+  tier: ComplexityTier,
+  config: DynamicRoutingConfig,
+  availableModelIds: string[],
+  crossProvider: boolean,
+  unitType: string,
+  metadata?: { tags?: string[]; complexityKeywords?: string[]; fileCount?: number; estimatedLines?: number },
+): { modelId: string | null; scores: Record<string, number>; requirements: Partial<Record<string, number>> } {
+  const explicitModel = config.tier_models?.[tier];
+  if (explicitModel) {
+    const match = availableModelIds.find(id => {
+      const bareAvail = id.includes("/") ? id.split("/").pop()! : id;
+      const bareExplicit = explicitModel.includes("/") ? explicitModel.split("/").pop()! : explicitModel;
+      return bareAvail === bareExplicit || id === explicitModel;
+    });
+    if (match) return { modelId: match, scores: {}, requirements: {} };
+  }
+
+  const requirements = computeTaskRequirements(unitType, metadata);
+  const candidates = availableModelIds.filter(id => getModelTier(id) === tier);
+  if (candidates.length === 0) return { modelId: null, scores: {}, requirements };
+
+  const scores: Record<string, number> = {};
+  for (const id of candidates) {
+    const bareId = id.includes("/") ? id.split("/").pop()! : id;
+    const profile = getModelProfile(bareId);
+    scores[id] = scoreModel(profile, requirements);
+  }
+
+  candidates.sort((a, b) => {
+    const scoreDiff = scores[b] - scores[a];
+    if (Math.abs(scoreDiff) > 2) return scoreDiff;
+    if (crossProvider) {
+      const costDiff = getModelCost(a) - getModelCost(b);
+      if (costDiff !== 0) return costDiff;
+    }
+    return a.localeCompare(b);
+  });
+
+  return { modelId: candidates[0], scores, requirements };
+}
+
+function getModelProfile(bareId: string): ModelCapabilities {
+  if (MODEL_CAPABILITY_PROFILES[bareId]) return MODEL_CAPABILITY_PROFILES[bareId];
+  for (const [knownId, profile] of Object.entries(MODEL_CAPABILITY_PROFILES)) {
+    if (bareId.includes(knownId) || knownId.includes(bareId)) return profile;
+  }
+  return { coding: 50, debugging: 50, research: 50, reasoning: 50, speed: 50, longContext: 50, instruction: 50 };
+}
+
 function getModelCost(modelId: string): number {
   const bareId = modelId.includes("/") ? modelId.split("/").pop()! : modelId;
 

package/src/resources/extensions/gsd/phase-anchor.ts

@@ -0,0 +1,71 @@
+/**
+ * Phase handoff anchors — compact structured summaries written between
+ * GSD auto-mode phases so downstream agents inherit decisions, blockers,
+ * and intent without re-inferring from scratch.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
+
+export interface PhaseAnchor {
+  phase: string;
+  milestoneId: string;
+  generatedAt: string;
+  intent: string;
+  decisions: string[];
+  blockers: string[];
+  nextSteps: string[];
+}
+
+function anchorsDir(basePath: string, milestoneId: string): string {
+  return join(gsdRoot(basePath), "milestones", milestoneId, "anchors");
+}
+
+function anchorPath(basePath: string, milestoneId: string, phase: string): string {
+  return join(anchorsDir(basePath, milestoneId), `${phase}.json`);
+}
+
+export function writePhaseAnchor(basePath: string, milestoneId: string, anchor: PhaseAnchor): void {
+  const dir = anchorsDir(basePath, milestoneId);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(anchorPath(basePath, milestoneId, anchor.phase), JSON.stringify(anchor, null, 2), "utf-8");
+}
+
+export function readPhaseAnchor(basePath: string, milestoneId: string, phase: string): PhaseAnchor | null {
+  const path = anchorPath(basePath, milestoneId, phase);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as PhaseAnchor;
+  } catch {
+    return null;
+  }
+}
+
+export function formatAnchorForPrompt(anchor: PhaseAnchor): string {
+  const lines: string[] = [
+    `## Handoff from ${anchor.phase}`,
+    "",
+    `**Intent:** ${anchor.intent}`,
+  ];
+
+  if (anchor.decisions.length > 0) {
+    lines.push("", "**Decisions:**");
+    for (const d of anchor.decisions) lines.push(`- ${d}`);
+  }
+
+  if (anchor.blockers.length > 0) {
+    lines.push("", "**Blockers:**");
+    for (const b of anchor.blockers) lines.push(`- ${b}`);
+  }
+
+  if (anchor.nextSteps.length > 0) {
+    lines.push("", "**Next steps:**");
+    for (const s of anchor.nextSteps) lines.push(`- ${s}`);
+  }
+
+  lines.push("", "---");
+  return lines.join("\n");
+}

package/src/resources/extensions/gsd/preferences-types.ts

@@ -21,6 +21,13 @@ import type {
   GateEvaluationConfig,
 } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
+
+export interface ContextManagementConfig {
+  observation_masking?: boolean;          // default: true
+  observation_mask_turns?: number;        // default: 8, range: 1-50
+  compaction_threshold_percent?: number;  // default: 0.70, range: 0.5-0.95
+  tool_result_max_chars?: number;         // default: 800, range: 200-10000
+}
 import type { GitHubSyncConfig } from "../github-sync/types.js";
 
 // ─── Workflow Modes ──────────────────────────────────────────────────────────
@@ -94,6 +101,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "forensics_dedup",
   "show_token_cost",
   "stale_commit_threshold_minutes",
+  "context_management",
   "experimental",
 ]);
 
@@ -227,6 +235,7 @@ export interface GSDPreferences {
   post_unit_hooks?: PostUnitHookConfig[];
   pre_dispatch_hooks?: PreDispatchHookConfig[];
   dynamic_routing?: DynamicRoutingConfig;
+  context_management?: ContextManagementConfig;
   token_profile?: TokenProfile;
   phases?: PhaseSkipPreferences;
   auto_visualize?: boolean;

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -428,6 +428,10 @@ export function validatePreferences(preferences: GSDPreferences): {
         if (typeof dr.hooks === "boolean") validDr.hooks = dr.hooks;
         else errors.push("dynamic_routing.hooks must be a boolean");
       }
+      if (dr.capability_routing !== undefined) {
+        if (typeof dr.capability_routing === "boolean") validDr.capability_routing = dr.capability_routing;
+        else errors.push("dynamic_routing.capability_routing must be a boolean");
+      }
       if (dr.tier_models !== undefined) {
         if (typeof dr.tier_models === "object" && dr.tier_models !== null) {
           const tm = dr.tier_models as Record<string, unknown>;
@@ -452,6 +456,40 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Context Management ──────────────────────────────────────────────
+  if (preferences.context_management !== undefined) {
+    if (typeof preferences.context_management === "object" && preferences.context_management !== null) {
+      const cm = preferences.context_management as unknown as Record<string, unknown>;
+      const validCm: Record<string, unknown> = {};
+
+      if (cm.observation_masking !== undefined) {
+        if (typeof cm.observation_masking === "boolean") validCm.observation_masking = cm.observation_masking;
+        else errors.push("context_management.observation_masking must be a boolean");
+      }
+      if (cm.observation_mask_turns !== undefined) {
+        const turns = cm.observation_mask_turns;
+        if (typeof turns === "number" && turns >= 1 && turns <= 50) validCm.observation_mask_turns = turns;
+        else errors.push("context_management.observation_mask_turns must be a number between 1 and 50");
+      }
+      if (cm.compaction_threshold_percent !== undefined) {
+        const pct = cm.compaction_threshold_percent;
+        if (typeof pct === "number" && pct >= 0.5 && pct <= 0.95) validCm.compaction_threshold_percent = pct;
+        else errors.push("context_management.compaction_threshold_percent must be a number between 0.5 and 0.95");
+      }
+      if (cm.tool_result_max_chars !== undefined) {
+        const chars = cm.tool_result_max_chars;
+        if (typeof chars === "number" && chars >= 200 && chars <= 10000) validCm.tool_result_max_chars = chars;
+        else errors.push("context_management.tool_result_max_chars must be a number between 200 and 10000");
+      }
+
+      if (Object.keys(validCm).length > 0) {
+        validated.context_management = validCm as any;
+      }
+    } else {
+      errors.push("context_management must be an object");
+    }
+  }
+
   // ─── Parallel Config ────────────────────────────────────────────────────
   if (preferences.parallel && typeof preferences.parallel === "object") {
     const p = preferences.parallel as unknown as Record<string, unknown>;

package/src/resources/extensions/gsd/prompts/execute-task.md

@@ -12,6 +12,8 @@ A researcher explored the codebase and a planner decomposed the work — you are
 
 {{runtimeContext}}
 
+{{phaseAnchorSection}}
+
 {{resumeSection}}
 
 {{carryForwardSection}}

package/src/resources/extensions/gsd/prompts/rethink.md

@@ -45,6 +45,13 @@ reason: "<reason>"
 ### Unpark a milestone
 Remove the `{ID}-PARKED.md` file from the milestone directory to reactivate it.
 
+### Skip a slice
+Mark a slice as skipped so auto-mode advances past it without executing. Use the `gsd_skip_slice` tool:
+```
+gsd_skip_slice({ milestone_id: "M003", slice_id: "S02", reason: "Descoped — feature moved to M005" })
+```
+Skipped slices are treated as closed by the state machine (like "complete" but distinct). Use when a slice is no longer needed or has been superseded. The slice data is preserved for reference.
+
 ### Discard a milestone
 **Permanently** delete a milestone directory and prune it from QUEUE-ORDER.json. **Always confirm with the user before discarding.** Warn explicitly if the milestone has completed work.
 

package/src/resources/extensions/gsd/prompts/triage-captures.md

@@ -20,6 +20,8 @@ The user captured thoughts during execution using `/gsd capture`. Your job is to
 
 For each capture, classify it as one of:
 
+- **stop**: User directive to halt auto-mode immediately. Use when the user says "stop", "halt", "abort", "don't continue", "pause", or otherwise wants execution to cease. Auto-mode will pause after the current unit completes. Examples: "stop running", "halt execution", "don't continue".
+- **backtrack**: User directive to abandon the current milestone and return to a previous one. The user believes earlier milestones missed critical features or need rework. Include the target milestone ID (e.g., M003) in the Resolution field. Auto-mode will pause and write a regression marker. Examples: "restart from M003", "go back to milestone 3", "M004 and M005 failed, restart from M003".
 - **quick-task**: Small, self-contained, no downstream impact. Can be done in minutes without modifying the plan. Examples: fix a typo, add a missing import, tweak a config value.
 - **inject**: Belongs in the current slice but wasn't planned. Needs a new task added to the slice plan. Examples: add error handling to a module being built, add a missing test case for current work.
 - **defer**: Belongs in a future slice or milestone. Not urgent for current work. Examples: performance optimization, feature that depends on unbuilt infrastructure, nice-to-have enhancement.
@@ -28,10 +30,12 @@ For each capture, classify it as one of:
 
 ## Decision Guidelines
 
+- **ALWAYS classify as stop** when the user explicitly says "stop", "halt", "abort", or "don't continue". Never shoe-horn a stop directive into "replan" or "note".
+- **ALWAYS classify as backtrack** when the user references returning to a previous milestone, restarting from an earlier point, or abandoning current milestone work. Include the target milestone ID in the Resolution field (e.g., "Backtrack to M003").
 - Prefer **quick-task** when the work is clearly small and self-contained.
 - Prefer **inject** over **replan** when only a new task is needed, not rewriting existing ones.
 - Prefer **defer** over **inject** when the work doesn't belong in the current slice's scope.
-- Use **replan** only when remaining incomplete tasks need to change — not just for adding work.
+- Use **replan** only when remaining incomplete tasks in the *current slice* need to change — not for cross-milestone issues.
 - Use **note** for observations that don't require action.
 - When unsure between quick-task and inject, consider: will this take more than 10 minutes? If yes, inject.
 
@@ -46,6 +50,7 @@ For each capture, classify it as one of:
    - If applicable, which files would be affected
    
    For captures classified as **note** or **defer**, auto-confirm without asking — these are low-impact.
+   For captures classified as **stop** or **backtrack**, auto-confirm without asking — these are urgent user directives that must be honored immediately.
    For captures classified as **quick-task**, **inject**, or **replan**, ask the user to confirm or choose a different classification.
 
 3. **Update** `.gsd/CAPTURES.md` — for each capture, update its section with the confirmed classification:

package/src/resources/extensions/gsd/rethink.ts

@@ -112,8 +112,11 @@ function buildRethinkData(
     if (dbAvailable && status !== "complete") {
       const slices = getMilestoneSlices(mid);
       if (slices.length > 0) {
-        const done = slices.filter(s => s.status === "complete").length;
-        sliceInfo = `${done}/${slices.length} complete`;
+        const done = slices.filter(s => s.status === "complete" || s.status === "done").length;
+        const skipped = slices.filter(s => s.status === "skipped").length;
+        sliceInfo = skipped > 0
+          ? `${done}/${slices.length} complete, ${skipped} skipped`
+          : `${done}/${slices.length} complete`;
       }
     }
 

package/src/resources/extensions/gsd/state.ts

@@ -295,7 +295,7 @@ function extractContextTitle(content: string | null, fallback: string): string {
  * Helper: check if a DB status counts as "done" (handles K002 ambiguity).
  */
 function isStatusDone(status: string): boolean {
-  return status === 'complete' || status === 'done';
+  return status === 'complete' || status === 'done' || status === 'skipped';
 }
 
 /**

package/src/resources/extensions/gsd/status-guards.ts

@@ -1,13 +1,14 @@
 /**
  * Status predicates for GSD state-machine guards.
  *
- * The DB stores status as free-form strings. Two values indicate
- * "closed": "complete" (canonical) and "done" (legacy / alias).
+ * The DB stores status as free-form strings. Three values indicate
+ * "closed": "complete" (canonical), "done" (legacy / alias), and
+ * "skipped" (user-directed skip via rethink or backtrack).
  * Every inline `status === "complete" || status === "done"` should
  * use isClosedStatus() instead.
  */
 
 /** Returns true when a milestone, slice, or task status indicates closure. */
 export function isClosedStatus(status: string): boolean {
-  return status === "complete" || status === "done";
+  return status === "complete" || status === "done" || status === "skipped";
 }

package/src/resources/extensions/gsd/tests/context-masker.test.ts

@@ -0,0 +1,122 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { createObservationMask } from "../context-masker.js";
+
+// These helpers produce messages in the pi-ai LLM payload format
+// (post-convertToLlm, pre-provider), which is what before_provider_request sees.
+
+function userMsg(content: string) {
+  return { role: "user", content: [{ type: "text", text: content }] };
+}
+
+function assistantMsg(content: string) {
+  return { role: "assistant", content: [{ type: "text", text: content }] };
+}
+
+/** toolResult in pi-ai format: role "toolResult", content as TextContent[] */
+function toolResult(text: string) {
+  return { role: "toolResult", content: [{ type: "text", text }], toolCallId: "toolu_test", toolName: "Read", isError: false };
+}
+
+/** bashExecution after convertToLlm: becomes a user message with "Ran `cmd`" prefix */
+function bashResult(text: string) {
+  return { role: "user", content: [{ type: "text", text: `Ran \`echo test\`\n\`\`\`\n${text}\n\`\`\`` }] };
+}
+
+const MASK_TEXT = "[result masked — within summarized history]";
+
+test("masks nothing when message count is within keepRecentTurns", () => {
+  const mask = createObservationMask(8);
+  const messages = [
+    userMsg("hello"),
+    assistantMsg("hi"),
+    toolResult("file contents"),
+  ];
+  const result = mask(messages as any);
+  assert.equal(result.length, 3);
+  assert.deepEqual((result[2].content as any)[0].text, "file contents");
+});
+
+test("masks tool results older than keepRecentTurns", () => {
+  const mask = createObservationMask(2);
+  const messages = [
+    userMsg("turn 1"),
+    toolResult("old tool output"),
+    assistantMsg("response 1"),
+    userMsg("turn 2"),
+    toolResult("newer tool output"),
+    assistantMsg("response 2"),
+    userMsg("turn 3"),
+    toolResult("newest tool output"),
+    assistantMsg("response 3"),
+  ];
+  const result = mask(messages as any);
+  // Old tool result (before boundary) should be masked
+  assert.equal((result[1].content as any)[0].text, MASK_TEXT);
+  // Recent tool results (within keep window) should be preserved
+  assert.equal((result[4].content as any)[0].text, "newer tool output");
+  assert.equal((result[7].content as any)[0].text, "newest tool output");
+});
+
+test("never masks assistant messages", () => {
+  const mask = createObservationMask(1);
+  const messages = [
+    userMsg("turn 1"),
+    assistantMsg("old reasoning"),
+    userMsg("turn 2"),
+    assistantMsg("new reasoning"),
+  ];
+  const result = mask(messages as any);
+  assert.equal((result[1].content as any)[0].text, "old reasoning");
+  assert.equal((result[3].content as any)[0].text, "new reasoning");
+});
+
+test("never masks user messages", () => {
+  const mask = createObservationMask(1);
+  const messages = [
+    userMsg("old user message"),
+    assistantMsg("response"),
+    userMsg("new user message"),
+    assistantMsg("response"),
+  ];
+  const result = mask(messages as any);
+  assert.equal((result[0].content as any)[0].text, "old user message");
+});
+
+test("masks bash result user messages", () => {
+  const mask = createObservationMask(1);
+  const messages = [
+    userMsg("turn 1"),
+    bashResult("huge log output"),
+    assistantMsg("response 1"),
+    userMsg("turn 2"),
+    assistantMsg("response 2"),
+  ];
+  const result = mask(messages as any);
+  assert.equal((result[1].content as any)[0].text, MASK_TEXT);
+});
+
+test("returns same array length", () => {
+  const mask = createObservationMask(1);
+  const messages = [
+    userMsg("a"), toolResult("b"), assistantMsg("c"),
+    userMsg("d"), toolResult("e"), assistantMsg("f"),
+  ];
+  const result = mask(messages as any);
+  assert.equal(result.length, messages.length);
+});
+
+test("masks toolResult by role, not by type field", () => {
+  const mask = createObservationMask(1);
+  const messages = [
+    userMsg("turn 1"),
+    // This is the actual pi-ai format: role "toolResult", no type field
+    { role: "toolResult", content: [{ type: "text", text: "old result" }], toolCallId: "t1", toolName: "Read", isError: false },
+    assistantMsg("response 1"),
+    userMsg("turn 2"),
+    assistantMsg("response 2"),
+  ];
+  const result = mask(messages as any);
+  assert.equal((result[1].content as any)[0].text, MASK_TEXT);
+});