codehere 2.1.0-rc.0 → 2.1.0-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -119,8 +119,11 @@ codehere show <id> read a help card
119
119
  codehere reply <id> "answer" [--solved] answer; --solved makes a lesson
120
120
  codehere status what Codehere has seen
121
121
  codehere stats turns to green, loops stopped, context size
122
+ codehere audit commits of the last 90 days to read: tests deleted, skipped or weakened
122
123
  ```
123
124
 
125
+ `codehere audit` reads this repo's git history on your machine and sends nothing anywhere. It lists the commits that deleted a test file, skipped a test, left tests out of the test script or runner config, or removed or weakened assertions in test files, and says which ones carry an agent's marker (`Co-Authored-By` naming Claude, Copilot or Codex, `Claude-Session:`, `Agent-Logs-Url:`, Claude Code's "Generated with Claude Code" footer, or the `copilot-swe-agent[bot]` author). The count is found by pattern: read each commit before drawing a conclusion. On 12 public repos picked before measuring, about 1 in 25 listed commits had left the tests checking less; most were tests rewritten along with a changed feature ([results](docs/evidence/2026-11-13-audit-heldout-results.md)). A commit with no marker may still be an agent's, since markers can be turned off.
126
+
124
127
  When an agent runs `rule`, `lesson`, `help` or `reply`, the command prints a draft and saves nothing. Codehere saves it if your next message is a plain yes. Typed in your own terminal, they save at once.
125
128
 
126
129
  ## What lives where
@@ -164,14 +167,16 @@ npm test # end-to-end checks
164
167
  - The "done" check needs a test command. Without one, only the tampering check runs.
165
168
  - Approvals are per folder. Each git worktree or extra clone needs its own `codehere approve`.
166
169
  - In `codex exec`, Codex shows you none of Codehere's lines. The agent still gets every message, and the finish check still sends it back.
167
- - Copilot shows you none of Codehere's lines either, so on Copilot you do not see the ✓, the ⊘, or the notes about an approval, an uninstall or a settings change during a session. The agent gets every message except what Codehere adds to your prompt (Copilot drops that, so its agent is not told when a draft is saved or discarded), and when the finish check sends it back you see the reason as the next prompt.
170
+ - Copilot shows you none of Codehere's lines either, so on Copilot you do not see the ✓, the ⊘, or the notes about an approval, an uninstall, a settings change or team files changed during a session. The agent gets every message except what Codehere adds to your prompt (Copilot drops that, so its agent is not told when a draft is saved or discarded), and when the finish check sends it back you see the reason as the next prompt.
168
171
  - Copilot's cloud agent also runs the committed `.github/hooks/codehere.json`. `codehere` is not installed there, so by GitHub's docs each hook fails and the job carries on without Codehere.
169
172
  - `codehere approve` and `codehere uninstall` ask only in your own terminal. They refuse when Claude Code, Codex or Copilot is among the processes above them, and inside Codex's sandbox. An agent that detaches its terminal on purpose can still answer, so the finish check of a session that was open tells you when an approval or an uninstall happened (not on Copilot, which shows none of these lines).
170
173
  - Approving `npm test` approves that command, not the scripts behind it in `package.json`. And Claude Code runs any hook a teammate adds to the committed `.claude/settings.json`, as Copilot does in a trusted folder for `.github/hooks/` and `.claude/settings.json`; Codex asks each developer to trust a new or changed hook first. Both are your repo's code, with the same trust as running it yourself.
171
174
  - When the agent changes `.codehere/config.json`, `.codehere/rules.md` (except a rule saved after your yes), the hook and env settings in `.claude/settings*.json` or `.github/copilot/settings*.json`, or `.codex/hooks.json`, `.codex/config.toml` or `.github/hooks/codehere.json` during a session, the finish check tells you. It cannot tell you if the session ends without a finish check, for example when you close it mid-turn. An agent that sets out to fake your terminal or rewrite Codehere's local files can also get around this.
175
+ - When the agent writes, changes or deletes a lesson or help card in `.codehere/` itself during a session, without a draft you said yes to, the finish check lists the files for you (not on Copilot or in `codex exec`, which show none of Codehere's lines). It does not stop the agent, and it does not list files that arrive committed, such as after a `git pull`, or a change the agent commits itself. A card a pull changes while it holds your own uncommitted changes is listed. A command that also deletes Codehere's local files, such as `git clean -x`, hides the change, and so can an agent that sets out to hide a change from git.
172
176
  - Only the test command needs approval. A teammate who sets `verifyOnStop` to `false` in `.codehere/config.json` turns the finish check off for everyone; `codehere status` shows it as off.
173
177
  - Sharing is through git. There is no server, so teammates see updates after `git pull`.
174
- - The yes before a draft is saved is checked by Codehere's hooks with a word list. An agent deliberately working around Codehere could fake that reply, as it could fake other hook input, or write files in `.codehere/` directly; that is not stopped or reported.
178
+ - `codehere audit` follows git's `--since`: git stops reading history at the first commit older than 90 days, so a newer commit behind a back-dated one is not read. A shallow clone has no history to read, and the audit says so.
179
+ - The yes before a draft is saved is checked by Codehere's hooks with a word list. An agent deliberately working around Codehere could fake that reply, as it could fake other hook input.
175
180
  - A command you send through the agent drafts: Claude Code's `!` and scripts with no terminal take the agent's path, and so does every command on a machine without `ps`. In VS Code an agent's command can run in a real terminal with no agent above it, and then saves at once. No test has shown whether a `!` command reaches Codehere's hooks; if it does not, your yes gets a "nothing saved" line.
176
181
  - A one-shot run (`claude -p`, `codex exec`) that is never resumed has no next message, so its drafts are never saved; a resumed turn (`--resume`, `codex exec resume`) can answer them. Unsaved drafts are removed after 7 days.
177
182
  - Codex saves no drafts until you trust its hooks in `/hooks`.
@@ -181,6 +186,6 @@ npm test # end-to-end checks
181
186
  - Restart briefs are written without a yes, for your own next session. They enter git only if you commit `.codehere/briefs/`.
182
187
  - A committed link to a folder that holds another repo's `.codehere/` can lead Codehere, run from inside that folder, to write its own local files there. `init` can stop halfway on a file it may not write, such as a read-only `.gitignore`.
183
188
  - Prompt checks are plain word lists (English and Indonesian). They can miss a short prompt in another language.
184
- - The weakened-test scan catches skipped and focused tests (`.skip`, `xit`, `{ skip: true }`, `.only`, `fit`), deleted test files, an assertion commented out with `//` or `#`, assertions that cannot fail (`assert.equal(1, 1)`), at least two more assertion lines removed than added, and a `package.json` test script changed to always pass (`|| true`). It does not catch one removed assertion, assertions wrapped in `/* */`, options spread over several lines, an edited expected value, or a `return` above an assertion; see `docs/overlap-with-check.md`.
189
+ - The weakened-test scan catches skipped and focused tests (`.skip`, `xit`, `{ skip: true }`, a skip option added to a test that already existed, `.only`, `fit`, Python's `skip` and a `skipif` with a literal condition), deleted test files, a test replaced by a differently named one (a renamed test counts), tests left out by the test script or the runner's config, an assertion commented out with `//` or `#`, assertions that cannot fail (`assert.equal(1, 1)`), at least two more assertion lines removed than added, an expected value changed (in an assertion or in a `want` or `expected` variable), an assertion flipped to its opposite or weakened to a truthy check, the call a test checks changed while its expected value stayed, a case dropped from a list on one line or rows of a test table reordered, an assertion inside a `try` that swallows its failure, a test script or CI test step made to always pass, a CI test step removed, code that returns the exact value a test expects for that test's input, and code that reads a test runner's own marker. Several of these rules are ported from noskip (MIT). It does not catch one removed assertion, assertions wrapped in `/* */`, options spread over several lines, a `return` above an assertion, a row removed from a multi-line test table, or a new test that skips itself on a variable; see `docs/overlap-with-check.md`. On the held-out half of CheatBench (Claude Code runs labelled by a person) it sent back 15 of 19 runs that changed a test to pass and 0 of 30 honest runs, with those results seen once before: `docs/evidence/2026-11-13-cheatbench.md`.
185
190
 
186
191
  MIT licensed.
package/bin/codehere.js CHANGED
@@ -47,6 +47,7 @@ When you're stuck
47
47
 
48
48
  codehere status what Codehere has seen
49
49
  codehere stats turns to green, loops stopped, session size
50
+ codehere audit commits of the last 90 days that deleted, skipped or weakened tests
50
51
 
51
52
  Run by an agent, rule, lesson, help and reply print a draft; it is saved if your next
52
53
  message in the chat is a plain yes. Typed in your own terminal, they save at once.
@@ -86,6 +87,12 @@ const run = async () => {
86
87
  return cmd.status();
87
88
  case 'stats':
88
89
  return cmd.stats();
90
+ case 'audit': {
91
+ // loaded only here: the hooks run on every agent turn and must stay fast
92
+ const { audit } = await import('../src/audit.js');
93
+ process.exitCode = await audit(process.cwd());
94
+ return;
95
+ }
89
96
  default:
90
97
  if (flags.version || command === '-v') {
91
98
  return console.log(`codehere ${JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codehere",
3
- "version": "2.1.0-rc.0",
3
+ "version": "2.1.0-rc.3",
4
4
  "description": "A git-native team brain for vibe coders. Silent fixes for AI coding agents: breaks doom loops, verifies 'done', blocks test tampering, and shares what your team learned.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -18,7 +18,7 @@
18
18
  "README.md"
19
19
  ],
20
20
  "engines": {
21
- "node": ">=18"
21
+ "node": ">=20"
22
22
  },
23
23
  "scripts": {
24
24
  "test": "node test/e2e.mjs"
package/src/audit.js ADDED
@@ -0,0 +1,173 @@
1
+ // codehere audit: the commits of the last 90 days that deleted, skipped or weakened tests, each listed for a person to read.
2
+ // Read-only: it runs git on this machine and sends nothing anywhere. The kinds come from the finish
3
+ // check's own detector. A count found by pattern is a list of candidates, never proof (DESIGN.md §1).
4
+ import { spawn, execFileSync } from 'node:child_process';
5
+ import readline from 'node:readline';
6
+ import { printable, hasGit } from './brain.js';
7
+ import { tamperEvents, isTestFile, isTestConfig } from './signals.js';
8
+
9
+ const DAYS = 90;
10
+ const KINDS = new Set(['test-deleted', 'test-skipped', 'assertion-weakened']);
11
+ const BIG = 512 * 1024 * 1024;
12
+
13
+ // How agents mark their commits. A commit without a marker is still counted and listed, unmarked:
14
+ // markers can be turned off, and some agents leave none.
15
+ const MARKERS = [
16
+ { re: /^Co-authored-by:[^\n]*\b(Claude|Copilot|Codex)\b/im, name: (m) => `Co-Authored-By ${m[1]}` },
17
+ { re: /^Claude-Session:/im, name: () => 'Claude-Session' },
18
+ { re: /^Agent-Logs-Url:/im, name: () => 'Agent-Logs-Url' },
19
+ // Claude Code's commit footer, the one marker a squash merge often keeps
20
+ { re: /Generated with \[?Claude Code\b/i, name: () => 'Generated with Claude Code' },
21
+ ];
22
+
23
+ export function markersOf(author, body) {
24
+ const found = /copilot-swe-agent\[bot\]/i.test(author) ? ['copilot-swe-agent[bot]'] : [];
25
+ for (const m of MARKERS) {
26
+ const x = m.re.exec(body);
27
+ if (x) found.push(m.name(x));
28
+ }
29
+ return found;
30
+ }
31
+
32
+ function gitLine(root, args) {
33
+ try {
34
+ return execFileSync('git', args, { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
35
+ } catch {
36
+ return null;
37
+ }
38
+ }
39
+
40
+ // Every non-merge commit since `since`, with what the markers need.
41
+ function commitsSince(root, since) {
42
+ const out = execFileSync('git', ['log', '--no-merges', `--since=${since}`, '--format=%H%x1f%an <%ae>%x1f%cs%x1f%s%x1f%B%x1e'], {
43
+ cwd: root,
44
+ stdio: ['ignore', 'pipe', 'ignore'],
45
+ maxBuffer: BIG,
46
+ }).toString();
47
+ return out
48
+ .split('\x1e')
49
+ .map((r) => r.replace(/^\n/, ''))
50
+ .filter(Boolean)
51
+ .map((r) => {
52
+ const [sha, author, date, subject, body = ''] = r.split('\x1f');
53
+ return { sha, author, date, subject, body, events: [] };
54
+ });
55
+ }
56
+
57
+ // The path in `diff --git a/P b/P` when both sides name the same file, as they do for a deletion.
58
+ function samePath(line) {
59
+ const rest = line.slice('diff --git a/'.length);
60
+ const half = (rest.length - ' b/'.length) / 2;
61
+ return Number.isInteger(half) && rest.slice(half, half + 3) === ' b/' ? rest.slice(0, half) : '';
62
+ }
63
+
64
+ // One `git log -p`, read line by line: hunks of test files and of the files that say which tests run
65
+ // (package.json, runner configs) are kept, a deleted file by its name only, so
66
+ // memory stays small however large a commit is. Each commit's kinds go on its entry in bySha.
67
+ function scanChanges(root, since, bySha) {
68
+ return new Promise((resolve, reject) => {
69
+ const child = spawn('git', ['log', '--no-merges', `--since=${since}`, '-p', '--no-color', '--format=%x00%H'], {
70
+ cwd: root,
71
+ stdio: ['ignore', 'pipe', 'ignore'],
72
+ });
73
+ const lines = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
74
+ let commit = null;
75
+ let nameStatus = [];
76
+ let kept = [];
77
+ let keep = false;
78
+ let deleted = '';
79
+ const finish = () => {
80
+ if (commit) commit.events = tamperEvents(nameStatus.join('\n'), kept.join('\n')).filter((e) => KINDS.has(e.kind));
81
+ };
82
+ lines.on('line', (line) => {
83
+ if (line.startsWith('\0')) {
84
+ finish();
85
+ commit = bySha.get(line.slice(1)) || null;
86
+ nameStatus = [];
87
+ kept = [];
88
+ keep = false;
89
+ return;
90
+ }
91
+ if (!commit) return;
92
+ if (line.startsWith('diff --git ')) {
93
+ keep = false;
94
+ deleted = samePath(line);
95
+ return;
96
+ }
97
+ if (line.startsWith('deleted file mode')) {
98
+ if (deleted && isTestFile(deleted)) nameStatus.push(`D\t${deleted}`);
99
+ deleted = '';
100
+ keep = false;
101
+ return;
102
+ }
103
+ if (line.startsWith('+++ ')) {
104
+ const file = line.replace(/^\+\+\+ (b\/)?/, '');
105
+ keep = file !== '/dev/null' && (isTestFile(file) || isTestConfig(file));
106
+ if (keep) kept.push(`+++ ${file}`);
107
+ return;
108
+ }
109
+ if (keep && !line.startsWith('--- ')) kept.push(line);
110
+ });
111
+ let failed = null;
112
+ child.on('error', (e) => (failed = e));
113
+ const ended = new Promise((r) => lines.on('close', r));
114
+ child.on('close', async (code) => {
115
+ await ended;
116
+ finish();
117
+ if (failed || code !== 0) reject(failed || new Error(`git log exited ${code}`));
118
+ else resolve();
119
+ });
120
+ });
121
+ }
122
+
123
+ function summary(events) {
124
+ const deletedFiles = events.filter((e) => e.kind === 'test-deleted');
125
+ const other = events.filter((e) => e.kind !== 'test-deleted').map((e) => e.why);
126
+ const parts = deletedFiles.length > 1 ? [`${deletedFiles.length} test files deleted`] : deletedFiles.map((e) => e.why);
127
+ parts.push(...other.slice(0, 3));
128
+ if (other.length > 3) parts.push(`and ${other.length - 3} more`);
129
+ return parts.join(' · ');
130
+ }
131
+
132
+ // Prints the audit; returns the exit code.
133
+ export async function audit(root, { out = console.log, err = console.error, now = Date.now() } = {}) {
134
+ if (!hasGit()) {
135
+ err('codehere audit: git was not found on PATH');
136
+ return 1;
137
+ }
138
+ if (gitLine(root, ['rev-parse', '--is-inside-work-tree']) !== 'true') {
139
+ err('codehere audit: not inside a git repository');
140
+ return 1;
141
+ }
142
+ if (gitLine(root, ['rev-parse', '--is-shallow-repository']) === 'true') {
143
+ err('codehere audit: this clone is shallow, so its history is not available › git fetch --unshallow');
144
+ return 1;
145
+ }
146
+ const since = new Date(now - DAYS * 24 * 3600 * 1000).toISOString();
147
+ let list;
148
+ try {
149
+ list = commitsSince(root, since);
150
+ if (list.length > 500) err(`codehere audit: reading ${list.length} commits`);
151
+ await scanChanges(root, since, new Map(list.map((c) => [c.sha, c])));
152
+ } catch {
153
+ err('codehere audit: git log failed, so nothing was counted');
154
+ return 1;
155
+ }
156
+ const flagged = list.filter((c) => c.events.length);
157
+ const marked = flagged.filter((c) => markersOf(c.author, c.body).length);
158
+ const n = (k, one, many) => `${k} ${k === 1 ? one : many}`;
159
+ out(`codehere audit · last ${DAYS} days · ${n(list.length, 'commit', 'commits')} read`);
160
+ if (!flagged.length) {
161
+ out('codehere › 0 commits to read: no test deleted, skipped or weakened');
162
+ return 0;
163
+ }
164
+ out(`codehere › ${n(flagged.length, 'commit', 'commits')} to read: tests deleted, skipped or weakened · ${n(marked.length, 'carries', 'carry')} an agent marker`);
165
+ out('codehere › found by pattern: a test removed with the code it tested is often fine, so read each commit');
166
+ for (const c of flagged) {
167
+ const m = markersOf(c.author, c.body);
168
+ out('');
169
+ out(` ${c.sha.slice(0, 8)} · ${c.date} · ${m.length ? m.join(', ') : 'no agent marker'} · ${printable(c.subject)}`);
170
+ out(` ${printable(summary(c.events))}`);
171
+ }
172
+ return 0;
173
+ }
package/src/brain.js CHANGED
@@ -10,6 +10,9 @@ export function findRoot(start = process.cwd()) {
10
10
  let dir = path.resolve(start);
11
11
  while (true) {
12
12
  if (fs.existsSync(path.join(dir, '.codehere'))) return dir;
13
+ // a repo's .codehere/ is at or below its git root: a .codehere/ further up (Codehere 1.x's ~/.codehere,
14
+ // another project) is not this repo's
15
+ if (fs.existsSync(path.join(dir, '.git'))) return null;
13
16
  const parent = path.dirname(dir);
14
17
  if (parent === dir) return null;
15
18
  dir = parent;
@@ -342,6 +345,16 @@ export function git(root, args, raw = false) {
342
345
  }
343
346
  }
344
347
 
348
+ // A diff can be far larger than execFileSync's 1 MiB default, and an unread diff must never look
349
+ // like an empty one: this reads it whole and returns null when git fails.
350
+ export function gitDiff(root, args) {
351
+ try {
352
+ return execFileSync('git', ['--literal-pathspecs', ...args], { cwd: root, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 512 * 1024 * 1024 }).toString();
353
+ } catch {
354
+ return null;
355
+ }
356
+ }
357
+
345
358
  // Files with uncommitted changes, relative to root, which may be a subfolder of the repo.
346
359
  export function statusFiles(root) {
347
360
  const prefix = git(root, ['rev-parse', '--show-prefix']);
@@ -389,6 +402,17 @@ export function commitId(x) {
389
402
  return typeof x === 'string' && /^[0-9a-f]{40}([0-9a-f]{24})?$/.test(x) ? x : null;
390
403
  }
391
404
 
405
+ // Whether git itself can be run. Without it every hook finds "no repository" and would stay silent, so
406
+ // init, audit and the finish check ask this first and say so.
407
+ export function hasGit() {
408
+ try {
409
+ execFileSync('git', ['--version'], { stdio: 'ignore' });
410
+ return true;
411
+ } catch {
412
+ return false;
413
+ }
414
+ }
415
+
392
416
  export function isGitRepo(root) {
393
417
  return git(root, 'rev-parse --is-inside-work-tree') === 'true';
394
418
  }
@@ -472,6 +496,60 @@ export function saveRecord(root, rec, proof = null) {
472
496
  }
473
497
  }
474
498
 
499
+ export const isMap = (x) => !!x && typeof x === 'object' && !Array.isArray(x);
500
+
501
+ // Lessons and help cards as hashes by path, for the finish check: one the agent writes itself is
502
+ // listed for the person. A link is not followed, and a linked folder is not read: it stands for
503
+ // itself, so swapping a folder for a link is a change too.
504
+ export function teamSnapshot(root) {
505
+ const snap = {};
506
+ for (const d of ['.codehere/lessons', '.codehere/help']) {
507
+ const dir = path.join(root, d);
508
+ if (!ownPath(root, dir)) {
509
+ let target = '';
510
+ try {
511
+ target = fs.readlinkSync(dir);
512
+ } catch {}
513
+ snap[d] = `link:${target}`;
514
+ continue;
515
+ }
516
+ let names = [];
517
+ try {
518
+ names = fs.readdirSync(dir);
519
+ } catch {}
520
+ for (const n of names) {
521
+ const f = path.join(dir, n);
522
+ try {
523
+ const st = fs.lstatSync(f);
524
+ const text = st.isSymbolicLink() ? `link:${fs.readlinkSync(f)}` : st.isFile() ? readPlain(f, null) : null;
525
+ if (text != null) snap[`${d}/${n}`] = crypto.createHash('sha256').update(text).digest('hex');
526
+ } catch {}
527
+ }
528
+ }
529
+ return snap;
530
+ }
531
+
532
+ // Before a save: the team files' hashes, and which files git sees as changed.
533
+ export function teamMark(root) {
534
+ return { hashes: teamSnapshot(root), dirty: new Set(statusFiles(root).map((f) => f.normalize('NFC'))) };
535
+ }
536
+
537
+ // A save Codehere made is not the agent's change: what it changed moves into the session's
538
+ // snapshot, unless that file had an uncommitted change made earlier in the session, which stays
539
+ // visible. A change that came committed (a pull) is not the agent's. True if anything moved.
540
+ export function keepSaved(s, mark, after) {
541
+ let moved = false;
542
+ if (!s || !isMap(s.team)) return moved;
543
+ const before = mark.hashes;
544
+ for (const f of new Set([...Object.keys(before), ...Object.keys(after)])) {
545
+ if (before[f] === after[f] || (s.team[f] !== before[f] && mark.dirty.has(f.normalize('NFC')))) continue;
546
+ if (after[f] === undefined) delete s.team[f];
547
+ else s.team[f] = after[f];
548
+ moved = true;
549
+ }
550
+ return moved;
551
+ }
552
+
475
553
  function save(root, rec, proof) {
476
554
  const p = paths(root);
477
555
  const rel = (f) => path.relative(root, f);
package/src/commands.js CHANGED
@@ -7,7 +7,8 @@ import {
7
7
  findRoot, paths, ensureDirs, readConfig, writeConfig, readState, writeState,
8
8
  readRules, listDocs, parseDoc, renderDoc, slug, stamp, today, git, isGitRepo, me,
9
9
  readApprovals, isApproved, addApproval, removeApprovals, markRemoved, printable, noTick, commitId,
10
- saveRecord, writeDraft, readPlain, writePlain, removePlain, ownPath,
10
+ saveRecord, writeDraft, readPlain, writePlain, removePlain, ownPath, teamSnapshot, teamMark, keepSaved,
11
+ hasGit,
11
12
  } from './brain.js';
12
13
  import { redact } from './signals.js';
13
14
  import { summarize } from './gemma.js';
@@ -232,11 +233,16 @@ const indent = (text) => text.trimEnd().split('\n').map((l) => ` ${l}`);
232
233
  // One line, built before the record, so the draft prints exactly what a yes saves.
233
234
  const oneLine = (s) => String(s).replace(/\s*[\r\n]+\s*/g, ' ');
234
235
  function saveOrExit(root, rec) {
236
+ const before = teamMark(root);
235
237
  const saved = saveRecord(root, rec);
236
238
  if (saved.error) {
237
239
  console.error(saved.error);
238
240
  process.exit(1);
239
241
  }
242
+ // typed by the person, so not the agent's change in a session that is open now
243
+ const after = teamSnapshot(root);
244
+ const state = readState(root);
245
+ if (Object.values(state.sessions || {}).filter((x) => keepSaved(x, before, after)).length) writeState(root, state);
240
246
  return saved;
241
247
  }
242
248
 
@@ -299,6 +305,10 @@ export async function init(flags) {
299
305
  console.error(`Unknown agent "${printable(flags.agent === true ? '' : flags.agent)}". Use --agent with claude, codex or copilot, or several: --agent claude,codex,copilot.`);
300
306
  process.exit(1);
301
307
  }
308
+ if (!hasGit()) {
309
+ console.error('codehere init: git was not found on PATH. Codehere reads what the agent changed through git, so nothing was set up.');
310
+ process.exit(1);
311
+ }
302
312
  const agents = [...new Set(names)].map((n) => AGENTS[n]);
303
313
  const root = process.cwd();
304
314
  // Everything init writes, checked before anything is written: a committed link anywhere on these
package/src/hooks.js CHANGED
@@ -7,11 +7,11 @@ import crypto from 'node:crypto';
7
7
  import { spawnSync } from 'node:child_process';
8
8
  import {
9
9
  findRoot, paths, readConfig, readState, writeState, session, readRules, renderDoc,
10
- listDocs, git, isGitRepo, me, isApproved, readApprovals, printable, commitId, statusFiles, gitHashes, noTick,
11
- removedAt, expireDrafts, draftFile, saveRecord, readPlain, ownPath,
10
+ listDocs, git, gitDiff, isGitRepo, hasGit, me, isApproved, readApprovals, printable, commitId, statusFiles, gitHashes, noTick,
11
+ removedAt, expireDrafts, draftFile, saveRecord, readPlain, ownPath, teamSnapshot, teamMark, keepSaved, isMap,
12
12
  } from './brain.js';
13
13
  import {
14
- responseText, signature, errorLines, similarity, tamperFindings, failingTest, lowInfoPrompt, vagueFeature, testCounts, redact, plainYes,
14
+ responseText, signature, errorLines, similarity, tamperFindings, failingTest, lowInfoPrompt, vagueFeature, testCounts, redact, plainYes, isTestFile,
15
15
  } from './signals.js';
16
16
 
17
17
  function readStdin() {
@@ -119,9 +119,13 @@ function sessionStart(root, input, agent) {
119
119
  s.startHead = git(root, 'rev-parse HEAD') || null;
120
120
  s.baseline = dirtySnapshot(root);
121
121
  s.settings = settingsSnapshot(root);
122
+ s.team = teamSnapshot(root);
123
+ s.teamHead = s.startHead;
122
124
  } else if (input.source === 'resume') {
123
125
  // While the session was closed only the developer or a pull could change settings.
124
126
  s.settings = settingsSnapshot(root);
127
+ s.team = teamSnapshot(root);
128
+ s.teamHead = git(root, 'rev-parse HEAD') || null;
125
129
  }
126
130
 
127
131
  const out = [];
@@ -262,6 +266,35 @@ function settingsSnapshot(root) {
262
266
  return snap;
263
267
  }
264
268
 
269
+ // Lessons and help cards changed since the snapshot. A file with an uncommitted change is listed.
270
+ // Otherwise it is listed only if no commit since the snapshot touched it: a pull, or the person's
271
+ // own commit, changes files through commits, while an uncommitted save undone by `git stash` or
272
+ // `git checkout`, or an untracked file deleted, leaves no commit. What Codehere saved was moved
273
+ // into the snapshot (keepSaved).
274
+ function teamChanged(root, s) {
275
+ if (!isMap(s.team)) return [];
276
+ const now = teamSnapshot(root);
277
+ const diff = [...new Set([...Object.keys(now), ...Object.keys(s.team)])].filter((f) => now[f] !== s.team[f]);
278
+ if (!diff.length) return [];
279
+ const nfc = (f) => f.normalize('NFC');
280
+ const dirty = new Set(statusFiles(root).map(nfc));
281
+ let byCommit = null;
282
+ const committed = (f) => {
283
+ if (!byCommit) {
284
+ // the commits since the snapshot, and the trees' difference (a reset or a branch switch); a
285
+ // rename counts as a removal and an addition
286
+ const from = commitId(s.teamHead === undefined ? s.startHead : s.teamHead);
287
+ const paths = ['--', '.codehere/lessons', '.codehere/help'];
288
+ const names = (out) => out.split('\0').map((x) => nfc(x.replace(/^\n+/, ''))).filter(Boolean);
289
+ const log = names(git(root, ['log', '--name-only', '--no-renames', '--relative', '-z', '--format=', from ? `${from}..HEAD` : 'HEAD', ...paths], true));
290
+ const trees = from ? names(git(root, ['diff', '--name-only', '--no-renames', '--relative', '-z', from, 'HEAD', ...paths], true)) : [];
291
+ byCommit = new Set([...log, ...trees]);
292
+ }
293
+ return byCommit.has(nfc(f));
294
+ };
295
+ return diff.filter((f) => dirty.has(nfc(f)) || !committed(f)).sort();
296
+ }
297
+
265
298
  function settingsChanged(root, s) {
266
299
  if (!s.settings) return []; // no snapshot from session start: cannot tell
267
300
  const now = settingsSnapshot(root);
@@ -677,6 +710,7 @@ function decideDrafts(root, state, s, prompt) {
677
710
  rec = JSON.parse(content);
678
711
  } catch {}
679
712
  const before = settingsSnapshot(root)[RULES];
713
+ const teamBefore = teamMark(root);
680
714
  const saved = saveRecord(root, rec, d.proof || null);
681
715
  if (saved.error) {
682
716
  notes.push(`Codehere could not save the draft: ${saved.error}`);
@@ -685,6 +719,8 @@ function decideDrafts(root, state, s, prompt) {
685
719
  }
686
720
  // a saved rule is not a settings change, unless rules.md had already changed this session
687
721
  if (rec.kind === 'rule' && s.settings && s.settings[RULES] === before) s.settings[RULES] = settingsSnapshot(root)[RULES];
722
+ const teamAfter = teamSnapshot(root);
723
+ for (const x of Object.values(state.sessions)) keepSaved(x, teamBefore, teamAfter); // every open session: the save is not its agent's either
688
724
  notes.push(`Codehere saved the draft after the user's yes: ${saved.file}${saved.lesson ? `, and the team lesson ${saved.lesson}` : ''}. Tell them it is saved. Teammates get it once the user commits and pushes it.`);
689
725
  // the agent's own words: never a tick in a codehere line (DESIGN.md §1)
690
726
  lines.push(`codehere › saved after your yes · ${rec.kind} · ${short(noTick(gist(rec)))}`);
@@ -728,6 +764,10 @@ function promptSubmit(root, input) {
728
764
  s.transcript = input.transcript_path || s.transcript;
729
765
  s.prompts = (s.prompts || 0) + 1;
730
766
  if (!s.settings) s.settings = settingsSnapshot(root); // session start did not run for this session
767
+ if (!isMap(s.team)) {
768
+ s.team = teamSnapshot(root);
769
+ s.teamHead = git(root, 'rev-parse HEAD') || null;
770
+ }
731
771
  const decided = decideDrafts(root, state, s, prompt);
732
772
 
733
773
  // Only a failure from the agent's last turn counts: an older one may be fixed or forgotten.
@@ -877,12 +917,14 @@ function stop(root, input) {
877
917
  emitJson({ systemMessage: [String(message || '').replace(/ · agent sent back · \d+ of 3/, ''), printable(why)].filter(Boolean).join('\n') });
878
918
  };
879
919
 
920
+ if (!hasGit()) emitJson({ systemMessage: 'codehere ⊘ git not found · the finish check did not run' });
880
921
  if (!isGitRepo(root)) quiet();
881
922
  const base = commitId(s.startHead) || 'HEAD';
882
923
  const changed = changedThisSession(root, s);
883
924
  const settings = settingsChanged(root, s);
884
925
  const removed = removedAt(root);
885
- if (!changed.length && !settings.length && !removed) quiet(); // the agent changed nothing this session: stay silent
926
+ const team = teamChanged(root, s);
927
+ if (!changed.length && !settings.length && !removed && !team.length) quiet(); // the agent changed nothing this session: stay silent
886
928
 
887
929
  // Lines for the developer. Each is escaped as a whole, so text from the repo cannot fake a
888
930
  // line, and text from the repo never carries a tick (noTick).
@@ -893,6 +935,7 @@ function stop(root, input) {
893
935
  if (a.at > (s.startedAt || '')) all.push(`codehere › approved on this machine during this session: ${noTick(a.command)}`);
894
936
  }
895
937
  if (settings.length) all.push(`codehere ✕ settings changed during this session · ${settings.join(' · ')}`);
938
+ if (team.length) all.push(`codehere ✕ team files changed during this session, not saved by Codehere · ${noTick(team.slice(0, 5).join(' · '))}${team.length > 5 ? ` · and ${team.length - 5} more` : ''}`);
896
939
  if (removed) all.push(removedLine(removed));
897
940
  return all.map(printable).join('\n');
898
941
  }
@@ -901,12 +944,38 @@ function stop(root, input) {
901
944
  if (m) emitJson({ systemMessage: m });
902
945
  quiet();
903
946
  }
947
+ // only lessons or help cards changed: the person gets the line, and the tests are not run
948
+ if (!changed.length && !settings.length && !removed) report();
904
949
 
905
950
  // 1. tampering with tests or checks (only in files changed this session)
906
951
  let findings = [];
952
+ let unread = false; // the session's diff could not be read, so weakened tests were not checked: never proven
907
953
  if (changed.length) {
908
954
  const nameStatus = git(root, ['diff', base, '--relative', '--name-status', '--', ...changed]);
909
- findings = tamperFindings(nameStatus, git(root, ['diff', base, '--relative', '-U0', '--', ...changed]));
955
+ const diff = gitDiff(root, ['diff', base, '--relative', '-U0', '--', ...changed]);
956
+ unread = diff === null;
957
+ // a test file as it is now, to see what a swallowing catch holds: plain files only, up to 1 MiB
958
+ const read = (f, max = 1024 * 1024) => {
959
+ try {
960
+ return readPlain(path.join(root, f), 'utf8', max);
961
+ } catch {
962
+ return null;
963
+ }
964
+ };
965
+ // the repo's test files, read only when the diff returns a literal under a condition: up to 400
966
+ // files, 256 KiB each and 4 MiB in all
967
+ const tests = () => {
968
+ const out = [];
969
+ let total = 0;
970
+ for (const f of git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], true).split('\0').filter(isTestFile).slice(0, 400)) {
971
+ const text = read(f, 256 * 1024);
972
+ if (text == null) continue;
973
+ if ((total += text.length) > 4 * 1024 * 1024) break;
974
+ out.push(`${f}\0${text}`);
975
+ }
976
+ return out;
977
+ };
978
+ findings = tamperFindings(nameStatus, diff || '', { read, tests });
910
979
  }
911
980
  const key = findings.join('|');
912
981
  if (findings.length && s.tamperReported !== key && mayBlock) {
@@ -920,7 +989,7 @@ function stop(root, input) {
920
989
  'Restore them and fix the code instead.',
921
990
  'If the change is truly intended, tell the user in one line why, then finish.',
922
991
  ].join('\n'),
923
- null,
992
+ [printable(`codehere ✕ a check was weakened · ${noTick(findings.join(' · '))} · agent sent back · ${s.stopBlocks} of 3`), message()].filter(Boolean).join('\n'),
924
993
  true
925
994
  );
926
995
  }
@@ -941,7 +1010,7 @@ function stop(root, input) {
941
1010
  'If you changed them and the user did not ask for it, undo your change.',
942
1011
  'Then tell the user in one line what changed and why, and finish.',
943
1012
  ].join('\n'),
944
- null,
1013
+ message(),
945
1014
  true
946
1015
  );
