@sawbuck/reins 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+reins (@sawbuck/reins)
+Copyright 2026 Matthew Owens

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# reins (engine)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The engine behind reins: measure how much you steer your AI coding agent. It reads
+a Claude Code session transcript, scores each of your turns for **steering
+pressure** (0 passive → 1 light refine → 2 redirect → 3 hard yank) with a small LLM,
+and prints a seismograph of the session plus the distribution.
+
+This is the LLM half of reins. The deterministic brake-slam counter (`sawbuck yank`)
+lives in sawbuck's offline core; the continuous pressure judge needs a model, so it
+lives here, keeping sawbuck's core model-free. (The reins *plugin*, the Claude Code
+surface, lives alongside this in `plugins/sawbuck-reins/`.)
+
+```
+$ reins
+  reins · steering this session   (judge: ollama:qwen2.5:7b)
+  ..--+-+---+---.--.--..+--+.--
+    . passive   - refine   + redirect   # yank
+
+  you steered 22 of 29 turns (76%)   ·   mean pressure 0.93/3
+  17 light refine · 5 redirect · 0 hard yank · 7 passive
+  the check guards the 7 turns you didn't steer - a miss there is the risk.
+```
+
+## Backend (SAWBUCK_JUDGE)
+
+The judge model is a socket. Set `SAWBUCK_JUDGE` (default `ollama:qwen2.5:7b`):
+
+- `ollama:<model>`, local, free, private (nothing leaves your box). `OLLAMA_HOST`
+  overrides the endpoint. Benchmarked default `qwen2.5:7b`: fastest, smallest, and
+  tied-best accuracy against an opus-labeled gold, model size did not help.
+- `haiku`, Anthropic `claude-haiku-5-5` (needs `ANTHROPIC_API_KEY`); zero VRAM,
+  about $0.00005 per turn.
+- `anthropic:<model>`, any Anthropic model.
+- `openai:<model>`, any OpenAI-compatible endpoint (`OPENAI_BASE_URL`,
+  `OPENAI_API_KEY`).
+
+Output is constrained to a JSON schema where the backend supports it (ollama
+structured outputs), so a thinking model can't break the parse.
+
+## Live on the statusline
+
+`--write [path]` writes the summary JSON (default `.sawbuck/steer.json`). The
+offline `sawbuck statusline` reads that file and shows `🤠 steer 76%` next to its
+own segment, the LLM work happens here, sawbuck's core stays model-free (it only
+reads a file). Keep it fresh by running `reins --write` on a cadence (a `/loop`, a
+watch, or a post-turn hook):
+
+```
+reins --write          # writes .sawbuck/steer.json; the statusline picks it up
+```
+
+## Usage
+
+```
+reins [--session <path.jsonl>] [--judge <backend>] [-n N] [--json] [--write [path]]
+```
+
+Defaults to your newest Claude Code session. `-n` scores only the most recent N
+turns. `--json` is machine-readable. Zero-dep, Node 18+.
+
+## The wizard: harvest your cues
+
+```
+reins wizard [--sessions N] [--max N] [--since DAYS] [--judge <backend>] [--json] [--write [path]] [--yes]
+```
+
+Reads your old Claude Code chats, finds the steers you keep giving (a correction of HOW
+the agent works, not a new task), and ranks them into a cue inventory, so a fresh saddle
+already knows your style. It writes `.sawbuck/cues.json` and prints your top cues, ranked by
+how many distinct sessions they span, then how generalizable they are.
+
+It reads every turn-pair with a model, so on the default local ollama it is free (just
+compute); a hosted backend (`haiku`, `openai:`) costs a little, and the command asks for
+`--yes` before it spends. `--max` caps the pairs scored (default 400). The cues are LEADS,
+candidates from your history to review, not rules it adopts for you.
+
+## Honest limits
+
+A single-turn judge: it sees the agent action and your reply, not the whole thread.
+Models agree on the *shape* (pressure within one level ~95% of the time) more than
+on exact per-turn scores, so read the seismograph and the distribution, not any one
+cell.

