@gajae-code/coding-agent 0.8.1 → 0.8.2

package/dist/types/notifications/config.d.ts

@@ -23,6 +23,12 @@ export declare function isGloballyConfigured(cfg: NotificationConfig): boolean;
 export declare function shouldRegisterNotificationsExtension(input: {
     env: NodeJS.ProcessEnv;
     cfg?: NotificationConfig;
+    /** Task recursion depth; helper/subagent sessions must not spawn remote surfaces. */
+    taskDepth?: number;
+    /** Parent subagent id/prefix; present for helper/subagent sessions even when depth is omitted. */
+    parentTaskPrefix?: string;
+    /** Role-agent type/name; present for task sessions even if depth metadata is lost. */
+    currentAgentType?: string;
 }): boolean;
 /**
  * Resolve whether THIS session should run notifications.
@@ -61,7 +67,8 @@ export interface RedactableAction {
  * When redact is false, return the action unchanged.
  *
  * Redaction still applies to streamed content frames (turn_stream, context_update,
- * image_attachment) which are suppressed at their emit sites, not here.
+ * image_attachment) which are suppressed at their emit sites, not here. Explicit
+ * `telegram_send` file attachments are rejected before the file is read or forwarded.
  */
 export declare function buildRedactedAction(action: RedactableAction, opts: {
     redact: boolean;

package/dist/types/notifications/daemon-paths.d.ts

@@ -5,5 +5,6 @@ export interface DaemonPaths {
     roots: string;
     steal: string;
     aliases: string;
+    seenUpdates: string;
 }
 export declare function daemonPaths(agentDir: string): DaemonPaths;

package/dist/types/notifications/index.d.ts

@@ -17,7 +17,8 @@
  * Enable with Settings notifications config, `GJC_NOTIFICATIONS=1` (a token is
  * generated), or `GJC_NOTIFICATIONS_TOKEN`.
  */
-import type { ExtensionFactory } from "../extensibility/extensions";
+import { Settings } from "../config/settings";
+import type { ExtensionAPI } from "../extensibility/extensions";
 /** Where a `session_create` should run. Discriminated by `kind`. */
 export type SessionCreateTarget = {
     kind: "existing_path";
@@ -69,7 +70,7 @@ export interface SessionCloseFrame {
     chatId: string;
     token: string;
     target: SessionCloseTarget;
-    /** Hard-kill even if a live pane is attached (GJC-managed only). */
+    /** Required force-only close flag; false/omitted is rejected by daemon policy. */
     force?: boolean;
 }
 /** Resume a session (reattach if alive, else cold-restart from history). */
@@ -173,4 +174,6 @@ export interface SessionReadyFrame {
  */
 export declare function readGitRepoName(cwd: string): string | undefined;
 export declare function notificationsEnabled(): boolean;
-export declare const createNotificationsExtension: ExtensionFactory;
+export declare function createNotificationsExtension(api: ExtensionAPI, options?: {
+    settings?: Settings;
+}): void;

package/dist/types/notifications/lifecycle-commands.d.ts

@@ -23,8 +23,13 @@ export type ParsedLifecycleCommand = {
 } | {
     kind: "none";
 };
-/** True when the text begins a /session_* command (cheap pre-gate). */
-export declare function isLifecycleCommandText(text: string | undefined): boolean;
+/** True when the text begins with any /session_* token, regardless of addressability. */
+export declare function isLifecycleCommandLikeText(text: string | undefined): boolean;
+/** True when the text begins an addressable /session_* command (cheap pre-gate). */
+export declare function isLifecycleCommandText(text: string | undefined, ctx?: {
+    chatType?: string;
+    botUsername?: string;
+}): boolean;
 /**
  * Parse a paired-chat message into a lifecycle command. Returns `none` for
  * non-lifecycle text, `usage`/`reject` for malformed input (no side effect), or
@@ -33,7 +38,10 @@ export declare function isLifecycleCommandText(text: string | undefined): boolea
  * The caller MUST have already enforced paired-chat authorization; this function
  * performs grammar + target validation only.
  */
-export declare function parseLifecycleCommand(text: string | undefined): ParsedLifecycleCommand;
+export declare function parseLifecycleCommand(text: string | undefined, ctx?: {
+    chatType?: string;
+    botUsername?: string;
+}): ParsedLifecycleCommand;
 /** The canonical usage text (exported for the daemon's help replies). */
 export declare function lifecycleUsage(): string;
 /**

package/dist/types/notifications/telegram-daemon.d.ts

@@ -3,8 +3,8 @@ import type { Settings } from "../config/settings";
 import type { DaemonRuntimeInfo } from "../daemon/control-types";
 import { type ControlServerLike, type LifecycleControlServerFactory } from "./lifecycle-control-runtime";
 import { NotificationOperatorRuntime, OperatorBackoffPolicy } from "./operator-runtime";
-import { type AliasTable, type CallbackRoute, type PendingAsk } from "./telegram-reference";
-export type EnsureDaemonResult = "owner_spawned" | "attached" | "disabled";
+import { type AliasTable, type CallbackRoute } from "./telegram-reference";
+export type EnsureDaemonResult = "owner_spawned" | "attached" | "disabled" | "blocked";
 export interface DaemonState {
     pid: number;
     ownerId: string;
@@ -95,6 +95,8 @@ export declare function acquireDaemonOwnership(input: {
     acquired: boolean;
     ownerId?: string;
     attached?: boolean;
+    blocked?: boolean;
+    reason?: "identity_mismatch";
 }>;
 export declare function renewDaemonHeartbeat(input: {
     settings: Settings;
@@ -276,6 +278,8 @@ export declare class TelegramNotificationDaemon {
     private readonly flatIdentitySent;
     /** Cached result of whether the paired chat is a private chat (flat-fallback gate). */
     private pairedChatPrivate;
+    /** Bot username from getMe, cached once at owner startup for group/forum command targeting. */
+    private botUsername;
     /** Sessions whose agent loop is currently busy (drives the typing indicator). */
     private get busy();
     /** Inbound update id → originating Telegram message, for delivery reactions. */
@@ -317,12 +321,17 @@ export declare class TelegramNotificationDaemon {
     /** Build an authenticated lifecycle frame from a parsed command + identity. */
     private buildLifecycleFrame;
     private handleLifecycleCommand;
+    private refreshBotIdentity;
     /** Map a lifecycle response/error to a user-facing message (G010 surfacing). */
     private formatLifecycleResponse;
     constructor(opts: TelegramDaemonOptions);
     private createSessionRouter;
     loadAliases(): Promise<void>;
     persistAliases(): Promise<void>;
+    loadSeenUpdateIds(): Promise<void>;
+    persistSeenUpdateIds(): Promise<void>;
+    private pruneSeenUpdateIds;
+    private rememberSeenUpdateId;
     scanRoots(): Promise<void>;
     connectSession(sessionId: string, url: string, token: string): void;
     /**
@@ -340,12 +349,15 @@ export declare class TelegramNotificationDaemon {
      * the socket. `scanRoots()` then reconnects the session.
      */
     private dropSession;
+    private deleteMessageRoutes;
     private static readonly THREADED_FRAMES;
     private topicNameFor;
     private topicIdentityKey;
     private topicIdentityBase;
     private topicOwnerForIdentity;
+    private sessionCanClaimIdentity;
     private submitThreadedFrame;
+    private existingTopicForPrivateChat;
     private rememberPendingThreadedFrame;
     private flushPendingThreadedFrames;
     private ensureTopic;
@@ -376,7 +388,7 @@ export declare class TelegramNotificationDaemon {
     private startTypingTimer;
     private stopTypingTimer;
     handleSessionMessage(session: SessionSocket, msg: any): Promise<void>;
-    pendingBySession: (sessionId?: string) => PendingAsk[];
+    private answerCallbackQueryBestEffort;
     private sendStaleGuidance;
     handleTelegramUpdate(update: unknown): Promise<void>;
     pollOnce(signal?: AbortSignal): Promise<number>;

package/dist/types/notifications/telegram-reference.d.ts

@@ -81,14 +81,9 @@ export type RouteDecision = ({
 } | {
     kind: "ignore";
 };
-export interface PendingAsk {
-    sessionId: string;
-    actionId: string;
-}
 export interface RouteInboundContext {
     aliasTable: Pick<AliasTable, "get">;
     messageRoutes: Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>;
-    pendingBySession: (sessionId?: string) => PendingAsk[];
     pairedChatId: string;
 }
 /** Route a Telegram update to a session/action without I/O. Fail closed under ambiguity. */

package/dist/types/runtime-api-key.d.ts

@@ -0,0 +1,7 @@
+export interface RuntimeApiKeyTarget {
+    setRuntimeApiKey(provider: string, apiKey: string): void;
+}
+export interface RuntimeApiKeyModel {
+    provider: string;
+}
+export declare function applyCliRuntimeApiKeyOverride(target: RuntimeApiKeyTarget, apiKey: string | undefined, model: RuntimeApiKeyModel | undefined): void;

package/dist/types/session/agent-session.d.ts

@@ -317,6 +317,13 @@ export interface SessionStats {
     premiumRequests: number;
     cost: number;
 }
+export type QueuedMessageEditMode = "steer" | "followUp";
+export interface QueuedMessageEditEntry {
+    id: string;
+    text: string;
+    mode: QueuedMessageEditMode;
+    label: string;
+}
 /** A custom message contributed at the before-agent-start point. */
 export type BeforeAgentStartInternalMessage = Pick<CustomMessage, "customType" | "content" | "display" | "details" | "attribution">;
 /**
@@ -670,6 +677,9 @@ export declare class AgentSession {
         steering: readonly string[];
         followUp: readonly string[];
     };
+    getQueuedMessageEntries(): QueuedMessageEditEntry[];
+    removeQueuedMessageForEditing(id: string): string | undefined;
+    moveQueuedMessageForEditing(id: string, direction: "up" | "down"): boolean;
     /**
      * Pop the newest queued message across steering and follow-up queues.
      * Used by dequeue keybinding to restore messages to editor one at a time.

package/dist/types/session/agent-storage.d.ts

@@ -93,6 +93,7 @@ export declare class AgentStorage {
      * Sets a cached value with expiry time (unix seconds).
      */
     setCache(key: string, value: string, expiresAtSec: number): void;
+    deleteCachePrefix(prefix: string): void;
     /**
      * Deletes expired cache entries. Call periodically for cleanup.
      */

package/dist/types/task/executor.d.ts

@@ -51,6 +51,8 @@ export interface ExecutorOptions {
     artifactsDir?: string;
     /** Path to parent conversation context file */
     contextFile?: string;
+    /** Whether the parent runtime actually exposes IRC coordination. */
+    ircAvailable?: boolean;
     eventBus?: EventBus;
     contextFiles?: ContextFileEntry[];
     skills?: Skill[];

package/dist/types/tools/computer.d.ts

@@ -238,7 +238,7 @@ export interface ComputerScreenshotDetails {
     scaleY?: number;
     originX?: number;
     originY?: number;
-    displayEpoch?: string;
+    displayEpoch?: number;
     captureId?: string;
     pngBytes?: number;
     path?: string;
@@ -281,7 +281,7 @@ type NativeScreenshot = {
     scaleY?: number;
     originX?: number;
     originY?: number;
-    displayEpoch?: string;
+    displayEpoch?: number;
     captureId?: string;
 };
 export type ComputerControllerFactory = () => NativeController;

package/dist/types/workflow/workflow-intent-diff.d.ts

@@ -1,5 +1,9 @@
+import { type WorkflowClaimsLedger, type WorkflowConsensusReport } from "./workflow-intent-report";
 export declare const WORKFLOW_INTENT_DIFF_CUSTOM_TYPE = "workflow-intent-diff";
-export type WorkflowIntentRoute = "direct" | "deep-interview" | "ralplan" | "ultragoal" | "team";
+export declare const WORKFLOW_INTENT_ROUTES: readonly ["direct", "deep-interview", "ralplan", "ultragoal", "team"];
+export declare const WORKFLOW_ESCALATION_ROUTES: readonly ["deep-interview", "ralplan", "ultragoal", "team"];
+export type WorkflowIntentRoute = (typeof WORKFLOW_INTENT_ROUTES)[number];
+export type WorkflowEscalationRoute = (typeof WORKFLOW_ESCALATION_ROUTES)[number];
 export type DirectTrackingMode = "custom-entry-only" | "not-direct";
 export type RootCausePhaseStatus = "active" | "inactive";
 export interface WorkflowIntentDiff {
@@ -7,13 +11,15 @@ export interface WorkflowIntentDiff {
     readonly route: WorkflowIntentRoute;
     readonly reason: string;
     readonly directTracking: DirectTrackingMode;
-    readonly recommendedSkill?: Exclude<WorkflowIntentRoute, "direct">;
+    readonly recommendedSkill?: WorkflowEscalationRoute;
     readonly recommendedInvocation?: string;
     readonly triggers: readonly string[];
     readonly rootCausePhase: {
         readonly status: RootCausePhaseStatus;
         readonly triggers: readonly string[];
     };
+    readonly claimsLedger: WorkflowClaimsLedger;
+    readonly consensusReport: WorkflowConsensusReport;
     readonly promptPreview: string;
 }
 export declare function buildWorkflowIntentDiff(text: string): WorkflowIntentDiff | null;

package/dist/types/workflow/workflow-intent-report-consumer.d.ts

@@ -0,0 +1,50 @@
+import type { SessionEntry } from "../session/session-manager";
+import { type WorkflowIntentDiff, type WorkflowIntentRoute } from "./workflow-intent-diff";
+import type { WorkflowSignalObserver } from "./workflow-intent-report";
+export type WorkflowConsumerConfidence = "none" | "low" | "medium" | "high";
+export interface WorkflowRouteCounts {
+    readonly direct: number;
+    readonly "deep-interview": number;
+    readonly ralplan: number;
+    readonly ultragoal: number;
+    readonly team: number;
+}
+export interface WorkflowIntentReportEntry {
+    readonly entryId: string;
+    readonly timestamp: string;
+    readonly intent: WorkflowIntentDiff;
+}
+export interface WorkflowIntentReportTotals {
+    readonly total: number;
+    readonly byRoute: WorkflowRouteCounts;
+    readonly escalationRequired: number;
+    readonly rootCauseActive: number;
+}
+export interface WorkflowIntentReportCollection {
+    readonly entries: readonly WorkflowIntentReportEntry[];
+    readonly latest: WorkflowIntentReportEntry | undefined;
+    readonly totals: WorkflowIntentReportTotals;
+}
+export interface WorkflowObserverSignalSummary {
+    readonly observer: WorkflowSignalObserver;
+    readonly conclusion: string;
+    readonly count: number;
+}
+export interface WorkflowConsensusSummary {
+    readonly total: number;
+    readonly dominantRoute: WorkflowIntentRoute | undefined;
+    readonly confidence: WorkflowConsumerConfidence;
+    readonly escalationGate: {
+        readonly required: boolean;
+        readonly count: number;
+        readonly latestReason: string | undefined;
+    };
+    readonly rootCausePhase: {
+        readonly active: boolean;
+        readonly count: number;
+        readonly triggers: readonly string[];
+    };
+    readonly observerSignals: readonly WorkflowObserverSignalSummary[];
+}
+export declare function collectWorkflowIntentReports(entries: readonly SessionEntry[]): WorkflowIntentReportCollection;
+export declare function summarizeWorkflowConsensus(intents: readonly WorkflowIntentDiff[]): WorkflowConsensusSummary;

package/dist/types/workflow/workflow-intent-report-schema.d.ts

@@ -0,0 +1,2 @@
+import { type WorkflowIntentDiff } from "./workflow-intent-diff";
+export declare function parseWorkflowIntentDiffPayload(value: unknown): WorkflowIntentDiff | undefined;

package/dist/types/workflow/workflow-intent-report.d.ts

@@ -0,0 +1,48 @@
+import type { RootCausePhaseStatus, WorkflowIntentRoute } from "./workflow-intent-diff";
+export type WorkflowConfidence = "high";
+export type WorkflowClaimStatus = "confirmed";
+export type WorkflowEscalationGateStatus = "required" | "not-required";
+export type WorkflowSignalObserver = "intent-router" | "root-cause-schema" | "escalation-gate";
+export interface WorkflowClaim {
+    readonly id: "workflow-route" | "root-cause-phase" | "escalation-gate";
+    readonly statement: string;
+    readonly status: WorkflowClaimStatus;
+    readonly confidence: WorkflowConfidence;
+    readonly evidence: readonly string[];
+}
+export interface WorkflowClaimsLedger {
+    readonly version: 1;
+    readonly claims: readonly WorkflowClaim[];
+}
+export interface WorkflowObserverSignal {
+    readonly observer: WorkflowSignalObserver;
+    readonly conclusion: string;
+    readonly evidence: readonly string[];
+}
+export interface WorkflowConsensusReport {
+    readonly version: 1;
+    readonly route: WorkflowIntentRoute;
+    readonly confidence: WorkflowConfidence;
+    readonly summary: string;
+    readonly observerSignals: readonly WorkflowObserverSignal[];
+    readonly escalationGate: {
+        readonly status: WorkflowEscalationGateStatus;
+        readonly reason: string;
+    };
+}
+export interface WorkflowIntentReport {
+    readonly claimsLedger: WorkflowClaimsLedger;
+    readonly consensusReport: WorkflowConsensusReport;
+}
+export interface WorkflowIntentReportInput {
+    readonly route: WorkflowIntentRoute;
+    readonly reason: string;
+    readonly direct: boolean;
+    readonly recommendedInvocation?: string;
+    readonly triggers: readonly string[];
+    readonly rootCausePhase: {
+        readonly status: RootCausePhaseStatus;
+        readonly triggers: readonly string[];
+    };
+}
+export declare function buildWorkflowIntentReport(input: WorkflowIntentReportInput): WorkflowIntentReport;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.8.1",
+	"version": "0.8.2",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo",
@@ -52,12 +52,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.8.1",
-		"@gajae-code/agent-core": "0.8.1",
-		"@gajae-code/ai": "0.8.1",
-		"@gajae-code/natives": "0.8.1",
-		"@gajae-code/tui": "0.8.1",
-		"@gajae-code/utils": "0.8.1",
+		"@gajae-code/stats": "0.8.2",
+		"@gajae-code/agent-core": "0.8.2",
+		"@gajae-code/ai": "0.8.2",
+		"@gajae-code/natives": "0.8.2",
+		"@gajae-code/tui": "0.8.2",
+		"@gajae-code/utils": "0.8.2",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/cli/completion-cli.ts

@@ -0,0 +1,234 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ArgDescriptor, CommandCtor, CommandEntry, FlagDescriptor } from "@gajae-code/utils/cli";
+
+export type FigName = string | string[];
+
+export interface FigArg {
+	name: string;
+	description?: string;
+	isOptional?: boolean;
+	isVariadic?: boolean;
+	suggestions?: string[];
+}
+
+export interface FigOption {
+	name: FigName;
+	description?: string;
+	args?: FigArg;
+	isRepeatable?: boolean;
+}
+
+export interface FigSubcommand {
+	name: FigName;
+	description?: string;
+	options?: FigOption[];
+	args?: FigArg | FigArg[];
+}
+
+export interface FigSpec extends FigSubcommand {
+	name: string;
+	subcommands?: FigSubcommand[];
+}
+
+export type InshellisenseIndexStatus = "created" | "updated" | "already-compatible" | "overwritten";
+
+export interface InstallGjcInshellisenseSpecOptions {
+	dir?: string;
+	force?: boolean;
+}
+
+export interface InstallGjcInshellisenseSpecResult {
+	directory: string;
+	specPath: string;
+	indexPath: string;
+	indexStatus: InshellisenseIndexStatus;
+}
+
+const GENERATED_INDEX_MARKER = "// Generated by gjc completion inshellisense";
+const BUILTIN_ROOT_OPTIONS: FigOption[] = [
+	{ name: ["-h", "--help"], description: "Show help" },
+	{ name: ["-v", "--version"], description: "Show version" },
+];
+const BUILTIN_COMMAND_OPTIONS: FigOption[] = [{ name: ["-h", "--help"], description: "Show help" }];
+
+export function defaultInshellisenseSpecDir(homeDir: string = os.homedir()): string {
+	return path.join(homeDir, ".fig", "autocomplete", "build");
+}
+
+function nameList(name: FigName): string[] {
+	return Array.isArray(name) ? name : [name];
+}
+
+function optionKey(option: FigOption): string {
+	return nameList(option.name).join("\u0000");
+}
+
+function combineOptions(primary: FigOption[], secondary: FigOption[]): FigOption[] {
+	const seen = new Set<string>();
+	const combined: FigOption[] = [];
+	for (const option of [...primary, ...secondary]) {
+		const key = optionKey(option);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		combined.push(option);
+	}
+	return combined;
+}
+
+function commandEntryName(entry: CommandEntry): FigName {
+	const names = [entry.name, ...(entry.aliases ?? [])];
+	return names.length === 1 ? names[0]! : names;
+}
+
+function flagName(name: string, descriptor: FlagDescriptor): FigName {
+	const longName = `--${name}`;
+	if (!descriptor.char) return longName;
+	return [`-${descriptor.char}`, longName];
+}
+
+function argSuggestions(options: readonly string[] | undefined): string[] | undefined {
+	return options && options.length > 0 ? [...options] : undefined;
+}
+
+function optionArgName(name: string, descriptor: FlagDescriptor): string {
+	if (descriptor.options && descriptor.options.length > 0) return name;
+	return descriptor.kind === "integer" ? "int" : "value";
+}
+
+function figOptionFromFlag(name: string, descriptor: FlagDescriptor): FigOption {
+	const option: FigOption = {
+		name: flagName(name, descriptor),
+	};
+	if (descriptor.description) option.description = descriptor.description;
+	if (descriptor.multiple) option.isRepeatable = true;
+	if (descriptor.kind !== "boolean") {
+		const arg: FigArg = { name: optionArgName(name, descriptor) };
+		const suggestions = argSuggestions(descriptor.options);
+		if (suggestions) arg.suggestions = suggestions;
+		option.args = arg;
+	}
+	return option;
+}
+
+function figOptionsFromFlags(flags: Record<string, FlagDescriptor> | undefined): FigOption[] {
+	if (!flags) return [];
+	return Object.entries(flags).map(([name, descriptor]) => figOptionFromFlag(name, descriptor));
+}
+
+function figArgFromDescriptor(name: string, descriptor: ArgDescriptor): FigArg {
+	const arg: FigArg = { name };
+	if (descriptor.description) arg.description = descriptor.description;
+	if (!descriptor.required) arg.isOptional = true;
+	if (descriptor.multiple) arg.isVariadic = true;
+	const suggestions = argSuggestions(descriptor.options);
+	if (suggestions) arg.suggestions = suggestions;
+	return arg;
+}
+
+function figArgsFromDescriptors(args: Record<string, ArgDescriptor> | undefined): FigArg | FigArg[] | undefined {
+	if (!args) return undefined;
+	const values = Object.entries(args).map(([name, descriptor]) => figArgFromDescriptor(name, descriptor));
+	if (values.length === 0) return undefined;
+	return values.length === 1 ? values[0] : values;
+}
+
+function commandToSubcommand(entry: CommandEntry, command: CommandCtor): FigSubcommand {
+	const subcommand: FigSubcommand = { name: commandEntryName(entry) };
+	if (command.description) subcommand.description = command.description;
+	const options = combineOptions(BUILTIN_COMMAND_OPTIONS, figOptionsFromFlags(command.flags));
+	if (options.length > 0) subcommand.options = options;
+	const args = figArgsFromDescriptors(command.args);
+	if (args) subcommand.args = args;
+	return subcommand;
+}
+
+export async function buildGjcFigSpec(entries: CommandEntry[], rootCommandOverride?: CommandCtor): Promise<FigSpec> {
+	const subcommands: FigSubcommand[] = [];
+	let rootCommand: CommandCtor | undefined = rootCommandOverride;
+
+	for (const entry of entries) {
+		if (entry.name === "launch" && rootCommandOverride) {
+			continue;
+		}
+		let command: CommandCtor;
+		try {
+			command = await entry.load();
+		} catch {
+			if (entry.name !== "launch") {
+				subcommands.push({ name: commandEntryName(entry) });
+			}
+			continue;
+		}
+		if (entry.name === "launch") {
+			rootCommand = command;
+			continue;
+		}
+		if (command.hidden) continue;
+		subcommands.push(commandToSubcommand(entry, command));
+	}
+
+	const spec: FigSpec = {
+		name: "gjc",
+		description: rootCommand?.description ?? "Gajae Code CLI",
+	};
+	const rootOptions = combineOptions(BUILTIN_ROOT_OPTIONS, figOptionsFromFlags(rootCommand?.flags));
+	if (rootOptions.length > 0) spec.options = rootOptions;
+	const rootArgs = figArgsFromDescriptors(rootCommand?.args);
+	if (rootArgs) spec.args = rootArgs;
+	if (subcommands.length > 0) spec.subcommands = subcommands;
+	return spec;
+}
+
+export function renderFigSpecModule(spec: FigSpec): string {
+	return `const completionSpec = ${JSON.stringify(spec, null, "\t")};\n\nexport default completionSpec;\n`;
+}
+
+export function renderInshellisenseIndexModule(): string {
+	return `${GENERATED_INDEX_MARKER}\n\nexport default ["gjc"];\nexport const diffVersionedCompletions = [];\n`;
+}
+
+async function fileTextIfExists(filePath: string): Promise<string | undefined> {
+	try {
+		return await Bun.file(filePath).text();
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+function indexDeclaresGjc(content: string): boolean {
+	return /["']gjc["']/.test(content);
+}
+
+async function resolveIndexStatus(indexPath: string, force: boolean | undefined): Promise<InshellisenseIndexStatus> {
+	const existing = await fileTextIfExists(indexPath);
+	if (existing === undefined) return "created";
+	if (existing.includes(GENERATED_INDEX_MARKER)) {
+		return existing === renderInshellisenseIndexModule() ? "already-compatible" : "updated";
+	}
+	if (indexDeclaresGjc(existing)) return "already-compatible";
+	if (force) return "overwritten";
+	throw new Error(
+		`inshellisense index already exists at ${indexPath} and does not list gjc; rerun with --force to overwrite it or pass --dir to install into a GJC-only specs directory`,
+	);
+}
+
+export async function installGjcInshellisenseSpec(
+	spec: FigSpec,
+	options: InstallGjcInshellisenseSpecOptions = {},
+): Promise<InstallGjcInshellisenseSpecResult> {
+	const directory = path.resolve(options.dir ?? defaultInshellisenseSpecDir());
+	const specPath = path.join(directory, "gjc.js");
+	const indexPath = path.join(directory, "index.js");
+	const indexStatus = await resolveIndexStatus(indexPath, options.force);
+
+	await fs.mkdir(directory, { recursive: true });
+	await Bun.write(specPath, renderFigSpecModule(spec));
+	if (indexStatus !== "already-compatible") {
+		await Bun.write(indexPath, renderInshellisenseIndexModule());
+	}
+
+	return { directory, specPath, indexPath, indexStatus };
+}