@useshifu/coding-harness 0.2.7 → 0.3.0

package/README.md

@@ -1,33 +1,44 @@
 # Shifu coding-harness connector
 
-`@useshifu/coding-harness` connects Codex, Claude Code, or OpenCode to Shifu through reviewed, incremental summaries. It never uploads raw transcripts or syncs in the background.
+`@useshifu/coding-harness` connects Codex, Claude Code, or OpenCode to Shifu. It reads local final-assistant notes, never user prompts or raw transcripts, and sends incremental redacted activity through durable checkpoints. Unattended runs emit controlled use-case labels rather than copying source prose.
+
+## Connect
 
 ```sh
-npx @useshifu/coding-harness install --harness codex
-npx @useshifu/coding-harness connect --harness codex
+npx @useshifu/coding-harness connect --harness <codex|claude_code|opencode>
 ```
 
-`connect` and `sync` each ask for confirmation. The connector has no lifecycle hooks and never uploads in the background. Codex, Claude Code, and OpenCode support local time-window discovery and review. Claude Code discovery reads local sessions under `~/.claude/projects`; review surfaces assistant text for inspection, never raw prompts or tool results.
+Connect installs the local instruction and scheduled runner, saves the connection key with owner-only permissions, and asks for two setup choices:
+
+- sync interval: four hours by default, configurable from 0.25 to 720 hours;
+- approval mode: automatic by default, or manual for one approval covering the accumulated queue.
 
-When asked to sync, Codex, Claude Code, and OpenCode discover unsynced user turns from the last 24 hours by default. A user can choose 48 or 72 hours instead. Discovery reports only opaque session references, timestamps, and unsynced turn ranges; it does not send transcript content. `blockedSessions` lists recently changed sessions whose next unsynced turn is older than the chosen window. Those older contiguous backlogs are not silently included; the user can explicitly select a session and review it with `--all`.
+No session content is sent during setup. Re-running `connect` on an older installation keeps its key and checkpoints and completes the missing onboarding. Change the choices later with:
 
 ```sh
-npx @useshifu/coding-harness sessions --harness <codex|claude_code|opencode> --hours 24
-npx @useshifu/coding-harness review --harness <codex|claude_code|opencode> --session-ref opaque-session-id
+npx @useshifu/coding-harness config update --harness <codex|claude_code|opencode>
 ```
 
-`review` reads the next contiguous segment of at most 12 unsynced turns locally. Pass the selected `--hours` value to `review` as well; `--all` is reserved for a specifically selected session's older backlog. It shows assistant final notes, candidate work items, and a draft that leaves required sync and work-item titles blank for the reviewer. Candidates are suggestions, not proof or guaranteed redaction. Candidate scope is left unset until a reviewer chooses the smallest supported level. If a segment has more than 64 candidates, rerun `sessions` and `review` with `--turns 1` to narrow it before syncing. Review each work title, detail, and area, prepare any verification, and preserve an item's `itemRef` when a later segment revises the same work. User-message records are omitted, but assistant notes may quote sensitive material. Nothing is uploaded by this command. Repeat discovery after each accepted segment to continue the delta.
+Older configuration files remain on-demand and manual until either command completes onboarding; upgrading the package alone never enables background upload.
 
-To submit a reviewed segment, pipe the exact payload to `sync`. The CLI prints it, asks again, and only then sends it to Shifu. Successful responses advance a local checkpoint; the server rejects out-of-order or changed retries.
+## Operate
 
 ```sh
-printf '%s' '{"harness":"codex","sessionRef":"opaque-session-id","fromTurn":1,"toTurn":8,"title":"Hardened connector checkpoints","summary":"Implemented a focused change and checked the result.","evidence":[{"kind":"implementation","title":"Added checkpoint recovery","statement":"Implemented a focused connector change.","scope":"service","area":"connector","itemRef":"work_1","verificationRefs":[0]}],"verification":["Focused tests passed."],"decisions":[],"redactionVersion":3}' | npx @useshifu/coding-harness sync --harness codex
+npx @useshifu/coding-harness status --harness codex
+npx @useshifu/coding-harness sessions --harness codex --hours 24
+npx @useshifu/coding-harness review --harness codex --session-ref opaque-session-id
+npx @useshifu/coding-harness pending --harness codex
+npx @useshifu/coding-harness approve --harness codex
 ```
 
-The server stores each approved sync title and summary, plus every redacted work-item title and statement as a separate claim with its scope, optional area and item reference, cited verification, and source receipt. Uncited verification wording, standalone decisions, raw assistant notes, and transcripts are not retained as claim text. `area`, `itemRef`, and `verificationRefs` are optional; citing a verification item applies only to that work item and is displayed separately from its work statement. A decision becomes a claim only when it is included as an `evidence` item with `kind: "decision"`. At least one reviewed work item is required to advance a checkpoint. The complete cross-component contract is in [coding-session-sync-contract.md](../../docs/coding-session-sync-contract.md).
+Automatic scheduled runs send each accepted segment and advance its local checkpoint only after the server returns a matching receipt. Manual scheduled runs rebuild an accumulated local queue without advancing checkpoints and create or resume one content-free harness session when the pending count changes; one approval sends the queue in order. Network failures and server throttling are retried, while rejected segments stay pending.
+
+The connector captures any useful harness activity, including engineering, product discovery, writing, interview feedback, research, and planning. Version-four payloads support generic `activity` items without a technical scope and accept a safe session-level summary when no item survives redaction. Version 1–3 clients remain supported.
 
-## Review quality
+## Sync a prepared payload
 
-Write each sync as a concise technical record that will remain useful after the raw session is unavailable. Separate architecture, implementation, security controls, rollout, and user-facing work when they have distinct boundaries. Describe the mechanism, boundary, and material constraint for each item; state known limits plainly. Put material architecture, security, and rollout choices in `decision` evidence if they should become claims. Keep tests and operational checks in `verification`, citing them from the work item they support. Do not claim impact, ownership, or outcomes without direct support.
+```sh
+printf '%s' '{"harness":"codex","sessionRef":"opaque-session-id","fromTurn":1,"toTurn":3,"title":"Prepared structured interview feedback","summary":"Prepared structured interview feedback and clarified the recommendation.","evidence":[{"kind":"activity","title":"Drafted interview feedback","statement":"Prepared structured interview feedback."}],"verification":[],"decisions":[],"redactionVersion":4}' | npx @useshifu/coding-harness sync --harness codex
+```
 
-The default API URL is `https://api.useshifu.com`. Override it during local or self-hosted use with `--api-url` on `connect`, or `SHIFU_API_URL`.
+Automatic mode sends immediately. Manual mode asks once unless the calling harness already obtained approval and passes `--approved`.

package/bin/shifu-harness.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 const fs = require("node:fs");
+const { createHash } = require("node:crypto");
 const os = require("node:os");
 const path = require("node:path");
 const { execFileSync } = require("node:child_process");
