@gajae-code/coding-agent 0.18.11 → 0.18.12

package/src/internal-urls/local-protocol.ts

@@ -179,6 +179,86 @@ async function assertDirectoryNotSymlink(directoryPath: string): Promise<void> {
 	}
 }
 
+/** Group-write and world-write bits. Either one lets another user rename the session directory. */
+const GROUP_OR_WORLD_WRITABLE = 0o022;
+
+interface DirectoryIdentityStat {
+	isDirectory(): boolean;
+	isSymbolicLink(): boolean;
+	dev: number;
+	ino: number;
+	uid: number;
+	mode: number;
+}
+
+interface ManagedRootIdentity {
+	readonly dev: number;
+	readonly ino: number;
+	readonly uid: number;
+}
+
+function isUnsafeDirectory(stat: DirectoryIdentityStat): boolean {
+	return !stat.isDirectory() || stat.isSymbolicLink();
+}
+
+function managedRootIdentity(stat: DirectoryIdentityStat): ManagedRootIdentity {
+	return { dev: stat.dev, ino: stat.ino, uid: stat.uid };
+}
+
+function sameManagedRoot(stat: DirectoryIdentityStat, recorded: ManagedRootIdentity): boolean {
+	if (isUnsafeDirectory(stat) || stat.dev !== recorded.dev || stat.ino !== recorded.ino) return false;
+	// A later chmod to 0755 keeps the same directory. Only a writable bit, a new
+	// inode, or a different owner means the root was replaced or opened up.
+	if (process.platform === "win32") return true;
+	return stat.uid === recorded.uid && (stat.mode & GROUP_OR_WORLD_WRITABLE) === 0;
+}
+
+/**
+ * An existing managed session directory is adopted only when this user owns it
+ * and the group and world cannot write it. Windows has no POSIX owner bits.
+ */
+function assertAdoptedManagedRoot(stat: DirectoryIdentityStat): void {
+	if (isUnsafeDirectory(stat)) throw new Error("Unsafe local:// root");
+	if (process.platform === "win32") return;
+	const uid = process.getuid?.();
+	if (uid === undefined || stat.uid !== uid || (stat.mode & GROUP_OR_WORLD_WRITABLE) !== 0) {
+		throw new Error("Unsafe local:// root");
+	}
+}
+
+function assertManagedParentSync(localRoot: string): void {
+	let parentStat: fsSync.Stats;
+	try {
+		parentStat = fsSync.lstatSync(path.dirname(localRoot));
+	} catch {
+		throw new Error("Unsafe local:// root");
+	}
+	assertAdoptedManagedRoot(parentStat);
+}
+
+/**
+ * Rebind a pinned root only when this call created it because the path was
+ * absent. An already-present directory must still be the pinned one.
+ */
+function acceptManagedRootForInit(
+	localRoot: string,
+	rootStat: DirectoryIdentityStat,
+	recorded: ManagedRootIdentity | undefined,
+	adoptedExisting: boolean,
+): void {
+	if (recorded && adoptedExisting) {
+		if (sameManagedRoot(rootStat, recorded)) return;
+		const pending = pendingCreatedRoots.get(localRoot);
+		if (pending && sameManagedRoot(rootStat, pending)) return;
+		throw new Error("Unsafe local:// root");
+	}
+	if (recorded || adoptedExisting) {
+		assertAdoptedManagedRoot(rootStat);
+		return;
+	}
+	if (isUnsafeDirectory(rootStat)) throw new Error("Unsafe local:// root");
+}
+
 const LEGACY_MIGRATION_MARKER = ".gjc-local-legacy-migrated-v1";
 const MAX_LEGACY_LOCAL_BYTES = 64 * 1024 * 1024;
 
@@ -508,9 +588,33 @@ async function migrateLegacyLocal(
 	}
 }
 
-const initializedLocalRoots = new Set<string>();
+const initializedLocalRoots = new Map<string, ManagedRootIdentity>();
+/** A directory this process created and has not finished migrating. */
+const pendingCreatedRoots = new Map<string, ManagedRootIdentity>();
 const initializingLocalRoots = new Map<string, Promise<string>>();
 
