@remixhq/claude-plugin 0.1.17 → 0.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixhq/claude-plugin",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Claude Code plugin for Remix collaboration workflows",
   "homepage": "https://github.com/RemixDotOne/remix-claude-plugin",
   "license": "MIT",
@@ -23,16 +23,27 @@
     "hooks",
     "agents"
   ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./historical": {
+      "types": "./dist/historical.d.ts",
+      "import": "./dist/historical.js"
+    }
+  },
   "scripts": {
     "build": "tsup",
     "postbuild": "node -e \"const fs=require('node:fs'); for (const p of ['dist/mcp-server.cjs','dist/hook-pre-git.cjs','dist/hook-user-prompt.cjs','dist/hook-post-collab.cjs','dist/hook-stop-collab.cjs']) fs.chmodSync(p, 0o755);\"",
     "dev": "tsx src/mcp-server.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test src/**/*.test.ts",
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@remixhq/core": "^0.1.12",
-    "@remixhq/mcp": "^0.1.12"
+    "@remixhq/core": "^0.1.14",
+    "@remixhq/mcp": "^0.1.14"
   },
   "devDependencies": {
     "@types/node": "^25.4.0",

package/skills/identity-and-scope-routing/SKILL.md

@@ -28,6 +28,7 @@ Recommended sequence:
 Important rules:
 
 - In a bound repo, treat the app as the default anchor for scope reasoning.
+- When the user asks for any URL, link, dashboard, or web address of a Remix-bound repo or app — phrasings like "URL of this repo", "link to this app", "where do I see it on the dashboard", "remix URL" — use `remix_collab_status` and answer with `binding.dashboardUrl`. That value is already in the canonical `https://dashboard.remix.one/apps/<appId>` form. Do NOT use `binding.remoteUrl` for this — that is the git remote URL, which is unrelated to the Remix dashboard. If `binding.dashboardUrl` is null but `binding.currentAppId` is set, fall back to constructing `https://dashboard.remix.one/apps/<currentAppId>`.
 - Do not assume the bound app's project or organization is readable just because the app is readable.
 - Treat warnings on cwd-derived results as meaningful partial context, not as failure.
 - If cwd inference cannot safely resolve a broader scope, prefer the app-level answer and explain the boundary.

package/skills/init-or-remix/SKILL.md

@@ -5,6 +5,12 @@ description: Use when deciding whether to bind the current repo to Remix or crea
 
 # Init, Remix, Or Checkout
 
+## Silent-init rule
+
+If during any turn you find yourself on an unbound branch in a Remix-bound repo — whether the user mentioned Remix or not, whether the prompt is trivial or not — **silently run `remix_collab_init` on the current branch without asking**. This is not a decision point. Do not present init as one option among several. Do not switch to a bound branch to avoid init. Init the branch you are on.
+
+The user-facing decision tree below (init vs. remix vs. checkout) only applies when the user is explicitly choosing how to bring a repo into Remix for the first time. Mid-turn unbound-branch recovery is always silent init.
+
 Use this skill when onboarding a repository into Remix, starting from an existing Remix app lineage, or checking out an exact existing Remix app.
 
 This is the entry-point choice:
@@ -15,8 +21,8 @@ This is the entry-point choice:
 
 Decision rule:
 
-- Use `remix_collab_init` when the user wants to bind the current local repository to Remix.
-- Use `remix_collab_remix` when the user wants a new local checkout forked from an existing Remix app.
+- Use `remix_collab_init` when the user wants the current repo to become a Remix app. This is the only way to bring a non-Remix repo into Remix — remix and checkout both require an existing appId.
+- Use `remix_collab_remix` ONLY when an existing Remix appId is already known or provided or the user indicated that they want to remix or fork and the user wants to fork that app into a new directory. If no appId exists and no indication is given and this is an unbound local repo, this tool does not apply — you cannot 'remix' an unbound local repo.
 - Use `remix_collab_checkout` when the user wants the exact existing app checked out locally as-is.
 
 Recommended sequence:
@@ -29,12 +35,14 @@ Recommended sequence:
 4. If the task starts from an existing app id and the user wants a new fork, prefer `remix_collab_remix`.
 5. If the task starts from an existing app id and the user wants the same app id locally, prefer `remix_collab_checkout`.
 6. After init, remix, or checkout, use `remix_collab_status` in the resulting repo to inspect readiness.
+7. After a successful `remix_collab_init` (i.e. the user just bound a brand-new repo), include a one-line collaboration hint in your user-facing summary, phrased naturally and conversationally — for example: "You can invite teammates to collaborate at any time by asking me to invite their email (e.g. \"invite alice@example.com\")." Show this once, right after the post-init summary; do not repeat it on subsequent turns, on `remix_collab_remix`, or on `remix_collab_checkout` (those flows join an app that already has collaborators). When the user actually asks you to invite someone by email, use `remix_collab_invite` with the email and let the tool default the scope to the current binding.
 
 Important note:
 
 - `remix_collab_init` is a repo-level, history-preserving bind of the current git repository.
 - Do not treat init as a subdirectory import workflow.
 - `remix_collab_remix` creates a new bound checkout in a newly created directory under the provided or current working directory.
+- `remix_collab_remix` forks an existing Remix app (requires appId) into a new directory under the provided or current working directory. It never reads or binds the current repo.
 - `remix_collab_checkout` creates a new bound checkout for the exact existing app id without creating a new fork.
 - Do not treat remix as binding the current repository in place.
 - When app discovery is only about \"what can I actually work on?\", prefer membership-oriented listing (`accessScope=\"explicit_member\"`) over broad readable discovery.
@@ -42,3 +50,5 @@ Important note:
 - If the user wants to start from an existing Remix app lineage with a new fork, use `remix_collab_remix`.
 - If the user wants to continue work on the same existing app id, use `remix_collab_checkout`.
 - After init, remix, or checkout, run `remix_collab_status` in the resulting repo and then follow the normal bound-repo workflow there.
+- If the user's request was ambiguous, ask for clarification in a very easy to understand and explanatory way. Remix is a new concept and you need to assume the user is not familiar with it.
+- If the user suggest creating a remix, initializing a remix, or something that indicates they want to start using remix on the local repo without mentioning anything specific about an app and the app is unbound, they probably want `remix_collab_init`.

package/skills/review-merge-request/SKILL.md

@@ -19,17 +19,19 @@ Recommended sequence:
     - `app_outgoing` for requests opened from this app
     - `app_related_visible` for all open visible requests where this app is source or target
 2. Use `remix_collab_view_merge_request` to inspect the request.
-3. Request bounded diff output first. Only request a larger diff if needed to answer the review task accurately.
-4. If approval is requested:
+3. If the current repo reports `await_finalize`, use `remix_collab_drain_finalize_queue`, then re-check `remix_collab_status` before request-merge or target-mutating approval flows.
+4. Request bounded diff output first. Only request a larger diff if needed to answer the review task accurately.
+5. If approval is requested:
    - use `remix_collab_approve_remote` when local target repo sync is not needed
    - use `remix_collab_approve_and_sync_target` only when you are in the correct target repo context and the user wants local sync too
-5. Use `remix_collab_reject` when the correct outcome is rejection.
+6. Use `remix_collab_reject` when the correct outcome is rejection.
 
 Important rules:
 
 - In a bound repo, use Remix review tools as the default path for MR handling.
 - Choose an explicit queue instead of treating merge requests as one broad inbox.
 - Do not treat raw `git merge` as the way Remix merge requests are approved or applied.
+- Do not assume a successful `remix_collab_finalize_turn` already created a remote change step; drain and re-check when status reports `await_finalize`.
 - If approval would mutate the local target repo, explain that before applying it.
 - If the repo context is unclear, stay in remote-only review mode until the target repo is confirmed.
 - Before the final response, use `remix_collab_finalize_turn` to record the completed review turn.

package/skills/safe-collab-workflow/SKILL.md

@@ -7,19 +7,32 @@ description: Use when working in a repo that may be bound to Remix, especially f
 
 In a Remix-bound repo, treat Remix MCP tools as the authoritative workflow layer for collaboration state and historical reasoning.
 
+## Runtime override (read this first)
+
+When this turn's context contains a Remix runtime status note (recognizable by the literal `[Remix runtime status]` prefix from the Remix `UserPromptSubmit` hook), recording and queue draining for **this** turn are handled automatically by the runtime's `Stop` hook. In that case:
+
+- Do **not** call `remix_collab_finalize_turn` for this turn — the runtime is recording it. Calling it would create a duplicate record.
+- Do **not** call `remix_collab_drain_finalize_queue` as a precondition for anything. The runtime drains the queue automatically in the background; mutation tools (`remix_collab_request_merge`, `remix_collab_reconcile_apply`) also drain internally before they run.
+
+The runtime status note is authoritative for the override. The rest of this skill — including the "before the final response, you must record" rule — still applies for **tool errors**, **explicit recovery flows**, and **turns where no runtime status note is present**.
+
 Canonical rules:
 
 - In a bound repo, Remix tools are the required workflow layer for collaboration work.
 - In a bound repo, branch switches are collaboration-state transitions because each branch can resolve to its own Remix lane and app lineage.
+- Never switch git branches on your own. Branch switches are user-initiated only. If a Remix tool points at a different branch, do not "fix" it by switching — run `remix_collab_status` and follow its recommendation for the current branch.
+- An unbound branch is always a silent-init situation. Run `remix_collab_init` without asking. The user's intent when working on a branch is that the branch be bound.
 - Historical intent questions go to Remix memory before raw git history.
-- Raw git mutation is not the normal collaboration path in a bound repo.
-- Before the final response, you must record exactly one completed turn with `remix_collab_finalize_turn`.
+- Remix is source-blind: any local content change since the last recorded turn — whether you typed it, the user typed it, a merge produced it, `git pull` brought it in, or an IDE saved it — is captured by exactly one `remix_collab_finalize_turn`. Do not pick a different command based on what produced the change. `re-anchor` is for the narrow missing-baseline case only (status reports `re_anchor`).
+- Raw git mutation is allowed in a bound repo, but it never substitutes for `remix_collab_finalize_turn`. After raw git mutations, run `remix_collab_status` and record with `finalize-turn`.
+- Before the final response, you must record exactly one completed turn with `remix_collab_finalize_turn` — **unless the runtime override at the top of this skill applies** (a `[Remix runtime status]` note from the Remix hook stating that the Stop hook will record this turn).
+- `remix_collab_finalize_turn` is queued only. It captures the local boundary first; a remote change step does not exist yet until the finalize queue drains.
 - The recording call must include the exact user prompt and your final assistant response.
-- Do not finish the response before recording the completed turn.
+- Do not finish the response before recording the completed turn (subject to the runtime override).
 - Prefer preview tools before apply tools whenever both exist.
 - Treat reconcile as high risk and use it only when sync is unavailable and clearly required.
 
-Raw git mutation commands must not be used for ordinary bound-repo collaboration work. Raw git reads are reserved for exact repository facts, not for normal collaboration-state or historical-reasoning flows.
+Raw git mutation commands are not the normal collaboration path, but they are allowed. When they are used, treat the result the same as any other local content change: run `remix_collab_status` and follow its `recommendedAction` (almost always `record` → `remix_collab_finalize_turn`). Raw git reads are reserved for exact repository facts, not for normal collaboration-state or historical-reasoning flows.
 
 Follow this order:
 
@@ -28,29 +41,48 @@ Follow this order:
 3. Prefer preview tools before apply tools:
    - `remix_collab_sync_preview` before `remix_collab_sync_apply`
    - `remix_collab_reconcile_preview` before `remix_collab_reconcile_apply`
-4. Prefer Remix merge request tools over raw git merge flows for collaboration review work.
-5. When you need historical context, hidden intent, failed attempts, merge/reconcile lineage, or pre-change risk context, check Remix memory before falling back to broader repo exploration:
+4. If status reports `await_finalize`, use `remix_collab_drain_finalize_queue`, then re-check `remix_collab_status` before merge-related or recovery flows.
+5. Prefer Remix merge request tools over raw git merge flows for collaboration review work.
+6. When you need historical context, hidden intent, failed attempts, merge/reconcile lineage, or pre-change risk context, check Remix memory before falling back to broader repo exploration:
    - `remix_collab_memory_summary`
    - `remix_collab_memory_search`
    - `remix_collab_memory_timeline`
-6. Only call `remix_collab_memory_change_step_diff` after you already have a specific `changeStepId`.
-7. Use raw git history only after Remix memory has narrowed the relevant change, or when the user explicitly asks for exact commit, blame, ancestry, or patch-level detail.
-8. Before the final response, call `remix_collab_finalize_turn`.
+7. Only call `remix_collab_memory_change_step_diff` after you already have a specific `changeStepId`.
+8. Use raw git history only after Remix memory has narrowed the relevant change, or when the user explicitly asks for exact commit, blame, ancestry, or patch-level detail.
+9. Before the final response, call `remix_collab_finalize_turn`, **unless** the runtime override at the top of this skill applies for this turn — in which case the runtime records it on your behalf and a manual call would be a duplicate.
 
 After switching branches:
 
 1. Run `remix_collab_status`.
 2. If the branch is healthy and bound, continue with the requested workflow.
-3. If the branch is unbound, initialize or provision that branch lane before mutation commands.
+3. If the branch is unbound, silently run `remix_collab_init` on that branch before mutation commands. Do not ask, do not offer to switch back to another branch — init the branch you are on.
 4. If status reports a branch mismatch, stop and recover the correct branch binding before recording, syncing, reconciling, or opening a merge request.
 5. Do not assume another branch's binding is safe to reuse on the current checkout.
 
+Detecting an unexpected branch or binding state:
+
+Branch state can change between turns by means you did not initiate — external git operations, IDE actions, or hook side effects. You must detect and recover, not assume continuity.
+
+**Treat any of the following as a mandatory trigger to run `remix_collab_status` before any other Remix mutation or response:**
+
+- A Remix tool returns an error mentioning a branch name you did not just switch to.
+- A Remix tool returns an error mentioning "not yet bound", "branch mismatch", "binding missing", or "baseline missing".
+- `git status` or a bash command reveals a branch that does not match your mental model of the session.
+- Any hook reminder, system-reminder, or preflight message flags an unexpected binding condition.
+
+**NEVER skip `remix_collab_status` on one of these triggers.** Do not work around the error by calling the next tool in the expected sequence, stashing, switching branches blindly, or declaring the situation unresolvable. The status tool is the only source of truth for the current lane binding, and every recovery decision must be grounded in its output — not in your memory of an earlier state, not in the error message alone, not in shell output.
+
+**NEVER end your response with an unhandled Remix error.** If a Remix tool fails and you cannot resolve it this turn, at minimum: run `remix_collab_status`, report the real state to the user, and explicitly ask how to proceed. Silently giving up is not an option in a bound repo.
+
+**NEVER switch branches to "recover" from an unexpected binding state.** If status shows the current branch is unbound or mismatched, the recovery is `remix_collab_init` (silent) or a user-facing question — never `git checkout` another branch. Branch switches belong to the user.
+
 Important rules:
 
 - If the repo is unbound, use `remix_collab_init` for the current repo, `remix_collab_remix` for a new fork from an existing app lineage, or `remix_collab_checkout` to materialize an existing app as-is.
-- In a bound repo, do not use raw git `commit`, `push`, `pull`, `merge`, `rebase`, or `reset` for ordinary Remix collaboration work.
+- In a bound repo, raw git mutations (`commit`, `pull`, `merge`, `rebase`, `reset`) are allowed but never replace `remix_collab_finalize_turn`. After any raw git mutation, run `remix_collab_status` and record with `finalize-turn`. Do not assume `re-anchor` is the recovery — that command is only for missing-baseline cases (`recommendedAction: re_anchor`).
 - In a bound repo, do not start why/history/failed-attempt questions with raw git `log`, `show`, `blame`, or `diff`; start with Remix memory reads instead.
 - In a bound repo, do not finish the response before recording the completed turn yourself.
+- Do not treat a successful `remix_collab_finalize_turn` call as proof that the turn is already available for merge-request or remote-history workflows. Drain and re-check when status reports `await_finalize`.
 - After the final recording call, avoid further repo mutations unless you intend to record another final turn.
 - Use raw git reads only when the task is clearly about exact repository facts or a separate GitHub-only branch workflow rather than Remix state.
 - When viewing merge requests, request bounded diff output first and only ask for more detail if needed.

package/skills/submit-change-step/SKILL.md

@@ -1,32 +1,91 @@
 ---
-name: submit-change-step
-description: Use when code edits are complete in a Remix-bound repo and the work should be recorded as a Remix change step.
+name: finalize-turn-workflow
+description: Use when code edits or review work are complete in a Remix-bound repo and the turn should be recorded with `remix_collab_finalize_turn`.
 ---
 
-# Submit Remix Change Step
+# Finalize A Remix Turn
 
-Use this skill after edits are complete and the task should be captured as the final recorded turn in a Remix-bound repo.
+Use this skill after edits or review work are complete and the task should be captured as the final recorded turn in a Remix-bound repo.
 
-This skill is specifically about what `remix_collab_finalize_turn` needs to record the completed work correctly.
+This skill is specifically about the queued-finalize model behind `remix_collab_finalize_turn`.
+
+## Source-blind recording rule
+
+Remix records turns source-blind. Any local content change since the last recorded turn — whether you typed it, the user typed it, a `git pull` brought it in, a `git merge` or `git rebase` produced it, or an IDE saved it — is captured by exactly one `remix_collab_finalize_turn`. `finalize-turn` automatically attaches `preTurnEvents` metadata describing any commits, merges, or uncommitted state captured at the boundary; you do not need to summarize that yourself.
+
+Do **not** pick a different command (`re-anchor`, `sync`, `reconcile`) based on what produced the local change. Those commands are only correct when `remix_collab_status.recommendedAction` explicitly names them:
+
+- `record` (or `repoState: local_only_changed`) → `remix_collab_finalize_turn`. This is the catch-all and the most common case.
+- `re_anchor` → `remix_collab_re_anchor_*`. Only when no local Remix baseline exists for this lane (fresh clone, deleted `.remix/`, or first init didn't seed). Re-anchor seeds the baseline; it is not a recovery for "the local content changed."
+- `pull` → `remix_collab_sync_*`. Only when the server lane advanced and local did not.
+- `reconcile` → `remix_collab_reconcile_*`. Only when both sides changed since the agreed baseline.
+
+## Runtime override (read this first)
+
+When a Remix runtime status note appears in this turn's context — recognizable by the literal `[Remix runtime status]` prefix and originating from the Remix `UserPromptSubmit` hook — recording and queue draining for **this** turn are handled automatically by the runtime's `Stop` hook. In that case:
+
+- Do **not** call `remix_collab_finalize_turn` for this turn. The runtime is recording it. A redundant call would create a duplicate record.
+- Do **not** call `remix_collab_drain_finalize_queue` for this turn. The runtime drains the queue automatically in the background. Mutation tools (`remix_collab_request_merge`, `remix_collab_reconcile_apply`) drain internally before they run, so manual draining is never required as a precondition.
+
+The runtime status note is authoritative for the override. Everything else in this skill — the mandates, the "NEVER" rules, the recovery sequences — still applies for **error recovery**, **tool failures**, and **turns where no runtime status note is present**. Treat the override as covering only the routine "I just finished a healthy turn, time to record it" case.
 
 Workflow:
 
 1. Run `remix_collab_status` first to confirm the repo is bound and inspect current warnings.
-2. Use `remix_collab_finalize_turn` before the final response, with the exact user prompt and your final assistant response.
-3. Let `remix_collab_finalize_turn` choose the changed-turn path from the live worktree by default.
-4. Provide an explicit external diff only when the task requires recording a diff that is not present in the current worktree.
+2. If status recommends `await_finalize`, do not record again and do not request a merge yet. Use `remix_collab_drain_finalize_queue`, then re-check `remix_collab_status`.
+3. When the repo is ready, use `remix_collab_finalize_turn` before the final response, with the exact user prompt and your final assistant response — **unless the runtime override above applies**.
+4. Treat `remix_collab_finalize_turn` as capturing the local workspace boundary and queueing remote processing, not as immediate proof that a remote change step already exists.
 
 Important behavior:
 
 - `remix_collab_finalize_turn` is the authoritative recording path for completed work instead of raw git commit or push.
-- When the diff comes from the live worktree, Remix may discard tracked changes and captured untracked paths locally as part of auto-sync.
-- When the diff comes from an external source, automatic local discard+sync is skipped because the external diff may not match the current worktree.
-- The resulting git commit is created on the Remix side first and appears in the local repo after sync or auto-sync.
-- Surface these side effects clearly to the user when they matter.
+- `remix_collab_finalize_turn` is queued only. A remote change step does not exist yet until the finalize queue drains successfully.
+- A successful finalize call means local capture and queueing succeeded. It does not mean merge-request or remote-history workflows can assume the turn is already materialized remotely.
+- If `remix_collab_status` reports `await_finalize`, use `remix_collab_drain_finalize_queue` and re-check status before merge-related or recovery flows.
 - If the user wants to understand current repo state before recording, re-run `remix_collab_status`.
 - Do not make further repo mutations after the final recording call unless you intend to record another completed turn.
-- If `remix_collab_finalize_turn` reports that the change step succeeded remotely but local sync failed, do not retry finalize immediately.
-- In that recovery case, treat the tool's `recommendedNextActions` and `error.hint` as authoritative, starting with `remix_collab_status`, then `remix_collab_sync_preview`, then `remix_collab_sync_apply` when appropriate.
-- If the error surfaces a preserved diff backup path, mention it explicitly and preserve it as the fallback recovery artifact while you repair local sync state.
+- Do not retry finalize immediately just because a remote record is not visible yet; queue drain is the next step, not a second finalize.
+- If finalize or drain returns `recommendedNextActions` or an `error.hint`, those fields are **authoritative and mandatory**. Do not ignore them. Do not improvise around them. Call `remix_collab_status` first and use its result plus the hint together to choose the next tool. Skipping this step is the single most common way agents fail in this skill.
+- If the tool surfaces a preserved local recovery artifact, mention it explicitly and keep it available while you repair repo state.
+
+Use the live worktree as the source of truth for finalized work. If the repo is not ready, fix the preflight state first rather than trying to bypass it.
+
+## Finalize errors — non-negotiable rules
+
+When `remix_collab_finalize_turn` returns an error, you are in a state-recovery situation. You do not have permission to end your turn until it is resolved.
+
+**NEVER, UNDER ANY CIRCUMSTANCES, END A TURN WITH AN UNHANDLED FINALIZE ERROR.**
+
+This means:
+
+- Do not decide "finalize isn't applicable here" because the user's prompt was trivial (e.g. "hello world"). The recording rule fires on any turn that touches the bound repo — including the very finalize call that just failed. The call touched the repo. You must record.
+- Do not skip finalize because the error seems like a state problem outside your control. State problems are exactly what the error's `hint` and `recommendedNextActions` fields are there to resolve. Read them. Follow them.
+- Do not run a random bash command to "check what happened" and then give up. That is the failure pattern. `remix_collab_status` is the correct first tool, every time, without exception.
+
+**Mandatory recovery sequence when finalize errors:**
+
+1. Read the error's `message`, `hint`, and `recommendedNextActions` fields in full. They are authoritative. If the hint names a tool, that tool is almost certainly the next correct call.
+2. Call `remix_collab_status` immediately. The hint from status supersedes anything you inferred from the error alone — status sees the actual current binding, branch, worktree, alignment, and queue state.
+3. Based on status, pick the correct recovery tool:
+   - `local_only_changed` (or `recommendedAction: record`) → `remix_collab_finalize_turn`. This is the catch-all for any local mutation, including raw `git commit`, `git pull`, `git merge`, `git rebase`, or `git reset`. The source of the change does not matter.
+   - `baseline_missing` or `external_local_base_changed` (or `recommendedAction: re_anchor`) → commit any pending edits, then `remix_collab_re_anchor_preview` → `remix_collab_re_anchor_apply`. This applies only when no local Remix baseline exists for this lane yet, not whenever local content moved.
+   - `await_finalize` → `remix_collab_drain_finalize_queue`, then re-check status.
+   - Unbound or mismatched branch → follow the branch-recovery rules below.
+   - `delta_ready` for sync (or `recommendedAction: pull`) → `remix_collab_sync_preview` → `remix_collab_sync_apply`.
+   - `both_changed` (or `recommendedAction: reconcile`) → `remix_collab_reconcile_preview` → `remix_collab_reconcile_apply`.
+4. Retry `remix_collab_finalize_turn` only after status confirms the blocker is cleared.
+5. Only then produce your final user-facing response.
+
+**If finalize fails because the current branch is unbound:**
+
+The error hint will explicitly name the branch (e.g., `"Run remix collab init on branch X"`). That hint is the answer. Sequence:
+
+1. Call `remix_collab_status` to confirm the current branch is unbound (not mismatched, not in another recoverable state).
+2. **Silently run `remix_collab_init` on the current branch.** Do not ask the user first. Do not offer alternatives. Do not switch branches. An unbound branch in a Remix-bound repo is always a silent-init situation — that is the entire point of the init-on-demand contract.
+3. Retry `remix_collab_finalize_turn`. Only after it succeeds, respond.
+
+**NEVER switch git branches to resolve a finalize error.** Branch switching is a user-initiated action and requires explicit user instruction. If status shows the current branch is unbound, init it — do not switch to some other bound branch to avoid the init. Silently initing the current branch is always correct; silently switching branches is always wrong.
+
+**Cross-branch finalize** (`allowBranchMismatch: true`) applies only when the user has explicitly asked for it. Do not infer it from status.
 
-Use external diff input only when the task explicitly requires it. Otherwise prefer the current worktree.
+**The triviality of the user's current prompt is irrelevant.** "Say hello world" does not exempt you from the protocol. Neither does "what time is it", "thanks", or any other small talk. If the bound repo was touched — including by a failing Remix tool call — you finalize. No exceptions, **except** the explicit runtime override at the top of this skill (a `[Remix runtime status]` note from the runtime hook stating that the Stop hook will record this turn automatically). The runtime override is the **only** sanctioned way to skip a finalize call; nothing else exempts you.

package/skills/sync-and-reconcile/SKILL.md

@@ -11,10 +11,11 @@ This skill is only about repository alignment. Use the general collaboration wor
 
 Mental model:
 
-- `remix_collab_sync_*` is for pulling Remix-known app state into the local repo when fast-forward sync is possible.
-- `remix_collab_reconcile_*` is for cases where local history exists that Remix cannot fast-forward from.
+- `remix_collab_sync_*` is for pulling Remix-known app state into the local repo when fast-forward sync is possible (i.e. `recommendedAction: pull`, `repoState: server_only_changed`).
+- `remix_collab_reconcile_*` is for the rare case where both the local workspace and the server lane changed since the last agreed baseline (i.e. `recommendedAction: reconcile`, `repoState: both_changed`).
 - `remix_collab_sync_upstream` is for bringing new upstream app changes into a remix.
 - `remix_collab_finalize_turn` is not a sync tool. It records the completed turn, but it does not replace sync, reconcile, or upstream-sync workflows.
+- `re-anchor` is **not** a sync or recovery tool for diverged history. It only seeds a missing local Remix baseline (`recommendedAction: re_anchor`). See the finalize-turn-workflow skill for full handling. If status reports `local_only_changed` (or `recommendedAction: record`), the answer is `finalize-turn`, never reconcile.
 
 Workflow: