@visual-z/xeno 0.8.4 → 0.9.0

package/src/store/command.ts

@@ -1,111 +0,0 @@
-/** O.1: own the process group, preserve partial observations, and drain before returning. */
-import { captureCommandObservation } from "./observations.ts";
-import { configDir } from "./config.ts";
-import { xenoBinDir } from "./tool-binaries.ts";
-import { commandArgv, commandEnvironment, COMMAND_TERMINATION_GRACE_MS } from "../core/command-contract.ts";
-import { ToolFault, NOT_STARTED, failureDiagnostic } from "../core/tool-failure.ts";
-
-interface CommandCaptureInput {
-  cwd: string;
-  outputStore: string;
-  maxOutputBytes: number;
-  timeoutMs: number;
-  signal?: AbortSignal;
-  onOutput?: (chunk: Uint8Array) => void;
-  /** Bounded probes never transfer background children to the caller. */
-  cleanupOnExit?: boolean;
-  /** Stop capture after the crossing chunk; command cancellation still owns process cleanup. */
-  outputLimitBytes?: number;
-}
-
-export async function observeCommand(input: CommandCaptureInput & { command: string }) {
-  if (input.signal?.aborted) {
-    const empty = () => new ReadableStream<Uint8Array>({ start: controller => controller.close() });
-    const captured = await captureCommandObservation(input.outputStore, empty(), empty(), Promise.resolve(130), input.maxOutputBytes);
-    return { ...captured, wallMs: 0, stopped: "cancelled" as const, cleanup: undefined };
-  }
-  return executeCaptured(input, commandArgv(input.command), false);
-}
-
-/** Native host API: argv is never interpreted by a shell and each pipe is recoverable. */
-export async function observeArgvCommand(input: CommandCaptureInput & { argv: readonly string[] }) {
-  if (!Array.isArray(input.argv) || input.argv.length === 0 || !input.argv[0] ||
-    input.argv.some(value => typeof value !== "string" || value.includes("\0"))) {
-    throw new ToolFault("invalid_input", "native argv must contain a program and literal string arguments without NUL", NOT_STARTED);
-  }
-  if (input.signal?.aborted) throw new ToolFault("cancelled", "native command was cancelled before it started", NOT_STARTED);
-  const captured = await executeCaptured(input, [...input.argv], true);
-  if (captured.channels.length !== 2) throw new Error("missing native stdout/stderr artifacts");
-  return { ...captured, stdout: captured.channels[0]!, stderr: captured.channels[1]! };
-}
-
-async function executeCaptured(input: CommandCaptureInput, argv: string[], native: boolean) {
-  const started = performance.now();
-  const proc = (() => {
-    try { return Bun.spawn(argv, {
-      cwd: input.cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe", detached: true,
-      // Preserve the trusted native API's inherited environment; shell tools
-      // retain their explicit noninteractive policy and login-shell startup.
-      env: native ? process.env : commandEnvironment(process.env, xenoBinDir(configDir())),
-    }); } catch (error) {
-      const os = (error as { code?: string }).code;
-      throw new ToolFault(os === "ENOENT" || os === "ENOTDIR" ? "environment_missing" : os === "EACCES" || os === "EPERM" ? "permission_denied" : "execution_failed", String(error), NOT_STARTED);
-    }
-  })();
-  let stopped: "cancelled" | "timeout" | undefined;
-  let escalation: ReturnType<typeof setTimeout> | undefined;
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  let exited = false, cleaned = false;
-  let cleanupError: unknown;
-  const kill = (signal: "SIGTERM" | "SIGKILL") => {
-    try {
-      // POSIX detached children lead their own group; never signal the caller's group.
-      if (process.platform === "win32") proc.kill(signal);
-      else process.kill(-proc.pid, signal);
-    } catch (error) {
-      if ((error as { code?: string }).code !== "ESRCH") throw error;
-    }
-  };
-  const cleanup = () => {
-    if (cleaned) return;
-    cleaned = true;
-    try { kill("SIGKILL"); } catch (error) { cleanupError = error; }
-  };
-  const stop = (reason: "cancelled" | "timeout") => {
-    if (exited || stopped !== undefined) return;
-    stopped = reason;
-    kill("SIGTERM");
-    escalation = setTimeout(cleanup, COMMAND_TERMINATION_GRACE_MS);
-  };
-  const exit = proc.exited.then(code => {
-    exited = true;
-    clearTimeout(timer); clearTimeout(escalation);
-    // Clean once at the observed exit, never after slow archival when a PID
-    // might have been reused. Legacy successful bash background starts remain.
-    if (native || input.cleanupOnExit || stopped !== undefined) cleanup();
-    return code;
-  });
-  const abort = () => stop("cancelled");
-  input.signal?.addEventListener("abort", abort, { once: true });
-  timer = setTimeout(() => stop("timeout"), input.timeoutMs);
-  if (input.signal?.aborted) abort();
-  try {
-    const captured = await captureCommandObservation(input.outputStore, proc.stdout, proc.stderr,
-      exit, input.maxOutputBytes, input.onOutput, native, input.outputLimitBytes);
-    // Parent exit and archived output remain facts even if group cleanup
-    // cannot be confirmed. This is execution uncertainty, not user denial.
-    const cleanupDiagnostic = cleanupError === undefined ? undefined : failureDiagnostic("unknown_effect",
-      `process-group cleanup was not confirmed: ${String(cleanupError)}`, { execution: "started", effects: "possible" });
-    return { ...captured, wallMs: performance.now() - started, ...(stopped ? { stopped } : {}), cleanup: cleanupDiagnostic };
-  } catch (error) {
-    cleanup();
-    await proc.exited;
-    throw error;
-  } finally {
-    clearTimeout(timer);
-    clearTimeout(escalation);
-    input.signal?.removeEventListener("abort", abort);
-    // A descendant can close stdio yet ignore SIGTERM; completing capture is not proof it stopped.
-    if (stopped !== undefined) cleanup();
-  }
-}

