replicas-engine 0.1.735 → 0.1.736

package/dist/src/{chunk-2VCV6W5F.js → chunk-AQXSBHCI.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   mayCreatePullRequest
-} from "./chunk-EZ6Z6GSU.js";
+} from "./chunk-NQFMLRS4.js";
 
 // src/services/post-tool-pr-notifier.ts
 async function notifyPostToolUse(toolName, toolInput) {

package/dist/src/{chunk-CZXDETV5.js → chunk-KIBFWYCG.js}

@@ -5,15 +5,17 @@ import {
 import {
   REPLICAS_RUNTIME_ENV_ALIASES,
   agentCredentialSnapshotSchema,
-  chatForkFallbackResponseSchema,
+  createErrorResult,
+  createSuccessResult,
   extractCommandProtectionCommandText,
+  fallbackPlanResponseSchema,
   findGitCommitSignals,
   findPrMergeSignals,
   isRecord,
   isValidAgentProvider,
   parsePosixEnvFile,
   readReplicasRuntimeEnv
-} from "./chunk-EZ6Z6GSU.js";
+} from "./chunk-NQFMLRS4.js";
 
 // src/engine-env.ts
 import { readFileSync as readFileSync2 } from "fs";
@@ -198,15 +200,19 @@ var MonolithService = class {
       return null;
     }
   }
