@useshifu/coding-harness 0.3.6 → 0.3.8

package/README.md

@@ -20,7 +20,7 @@ For named meeting transcripts, set your display name in Shifu Profile so your sp
 
 The shortcuts are symlinks to the same folder, not additional watched folders. An existing conflicting `Shifu` item is left untouched and reported. To choose another existing, readable folder, use `--input-folder <path>` with `connect` or `config update`; Shifu checks the path before saving the change. No macOS permission flow is required by the CLI.
 
-No content is sent during setup. Every `connect` asks for a connection key and verifies it with Shifu for the chosen coding tool before saving it or reporting success. An invalid key or unreachable server leaves the existing connection unchanged. Replacing a key resets local checkpoints so existing work can be reconsidered for the new connection; the selected sync policy remains. If a coding tool cannot run `npx` or accept hidden input in its tool terminal, run the same command in your own interactive terminal and check the confirmation output. Change the choices later with:
+No content is sent during setup. Every `connect` asks for a connection key using a normal terminal prompt, so the key is visible as you type or paste it. The key is verified with Shifu for the chosen coding tool before saving it or reporting success. An invalid key or unreachable server leaves the existing connection unchanged. Replacing a key resets local checkpoints so existing work can be reconsidered for the new connection; the selected sync policy remains. If a coding tool cannot run `npx` or accept input in its tool terminal, run the same command in your own interactive terminal and check the confirmation output. Change the choices later with:
 
 ```sh
 npx --yes @useshifu/coding-harness config update --harness <codex|claude_code|opencode> --interval-hours 1 --approval-mode automatic --input-folder ~/Desktop/Shifu
@@ -41,13 +41,19 @@ npx --yes @useshifu/coding-harness approve --harness codex
 npx --yes @useshifu/coding-harness sync-files --harness codex
 ```
 
+To select by session count instead of a time window, run `sessions --harness codex --count 5`. It selects the five most recently updated eligible sessions, newest first, without an hours cutoff. Current and setup sessions are excluded. `selectedSessionRefs` fixes that selection; `sessions` contains pending segments and `skippedSessions` reports already-synced sessions. Skipped sessions are not replaced with older ones. Review each pending session with `review --harness codex --session-ref <sessionRef> --all`. After an accepted segment, request the next with `sessions --harness codex --session-ref <sessionRef> --all` until that selected session is exhausted. Keep the original references instead of selecting another five.
+
+Manual session sync runs immediately, independently of the hourly schedule. If a segment fails, report it as failed/pending; a checkpoint advances only after a matching server receipt. Report completed, already-synced, and failed session counts separately.
+
+To upgrade an existing installation, run `npx --yes @useshifu/coding-harness@latest install --harness codex` (or `claude_code` / `opencode`). It replaces the local runner and harness instruction while preserving the connection, checkpoints, and schedule. Reconnecting is unnecessary. `status` includes `runnerVersion` so you can verify the installed version.
+
 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 same scheduled run checks the input folder. `sync-files` checks it immediately without changing the schedule. Before sending new or changed files, the runner polls unfinished jobs from its local checkpoints. It sends supported file bytes over the configured HTTPS connection (or localhost HTTP for development). The server accepts each file as a background job and processes its text in chunks; upload does not wait for claim extraction. A later scheduled or manual sync polls the job's result. Only `processed`, `no_claims`, or `duplicate` finalizes the local checkpoint; `partial` reopens failed chunks on the next sync. On this upgrade, completed file checkpoints are replayed once so the new extraction can retain suggestions; in-flight jobs are polled first and replayed after finishing. Server-side idempotency prevents already published claims from being duplicated. Files larger than 20 MB remain pending with an error. The scanner reads regular files directly in the chosen folder and ignores symlinks and subfolders. Unknown formats are reported as unsupported rather than treated as successful syncs.
 
 The file-job result reports published claims separately from needs-evidence suggestions. A `no_claims` result can still contain suggestions: these are possible contributions awaiting evidence or attribution, not verified claims. The runner reports the suggestion count but never labels those suggestions as established work. It does not print the file's text, candidate statements, or source excerpts to logs. Use Shifu to inspect the suggestions and their evidence status. A result with zero claims and zero suggestions means no user-attributable contribution was extracted; it does not mean the upload failed.
 
