@useshifu/coding-harness 0.3.10 → 0.3.12

package/README.md

@@ -32,6 +32,10 @@ To disconnect this device, run `npx --yes @useshifu/coding-harness disconnect --
 
 ## Operate
 
+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
@@ -43,6 +47,8 @@ npx --yes @useshifu/coding-harness sync-files --harness codex
 
 To select by session count instead of a time window, run `sessions --harness codex --count 5`. It selects the five most recently updated eligible sessions, newest first, without an hours cutoff. Current and setup sessions are excluded. `selectedSessionRefs` fixes that selection; `sessions` contains pending segments and `skippedSessions` reports already-synced sessions. Skipped sessions are not replaced with older ones. Review each pending session with `review --harness codex --session-ref <sessionRef> --all`. After an accepted segment, request the next with `sessions --harness codex --session-ref <sessionRef> --all` until that selected session is exhausted. Keep the original references instead of selecting another five.
 
+Time-window selection accepts any positive whole number of days or hours. `sessions --harness codex --days 3` uses the same window as `--hours 72`; pass the same window to `review`. `--days 7` also works. Mixed, missing, invalid, or unsupported options fail explicitly. A recently active session with older unsynced turns appears in `blockedSessions`: sync cannot skip those turns. Explicitly select that session with `--session-ref <sessionRef> --all` to backfill in chronological segments of at most 12 turns.
+
 Manual session sync runs immediately, independently of the hourly schedule. If a segment fails, report it as failed/pending; a checkpoint advances only after a matching server receipt. Report completed, already-synced, and failed session counts separately.
 
 To upgrade an existing installation, run `npx --yes @useshifu/coding-harness@latest install --harness codex` (or `claude_code` / `opencode`). It replaces the local runner and harness instruction while preserving the connection, checkpoints, and schedule. Reconnecting is unnecessary. `status` includes `runnerVersion` so you can verify the installed version.
@@ -73,6 +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 the latest published release, `0.3.9`. 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.12 install --harness codex`). Raise the server recommendation only after the target release is published and its backend requirements are deployed.
+
+## Force sync local work
+
+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 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.
 
