@useshifu/coding-harness 0.3.11 → 0.3.12

package/README.md

@@ -34,6 +34,8 @@ To disconnect this device, run `npx --yes @useshifu/coding-harness disconnect --
 
 Version `0.3.11` adds rolling days-based windows and explicit force replacement of reviewed segments. Force replacement requires backend migration 049 and the matching connector endpoints to be deployed first.
 
+Version `0.3.12` makes force sync independent of local and server checkpoints, creates missing work, and protects automatic retries from overwriting a newer force sync. Deploy backend migrations 049 and 050 before using it.
+
 ```sh
 npx --yes @useshifu/coding-harness status --harness codex
 npx --yes @useshifu/coding-harness sessions --harness codex --hours 24
@@ -77,16 +79,16 @@ The AI Profile page shows detected categories, model and thinking labels, and Je
 
 ## Recommended package updates
 
-The connection endpoint returns `recommendedPackageVersion`, currently pinned to `0.3.10` (publish this release before deploying the recommendation). Before `sync`, `sync-files`, `approve`, or `scheduled-sync`, the runner compares its embedded release version with that property. An older runner installs the exact recommended release through npm and resumes the original command with the updated runner. Equal or newer runners continue unchanged. Explicitly recommended major releases follow the same comparison rule. Missing or invalid recommendations, connection failures, and npm failures do not block sync. The connection, pending work, checkpoints, and schedule are preserved.
+The connection endpoint returns `recommendedPackageVersion`, pinned to a published release. Before `sync`, `sync-files`, `approve`, or `scheduled-sync`, the runner compares its embedded release version with that property. An older runner installs the exact recommended release through npm and resumes the original command with the updated runner. Equal or newer runners continue unchanged. Explicitly recommended major releases follow the same comparison rule. Missing or invalid recommendations, connection failures, and npm failures do not block sync. The connection, pending work, checkpoints, and schedule are preserved.
 
-This update mechanism first ships in `0.3.10`. Runners from earlier releases need a one-time installation of a release containing it (`npx --yes @useshifu/coding-harness@0.3.11 install --harness codex`). Raise the server recommendation only after the target release is published and its backend requirements are deployed.
+This update mechanism first ships in `0.3.10`. Runners from earlier releases need a one-time installation of a release containing it (`npx --yes @useshifu/coding-harness@0.3.12 install --harness codex`). Raise the server recommendation only after the target release is published and its backend requirements are deployed.
 
-## Replace previously synced work
+## Force sync local work
 
-An explicit force request re-reviews the original accepted segments and replaces their current work evidence and claims while retaining history. It does not reset or lower checkpoints, and never changes scheduled sync or AI Profile observations.
+An explicit force request selects local work independently of both local and server checkpoints. It includes already synced sessions and ranges the server has never accepted. It creates missing ranges or replaces their current work evidence and claims while retaining history. Force never resets or lowers checkpoints and does not change scheduled sync or AI Profile observations.
 
-1. Discover accepted targets with `sessions --harness codex --days 3 --force` (or a requested hours/count selection). Keep that initial target list fixed; new pending turns still use ordinary sync.
-2. Re-review each target with `review --harness codex --session-ref <sessionRef> --days 3 --force --from-turn <fromTurn> --to-turn <toTurn> --supersedes-sync-id <supersedesSyncId>`. The original local turns must exist. Explicit backfill/count selections use `--all`.
-3. Prepare and redact the payload again, keeping the exact session reference and turn range and adding its `supersedesSyncId`. Pipe it to `sync --harness codex --force`, following the saved manual/automatic approval policy.
+1. Discover ranges with `sessions --harness codex --days 3 --force` (or a requested hours/count selection). Keep that initial target list fixed. Complete stored ranges touching selected turns are preserved, including older turns across a window boundary; uncovered selected turns are split into ranges of at most 12.
+2. Re-review each range with `review --harness codex --session-ref <sessionRef> --days 3 --force --from-turn <fromTurn> --to-turn <toTurn>`. The original local turns must exist. Explicit backfill/count selections use `--all`. No old receipt ID is required.
+3. Prepare and redact the payload again, keeping the exact session reference and turn range and adding `force: true`. Pipe it to `sync --harness codex --force`, following the saved manual/automatic approval policy.
 
