@narumitw/pi-files 0.0.0-stage → 0.1.0

package/src/scope/input.ts

@@ -0,0 +1,207 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Input, matchesKey, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { runCustomInteraction } from "@narumitw/pi-tui-kit";
+import { displayError, displayPath } from "./display.js";
+import { resolveScopeTarget, type ScopeTarget } from "./paths.js";
+import { exactRows, scopeFrame } from "./ui.js";
+
+const PASTE_START = "\u001b[200~";
+const PASTE_END = "\u001b[201~";
+
+/** Public Input editing with paste-aware screen dispatch and display-only control masking. */
+export class ScopeInput {
+  readonly input: Input;
+  private pasting = false;
+  private pasteTail = "";
+  private discardPaste = false;
+
+  constructor(placeholder = "", placeholderStyle?: (text: string) => string) {
+    this.input = new Input({ placeholder, placeholderStyle });
+  }
+
+  get isPasting(): boolean {
+    return this.pasting;
+  }
+
+  handleInput(
+    data: string,
+    action: (key: string) => boolean,
+    editable = true,
+    afterPaste?: (remaining: string) => void,
+  ): void {
+    if (this.pasting || data.includes(PASTE_START)) {
+      if (!this.pasting) this.discardPaste = !editable;
+      const combined = this.pasteTail + data;
+      const start = this.pasting ? 0 : combined.indexOf(PASTE_START) + PASTE_START.length;
+      const end = combined.indexOf(PASTE_END, start);
+      if (end < 0) {
+        this.pasting = true;
+        this.pasteTail = combined.slice(-5);
+        if (!this.discardPaste) this.input.handleInput(data);
+        return;
+      }
+      const consumed = end + PASTE_END.length - this.pasteTail.length;
+      if (!this.discardPaste) this.input.handleInput(data.slice(0, consumed));
+      this.pasting = false;
+      this.discardPaste = false;
+      this.pasteTail = "";
+      const remaining = data.slice(consumed);
+      if (remaining) {
+        if (afterPaste) afterPaste(remaining);
+        else this.handleInput(remaining, action, editable);
+      }
+      return;
+    }
+    if (!action(data) && editable) this.input.handleInput(data);
+  }
+
+  render(width: number): string[] {
+    return this.withDisplayValue(() => this.input.render(width));
+  }
+
+  handleMouse(event: TuiMouseEvent) {
+    return this.withDisplayValue(() => this.input.handleMouse(event));
+  }
+
+  private withDisplayValue<T>(operation: () => T): T {
+    const raw = this.input.getValue();
+    // Native rendering and hit-testing must measure the same masked graphemes.
+    // Equal UTF-16 length preserves cursor offsets; only the display value changes.
+    const safe = raw.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, (character) => "�".repeat(character.length));
+    this.input.setValue(safe);
+    try {
+      return operation();
+    } finally {
+      this.input.setValue(raw);
+    }
+  }
+}
+
+type PathInputValue = { kind: "selected"; target: ScopeTarget } | { kind: "cancelled"; reason: "back" | "close" };
+
+interface PathInputOptions {
+  cwd: string;
+  signal: AbortSignal;
+  isCurrent(): boolean;
+}
+
+export function showScopePathInput(ctx: ExtensionCommandContext, options: PathInputOptions) {
+  return runCustomInteraction<PathInputValue>(ctx, {
+    signal: options.signal,
+    isCurrent: options.isCurrent,
+    create: ({ tui, theme, keybindings, signal: ownerSignal, complete }) => {
+      const controller = new AbortController();
+      const signal = AbortSignal.any([controller.signal, ownerSignal]);
+      const editor = new ScopeInput();
+      let error = "";
+      let pending = Promise.resolve();
+      let submitting = false;
+      let disposed = false;
+      let closing = false;
+      let focused = false;
+      let inputRow: number | undefined;
+      let frameWidth = 0;
+      const current = () => {
+        if (disposed || closing || signal.aborted) return false;
+        if (options.isCurrent()) return true;
+        closing = true;
+        // Calling the public completion boundary with stale ownership makes
+        // runCustomInteraction settle as stale and drain this component.
+        complete({ kind: "cancelled", reason: "close" });
+        controller.abort();
+        return false;
+      };
+      const close = (value: PathInputValue) => {
+        if (!current()) return;
+        closing = true;
+        complete(value);
+        controller.abort();
+      };
+      const submit = () => {
+        if (!current() || submitting) return;
+        submitting = true;
+        error = "";
+        const draft = editor.input.getValue();
+        pending = (async () => {
+          try {
+            const resolved = await resolveScopeTarget(draft, options.cwd, "new", signal);
+            if (!current()) return;
+            close({ kind: "selected", target: resolved });
+          } catch (failure) {
+            if (current()) error = displayError(failure);
+          } finally {
+            submitting = false;
+            if (current()) tui.requestRender();
+          }
+        })();
+      };
+      editor.input.onSubmit = submit;
+      editor.input.onEscape = () => close({ kind: "cancelled", reason: "back" });
+      return {
+        get focused() {
+          return focused;
+        },
+        set focused(value: boolean) {
+          focused = value;
+          editor.input.focused = value;
+        },
+        render(width: number) {
+          inputRow = undefined;
+          frameWidth = width;
+          const safeWidth = Math.max(1, width);
+          const content = [
+            ...editor.render(safeWidth),
+            ...exactRows(`Draft: ${displayPath(editor.input.getValue())}`, safeWidth).map((line) =>
+              theme.fg("muted", line),
+            ),
+            ...(error ? exactRows(error, safeWidth).map((line) => theme.fg("error", line)) : []),
+            ...(submitting ? [theme.fg("dim", "Checking target…")] : []),
+          ];
+          const priorities = [0, ...(error ? [content.length - 1] : [])];
+          // No key hints: public host listeners may consume configured keys before
+          // component dispatch. No replacement shortcuts or fallback keys are added.
+          const frame = scopeFrame(
+            tui,
+            theme,
+            width,
+            "New file",
+            [
+              `Cwd: ${displayPath(options.cwd)}`,
+              "Use a cwd-relative or full path. Submit to review; no file content is created here.",
+            ],
+            content,
+            priorities,
+            0,
+          );
+          inputRow = frame.contentRows.find((row) => row.contentIndex === 0)?.frameIndex;
+          return frame.lines;
+        },
+        handleInput(data: string) {
+          if (!current()) return;
+          const action = (key: string) => {
+            if (matchesKey(key, "ctrl+c")) close({ kind: "cancelled", reason: "close" });
+            else if (keybindings.matches(key, "tui.select.cancel")) close({ kind: "cancelled", reason: "back" });
+            else return false;
+            return true;
+          };
+          editor.handleInput(data, action, !submitting);
+          tui.requestRender();
+        },
+        handleMouse(event: TuiMouseEvent) {
+          if (!current() || submitting || event.width !== frameWidth || event.y !== inputRow) return;
+          return editor.handleMouse({ ...event, y: 0, height: 1 });
+        },
+        invalidate() {
+          inputRow = undefined;
+          editor.input.invalidate();
+        },
+        waitForPending: () => pending,
+        dispose() {
+          if (disposed) return;
+          disposed = true;
+          controller.abort();
+        },
+      };
+    },
+  });
+}

