codehere 2.1.0-rc.2 → 2.1.0-rc.4

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
@@ -98,7 +98,7 @@ Don't want to commit help cards? Copy the printed text into WhatsApp, Discord or
98
98
  | Ask the agent for a team chore, saved on your yes | yes: 12 of 12 runs (rule, help card, answer a card, lesson; [result](docs/conformance/2026-11-03-claude-2.1.317-haiku-chores.md)) | partly, with a 9B local model: lesson 2 of 3, rule, help card and answer 0 of 3; the agent wrote the team files itself ([result](docs/conformance/2026-11-03-codex-0.164.0-qwen3.5-9b-q4_K_M-chores.md), [lesson](docs/conformance/2026-11-03-codex-0.164.0-qwen3.5-9b-q4_K_M-chores-L10.md)) | partly, with a 9B local model: rule and answer 3 of 3, help card and lesson 0 of 3 ([result](docs/conformance/2026-11-03-copilot-1.0.105-qwen3.5-9b-q4_K_M-chores.md)) |
99
99
  | Before it works | nothing | each developer trusts the hooks in `/hooks` | each developer trusts the folder when Copilot asks |
100
100
  | MCP tools, instruction file | no | no | no |
101
- | Tested on | 2.1.311 with haiku: [result](docs/conformance/2026-10-27-claude-2.1.311-haiku.md) | 0.164.0 with a local model (Qwen 3.5 9B through Ollama): [result](docs/conformance/2026-10-27-codex-0.164.0-qwen3.5-9b-q4-K-M.md) | 1.0.105 with a local model (Qwen 3.5 9B through Ollama): [result](docs/conformance/2026-10-29-copilot-1.0.105-qwen3.5-9b-q4-K-M.md), with only the Claude Code hooks installed: [result](docs/conformance/2026-10-29-copilot-1.0.105-qwen3.5-9b-q4-K-M-claude-hooks-only.md), and with a GitHub-hosted model (`auto`, which picked gpt-6-luna): [result](docs/conformance/2026-10-29-copilot-1.0.105-auto.md) |
101
+ | Tested on | 2.1.323 with haiku, on 2.1.0-rc.3 from npm, 3 runs: [results](docs/evidence/2026-11-14-live-claude.md) | 0.164.0 with a local model (Qwen 3.5 9B through Ollama), on 2.1.0-rc.3 from npm, 3 runs: [results](docs/evidence/2026-11-14-live-codex.md) | 1.0.105 with a local model (Qwen 3.5 9B through Ollama), on 2.1.0-rc.3 from npm, 3 runs: [results](docs/evidence/2026-11-14-live-copilot.md); on 2.0.x, with only the Claude Code hooks installed: [result](docs/conformance/2026-10-29-copilot-1.0.105-qwen3.5-9b-q4-K-M-claude-hooks-only.md), and with a GitHub-hosted model (`auto`, which picked gpt-6-luna): [result](docs/conformance/2026-10-29-copilot-1.0.105-auto.md) |
102
102
 
103
103
  The rows for rules, lessons and the finish check are checked on the real agent by `node scripts/conformance.mjs`, and the chores row by `node scripts/chores.mjs` (3 runs per chore, each in a fresh repo). The other rows are checked by `npm test` on hook inputs recorded from each agent.
104
104
 
@@ -119,10 +119,10 @@ 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 that deleted, skipped or weakened tests
122
+ codehere audit commits of the last 90 days to read: tests deleted, skipped or weakened
123
123
  ```
124
124
 
125
- `codehere audit` reads this repo's git history on your machine and sends nothing anywhere. It lists every commit that deleted a test file, skipped a test, 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:`, or the `copilot-swe-agent[bot]` author). The count is found by pattern: read each commit before drawing a conclusion. A commit with no marker may still be an agent's, since markers can be turned off.
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
126
 
127
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.
128
128
 
@@ -145,7 +145,7 @@ Everything is plain markdown, so you can read, edit, review and delete it like a
145
145
  - **No AI in the decision path.** Loops, failed tests and tampering are detected with plain rules, so Codehere doesn't inherit the agent's mistakes.
146
146
  - **It talks to the agent, not to you.** If Codehere is wrong, the agent does one extra check. You lose nothing. For team chores, you ask your agent, and it shows you a draft first.
147
147
  - **Silent on normal turns.** Your prompt gets extra context only after a failure, for a feature with no way to check it, or in a long session stuck on one error. Each at most once, under 300 tokens. After you answer a draft, you also get one line saying whether it was saved.
