@gajae-code/coding-agent 0.6.5 → 0.7.0

package/src/config/model-registry.ts

@@ -70,7 +70,7 @@ export function isAuthenticated(apiKey: string | undefined | null): apiKey is st
 	return Boolean(apiKey) && apiKey !== kNoAuth;
 }
 
-export type ModelRole = "default";
+export type ModelRole = "default" | "vision";
 
 export interface ModelRoleInfo {
 	tag?: string;
@@ -80,11 +80,12 @@ export interface ModelRoleInfo {
 
 export const MODEL_ROLES: Record<ModelRole, ModelRoleInfo> = {
 	default: { tag: "DEFAULT", name: "Default", color: "success" },
+	vision: { tag: "VISION", name: "Vision", color: "accent" },
 };
 
-export const MODEL_ROLE_IDS: ModelRole[] = ["default"];
+export const MODEL_ROLE_IDS: ModelRole[] = ["default", "vision"];
 
-export type GjcModelAssignmentTargetId = "default" | "executor" | "architect" | "planner" | "critic";
+export type GjcModelAssignmentTargetId = "default" | "vision" | "executor" | "architect" | "planner" | "critic";
 
 export interface GjcModelAssignmentTargetInfo extends ModelRoleInfo {
 	id: GjcModelAssignmentTargetId;
@@ -93,6 +94,7 @@ export interface GjcModelAssignmentTargetInfo extends ModelRoleInfo {
 
 export const GJC_MODEL_ASSIGNMENT_TARGET_IDS: GjcModelAssignmentTargetId[] = [
 	"default",
+	"vision",
 	"executor",
 	"architect",
 	"planner",
@@ -101,6 +103,7 @@ export const GJC_MODEL_ASSIGNMENT_TARGET_IDS: GjcModelAssignmentTargetId[] = [
 
 export const GJC_MODEL_ASSIGNMENT_TARGETS: Record<GjcModelAssignmentTargetId, GjcModelAssignmentTargetInfo> = {
 	default: { id: "default", tag: "DEFAULT", name: "Default", color: "success", settingsPath: "modelRoles" },
+	vision: { id: "vision", tag: "VISION", name: "Vision", color: "accent", settingsPath: "modelRoles" },
 	executor: {
 		id: "executor",
 		tag: "EXECUTOR",

package/src/config/models-config-schema.ts

@@ -81,7 +81,7 @@ const ModelBindingsSchema = z.object({
 	modelRoles: z.record(z.string(), z.string().min(1)).optional(),
 	agentModelOverrides: z.record(z.string(), z.string().min(1)).optional(),
 });
-export const ProfileRoleSchema = z.enum(["default", "executor", "architect", "planner", "critic"]);
+export const ProfileRoleSchema = z.enum(["default", "vision", "executor", "architect", "planner", "critic"]);
 
 function isValidProfileModelSelector(value: string): boolean {
 	if (value.includes(",")) return false;

package/src/config/settings-schema.ts

@@ -254,6 +254,22 @@ export const SETTINGS_SCHEMA = {
 	"auth.broker.url": { type: "string", default: undefined },
 	"auth.broker.token": { type: "string", default: undefined },
 
+	// Notifications (Telegram bundled reference client)
+	"notifications.enabled": { type: "boolean", default: false },
+	"notifications.telegram.botToken": { type: "string", default: undefined },
+	"notifications.telegram.chatId": { type: "string", default: undefined },
+	"notifications.redact": { type: "boolean", default: false },
+	"notifications.verbosity": {
+		type: "string",
+		default: "lean",
+		validate: (value: string) => value === "lean" || value === "verbose",
+	},
+	"notifications.daemon.idleTimeoutMs": {
+		type: "number",
+		default: 60000,
+		validate: (value: number) => Number.isFinite(value) && value > 0,
+	},
+
 	autoResume: {
 		type: "boolean",
 		default: false,
@@ -3155,6 +3171,18 @@ export interface ShellMinimizerSettings {
 	maxCaptureBytes: number;
 }
 
+export interface NotificationsSettings {
+	enabled: boolean;
+	telegram: {
+		botToken: string | undefined;
+		chatId: string | undefined;
+	};
+	redact: boolean;
+	daemon: {
+		idleTimeoutMs: number;
+	};
+}
+
 /** Map group prefix -> typed settings interface */
 export interface GroupTypeMap {
 	compaction: CompactionSettings;
@@ -3173,6 +3201,7 @@ export interface GroupTypeMap {
 	modelTags: ModelTagsSettings;
 	cycleOrder: string[];
 	shellMinimizer: ShellMinimizerSettings;
+	notifications: NotificationsSettings;
 }
 
 export type GroupPrefix = keyof GroupTypeMap;

package/src/coordinator/contract.ts

@@ -17,6 +17,9 @@ export const COORDINATOR_MCP_TOOL_NAMES = [
 	"gjc_coordinator_read_turn",
 	"gjc_coordinator_await_turn",
 	"gjc_coordinator_report_status",
+	"gjc_delegate_plan",
+	"gjc_delegate_execute",
+	"gjc_delegate_team",
 ] as const;
 
 export type CoordinatorToolName = (typeof COORDINATOR_MCP_TOOL_NAMES)[number];

package/src/coordinator-mcp/server.ts

@@ -184,7 +184,8 @@ type CoordinatorEventKind =
 	| "question.answered"
 	| "report.written"
 	| "tmux.delivery_succeeded"
-	| "tmux.delivery_failed";
+	| "tmux.delivery_failed"
+	| "delegation.started";
 
 interface CoordinatorEvent {
 	schema_version: 1;
@@ -411,9 +412,116 @@ function toolSchema(name: CoordinatorToolName): {
 			},
 		};
 	}
+	const delegateWorkflow = workflowForDelegateTool(name);
+	if (delegateWorkflow) {
+		return {
+			name,
+			description: delegateToolDescription(delegateWorkflow),
+			inputSchema: {
+				type: "object",
+				properties: {
+					cwd,
+					task: {
+						type: "string",
+						description: "Delegated task or objective to run through the selected GJC workflow.",
+					},
+					prompt: { type: "string", description: "Alias for task; accepted when task is absent." },
+					allow_mutation: allowMutation,
+					session_id: {
+						type: "string",
+						description:
+							"Optional existing GJC coordinator bridge session id to reuse; omitted starts a fresh session.",
+					},
+					queue: {
+						type: "boolean",
+						description: "When reusing a session with an active turn, queue instead of failing.",
+					},
+					force: {
+						type: "boolean",
+						description: "When reusing a session with an active turn, supersede it before sending.",
+					},
+					model: {
+						type: "string",
+						description: "Optional model hint passed in prompt metadata; no provider default is implied.",
+					},
+					await_completion: { type: "boolean", description: "If true, poll the turn until terminal or timeout." },
+					timeout_ms: {
+						type: "number",
+						description: "Bounded await timeout; same cap semantics as gjc_coordinator_await_turn.",
+					},
+					poll_interval_ms: { type: "number", description: "Bounded await polling interval." },
+					lines: { type: "number", description: "Bounded advisory tail lines returned with await/read payloads." },
+				},
+				required: ["cwd", "allow_mutation"],
+			},
+		};
+	}
 	return { name, description: "List known scoped GJC coordinator bridge sessions.", inputSchema: common };
 }
 
+type DelegateWorkflow = "plan" | "execute" | "team";
+
+function workflowForDelegateTool(name: string): DelegateWorkflow | null {
+	switch (name) {
+		case "gjc_delegate_plan":
+			return "plan";
+		case "gjc_delegate_execute":
+			return "execute";
+		case "gjc_delegate_team":
+			return "team";
+		default:
+			return null;
+	}
+}
+
+function workflowSkill(workflow: DelegateWorkflow): "ralplan" | "ultragoal" | "team" {
+	switch (workflow) {
+		case "plan":
+			return "ralplan";
+		case "execute":
+			return "ultragoal";
+		case "team":
+			return "team";
+	}
+}
+
+function delegateToolDescription(workflow: DelegateWorkflow): string {
+	switch (workflow) {
+		case "plan":
+			return "Delegate consensus planning to GJC: start a session and run /skill:ralplan to completion, returning durable turn status and artifact references.";
+		case "execute":
+			return "Delegate execution to GJC: start a session and run /skill:ultragoal to completion, returning durable turn status and artifact references.";
+		case "team":
+			return "Delegate parallel team execution to GJC: start a session and run /skill:team to completion, returning durable turn status and artifact references.";
+	}
+}
+
+function workflowPrompt(
+	workflow: DelegateWorkflow,
+	toolName: string,
+	canonicalCwd: string,
+	task: string,
+	options: { mutationRequested: boolean; model?: string | null },
+): string {
+	const skill = workflowSkill(workflow);
+	const model = options.model && options.model.trim().length > 0 ? options.model.trim() : "none";
+	const mutationIntent = options.mutationRequested ? "mutation requested" : "read-only";
+	return [
+		`/skill:${skill}`,
+		"",
+		`Delegated by coordinator MCP tool: ${toolName}`,
+		`Workflow: ${workflow}`,
+		`CWD: ${canonicalCwd}`,
+		`Mutation intent: ${mutationIntent}; coordinator startup policy remains authoritative.`,
+		`Optional model hint: ${model}`,
+		"",
+		"Task:",
+		task,
+		"",
+		"Return durable status and artifact references through GJC runtime/coordinator state. Do not expose host-facing tmux controls.",
+	].join("\n");
+}
+
 function normalizeSession(session: Record<string, unknown>): Record<string, unknown> {
 	return {
 		session_id: session.sessionId ?? session.session_id ?? session.name ?? "unknown",
@@ -424,6 +532,14 @@ function normalizeSession(session: Record<string, unknown>): Record<string, unkn
 	};
 }
 
+async function canonicalizePath(value: string): Promise<string> {
+	try {
+		return await fs.realpath(value);
+	} catch {
+		return path.resolve(value);
+	}
+}
+
 async function ensureDir(dir: string): Promise<void> {
 	await fs.mkdir(dir, { recursive: true });
 }
@@ -1587,6 +1703,159 @@ export function createCoordinatorMcpServer(options: CoordinatorMcpServerOptions
 					transport: { mcp: "long_poll", push_subscriptions: false },
 				};
 			}
+			const delegateWorkflow = workflowForDelegateTool(name);
+			if (delegateWorkflow) {
+				requireCoordinatorMutation(config, "sessions", args);
+				const canonicalCwd = await assertCoordinatorWorkdir(config, args.cwd);
+				const hasTask = typeof args.task === "string" && args.task.trim().length > 0;
+				const hasPrompt = typeof args.prompt === "string" && args.prompt.trim().length > 0;
+				const task = hasTask ? String(args.task) : hasPrompt ? String(args.prompt) : null;
+				if (!task) return { ok: false, reason: "task_required" };
+				const promptAliasIgnored = hasTask && hasPrompt;
+				const mutationRequested = args.allow_mutation === true;
+				const taggedPrompt = workflowPrompt(delegateWorkflow, name, canonicalCwd, task, {
+					mutationRequested,
+					model: typeof args.model === "string" ? args.model : null,
+				});
+
+				let session: Record<string, unknown>;
+				let reusedSession = false;
+				if (args.session_id != null) {
+					const sessionId = safeExternalId("session", args.session_id);
+					const existing = asRecord(await readJsonFile(sessionFile(sessionId)));
+					if (!existing) return { ok: false, reason: "unknown_session", session_id: sessionId };
+					const storedCwd = typeof existing.cwd === "string" ? existing.cwd : null;
+					const canonicalStored = storedCwd ? await canonicalizePath(storedCwd) : null;
+					const canonicalRequested = await canonicalizePath(canonicalCwd);
+					if (!canonicalStored || canonicalStored !== canonicalRequested) {
+						return { ok: false, reason: "session_cwd_mismatch", session_id: sessionId };
+					}
+					session = existing;
+					reusedSession = true;
+				} else {
+					const input = {
+						cwd: canonicalCwd,
+						prompt: undefined,
+						namespace: config.namespace,
+						worktree: true as const,
+					};
+					const started = services.startSession
+						? await services.startSession(input)
+						: await startTmuxSession(config, input, namespaceDir, commandRunner);
+					const startedRecord = asRecord(started);
+					if (!startedRecord) throw new Error("coordinator_session_command_required");
+					session = normalizeSession(startedRecord);
+					await writeJsonFile(sessionFile(session.session_id), session);
+					await appendCoordinatorEvent(namespaceDir, {
+						kind: "session.started",
+						sessionId: String(session.session_id),
+						summary: `Session ${String(session.session_id)} started by coordinator delegate`,
+						payloadRef: path.relative(namespaceDir, sessionFile(session.session_id)),
+						metadata: { delegate: true, workflow: delegateWorkflow },
+					});
+					const live = hasTmuxIdentity(session) ? await hasTmuxSession(session, commandRunner) : null;
+					await writeSessionState(namespaceDir, String(session.session_id), "ready_for_input", {
+						live,
+						reason: null,
+					});
+				}
+
+				const sessionId = String(session.session_id);
+				const activeTurn = reusedSession ? await readActiveTurn(namespaceDir, sessionId) : null;
+				if (activeTurn && args.force !== true && args.queue !== true) {
+					return {
+						ok: false,
+						reason: "active_turn_exists",
+						session_id: sessionId,
+						active_turn_id: activeTurn.turn_id,
+					};
+				}
+				if (activeTurn && args.force === true) {
+					const timestamp = new Date().toISOString();
+					const superseded = {
+						...activeTurn,
+						status: "superseded" as const,
+						updated_at: timestamp,
+						completed_at: timestamp,
+					};
+					await writeTurnRecord(namespaceDir, superseded);
+					await clearActiveTurn(namespaceDir, superseded);
+				}
+				const shouldQueue = args.queue === true && args.force !== true && !!activeTurn;
+				const turn = shouldQueue
+					? makeTurnRecord(config, sessionId, taggedPrompt, "queued")
+					: await activateTurn(session, makeTurnRecord(config, sessionId, taggedPrompt, "active"));
+				if (shouldQueue) await writeTurnRecord(namespaceDir, turn);
+				await appendCoordinatorEvent(namespaceDir, {
+					kind: "delegation.started",
+					sessionId,
+					turnId: turn.turn_id,
+					summary: `Delegated ${delegateWorkflow} via ${name} on session ${sessionId}`,
+					metadata: {
+						workflow: delegateWorkflow,
+						tool_name: name,
+						reused_session: reusedSession,
+						queued: shouldQueue,
+						allow_mutation: args.allow_mutation === true,
+					},
+				});
+				const sessionState = await readSessionState(namespaceDir, sessionId);
+				const base: Record<string, unknown> = {
+					ok: true,
+					workflow: delegateWorkflow,
+					tool_name: name,
+					session_id: sessionId,
+					turn_id: turn.turn_id,
+					active_turn_id: shouldQueue ? activeTurn?.turn_id : turn.turn_id,
+					status: turn.status,
+					queued: turn.delivery.queued,
+					delivered: turn.delivery.delivered,
+					delivery: turn.delivery,
+					session,
+					session_state: sessionState,
+					turn,
+					awaited: false,
+					artifacts: [],
+				};
+				if (promptAliasIgnored) base.prompt_alias_ignored = true;
+				if (args.await_completion === true && !shouldQueue) {
+					const timeoutMs = boundedTimeoutMs(args.timeout_ms);
+					const pollIntervalMs = boundedPollIntervalMs(args.poll_interval_ms);
+					const deadline = Date.now() + timeoutMs;
+					let payload = await readTurnPayload(turn.turn_id, sessionId, args.lines);
+					while (
+						payload.ok === true &&
+						!TERMINAL_TURN_STATUSES.has((payload.turn as TurnRecord).status) &&
+						Date.now() < deadline
+					) {
+						const remainingMs = deadline - Date.now();
+						await waitForTurnStateChange(
+							namespaceDir,
+							payload.turn as TurnRecord,
+							Math.min(pollIntervalMs, remainingMs),
+						);
+						payload = await readTurnPayload(turn.turn_id, sessionId, args.lines);
+					}
+					const awaitedTurn = (payload.ok === true ? payload.turn : turn) as TurnRecord;
+					base.awaited = true;
+					base.status = awaitedTurn.status;
+					base.turn = awaitedTurn;
+					base.final_response = (awaitedTurn as unknown as Record<string, unknown>).final_response ?? null;
+					base.evidence = (awaitedTurn as unknown as Record<string, unknown>).evidence ?? [];
+					if (payload.ok === true) {
+						base.session_state = payload.session_state;
+						base.advisory_status = payload.advisory_status;
+					}
+					// Mirror gjc_coordinator_await_turn timeout semantics: a still-active
+					// turn at the deadline is a bounded timeout, not a completion.
+					if (!TERMINAL_TURN_STATUSES.has(awaitedTurn.status)) {
+						base.timed_out = true;
+						base.reason = "timeout";
+						base.ok = false;
+					}
+				}
+				return base;
+			}
 			if (name === "gjc_coordinator_start_session") {
 				requireCoordinatorMutation(config, "sessions", args);
 				const cwd = await assertCoordinatorWorkdir(config, args.cwd);

package/src/daemon/builtin.ts

@@ -0,0 +1,46 @@
+/**
+ * Static built-in daemon controller map.
+ *
+ * Intentionally a static map keyed by daemon kind rather than a mutable plugin
+ * registry: there is exactly one kind today (`telegram`). Promote to a richer
+ * registry only when a second daemon kind exists.
+ */
+
+import type { Settings } from "../config/settings";
+import { type TelegramDaemonControlDeps, TelegramDaemonController } from "../notifications/telegram-daemon-control";
+import type { BuiltInDaemonController, DaemonKind } from "./control-types";
+
+export const BUILT_IN_DAEMON_KINDS = ["telegram"] as const satisfies readonly DaemonKind[];
+
+export interface BuiltInDaemonControllerDeps {
+	telegram?: TelegramDaemonControlDeps;
+}
+
+export function createBuiltInDaemonControllers(
+	settings: Settings,
+	deps: BuiltInDaemonControllerDeps = {},
+): Record<DaemonKind, BuiltInDaemonController> {
+	return {
+		telegram: new TelegramDaemonController(settings, deps.telegram),
+	};
+}
+
+/**
+ * Resolve the controllers a command should act on. `--all` selects every
+ * built-in kind; otherwise the explicit `kinds` (defaulting to `telegram`).
+ */
+export function selectDaemonControllers(
+	settings: Settings,
+	kinds: DaemonKind[] | undefined,
+	all: boolean,
+	deps: BuiltInDaemonControllerDeps = {},
+): BuiltInDaemonController[] {
+	const map = createBuiltInDaemonControllers(settings, deps);
+	if (all) return Object.values(map);
+	const selected = kinds && kinds.length > 0 ? kinds : (["telegram"] as DaemonKind[]);
+	return selected.map(kind => {
+		const controller = map[kind];
+		if (!controller) throw new Error(`unknown daemon kind: ${kind}`);
+		return controller;
+	});
+}

package/src/daemon/control-types.ts

@@ -0,0 +1,65 @@
+/**
+ * Public types for the `gjc daemon` control plane.
+ *
+ * Deliberately compact: a small result/status surface plus a built-in
+ * controller contract. There is exactly one daemon kind today (`telegram`);
+ * a richer registry is intentionally deferred until a second kind exists.
+ */
+
+export type DaemonKind = "telegram";
+
+export type DaemonAction = "list" | "status" | "stop" | "reload";
+
+export type DaemonHealth = "not_configured" | "stopped" | "running" | "stale" | "stopping" | "error";
+
+export interface DaemonRuntimeInfo {
+	/** `source` when respawn goes through bun/node + the entry script; `compiled` for a single-file binary. */
+	mode: "source" | "compiled";
+	execPath: string;
+	/** True only in source/dev mode, where a respawn loads amended TypeScript directly. */
+	reloadPicksUpSourceEdits: boolean;
+	/** Present when the runtime mode constrains what reload can achieve (e.g. compiled binary). */
+	warning?: string;
+}
+
+export interface DaemonStatus {
+	kind: DaemonKind;
+	configured: boolean;
+	health: DaemonHealth;
+	pid?: number;
+	ownerId?: string;
+	startedAt?: number;
+	heartbeatAt?: number;
+	roots?: string[];
+	rootCount?: number;
+	runtime: DaemonRuntimeInfo;
+	detail?: string;
+}
+
+export interface DaemonOperationOptions {
+	/** How long to wait for cooperative release before escalating. */
+	gracefulTimeoutMs?: number;
+	/** How long to wait for the old pid to die after SIGKILL. */
+	killTimeoutMs?: number;
+	/** Allow hard-kill escalation / acting on a still-live owner. */
+	force?: boolean;
+	/** For reload: spawn a fresh owner even when none is currently running. */
+	spawnIfStopped?: boolean;
+}
+
+export interface DaemonOperationResult {
+	kind: DaemonKind;
+	action: Exclude<DaemonAction, "list">;
+	ok: boolean;
+	before?: DaemonStatus;
+	after?: DaemonStatus;
+	warnings: string[];
+	message: string;
+}
+
+export interface BuiltInDaemonController {
+	readonly kind: DaemonKind;
+	status(): Promise<DaemonStatus>;
+	stop(opts?: DaemonOperationOptions): Promise<DaemonOperationResult>;
+	reload(opts?: DaemonOperationOptions): Promise<DaemonOperationResult>;
+}

package/src/daemon/runtime.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared source-vs-compiled runtime detection for daemon spawning.
+ *
+ * Centralizes the logic previously embedded in `ensureTelegramDaemonRunning`
+ * so session autostart, reload, and status reporting agree on how a daemon
+ * process is launched and whether a reload can pick up amended source.
+ */
+
+import * as path from "node:path";
+
+export interface GjcRuntimeSpawnInfo {
+	execPath: string;
+	mode: "source" | "compiled";
+	/** Prefix prepended before the gjc subcommand args; `[Bun.main]` in source mode, otherwise `[]`. */
+	argsPrefix: string[];
+	/** True only when respawn loads edited TypeScript directly (source/dev mode). */
+	reloadPicksUpSourceEdits: boolean;
+	/** Set in compiled mode to explain that a rebuild is required before reload picks up source edits. */
+	warning?: string;
+}
+
+const COMPILED_RELOAD_WARNING =
+	"Compiled binary: reload respawns the same binary. Rebuild the binary first for amended source to take effect.";
+
+/**
+ * Resolve how to spawn a detached gjc subcommand for the current runtime.
+ *
+ * Source/dev mode (bun/node) prepends the entry script (`Bun.main`) so the
+ * respawn loads edited source. A compiled single-file binary self-spawns its
+ * own subcommand directly and cannot pick up workspace source edits.
+ */
+export function resolveGjcRuntimeSpawnInfo(execPath: string = process.execPath): GjcRuntimeSpawnInfo {
+	const base = path.basename(execPath).toLowerCase();
+	const fromSource = base === "bun" || base === "node" || base.startsWith("bun") || base.startsWith("node");
+	const mainScript = fromSource && typeof Bun !== "undefined" ? (Bun as unknown as { main?: string }).main : undefined;
+	if (fromSource) {
+		return {
+			execPath,
+			mode: "source",
+			argsPrefix: mainScript ? [mainScript] : [],
+			reloadPicksUpSourceEdits: true,
+		};
+	}
+	return {
+		execPath,
+		mode: "compiled",
+		argsPrefix: [],
+		reloadPicksUpSourceEdits: false,
+		warning: COMPILED_RELOAD_WARNING,
+	};
+}

package/src/defaults/gjc/skills/ultragoal/SKILL.md

@@ -107,6 +107,21 @@ Loop until `gjc ultragoal status` reports all goals complete:
    `gjc ultragoal checkpoint --goal-id <id> --status blocked --evidence "<completed legacy GJC goal blocks goal create in this thread>" --gjc-goal-json <goal-get-json-or-path>`
 11. Resume failed goals with `gjc ultragoal complete-goals --retry-failed`.
 
+## Blocker triage and pause discipline
+
+An active Ultragoal run must not give up on a blocker by pausing the goal and asking the user. Classify every blocker before deciding what to do, and default to `resolvable` when unsure:
+
+- **`resolvable`** — anything the agent can act on: failing tests, missing implementation, a dependency to install, an ambiguous-but-inferable detail, investigation. **Never pause.** Exhaust autonomous resolution first: investigate, `gjc ultragoal steer --kind add_subgoal --title "Investigate blocker" --objective "..." --evidence "..." --rationale "..."`, delegate an `executor`, or preserve the blocker durably with `gjc ultragoal checkpoint --status blocked` / `gjc ultragoal record-review-blockers` and keep scheduling the next goal.
+- **`human_blocked`** — only the user can act: credentials/secrets, a manual or physical step, an external approval/decision, access the agent lacks. Pause is the last resort and is gated.
+
+`goal({"op":"pause"})` is **blocked at runtime** while an Ultragoal run is active unless the latest durable ledger event classifies the current blocker as `human_blocked`. To pause, record the classification immediately before pausing and cite the human-only dependency as evidence:
+
+```sh
+gjc ultragoal classify-blocker --classification human_blocked --evidence "<the specific human-only dependency>" [--goal-id <id>]
+```
+
+Recording `--classification resolvable` is an audit note only; it never authorizes a pause. The `ask` tool stays blocked during active runs regardless of classification — record unresolved decisions as durable blockers instead of prompting.
+
 ## Dynamic steering
 
 Use `gjc ultragoal steer` when real findings or blockers prove the current story decomposition should change while the aggregate objective and constraints stay fixed. Steering is explicit-only and evidence-backed; broad natural-language requests are rejected instead of guessed.
@@ -199,6 +214,7 @@ An ultragoal story cannot be checkpointed `complete` until the active agent has
    - CLI surfaces require runtime argv replay: `replaySafe: true`, an allowlisted argv `command`, and replayed normalized stdout matching `recordedStdout`; unsafe commands require audited `replayExempt` metadata with exact fields `reasonCode`, `reason`, `approvedBy`, and `fallbackArtifactRefs` plus a structurally valid fallback artifact. Allowed `reasonCode` values are exactly `unsafe_side_effect`, `requires_credentials`, `requires_network`, `non_deterministic_external`, `destructive`, `interactive_only`, and `platform_unavailable`.
    - Native/desktop/tui surfaces require a structurally valid screenshot, PTY capture with terminal control codes, or app-automation transcript.
    - API/package/algorithm/math surfaces require a real artifact file or typed receipt. Bare `inlineEvidence` text alone is not sufficient for any surface.
+   - The mandatory **computer-use** red-team suite (`kill-switch-bypass`, `suspended-enforcement`, `permission-revoked`, …) is conditional, not universal: require it only when computer/desktop control is genuinely part of the product surface being dogfooded. For every other product type, prove the change through the matching live surface instead — browser-use automation for web/GUI, bash/CLI live invocation or argv replay for CLI, and real artifacts or typed receipts for API/package/algorithm/math. Editing docs, prompts, or skills that merely mention computer-use does not by itself make the computer-use suite applicable; pick the red-team surface that matches what the change actually ships.
 7. The executor QA/red-team lane must report a matrix using `executorQa.contractCoverage`, `executorQa.surfaceEvidence`, `executorQa.adversarialCases`, and `executorQa.artifactRefs`. Not-applicable rows are allowed only in `contractCoverage` and `surfaceEvidence`; each `status: "not_applicable"` row requires `contractRef` plus `reason`. `adversarialCases` rows cannot be not-applicable.
 8. Run a final code review pass and fold it into the strict quality gate. Clean means `architectReview.architectureStatus`, `architectReview.productStatus`, and `architectReview.codeStatus` are all `"CLEAR"`, `architectReview.recommendation` is `"APPROVE"`, executor QA statuses are `"passed"`, iteration is `"passed"` with `fullRerun: true`, every evidence field is non-empty, every required matrix row is present, and every blockers array is empty. `COMMENT`, `WATCH`, `REQUEST CHANGES`, `BLOCK`, missing evidence, missing or shallow matrix rows, plan/code mismatches, or non-empty blockers are non-clean.
 9. If any lane finds an issue, do **not** checkpoint `complete` and do **not** call `goal({"op":"complete"})`. Record durable blocker work instead:

package/src/extensibility/extensions/runner.ts

@@ -6,6 +6,7 @@ import type { CredentialDisabledEvent, ImageContent, Model, ProviderResponseMeta
 import type { KeyId } from "@gajae-code/tui";
 import { logger } from "@gajae-code/utils";
 import type { ModelRegistry } from "../../config/model-registry";
+import type { WorkflowGateEmitter } from "../../modes/shared/agent-wire/unattended-session";
 import { type Theme, theme } from "../../modes/theme/theme";
 import type { SessionManager } from "../../session/session-manager";
 import type {
@@ -180,6 +181,7 @@ export class ExtensionRunner {
 	#getContextUsageFn: () => ContextUsage | undefined = () => undefined;
 	#compactFn: (instructionsOrOptions?: string | CompactOptions) => Promise<void> = async () => {};
 	#getSystemPromptFn: () => string[] = () => [];
+	#getWorkflowGateFn: () => WorkflowGateEmitter | undefined = () => undefined;
 	#newSessionHandler: NewSessionHandler = async () => ({ cancelled: false });
 	#branchHandler: BranchHandler = async () => ({ cancelled: false });
 	#navigateTreeHandler: NavigateTreeHandler = async () => ({ cancelled: false });
@@ -234,6 +236,7 @@ export class ExtensionRunner {
 		this.#hasPendingMessagesFn = contextActions.hasPendingMessages;
 		this.#shutdownHandler = contextActions.shutdown;
 		this.#getSystemPromptFn = contextActions.getSystemPrompt;
+		this.#getWorkflowGateFn = contextActions.getWorkflowGate ?? (() => undefined);
 
 		// Command context actions (optional, only for interactive mode)
 		if (commandContextActions) {
@@ -463,6 +466,7 @@ export class ExtensionRunner {
 			shutdown: () => this.#shutdownHandler(),
 			getSystemPrompt: () => this.#getSystemPromptFn(),
 			hasQueuedMessages: () => this.#hasPendingMessagesFn(), // deprecated alias
+			workflowGate: this.#getWorkflowGateFn(),
 		};
 	}
 

package/src/extensibility/extensions/types.ts

@@ -32,6 +32,7 @@ import type { PythonResult } from "../../eval/py/executor";
 import type { BashResult } from "../../exec/bash-executor";
 import type { ExecOptions, ExecResult } from "../../exec/exec";
 import type { CustomEditor } from "../../modes/components/custom-editor";
+import type { WorkflowGateEmitter } from "../../modes/shared/agent-wire/unattended-session";
 import type { Theme } from "../../modes/theme/theme";
 import type { CustomMessage } from "../../session/messages";
 import type { ReadonlySessionManager, SessionManager } from "../../session/session-manager";
@@ -310,6 +311,11 @@ export interface ExtensionContext {
 	getSystemPrompt(): string[];
 	/** @deprecated Use hasPendingMessages() instead */
 	hasQueuedMessages(): boolean;
+	/**
+	 * Unattended workflow-gate bridge. Present only when the session runs in
+	 * unattended/RPC mode; `undefined` in interactive/TUI mode (notify-only).
+	 */
+	workflowGate?: WorkflowGateEmitter;
 }
 
 /**
@@ -1234,6 +1240,8 @@ export interface ExtensionContextActions {
 	getContextUsage: () => ContextUsage | undefined;
 	compact: (instructionsOrOptions?: string | CompactOptions) => Promise<void>;
 	getSystemPrompt: () => string[];
+	/** Unattended workflow-gate bridge (present only in unattended/RPC mode). */
+	getWorkflowGate?: () => WorkflowGateEmitter | undefined;
 }
 
 /** Actions for ExtensionCommandContext (ctx.* in command handlers). */