opencode-swarm-plugin 0.45.7 → 0.47.0

package/bin/cass.characterization.test.ts

@@ -1,12 +1,11 @@
 #!/usr/bin/env bun
 /**
- * CASS Binary Characterization Tests
+ * CASS Inhouse Implementation Characterization Tests
  * 
- * These tests capture the CURRENT behavior of the CASS binary tools.
- * They document WHAT the binary DOES, not what it SHOULD do.
+ * These tests capture the CURRENT behavior of the inhouse CASS implementation.
+ * They document WHAT the implementation DOES, not what it SHOULD do.
  * 
- * Purpose: Enable safe refactoring during ADR-010 (CASS inhousing).
- * Our inhouse implementation must match these behaviors exactly.
+ * Purpose: Verify inhouse implementation matches expected behavior after migration from binary.
  * 
  * Pattern: Feathers Characterization Testing
  * 1. Write a test you KNOW will fail
@@ -17,406 +16,428 @@
  * DO NOT modify these tests to match desired behavior.
  * These are BASELINE tests - they verify behaviors ARE present.
  */
-import { describe, test, expect } from "bun:test";
-import { $ } from "bun";
-import {
-  cassStatsBaseline,
-  cassSearchBaseline,
-  cassHealthHumanBaseline,
-  cassStatsHumanBaseline,
-  cassViewBaseline,
-  cassErrorBaseline,
-  type CassStatsResponse,
-  type CassSearchResponse,
-} from "../evals/fixtures/cass-baseline.ts";
-
-describe("CASS Binary - cass stats", () => {
-  test("JSON output structure matches baseline", async () => {
-    // CHARACTERIZATION: This documents the actual JSON structure
-    const result = await $`cass stats --json`.quiet().json();
-
-    // Verify top-level structure
-    expect(result).toHaveProperty("by_agent");
-    expect(result).toHaveProperty("conversations");
-    expect(result).toHaveProperty("date_range");
-    expect(result).toHaveProperty("db_path");
-    expect(result).toHaveProperty("messages");
-    expect(result).toHaveProperty("top_workspaces");
-
-    // Verify by_agent structure
-    expect(Array.isArray(result.by_agent)).toBe(true);
-    if (result.by_agent.length > 0) {
-      const firstAgent = result.by_agent[0];
-      expect(firstAgent).toHaveProperty("agent");
-      expect(firstAgent).toHaveProperty("count");
-      expect(typeof firstAgent.agent).toBe("string");
-      expect(typeof firstAgent.count).toBe("number");
-    }
-
-    // Verify date_range structure
-    expect(result.date_range).toHaveProperty("newest");
-    expect(result.date_range).toHaveProperty("oldest");
-    expect(typeof result.date_range.newest).toBe("string");
-    expect(typeof result.date_range.oldest).toBe("string");
-
-    // Verify top_workspaces structure
-    expect(Array.isArray(result.top_workspaces)).toBe(true);
-    if (result.top_workspaces.length > 0) {
-      const firstWorkspace = result.top_workspaces[0];
-      expect(firstWorkspace).toHaveProperty("count");
-      expect(firstWorkspace).toHaveProperty("workspace");
-      expect(typeof firstWorkspace.count).toBe("number");
-      expect(typeof firstWorkspace.workspace).toBe("string");
-    }
-
-    // Verify numeric fields are numbers
-    expect(typeof result.conversations).toBe("number");
-    expect(typeof result.messages).toBe("number");
-  });
-
-  test("human-readable output format matches baseline", async () => {
-    // CHARACTERIZATION: This documents the actual human-readable format
-    const result = await $`cass stats`.quiet().text();
-
-    // Verify presence of key sections (order matters)
-    expect(result).toContain("CASS Index Statistics");
-    expect(result).toContain("Database:");
-    expect(result).toContain("Totals:");
-    expect(result).toContain("Conversations:");
-    expect(result).toContain("Messages:");
-    expect(result).toContain("By Agent:");
-    expect(result).toContain("Top Workspaces:");
-    expect(result).toContain("Date Range:");
-
-    // Verify format patterns
-    expect(result).toMatch(/Conversations: \d+/);
-    expect(result).toMatch(/Messages: \d+/);
-    expect(result).toMatch(/\w+: \d+/); // Agent counts
-  });
+import { describe, test, expect, beforeAll } from "bun:test";
+import { cassTools } from "../src/cass-tools.ts";
+
+// ============================================================================
+// Test Helpers
+// ============================================================================
+
+/**
+ * Parse JSON from tool output (tools return strings)
+ */
+function parseToolJSON(output: string): any {
+	try {
+		return JSON.parse(output);
+	} catch {
+		// If not JSON, return as-is
+		return output;
+	}
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe("CASS Inhouse - cass_stats", () => {
+	test("returns JSON with SessionStats structure", async () => {
+		// CHARACTERIZATION: cass_stats returns JSON string with SessionStats
+		const output = await cassTools.cass_stats.execute({});
+		const result = parseToolJSON(output);
+
+		// Verify SessionStats structure
+		expect(result).toHaveProperty("total_sessions");
+		expect(result).toHaveProperty("total_chunks");
+		expect(result).toHaveProperty("by_agent");
+
+		// Verify types
+		expect(typeof result.total_sessions).toBe("number");
+		expect(typeof result.total_chunks).toBe("number");
+		expect(typeof result.by_agent).toBe("object");
+
+		// Verify by_agent structure
+		if (Object.keys(result.by_agent).length > 0) {
+			const firstAgent = Object.entries(result.by_agent)[0][1] as any;
+			expect(firstAgent).toHaveProperty("sessions");
+			expect(firstAgent).toHaveProperty("chunks");
+			expect(typeof firstAgent.sessions).toBe("number");
+			expect(typeof firstAgent.chunks).toBe("number");
+		}
+	});
+
+	test("numeric fields are non-negative", async () => {
+		// CHARACTERIZATION: Counts should be >= 0
+		const output = await cassTools.cass_stats.execute({});
+		const result = parseToolJSON(output);
+
+		expect(result.total_sessions).toBeGreaterThanOrEqual(0);
+		expect(result.total_chunks).toBeGreaterThanOrEqual(0);
+	});
+});
+
+describe("CASS Inhouse - cass_health", () => {
+	test("returns JSON with IndexHealth structure", async () => {
+		// CHARACTERIZATION: cass_health returns JSON with IndexHealth
+		const output = await cassTools.cass_health.execute({});
+		const result = parseToolJSON(output);
+
+		// Verify IndexHealth structure
+		expect(result).toHaveProperty("healthy");
+		expect(result).toHaveProperty("message");
+		expect(result).toHaveProperty("total_indexed");
+		expect(result).toHaveProperty("stale_count");
+		expect(result).toHaveProperty("fresh_count");
+
+		// Verify types
+		expect(typeof result.healthy).toBe("boolean");
+		expect(typeof result.message).toBe("string");
+		expect(typeof result.total_indexed).toBe("number");
+		expect(typeof result.stale_count).toBe("number");
+		expect(typeof result.fresh_count).toBe("number");
+	});
+
+	test("healthy=true when total_indexed > 0 and stale_count === 0", async () => {
+		// CHARACTERIZATION: Health is determined by indexed count and staleness
+		const output = await cassTools.cass_health.execute({});
+		const result = parseToolJSON(output);
+
+		if (result.total_indexed > 0 && result.stale_count === 0) {
+			expect(result.healthy).toBe(true);
+			expect(result.message).toContain("ready");
+		} else {
+			expect(result.healthy).toBe(false);
+			expect(result.message).toContain("needs");
+		}
+	});
+
+	test("includes optional timestamp fields when data exists", async () => {
+		// CHARACTERIZATION: oldest_indexed and newest_indexed are optional
+		const output = await cassTools.cass_health.execute({});
+		const result = parseToolJSON(output);
+
+		if (result.total_indexed > 0) {
+			// When there are indexed files, timestamps should be present
+			if (result.oldest_indexed !== undefined) {
+				expect(typeof result.oldest_indexed).toBe("string");
+			}
+			if (result.newest_indexed !== undefined) {
+				expect(typeof result.newest_indexed).toBe("string");
+			}
+		}
+	});
+});
+
+describe("CASS Inhouse - cass_search", () => {
+	test("returns formatted string with results", async () => {
+		// CHARACTERIZATION: cass_search returns formatted string, not JSON
+		const output = await cassTools.cass_search.execute({
+			query: "test",
+			limit: 2,
+		});
+
+		// Should be a string (not JSON object)
+		expect(typeof output).toBe("string");
+
+		// If results exist, should contain numbered results
+		if (!output.includes("No results found")) {
+			expect(output).toMatch(/1\./); // Numbered result
+		}
+	});
+
+	test("minimal fields format returns compact output", async () => {
+		// CHARACTERIZATION: fields='minimal' returns path:line (agent) format
+		const output = await cassTools.cass_search.execute({
+			query: "test",
+			limit: 2,
+			fields: "minimal",
+		});
+
+		if (!output.includes("No results found")) {
+			// Minimal format: "1. /path/to/file.jsonl:42 (agent)"
+			expect(output).toMatch(/\d+\.\s+\S+:\d+\s+\(\w+\)/);
+		}
+	});
+
+	test("default format includes score and preview", async () => {
+		// CHARACTERIZATION: Default format includes score and content preview
+		const output = await cassTools.cass_search.execute({
+			query: "test",
+			limit: 1,
+		});
+
+		if (!output.includes("No results found")) {
+			expect(output).toContain("Score:");
+		}
+	});
+
+	test("empty results return helpful message", async () => {
+		// CHARACTERIZATION: No results message suggests actions
+		const output = await cassTools.cass_search.execute({
+			query: "xyzzy-nonexistent-term-99999-abcdef",
+			limit: 5,
+		});
+
+		expect(output).toContain("No results found");
+		expect(output).toContain("Try:");
+	});
+
+	test("limit parameter controls max results", async () => {
+		// CHARACTERIZATION: Limit controls result count
+		const output = await cassTools.cass_search.execute({
+			query: "test",
+			limit: 1,
+		});
+
+		if (!output.includes("No results found")) {
+			const lines = output.split("\n").filter((l) => l.match(/^\d+\./));
+			expect(lines.length).toBeLessThanOrEqual(1);
+		}
+	});
+
+	test("agent filter parameter accepted", async () => {
+		// CHARACTERIZATION: agent parameter filters by agent type
+		const output = await cassTools.cass_search.execute({
+			query: "test",
+			agent: "claude",
+			limit: 2,
+		});
+
+		// Should not throw, result format same as unfiltered
+		expect(typeof output).toBe("string");
+	});
 });
 
-describe("CASS Binary - cass search", () => {
-  test("JSON output structure matches baseline", async () => {
-    // CHARACTERIZATION: This documents the actual search response structure
-    const result = await $`cass search "test" --limit 2 --json`.quiet().json();
-
-    // Verify top-level structure
-    expect(result).toHaveProperty("count");
-    expect(result).toHaveProperty("cursor");
-    expect(result).toHaveProperty("hits");
-    expect(result).toHaveProperty("hits_clamped");
-    expect(result).toHaveProperty("limit");
-    expect(result).toHaveProperty("max_tokens");
-    expect(result).toHaveProperty("offset");
-    expect(result).toHaveProperty("query");
-    expect(result).toHaveProperty("request_id");
-    expect(result).toHaveProperty("total_matches");
-
-    // Verify types
-    expect(typeof result.count).toBe("number");
-    expect(typeof result.hits_clamped).toBe("boolean");
-    expect(typeof result.limit).toBe("number");
-    expect(typeof result.offset).toBe("number");
-    expect(typeof result.query).toBe("string");
-    expect(typeof result.total_matches).toBe("number");
-    expect(Array.isArray(result.hits)).toBe(true);
-
-    // Verify hit structure (if any hits returned)
-    if (result.hits.length > 0) {
-      const firstHit = result.hits[0];
-      expect(firstHit).toHaveProperty("agent");
-      expect(firstHit).toHaveProperty("content");
-      expect(firstHit).toHaveProperty("created_at");
-      expect(firstHit).toHaveProperty("line_number");
-      expect(firstHit).toHaveProperty("match_type");
-      expect(firstHit).toHaveProperty("score");
-      expect(firstHit).toHaveProperty("snippet");
-      expect(firstHit).toHaveProperty("source_path");
-      expect(firstHit).toHaveProperty("title");
-      expect(firstHit).toHaveProperty("workspace");
-
-      expect(typeof firstHit.agent).toBe("string");
-      expect(typeof firstHit.content).toBe("string");
-      expect(typeof firstHit.created_at).toBe("number");
-      expect(typeof firstHit.line_number).toBe("number");
-      expect(typeof firstHit.match_type).toBe("string");
-      expect(typeof firstHit.score).toBe("number");
-      expect(typeof firstHit.snippet).toBe("string");
-      expect(typeof firstHit.source_path).toBe("string");
-      expect(typeof firstHit.title).toBe("string");
-      expect(typeof firstHit.workspace).toBe("string");
-    }
-  });
-
-  test("query parameter is preserved in response", async () => {
-    // CHARACTERIZATION: Query echoed back in response
-    const testQuery = "characterization-test-query-12345";
-    const result = await $`cass search "${testQuery}" --json`.quiet().json();
-
-    expect(result.query).toBe(testQuery);
-  });
-
-  test("limit parameter is respected", async () => {
-    // CHARACTERIZATION: Limit controls max hits returned
-    const result = await $`cass search "test" --limit 3 --json`.quiet().json();
-
-    expect(result.limit).toBe(3);
-    if (result.hits.length > 0) {
-      expect(result.hits.length).toBeLessThanOrEqual(3);
-    }
-  });
-
-  test("empty results include suggestions field", async () => {
-    // CHARACTERIZATION: Empty results return suggestions
-    const result =
-      await $`cass search "xyzzy-nonexistent-term-99999" --json`.quiet().json();
-
-    if (result.total_matches === 0) {
-      // Empty results may include suggestions (optional feature)
-      // Just verify structure if present
-      if (result.suggestions) {
-        expect(Array.isArray(result.suggestions)).toBe(true);
-      }
-    }
-  });
+describe("CASS Inhouse - cass_view", () => {
+	test("returns viewSessionLine formatted output", async () => {
+		// CHARACTERIZATION: cass_view uses viewSessionLine format
+		// We need a real session file to test this
+		// For now, just test error handling
+
+		const output = await cassTools.cass_view.execute({
+			path: "/nonexistent/session.jsonl",
+		});
+
+		// Error case returns JSON
+		const result = parseToolJSON(output);
+		if (result.error) {
+			expect(result).toHaveProperty("error");
+			expect(typeof result.error).toBe("string");
+		}
+	});
+
+	test("line parameter jumps to specific line", async () => {
+		// CHARACTERIZATION: line parameter controls starting line
+		const output = await cassTools.cass_view.execute({
+			path: "/nonexistent/session.jsonl",
+			line: 42,
+		});
+
+		// For now just verify parameter is accepted
+		expect(typeof output).toBe("string");
+	});
 });
 
-describe("CASS Binary - cass health", () => {
-  test("health check returns status indicator", async () => {
-    // CHARACTERIZATION: Health check outputs status with timing
-    const result = await $`cass health`.quiet().text();
-
-    // Should contain status indicator (✓ or ✗)
-    const hasHealthyIndicator = result.includes("✓ Healthy");
-    const hasUnhealthyIndicator = result.includes("✗");
-
-    expect(hasHealthyIndicator || hasUnhealthyIndicator).toBe(true);
-
-    // Should include timing information
-    if (hasHealthyIndicator) {
-      expect(result).toMatch(/\(\d+ms\)/);
-    }
-  });
-
-  test("health check may include staleness note", async () => {
-    // CHARACTERIZATION: May warn about stale index
-    const result = await $`cass health`.quiet().text();
-
-    // If index is stale, should mention it
-    // This is conditional - test just verifies format if present
-    if (result.includes("stale")) {
-      expect(result).toContain("Note:");
-      expect(result).toMatch(/older than \d+s/);
-    }
-  });
-
-  test("health check exits with code 0 when healthy", async () => {
-    // CHARACTERIZATION: Exit code 0 = healthy
-    const proc = Bun.spawn(["cass", "health"], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-
-    const exitCode = await proc.exited;
-    // Exit code 0 means healthy (even if stale)
-    // Exit code 3 means missing index
-    expect([0, 3]).toContain(exitCode);
-  });
+describe("CASS Inhouse - cass_expand", () => {
+	test("returns expanded context around line", async () => {
+		// CHARACTERIZATION: cass_expand uses viewSessionLine with context
+		const output = await cassTools.cass_expand.execute({
+			path: "/nonexistent/session.jsonl",
+			line: 10,
+			context: 5,
+		});
+
+		// Error case returns JSON
+		const result = parseToolJSON(output);
+		if (result.error) {
+			expect(result).toHaveProperty("error");
+		}
+	});
+
+	test("context parameter controls window size", async () => {
+		// CHARACTERIZATION: context defaults to 5, can be overridden
+		const output = await cassTools.cass_expand.execute({
+			path: "/nonexistent/session.jsonl",
+			line: 10,
+			context: 10,
+		});
+
+		// Parameter accepted
+		expect(typeof output).toBe("string");
+	});
+});
+
+describe("CASS Inhouse - cass_index", () => {
+	// NOTE: cass_index tests are slow (5s+ timeout) - skip in unit tests
+	// These are integration tests that require indexing real files
+	test.skip("returns summary string with counts", async () => {
+		// CHARACTERIZATION: cass_index returns summary string
+		const output = await cassTools.cass_index.execute({});
+
+		expect(typeof output).toBe("string");
+		expect(output).toMatch(/Indexed \d+ sessions/);
+		expect(output).toMatch(/\d+ chunks/);
+		expect(output).toMatch(/\d+ms/);
+	});
+
+	test.skip("full rebuild flag accepted", async () => {
+		// CHARACTERIZATION: full parameter triggers full rebuild
+		const output = await cassTools.cass_index.execute({ full: true });
+
+		expect(typeof output).toBe("string");
+	});
+
+	test.skip("incremental indexing is default", async () => {
+		// CHARACTERIZATION: No full flag = incremental
+		const output = await cassTools.cass_index.execute({});
+
+		expect(typeof output).toBe("string");
+	});
 });
 
-describe("CASS Binary - cass view", () => {
-  test("view output includes file path header", async () => {
-    // CHARACTERIZATION: View starts with file path
-    // We can only test this if session files exist
-    const sessionFiles = await $`ls ~/.config/swarm-tools/sessions/*.jsonl`
-      .quiet()
-      .text()
-      .catch(() => "");
-
-    if (sessionFiles.trim()) {
-      const firstFile = sessionFiles.split("\n")[0].trim();
-      const result = await $`cass view ${firstFile} -n 1`.quiet().text();
-
-      expect(result).toContain(`File: ${firstFile}`);
-      expect(result).toContain("Line: 1");
-      expect(result).toContain("context:");
-      expect(result).toContain("----------------------------------------");
-    }
-  });
-
-  test("view output shows line numbers with content", async () => {
-    // CHARACTERIZATION: Lines prefixed with numbers
-    const sessionFiles = await $`ls ~/.config/swarm-tools/sessions/*.jsonl`
-      .quiet()
-      .text()
-      .catch(() => "");
-
-    if (sessionFiles.trim()) {
-      const firstFile = sessionFiles.split("\n")[0].trim();
-      const result = await $`cass view ${firstFile} -n 1`.quiet().text();
-
-      // Target line marked with >
-      expect(result).toMatch(/>\s+\d+\s+\|/);
-    }
-  });
-
-  test("view with non-existent file returns error", async () => {
-    // CHARACTERIZATION: File not found error structure
-    const result = await $`cass view /nonexistent/path.jsonl -n 1 --json`
-      .quiet()
-      .json()
-      .catch((e) => JSON.parse(e.stderr.toString()));
-
-    expect(result).toHaveProperty("error");
-    expect(result.error).toHaveProperty("code");
-    expect(result.error).toHaveProperty("kind");
-    expect(result.error).toHaveProperty("message");
-    expect(result.error).toHaveProperty("retryable");
-
-    expect(result.error.code).toBe(3);
-    expect(result.error.kind).toBe("file-not-found");
-    expect(result.error.retryable).toBe(false);
-  });
+describe("CASS Inhouse - Error Handling", () => {
+	test("errors return JSON with error field", async () => {
+		// CHARACTERIZATION: Tool errors return {error: string}
+		const output = await cassTools.cass_view.execute({
+			path: "/definitely/does/not/exist.jsonl",
+		});
+
+		const result = parseToolJSON(output);
+		expect(result).toHaveProperty("error");
+		expect(typeof result.error).toBe("string");
+	});
+
+	test("search errors fall back gracefully", async () => {
+		// CHARACTERIZATION: Search with bad agent filter doesn't crash
+		const output = await cassTools.cass_search.execute({
+			query: "test",
+			agent: "nonexistent-agent-type",
+		});
+
+		// Should return results or no results message, not error
+		expect(typeof output).toBe("string");
+	});
 });
 
-describe("CASS Binary - Error handling", () => {
-  test("invalid arguments return usage error with hints", async () => {
-    // CHARACTERIZATION: Helpful error messages with examples
-    const proc = Bun.spawn(["cass", "stats", "--invalid-flag"], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-
-    await proc.exited;
-    const stderr = await new Response(proc.stderr).text();
-
-    // Should contain helpful error information
-    expect(stderr).toBeTruthy();
-    // Typically shows usage or suggests --help
-    expect(stderr.toLowerCase()).toMatch(/usage|help|invalid|unexpected/);
-  });
-
-  test("error responses include exit codes", async () => {
-    // CHARACTERIZATION: Exit codes documented in baseline
-    // Code 2 = usage error
-    // Code 3 = missing file/db
-    // Code 0 = success
-
-    const procInvalidArg = Bun.spawn(["cass", "stats", "--invalid-flag"], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const exitCodeInvalid = await procInvalidArg.exited;
-    expect(exitCodeInvalid).toBe(2); // Usage error
-
-    const procSuccess = Bun.spawn(["cass", "stats", "--json"], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const exitCodeSuccess = await procSuccess.exited;
-    expect([0, 3]).toContain(exitCodeSuccess); // Success or missing index
-  });
+describe("CASS Inhouse - Agent Discovery", () => {
+	test("indexes multiple agent directories", async () => {
+		// CHARACTERIZATION: Indexes from ~/.opencode, ~/.config/swarm-tools, etc.
+		const output = await cassTools.cass_stats.execute({});
+		const result = parseToolJSON(output);
+
+		// by_agent should contain different agent types if they exist
+		expect(typeof result.by_agent).toBe("object");
+	});
+
+	test("detects agent type from path", async () => {
+		// CHARACTERIZATION: Path like ~/.local/share/Claude → agent='claude'
+		const output = await cassTools.cass_stats.execute({});
+		const result = parseToolJSON(output);
+
+		// Agent types are detected from paths
+		// Possible values: claude, cursor, opencode, opencode-swarm, codex, aider
+		if (Object.keys(result.by_agent).length > 0) {
+			const agentTypes = Object.keys(result.by_agent);
+			for (const agentType of agentTypes) {
+				expect(typeof agentType).toBe("string");
+			}
+		}
+	});
 });
 
-describe("CASS Binary - Robot mode documentation", () => {
-  test("--robot-help provides machine-readable documentation", async () => {
-    // CHARACTERIZATION: Robot help is designed for AI agents
-    const result = await $`cass --robot-help`.quiet().text();
-
-    expect(result).toContain("cass --robot-help (contract v1)");
-    expect(result).toContain("QUICKSTART (for AI agents):");
-    expect(result).toContain("TIME FILTERS:");
-    expect(result).toContain("WORKFLOW:");
-    expect(result).toContain("OUTPUT:");
-    expect(result).toContain("Exit codes:");
-  });
-
-  test("robot-docs subcommand exists", async () => {
-    // CHARACTERIZATION: robot-docs provides detailed docs for AI
-    const result = await $`cass robot-docs commands`.quiet().text();
-
-    // Should return command documentation (exact format may vary)
-    expect(result.length).toBeGreaterThan(0);
-  });
+describe("CASS Inhouse - Staleness Detection", () => {
+	test("health check reports stale files", async () => {
+		// CHARACTERIZATION: stale_count indicates files needing reindex
+		const output = await cassTools.cass_health.execute({});
+		const result = parseToolJSON(output);
+
+		expect(result).toHaveProperty("stale_count");
+		expect(typeof result.stale_count).toBe("number");
+		expect(result.stale_count).toBeGreaterThanOrEqual(0);
+	});
+
+	test("fresh_count indicates up-to-date files", async () => {
+		// CHARACTERIZATION: fresh_count shows files that don't need reindex
+		const output = await cassTools.cass_health.execute({});
+		const result = parseToolJSON(output);
+
+		expect(result).toHaveProperty("fresh_count");
+		expect(typeof result.fresh_count).toBe("number");
+		expect(result.fresh_count).toBeGreaterThanOrEqual(0);
+	});
+
+	test("total_indexed equals fresh_count + stale_count", async () => {
+		// CHARACTERIZATION: Counts should add up
+		const output = await cassTools.cass_health.execute({});
+		const result = parseToolJSON(output);
+
+		expect(result.total_indexed).toBe(
+			result.fresh_count + result.stale_count,
+		);
+	});
 });
 
-describe("CASS Binary - Flag behavior", () => {
-  test("--json flag produces machine-readable output", async () => {
-    // CHARACTERIZATION: --json enables JSON mode
-    const result = await $`cass stats --json`.quiet().text();
-
-    // Should be valid JSON
-    expect(() => JSON.parse(result)).not.toThrow();
-  });
-
-  test("--json and --robot are equivalent", async () => {
-    // CHARACTERIZATION: Both flags enable robot mode
-    const jsonResult = await $`cass search "test" --limit 1 --json`
-      .quiet()
-      .json();
-    const robotResult = await $`cass search "test" --limit 1 --robot`
-      .quiet()
-      .json();
-
-    // Both should return same structure
-    expect(jsonResult).toHaveProperty("hits");
-    expect(robotResult).toHaveProperty("hits");
-  });
-
-  test("limit flag controls result count", async () => {
-    // CHARACTERIZATION: --limit parameter
-    const result = await $`cass search "test" --limit 1 --json`.quiet().json();
-
-    expect(result.limit).toBe(1);
-    expect(result.hits.length).toBeLessThanOrEqual(1);
-  });
+describe("CASS Inhouse - Ollama Fallback", () => {
+	test("search works even if Ollama unavailable", async () => {
+		// CHARACTERIZATION: Graceful degradation to FTS5
+		// Hard to test without mocking, but search shouldn't crash
+		const output = await cassTools.cass_search.execute({
+			query: "test",
+			limit: 1,
+		});
+
+		// Should return either results or "No results found"
+		expect(typeof output).toBe("string");
+		expect(output.length).toBeGreaterThan(0);
+	});
 });
 
 /**
  * CHARACTERIZATION NOTES:
  * 
- * These tests document the following CASS binary behaviors:
+ * These tests document the following inhouse CASS behaviors:
  * 
- * 1. JSON Output Structure:
- *    - cass stats: by_agent[], conversations, date_range, messages, top_workspaces[]
- *    - cass search: count, cursor, hits[], limit, offset, query, total_matches
- *    - Hit objects: agent, content, created_at, line_number, score, source_path, etc.
+ * 1. Output Format Changes from Binary:
+ *    - cass_stats: Returns JSON string with SessionStats structure
+ *    - cass_health: Returns JSON with healthy boolean + IndexHealth fields
+ *    - cass_search: Returns formatted string (not JSON), with optional minimal mode
+ *    - cass_view/cass_expand: Returns viewSessionLine formatted output
+ *    - cass_index: Returns summary string with counts
  * 
- * 2. Human-Readable Output:
- *    - Formatted tables with headers
- *    - Numeric statistics
- *    - Date ranges
+ * 2. Data Structures:
+ *    - SessionStats: { total_sessions, total_chunks, by_agent }
+ *    - IndexHealth: { healthy, message, total_indexed, stale_count, fresh_count, oldest_indexed?, newest_indexed? }
+ *    - SearchResult: Formatted string with numbered results, scores, previews
  * 
- * 3. Error Handling:
- *    - Exit code 0 = success
- *    - Exit code 2 = usage error
- *    - Exit code 3 = missing file/db
- *    - Error objects with code, kind, message, retryable fields
+ * 3. Agent Discovery:
+ *    - Indexes from multiple directories (~/.opencode, ~/.config/swarm-tools, etc.)
+ *    - Detects agent type from path (claude, cursor, opencode, aider, etc.)
+ *    - by_agent groups stats by detected agent type
  * 
- * 4. Robot Mode:
- *    - --json and --robot flags are equivalent
- *    - --robot-help provides AI-friendly documentation
- *    - robot-docs subcommand for detailed docs
+ * 4. Staleness Detection:
+ *    - stale_count: Files modified since last index
+ *    - fresh_count: Files up-to-date
+ *    - total_indexed = fresh_count + stale_count
+ *    - healthy = total_indexed > 0 && stale_count === 0
  * 
- * 5. Search Behavior:
- *    - Query parameter echoed in response
- *    - Limit parameter controls max hits
- *    - Empty results may include suggestions
+ * 5. Ollama Fallback:
+ *    - Search falls back to FTS5 if Ollama unavailable
+ *    - Graceful degradation with warning, no crash
  * 
- * 6. View Behavior:
- *    - File path header
- *    - Line numbers with > indicator for target
- *    - Context window (default 5 lines)
- *    - Horizontal separators
+ * 6. Error Handling:
+ *    - Tools return JSON with {error: string} on failure
+ *    - Search with invalid agent filter returns empty results, not error
+ *    - View/expand with missing file returns error JSON
  * 
- * 7. Health Check:
- *    - Status indicator (✓ or ✗)
- *    - Timing in milliseconds
- *    - Optional staleness warning
+ * 7. Removed from Binary Version:
+ *    - No --json/--robot flags (always returns structured output)
+ *    - No robot-docs subcommand
+ *    - No --robot-help flag
+ *    - No human-readable table format (JSON/formatted strings only)
+ *    - No exit codes (tools return strings)
  * 
- * When implementing the inhouse version:
+ * When modifying the inhouse implementation:
  * - Match these structures exactly
  * - Preserve field names and types
  * - Maintain error response format
- * - Keep exit codes consistent
+ * - Keep agent discovery patterns consistent
  */