@gajae-code/coding-agent 0.16.7 → 0.17.1

package/src/extensibility/plugins/marketplace/registry.ts

@@ -17,6 +17,8 @@ import * as path from "node:path";
 
 import { getConfigRootDir, getPluginsDir, isEnoent, logger, tryParseJson } from "@gajae-code/utils";
 
+import { withFileLock } from "../../../config/file-lock";
+
 import type {
 	InstalledPluginEntry,
 	InstalledPluginsRegistry,
@@ -131,6 +133,157 @@ export async function writeInstalledPluginsRegistry(filePath: string, reg: Insta
 	await atomicWriteJson(filePath, reg);
 }
 
+/**
+ * Refuse a registry file that is not an ordinary, singly-linked regular file:
+ * a symlink could redirect the write elsewhere, and a hard link (nlink > 1)
+ * means the mutation would silently also change another path. Absence is not
+ * a refusal — that is the normal "nothing installed yet" state.
+ */
+async function assertOrdinaryRegistryFile(filePath: string): Promise<void> {
+	let stat: import("node:fs").Stats;
+	try {
+		stat = await fs.lstat(filePath);
+	} catch (err) {
+		if (isEnoent(err)) return;
+		throw err;
+	}
+	if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink > 1) {
+		throw Object.assign(new Error(`Installed plugins registry at ${filePath} is not a safe ordinary file`), {
+			code: "unsafe_registry_link",
+		});
+	}
+}
+
+/**
+ * Strict read for mutation/CAS callers: a missing file is legitimately empty,
+ * but malformed JSON or an unexpected shape must never be silently treated as
+ * an empty registry — that would let a mutating writer overwrite (and lose)
+ * an unreadable but non-empty registry. Use {@link readInstalledPluginsRegistry}
+ * for lenient, display-only reads.
+ */
+async function readInstalledPluginsRegistryStrict(filePath: string): Promise<InstalledPluginsRegistry> {
+	await assertOrdinaryRegistryFile(filePath);
+	let text: string;
+	try {
+		text = await fs.readFile(filePath, "utf8");
+	} catch (err) {
+		if (isEnoent(err)) return emptyInstalledPluginsRegistry();
+		throw err;
+	}
+	const data = tryParseJson<InstalledPluginsRegistry>(text);
+	if (
+		!data ||
+		typeof data !== "object" ||
+		typeof data.version !== "number" ||
+		!data.plugins ||
+		typeof data.plugins !== "object" ||
+		Array.isArray(data.plugins)
+	) {
+		throw Object.assign(new Error(`Installed plugins registry is malformed at ${filePath}`), {
+			code: "malformed_registry",
+		});
+	}
+	return { ...data, version: 2 };
+}
+
+/** dev/ino/mtime/size identity of a file plus its parent directory, for exact CAS. */
+async function fileParentIdentity(filePath: string): Promise<Record<string, string> | null> {
+	try {
+		const stat = await fs.lstat(filePath, { bigint: true });
+		const parent = await fs.lstat(path.dirname(filePath), { bigint: true });
+		return {
+			dev: stat.dev.toString(),
+			ino: stat.ino.toString(),
+			mtimeNs: stat.mtimeNs.toString(),
+			size: stat.size.toString(),
+			parentDev: parent.dev.toString(),
+			parentIno: parent.ino.toString(),
+		};
+	} catch {
+		return null;
+	}
+}
+
+function entryBaseline(identity: Record<string, string> | null, entry: InstalledPluginEntry): string {
+	return JSON.stringify({ identity, entry });
+}
+
+export type InstalledPluginEnablementState =
+	| { status: "ok"; enabled: boolean; baseline: string }
+	| { status: "not_installed" }
+	| { status: "malformed" }
+	| { status: "unsafe_link" };
+
+/**
+ * Pure read-only snapshot of one (id, scope) entry's durable enablement plus
+ * an exact file+parent CAS baseline. Never touches the cached artifact at
+ * `installPath` — presence/absence of that artifact is a D6 concern, not D7's.
+ * A symlinked or hard-linked registry file is refused distinctly from an
+ * absent ("not_installed"-eligible) or malformed one.
+ */
+export async function getInstalledPluginEnablementState(
+	filePath: string,
+	id: string,
+	scope: "user" | "project",
+): Promise<InstalledPluginEnablementState> {
+	let reg: InstalledPluginsRegistry;
+	try {
+		reg = await readInstalledPluginsRegistryStrict(filePath);
+	} catch (error) {
+		if (error instanceof Error && (error as { code?: string }).code === "unsafe_registry_link")
+			return { status: "unsafe_link" };
+		return { status: "malformed" };
+	}
+	const entry = reg.plugins[id]?.find(e => e.scope === scope);
+	if (!entry) return { status: "not_installed" };
+	const identity = await fileParentIdentity(filePath);
+	return { status: "ok", enabled: entry.enabled !== false, baseline: entryBaseline(identity, entry) };
+}
+
+/**
+ * Update durable marketplace enablement without touching cached artifacts.
+ * Serialized under the canonical native-identity-bound file lock ordinary
+ * marketplace writers use (bounded retries, no blind directory removal).
+ * `expectedBaseline` is required: a caller with no prior read has no CAS
+ * authority and must call {@link getInstalledPluginEnablementState} first.
+ */
+export async function setInstalledPluginEnabled(
+	filePath: string,
+	id: string,
+	scope: "user" | "project",
+	enabled: boolean,
+	expectedBaseline: string,
+): Promise<"updated" | "not_needed"> {
+	return await withFileLock(filePath, async () => {
+		let reg: InstalledPluginsRegistry;
+		try {
+			reg = await readInstalledPluginsRegistryStrict(filePath);
+		} catch (error) {
+			if (error instanceof Error && (error as { code?: string }).code === "unsafe_registry_link") throw error;
+			throw Object.assign(new Error(`Installed plugins registry is malformed at ${filePath}`), {
+				code: "malformed_registry",
+				cause: error,
+			});
+		}
+		const entries = reg.plugins[id];
+		const index = entries?.findIndex(entry => entry.scope === scope) ?? -1;
+		if (!entries || index < 0)
+			throw Object.assign(new Error(`Plugin "${id}" is not installed in ${scope} scope`), { code: "not_installed" });
+		const current = entries[index] as InstalledPluginEntry;
+		const identity = await fileParentIdentity(filePath);
+		const baseline = entryBaseline(identity, current);
+		if (baseline !== expectedBaseline)
+			throw Object.assign(new Error("The installed plugin entry changed since it was reviewed"), {
+				code: "stale_baseline",
+			});
+		if ((current.enabled ?? true) === enabled) return "not_needed";
+		const nextEntries = [...entries];
+		nextEntries[index] = { ...current, enabled };
+		await writeInstalledPluginsRegistry(filePath, { ...reg, plugins: { ...reg.plugins, [id]: nextEntries } });
+		return "updated";
+	});
+}
+
 // ── Marketplace CRUD ─────────────────────────────────────────────────
 // Pure functions that transform registry state. Caller is responsible for
 // reading, mutating, and writing back.

