@rosetears/aili-pi 0.1.0

package/src/runtime/child-guard.ts

@@ -0,0 +1,70 @@
+import type { ExtensionAPI, ToolCallEventResult } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { lstat, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+
+interface ChildPolicy {
+  schemaVersion: 1;
+  taskId: string;
+  role: string;
+  projectRoot: string;
+  allowedTools: string[];
+  taskBoundaries: string[];
+}
+
+function loadPolicy(): ChildPolicy {
+  const path = process.env.AILI_CHILD_POLICY_FILE;
+  if (!path) throw new Error("AILI child policy is missing");
+  const policy = JSON.parse(readFileSync(path, "utf8")) as ChildPolicy;
+  if (policy.schemaVersion !== 1 || !policy.taskId || !policy.role || !policy.projectRoot || !Array.isArray(policy.allowedTools) || !Array.isArray(policy.taskBoundaries) || policy.taskBoundaries.length === 0) {
+    throw new Error("AILI child policy is malformed");
+  }
+  return policy;
+}
+
+function inside(target: string, boundary: string): boolean {
+  const rel = relative(boundary, target);
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !rel.startsWith(sep));
+}
+
+async function canonicalizeTarget(root: string, rawPath: string): Promise<string> {
+  const requested = isAbsolute(rawPath) ? rawPath : resolve(root, rawPath);
+  const missing: string[] = [];
+  let cursor = requested;
+  while (true) {
+    try {
+      await lstat(cursor);
+      const parent = await realpath(cursor);
+      return missing.reduceRight((current, segment) => resolve(current, segment), parent);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      const parent = dirname(cursor);
+      if (parent === cursor) throw error;
+      missing.push(cursor.slice(parent.length + (parent.endsWith(sep) ? 0 : 1)));
+      cursor = parent;
+    }
+  }
+}
+
+export default function registerChildGuard(pi: ExtensionAPI): void {
+  const policy = loadPolicy();
+  pi.on("tool_call", async (event): Promise<ToolCallEventResult | undefined> => {
+    try {
+      const allowed = policy.allowedTools.includes(event.toolName);
+      if (!allowed) return { block: true, reason: "AILI child denied by task/parent/role tool ceiling" };
+      if (["read", "write", "edit", "grep", "find", "ls"].includes(event.toolName)) {
+        const input = event.input as Record<string, unknown>;
+        const rawPath = typeof input.path === "string" ? input.path : policy.projectRoot;
+        const target = await canonicalizeTarget(policy.projectRoot, rawPath);
+        if (!policy.taskBoundaries.some((boundary) => inside(target, boundary))) {
+          return { block: true, reason: "AILI child denied outside the explicit task path boundary" };
+        }
+      } else if (event.toolName === "bash" && !policy.taskBoundaries.includes(policy.projectRoot)) {
+        return { block: true, reason: "AILI child denied bash because the task path boundary is narrower than the project root" };
+      }
+      return undefined;
+    } catch {
+      return { block: true, reason: "AILI child denied by classification.error.fail-closed" };
+    }
+  });
+}

package/src/runtime/conflicts.ts

@@ -0,0 +1,25 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { LIFECYCLE_PROMPTS } from "./lifecycle.js";
+
+export interface ResourceConflict {
+  name: string;
+  sources: Array<{ source: string; path: string }>;
+}
+
+function baseName(name: string): string {
+  return name.replace(/:\d+$/, "");
+}
+
+export function detectLifecycleConflicts(commands: ReturnType<ExtensionAPI["getCommands"]>): ResourceConflict[] {
+  return LIFECYCLE_PROMPTS.flatMap((name) => {
+    const matches = commands.filter((command) => baseName(command.name) === name);
+    if (matches.length === 1 && matches[0]?.source === "prompt") return [];
+    return [{
+      name,
+      sources: matches.map((command) => ({
+        source: `${command.source}:${command.sourceInfo.source}`,
+        path: command.sourceInfo.path,
+      })),
+    }];
+  });
+}

package/src/runtime/contracts.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export type RuntimeAvailability = "available" | "unverified" | "blocked";
+
+export interface RuntimeComponent {
+  id: string;
+  availability: RuntimeAvailability;
+  register?: (pi: ExtensionAPI) => void | Promise<void>;
+}

package/src/runtime/doctor.ts

