@useshifu/coding-harness 0.3.29 → 0.3.31

package/bin/shifu-harness.js

@@ -19,6 +19,7 @@ const HARNESS_NAMES = {
   codex: "Codex",
   claude_code: "Claude Code",
   opencode: "OpenCode",
+  cursor: "Cursor",
 };
 const TOKEN_PATTERN = /^cs_sk_[a-f0-9]{16}_[a-f0-9]{64}$/;
 const SENSITIVE_PATTERNS = ["-----begin", "authorization", "sk-", "sk_", "ghp_", "gho_", "ghu_", "ghs_", "ghr_", "xox", "github_pat_", "glpat-", "ignore previous instructions", "ignore all previous instructions", "system prompt", "@", "://", "`", "/"];
@@ -46,7 +47,7 @@ const MAX_TURNS_PER_SEGMENT = 12;
 const MAX_TITLE_LENGTH = 160;
 const MAX_WORK_DETAIL_LENGTH = 600;
 const CONFIG_VERSION = 2;
-const RUNNER_VERSION = "0.3.29";
+const RUNNER_VERSION = "0.3.31";
 const REDACTION_VERSION = 5;
 const LEGACY_REDACTION_VERSION = 4;
 const MAX_PREPARATIONS_PER_RUN = 4;
@@ -180,8 +181,9 @@ function openCodeDatabaseQuery(dbPath, query) {
   if (tables.length !== 2) return read(query);
   // V2 stores typed messages, ordered by sequence, instead of separate parts.
   // Read-only CTEs retain the existing adapter contract without changing its database.
+  const hasDirectory = read("PRAGMA table_info(session_v2)").some((column) => column.name === "directory");
   const projection = `WITH
-    session AS (SELECT id, time_created, time_updated FROM session_v2),
+    session AS (SELECT id, time_created, time_updated, ${hasDirectory ? "directory" : "NULL AS directory"} FROM session_v2),
     message AS (
       SELECT id, session_id, seq, time_created, json_object(
         'role', type, 'finish', CASE WHEN json_extract(data, '$.time.completed') IS NOT NULL THEN json_extract(data, '$.finish') END,
@@ -211,7 +213,12 @@ function opencodeSessions(rows) {
   return [...sessions.values()];
 }
 
+function cursorOptions() {
+  return { journalRoot: path.join(configRoot(), "cursor-capture") };
+}
+
 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"));
@@ -219,7 +226,7 @@ function localSessions(harness) {
 }
 
 function requireHarness(value) {
-  if (!Object.hasOwn(HARNESS_NAMES, value)) throw new Error("Choose --harness codex, claude_code, or opencode.");
+  if (!Object.hasOwn(HARNESS_NAMES, value)) throw new Error("Choose --harness codex, claude_code, opencode, or cursor.");
   return value;
 }
 
@@ -244,12 +251,15 @@ function validateSyncOptions(command, start = 3) {
     "sync-files": common,
     "scheduled-sync": common,
     pending: common,
+    "retry-preparation": [...common, "--session-ref", "--from-turn"],
     approve: common,
     install: common,
     connect: [...common, ...setup, ...syncSettings, "--api-url"],
     "config-update": [...common, ...setup, ...syncSettings],
     "mcp-setup": [...common, ...setup, "--mcp-url", "--api-url"],
     "mcp-headers": common,
+    "mcp-bridge": common,
+    "cursor-hook": common,
   };
   const flags = {
     connect: ["--interactive", "--non-interactive"], "mcp-setup": ["--interactive", "--non-interactive"], "config-update": ["--interactive", "--non-interactive"],
@@ -296,6 +306,7 @@ function writeJSON(file, value) {
 }
 
 function readConfig(harness) {
+  if (fs.existsSync(path.join(configRoot(), `${harness}-connection-transition.json`))) throw new Error("An interrupted connection replacement is held locally. Run connect again with the selected connection before syncing.");
   const config = readJSON(configPath(harness), undefined);
   if (!config || typeof config.token !== "string" || typeof config.apiUrl !== "string") {
     throw new Error(`No ${HARNESS_NAMES[harness]} connection is configured. Run connect first.`);
@@ -305,6 +316,7 @@ function readConfig(harness) {
 }
 
 function environmentSessionRef(harness) {
+  if (harness === "cursor") return process.env.SHIFU_CURSOR_SESSION_REF;
   return harness === "codex" ? process.env.CODEX_THREAD_ID || process.env.CODEX_SESSION_ID :
     harness === "claude_code" ? process.env.CLAUDE_CODE_SESSION_ID : process.env.OPENCODE_SESSION_ID;
 }
@@ -614,6 +626,11 @@ function opencodeReview(sessionRef, fromTurn, toTurn) {
 }
 
 function reviewSegment(harness, sessionRef, fromTurn, toTurn) {
+  if (harness === "cursor") {
+    const records = sourceRecords(harness, sessionRef);
+    const { turnCount, sources } = require("./cursor-sessions.js").sources({ sessionRef, fromTurn, toTurn }, records);
+    return { sessionRef, turnCount, notes: sources.filter((source) => source.role === "assistant").map((source) => ({ turn: source.turn, note: source.content })) };
+  }
   if (harness === "opencode") return opencodeReview(sessionRef, fromTurn, toTurn);
   const selectedFile = sessionFile(harness, sessionRef);
   return harness === "codex" ? codexReview(selectedFile, fromTurn, toTurn) : claudeReview(selectedFile, fromTurn, toTurn);
@@ -630,6 +647,7 @@ function reviewSourcePacket(harness, sessionRef, fromTurn, toTurn, scheduled = f
 }
 
 function sourceRecords(harness, sessionRef) {
+  if (harness === "cursor") return require("./cursor-sessions.js").sourceRecords(sessionRef, cursorOptions());
   if (harness === "opencode") {
     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`);
   }