package/src/store/config.ts

@@ -1,69 +0,0 @@
-/**
- * The user's configuration, which lives with the user and not with the project.
- *
- * `~/.xeno/` rather than the workspace's `.xeno/`. The split is not cosmetic:
- * the log and the blob store belong to one piece of work and should travel
- * with it, while a credential belongs to a person. A key written into the
- * workspace would be committed, would be seen by the snapshot scan that backs
- * `/back`, and would ship with the project.
- *
- * This layer only reads and writes files. It knows nothing about providers,
- * priority, or what a key means -- that is `runtime/auth.ts`, and keeping the
- * two apart is what lets the priority rules be tested without a filesystem.
- */
-
-import { readFile, writeFile, mkdir, chmod } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-export function configDir(): string {
-  // XENO_CONFIG_DIR exists for tests and for anyone running two configurations
-  // side by side. Read here rather than threaded through every caller, because
-  // this is the one place that turns "the user" into a path.
-  return process.env["XENO_CONFIG_DIR"] ?? join(homedir(), ".xeno");
-}
-
-export function authPath(): string {
-  return join(configDir(), "auth.json");
-}
-
-export function settingsPath(): string {
-  return join(configDir(), "settings.json");
-}
-
-/**
- * Reads a JSON config, treating "absent" and "unreadable" as empty.
- *
- * A missing config file is the normal first-run state, not an error. A
- * corrupt one is reported to the caller as absent plus a reason, because
- * silently starting with default settings after someone hand-edited a file
- * is how a typo becomes an hour of confusion.
- */
-export async function readJsonFile<T>(
-  path: string,
-): Promise<{ value: T | null; error: string | null }> {
-  let text: string;
-  try {
-    text = await readFile(path, "utf8");
-  } catch {
-    return { value: null, error: null };
-  }
-  try {
-    return { value: JSON.parse(text) as T, error: null };
-  } catch (err) {
-    return { value: null, error: `${path} is not valid JSON: ${(err as Error).message}` };
-  }
-}
-
-/**
- * Writes a config file, 0600 for the one that holds secrets.
- *
- * `chmod` after the write rather than a `mode` on the open, because an
- * existing file keeps its old permissions when reopened -- so a file created
- * before this rule existed would stay world-readable and nothing would say so.
- */
-export async function writeJsonFile(path: string, value: unknown, secret: boolean): Promise<void> {
-  await mkdir(configDir(), { recursive: true });
-  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
-  if (secret) await chmod(path, 0o600);
-}

package/src/store/context-files.ts

