killeros 2.0.3 → 2.0.4

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to KillerOS are documented here.
 
 ## [Unreleased]
 
+## [2.0.4] - 2026-08-10
+
+### Changed
+
+- Rebuilt `/init` around a packaged four-section guideline-synthesis workflow that preserves compatible root policy without requiring an external skill.
+- Removed live blue slash-command coloring while retaining slash autocomplete, the framed multiline editor, and Shift+Enter.
+
+### Fixed
+
+- Prevented `/init` from reading Git-ignored files, known secrets, private keys, linked or non-regular files, other guidance, dependencies, and files outside its frozen evidence map.
+- Protected root `AGENTS.md` from concurrent replacement and reported incompatible policy conflicts without writing.
+- Made `/clear` confirm before aborting active work, wait for settlement, and then start the new session.
+- Preserved explicit Responses API verbosity and reasoning-summary settings while applying concise defaults only to absent fields.
+- Cancelled lifecycle hook process trees with bounded cleanup when Pi aborts the parent request.
+- Kept `/init` middleware from freezing shared tool input and preserved custom editors installed by other extensions.
+- Removed private Pi editor-state access in favor of public rendering contracts.
+
 ## [2.0.3] - 2026-08-09
 
 ### Added

package/Killeros.ts

@@ -15,10 +15,12 @@ import { createGoalRuntime, createInitRuntime } from "./killeros/runtime.ts";
 import { registerShellUi } from "./killeros/shell-ui.ts";
 import { registerVariants } from "./killeros/variants.ts";
 
-export { CONCISE_SYSTEM_PROMPT, isConcisedEnabled } from "./killeros/concise.ts";
+export { CONCISE_SYSTEM_PROMPT, isConciseEnabled, isConcisedEnabled } from "./killeros/concise.ts";
 export { contextPercentRemaining, formatCost, formatContextProgress } from "./killeros/footer.ts";
 export { executeHook } from "./killeros/hooks.ts";
