@gajae-code/coding-agent 0.13.3 → 0.14.0

package/dist/types/discovery/codex.d.ts

@@ -1 +1,39 @@
-export {};
+import type { ExtensionModule } from "../capability/extension-module";
+import type { Hook } from "../capability/hook";
+import type { MCPServer } from "../capability/mcp";
+import type { Skill } from "../capability/skill";
+import type { SlashCommand } from "../capability/slash-command";
+import type { CustomTool } from "../capability/tool";
+import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
+export declare const CODEX_PROVIDER_ID = "codex";
+export declare const CODEX_DISPLAY_NAME = "OpenAI Codex";
+export declare const CODEX_CONFIG_DIR = ".codex";
+/**
+ * Enumerate the project-local `.codex/skills` layout (cwd only), mirroring the
+ * OpenAI Codex project convention.
+ */
+export declare function scanCodexProjectSkills(ctx: LoadContext): Promise<LoadResult<Skill>>;
+/**
+ * Enumerate the user-global `~/.codex/skills` layout. This is an explicit
+ * import candidate only; GJC never loads it without an explicit import action.
+ */
+export declare function scanCodexUserSkills(ctx: LoadContext): Promise<LoadResult<Skill>>;
+export declare function codexSkillSourceMeta(filePath: string, level: "user" | "project"): SourceMeta;
+export interface CodexConventionInspection {
+    mcps: LoadResult<MCPServer>;
+    skills: LoadResult<Skill>;
+    hooks: LoadResult<Hook>;
+    tools: LoadResult<CustomTool>;
+    extensions: LoadResult<ExtensionModule>;
+    commands: LoadResult<SlashCommand>;
+}
+/**
+ * Inspect what the Codex project convention (.codex/) would surface.
+ *
+ * Reuses the shared discovery scan helpers without registering any provider,
+ * so diagnostics can report the convention's files while keeping the runtime
+ * load path exactly as configured (none of these surfaces are registered for
+ * session loading; hooks are covered by the separate registered codex-hooks
+ * provider).
+ */
+export declare function inspectCodexConvention(ctx: LoadContext): Promise<CodexConventionInspection>;

package/dist/types/discovery/index.d.ts

@@ -20,10 +20,12 @@ import "../capability/system-prompt";
 import "../capability/tool";
 import "./agents-md";
 import "./builtin";
+import "./claude-hooks";
 import "./claude-plugins";
 import "./cline";
 import "./agents";
 import "./cursor";
+import "./codex-hooks";
 import "./gemini";
 import "./opencode";
 import "./github";

package/dist/types/discovery/mcp-compat.d.ts

@@ -0,0 +1,30 @@
+import { type MCPServer } from "../capability/mcp";
+import type { LoadResult } from "../capability/types";
+/** Result of normalizing a foreign MCP config into the internal contract. */
+export interface MCPCompatNormalizeResult extends LoadResult<MCPServer> {
+    /** Normalization diagnostics (always present, possibly empty). */
+    warnings: string[];
+    /** Path the definitions were normalized from (for provenance). */
+    sourcePath: string;
+}
+/**
+ * Normalize a Claude Code `.mcp.json` file body into the internal MCP contract.
+ *
+ * The Claude project format uses the same `{ "mcpServers": { name: {...} } }`
+ * JSON shape as GJC's config; `enabled`/`autoload` are preserved so a caller
+ * can decide startup behavior after import. Bounded to the supplied content:
+ * no filesystem scanning, no user-home reads.
+ */
+export declare function normalizeClaudeMcpJson(content: string, sourcePath: string, level?: "project" | "user"): MCPCompatNormalizeResult;
+/**
+ * Normalize a Codex `config.toml` file body into the internal MCP contract.
+ * Only the `[mcp_servers.*]` sections are read; everything else is ignored.
+ */
+export declare function normalizeCodexMcpToml(content: string, sourcePath: string, level?: "project" | "user"): MCPCompatNormalizeResult;
+/**
+ * Validate a normalized server against the internal MCP contract. Returns an
+ * error message, or undefined when the definition is importable. Callers use
+ * this to fail closed before writing a malformed/untrusted definition into
+ * `.gjc` (mcpCapability.validate is reused so import and runtime share one rule).
+ */
+export declare function validateMCPCompatServer(server: MCPServer): string | undefined;

package/dist/types/edit/renderer.d.ts

