@useshifu/coding-harness 0.1.0 → 0.2.1

package/README.md

@@ -5,16 +5,25 @@
 ```sh
 npx @useshifu/coding-harness install --harness codex
 npx @useshifu/coding-harness connect --harness codex
-npx @useshifu/coding-harness schedule --harness codex --after-turns 12 --after-hours 4
-npx @useshifu/coding-harness activate --harness codex
 ```
 
-Replace `codex` with `claude_code` or `opencode` as needed. `connect`, `schedule`, `activate`, and `sync` each ask for confirmation. Activation writes only local harness configuration; it can mark a segment as due but cannot upload it. A due reminder appears when the harness next becomes active.
+`connect` and `sync` each ask for confirmation. The Codex connector has no lifecycle hooks and never uploads in the background. Claude Code and OpenCode time-window discovery are not available yet.
+
+When asked to sync, Codex discovers 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`.
+
+```sh
+npx @useshifu/coding-harness sessions --harness codex --hours 24
+npx @useshifu/coding-harness review --harness codex --session-ref opaque-session-id
+```
+
+`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.
 
 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.
 
 ```sh
-printf '%s' '{"harness":"codex","sessionRef":"opaque-session-id","fromTurn":1,"toTurn":8,"summary":"Implemented a focused change and checked the result.","evidence":["Focused tests passed."],"decisions":[],"redactionVersion":1}' | npx @useshifu/coding-harness sync --harness codex
+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
 ```
 
+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).
+
 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`.

package/bin/shifu-harness.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
-const crypto = require("node:crypto");
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
 const readline = require("node:readline/promises");
+const tty = require("node:tty");
 
 const DEFAULT_API_URL = "https://api.useshifu.com";
 const HARNESS_NAMES = {
@@ -13,7 +13,22 @@ const HARNESS_NAMES = {
   opencode: "OpenCode",
 };
 const TOKEN_PATTERN = /^cs_sk_[a-f0-9]{16}_[a-f0-9]{64}$/;
-const SENSITIVE_PATTERNS = ["-----begin", "api_key", "authorization", "password=", "sk-", "ghp_", "@", "://", "`", "/"];
+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", "@", "://", "`", "/"];
+const PHONE_NUMBER_PATTERN = /(?:\+?\d[\d .()-]{6,}\d)/i;
+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_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"]);
+const WORK_AREAS = new Set(["architecture", "api", "backend", "connector", "database", "documentation", "frontend", "performance", "security", "testing", "tooling"]);
+const ITEM_REF_PATTERN = /^[A-Za-z0-9_-]{1,80}$/;
+const MAX_EVIDENCE_ITEMS = 64;
+const MAX_SYNC_ITEMS = 16;
+const MAX_TURNS_PER_SEGMENT = 12;
+const MAX_TITLE_LENGTH = 160;
+const MAX_WORK_DETAIL_LENGTH = 600;
 
 function configRoot() {
   return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "shifu", "coding-harness");
@@ -31,6 +46,10 @@ function installedRunnerPath() {
   return path.join(configRoot(), "runner.js");
 }
 
