@gcunharodrigues/wrxn 0.13.2 → 0.14.0

package/payload/.claude/hooks/reward.cjs

@@ -0,0 +1,244 @@
+'use strict';
+
+// WRXN reward module — the learning-moat's value axis (kernel #13 / S2). A per-page Beta-Bernoulli
+// store keyed by wiki-rel page path: { "<wiki-rel>": { s, f } } = good / bad sessions in which the page
+// surfaced. `updateReward(counts, surfacedSet, signal)` is the PURE, deterministic, TOTAL update applied
+// ONCE PER SESSION: +1 credits each surfaced page's success count `s`, −1 credits its failure count `f`,
+// neutral (0) leaves counts untouched. The signal is INJECTED (the math never reads git/clock itself —
+// the impure session-end shell derives ±1 and passes it), mirroring the recon decay-scorer's discipline.
+//
+// SHADOW (S2): this module only WRITES counts. It does NOT compute a reward factor or touch recall
+// ranking — the re-rank is S3, behind a recorded mode constant. Keeping the factor out of S2 makes
+// "shipping S2 is a recall no-op" true by construction.
+//
+// Self-contained: ships into installs alongside the hooks — node stdlib ONLY, NO kernel-lib / recon
+// import (mirrors sidecar.cjs). The update is pure (no IO); only the shell that calls it does git/fs.
+
+// Counts are bounded by construction so one lucky (or unlucky) page can't dominate every recall once the
+// factor goes live in S3: each of s/f saturates at COUNT_CAP. The exact cap is a placeholder pending the
+// lift gate (the PRD records caps as gate-tuned, not guessed — like the decay half-life); it exists now
+// only so the store is bounded from day one, never as a tuned value.
+const COUNT_CAP = 1e6;
+
+// A valid join key is a wiki-rel page path: a STRING with non-whitespace content (e.g. 'concepts/a.md').
+// Strictly string-typed (a coerced number like 0 is not a path) and non-blank, so garbage in the
+// surfaced set credits nobody. This is also the sec-F3 posture: the value is treated only as a discrete
+// page-identity key, never decomposed or used as anything but a map key.
+function isWikiRelKey(k) {
+  return typeof k === 'string' && k.trim().length > 0;
+}
+
+// A non-negative finite integer-ish count, defaulting to 0 (totality: garbage in a slot reads as 0).
+function asCount(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+// Read an existing { s, f } slot defensively (totality: a malformed slot reads as zero evidence).
+function readSlot(counts, key) {
+  const slot = counts && typeof counts === 'object' ? counts[key] : null;
+  if (!slot || typeof slot !== 'object') return { s: 0, f: 0 };
+  return { s: asCount(slot.s), f: asCount(slot.f) };
+}
+
+/**
+ * The pure Beta-Bernoulli update, applied ONCE PER SESSION (the caller passes the session's surfaced set
+ * exactly once). Returns a FRESH counts map — the input is never mutated.
+ *   signal > 0  → s += 1 for each surfaced page (a good session: new commits, green suite by construction)
+ *   signal < 0  → f += 1 for each surfaced page (a bad session: a later revert / correction)
+ *   signal == 0 → no change (neutral: no new commits — nothing to attribute)
+ * Equal credit to every page in the surfaced set (attribution v1). TOTAL: any garbage (non-array set,
+ * non-object counts, non-numeric signal, malformed slots) yields a sane map and never throws.
+ *
+ * Optional `opts.discount` ∈ (0,1) decays EVERY prior count toward neutral before this session's signal
+ * (non-stationarity: a stale regime is unlearned over the page's lifetime). Out-of-range / garbage →
+ * no decay (totality). Off by default — the exact value is gate-tuned, not guessed (PRD).
+ *
+ * @param {Record<string,{s:number,f:number}>} counts  prior per-page counts (treated read-only)
+ * @param {Iterable<string>} surfacedSet  wiki-rel page keys surfaced this session
+ * @param {number} signal  +1 good / −1 bad / 0 neutral (injected; never read from git/clock here)
+ * @param {{discount?:number}} [opts]  optional decay factor in (0,1) applied to prior counts
+ * @returns {Record<string,{s:number,f:number}>} a fresh updated counts map
+ */
+function updateReward(counts, surfacedSet, signal, opts) {
+  // A well-formed, fresh defensive copy of the prior counts (every slot normalized to {s,f} numbers).
+  const copyPrior = () => {
+    const m = {};
+    if (counts && typeof counts === 'object' && !Array.isArray(counts)) {
+      for (const k of Object.keys(counts)) {
+        if (!isWikiRelKey(k)) continue;
+        m[k] = readSlot(counts, k);
+      }
+    }
+    return m;
+  };
+
+  const dir = Number(signal);
+  if (!Number.isFinite(dir) || dir === 0) return copyPrior(); // neutral → no update (and no decay)
+
+  // A discount strictly inside (0,1) decays prior counts toward neutral BEFORE this session's signal;
+  // anything else (incl. 1, 0, NaN) → no decay. Applied only on a real (non-neutral) session.
+  const d = Number(opts && opts.discount);
+  const discount = Number.isFinite(d) && d > 0 && d < 1 ? d : 1;
+  const out = copyPrior();
+  if (discount !== 1) {
+    for (const k of Object.keys(out)) {
+      out[k] = { s: out[k].s * discount, f: out[k].f * discount };
+    }
+  }
+
+  // A surfaced SET is a collection of page keys. A bare string is NOT a set — Array.from would split it
+  // into single characters and credit each as a page (corrupting the store); so anything that isn't an
+  // array or a non-string iterable credits nobody (totality), never throws.
+  let iterable;
+  if (Array.isArray(surfacedSet)) {
+    iterable = surfacedSet;
+  } else if (surfacedSet != null && typeof surfacedSet !== 'string' && typeof surfacedSet[Symbol.iterator] === 'function') {
+    try {
+      iterable = Array.from(surfacedSet);
+    } catch {
+      iterable = [];
+    }
+  } else {
+    iterable = [];
+  }
+
+  const seen = new Set();
+  for (const raw of iterable) {
+    if (!isWikiRelKey(raw)) continue; // non-string / blank → not a page key, credit nobody (totality)
+    const key = raw;
+    if (seen.has(key)) continue; // once per page per session (a dupe in the set is a single credit)
+    seen.add(key);
+    const slot = out[key] || { s: 0, f: 0 };
+    if (dir > 0) slot.s = Math.min(slot.s + 1, COUNT_CAP);
+    else slot.f = Math.min(slot.f + 1, COUNT_CAP);
+    out[key] = slot;
+  }
+  return out;
+}
+
+/**
+ * The reward VALUE AXIS (S3): map a page's Beta-Bernoulli slot `{s,f}` to a centered multiplicative
+ * factor for the recall re-rank. Laplace-smoothed posterior mean `(s+1)/(s+f+2)` ∈ (0,1) (neutral 1/2
+ * at zero evidence) → factor `2·mean` ∈ (0,2): a proven page (s≫f) lifts toward 2, a disproven page
+ * (f≫s) sinks toward 0, and a page with NO evidence maps to EXACTLY 1 so it never moves a rank.
+ *
+ * BOUNDED by construction: s,f are finite non-negative (and saturate at COUNT_CAP in updateReward), so
+ * the mean is strictly inside (0,1) and the factor strictly inside (0,2) — it can never reach 0 or 2,
+ * so one lucky page can neither zero out nor double a rank. PURE + TOTAL: garbage / missing slot reads
+ * as zero evidence → neutral 1, never a throw, never reads a clock. The same posterior the mechanism
+ * gate fixtures lock (a known-useful page outranks a known-useless one).
+ *
+ * @param {{s:number,f:number}} [slot]  a page's reward counts (missing/garbage → zero evidence)
+ * @returns {number} the centered reward factor in (0,2); exactly 1 at zero evidence
+ */
+function rewardFactor(slot) {
+  const s = asCount(slot && slot.s);
+  const f = asCount(slot && slot.f);
+  const mean = (s + 1) / (s + f + 2); // Laplace posterior mean ∈ (0,1), exactly 1/2 at s=f=0
+  return 2 * mean; // centered factor ∈ (0,2), exactly 1 at zero evidence
+}
+
+// ── starvedUseful: the learning-moat WATCHDOG (S4) ───────────────────────────────────
+// A pure, deterministic, TOTAL canary over the (reward, surfaced-log) sidecar pair. It counts the
+// STARVED-USEFUL set: pages the reward signal has learned are useful (high posterior) yet recall RARELY
+// surfaces (low surfaced-count) — because they sit below recon's floor, where a kernel-side re-rank
+// cannot lift them. A growing set means the cheap kernel-side approach has hit its ceiling; the count is
+// the data-driven signal toward graduating a recon reward term (option b). This module only COMPUTES the
+// count — the handoff emission lives in the session-end shell (synapse-engine), the SAME channel as
+// harvest's curation-debt nudge. Read-only: it never mutates the sidecars or touches recall ranking.
+
+// "High reward" REUSES the value axis's posterior (rewardFactor = 2·mean ⇒ mean = factor/2 — never a
+// second notion). R_HIGH is the posterior-mean bar for "learned useful"; S_LOW the surfaced-count bar
+// for "rarely surfaced". Both are PLACEHOLDERS pending the lift gate — recorded with the gate verdict,
+// exactly like COUNT_CAP and the decay half-life (the PRD records thresholds as gate-tuned, not guessed).
+// They exist now only so the canary is bounded and deterministic from day one, never as tuned values.
+const R_HIGH = 0.75; // posterior mean ≥ 0.75 (⇔ rewardFactor ≥ 1.5) — clearly net-positive evidence
+const S_LOW = 1; // surfaced in ≤ 1 recorded session — recall almost never brings it up
+
+// Build a { page → number-of-sessions-that-surfaced-it } map from the surfaced-log
+// ({ "<session_id>": ["<wiki-rel>", …] }). Each session credits a page AT MOST ONCE (a within-session
+// dupe is one surfacing), mirroring recall-surface's per-session de-dup. TOTAL: a non-object log, a
+// non-array session entry, or a non-string/blank page key contributes nothing — never throws.
+function surfacedCounts(surfaced) {
+  const counts = Object.create(null);
+  if (!surfaced || typeof surfaced !== 'object' || Array.isArray(surfaced)) return counts;
+  for (const sid of Object.keys(surfaced)) {
+    const entry = surfaced[sid];
+    if (!Array.isArray(entry)) continue;
+    const seen = new Set();
+    for (const raw of entry) {
+      if (!isWikiRelKey(raw) || seen.has(raw)) continue;
+      seen.add(raw);
+      counts[raw] = (counts[raw] || 0) + 1;
+    }
+  }
+  return counts;
+}
+
+/**
+ * PURE watchdog: count the STARVED-USEFUL pages over the (reward, surfaced) sidecar pair. A page is
+ * starved-useful when BOTH hold:
+ *   · posterior(reward[page]) ≥ rHigh   — learned useful (the SAME posterior the value axis uses)
+ *   · surfaced-count(page)    ≤ sLow    — rarely surfaced across the log (sits below recon's floor)
+ * Returns { count, pages } with `pages` sorted (DETERMINISTIC) and `count = pages.length`. TOTAL: any
+ * garbage (non-object reward/surfaced, malformed slot, garbage opts) yields { count: 0, pages: [] } and
+ * never throws. Thresholds default to the named constants R_HIGH / S_LOW; opts may override them for the
+ * gate's tuning (out-of-range / non-finite → the constant default).
+ *
+ * @param {Record<string,{s:number,f:number}>} reward  per-page Beta-Bernoulli counts (read-only)
+ * @param {Record<string,string[]>} surfaced           per-session surfaced-log (read-only)
+ * @param {{rHigh?:number, sLow?:number}} [opts]        optional threshold overrides (gate-tuned)
+ * @returns {{count:number, pages:string[]}}
+ */
+function starvedUseful(reward, surfaced, opts) {
+  const rh = Number(opts && opts.rHigh);
+  const rHigh = Number.isFinite(rh) && rh > 0 && rh < 1 ? rh : R_HIGH;
+  const sl = Number(opts && opts.sLow);
+  const sLow = Number.isFinite(sl) && sl >= 0 ? sl : S_LOW;
+
+  const counts = surfacedCounts(surfaced);
+  const pages = [];
+  if (reward && typeof reward === 'object' && !Array.isArray(reward)) {
+    for (const key of Object.keys(reward)) {
+      if (!isWikiRelKey(key)) continue;
+      const posterior = rewardFactor(reward[key]) / 2; // SAME posterior as the value axis (factor = 2·mean)
+      if (posterior < rHigh) continue; // not learned-useful
+      if ((counts[key] || 0) > sLow) continue; // surfaced often enough — recall already reaches it
+      pages.push(key);
+    }
+  }
+  pages.sort();
+  return { count: pages.length, pages };
+}
+
+// ── selectRewardMode: the SHIP GATE (S5 / kernel #16) ─────────────────────────────────
+// Mirrors the recon decay-scorer's selectDecayMode(verdict) → SHIPPED_DECAY_MODE. The reward re-rank in
+// recall-surface ships behind a single recorded mode constant; that constant is DERIVED from the lift
+// gate's verdict, never hard-coded. The re-rank goes 'live' ONLY on a PASSING verdict; a failing OR an
+// absent/garbage verdict stays 'shadow' (the safe default — a learned ranker is never silently enabled).
+// A passing verdict is the LITERAL `{ pass: true }`: only an explicit, recorded pass flips recall on, so
+// a malformed or missing verdict can never leak 'live'. PURE + TOTAL — no IO, no clock, never throws.
+function selectRewardMode(verdict) {
+  return verdict && typeof verdict === 'object' && verdict.pass === true ? 'live' : 'shadow';
+}
+
+// The RECORDED production verdict the shipped mode is derived from (the kernel analogue of the decay
+// gate's recorded PASS). It is NOT a passing verdict: ① ships in SHADOW because there is no real
+// accumulated session corpus yet (no logged sessions → the lift gate cannot be run on production data).
+// The mechanism gate + lift-replay harness (docs/eval/0001-reward-lift-gate.md) prove the MECHANISM on
+// synthetic fixtures; the PRODUCTION flip to 'live' additionally requires (a) a passing lift verdict on
+// REAL accumulated sessions AND (b) operator ratification of the git-only outcome signal (it is unsound
+// for `--no-verify` / suite-less installs). Frozen so the recorded verdict cannot be mutated in place.
+const RECORDED_REWARD_VERDICT = Object.freeze({ pass: false, reason: 'insufficient-data' });
+
+module.exports = {
+  updateReward,
+  rewardFactor,
+  starvedUseful,
+  selectRewardMode,
+  RECORDED_REWARD_VERDICT,
+  COUNT_CAP,
+  R_HIGH,
+  S_LOW,
+};

package/payload/.claude/hooks/session-end-reward.cjs

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+'use strict';
+
+// WRXN session-end reward shell — the learning-moat's outcome attributor (kernel #13 / S2).
+// SessionEnd. A thin, FAIL-OPEN hook that turns "did this session ship durable work?" into a per-page
+// reward update. It reads the start-HEAD baseline (stamped by session-start), this session's surfaced
+// set (the per-session surfaced-log .wrxn/surfaced.json by session id), derives a GIT-GROUNDED outcome
+// signal, and persists updated Beta-Bernoulli counts (.wrxn/reward.json) via the shared coalesceSidecar
+// helper. The pure reward math lives in reward.cjs; this shell only supplies git facts + IO.
+//
+// SIGNAL (resolved): Article III makes a landed commit green by construction (the commit gate runs the
+// suite), so the production signal is git-only and cheap — the suite is NEVER run here:
+//   · new non-revert commit(s) since baseline ⇒ +1 (good)
+//   · a `git revert` / recorded correction of this session's work ⇒ −1 (bad)
+//   · no new commits ⇒ neutral (no update)
+// The pure deriveSignal takes the new-commit subjects explicitly, so a future stricter signal can be
+// swapped in without touching the math.
+//
+// SHADOW: this shell only WRITES counts — it never reads or writes recall ranking (the re-rank is S3).
+// Self-contained: ships into installs, MUST NOT import the kernel lib — node stdlib ONLY (+ the
+// co-located sidecar.cjs / reward.cjs siblings). Fail-open: any fault emits {} (no update), never blocks
+// a session closing.
+//
+// Contract: SessionEnd event JSON on stdin → {} on stdout (exit 0).
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { coalesceSidecar } = require('./sidecar.cjs');
+const { updateReward } = require('./reward.cjs');
+const { prune, pruneFiles, LOG_DIRS } = require('./prune.cjs');
+
+const BASELINE_DIR_REL = ['.wrxn', 'baseline'];
+const SURFACED_REL = ['.wrxn', 'surfaced.json'];
+const REWARD_REL = ['.wrxn', 'reward.json'];
+
+// safeId — canonicalize a session id used as a FILESYSTEM PATH component (sec-F1): lowercase, collapse every
+// non-alnum run to '-', trim, cap length. The baseline marker is keyed by session id; a raw id like
+// '../../evil' would traverse out of .wrxn/baseline. REPLICATED byte-identically from session-start.cjs /
+// code-intel-push.cjs — each install-only hook is self-contained (node stdlib only, no shared import, exactly
+// as secretScan is duplicated across the adapters). session-start sanitizes the SAME way, so the marker the
+// reward shell reads + stamps is exactly the one session-start wrote. NB: the surfaced-log MAP KEY stays RAW
+// (a JSON key is not a path; raw preserves join parity with the S1 surfaced-log writer) — only paths sanitize.
+function safeId(sid) {
+  return String(sid || 'session')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48) || 'session';
+}
+
+// Walk up from cwd / CLAUDE_PROJECT_DIR to the install root carrying wrxn.install.json (mirrors the
+// sibling session hooks). Returns null when no install is found (the hook then no-ops, fail-open).
+function findInstallRoot(startDir) {
+  let dir = startDir || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  for (let i = 0; i < 12; i++) {
+    if (fs.existsSync(path.join(dir, 'wrxn.install.json'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+// A commit subject is a REVERT when git's own `git revert` wrote it: "Revert "<subject>"". Used to flip
+// a session bad — its work did not durably hold. Matched on the canonical prefix git emits.
+function isRevertSubject(s) {
+  return /^Revert "/.test(String(s || ''));
+}
+
+/**
+ * PURE: derive the outcome signal from the new commits made since the session's start-HEAD baseline.
+ *   newCommits present and none is a revert ⇒ +1 (good)
+ *   any new commit is a `git revert`            ⇒ −1 (bad — the session work was corrected)
+ *   no new commits                              ⇒ 0  (neutral — nothing to attribute)
+ * TOTAL: any garbage (null, non-array) is treated as "no new commits" → neutral, never throws.
+ * @param {{newCommits?: string[]}} facts  the git facts gathered by the shell (subjects of baseline..HEAD)
+ * @returns {-1|0|1}
+ */
+function deriveSignal(facts) {
+  const list = facts && Array.isArray(facts.newCommits) ? facts.newCommits : [];
+  if (!list.length) return 0; // no new commits → neutral
+  if (list.some(isRevertSubject)) return -1; // a revert flips the session bad
+  return +1; // new non-revert work, green by construction (Art. III commit gate)
+}
+
+// Read the start-HEAD baseline marker for `sessionId` → { head, rewarded }, or null (absent/malformed →
+// no baseline, the shell then no-ops: without a known start commit "commits this session" is undefined).
+// `rewarded` is the once-per-session guard: set true after this session's first credit. Fail-open.
+function readBaseline(root, sessionId) {
+  try {
+    const raw = fs.readFileSync(path.join(root, ...BASELINE_DIR_REL, safeId(sessionId)), 'utf8');
+    const rec = JSON.parse(raw);
+    const head = rec && typeof rec.head === 'string' ? rec.head.trim() : '';
+    if (!head) return null;
+    return { head, rewarded: !!(rec && rec.rewarded) };
+  } catch {
+    return null;
+  }
+}
+
+// Mark the session's baseline marker as rewarded (the once-per-session guard) so a second SessionEnd for
+// the same session is a no-op. Best-effort: a failure to stamp the guard must not throw — at worst the
+// next run re-credits, which the coalesced no-op already softens for an unchanged surfaced set.
+function markRewarded(root, sessionId) {
+  try {
+    const file = path.join(root, ...BASELINE_DIR_REL, safeId(sessionId));
+    const rec = JSON.parse(fs.readFileSync(file, 'utf8'));
+    rec.rewarded = true;
+    fs.writeFileSync(file, JSON.stringify(rec));
+  } catch {
+    /* best-effort guard */
+  }
+}
+
+// Read THIS session's surfaced set from the per-session surfaced-log (.wrxn/surfaced.json).
+// sec-F3 (carried from S1): every value is treated STRICTLY as a join key — a page-identity STRING —
+// and is NEVER passed to fs as a path to open. We join on the key space only. Returns a de-duplicated
+// array of string keys, or [] (absent / malformed / no entry for this session). Fail-open.
+function readSurfacedSet(root, sessionId) {
+  let map;
+  try {
+    map = JSON.parse(fs.readFileSync(path.join(root, ...SURFACED_REL), 'utf8'));
+  } catch {
+    return []; // absent or malformed surfaced-log → nothing to attribute
+  }
+  if (!map || typeof map !== 'object' || Array.isArray(map)) return [];
+  const entry = map[sessionId];
+  if (!Array.isArray(entry)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const v of entry) {
+    if (typeof v !== 'string') continue; // join keys are strings; ignore anything else (never coerce)
+    const key = v;
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    out.push(key);
+  }
+  return out;
+}
+
+// Production git facts: the subjects of the commits made since the session's start-HEAD baseline, i.e.
+// `git log <baseline>..HEAD --format=%s`. An empty range (HEAD unchanged) → [] → neutral. Rooted at the
+// install; fail-open (no git / bad range → no facts → neutral). NEVER runs the suite (Art. III makes a
+// landed commit green by construction — the signal is git-only and cheap).
+function gitFactsSince(root, baselineHead) {
+  // sec-F2: the baseline head comes from an on-disk marker that could be corrupt — only a sha-SHAPED value
+  // may become a git revision. A missing or non-sha head (option-/ref-expression-shaped) ⇒ neutral, never an
+  // arg to `git log` (defense-in-depth: execFile already blocks the shell; this blocks ref/option abuse).
+  if (!baselineHead || !/^[0-9a-f]{7,40}$/.test(baselineHead)) return { newCommits: [] };
+  try {
+    const out = execFileSync('git', ['log', `${baselineHead}..HEAD`, '--format=%s'], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const newCommits = String(out || '')
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean);
+    return { newCommits };
+  } catch {
+    return { newCommits: [] }; // unknown baseline sha / no git → treat as no new commits (neutral)
+  }
+}
+
+/**
+ * The testable persist core. Reads the session's start-HEAD baseline + surfaced set, derives the
+ * git-grounded signal (git facts injected in tests, gathered from real git in production), applies the
+ * pure Beta-Bernoulli update ONCE for the session, and persists the updated counts to .wrxn/reward.json
+ * via coalesceSidecar. Returns {} always. FAIL-OPEN: any fault → {} (no update), never blocks close.
+ *
+ * No-op (writes nothing) when: no session id, no surfaced pages this session, no baseline, or a NEUTRAL
+ * signal. SHADOW: it only writes counts — it never touches recall ranking.
+ * @param {{payload?:object, root:string, gitFacts?:object}} opts
+ * @returns {object} always {}
+ */
+function run({ payload, root, gitFacts } = {}) {
+  try {
+    const sessionId = payload && typeof payload.session_id === 'string' ? payload.session_id : '';
+    if (!root || !sessionId) return {};
+
+    const surfaced = readSurfacedSet(root, sessionId);
+    if (!surfaced.length) return {}; // nothing surfaced this session → nothing to attribute
+
+    const baseline = readBaseline(root, sessionId);
+    if (!baseline) return {}; // no exact start commit → "commits this session" is undefined → skip
+    if (baseline.rewarded) return {}; // ONCE PER SESSION: already credited → do not double-count
+
+    const facts = gitFacts || gitFactsSince(root, baseline.head);
+    const signal = deriveSignal(facts);
+    if (!signal) return {}; // neutral (no new commits) → no update, no write
+
+    // Persist via the shared coalesced helper: read current counts, apply the pure update once, rewrite.
+    // The update is pure (produces a fresh map); the mutate adopts that map and reports whether it changed.
+    // rev-F2: `wrote` is coalesceSidecar's ACTUAL return (did the rewrite land on disk), NOT the mutate's
+    // computed delta — so a refuse/fail AFTER the mutate (secret-scan refusal, EISDIR, unwritable path) does
+    // not arm the once-per-session guard below, and the dropped attribution stays re-creditable on retry.
+    const wrote = coalesceSidecar(path.join(root, ...REWARD_REL), (map) => {
+      // The discount is OFF in S2 (gate-tuned later, per the PRD); pass no opts → no decay.
+      const next = updateReward(map, surfaced, signal);
+      const before = JSON.stringify(map);
+      // adopt next into the map object the helper will serialize
+      for (const k of Object.keys(map)) delete map[k];
+      Object.assign(map, next);
+      return JSON.stringify(map) !== before; // write only when the counts actually changed
+    });
+
+    // Mark the session credited so a second SessionEnd is a no-op (once-per-session). Only when a write
+    // actually happened — if the helper refused (corrupt/secret), leave the guard unset so a healthy
+    // retry can still attribute.
+    if (wrote) markRewarded(root, sessionId);
+  } catch {
+    // fail-open: a reward-update fault must never block a session closing.
+  }
+  return {};
+}
+
+function main() {
+  let consumed = '';
+  try {
+    consumed = fs.readFileSync(0, 'utf8');
+  } catch {
+    /* no stdin → nothing to attribute */
+  }
+  let payload = {};
+  try {
+    payload = consumed.trim() ? JSON.parse(consumed) : {};
+  } catch {
+    payload = {};
+  }
+  const root = findInstallRoot(payload && payload.cwd);
+  // Rolling retention (C1 / #34): bound the append-only intel logs by age + count at session end, BEFORE
+  // (and independent of) the reward attribution — which returns early in the common case. prune is itself
+  // fail-open; the extra guard keeps a retention fault from ever blocking a session closing.
+  if (root) {
+    try {
+      for (const rel of LOG_DIRS) prune(path.join(root, rel));
+      // S2 (#35): the event source writes one file per session, so after the within-file pass also GC
+      // whole STALE / drained event files (the within-file prune can bound records but never delete a file).
+      pruneFiles(path.join(root, '.wrxn', 'events'));
+    } catch {
+      /* retention is best-effort — never block shutdown */
+    }
+  }
+  let out = {};
+  try {
+    if (root) out = run({ payload, root });
+  } catch {
+    out = {}; // fail-open: never block a session closing
+  }
+  process.stdout.write(JSON.stringify(out || {}));
+  process.exit(0);
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch {
+    process.stdout.write('{}');
+    process.exit(0);
+  }
+}
+
+module.exports = { deriveSignal, run, readSurfacedSet, readBaseline, gitFactsSince, findInstallRoot };

package/payload/.claude/hooks/session-start.cjs

@@ -17,12 +17,82 @@
 
 const fs = require('fs');
 const path = require('path');
+const { execFileSync } = require('child_process');
 
 function emit(envelope) {
   process.stdout.write(JSON.stringify(envelope));
   process.exit(0);
 }
 
+// ── S2 / #13: the start-HEAD baseline (the reward signal's anchor) ────────────────
+// session-start records the session's start commit (git HEAD) into a tiny per-session marker so the
+// session-end reward shell can compute "commits made THIS session" EXACTLY (HEAD-then vs HEAD-now). The
+// git resolver is injected so the marker-writing core is unit-tested with no real repo; production
+// resolves the real HEAD rooted at the install. Wholly fail-open: any fault → no marker, never a throw,
+// orientation always proceeds. The marker dir is STATE (runtime, gitignored), keyed by session id.
+
+const BASELINE_DIR_REL = ['.wrxn', 'baseline'];
+
+// safeId — canonicalize a session id used as a FILESYSTEM PATH component (sec-F1): lowercase, collapse every
+// non-alnum run to '-', trim, cap length. A raw session id concatenated into a path is a traversal surface;
+// this keeps the marker INSIDE .wrxn/baseline. REPLICATED byte-identically from code-intel-push.cjs and the
+// session-end reward shell — each install-only hook is self-contained (node stdlib only, no shared import,
+// exactly as secretScan is duplicated across the adapters). The reward shell sanitizes the SAME way, so the
+// baseline marker round-trips (writer here ↔ reader there) and the read can never miss what this wrote.
+function safeId(sid) {
+  return String(sid || 'session')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48) || 'session';
+}
+
+// Resolve the install repo's current git HEAD sha. Returns the sha string, or null when there is no git
+// / no repo (fail-open). Rooted at the install so a nested cwd can't resolve a different repo's HEAD.
+function resolveGitHead(root) {
+  try {
+    const out = execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const sha = String(out || '').trim();
+    return sha || null;
+  } catch {
+    return null; // no git binary / not a repo / detached with no commit → no baseline (fail-open)
+  }
+}
+
+/**
+ * Stamp the session's start HEAD into <root>/.wrxn/baseline/<sessionId> as { head, at }. Returns true
+ * when a marker was written, false on any fail-open path (no root/session, unresolvable HEAD, unwritable).
+ * The HEAD resolver is injected (tests pass a stub); production uses resolveGitHead. NEVER throws.
+ * @param {string} root  install root
+ * @param {string} sessionId  the session id (marker key)
+ * @param {{resolveHead?:Function, now?:Function}} [opts]
+ * @returns {boolean}
+ */
+function stampStartHead(root, sessionId, opts = {}) {
+  try {
+    if (!root || !sessionId) return false;
+    const resolveHead = opts.resolveHead || (() => resolveGitHead(root));
+    let head;
+    try {
+      head = resolveHead();
+    } catch {
+      return false; // resolver threw → fail-open, no marker
+    }
+    if (!head || typeof head !== 'string') return false; // unresolvable HEAD → no baseline
+    const now = opts.now || Date.now;
+    const dir = path.join(root, ...BASELINE_DIR_REL);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, safeId(sessionId)), JSON.stringify({ head, at: now() }));
+    return true;
+  } catch {
+    return false; // best-effort: a baseline-stamp fault must never block session orientation
+  }
+}
+
 // Walk up from CLAUDE_PROJECT_DIR (or cwd) to the install root carrying wrxn.install.json.
 function findInstallRoot(startDir) {
   let dir = startDir || process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -138,11 +208,26 @@ function main() {
   } catch {
     /* no stdin → still try to orient */
   }
-  void consumed; // SessionStart carries no field we need beyond the install context
+  // SessionStart carries the session id — used to key the start-HEAD baseline marker (#13). Parse
+  // defensively; a malformed payload simply yields no session id (the baseline is then skipped).
+  let event = {};
+  try {
+    event = consumed.trim() ? JSON.parse(consumed) : {};
+  } catch {
+    event = {};
+  }
 
   const root = findInstallRoot();
   if (!root) emit({});
 
+  // Stamp the session's start HEAD so the session-end reward shell can attribute commits made THIS
+  // session (#13 / S2). Fail-open: any fault is swallowed and orientation proceeds unchanged.
+  try {
+    if (event && event.session_id) stampStartHead(root, event.session_id);
+  } catch {
+    /* never block orientation on the baseline stamp */
+  }
+
   // Hold for an in-flight SessionEnd synth (auto-memory-03) so a back-to-back /clear resumes on the
   // FRESH baton, bounded by the crash safety-cap. Fail-open: any fault here must not block orientation.
   try {
@@ -176,4 +261,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = { holdDecision, holdForHandoff, HOLD_CAP_MS };
+module.exports = { holdDecision, holdForHandoff, HOLD_CAP_MS, stampStartHead, resolveGitHead, BASELINE_DIR_REL };