148
- - **It only reacts to this session's work.** Changes you had before the session are ignored. If the agent changed nothing, Codehere does nothing. A draft saved after your yes does not count as a change by the agent.
148
+ - **It only reacts to this session's work.** Changes you had before the session are ignored. If the agent changed nothing, Codehere does nothing. A session Codehere did not see start (set up mid-session) is checked at each finish and says there is no record of its test files. A draft saved after your yes does not count as a change by the agent.
149
149
  - **It never traps the agent.** At most 3 "not done yet" messages per session, then it lets go.
150
150
  - **It fails open.** If anything breaks, the hook exits quietly and the agent carries on.
151
151
  - **Small model, small job.** Gemma 4 (via Ollama) is optional and only writes summaries for briefs and help cards, which you read before using. Turn it on with `--gemma`. The text goes only to a model on this machine: Codehere refuses an `OLLAMA_HOST` on another machine and Ollama cloud models, and uses the plain text instead.
@@ -164,7 +164,8 @@ npm test # end-to-end checks
164
164
  - Claude Code, Codex CLI and Copilot CLI. OpenCode is next. Copilot in VS Code reads the same hook files but has not been checked, and Copilot's cloud agent is not supported. See [Which agents](#which-agents) for what works on each.
165
165
  - Lessons match by error text: at least 0.45 of the words in the two error lines must be shared (words in both, divided by words in either). When both the failure and the lesson name a failing test, the names must be the same, so a lesson for a failed `assert.equal` reaches only a failing test with the same name. Two tests with the same name in different files or suites still share lessons. A generic error outside a test can bring up a lesson that doesn't fit, which is why the agent gets it as reference, not as an instruction.
166
166
  - Redaction catches common keys, tokens and emails. Always read a help card before sharing it.
167
- - The "done" check needs a test command. Without one, only the tampering check runs.
167
+ - The "done" check needs a test command. Without one, only the tampering check runs. A run where the test runner reports 0 passed (every test skipped, or none found) gets no ✓; for runners whose count Codehere cannot read, the ✓ line says "exit 0" instead of a count.
168
+ - The finish check checks the work of an agent doing its task. It is not a sandbox: an agent that sets out to defeat it through git's own machinery (index flags such as assume-unchanged, replace refs, `core.bare`, moving `.git`, a test folder swapped for a link) can hide a change from it. What the ✓ promises, and what is out of scope, is in [docs/finish-check-promise.md](docs/finish-check-promise.md).
168
169
  - Approvals are per folder. Each git worktree or extra clone needs its own `codehere approve`.
169
170
  - 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.
170
171
  - 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.
@@ -186,6 +187,6 @@ npm test # end-to-end checks
186
187
  - Restart briefs are written without a yes, for your own next session. They enter git only if you commit `.codehere/briefs/`.
