@gajae-code/coding-agent 0.4.5 → 0.5.1

package/dist/types/gjc-runtime/deep-interview-recorder.d.ts

@@ -0,0 +1,103 @@
+import { type DeepInterviewEstablishedFact, type DeepInterviewRoundRecord, type DeepInterviewStateEnvelope, type DeepInterviewTriggerMetadata } from "./deep-interview-state";
+export * from "./deep-interview-state";
+/**
+ * Runtime-owned deep-interview round recorder (conflict-aware scoring support).
+ *
+ * Ownership boundary (per the approved consensus plan): this module owns durable
+ * round-record semantics — stable identity, append-or-merge, lifecycle, compact
+ * reads, replay detection, and the pure scored-transition validator. Callers such
+ * as the `ask` tool only resolve an answer and invoke these helpers; they never
+ * compute state paths, merge records, or write `.gjc` files directly. All writes
+ * go through the sanctioned state-writer (`writeWorkflowEnvelopeAtomic`).
+ */
+export interface DeepInterviewAnswerInput {
+    interviewId?: string;
+    round: number;
+    round_id?: string;
+    questionId?: string;
+    questionText: string;
+    component?: string;
+    dimension?: string;
+    ambiguity?: number;
+    selectedOptions?: string[];
+    customInput?: string;
+}
+export interface DeepInterviewScoringInput {
+    interviewId?: string;
+    round: number;
+    round_id?: string;
+    questionId?: string;
+    scores: Record<string, number>;
+    ambiguity: number;
+    triggers?: DeepInterviewTriggerMetadata[];
+}
+export type AppendOrMergeAction = "created" | "noop" | "replaced";
+export interface AppendOrMergeResult {
+    rounds: DeepInterviewRoundRecord[];
+    action: AppendOrMergeAction;
+    record: DeepInterviewRoundRecord;
+}
+export interface DeepInterviewCompactState {
+    threshold?: number;
+    threshold_source?: string;
+    current_ambiguity?: number;
+    topology_summary?: {
+        active: number;
+        deferred: number;
+        components: string[];
+    };
+    established_facts: DeepInterviewEstablishedFact[];
+    unresolved_triggers: DeepInterviewTriggerMetadata[];
+    recent_scored_rounds: DeepInterviewRoundRecord[];
+    pending_shells: DeepInterviewRoundRecord[];
+}
+export interface TransitionValidationResult {
+    ok: boolean;
+    violations: string[];
+}
+export declare function buildAnswerShell(input: DeepInterviewAnswerInput, now?: string): DeepInterviewRoundRecord;
+/**
+ * Append-or-merge by `round_key`. Exactly one record per key:
+ * - no existing record -> append (`created`);
+ * - identical question_hash + answer_hash -> deterministic no-op (`noop`);
+ * - same key, different hashes -> deterministic replacement of the prior shell
+ *   (`replaced`); the prior answer for that key is superseded and lifecycle resets.
+ */
+export declare function appendOrMergeRound(rounds: readonly DeepInterviewRoundRecord[], shell: DeepInterviewRoundRecord): AppendOrMergeResult;
+/**
+ * Merge scoring output into the existing record for the derived key, transitioning
+ * it to `scored`. Never appends a second record for the same key; if no shell exists
+ * yet (scoring without a prior ask), a scored record is created so data is not lost.
+ */
+export declare function enrichRoundWithScoring(rounds: readonly DeepInterviewRoundRecord[], input: DeepInterviewScoringInput, now?: string): {
+    rounds: DeepInterviewRoundRecord[];
+    record: DeepInterviewRoundRecord;
+};
+/**
+ * Bidirectional invariant: if `next` carries an `active` trigger, the affected
+ * dimension must not improve and overall ambiguity must rise vs the prior scored
+ * round. `disputed`/`unresolved` triggers are exempt but must carry a rationale.
+ */
+export declare function validateDeepInterviewScoredTransition(prior: DeepInterviewRoundRecord | undefined, next: DeepInterviewRoundRecord): TransitionValidationResult;
+/** Back-compat wrapper: normalize a deep-interview envelope to its canonical nested shape. */
+export declare function ensureDeepInterviewStateShape(value: unknown): DeepInterviewStateEnvelope;
+export declare function projectCompactState(value: unknown, options?: {
+    lastN?: number;
+}): DeepInterviewCompactState;
+/** Record an `answered` shell for one round (append-or-merge by durable key). */
+export declare function appendOrMergeDeepInterviewRound(cwd: string, statePath: string, input: DeepInterviewAnswerInput, options?: {
+    sessionId?: string;
+}): Promise<{
+    action: AppendOrMergeAction;
+    record: DeepInterviewRoundRecord;
+}>;
+/** Merge scoring output into the same round record, transitioning to `scored`. */
+export declare function enrichDeepInterviewRoundScoring(cwd: string, statePath: string, input: DeepInterviewScoringInput, options?: {
+    sessionId?: string;
+}): Promise<{
+    record: DeepInterviewRoundRecord;
+}>;
+/** Compact projection so callers read a slice instead of the full transcript. */
+export declare function readDeepInterviewStateCompact(statePath: string, options?: {
+    lastN?: number;
+}): Promise<DeepInterviewCompactState>;

