@hasna/skills 0.10.71 → 0.10.73

package/dist/lib/agent-discovery-directories.d.ts

@@ -1,3 +1,4 @@
+import { type NativeDiscoveryWitnessTolerance } from "./native-discovery-witness-change.js";
 /** Recursive path/type membership only; source-file hashes bind reviewed bytes. */
 export interface DiscoveryDirectory {
     path: string;
@@ -10,8 +11,12 @@ export interface DiscoveryDirectoryProjection extends DiscoveryDirectory {
  * reviewed inactive roots. It never replaces a historical full witness. */
 export declare function captureDiscoveryDirectoryProjection(paths: string[], omittedRoots: readonly string[]): DiscoveryDirectoryProjection[];
 /** Compare a planner-captured inventory after removing only exact inert graphs.
- * The stored rows must reproduce their original digest before projection. */
-export declare function verifyDiscoveryDirectoryProjection(directories: DiscoveryDirectoryProjection[], omittedRoots: readonly string[]): void;
+ * The stored rows must reproduce their original digest before projection. A
+ * membership change is a NativeDiscoveryWitnessChange: thrown, unless the live
+ * Codex prompt hook's tolerance accepts it. Invalid inventories always throw. */
+export declare function verifyDiscoveryDirectoryProjection(directories: DiscoveryDirectoryProjection[], omittedRoots: readonly string[], tolerance?: NativeDiscoveryWitnessTolerance): void;
 /** Read-only capture; callers must review both membership and source bytes. */
 export declare function captureDiscoveryDirectories(paths: string[], excludedRoots?: readonly string[]): DiscoveryDirectory[];
-export declare function verifyDiscoveryDirectories(directories: DiscoveryDirectory[], excludedRoots?: readonly string[]): void;
+/** A membership change is a NativeDiscoveryWitnessChange: thrown, unless the
+ * live Codex prompt hook's tolerance accepts it. Invalid collections always throw. */
+export declare function verifyDiscoveryDirectories(directories: DiscoveryDirectory[], excludedRoots?: readonly string[], tolerance?: NativeDiscoveryWitnessTolerance): void;

package/dist/lib/agent-discovery.d.ts

@@ -1,6 +1,8 @@
 import type { IntegrationAgent } from "./agent-adapters.js";
 import { type DiscoveryDirectory } from "./agent-discovery-directories.js";
 import { type CodexReviewedHookSource } from "./codex-hook-mcp-dependencies.js";
+import { CLAUDE_ORPHAN_MARKER_MODE } from "./claude-plugin-cache-marker.js";
+import { type NativeDiscoveryWitnessTolerance } from "./native-discovery-witness-change.js";
 import { type ManagedPluginRegistrationWitness } from "./plugin-discovery.js";
 import { type CodexHookDiscoveryRecovery } from "./codex-hook-discovery-recovery.js";
 import { type CodexPluginSkillControl, type CodexPluginSourceInput } from "./codex-plugin-skill-controls.js";
@@ -11,7 +13,7 @@ export interface DiscoverySource {
     reviewArtifact?: RetainedReviewArtifact;
     path: string;
     sha256: string | null;
-    hashMode?: "bytes" | "path-bytes" | "claude-plugin-manifest-v1" | "claude-plugin-registry" | "claude-marketplace-registry" | "claude-settings-v1" | "claude-settings-v2" | "claude-settings-v3" | "claude-settings-v4" | "claude-marketplace-registry-v2" | "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3" | "codex-settings-v4" | "codex-settings-v5" | "codex-settings-v6" | "executable-v1" | "sumi-settings-v1" | "claude-marketplace-entry-v1";
+    hashMode?: "bytes" | "path-bytes" | "claude-plugin-orphaned-at-v1" | "claude-plugin-manifest-v1" | "claude-plugin-registry" | "claude-marketplace-registry" | "claude-settings-v1" | "claude-settings-v2" | "claude-settings-v3" | "claude-settings-v4" | "claude-marketplace-registry-v2" | "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3" | "codex-settings-v4" | "codex-settings-v5" | "codex-settings-v6" | "executable-v1" | "sumi-settings-v1" | "claude-marketplace-entry-v1";
     hookSources?: CodexReviewedHookSource[];
     managedPlugins?: ManagedPluginRegistrationWitness[];
     format?: "json" | "toml" | "yaml";
@@ -94,23 +96,56 @@ export declare function projectNativeDiscoveryFields(text: string, format: "json
 /** Called only after the owning planner validated discovery and capabilities.
  * New roots must already be body-free; absent roots need the prior typed proof. */
 export declare function captureRetiredCodexDiscovery(binding: AgentDiscoveryBinding, controls: CodexPluginSkillControl[], rules: unknown): AgentDiscoveryBinding;
+/** The witness class that may keep its reviewed digest beneath a positively
+ * verified absent root: a full byte witness, the installer's full manifest
+ * projection or a present version-root orphan marker. Null for every other
+ * source, which must stay current. */
+export type RetainedAbsentWitness = "bytes" | "claude-plugin-manifest-v1" | typeof CLAUDE_ORPHAN_MARKER_MODE;
 /** Only native capability locations covered by the complete typed cache census
  * qualify. Historical sources remain stored; arbitrary missing files do not. */
 export declare function codexSemanticCacheSourceRole(source: DiscoverySource, cacheRoot: string, parents: readonly string[], hookParents?: readonly string[]): boolean;
 export declare function codexSemanticCacheDirectoryRole(path: string, cacheRoot: string): boolean;
 export declare function assertCodexSemanticCacheHookSafety(cacheRoot: string, parents: readonly string[], configPath: string, hookRootAlias?: CodexSemanticCacheDiscovery["hookRootAlias"]): void;
+/** Source-byte and directory-membership drift are NativeDiscoveryWitnessChange
+ * errors. Only the live Codex prompt hook passes `witnessTolerance`; a change it
+ * accepts as a vendor refresh is collected and the remaining checks still run.
+ * Every other change and every other failure throws as before. */
 export declare function verifyAgentDiscovery(binding: AgentDiscoveryBinding, codexRecovery?: CodexHookDiscoveryRecovery, reviewedRootAliases?: readonly {
     agent: IntegrationAgent;
     alias: string;
     target: string;
-}[]): void;
+}[], witnessTolerance?: NativeDiscoveryWitnessTolerance): void;
+/** One stored Claude discovery source as an installer sees it. */
+export type ClaudeDiscoverySourceVerdict = {
+    status: "current";
+} | {
+    status: "retained-absent";
+    root: string;
+    witness: RetainedAbsentWitness;
+} | {
+    status: "drift";
+    reason: "MISSING" | "APPEARED" | "CHANGED" | "MARKER_INVALID" | "REFUSED";
+};
+/** Read-only, per-source report on a stored Claude discovery binding, in
+ * stored order. A source is retained only through the same absent retired
+ * version rule and predicate verifyAgentDiscovery applies; a refused rule
+ * retains nothing. Every other source is checked by its own witness, exactly
+ * as verification checks it (a typed orphan marker by the marker predicate).
+ * This report never accepts a binding by itself: a caller must also require
+ * verifyAgentDiscovery to accept the same binding. */
+export declare function classifyClaudeDiscoverySources(binding: AgentDiscoveryBinding): ClaudeDiscoverySourceVerdict[];
 export declare function rebindAgentDiscovery(binding: AgentDiscoveryBinding, changes: Map<string, string>): AgentDiscoveryBinding;
 /** Explicit streaming integrity witness. Never read an executable as text or execute it. */
 export declare function captureDiscoveryExecutableSources(paths: string[]): DiscoverySource[];
-/** Capture full byte witnesses for reviewed source or executable files; never import or execute them. */
+/** Capture exact source bytes, or typed Claude cache marker presence; never execute them. */
 export declare function captureDiscoveryByteSources(paths: string[]): DiscoverySource[];
 /** Capture executable/source path identity, including links and absent targets. */
 export declare function captureDiscoveryPathSources(paths: string[]): DiscoverySource[];
+/** Top-level keys whose presence, at any value, makes a project Claude settings
+ * file a higher-precedence discovery source that needs review. Claude 2.1.300
+ * rewrites `additionalMarketplaces` into `extraKnownMarketplaces` on every
+ * settings read, including local settings, so the alias counts as well. */
+export declare const CLAUDE_PROJECT_DISCOVERY_KEYS: readonly ["enabledPlugins", "extraKnownMarketplaces", "additionalMarketplaces", "skillOverrides"];
 /** Project settings can introduce a higher-precedence discovery source. Until
  * its native merge format is supported, refuse that layer rather than certify
  * the home-only inventory. Ordinary unrelated project settings remain usable. */
@@ -120,13 +155,30 @@ export declare function assertProjectDiscovery(agent: IntegrationAgent, director
 export declare function agentDiscoveryConfigPath(home: string, agent: IntegrationAgent): string;
 /** Re-derive an automatic binding and compare it with the stored one. A
  * mismatch is drift, except when the only difference is a runtime this process
- * cannot resolve: then it is DISCOVERY_ROOT_UNRESOLVED, which stays blocking. */
+ * cannot resolve: then it is DISCOVERY_ROOT_UNRESOLVED, which stays blocking.
+ * Only the live Codex prompt hook passes `witnessTolerance`: when roots, method
+ * and every source and directory path are unchanged, only witness digests differ
+ * and the tolerance accepts every one of them, they are collected instead of
+ * refusing. */
 export declare function verifyAutomaticDiscoveryClosure(binding: AgentDiscoveryBinding, options: {
     home: string;
     canonical: (path: string) => string;
     change: string;
     executable?: DiscoveryExecutable;
+    witnessTolerance?: NativeDiscoveryWitnessTolerance;
 }): void;
+/** True only when the changed Codex config.toml differs from its reviewed
+ * witness by appended vendor disable rows and/or vendor plugin disables:
+ * removing those entries or restoring a formerly enabled vendor flag reproduces
+ * the stored digest. Witness modes
+ * without a replacement digest (V6, artifacts, managed registries) stay strict. */
+export declare function codexVendorConfigChangeOnly(source: DiscoverySource, cache: string): boolean;
+/** Whether replacing `path` with `text` leaves every recorded witness of it
+ * satisfied, judged by each source's own digest mode without touching the file,
+ * with the same screen-reader receipt tolerance typed V1-V5 verification applies.
+ * Fails closed: a review artifact, managed-plugin or hook-source witness, a
+ * semantic cache binding of the file, or an unsupported mode counts as changed. */
+export declare function discoveryTextKeepsWitness(binding: Pick<AgentDiscoveryBinding, "sources" | "codexSemanticCache">, path: string, text: string): boolean;
 /** `executable` is the agent's runtime: omitted, it is resolved through PATH;
  * a value (or null for none) is used as given, so verification never depends
  * on the caller's PATH. */

package/dist/lib/agent-integration.d.ts

@@ -2,6 +2,7 @@ import { type CodexCorpusWriteOptions } from "./codex-corpus-write.js";
 import { type ReviewedCodexSkillDenial } from "./codex-plugin-skill-controls.js";
 import { type CodexNativeHookEnvelope, type ProcessInspector, type NativePolicyHelperRunner } from "./codex-native-skill-policy.js";
 import { type CodexNativeSkillCatalog } from "./codex-native-skill-catalog.js";
+import type { NativeDiscoveryWitnessKind } from "./native-discovery-witness-change.js";
 import { type DiscoveryExecutable, type AgentDiscoveryBinding, type ReviewedDiscoveryInputs } from "./agent-discovery.js";
 import { type IntegrationAgent } from "./agent-adapters.js";
 import type { CodexHookDiscoveryRecovery } from "./codex-hook-discovery-recovery.js";
@@ -279,15 +280,52 @@ interface ManagedBridgeOptions {
     profileId?: string;
     codexDiscoveryRecovery?: CodexHookDiscoveryRecovery;
     codexNativePolicy?: CodexNativePolicyGuardInput;
+    /** Live Codex prompt hook only. Exempt vendor Codex plugin-cache copies that
+     * Codex configuration provably disables, and tolerate, with a warning, the
+     * discovery-witness changes a vendor plugin refresh provably makes. Enabled
+     * vendor copies and every other change still refuse. Install, trust, migrate
+     * and sync never pass it. */
+    codexPromptHook?: boolean;
+}
+/** Result of a guard call; both lists are empty unless the caller opted in.
+ * `codexInertVendorCopies` holds the canonical skill directories exempted as
+ * disabled vendor copies; `codexDiscoveryChanges` the witnesses tolerated as a
+ * vendor plugin refresh. */
+export interface ManagedBridgeReport {
+    codexInertVendorCopies: string[];
+    codexDiscoveryChanges: Array<{
+        kind: NativeDiscoveryWitnessKind;
+        path: string | null;
+    }>;
 }
 /** Package-classified installed-plugin content below the Codex plugin cache that
  * a verified restricted policy cannot load. Classification is the existing plugin
  * manifest identity and real-path binding, never a path prefix; user, repo and
  * project copies, unclassified cache files and any allowed host path refuse. */
 export declare function isInertCodexPluginCacheCopy(entry: NativeSkillEntry, cache: string, allowedHostPaths: readonly string[], read: (path: string) => string): boolean;
+/** A vendor plugin-cache copy that Codex configuration provably disables, so its
+ * payload never loads natively. Vendor means: classified installed-plugin content
+ * in an allowlisted OpenAI marketplace (exact names), with the native remote
+ * install receipt for remote marketplaces, no Skills-managed or Hasna marker,
+ * and a plugin whose every cached version passes the fail-closed refresh check
+ * (codexVendorPluginRefreshSafe: one Codex manifest with only known keys, no
+ * hooks, MCP, command, agent or extension declaration, no other manifest
+ * location, no link and no skill hidden from the inventory or nested in
+ * another). Classification reads only the Codex manifest, so without that check
+ * a version could load payloads no rule here covers. Disabled means: a `[[skills.config]]`
+ * rule names its exact SKILL.md path or its plugin-qualified name with
+ * `enabled = false` (the native ordered evaluation agrees), and no matching rule
+ * enables it. A whole-plugin `[plugins."<id>"] enabled = false` table is never
+ * enough: remote state can enable a locally disabled remote plugin, and a
+ * cache copy carries no proof that its source is configuration-controlled. */
+export declare function isInertCodexVendorPluginCopy(entry: NativeSkillEntry, cache: string, rules: unknown, read: (path: string) => string): boolean;
+/** Visible, non-blocking warning for the discovery-witness changes the live Codex
+ * prompt hook tolerated as a vendor plugin refresh, or undefined when there were
+ * none. One bounded line; paths only, never payloads or file contents. */
+export declare function codexPromptDriftWarning(report: ManagedBridgeReport): string | undefined;
 /** Run before any prompt context load. Missing ownership or reappearing native
  * discovery files require repair; verified cache availability is not an override. */
-export declare function assertManagedAgentBridge(agent: IntegrationAgent, options?: ManagedBridgeOptions): void;
+export declare function assertManagedAgentBridge(agent: IntegrationAgent, options?: ManagedBridgeOptions): ManagedBridgeReport;
 export declare function normalizeAgentHookPrompt(agent: IntegrationAgent, event: string, prompt: string): string;
 export declare function hookContextOutput(event: string, result: {
     context: string;

package/dist/lib/claude-installer-binding.d.ts

@@ -0,0 +1,65 @@
+import { type RetainedAbsentWitness } from "./agent-discovery.js";
+export declare const CLAUDE_DISCOVERY_BINDING_VERIFICATION_SCHEMA: "skills.claude-discovery-binding-verification/v1";
+/** The rule that lets a stored witness stay unverified because Claude removed
+ * its whole retired plugin-cache version while unchanged settings and
+ * registrations select a current sibling version. */
+export declare const ABSENT_RETIRED_CLAUDE_VERSION_RULE: "absent-retired-claude-version";
+export type ClaudeDiscoveryBindingRefusalCode = "POLICY_PATH_MISMATCH" | "POLICY_UNAVAILABLE" | "POLICY_UNREADABLE" | "BINDING_UNAVAILABLE" | "BINDING_INVALID" | "POLICY_CHANGED";
+/** A request, policy or stored-binding read/parse failure: no verdict. */
+export declare class ClaudeDiscoveryBindingRefusal extends Error {
+    readonly code: ClaudeDiscoveryBindingRefusalCode;
+    constructor(code: ClaudeDiscoveryBindingRefusalCode);
+}
+export type ClaudeBindingSourceFailure = "MISSING" | "APPEARED" | "CHANGED" | "MARKER_INVALID" | "REFUSED";
+export type ClaudeBindingDirectoryFailure = "MEMBERSHIP_CHANGED" | "REFUSED";
+export interface ClaudeBindingSourceReport {
+    index: number;
+    path: string;
+    hashMode: string | null;
+    format: string | null;
+    sha256: string | null;
+    status: "current" | "retained-absent" | "drift";
+    retention?: {
+        rule: typeof ABSENT_RETIRED_CLAUDE_VERSION_RULE;
+        root: string;
+        witness: RetainedAbsentWitness;
+    };
+    reason?: ClaudeBindingSourceFailure;
+}
+export interface ClaudeBindingDirectoryReport {
+    index: number;
+    path: string;
+    status: "current" | "drift";
+    reason?: ClaudeBindingDirectoryFailure;
+}
+export type ClaudeBindingFailure = {
+    kind: "source";
+    index: number;
+    path: string;
+    reason: ClaudeBindingSourceFailure;
+} | {
+    kind: "directory";
+    index: number;
+    path: string;
+    reason: ClaudeBindingDirectoryFailure;
+} | {
+    kind: "binding";
+    reason: "DISCOVERY_REFUSED";
+};
+export interface ClaudeDiscoveryBindingVerification {
+    schema: typeof CLAUDE_DISCOVERY_BINDING_VERIFICATION_SCHEMA;
+    ok: boolean;
+    policySha256: string;
+    discoverySha256: string;
+    agent: "claude";
+    method: "reviewed" | "automatic";
+    rootCount: number;
+    sources: ClaudeBindingSourceReport[];
+    directories: ClaudeBindingDirectoryReport[];
+    failures: ClaudeBindingFailure[];
+}
+/** Verify the stored `bridge.discovery.claude` binding of the package-owned
+ * Skills policy. `ok` is true only when the hook's own discovery verification
+ * accepts the binding and every source is current or retained under the
+ * absent retired version rule, and every directory witness is current. */
+export declare function verifyClaudeInstallerDiscoveryBinding(policyPath: string): ClaudeDiscoveryBindingVerification;

package/dist/lib/claude-plugin-cache-marker.d.ts

@@ -0,0 +1,10 @@
+import type { DiscoveryByteBudget } from "./agent-discovery-bytes.js";
+export declare const CLAUDE_ORPHAN_MARKER_MODE: "claude-plugin-orphaned-at-v1";
+/** True only for `<...>/.claude/plugins/cache/<marketplace>/<plugin>/<version>/.orphaned_at`
+ * with exactly one cache segment in the path. Every other path, including a
+ * marker at another depth, keeps its ordinary exact witness. */
+export declare function isClaudePluginCacheOrphanMarker(path: string): boolean;
+/** Validate on every capture and check; only presence enters the digest.
+ * Claude rewrites the timestamp (and may replace the inode) between checks,
+ * so neither is bound, but the file may not change during one read. */
+export declare function hashClaudePluginCacheOrphanMarker(path: string, budget?: DiscoveryByteBudget, changes?: Map<string, string>): string | null;

package/dist/lib/codex-node-modules.d.ts

@@ -0,0 +1,11 @@
+/** Whether Codex can load a skill below `path`, a `node_modules` directory
+ * `depth` levels below its plugin cache. A marketplace, plugin or version
+ * directory is an identity, so one named `node_modules` is always walked.
+ * Inside a version, the directory is walked when it lies in, or leads to, a
+ * manifest-declared skills path or the default `skills` root. Codex replaces
+ * the default with a declared path; Skills keeps walking it, as it walks every
+ * other visible directory in the cache. A manifest that cannot be read exactly
+ * (a link or special file, oversized, invalid UTF-8 or JSON, duplicate keys, an
+ * unsupported skills shape or an escaping path) walks it too, so an unreadable
+ * declaration never hides a loaded skill. */
+export declare function codexPluginCacheSkillTree(path: string, depth: number): boolean;

package/dist/lib/codex-plugin-skill-controls.d.ts

@@ -32,6 +32,15 @@ export interface CodexPluginSourceInput {
     sourceSha256: string;
 }
 type Read = (path: string) => string;
+/** The remote plugin identifier from the exact native install receipt Codex
+ * writes beside a remote plugin's versions, or null when it is absent or invalid. */
+export declare function codexRemoteInstallReceipt(parent: string, read: Read): string | null;
+/** Whether a vendor refresh's `.app.json` connector declaration is valid under
+ * the same appControls validation rootControls applies (duplicate keys, the
+ * single `apps` object, app names, `id`/`category`/`required` only, types and
+ * caps), read as a regular, unlinked file of at most 1 MiB in strict UTF-8.
+ * Every failure is false. */
+export declare function codexAppDeclarationValid(path: string): boolean;
 export interface CodexPluginRootControls {
     namespace: string;
     manifestSha256: string;

package/dist/lib/codex-settings-witness-v1.d.ts

@@ -1,5 +1,14 @@
 import { type ClaudeSettingsWitnessBudget } from "./claude-settings-witness.js";
 export declare function hashCodexSettingsReplacement(text: string, budget?: ClaudeSettingsWitnessBudget): string;
+/** The parsed document and numeric spellings a V1 digest binds, before the
+ * documented inference fields are removed. Callers that edit the structure
+ * (codexSettingsToleratesScreenReaderReceipt) finish each edited copy separately. */
+export declare function prepareCodexSettingsV1(text: string): {
+    config: Record<string, any>;
+    tokens: string[];
+};
+/** The V1 digest of a prepared structure. Mutates `config`. */
+export declare function finishCodexSettingsV1(config: Record<string, any>, tokens: string[]): string;
 export declare function captureCodexSettings(path: string, budget?: ClaudeSettingsWitnessBudget): {
     path: string;
     hashMode: "codex-settings-v1";

package/dist/lib/codex-settings-witness.d.ts

@@ -5,6 +5,24 @@ import { type ClaudeSettingsWitnessBudget } from "./claude-settings-witness.js";
  * `codex-settings-v2` witness binds strictly more of the same file, so it
  * supersedes this projection instead of coexisting with it. */
 export declare const CODEX_DISCOVERY_PROJECTION_FIELDS: readonly ["plugins", "marketplaces", "skills"];
+/** Typed modes whose digests bind the receipt. */
+export type CodexReceiptSettingsMode = "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3" | "codex-settings-v4" | "codex-settings-v5";
+/** How a current document relates to a typed V1-V5 witness's reviewed digest.
+ * `screen-reader-receipt` is the only tolerated difference. */
+export type CodexSettingsWitnessMatch = "exact" | "screen-reader-receipt";
+/** True when `text` differs from the document a typed V1-V5 witness reviewed
+ * only by the boolean screen-reader receipt, proven by reproducing `expected`
+ * under the witness's own unchanged digest from the current document with the
+ * receipt edited back. The text-bound projections (local MCP rows, V4 counts,
+ * numeric spelling) run once on the current text; a receipt line holds no
+ * numeric token. Digest values never change and nothing is recorded. Any other
+ * TUI key, a non-boolean value and every other difference stay bound.
+ * Fail-closed: errors return false. */
+export declare function codexSettingsToleratesScreenReaderReceipt(text: string, hashMode: CodexReceiptSettingsMode, expected: string): boolean;
+/** Read a typed V1-V5 settings witness file once and classify it against the
+ * reviewed digest: `exact`, `screen-reader-receipt` (the only tolerated
+ * difference), or null (drift). */
+export declare function codexSettingsWitnessMatch(path: string, hashMode: CodexReceiptSettingsMode, expected: string, budget?: ClaudeSettingsWitnessBudget): CodexSettingsWitnessMatch | null;
 export declare function hashCodexSettingsReplacementV2(text: string, budget?: ClaudeSettingsWitnessBudget): string;
 export declare function captureCodexSettingsV2(path: string, budget?: ClaudeSettingsWitnessBudget): {
     path: string;

package/dist/lib/codex-vendor-refresh.d.ts

@@ -0,0 +1,54 @@
+/** OpenAI's own Codex plugin marketplaces, by their exact native names in Codex
+ * 0.162.1. Only these hold vendor plugin copies; every other marketplace,
+ * including Hasna's and look-alike names, is never treated as vendor content. */
+export declare const CODEX_VENDOR_MARKETPLACES: readonly string[];
+/** Vendor marketplaces whose plugins Codex installs remotely and records with a
+ * `.codex-remote-plugin-install.json` receipt beside their versions. */
+export declare const CODEX_REMOTE_VENDOR_MARKETPLACES: readonly string[];
+/** The allowlisted vendor marketplace a canonical path lies in, at or below
+ * `<cache>/<marketplace>`, or null for the cache itself, other marketplaces and
+ * any non-canonical path. */
+export declare function codexVendorMarketplace(cache: string, path: string): string | null;
+/** A plugin version root a vendor refresh can add without review: its only
+ * manifest is a regular `.codex-plugin/plugin.json` (alone in its directory,
+ * no duplicate keys) whose keys are all in VENDOR_MANIFEST_KEYS, with the
+ * default skills root and, when present, exactly the `./.app.json` connector
+ * declaration backed by an `.app.json` that passes the strict connector
+ * validation rootControls applies (codexAppDeclarationValid); there is no hooks, MCP, command
+ * or agent location and no root, Claude or Cursor manifest; every skill in it
+ * is visible to the native inventory. Errors and bounds refuse. */
+export declare function codexVendorPluginRootRefreshSafe(root: string, budget?: {
+    remaining: number;
+}): boolean;
+/** True only when every cached version of one vendor plugin
+ * (`<cache>/<marketplace>/<plugin>`) passes codexVendorPluginRootRefreshSafe,
+ * the plugin directory carries no manifest, hooks, MCP, command or agent
+ * location of its own, and no version is a link. Errors and bounds refuse. */
+export declare function codexVendorPluginRefreshSafe(parent: string, budget?: {
+    remaining: number;
+}): boolean;
+/** True only when every plugin in a vendor marketplace subtree could have been
+ * added by a routine vendor refresh: each plugin passes
+ * codexVendorPluginRefreshSafe and the marketplace holds no link, special file
+ * or hidden directory. Plugin hooks and other skill roots need their own
+ * review, so a membership change that adds them is never a routine vendor
+ * refresh. The whole marketplace is checked, not only new versions, so anything
+ * unexpected anywhere refuses. Bounded; links are never followed; errors refuse. */
+export declare function codexVendorSubtreeHookFree(cache: string, path: string): boolean;
+/** Candidate earlier versions of a Codex config.toml that differ from `text`
+ * only by appended vendor disable rows and/or vendor plugin disables,
+ * the entries an operator or Codex adds when a vendor plugin refreshes. Each
+ * candidate is checked to parse to exactly `text` without those entries, so a
+ * candidate whose digest equals the reviewed witness proves the change is
+ * vendor-only. Anything the text model cannot remove exactly yields no
+ * candidate, which keeps the witness strict.
+ *
+ * Bounds: at most 8 vendor plugin tables, 16 trailing rows and 128 candidates,
+ * tried smallest edit first (fewest changed tables, then fewest removed rows).
+ * `rowsAffectDigest: false` (a typed V2-V5 witness, which ignores disable-only
+ * rows) skips row removal; with it, every change to at most two of eight
+ * tables fits the 128 candidates. Otherwise appended rows alone always fit.
+ * A bound only ever omits candidates, so it can only cause a refusal. */
+export declare function codexVendorConfigCandidates(text: string, cache: string, options?: {
+    rowsAffectDigest?: boolean;
+}): string[];

package/dist/lib/config.d.ts

@@ -39,6 +39,8 @@ export interface SkillsConfig {
     defaultScope?: "global" | "project";
     format?: "compact" | "json" | "csv";
     extensionsDir?: string;
+    /** Managed hooks, global scope only: "auto" (default) migrates a refused expired session pin; "off" keeps the refusal. */
+    sessionPinMigration?: "auto" | "off";
 }
 export type ConfigScope = "global" | "project";
 /**
@@ -97,6 +99,24 @@ export declare function loadConfigReadOnly(): SkillsConfig;
  * Get the config file path for a given scope
  */
 export declare function getConfigPath(scope: ConfigScope): string;
+/**
+ * Managed hooks migrate a session pin whose renewal was refused only because
+ * its profile moved on, unless the station turns that off with
+ * `skills config set sessionPinMigration off --global`. Only the global
+ * configuration is read: the prompt hook never reads a project-controlled file
+ * for this.
+ *
+ * This reads the file itself instead of readConfigFile, which returns {} for
+ * an unreadable or malformed file. An opt-out must survive a damaged file, so
+ * "auto" needs one of two confirmed states. Either lstat finds no entry at the
+ * path and its directory exists, or the entry is a regular file (not a
+ * symlink), opened without following links, holding a JSON object without the
+ * key or with exactly "auto". Everything else keeps the refusal: a dangling or
+ * other symlink, a directory or other non-regular entry, a missing or dangling
+ * data directory, any read error, a parse error (including a truncated write),
+ * a non-object document, a retired key, or a value other than "auto" or "off".
+ */
+export declare function sessionPinMigrationEnabled(): boolean;
 /**
  * Load merged config: project-local overrides global
  */

package/dist/lib/hook-diagnostics.d.ts

@@ -3,7 +3,9 @@ export declare const HOOK_REFUSAL_REASON_CODES: readonly string[];
 export declare class HookDiagnosticError extends Error {
     readonly code: string;
     readonly stage: "context" | "sync";
-    constructor(code: string, stage: "context" | "sync");
+    /** Fixed marker: a refused renewal whose automatic pin migration ran out of budget. */
+    readonly migration?: "timeout";
+    constructor(code: string, stage: "context" | "sync", migration?: "timeout");
 }
 export declare function hookChildError(stdout: string, stage: "context" | "sync"): HookDiagnosticError;
 export declare function hookFailureReason(error: unknown, profileId?: string): string;

package/dist/lib/native-discovery-witness-change.d.ts

@@ -0,0 +1,25 @@
+import type { DiscoverySource } from "./agent-discovery.js";
+/** What changed under a reviewed native discovery witness: a bound source
+ * file's projected bytes, or a bound directory's membership. */
+export type NativeDiscoveryWitnessKind = "input" | "membership";
+/** A reviewed discovery witness no longer matches the current file system. It is
+ * drift of something the review bound, never an invalid, missing or unresolvable
+ * binding, which keep their own plain errors. The message is unchanged from the
+ * plain error each site threw before, so every caller that does not tolerate
+ * these sees exactly the same refusal. */
+export declare class NativeDiscoveryWitnessChange extends Error {
+    readonly kind: NativeDiscoveryWitnessKind;
+    /** Canonical path the witness bound, or null when the site names none. */
+    readonly path: string | null;
+    constructor(kind: NativeDiscoveryWitnessKind, path: string | null, message: string);
+}
+/** Live Codex prompt hook only. Decides, per changed witness, whether the change
+ * is provably one a Codex vendor plugin refresh makes; accepted changes are
+ * collected instead of refusing. Every other change still throws. */
+export interface NativeDiscoveryWitnessTolerance {
+    acceptsInput(source: DiscoverySource): boolean;
+    acceptsMembership(path: string): boolean;
+    readonly changes: NativeDiscoveryWitnessChange[];
+}
+/** Throw the change unless an opted-in tolerance accepted it. */
+export declare function witnessChanged(change: NativeDiscoveryWitnessChange, tolerance: NativeDiscoveryWitnessTolerance | undefined, accepted: boolean): void;

package/dist/lib/selection-cache.d.ts

@@ -18,6 +18,11 @@ export interface SkillSessionParentBinding {
     generation: number;
     receiptSha256: string;
 }
+/** The project lock a session's pin was inherited from: its absolute path and the SHA-256 of its exact bytes. */
+export interface SkillSessionProjectLock {
+    path: string;
+    sha256: string;
+}
 export interface SkillSessionReceipt extends CachedSelectionProfile {
     sessionId: string;
     loaded: string[];
@@ -25,6 +30,12 @@ export interface SkillSessionReceipt extends CachedSelectionProfile {
     generation?: number;
     /** Private local metadata binding a child receipt to the exact parent snapshot it inherited. */
     parent?: SkillSessionParentBinding;
+    /**
+     * Set when the session was created from a project lock (and inherited by its
+     * child sessions). Such a pin follows that intentional lock, so the managed
+     * hook never migrates it automatically, whatever the prompt's directory.
+     */
+    projectLock?: SkillSessionProjectLock;
 }
 export interface SkillSessionSnapshot extends SkillSessionParentBinding {
     path: string;
@@ -60,6 +71,11 @@ export declare function assertFreshCachedProfile(receipt: CachedSelectionProfile
 }): void;
 export declare function projectSelectionLockPath(projectDir: string): string;
 export declare function readProjectSelection(projectDir: string): CachedSelectionProfile | null;
+/** The project lock with the provenance a session created from it records. */
+export declare function readProjectSelectionSnapshot(projectDir: string): {
+    receipt: CachedSelectionProfile;
+    lock: SkillSessionProjectLock;
+} | null;
 export declare function sessionReceiptPath(sessionId: string, options?: SelectionCacheOptions): string;
 export declare function readSkillSession(sessionId: string, options?: SelectionCacheOptions): SkillSessionReceipt | null;
 export declare function readSkillSessionSnapshotIfExists(sessionId: string, options?: SelectionCacheOptions): SkillSessionSnapshot | null;
@@ -77,6 +93,12 @@ export declare function inspectSessionWriteLock(sessionId: string, options?: Sel
     hostBound: boolean;
 };
 export declare function recoverSessionWriteLock(sessionId: string, reviewDigest: string, options?: SelectionCacheOptions): string;
+/**
+ * Hold this session's receipt write lock for state that must change only with
+ * its pin (the managed-hook migration notice). Another holder refuses with
+ * SESSION_WRITE_BUSY; nothing waits.
+ */
+export declare function withSkillSessionWriteLock<T>(sessionId: string, options: SelectionCacheOptions, action: (assertOwned: () => void) => T): T;
 export declare function nextSkillSessionGeneration(generation: number): number;
 /** Receipt creation and updates are exact-snapshot CAS operations. Child creation also fences its parent. */
 export declare function writeSkillSession(receipt: SkillSessionReceipt, expected: SkillSessionWritePrecondition, options?: SelectionCacheOptions): void;

package/dist/lib/selection-resolver.d.ts

@@ -2,7 +2,7 @@
 import { type ProfileClient } from "./profile-client.js";
 import type { ResolvedSkillProfile, ResolvedSkillSelection } from "../types/skill-selection.js";
 import type { SkillBundleEntry } from "./skill-bundle.js";
-import { type CachedSelectionProfile, type SelectionCacheOptions, type SkillSessionParentBinding, type SkillSessionReceipt } from "./selection-cache.js";
+import { type CachedSelectionProfile, type SelectionCacheOptions, type SkillSessionParentBinding, type SkillSessionProjectLock, type SkillSessionReceipt } from "./selection-cache.js";
 export interface SelectionResolverOptions extends SelectionCacheOptions {
     client?: ProfileClient;
     cached?: boolean;
@@ -36,6 +36,8 @@ export interface ResolvedSelectionContext {
     parentSnapshot?: SkillSessionParentBinding;
     inheritedLoaded?: string[];
     client?: ProfileClient;
+    /** Set when a new session's pin comes from the project lock; the session receipt records it. */
+    projectLock?: SkillSessionProjectLock;
 }
 export declare function resolveSelectionContext(profileId: string, options?: SelectionResolverOptions): Promise<ResolvedSelectionContext>;
 export declare function readSelectedEntries(selection: ResolvedSkillSelection, context: ResolvedSelectionContext, options?: SelectionResolverOptions): Promise<SkillBundleEntry[]>;

package/dist/lib/session-reconciliation.d.ts

@@ -1,5 +1,5 @@
 import { type ProfileClient } from "./profile-client.js";
-import { type SelectionCacheOptions } from "./selection-cache.js";
+import { SkillSelectionError, type SelectionCacheOptions } from "./selection-cache.js";
 export interface SessionReconciliationInput {
     sessionId: string;
     fromProfile: string;
@@ -58,8 +58,21 @@ export declare const SESSION_RENEWAL_TIMEOUT_MS = 4000;
  * It binds the exact receipt bytes, profile, authority, workspace and the
  * locally synced profile revision, and lapses after a fixed window that the
  * file cannot extend. Anything unexpected is ignored and the authority is asked.
+ *
+ * Two kinds exist. A renewal refusal says only that this pin cannot be renewed
+ * as it is, so it is repeated only while migration is off. A refusal of the
+ * managed hook's migration itself (a project lock, a rotated epoch, a planner
+ * refusal or anything else that is not transient) also implies the renewal
+ * refusal, so it is repeated in either mode. Timeouts, an unavailable
+ * authority, write-lock contention and other transient failures are never
+ * remembered.
  */
 export declare const SESSION_RENEWAL_REFUSAL_TTL_MS: number;
+/**
+ * Return the pending migration notice for this session once its pin holds the
+ * migrated profile, then mark it delivered. Anything unexpected returns null.
+ */
+export declare function takeSessionPinMigrationNotice(sessionId: string, options?: SelectionCacheOptions): string | null;
 /**
  * Renew authorization for the complete immutable pin; never manufacture a
  * profile combining historical loaded versions with current unloaded versions.
@@ -67,6 +80,49 @@ export declare const SESSION_RENEWAL_REFUSAL_TTL_MS: number;
  * versions additionally require the authenticated exact-version bundle read.
  */
 export declare function reconcileSkillSessionIfSafe(sessionId: string, profileId: string, options?: SessionReconciliationOptions): Promise<boolean>;
+/** Metadata only: what an automatic migration retired, never payloads. */
+export interface SessionPinMigration {
+    profileId: string;
+    fromRevision: string;
+    toRevision: string;
+    retainedLoadedCount: number;
+    retiredLoadedCount: number;
+    retired: SessionSelectionDelta[];
+    archivePath: string;
+    receiptPath: string;
+}
+export type SessionPinRenewalOutcome = {
+    outcome: "unchanged";
+} | {
+    outcome: "renewed";
+} | {
+    outcome: "migrated";
+    migration: SessionPinMigration;
+};
+export interface SessionPinRenewalOptions extends SessionReconciliationOptions {
+    /**
+     * Managed hooks only: when renewal is refused because the same profile moved
+     * on, apply the explicit reconciliation plan to the authenticated current
+     * revision instead. Every other failure keeps its existing refusal.
+     */
+    migrate?: boolean;
+    /**
+     * Required for `migrate`: the prompt's directory (the hook input's cwd).
+     * Without it, or while it or an ancestor holds a project lock, migration
+     * does not run.
+     */
+    projectDir?: string;
+}
+/**
+ * A refused renewal whose automatic migration could not finish within the
+ * renewal deadline. It keeps the refusal code; the fixed `migration` marker
+ * lets the hook say why without carrying free text across its boundary.
+ */
+export declare class SessionPinMigrationTimeout extends SkillSelectionError {
+    readonly migration: "timeout";
+    constructor();
+}
+export declare function renewSkillSessionPin(sessionId: string, profileId: string, options?: SessionPinRenewalOptions): Promise<SessionPinRenewalOutcome>;
 /** Explicit review for changed loaded selections or intentional profile migration. */
 export declare function reconcileSkillSession(input: SessionReconciliationInput, options?: SessionReconciliationOptions): Promise<{
     applied: false;