chainlesschain 0.162.162 → 0.162.164

package/src/lib/plugin-runtime/plugin-options.js

@@ -0,0 +1,151 @@
+/**
+ * Plugin OPTIONS resolution (Phase 3 gap: typed optionsSchema + sensitive
+ * project-scope gate).
+ *
+ * A plugin declares `optionsSchema` (typed config with `scope` and `sensitive`
+ * in [[capabilities.js]]). Users supply option VALUES at two scopes:
+ *   - USER scope   → user data dir `plugin-options.json` (may hold secrets)
+ *   - PROJECT scope → repo-local `.chainlesschain/plugin-options.json`
+ *     (checked-in-able → MUST NOT hold secrets)
+ *
+ * The security-critical rule (already enforced by `validateOptions`): a
+ * SENSITIVE option can never come from project config. `resolvePluginOptions`
+ * layers defaults < project (non-sensitive only) < user, DROPS + WARNS on any
+ * sensitive/user-only option that appears in project config, and returns the
+ * merged values with a redacted view for logging.
+ *
+ * Store IO is injected (`_deps`) so unit tests never touch the real dirs; the
+ * resolver itself is pure.
+ */
+
+import fs from "fs";
+import path from "path";
+import { getElectronUserDataDir } from "../paths.js";
+import {
+  optionDefaults,
+  validateOptions,
+  redactSensitiveOptions,
+} from "./capabilities.js";
+
+export const _deps = {
+  existsSync: fs.existsSync,
+  readFileSync: fs.readFileSync,
+  writeFileSync: fs.writeFileSync,
+  mkdirSync: fs.mkdirSync,
+  userStorePath: () =>
+    path.join(getElectronUserDataDir(), "plugin-options.json"),
+  projectStorePath: (cwd) =>
+    path.join(cwd || process.cwd(), ".chainlesschain", "plugin-options.json"),
+};
+
+function readJsonObject(p) {
+  try {
+    if (!_deps.existsSync(p)) return {};
+    const data = JSON.parse(_deps.readFileSync(p, "utf8"));
+    return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeJsonObject(p, obj) {
+  _deps.mkdirSync(path.dirname(p), { recursive: true });
+  _deps.writeFileSync(p, JSON.stringify(obj, null, 2), "utf8");
+}
+
+/** Load a plugin's option VALUES at the given scope (`user` | `project`). */
+export function loadPluginOptionValues(name, scope, { cwd } = {}) {
+  const p =
+    scope === "project" ? _deps.projectStorePath(cwd) : _deps.userStorePath();
+  const store = readJsonObject(p);
+  const v = store[name];
+  return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+
+/** Persist a plugin's option VALUES at a scope (replaces the plugin's entry). */
+export function setPluginOptionValues(name, values, scope, { cwd } = {}) {
+  const p =
+    scope === "project" ? _deps.projectStorePath(cwd) : _deps.userStorePath();
+  const store = readJsonObject(p);
+  store[name] = values && typeof values === "object" ? values : {};
+  writeJsonObject(p, store);
+  return { name, scope, path: p };
+}
+
+/** Provided keys of `values` (that exist in schema) accepted at `scope`. */
+function acceptedKeys(schema, values, scope) {
+  const res = validateOptions(schema, values, { scope });
+  const keys = new Set();
+  for (const key of Object.keys(values || {})) {
+    if (!Object.prototype.hasOwnProperty.call(schema, key)) continue; // unknown → ignored
+    // A provided key was accepted iff no error names it. validateOptions always
+    // quotes the offending key as `"<key>"`, so this is an exact match.
+    if (!res.errors.some((e) => e.includes(`"${key}"`))) keys.add(key);
+  }
+  return { res, keys };
+}
+
+/**
+ * PURE: resolve effective option values from defaults + project + user config.
+ *
+ * Precedence: defaults < project (non-sensitive, non-user-only) < user.
+ * A sensitive or user-only option present in project config is DROPPED and a
+ * warning is recorded — a checked-in project file can never inject a secret.
+ *
+ * @returns {{ options:object, redacted:object, warnings:string[],
+ *             sources:Record<string,'default'|'project'|'user'>,
+ *             droppedFromProject:string[] }}
+ */
+export function resolvePluginOptions(
+  schema,
+  { userValues, projectValues } = {},
+) {
+  const s = schema || {};
+  const options = optionDefaults(s);
+  const sources = {};
+  for (const key of Object.keys(options)) sources[key] = "default";
+
+  const warnings = [];
+  const droppedFromProject = [];
+
+  // Project layer first (lower precedence). validateOptions errors on sensitive/
+  // user-only keys at project scope — those are the drops we surface + refuse.
+  const proj = acceptedKeys(s, projectValues, "project");
+  for (const err of proj.res.errors) {
+    if (/sensitive|user-scoped/.test(err)) {
+      const m = err.match(/"([^"]+)"/);
+      if (m) droppedFromProject.push(m[1]);
+    }
+    warnings.push(`project: ${err}`);
+  }
+  for (const w of proj.res.warnings) warnings.push(`project: ${w}`);
+  for (const key of proj.keys) {
+    options[key] = proj.res.normalized[key];
+    sources[key] = "project";
+  }
+
+  // User layer on top (highest precedence; may carry secrets).
+  const user = acceptedKeys(s, userValues, "user");
+  for (const err of user.res.errors) warnings.push(`user: ${err}`);
+  for (const w of user.res.warnings) warnings.push(`user: ${w}`);
+  for (const key of user.keys) {
+    options[key] = user.res.normalized[key];
+    sources[key] = "user";
+  }
+
+  return {
+    options,
+    redacted: redactSensitiveOptions(s, options),
+    warnings,
+    sources,
+    droppedFromProject: [...new Set(droppedFromProject)],
+  };
+}
+
+/** Load both scopes' values from disk and resolve against a schema. */
+export function getResolvedPluginOptions(name, schema, { cwd } = {}) {
+  return resolvePluginOptions(schema, {
+    userValues: loadPluginOptionValues(name, "user", { cwd }),
+    projectValues: loadPluginOptionValues(name, "project", { cwd }),
+  });
+}

package/src/lib/plugin-runtime/policy.js

@@ -25,6 +25,7 @@
 import { enforcePluginPolicy } from "../plugin-security.js";
 import { loadManagedSettings } from "../settings-loader.cjs";
 import { verifyInstalledSignature } from "./signature.js";
+import { isPluginCapabilityConsented } from "./capability-consent.js";
 
 // Managed settings are org-admin controlled and effectively static for a
 // session, and discoverPlugins is called by every collector — memoize the load
@@ -142,6 +143,67 @@ export function filterByManagedPolicy(plugins, managed) {
   return { kept, dropped };
 }
 
+/**
+ * Whether capability-consent must be ENFORCED at load time. The consent gate
+ * ([[capability-consent.js]]) already exists but was consulted only by `cc
+ * plugin consent`/`validate`/`doctor` — a plugin that declared capabilities and
+ * was never consented still loaded all six component types. Enforcement is
+ * OPT-IN (byte-identical default): an org sets `requirePluginCapabilityConsent`
+ * in managed settings, or a single user exports `CC_REQUIRE_PLUGIN_CONSENT=1`.
+ *
+ * @param {object|null} managed  managed settings
+ * @param {object} [env]         process env (injectable)
+ * @returns {boolean}
+ */
+export function capabilityConsentRequired(managed, env) {
+  const raw = (env || process.env).CC_REQUIRE_PLUGIN_CONSENT;
+  if (raw != null && /^(1|true|yes|on)$/i.test(String(raw).trim())) return true;
+  return (
+    managed?.requirePluginCapabilityConsent === true ||
+    managed?.requirePluginCapabilityConsent === "require"
+  );
+}
+
+/**
+ * Drop plugins that DECLARE capabilities but whose current capability SET has
+ * not been consented (first request or any widening). Fail-closed: a consent
+ * check that throws drops the plugin. Legacy plugins that declare no
+ * `permissions` block are UNAFFECTED — the same "未声明 legacy 不受限" rule the
+ * declaration audit uses. A plugin whose declared set is empty (all-deny) is
+ * auto-consented by `isPluginCapabilityConsented`, so it stays.
+ *
+ * @param {Array<{name, scope, manifest}>} plugins
+ * @returns {{ kept: Array, dropped: Array<{name, reason}> }}
+ */
+export function filterByCapabilityConsent(plugins) {
+  const kept = [];
+  const dropped = [];
+  for (const p of plugins) {
+    if (!p.manifest?.capabilitiesDeclared) {
+      kept.push(p); // legacy plugin, no declaration → not gated
+      continue;
+    }
+    let consented = false;
+    try {
+      consented = isPluginCapabilityConsented(
+        { name: p.name, scope: p.scope },
+        p.manifest.capabilities,
+      );
+    } catch {
+      consented = false; // fail closed
+    }
+    if (consented) {
+      kept.push(p);
+    } else {
+      dropped.push({
+        name: p.name,
+        reason: `capabilities not consented — run \`cc plugin consent ${p.name} --grant\``,
+      });
+    }
+  }
+  return { kept, dropped };
+}
+
 let _warnedDropped = new Set();
 
 /** One-time stderr warning naming plugins an org policy blocked from loading. */

package/src/lib/plugin-runtime/scopes.js

@@ -27,6 +27,8 @@ import { parsePluginManifest } from "./manifest.js";
 import {
   loadManagedPluginPolicy,
   filterByManagedPolicy,
+  filterByCapabilityConsent,
+  capabilityConsentRequired,
   warnDroppedOnce,
 } from "./policy.js";
 
@@ -160,10 +162,24 @@ export function discoverPlugins(opts = {}) {
     env: opts.env,
     managedSettingsFile: opts.managedSettingsFile,
   });
-  if (!managed) return all;
-  const { kept, dropped } = filterByManagedPolicy(all, managed);
-  if (dropped.length > 0) warnDroppedOnce(dropped);
-  return kept;
+  const consentGate = capabilityConsentRequired(managed, opts.env);
+  // Default (no managed policy AND consent enforcement off): byte-identical —
+  // return every discovered plugin, exactly as before.
+  if (!managed && !consentGate) return all;
+  let list = all;
+  if (managed) {
+    const { kept, dropped } = filterByManagedPolicy(list, managed);
+    if (dropped.length > 0) warnDroppedOnce(dropped);
+    list = kept;
+  }
+  // Capability-consent enforcement funnels through the SAME chokepoint, so an
+  // un-consented plugin loads NONE of its six component types (opt-in).
+  if (consentGate) {
+    const { kept, dropped } = filterByCapabilityConsent(list);
+    if (dropped.length > 0) warnDroppedOnce(dropped);
+    list = kept;
+  }
+  return list;
 }
 
 // ── internals ────────────────────────────────────────────────────────────

