@hasna/skills 0.9.1 → 0.9.3

package/dist/index.js

@@ -11448,7 +11448,7 @@ import { isAbsolute as isAbsolute10, join as join20, resolve as resolve10 } from
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.9.1",
+  version: "0.9.3",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -11457,6 +11457,7 @@ var package_default = {
     "skills-serve": "bin/server.js",
     "skills-server": "bin/server.js",
     "skills-worker": "bin/worker.js",
+    "skills-maintenance": "bin/maintenance.js",
     "skills-migrate": "bin/migrate.js"
   },
   exports: {
@@ -11497,7 +11498,7 @@ var package_default = {
   types: "./dist/index.d.ts",
   scripts: {
     clean: "rm -rf bin/ dist/",
-    build: "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
+    build: "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/server/maintenance.ts --outfile ./bin/maintenance.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     "build:js": "rm -rf dist && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     test: "bun test --timeout 30000",
     dev: "bun run ./src/cli/index.tsx",
@@ -15738,6 +15739,35 @@ function treeHash(root2) {
   visit2(root2);
   return hash2.digest("hex");
 }
+function selectNativeMigrationTargets(inventory, manifest) {
+  if (manifest.schema !== "hasna.skills-native-migration-targets.v1" || !/^[0-9a-f]{64}$/.test(manifest.digest) || !Array.isArray(manifest.targets) || manifest.targets.length === 0)
+    throw new Error("Invalid native migration target manifest");
+  const identities = new Set;
+  const selected = [];
+  for (const target of manifest.targets) {
+    const projectRoot = resolve15(target.projectRoot), normalized = relative5(projectRoot, resolve15(projectRoot, target.path));
+    if (!isAbsolute15(target.projectRoot) || projectRoot !== target.projectRoot || !existsSync11(projectRoot) || !lstatSync18(projectRoot).isDirectory())
+      throw new Error(`Native migration target project root must be an existing absolute directory: ${target.projectRoot}`);
+    assertSafePath(projectRoot);
+    if (isAbsolute15(target.path) || target.path.includes("\\") || target.path.includes("\x00") || !normalized || normalized === ".." || normalized.startsWith(`..${sep6}`) || normalized !== target.path || !/^[0-9a-f]{64}$/.test(target.treeSha256))
+      throw new Error(`Invalid native migration target: ${target.path}`);
+    const identity3 = `${target.agent}\x00${projectRoot}\x00${normalized}`;
+    if (identities.has(identity3))
+      throw new Error(`Duplicate native migration target: ${target.path}`);
+    identities.add(identity3);
+    const expected = resolve15(target.projectRoot, target.path);
+    const matches = inventory.filter((entry2) => entry2.agent === target.agent && resolve15(entry2.path) === expected);
+    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.hash !== target.treeSha256 || treeHash(entry.path) !== target.treeSha256)
+      throw new Error(`Native migration target changed after review: ${entry.path}`);
+    selected.push(entry);
+  }
+  return selected;
+}
 function projectAncestorDirectories(projects) {
   const directories = new Set;
   for (const project of projects) {
@@ -15755,10 +15785,12 @@ function projectAncestorDirectories(projects) {
 }
 function inventoryNativeSkills(home = homedir3(), options = {}) {
   const aliases = rootAliases(home, options.allowRootAliases);
-  const roots = ROOTS.map(([agent, path]) => [agent, canonicalAgentPath(join25(home, path), aliases)]);
+  const selectedAgents = options.agents ? new Set(options.agents) : undefined;
+  const rootDefinitions = selectedAgents ? ROOTS.filter(([agent, path]) => selectedAgents.has(agent) || selectedAgents.has("hermes") && agent === "codex" && path === ".agents/skills") : ROOTS;
+  const roots = rootDefinitions.map(([agent, path]) => [agent, canonicalAgentPath(join25(home, path), aliases)]);
   const bridgePaths = Object.values(AGENT_ADAPTERS).map((adapter) => canonicalAgentPath(join25(home, adapter.root, CLI_BRIDGE_NAME), aliases));
   for (const project of projectAncestorDirectories([...options.projectDirs ?? [], ...options.projectDir ? [options.projectDir] : []])) {
-    for (const [agent, path] of ROOTS)
+    for (const [agent, path] of rootDefinitions)
       roots.push([agent, canonicalAgentPath(join25(project, path), aliases)]);
   }
   const entries = [], seen = new Set;
@@ -16014,7 +16046,7 @@ function planAgentIntegration(options) {
     return [agent, { command, profileId: profileId2 }];
   }));
   const discoveries = [...new Set(options.agents)].map((agent) => resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, canonical: (path) => canonicalAgentPath(path, aliases) }));
-  const nativeSkills = inventoryNativeSkills(home, { includeVendor: true, guardHermes: options.agents.includes("hermes"), projectDir: options.projectDir, agentRoots: discoveries.flatMap((binding) => binding.roots.map((path) => ({ agent: binding.agent, path }))), allowRootAliases: options.allowRootAliases });
+  const nativeSkills = inventoryNativeSkills(home, { includeVendor: true, guardHermes: options.agents.includes("hermes"), agents: options.agents, projectDir: options.projectDir, agentRoots: discoveries.flatMap((binding) => binding.roots.map((path) => ({ agent: binding.agent, path }))), allowRootAliases: options.allowRootAliases });
   const changes = [];
   for (const agent of [...new Set(options.agents)]) {
     if (!INTEGRATION_AGENTS.includes(agent))
@@ -16226,12 +16258,13 @@ function archiveNativeSkills(inventory, options) {
     if (!expected || treeHash(entry.path) !== entry.hash || !isOwnedCliBridge(entry.path, [expected]))
       throw new Error(`Skills bridge changed after planning: ${entry.path}`);
   }
-  const selected = inventory.filter((entry) => !entry.bridge && !entry.system && (entry.vendor ? options.includeVendor : entry.managed || options.includeUnmanaged));
+  const selected = options.targetManifest ? selectNativeMigrationTargets(inventory, options.targetManifest) : inventory.filter((entry) => !entry.bridge && !entry.system && (entry.vendor ? options.includeVendor : entry.managed || options.includeUnmanaged));
   for (const entry of selected)
     if (treeHash(entry.path) !== entry.hash)
       throw new Error(`Native skill changed after planning: ${entry.path}`);
+  const targetManifest = options.targetManifest ? { schema: options.targetManifest.schema, digest: options.targetManifest.digest, targetCount: options.targetManifest.targets.length } : undefined;
   if (!selected.length)
-    return { entries: [], ...aliases.length ? { rootAliases: aliases } : {} };
+    return { entries: [], ...targetManifest ? { targetManifest } : {}, ...aliases.length ? { rootAliases: aliases } : {} };
   const operationId = randomUUID3(), archiveRoot = join25(options.dataDir ?? getDataDir(), "migration", operationId, "native"), receiptPath = join25(archiveRoot, "receipt.json");
   const entries = selected.map((entry, index) => ({
     source: entry.vendor ? join25(entry.path, "SKILL.md") : entry.path,
@@ -16240,7 +16273,7 @@ function archiveNativeSkills(inventory, options) {
     ...entry.vendor ? { discoveryOnly: true } : {},
     status: "planned"
   }));
-  const journal = { version: 2, operationId, status: "planned", entries, ...aliases.length ? { rootAliases: aliases } : {} };
+  const journal = { version: 2, operationId, status: "planned", entries, ...targetManifest ? { targetManifest } : {}, ...aliases.length ? { rootAliases: aliases } : {} };
   const moved = [];
   const verifyArchive = (entry) => {
     assertSafePath(entry.archive);
@@ -16334,7 +16367,7 @@ function archiveNativeSkills(inventory, options) {
     } catch {}
     throw new Error(`Native archive failed; inspect the recovery journal at ${receiptPath} before retrying.`, { cause: error });
   }
-  return { entries: entries.map(({ status, conflict, ...entry }) => entry), receiptPath, ...aliases.length ? { rootAliases: aliases } : {} };
+  return { entries: entries.map(({ status, conflict, ...entry }) => entry), receiptPath, ...targetManifest ? { targetManifest } : {}, ...aliases.length ? { rootAliases: aliases } : {} };
 }
 function assertNativeExportAllowed(dataDir2 = getDataDirReadOnly()) {
   if (requiresCliSkillLoading(dataDir2))

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

@@ -22,6 +22,17 @@ export interface NativeSkillEntry {
     bridgeHome?: string;
     rootAlias?: AgentRootAlias;
 }
+export interface NativeMigrationTarget {
+    agent: string;
+    projectRoot: string;
+    path: string;
+    treeSha256: string;
+}
+export interface NativeMigrationTargetManifest {
+    schema: "hasna.skills-native-migration-targets.v1";
+    targets: NativeMigrationTarget[];
+    digest: string;
+}
 export interface AgentConfigChange {
     path: string;
     before: string | null;
@@ -40,11 +51,21 @@ export interface AgentIntegrationPlan {
     discoveryAfter?: AgentDiscoveryBinding[];
     rootAliases?: AgentRootAlias[];
 }
+/** Parse the reviewed exact-target binding used by native migration. Paths are
+ * deliberately project-relative so a manifest cannot silently select another
+ * checkout when a project root changes. */
+export declare function parseNativeMigrationTargetManifest(input: string | Buffer): NativeMigrationTargetManifest;
+/** Read a manifest without following links or opening special files, with a
+ * finite bound so a CLI cannot block on an untrusted path. */
+export declare function readNativeMigrationTargetManifest(path: string): NativeMigrationTargetManifest;
+/** Validate every reviewed target before any archive directory or journal is created. */
+export declare function selectNativeMigrationTargets(inventory: NativeSkillEntry[], manifest: NativeMigrationTargetManifest): NativeSkillEntry[];
 export declare function inventoryNativeSkills(home?: string, options?: {
     includeVendor?: boolean;
     guardHermes?: boolean;
     projectDir?: string;
     projectDirs?: string[];
+    agents?: readonly IntegrationAgent[];
     agentRoots?: Array<{
         agent: string;
         path: string;
@@ -75,6 +96,7 @@ export declare function archiveNativeSkills(inventory: NativeSkillEntry[], optio
     includeUnmanaged?: boolean;
     includeVendor?: boolean;
     allowRootAliases?: boolean;
+    targetManifest?: NativeMigrationTargetManifest;
 }): {
     entries: Array<{
         source: string;
@@ -84,6 +106,11 @@ export declare function archiveNativeSkills(inventory: NativeSkillEntry[], optio
     }>;
     receiptPath?: string;
     rootAliases?: AgentRootAlias[];
+    targetManifest?: {
+        schema: string;
+        digest: string;
+        targetCount: number;
+    };
 };
 /** Run before any prompt context load. Missing ownership or reappearing native
  * discovery files require repair; verified cache availability is not an override. */

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

@@ -1,4 +1,4 @@
-export declare const SUPPORTED_CODEX_HOOK_VERSIONS: readonly ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.155.0"];
+export declare const SUPPORTED_CODEX_HOOK_VERSIONS: readonly ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.155.0", "codex-cli 0.155.1"];
 export interface CodexHookRpc {
     version: string;
     processId?: number;

package/dist/sdk/index.js

@@ -32373,7 +32373,7 @@ var init_event_sink = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.9.1",
+  version: "0.9.3",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -32382,6 +32382,7 @@ var package_default = {
     "skills-serve": "bin/server.js",
     "skills-server": "bin/server.js",
     "skills-worker": "bin/worker.js",
+    "skills-maintenance": "bin/maintenance.js",
     "skills-migrate": "bin/migrate.js"
   },
   exports: {
@@ -32422,7 +32423,7 @@ var package_default = {
   types: "./dist/index.d.ts",
   scripts: {
     clean: "rm -rf bin/ dist/",
-    build: "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
+    build: "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/server/maintenance.ts --outfile ./bin/maintenance.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     "build:js": "rm -rf dist && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     test: "bun test --timeout 30000",
     dev: "bun run ./src/cli/index.tsx",
@@ -40661,6 +40662,35 @@ function treeHash(root2) {
   visit2(root2);
   return hash2.digest("hex");
 }
+function selectNativeMigrationTargets(inventory, manifest) {
+  if (manifest.schema !== "hasna.skills-native-migration-targets.v1" || !/^[0-9a-f]{64}$/.test(manifest.digest) || !Array.isArray(manifest.targets) || manifest.targets.length === 0)
+    throw new Error("Invalid native migration target manifest");
+  const identities = new Set;
+  const selected = [];
+  for (const target of manifest.targets) {
+    const projectRoot = resolve14(target.projectRoot), normalized = relative3(projectRoot, resolve14(projectRoot, target.path));
+    if (!isAbsolute15(target.projectRoot) || projectRoot !== target.projectRoot || !existsSync6(projectRoot) || !lstatSync17(projectRoot).isDirectory())
+      throw new Error(`Native migration target project root must be an existing absolute directory: ${target.projectRoot}`);
+    assertSafePath(projectRoot);
+    if (isAbsolute15(target.path) || target.path.includes("\\") || target.path.includes("\x00") || !normalized || normalized === ".." || normalized.startsWith(`..${sep4}`) || normalized !== target.path || !/^[0-9a-f]{64}$/.test(target.treeSha256))
+      throw new Error(`Invalid native migration target: ${target.path}`);
+    const identity3 = `${target.agent}\x00${projectRoot}\x00${normalized}`;
+    if (identities.has(identity3))
+      throw new Error(`Duplicate native migration target: ${target.path}`);
+    identities.add(identity3);
+    const expected = resolve14(target.projectRoot, target.path);
+    const matches = inventory.filter((entry2) => entry2.agent === target.agent && resolve14(entry2.path) === expected);
+    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.hash !== target.treeSha256 || treeHash(entry.path) !== target.treeSha256)
+      throw new Error(`Native migration target changed after review: ${entry.path}`);
+    selected.push(entry);
+  }
+  return selected;
+}
 function projectAncestorDirectories(projects) {
   const directories = new Set;
   for (const project of projects) {
@@ -40678,10 +40708,12 @@ function projectAncestorDirectories(projects) {
 }
 function inventoryNativeSkills(home = homedir3(), options = {}) {
   const aliases = rootAliases(home, options.allowRootAliases);
-  const roots = ROOTS.map(([agent, path]) => [agent, canonicalAgentPath(join21(home, path), aliases)]);
+  const selectedAgents = options.agents ? new Set(options.agents) : undefined;
+  const rootDefinitions = selectedAgents ? ROOTS.filter(([agent, path]) => selectedAgents.has(agent) || selectedAgents.has("hermes") && agent === "codex" && path === ".agents/skills") : ROOTS;
+  const roots = rootDefinitions.map(([agent, path]) => [agent, canonicalAgentPath(join21(home, path), aliases)]);
   const bridgePaths = Object.values(AGENT_ADAPTERS).map((adapter) => canonicalAgentPath(join21(home, adapter.root, CLI_BRIDGE_NAME), aliases));
   for (const project of projectAncestorDirectories([...options.projectDirs ?? [], ...options.projectDir ? [options.projectDir] : []])) {
-    for (const [agent, path] of ROOTS)
+    for (const [agent, path] of rootDefinitions)
       roots.push([agent, canonicalAgentPath(join21(project, path), aliases)]);
   }
   const entries = [], seen = new Set;
@@ -40937,7 +40969,7 @@ function planAgentIntegration(options) {
     return [agent, { command, profileId: profileId2 }];
   }));
   const discoveries = [...new Set(options.agents)].map((agent) => resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, canonical: (path) => canonicalAgentPath(path, aliases) }));
-  const nativeSkills = inventoryNativeSkills(home, { includeVendor: true, guardHermes: options.agents.includes("hermes"), projectDir: options.projectDir, agentRoots: discoveries.flatMap((binding) => binding.roots.map((path) => ({ agent: binding.agent, path }))), allowRootAliases: options.allowRootAliases });
+  const nativeSkills = inventoryNativeSkills(home, { includeVendor: true, guardHermes: options.agents.includes("hermes"), agents: options.agents, projectDir: options.projectDir, agentRoots: discoveries.flatMap((binding) => binding.roots.map((path) => ({ agent: binding.agent, path }))), allowRootAliases: options.allowRootAliases });
   const changes = [];
   for (const agent of [...new Set(options.agents)]) {
     if (!INTEGRATION_AGENTS.includes(agent))
@@ -41149,12 +41181,13 @@ function archiveNativeSkills(inventory, options) {
     if (!expected || treeHash(entry.path) !== entry.hash || !isOwnedCliBridge(entry.path, [expected]))
       throw new Error(`Skills bridge changed after planning: ${entry.path}`);
   }
-  const selected = inventory.filter((entry) => !entry.bridge && !entry.system && (entry.vendor ? options.includeVendor : entry.managed || options.includeUnmanaged));
+  const selected = options.targetManifest ? selectNativeMigrationTargets(inventory, options.targetManifest) : inventory.filter((entry) => !entry.bridge && !entry.system && (entry.vendor ? options.includeVendor : entry.managed || options.includeUnmanaged));
   for (const entry of selected)
     if (treeHash(entry.path) !== entry.hash)
       throw new Error(`Native skill changed after planning: ${entry.path}`);
+  const targetManifest = options.targetManifest ? { schema: options.targetManifest.schema, digest: options.targetManifest.digest, targetCount: options.targetManifest.targets.length } : undefined;
   if (!selected.length)
-    return { entries: [], ...aliases.length ? { rootAliases: aliases } : {} };
+    return { entries: [], ...targetManifest ? { targetManifest } : {}, ...aliases.length ? { rootAliases: aliases } : {} };
   const operationId = randomUUID3(), archiveRoot = join21(options.dataDir ?? getDataDir(), "migration", operationId, "native"), receiptPath = join21(archiveRoot, "receipt.json");
   const entries = selected.map((entry, index) => ({
     source: entry.vendor ? join21(entry.path, "SKILL.md") : entry.path,
@@ -41163,7 +41196,7 @@ function archiveNativeSkills(inventory, options) {
     ...entry.vendor ? { discoveryOnly: true } : {},
     status: "planned"
   }));
-  const journal = { version: 2, operationId, status: "planned", entries, ...aliases.length ? { rootAliases: aliases } : {} };
+  const journal = { version: 2, operationId, status: "planned", entries, ...targetManifest ? { targetManifest } : {}, ...aliases.length ? { rootAliases: aliases } : {} };
   const moved = [];
   const verifyArchive = (entry) => {
     assertSafePath(entry.archive);
@@ -41257,7 +41290,7 @@ function archiveNativeSkills(inventory, options) {
     } catch {}
     throw new Error(`Native archive failed; inspect the recovery journal at ${receiptPath} before retrying.`, { cause: error });
   }
-  return { entries: entries.map(({ status, conflict, ...entry }) => entry), receiptPath, ...aliases.length ? { rootAliases: aliases } : {} };
+  return { entries: entries.map(({ status, conflict, ...entry }) => entry), receiptPath, ...targetManifest ? { targetManifest } : {}, ...aliases.length ? { rootAliases: aliases } : {} };
 }
 function assertNativeExportAllowed(dataDir2 = getDataDirReadOnly()) {
   if (requiresCliSkillLoading(dataDir2))
@@ -55195,6 +55228,10 @@ class SkillLifecycleConflictError extends Error {
     this.name = "SkillLifecycleConflictError";
   }
 }
+function validOperatorScopeEnrollmentInput(input) {
+  const bounded = (value, max = 256) => typeof value === "string" && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+  return bounded(input.keyId) && bounded(input.stationId) && bounded(input.orgId) && bounded(input.operationId) && bounded(input.manifestDigest, 64) && /^[a-f0-9]{64}$/.test(input.manifestDigest) && bounded(input.operatorJobId) && bounded(input.operatorTaskArn, 512) && input.expectedScopes.length > 0 && input.expectedScopes.length <= 32 && input.expectedScopes.every((scope) => bounded(scope, 128) && /^[a-z][a-z0-9_-]*:[a-z][a-z0-9_-]*$/.test(scope));
+}
 
 // src/lib/revision.ts
 import { createHash as createHash20 } from "crypto";
@@ -55343,6 +55380,54 @@ class SqliteSkillsStore {
     }
     return { kind: "updated", scopes };
   }
+  async enrollPublishScopeByOperator(input) {
+    if (!validOperatorScopeEnrollmentInput(input))
+      return { kind: "invalid" };
+    if (input.expectedScopes.includes("skills:publish"))
+      return { kind: "stale", scopes: input.expectedScopes };
+    const operation = this.get("SELECT org_id, target_id FROM skills_audit_events WHERE action = ? AND operator_operation_id = ? LIMIT 1", ["api_key_scopes_added", input.operationId]);
+    if (operation && (String(operation.org_id) !== input.orgId || String(operation.target_id) !== input.keyId))
+      return { kind: "target_mismatch" };
+    const row = this.get("SELECT id, org_id, name, scopes_json FROM api_keys WHERE id = ? AND revoked_at IS NULL LIMIT 1", [input.keyId]);
+    if (!row)
+      return { kind: "not_found" };
+    if (String(row.org_id) !== input.orgId)
+      return { kind: "target_mismatch" };
+    const current = parseScopes(row.scopes_json);
+    const prior = this.get("SELECT metadata_json FROM skills_audit_events WHERE action = ? AND target_type = ? AND target_id = ? AND json_extract(metadata_json, '$.operator_operation_id') = ? LIMIT 1", ["api_key_scopes_added", "api_key", input.keyId, input.operationId]);
+    if (prior) {
+      try {
+        if (JSON.parse(String(prior.metadata_json)).target_manifest_digest !== input.manifestDigest)
+          return { kind: "target_mismatch" };
+      } catch {
+        return { kind: "target_mismatch" };
+      }
+      return current.includes("skills:publish") ? { kind: "already_applied", scopes: current } : { kind: "stale", scopes: current };
+    }
+    if (current.length !== input.expectedScopes.length || current.some((scope, index) => scope !== input.expectedScopes[index]))
+      return { kind: "stale", scopes: current };
+    const scopes = [...current, "skills:publish"];
+    const tx = this.db.transaction(() => {
+      const changed = this.db.run("UPDATE api_keys SET scopes_json = ? WHERE id = ? AND org_id = ? AND revoked_at IS NULL AND scopes_json = ?", [JSON.stringify(scopes), input.keyId, input.orgId, JSON.stringify(input.expectedScopes)]);
+      if (changed.changes !== 1)
+        return false;
+      this.db.run("INSERT INTO skills_audit_events (org_id, user_id, api_key_id, action, target_type, target_id, operator_operation_id, metadata_json) VALUES (?, NULL, NULL, ?, ?, ?, ?, ?)", [input.orgId, "api_key_scopes_added", "api_key", input.keyId, input.operationId, JSON.stringify({ added: ["skills:publish"], scopes, operator_operation_id: input.operationId, operator_job_id: input.operatorJobId, operator_task_arn: input.operatorTaskArn, target_manifest_digest: input.manifestDigest, station_id: input.stationId })]);
+      return true;
+    });
+    if (!tx()) {
+      const latest = this.get("SELECT scopes_json FROM api_keys WHERE id = ? AND org_id = ? AND revoked_at IS NULL LIMIT 1", [input.keyId, input.orgId]);
+      return { kind: "stale", scopes: latest ? parseScopes(latest.scopes_json) : current };
+    }
+    return { kind: "updated", scopes };
+  }
+  async inspectOperatorScopeTarget(keyId, orgId) {
+    const row = this.get("SELECT org_id, scopes_json FROM api_keys WHERE id = ? AND revoked_at IS NULL LIMIT 1", [keyId]);
+    if (!row)
+      return { kind: "not_found" };
+    if (String(row.org_id) !== orgId)
+      return { kind: "target_mismatch" };
+    return { kind: "found", scopes: parseScopes(row.scopes_json) };
+  }
   async createRun(input) {
     if (input.idempotencyKey) {
       const existing = this.get("SELECT * FROM skills_runs WHERE org_id = ? AND idempotency_key = ? LIMIT 1", [input.principal.orgId, input.idempotencyKey]);
@@ -62590,6 +62675,7 @@ class MemorySkillsStore {
   bundles = new Map;
   versions = new Map;
   pins = new Map;
+  operatorEnrollments = new Map;
   constructor(apiKeys = []) {
     for (const key of apiKeys)
       this.addApiKey(key.token, key.principal);
@@ -62619,6 +62705,41 @@ class MemorySkillsStore {
     }
     return { kind: "not_found" };
   }
+  async enrollPublishScopeByOperator(input) {
+    if (!validOperatorScopeEnrollmentInput(input))
+      return { kind: "invalid" };
+    const previous = this.operatorEnrollments.get(input.operationId);
+    if (previous) {
+      if (previous.keyId !== input.keyId || previous.manifestDigest !== input.manifestDigest)
+        return { kind: "target_mismatch" };
+      for (const target of this.apiKeys.values()) {
+        if (target.apiKeyId === input.keyId && target.orgId === input.orgId && target.scopes.includes("skills:publish")) {
+          return { kind: "already_applied", scopes: [...target.scopes] };
+        }
+      }
+      return { kind: "stale", scopes: [] };
+    }
+    for (const [hash3, target] of this.apiKeys) {
+      if (target.apiKeyId !== input.keyId || target.orgId !== input.orgId)
+        continue;
+      if (target.scopes.length !== input.expectedScopes.length || target.scopes.some((scope2, index) => scope2 !== input.expectedScopes[index])) {
+        return { kind: "stale", scopes: [...target.scopes] };
+      }
+      const scopes = target.scopes.includes("skills:publish") ? [...target.scopes] : [...target.scopes, "skills:publish"];
+      this.apiKeys.set(hash3, { ...target, scopes });
+      this.operatorEnrollments.set(input.operationId, { keyId: input.keyId, manifestDigest: input.manifestDigest });
+      return { kind: "updated", scopes };
+    }
+    return { kind: "not_found" };
+  }
+  async inspectOperatorScopeTarget(keyId, orgId) {
+    for (const target of this.apiKeys.values()) {
+      if (target.apiKeyId !== keyId)
+        continue;
+      return target.orgId === orgId ? { kind: "found", scopes: [...target.scopes] } : { kind: "target_mismatch" };
+    }
+    return { kind: "not_found" };
+  }
   async createRun(input) {
     const idemKey = input.idempotencyKey?.trim();
     const idemMapKey = idemKey ? `${input.principal.orgId}:${idemKey}` : undefined;
@@ -63033,24 +63154,98 @@ class PostgresSkillsStore {
       if (current.length !== expectedScopes.length || current.some((scope2, index) => scope2 !== expectedScopes[index])) {
         return { kind: "stale", scopes: current };
       }
-      const scopes = [...current, ...addScopes.filter((scope2) => !current.includes(scope2))];
-      const updated = await tx`
-        UPDATE api_keys SET scopes_json = ${JSON.stringify(scopes)}::jsonb
-        WHERE id = ${keyId} AND org_id = ${actor.orgId} AND revoked_at IS NULL
-          AND scopes_json = ${JSON.stringify(expectedScopes)}::jsonb
-        RETURNING scopes_json
-      `;
+      const updated = await this.casUpdateApiKeyScopes(tx, keyId, actor.orgId, expectedScopes, addScopes);
       if (!updated[0]) {
         const latest = await tx`SELECT scopes_json FROM api_keys WHERE id = ${keyId} AND org_id = ${actor.orgId} AND revoked_at IS NULL LIMIT 1`;
         return { kind: "stale", scopes: latest[0] ? parseJsonArray(latest[0].scopes_json) : current };
       }
       await tx`
         INSERT INTO skills_audit_events (org_id, user_id, api_key_id, action, target_type, target_id, metadata_json)
-        VALUES (${actor.orgId}, ${actor.userId}, ${actor.apiKeyId}, ${"api_key_scopes_added"}, ${"api_key"}, ${keyId}, ${JSON.stringify({ added: addScopes, scopes })}::jsonb)
+        VALUES (${actor.orgId}, ${actor.userId}, ${actor.apiKeyId}, ${"api_key_scopes_added"}, ${"api_key"}, ${keyId}, ${JSON.stringify({ added: addScopes, scopes: parseJsonArray(updated[0].scopes_json) })}::jsonb)
+      `;
+      return { kind: "updated", scopes: parseJsonArray(updated[0].scopes_json) };
+    });
+  }
+  async casUpdateApiKeyScopes(tx, keyId, orgId, expectedScopes, addScopes) {
+    const current = expectedScopes;
+    const scopes = [...current, ...addScopes.filter((scope2) => !current.includes(scope2))];
+    return tx`
+      UPDATE api_keys SET scopes_json = ${JSON.stringify(scopes)}::jsonb
+      WHERE id = ${keyId} AND org_id = ${orgId} AND revoked_at IS NULL
+        AND scopes_json = ${JSON.stringify(expectedScopes)}::jsonb
+      RETURNING scopes_json
+    `;
+  }
+  async enrollPublishScopeByOperator(input) {
+    if (!validOperatorScopeEnrollmentInput(input))
+      return { kind: "invalid" };
+    if (input.expectedScopes.includes("skills:publish"))
+      return { kind: "stale", scopes: input.expectedScopes };
+    return this.sql.begin(async (tx) => {
+      const operation = await tx`
+        SELECT org_id, target_id FROM skills_audit_events
+        WHERE action = ${"api_key_scopes_added"} AND operator_operation_id = ${input.operationId}
+        LIMIT 1
+      `;
+      if (operation[0] && (String(operation[0].org_id) !== input.orgId || String(operation[0].target_id) !== input.keyId))
+        return { kind: "target_mismatch" };
+      const rows = await tx`
+        SELECT id, org_id, name, scopes_json FROM api_keys
+        WHERE id = ${input.keyId} AND revoked_at IS NULL
+        FOR UPDATE
+      `;
+      const row = rows[0];
+      if (!row)
+        return { kind: "not_found" };
+      if (String(row.org_id) !== input.orgId)
+        return { kind: "target_mismatch" };
+      const current = parseJsonArray(row.scopes_json);
+      const prior = await tx`
+        SELECT metadata_json, metadata_json->>'target_manifest_digest' AS manifest_digest FROM skills_audit_events
+        WHERE action = ${"api_key_scopes_added"} AND target_type = ${"api_key"} AND target_id = ${input.keyId}
+          AND operator_operation_id = ${input.operationId}
+        LIMIT 1
+      `;
+      if (prior[0]) {
+        const priorMetadata = typeof prior[0].metadata_json === "string" ? JSON.parse(prior[0].metadata_json) : prior[0].metadata_json;
+        const priorDigest = prior[0].manifest_digest ?? priorMetadata?.target_manifest_digest;
+        if (String(priorDigest) !== input.manifestDigest)
+          return { kind: "target_mismatch" };
+        if (!current.includes("skills:publish"))
+          return { kind: "stale", scopes: current };
+        return { kind: "already_applied", scopes: current };
+      }
+      if (current.length !== input.expectedScopes.length || current.some((scope2, index) => scope2 !== input.expectedScopes[index])) {
+        return { kind: "stale", scopes: current };
+      }
+      const updated = await this.casUpdateApiKeyScopes(tx, input.keyId, input.orgId, input.expectedScopes, ["skills:publish"]);
+      if (!updated[0])
+        return { kind: "stale", scopes: current };
+      const scopes = parseJsonArray(updated[0].scopes_json);
+      await tx`
+        INSERT INTO skills_audit_events (org_id, user_id, api_key_id, action, target_type, target_id, operator_operation_id, metadata_json)
+        VALUES (${input.orgId}, NULL, NULL, ${"api_key_scopes_added"}, ${"api_key"}, ${input.keyId}, ${input.operationId}, ${JSON.stringify({
+        added: ["skills:publish"],
+        scopes,
+        operator_operation_id: input.operationId,
+        operator_job_id: input.operatorJobId,
+        operator_task_arn: input.operatorTaskArn,
+        target_manifest_digest: input.manifestDigest,
+        station_id: input.stationId
+      })}::jsonb)
       `;
       return { kind: "updated", scopes };
     });
   }
+  async inspectOperatorScopeTarget(keyId, orgId) {
+    const rows = await this.sql`SELECT org_id, scopes_json FROM api_keys WHERE id = ${keyId} AND revoked_at IS NULL LIMIT 1`;
+    const row = rows[0];
+    if (!row)
+      return { kind: "not_found" };
+    if (String(row.org_id) !== orgId)
+      return { kind: "target_mismatch" };
+    return { kind: "found", scopes: parseJsonArray(row.scopes_json) };
+  }
   async withContext(orgId, worker, fn) {
     return this.sql.begin(async (tx) => {
       await tx`SELECT set_config('app.skills_org_id', ${orgId ?? ""}, true)`;

package/dist/server/maintenance-entry.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerMaintenance(parent: Command): void;

package/dist/server/maintenance.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/sqlite-store.d.ts

@@ -15,7 +15,7 @@ import { SqliteExecutionGrantStore } from "./execution-grant-store.js";
  */
 import { Database } from "bun:sqlite";
 import { SqliteSkillSelectionStore } from "./selection-store.js";
-import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillVersion, ApiKeyScopeUpdateResult, ServerSkillRecord, SkillLifecyclePatch, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
+import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillVersion, ApiKeyScopeUpdateResult, OperatorScopeEnrollmentInput, OperatorScopeEnrollmentResult, OperatorScopeTargetSnapshot, ServerSkillRecord, SkillLifecyclePatch, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
 export interface SqliteStoreOptions {
     /** Apply pending migrations on open. Default true - it is what makes zero-config work. */
     migrate?: boolean;
@@ -53,6 +53,8 @@ export declare class SqliteSkillsStore implements SkillsProductStore {
     ensureBootstrapApiKey(token: string, principal?: Partial<ApiPrincipal>): Promise<void>;
     authenticateApiKeyHash(hash: string): Promise<ApiPrincipal | null>;
     updateApiKeyScopes(actor: ApiPrincipal, keyId: string, expectedScopes: string[], addScopes: string[]): Promise<ApiKeyScopeUpdateResult>;
+    enrollPublishScopeByOperator(input: OperatorScopeEnrollmentInput): Promise<OperatorScopeEnrollmentResult>;
+    inspectOperatorScopeTarget(keyId: string, orgId: string): Promise<OperatorScopeTargetSnapshot>;
     createRun(input: CreateRunInput): Promise<ServerRunRecord>;
     listRuns(principal: ApiPrincipal, limit: number): Promise<ServerRunRecord[]>;
     getRun(principal: ApiPrincipal, id: string): Promise<ServerRunRecord | null>;

package/dist/server/store.d.ts

@@ -1,6 +1,6 @@
 import { MemoryExecutionGrantStore, PostgresExecutionGrantStore } from "./execution-grant-store.js";
 import { MemorySkillSelectionStore, PostgresSkillSelectionStore } from "./selection-store.js";
-import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, ServerSkillVersion, ApiKeyScopeUpdateResult, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
+import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, ServerSkillVersion, ApiKeyScopeUpdateResult, OperatorScopeEnrollmentInput, OperatorScopeEnrollmentResult, OperatorScopeTargetSnapshot, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
 import { type SkillLifecyclePatch } from "./types.js";
 import { type SqliteStoreOptions } from "./sqlite-store.js";
 export declare function createArtifactId(): string;
@@ -38,6 +38,7 @@ export declare class MemorySkillsStore implements SkillsProductStore {
     private bundles;
     private versions;
     private pins;
+    private operatorEnrollments;
     constructor(apiKeys?: Array<{
         token: string;
         principal?: Partial<ApiPrincipal>;
@@ -46,6 +47,8 @@ export declare class MemorySkillsStore implements SkillsProductStore {
     ensureBootstrapApiKey(token: string, principal?: Partial<ApiPrincipal>): Promise<void>;
     authenticateApiKeyHash(hash: string): Promise<ApiPrincipal | null>;
     updateApiKeyScopes(actor: ApiPrincipal, keyId: string, expectedScopes: string[], addScopes: string[]): Promise<ApiKeyScopeUpdateResult>;
+    enrollPublishScopeByOperator(input: OperatorScopeEnrollmentInput): Promise<OperatorScopeEnrollmentResult>;
+    inspectOperatorScopeTarget(keyId: string, orgId: string): Promise<OperatorScopeTargetSnapshot>;
     createRun(input: CreateRunInput): Promise<ServerRunRecord>;
     listRuns(principal: ApiPrincipal, limit: number): Promise<ServerRunRecord[]>;
     getRun(principal: ApiPrincipal, runId: string): Promise<ServerRunRecord | null>;
@@ -122,6 +125,9 @@ export declare class PostgresSkillsStore implements SkillsProductStore {
     ensureBootstrapApiKey(token: string, principal?: Partial<ApiPrincipal>): Promise<void>;
     authenticateApiKeyHash(hash: string): Promise<ApiPrincipal | null>;
     updateApiKeyScopes(actor: ApiPrincipal, keyId: string, expectedScopes: string[], addScopes: string[]): Promise<ApiKeyScopeUpdateResult>;
+    private casUpdateApiKeyScopes;
+    enrollPublishScopeByOperator(input: OperatorScopeEnrollmentInput): Promise<OperatorScopeEnrollmentResult>;
+    inspectOperatorScopeTarget(keyId: string, orgId: string): Promise<OperatorScopeTargetSnapshot>;
     /**
      * Run a callback under an RLS tenant or worker context, on one pooled
      * connection, for the duration of one transaction only.