@@ -1,436 +0,0 @@
-/**
- * Project context files (AGENTS.md and friends) and the system prompt they
- * join.
- *
- * Two halves, kept apart because they have different reasons to change:
- *
- *   DISCOVERY is I/O. It walks directories, reads bytes, skips what it
- *   cannot, and truncates what does not fit. It runs once at process
- *   start.
- *
- *   ASSEMBLY is a pure function of those bytes. Same files in, same
- *   string out. That is what makes the ordering rules testable without
- *   a filesystem, and what makes `frozen.system` a value rather than a
- *   live view of disk.
- *
- * Re-reading these files at a node boundary would change `system` and
- * invalidate the prefix cache for the whole conversation (D6). They are
- * frozen at startup; an explicit reload checkpoints a changed prefix.
- */
-
-import { readFile, stat, lstat } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { assertNever } from "../core/exhaustive.ts";
-import { blobAddress } from "./blobs.ts";
-import { gitBytes } from "./workspace-observation.ts";
-
-/**
- * Per-file cap. Assumed, not measured: a rule file larger than this is a
- * document someone should split, not a prompt prefix. Hitting it truncates
- * that file and names it in the prompt; the omitted rules are simply not
- * followed, which is the failure mode the notice exists to make visible.
- */
-export const MAX_FILE_BYTES = 64 * 1024;
-
-/**
- * Cap on the sum of loaded context files. Assumed, not measured: 256KB of
- * instructions already crowds out the task. Hitting it truncates the file
- * that overflowed (and names it); later files may be omitted, so a huge
- * farther file can starve a nearer one.
- */
-export const MAX_TOTAL_BYTES = 256 * 1024;
-
-/**
- * Directories walked from cwd toward the workspace root, including cwd.
- * Assumed, not measured: a 32-level nest is not a project layout, it is a
- * pathologically generated tree. Hitting it drops the farther (workspace)
- * files -- the walk starts at cwd so nearer rules are kept.
- */
-export const MAX_WALK_DEPTH = 32;
-
-const AGENTS_CANDIDATES = ["AGENTS.override.md", "AGENTS.md", "CLAUDE.md"] as const;
-
-export type ContextRole = "system" | "agents" | "append";
-
-export interface LoadedFile {
-  path: string;
-  content: string;
-  /** Original size in UTF-8 bytes, before any truncation. */
-  bytes: number;
-  truncated: boolean;
-  role: ContextRole;
-}
-
-export type ContextNotice =
-  | { kind: "loaded"; path: string; truncated: boolean }
-  | { kind: "skipped"; path: string; reason: string };
-
-export interface LoadedContext {
-  /** Replacement for the builtin system prompt, if any. */
-  system: LoadedFile | null;
-  /** AGENTS.md chain, far (global) to near (cwd). */
-  agents: LoadedFile[];
-  /** APPEND_SYSTEM.md then `--append-system-prompt`, in append order. */
-  appends: LoadedFile[];
-  notices: ContextNotice[];
-}
-
-export interface LoadOptions {
-  workspace: string;
-  cwd: string;
-  /** `~/.xeno` or `XENO_CONFIG_DIR`. Injected so tests never touch the real home. */
-  configDir: string;
-  noContextFiles: boolean;
-  appendSystemPrompt: readonly string[];
-  /** Raw `--system-prompt` value. Omitted when the flag was not passed. */
-  systemPrompt?: string;
-}
-
-class Budget {
-  remaining = MAX_TOTAL_BYTES;
-
-  fit(text: string, bytes: number): { content: string; truncated: boolean } {
-    const cap = Math.min(MAX_FILE_BYTES, this.remaining);
-    if (bytes <= cap) {
-      this.remaining -= bytes;
-      return { content: text, truncated: false };
-    }
-    const content = truncateUtf8(text, cap);
-    this.remaining = Math.max(0, this.remaining - Buffer.byteLength(content, "utf8"));
-    return { content, truncated: true };
-  }
-}
-
-/**
- * Walk from cwd up to the workspace root, nearest first, then reverse so
- * assembly sees farther files first. cwd outside the workspace contributes
- * only the workspace itself -- the session is rooted there, and climbing
- * into unrelated trees would load someone else's rules.
- */
-function projectDirectories(workspace: string, cwd: string): string[] {
-  const root = resolve(workspace);
-  const start = resolve(cwd);
-  if (!isInside(start, root)) return [root];
-
-  const fromCwd: string[] = [];
-  let dir = start;
-  for (let i = 0; i < MAX_WALK_DEPTH; i++) {
-    fromCwd.push(dir);
-    if (dir === root) break;
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return fromCwd.reverse();
-}
-
-function isInside(child: string, parent: string): boolean {
-  const rel = relative(parent, child);
-  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
-}
-
-function truncateUtf8(text: string, maxBytes: number): string {
-  if (maxBytes <= 0) return "";
-  const buf = Buffer.from(text, "utf8");
-  if (buf.byteLength <= maxBytes) return text;
-  let end = maxBytes;
-  // Do not split a multibyte sequence: a dangling continuation byte is
-  // not valid UTF-8, and the model would see a replacement character in
-  // the middle of a rule.
-  while (end > 0 && (buf[end]! & 0xc0) === 0x80) end--;
-  return buf.subarray(0, end).toString("utf8");
-}
-
-type ReadResult =
-  | { status: "missing" }
-  | { status: "ok"; text: string; bytes: number }
-  | { status: "skip"; reason: string };
-
-async function tryRead(path: string): Promise<ReadResult> {
-  let buf: Buffer;
-  try {
-    buf = await readFile(path);
-  } catch (err) {
-    const code = (err as { code?: string }).code;
-    if (code === "ENOENT") return { status: "missing" };
-    if (code === "EACCES") return { status: "skip", reason: "permission denied" };
-    if (code === "EISDIR") return { status: "skip", reason: "is a directory" };
-    const message = err instanceof Error ? err.message : String(err);
-    return { status: "skip", reason: message };
-  }
-  try {
-    const text = new TextDecoder("utf-8", { fatal: true }).decode(buf);
-    return { status: "ok", text, bytes: buf.byteLength };
-  } catch {
-    return { status: "skip", reason: "not valid UTF-8" };
-  }
-}
-
-function absorbText(
-  path: string,
-  text: string,
-  role: ContextRole,
-  bytes: number,
-  budget: Budget,
-  notices: ContextNotice[],
-): LoadedFile {
-  const fitted = budget.fit(text, bytes);
-  const file: LoadedFile = {
-    path,
-    content: fitted.content,
-    bytes,
-    truncated: fitted.truncated,
-    role,
-  };
-  notices.push({ kind: "loaded", path, truncated: file.truncated });
-  return file;
-}
-
-async function absorbFile(
-  path: string,
-  role: ContextRole,
-  budget: Budget,
-  notices: ContextNotice[],
-): Promise<LoadedFile | null> {
-  const got = await tryRead(path);
-  if (got.status === "missing") return null;
-  if (got.status === "skip") {
-    notices.push({ kind: "skipped", path, reason: got.reason });
-    return null;
-  }
-  return absorbText(path, got.text, role, got.bytes, budget, notices);
-}
-
-/**
- * `--system-prompt` is text, or a file if the argument names one that
- * exists. An existing path that cannot be read is skipped (and reported)
- * rather than silently becoming the path string as the prompt.
- */
-async function absorbSystemArg(
-  value: string,
-  cwd: string,
-  budget: Budget,
-  notices: ContextNotice[],
-): Promise<LoadedFile | null> {
-  const candidate = resolve(cwd, value);
-  let file = false;
-  try {
-    file = (await stat(candidate)).isFile();
-  } catch {
-    file = false;
-  }
-  if (file) return absorbFile(candidate, "system", budget, notices);
-  return absorbText("--system-prompt", value, "system", Buffer.byteLength(value, "utf8"), budget, notices);
-}
-
-/**
- * One file per directory: override, else AGENTS.md, else CLAUDE.md.
- *
- * An unreadable chosen file does not fall through to the next name -- the
- * directory had a preference, it just could not be honoured. A name that
- * is missing or is a directory is not a preference, so the next candidate
- * is tried.
- */
-async function absorbAgentsAt(
-  dir: string,
-  budget: Budget,
-  notices: ContextNotice[],
-): Promise<LoadedFile | null> {
-  for (const name of AGENTS_CANDIDATES) {
-    const path = join(dir, name);
-    const got = await tryRead(path);
-    if (got.status === "missing") continue;
-    if (got.status === "skip") {
-      if (got.reason === "is a directory") continue;
-      notices.push({ kind: "skipped", path, reason: got.reason });
-      return null;
-    }
-    return absorbText(path, got.text, "agents", got.bytes, budget, notices);
-  }
-  return null;
-}
-
-export async function loadContext(opts: LoadOptions): Promise<LoadedContext> {
-  const budget = new Budget();
-  const notices: ContextNotice[] = [];
-  const agents: LoadedFile[] = [];
-  const appends: LoadedFile[] = [];
-
-  let system: LoadedFile | null = null;
-  if (opts.systemPrompt !== undefined) {
-    // The flag is an explicit choice. A missing/unreadable file does not
-    // fall through to SYSTEM.md -- that would make a typo in the path
-    // silently restore the project prompt.
-    system = await absorbSystemArg(opts.systemPrompt, opts.cwd, budget, notices);
-  } else {
-    system =
-      (await absorbFile(join(opts.workspace, ".xeno", "SYSTEM.md"), "system", budget, notices)) ??
-      (await absorbFile(join(opts.configDir, "SYSTEM.md"), "system", budget, notices));
-  }
-
-  if (!opts.noContextFiles) {
-    const globalAgents = await absorbFile(join(opts.configDir, "AGENTS.md"), "agents", budget, notices);
-    if (globalAgents) agents.push(globalAgents);
-    for (const dir of projectDirectories(opts.workspace, opts.cwd)) {
-      const file = await absorbAgentsAt(dir, budget, notices);
-      if (file) agents.push(file);
-    }
-  }
-
-  const globalAppend = await absorbFile(join(opts.configDir, "APPEND_SYSTEM.md"), "append", budget, notices);
-  if (globalAppend) appends.push(globalAppend);
-  const projectAppend = await absorbFile(
-    join(opts.workspace, ".xeno", "APPEND_SYSTEM.md"),
-    "append",
-    budget,
-    notices,
-  );
-  if (projectAppend) appends.push(projectAppend);
-  for (const text of opts.appendSystemPrompt) {
-    appends.push(
-      absorbText(
-        "--append-system-prompt",
-        text,
-        "append",
-        Buffer.byteLength(text, "utf8"),
-        budget,
-        notices,
-      ),
-    );
-  }
-
-  return { system, agents, appends, notices };
-}
-
-const CONTEXT_INTRO =
-  "# Project context\n\n" +
-  "These files were loaded at startup. Later files are closer to the working " +
-  "directory and take precedence.";
-
-function truncationLine(file: LoadedFile): string {
-  const included = Buffer.byteLength(file.content, "utf8");
-  const omitted = Math.max(0, file.bytes - included);
-  return `[truncated: ${file.path} exceeded a size limit; ${omitted} bytes omitted]`;
-}
-
-function escapeAttr(value: string): string {
-  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
-}
-
-function renderFile(file: LoadedFile): string {
-  const inner = file.truncated ? `${file.content}\n${truncationLine(file)}` : file.content;
-  return `<context_file path="${escapeAttr(file.path)}">\n${inner}\n</context_file>`;
-}
-
-/**
- * File contents in, prompt string out. The path of every loaded file is in
- * the result so the model can cite which rule it is following, and a
- * truncated file is named so a silent cut cannot hide.
- */
-export function assembleSystemPrompt(builtin: string, loaded: LoadedContext): string {
-  const parts: string[] = [];
-  if (loaded.system !== null) {
-    parts.push(loaded.system.content);
-    if (loaded.system.truncated) parts.push(truncationLine(loaded.system));
-  } else {
-    parts.push(builtin);
-  }
-
-  const files = [...loaded.agents, ...loaded.appends];
-  if (files.length > 0) {
-    parts.push(CONTEXT_INTRO);
-    for (const file of files) parts.push(renderFile(file));
-  }
-  return parts.join("\n\n");
-}
-
-export function formatNotice(notice: ContextNotice): string {
-  switch (notice.kind) {
-    case "loaded":
-      return notice.truncated
-        ? `context  ${notice.path}  (truncated)`
-        : `context  ${notice.path}`;
-    case "skipped":
-      return `context  skipped ${notice.path}  (${notice.reason})`;
-    default:
-      return assertNever(notice, "formatNotice");
-  }
-}
-
-/** Startup uses the actual repository instruction chain; loadContext remains explicit/compatible. */
-export async function resolveContextWorkspace(cwd: string): Promise<string> {
-  try {
-    const bytes = await gitBytes(cwd, ["--no-pager", "rev-parse", "--show-prefix"]);
-    const prefix = new TextDecoder("utf-8", { fatal: true }).decode(bytes).replace(/\n$/, "");
-    // Git canonicalizes macOS /var to /private/var. Ascending the known prefix
-    // keeps root and cwd in the same spelling, preserving the instruction chain.
-    let root = resolve(cwd);
-    const levels = prefix.split("/").filter(Boolean).length;
-    for (let level = 0; level < levels; level++) root = dirname(root);
-    return root;
-  } catch { return resolve(cwd); }
-}
-
-export interface TargetInstruction extends LoadedFile { scope: string; key: string }
-export interface TargetInstructionOptions {
-  workspace: string;
-  paths: readonly string[];
-  /** Digests from frozen startup files and durable instruction events, never model claims. */
-  known?: ReadonlySet<string>;
-  noContextFiles?: boolean;
-  /** Admission runs before instruction bytes are captured. */
-  canRead?: (path: string) => Promise<boolean>;
-}
-export const instructionKey = (file: Pick<LoadedFile, "path" | "content">): string =>
-  `${resolve(file.path)}:${blobAddress(file.content)}`;
-
-/** Target paths are explicit. No recursive scan, sibling instruction loading or prefix surgery. */
-export async function discoverTargetInstructions(options: TargetInstructionOptions): Promise<{ files: TargetInstruction[]; notices: ContextNotice[] }> {
-  if (options.noContextFiles) return { files: [], notices: [] };
-  const root = resolve(options.workspace), directories = new Set<string>();
-  for (const path of options.paths) {
-    const absolute = resolve(root, path);
-    // No workspace scope applies outside it, and another project's AGENTS.md
-    // is not this workspace's authority. Whether the target may be touched at
-    // all is the path rules' decision; throwing here pre-empted it with an
-    // internal step's name (outside-path-instructions card).
-    if (!isInside(absolute, root)) continue;
-    for (const directory of projectDirectories(root, dirname(absolute))) directories.add(directory);
-  }
-  const ordered = [...directories].sort((a, b) => a.split(sep).length - b.split(sep).length || a.localeCompare(b));
-  const files: TargetInstruction[] = [], notices: ContextNotice[] = [], budget = new Budget();
-  for (const directory of ordered) {
-    // A target directory's symlink must not import another project's ambient authority.
-    let safe = true, current = root;
-    for (const part of relative(root, directory).split(sep).filter(Boolean)) {
-      current = join(current, part);
-      try { const info = await lstat(current); if (info.isSymbolicLink() || !info.isDirectory()) { safe = false; break; } }
-      catch (error) { if ((error as { code?: string }).code !== "ENOENT") throw error; }
-    }
-    if (!safe) { notices.push({ kind: "skipped", path: directory, reason: "instruction scope crosses a symlink or non-directory" }); continue; }
-    for (const name of AGENTS_CANDIDATES) {
-      const path = join(directory, name);
-      try {
-        const info = await lstat(path);
-        if (info.isDirectory()) continue;
-        if (info.isSymbolicLink() || !info.isFile()) { notices.push({ kind: "skipped", path, reason: "instruction file must be ordinary, not a symlink" }); break; }
-      } catch (error) { if ((error as { code?: string }).code === "ENOENT") continue; throw error; }
-      if (options.canRead && !await options.canRead(path)) { notices.push({ kind: "skipped", path, reason: "instruction read permission is unavailable" }); break; }
-      const got = await tryRead(path);
-      if (got.status !== "ok") { if (got.status === "skip") notices.push({ kind: "skipped", path, reason: got.reason }); break; }
-      const file = absorbText(path, got.text, "agents", got.bytes, budget, notices), key = instructionKey(file);
-      if (!options.known?.has(key)) files.push({ ...file, scope: directory, key });
-      break;
-    }
-  }
-  return { files, notices };
-}
-
-/** Append as a durable in-context event; closer scope overrides only files under that directory. */
-export function renderTargetInstructions(files: readonly TargetInstruction[]): string {
-  if (!files.length) return "";
-  return "# Instructions discovered for the current file targets\n\n" +
-    "Apply each file only within its directory scope. Deeper directories take precedence. " +
-    "This observed version supersedes earlier versions at the same path; other scopes remain unchanged.\n\n" +
-    files.map(file => `<instruction_scope directory="${escapeAttr(file.scope)}" key="${escapeAttr(file.key)}">\n${renderFile(file)}\n</instruction_scope>`).join("\n\n");
-}