@useshifu/coding-harness 0.3.10 → 0.3.11

package/README.md

@@ -32,6 +32,8 @@ 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.
+
 ```sh
 npx --yes @useshifu/coding-harness status --harness codex
 npx --yes @useshifu/coding-harness sessions --harness codex --hours 24
@@ -43,6 +45,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 +77,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`, 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.
+
+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.
+
+## Replace previously synced 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.
+
+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.
 
-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.
+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.

package/bin/shifu-harness.js

@@ -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"]);
 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.11";
 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,7 @@ 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 (!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 +1373,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.supersedesSyncId ? receipt.lastSyncedTurn >= input.toTurn : receipt.lastSyncedTurn === input.toTurn);
 }
 
 function sleep(milliseconds) {
@@ -1582,18 +1620,21 @@ 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);
+  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 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." : input.supersedesSyncId ? `Replaced the reviewed sync for turns ${input.fromTurn}–${input.toTurn}.` : `Synced through turn ${receipt.lastSyncedTurn}.`);
   return receipt;
 }
 
@@ -1631,6 +1672,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.");
   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 +1878,75 @@ 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.");
+}
+
+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 replacement uses the original stored ranges; 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 metadataByRef = new Map();
+    for (const metadata of localSessions(harness)) {
+      if (metadata.turnCount >= (metadataByRef.get(metadata.sessionRef)?.turnCount || 0)) 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 });
+      }
+    }
+    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 +1958,43 @@ 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 original stored 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.");
+  } 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)) {
+    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,
+    ...(supersedesSyncId ? { supersedesSyncId } : {}),
     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 +2040,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. 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useshifu/coding-harness",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "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 replacement
+
+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.
+
+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.
+
+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.