zob-harness 0.6.0 → 0.7.1

package/.pi/capabilities/zob-public-runtime-capabilities.json

@@ -1030,7 +1030,7 @@
         "README.md",
         "scripts/README.md"
       ],
-      "noShipNotes": "Bounded repo-local context discovery only; prefer ColGREP when installed/ready, otherwise use grep/find/read fallback. Never auto-install ColGREP, run installer/network/package-manager commands, read forbidden/secret/session/vendor/build paths, persist raw secret/session bodies, inject stale/global/unbounded prompt context, or treat broad search hits as exact proof without grep/read/file-ref verification. Oracle/no-ship review must check freshness, citation coverage, and forbidden-source violations."
+      "noShipNotes": "Bounded repo-local context discovery only; for exploratory/natural-language repo discovery start with zob_context_search/ColGREP when installed/ready; if the native tool is unavailable but bash is available, use compact npm run --silent zob:context:query before rg/grep; otherwise use grep/find/read fallback. Never auto-install ColGREP, run installer/network/package-manager commands, broad-grep .pi without pruning .pi/sessions and .pi/agent-sessions, read forbidden/secret/session/vendor/build paths, persist raw secret/session bodies, inject stale/global/unbounded prompt context, or treat broad search hits as exact proof without grep/read/file-ref verification. Oracle/no-ship review must check freshness, citation coverage, and forbidden-source violations."
     },
     {
       "name": "zob_context_readiness",

package/.pi/context-discovery.json

@@ -25,8 +25,8 @@
     "build"
   ],
   "limits": {
-    "maxResults": 20,
-    "maxContextLines": 2,
+    "maxResults": 6,
+    "maxContextLines": 1,
     "maxFileBytes": 1048576
   },
   "promptInjection": {

package/.pi/extensions/zob-harness/src/core/constants.ts

@@ -56,7 +56,7 @@ export const ZOB_ZCOMMIT_TOOLS = ["zob_zcommit_run"] as const;
 export const ZOB_DELEGATION_READ_TOOLS = ["zob_delegation_catalog", "get_delegation_run", "await_delegation_run"] as const;
 export const ZOB_MISSION_CONTROL_READ_TOOLS = ["zob_coms_readiness", "zob_mission_control_snapshot"] as const;
 export const ZOB_MISSION_CONTROL_PROPOSAL_TOOLS = ["zob_mission_control_propose_command"] as const;
-export const ZOB_CONTEXT_READ_TOOLS = ["zob_context_readiness", "zob_context_validate_scope"] as const;
+export const ZOB_CONTEXT_READ_TOOLS = ["zob_context_search", "zob_context_readiness", "zob_context_validate_scope"] as const;
 export const ZOB_CONTEXT_PROPOSAL_TOOLS = ["zob_context_writeback_proposal"] as const;
 export const ZOB_COMPUTE_READ_TOOLS = ["zob_compute_preview", "zob_compute_resolve_profile", "zob_compute_plan_workflow", "zob_compute_validate_profile"] as const;
 export const ZOB_COMPUTE_REPORT_TOOLS = ["zob_compute_write_profile_reports"] as const;

package/.pi/extensions/zob-harness/src/domains/context/context-discovery.ts

@@ -1,6 +1,6 @@
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { basename, extname, isAbsolute, join, normalize, sep } from "node:path";
+import { basename, extname, isAbsolute, join, normalize, relative, sep } from "node:path";
 
 export type ContextSearchMode = "auto" | "semantic" | "hybrid" | "regex" | "files";
 
@@ -48,7 +48,7 @@ const DEFAULT_CONFIG: ContextDiscoveryConfig = {
   fallbackProvider: "grep",
   includePaths: [".pi/extensions", ".pi/skills", ".pi/capabilities", "scripts", "docs", "README.md", "AGENTS.md"],
   excludePaths: [".env", "**/.env", ".env.*", "**/*secret*", "**/*key*", "*.pem", ".pi/sessions", ".pi/agent-sessions", "node_modules", "dist", "build"],
-  limits: { maxResults: 20, maxContextLines: 2, maxFileBytes: 1024 * 1024 },
+  limits: { maxResults: 6, maxContextLines: 1, maxFileBytes: 1024 * 1024 },
   promptInjection: { enabled: true, includeInstallHint: true },
   loadedFrom: "defaults",
 };
@@ -78,6 +78,14 @@ export function normalizeRepoPath(raw: unknown): string | undefined {
   return normalized.split(sep).join("/");
 }
 
+function normalizeBackendPath(repoRoot: string, raw: unknown): string | undefined {
+  if (typeof raw !== "string" || raw.trim().length === 0 || raw.includes("\0")) return undefined;
+  if (!isAbsolute(raw)) return normalizeRepoPath(raw);
+  const relPath = relative(repoRoot, raw);
+  if (!relPath || relPath === ".." || relPath.startsWith(`..${sep}`) || isAbsolute(relPath)) return undefined;
+  return normalizeRepoPath(relPath);
+}
+
 function pathIsExcluded(relPath: string, excludePaths: string[]): boolean {
   const normalized = normalizeRepoPath(relPath);
   if (!normalized) return true;
@@ -136,10 +144,10 @@ export function buildActiveSearchBackendPromptSnippet(repoRoot: string): string
   const detection = detectColgrep(repoRoot);
   const scope = `${config.loadedFrom}; roots=${config.includePaths.slice(0, 6).join(",")}; excludes=${config.excludePaths.length}`;
   if (detection.ready) {
-    return `\n\nZOB ACTIVE SEARCH BACKEND\n- active search backend: colgrep\n- prompt injection: enabled by ${scope}; bounded per turn from current repo config, not a global/stale context pack.\n- Prefer zob_context_search for codebase discovery and broad/semantic search; use grep/read for exact proof and final citations.\n- Search output must stay bounded and avoid forbidden paths/secrets.`;
+    return `\n\nZOB ACTIVE SEARCH BACKEND\n- active search backend: colgrep\n- prompt injection: enabled by ${scope}; bounded per turn from current repo config, not a global/stale context pack.\n- For exploratory, natural-language, or "where is this mechanism?" repo discovery, start with zob_context_search/ColGREP before grep/find.\n- If zob_context_search is not listed in your available tools but bash is available, run npm run --silent zob:context:query -- --query "<natural language query>" --max-results 6 --max-context-lines 1 before rg/grep; the wrapper returns compact refs by default.\n- Do not conclude the native tool is unavailable and immediately use broad rg/grep; use the wrapper above as the ColGREP path.\n- Run one exploratory context search, then read the returned refs; retry only if results=0 or clearly irrelevant.\n- Use grep/read after semantic discovery for exact proof, known identifiers, final citations, and line refs.\n- Never run broad grep/find over .pi unless .pi/sessions and .pi/agent-sessions are explicitly excluded/pruned.\n- Search output must stay bounded and avoid forbidden paths/secrets.`;
   }
   const installHint = config.promptInjection.includeInstallHint ? `\n- Optional ColGREP setup hint: ${detection.guidance}` : "";
-  return `\n\nZOB ACTIVE SEARCH BACKEND\n- active search backend: grep fallback\n- prompt injection: enabled by ${scope}; bounded per turn from current repo config, not a global/stale context pack.\n- Prefer zob_context_search, grep, find, and read for bounded repo-local discovery and exact proof.${installHint}\n- Missing ColGREP is not a blocker; do not auto-install it.`;
+  return `\n\nZOB ACTIVE SEARCH BACKEND\n- active search backend: grep fallback\n- prompt injection: enabled by ${scope}; bounded per turn from current repo config, not a global/stale context pack.\n- Prefer zob_context_search when listed; if not listed and bash is available, npm run --silent zob:context:query -- --query "<query>" still gives the same bounded compact fallback path.${installHint}\n- Missing ColGREP is not a blocker; do not auto-install it.\n- Never run broad grep/find over .pi unless .pi/sessions and .pi/agent-sessions are explicitly excluded/pruned.`;
 }
 
 function safeSearchRoots(repoRoot: string, config: ContextDiscoveryConfig, requestedPaths?: string[]): { roots: string[]; rejected: string[] } {
@@ -180,12 +188,13 @@ function collectFiles(repoRoot: string, relPath: string, config: ContextDiscover
 }
 
 function normalizeLineResult(repoRoot: string, item: Record<string, unknown>, config: ContextDiscoveryConfig): NormalizedContextResult | undefined {
-  const rawPath = item.path ?? item.file ?? item.filename ?? item.source_path;
-  const path = normalizeRepoPath(rawPath);
+  const unit = typeof item.unit === "object" && item.unit !== null ? item.unit as Record<string, unknown> : undefined;
+  const rawPath = item.path ?? item.file ?? item.filename ?? item.source_path ?? unit?.path ?? unit?.file ?? unit?.filename ?? unit?.source_path;
+  const path = normalizeBackendPath(repoRoot, rawPath);
   if (!path || pathIsExcluded(path, config.excludePaths) || !existsSync(join(repoRoot, path))) return undefined;
-  const lineValue = item.line ?? item.lineNumber ?? item.line_number ?? item.start_line;
+  const lineValue = item.line ?? item.lineNumber ?? item.line_number ?? item.start_line ?? unit?.line ?? unit?.lineNumber ?? unit?.line_number ?? unit?.start_line;
   const line = typeof lineValue === "number" ? Math.max(1, Math.floor(lineValue)) : undefined;
-  const rawPreview = item.preview ?? item.text ?? item.lineText ?? item.content ?? item.match ?? "";
+  const rawPreview = item.preview ?? item.text ?? item.lineText ?? item.content ?? item.match ?? unit?.preview ?? unit?.text ?? unit?.lineText ?? unit?.content ?? unit?.code ?? unit?.docstring ?? unit?.signature ?? unit?.qualified_name ?? unit?.name ?? "";
   const preview = String(rawPreview).replace(/\s+/gu, " ").trim().slice(0, 240);
   const score = typeof item.score === "number" ? item.score : undefined;
   return { path, line, ref: line ? `${path}:${line}` : path, preview, score };
@@ -202,12 +211,47 @@ function extractJsonResults(repoRoot: string, stdout: string, config: ContextDis
   }
 }
 
-function runColgrep(repoRoot: string, query: string, roots: string[], config: ContextDiscoveryConfig, maxResults: number, maxContextLines: number): { ok: boolean; results: NormalizedContextResult[]; error?: string } {
+const COLGREP_TIMEOUT_MS = 30_000;
+const COLGREP_MAX_OUTPUT_BYTES = 1024 * 1024;
+
+type ColgrepRunResult = { ok: boolean; results: NormalizedContextResult[]; error?: string };
+
+async function runColgrep(repoRoot: string, query: string, roots: string[], config: ContextDiscoveryConfig, maxResults: number, maxContextLines: number): Promise<ColgrepRunResult> {
   const args = ["--json", "-k", String(maxResults), "-n", String(maxContextLines), query, ...roots];
-  const result = spawnSync("colgrep", args, { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10_000, maxBuffer: 1024 * 1024 });
-  if (result.status !== 0) return { ok: false, results: [], error: result.stderr.trim().slice(0, 240) || `colgrep exited ${String(result.status)}` };
-  const results = extractJsonResults(repoRoot, result.stdout, config, maxResults);
-  return { ok: true, results };
+  return await new Promise<ColgrepRunResult>((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const child = spawn("colgrep", args, { cwd: repoRoot, stdio: ["ignore", "pipe", "pipe"] });
+    const finish = (value: ColgrepRunResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish({ ok: false, results: [], error: `colgrep timed out after ${String(COLGREP_TIMEOUT_MS)}ms; retry with narrower paths or max_results.` });
+    }, COLGREP_TIMEOUT_MS);
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => {
+      stdout += chunk;
+      if (stdout.length > COLGREP_MAX_OUTPUT_BYTES) {
+        child.kill("SIGTERM");
+        finish({ ok: false, results: [], error: "colgrep output exceeded compact result budget; retry with lower max_results." });
+      }
+    });
+    child.stderr.on("data", (chunk: string) => { stderr += chunk; });
+    child.on("error", (error) => finish({ ok: false, results: [], error: error.message.slice(0, 240) }));
+    child.on("close", (code) => {
+      if (code !== 0) {
+        finish({ ok: false, results: [], error: stderr.trim().slice(0, 240) || `colgrep exited ${String(code)}` });
+        return;
+      }
+      finish({ ok: true, results: extractJsonResults(repoRoot, stdout, config, maxResults) });
+    });
+  });
 }
 
 function fallbackSearch(repoRoot: string, params: Required<Pick<ContextSearchParams, "query" | "mode">> & Pick<ContextSearchParams, "pattern" | "paths">, config: ContextDiscoveryConfig, maxResults: number, maxContextLines: number): { results: NormalizedContextResult[]; rejectedPaths: string[]; roots: string[] } {
@@ -246,7 +290,7 @@ function fallbackSearch(repoRoot: string, params: Required<Pick<ContextSearchPar
   return { results, rejectedPaths: rejected, roots };
 }
 
-export function runContextSearch(repoRoot: string, input: ContextSearchParams): Record<string, unknown> {
+export async function runContextSearch(repoRoot: string, input: ContextSearchParams): Promise<Record<string, unknown>> {
   const config = loadContextDiscoveryConfig(repoRoot);
   const query = String(input.query ?? "").trim();
   const mode = input.mode ?? "auto";
@@ -259,7 +303,7 @@ export function runContextSearch(repoRoot: string, input: ContextSearchParams):
   let fallbackReason = detection.ready ? undefined : detection.guidance;
   let results: NormalizedContextResult[] = [];
   if (detection.ready && mode !== "regex" && mode !== "files") {
-    const colgrep = runColgrep(repoRoot, query, roots, config, maxResults, maxContextLines);
+    const colgrep = await runColgrep(repoRoot, query, roots, config, maxResults, maxContextLines);
     if (colgrep.ok) results = colgrep.results;
     else {
       provider = "grep-fallback";
@@ -292,7 +336,7 @@ export function runContextSearch(repoRoot: string, input: ContextSearchParams):
     rejectedPaths: rejected,
     limits: { maxResults, maxContextLines },
     recommendedVerification: refs.length > 0
-      ? [`grep -n ${shellQuote(query)} ${shellQuote(results[0]?.path ?? roots[0] ?? ".")}`, `read ${results[0]?.path ?? roots[0] ?? "."}`]
+      ? [`read ${results[0]?.path ?? roots[0] ?? "."}`, "After reading, grep exact identifiers/strings found in returned refs for final proof."]
       : [`grep -R -n ${shellQuote(query)} ${roots.map(shellQuote).join(" ") || "."}`, "find relevant safe paths, then read exact files"],
     safety: { repoRelativeOnly: true, forbiddenPathsExcluded: config.excludePaths, rawPromptOrConversationPersisted: false, autoInstall: false },
   };

package/.pi/extensions/zob-harness/src/runtime/commands.ts

@@ -26,6 +26,7 @@ import { showDelegationOverlay } from "./delegation-overlay.js";
 import { finishDelegationRun } from "./delegation-monitor.js";
 import { showGoalTodoOverlay } from "./goal-todo-overlay.js";
 import type { HarnessRuntimeState } from "./state.js";
+import { registerZobIntroCommand } from "./zob-intro.js";
 import {
   asInteractiveAutonomyMode,
   formatInteractiveAutonomyStatus,
@@ -986,6 +987,8 @@ export function registerHarnessCommands(pi: ExtensionAPI, state: HarnessRuntimeS
     refreshIntentClassifierModelCache(ctx);
   });
 
+  registerZobIntroCommand(pi);
+
   // Exact `/new` is handled by Pi before extension input/command hooks. Soft carryover
   // is therefore written from the `session_shutdown` reason="new" hook in events.ts.
   // Keep this registration only for `/new hard`, where users need an explicit clean reset.

package/.pi/extensions/zob-harness/src/runtime/tools-context.ts

@@ -30,16 +30,19 @@ export function registerContextTools(pi: ExtensionAPI): void {
     name: "zob_context_search",
     label: "ZOB Context Search",
     description: "Search bounded repo-local context through the active context backend. Prefers ColGREP when installed and ready, falls back to safe grep/find-style search, never auto-installs ColGREP, and excludes forbidden/session/vendor/build paths.",
-    promptSnippet: "Use zob_context_search for bounded repo-local discovery before broad grep/read; verify exact proof with grep/read on returned refs.",
+    promptSnippet: "For exploratory/natural-language repo discovery, call zob_context_search before broad grep/find; if this tool is not exposed but bash is available, use compact npm run --silent zob:context:query before rg/grep; verify exact proof with grep/read on returned refs.",
     promptGuidelines: [
-      "Call zob_context_search for codebase/context discovery when semantic or broad search is useful.",
+      "Call zob_context_search first for exploratory/natural-language codebase discovery when semantic or broad search is useful.",
       "zob_context_search prefers ColGREP when ready and falls back to bounded grep when ColGREP is missing, not ready, or a query fails.",
+      "If zob_context_search is not available in the current toolset, use the compact local wrapper: npm run --silent zob:context:query -- --query \"<query>\" --max-results 6 --max-context-lines 1 before broad rg/grep.",
       "Never install ColGREP from this tool path; missing ColGREP is not a blocker.",
+      "Run one exploratory context search, then read returned refs; retry only when results are empty or clearly irrelevant.",
+      "Never run broad grep/find over .pi unless .pi/sessions and .pi/agent-sessions are explicitly excluded/pruned.",
       "Use returned refs as leads and verify final claims with exact read/grep evidence.",
     ],
     parameters: ContextSearchParams,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const result = runContextSearch(ctx.cwd, params);
+      const result = await runContextSearch(ctx.cwd, params);
       return { content: [{ type: "text", text: formatContextSearchResult(result) }], details: result };
     },
   });

package/.pi/extensions/zob-harness/src/runtime/zob-intro.ts

@@ -0,0 +1,662 @@
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem, Component, TUI } from "@earendil-works/pi-tui";
+import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import { sha256 } from "../core/utils/hashing.js";
+
+type LogicalFrame = readonly string[];
+type ZobIntroStyleName = "accent" | "plain";
+
+type ZobIntroOptions = {
+  blockWidth: number;
+  blockHeight: number;
+  tickMs: number;
+  repeat: number | null;
+  style: ZobIntroStyleName;
+};
+
+type ZobIntroParseResult =
+  | { ok: true; help: false; options: ZobIntroOptions }
+  | { ok: true; help: true; options: ZobIntroOptions }
+  | { ok: false; errors: string[]; options: ZobIntroOptions };
+
+type ZobIntroStyles = {
+  accent: (text: string) => string;
+  block: (text: string) => string;
+  bold: (text: string) => string;
+  dim: (text: string) => string;
+  exhaustHot: (text: string) => string;
+  exhaustDim: (text: string) => string;
+  warning: (text: string) => string;
+};
+
+const WELCOME_TITLE = "Welcome to the ZOB Harness";
+const START_PROMPT = "Press Enter/Space to continue";
+const FIRST_RUN_MARKER_RELATIVE_PATH = ".pi/tmp/zob-intro-first-run.json";
+const FIRST_RUN_ARGS = "once fast";
+
+const DEFAULT_ZOB_INTRO_OPTIONS: ZobIntroOptions = {
+  blockWidth: 6,
+  blockHeight: 3,
+  tickMs: 180,
+  repeat: 3,
+  style: "accent",
+};
+
+const ZOB_INTRO_MIN_CANVAS_COLS = 8;
+const ZOB_INTRO_EXIT_FRAME_COUNT = 10;
+const ZOB_INTRO_WRAP_PAUSE_FRAME_COUNT = 2;
+const ZOB_INTRO_WRAP_PASS_FRAME_COUNT = 8;
+const BUILD_FRAME_TICK_HOLD = 2;
+const WELCOME_TEXT_SHIFT_LEFT = -3;
+
+const ZOB_INTRO_TARGET_FRAME = [
+  "###.....",
+  "#.#####.",
+  "###....#",
+  "#.#####.",
+  "###.....",
+] as const satisfies LogicalFrame;
+
+const ZOB_INTRO_MORPH_FRAMES = [
+  ["###.", "#.#.", "##.#", "#..#"],
+  ["###.", "#.#.", "##+#", "#.+#"],
+  ["###.", "#.#.", "###.", "#.#."],
+  ["###.", "#.#.", "###.", "#.#.", "+..."],
+  ["###.", "#.#.", "###.", "#.#.", "#..."],
+  ["###.", "#.#.", "###.", "#.#.", "#+.."],
+  ["###.", "#.#.", "###.", "#.#.", "##.."],
+  ["###.....", "#.#.....", "###.....", "#.#.....", "##+....."],
+  ["###.....", "#.#.....", "###.....", "#.#.....", "###....."],
+  ["###.....", "#.#+....", "###.+...", "#.#+....", "###....."],
+  ["###.....", "#.##....", "###.#...", "#.##....", "###....."],
+  ["###.....", "#.##+...", "###..+..", "#.##+...", "###....."],
+  ["###.....", "#.###...", "###..#..", "#.###...", "###....."],
+  ["###.....", "#.###+..", "###...+.", "#.###+..", "###....."],
+  ["###.....", "#.####..", "###...#.", "#.####..", "###....."],
+  ["###.....", "#.####+.", "###....+", "#.####+.", "###....."],
+  ZOB_INTRO_TARGET_FRAME,
+] as const satisfies readonly LogicalFrame[];
+
+function frameWidth(frame: LogicalFrame): number {
+  return Math.max(...frame.map((row) => row.length));
+}
+
+function centerOffset(frame: LogicalFrame, width: number): number {
+  return Math.max(0, Math.floor((width - frameWidth(frame)) / 2));
+}
+
+function placeFrame(frame: LogicalFrame, offsetX: number, width: number): string[] {
+  return frame.map((row) => {
+    const cells = Array.from({ length: width }, () => ".");
+    for (let sourceX = 0; sourceX < row.length; sourceX += 1) {
+      const cell = row[sourceX];
+      if (!cell || cell === ".") continue;
+      const targetX = offsetX + sourceX;
+      if (targetX >= 0 && targetX < width) cells[targetX] = cell;
+    }
+    return cells.join("");
+  });
+}
+
+function writeCells(row: string[], startX: number, pattern: string): void {
+  for (let index = 0; index < pattern.length; index += 1) {
+    const targetX = startX + index;
+    if (targetX < 0 || targetX >= row.length) continue;
+    if (row[targetX] !== ".") continue;
+    row[targetX] = pattern[index] ?? ".";
+  }
+}
+
+function buildLaserPattern(length: number, pulse: number, lane: number): string {
+  return Array.from({ length }, (_unused, index) => {
+    const phase = (index + pulse + lane * 2) % 7;
+    if (phase <= 1) return "=";
+    if (phase === 2 || phase === 5) return "-";
+    if (phase === 3) return "~";
+    return ".";
+  }).join("");
+}
+
+function withLaserRays(frame: LogicalFrame, rayStartX: number, pulse: number, width: number, boosted = false): string[] {
+  const rows = frame.map((row) => row.padEnd(width, ".").slice(0, width).split(""));
+  const start = Math.max(0, rayStartX);
+  const length = Math.max(0, width - start);
+  if (boosted && rows[1]) writeCells(rows[1], start, buildLaserPattern(Math.max(0, length - 2), pulse, 1));
+  if (rows[2]) writeCells(rows[2], start, buildLaserPattern(length, pulse + 1, 0));
+  if (boosted && rows[3]) writeCells(rows[3], start, buildLaserPattern(Math.max(0, length - 1), pulse + 2, 2));
+  return rows.map((row) => row.join(""));
+}
+
+function emptyIntroFrame(width: number): LogicalFrame {
+  return Array.from({ length: LOGICAL_ROWS }, () => ".".repeat(width));
+}
+
+function buildExitFrame(exitIndex: number, width: number, startOffset: number, endOffset: number, pulseOffset = 0, boosted = false): LogicalFrame {
+  const targetWidth = frameWidth(ZOB_INTRO_TARGET_FRAME);
+  const denominator = Math.max(1, ZOB_INTRO_EXIT_FRAME_COUNT - 1);
+  const rawT = Math.min(1, exitIndex / denominator);
+  const t = rawT * rawT;
+  const offsetX = Math.round(startOffset + (endOffset - startOffset) * t);
+  const shiftedWholeLogo = placeFrame(ZOB_INTRO_TARGET_FRAME, offsetX, width);
+  return withLaserRays(shiftedWholeLogo, offsetX + targetWidth, exitIndex + pulseOffset, width, boosted);
+}
+
+function buildWrapPassFrame(passIndex: number, width: number): LogicalFrame {
+  const targetWidth = frameWidth(ZOB_INTRO_TARGET_FRAME);
+  const startOffset = width + 1;
+  const endOffset = -targetWidth - 1;
+  const denominator = Math.max(1, ZOB_INTRO_WRAP_PASS_FRAME_COUNT - 1);
+  const t = Math.min(1, passIndex / denominator);
+  const offsetX = Math.round(startOffset + (endOffset - startOffset) * t);
+  const shiftedWholeLogo = placeFrame(ZOB_INTRO_TARGET_FRAME, offsetX, width);
+  return withLaserRays(shiftedWholeLogo, offsetX + targetWidth, passIndex + ZOB_INTRO_EXIT_FRAME_COUNT, width, true);
+}
+
+function buildIntroFrame(frameIndex: number, width: number): LogicalFrame {
+  if (frameIndex < ZOB_INTRO_MORPH_FRAMES.length) {
+    const frame = ZOB_INTRO_MORPH_FRAMES[frameIndex] ?? ZOB_INTRO_MORPH_FRAMES[0];
+    return placeFrame(frame, centerOffset(frame, width), width);
+  }
+
+  let phaseIndex = Math.max(0, frameIndex - ZOB_INTRO_MORPH_FRAMES.length);
+  const targetWidth = frameWidth(ZOB_INTRO_TARGET_FRAME);
+  if (phaseIndex < ZOB_INTRO_EXIT_FRAME_COUNT) {
+    return buildExitFrame(phaseIndex, width, centerOffset(ZOB_INTRO_TARGET_FRAME, width), -targetWidth - 1);
+  }
+  phaseIndex -= ZOB_INTRO_EXIT_FRAME_COUNT;
+  if (phaseIndex < ZOB_INTRO_WRAP_PAUSE_FRAME_COUNT) return emptyIntroFrame(width);
+  phaseIndex -= ZOB_INTRO_WRAP_PAUSE_FRAME_COUNT;
+  return buildWrapPassFrame(phaseIndex, width);
+}
+
+const ZOB_INTRO_FRAME_COUNT = ZOB_INTRO_MORPH_FRAMES.length + ZOB_INTRO_EXIT_FRAME_COUNT + ZOB_INTRO_WRAP_PAUSE_FRAME_COUNT + ZOB_INTRO_WRAP_PASS_FRAME_COUNT;
+const LOGICAL_ROWS = Math.max(...ZOB_INTRO_MORPH_FRAMES.map((frame) => frame.length));
+
+function cloneDefaultOptions(): ZobIntroOptions {
+  return { ...DEFAULT_ZOB_INTRO_OPTIONS };
+}
+
+function parsePositiveInt(value: string, label: string, min: number, max: number, errors: string[]): number | undefined {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < min || parsed > max) {
+    errors.push(`${label} must be an integer between ${min} and ${max}`);
+    return undefined;
+  }
+  return parsed;
+}
+
+function parseZobIntroArgs(args: string): ZobIntroParseResult {
+  const options = cloneDefaultOptions();
+  const parts = args.trim().split(/\s+/).filter(Boolean);
+  const errors: string[] = [];
+  let help = false;
+
+  for (let index = 0; index < parts.length; index += 1) {
+    const part = parts[index]?.toLowerCase() ?? "";
+    if (part === "help" || part === "--help" || part === "-h") {
+      help = true;
+      continue;
+    }
+    if (part === "loop") {
+      options.repeat = null;
+      continue;
+    }
+    if (part === "once") {
+      options.repeat = 1;
+      continue;
+    }
+    if (part === "fast") {
+      options.tickMs = 90;
+      continue;
+    }
+    if (part === "slow") {
+      options.tickMs = 300;
+      continue;
+    }
+    if (part === "normal") {
+      options.tickMs = DEFAULT_ZOB_INTRO_OPTIONS.tickMs;
+      continue;
+    }
+    if (part === "plain" || part === "mono") {
+      options.style = "plain";
+      continue;
+    }
+    if (part === "accent" || part === "neon") {
+      options.style = "accent";
+      continue;
+    }
+    if (part === "--repeat") {
+      const next = parts[index + 1];
+      if (!next) {
+        errors.push("--repeat requires a positive integer or 'loop'");
+        continue;
+      }
+      index += 1;
+      if (next.toLowerCase() === "loop") options.repeat = null;
+      else {
+        const repeat = parsePositiveInt(next, "repeat", 1, 99, errors);
+        if (repeat !== undefined) options.repeat = repeat;
+      }
+      continue;
+    }
+    if (part === "--speed" || part === "--tick-ms") {
+      const next = parts[index + 1];
+      if (!next) {
+        errors.push(`${part} requires a millisecond value`);
+        continue;
+      }
+      index += 1;
+      const tickMs = parsePositiveInt(next, "tickMs", 30, 2_000, errors);
+      if (tickMs !== undefined) options.tickMs = tickMs;
+      continue;
+    }
+    const blockMatch = /^(\d+)x(\d+)$/.exec(part);
+    if (blockMatch) {
+      const blockWidth = parsePositiveInt(blockMatch[1] ?? "", "blockWidth", 1, 20, errors);
+      const blockHeight = parsePositiveInt(blockMatch[2] ?? "", "blockHeight", 1, 12, errors);
+      if (blockWidth !== undefined) options.blockWidth = blockWidth;
+      if (blockHeight !== undefined) options.blockHeight = blockHeight;
+      continue;
+    }
+    errors.push(`unknown option '${part}'`);
+  }
+
+  if (errors.length > 0) return { ok: false, errors, options };
+  return { ok: true, help, options };
+}
+
+function zobIntroHelpTemplate(): string {
+  return [
+    "# ZOB intro animation",
+    "",
+    "Usage:",
+    "/zob-intro                 # play the morph + whole-logo laser exit, default 6x3 terminal pixels",
+    "/zob-intro once            # play once then close",
+    "/zob-intro loop            # loop until ESC/Q",
+    "/zob-intro fast 6x3 neon   # faster and wider terminal pixels",
+    "/zob-intro slow 5x3 plain  # slower uncolored blocks",
+    "/zob-intro reset-first-run # show the startup intro again on next Pi/ZOB launch",
+    "",
+    "Options:",
+    "- once | loop | --repeat N",
+    "- fast | normal | slow | --speed MS",
+    "- 3x3 | 5x3 | 6x3 | any WxH up to 20x12",
+    "- accent/neon | plain/mono",
+    "",
+    "Controls:",
+    "- Enter or Space: start from welcome screen",
+    "- ESC or Q: close",
+    "- Space after start: pause/resume",
+  ].join("\n");
+}
+
+function zobIntroArgumentCompletions(prefix: string): AutocompleteItem[] | null {
+  const query = prefix.trim().toLowerCase();
+  const items: AutocompleteItem[] = [
+    { value: "once", label: "once", description: "play one time then close" },
+    { value: "loop", label: "loop", description: "loop until ESC/Q" },
+    { value: "fast", label: "fast", description: "90ms per frame" },
+    { value: "normal", label: "normal", description: "180ms per frame" },
+    { value: "slow", label: "slow", description: "300ms per frame" },
+    { value: "5x3", label: "5x3", description: "narrower terminal-pixel ratio" },
+    { value: "6x3", label: "6x3", description: "default terminal-pixel ratio" },
+    { value: "plain", label: "plain", description: "uncolored terminal foreground" },
+    { value: "neon", label: "neon", description: "theme accent blocks" },
+    { value: "reset-first-run", label: "reset-first-run", description: "show startup intro again on next Pi/ZOB launch" },
+    { value: "help", label: "help", description: "insert usage help" },
+  ];
+  const filtered = query
+    ? items.filter((item) => item.value.toLowerCase().startsWith(query) || item.label.toLowerCase().includes(query) || item.description?.toLowerCase().includes(query))
+    : items;
+  return filtered.length > 0 ? filtered.slice(0, 20) : null;
+}
+
+function stableFrameHash(): string {
+  return sha256(JSON.stringify({ morphFrames: ZOB_INTRO_MORPH_FRAMES, targetFrame: ZOB_INTRO_TARGET_FRAME, exitFrameCount: ZOB_INTRO_EXIT_FRAME_COUNT, wrapPauseFrameCount: ZOB_INTRO_WRAP_PAUSE_FRAME_COUNT, wrapPassFrameCount: ZOB_INTRO_WRAP_PASS_FRAME_COUNT }));
+}
+
+function appendZobIntroLedger(pi: ExtensionAPI, options: ZobIntroOptions, status: "played" | "blocked" | "help" | "reset" | "auto_skipped", errors: string[] = []): void {
+  pi.appendEntry("zob-intro-command", {
+    schema: "zob.intro-command.v1",
+    status,
+    frameCount: ZOB_INTRO_FRAME_COUNT,
+    logicalCols: "dynamic",
+    logicalRows: LOGICAL_ROWS,
+    blockWidth: options.blockWidth,
+    blockHeight: options.blockHeight,
+    tickMs: options.tickMs,
+    repeat: options.repeat ?? "loop",
+    style: options.style,
+    frameHash: stableFrameHash(),
+    errorHashes: errors.map((error) => sha256(error)),
+    rawFramesStored: false,
+    bodyStored: false,
+    generatedAt: new Date().toISOString(),
+  });
+}
+
+function firstRunMarkerPath(cwd: string): string {
+  return join(cwd, FIRST_RUN_MARKER_RELATIVE_PATH);
+}
+
+async function hasSeenFirstRunIntro(cwd: string): Promise<boolean> {
+  try {
+    await readFile(firstRunMarkerPath(cwd), "utf8");
+    return true;
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return false;
+    return true;
+  }
+}
+
+async function markFirstRunIntroSeen(cwd: string): Promise<void> {
+  const markerPath = firstRunMarkerPath(cwd);
+  await mkdir(dirname(markerPath), { recursive: true });
+  await writeFile(markerPath, `${JSON.stringify({ schema: "zob.intro-first-run-marker.v1", seenAt: new Date().toISOString(), frameHash: stableFrameHash(), bodyStored: false }, null, 2)}\n`, "utf8");
+}
+
+async function resetFirstRunIntro(cwd: string): Promise<void> {
+  try {
+    await unlink(firstRunMarkerPath(cwd));
+  } catch (error) {
+    if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT")) throw error;
+  }
+}
+
+class ZobIntroComponent implements Component {
+  private frameIndex = 0;
+  private completedCycles = 0;
+  private paused = false;
+  private interval: ReturnType<typeof setInterval> | undefined;
+  private welcomeInterval: ReturnType<typeof setInterval> | undefined;
+  private cachedWidth = 0;
+  private cachedHeight = 0;
+  private cachedVersion = -1;
+  private cachedLines: string[] = [];
+  private version = 0;
+  private closed = false;
+  private waitingForStart = true;
+  private welcomeTick = 0;
+  private buildHoldTick = 0;
+
+  constructor(
+    private readonly tui: Pick<TUI, "requestRender" | "terminal">,
+    private readonly styles: ZobIntroStyles,
+    private readonly options: ZobIntroOptions,
+    private readonly onDone: () => void,
+  ) {
+    this.tui.terminal.clearScreen();
+    this.tui.terminal.hideCursor();
+    this.startWelcomeReveal();
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape") || data === "q" || data === "Q") {
+      this.close();
+      return;
+    }
+    if (this.waitingForStart) {
+      if (matchesKey(data, "enter") || matchesKey(data, "space") || data === "\r" || data === "\n" || data === " ") {
+        this.waitingForStart = false;
+        this.stopWelcomeReveal();
+        this.start();
+        this.version += 1;
+        this.tui.requestRender();
+      }
+      return;
+    }
+    if (matchesKey(data, "space") || data === " ") {
+      this.paused = !this.paused;
+      this.version += 1;
+      this.tui.requestRender();
+    }
+  }
+
+  invalidate(): void {
+    this.cachedWidth = 0;
+    this.cachedHeight = 0;
+    this.cachedVersion = -1;
+  }
+
+  render(width: number): string[] {
+    const height = Math.max(1, this.tui.terminal.rows);
+    if (this.cachedWidth === width && this.cachedHeight === height && this.cachedVersion === this.version) return this.cachedLines;
+
+    const welcomeLines = this.waitingForStart ? this.renderWelcomeLines(width) : [];
+    const artLines = this.renderArt(this.options.blockWidth, this.options.blockHeight, this.logicalColsForWidth(width));
+    const emptyLine = " ".repeat(Math.max(0, width));
+    const contentHeight = artLines.length + welcomeLines.length;
+    const topPad = Math.max(0, Math.floor((height - contentHeight) / 2));
+    const lines: string[] = [];
+
+    for (let index = 0; index < topPad; index += 1) lines.push(emptyLine);
+    for (const artLine of artLines) lines.push(this.centerLine(artLine, width));
+    for (const welcomeLine of welcomeLines) lines.push(this.centerLine(welcomeLine, width, WELCOME_TEXT_SHIFT_LEFT));
+    while (lines.length < height) lines.push(emptyLine);
+
+    this.cachedLines = lines.slice(0, height);
+    this.cachedWidth = width;
+    this.cachedHeight = height;
+    this.cachedVersion = this.version;
+    return this.cachedLines;
+  }
+
+  dispose(): void {
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = undefined;
+    }
+    this.stopWelcomeReveal();
+    this.tui.terminal.showCursor();
+  }
+
+  private startWelcomeReveal(): void {
+    this.welcomeInterval = setInterval(() => {
+      if (!this.waitingForStart) return;
+      this.welcomeTick += 1;
+      this.version += 1;
+      this.tui.requestRender();
+    }, 55);
+    this.welcomeInterval.unref?.();
+  }
+
+  private stopWelcomeReveal(): void {
+    if (!this.welcomeInterval) return;
+    clearInterval(this.welcomeInterval);
+    this.welcomeInterval = undefined;
+  }
+
+  private start(): void {
+    if (this.interval) return;
+    this.interval = setInterval(() => {
+      if (this.paused) return;
+      if (this.shouldHoldBuildFrame()) return;
+      this.advanceFrame();
+      this.version += 1;
+      this.tui.requestRender();
+    }, this.options.tickMs);
+    this.interval.unref?.();
+  }
+
+  private shouldHoldBuildFrame(): boolean {
+    if (this.frameIndex >= ZOB_INTRO_MORPH_FRAMES.length) {
+      this.buildHoldTick = 0;
+      return false;
+    }
+    this.buildHoldTick = (this.buildHoldTick + 1) % BUILD_FRAME_TICK_HOLD;
+    return this.buildHoldTick !== 0;
+  }
+
+  private advanceFrame(): void {
+    this.frameIndex += 1;
+    if (this.frameIndex < ZOB_INTRO_FRAME_COUNT) return;
+
+    this.completedCycles += 1;
+    if (this.options.repeat !== null && this.completedCycles >= this.options.repeat) {
+      this.frameIndex = ZOB_INTRO_FRAME_COUNT - 1;
+      this.close();
+      return;
+    }
+    this.frameIndex = 0;
+  }
+
+  private close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.dispose();
+    this.onDone();
+  }
+
+  private renderWelcomeLines(width: number): string[] {
+    const titleVisible = this.revealText(WELCOME_TITLE, this.welcomeTick);
+    const promptStartTick = WELCOME_TITLE.length + 8;
+    const promptVisible = this.revealText(START_PROMPT, Math.max(0, this.welcomeTick - promptStartTick));
+    const title = this.styles.bold(this.styles.accent(titleVisible)) + " ".repeat(Math.max(0, WELCOME_TITLE.length - titleVisible.length));
+    const promptPulse = Math.floor(this.welcomeTick / 12) % 2 === 0;
+    const promptText = promptPulse ? this.styles.dim(promptVisible) : this.styles.accent(promptVisible);
+    const prompt = promptText + " ".repeat(Math.max(0, START_PROMPT.length - promptVisible.length));
+    return ["", title, prompt].filter((line) => visibleWidth(line) <= width || line.length > 0);
+  }
+
+  private revealText(text: string, tick: number): string {
+    if (tick <= 0) return "";
+    return text.slice(0, Math.min(text.length, tick));
+  }
+
+  private logicalColsForWidth(width: number): number {
+    return Math.max(ZOB_INTRO_MIN_CANVAS_COLS, Math.floor(width / Math.max(1, this.options.blockWidth)));
+  }
+
+  private renderArt(blockWidth: number, blockHeight: number, logicalCols: number): string[] {
+    const frame = buildIntroFrame(this.frameIndex, logicalCols);
+    const lines: string[] = [];
+
+    for (let rowIndex = 0; rowIndex < LOGICAL_ROWS; rowIndex += 1) {
+      const logicalRow = (frame[rowIndex] ?? "").padEnd(logicalCols, ".").slice(0, logicalCols);
+      for (let subRow = 0; subRow < blockHeight; subRow += 1) {
+        let renderedRow = "";
+        for (const cell of logicalRow) renderedRow += this.renderCell(cell, subRow, blockWidth, blockHeight);
+        lines.push(renderedRow);
+      }
+    }
+    return lines;
+  }
+
+  private renderCell(cell: string, subRow: number, blockWidth: number, blockHeight: number): string {
+    const blank = " ".repeat(blockWidth);
+    const solid = (glyph: string, color: (text: string) => string): string => {
+      const text = glyph.repeat(blockWidth);
+      return this.options.style === "plain" ? text : color(text);
+    };
+    if (cell === "#") return solid("█", this.styles.block);
+    if (cell === "*") return solid("▓", this.styles.exhaustHot);
+    if (cell === "+") return solid("▒", this.styles.exhaustDim);
+    if (cell === "=") {
+      const middle = Math.floor(blockHeight / 2);
+      return subRow === middle ? solid("━", this.styles.exhaustHot) : blank;
+    }
+    if (cell === "~") {
+      const middle = Math.floor(blockHeight / 2);
+      return subRow === middle ? solid("·", this.styles.exhaustDim) : blank;
+    }
+    if (cell === "-") {
+      const middle = Math.floor(blockHeight / 2);
+      return subRow === middle ? solid("─", this.styles.exhaustDim) : blank;
+    }
+    return blank;
+  }
+
+  private centerLine(line: string, width: number, shiftRight = 0): string {
+    if (width <= 0) return "";
+    const lineWidth = visibleWidth(line);
+    if (lineWidth >= width) return truncateToWidth(line, width, "");
+    const leftPad = Math.max(0, Math.min(width - lineWidth, Math.floor((width - lineWidth) / 2) + shiftRight));
+    return `${" ".repeat(leftPad)}${line}`;
+  }
+}
+
+async function handleZobIntroCommand(pi: ExtensionAPI, args: string, ctx: ExtensionContext): Promise<void> {
+  const normalized = args.trim().toLowerCase();
+  if (normalized === "reset-first-run" || normalized === "reset-startup" || normalized === "reset") {
+    await resetFirstRunIntro(ctx.cwd);
+    appendZobIntroLedger(pi, DEFAULT_ZOB_INTRO_OPTIONS, "reset");
+    ctx.ui.notify("ZOB intro first-run marker reset. Quit and relaunch Pi/ZOB to see the startup intro again.", "info");
+    return;
+  }
+
+  const parsed = parseZobIntroArgs(args);
+  if (parsed.ok && parsed.help) {
+    appendZobIntroLedger(pi, parsed.options, "help");
+    ctx.ui.setEditorText(zobIntroHelpTemplate());
+    ctx.ui.notify("ZOB intro help inserted. Use /zob-intro or /zob-intro loop.", "info");
+    return;
+  }
+  if (!parsed.ok) {
+    appendZobIntroLedger(pi, parsed.options, "blocked", parsed.errors);
+    ctx.ui.notify(`/zob-intro blocked: ${parsed.errors.join(" | ")}. Use /zob-intro help.`, "warning");
+    return;
+  }
+  if (!ctx.hasUI) {
+    appendZobIntroLedger(pi, parsed.options, "blocked", ["interactive UI required"]);
+    ctx.ui.notify("/zob-intro requires interactive Pi TUI mode.", "warning");
+    return;
+  }
+
+  appendZobIntroLedger(pi, parsed.options, "played");
+  await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+    const styles: ZobIntroStyles = {
+      accent: (text) => theme.fg("accent", text),
+      block: (text) => theme.fg("accent", text),
+      bold: (text) => theme.bold(text),
+      dim: (text) => theme.fg("dim", text),
+      exhaustHot: (text) => theme.fg("warning", text),
+      exhaustDim: (text) => theme.fg("dim", text),
+      warning: (text) => theme.fg("warning", text),
+    };
+    return new ZobIntroComponent(tui, styles, parsed.options, () => done(undefined));
+  }, {
+    overlay: true,
+    overlayOptions: {
+      width: "100%",
+      maxHeight: "100%",
+      anchor: "center",
+      margin: 0,
+    },
+  });
+}
+
+export function registerZobIntroCommand(pi: ExtensionAPI): void {
+  const command = {
+    description: "Play the custom ZOB pixel-art terminal intro animation. Options: once|loop|fast|slow|5x3|6x3|plain|neon.",
+    getArgumentCompletions: zobIntroArgumentCompletions,
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      await handleZobIntroCommand(pi, args, ctx);
+    },
+  };
+
+  pi.registerCommand("zob-intro", command);
+  pi.registerCommand("zintro", { ...command, description: "Alias for /zob-intro." });
+  pi.registerCommand("intro", { ...command, description: "Alias for /zob-intro." });
+
+  pi.on("session_start", async (event, ctx) => {
+    if (event.reason !== "startup") return;
+    if (!ctx.hasUI) return;
+    if (await hasSeenFirstRunIntro(ctx.cwd)) {
+      appendZobIntroLedger(pi, DEFAULT_ZOB_INTRO_OPTIONS, "auto_skipped");
+      return;
+    }
+    await markFirstRunIntroSeen(ctx.cwd);
+    await handleZobIntroCommand(pi, FIRST_RUN_ARGS, ctx);
+  });
+
+  pi.on("input", async (event, ctx) => {
+    const match = /^\/(zob-intro|zintro|intro)(?:\s+(.*))?$/.exec(event.text.trim());
+    if (!match) return { action: "continue" as const };
+    await handleZobIntroCommand(pi, match[2] ?? "", ctx);
+    return { action: "handled" as const };
+  });
+}

