snipara-companion 3.4.0 → 3.4.1

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 Release notes for `snipara-companion`, newest first.
 
+## New In 3.4.1
+
+- Declares provider API keys by environment-variable name and supports
+  `authorization` or `x-api-key` headers without persisting secret values.
+- Resolves declared Codex and Claude CLI workers to explicit native adapters;
+  unsupported generic CLI profiles fail closed.
+- Preserves opt-in local routing behavior while forwarding provider auth metadata
+  to the orchestrator catalog.
+
 ## New In 3.4.0
 
 - Adds repeatable `workers execute --output-fragment` contracts.

package/dist/index.d.ts

@@ -4478,6 +4478,8 @@ interface LocalWorkerDeclaration {
     endpointType: "local";
     provider: string;
     baseUrl: string;
+    apiKeyEnv?: string;
+    apiKeyHeader?: "authorization" | "x-api-key";
     command?: string;
     model?: string;
     preferModel?: string;
@@ -4496,11 +4498,16 @@ interface LocalWorkersConfig {
 interface LocalWorkerRoutingDefaults {
     worker: LocalWorkerDeclaration;
     routeLocalWorkers: true;
+    routingLocalTransport: "openai_http" | "cli";
+    routingLocalAdapter?: "codex_app_server" | "claude_cli";
+    routingLocalCommand?: string;
     routingWorkerRole: string;
     routingLocalBaseUrl: string;
     routingLocalModel?: string;
     routingLocalPreferModel?: string;
     routingLocalProvider: string;
+    routingLocalApiKeyEnv?: string;
+    routingLocalApiKeyHeader?: "authorization" | "x-api-key";
     routingPreferredEndpoints: string[];
     routingAllowedEndpoints: string[];
     plannerRetainsReasoning: true;
@@ -4520,6 +4527,8 @@ interface LocalWorkerAddOptions {
     json?: boolean;
     transport?: "openai_http" | "cli";
     command?: string;
+    apiKeyEnv?: string;
+    apiKeyHeader?: "authorization" | "x-api-key";
 }
 interface LocalWorkerStatusOptions {
     json?: boolean;
@@ -4542,6 +4551,8 @@ interface LocalWorkerProbeOptions {
     writeScope?: string[];
     reasoning?: "low" | "medium" | "high";
     contextWindow?: number;
+    apiKeyEnv?: string;
+    apiKeyHeader?: "authorization" | "x-api-key";
     json?: boolean;
 }
 declare function workersLocalAddCommand(options: LocalWorkerAddOptions): void;

package/dist/index.js

@@ -9755,7 +9755,9 @@ function normalizeWorkerProfileTransport(value) {
       baseUrl,
       ...stringValue(value.model) ? { model: stringValue(value.model) } : {},
       ...stringValue(value.preferModel) ? { preferModel: stringValue(value.preferModel) } : {},
-      ...stringValue(value.provider) ? { provider: stringValue(value.provider) } : {}
+      ...stringValue(value.provider) ? { provider: stringValue(value.provider) } : {},
+      ...safeEnvironmentVariableName(value.apiKeyEnv) ? { apiKeyEnv: safeEnvironmentVariableName(value.apiKeyEnv) } : {},
+      ...value.apiKeyHeader === "authorization" || value.apiKeyHeader === "x-api-key" ? { apiKeyHeader: value.apiKeyHeader } : {}
     };
   }
   if (kind === "cli") {
@@ -9897,6 +9899,10 @@ function numberValue(value) {
 function booleanValue(value) {
   return value === true;
 }
+function safeEnvironmentVariableName(value) {
+  const normalized = stringValue(value);
+  return normalized && /^[A-Za-z_][A-Za-z0-9_]*$/.test(normalized) ? normalized : void 0;
+}
 function stringValue(value) {
   if (value === null || value === void 0) {
     return void 0;
@@ -19627,6 +19633,9 @@ function workersLocalAddCommand(options) {
   printKeyValue("Role:", result.worker.workerRole);
   printKeyValue("Provider:", result.worker.provider);
   printKeyValue("Base URL:", result.worker.baseUrl);
+  if (result.worker.apiKeyEnv) {
+    printKeyValue("API key env:", result.worker.apiKeyEnv);
+  }
   if (result.worker.model) {
     printKeyValue("Model:", result.worker.model);
   } else if (result.worker.preferModel) {
@@ -19718,7 +19727,9 @@ function workersLocalProbeCommand(options) {
     capabilities: normalizeStringList3(options.capabilities),
     writeScope: normalizeStringList3(options.writeScope),
     model,
-    preferModel
+    preferModel,
+    apiKeyEnv: options.apiKeyEnv,
+    apiKeyHeader: options.apiKeyHeader
   });
   const catalogContextWindow = resolveContextWindowFromCatalog(catalog, model, preferModel);
   const contextWindow = normalizeContextWindow(
@@ -19737,7 +19748,9 @@ function workersLocalProbeCommand(options) {
         baseUrl,
         ...model ? { model } : {},
         ...preferModel ? { preferModel } : {},
-        provider
+        provider,
+        ...options.apiKeyEnv ? { apiKeyEnv: options.apiKeyEnv } : {},
+        ...options.apiKeyHeader ? { apiKeyHeader: options.apiKeyHeader } : {}
       },
       capabilities: {
         roles: [role],
@@ -19891,7 +19904,26 @@ function resolveLocalWorkerRoutingDefaults(options = {}) {
     throw new Error(`Local worker ${requestedId} is not declared.`);
   }
   if (!worker.baseUrl || worker.baseUrl === "cli://command") {
-    return null;
+    const command = worker.command?.toLowerCase() ?? "";
+    const adapter = command.includes("codex") ? "codex_app_server" : command.includes("claude") ? "claude_cli" : void 0;
+    if (!adapter) {
+      throw new Error(
+        `CLI worker ${worker.id} is not mapped to a supported native adapter; use a Codex or Claude command.`
+      );
+    }
+    return {
+      worker,
+      routeLocalWorkers: true,
+      routingLocalTransport: "cli",
+      routingLocalBaseUrl: "cli://command",
+      routingLocalAdapter: adapter,
+      routingLocalCommand: worker.command,
+      routingWorkerRole: worker.workerRole,
+      routingLocalProvider: worker.provider,
+      routingPreferredEndpoints: ["local"],
+      routingAllowedEndpoints: ["local"],
+      plannerRetainsReasoning: true
+    };
   }
   if (!worker.model && !worker.preferModel) {
     const hasCatalogHint = true;
@@ -19900,11 +19932,14 @@ function resolveLocalWorkerRoutingDefaults(options = {}) {
   return {
     worker,
     routeLocalWorkers: true,
+    routingLocalTransport: "openai_http",
     routingWorkerRole: worker.workerRole,
     routingLocalBaseUrl: worker.baseUrl,
     ...worker.model ? { routingLocalModel: worker.model } : {},
     ...worker.preferModel ? { routingLocalPreferModel: worker.preferModel } : {},
     routingLocalProvider: worker.provider,
+    ...worker.apiKeyEnv ? { routingLocalApiKeyEnv: worker.apiKeyEnv } : {},
+    ...worker.apiKeyHeader ? { routingLocalApiKeyHeader: worker.apiKeyHeader } : {},
     routingPreferredEndpoints: ["local"],
     routingAllowedEndpoints: ["local"],
     plannerRetainsReasoning: true
@@ -20012,7 +20047,9 @@ function normalizeWorkerProfileRecord(value) {
       transport: {
         ...transport,
         baseUrl,
-        provider: normalizeProvider(transport.provider ?? "lm-studio")
+        provider: normalizeProvider(transport.provider ?? "lm-studio"),
+        ...transport.apiKeyEnv ? { apiKeyEnv: transport.apiKeyEnv } : {},
+        ...transport.apiKeyHeader ? { apiKeyHeader: transport.apiKeyHeader } : {}
       }
     };
   }
@@ -20047,7 +20084,9 @@ function toProfileFromLegacyWorker(worker) {
       baseUrl: worker.baseUrl,
       ...worker.model ? { model: worker.model } : {},
       ...worker.preferModel ? { preferModel: worker.preferModel } : {},
-      provider: worker.provider
+      provider: worker.provider,
+      ...worker.apiKeyEnv ? { apiKeyEnv: worker.apiKeyEnv } : {},
+      ...worker.apiKeyHeader ? { apiKeyHeader: worker.apiKeyHeader } : {}
     },
     capabilities: {
       roles: [normalizeWorkerRole(worker.workerRole)],
@@ -20090,6 +20129,8 @@ function toLocalWorkerDeclaration(profile) {
     endpointType: "local",
     provider: normalizeProvider(profile.transport.provider ?? "lm-studio"),
     baseUrl: profile.transport.baseUrl,
+    ...profile.transport.apiKeyEnv ? { apiKeyEnv: profile.transport.apiKeyEnv } : {},
+    ...profile.transport.apiKeyHeader ? { apiKeyHeader: profile.transport.apiKeyHeader } : {},
     ...stringValue6(profile.transport.model) ? { model: stringValue6(profile.transport.model) } : {},
     ...stringValue6(profile.transport.preferModel) && !profile.transport.model ? { preferModel: stringValue6(profile.transport.preferModel) } : {},
     capabilities: normalizeWorkerCapabilities(profile.capabilities.roles),
@@ -20195,6 +20236,12 @@ function runOrchestratorLocalCatalog(options) {
   if (options.preferModel) {
     args.push("--prefer-model", options.preferModel);
   }
+  if (options.apiKeyEnv) {
+    args.push("--api-key-env", options.apiKeyEnv);
+  }
+  if (options.apiKeyHeader) {
+    args.push("--api-key-header", options.apiKeyHeader);
+  }
   try {
     const result = (0, import_node_child_process9.execFileSync)("snipara-orchestrator", args, {
       encoding: "utf8",
@@ -20330,12 +20377,15 @@ function normalizeWorkerTransport(options) {
   const baseUrl = normalizeBaseUrl(options.baseUrl ?? "http://127.0.0.1:1234");
   const model = stringValue6(options.model);
   const preferModel = stringValue6(options.preferModel);
+  const apiKeyEnv = normalizeApiKeyEnvironmentName(options.apiKeyEnv);
   return {
     kind: "openai_http",
     baseUrl,
     ...model ? { model } : {},
     ...preferModel ? { preferModel } : {},
-    provider: normalizeProvider(stringValue6(options.provider) ?? "lm-studio")
+    provider: normalizeProvider(stringValue6(options.provider) ?? "lm-studio"),
+    ...apiKeyEnv ? { apiKeyEnv } : {},
+    ...options.apiKeyHeader ? { apiKeyHeader: options.apiKeyHeader } : {}
   };
 }
 function normalizeProvider(value) {
@@ -20357,6 +20407,8 @@ function normalizeLegacyWorkerDeclaration(value) {
     endpointType: "local",
     provider: normalizeProvider(stringValue6(value.provider) ?? "lm-studio"),
     baseUrl,
+    ...stringValue6(value.apiKeyEnv) ? { apiKeyEnv: stringValue6(value.apiKeyEnv) } : {},
+    ...value.apiKeyHeader === "authorization" || value.apiKeyHeader === "x-api-key" ? { apiKeyHeader: value.apiKeyHeader } : {},
     ...stringValue6(value.model) ? { model: stringValue6(value.model) } : {},
     ...stringValue6(value.preferModel) ? { preferModel: stringValue6(value.preferModel) } : {},
     capabilities: normalizeStringList3(value.capabilities).length > 0 ? normalizeStringList3(value.capabilities) : defaultCapabilitiesForWorker(normalizeWorkerRole(value.workerRole)),
@@ -20434,6 +20486,16 @@ function stringValue6(value) {
   const stringified = String(value).trim();
   return stringified || void 0;
 }
+function normalizeApiKeyEnvironmentName(value) {
+  const normalized = stringValue6(value);
+  if (!normalized) {
+    return void 0;
+  }
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(normalized)) {
+    throw new Error("API key env must be a shell-safe environment variable name.");
+  }
+  return normalized;
+}
 function isRecord10(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -25425,7 +25487,7 @@ function shouldResolveAdaptiveRoutingLocally(options, routing) {
   return preferred.includes("local") || allowed.length === 0 || allowed.includes("local");
 }
 function hasLocalRoutingRequest(options) {
-  return options.routeLocalWorkers === true || Boolean(options.routingLocalWorker) || Boolean(options.routingLocalBaseUrl) || Boolean(options.routingLocalModel) || Boolean(options.routingLocalPreferModel) || Boolean(options.routingLocalProvider) || normalizeRoutingEndpointTypes(options.routingPreferredEndpoints).includes("local") || normalizeRoutingEndpointTypes(options.routingAllowedEndpoints).includes("local");
+  return options.routeLocalWorkers === true || Boolean(options.routingLocalWorker) || Boolean(options.routingLocalBaseUrl) || Boolean(options.routingLocalModel) || Boolean(options.routingLocalPreferModel) || Boolean(options.routingLocalProvider) || Boolean(options.routingLocalApiKeyEnv) || normalizeRoutingEndpointTypes(options.routingPreferredEndpoints).includes("local") || normalizeRoutingEndpointTypes(options.routingAllowedEndpoints).includes("local");
 }
 function applyLocalWorkerRoutingDefaults(options, defaults) {
   if (!defaults) {
@@ -25434,6 +25496,9 @@ function applyLocalWorkerRoutingDefaults(options, defaults) {
   return {
     ...options,
     routeLocalWorkers: options.routeLocalWorkers ?? defaults.routeLocalWorkers,
+    routingLocalTransport: options.routingLocalTransport ?? defaults.routingLocalTransport,
+    routingLocalAdapter: options.routingLocalAdapter ?? defaults.routingLocalAdapter,
+    routingLocalCommand: options.routingLocalCommand ?? defaults.routingLocalCommand,
     routingWorkerRole: options.routingWorkerRole ?? defaults.routingWorkerRole,
     routingPreferredEndpoints: options.routingPreferredEndpoints && options.routingPreferredEndpoints.length > 0 ? options.routingPreferredEndpoints : defaults.routingPreferredEndpoints,
     routingAllowedEndpoints: options.routingAllowedEndpoints && options.routingAllowedEndpoints.length > 0 ? options.routingAllowedEndpoints : defaults.routingAllowedEndpoints,
@@ -25441,6 +25506,8 @@ function applyLocalWorkerRoutingDefaults(options, defaults) {
     routingLocalModel: options.routingLocalModel ?? defaults.routingLocalModel,
     routingLocalPreferModel: options.routingLocalPreferModel ?? defaults.routingLocalPreferModel,
     routingLocalProvider: options.routingLocalProvider ?? defaults.routingLocalProvider,
+    routingLocalApiKeyEnv: options.routingLocalApiKeyEnv ?? defaults.routingLocalApiKeyEnv,
+    routingLocalApiKeyHeader: options.routingLocalApiKeyHeader ?? defaults.routingLocalApiKeyHeader,
     plannerRetainsReasoning: options.plannerRetainsReasoning ?? defaults.plannerRetainsReasoning
   };
 }
@@ -25455,6 +25522,67 @@ function runOrchestratorJsonCommand(args, cwd = process.cwd()) {
 }
 function enrichAdaptiveRoutingWithLocalOrchestrator(routing, options, cwd = process.cwd()) {
   try {
+    if (options.routingLocalTransport === "cli") {
+      const candidateId = options.routingLocalAdapter ?? options.routingLocalCommand ?? "declared-cli";
+      const candidate = {
+        candidateId,
+        workerClass: routing.requirements.workerRole,
+        catalogSource: "declared_cli_worker",
+        endpointType: "local",
+        workerRoles: [routing.requirements.workerRole],
+        capabilities: routing.requirements.capabilities ?? [],
+        writeScope: routing.requirements.writeScope ?? [],
+        reasoning: routing.requirements.reasoning,
+        speed: "normal",
+        cost: "balanced",
+        contextBudget: routing.requirements.contextBudget,
+        qualityScore: null,
+        isAvailable: true,
+        requiresApiKey: false,
+        metadata: {
+          adapter: options.routingLocalAdapter,
+          command: options.routingLocalCommand
+        }
+      };
+      const resolution2 = normalizeAdaptiveRoutingResolution(
+        runOrchestratorJsonCommand(
+          [
+            "route",
+            "--dry-run",
+            "--json",
+            "--work-profile-json",
+            JSON.stringify(routing.workProfile),
+            "--requirements-json",
+            JSON.stringify(routing.requirements),
+            "--candidate-json",
+            JSON.stringify(candidate)
+          ],
+          cwd
+        )
+      );
+      return {
+        ...routing,
+        gateway: {
+          source: "local_orchestrator",
+          success: true,
+          resolutionStatus: resolution2?.status ?? "resolved",
+          candidateCount: 1,
+          fallback: "main_agent",
+          warnings: []
+        },
+        runtimeCatalog: {
+          source: "declared_cli_worker",
+          candidates: [candidate],
+          workerEndpoints: {
+            [candidateId]: {
+              adapter: options.routingLocalAdapter,
+              command: options.routingLocalCommand
+            }
+          }
+        },
+        resolution: resolution2
+      };
+    }
     const catalogArgs = [
       "local-model-catalog",
       "--json",
@@ -25477,6 +25605,12 @@ function enrichAdaptiveRoutingWithLocalOrchestrator(routing, options, cwd = proc
     if (options.routingLocalProvider) {
       catalogArgs.push("--provider", options.routingLocalProvider);
     }
+    if (options.routingLocalApiKeyEnv) {
+      catalogArgs.push("--api-key-env", options.routingLocalApiKeyEnv);
+    }
+    if (options.routingLocalApiKeyHeader) {
+      catalogArgs.push("--api-key-header", options.routingLocalApiKeyHeader);
+    }
     const runtimeCatalog = normalizeAdaptiveRoutingCatalog(
       runOrchestratorJsonCommand(catalogArgs, cwd)
     );
@@ -27367,7 +27501,7 @@ async function workflowRunCommand(options) {
 }
 function shouldBuildAdaptiveRouting(options) {
   return Boolean(
-    options.adaptiveRoutingDryRun || options.routeLocalWorkers || options.routingLocalWorker || options.routingWorkerRole || options.routingPreferredEndpoints?.length || options.routingAllowedEndpoints?.length || options.routingLocalBaseUrl || options.routingLocalModel || options.routingLocalPreferModel || options.routingLocalProvider || options.plannerRetainsReasoning
+    options.adaptiveRoutingDryRun || options.routeLocalWorkers || options.routingLocalWorker || options.routingWorkerRole || options.routingPreferredEndpoints?.length || options.routingAllowedEndpoints?.length || options.routingLocalBaseUrl || options.routingLocalModel || options.routingLocalPreferModel || options.routingLocalProvider || options.routingLocalApiKeyEnv || options.plannerRetainsReasoning
   );
 }
 function buildWorkflowAdaptiveRouting(options, policy = null, intentWarnings = []) {
@@ -38817,6 +38951,12 @@ workflow.command("run").description("Run a LITE/STANDARD/FULL/orchestrate workfl
   "--routing-local-prefer-model <text>",
   "Prefer a local /v1/models entry containing this text during worker routing"
 ).option("--routing-local-provider <provider>", "Provider label for local worker routing").option(
+  "--routing-local-api-key-env <env>",
+  "Environment variable containing the local/remote provider API key"
+).option(
+  "--routing-local-api-key-header <header>",
+  "Provider API key header: authorization or x-api-key"
+).option(
   "--planner-retains-reasoning",
   "Mark the main planner as retaining deep reasoning while the worker executes scoped work"
 ).option("--write-plan-file <file>", "Write the generated FULL-mode plan as workflow JSON").option(
@@ -38844,6 +38984,8 @@ workflow.command("run").description("Run a LITE/STANDARD/FULL/orchestrate workfl
     routingLocalModel: options.routingLocalModel,
     routingLocalPreferModel: options.routingLocalPreferModel,
     routingLocalProvider: options.routingLocalProvider,
+    routingLocalApiKeyEnv: options.routingLocalApiKeyEnv,
+    routingLocalApiKeyHeader: options.routingLocalApiKeyHeader,
     plannerRetainsReasoning: options.plannerRetainsReasoning ? true : void 0,
     writePlanFile: options.writePlanFile,
     startWorkflowFromPlan: Boolean(options.startWorkflowFromPlan),
@@ -38944,7 +39086,11 @@ localWorkers.command("add").description("Declare a local worker and enable local
   "--role <role>",
   "Worker role, for example coding, documentation, tests, or review",
   "coding"
-).option("--provider <provider>", "Provider label", "lm-studio").option("--base-url <url>", "OpenAI-compatible local runtime base URL", "http://127.0.0.1:1234").option("--model <id>", "Exact model id exposed by the local runtime").option(
+).option("--provider <provider>", "Provider label", "lm-studio").option("--base-url <url>", "OpenAI-compatible local runtime base URL", "http://127.0.0.1:1234").option("--api-key-env <env>", "Environment variable containing the provider API key").option(
+  "--api-key-header <header>",
+  "Provider API key header: authorization or x-api-key",
+  "authorization"
+).option("--model <id>", "Exact model id exposed by the local runtime").option(
   "--prefer-model <text>",
   "Fallback model id substring to prefer when no exact model is set"
 ).option("--transport <openai_http|cli>", "Worker transport: openai_http (default) or cli").option("--command <command>", "CLI command to execute when transport is cli").option("--capability <capability>", "Worker capability; repeatable", collectOption, []).option(
@@ -38971,6 +39117,8 @@ localWorkers.command("add").description("Declare a local worker and enable local
     preferModel: options.preferModel,
     transport: options.transport,
     command: options.command,
+    apiKeyEnv: options.apiKeyEnv,
+    apiKeyHeader: options.apiKeyHeader,
     capabilities: options.capability,
     reasoning: options.reasoning ? options.reasoning.toLowerCase() : void 0,
     contextWindow: options.contextWindow,
@@ -38988,7 +39136,11 @@ localWorkers.command("list").description("List declared local workers").option("
 localWorkers.command("remove").description("Remove a declared local worker").argument("id", "Local worker id").option("--json", "Print raw JSON").action((id, options) => {
   workersLocalRemoveCommand({ id, json: options.json });
 });
-localWorkers.command("probe").description("Probe an OpenAI-compatible endpoint and draft a worker suggestion").option("--base-url <url>", "OpenAI-compatible local runtime base URL", "http://127.0.0.1:1234").option("--provider <provider>", "Provider label", "lm-studio").option("--model <id>", "Exact model id exposed by the local runtime").option("--prefer-model <text>", "Fallback local model substring when exact model is unset").option(
+localWorkers.command("probe").description("Probe an OpenAI-compatible endpoint and draft a worker suggestion").option("--base-url <url>", "OpenAI-compatible local runtime base URL", "http://127.0.0.1:1234").option("--api-key-env <env>", "Environment variable containing the provider API key").option(
+  "--api-key-header <header>",
+  "Provider API key header: authorization or x-api-key",
+  "authorization"
+).option("--provider <provider>", "Provider label", "lm-studio").option("--model <id>", "Exact model id exposed by the local runtime").option("--prefer-model <text>", "Fallback local model substring when exact model is unset").option(
   "--role <role>",
   "Worker role; for example coding, documentation, tests, or review",
   "coding"
@@ -39019,6 +39171,8 @@ localWorkers.command("probe").description("Probe an OpenAI-compatible endpoint a
     reasoning: options.reasoning ? options.reasoning.toLowerCase() : void 0,
     contextWindow: options.contextWindow,
     writeScope: options.writeScope,
+    apiKeyEnv: options.apiKeyEnv,
+    apiKeyHeader: options.apiKeyHeader,
     json: options.json
   });
 });

package/docs/FULL_REFERENCE.md

@@ -464,7 +464,8 @@ snipara-companion workers local add \
   --role coding \
   --provider lm-studio \
   --base-url http://127.0.0.1:1234 \
-  --model openai/gpt-oss-20b
+  --model openai/gpt-oss-20b \
+  --api-key-env LM_STUDIO_API_KEY
 ```
 
 The declaration is written under `.snipara/workers/<worker-id>.json`; Companion
@@ -499,7 +500,11 @@ Do not store secrets in worker profiles. Local endpoints such as
 `http://127.0.0.1:1234` are safe to commit when they contain no credentials, but
 cloud CLI transports or authenticated endpoints must reference secrets through
 environment variables rather than embedding API keys, bearer tokens, passwords,
-or private URLs directly in `.snipara/workers/*.json`.
+or private URLs directly in `.snipara/workers/*.json`. `--api-key-env` stores
+only the variable name; pair it with `--api-key-header authorization` (default)
+or `--api-key-header x-api-key`. Native Codex and Claude profiles use their
+host-managed credentials. A generic `cli://command` profile fails closed unless
+the command maps to a supported Codex or Claude adapter.
 
 Use `workers local probe` to query a local endpoint and preview a declaration
 proposal before committing it:
@@ -559,6 +564,24 @@ snipara-orchestrator local-model-catalog \
   --json > .snipara/local-devstral-runtime-catalog.json
 ```
 
+For a remote OpenAI-compatible runtime, use an explicit allowlist and an
+environment-backed key when running the native host:
+
+```bash
+snipara-orchestrator host run \
+  --adapter openai_compatible \
+  --base-url https://provider.example.com --allow-remote \
+  --api-key-env PROVIDER_API_KEY --api-key-header authorization \
+  --model provider/coder --task "Bounded task" --workspace . \
+  --write-scope docs/** --proof "git diff --check" --execute
+```
+
+Native host proof commands run automatically after dispatch. Use
+`--no-run-proof` only when a reviewer will validate the receipt; the state then
+remains `verification_required`. Use `--require-approval` with both an approval
+receipt id and `--approval-receipt-file <json>` for unattended execution; an id
+alone never bypasses the approval gate.
+
 The local catalog records the OpenAI-compatible routes exposed by LM Studio:
 `GET /v1/models`, `POST /v1/responses`, `POST /v1/chat/completions`,
 `POST /v1/completions`, and `POST /v1/embeddings`. `--prefer-model devstral`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "3.4.0",
+  "version": "3.4.1",
   "description": "Local-first CLI that asks your repo what breaks before an AI coding agent edits it.",
   "main": "dist/index.js",
   "bin": {