@gajae-code/coding-agent 0.11.11 → 0.12.1

package/dist/types/exa/mcp-client.d.ts

@@ -1,7 +1,16 @@
 import type { TSchema } from "@gajae-code/ai";
 import type { CustomTool, CustomToolResult } from "../extensibility/custom-tools/types";
 import type { ExaRenderDetails, ExaSearchResponse, MCPTool, MCPToolWrapperConfig } from "./types";
-/** Find EXA_API_KEY from Bun.env or .env files */
+/**
+ * Find `EXA_API_KEY` from trusted environment sources.
+ *
+ * The key authenticates every Exa MCP call and travels in the request URL, so
+ * whatever can set it decides which account the agent's searches run through —
+ * and therefore who can see those queries. `$env` merges the caller's `cwd/.env`
+ * into `process.env`, so reading it there would let repository content supply
+ * that account. Resolve it the same way provider credentials are: launching
+ * shell plus GJC/user-owned `.env` files, never the project `.env`.
+ */
 export declare function findApiKey(): string | null;
 /** Fetch available tools from Exa MCP */
 export declare function fetchExaTools(apiKey: string | null, toolNames: string[]): Promise<MCPTool[]>;

package/dist/types/exec/bash-executor.d.ts

@@ -1,6 +1,43 @@
 import { type MinimizerOptions } from "@gajae-code/natives";
 import { type ShellMinimizerSettings } from "../config/settings";
+import { type TerminalArtifactPublisher } from "../session/streaming-output";
+export interface BashArtifactSaveSummary {
+    artifactId: string;
+    complete: boolean;
+    omittedBytes?: number;
+}
+export type BashMinimizedSaveReturn = BashArtifactSaveResult | BashArtifactSaveSummary | string | undefined;
+export type BashArtifactSaveResult = {
+    status: "saved";
+    artifactId: string;
+    complete: true;
+    omittedBytes?: undefined;
+} | {
+    status: "saved";
+    artifactId: string;
+    complete: false;
+    omittedBytes: number;
+} | {
+    status: "unavailable";
+} | {
+    status: "failed";
+    diagnostic: string;
+};
+export declare function normalizeMinimizedSaveResultForTests(value: BashMinimizedSaveReturn, originalText: string): BashArtifactSaveResult;
 export interface BashExecutorOptions {
+    /**
+     * Invoked when the native minimizer rewrote the command's output, giving
+     * the caller a chance to persist the lossless original capture (typically
+     * via the session's `ArtifactManager`). Complete saves preserve the
+     * historical `[raw output: artifact://<id>]` footer; capped saves carry an
+     * honest retained/omitted reference. A legacy string id is still accepted
+     * for non-tool callers and is classified from the original UTF-8 byte count.
+     */
+    onMinimizedSave?: (originalText: string, info: {
+        filter: string;
+        inputBytes: number;
+        outputBytes: number;
+    }) => Promise<BashMinimizedSaveReturn>;
     cwd?: string;
     timeout?: number | null;
     onChunk?: (chunk: string) => void;
@@ -19,24 +56,18 @@ export interface BashExecutorOptions {
     /** Artifact path/id for full output storage */
     artifactPath?: string;
     artifactId?: string;
+    /** Optional terminal publisher for managed artifacts without writable paths. */
+    artifactPublisher?: TerminalArtifactPublisher;
+    /** Optional Bash-specific retained tail budget in bytes. */
+    spillThreshold?: number;
+    /** Optional Bash-specific retained head budget in bytes. */
+    headBytes?: number;
     /** Execute without retaining a native Shell in the persistent session registry. */
     oneShot?: boolean;
     /** Ignore user-configured shell command prefixes. Used by constrained read-only shells. */
     ignoreShellPrefix?: boolean;
     /** Skip sourced shell snapshots. Used by constrained read-only shells. */
     disableShellSnapshot?: boolean;
-    /**
-     * Invoked when the native minimizer rewrote the command's output, giving
-     * the caller a chance to persist the lossless original capture (typically
-     * via the session's `ArtifactManager`). The returned id is spliced into
-     * the sink output as `artifact://<id>` so the agent can retrieve the raw
-     * bytes. Return `undefined` to skip the footer.
-     */
-    onMinimizedSave?: (originalText: string, info: {
-        filter: string;
-        inputBytes: number;
-        outputBytes: number;
-    }) => Promise<string | undefined>;
 }
 export interface BashResult {
     output: string;
@@ -48,6 +79,8 @@ export interface BashResult {
     outputLines: number;
     outputBytes: number;
     artifactId?: string;
+    artifactTruncatedBytes?: number;
+    artifactFailureDiagnostic?: string;
 }
 /** Number of persistent shell sessions currently retained (owner gauge). */
 export declare function getShellSessionCount(): number;

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

@@ -7,7 +7,7 @@
  * - Register commands, keyboard shortcuts, and CLI flags
  * - Interact with the user via UI primitives
  */
-import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel } from "@gajae-code/agent-core";
+import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, RunSettlementProof, ThinkingLevel } from "@gajae-code/agent-core";
 import type { CompactionResult } from "@gajae-code/agent-core/compaction";
 import type { Api, AssistantMessageEvent, AssistantMessageEventStream, Context, ImageContent, Model, ProviderResponseMetadata, SimpleStreamOptions, Static, TextContent, Tool, TSchema, UsageReport } from "@gajae-code/ai";
 import type { OAuthCredentials, OAuthLoginCallbacks } from "@gajae-code/ai/utils/oauth/types";