package/src/scope/menu.ts

@@ -0,0 +1,277 @@
+import { isAbsolute, relative, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu, runTask } from "@narumitw/pi-tui-kit";
+import { displayError, displayPath } from "./display.js";
+import { discoverScopeFiles } from "./files.js";
+import { showScopePathInput } from "./input.js";
+import { assertScopeTarget, resolveScopeTarget, type ScopeTarget } from "./paths.js";
+import { showScopePicker } from "./picker.js";
+import type { ScopeSettings } from "./settings.js";
+import { createSnapshot, MAX_TARGETS } from "./state.js";
+import { scopeOverlayContext } from "./ui.js";
+
+export interface ScopeView {
+  state: "inactive" | "active" | "blocked";
+  cwd: string;
+  targets: readonly ScopeTarget[];
+  error?: string;
+}
+
+export interface ScopeMenuOptions {
+  signal: AbortSignal;
+  isCurrent(): boolean;
+  getView(): ScopeView;
+  getSettings(): ScopeSettings;
+  saveShowHiddenFiles(value: boolean): Promise<void>;
+  apply(targets: readonly ScopeTarget[], newFile?: boolean, signal?: AbortSignal): Promise<void>;
+  off(): Promise<void>;
+}
+
+type Screen = "main" | "settings" | "status" | "help" | "new-review";
+type Action = "select" | "new" | "apply-new" | "hidden" | "off";
+
+function stateLines(view: ScopeView): string[] {
+  return [
+    `Cwd: ${displayPath(view.cwd)}`,
+    view.state === "inactive"
+      ? "Not restricted"
+      : `Editing limited to ${view.targets.length} file${view.targets.length === 1 ? "" : "s"}`,
+    ...(view.state === "blocked"
+      ? ["Restriction blocked: repair the allowed files or explicitly end the restriction."]
+      : []),
+    ...(view.error ? [displayError(view.error)] : []),
+  ];
+}
+
+export async function showScopeMenu(context: ExtensionCommandContext, options: ScopeMenuOptions): Promise<void> {
+  if (context.mode !== "tui" || !context.hasUI) throw new Error("/edit-scope requires interactive TUI mode.");
+  const ctx = scopeOverlayContext(context);
+  const current = () => !options.signal.aborted && options.isCurrent();
+  const notify = (error: unknown) => {
+    if (current()) ctx.ui.notify(displayError(error), "error");
+  };
+  let pendingNew: ScopeTarget | undefined;
+  const definition = defineMenu<ScopeView, Screen, Action>({
+    start: "main",
+    screens: {
+      main: ({ state }) => ({
+        kind: "actions",
+        title: "Edit Scope",
+        lines: stateLines(state),
+        hint: "close",
+        items: [
+          {
+            id: "select",
+            label: state.state === "inactive" ? "Select files…" : "Change allowed files…",
+            action: "select",
+          },
+          { id: "new", label: state.state === "inactive" ? "New file…" : "Use only a new file…", action: "new" },
+          { id: "settings", label: "Settings", to: "settings" },
+          { id: "status", label: "Status", to: "status" },
+          { id: "help", label: "Help", to: "help" },
+          ...(state.state === "inactive" ? [] : [{ id: "off", label: "End restriction", action: "off" as const }]),
+          { id: "close", label: "Close", close: true },
+        ],
+      }),
+      "new-review": ({ state }) => {
+        if (!pendingNew) throw new Error("No new-file target to review.");
+        const outside = [pendingNew.path, pendingNew.canonical].some((path) => {
+          const fromCwd = relative(state.cwd, path);
+          return isAbsolute(fromCwd) || fromCwd === ".." || fromCwd.startsWith(`..${sep}`);
+        });
+        return {
+          kind: "review",
+          title: "Review new file",
+          content: [
+            ...(state.state === "inactive" ? [] : ["This replaces the complete allowed-file set with one file."]),
+            ...(outside ? ["Outside the current directory."] : []),
+            ...(pendingNew.canonical !== pendingNew.path
+              ? ["The canonical target differs from the entered path."]
+              : []),
+            `Path: ${displayPath(pendingNew.path)}`,
+            ...(pendingNew.canonical !== pendingNew.path
+              ? [`Canonical target: ${displayPath(pendingNew.canonical)}`]
+              : []),
+            "Reserved only. The first normal write creates the file and parent directories.",
+          ].join("\n"),
+          format: { kind: "text" },
+          viewportSize: "adaptive",
+          confirm: {
+            id: "apply-new",
+            label: state.state === "inactive" ? "Start restriction" : "Replace allowed files with this new file",
+            action: "apply-new",
+          },
+          hint: "back",
+        };
+      },
+      settings: () => ({
+        kind: "settings",
+        title: "Edit Scope Settings",
+        lines: ["User setting. Changes are saved immediately."],
+        items: [
+          {
+            id: "hidden",
+            label: "Show hidden files",
+            description:
+              "Include hidden files and directories in the picker. This does not change the active restriction.",
+            currentValue: options.getSettings().showHiddenFiles ? "true" : "false",
+            values: ["false", "true"],
+            action: "hidden",
+          },
+        ],
+      }),
+      status: ({ state }) => ({
+        kind: "review",
+        title: "Edit Scope Status",
+        lines: stateLines(state),
+        content: [
+          ...state.targets.flatMap((target, index) => [
+            `${index + 1}. ${displayPath(target.path)}`,
+            ...(target.path === target.canonical ? [] : [`   Canonical: ${displayPath(target.canonical)}`]),
+          ]),
+          "",
+          "Missing selected paths are reserved. The first normal write creates the file and parent directories.",
+          "While restricted, write/edit are limited to exact allowed targets. Supported readers remain available.",
+          "Shell commands, tests, formatters, and opaque writing/delegation tools are blocked; use /edit-scope off first.",
+          "This guard is not an OS sandbox. User shell commands, other programs, filesystem races, and trusted extensions are outside its boundary.",
+        ].join("\n"),
+        format: { kind: "text" },
+        viewportSize: "adaptive",
+        hint: "back",
+      }),
+      help: () => ({
+        kind: "detail",
+        title: "Edit Scope Help",
+        lines: [
+          "Select files to start a restriction or replace the complete allowed-file set.",
+          "Typing searches files, including spaces and directory fragments. By default, Tab toggles and moves down, Shift+Tab toggles and moves up, and Enter applies the checked files. Marking stops at the first or last match. The footer follows your configured keys.",
+          "Project paths are relative to cwd by default. Use Full paths to switch views without changing the search or selected files.",
+          "Use Add file for an existing full, ~/ or relative path, including files outside cwd. This separate field preserves the search and checked draft; adding does not apply the restriction.",
+          "New file reserves one target; it replaces all allowed files and creates no content here.",
+          "Cancelling a draft, closing this menu, and run completion do not release the restriction.",
+          "Use End restriction or /edit-scope off to release it explicitly.",
+          "Discovery starts at cwd, skips symlinks and fixed generated/dependency/version-control directories, and does not use .gitignore.",
+          "Settings controls only hidden-file discovery. Selected targets remain visible even when discovery would exclude them.",
+          "Status lists every selected path and the tool limitations.",
+        ],
+        hint: "back",
+      }),
+    },
+    actions: {
+      select: async ({ signal }) => {
+        const view = options.getView();
+        const live = new Map(view.targets.map((target) => [target.path, target]));
+        const result = await showScopePicker(ctx, {
+          cwd: view.cwd,
+          targets: view.targets,
+          completionLabel: view.state === "inactive" ? "Start restriction" : "Apply changes",
+          signal,
+          isCurrent: current,
+          discover: (scanSignal) => discoverScopeFiles(view.cwd, options.getSettings().showHiddenFiles, scanSignal),
+          resolvePath: async (raw, validationSignal) => {
+            const target = await resolveScopeTarget(raw, view.cwd, "existing", validationSignal);
+            if (!current() || validationSignal.aborted)
+              throw validationSignal.reason ?? new Error("Scope flow is stale.");
+            return target;
+          },
+          validate: async (paths, validationSignal, added) => {
+            if (paths.length > MAX_TARGETS) throw new Error(`Select no more than ${MAX_TARGETS} files.`);
+            const manual = new Map(added.map((target) => [target.path, target] as const));
+            const known = new Map([...live, ...manual]);
+            const targets: ScopeTarget[] = [];
+            for (const path of paths) {
+              // Discovery/snapshots already contain lexical native paths. A file
+              // URL preserves literal Unicode spaces through Pi's raw-input resolver.
+              const nativePath = pathToFileURL(path).href;
+              const existing = known.get(path);
+              if (existing) {
+                let checked = existing;
+                if (manual.has(path)) {
+                  checked = await resolveScopeTarget(nativePath, view.cwd, "existing", validationSignal);
+                  if (!current() || validationSignal.aborted)
+                    throw validationSignal.reason ?? new Error("Scope flow is stale.");
+                  if (checked.canonical !== existing.canonical)
+                    throw new Error(`The added target changed: ${displayPath(path)}. Add it again.`);
+                }
+                await assertScopeTarget(nativePath, view.cwd, [existing], validationSignal);
+                if (!current() || validationSignal.aborted)
+                  throw validationSignal.reason ?? new Error("Scope flow is stale.");
+                targets.push(checked);
+              } else {
+                const target = await resolveScopeTarget(nativePath, view.cwd, "existing", validationSignal);
+                if (!current() || validationSignal.aborted)
+                  throw validationSignal.reason ?? new Error("Scope flow is stale.");
+                targets.push(target);
+              }
+            }
+            createSnapshot(view.cwd, targets);
+            return targets;
+          },
+        });
+        if (!current() || signal.aborted || result.kind === "stale") return { kind: "close" };
+        if (result.kind !== "completed") return { kind: "stay" };
+        if (result.value.kind === "cancelled") return { kind: result.value.reason === "close" ? "close" : "stay" };
+        if (result.value.kind === "error") {
+          notify(result.value.error);
+          return { kind: "stay" };
+        }
+        if (result.value.targets.length === 0) {
+          ctx.ui.notify("No files selected. The restriction is unchanged.", "info");
+          return { kind: "stay" };
+        }
+        const selected = result.value.targets;
+        const applied = await runTask(ctx, {
+          label: "Applying editing scope…",
+          signal,
+          isCurrent: current,
+          task: ({ signal: operation }) => options.apply(selected, false, operation),
+          onError: (_ctx, error) => notify(error),
+        });
+        return { kind: applied.kind === "completed" || applied.kind === "stale" ? "close" : "stay" };
+      },
+      new: async ({ signal }) => {
+        const view = options.getView();
+        const result = await showScopePathInput(ctx, {
+          cwd: view.cwd,
+          signal,
+          isCurrent: current,
+        });
+        if (!current() || signal.aborted || result.kind === "stale") return { kind: "close" };
+        if (result.kind !== "completed") return { kind: "stay" };
+        if (result.value.kind === "cancelled") return { kind: result.value.reason === "close" ? "close" : "stay" };
+        pendingNew = result.value.target;
+        return { kind: "to", screen: "new-review" };
+      },
+      "apply-new": async ({ signal }) => {
+        if (!current() || signal.aborted || !pendingNew) return { kind: "close" };
+        const target = pendingNew;
+        const applied = await runTask(ctx, {
+          label: "Applying new-file scope…",
+          signal,
+          isCurrent: current,
+          task: ({ signal: operation }) => options.apply([target], true, operation),
+          onError: (_ctx, error) => notify(error),
+        });
+        return { kind: applied.kind === "completed" || applied.kind === "stale" ? "close" : "stay" };
+      },
+      hidden: async ({ value, signal }) => {
+        if (!current() || signal.aborted) return { kind: "close" };
+        await options.saveShowHiddenFiles(value === "true");
+        if (!current() || signal.aborted) return { kind: "close" };
+        return { kind: "stay" };
+      },
+      off: async ({ signal }) => {
+        if (!current() || signal.aborted) return { kind: "close" };
+        await options.off();
+        return { kind: "close" };
+      },
+    },
+  });
+  await runMenu(ctx, definition, {
+    signal: options.signal,
+    isCurrent: current,
+    getState: () => options.getView(),
+    onError: (_ctx, error) => notify(error),
+  });
+}