187
188
  - 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`.
188
189
  - Prompt checks are plain word lists (English and Indonesian). They can miss a short prompt in another language.
189
- - 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`.
190
+ - 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`.
190
191
 
191
192
  MIT licensed.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codehere",
3
- "version": "2.1.0-rc.2",
3
+ "version": "2.1.0-rc.4",
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 CHANGED
@@ -1,10 +1,10 @@
1
- // codehere audit: the commits of the last 90 days that weakened tests, each listed for a person to read.
1
+ // codehere audit: the commits of the last 90 days that deleted, skipped or weakened tests, each listed for a person to read.
2
2
  // Read-only: it runs git on this machine and sends nothing anywhere. The kinds come from the finish
3
3
  // check's own detector. A count found by pattern is a list of candidates, never proof (DESIGN.md §1).
4
4
  import { spawn, execFileSync } from 'node:child_process';
5
- import readline from 'node:readline';
6
- import { printable } from './brain.js';
7
- import { tamperEvents, isTestFile } from './signals.js';
5
+ import { printable, hasGit, gitRead, PLAIN_DIFF, GIT_ENV, GIT_TIMEOUT } from './brain.js';
6
+ import { tamperEvents, isTestFile, isTestConfig } from './signals.js';
7
+ import { unquotePath, hunkReader } from './gitpath.js';
8
8
 
9
9
  const DAYS = 90;
10
10
  const KINDS = new Set(['test-deleted', 'test-skipped', 'assertion-weakened']);
@@ -16,6 +16,8 @@ const MARKERS = [
16
16
  { re: /^Co-authored-by:[^\n]*\b(Claude|Copilot|Codex)\b/im, name: (m) => `Co-Authored-By ${m[1]}` },
17
17
  { re: /^Claude-Session:/im, name: () => 'Claude-Session' },
18
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' },
19
21
  ];
20
22
 
21
23
  export function markersOf(author, body) {
@@ -29,7 +31,7 @@ export function markersOf(author, body) {
29
31
 
30
32
  function gitLine(root, args) {
31
33
  try {
32
- return execFileSync('git', args, { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
34
+ return execFileSync('git', args, { cwd: root, stdio: ['ignore', 'pipe', 'ignore'], env: GIT_ENV, timeout: GIT_TIMEOUT }).toString().trim();
33
35
  } catch {
34
36
  return null;
35
37
  }
@@ -41,6 +43,7 @@ function commitsSince(root, since) {
41
43
  cwd: root,
42
44
  stdio: ['ignore', 'pipe', 'ignore'],
43
45
  maxBuffer: BIG,
46
+ env: GIT_ENV,
44
47
  }).toString();
45
48
  return out
46
49
  .split('\x1e')
@@ -53,63 +56,96 @@ function commitsSince(root, since) {
53
56
  }
54
57
 
55
58
  // The path in `diff --git a/P b/P` when both sides name the same file, as they do for a deletion.
59
+ // Git quotes both sides of a path it escapes: diff --git "a/caf\303\251.js" "b/caf\303\251.js".
56
60
  function samePath(line) {
61
+ const q = /^diff --git ("(?:[^"\\]|\\.)*") ("(?:[^"\\]|\\.)*")$/.exec(line);
62
+ if (q) {
63
+ const [a, b] = [unquotePath(q[1]), unquotePath(q[2])];
64
+ return a.startsWith('a/') && b === `b/${a.slice(2)}` ? a.slice(2) : '';
65
+ }
57
66
  const rest = line.slice('diff --git a/'.length);
58
67
  const half = (rest.length - ' b/'.length) / 2;
59
68
  return Number.isInteger(half) && rest.slice(half, half + 3) === ' b/' ? rest.slice(0, half) : '';
60
69
  }
61
70
 
62
- // One `git log -p`, read line by line: test-file hunks are kept, a deleted file by its name only, so
71
+ // One `git log -p`, read line by line: hunks of test files and of the files that say which tests run
72
+ // (package.json, runner configs) are kept, a deleted file by its name only, so
63
73
  // memory stays small however large a commit is. Each commit's kinds go on its entry in bySha.
64
74
  function scanChanges(root, since, bySha) {
65
75
  return new Promise((resolve, reject) => {
66
- const child = spawn('git', ['log', '--no-merges', `--since=${since}`, '-p', '--no-color', '--format=%x00%H'], {
76
+ const child = spawn('git', ['log', ...PLAIN_DIFF, '--no-merges', `--since=${since}`, '-p', '--format=%x00%H'], {
67
77
  cwd: root,
68
78
  stdio: ['ignore', 'pipe', 'ignore'],
79
+ env: GIT_ENV,
69
80
  });
70
- const lines = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
71
81
  let commit = null;
82
+ let sha = '';
83
+ let inHunk = hunkReader();
72
84
  let nameStatus = [];
73
85
  let kept = [];
74
86
  let keep = false;
75
87
  let deleted = '';
88
+ let renamedFrom = '';
76
89
  const finish = () => {
77
- if (commit) commit.events = tamperEvents(nameStatus.join('\n'), kept.join('\n')).filter((e) => KINDS.has(e.kind));
90
+ // the repo's test files before that commit, for a test renamed to another code extension
91
+ const at = sha;
92
+ const testFiles = () => (gitRead(root, ['ls-tree', '-r', '-z', '--name-only', `${at}^`]) ?? '').split('\0').filter(isTestFile);
93
+ if (commit) commit.events = tamperEvents(nameStatus.join('\n'), kept.join('\n'), { testFiles }).filter((e) => KINDS.has(e.kind));
78
94
  };
79
- lines.on('line', (line) => {
95
+ const onLine = (line) => {
80
96
  if (line.startsWith('\0')) {
81
97
  finish();
82
- commit = bySha.get(line.slice(1)) || null;
98
+ sha = line.slice(1);
99
+ commit = bySha.get(sha) || null;
100
+ inHunk = hunkReader();
83
101
  nameStatus = [];
84
102
  kept = [];
85
103
  keep = false;
86
104
  return;
87
105
  }
88
106
  if (!commit) return;
107
+ const body = inHunk(line); // in a hunk, "+++ n;" is an added "++ n;", not a file header
89
108
  if (line.startsWith('diff --git ')) {
90
109
  keep = false;
91
110
  deleted = samePath(line);
92
111
  return;
93
112
  }
113
+ if (line.startsWith('rename from ')) {
114
+ renamedFrom = unquotePath(line.slice('rename from '.length));
115
+ return;
116
+ }
117
+ if (line.startsWith('rename to ')) {
118
+ if (isTestFile(renamedFrom)) nameStatus.push(`R\t${renamedFrom}\t${unquotePath(line.slice('rename to '.length))}`);
119
+ renamedFrom = '';
120
+ return;
121
+ }
94
122
  if (line.startsWith('deleted file mode')) {
95
123
  if (deleted && isTestFile(deleted)) nameStatus.push(`D\t${deleted}`);
96
124
  deleted = '';
97
125
  keep = false;
98
126
  return;
99
127
  }
100
- if (line.startsWith('+++ ')) {
101
- const file = line.replace(/^\+\+\+ (b\/)?/, '');
102
- keep = file !== '/dev/null' && isTestFile(file);
128
+ if (!body && line.startsWith('+++ ')) {
129
+ const file = unquotePath(line.slice(4)).replace(/^b\//, '');
130
+ keep = file !== '/dev/null' && (isTestFile(file) || isTestConfig(file));
103
131
  if (keep) kept.push(`+++ ${file}`);
104
132
  return;
105
133
  }
106
- if (keep && !line.startsWith('--- ')) kept.push(line);
134
+ if (keep && (body || !line.startsWith('--- '))) kept.push(line);
135
+ };
136
+ // Lines end at \n only, as git writes them: readline also ends one at a lone \r inside a line, which puts
137
+ // the hunk reader out of step (cold review, L13 round 6).
138
+ let rest = '';
139
+ child.stdout.setEncoding('utf8');
140
+ child.stdout.on('data', (chunk) => {
141
+ const parts = (rest + chunk).split('\n');
142
+ rest = parts.pop();
143
+ parts.forEach(onLine);
107
144
  });
108
145
  let failed = null;
109
146
  child.on('error', (e) => (failed = e));
110
- const ended = new Promise((r) => lines.on('close', r));
111
- child.on('close', async (code) => {
112
- await ended;
147
+ child.on('close', (code) => {
148
+ if (rest) onLine(rest);
113
149
  finish();
114
150
  if (failed || code !== 0) reject(failed || new Error(`git log exited ${code}`));
115
151
  else resolve();
@@ -128,6 +164,10 @@ function summary(events) {
128
164
 
129
165
  // Prints the audit; returns the exit code.
130
166
  export async function audit(root, { out = console.log, err = console.error, now = Date.now() } = {}) {
167
+ if (!hasGit()) {
168
+ err('codehere audit: git was not found on PATH');
169
+ return 1;
170
+ }
131
171
  if (gitLine(root, ['rev-parse', '--is-inside-work-tree']) !== 'true') {
132
172
  err('codehere audit: not inside a git repository');
133
173
  return 1;
@@ -150,9 +190,12 @@ export async function audit(root, { out = console.log, err = console.error, now
150
190
  const marked = flagged.filter((c) => markersOf(c.author, c.body).length);
151
191
  const n = (k, one, many) => `${k} ${k === 1 ? one : many}`;
152
192
  out(`codehere audit · last ${DAYS} days · ${n(list.length, 'commit', 'commits')} read`);
153
- out(`codehere › ${n(flagged.length, 'commit', 'commits')} weakened tests · ${n(marked.length, 'carries', 'carry')} an agent marker`);
154
- if (!flagged.length) return 0;
155
- out('codehere › each was found by pattern: read the commit before drawing a conclusion');
193
+ if (!flagged.length) {
194
+ out('codehere › 0 commits to read: no test deleted, skipped or weakened');
195
+ return 0;
196
+ }
197
+ out(`codehere › ${n(flagged.length, 'commit', 'commits')} to read: tests deleted, skipped or weakened · ${n(marked.length, 'carries', 'carry')} an agent marker`);
198
+ out('codehere › found by pattern: a test removed with the code it tested is often fine, so read each commit');
156
199
  for (const c of flagged) {
157
200
  const m = markersOf(c.author, c.body);
158
201
  out('');
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;
@@ -54,6 +57,13 @@ const DEFAULT_CONFIG = {
54
57
  // final link and without blocking, checked on the open file, and read up to max bytes: a linked
55
58
  // folder can still reach a file such as /proc/self/pagemap, which says it is plain and never ends.
56
59
  // encoding null gives a Buffer.
60
+ // A teammate can commit .codehere/ or a folder in it as a link to a folder outside the repo (git keeps
61
+ // links), so a brain file is read only when no part of its path below root is a link.
62
+ export function readOwn(root, file, encoding, max) {
63
+ if (!ownPath(root, file)) throw Object.assign(new Error(`linked path: ${file}`), { code: 'ENOTPLAIN' });
64
+ return readPlain(file, encoding, max);
65
+ }
66
+
57
67
  export function readPlain(file, encoding = 'utf8', max = 8 * 1024 * 1024) {
58
68
  const notPlain = () => Object.assign(new Error(`not a plain file: ${file}`), { code: 'ENOTPLAIN' });
59
69
  let fd;
@@ -79,7 +89,7 @@ export function readPlain(file, encoding = 'utf8', max = 8 * 1024 * 1024) {
79
89
  export function readConfig(root) {
80
90
  const p = paths(root);
81
91
  try {
82
- return { ...DEFAULT_CONFIG, ...JSON.parse(readPlain(p.config)) };
92
+ return { ...DEFAULT_CONFIG, ...JSON.parse(readOwn(root, p.config)) };
83
93
  } catch {
84
94
  return { ...DEFAULT_CONFIG };
85
95
  }
@@ -93,7 +103,7 @@ export function writeConfig(root, cfg) {
93
103
 
94
104
  export function readState(root) {
95
105
  try {
96
- const state = JSON.parse(readPlain(paths(root).state));
106
+ const state = JSON.parse(readOwn(root, paths(root).state));
97
107
  // state.json can arrive through git: a file of the wrong shape counts as empty
98
108
  if (state && state.sessions && typeof state.sessions === 'object') return state;
99
109
  } catch {}
@@ -107,12 +117,27 @@ export function readState(root) {
107
117
  // made with exclusive create, so no planted link at that name is followed. Never throws: false when
108
118
  // nothing was saved, and a caller that needs the state kept (the finish check's send-back count)
109
119
  // then holds back, while what it reports still goes out.
110
- export function writeState(root, state) {
120
+ // owned: the sessions this writer changed. Every other session is taken from the file as it is now, under a lock, so
121
+ // hooks running at once (two session starts, a finish check running the tests while another session starts or stops)
122
+ // neither drop each other's sessions nor write them back stale (cold review, L13 rounds 9 and 10). The top-level
123
+ // fields are taken from the file too, except those named in fields, which this writer set (round 11). Without owned,
124
+ // the state is written as given.
125
+ export function writeState(root, state, owned, fields = ['lastSession']) {
111
126
  const p = paths(root);
112
127
  if (!ownPath(root, p.local)) return false;
113
128
  const tmp = `${p.state}.${crypto.randomBytes(6).toString('hex')}.tmp`;
129
+ let lock = null;
114
130
  try {
115
131
  fs.mkdirSync(p.local, { recursive: true });
132
+ if (owned) {
133
+ lock = takeLock(`${p.state}.lock`);
134
+ const mine = new Set(owned);
135
+ const disk = readState(root);
136
+ for (const [k, v] of Object.entries(disk)) if (k !== 'sessions' && !fields.includes(k)) state[k] = v;
137
+ const sessions = { ...disk.sessions };
138
+ for (const k of mine) if (state.sessions[k]) sessions[k] = state.sessions[k];
139
+ state.sessions = keepRecent(sessions, mine);
140
+ }
116
141
  fs.writeFileSync(tmp, JSON.stringify(state, null, 2), { flag: 'wx' });
117
142
  fs.renameSync(tmp, p.state);
118
143
  return true;
@@ -121,9 +146,41 @@ export function writeState(root, state) {
121
146
  fs.rmSync(tmp, { force: true });
122
147
  } catch {} // local/ may be a file: there is no temporary file to remove
123
148
  return false;
149
+ } finally {
150
+ if (lock) fs.rmSync(lock, { force: true });
151
+ }
152
+ }
153
+
154
+ // A lock taken with an exclusive create, waited for up to 3 s; one older than 10 s is left by a hook that died. null
155
+ // when it cannot be taken: the write goes ahead without it, as a hook must not hang.
156
+ function takeLock(file) {
157
+ const until = Date.now() + 3000;
158
+ for (;;) {
159
+ try {
160
+ fs.writeFileSync(file, String(process.pid), { flag: 'wx' });
161
+ return file;
162
+ } catch (e) {
163
+ if (e.code !== 'EEXIST') return null;
164
+ try {
165
+ if (Date.now() - fs.lstatSync(file).mtimeMs > 10000) fs.rmSync(file, { force: true });
166
+ } catch {}
167
+ if (Date.now() > until) return null;
168
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
169
+ }
124
170
  }
125
171
  }
126
172
 
173
+ // keep the state file small: drop all but the 50 sessions active most recently (a long session still in use is kept,
174
+ // though newer ones started after it: rounds 9 and 10), never one in keep
175
+ function keepRecent(sessions, keep = new Set()) {
176
+ const keys = Object.keys(sessions);
177
+ if (keys.length <= 50) return sessions;
178
+ const seen = (k) => sessions[k].lastActive || sessions[k].startedAt || '';
179
+ const drop = keys.filter((k) => !keep.has(k)).sort((a, b) => seen(a).localeCompare(seen(b))).slice(0, keys.length - 50);
180
+ for (const k of drop) delete sessions[k];
181
+ return sessions;
182
+ }
183
+
127
184
  export function session(state, id) {
128
185
  const key = id || 'default';
129
186
  if (!state.sessions[key]) {
@@ -139,14 +196,7 @@ export function session(state, id) {
139
196
  }
140
197
  state.lastSession = key;
141
198
  state.sessions[key].lastActive = new Date().toISOString();
142
- // keep the state file small: drop sessions older than the 20 most recent
143
- const keys = Object.keys(state.sessions);
144
- if (keys.length > 20) {
145
- keys
146
- .sort((a, b) => (state.sessions[a].startedAt || '').localeCompare(state.sessions[b].startedAt || ''))
147
- .slice(0, keys.length - 20)
148
- .forEach((k) => delete state.sessions[k]);
149
- }
199
+ keepRecent(state.sessions, new Set([key]));
150
200
  return state.sessions[key];
151
201
  }
152
202
 
@@ -171,7 +221,7 @@ export function renderDoc(meta, body) {
171
221
  }
172
222
 
173
223
  export function listDocs(dir) {
174
- if (!fs.existsSync(dir)) return [];
224
+ if (!fs.existsSync(dir) || !ownPath(path.dirname(path.dirname(dir)), dir)) return []; // dir is <root>/.codehere/<folder>
175
225
  return fs
176
226
  .readdirSync(dir)
177
227
  .filter((f) => f.endsWith('.md'))
@@ -213,7 +263,7 @@ export function readRules(root) {
213
263
  const file = paths(root).rules;
214
264
  let text = '';
215
265
  try {
216
- text = readPlain(file);
266
+ text = readOwn(root, file);
217
267
  } catch {
218
268
  return [];
219
269
  }
@@ -329,62 +379,126 @@ export function printable(text) {
329
379
 
330
380
  // ---------- git helpers (all fail-safe) ----------
331
381
 
332
- // Pass an array whenever an argument comes from the repo or the state file: it never
333
- // goes through a shell, so a file name such as a$(cmd).js stays a file name.
334
- // raw keeps the output as git wrote it: -z lists, and porcelain lines whose first character is a space.
335
- export function git(root, args, raw = false) {
382
+ const BIG = 512 * 1024 * 1024;
383
+
384
+ // diff and log output as plain text whatever the repo's config or attributes ask for: no color, no external
385
+ // diff program, no textconv, no "Binary files differ", and a/ b/ prefixes. The agent can change all of these
386
+ // in .git/config or .git/info/attributes (cold review, L13 round 5).
387
+ export const PLAIN_DIFF = ['--no-color', '--no-ext-diff', '--no-textconv', '--text', '--src-prefix=a/', '--dst-prefix=b/'];
388
+
389
+ // Every git call runs with these over anything the repo or the user set (cold review, L13 rounds 6 and 7): no
390
+ // fsmonitor program or repo hook, which git would run inside the hook; no replace objects, which can swap the session's
391
+ // start commit for one holding a gutted test; and blank context lines that keep their leading space. A call
392
+ // that takes longer than GIT_TIMEOUT counts as failed, so the finish check says it could not read the diff.
393
+ const extra = Number(process.env.GIT_CONFIG_COUNT) || 0;
394
+ export const GIT_ENV = {
395
+ ...process.env,
396
+ GIT_NO_REPLACE_OBJECTS: '1',
397
+ GIT_OPTIONAL_LOCKS: '0', // git status does not write the index, so no index hook has a reason to run
398
+ GIT_CONFIG_COUNT: String(extra + 4),
399
+ [`GIT_CONFIG_KEY_${extra}`]: 'core.fsmonitor',
400
+ [`GIT_CONFIG_VALUE_${extra}`]: 'false',
401
+ [`GIT_CONFIG_KEY_${extra + 1}`]: 'diff.suppressBlankEmpty',
402
+ [`GIT_CONFIG_VALUE_${extra + 1}`]: 'false',
403
+ // no hook of the repo's runs inside Codehere's git calls, such as post-index-change (round 7, finding 2)
404
+ [`GIT_CONFIG_KEY_${extra + 2}`]: 'core.hooksPath',
405
+ [`GIT_CONFIG_VALUE_${extra + 2}`]: os.devNull,
406
+ // no signature check, which would run the repo's gpg.program inside a `git log` (round 8, m4)
407
+ [`GIT_CONFIG_KEY_${extra + 3}`]: 'log.showSignature',
408
+ [`GIT_CONFIG_VALUE_${extra + 3}`]: 'false',
409
+ };
410
+ export const GIT_TIMEOUT = 30000;
411
+
412
+ // Every git call with arguments from the repo or the state file: an array never goes through a shell, so a
413
+ // file name such as a$(cmd).js stays a file name. The output is read whole, and null when git fails, so an
414
+ // unread answer never looks like an empty one.
415
+ export function gitRead(root, args, input) {
416
+ const [cmd, ...rest] = args;
336
417
  try {
337
- const opts = { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] };
338
- const out = (Array.isArray(args) ? execFileSync('git', ['--literal-pathspecs', ...args], opts) : execSync(`git ${args}`, opts)).toString();
339
- return raw ? out : out.trim();
418
+ // check-ignore takes plain paths and refuses the pathspec flag
419
+ const all = [...(cmd === 'check-ignore' ? [] : ['--literal-pathspecs']), cmd, ...(cmd === 'diff' || cmd === 'log' ? PLAIN_DIFF : []), ...rest];
420
+ return execFileSync('git', all, { cwd: root, input, stdio: [input == null ? 'ignore' : 'pipe', 'pipe', 'ignore'], maxBuffer: BIG, env: GIT_ENV, timeout: GIT_TIMEOUT }).toString();
340
421
  } catch {
341
- return '';
422
+ return null;
423
+ }
424
+ }
425
+
426
+ // gitRead with paths after "--", in batches: one argument list holds about 1 MiB on macOS, and a session can
427
+ // change tens of thousands of files (an npm install into a node_modules that is not ignored). Null when a batch fails.
428
+ export function gitPaths(root, args, paths) {
429
+ let out = '';
430
+ for (let i = 0; i < paths.length; ) {
431
+ let j = i;
432
+ for (let bytes = 0; j < paths.length && (j === i || bytes < 256 * 1024); j++) bytes += Buffer.byteLength(paths[j]) + 1;
433
+ const part = gitRead(root, [...args, '--', ...paths.slice(i, j)]);
434
+ if (part == null) return null;
435
+ out += part;
436
+ i = j;
342
437
  }
438
+ return out;
343
439
  }
344
440
 
345
- // A diff can be far larger than execFileSync's 1 MiB default, and an unread diff must never look
346
- // like an empty one: this reads it whole and returns null when git fails.
347
- export function gitDiff(root, args) {
441
+ // raw keeps the output as git wrote it: -z lists, and porcelain lines whose first character is a space.
442
+ // '' when git fails; a string is for fixed commands only.
443
+ export function git(root, args, raw = false) {
348
444
  try {
349
- return execFileSync('git', ['--literal-pathspecs', ...args], { cwd: root, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 512 * 1024 * 1024 }).toString();
445
+ const out = Array.isArray(args) ? (gitRead(root, args) ?? '') : execSync(`git ${args}`, { cwd: root, stdio: ['ignore', 'pipe', 'ignore'], env: GIT_ENV, timeout: GIT_TIMEOUT }).toString();
446
+ return raw ? out : out.trim();
350
447
  } catch {
351
- return null;
448
+ return '';
352
449
  }
353
450
  }
354
451
 
355
- // Files with uncommitted changes, relative to root, which may be a subfolder of the repo.
452
+ // Files with uncommitted changes, relative to root, which may be a subfolder of the repo. Null when git fails.
356
453
  export function statusFiles(root) {
357
454
  const prefix = git(root, ['rev-parse', '--show-prefix']);
358
- const entries = git(root, ['status', '--porcelain', '-z', '--untracked-files=all', '--', '.'], true).split('\0');
455
+ const out = gitRead(root, ['status', '--porcelain', '-z', '--untracked-files=all', '--', '.']);
456
+ if (out == null) return null;
457
+ const entries = out.split('\0');
359
458
  const files = [];
360
459
  for (let i = 0; i < entries.length; i++) {
361
460
  const e = entries[i];
362
461
  if (e.length < 4) continue;
363
462
  if (e.slice(3).startsWith(prefix)) files.push(e.slice(3 + prefix.length));
364
- if (e[0] === 'R' || e[0] === 'C') i++; // the old name of a rename or copy
463
+ if (e[0] === 'R' || e[0] === 'C') {
464
+ const old = entries[++i] || ''; // the old name of a rename or copy
465
+ if (e[0] === 'R' && old.startsWith(prefix)) files.push(old.slice(prefix.length)); // a rename changed the old path too
466
+ }
365
467
  }
366
468
  return files;
367
469
  }
368
470
 
369
- // What `git hash-object` gives for each file (git's filters applied), 'deleted' for a missing
370
- // file, null when git cannot say. One git call for all of them; absolute paths, because
471
+ // What `git hash-object` gives for each file (git's filters applied, so a lesson's hash is the same on a teammate's
472
+ // machine; filters: false for a session's own snapshot, so no filter program of the repo's runs), 'deleted' for a missing
473
+ // file, null for one git cannot say; and null for all of them when the git call fails. One git call for all of them; absolute paths, because
371
474
  // --stdin-paths ignores the subfolder git was started in.
372
- export function gitHashes(root, files) {
373
- const present = files.filter((f) => !f.includes('\n') && fs.existsSync(path.join(root, f)));
374
- let out = [];
375
- try {
376
- if (present.length) {
377
- out = execFileSync('git', ['hash-object', '--stdin-paths'], { cwd: root, input: present.map((f) => path.resolve(root, f)).join('\n') + '\n', stdio: ['pipe', 'pipe', 'ignore'] })
378
- .toString()
379
- .trim()
380
- .split('\n');
475
+ export function gitHashes(root, files, { filters = true } = {}) {
476
+ // only regular files: git status lists a dirty submodule or a nested worktree as a folder, and one folder fails
477
+ // the whole call (round 9). A folder or another kind of entry gets its kind, not a hash.
478
+ const kind = (f) => {
479
+ try {
480
+ const st = fs.lstatSync(path.join(root, f)); // a link is not followed: it counts by where it points (round 11)
481
+ return st.isSymbolicLink() ? `link:${fs.readlinkSync(path.join(root, f))}` : st.isFile() ? 'file' : st.isDirectory() ? 'folder' : 'other';
482
+ } catch {
483
+ return 'deleted';
381
484
  }
382
- } catch {}
383
- return files.map((f) => {
384
- const i = present.indexOf(f);
385
- if (i >= 0) return out[i] || null;
386
- return f.includes('\n') ? null : 'deleted';
387
- });
485
+ };
486
+ const kinds = files.map((f) => (f.includes('\n') ? null : kind(f)));
487
+ const present = files.filter((f, i) => kinds[i] === 'file');
488
+ const read = present.length ? gitRead(root, ['hash-object', ...(filters ? [] : ['--no-filters']), '--stdin-paths'], present.map((f) => path.resolve(root, f)).join('\n') + '\n') : '';
489
+ if (read == null) return null;
490
+ const out = read.trim().split('\n');
491
+ const at = new Map(present.map((f, i) => [f, i]));
492
+ // a folder (a submodule, a worktree inside the repo) by its own commit and status, so an edit inside one is seen
493
+ // (round 10); 'folder' when git cannot read it
494
+ const folder = (f) => {
495
+ const dir = path.join(root, f);
496
+ const head = gitRead(dir, ['rev-parse', 'HEAD']);
497
+ const status = gitRead(dir, ['status', '--porcelain', '-z', '--untracked-files=all']);
498
+ const diff = gitRead(dir, ['diff', 'HEAD']); // a second edit to a file already changed keeps its status line
499
+ return head == null || status == null || diff == null ? 'folder' : `folder:${crypto.createHash('sha256').update(`${head}\0${status}\0${diff}`).digest('hex')}`;
500
+ };
501
+ return files.map((f, i) => (kinds[i] === 'file' ? out[at.get(f)] || null : kinds[i] === 'folder' ? folder(f) : kinds[i]));
388
502
  }
389
503
 
390
504
  // A tick is Codehere's mark for a run it made on this machine (DESIGN.md §1). Text from the
@@ -399,6 +513,17 @@ export function commitId(x) {
399
513
  return typeof x === 'string' && /^[0-9a-f]{40}([0-9a-f]{24})?$/.test(x) ? x : null;
400
514
  }
401
515
 
516
+ // Whether git itself can be run. Without it every hook finds "no repository" and would stay silent, so
517
+ // init, audit and the finish check ask this first and say so.
518
+ export function hasGit() {
519
+ try {
520
+ execFileSync('git', ['--version'], { stdio: 'ignore' });
521
+ return true;
522
+ } catch {
523
+ return false;
524
+ }
525
+ }
526
+
402
527
  export function isGitRepo(root) {
403
528
  return git(root, 'rev-parse --is-inside-work-tree') === 'true';
404
529
  }
@@ -517,7 +642,7 @@ export function teamSnapshot(root) {
517
642
 
518
643
  // Before a save: the team files' hashes, and which files git sees as changed.
519
644
  export function teamMark(root) {
520
- return { hashes: teamSnapshot(root), dirty: new Set(statusFiles(root).map((f) => f.normalize('NFC'))) };
645
+ return { hashes: teamSnapshot(root), dirty: new Set((statusFiles(root) || []).map((f) => f.normalize('NFC'))) };
521
646
  }
522
647
 
523
648
  // A save Codehere made is not the agent's change: what it changed moves into the session's