@@ -21,7 +22,7 @@ const UNSAFE_SESSION_REF_PATTERNS = ["api_key", "authorization", "password", "@"
 const UNSAFE_CODE_PATTERN = /\b(?:func|class|interface|struct|package|import|select|insert|update|delete|create\s+table)\s+[a-z_][a-z0-9_]*\s*(?:\(|\{|=|$)/i;
 const CREDENTIAL_ASSIGNMENT_PATTERN = /\b(?:token|secret|password|api[_-]?key)\s*[:=]\s*\S+/i;
 const CLOUD_CREDENTIAL_PATTERN = /\bAKIA[0-9A-Z]{16}\b|AIza[0-9A-Za-z_-]{20,}/;
-const EVIDENCE_KINDS = new Set(["implementation", "decision"]);
+const EVIDENCE_KINDS = new Set(["implementation", "decision", "activity"]);
 const EVIDENCE_FIELDS = new Set(["kind", "title", "statement", "scope", "area", "itemRef", "verificationRefs"]);
 const SYNC_FIELDS = new Set(["harness", "sessionRef", "fromTurn", "toTurn", "title", "summary", "evidence", "verification", "decisions", "redactionVersion"]);
 const SCOPE_LEVELS = new Set(["unit", "module", "service", "system", "product"]);
@@ -32,9 +33,16 @@ const MAX_SYNC_ITEMS = 16;
 const MAX_TURNS_PER_SEGMENT = 12;
 const MAX_TITLE_LENGTH = 160;
 const MAX_WORK_DETAIL_LENGTH = 600;
+const CONFIG_VERSION = 2;
+const REDACTION_VERSION = 4;
+const DEFAULT_INTERVAL_HOURS = 4;
+const MIN_INTERVAL_HOURS = 0.25;
+const MAX_INTERVAL_HOURS = 720;
+const SCHEDULER_TICK_MINUTES = 15;
+const MAX_RETRIES = 4;
 
 function configRoot() {
-  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "shifu", "coding-harness");
+  return process.env.SHIFU_CONFIG_ROOT || path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "shifu", "coding-harness");
 }
 
 function configPath(harness) {
@@ -45,6 +53,14 @@ function statePath(harness) {
   return path.join(configRoot(), `${harness}-checkpoints.json`);
 }
 
+function pendingPath(harness) {
+  return path.join(configRoot(), `${harness}-pending.json`);
+}
+
+function lockPath(harness) {
+  return path.join(configRoot(), `${harness}.lock`);
+}
+
 function installedRunnerPath() {
   return path.join(configRoot(), "runner.js");
 }
@@ -165,6 +181,63 @@ function readConfig(harness) {
   return config;
 }
 
+function environmentSessionRef(harness) {
+  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;
+}
+
+function currentSessionRef(harness) {
+  const fromEnvironment = environmentSessionRef(harness);
+  if (sessionRefIsSafe(fromEnvironment)) return fromEnvironment;
+  try {
+    const recent = localSessions(harness).filter((session) => Date.parse(session.updatedAt) >= Date.now() - 5 * 60_000);
+    if (recent.length === 1) return recent[0].sessionRef;
+  } catch {}
+  return undefined;
+}
+
+function normalizedPolicy(config) {
+  const interval = Number(config?.syncPolicy?.intervalHours);
+  const approvalMode = config?.syncPolicy?.approvalMode;
+  const configured = config?.version === CONFIG_VERSION && config.syncPolicy?.onboardingComplete === true &&
+    Number.isFinite(interval) && interval >= MIN_INTERVAL_HOURS && interval <= MAX_INTERVAL_HOURS &&
+    (approvalMode === "automatic" || approvalMode === "manual");
+  return {
+    onboardingComplete: configured,
+    intervalHours: configured ? interval : DEFAULT_INTERVAL_HOURS,
+    approvalMode: configured ? approvalMode : "manual",
+    scheduleEnabled: configured ? config.syncPolicy.scheduleEnabled !== false : false,
+    excludedSessionRefs: Array.isArray(config?.syncPolicy?.excludedSessionRefs) ? config.syncPolicy.excludedSessionRefs.filter(sessionRefIsSafe) : [],
+  };
+}
+
+function validateIntervalHours(value) {
+  const interval = Number(value);
+  if (!Number.isFinite(interval) || interval < MIN_INTERVAL_HOURS || interval > MAX_INTERVAL_HOURS) {
+    throw new Error(`Choose a sync interval between ${MIN_INTERVAL_HOURS} and ${MAX_INTERVAL_HOURS} hours.`);
+  }
+  return interval;
+}
+
+function validateApprovalMode(value) {
+  if (value !== "automatic" && value !== "manual") throw new Error("Choose automatic or manual approval.");
+  return value;
+}
+
+function configuredSyncPolicy(config, harness, intervalHours, approvalMode, scheduleEnabled = true) {
+  const existing = normalizedPolicy(config);
+  const excludedSessionRefs = new Set(existing.excludedSessionRefs);
+  const current = currentSessionRef(harness);
+  if (sessionRefIsSafe(current)) excludedSessionRefs.add(current.trim());
+  return {
+    onboardingComplete: true,
+    intervalHours: validateIntervalHours(intervalHours),
+    approvalMode: validateApprovalMode(approvalMode),
+    scheduleEnabled,
+    excludedSessionRefs: [...excludedSessionRefs],
+  };
+}
+
 function requireSafeApiUrl(value) {
   let url;
   try { url = new URL(value); } catch { throw new Error("Use a valid Shifu API URL."); }
@@ -364,6 +437,16 @@ function opencodeReview(sessionRef, fromTurn, toTurn) {
   return { sessionRef, turnCount: turn, notes };
 }
 
+function reviewSegment(harness, sessionRef, fromTurn, toTurn) {
+  if (harness === "opencode") return opencodeReview(sessionRef, fromTurn, toTurn);
+  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;
+  if (!selectedFile) throw new Error(`No local ${HARNESS_NAMES[harness]} session matches ${sessionRef}.`);
+  return harness === "codex" ? codexReview(selectedFile, fromTurn, toTurn) : claudeReview(selectedFile, fromTurn, toTurn);
+}
+
 function reviewCandidates(notes) {
   const candidates = [];
   const seen = new Set();
@@ -384,13 +467,66 @@ function reviewCandidates(notes) {
   return candidates;
 }
 
+function conciseTitle(statement, fallback) {
+  const value = (statement || fallback).trim();
+  if (value.length <= MAX_TITLE_LENGTH) return value;
+  return `${value.slice(0, MAX_TITLE_LENGTH - 1).trimEnd()}…`;
+}
+
+const ACTIVITY_CATEGORIES = [
+  { key: "interview_feedback", title: "Interview feedback", pattern: /\b(?:interview|candidate|hiring feedback)\b/i },
+  { key: "professional_writing", title: "Professional writing", pattern: /\b(?:linkedin|social post|article|newsletter|professional post|writing)\b/i },
+  { key: "product_discovery", title: "Product discovery", pattern: /\b(?:product discovery|user research|customer research|requirements?|roadmap)\b/i },
+  { key: "product_delivery", title: "Product and design delivery", pattern: /\b(?:landing page|website|user interface|user experience|design|prototype)\b/i },
+  { key: "research", title: "Research", pattern: /\b(?:research|investigat|compar|evaluat|analysis|analyz)\w*/i },
+  { key: "planning", title: "Planning", pattern: /\b(?:plan|strategy|prioriti|proposal|brief)\w*/i },
+  { key: "documentation", title: "Documentation", pattern: /\b(?:documentation|readme|guide|runbook)\b/i },
+  { key: "engineering", title: "Engineering", pattern: /\b(?:implement|code|bug|fix|test|api|database|frontend|backend|refactor|deploy)\w*/i },
+];
+
+function safeActivityEvidence(notes, segment) {
+  const source = notes.map((note) => note.note).join("\n");
+  const categories = ACTIVITY_CATEGORIES.filter((category) => category.pattern.test(source));
+  if (categories.length === 0) return [];
+  return categories.map((category, index) => ({
+    kind: "activity",
+    title: category.title,
+    statement: `Used the harness for ${category.title.toLowerCase()}.`,
+    itemRef: `t${segment.fromTurn}_${category.key}_${index + 1}`,
+  }));
+}
+
+function payloadForSegment(harness, segment) {
+  const { notes } = reviewSegment(harness, segment.sessionRef, segment.fromTurn, segment.toTurn);
+  const fallback = `${HARNESS_NAMES[harness]} activity across turns ${segment.fromTurn}–${segment.toTurn}.`;
+  const evidence = safeActivityEvidence(notes, segment).slice(0, MAX_EVIDENCE_ITEMS);
+  const title = evidence.length === 1 ? evidence[0].title : evidence.length > 1 ? "Multiple harness activities" : fallback;
+  const summary = evidence.length ? `Used ${HARNESS_NAMES[harness]} for ${evidence.map((item) => item.title.toLowerCase()).join(", ")}.` : fallback;
+  return {
+    harness,
+    sessionRef: segment.sessionRef,
+    fromTurn: segment.fromTurn,
+    toTurn: segment.toTurn,
+    title: conciseTitle(title, fallback),
+    summary,
+    evidence,
+    verification: [],
+    decisions: [],
+    redactionVersion: REDACTION_VERSION,
+  };
+}
+
 function unsyncedCodexSessions(harness, hours, turns = MAX_TURNS_PER_SEGMENT, selectedRef, includeOlder = false) {
   if (![24, 48, 72].includes(hours)) throw new Error("Choose --hours 24, 48, or 72.");
   if (!Number.isInteger(turns) || turns < 1 || turns > MAX_TURNS_PER_SEGMENT) throw new Error("Choose --turns between 1 and 12.");
   const since = Date.now() - hours * 3_600_000;
   const state = readState(harness);
+  const excluded = new Set(normalizedPolicy(readJSON(configPath(harness), {})).excludedSessionRefs);
+  const controlSession = environmentSessionRef(harness);
+  if (sessionRefIsSafe(controlSession)) excluded.add(controlSession);
   const sessions = new Map();
   for (const session of localSessions(harness)
+    .filter((session) => !excluded.has(session.sessionRef))
     .filter((session) => selectedRef ? session.sessionRef === selectedRef : Date.parse(session.updatedAt) >= since)) {
     const existing = sessions.get(session.sessionRef);
     sessions.set(session.sessionRef, existing ? {
@@ -416,8 +552,33 @@ function unsyncedCodexSessions(harness, hours, turns = MAX_TURNS_PER_SEGMENT, se
     .filter((session) => session.fromTurn <= session.toTurn && (includeOlder || Date.parse(session.oldestUnsyncedAt) >= since));
 }
 
+function pendingSegments(harness) {
+  const state = readState(harness);
+  const policy = normalizedPolicy(readConfig(harness));
+  const excluded = new Set(policy.excludedSessionRefs);
+  const segments = [];
+  for (const session of localSessions(harness)
+    .filter((candidate) => !excluded.has(candidate.sessionRef))
+    .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt))) {
+    let fromTurn = (state.sessions[session.sessionRef]?.lastSyncedTurn || 0) + 1;
+    while (fromTurn <= session.turnCount) {
+      let toTurn = Math.min(session.turnCount, fromTurn + MAX_TURNS_PER_SEGMENT - 1);
+      if (Date.parse(session.updatedAt) > Date.now() - SCHEDULER_TICK_MINUTES * 60_000) {
+        const completedTurns = new Set(reviewSegment(harness, session.sessionRef, fromTurn, toTurn).notes.map((note) => note.turn));
+        let completedTo = fromTurn - 1;
+        while (completedTurns.has(completedTo + 1)) completedTo += 1;
+        if (completedTo < fromTurn) break;
+        toTurn = completedTo;
+      }
+      segments.push({ ...session, fromTurn, toTurn });
+      fromTurn = toTurn + 1;
+    }
+  }
+  return segments;
+}
+
 function prompt() {
-  const input = process.stdin.isTTY ? process.stdin : fs.createReadStream("/dev/tty");
+  const input = process.stdin.isTTY ? process.stdin : fs.createReadStream(process.platform === "win32" ? "CONIN$" : "/dev/tty");
   const terminal = readline.createInterface({ input, output: process.stderr });
   terminal.shifuInput = input;
   return terminal;
@@ -434,9 +595,20 @@ async function confirm(question) {
   }
 }
 
+async function ask(question, fallback) {
+  const terminal = prompt();
+  try {
+    const answer = (await terminal.question(`${question} [${fallback}] `)).trim();
+    return answer || fallback;
+  } finally {
+    terminal.close();
+    if (terminal.shifuInput !== process.stdin) terminal.shifuInput.destroy();
+  }
+}
+
 async function readSecret(input = process.stdin) {
   const ownsInput = !input.isTTY;
-  if (ownsInput) input = new tty.ReadStream(fs.openSync("/dev/tty", "r"));
+  if (ownsInput) input = new tty.ReadStream(fs.openSync(process.platform === "win32" ? "CONIN$" : "/dev/tty", "r"));
   const wasRaw = input.isRaw;
   process.stderr.write("Connection key (hidden): ");
   input.setRawMode(true);
@@ -514,7 +686,7 @@ function installDestination(harness) {
   return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "opencode", "skills", "shifu-sync");
 }
 
-function install(harness) {
+function install(harness, quiet = false) {
   copyRunner();
   if (harness === "opencode") {
     const configDir = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
@@ -546,21 +718,125 @@ function install(harness) {
     fs.writeFileSync(skill, content, { mode: 0o600 });
   }
   const removedHooks = harness === "codex" && removeCodexHooks();
-  console.error(`Installed the Shifu sync instruction for ${HARNESS_NAMES[harness]}.`);
-  if (removedHooks) console.error("Removed obsolete Codex lifecycle hooks.");
-  console.error(`Next: coding-harness connect --harness ${harness}`);
+  if (!quiet) {
+    console.error(`Installed the Shifu sync instruction for ${HARNESS_NAMES[harness]}.`);
+    if (removedHooks) console.error("Removed obsolete Codex lifecycle hooks.");
+    console.error(`Next: coding-harness connect --harness ${harness}`);
+  }
+}
+
+function xml(value) {
+  return String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+function schedulerArtifact(harness, platform = process.platform) {
+  const runner = installedRunnerPath();
+  const label = `com.useshifu.coding-harness.${harness}`;
+  if (platform === "darwin") {
+    const file = path.join(os.homedir(), "Library", "LaunchAgents", `${label}.plist`);
+    return {
+      file,
+      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()}`;
+        try { execFileSync("launchctl", ["bootout", domain, file], { stdio: "ignore" }); } catch {}
+        execFileSync("launchctl", ["bootstrap", domain, file], { stdio: "ignore" });
+      },
+    };
+  }
+  if (platform === "linux") {
+    const systemd = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "systemd", "user");
+    const service = `shifu-coding-harness-${harness}.service`;
+    const timer = `shifu-coding-harness-${harness}.timer`;
+    return {
+      file: path.join(systemd, service),
+      content: `[Unit]\nDescription=Sync ${HARNESS_NAMES[harness]} activity to Shifu\n\n[Service]\nType=oneshot\nExecStart=${systemdQuote(process.execPath)} ${systemdQuote(runner)} scheduled-sync --harness ${harness} --config-root ${systemdQuote(configRoot())}\n`,
+      extraFiles: [{
+        file: path.join(systemd, timer),
+        content: `[Unit]\nDescription=Check whether ${HARNESS_NAMES[harness]} activity is due for Shifu sync\n\n[Timer]\nOnStartupSec=${SCHEDULER_TICK_MINUTES}min\nOnUnitActiveSec=${SCHEDULER_TICK_MINUTES}min\nPersistent=true\n\n[Install]\nWantedBy=timers.target\n`,
+      }],
+      activate() {
+        execFileSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+        execFileSync("systemctl", ["--user", "enable", "--now", timer], { stdio: "ignore" });
+      },
+    };
+  }
+  if (platform === "win32") {
+    const file = path.join(configRoot(), `${harness}-scheduled-sync.cmd`);
+    const taskName = `Shifu coding harness ${harness}`;
+    return {
+      file,
+      content: `@echo off\r\n"${process.execPath}" "${runner}" scheduled-sync --harness ${harness} --config-root "${configRoot()}"\r\n`,
+      activate() {
+        execFileSync("schtasks.exe", ["/Create", "/TN", taskName, "/TR", file, "/SC", "MINUTE", "/MO", String(SCHEDULER_TICK_MINUTES), "/F"], { stdio: "ignore" });
+      },
+    };
+  }
+  throw new Error(`Scheduled sync is not supported on ${platform}. You can still run coding-harness sync on demand.`);
+}
+
+function systemdQuote(value) {
+  return `"${String(value).replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%")}"`;
+}
+
+function installSchedule(harness) {
+  const artifact = schedulerArtifact(harness, process.env.SHIFU_PLATFORM || process.platform);
+  for (const item of [artifact, ...(artifact.extraFiles || [])]) {
+    fs.mkdirSync(path.dirname(item.file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(item.file, item.content, { mode: 0o600 });
+    fs.chmodSync(item.file, 0o600);
+  }
+  if (process.env.SHIFU_SKIP_SCHEDULER_ACTIVATION !== "1") artifact.activate();
+  return artifact.file;
+}
+
+function scheduleNextRun(harness, intervalHours) {
+  const state = readState(harness);
+  state.schedule = { ...(state.schedule || {}), nextRunAt: Date.now() + intervalHours * 3_600_000 };
+  saveState(harness, state);
+}
+
+async function chooseSyncPolicy(existing) {
+  const intervalOption = option("--interval-hours");
+  const approvalOption = option("--approval-mode");
+  const intervalHours = validateIntervalHours(intervalOption ?? await ask("Sync every how many hours?", String(existing.intervalHours || DEFAULT_INTERVAL_HOURS)));
+  let approvalMode = approvalOption;
+  if (approvalMode === undefined) {
+    const answer = (await ask("Approval mode: automatic or manual?", existing.approvalMode || "automatic")).toLowerCase();
+    approvalMode = answer === "auto" ? "automatic" : answer;
+  }
+  return { intervalHours, approvalMode: validateApprovalMode(approvalMode) };
 }
 
 async function connect(harness) {
-  const token = (await readSecret()).trim();
+  const existing = readJSON(configPath(harness), undefined);
+  const token = existing?.token || (await readSecret()).trim();
   if (!TOKEN_PATTERN.test(token)) throw new Error("The connection key is invalid.");
-  const apiUrl = requireSafeApiUrl(option("--api-url") || process.env.SHIFU_API_URL || DEFAULT_API_URL);
-  if (!(await confirm(`Save this ${HARNESS_NAMES[harness]} key locally for ${apiUrl}? No work content will be sent.`))) {
-    console.error("Connection was not saved.");
-    return;
-  }
-  writeJSON(configPath(harness), { apiUrl, token, harness });
-  console.error(`${HARNESS_NAMES[harness]} is connected. Ask it to sync when you are ready to review recent work.`);
+  const apiUrl = requireSafeApiUrl(option("--api-url") || existing?.apiUrl || process.env.SHIFU_API_URL || DEFAULT_API_URL);
+  const savedPolicy = existing && normalizedPolicy(existing);
+  const currentPolicy = savedPolicy?.onboardingComplete ? savedPolicy : { intervalHours: DEFAULT_INTERVAL_HOURS, approvalMode: "automatic", excludedSessionRefs: savedPolicy?.excludedSessionRefs || [] };
+  const selected = await chooseSyncPolicy(currentPolicy);
+  const syncPolicy = configuredSyncPolicy(existing || {}, harness, selected.intervalHours, selected.approvalMode);
+  install(harness, true);
+  const scheduleFile = installSchedule(harness);
+  writeJSON(configPath(harness), { ...existing, version: CONFIG_VERSION, apiUrl, token, harness, syncPolicy });
+  scheduleNextRun(harness, syncPolicy.intervalHours);
+  console.error(`${HARNESS_NAMES[harness]} is connected. It will sync every ${syncPolicy.intervalHours} hours with ${syncPolicy.approvalMode} approval.`);
+  console.error(`Schedule installed at ${scheduleFile}. No session content was sent during setup.`);
+}
+
+async function updateConfig(harness) {
+  const config = readConfig(harness);
+  const savedPolicy = normalizedPolicy(config);
+  const selected = await chooseSyncPolicy(savedPolicy.onboardingComplete ? savedPolicy : { intervalHours: DEFAULT_INTERVAL_HOURS, approvalMode: "automatic" });
+  const scheduleEnabled = option("--schedule") !== "off";
+  config.version = CONFIG_VERSION;
+  config.syncPolicy = configuredSyncPolicy(config, harness, selected.intervalHours, selected.approvalMode, scheduleEnabled);
+  install(harness, true);
+  if (scheduleEnabled) installSchedule(harness);
+  writeJSON(configPath(harness), config);
+  scheduleNextRun(harness, config.syncPolicy.intervalHours);
+  console.error(`${HARNESS_NAMES[harness]} now syncs every ${config.syncPolicy.intervalHours} hours with ${config.syncPolicy.approvalMode} approval${scheduleEnabled ? "" : "; scheduling is off"}.`);
 }
 
 function textIsSafe(value, maximum) {
@@ -578,10 +854,15 @@ function validateSync(input, harness) {
   if (!input || Object.keys(input).some((field) => !SYNC_FIELDS.has(field))) throw new Error("Remove unsupported fields from the reviewed sync payload.");
   if (!input || input.harness !== harness || !sessionRefIsSafe(input.sessionRef)) throw new Error("Add the current opaque sessionRef before syncing.");
   if (!Number.isInteger(input.fromTurn) || !Number.isInteger(input.toTurn) || input.fromTurn < 1 || input.toTurn < input.fromTurn || input.toTurn > 1_000_000 || input.toTurn - input.fromTurn >= MAX_TURNS_PER_SEGMENT) throw new Error("Use a valid incremental range of at most 12 turns.");
-  if (input.redactionVersion === 3 && !textIsSafe(input.title, MAX_TITLE_LENGTH)) throw new Error("Add a concise, redacted title for this reviewed sync.");
+  if (input.redactionVersion >= 3 && !textIsSafe(input.title, MAX_TITLE_LENGTH)) throw new Error("Add a concise, redacted title for this reviewed sync.");
   if (!textIsSafe(input.summary, 1200)) throw new Error("The summary is empty, too long, or contains sensitive content. Redact it before syncing.");
-  if (!Array.isArray(input.evidence) || input.evidence.length < 1 || input.evidence.length > MAX_EVIDENCE_ITEMS || !input.evidence.every((item) => item && EVIDENCE_KINDS.has(item.kind) && SCOPE_LEVELS.has(item.scope) && (input.redactionVersion !== 3 || textIsSafe(item.title, MAX_TITLE_LENGTH)) && textIsSafe(item.statement, MAX_WORK_DETAIL_LENGTH))) {
-	throw new Error(`evidence must contain 1-${MAX_EVIDENCE_ITEMS} redacted work items with title, detail, kind, and scope.`);
+  const minimumEvidence = input.redactionVersion >= REDACTION_VERSION ? 0 : 1;
+  if (!Array.isArray(input.evidence) || input.evidence.length < minimumEvidence || input.evidence.length > MAX_EVIDENCE_ITEMS || !input.evidence.every((item) => {
+    if (!item || !EVIDENCE_KINDS.has(item.kind) || (input.redactionVersion >= 3 && !textIsSafe(item.title, MAX_TITLE_LENGTH)) || !textIsSafe(item.statement, MAX_WORK_DETAIL_LENGTH)) return false;
+    if (item.kind === "activity" && input.redactionVersion >= REDACTION_VERSION) return item.scope === undefined || item.scope === "";
+    return SCOPE_LEVELS.has(item.scope);
+  })) {
+	throw new Error(`evidence must contain ${minimumEvidence}-${MAX_EVIDENCE_ITEMS} redacted activity or work items with valid titles, details, kinds, and scopes.`);
   }
   for (const field of ["verification", "decisions"]) {
     if (!Array.isArray(input[field]) || input[field].length > MAX_SYNC_ITEMS || !input[field].every((item) => textIsSafe(item, 240))) throw new Error(`${field} must contain at most ${MAX_SYNC_ITEMS} redacted statements.`);
@@ -601,7 +882,7 @@ function validateSync(input, harness) {
     if (identities.has(identity)) throw new Error("Each work item must have a distinct identity.");
     identities.add(identity);
   }
-  if (input.redactionVersion !== 2 && input.redactionVersion !== 3) throw new Error("Use redactionVersion 3 for new reviewed syncs.");
+  if (input.redactionVersion !== 2 && input.redactionVersion !== 3 && input.redactionVersion !== REDACTION_VERSION) throw new Error(`Use redactionVersion ${REDACTION_VERSION} for new syncs.`);
 }
 
 function validSyncReceipt(receipt, input) {
@@ -609,46 +890,249 @@ function validSyncReceipt(receipt, input) {
     (receipt.duplicate ? receipt.lastSyncedTurn >= input.toTurn : receipt.lastSyncedTurn === input.toTurn);
 }
 
-async function sync(harness) {
-  const config = readConfig(harness);
-  const input = readJSON(0, undefined);
+function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function retryDelay(response, attempt) {
+  const retryAfter = response?.headers?.get?.("retry-after");
+  const seconds = Number(retryAfter);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1000, 30_000);
+  const retryAt = Date.parse(retryAfter);
+  if (Number.isFinite(retryAt)) return Math.min(Math.max(0, retryAt - Date.now()), 30_000);
+  const base = Number(process.env.SHIFU_RETRY_BASE_MS || 1000);
+  return Math.min(base * (2 ** attempt), 30_000);
+}
+
+async function postSync(config, input) {
+  let lastError;
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt += 1) {
+    let response;
+    try {
+      response = await fetch(`${config.apiUrl}/v1/connectors/coding-sessions/syncs`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${config.token}` },
+        body: JSON.stringify(input),
+        signal: AbortSignal.timeout(30_000),
+      });
+    } catch (error) {
+      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));
+      continue;
+    }
+    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 (attempt + 1 < MAX_RETRIES) await sleep(retryDelay(response, attempt));
+  }
+  throw lastError;
+}
+
+async function sendSync(harness, input, config = readConfig(harness)) {
   validateSync(input, harness);
   const state = readState(harness);
   const checkpoint = state.sessions[input.sessionRef];
   const expected = (checkpoint?.lastSyncedTurn || 0) + 1;
   if (input.fromTurn !== expected) throw new Error(`This local checkpoint expects turn ${expected}. Review the pending segment before retrying.`);
-  const preview = JSON.stringify(input, null, 2);
-  console.error(`\nThis exact reviewed, redacted segment will be sent to Shifu:\n${preview}`);
-  if (!(await confirm("Sync this segment"))) {
-    console.error("Nothing was sent.");
-    return;
-  }
-  let response;
-  try {
-    response = await fetch(`${config.apiUrl}/v1/connectors/coding-sessions/syncs`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json", Authorization: `Bearer ${config.token}` },
-      body: JSON.stringify(input),
-    });
-  } catch (error) {
-    const reason = error?.cause?.code || error?.message || "unknown transport error";
-    throw new Error(`Could not reach Shifu at ${config.apiUrl}: ${reason}.`);
-  }
-  const payload = await response.json().catch(() => undefined);
-  if (!response.ok) throw new Error(payload?.error?.message || `Shifu rejected the sync (${response.status}).`);
-  const receipt = payload?.data;
+  const receipt = await postSync(config, input);
   if (!validSyncReceipt(receipt, input)) {
     throw new Error("Shifu returned a checkpoint that does not match this reviewed segment. Local state was not advanced.");
   }
   state.sessions[input.sessionRef] = { turnsSinceSync: 0, lastSyncedAt: Date.now(), lastSyncedTurn: receipt.lastSyncedTurn, syncDue: false };
   saveState(harness, state);
   console.error(receipt.duplicate ? "Shifu already had this exact segment. Local checkpoint recovered." : `Synced through turn ${receipt.lastSyncedTurn}.`);
+  return receipt;
+}
+
+async function withSyncLock(harness, action) {
+  fs.mkdirSync(configRoot(), { recursive: true, mode: 0o700 });
+  const file = lockPath(harness);
+  let descriptor;
+  try {
+    try {
+      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);
+    }
+    fs.writeFileSync(descriptor, `${process.pid}\n`);
+    return await action();
+  } finally {
+    if (descriptor !== undefined) {
+      fs.closeSync(descriptor);
+      try { fs.unlinkSync(file); } catch {}
+    }
+  }
+}
+
+async function sync(harness) {
+  const config = readConfig(harness);
+  const input = readJSON(0, undefined);
+  validateSync(input, harness);
+  const policy = normalizedPolicy(config);
+  if (policy.approvalMode === "manual" && !hasFlag("--approved")) {
+    console.error(`\nThis exact redacted segment will be sent to Shifu:\n${JSON.stringify(input, null, 2)}`);
+    if (!(await confirm("Approve this sync"))) {
+      console.error("Nothing was sent.");
+      return;
+    }
+  }
+  const result = await withSyncLock(harness, () => sendSync(harness, input, config));
+  if (result?.skipped) throw new Error("Another Shifu sync is already running. This segment was not sent; retry later.");
+}
+
+function rebuildPendingQueue(harness) {
+  const segments = pendingSegments(harness).map((segment) => payloadForSegment(harness, segment));
+  const queue = { updatedAt: new Date().toISOString(), segments };
+  writeJSON(pendingPath(harness), queue);
+  return queue;
+}
+
+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") {
+    return sessionRef ? { command: "codex", args: ["exec", "resume", "--all", "--json", sessionRef, prompt] } :
+      { command: "codex", args: ["exec", "--json", "--sandbox", "read-only", "--skip-git-repo-check", "-C", os.homedir(), prompt] };
+  }
+  if (harness === "claude_code") {
+    const args = ["-p", prompt, "--output-format", "json", "--max-turns", "1", "--permission-mode", "plan"];
+    if (sessionRef) args.push("--resume", sessionRef);
+    return { command: "claude", args };
+  }
+  const args = ["run", "--format", "json", "--title", "Shifu sync approval", prompt];
+  if (sessionRef) args.splice(1, 0, "--session", sessionRef);
+  return { command: "opencode", args };
+}
+
+function notificationSessionRef(output) {
+  for (const line of String(output).split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const value = JSON.parse(line);
+      const sessionRef = value.thread_id || value.session_id || value.sessionID || value.sessionId || value.data?.thread_id || value.data?.session_id || value.data?.sessionID;
+      if (sessionRefIsSafe(sessionRef)) return sessionRef;
+    } catch {}
+  }
+  return undefined;
+}
+
+function notifyManualApproval(harness, count, existingSessionRef) {
+  const invocation = approvalNotificationInvocation(harness, count, existingSessionRef);
+  const before = existingSessionRef ? new Set() : new Set(localSessions(harness).map((session) => session.sessionRef));
+  const output = execFileSync(invocation.command, invocation.args, {
+    cwd: os.homedir(),
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 120_000,
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  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;
+  if (!created) throw new Error("The approval session was created but its session reference could not be recorded safely.");
+  return created;
+}
+
+function showPending(harness) {
+  readConfig(harness);
+  const queue = rebuildPendingQueue(harness);
+  console.log(JSON.stringify(queue, null, 2));
+}
+
+async function approvePending(harness) {
+  const config = readConfig(harness);
+  const queue = rebuildPendingQueue(harness);
+  if (queue.segments.length === 0) {
+    console.error("There is no pending Shifu activity to approve.");
+    return;
+  }
+  console.error(`\nThese ${queue.segments.length} redacted segment(s) will be sent to Shifu:\n${JSON.stringify(queue.segments, null, 2)}`);
+  if (!hasFlag("--approved") && !(await confirm("Approve all pending segments"))) {
+    console.error("Nothing was sent. The pending list will keep accumulating.");
+    return;
+  }
+  const result = await withSyncLock(harness, async () => {
+    for (const input of queue.segments) await sendSync(harness, input, config);
+  });
+  if (result?.skipped) throw new Error("Another Shifu sync is already running. Nothing was sent; retry later.");
+  rebuildPendingQueue(harness);
+}
+
+async function scheduledSync(harness) {
+  const config = readConfig(harness);
+  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();
+    let failures = 0;
+    let synced = 0;
+    if (policy.approvalMode === "manual") {
+      const queue = rebuildPendingQueue(harness);
+      const pendingFingerprint = createHash("sha256").update(queue.segments.map((segment) => `${segment.sessionRef}:${segment.fromTurn}:${segment.toTurn}`).join("\n")).digest("hex");
+      const changed = state.schedule?.pendingFingerprint !== pendingFingerprint;
+      let approvalSessionRef = state.schedule?.approvalSessionRef;
+      let notificationError;
+      if (queue.segments.length > 0 && changed) {
+        try {
+          approvalSessionRef = notifyManualApproval(harness, queue.segments.length, approvalSessionRef);
+          if (approvalSessionRef && !config.syncPolicy.excludedSessionRefs.includes(approvalSessionRef)) {
+            config.syncPolicy.excludedSessionRefs.push(approvalSessionRef);
+            writeJSON(configPath(harness), config);
+          }
+        } catch (error) {
+          notificationError = error?.message || "Could not create the approval session.";
+        }
+      }
+      state.schedule = {
+        ...state.schedule,
+        lastAttemptAt: startedAt,
+        lastResult: notificationError ? "awaiting_approval_notification_failed" : "awaiting_approval",
+        pendingSegments: queue.segments.length,
+        pendingFingerprint,
+        approvalSessionRef,
+        notificationError,
+        nextRunAt: startedAt + (notificationError ? SCHEDULER_TICK_MINUTES / 60 : policy.intervalHours) * 3_600_000,
+      };
+    } else {
+      const blockedSessions = new Set();
+      for (const segment of pendingSegments(harness)) {
+        if (blockedSessions.has(segment.sessionRef)) continue;
+        try {
+          await sendSync(harness, payloadForSegment(harness, segment), config);
+          synced += 1;
+        } catch (error) {
+          failures += 1;
+          blockedSessions.add(segment.sessionRef);
+          console.error(`${HARNESS_NAMES[harness]} session ${segment.sessionRef} remains pending: ${error.message}`);
+        }
+      }
+      state.schedule = {
+        lastAttemptAt: startedAt,
+        lastResult: failures ? "partial_failure" : "complete",
+        syncedSegments: synced,
+        failedSessions: failures,
+        nextRunAt: startedAt + (failures ? SCHEDULER_TICK_MINUTES / 60 : policy.intervalHours) * 3_600_000,
+      };
+    }
+    const latest = readState(harness);
+    latest.schedule = state.schedule;
+    saveState(harness, latest);
+  });
+  if (result?.skipped) return;
 }
 
 function status(harness) {
   const config = readConfig(harness);
   const state = readState(harness);
-  console.log(JSON.stringify({ harness, apiUrl: config.apiUrl, sessions: state.sessions }, null, 2));
+  const pending = readJSON(pendingPath(harness), { segments: [] });
+  console.log(JSON.stringify({ harness, apiUrl: config.apiUrl, syncPolicy: normalizedPolicy(config), schedule: state.schedule || null, pendingSegments: pending.segments.length, sessions: state.sessions }, null, 2));
 }
 
 function sessions(harness) {
@@ -683,10 +1167,7 @@ function review(harness) {
   if (!Number.isInteger(turns) || turns < 1 || turns > MAX_TURNS_PER_SEGMENT) throw new Error("Choose --turns between 1 and 12.");
   const toTurn = Math.min(selected.turnCount, fromTurn + turns - 1);
   if (fromTurn > toTurn) throw new Error(`This ${HARNESS_NAMES[harness]} session has no unsynced turns to review.`);
-  const files = harness === "codex" ? sessionFiles(codexSessionsRoot()) : harness === "claude_code" ? 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)[0]?.file;
-  const { notes } = harness === "codex" ? codexReview(selectedFile, fromTurn, toTurn) : harness === "claude_code" ? claudeReview(selectedFile, fromTurn, toTurn) : opencodeReview(sessionRef, fromTurn, toTurn);
+  const { notes } = reviewSegment(harness, sessionRef, fromTurn, toTurn);
   const candidates = reviewCandidates(notes);
   console.log(JSON.stringify({
     sessionRef,
@@ -703,16 +1184,21 @@ function review(harness) {
 }
 
 async function main() {
+  if (option("--config-root")) process.env.SHIFU_CONFIG_ROOT = path.resolve(option("--config-root"));
   const command = process.argv[2];
   const subCommand = process.argv[3];
   const harness = requireHarness(option("--harness"));
   if (command === "install") return install(harness);
   if (command === "connect") return connect(harness);
+  if (command === "config" && subCommand === "update") return updateConfig(harness);
   if (command === "sync") return sync(harness);
+  if (command === "scheduled-sync") return scheduledSync(harness);
+  if (command === "pending") return showPending(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);
-  throw new Error("Use install, connect, status, sessions, review, or sync.");
+  throw new Error("Use install, connect, config update, status, sessions, review, sync, pending, approve, or scheduled-sync.");
 }
 
 if (require.main === module) {
@@ -724,4 +1210,4 @@ if (require.main === module) {
     });
 }
 
-module.exports = { claudeReview, claudeSession, codexReview, codexSession, configPath, finalAssistantNote, install, installDestination, localSessions, opencodeQuery, opencodeReview, opencodeSessions, readSecret, removeHooks, requireSafeApiUrl, reviewCandidates, statePath, textIsSafe, unsyncedCodexSessions, validSyncReceipt, validateSync };
+module.exports = { approvalNotificationInvocation, claudeReview, claudeSession, codexReview, codexSession, configPath, configuredSyncPolicy, finalAssistantNote, install, installDestination, localSessions, normalizedPolicy, notificationSessionRef, opencodeQuery, opencodeReview, opencodeSessions, payloadForSegment, pendingSegments, readSecret, removeHooks, requireSafeApiUrl, reviewCandidates, schedulerArtifact, statePath, textIsSafe, unsyncedCodexSessions, validSyncReceipt, validateApprovalMode, validateIntervalHours, validateSync };

package/commands/shifu-sync.md

@@ -1,47 +1,17 @@
 ---
-description: Prepare a reviewed, redacted incremental Shifu sync and ask for confirmation.
+description: Inspect or sync redacted OpenCode activity using the saved Shifu policy.
 ---
 
-Use the Shifu reviewed-sync process for OpenCode only after an explicit user request. Never upload automatically or include raw transcript content. Before acting, say whether you will connect or sync and ask for confirmation.
+Run `npx @useshifu/coding-harness status --harness opencode` first.
 
-For a sync request, use the time window the user names. If none is named, state that you will use the last 24 hours. The only supported windows are 24, 48, and 72 hours.
+If manual approval has queued scheduled work, run `pending --harness opencode`, show the complete redacted list, and ask once. After approval, run `approve --approved --harness opencode`.
 
-1. Run `npx @useshifu/coding-harness sessions --harness opencode --hours <24|48|72>`.
-2. Use every returned opaque `sessionRef`, `fromTurn`, and `toTurn`. A segment contains at most 12 user turns.
-3. Do not upload a `blockedSessions` entry automatically. Its next unsynced turn predates the selected window. Only if the user specifically chooses that session, run discovery and review with `--session-ref <sessionRef> --all`.
-4. For each selected segment, run `npx @useshifu/coding-harness review --harness opencode --session-ref <sessionRef> --hours <24|48|72>`. Review returns local assistant notes and suggested candidates only. It never returns user prompts.
-5. If review reports more than 64 candidates, rerun discovery and review with `--turns 1`. Repeat discovery after every accepted segment until the selected pending delta is exhausted.
-6. Redact the reviewed assistant notes, show the exact JSON payload, and ask the user to confirm. Only after confirmation, pipe the payload to:
+For an explicit sync-now request:
 
-```sh
-npx @useshifu/coding-harness sync --harness opencode
-```
+1. Run `sessions --harness opencode --hours 24`, using 48 or 72 only when requested.
+2. Review each returned segment with `review --harness opencode --session-ref <sessionRef> --hours <hours>`.
+3. Prepare a redaction-version-four payload from final assistant notes only. Use generic `activity` evidence for writing, feedback, research, planning, product work, and any work that is not clearly an engineering implementation or decision. Activity evidence has no technical scope. An empty evidence list is valid when only the safe session summary remains.
+4. In automatic mode, pipe the payload to `sync --harness opencode` without asking again. In manual mode, show the exact payload, ask once, and then use `sync --approved --harness opencode`.
+5. Keep the returned session reference and turn range unchanged. Never upload prompts, raw transcripts, tool output, code, paths, commands, URLs, credentials, names, customer details, or proprietary identifiers.
 
-The payload must contain `harness: "opencode"`, an opaque `sessionRef`, the returned contiguous `fromTurn`/`toTurn` range, a concise redacted sync `title`, a redacted `summary`, 1–64 redacted `evidence` work items (`title`, `kind`, `statement`, `scope`), up to 16 redacted `verification` items, up to 16 redacted `decisions`, and `redactionVersion: 3`. Evidence describes the work itself; verification records how it was checked. Scope must be one of `unit`, `module`, `service`, `system`, or `product` and must be reviewed rather than guessed from the candidate. Replace names, repository identifiers, file paths, URLs, credentials, commands, prompts, source code, customer details, and proprietary identifiers with neutral descriptions. Never invent missing details or alter the returned turn range.
-
-Write a concise but useful durable technical record. Split architecture, implementation, security controls, configuration or rollout, and user-facing behaviour into separate evidence items when they have different boundaries. Each item should state the mechanism, responsible boundary, and material constraint. Record a material architecture, security, or rollout choice as `kind: "decision"` evidence when it should persist; do not treat the standalone `decisions` list as a durable work item. State known security limits plainly. Keep tests, builds, reviews, deployment checks, and other proof in `verification`, and cite relevant verification entries from evidence with `verificationRefs`. Use the smallest true scope and do not claim impact, ownership, or outcomes not supported by the reviewed work.
-
-Use this structure:
-
-```json
-{
-  "harness": "opencode",
-  "sessionRef": "opaque-session-id",
-  "fromTurn": 1,
-  "toTurn": 12,
-  "title": "Hardened connector checkpoints",
-  "summary": "Implemented a narrow change and checked the relevant behaviour.",
-  "evidence": [{"kind": "implementation", "title": "Added checkpoint recovery", "statement": "Implemented a focused connector change.", "scope": "service"}],
-  "verification": ["Focused tests passed."],
-  "decisions": ["Kept the change within the existing connector boundary."],
-  "redactionVersion": 3
-}
-```
-
-Only after the user confirms the displayed payload, run:
-
-```sh
-printf '%s' '<reviewed JSON>' | npx @useshifu/coding-harness sync --harness opencode
-```
-
-The CLI prints the payload again and asks for a final terminal confirmation. Never bypass that confirmation.
+To connect or finish onboarding, run `connect --harness opencode`. To change the interval or approval policy later, run `config update --harness opencode`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@useshifu/coding-harness",
-  "version": "0.2.7",
-  "description": "Reviewed, incremental coding-harness sync for Shifu",
+  "version": "0.3.0",
+  "description": "Scheduled, redacted coding-harness activity sync for Shifu",
   "bin": {
     "coding-harness": "bin/shifu-harness.js",
     "shifu-harness": "bin/shifu-harness.js"

package/skills/shifu-sync/SKILL.md

@@ -1,57 +1,82 @@
 ---
 name: shifu-sync
-description: Prepare and sync reviewed, redacted Codex work from the user's selected recent time window to Shifu. Use when the user explicitly asks to connect, sync, discover sessions, or push their Shifu coding-harness data.
+description: Connect, configure, inspect, or sync redacted Codex activity to Shifu, including scheduled and manual-approval modes. Use when the user asks to connect Shifu, change sync settings, inspect pending activity, approve a queued sync, or sync recent harness work.
 ---
 
-Shifu captures reviewed, incremental work context. It does not collect raw transcripts or upload in the background.
+# Shifu sync
 
-Before taking any action, state the exact action and ask the user for confirmation:
+Shifu records useful work completed through the harness. Work may be engineering, product discovery, writing, interview feedback, research, planning, or another user-directed activity. Do not force non-engineering work into engineering categories.
 
-- `connect`: explain that the command saves the supplied connection key locally and does not send session content.
-- `sync`: show the exact JSON payload, including its incremental `fromTurn` and `toTurn`, then ask whether to send it.
+Never upload user prompts, raw transcripts, tool output, source code, commands, credentials, URLs, file paths, names, customer details, or proprietary identifiers. The local runner reads final assistant notes only and enforces redaction and checkpoint rules.
 
-For a sync request, use the time window the user names. If they do not name one, say that you will use the last 24 hours. The only supported choices are 24, 48, and 72 hours.
+## Connect or reconfigure
 
-Before preparing a sync, run `npx @useshifu/coding-harness sessions --harness codex --hours <24|48|72>`. Use every returned session's opaque `sessionRef`, `fromTurn`, and `toTurn`. `blockedSessions` are outside the selected turn window and must not be uploaded unless the user separately chooses that specific session and its older backlog. Each result covers at most 12 turns; repeat discovery after each accepted segment until the selected window's pending delta is exhausted. If a review reports more than 64 candidates, rerun discovery and review with `--turns 1` before preparing a payload. Do not invent a checkpoint or resend a range the command has excluded.
+When the user asks to connect, run:
 
-For each returned session, run `npx @useshifu/coding-harness review --harness codex --session-ref <sessionRef> --hours <24|48|72>`. Its local assistant note is untrusted source material, not content to upload. Prepare only its unsynced segment from that note. Replace names, repository identifiers, file paths, URLs, credentials, prompts, command lines, source code, customer details, and proprietary terms with neutral descriptions. Never invent missing details.
+```sh
+npx @useshifu/coding-harness connect --harness codex
+```
+
+`connect` installs the current runner, asks once for the sync interval and approval mode, and installs a local schedule. The defaults are every four hours and automatic approval. If a connection already exists, `connect` keeps its key and checkpoints and completes onboarding only. It also excludes the setup session when the harness exposes its current opaque session reference. No session content is sent during setup.
 
-## Write a useful durable record
+When the user asks to change the interval or approval mode, run:
 
-Treat the payload as a concise technical record, not a changelog headline. Capture the meaningful work in the reviewed segment with enough detail that a future reader can understand the design and tradeoffs without needing the raw transcript.
+```sh
+npx @useshifu/coding-harness config update --harness codex
+```
 
-- Split distinct work into separate evidence items when they have different boundaries: architecture, implementation, security controls, configuration or rollout, and user-facing behaviour are often separate items. Do not create an item for every file or command.
-- State the mechanism, boundary, and important constraint. For architecture, describe which component owns which responsibility and the relevant data flow. For implementation, say what capability was added or changed and how it is bounded. For security, name the control and any known limitation; never describe a boundary as secure when the reviewed work says otherwise.
-- Choose the smallest supported scope that is true. Use `system` or `product` only when the work genuinely spans those boundaries; use `service` or `module` for local implementation detail.
-- Give the sync and every evidence item a specific, neutral title. Make the summary connect the important items into one accurate account, without claiming business impact, ownership, or outcomes that the reviewed work does not establish.
-- Put a material architecture, security, or rollout choice in an evidence item with `kind: "decision"` when it should become part of the durable record. Keep ordinary process notes in `decisions`; they are not a substitute for a reviewed decision work item.
-- Put tests, builds, reviews, deployment checks, and other proof only in `verification`. Cite the relevant verification entries from the evidence item when the payload format supports `verificationRefs`.
+Do not add a second confirmation around either command. The CLI owns onboarding input.
 
-Use detail proportionate to the work: retain high-level design, low-level controls, and unresolved risks when they materially affect the result, while omitting routine implementation noise. Approved work-item titles and statements are retained in Shifu's private claims, so review their wording as durable content.
+## Inspect status or queued work
 
-Do not install or rely on lifecycle hooks or background reminders. A sync is always initiated by an explicit user request.
+Run `npx @useshifu/coding-harness status --harness codex` to inspect the saved policy, next scheduled run, pending count, and checkpoints.
+
+In manual mode, scheduled runs accumulate redacted segments locally. Run:
+
+```sh
+npx @useshifu/coding-harness pending --harness codex
+```
 
-Use this structure. Do not invent additional evidence fields; the sync API rejects fields outside its contract.
+Show the returned list and ask for one approval for the whole list. After approval, run `npx @useshifu/coding-harness approve --approved --harness codex`. Do not ask again.
+
+## Sync now
+
+For an explicit sync request, first read `status` to determine the saved approval mode. Use the time window the user names; otherwise use 24 hours. Supported interactive windows are 24, 48, and 72 hours.
+
+1. Run `npx @useshifu/coding-harness sessions --harness codex --hours <24|48|72>`.
+2. Ignore `blockedSessions` unless the user specifically selects one. For a selected older backlog, add `--session-ref <sessionRef> --all`.
+3. For each returned segment, run `npx @useshifu/coding-harness review --harness codex --session-ref <sessionRef> --hours <24|48|72>`.
+4. Prepare a version-four payload from the returned final-assistant notes. Keep the returned `sessionRef`, `fromTurn`, and `toTurn` unchanged.
+5. In automatic mode, send it without another approval. In manual mode, show the exact payload and ask once; after approval, pass `--approved` to the sync command.
+6. Repeat discovery after accepted segments until the selected window is exhausted.
+
+Use `kind: "activity"` for general harness work; it does not require a technical scope. Use `implementation` or `decision` only when the note clearly supports that engineering classification, and then use the smallest reviewed scope among `unit`, `module`, `service`, `system`, and `product`. Evidence may be empty when the safe final note supports only a session-level title and summary. Never invent impact, ownership, verification, or outcomes.
 
 ```json
 {
   "harness": "codex",
   "sessionRef": "opaque-session-id",
   "fromTurn": 1,
-  "toTurn": 12,
-  "title": "Hardened connector checkpoints",
-  "summary": "Implemented a narrow change and checked the relevant behaviour.",
-  "evidence": [{"kind": "implementation", "title": "Added checkpoint recovery", "statement": "Implemented a focused connector change.", "scope": "service"}],
-  "verification": ["Focused tests passed."],
-  "decisions": ["Kept the change within the existing connector boundary."],
-  "redactionVersion": 3
+  "toTurn": 3,
+  "title": "Prepared structured interview feedback",
+  "summary": "Prepared structured interview feedback and clarified the recommendation.",
+  "evidence": [{"kind": "activity", "title": "Drafted interview feedback", "statement": "Prepared structured interview feedback."}],
+  "verification": [],
+  "decisions": [],
+  "redactionVersion": 4
 }
 ```
 
-Only after the user confirms the displayed payload, run:
+Automatic mode:
+
+```sh
+printf '%s' '<redacted JSON>' | npx @useshifu/coding-harness sync --harness codex
+```
+
+Manual mode, only after the user's single approval:
 
 ```sh
-printf '%s' '<reviewed JSON>' | npx @useshifu/coding-harness sync --harness codex
+printf '%s' '<redacted JSON>' | npx @useshifu/coding-harness sync --approved --harness codex
 ```
 
-The CLI prints the payload again and asks for a final terminal confirmation. Never bypass that confirmation.
+If a transport or server error remains after the runner's retries, report that the checkpoint was not advanced. Do not alter the segment or skip ahead.