@hasna/skills 0.10.82 → 0.10.88

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

@@ -1,3 +1,4 @@
+export { renderOpenCodePlugin } from "./agent-opencode.js";
 export declare const INTEGRATION_AGENTS: readonly ["claude", "codex", "gemini", "opencode", "cursor", "hermes", "sumi"];
 export type IntegrationAgent = typeof INTEGRATION_AGENTS[number];
 export declare function renderAgentHookCommand(command: string, agent: IntegrationAgent, profileId: string, event: string): string;
@@ -23,7 +24,7 @@ export declare const AGENT_ADAPTERS: {
     readonly opencode: {
         readonly root: ".config/opencode/skills";
         readonly config: ".config/opencode/opencode.json";
-        readonly events: readonly ["chat.message"];
+        readonly events: readonly ["prompt", "context"];
         readonly promptContext: true;
     };
     readonly sumi: {
@@ -49,4 +50,6 @@ export declare const AGENT_ADAPTERS: {
     };
 };
 export declare function normalizeAgentHookEvent(agent: IntegrationAgent, event: string): string;
-export declare function renderOpenCodePlugin(command: string, profileId: string): string;
+export declare function renderLegacyOpenCodePlugin(command: string, profileId: string): string;
+/** Recognize exact managed bytes only, including the shipped v1 generator. */
+export declare function isManagedOpenCodePlugin(text: string | null, command: string, profileId: string): boolean;

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

@@ -5,6 +5,7 @@ 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 NarrowedWitnessLedger } from "./narrowed-witness-ledger.js";
 import { type CodexPluginSkillControl, type CodexPluginSourceInput } from "./codex-plugin-skill-controls.js";
 import { type RetainedReviewArtifact, type ReviewedArtifact } from "./retained-review-artifacts.js";
 import { type CodexSemanticCacheWitness, type CodexSemanticCacheAppOnlyParent, type CodexSemanticCacheReviewedHookParent } from "./codex-semantic-cache-witness.js";