package/.pi/skills/zob-context-discovery/SKILL.md

@@ -15,13 +15,17 @@ Use this skill for:
 ## Active backend rules
 
 1. Prefer `zob_context_search` for repo-local discovery when the runtime tool is available.
-2. When ColGREP is installed and ready, use it as the preferred broad/semantic discovery backend.
-3. Always use grep/find/read or exact file refs for verification before making claims.
-4. When ColGREP is missing, unavailable, or not indexed, fall back to grep/find/read. Missing ColGREP is not a blocker for normal ZOB work.
-5. Do not auto-install ColGREP, run network/package-manager installer commands, or mutate user tooling without explicit owner approval.
-6. Keep search bounded to repo-local allowed paths and task-relevant globs.
-7. Never read forbidden paths or secret-like files, including `.env`, `**/.env`, `**/*secret*`, `**/*key*`, private keys, `.pi/sessions`, `.pi/agent-sessions`, `node_modules`, `dist`, or `build`.
-8. Persist only safe metadata/artifact refs for context packs. Do not persist raw secret/session bodies.
+2. When ColGREP is installed and ready, exploratory or natural-language repo discovery MUST start with `zob_context_search`/ColGREP before broad grep/find. This includes prompts like “explore this repo”, “where is this mechanism?”, or “find the design/flow”.
+3. If `zob_context_search` is not exposed in the current session/toolset but `bash` is available, use the compact local wrapper before broad grep: `npm run --silent zob:context:query -- --query "<natural language query>" --max-results 6 --max-context-lines 1`.
+4. Do not treat missing native-tool exposure as permission to immediately use broad `rg`/`grep`; the wrapper is the ColGREP path for those sessions.
+5. Run one exploratory context search, then read returned refs; retry only when results are empty or clearly irrelevant.
+6. Use grep/find/read after semantic discovery for exact proof, known identifiers/strings, final citations, and line refs. If the exact identifier/path/string is already known, grep/read may be used directly.
+7. When ColGREP is missing, unavailable, or not indexed, fall back to grep/find/read. Missing ColGREP is not a blocker for normal ZOB work.
+8. Do not auto-install ColGREP, run network/package-manager installer commands, or mutate user tooling without explicit owner approval.
+9. Keep search bounded to repo-local allowed paths and task-relevant globs.
+10. Never run broad grep/find over `.pi` unless `.pi/sessions` and `.pi/agent-sessions` are explicitly excluded/pruned.
+11. Never read forbidden paths or secret-like files, including `.env`, `**/.env`, `**/*secret*`, `**/*key*`, private keys, `.pi/sessions`, `.pi/agent-sessions`, `node_modules`, `dist`, or `build`.
+12. Persist only safe metadata/artifact refs for context packs. Do not persist raw secret/session bodies.
 
 ## User setup and scripts
 
