snipara-companion 1.4.21 → 2.0.0

package/README.md

@@ -127,6 +127,7 @@ snipara-companion brief --task "ship auth hardening" --changed-files src/auth.ts
 snipara-companion timeline
 snipara-companion workflow phase-commit build --summary "tests green"
 snipara-companion workflow impact-gate
+snipara-companion workflow run --adaptive-routing-dry-run --route-local-workers "document a scoped change"
 snipara-companion verify --changed-files src/auth.ts --diff-summary "auth hardening"
 snipara-companion run --task "ship auth hardening" --changed-files src/auth.ts --release
 snipara-companion handoff --summary "status command shipped" --next "publish package"
@@ -141,6 +142,9 @@ snipara-companion workflow resume --include-session-context
 - `workflow impact-gate` audits committed local workflow phases that are ahead
   of upstream but not pushed. It does not push, and dirty working-tree files are
   reported separately from the committed diff.
+- `workflow run --adaptive-routing-dry-run` prints an Adaptive Work Routing
+  card. Add `--route-local-workers` when a strong planner should keep deep
+  reasoning while a local worker handles scoped execution.
 - `verify` builds a transparent verification plan from companion code impact
   signals plus local package scripts. It recommends checks; it does not claim to
   execute them.
@@ -167,6 +171,59 @@ if the hosted call still times out. A hosted final-commit timeout does not modif
 Git state. Custom final-commit categories are namespaced under `final-commit`
 before the hosted call so they stay on the handoff-only path.
 
+## Adaptive Work Routing
+
+Adaptive Work Routing is a recommendation-first path for routing scoped work to
+the right worker class, endpoint type, and cost profile without hardcoding model
+names in the CLI.
+
+```bash
+snipara-companion workflow run \
+  --mode full \
+  --adaptive-routing-dry-run \
+  --route-local-workers \
+  --routing-worker-role coding \
+  --routing-preferred-endpoint local \
+  --routing-allowed-endpoint local \
+  --routing-allowed-endpoint cloud \
+  --planner-retains-reasoning \
+  "Update documentation for the new gateway"
+```
+
+The output is a routing card and handoff metadata. Companion calls the hosted
+`snipara_adaptive_routing_catalog` tool when project auth and policy allow it,
+records the sanitized runtime catalog in the handoff, and falls back to local
+dry-run metadata when the hosted gateway is unavailable or omits
+`success: true`. It does not silently spawn workers. The stable contract is
+provider-neutral requirements such as worker role, reasoning depth, context
+budget, endpoint type, write scope, and fallback.
+
+Project owners can configure Adaptive Work Routing in Project > Automation:
+`off`, `recommend`, or `catalog`; approval; planner-retained reasoning; allowed
+endpoint types (`cloud`, `local`, `self_hosted`); worker classes; and budget
+hints. `workflow run` reads that hosted policy and CLI flags cannot broaden it.
+Project credentials stay server-side behind the hosted gateway; local endpoints
+such as Ollama, LM Studio, AnythingLLM, or other OpenAI-compatible servers must
+be reachable from the worker execution environment.
+
+For the open package without Snipara SaaS, add a local policy file:
+
+```json
+{
+  "mode": "recommend",
+  "plannerRetainsReasoning": true,
+  "preferLocalWorkers": true,
+  "allowedEndpointTypes": ["local", "cloud"],
+  "preferredEndpointTypes": ["local"],
+  "allowedWorkerClasses": ["documentation", "tests", "review"],
+  "catalogLimit": 8
+}
+```
+
+Save it at `.snipara/adaptive-routing.json`. Without hosted configuration,
+`workflow run` only emits local Adaptive Work Routing metadata and handoff files:
+it does not query hosted context, call the hosted catalog, or spawn workers.
+
 ## Verification Plans
 
 Use `verify` when an agent asks what to prove before handoff or release:

package/dist/index.d.ts

@@ -379,6 +379,33 @@ interface AutomationConfigBundle {
     files: AutomationConfigFile[];
     instructions: string[];
 }