package/src/lib/pr-automation-policy.js

@@ -0,0 +1,224 @@
+/**
+ * PR/CI automation policy — the fail-closed decision engine behind "P1-4 PR/CI
+ * Monitor、Auto-fix 与受控合并" of CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-
+ * 07-13.md.
+ *
+ * Letting an agent iterate on CI failures and merge PRs is useful and dangerous.
+ * The gap doc pins the guardrails precisely: each failing check may be auto-
+ * fixed at most N times within a token/time budget; a fix must read only the
+ * CURRENT commit's logs (never chase a stale failure); auto-merge is OFF by
+ * default and, when on, requires branch protection, all required checks, an
+ * approving review and zero pending approvals — and never pushes a protected
+ * branch directly or bypasses protection.
+ *
+ * This module is those decisions as pure predicates. It holds no state and does
+ * no I/O — a caller feeds the observed PR/CI signals and gets an allow/deny with
+ * a named reason. Everything defaults to DENY: an unknown or missing signal
+ * blocks the automation rather than assuming it is safe.
+ */
+
+/** Canonical CI check states. */
+export const CHECK_STATE = Object.freeze({
+  PASSED: "passed",
+  FAILED: "failed",
+  PENDING: "pending",
+  NEUTRAL: "neutral",
+  ERROR: "error",
+});
+
+const CHECK_ALIASES = new Map([
+  ["passed", CHECK_STATE.PASSED],
+  ["pass", CHECK_STATE.PASSED],
+  ["success", CHECK_STATE.PASSED],
+  ["succeeded", CHECK_STATE.PASSED],
+  ["green", CHECK_STATE.PASSED],
+  ["failed", CHECK_STATE.FAILED],
+  ["fail", CHECK_STATE.FAILED],
+  ["failure", CHECK_STATE.FAILED],
+  ["red", CHECK_STATE.FAILED],
+  ["pending", CHECK_STATE.PENDING],
+  ["queued", CHECK_STATE.PENDING],
+  ["in_progress", CHECK_STATE.PENDING],
+  ["running", CHECK_STATE.PENDING],
+  ["neutral", CHECK_STATE.NEUTRAL],
+  ["skipped", CHECK_STATE.NEUTRAL],
+  ["cancelled", CHECK_STATE.NEUTRAL],
+  ["canceled", CHECK_STATE.NEUTRAL],
+  ["error", CHECK_STATE.ERROR],
+  ["timed_out", CHECK_STATE.ERROR],
+  ["action_required", CHECK_STATE.ERROR],
+]);
+
+/** Normalize any provider's check conclusion/status to a canonical state. */
+export function normalizeCheckState(value) {
+  if (typeof value !== "string") return null;
+  return CHECK_ALIASES.get(value.trim().toLowerCase()) || null;
+}
+
+/** A failing state that auto-fix could act on. */
+function isFailing(state) {
+  return state === CHECK_STATE.FAILED || state === CHECK_STATE.ERROR;
+}
+
+/**
+ * Summarize a set of checks. `allPassed` is true only when there is at least one
+ * check and every one is passed or neutral (a bare PR with no checks is NOT
+ * "all passed" — required checks must actually exist and run).
+ *
+ * @param {Array<{name?:string, state?:string, conclusion?:string, status?:string}>} checks
+ */
+export function summarizeChecks(checks = []) {
+  const list = Array.isArray(checks) ? checks : [];
+  let passed = 0;
+  let failed = 0;
+  let pending = 0;
+  const byName = new Map();
+  for (const c of list) {
+    const state =
+      normalizeCheckState(c?.state) ??
+      normalizeCheckState(c?.conclusion) ??
+      normalizeCheckState(c?.status);
+    if (c?.name != null) byName.set(String(c.name), state);
+    if (state === CHECK_STATE.PASSED || state === CHECK_STATE.NEUTRAL) passed++;
+    else if (isFailing(state)) failed++;
+    else pending++; // pending / unknown → not yet decided
+  }
+  return {
+    total: list.length,
+    passed,
+    failed,
+    pending,
+    anyFailed: failed > 0,
+    allPassed: list.length > 0 && failed === 0 && pending === 0,
+    byName,
+  };
+}
+
+function budgetExhausted(budget) {
+  if (!budget || typeof budget !== "object") return false;
+  const over = (spent, cap) =>
+    cap != null && Number.isFinite(Number(cap)) && Number(spent) >= Number(cap);
+  return (
+    over(budget.tokensSpent, budget.tokenBudget) ||
+    over(budget.timeSpentMs, budget.timeBudgetMs)
+  );
+}
+
+/**
+ * Decide whether an agent may auto-fix ONE failing check right now. Fail-closed:
+ * anything unproven denies.
+ *
+ * @param {object} params
+ * @param {object} params.check           {name, state|conclusion, logCommitSha}
+ * @param {string} params.headCommitSha   the PR head the fix would target
+ * @param {number} params.iteration       fixes already attempted for this check
+ * @param {number} params.maxIterations   cap (default 3)
+ * @param {object} [params.budget]        {tokensSpent, tokenBudget, timeSpentMs, timeBudgetMs}
+ * @returns {{allow:boolean, reason:string}}
+ */
+export function autoFixDecision(params = {}) {
+  const check = params.check || {};
+  const state =
+    normalizeCheckState(check.state) ?? normalizeCheckState(check.conclusion);
+  if (!isFailing(state)) {
+    return { allow: false, reason: "check-not-failing" };
+  }
+
+  const maxIterations = Number.isFinite(Number(params.maxIterations))
+    ? Number(params.maxIterations)
+    : 3;
+  const iteration = Number(params.iteration) || 0;
+  if (iteration >= maxIterations) {
+    return { allow: false, reason: "max-iterations-reached" };
+  }
+
+  // Only fix the CURRENT failure: the log we would read must belong to the head
+  // commit. A missing/older log sha means we cannot prove freshness → deny.
+  const logSha = check.logCommitSha == null ? "" : String(check.logCommitSha);
+  const headSha =
+    params.headCommitSha == null ? "" : String(params.headCommitSha);
+  if (!logSha || !headSha) {
+    return { allow: false, reason: "commit-sha-unverifiable" };
+  }
+  if (logSha !== headSha) {
+    return { allow: false, reason: "stale-failure-log" };
+  }
+
+  if (budgetExhausted(params.budget)) {
+    return { allow: false, reason: "budget-exhausted" };
+  }
+
+  return { allow: true, reason: "ok" };
+}
+
+/**
+ * Decide whether a PR may be auto-merged. Fail-closed and exhaustive: every
+ * unmet requirement is collected, and merge is allowed ONLY when the list is
+ * empty. Auto-merge is off unless `enabled === true`.
+ *
+ * @param {object} params
+ * @param {boolean} params.enabled                  auto-merge explicitly turned on
+ * @param {boolean} params.hasOpenPr                a real PR exists (no direct-to-branch)
+ * @param {boolean} params.branchProtectionSatisfied
+ * @param {boolean} params.reviewApproved
+ * @param {number}  params.pendingApprovals         permission approvals still waiting
+ * @param {string[]} params.requiredChecks          names that must be present AND passed
+ * @param {Array}   params.checks                   observed checks (summarizeChecks input)
+ * @param {string}  [params.targetBranch]
+ * @returns {{allow:boolean, reason:string, unmet:string[]}}
+ */
+export function autoMergeDecision(params = {}) {
+  const unmet = [];
+
+  if (params.enabled !== true) unmet.push("auto-merge-disabled");
+  if (params.hasOpenPr !== true) unmet.push("no-open-pr");
+  if (params.branchProtectionSatisfied !== true) {
+    unmet.push("branch-protection-unsatisfied");
+  }
+  if (params.reviewApproved !== true) unmet.push("review-not-approved");
+  if (Number(params.pendingApprovals) > 0) unmet.push("pending-approvals");
+
+  const summary = summarizeChecks(params.checks);
+  if (summary.anyFailed) unmet.push("checks-failing");
+  if (summary.pending > 0) unmet.push("checks-pending");
+
+  // Every REQUIRED check must be present and passed — a required check that
+  // never ran is a block, not a pass.
+  const required = Array.isArray(params.requiredChecks)
+    ? params.requiredChecks
+    : [];
+  for (const name of required) {
+    const state = summary.byName.get(String(name));
+    if (state !== CHECK_STATE.PASSED && state !== CHECK_STATE.NEUTRAL) {
+      unmet.push(`required-check-missing:${name}`);
+    }
+  }
+
+  return {
+    allow: unmet.length === 0,
+    reason: unmet.length === 0 ? "ok" : unmet[0],
+    unmet,
+  };
+}
+
+/**
+ * A compact, log-safe status line for the PR status bar (P1-4 "Session 顶部提供
+ * PR 状态条"). Carries only coordinates + a checks tally, never a token.
+ *
+ * @param {object} params {branch, prNumber, checks, reviewApproved, mergeable}
+ * @returns {string}
+ */
+export function describePrStatusBar(params = {}) {
+  const parts = [];
+  if (params.branch) parts.push(`branch:${params.branch}`);
+  if (params.prNumber != null) parts.push(`PR#${params.prNumber}`);
+  const s = summarizeChecks(params.checks);
+  parts.push(`checks:${s.passed}/${s.total}${s.anyFailed ? " ✗" : ""}`);
+  parts.push(
+    `review:${params.reviewApproved === true ? "approved" : "pending"}`,
+  );
+  if (params.mergeable != null) {
+    parts.push(`merge:${params.mergeable ? "ready" : "blocked"}`);
+  }
+  return parts.join(" · ");
+}