@@ -34,7 +38,12 @@ Use this skill for:
 
 - Active-backend prompt injection is controlled by `.pi/context-discovery.json` under `promptInjection.enabled`.
 - The injected block must stay concise, current-repo scoped, and bounded by the configured include/exclude roots; it is a discovery hint, not a context pack or evidence source.
-- Do not inject stale/global context or raw search results into the prompt. Use `zob_context_search` and then read exact files when details are needed.
+- Do not inject stale/global context or raw search results into the prompt. Use `zob_context_search` or the compact `npm run --silent zob:context:query` wrapper, then read exact files when details are needed.
+
+## UX / performance posture
+
+- Native `zob_context_search` execution must remain async/non-blocking from the Pi extension perspective; avoid synchronous long-running ColGREP calls in tool handlers.
+- Default discovery output should be compact: a small set of refs/previews, then read exact files. Do not dump raw ColGREP JSON or code bodies into the chat by default.
 
 ## Evidence expectations
 

package/.pi/skills/zob-harness/SKILL.md

@@ -34,7 +34,7 @@ Communication is a core deliverable. Prefer one parent-visible control room by d
 1. Classify the task as one of: `explore`, `plan`, `implement`, `oracle`, `factory`, `orchestrator`. When `.pi/routing/intent-classifier.json` enables an optional model classifier, treat it as advisory intent routing only; regex fallback and deterministic safety hard-blocks remain authoritative. `autoSwitchIntents` controls which detected intents switch mode directly; this project enables all ZOB modes by default. Use `/intent-classifier status|regex|model-strict|model-fallback|test` (alias `/intent`) to switch/test routing without editing JSON by hand.
 2. For non-trivial or tool-ambiguous work, apply `zob-tool-router`: classify applicable families, then use/delegate/skip each with a reason.
 3. Use `orchestrator` when the task needs Chief Vision coordination, multi-agent decomposition, Lead/Worker routing, goal/TODO graph governance, or parent-owned dispatch; the root should delegate substantive work rather than do it directly.
