windows-development-sandbox 1.11.7 → 1.12.0

package/dist/host/audit/collect.d.ts

@@ -5,29 +5,55 @@ declare const AuditSettingsSchema: z.ZodObject<{
     maxMb: z.ZodNumber;
     processes: z.ZodBoolean;
     files: z.ZodBoolean;
+    commits: z.ZodDefault<z.ZodBoolean>;
     projects: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 export type AuditSettings = z.output<typeof AuditSettingsSchema>;
 /** Host-only: the audit settings of the running sandbox (written at launch, read by the watcher). */
 export declare function saveAuditSettings(storageRoot: string, dataPath: string, settings: AuditSettings): void;
 export declare function readAuditSettings(storageRoot: string, dataPath: string): AuditSettings | null;
+/** A project of the running sandbox: its name (as sessions name it) and its folder on this PC. */
+export interface AuditProject {
+    readonly name: string;
+    readonly host: string;
+}
 export declare class AuditCollector {
     private readonly dataPath;
     private readonly settings;
+    private readonly projects;
     private readonly log;
     private pending;
     private sessions;
+    private readonly book;
+    private gitRuns;
+    private held;
+    private readonly commitWatcher;
+    private readonly watched;
     private watchers;
-    constructor(dataPath: string, storageRoot: string, settings: AuditSettings);
+    private maintainedOn;
+    constructor(dataPath: string, storageRoot: string, settings: AuditSettings, projects?: () => readonly AuditProject[]);
     private add;
-    /** Starts watching the projects' files (when audit.files). */
+    /** Deletes old days, then starts watching the projects' files and commits. */
     start(): void;
+    /** The projects not watched yet (one that joined the sandbox since): their files and their reflogs from now on. */
+    private watchProjects;
+    private watchFiles;
+    private linked;
     /** Programs the sandbox reported: taken in (checked) and deleted. */
     private takeGuestReports;
+    /** One line the sandbox wrote: only a program, with only the fields it may set. */
+    private takeLine;
+    private primaryProject;
     private trackSessions;
+    /** New commits are held a moment; held ones whose time has come are written, linked to a session if one is known. */
+    private takeCommits;
+    /** File changes not linked yet: to the one session running in their project then, if there was exactly one. */
+    private linkFiles;
     guard(detail: string): void;
+    /** Old days go when the watcher starts and again whenever the day changes while it runs. */
+    private maintainDaily;
     /** Writes what came in since the last call (repeats folded); call every few seconds. */
-    flush(): void;
+    flush(final?: boolean): void;
     stop(): void;
     maintain(): void;
 }

package/dist/host/audit/collect.js

@@ -1,26 +1,68 @@
 // What goes into the audit log, from the background watcher while the sandbox runs:
 //  - programs started in the sandbox: the .jsonl files it leaves in run\audit\ (untrusted: links refused, each file
-//    and line size-capped, every line checked and forced to kind "proc"), taken in and deleted;
+//    and line size-capped, every line checked and forced to kind "proc", times kept to now, command lines scrubbed of
+//    secrets, a session it names kept only when this sandbox has that session), taken in and deleted;
 //  - files changed in the projects: watched from this PC (the sandbox cannot hide or fake these);
+//  - git commits in the projects: read from each project's reflog on this PC (git-commits.ts);
 //  - sessions starting and ending, and what the repo guard caught.
+// Each event is linked to the agent session that did it where that can be known (attribute.ts), else to none.
 import fs from 'node:fs';
 import path from 'node:path';
 import { z } from 'zod';
 import { assertNoLinks } from '../../core/util/index.js';
 import { RunDir } from '../../shared/channel/index.js';
 import { JsonFile } from '../../shared/io/index.js';
+import { hubName } from '../../shared/paths/index.js';
+// The file itself, not the barrel: the barrel leads back to the watcher, which imports this file.
+import { ProjectRegistry } from '../projects/registry.js';
 import { hostStateFile } from '../storage/index.js';
-import { AuditEventSchema, AuditLog, fold } from './log.js';
+import { makesCommits, SessionBook } from './attribute.js';
+import { CommitWatcher } from './git-commits.js';
+import { AuditEventSchema, AuditLog, AuditSessionIdSchema, fold } from './log.js';
+import { redactCommandLine } from './redact.js';
 const MAX_FILES_PER_PASS = 200;
 const MAX_FILE_BYTES = 8 * 1024 * 1024;
+/** Most of the sandbox's reports taken in per pass, all files together. */
+const MAX_BYTES_PER_PASS = 16 * 1024 * 1024;
+/** Commits waiting to be written, and git commands remembered for linking them, at most. */
+const MAX_HELD_COMMITS = 500;
+const MAX_GIT_RUNS = 2000;
+/** A plain file's text (null when it is not a plain file or is bigger than `max`), checked on the open handle. */
+function readPlainFile(file, max) {
+    if (!fs.lstatSync(file).isFile())
+        return null;
+    const fd = fs.openSync(file, 'r');
+    try {
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.size > max)
+            return null;
+        const buffer = Buffer.alloc(stat.size);
+        const read = fs.readSync(fd, buffer, 0, stat.size, 0);
+        return buffer.subarray(0, read).toString('utf8');
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 /** Paths in a project not worth a line each (git's own bookkeeping, dependency folders). */
 const QUIET = /(^|[\\/])(\.git[\\/](objects|logs|refs|index\.lock|FETCH_HEAD|ORIG_HEAD)|node_modules[\\/]|target[\\/]|\.venv[\\/]|__pycache__[\\/])/i;
+/** A commit waits this long before it is written, so the git command that made it (reported later) can claim it. */
+const COMMIT_HOLD_MS = 45 * 1000;
+/** Git commands are remembered this long for linking commits. */
+const GIT_RUNS_KEPT_MS = 10 * 60 * 1000;
+/** A time the sandbox reports is believed only this far from now (else it is now). */
+const PAST_MS = 2 * 86400000;
+const FUTURE_MS = 3600000;
+/** Projects watched at most (the running sandbox's registry can grow while it runs). */
+const MAX_PROJECTS = 64;
 const AuditSettingsSchema = z.object({
     enabled: z.boolean(),
     days: z.number().int().min(1).max(365),
     maxMb: z.number().int().min(5).max(5000),
     processes: z.boolean(),
     files: z.boolean(),
+    /** Missing in files written by versions before commits were recorded. */
+    commits: z.boolean().default(true),
     projects: z.array(z.string().max(1024)).max(64),
 });
 const settingsFile = (storageRoot, dataPath) => new JsonFile(AuditSettingsSchema, hostStateFile(storageRoot, dataPath, '-audit.json'));
@@ -31,51 +73,109 @@ export function saveAuditSettings(storageRoot, dataPath, settings) {
 export function readAuditSettings(storageRoot, dataPath) {
     return settingsFile(storageRoot, dataPath).read();
 }
+/** The sandbox's projects: the registry's (projects that joined while it runs too) and the ones it started with. */
+function registryProjects(storageRoot, started) {
+    const out = [];
+    const add = (name, host) => {
+        if (!out.some((p) => p.host.toLowerCase() === host.toLowerCase()))
+            out.push({ name, host });
+    };
+    try {
+        for (const p of new ProjectRegistry(storageRoot).read()?.projects ?? [])
+            add(p.name, p.host);
+    }
+    catch {
+        // No registry (or an unreadable one): the projects it started with.
+    }
+    for (const host of started)
+        add(hubName(host, []), host);
+    return out.slice(0, MAX_PROJECTS);
+}
+/** A time from the sandbox as an ISO time near now: one too far off (a wrong clock, a made-up line) becomes now. */
+function believable(t, now) {
+    const ms = Date.parse(t);
+    return Number.isNaN(ms) || ms < now - PAST_MS || ms > now + FUTURE_MS
+        ? new Date(now).toISOString()
+        : new Date(ms).toISOString();
+}
 export class AuditCollector {
     dataPath;
     settings;
+    projects;
     log;
     pending = [];
     sessions = new Map();
+    book = new SessionBook();
+    gitRuns = [];
+    held = [];
+    commitWatcher = new CommitWatcher();
+    watched = new Set();
     watchers = [];
-    constructor(dataPath, storageRoot, settings) {
+    maintainedOn = '';
+    constructor(dataPath, storageRoot, settings, projects = () => registryProjects(storageRoot, settings.projects)) {
         this.dataPath = dataPath;
         this.settings = settings;
+        this.projects = projects;
         this.log = new AuditLog(AuditLog.dirFor(storageRoot, dataPath), settings);
     }
     add(e) {
         this.pending.push({ t: new Date().toISOString(), ...e });
     }
-    /** Starts watching the projects' files (when audit.files). */
+    /** Deletes old days, then starts watching the projects' files and commits. */
     start() {
+        this.maintainDaily();
         this.add({
             k: 'note',
             p: 'sandbox started; audit: ' +
-                [this.settings.processes && 'programs', this.settings.files && 'files', 'sessions'].filter(Boolean).join(', '),
+                [
+                    this.settings.processes && 'programs',
+                    this.settings.files && 'files',
+                    this.settings.commits && 'commits',
+                    'sessions',
+                ]
+                    .filter(Boolean)
+                    .join(', '),
         });
-        if (!this.settings.files)
-            return;
-        for (const project of this.settings.projects) {
-            try {
-                this.watchers.push(fs.watch(project, { recursive: true }, (event, file) => {
-                    const rel = file ? String(file) : '';
-                    if (!rel || QUIET.test(rel))
-                        return;
-                    this.add({
-                        k: 'file',
-                        a: event === 'rename' ? 'rename' : 'change',
-                        p: rel.replace(/\\/g, '/').slice(0, 1024),
-                        w: project,
-                    });
-                }));
-            }
-            catch {
-                /* a project that is gone */
-            }
+        this.watchProjects();
+    }
+    /** The projects not watched yet (one that joined the sandbox since): their files and their reflogs from now on. */
+    watchProjects() {
+        for (const project of this.projects()) {
+            const key = project.host.toLowerCase();
+            if (this.watched.has(key))
+                continue;
+            this.watched.add(key);
+            if (this.settings.commits)
+                this.commitWatcher.prime([project.host]);
+            if (this.settings.files)
+                this.watchFiles(project);
+        }
+    }
+    watchFiles(project) {
+        try {
+            this.watchers.push(fs.watch(project.host, { recursive: true }, (event, file) => {
+                const rel = file ? String(file) : '';
+                if (!rel || QUIET.test(rel))
+                    return;
+                this.add({
+                    k: 'file',
+                    a: event === 'rename' ? 'rename' : 'change',
+                    p: rel.replace(/\\/g, '/').slice(0, 1024),
+                    w: project.host,
+                    pj: project.name,
+                });
+            }));
         }
+        catch {
+            /* a project that is gone */
+        }
+    }
+    linked(link) {
+        const s = this.book.get(link?.s);
+        return link && s ? { s: s.id, ag: s.agent, pj: s.project, sv: link.sv } : {};
     }
     /** Programs the sandbox reported: taken in (checked) and deleted. */
-    takeGuestReports() {
+    takeGuestReports(now) {
         if (!this.settings.processes)
             return;
         const dir = new RunDir(this.dataPath).auditDir;
@@ -91,38 +191,80 @@ export class AuditCollector {
         catch {
             return;
         }
+        // A budget for the whole pass: what is over it waits (the next pass takes the next files).
+        let budget = MAX_BYTES_PER_PASS;
         for (const name of names) {
             const file = path.join(dir, name);
             try {
-                const stat = fs.lstatSync(file);
-                if (stat.isFile() && stat.size <= MAX_FILE_BYTES) {
-                    for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
-                        if (!line.trim() || line.length > 8192)
-                            continue;
-                        let raw;
-                        try {
-                            raw = JSON.parse(line);
-                        }
-                        catch {
-                            continue;
-                        }
-                        const e = AuditEventSchema.safeParse(raw);
-                        if (e.success)
-                            this.pending.push({ ...e.data, k: 'proc', w: undefined, a: undefined });
-                    }
+                const size = fs.lstatSync(file).size;
+                if (size <= MAX_FILE_BYTES && size > budget)
+                    break;
+            }
+            catch {
+                continue;
+            }
+            try {
+                const text = readPlainFile(file, MAX_FILE_BYTES);
+                if (text !== null) {
+                    budget -= text.length;
+                    for (const line of text.split('\n'))
+                        this.takeLine(line, now);
                 }
             }
+            catch {
+                /* unreadable: deleted below like any other */
+            }
             finally {
-                fs.rmSync(file, { force: true });
+                try {
+                    fs.rmSync(file, { force: true, recursive: true });
+                }
+                catch {
+                    // Cannot be removed (held open): the next pass tries again.
+                }
             }
         }
     }
-    trackSessions() {
-        const now = new Map(new RunDir(this.dataPath).listSessions().map((s) => [s.id, s.phase]));
-        for (const s of new RunDir(this.dataPath).listSessions()) {
+    /** One line the sandbox wrote: only a program, with only the fields it may set. */
+    takeLine(line, now) {
+        if (!line.trim() || line.length > 8192)
+            return;
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const e = AuditEventSchema.safeParse(raw);
+        if (!e.success)
+            return;
+        const { t, p, c, pp } = e.data;
+        const claimed = AuditSessionIdSchema.safeParse(e.data.s);
+        const session = claimed.success ? this.book.get(claimed.data) : undefined;
+        const event = {
+            t: believable(t, now),
+            k: 'proc',
+            ...(p !== undefined ? { p } : {}),
+            ...(c !== undefined ? { c: redactCommandLine(c) } : {}),
+            ...(pp !== undefined ? { pp } : {}),
+            ...(session ? this.linked({ s: session.id, sv: 'p' }) : {}),
+        };
+        if (session && makesCommits(p ?? '', c ?? '') && this.gitRuns.length < MAX_GIT_RUNS)
+            this.gitRuns.push({ t: Date.parse(event.t), session: session.id });
+        this.pending.push(event);
+    }
+    primaryProject() {
+        return this.projects()[0]?.name ?? 'project';
+    }
+    trackSessions(now) {
+        const list = new RunDir(this.dataPath).listSessions();
+        this.book.update(list, this.primaryProject(), now);
+        const phases = new Map(list.map((s) => [s.id, s.phase]));
+        for (const s of list) {
             const before = this.sessions.get(s.id);
+            const who = this.linked({ s: s.id, sv: 'p' });
             if (!before && s.phase === 'running')
-                this.add({ k: 'session', a: 'start', p: s.harness, w: s.cwd, c: s.id });
+                this.add({ k: 'session', a: 'start', p: s.harness, w: s.cwd, c: s.id, ...who, sv: undefined });
             if (before === 'running' && (s.phase === 'exited' || s.phase === 'failed'))
                 this.add({
                     k: 'session',
@@ -130,35 +272,88 @@ export class AuditCollector {
                     p: s.harness,
                     w: s.cwd,
                     c: s.id + (s.exitCode !== undefined ? ' exit ' + s.exitCode : ''),
+                    ...who,
+                    sv: undefined,
                 });
         }
-        this.sessions = now;
+        this.sessions = phases;
+    }
+    /** New commits are held a moment; held ones whose time has come are written, linked to a session if one is known. */
+    takeCommits(now, final) {
+        if (!this.settings.commits)
+            return;
+        const projects = this.projects();
+        // Commits are never folded, so their number is capped here (a reflog full of made-up lines cannot flood the log).
+        const fresh = this.commitWatcher.commits(projects.map((p) => p.host));
+        const room = Math.max(0, MAX_HELD_COMMITS - this.held.length);
+        for (const commit of fresh.slice(0, room))
+            this.held.push({ commit, seenAt: now });
+        if (fresh.length > room)
+            this.add({ k: 'note', p: fresh.length - room + ' more commits were seen at once and not listed (audit cap)' });
+        const due = this.held.filter((h) => final || now - h.seenAt >= COMMIT_HOLD_MS);
+        this.held = this.held.filter((h) => !due.includes(h));
+        for (const { commit, seenAt } of due) {
+            const name = projects.find((p) => p.host.toLowerCase() === commit.project.toLowerCase())?.name ??
+                hubName(commit.project, []);
+            // Git's own time, unless the sandbox's clock (or the line) is far off: then when it was seen.
+            const t = believable(commit.t, seenAt);
+            this.pending.push({
+                t,
+                k: 'commit',
+                a: commit.action,
+                p: redactCommandLine(commit.message),
+                h: commit.sha,
+                au: commit.author,
+                w: commit.project,
+                pj: name,
+                // With programs recorded, a commit no session's git command made is not put on a session as "likely" (it
+                // may well be yours, made on this PC).
+                ...this.linked(this.book.linkCommit(name, Date.parse(t), this.gitRuns, !this.settings.processes)),
+            });
+        }
+        this.gitRuns = this.gitRuns.filter((g) => g.t >= now - GIT_RUNS_KEPT_MS);
+    }
+    /** File changes not linked yet: to the one session running in their project then, if there was exactly one. */
+    linkFiles() {
+        this.pending = this.pending.map((e) => e.k === 'file' && !e.s && e.pj ? { ...e, ...this.linked(this.book.linkFile(e.pj, Date.parse(e.t))) } : e);
     }
     guard(detail) {
         this.add({ k: 'guard', p: detail.slice(0, 1024) });
     }
+    /** Old days go when the watcher starts and again whenever the day changes while it runs. */
+    maintainDaily() {
+        const today = new Date().toISOString().slice(0, 10);
+        if (today === this.maintainedOn)
+            return;
+        this.maintainedOn = today;
+        this.log.maintain(today);
+    }
     /** Writes what came in since the last call (repeats folded); call every few seconds. */
-    flush() {
-        try {
-            this.takeGuestReports();
-        }
-        catch {
-            /* next pass */
-        }
-        try {
-            this.trackSessions();
-        }
-        catch {
-            /* next pass */
-        }
+    flush(final = false) {
+        const now = Date.now();
+        const step = (work) => {
+            try {
+                work();
+            }
+            catch {
+                /* next pass */
+            }
+        };
+        step(() => this.watchProjects());
+        // Sessions first: a program or commit can only be linked to a session the book knows.
+        step(() => this.trackSessions(now));
+        step(() => this.takeGuestReports(now));
+        step(() => this.takeCommits(now, final));
+        step(() => this.linkFiles());
         const events = this.pending.sort((a, b) => a.t.localeCompare(b.t));
         this.pending = [];
         this.log.append(fold(events));
+        step(() => this.maintainDaily());
     }
     stop() {
         this.watchers.forEach((w) => w.close());
         this.add({ k: 'note', p: 'sandbox closed' });
-        this.flush();
+        this.flush(true);
         this.log.maintain();
     }
     maintain() {

package/dist/host/audit/git-commits.d.ts

@@ -0,0 +1,29 @@
+/** One commit as the reflog records it. */
+export interface CommitSeen {
+    /** ISO time git wrote. */
+    readonly t: string;
+    readonly sha: string;
+    /** Who made it, as git names them ("Name <email>"). */
+    readonly author: string;
+    /** commit | amend | merge | cherry-pick | revert | rebase | initial. */
+    readonly action: string;
+    /** The first line of its message. */
+    readonly message: string;
+    /** The project folder on this PC. */
+    readonly project: string;
+}
+/** A reflog line as a commit, or null when it is not one (a checkout, a reset, a pull without a merge commit ...). */
+export declare function parseReflogLine(line: string, project: string): CommitSeen | null;
+/** Follows the projects' reflogs: commits() returns the commits added since the last call. */
+export declare class CommitWatcher {
+    /** Reflog file -> bytes already read. */
+    private readonly offsets;
+    /** The reflogs of a project: the main one and each worktree's. */
+    private reflogs;
+    /** Starts from what is there now: only commits made from here on are reported. */
+    prime(projects: readonly string[]): void;
+    private sizeOf;
+    /** The commits added to the projects' reflogs since the last call. A reflog seen for the first time is primed. */
+    commits(projects: readonly string[]): CommitSeen[];
+    private readRange;
+}

package/dist/host/audit/git-commits.js

@@ -0,0 +1,157 @@
+// audit.commits: the git commits made in the projects while the sandbox runs, seen from this PC. Git appends a line
+// to <project>\.git\logs\HEAD (and to each worktree's) for every commit; only what was added since the last look is
+// read, a bounded amount each time. The sandbox can write these files (the project is mapped into it), so they are
+// read as untrusted text: no links followed, sizes capped, every line checked, and a reflog that shrank is not read
+// again from the start (that would report old commits as new).
+import fs from 'node:fs';
+import path from 'node:path';
+/** Most new bytes read from one reflog per look (the rest waits for the next look). */
+const MAX_READ = 256 * 1024;
+/** A reflog bigger than this is not read at all (it is not a project's). */
+const MAX_REFLOG = 512 * 1024 * 1024;
+const MAX_LINE = 4096;
+/** Worktrees of one project looked at, at most. */
+const MAX_WORKTREES = 32;
+const LINE = /^([0-9a-f]{40,64}) ([0-9a-f]{40,64}) (.{0,300}?) (\d{1,12}) ([+-]\d{4})\t(.*)$/;
+/** The reflog messages that are new commits: what made it, and its subject. */
+const COMMIT = /^(commit(?: \((initial|amend|merge)\))?|cherry-pick|revert|merge [^:]{1,200}|rebase(?: -i)? \((pick|reword|squash|fixup|edit)\)): ?(.*)$/;
+/** A reflog line as a commit, or null when it is not one (a checkout, a reset, a pull without a merge commit ...). */
+export function parseReflogLine(line, project) {
+    const m = LINE.exec(line);
+    if (!m)
+        return null;
+    const c = COMMIT.exec(m[6]);
+    if (!c || /^0+$/.test(m[2]))
+        return null;
+    const action = c[2] ?? (c[1].startsWith('merge') ? 'merge' : c[1].startsWith('rebase') ? 'rebase' : c[1]);
+    const seconds = Number(m[4]);
+    const time = new Date(seconds * 1000);
+    if (Number.isNaN(time.getTime()))
+        return null;
+    return {
+        t: time.toISOString(),
+        sha: m[2],
+        author: m[3].slice(0, 256),
+        action: action === 'commit' || action === 'initial' ? action : action.slice(0, 32),
+        message: (c[4] || '').slice(0, 1024),
+        project,
+    };
+}
+/** Is this path a plain folder or file (not a link), every step from `root` down? */
+function plainPath(root, target, kind) {
+    const rel = path.relative(root, target);
+    if (rel.startsWith('..') || path.isAbsolute(rel))
+        return false;
+    let current = root;
+    const parts = rel.split(path.sep).filter(Boolean);
+    try {
+        if (fs.lstatSync(current).isSymbolicLink())
+            return false;
+        for (let i = 0; i < parts.length; i++) {
+            current = path.join(current, parts[i]);
+            const stat = fs.lstatSync(current);
+            if (stat.isSymbolicLink())
+                return false;
+            const last = i === parts.length - 1;
+            if (last ? (kind === 'file' ? !stat.isFile() : !stat.isDirectory()) : !stat.isDirectory())
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Follows the projects' reflogs: commits() returns the commits added since the last call. */
+export class CommitWatcher {
+    /** Reflog file -> bytes already read. */
+    offsets = new Map();
+    /** The reflogs of a project: the main one and each worktree's. */
+    reflogs(project) {
+        const git = path.join(project, '.git');
+        if (!plainPath(project, git, 'dir'))
+            return [];
+        const files = [path.join(git, 'logs', 'HEAD')];
+        const worktrees = path.join(git, 'worktrees');
+        if (plainPath(project, worktrees, 'dir'))
+            try {
+                for (const name of fs.readdirSync(worktrees).slice(0, MAX_WORKTREES))
+                    files.push(path.join(worktrees, name, 'logs', 'HEAD'));
+            }
+            catch {
+                /* no worktrees to read */
+            }
+        return files.filter((f) => plainPath(project, f, 'file'));
+    }
+    /** Starts from what is there now: only commits made from here on are reported. */
+    prime(projects) {
+        for (const project of projects)
+            for (const file of this.reflogs(project))
+                if (!this.offsets.has(file))
+                    this.offsets.set(file, this.sizeOf(file));
+    }
+    sizeOf(file) {
+        try {
+            return fs.lstatSync(file).size;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /** The commits added to the projects' reflogs since the last call. A reflog seen for the first time is primed. */
+    commits(projects) {
+        const found = [];
+        for (const project of projects)
+            for (const file of this.reflogs(project)) {
+                const size = this.sizeOf(file);
+                const done = this.offsets.get(file);
+                // New (a worktree made since): from its end. Shrunk (expired or rewritten): from its new end.
+                if (done === undefined || size < done || size > MAX_REFLOG) {
+                    this.offsets.set(file, size);
+                    continue;
+                }
+                if (size === done)
+                    continue;
+                const length = Math.min(size - done, MAX_READ);
+                const bytes = this.readRange(file, done, length);
+                if (bytes === null)
+                    continue;
+                // Only whole lines (counted in bytes); a line cut by the read limit is read next time, one longer than the
+                // limit is skipped.
+                const end = bytes.lastIndexOf(0x0a);
+                if (end < 0) {
+                    if (length === MAX_READ)
+                        this.offsets.set(file, done + length);
+                    continue;
+                }
+                this.offsets.set(file, done + end + 1);
+                for (const line of bytes.subarray(0, end).toString('utf8').split('\n')) {
+                    if (line.length > MAX_LINE)
+                        continue;
+                    const commit = parseReflogLine(line.replace(/\r$/, ''), project);
+                    if (commit)
+                        found.push(commit);
+                }
+            }
+        return found;
+    }
+    readRange(file, from, length) {
+        let fd;
+        try {
+            fd = fs.openSync(file, 'r');
+            // What was opened must still be a plain file (not swapped for something else after the check).
+            if (!fs.fstatSync(fd).isFile())
+                return null;
+            const buffer = Buffer.alloc(length);
+            const read = fs.readSync(fd, buffer, 0, length, from);
+            return buffer.subarray(0, read);
+        }
+        catch {
+            return null;
+        }
+        finally {
+            if (fd !== undefined)
+                fs.closeSync(fd);
+        }
+    }
+}

package/dist/host/audit/index.d.ts

@@ -0,0 +1,5 @@
+export * from './attribute.js';
+export * from './collect.js';
+export * from './git-commits.js';
+export * from './log.js';
+export * from './redact.js';

package/dist/host/audit/index.js

@@ -0,0 +1,6 @@
+// The audit log: what agents did in the sandbox (programs, files, commits, sessions, repo guard), kept on this PC.
+export * from './attribute.js';
+export * from './collect.js';
+export * from './git-commits.js';
+export * from './log.js';
+export * from './redact.js';