@damiangilgonzalez/harness 1.3.17 → 1.3.19

package/targets/session-memory-core.mjs

@@ -1,5 +1,5 @@
 import {
-  appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync,
+  appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync,
 } from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
@@ -84,21 +84,27 @@ export function chooseMemoryRoot(cwd = process.cwd()) {
     return { root: join(project, '.rsc', 'memory'), kind: 'local-state', reason: 'without-git', git: false };
   }
 
+  // The harness itself commits `worklog/.gitkeep` so the folder exists in every clone. A placeholder
+  // is not the team committing its worklog, and reading it as one warned every teammate in every clone
+  // about a tracked worklog that was an empty file (team simulation D13).
   const worklog = join(project, 'docs', 'raw', 'worklog');
-  if (existsSync(worklog)) {
-    const tracked = git(project, ['ls-files', '--', 'docs/raw/worklog']).out;
-    if (!tracked) {
-      const candidate = join(worklog, '.rsc-memory');
-      if (ensureExcluded(project, candidate)) {
-        return { root: candidate, kind: 'wiki-worklog', reason: 'untracked-worklog', git: true };
-      }
+  const local = join(project, '.rsc', 'memory');
+  const trackedFiles = existsSync(worklog)
+    ? git(project, ['ls-files', '--', 'docs/raw/worklog']).out.split('\n').filter(Boolean) : [];
+  const trackedNotes = trackedFiles.filter((file) => !/(^|\/)\.(gitkeep|keep)$/u.test(file));
+  // A clone whose journal already lives in .rsc/memory keeps it there: moving would orphan its history.
+  const placeholderOnly = trackedFiles.length > 0 && trackedNotes.length === 0;
+  const settled = placeholderOnly && existsSync(join(local, 'sessions'));
+  if (existsSync(worklog) && !trackedNotes.length && !settled) {
+    const candidate = join(worklog, '.rsc-memory');
+    if (ensureExcluded(project, candidate)) {
+      return { root: candidate, kind: 'wiki-worklog', reason: 'untracked-worklog', git: true };
     }
   }
 
-  const local = join(project, '.rsc', 'memory');
   if (ensureExcluded(project, local)) {
-    const trackedWorklog = existsSync(worklog) && Boolean(git(project, ['ls-files', '--', 'docs/raw/worklog']).out);
-    return { root: local, kind: 'local-state', reason: trackedWorklog ? 'tracked-worklog' : 'no-wiki', git: true };
+    const reason = trackedNotes.length ? 'tracked-worklog' : settled ? 'placeholder-worklog' : 'no-wiki';
+    return { root: local, kind: 'local-state', reason, git: true };
   }
 
   const gitRoot = git(project, ['rev-parse', '--git-path', 'rsc-memory']).out;
@@ -109,7 +115,7 @@ export function chooseMemoryRoot(cwd = process.cwd()) {
 }
 
 function ensureStore(root) {
-  for (const dir of ['sessions', 'anchors', 'lessons']) mkdirSync(join(root, dir), { recursive: true });
+  for (const dir of ['sessions', 'anchors', 'lessons', 'presence']) mkdirSync(join(root, dir), { recursive: true });
 }
 
 function atomicJson(path, value) {
@@ -167,20 +173,35 @@ function parseStatus(output) {
 // runs on every hook event: a few hundred dirty files were enough to blow the 5 s hook timeout.
 // `--stdin-paths` stops at the first path it cannot read (a deleted file), so on failure each file
 // is hashed on its own, which keeps the old per-file `null` for the unreadable ones.
+//
+// A deleted file is the ordinary case, not the exotic one — any `rm` or `git rm` puts one in the
+// status — and it used to send EVERY file down the per-file path, back over the timeout (400 dirty
+// files and one deletion: ~20 s per event, so PreCompact was cancelled). So paths that are not a
+// readable regular file are settled here, as `null`, before the batch ever sees them.
 function fingerprintFiles(worktree, files) {
   if (!files.length) return {};
-  const batch = git(worktree, ['hash-object', '--no-filters', '--stdin-paths'], `${files.join('\n')}\n`);
+  const readable = files.filter((path) => {
+    try { return statSync(join(worktree, path)).isFile(); } catch { return false; }
+  });
+  const isReadable = new Set(readable);
+  const missing = Object.fromEntries(files.filter((path) => !isReadable.has(path)).map((path) => [path, null]));
+  if (!readable.length) return missing;
+  const batch = git(worktree, ['hash-object', '--no-filters', '--stdin-paths'], `${readable.join('\n')}\n`);
   const hashes = batch.ok ? batch.out.split('\n') : [];
-  if (hashes.length === files.length) return Object.fromEntries(files.map((path, i) => [path, hashes[i]]));
+  if (hashes.length === readable.length) return { ...missing, ...Object.fromEntries(readable.map((path, i) => [path, hashes[i]])) };
   return Object.fromEntries(files.map((path) => {
     const result = git(worktree, ['hash-object', '--no-filters', '--', path]);
     return [path, result.ok ? result.out : null];
   }));
 }
 
+// `📥 docs(auto): sync desde rsc/knowledge` — written by knowledge-sync.mjs when it imports the team's
+// documents. Authored locally, but its content is other people's.
+const KNOWLEDGE_IMPORT = /^\S*\s*docs\(auto\): sync desde /u;
+
 function snapshot(cwd, baselineHead = null) {
   const top = git(cwd, ['rev-parse', '--show-toplevel']);
-  if (!top.ok) return { git: false, branch: null, worktree: resolve(cwd), head: null, files: [], fingerprints: {}, commits: [] };
+  if (!top.ok) return { git: false, branch: null, worktree: resolve(cwd), head: null, files: [], dirty: [], committed: [], fingerprints: {}, commits: [] };
   const worktree = resolve(top.out);
   const branch = cleanString(git(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD']).out, 255);
   const head = cleanString(git(cwd, ['rev-parse', '--verify', 'HEAD']).out, 64);
@@ -188,11 +209,36 @@ function snapshot(cwd, baselineHead = null) {
   let committed = [];
   let commits = [];
   if (baselineHead && head && git(cwd, ['cat-file', '-e', `${baselineHead}^{commit}`]).ok) {
-    committed = git(cwd, ['diff', '--name-only', '-z', `${baselineHead}..${head}`]).out.split('\0').map((item) => cleanString(item, 1000)).filter(Boolean);
-    commits = git(cwd, ['log', '--format=%H', `${baselineHead}..${head}`]).out.split('\n').map((item) => cleanString(item, 64)).filter(Boolean);
+    // The session's OWN commits: the first-parent chain, merges left out. `baseline..head` after a
+    // `git merge origin/main` also walks every teammate commit the merge brought in, and the memory
+    // then told the next session it had done their work and should carry out their next step (team
+    // simulation, 2026-10-07). The files follow from those commits only — never `diff baseline..head`,
+    // which counts everything the merge changed. The knowledge-sync import commit is machine-made and
+    // carries other people's feature documents, so it is not the session's work either.
+    //
+    // A merge the session itself made IS its work, though (second team simulation: a session that
+    // merged main and resolved five conflicts was recorded as «no commits, files: none»). So merges on
+    // the first-parent chain stay, and from a merge only what the session resolved counts — the
+    // combined diff (`--cc`), never everything the merge brought in.
+    const own = git(cwd, ['log', '--first-parent', '--format=%H%x09%P%x09%s', `${baselineHead}..${head}`]).out
+      .split('\n').filter(Boolean).map((line) => line.split('\t'))
+      .filter(([, , subject = '']) => !KNOWLEDGE_IMPORT.test(subject));
+    commits = own.map(([sha]) => cleanString(sha, 64)).filter(Boolean);
+    const merges = new Set(own.filter(([, parents = '']) => parents.trim().split(/\s+/).length > 1).map(([sha]) => sha));
+    const touched = new Set();
+    for (const sha of commits) {
+      const args = merges.has(sha)
+        ? ['diff-tree', '--no-commit-id', '--name-only', '--cc', '-z', sha]
+        : ['diff-tree', '--no-commit-id', '--name-only', '-r', '-z', '--root', sha];
+      for (const item of git(cwd, args).out.split('\0')) {
+        const clean = cleanString(item, 1000);
+        if (clean) touched.add(clean);
+      }
+    }
+    committed = [...touched];
   }
   const files = [...new Set([...dirty, ...committed])].sort();
-  return { git: true, branch, worktree, head, files, fingerprints: fingerprintFiles(worktree, dirty), commits };
+  return { git: true, branch, worktree, head, files, dirty, committed, fingerprints: fingerprintFiles(worktree, dirty), commits };
 }
 
 function ledgerSnapshot(cwd) {
@@ -237,19 +283,76 @@ function prune(root, now, config) {
     const updated = value?.timestamps?.updatedAt || value?.startedAt;
     if (!updated || new Date(updated).getTime() < cutoff) rmSync(path, { force: true });
   }
+  // Presence only means anything inside the active window; a day is generous and keeps the dir small.
+  const presenceCutoff = new Date(now).getTime() - 86400000;
+  for (const path of presenceFiles(root)) {
+    const value = readJson(path);
+    if (!value?.updatedAt || new Date(value.updatedAt).getTime() < presenceCutoff) rmSync(path, { force: true });
+  }
+}
+
+function presenceFiles(root) {
+  const dir = join(root, 'presence');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((name) => name.endsWith('.json')).map((name) => join(dir, name));
+}
+
+const PRESENCE_FIELDS = ['schemaVersion', 'sessionId', 'target', 'branch', 'worktree', 'updatedAt'];
+
+/**
+ * "A session is here", written on every event from the first one (team simulation W2). The journal
+ * only writes a RECORD once there is work, so a session that had just started — or was still reading
+ * before its first edit — was invisible, and a second session opened twenty seconds later was never
+ * told to isolate. A record cannot carry this: resume would hand that empty record to the next
+ * session as "your continuation". So presence is its own tiny file: who and where, never what — no
+ * prompt, no file, no content (P3) — and it is removed when the session ends.
+ */
+function writePresence(root, storageId, presence) {
+  const value = Object.fromEntries(PRESENCE_FIELDS.map((key) => [key, presence[key] ?? null]));
+  if (Object.values(value).some((item) => secretShaped(item))) return;
+  atomicJson(join(root, 'presence', `${storageId}.json`), value);
+}
+
+function readPresence(root) {
+  return presenceFiles(root).map(readJson).filter((item) => item && item.schemaVersion === 1
+    && typeof item.sessionId === 'string' && typeof item.updatedAt === 'string'
+    && Object.keys(item).every((key) => PRESENCE_FIELDS.includes(key)));
+}
+
+// Where a session is, in the parent project's terms: the worktree under `<project>/.worktrees/` that
+// holds `path`, or null when `path` is not inside one.
+function nestedWorktreeOf(project, path) {
+  if (!path) return null;
+  const rel = relativeSlash(project, path);
+  if (!rel.startsWith('.worktrees/')) return null;
+  // git needs a directory to stand in: the file's own folder, or the nearest one that exists yet.
+  let probe = existsSync(path) && statSync(path).isDirectory() ? path : dirname(path);
+  while (!existsSync(probe)) {
+    const parent = dirname(probe);
+    if (parent === probe) return null;
+    probe = parent;
+  }
+  const top = git(probe, ['rev-parse', '--show-toplevel']);
+  if (!top.ok) return null;
+  const worktree = resolve(top.out);
+  return relativeSlash(project, worktree).startsWith('.worktrees/') ? worktree : null;
 }
 
 function noticeText(info) {
+  if (info.reason === 'placeholder-worklog') return null; // nothing the person needs to know
   if (info.reason === 'tracked-worklog') return 'rsc memory: tracked worklog detected; using ignored local state instead.';
   if (info.reason === 'untracked-worklog') return 'rsc memory: using the ignored wiki worklog store.';
   if (info.reason === 'without-git') return 'rsc memory: running without git; branch and commit metadata are unavailable.';
   if (info.reason === 'local-state-tracked') return 'rsc memory: .rsc memory was tracked; using git-private local state.';
-  return 'rsc memory: no wiki worklog found; using ignored local state.';
+  // The ordinary case (no wiki worklog, local state) is not news: said to every new clone it was noise
+  // (second team simulation), like the placeholder case above.
+  return null;
 }
 
 function consumeNotice(info) {
   const marker = join(info.root, `.notice-${info.reason}`);
   if (existsSync(marker)) return null;
+  if (!noticeText(info)) return null;
   writeFileSync(marker, `${iso()}\n`, { mode: 0o600 });
   return noticeText(info);
 }
@@ -267,6 +370,59 @@ function activeConcurrent(records, sessionId, target, worktree, now) {
     && !record?.timestamps?.completedAt && new Date(record?.timestamps?.updatedAt || 0).getTime() >= recent);
 }
 
+/** How long a session counts as "working here" after its last recorded event (team-safe-default B). */
+export const ACTIVE_WINDOW_MS = 30 * 60 * 1000;
+
+/**
+ * Other sessions working in THIS checkout right now: any assistant with rsc, same worktree, an event
+ * in the last 30 minutes, not closed, and not the asking session itself. It answers WHO is working,
+ * never WHAT is in the project (constitution P3), reads only the local journal (no network, no
+ * content), and its worst failure is one worktree too many or too few.
+ *
+ * A session that only talks has no RECORD — the journal only writes when there is work — but it has a
+ * PRESENCE from its first event, so a session opened seconds after another one is still told to
+ * isolate (team simulation W2). Sessions are counted where they are NOW: one that moved into
+ * `.worktrees/<b>/` no longer counts in the main checkout.
+ */
+export function otherActiveSessions(input = {}) {
+  try {
+    const cwd = resolve(input.cwd || process.cwd());
+    const top = git(resolve(input.worktreeCwd || cwd), ['rev-parse', '--show-toplevel']);
+    if (!top.ok) return [];
+    const here = resolve(top.out);
+    const store = chooseMemoryRoot(cwd);
+    if (!existsSync(store.root)) return [];
+    const now = new Date(input.now || Date.now()).getTime();
+    const windowMs = Number.isFinite(input.windowMs) ? input.windowMs : ACTIVE_WINDOW_MS;
+    // Each session once, at its LATEST known position: its record (work) or its presence (any event),
+    // whichever is newer. A session that moved into a worktree is no longer here, whatever an older
+    // record of it says.
+    const latest = new Map();
+    for (const r of readRecords(store.root)) {
+      latest.set(`${r.target}--${r.sessionId}`, {
+        target: r.target, sessionId: r.sessionId, branch: r.branch, worktree: r.worktree,
+        updatedAt: r.timestamps?.updatedAt, completedAt: r.timestamps?.completedAt || null,
+      });
+    }
+    for (const p of readPresence(store.root)) {
+      const key = `${p.target}--${p.sessionId}`;
+      const known = latest.get(key);
+      const newer = !known || new Date(p.updatedAt).getTime() >= new Date(known.updatedAt || 0).getTime();
+      // A presence newer than the record's close means the session came back (resumed by id).
+      if (newer) latest.set(key, { ...p, completedAt: known?.completedAt && new Date(known.completedAt).getTime() >= new Date(p.updatedAt).getTime() ? known.completedAt : null });
+    }
+    const self = (s) => s.sessionId === cleanId(input.sessionId, 'session') && s.target === input.target;
+    return [...latest.values()]
+      .filter((s) => s.worktree === here)
+      .filter((s) => !self(s))
+      .filter((s) => !s.completedAt)
+      .filter((s) => now - new Date(s.updatedAt || 0).getTime() <= windowMs)
+      .map((s) => ({ target: s.target, sessionId: s.sessionId, branch: s.branch, updatedAt: s.updatedAt }));
+  } catch {
+    return [];
+  }
+}
+
 export function validateSessionRecord(record) {
   const errors = [];
   if (!record || typeof record !== 'object' || Array.isArray(record)) return ['record: object required'];
@@ -298,7 +454,7 @@ export function capture(input = {}) {
   // The second has to be asked of git from where the agent actually works: asked from the harness,
   // every worktree nested under it came back as the harness itself, and a sibling's record then
   // "matched exactly". See GHSA-8gjp-3r7c-33f4.
-  const here = resolve(input.worktreeCwd || cwd);
+  let here = resolve(input.worktreeCwd || cwd);
   const config = settings(input.settings);
   if (!config.enabled) return { record: null, path: null, notice: null, compactionHint: false };
   const store = chooseMemoryRoot(cwd);
@@ -314,8 +470,33 @@ export function capture(input = {}) {
   const recordPath = join(store.root, 'sessions', `${storageId}.json`);
   let anchor = readJson(anchorPath);
   let existing = readJson(recordPath);
-  // The first snapshot only seeds a new anchor; an existing one already has its baseline.
-  const firstSnapshot = anchor ? null : snapshot(here, null);
+  // A session that moved into `.worktrees/<b>/` is THERE, also on the events that do not say so.
+  // An edit names its file — the first sign of the move when the agent writes by absolute path and
+  // its cwd never changed — and `Stop`/`SessionEnd` name nothing, so the move is remembered on the
+  // anchor until the session edits the main checkout again. Without this the record stayed on the
+  // main checkout, open, and every later session there was told for half an hour that someone was
+  // working beside it (team simulation W1).
+  const projectTop = git(cwd, ['rev-parse', '--show-toplevel']);
+  const project = projectTop.ok ? resolve(projectTop.out) : cwd;
+  const fileHint = typeof input.filePath === 'string' && isAbsolute(input.filePath) ? resolve(input.filePath) : null;
+  let movedTo = anchor?.movedTo || null;
+  const fromFile = nestedWorktreeOf(project, fileHint);
+  if (fromFile) here = fromFile;
+  const nestedHere = nestedWorktreeOf(project, here);
+  if (nestedHere) movedTo = nestedHere;
+  else if (fileHint && !relativeSlash(project, fileHint).startsWith('..')) movedTo = null; // back in the main checkout
+  else if (movedTo && existsSync(movedTo)) here = movedTo;
+  else movedTo = null;
+  const firstSnapshot = snapshot(here, null);
+  // Presence: on every event, before any early return — the point is to be seen before there is work.
+  const ending = ['end', 'sessionEnd', 'stop'].includes(input.event);
+  if (ending) rmSync(join(store.root, 'presence', `${storageId}.json`), { force: true });
+  else {
+    writePresence(store.root, storageId, {
+      schemaVersion: 1, sessionId, target, branch: cleanString(firstSnapshot.branch, 255),
+      worktree: cleanString(firstSnapshot.worktree, 1000), updatedAt: now,
+    });
+  }
   if (!anchor) {
     anchor = {
       sessionId,
@@ -323,8 +504,13 @@ export function capture(input = {}) {
       baselineHead: cleanString(input.baselineHead, 64) || firstSnapshot.head,
       baselineFiles: firstSnapshot.files,
       baselineFingerprints: firstSnapshot.fingerprints,
+      ...(movedTo ? { movedTo } : {}),
     };
     atomicJson(anchorPath, anchor);
+  } else if ((anchor.movedTo || null) !== movedTo) {
+    const { movedTo: _previous, ...rest } = anchor;
+    anchor = movedTo ? { ...rest, movedTo } : rest;
+    atomicJson(anchorPath, anchor);
   }
   if (input.event === 'start' && !existing) return { record: null, path: null, notice: null, compactionHint: false };
 
@@ -346,13 +532,27 @@ export function capture(input = {}) {
   const observed = Object.entries(repo.fingerprints || {})
     .filter(([path, fingerprint]) => fingerprint && previousFingerprints[path] !== fingerprint).length;
   const editDelta = Math.max(finiteOrNull(input.editDelta, true) || 0, observed);
-  // Compaction closes a context window, so the edit budget starts again from zero.
-  const previousEdits = input.event === 'compact' ? 0 : (existing?.editCount || 0);
+  // Compaction closes a context window, so the edit budget starts again from zero. Two signals say
+  // it happened, and either is enough: PreCompact (`compact`) and the SessionStart that follows it
+  // (`reset`, from `source: "compact"`). Relying on PreCompact alone meant a cancelled PreCompact
+  // hook — which is what the 5 s timeout did on a dirty tree — left the old count standing.
+  const resetsBudget = input.event === 'compact' || input.reset === true;
+  const previousEdits = resetsBudget ? 0 : (existing?.editCount || 0);
   const editCount = Math.max(0, previousEdits + editDelta);
   // Hint once per threshold crossed, and only on the edit that crosses it: re-emitting on
   // every later event (Stop in particular) wakes the model again and loops.
   const crossedThreshold = editCount > previousEdits
     && Math.floor(editCount / config.editThreshold) > Math.floor(previousEdits / config.editThreshold);
+  // And never ON a turn end, even the one that crosses. A Stop hook that speaks is a Stop hook that
+  // can start another turn, and that turn ends in another Stop: the field report is ~150 empty
+  // assistant replies in a row. A crossing seen at a turn end is kept on the anchor and said by the
+  // next event that is not one (the person's next prompt, or the next tool call). Compaction and
+  // start never say it either — "consider compacting" while compacting is noise — and a reset
+  // drops whatever was pending, because the window it was about is gone.
+  const mutedEvents = ['turn', 'stop', 'compact', 'start', 'end', 'sessionEnd'];
+  const hintDue = !resetsBudget && (crossedThreshold || anchor.hintPending === true);
+  const speaks = !mutedEvents.includes(input.event);
+  const hintPending = hintDue && !speaks;
   const baselineFiles = new Set(anchor.baselineFiles || []);
   const newDirtyPath = repo.files.some((path) => !baselineFiles.has(path));
   const baselineFingerprints = anchor.baselineFingerprints || {};
@@ -378,7 +578,11 @@ export function capture(input = {}) {
     worktree: cleanString(repo.worktree, 1000),
     baselineHead: cleanString(anchor.baselineHead, 64),
     head: cleanString(repo.head, 64),
-    files: repo.files.filter((item) => !secretShaped(item)),
+    // What THIS session touched: what it committed, plus what is dirty now and was not dirty — or not
+    // this content — when it started. The plain union listed whatever an install had left untracked,
+    // so a session that never opened `.rsc.json` reported it as its work (E2E 2026-10-07).
+    files: [...new Set([...repo.committed, ...repo.dirty.filter((path) => !baselineFiles.has(path)
+      || baselineFingerprints[path] !== repo.fingerprints[path])])].sort().filter((item) => !secretShaped(item)),
     commits: repo.commits.filter((item) => !secretShaped(item)),
     ledger: ledgerSnapshot(cwd),
     timestamps: { startedAt: anchor.startedAt, updatedAt: now, completedAt: completed },
@@ -391,13 +595,20 @@ export function capture(input = {}) {
   if (errors.length) return { record: null, path: null, notice: null, compactionHint: false, errors };
   atomicJson(recordPath, record);
   existing = record;
-  const compactionHint = Boolean(config.compactionHint && crossedThreshold);
+  const compactionHint = Boolean(config.compactionHint && hintDue && speaks);
   // The fingerprints the next event compares against live on the ANCHOR, not on the record: the
   // record's schema is closed and every field of it is required, so a new field there would fail
   // validation on every record already written. Written only when they moved, so a read-only shell
-  // command costs no extra disk.
+  // command costs no extra disk. The pending hint lives there for the same reason.
   const fingerprintsMoved = observed > 0 || !anchor.lastFingerprints;
-  if (fingerprintsMoved) atomicJson(anchorPath, { ...anchor, lastFingerprints: repo.fingerprints || {} });
+  if (fingerprintsMoved || Boolean(anchor.hintPending) !== hintPending) {
+    const { hintPending: _previous, ...rest } = anchor;
+    atomicJson(anchorPath, {
+      ...rest,
+      lastFingerprints: fingerprintsMoved ? (repo.fingerprints || {}) : anchor.lastFingerprints,
+      ...(hintPending ? { hintPending: true } : {}),
+    });
+  }
   return {
     record,
     path: recordPath,
@@ -428,19 +639,54 @@ function truncateUtf8(text, maxBytes) {
   return output;
 }
 
-function renderContext(record, match, lessons, config) {
+// WHAT the last session did, not only where it stopped: the subjects of its commits and the next step
+// its feature document wrote down. Read at resume time from git and the document — never from the
+// prompts, which the record promises not to keep — so the record's closed schema does not change.
+function subjects(cwd, commits) {
+  return commits.slice(0, 8).map((sha) => {
+    const out = git(cwd, ['log', '-1', '--format=%h %s', sha]);
+    return out.ok ? cleanString(out.out, 160) : cleanString(sha.slice(0, 7), 7);
+  }).filter((item) => item && !secretShaped(item));
+}
+
+// A document whose frontmatter says `status: done` is finished work, not a next step. On a closed
+// default branch the close travels by rsc/knowledge and is not in the checkout yet (knowledge-sync
+// `closeLanded`), so the exchange branch's copy is asked too — a local ref, no network.
+const isDone = (text) => /^status:[ \t]*done[ \t]*$/mu.test(String(text || '').replace(/\r\n/gu, '\n').match(/^---\n([\s\S]*?)\n---(?:\n|$)/u)?.[1] || '');
+
+function nextSteps(cwd, files) {
+  const out = [];
+  for (const rel of files.filter((f) => /^docs\/wiki\/(ftd|sdd\/(specs|plans|progress))\/[^/]+\.md$/u.test(f)).slice(0, 3)) {
+    let body = '';
+    try { body = readFileSync(join(cwd, rel), 'utf8'); } catch { continue; }
+    if (isDone(body)) continue;
+    const exchange = git(cwd, ['show', `refs/remotes/origin/rsc/knowledge:${rel}`]);
+    if (exchange.ok && isDone(exchange.out)) continue;
+    const section = body.match(/^##\s*(Next|Siguiente|Próximo)[^\n]*\n+([\s\S]*?)(?=\n##\s|$)/imu)?.[2];
+    const first = section?.split('\n').map((l) => l.replace(/^[-*]\s*/u, '').trim()).find(Boolean);
+    const open = (body.match(/^- \[ \]/gmu) || []).length;
+    if (first || open) out.push(`${rel}: ${first ? cleanString(first, 200) : 'no next step written'}${open ? ` (${open} open)` : ''}`);
+  }
+  return out;
+}
+
+function renderContext(record, match, lessons, config, cwd = process.cwd()) {
   if (!record && !lessons.length) return '';
+  const done = record ? subjects(cwd, record.commits) : [];
+  const next = record ? nextSteps(cwd, record.files) : [];
   const lines = record ? [
     `[rsc local ${match} continuation]`,
-    `source: ${record.target}/${record.sessionId}`,
+    `source: ${record.target}/${record.sessionId} (${record.timestamps.startedAt} → ${record.timestamps.updatedAt})`,
     `branch: ${record.branch || 'unavailable'}`,
     `worktree: ${record.worktree || 'unavailable'}`,
     `head: ${record.head || 'unavailable'}`,
+    `done: ${done.length ? done.join(' | ') : 'no commits'}`,
     `files: ${record.files.join(', ') || 'none'}`,
-    `commits: ${record.commits.join(', ') || 'none'}`,
+    ...(next.length ? [`next: ${next.join(' | ')}`] : []),
   ] : ['[rsc local approved lessons]'];
   if (record?.ledger.length) lines.push(`ledger: ${record.ledger.map((item) => `${item.path}=${item.status}/${item.openItems}`).join(', ')}`);
-  if (record) lines.push(`metrics: cost=${record.cost ?? 'unknown'} toolCalls=${record.toolCalls ?? 'unknown'}`);
+  // Only when something is known: «cost=unknown toolCalls=unknown» on every resume told the model nothing.
+  if (record && (record.cost != null || record.toolCalls != null)) lines.push(`metrics: cost=${record.cost ?? 'unknown'} toolCalls=${record.toolCalls ?? 'unknown'}`);
   if (record?.concurrent) lines.push('parallel sessions detected; this record was not merged with them.');
   for (const lesson of lessons) lines.push(`approved lesson (${lesson.confidence}): ${lesson.text}`);
   return truncateUtf8(`${lines.join('\n')}\n`, config.contextBytes);
@@ -470,7 +716,7 @@ export function resume(input = {}) {
     if (record) match = 'nearby';
   }
   const lessons = selectedLessons(store.root, config);
-  return { match, record, lessons, context: renderContext(record, match, lessons, config) };
+  return { match, record, lessons, context: renderContext(record, match, lessons, config, here) };
 }
 
 export function learn(input = {}) {
@@ -503,10 +749,11 @@ export function metricsSummary(input = {}) {
     cost: sessions.filter((row) => row.cost === null).length,
     toolCalls: sessions.filter((row) => row.toolCalls === null).length,
   };
-  const knownTotal = {
-    cost: sessions.reduce((sum, row) => sum + (row.cost ?? 0), 0),
-    toolCalls: sessions.reduce((sum, row) => sum + (row.toolCalls ?? 0), 0),
-  };
+  // A sum over nothing known is unknown, not zero: doctor printed `cost: 0` for three sessions whose
+  // cost nobody had measured.
+  const knownSum = (key) => (unknown[key] === sessions.length ? null
+    : sessions.reduce((sum, row) => sum + (row[key] ?? 0), 0));
+  const knownTotal = { cost: knownSum('cost'), toolCalls: knownSum('toolCalls') };
   const total = {
     cost: !sessions.length || unknown.cost ? null : knownTotal.cost,
     toolCalls: !sessions.length || unknown.toolCalls ? null : knownTotal.toolCalls,

package/targets/session-start.mjs

@@ -274,7 +274,8 @@ ${candidates.map((c) => W.summarize(c, root)).join('\n')}
 ACTION: offer to retire them in ONE line and wait for a yes. On a yes run:
   npx @damiangilgonzalez/harness worktrees reap          (the ones marked safe)
   npx @damiangilgonzalez/harness worktrees reap <path>   (one the user confirmed by name)
-A yes in bulk covers only the safe ones; anything marked \`ask\` is confirmed on its own.
+  npx @damiangilgonzalez/harness worktrees reap --merged --confirm   (safe + "provenance unclear" only, after a fetch; say so when offering)
+A yes in bulk covers only those; any other \`ask\` (uncommitted changes, files in no commit) is confirmed on its own.
 A no holds for this session. Permanent off: .rsc/.no-worktree-cleanup
 ================================
 `;

package/targets/ship-guard.mjs

@@ -5,9 +5,10 @@
 //
 // Enforces the "close the feature before you leave it" rule at the one deterministic
 // moment it matters: when a Bash command tries to switch to the trunk (main/master)
-// or merge into it. If the current feature branch has uncommitted changes or commits
-// that were never pushed, the guard DENIES the command and tells the agent to run
-// `ship` (commit → push → PR). Opening the PR itself is `ship`'s job and the skill's
+// or merge into it. If the current feature branch has commits that were never pushed,
+// the guard DENIES the command and tells the agent to run `ship` (commit → push → PR).
+// Uncommitted changes alone only earn a hint: they may be the user's own work, and git
+// already refuses a switch that would overwrite them. Opening the PR itself is `ship`'s job and the skill's
 // hard rule; this hook guarantees you cannot quietly abandon unsaved/unpushed work.
 //
 // Design: precise (only fires on a trunk switch/merge), local-only (no network, no gh),
@@ -77,10 +78,26 @@ if (!branch || branch === 'HEAD' || branch === 'main' || branch === 'master') al
 
 const tail = '\n(If this is intentional and you accept the risk, create .rsc/.no-ship-guard to disable this guard.)';
 
-// 1) Uncommitted work would be carried off the feature branch.
+// 1) Uncommitted changes are NOT a reason to deny. They may well be the user's own work in the main
+// checkout, not the agent's: in real sessions this denied five branch switches over a diff the agent
+// had no business committing, and "commit them first" pushed it to do exactly that. Git itself
+// refuses a switch that would overwrite local changes, and carries the rest along untouched, so the
+// switch is left to git and the agent gets a hint: leave that diff alone and work in a worktree.
+// The unpushed-commits rule below is the guard's real purpose and still denies.
 const dirty = git('status', '--porcelain');
-if (dirty && dirty.length > 0) {
-  deny(`You're leaving feature branch "${branch}" with uncommitted changes. Commit them first — run the \`ship\` skill (commit → push → PR), don't abandon the diff.${tail}`);
+const worktreeHint = dirty && dirty.length > 0
+  ? `The working tree on "${branch}" has uncommitted changes, and they may be the user's, not yours: ` +
+    `do not commit, stash or discard them to make room. If git refuses the switch, work in a separate ` +
+    `worktree instead: \`git worktree add .claude/worktrees/<name> -b <branch> origin/main\` ` +
+    `(or \`npx @damiangilgonzalez/harness worktrees new <name>\`).`
+  : '';
+function hint() {
+  if (!worktreeHint) allow();
+  process.stdout.write(JSON.stringify({
+    systemMessage: 'ship-guard: hay cambios sin commitear en el árbol; no se tocan.',
+    hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: worktreeHint },
+  }));
+  process.exit(0);
 }
 
 // 2) Commits exist but were never pushed.
@@ -88,14 +105,14 @@ const upstream = git('rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'
 if (upstream) {
   const ahead = git('rev-list', '--count', `${upstream}..HEAD`);
   if (ahead && Number(ahead) > 0) {
-    deny(`Feature branch "${branch}" has ${ahead} commit(s) not pushed to ${upstream}. Push them and open the PR — run the \`ship\` skill — before switching to the trunk.${tail}`);
+    deny(`Feature branch "${branch}" has ${ahead} commit(s) not pushed to ${upstream}. Push them and open the PR — run the \`ship\` skill — before switching to the trunk.${worktreeHint ? `\n${worktreeHint}` : ''}${tail}`);
   }
 } else {
   // No upstream at all: if the branch carries commits beyond the trunk, it was never pushed.
   const aheadOfTrunk = git('rev-list', '--count', 'main..HEAD') ?? git('rev-list', '--count', 'master..HEAD');
   if (aheadOfTrunk && Number(aheadOfTrunk) > 0) {
-    deny(`Feature branch "${branch}" was never pushed (no upstream, ${aheadOfTrunk} commit(s) ahead of the trunk). Push it and open a PR — run the \`ship\` skill — before leaving it.${tail}`);
+    deny(`Feature branch "${branch}" was never pushed (no upstream, ${aheadOfTrunk} commit(s) ahead of the trunk). Push it and open a PR — run the \`ship\` skill — before leaving it.${worktreeHint ? `\n${worktreeHint}` : ''}${tail}`);
   }
 }
 
-allow();
+hint();