-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.10 install --harness codex`, after publication). Raise the server recommendation only after the target release is published.
+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"]);
+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.10";
+const RUNNER_VERSION = "0.3.12";
 const REDACTION_VERSION = 4;
 const DEFAULT_INTERVAL_HOURS = 1;
 const LEGACY_INTERVAL_HOURS = 4;
@@ -178,6 +178,43 @@ function hasFlag(name) {
   return process.argv.includes(name);
 }
 
+function validateSyncOptions(command, start = 3) {
+  const common = ["--harness", "--config-root"];
+  const options = {
+    sessions: [...common, "--hours", "--days", "--count", "--turns", "--session-ref"],
+    review: [...common, "--hours", "--days", "--turns", "--session-ref", "--from-turn", "--to-turn", "--supersedes-sync-id"],
+    sync: common,
+    "sync-files": common,
+    "scheduled-sync": common,
+    pending: common,
+    approve: common,
+  };
+  const flags = {
+    sessions: ["--all", "--force"], review: ["--all", "--force"], sync: ["--approved", "--force"], approve: ["--approved"],
+  };
+  if (!options[command]) return;
+  const seen = new Set();
+  for (let index = start; index < process.argv.length; index += 1) {
+    const argument = process.argv[index];
+    if (seen.has(argument)) throw new Error(`Provide ${argument} only once.`);
+    seen.add(argument);
+    if ((flags[command] || []).includes(argument)) continue;
+    if (!options[command].includes(argument)) throw new Error(`Unsupported option ${argument} for ${command}.`);
+    const value = process.argv[++index];
+    if (value === undefined || value.startsWith("--")) throw new Error(`Provide a value for ${argument}.`);
+  }
+}
+
+function syncWindowHours() {
+  if (hasFlag("--days") && hasFlag("--hours")) throw new Error("Use either --days or --hours, not both.");
+  const name = hasFlag("--days") ? "--days" : "--hours";
+  const value = numberOption(name, 24);
+  if (!Number.isSafeInteger(value) || value < 1) throw new Error(`Choose a positive whole number for ${name}.`);
+  const hours = name === "--days" ? value * 24 : value;
+  if (!Number.isSafeInteger(hours) || hours * 3_600_000 > 8_640_000_000_000_000) throw new Error("The requested sync window is too large.");
+  return hours;
+}
+
 function readJSON(file, fallback) {
   try {
     return JSON.parse(fs.readFileSync(file, "utf8"));
@@ -892,7 +929,7 @@ function validateGeneratedProfile(profile, harness) {
 }
 
 function selectedSessionSegments(harness, { hours = 24, turns = MAX_TURNS_PER_SEGMENT, selectedRef, includeOlder = false, count } = {}) {
-  if (count === undefined && ![24, 48, 72].includes(hours)) throw new Error("Choose --hours 24, 48, or 72.");
+  if (count === undefined && (!Number.isSafeInteger(hours) || hours < 1)) throw new Error("Choose a positive whole number for --hours.");
   if (count !== undefined && (!Number.isSafeInteger(count) || count < 1)) throw new Error("Choose a positive whole number for --count.");
   if (!Number.isInteger(turns) || turns < 1 || turns > MAX_TURNS_PER_SEGMENT) throw new Error("Choose --turns between 1 and 12.");
   const since = Date.now() - hours * 3_600_000;
@@ -1292,6 +1329,9 @@ function sessionRefIsSafe(value) {
 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.");
@@ -1335,8 +1375,8 @@ function validateAIProfileObservation(input, harness) {
 }
 
 function validSyncReceipt(receipt, input) {
-  return receipt?.sessionRef === input.sessionRef && receipt.acceptedToTurn === input.toTurn && Number.isInteger(receipt.lastSyncedTurn) &&
-    (receipt.duplicate ? receipt.lastSyncedTurn >= input.toTurn : receipt.lastSyncedTurn === input.toTurn);
+  return receipt?.sessionRef === input.sessionRef && receipt.acceptedToTurn === input.toTurn && Number.isInteger(receipt.lastSyncedTurn) && receipt.lastSyncedTurn <= 1_000_000 &&
+    (receipt.duplicate || input.force || input.supersedesSyncId ? receipt.lastSyncedTurn >= input.toTurn : receipt.lastSyncedTurn === input.toTurn);
 }
 
 function sleep(milliseconds) {
@@ -1354,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;
@@ -1361,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) {
@@ -1582,18 +1623,22 @@ 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.fromTurn !== expected) throw new Error(`This local checkpoint expects turn ${expected}. Review the pending segment before retrying.`);
-  const profile = 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.");
   }
-  state.profilePending ||= {};
-  state.profilePending[`${profile.sessionRef}:${profile.fromTurn}:${profile.toTurn}`] = profile;
-  state.sessions[input.sessionRef] = { turnsSinceSync: 0, lastSyncedAt: Date.now(), lastSyncedTurn: receipt.lastSyncedTurn, syncDue: false };
+  if (profile) {
+    state.profilePending ||= {};
+    state.profilePending[`${profile.sessionRef}:${profile.fromTurn}:${profile.toTurn}`] = profile;
+  }
+  state.sessions[input.sessionRef] = { turnsSinceSync: 0, lastSyncedAt: Date.now(), lastSyncedTurn: Math.max(checkpoint?.lastSyncedTurn || 0, receipt.lastSyncedTurn), syncDue: false };
   saveState(harness, state);
-  await flushPendingProfiles(harness, config);
-  console.error(receipt.duplicate ? "Shifu already had this exact segment. Local checkpoint recovered." : `Synced through turn ${receipt.lastSyncedTurn}.`);
+  if (profile) await flushPendingProfiles(harness, config);
+  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;
 }
 
@@ -1631,6 +1676,7 @@ async function sync(harness) {
   const config = readConfig(harness);
   const input = readJSON(0, undefined);
   validateSync(input, harness);
+  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)}`);
@@ -1836,23 +1882,95 @@ async function syncFilesNow(harness) {
   if (result.failures) throw new Error("Some input files need retry. They will be checked on the next sync.");
 }
 
