@remixhq/mcp 0.1.12 → 0.1.14

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 { drainAsyncJobs, 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 {
@@ -355,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) {
@@ -510,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()
@@ -519,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
 };
@@ -626,7 +623,7 @@ var statusDataSchema = z2.object({
   status: genericRecordSchema,
   riskLevel: z2.enum(["low", "medium", "high"])
 });
-var initDataSchema = z2.object({
+var initSyncDataSchema = z2.object({
   reused: z2.boolean(),
   projectId: z2.string(),
   appId: z2.string(),
@@ -635,8 +632,26 @@ var initDataSchema = z2.object({
   bindingPath: z2.string(),
   repoRoot: z2.string(),
   bindingMode: z2.enum(["legacy", "lane", "explicit_root"]).optional(),
-  createdCanonicalFamily: z2.boolean().optional()
+  createdCanonicalFamily: z2.boolean().optional(),
+  baselineStatus: z2.enum(["seeded", "existing", "requires_re_anchor", "requires_sync"]).optional()
 });
+var initQueuedDataSchema = z2.object({
+  queued: z2.literal(true),
+  status: z2.literal("ready_to_record"),
+  doNotRetry: z2.literal(true),
+  jobId: z2.string(),
+  projectId: z2.string(),
+  appId: z2.string(),
+  dashboardUrl: z2.string(),
+  upstreamAppId: z2.string(),
+  bindingPath: z2.string(),
+  repoRoot: z2.string(),
+  bindingMode: z2.enum(["legacy", "lane", "explicit_root"]),
+  createdCanonicalFamily: z2.boolean(),
+  remoteUrl: z2.string().nullable(),
+  defaultBranch: z2.string().nullable()
+});
+var initDataSchema = initSyncDataSchema;
 var listDataSchema = z2.object({
   apps: genericArraySchema,
   pagination: paginationSchema
@@ -658,19 +673,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,
@@ -745,7 +767,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);
@@ -763,17 +787,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,
@@ -784,11 +809,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 === "choose_family") return "medium";
-  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";
 }
@@ -801,10 +828,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. This seeds a local Remix baseline. It is required because no local baseline exists for this lane yet (fresh clone, deleted .remix/ state, or first init didn't seed) \u2014 not because of any specific git operation. After it succeeds, normal recording (remix_collab_finalize_turn) becomes available."
+      ];
+    case "record":
+      return [
+        "Run remix_collab_finalize_turn to capture the local boundary delta. This is the catch-all for any local content change since the last recorded turn, regardless of whether the change came from agent edits, manual user edits, git commit, git pull, git merge, git rebase, or git reset."
+      ];
     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 applies only when both the local workspace and the server lane changed since the last agreed baseline."];
+    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":
@@ -838,6 +877,21 @@ 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 drainBeforeMutation(api) {
+  const results = await coreDrainPendingFinalizeQueue({ api });
+  return results.flatMap((result) => collectResultWarnings(result));
+}
 async function getStatus(params) {
   const api = params.includeRemote ? await createCollabApiClient() : null;
   const status = await coreCollabStatus({
@@ -863,15 +917,26 @@ async function initCollab(params) {
     api,
     cwd: params.cwd,
     appName: params.appName ?? null,
-    forceNew: params.forceNew ?? false
+    forceNew: params.forceNew ?? false,
+    asyncSubmit: false
   });
+  if ("queued" in result && result.queued) {
+    throw new Error(
+      "Unexpected queued init result on the MCP path. Async init is currently disabled for agent callers; if you intended to re-enable it, also restore the queued shape in initDataSchema (see remix-mcp/src/contracts/collab.ts)."
+    );
+  }
+  const syncResult = result;
   return {
-    data: result,
+    data: syncResult,
     warnings: collectResultWarnings(result),
-    recommendedNextActions: ["Run remix_collab_status to inspect sync, reconcile, and merge-request readiness before mutating bound-repo state."],
+    recommendedNextActions: syncResult.baselineStatus === "requires_re_anchor" ? [
+      "This checkout has no local Remix baseline yet. Run remix_collab_re_anchor_preview, then remix_collab_re_anchor_apply to seed one. After it succeeds, normal recording (remix_collab_finalize_turn) becomes available."
+    ] : syncResult.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
+      repoRoot: syncResult.repoRoot,
+      appId: syncResult.appId
     }
   };
 }
@@ -938,23 +1003,46 @@ 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
+    actor: params.agent,
+    awaitingUsageDeadlineMs: params.awaitingUsageDeadlineMs ?? null
   });
+  const hasAwaitingDeadline = typeof params.awaitingUsageDeadlineMs === "number" && params.awaitingUsageDeadlineMs > 0;
+  if (result.queued && !hasAwaitingDeadline) {
+    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({
@@ -966,21 +1054,45 @@ 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 seed a local Remix baseline for this checkout. Re-anchor is for missing-baseline cases only and does not replace remix_collab_finalize_turn for ordinary local content changes."
+    ] : [],
+    logContext: {
+      repoRoot: result.repoRoot,
+      appId: result.currentAppId
+    }
+  };
+}
 async function requestMerge(params) {
   const api = await createCollabApiClient();
+  const drainWarnings = await drainBeforeMutation(api);
   const result = await coreCollabRequestMerge({
     api,
     cwd: params.cwd
   });
   return {
     data: result,
-    warnings: [],
+    warnings: drainWarnings,
     recommendedNextActions: result.id ? [`Run remix_collab_view_merge_request with mrId=${String(result.id)} to inspect the request before deciding whether to approve or reject it.`] : [],
     logContext: {
       mrId: typeof result.id === "string" ? result.id : null
@@ -1136,6 +1248,7 @@ async function syncUpstream(params) {
 }
 async function reconcile(params) {
   const api = await createCollabApiClient();
+  const drainWarnings = params.dryRun ? [] : await drainBeforeMutation(api);
   const result = await coreCollabReconcile({
     api,
     cwd: params.cwd,
@@ -1144,9 +1257,9 @@ 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."] : [],
+    warnings: [...drainWarnings, ...collectWarnings(result.warnings)],
+    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 recover the server lane onto the latest agreed state before future recording continues."] : [],
     logContext: {
       repoRoot: result.repoRoot ?? null
     }
@@ -1693,6 +1806,50 @@ async function accessDebug(params) {
   };
 }
 
+// src/tools/collab/autoSpawnHistoryImport.ts
+import { spawn as spawn2 } from "child_process";
+import { existsSync, mkdirSync, openSync } from "fs";
+import path2 from "path";
+var MARKER_REL_PATH = path2.join(".remix", ".history-imported");
+var LOG_REL_PATH = path2.join(".remix", "history-import.log");
+function shouldAutoSpawnHistoryImport(repoRoot) {
+  try {
+    return !existsSync(path2.join(repoRoot, MARKER_REL_PATH));
+  } catch {
+    return false;
+  }
+}
+function spawnHistoryImportDetached(repoRoot) {
+  const remixDir = path2.join(repoRoot, ".remix");
+  try {
+    mkdirSync(remixDir, { recursive: true });
+  } catch {
+  }
+  const logPath = path2.join(repoRoot, LOG_REL_PATH);
+  const out = openSync(logPath, "a");
+  const err = openSync(logPath, "a");
+  const child = spawn2(
+    "remix",
+    [
+      "history",
+      "import",
+      "--repo",
+      repoRoot,
+      // Include prompt text for parity with the CLI auto-spawn path:
+      // first-time UX is a lot worse if the dashboard renders every
+      // historical row as "(prompt not uploaded)".
+      "--include-prompt-text"
+    ],
+    {
+      detached: true,
+      stdio: ["ignore", out, err],
+      env: { ...process.env, REMIX_HISTORY_AUTO_SPAWN: "1" }
+    }
+  );
+  child.unref();
+  return { pid: child.pid, logPath };
+}
+
 // src/tools/collab/register.ts
 function getAnnotations(access, options) {
   if (access === "read") {
@@ -1722,9 +1879,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."];
   }
@@ -1736,16 +1890,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,
@@ -1824,18 +1971,37 @@ function registerCollabTools(server, context) {
   });
   registerTool(server, context, {
     name: "remix_collab_init",
-    description: "Import the current repository into Remix and write the local binding file.",
+    description: "Import the current repository into Remix and write the local binding file. Synchronous: by the time this tool resolves, the local binding file AND the local Remix baseline are both on disk, so the very next call to remix_collab_finalize_turn will succeed. Brand-new init on the default branch typically takes ~10s; non-default-branch init can take 30-90s while the server provisions a feature lane. The result includes `reused: boolean` (false for a brand-new app, true if a binding already existed) plus the canonical app/project identifiers and the dashboard URL. Use forceNew=true only when intentionally creating a new canonical family from scratch in a previously-bound repo; do NOT use forceNew as a retry mechanism for a failed init \u2014 it creates orphan backend apps and triggers canonical-family ambiguity errors on subsequent inits in this directory.",
     access: "remote_write",
     inputSchema: initInputSchema,
     outputSchema: initSuccessSchema,
     run: async (args) => {
       const input = z3.object(initInputSchema).parse(args);
       const cwd = resolvePolicyCwd(context.policy, input.cwd);
-      return initCollab({
+      const result = await initCollab({
         cwd,
         appName: input.appName,
         forceNew: input.forceNew
       });
+      try {
+        const repoRoot = result && typeof result === "object" && "data" in result && result.data && typeof result.data.repoRoot === "string" ? result.data.repoRoot : null;
+        if (repoRoot && shouldAutoSpawnHistoryImport(repoRoot)) {
+          const spawned = spawnHistoryImportDetached(repoRoot);
+          context.logger.log({
+            level: "info",
+            message: `history_import_auto_spawned pid=${spawned.pid ?? "?"} log=${spawned.logPath}`,
+            tool: "remix_collab_init",
+            repoRoot
+          });
+        }
+      } catch (spawnError) {
+        context.logger.log({
+          level: "error",
+          message: `history_import_auto_spawn_failed: ${spawnError instanceof Error ? spawnError.message : String(spawnError)}`,
+          tool: "remix_collab_init"
+        });
+      }
+      return result;
     }
   });
   registerTool(server, context, {
@@ -1891,7 +2057,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. Required: call this exactly once before the final response on every turn that touched a Remix-bound repo. Captures the current boundary locally and queues remote processing. Queued only: no remote change step exists yet until the finalize queue drains. Runtime exception: if this turn's context contains a [Remix runtime status] system note from the Remix UserPromptSubmit hook stating that the Stop hook will record this turn automatically, do NOT call this tool \u2014 the runtime is recording it on your behalf and a manual call would create a duplicate record. The runtime note is the only sanctioned override; trivial prompts, error states, and ambiguity all still require this call.",
     access: "local_write",
     inputSchema: finalizeTurnInputSchema,
     outputSchema: finalizeTurnSuccessSchema,
@@ -1899,25 +2065,34 @@ 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,
-        agent: context.agentMetadata
+        agent: context.agentMetadata,
+        awaitingUsageDeadlineMs: 3e4
       });
     }
   });
+  registerTool(server, context, {
+    name: "remix_collab_drain_finalize_queue",
+    description: "Drain the local finalize queue and record queued finalize_turn jobs immediately. NOT required as a precondition for `remix_collab_request_merge` or `remix_collab_reconcile_apply` \u2014 those tools drain the queue internally before they run. Useful only for explicit recovery flows (e.g. status reports `await_finalize` and you want to flush before re-checking). Runtime exception: if this turn's context contains a [Remix runtime status] system note from the Remix UserPromptSubmit hook, the runtime drains the queue automatically in the background; do NOT call this tool unless an explicit recovery flow requires it.",
+    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,
@@ -1929,7 +2104,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,
@@ -1940,6 +2115,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 this checkout needs a fresh local Remix baseline. Use only when status reports `re_anchor` (no local baseline exists for this lane yet \u2014 fresh clone, deleted `.remix/` state, or first init didn't seed). Re-anchor does not replace `remix_collab_finalize_turn`; ordinary local content changes (including merges, pulls, and rebases) are recorded by `finalize-turn`, not by re-anchor.",
+    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: "Establish a local Remix baseline for the current checkout against the existing app head, without rewriting the local checkout afterward. Required only when status reports `re_anchor` (missing local baseline). It does not replace `remix_collab_finalize_turn` \u2014 local commits, pulls, merges, and rebases must still be recorded with `finalize-turn`.",
+    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.",
@@ -2080,7 +2280,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,
@@ -2092,7 +2292,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,
@@ -3217,6 +3417,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()
@@ -3226,6 +3439,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)
@@ -3258,6 +3478,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);
@@ -3291,7 +3512,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
   };
@@ -3314,6 +3535,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);
@@ -3540,6 +3797,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.",
@@ -3670,6 +3946,16 @@ 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;
+  }
+  if (process.argv.includes("--drain-async-jobs")) {
+    const api = await createCollabApiClient();
+    await drainAsyncJobs({ api });
+    return;
+  }
   await startStdioServer({ version });
 }
 main().catch((error) => {