-  async getChatForkFallback(params) {
+  /** `unsupported` means an older monolith; `unavailable` means this one could not be read. */
+  async getFallbackPlan(params) {
     const query = new URLSearchParams({ provider: params.provider, exclude: params.exclude.join(",") });
+    if (params.exhaustedMethod) query.set("exhaustedMethod", params.exhaustedMethod);
     if (params.userId) query.set("userId", params.userId);
     try {
-      const response = await monolithRequest(`/v1/engine/chat-fork-fallback?${query}`, { method: "GET" });
-      if (!response.ok) return null;
-      return chatForkFallbackResponseSchema.safeParse(await response.json()).data ?? null;
-    } catch {
-      return null;
+      const response = await monolithRequest(`/v1/engine/fallback-plan?${query}`, { method: "GET" });
+      if (response.status === 404) return createErrorResult({ message: "Monolith has no fallback-plan route", code: "unsupported" });
+      if (!response.ok) return createErrorResult({ message: `Fallback plan request failed: ${response.status}`, code: "unavailable" });
+      const parsed = fallbackPlanResponseSchema.safeParse(await response.json());
+      return parsed.success ? createSuccessResult(parsed.data) : createErrorResult({ message: "Fallback plan response did not match the schema", code: "unavailable" });
+    } catch (error) {
+      return createErrorResult({ message: error instanceof Error ? error.message : String(error), code: "unavailable" });
     }
   }
   async sendEvent(event) {

package/dist/src/{chunk-EZ6Z6GSU.js → chunk-NQFMLRS4.js}

@@ -1268,43 +1268,54 @@ function describeAuthFallback(payload) {
 }
 
 // ../shared/src/chat-fork.ts
+import { z as z5 } from "zod";
+
+// ../shared/src/fallback-chains.ts
 import { z as z4 } from "zod";
-var quotaLimitKindSchema = z4.enum(["rate_limit", "out_of_credits"]);
-var chatForkInfoSchema = z4.object({
-  source: z4.object({
-    chatId: z4.string().min(1),
-    provider: z4.enum(VALID_AGENT_PROVIDERS),
-    title: z4.string()
+var fallbackHarnessStepSchema = z4.object({
+  kind: z4.literal("harness"),
+  provider: z4.enum(VALID_AGENT_PROVIDERS),
+  model: z4.string().min(1),
+  thinkingLevel: z4.enum(VALID_THINKING_LEVELS).optional()
+});
+var fallbackPlanStepSchema = z4.discriminatedUnion("kind", [
+  z4.object({ kind: z4.literal("credentials"), methods: z4.array(z4.custom(isAuthMethod)).min(1) }),
+  fallbackHarnessStepSchema
+]);
+var fallbackPlanResponseSchema = z4.object({ steps: z4.array(fallbackPlanStepSchema) });
+
+// ../shared/src/chat-fork.ts
+var quotaLimitKindSchema = z5.enum(["rate_limit", "out_of_credits"]);
+var chatForkInfoSchema = z5.object({
+  source: z5.object({
+    chatId: z5.string().min(1),
+    provider: z5.enum(VALID_AGENT_PROVIDERS),
+    title: z5.string()
   }),
-  trigger: z4.enum(["manual", "auto"]),
+  trigger: z5.enum(["manual", "auto"]),
   reason: quotaLimitKindSchema.optional(),
-  state: z4.enum(["preparing", "ready", "failed"]),
-  error: z4.string().optional(),
-  startedAt: z4.string(),
-  completedAt: z4.string().optional()
+  state: z5.enum(["preparing", "ready", "failed"]),
+  error: z5.string().optional(),
+  startedAt: z5.string(),
+  completedAt: z5.string().optional()
 });
 function coerceChatForkInfo(value) {
   const parsed = chatForkInfoSchema.safeParse(value);
   return parsed.success ? parsed.data : null;
 }
-var forkChatRequestSchema = z4.object({
-  provider: z4.enum(VALID_AGENT_PROVIDERS),
-  model: z4.string().min(1).optional(),
-  thinkingLevel: z4.enum(VALID_THINKING_LEVELS).optional(),
-  title: z4.string().min(1).max(200).optional(),
-  id: z4.string().uuid().optional(),
-  clientRequestId: z4.string().min(1).max(128).optional(),
-  enableInteractiveTools: z4.boolean().optional(),
+var forkChatRequestSchema = z5.object({
+  provider: z5.enum(VALID_AGENT_PROVIDERS),
+  model: z5.string().min(1).optional(),
+  thinkingLevel: z5.enum(VALID_THINKING_LEVELS).optional(),
+  title: z5.string().min(1).max(200).optional(),
+  id: z5.string().uuid().optional(),
+  clientRequestId: z5.string().min(1).max(128).optional(),
+  enableInteractiveTools: z5.boolean().optional(),
   // Server-injected by the monolith from the authenticated request; never trusted from clients.
-  senderUserId: z4.string().optional(),
-  senderEmail: z4.string().optional(),
-  senderDisplayName: z4.string().optional(),
-  senderAvatarUrl: z4.string().optional()
-});
-var chatForkFallbackResponseSchema = z4.object({
-  provider: z4.enum(VALID_AGENT_PROVIDERS).nullable(),
-  model: z4.string().min(1).optional(),
-  thinkingLevel: z4.enum(VALID_THINKING_LEVELS).optional()
+  senderUserId: z5.string().optional(),
+  senderEmail: z5.string().optional(),
+  senderDisplayName: z5.string().optional(),
+  senderAvatarUrl: z5.string().optional()
 });
 function describeQuotaLimit(reason) {
   return reason === "out_of_credits" ? "ran out of credits" : "hit its usage limit";
@@ -1313,10 +1324,11 @@ function describeChatForkReason(reason, provider) {
   return reason ? `${getProviderDisplayName(provider)} ${describeQuotaLimit(reason)}` : null;
 }
 var AGENT_QUOTA_EXHAUSTED_EVENT_TYPE = "agent-quota-exhausted";
-var agentQuotaExhaustedPayloadSchema = z4.object({
-  provider: z4.enum(VALID_CODING_AGENT_PROVIDERS),
+var agentQuotaExhaustedPayloadSchema = z5.object({
+  provider: z5.enum(VALID_CODING_AGENT_PROVIDERS),
   reason: quotaLimitKindSchema,
-  detail: z4.string().optional()
+  detail: z5.string().optional(),
+  forkTo: fallbackHarnessStepSchema.optional()
 });
 function defaultForkChatTitle(source, provider) {
   return isDefaultChat(source) ? `Forked from ${source.title}` : `${source.title} (${getProviderDisplayName(provider)})`;
@@ -3272,9 +3284,7 @@ var DEFAULT_USER_PREFERENCES = {
   open_links_in_desktop_app: false,
   default_fast_mode: false,
   agent_defaults: { ...EMPTY_AGENT_DEFAULT_SETTINGS },
-  credential_priority: null,
-  chat_fork_fallbacks_enabled: false,
-  chat_fork_fallback_providers: []
+  fallback_chains: null
 };
 function defaultReplicasAgentAbilities() {
   const abilities = {};
@@ -5928,20 +5938,20 @@ var TEAM_PLAN = PLANS.team;
 var ENTERPRISE_PLAN = PLANS.enterprise;
 
 // ../shared/src/models-dev.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var MODELS_DEV_API_URL = "https://models.dev/api.json";
 var MODELS_DEV_CACHE_MS = 5 * 6e4;
-var modelsDevCatalogSchema = z5.record(z5.string(), z5.object({
-  models: z5.record(z5.string(), z5.object({
-    id: z5.string().optional(),
-    name: z5.string(),
-    description: z5.string().optional(),
-    status: z5.enum(["alpha", "beta", "deprecated"]).optional(),
-    cost: z5.object({
-      input: z5.number().finite().nonnegative().optional(),
-      output: z5.number().finite().nonnegative().optional(),
-      cache_read: z5.number().finite().nonnegative().optional(),
-      cache_write: z5.number().finite().nonnegative().optional()
+var modelsDevCatalogSchema = z6.record(z6.string(), z6.object({
+  models: z6.record(z6.string(), z6.object({
+    id: z6.string().optional(),
+    name: z6.string(),
+    description: z6.string().optional(),
+    status: z6.enum(["alpha", "beta", "deprecated"]).optional(),
+    cost: z6.object({
+      input: z6.number().finite().nonnegative().optional(),
+      output: z6.number().finite().nonnegative().optional(),
+      cache_read: z6.number().finite().nonnegative().optional(),
+      cache_write: z6.number().finite().nonnegative().optional()
     }).optional()
   }))
 }));
@@ -6873,46 +6883,46 @@ var DEFAULT_WORKSPACE_FILTERS = {
 var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
 
 // ../shared/src/routes/workspace-events.ts
-import { z as z6 } from "zod";
-var workspaceChangedEventSchema = z6.discriminatedUnion("type", [
-  z6.object({
-    type: z6.literal("workspace.changed"),
-    workspaceId: z6.string(),
-    completion: z6.object({
-      workspaceName: z6.string(),
-      completedAt: z6.string(),
-      processing: z6.boolean().optional()
+import { z as z7 } from "zod";
+var workspaceChangedEventSchema = z7.discriminatedUnion("type", [
+  z7.object({
+    type: z7.literal("workspace.changed"),
+    workspaceId: z7.string(),
+    completion: z7.object({
+      workspaceName: z7.string(),
+      completedAt: z7.string(),
+      processing: z7.boolean().optional()
     }).optional(),
-    ts: z6.string()
+    ts: z7.string()
   }),
-  z6.object({
-    type: z6.literal("workspace.chat.changed"),
-    workspaceId: z6.string(),
-    chatId: z6.string(),
-    ts: z6.string()
+  z7.object({
+    type: z7.literal("workspace.chat.changed"),
+    workspaceId: z7.string(),
+    chatId: z7.string(),
+    ts: z7.string()
   }),
-  z6.object({ type: z6.literal("presence.changed"), ts: z6.string() }),
-  z6.object({
-    type: z6.literal("mobile-testing.changed"),
-    workspaceId: z6.string(),
-    ts: z6.string()
+  z7.object({ type: z7.literal("presence.changed"), ts: z7.string() }),
+  z7.object({
+    type: z7.literal("mobile-testing.changed"),
+    workspaceId: z7.string(),
+    ts: z7.string()
   })
 ]);
 
 // ../shared/src/routes/presence.ts
-import { z as z7 } from "zod";
-var presenceStatusSchema = z7.enum(["online", "typing"]);
-var presenceLocationSchema = z7.object({
-  environmentId: z7.string().optional(),
-  workspaceId: z7.string().optional()
+import { z as z8 } from "zod";
+var presenceStatusSchema = z8.enum(["online", "typing"]);
+var presenceLocationSchema = z8.object({
+  environmentId: z8.string().optional(),
+  workspaceId: z8.string().optional()
 });
-var presenceEntrySchema = z7.object({
-  userId: z7.string(),
+var presenceEntrySchema = z8.object({
+  userId: z8.string(),
   status: presenceStatusSchema,
   location: presenceLocationSchema,
-  ts: z7.string()
+  ts: z8.string()
 });
-var updatePresenceRequestSchema = z7.object({
+var updatePresenceRequestSchema = z8.object({
   status: presenceStatusSchema,
   location: presenceLocationSchema.optional()
 });
@@ -7177,31 +7187,31 @@ function parseChatTranscriptArtifact(value) {
 }
 
 // ../shared/src/memory.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var MEMORY_ROOT = `${SANDBOX_PATHS.REPLICAS_DIR}/memories`;
 var MEMORY_INDEX_FILENAME = "MEMORY.md";
 var MEMORY_BUNDLE_FILENAME = "memory.tar.gz";
-var memoryExtractionResultSchema = z8.object({
-  seatSummary: z8.string().nullable(),
-  organizationSummary: z8.string().nullable()
+var memoryExtractionResultSchema = z9.object({
+  seatSummary: z9.string().nullable(),
+  organizationSummary: z9.string().nullable()
 });
-var { $schema: _, ...MEMORY_EXTRACTION_SCHEMA } = z8.toJSONSchema(memoryExtractionResultSchema);
-var memoryGenerationManifestSchema = z8.object({
-  domainId: z8.string(),
-  generation: z8.number().int().nonnegative(),
-  previousManifestKey: z8.string().nullable(),
-  createdAt: z8.string(),
-  promptVersion: z8.string(),
-  harness: z8.enum(["claude", "codex", "none"]),
-  model: z8.string(),
-  bundle: z8.object({
-    path: z8.literal(MEMORY_BUNDLE_FILENAME),
-    sha256: z8.string().regex(/^[a-f0-9]{64}$/),
-    sizeBytes: z8.number().int().positive()
+var { $schema: _, ...MEMORY_EXTRACTION_SCHEMA } = z9.toJSONSchema(memoryExtractionResultSchema);
+var memoryGenerationManifestSchema = z9.object({
+  domainId: z9.string(),
+  generation: z9.number().int().nonnegative(),
+  previousManifestKey: z9.string().nullable(),
+  createdAt: z9.string(),
+  promptVersion: z9.string(),
+  harness: z9.enum(["claude", "codex", "none"]),
+  model: z9.string(),
+  bundle: z9.object({
+    path: z9.literal(MEMORY_BUNDLE_FILENAME),
+    sha256: z9.string().regex(/^[a-f0-9]{64}$/),
+    sizeBytes: z9.number().int().positive()
   }).nullable(),
-  files: z8.record(z8.string(), z8.string()),
-  rollouts: z8.record(z8.string(), z8.string()),
-  rolloutSources: z8.record(z8.string(), z8.string()).optional()
+  files: z9.record(z9.string(), z9.string()),
+  rollouts: z9.record(z9.string(), z9.string()),
+  rolloutSources: z9.record(z9.string(), z9.string()).optional()
 });
 
 // ../shared/src/skill-registry.ts
@@ -7229,8 +7239,17 @@ export {
   isValidAgentProvider,
   VALID_THINKING_LEVELS,
   codexReasoningEffortForThinkingLevel,
+  getProviderDisplayName,
   detectAgentQuotaLimit,
   CREDENTIAL_METHOD,
+  agentCredentialSnapshotSchema,
+  isAgentChatTurnActivityRecord,
+  isAgentChatSkillActivityRecord,
+  isAgentChatMcpActivityRecord,
+  TOKEN_USAGE_PATH,
+  isTokenUsageCounts,
+  isTokenUsageUploadRecord,
+  fallbackPlanResponseSchema,
   ASTER_PROVIDER,
   ASTER_BASE_URL,
   ASTER_MODELS,
@@ -7275,17 +7294,10 @@ export {
   paginateEngineLogContent,
   coerceChatForkInfo,
   forkChatRequestSchema,
-  chatForkFallbackResponseSchema,
+  describeQuotaLimit,
   AGENT_QUOTA_EXHAUSTED_EVENT_TYPE,
   agentQuotaExhaustedPayloadSchema,
   defaultForkChatTitle,
-  agentCredentialSnapshotSchema,
-  isAgentChatTurnActivityRecord,
-  isAgentChatSkillActivityRecord,
-  isAgentChatMcpActivityRecord,
-  TOKEN_USAGE_PATH,
-  isTokenUsageCounts,
-  isTokenUsageUploadRecord,
   CLAUDE_PARTIAL_MESSAGE_EVENT_TYPE,
   getClaudePartialMessageStreamId,
   ACCEPTED_USER_MESSAGE_SOURCE,

package/dist/src/{chunk-3FHZVVPZ.js → chunk-ZQSFPKUG.js}

@@ -2,7 +2,7 @@
 import {
   HOOK_EXEC_MAX_BUFFER_BYTES,
   isVersionBelow
-} from "./chunk-EZ6Z6GSU.js";
+} from "./chunk-NQFMLRS4.js";
 
 // src/utils/presigned-upload.ts
 import { createReadStream } from "fs";
@@ -272,7 +272,7 @@ var DEFAULT_CODEX_ARGS = [
 var MIN_CODEX_CLI_VERSION = "0.144.6";
 var CODEX_UPGRADE_TIMEOUT_MS = 12e4;
 var codexCliVersionEnsured = null;
-var ENGINE_PACKAGE_VERSION = "0.1.735";
+var ENGINE_PACKAGE_VERSION = "0.1.736";
 var INITIALIZE_METHOD = "initialize";
 var INITIALIZED_NOTIFICATION = "initialized";
 var ACCOUNT_LOGIN_START_METHOD = "account/login/start";

package/dist/src/command-protection-hook.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import {
   evaluateCommandProtection
-} from "./chunk-CZXDETV5.js";
+} from "./chunk-KIBFWYCG.js";
 import {
   isRecord
 } from "./chunk-2RB7SIP3.js";
-import "./chunk-EZ6Z6GSU.js";
+import "./chunk-NQFMLRS4.js";
 
 // src/command-protection-hook.ts
 var provider = process.argv[2];

package/dist/src/deepseek-command-protection-plugin.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import {
   evaluateCommandProtection
-} from "./chunk-CZXDETV5.js";
+} from "./chunk-KIBFWYCG.js";
 import {
   notifyPostToolUse
-} from "./chunk-2VCV6W5F.js";
+} from "./chunk-AQXSBHCI.js";
 import "./chunk-2RB7SIP3.js";
-import "./chunk-EZ6Z6GSU.js";
+import "./chunk-NQFMLRS4.js";
 
 // src/deepseek-command-protection-plugin.ts
 function replicasCommandProtection(context) {

package/dist/src/headless-agent.js

@@ -4,12 +4,12 @@ import {
   buildCodexAgentEnv,
   putPresignedFile,
   recoverCompletedTurn
-} from "./chunk-3FHZVVPZ.js";
+} from "./chunk-ZQSFPKUG.js";
 import {
   AGENT,
   getMemoryOutputSafetyViolation,
   headlessAgentRequestSchema
-} from "./chunk-EZ6Z6GSU.js";
+} from "./chunk-NQFMLRS4.js";
 
 // src/headless-agent.ts
 import { createHash } from "crypto";

package/dist/src/index.js

@@ -8,7 +8,7 @@ import {
   monolithService,
   reportCommandProtectionBlock,
   setAgentCredentialSnapshot
-} from "./chunk-CZXDETV5.js";
+} from "./chunk-KIBFWYCG.js";
 import {
   ACCOUNT_RATE_LIMITS_UPDATED_METHOD,
   AGENT_MESSAGE_DELTA_METHOD,
@@ -36,7 +36,7 @@ import {
   execFileAsync,
   putPresignedFile,
   recoverCompletedTurn
-} from "./chunk-3FHZVVPZ.js";
+} from "./chunk-ZQSFPKUG.js";
 import {
   isRecord as isRecord2
 } from "./chunk-2RB7SIP3.js";
@@ -148,6 +148,7 @@ import {
   createUuidFromHex,
   decodePathSegments,
   defaultForkChatTitle,
+  describeQuotaLimit,
   detectAgentQuotaLimit,
   detectLanguageByPath,
   extractErrorText,
@@ -168,6 +169,7 @@ import {
   getFxTextChunk,
   getGoalCommand,
   getGoalCommandObjectiveValidationError,
+  getProviderDisplayName,
   getSlashCommandsForProvider,
   getUserMessage,
   getUserMessageId,
@@ -228,7 +230,7 @@ import {
   shellQuotePosix,
   stripAgentDiagnosticErrors,
   withTimeout
-} from "./chunk-EZ6Z6GSU.js";
+} from "./chunk-NQFMLRS4.js";
 
 // src/index.ts
 import { serve } from "@hono/node-server";
@@ -323,7 +325,10 @@ var BaseRefreshManager = class {
     try {
       console.log(`[${this.managerName}] Fetching fresh credentials from monolith (${params.failureKind})...`);
       const excludeCredentials = listExhaustedCredentials(params.provider);
-      await params.refresh(excludeCredentials.length > 0 ? { excludeCredentials } : {});
+      await params.refresh({
+        ...excludeCredentials.length > 0 ? { excludeCredentials } : {},
+        ...params.allowedMethods ? { allowedMethods: [...params.allowedMethods] } : {}
+      });
       if (params.isOauthNow()) {
         this.start().catch((error) => {
           console.error(`[${this.managerName}] Failed to restart OAuth refresh service after fallback:`, error);
@@ -1310,11 +1315,12 @@ var ClaudeTokenManager = class extends BaseRefreshManager {
     }
     console.log(`[ClaudeTokenManager] Credentials refreshed (method=${data.type})`);
   }
-  async fetchFreshCredentials(failureReason, failureKind = "rejected", failedCredential = ENGINE_ENV.REPLICAS_AGENT_CREDENTIALS.claude) {
+  async fetchFreshCredentials(failureReason, failureKind = "rejected", failedCredential = ENGINE_ENV.REPLICAS_AGENT_CREDENTIALS.claude, allowedMethods) {
     const failedMethod = failedCredential?.method === "oauth" || failedCredential?.method === "api_key" || failedCredential?.method === "bedrock" || failedCredential?.method === "foundry" ? failedCredential.method : ENGINE_ENV.REPLICAS_CLAUDE_AUTH_METHOD;
     return this.swapCredentials({
       provider: "claude",
       failureKind,
+      allowedMethods,
       refresh: (exclusions) => this.refreshWithRequest(failedMethod && failedMethod !== "none" ? {
         failedMethod,
         ...failedCredential?.method === failedMethod ? { failedCredential } : {},
@@ -1469,11 +1475,12 @@ var CodexTokenManager = class extends BaseRefreshManager {
       });
     }
   }
-  async fetchFreshCredentials(failureReason, failureKind = "rejected", failedCredential = ENGINE_ENV.REPLICAS_AGENT_CREDENTIALS.codex) {
+  async fetchFreshCredentials(failureReason, failureKind = "rejected", failedCredential = ENGINE_ENV.REPLICAS_AGENT_CREDENTIALS.codex, allowedMethods) {
     const failedMethod = failedCredential?.method === "oauth" || failedCredential?.method === "api_key" || failedCredential?.method === "foundry" ? failedCredential.method : ENGINE_ENV.REPLICAS_CODEX_AUTH_METHOD;
     return this.swapCredentials({
       provider: "codex",
       failureKind,
+      allowedMethods,
       refresh: async (exclusions) => {
         await this.refreshWithRequest(
           failedMethod === "oauth" || failedMethod === "api_key" || failedMethod === "foundry" ? {
@@ -1903,6 +1910,7 @@ var EnvironmentDetailsService = class {
     details.supportsClaudeMidTurnSteering = true;
     details.supportsGoalUpdates = true;
     details.supportsQueuedMessageEditing = true;
+    details.supportsChatForking = true;
     details.claudeAuthMethod = detectAgentAuthMethod(AGENT.CLAUDE);
     details.codexAuthMethod = detectAgentAuthMethod(AGENT.CODEX);
     details.cursorAuthMethod = detectAgentAuthMethod(AGENT.CURSOR);
@@ -3353,10 +3361,11 @@ var MuseTokenManager = class extends BaseRefreshManager {
   doRefresh() {
     return Promise.resolve();
   }
-  async fetchFreshCredentials(failureReason, failureKind = "exhausted", failedCredential = ENGINE_ENV.REPLICAS_AGENT_CREDENTIALS.muse) {
+  async fetchFreshCredentials(failureReason, failureKind = "exhausted", failedCredential = ENGINE_ENV.REPLICAS_AGENT_CREDENTIALS.muse, allowedMethods) {
     return this.swapCredentials({
       provider: "muse",
       failureKind,
+      allowedMethods,
       refresh: async (exclusions) => {
         const request = {
           failedMethod: CREDENTIAL_METHOD.MUSE_OAUTH,
@@ -3392,25 +3401,61 @@ var SWAPPABLE_AGENTS = {
   muse: museTokenManager
 };
 var AuthFallbackCoordinator = class {
-  constructor(provider, record) {
+  constructor(provider, record, context) {
     this.provider = provider;
     this.record = record;
+    this.context = context;
   }
   provider;
   record;
+  context;
   async fallBack(reason, detail) {
     const tokenManager = SWAPPABLE_AGENTS[this.provider];
-    if (!tokenManager) return "unavailable";
     const exhausted = ENGINE_ENV.REPLICAS_AGENT_CREDENTIALS[this.provider];
-    if (!exhausted) return "unavailable";
-    recordExhaustedCredential(this.provider, exhausted);
-    const swap = await tokenManager.fetchFreshCredentials(
-      `${this.provider} ${reason === "out_of_credits" ? "is out of credits" : "hit its usage limit"}: ${detail}`,
-      "exhausted"
-    );
-    if (!swap.ok && swap.error.code === "no_credentials") return "not_configured";
-    const applied = ENGINE_ENV.REPLICAS_AGENT_CREDENTIALS[this.provider] ?? exhausted;
-    const moved = swap.ok && !(applied.method === exhausted.method && applied.scope === exhausted.scope);
+    if (exhausted) recordExhaustedCredential(this.provider, exhausted);
+    const { userId, excludeProviders, forkable } = this.context();
+    const plan = await monolithService.getFallbackPlan({
+      provider: this.provider,
+      exhaustedMethod: exhausted?.method,
+      exclude: excludeProviders,
+      userId
+    });
+    if (!plan.ok && plan.error.code === "unavailable") {
+      console.error(`[AuthFallback] ${this.provider} fallback stopped; plan unavailable:`, plan.error.message);
+      return { outcome: "unavailable" };
+    }
+    const steps = plan.ok ? plan.data.steps : tokenManager && exhausted ? [{ kind: "credentials", methods: [] }] : [];
+    let failed = false;
+    for (const step of steps) {
+      if (step.kind === "harness") {
+        if (forkable && isAgentAvailable(step.provider)) return { outcome: "fork", target: step };
+        continue;
+      }
+      if (!tokenManager || !exhausted) continue;
+      const swap = await tokenManager.fetchFreshCredentials(
+        `${this.provider} ${describeQuotaLimit(reason)}: ${detail}`,
+        "exhausted",
+        void 0,
+        step.methods.length > 0 ? step.methods : void 0
+      );
+      if (!swap.ok) {
+        failed ||= swap.error.code !== "no_credentials";
+        continue;
+      }
+      const applied = ENGINE_ENV.REPLICAS_AGENT_CREDENTIALS[this.provider] ?? exhausted;
+      if (applied.method === exhausted.method && applied.scope === exhausted.scope) {
+        failed = true;
+        continue;
+      }
+      this.recordNotice(reason, exhausted, applied, "switched", detail);
+      return { outcome: "switched" };
+    }
+    if (!tokenManager || !exhausted) return { outcome: "unavailable" };
+    if (!failed) return { outcome: "not_configured" };
+    this.recordNotice(reason, exhausted, exhausted, "failed", "Replicas could not load an alternate credential.");
+    return { outcome: "failed" };
+  }
+  recordNotice(reason, exhausted, applied, status, detail) {
     const payload = {
       provider: this.provider,
       reason,
@@ -3418,13 +3463,12 @@ var AuthFallbackCoordinator = class {
       exhaustedScope: exhausted.scope,
       candidateMethod: applied.method,
       candidateScope: applied.scope,
-      status: moved ? "switched" : "failed",
-      detail: moved ? detail : "Replicas could not load an alternate credential."
+      status,
+      detail
     };
     const at = (/* @__PURE__ */ new Date()).toISOString();
     this.record({ timestamp: at, type: AUTH_FALLBACK_EVENT_TYPE, payload: { ...payload } });
     recordCredentialFallback({ ...payload, at });
-    return moved ? "switched" : "failed";
   }
 };
 
@@ -3686,10 +3730,10 @@ var CodingAgentManager = class {
     this.authFallback = options.provider ? new AuthFallbackCoordinator(options.provider, (event) => {
       this.onEvent(event);
       this.getHistorySink()?.append(event);
-    }) : null;
+    }, options.fallbackContext ?? (() => ({ excludeProviders: [], forkable: false }))) : null;
   }
   async fallBackCredential(reason, detail) {
-    if (!this.authFallback) return "unavailable";
+    if (!this.authFallback) return { outcome: "unavailable" };
     return this.authFallback.fallBack(reason, detail);
   }
   onTurnComplete = async () => {
@@ -5001,14 +5045,14 @@ var ClaudeManager = class _ClaudeManager extends CodingAgentManager {
           const quotaKind = _ClaudeManager.quotaLimitKind(error);
           if (quotaKind) {
             const detail = error instanceof ClaudeQuotaError ? error.message : extractErrorText(error);
-            const outcome = quotaFallbacks < MAX_QUOTA_FALLBACKS ? await this.fallBackCredential(quotaKind, detail) : "unavailable";
-            if (outcome === "switched") {
+            const fallback = quotaFallbacks < MAX_QUOTA_FALLBACKS ? await this.fallBackCredential(quotaKind, detail) : { outcome: "unavailable" };
+            if (fallback.outcome === "switched") {
               quotaFallbacks++;
               await this.tearDownSession();
               attempt++;
               continue;
             }
-            await this.emitQuotaExhaustedEvent(quotaKind, outcome, detail);
+            await this.emitQuotaExhaustedEvent(quotaKind, fallback, detail);
             return;
           }
           if (_ClaudeManager.isAuthError(error)) {
@@ -5119,11 +5163,16 @@ var ClaudeManager = class _ClaudeManager extends CodingAgentManager {
         return "Claude authentication failed after multiple attempts. Check your Claude, Anthropic API key, or Bedrock credentials in Settings \u2192 Agents and try again.";
     }
   }
-  async emitQuotaExhaustedEvent(kind, outcome, detail) {
+  async emitQuotaExhaustedEvent(kind, fallback, detail) {
     const limit = kind === "out_of_credits" ? "Claude ran out of credits on the credential this workspace is using." : "Claude hit the usage limit on the credential this workspace is using.";
-    const next = outcome === "failed" ? "The configured fallback credential could not be used. Check it in Settings \u2192 Agents and try again." : outcome === "not_configured" ? "No fallback credential is configured for this workspace. Add one in Settings \u2192 Agents, or try again once the limit resets." : "No other credential is available for this workspace. Check Settings \u2192 Agents, or try again once the limit resets.";
+    const next = fallback.outcome === "fork" ? `Forking this chat to ${getProviderDisplayName(fallback.target.provider, "long")}.` : fallback.outcome === "failed" ? "The next credential in the fallback chain could not be used. Check it in Settings \u2192 Fallbacks and try again." : fallback.outcome === "not_configured" ? "Nothing further is configured in the fallback chain. Add a credential or harness in Settings \u2192 Fallbacks, or try again once the limit resets." : "No other credential is available for this workspace. Check Settings \u2192 Fallbacks, or try again once the limit resets.";
     await this.emitTerminalErrorResult(detail, [`${limit} ${next}`]);
-    this.emitQuotaExhausted({ provider: "claude", reason: kind, detail });
+    this.emitQuotaExhausted({
+      provider: "claude",
+      reason: kind,
+      detail,
+      ...fallback.outcome === "fork" ? { forkTo: fallback.target } : {}
+    });
   }
   async emitMidTurnExhaustedEvent(error) {
     const detail = error instanceof Error ? error.message : String(error);
@@ -7001,11 +7050,11 @@ var CodexAspManager = class extends CodingAgentManager {
       let terminalError = error;
       if (terminalError instanceof CodexQuotaError && !quotaFallbackAttempted) {
         quotaFallbackAttempted = true;
-        const outcome = await this.fallBackCredential(
+        const fallback = await this.fallBackCredential(
           detectAgentQuotaLimit(terminalError.message) ?? "rate_limit",
           terminalError.message
         );
-        if (outcome === "switched") {
+        if (fallback.outcome === "switched") {
           attemptedCredential = ENGINE_ENV.REPLICAS_AGENT_CREDENTIALS.codex;
           const retryFailure = await this.restartAndRetry(dispatch);
           if (!retryFailure) return;
@@ -7015,7 +7064,8 @@ var CodexAspManager = class extends CodingAgentManager {
           this.emitQuotaExhausted({
             provider: "codex",
             reason: outOfCredits ? "out_of_credits" : detectAgentQuotaLimit(terminalError.message) ?? "rate_limit",
-            detail: terminalError.message
+            detail: terminalError.message,
+            ...fallback.outcome === "fork" ? { forkTo: fallback.target } : {}
           });
           if (outOfCredits) return;
         }
@@ -9782,8 +9832,8 @@ ${pending}
     } catch (error) {
       if (error instanceof MuseQuotaError) {
         const quotaKind = detectAgentQuotaLimit(error.message);
-        const outcome = await this.fallBackCredential(quotaKind ?? "rate_limit", error.message);
-        if (outcome === "switched") {
+        const fallback = await this.fallBackCredential(quotaKind ?? "rate_limit", error.message);
+        if (fallback.outcome === "switched") {
           this.stopProcess();
           try {
             await dispatch();
@@ -9794,6 +9844,8 @@ ${pending}
             }, this.historyFile);
             throw retryError;
           }
+        } else if (fallback.outcome === "fork") {
+          this.emitQuotaExhausted({ provider: "muse", reason: quotaKind ?? "rate_limit", detail: error.message, forkTo: fallback.target });
         }
         return;
       }
@@ -10186,7 +10238,7 @@ var OpencodeManager = class extends CodingAgentManager {
   slashCommandsCache = null;
   slashCommandsRequest = null;
   constructor(options) {
-    super(options);
+    super({ ...options, provider: "opencode" });
     this.sessionId = options.initialSessionId;
     this.historyFilePath = options.historyFilePath ?? join22(ENGINE_ENV.HOME_DIR, ".replicas", "opencode", "history.jsonl");
     this.historyFile = new CodexHistoryFile(this.historyFilePath);
@@ -10487,7 +10539,13 @@ var OpencodeManager = class extends CodingAgentManager {
     this.handledAccountRateLimit = true;
     const message = typeof status.message === "string" ? status.message : typeof action.message === "string" ? action.message : "OpenCode Go usage limit reached.";
     this.recordHistoryEvent("opencode-error", { message, code: "account_rate_limit" }, this.historyFile);
-    this.emitQuotaExhausted({ provider: "opencode", reason: "rate_limit", detail: message });
+    const fallback = await this.fallBackCredential("rate_limit", message);
+    this.emitQuotaExhausted({
+      provider: "opencode",
+      reason: "rate_limit",
+      detail: message,
+      ...fallback.outcome === "fork" ? { forkTo: fallback.target } : {}
+    });
     await this.abortActiveTurn();
   }
   recordOpencodeMessageRole(payload) {
@@ -13694,7 +13752,7 @@ var ChatService = class {
   /** Resolves once the target chat exists; the handoff and its first turn run in the background. */
   async forkChat(sourceChatId, request, trigger = "manual", reason) {
     const source = this.requireChat(sourceChatId);
-    if (!isAgentAvailable(request.provider)) throw new ChatProviderUnavailableError(request.provider);
+    if (trigger === "manual" && !isAgentAvailable(request.provider)) throw new ChatProviderUnavailableError(request.provider);
     const fork = {
       source: { chatId: source.persisted.id, provider: source.persisted.provider, title: source.persisted.title },
       trigger,
@@ -13719,6 +13777,7 @@ var ChatService = class {
     const fork = target?.persisted.fork;
     if (!target || !fork) return;
     try {
+      if (!isAgentAvailable(request.provider)) throw new ChatProviderUnavailableError(request.provider);
       const handoff = await buildForkHandoff({
         sourceChatId: fork.source.chatId,
         sourceProvider: fork.source.provider,
@@ -13771,20 +13830,15 @@ var ChatService = class {
     return providers;
   }
   async autoForkAfterQuota(chat, exhaustion) {
-    if (chat.persisted.parentChatId !== null || chat.persisted.deletedAt) return;
+    const target = exhaustion.forkTo;
+    if (!target || chat.persisted.deletedAt) return;
     const alreadyForked = [...this.chats.values()].some((other) => other.persisted.fork?.trigger === "auto" && other.persisted.fork.source.chatId === chat.persisted.id && !other.persisted.deletedAt);
     if (alreadyForked) return;
     const last = chat.lastSendRequest;
-    const fallback = await monolithService.getChatForkFallback({
-      provider: chat.persisted.provider,
-      exclude: this.forkChainProviders(chat),
-      userId: last?.senderUserId
-    });
-    if (!fallback?.provider || !isAgentAvailable(fallback.provider)) return;
     await this.forkChat(chat.persisted.id, {
-      provider: fallback.provider,
-      model: fallback.model,
-      thinkingLevel: fallback.thinkingLevel,
+      provider: target.provider,
+      model: target.model,
+      thinkingLevel: target.thinkingLevel,
       enableInteractiveTools: last?.enableInteractiveTools,
       senderUserId: last?.senderUserId,
       senderEmail: last?.senderEmail,
@@ -13908,6 +13962,15 @@ var ChatService = class {
       }).catch(() => {
       });
     };
+    const fallbackContext = () => {
+      const chat = this.chats.get(persisted.id);
+      return {
+        userId: chat?.lastSendRequest?.senderUserId,
+        excludeProviders: chat ? this.forkChainProviders(chat) : [persisted.provider],
+        // A subagent thread is driven by its parent's tool call, which a sibling chat would leave hanging.
+        forkable: (chat?.persisted ?? persisted).parentChatId === null
+      };
+    };
     if (persisted.parentChatId === void 0) {
       persisted.parentChatId = null;
     }
@@ -13921,7 +13984,8 @@ var ChatService = class {
         onTurnComplete: onProviderTurnComplete,
         onEvent: onProviderEvent,
         onProcessingChanged,
-        onMessageStarted
+        onMessageStarted,
+        fallbackContext
       });
     } else if (persisted.provider === "relay") {
       const getProviderAvailability = () => ({
@@ -14003,6 +14067,7 @@ var ChatService = class {
         onEvent: onProviderEvent,
         onProcessingChanged,
         onMessageStarted,
+        fallbackContext,
         onUsageUpdate: onProviderUsage
       });
     } else if (persisted.provider === "opencode") {
@@ -14015,7 +14080,8 @@ var ChatService = class {
         onEvent: onProviderEvent,
         onProcessingChanged,
         onMessageStarted,
-        onUsageUpdate: onProviderUsage
+        onUsageUpdate: onProviderUsage,
+        fallbackContext
       });
     } else if (persisted.provider === "pi") {
       provider = new PiManager({
@@ -14044,6 +14110,7 @@ var ChatService = class {
         onEvent: onProviderEvent,
         onProcessingChanged,
         onMessageStarted,
+        fallbackContext,
         onCodexTurnStarted: codexTokenUsage.onTurnStarted,
         onCodexTokenUsage: codexTokenUsage.onTokenUsage,
         onCodexModelRerouted: codexTokenUsage.onModelRerouted,

package/dist/src/post-tool-pr-hook.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import {
   notifyPostToolUse
-} from "./chunk-2VCV6W5F.js";
+} from "./chunk-AQXSBHCI.js";
 import {
   isRecord
 } from "./chunk-2RB7SIP3.js";
-import "./chunk-EZ6Z6GSU.js";
+import "./chunk-NQFMLRS4.js";
 
 // src/post-tool-pr-hook.ts
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicas-engine",
-  "version": "0.1.735",
+  "version": "0.1.736",
   "description": "Lightweight API server for Replicas workspaces",
   "type": "module",
   "main": "dist/src/index.js",