package/bin/reins.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// reins: how much did you steer your agent this session? Reads your Claude Code
+// transcript, scores each turn's steering pressure via SAWBUCK_JUDGE, and prints
+// the seismograph + distribution. The check guards the turns you did not steer.
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { scan, resolveSessionPath, pairs } from "../scan.mjs";
+import { score, backend, harvestScore } from "../judge.mjs";
+import { harvest, resolveSessions } from "../wizard.mjs";
+
+const argv = process.argv.slice(2);
+const flag = (n) => { const i = argv.indexOf(n); return i > -1 ? argv[i + 1] : null; };
+const has = (n) => argv.includes(n);
+
+// ---- `reins wizard` / `reins harvest`: read your old chats, rank the cues you keep giving ----
+if (argv[0] === "wizard" || argv[0] === "harvest") {
+  if (has("--help") || has("-h")) {
+    process.stdout.write(`reins wizard: harvest your old Claude Code chats into a cue inventory
+
+Usage: reins wizard [--judge <backend>] [--sessions N] [--max N] [--since DAYS] [--json] [--write [path]] [--yes]
+
+  --sessions N   scan the N most recent sessions (default: all)
+  --max N        cap the turn-pairs scored, for cost/time control (default 400)
+  --since DAYS   only sessions touched in the last DAYS days
+  --judge <b>    ollama:<model> (default, free, local) | haiku | anthropic:<model> | openai:<model>
+  --yes          proceed without the confirm on a HOSTED (paid) backend
+  --write [path] write the cue inventory (default .sawbuck/cues.json)
+  --json         machine-readable output
+
+It reads every turn-pair with a model. On the local ollama default that is free; a hosted backend costs a little.
+`);
+    process.exit(0);
+  }
+  if (flag("--judge")) process.env.SAWBUCK_JUDGE = flag("--judge");
+  const b = backend();
+  const sessionsN = parseInt(flag("--sessions"), 10) || 0;
+  const maxPairs = parseInt(flag("--max"), 10) || 400;
+  const sinceDays = parseInt(flag("--since"), 10) || 0;
+  const sinceMs = sinceDays > 0 ? Date.now() - sinceDays * 86400000 : 0;
+  const sessions = resolveSessions({ limit: sessionsN, sinceMs });
+  if (!sessions.length) { process.stderr.write("reins wizard: no Claude Code sessions found under ~/.claude/projects\n"); process.exit(2); }
+  const hosted = !b.startsWith("ollama:");
+  if (hosted && !has("--yes")) {
+    process.stderr.write(`reins wizard: ${b} is a HOSTED backend and will make up to ${maxPairs} calls (a small cost).\n  re-run with --yes to proceed, or use the free local default (omit --judge).\n`);
+    process.exit(2);
+  }
+  process.stderr.write(`reins wizard: harvesting up to ${maxPairs} turn-pairs from ${sessions.length} session(s) via ${b}${hosted ? " (hosted, paid)" : " (local, free)"}...\n`);
+  const rw = await harvest(harvestScore, { sessions, maxPairs });
+  const wf = flag("--write");
+  const out = wf && !wf.startsWith("--") ? wf : join(process.cwd(), ".sawbuck", "cues.json");
+  if (has("--write") || !has("--json")) {
+    try { mkdirSync(dirname(out), { recursive: true }); writeFileSync(out, JSON.stringify({ at: new Date().toISOString(), backend: b, ...rw }, null, 2) + "\n"); }
+    catch { process.stderr.write("reins wizard: could not write " + out + "\n"); }
+  }
+  if (has("--json")) { process.stdout.write(JSON.stringify({ backend: b, ...rw }, null, 2) + "\n"); process.exit(0); }
+  const pct = rw.scored ? Math.round((rw.steers / rw.scored) * 100) : 0;
+  process.stdout.write(`\n  reins · wizard   (judge: ${b})\n`);
+  process.stdout.write(`  read ${rw.pairs} turn-pairs from ${rw.sessionsRead} session(s) · ${rw.steers} steers (${pct}%)\n\n`);
+  const top = rw.cues.filter((c) => c.count >= 2 || c.gen > 0).slice(0, 12);
+  if (!top.length) { process.stdout.write("  no repeated cues surfaced yet - harvest more sessions (--sessions, --since).\n\n"); process.exit(0); }
+  process.stdout.write("  your top cues (candidates from your history, review before trusting):\n");
+  for (const c of top) {
+    process.stdout.write(`    ${("[" + c.axis + "]").padEnd(13)} ${(c.cue || "(unnamed)").padEnd(34)} · ${c.sessions} sess · gen ${c.genShare} · ${c.count}x\n`);
+  }
+  process.stdout.write(`\n  wrote ${out}\n  these are LEADS. Promote the ones that are really you; the check still guards the rest.\n\n`);
+  process.exit(0);
+}
+
+if (has("--help") || has("-h")) {
+  process.stdout.write(`reins: measure how much you steer your agent this session
+
+Usage: reins [--session <path.jsonl>] [--judge <backend>] [-n N] [--json] [--write [path]] [--share [--label <term>]]
+
+  --session <path>   a Claude Code transcript (default: your newest session)
+  --judge <backend>  override SAWBUCK_JUDGE: ollama:<model> | haiku | anthropic:<model> | openai:<model>
+  -n <N>             score only the most recent N turns
+  --json             machine-readable output
+  --write [path]     also write the summary JSON (default .sawbuck/steer.json) for the
+                     offline sawbuck statusline to read - run it on a cadence for a live readout
+  --share            print a paste-ready card for posting (LinkedIn / X / Reddit)
+  --label <term>     the word for the stat on the share card (default "steer rate";
+                     e.g. "yank rate" for a playful channel - keep it neutral for LinkedIn)
+
+Backend is SAWBUCK_JUDGE (default ollama:qwen2.5:7b). Local = free + private.
+`);
+  process.exit(0);
+}
+
+if (flag("--judge")) process.env.SAWBUCK_JUDGE = flag("--judge");
+const sess = resolveSessionPath(flag("--session"));
+if (!sess) { process.stderr.write("reins: no session transcript found (pass --session <path.jsonl>)\n"); process.exit(2); }
+
+let text = "";
+try { text = readFileSync(sess, "utf8"); } catch { process.stderr.write("reins: cannot read " + sess + "\n"); process.exit(2); }
+
+// --append: incremental, BOUNDED per-turn scoring for the live watcher. Reads the
+// prior tally from .sawbuck/steer.json, scores only the NEW turn-pairs since the last
+// run, merges, rewrites. One new pair per turn - not a full re-scan (which would be
+// quadratic over a session). The sawbuck statusline reads the same steer.json offline.
+if (has("--append")) {
+  const out = join(process.cwd(), ".sawbuck", "steer.json");
+  let prior = { lastPairs: 0, scored: 0, steering: 0, wsum: 0, distribution: { 0: 0, 1: 0, 2: 0, 3: 0 } };
+  try {
+    const p = JSON.parse(readFileSync(out, "utf8"));
+    if (p && p.lastPairs != null) prior = { lastPairs: p.lastPairs, scored: p.scored || 0, steering: p.steering || 0, wsum: p._wsum || 0, distribution: p.distribution || prior.distribution };
+  } catch { /* no prior tally = fresh */ }
+  const all = pairs(text);
+  let added = 0;
+  for (const { prior: a, user: u } of all.slice(prior.lastPairs)) {
+    let s = null; try { s = await score(a, u); } catch {}
+    if (!s) continue;
+    prior.distribution[s.pressure] = (prior.distribution[s.pressure] || 0) + 1;
+    prior.scored++; prior.wsum += s.pressure; added++;
+    if (s.pressure >= 1) prior.steering++;
+  }
+  const rate = prior.scored ? prior.steering / prior.scored : 0;
+  const rec = { at: new Date().toISOString(), backend: backend(), lastPairs: all.length, turns: all.length, scored: prior.scored, steering: prior.steering, steeringRate: rate, meanPressure: prior.scored ? prior.wsum / prior.scored : 0, distribution: prior.distribution, _wsum: prior.wsum };
+  try { mkdirSync(dirname(out), { recursive: true }); writeFileSync(out, JSON.stringify(rec) + "\n"); } catch { process.stderr.write("reins: could not write " + out + "\n"); }
+  if (has("--json")) process.stdout.write(JSON.stringify(rec) + "\n");
+  else process.stdout.write(`reins: +${added} new turn(s), steer rate ${Math.round(rate * 100)}% over ${prior.scored} turns\n`);
+  process.exit(0);
+}
+
+const n = parseInt(flag("-n"), 10) || 0;
+const r = await scan(text, score, { limit: n });
+
+// --write [path]: persist the summary so an OFFLINE reader (the sawbuck statusline)
+// can display the live steering number without ever calling a model itself.
+if (has("--write")) {
+  const wf = flag("--write");
+  const out = wf && !wf.startsWith("--") ? wf : join(process.cwd(), ".sawbuck", "steer.json");
+  try {
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, JSON.stringify({ at: new Date().toISOString(), backend: backend(), turns: r.turns, scored: r.scored, steering: r.steering, steeringRate: r.steeringRate, meanPressure: r.meanPressure, distribution: r.distribution }) + "\n");
+  } catch { process.stderr.write("reins: could not write " + out + "\n"); }
+}
+
+if (has("--json")) { process.stdout.write(JSON.stringify({ backend: backend(), ...r }) + "\n"); process.exit(0); }
+
+// --share: a tasteful, paste-anywhere card (plain text works on LinkedIn / X / Reddit).
+// --label swaps the stat's word; default stays neutral ("steer rate") so it's safe for a
+// professional feed, e.g. --label "yank rate" for a playful channel.
+if (has("--share")) {
+  if (r.scored === 0) { process.stdout.write("reins: nothing to share yet (no turns scored).\n"); process.exit(0); }
+  const lf = flag("--label");
+  const label = lf && !lf.startsWith("--") ? lf : "steer rate";
+  const pct = Math.round(r.steeringRate * 100);
+  const d = r.distribution;
+  const texture = d[1] >= d[2] + d[3] ? "mostly light refinements" : d[3] > 0 ? "a few hard pulls" : "real redirects";
+  const grip = pct >= 60 ? "hands-on" : pct >= 30 ? "a steady hand" : "a loose rein";
+  process.stdout.write(
+`my ${label} this session 🐴
+
+  ${r.seismograph}
+  · let it ride   - nudge   + redirect   # hard pull
+
+I steered ${r.steering} of ${r.scored} turns (${pct}%) — ${grip}, ${texture}.
+The ${r.scored - r.steering} I let ride, the check had my back.
+
+— measured with reins · sawbuck
+`);
+  process.exit(0);
+}
+
+const pct = Math.round(r.steeringRate * 100);
+const d = r.distribution;
+process.stdout.write(`\n  reins · steering this session   (judge: ${backend()})\n`);
+if (r.scored === 0) {
+  process.stdout.write(`  no turns scored${r.fails ? ` (${r.fails} judge errors - is the backend reachable?)` : ""}.\n\n`);
+  process.exit(r.fails ? 2 : 0);
+}
+process.stdout.write(`  ${r.seismograph}\n`);
+process.stdout.write(`    . passive   - refine   + redirect   # yank\n\n`);
+process.stdout.write(`  you steered ${r.steering} of ${r.scored} turns (${pct}%)   ·   mean pressure ${r.meanPressure.toFixed(2)}/3\n`);
+process.stdout.write(`  ${d[1]} light refine · ${d[2]} redirect · ${d[3]} hard yank · ${d[0]} passive${r.fails ? ` · ${r.fails} skipped` : ""}\n`);
+process.stdout.write(`  the check guards the ${r.scored - r.steering} turns you didn't steer - a miss there is the risk.\n`);
+if (r.recent.length) {
+  process.stdout.write(`\n  recent steers:\n`);
+  for (const s of r.recent) process.stdout.write(`    ${["", "-", "+", "#"][s.pressure]}${s.pressure} ${(s.axis || "").padEnd(12)} ${s.nudge}\n`);
+}
+process.stdout.write("\n");

