@remixhq/mcp 0.1.11 → 0.1.13

package/dist/cli.js

@@ -2,10 +2,7 @@
 
 // src/cli.ts
 import { createRequire } from "module";
-
-// src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { drainPendingFinalizeQueue } from "@remixhq/core/collab";
 
 // src/domain/apiClient.ts
 import { createApiClient as createCoreApiClient, resolveConfig as resolveConfig2 } from "@remixhq/core";
@@ -42,6 +39,10 @@ async function createApiClient() {
   });
 }
 
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
 // src/observability/logger.ts
 function createLogger() {
   return {
@@ -77,6 +78,7 @@ var ERROR_CODES = {
   DIRTY_WORKTREE: "DIRTY_WORKTREE",
   DETACHED_HEAD: "DETACHED_HEAD",
   PREFERRED_BRANCH_MISMATCH: "PREFERRED_BRANCH_MISMATCH",
+  FAMILY_SELECTION_AMBIGUOUS: "FAMILY_SELECTION_AMBIGUOUS",
   MISSING_HEAD: "MISSING_HEAD",
   REPO_LOCK_HELD: "REPO_LOCK_HELD",
   REPO_LOCK_TIMEOUT: "REPO_LOCK_TIMEOUT",
@@ -213,6 +215,14 @@ function normalizeByMessage(err) {
       category: "local_state"
     });
   }
+  if (message.includes("Multiple canonical Remix families") || message.includes("family selection is ambiguous")) {
+    return makeNormalized({
+      code: ERROR_CODES.FAMILY_SELECTION_AMBIGUOUS,
+      message,
+      hint,
+      category: "local_state"
+    });
+  }
   if (message.includes("Failed to resolve local HEAD")) {
     return makeNormalized({
       code: ERROR_CODES.MISSING_HEAD,
@@ -346,14 +356,6 @@ function assertConfirm(confirm, operation) {
   if (confirm) return;
   throw createPolicyError(`${operation} requires explicit confirmation.`, "Pass confirm=true to run this tool.");
 }
-function assertDiffWithinLimit(policy, diff) {
-  const sizeBytes = Buffer.byteLength(diff, "utf8");
-  if (sizeBytes <= policy.maxDiffBytes) return;
-  throw createPolicyError(
-    "Diff exceeds the configured maximum size for Remix MCP.",
-    `Configured limit=${policy.maxDiffBytes} bytes actual=${sizeBytes} bytes.`
-  );
-}
 
 // src/bootstrap/context.ts
 function createServerContext(params) {
@@ -501,8 +503,6 @@ var finalizeTurnInputSchema = {
   ...commonRequestFieldsSchema,
   prompt: z2.string().trim().min(1),
   assistantResponse: z2.string().trim().min(1),
-  diffSource: z2.enum(["worktree", "external"]).optional(),
-  externalDiff: z2.string().optional(),
   sync: z2.boolean().optional(),
   allowBranchMismatch: z2.boolean().optional(),
   idempotencyKey: z2.string().trim().min(1).optional()
@@ -510,11 +510,17 @@ var finalizeTurnInputSchema = {
 var previewInputSchema = {
   ...commonRequestFieldsSchema
 };
+var drainFinalizeQueueInputSchema = {
+  ...commonRequestFieldsSchema
+};
 var applyInputSchema = {
   ...commonRequestFieldsSchema,
   confirm: z2.boolean(),
   allowBranchMismatch: z2.boolean().optional()
 };
+var reAnchorInputSchema = {
+  ...applyInputSchema
+};
 var requestMergeInputSchema = {
   ...commonRequestFieldsSchema
 };
@@ -624,7 +630,10 @@ var initDataSchema = z2.object({
   dashboardUrl: z2.string().url(),
   upstreamAppId: z2.string(),
   bindingPath: z2.string(),
-  repoRoot: z2.string()
+  repoRoot: z2.string(),
+  bindingMode: z2.enum(["legacy", "lane", "explicit_root"]).optional(),
+  createdCanonicalFamily: z2.boolean().optional(),
+  baselineStatus: z2.enum(["seeded", "existing", "requires_re_anchor", "requires_sync"]).optional()
 });
 var listDataSchema = z2.object({
   apps: genericArraySchema,
@@ -647,19 +656,26 @@ var checkoutDataSchema = z2.object({
   repoRoot: z2.string()
 });
 var addDataSchema = z2.object({
-  changeStep: genericRecordSchema,
-  autoSync: genericRecordSchema
+  changeStep: genericRecordSchema
 });
 var recordTurnDataSchema = genericRecordSchema;
 var finalizeTurnDataSchema = z2.object({
   mode: z2.enum(["changed_turn", "no_diff_turn"]),
   idempotencyKey: z2.string().min(1),
+  queued: z2.boolean(),
+  jobId: z2.string().nullable(),
+  repoState: z2.string().nullable(),
   changeStep: genericRecordSchema.nullable(),
   collabTurn: genericRecordSchema.nullable(),
   autoSync: genericRecordSchema.nullable(),
   warnings: z2.array(z2.string())
 });
+var drainFinalizeQueueDataSchema = z2.object({
+  processed: z2.number().int().nonnegative(),
+  results: z2.array(genericRecordSchema)
+});
 var syncDataSchema = genericRecordSchema;
+var reAnchorDataSchema = genericRecordSchema;
 var requestMergeDataSchema = genericRecordSchema;
 var mergeRequestQueueDataSchema = z2.object({
   queue: mergeRequestQueueSchema,
@@ -734,7 +750,9 @@ var checkoutSuccessSchema = makeSuccessSchema(checkoutDataSchema);
 var addSuccessSchema = makeSuccessSchema(addDataSchema);
 var recordTurnSuccessSchema = makeSuccessSchema(recordTurnDataSchema);
 var finalizeTurnSuccessSchema = makeSuccessSchema(finalizeTurnDataSchema);
+var drainFinalizeQueueSuccessSchema = makeSuccessSchema(drainFinalizeQueueDataSchema);
 var syncSuccessSchema = makeSuccessSchema(syncDataSchema);
+var reAnchorSuccessSchema = makeSuccessSchema(reAnchorDataSchema);
 var requestMergeSuccessSchema = makeSuccessSchema(requestMergeDataSchema);
 var mergeRequestQueueSuccessSchema = makeSuccessSchema(mergeRequestQueueDataSchema);
 var viewMergeRequestSuccessSchema = makeSuccessSchema(viewMergeRequestDataSchema);
@@ -752,17 +770,18 @@ var accessDebugSuccessSchema = makeSuccessSchema(accessDebugDataSchema);
 var updateMemberRoleSuccessSchema = makeSuccessSchema(updateMemberRoleDataSchema);
 
 // src/domain/coreAdapter.ts
+import { spawn } from "child_process";
 import {
   collabList as coreCollabList,
   collabListMembers as coreCollabListMembers,
   collabUpdateMemberRole as coreCollabUpdateMemberRole,
-  collabAdd as coreCollabAdd,
+  drainPendingFinalizeQueue as coreDrainPendingFinalizeQueue,
   collabFinalizeTurn as coreCollabFinalizeTurn,
-  collabRecordTurn as coreCollabRecordTurn,
   collabApprove as coreCollabApprove,
   collabCheckout as coreCollabCheckout,
   collabListMergeRequests as coreCollabListMergeRequests,
   collabInit as coreCollabInit,
+  collabReAnchor as coreCollabReAnchor,
   collabInvite as coreCollabInvite,
   collabReconcile as coreCollabReconcile,
   collabReject as coreCollabReject,
@@ -773,10 +792,13 @@ import {
   collabSyncUpstream as coreCollabSyncUpstream,
   collabView as coreCollabView
 } from "@remixhq/core/collab";
-import { findGitRoot, getHeadCommitHash, listUntrackedFiles } from "@remixhq/core/repo";
+import { findGitRoot } from "@remixhq/core/repo";
 function getRiskLevel(status) {
   if (status.recommendedAction === "reconcile") return "high";
-  if (status.recommendedAction === "sync" || status.remote.incomingOpenMergeRequestCount) return "medium";
+  if (status.recommendedAction === "choose_family" || status.recommendedAction === "await_finalize") return "medium";
+  if (status.recommendedAction === "pull" || status.recommendedAction === "re_anchor" || status.remote.incomingOpenMergeRequestCount) {
+    return "medium";
+  }
   if (status.repo.branchMismatch || !status.repo.isGitRepo || !status.binding.isBound || !status.repo.worktree.isClean) return "medium";
   return "low";
 }
@@ -789,12 +811,22 @@ function getRecommendedNextActions(status) {
   switch (status.recommendedAction) {
     case "init":
       return ["Run remix_collab_init to bind the repository to Remix before using any Remix collaboration mutation flow."];
-    case "sync":
-      return ["Run remix_collab_sync_preview, then remix_collab_sync_apply if the preview is acceptable. Use this instead of raw git pull or rebase for bound-repo alignment."];
+    case "pull":
+      return ["Run remix_collab_sync_preview, then remix_collab_sync_apply if the preview is acceptable. This pulls the server delta into the local working tree without rewriting local git history."];
+    case "re_anchor":
+      return ["Run remix_collab_re_anchor_preview, then remix_collab_re_anchor_apply to re-anchor the lane after manual Git/GitHub history movement."];
     case "reconcile":
-      return ["Run remix_collab_reconcile_preview before attempting remix_collab_reconcile_apply. Reconcile is the explicit Remix recovery path when fast-forward sync is no longer possible."];
+      return ["Run remix_collab_reconcile_preview before attempting remix_collab_reconcile_apply. Reconcile now routes through the explicit Remix recovery/re-anchor flow for diverged state."];
+    case "await_finalize":
+      return [
+        "Run remix_collab_drain_finalize_queue before merge-related or recovery flows. finalize_turn is queued only until the local finalize queue is drained."
+      ];
     case "review_queue":
       return ["Run remix_collab_review_queue to inspect reviewable merge requests instead of using local git merge flows."];
+    case "choose_family":
+      return [
+        "This checkout is ambiguous across multiple canonical Remix families. Continue from a checkout already bound to the intended family, or run remix_collab_init with forceNew=true to create and bind a new canonical family."
+      ];
     default:
       return [];
   }
@@ -822,6 +854,17 @@ function truncateText(value, maxChars) {
     originalChars: value.length
   };
 }
+function spawnFinalizeQueueDrainer() {
+  const entrypoint = process.argv[1];
+  if (!entrypoint) return false;
+  const child = spawn(process.execPath, [...process.execArgv, entrypoint, "--drain-finalize-queue"], {
+    detached: true,
+    stdio: "ignore",
+    env: process.env
+  });
+  child.unref();
+  return true;
+}
 async function getStatus(params) {
   const api = params.includeRemote ? await createCollabApiClient() : null;
   const status = await coreCollabStatus({
@@ -852,7 +895,11 @@ async function initCollab(params) {
   return {
     data: result,
     warnings: collectResultWarnings(result),
-    recommendedNextActions: ["Run remix_collab_status to inspect sync, reconcile, and merge-request readiness before mutating bound-repo state."],
+    recommendedNextActions: result.baselineStatus === "requires_re_anchor" ? [
+      "Run remix_collab_re_anchor_preview, then remix_collab_re_anchor_apply to anchor this checkout before recording turns."
+    ] : result.baselineStatus === "requires_sync" ? [
+      "Run remix_collab_sync_preview, then remix_collab_sync_apply to pull the server delta and create the first local baseline for this checkout."
+    ] : ["Run remix_collab_status to inspect sync, reconcile, and merge-request readiness before mutating bound-repo state."],
     logContext: {
       repoRoot: result.repoRoot,
       appId: result.appId
@@ -922,23 +969,44 @@ async function finalizeCollabTurn(params) {
     cwd: params.cwd,
     prompt: params.prompt,
     assistantResponse: params.assistantResponse,
-    diff: params.externalDiff ?? null,
-    diffSource: params.diffSource,
     sync: params.sync,
     allowBranchMismatch: params.allowBranchMismatch ?? false,
     idempotencyKey: params.idempotencyKey ?? null,
     actor: params.agent
   });
+  if (result.queued) {
+    if (!spawnFinalizeQueueDrainer()) {
+      await coreDrainPendingFinalizeQueue({ api });
+    }
+  }
   return {
     data: result,
     warnings: result.warnings,
-    recommendedNextActions: [],
+    recommendedNextActions: result.queued ? ["Run remix_collab_drain_finalize_queue before merge-related flows if you need this queued turn recorded immediately."] : [],
     logContext: {
       repoRoot,
       appId: result.changeStep?.appId ?? result.collabTurn?.appId ?? null
     }
   };
 }
+async function drainFinalizeQueue(params) {
+  const api = await createCollabApiClient();
+  const repoRoot = await findGitRoot(params.cwd);
+  const results = await coreDrainPendingFinalizeQueue({ api });
+  const warnings = results.flatMap((result) => collectResultWarnings(result));
+  return {
+    data: {
+      processed: results.length,
+      results
+    },
+    warnings,
+    recommendedNextActions: [],
+    logContext: {
+      repoRoot,
+      appId: null
+    }
+  };
+}
 async function syncCollab(params) {
   const api = await createCollabApiClient();
   const result = await coreCollabSync({
@@ -950,12 +1018,33 @@ async function syncCollab(params) {
   return {
     data: result,
     warnings: collectResultWarnings(result),
-    recommendedNextActions: params.dryRun ? ["Run remix_collab_sync_apply with confirm=true to apply this fast-forward update instead of using raw git pull or rebase."] : [],
+    recommendedNextActions: params.dryRun ? result.status === "delta_ready" ? ["Run remix_collab_sync_apply with confirm=true to apply this server delta into the local working tree."] : result.status === "base_unknown" ? [
+      "Direct pull is unavailable because Remix cannot diff from the last acknowledged server head.",
+      "Run remix_collab_reconcile_preview next to inspect recovery options before applying any recovery flow."
+    ] : [] : [],
     logContext: {
       repoRoot: result.repoRoot
     }
   };
 }
+async function reAnchor(params) {
+  const api = await createCollabApiClient();
+  const result = await coreCollabReAnchor({
+    api,
+    cwd: params.cwd,
+    dryRun: params.dryRun,
+    allowBranchMismatch: params.allowBranchMismatch ?? false
+  });
+  return {
+    data: result,
+    warnings: collectWarnings(result.warnings),
+    recommendedNextActions: params.dryRun ? ["Run remix_collab_re_anchor_apply with confirm=true to re-anchor this lane after manual Git/GitHub history movement."] : [],
+    logContext: {
+      repoRoot: result.repoRoot,
+      appId: result.currentAppId
+    }
+  };
+}
 async function requestMerge(params) {
   const api = await createCollabApiClient();
   const result = await coreCollabRequestMerge({
@@ -1129,8 +1218,8 @@ async function reconcile(params) {
   return {
     data: result,
     warnings: collectWarnings(result.warnings),
-    recommendedNextActions: params.dryRun ? ["Run remix_collab_reconcile_apply with confirm=true only if the preview is acceptable. Do not replace this with raw git history-rewrite commands."] : [],
-    risks: params.dryRun ? ["Reconcile apply rewrites local history and creates a backup branch."] : [],
+    recommendedNextActions: params.dryRun ? ["Run remix_collab_reconcile_apply with confirm=true only if the preview is acceptable. This is the explicit Remix recovery flow for diverged state."] : [],
+    risks: params.dryRun ? ["Reconcile may upload local history to re-anchor the server lane before future recording continues."] : [],
     logContext: {
       repoRoot: result.repoRoot ?? null
     }
@@ -1706,9 +1795,6 @@ function buildSuccessEnvelope(tool, requestId, result) {
   };
 }
 function deriveErrorRisks(tool, normalized) {
-  if (isFinalizeTurnLocalSyncFailure(tool, normalized)) {
-    return ["The change step succeeded remotely, but the local repository may need manual recovery or a follow-up sync."];
-  }
   if (normalized.code === "DESTRUCTIVE_OPERATION_BLOCKED") {
     return ["A policy guard blocked a potentially destructive or state-mutating operation."];
   }
@@ -1720,16 +1806,9 @@ function deriveErrorRisks(tool, normalized) {
   }
   return [];
 }
-function isFinalizeTurnLocalSyncFailure(tool, normalized) {
-  return tool === "remix_collab_finalize_turn" && normalized.message === "Change step succeeded remotely, but automatic local sync failed.";
-}
 function buildErrorEnvelope(tool, requestId, error) {
   const normalized = normalizeToolError(error);
-  const recommendedNextActions = isFinalizeTurnLocalSyncFailure(tool, normalized) ? [
-    "Run `remix_collab_status` to confirm the bound repo state before attempting recovery.",
-    "Run `remix_collab_sync_preview` next, then `remix_collab_sync_apply` with `confirm=true` if the preview looks correct.",
-    "Inspect `error.hint` for any preserved diff backup path before retrying local recovery, and do not rerun `remix_collab_finalize_turn` immediately."
-  ] : normalized.code === "AUTH_REQUIRED" ? ["Set COMERGE_ACCESS_TOKEN, then retry the tool call."] : normalized.code === "REPO_LOCK_TIMEOUT" ? ["Wait for the active Remix mutation to finish, then retry the tool call."] : normalized.code === "REPO_STATE_CHANGED_DURING_OPERATION" ? ["Review local repository changes, then rerun the tool once the worktree is stable."] : normalized.code === "PREFERRED_BRANCH_MISMATCH" ? ["Switch to the repository's preferred Remix branch, or rerun with allowBranchMismatch=true if intentional."] : [];
+  const recommendedNextActions = normalized.code === "AUTH_REQUIRED" ? ["Set COMERGE_ACCESS_TOKEN, then retry the tool call."] : normalized.code === "REPO_LOCK_TIMEOUT" ? ["Wait for the active Remix mutation to finish, then retry the tool call."] : normalized.code === "REPO_STATE_CHANGED_DURING_OPERATION" ? ["Review local repository changes, then rerun the tool once the worktree is stable."] : normalized.code === "PREFERRED_BRANCH_MISMATCH" ? ["Switch to the repository's preferred Remix branch, or rerun with allowBranchMismatch=true if intentional."] : [];
   return {
     schemaVersion: SCHEMA_VERSION,
     ok: false,
@@ -1875,7 +1954,7 @@ function registerCollabTools(server, context) {
   });
   registerTool(server, context, {
     name: "remix_collab_finalize_turn",
-    description: "Primary turn recorder for the current bound repository. Call this exactly once before the final response; it records a changed turn when the worktree has a diff, records a no-diff turn when it does not, and can accept an explicit external diff when needed.",
+    description: "Primary turn recorder for the current bound repository. Call this exactly once before the final response; it captures the current boundary locally and queues remote processing. Queued only: no remote change step exists yet until the finalize queue is drained.",
     access: "local_write",
     inputSchema: finalizeTurnInputSchema,
     outputSchema: finalizeTurnSuccessSchema,
@@ -1883,15 +1962,10 @@ function registerCollabTools(server, context) {
     run: async (args) => {
       const input = z3.object(finalizeTurnInputSchema).parse(args);
       const cwd = resolvePolicyCwd(context.policy, input.cwd);
-      if ((input.diffSource ?? "worktree") === "external" || typeof input.externalDiff === "string") {
-        assertDiffWithinLimit(context.policy, input.externalDiff ?? "");
-      }
       return finalizeCollabTurn({
         cwd,
         prompt: input.prompt,
         assistantResponse: input.assistantResponse,
-        diffSource: input.diffSource,
-        externalDiff: input.externalDiff,
         sync: input.sync,
         allowBranchMismatch: input.allowBranchMismatch ?? false,
         idempotencyKey: input.idempotencyKey,
@@ -1899,9 +1973,22 @@ function registerCollabTools(server, context) {
       });
     }
   });
+  registerTool(server, context, {
+    name: "remix_collab_drain_finalize_queue",
+    description: "Drain the local finalize queue and record queued finalize_turn jobs immediately. Use this before request-merge, reconcile, or other flows that require the remote change step to exist already.",
+    access: "local_write",
+    inputSchema: drainFinalizeQueueInputSchema,
+    outputSchema: drainFinalizeQueueSuccessSchema,
+    annotations: getAnnotations("local_write", { idempotent: true }),
+    run: async (args) => {
+      const input = z3.object(drainFinalizeQueueInputSchema).parse(args);
+      const cwd = resolvePolicyCwd(context.policy, input.cwd);
+      return drainFinalizeQueue({ cwd });
+    }
+  });
   registerTool(server, context, {
     name: "remix_collab_sync_preview",
-    description: "Preview whether the current bound repository can be fast-forward synced to the Remix app state. Use this instead of raw git pull or rebase for bound-repo alignment.",
+    description: "Preview whether the current bound repository can pull the server delta into the working tree. Use this instead of raw git pull or rebase for bound-repo alignment.",
     access: "read",
     inputSchema: previewInputSchema,
     outputSchema: syncSuccessSchema,
@@ -1913,7 +2000,7 @@ function registerCollabTools(server, context) {
   });
   registerTool(server, context, {
     name: "remix_collab_sync_apply",
-    description: "Fast-forward sync the current bound repository to the Remix app state. This is the Remix-native replacement for raw git pull or rebase in a bound repo.",
+    description: "Pull the server delta into the local working tree without moving local git history. This is the Remix-native replacement for raw git pull or rebase in a bound repo.",
     access: "local_write",
     inputSchema: applyInputSchema,
     outputSchema: syncSuccessSchema,
@@ -1924,6 +2011,31 @@ function registerCollabTools(server, context) {
       return syncCollab({ cwd, dryRun: false, allowBranchMismatch: input.allowBranchMismatch ?? false });
     }
   });
+  registerTool(server, context, {
+    name: "remix_collab_re_anchor_preview",
+    description: "Preview whether the current checkout needs an explicit re-anchor to adopt or recover external Git/GitHub history.",
+    access: "read",
+    inputSchema: previewInputSchema,
+    outputSchema: reAnchorSuccessSchema,
+    run: async (args) => {
+      const input = z3.object(previewInputSchema).parse(args);
+      const cwd = resolvePolicyCwd(context.policy, input.cwd);
+      return reAnchor({ cwd, dryRun: true });
+    }
+  });
+  registerTool(server, context, {
+    name: "remix_collab_re_anchor_apply",
+    description: "Explicitly re-anchor the current lane to adopted or recovered external Git/GitHub history, without rewriting the local checkout afterward.",
+    access: "local_write",
+    inputSchema: reAnchorInputSchema,
+    outputSchema: reAnchorSuccessSchema,
+    run: async (args) => {
+      const input = z3.object(reAnchorInputSchema).parse(args);
+      assertConfirm(input.confirm, "remix_collab_re_anchor_apply");
+      const cwd = resolvePolicyCwd(context.policy, input.cwd);
+      return reAnchor({ cwd, dryRun: false, allowBranchMismatch: input.allowBranchMismatch ?? false });
+    }
+  });
   registerTool(server, context, {
     name: "remix_collab_request_merge",
     description: "Open a prompt-backed Remix merge request from the current bound repository to its upstream app instead of merging locally with raw git.",
@@ -2064,7 +2176,7 @@ function registerCollabTools(server, context) {
   });
   registerTool(server, context, {
     name: "remix_collab_reconcile_preview",
-    description: "Preview reconcile readiness when the local repository cannot be fast-forward synced. Use this before any explicit Remix history-repair workflow.",
+    description: "Preview the explicit Remix recovery flow when local and server state diverged beyond a simple pull.",
     access: "read",
     inputSchema: previewInputSchema,
     outputSchema: reconcileSuccessSchema,
@@ -2076,7 +2188,7 @@ function registerCollabTools(server, context) {
   });
   registerTool(server, context, {
     name: "remix_collab_reconcile_apply",
-    description: "Reconcile divergent local history against the bound Remix app and update the local checkout. This is the explicit Remix recovery path for divergent history.",
+    description: "Run the explicit Remix recovery flow for diverged local/server state.",
     access: "local_write",
     inputSchema: applyInputSchema,
     outputSchema: reconcileSuccessSchema,
@@ -3201,6 +3313,19 @@ import { z as z9 } from "zod";
 // src/contracts/ops.ts
 import { z as z8 } from "zod";
 var genericRecordSchema4 = z8.record(z8.string(), z8.unknown());
+var appJobKindSchema = z8.enum([
+  "fork",
+  "edit",
+  "bundle",
+  "import_github",
+  "import_upload",
+  "merge",
+  "revert",
+  "change_step",
+  "reconcile",
+  "change_step_replay"
+]);
+var appJobStatusSchema = z8.enum(["pending", "enqueued", "processing", "succeeded", "failed", "cancelled"]);
 var appScopedInputSchema = {
   ...commonRequestFieldsSchema,
   appId: z8.string().trim().min(1).optional()
@@ -3210,6 +3335,13 @@ var editQueueInputSchema = {
   limit: z8.number().int().positive().max(100).optional(),
   offset: z8.number().int().nonnegative().optional()
 };
+var appJobQueueInputSchema = {
+  ...appScopedInputSchema,
+  limit: z8.number().int().positive().max(100).optional(),
+  offset: z8.number().int().nonnegative().optional(),
+  kind: z8.array(appJobKindSchema).min(1).optional(),
+  status: z8.array(appJobStatusSchema).min(1).optional()
+};
 var bundleInputSchema = {
   ...appScopedInputSchema,
   bundleId: z8.string().trim().min(1)
@@ -3242,6 +3374,7 @@ var agentRunEventsInputSchema = {
 };
 var appOverviewSuccessSchema = makeSuccessSchema(genericRecordSchema4);
 var editQueueSuccessSchema = makeSuccessSchema(genericRecordSchema4);
+var appJobQueueSuccessSchema = makeSuccessSchema(genericRecordSchema4);
 var bundleSuccessSchema = makeSuccessSchema(genericRecordSchema4);
 var timelineSuccessSchema = makeSuccessSchema(genericRecordSchema4);
 var agentRunsSuccessSchema = makeSuccessSchema(genericRecordSchema4);
@@ -3275,7 +3408,7 @@ async function getAppOverview(params) {
     data,
     warnings: [],
     recommendedNextActions: [
-      "Use `remix_ops_list_timeline`, `remix_ops_list_agent_runs`, `remix_ops_get_edit_queue`, or `remix_ops_get_sandbox_status` for the next operational drill-down on this app."
+      "Use `remix_ops_list_timeline`, `remix_ops_list_agent_runs`, `remix_ops_get_edit_queue`, `remix_ops_list_app_job_queue`, or `remix_ops_get_sandbox_status` for the next operational drill-down on this app."
     ],
     logContext: target
   };
@@ -3298,6 +3431,42 @@ async function getEditQueue(params) {
     logContext: target
   };
 }
+async function listAppJobQueue(params) {
+  const api = await createApiClient();
+  const target = await resolveAppTarget(api, params);
+  const data = unwrapResponseObject(
+    await api.listAppJobQueue(target.appId, {
+      limit: params.limit,
+      offset: params.offset,
+      kind: params.kind,
+      status: params.status
+    }),
+    "app job queue"
+  );
+  const pageInfo = typeof data.pageInfo === "object" && data.pageInfo ? data.pageInfo : null;
+  const items = Array.isArray(data.items) ? data.items : [];
+  const activeBlockingKinds = /* @__PURE__ */ new Set(["merge", "change_step", "change_step_replay", "reconcile", "revert"]);
+  const hasBlockingJobs = items.some((item) => {
+    if (!item || typeof item !== "object") return false;
+    const record = item;
+    return typeof record.kind === "string" && activeBlockingKinds.has(record.kind) && (typeof record.status !== "string" || ["pending", "enqueued", "processing"].includes(record.status));
+  });
+  const recommendedNextActions = [];
+  if (hasBlockingJobs) {
+    recommendedNextActions.push(
+      "Inspect the returned active workflow jobs before concluding that merge, replay, reconcile, or revert work is stuck. This surface reflects backend app-scoped queue state, not local finalize state."
+    );
+  }
+  if (pageInfo?.hasMore === true && typeof pageInfo.limit === "number" && typeof pageInfo.offset === "number") {
+    recommendedNextActions.push(`Pass offset=${pageInfo.offset + pageInfo.limit} to load the next app job queue page.`);
+  }
+  return {
+    data,
+    warnings: [],
+    recommendedNextActions,
+    logContext: target
+  };
+}
 async function getBundle(params) {
   const api = await createApiClient();
   const target = await resolveAppTarget(api, params);
@@ -3524,6 +3693,25 @@ function registerOpsTools(server, context) {
       });
     }
   });
+  registerTool4(server, context, {
+    name: "remix_ops_list_app_job_queue",
+    description: "Inspect bounded app-scoped workflow queue jobs for one app, including active backend work such as merge, replay, reconcile, revert, bundle, or import processing.",
+    access: "read",
+    inputSchema: appJobQueueInputSchema,
+    outputSchema: appJobQueueSuccessSchema,
+    run: async (args) => {
+      const input = z9.object(appJobQueueInputSchema).parse(args);
+      const cwd = input.cwd ? resolvePolicyCwd(context.policy, input.cwd) : void 0;
+      return listAppJobQueue({
+        appId: input.appId,
+        cwd,
+        limit: input.limit,
+        offset: input.offset,
+        kind: input.kind,
+        status: input.status
+      });
+    }
+  });
   registerTool4(server, context, {
     name: "remix_ops_get_bundle",
     description: "Inspect one app bundle by id without downloading the artifact payload.",
@@ -3654,6 +3842,11 @@ async function startStdioServer(params) {
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
 async function main() {
+  if (process.argv.includes("--drain-finalize-queue")) {
+    const api = await createCollabApiClient();
+    await drainPendingFinalizeQueue({ api });
+    return;
+  }
   await startStdioServer({ version });
 }
 main().catch((error) => {