@gajae-code/coding-agent 0.6.5 → 0.7.1

package/src/rlm/index.ts

@@ -240,8 +240,27 @@ async function writeRlmMetadata(input: {
 	}
 }
 
+/**
+ * RLM artifacts are scoped under a GJC session directory and resolving their
+ * paths is a *write* (it must pick a concrete session). When `gjc rlm` runs
+ * standalone — no parent agent, no `GJC_SESSION_ID` in the environment — there is
+ * no session to resolve and `resolveGjcSessionForWrite` throws
+ * `missing_for_write`. Establish a dedicated GJC session id in that case and pin
+ * it into the environment so artifact-path resolution, the per-session activity
+ * marker, and the child agent's workflow state all share one writable session.
+ *
+ * Returns the resolved (existing or freshly generated) GJC session id.
+ */
+export function ensureRlmGjcSessionId(): string {
+	const existing = resolveSessionIdFromSources({ envSessionId: process.env.GJC_SESSION_ID })?.gjcSessionId;
+	if (existing) return existing;
+	const generated = `rlm-${generateRlmSessionId()}`;
+	process.env.GJC_SESSION_ID = generated;
+	return generated;
+}
 export async function runRlmCommand(argv: string[]): Promise<void> {
 	const cwd = getProjectDir();
+	ensureRlmGjcSessionId();
 	const { dataPath, resumeSessionId, minSuccessfulRuns, rest } = extractRlmFlags(argv);
 	const dataContext = await loadRlmDataContext(cwd, dataPath);
 

package/src/sdk.ts

@@ -79,6 +79,12 @@ import type { HindsightSessionState } from "./hindsight/state";
 import { LocalProtocolHandler, type LocalProtocolOptions } from "./internal-urls";
 import { LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "./lsp/startup-events";
 import { resolveMemoryBackend } from "./memory-backend";
+import { createNotificationsExtension } from "./notifications";
+import {
+	getNotificationConfig,
+	type NotificationConfig,
+	shouldRegisterNotificationsExtension,
+} from "./notifications/config";
 import asyncResultTemplate from "./prompts/tools/async-result.md" with { type: "text" };
 import { AgentRegistry, MAIN_AGENT_ID } from "./registry/agent-registry";
 import { MCPManager } from "./runtime-mcp";
@@ -1238,6 +1244,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			getPlanModeState: () => session?.getPlanModeState(),
 			getGoalModeState: () => session?.getGoalModeState(),
 			getWorkflowGateEmitter: () => session?.getWorkflowGateEmitter(),
+			getAskAnswerSource: () => session?.getAskAnswerSource(),
 			getGoalRuntime: () => session?.goalRuntime,
 			getClientBridge: () => session?.clientBridge,
 			getCompactContext: () => session.formatCompactContext(),
@@ -1386,6 +1393,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		if (customTools.length > 0) {
 			inlineExtensions.push(createCustomToolsExtension(customTools));
 		}
+		let notificationCfg: NotificationConfig | undefined;
+		try {
+			notificationCfg = getNotificationConfig(Settings.instance);
+		} catch {
+			notificationCfg = undefined;
+		}
+		if (shouldRegisterNotificationsExtension({ env: process.env, cfg: notificationCfg })) {
+			inlineExtensions.push(createNotificationsExtension);
+		}
 
 		// Extension/module discovery is quarantined; retain only the private
 		// runtime needed for bundled product extensions, explicitly supplied SDK

package/src/session/agent-session.ts

@@ -238,8 +238,9 @@ import {
 	type DiscoverableTool,
 	type DiscoverableToolSearchIndex,
 } from "../tool-discovery/tool-index";
-import type { ToolSession } from "../tools";
+import type { AskAnswerSource, ToolSession } from "../tools";
 import { AskTool } from "../tools/ask";
+import { getAskAnswerSource as getAskAnswerSourceFromRegistry } from "../tools/ask-answer-registry";
 import { assertEditableFile } from "../tools/auto-generated-guard";
 import { releaseTabsForOwner } from "../tools/browser/tab-supervisor";
 import type { CheckpointState } from "../tools/checkpoint";
@@ -313,6 +314,7 @@ export type AgentSessionEvent =
 	| { type: "todo_reminder"; todos: TodoItem[]; attempt: number; maxAttempts: number }
 	| { type: "todo_auto_clear" }
 	| { type: "irc_message"; message: CustomMessage }
+	| { type: "subagent_steer_message"; message: CustomMessage }
 	| { type: "notice"; level: "info" | "warning" | "error"; message: string; source?: string }
 	| { type: "thinking_level_changed"; thinkingLevel: ThinkingLevel | undefined }
 	| { type: "goal_updated"; goal: Goal | null; state?: GoalModeState };
@@ -4385,6 +4387,10 @@ export class AgentSession {
 		return this.#workflowGateEmitter;
 	}
 
+	getAskAnswerSource(): AskAnswerSource | undefined {
+		return getAskAnswerSourceFromRegistry(this.sessionId);
+	}
+
 	setWorkflowGateEmitter(emitter: WorkflowGateEmitter | undefined): void {
 		this.#workflowGateEmitter = emitter;
 		if (emitter) {
@@ -5453,6 +5459,16 @@ export class AgentSession {
 			return;
 		}
 
+		// No explicit delivery mode: only a live stream makes prompt() throw
+		// AgentBusyError, so queue the message as steering while streaming.
+		// Compaction is intentionally NOT diverted here: prompt() handles an
+		// in-flight compaction internally, and #queueSteer would otherwise park
+		// the message in the steering queue with no turn to consume it.
+		if (this.isStreaming) {
+			await this.#queueSteer(text, images);
+			return;
+		}
+
 		// Use prompt() with expandPromptTemplates: false to skip command handling and template expansion
 		await this.prompt(text, {
 			expandPromptTemplates: false,
@@ -5856,12 +5872,46 @@ export class AgentSession {
 		return this.#activeModelProfile;
 	}
 
+	/**
+	 * The model selector ("provider/id") that resume restores as the session
+	 * default — the latest session-log `model_change` with role="default".
+	 * Model-profile activation snapshots this before mutating the session so a
+	 * failed-activation rollback can restore the pre-activation resume default
+	 * instead of promoting a transient runtime model to the resume default.
+	 */
+	getSessionDefaultModelSelector(): string | undefined {
+		return this.sessionManager.buildSessionContext().models.default;
+	}
+
+	/**
+	 * Re-assert the session resume default ("provider/id") in the session log
+	 * WITHOUT touching the live runtime model. Appends a `model_change` with
+	 * role="default"; never writes to global settings (apply-for-this-session
+	 * semantics). Used by model-profile activation rollback to neutralize the
+	 * profile main model the failed activation already recorded as the default.
+	 */
+	recordResumeDefaultModel(selector: string): void {
+		this.sessionManager.appendModelChange(selector, "default");
+	}
+
 	/**
 	 * Set model temporarily (for this session only).
 	 * Validates API key, saves to session log but NOT to settings.
+	 *
+	 * The change is recorded in the session log as `role: "temporary"` by
+	 * default, which means it is NOT restored as the session default on resume —
+	 * transient retry/fallback/context-promotion/plan switches must not clobber
+	 * the user's explicit pick (issue #849). Model-profile activation passes
+	 * `persistAsSessionDefault: true` so the profile's main model becomes the
+	 * session default and survives resume, while still not being written to
+	 * global settings (new sessions keep the global default).
 	 * @throws Error if no API key available for the model
 	 */
-	async setModelTemporary(model: Model, thinkingLevel?: ThinkingLevel): Promise<void> {
+	async setModelTemporary(
+		model: Model,
+		thinkingLevel?: ThinkingLevel,
+		options?: { persistAsSessionDefault?: boolean },
+	): Promise<void> {
 		const previousEditMode = this.#resolveActiveEditMode();
 		const apiKey = await this.#modelRegistry.getApiKey(model, this.sessionId);
 		if (!apiKey) {
@@ -5870,7 +5920,10 @@ export class AgentSession {
 
 		this.#clearActiveRetryFallback();
 		this.#setModelWithProviderSessionReset(model);
-		this.sessionManager.appendModelChange(`${model.provider}/${model.id}`, "temporary");
+		this.sessionManager.appendModelChange(
+			`${model.provider}/${model.id}`,
+			options?.persistAsSessionDefault ? "default" : "temporary",
+		);
 		this.settings.getStorage()?.recordModelUsage(`${model.provider}/${model.id}`);
 
 		// Apply explicit thinking level if given; otherwise prefer the model's
@@ -9089,6 +9142,63 @@ export class AgentSession {
 		void this.#emitSessionEvent({ type: "irc_message", message: record });
 	}
 
+	emitSubagentSteerObservation(args: { from: string; to: string; body: string; timestamp?: number }): void {
+		const timestamp = args.timestamp ?? Date.now();
+		const observationId = crypto.randomUUID();
+		const message: CustomMessage = {
+			role: "custom",
+			customType: "subagent:steer",
+			content: `[Steer \`${args.from}\` ⇨ \`${args.to}\` (queued)]\n\n${args.body}`,
+			display: true,
+			details: { observationId, from: args.from, to: args.to, body: args.body, state: "queued" },
+			attribution: "agent",
+			timestamp,
+		};
+		void this.#emitSessionEvent({ type: "subagent_steer_message", message });
+		this.#forwardSubagentSteerRelayToMain({
+			from: args.from,
+			to: args.to,
+			body: args.body,
+			observationId,
+			timestamp,
+		});
+	}
+
+	#forwardSubagentSteerRelayToMain(args: {
+		from: string;
+		to: string;
+		body: string;
+		observationId: string;
+		timestamp: number;
+	}): void {
+		const registry = this.#agentRegistry;
+		if (!registry) return;
+		if (this.#agentId === MAIN_AGENT_ID) return;
+		const mainRef = registry.get(MAIN_AGENT_ID);
+		const mainSession = mainRef?.session;
+		if (!mainSession || mainSession === this) return;
+		const record: CustomMessage = {
+			role: "custom",
+			customType: "subagent:steer:relay",
+			content: `[Steer \`${args.from}\` ⇨ \`${args.to}\` (queued)]\n\n${args.body}`,
+			display: true,
+			details: {
+				observationId: args.observationId,
+				from: args.from,
+				to: args.to,
+				body: args.body,
+				state: "queued",
+			},
+			attribution: "agent",
+			timestamp: args.timestamp,
+		};
+		mainSession.emitSubagentSteerRelayObservation(record);
+	}
+
+	emitSubagentSteerRelayObservation(record: CustomMessage): void {
+		void this.#emitSessionEvent({ type: "subagent_steer_message", message: record });
+	}
+
 	/**
 	 * Run a single ephemeral side-channel turn against this session's current
 	 * model + system prompt + history.  No tools are used; the side request

package/src/session/auth-storage.ts

@@ -7,6 +7,9 @@ export type {
 	ApiKeyCredential,
 	AuthCredential,
 	AuthCredentialEntry,
+	AuthCredentialIfAbsentReason,
+	AuthCredentialIfAbsentResult,
+	AuthCredentialIfAbsentSnapshotResult,
 	AuthCredentialStore,
 	AuthStorageData,
 	AuthStorageOptions,

package/src/session/session-dump-format.ts

@@ -47,13 +47,54 @@ function stripTypeBoxFields(obj: unknown): unknown {
 	return obj;
 }
 
+function escapeXmlAttribute(input: string): string {
+	return input.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function escapeXmlText(input: string): string {
+	return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function decodeCodePoint(hex: string): string {
+	const codePoint = Number.parseInt(hex, 16);
+	if (
+		!Number.isFinite(codePoint) ||
+		codePoint < 0x20 ||
+		(codePoint >= 0x7f && codePoint <= 0x9f) ||
+		(codePoint >= 0xd800 && codePoint <= 0xdfff)
+	) {
+		return `\\u${hex}`;
+	}
+	return String.fromCharCode(codePoint);
+}
+
+function decodeUnicodeEscapeText(input: string): string {
+	return input
+		.replace(/\\\\u([0-9a-fA-F]{4})/g, (_match, hex: string) => decodeCodePoint(hex))
+		.replace(/\\u([0-9a-fA-F]{4})/g, (_match, hex: string) => decodeCodePoint(hex));
+}
+
+function formatParameterValue(value: unknown): string {
+	const raw = typeof value === "string" ? value : (JSON.stringify(value, null, "\t") ?? "null");
+	return escapeXmlText(decodeUnicodeEscapeText(raw));
+}
+
 /** Serialize an object as XML parameter elements, one per key. */
 function formatArgsAsXml(args: Record<string, unknown>, indent = "\t"): string {
 	const parts: string[] = [];
 	for (const [key, value] of Object.entries(args)) {
 		if (key === INTENT_FIELD) continue;
-		const text = typeof value === "string" ? value : JSON.stringify(value);
-		parts.push(`${indent}<parameter name="${key}">${text}</parameter>`);
+		const escapedKey = escapeXmlAttribute(key);
+		const text = formatParameterValue(value);
+		if (text.includes("\n")) {
+			const indentedText = text
+				.split("\n")
+				.map(line => `${indent}\t${line}`)
+				.join("\n");
+			parts.push(`${indent}<parameter name="${escapedKey}">\n${indentedText}\n${indent}</parameter>`);
+		} else {
+			parts.push(`${indent}<parameter name="${escapedKey}">${text}</parameter>`);
+		}
 	}
 	return parts.join("\n");
 }

package/src/session/session-manager.ts

@@ -28,6 +28,7 @@ import {
 	toError,
 } from "@gajae-code/utils";
 import { writeTextAtomic } from "../gjc-runtime/state-writer";
+import * as git from "../utils/git";
 import { ArtifactManager } from "./artifacts";
 import {
 	type BlobPutResult,
@@ -791,6 +792,25 @@ function writeTerminalBreadcrumb(cwd: string, sessionFile: string): void {
 	write.catch(() => {});
 }
 
+/**
+ * Two paths belong to linked worktrees of the same repository when they share a
+ * git common dir but resolve to different git dirs (i.e. one is a `git worktree`
+ * of the other). `--worktree` sessions run from such a linked worktree, so a
+ * `--continue` from the main checkout should still resolve their breadcrumb.
+ */
+function isLinkedWorktreePeer(a: string, b: string): boolean {
+	const ra = git.repo.resolveSync(a);
+	const rb = git.repo.resolveSync(b);
+	if (ra === null || rb === null) return false;
+	// Canonicalize: a worktree's commondir is stored as an absolute path that may
+	// differ from the main checkout only by a symlink prefix (e.g. macOS
+	// /tmp -> /private/tmp), so compare resolved-equivalent paths.
+	return (
+		resolveEquivalentPath(ra.commonDir) === resolveEquivalentPath(rb.commonDir) &&
+		resolveEquivalentPath(ra.gitDir) !== resolveEquivalentPath(rb.gitDir)
+	);
+}
+
 /**
  * Read the terminal breadcrumb for the current terminal, scoped to a cwd.
  * Returns the session file path if it exists and matches the cwd, null otherwise.
@@ -808,8 +828,12 @@ async function readTerminalBreadcrumb(cwd: string): Promise<string | null> {
 		const breadcrumbCwd = lines[0];
 		const sessionFile = lines[1];
 
-		// Only return if cwd matches (user might have cd'd)
-		if (path.resolve(breadcrumbCwd) !== path.resolve(cwd)) return null;
+		// Honor the breadcrumb when the cwd matches, or when it points to a linked
+		// worktree of the same repository (e.g. a `--worktree` session resumed from
+		// the main checkout). A genuinely different project is still ignored.
+		if (path.resolve(breadcrumbCwd) !== path.resolve(cwd) && !isLinkedWorktreePeer(breadcrumbCwd, cwd)) {
+			return null;
+		}
 
 		// Verify the session file still exists
 		const stat = fs.statSync(sessionFile, { throwIfNoEntry: false });
@@ -4010,12 +4034,22 @@ export class SessionManager {
 		// Prefer terminal-scoped breadcrumb (handles concurrent sessions correctly)
 		const terminalSession = await readTerminalBreadcrumb(cwd);
 		const mostRecent = terminalSession ?? (await findMostRecentSession(dir, storage));
-		const manager = new SessionManager(cwd, dir, true, storage);
 		if (mostRecent) {
+			// Adopt the resumed session's recorded cwd and its own directory. A
+			// `--worktree` session lives in a linked worktree whose path differs from
+			// the invocation cwd; binding the manager (and HUD) to `cwd` would leave
+			// it on the main checkout instead of the worktree it was created in.
+			const header = (await loadEntriesFromFile(mostRecent, storage)).find(e => e.type === "session") as
+				| SessionHeader
+				| undefined;
+			const resumeCwd = header?.cwd || cwd;
+			const resumeDir = sessionDir ?? path.resolve(mostRecent, "..");
+			const manager = new SessionManager(resumeCwd, resumeDir, true, storage);
 			await manager.#initSessionFile(mostRecent);
-		} else {
-			manager.#initNewSession();
+			return manager;
 		}
+		const manager = new SessionManager(cwd, dir, true, storage);
+		manager.#initNewSession();
 		return manager;
 	}
 

package/src/setup/credential-auto-import.ts

@@ -0,0 +1,258 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type {
+	AuthCredential,
+	AuthCredentialIfAbsentReason,
+	AuthCredentialIfAbsentSnapshotResult,
+	AuthStorage,
+} from "@gajae-code/ai";
+import { getAgentDir, logger, VERSION } from "@gajae-code/utils";
+import type { ModelRegistry } from "../config/model-registry";
+
+import {
+	type CredentialDiscoveryResult,
+	type CredentialOrigin,
+	type DiscoveryOptions,
+	discoverExternalCredentials,
+	EXTERNAL_PROVIDER_LABELS,
+	type ExternalProvider,
+	filterAutoImportOAuthCredentials,
+	formatCredentialSummary,
+	type ImportableCredential,
+} from "./credential-import";
+
+export const CREDENTIAL_AUTO_IMPORT_ROTATION_WARNING =
+	"Refreshing in gjc may log out the Claude/Codex CLI because OAuth refresh tokens can rotate.";
+
+export type CredentialAutoImportSourceLabel = "claude-code-file" | "claude-code-keychain" | "codex-file";
+export type CredentialAutoImportTrigger = "startup" | "bare-login" | "setup-cli";
+
+const CREDENTIAL_AUTO_IMPORT_STATE_FILENAME = "credential-auto-import-state.json";
+
+interface CredentialAutoImportStateFile {
+	lastImportVersion?: unknown;
+}
+
+export function getCredentialAutoImportStatePath(agentDir: string = getAgentDir()): string {
+	return path.join(agentDir, CREDENTIAL_AUTO_IMPORT_STATE_FILENAME);
+}
+
+export async function readCredentialImportMarker(agentDir?: string): Promise<string | undefined> {
+	try {
+		const raw = await fs.readFile(getCredentialAutoImportStatePath(agentDir), "utf-8");
+		const parsed = JSON.parse(raw) as CredentialAutoImportStateFile;
+		return typeof parsed.lastImportVersion === "string" ? parsed.lastImportVersion : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export async function writeCredentialImportMarker(version: string, agentDir?: string): Promise<boolean> {
+	try {
+		const statePath = getCredentialAutoImportStatePath(agentDir);
+		await fs.mkdir(path.dirname(statePath), { recursive: true });
+		await fs.writeFile(statePath, `${JSON.stringify({ lastImportVersion: version })}\n`);
+		return true;
+	} catch (error: unknown) {
+		logger.warn("Failed to persist credential auto-import state", { error });
+		return false;
+	}
+}
+
+export enum CredentialAutoImportFailureClass {
+	DiscoveryUnavailable = "discovery-unavailable",
+	SourceUnreadable = "source-unreadable",
+	SourceMalformed = "source-malformed",
+	KeychainDenied = "keychain-denied",
+	WriteInvalid = "write-invalid",
+	WriteConflict = "write-conflict",
+	BrokerUnavailable = "broker-unavailable",
+	BrokerUnsupported = "broker-unsupported",
+	Unknown = "unknown",
+}
+
+export interface CredentialAutoImportSkipped {
+	credential: ImportableCredential;
+	reason: AuthCredentialIfAbsentReason;
+	entries: AuthCredentialIfAbsentSnapshotResult["entries"];
+}
+
+export interface CredentialAutoImportFailure {
+	credential?: ImportableCredential;
+	origin?: CredentialOrigin;
+	source?: string;
+	failureClass: CredentialAutoImportFailureClass;
+}
+
+export interface CredentialAutoImportResult {
+	imported: ImportableCredential[];
+	skipped: CredentialAutoImportSkipped[];
+	failures: CredentialAutoImportFailure[];
+	discovered: boolean;
+	discovery?: CredentialDiscoveryResult;
+	globalDiscoveryFailure?: CredentialAutoImportFailure;
+}
+
+export type CredentialAutoImportAuthStorage = Pick<AuthStorage, "importCredentialIfAbsent">;
+
+export interface CredentialAutoImportOptions {
+	authStorage: CredentialAutoImportAuthStorage;
+	discover?: (options?: DiscoveryOptions) => Promise<CredentialDiscoveryResult>;
+	discoveryOptions?: DiscoveryOptions;
+	trigger: CredentialAutoImportTrigger;
+	sourceLabel?: CredentialAutoImportSourceLabel;
+}
+
+function classifyDiscoverySkip(reason: string, origin: CredentialOrigin): CredentialAutoImportFailureClass {
+	const lower = reason.toLowerCase();
+	if (
+		origin === "claude-code-keychain" &&
+		(lower.includes("eacces") || lower.includes("eperm") || lower.includes("denied"))
+	) {
+		return CredentialAutoImportFailureClass.KeychainDenied;
+	}
+	if (lower.includes("malformed")) return CredentialAutoImportFailureClass.SourceMalformed;
+	if (lower.includes("unreadable")) return CredentialAutoImportFailureClass.SourceUnreadable;
+	return CredentialAutoImportFailureClass.Unknown;
+}
+
+function classifyWriteFailure(error: unknown): CredentialAutoImportFailureClass {
+	const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+	if (message.includes("invalid")) return CredentialAutoImportFailureClass.WriteInvalid;
+	if (message.includes("conflict") || message.includes("constraint"))
+		return CredentialAutoImportFailureClass.WriteConflict;
+	if (
+		message.includes("broker") &&
+		(message.includes("unsupported") || message.includes("404") || message.includes("501"))
+	) {
+		return CredentialAutoImportFailureClass.BrokerUnsupported;
+	}
+	if (message.includes("broker") || message.includes("fetch") || message.includes("network")) {
+		return CredentialAutoImportFailureClass.BrokerUnavailable;
+	}
+	return CredentialAutoImportFailureClass.Unknown;
+}
+
+export async function runExternalCredentialAutoImport({
+	authStorage,
+	discover = discoverExternalCredentials,
+	discoveryOptions,
+}: CredentialAutoImportOptions): Promise<CredentialAutoImportResult> {
+	let discovery: CredentialDiscoveryResult;
+	try {
+		discovery = await discover(discoveryOptions);
+	} catch {
+		const globalDiscoveryFailure = { failureClass: CredentialAutoImportFailureClass.DiscoveryUnavailable };
+		return {
+			imported: [],
+			skipped: [],
+			failures: [globalDiscoveryFailure],
+			discovered: false,
+			globalDiscoveryFailure,
+		};
+	}
+
+	const candidates = filterAutoImportOAuthCredentials(discovery.importable);
+	const failures: CredentialAutoImportFailure[] = discovery.skipped.map(skip => ({
+		origin: skip.origin,
+		source: skip.source,
+		failureClass: classifyDiscoverySkip(skip.reason, skip.origin),
+	}));
+	const imported: ImportableCredential[] = [];
+	const skipped: CredentialAutoImportSkipped[] = [];
+	const importIfAbsent = authStorage.importCredentialIfAbsent;
+
+	for (const credential of candidates) {
+		try {
+			const outcome = await importIfAbsent.call(
+				authStorage,
+				credential.provider,
+				credential.credential as AuthCredential,
+			);
+			if (outcome.inserted === true) {
+				imported.push(credential);
+			} else {
+				skipped.push({ credential, reason: outcome.reason, entries: outcome.entries });
+			}
+		} catch (error) {
+			failures.push({ credential, failureClass: classifyWriteFailure(error) });
+		}
+	}
+
+	return { imported, skipped, failures, discovered: true, discovery };
+}
+
+export function buildCredentialAutoImportNotice(
+	result: Pick<CredentialAutoImportResult, "imported">,
+): string | undefined {
+	if (result.imported.length === 0) return undefined;
+	const providers = [
+		...new Set(result.imported.map(c => EXTERNAL_PROVIDER_LABELS[c.provider as ExternalProvider] ?? c.provider)),
+	];
+	const success = `Imported ${result.imported.length} external OAuth credential(s) into gjc: ${providers.join(", ")}.`;
+	return `${success}\n${CREDENTIAL_AUTO_IMPORT_ROTATION_WARNING}`;
+}
+
+export function formatCredentialAutoImportResult(result: CredentialAutoImportResult): string[] {
+	const lines: string[] = [];
+	for (const credential of result.imported) lines.push(`imported ${formatCredentialSummary(credential)}`);
+	for (const skip of result.skipped) lines.push(`skipped ${skip.credential.source}: ${skip.reason}`);
+	for (const failure of result.failures) {
+		const label = failure.credential?.source ?? failure.source ?? "external credential discovery";
+		lines.push(`failed ${label}: ${failure.failureClass}`);
+	}
+	return lines;
+}
+
+export interface CredentialImportMarkerStore {
+	read: () => Promise<string | undefined> | string | undefined;
+	write: (version: string) => Promise<boolean> | boolean;
+}
+
+export interface StartupCredentialAutoImportOptions {
+	authStorage: CredentialAutoImportOptions["authStorage"];
+	modelRegistry: Pick<ModelRegistry, "refresh">;
+	discover?: CredentialAutoImportOptions["discover"];
+	version?: string;
+	agentDir?: string;
+	markerStore?: CredentialImportMarkerStore;
+}
+
+export async function runStartupCredentialAutoImportIfNeeded({
+	authStorage: activeAuthStorage,
+	modelRegistry: activeModelRegistry,
+	discover,
+	version = VERSION,
+	agentDir,
+	markerStore,
+}: StartupCredentialAutoImportOptions): Promise<string | undefined> {
+	const store = markerStore ?? {
+		read: () => readCredentialImportMarker(agentDir),
+		write: (nextVersion: string) => writeCredentialImportMarker(nextVersion, agentDir),
+	};
+	const lastVersion = await store.read();
+	if (lastVersion === version) {
+		// Steady state: user already completed this version's auto-import gate. Skip all file/Keychain reads.
+		return undefined;
+	}
+
+	const result = await runExternalCredentialAutoImport({
+		authStorage: activeAuthStorage,
+		discover,
+		trigger: "startup",
+	});
+	if (!result.discovered) {
+		return undefined;
+	}
+
+	const candidates = filterAutoImportOAuthCredentials(result.discovery?.importable ?? []);
+	if (candidates.length > 0 && result.imported.length === 0 && result.skipped.length === 0) {
+		return undefined;
+	}
+	await store.write(version);
+
+	if (result.imported.length > 0) {
+		await activeModelRegistry.refresh("offline");
+	}
+	return buildCredentialAutoImportNotice(result);
+}

package/src/setup/credential-import.ts

@@ -25,6 +25,11 @@ export type ExternalProvider = "anthropic" | "openai-codex";
 /** Where a discovered credential came from. */
 export type CredentialOrigin = "claude-code-file" | "claude-code-keychain" | "codex-file";
 
+export const AUTO_IMPORT_OAUTH_PROVIDER_ORIGINS: Record<ExternalProvider, ReadonlySet<CredentialOrigin>> = {
+	anthropic: new Set<CredentialOrigin>(["claude-code-file", "claude-code-keychain"]),
+	"openai-codex": new Set<CredentialOrigin>(["codex-file"]),
+};
+
 /** Human labels for providers, used in redacted summaries. */
 export const EXTERNAL_PROVIDER_LABELS: Record<ExternalProvider, string> = {
 	anthropic: "Claude (Anthropic)",
@@ -408,6 +413,18 @@ export function formatDiscoverySummary(result: CredentialDiscoveryResult): strin
 	return lines;
 }
 
+export function isAutoImportOAuthCredential(credential: ImportableCredential): boolean {
+	return (
+		AUTO_IMPORT_OAUTH_PROVIDER_ORIGINS[credential.provider]?.has(credential.origin) === true &&
+		credential.kind === "oauth" &&
+		credential.credential.type === "oauth"
+	);
+}
+
+export function filterAutoImportOAuthCredentials(credentials: readonly ImportableCredential[]): ImportableCredential[] {
+	return credentials.filter(isAutoImportOAuthCredential);
+}
+
 /**
  * Persist discovered credentials via `upsert`. Each credential is imported
  * independently; a failure on one is recorded without aborting the rest.

package/src/setup/hermes/templates/operator-instructions.v1.md

@@ -15,6 +15,16 @@ These instructions teach a Hermes-style coordinator how to operate GJC through t
 6. Use `{{TOOL_PREFIX}}_report_status` for coordinator-visible status and final reports.
 7. Use `{{TOOL_PREFIX}}_read_tail` only as advisory debug output when structured turn state is insufficient.
 
+## Prefer high-level delegation
+
+When the goal is to hand GJC a whole workflow rather than micro-manage one prompt, prefer the first-class delegate tools over manual `{{TOOL_PREFIX}}_start_session` + `{{TOOL_PREFIX}}_send_prompt` sequencing:
+
+- `gjc_delegate_plan` — run consensus planning (`/skill:ralplan`) to a pending-approval plan.
+- `gjc_delegate_execute` — run execution (`/skill:ultragoal`) to completion with verification.
+- `gjc_delegate_team` — run parallel team execution (`/skill:team`) with internal tmux workers.
+
+Each delegate starts (or reuses) a session, sends one workflow-tagged turn, and returns a durable `turn_id`. Pass `cwd` and `task`; set `allow_mutation: true` only when the bridge startup mutation class is enabled and the user has approved changes. Poll the returned `turn_id` with `{{TOOL_PREFIX}}_await_turn` or watch for the `delegation.started` event, exactly as with `send_prompt`. Drop to the manual start/send tools only for fine-grained control the delegate tools do not cover.
+
 ## Event watch
 
 `{{TOOL_PREFIX}}_watch_events` is a bounded long-poll read tool. Call it with `after_seq` set to the last stored sequence number, optional `session_id` or `event_types`, `timeout_ms` up to 30000, and `limit` up to 100. Store the returned `latest_seq` before the next wait. A timeout with no events is not failure; call again or use the turn/status read tools for a snapshot.