+function assertRememberedManagedRoot(localRoot: string, recorded: ManagedRootIdentity): void {
+	let stat: fsSync.Stats;
+	try {
+		stat = fsSync.lstatSync(localRoot);
+	} catch {
+		throw new Error("Unsafe local:// root");
+	}
+	if (!sameManagedRoot(stat, recorded)) throw new Error("Unsafe local:// root");
+}
+
+function rememberManagedRoot(localRoot: string, expected: ManagedRootIdentity): void {
+	let stat: fsSync.Stats;
+	try {
+		stat = fsSync.lstatSync(localRoot);
+	} catch {
+		throw new Error("Unsafe local:// root");
+	}
+	if (!sameManagedRoot(stat, expected)) throw new Error("Unsafe local:// root");
+	initializedLocalRoots.set(localRoot, managedRootIdentity(stat));
+	pendingCreatedRoots.delete(localRoot);
+}
+
 /**
  * Completes the mandatory legacy migration gate for a local root.
  * Call and await this before using the synchronous path resolver for reads or writes.
@@ -559,16 +663,21 @@ async function initializeManagedLocalRoot(options: LocalProtocolOptions, localRo
 
 	await fs.mkdir(scratchParent, { recursive: true, mode: 0o700 });
 	await assertDirectoryNotSymlink(scratchParent);
+	assertAdoptedManagedRoot(await fs.lstat(scratchParent));
+	let adoptedExisting = false;
 	try {
 		await fs.mkdir(localRoot, { mode: 0o700 });
 	} catch (error) {
 		if (error instanceof Error && "code" in error && error.code === "EEXIST") {
-			await assertDirectoryNotSymlink(localRoot);
+			adoptedExisting = true;
 		} else {
 			throw error;
 		}
 	}
-	await assertDirectoryNotSymlink(localRoot);
+	const rootStat = await fs.lstat(localRoot);
+	const recorded = initializedLocalRoots.get(localRoot);
+	acceptManagedRootForInit(localRoot, rootStat, recorded, adoptedExisting);
+	if (!adoptedExisting) pendingCreatedRoots.set(localRoot, managedRootIdentity(rootStat));
 	await migrateLegacyLocal(options, localRoot, scratchParent);
 
 	const resolvedScratchParent = await fs.realpath(scratchParent);
@@ -577,7 +686,10 @@ async function initializeManagedLocalRoot(options: LocalProtocolOptions, localRo
 	if (resolvedLocalRoot === resolvedScratchParent) {
 		throw new Error("Unsafe local:// root");
 	}
-	initializedLocalRoots.add(resolvedLocalRoot);
+	// Key the lexical path the sync resolver checks. realpath(/var -> /private/var)
+	// is a different string for the same directory, so caching only the real path
+	// let a later rename-swap skip this identity check.
+	rememberManagedRoot(localRoot, managedRootIdentity(rootStat));
 	return resolvedLocalRoot;
 }
 
@@ -587,18 +699,39 @@ function initializeLocalRootSyncWhenLegacyAbsent(options: LocalProtocolOptions,
 		initializeExplicitLocalRootSync(explicitRoot);
 		return;
 	}
-	if (initializedLocalRoots.has(localRoot)) return;
+	const recorded = initializedLocalRoots.get(localRoot);
+	if (recorded) {
+		assertManagedParentSync(localRoot);
+		let present: fsSync.Stats | undefined;
+		try {
+			present = fsSync.lstatSync(localRoot);
+		} catch (error) {
+			if (!isEnoent(error)) throw new Error("Unsafe local:// root");
+		}
+		if (present) {
+			if (sameManagedRoot(present, recorded)) {
+				assertRememberedManagedRoot(localRoot, recorded);
+				return;
+			}
+			const pending = pendingCreatedRoots.get(localRoot);
+			if (!(pending && sameManagedRoot(present, pending))) throw new Error("Unsafe local:// root");
+		}
+	}
 	const scratchParent = path.dirname(localRoot);
 	fsSync.mkdirSync(scratchParent, { recursive: true, mode: 0o700 });
 	const parentStat = fsSync.lstatSync(scratchParent);
 	if (!parentStat.isDirectory() || parentStat.isSymbolicLink()) throw new Error("Unsafe local:// root");
+	assertAdoptedManagedRoot(parentStat);
+	let adoptedExisting = false;
 	try {
 		fsSync.mkdirSync(localRoot, { mode: 0o700 });
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		adoptedExisting = true;
 	}
 	const rootStat = fsSync.lstatSync(localRoot);
-	if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error("Unsafe local:// root");
+	acceptManagedRootForInit(localRoot, rootStat, recorded, adoptedExisting);
+	if (!adoptedExisting) pendingCreatedRoots.set(localRoot, managedRootIdentity(rootStat));
 	const marker = path.join(localRoot, LEGACY_MIGRATION_MARKER);
 	try {
 		// Accept exactly the marker states the async gate treats as settled. A
@@ -608,7 +741,7 @@ function initializeLocalRootSyncWhenLegacyAbsent(options: LocalProtocolOptions,
 		// async gate had already completed.
 		if (!isSettledMigrationMarkerValue(fsSync.readFileSync(marker, "utf8")))
 			throw new Error("Unsafe local:// migration marker");
-		initializedLocalRoots.add(localRoot);
+		rememberManagedRoot(localRoot, managedRootIdentity(rootStat));
 		return;
 	} catch (error) {
 		if (!isEnoent(error)) throw error;
@@ -629,7 +762,7 @@ function initializeLocalRootSyncWhenLegacyAbsent(options: LocalProtocolOptions,
 		if (!isSettledMigrationMarkerValue(fsSync.readFileSync(marker, "utf8")))
 			throw new Error("Unsafe local:// migration marker");
 	}
-	initializedLocalRoots.add(localRoot);
+	rememberManagedRoot(localRoot, managedRootIdentity(rootStat));
 }
 
 export function resolveLocalRoot(options: LocalProtocolOptions): string {
@@ -696,6 +829,7 @@ export class LocalProtocolHandler implements ProtocolHandler {
 		LocalProtocolHandler.#override = undefined;
 		LocalProtocolHandler.#ownedOverrides = [];
 		initializedLocalRoots.clear();
+		pendingCreatedRoots.clear();
 		initializingLocalRoots.clear();
 	}
 

package/src/lsp/index.ts

@@ -77,6 +77,7 @@ import {
 	symbolKindToIcon,
 	uriToFile,
 } from "./utils";
+import { assertInsideWorkspace } from "./workspace-path";
 
 export type { LspServerStatus } from "./client";
 export type { LspToolDetails } from "./types";
@@ -347,6 +348,17 @@ interface FileRenamePair {
  * For files this is a single pair. For directories this walks every regular file underneath
  * and produces a parallel pair anchored at the new directory root.
  */
