@gajae-code/coding-agent 0.2.5 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-03
+
+### Added
+
+- Added runtime-enforced Ultragoal executor QA/red-team evidence matrices for completion checkpoints, with plan-first contract coverage, user-surface evidence, adversarial cases, artifact references, scoped Executor red-team guidance, and focused rejection tests for shallow or contradictory QA evidence.
+### Fixed
+
+- Clarified that `gjc team` requires an existing tmux-backed leader session from `gjc --tmux`, with actionable help, docs, and failure text.
+- Kept deep-interview ask options visible for long prompts by adding an opt-in scrollable selector title panel with selector-local `PageUp`/`PageDown` prompt scrolling, while leaving normal ask dialogs and global keybinding configuration unchanged.
+
 ## [0.2.5] - 2026-06-02
 
 ### Added

package/dist/types/async/job-manager.d.ts

@@ -2,7 +2,7 @@ import type { AgentSource } from "../task/types";
 export interface AsyncJob {
     id: string;
     type: "bash" | "task";
-    status: "running" | "completed" | "failed" | "cancelled";
+    status: "running" | "completed" | "failed" | "cancelled" | "paused";
     startTime: number;
     label: string;
     abortController: AbortController;
@@ -27,6 +27,61 @@ export interface AsyncJobMetadata {
         assignment?: string;
     };
 }
+/**
+ * Typed outcome a subagent task run may produce. A `paused` outcome is
+ * non-terminal and non-delivering: the run suspended at a safe boundary and the
+ * subagent can be resumed from its persisted sessionFile. `completed` always
+ * wins a race with a late pause because the run returns it once it has actually
+ * finished.
+ */
+export type SubagentRunOutcome = {
+    kind: "completed";
+    text: string;
+} | {
+    kind: "paused";
+    note?: string;
+};
+/** Canonical lifecycle of a subagent across pause/resume cycles. */
+export type SubagentLifecycle = "running" | "paused" | "queued" | "completed" | "failed" | "cancelled";
+/**
+ * Live, executor-owned control handle for a RUNNING subagent. Registered when a
+ * subagent run starts and removed on pause/terminal so a paused subagent retains
+ * no live `AgentSession` reference (leak-free).
+ */
+export interface SubagentLiveHandle {
+    /** Request a cooperative safe-boundary pause (never aborts the in-flight tool). */
+    requestPause(): void;
+    /** Inject a steering message into the live session. */
+    injectMessage(content: string, deliverAs: "steer" | "followUp" | "nextTurn"): Promise<void>;
+}
+/**
+ * Canonical, stable-id-keyed record for a subagent. Survives `AsyncJob`
+ * eviction so resume stays addressable by subagent id, and is the single source
+ * of truth for control-plane status and identity.
+ */
+export interface SubagentRecord {
+    subagentId: string;
+    ownerId?: string;
+    /** Current live/last AsyncJob id; null while queued with no active job. */
+    currentJobId: string | null;
+    historicalJobIds: string[];
+    status: SubagentLifecycle;
+    sessionFile: string | null;
+    /** False for ephemeral sessions (no persistent artifacts dir). */
+    resumable: boolean;
+    queued?: {
+        ownerId?: string;
+        seq: number;
+        message?: string;
+        createdAt: number;
+    };
+}
+/** Lightweight, manager-owned resume payload. The async layer treats `data` as opaque. */
+export interface ResumeDescriptor {
+    subagentId: string;
+    ownerId?: string;
+    data: unknown;
+}
 export interface AsyncJobManagerOptions {
     onJobComplete: (jobId: string, text: string, job?: AsyncJob) => void | Promise<void>;
     maxRunningJobs?: number;
@@ -88,13 +143,40 @@ export declare class AsyncJobManager {
         jobId: string;
         signal: AbortSignal;
         reportProgress: (text: string, details?: Record<string, unknown>) => Promise<void>;
-    }) => Promise<string>, options?: AsyncJobRegisterOptions): string;
+    }) => Promise<string | SubagentRunOutcome>, options?: AsyncJobRegisterOptions): string;
     /**
      * Cancel a single job by id. When `filter.ownerId` is set and does not
      * match the job's owner, the call is treated as not-found (returns false)
      * so cross-agent cancellation is rejected at the manager level.
      */
     cancel(id: string, filter?: AsyncJobFilter): boolean;