package/src/extensibility/plugins/marketplace/source-resolver.ts

@@ -27,6 +27,34 @@ export interface ResolveContext {
 	tmpDir: string;
 }
 
+export function sourcePin(source: PluginSource): { ref?: string; sha?: string; immutable: boolean } {
+	if (typeof source === "string") return { immutable: false };
+	if (source.source === "npm") return { immutable: false };
+	return {
+		ref: source.ref,
+		sha: source.sha,
+		immutable: typeof source.sha === "string" && /^[a-f0-9]{40}$/i.test(source.sha),
+	};
+}
+
+export function assertPinnedSource(source: PluginSource): void {
+	const pin = sourcePin(source);
+	if (!pin.immutable) throw new Error("marketplace restore requires an immutable source SHA");
+}
+
+/**
+ * Independently verify that a resolved git checkout's HEAD matches the pinned
+ * SHA the plan/token claims to restore. `git.clone` already checks out the
+ * exact SHA, but this re-derives the fact from the checkout itself (a fresh
+ * `rev-parse HEAD` in the resolved directory) rather than trusting whatever
+ * the resolver returned, so a resolver bug or a swapped working tree cannot
+ * silently mismatch source and to-be-published bytes.
+ */
+export async function verifyResolvedProvenance(resolvedDir: string, expectedSha: string): Promise<boolean> {
+	const actual = await git.head.sha(resolvedDir).catch(() => null);
+	return typeof actual === "string" && actual.toLowerCase() === expectedSha.toLowerCase();
+}
+
 /**
  * Resolve a plugin source to an absolute local directory path.
  *
@@ -65,12 +93,10 @@ async function resolveRelativeSource(
 
 	// Resolve against marketplace root (not the .Anthropic model-plugin/ catalog subdirectory)
 	const resolved = path.resolve(context.marketplaceClonePath, relativePath);
+	const outsideRoot = `Plugin source "${source}" resolves outside marketplace root ("${context.marketplaceClonePath}")`;
 
-	if (!pathIsWithin(context.marketplaceClonePath, resolved)) {
-		throw new Error(
-			`Plugin source "${source}" resolves outside marketplace root ("${context.marketplaceClonePath}")`,
-		);
-	}
+	if (!pathIsWithin(context.marketplaceClonePath, resolved)) throw new Error(outsideRoot);
+	await assertCanonicalContainment(context.marketplaceClonePath, resolved, outsideRoot);
 
 	await verifyDirExists(resolved, `Plugin source directory does not exist: "${resolved}"`);
 	return { dir: resolved };
@@ -87,13 +113,13 @@ async function resolveObjectSource(
 			// { source: "url", url: "https://github.com/owner/repo.git" }
 			// Despite the name, this is typically a git clone URL
 			const targetDir = path.join(context.tmpDir, `plugin-${crypto.randomUUID()}`);
-			await git.clone(source.url, targetDir, { ref: source.ref, sha: source.sha });
+			await git.clone(assertCloneUrl(source.url), targetDir, { ref: source.ref, sha: source.sha });
 			return { dir: targetDir, tempCloneRoot: targetDir };
 		}
 
 		case "github": {
 			// { source: "github", repo: "owner/repo" }
-			const url = `https://github.com/${source.repo}.git`;
+			const url = `https://github.com/${assertRepoSlug(source.repo)}.git`;
 			const targetDir = path.join(context.tmpDir, `plugin-${crypto.randomUUID()}`);
 			await git.clone(url, targetDir, { ref: source.ref, sha: source.sha });
 			return { dir: targetDir, tempCloneRoot: targetDir };
@@ -103,17 +129,20 @@ async function resolveObjectSource(
 			// { source: "git-subdir", url: "owner/repo" | "https://...", path: "plugins/foo" }
 			const url =
 				source.url.includes("://") || source.url.startsWith("git@")
-					? source.url
-					: `https://github.com/${source.url}.git`;
+					? assertCloneUrl(source.url)
+					: `https://github.com/${assertRepoSlug(source.url)}.git`;
+			assertSubdirPath(source.path);
 			const cloneDir = path.join(context.tmpDir, `plugin-repo-${crypto.randomUUID()}`);
 			await git.clone(url, cloneDir, { ref: source.ref, sha: source.sha });
 
 			const subdirPath = path.resolve(cloneDir, source.path);
+			const escapes = `git-subdir path "${source.path}" escapes the cloned repository`;
 			if (!pathIsWithin(cloneDir, subdirPath)) {
 				await fs.rm(cloneDir, { recursive: true, force: true });
-				throw new Error(`git-subdir path "${source.path}" escapes the cloned repository`);
+				throw new Error(escapes);
 			}
 			try {
+				await assertCanonicalContainment(cloneDir, subdirPath, escapes);
 				await verifyDirExists(subdirPath, `git-subdir path "${source.path}" does not exist in cloned repository`);
 			} catch (err) {
 				await fs.rm(cloneDir, { recursive: true, force: true });
@@ -132,6 +161,83 @@ async function resolveObjectSource(
 
 // ── Helpers ─────────────────────────────────────────────────────────
 
+/** Network transports a plugin source may be fetched over. */
+const CLONE_URL_SCHEME = /^(?:https|http|git|ssh|file):\/\//;
+/** scp-like `user@host:path`, which git accepts without a scheme. */
+const SCP_LIKE_URL = /^[A-Za-z0-9._-]+@[A-Za-z0-9._-]+:/;
+/** `git-remote-<helper>` dispatch (`ext::sh -c ...`), i.e. arbitrary command execution. */
+const REMOTE_HELPER_URL = /^[A-Za-z0-9][A-Za-z0-9+.-]*::/;
+/** `owner/repo` as GitHub itself accepts it; no options, no path traversal, no separators. */
+const REPO_SLUG = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/**
+ * A catalog is untrusted input, and its URL goes straight to `git clone`.
+ *
+ * Two shapes are dangerous on their own: a value starting with `-`, which git
+ * reads as an option (`--upload-pack=<cmd>` is command execution), and a
+ * remote-helper URL such as `ext::sh -c ...`, which git dispatches to
+ * `git-remote-ext` and which executes its argument by design. `git.clone` also
+ * passes `--` before the URL, but that only closes the first hole and only for
+ * callers that go through it, so both are refused here where the failure can
+ * name the offending catalog entry.
+ *
+ * Local absolute paths stay allowed: a privately hosted marketplace pointing at
+ * an on-disk repository is a supported layout.
+ */
+function assertCloneUrl(url: string): string {
+	const supported =
+		!url.startsWith("-") &&
+		!REMOTE_HELPER_URL.test(url) &&
+		(CLONE_URL_SCHEME.test(url) || SCP_LIKE_URL.test(url) || path.isAbsolute(url));
+	if (!supported)
+		throw new Error(
+			`Plugin source URL must be an https/http/git/ssh/file URL, a user@host:path remote, or an absolute local path — got: "${url}"`,
+		);
+	return url;
+}
+
+function assertRepoSlug(repo: string): string {
+	if (!REPO_SLUG.test(repo)) throw new Error(`Plugin source repository must be "owner/repo" — got: "${repo}"`);
+	return repo;
+}
+
+/** The subdir is joined into a clone path, so it must be a plain relative path. */
+function assertSubdirPath(subdir: string): string {
+	if (subdir.startsWith("-") || path.isAbsolute(subdir) || path.win32.isAbsolute(subdir))
+		throw new Error(`git-subdir path must be a relative path — got: "${subdir}"`);
+	return subdir;
+}
+
+/**
+ * Decide containment on canonical paths, and fail closed when they cannot be
+ * derived.
+ *
+ * A catalog is untrusted input and controls the tree it ships, so the plugin
+ * directory it names can be a symlink pointing out of the marketplace root.
+ * `pathIsWithin` does resolve symlinks, but it silently degrades to a lexical
+ * comparison whenever `realpath` fails — a dangling or looping link therefore
+ * passes the containment gate and is only rejected later (or not at all) by the
+ * existence probe, which follows symlinks itself. Here both sides must
+ * canonicalize successfully. A candidate that exists as a directory entry but
+ * cannot be canonicalized (dangling or looping link) is classified as an
+ * untrusted source; a path that is simply absent is left to the existence probe
+ * so a missing plugin still reports as missing.
+ */
+async function assertCanonicalContainment(root: string, candidate: string, errorMessage: string): Promise<void> {
+	const canonicalRoot = await fs.realpath(root).catch(() => undefined);
+	if (canonicalRoot === undefined) throw new Error(errorMessage);
+	const canonicalCandidate = await fs.realpath(candidate).catch(() => undefined);
+	if (canonicalCandidate === undefined) {
+		const entryExists = await fs
+			.lstat(candidate)
+			.then(() => true)
+			.catch(() => false);
+		if (entryExists) throw new Error(errorMessage);
+		return;
+	}
+	if (!pathIsWithin(canonicalRoot, canonicalCandidate)) throw new Error(errorMessage);
+}
+
 async function verifyDirExists(dirPath: string, errorMessage: string): Promise<void> {
 	try {
 		const stat = await fs.stat(dirPath);

package/src/extensibility/runtime-skill-discovery.ts

@@ -10,6 +10,7 @@ import { findRepoRoot } from "../capability/fs";
 import type { Skill as CapabilitySkill } from "../capability/skill";
 import type { SkillsSettings } from "../config/settings-schema";
 import { resolveSkillScopeTrust } from "../config/skill-settings-defaults";
+import { BUNDLED_GJC_SKILL_CATALOG } from "../defaults/gjc-skills.generated";
 import { scanClaudeProjectSkills, scanClaudeUserSkills } from "../discovery/claude";
 import { loadMarketplaceSkills } from "../discovery/claude-plugins";
 import { scanCodexProjectSkills, scanCodexUserSkills } from "../discovery/codex";
@@ -27,7 +28,9 @@ import {
 import { expandTilde } from "../tools/path-utils";
 import { loadSkills, type Skill } from "./skills";
 
-export type RuntimeSkillDiscoverySource = "project" | "user";
+export type RuntimeSkillDiscoverySource = "project" | "user" | "bundled";
+/** Search requests cover filesystem scopes; bundled is only a candidate source. */
+type RuntimeSkillDiscoveryScope = Exclude<RuntimeSkillDiscoverySource, "bundled">;
 
 export interface RuntimeSkillDiscoveryCandidate {
 	name: string;
@@ -49,6 +52,8 @@ export interface RuntimeSkillDiscoveryDiagnostics {
 
 export interface RuntimeSkillDiscoveryResult {
 	candidates: RuntimeSkillDiscoveryCandidate[];
+	/** Deduped skill metadata the query filter ran against, including bundled entries; candidates.length <= scanned. */
+	scanned: number;
 	diagnostics: RuntimeSkillDiscoveryDiagnostics;
 }
 
@@ -60,7 +65,7 @@ export interface DiscoverRuntimeSkillsOptions {
 	profileAuthority?: "default" | "custom";
 	query?: string;
 	limit?: number;
-	source?: RuntimeSkillDiscoverySource | "all";
+	source?: RuntimeSkillDiscoveryScope | "all";
 	policy?: SkillsSettings;
 }
 
@@ -146,7 +151,7 @@ function getUseWhen(skill: CapabilitySkill): string[] | undefined {
 	return values.length > 0 ? values : undefined;
 }
 
-function sourceEnabled(source: RuntimeSkillDiscoverySource, policy: SkillsSettings | undefined): boolean {
+function sourceEnabled(source: RuntimeSkillDiscoveryScope, policy: SkillsSettings | undefined): boolean {
 	if (policy?.enabled !== true) return false;
 	return resolveSkillScopeTrust(policy, source);
 }
@@ -184,7 +189,7 @@ async function realPathOrSelf(filePath: string): Promise<string> {
 }
 
 interface ScanJobResult {
-	items: Array<{ skill: CapabilitySkill; source: RuntimeSkillDiscoverySource; providerPriority: number }>;
+	items: Array<{ skill: CapabilitySkill; source: RuntimeSkillDiscoveryScope; providerPriority: number }>;
 	warnings: string[];
 	label: string;
 }
@@ -261,12 +266,13 @@ async function scanProjectOrUserDir(
 	dir: string,
 	level: "project" | "user",
 	label: string,
-	source: RuntimeSkillDiscoverySource,
+	source: RuntimeSkillDiscoveryScope,
 	providerPriority: number,
 	authorityRoot?: string,
 ): Promise<ScanJobResult> {
 	const result = await scanSkillsFromDir(ctx, {
 		dir,
+		linkContainmentRoot: level === "project" ? (ctx.repoRoot ?? undefined) : undefined,
 		authorityRoot,
 		providerId: "runtime",
 		level,
@@ -282,7 +288,7 @@ async function scanProjectOrUserDir(
 interface ConventionImportScan {
 	host: "Claude Code" | "Codex";
 	dir: string;
-	scope: RuntimeSkillDiscoverySource;
+	scope: RuntimeSkillDiscoveryScope;
 	skills: CapabilitySkill[];
 }
 
@@ -297,7 +303,7 @@ interface ConventionImportScan {
  */
 async function collectConventionImportCandidates(
 	ctx: { cwd: string; home: string; repoRoot: string | null },
-	source: RuntimeSkillDiscoverySource | "all",
+	source: RuntimeSkillDiscoveryScope | "all",
 	policy: SkillsSettings | undefined,
 ): Promise<ConventionImportScan[]> {
 	const scans: ConventionImportScan[] = [];
@@ -359,7 +365,7 @@ function reportConventionImportCandidates(
  * tool and `gjc skills discover`.
  */
 export function describeDisabledSkillScopes(
-	source: RuntimeSkillDiscoverySource | "all",
+	source: RuntimeSkillDiscoveryScope | "all",
 	policy: SkillsSettings | undefined,
 ): string | undefined {
 	if (policy?.enabled !== true) {
@@ -379,6 +385,36 @@ export function describeDisabledSkillScopes(
 	return `Skill discovery skipped disabled scope(s): ${skipped.join(", ")}. Enable them with ${commands.join(" and ")}.`;
 }
 
+/**
+ * Explain a zero-candidate result caused by the conjunctive query filter rather
+ * than by an empty catalog or disabled scopes: every whitespace-separated term
+ * must appear in a candidate's name, description, source, or use conditions (or
+ * one term must equal the exact skill name), so a single keyword that appears
+ * nowhere drops every skill. Shared by the skill_discovery tool.
+ */
+export function describeNoSkillMatch(query: string | undefined, scanned: number): string | undefined {
+	const trimmed = (query ?? "").trim();
+	if (trimmed.length === 0 || scanned === 0) return undefined;
+	return `No skill matched every query term (${scanned} skill${scanned === 1 ? "" : "s"} scanned). Matching is conjunctive substring: every whitespace-separated term must appear in the skill's name, description, source, or use conditions, unless a term equals the exact skill name. Retry with the exact skill name or fewer terms; a zero-candidate result does not prove no skills exist.`;
+}
+
+function getBundledSkillCandidates(): RuntimeSkillDiscoveryCandidate[] {
+	// Catalog loaders remain lazy; discovery reads only each entry's metadata.
+	return BUNDLED_GJC_SKILL_CATALOG.flatMap(entry => {
+		if (entry.kind !== "skill" || entry.name === undefined) return [];
+		return [
+			{
+				name: entry.name,
+				description: entry.description ?? "",
+				source: "bundled" as const,
+				// `embedded:gjc/...` is the stable non-filesystem identifier used by
+				// bundled Skill metadata; the relative path comes from the generated catalog.
+				path: `embedded:gjc/${entry.relativePath}`,
+			},
+		];
+	});
+}
+
 export async function discoverRuntimeSkills(
 	options: DiscoverRuntimeSkillsOptions,
 ): Promise<RuntimeSkillDiscoveryResult> {
@@ -442,7 +478,7 @@ export async function discoverRuntimeSkills(
 			collectPluginSkills(home, options.cwd, allowedLevels).then(result => ({
 				items: result.items.map(skill => ({
 					skill,
-					source: skill.level as RuntimeSkillDiscoverySource,
+					source: skill.level as RuntimeSkillDiscoveryScope,
 					providerPriority: 70,
 				})),
 				warnings: result.warnings,
@@ -461,6 +497,20 @@ export async function discoverRuntimeSkills(
 	const seenNames = new Set<string>();
 	const seenPaths = new Set<string>();
 	const candidates: RuntimeSkillDiscoveryCandidate[] = [];
+	let scanned = 0;
+	// Bundled workflow skills are neither project nor user scope, so explicit
+	// project/user requests exclude them; source "all" includes them regardless
+	// of filesystem trust and include/ignore/disabled policy filters because the
+	// bundled definitions cannot be replaced.
+	if (source === "all") {
+		for (const candidate of getBundledSkillCandidates()) {
+			const normalizedName = getSkillFilesystemIdentity(candidate.name);
+			seenNames.add(normalizedName);
+			seenPaths.add(candidate.path);
+			scanned += 1;
+			if (matchesQuery(candidate, options.query ?? "")) candidates.push(candidate);
+		}
+	}
 	const orderedItems: ScanJobResult["items"] = [];
 	for (const entry of settled) {
 		if ("error" in entry) {
@@ -499,6 +549,7 @@ export async function discoverRuntimeSkills(
 			path: item.skill.path,
 			useWhen: getUseWhen(item.skill),
 		};
+		scanned += 1;
 		if (matchesQuery(candidate, options.query ?? "")) candidates.push(candidate);
 	}
 	candidates.sort((a, b) => compareSkillOrder(a.name, a.path, b.name, b.path));
@@ -509,6 +560,7 @@ export async function discoverRuntimeSkills(
 	);
 	return {
 		candidates: candidates.slice(0, normalizeLimit(options.limit)),
+		scanned,
 		diagnostics: { messages: diagnostics },
 	};
 }

package/src/extensibility/skill-management.ts

@@ -329,7 +329,13 @@ export async function listNativeSkillsForManagement(options: {
 			scanJobs.push(
 				scanSkillsFromDir(
 					{ cwd: options.cwd, home, repoRoot: projectDirs.repoRoot },
-					{ dir, providerId: "runtime", level: "project", requireDescription: true },
+					{
+						dir,
+						linkContainmentRoot: projectDirs.repoRoot ?? undefined,
+						providerId: "runtime",
+						level: "project",
+						requireDescription: true,
+					},
 				).then(result => ({ dir, scope: "project" as const, items: result.items })),
 			);
 		}

package/src/gjc-runtime/autoresearch-runtime.ts

@@ -894,6 +894,15 @@ export async function autoresearchIssueVerdict(input: {
 
 /* ------------------------------ CLI dispatch ------------------------------ */
 
+/**
+ * A help request is `--help`/`-h` anywhere in the argv, or a leading `help`
+ * verb. Exported so the CLI command class routes help back through this
+ * runtime instead of a generic command-level fallback.
+ */
+export function isAutoresearchHelpInvocation(args: readonly string[]): boolean {
+	return args.includes("--help") || args.includes("-h") || args[0] === "help";
+}
+
 function renderAutoresearchHelp(): string {
 	return [
 		"Run native GJC Autoresearch workflow commands",
@@ -1081,7 +1090,7 @@ export async function runNativeAutoresearchCommand(
 	cwd = process.cwd(),
 ): Promise<AutoresearchCommandResult> {
 	try {
-		if (args.includes("--help") || args.includes("-h") || args[0] === "help") {
+		if (isAutoresearchHelpInvocation(args)) {
 			return { status: 0, stdout: renderAutoresearchHelp() };
 		}
 		const verb = args[0];