package/judge.mjs

@@ -0,0 +1,132 @@
+// judge.mjs - the steering judge's backend socket.
+//
+//   score(prior, user)        -> {pressure 0-3, axis, nudge}   (the per-turn seismograph)
+//   harvestScore(prior, user) -> {steer, axis, magnitude, generalizable, cue}   (the wizard's cue finder)
+//
+// Both run through the backend SAWBUCK_JUDGE selects. This file does network/LLM calls ON
+// PURPOSE - it is a STANDALONE tool, never imported into sawbuck's offline core.
+//
+// Backends (SAWBUCK_JUDGE):
+//   ollama:<model>     local, free, private - the default (ollama:qwen2.5:7b). OLLAMA_HOST overrides.
+//   haiku              Anthropic claude-haiku-5-5 (needs ANTHROPIC_API_KEY); cheap hosted, zero VRAM.
+//   anthropic:<model>  any Anthropic model.
+//   openai:<model>     any OpenAI-compatible endpoint (OPENAI_BASE_URL + OPENAI_API_KEY).
+//
+// Benchmarked default = qwen2.5:7b: tied-best accuracy vs an opus gold, fastest, smallest.
+
+// ---- schemas (ollama structured outputs: a grammar, not a prayer, so no parse-fails) ----
+const PRESSURE_SCHEMA = {
+  type: "object",
+  properties: {
+    pressure: { type: "integer", enum: [0, 1, 2, 3] },
+    axis: { type: "string" },
+    nudge: { type: "string" },
+  },
+  required: ["pressure", "axis", "nudge"],
+};
+const HARVEST_SCHEMA = {
+  type: "object",
+  properties: {
+    steer: { type: "boolean" },
+    axis: { type: "string" },
+    magnitude: { type: "string", enum: ["refine", "redirect", "hard-stop"] },
+    generalizable: { type: "boolean" },
+    cue: { type: "string" },
+  },
+  required: ["steer", "axis", "magnitude", "generalizable", "cue"],
+};
+
+const PROMPT = (a, u) =>
+`You rate how much a developer's message STEERS an AI coding agent's current work.
+Output ONLY one JSON object: {"pressure":0-3,"axis":"one-word","nudge":"<=8 words"}
+pressure: 0 passive (approval like "yes/go/do it", a pure question, or a brand-new unrelated task; NOT steering current work). 1 light refine (small adjustment to the SAME work: tone, length, scope, emphasis, "a bit more X", "also Y"). 2 redirect (change the approach/direction of current work). 3 hard-stop ("no/stop/undo/revert", reject and restart).
+AGENT just did: ${a}
+USER replied: ${u}
+JSON:`;
+
+const HARVEST_PROMPT = (a, u) =>
+`You analyze a developer's message to an AI coding agent to find a repeated STEER: a correction of HOW the agent works, not a new task.
+Output ONLY one JSON object: {"steer":true|false,"axis":"one-word","magnitude":"refine|redirect|hard-stop","generalizable":true|false,"cue":"<=6 words"}
+steer: true if the message corrects or redirects the current work; false for a brand-new task, a pure question, or plain approval.
+axis: the dimension - rigor, scope, approach, correctness, format, process, tone, naming, or constraint.
+magnitude: refine (small adjustment) | redirect (change the approach) | hard-stop (reject or undo).
+generalizable: true if it is a STANDING preference that would apply to future work, false if specific to this one case.
+cue: a short imperative naming the rule, e.g. "verify before claiming done".
+AGENT just did: ${String(a).slice(0, 600)}
+USER replied: ${String(u).replace(/\s+/g, " ").slice(0, 800)}
+JSON:`;
+
+// lenient parse: strip reasoning-model <think> blocks, take the last JSON object.
+function lastJson(txt) {
+  txt = String(txt).replace(/<think>[\s\S]*?<\/think>/g, "");
+  const cands = txt.match(/\{[^{}]*\}/g) || [];
+  for (const c of cands.reverse()) { try { return JSON.parse(c); } catch { /* keep scanning */ } }
+  return null;
+}
+export function parse(txt) {
+  const j = lastJson(txt);
+  if (!j || j.pressure == null) return null;
+  return {
+    pressure: Math.max(0, Math.min(3, parseInt(j.pressure, 10) || 0)),
+    axis: String(j.axis || "").slice(0, 16),
+    nudge: String(j.nudge || "").slice(0, 48),
+  };
+}
+export function parseHarvest(txt) {
+  const j = lastJson(txt);
+  if (!j || j.steer == null) return null;
+  const mags = ["refine", "redirect", "hard-stop"];
+  return {
+    steer: j.steer === true,
+    axis: String(j.axis || "other").toLowerCase().slice(0, 20),
+    magnitude: mags.includes(j.magnitude) ? j.magnitude : "refine",
+    generalizable: j.generalizable === true,
+    cue: String(j.cue || "").trim().slice(0, 60),
+  };
+}
+
+// one backend call -> RAW text (the caller parses). schema is used where the backend supports it (ollama).
+async function complete(promptStr, schema) {
+  const b = backend();
+  if (b === "haiku") return anthropic("claude-haiku-5-5", promptStr);
+  if (b.startsWith("anthropic:")) return anthropic(b.slice(10), promptStr);
+  if (b.startsWith("ollama:")) return ollama(b.slice(7), promptStr, schema);
+  if (b.startsWith("openai:")) return openai(b.slice(7), promptStr);
+  throw new Error("unknown SAWBUCK_JUDGE backend: " + b + " (use ollama:<model> | haiku | anthropic:<model> | openai:<model>)");
+}
+
+async function ollama(model, promptStr, schema) {
+  const host = process.env.OLLAMA_HOST || "http://localhost:11434";
+  const res = await fetch(host + "/api/generate", {
+    method: "POST", headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ model, prompt: promptStr, stream: false, format: schema, options: { temperature: 0, num_predict: 800 } }),
+  });
+  const j = await res.json();
+  return j.response || "";
+}
+async function anthropic(model, promptStr) {
+  const key = process.env.ANTHROPIC_API_KEY;
+  if (!key) throw new Error("ANTHROPIC_API_KEY not set (SAWBUCK_JUDGE=haiku needs it)");
+  const res = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST", headers: { "Content-Type": "application/json", "x-api-key": key, "anthropic-version": "2023-06-01" },
+    body: JSON.stringify({ model, max_tokens: 200, messages: [{ role: "user", content: promptStr }] }),
+  });
+  const j = await res.json();
+  return (j.content || []).filter((x) => x.type === "text").map((x) => x.text).join("");
+}
+async function openai(model, promptStr) {
+  const base = process.env.OPENAI_BASE_URL || "https://api.openai.com/v1";
+  const key = process.env.OPENAI_API_KEY;
+  if (!key) throw new Error("OPENAI_API_KEY not set");
+  const res = await fetch(base.replace(/\/$/, "") + "/chat/completions", {
+    method: "POST", headers: { "Content-Type": "application/json", Authorization: "Bearer " + key },
+    body: JSON.stringify({ model, temperature: 0, max_tokens: 200, response_format: { type: "json_object" }, messages: [{ role: "user", content: promptStr }] }),
+  });
+  const j = await res.json();
+  return j.choices?.[0]?.message?.content || "";
+}
+
+export function backend() { return process.env.SAWBUCK_JUDGE || "ollama:qwen2.5:7b"; }
+
+export async function score(prior, user) { return parse(await complete(PROMPT(prior, user), PRESSURE_SCHEMA)); }
+export async function harvestScore(prior, user) { return parseHarvest(await complete(HARVEST_PROMPT(prior, user), HARVEST_SCHEMA)); }

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@sawbuck/reins",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Reins: measure how much you steer your AI coding agent. A per-turn steering-pressure judge over your session transcript, pluggable backend (Haiku / local ollama / any OpenAI-compatible). The LLM half of the reins steering layer; keeps sawbuck's core offline.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "bin": {
+    "reins": "bin/reins.mjs"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "bin/reins.mjs",
+    "judge.mjs",
+    "scan.mjs",
+    "wizard.mjs",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/scan.mjs