+/**
+ * POSIX `/` contains every absolute path, and the shared helper's prefix for
+ * it is `//`, so skip containment there. A Windows drive root is only that
+ * volume, so it is checked. Any other platform root keeps the previous skip.
+ */
+function workspaceRootSkipsContainment(root: string): boolean {
+	if (root === "/") return true;
+	if (/^[A-Za-z]:[\\/]$/.test(root)) return false;
+	return root === path.parse(root).root;
+}
+
 async function enumerateRenamePairs(
 	source: string,
 	dest: string,
@@ -1525,6 +1537,23 @@ export class LspTool implements AgentTool<typeof lspSchema, LspToolDetails, Them
 				}
 			}
 
+			// Reject every path this rename will write before the first write. Check the
+			// caller signal after each await, including the last one.
+			const cwd = this.session.cwd;
+			throwIfAborted(signal);
+			const workspaceRoot = await fs.promises.realpath(cwd);
+			throwIfAborted(signal);
+			if (!workspaceRootSkipsContainment(workspaceRoot)) {
+				await assertInsideWorkspace(cwd, source);
+				throwIfAborted(signal);
+				await assertInsideWorkspace(cwd, dest);
+				throwIfAborted(signal);
+				for (const uri of acceptedByUri.keys()) {
+					await assertInsideWorkspace(cwd, uriToFile(uri));
+					throwIfAborted(signal);
+				}
+			}
+
 			for (const [uri, bucket] of acceptedByUri) {
 				const filePath = uriToFile(uri);
 				await applyTextEdits(filePath, bucket.edits);

package/src/lsp/workspace-path.ts

@@ -6,7 +6,30 @@ function isEnoent(error: unknown): boolean {
 	return (error as NodeJS.ErrnoException).code === "ENOENT";
 }
 
+/** Drive-letter root such as `C:\`. A UNC share root is not a drive root. */
+function windowsDriveLetter(root: string): string | null {
+	const match = /^([A-Za-z]):[\\/]$/.exec(root);
+	return match ? match[1].toLowerCase() : null;
+}
+
+/**
+ * A Windows drive root already ends in a separator. Prefixing another one
+ * (`C:\` + `\`) matches nothing on that volume, so compare the drive letter.
+ * Same-volume paths stay inside, including `\\?\C:\`. Other drives and UNC
+ * shares do not.
+ */
+function sameWindowsDrive(driveRoot: string, candidate: string): boolean {
+	const letter = windowsDriveLetter(driveRoot);
+	if (!letter) return false;
+	const normalized = candidate.replace(/\//g, "\\");
+	const extended = /^\\\\\?\\([A-Za-z]):\\/.exec(normalized);
+	if (extended) return extended[1].toLowerCase() === letter;
+	if (normalized.startsWith("\\\\")) return false;
+	return path.win32.parse(normalized).root.toLowerCase() === `${letter}:\\`;
+}
+
 function escapes(root: string, candidate: string): boolean {
+	if (windowsDriveLetter(root)) return !sameWindowsDrive(root, candidate);
 	return candidate !== root && !candidate.startsWith(`${root}${path.sep}`);
 }
 

package/src/migrate/action-planner.ts

@@ -314,5 +314,62 @@ export async function planMigration(input: PlanInput): Promise<PlanOutput> {
 		}
 	}
 
+	// 4. Instructions — all selected sources target the same scoped AGENTS.md.
+	const plannedInstructions = new Set<string>();
+	for (const result of input.results) {
+		for (const candidate of result.instructionCandidates) {
+			const destination = input.destinations.instructionsPath;
+			const base = { source: candidate.source, type: "instruction" as const, name: candidate.name, destination };
+			if (plannedInstructions.has(destination)) {
+				actions.push({
+					...base,
+					operation: "skip",
+					status: "skipped_exists",
+					reason: "another selected source already targets this file; import one source at a time",
+				});
+				continue;
+			}
+
+			let exists = false;
+			try {
+				const stat = await fs.lstat(destination);
+				exists = true;
+				if (!stat.isFile() || stat.isSymbolicLink()) {
+					actions.push({
+						...base,
+						operation: input.force ? "fail" : "skip",
+						status: input.force ? "failed_invalid_destination" : "skipped_exists",
+						reason: "destination is not a regular file; refusing to replace it",
+					});
+					plannedInstructions.add(destination);
+					continue;
+				}
+			} catch (error) {
+				if (!isEnoent(error)) {
+					actions.push({
+						...base,
+						operation: "fail",
+						status: "failed_io",
+						reason: `failed to inspect destination: ${(error as Error).message}`,
+					});
+					plannedInstructions.add(destination);
+					continue;
+				}
+			}
+
+			if (exists && !input.force) {
+				actions.push({ ...base, operation: "skip", status: "skipped_exists" });
+			} else {
+				actions.push({
+					...base,
+					operation: exists ? "update" : "create",
+					status: exists ? "updated" : "imported",
+					instruction: { content: candidate.content },
+				});
+			}
+			plannedInstructions.add(destination);
+		}
+	}
+
 	return { actions, warnings };
 }