@@ -13,7 +14,7 @@ export interface DiscoverySource {
     reviewArtifact?: RetainedReviewArtifact;
     path: string;
     sha256: string | null;
-    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";
+    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-settings-v5" | "claude-marketplace-registry-v2" | "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3" | "codex-settings-v4" | "codex-settings-v5" | "codex-settings-v6" | "codex-settings-v7" | "executable-v1" | "sumi-settings-v1" | "claude-marketplace-entry-v1";
     hookSources?: CodexReviewedHookSource[];
     managedPlugins?: ManagedPluginRegistrationWitness[];
     format?: "json" | "toml" | "yaml";
@@ -120,12 +121,15 @@ export declare function assertCodexSemanticCacheHookSafety(cacheRoot: string, pa
 /** 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.
+ * Only the live hooks pass `narrowed`: a legacy full-file settings witness that
+ * no longer matches is still current when the narrowed digest recorded for it
+ * matches (see narrowed-witness-ledger.ts), and a matching one is observed.
  * 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;
-}[], witnessTolerance?: NativeDiscoveryWitnessTolerance): void;
+}[], witnessTolerance?: NativeDiscoveryWitnessTolerance, narrowed?: NarrowedWitnessLedger): void;
 /** One stored Claude discovery source as an installer sees it. */
 export type ClaudeDiscoverySourceVerdict = {
     status: "current";
@@ -193,11 +197,25 @@ export declare function discoveryTextKeepsWitness(binding: Pick<AgentDiscoveryBi
 /** `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. */
-export declare function resolveAgentDiscovery(options: {
+type DiscoveryOptions = {
     home: string;
     agent: IntegrationAgent;
     reviewed?: ReviewedDiscoveryInputs;
     retainedReview?: AgentDiscoveryBinding;
     canonical?: (path: string) => string;
     executable?: DiscoveryExecutable | null;
-}): AgentDiscoveryBinding;
+};
+export declare function resolveAgentDiscovery(options: DiscoveryOptions): AgentDiscoveryBinding;
+/** Read-only exclusion, not native admission. Retained roots remain excluded,
+ * while current supported controls are re-derived even when old settings or
+ * directory witnesses are stale. Non-enumerable executable inputs still need
+ * their existing review. No witness, policy or enrollment is written. */
+export declare function resolveAgentDiscoveryExclusionRoots(options: Omit<DiscoveryOptions, "reviewed" | "retainedReview"> & {
+    retained?: AgentDiscoveryBinding;
+    narrowed?: NarrowedWitnessLedger;
+    nativeHome?: string;
+}): readonly string[];
+/** Metadata-only closure of aliases inside the selected native discovery
+ * trees. Never search the account generally or load a payload/plugin. Each
+ * resolved alias remains excluded while unrelated portable paths stay usable. */
+export declare function nativeDiscoveryAliasTargets(roots: readonly string[], home: string): string[];

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

@@ -12,13 +12,19 @@ export declare function hermesHookDefinitions(supervisor: Pick<HermesSupervisorB
     fail_closed?: boolean;
 }>;
 export declare function configureHermesHooks(text: string | null, supervisor: HermesSupervisorBinding, previous?: HermesSupervisorBinding): string;
+/** Every refusal here leaves the effective Hermes discovery unchecked (another
+ * project, home, bundled tree or project plugins), so a payload named skills-cli
+ * there could load through the bridge. They are bridge-integrity refusals: the
+ * live skill_view(skills-cli) call is refused while prompts still fail open. */
 export declare function assertHermesEnvironment(home: string): void;
 export declare function assertHermesProtection(home: string, config: Record<string, any>, command: string, profile: string, supervisor: HermesSupervisorBinding): void;
 /** skill_view also searches legacy <name>.md with rglob, including hidden and
  * dependency directories that the normal SKILL.md index skips. Check the one
  * name admitted by the native tool guard without reading any candidate bytes.
  * Only support folders directly under a real skill descriptor are excluded,
- * matching Hermes is_skill_support_path. Every other bounded path is checked. */
+ * matching Hermes is_skill_support_path. Every other bounded path is checked.
+ * A found or unrulable shadow is a bridge-integrity refusal: the live
+ * skill_view(skills-cli) call is refused, while prompts still fail open. */
 export declare function assertNoHermesLegacyShadow(root: string): void;
 export declare function normalizeHermesHookInput(input: Record<string, any>): Record<string, any>;
 export declare function assertHermesTool(input: Record<string, any>): void;

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

@@ -4,6 +4,7 @@ import { type ReviewedCodexSkillDenial, type CodexPluginSkillControl } from "./c
 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 BigIntStats } from "node:fs";
 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";
@@ -178,6 +179,11 @@ export interface ClaudeManagedHookProjectionOptions {
     /** Supply the preceding plan's source witness when checking it before use. */
     expectedSourceSha256?: string;
 }
+export declare function assertNativePathAcl(path: string, observed: BigIntStats, options?: {
+    allowDenyOnly?: boolean;
+    descriptor?: number;
+    creationParent?: boolean;
+}): void;
 /** Read-only projection for a copied Claude configuration. This does not install
  * hooks, adopt target discovery, change policy, or confer write/admission authority.
  * The caller must preserve the full target, hold its owning writer lease, replan
@@ -207,8 +213,8 @@ export declare function planClaudeHookEventsUpdate(options: ClaudeHookUpdateOpti
  */
 export declare function planAgentSettingsWitnessUpgrade(options: {
     agent: "claude" | "codex" | "sumi";
-    targetCodexVersion?: 2 | 3 | 4 | 5;
-    targetClaudeVersion?: 3 | 4;
+    targetCodexVersion?: 2 | 3 | 4 | 5 | 7;
+    targetClaudeVersion?: 3 | 4 | 5;
     reviewedPreimage: string;
     home?: string;
     dataDir?: string;
@@ -404,6 +410,25 @@ interface ManagedBridgeOptions {
      * vendor copies and every other change still refuse. Install, trust, migrate
      * and sync never pass it. */
     codexPromptHook?: boolean;
+    /** Live lifecycle hooks only (prompt, session, subagent and tool events).
+     * - A legacy full-file settings witness that no longer matches stays current
+     *   when the narrowed digest recorded for its review is unchanged, and a
+     *   matching one is recorded (narrowed-witness-ledger.ts).
+     * - Anything that stops the skills-cli bridge from being verified is a
+     *   NativeBridgeIntegrityRefusal, and any other failure to verify native
+     *   discovery (a changed root alias, an unreadable settings file, an
+     *   inventory error) is reported as NATIVE_SKILL_DRIFT, so the hook can fail
+     *   open instead of blocking the prompt.
+     * Install, trust, migrate, sync and upgrades never pass it. */
+    liveHook?: boolean;
+    /** Live tool events that would load the skills-cli bridge (Claude
+     * Skill(skills-cli), Gemini activate_skill(skills-cli), Hermes
+     * skill_view(skills-cli)); requires liveHook. Before such a call proceeds,
+     * no native copy may be able to resolve under the bridge's own name, in any
+     * tier the agent searches, including after an earlier drift skipped the
+     * inventory. A found copy, or a check that cannot complete, is a
+     * NativeBridgeIntegrityRefusal. */
+    bridgeToolCall?: boolean;
 }
 /** Result of a guard call; both lists are empty unless the caller opted in.
  * `codexInertVendorCopies` holds the canonical skill directories exempted as
@@ -444,7 +469,11 @@ export declare function codexPromptDriftWarning(report: ManagedBridgeReport): st
 /** 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): ManagedBridgeReport;
+/** Consumption-edge check: native registry content and path must name the
+ * exact owned bridge, and live on-disk custody must still verify now. */
+export declare function assertOpenCodeNativeBridge(skill: unknown, options?: ManagedBridgeOptions): void;
 export declare function normalizeAgentHookPrompt(agent: IntegrationAgent, event: string, prompt: string): string;
+export declare function isAgentSubmittedPrompt(prompt: unknown): boolean;
 export declare function hookContextOutput(event: string, result: {
     context: string;
     receipt?: unknown;

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

@@ -0,0 +1,4 @@
+/** OpenCode v2.0.32 Promise contract: plugin/module.ts, promise/session.ts,
+ * promise/tool.ts and promise/registration.ts in anomalyco/opencode.
+ * Prompt admission captures genuine input; context matches/restores at delivery. */
+export declare function renderOpenCodePlugin(command: string, profile: string): string;

package/dist/lib/claude-hook-disable.d.ts

@@ -0,0 +1,32 @@
+export interface ClaudeHookDisableOptions {
+    settings: string;
+    expectedSettingsSha256: string;
+    expectedMode: "0600" | "absent";
+    command: string;
+    expectedCommandSha256: string;
+    profile: string;
+    apply?: boolean;
+    /** New, exclusive, private directory. Its parent must already exist. */
+    preimageDir?: string;
+}
+export interface ClaudeHookDisableResult {
+    schema: "hasna.claude-hook-disable.v1";
+    state: "preview" | "applied" | "no-op" | "no-data" | "ambiguous";
+    mutationOccurred: boolean;
+    target: string;
+    beforeSha256: string | null;
+    plannedAfterSha256: string | null;
+    afterSha256: string | null;
+    removed: Array<{
+        event: string;
+        groupIndex: number;
+        hookIndex: number;
+    }>;
+    settingsWitness: "unchanged" | "not-renewed";
+    preimage?: string;
+    displaced?: string;
+    receipt?: string;
+    reason?: string;
+}
+/** Only removes exact rendered context registrations. Never installs, admits or rebinds. */
+export declare function disableClaudeHooks(options: ClaudeHookDisableOptions): ClaudeHookDisableResult;

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

@@ -10,6 +10,9 @@ export interface ClaudeSettingsWitnessBudget {
     remaining: number;
 }
 export declare function readNativeSettingsWitnessFile(path: string, budget: ClaudeSettingsWitnessBudget, filename?: "settings.json" | "config.toml" | "sumi.json" | "marketplace.json"): string;
+/** The same bounded, stable, strict-UTF8 read for root-exclusion inputs whose
+ * filenames are selected by the owning agent adapter rather than settings. */
+export declare function readNativeDiscoveryWitnessFile(path: string, budget: ClaudeSettingsWitnessBudget): string;
 export type NativeJsonObject = ObjectValue;
 export type NativeJsonValue = Value;
 type ObjectValue = {
@@ -93,6 +96,31 @@ export declare function upgradeClaudeSettingsWitnessV4(previous: {
     hashMode?: "bytes" | "claude-settings-v1" | "claude-settings-v2" | "claude-settings-v3";
     sha256: string;
 }, reviewedSettingsPath: string): ReturnType<typeof captureClaudeSettingsV4>;
+/** Current discovery controls, parsed by the same bounded, duplicate-key-safe
+ * adapter as the v5 witness. Root exclusion consumes this without changing a
+ * stored review or accepting that review for native loading. */
+export declare function claudeDiscoveryControlKeys(text: string): string[];
+/** Discovery environment names from the same owning projection, without
+ * returning their values or treating ordinary environment as discovery. */
+export declare function claudeDiscoveryEnvironmentKeys(text: string): string[];
+/** Explicit v5 review: the narrowed discovery projection above. v1-v4
+ * witnesses keep their meaning; nothing selects v5 implicitly. */
+export declare function captureClaudeSettingsV5(path: string, budget?: ClaudeSettingsWitnessBudget): {
+    path: string;
+    hashMode: "claude-settings-v5";
+    sha256: string;
+};
+export declare function hashClaudeSettingsReplacementV5(text: string, budget: ClaudeSettingsWitnessBudget): string;
+/** Explicit upgrade from any prior witness (raw bytes, v1-v4) with an exact
+ * preserved preimage of its review. v5 binds a subset of what each earlier mode
+ * binds, so only a difference in settings v5 ignores is accepted; a change to a
+ * hook, plugin, marketplace, skill key, Skill rule, added directory or
+ * discovery environment variable still refuses. */
+export declare function upgradeClaudeSettingsWitnessV5(previous: {
+    path: string;
+    hashMode?: "bytes" | "claude-settings-v1" | "claude-settings-v2" | "claude-settings-v3" | "claude-settings-v4";
+    sha256: string;
+}, reviewedSettingsPath: string): ReturnType<typeof captureClaudeSettingsV5>;
 /** Strict bounded JSON control witness; metadata exclusion must be explicit. */
 export declare function hashNativeJsonControls(text: string, excludedMetadata?: "version"): string;
 /** Sumi's versioned review uses the same strict JSON parser and bounded syntax

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

@@ -79,6 +79,26 @@ export declare function upgradeCodexSettingsWitnessV5(previous: {
     hashMode?: "bytes" | "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3" | "codex-settings-v4";
     sha256: string;
 }, reviewedSettingsPath: string): ReturnType<typeof captureCodexSettingsV5>;
+/** Root exclusion uses the same discovery projection as V7, including every
+ * profile and instruction/MCP control, without creating a settings witness. */
+export declare function codexDiscoveryControlKeys(config: Record<string, any>): string[];
+/** Explicit V7 review: the narrowed discovery projection above. Earlier modes
+ * keep their meaning; nothing selects V7 implicitly. */
+export declare function hashCodexSettingsReplacementV7(text: string, budget?: ClaudeSettingsWitnessBudget): string;
+export declare function captureCodexSettingsV7(path: string, budget?: ClaudeSettingsWitnessBudget): {
+    path: string;
+    hashMode: "codex-settings-v7";
+    sha256: string;
+};
+/** Prove the preserved original under its exact original contract (raw bytes or
+ * V1-V5), then require the same V7 projection. V7 binds a subset of what each
+ * of those modes binds, so only a difference in settings V7 ignores passes.
+ * V6 is not eligible: it binds hook MCP dependencies V7 does not carry. */
+export declare function upgradeCodexSettingsWitnessV7(previous: {
+    path: string;
+    hashMode?: "bytes" | "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3" | "codex-settings-v4" | "codex-settings-v5";
+    sha256: string;
+}, reviewedSettingsPath: string): ReturnType<typeof captureCodexSettingsV7>;
 /** V6 keeps V5 display tolerances and binds routes referenced by the complete
  * independently reviewed native hook source population. No legacy migration. */
 export declare function captureCodexSettingsV6(path: string, reviewedSources: readonly CodexReviewedHookSource[], budget?: ClaudeSettingsWitnessBudget, changes?: Map<string, string>): {

package/dist/lib/guarded-agent-config.d.ts

@@ -0,0 +1,3 @@
+export declare function guardedAgentConfigRefusal(error: unknown): string;
+/** One transaction for the direct-file adapters. Failed evidence stays beside the original. */
+export declare function guardedAgentConfigWrite(path: string, transform: (current: Buffer | null) => string): void;

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

@@ -5,7 +5,9 @@ export declare class HookDiagnosticError extends Error {
     readonly 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");
+    /** Fixed marker: an expired pin whose renewal continues in a background worker. */
+    readonly renewal?: "background";
+    constructor(code: string, stage: "context" | "sync", migration?: "timeout", renewal?: "background");
 }
 export declare function hookChildError(stdout: string, stage: "context" | "sync"): HookDiagnosticError;
 export declare function hookFailureReason(error: unknown, profileId?: string): string;

package/dist/lib/narrowed-witness-ledger.d.ts

@@ -0,0 +1,24 @@
+import type { DiscoverySource } from "./agent-discovery.js";
+export type NarrowedSettingsMode = "claude-settings-v5" | "codex-settings-v7";
+export declare const NARROWED_WITNESS_LEDGER_FILE = "native-witness-narrowed.json";
+/** The narrowed mode that covers this legacy full-file settings witness, or
+ * null when it has none. */
+export declare function narrowedLegacyWitnessMode(source: DiscoverySource): NarrowedSettingsMode | null;
+export interface NarrowedWitnessLedger {
+    /** The legacy witness no longer matches: accept only when the current file's
+     * narrowed digest equals the one recorded for this exact witness. */
+    accepts(source: DiscoverySource): boolean;
+    /** The legacy witness verified the current file: record its narrowed digest,
+     * re-proving the legacy match on the same bytes first. */
+    observe(source: DiscoverySource): void;
+    /** Paths accepted through a recorded narrowed digest during this check. */
+    readonly accepted: string[];
+}
+/** Opened by the live hook only. `record` permits observations to be written
+ * by flush(); reads never write. Every failure is fail-closed: an unreadable or
+ * malformed ledger accepts nothing and is never overwritten. */
+export declare function openNarrowedWitnessLedger(dataDir: string, options?: {
+    record: boolean;
+}): NarrowedWitnessLedger & {
+    flush(): void;
+};

package/dist/lib/native-discovery-roots.d.ts

@@ -1,2 +1,10 @@
 /** Shared default discovery roots for inventory and authoring exclusion. */
 export declare const NATIVE_SKILL_ROOTS: readonly [readonly ["claude", ".claude/skills"], readonly ["codex", ".codex/skills"], readonly ["codex", ".agents/skills"], readonly ["gemini", ".gemini/skills"], readonly ["sumi", ".sumi/skills"], readonly ["sumi", ".sumi/skill"], readonly ["codewith", ".codewith/skills"], readonly ["opencode", ".config/opencode/skills"], readonly ["opencode", ".opencode/skills"], readonly ["cursor", ".cursor/skills"], readonly ["hermes", ".hermes/skills"], readonly ["windsurf", ".windsurf/skills"], readonly ["pi", ".pi/agent/skills"], readonly ["amp", ".amp/skills"], readonly ["cline", ".cline/skills"], readonly ["roo", ".roo/skills"], readonly ["copilot", ".github/skills"]];
+/** Supplemental Sumi project tiers are shared with inventory. The caller
+ * supplies Sumi's owning resolver so this root contract has no runtime or
+ * enrollment dependency. Authoring can still exclude the shared tiers when
+ * the Sumi resolver is absent. */
+export declare function nativeSumiProjectSkillRoots(home: string, project: string, resolveSumiRoots: (home: string, project: string) => readonly string[]): string[];
+/** Native project discovery includes every ancestor. Keep inventory and
+ * authoring on this same bounded context enumeration. */
+export declare function nativeProjectAncestorDirectories(projects: readonly string[], canonical?: (path: string) => string): string[];

package/dist/lib/native-drift-receipt.d.ts

@@ -0,0 +1,55 @@
+export declare const NATIVE_DRIFT_RECEIPT_SCHEMA = "hasna.skills.native-drift-receipt.v1";
+export declare const NATIVE_DRIFT_RECEIPT_DIRECTORY = "native-drift";
+/** A native tool-policy refusal: denying a native payload skill is the
+ * protection that keeps a drifted station safe, so it is never failed open. */
+export declare class NativeSkillPolicyRefusal extends Error {
+}
+/** The skills-cli bridge itself could not be verified: it is missing or
+ * modified, or the managed binding that names it is missing, incompatible or
+ * no longer resolves. A tool call that would load the bridge is refused; a
+ * prompt, session or subagent event fails open with NATIVE_DRIFT_BRIDGE_NOTICE. */
+export declare class NativeBridgeIntegrityRefusal extends NativeSkillPolicyRefusal {
+}
+export declare function isNativeSkillDrift(error: unknown): error is Error;
+export declare function isNativeBridgeIntegrityRefusal(error: unknown): error is NativeBridgeIntegrityRefusal;
+/** Escape controls, format characters and line separators as \uXXXX so a path
+ * from the file system cannot hide or reorder warning text, then bound it. */
+export declare function boundedDriftReason(message: string, limit?: number): string;
+export declare function nativeDriftRepair(agent: string): string;
+/** One visible line: what happened, the bounded drift reason (it names the
+ * changed path or copies), the repair command and the receipt path. */
+export declare function nativeDriftWarning(agent: string, message: string, receiptPath: string | null): string;
+/** Fixed agent-facing notice for the turn whose Skills context was omitted. */
+export declare const NATIVE_DRIFT_AGENT_NOTICE = "Skills context is unavailable for this turn because the station's native skill discovery changed; the change was reported to the operator. Continue the user's task. Load a selected skill explicitly with `skills load <slug>` if one is needed, and do not load native skill copies.";
+/** Fixed agent-facing notice when the skills-cli bridge itself is unverified:
+ * the bridge tool is refused this turn, so the agent uses the CLI instead. */
+export declare const NATIVE_DRIFT_BRIDGE_NOTICE = "Skills context is unavailable for this turn because the station's skills-cli bridge could not be verified; the change was reported to the operator. Continue the user's task, but do not invoke the skills-cli native skill until it is repaired. Run the `skills` command directly (for example `skills load <slug>`) if a skill is needed, and do not load native skill copies.";
+export interface NativeDriftReceipt {
+    schema: typeof NATIVE_DRIFT_RECEIPT_SCHEMA;
+    agent: string;
+    status: "active" | "cleared";
+    code: "NATIVE_SKILL_DRIFT";
+    event: string;
+    promptBlocked: false;
+    skillsContext: "omitted";
+    reason: string;
+    reasonSha256: string;
+    repair: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    occurrences: number;
+    clearedAt?: string;
+}
+export declare function nativeDriftReceiptPath(dataDir: string, agent: string): string;
+/** Record or refresh the active receipt for this agent. Never throws: the
+ * warning says when the receipt could not be recorded. */
+export declare function recordNativeDriftReceipt(dataDir: string, agent: string, event: string, message: string, now?: Date): string | null;
+/** After a clean verification: mark an active receipt cleared, keeping its
+ * history. Absent or already cleared receipts are left untouched. */
+export declare function clearNativeDriftReceipt(dataDir: string, agent: string, now?: Date): void;
+/** Every readable receipt, for operators and monitors. */
+export declare function readNativeDriftReceipts(dataDir: string): NativeDriftReceipt[];
+/** The non-blocking envelope for drift, in each native adapter's own shape. */
+export declare function nativeDriftFailOpen(dataDir: string, agent: string, event: string, nativeEvent: string, message: string, options?: {
+    bridgeUnverified?: boolean;
+}): Record<string, unknown>;

package/dist/lib/opencode-hook-protocol.d.ts

@@ -0,0 +1,5 @@
+export declare const OPENCODE_BRIDGE_BODY_SHA256: string;
+export declare const OPENCODE_BRIDGE_DESCRIPTION_SHA256: string;
+export declare function isVerifiedOpenCodeSkillDescriptor(value: unknown, expectedPath: string): boolean;
+/** Explicit adapter phase, including empty attachment-only prompt admission. */
+export declare function openCodeContextDelivery(input: unknown): boolean;

package/dist/lib/profile-client.d.ts

@@ -20,6 +20,7 @@ export declare class HttpProfileClient implements ProfileClient {
     private signal?;
     readonly authority: string;
     private origin;
+    private responseSignals;
     constructor(key: string, origin: string, signal?: AbortSignal | undefined);
     private requestRoute;
     private request;

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

@@ -55,6 +55,25 @@ export declare function validateSelection(selection: ResolvedSkillSelection): vo
 export declare function validateResolvedProfile(profile: ResolvedSkillProfile, authority?: string): void;
 export declare function selectionBundlePath(selection: ResolvedSkillSelection, options?: SelectionCacheOptions): string;
 export declare function writeSelectionJson(path: string, value: unknown): void;
+/**
+ * Create a small private JSON file with exclusive, no-follow semantics. Returns
+ * false when the path already exists; never replaces anything.
+ */
+export declare function createExclusiveSelectionJson(path: string, value: unknown, maximumBytes?: number): boolean;
+/** A small private regular file's bytes and identity, or null when it is absent. */
+export declare function readSelectionFileSnapshot(path: string, maximumBytes?: number): {
+    bytes: Uint8Array;
+    sha256: string;
+    mtimeMs: number;
+    dev: number;
+    ino: number;
+} | null;
+/** Remove a small private file only while it still holds exactly the inspected bytes and inode. */
+export declare function removeSelectionFileIfUnchanged(path: string, expected: {
+    sha256: string;
+    dev: number;
+    ino: number;
+}): boolean;
 export declare function readSelectionJson<T>(path: string, maximumBytes?: number): T | null;
 export declare function readCachedSelection(selection: ResolvedSkillSelection, options?: SelectionCacheOptions): Promise<SkillBundleEntry[] | null>;
 /** Verify an authenticated exact-version response without changing any cache or receipt. */
@@ -93,6 +112,24 @@ export declare function inspectSessionWriteLock(sessionId: string, options?: Sel
     hostBound: boolean;
 };
 export declare function recoverSessionWriteLock(sessionId: string, reviewDigest: string, options?: SelectionCacheOptions): string;
+/**
+ * How long a receipt write waits for another live holder of a session write
+ * lock before it refuses with SESSION_WRITE_BUSY. Holders keep a lock only for
+ * one bounded receipt read-compare-write (or one archived replacement), so
+ * concurrent hooks of one session (a prompt and its subagents starting
+ * together) serialize instead of refusing. Waiting never replaces, recovers or
+ * ignores a lock: a held lock that outlives the wait still refuses.
+ */
+export declare const SESSION_WRITE_LOCK_WAIT_MS = 2000;
+/**
+ * A context that writes nothing never takes the session write lock, so a
+ * live writer cannot make it wait or refuse. It still refuses, exactly as a
+ * writer would, when the lock path holds something that is not a structurally
+ * valid writer lock (SESSION_WRITE_LOCKED: damaged, foreign or unsafe state
+ * that needs recovery review). A lock that changes while it is inspected (a
+ * writer publishing or releasing it) is inspected again a few times first.
+ */
+export declare function assertSessionWriteLockReadable(sessionId: string, options?: SelectionCacheOptions): void;
 /**
  * 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
@@ -100,9 +137,17 @@ export declare function recoverSessionWriteLock(sessionId: string, reviewDigest:
  */
 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. */
+/**
+ * Receipt creation and updates are exact-snapshot CAS operations. Child
+ * creation also fences its parent. Under contention this blocks the calling
+ * thread for at most SESSION_WRITE_LOCK_WAIT_MS.
+ */
 export declare function writeSkillSession(receipt: SkillSessionReceipt, expected: SkillSessionWritePrecondition, options?: SelectionCacheOptions): void;
-/** Preserve both sides before the single atomic replacement; failures retain recovery evidence. */
+/**
+ * Preserve both sides before the single atomic replacement; failures retain
+ * recovery evidence. Under contention this blocks the calling thread for at
+ * most SESSION_WRITE_LOCK_WAIT_MS.
+ */
 export declare function replaceSkillSession(expected: SkillSessionParentBinding, replacement: SkillSessionReceipt, plan: unknown, options?: SelectionCacheOptions, beforeCommit?: () => void): {
     archivePath: string;
     receiptPath: string;

package/dist/lib/session-background-renewal.d.ts

@@ -0,0 +1,118 @@
+import { SkillSelectionError, type SelectionCacheOptions } from "./selection-cache.js";
+import { type SessionReconciliationOptions } from "./session-reconciliation.js";
+/** The longest an expired-pin prompt waits for its background renewal. */
+export declare const BACKGROUND_RENEWAL_WAIT_MS = 3000;
+/** A lock older than this belongs to no live worker (the worker's own budget plus margin). */
+export declare const BACKGROUND_RENEWAL_LOCK_TTL_MS: number;
+/** A failed attempt for the same pin is reported again, not retried, within these windows. */
+export declare const EXPIRED_RENEWAL_RETRY_MS = 30000;
+export declare const AHEAD_RENEWAL_RETRY_MS: number;
+export type BackgroundRenewalMode = "expired" | "ahead";
+export type BackgroundRenewalStatus = "running" | "renewed" | "migrated" | "unchanged" | "failed";
+export interface BackgroundRenewalState {
+    schemaVersion: 1;
+    kind: "session-pin-background-renewal";
+    sessionId: string;
+    profileId: string;
+    operationId: string;
+    /** verifiedAt of the exact pin this attempt renews. */
+    pinVerifiedAt: string;
+    mode: BackgroundRenewalMode;
+    status: BackgroundRenewalStatus;
+    startedAt: string;
+    finishedAt?: string;
+    workerPid?: number;
+    code?: string;
+    migrationTimeout?: true;
+    /** No worker could be started; such a record never delays the next attempt. */
+    notStarted?: true;
+    /**
+     * The exact request this attempt answers: the receipt bytes, mode,
+     * migration setting and prompt directory. A recorded failure is reused only
+     * for the same request; any change (a rewritten receipt, migration turned
+     * on, another directory) asks again at once.
+     */
+    requestDigest?: string;
+}
+export interface BackgroundRenewalRequest {
+    sessionId: string;
+    profileId: string;
+    pinVerifiedAt: string;
+    mode: BackgroundRenewalMode;
+    /** SHA-256 of the exact receipt bytes this request read. */
+    receiptSha256: string;
+    /** Expired pins only: the managed hook's automatic migration of a refused renewal. */
+    migrate?: boolean;
+    /** The prompt's directory, which migration requires (project locks keep the refusal). */
+    projectDir?: string;
+}
+export interface BackgroundRenewalOptions extends SelectionCacheOptions {
+    /**
+     * Tests replace the detached worker; production spawns `skills sessions
+     * renew-background`. `notStarted` is called if the worker fails to start
+     * after this returns (an asynchronous spawn error such as EAGAIN).
+     */
+    spawnWorker?: (args: string[], notStarted: () => void) => void;
+}
+/** The identity of one renewal request; equal digests ask the authority the same question. */
+export declare function backgroundRenewalRequestDigest(request: BackgroundRenewalRequest): string;
+/**
+ * The last recorded attempt for this session, or null when absent or not
+ * exact. Only validated fields are returned; anything else in the file is
+ * dropped, so no unvalidated value reaches a caller's output.
+ */
+export declare function readBackgroundRenewalState(sessionId: string, options?: SelectionCacheOptions): BackgroundRenewalState | null;
+export type BackgroundRenewalStart = 
+/** `operationId` names the attempt to wait for, when its lock is readable. */
+{
+    status: "started" | "running";
+    operationId?: string;
+}
+/** `notStarted`: no worker could be started, so the caller may renew inline instead. */
+ | {
+    status: "failed";
+    state: BackgroundRenewalState;
+    notStarted?: true;
+};
+/**
+ * Start the session's background renewal unless one is running, or report a
+ * recent failure of the same pin without starting another.
+ */
+export declare function startBackgroundRenewal(request: BackgroundRenewalRequest, options?: BackgroundRenewalOptions): BackgroundRenewalStart;
+export type BackgroundRenewalWait = {
+    status: "running" | "changed";
+} | {
+    status: Exclude<BackgroundRenewalStatus, "running">;
+    state: BackgroundRenewalState;
+};
+/**
+ * Wait up to waitMs for the attempt renewing this exact pin to finish, or for
+ * the session receipt to stop holding that pin. With an operation id, only
+ * that attempt's outcome counts.
+ */
+export declare function awaitBackgroundRenewal(sessionId: string, pinVerifiedAt: string, waitMs: number, options?: SelectionCacheOptions, operationId?: string): Promise<BackgroundRenewalWait>;
+export interface BackgroundRenewalRun {
+    status: BackgroundRenewalStatus | "superseded";
+    code?: string;
+}
+/**
+ * The worker: renew (or, for an expired pin with migration on, migrate) one
+ * session pin with the background budget, record the outcome, release the lock.
+ */
+export declare function runBackgroundRenewal(sessionId: string, profileId: string, operationId: string, request: {
+    migrate?: boolean;
+    projectDir?: string;
+}, options?: SessionReconciliationOptions): Promise<BackgroundRenewalRun>;
+/**
+ * An expired pin whose background renewal is still running. It keeps the
+ * renewal timeout's code (fixed codes cross the hook boundary) and a fixed
+ * marker so the hook can say the renewal continues instead of restarting.
+ */
+export declare class SessionRenewalInBackground extends SkillSelectionError {
+    readonly renewal: "background";
+    constructor();
+}
+/** The recorded failure of a background attempt, as the error the inline renewal would have raised. */
+export declare function backgroundRenewalError(state: BackgroundRenewalState): SkillSelectionError;
+/** The pin's age class, from its verifiedAt; null when it is neither due nor expired. */
+export declare function renewalModeFor(verifiedAt: string, now: number): BackgroundRenewalMode | null;