@north-light/crouter 0.3.305 → 0.3.306

package/dist/core/__tests__/integration/git-optional-locks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/integration/git-optional-locks.test.js

@@ -0,0 +1,81 @@
+// Run with: npm run test:integration
+//
+// Regression: crouter's read-only git calls must not take `.git/index.lock`.
+//
+// `git status` refreshes the index stat cache and writes the index back, which
+// means creating `.git/index.lock` and renaming it over `.git/index`. A process
+// killed between those two steps orphans the lock, and it then blocks every
+// later writer in that checkout with no owning process left to name. Agent
+// processes are killed mid-command routinely — a closed node, a cancelled daemon
+// tick, a timed-out shell — so the residue accumulates in a shared checkout
+// until someone removes it by hand.
+//
+// `GIT_OPTIONAL_LOCKS=0` suppresses exactly that optional lock. These tests pin
+// the two paths that reach git: the shared spawner in `core/git.ts`, and the
+// bearings project-context block, which renders on every node boot and revive
+// and is therefore the most frequent git caller in the runtime.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { gitSync } from '../../git.js';
+import { buildProjectContextBlock } from '../../runtime/bearings-render.js';
+/** A repo with one committed file whose stat cache is deliberately stale, so a
+ *  status that refreshes the index has a reason to write it back. Without the
+ *  stale stat there is nothing to refresh and the assertion passes vacuously. */
+function repoWithStaleStatCache() {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-git-locks-'));
+    const git = (args) => {
+        const result = spawnSync('git', args, { cwd: dir, encoding: 'utf8' });
+        assert.equal(result.status, 0, `git ${args.join(' ')}: ${result.stderr}`);
+    };
+    writeFileSync(join(dir, 'f.txt'), 'a\n', 'utf8');
+    git(['init', '-q', '.']);
+    git(['-c', 'user.email=t@t', '-c', 'user.name=t', 'add', 'f.txt']);
+    git(['-c', 'user.email=t@t', '-c', 'user.name=t', 'commit', '-qm', 'init']);
+    // Move the file's mtime forward so git's cached stat no longer matches.
+    const future = new Date(Date.now() + 10_000);
+    utimesSync(join(dir, 'f.txt'), future, future);
+    return dir;
+}
+function indexMtime(dir) {
+    return statSync(join(dir, '.git', 'index')).mtimeMs;
+}
+test('gitSync status does not rewrite the index', (t) => {
+    if (spawnSync('git', ['--version']).status !== 0) {
+        t.skip('git is unavailable');
+        return;
+    }
+    const dir = repoWithStaleStatCache();
+    try {
+        const before = indexMtime(dir);
+        const result = gitSync(['status', '--porcelain'], dir);
+        assert.equal(result.status, 0, result.stderr);
+        // Suppressing the lock must not change what the command reports.
+        assert.equal(result.stdout, '');
+        assert.equal(indexMtime(dir), before, 'status took .git/index.lock and rewrote the index');
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('the bearings project-context block does not rewrite the index', (t) => {
+    if (spawnSync('git', ['--version']).status !== 0) {
+        t.skip('git is unavailable');
+        return;
+    }
+    const dir = repoWithStaleStatCache();
+    try {
+        const before = indexMtime(dir);
+        const block = buildProjectContextBlock(dir);
+        // The snapshot still reports real git state; it just does not lock to do it.
+        assert.match(block, /Git: /);
+        assert.match(block, /clean/);
+        assert.equal(indexMtime(dir), before, 'the bearings snapshot took .git/index.lock');
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});

package/dist/core/git.js

@@ -1,7 +1,21 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { network } from './errors.js';
+/** Git takes `.git/index.lock` to refresh the index stat cache even during
+ *  otherwise read-only commands — `status` is the common one. Killed between
+ *  creating that lock and renaming it over the index, the lock orphans and
+ *  blocks every later writer in the checkout with no owning process left to
+ *  name. Agent processes are killed mid-command routinely (a closed node, a
+ *  cancelled daemon tick, a timed-out shell), so the residue accumulates.
+ *
+ *  `GIT_OPTIONAL_LOCKS=0` suppresses exactly those optional locks and nothing
+ *  else: a commit, rebase, or `add` still takes the lock it requires, and
+ *  command output is byte-identical. Built per call rather than snapshotted at
+ *  module load, so a later change to the ambient environment still reaches git. */
+function gitEnv(base = process.env) {
+    return { ...base, GIT_OPTIONAL_LOCKS: '0' };
+}
 export function gitSync(args, cwd, input, options = {}) {
-    const res = spawnSync('git', args, { cwd, encoding: 'utf8', input, timeout: options.timeoutMs });
+    const res = spawnSync('git', args, { cwd, encoding: 'utf8', input, env: gitEnv(), timeout: options.timeoutMs });
     const status = typeof res.status === 'number' ? res.status : 1;
     const completed = typeof res.status === 'number';
     const stdout = typeof res.stdout === 'string' ? res.stdout : '';
@@ -12,7 +26,7 @@ export function gitSync(args, cwd, input, options = {}) {
 }
 export async function gitAsync(args, cwd, input, options = {}) {
     return new Promise((resolve) => {
-        const child = spawn('git', args, { cwd, ...(options.env === undefined ? {} : { env: options.env }) });
+        const child = spawn('git', args, { cwd, env: gitEnv(options.env) });
         if (input === undefined)
             child.stdin.end();
         else

package/dist/core/runtime/bearings-render.js

@@ -57,8 +57,8 @@ function directoryListingLines(cwd) {
         return ['Directory listing: unavailable (cwd missing or unreadable).'];
     }
 }
-function runCommand(cwd, cmd, args) {
-    const result = spawnSync(cmd, args, { cwd, encoding: 'utf8' });
+function runCommand(cwd, cmd, args, env) {
+    const result = spawnSync(cmd, args, { cwd, encoding: 'utf8', ...(env === undefined ? {} : { env }) });
     if (result.error !== undefined) {
         return { ok: false, stdout: '', stderr: result.error.message };
     }
@@ -68,8 +68,17 @@ function runCommand(cwd, cmd, args) {
         stderr: (result.stderr ?? '').trim(),
     };
 }
+/** This snapshot renders on every node boot and every revive, which makes it the
+ *  most frequent git caller in the runtime — and boot is exactly when a process
+ *  gets killed. `git status` would take `.git/index.lock` to refresh the stat
+ *  cache; suppressing that optional lock keeps an interrupted render from
+ *  orphaning a lock that then blocks every writer in the user's checkout.
+ *  Only optional locks are affected, and the output is unchanged. */
+function gitEnv() {
+    return { ...process.env, GIT_OPTIONAL_LOCKS: '0' };
+}
 function runGit(cwd, args) {
-    const result = runCommand(cwd, 'git', args);
+    const result = runCommand(cwd, 'git', args, gitEnv());
     return result.ok ? result.stdout : '';
 }
 function parseWorktrees(lines) {
@@ -98,7 +107,7 @@ function parseWorktrees(lines) {
  *  benign state. Every other probe here is genuinely optional and already
  *  falls back to 'unknown'/'HEAD'/a zero count on failure, which stays as-is. */
 function gitSnapshotLines(cwd) {
-    const probe = runCommand(cwd, 'git', ['rev-parse', '--is-inside-work-tree']);
+    const probe = runCommand(cwd, 'git', ['rev-parse', '--is-inside-work-tree'], gitEnv());
     if (!probe.ok) {
         if (/not a git repository/i.test(probe.stderr)) {
             return ['Git: not a git repository.'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.305",
+  "version": "0.3.306",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.305",
+  "version": "0.3.306",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.305",
+      "version": "0.3.306",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -5206,17 +5206,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/crouter-api",
-      "version": "0.3.305",
+      "version": "0.3.306",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/crouter-env-docker",
-      "version": "0.3.305",
+      "version": "0.3.306",
       "license": "UNLICENSED"
     },
     "packages/crouter-sdk": {
       "name": "@north-light/crouter-sdk",
-      "version": "0.3.305",
+      "version": "0.3.306",
       "license": "UNLICENSED",
       "dependencies": {
         "@north-light/crouter-api": "^0.3.295"