@useshifu/coding-harness 0.3.36 → 0.3.38

package/bin/shifu-harness.js

@@ -13,6 +13,9 @@ const { normalizeContextPreferences, contextInstructions, contextSkill, CONTEXT_
 const { chooseSetupOptions } = require("./setup-options.js");
 const { createInitialBackfill, initialHistoryEligibility } = require("./initial-history.js");
 const { printWelcome, printSetupIntro, printConnected } = require("./onboarding-ui.js");
+const { deadlineError, requestTimeout } = require("./run-deadline.js");
+const controls = require("./sync-controls.js");
+const { assertNoCredentials } = require("./secret-check.js");
 
 const DEFAULT_API_URL = "https://api.useshifu.com";
 const HARNESS_NAMES = {
@@ -47,10 +50,11 @@ 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.36";
+const RUNNER_VERSION = JSON.parse(fs.readFileSync(path.join(__dirname, path.basename(__filename) === "runner.js" ? "runner-package.json" : "../package.json"), "utf8")).version;
 const REDACTION_VERSION = 5;
 const LEGACY_REDACTION_VERSION = 4;
 const MAX_PREPARATIONS_PER_RUN = 4;
+let remainingNativeRequests;
 const PREPARATION_RUN_MS = 5 * 60_000;
 const DEFAULT_INTERVAL_HOURS = 1;
 const LEGACY_INTERVAL_HOURS = 4;
@@ -66,17 +70,20 @@ const ACTIVE_WORK_FILE_STATUSES = new Set(["queued", "processing", "retrying"]);
 const INPUT_FOLDER_README_NAME = "README.md";
 const INPUT_FOLDER_README = `# Shifu sync folder
 
-Put work logs, meeting transcripts, and other work documents directly in this folder. Shifu checks it every hour by default and keeps claims only when the file supports a contribution you made. Other people's work and meeting action items alone are not your claims.
+Files in this folder are processed only after you review the folder and select Start sync in Shifu setup. File parsing is selected by default for new setups and can be turned off. Once approved, put work logs, meeting transcripts, and other work documents directly here; Shifu checks them on your selected schedule and keeps claims only when the file supports a contribution you made. Other people's work and meeting action items alone are not your claims.
 
 Supported files: .txt, .md, .rtf, and .docx, up to 20 MB each. Subfolders, links, images, and screenshots are not processed. This README is not synced. Unsupported files are counted but never uploaded.
 
 Uploading starts a background job. Shifu checks unfinished jobs before the next scheduled or manual sync; a file is complete only when the server reports its final result. A partial result stays pending for retry. A completed file may have published claims, needs-evidence suggestions, or neither; suggestions are not verified claims.
 
-Files you add are sent to Shifu for parsing and sanitization; they are not redacted on this device. Only place files here if you want them processed. For named meeting transcripts, set your display name in Shifu Profile so your speaker turns can be matched.
+Files you add are sent as provided to your connected Shifu workspace for parsing and sanitization. In Shifu Desktop, parsing runs on your Mac; AI processing may send extracted text through Shifu’s gateway. In the web app, files are uploaded to your hosted workspace. Only place files here if you want them processed. For named meeting transcripts, set your display name in Shifu Profile so your speaker turns can be matched.
 `;
 
 function configRoot() {
-  return process.env.SHIFU_CONFIG_ROOT || path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "shifu", "coding-harness");
+  if (process.env.SHIFU_CONFIG_ROOT) return process.env.SHIFU_CONFIG_ROOT;
+  const installedRoot = path.dirname(__filename);
+  if (path.basename(__filename) === "runner.js" && readDesktopProfile(installedRoot)) return installedRoot;
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "shifu", "coding-harness");
 }
 
 function configPath(harness) {
@@ -204,10 +211,11 @@ function openCodeDatabaseQuery(dbPath, query) {
 function opencodeSessions(rows) {
   const sessions = new Map();
   for (const row of rows) {
-    if (typeof row.sessionRef !== "string" || !Number.isFinite(row.startedAt) || !Number.isFinite(row.updatedAt) || !Number.isFinite(row.turnAt)) continue;
+    if (typeof row.sessionRef !== "string" || !Number.isFinite(row.startedAt) || !Number.isFinite(row.updatedAt)) continue;
     const session = sessions.get(row.sessionRef) || { sessionRef: row.sessionRef, startedAt: new Date(row.startedAt).toISOString(), updatedAt: new Date(row.updatedAt).toISOString(), turnCount: 0, turnTimes: [] };
+    if (typeof row.workspace === "string" && path.isAbsolute(row.workspace)) session.workspace = row.workspace;
     session.turnCount += 1;
-    session.turnTimes.push(new Date(row.turnAt).toISOString());
+    session.turnTimes.push(Number.isFinite(row.turnAt) && Number.isFinite(new Date(row.turnAt).getTime()) ? new Date(row.turnAt).toISOString() : null);
     sessions.set(row.sessionRef, session);
   }
   return [...sessions.values()];
@@ -217,11 +225,48 @@ function cursorOptions() {
   return { journalRoot: path.join(configRoot(), "cursor-capture") };
 }
 
+const sessionMetadataCache = new Map();
+
+function sessionFileIndex(harness) {
+  const configuredRoot = harness === "codex" ? codexSessionsRoot() : claudeSessionsRoot();
+  const root = fs.existsSync(configuredRoot) ? fs.realpathSync(configuredRoot) : path.resolve(configuredRoot);
+  let cache = sessionMetadataCache.get(harness);
+  if (!cache || cache.root !== root) {
+    cache = { root, files: new Map() };
+    sessionMetadataCache.set(harness, cache);
+  }
+  const index = new Map();
+  const currentFiles = new Set();
+  for (const file of sessionFiles(root)) {
+    currentFiles.add(file);
+    const stat = fs.statSync(file, { bigint: true });
+    const signature = `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+    let cached = cache.files.get(file);
+    if (!cached || cached.signature !== signature) {
+      cached = { file, signature, session: harness === "codex" ? codexSession(file) : claudeSession(file) };
+      cache.files.set(file, cached);
+    }
+    if (!cached.session) continue;
+    const previous = index.get(cached.session.sessionRef);
+    if (!previous || cached.session.turnCount > previous.session.turnCount ||
+      (cached.session.turnCount === previous.session.turnCount && cached.session.updatedAt > previous.session.updatedAt)) {
+      index.set(cached.session.sessionRef, cached);
+    }
+  }
+  for (const file of cache.files.keys()) if (!currentFiles.has(file)) cache.files.delete(file);
+  return index;
+}
+
 function localSessions(harness) {
   if (harness === "cursor") return require("./cursor-sessions.js").localSessions(cursorOptions());
-  if (harness === "codex") return sessionFiles(codexSessionsRoot()).map(codexSession).filter(Boolean);
-  if (harness === "claude_code") return sessionFiles(claudeSessionsRoot()).map(claudeSession).filter(Boolean);
-  if (harness === "opencode") return opencodeSessions(opencodeQuery("SELECT s.id AS sessionRef, s.time_created AS startedAt, s.time_updated AS updatedAt, m.time_created AS turnAt FROM session s JOIN message m ON m.session_id = s.id WHERE json_extract(m.data, '$.role') = 'user' ORDER BY s.time_updated, m.time_created"));
+  if (harness === "codex" || harness === "claude_code") return [...sessionFileIndex(harness).values()].map(({ session }) => session);
+  if (harness === "opencode") {
+    const query = "SELECT s.id AS sessionRef, s.time_created AS startedAt, s.time_updated AS updatedAt, m.time_created AS turnAt FROM session s JOIN message m ON m.session_id = s.id WHERE json_extract(m.data, '$.role') = 'user' ORDER BY s.time_updated, m.time_created";
+    let rows;
+    try { rows = opencodeQuery(query.replace("SELECT s.id", "SELECT s.directory AS workspace, s.id")); }
+    catch { rows = opencodeQuery(query); }
+    return opencodeSessions(rows);
+  }
   throw new Error("Choose a supported coding harness.");
 }
 
@@ -251,21 +296,25 @@ function validateSyncOptions(command, start = 3) {
     "sync-files": common,
     "scheduled-sync": common,
     pending: common,
+    prepare: [...common, "--session-ref", "--from-turn", "--to-turn"],
+    recover: [...common, "--selection"],
     "retry-preparation": [...common, "--session-ref", "--from-turn"],
     approve: common,
     install: common,
     connect: [...common, ...setup, ...syncSettings, "--api-url"],
-    "config-update": [...common, ...setup, ...syncSettings],
+    "config-update": [...common, ...setup, ...syncSettings, "--background-reasoning", "--exclude-session", "--include-session"],
     "mcp-setup": [...common, ...setup, "--mcp-url", "--api-url"],
-    onboard: [...common, "--run", "--api-url"],
+    onboard: [...common, "--run", "--api-url", "--mcp-url"],
+    pause: common, resume: common, "purge-local": common,
     "mcp-headers": common,
     "mcp-bridge": common,
     "cursor-hook": common,
   };
   const flags = {
     onboard: ["--status", "--worker", "--serve", "--helpful", "--new", "--abandon"],
+    "purge-local": ["--approved"],
     connect: ["--interactive", "--non-interactive"], "mcp-setup": ["--interactive", "--non-interactive"], "config-update": ["--interactive", "--non-interactive"],
-    sessions: ["--all", "--force", "--initial-history"], review: ["--all", "--force"], sync: ["--approved", "--force"], approve: ["--approved"],
+    sessions: ["--all", "--force", "--initial-history"], review: ["--all", "--force"], prepare: ["--all"], "retry-preparation": ["--all"], sync: ["--approved", "--force"], approve: ["--approved"],
   };
   if (!options[command]) return;
   const seen = new Set();
@@ -389,6 +438,134 @@ function readState(harness) {
   return readJSON(statePath(harness), { sessions: {} });
 }
 
+function currentProcessingConfig(harness, expected, selection = {}) {
+  const config = readConfig(harness);
+  if (controls.connectionFingerprint(config) !== controls.connectionFingerprint(expected) ||
+      (config.syncGeneration || 0) !== (expected.syncGeneration || 0) || JSON.stringify(config.syncAuthorization) !== JSON.stringify(expected.syncAuthorization)) throw controls.processingError("SHIFU_SCOPE_REQUIRED");
+  const current = controls.captureConfig(config);
+  if (selection.sessionRef) {
+    const session = localSessions(harness).find((item) => item.sessionRef === selection.sessionRef);
+    if ((selection.force || selection.supersedesSyncId) && (!session || selection.toTurn > session.turnCount)) throw new Error("The original local turns must still exist before force syncing this range.");
+    if (!session || normalizedPolicy(config).excludedSessionRefs.includes(selection.sessionRef) || !controls.sessionAllowed(config, session)) throw controls.processingError("SHIFU_SCOPE_REQUIRED");
+    if (selection.fromTurn) {
+      const through = selection.toTurn || selection.fromTurn;
+      if (!Number.isSafeInteger(through) || through < selection.fromTurn || through - selection.fromTurn >= MAX_TURNS_PER_SEGMENT) throw controls.processingError("SHIFU_SCOPE_REQUIRED");
+      for (let turn = selection.fromTurn; turn <= through; turn++) {
+        if (!initialHistoryEligibility(session, turn, current).eligible) throw controls.processingError("SHIFU_SCOPE_REQUIRED");
+      }
+    }
+  }
+  if (selection.folder && !controls.filesAllowed(config, selection.folder)) throw controls.processingError("SHIFU_SCOPE_REQUIRED");
+  return current;
+}
+
+function processingLease(harness, config, selection) {
+  currentProcessingConfig(harness, config, selection);
+  const controller = new AbortController();
+  const interval = setInterval(() => {
+    try { currentProcessingConfig(harness, config, selection?.folder ? selection : {}); }
+    catch (error) { controller.abort(error); }
+  }, 250);
+  interval.unref();
+  return { signal: controller.signal, close: () => clearInterval(interval) };
+}
+
+function requestSignal(timeoutMs, signal) {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  if (!signal) return timeout;
+  const controller = new AbortController();
+  for (const source of [signal, timeout]) {
+    if (source.aborted) controller.abort(source.reason);
+    else source.addEventListener("abort", () => controller.abort(source.reason), { once: true });
+  }
+  return controller.signal;
+}
+
+async function processingFetch(harness, config, selection, url, options) {
+  const lease = processingLease(harness, config, selection);
+  const controller = new AbortController();
+  const abort = () => controller.abort(lease.signal.reason || options.signal?.reason);
+  lease.signal.addEventListener("abort", abort, { once: true });
+  options.signal?.addEventListener("abort", abort, { once: true });
+  if (options.signal?.aborted) abort();
+  try { return await fetch(url, { ...options, redirect: "error", signal: controller.signal }); }
+  finally {
+    lease.close();
+    lease.signal.removeEventListener("abort", abort);
+    options.signal?.removeEventListener("abort", abort);
+  }
+}
+
+function updateSavedConfig(harness, change) {
+  fs.mkdirSync(configRoot(), { recursive: true, mode: 0o700 });
+  const file = lockPath(`${harness}-settings`);
+  let descriptor;
+  for (let attempt = 0; attempt < 100 && descriptor === undefined; attempt++) {
+    try { descriptor = fs.openSync(file, "wx", 0o600); }
+    catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      recoverSyncLock(file, 1_000);
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  }
+  if (descriptor === undefined) throw new Error("Shifu settings are being updated. Retry this action.");
+  try {
+    fs.writeFileSync(descriptor, `${process.pid}\n`);
+    const next = change(readJSON(configPath(harness), null));
+    if (next !== undefined) writeJSON(configPath(harness), next);
+    return next;
+  } finally { releaseOwnedLock(file, descriptor); }
+}
+
+function setSyncPaused(harness, paused) {
+  const config = updateSavedConfig(harness, (current) => {
+    if (!current) throw new Error("No saved Shifu connection was found.");
+    if (!paused) controls.captureConfig({ ...current, syncPaused: false });
+    return { ...current, syncPaused: paused, syncGeneration: (current.syncGeneration || 0) + 1 };
+  });
+  if (paused) stopLegacyWorker(harness);
+  if (!paused) scheduleNextRun(harness, 0);
+  console.error(paused ? "All Shifu capture is paused. Accepted work and pending ranges are preserved." : "Shifu capture resumed within the approved scope.");
+  return config;
+}
+
+function stopLegacyWorker(harness) {
+  const file = lockPath(harness);
+  if (!fs.existsSync(file)) return;
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.size > 64) return;
+  const owner = fs.readFileSync(file, "utf8").trim();
+  if (!/^[1-9]\d{0,9}$/.test(owner) || Number(owner) === process.pid) return;
+  const active = readJSON(path.join(configRoot(), `${harness}-active-run.json`), null);
+  if (active?.pid === Number(owner) && active.lockInode === stat.ino) return;
+  let command;
+  try { command = execFileSync("ps", ["-p", owner, "-o", "command="], { encoding: "utf8", timeout: 1_000, stdio: ["ignore", "pipe", "ignore"] }); }
+  catch { return; }
+  const paths = [installedRunnerPath(), __filename].flatMap((value) => [value, fs.existsSync(value) ? fs.realpathSync(value) : value]);
+  const executable = command.trimStart().match(/^(?:\S*\/)?node(?:js)?[ \t]+/)?.[0];
+  if (!executable) return;
+  const invocation = command.trimStart().slice(executable.length);
+  if (!paths.some((value) => invocation.startsWith(`${value} `)) || !new RegExp(`--harness\\s+${harness}(?:\\s|$)`).test(invocation)) return;
+  try { process.kill(Number(owner), "SIGTERM"); }
+  catch (error) { if (error.code !== "ESRCH") throw new Error("Capture is paused, but an older worker could not be stopped. Stop that Shifu worker before continuing."); }
+}
+
+function purgeLocal(harness) {
+  const config = readJSON(configPath(harness), null);
+  if (config && config.syncPaused !== true) throw new Error("Pause Shifu capture before clearing its local preparation data.");
+  recoverSyncLock(lockPath(harness));
+  if (fs.existsSync(lockPath(harness))) throw new Error("A sync is still finishing. Retry the local purge after it stops.");
+  const names = [`${harness}-continuity.json`, `${harness}-entity-dictionary.json`, `${harness}-recovery.json`, `${harness}-onboarding.json`, `${harness}-wizard.json`, `${harness}-pending.json`];
+  if (harness === "cursor") names.push("cursor-capture");
+  const selected = fs.readdirSync(configRoot()).filter((name) => names.some((base) => name === base || (name.startsWith(`${base}.quarantined.`) && /^[a-f0-9-]+$/i.test(name.slice(base.length + 13)))));
+  if (!hasFlag("--approved")) {
+    console.log(JSON.stringify({ harness, artifacts: selected, confirmationRequired: true, preserves: ["connection", "accepted checkpoints", "coding tool history", "user documents", "saved Shifu work"] }));
+    return;
+  }
+  for (const name of selected) fs.rmSync(path.join(configRoot(), name), { recursive: true, force: true });
+  console.log(JSON.stringify({ harness, removedArtifacts: selected.length, paused: true }));
+}
+
 function defaultInputFolder(home = os.homedir()) {
   return path.join(home, "Desktop", "Shifu");
 }
@@ -464,6 +641,7 @@ function codexSession(file) {
   let startedAt;
   let updatedAt;
   let turnCount = 0;
+  let workspace;
   const turnTimes = [];
   for (const line of lines) {
     let entry;
@@ -474,6 +652,7 @@ function codexSession(file) {
     }
     if (entry.type === "session_meta") {
       sessionRef = entry.payload?.id || entry.payload?.session_id;
+      if (typeof entry.payload?.cwd === "string" && path.isAbsolute(entry.payload.cwd)) workspace = entry.payload.cwd;
       startedAt ||= entry.timestamp;
     }
     if (entry.type === "response_item" && entry.payload?.type === "message" && entry.payload?.role === "user") {
@@ -483,7 +662,7 @@ function codexSession(file) {
     if (typeof entry.timestamp === "string") updatedAt = entry.timestamp;
   }
   if (typeof sessionRef !== "string" || sessionRef.length < 8 || !updatedAt || turnCount === 0) return undefined;
-  return { sessionRef, startedAt: startedAt || updatedAt, updatedAt, turnCount, turnTimes };
+  return { sessionRef, startedAt: startedAt || updatedAt, updatedAt, turnCount, turnTimes, ...(workspace ? { workspace } : {}) };
 }
 
 function claudeEntries(file) {
@@ -504,14 +683,17 @@ function claudeSession(file) {
   if (!OPAQUE_SESSION_REF_PATTERN.test(sessionRef)) return undefined;
   let startedAt;
   let updatedAt;
+  let workspace;
   const turnTimes = [];
   for (const entry of claudeEntries(file)) {
-    if (typeof entry.timestamp !== "string" || !Number.isFinite(Date.parse(entry.timestamp))) continue;
+    if (typeof entry.cwd === "string" && path.isAbsolute(entry.cwd)) workspace ||= entry.cwd;
+    const timestampValid = typeof entry.timestamp === "string" && Number.isFinite(Date.parse(entry.timestamp));
+    if (isClaudeUserTurn(entry)) turnTimes.push(timestampValid ? entry.timestamp : null);
+    if (!timestampValid) continue;
     startedAt ||= entry.timestamp;
     updatedAt = entry.timestamp;
-    if (isClaudeUserTurn(entry)) turnTimes.push(entry.timestamp);
   }
-  return updatedAt && turnTimes.length ? { sessionRef, startedAt, updatedAt, turnCount: turnTimes.length, turnTimes } : undefined;
+  return updatedAt && turnTimes.length ? { sessionRef, startedAt, updatedAt, turnCount: turnTimes.length, turnTimes, ...(workspace ? { workspace } : {}) } : undefined;
 }
 
 function claudeReview(file, fromTurn, toTurn) {
@@ -654,19 +836,29 @@ function sourceRecords(harness, sessionRef) {
     return opencodeQuery(`SELECT m.id AS messageId, m.time_created AS createdAt, json_extract(m.data, '$.role') AS role, json_extract(m.data, '$.finish') AS finish, json_extract(m.data, '$.error') AS error, json_extract(m.data, '$.storageVersion') AS storageVersion, p.data AS part FROM message m LEFT JOIN part p ON p.message_id = m.id WHERE m.session_id = ${JSON.stringify(sessionRef)} ORDER BY m.time_created, p.id`);
   }
   const file = sessionFile(harness, sessionRef);
+  return readSessionRecords(file);
+}
+
+function readSessionRecords(file) {
   try { return fs.readFileSync(file, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line)); }
   catch { throw new Error("Could not read selected original messages locally. Nothing was reconstructed or synced."); }
 }
 
 function sessionFile(harness, sessionRef) {
-  const files = harness === "codex" ? sessionFiles(codexSessionsRoot()) : sessionFiles(claudeSessionsRoot());
-  const selectedFile = files.map((file) => ({ file, session: harness === "codex" ? codexSession(file) : claudeSession(file) }))
-    .filter(({ session }) => session?.sessionRef === sessionRef)
-    .sort((left, right) => right.session.turnCount - left.session.turnCount || right.session.updatedAt.localeCompare(left.session.updatedAt))[0]?.file;
+  const selectedFile = sessionFileIndex(harness).get(sessionRef)?.file;
   if (!selectedFile) throw new Error(`No local ${HARNESS_NAMES[harness]} session matches ${sessionRef}.`);
   return selectedFile;
 }
 
+function completedSessionTurn(harness, sessionRef, fileIndex) {
+  const adapter = require("./source-review.js");
+  if (harness !== "codex" && harness !== "claude_code") return adapter.completedSourceTurn({ harness }, sourceRecords(harness, sessionRef));
+  const cached = (fileIndex || sessionFileIndex(harness)).get(sessionRef);
+  if (!cached) throw new Error(`No local ${HARNESS_NAMES[harness]} session matches ${sessionRef}.`);
+  if (cached.completedTo === undefined) cached.completedTo = adapter.completedSourceTurn({ harness }, readSessionRecords(cached.file));
+  return cached.completedTo;
+}
+
 function reviewCandidates(notes) {
   const candidates = [];
   const seen = new Set();
@@ -1231,16 +1423,20 @@ function unsyncedCodexSessions(harness, options = {}) {
 }
 
 function pendingSegments(harness, state = readState(harness)) {
-  const config = readConfig(harness);
+  const saved = readConfig(harness);
+  if (!controls.validAuthorization(saved) || saved.syncPaused) return [];
+  const config = controls.captureConfig(saved);
   const policy = normalizedPolicy(config);
   const excluded = new Set(policy.excludedSessionRefs);
   const segments = [];
-  for (const session of localSessions(harness)
-    .filter((candidate) => !excluded.has(candidate.sessionRef))
+  const fileIndex = harness === "codex" || harness === "claude_code" ? sessionFileIndex(harness) : undefined;
+  const sessions = fileIndex ? [...fileIndex.values()].map(({ session }) => session) : localSessions(harness);
+  for (const session of sessions
+    .filter((candidate) => !excluded.has(candidate.sessionRef) && controls.sessionAllowed(config, candidate))
     .sort((left, right) => String(left.updatedAt || "").localeCompare(String(right.updatedAt || "")))) {
     let fromTurn = (state.sessions[session.sessionRef]?.lastSyncedTurn || 0) + 1;
     if (fromTurn > session.turnCount || !initialHistoryEligibility(session, fromTurn, config).eligible) continue;
-    const completedTo = require("./source-review.js").completedSourceTurn({ harness }, sourceRecords(harness, session.sessionRef));
+    const completedTo = completedSessionTurn(harness, session.sessionRef, fileIndex);
     while (fromTurn <= completedTo) {
       const toTurn = Math.min(completedTo, fromTurn + MAX_TURNS_PER_SEGMENT - 1);
       segments.push({ ...session, fromTurn, toTurn });
@@ -1292,12 +1488,13 @@ function sameFile(source, destination) {
 
 function copyRunner() {
   fs.mkdirSync(configRoot(), { recursive: true, mode: 0o700 });
+  writeJSON(path.join(configRoot(), "runner-package.json"), { version: RUNNER_VERSION });
   for (const name of ["jsonc-parser", "smol-toml"]) {
     const dependency = name === "smol-toml" ? path.dirname(path.dirname(require.resolve(name))) : path.dirname(require.resolve(`${name}/package.json`));
     const installedDependency = path.join(configRoot(), "node_modules", name);
     if (!sameFile(dependency, installedDependency)) copyDirectory(dependency, installedDependency);
   }
-  for (const name of ["source-review.js", "v5-payload.js", "native-preparation.js", "opencode-v2-account.js", "context-preferences.js", "setup-options.js", "initial-history.js", "onboarding-ui.js", "onboarding.js", "continuity-preparation.js", "continuity-state.js", "cursor-config.js", "cursor-mcp.js", "cursor-sessions.js", "cursor-native.js"]) {
+  for (const name of ["source-review.js", "v5-payload.js", "native-preparation.js", "opencode-v2-account.js", "context-preferences.js", "setup-options.js", "initial-history.js", "onboarding-ui.js", "onboarding.js", "continuity-preparation.js", "continuity-state.js", "recovery-state.js", "run-deadline.js", "sync-controls.js", "secret-check.js", "cursor-config.js", "cursor-mcp.js", "cursor-sessions.js", "cursor-native.js"]) {
     const source = path.join(__dirname, name);
     const destination = path.join(configRoot(), name);
     if (!sameFile(source, destination)) {
@@ -1429,13 +1626,37 @@ function xml(value) {
   return String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 }
 
+function readDesktopProfile(directory) {
+  let marker;
+  try {
+    marker = fs.readFileSync(path.join(directory, "desktop-profile.json"), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return undefined;
+    throw error;
+  }
+  let profile;
+  try { profile = JSON.parse(marker); }
+  catch { throw new Error("The desktop profile is invalid. Reopen the desktop app before changing its schedule."); }
+  if (profile?.version !== 1 || typeof profile.namespace !== "string" || !/^desktop-[a-f0-9]{12}$/.test(profile.namespace)) {
+    throw new Error("The desktop profile is invalid. Reopen the desktop app before changing its schedule.");
+  }
+  return profile;
+}
+
+function macSchedulerLabel(harness) {
+  const label = `com.useshifu.coding-harness.${harness}`;
+  const profile = readDesktopProfile(configRoot());
+  return profile ? `${label}.${profile.namespace}` : label;
+}
+
 function schedulerArtifact(harness, platform = process.platform) {
   const runner = installedRunnerPath();
-  const label = `com.useshifu.coding-harness.${harness}`;
   if (platform === "darwin") {
+    const label = macSchedulerLabel(harness);
     const file = path.join(os.homedir(), "Library", "LaunchAgents", `${label}.plist`);
     return {
       file,
+      label,
       content: `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key><string>${label}</string>\n<key>ProgramArguments</key><array><string>${xml(process.execPath)}</string><string>${xml(runner)}</string><string>scheduled-sync</string><string>--harness</string><string>${harness}</string><string>--config-root</string><string>${xml(configRoot())}</string></array>\n<key>StartInterval</key><integer>${SCHEDULER_TICK_MINUTES * 60}</integer>\n<key>ProcessType</key><string>Background</string>\n<key>StandardOutPath</key><string>/dev/null</string>\n<key>StandardErrorPath</key><string>/dev/null</string>\n</dict></plist>\n`,
       activate() {
         const domain = `gui/${process.getuid()}`;
@@ -1495,7 +1716,7 @@ function removeSchedule(harness) {
   if (process.env.SHIFU_SKIP_SCHEDULER_ACTIVATION !== "1") {
     if (process.platform === "darwin") {
       const domain = `gui/${process.getuid()}`;
-      const label = `com.useshifu.coding-harness.${harness}`;
+      const label = artifact.label;
       const scheduleIsLoaded = () => {
         let listing;
         try { listing = execFileSync("launchctl", ["list"], { encoding: "utf8" }); }
@@ -1544,7 +1765,7 @@ async function chooseSyncPolicy(existing) {
   };
 }
 
-async function onboardingOptions(config, allowQuestions = true) {
+async function onboardingOptions(config, allowQuestions = true, includeHistory = true) {
   if (hasFlag("--interactive") && hasFlag("--non-interactive")) throw new Error("Choose interactive or non-interactive setup, not both.");
   if (hasFlag("--interactive") && !process.stdin.isTTY) throw new Error("Interactive setup needs a terminal. Use --backfill-days, --growth-feedback and --decision-alignment from your assistant instead.");
   const interactive = allowQuestions && process.stdin.isTTY && !hasFlag("--non-interactive");
@@ -1556,25 +1777,28 @@ async function onboardingOptions(config, allowQuestions = true) {
       terminal.once("close", closed);
       terminal.question(question).then(resolve, reject).finally(() => terminal.removeListener("close", closed));
     }));
-    return await chooseSetupOptions(config, { option, ask });
+    return await chooseSetupOptions(config, { option, ask, includeHistory });
   } finally {
     terminal?.close();
   }
 }
 
-async function validateConnection(apiUrl, token, harness) {
+async function validateConnection(apiUrl, token, harness, deadlineAt = Infinity) {
+  const timeoutMs = requestTimeout(deadlineAt, 10_000);
   let response;
   try {
     response = await fetch(`${apiUrl}/v1/connectors/coding-sessions/connection?harness=${encodeURIComponent(harness)}`, {
       headers: { Authorization: `Bearer ${token}` },
-      signal: AbortSignal.timeout(10_000),
+      signal: AbortSignal.timeout(timeoutMs),
     });
   } catch {
+    if (Date.now() >= deadlineAt) throw deadlineError();
     throw new Error("Could not reach Shifu to verify the connection key. Nothing was changed.");
   }
   if (response.status === 401 || response.status === 422) throw new Error("Shifu rejected this connection key for the selected coding tool. Nothing was changed.");
   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 === null && Date.now() >= deadlineAt) throw deadlineError();
   if (result?.data?.connected !== true) throw new Error("Shifu returned an invalid connection check. Nothing was changed.");
   return result.data;
 }
@@ -1595,7 +1819,8 @@ async function connect(harness, readKey = readSecret, choices, deferSchedule = f
   const selected = await chooseSyncPolicy(currentPolicy);
   const schedule = option("--schedule");
   if (schedule !== undefined && schedule !== "on" && schedule !== "off") throw new Error("Choose on or off for the sync schedule.");
-  const scheduleEnabled = !deferSchedule && (schedule === undefined ? (savedPolicy?.onboardingComplete ? savedPolicy.scheduleEnabled : true) : schedule === "on");
+  if (schedule === "on" && !controls.validAuthorization(existing)) throw controls.processingError("SHIFU_SCOPE_REQUIRED");
+  const scheduleEnabled = !deferSchedule && Boolean(controls.validAuthorization(existing)) && (schedule === undefined ? savedPolicy?.scheduleEnabled === true : schedule === "on");
   const syncPolicy = configuredSyncPolicy(existing || {}, harness, selected.intervalHours, selected.approvalMode, scheduleEnabled);
   const inputFolder = configuredInputFolder(existing);
   const conflicts = prepareInputFolder(inputFolder, inputFolder === defaultInputFolder());
@@ -1603,9 +1828,14 @@ async function connect(harness, readKey = readSecret, choices, deferSchedule = f
   const scheduleFile = scheduleEnabled ? installSchedule(harness) : undefined;
   if (!scheduleEnabled && savedPolicy?.scheduleEnabled) removeSchedule(harness);
   const connection = { ...existing, ...choices, onboardingSchedulePending: deferSchedule || undefined, version: CONFIG_VERSION, apiUrl, token, harness, syncPolicy, inputFolder, capabilities: connectionInfo.capabilities || {} };
+  if (schedule === "off" || (existing && selected.approvalMode !== currentPolicy.approvalMode)) connection.syncGeneration = (existing?.syncGeneration || 0) + 1;
+  if (schedule === "off") connection.syncPaused = true;
   const committed = await withSyncLock(harness, async () => {
     if (JSON.stringify(readJSON(configPath(harness), undefined)) !== JSON.stringify(existing)) throw new Error("The connection changed during setup. Run connect again.");
-    require("./continuity-state.js").commitConnection(configRoot(), harness, existing, connection);
+    updateSavedConfig(harness, (current) => {
+      if (JSON.stringify(current) !== JSON.stringify(existing || null)) throw new Error("The connection changed during setup. Run connect again.");
+      require("./continuity-state.js").commitConnection(configRoot(), harness, existing, connection);
+    });
     refreshManagedContextInstructions(harness, choices.contextPreferences);
     if (refreshContextKey) writePrivateText(openCodeTokenPath(), token);
     const continuity = continuityState(harness, connection);
@@ -1613,6 +1843,7 @@ async function connect(harness, readKey = readSecret, choices, deferSchedule = f
     scheduleNextRun(harness, syncPolicy.intervalHours);
   });
   if (committed?.skipped) throw new Error("Another Shifu sync is running. Retry connect after it finishes; the connection was not replaced.");
+  if (schedule === "off") stopLegacyWorker(harness);
   console.error(`${HARNESS_NAMES[harness]} is connected. ${scheduleEnabled ? `It will sync every ${syncPolicy.intervalHours} hours with ${syncPolicy.approvalMode} approval.` : "The sync schedule is off."}`);
   console.error(`Shifu sync folder: ${inputFolder}. Place .txt, .md, .rtf, or .docx files there. Only grounded contributions will become claims.`);
   if (conflicts.length) console.error(`Existing Shifu shortcut(s) were left unchanged: ${conflicts.join(", ")}.`);
@@ -2054,7 +2285,7 @@ async function setupMcp(harness) {
     throw new Error(`The saved ${HARNESS_NAMES[harness]} connection must be a regular private file, not a link.`);
   }
   printSetupIntro();
-  const choices = await onboardingOptions(readJSON(configPath(harness), undefined));
+  const choices = await onboardingOptions(readJSON(configPath(harness), undefined), true, false);
   const instructions = prepareContextInstructions(harness, choices.contextPreferences);
   const helper = ["opencode", "cursor"].includes(harness) ? undefined : helperCommand(harness);
   if (fs.existsSync(configPath(harness)) && !fs.lstatSync(configPath(harness)).isFile()) {
@@ -2062,7 +2293,7 @@ async function setupMcp(harness) {
   }
   let config = readJSON(configPath(harness), undefined);
   if (!config) {
-    await connect(harness, readSecret, choices);
+    await connect(harness, readSecret, choices, true);
     config = readConfig(harness);
   }
   const originalConnection = fs.readFileSync(configPath(harness), "utf8");
@@ -2089,7 +2320,10 @@ async function setupMcp(harness) {
   if (!unchangedContextInstructions(instructions)) throw new Error("The global instructions changed during setup. Run mcp-setup again to preserve those changes.");
   if (harness === "opencode") writePrivateText(openCodeTokenPath(), config.token);
   writePrivateText(prepared.file, prepared.candidate);
-  writeJSON(configPath(harness), { ...config, ...choices, mcpUrl, ...(harness === "opencode" ? { mcpConfigMajor: prepared.openCodeMajor } : {}), ...(harness === "claude_code" ? { mcpHeadersHelper: helper } : {}) });
+  updateSavedConfig(harness, (current) => {
+    if (JSON.stringify(current) !== JSON.stringify(config)) throw new Error("The saved Shifu connection changed during setup. Run mcp-setup again to preserve those changes.");
+    return { ...current, ...choices, mcpUrl, ...(harness === "opencode" ? { mcpConfigMajor: prepared.openCodeMajor } : {}), ...(harness === "claude_code" ? { mcpHeadersHelper: helper } : {}) };
+  });
   writeContextInstructions(instructions);
   console.error(`Verified Shifu MCP tools: ${tools.join(", ")}. ${HARNESS_NAMES[harness]} configuration and usage instructions are installed.`);
   console.error(`The existing connection key is read ${harness === "opencode" ? "from a private credential file" : "by a local credential helper"}; it was not copied into MCP configuration. The sync endpoint and schedule were preserved.`);
@@ -2117,36 +2351,70 @@ function disconnect(harness) {
 
 async function updateConfig(harness) {
   const config = readConfig(harness);
+  const excludedSession = option("--exclude-session");
+  const includedSession = option("--include-session");
+  if ((excludedSession !== undefined || includedSession !== undefined) &&
+      ((excludedSession !== undefined && includedSession !== undefined) || !sessionRefIsSafe(excludedSession || includedSession))) {
+    throw new Error("Choose one opaque session reference to exclude or include.");
+  }
+  const originalConfig = JSON.stringify(config);
+  const backgroundReasoning = option("--background-reasoning");
+  if (backgroundReasoning !== undefined && (harness !== "codex" || !["medium", "high", "inherit"].includes(backgroundReasoning))) {
+    throw new Error("Codex background reasoning must be medium, high or inherit. Chat reasoning stays unchanged.");
+  }
   const choices = await onboardingOptions(config, hasFlag("--interactive"));
   const instructions = config.mcpUrl ? prepareContextInstructions(harness, choices.contextPreferences) : undefined;
-  const syncOptions = ["--interval-hours", "--approval-mode", "--schedule", "--input-folder"];
-  const preferencesOnly = (hasFlag("--interactive") || ["--growth-feedback", "--decision-alignment", "--backfill-days"].some((name) => option(name) !== undefined)) && !syncOptions.some((name) => option(name) !== undefined);
+  const syncOptions = ["--interval-hours", "--approval-mode", "--schedule", "--input-folder", "--exclude-session", "--include-session"];
+  const preferencesOnly = (hasFlag("--interactive") || ["--growth-feedback", "--decision-alignment", "--backfill-days", "--background-reasoning"].some((name) => option(name) !== undefined)) && !syncOptions.some((name) => option(name) !== undefined);
   if (!preferencesOnly) {
     const savedPolicy = normalizedPolicy(config);
     const selected = await chooseSyncPolicy(savedPolicy.onboardingComplete ? savedPolicy : { intervalHours: DEFAULT_INTERVAL_HOURS, approvalMode: "automatic" });
     const schedule = option("--schedule");
     if (schedule !== undefined && schedule !== "on" && schedule !== "off") throw new Error("Choose on or off for the sync schedule.");
-    const scheduleEnabled = schedule === undefined ? (savedPolicy.onboardingComplete ? savedPolicy.scheduleEnabled : true) : schedule === "on";
+    if (schedule === "on" && !controls.validAuthorization(config)) throw controls.processingError("SHIFU_SCOPE_REQUIRED");
+    const scheduleEnabled = Boolean(controls.validAuthorization(config)) && (schedule === undefined ? savedPolicy.scheduleEnabled : schedule === "on");
     const inputFolder = configuredInputFolder(config);
     const conflicts = prepareInputFolder(inputFolder, inputFolder === defaultInputFolder());
     config.version = CONFIG_VERSION;
     config.syncPolicy = configuredSyncPolicy(config, harness, selected.intervalHours, selected.approvalMode, scheduleEnabled);
+    if (selected.approvalMode !== savedPolicy.approvalMode) config.syncGeneration = (config.syncGeneration || 0) + 1;
+    if (config.inputFolder !== inputFolder && config.syncAuthorization) {
+      config.syncAuthorization = { ...config.syncAuthorization, filesEnabled: false, inputFolder: null };
+      config.syncGeneration = (config.syncGeneration || 0) + 1;
+    }
     config.inputFolder = inputFolder;
     if (scheduleEnabled) installSchedule(harness);
     else if (savedPolicy.scheduleEnabled) removeSchedule(harness);
     scheduleNextRun(harness, config.syncPolicy.intervalHours);
     if (conflicts.length) console.error(`Existing Shifu shortcut(s) were left unchanged: ${conflicts.join(", ")}.`);
   }
-  if (option("--schedule") !== undefined) delete config.onboardingSchedulePending;
+  if (excludedSession !== undefined || includedSession !== undefined) {
+    const excluded = new Set(normalizedPolicy(config).excludedSessionRefs);
+    if (excludedSession) excluded.add(excludedSession); else excluded.delete(includedSession);
+    config.syncPolicy.excludedSessionRefs = [...excluded];
+    config.syncGeneration = (config.syncGeneration || 0) + 1;
+  }
+  if (option("--schedule") !== undefined) {
+    delete config.onboardingSchedulePending;
+    config.syncPaused = option("--schedule") === "off";
+    config.syncGeneration = (config.syncGeneration || 0) + 1;
+  }
   Object.assign(config, choices);
+  if (backgroundReasoning === "inherit") delete config.backgroundReasoning;
+  else if (backgroundReasoning !== undefined) config.backgroundReasoning = backgroundReasoning;
   install(harness, true, choices.contextPreferences);
-  writeJSON(configPath(harness), config);
+  updateSavedConfig(harness, (current) => {
+    if (JSON.stringify(current) !== originalConfig) throw new Error("Shifu settings changed while this update was running. Your latest settings were preserved; retry the update.");
+    return config;
+  });
+  if (config.syncPaused) stopLegacyWorker(harness);
   if (instructions) writeContextInstructions(instructions);
   else refreshManagedContextInstructions(harness, choices.contextPreferences);
   console.error(`Shifu preferences saved for ${HARNESS_NAMES[harness]}. Historical context remains on after MCP setup.`);
   console.error(`Growth feedback: ${choices.contextPreferences.growthFeedback ? "On" : "Off"}. Decision alignment: ${choices.contextPreferences.decisionAlignment ? "On" : "Off"}.`);
   const policy = normalizedPolicy(config);
   console.error(`Work-summary sync: ${policy.scheduleEnabled ? `every ${policy.intervalHours} hours with ${policy.approvalMode} approval` : "schedule off"}.`);
+  if (harness === "codex") console.error(`Background extraction reasoning: ${config.backgroundReasoning || "inherit"}. Codex chat settings are unchanged.`);
   if (config.mcpUrl) console.error(`Reload ${HARNESS_NAMES[harness]} or start a new chat to load the updated preferences.`);
 }
 
@@ -2259,62 +2527,75 @@ function retryDelay(response, attempt) {
   return Math.min(base * (2 ** attempt), 30_000);
 }
 
-async function postSync(config, input, beforeAttempt, onPermanentFailure) {
+async function postSync(config, input, beforeAttempt, onPermanentFailure, deadlineAt = Infinity, signal) {
+  assertNoCredentials(input);
   const body = JSON.stringify(input.force ? { ...input, forceRequestId: randomUUID() } : input);
   let lastError;
   for (let attempt = 0; attempt < MAX_RETRIES; attempt += 1) {
+    requestTimeout(deadlineAt);
     beforeAttempt?.();
+    const timeoutMs = requestTimeout(deadlineAt);
     let response;
     try {
       response = await fetch(`${config.apiUrl}/v1/connectors/coding-sessions/syncs`, {
+        redirect: "error",
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${config.token}` },
         body,
-        signal: AbortSignal.timeout(30_000),
+        signal: requestSignal(timeoutMs, signal),
       });
     } catch (error) {
+      if (signal?.aborted) throw signal.reason;
+      if (Date.now() >= deadlineAt) throw deadlineError();
       lastError = new Error(`Could not reach Shifu at ${config.apiUrl}: ${error?.cause?.code || error?.message || "unknown transport error"}.`);
-      if (attempt + 1 < MAX_RETRIES) await sleep(retryDelay(undefined, attempt));
+      if (attempt + 1 < MAX_RETRIES) await sleep(requestTimeout(deadlineAt, retryDelay(undefined, attempt)));
       continue;
     }
     const payload = await response.json().catch(() => undefined);
+    if (payload === undefined && Date.now() >= deadlineAt) throw deadlineError();
     if (response.ok) return payload?.data;
     lastError = new Error(payload?.error?.message || `Shifu rejected the sync (${response.status}).`);
     if (response.status !== 429 && response.status < 500) { onPermanentFailure?.(); throw lastError; }
-    if (attempt + 1 < MAX_RETRIES) await sleep(retryDelay(response, attempt));
+    if (attempt + 1 < MAX_RETRIES) await sleep(requestTimeout(deadlineAt, retryDelay(response, attempt)));
   }
   throw lastError;
 }
 