-export { INIT_WORKFLOW_PROMPT, writeInitAgentsFile } from "./killeros/init.ts";
+export { INIT_WORKFLOW_PROMPT } from "./killeros/init.ts";
+export { buildInitEvidence, listInitEvidence, readInitEvidence } from "./killeros/init-evidence.ts";
+export { captureInitTargetBaseline, installInitAgentsFile, validateGeneratedGuidance, writeInitAgentsFile } from "./killeros/init-target.ts";
 
 export interface KillerosOptions {
   completionNotifications?: CompletionNotificationDependencies;

package/README.md

@@ -31,7 +31,7 @@ pi install git:github.com/KyrosHendrix/pi-KillerOS
 Pin an install to a release:
 
 ```bash
-pi install git:github.com/KyrosHendrix/pi-KillerOS@v2.0.3
+pi install git:github.com/KyrosHendrix/pi-KillerOS@v2.0.4
 ```
 
 Add `-l` to either command for a project-only install. Restart Pi after installing.
@@ -41,17 +41,17 @@ Add `-l` to either command for a project-only install. Restart Pi after installi
 - 52-column Compact startup card with inline version, polished model/provider identity, adjacent `/model`, directory, conditional Git branch, and a shuffled session-stable tip
 - Cohesive dark theme with coral accents and neutral tool-call containers across pending, success, and error states
 - Animated orange 12-frame activity glyph loop at 120 ms per frame, with orange shuffled Claude-adjacent verbs changing every 2.5 seconds, a gray `(esc to interrupt · thinking)` status with bold `esc`, and a quiet hidden-thinking label
-- Framed multiline editor with Shift+Enter support and live command-blue highlighting for recognized slash command prefixes
+- Framed multiline editor with Shift+Enter support and slash-command autocomplete; KillerOS preserves an editor factory configured by another extension
 - Responsive footer with polished model/provider identity, plain-language context, and active goal state remaining; reasoning, Git branch, elapsed time, cost, and path cut down by available width
 - Pi-owned context compaction with active goals continuing from Pi's settled boundary after manual, threshold, and overflow compaction
 - Optional completion sounds after successful or failed settled requests, excluding manual aborts
 - `/variants` selector and direct reasoning-level arguments
 - Codex-style `/goal` with an interactive status/action panel, durable objectives, pause, resume, edit, confirmed panel clearing, automatic continuation, and explicit completion
-- Claude Code-style `/init` that scans the repository and generates a concise root `AGENTS.md` without setup questions
+- Automatic `/init` guideline synthesis with a frozen safe evidence map, protected existing policy, and the four packaged behavioral sections adapted from `writing-great-guidelines`
 - `question` tool with height-bounded option windows, configured Pi keybindings, live option/input progress, proposal previews, custom answers, history, cancellation, and compact expandable transcript rendering
 - Mid-prompt slash completion with current Pi `0.82.1` commands, extensions, prompts, and skills; paths, URLs, and invalid commands remain plain text
-- `/clear` for a confirmed new session, plus `/exit` for graceful shutdown
-- Concise system-prompt guidance without modifying completed assistant messages
+- Goal-aware `/clear` that confirms, aborts active work, waits for settlement, and starts a new session, plus `/exit` for graceful shutdown
+- Concise system-prompt guidance and supported native concise defaults that preserve explicit provider settings
 
 ## Commands
 
@@ -72,7 +72,9 @@ Add `-l` to either command for a project-only install. Restart Pi after installi
 
 `/goal` requires a saved session in TUI or RPC mode. Goal state is stored in versioned session entries on the active branch and restored after reload, resume, fork, or tree navigation. Active goals inject their unchanged objective every turn and continue one settled turn at a time. The model must use KillerOS’s private goal tool to mark verified completion or a blocker repeated across at least three goal turns; final prose alone does not end the loop. Aborted turns, provider failures, and continuation failures pause safely. Replacing unfinished work requires confirmation, and `/goal edit` requires TUI mode.
 
-`/init` builds a bounded project map, reads high-value manifests, documentation, and CI configuration, and lets the active model inspect additional implementation files before generating root `AGENTS.md`. Existing `AGENTS.md` and `CLAUDE.md` content is intentionally excluded so stale guidance is not inherited. The command asks no setup questions, starts no second model process, writes only `AGENTS.md`, and reloads Pi resources when finished.
+`/init` freezes a safe project-file map and exposes only dedicated read and list operations while it generates root `AGENTS.md`. Git-ignored files, known secret paths, private-key formats, other guidance, dependencies, links, non-regular files, and files outside that map are unavailable. Existing root `AGENTS.md` is separate protected policy: compatible rules are preserved, a real policy conflict leaves it unchanged with a reason, and any concurrent target change aborts installation without replacing the newer file.
+
+The generated file uses the four behavioral sections adapted from `writing-great-guidelines`; no external skill installation is required. `/init` asks no setup questions, starts no second model process, writes no other file, and reloads Pi resources only after a successful write.
 
 Supported reasoning levels are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. KillerOS limits choices to levels supported by the current model.
 
@@ -90,7 +92,7 @@ Manual `/compact` aborts the current goal turn before summarization, so KillerOS
 
 For trusted projects, KillerOS loads `AGENTS.local.md` after Pi's shared repository context. A one-line `@path` or `@~/path` file imports personal guidance from another location.
 
-Lifecycle hooks are loaded from `.pi/killeros-hooks.json` at session start. Supported event keys are `tool_call`, `tool_result`, and `agent_settled`; matchers are JavaScript regular expressions over Pi tool names. Hook commands run from the repository root with `KILLEROS_EVENT`, `KILLEROS_TOOL`, and `KILLEROS_PAYLOAD` environment variables. Failed `tool_call` hooks block the tool, while later-event failures notify the user.
+Lifecycle hooks are loaded from `.pi/killeros-hooks.json` at session start. Supported event keys are `tool_call`, `tool_result`, and `agent_settled`; matchers are JavaScript regular expressions over Pi tool names. Hook commands run from the repository root with `KILLEROS_EVENT`, `KILLEROS_TOOL`, and `KILLEROS_PAYLOAD` environment variables. Failed `tool_call` hooks block the tool, while later-event failures notify the user. Aborting the parent request stops the hook process tree with bounded graceful and forced cleanup without reporting cancellation as a hook failure.
 
 ## Behavior by mode
 

package/killeros/commands.ts

@@ -8,8 +8,9 @@ async function confirmNewSession(ctx: ExtensionCommandContext): Promise<boolean>
 
 export function registerAliases(pi: ExtensionAPI): void {
   const startNewSession = async (_args: string, ctx: ExtensionCommandContext): Promise<void> => {
-    await ctx.waitForIdle();
     if (!await confirmNewSession(ctx)) return;
+    if (!ctx.isIdle()) ctx.abort();
+    await ctx.waitForIdle();
     await ctx.newSession();
   };
   pi.registerCommand("clear", { description: "Start a new session after confirmation", handler: startNewSession });
@@ -54,13 +55,6 @@ const BUILTIN_COMMANDS: ReadonlyArray<{ name: string; description: string }> = [
   { name: "quit", description: "Quit Pi" },
 ];
 
-export function availableCommandNames(pi: ExtensionAPI): ReadonlySet<string> {
-  return new Set([
-    ...BUILTIN_COMMANDS.map((command) => command.name),
-    ...pi.getCommands().map((command) => command.name),
-  ]);
-}
-
 const COMMAND_SYNTAX_HINTS: Readonly<Record<string, string>> = {
   goal: "/goal [objective|clear|edit|pause|resume]",
   variants: "/variants [level]",

package/killeros/concise.ts

@@ -41,22 +41,26 @@ function applyConciseModelSettings(payload: unknown, api: unknown, modelId: unkn
   const supportsVerbosity = api === "openai-codex-responses"
     || api === "openai-responses" && typeof modelId === "string" && /^gpt-5(?:[.-]|$)/u.test(modelId);
   let updated = payload;
-  if (supportsVerbosity) {
-    updated = {
-      ...updated,
-      text: { ...(isRecord(payload.text) ? payload.text : {}), verbosity: "low" },
-    };
+  const text = isRecord(payload.text) ? payload.text : undefined;
+  if (supportsVerbosity && !Object.hasOwn(text ?? {}, "verbosity")) {
+    updated = { ...updated, text: { ...(text ?? {}), verbosity: "low" } };
   }
-  if (supportsSummary && isRecord(payload.reasoning)) {
-    updated = { ...updated, reasoning: { ...payload.reasoning, summary: "concise" } };
+  const reasoning = isRecord(payload.reasoning) ? payload.reasoning : undefined;
+  if (supportsSummary && reasoning && !Object.hasOwn(reasoning, "summary")) {
+    updated = { ...updated, reasoning: { ...reasoning, summary: "concise" } };
   }
   return updated;
 }
 
-export function isConcisedEnabled(): boolean {
+export function isConciseEnabled(): boolean {
   return true;
 }
 
+/** @deprecated Use isConciseEnabled instead. */
+export function isConcisedEnabled(): boolean {
+  return isConciseEnabled();
+}
+
 export function registerConcisePrompt(pi: ExtensionAPI): void {
   pi.on("before_agent_start", (event) => ({
     systemPrompt: `${event.systemPrompt}\n\n${CONCISE_SYSTEM_PROMPT}`,

package/killeros/goals.ts

@@ -3,7 +3,6 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { MAX_NODE_TIMER_MS } from "./limits.ts";
 import { BoundedText } from "./bounded-text.ts";
-import { CONCISE_SYSTEM_PROMPT } from "./concise.ts";
 import { formatTime, formatTokens } from "./display.ts";
 import { reportError } from "./errors.ts";
 import { resolvePersonalInstructions } from "./personal-instructions.ts";
@@ -355,7 +354,6 @@ function goalContinuationMessage(state: GoalState, ctx: ExtensionContext): strin
       sections.push(`<personal_instructions source=${JSON.stringify(personal.source)}>\n${personal.content}\n</personal_instructions>`);
     }
   }
-  sections.push(CONCISE_SYSTEM_PROMPT);
   return sections.join("\n\n");
 }
 

package/killeros/hooks.ts

@@ -22,6 +22,7 @@ interface HookExecutionResult {
   stdout: string;
   stderr: string;
   timedOut: boolean;
+  cancelled: boolean;
   exitUnconfirmed: boolean;
 }
 
@@ -109,7 +110,17 @@ function terminateHookProcess(child: ReturnType<typeof spawn>, force: boolean):
   }
 }
 
-export function executeHook(command: string, cwd: string, environment: Record<string, string>, timeoutMs = 30_000, spawnProcess: typeof spawn = spawn): Promise<HookExecutionResult> {
+export function executeHook(
+  command: string,
+  cwd: string,
+  environment: Record<string, string>,
+  timeoutMs = 30_000,
+  spawnProcess: typeof spawn = spawn,
+  signal?: AbortSignal,
+): Promise<HookExecutionResult> {
+  if (signal?.aborted) {
+    return Promise.resolve({ code: 130, stdout: "", stderr: "", timedOut: false, cancelled: true, exitUnconfirmed: false });
+  }
   return new Promise((resolve) => {
     const child = spawnProcess(command, {
       cwd,
@@ -122,36 +133,48 @@ export function executeHook(command: string, cwd: string, environment: Record<st
     let stdout = "";
     let stderr = "";
     let completed = false;
-    let timedOut = false;
-    let exitUnconfirmed = false;
+    let termination: "timeout" | "cancelled" | undefined;
     let timer: NodeJS.Timeout | undefined;
     let forceTimer: NodeJS.Timeout | undefined;
     let settleTimer: NodeJS.Timeout | undefined;
-    const finish = (code: number, unconfirmed = false): void => {
+    const finish = (code: number, exitUnconfirmed = false): void => {
       if (completed) return;
       completed = true;
-      exitUnconfirmed = unconfirmed;
       if (timer) clearTimeout(timer);
       if (forceTimer) clearTimeout(forceTimer);
       if (settleTimer) clearTimeout(settleTimer);
-      resolve({ code, stdout, stderr, timedOut, exitUnconfirmed });
+      signal?.removeEventListener("abort", abort);
+      resolve({
+        code,
+        stdout,
+        stderr,
+        timedOut: termination === "timeout",
+        cancelled: termination === "cancelled",
+        exitUnconfirmed,
+      });
     };
-    child.stdout.on("data", (chunk) => { stdout = appendBounded(stdout, chunk); });
-    child.stderr.on("data", (chunk) => { stderr = appendBounded(stderr, chunk); });
-    child.on("error", (error) => {
-      stderr = appendBounded(stderr, error.message);
-      finish(timedOut ? 124 : 1);
-    });
-    child.once("close", (code) => finish(timedOut ? 124 : code ?? 1));
-    timer = setTimeout(() => {
-      timedOut = true;
+    const terminationCode = (): number => termination === "cancelled" ? 130 : 124;
+    const beginTermination = (reason: "timeout" | "cancelled"): void => {
+      if (completed || termination) return;
+      termination = reason;
       terminateHookProcess(child, false);
       forceTimer = setTimeout(() => {
         if (completed) return;
         terminateHookProcess(child, true);
-        settleTimer = setTimeout(() => finish(124, true), 1_000);
+        settleTimer = setTimeout(() => finish(terminationCode(), true), 1_000);
       }, 1_000);
-    }, Math.max(1_000, Math.min(timeoutMs, 300_000)));
+    };
+    const abort = (): void => beginTermination("cancelled");
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) beginTermination("cancelled");
+    child.stdout.on("data", (chunk) => { stdout = appendBounded(stdout, chunk); });
+    child.stderr.on("data", (chunk) => { stderr = appendBounded(stderr, chunk); });
+    child.on("error", (error) => {
+      stderr = appendBounded(stderr, error.message);
+      finish(termination ? terminationCode() : 1);
+    });
+    child.once("close", (code) => finish(termination ? terminationCode() : code ?? 1));
+    timer = setTimeout(() => beginTermination("timeout"), Math.max(1_000, Math.min(timeoutMs, 300_000)));
   });
 }
 
@@ -180,7 +203,10 @@ export function registerLifecycleHooks(pi: ExtensionAPI): void {
         ctx.cwd,
         hookEnvironment("tool_call", event.toolName, event.input),
         hook.timeoutMs,
+        spawn,
+        ctx.signal,
       );
+      if (result.cancelled) return { block: true, reason: "Hook cancelled because the parent request was aborted" };
       if (result.code !== 0) {
         const reason = hookFailureMessage(hook, result);
         ctx.ui.notify(reason, "error");
@@ -200,7 +226,10 @@ export function registerLifecycleHooks(pi: ExtensionAPI): void {
           isError: event.isError,
         }),
         hook.timeoutMs,
+        spawn,
+        ctx.signal,
       );
+      if (result.cancelled) break;
       if (result.code !== 0) ctx.ui.notify(hookFailureMessage(hook, result), "error");
     }
   });
@@ -212,7 +241,10 @@ export function registerLifecycleHooks(pi: ExtensionAPI): void {
         ctx.cwd,
         hookEnvironment("agent_settled"),
         hook.timeoutMs,
+        spawn,
+        ctx.signal,
       );
+      if (result.cancelled) break;
       if (result.code !== 0) ctx.ui.notify(hookFailureMessage(hook, result), "error");
     }
   });

package/killeros/init-evidence.ts

@@ -0,0 +1,240 @@
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+export const INIT_READ_TOOL = "killeros_init_read";
+export const INIT_LIST_TOOL = "killeros_init_list";
+
+const SNAPSHOT_LIMIT = 40 * 1024;
+const AUTOMATIC_FILE_LIMIT = 8 * 1024;
+const READ_LIMIT = 32 * 1024;
+const PATH_LIMIT = 400;
+const DIRECTORY_LIMIT = 120;
+const DEPTH_LIMIT = 4;
+const EXCLUDED_DIRS = new Set([
+  ".agents", ".claude", ".git", ".next", ".pi", ".pytest_cache", ".turbo", ".venv", "__pycache__", "archive", "build", "coverage", "data", "dist", "logs", "node_modules", "target", "test-results", "vendor",
+]);
+const EXCLUDED_GUIDANCE = new Set([
+  ".cursorrules", "agents.md", "agents.local.md", "claude.md", "claude.local.md", "copilot-instructions.md", "gemini.md", "memory.md", "skill.md",
+]);
+const ROOT_EVIDENCE = [
+  "README.md", "README.rst", "README.txt", "CONTRIBUTING.md", "package.json", "pyproject.toml", "requirements.txt", "Cargo.toml", "go.mod", "Makefile", "Dockerfile", "compose.yaml", "compose.yml", "config.yaml", "config.yml", "tsconfig.json", "vite.config.ts", "vite.config.js", "eslint.config.js", "eslint.config.mjs",
+] as const;
+const NESTED_EVIDENCE = new Set(["package.json", "pyproject.toml", "requirements.txt", "Cargo.toml", "go.mod"]);
+
+export interface InitEvidenceIndex {
+  projectRoot: string;
+  canonicalPaths: ReadonlyMap<string, string>;
+  snapshot: string;
+}
+
+export interface InitEvidenceBuildResult {
+  index: InitEvidenceIndex;
+}
+
+function evidenceKey(relativePath: string): string {
+  const normalized = relativePath.replaceAll("\\", "/");
+  return process.platform === "win32" ? normalized.toLocaleLowerCase() : normalized;
+}
+
+function sensitiveEvidencePath(relativePath: string): boolean {
+  const normalized = relativePath.replaceAll("\\", "/").toLocaleLowerCase();
+  const name = path.posix.basename(normalized);
+  return /^\.env(?:\.|$)/u.test(name)
+    || [".npmrc", ".pypirc", ".netrc", "id_rsa", "id_ed25519", "credentials.json"].includes(name)
+    || /^service-account.*\.json$/u.test(name)
+    || /\.(?:pem|key|p12|pfx|jks|keystore)$/u.test(name);
+}
+
+function excludedPath(relativePath: string): boolean {
+  const segments = relativePath.replaceAll("\\", "/").split("/");
+  return segments.some((segment, index) =>
+    (index < segments.length - 1 && EXCLUDED_DIRS.has(segment.toLocaleLowerCase()))
+    || EXCLUDED_GUIDANCE.has(segment.toLocaleLowerCase()))
+    || sensitiveEvidencePath(relativePath);
+}
+
+async function collectCandidates(projectRoot: string): Promise<string[]> {
+  const files: string[] = [];
+  const queue: Array<{ relativePath: string; depth: number }> = [{ relativePath: "", depth: 0 }];
+  let directoriesRead = 0;
+  while (queue.length && files.length < PATH_LIMIT && directoriesRead < DIRECTORY_LIMIT) {
+    const current = queue.shift()!;
+    directoriesRead += 1;
+    let entries;
+    try {
+      entries = await fs.readdir(path.join(projectRoot, current.relativePath), { withFileTypes: true });
+    } catch (error) {
+      if (!current.relativePath) throw error;
+      continue;
+    }
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      if (files.length >= PATH_LIMIT) break;
+      const relativePath = path.posix.join(current.relativePath.replaceAll("\\", "/"), entry.name);
+      if (entry.isDirectory()) {
+        if (current.depth < DEPTH_LIMIT && !EXCLUDED_DIRS.has(entry.name.toLocaleLowerCase())) {
+          queue.push({ relativePath, depth: current.depth + 1 });
+        }
+      } else if (entry.isFile() && !excludedPath(relativePath)) {
+        try {
+          const stat = await fs.lstat(path.join(projectRoot, relativePath));
+          if (stat.isFile() && !stat.isSymbolicLink() && stat.nlink === 1) files.push(relativePath);
+        } catch {
+          // Files may disappear while the bounded map is collected.
+        }
+      }
+    }
+  }
+  return files;
+}
+
+async function gitIgnoredPaths(projectRoot: string, candidates: readonly string[]): Promise<ReadonlySet<string>> {
+  if (!candidates.length) return new Set();
+  return new Promise((resolve) => {
+    let settled = false;
+    let stdout = Buffer.alloc(0);
+    const child = spawn("git", ["-C", projectRoot, "check-ignore", "--stdin", "-z"], {
+      shell: false,
+      stdio: ["pipe", "pipe", "ignore"],
+      windowsHide: true,
+    });
+    const finish = (value: ReadonlySet<string>): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      finish(new Set());
+    }, 2_000);
+    child.stdout.on("data", (chunk: Buffer) => {
+      if (stdout.length <= 256 * 1024) stdout = Buffer.concat([stdout, chunk]);
+    });
+    child.once("error", () => finish(new Set()));
+    child.once("close", (code) => {
+      if (code === 1) return finish(new Set());
+      if (code !== 0 || stdout.length > 256 * 1024 || stdout.at(-1) !== 0) return finish(new Set());
+      const candidateSet = new Set(candidates.map(evidenceKey));
+      const values = stdout.subarray(0, -1).toString("utf8").split("\0");
+      if (values.some((value) => !value || !candidateSet.has(evidenceKey(value)))) return finish(new Set());
+      finish(new Set(values.map(evidenceKey)));
+    });
+    child.stdin.on("error", () => {});
+    child.stdin.end(`${candidates.join("\0")}\0`);
+  });
+}
+
+function appendWithinLimit(current: string, section: string, limit: number): string {
+  const remaining = limit - Buffer.byteLength(current, "utf8");
+  if (remaining <= 0) return current;
+  const bytes = Buffer.from(section, "utf8");
+  return current + bytes.subarray(0, remaining).toString("utf8");
+}
+
+async function validateAndRead(projectRoot: string, absolutePath: string, limit: number): Promise<{ content: string; truncated: boolean }> {
+  const relative = path.relative(projectRoot, absolutePath);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error("path is not available to /init");
+  }
+  let current = projectRoot;
+  for (const segment of relative.split(path.sep)) {
+    current = path.join(current, segment);
+    const stat = await fs.lstat(current);
+    if (stat.isSymbolicLink()) throw new Error("/init rejects symbolic-link and junction paths");
+  }
+  const pathStat = await fs.lstat(absolutePath);
+  if (!pathStat.isFile() || pathStat.nlink !== 1) throw new Error("/init rejects linked and non-regular files");
+  const handle = await fs.open(absolutePath, "r");
+  try {
+    const openedStat = await handle.stat();
+    if (!openedStat.isFile() || openedStat.nlink !== 1
+      || openedStat.dev !== pathStat.dev || openedStat.ino !== pathStat.ino) {
+      throw new Error("/init file changed while it was being opened");
+    }
+    const buffer = Buffer.alloc(limit + 1);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    const data = buffer.subarray(0, Math.min(bytesRead, limit));
+    if (data.includes(0)) throw new Error("/init rejects binary files");
+    return { content: data.toString("utf8"), truncated: bytesRead > limit };
+  } finally {
+    await handle.close();
+  }
+}
+
+function normalizeRequestedPath(requestedPath: string): string {
+  if (!requestedPath || requestedPath.trim() !== requestedPath || requestedPath.startsWith("~")
+    || /^file:/iu.test(requestedPath) || path.isAbsolute(requestedPath)) {
+    throw new Error("path is not available to /init");
+  }
+  const normalized = requestedPath.replaceAll("\\", "/");
+  if (!normalized || normalized.split("/").some((segment) => segment === ".." || segment === "")) {
+    throw new Error("path is not available to /init");
+  }
+  return normalized.replace(/^\.\//u, "");
+}
+
+export async function buildInitEvidence(projectRoot: string): Promise<InitEvidenceBuildResult> {
+  const candidates = await collectCandidates(projectRoot);
+  const ignored = await gitIgnoredPaths(projectRoot, candidates);
+  const canonicalPaths = new Map<string, string>();
+  for (const relativePath of candidates) {
+    if (!ignored.has(evidenceKey(relativePath))) canonicalPaths.set(evidenceKey(relativePath), relativePath);
+  }
+
+  let snapshot = [
+    "# KillerOS repository snapshot",
+    "Root AGENTS.md is protected policy and is intentionally not part of this untrusted evidence.",
+    "",
+    "## Project files",
+    [...canonicalPaths.values()].join("\n"),
+  ].join("\n");
+  snapshot = appendWithinLimit("", snapshot, SNAPSHOT_LIMIT);
+  const automatic = new Set<string>(ROOT_EVIDENCE);
+  for (const relativePath of canonicalPaths.values()) {
+    const name = path.posix.basename(relativePath);
+    if (NESTED_EVIDENCE.has(name) || /^\.github\/workflows\/[^/]+\.ya?ml$/iu.test(relativePath)) automatic.add(relativePath);
+  }
+  for (const requested of automatic) {
+    const relativePath = canonicalPaths.get(evidenceKey(requested));
+    if (!relativePath || Buffer.byteLength(snapshot, "utf8") >= SNAPSHOT_LIMIT) continue;
+    try {
+      const result = await validateAndRead(projectRoot, path.join(projectRoot, relativePath), AUTOMATIC_FILE_LIMIT);
+      const suffix = result.truncated ? "\n[truncated by /init]" : "";
+      snapshot = appendWithinLimit(snapshot, `\n\n## ${relativePath}\n${result.content}${suffix}`, SNAPSHOT_LIMIT);
+    } catch {
+      // A mapped file may become unsafe or disappear before snapshot creation.
+    }
+  }
+  return { index: { projectRoot, canonicalPaths, snapshot } };
+}
+
+export async function readInitEvidence(index: InitEvidenceIndex, requestedPath: string): Promise<string> {
+  const normalized = normalizeRequestedPath(requestedPath);
+  const relativePath = index.canonicalPaths.get(evidenceKey(normalized));
+  if (!relativePath) throw new Error(`${requestedPath} is not available to /init`);
+  const result = await validateAndRead(index.projectRoot, path.join(index.projectRoot, relativePath), READ_LIMIT);
+  return result.truncated ? `${result.content}\n[truncated by /init at ${READ_LIMIT} bytes]` : result.content;
+}
+
+export async function readGeneratedInitTarget(projectRoot: string, targetPath: string): Promise<string> {
+  const result = await validateAndRead(projectRoot, targetPath, READ_LIMIT);
+  return result.truncated ? `${result.content}\n[truncated by /init at ${READ_LIMIT} bytes]` : result.content;
+}
+
+export function listInitEvidence(index: InitEvidenceIndex, requestedPath = "."): string[] {
+  const prefix = requestedPath === "." ? "" : normalizeRequestedPath(requestedPath).replace(/\/$/u, "");
+  const prefixWithSlash = prefix ? `${prefix}/` : "";
+  const children = new Set<string>();
+  let found = !prefix;
+  for (const relativePath of index.canonicalPaths.values()) {
+    if (!relativePath.startsWith(prefixWithSlash)) continue;
+    const remainder = relativePath.slice(prefixWithSlash.length);
+    if (!remainder) continue;
+    found = true;
+    children.add(remainder.split("/")[0]!);
+  }
+  if (!found) throw new Error(`${requestedPath} is not available to /init`);
+  return [...children].sort((left, right) => left.localeCompare(right)).slice(0, PATH_LIMIT);
+}