@useshifu/coding-harness 0.3.7 → 0.3.9

package/README.md

@@ -41,6 +41,12 @@ 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.

package/bin/shifu-harness.js

@@ -37,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.9";
 const REDACTION_VERSION = 4;
 const DEFAULT_INTERVAL_HOURS = 1;
 const LEGACY_INTERVAL_HOURS = 4;
@@ -837,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);
@@ -848,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,
@@ -859,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 {
@@ -870,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) {
@@ -1012,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}`);
   }
 }
 
@@ -1755,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) {
@@ -1767,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>`.
+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, 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 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.7",
+  "version": "0.3.9",
   "description": "Scheduled, redacted coding-harness activity sync for Shifu",
   "bin": {
     "coding-harness": "bin/shifu-harness.js",

package/skills/shifu-sync/SKILL.md

@@ -53,14 +53,14 @@ 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.