@useshifu/coding-harness 0.3.9 → 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.
@@ -70,3 +74,19 @@ AI Profile observations are created automatically with each coding-session activ
 The category is one of `system_design`, `detailed_design`, `implementation`, `debugging_testing`, `production_support`, `research_analysis`, `product_planning`, `writing_communication`, `marketing_growth`, `learning`, or `other`. Evidence dimensions are `task_selection`, `goal_clarity`, `context_sharing`, `constraint_setting`, `work_decomposition`, `iterative_steering`, `critical_judgment`, `verification`, `application`, and `responsible_use`. Automatic observations cite the relevant turn and never infer a limiting behavior from silence. Unsupported dimensions remain unscored.
 
 The AI Profile page shows detected categories, model and thinking labels, and Jev scores supported by these limited observations. Local signals do not prove work quality or establish that another model setting would have performed better. Identical retries are safe.
+
+## 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.
+
+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.
+
+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

@@ -4,7 +4,9 @@ const fs = require("node:fs");
 const { createHash } = require("node:crypto");
 const os = require("node:os");
 const path = require("node:path");
-const { execFileSync } = require("node:child_process");
+const { execFile, execFileSync, spawn } = require("node:child_process");
+const { promisify } = require("node:util");
+const execFileAsync = promisify(execFile);
 const readline = require("node:readline/promises");
 
 const DEFAULT_API_URL = "https://api.useshifu.com";
@@ -23,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"]);
@@ -37,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.9";
+const RUNNER_VERSION = "0.3.11";
 const REDACTION_VERSION = 4;
 const DEFAULT_INTERVAL_HOURS = 1;
 const LEGACY_INTERVAL_HOURS = 4;