@@ -1078,7 +1096,11 @@ function canonicalThinking(value) {
 
 function localProfileTurns(harness, segment) {
   const turns = [];
-  if (harness === "opencode") {
+  if (harness === "cursor") {
+    const records = sourceRecords(harness, segment.sessionRef);
+    const sources = require("./cursor-sessions.js").sources({ ...segment, fromTurn: 1 }, records).sources;
+    for (const source of sources.filter((source) => source.role === "user")) turns.push({ turn: source.turn, text: source.content });
+  } else if (harness === "opencode") {
     const rows = opencodeQuery(`SELECT m.id AS messageId, json_extract(m.data, '$.role') AS role, json_extract(m.data, '$.modelID') AS model, p.data AS part FROM message m LEFT JOIN part p ON p.message_id = m.id WHERE m.session_id = ${JSON.stringify(segment.sessionRef)} ORDER BY m.time_created, p.id`);
     let lastMessage;
     let turn = 0;
@@ -1186,8 +1208,8 @@ function selectedSessionSegments(harness, { hours = 24, turns = MAX_TURNS_PER_SE
   }
   return [...sessions.values()]
     .sort((left, right) => count === undefined
-      ? left.updatedAt.localeCompare(right.updatedAt)
-      : right.updatedAt.localeCompare(left.updatedAt) || left.sessionRef.localeCompare(right.sessionRef))
+      ? String(left.updatedAt || "").localeCompare(String(right.updatedAt || ""))
+      : String(right.updatedAt || "").localeCompare(String(left.updatedAt || "")) || left.sessionRef.localeCompare(right.sessionRef))
     .slice(0, count ?? Infinity)
     .map(({ turnTimes, ...session }) => {
       const checkpoint = state.sessions[session.sessionRef]?.lastSyncedTurn || 0;
@@ -1213,7 +1235,7 @@ function pendingSegments(harness, state = readState(harness)) {
   const segments = [];
   for (const session of localSessions(harness)
     .filter((candidate) => !excluded.has(candidate.sessionRef))
-    .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt))) {
+    .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));
@@ -1273,7 +1295,7 @@ function copyRunner() {
     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"]) {
+  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", "continuity-preparation.js", "continuity-state.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)) {
@@ -1333,6 +1355,7 @@ function removeCodexHooks() {
 }
 
 function installDestination(harness) {
+  if (harness === "cursor") return path.join(require("./cursor-config.js").cursorHome(), "skills", "shifu-sync");
   if (harness === "codex") return path.join(codexHome(), "skills", "shifu-sync");
   if (harness === "claude_code") return path.join(claudeHome(), "skills", "shifu-sync");
   return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "opencode", "skills", "shifu-sync");
@@ -1382,6 +1405,7 @@ function install(harness, quiet = false, preferences = readJSON(configPath(harne
     fs.appendFileSync(syncFile, `\n## ${HARNESS_NAMES[harness]} context connection\n\nAfter connecting ${HARNESS_NAMES[harness]}, run \`"${process.execPath}" "${installedRunnerPath()}" mcp-setup --harness ${harness}\` to configure Shifu context and memory tools with the saved key. Use \`--mcp-url\` when the user supplied a branch endpoint. If the endpoint is not deployed, report that limitation while leaving sync connected. Reload ${HARNESS_NAMES[harness]} or start a new chat after successful setup. Follow the installed shifu-context skill for context and memory use.\n`);
     if (!quiet) refreshManagedContextInstructions(harness, preferences);
   }
+  if (harness === "cursor") require("./cursor-config.js").configureHooks(installedRunnerPath(), path.resolve(configRoot()));
   const removedHooks = harness === "codex" && removeCodexHooks();
   if (!quiet) {
     printWelcome({ harness, upgraded });
@@ -1557,7 +1581,7 @@ async function connect(harness, readKey = readSecret, choices) {
   const token = (await readKey()).trim();
   if (!TOKEN_PATTERN.test(token)) throw new Error("The connection key is invalid.");
   const apiUrl = requireSafeApiUrl(option("--api-url") || existing?.apiUrl || process.env.SHIFU_API_URL || DEFAULT_API_URL);
-  await validateConnection(apiUrl, token, harness);
+  const connectionInfo = await validateConnection(apiUrl, token, harness);
   const savedPolicy = existing && normalizedPolicy(existing);
   const currentPolicy = savedPolicy?.onboardingComplete ? savedPolicy : { intervalHours: DEFAULT_INTERVAL_HOURS, approvalMode: "automatic", excludedSessionRefs: savedPolicy?.excludedSessionRefs || [] };
   const selected = await chooseSyncPolicy(currentPolicy);
@@ -1570,15 +1594,17 @@ async function connect(harness, readKey = readSecret, choices) {
   install(harness, true, choices.contextPreferences);
   const scheduleFile = scheduleEnabled ? installSchedule(harness) : undefined;
   if (!scheduleEnabled && savedPolicy?.scheduleEnabled) removeSchedule(harness);
-  writeJSON(configPath(harness), { ...existing, ...choices, version: CONFIG_VERSION, apiUrl, token, harness, syncPolicy, inputFolder });
-  refreshManagedContextInstructions(harness, choices.contextPreferences);
-  if (refreshContextKey) writePrivateText(openCodeTokenPath(), token);
-  if (existing?.token && existing.token !== token) {
-    for (const file of [statePath(harness), pendingPath(harness)]) {
-      try { fs.unlinkSync(file); } catch (error) { if (error?.code !== "ENOENT") throw error; }
-    }
-  }
-  scheduleNextRun(harness, syncPolicy.intervalHours);
+  const connection = { ...existing, ...choices, version: CONFIG_VERSION, apiUrl, token, harness, syncPolicy, inputFolder, capabilities: connectionInfo.capabilities || {} };
+  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);
+    refreshManagedContextInstructions(harness, choices.contextPreferences);
+    if (refreshContextKey) writePrivateText(openCodeTokenPath(), token);
+    const continuity = continuityState(harness, connection);
+    continuity.load(); continuity.dictionary();
+    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.");
   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(", ")}.`);
@@ -1938,6 +1964,7 @@ function readContextInstructionFile(file) {
 }
 
 function contextInstructionFile(harness) {
+  if (harness === "cursor") return path.join(configRoot(), "cursor-context.md");
   if (harness === "codex") {
     const override = path.join(codexHome(), "AGENTS.override.md");
     if (readContextInstructionFile(override).original.trim()) return override;
@@ -2021,7 +2048,7 @@ async function setupMcp(harness) {
   printSetupIntro();
   const choices = await onboardingOptions(readJSON(configPath(harness), undefined));
   const instructions = prepareContextInstructions(harness, choices.contextPreferences);
-  const helper = harness === "opencode" ? undefined : helperCommand(harness);
+  const helper = ["opencode", "cursor"].includes(harness) ? undefined : helperCommand(harness);
   if (fs.existsSync(configPath(harness)) && !fs.lstatSync(configPath(harness)).isFile()) {
     throw new Error(`The saved ${HARNESS_NAMES[harness]} connection must be a regular private file, not a link.`);
   }
@@ -2038,7 +2065,7 @@ async function setupMcp(harness) {
   if (!TOKEN_PATTERN.test(config.token)) throw new Error(`The saved ${HARNESS_NAMES[harness]} connection key is invalid. Run connect again.`);
   await validateConnection(config.apiUrl, config.token, harness);
   const tools = await verifyMcp(mcpUrl, config.token);
-  const prepared = harness === "codex" ? prepareCodexMcpConfig(mcpUrl, helper) : harness === "opencode" ? prepareOpenCodeMcpConfig(mcpUrl) : prepareClaudeMcpConfig(mcpUrl, helper);
+  const prepared = harness === "cursor" ? require("./cursor-config.js").prepareMcp(path.resolve(installedRunnerPath()), path.resolve(configRoot())) : harness === "codex" ? prepareCodexMcpConfig(mcpUrl, helper) : harness === "opencode" ? prepareOpenCodeMcpConfig(mcpUrl) : prepareClaudeMcpConfig(mcpUrl, helper);
   if (!unchangedMcpConfig(prepared)) {
     throw new Error(`${HARNESS_NAMES[harness]} configuration changed during setup. Run mcp-setup again to preserve those changes.`);
   }
@@ -2068,6 +2095,11 @@ function disconnect(harness) {
   if (fs.existsSync(lockPath(harness))) throw new Error("A Shifu sync is running. Try disconnecting again after it finishes.");
   if (harness === "opencode" && (config.mcpUrl || fs.existsSync(openCodeTokenPath()))) removeOpenCodeMcpConfig(config.mcpConfigMajor);
   if (harness === "claude_code" && config.mcpUrl) removeClaudeMcpConfig(config.mcpHeadersHelper || helperCommand("claude_code"));
+  if (harness === "cursor") {
+    const cursor = require("./cursor-config.js");
+    cursor.removeMcp(path.resolve(installedRunnerPath()), path.resolve(configRoot()));
+    cursor.configureHooks(installedRunnerPath(), path.resolve(configRoot()), true);
+  }
   removeSchedule(harness);
   for (const file of [configPath(harness), statePath(harness), pendingPath(harness)]) {
     try { fs.unlinkSync(file); } catch (error) { if (error?.code !== "ENOENT") throw error; }
@@ -2217,10 +2249,11 @@ function retryDelay(response, attempt) {
   return Math.min(base * (2 ** attempt), 30_000);
 }
 
-async function postSync(config, input) {
+async function postSync(config, input, beforeAttempt, onPermanentFailure) {
   const body = JSON.stringify(input.force ? { ...input, forceRequestId: randomUUID() } : input);
   let lastError;
   for (let attempt = 0; attempt < MAX_RETRIES; attempt += 1) {
+    beforeAttempt?.();
     let response;
     try {
       response = await fetch(`${config.apiUrl}/v1/connectors/coding-sessions/syncs`, {
@@ -2237,7 +2270,7 @@ async function postSync(config, input) {
     const payload = await response.json().catch(() => undefined);
     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) throw lastError;
+    if (response.status !== 429 && response.status < 500) { onPermanentFailure?.(); throw lastError; }
     if (attempt + 1 < MAX_RETRIES) await sleep(retryDelay(response, attempt));
   }
   throw lastError;
@@ -2446,20 +2479,27 @@ async function sendSync(harness, input, config = readConfig(harness)) {
   validateSync(input, harness);
   const state = readState(harness);
   const checkpoint = state.sessions[input.sessionRef];
+  const store = continuityState(harness, config);
+  const frozen = store.find(input);
   const expected = (checkpoint?.lastSyncedTurn || 0) + 1;
   const force = input.force || Boolean(input.supersedesSyncId);
-  if (!force && input.fromTurn !== expected) throw new Error(`This local checkpoint expects turn ${expected}. Review the pending segment before retrying.`);
+  if (!force && !frozen && input.fromTurn !== expected) throw new Error(`This local checkpoint expects turn ${expected}. Review the pending segment before retrying.`);
   if (force && reviewSegment(harness, input.sessionRef, input.fromTurn, input.toTurn).turnCount < input.toTurn) throw new Error("The original local turns must still exist before force syncing this range.");
-  if (!force) input = queuePayload(harness, input);
+  if (!force && (!frozen || input.toTurn > (checkpoint?.lastSyncedTurn || 0))) input = queuePayload(harness, input);
   let profile;
   if (!force) {
     try { profile = profileForSegment(harness, input); }
     catch { console.error("AI Profile source is unavailable; the prepared activity payload remains retryable."); }
   }
-  const receipt = await postSync(config, input);
-  if (!validSyncReceipt(receipt, input)) {
-    throw new Error("Shifu returned a checkpoint that does not match this reviewed segment. Local state was not advanced.");
+  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);
+    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"; });
+    throw error;
   }
+  if (frozen) store.bind(input, receipt);
   if (profile) {
     state.profilePending ||= {};
     state.profilePending[`${profile.sessionRef}:${profile.fromTurn}:${profile.toTurn}`] = profile;
@@ -2568,27 +2608,108 @@ async function reconcilePreparedSession(harness, sessionRef, config) {
   saveState(harness, state);
 }
 
+function continuityState(harness, config = readConfig(harness)) {
+  return require("./continuity-state.js").continuityStore(configRoot(), harness, config);
+}
+
+function preparationPacket(harness, segment, config) {
+  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 records = sourceRecords(harness, segment.sessionRef);
+  let minimumTurn = Math.max(1, segment.fromTurn - 6);
+  for (let turn = segment.fromTurn - 1; turn >= minimumTurn; turn -= 1) {
+    if (!initialHistoryEligibility(segment, turn, config).eligible) { minimumTurn = turn + 1; break; }
+  }
+  const packet = require("./source-review.js").continuitySourcePacket({ harness, sessionRef: segment.sessionRef, fromTurn: segment.fromTurn, toTurn: segment.toTurn }, records, minimumTurn);
+  let workspace;
+  if (harness === "codex") workspace = records.find((record) => record.type === "session_meta")?.payload?.cwd;
+  else if (harness === "claude_code") workspace = records.find((record) => typeof record.cwd === "string")?.cwd;
+  else if (harness === "cursor") workspace = records.find((record) => typeof record.workspace === "string")?.workspace;
+  else {
+    try { workspace = opencodeQuery(`SELECT directory FROM session WHERE id = ${JSON.stringify(segment.sessionRef)}`)[0]?.directory; }
+    catch { /* No trusted directory means a session-specific scope, never the scheduler workspace. */ }
+  }
+  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 packet = reviewSourcePacket(harness, segment.sessionRef, segment.fromTurn, segment.toTurn, true);
+  const config = readConfig(harness);
+  const store = continuityState(harness, config);
+  const prior = store.load().attempts[`${segment.sessionRef}:${segment.fromTurn}`];
+  if (prior?.payloadKey) {
+    const frozen = store.load().outbox.find((entry) => entry.key === prior.payloadKey);
+    if (!frozen) throw new Error("Frozen preparation is unavailable; continuity needs review.");
+    return frozen.payload;
+  }
+  if (prior?.toTurn) segment = { ...segment, toTurn: prior.toTurn };
+  const { packet, workspace } = preparationPacket(harness, segment, config);
+  const dictionary = store.dictionary();
+  dictionary.scopes[workspace] ||= { scopeRef: `s_${randomUUID().replaceAll("-", "")}`, entities: {} };
+  store.saveDictionary(dictionary);
+  const relevantBindings = () => {
+    const content = [...packet.sources, ...packet.referenceSources].map((source) => source.content).join("\n").toLocaleLowerCase();
+    return Object.values(dictionary.scopes[workspace].entities).filter((entry) => entry.createdBy !== `${packet.sessionRef}:${packet.fromTurn}` && content.includes(entry.mention.toLocaleLowerCase()))
+      .map(({ key, mention, kind }) => ({ bindingRef: key, mention, kind }));
+  };
+  packet.entityBindings = relevantBindings();
+  while (packet.referenceSources.length && Buffer.byteLength(JSON.stringify(packet)) + 1 > 256 * 1024) {
+    const oldest = packet.referenceSources[0].turn;
+    packet.referenceSources = packet.referenceSources.filter((source) => source.turn > oldest);
+    packet.referenceCoverage.limited = true;
+    packet.referenceCoverage.droppedTurns += 1;
+    packet.referenceCoverage.fromTurn = packet.referenceSources[0]?.turn || packet.fromTurn;
+    packet.entityBindings = relevantBindings();
+  }
+  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;
   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.");
-    const output = await prepare(harness, packet, { validationFeedback, timeoutMs: remainingMs });
+    const reservation = store.reservation(packet, bindings);
+    let output;
     try {
-      const payload = require("./v5-payload.js").preparedPayload(packet, output);
-      validateSync(payload, harness);
-      return payload;
+      output = await prepare(harness, packet, { validationFeedback, timeoutMs: remainingMs, continuity: true });
+      const candidateDictionary = structuredClone(dictionary);
+      const result = require("./continuity-preparation.js").bindContinuity(packet, output, candidateDictionary, workspace);
+      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.");
+      store.saveDictionary(candidateDictionary);
+      return store.freeze(packet, result).payload;
     } catch (error) {
-      if (attempt === 1) throw error;
-      // Only local validator diagnostics enter the isolated correction prompt.
-      // Failed model output is never queued, echoed, or sent to Shifu.
+      store.failure(packet);
+      if (reservation.attempt >= 2 || output === undefined) throw error;
       validationFeedback = preparationValidationFeedback(error, output);
     }
   }
 }
 
+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 store = continuityState(harness);
+    const state = store.load();
+    const identity = `${sessionRef}:${fromTurn}`;
+    const held = state.attempts[identity];
+    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;
+    store.save(state);
+    const payload = await prepareV5Payload(harness, { ...session, fromTurn, toTurn: held.toTurn });
+    queuePayload(harness, payload);
+    console.error("The selected preparation is queued for its existing approval and transport policy.");
+  });
+  if (result?.skipped) throw new Error("Another sync is running; the hold was preserved.");
+}
+
 function preparationValidationFeedback(error, output) {
   const fields = [["title", output?.title, 160], ["summary", output?.summary, 1100]];
   for (const name of ["decisions", "verification"]) {
@@ -2631,6 +2752,7 @@ function preparationState(harness, queue) {
 }
 
 async function preparePendingQueue(harness, config, blockedSessions = new Set()) {
+  restoreContinuityQueue(harness, config);
   let queue = prunePendingQueue(harness);
   const previousFailures = new Set((queue.preparationErrors || []).map((error) => error.sessionRef));
   const errors = [];
@@ -2680,8 +2802,13 @@ async function preparePendingQueue(harness, config, blockedSessions = new Set())
 async function drainPendingQueue(harness, config, blockedSessions) {
   let synced = 0;
   let failures = 0;
-  for (const input of eligibleQueuedSegments(readPendingQueue(harness), config)) {
-    if (blockedSessions.has(input.sessionRef)) continue;
+  const store = continuityState(harness, config);
+  const entries = store.load().outbox.filter((entry) => entry.baseStatus !== "needs_review" && (entry.baseStatus !== "accepted" || entry.toTurn > (readState(harness).sessions[entry.sessionRef]?.lastSyncedTurn || 0)));
+  const queued = eligibleQueuedSegments(readPendingQueue(harness), config);
+  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 (blockedSessions.has(input.sessionRef) || store.find(input)?.baseStatus === "needs_review") continue;
     try { await sendSync(harness, input, config); synced += 1; }
     catch (error) {
       failures += 1;
@@ -2692,11 +2819,35 @@ async function drainPendingQueue(harness, config, blockedSessions) {
   return { synced, failures };
 }
 
+async function flushContinuityAttachments(harness, config) {
+  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);
+    capable = connection.capabilities?.continuityAttachment === 1;
+  } catch { /* Base receipts remain valid while capability discovery is unavailable. */ }
+  await require("./continuity-state.js").flushContinuity(store, config, capable);
+}
+
+function restoreContinuityQueue(harness, config) {
+  const queue = readPendingQueue(harness);
+  const state = readState(harness);
+  for (const entry of continuityState(harness, config).load().outbox) {
+    if (entry.toTurn > (state.sessions[entry.sessionRef]?.lastSyncedTurn || 0) && entry.baseStatus !== "needs_review" && !queue.segments.some((payload) => JSON.stringify(payload) === JSON.stringify(entry.payload))) queuePayload(harness, entry.payload);
+  }
+}
+
 function eligibleQueuedSegments(queue, config) {
   const excluded = new Set(normalizedPolicy(config).excludedSessionRefs);
   return queue.segments.filter((input) => !excluded.has(input.sessionRef));
 }
 
+function continuityRecoveries(harness, config, queued) {
+  const excluded = new Set(normalizedPolicy(config).excludedSessionRefs);
+  return continuityState(harness, config).load().outbox.filter((entry) => entry.baseStatus === "awaiting_receipt" && !excluded.has(entry.sessionRef) && !queued.some((payload) => JSON.stringify(payload) === JSON.stringify(entry.payload))).map((entry) => entry.payload);
+}
+
 function approvalNotificationInvocation(harness, count, sessionRef) {
   const prompt = `Shifu sync approval: ${count} redacted segment${count === 1 ? " is" : "s are"} waiting locally. Tell the user to ask you to show the pending Shifu sync and approve it once. Do not inspect files, run tools, or sync anything in this session.`;
   if (harness === "codex") {
@@ -2726,6 +2877,12 @@ function notificationSessionRef(output) {
 }
 
 function notifyManualApproval(harness, count, existingSessionRef) {
+  if (harness === "cursor") {
+    const message = `${count} redacted work summaries are waiting. Ask Cursor to show pending Shifu sync and approve it once.`;
+    if (process.platform === "darwin") execFileSync("osascript", ["-e", `display notification ${JSON.stringify(message)} with title "Shifu sync approval"`], { stdio: "ignore", timeout: 10_000 });
+    else execFileSync("notify-send", ["Shifu sync approval", message], { stdio: "ignore", timeout: 10_000 });
+    return "thread_cursor_approval";
+  }
   const invocation = approvalNotificationInvocation(harness, count, existingSessionRef);
   const { resolveNativeBinary, nativeEnvironment } = require("./native-preparation.js");
   const before = existingSessionRef ? new Set() : new Set(localSessions(harness).map((session) => session.sessionRef));
@@ -2740,7 +2897,7 @@ function notifyManualApproval(harness, count, existingSessionRef) {
   if (existingSessionRef) return existingSessionRef;
   const created = notificationSessionRef(output) || localSessions(harness)
     .filter((session) => !before.has(session.sessionRef))
-    .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0]?.sessionRef;
+    .sort((left, right) => String(right.updatedAt || "").localeCompare(String(left.updatedAt || "")))[0]?.sessionRef;
   if (!created) throw new Error("The approval session was created but its session reference could not be recorded safely.");
   return created;
 }
@@ -2748,7 +2905,9 @@ function notifyManualApproval(harness, count, existingSessionRef) {
 async function showPending(harness) {
   const config = readConfig(harness);
   const result = await withSyncLock(harness, async () => {
-    console.log(JSON.stringify(await preparePendingQueue(harness, config), null, 2));
+    const queue = await preparePendingQueue(harness, config);
+    queue.segments = [...eligibleQueuedSegments(queue, config), ...continuityRecoveries(harness, config, queue.segments)];
+    console.log(JSON.stringify(queue, null, 2));
   });
   if (result?.skipped) throw new Error("Another Shifu sync is already preparing this queue. Retry later.");
 }
@@ -2756,18 +2915,21 @@ async function showPending(harness) {
 async function approvePending(harness) {
   const config = readConfig(harness);
   const result = await withSyncLock(harness, async () => {
+    restoreContinuityQueue(harness, config);
     const queue = prunePendingQueue(harness);
     queue.segments = eligibleQueuedSegments(queue, config);
-    if (queue.segments.length === 0) {
+    const recoveries = continuityRecoveries(harness, config, queue.segments);
+    if (queue.segments.length === 0 && recoveries.length === 0) {
       console.error("There is no prepared Shifu activity to approve. Run pending to prepare the next ranges.");
       return;
     }
-    console.error(`\nThese ${queue.segments.length} redacted segment(s) will be sent to Shifu:\n${JSON.stringify(queue.segments, null, 2)}`);
+    console.error(`\nThese ${queue.segments.length + recoveries.length} redacted segment(s) will be sent to Shifu:\n${JSON.stringify([...queue.segments, ...recoveries], null, 2)}`);
     if (!hasFlag("--approved") && !(await confirm("Approve all pending segments"))) {
       console.error("Nothing was sent. The prepared queue is unchanged.");
       return;
     }
     const sent = await drainPendingQueue(harness, config, new Set());
+    await flushContinuityAttachments(harness, config);
     if (sent.failures) throw new Error("Some approved segments could not be acknowledged. Their exact payloads remain pending for retry.");
   });
   if (result?.skipped) throw new Error("Another Shifu sync is already running. Nothing was sent; retry later.");
@@ -2800,9 +2962,12 @@ async function scheduledSync(harness) {
       }
     }
     await flushPendingProfiles(harness, config);
+    restoreContinuityQueue(harness, config);
+    await flushContinuityAttachments(harness, config);
     if (policy.approvalMode === "manual") {
       const queue = await preparePendingQueue(harness, config);
-      const eligible = eligibleQueuedSegments(queue, config);
+      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");
       const changed = state.schedule?.pendingFingerprint !== pendingFingerprint;
       let approvalSessionRef = state.schedule?.approvalSessionRef;
@@ -2860,6 +3025,7 @@ async function scheduledSync(harness) {
         nextRunAt: Date.now() + (failures || failedFiles || pendingProfiles || remaining ? SCHEDULER_TICK_MINUTES / 60 : policy.intervalHours) * 3_600_000,
       };
     }
+    await flushContinuityAttachments(harness, config);
     const latest = readState(harness);
     latest.schedule = state.schedule;
     saveState(harness, latest);
@@ -2890,7 +3056,7 @@ function status(harness) {
       if (!eligibility.eligible) initialHistoryBlocked.push({ sessionRef: session.sessionRef, reason: eligibility.reason, cutoffAt: eligibility.cutoffAt });
     }
   }
-  console.log(JSON.stringify({ 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({ 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));
 }
 
 async function syncFilesNow(harness) {
@@ -3025,7 +3191,7 @@ async function review(harness) {
   const state = readState(harness);
   let fromTurn = (state.sessions[sessionRef]?.lastSyncedTurn || 0) + 1;
   const selected = localSessions(harness).filter((session) => session.sessionRef === sessionRef)
-    .sort((left, right) => right.turnCount - left.turnCount || right.updatedAt.localeCompare(left.updatedAt))[0];
+    .sort((left, right) => right.turnCount - left.turnCount || String(right.updatedAt || "").localeCompare(String(left.updatedAt || "")))[0];
   if (!selected) throw new Error(`No local ${HARNESS_NAMES[harness]} session matches this reference.`);
   const hours = syncWindowHours();
   const turns = numberOption("--turns", MAX_TURNS_PER_SEGMENT);
@@ -3104,6 +3270,25 @@ async function updateRecommendedPackage(harness, { currentVersion = RUNNER_VERSI
   }
 }
 
+async function cursorHook() {
+  if (process.env.SHIFU_CURSOR_PREPARATION === "1" || !fs.existsSync(configPath("cursor"))) return console.log("{}");
+  let input = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) {
+    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);
+  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());
+  console.log("{}");
+}
+
 async function main() {
   if (option("--config-root")) process.env.SHIFU_CONFIG_ROOT = path.resolve(option("--config-root"));
   const command = process.argv[2];
@@ -3120,6 +3305,11 @@ async function main() {
     });
     return;
   }
+  if (command === "cursor-hook" && harness === "cursor") return cursorHook();
+  if (command === "mcp-bridge" && harness === "cursor") {
+    const config = readConfig(harness);
+    return require("./cursor-mcp.js").runBridge({ url: requireSafeApiUrl(config.mcpUrl || `${config.apiUrl}/mcp`), credentials: () => mcpHeaders(harness) });
+  }
   if (command === "install") return install(harness);
   if (command === "connect") return connect(harness);
   if (command === "mcp-setup") return setupMcp(harness);
@@ -3130,21 +3320,21 @@ 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 === "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, approve, or scheduled-sync.");
+  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.");
 }
 
 if (require.main === module) {
   main()
-    .then(() => process.exit(0))
     .catch((error) => {
       console.error(error.message);
-      process.exit(1);
+      process.exitCode = 1;
     });
 }
 
-module.exports = { 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, prepareInputFolder, profileForSegment, readSecret, removeHooks, requireSafeApiUrl, reviewCandidates, reviewSourcePacket, schedulerArtifact, statePath, syncWorkFiles, textIsSafe, unsyncedCodexSessions, validateAIProfileObservation, validateConnection, validateInputFolder, validSyncReceipt, validateApprovalMode, validateIntervalHours, validateSync, workFiles };
+module.exports = { 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 };