@gajae-code/coding-agent 0.6.4 → 0.6.5

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [0.6.5] - 2026-06-21
+
+### Changed
+
+- Scoped all GJC workflow state by session ID: skill state, plans, specs, and ledgers now live under per-session `.gjc/_session-{id}/` directories, so concurrent or resumed sessions no longer collide on shared workflow state.
+- Hardened skill-state hooks with a writer revision policy, a force-ask on Stop, HUD reconciliation, and an fd-duplication guard; forced/authoritative state writes now survive corrupt prior state (#950).
+- Migrated the global debug shortcut into the keybinding registry and added `pasteImage` as a single source of truth with default-collision diagnostics (#925, #939).
+- Added safe import of custom skills and MCP servers via `migrate` (#944).
+- Trimmed the bundled agent roster to the four canonical role agents: planner, architect, critic, and executor (#922).
+- Added a research-plan ledger spike (#933).
+
+### Fixed
+
+- Stopped including `bash` in the planning-phase mutation guard. The phase-boundary block (and the always-on `.gjc/**` runtime-owned block) now apply only to the fully-pathed `write`/`edit`/`ast_edit` tools; `bash` is never blocked by any workflow skill (`deep-interview`, `ralplan`, `ultragoal` goal-planning), so read-only shell commands run freely during planning. This reverts the `bash` parity added in 0.6.2; product-code and `.gjc/**` mutation are still gated through the dedicated edit tools (#951).
+- Rejected counterexample-only claims in research-plan regardless of `dropCondition` wording (#942).
+- Bounded computer-use screenshot inline images to avoid oversized payloads.
+- Tolerated missing session env in guard reads (#930).
+
+### Documentation
+
+- Documented standalone MCP boundaries (#923).
+
 ## [0.6.4] - 2026-06-20
 
 ### Changed

package/dist/types/cli/migrate-cli.d.ts

@@ -0,0 +1,20 @@
+import { type MigrateReport, type MigrateSource } from "../migrate/types";
+export interface MigrateCommandArgs {
+    from: string[];
+    project: boolean;
+    force: boolean;
+    dryRun: boolean;
+    json: boolean;
+    /** Test seam: override home dir for source discovery. */
+    homeDir?: string;
+    /** Test seam: override cwd for project-scope destinations. */
+    cwd?: string;
+}
+export declare class MigrateArgsError extends Error {
+}
+/** Expand `all`/repeated `--from`, validate, and return sources in canonical order. */
+export declare function resolveSources(from: string[]): MigrateSource[];
+/** Run the migration and return the report (does not set process.exitCode). */
+export declare function runMigrate(args: MigrateCommandArgs): Promise<MigrateReport>;
+/** CLI entry: run, render, and set the process exit code. */
+export declare function runMigrateCommand(args: MigrateCommandArgs): Promise<void>;

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

@@ -0,0 +1,33 @@
+/**
+ * Import MCP servers and skills from other coding agents into GJC.
+ */
+import { Command } from "@gajae-code/utils/cli";
+export default class Migrate extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        from: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            multiple: true;
+            required: true;
+        };
+        project: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+        force: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+        "dry-run": import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+        json: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            char: string;
+            description: string;
+            default: boolean;
+        };
+    };
+    run(): Promise<void>;
+}

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

@@ -173,6 +173,10 @@ export declare const KEYBINDINGS: {
         readonly defaultKeys: ["escape", "ctrl+c"];
         readonly description: "Cancel selection";
     };
+    readonly "tui.global.debug": {
+        readonly defaultKeys: "shift+ctrl+d";
+        readonly description: "Toggle debug overlay";
+    };
     readonly "app.interrupt": {
         readonly defaultKeys: "escape";
         readonly description: "Interrupt current operation";

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

@@ -84,6 +84,8 @@ export declare function ensureDeepInterviewStateShape(value: unknown): DeepInter
 export declare function projectCompactState(value: unknown, options?: {
     lastN?: number;
 }): DeepInterviewCompactState;
+/** Refresh the best-effort HUD cache from persisted deep-interview state. */
+export declare function syncDeepInterviewRecorderHud(cwd: string, statePath: string, sessionId: string | undefined): Promise<void>;
 /** 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;

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,25 @@ 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;
+} | {
+    path: string;
+    written: false;
+    reason: "stale-skip";
+};
 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 +83,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 +139,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 +207,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 +224,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-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;

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;