@openlines/opl-pi-sht 0.2.0 → 0.2.2

package/README.md

@@ -71,11 +71,12 @@ Copy mode overwrites matching destinations. Link mode skips existing destination
 
 | Extension                                                     | Summary                                                                                                                                                                                                                      | Commands, tools, and configuration                                                                             |
 | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| [`opl-init`](extensions/opl-init/README.md)                   | Fingerprinted repository-guide generator.                                                                                                                                                                                    | `/init [--refine]`; no config.                                                                                            |
+| [`opl-init`](extensions/opl-init/README.md)                   | Fingerprinted repository-guide generator with out-of-band model refinement.                                                                                                                                                  | `/init`; no config.                                                                                             |
 | [`opl-simplebench`](extensions/opl-simplebench/README.md)     | Auditable provider-aware model benchmark with JSON artifacts and metrics.                                                                                                                                                    | `/simplebench`, `simplebench`; supports Ollama, OpenAI-compatible providers, and Bedrock; optional `opl-simplebench.json`. |
 | [`opl-webaccess`](extensions/opl-webaccess/README.md)         | Search plus readable URL/PDF retrieval with session recovery.                                                                                                                                                                | `web_search`, `fetch_content`, `get_search_content`; `opl-webaccess.json`.                                     |
 | [`opl-browser`](extensions/opl-browser/README.md)             | Chromium automation via Playwright with structured extraction of rendered pages; single dispatcher tool replacing the chrome-devtools MCP.                                                                                   | `browser` (action-based); `opl-browser.json`.                                                                  |
 | [`opl-ctxtrim`](extensions/opl-ctxtrim/README.md)             | Trims verbose`ctx_*` tool-schema descriptions on outbound provider requests (~67% smaller schema, ~4,700-6,300 tokens/request). Built specifically for the [context-mode](https://github.com/mksglu/context-mode) extension. | No commands/tools; no config.                                                                                  |
+| [`opl-guardian`](extensions/opl-guardian/README.md)           | Drops malformed assistant tool calls before session persistence or replay, with project-local JSONL evidence. | No commands/tools; no config.                                                                                  |
 | [`opl-todo`](extensions/opl-todo/README.md)                   | Branch-aware task tool, overlay, and task list.                                                                                                                                                                              | `todo`, `/todos`; `opl-todo.json`.                                                                             |
 | [`opl-questionnaire`](extensions/opl-questionnaire/README.md) | Interactive structured-choice tool.                                                                                                                                                                                          | `questionnaire`; no config.                                                                                    |
 | [`opl-input`](extensions/opl-input/README.md)                 | Configurable replacement editor - enhanced [pikit chat-input](https://github.com/adrianapan/pikit) (because pet is life, and configurable). ![pet](images/ss-input-pet.png)                                                                                   | No commands/tools;`opl-input.json`.                                                                            |
@@ -107,11 +108,12 @@ Cold prompt-cache write, measured /init session (opl-modes lazy tools + MCP adap
 - **`opl-modes`** chat and plan modes swap the active toolset for read-only lists and gate Bash to safe inspection patterns **per shell segment**, so `cat f && node -e '...'`, `cat x & rm -rf /tmp/x`, and `echo "$(node -e ...)"` can no longer ride the first command's allowance. Destructive checks still fire inside otherwise-safe commands (anchored to command position, so `du -sh` and `find . -name '*.sh'` stay allowed; `find -delete`, `find -fprint`, `git log --output`, `sort -o`, `npm audit fix`, `git clean`, `sudo`, and quote-obfuscated `r"m"`/`-del"ete"` are blocked; `env`/`printenv` are not safe-listed). The plan to execute lifecycle keeps exploration and mutation cleanly separated. Add custom modes (like below) for your workflow needs.
 ![custom mode sample](images/ss-mode-custom.png)
 - `load_tools` activation is bounded by the current mode, so a read-only mode cannot be tricked into enabling a write-capable tool.
+- **`opl-guardian`** stops a malformed provider tool-call record from poisoning the session: it removes calls missing an ID or name before Pi persists or replays them, while preserving dropped records in `err/guardian.jsonl` for an upstream report.
 
 
 ### Move through work faster
 
-- **`opl-init`** deterministically writes a fingerprinted `AGENTS.md` so any agent starts already oriented in a repo. It refreshes only when the tree changes, overwriting a stale guide outright, and plain `/init` never sends a synthetic user message; `/init --refine` is the opt-in single request for a model-expanded guide, meant for session start or just before a push, not mid-task.
+- **`opl-init`** deterministically crawls and refines `AGENTS.md` with a single out-of-band model call (never a synthetic user message), writes it, and reloads context so the session runs on the new guide. A current fingerprint means zero model calls; mid-session invocations wait for the agent to settle instead of interrupting it. Needs pi >= 0.86.0.
 ![init](images/ss-init.png)
 - **`opl-browser`** gives full Chromium automation (navigate, snapshot, extract rendered-page markdown, interact, screenshot, console/network capture, evaluate) through a single tool, with handle+preview output for large results — navigation is http(s)-only and screenshots stay in the project directory.
 - **`opl-webaccess`** adds provider-backed search plus readable URL and PDF extraction, with session recovery of earlier results, an http(s)-only fetch, a 10 MB response cap, and a 30s timeout.
@@ -137,7 +139,7 @@ Cold prompt-cache write, measured /init session (opl-modes lazy tools + MCP adap
 | If you want to...                  | Install                                                         |
 | ---------------------------------- | --------------------------------------------------------------- |
 | Cut token cost with minimal change | `opl-ctxtrim`, `opl-modes`                                      |
-| Run the agent safely on real repos | `opl-modes` (pulls in the `opl-input` + `opl-footer` UI bundle) |
+| Run the agent safely on real repos | `opl-modes` (pulls in the `opl-input` + `opl-footer` UI bundle), `opl-guardian` |
 | Research and drive the web         | `opl-webaccess`, `opl-browser`                                  |
 | Choose models with data            | `opl-simplebench`                                               |
 | The full, coordinated experience   | all ten                                                         |
@@ -161,6 +163,7 @@ Installing extensions adds tool schemas (name + description + JSON parameters) t
 | `opl-init` | command only (no tool) | ~0 |
 | `opl-input` | UI only | ~0 |
 | `opl-footer` | UI only | ~0 |
+| `opl-guardian` | none (session-integrity guard) | ~0 |
 | `opl-ctxtrim` | none (payload transformer) | net negative |
 
 Command descriptions add roughly another ~120 tokens collectively, and only if your build surfaces them in the prompt or help block.
@@ -218,4 +221,4 @@ A Pi package (npm or Git) still needs the one-time `npx playwright install chrom
 npm test
 ```
 
-Run one extension suite with `npm run test:opl-<name>` for `browser`, `footer`, `init`, `input`, `modes`, `questionnaire`, `todo`, `webaccess`, `simplebench`, or `ctxtrim`. Every helper, functional, and selected-entrypoint smoke check uses Bun's named-test reporter; output includes per-test status, timings, and pass/fail totals. Functional tests cover deterministic helpers where practical; smoke tests bundle entrypoints and parse config. They do not test live TUI behavior, provider credentials, network access, or PDF extraction.
+Run one extension suite with `npm run test:opl-<name>` for `browser`, `footer`, `guardian`, `init`, `input`, `modes`, `questionnaire`, `todo`, `webaccess`, `simplebench`, or `ctxtrim`. Every helper, functional, and selected-entrypoint smoke check uses Bun's named-test reporter; output includes per-test status, timings, and pass/fail totals. Functional tests cover deterministic helpers where practical; smoke tests bundle entrypoints and parse config. They do not test live TUI behavior, provider credentials, network access, or PDF extraction.

package/extensions/opl-guardian/README.md

@@ -0,0 +1,52 @@
+# opl-guardian
+
+Prevents malformed assistant tool calls from entering Pi session history. It runs on every provider and model through Pi's `message_end` hook, removes protocol-invalid calls before Pi persists or replays them, and records each removal as JSON Lines evidence.
+
+>
+> This is the first feature that opl-guardian can do for now. If I happen to encounter another error/issue that can be (possibly) fixed via extensions, I might add that up in this extension.
+>
+
+## Commands, tools, and configuration
+
+No commands, tools, or configuration. Loading the extension is the entire interface and adds no prompt or tool-schema overhead.
+
+## What it guards
+
+A tool call is malformed when its `id` or `name` is blank after trimming whitespace. Such a record cannot be safely replayed through OpenAI-compatible tool-call APIs: a later provider request may reject it and block the session until its history is abandoned.
+
+`opl-guardian` does not reject an unfamiliar but non-empty tool name. That is a normal model/tool-resolution error, not an invalid protocol envelope.
+
+| Assistant response | Guardian behavior |
+| --- | --- |
+| No malformed calls | Leaves the response unchanged. |
+| Valid and malformed calls | Drops only malformed calls, preserves valid calls and `toolUse`, appends a diagnostic, and lets Pi execute the valid calls normally. |
+| Only malformed calls | Removes every call, returns a text-only `stop` response, and tells the user to send another prompt. |
+
+When a UI is available, every incident also produces a warning notification.
+
+## Forensic JSONL
+
+Each incident appends one JSON object to:
+
+```text
+<project cwd>/err/guardian.jsonl
+```
+
+A record includes timestamp, session ID, project CWD, provider, model, response ID when available, and the removed `toolCall` blocks. It does not log prompts, assistant text, thinking, or tool results.
+
+Tool-call arguments can still contain project paths, commands, or user text. Add `err/` to the project’s version-control ignore policy if it is not already ignored, and treat the file as local diagnostic data.
+
+If the log write fails, guardian still removes the malformed calls. The session diagnostic and UI warning report that the forensic file could not be written rather than claiming it was saved.
+
+## Architecture
+
+```text
+guardian.ts  Pure malformed-call filter and JSONL incident-record builder.
+index.ts     Pi message_end handler, project-local JSONL append, UI notification.
+```
+
+The extension has no runtime dependencies. Run its checks with:
+
+```bash
+npm run test:opl-guardian
+```

package/extensions/opl-guardian/guardian.ts

@@ -0,0 +1,70 @@
+import type { AssistantMessage, ToolCall } from "@earendil-works/pi-ai";
+
+export interface IncidentContext {
+  sessionId: string;
+  cwd: string;
+}
+
+export interface GuardianIncident {
+  timestamp: string;
+  kind: "malformed_tool_call";
+  sessionId: string;
+  cwd: string;
+  provider: string;
+  model: string;
+  responseId?: string;
+  action: "dropped";
+  removedToolCalls: ToolCall[];
+}
+
+export interface GuardResult {
+  message: AssistantMessage;
+  removedToolCalls: ToolCall[];
+}
+
+function hasValue(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export function isMalformedToolCall(block: unknown): block is ToolCall {
+  if (!block || typeof block !== "object" || (block as { type?: unknown }).type !== "toolCall") {
+    return false;
+  }
+  const toolCall = block as ToolCall;
+  return !hasValue(toolCall.id) || !hasValue(toolCall.name);
+}
+
+export function guardAssistantMessage(message: AssistantMessage): GuardResult | undefined {
+  const removedToolCalls = message.content.filter(isMalformedToolCall);
+  if (removedToolCalls.length === 0) return undefined;
+
+  const content = message.content.filter((block) => !isMalformedToolCall(block));
+  const hasValidToolCall = content.some((block) => block.type === "toolCall");
+
+  return {
+    removedToolCalls,
+    message: {
+      ...message,
+      content,
+      stopReason: hasValidToolCall ? "toolUse" : "stop",
+    },
+  };
+}
+
+export function buildIncidentRecord(
+  message: AssistantMessage,
+  context: IncidentContext,
+  removedToolCalls: ToolCall[],
+): GuardianIncident {
+  return {
+    timestamp: new Date(message.timestamp).toISOString(),
+    kind: "malformed_tool_call",
+    sessionId: context.sessionId,
+    cwd: context.cwd,
+    provider: message.provider,
+    model: message.model,
+    ...(message.responseId ? { responseId: message.responseId } : {}),
+    action: "dropped",
+    removedToolCalls,
+  };
+}

package/extensions/opl-guardian/index.ts

@@ -0,0 +1,81 @@
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { appendFile, chmod, mkdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  buildIncidentRecord,
+  guardAssistantMessage,
+  type GuardianIncident,
+} from "./guardian.js";
+
+const LOG_PATH = join("err", "guardian.jsonl");
+
+export async function appendIncident(cwd: string, incident: GuardianIncident): Promise<void> {
+  const directory = join(cwd, "err");
+  const path = join(cwd, LOG_PATH);
+  await mkdir(directory, { recursive: true });
+
+  let existed = true;
+  try {
+    await stat(path);
+  } catch {
+    existed = false;
+  }
+
+  await appendFile(path, `${JSON.stringify(incident)}\n`, "utf8");
+  if (!existed && process.platform !== "win32") {
+    await chmod(path, 0o600).catch(() => {});
+  }
+}
+
+function diagnostic(removed: number, logError?: unknown): string {
+  if (logError) {
+    const detail = logError instanceof Error ? logError.message : String(logError);
+    return `[opl-guardian] Dropped malformed provider tool call(s), but could not write err/guardian.jsonl: ${detail}.`;
+  }
+  return `[opl-guardian] Dropped ${removed} malformed provider tool call(s). Details: err/guardian.jsonl.`;
+}
+
+function appendDiagnostic(message: AssistantMessage, text: string, invalidOnly: boolean): AssistantMessage {
+  const content = invalidOnly
+    ? [{ type: "text" as const, text: `${text} No tool was executed; send another prompt to continue.` }]
+    : [...message.content, { type: "text" as const, text }];
+  return { ...message, content, stopReason: invalidOnly ? "stop" : "toolUse" };
+}
+
+export async function guardMessageEnd(
+  message: AssistantMessage,
+  context: { cwd: string; sessionId: string },
+): Promise<{ message: AssistantMessage; diagnostic: string } | undefined> {
+  const guarded = guardAssistantMessage(message);
+  if (!guarded) return undefined;
+
+  let logError: unknown;
+  try {
+    await appendIncident(context.cwd, buildIncidentRecord(message, context, guarded.removedToolCalls));
+  } catch (error) {
+    logError = error;
+  }
+
+  const invalidOnly = !guarded.message.content.some((block) => block.type === "toolCall");
+  const notice = diagnostic(guarded.removedToolCalls.length, logError);
+  return {
+    message: appendDiagnostic(guarded.message, notice, invalidOnly),
+    diagnostic: notice,
+  };
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("message_end", async (event, ctx) => {
+    if (event.message.role !== "assistant") return;
+    const guarded = await guardMessageEnd(event.message, {
+      cwd: ctx.cwd,
+      sessionId: ctx.sessionManager.getSessionId(),
+    });
+    if (!guarded) return;
+
+    ctx.ui?.notify(guarded.diagnostic, "warning");
+    return { message: guarded.message };
+  });
+}

package/extensions/opl-init/README.md

@@ -4,34 +4,23 @@ Generates or refreshes a repository-specific `AGENTS.md` guide through `/init`.
 
 ## Commands, flags, and shortcuts
 
-- `/init`: crawl the current repository and write `AGENTS.md` when its fingerprint is missing or stale. A stale guide is **overwritten** wholesale, hand-edited prose included; version control is the recovery path.
-- `/init --refine`: same write, then one injected user turn asking the model to expand the guide into a fuller, evidence-based version. Opt-in only: plain `/init` never touches the transcript.
+- `/init`: the only interface; there are no flags and unknown args are ignored. If the guide's fingerprint is current it stops and says so - zero model calls. If it is missing or stale: deterministic crawl, one out-of-band model refinement, extension-validated write, then `ctx.reload()` so the running session picks the new guide up.
 - No shortcuts.
 
 ## Extension features
 
-- Produces a deterministic repository guide with package commands and a file-type inventory.
-- Crawls deterministically to depth 3, ignores generated/dependency directories, caps directory listings at 40 entries, and caps the rendered tree at 300 lines with explicit omission markers.
-- Re-walks declared `pnpm-workspace.yaml` and Cargo workspace members with their own depth-3 budget.
-- Reads known manifests to include package scripts when present.
-- Writes the deterministic fingerprinted `AGENTS.md` directly. It sends no synthetic user message on its own; `/init --refine` is the single, explicit request for a model-refined guide.
-- Skips the write when the final `<!-- opl-init:fp <fingerprint> -->` marker is current.
-- Excludes `AGENTS.md` itself from the Git status fingerprint, preventing the act of updating the guide from making it immediately stale.
+- Produces a deterministic repository guide with package commands and a file-type inventory, then refines it with **one** `ctx.modelRegistry.streamSimple()` call on the current model (pi >= 0.86.0). The refinement never enters the conversation: no synthetic user message, no turn in the transcript, no `write` tool needed, and read-only/chat/plan modes refine identically.
+- The model only sees a bounded evidence packet (the baseline guide, every `package.json`'s full scripts block, and the first ~2 KB of each root/workspace `README`/`CLAUDE.md`, hard 24 KB budget with an explicit truncation line). The crawl is the only explorer.
+- The extension owns the fingerprint marker: model output is stripped of fences and any `opl-init:fp` comment, and the exact marker is appended as the final line. A model can never corrupt or fake a "current" guide.
+- Refine failure (no model, no auth, provider error, empty output) writes the deterministic baseline and notifies `refine failed` - `/init` only fails to write if the write itself fails.
+- Mid-session `/init` waits for the agent to settle (`ctx.waitForIdle()`), recomputes the fingerprint, and only then crawls. It never steers or interrupts the task in flight.
+- Crawls to depth 3, ignores generated/dependency directories, caps directory listings at 40 entries, caps the rendered tree at 300 lines with explicit omission markers, and re-walks declared `pnpm-workspace.yaml`/Cargo members with their own depth-3 budget.
+- Fingerprints dirty tracked + untracked file **contents** (plus HEAD and a generator schema version), excluding the root `AGENTS.md` itself, so writing the guide never makes it immediately stale and re-editing an already-modified file is never read as "current".
 
-## Session timing, reiterations, and re-injections
+## Requirements
 
-`/init` is an initialization command: run it at the **start** of a session, before the work begins, and again at the **very end** to fold the session's changes into the guide before pushing to the remote. Both are quiet moments, and `--refine` needs a quiet moment.
-
-What a `--refine` injection does to a live session:
-
-- It is a **user-role turn**. It is persisted in the session and replayed as context on every later turn and on resume, so two `--refine` runs in one session leave two instruction blocks behind and the transcript keeps paying for both.
-- It **always triggers a turn**. With an idle agent the refinement starts immediately. With an agent already streaming it is queued as a follow-up (`deliverAs: "followUp"`), so the guide is rewritten *after* the current turn finishes — later than you asked, and possibly after you have moved on to something else. An injection with no `deliverAs` makes Pi throw `Agent is already processing` and the request is lost.
-- It **cannot be fulfilled in a read-only mode**. Chat and plan modes carry no `write` tool, so the model can only describe the guide it was asked to write: the turn is spent and `AGENTS.md` stays at the deterministic baseline. Run `--refine` in normal (OFF) mode.
-- In **execute mode it ends the plan**. `opl-modes` leaves execute mode when a turn completes without `plan_complete`, so the refinement turn finishing drops the session to OFF mid-plan.
-- A refined guide is **not sticky**. The fingerprint is `HEAD` plus `git status`, so the next commit or dirty file makes the guide stale, and the next plain `/init` overwrites the refined prose with the baseline. Refine last, then commit `AGENTS.md`; if you refine and keep working, expect to refine once more at the end of the session.
-- The refinement's own write does **not** invalidate the marker: `AGENTS.md` is filtered out of the status fingerprint, so a successful `--refine` leaves `/init` reporting "current".
-- There is **no recursion and no automatic re-injection**. The message is sent with `expandPromptTemplates: false`, so a `/init` appearing inside it is not re-dispatched, and the extension registers no event handlers: every injection comes from you typing `--refine`.
+Refinement needs pi 0.86.0 or newer (`ctx.modelRegistry.streamSimple`, `ctx.reload`). Run `pi update` first if `/init` reports a refine failure on a machine with configured auth.
 
 ## Architecture
 
-`index.ts` owns crawling, fingerprinting, and deterministic guide writing. Git repositories fingerprint `HEAD` plus relevant `git status --porcelain=v1 --untracked-files=all` output, excluding `AGENTS.md` itself; non-Git repositories use sorted path, size, and mtime tuples. `/init` writes its guide locally and leaves the Pi transcript alone; `--refine` adds one small user message that points the model at the written file instead of re-sending the crawl.
+`index.ts` owns crawling, fingerprinting, the evidence packet, the model call, output validation, and writing. Git repositories fingerprint `schema version + HEAD + sha256 of every dirty tracked and untracked file` (root `AGENTS.md` excluded); non-git repositories use sorted path/size/mtime tuples. `/init` writes the file itself and reloads the session context; the main agent is never enlisted.

package/extensions/opl-init/index.ts

@@ -20,40 +20,68 @@ const MANIFESTS = new Set([
 const MAX_DEPTH = 3;
 const MAX_MEMBER_DEPTH = 3;
 const MAX_TREE_LINES = 300;
-const MAX_MANIFEST_BYTES = 2048;
+const MAX_MANIFEST_PARSE_BYTES = 262144;
 const MAX_DIR_ENTRIES = 40;
+// Bumping this constant is how generator upgrades invalidate every
+// previously-written guide: it is a fingerprint input.
+const GUIDE_SCHEMA_VERSION = 1;
 
 type Crawl = {
   tree: string[];
   extCounts: Map<string, number>;
   manifests: { path: string; content: string }[];
   workspaceMembers: string[];
+  seen: Set<string>;
 };
 
 // Marker the model appends to AGENTS.md so future runs can detect staleness exactly.
 const FP_MARKER = /<!-- opl-init:fp (\S+) -->/;
 
 // Exact snapshot of git-tracked + untracked state. Respects .gitignore for free.
+// Content-based: HEAD + per-path content hashes of every dirty tracked file
+// (vs HEAD, so staged changes count) and every untracked file. Only the root
+// AGENTS.md is excluded, so writing the guide does not make it stale;
+// subdirectory AGENTS.md files are repository facts.
 // Returns null for non-git directories (caller falls back to fingerprintFallback).
 function fingerprintGit(root: string): string | null {
+  const head = gitOutput(root, ["rev-parse", "HEAD"]);
+  if (head === null) return null;
+  const hash = createHash("sha256").update(`schema:${GUIDE_SCHEMA_VERSION}\0head:${head}\0`);
+  // --relative keeps diff paths cwd-relative and cwd-scoped, matching
+  // ls-files --others and the crawl; without it a subdirectory session would
+  // resolve every dirty path to a nonexistent file and hash "DELETED".
+  for (const path of (gitOutput(root, ["diff", "HEAD", "--name-only", "-z", "--relative"]) ?? "").split("\0")) {
+    if (!path || path === "AGENTS.md") continue;
+    hash.update(`${path}\0`).update(hashFile(join(root, path))).update("\0");
+  }
+  for (const path of (gitOutput(root, ["ls-files", "--others", "--exclude-standard", "-z"]) ?? "").split("\0")) {
+    if (!path || path === "AGENTS.md") continue;
+    hash.update(`${path}\0`).update(hashFile(join(root, path))).update("\0");
+  }
+  return hash.digest("hex").slice(0, 16);
+}
+
+function gitOutput(root: string, args: string[]): string | null {
   try {
-    const head = execFileSync("git", ["rev-parse", "HEAD"], {
+    return execFileSync("git", args, {
       cwd: root,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 64 * 1024 * 1024,
     });
-    const status = execFileSync(
-      "git",
-      ["status", "--porcelain=v1", "--untracked-files=all"],
-      { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
-    );
-    const relevantStatus = status.split("\n").filter(line => !line.endsWith("AGENTS.md")).join("\n");
-    return createHash("sha256").update(head).update(relevantStatus).digest("hex").slice(0, 16);
   } catch {
     return null;
   }
 }
 
+function hashFile(path: string): string {
+  try {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+  } catch {
+    return "DELETED";
+  }
+}
+
 // ponytail: stat-only (path|size|mtime), not content hashing. Catches add/delete/
 // rename but shares the touch-without-change blind spot; only used for non-git dirs.
 function fingerprintFallback(root: string): string {
@@ -85,7 +113,7 @@ function fingerprintFallback(root: string): string {
 
   walk(root);
   parts.sort();
-  return createHash("sha256").update(parts.join("\n")).digest("hex").slice(0, 16);
+  return createHash("sha256").update(`schema:${GUIDE_SCHEMA_VERSION}\n`).update(parts.join("\n")).digest("hex").slice(0, 16);
 }
 
 function fingerprint(root: string): string {
@@ -98,6 +126,7 @@ function crawl(root: string): Crawl {
     extCounts: new Map(),
     manifests: [],
     workspaceMembers: [],
+    seen: new Set(),
   };
 
   function walk(dir: string, depth: number, prefix: string, maxDepth: number) {
@@ -128,17 +157,23 @@ function crawl(root: string): Crawl {
       }
 
       files.push(entry);
-      const extension = extname(entry) || entry;
-      result.extCounts.set(extension, (result.extCounts.get(extension) ?? 0) + 1);
-
-      if (MANIFESTS.has(entry)) {
-        try {
-          result.manifests.push({
-            path: relative(root, path),
-            content: readFileSync(path, "utf8").slice(0, MAX_MANIFEST_BYTES),
-          });
-        } catch {
-          // Skip unreadable manifests.
+      // Dedupe by absolute path: declared-member re-walks overlap the root
+      // walk, and the inventory must not double-count. Tree lines still
+      // accept shallow overlap for completeness.
+      if (!result.seen.has(path)) {
+        result.seen.add(path);
+        const extension = extname(entry) || entry;
+        result.extCounts.set(extension, (result.extCounts.get(extension) ?? 0) + 1);
+
+        if (MANIFESTS.has(entry)) {
+          try {
+            result.manifests.push({
+              path: relative(root, path),
+              content: readFileSync(path, "utf8").slice(0, MAX_MANIFEST_PARSE_BYTES),
+            });
+          } catch {
+            // Skip unreadable manifests.
+          }
         }
       }
     }
@@ -279,87 +314,194 @@ function result_tree_paths(root: string): string[] {
   return paths;
 }
 
-function packageScripts(content: string): string | null {
-  try {
-    const packageJson = JSON.parse(content);
-    if (!packageJson.scripts || !Object.keys(packageJson.scripts).length) return null;
-    return Object.entries(packageJson.scripts)
-      .map(([name, command]) => `  ${name}: ${command}`)
-      .join("\n");
-  } catch {
-    return null;
+// Root-first, per-package-labeled script lines, bounded at 30 entries total.
+function aggregateScripts(manifests: { path: string; content: string }[]): string | null {
+  const lines: string[] = [];
+  const sorted = [...manifests].sort((a, b) =>
+    a.path === "package.json" ? -1 : b.path === "package.json" ? 1 : a.path.localeCompare(b.path));
+  for (const manifest of sorted) {
+    if (!manifest.path.endsWith("package.json") || lines.length >= 30) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(manifest.content);
+    } catch {
+      continue;
+    }
+    const scripts = parsed?.scripts;
+    if (!scripts || typeof scripts !== "object") continue;
+    const label = manifest.path === "package.json" ? "" : `${manifest.path.replace(/\/package\.json$/, "")}/ `;
+    for (const [name, command] of Object.entries(scripts)) {
+      if (lines.length >= 30) break;
+      lines.push(`  ${label}${name}: ${command}`);
+    }
   }
+  return lines.length ? lines.join("\n") : null;
 }
 
 function buildGuide(root: string, crawlResult: Crawl, marker: string): string {
   const topLevel = crawlResult.tree.filter(line => !line.startsWith("  ")).slice(0, 30).join(", ");
-  const scripts = crawlResult.manifests
-    .map(manifest => manifest.path.endsWith("package.json") ? packageScripts(manifest.content) : null)
-    .find(Boolean);
+  const scripts = aggregateScripts(crawlResult.manifests);
   const commandBlock = scripts ? "Package scripts:\n```\n" + scripts + "\n```" : "No package scripts were detected by the repository crawl.";
   return `# Repository Guide\n\n## What this is\n\nRepository at \`${root}\`. Use the repository files as the source of truth; the top-level inventory includes ${topLevel || "(not available)"}.\n\n## Commands\n\n${commandBlock}\n\n## Repository inventory\n\n- File types: ${[...crawlResult.extCounts.entries()].map(([extension, count]) => `${extension} (${count})`).join(", ") || "none detected"}.\n- Inspect specific files before changing behavior; this guide is a starting point, not a substitute for reading the code.\n\n## Agent workflow\n\nKeep changes focused on the requested behavior, preserve existing interfaces, and run the narrowest relevant test before the full suite. Keep secrets and generated output out of tracked configuration.\n${marker}\n`;
 }
 
-/**
- * Opt-in refinement request for `/init --refine`. Deliberately small: the crawl inventory is
- * already in the guide, so the model reads the file instead of receiving a second copy of the
- * tree. This is the only injected user turn in the extension, and it never fires on its own.
- */
-function refinePrompt(agentsPath: string, marker: string): string {
-  return [
-    `Refine the repository guide at ${agentsPath}, which /init generated from a repository crawl.`,
-    "Read the guide first, then open only the specific files you need to confirm repository-specific facts. Do not re-crawl the tree, spawn subagents, or create task lists.",
-    "Rewrite the guide in place with the write tool, concise and evidence-based (usually 250-700 words):",
-    '- Prefer these sections when evidence supports them: "## What this is", "## Commands", "## Architecture", "## Configuration and installation", "## Testing and operational quirks", "## Key files". Omit unsupported sections instead of inventing them, and state meaningful absences such as no build, lint, or typecheck command.',
-    "- Keep the crawl's factual inventory (commands, file types, workspace members) and avoid generic contribution, Git, or pull-request advice.",
-    "- Do not modify, create, or delete any other file.",
-    `- Make the very last line exactly: ${marker}`,
-    "A response containing Markdown without writing the file is a failure.",
-  ].join("\n");
+const MAX_EVIDENCE_BYTES = 24576;
+const MAX_README_HEAD_BYTES = 2048;
+
+// Evidence the model cannot fetch itself: the deterministic stand-in for the
+// tools the refine call does not have, under a hard byte budget. The spec's
+// three parts: baseline guide, full per-package scripts blocks, readme heads.
+function evidencePacket(
+  root: string,
+  baseline: string,
+  crawlResult: { manifests: { path: string; content: string }[]; workspaceMembers: string[] },
+): string {
+  const parts = [baseline];
+  let used = Buffer.byteLength(baseline, "utf8");
+  const push = (block: string): boolean => {
+    const bytes = Buffer.byteLength(block, "utf8") + 1;
+    if (used + bytes > MAX_EVIDENCE_BYTES) {
+      parts.push("(evidence truncated)");
+      return false;
+    }
+    used += bytes;
+    parts.push(block);
+    return true;
+  };
+  for (const manifest of crawlResult.manifests) {
+    if (!manifest.path.endsWith("package.json")) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(manifest.content);
+    } catch {
+      continue;
+    }
+    const scripts = parsed?.scripts;
+    if (!scripts || typeof scripts !== "object") continue;
+    const block = `=== scripts: ${manifest.path} ===\n${Object.entries(scripts).map(([name, command]) => `${name}: ${command}`).join("\n")}`;
+    if (!push(block)) return parts.join("\n");
+  }
+  const candidates = ["README.md", "readme.md", "README", "CLAUDE.md"];
+  const paths = [...candidates, ...crawlResult.workspaceMembers.flatMap((m) => candidates.map((c) => `${m}/${c}`))];
+  for (const rel of paths) {
+    let head: string;
+    try {
+      head = readFileSync(join(root, rel), "utf8").slice(0, MAX_README_HEAD_BYTES);
+    } catch {
+      continue;
+    }
+    if (!push(`=== ${rel} ===\n${head}`)) break;
+  }
+  return parts.join("\n");
 }
 
-// Named export for fixture tests (tests/opl-init-crawl.test.mjs).
-export { crawl };
+const REFINE_SYSTEM_PROMPT = [
+  "You are rewriting a repository guide for an AI coding agent.",
+  "Input: a draft guide generated from a deterministic repository crawl, plus bounded file excerpts.",
+  "Return ONLY the final Markdown document: no preamble, no code fence around the document, no HTML comments.",
+  "Do not invent facts unsupported by the input; keep the factual inventory (commands, file types, workspace members).",
+  'Prefer these sections when evidence supports them: "## What this is", "## Commands", "## Architecture", "## Configuration and installation", "## Testing and operational quirks", "## Key files". Omit unsupported sections.',
+  "Usually 250-700 words. Avoid generic contribution, Git, or pull-request advice.",
+].join("\n");
+
+// The model never owns the marker line: every opl-init:fp comment is stripped
+// and the extension's exact marker is appended as the final line.
+function finalizeRefinedGuide(text: string, marker: string): string {
+  let body = text.trim();
+  // Strip a wrapper fence only when it opens *and* closes; a guide ending in
+  // a legitimate code block keeps its closing fence.
+  if (/^```[a-zA-Z]*\s*\n/.test(body)) {
+    body = body.replace(/^```[a-zA-Z]*\s*\n/, "").replace(/\n```\s*$/, "");
+  }
+  body = body.replace(/<!-- opl-init:fp \S+ -->/g, "").trimEnd();
+  return `${body}\n${marker}\n`;
+}
+
+// One out-of-band completion on the current model. No tools, no session
+// message: any failure returns null and the caller writes the baseline.
+// Bounded so a stalled provider cannot leave /init hanging with no UI signal
+// (the old injected turn was Esc-cancellable; this replaces that escape hatch).
+const REFINE_TIMEOUT_MS = 120000;
+
+async function refineGuide(ctx: any, evidence: string, marker: string): Promise<string | null> {
+  const model = ctx.model;
+  if (!model || typeof ctx.modelRegistry?.streamSimple !== "function") return null;
+  ctx.ui?.notify?.("opl-init: refining the guide with the current model...", "info");
+  try {
+    const stream = ctx.modelRegistry.streamSimple(
+      model,
+      { systemPrompt: REFINE_SYSTEM_PROMPT, messages: [{ role: "user", content: evidence, timestamp: Date.now() }], tools: [] },
+      { reasoning: false, signal: AbortSignal.timeout(REFINE_TIMEOUT_MS) },
+    );
+    const result = await stream.result();
+    if (!result || result.stopReason === "error" || result.stopReason === "aborted") return null;
+    const text = (result.content ?? [])
+      .filter((part: any) => part.type === "text")
+      .map((part: any) => part.text)
+      .join("\n");
+    return text.trim() ? finalizeRefinedGuide(text, marker) : null;
+  } catch {
+    return null;
+  }
+}
+
+// Named exports for fixture tests (tests/opl-init-*.test.mjs).
+export { crawl, fingerprint, evidencePacket, finalizeRefinedGuide, refineGuide };
 
 export default function (pi: ExtensionAPI) {
   pi.registerCommand("init", {
-    description: "[opl-init] Crawl the repository and write an AGENTS.md guide (--refine also asks the model to expand it)",
-    handler: async (args, ctx) => {
-      const refine = /(?:^|\s)--refine(?:\s|$)/.test(args.trim());
+    description: "[opl-init] Crawl + refine AGENTS.md out-of-band; zero model calls when current",
+    handler: async (_args, ctx) => {
       const root = ctx.cwd;
       const agentsPath = join(root, "AGENTS.md");
-      const currentFp = fingerprint(root);
-      const exists = existsSync(agentsPath);
-
-      let storedFp: string | null = null;
-      if (exists) {
+      const storedFp = () => {
         try {
-          storedFp = readFileSync(agentsPath, "utf8").match(FP_MARKER)?.[1] ?? null;
+          return readFileSync(agentsPath, "utf8").match(FP_MARKER)?.[1] ?? null;
         } catch {
-          storedFp = null;
+          return null;
         }
-      }
+      };
 
-      const marker = `<!-- opl-init:fp ${currentFp} -->`;
-
-      if (exists && storedFp === currentFp) {
+      let currentFp = fingerprint(root);
+      if (existsSync(agentsPath) && storedFp() === currentFp) {
         ctx.ui.notify("AGENTS.md is current; /init will not modify it.", "info");
-      } else {
-        // Regenerating replaces the whole file, including hand-edited prose; the repository's
-        // version control is the recovery path.
-        const crawlResult = crawl(root);
-        try {
-          writeFileSync(agentsPath, buildGuide(root, crawlResult, marker), "utf8");
-          ctx.ui.notify(exists ? "AGENTS.md overwritten from the repository crawl." : "AGENTS.md created.", "info");
-        } catch (error: any) {
-          ctx.ui.notify(`Could not write AGENTS.md: ${error?.message || error}`, "error");
+        return;
+      }
+
+      if (!ctx.isIdle()) {
+        ctx.ui.notify("opl-init: waiting for the current agent run to settle before writing AGENTS.md.", "info");
+        await ctx.waitForIdle();
+        // The settling run may have moved the tree; recompute before crawling.
+        currentFp = fingerprint(root);
+        if (existsSync(agentsPath) && storedFp() === currentFp) {
+          ctx.ui.notify("AGENTS.md is current; /init will not modify it.", "info");
           return;
         }
       }
 
-      // Queue, never steer: Pi throws "Agent is already processing" for an injection with no
-      // deliverAs while a turn is streaming, and steering would hijack the task in flight.
-      if (refine) pi.sendUserMessage(refinePrompt(agentsPath, marker), { deliverAs: "followUp" });
+      const marker = `<!-- opl-init:fp ${currentFp} -->`;
+      // Regenerating replaces the whole file, including hand-edited prose; the
+      // repository's version control is the recovery path.
+      const crawlResult = crawl(root);
+      const baseline = buildGuide(root, crawlResult, marker);
+      const refined = await refineGuide(ctx, evidencePacket(root, baseline, crawlResult), marker);
+
+      try {
+        writeFileSync(agentsPath, refined ?? baseline, "utf8");
+      } catch (error: any) {
+        ctx.ui.notify(`Could not write AGENTS.md: ${error?.message || error}`, "error");
+        return;
+      }
+
+      ctx.ui.notify(
+        refined
+          ? "AGENTS.md written from the repository crawl (model-refined)."
+          : "refine failed; wrote deterministic AGENTS.md from the repository crawl.",
+        "info",
+      );
+      // Terminal: pi docs say code after ctx.reload() runs in the old frame.
+      await ctx.reload();
+      return;
     },
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlines/opl-pi-sht",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "opl-pi-sht (shouldHaveThat) Pi coding-agent extension kit: token-efficient context, safe modes, fingerprinted /init, model benchmarking, web access, and browser automation.",
   "repository": {
     "type": "git",
@@ -40,10 +40,11 @@
   },
   "type": "module",
   "scripts": {
-    "test": "npm run test:opl-browser && npm run test:opl-footer && npm run test:opl-init && npm run test:opl-input && npm run test:opl-modes && npm run test:opl-questionnaire && npm run test:opl-todo && npm run test:opl-webaccess && npm run test:opl-simplebench && npm run test:opl-ctxtrim",
+    "test": "npm run test:opl-browser && npm run test:opl-footer && npm run test:opl-guardian && npm run test:opl-init && npm run test:opl-input && npm run test:opl-modes && npm run test:opl-questionnaire && npm run test:opl-todo && npm run test:opl-webaccess && npm run test:opl-simplebench && npm run test:opl-ctxtrim",
     "test:opl-browser": "bun test tests/opl-browser-helpers.test.mjs && OPL_EXTENSION=opl-browser bun test tests/extension-smoke.test.mjs",
     "test:opl-footer": "bun test tests/opl-footer-helpers.test.mjs && OPL_EXTENSION=opl-footer bun test tests/extension-smoke.test.mjs",
-    "test:opl-init": "bun test tests/opl-init-crawl.test.mjs && OPL_EXTENSION=opl-init bun test tests/extension-smoke.test.mjs",
+    "test:opl-guardian": "bun test tests/opl-guardian.test.mjs && OPL_EXTENSION=opl-guardian bun test tests/extension-smoke.test.mjs",
+    "test:opl-init": "bun test tests/opl-init-crawl.test.mjs tests/opl-init-fingerprint.test.mjs tests/opl-init-packet.test.mjs && OPL_EXTENSION=opl-init bun test tests/extension-smoke.test.mjs",
     "test:opl-input": "bun test tests/opl-input-style.test.mjs && OPL_EXTENSION=opl-input bun test tests/extension-smoke.test.mjs",
     "test:opl-modes": "bun test tests/opl-modes-helpers.test.mjs tests/opl-modes-lifecycle.test.mjs && OPL_EXTENSION=opl-modes bun test tests/extension-smoke.test.mjs",
     "test:opl-questionnaire": "OPL_EXTENSION=opl-questionnaire bun test tests/extension-smoke.test.mjs",