@@ -53,6 +53,29 @@ export interface EditToolDetails {
     /** Source-of-truth content after the edit; `undefined` for delete operations. */
     newText?: string;
 }
+/**
+ * Bounded durable identity of one edit snapshot (#4566).
+ *
+ * Live edit results carry full `oldText`/`newText` file bodies so in-process
+ * consumers (ACP `diff` ToolCallContent, editors) keep working. Every persisted
+ * transcript entry replaces those bodies with this fixed-size receipt: byte
+ * length plus SHA-256 content digest, enough to detect source drift and to
+ * account for the edit durably without re-writing the whole file per edit.
+ */
+export interface EditSnapshotReceipt {
+    /** UTF-8 byte length of the snapshot (`0` for create/delete-absent sides). */
+    bytes: number;
+    /** SHA-256 hex digest of the exact snapshot text (empty string for length 0). */
+    sha256: string;
+}
+/** Per-edit-mode cap on any single persisted edit-result string field (#4566). */
+export declare const EDIT_PERSIST_FIELD_MAX_CHARS: number;
+/** Fixed marker used when a snapshot receipt replaces a full body. */
+export declare const EDIT_SNAPSHOT_EXTERNALIZED_NOTICE = "[edit snapshot externalized: see oldTextDigest/newTextDigest; full body omitted from transcript]";
+/** Build the bounded durable receipt for one snapshot body. */
+export declare function editSnapshotReceipt(text: string | undefined): EditSnapshotReceipt | undefined;
+/** True when a snapshot body is small enough to persist inline without amplification. */
+export declare function editSnapshotPersistableInline(text: string | undefined): boolean;
 export interface EditRenderArgs {
     path?: string;
     file_path?: string;

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

@@ -14,8 +14,11 @@ interface BeforeAgentStartCombinedResult {
     systemPrompt?: string[];
 }
 export type ExtensionErrorListener = (error: ExtensionError) => void;
+/** Bounded timeout for session_shutdown handlers — generous but never infinite. */
+export declare const SESSION_SHUTDOWN_HANDLER_TIMEOUT_MS = 60000;
 export declare const EXTENSION_HANDLER_TIMEOUT_MS = 30000;
 export declare function testSetExtensionHandlerTimeoutMs(timeoutMs: number): void;
+export declare function testSetSessionShutdownHandlerTimeoutMs(timeoutMs: number): void;
 /**
  * Events handled by the generic emit() method.
  * Events with dedicated emitXxx() methods are excluded for stronger type safety.

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

@@ -27,7 +27,7 @@ import type { CustomMessage } from "../../session/messages";
 import type { ReadonlySessionManager, SessionManager } from "../../session/session-manager";
 import type { BashToolDetails, BashToolInput, FindToolDetails, FindToolInput, ReadToolDetails, ReadToolInput, SearchToolDetails, SearchToolInput, WriteToolInput } from "../../tools";
 import type { EventBus } from "../../utils/event-bus";
-import type { AgentEndEvent, AgentStartEvent, AutoCompactionEndEvent, AutoCompactionStartEvent, AutoRetryEndEvent, AutoRetryStartEvent, ContextEvent, GoalUpdatedEvent, SessionBeforeBranchEvent, SessionBeforeBranchResult, SessionBeforeCompactEvent, SessionBeforeCompactResult, SessionBeforeSwitchEvent, SessionBeforeSwitchResult, SessionBeforeTreeEvent, SessionBeforeTreeResult, SessionBranchEvent, SessionCompactEvent, SessionCompactingEvent, SessionCompactingResult, SessionEvent, SessionShutdownEvent, SessionStartEvent, SessionSwitchEvent, SessionTreeEvent, TodoReminderEvent, ToolCallEventResult, ToolResultEventResult, TtsrTriggeredEvent, TurnEndEvent, TurnStartEvent } from "../shared-events";
+import type { AgentEndEvent, AutoCompactionEndEvent, AutoCompactionStartEvent, AutoRetryEndEvent, AutoRetryStartEvent, ContextEvent, GoalUpdatedEvent, SessionBeforeBranchEvent, SessionBeforeBranchResult, SessionBeforeCompactEvent, SessionBeforeCompactResult, SessionBeforeSwitchEvent, SessionBeforeSwitchResult, SessionBeforeTreeEvent, SessionBeforeTreeResult, SessionBranchEvent, SessionCompactEvent, SessionCompactingEvent, SessionCompactingResult, SessionEvent, SessionShutdownEvent, SessionStartEvent, SessionSwitchEvent, SessionTreeEvent, AgentStartEvent as SharedAgentStartEvent, TodoReminderEvent, ToolCallEventResult, ToolResultEventResult, TtsrTriggeredEvent, TurnEndEvent, TurnStartEvent } from "../shared-events";
 import type { SlashCommandInfo } from "../slash-commands";
 export type { AppKeybinding, KeybindingsManager } from "../../config/keybindings";
 export type { ExecOptions, ExecResult } from "../../exec/exec";
@@ -256,7 +256,7 @@ export interface ExtensionContext {
     /** Stable resource ownership identifier for the active prompt run. */
     getActivePromptHandle(): string | undefined;
     /** Abort the current agent operation */
-    abort(): void;
+    abort(): void | Promise<void>;
     /** Abort and prove whether resources for a specific prompt settled. */
     abortPromptAndWait?(handle: string, options: {
         graceMs: number;
@@ -322,6 +322,7 @@ export interface ExtensionContext {
             lineCount?: number;
             cleanedArgs?: string;
         }) => void;
+        preflightSignal?: AbortSignal;
     }): Promise<unknown>;
     setPlanMode?(on: boolean): unknown;
     operateGoal?(op: "create" | "get" | "resume" | "pause" | "complete" | "drop", objective?: string): Promise<unknown>;