-A changed target is rejected so newer work cannot be overwritten accidentally. Re-discover and re-review before attempting that replacement again. Identical retries are safe. Existing conversations retain their context; start a new chat in Shifu to use the latest context.
+Missing local turns are reported in `unavailableSegments`. A partial overlap with accepted work is rejected; re-discover and re-review complete ranges before retrying. Automatic retries preserve the accepted result even if another force sync finishes meanwhile. A new invocation is a new explicit force request. Existing conversations retain their context; start a new chat in Shifu to use the latest context.

package/bin/shifu-harness.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 const fs = require("node:fs");
-const { createHash } = require("node:crypto");
+const { createHash, randomUUID } = require("node:crypto");
 const os = require("node:os");
 const path = require("node:path");
 const { execFile, execFileSync, spawn } = require("node:child_process");
@@ -25,7 +25,7 @@ const CREDENTIAL_ASSIGNMENT_PATTERN = /\b(?:token|secret|password|api[_-]?key)\s
 const CLOUD_CREDENTIAL_PATTERN = /\bAKIA[0-9A-Z]{16}\b|AIza[0-9A-Za-z_-]{20,}/;
 const EVIDENCE_KINDS = new Set(["implementation", "decision", "activity"]);
 const EVIDENCE_FIELDS = new Set(["kind", "title", "statement", "scope", "area", "itemRef", "verificationRefs"]);
-const SYNC_FIELDS = new Set(["harness", "sessionRef", "fromTurn", "toTurn", "title", "summary", "evidence", "verification", "decisions", "redactionVersion", "supersedesSyncId"]);
+const SYNC_FIELDS = new Set(["harness", "sessionRef", "fromTurn", "toTurn", "title", "summary", "evidence", "verification", "decisions", "redactionVersion", "supersedesSyncId", "force"]);
 const AI_PROFILE_FIELDS = new Set(["harness", "sessionRef", "fromTurn", "toTurn", "category", "model", "thinking", "evidence"]);
 const AI_PROFILE_EVIDENCE_FIELDS = new Set(["dimension", "statement", "signal", "turn"]);
 const AI_PROFILE_DIMENSIONS = new Set(["task_selection", "goal_clarity", "context_sharing", "constraint_setting", "work_decomposition", "iterative_steering", "critical_judgment", "verification", "application", "responsible_use"]);
@@ -39,7 +39,7 @@ const MAX_TURNS_PER_SEGMENT = 12;
 const MAX_TITLE_LENGTH = 160;
 const MAX_WORK_DETAIL_LENGTH = 600;
 const CONFIG_VERSION = 2;
-const RUNNER_VERSION = "0.3.11";
+const RUNNER_VERSION = "0.3.12";
 const REDACTION_VERSION = 4;
 const DEFAULT_INTERVAL_HOURS = 1;
 const LEGACY_INTERVAL_HOURS = 4;