-function sessions(harness) {
-  readConfig(harness);
+async function acceptedSegments(config, sessionRef) {
+  const segments = [];
+  let cursor = 0;
+  do {
+    const url = new URL(`${config.apiUrl}/v1/connectors/coding-sessions/syncs`);
+    url.searchParams.set("sessionRef", sessionRef);
+    if (cursor) url.searchParams.set("cursor", String(cursor));
+    const response = await fetch(url, { headers: { Authorization: `Bearer ${config.token}` }, signal: AbortSignal.timeout(30_000) });
+    const payload = await response.json().catch(() => undefined);
+    if (!response.ok) throw new Error(payload?.error?.message || `Could not inspect accepted sync segments (${response.status}).`);
+    const page = payload?.data;
+    if (!Array.isArray(page?.segments) || page.segments.length > 100 || page.segments.some((segment, index) =>
+      !Number.isSafeInteger(segment.id) || segment.id < 1 || segment.sessionRef !== sessionRef ||
+      !Number.isInteger(segment.fromTurn) || !Number.isInteger(segment.toTurn) || segment.fromTurn < 1 ||
+      segment.toTurn < segment.fromTurn || segment.toTurn - segment.fromTurn >= MAX_TURNS_PER_SEGMENT ||
+      segment.toTurn > 1_000_000 || segment.fromTurn <= (index ? page.segments[index - 1].toTurn : cursor))) {
+      throw new Error("Shifu returned invalid accepted sync segments. No replacement was sent.");
+    }
+    segments.push(...page.segments);
+    const next = page.nextCursor;
+    if (next === undefined || next === null || next === "") return segments;
+    const nextTurn = Number(next);
+    if (typeof next !== "string" || !/^[1-9]\d*$/.test(next) || !Number.isInteger(nextTurn) || nextTurn <= cursor || nextTurn !== page.segments.at(-1)?.toTurn) throw new Error("Shifu returned an invalid sync-segment cursor.");
+    cursor = nextTurn;
+  } while (cursor < 1_000_000);
+  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");
   if (hasFlag("--count") && count === undefined) throw new Error("Provide a value for --count.");
-  if (count !== undefined && option("--hours") !== undefined) throw new Error("Use either --count or --hours, not both.");
-  const hours = numberOption("--hours", 24);
+  if (count !== undefined && (hasFlag("--hours") || hasFlag("--days"))) throw new Error("Use --count without --hours or --days.");
+  const hours = syncWindowHours();
   const turns = numberOption("--turns", MAX_TURNS_PER_SEGMENT);
   const sessionRef = option("--session-ref");
   const all = hasFlag("--all");
   if (count !== undefined && (sessionRef || all)) throw new Error("Use --count without --session-ref or --all.");
   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 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 = all || count !== undefined ? undefined : Date.now() - hours * 3_600_000;
+    const metadataByRef = new Map();
+    for (const metadata of localSessions(harness)) {
+      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);
+      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;
+  }
   const selected = selectedSessionSegments(harness, { hours, turns, selectedRef: sessionRef, includeOlder: all, count: countValue });
   const pending = selected.filter((session) => session.fromTurn <= session.toTurn);
   const blocked = all || count !== undefined ? [] : unsyncedCodexSessions(harness, { hours, turns, selectedRef: sessionRef, includeOlder: true })
     .filter((session) => !pending.some((item) => item.sessionRef === session.sessionRef))
-    .map(({ sessionRef, oldestUnsyncedAt }) => ({ sessionRef, oldestUnsyncedAt }));
+    .map(({ sessionRef, oldestUnsyncedAt }) => ({ sessionRef, oldestUnsyncedAt, reason: "older_unsynced_turns", nextStep: "Select this session explicitly with --session-ref and --all to backfill in order." }));
   console.log(JSON.stringify(count === undefined
     ? { harness, hours, turns, sessions: pending, blockedSessions: blocked }
     : {
@@ -1864,32 +1982,51 @@ function sessions(harness) {
     }, null, 2));
 }
 
-function review(harness) {
-  readConfig(harness);
+async function review(harness) {
+  const config = readConfig(harness);
   const sessionRef = option("--session-ref");
   if (typeof sessionRef !== "string" || sessionRef.length < 8) throw new Error(`Provide an opaque ${HARNESS_NAMES[harness]} --session-ref from the sessions command.`);
   const state = readState(harness);
-  const fromTurn = (state.sessions[sessionRef]?.lastSyncedTurn || 0) + 1;
+  let fromTurn = (state.sessions[sessionRef]?.lastSyncedTurn || 0) + 1;
   const selected = localSessions(harness).filter((session) => session.sessionRef === sessionRef)
     .sort((left, right) => right.turnCount - left.turnCount || right.updatedAt.localeCompare(left.updatedAt))[0];
   if (!selected) throw new Error(`No local ${HARNESS_NAMES[harness]} session matches this reference.`);
-  const hours = numberOption("--hours", 24);
-  if (![24, 48, 72].includes(hours)) throw new Error("Choose --hours 24, 48, or 72.");
-  if (!hasFlag("--all") && !(Date.parse(selected.turnTimes[fromTurn - 1]) >= Date.now() - hours * 3_600_000)) {
-    throw new Error("This session's next unsynced turn predates the selected window. Ask for this specific session and use --all to review its backlog.");
-  }
+  const hours = syncWindowHours();
   const turns = numberOption("--turns", MAX_TURNS_PER_SEGMENT);
   if (!Number.isInteger(turns) || turns < 1 || turns > MAX_TURNS_PER_SEGMENT) throw new Error("Choose --turns between 1 and 12.");
-  const toTurn = Math.min(selected.turnCount, fromTurn + turns - 1);
+  let toTurn = Math.min(selected.turnCount, fromTurn + turns - 1);
+  let supersedesSyncId;
+  if (hasFlag("--force")) {
+    if (hasFlag("--turns")) throw new Error("Force review uses the discovered range; do not provide --turns.");
+    fromTurn = numberOption("--from-turn");
+    toTurn = numberOption("--to-turn");
+    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.`);
+  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);
   const candidates = reviewCandidates(notes);
   console.log(JSON.stringify({
     sessionRef,
     fromTurn,
     toTurn,
+    ...(hasFlag("--force") ? { force: true } : {}),
     oldestUnsyncedAt: selected.turnTimes[fromTurn - 1] || null,
-    source: "Local assistant final notes for unsynced user turns. Candidates are suggestions, not verified or guaranteed redacted; inspect them before constructing a Shifu payload.",
+    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,
     candidates,
     draft: { title: null, summary: null, evidence: candidates.map((candidate) => ({ ...candidate, title: null })) },
@@ -1935,6 +2072,7 @@ async function main() {
   if (option("--config-root")) process.env.SHIFU_CONFIG_ROOT = path.resolve(option("--config-root"));
   const command = process.argv[2];
   const subCommand = process.argv[3];
+  validateSyncOptions(command === "discover" || command === "session" ? "sessions" : command, command === "session" && ["discover", "list"].includes(subCommand) ? 4 : 3);
   const harness = requireHarness(option("--harness"));
   if (["sync", "sync-files", "scheduled-sync", "approve"].includes(command) && process.env.SHIFU_UPDATE_CHECKED !== "1" && await updateRecommendedPackage(harness)) {
     const child = spawn(process.execPath, [installedRunnerPath(), ...process.argv.slice(2)], {

package/commands/shifu-sync.md

@@ -12,11 +12,13 @@ If manual approval has queued scheduled work, run `pending --harness opencode`,
 
 For an explicit sync-now request:
 
-1. For a time-window request, run `sessions --harness opencode --hours 24`, using 48 or 72 only when requested. For a request by number of recent sessions, run `sessions --harness opencode --count <count>`; this ignores the hours window and returns the most recently updated sessions first.
-2. Review each returned segment with `review --harness opencode --session-ref <sessionRef> --hours <hours>`. For count-based selection, use `review --harness opencode --session-ref <sessionRef> --all` so older sessions are allowed.
+1. For a time-window request, run `sessions --harness opencode --hours 24`, using the positive whole number of hours requested. A day request uses `--days N`; `--days 3` and `--hours 72` are identical. Never combine the two flags. For a request by number of recent sessions, run `sessions --harness opencode --count <count>`; this ignores the hours window and returns the most recently updated sessions first.
+2. Report `blockedSessions` when older unsynced turns prevent the requested window from syncing; user-selected backfill uses `--session-ref <sessionRef> --all` and keeps chronological 12-turn segments. Review each returned segment with `review --harness opencode --session-ref <sessionRef> --hours <hours>`. Use the same hours or days value for discovery and review. For count-based selection, use `review --harness opencode --session-ref <sessionRef> --all` so older sessions are allowed.
 3. Prepare a redaction-version-four payload from final assistant notes only. Use `activity` evidence for writing, feedback, research, planning, product work, and any work that is not clearly an engineering implementation or decision. Activity evidence has no technical scope. Preserve the supported action, feature or project purpose, specific problem, approach, technologies and design patterns used, and verified result. Synthesize a descriptive project label (such as "payment reconciliation service") from its purpose; never copy a raw label that could identify a company or person. Keep distinct contributions separate, including different fixes within one feature. An empty evidence list advances the checkpoint without creating a claim.
 4. In automatic mode, pipe the payload to `sync --harness opencode` without asking again. In manual mode, show the exact payload, ask once, and then use `sync --approved --harness opencode`.
 5. Keep the returned session reference and turn range unchanged. Never upload prompts, raw transcripts, tool output, code, paths, commands, URLs, credentials, company or person names, customer details, or proprietary identifiers.
 6. For a count-based sync, keep `selectedSessionRefs` from the first discovery and review only pending `sessions`. `skippedSessions` reports already-synced selections; do not replace them with older sessions. If one has remaining turns, request its next segment with `sessions --harness opencode --session-ref <sessionRef> --all`. Stop after those selected sessions are exhausted. Report completed, already-synced, and failed/pending sessions separately. Manual sync runs immediately, independently of the hourly schedule.
 
 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. 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.10",
+  "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

@@ -55,11 +55,11 @@ Show the returned list and ask for one approval for the whole list. After approv
 
 ## Sync now
 
-For an explicit sync request, first read `status` to determine the saved approval mode. Manual sync runs immediately and does not wait for the hourly schedule. Use the time window the user names; otherwise use 24 hours. Supported interactive windows are 24, 48, and 72 hours. If the user specifies a number of recent sessions, use count-based selection instead; it has no hours cutoff and orders sessions from latest to earliest. It selects the latest eligible sessions, excluding current/setup sessions, and reports already-synced selections in `skippedSessions` without replacing them with older sessions.
+For an explicit sync request, first read `status` to determine the saved approval mode. Manual sync runs immediately and does not wait for the hourly schedule. Use the time window the user names; otherwise use 24 hours. Use `--days N` for a positive whole number of days or `--hours N` for a positive whole number of hours. Days use exactly the same selection and review rules as hours (`--days 3` equals `--hours 72`). Never combine them or silently substitute the default window. If the user specifies a number of recent sessions, use count-based selection instead; it has no hours cutoff and orders sessions from latest to earliest. It selects the latest eligible sessions, excluding current/setup sessions, and reports already-synced selections in `skippedSessions` without replacing them with older sessions.
 
-1. For a time-window sync, run `npx --yes @useshifu/coding-harness sessions --harness codex --hours <24|48|72>`. For a count-based sync, run `npx --yes @useshifu/coding-harness sessions --harness codex --count <count>`; do not add `--hours`.
-2. Ignore `blockedSessions` unless the user specifically selects one. For a selected older backlog, add `--session-ref <sessionRef> --all`.
-3. For each returned segment, run `npx --yes @useshifu/coding-harness review --harness codex --session-ref <sessionRef> --hours <24|48|72>`. For count-based selection, use `--all` instead of `--hours` so the review has no time cutoff.
+1. For a time-window sync, run `npx --yes @useshifu/coding-harness sessions --harness codex --hours <hours>`. For a count-based sync, run `npx --yes @useshifu/coding-harness sessions --harness codex --count <count>`; do not add `--hours` or `--days`.
+2. Report `blockedSessions` honestly: these recently active sessions have older unsynced turns and cannot skip ahead. Explain that explicit backfill is needed. For a user-selected older backlog, add `--session-ref <sessionRef> --all`; process its original turns chronologically in segments of at most 12.
+3. For each returned segment, run `npx --yes @useshifu/coding-harness review --harness codex --session-ref <sessionRef> --hours <hours>`. Use the same `--days` or `--hours` value for discovery and review. For count-based selection, use `--all` so the review has no time cutoff.
 4. Prepare a version-four payload from the returned final-assistant notes. Keep the returned `sessionRef`, `fromTurn`, and `toTurn` unchanged.
 5. In automatic mode, send it without another approval. In manual mode, show the exact payload and ask once; after approval, pass `--approved` to the sync command.
 6. For a time-window sync, repeat discovery after accepted segments until the selected window is exhausted. For a count-based sync, keep `selectedSessionRefs` from the first discovery and review only pending `sessions`. If a selected session has remaining turns, request its next segment with `sessions --harness codex --session-ref <sessionRef> --all`; stop after those selected sessions are exhausted. Report completed, already-synced, and failed/pending sessions separately. A failed session does not count as completed.
@@ -96,3 +96,11 @@ 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 sync
+
+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 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 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.