+interface ProjectAutomationSettings {
+    automationClient?: string;
+    autoInjectContext?: boolean;
+    trackAccessedFiles?: boolean;
+    preserveOnCompaction?: boolean;
+    restoreOnSessionStart?: boolean;
+    enrichPrompts?: boolean;
+    maxTokensPerQuery?: number;
+    searchMode?: string;
+    includeSummaries?: boolean;
+    adaptiveRoutingMode?: string;
+    adaptiveRoutingRequireApproval?: boolean;
+    adaptiveRoutingPlannerRetainsReasoning?: boolean;
+    adaptiveRoutingPreferLocalWorkers?: boolean;
+    adaptiveRoutingAllowedEndpointTypes?: string[];
+    adaptiveRoutingPreferredEndpointTypes?: string[];
+    adaptiveRoutingAllowedWorkerClasses?: string[];
+    adaptiveRoutingFallback?: string;
+    adaptiveRoutingDailyBudgetCents?: number;
+    adaptiveRoutingMonthlyBudgetCents?: number;
+    adaptiveRoutingCatalogLimit?: number;
+}
+interface ProjectAutomationSettingsResult {
+    settings: ProjectAutomationSettings;
+    plan?: string;
+    featureAvailability?: Record<string, unknown>;
+}
 interface RecentAutomationEvent {
     id: string;
     sessionId: string;
@@ -986,6 +1013,7 @@ declare class RLMClient {
         limit?: number;
     }): Promise<RecentAutomationEventsResult>;
     getAutomationConfigBundle(client: string): Promise<AutomationConfigBundle>;