-4. Check `.pi/capabilities/zob-public-runtime-capabilities.json` for the relevant tool/command family, mode allowlist, skill refs, and no-ship notes. For context tasks, prefer the active backend via `zob_context_search`; use ColGREP when ready, and grep/find/read for fallback plus exact verification.
+4. Check `.pi/capabilities/zob-public-runtime-capabilities.json` for the relevant tool/command family, mode allowlist, skill refs, and no-ship notes. For exploratory/natural-language context tasks, start with the active backend via `zob_context_search`; use ColGREP when ready before broad grep/find. If `zob_context_search` is not exposed but bash is available, run `npm run --silent zob:context:query -- --query "<query>" --max-results 6 --max-context-lines 1` before `rg`/`grep`. Use grep/find/read for fallback plus exact verification. Never broad-grep `.pi` without pruning `.pi/sessions` and `.pi/agent-sessions`.
 5. If broad or risky, use the `delegate_agent` tool before editing.
 6. For delegated work, use the six-part contract:
    - TASK

package/.pi/skills/zob-tool-router/SKILL.md

@@ -53,7 +53,7 @@ Do not use this skill for a small factual answer when no tools are needed.
 | delegation | Specialist review, parallel discovery, implementation handoff, independent QA, or uncertain broad work | `zob_delegation_catalog`, `delegate_task`, `delegate_agent`; skill `zob-delegation-routing` |
 | orchestration | Lead/Worker lanes, Chief Vision coordination, parent-owned dispatch, multi-agent workgraph | `/zmode orchestrator`, `orchestrate_run`, `chain_run`, goal/TODO tools |
 | compute | Complexity, budget, model class, max profile, or multi-agent sizing matters | `zob_compute_preview`, `zob_compute_resolve_profile`, `zob_compute_plan_workflow`, `zob_compute_validate_profile`; skill `zob-compute-profile` |
