@hasna/skills 0.10.71 → 0.10.73

package/dist/storage.js

@@ -53,13 +53,13 @@ import {
   mkdirSync as mkdirSync3,
   readFileSync as readFileSync3,
   readdirSync,
-  statSync,
+  statSync as statSync2,
   writeFileSync as writeFileSync3
 } from "fs";
 import { dirname as dirname2, join as join4, normalize, relative, sep } from "path";
 
 // src/lib/config.ts
-import { existsSync as existsSync2, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { closeSync, constants, existsSync as existsSync2, fstatSync, lstatSync, openSync, readFileSync, statSync, writeFileSync, mkdirSync } from "fs";
 import { join as join2, dirname } from "path";
 
 // src/lib/retired-settings.ts
@@ -195,7 +195,8 @@ function skillsDataRootForHome(home) {
 var ENUM_KEYS = {
   defaultAgent: ["claude", "codex", "gemini", "pi", "opencode", "all"],
   defaultScope: ["global", "project"],
-  format: ["compact", "json", "csv"]
+  format: ["compact", "json", "csv"],
+  sessionPinMigration: ["auto", "off"]
 };
 var STRING_KEYS = ["extensionsDir"];
 function validKeys() {
@@ -266,6 +267,9 @@ function saveConfig(key, value, scope = "project") {
   if (!validKeys().includes(key)) {
     throw new Error(`Unknown config key: ${key}. Valid keys: ${validKeys().join(", ")}`);
   }
+  if (key === "sessionPinMigration" && scope !== "global") {
+    throw new Error(`${key} is read only from the global configuration. Use: skills config set ${key} <auto|off> --global`);
+  }
   const normalized = normalizeConfigValue(key, value);
   if (normalized === undefined) {
     const allowed = allowedValues(key);
@@ -959,7 +963,7 @@ function walkFiles(dir) {
   const files = [];
   for (const entry of readdirSync(dir)) {
     const full = join4(dir, entry);
-    const stats = statSync(full);
+    const stats = statSync2(full);
     if (stats.isDirectory())
       files.push(...walkFiles(full));
     else

package/docs/plugin-admission.md

@@ -195,7 +195,7 @@ plugin dependency declarations refuse because this validator does not resolve
 or review unselected external plugins.
 The request may declare `functionHooksEnv: "1"`; without that declaration the
 environment document is preserved unchanged. For a measured Claude 2.1.276,
-2.1.278, 2.1.282, 2.1.287, 2.1.293, 2.1.296 or 2.1.299 user-scoped install,
+2.1.278, 2.1.282, 2.1.287, 2.1.293, 2.1.296, 2.1.299 or 2.1.300 user-scoped install,
 `candidate.settingsMarketplaceSource: "directory"`
 explicitly declares the native settings registration. Skills derives
 `extraKnownMarketplaces[candidate.marketplace].source` from the exact frozen
@@ -249,6 +249,49 @@ structural refusal checks do not prove hook behavior. Recheck all preimages and
 candidate closure immediately before the first native mutation. The validator
 does not claim native install atomicity or crash recovery.
 
+The reviewed discovery inputs must bind every current Claude settings and
+registration source: the user settings, both project settings files,
+`known_marketplaces.json` and `installed_plugins.json`. A project
+`.claude/settings.json` or `.claude/settings.local.json` that the reviewed
+sources omit is exempt only when no other expected source (the target settings
+or the user settings) shares its path, and it is either:
+
+- absent, with a null preimage; or
+- present, and all of the following hold:
+  - its current bytes match its preimage SHA-256; a mismatch refuses with
+    `<name> preimage changed`;
+  - those exact bytes are strict UTF-8 without a byte-order mark and parse as
+    one JSON object within the native JSON witness limits (no comments,
+    trailing commas, trailing content or duplicate keys at any depth);
+  - none of `enabledPlugins`, `extraKnownMarketplaces`,
+    `additionalMarketplaces` or `skillOverrides` is present at any value,
+    including `null`, `{}` and `[]`;
+  - every top-level key is on the exemption allowlist with its type:
+    `permissions` (an object), `outputStyle`, `model`, `theme` and
+    `effortLevel` (strings), and `verbose` and `spinnerTipsEnabled` (booleans);
+  - `permissions` holds only `allow`, `deny` and `ask` (arrays of strings) and
+    `defaultMode` (a string).
+
+Anything else keeps the file required, including `env` (Claude reads
+`CLAUDE_CODE_PLUGIN_DIRS` from it), `hooks`, `permissions.additionalDirectories`
+(Claude loads skills, commands and agents from those directories), `__proto__`
+and unknown keys. The allowlist names settings reviewed as not configuring
+plugins, marketplaces, skills, hooks, extra directories or the environment. It
+does not prove that Claude cannot discover anything from the file; a setting
+joins it only after that review.
+
+This covers the permissions-only `~/.claude/settings.local.json` that Claude
+writes when it saves a permission rule during a user-scope install, whose
+project path is the Claude home. A present unreviewed file that fails the parse,
+discovery-key or allowlist checks refuses and names the reason. Each exempt file
+is re-checked against its exact preimage (still absent, or the same bytes) after
+discovery and again before the result, so a change, creation or removal in
+between refuses. The live hooks' project check still runs on top; it refuses
+any of the four discovery keys (`additionalMarketplaces` included, because
+Claude 2.1.300 rewrites it into `extraKnownMarketplaces` on every settings read)
+and its other project skill and hook settings. The user settings and both
+registries are never exempt.
+
 The optional release manifest witness binds the complete supplied release.json
 file bytes, path and SHA-256 in the request/receipt. Harnesses remains
 responsible for verifying that its release options correspond to every
@@ -270,8 +313,12 @@ skills hook capture-claude-installer --request /absolute/request.json --json
 The UTF-8 request is a bounded JSON object with schema
 `skills.claude-installer-capture/v1`, the exact configured `commandPath`, one
 fixed `operation` (`settings`, `marketplace-registry`, `managed-plugin-registry`,
-`path-bytes`, `discovery-directories`, `plugin-manifest`, or `candidate`), and
-only that operation's documented inputs. The result uses
+`path-bytes`, `discovery-directories`, `plugin-manifest`, `candidate`, or
+`discovery-binding`), and only that operation's documented inputs. The
+`discovery-binding` operation verifies the stored Claude discovery binding as a
+whole, including witnesses retained under an absent retired plugin-cache
+version; its request and result contract is in the README section
+"Claude installer witness CLI". The result uses
 `skills.claude-installer-capture-result/v1` and contains a Skills producer
 receipt plus the selected existing witness result. Candidate manifests include
 their plugin name, canonical path, `hashMode: "claude-plugin-manifest-v1"`, and
@@ -330,9 +377,23 @@ What the software currently enforces is narrower:
   managed row's `installPath` to be `cache/<marketplace>/<plugin>/<version>`,
   checks every file in every retained cache version against the admission
   receipts without the review listing them, and binds unmanaged rows exactly.
+- Claude rewrites the 13-digit millisecond timestamp in
+  `.claude/plugins/cache/<marketplace>/<plugin>/<version>/.orphaned_at` when it
+  starts. Capturing that exact path with `captureDiscoveryByteSources` or
+  `captureDiscoveryPathSources` (including the installer `path-bytes`
+  operation) produces a `claude-plugin-orphaned-at-v1` witness, and a fresh
+  explicit review converts a plain byte or `path-bytes` witness of it to that
+  form. The witness binds the marker's presence or absence, not its bytes or
+  inode. Every capture and check still requires a regular, non-symlink file
+  owned by the current user, at most 32 bytes, matching `^[1-9][0-9]{12}$`.
+  The name stays in `directories` membership, so other added or removed names
+  are still detected. A marker at any other depth, any other name, and any
+  Skills-owned producer tree keep their exact byte witnesses. A stored review
+  that binds the marker's bytes keeps that meaning and needs one fresh review.
 - An entirely absent retired Claude version root exempts only its plain byte
   sources (`hashMode` omitted or `"bytes"`, with no `format`, `fields` or
-  `managedPlugins`). Such a source with a non-null `sha256` is also the only
+  `managedPlugins`) and a present `claude-plugin-orphaned-at-v1` marker. Such a
+  source with a non-null `sha256` is also the only
   thing that identifies the root, and the root qualifies only while it stays
   entirely absent and the reviewed settings and registry select a different,
   verified version. Every other source under that root is re-hashed as usual,

package/package.json

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