@openlines/opl-pi-sht 0.2.0 → 0.2.1

package/README.md

@@ -71,7 +71,7 @@ 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`.                                                                  |
@@ -111,7 +111,7 @@ Cold prompt-cache write, measured /init session (opl-modes lazy tools + MCP adap
 
 ### 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.

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.1",
   "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",
@@ -43,7 +43,7 @@
     "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: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-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",