package/dist/types/gjc-runtime/deep-interview-runtime.d.ts

@@ -1,3 +1,4 @@
+export * from "./deep-interview-recorder";
 /**
  * Native implementation of `gjc deep-interview`.
  *
@@ -12,6 +13,7 @@ export interface DeepInterviewCommandResult {
     stdout?: string;
     stderr?: string;
 }
+export declare function deepInterviewStatePath(cwd: string, sessionId: string | undefined): string;
 export interface ResolvedDeepInterviewSpecWriteArgs {
     stage: "final";
     slug: string;

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

@@ -0,0 +1,112 @@
+/**
+ * Pure, dependency-free foundation for deep-interview state shape.
+ *
+ * Ownership boundary (per the approved consensus plan): this leaf module owns the
+ * canonical persisted shape (interview data nested under `state`), durable round
+ * identity/hashing, lossless legacy normalization, and the deep-interview-specific
+ * envelope/round merge used by every writer (`deep-interview-recorder`,
+ * `state-runtime` write/reconcile, seed, and handoff). It MUST NOT import the
+ * active-state, state-writer, CLI runtime, or filesystem so it stays cycle-free and
+ * trivially testable.
+ */
+export type DeepInterviewRoundLifecycle = "answered" | "pending_scoring" | "scored";
+export type DeepInterviewTriggerKind = "A" | "B" | "C" | "D";
+/** `active` triggers must satisfy the bidirectional invariant; disputed/unresolved are exempt with rationale. */
+export type DeepInterviewTriggerStatus = "active" | "disputed" | "unresolved";
+export interface DeepInterviewEstablishedFact {
+    id: string;
+    statement: string;
+    round: number;
+    component?: string;
+    dimension?: string;
+    evidence?: string;
+    disputed: boolean;
+}
+export interface DeepInterviewTriggerMetadata {
+    kind: DeepInterviewTriggerKind;
+    name: string;
+    status: DeepInterviewTriggerStatus;
+    component: string;
+    dimension: string;
+    priorDimensionScore?: number;
+    newDimensionScore?: number;
+    priorAmbiguity?: number;
+    newAmbiguity?: number;
+    evidence?: string;
+    contradictedFactId?: string;
+    /** Required when status is `disputed` or `unresolved` to exempt the invariant. */
+    rationale?: string;
+}
+export interface DeepInterviewRoundRecord {
+    round_key: string;
+    round_id?: string;
+    round: number;
+    question_id?: string;
+    question_text?: string;
+    question_hash: string;
+    answer_hash: string;
+    selected_options?: string[];
+    custom_input?: string;
+    component?: string;
+    dimension?: string;
+    ambiguity_at_ask?: number;
+    lifecycle: DeepInterviewRoundLifecycle;
+    answered_at: string;
+    scored_at?: string;
+    scores?: Record<string, number>;
+    ambiguity?: number;
+    triggers?: DeepInterviewTriggerMetadata[];
+}
+export interface DeepInterviewStateEnvelope {
+    threshold?: number;
+    threshold_source?: string;
+    state?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export declare function hashContent(value: string): string;
+export declare function questionHash(questionText: string): string;
+export declare function answerHash(selectedOptions: string[] | undefined, customInput: string | undefined): string;
+/**
+ * Durable round identity. Prefer `interview_id + round_id`; fall back to
+ * `interview_id + round + question.id` when no caller-supplied `round_id` exists.
+ */
+export declare function deriveRoundKey(interviewId: string | undefined, input: {
+    round_id?: string;
+    round: number;
+    questionId?: string;
+}): string;
+/**
+ * Canonicalize a deep-interview envelope: interview data nested under `state`,
+ * legacy flattened fields hoisted in losslessly, transcript duplicates removed
+ * from the top level, and `rounds`/`established_facts` guaranteed to be arrays.
+ *
+ * Idempotent: a canonical envelope is returned unchanged in shape. Never deletes
+ * unknown envelope or nested fields, and never mutates the input.
+ */
+export declare function normalizeDeepInterviewEnvelope(value: unknown): DeepInterviewStateEnvelope;
+/**
+ * Lossless, idempotent merge of two round arrays.
+ *
+ * - Records sharing a durable key (`round_key`, or synthesized from
+ *   `round_id`/`question_id`) merge into one, preferring scored over answered.
+ * - Records without any durable identity are preserved verbatim; an exact
+ *   duplicate is skipped so repeated writes stay idempotent, but distinct records
+ *   are never collapsed.
+ *
+ * Deliberate refinement of the approved plan: rather than mutating opaque legacy
+ * records with synthetic `legacy:<index>` keys, they are preserved verbatim with
+ * exact-duplicate dedupe. This satisfies the plan's intent (lossless, idempotent,
+ * never collapse distinct rounds) without rewriting user-supplied round objects,
+ * and keeps free-form extension preservation intact. Recorder-produced records
+ * always carry a `round_key`, so the synthetic path is unnecessary in practice.
+ */
+export declare function mergeDeepInterviewRounds(existing: readonly Record<string, unknown>[], incoming: readonly Record<string, unknown>[]): Record<string, unknown>[];
+/**
+ * Deep-interview-specific envelope merge. Unlike the generic shallow null-delete
+ * merge, this keeps interview data nested under `state`, never deletes `state`,
+ * and merges `rounds` losslessly by durable key so a partial write (e.g. a
+ * scoring update) cannot drop recorder-written transcript history.
+ */
+export declare function mergeDeepInterviewEnvelope(existing: unknown, incoming: unknown, options?: {
+    replace?: boolean;
+}): DeepInterviewStateEnvelope;

package/dist/types/gjc-runtime/gc-render.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Text rendering for `gjc gc` reports. JSON output is produced directly in
+ * `gc-runtime.ts`; this module owns the human-readable grouped report.
+ */
+import type { GcReport } from "./gc-runtime";
+export declare function buildGcReportText(report: GcReport): string;

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

@@ -0,0 +1,134 @@
+/**
+ * `gjc gc` runtime — a global, liveness-only, dry-run-by-default garbage
+ * collector for stale GJC session/PID records.
+ *
+ * Design (see .gjc/plans/ralplan/2026-06-13-1347-954f/pending-approval.md):
+ * - This module is an ORCHESTRATOR only. It owns the shared PID probe, the
+ *   report/exit-code policy, and text/JSON rendering. It must NOT parse private
+ *   store layouts directly; every store is reached through an injectable
+ *   `GcStoreAdapter` that lives next to its store owner.
+ * - Liveness-only and fail-closed: only `ESRCH` (no such process) is `dead`
+ *   (removable). `process.kill(pid, 0)` success, `EPERM`, and any unknown probe
+ *   error all mean KEEP — a live process is never signalled or killed.
+ * - Dry-run by default: nothing is deleted unless `--prune`/`--force`.
+ */
+export type GcStore = "harness_leases" | "team_workers" | "file_locks" | "tmux_sessions" | "registry_entries";
+export declare const GC_STORES: readonly GcStore[];
+/** Why a probed pid is kept instead of treated as dead. */
+export type GcPidKeepReason = "alive" | "eperm" | "unknown";
+export interface GcPidProbeResult {
+    /** `dead` only on ESRCH; `keep` for alive/eperm/unknown (fail-closed). */
+    status: "dead" | "keep";
+    reason?: GcPidKeepReason;
+    error?: string;
+}
+/** Single shared liveness contract threaded through every classifier + prune path. */
+export type GcPidProbe = (pid: number) => GcPidProbeResult;
+export type GcPidStatus = "dead" | "alive" | "eperm" | "unknown" | "none";
+export type GcAction = "none" | "would_remove" | "removed" | "remove_failed" | "skipped";
+export interface GcRecord {
+    store: GcStore;
+    /** Stable identifier: session id, lock dir path, worker id, tmux name, registry session id. */
+    id: string;
+    path?: string;
+    root?: string;
+    pid?: number;
+    pid_status?: GcPidStatus;
+    /** Store-specific classification label (e.g. "dead", "live", "unclassified", "terminal_lifecycle"). */
+    status: string;
+    stale: boolean;
+    removable: boolean;
+    action: GcAction;
+    reason: string;
+    detail?: string;
+    error?: string;
+    removed?: boolean;
+}
+export interface GcError {
+    store: GcStore;
+    scope: string;
+    message: string;
+}
+export interface GcCollectResult {
+    records: GcRecord[];
+    errors: GcError[];
+}
+export interface GcPruneOutcome {
+    removed: boolean;
+    error?: string;
+    /** Set when a removable record was skipped at prune time (e.g. TOCTOU became live). */
+    skipped?: string;
+}
+export interface GcContext {
+    probe: GcPidProbe;
+    force: boolean;
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+}
+/**
+ * A store-owned GC adapter. `collect` discovers + classifies (using the shared
+ * probe) without mutating anything. `prune` removes a single record, and MUST
+ * re-validate / re-probe immediately before any destructive action.
+ */
+export interface GcStoreAdapter {
+    store: GcStore;
+    collect(ctx: GcContext): Promise<GcCollectResult>;
+    prune(record: GcRecord, ctx: GcContext): Promise<GcPruneOutcome>;
+}
+export interface GcCounts {
+    discovered: number;
+    stale: number;
+    alive: number;
+    eperm: number;
+    unknown: number;
+    terminal_lifecycle: number;
+    unclassified: number;
+    would_remove: number;
+    removed: number;
+    failed: number;
+    errors: number;
+    by_store: Record<GcStore, {
+        discovered: number;
+        stale: number;
+        would_remove: number;
+        removed: number;
+        failed: number;
+    }>;
+}
+export interface GcReport {
+    dry_run: boolean;
+    stores: Record<GcStore, GcRecord[]>;
+    counts: GcCounts;
+    errors: GcError[];
+}
+export interface GcRunResult {
+    stdout: string;
+    stderr: string;
+    status: number;
+}
+/**
+ * The shared, fail-closed PID probe. ESRCH => dead/removable; success => alive;
+ * EPERM => kept (owned by another user); any other error => kept as unknown.
+ */
+export declare const gcPidProbe: GcPidProbe;
+/** Map a `GcPidProbe` onto the harness lease probe shape (`"alive"|"dead"|"eperm"`). */
+export declare function gcProbeToLeasePidStatus(probe: GcPidProbe): (pid: number) => "alive" | "dead" | "eperm";
+/** Translate a probe result into a record-friendly pid status label. */
+export declare function gcPidStatusLabel(result: GcPidProbeResult): Exclude<GcPidStatus, "none">;
+/**
+ * Collect every store's records (catching hard discovery errors per adapter),
+ * then optionally prune removable records with per-record revalidation.
+ */
+export declare function collectGcReport(adapters: GcStoreAdapter[], ctx: GcContext, prune: boolean): Promise<GcReport>;
+/**
+ * Exit-code policy:
+ * - usage/parse error => 2
+ * - hard discovery errors => 1 (both modes)
+ * - prune mode with a failed intended removal => 1
+ * - otherwise => 0
+ */
+export declare function computeExitCode(report: GcReport): number;
+export declare function runGjcGcCommand(argv: string[], cwd?: string, env?: NodeJS.ProcessEnv, adapters?: GcStoreAdapter[]): Promise<GcRunResult>;
+export declare function gcHelpText(): string;
+/** Lazily assemble the real store adapters (kept lazy to avoid import cycles). */
+export declare function defaultGcAdapters(): Promise<GcStoreAdapter[]>;

package/dist/types/gjc-runtime/ledger-event-renderer.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Pure parse + summarize for ledger-backed skill observability.
+ *
+ * Workflow progress for ultragoal/ralplan cannot be observed via subagent tool
+ * events (those skills persist through `bash`-backed `gjc` CLI calls whose tool
+ * `details` carry no structured payload). The durable source of truth is the
+ * append-only ledgers:
+ *   - ultragoal: `.gjc/ultragoal/ledger.jsonl`
+ *   - ralplan:   `.gjc/plans/ralplan/<run-id>/index.jsonl`
+ *
+ * This module is I/O-free: callers read the files and pass lines or already-parsed
+ * rows. It feeds the compact HUD chip builders in `skill-state/workflow-hud.ts`
+ * via the runtime sync paths. Display-string helpers stay theme-free.
+ */
+/** Minimal projection of an ultragoal ledger row used for the HUD chip. */
+export interface UltragoalLedgerEventLite {
+    /** Normalized from the row's `event` field, or `type` for reconcile rows. */
+    event: string;
+    goalId?: string;
+    status?: string;
+    timestamp?: string;
+}
+/**
+ * Coerce an already-parsed ledger row into the lite shape. Accepts both the
+ * `event`-keyed vocabulary (plan_created, goal_started, goal_checkpointed,
+ * steering_accepted/rejected, review_blockers_recorded) and the `type`-keyed
+ * reconcile-failure row (`type: "reconcile_failed"`). Returns undefined when no
+ * event/type discriminator is present.
+ */
+export declare function coerceUltragoalLedgerEvent(row: Record<string, unknown>): UltragoalLedgerEventLite | undefined;
+/** Parse a single ultragoal ledger JSONL line; undefined for blank/malformed lines. */
+export declare function parseUltragoalLedgerLine(line: string): UltragoalLedgerEventLite | undefined;
+/** The most recent event, or undefined when the ledger is empty. */
+export declare function latestUltragoalLedgerEvent(events: readonly UltragoalLedgerEventLite[]): UltragoalLedgerEventLite | undefined;
+/**
+ * Best-effort latest event from raw ledger text: parses line-by-line and skips
+ * blank/malformed rows so a torn or hand-edited ledger never throws on the HUD
+ * path. Strict receipt consumers should keep using the validating reader.
+ */
+export declare function latestUltragoalLedgerEventFromText(text: string): UltragoalLedgerEventLite | undefined;
+/** Minimal projection of a ralplan `index.jsonl` row. */
+export interface RalplanIndexRow {
+    stage: string;
+    stageN?: number;
+}
+/** Parse a single ralplan index JSONL line; undefined for blank/malformed lines. */
+export declare function parseRalplanIndexLine(line: string): RalplanIndexRow | undefined;
+export interface RalplanIndexSummary {
+    /** Number of consensus iterations (planner/revision boundaries), >= 0. */
+    iteration: number;
+    /** Stage names present in the current (latest) iteration, in append order. */
+    currentStages: string[];
+}
+/**
+ * Derive iteration count and current-iteration stage presence from index rows.
+ *
+ * `stage_n` is NOT used as the iteration key: it is stored verbatim per row and a
+ * single planner/architect/critic pass can span multiple stage_n values. Instead,
+ * a `planner` or `revision` row opens a new iteration and subsequent rows attach
+ * to it. No verdict is derived here (index rows carry none).
+ */
+export declare function summarizeRalplanIndex(rows: readonly RalplanIndexRow[]): RalplanIndexSummary;
+/**
+ * Compact, theme-free presence string for the ralplan `stages` chip, e.g.
+ * `P·A·C`. Collapses past `cap` with a "… N more" suffix. Returns undefined when
+ * there are no stages.
+ */
+export declare function formatRalplanStagePresence(stages: readonly string[], cap?: number): string | undefined;

package/dist/types/gjc-runtime/team-gc.d.ts

@@ -0,0 +1,7 @@
+/**
+ * GC adapter for team workers (`.gjc/state/team/<name>/workers/<id>/` heartbeat
+ * + lifecycle). Liveness-only: numeric PID status dominates lifecycle/heartbeat
+ * signals.
+ */
+import type { GcStoreAdapter } from "./gc-runtime";
+export declare const teamWorkersGcAdapter: GcStoreAdapter;

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

@@ -1,4 +1,5 @@
 import type { WorkflowHudSummary } from "../skill-state/active-state";
+import type { GcPidProbe, GcRecord } from "./gc-runtime";
 export type GjcTeamPhase = "starting" | "running" | "awaiting_integration" | "complete" | "failed" | "cancelled";
 export type GjcTeamTaskStatus = "pending" | "blocked" | "in_progress" | "completed" | "failed";
 export type GjcWorkerStatusState = "idle" | "working" | "blocked" | "done" | "failed" | "draining" | "unknown";
@@ -272,10 +273,13 @@ export interface GjcWorkerIntegrationAttemptRequestResult {
 }
 export declare const GJC_TEAM_API_OPERATIONS: readonly ["send-message", "broadcast", "mailbox-list", "mailbox-mark-delivered", "mailbox-mark-notified", "notification-list", "notification-read", "notification-replay", "notification-mark-pane-attempt", "worker-startup-ack", "create-task", "read-task", "list-tasks", "update-task", "claim-task", "transition-task-status", "transition-task", "release-task-claim", "read-config", "read-manifest", "read-worker-status", "update-worker-status", "read-worker-heartbeat", "recover-stale-claims", "update-worker-heartbeat", "write-worker-inbox", "write-worker-identity", "append-event", "read-events", "read-traces", "await-event", "write-shutdown-request", "read-shutdown-ack", "read-monitor-snapshot", "write-monitor-snapshot", "read-task-approval", "write-task-approval"];
 export declare function resolveGjcTeamStateRoot(cwd?: string, env?: NodeJS.ProcessEnv): string;
+/** @internal */
+export declare function listTeamWorkerGcRecords(teamRoot: string, probe: GcPidProbe): Promise<GcRecord[]>;
+/** @internal */
+export declare function pruneTeamWorkerGcRecord(record: GcRecord, probe: GcPidProbe): Promise<boolean>;
 export declare function persistGjcTeamModeStateSummary(snapshot: GjcTeamSnapshot, cwd?: string): Promise<void>;
 export declare function recoverGjcTeamStaleClaims(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamLivenessRecoveryResult>;
 type GjcTeamTaskMetadataInput = Partial<Pick<GjcTeamTask, "owner" | "lane" | "required_role" | "allowed_roles" | "depends_on" | "blocked_by">>;
-export declare function resolveGjcTmuxCommand(env?: NodeJS.ProcessEnv): string;
 export declare function resolveGjcWorkerCommand(cwd?: string, env?: NodeJS.ProcessEnv): string;
 export type GjcWorkerCheckpointClassification = {
     kind: "clean";

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

@@ -21,6 +21,20 @@ export interface TmuxCommandResult {
 export type TmuxCommandRunner = (args: string[]) => TmuxCommandResult;
 export declare function envDisabled(value: string | undefined): boolean;
 export declare function resolveGjcTmuxCommand(env?: NodeJS.ProcessEnv): string;
+/**
+ * Build the exact-session target for tmux *option* commands
+ * (`show-options` / `set-option`) and `display-message -t`.
+ *
+ * Session-scoped commands such as `kill-session` / `attach-session` resolve a
+ * bare exact target (`=NAME`), but tmux 3.6a refuses to resolve a bare `=NAME`
+ * for option/display commands. Appending the empty window separator (`=NAME:`)
+ * keeps the exact-session match while giving tmux the window-qualified target
+ * those commands require. See gajae-code#580.
+ */
+export declare function buildGjcTmuxExactOptionTarget(sessionName: string): string;
+export declare const GJC_TMUX_UNTAGGED_REASON = "gjc_tmux_session_untagged";
+export declare function buildGjcTmuxUntaggedSessionHint(tmuxCommand: string): string;
+export declare function buildGjcTmuxUntaggedSessionError(sessionName: string, tmuxCommand: string): string;
 export declare function sanitizeTmuxToken(value: string): string;
 export declare function buildGjcTmuxSessionSlug(value: string): string;
 export declare function buildGjcTmuxSessionName(env?: NodeJS.ProcessEnv, context?: {

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

@@ -0,0 +1,7 @@
+/**
+ * GC adapter for gjc-tagged tmux sessions. Stale iff `@gjc-project` path is gone
+ * OR `@gjc-branch` has no live git worktree. Removal is a spec-authorized
+ * destructive `kill-session`, gated by exact-target re-read + revalidation.
+ */
+import type { GcStoreAdapter } from "./gc-runtime";
+export declare const tmuxSessionsGcAdapter: GcStoreAdapter;

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

@@ -9,9 +9,22 @@ export interface GjcTmuxSessionStatus {
     branchSlug?: string;
     project?: string;
 }
+export interface GjcTmuxSessionTagsForGc {
+    profile?: string;
+    project?: string;
+    branch?: string;
+}
+export interface GjcTmuxSessionsForGc {
+    tagged: GjcTmuxSessionStatus[];
+    untagged: string[];
+}
 export declare function listGjcTmuxSessions(env?: NodeJS.ProcessEnv): GjcTmuxSessionStatus[];
+/** @internal */
+export declare function listTmuxSessionsForGc(env?: NodeJS.ProcessEnv): GjcTmuxSessionsForGc;
 export declare function findGjcTmuxSessionByBranch(branch: string, env?: NodeJS.ProcessEnv, project?: string | null): GjcTmuxSessionStatus | undefined;
 export declare function statusGjcTmuxSession(sessionName: string, env?: NodeJS.ProcessEnv): GjcTmuxSessionStatus;
 export declare function createGjcTmuxSession(env?: NodeJS.ProcessEnv): GjcTmuxSessionStatus;
+/** @internal */
+export declare function readTmuxSessionTagsForGc(sessionName: string, env?: NodeJS.ProcessEnv): GjcTmuxSessionTagsForGc;
 export declare function removeGjcTmuxSession(sessionName: string, env?: NodeJS.ProcessEnv): GjcTmuxSessionStatus;
 export declare function attachGjcTmuxSession(sessionName: string, env?: NodeJS.ProcessEnv): never;

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

@@ -0,0 +1,3 @@
+import { type GcStoreAdapter } from "../gjc-runtime/gc-runtime";
+export declare const harnessLeasesGcAdapter: GcStoreAdapter;
+export declare const registryEntriesGcAdapter: GcStoreAdapter;

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

@@ -11,7 +11,7 @@
  * Stateless `gjc harness` CLI calls reach the owner via {@link resolveOwner} + the endpoint.
  */
 import { type FinalizeChecks, type ValidationCommandSpec } from "./finalize";
-import type { HarnessRpc } from "./rpc-adapter";
+import { type HarnessRpc } from "./rpc-adapter";
 import { type SessionLease } from "./session-lease";
 export interface OwnerOptions {
     root: string;
@@ -44,3 +44,10 @@ export interface ResolvedOwner {
 }
 /** Determine whether a live owner currently holds the session (for CLI routing). */
 export declare function resolveOwner(root: string, sessionId: string): Promise<ResolvedOwner>;
+/**
+ * Owner liveness for verbs that do not route to the owner (e.g. `classify`): a routable owner
+ * has a live lease and a socket endpoint. This is the same lease/socket probe `observe` uses to
+ * decide routing, so non-routing verbs derive `ownerLive` consistently instead of assuming the
+ * owner is gone (which would misclassify a live owner as vanished/restart-clean).
+ */
+export declare function resolveOwnerLive(root: string, sessionId: string): Promise<boolean>;

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

@@ -0,0 +1,19 @@
+import type { ReceiptEnvelope } from "./receipts";
+export declare const RECEIPT_SPOOL_DIR_ENV = "GJC_RECEIPT_SPOOL_DIR";
+export declare const RECEIPT_SPOOL_FILENAME = "spool.jsonl";
+export declare const RECEIPT_SPOOL_CURSOR_WIDTH = 12;
+export interface ReceiptSpoolRecord {
+    cursor: string;
+    envelope: ReceiptEnvelope<unknown>;
+}
+export interface ReceiptSpoolAppendResult {
+    cursor: string;
+    path: string;
+}
+export declare function withReceiptSpoolDir<T>(spoolDir: string, fn: () => Promise<T>): Promise<T>;
+export declare function resolveReceiptSpoolDir(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function receiptSpoolPath(spoolDir: string): string;
+export declare function formatReceiptSpoolCursor(cursor: bigint): string;
+export declare function readHighestReceiptSpoolCursor(spoolDir: string): Promise<bigint>;
+export declare function appendReceiptToSpool(spoolDir: string, envelope: ReceiptEnvelope<unknown>): Promise<ReceiptSpoolAppendResult>;
+export declare function appendReceiptToConfiguredSpool(envelope: ReceiptEnvelope<unknown>, env?: NodeJS.ProcessEnv): Promise<ReceiptSpoolAppendResult | undefined>;

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

@@ -9,11 +9,16 @@ import type { HarnessLifecycle, NextAllowedAction, PrimitiveResponse, SessionSta
 export declare function isTerminal(lifecycle: HarnessLifecycle): boolean;
 export declare function canTransition(from: HarnessLifecycle, to: HarnessLifecycle): boolean;
 export declare function assertTransition(from: HarnessLifecycle, to: HarnessLifecycle): void;
+export interface NextAllowedActionsOptions {
+    /** Additional live-owner/RPC readiness gate for submit, e.g. rpc-not-idle. */
+    submitUnavailableReason?: string | null;
+}
+export declare function submitUnavailableReason(lifecycle: HarnessLifecycle, ownerLive: boolean, gateReason?: string | null): string | null;
 /**
  * Derive the permitted next actions for a session given its lifecycle and whether
  * a live owner currently holds the lease.
  */
-export declare function nextAllowedActions(lifecycle: HarnessLifecycle, ownerLive: boolean): NextAllowedAction[];
+export declare function nextAllowedActions(lifecycle: HarnessLifecycle, ownerLive: boolean, options?: NextAllowedActionsOptions): NextAllowedAction[];
 export declare function buildStateView(state: SessionState, ownerLive: boolean): SessionStateView;
 /** Build the universal contract response carried by every primitive. */
 export declare function buildResponse<E extends Record<string, unknown>>(state: SessionState, ownerLive: boolean, evidence: E, ok?: boolean): PrimitiveResponse<E>;

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

@@ -1,8 +1,28 @@
 import type { EventEnvelope, ReceiptFamily, SessionState } from "./types";
+interface HarnessRootRegistryEntry {
+    root: string;
+    updatedAt: string;
+}
+export interface HarnessRootRegistryForGc {
+    sessionId: string;
+    roots: HarnessRootRegistryEntry[];
+}
+export interface HarnessRootRegistryListingForGc {
+    sessionId: string;
+    file: string;
+    roots: HarnessRootRegistryEntry[];
+    error?: string;
+}
 interface ResolveHarnessSessionRootOptions {
     expectedWorkspace?: string;
 }
 export declare function canonicalWorkspacePath(workspace: string): string;
+/** @internal */
+export declare function listHarnessRootRegistriesForGc(env?: NodeJS.ProcessEnv): Promise<HarnessRootRegistryListingForGc[]>;
+/** @internal */
+export declare function rewriteHarnessRootRegistryForGc(file: string, registry: HarnessRootRegistryForGc): Promise<void>;
+/** @internal */
+export declare function removeHarnessRootRegistryFileForGc(file: string): Promise<void>;
 export declare const MAX_UNIX_SOCKET_PATH_BYTES = 100;
 export declare function controlSocketPath(root: string, sessionId: string, env?: NodeJS.ProcessEnv): string;
 export declare class StorageError extends Error {

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

@@ -138,6 +138,10 @@ export interface Observation {
     rpcLive?: boolean;
     /** ISO timestamp of the most recent RPC frame the owner observed, if any. */
     rpcLastFrameAt?: string | null;
+    /** True only when owner/rpc/lifecycle gates indicate a prompt can be submitted now. */
+    readyForSubmit?: boolean;
+    /** Present when readyForSubmit is false; mirrors submit's nextAllowedActions reason. */
+    submitUnavailableReason?: string | null;
 }
 /** Input to the deterministic recovery classifier. */
 export interface ClassifyInput {

package/dist/types/hindsight/mental-models.d.ts

@@ -108,12 +108,12 @@ export declare function summarizeMentalModel(model: MentalModelSummary): string;
  * snapshot only; the diff is computed locally for display purposes.
  *
  * This is intentionally minimal — for "what changed" at a glance, not for a
- * full structural diff. Each side is capped at `MAX_LCS_LINES` lines BEFORE
- * the O(n*m) LCS table is built so a long curated model can never hang the
- * TUI; output is then capped at `maxLines` so the rendered diff stays
- * readable. The cap is signalled inline.
+ * full structural diff. Each side is capped at `MAX_LCS_LINES` lines before
+ * the Hunt-Szymanski LCS pass so a long curated model can never hang the TUI;
+ * output is then capped at `maxLines` so the rendered diff stays readable. The
+ * cap is signalled inline.
  */
-/** Hard cap on input line count per side before LCS. Keeps the O(n*m) table tractable. */
+/** Hard cap on input line count per side before LCS. Keeps worst-case repeated-line matching bounded. */
 export declare const MAX_LCS_LINES = 1000;
 export declare function diffMentalModelContent(previous: string | null, current: string, maxLines?: number): string;
 /** Awaited only by the first-turn race in `beforeAgentStartPrompt`. */