+    /** Register or replace the canonical record for a subagent. */
+    registerSubagentRecord(record: SubagentRecord): void;
+    getSubagentRecord(subagentId: string, filter?: AsyncJobFilter): SubagentRecord | undefined;
+    getSubagentRecords(filter?: AsyncJobFilter): SubagentRecord[];
+    registerLiveHandle(subagentId: string, handle: SubagentLiveHandle): void;
+    getLiveHandle(subagentId: string): SubagentLiveHandle | undefined;
+    removeLiveHandle(subagentId: string): void;
+    /** Install the TaskTool-owned resume runner. Returns the new job id, or undefined on failure. */
+    setResumeRunner(runner: (subagentId: string, message?: string, descriptor?: ResumeDescriptor) => string | undefined): void;
+    registerResumeDescriptor(descriptor: ResumeDescriptor): void;
+    getResumeDescriptor(subagentId: string, filter?: AsyncJobFilter): ResumeDescriptor | undefined;
+    /** Request a graceful safe-boundary pause of a running subagent. */
+    pauseSubagent(subagentId: string, filter?: AsyncJobFilter): {
+        ok: boolean;
+        status?: SubagentLifecycle;
+        reason?: string;
+    };
+    /** Resume a non-running subagent from its sessionFile, optionally injecting a message first. */
+    resumeSubagent(subagentId: string, filter?: AsyncJobFilter, message?: string): {
+        ok: boolean;
+        status?: SubagentLifecycle;
+        jobId?: string;
+        queued?: boolean;
+        reason?: string;
+    };
+    /** Cancel a subagent by stable id across running/paused/queued states (keeps the session file). */
+    cancelSubagent(subagentId: string, filter?: AsyncJobFilter): boolean;
     getJob(id: string): AsyncJob | undefined;
     getRunningJobs(filter?: AsyncJobFilter): AsyncJob[];
     getRecentJobs(limit?: number, filter?: AsyncJobFilter): AsyncJob[];

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

@@ -0,0 +1,37 @@
+import { Command } from "@gajae-code/utils/cli";
+export default class Harness extends Command {
+    #private;
+    static description: string;
+    static strict: boolean;
+    static args: {
+        verb: import("@gajae-code/utils/cli").ArgDescriptor & {
+            description: string;
+            required: true;
+        };
+    };
+    static flags: {
+        input: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            default: string;
+        };
+        session: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            char: string;
+            description: string;
+        };
+        cursor: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            default: string;
+        };
+        follow: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+        json: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            char: string;
+            description: string;
+            default: boolean;
+        };
+    };
+    static examples: string[];
+    run(): Promise<void>;
+}

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

