@gajae-code/coding-agent 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-06-09
+
+### Changed
+
+- Added conservative `timeout-minutes` values to all CI workflow jobs to prevent indefinite hangs.
+
+### Fixed
+
+- Improved the grep limit-reached message to show the current limit value and suggest using `--limit` for more results.
+- Fixed a `gjc harness` recovery deadlock where a session created by `start` without `--detach` (persisted as `started` with no owner lease/endpoint) could never get a live owner: `recover` refused to spawn one because no prior endpoint existed, while `start` reported `session-already-exists`. `recover` now bootstraps a fresh owner for a never-started session (no lease, no endpoint, no owner-run evidence) without writing a misleading `vanish` receipt, reported via `bootstrappedOwner: true`. Bootstrap is independent of the vanish classifier's `ownerRequired` verdict (nothing has vanished), so a session started in a non-git workspace (git delta `unknown`) is recovered too, while a deleted worktree is still refused (#421).
+
+## [0.4.1] - 2026-06-07
+
+### Changed
+
+- Hardened the default system prompt with a `<skill-discipline>` block (never ignore skill text, keep read-only/interview skills from mutating, recommend and invoke the matching `/skill` on approval) and tightened `<communication>` to ban permission-begging/deferral phrasing and never announce remaining work instead of doing it (#392).
+- Cleaned up the bundled GJC workflow skill docs and defaulted execution handoff to ultragoal while prioritizing ralplan refinement (#395, #396).
+
 ## [0.4.0] - 2026-06-06
 
 ### Added

package/dist/types/commands/ultragoal.d.ts

@@ -3,5 +3,6 @@ export default class Ultragoal extends Command {
     static description: string;
     static strict: boolean;
     static examples: string[];
+    static delegateHelp: boolean;
     run(): Promise<void>;
 }

package/dist/types/config/settings-schema.d.ts

@@ -1,6 +1,5 @@
 import { type SkillDiscoverySettings } from "./skill-settings-defaults";
 /** Unified settings schema - single source of truth for all settings.
- * Unified settings schema - single source of truth for all settings.
  *
  * Each setting is defined once here with:
  * - Type and default value
@@ -1144,6 +1143,15 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "If false, skip update check";
         };
     };
+    readonly "starReminder.enabled": {
+        readonly type: "boolean";
+        readonly default: true;
+        readonly ui: {
+            readonly tab: "interaction";
+            readonly label: "GitHub Star Reminder";
+            readonly description: "Show the interactive GitHub star reminder when gh is authenticated";
+        };
+    };
     readonly collapseChangelog: {
         readonly type: "boolean";
         readonly default: false;
@@ -1260,11 +1268,11 @@ export declare const SETTINGS_SCHEMA: {
     };
     readonly "contextPromotion.enabled": {
         readonly type: "boolean";
-        readonly default: true;
+        readonly default: false;
         readonly ui: {
             readonly tab: "context";
             readonly label: "Auto-Promote Context";
-            readonly description: "Promote to a larger-context model on context overflow instead of compacting";
+            readonly description: "Promote to a larger-context model on context overflow instead of compacting (off by default; opt in to enable)";
         };
     };
     readonly "compaction.enabled": {

package/dist/types/gjc-runtime/launch-tmux.d.ts

@@ -22,6 +22,7 @@ export interface TmuxLaunchContext {
     currentBranch?: string | null;
     existingBranchSessionName?: string | null;
     project?: string | null;
+    diagnosticWriter?: (message: string) => void;
 }
 export interface TmuxSpawnResult {
     exitCode: number | null;

package/dist/types/gjc-runtime/ultragoal-runtime.d.ts

@@ -99,6 +99,17 @@ export declare function createUltragoalPlan(input: {
     brief: string;
     gjcGoalMode?: UltragoalGjcGoalMode;
 }): Promise<UltragoalPlan>;
+export interface UltragoalRunCompletionState {
+    requiredGoals: UltragoalGoal[];
+    incompleteGoals: UltragoalGoal[];
+    nextGoal?: UltragoalGoal;
+    allComplete: boolean;
+    hasBlockers: boolean;
+    needsFinalAggregateReceipt: boolean;
+}
+export declare function getUltragoalRunCompletionState(plan: UltragoalPlan, options?: {
+    retryFailed?: boolean;
+}): UltragoalRunCompletionState;
 export declare function startNextUltragoalGoal(input: {
     cwd: string;
     retryFailed?: boolean;
@@ -115,6 +126,24 @@ export declare function checkpointUltragoalGoal(input: {
     gjcGoalJson?: string;
     qualityGateJson?: string;
 }): Promise<UltragoalPlan>;
+export interface UltragoalCheckpointContinuation {
+    plan: UltragoalPlan;
+    checkpointedGoal: UltragoalGoal;
+    nextGoal?: UltragoalGoal;
+    startedNext: boolean;
+    allComplete: boolean;
+    incompleteGoals: UltragoalGoal[];
+}
+export declare function checkpointAndContinueUltragoalGoal(input: {
+    cwd: string;
+    goalId: string;
+    status: UltragoalGoalStatus;
+    evidence: string;
+    gjcGoalJson?: string;
+    qualityGateJson?: string;
+    advanceNext?: boolean;
+    retryFailed?: boolean;
+}): Promise<UltragoalCheckpointContinuation>;
 export declare function addUltragoalSubgoal(input: {
     cwd: string;
     title: string;

package/dist/types/harness-control-plane/finalize.d.ts

@@ -1,3 +1,4 @@
+import { type ReviewVerdict } from "./types";
 export interface ValidationCommandSpec {
     name: string;
     command: string;
@@ -25,6 +26,12 @@ export interface FinalizeOptions {
     requireTests?: boolean;
     requireCommit?: boolean;
     requirePr?: boolean;
+    /** Review-only sessions produce a terminal verdict instead of implementation validation. */
+    reviewOnly?: boolean;
+    /** Operator/loop-supplied terminal review verdict (closed vocabulary). */
+    verdict?: string | null;
+    /** Bounded PR/issue reference for the review target (e.g. "PR-414"). Never resolved from the live repo. */
+    prTarget?: string | null;
     validationCommands?: ValidationCommandSpec[];
     checks: FinalizeChecks;
     clock?: () => number;
@@ -39,6 +46,7 @@ export interface FinalizeResult {
     }[];
     commitHash: string | null;
     prUrl: string | null;
+    verdict?: ReviewVerdict | null;
     issueArtifact: string | null;
     blockers: string[];
 }

package/dist/types/harness-control-plane/receipts.d.ts

@@ -1,4 +1,4 @@
-import type { GitDelta, ReceiptFamily, RecoveryClassification } from "./types";
+import { type GitDelta, type ReceiptFamily, type RecoveryClassification, type ReviewVerdict } from "./types";
 export interface ReceiptSubject {
     workspace: string;
     branch: string | null;
@@ -84,5 +84,20 @@ export interface CompletionEvidence {
     finalizedAt: string;
     blockers: string[];
 }
+export interface ReviewVerdictEvidence {
+    verdict: ReviewVerdict;
+    prTarget: string | null;
+    finalizedAt: string;
+    /** Bounded summary code/reference for the verdict; never raw assistant text. */
+    summaryRef: string | null;
+}
+export interface ReviewFailureEvidence {
+    /** Machine-actionable reason the review produced no terminal verdict. */
+    reason: string;
+    prTarget: string | null;
+    failedAt: string;
+    /** Routing hint for the operator/fallback path. */
+    fallback: string;
+}
 /** Classifications that MUST have a valid `vanish` receipt before the action proceeds. */
 export declare function requiresVanishBeforeAction(classification: RecoveryClassification): boolean;

package/dist/types/harness-control-plane/types.d.ts

@@ -9,6 +9,12 @@
  */
 /** Harnesses the control plane can operate. v1 implements `gajae-code` only. */
 export type Harness = "gajae-code" | "codex" | "omx";
+/** Operating mode of a session. `implement` builds/changes code; `review` produces a read-only verdict. */
+export type SessionMode = "implement" | "review";
+/** Closed vocabulary of terminal review verdicts a review-only session may emit. */
+export type ReviewVerdict = "APPROVE_MERGE_READY" | "REQUEST_CHANGES" | "OWNER_CONFIRMATION_REQUIRED";
+export declare const REVIEW_VERDICTS: readonly ReviewVerdict[];
+export declare function isReviewVerdict(value: unknown): value is ReviewVerdict;
 /** Lifecycle states of an operated session. */
 export type HarnessLifecycle = "new" | "started" | "submitted" | "observing" | "recovering" | "validating" | "finalizing" | "completed" | "blocked" | "retired";
 /** Event severities emitted by the owner. */
@@ -20,7 +26,7 @@ export type RiskKind = "normal" | "prompt-not-accepted" | "deleted-worktree" | "
 /** Deterministic recovery classifications. */
 export type RecoveryClassification = "continue" | "send-enter" | "reinject-prompt" | "restart-clean" | "restart-preserve-delta" | "fallback-codex-exec" | "human-check";
 /** Receipt families persisted under the session storage dir. */
-export type ReceiptFamily = "vanish" | "prompt-acceptance" | "validation" | "completion";
+export type ReceiptFamily = "vanish" | "prompt-acceptance" | "validation" | "completion" | "review-verdict" | "review-failure";
 /** The CLI verbs / primitives exposed by `gjc harness <verb>`. */
 export type HarnessVerb = "start" | "submit" | "observe" | "classify" | "recover" | "validate" | "finalize" | "retire" | "events" | "monitor" | "operate";
 /** Submission transports. */
@@ -54,6 +60,8 @@ export interface PrimitiveResponse<E = Record<string, unknown>> {
 export interface SessionHandle {
     sessionId: string;
     harness: Harness;
+    /** Operating mode; absent on legacy records means `implement`. */
+    mode?: SessionMode;
     repo: string | null;
     workspace: string;
     branch: string | null;

package/dist/types/modes/rpc/rpc-client.d.ts

@@ -8,7 +8,7 @@ import type { CompactionResult } from "@gajae-code/agent-core/compaction";
 import type { ImageContent, Model } from "@gajae-code/ai";
 import type { BashResult } from "../../exec/bash-executor";
 import type { SessionStats } from "../../session/agent-session";
-import type { RpcHandoffResult, RpcHostToolDefinition, RpcSessionState, RpcWorkflowGate, RpcWorkflowGateResolution } from "./rpc-types";
+import type { RpcExtensionUIRequest, RpcHandoffResult, RpcHostToolDefinition, RpcSessionState, RpcUnattendedAccepted, RpcUnattendedDeclaration, RpcWorkflowGate, RpcWorkflowGateResolution } from "./rpc-types";
 export interface RpcClientOptions {
     /** Path to the CLI entry point (default: searches for dist/cli.js) */
     cliPath?: string;
@@ -68,6 +68,16 @@ export declare class RpcClient {
      * Answer a workflow lifecycle gate and wait for the server resolution envelope.
      */
     respondGate(gateId: string, answer: unknown, idempotencyKey?: string): Promise<RpcWorkflowGateResolution>;
+    /**
+     * Subscribe to extension UI requests emitted by the server (e.g. select /
+     * input / editor / confirm). Returns an unsubscribe function.
+     */
+    onExtensionUiRequest(listener: (req: RpcExtensionUIRequest) => void): () => void;
+    /**
+     * Enter unattended mode by declaring budget + scopes + action allowlist.
+     * Returns the accepted declaration, or rejects (fail-closed) on refusal.
+     */
+    negotiateUnattended(declaration: RpcUnattendedDeclaration): Promise<RpcUnattendedAccepted>;
     /**
      * Get collected stderr output (useful for debugging).
      */

package/dist/types/reminders/star-reminder.d.ts

@@ -0,0 +1,115 @@
+import type { ImageContent } from "@gajae-code/ai";
+import type { CustomMessage } from "../session/messages";
+export declare const STAR_REMINDER_REPO = "Yeachan-Heo/gajae-code";
+export declare const STAR_REMINDER_CUSTOM_TYPE = "star-reminder";
+export declare const STARRED_CACHE_TTL_MS: number;
+export interface StarReminderState {
+    declined: boolean;
+    starred: boolean;
+    /** ISO-8601 timestamp of the last authoritative star check, or "" if never. */
+    starredCheckedAt: string;
+}
+export type StarCheckStatus = "starred" | "unstarred" | "unavailable";
+export interface GhResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+}
+export type RunGh = (args: string[], options?: {
+    timeoutMs?: number;
+}) => Promise<GhResult>;
+export interface StarReminderDeps {
+    statePath?: string;
+    now?: () => Date;
+    runGh?: RunGh;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function getStarReminderStatePath(): string;
+export declare function defaultStarReminderState(): StarReminderState;
+/** Read state without locking. Missing or malformed files return the default. */
+export declare function readStarReminderStateUnlocked(statePath?: string): Promise<StarReminderState>;
+/** Whether a stored `starred:true` is still within the 24h cache window. */
+export declare function isStarredCacheFresh(state: StarReminderState, now?: Date): boolean;
+/**
+ * Lock-protected read-modify-write. The mutator receives the freshly re-read
+ * state under the lock; callers MUST base monotonic decisions on that value,
+ * not on any snapshot captured before the lock was held.
+ */
+export declare function updateStarReminderStateLocked(mutator: (current: StarReminderState) => StarReminderState | Promise<StarReminderState>, deps?: StarReminderDeps): Promise<StarReminderState>;
+/** A successful PUT is authoritative: always record starred and clear declined. */
+export declare function recordStarredFromPut(deps?: StarReminderDeps): Promise<StarReminderState>;
+/**
+ * Record the result of a fresh `gh` star check performed by this operation.
+ * - "starred": authoritative, clears declined so all reminders stop.
+ * - "unstarred": may downgrade, but only when the current state is not a
+ *   still-fresh confirmed star (which a concurrent process may have just
+ *   written); in that case the fresher confirmation wins.
+ */
+export declare function recordFreshStarCheck(status: "starred" | "unstarred", deps?: StarReminderDeps): Promise<StarReminderState>;
+/** Record a launch-nudge decline. Never downgrades a confirmed star. */
+export declare function recordDeclinedAfterNo(deps?: StarReminderDeps): Promise<StarReminderState>;
+/** Default `gh` runner. Returns an unavailable-style result instead of throwing. */
+export declare function runGhDefault(args: string[], options?: {
+    timeoutMs?: number;
+}): Promise<GhResult>;
+/** Classify the star state of the repo via `gh api`. */
+export declare function checkGhStarred(deps?: StarReminderDeps): Promise<StarCheckStatus>;
+/** Star the repo via `gh api -X PUT`. Returns whether the PUT succeeded. */
+export declare function autoStarRepo(deps?: StarReminderDeps): Promise<boolean>;
+/**
+ * Determine the star state for this session, hitting `gh` only when needed.
+ * A fresh cached star skips `gh`; unstarred and declined states are rechecked.
+ * Authoritative results are persisted via the monotonic helpers.
+ */
+export declare function refreshStarStateForSession(deps?: StarReminderDeps): Promise<StarCheckStatus>;
+export interface StarReminderPromptUI {
+    /** Show a yes/no confirmation. Resolves true when the user accepts. */
+    confirm(title: string, message: string): Promise<boolean>;
+    /** Optional guard; when it returns false the nudge is skipped silently. */
+    isIdle?: () => boolean;
+}
+/**
+ * Run the launch nudge once. Caller is responsible for the `startup.quiet`,
+ * `starReminder.enabled`, and true-interactive gates. All errors are swallowed
+ * so the launch path can never be broken by the reminder.
+ */
+export declare function maybeShowLaunchStarReminder(ui: StarReminderPromptUI, deps?: StarReminderDeps): Promise<void>;
+/**
+ * Schedule the launch nudge to run after the first render so the networked
+ * `gh` check never blocks startup. Returns immediately.
+ */
+export declare function scheduleLaunchStarReminderAfterFirstRender(ui: StarReminderPromptUI, deps?: StarReminderDeps): void;
+export interface StarReminderLaunchGateInput {
+    /** The `starReminder.enabled` setting. */
+    enabled: boolean;
+    /** The `startup.quiet` setting. */
+    quiet: boolean;
+}
+export interface StarReminderLaunchGate {
+    /** Whether to register the decline-driven injection contributor. */
+    register: boolean;
+    /** Whether to schedule the launch nudge after first render. */
+    schedule: boolean;
+}
+/**
+ * Pure decision for interactive wiring. The injection contributor is registered
+ * whenever the feature is enabled; the launch nudge is additionally suppressed
+ * by quiet startup. Centralizing this keeps the interactive gate testable.
+ */
+export declare function starReminderLaunchGate(input: StarReminderLaunchGateInput): StarReminderLaunchGate;
+export interface StarReminderSessionRef {
+    getSessionId(): string | undefined;
+}
+export type StarReminderCustomMessage = Pick<CustomMessage, "customType" | "content" | "display" | "details" | "attribution">;
+export type InternalBeforeAgentStartContributor = (event: {
+    prompt: string;
+    images?: ImageContent[];
+    sessionId: string | undefined;
+}) => Promise<StarReminderCustomMessage | undefined>;
+export declare function createStarReminderMessage(): StarReminderCustomMessage;
+/**
+ * Build a before-agent-start contributor that injects the persuasion message
+ * once per logical session id, for declined-and-still-unstarred users only.
+ */
+export declare function createStarReminderBeforeAgentStartContributor(session: StarReminderSessionRef, deps?: StarReminderDeps): InternalBeforeAgentStartContributor;

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

@@ -294,6 +294,18 @@ export interface SessionStats {
     premiumRequests: number;
     cost: number;
 }
+/** A custom message contributed at the before-agent-start point. */
+export type BeforeAgentStartInternalMessage = Pick<CustomMessage, "customType" | "content" | "display" | "details" | "attribution">;
+/**
+ * Internal (first-party, non-user-hook) contributor invoked at the active
+ * before-agent-start point alongside the extension runner. Returns an optional
+ * custom message to append to the prompt context. Errors are nonfatal.
+ */
+export type BeforeAgentStartContributor = (event: {
+    prompt: string;
+    images?: ImageContent[];
+    sessionId: string | undefined;
+}) => Promise<BeforeAgentStartInternalMessage | undefined>;
 export declare class AgentSession {
     #private;
     readonly agent: Agent;
@@ -991,6 +1003,12 @@ export declare class AgentSession {
      * Check if extensions have handlers for a specific event type.
      */
     hasExtensionHandlers(eventType: string): boolean;
+    /**
+     * Register a first-party internal before-agent-start contributor. Returns an
+     * unregister function. This is NOT user-facing hook discovery; it is an
+     * in-core seam invoked alongside the extension runner.
+     */
+    registerBeforeAgentStartContributor(contributor: BeforeAgentStartContributor): () => void;
     /**
      * Get the extension runner (for setting UI context and error handlers).
      */

package/examples/extensions/README.md

@@ -5,57 +5,37 @@ Example extensions for gajae-code.
 ## Usage
 
 ```bash
-# Load an extension with --extension flag
-pi --extension examples/extensions/permission-gate.ts
+# Copy an existing extension into the user extension directory for auto-discovery
+mkdir -p ~/.gjc/agent/extensions
+cp packages/coding-agent/examples/extensions/hello.ts ~/.gjc/agent/extensions/
 
-# Or copy to extensions directory for auto-discovery
-cp permission-gate.ts ~/.gjc/agent/extensions/
+# Project-local extensions can live in .gjc/extensions/
+mkdir -p .gjc/extensions
+cp packages/coding-agent/examples/extensions/pirate.ts .gjc/extensions/
 ```
 
 ## Examples
 
-### Lifecycle & Safety
+### Custom Tools & API
 
-| Extension                | Description                                                                  |
-| ------------------------ | ---------------------------------------------------------------------------- |
-| `permission-gate.ts`     | Prompts for confirmation before dangerous bash commands (rm -rf, sudo, etc.) |
-| `protected-paths.ts`     | Blocks writes to protected paths (.env, .git/, node_modules/)                |
-| `confirm-destructive.ts` | Confirms before destructive session actions (clear, switch, branch)          |
-| `dirty-repo-guard.ts`    | Prevents session changes with uncommitted git changes                        |
-
-### Custom Tools
-
-| Extension     | Description                                                                   |
-| ------------- | ----------------------------------------------------------------------------- |
-| `todo.ts`     | Todo list tool + `/todos` command with custom rendering and state persistence |
-| `hello.ts`    | Minimal custom tool example                                                   |
-| `question.ts` | Demonstrates `ctx.ui.select()` for asking the user questions                  |
-| `subagent/`   | Delegate tasks to specialized subagents with isolated context windows         |
+| Extension     | Description                                                |
+| ------------- | ---------------------------------------------------------- |
+| `hello.ts`    | Minimal custom tool example                                |
+| `api-demo.ts` | Demonstrates logger access, injected `pi.zod`, and modules |
 
 ### Commands & UI
 
-| Extension        | Description                                                                    |
-| ---------------- | ------------------------------------------------------------------------------ |
-| `plan-mode.ts`   | Anthropic Code-style plan mode for read-only exploration with `/plan` command     |
-| `tools.ts`       | Interactive `/tools` command to enable/disable tools with session persistence  |
-| `handoff.ts`     | Transfer context to a new focused session via `/handoff <goal>`                |
-| `qna.ts`         | Extracts questions from last response into editor via `ctx.ui.setEditorText()` |
-| `status-line.ts` | Shows turn progress in footer via `ctx.ui.setStatus()` with themed colors      |
-| `snake.ts`       | Snake game with custom UI, keyboard handling, and session persistence          |
-
-### Git Integration
-
-| Extension                | Description                                                               |
-| ------------------------ | ------------------------------------------------------------------------- |
-| `git-checkpoint.ts`      | Creates git stash checkpoints at each turn for code restoration on branch |
-| `auto-commit-on-exit.ts` | Auto-commits on exit using last assistant message for commit message      |
+| Extension           | Description                                                                   |
+| ------------------- | ----------------------------------------------------------------------------- |
+| `plan-mode.ts`      | Anthropic Code-style plan mode for read-only exploration with `/plan` command |
+| `tools.ts`          | Interactive `/tools` command to enable/disable tools with session persistence |
+| `reload-runtime.ts` | Adds a command and tool for reloading extensions, skills, prompts, and themes |
 
 ### System Prompt & Compaction
 
-| Extension              | Description                                                           |
-| ---------------------- | --------------------------------------------------------------------- |
-| `pirate.ts`            | Demonstrates `systemPromptAppend` to dynamically modify system prompt |
-| `custom-compaction.ts` | Custom compaction that summarizes entire conversation                 |
+| Extension   | Description                                                          |
+| ----------- | -------------------------------------------------------------------- |
+| `pirate.ts` | Demonstrates `systemPromptAppend` to dynamically modify system prompt |
 
 ### External Dependencies
 
@@ -63,11 +43,10 @@ cp permission-gate.ts ~/.gjc/agent/extensions/
 | ----------------- | ------------------------------------------------------------------------- |
 | `chalk-logger.ts` | Uses chalk from parent node_modules (demonstrates jiti module resolution) |
 | `with-deps/`      | Extension with its own package.json and dependencies                      |
-| `file-trigger.ts` | Watches a trigger file and injects contents into conversation             |
 
 ## Writing Extensions
 
-See [docs/extensions.md](../../docs/extensions.md) for full documentation.
+The examples below show the core extension patterns used by this directory.
 
 ```typescript
 import type { ExtensionAPI } from "@gajae-code/coding-agent";

package/package.json

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

package/src/cli/grep-cli.ts

@@ -98,7 +98,7 @@ export async function runGrepCommand(cmd: GrepCommandArgs): Promise<void> {
 		console.log(chalk.green(`Files with matches: ${result.filesWithMatches}`));
 		console.log(chalk.green(`Files searched: ${result.filesSearched}`));
 		if (result.limitReached) {
-			console.log(chalk.yellow(`Limit reached: true`));
+			console.log(chalk.yellow(`Result limit reached (${cmd.limit} matches). Use --limit to show more.`));
 		}
 		console.log("");
 

package/src/commands/harness.ts

@@ -241,6 +241,12 @@ interface OwnerExitEvidence {
 	lastSignal: string | null;
 	promptAcceptedSeen: boolean;
 	completedSeen: boolean;
+	/** True only when the owner is genuinely gone (lease missing or process dead). */
+	terminal: boolean;
+	/** True when the owner process is provably alive (live lease + fresh heartbeat) but the endpoint did not route. */
+	transient: boolean;
+	/** ISO timestamp of the most recent non-terminal RPC-derived owner event, if any (observability only). */
+	lastRpcActivityAt: string | null;
 }
 
 async function buildOwnerExitEvidence(root: string, state: SessionState): Promise<OwnerExitEvidence> {
@@ -251,12 +257,23 @@ async function buildOwnerExitEvidence(root: string, state: SessionState): Promis
 	let lastSignal: string | null = null;
 	let promptAcceptedSeen = false;
 	let completedSeen = false;
+	let lastRpcActivityAt: string | null = null;
 	for (const event of events) {
 		const signal = (event.evidence as { signal?: unknown } | undefined)?.signal;
 		if (typeof signal === "string") lastSignal = signal;
 		if (event.kind === "prompt_accepted" || signal === "prompt-accepted") promptAcceptedSeen = true;
 		if (event.kind === "rpc_agent_completed" || signal === "completed") completedSeen = true;
+		// Terminal completion/failure frames are NOT owner liveness — exclude them from activity.
+		if (event.kind.startsWith("rpc_") && event.kind !== "rpc_agent_completed" && event.kind !== "rpc_agent_failed") {
+			lastRpcActivityAt = event.createdAt;
+		}
 	}
+	// Owner liveness is the lease heartbeat, never RPC frames: a "live" lease means the owner process
+	// is alive and heartbeating within TTL, so a failed endpoint call is a transient observation gap.
+	// Real owner loss (missing/dead lease) stays terminal and keeps its original reason string so
+	// existing consumers that match on the reason continue to escalate.
+	const terminal = !lease || leaseStatus === "dead";
+	const transient = leaseStatus === "live";
 	let reason = "owner-not-live";
 	if (!lease) {
 		reason = promptAcceptedSeen && !completedSeen ? "owner-exited-after-prompt-acceptance" : "owner-lease-missing";
@@ -281,6 +298,9 @@ async function buildOwnerExitEvidence(root: string, state: SessionState): Promis
 		lastSignal,
 		promptAcceptedSeen,
 		completedSeen,
+		terminal,
+		transient,
+		lastRpcActivityAt,
 	};
 }
 
@@ -684,6 +704,7 @@ export default class Harness extends Command {
 		const handle: SessionHandle = {
 			sessionId,
 			harness,
+			mode: input.mode === "review" || input.reviewOnly === true ? "review" : "implement",
 			repo: typeof input.repo === "string" ? input.repo : null,
 			workspace,
 			branch: preflight.declaredBranch ?? preflight.actualBranch,
@@ -953,9 +974,27 @@ export default class Harness extends Command {
 			observation: { ...observation, lifecycle: state.lifecycle },
 			retryBudget: budget,
 		});
-		const vanishReceiptId = await writeVanishReceiptForDecision(root, state, observation, decision.classification);
+		// A session persisted as `started` whose owner was never spawned (no lease,
+		// no endpoint, no owner-run evidence) is not a vanish — it simply never had
+		// an owner. Bootstrap a fresh owner instead of deadlocking on the missing
+		// prior endpoint (which `start` without `--detach` never records).
+		const ownerNeverStarted =
+			state.lifecycle === "started" &&
+			!beforeExit.endpointPresent &&
+			!beforeExit.promptAcceptedSeen &&
+			!beforeExit.completedSeen &&
+			beforeExit.lastEventKind === null &&
+			observation.risk !== "deleted-worktree";
+		// Bootstrapping a never-started owner is not a vanish, so it needs no vanish receipt.
+		const vanishReceiptId = ownerNeverStarted
+			? null
+			: await writeVanishReceiptForDecision(root, state, observation, decision.classification);
+		// A never-started owner has no in-flight work to preserve, so bootstrapping it does not
+		// depend on the vanish classifier's `ownerRequired` verdict — that gate exists to protect a
+		// vanished owner's worktree. Without this, a session started in a non-git workspace (git
+		// delta `unknown` → classifier `human-check` with `ownerRequired: false`) would stay stuck.
 		const restoredOwner =
-			decision.ownerRequired && beforeExit.endpointPresent
+			ownerNeverStarted || (decision.ownerRequired && beforeExit.endpointPresent)
 				? await this.#spawnDetachedOwner(root, sessionId, state.handle.workspace)
 				: null;
 		if (restoredOwner?.live) {
@@ -968,7 +1007,7 @@ export default class Harness extends Command {
 				writeJson(
 					buildResponse(state, true, {
 						pending: false,
-						restoredOwner: true,
+						...(ownerNeverStarted ? { bootstrappedOwner: true } : { restoredOwner: true }),
 						decision,
 						observation: { ...observation, lifecycle: state.lifecycle, ownerLive: true },
 						ownerExit: beforeExit,

package/src/commands/ultragoal.ts

@@ -12,6 +12,7 @@ export default class Ultragoal extends Command {
 	static description = "Run native GJC Ultragoal workflow commands";
 	static strict = false;
 	static examples = ["$ gjc ultragoal status --json"];
+	static delegateHelp = true;
 
 	async run(): Promise<void> {
 		const shouldActivateGoalMode = isUltragoalCreateGoalsInvocation(this.argv);