@gajae-code/coding-agent 0.5.0 → 0.5.2

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/state-writer.d.ts

@@ -1,4 +1,5 @@
-import * as fs from "node:fs/promises";
+import type { Stats } from "node:fs";
+import { type FileLockOptions } from "../config/file-lock";
 import type { SkillActiveEntry } from "../skill-state/active-state";
 import { type AuditEntry, type CanonicalGjcWorkflowSkill, type WorkflowStateMutationOwner } from "../skill-state/workflow-state-contract";
 /**
@@ -55,6 +56,12 @@ export interface StateWriterOptions {
     cwd?: string;
     receipt?: StateWriterReceiptContext;
     audit?: StateWriterAuditContext;
+    /**
+     * Cross-process lock tuning for read-modify-write paths that route through
+     * `withWorkflowStateLock` / `updateJsonAtomic`. Omit for the hardened
+     * `withFileLock` defaults.
+     */
+    lock?: FileLockOptions;
 }
 export interface DeleteIfOwnedOptions extends StateWriterOptions {
     predicate?: (current: unknown) => boolean | Promise<boolean>;
@@ -81,7 +88,7 @@ export interface GenericHardPruneTarget {
 export interface GenericHardPruneSelectorContext {
     path: string;
     category: WriterCategory | string;
-    stat: Awaited<ReturnType<typeof fs.stat>>;
+    stat: Stats;
     readJson: () => Promise<unknown>;
 }
 export type GenericHardPruneSelector = (context: GenericHardPruneSelectorContext) => boolean | Promise<boolean>;
@@ -109,8 +116,63 @@ export declare function detectWorkflowEnvelopeIntegrityMismatch(filePath: string
 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>;
+/**
+ * Serialize a read-modify-write (or any multi-step mutation) against concurrent
+ * writers of the same `.gjc/**` target. Uses the cross-process directory lock
+ * from `withFileLock`, keyed on the resolved file path, so separate CLI/agent
+ * processes (e.g. team-mode workers) cannot interleave one writer's read with
+ * another writer's write and silently drop the first mutation (issue #646).
+ *
+ * The lock is advisory: it only protects callers that route through it, so every
+ * read-modify-write of a given file MUST acquire this lock for the same resolved
+ * path. `atomicWrite`'s temp-file + rename crash-atomicity is preserved; this
+ * layers concurrency-atomicity on top without weakening it.
+ */
+export declare function withWorkflowStateLock<T>(targetPath: string, fn: () => Promise<T>, options?: StateWriterOptions): Promise<T>;
 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 interface AppendJsonlIdempotentOptions extends StateWriterOptions {
+    /**
+     * Identity key for an entry. Two entries that produce the same non-`undefined`
+     * key are duplicates, so only the first is appended. Return `undefined` to opt a
+     * candidate out of dedup (it is always appended). Use `key` for the common case
+     * where identity reduces to a single string.
+     */
+    key?: (entry: unknown) => string | undefined;
+    /**
+     * Equivalence predicate: return `true` when `existing` already represents
+     * `candidate`, suppressing the append. Use when identity cannot be reduced to a
+     * single string key. When both `key` and `equals` are supplied, `equals` wins.
+     */
+    equals?: (candidate: unknown, existing: unknown) => boolean;
+}
+export interface AppendJsonlIdempotentResult {
+    path: string;
+    /** `true` when the entry was written; `false` when an equivalent entry already existed. */
+    appended: boolean;
+    /** The pre-existing entry that suppressed the append, when `appended` is `false`. */
+    duplicate?: unknown;
+}
+/**
+ * Append `entry` to a JSONL file only when no equivalent entry already exists —
+ * the shared idempotent append primitive (issue #660).
+ *
+ * `appendJsonl` is a pure append with no dedup, so every recurring "duplicate
+ * ledger row" bug (#638, #643, #645) had to be patched with bespoke per-call-site
+ * guards. This primitive centralizes the read-check-append cycle: a caller
+ * declares identity once via `key` or `equals` instead of re-deriving the lookup
+ * at each site.
+ *
+ * The read-then-append is serialized through the same cross-process workflow lock
+ * as `updateJsonAtomic`, so two concurrent idempotent appends cannot both observe
+ * "no duplicate" and both write (the #646 TOCTOU that a plain `appendJsonl`
+ * preceded by a manual existence check is still exposed to).
+ *
+ * Scope note: this dedups the *append* only. Call sites whose idempotency must
+ * also skip a coupled mutation — e.g. the plan/state rewrite in #643/#645 — still
+ * need a whole-operation guard; this primitive is the ledger-level half of that.
+ */
+export declare function appendJsonlIdempotent(targetPath: string, entry: unknown, options: AppendJsonlIdempotentOptions): Promise<AppendJsonlIdempotentResult>;
 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>;

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,6 +273,10 @@ 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">>;

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

@@ -21,6 +21,17 @@ 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;

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/gjc-runtime/ultragoal-guard.d.ts

@@ -5,6 +5,15 @@ export interface UltragoalGuardDiagnostic {
     message: string;
     goalId?: string;
 }
+export interface UltragoalAskBlockDiagnostic {
+    active: boolean;
+    reason: string;
+    source: "absent" | "durable_state" | "durable_state_unreadable" | "ledger" | "goals_json";
+    goalsPath?: string;
+    ledgerPath?: string;
+    goalIds?: string[];
+    message: string;
+}
 export interface CurrentGoalLike {
     objective: string;
     status?: string;
@@ -19,6 +28,7 @@ export declare function readUltragoalVerificationState(input: {
     cwd: string;
     currentGoal?: CurrentGoalLike | null;
 }): Promise<UltragoalGuardDiagnostic>;
+export declare function isUltragoalAskBlocked(cwd: string): Promise<UltragoalAskBlockDiagnostic>;
 export declare function assertCanCompleteCurrentGoal(input: {
     cwd: string;
     currentGoal?: CurrentGoalLike | null;