package/src/lib/project-instructions.js

@@ -477,4 +477,132 @@ export function loadProjectInstructionsBlock(opts = {}) {
   }
 }
 
+function isDir(fs, p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Lazy subtree-instruction discovery (module 99 §5.3 "子目录指令按首次访问子树
+ * 懒加载"). Startup only loads the instruction chain from the project root DOWN
+ * to the cwd (see `findInstructionFiles`); a large monorepo's per-package
+ * `cc.md`/`CLAUDE.md`/`AGENTS.md` that sit BELOW the cwd are intentionally NOT
+ * injected up front — they cost tokens for subtrees a turn may never touch.
+ *
+ * This resolver answers "given a path a tool just accessed, which subtree
+ * instruction files should now be injected?" — the files in every directory
+ * strictly between `baseDir` (the already-loaded cwd) and the accessed path's
+ * directory, minus anything already loaded or excluded. Pure + deterministic;
+ * the tool-time injection itself is the caller's job.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot        excludes are matched relative to this
+ * @param {string} opts.baseDir         the startup cwd (its own file already loaded)
+ * @param {string} opts.accessedPath    a file/dir a tool touched (abs or rel to baseDir)
+ * @param {Set<string>|string[]} [opts.alreadyLoaded]  abs paths already injected
+ * @param {string[]} [opts.instructionExcludes]
+ * @returns {Array<{path:string, scope:"project", dir:string}>} shallowest-first
+ */
+export function resolveSubtreeInstructions(opts = {}) {
+  const { fs, path } = resolveDeps(opts);
+  const repoRoot = path.resolve(opts.repoRoot || opts.baseDir || process.cwd());
+  const baseDir = path.resolve(opts.baseDir || repoRoot);
+  const excludes = normalizeInstructionExcludes(opts.instructionExcludes);
+  const already =
+    opts.alreadyLoaded instanceof Set
+      ? opts.alreadyLoaded
+      : new Set((opts.alreadyLoaded || []).map((p) => path.resolve(p)));
+
+  if (!opts.accessedPath) return [];
+  // Resolve the accessed path to a directory inside the subtree. A not-yet-
+  // created file (about to be written) stats as neither file nor dir → treat it
+  // as a file and use its parent.
+  let target = path.resolve(baseDir, opts.accessedPath);
+  if (!isDir(fs, target)) target = path.dirname(target);
+
+  // Subtree instructions apply only to DESCENDANTS of baseDir (ancestors were
+  // loaded at startup). Reject a target that escapes baseDir or the repo.
+  const relFromBase = path.relative(baseDir, target);
+  if (
+    !relFromBase ||
+    relFromBase.startsWith("..") ||
+    path.isAbsolute(relFromBase)
+  ) {
+    return [];
+  }
+  const relFromRoot = path.relative(repoRoot, target);
+  if (relFromRoot.startsWith("..") || path.isAbsolute(relFromRoot)) return [];
+
+  // Directories strictly between baseDir (exclusive) and target (inclusive).
+  const dirs = [];
+  let dir = target;
+  while (dir !== baseDir) {
+    dirs.push(dir);
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // hit fs root without meeting baseDir
+    dir = parent;
+  }
+  dirs.reverse(); // shallowest first
+
+  const out = [];
+  for (const d of dirs) {
+    const file = firstExisting(fs, path, d, PROJECT_FILE_NAMES);
+    if (!file) continue;
+    const abs = path.resolve(file);
+    if (already.has(abs)) continue;
+    if (
+      excludes.length > 0 &&
+      pathIsExcluded(path.relative(repoRoot, abs), excludes)
+    ) {
+      continue;
+    }
+    out.push({ path: abs, scope: "project", dir: d });
+  }
+  return out;
+}
+
+/**
+ * Stateful companion to `resolveSubtreeInstructions`: tracks which subtree
+ * directories have already been injected across a session so a second access to
+ * the same subtree is a no-op. `onAccess(path)` returns ONLY the freshly
+ * discovered files. Fail-open (any error → []).
+ */
+export class SubtreeInstructionLoader {
+  constructor(opts = {}) {
+    const path = opts.deps?.path || pathDefault;
+    this._opts = opts;
+    this._loadedDirs = new Set();
+    this._loadedFiles = new Set(
+      (opts.alreadyLoaded || []).map((p) => path.resolve(p)),
+    );
+  }
+
+  /** @returns {Array<{path:string, scope:"project", dir:string}>} newly injected */
+  onAccess(accessedPath) {
+    try {
+      const found = resolveSubtreeInstructions({
+        ...this._opts,
+        accessedPath,
+        alreadyLoaded: this._loadedFiles,
+      });
+      const fresh = found.filter((f) => !this._loadedDirs.has(f.dir));
+      for (const f of fresh) {
+        this._loadedDirs.add(f.dir);
+        this._loadedFiles.add(f.path);
+      }
+      return fresh;
+    } catch {
+      return [];
+    }
+  }
+
+  /** Absolute paths injected so far (startup set + every onAccess discovery). */
+  loadedFiles() {
+    return [...this._loadedFiles];
+  }
+}
+
 export const _deps = { fs: fsDefault, path: pathDefault, os: osDefault };