Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* The one way the skills code writes under `~/.trail`: files 0600 (a copied
* helper script 0700), folders 0700, whole files by temp file and rename,
* log lines by one O_APPEND write, and a lock that gives up.
*
* The lock gives up rather than waits forever or barges in: a hook that can't
* get it in time does nothing, because a fold that ran twice would count
* every call twice, and a lost update is better than a double one. A lock
* older than 10 s belongs to a process that died, so it is taken over, by one
* process at a time (a second lock, held for microseconds, guards the
* takeover), and a holder only ever removes its own lock.
*
* Nothing here writes through a symlink: an append refuses one, and a whole
* file replaces the link itself, never what it points to.
*/
import {
closeSync, constants, fchmodSync, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmdirSync, rmSync, unlinkSync, writeSync, type Stats,
} from 'node:fs';
import { dirname, join } from 'node:path';
import { trailHome } from '../notes/trail-home.js';
import { ensurePrivateDir } from '../trace/state.js';
export { ensurePrivateDir, writePrivateJson } from '../trace/state.js';
const POSIX = process.platform !== 'win32';
/** One append is one write: a line this long or longer is refused. */
const MAX_LINE_BYTES = 4096;
const LOCK_POLL_MS = 10;
const LOCK_STALE_MS = 10_000;
/** A takeover takes microseconds; a takeover lock this old belongs to a process that died mid-way. */
const STEAL_STALE_MS = 2_000;
/** O_APPEND that refuses a symlink (ELOOP) where the platform has O_NOFOLLOW. */
/** O_NONBLOCK: a FIFO planted at the path can't hold the open (D100 18); the fstat below then refuses it. */
const APPEND_FLAGS = constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
function writeAll(fd: number, text: string): void {
const buf = Buffer.from(text, 'utf8');
for (let off = 0; off < buf.length; ) off += writeSync(fd, buf, off, buf.length - off);
}
/** tmp file + rename; mode 0o600 unless given (0o700 for a copied helper script). */
export function writePrivate(path: string, data: string, mode = 0o600): void {
ensurePrivateDir(dirname(path));
const tmp = `${path}.${process.pid}.${Math.random().toString(16).slice(2, 8)}.tmp`;
try {
const fd = openSync(tmp, 'wx', mode);
try {
if (POSIX) fchmodSync(fd, mode);
writeAll(fd, data);
} finally {
closeSync(fd);
}
renameSync(tmp, path);
} catch (e) {
try { rmSync(tmp, { force: true }); } catch { /* nothing more to do */ }
throw e;
}
}
/**
* O_APPEND, 0600, adds '\n'. Throws on a line of 4 KB or more, so one append stays one write. Throws on a symlink,
* and on anything that isn't a regular file (a FIFO, a device) without blocking or writing to it.
*/
export function appendPrivateLine(path: string, line: string): void {
if (/[\r\n]/.test(line)) throw new Error('appendPrivateLine takes one line: it holds a line break');
if (Buffer.byteLength(line, 'utf8') >= MAX_LINE_BYTES) throw new Error('appendPrivateLine: a line of 4 KB or more is refused');
ensurePrivateDir(dirname(path));
const fd = openSync(path, APPEND_FLAGS, 0o600);
try {
if (!fstatSync(fd).isFile()) throw new Error('appendPrivateLine: not a regular file');
if (POSIX) fchmodSync(fd, 0o600);
writeAll(fd, `${line}\n`);
} finally {
closeSync(fd);
}
}
/** null on a missing file or bad JSON. */
export function readJsonSafe<T>(path: string): T | null {
try {
return JSON.parse(readFileSync(path, 'utf8')) as T;
} catch {
return null;
}
}
export type Locked<T> = { ok: true; value: T } | { ok: false };
const SLEEP_CELL = typeof SharedArrayBuffer === 'function' ? new Int32Array(new SharedArrayBuffer(4)) : null;
function pause(ms: number): void {
if (SLEEP_CELL) Atomics.wait(SLEEP_CELL, 0, 0, ms);
else {
const until = Date.now() + ms;
while (Date.now() < until) { /* spin: no SharedArrayBuffer here */ }
}
}
const lstatOrNull = (p: string): Stats | null => {
try {
return lstatSync(p);
} catch {
return null;
}
};
const sameFile = (a: Stats, b: Stats) => a.ino === b.ino && a.dev === b.dev;
const readOrNull = (p: string) => {
try {
return readFileSync(p, 'utf8');
} catch {
return null;
}
};
const aside = (p: string) => `${p}.${process.pid}.${Math.random().toString(16).slice(2, 8)}.stale`;
/** A file, a link or an empty folder; never a folder's contents. */
const removeAny = (p: string) => {
try {
unlinkSync(p);
} catch {
try { rmdirSync(p); } catch { /* left as it is, under a name nobody locks */ }
}
};
/**
* Take `<lock>` over if it is older than 10 s. True when it is gone (taken over, or released) and a retry
* may win. Under `<lock>.steal` (open wx), so two processes that both saw the old lock can't both take
* it: the second one would move aside the first one's new lock. The lock is moved aside and checked to
* be the old one; a fresh one moved by mistake is linked back.
*/
function stealStale(lock: string): boolean {
const seen = lstatOrNull(lock);
if (!seen) return true; // released between our open and our look
if (Date.now() - seen.mtimeMs <= LOCK_STALE_MS) return false;
const guard = `${lock}.steal`;
let fd: number;
try {
fd = openSync(guard, 'wx', 0o600);
} catch {
const g = lstatOrNull(guard);
if (g && Date.now() - g.mtimeMs > STEAL_STALE_MS) {
const moved = aside(guard);
try { renameSync(guard, moved); removeAny(moved); } catch { /* another process cleared it */ }
}
return false;
}
closeSync(fd);
try {
const now = lstatOrNull(lock);
if (!now) return true;
if (!sameFile(now, seen) || Date.now() - now.mtimeMs <= LOCK_STALE_MS) return false;
const moved = aside(lock);
try {
renameSync(lock, moved);
} catch {
return true;
}
const was = lstatOrNull(moved);
if (was && (!sameFile(was, seen) || Date.now() - was.mtimeMs <= LOCK_STALE_MS)) {
// A fresh lock replaced the old one after our look: put it back, unless someone holds the path again.
try { linkSync(moved, lock); } catch { /* the path is taken: that holder goes on */ }
removeAny(moved);
return false;
}
removeAny(moved);
return true;
} finally {
try { unlinkSync(guard); } catch { /* gone already */ }
}
}
/**
* Lock `<path>.lock` (open with wx). Polls every 10 ms up to waitMs (default 200). Steals a lock
* older than 10 s. On timeout returns { ok: false } and does NOT run fn: a fold that ran twice
* would count every call twice, and a lost update is better than a double one.
*/
export function withLock<T>(path: string, fn: () => T, waitMs = 200): Locked<T> {
const lock = `${path}.lock`;
mkdirSync(dirname(lock), { recursive: true, mode: 0o700 });
const deadline = Date.now() + Math.max(0, waitMs);
let fd = -1;
for (;;) {
try {
fd = openSync(lock, 'wx', 0o600);
break;
} catch (e) {
if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e;
}
// The deadline is checked on every turn: a lock that can't be taken over (a dangling symlink, a
// folder we can't move) must not spin forever.
const gone = stealStale(lock);
if (Date.now() >= deadline) return { ok: false };
if (!gone) pause(Math.min(LOCK_POLL_MS, Math.max(1, deadline - Date.now())));
}
let mine: Stats | null = null;
// The pid, and a nonce: Linux hands a freed inode to the next file at once, so a lock that was taken over
// can have our inode number; its text tells it apart.
const token = `${process.pid} ${Math.random().toString(16).slice(2, 10)}`;
let wrote = false;
try {
try { mine = fstatSync(fd); } catch { /* checked below */ }
try { writeAll(fd, token); wrote = true; } catch { /* the lock is the file, not its text */ }
closeSync(fd);
return { ok: true, value: fn() };
} finally {
// Only our own lock: if fn ran past 10 s and another process took over, the path is theirs now.
const now = lstatOrNull(lock);
if (now && mine && sameFile(now, mine) && (!wrote || readOrNull(lock) === token)) {
try { unlinkSync(lock); } catch { /* already gone */ }
}
}
}
/** join(trailHome(env), ...parts). */
export function trailPath(env: NodeJS.ProcessEnv | undefined, ...parts: string[]): string {
return join(trailHome(env ?? process.env), ...parts);
}