@@ -459,7 +460,11 @@ export interface BeforeAgentStartEvent {
     images?: ImageContent[];
     systemPrompt: string[];
 }
-export type { AgentEndEvent, AgentStartEvent, TurnEndEvent, TurnStartEvent } from "../shared-events";
+export type { AgentEndEvent, TurnEndEvent, TurnStartEvent } from "../shared-events";
+/** Fired when an agent loop starts. `sdkRunToken` is an internal SDK queue-owner binding. */
+export interface AgentStartEvent extends SharedAgentStartEvent {
+    sdkRunToken?: string;
+}
 /** Fired when a message starts (user, assistant, or toolResult) */
 export interface MessageStartEvent {
     type: "message_start";
@@ -792,8 +797,14 @@ export interface ExtensionAPI {
     /** Send a user message to the agent, or queue it when deliverAs is set. */
     sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
         deliverAs?: "steer" | "followUp";
+        /** Internal SDK signal preserving a busy dispatch across async admission fences. */
+        queuedAtDispatch?: boolean;
         onPreflightAccepted?: () => void;
         onPreflightAcceptCommit?: () => void | Promise<void>;
+        onQueuedPromoted?: () => void;
+        preflightSignal?: AbortSignal;
+        /** Internal SDK correlation owner for an exact queued follow-up. */
+        sdkRunToken?: string;
     }): Promise<void>;
     /** Append a custom entry to the session for state persistence (not sent to LLM). */
     appendEntry<T = unknown>(customType: string, data?: T): void;
@@ -968,6 +979,11 @@ export type SendUserMessageHandler = (content: string | (TextContent | ImageCont
     deliverAs?: "steer" | "followUp";
     onPreflightAccepted?: () => void;
     onPreflightAcceptCommit?: () => void | Promise<void>;
+    /** Fired when a queued submission (steering or follow-up) is promoted to its own run (SDK ownership correlation). */
+    onQueuedPromoted?: () => void;
+    preflightSignal?: AbortSignal;
+    /** Internal SDK correlation owner for an exact queued follow-up. */
+    sdkRunToken?: string;
 }) => void | Promise<void>;
 export type AppendEntryHandler = <T = unknown>(customType: string, data?: T) => void;
 export type GetActiveToolsHandler = () => string[];
@@ -1034,7 +1050,7 @@ export interface ExtensionContextActions {
     isIdle: () => boolean;
     /** Stable resource ownership identifier for the active prompt run. */
     getActivePromptHandle?: () => string | undefined;
-    abort: () => void;
+    abort: () => void | Promise<void>;
     abortPromptAndWait?: (handle: string, options: {
         graceMs: number;
     }) => Promise<RunSettlementProof>;
@@ -1103,6 +1119,7 @@ export interface ExtensionContextActions {
             lineCount?: number;
             cleanedArgs?: string;
         }) => void;
