ultimate-pi 0.12.0 → 0.13.1

package/.agents/skills/ccc/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: ccc
+description: "This skill should be used when code search, file/directory summary lookup, or concept-guide lookup is needed (whether explicitly requested or as part of completing a task), when indexing the codebase after changes, or when the user asks about ccc, cocoindex-code, or the codebase index. Trigger phrases include 'search the codebase', 'find code related to', 'describe this file', 'read the concept guide', 'update the index', 'ccc', 'cocoindex-code'."
+---
+
+# ccc - Semantic Code Search & Indexing
+
+`ccc` is the CLI for CocoIndex Code, providing semantic search over the current codebase and index management.
+
+## Ownership
+
+The agent owns the `ccc` lifecycle for the current project — initialization, indexing, and searching. Do not ask the user to perform these steps; handle them automatically.
+
+- **Initialization**: If `ccc search` or `ccc index` fails with an initialization error (e.g., "Not in an initialized project directory"), run `ccc init` from the project root directory, then `ccc index` to build the index, then retry the original command.
+- **Index freshness**: Keep the index up to date by running `ccc index` (or `ccc search --refresh`) when the index may be stale — e.g., at the start of a session, or after making significant code changes (new files, refactors, renamed modules). There is no need to re-index between consecutive searches if no code was changed in between.
+- **Installation**: If `ccc` itself is not found (command not found), refer to [management.md](references/management.md) for installation instructions and inform the user.
+
+## Searching the Codebase
+
+To perform a semantic search:
+
+```bash
+ccc search <query terms>
+```
+
+The query should describe the concept, functionality, or behavior to find, not exact code syntax. For example:
+
+```bash
+ccc search database connection pooling
+ccc search user authentication flow
+ccc search error handling retry logic
+```
+
+### Filtering Results
+
+- **By language** (`--lang`, repeatable): restrict results to specific languages.
+
+  ```bash
+  ccc search --lang python --lang markdown database schema
+  ```
+
+- **By path** (`--path`): restrict results to a glob pattern relative to project root. If omitted, defaults to the current working directory (only results under that subdirectory are returned).
+
+  ```bash
+  ccc search --path 'src/api/*' request validation
+  ```
+
+### Pagination
+
+Results default to the first page. To retrieve additional results:
+
+```bash
+ccc search --offset 5 --limit 5 database schema
+```
+
+If all returned results look relevant, use `--offset` to fetch the next page — there are likely more useful matches beyond the first page.
+
+### Working with Search Results
+
+Search results include file paths and line ranges. To explore a result in more detail:
+
+- Use the editor's built-in file reading capabilities (e.g., the `Read` tool) to load the matched file and read lines around the returned range for full context.
+- When working in a terminal without a file-reading tool, use `sed -n '<start>,<end>p' <file>` to extract a specific line range.
+
+### Following Hints in Search Output
+
+Search results are a mixed ranking of code chunks, per-file/dir summaries, and (when configured) curated concept guides — all scored against the same query. Two kinds of hit come with a follow-up command embedded in the output:
+
+- `[summary]` — a file or directory summary. Read with `ccc describe <path>`.
+- `[guide]` — a curated concept guide. Read with `ccc guide <slug>`.
+
+When a hit carries one of these tags, follow the hint: the synthesised text is usually a faster read than chasing through individual files. Conversely, do **not** run `ccc describe .` or `ccc guide` proactively as a triage step — let search rank what's relevant and act on what it returns.
+
+## Describing Files and Directories
+
+Per-file and per-directory summaries (when configured for the project) condense each file's public API, contracts, and role into a short markdown block. They are typically faster to consult than reading the source.
+
+```bash
+ccc describe src/auth/session.py        # one file
+ccc describe src/auth/                  # directory: summary + children tree
+ccc describe .                          # project root overview
+```
+
+Use `describe` when you already know the path you want; let `ccc search` find paths for you when you don't.
+
+## Concept Guides
+
+Some projects configure cross-cutting concept guides in `.cocoindex_code/guides.yml` — synthesised markdown documents for architectural topics that span many files (e.g. memoization, plugin-SDK boundary, channel routing). Each guide names canonical files, end-to-end flow, and contracts/invariants.
+
+```bash
+ccc guide                               # list available guides + descriptions
+ccc guide <slug>                        # print one guide
+```
+
+Discovery is search-driven: a relevant guide will surface in `ccc search` results tagged `[guide]` with a `ccc guide <slug>` hint. Run `ccc guide` (no args) only when first orienting in an unfamiliar codebase or when the user explicitly asks for the guide list — not as a routine first step.
+
+### Authoring `guides.yml` Interactively
+
+When the user wants to add or improve concept guides, collaborate on the slug list rather than dumping a finished YAML. Good guide candidates are **named subsystems the codebase obviously has** — cross-cutting lifecycles, registration/dispatch protocols, end-to-end data paths. Single-file or symbol-specific topics do not warrant a guide; per-file summaries already cover those.
+
+Recommended flow:
+
+1. **Survey the codebase.** Use `ccc describe .` and a few likely subdirectory summaries to enumerate the project's subsystems and inter-edge boundaries.
+2. **Propose candidates.** Suggest 5–10 slugs with one-line descriptions, framed to name the canonical starting file or directory for each topic. Show them to the user as a list.
+3. **Iterate.** Ask which to keep, drop, rename, or merge. Surface non-obvious dependencies (`deps:`) so a higher-level guide can cite a lower-level one rather than restate it. Cycles are rejected at load time.
+4. **Write the YAML.** Add the agreed entries to `.cocoindex_code/guides.yml` (creating the file if absent). Confirm `defaults.enabled: true` and that the project's summary feature is enabled — guides require summaries.
+5. **Generate.** Run `ccc index` to drive the per-guide agent loop and produce `<slug>.md` files under `.cocoindex_code/guides/`. Re-run after editing descriptions to refresh.
+
+Schema:
+
+```yaml
+defaults:
+  enabled: true                     # disables all guides when false
+  model: openai/gpt-5.4-nano        # falls back to summary.model when omitted
+  session_budget: 200
+  max_logical_depth: 3
+  max_turns_per_session: 18
+
+guides:
+  - slug: memoization                          # [a-z0-9][a-z0-9-]*
+    description: |
+      What this guide covers, framed for the reader.
+      Name the canonical starting files (e.g. "start with src/cache.py").
+    deps: [other-slug]                         # optional; must not cycle
+    max_turns_per_session: 28                  # optional per-entry overrides
+```
+
+A multi-line description is fine and often clearer than one terse sentence — the description seeds the guide-generation agent's question, so concrete file/directory anchors pay off.
+
+## Settings
+
+To view or edit embedding model configuration, include/exclude patterns, or language overrides, see [settings.md](references/settings.md).
+
+## Management & Troubleshooting
+
+For installation, initialization, daemon management, troubleshooting, and cleanup commands, see [management.md](references/management.md).

