windows-development-sandbox 1.11.7 → 1.13.0

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

@@ -0,0 +1,46 @@
+/** A session as the audit remembers it (its run record goes with the sandbox). */
+export interface KnownSession {
+    readonly id: string;
+    readonly agent: string;
+    /** The project it runs in (hub name). */
+    readonly project: string;
+    /** When it started and ended (ms). */
+    readonly from: number;
+    readonly to?: number;
+}
+/** A git command a session ran that can make a commit (from the programs the sandbox reported). */
+export interface GitRun {
+    readonly t: number;
+    readonly session: string;
+}
+/** A link to a session: its id and how it was made (p: process tree / git command; t: only session running). */
+export interface Link {
+    readonly s: string;
+    readonly sv: 'p' | 't';
+}
+/** git commit, merge, cherry-pick, revert, rebase, am, pull: the commands that can add a commit. */
+export declare function makesCommits(program: string, commandLine: string): boolean;
+/** The sessions of this sandbox seen so far, with when each ran. */
+export declare class SessionBook {
+    private readonly sessions;
+    /** Takes the sessions as they are now: new ones are added, ended ones get their end time. */
+    update(list: readonly {
+        readonly id: string;
+        readonly harness: string;
+        readonly project?: string;
+        readonly phase: string;
+        readonly startedAt: string;
+        readonly updatedAt: string;
+    }[], fallbackProject: string, now?: number): void;
+    get(id: string | undefined): KnownSession | undefined;
+    /** The one session running in this project at time t, or undefined when none or several were. */
+    onlyRunning(project: string, t: number): KnownSession | undefined;
+    /** A file change in a project at time t: linked only when one session ran there then. */
+    linkFile(project: string, t: number): Link | undefined;
+    /**
+     * A commit in a project at time t: the session whose git command made it when that project's sessions ran git
+     * commands that make commits around then and all were the same session's; else, when `likely` is allowed (programs
+     * are not recorded, so no git command could be seen), the one session running there.
+     */
+    linkCommit(project: string, t: number, gitRuns: readonly GitRun[], likely?: boolean): Link | undefined;
+}

package/dist/host/audit/attribute.js

@@ -0,0 +1,76 @@
+// Which agent session an event belongs to, on the PC side. Programs come linked from the sandbox (by the process tree,
+// guest/audit/parse.ts); the host only keeps a link to a session it knows. Files and commits are seen from this PC,
+// where the writer cannot be told: they are linked only when exactly one session was running in that project at the
+// time ("likely", marked as such), or, for a commit, when that project's sessions ran exactly one git command that
+// makes commits around then. Anything else stays "no session": nothing is guessed. Pure, so the self-test checks it.
+import path from 'node:path';
+/** How long before and after a commit a git command counts as the one that made it. */
+const GIT_BEFORE_MS = 3 * 60 * 1000;
+const GIT_AFTER_MS = 30 * 1000;
+/** Sessions remembered at most. */
+const MAX_SESSIONS = 512;
+/** git commit, merge, cherry-pick, revert, rebase, am, pull: the commands that can add a commit. */
+export function makesCommits(program, commandLine) {
+    return (/^git(\.exe)?$/i.test(path.win32.basename(program)) &&
+        /\s(commit|merge|cherry-pick|revert|rebase|am|pull)(\s|$)/i.test(commandLine));
+}
+/** The sessions of this sandbox seen so far, with when each ran. */
+export class SessionBook {
+    sessions = new Map();
+    /** Takes the sessions as they are now: new ones are added, ended ones get their end time. */
+    update(list, fallbackProject, now = Date.now()) {
+        for (const s of list) {
+            const known = this.sessions.get(s.id);
+            const ended = s.phase === 'exited' || s.phase === 'failed';
+            if (known) {
+                if (ended && known.to === undefined)
+                    this.sessions.set(s.id, { ...known, to: Math.min(now, Date.parse(s.updatedAt) || now) });
+                continue;
+            }
+            if (this.sessions.size >= MAX_SESSIONS)
+                continue;
+            const from = Date.parse(s.startedAt) || now;
+            this.sessions.set(s.id, {
+                id: s.id,
+                agent: s.harness,
+                project: s.project ?? fallbackProject,
+                from,
+                ...(ended ? { to: Math.max(from, Date.parse(s.updatedAt) || now) } : {}),
+            });
+        }
+        // A session whose record is gone is not running any more: it ended by now at the latest.
+        const listed = new Set(list.map((s) => s.id));
+        for (const [id, s] of this.sessions)
+            if (!listed.has(id) && s.to === undefined)
+                this.sessions.set(id, { ...s, to: now });
+    }
+    get(id) {
+        return id === undefined ? undefined : this.sessions.get(id);
+    }
+    /** The one session running in this project at time t, or undefined when none or several were. */
+    onlyRunning(project, t) {
+        const running = [...this.sessions.values()].filter((s) => s.project.toLowerCase() === project.toLowerCase() && s.from <= t && (s.to === undefined || t <= s.to));
+        return running.length === 1 ? running[0] : undefined;
+    }
+    /** A file change in a project at time t: linked only when one session ran there then. */
+    linkFile(project, t) {
+        const only = this.onlyRunning(project, t);
+        return only ? { s: only.id, sv: 't' } : undefined;
+    }
+    /**
+     * A commit in a project at time t: the session whose git command made it when that project's sessions ran git
+     * commands that make commits around then and all were the same session's; else, when `likely` is allowed (programs
+     * are not recorded, so no git command could be seen), the one session running there.
+     */
+    linkCommit(project, t, gitRuns, likely = true) {
+        const near = new Set(gitRuns
+            .filter((g) => g.t >= t - GIT_BEFORE_MS && g.t <= t + GIT_AFTER_MS)
+            .map((g) => g.session)
+            .filter((id) => this.get(id)?.project.toLowerCase() === project.toLowerCase()));
+        if (near.size === 1)
+            return { s: [...near][0], sv: 'p' };
+        if (near.size > 1)
+            return undefined;
+        return likely ? this.linkFile(project, t) : undefined;
+    }
+}

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;
+}