@gajae-code/coding-agent 0.16.7 → 0.17.1

package/dist/types/coordinator-mcp/session-reaper.d.ts

@@ -1,12 +1,13 @@
 /**
  * Idle reaper for coordinator-managed GJC worker sessions.
  *
- * Every `gjc_delegate_*` call that omits `session_id` starts a fresh tmux worker
- * session. Nothing in the coordinator ever tore those down, so completed/crashed
- * sessions accumulated (RAM + worktrees) until something killed them by hand.
+ * New coordinator-owned sessions created by `gjc_coordinator_start_session` or by a
+ * `gjc_delegate_*` call that omits `session_id` are ephemeral. Nothing in the
+ * coordinator ever tore those down, so completed/crashed sessions accumulated
+ * (RAM + worktrees) until something killed them by hand.
  *
  * This is the automatic backstop (defense-in-depth): a periodic sweep force-closes
- * sessions that are (a) ephemeral — coordinator delegate-created, never a user's
+ * sessions that are (a) ephemeral — coordinator-created, never a user's
  * registered resident session, (b) not mid-turn, and (c) idle past a TTL.
  *
  * The controller is pure + fully injectable (clock / list / reap side-effects) so
@@ -18,10 +19,12 @@ export declare const DEFAULT_SESSION_IDLE_TTL_MS: number;
 export declare const DEFAULT_SESSION_SWEEP_INTERVAL_MS: number;
 export declare const MIN_SESSION_IDLE_TTL_MS = 60000;
 export declare const MIN_SESSION_SWEEP_INTERVAL_MS = 30000;
+/** After this many consecutive reap failures the session is force-evicted from the index. */
+export declare const MAX_REAP_FAILURES = 3;
 /** Minimal projection of a coordinator session the reaper needs to decide. */
 export interface ReapableSession {
     sessionId: string;
-    /** True only for coordinator delegate-created sessions. User-registered resident sessions are false and never reaped. */
+    /** True for newly coordinator-created sessions. User-registered resident sessions are false and never reaped. */
     ephemeral: boolean;
     /** Epoch ms of last observed activity (turn update / session-state write / session creation). */
     lastActivityMs: number;
@@ -41,6 +44,13 @@ export declare function selectReapableSessions(sessions: readonly ReapableSessio
 export interface SessionReaperDeps {
     listSessions: () => Promise<ReapableSession[]>;
     reapSession: (sessionId: string) => Promise<void>;
+    /**
+     * Force-evict a session from the coordinator index when it has exceeded the
+     * consecutive-failure limit and cannot be reaped normally (e.g. endpoint_stale).
+     * Called exactly once per session-id at the eviction boundary; the session must
+     * not appear in future listSessions() results after this resolves.
+     */
+    markSessionDead: (sessionId: string) => Promise<void>;
     now: () => number;
 }
 export interface SessionReaper {

package/dist/types/cursor.d.ts

@@ -27,13 +27,13 @@ export declare class CursorExecHandlers implements ICursorExecHandlers {
     #private;
     private options;
     constructor(options: CursorExecBridgeOptions);
-    read(args: Parameters<NonNullable<ICursorExecHandlers["read"]>>[0]): Promise<ToolResultMessage<any>>;
-    ls(args: Parameters<NonNullable<ICursorExecHandlers["ls"]>>[0]): Promise<ToolResultMessage<any>>;
-    grep(args: Parameters<NonNullable<ICursorExecHandlers["grep"]>>[0]): Promise<ToolResultMessage<any>>;
-    write(args: Parameters<NonNullable<ICursorExecHandlers["write"]>>[0]): Promise<ToolResultMessage<any>>;
-    delete(args: Parameters<NonNullable<ICursorExecHandlers["delete"]>>[0]): Promise<ToolResultMessage<any>>;
-    shell(args: Parameters<NonNullable<ICursorExecHandlers["shell"]>>[0]): Promise<ToolResultMessage<any>>;
-    shellStream(args: Parameters<NonNullable<ICursorExecHandlers["shellStream"]>>[0], callbacks: CursorShellStreamCallbacks): Promise<ToolResultMessage<any>>;
+    read(args: Parameters<NonNullable<ICursorExecHandlers["read"]>>[0], signal?: AbortSignal, markNonAbortable?: () => void): Promise<ToolResultMessage<any>>;
+    ls(args: Parameters<NonNullable<ICursorExecHandlers["ls"]>>[0], signal?: AbortSignal, markNonAbortable?: () => void): Promise<ToolResultMessage<any>>;
+    grep(args: Parameters<NonNullable<ICursorExecHandlers["grep"]>>[0], signal?: AbortSignal): Promise<ToolResultMessage<any>>;
+    write(args: Parameters<NonNullable<ICursorExecHandlers["write"]>>[0], signal?: AbortSignal, markNonAbortable?: () => void): Promise<ToolResultMessage<any>>;
+    delete(args: Parameters<NonNullable<ICursorExecHandlers["delete"]>>[0], signal?: AbortSignal, markNonAbortable?: () => void): Promise<ToolResultMessage<any>>;
+    shell(args: Parameters<NonNullable<ICursorExecHandlers["shell"]>>[0], signal?: AbortSignal, markNonAbortable?: () => void): Promise<ToolResultMessage<any>>;
+    shellStream(args: Parameters<NonNullable<ICursorExecHandlers["shellStream"]>>[0], callbacks: CursorShellStreamCallbacks, signal?: AbortSignal, markNonAbortable?: () => void): Promise<ToolResultMessage<any>>;
     piRead(call: Parameters<NonNullable<ICursorExecHandlers["piRead"]>>[0]): Promise<ToolResultMessage<any>>;
     piBash(call: Parameters<NonNullable<ICursorExecHandlers["piBash"]>>[0]): Promise<ToolResultMessage<any>>;
     piEdit(call: Parameters<NonNullable<ICursorExecHandlers["piEdit"]>>[0]): Promise<ToolResultMessage<any>>;
@@ -41,7 +41,7 @@ export declare class CursorExecHandlers implements ICursorExecHandlers {
     piGrep(call: Parameters<NonNullable<ICursorExecHandlers["piGrep"]>>[0]): Promise<ToolResultMessage<any>>;
     piFind(call: Parameters<NonNullable<ICursorExecHandlers["piFind"]>>[0]): Promise<ToolResultMessage<any>>;
     piLs(call: Parameters<NonNullable<ICursorExecHandlers["piLs"]>>[0]): Promise<ToolResultMessage<any>>;
-    diagnostics(args: Parameters<NonNullable<ICursorExecHandlers["diagnostics"]>>[0]): Promise<ToolResultMessage<any>>;
-    mcp(call: CursorMcpCall): Promise<ToolResultMessage<any>>;
+    diagnostics(args: Parameters<NonNullable<ICursorExecHandlers["diagnostics"]>>[0], signal?: AbortSignal): Promise<ToolResultMessage<any>>;
+    mcp(call: CursorMcpCall, signal?: AbortSignal, markNonAbortable?: () => void): Promise<ToolResultMessage<any>>;
 }
 export {};

package/dist/types/discovery/agents-md.d.ts

@@ -1,6 +1,11 @@
 import { type ContextFile } from "../capability/context-file";
+import type { FileIdentity } from "../capability/fs";
 import type { LoadContext, LoadResult } from "../capability/types";
-export type AgentsMdReader = (filePath: string, maxBytes: number) => Promise<{
+export type AgentsMdReader = (filePath: string, maxBytes: number, options?: {
+    noFollow?: boolean;
+    home?: string;
+    homeIdentity?: FileIdentity;
+}) => Promise<{
     content: string | null;
     byteLength: number;
     tooLarge: boolean;

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

@@ -1,5 +1,6 @@
 import type { ThinkingLevel } from "@gajae-code/agent-core";
 import type { ExtensionModule } from "../capability/extension-module";
+import { type FileIdentity, type ReadFileOptions, type ReadScope } from "../capability/fs";
 import { type Rule } from "../capability/rule";
 import type { Skill } from "../capability/skill";
 import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
@@ -91,6 +92,9 @@ export declare function getUserSkillScanDirs(home: string, userAgentDir?: string
  * Get project-level path for a source (cwd only).
  */
 export declare function getProjectPath(ctx: LoadContext, source: SourceId, subpath: string): string | null;
+/** Build the filesystem authority for a provider read. */
+export declare function getReadOptions(ctx: Pick<LoadContext, "home" | "isolatedHome" | "userAgentDir" | "homeIdentity" | "userAgentIdentity">, scope: ReadScope): ReadFileOptions | undefined;
+export declare function getReadOptionsForContainment(ctx: Pick<LoadContext, "home" | "isolatedHome" | "userAgentDir" | "homeIdentity" | "userAgentIdentity">, scope: ReadScope, containmentRoot?: string): Promise<ReadFileOptions | undefined>;
 /**
  * Create source metadata for an item.
  */
@@ -143,6 +147,12 @@ export interface ScanSkillsFromDirOptions {
     providerId: string;
     level: "user" | "project";
     requireDescription?: boolean;
+    /** Optional physical root that every discovered skill must remain within. */
+    containmentRoot?: string;
+    /** Physical repository root permitting the project scan directory itself to be a symlink. */
+    linkContainmentRoot?: string;
+    /** Filesystem authority for explicit-home reads. */
+    scope?: ReadScope;
 }
 export declare function compareSkillOrder(aName: string, aPath: string, bName: string, bPath: string): number;
 /** Maximum bytes read per incremental frontmatter scan chunk. */
@@ -154,10 +164,11 @@ export declare const SkillDiscoveryTestHooks: {
     afterAuthorityRootValidated?: (root: string) => void | Promise<void>;
     afterAuthorityRootMissing?: (root: string) => void | Promise<void>;
     afterContainedRootValidated?: (root: string) => void | Promise<void>;
+    afterScanRootValidated?: (root: string) => void | Promise<void>;
 };
 export declare function scanSkillsFromDir(_ctx: LoadContext, options: ScanSkillsFromDirOptions): Promise<LoadResult<Skill>>;
-/** Read a regular single-link file that remains contained by its configured root. */
-export declare function readContainedFile(root: string, filePath: string): Promise<string | null>;
+/** Read a regular file that remains contained by its configured root. */
+export declare function readContainedFile(root: string, filePath: string, expectedRootIdentity?: FileIdentity | null): Promise<string | null>;
 /**
  * Recursively expand environment variables in an object.
  */
@@ -173,6 +184,10 @@ export declare function loadFilesFromDir<T>(_ctx: LoadContext, dir: string, prov
     transform: (name: string, content: string, path: string, source: SourceMeta) => T | null;
     /** Whether to recurse into subdirectories (default: false) */
     recursive?: boolean;
+    /** Optional physical root that every discovered file must remain within. */
+    containmentRoot?: string;
+    /** Filesystem authority for explicit-home reads. */
+    scope?: ReadScope;
 }): Promise<LoadResult<T>>;
 /**
  * Calculate depth of target directory relative to current working directory.
@@ -193,7 +208,9 @@ export declare function calculateDepth(cwd: string, targetDir: string, separator
  * No recursion beyond one level. Complex packages must use package.json manifest.
  * Uses native glob for fast filesystem scanning with gitignore support.
  */
-export declare function discoverExtensionModulePaths(_ctx: LoadContext, dir: string): Promise<string[]>;
+export declare function discoverExtensionModulePaths(ctx: LoadContext, dir: string, options?: {
+    scope?: ReadScope;
+}): Promise<string[]>;
 /**
  * Derive a stable extension name from a path.
  */
@@ -256,7 +273,7 @@ export declare function parseClaudePluginsRegistry(content: string): ClaudePlugi
  * This is the single source of truth for "active project root" used by install,
  * uninstall, list, upgrade, discovery, and doctor. Deterministic for a given `cwd`.
  */
-export declare function resolveActiveProjectRegistryPath(cwd: string): Promise<string | null>;
+export declare function resolveActiveProjectRegistryPath(cwd: string, homeDir?: string, isolatedHome?: boolean): Promise<string | null>;
 /**
  * Like resolveActiveProjectRegistryPath, but falls back to `<cwd>/.gjc/plugins/installed_plugins.json`
  * when no project anchor (.gjc/ or .git/) is found.
@@ -270,14 +287,26 @@ export declare function resolveActiveProjectRegistryPath(cwd: string): Promise<s
  */
 export declare function resolveOrDefaultProjectRegistryPath(cwd: string): Promise<string | undefined>;
 /** Invalidate the exact user/project registry pair and their resolved-root cache entry. */
-export declare function invalidateClaudePluginRoots(home: string, cwd?: string): Promise<void>;
+export declare function invalidateClaudePluginRoots(home: string, cwd?: string, isolatedHome?: boolean): Promise<void>;
+/**
+ * Resolve a configured path through existing symlinks when an explicit-home
+ * load is active. Ordinary discovery keeps its historical lexical path
+ * handling; isolated discovery must reject paths that leave the supplied
+ * physical home (or an explicitly selected agent directory), including paths
+ * that escape through an existing symlink. When provided, containmentRoot is
+ * an additional physical boundary, such as a plugin root.
+ */
+export declare function canonicalizePathWithinHome(ctx: Pick<LoadContext, "home" | "isolatedHome" | "userAgentDir" | "homeIdentity">, target: string, containmentRoot?: string, scope?: ReadScope): Promise<string | undefined>;
 /**
  * List installed GJC plugin roots from the GJC plugin registry and, when present,
  * the nearest project-scoped registry resolved from `cwd`.
  *
- * Results are cached per `home:resolvedProjectPath` key to avoid repeated parsing.
+ * Ordinary results are cached per `home:resolvedProjectPath` key to avoid
+ * repeated parsing. Isolated results intentionally bypass the shared cache:
+ * an ordinary load may contain external install roots that an isolated load
+ * must reject, and reusing that result would cross the home boundary.
  */
-export declare function listClaudePluginRoots(home: string, cwd?: string): Promise<{
+export declare function listClaudePluginRoots(home: string, cwd?: string, isolatedHome?: boolean, homeIdentity?: FileIdentity): Promise<{
     roots: ClaudePluginRoot[];
     warnings: string[];
 }>;

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

@@ -32,7 +32,7 @@ import "./github";
 import "./mcp-json";
 import "./ssh";
 import "./windsurf";
-export { cacheStats, disableProvider, enableProvider, getAllCapabilitiesInfo, getAllProvidersInfo, getCapability, getCapabilityInfo, getDisabledProviders, getProviderInfo, initializeWithSettings, invalidate, isProviderEnabled, listCapabilities, loadCapability, releaseSettingsScope, reset, setDisabledProviders, } from "../capability";
+export { cacheStats, disableProvider, enableProvider, getAllCapabilitiesInfo, getAllProvidersInfo, getCapability, getCapabilityInfo, getDisabledProviders, getProviderInfo, initializeWithSettings, invalidate, isProviderEnabled, listCapabilities, loadCapability, loadCapabilityForHome, releaseSettingsScope, reset, setDisabledProviders, } from "../capability";
 export type { ContextFile } from "../capability/context-file";
 export type { Extension, ExtensionManifest } from "../capability/extension";
 export type { ExtensionModule } from "../capability/extension-module";

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

@@ -1,3 +1,4 @@
+import { type ReadFileOptions } from "../capability/fs";
 import { type MCPServer } from "../capability/mcp";
 import type { LoadResult } from "../capability/types";
 export interface MCPJsonLoadResult extends LoadResult<MCPServer> {
@@ -9,4 +10,5 @@ export interface MCPJsonLoadResult extends LoadResult<MCPServer> {
 export declare function loadMCPJsonFile(filePath: string, level: "user" | "project", options?: {
     quiet?: boolean;
     useCache?: boolean;
+    readOptions?: ReadFileOptions;
 }): Promise<MCPJsonLoadResult>;

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

@@ -1,5 +1,6 @@
 import type { ThinkingLevel } from "@gajae-code/agent-core";
 import type { Tool, UsageReport } from "@gajae-code/ai/core";
+import type { Settings } from "../../config/settings";
 import { EventBus } from "../../utils/event-bus";
 import type { Extension, ExtensionFactory, ExtensionRuntime as IExtensionRuntime, LoadExtensionsResult } from "./types";
 export declare class ExtensionRuntimeNotInitializedError extends Error {
@@ -79,7 +80,27 @@ export declare function loadExtensionFromFactory(factory: ExtensionFactory, cwd:
  * Load extensions from paths.
  */
 export declare function loadExtensions(paths: string[], cwd: string, eventBus?: EventBus): Promise<LoadExtensionsResult>;
+/**
+ * Session-scoped discovery inputs.
+ *
+ * A session's selected agent directory is not necessarily the process-global
+ * one (`createAgentSession({ agentDir })`), so user-scope extension modules and
+ * provider policy must resolve against the caller's profile rather than
+ * `getAgentDir()`.
+ */
+export interface DiscoverExtensionsOptions {
+    /**
+     * Agent directory backing user-scope discovery. Default: `getAgentDir()`.
+     * Only the native capability provider is scoped this way; installed
+     * plugin-bundle extension paths stay home-scoped by design.
+     */
+    agentDir?: string;
+    /** Resolver-owned classification for `agentDir`. */
+    profileAuthority?: "default" | "custom";
+    /** Session settings whose provider policy applies to this load. */
+    settings?: Settings;
+}
 /**
  * Discover and load extensions from standard locations.
  */
-export declare function discoverAndLoadExtensions(configuredPaths: string[], cwd: string, eventBus?: EventBus, disabledExtensionIds?: string[]): Promise<LoadExtensionsResult>;
+export declare function discoverAndLoadExtensions(configuredPaths: string[], cwd: string, eventBus?: EventBus, disabledExtensionIds?: string[], options?: DiscoverExtensionsOptions): Promise<LoadExtensionsResult>;

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

@@ -1,4 +1,4 @@
-import type { GjcBundleIdentity, GjcBundleSummary, GjcInstallResult, GjcLifecycleResult, GjcPluginRegistryEntry, GjcPluginRegistrySource, GjcPluginScope, GjcReviewedUpdateToken, GjcToggleResult, GjcUninstallPreview, GjcUpdateApplyResult, GjcUpdatePreview } from "./types";
+import type { GjcBundleIdentity, GjcBundleSummary, GjcInstallResult, GjcLifecycleResult, GjcPluginRegistryEntry, GjcPluginRegistrySource, GjcPluginScope, GjcReviewedUpdateToken, GjcToggleResult, GjcUninstallPreview, GjcUpdateApplyResult, GjcUpdatePreview, LocalRestorePlanV1, ReviewedRestoreTokenV1 } from "./types";
 /**
  * GJC bundle lifecycle service.
  *
@@ -72,6 +72,19 @@ export declare function previewGjcBundleUpdate(ctx: GjcLifecycleContext, identit
  * zero mutation.
  */
 export declare function applyGjcBundleUpdate(ctx: GjcLifecycleContext, token: GjcReviewedUpdateToken): Promise<GjcLifecycleResult<GjcUpdateApplyResult>>;
+export declare function previewGjcBundleRestore(ctx: GjcLifecycleContext, identity: GjcBundleIdentity): Promise<GjcLifecycleResult<LocalRestorePlanV1>>;
+export declare function authorizeGjcBundleRestore(ctx: GjcLifecycleContext, plan: LocalRestorePlanV1, authorizations: readonly string[]): Promise<GjcLifecycleResult<ReviewedRestoreTokenV1>>;
+export declare function applyGjcBundleRestore(ctx: GjcLifecycleContext, token: ReviewedRestoreTokenV1): Promise<GjcLifecycleResult<GjcUpdateApplyResult>>;
+/**
+ * Doctor-only quarantine primitive. The expected baseline is compared while
+ * holding the ordinary registry writer lock, so concurrent enable/disable or
+ * update cannot be clobbered.
+ */
+export declare function setGjcBundleQuarantineExpectedBaseline(ctx: GjcLifecycleContext, identity: GjcBundleIdentity, enabled: boolean, expectedBaseline: string): Promise<GjcLifecycleResult<GjcToggleResult>>;
+export declare function getGjcBundleEnablementState(ctx: GjcLifecycleContext, identity: GjcBundleIdentity): Promise<GjcLifecycleResult<{
+    enabled: boolean;
+    baseline: string;
+}>>;
 /**
  * Enable or disable a whole bundle. Deterministic quarantine blocks enabling;
  * disabling is always allowed so operators can always de-escalate.

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

@@ -1,8 +1,9 @@
+import type { ReadFileOptions } from "../../capability/fs";
 export declare function gjcPluginUserRoot(): string;
 export declare function gjcPluginProjectRoot(cwd: string): string;
 export declare function gjcPluginSafeDirectoryName(name: string): string;
 export declare function gjcPluginInstallRoot(scope: "user" | "project", cwd: string, name: string): string;
-export declare function rootContainsGjcManifest(dir: string): Promise<boolean>;
+export declare function rootContainsGjcManifest(dir: string, options?: ReadFileOptions): Promise<boolean>;
 export declare function discoverGjcPluginRoots({ cwd }: {
     cwd: string;
     home?: string;

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

@@ -358,6 +358,31 @@ export interface GjcReviewedUpdateToken {
     decisionContextFingerprint: string;
     reviewedAt: string;
 }
+export interface LocalRestorePlanV1 {
+    schemaVersion: 1;
+    kind: "gjc-plugin.restore-artifact";
+    identity: GjcBundleIdentity;
+    baselineFingerprint: string;
+    decisionContextFingerprint: string;
+    artifact: {
+        status: "present" | "absent" | "unreadable";
+        digest?: string;
+    };
+    writes: false;
+    fetch: false;
+    locks: false;
+}
+export interface ReviewedRestoreTokenV1 {
+    schemaVersion: 1;
+    kind: "gjc-plugin.restore-artifact";
+    purpose: "restore-artifact";
+    identity: GjcBundleIdentity;
+    candidateFingerprint: string;
+    baselineFingerprint: string;
+    decisionContextFingerprint: string;
+    artifactFingerprint: string;
+    reviewedAt: string;
+}
 export type GjcLifecycleErrorCode = "already_installed_use_upgrade" | "not_installed" | "registry_unreadable" | "identity_mismatch" | "stale_candidate" | "stale_baseline" | "stale_decision_context" | "source_unsupported" | "source_unavailable" | "quarantined" | "surface_unknown" | "invalid_target";
 export interface GjcLifecycleError {
     code: GjcLifecycleErrorCode;

package/dist/types/extensibility/plugins/manager.d.ts

@@ -1,7 +1,40 @@
 import type { DoctorCheck, DoctorOptions, InstalledPlugin, InstallOptions, PluginSettingSchema } from "./types";
+export type PluginEnablementState = {
+    status: "ok";
+    enabled: boolean;
+    baseline: string;
+} | {
+    status: "not_installed";
+} | {
+    status: "malformed";
+};
 export declare class PluginManager {
     #private;
     constructor(cwd?: string);
+    /**
+     * Read-only durable-enablement snapshot for one npm plugin, scope-qualified.
+     * `"user"` reads the shared runtime lock file (~/.gjc/plugins/gjc-plugins.lock.json);
+     * `"project"` reads this project's `.gjc/plugin-overrides.json` disabled list.
+     * A malformed underlying file is reported distinctly from "not installed" —
+     * neither is silently treated as an empty/enabled state.
+     */
+    getEnablementState(name: string, scope: "user" | "project"): Promise<PluginEnablementState>;
+    /**
+     * Durable enablement toggle used by doctor quarantine and the plugin CLI.
+     * No install/fetch/reinstall occurs — this only flips the durable enabled
+     * flag a future session-startup load (`getEnabledPlugins`) consults: the
+     * user-scope runtime lock file, or the project's disabled-list override.
+     * Serialized under the canonical native-identity-bound file lock shared
+     * with every other writer of the same file (bounded retry/timeout,
+     * owner-safe release — never an unbounded wait, never a blind `rm`).
+     * `expectedBaseline` is required: a caller with no prior
+     * {@link getEnablementState} read has no CAS authority to mutate.
+     */
+    setEnabled(name: string, enabled: boolean, scope: "user" | "project", expectedBaseline: string): Promise<{
+        status: "updated" | "not_needed";
+        enabled: boolean;
+        version?: string;
+    }>;
     /**
      * Install a plugin from npm with optional feature selection.
      *
@@ -30,10 +63,6 @@ export declare class PluginManager {
      * Link a local plugin for development.
      */
     link(localPath: string): Promise<InstalledPlugin>;
-    /**
-     * Enable or disable a plugin globally.
-     */
-    setEnabled(name: string, enabled: boolean): Promise<void>;
     /**
      * Get enabled features for a plugin.
      */

package/dist/types/extensibility/plugins/marketplace/cache.d.ts

@@ -23,6 +23,12 @@ export declare function getCachedPluginPath(cacheDir: string, marketplace: strin
  * so a partial previous cache is never silently reused.
  */
 export declare function cachePlugin(sourcePath: string, cacheDir: string, marketplace: string, pluginName: string, version: string): Promise<string>;
+export declare function stageCachedPlugin(sourcePath: string, stagingPath: string): Promise<string>;
+export declare function digestCachedPlugin(targetPath: string): Promise<string | undefined>;
+export declare function inspectCachedPlugin(targetPath: string): Promise<{
+    status: "present" | "absent" | "unreadable";
+    digest?: string;
+}>;
 /**
  * Synchronous check — true when the cache directory exists on disk.
  * Uses `existsSync` because callers may need to run this check inline without async.

package/dist/types/extensibility/plugins/marketplace/manager.d.ts

@@ -21,7 +21,165 @@ export interface MarketplaceManagerOptions {
      *  Receives any additional file paths that should also be invalidated from the fs cache.
      */
     clearPluginRootsCache?: (extraPaths?: readonly string[]) => void;
+    /**
+     * Test seam ONLY: injected immediately after {@link MarketplaceManager.applyPluginRestore}
+     * renames the staged candidate onto `finalPath` and captures its own
+     * published identity, before any further verification. Production callers
+     * never set this — default behavior is a no-op. Exists so a test can
+     * deterministically simulate a concurrent second writer republishing
+     * `finalPath` with a different inode inside the real race window, to
+     * exercise the `foreign_owner_conflict` rollback branch without a second
+     * process. Never used to bypass or weaken the identity re-check itself.
+     */
+    afterRestorePublish?: (finalPath: string) => Promise<void>;
+}
+export type MarketplaceRestoreRiskClass = "plugin-change" | "install-replace" | "network" | "external-execution";
+/**
+ * Pure, read-only restoration descriptor. Every field is an observation of
+ * already-stored registry/catalog/local-artifact state; nothing here resolves
+ * a source, touches the network, or stages anything. `installPath` names the
+ * artifact this plan is ABOUT (the thing that would be repaired), never a
+ * staged candidate — the plan carries no writable authority.
+ */
+export interface MarketplaceRestorePlanV1 {
+    schemaVersion: 1;
+    kind: "marketplace-plugin.restore-artifact";
+    pluginId: string;
+    scope: "user" | "project";
+    version: string;
+    installPath: string;
+    enabled: boolean;
+    /** Pinned SHA already recorded for this install, when known. */
+    gitCommitSha?: string;
+    /** Covers every entry recorded for this pluginId (all scopes) plus the local artifact observation. */
+    baselineFingerprint: string;
+    catalogFingerprint: string;
+    source: MarketplacePluginEntry["source"];
+    artifact: {
+        status: "present" | "absent" | "unreadable";
+        digest?: string;
+    };
+    riskClasses: readonly MarketplaceRestoreRiskClass[];
+    writes: false;
+    fetch: false;
+    execute: false;
+}
+/**
+ * Materialized after explicit risk authorization: a verified, staged,
+ * pinned-SHA candidate bound to the exact baseline/catalog it was reviewed
+ * against. `originalInstallPath` (what apply repairs) and `stagedArtifactPath`
+ * (the verified candidate bytes) are always distinct paths — apply never
+ * confuses the target it is replacing with the replacement.
+ */
+export interface MarketplaceReviewedRestoreTokenV1 {
+    schemaVersion: 1;
+    kind: "marketplace-plugin.restore-artifact";
+    purpose: "restore-artifact";
+    pluginId: string;
+    scope: "user" | "project";
+    version: string;
+    originalInstallPath: string;
+    stagedArtifactPath: string;
+    enabled: boolean;
+    pinnedSha: string;
+    baselineFingerprint: string;
+    catalogFingerprint: string;
+    candidateFingerprint: string;
+    candidateArtifact: {
+        status: "present";
+        digest: string;
+    };
+    riskClasses: readonly MarketplaceRestoreRiskClass[];
+    reviewedAt: string;
 }
+/**
+ * `refused` — nothing was mutated; safe to retry after fixing the cause.
+ * `conflict` — a filesystem mutation was attempted and then fully, verifiably
+ * rolled back to OUR exact prior artifact; the installed state is unchanged
+ * from before this apply ran.
+ * `foreign_owner_conflict` — a filesystem mutation was attempted, but the
+ * publish target now belongs to a different, concurrently-completed owner.
+ * Neither the foreign publication nor our own retained backup is touched;
+ * `retainedBackupPath` on the error names exactly where our pre-swap artifact
+ * is preserved for inspection/manual reconciliation.
+ * `uncertain` — a filesystem mutation was attempted and rollback to OUR prior
+ * artifact could not be verified; the installed state may not match either
+ * the old or new artifact and requires manual inspection.
+ * A caller (doctor journal) MUST record all four distinctly and MUST NOT
+ * treat any of the non-`refused` outcomes as a clean no-op.
+ */
+export type MarketplaceRestoreOutcome = "refused" | "conflict" | "foreign_owner_conflict" | "uncertain";
+/**
+ * Typed refusal/failure for the restore lane. Every throw site in
+ * previewPluginRestore/authorizePluginRestore/applyPluginRestore uses this
+ * class (never a bare `Error`) so a caller (the doctor journal) can
+ * distinguish a clean pre-mutation refusal from a filesystem mutation that
+ * was attempted and either rolled back, lost to a foreign owner, or left
+ * uncertain.
+ */
+export declare class MarketplaceRestoreError extends Error {
+    readonly reasonCode: MarketplaceRestoreReasonCode;
+    readonly sideEffectStarted: boolean;
+    readonly outcome: MarketplaceRestoreOutcome;
+    /** Set whenever a pre-swap backup survives this call untouched: `foreign_owner_conflict` and every `uncertain` outcome that retains it. */
+    readonly retainedBackupPath?: string;
+    /**
+     * Private, non-reported free-text context (e.g. a wrapped underlying error
+     * message). NEVER surfaced as `reasonCode` — `reasonCode` reaches redacted
+     * external reports and must stay a fixed enum member.
+     */
+    readonly detail?: string;
+    constructor(reasonCode: MarketplaceRestoreReasonCode, options?: {
+        sideEffectStarted?: boolean;
+        outcome?: MarketplaceRestoreOutcome;
+        retainedBackupPath?: string;
+        detail?: string;
+    });
+}
+/**
+ * Fixed enum of every `MarketplaceRestoreError.reasonCode` produced by
+ * previewPluginRestore/authorizePluginRestore/applyPluginRestore. `reasonCode`
+ * reaches redacted external reports, so it MUST stay a member of this exact
+ * set — never an interpolated raw Error message (that goes into `detail`,
+ * a private, non-reported field on the error).
+ */
+export declare const MARKETPLACE_RESTORE_REASON_CODES: readonly ["invalid_plugin_id", "not_installed", "marketplace_missing", "catalog_entry_missing", "catalog_changed", "baseline_changed", "original_path_not_canonical_private_layout", "candidate_changed", "unpinned_source", "unsupported_shared_layout", "install_path_not_canonical_private_layout", "resolved_provenance_mismatch", "unsafe_candidate_artifact", "authorization_missing", "staged_artifact_inside_cache_root", "final_path_outside_private_cache_root", "invalid_restore_token", "staged_snapshot_unavailable", "private_cache_root_missing", "private_cache_root_changed", "final_path_snapshot_unavailable", "final_path_is_symlink", "backup_detach_failed", "final_path_changed_before_backup", "backup_detach_unverified", "backup_publish_failed", "final_path_claimed_by_new_owner", "post_publish_identity_unconfirmed", "post_publish_digest_mismatch", "registry_write_failed", "post_publish_registry_verification_failed", "unexpected_occupant_before_our_publish", "rollback_rename_failed", "rollback_digest_mismatch", "restore_publish_failed"];
+export type MarketplaceRestoreReasonCode = (typeof MARKETPLACE_RESTORE_REASON_CODES)[number];
+export type MarketplaceRestoreApplyStatus = "verified" | "not_needed";
+/**
+ * Discriminated success result for {@link MarketplaceManager.applyPluginRestore}.
+ * A TypeScript discriminated union (not one interface with optional fields):
+ * `not_needed` structurally has ONLY `staleStagedArtifactPath` and can never
+ * carry a `retainedBackupPath` field — there is no backup rollback state in
+ * a branch that made zero mutations. `verified` carries neither field, since
+ * a fully committed apply has nothing stale or retained to report.
+ *
+ * `sideEffectStarted` is explicit and MUST be `false` for `not_needed` (zero
+ * filesystem or registry mutation of any kind is attempted — the token is not
+ * consumed and can be safely retried or discarded) and `true` for `verified`
+ * (the cache directory was swapped and the registry written). `entry` for
+ * `verified` is re-read from disk after the write, not the in-memory value
+ * that was written, so it is independent observation rather than an echo of
+ * the input.
+ *
+ * `not_needed.staleStagedArtifactPath` names the token's now-redundant staged
+ * scratch directory for the CALLER to dispose of; this function does not
+ * delete it (doing so would itself be a write inside a branch that must
+ * remain a true zero-effect no-op), and it is populated ONLY with the exact
+ * path this same call's precheck confirmed still exists and still matches
+ * the token — never a path this call did not itself verify.
+ */
+export type MarketplaceRestoreApplyResult = {
+    status: "verified";
+    sideEffectStarted: true;
+    entry: InstalledPluginEntry;
+} | {
+    status: "not_needed";
+    sideEffectStarted: false;
+    entry: InstalledPluginEntry;
+    /** Present only when this call itself verified the staged directory still exists. */
+    staleStagedArtifactPath?: string;
+};
 export declare class MarketplaceManager {
     #private;
     constructor(options: MarketplaceManagerOptions);
@@ -32,6 +190,34 @@ export declare class MarketplaceManager {
     listMarketplaces(): Promise<MarketplaceRegistryEntry[]>;
     listAvailablePlugins(marketplace?: string): Promise<MarketplacePluginEntry[]>;
     getPluginInfo(name: string, marketplace: string): Promise<MarketplacePluginEntry | null>;
+    /**
+     * Pure, read-only restoration observation. Reads the installed registry
+     * entry, the marketplace catalog entry, and the local cache artifact only.
+     * Never resolves the plugin source, never touches the network, never stages
+     * or writes anything.
+     */
+    previewPluginRestore(pluginId: string, scope: "user" | "project"): Promise<MarketplaceRestorePlanV1>;
+    /**
+     * Materialize a verified, pinned-SHA candidate after explicit risk
+     * authorization. Re-derives every fact from live state instead of trusting
+     * the caller-supplied plan: risk classes are recomputed (never taken from
+     * `plan.riskClasses`), the source is re-read from the current catalog entry
+     * (never from `plan.source`), and the resolved checkout's HEAD is
+     * independently re-verified against the pinned SHA before anything is
+     * staged. The plan itself confers no authority — only an explicit,
+     * risk-complete `authorizations` set does.
+     */
+    authorizePluginRestore(plan: MarketplaceRestorePlanV1, authorizations: readonly string[]): Promise<MarketplaceReviewedRestoreTokenV1>;
+    /**
+     * Publish a verified restore candidate. Re-verifies catalog/baseline/
+     * candidate CAS against live state (the token confers no authority by
+     * itself), swaps the private per-version cache directory atomically with a
+     * randomized backup name, and mutates ONLY the matched (pluginId, scope)
+     * registry entry — every sibling entry, every other pluginId, and the
+     * opposite scope's registry file are left untouched. On any failure after
+     * the filesystem swap the exact old artifact/registry pair is restored.
+     */
+    applyPluginRestore(token: MarketplaceReviewedRestoreTokenV1): Promise<MarketplaceRestoreApplyResult>;
     installPlugin(name: string, marketplace: string, options?: {
         force?: boolean;
         scope?: "user" | "project";

package/dist/types/extensibility/plugins/marketplace/registry.d.ts

@@ -20,6 +20,33 @@ export declare function readMarketplacesRegistry(filePath: string): Promise<Mark
 export declare function writeMarketplacesRegistry(filePath: string, reg: MarketplacesRegistry): Promise<void>;
 export declare function readInstalledPluginsRegistry(filePath: string): Promise<InstalledPluginsRegistry>;
 export declare function writeInstalledPluginsRegistry(filePath: string, reg: InstalledPluginsRegistry): Promise<void>;
+export type InstalledPluginEnablementState = {
+    status: "ok";
+    enabled: boolean;
+    baseline: string;
+} | {
+    status: "not_installed";
+} | {
+    status: "malformed";
+} | {
+    status: "unsafe_link";
+};
+/**
+ * Pure read-only snapshot of one (id, scope) entry's durable enablement plus
+ * an exact file+parent CAS baseline. Never touches the cached artifact at
+ * `installPath` — presence/absence of that artifact is a D6 concern, not D7's.
+ * A symlinked or hard-linked registry file is refused distinctly from an
+ * absent ("not_installed"-eligible) or malformed one.
+ */
+export declare function getInstalledPluginEnablementState(filePath: string, id: string, scope: "user" | "project"): Promise<InstalledPluginEnablementState>;
+/**
+ * Update durable marketplace enablement without touching cached artifacts.
+ * Serialized under the canonical native-identity-bound file lock ordinary
+ * marketplace writers use (bounded retries, no blind directory removal).
+ * `expectedBaseline` is required: a caller with no prior read has no CAS
+ * authority and must call {@link getInstalledPluginEnablementState} first.
+ */
+export declare function setInstalledPluginEnabled(filePath: string, id: string, scope: "user" | "project", enabled: boolean, expectedBaseline: string): Promise<"updated" | "not_needed">;
 export declare function addMarketplaceEntry(reg: MarketplacesRegistry, entry: MarketplaceRegistryEntry): MarketplacesRegistry;
 export declare function removeMarketplaceEntry(reg: MarketplacesRegistry, name: string): MarketplacesRegistry;
 export declare function getMarketplaceEntry(reg: MarketplacesRegistry, name: string): MarketplaceRegistryEntry | undefined;