@gajae-code/coding-agent 0.6.4 → 0.7.0

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

@@ -13,12 +13,12 @@ export interface DeepInterviewCommandResult {
     stdout?: string;
     stderr?: string;
 }
-export declare function deepInterviewStatePath(cwd: string, sessionId: string | undefined): string;
+export declare function deepInterviewStatePath(cwd: string, sessionId?: string): string;
 export interface ResolvedDeepInterviewSpecWriteArgs {
     stage: "final";
     slug: string;
     spec: string;
-    sessionId?: string;
+    sessionId: string;
     json: boolean;
     deliberate: boolean;
     handoff?: "ralplan";

package/dist/types/gjc-runtime/goal-mode-request.d.ts

@@ -30,7 +30,7 @@ export type CurrentSessionGoalModeWriteResult = {
     sessionFile: string;
 };
 export declare function isUltragoalCreateGoalsInvocation(args: readonly string[]): boolean;
-export declare function readUltragoalGjcObjective(cwd: string): Promise<{
+export declare function readUltragoalGjcObjective(cwd: string, sessionId?: string | null): Promise<{
     objective: string;
     goalsPath: string;
 }>;

package/dist/types/gjc-runtime/session-layout.d.ts

@@ -0,0 +1,59 @@
+export declare const GJC_DIR = ".gjc";
+export declare const GJC_SESSION_PREFIX = "_session-";
+export declare const GJC_SESSION_ACTIVITY_FILE = ".session-activity.json";
+/** Source that produced a resolved GJC session id, for audit/diagnostics. */
+export type GjcSessionSource = "flag" | "payload" | "env" | "latest";
+export interface GjcSessionContext {
+    gjcSessionId: string;
+    sessionRoot: string;
+    source: GjcSessionSource;
+}
+/**
+ * Encode a session id into a single safe path segment. Matches the historical
+ * encoding used across the runtimes so ids round-trip identically:
+ * `encodeURIComponent` plus dot-escaping (dots are legal in filenames but we
+ * avoid `.`/`..` traversal ambiguity).
+ */
+export declare function encodeSessionSegment(value: string): string;
+/** Inverse of {@link encodeSessionSegment}. */
+export declare function decodeSessionSegment(segment: string): string;
+/** Throw when a session id is missing or blank; never let blank suppress callers. */
+export declare function assertNonEmptyGjcSessionId(value: string | undefined, source: string): asserts value is string;
+/**
+ * Assert a value is safe to use as a single path segment: non-blank and free of
+ * path separators or `.`/`..` traversal. Use for already-safe identifiers
+ * (skill modes, slugs) where we want identical filenames but fail closed on
+ * traversal rather than silently normalizing out of the intended directory.
+ */
+export declare function assertSafePathComponent(value: string, label: string): void;
+/** The shared `.gjc/` root (holds shared config; never session-scoped). */
+export declare function gjcRoot(cwd: string): string;
+/** The per-session root directory: `<cwd>/.gjc/_session-{encodedId}`. */
+export declare function sessionRoot(cwd: string, gjcSessionId: string): string;
+/** Directory name (no path) for a session id, e.g. `_session-abc`. */
+export declare function sessionDirName(gjcSessionId: string): string;
+/** Return the decoded session id for a `_session-*` directory name, else undefined. */
+export declare function sessionIdFromDirName(name: string): string | undefined;
+/** Authoritative per-session activity marker path. */
+export declare function sessionActivityPath(cwd: string, gjcSessionId: string): string;
+export declare function sessionStateDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionSpecsDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionPlansDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionUltragoalDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionAuditDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionReportsDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionLogsDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionRuntimeDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionRlmDir(cwd: string, gjcSessionId: string): string;
+export declare function activeStateDir(cwd: string, gjcSessionId: string): string;
+export declare function activeSnapshotPath(cwd: string, gjcSessionId: string): string;
+export declare function activeEntryPath(cwd: string, gjcSessionId: string, skill: string): string;
+export declare function modeStatePath(cwd: string, gjcSessionId: string, mode: string): string;
+export declare function auditPath(cwd: string, gjcSessionId: string): string;
+export declare function transactionJournalPath(cwd: string, gjcSessionId: string, mutationId: string): string;
+export declare function teamStateRoot(cwd: string, gjcSessionId: string): string;
+export declare function workflowGatePath(cwd: string, gjcSessionId: string, gateId: string): string;
+export declare function harnessStateRoot(cwd: string, gjcSessionId: string): string;
+export declare function coordinatorMcpStateRoot(cwd: string, gjcSessionId: string): string;
+export declare function tmuxRuntimeSessionPath(cwd: string, gjcSessionId: string, slug: string): string;
+export declare function rlmArtifactRoot(cwd: string, gjcSessionId: string, rlmSessionId: string): string;

package/dist/types/gjc-runtime/session-resolution.d.ts

@@ -0,0 +1,47 @@
+import { type GjcSessionContext, type GjcSessionSource } from "./session-layout";
+/** Window within which two activity timestamps are treated as an ambiguous tie. */
+export declare const LATEST_SESSION_TIE_WINDOW_MS = 1000;
+export interface SessionIdSources {
+    /** Raw `--session-id` value: `undefined` = flag absent; `""` = present-but-blank (invalid). */
+    flagValue?: string | undefined;
+    payloadSessionId?: unknown;
+    envSessionId?: string | undefined;
+}
+export declare class SessionResolutionError extends Error {
+    readonly code: "blank_flag" | "no_session" | "ambiguous" | "missing_for_write";
+    constructor(message: string, code: "blank_flag" | "no_session" | "ambiguous" | "missing_for_write");
+}
+interface ResolvedFromSources {
+    gjcSessionId: string;
+    source: GjcSessionSource;
+}
+/**
+ * Resolve a session id from explicit sources only (flag -> payload -> env).
+ * Returns `undefined` when none is present. A blank explicit flag throws.
+ */
+export declare function resolveSessionIdFromSources(sources: SessionIdSources): ResolvedFromSources | undefined;
+/** Resolve session context for a WRITE command. Errors when no explicit id is present. */
+export declare function resolveGjcSessionForWrite(cwd: string, sources: SessionIdSources): GjcSessionContext;
+/**
+ * Resolve session context for a READ/STATUS/CLEAR command. Falls back to the
+ * latest active session by activity marker when no explicit id is present.
+ */
+export declare function resolveGjcSessionForRead(cwd: string, sources: SessionIdSources): Promise<GjcSessionContext>;
+/**
+ * Scan `.gjc/_session-*` directories and select the most-recently-active one by
+ * its activity marker. Never uses raw directory mtime. Throws on zero candidates
+ * or an ambiguous tie.
+ */
+export declare function detectLatestSession(cwd: string): Promise<GjcSessionContext>;
+export interface ActivityMarkerInfo {
+    writer: string;
+    /** Relative generated path that was just written, for diagnostics. */
+    path?: string;
+}
+/**
+ * Best-effort write of the per-session activity marker. State-command callers
+ * MUST treat a thrown error as a command failure (auto-detect depends on it);
+ * non-critical writers may swallow it.
+ */
+export declare function writeSessionActivityMarker(cwd: string, gjcSessionId: string, info: ActivityMarkerInfo): Promise<void>;
+export {};

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

@@ -1,4 +1,4 @@
-import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import { type CanonicalGjcWorkflowSkill } from "../skill-state/canonical-skills";
 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-runtime.d.ts

@@ -2,9 +2,9 @@ import { type CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
 /**
  * Native implementation of the `gjc state read|write|clear` command surface.
  *
- * Simple file-receipt operations against `.gjc/state/[sessions/<id>/]<mode>-state.json` and
- * `.gjc/state/[sessions/<id>/]skill-active-state.json`. This is the sanctioned CLI mediator for
- * the mutation-guarded `.gjc/state` ACL — agents call it instead of editing those files directly.
+ * Simple file-receipt operations against session-scoped state under
+ * `.gjc/_session-{id}/state/`. This is the sanctioned CLI mediator for
+ * mutation-guarded GJC state — agents call it instead of editing those files directly.
  */
 export interface StateCommandResult {
     status: number;
@@ -24,12 +24,13 @@ export interface StateCommandResult {
 export declare function reconcileWorkflowSkillState(options: {
     cwd: string;
     mode: CanonicalGjcWorkflowSkill;
-    sessionId: string | undefined;
+    sessionId?: string;
     threadId?: string;
     turnId?: string;
     active: boolean;
     phase: string;
     payload: Record<string, unknown>;
+    sourceRevision?: number;
 }): Promise<{
     stateFile: string;
 }>;

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

@@ -84,6 +84,7 @@ export declare const WorkflowStateEnvelopeSchema: z.ZodObject<{
             computed_at: z.ZodString;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
+    state_revision: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
 /**
  * Strict receipt required on WRITE (post checksum-stamping). Anchored to the
@@ -164,6 +165,7 @@ export declare const RequiredOnWriteEnvelopeSchema: z.ZodObject<{
             computed_at: z.ZodString;
         }, z.core.$loose>;
     }, z.core.$loose>;
+    state_revision: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
 /** Per-skill mode state consumed by hooks / the mutation guard. */
 export declare const ModeStateSchema: z.ZodObject<{

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

@@ -11,7 +11,7 @@ import { type AuditEntry, type CanonicalGjcWorkflowSkill, type WorkflowStateMuta
  * 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/`;
+ * Transaction journals are per mutation id under the session state transactions directory;
  * they are recovery evidence only, never global locks or waiters, so stale
  * journals do not block unrelated state reads or writes.
  */
@@ -24,9 +24,14 @@ export interface StateWriterReceiptContext {
     sessionId?: string;
     mutationId?: string;
     nowIso?: string;
+    verb?: string;
+    fromPhase?: string;
+    toPhase?: string;
+    forced?: boolean;
 }
 export interface StateWriterAuditContext {
     cwd?: string;
+    sessionId?: string;
     category: WriterCategory;
     verb: string;
     owner: WorkflowStateMutationOwner;
@@ -52,10 +57,27 @@ export interface WorkflowTransactionJournal {
     paths: string[];
     steps: string[];
 }
+export type StateWritePolicy = "source" | "cache";
+export interface GuardedStateWriterOptions extends StateWriterOptions {
+    policy: StateWritePolicy;
+    expectedRevision?: number;
+    sourceRevision?: number;
+}
+export type GuardedWriteResult = {
+    path: string;
+    written: true;
+    revision: number;
+} | {
+    path: string;
+    written: false;
+    reason: "stale-skip";
+    revision: number;
+};
 export interface StateWriterOptions {
     cwd?: string;
     receipt?: StateWriterReceiptContext;
     audit?: StateWriterAuditContext;
+    sourceRevision?: number;
     /**
      * Cross-process lock tuning for read-modify-write paths that route through
      * `withWorkflowStateLock` / `updateJsonAtomic`. Omit for the hardened
@@ -63,6 +85,12 @@ export interface StateWriterOptions {
      */
     lock?: FileLockOptions;
 }
+export declare class StateWriteConflictError extends Error {
+    readonly path: string;
+    readonly expectedRevision: number;
+    readonly persistedRevision: number;
+    constructor(path: string, expectedRevision: number, persistedRevision: number);
+}
 export interface DeleteIfOwnedOptions extends StateWriterOptions {
     predicate?: (current: unknown) => boolean | Promise<boolean>;
 }
@@ -113,6 +141,9 @@ export declare function readExistingStateForMutation(filePath: string): Promise<
 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 persistedStateRevision(value: unknown): number;
+export declare function writeGuardedJsonAtomic(targetPath: string, value: unknown, options: GuardedStateWriterOptions): Promise<GuardedWriteResult>;
+export declare function writeGuardedWorkflowEnvelopeAtomic(targetPath: string, value: unknown, options: GuardedStateWriterOptions): Promise<GuardedWriteResult>;
 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>;
@@ -178,8 +209,7 @@ export declare function createJsonNoClobber(targetPath: string, value: unknown,
 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
+ * Active entry files under `.gjc/_session-{id}/state/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.
@@ -196,14 +226,15 @@ export declare function softDelete(targetPath: string, meta: Record<string, unkn
 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 appendAuditEntry(cwd: string, sessionIdOrEntry: string | AuditEntry, maybeEntry?: AuditEntry): Promise<string>;
+export declare function readWorkflowTransactionJournal(cwd: string, sessionId: string, mutationId: string): Promise<WorkflowTransactionJournal | undefined>;
 export declare function beginWorkflowTransactionJournal(input: {
     cwd: string;
+    sessionId: 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>;
+export declare function updateWorkflowTransactionJournal(cwd: string, sessionId: string, mutationId: string, patch: Partial<WorkflowTransactionJournal>): Promise<string>;
+export declare function completeWorkflowTransactionJournal(cwd: string, sessionId: string, mutationId: string): Promise<void>;

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

@@ -27,10 +27,25 @@ export declare function validateCompletionReceipt(input: {
 export declare function readUltragoalVerificationState(input: {
     cwd: string;
     currentGoal?: CurrentGoalLike | null;
+    sessionId?: string | null;
 }): Promise<UltragoalGuardDiagnostic>;
 export declare function isUltragoalAskBlocked(cwd: string): Promise<UltragoalAskBlockDiagnostic>;
 export declare function assertCanCompleteCurrentGoal(input: {
     cwd: string;
     currentGoal?: CurrentGoalLike | null;
+    sessionId?: string | null;
 }): Promise<void>;
 export declare function isUltragoalBypassPrompt(prompt: string): boolean;
+export interface UltragoalPauseBlockDiagnostic {
+    blocked: boolean;
+    reason: string;
+}
+/**
+ * While an Ultragoal run is active, `goal({"op":"pause"})` is only allowed when the
+ * current durable Ultragoal state is readable and the latest durable ledger event
+ * classifies the current blocker as `human_blocked`. Resolvable blockers must be
+ * worked, not parked. Reads fail closed so unreadable durable state or ledger data
+ * blocks pause rather than silently allowing a give-up.
+ */
+export declare function isUltragoalPauseBlocked(cwd: string): Promise<UltragoalPauseBlockDiagnostic>;
+export declare function assertUltragoalPauseAllowed(cwd: string): Promise<void>;

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

@@ -23,6 +23,7 @@ export interface UltragoalPlan {
     goals: UltragoalGoal[];
     createdAt: string;
     updatedAt: string;
+    [key: string]: unknown;
 }
 export type UltragoalReceiptKind = "per-goal" | "final-aggregate";
 export interface UltragoalCompletionVerification {
@@ -79,8 +80,8 @@ interface JsonObject {
     [key: string]: unknown;
 }
 export declare function hashStructuredValue(value: unknown): string;
-export declare function getUltragoalPaths(cwd: string): UltragoalPaths;
-export declare function readUltragoalLedger(cwd: string): Promise<UltragoalLedgerEvent[]>;
+export declare function getUltragoalPaths(cwd: string, sessionId?: string | null): UltragoalPaths;
+export declare function readUltragoalLedger(cwd: string, sessionId?: string | null): Promise<UltragoalLedgerEvent[]>;
 export declare function computeUltragoalPlanGeneration(input: {
     plan: UltragoalPlan;
     ledger: readonly UltragoalLedgerEvent[];
@@ -93,13 +94,14 @@ export declare function computeUltragoalPlanGeneration(input: {
     planGeneration: string;
     basis: UltragoalCompletionVerification["basis"];
 };
-export declare function readUltragoalPlan(cwd: string): Promise<UltragoalPlan | null>;
-export declare function getUltragoalStatus(cwd: string): Promise<UltragoalStatusSummary>;
+export declare function readUltragoalPlan(cwd: string, sessionId?: string | null): Promise<UltragoalPlan | null>;
+export declare function getUltragoalStatus(cwd: string, sessionId?: string | null): Promise<UltragoalStatusSummary>;
 export declare function buildUltragoalHudSummary(summary: UltragoalStatusSummary, latestLedger?: UltragoalLedgerEvent): WorkflowHudSummary;
 export declare function createUltragoalPlan(input: {
     cwd: string;
     brief: string;
     gjcGoalMode?: UltragoalGjcGoalMode;
+    sessionId?: string | null;
 }): Promise<UltragoalPlan>;
 export interface UltragoalRunCompletionState {
     requiredGoals: UltragoalGoal[];
@@ -115,6 +117,7 @@ export declare function getUltragoalRunCompletionState(plan: UltragoalPlan, opti
 export declare function startNextUltragoalGoal(input: {
     cwd: string;
     retryFailed?: boolean;
+    sessionId?: string | null;
 }): Promise<{
     plan: UltragoalPlan;
     goal?: UltragoalGoal;
@@ -190,6 +193,19 @@ export declare function recordUltragoalReviewBlockers(input: {
     evidence: string;
     gjcGoalJson?: string;
 }): Promise<UltragoalPlan>;
+export type UltragoalBlockerClassification = "human_blocked" | "resolvable";
+/**
+ * Record an audited blocker triage classification in the durable ledger. A
+ * `human_blocked` classification is the only thing that authorizes
+ * `goal({"op":"pause"})` while an Ultragoal run is active; `resolvable` is an
+ * audit note and never unblocks pause.
+ */
+export declare function recordUltragoalBlockerClassification(input: {
+    cwd: string;
+    classification: UltragoalBlockerClassification;
+    evidence: string;
+    goalId?: string;
+}): Promise<UltragoalLedgerEvent>;
 type UltragoalReviewContractStrength = "strong" | "thin-derived";
 interface UltragoalReviewFinding extends JsonObject {
     severity: "blocker";
@@ -205,6 +221,7 @@ interface UltragoalReviewResult extends JsonObject {
     weakContractCapApplied: boolean;
     blockerGoalIds?: string[];
 }
+export declare function resolveGitBase(cwd: string, branch?: string): Promise<string>;
 export declare function runUltragoalReview(cwd: string, args: readonly string[]): Promise<UltragoalReviewResult>;
 export declare function runNativeUltragoalCommand(args: string[], cwd?: string): Promise<UltragoalCommandResult>;
 export {};

package/dist/types/gjc-runtime/workflow-command-ref.d.ts

@@ -1,4 +1,4 @@
-import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import { type CanonicalGjcWorkflowSkill } from "../skill-state/canonical-skills";
 export type CommandRefVisibility = "public" | "hidden" | "planned";
 export type CommandRefIncludeWhen = "implemented-only" | "planned";
 export interface CommandRefCommand {

package/dist/types/gjc-runtime/workflow-manifest.d.ts

@@ -3,7 +3,7 @@
  * Any JSON manifest projection is derived from this module and must never be
  * hand-edited.
  */
-import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import { type CanonicalGjcWorkflowSkill } from "../skill-state/canonical-skills";
 export interface WorkflowState {
     id: string;
     initial?: boolean;

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

@@ -29,11 +29,12 @@ export declare class StorageError extends Error {
     readonly code: string;
     constructor(message: string, code: string);
 }
-/** Resolve the harness state root from explicit value, env, or cwd default. */
+/** Resolve the harness state root from explicit value, env, or cwd/session default. */
 export declare function resolveHarnessRoot(opts?: {
     root?: string;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+    gjcSessionId?: string;
 }): string;
 export declare function assertSafeSessionId(id: string): void;
 export declare function generateSessionId(prefix?: string): string;

package/dist/types/hooks/skill-state.d.ts

@@ -1,7 +1,9 @@
 import type { SkillDiscoverySettings } from "../config/skill-settings-defaults";
 import { type SkillActiveState } from "../skill-state/active-state";
+import { initialPhaseForSkill } from "../skill-state/initial-phase";
+export { initialPhaseForSkill };
 import { type GjcWorkflowSkill } from "./skill-keywords";
-export declare const GJC_STATE_DIR = ".gjc/state";
+export declare const GJC_STATE_DIR = ".gjc";
 export declare const SKILL_ACTIVE_STATE_FILE = "skill-active-state.json";
 export interface EffectiveSkillConfigInput {
     skillsSettings?: SkillDiscoverySettings;
@@ -55,9 +57,15 @@ export interface UserPromptSubmitStateInput {
 export declare function detectSkillKeywords(text: string): SkillKeywordMatch[];
 export declare function detectPrimarySkillKeyword(text: string): SkillKeywordMatch | null;
 export declare function resolveGjcStateDir(cwd: string, stateDir?: string): string;
-import { initialPhaseForSkill } from "../skill-state/initial-phase";
-export { initialPhaseForSkill };
-export declare function readVisibleSkillActiveState(cwd: string, sessionId?: string, stateDir?: string): Promise<SkillActiveState | null>;
+export interface StateRecoveryDiagnostic {
+    kind: "skill-active-state" | "mode-state";
+    statePath: string;
+    reason: "missing" | "corrupt" | "unreadable";
+    skill?: GjcWorkflowSkill;
+}
+export declare function buildStateRecoveryDiagnosticsContext(diagnostics: readonly StateRecoveryDiagnostic[]): string | null;
+export declare function collectUserPromptStateRecoveryDiagnostics(input: UserPromptSubmitStateInput): Promise<StateRecoveryDiagnostic[]>;
+export declare function readVisibleSkillActiveState(cwd: string, sessionId?: string, _stateDir?: string): Promise<SkillActiveState | null>;
 export declare function recordSkillActivation(input: RecordSkillActivationInput): Promise<SkillActiveState | null>;
 export interface EnsureWorkflowSkillActivationInput {
     cwd: string;

package/dist/types/migrate/action-planner.d.ts

@@ -0,0 +1,11 @@
+import type { AdapterResult, MigrateAction, MigrateDestinations, MigrateWarning } from "./types";
+export interface PlanInput {
+    results: AdapterResult[];
+    destinations: MigrateDestinations;
+    force: boolean;
+}
+export interface PlanOutput {
+    actions: MigrateAction[];
+    warnings: MigrateWarning[];
+}
+export declare function planMigration(input: PlanInput): Promise<PlanOutput>;

package/dist/types/migrate/adapters/claude-code.d.ts

@@ -0,0 +1,2 @@
+import { type Adapter } from "./index";
+export declare const claudeCodeAdapter: Adapter;

package/dist/types/migrate/adapters/codex.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Codex adapter: reads `~/.codex/config.toml` ([mcp_servers]) and `~/.codex/prompts`.
+ */
+import { type Adapter } from "./index";
+export declare const codexAdapter: Adapter;

package/dist/types/migrate/adapters/index.d.ts

@@ -0,0 +1,45 @@
+import type { AdapterResult, MigrateSource, SkillCandidate, SourceDiagnostic } from "../types";
+export interface AdapterOptions {
+    /** Home directory root; overridable for tests. */
+    homeDir: string;
+}
+export interface Adapter {
+    source: MigrateSource;
+    collect(options: AdapterOptions): Promise<AdapterResult>;
+}
+export declare function getAdapter(source: MigrateSource): Adapter;
+/** Read a text file, classifying absence/IO errors into source diagnostics. */
+export declare function readSourceText(filePath: string, source: MigrateSource, type: SourceDiagnostic["type"]): Promise<{
+    text: string;
+} | {
+    diagnostic: SourceDiagnostic;
+}>;
+/** Parse JSON text, classifying parse errors into a `failed_invalid_source` diagnostic. */
+export declare function parseSourceJson(text: string, filePath: string, source: MigrateSource, type: SourceDiagnostic["type"]): {
+    data: Record<string, unknown>;
+} | {
+    diagnostic: SourceDiagnostic;
+};
+/**
+ * Collect skill candidates from a directory of `<name>/SKILL.md` entries.
+ * A missing directory yields a `skipped_absent_source` diagnostic.
+ */
+export declare function collectSkillDir(dir: string, source: MigrateSource): Promise<{
+    candidates: SkillCandidate[];
+    diagnostics: SourceDiagnostic[];
+}>;
+/**
+ * Collect skill candidates from a flat directory of `*.md` prompt/command files.
+ */
+export declare function collectMarkdownPrompts(dir: string, source: MigrateSource): Promise<{
+    candidates: SkillCandidate[];
+    diagnostics: SourceDiagnostic[];
+}>;
+/**
+ * Recursively collect skill candidates from any `**​/SKILL.md` under `root`.
+ * The slug derives from the directory that directly contains the `SKILL.md`.
+ */
+export declare function collectSkillTree(root: string, source: MigrateSource): Promise<{
+    candidates: SkillCandidate[];
+    diagnostics: SourceDiagnostic[];
+}>;

package/dist/types/migrate/adapters/opencode.d.ts

@@ -0,0 +1,2 @@
+import { type Adapter } from "./index";
+export declare const opencodeAdapter: Adapter;

package/dist/types/migrate/executor.d.ts

@@ -0,0 +1,2 @@
+import type { MigrateAction } from "./types";
+export declare function executeActions(actions: MigrateAction[]): Promise<MigrateAction[]>;

package/dist/types/migrate/mcp-mapper.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Map raw source MCP server entries onto GJC `MCPServerConfig`.
+ *
+ * Implements the source-schema compatibility matrix from the consensus plan:
+ * preserved (P), transformed (T), omitted-with-warning (OW), skipped (S,
+ * `skipped_unmappable`), and failed (F, `failed_invalid_source`). Secret-indirection
+ * fields are always omitted-with-warning; their values are never read or emitted.
+ */
+import type { MCPServerConfig } from "../runtime-mcp/types";
+import type { MigrateSource } from "./types";
+export type McpMapOutcome = {
+    ok: true;
+    config: MCPServerConfig;
+    warnings: string[];
+} | {
+    ok: false;
+    status: "skipped_unmappable" | "failed_invalid_source";
+    reason: string;
+};
+export declare function mapMcpEntry(source: MigrateSource, name: string, raw: unknown): McpMapOutcome;

package/dist/types/migrate/report.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Build the human-readable and `--json` reports for `gjc migrate`.
+ *
+ * Secret values are never read upstream, so the report only ever contains field
+ * names in warnings — but rendering still treats action/warning text as opaque.
+ */
+import { type MigrateAction, type MigrateDestinations, type MigrateReport, type MigrateSource, type MigrateWarning } from "./types";
+export interface BuildReportInput {
+    actions: MigrateAction[];
+    warnings: MigrateWarning[];
+    sources: MigrateSource[];
+    destinations: MigrateDestinations;
+    dryRun: boolean;
+    project: boolean;
+    force: boolean;
+}
+export declare function buildReport(input: BuildReportInput): MigrateReport;
+export declare function renderHuman(report: MigrateReport): string;

package/dist/types/migrate/skill-normalizer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Normalize a skill from another agent into a native GJC `SKILL.md`.
+ *
+ * GJC derives a skill's loaded name from its directory (`<slug>/SKILL.md`) when no
+ * frontmatter `name` is present, and requires a `description`. To guarantee the
+ * effective loaded name equals the lowercase-hyphen slug, we drop any frontmatter
+ * `name` and place the file at `<slug>/SKILL.md`, synthesizing a `description`
+ * when the source lacks one.
+ */
+export interface NormalizeSkillInput {
+    /** Raw name from the source (filename stem, frontmatter name, etc.). */
+    rawName: string;
+    /** Full source markdown (may or may not have frontmatter). */
+    content: string;
+}
+export interface NormalizedSkill {
+    slug: string;
+    content: string;
+    warnings: string[];
+}
+/** Convert an arbitrary name into a lowercase-hyphen slug. */
+export declare function slugify(name: string): string;
+/**
+ * Produce a `{ slug, content }` pair whose effective GJC-loaded name equals `slug`.
+ * Throws only on an unusable name (cannot produce a slug).
+ */
+export declare function normalizeSkill(input: NormalizeSkillInput): NormalizedSkill;