-| context / ProjectDNA | Need bounded repo/reference context, scan artifacts, cited context packs, or writeback proposals | `zob_context_validate_scope`, `zob_context_readiness`, `zob_project_dna_query`, `zob_project_dna_federated_query`, `zob_project_dna_readiness`; skill `zob-project-dna` |
+| context / ProjectDNA | Need bounded repo/reference context, scan artifacts, cited context packs, or writeback proposals | `zob_context_search`, `zob_context_validate_scope`, `zob_context_readiness`, `zob_project_dna_query`, `zob_project_dna_federated_query`, `zob_project_dna_readiness`; skills `zob-context-discovery`, `zob-project-dna` |
 | factory | Repeated workflow, smoke/pilot/batch gates, manifests, checkpoints, sentinels | `factory_run`, factory quarantine tools, autonomous factory read-only smokes; skill `zob-factory` |
 | coms / goal-room | Parent-visible coordination, live required-local handoff, blockers, TODO claims, status refs | `zob_goal_room_*`, `zob_coms_*`; skills `zob-coms-v2-live`, `zob-coms-safety` |
 | workspace / merge queue | Parallel write intent, sandbox diff review, parent-owned manual apply decisions | `zob_workspace_claim`, `zob_workspace_release`, `zob_merge_candidate_submit`, `zob_merge_queue_decide`; skill `zob-sandbox` |