@@ -176,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"));
@@ -562,6 +601,7 @@ const WORK_ACTIONS = [
   { key: "reviewed", title: "Reviewed", pattern: /^(?:I\s+|We\s+)?(?:reviewed|audited)\b/i },
   { key: "investigated", title: "Investigated", pattern: /^(?:I\s+|We\s+)?(?:investigated|researched|evaluated|compared)\b/i },
   { key: "deployed", title: "Deployed", pattern: /^(?:I\s+|We\s+)?(?:deployed|published)\b/i },
+  { key: "decided", title: "Decided", pattern: /^(?:I\s+|We\s+)?(?:decided|chose|selected)\b/i },
 ];
 
 const WORK_OBJECTS = [
@@ -572,6 +612,11 @@ const WORK_OBJECTS = [
   { key: "claim_extraction", title: "claim extraction", pattern: /\b(?:claim extraction|claim generation|claim matching)\b/i },
   { key: "retry", title: "retry handling", pattern: /\b(?:retries|retry)\b/i },
   { key: "cache", title: "cache behavior", pattern: /\b(?:cache|caching|ttl)\b/i },
+  { key: "outbox", title: "transactional outbox", pattern: /\b(?:transactional outbox|outbox pattern)\b/i },
+  { key: "token_bucket", title: "token bucket limiter", pattern: /\btoken bucket limiter\b/i },
+  { key: "actor_scheduler", title: "actor scheduler", pattern: /\bactor scheduler\b/i },
+  { key: "quota_balancing", title: "quota balancing", pattern: /\bquota balancing\b/i },
+  { key: "shard_rebalancing", title: "shard rebalancing", pattern: /\bshard rebalancing\b/i },
   { key: "navigation", title: "navigation", pattern: /\b(?:navigation|sidebar|sub.?nav)\b/i },
   { key: "sync", title: "sync behavior", pattern: /\b(?:sync|synchronization|checkpoint)\b/i },
   { key: "auth", title: "authentication", pattern: /\b(?:authentication|sign.?in|login)\b/i },
@@ -626,6 +671,39 @@ const WORK_DETAILS = [
   { title: "mobile layout", pattern: /\bmobile layout\b/i },
 ];
 
+// These terms are safe to retain without copying surrounding private prose.
+const TECHNICAL_DETAILS = [
+  { title: "Redis", pattern: /\bRedis\b/i },
+  { title: "Kafka", pattern: /\bKafka\b/i },
+  { title: "Postgres", pattern: /\bPostgres(?:ql)?\b/i },
+  { title: "MongoDB", pattern: /\bMongoDB\b/i },
+  { title: "React", pattern: /\bReact\b/i },
+  { title: "Node.js", pattern: /\bNode\.js\b/i },
+  { title: "TypeScript", pattern: /\bTypeScript\b/i },
+  { title: "Python", pattern: /\bPython\b/i },
+  { title: "Spring Boot", pattern: /\bSpring Boot\b/i },
+  { title: "Kubernetes", pattern: /\bKubernetes\b/i },
+  { title: "Docker", pattern: /\bDocker\b/i },
+  { title: "GraphQL", pattern: /\bGraphQL\b/i },
+  { title: "gRPC", pattern: /\bgRPC\b/i },
+  { title: "cache-aside", pattern: /\bcache.aside\b/i },
+  { title: "transactional outbox", pattern: /\btransactional outbox\b/i },
+  { title: "circuit breaker", pattern: /\bcircuit breaker\b/i },
+  { title: "Builder Pattern", pattern: /\bBuilder Pattern\b/i },
+  { title: "event sourcing", pattern: /\bevent sourcing\b/i },
+  { title: "CQRS", pattern: /\bCQRS\b/i },
+  { title: "Saga Pattern", pattern: /\bSaga Pattern\b/i },
+  { title: "Repository Pattern", pattern: /\bRepository Pattern\b/i },
+  { title: "Dependency Injection", pattern: /\bDependency Injection\b/i },
+  { title: "OpenTelemetry", pattern: /\bOpenTelemetry\b/i },
+  { title: "Temporal", pattern: /\bTemporal\b/i },
+  { title: "Rust", pattern: /\bRust\b/i },
+  { title: "Tokio", pattern: /\bTokio\b/i },
+  { title: "consistent hashing", pattern: /\bconsistent hashing\b/i },
+  { title: "virtual nodes", pattern: /\bvirtual nodes\b/i },
+  { title: "adaptive jitter", pattern: /\badaptive jitter\b/i },
+];
+
 function controlledContexts(text) {
   const matches = WORK_CONTEXTS.flatMap((item) => {
     const match = item.pattern.exec(text);
@@ -640,15 +718,27 @@ function controlledContexts(text) {
 }
 
 function controlledDetails(text) {
-  return WORK_DETAILS.map((item) => ({ item, index: item.pattern.exec(text)?.index }))
+  const known = [...WORK_DETAILS, ...TECHNICAL_DETAILS];
+  const ttl = /\b(\d{1,3})[ -]hour TTL\b/i.exec(text);
+  const latency = /\bp(?:50|90|95|99) latency from (\d{1,4}) ms to (\d{1,4}) ms\b/i.exec(text);
+  const reductionPattern = /\b(?:cutting|cut|reducing|reduced|decreasing|decreased|lowering|lowered)\s+(queue time|memory(?: usage)?)\s+by\s*(\d{1,3}(?:\.\d{1,2})?)%(?![\d.])/i;
+  const reduction = reductionPattern.exec(text);
+  if (ttl) known.push({ title: `${ttl[1]}-hour TTL`, pattern: /\b\d{1,3}[ -]hour TTL\b/i });
+  if (latency) known.push({ title: latency[0], pattern: /\bp(?:50|90|95|99) latency from \d{1,4} ms to \d{1,4} ms\b/i });
+  if (reduction && Number(reduction[2]) <= 100) {
+    const metric = reduction[1].toLowerCase().startsWith("memory") ? "memory usage" : "queue time";
+    known.push({ title: `${metric} reduced by ${reduction[2]}%`, pattern: reductionPattern });
+  }
+  return known.map((item) => ({ item, index: item.pattern.exec(text)?.index }))
     .filter(({ index }) => index !== undefined)
     .sort((left, right) => left.index - right.index)
-    .slice(0, 3)
-    .map(({ item }) => item.title);
+    .map(({ item }) => item.title)
+    .filter((detail, index, details) => details.indexOf(detail) === index)
+    .slice(0, 6);
 }
 
 function withoutNamedLabels(text) {
-  return text.replace(/\b(?:Project|Client|Customer|Company)\s+[A-Z][A-Za-z0-9_-]*/g, "");
+  return text.replace(/\b(?:Project|Client|Customer|Company)\s+[A-Z][A-Za-z0-9_-]*/gi, "");
 }
 
 function safeActivityEvidence(notes) {
@@ -666,7 +756,7 @@ function safeActivityEvidence(notes) {
         sectionContexts = /\b(?:project|feature|flow|service|system|product)\b/i.test(label) ? controlledContexts(label) || [] : [];
         continue;
       }
-      const line = rawLine.trim().replace(/^[-*]\s+/, "").split(/[.;—]/, 1)[0];
+      const line = rawLine.trim().replace(/^[-*]\s+/, "").split(/[;—]|[.!?](?=\s|$)/, 1)[0];
       const clauses = line.split(/\s+(?:and|but|while)\s+/i);
       const nextAction = clauses.findIndex((clause, index) => index > 0 && WORK_ACTIONS.some((item) => item.pattern.test(clause)));
       const workClause = withoutNamedLabels(nextAction > 0 ? clauses.slice(0, nextAction).join(" and ") : line);
@@ -710,7 +800,7 @@ function payloadForSegment(harness, segment) {
     summary,
     evidence,
     verification: [],
-    decisions: [],
+    decisions: evidence.filter((item) => item.title.startsWith("Decided ")).slice(0, MAX_SYNC_ITEMS).map((item) => item.statement),
     redactionVersion: REDACTION_VERSION,
   };
 }
@@ -839,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;
@@ -940,8 +1030,14 @@ async function readSecret(input = process.stdin, output = process.stderr) {
 
 function copyRunner() {
   fs.mkdirSync(configRoot(), { recursive: true, mode: 0o700 });
-  fs.copyFileSync(__filename, installedRunnerPath());
-  fs.chmodSync(installedRunnerPath(), 0o700);
+  const temporary = `${installedRunnerPath()}.${process.pid}.tmp`;
+  try {
+    fs.copyFileSync(__filename, temporary);
+    fs.chmodSync(temporary, 0o700);
+    fs.renameSync(temporary, installedRunnerPath());
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
 }
 
 function copyDirectory(source, destination) {
@@ -1160,6 +1256,7 @@ async function validateConnection(apiUrl, token, harness) {
   if (!response.ok) throw new Error(`Shifu could not verify the connection key (HTTP ${response.status}). Nothing was changed.`);
   const result = await response.json().catch(() => null);
   if (result?.data?.connected !== true) throw new Error("Shifu returned an invalid connection check. Nothing was changed.");
+  return result.data;
 }
 
 async function connect(harness, readKey = readSecret) {
@@ -1232,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.");
@@ -1275,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) {
@@ -1522,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;
 }
 
@@ -1571,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)}`);
@@ -1776,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 }
     : {
@@ -1804,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 })) },
@@ -1838,11 +2003,55 @@ function review(harness) {
   }, null, 2));
 }
 
+function olderPackageVersion(current, recommended) {
+  const pattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+  if (!pattern.test(current) || !pattern.test(recommended)) return false;
+  const left = current.split(".").map(BigInt);
+  const right = recommended.split(".").map(BigInt);
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] < right[index];
+  }
+  return false;
+}
+
+async function installPackageVersion(version, harness) {
+  await execFileAsync("npm", ["exec", "--yes", `--package=@useshifu/coding-harness@${version}`, "--", "shifu-harness", "install", "--harness", harness, "--config-root", configRoot()], {
+    timeout: 60_000,
+    env: { ...process.env, PATH: `${process.env.PATH || ""}${path.delimiter}${path.dirname(process.execPath)}`, SHIFU_UPDATE_CHECKED: "1" },
+  });
+}
+
+async function updateRecommendedPackage(harness, { currentVersion = RUNNER_VERSION, fetchConnection = validateConnection, installVersion = installPackageVersion } = {}) {
+  try {
+    const config = readConfig(harness);
+    const connection = await fetchConnection(config.apiUrl, config.token, harness);
+    const recommended = connection?.recommendedPackageVersion;
+    if (!olderPackageVersion(currentVersion, recommended)) return false;
+    await installVersion(recommended, harness);
+    console.error(`Updated Shifu coding harness to recommended version ${recommended}.`);
+    return true;
+  } catch {
+    console.error("Could not check or install the recommended Shifu package. Continuing with the current runner.");
+    return false;
+  }
+}
+
 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)], {
+      env: { ...process.env, SHIFU_UPDATE_CHECKED: "1" }, stdio: "inherit",
+    });
+    await new Promise((resolve, reject) => {
+      child.once("error", reject);
+      child.once("exit", (code) => code === 0 ? resolve() : reject(new Error("The updated Shifu sync failed; pending work is preserved.")));
+    });
+    return;
+  }
   if (command === "install") return install(harness);
   if (command === "connect") return connect(harness);
   if (command === "disconnect") return disconnect(harness);
@@ -1867,4 +2076,4 @@ if (require.main === module) {
     });
 }
 
-module.exports = { approvalNotificationInvocation, claudeReview, claudeSession, codexReview, codexSession, configPath, configuredSyncPolicy, connect, defaultInputFolder, disconnect, finalAssistantNote, install, installDestination, localSessions, normalizedPolicy, notificationSessionRef, opencodeQuery, opencodeReview, opencodeSessions, payloadForSegment, pendingSegments, prepareInputFolder, profileForSegment, readSecret, removeHooks, requireSafeApiUrl, reviewCandidates, schedulerArtifact, statePath, syncWorkFiles, textIsSafe, unsyncedCodexSessions, validateAIProfileObservation, validateConnection, validateInputFolder, validSyncReceipt, validateApprovalMode, validateIntervalHours, validateSync, workFiles };
+module.exports = { olderPackageVersion, updateRecommendedPackage, installPackageVersion, approvalNotificationInvocation, claudeReview, claudeSession, codexReview, codexSession, configPath, configuredSyncPolicy, connect, defaultInputFolder, disconnect, finalAssistantNote, install, installDestination, localSessions, normalizedPolicy, notificationSessionRef, opencodeQuery, opencodeReview, opencodeSessions, payloadForSegment, pendingSegments, prepareInputFolder, profileForSegment, readSecret, removeHooks, requireSafeApiUrl, reviewCandidates, schedulerArtifact, statePath, syncWorkFiles, textIsSafe, unsyncedCodexSessions, validateAIProfileObservation, validateConnection, validateInputFolder, validSyncReceipt, validateApprovalMode, validateIntervalHours, validateSync, workFiles };

package/commands/shifu-sync.md

@@ -2,6 +2,8 @@
 description: Inspect or sync redacted OpenCode activity using the saved Shifu policy.
 ---
 
+Before sync, the runner installs Shifu's exact `recommendedPackageVersion` only if its current version is older. Equal or newer versions are left alone. Update failures allow sync to continue; do not independently install npm latest.
+
 Run `npx --yes @useshifu/coding-harness status --harness opencode` first.
 
 For an explicit Shifu input-folder sync, run `sync-files --harness opencode`. It polls unfinished jobs before submitting new or changed `.txt`, `.md`, `.rtf`, and `.docx` files up to 20 MB. Upload starts asynchronous server processing; check status on the next manual or scheduled sync. Only a final `processed`, `no_claims`, or `duplicate` result completes the local checkpoint; a `partial` result remains retryable. Completed file checkpoints from the previous runner are replayed once; existing in-flight jobs are polled before replay. Report published claims and needs-evidence suggestions separately. `no_claims` may still include suggestions, which are not verified user contributions. Unsupported files are counted but not uploaded. No claim-review step is needed. Do not treat another speaker's work or a meeting action item as the user's contribution. The server parses and sanitizes files; the local runner does not redact file contents, and file text or excerpts must not appear in logs.
@@ -10,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.
-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, 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.
+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.9",
+  "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

@@ -5,6 +5,8 @@ description: Connect, configure, inspect, or sync coding-harness activity, AI Pr
 
 # Shifu sync
 
+Before manual or scheduled sync, the runner checks Shifu's `recommendedPackageVersion`. It automatically installs that exact release only when the installed version is older; equal or newer versions are left alone. Do not independently install npm latest. If the check or update fails, continue syncing with the current runner. Connection settings, pending work, checkpoints, and the schedule are preserved.
+
 Shifu records useful work completed through the harness. Work may be engineering, product discovery, writing, interview feedback, research, planning, or another user-directed activity. Do not force non-engineering work into engineering categories.
 
 Never include user prompts, raw transcripts, tool output, source code, commands, credentials, URLs, file paths, company or person names, customer details, or proprietary identifiers in a coding-session payload. Synthesize descriptive project labels from their purpose rather than copying a raw name. The local coding runner reads final assistant notes for career activity and scans user turns locally for fixed AI Profile signals; it sends neither raw source. Files placed in the user's chosen Shifu input folder are a separate path: the runner sends supported files over TLS for server-side parsing and sanitization. Do not describe folder files as locally redacted.
@@ -53,18 +55,18 @@ 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.
 
 Use `kind: "activity"` for general harness work; it does not require a technical scope. Use `implementation` or `decision` only when the note clearly supports that engineering classification, and then use the smallest reviewed scope among `unit`, `module`, `service`, `system`, and `product`. Evidence may be empty when the safe final note supports only a session-level title and summary. Never invent impact, ownership, verification, or outcomes.
 
-Make each supported item useful for later recall: retain the user's action, the feature or project purpose, the specific problem, the approach, and a verified result when the final note supports each part. A descriptive project label such as "payment reconciliation service" is useful; synthesize it from the work's purpose instead of copying a raw project label that might contain a company or person's name. Keep distinct contributions separate, including two fixes in one feature that addressed different problems. Omit names of companies and people, customer details, proprietary identifiers, paths, code snippets, and unsupported impact. If a detail cannot be safely described, keep the supported parts. Prefer a summary that names the main distinct work items over a generic count alone.
+Make each supported item useful for later recall: retain the user's action, the feature or project purpose, the specific problem, the approach, and a verified result when the final note supports each part. Preserve supported technologies, design patterns, configuration choices, and measured results; these are useful work details, not identifiers to redact. A descriptive project label such as "payment reconciliation service" is useful; synthesize it from the work's purpose instead of copying a raw project label that might contain a company or person's name. Keep distinct contributions separate, including two fixes in one feature that addressed different problems. Omit names of companies and people, customer details, proprietary identifiers, paths, code snippets, credentials, and unsupported impact. If a detail cannot be safely described, keep the supported parts. Prefer a summary that names the main distinct work items over a generic count alone.
 
 ```json
 {
@@ -94,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.