-The connector captures supported harness work in engineering, product discovery, writing, interview feedback, research, and planning. Automatic sync turns completed actions and known work topics into separate controlled statements without sending source prose. If a segment has no supported work items, it advances the checkpoint without creating a claim. Version 1–3 clients remain supported.
+The connector captures supported harness work in engineering, product discovery, writing, interview feedback, research, and planning. Automatic sync turns completed actions, known work topics, descriptive feature or project types, and supported problem or approach details into separate controlled statements without sending source prose or raw names. If a segment has no supported work items, it advances the checkpoint without creating a claim. Version 1–3 clients remain supported.
 
 ## Sync a prepared payload
 

package/bin/shifu-harness.js

@@ -6,7 +6,6 @@ const os = require("node:os");
 const path = require("node:path");
 const { execFileSync } = require("node:child_process");
 const readline = require("node:readline/promises");
-const tty = require("node:tty");
 
 const DEFAULT_API_URL = "https://api.useshifu.com";
 const HARNESS_NAMES = {
@@ -38,6 +37,7 @@ const MAX_TURNS_PER_SEGMENT = 12;
 const MAX_TITLE_LENGTH = 160;
 const MAX_WORK_DETAIL_LENGTH = 600;
 const CONFIG_VERSION = 2;
+const RUNNER_VERSION = "0.3.8";
 const REDACTION_VERSION = 4;
 const DEFAULT_INTERVAL_HOURS = 1;
 const LEGACY_INTERVAL_HOURS = 4;
@@ -588,23 +588,107 @@ const WORK_OBJECTS = [
   { key: "planning", title: "project plan", pattern: /\b(?:roadmap|project plan|delivery plan)\b/i },
 ];
 
+// Only controlled feature descriptions leave the device during unattended sync.
+const WORK_CONTEXTS = [
+  { key: "payment_reconciliation", title: "payment reconciliation flow", phrase: "a payment reconciliation flow", pattern: /\bpayment reconciliation\b/i },
+  { key: "payment", title: "payment flow", phrase: "a payment flow", pattern: /\b(?:payment|payments|payout|payouts)\b/i },
+  { key: "checkout", title: "checkout flow", phrase: "a checkout flow", pattern: /\bcheckout\b/i },
+  { key: "billing", title: "billing flow", phrase: "a billing flow", pattern: /\b(?:billing|invoic(?:e|es|ing)|subscription|subscriptions)\b/i },
+  { key: "reconciliation", title: "reconciliation flow", phrase: "a reconciliation flow", pattern: /\breconciliation\b/i },
+  { key: "onboarding", title: "onboarding flow", phrase: "an onboarding flow", pattern: /\bonboarding\b/i },
+  { key: "search", title: "search experience", phrase: "a search experience", pattern: /\bsearch\b/i },
+  { key: "notification", title: "notification flow", phrase: "a notification flow", pattern: /\bnotifications?\b/i },
+  { key: "reporting", title: "reporting feature", phrase: "a reporting feature", pattern: /\b(?:reporting|reports)\b/i },
+  { key: "messaging", title: "messaging feature", phrase: "a messaging feature", pattern: /\bmessaging\b/i },
+  { key: "file_upload", title: "file upload flow", phrase: "a file upload flow", pattern: /\b(?:file uploads?|document uploads?)\b/i },
+  { key: "scheduling", title: "scheduling flow", phrase: "a scheduling flow", pattern: /\b(?:scheduling|booking)\b/i },
+  { key: "analytics", title: "analytics feature", phrase: "an analytics feature", pattern: /\banalytics\b/i },
+  { key: "data_import", title: "data import flow", phrase: "a data import flow", pattern: /\b(?:data import|csv import|bulk import)\b/i },
+  { key: "document_processing", title: "document processing flow", phrase: "a document processing flow", pattern: /\bdocument processing\b/i },
+];
+
+const WORK_DETAILS = [
+  { title: "timeouts", pattern: /\btimeouts?\b/i },
+  { title: "duplicates", pattern: /\bduplicat(?:e|es|ed|ion)\b/i },
+  { title: "stale data", pattern: /\bstale (?:data|results?|cache)\b/i },
+  { title: "race conditions", pattern: /\brace conditions?\b/i },
+  { title: "data loss", pattern: /\bdata loss\b/i },
+  { title: "latency", pattern: /\b(?:latency|slow responses?)\b/i },
+  { title: "idempotency", pattern: /\bidempoten(?:t|cy)\b/i },
+  { title: "backoff", pattern: /\bbackoff\b/i },
+  { title: "validation", pattern: /\bvalidat(?:e|ed|ion|ing)\b/i },
+  { title: "pagination", pattern: /\bpaginat(?:e|ed|ion|ing)\b/i },
+  { title: "batching", pattern: /\bbatch(?:es|ed|ing)?\b/i },
+  { title: "rate limiting", pattern: /\brate limit(?:s|ing|ed)?\b/i },
+  { title: "deduplication", pattern: /\bdedupl?icat(?:e|ed|ion|ing)\b/i },
+  { title: "fallback behavior", pattern: /\bfallback\b/i },
+  { title: "accessibility", pattern: /\baccessibility\b/i },
+  { title: "mobile layout", pattern: /\bmobile layout\b/i },
+];
+
+function controlledContexts(text) {
+  const matches = WORK_CONTEXTS.flatMap((item) => {
+    const match = item.pattern.exec(text);
+    if (!match) return [];
+    const type = text.slice(match.index + match[0].length).match(/^\s+(service|platform|system|feature|project|workflow|flow|experience)\b/i)?.[1];
+    if (!type) return [item];
+    const title = `${item.title.replace(/ (?:flow|feature|experience)$/, "")} ${type.toLowerCase()}`;
+    return [{ ...item, title, phrase: `${item.phrase.startsWith("an ") ? "an" : "a"} ${title}` }];
+  });
+  const contexts = matches.some((item) => item.key === "payment_reconciliation") ? matches.filter((item) => item.key !== "payment" && item.key !== "reconciliation") : matches;
+  return contexts.length <= 2 ? contexts : null;
+}
+
+function controlledDetails(text) {
+  return WORK_DETAILS.map((item) => ({ item, index: item.pattern.exec(text)?.index }))
+    .filter(({ index }) => index !== undefined)
+    .sort((left, right) => left.index - right.index)
+    .slice(0, 3)
+    .map(({ item }) => item.title);
+}
+
+function withoutNamedLabels(text) {
+  return text.replace(/\b(?:Project|Client|Customer|Company)\s+[A-Z][A-Za-z0-9_-]*/g, "");
+}
+
 function safeActivityEvidence(notes) {
   const evidence = [];
   const seen = new Set();
   for (const [noteIndex, { turn, note }] of notes.entries()) {
     let inCodeBlock = false;
+    let sectionContexts = [];
     for (const [lineIndex, rawLine] of note.split("\n").entries()) {
       if (rawLine.trim().startsWith("```")) { inCodeBlock = !inCodeBlock; continue; }
       if (inCodeBlock) continue;
+      const heading = rawLine.trim().match(/^(?:#{1,6}\s+(.+)|\*\*(.+)\*\*:?\s*)$/);
+      if (heading) {
+        const label = withoutNamedLabels(heading[1] || heading[2]);
+        sectionContexts = /\b(?:project|feature|flow|service|system|product)\b/i.test(label) ? controlledContexts(label) || [] : [];
+        continue;
+      }
       const line = rawLine.trim().replace(/^[-*]\s+/, "").split(/[.;—]/, 1)[0];
+      const clauses = line.split(/\s+(?:and|but|while)\s+/i);
+      const nextAction = clauses.findIndex((clause, index) => index > 0 && WORK_ACTIONS.some((item) => item.pattern.test(clause)));
+      const workClause = withoutNamedLabels(nextAction > 0 ? clauses.slice(0, nextAction).join(" and ") : line);
       const action = WORK_ACTIONS.find((item) => item.pattern.test(line));
-      const object = WORK_OBJECTS.find((item) => item.pattern.test(line));
+      const detailSource = workClause.split(/\b(?:about|titled)\b/i, 1)[0];
+      const contexts = controlledContexts(detailSource);
+      const featureContexts = contexts === null ? [] : contexts.length ? contexts : sectionContexts;
+      let object;
+      let objectPosition = Infinity;
+      for (const item of WORK_OBJECTS) {
+        const match = item.pattern.exec(workClause);
+        if (match && match.index < objectPosition) { object = item; objectPosition = match.index; }
+      }
+      object ||= featureContexts[0];
       if (!action || !object) continue;
-      const key = `${action.key}:${object.key}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      const title = `${action.title} ${object.title}`;
-      evidence.push({ kind: "activity", title, statement: `${title}.`, itemRef: `t${turn}_n${noteIndex + 1}_l${lineIndex + 1}` });
+      const context = ["interview_feedback", "professional_post"].includes(object.key) ? [] : featureContexts.filter((item) => item !== object);
+      const details = controlledDetails(detailSource).filter((detail) => !object.title.includes(detail));
+      const title = `${action.title} ${object.title}${context.length ? ` for ${context.map((item) => item.phrase).join(" and ")}` : ""}`;
+      const statement = `${title}${details.length ? ` (${details.join(", ")})` : ""}.`;
+      if (seen.has(statement)) continue;
+      seen.add(statement);
+      evidence.push({ kind: "activity", title, statement, itemRef: `t${turn}_n${noteIndex + 1}_l${lineIndex + 1}` });
       if (evidence.length === MAX_EVIDENCE_ITEMS) return evidence;
     }
   }
@@ -615,8 +699,8 @@ function payloadForSegment(harness, segment) {
   const { notes } = reviewSegment(harness, segment.sessionRef, segment.fromTurn, segment.toTurn);
   const evidence = safeActivityEvidence(notes);
   const title = evidence.length ? evidence[0].title : "No supported work identified";
-  const summary = evidence.length > 1 ? `${evidence[0].statement} ${evidence.length - 1} more supported work items.` :
-    evidence.length === 1 ? evidence[0].statement : "This range had no supported work items.";
+  const summary = evidence.length ? `${evidence.slice(0, 3).map((item) => item.statement).join(" ")}${evidence.length > 3 ? ` ${evidence.length - 3} more supported work items.` : ""}` :
+    "This range had no supported work items.";
   return {
     harness,
     sessionRef: segment.sessionRef,
@@ -754,8 +838,9 @@ function validateGeneratedProfile(profile, harness) {
   }
 }
 
-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.");
+function selectedSessionSegments(harness, { hours = 24, turns = MAX_TURNS_PER_SEGMENT, selectedRef, includeOlder = false, count } = {}) {
+  if (count === undefined && ![24, 48, 72].includes(hours)) throw new Error("Choose --hours 24, 48, or 72.");
+  if (count !== undefined && (!Number.isSafeInteger(count) || count < 1)) throw new Error("Choose a positive whole number for --count.");
   if (!Number.isInteger(turns) || turns < 1 || turns > MAX_TURNS_PER_SEGMENT) throw new Error("Choose --turns between 1 and 12.");
   const since = Date.now() - hours * 3_600_000;
   const state = readState(harness);
@@ -765,7 +850,7 @@ function unsyncedCodexSessions(harness, hours, turns = MAX_TURNS_PER_SEGMENT, se
   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)) {
+    .filter((session) => selectedRef ? session.sessionRef === selectedRef : count !== undefined || Date.parse(session.updatedAt) >= since)) {
     const existing = sessions.get(session.sessionRef);
     sessions.set(session.sessionRef, existing ? {
       ...session,
@@ -776,7 +861,10 @@ function unsyncedCodexSessions(harness, hours, turns = MAX_TURNS_PER_SEGMENT, se
     } : session);
   }
   return [...sessions.values()]
-    .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt))
+    .sort((left, right) => count === undefined
+      ? left.updatedAt.localeCompare(right.updatedAt)
+      : right.updatedAt.localeCompare(left.updatedAt) || left.sessionRef.localeCompare(right.sessionRef))
+    .slice(0, count ?? Infinity)
     .map(({ turnTimes, ...session }) => {
       const checkpoint = state.sessions[session.sessionRef]?.lastSyncedTurn || 0;
       return {
@@ -787,7 +875,11 @@ function unsyncedCodexSessions(harness, hours, turns = MAX_TURNS_PER_SEGMENT, se
         oldestUnsyncedAt: turnTimes[checkpoint] || null,
       };
     })
-    .filter((session) => session.fromTurn <= session.toTurn && (includeOlder || Date.parse(session.oldestUnsyncedAt) >= since));
+    .filter((session) => count !== undefined || includeOlder || Date.parse(session.oldestUnsyncedAt) >= since);
+}
+
+function unsyncedCodexSessions(harness, options = {}) {
+  return selectedSessionSegments(harness, options).filter((session) => session.fromTurn <= session.toTurn);
 }
 
 function pendingSegments(harness) {
@@ -833,41 +925,17 @@ async function confirm(question) {
   }
 }
 
-async function readSecret(input = process.stdin) {
-  const ownsInput = !input.isTTY;
-  if (ownsInput) {
-    let descriptor;
-    try { descriptor = fs.openSync(process.platform === "win32" ? "CONIN$" : "/dev/tty", "r"); }
-    catch { throw new Error("This terminal cannot accept a hidden connection key. Run connect in your own interactive terminal."); }
-    input = new tty.ReadStream(descriptor);
+async function readSecret(input = process.stdin, output = process.stderr) {
+  const terminal = readline.createInterface({ input, output });
+  try {
+    const answer = terminal.question("Connection key: ");
+    const closed = new Promise((_, reject) => terminal.once("close", () => reject(new Error("Connection key input closed."))));
+    return await Promise.race([answer, closed]);
+  } catch {
+    throw new Error("Could not read a connection key. Run connect in an interactive terminal.");
+  } finally {
+    terminal.close();
   }
-  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() {
@@ -953,7 +1021,9 @@ function install(harness, quiet = false) {
   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: npx --yes @useshifu/coding-harness connect --harness ${harness}`);
+    console.error(fs.existsSync(configPath(harness))
+      ? "Updated the local runner and sync instruction. Your connection, checkpoints, and schedule were preserved."
+      : `Next: npx --yes @useshifu/coding-harness connect --harness ${harness}`);
   }
 }
 
@@ -1696,7 +1766,7 @@ function status(harness) {
   if (folder) {
     try { unsupportedFiles = scanWorkFiles(folder).unsupported; } catch (error) { inputFolderError = error.message; }
   }
-  console.log(JSON.stringify({ harness, apiUrl: config.apiUrl, inputFolder: folder, inputFolderError, syncPolicy: normalizedPolicy(config), schedule: state.schedule || null, pendingSegments: pending.segments.length, completedFiles: entries.filter((entry) => typeof entry === "string").length, pendingFiles: entries.filter((entry) => typeof entry === "object" && entry?.jobId).length, unsupportedFiles, sessions: state.sessions }, null, 2));
+  console.log(JSON.stringify({ harness, runnerVersion: RUNNER_VERSION, apiUrl: config.apiUrl, inputFolder: folder, inputFolderError, syncPolicy: normalizedPolicy(config), schedule: state.schedule || null, pendingSegments: pending.segments.length, completedFiles: entries.filter((entry) => typeof entry === "string").length, pendingFiles: entries.filter((entry) => typeof entry === "object" && entry?.jobId).length, unsupportedFiles, sessions: state.sessions }, null, 2));
 }
 
 async function syncFilesNow(harness) {
@@ -1708,16 +1778,30 @@ async function syncFilesNow(harness) {
 
 function sessions(harness) {
   readConfig(harness);
+  const count = option("--count");
+  if (hasFlag("--count") && count === undefined) throw new Error("Provide a value for --count.");
+  if (count !== undefined && option("--hours") !== undefined) throw new Error("Use either --count or --hours, not both.");
   const hours = numberOption("--hours", 24);
   const turns = numberOption("--turns", MAX_TURNS_PER_SEGMENT);
   const sessionRef = option("--session-ref");
   const all = hasFlag("--all");
+  if (count !== undefined && (sessionRef || all)) throw new Error("Use --count without --session-ref or --all.");
   if (all && !sessionRef) throw new Error("Use --all only with an explicitly selected --session-ref.");
-  const pending = unsyncedCodexSessions(harness, hours, turns, sessionRef, all);
-  const blocked = all ? [] : unsyncedCodexSessions(harness, hours, turns, sessionRef, true)
+  const countValue = count === undefined ? undefined : Number(count);
+  const selected = selectedSessionSegments(harness, { hours, turns, selectedRef: sessionRef, includeOlder: all, count: countValue });
+  const pending = selected.filter((session) => session.fromTurn <= session.toTurn);
+  const blocked = all || count !== undefined ? [] : unsyncedCodexSessions(harness, { hours, turns, selectedRef: sessionRef, includeOlder: true })
     .filter((session) => !pending.some((item) => item.sessionRef === session.sessionRef))
     .map(({ sessionRef, oldestUnsyncedAt }) => ({ sessionRef, oldestUnsyncedAt }));
-  console.log(JSON.stringify({ harness, hours, turns, sessions: pending, blockedSessions: blocked }, null, 2));
+  console.log(JSON.stringify(count === undefined
+    ? { harness, hours, turns, sessions: pending, blockedSessions: blocked }
+    : {
+      harness, count: countValue, order: "latest_to_earliest", turns,
+      selectedSessionRefs: selected.map((session) => session.sessionRef),
+      sessions: pending,
+      skippedSessions: selected.filter((session) => session.fromTurn > session.toTurn)
+        .map(({ sessionRef }) => ({ sessionRef, reason: "already_synced" })),
+    }, null, 2));
 }
 
 function review(harness) {

package/commands/shifu-sync.md

@@ -10,10 +10,11 @@ If manual approval has queued scheduled work, run `pending --harness opencode`,
 
 For an explicit sync-now request:
 
-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 `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 advances the checkpoint without creating a claim.
+1. For a time-window request, run `sessions --harness opencode --hours 24`, using 48 or 72 only when requested. For a request by number of recent sessions, run `sessions --harness opencode --count <count>`; this ignores the hours window and returns the most recently updated sessions first.
+2. Review each returned segment with `review --harness opencode --session-ref <sessionRef> --hours <hours>`. For count-based selection, use `review --harness opencode --session-ref <sessionRef> --all` so older sessions are allowed.
+3. Prepare a redaction-version-four payload from final assistant notes only. Use `activity` evidence for writing, feedback, research, planning, product work, and any work that is not clearly an engineering implementation or decision. Activity evidence has no technical scope. Preserve the supported action, feature or project purpose, specific problem, approach, and verified result. Synthesize a descriptive project label (such as "payment reconciliation service") from its purpose; never copy a raw label that could identify a company or person. Keep distinct contributions separate, including different fixes within one feature. An empty evidence list advances the checkpoint without creating a claim.
 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.
+5. Keep the returned session reference and turn range unchanged. Never upload prompts, raw transcripts, tool output, code, paths, commands, URLs, credentials, company or person names, customer details, or proprietary identifiers.
+6. For a count-based sync, keep `selectedSessionRefs` from the first discovery and review only pending `sessions`. `skippedSessions` reports already-synced selections; do not replace them with older sessions. If one has remaining turns, request its next segment with `sessions --harness opencode --session-ref <sessionRef> --all`. Stop after those selected sessions are exhausted. Report completed, already-synced, and failed/pending sessions separately. Manual sync runs immediately, independently of the hourly schedule.
 
-To connect or replace a key, run `npx --yes @useshifu/coding-harness connect --harness opencode`. Connect asks for a key and verifies it with Shifu before reporting success. If this tool terminal cannot run the command or accept hidden input, ask the user to run it in their own interactive terminal and report the output; do not claim the connection succeeded. To disconnect locally, run `npx --yes @useshifu/coding-harness disconnect --harness opencode`. New connections use one-hour automatic sync and `~/Desktop/Shifu` on macOS by default. To change the interval, approval policy, or folder later, run `config update --harness opencode` with the desired flags (for example, `--input-folder <existing-readable-folder>`).
+To connect or replace a key, run `npx --yes @useshifu/coding-harness connect --harness opencode`. Connect asks for a key with a normal visible terminal prompt and verifies it with Shifu before reporting success. Do not ask the user to paste the key into chat. If this tool terminal cannot run the command or accept input, ask the user to run it in their own interactive terminal and report the output; do not claim the connection succeeded. To disconnect locally, run `npx --yes @useshifu/coding-harness disconnect --harness opencode`. New connections use one-hour automatic sync and `~/Desktop/Shifu` on macOS by default. To change the interval, approval policy, or folder later, run `config update --harness opencode` with the desired flags (for example, `--input-folder <existing-readable-folder>`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useshifu/coding-harness",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Scheduled, redacted coding-harness activity sync for Shifu",
   "bin": {
     "coding-harness": "bin/shifu-harness.js",

package/skills/shifu-sync/SKILL.md

@@ -7,7 +7,7 @@ description: Connect, configure, inspect, or sync coding-harness activity, AI Pr
 
 Shifu records useful work completed through the harness. Work may be engineering, product discovery, writing, interview feedback, research, planning, or another user-directed activity. Do not force non-engineering work into engineering categories.
 
-Never include user prompts, raw transcripts, tool output, source code, commands, credentials, URLs, file paths, names, customer details, or proprietary identifiers in a coding-session payload. The local coding runner reads final assistant notes for career activity and scans user turns locally for fixed AI Profile signals; it sends neither raw source. Files placed in the user's chosen Shifu input folder are a separate path: the runner sends supported files over TLS for server-side parsing and sanitization. Do not describe folder files as locally redacted.
+Never include user prompts, raw transcripts, tool output, source code, commands, credentials, URLs, file paths, company or person names, customer details, or proprietary identifiers in a coding-session payload. Synthesize descriptive project labels from their purpose rather than copying a raw name. The local coding runner reads final assistant notes for career activity and scans user turns locally for fixed AI Profile signals; it sends neither raw source. Files placed in the user's chosen Shifu input folder are a separate path: the runner sends supported files over TLS for server-side parsing and sanitization. Do not describe folder files as locally redacted.
 
 Only describe work attributable to the user. A team action item, meeting discussion, or another person's contribution is not evidence that the user did it. If a final note does not support a specific user contribution, do not invent one.
 
@@ -23,7 +23,7 @@ When the user asks to connect, run:
 npx --yes @useshifu/coding-harness connect --harness codex
 ```
 
-`connect` asks for a key every time and verifies it against Shifu for this harness before reporting success. If this tool terminal cannot run npx or accept hidden input, ask the user to run the command in their own interactive terminal and report its output; do not claim the connection succeeded. It installs the current runner and a local schedule with no policy questions. New connections default to hourly automatic sync and `~/Desktop/Shifu` as the single input folder on macOS. It creates shortcuts at `~/Downloads/Shifu` and `~/Documents/Shifu` when possible without replacing conflicting items. Supported files are `.txt`, `.md`, `.rtf`, and `.docx` up to 20 MB directly inside the folder; images and screenshots are not supported. Unknown formats are counted but never uploaded. Replacing a key resets local checkpoints so work can sync to the new connection. It also excludes the setup session when the harness exposes its current opaque session reference. No content is sent during setup.
+`connect` asks for a key with a normal visible terminal prompt every time and verifies it against Shifu for this harness before reporting success. Do not ask the user to paste the key into chat. If this tool terminal cannot run npx or accept input, ask the user to run the command in their own interactive terminal and report its output; do not claim the connection succeeded. It installs the current runner and a local schedule with no policy questions. New connections default to hourly automatic sync and `~/Desktop/Shifu` as the single input folder on macOS. It creates shortcuts at `~/Downloads/Shifu` and `~/Documents/Shifu` when possible without replacing conflicting items. Supported files are `.txt`, `.md`, `.rtf`, and `.docx` up to 20 MB directly inside the folder; images and screenshots are not supported. Unknown formats are counted but never uploaded. Replacing a key resets local checkpoints so work can sync to the new connection. It also excludes the setup session when the harness exposes its current opaque session reference. No content is sent during setup.
 
 To disconnect locally, run `npx --yes @useshifu/coding-harness disconnect --harness codex`. Tell the user to revoke the old key in Shifu if they no longer want it usable.
 
@@ -53,17 +53,19 @@ Show the returned list and ask for one approval for the whole list. After approv
 
 ## Sync now
 
-For an explicit sync request, first read `status` to determine the saved approval mode. Use the time window the user names; otherwise use 24 hours. Supported interactive windows are 24, 48, and 72 hours.
+For an explicit sync request, first read `status` to determine the saved approval mode. Manual sync runs immediately and does not wait for the hourly schedule. Use the time window the user names; otherwise use 24 hours. Supported interactive windows are 24, 48, and 72 hours. If the user specifies a number of recent sessions, use count-based selection instead; it has no hours cutoff and orders sessions from latest to earliest. It selects the latest eligible sessions, excluding current/setup sessions, and reports already-synced selections in `skippedSessions` without replacing them with older sessions.
 
-1. Run `npx --yes @useshifu/coding-harness sessions --harness codex --hours <24|48|72>`.
+1. For a time-window sync, run `npx --yes @useshifu/coding-harness sessions --harness codex --hours <24|48|72>`. For a count-based sync, run `npx --yes @useshifu/coding-harness sessions --harness codex --count <count>`; do not add `--hours`.
 2. Ignore `blockedSessions` unless the user specifically selects one. For a selected older backlog, add `--session-ref <sessionRef> --all`.
-3. For each returned segment, run `npx --yes @useshifu/coding-harness review --harness codex --session-ref <sessionRef> --hours <24|48|72>`.
+3. For each returned segment, run `npx --yes @useshifu/coding-harness review --harness codex --session-ref <sessionRef> --hours <24|48|72>`. For count-based selection, use `--all` instead of `--hours` so the review has no time cutoff.
 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.
+6. For a time-window sync, repeat discovery after accepted segments until the selected window is exhausted. For a count-based sync, keep `selectedSessionRefs` from the first discovery and review only pending `sessions`. If a selected session has remaining turns, request its next segment with `sessions --harness codex --session-ref <sessionRef> --all`; stop after those selected sessions are exhausted. Report completed, already-synced, and failed/pending sessions separately. A failed session does not count as completed.
 
 Use `kind: "activity"` for general harness work; it does not require a technical scope. Use `implementation` or `decision` only when the note clearly supports that engineering classification, and then use the smallest reviewed scope among `unit`, `module`, `service`, `system`, and `product`. Evidence may be empty when the safe final note supports only a session-level title and summary. Never invent impact, ownership, verification, or outcomes.
 
+Make each supported item useful for later recall: retain the user's action, the feature or project purpose, the specific problem, the approach, and a verified result when the final note supports each part. A descriptive project label such as "payment reconciliation service" is useful; synthesize it from the work's purpose instead of copying a raw project label that might contain a company or person's name. Keep distinct contributions separate, including two fixes in one feature that addressed different problems. Omit names of companies and people, customer details, proprietary identifiers, paths, code snippets, and unsupported impact. If a detail cannot be safely described, keep the supported parts. Prefer a summary that names the main distinct work items over a generic count alone.
+
 ```json
 {
   "harness": "codex",