+    getAutomationSettings(): Promise<ProjectAutomationSettingsResult>;
     evaluateStuckGuard(args?: EvaluateStuckGuardArgs): Promise<StuckGuardEvaluationResult>;
     getStuckGuardStatus(args?: {
         sessionId?: string;
@@ -2820,6 +2848,7 @@ interface AdaptiveModelRequirements {
     writeScope: string[];
     preferredEndpointTypes?: string[];
     allowedEndpointTypes?: string[];
+    catalogLimit?: number;
     fallback: "main_agent";
 }
 interface AdaptiveRoutingCostEstimate {
@@ -2837,10 +2866,24 @@ interface AdaptiveRoutingCard {
     reasons: string[];
     warnings: string[];
 }
+interface AdaptiveRoutingGatewayStatus {
+    source: "hosted_mcp";
+    success: boolean;
+    resolutionStatus?: string;
+    candidateCount: number;
+    fallback?: string;
+    warnings: string[];
+}
+interface AdaptiveRoutingRuntimeCatalog {
+    version?: string;
+    candidates: Array<Record<string, unknown>>;
+}
 interface AdaptiveWorkRoutingRecommendation {
     workProfile: AdaptiveWorkProfile;
     requirements: AdaptiveModelRequirements;
     routingCard: AdaptiveRoutingCard;
+    gateway?: AdaptiveRoutingGatewayStatus;
+    runtimeCatalog?: AdaptiveRoutingRuntimeCatalog;
 }
 interface AdaptiveWorkRoutingOptions {
     query: string;
@@ -2850,6 +2893,7 @@ interface AdaptiveWorkRoutingOptions {
     allowedEndpointTypes?: string[];
     workerRole?: string;
     plannerRetainsReasoning?: boolean;
+    catalogLimit?: number;
 }
 interface OrchestratorHandoffArtifact {
     schemaVersion: "snipara.orchestrator.handoff.v1";
@@ -2877,6 +2921,8 @@ interface OrchestratorHandoffArtifact {
         workProfile?: AdaptiveWorkProfile;
         requirements?: AdaptiveModelRequirements;
         routingCard?: AdaptiveRoutingCard;
+        gateway?: AdaptiveRoutingGatewayStatus;
+        runtimeCatalog?: AdaptiveRoutingRuntimeCatalog;
     };
     task: {
         title: string;

package/dist/index.js

@@ -1024,6 +1024,44 @@ var RLMClient = class {
       clearTimeout(timeoutId);
     }
   }
+  async getAutomationSettings() {
+    if (!this.config.apiKey) {
+      throw new Error("API key not configured. Run 'npx -y snipara-companion@latest init' first.");
+    }
+    const projectIdentifier = this.resolveProjectIdentifier();
+    const projectId = encodeURIComponent(projectIdentifier);
+    const url = `${this.dashboardApiUrl()}/api/projects/${projectId}/automation`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await this.fetchWithApiKeyRetry(
+        url,
+        {
+          method: "GET",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          signal: controller.signal
+        },
+        projectIdentifier
+      );
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      const data = await response.json();
+      if (!data.success || !data.data?.settings || typeof data.data.settings !== "object") {
+        throw new Error("Automation settings response was invalid");
+      }
+      return {
+        settings: data.data.settings,
+        plan: typeof data.data.plan === "string" ? data.data.plan : void 0,
+        featureAvailability: data.data.featureAvailability && typeof data.data.featureAvailability === "object" && !Array.isArray(data.data.featureAvailability) ? data.data.featureAvailability : void 0
+      };
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   async evaluateStuckGuard(args = {}) {
     if (!this.config.apiKey) {
       throw new Error("API key not configured. Run 'npx -y snipara-companion@latest init' first.");
@@ -11144,7 +11182,9 @@ function buildOrchestratorHandoff(options) {
       ...options.adaptiveRouting ? {
         workProfile: options.adaptiveRouting.workProfile,
         requirements: options.adaptiveRouting.requirements,
-        routingCard: options.adaptiveRouting.routingCard
+        routingCard: options.adaptiveRouting.routingCard,
+        ...options.adaptiveRouting.gateway ? { gateway: options.adaptiveRouting.gateway } : {},
+        ...options.adaptiveRouting.runtimeCatalog ? { runtimeCatalog: options.adaptiveRouting.runtimeCatalog } : {}
       } : {}
     },
     task: {
@@ -11223,6 +11263,7 @@ function buildAdaptiveWorkRoutingRecommendation(options) {
     writeScope: changedFiles,
     preferredEndpointTypes,
     allowedEndpointTypes,
+    catalogLimit: options.catalogLimit,
     fallback: "main_agent"
   });
   const warnings = [
@@ -11356,7 +11397,9 @@ function normalizeEndpointTypes(values) {
 }
 function compactObject2(value) {
   return Object.fromEntries(
-    Object.entries(value).filter(([, item]) => !(Array.isArray(item) && item.length === 0))
+    Object.entries(value).filter(
+      ([, item]) => item !== void 0 && !(Array.isArray(item) && item.length === 0)
+    )
   );
 }
 function writeOrchestratorHandoff(options) {
@@ -14549,6 +14592,8 @@ var FINAL_COMMIT_TIMEOUT_MS = 9e4;
 var FINAL_COMMIT_RETRY_TIMEOUT_MS = 45e3;
 var FINAL_COMMIT_SUMMARY_MAX_CHARS = 1200;
 var FINAL_COMMIT_RETRY_SUMMARY_MAX_CHARS = 600;
+var DEFAULT_ADAPTIVE_ROUTING_CATALOG_LIMIT = 20;
+var ADAPTIVE_ROUTING_POLICY_RELATIVE_PATH = path18.join(".snipara", "adaptive-routing.json");
 var SHARED_CONTEXT_INTENT_PATTERN = /\b(standard|standards|convention|conventions|guideline|guidelines|best practice|best practices|policy|policies|compliance|compliant|security rules|team rules|style guide|playbook|checklist)\b/i;
 var DOCUMENT_SYNC_FORMATS = {
   ".adoc": { kind: "DOC", format: "adoc" },
@@ -14648,6 +14693,20 @@ function stringValue5(value) {
   const stringified = String(value).trim();
   return stringified || void 0;
 }
+function numberValue5(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  const text = stringValue5(value);
+  if (!text) {
+    return void 0;
+  }
+  const parsed = Number(text);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function uniqueStrings3(values) {
+  return Array.from(new Set(values.filter((value) => value.trim().length > 0)));
+}
 function normalizeEnum(value) {
   return stringValue5(value)?.replace(/[-\s]/g, "_").toUpperCase() ?? "";
 }
@@ -17064,6 +17123,12 @@ function printAdaptiveRoutingRecommendation(routing) {
   if (routing.requirements.plannerRetainsReasoning) {
     printKeyValue("Planner retains reasoning:", "yes");
   }
+  if (routing.gateway) {
+    printKeyValue(
+      "Hosted catalog:",
+      routing.gateway.success ? `${routing.gateway.candidateCount} candidate(s), ${routing.gateway.resolutionStatus ?? "ready"}` : "unavailable"
+    );
+  }
   if (routing.routingCard.reasons.length > 0) {
     console.log("Reasons:");
     for (const reason of routing.routingCard.reasons) {
@@ -17077,6 +17142,182 @@ function printAdaptiveRoutingRecommendation(routing) {
     }
   }
 }
+function policyValue(settings, hostedKey, localKey) {
+  const record = settings;
+  return record[hostedKey] ?? record[localKey];
+}
+function readLocalAdaptiveRoutingProjectPolicy() {
+  const workspaceRoot = findWorkspaceRoot(process.cwd(), true);
+  if (!workspaceRoot) {
+    return null;
+  }
+  const policyPath = path18.join(workspaceRoot, ADAPTIVE_ROUTING_POLICY_RELATIVE_PATH);
+  if (!fs19.existsSync(policyPath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fs19.readFileSync(policyPath, "utf8"));
+    if (!isRecord9(parsed)) {
+      return null;
+    }
+    return normalizeAdaptiveRoutingProjectPolicy(parsed, "local_file");
+  } catch {
+    return null;
+  }
+}
+async function loadAdaptiveRoutingProjectPolicy(client, fallbackPolicy = null) {
+  try {
+    if (!client) {
+      return fallbackPolicy;
+    }
+    const result = await client.getAutomationSettings();
+    return normalizeAdaptiveRoutingProjectPolicy(result.settings, "hosted_project") ?? fallbackPolicy;
+  } catch {
+    return fallbackPolicy;
+  }
+}
+function normalizeAdaptiveRoutingProjectPolicy(settings, source) {
+  const mode = normalizeAdaptiveRoutingMode(policyValue(settings, "adaptiveRoutingMode", "mode"));
+  if (!mode) {
+    return null;
+  }
+  const allowedEndpointTypes = normalizeRoutingEndpointTypes(
+    normalizeStringArray3(
+      policyValue(settings, "adaptiveRoutingAllowedEndpointTypes", "allowedEndpointTypes")
+    )
+  );
+  const preferredEndpointTypes = normalizeRoutingEndpointTypes(
+    normalizeStringArray3(
+      policyValue(settings, "adaptiveRoutingPreferredEndpointTypes", "preferredEndpointTypes")
+    )
+  );
+  const allowedWorkerClasses = normalizeAdaptiveWorkerClasses(
+    normalizeStringArray3(
+      policyValue(settings, "adaptiveRoutingAllowedWorkerClasses", "allowedWorkerClasses")
+    )
+  );
+  return {
+    source,
+    mode,
+    requireApproval: policyValue(settings, "adaptiveRoutingRequireApproval", "requireApproval") !== false,
+    plannerRetainsReasoning: policyValue(settings, "adaptiveRoutingPlannerRetainsReasoning", "plannerRetainsReasoning") !== false,
+    preferLocalWorkers: policyValue(settings, "adaptiveRoutingPreferLocalWorkers", "preferLocalWorkers") === true,
+    allowedEndpointTypes: allowedEndpointTypes.length > 0 ? allowedEndpointTypes : ["cloud"],
+    preferredEndpointTypes,
+    allowedWorkerClasses: allowedWorkerClasses.length > 0 ? allowedWorkerClasses : ["documentation", "tests", "review"],
+    fallback: "main_agent",
+    dailyBudgetCents: normalizeCents(
+      policyValue(settings, "adaptiveRoutingDailyBudgetCents", "dailyBudgetCents")
+    ),
+    monthlyBudgetCents: normalizeCents(
+      policyValue(settings, "adaptiveRoutingMonthlyBudgetCents", "monthlyBudgetCents")
+    ),
+    catalogLimit: normalizeAdaptiveRoutingCatalogLimit(
+      policyValue(settings, "adaptiveRoutingCatalogLimit", "catalogLimit")
+    )
+  };
+}
+function resolveAdaptiveRoutingIntent(options, policy, hostedConfigured) {
+  const cliRequested = shouldBuildAdaptiveRouting(options);
+  if (!policy) {
+    return {
+      shouldBuild: cliRequested,
+      shouldUseHostedCatalog: cliRequested,
+      warnings: []
+    };
+  }
+  if (policy.mode === "off") {
+    return {
+      shouldBuild: cliRequested,
+      shouldUseHostedCatalog: false,
+      warnings: cliRequested ? ["Project Adaptive Work Routing policy is off; keeping recommendation metadata local."] : []
+    };
+  }
+  return {
+    shouldBuild: true,
+    shouldUseHostedCatalog: hostedConfigured && policy.mode === "catalog",
+    warnings: [
+      ...policy.mode === "recommend" ? [
+        "Project Adaptive Work Routing policy is recommendation-only; hosted catalog lookup is disabled."
+      ] : [],
+      ...!hostedConfigured && policy.mode === "catalog" ? [
+        "Local Adaptive Work Routing policy requested catalog mode; hosted catalog lookup is skipped without Snipara configuration."
+      ] : []
+    ]
+  };
+}
+async function enrichAdaptiveRoutingWithHostedCatalog(client, routing) {
+  try {
+    const result = await client.callTool(
+      "snipara_adaptive_routing_catalog",
+      {
+        work_profile: routing.workProfile,
+        model_requirements: routing.requirements,
+        limit: routing.requirements.catalogLimit ?? DEFAULT_ADAPTIVE_ROUTING_CATALOG_LIMIT
+      }
+    );
+    const catalog = normalizeAdaptiveRoutingCatalog(result.catalog);
+    const gatewaySucceeded = result.success === true;
+    const warnings = normalizeStringArray3(result.warnings) ?? [];
+    const gatewayWarnings = gatewaySucceeded ? warnings : [
+      ...warnings,
+      "Hosted adaptive routing catalog did not return success=true; treating gateway as failed closed."
+    ];
+    const candidateCount = numberValue5(result.resolution?.candidate_count) ?? numberValue5(result.resolution?.candidateCount) ?? catalog.candidates.length;
+    const gateway = {
+      source: "hosted_mcp",
+      success: gatewaySucceeded,
+      resolutionStatus: stringValue5(result.resolution?.status),
+      candidateCount,
+      fallback: stringValue5(result.fallback) ?? stringValue5(result.resolution?.fallback) ?? "main_agent",
+      warnings: gatewayWarnings
+    };
+    const reasons = [
+      ...routing.routingCard.reasons,
+      gatewaySucceeded ? candidateCount > 0 ? `hosted adaptive routing catalog returned ${candidateCount} candidate(s)` : "hosted adaptive routing catalog returned no candidates and will fail closed" : "hosted adaptive routing catalog did not report explicit success and will fail closed"
+    ];
+    return {
+      ...routing,
+      gateway,
+      runtimeCatalog: catalog,
+      routingCard: {
+        ...routing.routingCard,
+        reasons: uniqueStrings3(reasons),
+        warnings: uniqueStrings3([...routing.routingCard.warnings, ...gatewayWarnings])
+      }
+    };
+  } catch (error) {
+    const warning = `Hosted adaptive routing catalog unavailable; keeping local dry-run metadata (${toPreview(error)}).`;
+    return {
+      ...routing,
+      gateway: {
+        source: "hosted_mcp",
+        success: false,
+        resolutionStatus: "unavailable",
+        candidateCount: 0,
+        fallback: "main_agent",
+        warnings: [warning]
+      },
+      routingCard: {
+        ...routing.routingCard,
+        warnings: uniqueStrings3([...routing.routingCard.warnings, warning])
+      }
+    };
+  }
+}
+function normalizeAdaptiveRoutingCatalog(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { candidates: [] };
+  }
+  const record = value;
+  const candidates = Array.isArray(record.candidates) ? record.candidates.filter(
+    (candidate) => Boolean(candidate) && typeof candidate === "object" && !Array.isArray(candidate)
+  ) : [];
+  return {
+    version: stringValue5(record.version),
+    candidates
+  };
+}
 function printUploadResult(path20, result) {
   printKeyValue("Uploaded:", path20);
   printCompactObject(result, ["message", "document_id", "documentId", "version", "status"]);
@@ -18219,15 +18460,15 @@ function hasReferenceProvenance(metadata) {
   ].some(Boolean);
 }
 function validateFreshnessPolicy(metadata, reasons) {
-  const policyValue = metadata.freshnessPolicy ?? metadata.freshness_policy;
-  if (policyValue === void 0) {
+  const policyValue2 = metadata.freshnessPolicy ?? metadata.freshness_policy;
+  if (policyValue2 === void 0) {
     return { maxAgeDays: void 0 };
   }
-  if (!isRecord9(policyValue)) {
+  if (!isRecord9(policyValue2)) {
     reasons.push("invalid_freshness_policy");
     return { maxAgeDays: void 0 };
   }
-  const maxAge = policyValue.maxAgeDays ?? policyValue.max_age_days;
+  const maxAge = policyValue2.maxAgeDays ?? policyValue2.max_age_days;
   if (maxAge === void 0) {
     return { maxAgeDays: void 0 };
   }
@@ -18548,14 +18789,26 @@ async function sharedContextCommand(options) {
   printSharedContextResult(result);
 }
 async function workflowRunCommand(options) {
-  ensureConfigured();
-  const client = createClient(2e4);
-  const adaptiveRoutingRequested = shouldBuildAdaptiveRouting(options);
-  const adaptiveRouting = adaptiveRoutingRequested ? buildWorkflowAdaptiveRouting(options) : null;
+  const hostedConfigured = isConfigured();
+  const localAdaptiveRoutingPolicy = readLocalAdaptiveRoutingProjectPolicy();
+  const localAdaptiveRoutingRequested = shouldBuildAdaptiveRouting(options);
+  const canRunLocalAdaptiveRouting = !hostedConfigured && options.mode !== "orchestrate" && (localAdaptiveRoutingRequested || localAdaptiveRoutingPolicy !== null && localAdaptiveRoutingPolicy.mode !== "off");
+  if (!hostedConfigured && !canRunLocalAdaptiveRouting) {
+    ensureConfigured();
+  }
+  const client = hostedConfigured ? createClient(2e4) : null;
+  const adaptiveRoutingPolicy = hostedConfigured ? await loadAdaptiveRoutingProjectPolicy(client, localAdaptiveRoutingPolicy) : localAdaptiveRoutingPolicy;
+  const adaptiveRoutingIntent = resolveAdaptiveRoutingIntent(
+    options,
+    adaptiveRoutingPolicy,
+    hostedConfigured
+  );
+  const adaptiveRoutingDryRun = adaptiveRoutingIntent.shouldBuild ? buildWorkflowAdaptiveRouting(options, adaptiveRoutingPolicy, adaptiveRoutingIntent.warnings) : null;
+  const adaptiveRouting = adaptiveRoutingDryRun && adaptiveRoutingIntent.shouldUseHostedCatalog && client ? await enrichAdaptiveRoutingWithHostedCatalog(client, adaptiveRoutingDryRun) : adaptiveRoutingDryRun;
   const orchestratorRecommendation = getOrchestratorRecommendation(options.query, options.mode, {
     policyAutoRoute: options.autoRouteOrchestrator,
     policySource: options.orchestratorPolicySource,
-    adaptiveRoutingDryRun: adaptiveRoutingRequested
+    adaptiveRoutingDryRun: Boolean(adaptiveRouting)
   });
   const shouldEmitOrchestratorHandoff = options.emitOrchestratorHandoff || options.autoRouteOrchestrator;
   const preparedHandoff = shouldEmitOrchestratorHandoff && orchestratorRecommendation ? writeOrchestratorHandoff({
@@ -18567,6 +18820,38 @@ async function workflowRunCommand(options) {
     mode: options.mode,
     adaptiveRouting
   }) : null;
+  if (!hostedConfigured) {
+    const payload2 = {
+      mode: options.mode,
+      effective_mode: effectiveWorkflowMode(options.mode),
+      local_only: true,
+      local_policy_path: localAdaptiveRoutingPolicy ? ADAPTIVE_ROUTING_POLICY_RELATIVE_PATH : null,
+      orchestrator_recommendation: orchestratorRecommendation,
+      orchestrator_handoff: preparedHandoff,
+      adaptive_routing: adaptiveRouting,
+      warnings: [
+        "Hosted Snipara is not configured; workflow run is limited to local Adaptive Work Routing metadata."
+      ]
+    };
+    if (options.json) {
+      printJson2(payload2);
+      return;
+    }
+    console.log(import_chalk9.default.bold("Local Adaptive Work Routing"));
+    console.log(
+      "Hosted Snipara is not configured; no context query, hosted catalog, or planner call ran."
+    );
+    if (adaptiveRouting) {
+      printAdaptiveRoutingRecommendation(adaptiveRouting);
+    }
+    if (preparedHandoff) {
+      printPreparedOrchestratorHandoff2(preparedHandoff);
+    }
+    return;
+  }
+  if (!client) {
+    throw new Error("Hosted Snipara client unavailable after configuration check.");
+  }
   if (options.mode === "orchestrate") {
     const result = await client.orchestrate(options.query, options.maxTokens);
     if (options.json) {
@@ -18745,22 +19030,72 @@ function shouldBuildAdaptiveRouting(options) {
     options.adaptiveRoutingDryRun || options.routeLocalWorkers || options.routingWorkerRole || options.routingPreferredEndpoints?.length || options.routingAllowedEndpoints?.length || options.plannerRetainsReasoning
   );
 }
-function buildWorkflowAdaptiveRouting(options) {
+function buildWorkflowAdaptiveRouting(options, policy = null, intentWarnings = []) {
   const state = readWorkflowState2();
   const currentPhase = state ? currentWorkflowPhase(state) : void 0;
-  const preferredEndpointTypes = normalizeRoutingEndpointTypes([
+  const initialPreferredEndpointTypes = normalizeRoutingEndpointTypes([
     ...options.routingPreferredEndpoints ?? [],
-    ...options.routeLocalWorkers ? ["local"] : []
+    ...options.routeLocalWorkers ? ["local"] : [],
+    ...policy?.preferredEndpointTypes ?? [],
+    ...policy?.preferLocalWorkers ? ["local"] : []
   ]);
-  return buildAdaptiveWorkRoutingRecommendation({
+  const policyAllowedEndpointTypes = policy?.allowedEndpointTypes ?? [];
+  const requestedAllowedEndpointTypes = normalizeRoutingEndpointTypes(
+    options.routingAllowedEndpoints
+  );
+  const requestedPolicyEndpointIntersection = policyAllowedEndpointTypes.length > 0 && requestedAllowedEndpointTypes.length > 0 ? intersectStrings(requestedAllowedEndpointTypes, policyAllowedEndpointTypes) : [];
+  const allowedEndpointTypes = policyAllowedEndpointTypes.length > 0 ? requestedAllowedEndpointTypes.length > 0 ? requestedPolicyEndpointIntersection.length > 0 ? requestedPolicyEndpointIntersection : policyAllowedEndpointTypes : policyAllowedEndpointTypes : requestedAllowedEndpointTypes;
+  const preferredEndpointTypes = allowedEndpointTypes.length > 0 ? initialPreferredEndpointTypes.filter((type) => allowedEndpointTypes.includes(type)) : initialPreferredEndpointTypes;
+  const removedPreferredEndpointTypes = initialPreferredEndpointTypes.filter(
+    (type) => !preferredEndpointTypes.includes(type)
+  );
+  const policyWarnings = [
+    ...intentWarnings,
+    ...requestedAllowedEndpointTypes.length > 0 && policyAllowedEndpointTypes.length > 0 && requestedPolicyEndpointIntersection.length === 0 ? [
+      `Project Adaptive Work Routing policy rejected requested allowed endpoint(s): ${requestedAllowedEndpointTypes.join(", ")}.`
+    ] : [],
+    ...removedPreferredEndpointTypes.length > 0 ? [
+      `Project Adaptive Work Routing policy removed unsupported preferred endpoint(s): ${removedPreferredEndpointTypes.join(", ")}.`
+    ] : []
+  ];
+  const buildRecommendation = (workerRole) => buildAdaptiveWorkRoutingRecommendation({
     query: options.query,
     mode: options.mode,
     changedFiles: currentPhase?.files ?? [],
     preferredEndpointTypes,
-    allowedEndpointTypes: normalizeRoutingEndpointTypes(options.routingAllowedEndpoints),
-    workerRole: stringValue5(options.routingWorkerRole),
-    plannerRetainsReasoning: options.plannerRetainsReasoning ?? (options.routeLocalWorkers ? true : void 0)
+    allowedEndpointTypes,
+    workerRole,
+    plannerRetainsReasoning: options.plannerRetainsReasoning ?? policy?.plannerRetainsReasoning ?? (options.routeLocalWorkers ? true : void 0),
+    catalogLimit: policy?.catalogLimit ?? DEFAULT_ADAPTIVE_ROUTING_CATALOG_LIMIT
   });
+  const requestedWorkerRole = stringValue5(options.routingWorkerRole);
+  let routing = buildRecommendation(requestedWorkerRole);
+  const allowedWorkerClasses = policy?.allowedWorkerClasses ?? [];
+  if (allowedWorkerClasses.length > 0 && !isAdaptiveWorkerClassAllowed(routing.requirements.workerRole, allowedWorkerClasses)) {
+    const disallowedWorkerClass = canonicalAdaptiveWorkerClass(routing.requirements.workerRole);
+    const fallbackWorkerRole = selectAdaptiveWorkerRoleForPolicy(
+      routing.workProfile.taskType,
+      allowedWorkerClasses
+    );
+    routing = buildRecommendation(fallbackWorkerRole);
+    policyWarnings.push(
+      `Project Adaptive Work Routing policy does not allow worker class ${disallowedWorkerClass}; using ${canonicalAdaptiveWorkerClass(
+        fallbackWorkerRole
+      )}.`
+    );
+  }
+  const policyReasons = policy ? [
+    `project adaptive routing policy mode is ${policy.mode}`,
+    `project adaptive routing allows endpoint type(s): ${policy.allowedEndpointTypes.join(", ")}`
+  ] : [];
+  return {
+    ...routing,
+    routingCard: {
+      ...routing.routingCard,
+      reasons: uniqueStrings3([...routing.routingCard.reasons, ...policyReasons]),
+      warnings: uniqueStrings3([...routing.routingCard.warnings, ...policyWarnings])
+    }
+  };
 }
 function normalizeRoutingEndpointTypes(values) {
   return Array.from(
@@ -18769,6 +19104,60 @@ function normalizeRoutingEndpointTypes(values) {
     )
   ).sort();
 }
+function normalizeAdaptiveRoutingMode(value) {
+  const normalized = stringValue5(value)?.toLowerCase();
+  return normalized === "off" || normalized === "recommend" || normalized === "catalog" ? normalized : null;
+}
+function normalizeAdaptiveWorkerClasses(values) {
+  return uniqueStrings3((values ?? []).map(canonicalAdaptiveWorkerClass)).filter(
+    (value) => ["documentation", "tests", "review", "coding"].includes(value)
+  );
+}
+function normalizeCents(value) {
+  const parsed = numberValue5(value);
+  if (parsed === void 0 || parsed < 0) {
+    return 0;
+  }
+  return Math.floor(parsed);
+}
+function normalizeAdaptiveRoutingCatalogLimit(value) {
+  const parsed = numberValue5(value);
+  if (parsed === void 0 || parsed < 1) {
+    return void 0;
+  }
+  return Math.min(Math.floor(parsed), 100);
+}
+function intersectStrings(left, right) {
+  const rightSet = new Set(right);
+  return left.filter((value) => rightSet.has(value));
+}
+function canonicalAdaptiveWorkerClass(value) {
+  const normalized = stringValue5(value)?.toLowerCase().replace(/[-\s]/g, "_") ?? "execution";
+  if (normalized === "docs" || normalized === "doc") {
+    return "documentation";
+  }
+  if (normalized === "test" || normalized === "testing") {
+    return "tests";
+  }
+  if (normalized === "validation" || normalized === "reviewer") {
+    return "review";
+  }
+  if (normalized === "code" || normalized === "coder" || normalized === "implementation") {
+    return "coding";
+  }
+  return normalized;
+}
+function isAdaptiveWorkerClassAllowed(workerRole, allowedWorkerClasses) {
+  return allowedWorkerClasses.includes(canonicalAdaptiveWorkerClass(workerRole));
+}
+function selectAdaptiveWorkerRoleForPolicy(taskType, allowedWorkerClasses) {
+  const preferences = taskType === "documentation" ? ["documentation", "review", "coding", "tests"] : taskType === "tests" ? ["tests", "review", "coding", "documentation"] : taskType === "coding" || taskType === "critical_code" ? ["coding", "review", "tests", "documentation"] : ["review", "coding", "documentation", "tests"];
+  const selected = preferences.find((workerClass) => allowedWorkerClasses.includes(workerClass));
+  return workerRoleFromAdaptiveClass(selected ?? allowedWorkerClasses[0] ?? "review");
+}
+function workerRoleFromAdaptiveClass(workerClass) {
+  return workerClass === "tests" ? "testing" : workerClass;
+}
 function startManagedWorkflowState(options) {
   const existing = readWorkflowState2();
   if (existing && existing.status === "active" && !options.force) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "1.4.21",
+  "version": "2.0.0",
   "description": "Snipara Git-style companion CLI for local workflow continuity, hooks, hosted context, and Mini Snipara OSS workflows",
   "main": "dist/index.js",
   "bin": {