@@ -0,0 +1,134 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readFile } from "node:fs/promises";
+import { detectLifecycleConflicts } from "./conflicts.js";
+import { loadRegistry, validateProvenance, validateRegistry } from "./registry.js";
+import { inspectGlobalResources } from "./global-resources.js";
+import { nativeIntegrationDiagnostics } from "./native-integrations.js";
+import { subagentDiagnostics } from "./subagents.js";
+
+export type DoctorStatus = "PASS" | "WARN" | "SKIP" | "ERROR" | "UNVERIFIED";
+
+export interface DoctorResult {
+  id: string;
+  status: DoctorStatus;
+  evidence: string;
+}
+
+export interface DoctorReport {
+  schemaVersion: 1;
+  status: "PASS" | "NON_PASS";
+  results: DoctorResult[];
+}
+
+const ROOT = new URL("../../", import.meta.url);
+
+export async function runDoctor(
+  pi: Pick<ExtensionAPI, "getCommands">,
+  options: { platform?: NodeJS.Platform } = {},
+): Promise<DoctorReport> {
+  const results: DoctorResult[] = [];
+  try {
+    const packageJson = JSON.parse(await readFile(new URL("package.json", ROOT), "utf8")) as {
+      version?: string;
+      engines?: { node?: string };
+      pi?: { extensions?: string[]; prompts?: string[]; skills?: string[] };
+    };
+    const dependencies = (packageJson as { dependencies?: Record<string, string> }).dependencies ?? {};
+    const expectedDependencies = ["@agwab/pi-subagent@0.4.8", "pi-permission-modes@2.2.0", "pi-quota-status@0.3.0", "pi-web-access@0.13.0"];
+    const dependencyState = expectedDependencies.every((entry) => {
+      const separator = entry.lastIndexOf("@");
+      return dependencies[entry.slice(0, separator)] === entry.slice(separator + 1);
+    });
+    results.push({ id: "package", status: dependencyState ? "PASS" : "ERROR", evidence: `version=${packageJson.version ?? "unverified"}; node=${packageJson.engines?.node ?? "unverified"}; native_dependencies=${dependencyState ? "exact" : "drift"}` });
+    const resources = [...(packageJson.pi?.extensions ?? []), ...(packageJson.pi?.prompts ?? []), ...(packageJson.pi?.skills ?? [])];
+    results.push({ id: "package.resources", status: resources.length === 8 ? "PASS" : "ERROR", evidence: `declared=${resources.length}` });
+  } catch (error) {
+    results.push({ id: "package", status: "ERROR", evidence: boundedError(error) });
+  }
+
+  try {
+    const lock = JSON.parse(await readFile(new URL("upstream/aili-workflows.lock.json", ROOT), "utf8")) as {
+      commit?: string; contentHash?: string; skillCount?: number; fileCount?: number;
+    };
+    results.push({ id: "skill.snapshot", status: lock.commit && lock.contentHash ? "PASS" : "ERROR", evidence: `commit=${lock.commit ?? "missing"}; hash=${lock.contentHash ?? "missing"}; skills=${lock.skillCount ?? "missing"}; files=${lock.fileCount ?? "missing"}` });
+  } catch (error) {
+    results.push({ id: "skill.snapshot", status: "ERROR", evidence: boundedError(error) });
+  }
+
+  const conflicts = detectLifecycleConflicts(pi.getCommands());
+  results.push({ id: "rose.prompts", status: conflicts.length === 0 ? "PASS" : "ERROR", evidence: conflicts.length === 0 ? "five lifecycle/review prompts have unique ownership" : `conflicts=${conflicts.map((item) => item.name).join(",")}` });
+
+  try {
+    const errors = await validateRegistry();
+    const { capabilities, compatibility } = await loadRegistry();
+    results.push({ id: "capability.registry", status: errors.length === 0 ? "PASS" : "ERROR", evidence: errors.length === 0 ? `capabilities=${capabilities.capabilities.length}; skills=${compatibility.records.length}` : errors.slice(0, 5).join("; ") });
+    const optional = capabilities.capabilities.filter((item) => item.class === "optional");
+    results.push({ id: "optional.packs", status: "SKIP", evidence: optional.map((item) => `${item.id}:${item.optionalPack?.id}`).join(",") });
+  } catch (error) {
+    results.push({ id: "capability.registry", status: "ERROR", evidence: boundedError(error) });
+  }
+
+  const staticSubagents = await subagentDiagnostics();
+  results.push({ id: "roles.subagents", ...staticSubagents });
+  results.push({ id: "permission.native", ...nativeIntegrationDiagnostics(pi.getCommands()) });
+  try {
+    const global = await inspectGlobalResources();
+    const ready = global.appendSystem === "installed" && global.roles.missing.length === 0;
+    results.push({ id: "global.resources", status: ready ? "PASS" : "UNVERIFIED", evidence: `append=${global.appendSystem}; roles=${global.roles.installed}/${global.roles.expected}; stale=${global.roles.stale.length}; path=${global.roleDirectory}` });
+  } catch (error) {
+    results.push({ id: "global.resources", status: "ERROR", evidence: boundedError(error) });
+  }
+  const platform = options.platform ?? process.platform;
+  results.push({ id: "platform", status: platform === "linux" ? "PASS" : "ERROR", evidence: `platform=${platform}; supported=linux; node=${process.version}` });
+  const provenanceErrors = await validateProvenance();
+  results.push({ id: "provenance", status: provenanceErrors.length === 0 ? "PASS" : "ERROR", evidence: provenanceErrors.length === 0 ? "notices and SPDX SBOM are complete" : provenanceErrors.slice(0, 3).join("; ") });
+
+  return {
+    schemaVersion: 1,
+    status: results.every((item) => item.status === "PASS" || item.status === "SKIP") ? "PASS" : "NON_PASS",
+    results,
+  };
+}
+
+export async function runBoundedProbe(
+  id: string,
+  timeoutMs: number,
+  probe: () => Promise<string>,
+): Promise<DoctorResult> {
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    const evidence = await Promise.race([
+      probe(),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`probe timeout after ${timeoutMs}ms`)), timeoutMs);
+      }),
+    ]);
+    if (typeof evidence !== "string" || evidence.trim() === "") {
+      return { id, status: "UNVERIFIED", evidence: "probe returned malformed or empty evidence" };
+    }
+    return { id, status: "PASS", evidence: evidence.slice(0, 240) };
+  } catch (error) {
+    return { id, status: "ERROR", evidence: boundedError(error) };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+export function formatDoctorReport(report: DoctorReport): string {
+  return [`AILI doctor: ${report.status}`, ...report.results.map((item) => `${item.status.padEnd(10)} ${item.id}: ${item.evidence}`)].join("\n");
+}
+
+function boundedError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.replace(/[\r\n]+/g, " ").slice(0, 240);
+}
+
+export function registerDoctor(pi: ExtensionAPI): void {
+  pi.registerCommand("aili-doctor", {
+    description: "Report AILI runtime health (append --json for machine-readable output)",
+    handler: async (args, context) => {
+      const report = await runDoctor(pi);
+      context.ui.notify(args.trim() === "--json" ? JSON.stringify(report, null, 2) : formatDoctorReport(report), report.status === "PASS" ? "info" : "warning");
+    },
+  });
+}