@@ -22,7 +22,7 @@ import type { ExecOptions, ExecResult } from "../../exec/exec";
 import type { CustomEditor } from "../../modes/components/custom-editor";
 import type { WorkflowGateEmitter } from "../../modes/shared/agent-wire/workflow-gate-broker";
 import type { Theme } from "../../modes/theme/theme";
-import type { ClientBridgePermissionOption, ClientBridgePermissionOutcome, ClientBridgePermissionToolCall } from "../../session/client-bridge";
+import type { ClientBridge, ClientBridgePermissionOption, ClientBridgePermissionOutcome, ClientBridgePermissionToolCall } from "../../session/client-bridge";
 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";
@@ -249,8 +249,14 @@ export interface ExtensionContext {
     model: Model | undefined;
     /** Whether the agent is idle (not streaming) */
     isIdle(): boolean;
+    /** Stable resource ownership identifier for the active prompt run. */
+    getActivePromptHandle(): string | undefined;
     /** Abort the current agent operation */
     abort(): void;
+    /** Abort and prove whether resources for a specific prompt settled. */
+    abortPromptAndWait?(handle: string, options: {
+        graceMs: number;
+    }): Promise<RunSettlementProof>;
     /** Whether there are queued messages waiting */
     hasPendingMessages(): boolean;
     /** Typed pending-message counts per queue (steering, follow-up, next-turn). */
@@ -291,13 +297,24 @@ export interface ExtensionContext {
     } | undefined>;
     getJobs(): unknown;
     /** Typed skill and mode controls exposed to the SDK host. */
-    invokeSkill?(name: string, args?: string): Promise<unknown>;
+    invokeSkill?(name: string, args?: string, options?: {
+        onPreflightAccepted?: () => void;
+        onPreflightAcceptCommit?: () => void | Promise<void>;
+        onSkillPrepared?: (meta: {
+            name: string;
+            path: string;
+            lineCount?: number;
+            cleanedArgs?: string;
+        }) => void;
+    }): Promise<unknown>;
     setPlanMode?(on: boolean): unknown;
     operateGoal?(op: "create" | "get" | "resume" | "pause" | "complete" | "drop", objective?: string): Promise<unknown>;
     /** Typed nonvisual session controls exposed to the SDK host. */
     sdkControl?(operation: string, input: Record<string, unknown>): unknown | Promise<unknown>;
     /** Install a permission callback backed by a live SDK reverse provider lease. */
     setSdkPermissionProvider?(provider: ((toolCall: ClientBridgePermissionToolCall, options: ClientBridgePermissionOption[], signal?: AbortSignal) => Promise<ClientBridgePermissionOutcome>) | undefined): void;
+    /** Install a client bridge backed by a live SDK reverse provider lease. */
+    setSdkClientBridge?(bridge: ClientBridge | undefined): void;
     /** Names of session SDK seams actually installed by the active runtime. */
     sdkBindings?(): readonly string[];
     /** Gracefully shutdown and exit. */
@@ -760,6 +777,7 @@ export interface ExtensionAPI {
     sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
         deliverAs?: "steer" | "followUp";
         onPreflightAccepted?: () => void;
+        onPreflightAcceptCommit?: () => void | Promise<void>;
     }): Promise<void>;
     /** Append a custom entry to the session for state persistence (not sent to LLM). */
     appendEntry<T = unknown>(customType: string, data?: T): void;