@@ -74,6 +74,7 @@ interface StringDef {
 interface NumberDef {
     type: "number";
     default: number;
+    validate?: (value: number) => boolean;
     ui?: UiNumber;
 }
 interface EnumDef<T extends readonly string[]> {
@@ -200,6 +201,11 @@ export declare const SETTINGS_SCHEMA: {
         readonly type: "array";
         readonly default: string[];
     };
+    readonly "gjc.deepInterview.ambiguityThreshold": {
+        readonly type: "number";
+        readonly default: 0.05;
+        readonly validate: (value: number) => boolean;
+    };
     readonly "theme.dark": {
         readonly type: "string";
         readonly default: "red-claw";

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

@@ -54,6 +54,8 @@ export declare class Settings {
      * Returns the merged value from global + project + overrides, or the default.
      */
     get<P extends SettingPath>(path: P): SettingValue<P>;
+    /** Check whether a setting is present in loaded settings/overrides rather than coming from schema defaults. */
+    has(path: SettingPath): boolean;
     /**
      * Set a setting value (sync).
      * Updates global settings and queues a background save.

package/dist/types/deep-interview/render-middleware.d.ts

@@ -0,0 +1,5 @@
+import { type Component } from "@gajae-code/tui";
+import { type Theme } from "../modes/theme/theme";
+export declare function renderDeepInterviewAssistantText(text: string, uiTheme: Theme): Component | null;
+export declare function renderDeepInterviewAskQuestion(question: string, uiTheme: Theme): Component | null;
+export declare function formatDeepInterviewSelectorPrompt(question: string): string | null;

package/dist/types/extensibility/custom-tools/types.d.ts

@@ -98,6 +98,7 @@ export type CustomToolSessionEvent = {
     maxAttempts: number;
     delayMs: number;
     errorMessage: string;
+    unbounded?: boolean;
 } | {
     reason: "auto_retry_end";
     success: boolean;

package/dist/types/extensibility/extensions/types.d.ts

@@ -56,6 +56,12 @@ export interface ExtensionUIDialogOptions {
      * hint; non-TUI bridges (RPC, ACP) drop it and do not serialize it.
      */
     wrapFocused?: boolean;
+    /**
+     * For interactive TUI select dialogs, cap the title/prompt area to this
+     * many rows and let PageUp/PageDown scroll that prompt locally. This is a
+     * select-only rendering hint; non-TUI bridges drop it and do not serialize it.
+     */
+    scrollTitleRows?: number;
 }
 /** Raw terminal input listener for extensions. */
 export type TerminalInputHandler = (data: string) => {

package/dist/types/extensibility/shared-events.d.ts

@@ -180,6 +180,7 @@ export interface AutoRetryStartEvent {
     maxAttempts: number;
     delayMs: number;
     errorMessage: string;
+    unbounded?: boolean;
 }
 /** Fired when auto-retry ends */
 export interface AutoRetryEndEvent {

package/dist/types/gjc-runtime/state-graph.d.ts

@@ -0,0 +1,4 @@
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+export type StateGraphSkill = CanonicalGjcWorkflowSkill | "all";
+export type StateGraphFormat = "ascii" | "mermaid" | "dot";
+export declare function renderStateGraph(skill: StateGraphSkill, format?: string): string;

package/dist/types/gjc-runtime/state-migrations.d.ts

@@ -0,0 +1,24 @@
+export interface NormalizeLegacyStateResult {
+    state: Record<string, unknown>;
+    changed: boolean;
+}
+export interface MigrateAndPersistLegacyStateArgs {
+    cwd: string;
+    skill: string;
+    statePath: string;
+    sessionId?: string;
+}
+export interface MigrateAndPersistLegacyStateResult {
+    migrated: boolean;
+    path: string;
+}
+/**
+ * Pure legacy state normalizer for background/internal readers.
+ *
+ * Readers that need compatibility with old on-disk workflow state shapes must call
+ * this in-memory helper and must never call `migrateAndPersistLegacyState`. The
+ * persist variant is reserved for explicit state migration commands because it is
+ * the only path allowed to write normalized upgrades back to `.gjc/state/**`.
+ */
+export declare function normalizeLegacyState(raw: Record<string, unknown>, skill: string): NormalizeLegacyStateResult;
+export declare function migrateAndPersistLegacyState(args: MigrateAndPersistLegacyStateArgs): Promise<MigrateAndPersistLegacyStateResult>;

package/dist/types/gjc-runtime/state-renderer.d.ts

@@ -0,0 +1,65 @@
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import type { SkillManifest } from "./workflow-manifest";
+export declare const STATE_FIELD_ALLOWLIST: readonly ["skill", "phase", "current_phase", "next", "active", "status", "fresh", "fresh_until", "receipt", "artifact_path", "plan_path", "spec_path", "run_id", "stage", "stage_n", "session_id", "updated_at", "handoff_to", "handoff_from", "counts", "hud"];
+export type StateProjectionField = (typeof STATE_FIELD_ALLOWLIST)[number];
+export interface StateStatusSummary {
+    skill: CanonicalGjcWorkflowSkill;
+    phase: string;
+    active: boolean;
+    fresh: boolean;
+    fresh_until?: string;
+    next: string[];
+    receipt_status: string;
+    storage_path: string;
+}
+export declare function compactProjectStateJson(skill: CanonicalGjcWorkflowSkill, stateJson: Record<string, unknown>, manifest: SkillManifest): Record<string, unknown>;
+export declare function projectStateFields(skill: CanonicalGjcWorkflowSkill, stateJson: Record<string, unknown>, manifest: SkillManifest, fields: readonly StateProjectionField[]): Record<string, unknown>;
+export declare function buildStateStatusSummary(skill: CanonicalGjcWorkflowSkill, stateJson: Record<string, unknown>, manifest: SkillManifest, storagePath: string): StateStatusSummary;
+export declare function renderStateStatusLine(summary: StateStatusSummary): string;
+export declare function renderContractMarkdown(skill: CanonicalGjcWorkflowSkill, contract: unknown): string;
+export declare function renderHistoryMarkdown(history: {
+    entries: unknown[];
+    limit: number;
+    since?: string;
+    truncated: boolean;
+}): string;
+export declare function renderUltragoalStatusMarkdown(summary: {
+    exists: boolean;
+    status: string;
+    paths: {
+        goalsPath: string;
+        ledgerPath?: string;
+    };
+    gjcObjective?: string;
+    currentGoal?: {
+        id: string;
+        status: string;
+        title?: string;
+        objective?: string;
+    };
+    counts: Record<string, number>;
+    goals: unknown[];
+}): string;
+export declare function renderTeamStatusMarkdown(snapshot: {
+    team_name: string;
+    phase: string;
+    tmux_target?: string;
+    tmux_session?: string;
+    state_dir: string;
+    task_total: number;
+    task_counts: Record<string, number>;
+    workers: Array<{
+        id: string;
+        status: string;
+    }>;
+    notification_summary?: {
+        total: number;
+        replay_eligible: number;
+        by_state: Record<string, number>;
+    };
+    integration_by_worker?: Record<string, {
+        status?: string;
+        conflict_files?: string[];
+    }>;
+}): string;
+export declare function renderStateMarkdown(skill: CanonicalGjcWorkflowSkill, stateJson: Record<string, unknown>, manifest: SkillManifest): string;

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

@@ -1,3 +1,4 @@
+import { type CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
 /**
  * Native implementation of the `gjc state read|write|clear` command surface.
  *
@@ -10,4 +11,5 @@ export interface StateCommandResult {
     stdout?: string;
     stderr?: string;
 }
+export declare function readWorkflowStateJson(cwd: string, skill: CanonicalGjcWorkflowSkill, sessionId?: string): Promise<Record<string, unknown>>;
 export declare function runNativeStateCommand(args: string[], cwd?: string): Promise<StateCommandResult>;

package/dist/types/gjc-runtime/state-validation.d.ts

@@ -0,0 +1,6 @@
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+export interface StateValidationResult {
+    valid: boolean;
+    error?: string;
+}
+export declare function validateWorkflowStateEnvelope(skill: CanonicalGjcWorkflowSkill, state: unknown): StateValidationResult;

package/dist/types/gjc-runtime/state-writer.d.ts

@@ -0,0 +1,137 @@
+import * as fs from "node:fs/promises";
+import type { SkillActiveEntry } from "../skill-state/active-state";
+import { type AuditEntry, type CanonicalGjcWorkflowSkill, type WorkflowStateMutationOwner } from "../skill-state/workflow-state-contract";
+/**
+ * Sole sanctioned project `.gjc/**` writer module (gate G1).
+ *
+ * All native `.gjc/**` filesystem mutations must route through these primitives.
+ * The primitives validate project `.gjc/**` ownership, create parent directories,
+ * and emit workflow receipts or audit entries where applicable by the caller's
+ * supplied mutation context. No lockfiles are used; isolation is by atomic rename,
+ * append, O_EXCL creates, conditional deletes, per-entry active-state files,
+ * and derived active-state snapshots.
+ * Transaction journals are per mutation id under `.gjc/state/transactions/`;
+ * they are recovery evidence only, never global locks or waiters, so stale
+ * journals do not block unrelated state reads or writes.
+ */
+export type WriterCategory = "state" | "artifact" | "ledger" | "log" | "report" | "agents" | "prune" | "force" | "transaction";
+export interface StateWriterReceiptContext {
+    cwd?: string;
+    skill: CanonicalGjcWorkflowSkill;
+    owner: WorkflowStateMutationOwner;
+    command: string;
+    sessionId?: string;
+    mutationId?: string;
+    nowIso?: string;
+}
+export interface StateWriterAuditContext {
+    cwd?: string;
+    category: WriterCategory;
+    verb: string;
+    owner: WorkflowStateMutationOwner;
+    skill?: CanonicalGjcWorkflowSkill | string;
+    mutationId?: string;
+    fromPhase?: string;
+    toPhase?: string;
+    forced?: boolean;
+}
+export interface WorkflowEnvelopeIntegrityMismatch {
+    path: string;
+    expected: string;
+    actual: string;
+}
+export interface WorkflowTransactionJournal {
+    version: 1;
+    mutation_id: string;
+    status: "pending" | "committed";
+    created_at: string;
+    updated_at: string;
+    caller?: CanonicalGjcWorkflowSkill;
+    callee?: CanonicalGjcWorkflowSkill;
+    paths: string[];
+    steps: string[];
+}
+export interface StateWriterOptions {
+    cwd?: string;
+    receipt?: StateWriterReceiptContext;
+    audit?: StateWriterAuditContext;
+}
+export interface DeleteIfOwnedOptions extends StateWriterOptions {
+    predicate?: (current: unknown) => boolean | Promise<boolean>;
+}
+export interface DeleteResult {
+    path: string;
+    deleted: boolean;
+}
+export interface ActiveSessionScope {
+    sessionId?: string;
+}
+export interface ActiveEntryWriteResult {
+    entryPath: string;
+    snapshotPath: string;
+}
+export interface HardPruneSelectorContext {
+    path: string;
+    value: unknown;
+}
+export interface GenericHardPruneTarget {
+    path: string;
+    category: WriterCategory | string;
+}
+export interface GenericHardPruneSelectorContext {
+    path: string;
+    category: WriterCategory | string;
+    stat: Awaited<ReturnType<typeof fs.stat>>;
+    readJson: () => Promise<unknown>;
+}
+export type GenericHardPruneSelector = (context: GenericHardPruneSelectorContext) => boolean | Promise<boolean>;
+export interface ForceOverwriteOptions extends StateWriterOptions {
+    raw?: boolean;
+}
+export type HardPruneSelector = (context: HardPruneSelectorContext) => boolean | Promise<boolean>;
+export declare class AlreadyExistsError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+export declare function workflowEnvelopeContentSha256(value: unknown): string;
+export declare function stampWorkflowEnvelopeChecksum<T>(value: T, filePath: string, computedAt?: string): T;
+export declare function detectWorkflowEnvelopeIntegrityMismatch(filePath: string): Promise<WorkflowEnvelopeIntegrityMismatch | undefined>;
+export declare function writeJsonAtomic(targetPath: string, value: unknown, options?: StateWriterOptions): Promise<string>;
+export declare function writeWorkflowEnvelopeAtomic(targetPath: string, value: unknown, options?: StateWriterOptions): Promise<string>;
+export declare function writeTextAtomic(targetPath: string, text: string, options?: StateWriterOptions): Promise<string>;
+export declare function updateJsonAtomic<T = unknown>(targetPath: string, mutator: (current: T | undefined) => T | Promise<T>, options?: StateWriterOptions): Promise<string>;
+export declare function appendJsonl(targetPath: string, entry: unknown, options?: StateWriterOptions): Promise<string>;
+export declare function appendText(targetPath: string, text: string, options?: StateWriterOptions): Promise<string>;
+export declare function createJsonNoClobber(targetPath: string, value: unknown, options?: StateWriterOptions): Promise<string>;
+export declare function deleteIfOwned(targetPath: string, predicateOrOptions?: ((current: unknown) => boolean | Promise<boolean>) | DeleteIfOwnedOptions): Promise<DeleteResult>;
+export declare function removeFileAudited(targetPath: string, options?: StateWriterOptions): Promise<DeleteResult>;
+/**
+ * Active entry files under `.gjc/state/active/<skill>.json` and
+ * `.gjc/state/sessions/<id>/active/<skill>.json` are authoritative. The
+ * adjacent `skill-active-state.json` file is only a derived cache rebuilt from
+ * those entries, so concurrent snapshot rebuilds can race without losing any
+ * writer's per-skill state.
+ */
+export declare function writeActiveEntry(cwd: string, sessionScope: string | ActiveSessionScope | undefined, skill: string, entry: SkillActiveEntry, options?: StateWriterOptions): Promise<string>;
+export declare function removeActiveEntry(cwd: string, sessionScope: string | ActiveSessionScope | undefined, skill: string, options?: StateWriterOptions): Promise<DeleteResult>;
+export declare function readActiveEntries(cwd: string, sessionScope?: string | ActiveSessionScope): Promise<SkillActiveEntry[]>;
+export declare function rebuildActiveSnapshot(cwd: string, sessionScope?: string | ActiveSessionScope, options?: StateWriterOptions): Promise<string>;
+export declare function mergeActiveState(cwd: string, sessionScope: string | ActiveSessionScope | undefined, skill: string, entry: SkillActiveEntry, options?: StateWriterOptions): Promise<ActiveEntryWriteResult>;
+export declare function writeArtifact(targetPath: string, content: string, options?: StateWriterOptions): Promise<string>;
+export declare function writeReport(targetPath: string, content: string, options?: StateWriterOptions): Promise<string>;
+export declare function writeLogJsonl(targetPath: string, entry: unknown, options?: StateWriterOptions): Promise<string>;
+export declare function softDelete(targetPath: string, meta: Record<string, unknown>, options?: StateWriterOptions): Promise<string>;
+export declare function hardPruneJson(targetPaths: readonly string[], selector: HardPruneSelector, options?: StateWriterOptions): Promise<string[]>;
+export declare function hardPrune(targets: readonly GenericHardPruneTarget[], selector: GenericHardPruneSelector, options?: StateWriterOptions): Promise<string[]>;
+export declare function forceOverwrite(targetPath: string, rawValue: unknown, options?: ForceOverwriteOptions): Promise<string>;
+export declare function appendAuditEntry(cwd: string, entry: AuditEntry): Promise<string>;
+export declare function readWorkflowTransactionJournal(cwd: string, mutationId: string): Promise<WorkflowTransactionJournal | undefined>;
+export declare function beginWorkflowTransactionJournal(input: {
+    cwd: string;
+    mutationId: string;
+    caller?: CanonicalGjcWorkflowSkill;
+    callee?: CanonicalGjcWorkflowSkill;
+    paths: string[];
+}): Promise<string>;
+export declare function updateWorkflowTransactionJournal(cwd: string, mutationId: string, patch: Partial<WorkflowTransactionJournal>): Promise<string>;
+export declare function completeWorkflowTransactionJournal(cwd: string, mutationId: string): Promise<void>;