+function codexSessionsRoot() {
+  return process.env.SHIFU_CODEX_SESSIONS_ROOT || path.join(os.homedir(), ".codex", "sessions");
+}
+
 function requireHarness(value) {
   if (!Object.hasOwn(HARNESS_NAMES, value)) throw new Error("Choose --harness codex, claude_code, or opencode.");
   return value;
@@ -67,9 +86,20 @@ function readConfig(harness) {
   if (!config || typeof config.token !== "string" || typeof config.apiUrl !== "string") {
     throw new Error(`No ${HARNESS_NAMES[harness]} connection is configured. Run connect first.`);
   }
+  requireSafeApiUrl(config.apiUrl);
   return config;
 }
 
+function requireSafeApiUrl(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new Error("Use a valid Shifu API URL."); }
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if ((url.protocol !== "https:" && !(local && url.protocol === "http:")) || url.username || url.password || url.search || url.hash) {
+    throw new Error("Use HTTPS for the Shifu API, or HTTP on localhost for development.");
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
 function readState(harness) {
   return readJSON(statePath(harness), { sessions: {} });
 }
@@ -78,15 +108,204 @@ function saveState(harness, state) {
   writeJSON(statePath(harness), state);
 }
 
+function numberOption(name, fallback) {
+  const value = option(name);
+  return value === undefined ? fallback : Number(value);
+}
+
+function sessionFiles(root) {
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root, { recursive: true, withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+    .map((entry) => path.join(entry.parentPath || entry.path, entry.name));
+}
+
+function codexSession(file) {
+  const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+  let sessionRef;
+  let startedAt;
+  let updatedAt;
+  let turnCount = 0;
+  const turnTimes = [];
+  for (const line of lines) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      throw new Error(`Could not read Codex session metadata from ${file}.`);
+    }
+    if (entry.type === "session_meta") {
+      sessionRef = entry.payload?.id || entry.payload?.session_id;
+      startedAt ||= entry.timestamp;
+    }
+    if (entry.type === "response_item" && entry.payload?.type === "message" && entry.payload?.role === "user") {
+      turnCount += 1;
+      turnTimes.push(typeof entry.timestamp === "string" ? entry.timestamp : null);
+    }
+    if (typeof entry.timestamp === "string") updatedAt = entry.timestamp;
+  }
+  if (typeof sessionRef !== "string" || sessionRef.length < 8 || !updatedAt || turnCount === 0) return undefined;
+  return { sessionRef, startedAt: startedAt || updatedAt, updatedAt, turnCount, turnTimes };
+}
+
+function finalAssistantNote(file) {
+  const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+  let sessionRef;
+  let updatedAt;
+  let note;
+  for (const line of lines) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      throw new Error(`Could not read Codex session metadata from ${file}.`);
+    }
+    if (entry.type === "session_meta") sessionRef = entry.payload?.id || entry.payload?.session_id;
+    if (entry.type === "response_item" && entry.payload?.type === "message" && entry.payload?.role === "assistant") {
+      const text = entry.payload.content
+        ?.filter((content) => content.type === "output_text" && typeof content.text === "string")
+        .map((content) => content.text)
+        .join("\n")
+        .trim();
+      if (text) note = text;
+    }
+    if (typeof entry.timestamp === "string") updatedAt = entry.timestamp;
+  }
+  return typeof sessionRef === "string" && note && updatedAt ? { sessionRef, updatedAt, note } : undefined;
+}
+
+function codexReview(file, fromTurn, toTurn) {
+  const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+  let sessionRef;
+  let turn = 0;
+  const notes = [];
+  for (const line of lines) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      throw new Error(`Could not read Codex session metadata from ${file}.`);
+    }
+    if (entry.type === "session_meta") sessionRef = entry.payload?.id || entry.payload?.session_id;
+    if (entry.type !== "response_item" || entry.payload?.type !== "message") continue;
+    if (entry.payload.role === "user") {
+      turn += 1;
+      continue;
+    }
+    if (entry.payload.role !== "assistant" || (entry.payload.phase && entry.payload.phase !== "final_answer") || turn < fromTurn || turn > toTurn) continue;
+    const note = entry.payload.content
+      ?.filter((content) => content.type === "output_text" && typeof content.text === "string")
+      .map((content) => content.text)
+      .join("\n")
+      .trim();
+    if (note) notes.push({ turn, note });
+  }
+  return { sessionRef, turnCount: turn, notes };
+}
+
+function reviewCandidates(notes) {
+  const candidates = [];
+  const seen = new Set();
+  for (const [noteIndex, { turn, note }] of notes.entries()) {
+    for (const [lineIndex, line] of note.split("\n").entries()) {
+      const statement = line.trim().replace(/^[-*]\s+/, "");
+      if (!textIsSafe(statement, MAX_WORK_DETAIL_LENGTH) || /\b(?:tests?|checks?|build|lint|review)\b.*\b(?:passed|pass|completed|succeeded)\.?$/i.test(statement)) continue;
+      const kind = /^(decided|chose|selected|kept|rejected)\b/i.test(statement) ? "decision" : "implementation";
+      if (seen.has(`${kind}:${statement}`)) continue;
+      seen.add(`${kind}:${statement}`);
+      const itemRef = `t${turn}_n${noteIndex + 1}_l${lineIndex + 1}`;
+      const areas = [...WORK_AREAS].filter((area) => new RegExp(`\\b${area}\\b`, "i").test(statement));
+      const candidate = { kind, statement, scope: null, itemRef };
+      if (areas.length === 1) candidate.area = areas[0];
+      candidates.push(candidate);
+    }
+  }
+  return candidates;
+}
+
+function unsyncedCodexSessions(harness, hours, turns = MAX_TURNS_PER_SEGMENT, selectedRef, includeOlder = false) {
+  if (harness !== "codex") throw new Error("Session discovery is currently available for Codex only.");
+  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 sessions = new Map();
+  for (const session of sessionFiles(codexSessionsRoot())
+    .map(codexSession)
+    .filter(Boolean)
+    .filter((session) => selectedRef ? session.sessionRef === selectedRef : Date.parse(session.updatedAt) >= since)) {
+    const existing = sessions.get(session.sessionRef);
+    sessions.set(session.sessionRef, existing ? {
+      ...session,
+      startedAt: existing.startedAt < session.startedAt ? existing.startedAt : session.startedAt,
+      updatedAt: existing.updatedAt > session.updatedAt ? existing.updatedAt : session.updatedAt,
+      turnCount: Math.max(existing.turnCount, session.turnCount),
+      turnTimes: session.turnCount >= existing.turnCount ? session.turnTimes : existing.turnTimes,
+    } : session);
+  }
+  return [...sessions.values()]
+    .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt))
+    .map(({ turnTimes, ...session }) => {
+      const checkpoint = state.sessions[session.sessionRef]?.lastSyncedTurn || 0;
+      return {
+        ...session,
+        fromTurn: checkpoint + 1,
+        toTurn: Math.min(session.turnCount, checkpoint + turns),
+        remainingTurns: Math.max(0, session.turnCount - checkpoint - turns),
+        oldestUnsyncedAt: turnTimes[checkpoint] || null,
+      };
+    })
+    .filter((session) => session.fromTurn <= session.toTurn && (includeOlder || Date.parse(session.oldestUnsyncedAt) >= since));
+}
+
 function prompt() {
-  return readline.createInterface({ input: process.stdin, output: process.stderr });
+  const input = process.stdin.isTTY ? process.stdin : fs.createReadStream("/dev/tty");
+  const terminal = readline.createInterface({ input, output: process.stderr });
+  terminal.shifuInput = input;
+  return terminal;
 }
 
 async function confirm(question) {
   const terminal = prompt();
-  const answer = (await terminal.question(`${question} [y/N] `)).trim().toLowerCase();
-  terminal.close();
-  return answer === "y" || answer === "yes";
+  try {
+    const answer = (await terminal.question(`${question} [y/N] `)).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } 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"));
+  const wasRaw = input.isRaw;
+  process.stderr.write("Connection key (hidden): ");
+  input.setRawMode(true);
+  input.setEncoding("utf8");
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const finish = (error) => {
+      input.off("data", onData);
+      input.off("error", onError);
+      input.setRawMode(Boolean(wasRaw));
+      if (ownsInput) input.destroy();
+      process.stderr.write("\n");
+      if (error) reject(error);
+      else resolve(value);
+    };
+    const onError = (error) => finish(error);
+    const onData = (chunk) => {
+      for (const character of chunk) {
+        if (character === "\r" || character === "\n") return finish();
+        if (character === "\u0003") return finish(new Error("Connection was cancelled."));
+        if (character === "\u007f" || character === "\b") value = value.slice(0, -1);
+        else if (character >= " " && character !== "\u007f") value += character;
+      }
+    };
+    input.on("data", onData);
+    input.on("error", onError);
+  });
 }
 
 function copyRunner() {
@@ -100,42 +319,35 @@ function copyDirectory(source, destination) {
   fs.cpSync(source, destination, { recursive: true, force: true });
 }
 
-function shellCommand(harness, event) {
-  return `\"${process.execPath}\" \"${installedRunnerPath()}\" hook --harness ${harness} --event ${event}`;
-}
-
-function addHook(config, event, command, timeout) {
-  config.hooks ||= {};
-  config.hooks[event] ||= [];
-  const present = config.hooks[event].some((group) => group && Array.isArray(group.hooks) && group.hooks.some((hook) => hook.command === command));
-  if (!present) config.hooks[event].push({ hooks: [{ type: "command", command, timeout }] });
+function removeHooks(config, commandFragment) {
+  if (!config.hooks || typeof config.hooks !== "object") return false;
+  let changed = false;
+  for (const [event, groups] of Object.entries(config.hooks)) {
+    if (!Array.isArray(groups)) continue;
+    const retainedGroups = groups
+      .map((group) => {
+        if (!group || !Array.isArray(group.hooks)) return group;
+        const hooks = group.hooks.filter((hook) => {
+          const remove = hook?.type === "command" && typeof hook.command === "string" && hook.command.includes(commandFragment);
+          changed ||= remove;
+          return !remove;
+        });
+        return hooks.length === 0 ? undefined : { ...group, hooks };
+      })
+      .filter(Boolean);
+    if (retainedGroups.length === 0) delete config.hooks[event];
+    else config.hooks[event] = retainedGroups;
+  }
+  return changed;
 }
 
-function enableCodex(harness) {
+function removeCodexHooks() {
   const file = path.join(os.homedir(), ".codex", "hooks.json");
-  const config = readJSON(file, { description: "Shifu reviewed sync reminders" });
-  addHook(config, "Stop", shellCommand(harness, "stop"), 3);
-  addHook(config, "SessionEnd", shellCommand(harness, "session_end"), 3);
-  writeJSON(file, config);
-  return file;
-}
-
-function enableClaude(harness) {
-  const file = path.join(os.homedir(), ".claude", "settings.json");
+  if (!fs.existsSync(file)) return false;
   const config = readJSON(file, {});
-  addHook(config, "Stop", shellCommand(harness, "stop"), 3);
-  addHook(config, "SessionEnd", shellCommand(harness, "session_end"), 3);
+  if (!removeHooks(config, `${installedRunnerPath()}\" hook --harness codex`)) return false;
   writeJSON(file, config);
-  return file;
-}
-
-function enableOpenCode(harness) {
-  const file = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "opencode", "plugins", "shifu-sync.js");
-  const runner = JSON.stringify(installedRunnerPath());
-  const source = `import { spawn } from "node:child_process";\n\nconst runner = ${runner};\n\nfunction notify(event) {\n  const child = spawn(process.execPath, [runner, "hook", "--harness", "${harness}", "--event", "idle"], { stdio: ["pipe", "ignore", "ignore"], detached: true });\n  child.stdin.end(JSON.stringify({ event }));\n  child.unref();\n}\n\nexport const ShifuSync = async () => ({\n  event: async ({ event }) => {\n    if (event.type === "session.idle" || event.type === "session.deleted") notify(event);\n  },\n});\n`;
-  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-  fs.writeFileSync(file, source, { mode: 0o600 });
-  return file;
+  return true;
 }
 
 function installDestination(harness) {
@@ -155,93 +367,59 @@ function install(harness) {
     const skill = path.join(destination, "SKILL.md");
     const content = fs.readFileSync(skill, "utf8")
       .replaceAll('"codex"', `"${harness}"`)
-      .replaceAll("--harness codex", `--harness ${harness}`);
+      .replaceAll("--harness codex", `--harness ${harness}`)
+      .replaceAll("npx @useshifu/coding-harness", `"${process.execPath}" "${installedRunnerPath()}"`);
     fs.writeFileSync(skill, content, { mode: 0o600 });
   }
+  const removedHooks = harness === "codex" && removeCodexHooks();
   console.error(`Installed the Shifu sync instruction for ${HARNESS_NAMES[harness]}.`);
-  console.error(`Next: shifu-harness connect --harness ${harness}`);
+  if (removedHooks) console.error("Removed obsolete Codex lifecycle hooks.");
+  console.error(`Next: coding-harness connect --harness ${harness}`);
 }
 
 async function connect(harness) {
-  const terminal = prompt();
-  const token = (await terminal.question("Connection key: ")).trim();
-  terminal.close();
+  const token = (await readSecret()).trim();
   if (!TOKEN_PATTERN.test(token)) throw new Error("The connection key is invalid.");
-  const apiUrl = (option("--api-url") || process.env.SHIFU_API_URL || DEFAULT_API_URL).replace(/\/$/, "");
+  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;
   }
-  const existing = readJSON(configPath(harness), {});
-  writeJSON(configPath(harness), { ...existing, apiUrl, token, harness, schedule: existing.schedule || { afterTurns: 12, afterHours: 4 } });
-  console.error(`${HARNESS_NAMES[harness]} is connected. Run activate only when you want reminders.`);
-}
-
-async function activate(harness) {
-  readConfig(harness);
-  if (!(await confirm(`Activate Shifu reminders for ${HARNESS_NAMES[harness]}? This adds local lifecycle hooks. They only mark syncs as due; they never upload automatically.`))) {
-    console.error("Activation was cancelled.");
-    return;
-  }
-  copyRunner();
-  const file = harness === "codex" ? enableCodex(harness) : harness === "claude_code" ? enableClaude(harness) : enableOpenCode(harness);
-  console.error(`Shifu reminders are active. Updated ${file}.`);
-}
-
-async function schedule(harness) {
-  const config = readConfig(harness);
-  const afterTurns = Number(option("--after-turns") || config.schedule?.afterTurns || 12);
-  const afterHours = Number(option("--after-hours") || config.schedule?.afterHours || 4);
-  if (!Number.isInteger(afterTurns) || afterTurns < 1 || afterTurns > 1000 || !Number.isFinite(afterHours) || afterHours <= 0 || afterHours > 168) {
-    throw new Error("Choose --after-turns from 1 to 1000 and --after-hours greater than 0 and at most 168.");
-  }
-  if (!(await confirm(`Save a reminder after ${afterTurns} turns or ${afterHours} hours without a sync? It will request review, never upload automatically.`))) {
-    console.error("Schedule was not changed.");
-    return;
-  }
-  writeJSON(configPath(harness), { ...config, schedule: { afterTurns, afterHours } });
-  console.error("Reminder schedule saved. Activate the connector to receive harness lifecycle reminders.");
-}
-
-function sessionID(input) {
-  return input.session_id || input.sessionId || input?.event?.properties?.sessionID || input?.event?.properties?.id;
-}
-
-function hook(harness, event) {
-  const config = readConfig(harness);
-  const input = readJSON(0, {});
-  const reference = sessionID(input);
-  if (typeof reference !== "string" || reference.length < 8) return;
-  const state = readState(harness);
-  state.lastSessionRef = reference;
-  const session = state.sessions[reference] || { turnsSinceSync: 0, lastSyncedAt: 0, syncDue: false };
-  if (event === "stop" || event === "idle") session.turnsSinceSync += 1;
-  if (event === "session_end") session.syncDue = true;
-  const hoursSinceSync = session.lastSyncedAt ? (Date.now() - session.lastSyncedAt) / 3_600_000 : 0;
-  const schedule = config.schedule || { afterTurns: 12, afterHours: 4 };
-  const due = session.turnsSinceSync >= schedule.afterTurns || hoursSinceSync >= schedule.afterHours || session.syncDue;
-  session.syncDue = due;
-  state.sessions[reference] = session;
-  saveState(harness, state);
-  if (event === "stop" && harness === "codex") {
-    process.stdout.write(JSON.stringify(due
-      ? { systemMessage: "A Shifu sync is due. Prepare an incremental, redacted summary, show exactly what would be sent, and ask the user to confirm before running sync." }
-      : { continue: true }));
-  }
+  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.`);
 }
 
 function textIsSafe(value, maximum) {
-  return typeof value === "string" && value.trim().length > 0 && value.length <= maximum && !SENSITIVE_PATTERNS.some((pattern) => value.toLowerCase().includes(pattern));
+  return typeof value === "string" && value.trim().length > 0 && value.length <= maximum && !/[\x00-\x1f\x7f]/.test(value) && !PHONE_NUMBER_PATTERN.test(value) && !UNSAFE_CODE_PATTERN.test(value) && !CREDENTIAL_ASSIGNMENT_PATTERN.test(value) && !CLOUD_CREDENTIAL_PATTERN.test(value) && !SENSITIVE_PATTERNS.some((pattern) => value.toLowerCase().includes(pattern));
 }
 
 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 || typeof input.sessionRef !== "string" || !textIsSafe(input.sessionRef, 200) || input.sessionRef.length < 8) 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) throw new Error("Use a valid incremental turn range.");
+  if (!Number.isInteger(input.fromTurn) || !Number.isInteger(input.toTurn) || input.fromTurn < 1 || input.toTurn < input.fromTurn || input.toTurn - input.fromTurn >= MAX_TURNS_PER_SEGMENT) throw new Error("Use a valid incremental range of at most 12 turns.");
+  if (input.redactionVersion === 3 && !textIsSafe(input.title, MAX_TITLE_LENGTH)) throw new Error("Add a concise, redacted title for this reviewed sync.");
   if (!textIsSafe(input.summary, 1200)) throw new Error("The summary is empty, too long, or contains sensitive content. Redact it before syncing.");
-  for (const field of ["evidence", "decisions"]) {
-    if (!Array.isArray(input[field]) || input[field].length > 4 || !input[field].every((item) => textIsSafe(item, 240))) throw new Error(`${field} must contain at most four redacted statements.`);
+  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.`);
   }