package/src/migrate/adapters/claude-code.ts

@@ -1,16 +1,29 @@
 /**
- * Claude Code adapter: reads `~/.claude.json` (mcpServers) and `~/.claude/skills`.
+ * Claude Code adapter: reads `~/.claude.json` (mcpServers), `~/.claude/skills`,
+ * and the selected scope's `CLAUDE.md`.
  */
 import * as path from "node:path";
 import type { AdapterResult, McpCandidate } from "../types";
-import { type Adapter, type AdapterOptions, collectSkillDir, parseSourceJson, readSourceText } from "./index";
+import {
+	type Adapter,
+	type AdapterOptions,
+	collectInstructionFile,
+	collectSkillDir,
+	parseSourceJson,
+	readSourceText,
+} from "./index";
 
 const SOURCE = "claude-code" as const;
 
 export const claudeCodeAdapter: Adapter = {
 	source: SOURCE,
-	async collect({ homeDir }: AdapterOptions): Promise<AdapterResult> {
-		const result: AdapterResult = { mcpCandidates: [], skillCandidates: [], diagnostics: [] };
+	async collect({ homeDir, cwd, scope }: AdapterOptions): Promise<AdapterResult> {
+		const result: AdapterResult = {
+			mcpCandidates: [],
+			skillCandidates: [],
+			instructionCandidates: [],
+			diagnostics: [],
+		};
 
 		const configPath = path.join(homeDir, ".claude.json");
 		const read = await readSourceText(configPath, SOURCE, "mcp");
@@ -34,6 +47,12 @@ export const claudeCodeAdapter: Adapter = {
 		result.skillCandidates.push(...skills.candidates);
 		result.diagnostics.push(...skills.diagnostics);
 
+		const instructionsPath =
+			scope === "project" ? path.join(cwd, "CLAUDE.md") : path.join(homeDir, ".claude", "CLAUDE.md");
+		const instructions = await collectInstructionFile(instructionsPath, SOURCE);
+		result.instructionCandidates.push(...instructions.candidates);
+		result.diagnostics.push(...instructions.diagnostics);
+
 		return result;
 	},
 };

package/src/migrate/adapters/codex.ts

@@ -1,11 +1,18 @@
 /**
- * Codex adapter: reads `~/.codex/config.toml` ([mcp_servers]) and `~/.codex/prompts`.
+ * Codex adapter: reads `~/.codex/config.toml` ([mcp_servers]), `~/.codex/prompts`,
+ * and user-level `~/.codex/AGENTS.md` instructions. Project AGENTS.md is native GJC input.
  */
 
 import * as path from "node:path";
 import { TOML } from "bun";
 import type { AdapterResult, McpCandidate, SourceDiagnostic } from "../types";
-import { type Adapter, type AdapterOptions, collectMarkdownPrompts, readSourceText } from "./index";
+import {
+	type Adapter,
+	type AdapterOptions,
+	collectInstructionFile,
+	collectMarkdownPrompts,
+	readSourceText,
+} from "./index";
 
 const SOURCE = "codex" as const;
 
@@ -40,8 +47,13 @@ function parseToml(
 
 export const codexAdapter: Adapter = {
 	source: SOURCE,
-	async collect({ homeDir }: AdapterOptions): Promise<AdapterResult> {
-		const result: AdapterResult = { mcpCandidates: [], skillCandidates: [], diagnostics: [] };
+	async collect({ homeDir, scope }: AdapterOptions): Promise<AdapterResult> {
+		const result: AdapterResult = {
+			mcpCandidates: [],
+			skillCandidates: [],
+			instructionCandidates: [],
+			diagnostics: [],
+		};
 
 		const configPath = path.join(homeDir, ".codex", "config.toml");
 		const read = await readSourceText(configPath, SOURCE, "mcp");
@@ -65,6 +77,12 @@ export const codexAdapter: Adapter = {
 		result.skillCandidates.push(...prompts.candidates);
 		result.diagnostics.push(...prompts.diagnostics);
 
+		if (scope === "user") {
+			const instructions = await collectInstructionFile(path.join(homeDir, ".codex", "AGENTS.md"), SOURCE);
+			result.instructionCandidates.push(...instructions.candidates);
+			result.diagnostics.push(...instructions.diagnostics);
+		}
+
 		return result;
 	},
 };

package/src/migrate/adapters/index.ts

@@ -1,14 +1,15 @@
 /**
  * Source adapters for `gjc migrate`.
  *
- * Each adapter reads GLOBAL/home config for one source agent and returns
- * normalized MCP + skill candidates plus source-level diagnostics. Adapters never
- * read project-level config and never connect to anything.
+ * Each adapter returns normalized home-scoped MCP/skill candidates, selected-scope
+ * instruction candidates, and source-level diagnostics. Adapters never connect to
+ * anything.
  */
 import * as fs from "node:fs/promises";
+import * as path from "node:path";
 import { isEnoent } from "@gajae-code/utils";
 import { normalizeSkill } from "../skill-normalizer";
-import type { AdapterResult, MigrateSource, SkillCandidate, SourceDiagnostic } from "../types";
+import type { AdapterResult, InstructionCandidate, MigrateSource, SkillCandidate, SourceDiagnostic } from "../types";
 import { claudeCodeAdapter } from "./claude-code";
 import { codexAdapter } from "./codex";
 import { opencodeAdapter } from "./opencode";
@@ -16,6 +17,10 @@ import { opencodeAdapter } from "./opencode";
 export interface AdapterOptions {
 	/** Home directory root; overridable for tests. */
 	homeDir: string;
+	/** Source scope for instructions; other source files remain home-scoped. */
+	scope: "project" | "user";
+	/** Project root used when importing project instructions. */
+	cwd: string;
 }
 
 export interface Adapter {
@@ -33,6 +38,19 @@ export function getAdapter(source: MigrateSource): Adapter {
 	return ADAPTERS[source];
 }
 
+/** Collect one source instruction file without interpreting or rewriting its content. */
+export async function collectInstructionFile(
+	filePath: string,
+	source: MigrateSource,
+): Promise<{ candidates: InstructionCandidate[]; diagnostics: SourceDiagnostic[] }> {
+	const read = await readSourceText(filePath, source, "instruction");
+	if ("diagnostic" in read) return { candidates: [], diagnostics: [read.diagnostic] };
+	return {
+		candidates: [{ source, name: path.basename(filePath), content: read.text }],
+		diagnostics: [],
+	};
+}
+
 /** Read a text file, classifying absence/IO errors into source diagnostics. */
 export async function readSourceText(
 	filePath: string,

package/src/migrate/adapters/opencode.ts

@@ -18,7 +18,12 @@ const SOURCE = "opencode" as const;
 export const opencodeAdapter: Adapter = {
 	source: SOURCE,
 	async collect({ homeDir }: AdapterOptions): Promise<AdapterResult> {
-		const result: AdapterResult = { mcpCandidates: [], skillCandidates: [], diagnostics: [] };
+		const result: AdapterResult = {
+			mcpCandidates: [],
+			skillCandidates: [],
+			instructionCandidates: [],
+			diagnostics: [],
+		};
 		const baseDir = path.join(homeDir, ".config", "opencode");
 
 		const configPath = path.join(baseDir, "opencode.json");

package/src/migrate/executor.ts

@@ -9,6 +9,7 @@
 import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { getTrustedHomeDir } from "@gajae-code/utils";
 import { upsertMCPServer } from "../runtime-mcp/config-writer";
 import type { MigrateAction } from "./types";
 
@@ -19,17 +20,23 @@ function trustedSkillDestinationBase(destination: string): string {
 	return path.basename(scopeRoot) === ".gjc" ? path.dirname(scopeRoot) : scopeRoot;
 }
 
-async function ensureRealDirectoryPathNoFollow(directory: string, trustedBase: string): Promise<void> {
+async function ensureRealDirectoryPathNoFollow(
+	directory: string,
+	trustedBase: string,
+	label = "skill destination",
+	createMissing = true,
+	mode?: number,
+): Promise<void> {
 	const resolvedBase = path.resolve(trustedBase);
 	const resolvedDirectory = path.resolve(directory);
 	const relative = path.relative(resolvedBase, resolvedDirectory);
 	if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-		throw new Error(`skill destination escapes trusted base: ${resolvedDirectory}`);
+		throw new Error(`${label} escapes trusted base: ${resolvedDirectory}`);
 	}
 
 	const baseStat = await fs.stat(resolvedBase);
 	if (!baseStat.isDirectory()) {
-		throw new Error(`skill destination base is not a directory: ${resolvedBase}`);
+		throw new Error(`${label} base is not a directory: ${resolvedBase}`);
 	}
 
 	let current = resolvedBase;
@@ -38,14 +45,17 @@ async function ensureRealDirectoryPathNoFollow(directory: string, trustedBase: s
 		try {
 			const stat = await fs.lstat(current);
 			if (!stat.isDirectory() || stat.isSymbolicLink()) {
-				throw new Error(`skill destination ancestor is not a real directory: ${current}`);
+				throw new Error(`${label} ancestor is not a real directory: ${current}`);
 			}
 		} catch (error) {
 			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-			await fs.mkdir(current);
+			// A missing project `.gjc` is created by the MCP writer (mode 0o700).
+			// Do not mkdir here, or that mode is lost. An existing symlink still fails above.
+			if (!createMissing) return;
+			await fs.mkdir(current, mode === undefined ? undefined : { mode });
 			const stat = await fs.lstat(current);
 			if (!stat.isDirectory() || stat.isSymbolicLink()) {
-				throw new Error(`skill destination ancestor is not a real directory: ${current}`);
+				throw new Error(`${label} ancestor is not a real directory: ${current}`);
 			}
 		}
 	}
@@ -66,7 +76,56 @@ async function writeSkillFileNoFollow(destination: string, content: string): Pro
 	}
 }
 
-export async function executeActions(actions: MigrateAction[]): Promise<MigrateAction[]> {
+async function ensureInstructionDirectory(directory: string, project: boolean): Promise<void> {
+	let trustedBase = path.dirname(directory);
+	if (!project) {
+		const home = path.resolve(getTrustedHomeDir());
+		const resolvedDirectory = path.resolve(directory);
+		const relative = path.relative(home, resolvedDirectory);
+		const isWithinHome =
+			relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+		if (isWithinHome) {
+			trustedBase = home;
+		} else {
+			let current = path.dirname(resolvedDirectory);
+			while (true) {
+				try {
+					const stat = await fs.lstat(current);
+					if (!stat.isDirectory() || stat.isSymbolicLink()) {
+						throw new Error(`user instruction destination ancestor is not a real directory: ${current}`);
+					}
+					trustedBase = current;
+					break;
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+					const parent = path.dirname(current);
+					if (parent === current) throw error;
+					current = parent;
+				}
+			}
+		}
+	}
+	await ensureRealDirectoryPathNoFollow(directory, trustedBase, "instruction destination", true, 0o700);
+}
+
+async function writeInstructionFileNoFollow(destination: string, content: string, project: boolean): Promise<void> {
+	await ensureInstructionDirectory(path.dirname(destination), project);
+	const handle = await fs.open(
+		destination,
+		fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_TRUNC | fsSync.constants.O_NOFOLLOW,
+		0o666,
+	);
+	try {
+		await handle.writeFile(content, "utf-8");
+	} finally {
+		await handle.close();
+	}
+}
+
+export async function executeActions(
+	actions: MigrateAction[],
+	options?: { project?: boolean },
+): Promise<MigrateAction[]> {
 	const out: MigrateAction[] = [];
 	for (const action of actions) {
 		if (action.operation !== "create" && action.operation !== "update") {
@@ -75,6 +134,17 @@ export async function executeActions(actions: MigrateAction[]): Promise<MigrateA
 		}
 		try {
 			if (action.type === "mcp" && action.mcp && action.name && action.destination) {
+				// `project` is the migrate scope, not a guess from the directory name.
+				// A user agent dir may itself be named `.gjc`.
+				if (options?.project) {
+					const directory = path.dirname(action.destination);
+					await ensureRealDirectoryPathNoFollow(
+						directory,
+						path.dirname(path.resolve(directory)),
+						"mcp destination",
+						false,
+					);
+				}
 				await upsertMCPServer(action.destination, action.name, action.mcp.config, {
 					force: action.operation === "update",
 				});
@@ -82,6 +152,13 @@ export async function executeActions(actions: MigrateAction[]): Promise<MigrateA
 			} else if (action.type === "skill" && action.skill && action.destination) {
 				await writeSkillFileNoFollow(action.destination, action.skill.content);
 				out.push(action);
+			} else if (action.type === "instruction" && action.instruction && action.destination) {
+				await writeInstructionFileNoFollow(
+					action.destination,
+					action.instruction.content,
+					options?.project ?? false,
+				);
+				out.push(action);
 			} else {
 				out.push(action);
 			}