@gajae-code/coding-agent 0.16.4 → 0.16.6

package/src/crash/sanitize.ts

@@ -40,7 +40,7 @@ const INVISIBLE_PATTERN = new RegExp(INVISIBLE_CLASS, "g");
 // residual scanner that silently alternates verdicts is worse than none.
 const CONTROL_PROBE = new RegExp(CONTROL_CLASS);
 const INVISIBLE_PROBE = new RegExp(INVISIBLE_CLASS);
-const URL_PATTERN = /\b[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s<>"'`)\]]+/g;
+const URL_PATTERN = /(?<![A-Za-z0-9+.-])[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s<>"'`)\]]+/g;
 /** Anything still matching these after sanitization means the scanner is not certain. */
 const RESIDUAL_PATTERNS: readonly RegExp[] = [
 	/\bsk-[A-Za-z0-9_-]{8,}/,

package/src/defaults/gjc/skills/ultragoal/SKILL.md

@@ -442,6 +442,28 @@ Receipts are freshness-scoped:
 - Appending required goals or changing final required-goal state stales final aggregate receipts. Final aggregate completion requires a fresh final aggregate receipt proving no incomplete, blocked, or `review_blocked` required goals remain.
 - Deferred per-goal receipts (validation-batch members) are incomplete until a matching fresh batch-close receipt exists on the batch's `finalGoalId`; a story-scope query for a deferred member stays blocked until that close, and mutating a member after close stales the batch-close and final aggregate receipts.
 
+## Cross-repository succession
+
+When an approved run was planned in one repository but the implementation belongs in another, the repository-binding guard correctly refuses to execute the plan from the second repository. Never edit `repositoryBinding` and never copy the runtime directory: both defeat the boundary and launder verification provenance. Use the explicit successor path instead.
+
+```
+gjc ultragoal succession offer --target-repo <path> --goal-id G002 --goal-id G003 --authorize "<who approved what, for which source, target and goals>" --authorized-by <identity> --json
+gjc ultragoal succession adopt --offer <offer path inside the source worktree> --json
+gjc ultragoal succession status --json
+```
+
+`offer` runs in the source repository. It records an offer document plus a durable outgoing ownership fence, and writes nothing to `brief.md`, `goals.json` or `ledger.jsonl`. From that moment the source run refuses to schedule or checkpoint the fenced goals; goals outside the selection stay fully schedulable. Ownership therefore leaves the source at the offer, not when the target happens to adopt, so no interval exists in which both runs may resume the same goal. There is deliberately no `revoke` verb: any read-then-delete of the fence races a concurrent adoption and could revive the source while the target is starting, so an unadopted offer keeps its goals fenced.
+
+Because unselected goals stay schedulable, ordinary source progress moves whole-file digests. Adoption therefore compares a **snapshot of the offered work** — the brief plus each selected goal's record and unresolved obligations — instead of whole-file equality, so unrelated progress cannot permanently strand the handed-off work. Whole-file digests are still recorded as provenance and any drift is written into the adoption record.
+
+`adopt` runs in the target repository and starts a genuinely fresh run: new pending goals, fresh timestamps, the target repository's own binding, and no inherited receipts, quality gates, validation batches, steering or activated objective. The source brief and every selected objective are carried verbatim, together with the unresolved obligations recorded against those goals — requirements are carried forward in full, never summarized down. Dependency groups travel as explicit obligations with source-to-target id mapping: the source's batch metadata and receipts are not inherited, but the requirement to validate those goals together is.
+
+Selection and authorization must be explicit. Only unfinished goals (`pending`, `failed`, `blocked`, `review_blocked`) may be handed off; the source run must be quiescent with no `active` goal; there is no implicit or wildcard selection; and a selection that takes only part of a validation batch, or splits a review blocker from the goal it still blocks, is rejected rather than silently dropping that obligation. Adoption fails closed on changed offered work, an altered or unfenced offer, an offer path that escapes the source worktree, a target the offer does not name, a linked worktree that is not the exact named target, an occupied target session, and any duplicate or simultaneous adoption anywhere in the target repository. A retry reconciles the exact recorded operation or fails closed — a matching operation id is never authority to overwrite target work it did not write, and a published plan that has disappeared is never reconstructed.
+
+Until publication completes, the target refuses to execute: a visible `goals.json` is not admission evidence, the adoption record is. `start`/`complete-goals` and `checkpoint` reject while an adoption remains pending.
+
+Integrity digests are evidence, not authorization: a matching digest set with no fence, no bounded authorization, or the wrong target is still rejected. Historical source statuses, receipts, reviews and approvals travel as provenance only and never satisfy a target gate.
+
 ## Handoff back to planning
 
 When the aggregate ultragoal is complete OR the user requests return to planning/clarification, mark ultragoal ready for handoff so the skill tool's chain guard permits the backward transition:

package/src/discovery/builtin.ts

@@ -28,8 +28,11 @@ import {
 	createSourceMeta,
 	discoverExtensionModulePaths,
 	expandEnvVarsDeep,
+	getAncestorDirs,
 	getExtensionNameFromPath,
+	getUserSkillScanDirs,
 	loadFilesFromDir,
+	readContainedFile,
 	SOURCE_PATHS,
 	scanSkillsFromDir,
 } from "./helpers";
@@ -41,10 +44,6 @@ const PRIORITY = 100;
 
 const PATHS = SOURCE_PATHS.native;
 
-function getUserAgentDirs(): string[] {
-	return [PATHS.userAgent];
-}
-
 /**
  * GJC's user-scope config directory.
  *
@@ -92,26 +91,12 @@ async function getConfigDirs(ctx: LoadContext): Promise<Array<{ dir: string; lev
 	return result;
 }
 
-function getAncestorDirs(cwd: string, stopAt?: string | null): Array<{ dir: string; depth: number }> {
-	const ancestors: Array<{ dir: string; depth: number }> = [];
-	let current = cwd;
-	let depth = 0;
-	while (true) {
-		ancestors.push({ dir: current, depth });
-		if (stopAt && current === stopAt) break;
-		const parent = path.dirname(current);
-		if (parent === current) break;
-		current = parent;
-		depth++;
-	}
-	return ancestors;
-}
-
 async function findNearestProjectConfigDir(
 	cwd: string,
 	repoRoot?: string | null,
+	home?: string,
 ): Promise<{ dir: string; depth: number } | null> {
-	for (const ancestor of getAncestorDirs(cwd, repoRoot)) {
+	for (const ancestor of getAncestorDirs(cwd, repoRoot ?? home, home)) {
 		for (const projectConfigDir of getProjectConfigDirs()) {
 			const configDir = await ifNonEmptyDir(ancestor.dir, projectConfigDir);
 			if (configDir) return { dir: configDir, depth: ancestor.depth };
@@ -280,20 +265,21 @@ registerProvider<MCPServer>(mcpCapability.id, {
 async function loadSystemPrompt(ctx: LoadContext): Promise<LoadResult<SystemPrompt>> {
 	const items: SystemPrompt[] = [];
 
-	for (const userAgentDir of getUserAgentDirs()) {
-		const userPath = path.join(ctx.home, userAgentDir, "SYSTEM.md");
-		const userContent = await readFile(userPath);
-		if (userContent) {
-			items.push({
-				path: userPath,
-				content: userContent,
-				level: "user",
-				_source: createSourceMeta(PROVIDER_ID, userPath, "user"),
-			});
-		}
+	// User scope is the agent directory — the directory `gjc config path` prints
+	// and the only user-scope seam. A profile is a separate scope; the default
+	// profile's home-relative SYSTEM.md is not read under one.
+	const userPath = path.join(resolveUserAgentDir(ctx), "SYSTEM.md");
+	const userContent = await readContainedFile(resolveUserAgentDir(ctx), userPath);
+	if (userContent) {
+		items.push({
+			path: userPath,
+			content: userContent,
+			level: "user",
+			_source: createSourceMeta(PROVIDER_ID, userPath, "user"),
+		});
 	}
 
-	const nearestProjectConfigDir = await findNearestProjectConfigDir(ctx.cwd, ctx.repoRoot);
+	const nearestProjectConfigDir = await findNearestProjectConfigDir(ctx.cwd, ctx.repoRoot, ctx.home);
 	if (nearestProjectConfigDir) {
 		const projectPath = path.join(nearestProjectConfigDir.dir, "SYSTEM.md");
 		const projectContent = await readFile(projectPath);
@@ -321,9 +307,7 @@ registerProvider<SystemPrompt>(systemPromptCapability.id, {
 // Skills
 async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 	// Walk up from cwd finding .gjc/skills/ in ancestors (closest first)
-	const ancestors = getAncestorDirs(ctx.cwd, ctx.repoRoot ?? ctx.home).filter(
-		({ dir }) => path.resolve(dir) !== path.resolve(ctx.home),
-	);
+	const ancestors = getAncestorDirs(ctx.cwd, ctx.repoRoot ?? ctx.home, ctx.home);
 	const projectScans = ancestors.flatMap(({ dir }) =>
 		getProjectConfigDirs().map(projectConfigDir =>
 			scanSkillsFromDir(ctx, {
@@ -335,17 +319,13 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 		),
 	);
 
-	// User-level scan from the active agent-directory profile.
-	const userSkillDirs = [
-		...new Set([
-			path.join(resolveUserAgentDir(ctx), "skills"),
-			path.join(ctx.home, PATHS.userBase, "skills"),
-			path.join(ctx.home, ".gjc", "skills"),
-		]),
-	];
-	const userScans = userSkillDirs.map(dir =>
+	// User-level scan from the selected agent-directory profile plus documented
+	// default-profile legacy scan roots.
+	const userAgentDir = resolveUserAgentDir(ctx);
+	const userScans = getUserSkillScanDirs(ctx.home, userAgentDir, ctx.profileAuthority).map(dir =>
 		scanSkillsFromDir(ctx, {
 			dir,
+			authorityRoot: path.resolve(dir) === path.resolve(userAgentDir, "skills") ? userAgentDir : undefined,
 			providerId: PROVIDER_ID,
 			level: "user",
 			requireDescription: true,
@@ -404,28 +384,36 @@ registerProvider<SlashCommand>(slashCommandCapability.id, {
 async function loadRules(ctx: LoadContext): Promise<LoadResult<Rule>> {
 	const items: Rule[] = [];
 	const warnings: string[] = [];
-
-	for (const { dir, level } of await getConfigDirs(ctx)) {
-		const rulesDir = path.join(dir, "rules");
-		const result = await loadFilesFromDir<Rule>(ctx, rulesDir, PROVIDER_ID, level, {
-			extensions: ["md", "mdc"],
-			transform: (name, content, path, source) =>
-				buildRuleFromMarkdown(name, content, path, source, { stripNamePattern: /\.(md|mdc)$/ }),
-		});
-		items.push(...result.items);
-		if (result.warnings) warnings.push(...result.warnings);
-	}
+	const configDirs = await getConfigDirs(ctx);
+	const projectConfigDirs = configDirs.filter(({ level }) => level === "project");
+	const userConfigDirs = configDirs.filter(({ level }) => level === "user");
+
+	const loadRulesFromDirs = async (dirs: Array<{ dir: string; level: "user" | "project" }>) => {
+		for (const { dir, level } of dirs) {
+			const rulesDir = path.join(dir, "rules");
+			const result = await loadFilesFromDir<Rule>(ctx, rulesDir, PROVIDER_ID, level, {
+				extensions: ["md", "mdc"],
+				transform: (name, content, path, source) =>
+					buildRuleFromMarkdown(name, content, path, source, { stripNamePattern: /\.(md|mdc)$/ }),
+			});
+			items.push(...result.items);
+			if (result.warnings) warnings.push(...result.warnings);
+		}
+	};
 
 	// Top-level RULES.md is a sticky always-apply rule. The context-file
 	// discovery contract treats it as the file "re-injected near the current
 	// turn so they keep hold across long conversations".
-	// User scope:    ~/.gjc/agent/RULES.md
+	// User scope:    <agentDir>/RULES.md (a profile is a separate user scope;
+	//                the default profile's home-relative copy is not read)
 	// Project scope: nearest .gjc/RULES.md walking up from cwd to repoRoot
+	await loadRulesFromDirs([...projectConfigDirs, ...userConfigDirs]);
+
 	const userRulesFile = path.join(resolveUserAgentDir(ctx), "RULES.md");
 	const userRule = await loadStickyRulesFile(userRulesFile, "user");
 	if (userRule) items.push(userRule);
 
-	const nearestProjectConfigDir = await findNearestProjectConfigDir(ctx.cwd, ctx.repoRoot);
+	const nearestProjectConfigDir = await findNearestProjectConfigDir(ctx.cwd, ctx.repoRoot, ctx.home);
 	if (nearestProjectConfigDir) {
 		const projectRulesFile = path.join(nearestProjectConfigDir.dir, "RULES.md");
 		const projectRule = await loadStickyRulesFile(projectRulesFile, "project");
@@ -440,7 +428,7 @@ async function loadRules(ctx: LoadContext): Promise<LoadResult<Rule>> {
  * Returns null when the file is absent or empty so callers can short-circuit.
  */
 async function loadStickyRulesFile(filePath: string, level: "user" | "project"): Promise<Rule | null> {
-	const content = await readFile(filePath);
+	const content = await readContainedFile(path.dirname(filePath), filePath);
 	if (!content) return null;
 	const source = createSourceMeta(PROVIDER_ID, filePath, level);
 	const rule = buildRuleFromMarkdown("RULES.md", content, filePath, source, { ruleName: "RULES" });
@@ -728,7 +716,7 @@ async function loadHooks(ctx: LoadContext): Promise<LoadResult<Hook>> {
 		const { typeDir, hookType, level } = typeDirRequests[i];
 		const typeEntries = typeEntriesResults[i];
 
-		for (const entry of typeEntries) {
+		for (const entry of [...typeEntries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
 			if (entry.name.startsWith(".")) continue;
 			if (!entry.isFile()) continue;
 
@@ -938,8 +926,8 @@ async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFil
 	const items: ContextFile[] = [];
 	const warnings: string[] = [];
 
-	const userPath = path.join(ctx.home, PATHS.userAgent, "AGENTS.md");
-	const userContent = await readFile(userPath);
+	const userPath = path.join(resolveUserAgentDir(ctx), "AGENTS.md");
+	const userContent = await readContainedFile(resolveUserAgentDir(ctx), userPath);
 	if (userContent) {
 		items.push({
 			path: userPath,
@@ -949,7 +937,7 @@ async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFil
 		});
 	}
 
-	const nearestProjectConfigDir = await findNearestProjectConfigDir(ctx.cwd, ctx.repoRoot);
+	const nearestProjectConfigDir = await findNearestProjectConfigDir(ctx.cwd, ctx.repoRoot, ctx.home);
 	if (nearestProjectConfigDir) {
 		const projectPath = path.join(nearestProjectConfigDir.dir, "AGENTS.md");
 		const projectContent = await readFile(projectPath);

package/src/discovery/helpers.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import type { FileHandle } from "node:fs/promises";
 import * as path from "node:path";
 import type { ThinkingLevel } from "@gajae-code/agent-core";
 import type { FileType as FileTypeEnum, glob as globFn } from "@gajae-code/natives";
@@ -9,6 +10,7 @@ import {
 	getProjectDir,
 	getTrustedHomeDir,
 	logger,
+	normalizePathForComparison,
 	parseFrontmatter,
 	tryParseJson,
 } from "@gajae-code/utils";
@@ -99,7 +101,32 @@ export const SOURCE_PATHS = {
 	},
 } as const;
 
+/** Ancestors from `cwd` through `stopAt`, excluding one normalized authority boundary. */
+export function getAncestorDirs(
+	cwd: string,
+	stopAt?: string | null,
+	excludeDir?: string,
+): Array<{ dir: string; depth: number }> {
+	const ancestors: Array<{ dir: string; depth: number }> = [];
+	let current = path.resolve(cwd);
+	let depth = 0;
+	let normalizedCurrent = normalizePathForComparison(current);
+	const normalizedStop = stopAt ? normalizePathForComparison(path.resolve(stopAt)) : undefined;
+	const normalizedExclude = excludeDir ? normalizePathForComparison(path.resolve(excludeDir)) : undefined;
+	while (true) {
+		if (normalizedCurrent !== normalizedExclude) ancestors.push({ dir: current, depth });
+		if (normalizedStop && normalizedCurrent === normalizedStop) break;
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+		normalizedCurrent = normalizePathForComparison(current);
+		depth++;
+	}
+	return ancestors;
+}
+
 export type SourceId = keyof typeof SOURCE_PATHS;
+export type ProfileAuthority = "default" | "custom";
 
 /**
  * Get user-level path for a source.
@@ -110,6 +137,49 @@ export function getUserPath(ctx: LoadContext, source: SourceId, subpath: string)
 	return path.join(ctx.home, paths.userAgent, subpath);
 }
 
+/**
+ * Deterministic user-scope skill scan directories, highest precedence first.
+ *
+ * The canonical root is the agent directory (`getAgentDir()`, moved by
+ * `--agent-dir` / `GJC_CODING_AGENT_DIR` / `setAgentDir()`) — the target of
+ * every user-scope skill writer (`gjc migrate`, `gjc skill`). An agent-directory
+ * profile is a *separate* user scope, the same contract as MCP user config
+ * (#4768): its legacy home-relative roots are not scanned, so a profile cannot
+ * pick up the default profile's skills (and vice versa). The resolver-owned
+ * `profileAuthority` classification is authoritative when supplied, so a
+ * custom profile remains isolated even if a later HOME/config-root refresh
+ * makes its path look like the current default. In the default profile the
+ * agent directory is `<home>/<configDir>/agent` and the configured legacy roots
+ * below it are still honored, exactly as before.
+ */
+export function resolveUserAgentDir(home: string, userAgentDir?: string): string {
+	return path.resolve(userAgentDir ?? path.join(home, SOURCE_PATHS.native.userAgent));
+}
+
+export function getUserSkillScanDirs(
+	home: string,
+	userAgentDir?: string,
+	profileAuthority?: ProfileAuthority,
+): string[] {
+	const resolvedAgentDir = resolveUserAgentDir(home, userAgentDir);
+	const defaultAgentDir = path.join(home, SOURCE_PATHS.native.userAgent);
+	const authority =
+		profileAuthority ??
+		(normalizePathForComparison(resolvedAgentDir) === normalizePathForComparison(defaultAgentDir)
+			? "default"
+			: "custom");
+	if (authority === "custom") {
+		return [path.join(resolvedAgentDir, "skills")];
+	}
+	return [
+		...new Set([
+			path.join(resolvedAgentDir, "skills"),
+			path.join(home, SOURCE_PATHS.native.userBase, "skills"),
+			path.join(home, ".gjc", "skills"),
+		]),
+	];
+}
+
 /**
  * Get project-level path for a source (cwd only).
  */
@@ -345,6 +415,8 @@ async function globIf(
 
 export interface ScanSkillsFromDirOptions {
 	dir: string;
+	/** Selected authority root whose own identity must not be a symlink. */
+	authorityRoot?: string;
 	providerId: string;
 	level: "user" | "project";
 	requireDescription?: boolean;
@@ -365,30 +437,40 @@ export const SKILL_FRONTMATTER_SCAN_BYTES = 4 * 1024;
 /** Maximum total bytes read while seeking the frontmatter closing delimiter. */
 export const SKILL_FRONTMATTER_SCAN_TOTAL_BYTES = 64 * 1024;
 
-async function readSkillFrontmatter(skillPath: string): Promise<SkillFrontmatter | null> {
-	const file = Bun.file(skillPath);
-	const size = (await fs.promises.stat(skillPath)).size;
-	const scanLimit = Math.min(size, SKILL_FRONTMATTER_SCAN_TOTAL_BYTES);
-	let offset = 0;
-	let prefix = "";
-	const decoder = new TextDecoder();
-	while (offset < scanLimit) {
-		const end = Math.min(offset + SKILL_FRONTMATTER_SCAN_BYTES, scanLimit);
-		const bytes = new Uint8Array(await file.slice(offset, end).arrayBuffer());
-		const chunk = decoder.decode(bytes, { stream: end < scanLimit });
-		if (!chunk) break;
-		prefix += chunk;
-		offset = end;
-
-		const opening = prefix.match(/^---[ \t]*(?:\r?\n|$)/);
-		if (!opening) return null;
-		const afterOpening = prefix.slice(opening[0].length);
-		const closing = afterOpening.match(/\r?\n---[ \t]*(?:\r?\n|$)/);
-		if (!closing || closing.index === undefined) continue;
-		const bounded = prefix.slice(0, opening[0].length + closing.index + closing[0].length);
-		return parseFrontmatter(bounded, { source: skillPath }).frontmatter as SkillFrontmatter;
+export const SkillDiscoveryTestHooks: {
+	afterCandidateValidated?: (candidatePath: string) => void | Promise<void>;
+	afterAuthorityRootValidated?: (root: string) => void | Promise<void>;
+	afterAuthorityRootMissing?: (root: string) => void | Promise<void>;
+	afterContainedRootValidated?: (root: string) => void | Promise<void>;
+} = {};
+
+interface DirectoryIdentity {
+	dev: bigint;
+	ino: bigint;
+	realPath: string;
+}
+
+async function captureDirectoryIdentity(root: string): Promise<DirectoryIdentity | null> {
+	const observed = await fs.promises.lstat(root, { bigint: true });
+	if (observed.isSymbolicLink() || !observed.isDirectory()) return null;
+	const realPath = await fs.promises.realpath(root);
+	const resolved = await fs.promises.stat(realPath, { bigint: true });
+	if (!resolved.isDirectory() || observed.dev !== resolved.dev || observed.ino !== resolved.ino) return null;
+	return { dev: observed.dev, ino: observed.ino, realPath };
+}
+
+async function directoryIdentityIsCurrent(root: string, expected: DirectoryIdentity): Promise<boolean> {
+	try {
+		const current = await captureDirectoryIdentity(root);
+		return (
+			current !== null &&
+			current.dev === expected.dev &&
+			current.ino === expected.ino &&
+			normalizePathForComparison(current.realPath) === normalizePathForComparison(expected.realPath)
+		);
+	} catch {
+		return false;
 	}
-	return null;
 }
 
 export async function scanSkillsFromDir(
@@ -400,19 +482,150 @@ export async function scanSkillsFromDir(
 	const { dir, level, providerId, requireDescription = false } = options;
 
 	let entries: fs.Dirent[];
+	let realRoot: string;
+	let authorityIdentity: DirectoryIdentity | null = null;
+	let scanRootIdentity: DirectoryIdentity;
 	try {
+		if (options.authorityRoot) {
+			try {
+				authorityIdentity = await captureDirectoryIdentity(options.authorityRoot);
+				if (!authorityIdentity) {
+					warnings.push(`Refusing unsafe skill authority root: ${options.authorityRoot}`);
+					return { items, warnings };
+				}
+				await SkillDiscoveryTestHooks.afterAuthorityRootValidated?.(options.authorityRoot);
+				if (!(await directoryIdentityIsCurrent(options.authorityRoot, authorityIdentity))) {
+					warnings.push(`Refusing changed skill authority root: ${options.authorityRoot}`);
+					return { items, warnings };
+				}
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+				await SkillDiscoveryTestHooks.afterAuthorityRootMissing?.(options.authorityRoot);
+				return { items, warnings };
+			}
+		}
+		const capturedScanRoot = await captureDirectoryIdentity(dir);
+		if (!capturedScanRoot) {
+			warnings.push(`Refusing unsafe skills directory: ${dir}`);
+			return { items, warnings };
+		}
+		scanRootIdentity = capturedScanRoot;
+		realRoot = scanRootIdentity.realPath;
 		entries = await fs.promises.readdir(dir, { withFileTypes: true });
+		if (!(await directoryIdentityIsCurrent(dir, scanRootIdentity))) {
+			warnings.push(`Refusing changed skills directory: ${dir}`);
+			return { items, warnings };
+		}
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
 			warnings.push(`Failed to read skills directory: ${dir} (${String(error)})`);
 		}
 		return { items, warnings };
 	}
-	const loadSkill = async (skillPath: string) => {
+	const isWithinRoot = (candidate: string): boolean => {
+		const relative = path.relative(realRoot, candidate);
+		return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+	};
+	const openSkillFileSafely = async (skillPath: string): Promise<FileHandle> => {
+		if (
+			!(await directoryIdentityIsCurrent(dir, scanRootIdentity)) ||
+			(options.authorityRoot &&
+				authorityIdentity &&
+				!(await directoryIdentityIsCurrent(options.authorityRoot, authorityIdentity)))
+		) {
+			throw new Error(`Unsafe skill authority root for: ${skillPath}`);
+		}
+		const flags =
+			fs.constants.O_RDONLY |
+			(process.platform === "win32" ? 0 : (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+		const handle = await fs.promises.open(skillPath, flags);
 		try {
-			const frontmatter = await readSkillFrontmatter(skillPath);
+			const [opened, observed, currentPath, currentScanRoot, currentAuthorityRoot] = await Promise.all([
+				handle.stat({ bigint: true }),
+				fs.promises.lstat(skillPath, { bigint: true }),
+				fs.promises.realpath(skillPath),
+				directoryIdentityIsCurrent(dir, scanRootIdentity),
+				options.authorityRoot && authorityIdentity
+					? directoryIdentityIsCurrent(options.authorityRoot, authorityIdentity)
+					: true,
+			]);
+			if (
+				!opened.isFile() ||
+				opened.nlink !== 1n ||
+				observed.isSymbolicLink() ||
+				!observed.isFile() ||
+				opened.dev !== observed.dev ||
+				opened.ino !== observed.ino ||
+				!isWithinRoot(currentPath) ||
+				!currentScanRoot ||
+				!currentAuthorityRoot
+			) {
+				throw new Error(`Unsafe skill file: ${skillPath}`);
+			}
+			return handle;
+		} catch (error) {
+			await handle.close();
+			throw error;
+		}
+	};
+	const readSkillContentSafely = async (skillPath: string): Promise<string> => {
+		const handle = await openSkillFileSafely(skillPath);
+		try {
+			return await handle.readFile({ encoding: "utf8" });
+		} finally {
+			await handle.close();
+		}
+	};
+	const readSkillFrontmatterSafely = async (
+		skillPath: string,
+	): Promise<{ frontmatter: SkillFrontmatter | null; size: number }> => {
+		const handle = await openSkillFileSafely(skillPath);
+		try {
+			const size = Number((await handle.stat({ bigint: true })).size);
+			const scanLimit = Math.min(size, SKILL_FRONTMATTER_SCAN_TOTAL_BYTES);
+			let offset = 0;
+			let prefix = "";
+			const decoder = new TextDecoder();
+			while (offset < scanLimit) {
+				const length = Math.min(SKILL_FRONTMATTER_SCAN_BYTES, scanLimit - offset);
+				const bytes = new Uint8Array(length);
+				const { bytesRead } = await handle.read(bytes, 0, length, offset);
+				if (bytesRead === 0) break;
+				offset += bytesRead;
+				prefix += decoder.decode(bytes.subarray(0, bytesRead), { stream: offset < scanLimit });
+
+				const opening = prefix.match(/^---[ \t]*(?:\r?\n|$)/);
+				if (!opening) return { frontmatter: null, size };
+				const afterOpening = prefix.slice(opening[0].length);
+				const closing = afterOpening.match(/\r?\n---[ \t]*(?:\r?\n|$)/);
+				if (!closing || closing.index === undefined) continue;
+				const bounded = prefix.slice(0, opening[0].length + closing.index + closing[0].length);
+				return {
+					frontmatter: parseFrontmatter(bounded, { source: skillPath }).frontmatter as SkillFrontmatter,
+					size,
+				};
+			}
+			return { frontmatter: null, size };
+		} finally {
+			await handle.close();
+		}
+	};
+	const loadSkill = async (candidatePath: string) => {
+		try {
+			const skillPath = await fs.promises.realpath(candidatePath);
+			if (!isWithinRoot(skillPath)) {
+				warnings.push(`Refusing skill path outside scan root: ${candidatePath}`);
+				return;
+			}
+			const stat = await fs.promises.stat(skillPath);
+			if (!stat.isFile() || stat.nlink !== 1) {
+				warnings.push(`Skill path is not a regular file: ${candidatePath}`);
+				return;
+			}
+			await SkillDiscoveryTestHooks.afterCandidateValidated?.(candidatePath);
+			const { frontmatter, size } = await readSkillFrontmatterSafely(skillPath);
 			if (!frontmatter) {
-				if (fs.statSync(skillPath).size > SKILL_FRONTMATTER_SCAN_TOTAL_BYTES) {
+				if (size > SKILL_FRONTMATTER_SCAN_TOTAL_BYTES) {
 					warnings.push(
 						`Skill frontmatter exceeded ${SKILL_FRONTMATTER_SCAN_TOTAL_BYTES} byte scan cap: ${skillPath}`,
 					);
@@ -435,15 +648,16 @@ export async function scanSkillsFromDir(
 				name,
 				path: skillPath,
 				loadContent: async () => {
-					const content = await Bun.file(skillPath).text();
+					const content = await readSkillContentSafely(skillPath);
 					return parseFrontmatter(content, { source: skillPath }).body;
 				},
 				frontmatter: frontmatter as SkillFrontmatter,
 				level,
 				_source: createSourceMeta(providerId, skillPath, level),
 			});
-		} catch {
-			warnings.push(`Failed to read skill file: ${skillPath}`);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+			warnings.push(`Failed to read skill file: ${candidatePath}`);
 		}
 	};
 
@@ -452,9 +666,7 @@ export async function scanSkillsFromDir(
 		if (entry.name.startsWith(".")) continue;
 		if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
 		const skillPath = path.join(dir, entry.name, "SKILL.md");
-		if (fs.existsSync(skillPath)) {
-			work.push(loadSkill(skillPath));
-		}
+		work.push(loadSkill(skillPath));
 	}
 	await Promise.all(work);
 
@@ -464,6 +676,59 @@ export async function scanSkillsFromDir(
 	return { items, warnings };
 }
 
+/** Read a regular single-link file that remains contained by its configured root. */
+export async function readContainedFile(root: string, filePath: string): Promise<string | null> {
+	let rootIdentity: DirectoryIdentity;
+	try {
+		const capturedRoot = await captureDirectoryIdentity(root);
+		if (!capturedRoot) return null;
+		rootIdentity = capturedRoot;
+		await SkillDiscoveryTestHooks.afterContainedRootValidated?.(root);
+		if (!(await directoryIdentityIsCurrent(root, rootIdentity))) return null;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw error;
+	}
+	const relative = path.relative(root, filePath);
+	if (relative.startsWith("..") || path.isAbsolute(relative)) return null;
+	const flags =
+		fs.constants.O_RDONLY |
+		(process.platform === "win32" ? 0 : (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+	let handle: FileHandle;
+	try {
+		handle = await fs.promises.open(filePath, flags);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		return null;
+	}
+	try {
+		const [opened, observed, currentPath, currentRoot] = await Promise.all([
+			handle.stat({ bigint: true }),
+			fs.promises.lstat(filePath, { bigint: true }),
+			fs.promises.realpath(filePath),
+			directoryIdentityIsCurrent(root, rootIdentity),
+		]);
+		const currentRelative = path.relative(rootIdentity.realPath, currentPath);
+		if (
+			!opened.isFile() ||
+			opened.nlink !== 1n ||
+			observed.isSymbolicLink() ||
+			!observed.isFile() ||
+			opened.dev !== observed.dev ||
+			opened.ino !== observed.ino ||
+			!currentRoot ||
+			currentRelative.startsWith("..") ||
+			path.isAbsolute(currentRelative)
+		) {
+			return null;
+		}
+		const content = await handle.readFile({ encoding: "utf8" });
+		return (await directoryIdentityIsCurrent(root, rootIdentity)) ? content : null;
+	} finally {
+		await handle.close();
+	}
+}
+
 /**
  * Expand environment variables in a string.
  * Supports ${VAR} and ${VAR:-default} syntax.