@@ -1330,6 +1330,8 @@ function validateSync(input, harness) {
   if (!input || Object.keys(input).some((field) => !SYNC_FIELDS.has(field))) throw new Error("Remove unsupported fields from the reviewed sync payload.");
   if (!input || input.harness !== harness || !sessionRefIsSafe(input.sessionRef)) throw new Error("Add the current opaque sessionRef before syncing.");
   if (Object.hasOwn(input, "supersedesSyncId") && (!Number.isSafeInteger(input.supersedesSyncId) || input.supersedesSyncId < 1)) throw new Error("Use the positive supersedesSyncId returned by force discovery.");
+  if (Object.hasOwn(input, "force") && typeof input.force !== "boolean") throw new Error("Use force: true only for explicitly requested force sync.");
+  if (input.force && input.supersedesSyncId) throw new Error("Use force: true without supersedesSyncId, or the legacy supersedesSyncId mode alone.");
   if (!Number.isInteger(input.fromTurn) || !Number.isInteger(input.toTurn) || input.fromTurn < 1 || input.toTurn < input.fromTurn || input.toTurn > 1_000_000 || input.toTurn - input.fromTurn >= MAX_TURNS_PER_SEGMENT) throw new Error("Use a valid incremental range of at most 12 turns.");
   if (input.redactionVersion >= 3 && !textIsSafe(input.title, MAX_TITLE_LENGTH)) throw new Error("Add a concise, redacted title for this reviewed sync.");
   if (!textIsSafe(input.summary, 1200)) throw new Error("The summary is empty, too long, or contains sensitive content. Redact it before syncing.");
@@ -1374,7 +1376,7 @@ function validateAIProfileObservation(input, harness) {
 
 function validSyncReceipt(receipt, input) {
   return receipt?.sessionRef === input.sessionRef && receipt.acceptedToTurn === input.toTurn && Number.isInteger(receipt.lastSyncedTurn) && receipt.lastSyncedTurn <= 1_000_000 &&
-    (receipt.duplicate || input.supersedesSyncId ? receipt.lastSyncedTurn >= input.toTurn : receipt.lastSyncedTurn === input.toTurn);
+    (receipt.duplicate || input.force || input.supersedesSyncId ? receipt.lastSyncedTurn >= input.toTurn : receipt.lastSyncedTurn === input.toTurn);
 }
 
 function sleep(milliseconds) {
@@ -1392,6 +1394,7 @@ function retryDelay(response, attempt) {
 }
 
 async function postSync(config, input) {
+  const body = JSON.stringify(input.force ? { ...input, forceRequestId: randomUUID() } : input);
   let lastError;
   for (let attempt = 0; attempt < MAX_RETRIES; attempt += 1) {
     let response;
@@ -1399,7 +1402,7 @@ async function postSync(config, input) {
       response = await fetch(`${config.apiUrl}/v1/connectors/coding-sessions/syncs`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${config.token}` },
-        body: JSON.stringify(input),
+        body,
         signal: AbortSignal.timeout(30_000),
       });
     } catch (error) {
@@ -1620,9 +1623,10 @@ async function sendSync(harness, input, config = readConfig(harness)) {
   const state = readState(harness);
   const checkpoint = state.sessions[input.sessionRef];
   const expected = (checkpoint?.lastSyncedTurn || 0) + 1;
-  if (!input.supersedesSyncId && input.fromTurn !== expected) throw new Error(`This local checkpoint expects turn ${expected}. Review the pending segment before retrying.`);
-  if (input.supersedesSyncId && reviewSegment(harness, input.sessionRef, input.fromTurn, input.toTurn).turnCount < input.toTurn) throw new Error("The original local turns must still exist before replacing this sync.");
-  const profile = input.supersedesSyncId ? undefined : profileForSegment(harness, input);
+  const force = input.force || Boolean(input.supersedesSyncId);
+  if (!force && input.fromTurn !== expected) throw new Error(`This local checkpoint expects turn ${expected}. Review the pending segment before retrying.`);
+  if (force && reviewSegment(harness, input.sessionRef, input.fromTurn, input.toTurn).turnCount < input.toTurn) throw new Error("The original local turns must still exist before force syncing this range.");
+  const profile = force ? undefined : profileForSegment(harness, input);
   const receipt = await postSync(config, input);
   if (!validSyncReceipt(receipt, input)) {
     throw new Error("Shifu returned a checkpoint that does not match this reviewed segment. Local state was not advanced.");
@@ -1634,7 +1638,7 @@ async function sendSync(harness, input, config = readConfig(harness)) {
   state.sessions[input.sessionRef] = { turnsSinceSync: 0, lastSyncedAt: Date.now(), lastSyncedTurn: Math.max(checkpoint?.lastSyncedTurn || 0, receipt.lastSyncedTurn), syncDue: false };
   saveState(harness, state);
   if (profile) await flushPendingProfiles(harness, config);
-  console.error(receipt.duplicate ? "Shifu already had this exact segment. Local checkpoint recovered." : input.supersedesSyncId ? `Replaced the reviewed sync for turns ${input.fromTurn}–${input.toTurn}.` : `Synced through turn ${receipt.lastSyncedTurn}.`);
+  console.error(receipt.duplicate ? "Shifu already had this exact segment. Local checkpoint recovered." : force ? `Force synced the reviewed range for turns ${input.fromTurn}–${input.toTurn}.` : `Synced through turn ${receipt.lastSyncedTurn}.`);
   return receipt;
 }
 
@@ -1672,7 +1676,7 @@ async function sync(harness) {
   const config = readConfig(harness);
   const input = readJSON(0, undefined);
   validateSync(input, harness);
-  if (hasFlag("--force") !== Boolean(input.supersedesSyncId)) throw new Error("Force replacement requires both --force and the reviewed payload's supersedesSyncId. Use ordinary sync for new segments.");
+  if (hasFlag("--force") !== Boolean(input.force || input.supersedesSyncId)) throw new Error("Force sync requires both --force and force: true in the reviewed payload (or a legacy supersedesSyncId).");
   const policy = normalizedPolicy(config);
   if (policy.approvalMode === "manual" && !hasFlag("--approved")) {
     console.error(`\nThis exact redacted segment will be sent to Shifu:\n${JSON.stringify(input, null, 2)}`);
@@ -1906,6 +1910,30 @@ async function acceptedSegments(config, sessionRef) {
   throw new Error("Shifu returned an invalid sync-segment cursor.");
 }
 
+function forceSegments(session, accepted, since) {
+  const selected = session.turnTimes.map((timestamp) => since === undefined || Date.parse(timestamp) >= since);
+  const covered = new Set();
+  const segments = [];
+  const unavailable = [];
+  for (const segment of accepted) {
+    if (!selected.slice(segment.fromTurn - 1, segment.toTurn).some(Boolean)) continue;
+    for (let turn = segment.fromTurn; turn <= Math.min(segment.toTurn, session.turnCount); turn += 1) covered.add(turn);
+    if (segment.toTurn > session.turnCount) {
+      unavailable.push({ sessionRef: session.sessionRef, fromTurn: segment.fromTurn, toTurn: segment.toTurn, reason: "local_turns_missing" });
+      continue;
+    }
+    segments.push({ sessionRef: session.sessionRef, fromTurn: segment.fromTurn, toTurn: segment.toTurn, force: true });
+  }
+  for (let fromTurn = 1; fromTurn <= session.turnCount; fromTurn += 1) {
+    if (!selected[fromTurn - 1] || covered.has(fromTurn)) continue;
+    let toTurn = fromTurn;
+    while (toTurn < session.turnCount && toTurn - fromTurn + 1 < MAX_TURNS_PER_SEGMENT && selected[toTurn] && !covered.has(toTurn + 1)) toTurn += 1;
+    segments.push({ sessionRef: session.sessionRef, fromTurn, toTurn, force: true });
+    fromTurn = toTurn;
+  }
+  return { segments: segments.sort((left, right) => left.fromTurn - right.fromTurn), unavailable };
+}
+
 async function sessions(harness) {
   const config = readConfig(harness);
   const count = option("--count");
@@ -1919,25 +1947,21 @@ async function sessions(harness) {
   if (all && !sessionRef) throw new Error("Use --all only with an explicitly selected --session-ref.");
   const countValue = count === undefined ? undefined : Number(count);
   if (hasFlag("--force")) {
-    if (hasFlag("--turns")) throw new Error("Force replacement uses the original stored ranges; do not provide --turns.");
+    if (hasFlag("--turns")) throw new Error("Force sync preserves stored ranges and bounds new ranges to 12 turns; do not provide --turns.");
     const selected = selectedSessionSegments(harness, { hours, selectedRef: sessionRef, includeOlder: true, count: countValue });
     const replacements = [];
     const unavailable = [];
-    const since = Date.now() - hours * 3_600_000;
+    const since = all || count !== undefined ? undefined : Date.now() - hours * 3_600_000;
     const metadataByRef = new Map();
     for (const metadata of localSessions(harness)) {
-      if (metadata.turnCount >= (metadataByRef.get(metadata.sessionRef)?.turnCount || 0)) metadataByRef.set(metadata.sessionRef, metadata);
+      const prior = metadataByRef.get(metadata.sessionRef);
+      if (!prior || metadata.turnCount > prior.turnCount || (metadata.turnCount === prior.turnCount && metadata.updatedAt > prior.updatedAt)) metadataByRef.set(metadata.sessionRef, metadata);
     }
     for (const session of selected) {
       const metadata = metadataByRef.get(session.sessionRef);
-      for (const segment of await acceptedSegments(config, session.sessionRef)) {
-        if (segment.toTurn > session.turnCount) {
-          unavailable.push({ sessionRef: session.sessionRef, supersedesSyncId: segment.id, reason: "local_turns_missing" });
-          continue;
-        }
-        if (!all && count === undefined && !(Date.parse(metadata.turnTimes[segment.fromTurn - 1]) >= since)) continue;
-        replacements.push({ sessionRef: session.sessionRef, fromTurn: segment.fromTurn, toTurn: segment.toTurn, supersedesSyncId: segment.id });
-      }
+      const ranges = forceSegments(metadata, await acceptedSegments(config, session.sessionRef), since);
+      replacements.push(...ranges.segments);
+      unavailable.push(...ranges.unavailable);
     }
     console.log(JSON.stringify({ harness, ...(count === undefined ? { hours } : { count: countValue, selectedSessionRefs: selected.map((item) => item.sessionRef) }), force: true, sessions: replacements, unavailableSegments: unavailable }, null, 2));
     return;
@@ -1973,17 +1997,25 @@ async function review(harness) {
   let toTurn = Math.min(selected.turnCount, fromTurn + turns - 1);
   let supersedesSyncId;
   if (hasFlag("--force")) {
-    if (hasFlag("--turns")) throw new Error("Force review uses the original stored range; do not provide --turns.");
+    if (hasFlag("--turns")) throw new Error("Force review uses the discovered range; do not provide --turns.");
     fromTurn = numberOption("--from-turn");
     toTurn = numberOption("--to-turn");
-    supersedesSyncId = numberOption("--supersedes-sync-id");
-    const target = (await acceptedSegments(config, sessionRef)).find((segment) => segment.id === supersedesSyncId && segment.fromTurn === fromTurn && segment.toTurn === toTurn);
-    if (!target || toTurn > selected.turnCount) throw new Error("Use the exact current segment and supersedesSyncId from sessions --force; the original local turns must still exist.");
+    if (!Number.isInteger(fromTurn) || !Number.isInteger(toTurn) || fromTurn < 1 || toTurn < fromTurn || toTurn - fromTurn >= MAX_TURNS_PER_SEGMENT || toTurn > selected.turnCount) throw new Error("Use the exact range from sessions --force; the original local turns must still exist.");
+    const accepted = await acceptedSegments(config, sessionRef);
+    const overlapping = accepted.filter((segment) => segment.fromTurn <= toTurn && segment.toTurn >= fromTurn);
+    if (overlapping.some((segment) => segment.fromTurn !== fromTurn || segment.toTurn !== toTurn)) throw new Error("This range partially overlaps accepted work. Run sessions --force and re-review its original complete range.");
+    if (hasFlag("--supersedes-sync-id")) {
+      supersedesSyncId = numberOption("--supersedes-sync-id");
+      if (!overlapping.some((segment) => segment.id === supersedesSyncId)) throw new Error("The replacement target changed. Run sessions --force and re-review the current range.");
+    }
   } else if (["--from-turn", "--to-turn", "--supersedes-sync-id"].some(hasFlag)) {
     throw new Error("Explicit replacement boundaries require --force.");
   }
   if (fromTurn > toTurn) throw new Error(`This ${HARNESS_NAMES[harness]} session has no unsynced turns to review.`);
-  if (!hasFlag("--all") && !(Date.parse(selected.turnTimes[fromTurn - 1]) >= Date.now() - hours * 3_600_000)) {
+  const withinWindow = hasFlag("--force")
+    ? selected.turnTimes.slice(fromTurn - 1, toTurn).some((timestamp) => Date.parse(timestamp) >= Date.now() - hours * 3_600_000)
+    : Date.parse(selected.turnTimes[fromTurn - 1]) >= Date.now() - hours * 3_600_000;
+  if (!hasFlag("--all") && !withinWindow) {
     throw new Error("This session's selected turn predates the selected window. Ask for this specific session and use --all to review its backlog.");
   }
   const { notes } = reviewSegment(harness, sessionRef, fromTurn, toTurn);
@@ -1992,7 +2024,7 @@ async function review(harness) {
     sessionRef,
     fromTurn,
     toTurn,
-    ...(supersedesSyncId ? { supersedesSyncId } : {}),
+    ...(hasFlag("--force") ? { force: true } : {}),
     oldestUnsyncedAt: selected.turnTimes[fromTurn - 1] || null,
     source: "Local assistant final notes for the selected user turns. Candidates are suggestions, not verified or guaranteed redacted; inspect them before constructing a Shifu payload.",
     notes,

package/commands/shifu-sync.md

@@ -21,4 +21,4 @@ For an explicit sync-now request:
 
 To connect or replace a key, run `npx --yes @useshifu/coding-harness connect --harness opencode`. Connect asks for a key with a normal visible terminal prompt and verifies it with Shifu before reporting success. Do not ask the user to paste the key into chat. If this tool terminal cannot run the command or accept input, ask the user to run it in their own interactive terminal and report the output; do not claim the connection succeeded. To disconnect locally, run `npx --yes @useshifu/coding-harness disconnect --harness opencode`. New connections use one-hour automatic sync and `~/Desktop/Shifu` on macOS by default. To change the interval, approval policy, or folder later, run `config update --harness opencode` with the desired flags (for example, `--input-folder <existing-readable-folder>`).
 
-For an explicit user force-sync request, use `sessions --harness opencode --force` with the requested window/count. Keep its initial targets fixed. Each accepted segment includes `supersedesSyncId` and exact original boundaries. Re-review with `review --harness opencode --session-ref <sessionRef> --force --from-turn <fromTurn> --to-turn <toTurn> --supersedes-sync-id <supersedesSyncId>` using the same window or explicit `--all`. Redact the final notes again and add the returned `supersedesSyncId` to the prepared payload; send with `sync --harness opencode --force`, following the saved approval policy. New pending turns use ordinary sync. Never guess boundaries, replace a changed target, or force scheduled/file sync. Checkpoints and history are preserved; identical retries are safe. Work replacements leave AI Profile observations unchanged. Start a new chat in Shifu to use the latest work context.
+For an explicit user force-sync request, use `sessions --harness opencode --force` with the requested window/count. It selects local turns independently of checkpoints, including already synced work and ranges missing from the server. It preserves whole stored ranges touching selected turns (including older turns across a window boundary) and splits uncovered selected turns into ranges of at most 12. Keep the initial targets fixed and report `unavailableSegments` honestly. Re-review with `review --harness opencode --session-ref <sessionRef> --force --from-turn <fromTurn> --to-turn <toTurn>` using the same window or explicit `--all`; no old receipt ID is needed. Redact the final notes again and add `force: true` to the prepared payload; send with `sync --harness opencode --force`, following the saved approval policy. Never guess boundaries or force scheduled/file sync. On a partial-overlap rejection, re-discover and re-review the complete ranges. Checkpoints and history are preserved; identical retries are safe. Force sync leaves AI Profile observations unchanged. Start a new chat in Shifu to use the latest work context.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useshifu/coding-harness",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "Scheduled, redacted coding-harness activity sync for Shifu",
   "bin": {
     "coding-harness": "bin/shifu-harness.js",

package/skills/shifu-sync/SKILL.md

@@ -97,10 +97,10 @@ printf '%s' '<redacted JSON>' | npx --yes @useshifu/coding-harness sync --approv
 
 If a transport or server error remains after the runner's retries, report that the checkpoint was not advanced. Do not alter the segment or skip ahead.
 
-## Explicit force replacement
+## Explicit force sync
 
-Only when the user explicitly asks to force-sync or replace previously synced work, add `--force` to `sessions` with their requested window or count. It returns current server segments with `supersedesSyncId` and their original `fromTurn`/`toTurn`; never guess replacement ranges from local checkpoints. Force discovery lists accepted segments only. New pending turns still use ordinary sync. Keep the initial returned targets fixed rather than repeating force discovery after each replacement.
+Only when the user explicitly asks to force-sync, add `--force` to `sessions` with their requested window or count. Force chooses local turns independently of local and server checkpoints, including already synced sessions and work never accepted by the server. It preserves complete stored range boundaries when they touch the selected window and splits uncovered selected turns into ranges of at most 12. A stored range crossing the window can include older turns so it is replaced in full. Missing local turns are reported in `unavailableSegments`; never invent them or silently count them as synced. Keep the initial returned targets fixed while processing this force request.
 
-Re-review each returned target with `review --harness codex --session-ref <sessionRef> --force --from-turn <fromTurn> --to-turn <toTurn> --supersedes-sync-id <supersedesSyncId>` and the same window (or `--all` for explicitly selected backfill/count selection). The original local turns must still exist. Inspect and redact the final notes again, preserving supported work detail. Add that exact `supersedesSyncId` to the prepared payload and send with `sync --harness codex --force` (plus `--approved` only after manual approval). Preserve the original reference and turn range. If another replacement already changed the target, stop and re-discover/re-review; do not silently force over newer work.
+Re-review each returned range with `review --harness codex --session-ref <sessionRef> --force --from-turn <fromTurn> --to-turn <toTurn>` and the same window (or `--all` for explicitly selected backfill/count selection). No prior sync ID is required. Inspect and redact the final notes again, preserving supported work detail. Keep the returned reference and range unchanged and include `force: true` in the prepared payload. Send with `sync --harness codex --force` (plus `--approved` only after manual approval). If accepted ranges changed and partially overlap the selection, stop and re-discover/re-review the complete ranges instead of guessing boundaries.
 
-Force replacement preserves sync history and never lowers checkpoints. Identical retries are safe. It replaces work evidence and claims for that segment; existing AI Profile observations stay unchanged. Do not add force to scheduled sync, approval queues, or file sync. Existing conversations keep their context; start a new chat in Shifu to use the latest work context.
+Force sync creates missing ranges or replaces existing exact ranges, preserves sync history, and never resets or lowers checkpoints. Automatic retries preserve the accepted result even if another force sync finishes meanwhile. A new invocation is a new explicit force request. Existing AI Profile observations stay unchanged. Do not add force to scheduled sync, approval queues, or file sync. Existing conversations keep their context; start a new chat in Shifu to use the latest work context.