@@ -0,0 +1,126 @@
+// scan.mjs - turn a Claude Code session transcript into a steering-pressure
+// reading: score each of your turns (given the agent action it followed) and
+// aggregate into a distribution + a seismograph. The scorer is injected so the
+// aggregation is testable without a live model.
+
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+function humanText(o) {
+  if (!o || o.type !== "user" || o.isMeta) return null;
+  if (o.userType && o.userType !== "external") return null;
+  const c = o.message && o.message.content;
+  if (typeof c === "string") return c;
+  if (Array.isArray(c)) {
+    if (c.some((b) => b && b.type === "tool_result")) return null;
+    const t = c.filter((b) => b && b.type === "text").map((b) => b.text || "").join(" ");
+    return t || null;
+  }
+  return null;
+}
+function assistantText(o) {
+  const c = o.message && o.message.content;
+  if (Array.isArray(c)) return c.filter((b) => b && b.type === "text").map((b) => b.text || "").join(" ").trim();
+  if (typeof c === "string") return c.trim();
+  return "";
+}
+const noise = (t) => {
+  const s = t.trim();
+  if (s.includes("<task-notification>") || s.startsWith("<task-id>")) return true;
+  if (s.replace(/\[Image #\d+\]/g, "").trim().length < 3) return true;
+  return false;
+};
+
+// Extract the (prior-agent, user-turn) pairs to score: every non-opener human turn
+// that followed an agent action.
+export function pairs(text) {
+  const out = [];
+  let prev = "", seen = false;
+  for (const line of String(text).split("\n")) {
+    if (!line.trim()) continue;
+    let o; try { o = JSON.parse(line); } catch { continue; }
+    if (o.type === "assistant") { prev = assistantText(o); continue; }
+    const t = humanText(o);
+    if (t === null || noise(t)) continue;
+    if (!seen) { seen = true; continue; }       // opener = a request, not a steer
+    if (prev) out.push({ prior: prev.slice(0, 600), user: t.replace(/\s+/g, " ").slice(0, 800) });
+    prev = "";
+  }
+  return out;
+}
+
+const GLYPH = { 0: ".", 1: "-", 2: "+", 3: "#" };
+
+// scan(text, scoreFn) -> aggregate. scoreFn(prior, user) -> {pressure, axis, nudge} | null.
+export async function scan(text, scoreFn, { limit = 0 } = {}) {
+  let ps = pairs(text);
+  if (limit > 0 && ps.length > limit) ps = ps.slice(-limit);   // most recent N
+  const dist = { 0: 0, 1: 0, 2: 0, 3: 0 };
+  let scored = 0, fails = 0, wsum = 0, spark = "";
+  const recent = [];
+  for (const { prior, user } of ps) {
+    let r = null;
+    try { r = await scoreFn(prior, user); } catch { r = null; }
+    if (!r) { fails++; spark += "?"; continue; }
+    dist[r.pressure]++; scored++; wsum += r.pressure; spark += GLYPH[r.pressure];
+    if (r.pressure >= 1) recent.push({ pressure: r.pressure, axis: r.axis, nudge: r.nudge, user: user.slice(0, 60) });
+  }
+  const turns = ps.length;
+  const steering = dist[1] + dist[2] + dist[3];
+  return {
+    turns, scored, fails,
+    distribution: dist,
+    steering, steeringRate: scored ? steering / scored : 0,
+    meanPressure: scored ? wsum / scored : 0,
+    seismograph: spark,
+    recent: recent.slice(-6),
+  };
+}
+
+// Resolve the newest session transcript for a cwd (Claude Code: ~/.claude/projects/
+// <encoded-cwd>/<id>.jsonl). Best-effort; prefer the cwd's dir, else newest overall.
+export function resolveSessionPath(explicit, cwd = process.cwd()) {
+  if (explicit) return existsSync(explicit) ? explicit : null;
+  const root = join(homedir(), ".claude", "projects");
+  if (!existsSync(root)) return null;
+  const key = cwd.replace(/[^A-Za-z0-9]/g, "-");
+  let dirs = [];
+  try { dirs = readdirSync(root).map((d) => join(root, d)).filter((p) => { try { return statSync(p).isDirectory(); } catch { return false; } }); }
+  catch { return null; }
+  const matched = dirs.filter((p) => p.endsWith("/" + key));
+  const pool = matched.length ? matched : dirs;
+  let best = null, bestT = 0;
+  for (const full of pool) {
+    let files = []; try { files = readdirSync(full); } catch { continue; }
+    for (const f of files) {
+      if (!f.endsWith(".jsonl")) continue;
+      const p = join(full, f);
+      try { const st = statSync(p); if (st.mtimeMs > bestT) { bestT = st.mtimeMs; best = p; } } catch {}
+    }
+  }
+  return best;
+}
+
+// Enumerate recent Claude Code session transcripts across ALL projects, newest first.
+// For the wizard's harvest ("read my old chats"). { limit } caps the count; { sinceMs }
+// drops anything older. Best-effort; returns [] if the projects dir is missing.
+export function resolveSessions({ limit = 0, sinceMs = 0 } = {}) {
+  const root = join(homedir(), ".claude", "projects");
+  if (!existsSync(root)) return [];
+  let dirs = [];
+  try { dirs = readdirSync(root).map((d) => join(root, d)).filter((p) => { try { return statSync(p).isDirectory(); } catch { return false; } }); }
+  catch { return []; }
+  const found = [];
+  for (const d of dirs) {
+    let files = []; try { files = readdirSync(d); } catch { continue; }
+    for (const f of files) {
+      if (!f.endsWith(".jsonl")) continue;
+      const p = join(d, f);
+      try { const st = statSync(p); if (sinceMs && st.mtimeMs < sinceMs) continue; found.push({ path: p, mtime: st.mtimeMs }); } catch {}
+    }
+  }
+  found.sort((a, b) => b.mtime - a.mtime);
+  const sliced = limit > 0 ? found.slice(0, limit) : found;
+  return sliced.map((f) => f.path);
+}

package/wizard.mjs

@@ -0,0 +1,62 @@
+// wizard.mjs - the harvest: read your old Claude Code chats, find the STEERS you keep
+// giving, and rank them into a cue inventory, so a fresh saddle already knows your style.
+//
+// Token honesty: every turn-pair is read by a model. On the default local ollama that is
+// free (just compute); on a hosted backend it costs a little. The CLI prints the count and
+// the backend before it runs. The scorer is injected here so the aggregation is testable
+// without a model.
+
+import { readFileSync } from "node:fs";
+import { pairs, resolveSessions } from "./scan.mjs";
+
+// aggregateCues(items) -> ranked cue inventory. items = [{ session, result }], where
+// result = { steer, axis, magnitude, generalizable, cue } | null. Pure + deterministic.
+// Rank = distinct-session support, then generalizable count, then raw frequency (so a
+// one-session spike never outranks a cue you give across many sessions - the study's lesson).
+export function aggregateCues(items) {
+  const clusters = new Map();
+  let scored = 0, steers = 0, fails = 0;
+  for (const { session, result } of items) {
+    if (!result) { fails++; continue; }
+    scored++;
+    if (!result.steer) continue;
+    steers++;
+    const key = (result.axis || "other") + "|" + String(result.cue || "").toLowerCase().replace(/\s+/g, " ").trim().slice(0, 40);
+    const c = clusters.get(key) || { axis: result.axis || "other", cue: result.cue || "", count: 0, gen: 0, sessions: new Set(), mag: { refine: 0, redirect: 0, "hard-stop": 0 } };
+    c.count++;
+    if (result.generalizable) c.gen++;
+    if (result.magnitude && c.mag[result.magnitude] != null) c.mag[result.magnitude]++;
+    if (session) c.sessions.add(session);
+    // keep the most specific non-empty cue text seen for this cluster
+    if (!c.cue && result.cue) c.cue = result.cue;
+    clusters.set(key, c);
+  }
+  const cues = [...clusters.values()]
+    .map((c) => ({ axis: c.axis, cue: c.cue, count: c.count, gen: c.gen, genShare: c.count ? +(c.gen / c.count).toFixed(2) : 0, sessions: c.sessions.size, magnitude: c.mag }))
+    .sort((a, b) => (b.sessions - a.sessions) || (b.gen - a.gen) || (b.count - a.count));
+  return { scored, steers, fails, steerRate: scored ? +(steers / scored).toFixed(3) : 0, cues };
+}
+
+// harvest(scoreFn, { sessions, maxPairs }) -> aggregateCues over the pairs in those session
+// files, newest first, capped at maxPairs (cost control). scoreFn(prior, user) -> result | null.
+export async function harvest(scoreFn, { sessions = [], maxPairs = 400 } = {}) {
+  const items = [];
+  const gathered = [];
+  for (const path of sessions) {
+    let text = ""; try { text = readFileSync(path, "utf8"); } catch { continue; }
+    for (const p of pairs(text)) {
+      gathered.push({ ...p, session: path });
+      if (gathered.length >= maxPairs) break;
+    }
+    if (gathered.length >= maxPairs) break;
+  }
+  for (const { prior, user, session } of gathered) {
+    let result = null;
+    try { result = await scoreFn(prior, user); } catch { result = null; }
+    items.push({ session, result });
+  }
+  const agg = aggregateCues(items);
+  return { pairs: gathered.length, sessionsRead: sessions.length, ...agg };
+}
+
+export { resolveSessions };