package/AGENTS.md

@@ -49,7 +49,7 @@ Use the registry plus the domain skill instead of copying tool docs into prompts
 - Delegation/catalog: `zob_delegation_catalog`, `delegate_agent`, `delegate_task` -> `.pi/skills/zob-delegation-routing/SKILL.md` and `.pi/skills/zob-harness/SKILL.md`; call the catalog before first delegation when agent/contract/tool routing is uncertain, normally omit `delegate_task.output_contract` and `delegate_task.required_tools`, and never invent contract IDs or agent tools.
 - Live coms: `zob_coms_*` -> `.pi/skills/zob-coms-v2-live/SKILL.md` and `.pi/skills/zob-coms-safety/SKILL.md`; required-local delivery must be live, never append-only success.
 - Mission Control: `zob_mission_control_*` / readiness -> `.pi/skills/zob-mission-control-coms/SKILL.md`; command writes are proposals only.
-- Context: `zob_context_search`, `zob_context_*` -> registry no-ship notes plus `.pi/skills/zob-context-discovery/SKILL.md`, `.pi/skills/zob-harness/SKILL.md`, and `.pi/skills/zob-spec/SKILL.md` as applicable; prefer the active search backend (ColGREP when ready, grep/find/read fallback) and verify exact claims with file refs.
+- Context: `zob_context_search`, `zob_context_*` -> registry no-ship notes plus `.pi/skills/zob-context-discovery/SKILL.md`, `.pi/skills/zob-harness/SKILL.md`, and `.pi/skills/zob-spec/SKILL.md` as applicable; for exploratory/natural-language repo discovery, start with the active search backend (`zob_context_search`/ColGREP when ready, grep/find/read fallback) before broad grep/find; if the native tool is not exposed but bash is available, run the compact wrapper `npm run --silent zob:context:query -- --query "<query>" --max-results 6 --max-context-lines 1` before `rg`/`grep`; then verify exact claims with grep/read/file refs; never broad-grep `.pi` without pruning `.pi/sessions` and `.pi/agent-sessions`.
 - Compute profile / effort routing: `zob_compute_*`, `npm run preview:compute-profile:project-dna-smoke`, `npm run validate:compute-profile:project-dna-smoke` -> `.pi/skills/zob-compute-profile/SKILL.md`; preview/resolve/report tools are metadata-only and never bypass safety, budget, oracle, sandbox, or parent-owned dispatch gates.
 - Autonomy: `zob_autonomous_*` -> `.pi/skills/zob-autonomous-runtime/SKILL.md`; dry-run/readonly smoke/validation are supervised evidence only, not global autonomy completion.
 - Factory quarantine/run: `factory_quarantine_*`, `factory_run` -> `.pi/skills/zob-factory/SKILL.md` and `.pi/skills/zob-sandbox/SKILL.md`.

package/README.md

@@ -332,7 +332,7 @@ This release adds the handoff runtime/docs and `npm run smoke:goal-todo-handoff`
 
 ### Use active context discovery
 
-ZOB can adapt context search to the active backend. Use `zob_context_search` inside Pi when available: it prefers ColGREP for broad/semantic repo discovery when ColGREP is installed and indexed, and falls back to grep/find/read when it is missing or unavailable. Treat broad search hits as leads and verify exact claims with file refs before editing or reporting readiness.
+ZOB can adapt context search to the active backend. Use `zob_context_search` inside Pi when available: it prefers ColGREP for broad/semantic repo discovery when ColGREP is installed and indexed, runs native search asynchronously from the extension handler, and falls back to grep/find/read when it is missing or unavailable. Treat broad search hits as leads and verify exact claims with file refs before editing or reporting readiness.
 
 ColGREP setup is optional and owner-driven; ZOB must not auto-install it or run installer/package-manager commands. Local helpers:
 
@@ -343,7 +343,7 @@ npm run zob:context:query -- "goal todo routing"  # one-shot query with grep fal
 npm run smoke:context-discovery   # deterministic fallback smoke; passes without ColGREP
 ```
 
-Forbidden/secret/session/vendor/build paths remain excluded from discovery. Active-backend prompt injection is bounded and configurable through `.pi/context-discovery.json` (`promptInjection.enabled`); it should never inject stale/global context or raw search results. Oracle/no-ship review for this feature checks context freshness, citation coverage, exact grep/read verification, forbidden-source violations, and no unapproved installer/network behavior.
+Forbidden/secret/session/vendor/build paths remain excluded from discovery. Active-backend prompt injection is bounded and configurable through `.pi/context-discovery.json` (`promptInjection.enabled`); it should never inject stale/global context or raw search results. When ColGREP is ready, exploratory/natural-language repo discovery should start with `zob_context_search`/ColGREP before broad grep/find; if the native tool is not exposed but `bash` is available, use the compact wrapper `npm run --silent zob:context:query -- --query "<query>" --max-results 6 --max-context-lines 1` before `rg`/`grep`. Then use grep/read for exact proof and citations. Broad grep/find over `.pi` must explicitly prune `.pi/sessions` and `.pi/agent-sessions`. Oracle/no-ship review for this feature checks context freshness, citation coverage, exact grep/read verification, forbidden-source violations, and no unapproved installer/network behavior.
 
 See [`reports/context-discovery/design.md`](reports/context-discovery/design.md), [`.pi/skills/zob-context-discovery/SKILL.md`](.pi/skills/zob-context-discovery/SKILL.md), and [scripts/README.md](scripts/README.md) for the operating rules and script map.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zob-harness",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "type": "module",
   "description": "A governed Agent Factory for Pi: launch communicating agent teams, run tmux-backed factories, validate artifacts, and package repeatable workflows.",
   "license": "MIT",

package/scripts/README.md

@@ -8,7 +8,7 @@ These script families are intended to be part of the normal tracked repo workflo
 
 - `scripts/autonomy/` — static/read-only autonomy readiness smokes.
 - `scripts/compute-profile/` — compute profile policy and regression checks.
-- `scripts/context-discovery/` — adaptive active search backend helpers: `npm run zob:context:doctor`, `npm run zob:context:init`, `npm run zob:context:query`, and `npm run smoke:context-discovery`; prefers ColGREP when installed/ready and validates grep fallback when it is absent.
+- `scripts/context-discovery/` — adaptive active search backend helpers: `npm run zob:context:doctor`, `npm run zob:context:init`, `npm run zob:context:query`, and `npm run smoke:context-discovery`; starts exploratory/natural-language discovery with ColGREP when installed/ready, gives sessions without native `zob_context_search` a compact wrapper command before `rg`/`grep`, validates grep fallback when absent, and keeps broad grep/find away from `.pi/sessions` / `.pi/agent-sessions`.
 - `scripts/git-ops/` — governed `/zcommit` policy smokes.
 - `scripts/goal-todo/` — Goal/TODO tree compatibility smokes, including `scripts/goal-todo/handoff-static-smoke.mjs` coverage for the Goal TODO ZPeer/ZTeam handoff script (`npm run smoke:goal-todo-handoff`).
 - `scripts/harness-intake/` — natural-language harness setup/session analyzer that produces quarantined ZOB team/factory proposals plus tmux launch support.

package/scripts/context-discovery/query.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { detectColgrep, fallbackSearch, loadConfig, parseArgs, printHumanSearch, printJson } from "./shared.mjs";
+import { detectColgrep, fallbackSearch, loadConfig, normalizeColgrepResults, parseArgs, printHumanSearch, printJson } from "./shared.mjs";
 
 const args = parseArgs(process.argv.slice(2));
 const query = args.query ?? args.q ?? args._.join(" ");
@@ -32,15 +32,9 @@ if (colgrep.ready) {
   });
 
   if (colgrepResult.status === 0) {
-    result = {
-      provider: "colgrep",
-      fallback: false,
-      query,
-      resultCount: undefined,
-      raw: colgrepResult.stdout.trim(),
-      stderr: colgrepResult.stderr.trim(),
-      recommendedVerification: ["Use grep/read on returned repo-relative refs for exact proof."],
-    };
+    result = normalizeColgrepResults(colgrepResult.stdout, { query, config, maxResults, maxContextLines });
+    result.stderr = colgrepResult.stderr.trim().slice(0, 240);
+    result.colgrepArgs = colgrepArgs;
   } else {
     result = runFallback("colgrep-query-failed");
     result.colgrepQueryStatus = colgrepResult.status;
@@ -53,9 +47,6 @@ if (colgrep.ready) {
 
 if (args.json) {
   printJson(result);
-} else if (result.provider === "colgrep") {
-  console.log("provider: colgrep");
-  console.log(result.raw);
 } else {
   printHumanSearch(result);
 }

package/scripts/context-discovery/shared.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { basename, dirname, extname, join, normalize, relative, sep } from "node:path";
+import { basename, extname, isAbsolute, join, normalize, relative, sep } from "node:path";
 
 export const repoRoot = process.cwd();
 export const configPath = ".pi/context-discovery.json";
@@ -33,8 +33,8 @@ export const defaultConfig = {
     "build",
   ],
   limits: {
-    maxResults: 20,
-    maxContextLines: 2,
+    maxResults: 6,
+    maxContextLines: 1,
     maxFileBytes: 1024 * 1024,
   },
   promptInjection: {
@@ -126,13 +126,35 @@ export function parseArgs(argv) {
 }
 
 export function normalizeRepoPath(raw) {
-  const normalized = normalize(String(raw).replace(/^\.\//u, ""));
+  if (typeof raw !== "string" || raw.trim().length === 0 || raw.includes("\0") || raw.includes("\\")) {
+    return null;
+  }
+  const trimmed = raw.trim().replace(/^\.\//u, "");
+  if (isAbsolute(trimmed)) {
+    return null;
+  }
+  const normalized = normalize(trimmed);
   if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith(`..${sep}`)) {
     return null;
   }
   return normalized.split(sep).join("/");
 }
 
+export function normalizeBackendPath(raw) {
+  if (typeof raw !== "string" || raw.trim().length === 0 || raw.includes("\0")) {
+    return null;
+  }
+  const trimmed = raw.trim();
+  if (!isAbsolute(trimmed)) {
+    return normalizeRepoPath(trimmed);
+  }
+  const relPath = relative(repoRoot, trimmed);
+  if (!relPath || relPath === ".." || relPath.startsWith(`..${sep}`) || isAbsolute(relPath)) {
+    return null;
+  }
+  return normalizeRepoPath(relPath);
+}
+
 function globToRegExp(pattern) {
   const escaped = pattern
     .split("*")
@@ -141,7 +163,7 @@ function globToRegExp(pattern) {
   return new RegExp(`^${escaped}$`, "iu");
 }
 
-function isExcluded(relPath, excludePaths) {
+export function isExcluded(relPath, excludePaths) {
   const normalized = normalizeRepoPath(relPath);
   if (!normalized) {
     return true;
@@ -231,6 +253,51 @@ export function fallbackSearch({ query, config, maxResults, maxContextLines }) {
   };
 }
 
+export function normalizeColgrepResults(stdout, { query, config, maxResults, maxContextLines }) {
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    parsed = [];
+  }
+  const candidates = Array.isArray(parsed)
+    ? parsed
+    : parsed && typeof parsed === "object"
+      ? [parsed.results, parsed.matches, parsed.items].find(Array.isArray) ?? []
+      : [];
+  const results = [];
+  for (const item of candidates) {
+    if (!item || typeof item !== "object") continue;
+    const unit = item.unit && typeof item.unit === "object" ? item.unit : {};
+    const path = normalizeBackendPath(item.path ?? item.file ?? item.filename ?? item.source_path ?? unit.path ?? unit.file ?? unit.filename ?? unit.source_path);
+    if (!path || isExcluded(path, config.excludePaths) || !existsSync(join(repoRoot, path))) continue;
+    const lineValue = item.line ?? item.lineNumber ?? item.line_number ?? item.start_line ?? unit.line ?? unit.lineNumber ?? unit.line_number ?? unit.start_line;
+    const line = Number.isFinite(Number(lineValue)) ? Math.max(1, Math.floor(Number(lineValue))) : undefined;
+    const previewSource = item.preview ?? item.text ?? item.lineText ?? item.match ?? unit.docstring ?? unit.signature ?? unit.qualified_name ?? unit.name ?? path;
+    const preview = String(previewSource).replace(/\s+/gu, " ").trim().slice(0, 240);
+    results.push({
+      path,
+      line,
+      ref: line ? `${path}:${line}` : path,
+      preview,
+      score: Number.isFinite(Number(item.score)) ? Number(item.score) : undefined,
+    });
+    if (results.length >= maxResults) break;
+  }
+  return {
+    provider: "colgrep",
+    fallback: false,
+    query,
+    maxResults,
+    maxContextLines,
+    resultCount: results.length,
+    results,
+    recommendedVerification: results.length
+      ? [`read ${results[0].path}`, "After reading, grep exact identifiers/strings found in returned refs for final proof."]
+      : ["No compact ColGREP refs parsed; retry with a narrower query or inspect ColGREP status."],
+  };
+}
+
 export function printJson(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
@@ -242,6 +309,10 @@ export function printHumanSearch(result) {
   for (const item of result.results ?? []) {
     console.log(`- ${item.ref}: ${item.preview}`);
   }
+  const verification = Array.isArray(result.recommendedVerification) ? result.recommendedVerification.slice(0, 2) : [];
+  if (verification.length > 0) {
+    console.log(`verify: ${verification.join(" ; ")}`);
+  }
 }
 
 export function repoRelative(path) {

package/scripts/context-discovery/smoke.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 
 const env = { ...process.env, ZOB_CONTEXT_FORCE_FALLBACK: "1" };
 const result = spawnSync(process.execPath, ["scripts/context-discovery/query.mjs", "--query", "ZOB Harness", "--json", "--max-results", "5"], {
@@ -31,6 +32,62 @@ if (parsed.provider !== "grep-fallback" || parsed.fallback !== true || parsed.re
   process.exit(1);
 }
 
+const constantsSource = readFileSync(".pi/extensions/zob-harness/src/core/constants.ts", "utf8");
+const runtimeSource = readFileSync(".pi/extensions/zob-harness/src/domains/context/context-discovery.ts", "utf8");
+const querySource = readFileSync("scripts/context-discovery/query.mjs", "utf8");
+const sharedSource = readFileSync("scripts/context-discovery/shared.mjs", "utf8");
+const requiredPromptFragments = [
+  "For exploratory, natural-language",
+  "start with zob_context_search/ColGREP before grep/find",
+  "npm run --silent zob:context:query -- --query",
+  "Do not conclude the native tool is unavailable and immediately use broad rg/grep",
+  "Run one exploratory context search, then read the returned refs",
+  "Use grep/read after semantic discovery",
+  "Never run broad grep/find over .pi unless .pi/sessions and .pi/agent-sessions are explicitly excluded/pruned",
+  "unit?.file",
+  "normalizeBackendPath(repoRoot, rawPath)",
+];
+const requiredWrapperFragments = [
+  "normalizeColgrepResults",
+  "printHumanSearch(result)",
+];
+const requiredAsyncRuntimeFragments = [
+  "async function runColgrep",
+  "spawn(\"colgrep\"",
+  "export async function runContextSearch",
+  "await runColgrep",
+  "COLGREP_TIMEOUT_MS = 30_000",
+];
+const forbiddenWrapperFragments = [
+  "console.log(result.raw)",
+  "raw: colgrepResult.stdout",
+];
+const missingWrapperFragments = requiredWrapperFragments.filter((fragment) => !querySource.includes(fragment) && !sharedSource.includes(fragment));
+const missingAsyncRuntimeFragments = requiredAsyncRuntimeFragments.filter((fragment) => !runtimeSource.includes(fragment));
+const presentForbiddenWrapperFragments = forbiddenWrapperFragments.filter((fragment) => querySource.includes(fragment));
+const contextReadToolsLine = constantsSource.match(/ZOB_CONTEXT_READ_TOOLS = \[(?<tools>[^\]]+)\]/u)?.groups?.tools ?? "";
+if (!contextReadToolsLine.includes('"zob_context_search"')) {
+  console.error("context-discovery smoke FAIL: zob_context_search missing from ZOB_CONTEXT_READ_TOOLS native mode allowlist");
+  process.exit(1);
+}
+
+const missingPromptFragments = requiredPromptFragments.filter((fragment) => !runtimeSource.includes(fragment));
+if (missingPromptFragments.length > 0) {
+  console.error("context-discovery smoke FAIL: runtime prompt hardening fragments missing");
+  console.error(JSON.stringify({ missingPromptFragments }, null, 2));
+  process.exit(1);
+}
+if (missingWrapperFragments.length > 0 || presentForbiddenWrapperFragments.length > 0) {
+  console.error("context-discovery smoke FAIL: ColGREP wrapper compact-output contract broken");
+  console.error(JSON.stringify({ missingWrapperFragments, presentForbiddenWrapperFragments }, null, 2));
+  process.exit(1);
+}
+if (missingAsyncRuntimeFragments.length > 0) {
+  console.error("context-discovery smoke FAIL: native ColGREP execution must stay async/non-blocking");
+  console.error(JSON.stringify({ missingAsyncRuntimeFragments }, null, 2));
+  process.exit(1);
+}
+
 console.log("context-discovery smoke PASS");
 console.log(`provider=${parsed.provider} reason=${parsed.reason} results=${parsed.resultCount}`);
 console.log(`evidence=${parsed.results.find((entry) => typeof entry.path === "string")?.ref}`);