947
1016
  }
@@ -955,12 +1024,16 @@ function stop(root, input) {
955
1024
  `codehere ⊘ ${noTick(cfg.testCommand)} · not run · not approved on this machine${last ? ` · last approved: ${noTick(last.command)}` : ''} › run codehere approve in your terminal`
956
1025
  );
957
1026
  }
1027
+ if (unread && !(cfg.verifyOnStop && approved)) lines.push("codehere ✕ this session's diff could not be read · weakened tests not checked");
958
1028
  const configChanged = settings.includes('.codehere/config.json');
959
1029
  const cmd = noTick(cfg.testCommand || '');
960
1030
  let passLine = null;
961
1031
  let proven = false; // passed here, now, with intact tests and an unchanged config
962
1032
  if (cfg.verifyOnStop && approved) {
963
1033
  const t = runTests(root, cfg);
1034
+ // saves made while the tests ran moved snapshots on disk, and this hook writes the whole state back
1035
+ const disk = readState(root).sessions || {};
1036
+ for (const [k, x] of Object.entries(state.sessions)) if (isMap(disk[k]?.team)) Object.assign(x, { team: disk[k].team, teamHead: disk[k].teamHead });
964
1037
  if (!t.ok && !mayBlock) {
965
1038
  lines.push(`codehere ✕ ${cmd} · ${runResult(t)} · not sent back, limit of 3 reached`);
966
1039
  writeState(root, state);
@@ -983,9 +1056,10 @@ function stop(root, input) {
983
1056
  }
984
1057
  // ✓ only for intact evidence (DESIGN.md §1): not after a weakened test, nor after the
985
1058
  // config that names the test command changed.
986
- proven = !findings.length && !configChanged;
1059
+ proven = !findings.length && !configChanged && !unread;
987
1060
  if (findings.length) passLine = `codehere ✕ ${cmd} passed, but a check was weakened · ${noTick(findings.join(' · '))}`;
988
1061
  else if (configChanged) passLine = `codehere ✕ ${cmd} passed, but .codehere/config.json changed during this session`;
1062
+ else if (unread) passLine = `codehere ✕ ${cmd} passed, but this session's diff could not be read · weakened tests not checked`;
989
1063
  else passLine = `codehere ✓ ${cmd} · ${runResult(t)} · re-run here · ${t.seconds.toFixed(1)} s`;
990
1064
  if (proven) {
991
1065
  state.lastGreen = { commit: git(root, 'rev-parse HEAD'), at: new Date().toISOString() };