package/.agents/skills/ccc/references/management.md

@@ -0,0 +1,110 @@
+# ccc Management
+
+## Installation
+
+Install CocoIndex Code via pipx. Two install styles:
+
+```bash
+pipx install 'cocoindex-code[full]'      # batteries included (local embeddings via sentence-transformers)
+pipx install cocoindex-code              # slim (LiteLLM-only; requires a cloud embedding provider + API key)
+```
+
+The `[full]` extra pulls in `sentence-transformers` so the first-run default (local embeddings, no API key) works out of the box. The slim install is for environments where you don't want the torch/transformers deps and plan to use a LiteLLM-supported cloud provider instead.
+
+To upgrade to the latest version:
+
+```bash
+pipx upgrade cocoindex-code
+```
+
+After installation, the `ccc` command is available globally.
+
+## Project Initialization
+
+Run from the root directory of the project to index:
+
+```bash
+ccc init
+```
+
+**First run (global settings don't exist yet)** — `ccc init` prompts interactively for the embedding provider (sentence-transformers / litellm) and model, then runs a one-off test embed via the daemon to confirm the model works. Accept the defaults for the sentence-transformers path, or pick litellm and enter a model identifier.
+
+**Subsequent runs** (global settings already exist) — prompts are skipped; only project settings and `.gitignore` are set up.
+
+To skip the interactive prompts on the first run (e.g. in a script or container), pass `--litellm-model MODEL`:
+
+```bash
+ccc init --litellm-model openai/text-embedding-3-small
+```
+
+This is also the only way to pick a LiteLLM model when stdin isn't a TTY and you've done a slim install.
+
+`ccc init` creates:
+- `~/.cocoindex_code/global_settings.yml` (user-level, embedding config + env vars).
+- `.cocoindex_code/settings.yml` (project-level, include/exclude patterns).
+
+If `.git` exists in the directory, `.cocoindex_code/` is automatically added to `.gitignore`.
+
+Use `-f` to skip the confirmation prompt if `ccc init` detects a potential parent project root.
+
+After initialization, edit the settings files if needed (see [settings.md](settings.md) for format details), then run `ccc index` to build the initial index. If the model test printed `[FAIL]` during `init`, edit `global_settings.yml` (and optionally add API keys under the commented `envs:` block) and verify with `ccc doctor` before indexing.
+
+## Troubleshooting
+
+### Diagnostics
+
+Run `ccc doctor` to check system health end-to-end:
+
+```bash
+ccc doctor
+```
+
+This checks global settings, daemon status, embedding model (runs a test embedding), and — if run from within a project — file matching (walks files using the same logic as the indexer) and index status. Results stream incrementally. Always points to `daemon.log` at the end for further investigation.
+
+### Checking Project Status
+
+To view the current project's index status:
+
+```bash
+ccc status
+```
+
+This shows whether indexing is ongoing and index statistics.
+
+### Daemon Management
+
+The daemon starts automatically on first use. To check its status:
+
+```bash
+ccc daemon status
+```
+
+This shows whether the daemon is running, its version, uptime, and loaded projects.
+
+To restart the daemon (useful if it gets into a bad state):
+
+```bash
+ccc daemon restart
+```
+
+To stop the daemon:
+
+```bash
+ccc daemon stop
+```
+
+## Cleanup
+
+To reset a project's index (removes databases, keeps settings):
+
+```bash
+ccc reset
+```
+
+To fully remove all CocoIndex Code data for a project (including settings):
+
+```bash
+ccc reset --all
+```
+
+Both commands prompt for confirmation. Use `-f` to skip.

package/.agents/skills/ccc/references/settings.md

@@ -0,0 +1,126 @@
+# ccc Settings
+
+Configuration lives in two YAML files, both created automatically by `ccc init`.
+
+## User-Level Settings (`~/.cocoindex_code/global_settings.yml`)
+
+Shared across all projects. Controls the embedding model and extra environment variables for the daemon.
+
+```yaml
+embedding:
+  provider: sentence-transformers   # or "litellm" (default when provider is omitted)
+  model: Snowflake/snowflake-arctic-embed-xs
+  device: mps                       # optional: cpu, cuda, mps (auto-detected if omitted)
+  min_interval_ms: 300              # optional: pace LiteLLM embedding requests to reduce 429s; defaults to 5 for LiteLLM
+
+envs:                               # extra environment variables for the daemon
+  OPENAI_API_KEY: your-key          # only needed if not already in the shell environment
+```
+
+### Fields
+
+| Field | Description |
+|-------|-------------|
+| `embedding.provider` | `sentence-transformers` for local models, `litellm` (or omit) for cloud/remote models |
+| `embedding.model` | Model identifier — format depends on provider (see examples below) |
+| `embedding.device` | Optional. `cpu`, `cuda`, or `mps`. Auto-detected if omitted. Only relevant for `sentence-transformers`. |
+| `embedding.min_interval_ms` | Optional. Minimum delay between LiteLLM embedding requests in milliseconds. Defaults to `5` for LiteLLM and is ignored by `sentence-transformers`. Set explicitly to override the default. |
+| `envs` | Key-value map of environment variables injected into the daemon. Use for API keys not already in the shell environment. |
+
+### Embedding Model Examples
+
+**Local (sentence-transformers, no API key needed):**
+
+```yaml
+embedding:
+  provider: sentence-transformers
+  model: Snowflake/snowflake-arctic-embed-xs        # default, lightweight
+```
+
+```yaml
+embedding:
+  provider: sentence-transformers
+  model: nomic-ai/CodeRankEmbed                     # better code retrieval, needs GPU (~1 GB VRAM)
+```
+
+**Ollama (local):**
+
+```yaml
+embedding:
+  model: ollama/nomic-embed-text
+```
+
+**OpenAI:**
+
+```yaml
+embedding:
+  model: text-embedding-3-small
+  min_interval_ms: 300
+envs:
+  OPENAI_API_KEY: your-api-key
+```
+
+**Gemini:**
+
+```yaml
+embedding:
+  model: gemini/gemini-embedding-001
+envs:
+  GEMINI_API_KEY: your-api-key
+```
+
+**Voyage (code-optimized):**
+
+```yaml
+embedding:
+  model: voyage/voyage-code-3
+envs:
+  VOYAGE_API_KEY: your-api-key
+```
+
+For the full list of supported cloud providers and model identifiers, see [LiteLLM Embedding Models](https://docs.litellm.ai/docs/embedding/supported_embedding).
+
+### Important
+
+Switching embedding models changes vector dimensions — you must re-index after changing the model:
+
+```bash
+ccc reset && ccc index
+```
+
+## Project-Level Settings (`<project>/.cocoindex_code/settings.yml`)
+
+Per-project. Controls which files to index. Created by `ccc init` and automatically added to `.gitignore`.
+
+```yaml
+include_patterns:
+  - "**/*.py"
+  - "**/*.js"
+  - "**/*.ts"
+  # ... (sensible defaults for 28+ file types)
+
+exclude_patterns:
+  - "**/.*"              # hidden directories
+  - "**/__pycache__"
+  - "**/node_modules"
+  - "**/dist"
+  # ...
+
+language_overrides:
+  - ext: inc             # treat .inc files as PHP
+    lang: php
+```
+
+### Fields
+
+| Field | Description |
+|-------|-------------|
+| `include_patterns` | Glob patterns for files to index. Defaults cover common languages (Python, JS/TS, Rust, Go, Java, C/C++, C#, SQL, Shell, Markdown, PHP, Lua, etc.). |
+| `exclude_patterns` | Glob patterns for files/directories to skip. Defaults exclude hidden dirs, `node_modules`, `dist`, `__pycache__`, `vendor`, etc. |
+| `language_overrides` | List of `{ext, lang}` pairs to override language detection for specific file extensions. |
+
+### Editing Tips
+
+- To index additional file types, append glob patterns to `include_patterns` (e.g. `"**/*.proto"`).
+- To exclude a directory, append to `exclude_patterns` (e.g. `"**/generated"`).
+- After editing, run `ccc index` to re-index with the new settings.

package/.agents/skills/harness-orchestration/SKILL.md

@@ -36,7 +36,7 @@ LIMIT 30
 1. **Parallel `tasks`** — one `subagent({ tasks: [...] })` for scouts, decompose+hypothesis, or review fan-in; subprocesses run in parallel upstream.
 2. **Blocking calls** — each `subagent` returns when the subprocess exits; no `get_subagent_result` polling.
 3. **Compact handoffs** — pass scout/decompose JSON only; never paste full subprocess message logs into the next spawn.
-4. **Spawn caps** — bridge enforces **8** active + **12** total harness spawns per session (`PI_SUBAGENT_TIMEOUT_MS` / per-task `timeoutMs` for backstop).
+4. **Spawn caps** — bridge enforces **8** active + **12** total harness spawns per session. Do **not** pass `timeoutMs` unless the user wants a cap — subprocesses wait for natural exit (`PI_SUBAGENT_TIMEOUT_MS` optional env backstop only).
 
 ## Command → agent
 
@@ -71,9 +71,9 @@ Spawn `harness/evaluator` / `harness/adversary` via `subagent` in the **same** p
 {
   "agentScope": "both",
   "tasks": [
-    { "agent": "harness/planning/scout-graphify", "task": "…", "timeoutMs": 90000 },
-    { "agent": "harness/planning/scout-structure", "task": "…", "timeoutMs": 90000 },
-    { "agent": "harness/planning/scout-semantic", "task": "…", "timeoutMs": 90000 }
+    { "agent": "harness/planning/scout-graphify", "task": "…" },
+    { "agent": "harness/planning/scout-structure", "task": "…" },
+    { "agent": "harness/planning/scout-semantic", "task": "…" }
   ]
 }
 ```

package/.pi/PACKAGING.md

@@ -24,6 +24,7 @@ We use an explicit allowlist (not the whole `.pi/` tree) so dev-only artifacts n
 - Ship `.pi/settings.example.json`, not `.pi/settings.json` (dev checkout uses `".."` local package)
 - Include **`vendor/pi-model-router/`** ([`pi-model-router`](https://github.com/yeliu84/pi-model-router), MIT) — see repo [`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md); refresh with `npm run vendor:sync-router`
 - Include **`vendor/pi-vcc/`** ([`pi-vcc`](https://github.com/sting8k/pi-vcc), MIT; inspired by [lllyasviel/VCC](https://github.com/lllyasviel/VCC)) — loaded via `.pi/extensions/ultimate-pi-vcc.ts`; refresh with `npm run vendor:sync-vcc`
+- Include **`vendor/pi-subagents/`** (vendored from [narumiruna/pi-extensions](https://github.com/narumiruna/pi-extensions) `pi-subagents`) — loaded via `.pi/extensions/harness-subagents.ts`; refresh with `npm run vendor:sync-subagents`
 
 ## Settings
 

package/.pi/SYSTEM.md

@@ -81,41 +81,42 @@ edges at build time. Use these to answer call-graph questions without external t
 - **How does `Auth` reach `Database`?** → `graphify path "Auth" "Database"` (shortest call chain)
 - **Trace a dependency chain deep** → `graphify query "how does X depend on Y" --dfs`
 
-**Semantic code search via graphify:**
-Graphify already indexes the entire codebase as a knowledge graph. Use graphify
-for conceptual code search before falling back to `ck`:
-- **Find code by meaning** → `graphify query "where is authentication logic"`
-- **Find related concepts** → `graphify query "what connects to error handling"`
+**Semantic code search (two lanes):**
+- **Architecture / relationships** → graphify (`query`, `explain`, `path`, `GRAPH_REPORT.md`)
+- **Implementation by meaning** → CocoIndex Code (`ccc search --limit N "concept"`)
+
+Examples:
+- **Find code by meaning** → `ccc search --limit 10 "authentication session validation"`
+- **Who calls X / cross-module path** → `graphify explain "X"` or `graphify path "A" "B"`
 - **Cross-file surprises** → `graphify query "what unexpected connections exist"`
 
 **Order of operations for codebase exploration:**
 1. Read `graphify-out/GRAPH_REPORT.md` (god nodes, surprises, suggested questions)
-2. Run `graphify query` for domain-specific questions, call traces, and semantic search
-3. Use `graphify explain "Concept"` for caller/callee/dependency deep dives
-4. Use `sg -p 'pattern'` for structural code search, then `ck --hybrid` only if graph and ast-grep don't surface it
-5. Read individual files last — the graph already told you what matters
+2. Run `graphify query` / `explain` / `path` for architecture and call graphs
+3. Use `sg -p 'pattern'` for structural code search
+4. Use `ccc search --limit N` for conceptual implementation chunks when graphify/sg are insufficient
+5. Read individual files last — scouts and graph already narrowed the set
+
+**Indexing:** Harness runs incremental `ccc index` before subagent spawns. Use `ccc search` only in agents; run `ccc index` at session start or after large edits on parent turns. Never use `ccc search --refresh` in scouts. `/skill:ccc` for full CLI reference.
 
 ### Fallback Search (when graph doesn't cover it)
 
-> [!note] Graphify handles semantic search and call graphs
-> Graphify already provides semantic code search and call-graph tracing. Use
-> `graphify query`, `graphify explain`, and `graphify path` as your primary
-> code exploration tools. Only fall back to `sg`/`ck`/`find` when the graph
-> doesn't have the answer (e.g., not yet indexed, or you need exact raw text).
+> [!note] Graphify + ccc split responsibilities
+> Graphify owns call graphs and cross-module relationships. `ccc` owns AST-aware
+> semantic chunks. Only fall back to `find`/`grep` for exact literals or non-code files.
 
 | Tool | When | Command |
 |------|------|---------|
-| `sg -p` | **Primary code search** — AST-aware structural pattern matching | `sg -p 'pattern' --lang typescript` |
+| `sg -p` | **Structural code search** — AST pattern matching | `sg -p 'pattern' --lang typescript` |
 | `sg scan` | Rule-based code scanning (use project rules in `sgconfig.yml`) | `sg scan` |
-| `ck --hybrid` | Lexical + semantic fusion search (fallback after ast-grep) | `ck --hybrid "query" .` |
-| `ck --sem` | Purely conceptual searches (fallback after ast-grep) | `ck --sem "concept" src/` |
+| `ccc search` | **Semantic chunks** — implementation by meaning | `ccc search --limit 10 "query"` |
 | `find` | File discovery by name/glob only | `find . -name "*.ts"` |
 | `grep` | **Last resort** — exact literal string matching in non-code files only | `grep -F "exact string"` |
 
-- **Always prefer ast-grep (`sg`) over grep for code search.** ast-grep understands code structure via tree-sitter — it matches patterns, not strings. Use it for: finding function calls, class definitions, import statements, variable usage, and any structural code query.
+- **Always prefer ast-grep (`sg`) over grep for code search.** ast-grep understands code structure via tree-sitter — it matches patterns, not strings.
 - Never use grep for code search. grep is only for: log files, non-code text files, exact byte-level matching when AST patterns can't work.
-- Always use `--limit N` on ck to cap output and save context.
-- Graphify is primary. ast-grep is secondary. ck/find are fallbacks. grep is last resort.
+- Always use `--limit N` on `ccc search` to cap output and save context.
+- Graphify is primary for architecture. ast-grep is secondary for structure. ccc is semantic implementation search. grep is last resort.
 - Do NOT install or use grepai/seagoat/mgrep for call-graph traces or semantic
   search — graphify already handles both.
 

package/.pi/agents/harness/planning/scout-graphify.md

@@ -15,6 +15,8 @@ Explore the codebase via graphify for the task in `HarnessSpawnContext`. You do
 
 Findings should feed **constraints, prior art, and tensions** for the decompose agent (existing patterns, god nodes, surprising connections).
 
+**Lane contract:** you own **relationships and architecture** (`graphify query`, `explain`, `path`). `scout-semantic` owns implementation-by-meaning via `ccc search` — do not duplicate semantic chunk search here.
+
 ## Spawn context
 
 Read `HarnessSpawnContext` in the spawn prompt (`task_summary`, `mode`, `plan_packet_path`, `risk_level`, `quick`). For `mode: revise`, read the existing plan at `plan_packet_path` first and focus findings on what changed or is at risk.

package/.pi/agents/harness/planning/scout-semantic.md

@@ -1,5 +1,5 @@
 ---
-description: Plan-phase scout — ck semantic code search (read-only).
+description: Plan-phase scout — CocoIndex semantic code search (read-only).
 tools: read, bash, ls
 disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent, grep, find
 extensions: false
@@ -11,7 +11,9 @@ You are the **Harness planning scout (semantic lane)**.
 
 ## Mission
 
-Find conceptually related code via ck semantic search for the task in `HarnessSpawnContext`. You do **not** build the PlanPacket or mutate files.
+Find conceptually related **implementation** via CocoIndex (`ccc search`) for the task in `HarnessSpawnContext`. You do **not** build the PlanPacket or mutate files.
+
+**Lane contract:** `scout-graphify` owns relationships, callers, and communities. You own **meaning** — functions, classes, and chunks that implement the task.
 
 ## Spawn context
 
@@ -19,13 +21,18 @@ Read `HarnessSpawnContext` in the spawn prompt. For `mode: revise`, bias searche
 
 ## Process
 
-1. Use `ck search` or `ck query` (or project-documented ck CLI) with task-focused queries.
-2. If ck is unavailable, set `status: partial` and document in `findings`.
-3. **Stop early** — top **5** most relevant paths only.
+1. Run **2–3** task-focused queries: `ccc search "<query>" --limit 5` (add `--path` when spawn context names a directory).
+2. The harness runs incremental `ccc index` before scouts spawn — **do not** run `ccc index`, `ccc init`, or `ccc search --refresh`.
+3. If `ccc` is missing or the index is empty: `status: partial` and document in `findings`.
+4. **Stop early** — top **5** most relevant paths only.
 
 ## Bash guardrails
 
-Read-only only: no installs, index rebuilds that mutate disk, or redirects.
+Read-only only: no installs, indexing, daemon control, or redirects.
+
+**Allowed:** `ccc search`, `ccc status`, `ls`, `head`, `cat`, `sed -n` (read slices).
+
+**Forbidden:** `ccc index`, `ccc init`, `ccc reset`, `ccc daemon`, `ccc search --refresh`, package installs.
 
 ## Output limits
 

package/.pi/extensions/harness-run-context.ts

@@ -55,6 +55,10 @@ import {
 	parseStructuredDocument,
 	writeYamlFile,
 } from "../lib/harness-yaml.js";
+import { claimExtensionLoad } from "./lib/extension-load-guard.js";
+
+// @ts-expect-error pi extensions run as ESM
+const MODULE_URL = import.meta.url;
 
 interface SessionEntryLike {
 	type?: string;
@@ -191,6 +195,7 @@ function needsClarificationFollowUp(ctx: HarnessRunContext | null): boolean {
 }
 
 export default function harnessRunContext(pi: ExtensionAPI) {
+	if (!claimExtensionLoad("harness-run-context", MODULE_URL)) return;
 	let activeCtx: HarnessRunContext | null = null;
 
 	pi.on("session_start", async (_event, ctx) => {

package/.pi/extensions/harness-subagents.ts

@@ -1,14 +1,25 @@
 /**
  * harness-subagents — vendored pi-subagents with ultimate-pi discovery and policy gates.
+ *
+ * Dynamic-imports the bridge only after claimExtensionLoad so a stale global npm
+ * install (missing vendor/pi-subagents) does not crash local development in this repo.
  */
 
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { claimExtensionLoad } from "./lib/extension-load-guard.js";
-import { getHarnessPackageRoot } from "./lib/harness-paths.js";
-import { createHarnessSubagentsExtension } from "./lib/harness-subagents-bridge.js";
 
 // @ts-expect-error pi extensions run as ESM
 const MODULE_URL = import.meta.url;
 
-export default claimExtensionLoad("harness-subagents", MODULE_URL)
-	? createHarnessSubagentsExtension(getHarnessPackageRoot(MODULE_URL))
-	: () => {};
+async function loadHarnessSubagents(): Promise<(pi: ExtensionAPI) => void> {
+	if (!claimExtensionLoad("harness-subagents", MODULE_URL)) {
+		return () => {};
+	}
+	const { getHarnessPackageRoot } = await import("./lib/harness-paths.js");
+	const { createHarnessSubagentsExtension } = await import(
+		"./lib/harness-subagents-bridge.js"
+	);
+	return createHarnessSubagentsExtension(getHarnessPackageRoot(MODULE_URL));
+}
+
+export default await loadHarnessSubagents();

package/.pi/extensions/lib/harness-cocoindex-refresh.ts

@@ -0,0 +1,49 @@
+/**
+ * Incremental CocoIndex refresh before harness subagent batches (plan/execute).
+ * Agents use `ccc search` only; harness owns `ccc index`.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export function refreshHarnessCocoindexIndex(cwd: string): string | undefined {
+	if (process.env.HARNESS_COCOINDEX_REFRESH === "0") {
+		return undefined;
+	}
+	const settingsPath = join(cwd, ".cocoindex_code", "settings.yml");
+	if (!existsSync(settingsPath)) {
+		return undefined;
+	}
+
+	const timeoutMs = Number(
+		process.env.HARNESS_COCOINDEX_REFRESH_TIMEOUT_MS ?? DEFAULT_TIMEOUT_MS,
+	);
+	const result = spawnSync("ccc", ["index"], {
+		cwd,
+		encoding: "utf8",
+		timeout: Number.isFinite(timeoutMs) ? timeoutMs : DEFAULT_TIMEOUT_MS,
+		stdio: "pipe",
+	});
+
+	if (result.error) {
+		const msg = `harness-cocoindex: ccc index failed (${result.error.message})`;
+		if (process.env.HARNESS_COCOINDEX_REFRESH_STRICT === "1") {
+			return msg;
+		}
+		return `${msg} — continuing`;
+	}
+
+	if (result.status !== 0) {
+		const stderr = (result.stderr ?? "").trim().slice(0, 500);
+		const msg = `harness-cocoindex: ccc index exited ${result.status ?? "?"}${stderr ? `: ${stderr}` : ""}`;
+		if (process.env.HARNESS_COCOINDEX_REFRESH_STRICT === "1") {
+			return msg;
+		}
+		return `${msg} — continuing`;
+	}
+
+	return undefined;
+}

package/.pi/extensions/lib/harness-subagent-policy.ts

@@ -24,9 +24,13 @@ const PLANNING_BASH_DENY_PATTERNS = [
 	/\bgraphify\s+update\b/i,
 	/\bgraphify\s+extract\b/i,
 	/\bgraphify\s+install\b/i,
+	/\bccc\s+(index|init|reset|daemon)\b/i,
+	/\bccc\s+search\b.*--refresh/i,
 	/\bpip\s+install\b/i,
 	/\buv\s+tool\s+install\b/i,
 	/\bnpm\s+install\b/i,
+	/\bnpm\s+install\b.*cocoindex/i,
+	/\buv\s+tool\s+install\b.*cocoindex/i,
 ];
 
 const BASH_MUTATION_PATTERNS = [
@@ -141,7 +145,7 @@ export function evaluateHarnessSubagentToolCall(
 			return {
 				action: "block",
 				reason:
-					"harness-subagent-policy: planning scouts may use read-only graphify/sg/ck commands only.",
+					"harness-subagent-policy: planning scouts may use read-only graphify/sg/ccc commands only.",
 			};
 		}
 	}