@hasna/skills 0.10.2 → 0.10.4

package/README.md

@@ -453,17 +453,22 @@ during installation. A successful update does not reload an existing session.
 At session start, the hook authenticates and refreshes the profile. Prompt hooks
 select complete skill instructions from that verified cache using explicit
 `$skill` references, profile keywords, paths and always-required selections.
-A session retains its selected versions; compaction restores loaded instructions,
+A session retains its loaded selections; compaction restores loaded instructions,
 and subagents inherit the parent's selection. Instructions that exceed the
 context budget produce an explicit `skills load` command. A hook never executes
-a skill. Cached use is explicit and expires after 24 hours. When cached context
-expires or is missing, the hook makes one authenticated API attempt for the same
-pinned session. It preserves exact versions and does not extend an expired
-receipt's lifetime. Authentication, integrity and native discovery failures still
-block; they do not silently switch to a local catalog.
-
-An intentional profile change for an already running session uses a separate
-reviewed operation. `sync` and hook reinstallation do not migrate session pins:
+a skill. Cached use is explicit and expires after 24 hours. When a session
+receipt expires, the hook authenticates the current profile. If every loaded
+selection still has identical metadata and bundle digest, it archives the old
+receipt and advances that session to the current profile under an exact receipt
+precondition. Unloaded selections may be added or removed. If a loaded selection
+changed or disappeared, the hook blocks and requires the explicit reconciliation
+below. A missing cache may be recovered through authenticated context.
+Authentication, integrity and native discovery failures still block; they do
+not silently switch to a local catalog.
+
+An intentional change to a loaded selection or profile identity for an already
+running session uses a separate reviewed operation. `sync` and hook
+reinstallation do not migrate session pins:
 
 ```bash
 skills sessions show <session-id> --json

package/bin/index.js

@@ -36868,7 +36868,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.10.2",
+    version: "0.10.4",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -51164,7 +51164,7 @@ function parseNativeMigrationTargetManifest(input) {
     if (!target || typeof target !== "object" || Array.isArray(target))
       throw new Error("Invalid native migration target");
     const item = target;
-    if (Object.keys(item).some((key) => !["agent", "projectRoot", "path", "treeSha256"].includes(key)) || typeof item.agent !== "string" || typeof item.projectRoot !== "string" || typeof item.path !== "string" || typeof item.treeSha256 !== "string")
+    if (Object.keys(item).some((key) => !["agent", "projectRoot", "path", "treeSha256", "vendor"].includes(key)) || typeof item.agent !== "string" || typeof item.projectRoot !== "string" || typeof item.path !== "string" || typeof item.treeSha256 !== "string" || item.vendor !== undefined && item.vendor !== true)
       throw new Error("Invalid native migration target fields");
     if (!ROOTS.some(([agent]) => agent === item.agent))
       throw new Error(`Unsupported native migration target agent: ${item.agent}`);
@@ -51183,7 +51183,7 @@ function parseNativeMigrationTargetManifest(input) {
     if (identities.has(identity4))
       throw new Error(`Duplicate native migration target: ${item.path}`);
     identities.add(identity4);
-    targets.push({ agent: item.agent, projectRoot, path: normalized, treeSha256: item.treeSha256 });
+    targets.push({ agent: item.agent, projectRoot, path: normalized, treeSha256: item.treeSha256, ...item.vendor === true ? { vendor: true } : {} });
   }
   return { schema: "hasna.skills-native-migration-targets.v1", targets, digest };
 }
@@ -51211,8 +51211,8 @@ function selectNativeMigrationTargets(inventory, manifest) {
     if (matches2.length !== 1)
       throw new Error(`Native migration target was not found exactly once: ${target.agent} ${target.projectRoot}/${target.path}`);
     const entry = matches2[0];
-    if (entry.bridge || entry.system || entry.vendor)
-      throw new Error(`Native migration target is protected or vendor-owned: ${entry.path}`);
+    if (entry.bridge || entry.system || entry.vendor !== (target.vendor === true))
+      throw new Error(`Native migration target is protected or vendor classification changed: ${entry.path}`);
     if (entry.hash !== target.treeSha256 || treeHash(entry.path) !== target.treeSha256)
       throw new Error(`Native migration target changed after review: ${entry.path}`);
     selected.push(entry);
@@ -51235,6 +51235,8 @@ function projectAncestorDirectories(projects) {
   return [...directories];
 }
 function inventoryNativeSkills(home = homedir3(), options = {}) {
+  if (options.reviewedCacheAlias !== undefined && (!options.includeVendor || !isAbsolute9(options.reviewedCacheAlias) || resolve10(options.reviewedCacheAlias) !== options.reviewedCacheAlias))
+    throw new Error("A reviewed cache alias requires vendor inventory and an exact absolute path");
   const aliases = rootAliases(home, options.allowRootAliases);
   const selectedAgents = options.agents ? new Set(options.agents) : undefined;
   const includesAgent = (agent) => !selectedAgents || selectedAgents.has(agent);
@@ -51255,14 +51257,22 @@ function inventoryNativeSkills(home = homedir3(), options = {}) {
     if (discoveryPathBytes > 4 * 1024 * 1024)
       throw new Error("Native skill discovery metadata limit exceeded");
   }
-  function emptySiblingCacheAlias(path, parent) {
+  let reviewedCacheAliasFound = false;
+  function verifiedSiblingCacheAlias(path, parent) {
     const link2 = readlinkSync3(path), target = resolve10(parent, link2);
     if (dirname10(target) !== parent || (isAbsolute9(link2) ? link2 !== target : dirname10(link2) !== "."))
       return false;
     if (!lstatSync14(target, { throwIfNoEntry: false })?.isDirectory())
       return false;
     const scan = cacheScans.get(target);
-    return Boolean(scan?.complete && !scan.hasSkills && scan.entries <= maxAliasProofEntries);
+    if (!scan?.complete || scan.entries > maxAliasProofEntries)
+      return false;
+    if (scan.hasSkills) {
+      if (path !== options.reviewedCacheAlias)
+        return false;
+      reviewedCacheAliasFound = true;
+    }
+    return true;
   }
   function visit2(agent, path, vendor = false, depth = 0, pluginCache = false, admitted = false) {
     if (!admitted)
@@ -51319,7 +51329,7 @@ function inventoryNativeSkills(home = homedir3(), options = {}) {
       const child = join20(path, name);
       if (isVendor && lstatSync14(child, { throwIfNoEntry: false })?.isSymbolicLink()) {
         const target = statSync7(child, { throwIfNoEntry: false });
-        if (target?.isFile() || pluginCache && target?.isDirectory() && emptySiblingCacheAlias(child, path)) {
+        if (target?.isFile() || pluginCache && target?.isDirectory() && verifiedSiblingCacheAlias(child, path)) {
           scan.entries++;
           continue;
         }
@@ -51353,6 +51363,8 @@ function inventoryNativeSkills(home = homedir3(), options = {}) {
   for (const root of [...options.agentRoots ?? [], ...configured])
     if (includesAgent(root.agent))
       scanRoot(root.agent, canonicalAgentPath(root.path, aliases), true);
+  if (options.reviewedCacheAlias !== undefined && !reviewedCacheAliasFound)
+    throw new Error("Reviewed cache alias was not an inventoried skill-containing sibling alias");
   recheckRootAliases(aliases);
   return entries;
 }
@@ -51934,12 +51946,17 @@ function assertManagedAgentBridge(agent, options = {}) {
   const setting = (path) => (codexConfig.skills?.config ?? []).filter((entry) => typeof entry.path === "string" && [path, join20(path, "SKILL.md")].includes(canonicalAgentPath(entry.path, aliases)));
   if (agent === "codex" && [...setting(expected), ...(codexConfig.skills?.config ?? []).filter((entry) => typeof entry.name === "string" && entry.name.trim() === CLI_BRIDGE_NAME)].some((entry) => entry.enabled === false))
     throw new Error("NATIVE_SKILL_DRIFT: the Codex CLI bridge is disabled; run skills hook install");
-  const disabledBuiltin = (entry) => {
-    if (agent !== "codex" || !entry.vendor || !entry.path.startsWith(canonicalAgentPath(join20(home, ".codex", "skills", ".system"), aliases) + sep4))
+  const disabledVendorSkill = (entry) => {
+    if (agent !== "codex" || !entry.vendor)
       return false;
-    const matched = Array.isArray(binding.disabledBuiltins) && binding.disabledBuiltins.some((item) => item.path === entry.path && item.hash === entry.hash);
     const settings = setting(entry.path);
-    return matched && settings.length === 1 && settings[0]?.enabled === false;
+    if (settings.length !== 1 || settings[0]?.enabled !== false)
+      return false;
+    if (entry.path.startsWith(canonicalAgentPath(join20(home, ".codex", "plugins", "cache"), aliases) + sep4))
+      return true;
+    if (!entry.path.startsWith(canonicalAgentPath(join20(home, ".codex", "skills", ".system"), aliases) + sep4))
+      return false;
+    return Array.isArray(binding.disabledBuiltins) && binding.disabledBuiltins.some((item) => item.path === entry.path && item.hash === entry.hash);
   };
   if (!discovery || discovery.agent !== agent)
     throw new Error("NATIVE_SKILL_DRIFT: native discovery coverage is missing; run skills hook install");
@@ -51956,7 +51973,7 @@ function assertManagedAgentBridge(agent, options = {}) {
     throw new Error(`NATIVE_SKILL_DRIFT: ${error.message}`);
   }
   const inventory = inventoryNativeSkills(home, { includeVendor: true, guardHermes: agent === "hermes", agents: [agent], projectDirs: [...roots], agentRoots: discovery.roots.map((path) => ({ agent, path })), allowRootAliases: aliases.length > 0 });
-  const unexpected = inventory.filter((entry) => visible(entry) && !entry.bridge && !disabledBuiltin(entry));
+  const unexpected = inventory.filter((entry) => visible(entry) && !entry.bridge && !disabledVendorSkill(entry));
   if (unexpected.length) {
     const paths = unexpected.slice(0, 3).map((entry) => {
       const escaped = JSON.stringify(entry.path).replace(/[\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
@@ -81557,6 +81574,7 @@ var init_skill_context = __esm(() => {
 
 // src/lib/session-reconciliation.ts
 import { createHash as createHash22 } from "crypto";
+import { isDeepStrictEqual as isDeepStrictEqual8 } from "util";
 function exactTimestamp(value) {
   const parsed = value === undefined ? Number.NaN : Date.parse(value);
   if (!Number.isFinite(parsed) || new Date(parsed).toISOString() !== value) {
@@ -81589,6 +81607,52 @@ function inspectSkillSession(sessionId, options = {}) {
     loadedCount: receipt.loaded.length
   };
 }
+async function reconcileSkillSessionIfSafe(sessionId, profileId, options = {}) {
+  const snapshot2 = readSkillSessionSnapshotIfExists(sessionId, options);
+  if (!snapshot2)
+    return false;
+  const old = snapshot2.receipt;
+  if (old.profile.profileId !== profileId)
+    throw new SkillSelectionError("PROFILE_LOCK_MISMATCH", "The session is pinned to a different Skills profile.");
+  const now3 = (options.now ?? Date.now)();
+  const age = now3 - Date.parse(old.verifiedAt);
+  if (age >= 0 && age <= MAX_CACHED_PROFILE_AGE_MS)
+    return false;
+  if (age < 0)
+    throw new SkillSelectionError("SESSION_RECONCILIATION_REQUIRED", "The session receipt has a future timestamp; inspect it before changing its pin.");
+  const client2 = options.client ?? await createProfileClient();
+  const target = structuredClone(await client2.resolveProfile(profileId));
+  validateResolvedProfile(target, client2.authority);
+  if (target.profileId !== profileId || target.authority !== old.profile.authority || target.workspaceId !== old.profile.workspaceId) {
+    throw new SkillSelectionError("PROFILE_IDENTITY_MISMATCH", "The authenticated Skills profile does not match this session's profile, authority and workspace.");
+  }
+  const oldByKey = new Map(old.profile.selections.map((selection) => [selectionKey(selection), selection]));
+  const targetBySlug = new Map(target.selections.map((selection) => [selection.slug, selection]));
+  for (const key of old.loaded) {
+    const previous = oldByKey.get(key);
+    const current = targetBySlug.get(previous.slug);
+    if (!current || !isDeepStrictEqual8({ ...previous, profileRevision: target.profileRevision }, current)) {
+      throw new SkillSelectionError("SESSION_RECONCILIATION_REQUIRED", "A loaded Skills selection was removed or changed; review skills sessions reconcile before changing this session's pin.");
+    }
+  }
+  const replacement = {
+    ...old,
+    generation: nextSkillSessionGeneration(snapshot2.generation),
+    verifiedAt: new Date((options.now ?? Date.now)()).toISOString(),
+    profile: target,
+    loaded: [...old.loaded]
+  };
+  replaceSkillSession(skillSessionSnapshotBinding(snapshot2), replacement, {
+    schemaVersion: 1,
+    kind: "managed-hook-safe-reconciliation",
+    sessionId,
+    fromProfileRevision: old.profile.profileRevision,
+    toProfileRevision: target.profileRevision,
+    retainedLoadedCount: old.loaded.length,
+    retiredLoadedCount: 0
+  }, options);
+  return true;
+}
 async function reconcileSkillSession(input2, options = {}) {
   if (![input2.fromProfile, input2.fromRevision, input2.selectionProfile, input2.profileRevision].every((value) => typeof value === "string" && value.trim()) || !/^[a-f0-9]{64}$/.test(input2.receiptSha256)) {
     throw new SkillSelectionError("INVALID_SESSION_RECONCILIATION", "Name the exact old receipt SHA256, old profile/revision and intended target profile/revision.");
@@ -81707,7 +81771,7 @@ Review digest: ${result2.reviewDigest}`);
       reportContextError(error61, options.json);
     }
   });
