@hasna/skills 0.9.2 → 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.2",
+  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",
@@ -15784,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;
@@ -16043,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))

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

@@ -65,6 +65,7 @@ export declare function inventoryNativeSkills(home?: string, options?: {
     guardHermes?: boolean;
     projectDir?: string;
     projectDirs?: string[];
+    agents?: readonly IntegrationAgent[];
     agentRoots?: Array<{
         agent: string;
         path: string;

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.2",
+  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",
@@ -40707,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;
@@ -40966,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))
@@ -55225,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";
@@ -55373,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]);
@@ -62620,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);
@@ -62649,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;
@@ -63063,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.

package/dist/server/types.d.ts

@@ -69,6 +69,47 @@ export type ApiKeyScopeUpdateResult = {
     kind: "stale";
     scopes: string[];
 };
+/**
+ * A maintenance task's provenance is deliberately separate from ApiPrincipal.
+ * An ECS task is not a user and must never be represented by impersonating an
+ * API key, user id, or role in the audit row.
+ */
+export interface OperatorScopeEnrollmentInput {
+    keyId: string;
+    stationId: string;
+    orgId: string;
+    expectedScopes: string[];
+    operationId: string;
+    manifestDigest: string;
+    operatorJobId: string;
+    operatorTaskArn: string;
+}
+export declare function validOperatorScopeEnrollmentInput(input: OperatorScopeEnrollmentInput): boolean;
+export declare function validOperatorScopeList(scopes: unknown): scopes is string[];
+export type OperatorScopeEnrollmentResult = {
+    kind: "updated";
+    scopes: string[];
+} | {
+    kind: "already_applied";
+    scopes: string[];
+} | {
+    kind: "not_found";
+} | {
+    kind: "target_mismatch";
+} | {
+    kind: "invalid";
+} | {
+    kind: "stale";
+    scopes: string[];
+};
+export type OperatorScopeTargetSnapshot = {
+    kind: "not_found";
+} | {
+    kind: "target_mismatch";
+} | {
+    kind: "found";
+    scopes: string[];
+};
 export interface ServerRunRecord {
     id: string;
     orgId: string;
@@ -339,6 +380,9 @@ export interface SkillsProductStore {
     authenticateApiKeyHash(hash: string): Promise<ApiPrincipal | null>;
     /** Guarded metadata-only scope admission for an existing key. */
     updateApiKeyScopes?(actor: ApiPrincipal, keyId: string, expectedScopes: string[], addScopes: string[]): Promise<ApiKeyScopeUpdateResult>;
+    /** Add only skills:publish to an existing key from a protected maintenance task. */
+    enrollPublishScopeByOperator?(input: OperatorScopeEnrollmentInput): Promise<OperatorScopeEnrollmentResult>;
+    inspectOperatorScopeTarget?(keyId: string, orgId: string): Promise<OperatorScopeTargetSnapshot>;
     ensureBootstrapApiKey?(token: string, principal?: Partial<ApiPrincipal>): Promise<void>;
     createRun(input: CreateRunInput): Promise<ServerRunRecord>;
     listRuns(principal: ApiPrincipal, limit: number): Promise<ServerRunRecord[]>;

package/migrations/postgres/0005_operator_scope_receipts.sql

@@ -0,0 +1,9 @@
+ALTER TABLE skills_audit_events ADD COLUMN operator_operation_id text;
+
+-- One operation may be retried, but it must produce one immutable receipt per
+-- tenant/key.  The partial expression index makes that property atomic under
+-- concurrent maintenance tasks; application pre-reads are not the guard.
+CREATE UNIQUE INDEX IF NOT EXISTS skills_operator_scope_receipt_idx
+  ON skills_audit_events (operator_operation_id)
+  WHERE action = 'api_key_scopes_added'
+    AND operator_operation_id IS NOT NULL;

package/migrations/sqlite/0005_operator_scope_receipts.sql

@@ -0,0 +1,7 @@
+ALTER TABLE skills_audit_events ADD COLUMN operator_operation_id text;
+
+-- SQLite equivalent of the PostgreSQL operation-receipt uniqueness fence.
+CREATE UNIQUE INDEX IF NOT EXISTS skills_operator_scope_receipt_idx
+  ON skills_audit_events (operator_operation_id)
+  WHERE action = 'api_key_scopes_added'
+    AND operator_operation_id IS NOT NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
     "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": {
@@ -49,7 +50,7 @@
   "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",