@hasna/skills 0.10.74 → 0.10.76

package/dist/lib/agent-codex-trust.d.ts

@@ -35,6 +35,8 @@ type Connect = typeof connectCodexHookRpc;
  * receipt for an already-effective operation so the ordinary apply guard can
  * stop refusing the same journal. */
 export declare function reconcileCodexNativeHooks(options: CodexNativeHookReconcileOptions, connect?: Connect): Promise<{
+    nativeAdmission?: "unavailable";
+    nativeAdmissionProbe?: import("./codex-corpus-write.js").CodexAdmissionProbe;
     recoveryPlan?: {
         reason?: string | undefined;
         changes?: {
@@ -119,6 +121,8 @@ export declare function reconcileCodexNativeHooks(options: CodexNativeHookReconc
 /** Deliberately separate from filesystem hook installation: native trust is an
  * explicit authorization of exact owned commands, never a broad trust bypass. */
 export declare function enrollCodexNativeHooks(options?: CodexNativeHookTrustOptions, connect?: Connect): Promise<{
+    nativeAdmission?: "unavailable";
+    nativeAdmissionProbe?: import("./codex-corpus-write.js").CodexAdmissionProbe;
     planDigest: string;
     skillsCli: {
         path: string;

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

@@ -1,4 +1,4 @@
-import { type CodexCorpusWriteOptions } from "./codex-corpus-write.js";
+import { type CodexAdmissionReceipt, 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";
@@ -242,7 +242,7 @@ export declare function applyAgentIntegration(plan: AgentIntegrationPlan, option
     changed: string[];
     backups: string[];
     rootAliases?: AgentRootAlias[];
-};
+} & CodexAdmissionReceipt;
 export declare function archiveNativeSkills(inventory: NativeSkillEntry[], options: CodexCorpusWriteOptions & {
     dataDir?: string;
     includeUnmanaged?: boolean;
@@ -263,7 +263,7 @@ export declare function archiveNativeSkills(inventory: NativeSkillEntry[], optio
         digest: string;
         targetCount: number;
     };
-};
+} & CodexAdmissionReceipt;
 /** Native hook input for the Codex policy adapter. Only the Codex hook paths that
  * receive native SessionStart/UserPromptSubmit input supply it; install-time and
  * other guard calls never do. `inspector` is a test seam for process lineage. */

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

@@ -1,4 +1,4 @@
-import { type CodexCorpusWriteOptions } from "./codex-corpus-write.js";
+import { type CodexAdmissionReceipt, type CodexAdmissionRecordOptions, type CodexCorpusWriteOptions } from "./codex-corpus-write.js";
 /**
  * `skills sync` — the last mile: write skills from this machine's corpus
  * (the migrated owner-layout cache ~/.hasna/skills/skills/<name>/, or the
@@ -76,7 +76,7 @@ export declare function isPointerSkillMd(markdown: string): boolean;
 /** A pointer SKILL.md for an executable skill: what it is and how to actually run it. */
 export declare function pointerSkillMd(name: string, description: string): string;
 export type SyncActionKind = "create" | "update" | "skip";
-export interface AgentSyncAction {
+export interface AgentSyncAction extends CodexAdmissionReceipt {
     skill: string;
     agent: SyncAgent;
     path: string;
@@ -155,7 +155,7 @@ export interface WriteManagedAgentSkillParams extends CodexCorpusWriteOptions {
  * directory is always left untouched. A fresh directory is created.
  */
 export declare function writeManagedAgentSkill(params: WriteManagedAgentSkillParams): AgentSyncAction;
-export interface ManagedDirWriteResult {
+export interface ManagedDirWriteResult extends CodexAdmissionReceipt {
     action: SyncActionKind;
     path: string;
     reason?: string;
@@ -181,4 +181,6 @@ export declare function writeManagedSkillDir(dir: string, skillMd: string, optio
  * did not write (no valid Skills ownership marker). Foreign or malformed markers
  * grant no deletion authority, and removal has no force override.
  */
-export declare function removeManagedAgentSkill(skill: string, agent: SyncAgent, homeDir?: string, options?: CodexCorpusWriteOptions): boolean;
+/** Returns only whether it removed; pass `onCodexAdmission` to receive the admission
+ * record. Without it, a Codex home without native admission refuses as before. */
+export declare function removeManagedAgentSkill(skill: string, agent: SyncAgent, homeDir?: string, options?: CodexCorpusWriteOptions & CodexAdmissionRecordOptions): boolean;

package/dist/lib/codex-corpus-write.d.ts

@@ -1,16 +1,57 @@
+/** Fixed refusal vocabulary for the interim fallback; never native text. */
+export type CodexCorpusRefusal = "native-lock-present" | "executable-unverified" | "probe-inconclusive" | "command-present" | "writer-busy" | "skills-lock-unavailable" | "lease-changed";
 export interface CodexCorpusWriteOptions {
     /** The selected native executable; never a shell command. */
     codexCommand?: string;
     /** Existing callers with a reviewed executable binding retain that binding. */
     codexSha256?: string;
 }
+/** The probe behind a fallback write. `executable`, `sha256` and `size` identify the
+ * selected executable file (for an npm install, the launcher script), not the vendor
+ * binary it starts. Never contains native output. */
+export interface CodexAdmissionProbe {
+    kind: "help-unrecognized-subcommand";
+    executable: string;
+    sha256: string;
+    size: number;
+    version: string;
+    probeExitCode: 2;
+    controlExitCode: 0;
+}
+export interface CodexCorpusAdmission {
+    nativeAdmission: "verified" | "unavailable";
+    probe?: CodexAdmissionProbe;
+}
+export interface CodexAdmissionReceipt {
+    nativeAdmission?: "unavailable";
+    nativeAdmissionProbe?: CodexAdmissionProbe;
+}
+export interface CodexCorpusLease {
+    assertCurrent(): void;
+    close(): void;
+    admission: CodexCorpusAdmission;
+}
+/** Boolean writers have no receipt: they use the fallback only when the caller takes this record. */
+export interface CodexAdmissionRecordOptions {
+    onCodexAdmission?: (admission: CodexCorpusAdmission) => void;
+}
+/** Gate policy for one transaction; writers without a receipt disable the fallback. */
+export interface CodexCorpusWritePolicy {
+    fallback?: boolean;
+}
+/** Reads `onCodexAdmission` once. Only a synchronous function enables the fallback and
+ * receives the record; any other defined value refuses before anything happens, and a
+ * callback that returns a thenable refuses before anything is removed. */
+export declare function codexAdmissionRecord(options: CodexAdmissionRecordOptions): {
+    policy: CodexCorpusWritePolicy;
+    deliver(admission: CodexCorpusAdmission | undefined): void;
+};
+/** Receipt fields for a write made under the interim fallback; native-path receipts are unchanged. */
+export declare function codexAdmissionReceipt(admission: CodexCorpusAdmission | undefined): CodexAdmissionReceipt;
 /** Protected aliases fail closed; unrelated project paths remain usable. */
 export declare function codexCorpusRootForPath(path: string): string | undefined;
-export declare function acquireCodexCorpusWrite(roots: readonly string[], options: CodexCorpusWriteOptions): {
-    assertCurrent: () => void;
-    close: () => void;
-};
+export declare function acquireCodexCorpusWrite(roots: readonly string[], options: CodexCorpusWriteOptions, policy?: CodexCorpusWritePolicy): CodexCorpusLease;
 /** Keep the descriptor through preimage checks, writes, rollback and readback. */
-export declare function withCodexCorpusWrite<T>(roots: readonly string[], run: (assertCurrent: () => void) => T, options?: CodexCorpusWriteOptions): T;
+export declare function withCodexCorpusWrite<T>(roots: readonly string[], run: (assertCurrent: () => void, admission?: CodexCorpusAdmission) => T, options?: CodexCorpusWriteOptions, policy?: CodexCorpusWritePolicy): T;
 /** The callback must await every native child's close before settling. */
-export declare function withCodexCorpusWriteAsync<T>(roots: readonly string[], run: (assertCurrent: () => void) => Promise<T>, options?: CodexCorpusWriteOptions): Promise<T>;
+export declare function withCodexCorpusWriteAsync<T>(roots: readonly string[], run: (assertCurrent: () => void, admission?: CodexCorpusAdmission) => Promise<T>, options?: CodexCorpusWriteOptions, policy?: CodexCorpusWritePolicy): Promise<T>;

package/dist/lib/codex-hook-rpc.d.ts

@@ -1,7 +1,10 @@
+import { type CodexCorpusAdmission } from "./codex-corpus-write.js";
 export { SUPPORTED_CODEX_HOOK_VERSIONS } from "./codex-native-compatibility.js";
 export interface CodexHookRpc {
     version: string;
     processId?: number;
+    /** How the owned client's corpus lease was admitted; absent on synthetic clients. */
+    admission?: CodexCorpusAdmission;
     request(method: string, params: unknown): Promise<any>;
     close(): Promise<void>;
 }

package/dist/lib/home-adoption.d.ts

@@ -1,6 +1,6 @@
 import { type SyncAgent, type SyncMarker } from "./agent-sync.js";
 import type { PortableSkillOptions } from "./portable-skills.js";
-import { type CodexCorpusWriteOptions } from "./codex-corpus-write.js";
+import { type CodexAdmissionReceipt, type CodexCorpusWriteOptions } from "./codex-corpus-write.js";
 export declare const CONFLICTS_LEDGER_FILE = "conflicts.json";
 export declare const ROLLBACK_DIRNAME = "rollback";
 export interface HomeSkillEntry {
@@ -36,7 +36,7 @@ export interface AdoptionOptions extends PortableSkillOptions, CodexCorpusWriteO
     /** Write markers and the conflicts ledger. Without it, scan only. */
     apply?: boolean;
 }
-export interface AdoptionResult extends AdoptionScan {
+export interface AdoptionResult extends AdoptionScan, CodexAdmissionReceipt {
     applied: boolean;
     /** Rollback record path, when markers were written. */
     rollbackFile?: string;
@@ -48,7 +48,7 @@ export interface RollbackMarker {
     hash: string;
     marker: SyncMarker;
 }
-export interface RollbackRecord {
+export interface RollbackRecord extends CodexAdmissionReceipt {
     version: 1;
     mode: "adopt" | "prune";
     timestamp: string;
@@ -58,7 +58,7 @@ export interface PruneCandidate extends RollbackMarker {
     /** The agent home skills directory. */
     home: string;
 }
-export interface PruneResult {
+export interface PruneResult extends CodexAdmissionReceipt {
     candidates: PruneCandidate[];
     pruned: number;
     dryRun: boolean;
@@ -78,7 +78,7 @@ export declare function scanUnmarkedHomes(options?: AdoptionOptions): AdoptionSc
  * every directory removed (mode "prune"), so both operations are auditable
  * from a single machine-readable file. Deleted resource bytes are not stored.
  */
-export declare function writeRollbackRecord(mode: "adopt" | "prune", entries: RollbackMarker[], appDir?: string): string;
+export declare function writeRollbackRecord(mode: "adopt" | "prune", entries: RollbackMarker[], appDir?: string, admission?: CodexAdmissionReceipt): string;
 /**
  * Adopt unmarked home skills whose content exactly matches the canonical
  * corpus. Without `apply` this is a pure scan; with `apply` it writes one

package/dist/lib/installer.d.ts

@@ -1,7 +1,7 @@
-import { type CodexCorpusWriteOptions } from "./codex-corpus-write.js";
+import { type CodexAdmissionReceipt, type CodexAdmissionRecordOptions, type CodexCorpusWriteOptions } from "./codex-corpus-write.js";
 import { type SkillMeta } from "./registry.js";
 import { type ProjectSkillPin } from "./project-state.js";
-export interface InstallResult {
+export interface InstallResult extends CodexAdmissionReceipt {
     skill: string;
     success: boolean;
     error?: string;
@@ -108,5 +108,7 @@ export declare function installSkillForAgent(name: string, options: AgentInstall
     overwrite?: boolean;
     dryRun?: boolean;
 }, generateSkillMd?: (name: string) => string | null): InstallResult;
-export declare function removeSkillForAgent(name: string, options: AgentInstallOptions): boolean;
+/** Returns only whether it removed; pass `onCodexAdmission` to receive the admission
+ * record. Without it, a Codex home without native admission refuses as before. */
+export declare function removeSkillForAgent(name: string, options: AgentInstallOptions & CodexAdmissionRecordOptions): boolean;
 export {};

package/dist/lib/search.d.ts

@@ -11,6 +11,24 @@ export declare function editDistance(a: string, b: string): number;
  * Search skills by name, description, and tags using fuzzy matching.
  */
 export declare function searchSkills(query: string, registry?: SkillMeta[]): SkillMeta[];
+/**
+ * Bounded close canonical names for a refused name, strongest evidence first:
+ *
+ *  0. the exact name;
+ *  1. a hyphen-delimited containment — the candidate owns the query as a whole
+ *     leading or trailing segment (`fleet-refresh` → `instructions-fleet-refresh`);
+ *  2. a multi-word token subset of the candidate;
+ *  3. the edit-distance rule that was the only signal before.
+ *
+ * Containment is what edit distance cannot see, and it is the case that cost
+ * real time: the canonical name that owns a shorter name as its trailing
+ * segment is 13 edits from the short name, so a caller naming the procedure by
+ * its last words was told the procedure did not exist (Agents Audit A27). The
+ * distance pass still runs and fills any slots containment leaves, so a
+ * distance-only miss — including every query under three characters — keeps the
+ * answer it has always had.
+ */
+export declare function findCloseSkillNames(query: string, names: readonly string[], maxResults?: number): string[];
 /**
  * Find skills with names similar to the given query (for "did you mean?" suggestions).
  */

package/dist/runtime-prerequisites.js

@@ -49,7 +49,7 @@ var __require = import.meta.require;
 // src/runtime-prerequisites.ts
 import { isAbsolute as isAbsolute7 } from "path";
 // package.json
-var version = "0.10.74";
+var version = "0.10.76";
 var package_default = {
   name: "@hasna/skills",
   version,