The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
refactor(gateguard): read the transcript tail through a small shared module
Jeffrey Montoyad39fcd8ac35c
diff --git a/docs/gateguard/design-notes.md b/docs/gateguard/design-notes.mdindex 3e0e14124..5809dc9aa 100644--- a/docs/gateguard/design-notes.md+++ b/docs/gateguard/design-notes.md@@ -58,6 +58,8 @@ and trivial edits) is in [change-profile.md](change-profile.md).detection and sibling-collapse eligibility. Stateless; filesystem access islimited to worktree `.git` checks, realpath/lstat of the target's parentchain, and lstat/stat of the target for its link count.+- `scripts/lib/file-tail.js`: the bounded tail read shared with the+ strategic-compact hook's `transcript-context.js`.- `scripts/lib/gateguard-turn-scan.js`: one bounded tail read of the Claude CodeJSONL transcript, walked back to the start of the current turn. Yields theturn id, the turn's completed non-error search calls (newest first), theirdiff --git a/scripts/lib/file-tail.js b/scripts/lib/file-tail.jsnew file mode 100644index 000000000..807a1a937--- /dev/null+++ b/scripts/lib/file-tail.js@@ -0,0 +1,41 @@+'use strict';++const fs = require('fs');++const DEFAULT_TRANSCRIPT_TAIL_BYTES = 256 * 1024;++/** Last `tailBytes` of a file as UTF-8 text, with whether earlier bytes were skipped; null when unreadable. */+function readFileTail(filePath, tailBytes) {+ let fd;+ try {+ fd = fs.openSync(filePath, 'r');+ } catch {+ return null;+ }++ try {+ const size = fs.fstatSync(fd).size;+ const start = Math.max(0, size - tailBytes);+ const length = size - start;+ if (length <= 0) {+ return { text: '', truncated: false };+ }++ const buffer = Buffer.alloc(length);+ const bytesRead = fs.readSync(fd, buffer, 0, length, start);+ return {+ text: buffer.toString('utf8', 0, bytesRead),+ truncated: start > 0+ };+ } catch {+ return null;+ } finally {+ try {+ fs.closeSync(fd);+ } catch {+ /* ignore */+ }+ }+}++module.exports = { DEFAULT_TRANSCRIPT_TAIL_BYTES, readFileTail };diff --git a/scripts/lib/gateguard-turn-scan.js b/scripts/lib/gateguard-turn-scan.jsindex 687623763..26cf20041 100644--- a/scripts/lib/gateguard-turn-scan.js+++ b/scripts/lib/gateguard-turn-scan.js@@ -3,7 +3,7 @@const crypto = require('crypto');const fs = require('fs');const path = require('path');-const { readFileTail, DEFAULT_TRANSCRIPT_TAIL_BYTES } = require('./transcript-context');+const { readFileTail, DEFAULT_TRANSCRIPT_TAIL_BYTES } = require('./file-tail');const TRANSCRIPT_SCAN_MAX_LINES = 2000;// see docs/gateguard/design-notes.md#read-is-not-evidencediff --git a/scripts/lib/transcript-context.js b/scripts/lib/transcript-context.jsindex b6665a986..87c6bb2d4 100644--- a/scripts/lib/transcript-context.js+++ b/scripts/lib/transcript-context.js@@ -17,14 +17,13 @@* keeping the PreToolUse hook fast even for very large sessions.*/-const fs = require('fs');+const { readFileTail, DEFAULT_TRANSCRIPT_TAIL_BYTES } = require('./file-tail');const STANDARD_CONTEXT_WINDOW_TOKENS = 200000;const LARGE_CONTEXT_WINDOW_TOKENS = 1000000;const DEFAULT_CONTEXT_THRESHOLD_STANDARD = 160000;const DEFAULT_CONTEXT_THRESHOLD_LARGE = 250000;const DEFAULT_CONTEXT_INTERVAL_TOKENS = 60000;-const DEFAULT_TRANSCRIPT_TAIL_BYTES = 256 * 1024;const MAX_TOKEN_SETTING = 10000000;const LARGE_WINDOW_MODEL_MARKER = '[1m]';@@ -59,38 +58,6 @@ function isKnownModelFamilyMatch(model, familyId) {* Read the trailing `tailBytes` of a file as UTF-8.* Returns null when the file is missing or unreadable.*/-function readFileTail(filePath, tailBytes) {- let fd;- try {- fd = fs.openSync(filePath, 'r');- } catch {- return null;- }-- try {- const size = fs.fstatSync(fd).size;- const start = Math.max(0, size - tailBytes);- const length = size - start;- if (length <= 0) {- return { text: '', truncated: false };- }-- const buffer = Buffer.alloc(length);- const bytesRead = fs.readSync(fd, buffer, 0, length, start);- return {- text: buffer.toString('utf8', 0, bytesRead),- truncated: start > 0- };- } catch {- return null;- } finally {- try {- fs.closeSync(fd);- } catch {- /* ignore */- }- }-}/*** Extract the context token total from a transcript record's usage block.diff --git a/tests/hooks/gateguard-fact-force.test.js b/tests/hooks/gateguard-fact-force.test.jsindex b77ca8dcf..e0b794300 100644--- a/tests/hooks/gateguard-fact-force.test.js+++ b/tests/hooks/gateguard-fact-force.test.js@@ -7394,7 +7394,7 @@ function runTests() {'const hook = require(process.argv[1]);','hook.run(process.argv[2]);',"const names = Object.keys(require.cache).map(f => require('path').basename(f, '.js'));",- "const libs = names.filter(n => /^(gateguard-|transcript-context$)/.test(n) && !/^gateguard-(fact-force|heredoc)$/.test(n));",+ "const libs = names.filter(n => /^(gateguard-|transcript-context$|file-tail$)/.test(n) && !/^gateguard-(fact-force|heredoc)$/.test(n));",'process.stdout.write(JSON.stringify(libs.sort()));'].join('\n');try {@@ -7411,7 +7411,7 @@ function runTests() {['a first shell command loads only the read-only check', lazyBash('npm test'), [], ['gateguard-readonly-shell', 'gateguard-state']],['a shell command after the routine gate loads only the state helpers', lazyBash('npm run build'), [lazyBash('npm test')], ['gateguard-state']],['an edit of a checked file loads only the target classification', lazyEdit, [lazyEdit], ['gateguard-state', 'gateguard-target-class']],- ['a first touch without a transcript loads no search matching', lazyEdit, [], ['gateguard-change-profile', 'gateguard-code-lexer', 'gateguard-file-context', 'gateguard-state', 'gateguard-target-class', 'gateguard-turn-scan', 'transcript-context']]+ ['a first touch without a transcript loads no search matching', lazyEdit, [], ['file-tail', 'gateguard-change-profile', 'gateguard-code-lexer', 'gateguard-file-context', 'gateguard-state', 'gateguard-target-class', 'gateguard-turn-scan']]];for (const [label, payload, setup, expected] of lazyCases) {if (test(`lazy loading: ${label}`, () => assert.deepStrictEqual(loadedLibs(payload, setup), expected))) passed++;diff --git a/tests/lib/file-tail.test.js b/tests/lib/file-tail.test.jsnew file mode 100644index 000000000..c5aa68a7c--- /dev/null+++ b/tests/lib/file-tail.test.js@@ -0,0 +1,65 @@+'use strict';+/**+ * Tests for scripts/lib/file-tail.js.+ *+ * Run with: node tests/lib/file-tail.test.js+ */++const assert = require('assert');+const fs = require('fs');+const os = require('os');+const path = require('path');++const { readFileTail, DEFAULT_TRANSCRIPT_TAIL_BYTES } = require(path.join(__dirname, '..', '..', 'scripts', 'lib', 'file-tail.js'));++console.log('=== Testing file-tail.js ===\n');++let passed = 0;+let failed = 0;++function test(desc, fn) {+ try {+ fn();+ console.log(` ✓ ${desc}`);+ passed++;+ } catch (e) {+ console.log(` ✗ ${desc}: ${e.message}`);+ failed++;+ }+}++const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'file-tail-'));+const file = path.join(dir, 'f.txt');+fs.writeFileSync(file, 'abcdef');++test('the default tail is 256 KiB', () => {+ assert.strictEqual(DEFAULT_TRANSCRIPT_TAIL_BYTES, 256 * 1024);+});++test('a file smaller than the tail is read whole', () => {+ assert.deepStrictEqual(readFileTail(file, 1024), { text: 'abcdef', truncated: false });+});++test('a larger file is cut to its last bytes and marked truncated', () => {+ assert.deepStrictEqual(readFileTail(file, 2), { text: 'ef', truncated: true });+});++test('an empty file gives empty text', () => {+ const empty = path.join(dir, 'empty.txt');+ fs.writeFileSync(empty, '');+ assert.deepStrictEqual(readFileTail(empty, 10), { text: '', truncated: false });+});++test('a missing file gives null', () => {+ assert.strictEqual(readFileTail(path.join(dir, 'missing.txt'), 10), null);+});++test('transcript-context still exports the same reader', () => {+ const context = require(path.join(__dirname, '..', '..', 'scripts', 'lib', 'transcript-context.js'));+ assert.strictEqual(context.readFileTail, readFileTail);+ assert.strictEqual(context.DEFAULT_TRANSCRIPT_TAIL_BYTES, DEFAULT_TRANSCRIPT_TAIL_BYTES);+});++fs.rmSync(dir, { recursive: true, force: true });+console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);+process.exit(failed > 0 ? 1 : 0);