package/src/scope/paths.ts

@@ -0,0 +1,142 @@
+import fs from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface ScopeTarget {
+  /** Normalized absolute lexical path; do not apply tool input normalization again. */
+  path: string;
+  canonical: string;
+}
+
+export interface ResolvedScopeTarget extends ScopeTarget {
+  exists: boolean;
+}
+
+// Mirrors Pi's installed utils/paths.js and tools/path-utils.js write/edit path.
+// Do not trim, normalize Unicode composition, or use the read-only macOS fallbacks.
+function normalizePath(input: string, toolPath: boolean): string {
+  let normalized = toolPath ? input.replace(/[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g, " ") : input;
+  if (toolPath && normalized.startsWith("@")) normalized = normalized.slice(1);
+  if (
+    process.platform === "win32" &&
+    normalized.startsWith("/") &&
+    !normalized.startsWith("//") &&
+    !normalized.includes("\\")
+  ) {
+    const match = normalized.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i);
+    if (match) normalized = `${match[1].toUpperCase()}:\\${match[2]?.replaceAll("/", "\\") ?? ""}`;
+  }
+  const home = homedir();
+  if (normalized === "~") return home;
+  if (normalized.startsWith("~/") || (process.platform === "win32" && normalized.startsWith("~\\"))) {
+    return join(home, normalized.slice(2));
+  }
+  return /^file:\/\//.test(normalized) ? fileURLToPath(normalized) : normalized;
+}
+
+/** The lexical target used by built-in write/edit; this does not access the filesystem. */
+export function resolveWritePath(raw: string, cwd: string): string {
+  const normalized = normalizePath(raw, true);
+  const base = normalizePath(cwd, false);
+  return isAbsolute(normalized) ? resolve(normalized) : resolve(base, normalized);
+}
+
+// Await OS work to completion before reporting cancellation; do not leave detached I/O.
+async function checked<T>(signal: AbortSignal | undefined, operation: () => Promise<T>): Promise<T> {
+  signal?.throwIfAborted();
+  try {
+    return await operation();
+  } finally {
+    signal?.throwIfAborted();
+  }
+}
+
+async function inspect(path: string, signal?: AbortSignal) {
+  try {
+    return await checked(signal, () => fs.lstat(path));
+  } catch (error) {
+    signal?.throwIfAborted();
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+/**
+ * Resolve existing files, or a missing suffix below the nearest existing directory.
+ * Symlinks may resolve to regular files/directories, but dangling links and hard-linked
+ * files are rejected. Only ENOENT means missing; permission and other errors propagate.
+ */
+export async function resolveScopeTarget(
+  raw: string,
+  cwd: string,
+  requirement: "existing" | "new" | "either",
+  signal?: AbortSignal,
+): Promise<ResolvedScopeTarget> {
+  signal?.throwIfAborted();
+  return resolveLexicalTarget(resolveWritePath(raw, cwd), requirement, signal);
+}
+
+async function resolveLexicalTarget(
+  path: string,
+  requirement: "existing" | "new" | "either",
+  signal?: AbortSignal,
+): Promise<ResolvedScopeTarget> {
+  signal?.throwIfAborted();
+  let ancestor = path;
+  const suffix: string[] = [];
+  let entry = await inspect(ancestor, signal);
+  signal?.throwIfAborted();
+  while (!entry) {
+    const parent = dirname(ancestor);
+    if (parent === ancestor) throw new Error(`No existing ancestor for scope target ${JSON.stringify(path)}.`);
+    suffix.unshift(basename(ancestor));
+    ancestor = parent;
+    entry = await inspect(ancestor, signal);
+    signal?.throwIfAborted();
+  }
+
+  // realpath must succeed even for symlinks: an ENOENT here is a dangling link,
+  // not a missing target which write is permitted to create.
+  const realAncestor = await checked(signal, () => fs.realpath(ancestor));
+  const stats = await checked(signal, () => fs.stat(realAncestor));
+  const exists = suffix.length === 0;
+  if (exists) {
+    if (!stats.isFile()) throw new Error(`Scope target must be a regular file: ${JSON.stringify(path)}.`);
+    if (stats.nlink > 1) throw new Error(`Scope does not support hard-linked files: ${JSON.stringify(path)}.`);
+  } else if (!stats.isDirectory()) {
+    throw new Error(`Scope target parent must be a directory: ${JSON.stringify(ancestor)}.`);
+  }
+  if (requirement === "existing" && !exists) {
+    throw new Error(`Scope target does not exist: ${JSON.stringify(path)}.`);
+  }
+  if (requirement === "new" && exists) {
+    throw new Error(`Scope target already exists: ${JSON.stringify(path)}.`);
+  }
+  return { path, canonical: resolve(realAncestor, ...suffix), exists };
+}
+
+/** Exact canonical matching, with fresh checks of both the reservation and mutation. */
+export async function assertScopeTarget(
+  raw: string,
+  cwd: string,
+  targets: readonly ScopeTarget[],
+  signal?: AbortSignal,
+): Promise<void> {
+  const candidate = await resolveScopeTarget(raw, cwd, "either", signal);
+  signal?.throwIfAborted();
+  const selected = targets.find((target) => target.canonical === candidate.canonical);
+  if (!selected) throw new Error("Scope blocks this target: it is not an allowed file.");
+  const refreshed = await resolveLexicalTarget(selected.path, "either", signal);
+  signal?.throwIfAborted();
+  if (refreshed.canonical !== selected.canonical) {
+    throw new Error("Scope target changed since selection. Select the allowed files again.");
+  }
+  const rechecked = await resolveScopeTarget(raw, cwd, "either", signal);
+  signal?.throwIfAborted();
+  if (rechecked.canonical !== selected.canonical) {
+    throw new Error("Scope mutation target changed during validation. Try again.");
+  }
+  // This is a trusted-extension guard, not race-free OS containment. Pi performs
+  // the mutation later; another process can still change filesystem entries.
+}