+        preflightSignal?: AbortSignal;
     }) => Promise<unknown>;
     setPlanMode?: (on: boolean) => unknown;
     operateGoal?: (op: "create" | "get" | "resume" | "pause" | "complete" | "drop", objective?: string) => Promise<unknown>;

package/dist/types/extensibility/gjc-plugins/observability.d.ts

@@ -23,5 +23,10 @@ export interface PluginObservabilitySummary {
 /**
  * Build the observability summary for the effective registry at `cwd`, including
  * hash-drift and session-collision quarantine status.
+ *
+ * Pass `{ migrate: false }` from read-only inspection surfaces (for example
+ * `gjc customize doctor`) so reporting never persists registry migrations.
  */
-export declare function summarizeGjcPluginObservability(cwd: string): Promise<PluginObservabilitySummary>;
+export declare function summarizeGjcPluginObservability(cwd: string, options?: {
+    migrate?: boolean;
+}): Promise<PluginObservabilitySummary>;

package/dist/types/extensibility/gjc-plugins/registry.d.ts

@@ -29,6 +29,13 @@ export declare function writeRegistry(registry: GjcPluginRegistry, cwd: string,
 export declare function updateRegistry(scope: GjcPluginScope, cwd: string, mutator: (entries: GjcPluginRegistryEntry[]) => GjcPluginRegistryEntry[]): Promise<GjcPluginRegistry>;
 /**
  * Effective registry for a cwd: user + project entries in deterministic order.
+ *
+ * Defaults to the startup semantics (legacy-entry discovery + migration, which
+ * may persist the migrated registry). Read-only inspection surfaces (for
+ * example `gjc customize doctor`) pass `{ migrate: false }` so reporting never
+ * writes to the registry.
  */
-export declare function loadEffectiveGjcPluginRegistry(cwd: string): Promise<GjcPluginRegistryEntry[]>;
+export declare function loadEffectiveGjcPluginRegistry(cwd: string, options?: {
+    migrate?: boolean;
+}): Promise<GjcPluginRegistryEntry[]>;
 export declare function registryEntryFingerprint(entry: GjcPluginRegistryEntry): string;

package/dist/types/extensibility/hooks/loader.d.ts

@@ -1,5 +1,7 @@
+import { type NormalizedHook } from "../../hooks/normalize";
 import type { HookMessage } from "../../session/messages";
 import type { SessionManager } from "../../session/session-manager";
+import type { ExtensionFactory } from "../extensions/types";
 import type { HookMessageRenderer, RegisteredCommand } from "./types";
 /**
  * Generic handler function type.
@@ -57,6 +59,8 @@ export interface LoadedHook {
     setSendMessageHandler: (handler: SendMessageHandler) => void;
     /** Set the append entry handler for this hook's pi.appendEntry() */
     setAppendEntryHandler: (handler: AppendEntryHandler) => void;
+    /** Canonical discovery descriptor when loaded from a known hook convention. */
+    normalization?: NormalizedHook;
 }
 /**
  * Result of loading hooks.
@@ -70,6 +74,16 @@ export interface LoadHooksResult {
         error: string;
     }>;
 }
+export interface LoadHookExtensionsResult {
+    factories: Array<{
+        factory: ExtensionFactory;
+        name: string;
+    }>;
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}
 /**
  * Load all hooks from configuration.
  * @param paths - Array of hook file paths
@@ -77,13 +91,13 @@ export interface LoadHooksResult {
  */
 export declare function loadHooks(paths: string[], cwd: string): Promise<LoadHooksResult>;
 /**
- * Discover and load hooks from all registered providers.
- * Uses the capability API to discover hook paths from:
- * 1. GJC native configs (.gjc/.pi hooks/)
- * 2. Installed plugins
- * 3. Other editor/IDE configurations
+ * Discover and load hooks from canonical native GJC configuration.
+ * Claude Code and Codex hook layouts remain registered capability providers for
+ * explicit import and diagnostics, but are not competing runtime authorities.
  *
  * Plus any explicitly configured paths from settings.
  */
 export declare function discoverAndLoadHooks(configuredPaths: string[], cwd: string): Promise<LoadHooksResult>;
+/** Load normalized directory hooks and adapt them into the authoritative ExtensionRunner path. */
+export declare function discoverAndLoadHookExtensions(configuredPaths: string[], cwd: string): Promise<LoadHookExtensionsResult>;
 export {};

package/dist/types/extensibility/runtime-skill-discovery.d.ts

@@ -8,6 +8,19 @@ export interface RuntimeSkillDiscoveryCandidate {
     path: string;
     useWhen?: string[];
 }
+/**
+ * Human-readable diagnostics collected while scanning, so an empty or partial
+ * result is explainable: protected-name collisions with bundled workflow
+ * skills, skills filtered by include/ignore/disable policy, invalid frontmatter,
+ * and scan warnings. Bounded to avoid flooding tool output.
+ */
+export interface RuntimeSkillDiscoveryDiagnostics {
+    messages: string[];
+}
+export interface RuntimeSkillDiscoveryResult {
+    candidates: RuntimeSkillDiscoveryCandidate[];
+    diagnostics: RuntimeSkillDiscoveryDiagnostics;
+}
 export interface DiscoverRuntimeSkillsOptions {
     cwd: string;
     home?: string;
@@ -16,5 +29,13 @@ export interface DiscoverRuntimeSkillsOptions {
     source?: RuntimeSkillDiscoverySource | "all";
     policy?: SkillsSettings;
 }
-export declare function discoverRuntimeSkills(options: DiscoverRuntimeSkillsOptions): Promise<RuntimeSkillDiscoveryCandidate[]>;
+/**
+ * Explain an empty result that is caused by disabled discovery config rather
+ * than by an actually empty skill catalog. Uses the user-facing trust
+ * settings; the legacy `skills.enablePiUser` / `skills.enablePiProject`
+ * aliases map onto the same effective values. Shared by the skill_discovery
+ * tool and `gjc skills discover`.
+ */
+export declare function describeDisabledSkillScopes(source: RuntimeSkillDiscoverySource | "all", policy: SkillsSettings | undefined): string | undefined;
+export declare function discoverRuntimeSkills(options: DiscoverRuntimeSkillsOptions): Promise<RuntimeSkillDiscoveryResult>;
 export declare function findRuntimeSkillByName(cwd: string, name: string, policy?: SkillsSettings, home?: string): Promise<Skill | undefined>;

package/dist/types/extensibility/skill-management.d.ts

@@ -0,0 +1,107 @@
+export type SkillScope = "project" | "user";
+export type ConventionSkillHost = "claude" | "codex";
+export interface SkillManagementPolicy {
+    enabled?: boolean;
+    trustProjectSkills?: boolean;
+    trustUserSkills?: boolean;
+    ignoredSkills?: string[];
+    includeSkills?: string[];
+    disabledExtensions?: string[];
+}
+export type SkillDisabledReason = "protected" | "scope-trust" | "ignored" | "include" | "disabled-extension";
+/** A discovered native skill with provenance and enablement state. */
+export interface ManagedSkillRecord {
+    name: string;
+    description: string;
+    path: string;
+    scope: SkillScope;
+    /** Canonical source label, e.g. "project .gjc/skills" or "user ~/.gjc/agent/skills". */
+    source: string;
+    hidden: boolean;
+    enabled: boolean;
+    disabledReason?: SkillDisabledReason;
+}
+/** A Claude Code / Codex skill enumerated as an explicit import source into `.gjc`. */
+export interface ConventionSkillImportSource {
+    host: ConventionSkillHost;
+    scope: SkillScope;
+    name: string;
+    description: string;
+    path: string;
+}
+export interface WriteNativeSkillInput {
+    cwd: string;
+    home?: string;
+    scope: SkillScope;
+    name: string;
+    content: string;
+}
+export interface WriteNativeSkillReceipt {
+    name: string;
+    scope: SkillScope;
+    directory: string;
+    path: string;
+}
+/** Raised when a write targets one of the four bundled workflow skill names. */
+export declare class SkillNameProtectedError extends Error {
+    readonly code = "SKILL_NAME_PROTECTED";
+    constructor(name: string);
+}
+/** Raised when skill content has no parseable frontmatter or lacks a description. */
+export declare class SkillFrontmatterError extends Error {
+    readonly code = "SKILL_FRONTMATTER_INVALID";
+    constructor(message: string);
+}
+/**
+ * Canonical project skill directories in precedence order: `.gjc/skills` in
+ * every ancestor from `cwd` up to the repo root (closest first).
+ */
+export declare function getProjectSkillDirs(cwd: string, home: string): Promise<{
+    dirs: string[];
+    repoRoot: string | null;
+}>;
+/** Canonical user skill directories in precedence order (same resolution as runtime discovery). */
+export declare function getUserSkillDirs(home: string): string[];
+/**
+ * The canonical directory a write targets for a scope: the repo root (or `cwd`)
+ * `.gjc/skills` for project scope, the canonical `<config>/agent/skills` user
+ * root for user scope (honoring `GJC_CONFIG_DIR` / `PI_CONFIG_DIR`).
+ */
+export declare function resolveNativeSkillScopeDir(cwd: string, scope: SkillScope, home?: string): Promise<string>;
+/**
+ * Authoritative discovery of native skills with provenance and enablement
+ * state. Unlike runtime session discovery, this lists every scanned skill —
+ * including disabled, shadowed, and protected ones — so `/extensions` and SDK
+ * consumers can show and toggle the full catalog.
+ */
+export declare function listNativeSkillsForManagement(options: {
+    cwd: string;
+    home?: string;
+    policy?: SkillManagementPolicy;
+}): Promise<ManagedSkillRecord[]>;
+/**
+ * Write a native skill into the canonical `.gjc` scope directory. The content
+ * must parse as frontmatter with a non-empty `description`; the effective name
+ * comes from `frontmatter.name` when present, else the requested `name`. Bundled
+ * workflow skill names are rejected.
+ */
+export declare function writeNativeSkill(input: WriteNativeSkillInput): Promise<WriteNativeSkillReceipt>;
+/** Whether a skill is enabled under the current policy (disabledExtensions/ignored/scope trust). */
+export declare function isNativeSkillEnabled(name: string, policy: SkillManagementPolicy | undefined): boolean;
+/**
+ * Toggle per-skill enablement by adding/removing the `skill:<name>` entry in
+ * `disabledExtensions`. Returns the updated list; the caller persists it through
+ * Settings. Bundled workflow skill names cannot be disabled.
+ */
+export declare function setNativeSkillEnabled(name: string, enabled: boolean, disabledExtensions: string[]): string[];
+/**
+ * Enumerate Claude Code / Codex skills (project and user scope) as explicit
+ * import sources into `.gjc`. This only reads the foreign layouts for
+ * inspection/import; nothing is loaded into sessions and user-home content is
+ * never used without an explicit import action (#4291).
+ */
+export declare function listConventionSkillImportSources(options: {
+    cwd: string;
+    home?: string;
+    host?: ConventionSkillHost | "all";
+}): Promise<ConventionSkillImportSource[]>;

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

@@ -33,4 +33,6 @@ export interface PersistedDeepInterviewSpec {
     statePath: string;
 }
 export declare function persistDeepInterviewSpec(cwd: string, resolved: ResolvedDeepInterviewSpecWriteArgs): Promise<PersistedDeepInterviewSpec>;
-export declare function runNativeDeepInterviewCommand(args: string[], cwd?: string): Promise<DeepInterviewCommandResult>;
+export declare function runNativeDeepInterviewCommand(args: string[], cwd?: string, options?: {
+    agentDir?: string;
+}): Promise<DeepInterviewCommandResult>;

package/dist/types/gjc-runtime/launch-worktree.d.ts

@@ -1,3 +1,4 @@
+import * as path from "node:path";
 export type GjcLaunchWorktreeMode = {
     enabled: false;
 } | {
@@ -27,6 +28,13 @@ export interface GjcLaunchWorktreeResult extends GjcLaunchWorktreePlan {
     createdBranch: boolean;
     dirty?: boolean;
 }
+/**
+ * Pure core of {@link resolveWorktreeBucket}, exported for tests.
+ *
+ * Injecting the home directory and path implementation lets tests exercise
+ * Windows drive/UNC/separator semantics (`path.win32`) on any host.
+ */
+export declare function resolveWorktreeBucketForPath(repoRoot: string, envValue: string | undefined, home: string, pathApi: typeof path.posix): string;
 export declare function parseLaunchWorktreeMode(args: string[]): ParsedLaunchWorktreeMode;
 export declare function planLaunchWorktree(cwd: string, mode: GjcLaunchWorktreeMode): GjcLaunchWorktreePlan | {
     enabled: false;

package/dist/types/gjc-runtime/linux-proc.d.ts

@@ -8,6 +8,7 @@
  * (`tty_nr`) is the 5th token after the closing paren (index 4).
  */
 export interface LinuxProcStatIdentity {
+    state?: string;
     startTime: string;
     ttyDevice: string;
 }
@@ -23,6 +24,8 @@ export type LinuxProcPidProbeResult = ({
 export declare function parseLinuxProcStartTime(stat: string | null | undefined): string | null;
 /** Parse field 7 (`tty_nr`) from a `/proc/<pid>/stat` record. */
 export declare function parseLinuxProcTtyDevice(stat: string | null | undefined): string | null;
+/** Parse field 3 (single-letter process state) from a `/proc/<pid>/stat` record. */
+export declare function parseLinuxProcState(stat: string | null | undefined): string | null;
 export declare function probeLinuxProcPidSync(pid: number): LinuxProcPidProbeResult;
 export declare function probeLinuxProcPid(pid: number): Promise<LinuxProcPidProbeResult>;
 /**

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

@@ -130,10 +130,10 @@ export declare function loadRalplanIndexForCap(cwd: string, sessionId: string, r
     rawText?: string;
 }>;
 /**
- * Resolve ralplan consensus iteration cap. Project `./.gjc/settings.json` overrides
- * user settings, else default 5.
+ * Resolve the ralplan consensus iteration cap through the shared resolver.
+ * Project `.gjc/config.yml` and `.gjc/settings.json` beat user layers.
  */
-export declare function resolveRalplanMaxIterations(cwd: string): Promise<{
+export declare function resolveRalplanMaxIterations(cwd: string, agentDir?: string): Promise<{
     maxIterations: number;
     source: string;
 }>;
@@ -145,13 +145,17 @@ type RalplanAutoHandoffOptions = {
         available: false;
         reason: string;
     };
+    /** The session's effective agent directory (see resolveWorkflowSetting). */
+    agentDir?: string;
 };
 export declare function resolveRalplanAutoHandoff(cwd: string, options?: RalplanAutoHandoffOptions): Promise<RalplanAutoHandoffResolution>;
-/** Resolve the per-lane review-pass budget with project-over-user precedence. */
-export declare function resolveRalplanMaxReviewPassesPerLane(cwd: string): Promise<{
+/** Resolve the per-lane review-pass budget through the shared resolver. */
+export declare function resolveRalplanMaxReviewPassesPerLane(cwd: string, agentDir?: string): Promise<{
     maxReviewPassesPerLane: number;
     source: string;
 }>;
 export declare function isRalplanArtifactWriteInvocation(args: readonly string[]): boolean;
-export declare function runNativeRalplanCommand(args: string[], cwd?: string): Promise<RalplanCommandResult>;
+export declare function runNativeRalplanCommand(args: string[], cwd?: string, options?: {
+    agentDir?: string;
+}): Promise<RalplanCommandResult>;
 export {};

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

@@ -0,0 +1,104 @@
+/**
+ * How a `<file>.lock` owner record can be opened safely on this platform.
+ *
+ * `posix-nofollow` proves the object's TYPE from the descriptor the bytes come off, so the
+ * pathname can change freely without ever being followed. Windows has neither `O_NOFOLLOW`
+ * nor `O_NONBLOCK`, so no such descriptor exists there and `windows-validated` brackets the
+ * open with `lstat`/`fstat` identity proofs instead. `unsupported` is neither, and the
+ * owner protocol fails closed rather than reading a pathname it cannot vouch for.
+ */
+export type SessionStateLockOwnerAccessStrategy = "posix-nofollow" | "windows-validated" | "unsupported";
+/**
+ * Select the safe owner-record access protocol for one platform/runtime pair.
+ *
+ * Platform identity comes first. A win32 runtime may expose numeric compatibility constants
+ * without providing POSIX no-follow semantics, so their mere presence must never select the
+ * POSIX path there.
+ *
+ * @internal Pure seam for cross-platform detection tests.
+ */
+export declare function detectedSessionStateLockOwnerAccessStrategy(platform: NodeJS.Platform, posixNoFollowAvailable: boolean): SessionStateLockOwnerAccessStrategy;
+/**
+ * Test seams for the windows a reclaim passes through: the moment the path's TYPE has just
+ * been decided and its owner has not been read yet, the stale verdict, and the FINAL
+ * identity validation immediately before the unlink. Production code never sets them.
+ */
+export declare const SessionStateLockTestHooks: {
+    afterLockTypeDecision?: (lockFile: string) => void | Promise<void>;
+    afterStaleInspection?: (lockFile: string) => void | Promise<void>;
+    beforeStaleRemoval?: (lockFile: string) => void | Promise<void>;
+    afterTransitionStaleInspection?: (transitionFile: string) => void | Promise<void>;
+    beforeTransitionStaleRemoval?: (transitionFile: string) => void | Promise<void>;
+    afterLegacyDirectoryStaleVerdict?: (lockDir: string) => void | Promise<void>;
+    /**
+     * @internal Which owner-access strategy to exercise, so the Windows path can be proved
+     * on the test filesystem this suite actually runs on. Production code never sets it,
+     * and it is never serialized or exposed as runtime configuration.
+     */
+    ownerAccessStrategy?: SessionStateLockOwnerAccessStrategy;
+    /**
+     * @internal How an owner pid is probed for liveness. Whether a signal is permitted is a
+     * property of the OS and this process's privileges, so it cannot be arranged on disk.
+     * Production code never sets it, and it is never serialized or exposed as runtime
+     * configuration.
+     */
+    probeProcessSignal?: (pid: number) => void;
+    /**
+     * @internal Runs inside a NEW owner record's write, after the exclusive create has
+     * taken the pathname and before the record's bytes land. Throwing from it fails that
+     * write exactly as an I/O fault does, which is the only deterministic way to reach the
+     * write-failure cleanup and prove what that cleanup is authorized to delete.
+     * Production code never sets it, and it is never serialized or exposed as runtime
+     * configuration.
+     */
+    ownerRecordWriteFault?: (file: string) => void | Promise<void>;
+    beforeLegacyDirectoryRemoval?: (lockDir: string) => void | Promise<void>;
+};
+/** Raised when the lock could not be acquired; callers map it to their own refusal. */
+export declare class SessionStateLockUnavailableError extends Error {
+    constructor(cause?: unknown);
+}
+/**
+ * The identity-bound deletion primitives this lock is built on.
+ *
+ * There is no portable atomic compare-and-delete in `fs`: validating a record and then
+ * unlinking its PATHNAME is always two syscalls, and a successor that claims the path in
+ * between loses its brand-new lock to the first reclaimer. These natives close that hole
+ * for real — every removal is descriptor-relative, no-follow, and refuses unless the
+ * object still carries the exact `dev`/`ino`/`nlink`/`size`/`mtimeNs`/SHA-256 identity the
+ * caller proved. A replacement is therefore never deleted, by construction rather than by
+ * a narrower window.
+ */
+export type SessionStateLockNativeBindings = Pick<typeof import("@gajae-code/natives"), "exactRemoveDirectoryTree" | "exactUnlink" | "snapshotDirectoryTree">;
+/** How the deletion primitives are obtained. Throwing means they are unavailable. */
+type SessionStateLockNativeLoader = () => SessionStateLockNativeBindings;
+/**
+ * @internal The seam focused TS tests bind a faithful in-process implementation to.
+ *
+ * It exists because the deletion contract — "refuse unless the object on disk still has
+ * exactly this identity" — is the thing under test, and a test double that merely reports
+ * success would assert nothing.
+ *
+ * A LOADER rather than a value, so the unavailable case needs no special production
+ * branch: a loader that throws is indistinguishable from an addon that will not load,
+ * which is the only way to observe that path where the addon is present. Passing
+ * `undefined` restores the real addon.
+ */
+export declare function setSessionStateLockNativeBindings(load: SessionStateLockNativeLoader | undefined): void;
+/**
+ * Decide what actually occupies the lock path, without following it.
+ *
+ * @internal exported as the seam these decisions are tested through: a live legacy
+ * directory owner must be provably left alone without waiting out a real stale window.
+ */
+export declare function reclaimStaleSessionStateLock(lockFile: string): Promise<void>;
+/**
+ * Serialize one read-modify-write of `stateFile` against every other holder of
+ * `<stateFile>.lock`.
+ *
+ * Taking the path, cleaning up a failed write, and releasing are all pathname transitions,
+ * so each runs under the transition claim — never the caller's operation, which holds the
+ * lock file itself and may run for as long as it needs.
+ */
+export declare function withSessionStateFileLock<T>(stateFile: string, operation: () => Promise<T>): Promise<T>;
+export {};