-  sessions.command("reconcile <id>").requiredOption("--from-profile <id>", "Expected current session profile").requiredOption("--from-revision <revision>", "Expected current session profile revision").requiredOption("--receipt-sha256 <sha256>", "Expected exact current receipt bytes").requiredOption("--selection-profile <id>", "Intended target selection profile").requiredOption("--profile-revision <revision>", "Expected current API target revision").option("--apply", "Archive the old receipt and atomically apply the reviewed plan", false).option("--plan-digest <sha256>", "Exact reviewed plan digest; required with --apply").option("--plan-issued-at <timestamp>", "Exact reviewed plan issuedAt; required with --apply").option("--plan-expires-at <timestamp>", "Exact reviewed plan expiresAt; required with --apply").option("--json", "Return the plan or application receipt as JSON", false).description("Plan an intentional migration of one session pin; ordinary hooks never migrate pins").action(async (id, options) => {
+  sessions.command("reconcile <id>").requiredOption("--from-profile <id>", "Expected current session profile").requiredOption("--from-revision <revision>", "Expected current session profile revision").requiredOption("--receipt-sha256 <sha256>", "Expected exact current receipt bytes").requiredOption("--selection-profile <id>", "Intended target selection profile").requiredOption("--profile-revision <revision>", "Expected current API target revision").option("--apply", "Archive the old receipt and atomically apply the reviewed plan", false).option("--plan-digest <sha256>", "Exact reviewed plan digest; required with --apply").option("--plan-issued-at <timestamp>", "Exact reviewed plan issuedAt; required with --apply").option("--plan-expires-at <timestamp>", "Exact reviewed plan expiresAt; required with --apply").option("--json", "Return the plan or application receipt as JSON", false).description("Plan an intentional migration of one session pin when loaded selections changed").action(async (id, options) => {
     try {
       const result2 = await reconcileSkillSession({ ...options, sessionId: id });
       await writeCliOutput(options.json ? JSON.stringify(result2) : result2.applied ? `Reconciled ${JSON.stringify(id)} to ${result2.plan.target.profileId} at ${result2.plan.target.profileRevision}.
@@ -81729,18 +81793,27 @@ Preserved original receipt: ${result2.archivePath}` : `Planned one session recon
       reportContextError(error61, options.json);
     }
   });
-  parent.command("context [prompt]").description("Select bounded, versioned skill context for this prompt without running skills").option("--stdin", "Read native hook JSON or a prompt from stdin", false).option("--selection-profile <id>", "Selection profile (separate from the credential --profile)").option("--cached", "Use only an explicitly selected verified cache, at most 24 hours old", false).option("--session <id>", "Keep the same skill versions across this session").option("--restore", "Re-emit loaded session context after compaction or resume", false).option("--max-chars <count>", "Maximum injected characters", "8000").option("--max-skills <count>", "Maximum loaded skills", "3").option("--json", "Return context and selection receipts as JSON", false).action(async (prompt, options) => {
+  parent.command("context [prompt]").description("Select bounded, versioned skill context for this prompt without running skills").option("--stdin", "Read native hook JSON or a prompt from stdin", false).option("--selection-profile <id>", "Selection profile (separate from the credential --profile)").option("--cached", "Use only an explicitly selected verified cache, at most 24 hours old", false).option("--auto-reconcile-safe", "For managed hooks, archive and renew an expired session only when all loaded selections are unchanged", false).option("--session <id>", "Keep the same skill versions across this session").option("--restore", "Re-emit loaded session context after compaction or resume", false).option("--max-chars <count>", "Maximum injected characters", "8000").option("--max-skills <count>", "Maximum loaded skills", "3").option("--json", "Return context and selection receipts as JSON", false).action(async (prompt, options) => {
     try {
+      if (options.autoReconcileSafe && !options.cached)
+        throw new SkillSelectionError("INVALID_CONTEXT_INPUT", "--auto-reconcile-safe requires --cached.");
       const input2 = options.stdin ? parseSkillContextInput(await readContextStdin()) : { prompt: prompt ?? "" };
       input2.profileId = selectedProfileId(options.selectionProfile ?? input2.profileId);
       input2.cwd ??= process.cwd();
       input2.sessionId = options.session ?? input2.sessionId;
       input2.restore ||= options.restore;
-      const result2 = await buildSkillContext(input2, {
-        ...contextResolverOptions(options),
-        maxChars: Number(options.maxChars),
-        maxSkills: Number(options.maxSkills)
-      });
+      const resolverOptions = { ...contextResolverOptions(options), maxChars: Number(options.maxChars), maxSkills: Number(options.maxSkills) };
+      let result2;
+      try {
+        result2 = await buildSkillContext(input2, resolverOptions);
+      } catch (error61) {
+        if (!options.cached || !options.autoReconcileSafe || !(error61 instanceof SkillSelectionError) || error61.code !== "CACHED_PROFILE_EXPIRED" || !input2.sessionId)
+          throw error61;
+        const sessionId = input2.agentId ? `${input2.sessionId}:${input2.agentId}` : input2.sessionId;
+        if (!await reconcileSkillSessionIfSafe(sessionId, input2.profileId, resolverOptions))
+          throw error61;
+        result2 = await buildSkillContext(input2, resolverOptions);
+      }
       await writeCliOutput(options.json ? JSON.stringify(result2) : result2.context);
     } catch (error61) {
       reportContextError(error61, options.json);
@@ -86158,7 +86231,7 @@ var init_execution_grants = __esm(() => {
 });
 
 // src/lib/execution-grant-client.ts
-import { isDeepStrictEqual as isDeepStrictEqual8 } from "util";
+import { isDeepStrictEqual as isDeepStrictEqual9 } from "util";
 function id(value) {
   if (!grantIdentifier(value))
     throw new Error("Invalid execution grant profile or revision identifier.");
@@ -86210,7 +86283,7 @@ async function saveExecutionGrantPolicy(profileId, grants, revision) {
     headers: revision === undefined ? { "If-None-Match": "*" } : { "If-Match": `"${revision}"` },
     body: JSON.stringify({ grants: snapshot2 })
   }));
-  if (policy.profileId !== profileId || policy.previousRevision !== (revision ?? null) || !isDeepStrictEqual8(policy.grants, snapshot2)) {
+  if (policy.profileId !== profileId || policy.previousRevision !== (revision ?? null) || !isDeepStrictEqual9(policy.grants, snapshot2)) {
     throw new Error("The API did not preserve the reviewed execution grant policy; read it before retrying.");
   }
   return policy;
@@ -86221,7 +86294,7 @@ async function resolveExecutionGrant(input2) {
   if (!grantRecord(value) || Object.keys(value).length !== 3 || !grantIdentifier(value.policyRevision) || !grantIdentifier(value.grantId) || !grantRecord(value.bindings)) {
     throw new SkillSelectionError("INVALID_EXECUTION_GRANT", "The Skills API returned an invalid execution grant.");
   }
-  if (!isDeepStrictEqual8(value.bindings.selection, snapshot2.selection) || !isDeepStrictEqual8(value.bindings.consumer, snapshot2.consumer)) {
+  if (!isDeepStrictEqual9(value.bindings.selection, snapshot2.selection) || !isDeepStrictEqual9(value.bindings.consumer, snapshot2.consumer)) {
     throw new SkillSelectionError("EXECUTION_GRANT_SCOPE_MISMATCH", "The Skills API returned a grant for a different selection or consumer.");
   }
   return value;
@@ -109440,7 +109513,7 @@ var init_create_sync_config = __esm(() => {
 });
 
 // src/lib/codex-native-config.ts
-import { isDeepStrictEqual as isDeepStrictEqual9 } from "util";
+import { isDeepStrictEqual as isDeepStrictEqual10 } from "util";
 function isRecord7(value) {
   if (!value || typeof value !== "object")
     return false;
@@ -109462,7 +109535,7 @@ function decimalIdentity(text4) {
   return `${match[1]}${coefficient}e${exponent}`;
 }
 function codexNativeConfigEqual(native, expected) {
-  if (isDeepStrictEqual9(native, expected))
+  if (isDeepStrictEqual10(native, expected))
     return true;
   if (typeof expected === "number") {
     if (!Number.isFinite(expected) || !isRecord7(native))
@@ -109628,7 +109701,7 @@ var init_codex_hook_rpc = __esm(() => {
 // src/lib/codex-hook-trust-identity.ts
 import { realpathSync as realpathSync13 } from "fs";
 import { dirname as dirname31, isAbsolute as isAbsolute25, join as join57 } from "path";
-import { isDeepStrictEqual as isDeepStrictEqual10 } from "util";
+import { isDeepStrictEqual as isDeepStrictEqual11 } from "util";
 function inspectRecordedSkillsCli(command, expected) {
   need4(isAbsolute25(command) && !command.includes("\x00"), "RECONCILE_RECORDED_COMMAND_REQUIRED");
   const resolved = realpathSync13(command);
@@ -109638,7 +109711,7 @@ function inspectRecordedSkillsCli(command, expected) {
   need4(pkg.name === "@hasna/skills" && /^\d+\.\d+\.\d+$/.test(pkg.version) && pkg.bin?.skills === "bin/index.js" && resolved === join57(dirname31(manifest.file), "bin/index.js"), "SKILLS_PACKAGE_MISMATCH");
   need4((cli.stat.mode & 0o100n) !== 0n, "SKILLS_COMMAND_NOT_EXECUTABLE");
   const receipt = { path: resolved, version: pkg.version, sha256: cli.sha256, manifestSha256: manifest.sha256 };
-  need4(isDeepStrictEqual10(receipt, expected), "RECONCILE_SKILLS_BINDING_CHANGED");
+  need4(isDeepStrictEqual11(receipt, expected), "RECONCILE_SKILLS_BINDING_CHANGED");
   return { receipt, recheck() {
     need4(realpathSync13(command) === resolved, "SKILLS_COMMAND_CHANGED");
     unchanged2(cli);
@@ -109674,19 +109747,19 @@ var init_codex_hook_trust_identity = __esm(() => {
 });
 
 // src/lib/codex-hook-policy-recovery.ts
-import { isDeepStrictEqual as isDeepStrictEqual11 } from "util";
+import { isDeepStrictEqual as isDeepStrictEqual12 } from "util";
 function reviewedClaudeDiscoveryChange(beforeText, currentText, options) {
   need4(typeof options.reason === "string" && options.reason.trim().length > 0 && options.reason.length <= 512 && !/[\x00-\x1f\x7f]/.test(options.reason), "RECONCILE_RECOVERY_REASON_REQUIRED");
   need4(options.reviewedPlanDigest === undefined || /^[a-f0-9]{64}$/.test(options.reviewedPlanDigest), "RECONCILE_RECOVERY_PLAN_CHANGED");
   const before2 = parseManagedSkillPolicy(beforeText), current = parseManagedSkillPolicy(currentText);
   const oldDiscovery = before2.bridge?.discovery?.claude, newDiscovery = current.bridge?.discovery?.claude;
   need4(oldDiscovery?.agent === "claude" && newDiscovery?.agent === "claude" && oldDiscovery.method === "reviewed" && newDiscovery.method === "reviewed", "RECONCILE_POLICY_CHANGED");
-  const changes = ["roots", "sources"].filter((key) => !isDeepStrictEqual11(oldDiscovery[key], newDiscovery[key])).map((key) => ({ path: `bridge.discovery.claude.${key}`, before: oldDiscovery[key], after: newDiscovery[key] }));
+  const changes = ["roots", "sources"].filter((key) => !isDeepStrictEqual12(oldDiscovery[key], newDiscovery[key])).map((key) => ({ path: `bridge.discovery.claude.${key}`, before: oldDiscovery[key], after: newDiscovery[key] }));
   need4(changes.length > 0, "RECONCILE_POLICY_CHANGED");
   const compared = structuredClone(current);
   compared.bridge.discovery.claude.roots = oldDiscovery.roots;
   compared.bridge.discovery.claude.sources = oldDiscovery.sources;
-  need4(isDeepStrictEqual11(before2, compared), "RECONCILE_POLICY_CHANGED");
+  need4(isDeepStrictEqual12(before2, compared), "RECONCILE_POLICY_CHANGED");
   verifyAgentDiscovery(newDiscovery);
   return { reason: options.reason, changes };
 }
@@ -109702,7 +109775,7 @@ import { createHash as createHash28, randomUUID as randomUUID10 } from "crypto";
 import { execFileSync } from "child_process";
 import { dirname as dirname32, isAbsolute as isAbsolute26, join as join58, resolve as resolve23 } from "path";
 import { homedir as homedir12 } from "os";
-import { isDeepStrictEqual as isDeepStrictEqual12 } from "util";
+import { isDeepStrictEqual as isDeepStrictEqual13 } from "util";
 function verifyReleaseArtifact(proof, skillsCli) {
   need4(isAbsolute26(proof.packageTarPath) && !proof.packageTarPath.includes("\x00"), "RECONCILE_RELEASE_PROVENANCE_PATH");
   const tarPath = realpathSync14(proof.packageTarPath);
@@ -109744,7 +109817,7 @@ async function reconcileCodexNativeHooks(options, connect = connectCodexHookRpc)
     const configSha256 = intent.configSha256 ?? configBefore.sha256, configVersion = intent.configVersion ?? intent.expectedVersion;
     const digestInput = { version: 1, home: intent.home ?? home, configPath: intent.configPath, ...intent.nativeConfigPath !== undefined ? { nativeConfigPath: intent.nativeConfigPath } : {}, configSha256, configVersion, policySha256: intent.policySha256, hooksSha256: intent.hooksSha256, skillsCli: intent.skillsCli, nativeVersion: intent.nativeVersion, declarations, admitted };
     need4(makePlanDigest(digestInput) === intent.planDigest, "RECONCILE_PLAN_CHANGED");
-    need4(isDeepStrictEqual12(intent.hooks, admitted.filter((hook) => !hook.enabled || hook.trustStatus !== "trusted")), "RECONCILE_INTENT_HOOKS_CHANGED");
+    need4(isDeepStrictEqual13(intent.hooks, admitted.filter((hook) => !hook.enabled || hook.trustStatus !== "trusted")), "RECONCILE_INTENT_HOOKS_CHANGED");
     need4(configBefore.sha256 === (intent.beforeSha256 ?? intent.configSha256) && hooksBefore.sha256 === intent.hooksSha256 && policyBefore.sha256 === intent.policySha256, "RECONCILE_JOURNAL_CHANGED");
     const policyCurrent = snapshot(join58(dataDir3, "agent-policy.json"), true);
     const { claudeDiscoveryRecovery: claudeRecovery, nativeHookAdditionsRecovery: additionsRecovery } = options;
@@ -109757,7 +109830,7 @@ async function reconcileCodexNativeHooks(options, connect = connectCodexHookRpc)
     if (policyCurrent.sha256 !== policyBefore.sha256 && !claudeRecovery) {
       need4(options.supersedeBinding === true, "RECONCILE_POLICY_CHANGED");
       const oldPolicy = JSON.parse(policyBefore.text), currentPolicy = JSON.parse(policyCurrent.text);
-      need4(isDeepStrictEqual12(withoutCodexCommand(oldPolicy), withoutCodexCommand(currentPolicy)), "RECONCILE_POLICY_CHANGED");
+      need4(isDeepStrictEqual13(withoutCodexCommand(oldPolicy), withoutCodexCommand(currentPolicy)), "RECONCILE_POLICY_CHANGED");
       supersededBinding = true;
     }
     if (supersededBinding || recovery) {
@@ -109793,7 +109866,7 @@ async function reconcileCodexNativeHooks(options, connect = connectCodexHookRpc)
         need4(state?.enabled === true && typeof state.trusted_hash === "string" && /^sha256:[a-f0-9]{64}$/.test(state.trusted_hash), "RECONCILE_CONFIG_DRIFT");
       }
     } else
-      need4(isDeepStrictEqual12(expectedConfig, current), "RECONCILE_CONFIG_DRIFT");
+      need4(isDeepStrictEqual13(expectedConfig, current), "RECONCILE_CONFIG_DRIFT");
     const configDiscoveryRecovery = recovery && binding.discovery?.codex ? createCodexHookDiscoveryRecovery(binding.discovery.codex, configBefore, currentConfig, intent.hooks, additions?.trustProof) : undefined;
     assertManagedAgentBridge("codex", { home, dataDir: dataDir3, projectDir: home, codexDiscoveryRecovery: configDiscoveryRecovery });
     const recoveryCli = recovery ? bindSkillsCli("skills", options.reviewedSkillsCli) : undefined;
@@ -109802,14 +109875,14 @@ async function reconcileCodexNativeHooks(options, connect = connectCodexHookRpc)
     const skillsCli = recovery ? inspectRecordedSkillsCli(binding.commands.codex, intent.skillsCli) : bindSkillsCli(binding.commands.codex, options.reviewedSkillsCli);
     if (supersededBinding)
       verifyReleaseArtifact(options.releaseProof, skillsCli);
-    const skillsBindingChanged = !isDeepStrictEqual12(skillsCli.receipt, intent.skillsCli);
+    const skillsBindingChanged = !isDeepStrictEqual13(skillsCli.receipt, intent.skillsCli);
     need4(!skillsBindingChanged || supersededBinding, "RECONCILE_SKILLS_BINDING_CHANGED");
     if (!additions && hooksCurrent.sha256 !== intent.hooksSha256 && hooksCurrent.sha256 !== hooksBefore.sha256) {
       need4(supersededBinding, "RECONCILE_HOOKS_CHANGED");
       const currentDeclarations = JSON.parse(hooksCurrent.text).hooks;
       for (const [event, [nativeEvent]] of Object.entries(eventNames)) {
         const command = renderAgentHookCommand(binding.commands.codex, "codex", binding.profiles.codex, event);
-        need4(isDeepStrictEqual12(currentDeclarations?.[event], [{ hooks: [{ type: "command", command, timeout: 15 }] }]), "RECONCILE_BINDING_HOOK_CHANGED");
+        need4(isDeepStrictEqual13(currentDeclarations?.[event], [{ hooks: [{ type: "command", command, timeout: 15 }] }]), "RECONCILE_BINDING_HOOK_CHANGED");
       }
     }
     rpc = await connect({ command: options.codexCommand ?? "codex", home, codexHome });
@@ -109832,9 +109905,9 @@ async function reconcileCodexNativeHooks(options, connect = connectCodexHookRpc)
           delete identity4.command;
         return identity4;
       };
-      need4(isDeepStrictEqual12(stable(actual), stable(expected)), "RECONCILE_NATIVE_IDENTITY_CHANGED");
+      need4(isDeepStrictEqual13(stable(actual), stable(expected)), "RECONCILE_NATIVE_IDENTITY_CHANGED");
       if (!plannedKeys.has(expected.key))
-        need4(isDeepStrictEqual12(actual, expected), "RECONCILE_UNRELATED_HOOK_CHANGED");
+        need4(isDeepStrictEqual13(actual, expected), "RECONCILE_UNRELATED_HOOK_CHANGED");
     }
     for (const wanted of intent.hooks) {
       const matches2 = nativeHooks.filter((h2) => h2.key === wanted.key || h2.key === wanted.key.replace(join58(home, ".codex/hooks.json"), hooksPath));
@@ -109853,7 +109926,7 @@ async function reconcileCodexNativeHooks(options, connect = connectCodexHookRpc)
     const layers = config2?.layers?.filter((layer) => layer.name?.type === "user" && layer.name.file === nativeConfigPath && !layer.name.profile);
     need4(layers?.length === 1 && !layers[0].disabledReason && codexNativeConfigEqual(layers[0].config, current), "RECONCILE_NATIVE_CONFIG_MISMATCH");
     const finalDiscovery = await rpc.request("hooks/list", { cwds: [home] });
-    need4(Array.isArray(finalDiscovery?.data) && finalDiscovery.data.length === 1 && finalDiscovery.data[0].cwd === home && !finalDiscovery.data[0].errors?.length && !finalDiscovery.data[0].warnings?.length && (!recordedNativeHooks || isDeepStrictEqual12(finalDiscovery.data[0].hooks.map(safeNativeHook), nativeHooks.map(safeNativeHook))), "RECONCILE_NATIVE_STATE_CHANGED");
+    need4(Array.isArray(finalDiscovery?.data) && finalDiscovery.data.length === 1 && finalDiscovery.data[0].cwd === home && !finalDiscovery.data[0].errors?.length && !finalDiscovery.data[0].warnings?.length && (!recordedNativeHooks || isDeepStrictEqual13(finalDiscovery.data[0].hooks.map(safeNativeHook), nativeHooks.map(safeNativeHook))), "RECONCILE_NATIVE_STATE_CHANGED");
     const finalConfig = await rpc.request("config/read", { includeLayers: true, cwd: home });
     const finalLayers = finalConfig?.layers?.filter((layer) => layer.name?.type === "user" && layer.name.file === nativeConfigPath && !layer.name.profile);
     need4(finalLayers?.length === 1 && !finalLayers[0].disabledReason && codexNativeConfigEqual(finalLayers[0].config, current), "RECONCILE_NATIVE_CONFIG_CHANGED");
@@ -109914,7 +109987,7 @@ async function enrollCodexNativeHooks(options = {}, connect = connectCodexHookRp
       const groups = declarations[event];
       need4(Array.isArray(groups), "DECLARATION_CHANGED");
       const matches2 = groups.flatMap((group, gi) => (group.hooks ?? []).flatMap((entry, hi) => entry.command === command ? [{ group, entry, gi, hi }] : []));
-      need4(matches2.length === 1 && isDeepStrictEqual12(matches2[0].group, { hooks: [{ type: "command", command, timeout: 15 }] }), "DECLARATION_CHANGED");
+      need4(matches2.length === 1 && isDeepStrictEqual13(matches2[0].group, { hooks: [{ type: "command", command, timeout: 15 }] }), "DECLARATION_CHANGED");
       expected.push({ event: nativeEvent, key: `${join58(home, ".codex/hooks.json")}:${label}:${matches2[0].gi}:${matches2[0].hi}`, command });
     }
     codexTrustTextWitness(configFile.text, expected.map((h) => h.key));
@@ -109980,7 +110053,7 @@ async function enrollCodexNativeHooks(options = {}, connect = connectCodexHookRp
     save(join58(journal, "hooks.before.json"), hooksFile.bytes);
     save(join58(journal, "policy.before.json"), policyFile.bytes);
     save(join58(journal, "intent.json"), json2({ ...digestInput, planDigest, hooks: planned, nativeHooks: discovered.map(safeNativeHook) }));
-    need4(isDeepStrictEqual12(admit(await list2()), admitted), "NATIVE_DISCOVERY_CHANGED");
+    need4(isDeepStrictEqual13(admit(await list2()), admitted), "NATIVE_DISCOVERY_CHANGED");
     checkInputs();
     let result2;
     try {
@@ -109994,7 +110067,7 @@ async function enrollCodexNativeHooks(options = {}, connect = connectCodexHookRp
     expectedConfig.hooks.state ??= {};
     for (const h of planned)
       expectedConfig.hooks.state[h.key] = { ...expectedConfig.hooks.state[h.key], enabled: true, trusted_hash: h.currentHash };
-    need4(isDeepStrictEqual12(structure3(after2.text), expectedConfig) && codexTrustTextWitness(after2.text, keys3) === preservationText, "PRESERVATION_FAILED");
+    need4(isDeepStrictEqual13(structure3(after2.text), expectedConfig) && codexTrustTextWitness(after2.text, keys3) === preservationText, "PRESERVATION_FAILED");
     const savedConfig = snapshot(join58(journal, "config.before.toml"), true);
     need4(savedConfig.sha256 === configFile.sha256, "JOURNAL_CHANGED");
     const discoveryTransition = binding.discovery?.codex ? createCodexHookDiscoveryRecovery(binding.discovery.codex, savedConfig, after2, planned) : undefined;
@@ -110002,8 +110075,8 @@ async function enrollCodexNativeHooks(options = {}, connect = connectCodexHookRp
     unchanged2(hooksFile);
     assertManagedAgentBridge("codex", { home, dataDir: dataDir3, projectDir: home, codexDiscoveryRecovery: discoveryTransition });
     const current = await list2(), confirmed = admit(current);
-    need4(confirmed.every((h) => h.enabled && h.trustStatus === "trusted") && isDeepStrictEqual12(confirmed.map((h) => [h.key, h.currentHash]), admitted.map((h) => [h.key, h.currentHash])), "NATIVE_NOT_ELIGIBLE");
-    need4(isDeepStrictEqual12(current.filter((h) => !keys3.includes(h.key)), discovered.filter((h) => !keys3.includes(h.key))), "UNRELATED_HOOK_CHANGED");
+    need4(confirmed.every((h) => h.enabled && h.trustStatus === "trusted") && isDeepStrictEqual13(confirmed.map((h) => [h.key, h.currentHash]), admitted.map((h) => [h.key, h.currentHash])), "NATIVE_NOT_ELIGIBLE");
+    need4(isDeepStrictEqual13(current.filter((h) => !keys3.includes(h.key)), discovered.filter((h) => !keys3.includes(h.key))), "UNRELATED_HOOK_CHANGED");
     unchanged2(after2);
     unchanged2(savedConfig);
     unchanged2(hooksFile);
@@ -110070,6 +110143,9 @@ function hookFailureReason(error61, profileId) {
   if (code2 === "PROFILE_LOCK_MISMATCH") {
     return `${prefix} This session or project is pinned to a different profile. Inspect the session with skills sessions show <session-id> --json; review skills sessions reconcile for an intentional session change, or explicit project sync for a project change. Sync alone does not change that pin.`;
   }
+  if (code2 === "SESSION_RECONCILIATION_REQUIRED") {
+    return `${prefix} A loaded skill changed or was removed. Inspect this session with skills sessions show <session-id> --json, then review skills sessions reconcile for an intentional change. Sync alone does not change this pin.`;
+  }
   if (code2.startsWith("SESSION_")) {
     return `${prefix} Inspect the session with skills sessions show <session-id> --json and review its parent or concurrent writer before retrying. Do not remove or rewrite its receipt to bypass this refusal.`;
   }
@@ -110112,6 +110188,7 @@ var init_hook_diagnostics = __esm(() => {
     "SESSION_GENERATION_EXHAUSTED",
     "SESSION_PARENT_CHANGED",
     "SESSION_RECEIPT_CHANGED",
+    "SESSION_RECONCILIATION_REQUIRED",
     "SESSION_RECONCILIATION_INCOMPLETE",
     "SESSION_WRITE_LOCKED",
     "SESSION_WRITE_LOCK_CHANGED",
@@ -110156,7 +110233,7 @@ async function contextForHook(input3, profileId, cached2, deadline) {
     throw new HookDiagnosticError("SKILLS_HOOK_TIMEOUT", "context");
   const args2 = [process.execPath, process.argv[1], "context", "--stdin", "--json", "--selection-profile", profileId];
   if (cached2)
-    args2.push("--cached");
+    args2.push("--cached", "--auto-reconcile-safe");
   const child = Bun.spawn(args2, { stdin: new Blob([JSON.stringify(input3)]), stdout: "pipe", stderr: "pipe", env: { ...process.env, NO_COLOR: "1" } });
   let timedOut = false;
   const timer = setTimeout(() => {
@@ -110363,13 +110440,18 @@ function registerAgentIntegration(parent) {
     }
   });
   const migrate = parent.command("migrate").description("Preserve and retire native agent skill copies");
-  migrate.command("native").option("--project <directory>", "Also inventory a project and its ancestors (the current directory and its ancestors are always included)").option("--include-unmanaged", "Archive user-authored skills as well as Skills-managed copies", false).option("--include-vendor", "Retire vendor SKILL.md discovery files while preserving plugin scripts and assets", false).option("--target-manifest <file>", "Reviewed exact native migration target manifest").option("--discovery-inputs <file>", "Advanced reviewed active plugin roots and source hashes").option("--allow-root-aliases", "Allow home .claude/.codex aliases to existing directories within this home", false).option("--apply", "Move selected skills to private archives outside agent discovery roots", false).option("--json", "Output inventory and archive receipt as JSON", false).description("Inventory native skill copies; preserve complete directories before retiring them").action(async (options) => {
+  migrate.command("native").option("--agent <agent>", "Limit inventory and migration to one maintained agent").option("--project <directory>", "Also inventory a project and its ancestors (the current directory and its ancestors are always included)").option("--include-unmanaged", "Archive user-authored skills as well as Skills-managed copies", false).option("--include-vendor", "Retire vendor SKILL.md discovery files while preserving plugin scripts and assets", false).option("--reviewed-cache-alias <path>", "Exact skill-containing vendor cache alias reviewed for migration; runtime hooks still refuse it").option("--target-manifest <file>", "Reviewed exact native migration target manifest").option("--discovery-inputs <file>", "Advanced reviewed active plugin roots and source hashes").option("--allow-root-aliases", "Allow home .claude/.codex aliases to existing directories within this home", false).option("--apply", "Move selected skills to private archives outside agent discovery roots", false).option("--json", "Output inventory and archive receipt as JSON", false).description("Inventory native skill copies; preserve complete directories before retiring them").action(async (options) => {
     try {
+      if (options.agent && !INTEGRATION_AGENTS.includes(options.agent))
+        throw new Error(`Unsupported migration agent: ${options.agent}`);
       const discoveryInputs = options.discoveryInputs ? JSON.parse(readFileSync40(options.discoveryInputs, "utf8")) : undefined;
       if (options.targetManifest && (options.includeUnmanaged || options.includeVendor))
         throw new Error("--target-manifest cannot be combined with broad native migration selectors");
       const targetManifest = options.targetManifest ? readNativeMigrationTargetManifest(options.targetManifest) : undefined;
-      const inventory = inventoryNativeSkills(undefined, { projectDirs: [process.cwd(), ...options.project ? [options.project] : []], includeVendor: options.includeVendor, configured: options.includeVendor, discoveryInputs, allowRootAliases: options.allowRootAliases });
+      if (options.apply && options.reviewedCacheAlias && !targetManifest)
+        throw new Error("Applying a reviewed cache alias requires an exact --target-manifest");
+      const includeVendor = options.includeVendor || Boolean(targetManifest?.targets.some((target) => target.vendor));
+      const inventory = inventoryNativeSkills(undefined, { projectDirs: [process.cwd(), ...options.project ? [options.project] : []], agents: options.agent ? [options.agent] : undefined, includeVendor, configured: includeVendor, discoveryInputs, allowRootAliases: options.allowRootAliases, reviewedCacheAlias: options.reviewedCacheAlias });
       if (targetManifest)
         selectNativeMigrationTargets(inventory, targetManifest);
       const result2 = options.apply ? archiveNativeSkills(inventory, { includeUnmanaged: options.includeUnmanaged, includeVendor: options.includeVendor, allowRootAliases: options.allowRootAliases, targetManifest }) : { entries: [], ...targetManifest ? { targetManifest: { schema: targetManifest.schema, digest: targetManifest.digest, targetCount: targetManifest.targets.length } } : {} };

package/bin/mcp.js

@@ -20019,7 +20019,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.10.2",
+    version: "0.10.4",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {

package/bin/migrate.js

@@ -7,7 +7,7 @@ import { join as join5 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.2",
+  version: "0.10.4",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/server.js

@@ -24122,7 +24122,7 @@ var init_dist_es9 = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.2",
+  version: "0.10.4",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/worker.js

@@ -24125,7 +24125,7 @@ import { randomUUID as randomUUID6 } from "crypto";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.2",
+  version: "0.10.4",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/dist/cli/commands/context.d.ts

@@ -5,6 +5,7 @@ export declare function selectedProfileId(explicit?: string): string;
 export interface ContextCommandOptions {
     selectionProfile?: string;
     cached?: boolean;
+    autoReconcileSafe?: boolean;
     json?: boolean;
     stdin?: boolean;
     session?: string;

package/dist/index.js

@@ -9611,7 +9611,7 @@ import { isAbsolute as isAbsolute11, join as join23, resolve as resolve11 } from
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.2",
+  version: "0.10.4",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -13309,8 +13309,8 @@ function selectNativeMigrationTargets(inventory, manifest) {
     if (matches.length !== 1)
       throw new Error(`Native migration target was not found exactly once: ${target.agent} ${target.projectRoot}/${target.path}`);
     const entry = matches[0];
-    if (entry.bridge || entry.system || entry.vendor)
-      throw new Error(`Native migration target is protected or vendor-owned: ${entry.path}`);
+    if (entry.bridge || entry.system || entry.vendor !== (target.vendor === true))
+      throw new Error(`Native migration target is protected or vendor classification changed: ${entry.path}`);
     if (entry.hash !== target.treeSha256 || treeHash(entry.path) !== target.treeSha256)
       throw new Error(`Native migration target changed after review: ${entry.path}`);
     selected.push(entry);
@@ -13333,6 +13333,8 @@ function projectAncestorDirectories(projects) {
   return [...directories];
 }
 function inventoryNativeSkills(home = homedir2(), options = {}) {
+  if (options.reviewedCacheAlias !== undefined && (!options.includeVendor || !isAbsolute9(options.reviewedCacheAlias) || resolve9(options.reviewedCacheAlias) !== options.reviewedCacheAlias))
+    throw new Error("A reviewed cache alias requires vendor inventory and an exact absolute path");
   const aliases = rootAliases(home, options.allowRootAliases);
   const selectedAgents = options.agents ? new Set(options.agents) : undefined;
   const includesAgent = (agent) => !selectedAgents || selectedAgents.has(agent);
@@ -13353,14 +13355,22 @@ function inventoryNativeSkills(home = homedir2(), options = {}) {
     if (discoveryPathBytes > 4 * 1024 * 1024)
       throw new Error("Native skill discovery metadata limit exceeded");
   }
-  function emptySiblingCacheAlias(path, parent) {
+  let reviewedCacheAliasFound = false;
+  function verifiedSiblingCacheAlias(path, parent) {
     const link = readlinkSync3(path), target = resolve9(parent, link);
     if (dirname10(target) !== parent || (isAbsolute9(link) ? link !== target : dirname10(link) !== "."))
       return false;
     if (!lstatSync14(target, { throwIfNoEntry: false })?.isDirectory())
       return false;
     const scan = cacheScans.get(target);
-    return Boolean(scan?.complete && !scan.hasSkills && scan.entries <= maxAliasProofEntries);
+    if (!scan?.complete || scan.entries > maxAliasProofEntries)
+      return false;
+    if (scan.hasSkills) {
+      if (path !== options.reviewedCacheAlias)
+        return false;
+      reviewedCacheAliasFound = true;
+    }
+    return true;
   }
   function visit2(agent, path, vendor = false, depth = 0, pluginCache = false, admitted = false) {
     if (!admitted)
@@ -13417,7 +13427,7 @@ function inventoryNativeSkills(home = homedir2(), options = {}) {
       const child = join16(path, name);
       if (isVendor && lstatSync14(child, { throwIfNoEntry: false })?.isSymbolicLink()) {
         const target = statSync7(child, { throwIfNoEntry: false });
-        if (target?.isFile() || pluginCache && target?.isDirectory() && emptySiblingCacheAlias(child, path)) {
+        if (target?.isFile() || pluginCache && target?.isDirectory() && verifiedSiblingCacheAlias(child, path)) {
           scan.entries++;
           continue;
         }
@@ -13451,6 +13461,8 @@ function inventoryNativeSkills(home = homedir2(), options = {}) {
   for (const root of [...options.agentRoots ?? [], ...configured])
     if (includesAgent(root.agent))
       scanRoot(root.agent, canonicalAgentPath(root.path, aliases), true);
+  if (options.reviewedCacheAlias !== undefined && !reviewedCacheAliasFound)
+    throw new Error("Reviewed cache alias was not an inventoried skill-containing sibling alias");
   recheckRootAliases(aliases);
   return entries;
 }
@@ -14113,12 +14125,17 @@ function assertManagedAgentBridge(agent, options = {}) {
   const setting = (path) => (codexConfig.skills?.config ?? []).filter((entry) => typeof entry.path === "string" && [path, join16(path, "SKILL.md")].includes(canonicalAgentPath(entry.path, aliases)));
   if (agent === "codex" && [...setting(expected), ...(codexConfig.skills?.config ?? []).filter((entry) => typeof entry.name === "string" && entry.name.trim() === CLI_BRIDGE_NAME)].some((entry) => entry.enabled === false))
     throw new Error("NATIVE_SKILL_DRIFT: the Codex CLI bridge is disabled; run skills hook install");
-  const disabledBuiltin = (entry) => {
-    if (agent !== "codex" || !entry.vendor || !entry.path.startsWith(canonicalAgentPath(join16(home, ".codex", "skills", ".system"), aliases) + sep4))
+  const disabledVendorSkill = (entry) => {
+    if (agent !== "codex" || !entry.vendor)
       return false;
-    const matched = Array.isArray(binding.disabledBuiltins) && binding.disabledBuiltins.some((item) => item.path === entry.path && item.hash === entry.hash);
     const settings = setting(entry.path);
-    return matched && settings.length === 1 && settings[0]?.enabled === false;
+    if (settings.length !== 1 || settings[0]?.enabled !== false)
+      return false;
+    if (entry.path.startsWith(canonicalAgentPath(join16(home, ".codex", "plugins", "cache"), aliases) + sep4))
+      return true;
+    if (!entry.path.startsWith(canonicalAgentPath(join16(home, ".codex", "skills", ".system"), aliases) + sep4))
+      return false;
+    return Array.isArray(binding.disabledBuiltins) && binding.disabledBuiltins.some((item) => item.path === entry.path && item.hash === entry.hash);
   };
   if (!discovery || discovery.agent !== agent)
     throw new Error("NATIVE_SKILL_DRIFT: native discovery coverage is missing; run skills hook install");
@@ -14135,7 +14152,7 @@ function assertManagedAgentBridge(agent, options = {}) {
     throw new Error(`NATIVE_SKILL_DRIFT: ${error.message}`);
   }
   const inventory = inventoryNativeSkills(home, { includeVendor: true, guardHermes: agent === "hermes", agents: [agent], projectDirs: [...roots], agentRoots: discovery.roots.map((path) => ({ agent, path })), allowRootAliases: aliases.length > 0 });
-  const unexpected = inventory.filter((entry) => visible(entry) && !entry.bridge && !disabledBuiltin(entry));
+  const unexpected = inventory.filter((entry) => visible(entry) && !entry.bridge && !disabledVendorSkill(entry));
   if (unexpected.length) {
     const paths = unexpected.slice(0, 3).map((entry) => {
       const escaped = JSON.stringify(entry.path).replace(/[\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);

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

@@ -29,6 +29,7 @@ export interface NativeMigrationTarget {
     projectRoot: string;
     path: string;
     treeSha256: string;
+    vendor?: true;
 }
 export interface NativeMigrationTargetManifest {
     schema: "hasna.skills-native-migration-targets.v1";
@@ -84,6 +85,7 @@ export declare function inventoryNativeSkills(home?: string, options?: {
     configured?: boolean;
     discoveryInputs?: ReviewedDiscoveryInputs;
     allowRootAliases?: boolean;
+    reviewedCacheAlias?: string;
 }): NativeSkillEntry[];
 /** Planning is read-only; credentials and unrelated settings never appear in CLI output. */
 export declare function planAgentIntegration(options: {

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

@@ -30,7 +30,13 @@ export declare function inspectSkillSession(sessionId: string, options?: Selecti
     selectionCount: number;
     loadedCount: number;
 };
-/** Explicit opt-in only. Ordinary loads and hooks retain their immutable session pins. */
+/**
+ * Managed hooks may move an expired pin only when every skill already loaded
+ * by this session is still selected with exactly the same behavior and bytes.
+ * The old receipt is archived and replaced under its exact snapshot lock.
+ */
+export declare function reconcileSkillSessionIfSafe(sessionId: string, profileId: string, options?: SessionReconciliationOptions): Promise<boolean>;
+/** Explicit review for changed loaded selections or intentional profile migration. */
 export declare function reconcileSkillSession(input: SessionReconciliationInput, options?: SessionReconciliationOptions): Promise<{
     applied: false;
     plan: {

package/dist/sdk/index.js

@@ -32373,7 +32373,7 @@ var init_event_sink = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.2",
+  version: "0.10.4",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -41180,8 +41180,8 @@ function selectNativeMigrationTargets(inventory, manifest) {
     if (matches.length !== 1)
       throw new Error(`Native migration target was not found exactly once: ${target.agent} ${target.projectRoot}/${target.path}`);
     const entry = matches[0];
-    if (entry.bridge || entry.system || entry.vendor)
-      throw new Error(`Native migration target is protected or vendor-owned: ${entry.path}`);
+    if (entry.bridge || entry.system || entry.vendor !== (target.vendor === true))
+      throw new Error(`Native migration target is protected or vendor classification changed: ${entry.path}`);
     if (entry.hash !== target.treeSha256 || treeHash(entry.path) !== target.treeSha256)
       throw new Error(`Native migration target changed after review: ${entry.path}`);
     selected.push(entry);
@@ -41204,6 +41204,8 @@ function projectAncestorDirectories(projects) {
   return [...directories];
 }
 function inventoryNativeSkills(home = homedir3(), options = {}) {
+  if (options.reviewedCacheAlias !== undefined && (!options.includeVendor || !isAbsolute15(options.reviewedCacheAlias) || resolve14(options.reviewedCacheAlias) !== options.reviewedCacheAlias))
+    throw new Error("A reviewed cache alias requires vendor inventory and an exact absolute path");
   const aliases = rootAliases(home, options.allowRootAliases);
   const selectedAgents = options.agents ? new Set(options.agents) : undefined;
   const includesAgent = (agent) => !selectedAgents || selectedAgents.has(agent);
@@ -41224,14 +41226,22 @@ function inventoryNativeSkills(home = homedir3(), options = {}) {
     if (discoveryPathBytes > 4 * 1024 * 1024)
       throw new Error("Native skill discovery metadata limit exceeded");
   }
-  function emptySiblingCacheAlias(path, parent) {
+  let reviewedCacheAliasFound = false;
+  function verifiedSiblingCacheAlias(path, parent) {
     const link = readlinkSync3(path), target = resolve14(parent, link);
     if (dirname14(target) !== parent || (isAbsolute15(link) ? link !== target : dirname14(link) !== "."))
       return false;
     if (!lstatSync18(target, { throwIfNoEntry: false })?.isDirectory())
       return false;
     const scan = cacheScans.get(target);
-    return Boolean(scan?.complete && !scan.hasSkills && scan.entries <= maxAliasProofEntries);
+    if (!scan?.complete || scan.entries > maxAliasProofEntries)
+      return false;
+    if (scan.hasSkills) {
+      if (path !== options.reviewedCacheAlias)
+        return false;
+      reviewedCacheAliasFound = true;
+    }
+    return true;
   }
   function visit2(agent, path, vendor = false, depth = 0, pluginCache = false, admitted = false) {
     if (!admitted)
@@ -41288,7 +41298,7 @@ function inventoryNativeSkills(home = homedir3(), options = {}) {
       const child = join21(path, name);
       if (isVendor && lstatSync18(child, { throwIfNoEntry: false })?.isSymbolicLink()) {
         const target = statSync5(child, { throwIfNoEntry: false });
-        if (target?.isFile() || pluginCache && target?.isDirectory() && emptySiblingCacheAlias(child, path)) {
+        if (target?.isFile() || pluginCache && target?.isDirectory() && verifiedSiblingCacheAlias(child, path)) {
           scan.entries++;
           continue;
         }
@@ -41322,6 +41332,8 @@ function inventoryNativeSkills(home = homedir3(), options = {}) {
   for (const root2 of [...options.agentRoots ?? [], ...configured])
     if (includesAgent(root2.agent))
       scanRoot(root2.agent, canonicalAgentPath(root2.path, aliases), true);
+  if (options.reviewedCacheAlias !== undefined && !reviewedCacheAliasFound)
+    throw new Error("Reviewed cache alias was not an inventoried skill-containing sibling alias");
   recheckRootAliases(aliases);
   return entries;
 }
@@ -41984,12 +41996,17 @@ function assertManagedAgentBridge(agent, options = {}) {
   const setting = (path) => (codexConfig.skills?.config ?? []).filter((entry) => typeof entry.path === "string" && [path, join21(path, "SKILL.md")].includes(canonicalAgentPath(entry.path, aliases)));
   if (agent === "codex" && [...setting(expected), ...(codexConfig.skills?.config ?? []).filter((entry) => typeof entry.name === "string" && entry.name.trim() === CLI_BRIDGE_NAME)].some((entry) => entry.enabled === false))
     throw new Error("NATIVE_SKILL_DRIFT: the Codex CLI bridge is disabled; run skills hook install");
-  const disabledBuiltin = (entry) => {
-    if (agent !== "codex" || !entry.vendor || !entry.path.startsWith(canonicalAgentPath(join21(home, ".codex", "skills", ".system"), aliases) + sep4))
+  const disabledVendorSkill = (entry) => {
+    if (agent !== "codex" || !entry.vendor)
       return false;
-    const matched = Array.isArray(binding.disabledBuiltins) && binding.disabledBuiltins.some((item) => item.path === entry.path && item.hash === entry.hash);
     const settings = setting(entry.path);
-    return matched && settings.length === 1 && settings[0]?.enabled === false;
+    if (settings.length !== 1 || settings[0]?.enabled !== false)
+      return false;
+    if (entry.path.startsWith(canonicalAgentPath(join21(home, ".codex", "plugins", "cache"), aliases) + sep4))
+      return true;
+    if (!entry.path.startsWith(canonicalAgentPath(join21(home, ".codex", "skills", ".system"), aliases) + sep4))
+      return false;
+    return Array.isArray(binding.disabledBuiltins) && binding.disabledBuiltins.some((item) => item.path === entry.path && item.hash === entry.hash);
   };
   if (!discovery || discovery.agent !== agent)
     throw new Error("NATIVE_SKILL_DRIFT: native discovery coverage is missing; run skills hook install");
@@ -42006,7 +42023,7 @@ function assertManagedAgentBridge(agent, options = {}) {
     throw new Error(`NATIVE_SKILL_DRIFT: ${error.message}`);
   }
   const inventory = inventoryNativeSkills(home, { includeVendor: true, guardHermes: agent === "hermes", agents: [agent], projectDirs: [...roots], agentRoots: discovery.roots.map((path) => ({ agent, path })), allowRootAliases: aliases.length > 0 });
-  const unexpected = inventory.filter((entry) => visible(entry) && !entry.bridge && !disabledBuiltin(entry));
+  const unexpected = inventory.filter((entry) => visible(entry) && !entry.bridge && !disabledVendorSkill(entry));
   if (unexpected.length) {
     const paths = unexpected.slice(0, 3).map((entry) => {
       const escaped = JSON.stringify(entry.path).replace(/[\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {