@gajae-code/coding-agent 0.13.2 → 0.14.0

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 {};

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

@@ -19,6 +19,8 @@ export type RuntimeInputReadyMarker = Readonly<{
     created_at: string;
 }>;
 export type RuntimeState = "ready_for_input" | "running" | "needs_user_input" | "completed" | "errored";
+/** Recorded whenever the caller could not prove a canonical public label for a tool. */
+export declare const UNPROVEN_TOOL_LABEL = "custom";
 /** Test-only counters for runtime sidecar hot-path assertions. */
 export declare const __sessionStateSidecarPerfCounters: {
     persistFromEventCalls: number;
@@ -28,9 +30,117 @@ interface RuntimeStateEvent {
     type: string;
     messages?: unknown[];
     toolCallId?: unknown;
-    toolName?: unknown;
     isError?: unknown;
 }
+export type RuntimeToolActivityPhase = "started" | "finished";
+/**
+ * A finished call's outcome. `cancelled` is the only honest answer for a call that was
+ * still in flight when the session settled: it neither succeeded nor failed, and nothing
+ * observed its end.
+ */
+export type RuntimeToolActivityOutcome = "success" | "failure" | "cancelled";
+/**
+ * What a session is doing right now, split into a bounded public projection and the
+ * minimum private state needed to keep that projection exact.
+ *
+ * Deliberately carries no tool arguments, results, command text, paths, output, prompt or
+ * model text, environment values, or credentials — only a proven public tool label, a
+ * phase, and timing.
+ */
+export interface RuntimeToolActivity {
+    seq: number;
+    last_activity_at: string;
+    tool: string;
+    phase: RuntimeToolActivityPhase;
+    outcome: RuntimeToolActivityOutcome | null;
+    elapsed_ms: number | null;
+    /** Exact number of in-flight calls; derived with `active_tools`, so it can never be smaller. */
+    active_tool_count: number;
+    /** Public projection of the newest in-flight calls, capped at `MAX_ACTIVE_TOOL_ENTRIES`. */
+    active_tools: Array<{
+        tool: string;
+        started_at: string;
+    }>;
+    /**
+     * Private exact correlation state. Each digest is one-way over the session id and the
+     * tool call id, so no raw call id is persisted, and the whole field is stripped by
+     * `publicRuntimeToolActivity` before any coordinator reader sees the snapshot.
+     */
+    in_flight: Array<{
+        digest: string;
+        tool: string;
+        started_at: string;
+    }>;
+}
+/**
+ * Collapses anything the caller could not prove into `custom`.
+ *
+ * Public safety comes from the caller's proof plus this closed vocabulary, never from a
+ * syntax check: a label that merely looks like a token is still model-influenced text.
+ */
+export declare function safeRuntimeToolLabel(value: unknown): string;
+export declare function toolActivityPhaseForEvent(event: RuntimeStateEvent): RuntimeToolActivityPhase | null;
+export type RuntimeToolActivityReadout = {
+    kind: "absent";
+} | {
+    kind: "malformed";
+} | {
+    kind: "valid";
+    activity: RuntimeToolActivity;
+};
+/**
+ * Re-validates an activity snapshot read back from disk.
+ *
+ * `absent` and `malformed` are deliberately distinct outcomes: an absent snapshot may be
+ * seeded from sequence 1, while a malformed one must never be replaced by a lower
+ * sequence. The public counters are re-derived from the private in-flight table rather
+ * than trusted from disk, so a hand-edited file cannot publish a contradiction.
+ */
+export declare function classifyRuntimeToolActivity(value: unknown): RuntimeToolActivityReadout;
+export declare function normalizedRuntimeToolActivity(value: unknown): RuntimeToolActivity | null;
+/**
+ * The only activity shape a coordinator reader may see: the private correlation digests
+ * are dropped here, so no projection can leak them, and a snapshot that contradicts the
+ * lifecycle state it accompanies is withheld entirely.
+ *
+ * Withheld, never repaired: the bytes on disk are preserved exactly as written — a
+ * malformed or contradictory snapshot is evidence — while every public projection shows
+ * nothing rather than a reconciled guess.
+ */
+export declare function publicRuntimeToolActivity(value: unknown, lifecycleState: unknown): Record<string, unknown> | null;
+/**
+ * What the caller observed at the exact moment the agent event was dispatched.
+ *
+ * Both the timestamp and the label are captured at that synchronous boundary, never
+ * re-derived here: a later lookup would see a tool registry that may already have been
+ * replaced, and a later clock reading would fold subscriber and lock latency into the
+ * measured interval.
+ */
+export interface CoordinatorToolObservation {
+    /** Canonical public label proven at the observation boundary; anything else is `custom`. */
+    label: string;
+    /** Wall clock captured when the agent event was observed, before any queueing or lock wait. */
+    observedAt: string;
+}
+/**
+ * Settle the activity snapshot a terminal lifecycle transition inherits.
+ *
+ * A settled session cannot still be running a tool, and later tool events are fenced out,
+ * so an unmatched start would otherwise leave a nonzero `active_tool_count` forever. The
+ * orphans are represented honestly — finished, `cancelled`, no elapsed interval — rather
+ * than claimed as a success or a failure nothing observed.
+ *
+ * The same helper serves the runtime `agent_end`/postmortem path and the Coordinator's
+ * canonical terminal repair so the two writers cannot settle differently.
+ *
+ * Two shapes need settling, not one. An orphaned in-flight call is the obvious case. The
+ * other is a `phase: started` snapshot with NOTHING correlated — a start whose call id was
+ * missing or blank never entered the in-flight table, so no end can ever close it — and
+ * leaving it would write the prohibited terminal+started pair, a settled session that
+ * still claims a tool is starting. An already-finished snapshot with nothing in flight is
+ * returned unchanged: a normal terminal transition is not an activity event.
+ */
+export declare function terminallySettledRuntimeToolActivity(value: unknown, observedAt: string): RuntimeToolActivityReadout;
 export interface OwnerTerminalContext {
     generation: string;
     stateDir: string;
@@ -68,8 +178,16 @@ export declare function readTerminalRuntimeStateMarker(input: {
     platform?: NodeJS.Platform;
 }): Promise<TerminalRuntimeStateStatus>;
 export declare function stateForEvent(event: RuntimeStateEvent): RuntimeState | null;
+/** True for every event the coordinator-shared file records: lifecycle state or tool activity. */
 export declare function eventAffectsCoordinatorRuntimeState(event: RuntimeStateEvent): boolean;
-export declare function persistCoordinatorRuntimeStateFromEvent(event: RuntimeStateEvent, context: RuntimeStateContext): Promise<void>;
+export declare function persistCoordinatorRuntimeStateFromEvent(event: RuntimeStateEvent, context: RuntimeStateContext, 
+/**
+ * What the caller observed at the synchronous agent-event boundary: the canonical
+ * public label it proved against the ACTIVE tool object, and the wall clock it read
+ * there. Without one, a tool event records `custom` at this writer's own clock — the
+ * sidecar never trusts a model-supplied name.
+ */
+observation?: CoordinatorToolObservation): Promise<void>;
 export declare function ownerTerminalContextFromEnvironment(): OwnerTerminalContext | "invalid" | null;
 export declare function persistCoordinatorRuntimeStateFromPostmortem(reason: postmortem.Reason, context: RuntimeStateContext): Promise<void>;
 export declare function registerCoordinatorRuntimeStateFinalizer(context: RuntimeStateContext): () => void;

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

@@ -74,11 +74,19 @@ export type GuardedWriteResult = {
     reason: "stale-skip";
     revision: number;
 };
+export interface GuardedStateWriteReceipt {
+    path: string;
+    revision: number;
+    stamped: unknown;
+}
+export declare function guardedStateWriteReceipt(result: GuardedWriteResult): GuardedStateWriteReceipt | undefined;
 export interface StateWriterOptions {
     cwd?: string;
     receipt?: StateWriterReceiptContext;
     audit?: StateWriterAuditContext;
     sourceRevision?: number;
+    /** Advance a cache source revision under the target lock when the value carries none. */
+    advanceSourceRevision?: boolean;
     /**
      * Cross-process lock tuning for read-modify-write paths that route through
      * `withWorkflowStateLock` / `updateJsonAtomic`. Omit for the hardened
@@ -150,6 +158,7 @@ export declare function detectWorkflowEnvelopeIntegrityMismatch(filePath: string
 type ActiveStateCacheInvalidator = (cwd?: string, sessionId?: string) => void;
 export declare function setActiveStateCacheInvalidator(invalidator: ActiveStateCacheInvalidator): void;
 export declare function persistedStateRevision(value: unknown): number;
+export declare function matchesGuardedStateWriteReceipt(current: unknown, receipt: GuardedStateWriteReceipt): boolean;
 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>;
@@ -222,7 +231,7 @@ export declare function removeFileAudited(targetPath: string, options?: StateWri
  * those entries, so concurrent snapshot rebuilds can race without losing any
  * writer's per-skill state.
  */
-export declare function writeActiveEntry(cwd: string, sessionScope: string | ActiveSessionScope | undefined, skill: string, entry: SkillActiveEntry, options?: StateWriterOptions): Promise<string>;
+export declare function writeActiveEntry(cwd: string, sessionScope: string | ActiveSessionScope | undefined, skill: string, entry: SkillActiveEntry, options?: StateWriterOptions): Promise<GuardedWriteResult>;
 export declare function removeActiveEntry(cwd: string, sessionScope: string | ActiveSessionScope | undefined, skill: string, options?: StateWriterOptions): Promise<DeleteResult>;
 export declare function readActiveEntries(cwd: string, sessionScope?: string | ActiveSessionScope): Promise<SkillActiveEntry[]>;
 export declare function rebuildActiveSnapshot(cwd: string, sessionScope?: string | ActiveSessionScope, options?: StateWriterOptions): Promise<string>;

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

@@ -61,7 +61,7 @@ export declare function formatUltragoalNudgeMessage(input: {
  * Resolves the active (leader) Ultragoal session so subagent/headless asks consume
  * the leader run's budget rather than a fresh child ledger.
  */
-export declare function consumeUltragoalAskNudge(cwd: string, sessionId?: string | null): Promise<{
+export declare function consumeUltragoalAskNudge(cwd: string, sessionId?: string | null, agentDir?: string): Promise<{
     nudged: true;
     message: string;
 } | {
@@ -71,6 +71,7 @@ export declare function assertCanCompleteCurrentGoal(input: {
     cwd: string;
     currentGoal?: CurrentGoalLike | null;
     sessionId?: string | null;
+    agentDir?: string;
 }): Promise<void>;
 export declare function isUltragoalBypassPrompt(prompt: string): boolean;
 export interface UltragoalPauseBlockDiagnostic {
@@ -85,7 +86,7 @@ export interface UltragoalPauseBlockDiagnostic {
  * 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>;
+export declare function assertUltragoalPauseAllowed(cwd: string, agentDir?: string): Promise<void>;
 /**
  * Guard `goal({"op":"drop"})` during an active Ultragoal run. A *real give-up* (an
  * aggregate run still mid-flight with incomplete required stories) is nudged while
@@ -98,4 +99,5 @@ export declare function assertUltragoalDropAllowed(input: {
     cwd: string;
     currentGoal?: CurrentGoalLike | null;
     sessionId?: string | null;
+    agentDir?: string;
 }): Promise<void>;

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

@@ -170,11 +170,11 @@ export declare const DEFAULT_ULTRAGOAL_NUDGE_BUDGET = 10;
 /** Pure: count ledger `nudge` rows for an exact goalId. */
 export declare function countUltragoalNudges(ledger: readonly UltragoalLedgerEvent[], goalId: string): number;
 /**
- * Resolve the per-story nudge budget. Project `./.gjc/settings.json` overrides the
- * user settings (`$GJC_CONFIG_DIR/settings.json` or `~/.gjc/settings.json`), else the
- * default. Mirrors the `gjc.deepInterview.ambiguityThreshold` user+project precedence.
+ * Resolve the per-story nudge budget through the shared five-layer resolver.
+ * Ultragoal stays tolerant: an invalid optional settings file continues to the
+ * next layer and finally to the built-in default (10).
  */
-export declare function resolveUltragoalNudgeBudget(cwd: string): Promise<{
+export declare function resolveUltragoalNudgeBudget(cwd: string, agentDir?: string): Promise<{
     budget: number;
     source: string;
 }>;
@@ -210,7 +210,7 @@ export declare function writePlan(cwd: string, plan: UltragoalPlan, sessionId?:
 export declare function nonEmptyString(value: unknown): string | null;
 export declare function stringArray(value: unknown): string[] | null;
 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 getUltragoalStatus(cwd: string, sessionId?: string | null, agentDir?: string): Promise<UltragoalStatusSummary>;
 export declare function buildUltragoalHudSummary(summary: UltragoalStatusSummary, latestLedger?: UltragoalLedgerEvent): WorkflowHudSummary;
 export declare function createUltragoalPlan(input: {
     cwd: string;
@@ -442,4 +442,6 @@ export declare class UltragoalReviewBlockerRecursionCapError extends Error {
     constructor(blockedGoalId: string, unresolvedDescents: number, cap?: number);
 }
 export declare function runUltragoalReview(cwd: string, args: readonly string[]): Promise<UltragoalReviewResult>;
-export declare function runNativeUltragoalCommand(args: string[], cwd?: string): Promise<UltragoalCommandResult>;
+export declare function runNativeUltragoalCommand(args: string[], cwd?: string, options?: {
+    agentDir?: string;
+}): Promise<UltragoalCommandResult>;

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

@@ -0,0 +1,109 @@
+/**
+ * Single source of precedence for the workflow settings surfaces.
+ *
+ * Every workflow runtime (ralplan, ultragoal, deep-interview) reads its
+ * settings through {@link resolveWorkflowSetting}; no runtime hand-rolls file
+ * discovery, YAML/JSON parsing, or key extraction. The precedence is fixed:
+ *
+ *   1. project `.gjc/config.yml`
+ *   2. user `<agentDir>/config.yml` (default `~/.gjc/agent/config.yml`)
+ *   3. built-in default
+ *
+ * Project configuration always beats user configuration, and `config.yml` is
+ * the primary settings surface: the legacy `settings.json` files (project and
+ * config-root) are retired, their workflow values migrated into `config.yml` by
+ * Settings once. The retained legacy source still applies while the migration
+ * has NOT durably recorded ownership/completion for its key: the project source
+ * until the per-key migrated-keys marker records the key, the config-root
+ * source until the migration retires it. A completed migration owns the value
+ * (a later `gjc config unset` sticks), so an owned key is never resurrected;
+ * the project legacy sits above the agent config.yml, the config-root legacy
+ * below it. Settings therefore writes exactly what the runtimes read: `gjc
+ * config set gjc.ralplan.maxIterations 7` is honored by ralplan.
+ *
+ * `config.yml` uses the nested schema form (`gjc: { ralplan: { maxIterations } }`);
+ * flat dotted keys are honored only while parsing a legacy `settings.json`
+ * during migration (see Settings) or the retained-legacy fallback layer.
+ *
+ * This module must stay pure and acyclic: it imports only path helpers and the
+ * pure `gjcRoot`/`dirs` utilities, never `Settings`, discovery/capability
+ * loaders, or workflow runtimes. All config/agent paths are constructed inside
+ * each resolver call (never at module scope) because `dirs.ts` caches directory
+ * resolution at module load.
+ */
+export type WorkflowSettingKey = "gjc.deepInterview.ambiguityThreshold" | "gjc.ralplan.autoHandoff" | "gjc.ralplan.maxIterations" | "gjc.ralplan.maxReviewPassesPerLane" | "gjc.ultragoal.nudgeBudget";
+export type WorkflowSettingLayer = "project-config" | "agent-config";
+export type WorkflowSettingParseResult<T> = {
+    kind: "valid";
+    value: T;
+} | {
+    kind: "invalid";
+    reason: string;
+};
+export type WorkflowSettingDiagnosticStatus = "missing-file" | "empty-document" | "missing-key" | "invalid" | "valid";
+export interface WorkflowSettingDiagnostic {
+    layer: WorkflowSettingLayer;
+    /** Lexical absolute candidate; missing paths stay actionable. */
+    path: string;
+    format: "yaml" | "json";
+    status: WorkflowSettingDiagnosticStatus;
+    classification?: "read" | "syntax" | "shape" | "value";
+    reason?: string;
+}
+export interface ResolveWorkflowSettingOptions<T> {
+    defaultValue: T;
+    parse: (value: unknown) => WorkflowSettingParseResult<T>;
+    /** Omitted means "continue"; ralplan passes "throw" explicitly. */
+    invalidPolicy?: "throw" | "continue";
+    /**
+     * The session's effective agent directory. Defaults to the process-global
+     * `getAgentDir()`; an SDK embedder that created the session with
+     * `createAgentSession({ agentDir })` must pass that directory here so the
+     * agent-config layer matches the profile `Settings.init` loaded and
+     * migrated, instead of inheriting an unrelated default-profile value.
+     */
+    agentDir?: string;
+}
+export interface WorkflowSettingResolution<T> {
+    value: T;
+    /** Canonical realpath for a winning existing file, or "default". */
+    source: string;
+    diagnostics: readonly WorkflowSettingDiagnostic[];
+}
+export type WorkflowSettingInvalidClassification = "read" | "syntax" | "shape" | "value";
+/** Raised under the strict ("throw") invalid policy; stable properties for callers. */
+export declare class WorkflowSettingError extends Error {
+    readonly diagnostic: WorkflowSettingDiagnostic;
+    readonly path: string;
+    readonly layer: WorkflowSettingLayer;
+    readonly classification: WorkflowSettingInvalidClassification;
+    readonly reason: string;
+    constructor(diagnostic: WorkflowSettingDiagnostic & {
+        classification: WorkflowSettingInvalidClassification;
+        reason: string;
+    });
+}
+/**
+ * Extract a workflow key from a parsed settings document. Flat dotted keys are
+ * honored only while parsing a legacy `settings.json` during migration (see
+ * Settings) - `config.yml` uses the nested (schema) form, so the public
+ * Settings/config CLI path (which addresses nested paths) can manage every
+ * effective override. Flat keys are checked before the nested `gjc: { ... }`
+ * shape (flat wins); an explicitly present `undefined` value counts as present.
+ */
+export declare function extractWorkflowSetting(document: unknown, key: WorkflowSettingKey, options?: {
+    flat?: boolean;
+}): {
+    present: boolean;
+    value: unknown;
+    malformedParent?: boolean;
+};
+/**
+ * Resolve a workflow setting across the fixed three-layer precedence (project
+ * `.gjc/config.yml`, then user `<agentDir>/config.yml`, then the built-in
+ * default). Returns the first valid configured value, otherwise
+ * {@link options.defaultValue} with `source: "default"`. Diagnostics are
+ * retained for unit tests and optional logging; runtime public wrappers expose
+ * their existing compact result shapes.
+ */
+export declare function resolveWorkflowSetting<T>(cwd: string, key: WorkflowSettingKey, options: ResolveWorkflowSettingOptions<T>): Promise<WorkflowSettingResolution<T>>;

package/dist/types/hooks/events.d.ts

@@ -0,0 +1,60 @@
+/** Stable canonical names used to compare hook surfaces without replacing runtime event types. */
+export declare const HookEventKind: {
+    readonly UserPromptSubmit: "user_prompt_submit";
+    readonly PreToolUse: "pre_tool_use";
+    readonly PostToolUse: "post_tool_use";
+    readonly Stop: "stop";
+    readonly SessionStart: "session_start";
+    readonly SessionShutdown: "session_shutdown";
+};
+export type HookEventKind = (typeof HookEventKind)[keyof typeof HookEventKind];
+export declare const HookAuthority: {
+    readonly Constrained: "constrained";
+    readonly Command: "command";
+    readonly InProcess: "in-process";
+};
+export type HookAuthority = (typeof HookAuthority)[keyof typeof HookAuthority];
+export declare const HookSourceConvention: {
+    readonly NativeGjc: "native-gjc";
+    readonly ClaudeCode: "claude-code";
+    readonly Codex: "codex";
+    readonly CodexManagedJson: "codex-managed-json";
+    readonly GjcPlugin: "gjc-plugin";
+    readonly InProcess: "in-process";
+};
+export type HookSourceConvention = (typeof HookSourceConvention)[keyof typeof HookSourceConvention];
+export interface HookEventSchemaContract {
+    kind: HookEventKind;
+    input: string;
+    output: string;
+}
+/**
+ * Canonical schema references. These point at existing runtime types; they are not a
+ * second runtime event union and do not change payloads dispatched by the hook runners.
+ */
+export declare const HOOK_EVENT_SCHEMAS: Record<HookEventKind, HookEventSchemaContract>;
+export type HookOrdering = "sequential" | "external-runtime";
+export type HookAwaitBehavior = "awaited" | "external-runtime";
+export type HookErrorBehavior = "isolate" | "fail-closed" | "external-runtime";
+export type HookProcessAuthority = "none" | "hook-api" | "command" | "ambient-host";
+export type HookTrustRequirement = "not-enforced" | "provider-owned";
+export type HookRedaction = "none" | "provider-owned";
+export interface HookExecutionContract {
+    kind: HookEventKind;
+    runtimeEvent: string;
+    authority: HookAuthority;
+    awaitBehavior: HookAwaitBehavior;
+    ordering: HookOrdering;
+    canCancel: boolean;
+    mutation: readonly string[];
+    timeoutMs: number | null;
+    errorBehavior: HookErrorBehavior;
+    processAuthority: HookProcessAuthority;
+    trustRequirement: HookTrustRequirement;
+    redaction: HookRedaction;
+    logging: string;
+    semanticNotes: string;
+}
+/** Per-convention execution truth. Missing entries are unsupported. */
+export declare const CONVENTION_EVENT_CONTRACTS: Record<HookSourceConvention, Partial<Record<HookEventKind, HookExecutionContract>>>;
+export declare const EXTERNAL_EVENT_ALIASES: Readonly<Record<string, HookEventKind>>;

package/dist/types/hooks/normalize.d.ts

@@ -0,0 +1,83 @@
+import { type HookAuthority, HookEventKind, type HookExecutionContract, HookSourceConvention } from "./events";
+export declare const HookDiagnosticSeverity: {
+    readonly Error: "error";
+    readonly Warning: "warning";
+};
+export type HookDiagnosticSeverity = (typeof HookDiagnosticSeverity)[keyof typeof HookDiagnosticSeverity];
+export declare const HookDiagnosticCode: {
+    readonly UnsupportedConventionEvent: "unsupported_convention_event";
+    readonly UnrecognizedPluginEvent: "unrecognized_plugin_event";
+    readonly InvalidPluginPhase: "invalid_plugin_phase";
+    readonly InvalidToolMatcher: "invalid_tool_matcher";
+    readonly InvalidSource: "invalid_source";
+    readonly InvalidCommand: "invalid_command";
+    readonly DuplicateHook: "duplicate_hook";
+    readonly InProcessEventOutsideIr: "in_process_event_outside_hook_ir";
+    readonly SemanticMismatch: "semantic_mismatch";
+};
+export type HookDiagnosticCode = (typeof HookDiagnosticCode)[keyof typeof HookDiagnosticCode];
+export interface HookNormalizationDiagnostic {
+    severity: HookDiagnosticSeverity;
+    code: HookDiagnosticCode;
+    message: string;
+    convention: HookSourceConvention;
+    externalEvent?: string;
+    canonicalKind?: HookEventKind;
+    source?: string;
+}
+export interface NormalizedHook {
+    kind: HookEventKind;
+    authority: HookAuthority;
+    convention: HookSourceConvention;
+    runtimeEvent: string;
+    toolName: string;
+    source: string;
+    contract: HookExecutionContract;
+}
+export interface NormalizeHookResult {
+    hook: NormalizedHook | null;
+    diagnostics: HookNormalizationDiagnostic[];
+}
+export declare function resolveExecutionContract(convention: HookSourceConvention, kind: HookEventKind): HookExecutionContract | null;
+export declare function resolveAuthority(convention: HookSourceConvention, kind: HookEventKind): HookAuthority | null;
+export declare function resolveCanonicalKind(externalEvent: string): HookEventKind | null;
+export declare function unsupportedEventDiagnostic(convention: HookSourceConvention, externalEvent: string, canonicalKind: HookEventKind | null, source?: string): HookNormalizationDiagnostic;
+/** Tool identifiers are logical, case-sensitive runtime names, not filesystem paths. */
+export declare function normalizeToolMatcher(toolName: unknown): string | null;
+export interface DirectoryHookInput {
+    convention: HookSourceConvention;
+    phase: "pre" | "post";
+    toolName: string;
+    source: string;
+    /** Original discovered filename, when normalization participates in discovery. */
+    externalName?: string;
+}
+/** Normalize discovery metadata for native, Claude, or Codex hook modules. */
+export declare function normalizeDirectoryHook(input: DirectoryHookInput): NormalizeHookResult;
+export interface ManagedJsonHookInput {
+    externalEvent: string;
+    command: string;
+    source: string;
+}
+/** Normalize the two GJC-managed Codex hooks.json entries. */
+export declare function normalizeManagedJsonHook(input: ManagedJsonHookInput): NormalizeHookResult;
+export interface PluginHookInput {
+    declaredEvent: string;
+    target?: unknown;
+    phase?: unknown;
+    plugin: string;
+    source: string;
+}
+/** Normalize only manifest shapes that the constrained plugin compiler accepts. */
+export declare function normalizePluginHook(input: PluginHookInput): NormalizeHookResult;
+export interface InProcessHookInput {
+    registeredEvent: string;
+    source: string;
+}
+export declare function normalizeInProcessHook(input: InProcessHookInput): NormalizeHookResult;
+export interface BatchNormalizeResult {
+    hooks: NormalizedHook[];
+    diagnostics: HookNormalizationDiagnostic[];
+}
+/** Stable first-wins deduplication; rejected and duplicate entries remain visible as diagnostics. */
+export declare function normalizeHookBatch(results: ReadonlyArray<NormalizeHookResult>): BatchNormalizeResult;

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

@@ -1,5 +1,5 @@
-import type { SkillDiscoverySettings } from "../config/skill-settings-defaults";
-import { type SkillActiveState } from "../skill-state/active-state";
+import { type SkillDiscoverySettings } from "../config/skill-settings-defaults";
+import { type SkillActiveEntry, type SkillActiveState } from "../skill-state/active-state";
 import { initialPhaseForSkill } from "../skill-state/initial-phase";
 export { initialPhaseForSkill };
 import { type GjcWorkflowSkill } from "./skill-keywords";
@@ -75,6 +75,12 @@ export interface EnsureWorkflowSkillActivationInput {
     turnId?: string;
     nowIso?: string;
     stateDir?: string;
+    activeSubskills?: SkillActiveEntry["active_subskills"];
+}
+export interface WorkflowSkillActivationSeed {
+    state: SkillActiveState | null;
+    seeded: boolean;
+    rollback(): Promise<boolean>;
 }
 /**
  * Idempotently seed `.gjc/state` for a workflow skill that was invoked directly
@@ -87,6 +93,7 @@ export interface EnsureWorkflowSkillActivationInput {
  * `handoff_from`/`handoff_at` lineage), nothing is written so lineage is
  * preserved. Non-workflow skills are ignored.
  */
+export declare function ensureWorkflowSkillActivationSeed(input: EnsureWorkflowSkillActivationInput): Promise<WorkflowSkillActivationSeed>;
 export declare function ensureWorkflowSkillActivationState(input: EnsureWorkflowSkillActivationInput): Promise<SkillActiveState | null>;
 export declare function buildActiveUltragoalPromptContext(input: UserPromptSubmitStateInput): Promise<string | null>;
 export declare function buildSkillStopOutput(input: StopHookInput): Promise<Record<string, unknown> | null>;

package/dist/types/main.d.ts

@@ -41,7 +41,7 @@ export declare function initializeInteractiveModeWithStartupUpdate(mode: Startup
  * Every other local-session flag is rejected so the broker-backed ACP host
  * never appears to accept options it cannot apply to its remote session.
  */
-export declare function resolveAcpStartupOptions(parsed: Pick<Args, "allowHome" | "apiKey" | "appendSystemPrompt" | "credential" | "continue" | "default" | "cwd" | "fileArgs" | "fork" | "hooks" | "messages" | "mpreset" | "mcpConfig" | "model" | "models" | "noLsp" | "noPty" | "noRules" | "noSession" | "noSkills" | "noTitle" | "noTools" | "pluginDirs" | "print" | "provider" | "providerSessionId" | "resume" | "sessionDir" | "skills" | "slow" | "smol" | "plan" | "systemPrompt" | "thinking" | "tmux" | "tools" | "extensions" | "unknownFlags">, sessionOptions: Pick<CreateAgentSessionOptions, "model" | "modelPattern" | "thinkingLevel">): AcpStartupOptions;
+export declare function resolveAcpStartupOptions(parsed: Pick<Args, "allowHome" | "apiKey" | "appendSystemPrompt" | "credential" | "preferCredential" | "continue" | "default" | "cwd" | "fileArgs" | "fork" | "hooks" | "messages" | "mpreset" | "mcpConfig" | "model" | "models" | "noLsp" | "noMcp" | "noPty" | "noRules" | "noSession" | "noSkills" | "noTitle" | "noTools" | "pluginDirs" | "print" | "provider" | "providerSessionId" | "resume" | "sessionDir" | "skills" | "slow" | "smol" | "plan" | "systemPrompt" | "thinking" | "tmux" | "tools" | "extensions" | "unknownFlags">, sessionOptions: Pick<CreateAgentSessionOptions, "model" | "modelPattern" | "thinkingLevel">): AcpStartupOptions;
 declare function readPipedInput(): Promise<string | undefined>;
 export interface InteractiveModeNotify {
     kind: "warn" | "error" | "info";
@@ -132,6 +132,7 @@ export interface RunRootCommandDependencies {
     getChangelogForDisplay?: typeof getChangelogForDisplay;
     createInteractiveMode?: CreateInteractiveMode;
     runPrintMode?: RunPrintMode;
+    quit?: (code: number) => Promise<void>;
     isResumePickerTerminal?: ResumePickerTerminalCheck;
     listForResumePickerReadOnly?: ListForResumePickerReadOnly;
     listManagedForResumePickerReadOnly?: ListManagedForResumePickerReadOnly;