@gajae-code/coding-agent 0.11.11 → 0.12.1

package/src/extensibility/gjc-plugins/runtime-adapters.ts

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import { bindPluginMcpToPublicNetwork } from "../../runtime-mcp/plugin-network-boundary";
 import { loadCustomTools } from "../custom-tools/loader";
 import type { CustomTool } from "../custom-tools/types";
+import { bundleIdentity } from "./lifecycle-reconciliation";
 import { loadEffectiveGjcPluginRegistry, registryPathForScope } from "./registry";
 import { type SessionQuarantine, type SessionValidationResult, validateSessionBundles } from "./session-validation";
 import type { GjcPluginRegistryEntry, GjcPluginScope } from "./types";
@@ -105,6 +106,7 @@ async function verifyEntryHashesCached(entry: GjcPluginRegistryEntry): Promise<S
 		const snapshot = await snapshotExistingFile(abs);
 		if (!snapshot) {
 			return {
+				identity: bundleIdentity(entry.scope, entry.name),
 				plugin: entry.name,
 				surfaceId: `plugin:${entry.name}`,
 				code: "runtime_mismatch",
@@ -113,6 +115,7 @@ async function verifyEntryHashesCached(entry: GjcPluginRegistryEntry): Promise<S
 		}
 		if ((await hashFile(snapshot)) !== file.sha256) {
 			return {
+				identity: bundleIdentity(entry.scope, entry.name),
 				plugin: entry.name,
 				surfaceId: `plugin:${entry.name}`,
 				code: "runtime_mismatch",
@@ -186,12 +189,16 @@ export async function loadAlwaysOnPluginTools(input: {
 	);
 
 	// Map declared (path -> name) for every active always-on tool surface.
-	const declared = new Map<string, { name: string; plugin: string }>();
+	const declared = new Map<string, { name: string; plugin: string; scope: GjcPluginScope }>();
 	for (const entry of active) {
 		const disabled = new Set(entry.disabledSurfaceIds);
 		for (const t of entry.surfaces.tools) {
 			if (disabled.has(t.extensionId)) continue;
-			declared.set(path.join(entry.pluginRoot, t.relativePath), { name: t.name, plugin: entry.name });
+			declared.set(path.join(entry.pluginRoot, t.relativePath), {
+				name: t.name,
+				plugin: entry.name,
+				scope: entry.scope,
+			});
 		}
 	}
 	if (declared.size === 0) return { tools: [], quarantine };
@@ -218,6 +225,7 @@ export async function loadAlwaysOnPluginTools(input: {
 		// Manifest is authoritative: exactly the one declared name must come back.
 		if (returned.length !== 1 || returned[0] !== info.name) {
 			quarantine.push({
+				identity: bundleIdentity(info.scope, info.plugin),
 				plugin: info.plugin,
 				surfaceId: `tool:${info.name}`,
 				code: "runtime_mismatch",
@@ -228,6 +236,7 @@ export async function loadAlwaysOnPluginTools(input: {
 		if (seenNames.has(info.name)) {
 			// Defense in depth: never overwrite a reserved/earlier name.
 			quarantine.push({
+				identity: bundleIdentity(info.scope, info.plugin),
 				plugin: info.plugin,
 				surfaceId: `tool:${info.name}`,
 				code: "session_collision",
@@ -335,6 +344,7 @@ export async function buildPluginMcpConfigs(input: { cwd: string }): Promise<{
 				}
 			} catch (error) {
 				quarantine.push({
+					identity: bundleIdentity(entry.scope, entry.name),
 					plugin: entry.name,
 					surfaceId: m.extensionId,
 					code: "security_policy",

package/src/extensibility/gjc-plugins/runtime-quarantine.ts

@@ -0,0 +1,121 @@
+import { identityEquals, identityKey } from "./lifecycle-reconciliation";
+import type { GjcBundleIdentity, GjcRuntimeFinding, GjcRuntimeSnapshot, GjcRuntimeSnapshotState } from "./types";
+
+/**
+ * Deterministic numeric activation generation for an activation fingerprint.
+ *
+ * Equal activation inputs yield an equal generation, so a consumer holding a
+ * snapshot can tell whether it still describes the state it is rendering.
+ * Derived from the fingerprint's leading hex so it stays inside the safe
+ * integer range.
+ */
+export function gjcActivationGenerationFor(activationFingerprint: string): number {
+	const parsed = Number.parseInt(activationFingerprint.slice(0, 13), 16);
+	return Number.isSafeInteger(parsed) ? parsed : 0;
+}
+
+/**
+ * Caller-owned accumulator for scope-qualified runtime evidence.
+ *
+ * Producers (loaders, adapters, validators) hand findings to an accumulator
+ * they were given; they never publish. Exactly one coordinator publishes a
+ * complete generation snapshot, and consumers merge it only when the identity
+ * and generation match.
+ */
+export class GjcRuntimeFindingAccumulator {
+	private readonly findings: GjcRuntimeFinding[] = [];
+
+	constructor(readonly generation: number) {}
+
+	add(finding: GjcRuntimeFinding): void {
+		this.findings.push(finding);
+	}
+
+	addAll(findings: readonly GjcRuntimeFinding[]): void {
+		for (const finding of findings) this.add(finding);
+	}
+
+	/** Sorted, de-duplicated snapshot for the generation this accumulator owns. */
+	snapshot(): GjcRuntimeSnapshot {
+		const seen = new Set<string>();
+		const unique: GjcRuntimeFinding[] = [];
+		for (const finding of this.findings) {
+			const key = [identityKey(finding.identity), finding.surfaceId, finding.code, finding.message].join("\u0000");
+			if (seen.has(key)) continue;
+			seen.add(key);
+			unique.push(finding);
+		}
+		unique.sort((a, b) => {
+			const ka = `${identityKey(a.identity)}\u0000${a.surfaceId}\u0000${a.code}`;
+			const kb = `${identityKey(b.identity)}\u0000${b.surfaceId}\u0000${b.code}`;
+			return ka.localeCompare(kb);
+		});
+		return { generation: this.generation, findings: unique };
+	}
+}
+
+/** Read-only view of the most recently published complete generation. */
+export interface GjcRuntimeSnapshotProvider {
+	current(): GjcRuntimeSnapshotState;
+}
+
+/**
+ * Single-writer publisher for runtime evidence.
+ *
+ * Passes can overlap: the session's prompt rebuild is re-entrant, so a second
+ * pass may start while a first is still awaiting its producers. Publication is
+ * therefore fenced by a monotonic epoch. A pass reserves an epoch when it
+ * begins, which immediately retires whatever was published before, and its
+ * later publish is accepted only if no newer pass has reserved since. A slow or
+ * failed older pass can never overwrite a newer one, and an incomplete pass
+ * simply never publishes, leaving consumers at `unavailable`.
+ */
+export class GjcRuntimeSnapshotStore implements GjcRuntimeSnapshotProvider {
+	private state: GjcRuntimeSnapshotState = { status: "unavailable" };
+	private epoch = 0;
+
+	/**
+	 * Begin a pass. Retires the current snapshot and returns the epoch token the
+	 * caller must present to publish.
+	 */
+	beginPass(): number {
+		this.epoch += 1;
+		this.state = { status: "unavailable" };
+		return this.epoch;
+	}
+
+	/** Publish only if `epoch` is still the newest reserved pass. */
+	publish(snapshot: GjcRuntimeSnapshot, epoch?: number): void {
+		if (epoch !== undefined && epoch !== this.epoch) return;
+		this.state = { status: "current", snapshot };
+	}
+
+	invalidate(): void {
+		this.state = { status: "unavailable" };
+	}
+
+	current(): GjcRuntimeSnapshotState {
+		return this.state;
+	}
+}
+
+/**
+ * Findings for one bundle, but only when the snapshot is current AND describes
+ * the exact generation the consumer is rendering. Missing provider, mismatched
+ * generation, or unavailable state resolve to `unavailable` — never to a
+ * silently empty "clear" result.
+ */
+export function findingsForBundle(
+	provider: GjcRuntimeSnapshotProvider | undefined,
+	identity: GjcBundleIdentity,
+	expectedGeneration: number,
+): { status: "unavailable" } | { status: "current"; findings: GjcRuntimeFinding[] } {
+	if (!provider) return { status: "unavailable" };
+	const state = provider.current();
+	if (state.status !== "current") return { status: "unavailable" };
+	if (state.snapshot.generation !== expectedGeneration) return { status: "unavailable" };
+	return {
+		status: "current",
+		findings: state.snapshot.findings.filter(f => identityEquals(f.identity, identity)),
+	};
+}

package/src/extensibility/gjc-plugins/schema.ts

@@ -5,6 +5,7 @@ import {
 	type GjcPluginAppendixManifestEntry,
 	type GjcPluginHookManifestEntry,
 	GjcPluginLoadError,
+	type GjcPluginLoadErrorCode,
 	type GjcPluginManifest,
 	type GjcPluginMcpManifestEntry,
 	type GjcPluginMcpTransport,
@@ -53,6 +54,67 @@ function requireNonEmptyString(value: unknown, field: string, filePath: string):
 	return value;
 }
 
+/**
+ * A bundle name is echoed by the CLI, rendered in Settings, and used to derive
+ * a directory segment, so it is constrained at the parse boundary rather than
+ * sanitized at every display site. Anything outside this set — control or ANSI
+ * sequences, path separators, whitespace, or credential-looking text — is
+ * rejected before it can ever be stored.
+ */
+function manifestSafeName(
+	value: unknown,
+	field: string,
+	manifestPath: string,
+	code: GjcPluginLoadErrorCode = "invalid_manifest",
+): string {
+	const name =
+		code === "invalid_frontmatter"
+			? requireNonEmptyString(value, field, manifestPath)
+			: manifestString(value, field, manifestPath);
+	if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(name)) {
+		throw new GjcPluginLoadError(
+			code,
+			`GJC plugin ${field} must be 1-128 characters of letters, digits, dot, underscore, or hyphen (${manifestPath})`,
+		);
+	}
+	return name;
+}
+
+/**
+ * Free-form prose that is rendered into prompts or UI. It is not constrained to
+ * the identifier grammar, but control and ANSI characters are rejected so a
+ * manifest cannot inject escape sequences into a rendered surface.
+ */
+function manifestSafeProse(
+	value: unknown,
+	field: string,
+	manifestPath: string,
+	code: GjcPluginLoadErrorCode = "invalid_manifest",
+): string {
+	const text = requireNonEmptyString(value, field, manifestPath);
+	// C0, DEL, and the C1 block: a single-byte CSI (U+009B) is an escape
+	// introducer on its own, so rejecting only C0 leaves the same injection open.
+	if (/[\u0000-\u001f\u007f-\u009f]/.test(text)) {
+		throw new GjcPluginLoadError(code, `GJC plugin ${field} must not contain control characters (${manifestPath})`);
+	}
+	return text;
+}
+
+/**
+ * A version string is rendered next to the bundle name everywhere the bundle
+ * appears, so it is constrained to printable version-like characters.
+ */
+function manifestSafeVersion(value: unknown, manifestPath: string): string {
+	const version = manifestString(value, "version", manifestPath);
+	if (!/^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,63}$/.test(version)) {
+		throw new GjcPluginLoadError(
+			"invalid_manifest",
+			`GJC plugin version must be 1-64 characters of letters, digits, dot, plus, underscore, or hyphen (${manifestPath})`,
+		);
+	}
+	return version;
+}
+
 function manifestString(value: unknown, field: string, manifestPath: string): string {
 	if (typeof value !== "string" || value.trim().length === 0) {
 		throw new GjcPluginLoadError(
@@ -109,12 +171,12 @@ function parseTools(value: unknown, manifestPath: string): GjcPluginToolManifest
 				`Invalid GJC plugin manifest at ${manifestPath}: tools[${index}] must be a string or object`,
 			);
 		}
-		const name = manifestString(entry.name, `tools[${index}].name`, manifestPath);
+		const name = manifestSafeName(entry.name, `tools[${index}].name`, manifestPath);
 		const path = manifestString(entry.path, `tools[${index}].path`, manifestPath);
 		const description =
 			entry.description === undefined
 				? undefined
-				: manifestString(entry.description, `tools[${index}].description`, manifestPath);
+				: manifestSafeProse(entry.description, `tools[${index}].description`, manifestPath);
 		const sha256 =
 			entry.sha256 === undefined ? undefined : manifestString(entry.sha256, `tools[${index}].sha256`, manifestPath);
 		return { name, path, description, sha256, surface: "always-on" };
@@ -130,11 +192,15 @@ function parseHooks(value: unknown, manifestPath: string): GjcPluginHookManifest
 				`Invalid GJC plugin manifest at ${manifestPath}: hooks[${index}] must be an object`,
 			);
 		}
-		const name = manifestString(entry.name, `hooks[${index}].name`, manifestPath);
-		const event = manifestString(entry.event, `hooks[${index}].event`, manifestPath);
+		const name = manifestSafeName(entry.name, `hooks[${index}].name`, manifestPath);
+		// event/target become part of the hook surface ID
+		// (`hook:<event>:<phase>:<target>:<name>`), which is rendered and printed.
+		const event = manifestSafeName(entry.event, `hooks[${index}].event`, manifestPath);
 		const path = manifestString(entry.path, `hooks[${index}].path`, manifestPath);
 		const target =
-			entry.target === undefined ? undefined : manifestString(entry.target, `hooks[${index}].target`, manifestPath);
+			entry.target === undefined
+				? undefined
+				: manifestSafeName(entry.target, `hooks[${index}].target`, manifestPath);
 		let phase: "before" | "after" | undefined;
 		if (entry.phase !== undefined) {
 			if (entry.phase !== "before" && entry.phase !== "after") {
@@ -160,7 +226,7 @@ function parseMcps(value: unknown, manifestPath: string): GjcPluginMcpManifestEn
 				`Invalid GJC plugin manifest at ${manifestPath}: mcps[${index}] must be an object`,
 			);
 		}
-		const name = manifestString(entry.name, `mcps[${index}].name`, manifestPath);
+		const name = manifestSafeName(entry.name, `mcps[${index}].name`, manifestPath);
 		const transport = entry.transport;
 		if (typeof transport !== "string" || !MCP_TRANSPORTS.includes(transport as GjcPluginMcpTransport)) {
 			throw new GjcPluginLoadError(
@@ -207,7 +273,7 @@ function parseAppendixEntry(entry: unknown, field: string, manifestPath: string)
 			`Invalid GJC plugin manifest at ${manifestPath}: ${field} must be an object`,
 		);
 	}
-	const name = manifestString(entry.name, `${field}.name`, manifestPath);
+	const name = manifestSafeName(entry.name, `${field}.name`, manifestPath);
 	const path = entry.path === undefined ? undefined : manifestString(entry.path, `${field}.path`, manifestPath);
 	// Content may be empty/whitespace here; the compiler enforces non-empty and
 	// maps emptiness to invalid_appendix (not invalid_manifest).
@@ -282,8 +348,8 @@ export function parseManifest(raw: unknown, manifestPath: string): GjcPluginMani
 		);
 	}
 
-	const name = manifestString(raw.name, "name", manifestPath);
-	const version = manifestString(raw.version, "version", manifestPath);
+	const name = manifestSafeName(raw.name, "name", manifestPath);
+	const version = manifestSafeVersion(raw.version, manifestPath);
 
 	return {
 		name,
@@ -300,10 +366,16 @@ export function parseManifest(raw: unknown, manifestPath: string): GjcPluginMani
 
 export function parseSubskillFrontmatter(fm: Record<string, unknown>, filePath: string): SubskillFrontmatter {
 	return {
-		name: requireNonEmptyString(fm.name, "name", filePath),
+		// Name and activation_arg become part of the surface ID
+		// (`subskill:<parent>:<phase>:<arg>`) and are rendered, so they share the
+		// identifier grammar. binds_to and phase are separately checked against
+		// the known parent/phase sets. The description is prose and may not be
+		// constrained to that grammar, but must not carry control characters into
+		// a rendered prompt.
+		name: manifestSafeName(fm.name, "name", filePath, "invalid_frontmatter"),
 		binds_to: requireNonEmptyString(fm.binds_to, "binds_to", filePath),
 		phase: requireNonEmptyString(fm.phase, "phase", filePath),
-		activation_arg: requireNonEmptyString(fm.activation_arg, "activation_arg", filePath),
-		description: requireNonEmptyString(fm.description, "description", filePath),
+		activation_arg: manifestSafeName(fm.activation_arg, "activation_arg", filePath, "invalid_frontmatter"),
+		description: manifestSafeProse(fm.description, "description", filePath, "invalid_frontmatter"),
 	};
 }

package/src/extensibility/gjc-plugins/session-validation.ts

@@ -1,7 +1,8 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import type { GjcPluginLoadErrorCode, GjcPluginRegistryEntry } from "./types";
+import { bundleIdentity, identityKey } from "./lifecycle-reconciliation";
+import type { GjcBundleIdentity, GjcPluginLoadErrorCode, GjcPluginRegistryEntry } from "./types";
 
 /**
  * Session-start validation: the registry is the collision authority. Capability
@@ -22,6 +23,8 @@ export interface SessionCapabilityEvidence {
 }
 
 export interface SessionQuarantine {
+	/** Scope-qualified canonical target this finding belongs to. */
+	identity: GjcBundleIdentity;
 	plugin: string;
 	surfaceId: string;
 	code: GjcPluginLoadErrorCode;
@@ -52,6 +55,7 @@ export async function verifyEntryHashes(entry: GjcPluginRegistryEntry): Promise<
 			buf = await fs.readFile(abs);
 		} catch {
 			return {
+				identity: bundleIdentity(entry.scope, entry.name),
 				plugin: entry.name,
 				surfaceId: `plugin:${entry.name}`,
 				code: "runtime_mismatch",
@@ -60,6 +64,7 @@ export async function verifyEntryHashes(entry: GjcPluginRegistryEntry): Promise<
 		}
 		if (sha256(buf) !== file.sha256) {
 			return {
+				identity: bundleIdentity(entry.scope, entry.name),
 				plugin: entry.name,
 				surfaceId: `plugin:${entry.name}`,
 				code: "runtime_mismatch",
@@ -103,7 +108,7 @@ export function validateSessionBundles(
 	preQuarantined: readonly SessionQuarantine[] = [],
 ): SessionValidationResult {
 	const quarantine: SessionQuarantine[] = [...preQuarantined];
-	const quarantinedPlugins = new Set(preQuarantined.map(q => q.plugin));
+	const quarantinedPlugins = new Set(preQuarantined.map(q => identityKey(q.identity)));
 
 	const seenTools = new Set<string>(evidence.toolNames ?? []);
 	const seenMcps = new Set<string>(evidence.mcpNames ?? []);
@@ -113,12 +118,13 @@ export function validateSessionBundles(
 	const active: GjcPluginRegistryEntry[] = [];
 	for (const entry of entries) {
 		if (!entry.enabled) continue; // user-disabled, not an error
-		if (quarantinedPlugins.has(entry.name)) continue;
+		if (quarantinedPlugins.has(identityKey(bundleIdentity(entry.scope, entry.name)))) continue;
 		const surfaces = activeSurfaceIds(entry);
 		let collided = false;
 		const recordCollision = (surfaceId: string, what: string): void => {
 			collided = true;
 			quarantine.push({
+				identity: bundleIdentity(entry.scope, entry.name),
 				plugin: entry.name,
 				surfaceId,
 				code: "session_collision",

package/src/extensibility/gjc-plugins/types.ts

@@ -291,3 +291,144 @@ export interface GjcPluginRegistry {
  * disabledSurfaceIds, and quarantine bookkeeping.
  */
 export type GjcPluginSurfaceExtensionId = string;
+
+/** Canonical GJC bundle identity: kind is fixed, target is (scope, name). */
+export const GJC_BUNDLE_KIND = "gjc-bundle";
+
+export interface GjcBundleIdentity {
+	kind: typeof GJC_BUNDLE_KIND;
+	scope: GjcPluginScope;
+	name: string;
+}
+
+/** Source descriptor exposed to CLI/Settings: never carries raw locator secrets. */
+export interface GjcBundleSafeSource {
+	kind: GjcPluginSourceKind;
+	/** Redacted display locator (host + path only; no userinfo/query/fragment). */
+	display: string;
+	/** Conservative safe git ref, omitted when the stored value is unsafe. */
+	ref?: string;
+	/** Hex-only revision identifier, omitted when the stored value is unsafe. */
+	sha?: string;
+	resolvedAt: string;
+	/** True when this source kind supports re-resolution during update. */
+	updatable: boolean;
+	/** Present only when updatable is false. */
+	unsupportedReason?: string;
+}
+
+export interface GjcBundleSurfaceSummary {
+	extensionId: string;
+	kind: "tool" | "hook" | "mcp" | "system-appendix" | "agent-appendix" | "subskill";
+	name: string;
+	/** Persisted user intent (registry disabledSurfaceIds). */
+	enabled: boolean;
+	/** Deterministic quarantine derived from persisted registry state only. */
+	quarantined: boolean;
+	quarantineCode?: GjcPluginLoadErrorCode;
+}
+
+/** Installed-bundle DTO shared by CLI and Settings. Contains no raw locators. */
+export interface GjcBundleSummary {
+	identity: GjcBundleIdentity;
+	version: string;
+	description?: string;
+	enabled: boolean;
+	source: GjcBundleSafeSource;
+	installedAt: string;
+	updatedAt: string;
+	manifestHash: string;
+	/** Deterministic fingerprint of the exact installed target. */
+	targetFingerprint: string;
+	surfaces: GjcBundleSurfaceSummary[];
+	/** True when any deterministic quarantine blocks enablement. */
+	quarantined: boolean;
+}
+
+/**
+ * Host-derived token binding an update preview to the exact candidate, the
+ * exact installed baseline, and the deterministic decision context. Apply is a
+ * compare-and-swap against all three fingerprints.
+ */
+export interface GjcReviewedUpdateToken {
+	identity: GjcBundleIdentity;
+	candidateFingerprint: string;
+	baselineFingerprint: string;
+	decisionContextFingerprint: string;
+	reviewedAt: string;
+}
+
+export type GjcLifecycleErrorCode =
+	| "already_installed_use_upgrade"
+	| "not_installed"
+	| "identity_mismatch"
+	| "stale_candidate"
+	| "stale_baseline"
+	| "stale_decision_context"
+	| "source_unsupported"
+	| "source_unavailable"
+	| "quarantined"
+	| "surface_unknown"
+	| "invalid_target";
+
+export interface GjcLifecycleError {
+	code: GjcLifecycleErrorCode;
+	/** Sanitized operator-facing message; never contains raw locators or causes. */
+	message: string;
+	/** Safe scoped recovery hint (e.g. the exact command to run instead). */
+	recovery?: string;
+}
+
+export type GjcLifecycleResult<T> = { ok: true; value: T } | { ok: false; error: GjcLifecycleError };
+
+export interface GjcUpdatePreview {
+	identity: GjcBundleIdentity;
+	current: GjcBundleSummary;
+	candidateVersion: string;
+	candidateManifestHash: string;
+	/** Surface IDs added, removed, or retained by this candidate. */
+	addedSurfaceIds: string[];
+	removedSurfaceIds: string[];
+	retainedSurfaceIds: string[];
+	changed: boolean;
+	token: GjcReviewedUpdateToken;
+}
+
+export type GjcUpdateApplyStatus = "updated" | "unchanged";
+
+export interface GjcUpdateApplyResult {
+	status: GjcUpdateApplyStatus;
+	summary: GjcBundleSummary;
+	/** Number of filesystem remnants that could not be removed after a successful swap. */
+	remnantCount: number;
+}
+
+export interface GjcInstallResult {
+	status: "installed";
+	summary: GjcBundleSummary;
+}
+
+export interface GjcToggleResult {
+	summary: GjcBundleSummary;
+	/** False when the requested state already matched (no persisted mutation). */
+	mutated: boolean;
+}
+
+/**
+ * Scope-qualified runtime evidence emitted by producers. Producers never
+ * publish; the session coordinator accumulates one complete generation.
+ */
+export interface GjcRuntimeFinding {
+	identity: GjcBundleIdentity;
+	surfaceId: string;
+	code: GjcPluginLoadErrorCode;
+	message: string;
+}
+
+export interface GjcRuntimeSnapshot {
+	/** Monotonic activation generation this snapshot describes. */
+	generation: number;
+	findings: GjcRuntimeFinding[];
+}
+
+export type GjcRuntimeSnapshotState = { status: "unavailable" } | { status: "current"; snapshot: GjcRuntimeSnapshot };

package/src/extensibility/gjc-plugins/validation.ts

@@ -88,6 +88,15 @@ export function validateInstallPlan(
 	bundle: NormalizedGjcPluginBundle,
 	effectiveEntries: readonly GjcPluginRegistryEntry[],
 ): void {
+	// Collision universe: the caller passes the effective registry across BOTH
+	// scopes, because surface IDs derive from the SURFACE name
+	// (`tool:<toolName>`, `mcp:<mcpName>`), not the bundle name. A differently
+	// named bundle in the opposite scope can therefore claim the same ID.
+	//
+	// Entries sharing this bundle's name are excluded in every scope: they are
+	// the same logical bundle being installed or replaced, and installing one
+	// bundle into both scopes is supported, so its own surfaces must not count
+	// as collisions against itself.
 	const others = effectiveEntries.filter(e => e.name !== bundle.name);
 
 	const toolNames = new Set<string>();

package/src/extensibility/shared-events.ts

@@ -38,6 +38,9 @@ export interface SessionBeforeSwitchEvent {
 	targetSessionFile?: string;
 }
 
+/** Origin used when an interactive session selector resumes a session. */
+export const INTERACTIVE_SELECTOR_RESUME_ORIGIN = "interactive_selector_resume";
+
 /** Fired after switching to another session */
 export interface SessionSwitchEvent {
 	type: "session_switch";
@@ -45,6 +48,8 @@ export interface SessionSwitchEvent {
 	reason: "new" | "resume" | "fork";
 	/** Session file we came from */
 	previousSessionFile: string | undefined;
+	/** Optional provenance for this session transition. */
+	transition?: { origin: string };
 }
 
 /** Fired before branching a session (can be cancelled) */