@@ -933,6 +951,7 @@ options?: {
 export type SendUserMessageHandler = (content: string | (TextContent | ImageContent)[], options?: {
     deliverAs?: "steer" | "followUp";
     onPreflightAccepted?: () => void;
+    onPreflightAcceptCommit?: () => void | Promise<void>;
 }) => void | Promise<void>;
 export type AppendEntryHandler = <T = unknown>(customType: string, data?: T) => void;
 export type GetActiveToolsHandler = () => string[];
@@ -990,7 +1009,12 @@ export interface ExtensionActions {
 export interface ExtensionContextActions {
     getModel: () => Model | undefined;
     isIdle: () => boolean;
+    /** Stable resource ownership identifier for the active prompt run. */
+    getActivePromptHandle?: () => string | undefined;
     abort: () => void;
+    abortPromptAndWait?: (handle: string, options: {
+        graceMs: number;
+    }) => Promise<RunSettlementProof>;
     hasPendingMessages: () => boolean;
     /** Typed pending-message counts per queue; optional for embedders without a counted queue. */
     getPendingMessageCounts?: () => {
@@ -1036,8 +1060,18 @@ export interface ExtensionContextActions {
     } | undefined>;
     getJobs?: () => unknown;
     setSdkPermissionProvider?: (provider: ((toolCall: ClientBridgePermissionToolCall, options: ClientBridgePermissionOption[], signal?: AbortSignal) => Promise<ClientBridgePermissionOutcome>) | undefined) => void;
+    setSdkClientBridge?: (bridge: ClientBridge | undefined) => void;
     sdkControl?: (operation: string, input: Record<string, unknown>) => unknown | Promise<unknown>;
-    invokeSkill?: (name: string, args?: string) => Promise<unknown>;
+    invokeSkill?: (name: string, args?: string, options?: {
+        onPreflightAccepted?: () => void;
+        onPreflightAcceptCommit?: () => void | Promise<void>;
+        onSkillPrepared?: (meta: {
+            name: string;
+            path: string;
+            lineCount?: number;
+            cleanedArgs?: string;
+        }) => void;
+    }) => Promise<unknown>;
     setPlanMode?: (on: boolean) => unknown;
     operateGoal?: (op: "create" | "get" | "resume" | "pause" | "complete" | "drop", objective?: string) => Promise<unknown>;
 }

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

@@ -2,14 +2,24 @@ export * from "./activation";
 export * from "./compiler";
 export * from "./constrained-hooks";
 export * from "./injection";
-export * from "./installer";
+/**
+ * Public barrel. Mutation primitives are deliberately NOT re-exported here:
+ * `lifecycle.ts` is the sole policy and persistence writer, so the installer
+ * transaction and the registry writers stay reachable only through their own
+ * modules. Re-exporting them would let a caller commit a replacement and
+ * bypass the create-only rule.
+ */
+export { isGjcPluginBundleSource, isGjcPluginSourceShape } from "./installer";
+export * from "./lifecycle";
+export * from "./lifecycle-reconciliation";
 export * from "./loader";
 export * from "./mcp-policy";
 export * from "./observability";
 export * from "./paths";
 export * from "./prompt-appendix";
-export * from "./registry";
+export { loadEffectiveGjcPluginRegistry, readRegistry, registryEntryFingerprint, registryPathForScope, registryRootForScope, sortRegistryEntries, } from "./registry";
 export * from "./runtime-adapters";
+export * from "./runtime-quarantine";
 export * from "./schema";
 export * from "./session-validation";
 export * from "./state";

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

@@ -1,13 +1,69 @@
-import { type GjcPluginRegistryEntry, type GjcPluginScope } from "./types";
-export interface InstallGjcPluginOptions {
+import { type GjcLifecycleError, type GjcPluginRegistry, type GjcPluginRegistryEntry, type GjcPluginRegistrySource, type GjcPluginScope, type NormalizedGjcPluginBundle } from "./types";
+export interface GjcBundleTransactionOptions {
     scope: GjcPluginScope;
     cwd: string;
-    force?: boolean;
+    /**
+     * Policy hook evaluated while both scope locks are held. It decides whether
+     * to commit the candidate, report an already-satisfied no-op, or abort with
+     * a typed lifecycle error. Only the lifecycle service supplies this.
+     */
+    decide: (input: GjcBundleTransactionContext) => Promise<GjcBundleTransactionDecision>;
 }
-export interface InstallGjcPluginResult {
-    status: "installed" | "updated" | "unchanged";
-    entry: GjcPluginRegistryEntry;
+export interface GjcBundleTransactionContext {
+    targetRegistry: GjcPluginRegistry;
+    /** Both scopes, deterministically sorted, for cross-scope decisions. */
+    effective: GjcPluginRegistryEntry[];
+    existing: GjcPluginRegistryEntry | undefined;
+    bundle: NormalizedGjcPluginBundle;
+    /** Entry the candidate would produce if committed as-is. */
+    candidate: GjcPluginRegistryEntry;
 }
-export declare function installGjcPluginBundle(source: string, options: InstallGjcPluginOptions): Promise<InstallGjcPluginResult>;
+export type GjcBundleTransactionDecision = {
+    kind: "commit";
+    entry: GjcPluginRegistryEntry;
+} | {
+    kind: "noop";
+    entry: GjcPluginRegistryEntry;
+} | {
+    kind: "abort";
+    error: GjcLifecycleError;
+};
+export type GjcBundleTransactionResult = {
+    status: "committed";
+    entry: GjcPluginRegistryEntry;
+    remnants: string[];
+} | {
+    status: "noop";
+    entry: GjcPluginRegistryEntry;
+    remnants: string[];
+} | {
+    status: "aborted";
+    error: GjcLifecycleError;
+    remnants: string[];
+};
+/**
+ * Serialized bundle transaction: prepare outside the locks, then hold the
+ * user->project locks in a fixed order so the decision sees a consistent
+ * cross-scope view. Only the target scope is ever committed.
+ */
+export declare function runGjcBundleTransaction(source: string, options: GjcBundleTransactionOptions): Promise<GjcBundleTransactionResult>;
+/** Compile a source into a validated candidate bundle without touching disk state. */
+export declare function resolveGjcBundleCandidate<T>(source: string, fn: (input: {
+    bundle: NormalizedGjcPluginBundle;
+    source: GjcPluginRegistrySource;
+}) => Promise<T>): Promise<T>;
+/** Build the registry entry a candidate bundle would produce at a target path. */
+export declare function candidateRegistryEntry(bundle: NormalizedGjcPluginBundle, scope: GjcPluginScope, cwd: string, source: GjcPluginRegistrySource, now: string): GjcPluginRegistryEntry;
+/**
+ * True when a spec has the SHAPE of a GJC bundle source: a filesystem path, a
+ * git locator, or a tarball. This is a pure string test that never touches the
+ * filesystem or the network, so a deleted or unreachable source is still
+ * recognised as GJC-intent and can reach the lifecycle's typed refusal instead
+ * of falling through to npm.
+ *
+ * npm and marketplace specs are never path/git/tarball shaped, so this cleanly
+ * separates the two install worlds.
+ */
+export declare function isGjcPluginSourceShape(source: string): boolean;
 /** True only when the source actually resolves to a GJC plugin bundle (root gajae-plugin.json). */
 export declare function isGjcPluginBundleSource(source: string): Promise<boolean>;

package/dist/types/extensibility/gjc-plugins/lifecycle-reconciliation.d.ts

@@ -0,0 +1,55 @@
+import { type GjcBundleIdentity, type GjcPluginQuarantineEntry, type GjcPluginRegistryEntry, type GjcPluginScope, type NormalizedGjcPluginBundle, type NormalizedGjcPluginSurfaces } from "./types";
+export declare function bundleIdentity(scope: GjcPluginScope, name: string): GjcBundleIdentity;
+export declare function identityKey(identity: GjcBundleIdentity): string;
+export declare function identityEquals(a: GjcBundleIdentity, b: GjcBundleIdentity): boolean;
+/** All stable surface IDs of a surface set, sorted and de-duplicated. */
+export declare function surfaceIdsOf(surfaces: NormalizedGjcPluginSurfaces): string[];
+/**
+ * Fingerprint of the exact installed target: identity plus the persisted bytes
+ * that any update must not silently replace.
+ */
+export declare function targetFingerprint(entry: GjcPluginRegistryEntry): string;
+/**
+ * Fingerprint of the exact installed baseline an update compares against: the
+ * installed content, the persisted enablement intent it must carry forward,
+ * and the stored source descriptor the update re-resolves from.
+ *
+ * Toggling the bundle or any surface changes this, so a preview taken before
+ * the toggle can no longer be applied. Binding the source matters just as much:
+ * apply re-resolves `entry.source.uri` before taking the locks, so a descriptor
+ * that changed in between must invalidate the reviewed baseline rather than let
+ * an update be committed from a locator the reviewer never saw.
+ */
+export declare function baselineFingerprint(entry: GjcPluginRegistryEntry): string;
+/** Fingerprint of an update candidate before it is written anywhere. */
+export declare function candidateFingerprint(scope: GjcPluginScope, bundle: NormalizedGjcPluginBundle): string;
+/**
+ * Fingerprint of everything besides the target and candidate bytes that the
+ * update decision depended on: opposite-scope same-name entries and the
+ * effective collision universe.
+ */
+export declare function decisionContextFingerprint(target: GjcBundleIdentity, effectiveEntries: readonly GjcPluginRegistryEntry[]): string;
+/**
+ * Fingerprint of the inputs that decide live activation. Changes here (and only
+ * here) advance the activation generation.
+ */
+export declare function activationFingerprint(entries: readonly GjcPluginRegistryEntry[]): string;
+export interface ReconciledEnablement {
+    disabledSurfaceIds: string[];
+    quarantine: GjcPluginQuarantineEntry[];
+}
+/**
+ * Carry persisted enablement intent across an update:
+ * - surviving disabled IDs stay disabled,
+ * - IDs whose surface disappeared are dropped,
+ * - new surface IDs are enabled by omission,
+ * - quarantine is recomputed from candidateQuarantine against the candidate's
+ *   surface set; omitted input means no candidate quarantine is justified.
+ */
+export declare function reconcileEnablement(previousDisabledSurfaceIds: readonly string[], candidateSurfaceIds: readonly string[], candidateQuarantine?: readonly GjcPluginQuarantineEntry[]): ReconciledEnablement;
+export interface SurfaceDelta {
+    addedSurfaceIds: string[];
+    removedSurfaceIds: string[];
+    retainedSurfaceIds: string[];
+}
+export declare function diffSurfaceIds(currentSurfaceIds: readonly string[], candidateSurfaceIds: readonly string[]): SurfaceDelta;

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

@@ -0,0 +1,64 @@
+import type { GjcBundleIdentity, GjcBundleSummary, GjcInstallResult, GjcLifecycleResult, GjcPluginRegistryEntry, GjcPluginRegistrySource, GjcPluginScope, GjcReviewedUpdateToken, GjcToggleResult, GjcUpdateApplyResult, GjcUpdatePreview } from "./types";
+/**
+ * GJC bundle lifecycle service.
+ *
+ * This module is the ONLY policy and persistence writer for GJC bundles: fresh
+ * install, update preview/apply, bundle enable/disable, and surface
+ * enable/disable. Callers (CLI, Settings) never touch the registry writers or
+ * the installer transaction directly.
+ */
+export interface GjcLifecycleContext {
+    cwd: string;
+}
+export declare function redactSourceLocator(source: GjcPluginRegistrySource): string;
+/** Safe, redacted DTO for one installed bundle. */
+export declare function toBundleSummary(entry: GjcPluginRegistryEntry): GjcBundleSummary;
+/**
+ * Rebuild the exact locator an update must re-resolve from. A git ref is stored
+ * separately from the URI, so re-resolving the bare URI would silently drop the
+ * reviewed branch or tag and update from the default branch instead.
+ */
+declare function storedSourceLocator(source: GjcPluginRegistrySource): string;
+/** Exposed for locator-reconstruction tests; not part of the lifecycle API. */
+export declare const storedSourceLocatorForTest: typeof storedSourceLocator;
+/** Exposed so a test can pin parity with the installer's source predicates. */
+export declare const isLocalDirectorySourceForTest: typeof isLocalDirectorySource;
+/** All installed bundles across both scopes, deterministically ordered. */
+export declare function listGjcBundles(ctx: GjcLifecycleContext): Promise<GjcBundleSummary[]>;
+/** One bundle by exact (scope, name) identity. Opposite scope never matches. */
+export declare function getGjcBundle(ctx: GjcLifecycleContext, identity: GjcBundleIdentity): Promise<GjcLifecycleResult<GjcBundleSummary>>;
+/**
+ * True only for strings the installer would treat as a local path rather than
+ * a remote locator. This deliberately mirrors the installer's own `looksLikeGit`
+ * predicate: if the two ever disagreed, a remote locator could be read as a
+ * relative path and shadowed by a local directory of the same shape.
+ */
+declare function isLocalDirectorySource(source: string): boolean;
+/**
+ * Fresh install only. An existing target in the same scope is create-only and
+ * is refused identically with or without force; upgrading is a separate,
+ * scope-qualified operation.
+ */
+export declare function installGjcBundle(ctx: GjcLifecycleContext, scope: GjcPluginScope, source: string): Promise<GjcLifecycleResult<GjcInstallResult>>;
+/**
+ * Re-resolve the stored source descriptor and describe what an update would do.
+ * The returned token binds the candidate, the exact installed baseline, and the
+ * deterministic decision context; apply is a compare-and-swap on all three.
+ */
+export declare function previewGjcBundleUpdate(ctx: GjcLifecycleContext, identity: GjcBundleIdentity): Promise<GjcLifecycleResult<GjcUpdatePreview>>;
+/**
+ * Apply a previously reviewed update. Any drift in the candidate bytes, the
+ * installed baseline, or the decision context returns a typed stale error with
+ * zero mutation.
+ */
+export declare function applyGjcBundleUpdate(ctx: GjcLifecycleContext, token: GjcReviewedUpdateToken): Promise<GjcLifecycleResult<GjcUpdateApplyResult>>;
+/**
+ * Enable or disable a whole bundle. Deterministic quarantine blocks enabling;
+ * disabling is always allowed so operators can always de-escalate.
+ */
+export declare function setGjcBundleEnabled(ctx: GjcLifecycleContext, identity: GjcBundleIdentity, enabled: boolean): Promise<GjcLifecycleResult<GjcToggleResult>>;
+/** Enable or disable one surface of a bundle by its stable extension ID. */
+export declare function setGjcBundleSurfaceEnabled(ctx: GjcLifecycleContext, identity: GjcBundleIdentity, surfaceId: string, enabled: boolean): Promise<GjcLifecycleResult<GjcToggleResult>>;
+/** Deterministic activation generation for the current persisted state. */
+export declare function currentActivationFingerprint(ctx: GjcLifecycleContext): Promise<string>;
+export {};

package/dist/types/extensibility/gjc-plugins/runtime-quarantine.d.ts

@@ -0,0 +1,67 @@
+import type { GjcBundleIdentity, GjcRuntimeFinding, GjcRuntimeSnapshot, GjcRuntimeSnapshotState } from "./types";
+/**
+ * Deterministic numeric activation generation for an activation fingerprint.
+ *
+ * Equal activation inputs yield an equal generation, so a consumer holding a
+ * snapshot can tell whether it still describes the state it is rendering.
+ * Derived from the fingerprint's leading hex so it stays inside the safe
+ * integer range.
+ */
+export declare function gjcActivationGenerationFor(activationFingerprint: string): number;
+/**
+ * Caller-owned accumulator for scope-qualified runtime evidence.
+ *
+ * Producers (loaders, adapters, validators) hand findings to an accumulator
+ * they were given; they never publish. Exactly one coordinator publishes a
+ * complete generation snapshot, and consumers merge it only when the identity
+ * and generation match.
+ */
+export declare class GjcRuntimeFindingAccumulator {
+    readonly generation: number;
+    private readonly findings;
+    constructor(generation: number);
+    add(finding: GjcRuntimeFinding): void;
+    addAll(findings: readonly GjcRuntimeFinding[]): void;
+    /** Sorted, de-duplicated snapshot for the generation this accumulator owns. */
+    snapshot(): GjcRuntimeSnapshot;
+}
+/** Read-only view of the most recently published complete generation. */
+export interface GjcRuntimeSnapshotProvider {
+    current(): GjcRuntimeSnapshotState;
+}
+/**
+ * Single-writer publisher for runtime evidence.
+ *
+ * Passes can overlap: the session's prompt rebuild is re-entrant, so a second
+ * pass may start while a first is still awaiting its producers. Publication is
+ * therefore fenced by a monotonic epoch. A pass reserves an epoch when it
+ * begins, which immediately retires whatever was published before, and its
+ * later publish is accepted only if no newer pass has reserved since. A slow or
+ * failed older pass can never overwrite a newer one, and an incomplete pass
+ * simply never publishes, leaving consumers at `unavailable`.
+ */
+export declare class GjcRuntimeSnapshotStore implements GjcRuntimeSnapshotProvider {
+    private state;
+    private epoch;
+    /**
+     * Begin a pass. Retires the current snapshot and returns the epoch token the
+     * caller must present to publish.
+     */
+    beginPass(): number;
+    /** Publish only if `epoch` is still the newest reserved pass. */
+    publish(snapshot: GjcRuntimeSnapshot, epoch?: number): void;
+    invalidate(): void;
+    current(): GjcRuntimeSnapshotState;
+}
+/**
+ * Findings for one bundle, but only when the snapshot is current AND describes
+ * the exact generation the consumer is rendering. Missing provider, mismatched
+ * generation, or unavailable state resolve to `unavailable` — never to a
+ * silently empty "clear" result.
+ */
+export declare function findingsForBundle(provider: GjcRuntimeSnapshotProvider | undefined, identity: GjcBundleIdentity, expectedGeneration: number): {
+    status: "unavailable";
+} | {
+    status: "current";
+    findings: GjcRuntimeFinding[];
+};

package/dist/types/extensibility/gjc-plugins/session-validation.d.ts

@@ -1,4 +1,4 @@
-import type { GjcPluginLoadErrorCode, GjcPluginRegistryEntry } from "./types";
+import type { GjcBundleIdentity, GjcPluginLoadErrorCode, GjcPluginRegistryEntry } from "./types";
 /**
  * Session-start validation: the registry is the collision authority. Capability
  * provider output is supplied as EVIDENCE only; plugin surfaces are never
@@ -16,6 +16,8 @@ export interface SessionCapabilityEvidence {
     appendixIds?: Iterable<string>;
 }
 export interface SessionQuarantine {
+    /** Scope-qualified canonical target this finding belongs to. */
+    identity: GjcBundleIdentity;
     plugin: string;
     surfaceId: string;
     code: GjcPluginLoadErrorCode;

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

@@ -218,3 +218,127 @@ export interface GjcPluginRegistry {
  * disabledSurfaceIds, and quarantine bookkeeping.
  */
 export type GjcPluginSurfaceExtensionId = string;
+/** Canonical GJC bundle identity: kind is fixed, target is (scope, name). */
+export declare const GJC_BUNDLE_KIND = "gjc-bundle";
+export interface GjcBundleIdentity {
+    kind: typeof GJC_BUNDLE_KIND;
+    scope: GjcPluginScope;
+    name: string;
+}
+/** Source descriptor exposed to CLI/Settings: never carries raw locator secrets. */
+export interface GjcBundleSafeSource {
+    kind: GjcPluginSourceKind;
+    /** Redacted display locator (host + path only; no userinfo/query/fragment). */
+    display: string;
+    /** Conservative safe git ref, omitted when the stored value is unsafe. */
+    ref?: string;
+    /** Hex-only revision identifier, omitted when the stored value is unsafe. */
+    sha?: string;
+    resolvedAt: string;
+    /** True when this source kind supports re-resolution during update. */
+    updatable: boolean;
+    /** Present only when updatable is false. */
+    unsupportedReason?: string;
+}
+export interface GjcBundleSurfaceSummary {
+    extensionId: string;
+    kind: "tool" | "hook" | "mcp" | "system-appendix" | "agent-appendix" | "subskill";
+    name: string;
+    /** Persisted user intent (registry disabledSurfaceIds). */
+    enabled: boolean;
+    /** Deterministic quarantine derived from persisted registry state only. */
+    quarantined: boolean;
+    quarantineCode?: GjcPluginLoadErrorCode;
+}
+/** Installed-bundle DTO shared by CLI and Settings. Contains no raw locators. */
+export interface GjcBundleSummary {
+    identity: GjcBundleIdentity;
+    version: string;
+    description?: string;
+    enabled: boolean;
+    source: GjcBundleSafeSource;
+    installedAt: string;
+    updatedAt: string;
+    manifestHash: string;
+    /** Deterministic fingerprint of the exact installed target. */
+    targetFingerprint: string;
+    surfaces: GjcBundleSurfaceSummary[];
+    /** True when any deterministic quarantine blocks enablement. */
+    quarantined: boolean;
+}
+/**
+ * Host-derived token binding an update preview to the exact candidate, the
+ * exact installed baseline, and the deterministic decision context. Apply is a
+ * compare-and-swap against all three fingerprints.
+ */
+export interface GjcReviewedUpdateToken {
+    identity: GjcBundleIdentity;
+    candidateFingerprint: string;
+    baselineFingerprint: string;
+    decisionContextFingerprint: string;
+    reviewedAt: string;
+}
+export type GjcLifecycleErrorCode = "already_installed_use_upgrade" | "not_installed" | "identity_mismatch" | "stale_candidate" | "stale_baseline" | "stale_decision_context" | "source_unsupported" | "source_unavailable" | "quarantined" | "surface_unknown" | "invalid_target";
+export interface GjcLifecycleError {
+    code: GjcLifecycleErrorCode;
+    /** Sanitized operator-facing message; never contains raw locators or causes. */
+    message: string;
+    /** Safe scoped recovery hint (e.g. the exact command to run instead). */
+    recovery?: string;
+}
+export type GjcLifecycleResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: GjcLifecycleError;
+};
+export interface GjcUpdatePreview {
+    identity: GjcBundleIdentity;
+    current: GjcBundleSummary;
+    candidateVersion: string;
+    candidateManifestHash: string;
+    /** Surface IDs added, removed, or retained by this candidate. */
+    addedSurfaceIds: string[];
+    removedSurfaceIds: string[];
+    retainedSurfaceIds: string[];
+    changed: boolean;
+    token: GjcReviewedUpdateToken;
+}
+export type GjcUpdateApplyStatus = "updated" | "unchanged";
+export interface GjcUpdateApplyResult {
+    status: GjcUpdateApplyStatus;
+    summary: GjcBundleSummary;
+    /** Number of filesystem remnants that could not be removed after a successful swap. */
+    remnantCount: number;
+}
+export interface GjcInstallResult {
+    status: "installed";
+    summary: GjcBundleSummary;
+}
+export interface GjcToggleResult {
+    summary: GjcBundleSummary;
+    /** False when the requested state already matched (no persisted mutation). */
+    mutated: boolean;
+}
+/**
+ * Scope-qualified runtime evidence emitted by producers. Producers never
+ * publish; the session coordinator accumulates one complete generation.
+ */
+export interface GjcRuntimeFinding {
+    identity: GjcBundleIdentity;
+    surfaceId: string;
+    code: GjcPluginLoadErrorCode;
+    message: string;
+}
+export interface GjcRuntimeSnapshot {
+    /** Monotonic activation generation this snapshot describes. */
+    generation: number;
+    findings: GjcRuntimeFinding[];
+}
+export type GjcRuntimeSnapshotState = {
+    status: "unavailable";
+} | {
+    status: "current";
+    snapshot: GjcRuntimeSnapshot;
+};