-async function flushPendingProfiles(harness, config) {
+async function flushPendingProfiles(harness, config, deadlineAt = Infinity) {
   const pending = readState(harness).profilePending || {};
   for (const [key, profile] of Object.entries(pending)) {
+    if (Date.now() >= deadlineAt) break;
+    let httpStatus;
     try {
       validateGeneratedProfile(profile, harness);
-      const response = await fetch(`${config.apiUrl}/v1/connectors/coding-sessions/ai-profile-observations`, {
+      assertNoCredentials(profile);
+      const response = await processingFetch(harness, config, profile, `${config.apiUrl}/v1/connectors/coding-sessions/ai-profile-observations`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${config.token}` },
         body: JSON.stringify(profile),
-        signal: AbortSignal.timeout(30_000),
+        signal: AbortSignal.timeout(requestTimeout(deadlineAt)),
       });
+      httpStatus = response.status;
       const receipt = await response.json().catch(() => undefined);
-      if (response.status !== 409 && (!response.ok || receipt?.data?.accepted !== true)) throw new Error(`HTTP ${response.status}`);
+      if (!response.ok || receipt?.data?.accepted !== true) throw new Error("AI Profile acceptance was not confirmed.");
       const state = readState(harness);
       delete state.profilePending[key];
       saveState(harness, state);
     } catch {
-      console.error(`AI Profile observation for ${profile.sessionRef} turns ${profile.fromTurn}–${profile.toTurn} remains pending.`);
+      console.error(`AI Profile observation for ${profile.sessionRef} turns ${profile.fromTurn}–${profile.toTurn} remains pending${Number.isInteger(httpStatus) ? ` (HTTP ${httpStatus})` : ""}.`);
     }
   }
 }
 
 function scanWorkFiles(folder) {
-  const entries = fs.readdirSync(validateInputFolder(folder), { withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name !== INPUT_FOLDER_README_NAME);
+  const all = fs.readdirSync(validateInputFolder(folder), { withFileTypes: true });
+  const entries = all.filter((entry) => entry.isFile() && entry.name !== INPUT_FOLDER_README_NAME);
   return {
     files: entries.filter((entry) => WORK_FILE_EXTENSIONS.has(path.extname(entry.name).toLowerCase()))
       .map((entry) => path.join(folder, entry.name)).sort(),
     unsupported: entries.filter((entry) => !WORK_FILE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())).length,
+    skippedSymlinks: all.filter((entry) => entry.isSymbolicLink()).length,
+    skippedDirectories: all.filter((entry) => entry.isDirectory()).length,
   };
 }
 
@@ -2338,26 +2619,33 @@ function readWorkFile(file) {
   }
 }
 
-async function postWorkFile(config, file, contents) {
+async function postWorkFile(config, file, contents, deadlineAt = Infinity, signal, beforeAttempt) {
+  assertNoCredentials(contents.bytes);
   let lastError;
   for (let attempt = 0; attempt < MAX_RETRIES; attempt += 1) {
+    requestTimeout(deadlineAt, 2 * 60_000);
+    beforeAttempt?.();
     let response;
     try {
       const form = new FormData();
       form.append("file", new Blob([contents.bytes]), path.basename(file));
       form.append("sourceModifiedAt", contents.modifiedAt);
       response = await fetch(`${config.apiUrl}/v1/connectors/work-files/jobs`, {
+        redirect: "error",
         method: "POST",
         headers: { Authorization: `Bearer ${config.token}` },
         body: form,
-        signal: AbortSignal.timeout(2 * 60_000),
+        signal: requestSignal(requestTimeout(deadlineAt, 2 * 60_000), signal),
       });
     } catch (error) {
+      if (signal?.aborted) throw signal.reason;
+      if (Date.now() >= deadlineAt) throw deadlineError();
       lastError = new Error(`Could not send ${path.basename(file)} to Shifu: ${error?.cause?.code || error?.message || "unknown transport error"}.`);
-      if (attempt + 1 < MAX_RETRIES) await sleep(retryDelay(undefined, attempt));
+      if (attempt + 1 < MAX_RETRIES) await sleep(requestTimeout(deadlineAt, retryDelay(undefined, attempt)));
       continue;
     }
     const payload = await response.json().catch(() => undefined);
+    if (payload === undefined && Date.now() >= deadlineAt) throw deadlineError();
     if (response.ok) {
       const receipt = payload?.data;
       if (validWorkFileJob(receipt)) return receipt;
@@ -2365,7 +2653,7 @@ async function postWorkFile(config, file, contents) {
     }
     lastError = new Error(payload?.error?.message || `Shifu rejected ${path.basename(file)} (${response.status}).`);
     if (response.status !== 429 && response.status < 500) throw lastError;
-    if (attempt + 1 < MAX_RETRIES) await sleep(retryDelay(response, attempt));
+    if (attempt + 1 < MAX_RETRIES) await sleep(requestTimeout(deadlineAt, retryDelay(response, attempt)));
   }
   throw lastError;
 }
@@ -2393,28 +2681,31 @@ function workFileEntries(state, folder) {
     .map(([name, entry]) => [name, { ...entry, replayOnCompletion: true }]));
 }
 
-async function getWorkFileJob(config, jobId) {
+async function getWorkFileJob(config, jobId, deadlineAt = Infinity) {
   let lastError;
   for (let attempt = 0; attempt < MAX_RETRIES; attempt += 1) {
+    const timeoutMs = requestTimeout(deadlineAt);
     let response;
     try {
       response = await fetch(`${config.apiUrl}/v1/connectors/work-files/jobs/${encodeURIComponent(jobId)}`, {
         headers: { Authorization: `Bearer ${config.token}` },
-        signal: AbortSignal.timeout(30_000),
+        signal: AbortSignal.timeout(timeoutMs),
       });
     } catch (error) {
+      if (Date.now() >= deadlineAt) throw deadlineError();
       lastError = new Error(`Could not check a Shifu file job: ${error?.cause?.code || error?.message || "unknown transport error"}.`);
-      if (attempt + 1 < MAX_RETRIES) await sleep(retryDelay(undefined, attempt));
+      if (attempt + 1 < MAX_RETRIES) await sleep(requestTimeout(deadlineAt, retryDelay(undefined, attempt)));
       continue;
     }
     const payload = await response.json().catch(() => undefined);
+    if (payload === undefined && Date.now() >= deadlineAt) throw deadlineError();
     if (response.ok) {
       if (validWorkFileJob(payload?.data) && payload.data.id === jobId) return payload.data;
       throw new Error("Shifu returned an invalid file-job status. Local state was not advanced.");
     }
     lastError = new Error(payload?.error?.message || `Shifu could not check a file job (${response.status}).`);
     if (response.status !== 429 && response.status < 500) throw lastError;
-    if (attempt + 1 < MAX_RETRIES) await sleep(retryDelay(response, attempt));
+    if (attempt + 1 < MAX_RETRIES) await sleep(requestTimeout(deadlineAt, retryDelay(response, attempt)));
   }
   throw lastError;
 }
@@ -2426,8 +2717,9 @@ function saveWorkFileEntry(harness, folder, name, entry) {
   saveState(harness, state);
 }
 
-async function syncWorkFiles(harness, config = readConfig(harness)) {
-  if (typeof config.inputFolder !== "string") throw new Error("No input folder is configured. Run connect again to enable file sync.");
+async function syncWorkFiles(harness, config = readConfig(harness), deadlineAt = Infinity) {
+  if (typeof config.inputFolder !== "string") throw new Error("Choose a file folder in Shifu onboarding before syncing files.");
+  currentProcessingConfig(harness, config, { folder: configuredInputFolder(config) });
   const folder = validateInputFolder(configuredInputFolder(config));
   const state = readState(harness);
   const prior = workFileEntries(state, folder);
@@ -2435,9 +2727,10 @@ async function syncWorkFiles(harness, config = readConfig(harness)) {
   const failedFiles = new Set();
   const unverifiedJobs = new Set();
   for (const [name, entry] of Object.entries(prior)) {
+    if (Date.now() >= deadlineAt) break;
     if (typeof entry !== "object" || !entry?.jobId) continue;
     try {
-      const job = await getWorkFileJob(config, entry.jobId);
+      const job = await getWorkFileJob(config, entry.jobId, deadlineAt);
       if (FINAL_WORK_FILE_STATUSES.has(job.status)) {
         console.error(`${name}: ${workFileResult(job)}.`);
         if (entry.replayOnCompletion) {
@@ -2459,15 +2752,22 @@ async function syncWorkFiles(harness, config = readConfig(harness)) {
     }
   }
   const scan = scanWorkFiles(folder);
+  if (scan.skippedSymlinks) console.error(`${scan.skippedSymlinks} symbolic link(s) skipped; linked files and folders are not uploaded.`);
+  if (scan.skippedDirectories) console.error(`${scan.skippedDirectories} subfolder(s) skipped; only files directly in the approved folder are uploaded.`);
   if (scan.unsupported) console.error(`${scan.unsupported} unsupported file${scan.unsupported === 1 ? "" : "s"} skipped (only .txt, .md, .rtf, and .docx are uploaded).`);
   for (const file of scan.files) {
+    if (Date.now() >= deadlineAt) break;
     const name = path.basename(file);
     try {
       if (unverifiedJobs.has(name)) continue;
       const contents = readWorkFile(file);
       const previous = prior[name];
       if (previous === contents.sha256 || (previous?.sha256 === contents.sha256 && previous.status !== "partial")) continue;
-      const job = await postWorkFile(config, file, contents);
+      const selection = { folder };
+      const lease = processingLease(harness, config, selection);
+      let job;
+      try { job = await postWorkFile(config, file, contents, deadlineAt, lease.signal, () => currentProcessingConfig(harness, config, selection)); }
+      finally { lease.close(); }
       const entry = FINAL_WORK_FILE_STATUSES.has(job.status) ? contents.sha256 : { sha256: contents.sha256, jobId: job.id, status: job.status };
       saveWorkFileEntry(harness, folder, name, entry);
       prior[name] = entry;
@@ -2482,10 +2782,12 @@ async function syncWorkFiles(harness, config = readConfig(harness)) {
   for (const [name, entry] of Object.entries(prior)) {
     if (entry?.status === "partial") failedFiles.add(name);
   }
-  return { submitted, pending, failures: failedFiles.size, unsupported: scan.unsupported };
+  return { submitted, pending, failures: failedFiles.size, unsupported: scan.unsupported, skippedSymlinks: scan.skippedSymlinks, skippedDirectories: scan.skippedDirectories };
 }
 
-async function sendSync(harness, input, config = readConfig(harness)) {
+async function sendSync(harness, input, config = readConfig(harness), deadlineAt = Infinity) {
+  requestTimeout(deadlineAt);
+  currentProcessingConfig(harness, config, input);
   validateSync(input, harness);
   const state = readState(harness);
   const checkpoint = state.sessions[input.sessionRef];
@@ -2503,7 +2805,10 @@ async function sendSync(harness, input, config = readConfig(harness)) {
   }
   let receipt;
   try {
-    receipt = frozen?.receipt || await postSync(config, input, frozen ? () => store.reserveBase(input) : undefined, frozen ? () => store.update(frozen.key, (entry) => { entry.baseStatus = "needs_review"; entry.reason = "base_rejected"; }) : undefined);
+    requestTimeout(deadlineAt);
+    const lease = processingLease(harness, config, input);
+    try { receipt = frozen?.receipt || await postSync(config, input, () => { currentProcessingConfig(harness, config, input); if (frozen) store.reserveBase(input); }, frozen ? () => store.update(frozen.key, (entry) => { entry.baseStatus = "needs_review"; entry.reason = "base_rejected"; }) : undefined, deadlineAt, lease.signal); }
+    finally { lease.close(); }
     if (!validSyncReceipt(receipt, input)) throw new Error("Shifu returned a checkpoint that does not match this reviewed segment. Local state was not advanced.");
   } catch (error) {
     if (frozen && store.find(input).baseAttempts >= 10) store.update(frozen.key, (entry) => { entry.baseStatus = "needs_review"; entry.reason = "base_transport_budget"; });
@@ -2517,11 +2822,54 @@ async function sendSync(harness, input, config = readConfig(harness)) {
   state.sessions[input.sessionRef] = { ...checkpoint, turnsSinceSync: 0, lastSyncedAt: Date.now(), lastSyncedTurn: Math.max(checkpoint?.lastSyncedTurn || 0, receipt.lastSyncedTurn), syncDue: false };
   saveState(harness, state);
   if (!force) prunePendingQueue(harness);
-  if (profile) await flushPendingProfiles(harness, config);
+  if (profile) await flushPendingProfiles(harness, config, deadlineAt);
   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;
 }
 
+function releaseOwnedLock(file, descriptor) {
+  const owned = fs.fstatSync(descriptor);
+  fs.closeSync(descriptor);
+  try {
+    const current = fs.lstatSync(file);
+    if (current.isFile() && current.dev === owned.dev && current.ino === owned.ino) fs.unlinkSync(file);
+  } catch (error) { if (error.code !== "ENOENT") throw error; }
+}
+
+function recoverableSyncLock(file, unknownOwnerMs = 2 * 3_600_000) {
+  let previous;
+  try { previous = fs.lstatSync(file); }
+  catch (error) { if (error.code === "ENOENT") return; throw error; }
+  if (!previous.isFile()) throw new Error("The sync lock is not a regular file; existing work was left untouched.");
+  const owner = previous.size <= 64 ? fs.readFileSync(file, "utf8").trim() : "";
+  if (/^[1-9]\d{0,9}$/.test(owner)) {
+    try { process.kill(Number(owner), 0); return; }
+    catch (error) { if (error.code !== "ESRCH") return; }
+  } else if (Date.now() - previous.mtimeMs <= unknownOwnerMs) return;
+  return previous;
+}
+
+function recoverSyncLock(file, unknownOwnerMs) {
+  if (!recoverableSyncLock(file, unknownOwnerMs)) return;
+  const guard = `${file}.recovery`;
+  let descriptor;
+  try {
+    try { descriptor = fs.openSync(guard, "wx", 0o600); }
+    catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if (recoverableSyncLock(guard, 30_000)) throw new Error("A previous sync lock recovery was interrupted; review the recovery guard before retrying. Existing work was left untouched.");
+      return;
+    }
+    fs.writeFileSync(descriptor, `${process.pid}\n`);
+    const previous = recoverableSyncLock(file, unknownOwnerMs);
+    if (!previous) return;
+    const current = fs.lstatSync(file);
+    if (current.dev === previous.dev && current.ino === previous.ino && current.ctimeMs === previous.ctimeMs) fs.unlinkSync(file);
+  } finally {
+    if (descriptor !== undefined) releaseOwnedLock(guard, descriptor);
+  }
+}
+
 async function withSyncLock(harness, action) {
   fs.mkdirSync(configRoot(), { recursive: true, mode: 0o700 });
   const file = lockPath(harness);
@@ -2532,12 +2880,12 @@ async function withSyncLock(harness, action) {
       descriptor = fs.openSync(file, "wx", 0o600);
     } catch (error) {
       if (error?.code !== "EEXIST") throw error;
-      const stale = Date.now() - fs.statSync(file).mtimeMs > 2 * 3_600_000;
-      if (!stale) return { skipped: true };
-      fs.unlinkSync(file);
-      descriptor = fs.openSync(file, "wx", 0o600);
+      recoverSyncLock(file);
+      try { descriptor = fs.openSync(file, "wx", 0o600); }
+      catch (error) { if (error.code === "EEXIST") return { skipped: true }; throw error; }
     }
     fs.writeFileSync(descriptor, `${process.pid}\n`);
+    if (HARNESS_NAMES[harness]) writeJSON(path.join(configRoot(), `${harness}-active-run.json`), { pid: process.pid, version: RUNNER_VERSION, lockInode: fs.fstatSync(descriptor).ino });
     heartbeat = setInterval(() => {
       try { fs.futimesSync(descriptor, new Date(), new Date()); } catch {}
     }, 60_000);
@@ -2545,10 +2893,11 @@ async function withSyncLock(harness, action) {
     return await action();
   } finally {
     if (heartbeat) clearInterval(heartbeat);
-    if (descriptor !== undefined) {
-      fs.closeSync(descriptor);
-      try { fs.unlinkSync(file); } catch {}
+    if (HARNESS_NAMES[harness] && descriptor !== undefined) {
+      const marker = path.join(configRoot(), `${harness}-active-run.json`);
+      if (readJSON(marker, null)?.pid === process.pid) fs.rmSync(marker, { force: true });
     }
+    if (descriptor !== undefined) releaseOwnedLock(file, descriptor);
   }
 }
 
@@ -2565,7 +2914,11 @@ async function sync(harness) {
       return;
     }
   }
-  const result = await withSyncLock(harness, () => sendSync(harness, input, config));
+  const result = await withSyncLock(harness, async () => {
+    const receipt = await sendSync(harness, input, config);
+    await flushContinuityAttachments(harness, config);
+    return receipt;
+  });
   if (result?.skipped) throw new Error("Another Shifu sync is already running. This segment was not sent; retry later.");
 }
 
@@ -2600,14 +2953,15 @@ function queuePayload(harness, input) {
   return input;
 }
 
-async function reconcilePreparedSession(harness, sessionRef, config) {
+async function reconcilePreparedSession(harness, sessionRef, config, { refresh = false, deadlineAt = Infinity } = {}) {
+  requestTimeout(deadlineAt);
   const state = readState(harness);
   const checkpoint = state.sessions[sessionRef] || {};
-  if (checkpoint.preparationVersion === REDACTION_VERSION) return;
+  if (!refresh && checkpoint.preparationVersion === REDACTION_VERSION) return;
   if (readPendingQueue(harness).segments.some((input) => input.sessionRef === sessionRef)) return;
   // Older runners did not persist automatic payloads before HTTP. Recover an
   // accepted prefix before switching an uncertain legacy range to v5.
-  const accepted = await acceptedSegments(config, sessionRef);
+  const accepted = await acceptedSegments(config, sessionRef, deadlineAt);
   let lastSyncedTurn = checkpoint.lastSyncedTurn || 0;
   for (const segment of accepted) {
     if (segment.toTurn <= lastSyncedTurn) continue;
@@ -2622,9 +2976,12 @@ function continuityState(harness, config = readConfig(harness)) {
   return require("./continuity-state.js").continuityStore(configRoot(), harness, config);
 }
 
-function preparationPacket(harness, segment, config) {
+function preparationPacket(harness, segment, config, { allowBackfill = false } = {}) {
   if (normalizedPolicy(config).excludedSessionRefs.includes(segment.sessionRef)) throw new Error("This session is excluded from preparation.");
-  if (!initialHistoryEligibility(segment, segment.fromTurn, config).eligible) throw new Error("This range is outside the saved initial-history selection.");
+  const source = localSessions(harness).find((session) => session.sessionRef === segment.sessionRef);
+  if (!source) throw new Error("The original session is unavailable; nothing was prepared.");
+  segment = { ...segment, turnTimes: source.turnTimes };
+  if (!allowBackfill && !initialHistoryEligibility(segment, segment.fromTurn, config).eligible) throw new Error("This range is outside the saved initial-history selection.");
   const records = sourceRecords(harness, segment.sessionRef);
   let minimumTurn = Math.max(1, segment.fromTurn - 6);
   for (let turn = segment.fromTurn - 1; turn >= minimumTurn; turn -= 1) {
@@ -2642,8 +2999,8 @@ function preparationPacket(harness, segment, config) {
   return { packet, workspace: createHash("sha256").update(typeof workspace === "string" && workspace ? `workspace:${workspace}` : `${harness}:session:${segment.sessionRef}`).digest("hex") };
 }
 
-async function prepareV5Payload(harness, segment, prepare = require("./native-preparation.js").prepareNative) {
-  const config = readConfig(harness);
+async function prepareV5Payload(harness, segment, prepare = require("./native-preparation.js").prepareNative, options = {}) {
+  const config = currentProcessingConfig(harness, readConfig(harness), segment);
   const store = continuityState(harness, config);
   const prior = store.load().attempts[`${segment.sessionRef}:${segment.fromTurn}`];
   if (prior?.payloadKey) {
@@ -2652,7 +3009,8 @@ async function prepareV5Payload(harness, segment, prepare = require("./native-pr
     return frozen.payload;
   }
   if (prior?.toTurn) segment = { ...segment, toTurn: prior.toTurn };
-  const { packet, workspace } = preparationPacket(harness, segment, config);
+  const { packet, workspace } = preparationPacket(harness, segment, config, options);
+  assertNoCredentials(packet);
   const dictionary = store.dictionary();
   dictionary.scopes[workspace] ||= { scopeRef: `s_${randomUUID().replaceAll("-", "")}`, entities: {} };
   store.saveDictionary(dictionary);
@@ -2671,34 +3029,243 @@ async function prepareV5Payload(harness, segment, prepare = require("./native-pr
   if (Buffer.byteLength(JSON.stringify(packet)) + 1 > 256 * 1024) throw new Error("The selected source packet exceeds 128 messages or 256 KiB. Nothing was truncated or synced.");
   if (packet.entityBindings.length > 32) throw new Error("Relevant private entity bindings exceed the bounded packet; this range needs review.");
   const bindings = { workspace, scopeRef: dictionary.scopes[workspace].scopeRef, catalog: require("./continuity-preparation.js").CATALOG };
-  const deadline = Date.now() + 180_000;
+  const deadline = Math.min(Date.now() + require("./native-preparation.js").preparationTimeoutMs(harness, config.backgroundReasoning), Number.isFinite(options.deadlineAt) ? options.deadlineAt : Infinity);
+  const { validationFeedbackText } = require("./continuity-state.js");
   let validationFeedback;
   for (let attempt = 0; attempt < 2; attempt += 1) {
     const remainingMs = deadline - Date.now();
-    if (remainingMs <= 0) throw new Error("Native preparation timed out; the source remains pending.");
+    if (remainingMs < 30_000) throw new Error("Native preparation remains pending because the run has insufficient time for another bounded attempt.");
+    if (remainingNativeRequests !== undefined && remainingNativeRequests <= 0) throw Object.assign(new Error("The native model request budget for this run is used; remaining work stays pending."), { code: "SHIFU_PREPARATION_BUDGET" });
     const reservation = store.reservation(packet, bindings);
+    validationFeedback ||= validationFeedbackText(reservation.validationFeedback);
     let output;
+    const nativeStartedAt = Date.now();
+    let diagnostic = { stage: "native_execution", category: "native_process_failed" };
     try {
-      output = await prepare(harness, packet, { validationFeedback, timeoutMs: remainingMs, continuity: true });
+      const lease = processingLease(harness, config, segment);
+      try {
+        if (remainingNativeRequests !== undefined) remainingNativeRequests--;
+        output = await prepare(harness, packet, { validationFeedback, timeoutMs: remainingMs, continuity: true, signal: lease.signal, ...(config.backgroundReasoning ? { backgroundReasoning: config.backgroundReasoning } : {}) });
+        currentProcessingConfig(harness, config, segment);
+      } finally { lease.close(); }
       const candidateDictionary = structuredClone(dictionary);
+      diagnostic = { stage: "continuity_validation", category: "continuity_validation_failed" };
       const result = require("./continuity-preparation.js").bindContinuity(packet, output, candidateDictionary, workspace);
+      diagnostic = { stage: "payload_validation", category: "payload_validation_failed" };
       validateSync(result.payload, harness);
       if (result.assessment.disposition === "no_safe_context" && reservation.attempt < 2 && packet.sources.length) throw new Error("Recheck this proposed empty result against the original sources; preserve meaningful context or confirm a legitimate neutral empty result.");
+      diagnostic = { stage: "preparation_persistence", category: "preparation_persistence_failed" };
       store.saveDictionary(candidateDictionary);
       return store.freeze(packet, result).payload;
     } catch (error) {
-      store.failure(packet);
-      if (reservation.attempt >= 2 || output === undefined) throw error;
-      validationFeedback = preparationValidationFeedback(error, output);
+      if (["SHIFU_SYNC_PAUSED", "SHIFU_SCOPE_REQUIRED"].includes(error.code)) error.preparationDiagnostic = { stage: "native_execution", category: "native_cancelled" };
+      const feedback = output !== undefined && ["continuity_validation", "payload_validation"].includes(diagnostic.stage)
+        ? preparationValidationFeedback(error, output) : undefined;
+      error.preparationDiagnostic ||= diagnostic;
+      store.failure(packet, error.preparationDiagnostic, feedback);
+      if (reservation.attempt >= 2 || output === undefined || !feedback) throw error;
+      if (deadline - Date.now() < Math.max(30_000, Date.now() - nativeStartedAt)) {
+        const deferred = new Error("Preparation correction remains pending; retry the unchanged range with its saved validation guidance and remaining native attempt.");
+        deferred.preparationDiagnostic = diagnostic;
+        throw deferred;
+      }
+      validationFeedback = validationFeedbackText(feedback);
     }
   }
 }
 
+function selectedPreparationRange(harness, config, { sessionRef, fromTurn, toTurn }, { allowBackfill = false } = {}) {
+  if (!sessionRefIsSafe(sessionRef) || !Number.isSafeInteger(fromTurn) || !Number.isSafeInteger(toTurn) || fromTurn < 1 || toTurn < fromTurn || toTurn - fromTurn >= MAX_TURNS_PER_SEGMENT) {
+    throw new Error("Choose one opaque session and an exact completed range of at most 12 turns.");
+  }
+  const session = localSessions(harness).filter((item) => item.sessionRef === sessionRef)
+    .sort((left, right) => right.turnCount - left.turnCount || String(right.updatedAt || "").localeCompare(String(left.updatedAt || "")))[0];
+  if (!session) throw new Error("The original session is unavailable; existing work was left untouched.");
+  if (toTurn > completedSessionTurn(harness, sessionRef)) throw new Error("The selected original range includes an unfinished or unavailable turn. Nothing was prepared.");
+  const segment = { ...session, fromTurn, toTurn };
+  if (normalizedPolicy(config).excludedSessionRefs.includes(sessionRef)) throw new Error("This session is excluded from preparation.");
+  if (!allowBackfill && !initialHistoryEligibility(segment, fromTurn, config).eligible) throw new Error("This range is outside the saved initial-history selection.");
+  return segment;
+}
+
+async function prepareSelectedRange(harness) {
+  const config = controls.captureConfig(readConfig(harness));
+  const selection = { sessionRef: option("--session-ref"), fromTurn: numberOption("--from-turn"), toTurn: numberOption("--to-turn") };
+  const options = { allowBackfill: hasFlag("--all") };
+  const result = await withSyncLock(harness, async () => {
+    const segment = selectedPreparationRange(harness, config, selection, options);
+    currentProcessingConfig(harness, config, segment);
+    const queue = readPendingQueue(harness);
+    const queued = queue.segments.find((input) => input.sessionRef === segment.sessionRef);
+    if (queued && (queued.fromTurn !== segment.fromTurn || queued.toTurn !== segment.toTurn)) throw new Error("Retry the existing queued range before preparing another range in this session.");
+    if (!queued) await reconcilePreparedSession(harness, segment.sessionRef, config, { refresh: true });
+    const acceptedThrough = readState(harness).sessions[segment.sessionRef]?.lastSyncedTurn || 0;
+    if (segment.fromTurn <= acceptedThrough && !queued) {
+      const outcome = { sessionRef: segment.sessionRef, fromTurn: segment.fromTurn, toTurn: segment.toTurn, acceptedThrough, status: segment.toTurn <= acceptedThrough ? "already_accepted" : "rediscover" };
+      console.log(JSON.stringify(outcome));
+      console.error("The selected range includes already accepted turns; rediscover the next range. Nothing was prepared or replayed.");
+      return outcome;
+    }
+    if (segment.fromTurn !== acceptedThrough + 1) throw new Error("Preparation must start at the next reconciled unsynced turn. Discover this session again.");
+    const prior = continuityState(harness, config).load().attempts[`${segment.sessionRef}:${segment.fromTurn}`];
+    if (prior && prior.toTurn !== segment.toTurn) throw new Error("The unresolved preparation range remains pinned; use its exact original boundaries.");
+    const payload = queued || await prepareV5Payload(harness, segment, undefined, options);
+    if (!queued) queuePayload(harness, payload);
+    const outcome = { sessionRef: payload.sessionRef, fromTurn: payload.fromTurn, toTurn: payload.toTurn, status: "queued" };
+    console.log(JSON.stringify(outcome));
+    console.error("The exact selected range is queued under the existing approval and transport policy; nothing was uploaded.");
+    return outcome;
+  });
+  if (result?.skipped) throw new Error("Another sync is running; the selected range was left untouched.");
+  return result;
+}
+
+function recoveryState(harness, config = readConfig(harness)) {
+  return require("./recovery-state.js").recoveryStore(configRoot(), harness, continuityState(harness, config).load().connection);
+}
+
+function recoveryFailureReason(error) {
+  if (error.code === "SHIFU_PREPARATION_BUDGET") return "preparation_deferred";
+  if (error.code === "SHIFU_RUN_DEADLINE") return "preparation_deferred";
+  const category = error.preparationDiagnostic?.category;
+  if (["native_timeout", "native_rate_limited", "native_authentication_failed", "native_provider_unavailable", "native_invalid_result", "continuity_validation_failed", "payload_validation_failed", "native_process_failed"].includes(category)) return category;
+  if (/exceeds 128 messages or 256 KiB/.test(error.message)) return "source_oversized";
+  if (/insufficient time/.test(error.message)) return "preparation_deferred";
+  if (/unfinished/.test(error.message)) return "unfinished_turn";
+  if (/original.*unavailable|session.*not found/i.test(error.message)) return "source_unavailable";
+  if (/exhausted|needs review/.test(error.message)) return "preparation_needs_review";
+  if (/checkpoint.*match/.test(error.message)) return "receipt_mismatch";
+  return "preparation_failed";
+}
+
+function recoverySessionComplete(harness, session, config) {
+  const checkpoint = readState(harness).sessions[session.sessionRef]?.lastSyncedTurn || 0;
+  if (checkpoint < session.throughTurn) return false;
+  return continuityState(harness, config).load().outbox
+    .filter((entry) => entry.sessionRef === session.sessionRef && entry.toTurn >= session.fromTurn && entry.fromTurn <= session.throughTurn)
+    .every((entry) => entry.baseStatus === "accepted" && validSyncReceipt(entry.receipt, entry.payload) && ["attached", "not_applicable"].includes(entry.continuityStatus));
+}
+
+function preparationRunMs(harness, config) {
+  const nativeMs = require("./native-preparation.js").preparationTimeoutMs(harness, config.backgroundReasoning);
+  return nativeMs > PREPARATION_RUN_MS ? nativeMs + PREPARATION_RUN_MS : PREPARATION_RUN_MS;
+}
+
+async function runRecoveryBatch(harness, config, deadlineAt = Date.now() + preparationRunMs(harness, config)) {
+  const store = recoveryState(harness, config);
+  const recovery = store.load();
+  if (!recovery || recovery.status === "complete") return { synced: 0, active: false, ...store.summary() };
+  if (normalizedPolicy(config).approvalMode !== "automatic") throw new Error("Recovery requires the saved automatic approval mode; no work was sent.");
+  const excluded = new Set(normalizedPolicy(config).excludedSessionRefs);
+  const continuity = continuityState(harness, config);
+  restoreContinuityQueue(harness, config);
+  let visited = 0;
+  let prepared = 0;
+  let synced = 0;
+  while (visited < recovery.sessions.length && prepared < MAX_PREPARATIONS_PER_RUN && Date.now() + 30_000 < deadlineAt) {
+    const index = recovery.nextSession;
+    const session = recovery.sessions[index];
+    recovery.nextSession = (index + 1) % recovery.sessions.length;
+    visited += 1;
+    store.save(recovery);
+    if (session.completed) continue;
+    try {
+      if (excluded.has(session.sessionRef)) { session.reason = "excluded_session"; continue; }
+      if (!session.reconciled) {
+        await reconcilePreparedSession(harness, session.sessionRef, config, { refresh: true, deadlineAt });
+        session.reconciled = true;
+      }
+      if (recoverySessionComplete(harness, session, config)) {
+        session.completed = true; session.reason = null; continue;
+      }
+      const checkpoint = readState(harness).sessions[session.sessionRef]?.lastSyncedTurn || 0;
+      if (checkpoint >= session.throughTurn) { session.reason = "continuity_pending"; continue; }
+      const identity = `${session.sessionRef}:${checkpoint + 1}`;
+      const queued = readPendingQueue(harness).segments.find((entry) => entry.sessionRef === session.sessionRef);
+      const state = continuity.load();
+      const held = state.attempts[identity];
+      const selected = require("./recovery-state.js").nextRecoveryRange({ session, checkpoint, completedTo: queued ? queued.toTurn : completedSessionTurn(harness, session.sessionRef), queued, held });
+      if (selected.status !== "range") { session.reason = selected.reason || "preparation_failed"; continue; }
+      if (!queued && held && recovery.retryCandidates.includes(identity) && !recovery.retriedHolds.includes(identity)) {
+        recovery.retriedHolds.push(identity);
+        store.save(recovery); // Consume this explicit authorization before changing an attempt budget.
+        held.attempts = 0; held.status = "unresolved";
+        delete held.reason; delete held.diagnostic;
+        continuity.save(state);
+      }
+      if (!queued && held?.attempts >= 2) { session.reason = "preparation_needs_review"; continue; }
+      if (!queued && Date.now() + require("./native-preparation.js").preparationTimeoutMs(harness, config.backgroundReasoning) > deadlineAt) {
+        session.reason = "preparation_deferred";
+        recovery.nextSession = index;
+        break;
+      }
+      const segment = queued || selectedPreparationRange(harness, config, { sessionRef: session.sessionRef, fromTurn: selected.fromTurn, toTurn: selected.toTurn }, { allowBackfill: true });
+      prepared += 1;
+      const payload = queued || await prepareV5Payload(harness, segment, undefined, { allowBackfill: true, deadlineAt });
+      if (!queued) queuePayload(harness, payload);
+      try {
+        await sendSync(harness, payload, config, deadlineAt);
+      } catch (error) {
+        session.reason = error.code === "SHIFU_RUN_DEADLINE" ? "preparation_deferred" : "transport_failed";
+        continue;
+      }
+      synced += 1;
+      session.reason = null;
+    } catch (error) {
+      session.reason = recoveryFailureReason(error);
+      console.error(`Selected recovery range remains pending: ${session.reason}.`);
+      if (error.nativeObservation) console.error(JSON.stringify({ nativeObservation: error.nativeObservation }));
+    } finally {
+      store.save(recovery);
+    }
+  }
+  await flushContinuityAttachments(harness, config, deadlineAt);
+  for (const session of recovery.sessions) {
+    if (session.reconciled && !session.completed && recoverySessionComplete(harness, session, config)) { session.completed = true; session.reason = null; }
+  }
+  recovery.status = recovery.sessions.every((session) => session.completed) ? "complete"
+    : recovery.sessions.some((session) => !session.completed && session.reason === null) ? "running" : "pending";
+  store.save(recovery);
+  return { synced, active: recovery.status !== "complete", ...store.summary() };
+}
+
+async function recoverSelectedSessions(harness) {
+  const config = controls.captureConfig(readConfig(harness));
+  if (normalizedPolicy(config).approvalMode !== "automatic") throw new Error("Recovery requires the configured automatic approval mode; settings were left unchanged.");
+  const result = await withSyncLock(harness, async () => {
+    const store = recoveryState(harness, config);
+    const selection = option("--selection");
+    if (selection) {
+      const input = readJSON(path.resolve(selection));
+      if (input.harness !== harness) throw new Error("Recovery selection belongs to another harness.");
+      const sessions = input.sessions || input.selected;
+      if (!Array.isArray(sessions)) throw new Error("A fixed recovery session selection is required.");
+      const selected = new Map(sessions.map((session) => [session.sessionRef, session]));
+      const retryCandidates = Object.entries(continuityState(harness, config).load().attempts)
+        .filter(([identity, attempt]) => {
+          const session = selected.get(attempt.sessionRef || identity.slice(0, identity.lastIndexOf(":")));
+          return session && attempt.fromTurn >= session.fromTurn && attempt.toTurn <= session.throughTurn && !attempt.payloadKey && ["unresolved", "needs_review", "preparing"].includes(attempt.status);
+        })
+        .map(([identity]) => identity);
+      store.start({ selectedAt: input.selectedAt, sessions, retryCandidates });
+    }
+    if (!store.load()) throw new Error("No saved recovery selection exists. Provide its fixed selection file once.");
+    const { sessions = [], ...progress } = await runRecoveryBatch(harness, config);
+    const pendingReasons = sessions.reduce((counts, session) => {
+      if (session.reason) counts[session.reason] = (counts[session.reason] || 0) + 1;
+      return counts;
+    }, {});
+    console.log(JSON.stringify({ ...progress, pendingReasons }));
+  });
+  if (result?.skipped) throw new Error("Another sync is running; the saved recovery selection is unchanged.");
+}
+
 async function retryPreparation(harness) {
   const sessionRef = option("--session-ref");
   const fromTurn = numberOption("--from-turn");
   if (!sessionRefIsSafe(sessionRef) || !Number.isSafeInteger(fromTurn) || fromTurn < 1) throw new Error("Choose the held session and original from-turn explicitly.");
   const result = await withSyncLock(harness, async () => {
+    const config = readConfig(harness);
     const store = continuityState(harness);
     const state = store.load();
     const identity = `${sessionRef}:${fromTurn}`;
@@ -2706,12 +3273,14 @@ async function retryPreparation(harness) {
     if (!held || held.payloadKey || state.outbox.some((entry) => entry.sessionRef === sessionRef && entry.fromTurn === fromTurn) || readPendingQueue(harness).segments.some((input) => input.sessionRef === sessionRef && input.toTurn >= fromTurn)) {
       throw new Error("Only an unqueued preparation hold can be retried; frozen payloads keep their exact transport path.");
     }
-    if ((readState(harness).sessions[sessionRef]?.lastSyncedTurn || 0) >= fromTurn) throw new Error("Accepted ranges require separately authorized historical recovery.");
-    const session = localSessions(harness).find((item) => item.sessionRef === sessionRef);
-    if (!session) throw new Error("The original session is unavailable; the hold was preserved.");
-    held.attempts = 0; held.status = "unresolved"; delete held.reason;
+    const options = { allowBackfill: hasFlag("--all") };
+    const segment = selectedPreparationRange(harness, config, { sessionRef, fromTurn, toTurn: held.toTurn }, options);
+    await reconcilePreparedSession(harness, sessionRef, config, { refresh: true });
+    if (fromTurn !== (readState(harness).sessions[sessionRef]?.lastSyncedTurn || 0) + 1) throw new Error("Only the next reconciled unsynced range can be retried; the hold was preserved.");
+    preparationPacket(harness, segment, config, options);
+    held.attempts = 0; held.status = "unresolved"; delete held.reason; delete held.diagnostic;
     store.save(state);
-    const payload = await prepareV5Payload(harness, { ...session, fromTurn, toTurn: held.toTurn });
+    const payload = await prepareV5Payload(harness, segment, undefined, options);
     queuePayload(harness, payload);
     console.error("The selected preparation is queued for its existing approval and transport policy.");
   });
@@ -2734,18 +3303,22 @@ function preparationValidationFeedback(error, output) {
     if (field.endsWith(".workContext") && value === "") continue;
     if (typeof value !== "string" || textIsSafe(value, maximum, true)) continue;
     let reason = "empty or oversized text";
+    let fragment;
     if (/[\x00-\x1f\x7f]/.test(value)) reason = "control characters or line breaks";
     else if (PHONE_NUMBER_PATTERN.test(value)) reason = "a phone-like numeric sequence";
     else if (UNSAFE_CODE_PATTERN.test(value)) reason = "a code-like declaration";
     else if (CREDENTIAL_ASSIGNMENT_PATTERN.test(value) || CLOUD_CREDENTIAL_PATTERN.test(value)) reason = "a credential-like pattern";
     else {
-      const fragment = SENSITIVE_PATTERNS.find((pattern) => value.toLowerCase().includes(pattern));
-      if (fragment) reason = `the forbidden literal fragment ${JSON.stringify(fragment)}`;
+      fragment = SENSITIVE_PATTERNS.find((pattern) => value.toLowerCase().includes(pattern));
+      if (fragment) reason = "a forbidden literal fragment";
     }
     // Field names and rule literals are code-owned; never echo rejected text.
-    issues.push(`Field ${field} fails the privacy or length rule for ${reason}.`);
+    issues.push({ path: field, reason, ...(fragment ? { fragment } : {}) });
   }
-  return `${error.message}${issues.length ? ` ${issues.join(" ")} Rephrase those fields without copying the rejected content.` : ""} Recheck every text field before returning. Describe a user's go-ahead as approval, permission or adoption; the literal word authorization is rejected by the privacy filter. Preserve supported results, failed or pending checks, unresolved problems and release status while correcting the validation error.`;
+  const { safeValidationFeedback } = require("./continuity-state.js");
+  const feedbackFields = issues.slice(0, 64);
+  const rule = "Preparation failed strict local validation; recheck schema, text limits and references.";
+  return safeValidationFeedback({ rule: error.message, fields: feedbackFields }) || safeValidationFeedback({ rule, fields: feedbackFields }) || safeValidationFeedback({ rule, fields: [] });
 }
 
 function preparationState(harness, queue) {
@@ -2760,15 +3333,26 @@ function preparationState(harness, queue) {
   return { virtual, blocked };
 }
 
-async function preparePendingQueue(harness, config, blockedSessions = new Set()) {
+function preparationFailureSessions(harness, config, errors = []) {
+  const excluded = new Set(normalizedPolicy(config).excludedSessionRefs);
+  const state = readState(harness);
+  const failures = new Set(errors.map((error) => error.sessionRef));
+  for (const attempt of continuityState(harness, config).summary().preparation) {
+    if (["unresolved", "needs_review"].includes(attempt.status) && attempt.toTurn > (state.sessions[attempt.sessionRef]?.lastSyncedTurn || 0)) failures.add(attempt.sessionRef);
+  }
+  for (const sessionRef of excluded) failures.delete(sessionRef);
+  return failures;
+}
+
+async function preparePendingQueue(harness, config, blockedSessions = new Set(), deadlineAt = Date.now() + preparationRunMs(harness, config)) {
   restoreContinuityQueue(harness, config);
   let queue = prunePendingQueue(harness);
   const previousFailures = new Set((queue.preparationErrors || []).map((error) => error.sessionRef));
   const errors = [];
   const attempted = new Set();
-  const deadline = Date.now() + PREPARATION_RUN_MS;
+  const deadline = deadlineAt;
   let attempts = 0;
-  while (attempts < MAX_PREPARATIONS_PER_RUN && Date.now() < deadline) {
+  while (attempts < MAX_PREPARATIONS_PER_RUN && Date.now() + require("./native-preparation.js").preparationTimeoutMs(harness, config.backgroundReasoning) < deadline) {
     const { virtual, blocked } = preparationState(harness, queue);
     const candidates = pendingSegments(harness, virtual).filter((item) => !blocked.has(item.sessionRef) && !blockedSessions.has(item.sessionRef));
     const segment = candidates.find((item) => !previousFailures.has(item.sessionRef)) || candidates[0];
@@ -2781,14 +3365,14 @@ async function preparePendingQueue(harness, config, blockedSessions = new Set())
       }
       if (!attempted.has(segment.sessionRef)) {
         attempted.add(segment.sessionRef);
-        await reconcilePreparedSession(harness, segment.sessionRef, config);
+        await reconcilePreparedSession(harness, segment.sessionRef, config, { deadlineAt: deadline });
         // Remote acknowledgement can change the next unsynced range.
         continue;
       }
       let payload;
       attempts += 1;
       for (let toTurn = segment.toTurn; toTurn >= segment.fromTurn; toTurn -= 1) {
-        try { payload = await prepareV5Payload(harness, { ...segment, toTurn }); break; }
+        try { payload = await prepareV5Payload(harness, { ...segment, toTurn }, undefined, { deadlineAt: deadline }); break; }
         catch (error) {
           if (toTurn > segment.fromTurn && /exceeds 128 messages or 256 KiB/.test(error.message)) continue;
           throw error;
@@ -2797,6 +3381,7 @@ async function preparePendingQueue(harness, config, blockedSessions = new Set())
       queuePayload(harness, payload);
       queue = readPendingQueue(harness);
     } catch (error) {
+      if (error.code === "SHIFU_PREPARATION_BUDGET") break;
       blockedSessions.add(segment.sessionRef);
       errors.push({ sessionRef: segment.sessionRef, fromTurn: segment.fromTurn, toTurn: segment.toTurn, reason: error.message });
       console.error(`${HARNESS_NAMES[harness]} preparation remains pending: ${error.message}`);
@@ -2808,7 +3393,7 @@ async function preparePendingQueue(harness, config, blockedSessions = new Set())
   return queue;
 }
 
-async function drainPendingQueue(harness, config, blockedSessions) {
+async function drainPendingQueue(harness, config, blockedSessions, deadlineAt = Infinity) {
   let synced = 0;
   let failures = 0;
   const store = continuityState(harness, config);
@@ -2817,8 +3402,9 @@ async function drainPendingQueue(harness, config, blockedSessions) {
   const excluded = new Set(normalizedPolicy(config).excludedSessionRefs);
   const inputs = [...queued, ...entries.filter((entry) => !excluded.has(entry.sessionRef) && !queued.some((input) => JSON.stringify(input) === JSON.stringify(entry.payload))).map((entry) => entry.payload)];
   for (const input of inputs) {
+    if (Date.now() >= deadlineAt) break;
     if (blockedSessions.has(input.sessionRef) || store.find(input)?.baseStatus === "needs_review") continue;
-    try { await sendSync(harness, input, config); synced += 1; }
+    try { await sendSync(harness, input, config, deadlineAt); synced += 1; }
     catch (error) {
       failures += 1;
       blockedSessions.add(input.sessionRef);
@@ -2828,15 +3414,26 @@ async function drainPendingQueue(harness, config, blockedSessions) {
   return { synced, failures };
 }
 
-async function flushContinuityAttachments(harness, config) {
+async function flushContinuityAttachments(harness, config, deadlineAt = Infinity) {
+  if (Date.now() >= deadlineAt) return;
   const store = continuityState(harness, config);
   if (!store.load().outbox.some((entry) => entry.baseStatus === "accepted" && !["attached", "not_applicable", "needs_review"].includes(entry.continuityStatus))) return;
   let capable = false;
   try {
-    const connection = await validateConnection(config.apiUrl, config.token, harness);
+    const connection = await validateConnection(config.apiUrl, config.token, harness, deadlineAt);
     capable = connection.capabilities?.continuityAttachment === 1;
   } catch { /* Base receipts remain valid while capability discovery is unavailable. */ }
-  await require("./continuity-state.js").flushContinuity(store, config, capable);
+  if (Date.now() >= deadlineAt) return;
+  await require("./continuity-state.js").flushContinuity(store, config, capable, (url, options) => {
+    const syncId = String(url).match(/\/syncs\/([^/]+)\/continuity$/)?.[1];
+    const source = store.load().outbox.find((entry) => String(entry.receipt?.id) === syncId);
+    assertNoCredentials(JSON.parse(options.body || "{}"));
+    if (!source) throw controls.processingError("SHIFU_SCOPE_REQUIRED");
+    return processingFetch(harness, config, source, url, options);
+  }, Date.now(), deadlineAt, (entry) => {
+    try { currentProcessingConfig(harness, config, entry); return true; }
+    catch (error) { if (["SHIFU_SCOPE_REQUIRED", "SHIFU_SYNC_PAUSED"].includes(error.code)) return false; throw error; }
+  });
 }
 
 function restoreContinuityQueue(harness, config) {
@@ -2945,23 +3542,32 @@ async function approvePending(harness) {
 }
 
 async function scheduledSync(harness) {
+  const startingConfig = readConfig(harness);
+  if (!controls.validAuthorization(startingConfig) || startingConfig.syncPaused) {
+    console.error(startingConfig.syncPaused ? "Shifu capture is paused." : "Shifu capture needs scope approval. Open onboarding to review and start sync.");
+    return;
+  }
   await require("./onboarding.js").resumeBackfill(onboardingRuntime(harness));
-  const config = readConfig(harness);
+  const config = currentProcessingConfig(harness, startingConfig);
   const policy = normalizedPolicy(config);
   if (!policy.onboardingComplete || !policy.scheduleEnabled) return;
   const state = readState(harness);
   if (Number.isFinite(state.schedule?.nextRunAt) && state.schedule.nextRunAt > Date.now()) return;
   const result = await withSyncLock(harness, async () => {
     const startedAt = Date.now();
+    const deadlineAt = startedAt + preparationRunMs(harness, config);
+    const running = readState(harness);
+    running.schedule = { ...running.schedule, lastAttemptAt: startedAt, lastResult: "running", runDeadlineAt: deadlineAt };
+    saveState(harness, running);
     let failures = 0;
     let synced = 0;
     let submittedFiles = 0;
     let pendingFiles = 0;
     let failedFiles = 0;
     let unsupportedFiles = 0;
-    if (config.inputFolder) {
+    if (config.inputFolder && controls.filesAllowed(config, configuredInputFolder(config))) {
       try {
-        const files = await syncWorkFiles(harness, config);
+        const files = await syncWorkFiles(harness, config, deadlineAt);
         failedFiles = files.failures;
         submittedFiles = files.submitted;
         pendingFiles = files.pending;
@@ -2971,11 +3577,11 @@ async function scheduledSync(harness) {
         console.error(`Shifu input folder remains pending: ${error.message}`);
       }
     }
-    await flushPendingProfiles(harness, config);
+    await flushPendingProfiles(harness, config, deadlineAt);
     restoreContinuityQueue(harness, config);
-    await flushContinuityAttachments(harness, config);
+    await flushContinuityAttachments(harness, config, deadlineAt);
     if (policy.approvalMode === "manual") {
-      const queue = await preparePendingQueue(harness, config);
+      const queue = await preparePendingQueue(harness, config, new Set(), deadlineAt);
       const queued = eligibleQueuedSegments(queue, config);
       const eligible = [...queued, ...continuityRecoveries(harness, config, queued)];
       const pendingFingerprint = createHash("sha256").update(eligible.map((segment) => `${segment.sessionRef}:${segment.fromTurn}:${segment.toTurn}`).join("\n")).digest("hex");
@@ -2986,8 +3592,11 @@ async function scheduledSync(harness) {
         try {
           approvalSessionRef = notifyManualApproval(harness, eligible.length, approvalSessionRef);
           if (approvalSessionRef && !config.syncPolicy.excludedSessionRefs.includes(approvalSessionRef)) {
-            config.syncPolicy.excludedSessionRefs.push(approvalSessionRef);
-            writeJSON(configPath(harness), config);
+            updateSavedConfig(harness, (current) => {
+              if (controls.connectionFingerprint(current) !== controls.connectionFingerprint(config)) throw controls.processingError("SHIFU_SCOPE_REQUIRED");
+              const excludedSessionRefs = [...new Set([...normalizedPolicy(current).excludedSessionRefs, approvalSessionRef])];
+              return { ...current, syncPolicy: { ...current.syncPolicy, excludedSessionRefs } };
+            });
           }
         } catch (error) {
           notificationError = error?.message || "Could not create the approval session.";
@@ -2995,7 +3604,7 @@ async function scheduledSync(harness) {
       }
       const pendingProfiles = Object.keys(readState(harness).profilePending || {}).length;
       const unprepared = pendingSegments(harness, preparationState(harness, queue).virtual).length;
-      const preparationFailures = queue.preparationErrors.length;
+      const preparationFailures = preparationFailureSessions(harness, config, queue.preparationErrors).size;
       state.schedule = {
         ...state.schedule,
         lastAttemptAt: startedAt,
@@ -3014,28 +3623,32 @@ async function scheduledSync(harness) {
         nextRunAt: Date.now() + (notificationError || failedFiles || pendingProfiles || preparationFailures || unprepared ? SCHEDULER_TICK_MINUTES / 60 : policy.intervalHours) * 3_600_000,
       };
     } else {
+      const recovery = await runRecoveryBatch(harness, config, deadlineAt);
       const blockedSessions = new Set();
-      const previous = await drainPendingQueue(harness, config, blockedSessions);
-      const queue = await preparePendingQueue(harness, config, blockedSessions);
-      const current = await drainPendingQueue(harness, config, blockedSessions);
-      synced = previous.synced + current.synced;
-      failures = previous.failures + current.failures + queue.preparationErrors.length;
+      const previous = await drainPendingQueue(harness, config, blockedSessions, deadlineAt);
+      const queue = Date.now() + 30_000 < deadlineAt ? await preparePendingQueue(harness, config, blockedSessions, deadlineAt) : prunePendingQueue(harness);
+      const current = await drainPendingQueue(harness, config, blockedSessions, deadlineAt);
+      synced = recovery.synced + previous.synced + current.synced;
+      const preparationFailures = preparationFailureSessions(harness, config, queue.preparationErrors).size;
+      failures = previous.failures + current.failures + preparationFailures;
       const remaining = pendingSegments(harness).length || eligibleQueuedSegments(readPendingQueue(harness), config).length;
       const pendingProfiles = Object.keys(readState(harness).profilePending || {}).length;
+      const deferred = Date.now() >= deadlineAt;
       state.schedule = {
         lastAttemptAt: startedAt,
-        lastResult: failures || failedFiles || pendingProfiles ? "partial_failure" : remaining ? "pending_preparation" : "complete",
+        lastResult: failures || failedFiles || pendingProfiles ? "partial_failure" : recovery.active ? "recovering" : remaining || deferred ? "pending_preparation" : "complete",
         syncedSegments: synced,
         failedSessions: failures,
+        preparationFailures,
         submittedFiles,
         pendingFiles,
         failedFiles,
         unsupportedFiles,
         pendingProfiles,
-        nextRunAt: Date.now() + (failures || failedFiles || pendingProfiles || remaining ? SCHEDULER_TICK_MINUTES / 60 : policy.intervalHours) * 3_600_000,
+        nextRunAt: Date.now() + (failures || failedFiles || pendingProfiles || remaining || recovery.active || deferred ? SCHEDULER_TICK_MINUTES / 60 : policy.intervalHours) * 3_600_000,
       };
     }
-    await flushContinuityAttachments(harness, config);
+    await flushContinuityAttachments(harness, config, deadlineAt);
     const latest = readState(harness);
     latest.schedule = state.schedule;
     saveState(harness, latest);
@@ -3047,12 +3660,21 @@ function status(harness) {
   const config = readConfig(harness);
   const state = readState(harness);
   const pending = readJSON(pendingPath(harness), { segments: [] });
+  const preparationFailures = preparationFailureSessions(harness, config, pending.preparationErrors).size;
+  const schedule = state.schedule ? { ...state.schedule } : null;
+  if (schedule && preparationFailures) {
+    schedule.preparationFailures = preparationFailures;
+    if (normalizedPolicy(config).approvalMode === "automatic") schedule.failedSessions = Math.max(schedule.failedSessions || 0, preparationFailures);
+    if (["complete", "pending_preparation", "awaiting_approval"].includes(schedule.lastResult)) schedule.lastResult = "partial_failure";
+  }
   const folder = config.inputFolder ? configuredInputFolder(config) : null;
   const entries = folder ? Object.values(workFileEntries(state, folder)) : [];
   let unsupportedFiles = null;
+  let skippedSymlinks = null;
+  let skippedDirectories = null;
   let inputFolderError = null;
   if (folder) {
-    try { unsupportedFiles = scanWorkFiles(folder).unsupported; } catch (error) { inputFolderError = error.message; }
+    try { ({ unsupported: unsupportedFiles, skippedSymlinks, skippedDirectories } = scanWorkFiles(folder)); } catch (error) { inputFolderError = error.message; }
   }
   const initialHistoryBlocked = [];
   if (config.initialBackfill) {
@@ -3066,7 +3688,7 @@ function status(harness) {
       if (!eligibility.eligible) initialHistoryBlocked.push({ sessionRef: session.sessionRef, reason: eligibility.reason, cutoffAt: eligibility.cutoffAt });
     }
   }
-  console.log(JSON.stringify({ continuity: continuityState(harness, config).summary(), harness, runnerVersion: RUNNER_VERSION, apiUrl: config.apiUrl, inputFolder: folder, inputFolderError, contextPreferences: config.contextPreferences === undefined ? null : normalizeContextPreferences(config.contextPreferences), historicalContext: true, initialBackfill: config.initialBackfill || null, initialHistoryBlocked, syncPolicy: normalizedPolicy(config), schedule: state.schedule || null, pendingSegments: pending.segments.length, completedFiles: entries.filter((entry) => typeof entry === "string").length, pendingFiles: entries.filter((entry) => typeof entry === "object" && entry?.jobId).length, unsupportedFiles, sessions: state.sessions }, null, 2));
+  console.log(JSON.stringify({ ...onboardingRuntime(harness).scopeStatus(), skippedSymlinks, skippedDirectories, continuity: continuityState(harness, config).summary(), recovery: recoveryState(harness, config).summary(), harness, runnerVersion: RUNNER_VERSION, backgroundReasoning: harness === "codex" ? config.backgroundReasoning || "inherit" : null, apiUrl: config.apiUrl, inputFolder: folder, inputFolderError, contextPreferences: config.contextPreferences === undefined ? null : normalizeContextPreferences(config.contextPreferences), historicalContext: true, initialBackfill: config.initialBackfill || null, initialHistoryBlocked, syncPolicy: normalizedPolicy(config), schedule, pendingSegments: pending.segments.length, completedFiles: entries.filter((entry) => typeof entry === "string").length, pendingFiles: entries.filter((entry) => typeof entry === "object" && entry?.jobId).length, unsupportedFiles, sessions: state.sessions }, null, 2));
 }
 
 async function syncFilesNow(harness) {
@@ -3076,14 +3698,14 @@ async function syncFilesNow(harness) {
   if (result.failures) throw new Error("Some input files need retry. They will be checked on the next sync.");
 }
 
-async function acceptedSegments(config, sessionRef) {
+async function acceptedSegments(config, sessionRef, deadlineAt = Infinity) {
   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 response = await fetch(url, { headers: { Authorization: `Bearer ${config.token}` }, signal: AbortSignal.timeout(requestTimeout(deadlineAt)) });
     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;
@@ -3288,42 +3910,122 @@ async function cursorHook() {
     input += chunk.toString("utf8");
     if (Buffer.byteLength(input) > 1024 * 1024) throw new Error("Cursor hook input exceeded 1 MB. Nothing was captured.");
   }
-  const payload = JSON.parse(input);
+  let payload;
+  try { payload = JSON.parse(input); } catch { throw new Error("Cursor hook input is not valid JSON. Nothing was captured."); }
   if (payload.hook_event_name === "sessionStart") {
     const file = contextInstructionFile("cursor");
     const instruction = fs.existsSync(file) ? readContextInstructionFile(file).original : "";
     const sessionRef = require("./cursor-sessions.js").sessionRefForConversation(payload.conversation_id || payload.session_id);
     return console.log(JSON.stringify({ env: { SHIFU_CURSOR_SESSION_REF: sessionRef }, ...(instruction ? { additional_context: instruction } : {}) }));
   }
-  require("./cursor-sessions.js").captureHook(payload, cursorOptions());
+  const config = readConfig("cursor");
+  if (!controls.validAuthorization(config) || config.syncPaused) return console.log("{}");
+  const sessionRef = require("./cursor-sessions.js").sessionRefForConversation(payload.conversation_id || payload.session_id);
+  const workspace = payload.workspace_roots?.[0] || localSessions("cursor").find((session) => session.sessionRef === sessionRef)?.workspace;
+  if (controls.sessionAllowed(config, { sessionRef, workspace })) require("./cursor-sessions.js").captureHook(payload, cursorOptions());
   console.log("{}");
 }
 
 function onboardingRuntime(harness, { prepareNative } = {}) {
+  const scopeStatus = () => {
+    const config = readJSON(configPath(harness), null);
+    const authorization = controls.validAuthorization(config);
+    const desktop = readDesktopProfile(configRoot());
+    const apiUrl = requireSafeApiUrl(config?.apiUrl || option("--api-url") || process.env.SHIFU_API_URL || DEFAULT_API_URL);
+    let connectionKeyUrl;
+    if (desktop?.connectionKeyLinks === true) connectionKeyUrl = `shifu://sources/coding-sessions?${new URLSearchParams({ harness, profile: desktop.namespace, connection: 'key' })}`;
+    else if (!desktop && apiUrl === DEFAULT_API_URL) connectionKeyUrl = `https://app.useshifu.com/#/sources/coding-sessions?${new URLSearchParams({ harness, connection: 'key' })}`;
+    let projects = [], projectDiscoveryError;
+    try { projects = controls.projectCatalog(localSessions(harness)); }
+    catch { projectDiscoveryError = "Local project history is unavailable. Check the coding tool installation before selecting history."; }
+    const current = controls.projectIdentity({ workspace: process.cwd() }).ref;
+    const projectRefs = authorization?.projectRefs || (projects.some((item) => item.ref === current) ? [current] : projects.length === 1 ? [projects[0].ref] : []);
+    return { runnerVersion: RUNNER_VERSION, connectionKeyUrl, projects, projectDiscoveryError, projectScope: authorization?.projectScope || "selected", projectRefs,
+      filesEnabled: authorization ? authorization.filesEnabled : true, inputFolder: config?.inputFolder || defaultInputFolder(),
+      paused: config?.syncPaused === true, scopeReviewRequired: !authorization,
+      syncPolicy: authorization ? normalizedPolicy(config) : { intervalHours: 1, approvalMode: "automatic", scheduleEnabled: true } };
+  };
+  const preview = (choices, state) => {
+    const config = readJSON(configPath(harness), null);
+    const status = scopeStatus();
+    const sessions = localSessions(harness);
+    const known = new Set(status.projects.map((item) => item.ref));
+    if (choices.projectRefs.some((ref) => !known.has(ref))) throw new Error("The project list changed. Review the selection again.");
+    if (choices.projectScope === "selected" && !choices.projectRefs.length) throw new Error("Choose a project or explicitly choose all projects.");
+    const selectedAt = state.previewSelectedAt || (state.authorized && state.historyDays === choices.historyDays ? state.selectedAt : null) || new Date().toISOString();
+    const history = createInitialBackfill(choices.historyDays, selectedAt);
+    const selected = sessions.filter((item) => choices.projectScope === "all" || choices.projectRefs.includes(controls.projectIdentity(item).ref));
+    const cutoff = Date.parse(history.selectedAt) - history.days * 86_400_000;
+    const selectedSessions = history.days ? selected.filter((item) => Date.parse(item.updatedAt) >= cutoff) : [];
+    const requestedFolder = choices.inputFolder || config?.inputFolder || defaultInputFolder();
+    let inputFolder = path.resolve(requestedFolder.startsWith("~/") ? path.join(os.homedir(), requestedFolder.slice(2)) : requestedFolder);
+    let scan = { files: [], unsupported: 0, skippedSymlinks: 0, skippedDirectories: 0 };
+    if (choices.filesEnabled) {
+      if (fs.existsSync(inputFolder)) { inputFolder = fs.realpathSync(validateInputFolder(inputFolder)); scan = scanWorkFiles(inputFolder); }
+      else if (inputFolder !== defaultInputFolder()) throw new Error("Choose an existing readable folder.");
+    }
+    const files = scan.files.map((file) => { const stat = fs.statSync(file); return { name: path.basename(file), bytes: stat.size, modifiedAt: stat.mtimeMs }; });
+    const projectRefs = choices.projectScope === "all" ? [] : [...choices.projectRefs].sort();
+    const metadata = { destination: requireSafeApiUrl(config?.apiUrl || option("--api-url") || process.env.SHIFU_API_URL || DEFAULT_API_URL), connection: controls.connectionFingerprint(config), generation: config?.syncGeneration || 0, history, projectScope: choices.projectScope, projectRefs, filesEnabled: choices.filesEnabled,
+      inputFolder: choices.filesEnabled ? inputFolder : null, scheduleEnabled: choices.scheduleEnabled, files,
+      sessions: selectedSessions.map((item) => [item.sessionRef, item.turnCount, item.updatedAt]).sort() };
+    const scopeRevision = parseInt(createHash("sha256").update(JSON.stringify(metadata)).digest("hex").slice(0, 12), 16) || 1;
+    return { ...metadata, connection: undefined, generation: undefined, files: files.map(({ name, bytes }) => ({ name, bytes })), sessions: undefined,
+      projects: status.projects.filter((item) => choices.projectScope === "all" || projectRefs.includes(item.ref)),
+      historyDays: history.days, selectedAt: history.selectedAt, scopeRevision,
+      sessionCount: selectedSessions.length, fileCount: files.length, totalFileBytes: files.reduce((sum, file) => sum + file.bytes, 0),
+      skippedSymlinks: scan.skippedSymlinks, skippedDirectories: scan.skippedDirectories, unsupportedFiles: scan.unsupported,
+      inputFolder, syncPolicy: { ...status.syncPolicy, scheduleEnabled: choices.scheduleEnabled },
+      quotaNotice: "Preparing selected history uses your coding tool’s configured model account and counts toward its usage allowance. Each background run makes at most four native model requests, including corrections." };
+  };
   return {
     harness, root: configRoot(), runner: installedRunnerPath(), assets: path.join(resourceRoot(), "wizard"),
-    readConfig: () => readJSON(configPath(harness), null),
+    readConfig: () => readJSON(configPath(harness), null), scopeStatus, preview,
+    canProcess: () => { const config = readJSON(configPath(harness), null); return Boolean(controls.validAuthorization(config)) && config.syncPaused !== true; },
+    pause: () => setSyncPaused(harness, true),
+    resume: () => setSyncPaused(harness, false),
     checkpoint: (reference) => readState(harness).sessions[reference]?.lastSyncedTurn || 0,
     copyRunner,
     configure: async (choices, key) => {
       const existing = readJSON(configPath(harness), null);
+      let generation;
       if (existing) {
         await validateConnection(existing.apiUrl, existing.token, harness);
-        writeJSON(configPath(harness), { ...existing, ...choices });
-      } else await connect(harness, async () => key, choices, true);
-      await setupMcp(harness);
-      if (readConfig(harness).onboardingSchedulePending) {
-        const config = readConfig(harness);
-        config.syncPolicy.scheduleEnabled = true;
-        delete config.onboardingSchedulePending;
-        writeJSON(configPath(harness), config);
-        installSchedule(harness);
-        scheduleNextRun(harness, config.syncPolicy.intervalHours);
+        generation = (existing.syncGeneration || 0) + 1;
+        updateSavedConfig(harness, (current) => {
+          if (JSON.stringify(current) !== JSON.stringify(existing)) throw new Error("Shifu settings changed. Review setup again.");
+          return { ...current, ...choices.preferences, syncPaused: true, syncGeneration: generation };
+        });
+      } else {
+        await connect(harness, async () => key, choices.preferences, true);
+        generation = readConfig(harness).syncGeneration || 0;
       }
+      try { await setupMcp(harness); }
+      catch { throw new Error("Your connection key is saved, but the coding tool connection could not be completed. Open or update your coding tool, choose Edit selection, review it again and retry. You do not need a new key."); }
+      const config = readConfig(harness);
+      if ((config.syncGeneration || 0) !== generation) throw new Error("Setup was paused or changed. Review and start again.");
+      if (choices.scope.filesEnabled) prepareInputFolder(choices.scope.inputFolder, choices.scope.inputFolder === defaultInputFolder());
+      const policy = normalizedPolicy(config);
+      config.syncAuthorization = controls.createAuthorization(config, choices.scope);
+      if (choices.scope.filesEnabled && config.syncAuthorization.inputFolder !== choices.scope.inputFolder) throw controls.processingError("SHIFU_SCOPE_REQUIRED");
+      config.initialBackfill = choices.scope.history;
+      config.inputFolder = choices.scope.inputFolder || config.inputFolder;
+      config.syncPaused = false;
+      config.syncGeneration = generation + 1;
+      config.syncPolicy = configuredSyncPolicy(config, harness, policy.intervalHours, policy.approvalMode, choices.scheduleEnabled);
+      delete config.onboardingSchedulePending;
+      updateSavedConfig(harness, (current) => {
+        if ((current?.syncGeneration || 0) !== generation || controls.connectionFingerprint(current) !== controls.connectionFingerprint(config)) throw new Error("Setup was paused or changed. Review and start again.");
+        return config;
+      });
+      if (choices.scheduleEnabled) installSchedule(harness); else removeSchedule(harness);
+      scheduleNextRun(harness, 0);
     },
     discover: (cutoff) => {
-      const eligible = selectedSessionSegments(harness, { since: cutoff });
-      const all = selectedSessionSegments(harness, { since: cutoff, includeOlder: true });
+      const config = readConfig(harness);
+      const allowed = (item) => controls.sessionAllowed(config, item);
+      const eligible = selectedSessionSegments(harness, { since: cutoff }).filter(allowed);
+      const all = selectedSessionSegments(harness, { since: cutoff, includeOlder: true }).filter(allowed);
       const bounded = (item) => ({ sessionRef: item.sessionRef, fromTurn: item.fromTurn, throughTurn: Math.min(item.turnCount, require("./source-review.js").completedSourceTurn({ harness }, sourceRecords(harness, item.sessionRef))) });
       const blockedSessions = all.filter((item) => item.fromTurn <= item.turnCount && !eligible.some((candidate) => candidate.sessionRef === item.sessionRef)).map(bounded).filter((item) => item.fromTurn <= item.throughTurn);
       return { sessions: eligible.filter((item) => item.fromTurn <= item.turnCount).map(bounded).filter((item) => item.fromTurn <= item.throughTurn), blocked: blockedSessions.length, blockedSessions };
@@ -3331,7 +4033,7 @@ function onboardingRuntime(harness, { prepareNative } = {}) {
     lock: (action) => withSyncLock(harness, action),
     setupLock: (action) => withSyncLock(`${harness}-onboarding-setup`, action),
     prepareAndSend: async (segment) => {
-      const config = readConfig(harness);
+      const config = currentProcessingConfig(harness, readConfig(harness), segment);
       await reconcilePreparedSession(harness, segment.sessionRef, config, { refresh: true });
       const checkpoint = readState(harness).sessions[segment.sessionRef]?.lastSyncedTurn || 0;
       if (checkpoint >= segment.toTurn) return;
@@ -3348,10 +4050,18 @@ function onboardingRuntime(harness, { prepareNative } = {}) {
 async function main() {
   if (option("--config-root")) process.env.SHIFU_CONFIG_ROOT = path.resolve(option("--config-root"));
   const command = process.argv[2];
+  if (["scheduled-sync", "pending", "prepare", "recover", "onboard"].includes(command)) remainingNativeRequests = MAX_PREPARATIONS_PER_RUN;
   const subCommand = process.argv[3];
   validateSyncOptions(command === "config" && subCommand === "update" ? "config-update" : command === "discover" || command === "session" ? "sessions" : command, (command === "config" && subCommand === "update") || (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)) {
+  if (["sync", "sync-files", "scheduled-sync", "approve", "recover", "prepare"].includes(command)) {
+    const config = readConfig(harness);
+    if (!controls.validAuthorization(config) || config.syncPaused) {
+      if (command === "scheduled-sync") { console.error(config.syncPaused ? "Shifu capture is paused." : "Review and start Shifu sync before scheduled processing."); return; }
+      controls.captureConfig(config);
+    }
+  }
+  if (["sync", "sync-files", "scheduled-sync", "approve", "recover"].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",
     });
@@ -3366,7 +4076,14 @@ async function main() {
     const config = readConfig(harness);
     return require("./cursor-mcp.js").runBridge({ url: requireSafeApiUrl(config.mcpUrl || `${config.apiUrl}/mcp`), credentials: () => mcpHeaders(harness) });
   }
-  if (command === "onboard") return require("./onboarding.js").main(onboardingRuntime(harness), { runId: option("--run"), status: hasFlag("--status"), worker: hasFlag("--worker"), serve: hasFlag("--serve"), helpful: hasFlag("--helpful"), fresh: hasFlag("--new"), abandon: hasFlag("--abandon") });
+  if (command === "onboard") {
+    const saved = readJSON(configPath(harness), null);
+    if (saved && !controls.validAuthorization(saved) && !hasFlag("--status")) setSyncPaused(harness, true);
+    return require("./onboarding.js").main(onboardingRuntime(harness), { runId: option("--run"), status: hasFlag("--status"), worker: hasFlag("--worker"), serve: hasFlag("--serve"), helpful: hasFlag("--helpful"), fresh: hasFlag("--new"), abandon: hasFlag("--abandon") });
+  }
+  if (command === "purge-local") return purgeLocal(harness);
+  if (command === "pause") return setSyncPaused(harness, true);
+  if (command === "resume") return setSyncPaused(harness, false);
   if (command === "install") return install(harness);
   if (command === "connect") return connect(harness);
   if (command === "mcp-setup") return setupMcp(harness);
@@ -3377,13 +4094,15 @@ async function main() {
   if (command === "sync-files") return syncFilesNow(harness);
   if (command === "scheduled-sync") return scheduledSync(harness);
   if (command === "pending") return showPending(harness);
+  if (command === "prepare") return prepareSelectedRange(harness);
+  if (command === "recover") return recoverSelectedSessions(harness);
   if (command === "retry-preparation") return retryPreparation(harness);
   if (command === "approve") return approvePending(harness);
   if (command === "status") return status(harness);
   if (command === "sessions" || command === "discover" || (command === "session" && (subCommand === "discover" || subCommand === "list" || !subCommand || subCommand.startsWith("-")))) return sessions(harness);
   if (command === "review") return review(harness);
   if (command === "review-source") return console.log(JSON.stringify(reviewSourcePacket(harness, option("--session-ref"), numberOption("--from-turn"), numberOption("--to-turn")), null, 2));
-  throw new Error("Use install, connect, mcp-setup, mcp-headers, disconnect, config update, status, sessions, review, review-source, sync, sync-files, pending, retry-preparation, approve, or scheduled-sync.");
+  throw new Error("Use install, connect, mcp-setup, mcp-headers, disconnect, config update, status, sessions, review, review-source, prepare, sync, sync-files, pending, recover, retry-preparation, approve, or scheduled-sync.");
 }
 
 if (require.main === module) {
@@ -3394,4 +4113,4 @@ if (require.main === module) {
     });
 }
 
-module.exports = { onboardingRuntime, setupMcp, olderPackageVersion, updateRecommendedPackage, installPackageVersion, approvalNotificationInvocation, claudeReview, claudeSession, codexReview, codexSession, configPath, configuredSyncPolicy, connect, defaultInputFolder, disconnect, finalAssistantNote, install, installDestination, localSessions, normalizedPolicy, notificationSessionRef, opencodeQuery, opencodeReview, opencodeSessions, payloadForSegment, pendingSegments, prepareV5Payload, preparationPacket, continuityState, flushContinuityAttachments, prepareInputFolder, profileForSegment, readSecret, removeHooks, requireSafeApiUrl, reviewCandidates, reviewSourcePacket, schedulerArtifact, statePath, syncWorkFiles, textIsSafe, unsyncedCodexSessions, validateAIProfileObservation, validateConnection, validateInputFolder, validSyncReceipt, validateApprovalMode, validateIntervalHours, validateSync, workFiles };
+module.exports = { updateSavedConfig, currentProcessingConfig, processingLease, processingFetch, setSyncPaused, scanWorkFiles, onboardingRuntime, postWorkFile, getWorkFileJob, acceptedSegments, reconcilePreparedSession, postSync, sendSync, flushPendingProfiles, drainPendingQueue, withSyncLock, setupMcp, olderPackageVersion, updateRecommendedPackage, installPackageVersion, approvalNotificationInvocation, claudeReview, claudeSession, codexReview, codexSession, configPath, configuredSyncPolicy, connect, defaultInputFolder, disconnect, finalAssistantNote, install, installDestination, localSessions, normalizedPolicy, notificationSessionRef, opencodeQuery, opencodeReview, opencodeSessions, payloadForSegment, pendingSegments, prepareSelectedRange, prepareV5Payload, preparationPacket, continuityState, flushContinuityAttachments, prepareInputFolder, profileForSegment, readSecret, removeHooks, requireSafeApiUrl, reviewCandidates, reviewSourcePacket, schedulerArtifact, statePath, syncWorkFiles, textIsSafe, unsyncedCodexSessions, validateAIProfileObservation, validateConnection, validateInputFolder, validSyncReceipt, validateApprovalMode, validateIntervalHours, validateSync, workFiles };