package/src/runtime/global-resources.ts

@@ -0,0 +1,152 @@
+import { lstat, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadRoleProfiles, type RoleProfile } from "./roles.js";
+
+const ROOT = new URL("../../", import.meta.url);
+export const ROSE_MARKER_START = "<!-- AILI-PI:ROSE:START -->";
+export const ROSE_MARKER_END = "<!-- AILI-PI:ROSE:END -->";
+
+export interface GlobalResourceReport {
+  appendSystemPath: string;
+  roleDirectory: string;
+  appendSystem: "missing" | "installed" | "malformed";
+  roles: { expected: number; installed: number; missing: string[]; stale: string[] };
+}
+
+export interface GlobalResourceInstallResult extends GlobalResourceReport {
+  appended: "created" | "updated" | "unchanged";
+  writtenRoles: string[];
+}
+
+export function globalResourcePaths(home = homedir()): { appendSystemPath: string; roleDirectory: string } {
+  const agentDirectory = join(home, ".pi", "agent");
+  return {
+    appendSystemPath: join(agentDirectory, "APPEND_SYSTEM.md"),
+    roleDirectory: join(agentDirectory, "agents", "aili"),
+  };
+}
+
+function markerState(content: string): "missing" | "installed" | "malformed" {
+  const starts = content.split(ROSE_MARKER_START).length - 1;
+  const ends = content.split(ROSE_MARKER_END).length - 1;
+  if (starts === 0 && ends === 0) return "missing";
+  if (starts === 1 && ends === 1 && content.indexOf(ROSE_MARKER_START) < content.indexOf(ROSE_MARKER_END)) return "installed";
+  return "malformed";
+}
+
+async function readOptional(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+async function requireRealDirectory(path: string): Promise<void> {
+  try {
+    const info = await lstat(path);
+    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error(`global resource directory is not a real directory: ${path}`);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+}
+
+async function expectedRoles(): Promise<RoleProfile[]> {
+  return await loadRoleProfiles();
+}
+
+export async function inspectGlobalResources(home = homedir()): Promise<GlobalResourceReport> {
+  const { appendSystemPath, roleDirectory } = globalResourcePaths(home);
+  const roles = await expectedRoles();
+  const appendContent = await readOptional(appendSystemPath);
+  const missing: string[] = [];
+  let installed = 0;
+  for (const role of roles) {
+    const content = await readOptional(join(roleDirectory, `${role.name}.md`));
+    if (content === undefined) missing.push(role.name);
+    else if (content === await readFile(new URL(role.profilePath, ROOT), "utf8")) installed += 1;
+    else missing.push(role.name);
+  }
+  let stale: string[] = [];
+  try {
+    const files = await readdir(roleDirectory);
+    const expected = new Set(roles.map((role) => `${role.name}.md`));
+    stale = files.filter((file) => file.endsWith(".md") && !expected.has(file)).sort();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  return {
+    appendSystemPath,
+    roleDirectory,
+    appendSystem: appendContent === undefined ? "missing" : markerState(appendContent),
+    roles: { expected: roles.length, installed, missing, stale },
+  };
+}
+
+function updatedAppendSystem(existing: string | undefined, block: string): { content: string; action: "created" | "updated" | "unchanged" } {
+  if (existing === undefined) return { content: `${block}\n`, action: "created" };
+  const state = markerState(existing);
+  if (state === "malformed") throw new Error("APPEND_SYSTEM.md contains malformed AILI marker boundaries; no mutation was made");
+  if (state === "missing") return { content: `${existing.replace(/\s*$/, "")}\n\n${block}\n`, action: "updated" };
+  const start = existing.indexOf(ROSE_MARKER_START);
+  const end = existing.indexOf(ROSE_MARKER_END) + ROSE_MARKER_END.length;
+  const content = `${existing.slice(0, start)}${block}${existing.slice(end)}`;
+  return { content, action: content === existing ? "unchanged" : "updated" };
+}
+
+/**
+ * Explicit global-resource operation. Package load never calls this function.
+ * Callers must obtain the user approval required for the exact home-directory
+ * target before invoking it outside a disposable test home.
+ */
+export async function installGlobalResources(home = homedir()): Promise<GlobalResourceInstallResult> {
+  const { appendSystemPath, roleDirectory } = globalResourcePaths(home);
+  const roles = await expectedRoles();
+  const template = await readFile(new URL("templates/APPEND_SYSTEM.md", ROOT), "utf8");
+  const existingAppend = await readOptional(appendSystemPath);
+  const append = updatedAppendSystem(existingAppend, template.trim());
+  const roleContents = await Promise.all(roles.map(async (role) => ({ role, content: await readFile(new URL(role.profilePath, ROOT), "utf8") })));
+
+  await requireRealDirectory(join(home, ".pi"));
+  await requireRealDirectory(join(home, ".pi", "agent"));
+  await requireRealDirectory(join(home, ".pi", "agent", "agents"));
+  await requireRealDirectory(roleDirectory);
+  for (const { role, content } of roleContents) {
+    const target = join(roleDirectory, `${role.name}.md`);
+    const existing = await readOptional(target);
+    if (existing !== undefined && existing !== content) {
+      throw new Error(`global role collision at ${target}; no mutation was made`);
+    }
+  }
+
+  await mkdir(join(home, ".pi", "agent", "agents"), { recursive: true });
+  await mkdir(roleDirectory, { recursive: true });
+  if (append.action !== "unchanged") await writeFile(appendSystemPath, append.content, "utf8");
+  const writtenRoles: string[] = [];
+  for (const { role, content } of roleContents) {
+    const target = join(roleDirectory, `${role.name}.md`);
+    if ((await readOptional(target)) === undefined) {
+      await writeFile(target, content, { encoding: "utf8", mode: 0o600 });
+      writtenRoles.push(role.name);
+    }
+  }
+  return { ...(await inspectGlobalResources(home)), appended: append.action, writtenRoles };
+}
+
+export function registerGlobalResourceCommand(pi: import("@earendil-works/pi-coding-agent").ExtensionAPI): void {
+  pi.registerCommand("aili-install-global-resources", {
+    description: "Explicitly install the AILI-owned APPEND_SYSTEM marker block and global AILI role profiles",
+    handler: async (_args, context) => {
+      try {
+        const result = await installGlobalResources();
+        context.ui.notify(`AILI global resources: append=${result.appended}; roles_written=${result.writtenRoles.length}; stale=${result.roles.stale.length}`, "info");
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        context.ui.notify(`AILI global resources: ${message.slice(0, 240)}`, "error");
+      }
+    },
+  });
+}

package/src/runtime/index.ts

@@ -0,0 +1,23 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { RuntimeComponent } from "./contracts.js";
+import { registerRoseContext } from "./rose-context.js";
+import { registerDoctor } from "./doctor.js";
+import { registerAiliTask } from "./subagents.js";
+import { registerNativeIntegrations } from "./native-integrations.js";
+import { registerGlobalResourceCommand } from "./global-resources.js";
+
+export const runtimeComponents: readonly RuntimeComponent[] = [
+  { id: "rose-context", availability: "available", register: registerRoseContext },
+  { id: "lifecycle-routing", availability: "available" },
+  { id: "task-runtime", availability: "available", register: registerAiliTask },
+  { id: "native-integrations", availability: "available", register: registerNativeIntegrations },
+  { id: "global-resources", availability: "available", register: registerGlobalResourceCommand },
+  { id: "capability-registry", availability: "available" },
+  { id: "doctor", availability: "available", register: registerDoctor },
+  { id: "shortcuts", availability: "available" },
+  { id: "status", availability: "available" },
+] as const;
+
+export async function registerAiliRuntime(pi: ExtensionAPI): Promise<void> {
+  for (const component of runtimeComponents) await component.register?.(pi);
+}

package/src/runtime/lifecycle.ts

@@ -0,0 +1,19 @@
+export const DELIVERY_MODES = ["IDEATE", "DEFINE", "BUILD", "SHIP"] as const;
+export const LIFECYCLE_PROMPTS = ["ideate", "define", "build", "ship", "local-review"] as const;
+
+export type DeliveryMode = (typeof DELIVERY_MODES)[number];
+
+const intentPatterns: Array<[DeliveryMode, RegExp]> = [
+  ["IDEATE", /\b(ideate|brainstorm|explore an idea|shape an idea)\b/i],
+  ["DEFINE", /\b(define|specify|write (?:a )?spec|requirements|test plan)\b/i],
+  ["BUILD", /\b(build|implement|apply (?:the )?change)\b/i],
+  ["SHIP", /\b(ship|release readiness|launch readiness)\b/i],
+];
+
+export function detectLifecycleIntent(input: string): DeliveryMode | undefined {
+  const slash = input.match(/^\s*\/(ideate|define|build|ship)\b/i)?.[1]?.toUpperCase() as
+    | DeliveryMode
+    | undefined;
+  if (slash) return slash;
+  return intentPatterns.find(([, pattern]) => pattern.test(input))?.[0];
+}

package/src/runtime/native-integrations.ts

@@ -0,0 +1,44 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type NativeExtension = (pi: ExtensionAPI) => void | Promise<void>;
+
+export const NATIVE_INTEGRATIONS = [
+  "pi-permission-modes@2.2.0",
+  "pi-quota-status@0.3.0",
+  "pi-web-access@0.13.0",
+] as const;
+
+/**
+ * Initialise the pinned upstream extensions through AILI's single package entry.
+ * They remain upstream-owned implementations; this module adds no substitute
+ * command, tool, permission, or provider behavior.
+ */
+export async function registerNativeIntegrations(pi: ExtensionAPI): Promise<void> {
+  for (const moduleName of [
+    "pi-permission-modes/src/index.ts",
+    "pi-quota-status",
+    "pi-web-access",
+  ]) {
+    const loaded = await import(moduleName) as { default?: unknown };
+    if (typeof loaded.default !== "function") {
+      throw new Error(`${moduleName} does not expose an Extension default export`);
+    }
+    await (loaded.default as NativeExtension)(pi);
+  }
+}
+
+export function nativeIntegrationDiagnostics(commands: ReturnType<ExtensionAPI["getCommands"]>): {
+  status: "PASS" | "ERROR";
+  evidence: string;
+} {
+  const names = commands.map((command) => command.name);
+  const missing = ["perm"].filter((name) => !names.includes(name));
+  const legacy = names.filter((name) => name === "aili-mode");
+  if (missing.length > 0 || legacy.length > 0) {
+    return {
+      status: "ERROR",
+      evidence: `missing=${missing.join(",") || "none"}; legacy=${legacy.join(",") || "none"}`,
+    };
+  }
+  return { status: "PASS", evidence: NATIVE_INTEGRATIONS.join(",") };
+}

package/src/runtime/path-boundaries.ts

@@ -0,0 +1,69 @@
+import { lstat, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+
+export interface CanonicalTarget {
+  canonicalRoot: string;
+  canonicalTarget: string;
+  insideProject: boolean;
+  protectedCredential: boolean;
+}
+
+export async function canonicalizeTarget(cwd: string, rawTarget: string): Promise<CanonicalTarget> {
+  const canonicalRoot = await realpathOrResolve(cwd);
+  const expanded = rawTarget === "~" ? homedir() : rawTarget.startsWith(`~${sep}`) ? resolve(homedir(), rawTarget.slice(2)) : rawTarget;
+  const lexicalTarget = isAbsolute(expanded) ? resolve(expanded) : resolve(canonicalRoot, expanded);
+  const canonicalTarget = await resolveThroughExistingParent(lexicalTarget);
+  const projectRelative = relative(canonicalRoot, canonicalTarget);
+  return {
+    canonicalRoot,
+    canonicalTarget,
+    insideProject: projectRelative === "" || (!projectRelative.startsWith(`..${sep}`) && projectRelative !== ".." && !isAbsolute(projectRelative)),
+    protectedCredential: isProtectedCredentialPath(lexicalTarget) || isProtectedCredentialPath(canonicalTarget),
+  };
+}
+
+async function resolveThroughExistingParent(target: string): Promise<string> {
+  const missing: string[] = [];
+  let current = target;
+  while (true) {
+    try {
+      await lstat(current);
+      return resolve(await realpath(current), ...missing.reverse());
+    } catch (error) {
+      if (!isMissingPathError(error)) throw error;
+      const parent = dirname(current);
+      if (parent === current) return resolve(target);
+      missing.push(current.slice(parent.length + (parent.endsWith(sep) ? 0 : 1)));
+      current = parent;
+    }
+  }
+}
+
+async function realpathOrResolve(path: string): Promise<string> {
+  try {
+    return await realpath(path);
+  } catch (error) {
+    if (!isMissingPathError(error)) throw error;
+    return resolve(path);
+  }
+}
+
+function isMissingPathError(error: unknown): boolean {
+  return error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+function isProtectedCredentialPath(path: string): boolean {
+  const normalized = path.replaceAll("\\", "/").toLowerCase();
+  const basename = normalized.split("/").at(-1) ?? "";
+  if (/^\.env(?:\..+)?$/.test(basename)) return true;
+  if (basename === ".envrc" || /^(?:secrets?|service[-_]?account|[a-z0-9._-]*(?:secret|credential|auth)[a-z0-9._-]*)\.(?:json|ya?ml)$/.test(basename)) return true;
+  if (/^(?:auth\.json|credentials(?:\.json)?|\.git-credentials|\.npmrc|\.pypirc|\.netrc|id_rsa|id_ed25519)$/.test(basename)) return true;
+  if (/\.(?:pem|key|p12|pfx)$/.test(basename)) return true;
+  if (/(?:^|\/)\.(?:ssh|aws|azure|gnupg)(?:\/|$)/.test(normalized)) return true;
+  if (/(?:^|\/)\.pi\/agent\/auth\.json$/.test(normalized)) return true;
+  if (/(?:^|\/)\.config\/(?:gh|gcloud|glab-cli|opencode)(?:\/|$)/.test(normalized)) return true;
+  if (/(?:^|\/)\.docker\/config\.json$/.test(normalized)) return true;
+  if (/(?:^|\/)\.kube\/config$/.test(normalized)) return true;
+  return /(?:^|\/)\.git\/(?:config|credentials)$/.test(normalized);
+}