-  if (input.redactionVersion !== 1) throw new Error("Use redactionVersion 1.");
+  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.`);
+  }
+  if (!input.evidence.every((item) =>
+    Object.keys(item).every((field) => EVIDENCE_FIELDS.has(field)) &&
+    (!Object.hasOwn(item, "area") || item.area === "" || WORK_AREAS.has(item.area)) &&
+    (!Object.hasOwn(item, "itemRef") || item.itemRef === "" || (typeof item.itemRef === "string" && ITEM_REF_PATTERN.test(item.itemRef))) &&
+    (!Object.hasOwn(item, "verificationRefs") || (Array.isArray(item.verificationRefs) &&
+      new Set(item.verificationRefs).size === item.verificationRefs.length &&
+      item.verificationRefs.every((ref) => Number.isInteger(ref) && ref >= 0 && ref < input.verification.length))))) {
+    throw new Error("Each work item must use a supported area, safe itemRef, and distinct indexes into verification.");
+  }
+  if (input.redactionVersion !== 2 && input.redactionVersion !== 3) throw new Error("Use redactionVersion 3 for new reviewed syncs.");
+}
+
+function validSyncReceipt(receipt, input) {
+  return receipt?.sessionRef === input.sessionRef && receipt.acceptedToTurn === input.toTurn && Number.isInteger(receipt.lastSyncedTurn) &&
+    (receipt.duplicate ? receipt.lastSyncedTurn >= input.toTurn : receipt.lastSyncedTurn === input.toTurn);
 }
 
 async function sync(harness) {
@@ -258,15 +436,23 @@ async function sync(harness) {
     console.error("Nothing was sent.");
     return;
   }
-  const 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),
-  });
+  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;
-  if (!receipt || !Number.isInteger(receipt.lastSyncedTurn)) throw new Error("Shifu did not return a sync checkpoint.");
+  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}.`);
@@ -275,7 +461,59 @@ async function sync(harness) {
 function status(harness) {
   const config = readConfig(harness);
   const state = readState(harness);
-  console.log(JSON.stringify({ harness, apiUrl: config.apiUrl, schedule: config.schedule, sessions: state.sessions }, null, 2));
+  console.log(JSON.stringify({ harness, apiUrl: config.apiUrl, sessions: state.sessions }, null, 2));
+}
+
+function sessions(harness) {
+  readConfig(harness);
+  const hours = numberOption("--hours", 24);
+  const turns = numberOption("--turns", MAX_TURNS_PER_SEGMENT);
+  const sessionRef = option("--session-ref");
+  const all = hasFlag("--all");
+  if (all && !sessionRef) throw new Error("Use --all only with an explicitly selected --session-ref.");
+  const pending = unsyncedCodexSessions(harness, hours, turns, sessionRef, all);
+  const blocked = all ? [] : unsyncedCodexSessions(harness, hours, turns, sessionRef, true)
+    .filter((session) => !pending.some((item) => item.sessionRef === session.sessionRef))
+    .map(({ sessionRef, oldestUnsyncedAt }) => ({ sessionRef, oldestUnsyncedAt }));
+  console.log(JSON.stringify({ harness, hours, turns, sessions: pending, blockedSessions: blocked }, null, 2));
+}
+
+function review(harness) {
+  if (harness !== "codex") throw new Error("Session review is currently available for Codex only.");
+  readConfig(harness);
+  const sessionRef = option("--session-ref");
+  if (typeof sessionRef !== "string" || sessionRef.length < 8) throw new Error("Provide an opaque Codex --session-ref from the sessions command.");
+  const state = readState(harness);
+  const fromTurn = (state.sessions[sessionRef]?.lastSyncedTurn || 0) + 1;
+  const matchingFiles = sessionFiles(codexSessionsRoot())
+    .map((file) => ({ file, session: codexSession(file) }))
+    .filter(({ session }) => session?.sessionRef === sessionRef)
+    .sort((left, right) => right.session.turnCount - left.session.turnCount || right.session.updatedAt.localeCompare(left.session.updatedAt));
+  const selected = matchingFiles[0];
+  if (!selected) throw new Error("No local Codex session matches this reference.");
+  const hours = numberOption("--hours", 24);
+  if (![24, 48, 72].includes(hours)) throw new Error("Choose --hours 24, 48, or 72.");
+  if (!hasFlag("--all") && !(Date.parse(selected.session.turnTimes[fromTurn - 1]) >= Date.now() - hours * 3_600_000)) {
+    throw new Error("This session's next unsynced turn predates the selected window. Ask for this specific session and use --all to review its backlog.");
+  }
+  const turns = numberOption("--turns", MAX_TURNS_PER_SEGMENT);
+  if (!Number.isInteger(turns) || turns < 1 || turns > MAX_TURNS_PER_SEGMENT) throw new Error("Choose --turns between 1 and 12.");
+  const toTurn = Math.min(selected.session.turnCount, fromTurn + turns - 1);
+  if (fromTurn > toTurn) throw new Error("This Codex session has no unsynced turns to review.");
+  const { notes } = codexReview(selected.file, fromTurn, toTurn);
+  const candidates = reviewCandidates(notes);
+  console.log(JSON.stringify({
+    sessionRef,
+    fromTurn,
+    toTurn,
+    oldestUnsyncedAt: selected.session.turnTimes[fromTurn - 1] || null,
+    source: "Local assistant final notes for unsynced user turns. Candidates are suggestions, not verified or guaranteed redacted; inspect them before constructing a Shifu payload.",
+    notes,
+    candidates,
+    draft: { title: null, summary: null, evidence: candidates.map((candidate) => ({ ...candidate, title: null })) },
+    candidateOverflow: candidates.length > MAX_EVIDENCE_ITEMS,
+    remainingTurns: selected.session.turnCount - toTurn,
+  }, null, 2));
 }
 
 async function main() {
@@ -283,19 +521,20 @@ async function main() {
   const harness = requireHarness(option("--harness"));
   if (command === "install") return install(harness);
   if (command === "connect") return connect(harness);
-  if (command === "activate") return activate(harness);
-  if (command === "schedule") return schedule(harness);
   if (command === "sync") return sync(harness);
   if (command === "status") return status(harness);
-  if (command === "hook") return hook(harness, option("--event"));
-  throw new Error("Use install, connect, activate, schedule, sync, status, or hook.");
+  if (command === "sessions") return sessions(harness);
+  if (command === "review") return review(harness);
+  throw new Error("Use install, connect, status, sessions, review, or sync.");
 }
 
 if (require.main === module) {
-  main().catch((error) => {
-    console.error(error.message);
-    process.exitCode = 1;
-  });
+  main()
+    .then(() => process.exit(0))
+    .catch((error) => {
+      console.error(error.message);
+      process.exit(1);
+    });
 }
 
-module.exports = { addHook, configPath, statePath, textIsSafe, validateSync };
+module.exports = { codexReview, codexSession, configPath, finalAssistantNote, readSecret, removeHooks, requireSafeApiUrl, reviewCandidates, statePath, textIsSafe, unsyncedCodexSessions, validSyncReceipt, validateSync };

package/commands/shifu-sync.md

@@ -8,4 +8,4 @@ Use the Shifu reviewed-sync process for the current OpenCode session. Never uplo
 npx @useshifu/coding-harness sync --harness opencode
 ```
 
-The payload must contain `harness`, an opaque `sessionRef`, `fromTurn`, `toTurn`, a concise redacted `summary`, up to four redacted `evidence` items, up to four redacted `decisions`, and `redactionVersion: 1`. Replace names, paths, URLs, credentials, commands, prompts, source code, customer details, and proprietary identifiers with neutral descriptions.
+The payload must contain `harness`, an opaque `sessionRef`, a contiguous `fromTurn`/`toTurn` range of at most 12 turns, 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, paths, URLs, credentials, commands, prompts, source code, customer details, and proprietary identifiers with neutral descriptions.

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@useshifu/coding-harness",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Reviewed, incremental coding-harness sync for Shifu",
   "bin": {
+    "coding-harness": "bin/shifu-harness.js",
     "shifu-harness": "bin/shifu-harness.js"
   },
   "files": [

package/skills/shifu-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shifu-sync
-description: Prepare and sync a reviewed, redacted incremental summary of the current coding session to Shifu. Use only when the user explicitly asks to connect, activate, schedule, sync, or push their Shifu coding-harness data.
+description: Prepare and sync reviewed, redacted Codex work from the user's selected recent time window to Shifu. Use only when the user explicitly asks to connect, sync, or push their Shifu coding-harness data.
 ---
 
 Shifu captures reviewed, incremental work context. It does not collect raw transcripts or upload in the background.
@@ -8,15 +8,15 @@ Shifu captures reviewed, incremental work context. It does not collect raw trans
 Before taking any action, state the exact action and ask the user for confirmation:
 
 - `connect`: explain that the command saves the supplied connection key locally and does not send session content.
-- `activate`: explain that it adds local lifecycle hooks. Hooks can mark a sync as due, but never upload automatically.
-- `schedule`: explain the turn and time thresholds. A threshold asks for review on the next active harness turn; it cannot interrupt an ended session with a dialog.
 - `sync`: show the exact JSON payload, including its incremental `fromTurn` and `toTurn`, then ask whether to send it.
 
-Before preparing a sync, run `npx @useshifu/coding-harness status --harness codex` to see the local checkpoint. Use its most recent opaque `lastSessionRef` and begin at `lastSyncedTurn + 1`. Do not guess a checkpoint or claim to be syncing the whole conversation when an earlier segment is still pending.
+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.
 
-For a manual request such as “push this conversation,” prepare only the unsynced segment. Make the content concise and useful, preserving technical decisions, outcome, evidence, and verification. 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.
+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 a turn or time reminder appears, first decide whether the unsynced work forms a coherent, useful segment. If it does not, keep the segment pending and continue the session without prompting or sending anything. A reminder is never permission to upload.
+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. Each `evidence` item must be a factual, redacted work item describing what was created, changed, or deliberately decided and which component was involved. Choose its smallest supported scope: `unit`, `module`, `service`, `system`, or `product`; the candidate's null scope is not a classification. Put tests, builds, reviews, and other checks only in `verification`. Do not claim impact, ownership, outcome, or a broader scope without direct support. 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. Approved work-item statements are retained in Shifu's private claims, so review their wording as durable content.
+
+Do not install or rely on lifecycle hooks or background reminders. A sync is always initiated by an explicit user request.
 
 Use this structure:
 
@@ -26,10 +26,12 @@ Use this structure:
   "sessionRef": "opaque-session-id",
   "fromTurn": 1,
   "toTurn": 12,
+  "title": "Hardened connector checkpoints",
   "summary": "Implemented a narrow change and checked the relevant behaviour.",
-  "evidence": ["Focused tests passed."],
+  "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": 1
+  "redactionVersion": 3
 }
 ```