aicodeman 1.44.0 → 1.46.0

package/dist/git-fetch-scheduler.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview Git fetch on an interval: the sessions the user turned on, fetched by a tick the server owns
+ * (`src/git-fetch-scheduler.ts`, wired in `src/web/server.ts`).
+ *
+ * The fetch module (src/git-fetch.ts) is the only git command the Git panel runs that writes, and on a timer
+ * it is the only one that can run without being asked (cloning and worktree management write too, but those
+ * happen when the user asks for them). Which is why the whole feature is off until the user turns it on, in
+ * Settings → Bottom bar, per session in Session Options → Git.
+ *
+ * The scheduler holds no timers of its own. The server ticks it (`GIT_FETCH_TICK_INTERVAL_MS`) and every
+ * tick reads the app setting FRESH, so a live toggle takes effect on the next tick instead of at boot, and
+ * turning the feature off actually stops the fetching. A session can override both the switch and the
+ * interval; a session with no override follows the app.
+ *
+ * Rules the code keeps and the tests pin:
+ *   - Nothing runs when nothing is on: no repository set is read and nothing is spawned, so a quiet
+ *     install costs one settings read per tick. A session that turned itself on still runs even while the
+ *     app-wide switch is off: that is what a per-session switch has to mean.
+ *   - Remote and Docker sessions are never fetched, exactly as the Git panel excludes them, and the Docker
+ *     workspace roots are checked again every tick, so a session whose case became a Docker case stops
+ *     fetching at the next tick. A Docker case list that cannot be read fails CLOSED: the tick fetches
+ *     nothing (a fetch runs a repository's hooks, and without the list nothing tells which folders a
+ *     container can write to), the folders it picked stay due for the next tick, and it is logged once
+ *     until a read succeeds again.
+ *   - A folder is fetched by at most one run at a time, and the run belongs to the FOLDER, not to one
+ *     session: two sessions open on the same folder are the same clone, so they share one run and both get
+ *     its result. State is keyed by `resolve(workingDir)`, deliberately not `realpath`, because `realpath`
+ *     is itself one of the unbounded fs calls rule #516 bounds; the bounded probe below is the fs read.
+ *     Every session open on a folder is remembered, so closing the one holding the override does not stop
+ *     the folder's fetching while another session is still on it. A folder is due when ANY session open on it
+ *     is due, and the tick decides that per folder in a second pass: the order the sessions were read cannot
+ *     change which interval wins, so a 30 s session on a folder a 3600 s session last fetched ten minutes ago
+ *     is fetched now. The folder is probed once, not once per session on it.
+ *   - Before anything is fetched, the folder is probed BOUNDED with the default options (rule #516): a case
+ *     on a mount that stopped answering is skipped, never touched, and a probe that answers `unknown` is not
+ *     read as "not a folder".
+ *   - A schedule is stamped at SELECTION, when a session goes into `due`, not when its run starts, so a
+ *     tick that is still running cannot pick the same folder again; and a tick is skipped while the previous
+ *     one is still going, so the bound below is the bound for the whole tick, not per tick.
+ *   - At most `FETCH_CONCURRENCY` git processes at a time across the whole tick, because each is a git
+ *     process: ONE bound is shared by every run of the tick, so `FETCH_CONCURRENCY` is the tick's ceiling
+ *     rather than each folder's own. The folders get their OWN bound (`mapLimited`), because one semaphore
+ *     cannot serve both levels: a folder that holds a slot and then waits for one for its own fetch is
+ *     waiting on itself, and the folders that fill the bound are exactly the ones blocking it.
+ *   - The interval is timed from the START of a run, so a run that takes three minutes does not push the
+ *     next one out by three minutes; it lands on the tick after its own interval elapses.
+ *   - The per-repository limit and the git timeout stay the module's defaults (`MAX_REPOS`,
+ *     `DEFAULT_GIT_TIMEOUT_MS`): both settings are per device and never reach the server, so the server
+ *     cannot know what a device chose.
+ *   - A failure is reported, not retried harder: the folder keeps its schedule and gets its next run at its
+ *     own interval. A settings read that fails skips this tick only, rather than deciding from defaults.
+ *     settings.json is replaced atomically, so such a failure is a file that does not parse (a hand edit) or
+ *     a real read error, which lasts until someone fixes it: it is logged once, and again only after a read
+ *     has succeeded in between, not every 15 s tick.
+ *
+ * @module git-fetch-scheduler
+ */
+import { type GitFetchOptions, type GitFetchRun, type GitFetchSettings, type GitFetchStatus, type GitFetchTrigger } from './git-fetch.js';
+import type { PathProbeKind } from './utils/bounded-path-probe.js';
+/** What the scheduler needs from a session: the facts a decision needs, and nothing else. */
+export interface GitFetchSessionView {
+    id: string;
+    workingDir: string;
+    /** `unknown`, not `boolean`: a session's remote/Docker markers are objects, and the only question here is whether either is set at all. */
+    remote?: unknown;
+    docker?: unknown;
+    gitFetchEnabled?: boolean;
+    gitFetchIntervalSeconds?: number;
+}
+export interface GitFetchPorts {
+    sessionIds(): Iterable<string>;
+    getSession(id: string): GitFetchSessionView | undefined;
+    /** Read FRESH every tick; that is the whole point of the tick-driven shape. */
+    readSettings(): Promise<GitFetchSettings>;
+    /**
+     * Host paths of every Docker case workspace. REJECTS when the list exists but cannot be read or parsed; the
+     * tick then fetches nothing and the folders it picked are due again on the next tick.
+     */
+    dockerWorkspaces(): Promise<string[]>;
+    /**
+     * Bounded probe (rule #516), default options: a bulk scan keeps the stall cap, so this must not be called
+     * with `pastCap`. Anything that is not `directory` (including `unknown`, which is never `absent`) is
+     * skipped, not fetched.
+     */
+    probePath(path: string): Promise<PathProbeKind>;
+    /** Called through `fetchWorkspaceOnce`, so a run already going for this folder is joined, not stacked. */
+    fetch(cwd: string, opts: GitFetchOptions, trigger: GitFetchTrigger): Promise<GitFetchRun>;
+    publish(id: string, status: GitFetchStatus): void;
+    log?(message: string): void;
+}
+/**
+ * What one session will actually do: its own override wins, otherwise the app-wide setting. The interval is
+ * clamped again here because a persisted value can predate the schema's bounds.
+ */
+export declare function effectiveGitFetch(view: GitFetchSessionView, settings: GitFetchSettings): {
+    enabled: boolean;
+    intervalSeconds: number;
+};
+export declare class GitFetchScheduler {
+    private readonly ports;
+    /** When each FOLDER last started a run; timed from the start, not the end. */
+    private readonly lastRunAt;
+    private readonly inFlight;
+    /** Session → folder, so `remove()` can keep the folder's schedule while other sessions are still on it. */
+    private readonly folderOf;
+    private running;
+    private stopped;
+    /** The last settings read failed and was logged; cleared by the next read that succeeds. */
+    private settingsUnreadable;
+    /** The same for the Docker case list. */
+    private dockerCasesUnreadable;
+    constructor(ports: GitFetchPorts);
+    /** One tick: fetch every folder whose sessions are on and due. Returns how many folders ran. */
+    tick(now?: number): Promise<number>;
+    /**
+     * A session that closed or was detached: its schedule goes with it, but the FOLDER's stays while another
+     * session is still open on it: the run belongs to the clone, not to the session that asked for it.
+     */
+    remove(id: string): void;
+    stop(): void;
+    /** Folders the scheduler still remembers a run for, so a test can see a `remove()` actually took. */
+    tracked(): number;
+}
+//# sourceMappingURL=git-fetch-scheduler.d.ts.map

package/dist/git-fetch-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-fetch-scheduler.d.ts","sourceRoot":"","sources":["../src/git-fetch-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAIH,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,6FAA6F;AAC7F,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,2IAA2I;IAC3I,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAQD,MAAM,WAAW,aAAa;IAC5B,UAAU,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAAC;IACxD,+EAA+E;IAC/E,YAAY,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1C;;;OAGG;IACH,gBAAgB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACtC;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAChD,0GAA0G;IAC1G,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1F,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAClD,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,mBAAmB,EACzB,QAAQ,EAAE,gBAAgB,GACzB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAU/C;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,2GAA2G;IAC3G,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,4FAA4F;IAC5F,OAAO,CAAC,kBAAkB,CAAS;IACnC,yCAAyC;IACzC,OAAO,CAAC,qBAAqB,CAAS;gBAE1B,KAAK,EAAE,aAAa;IAIhC,gGAAgG;IAC1F,IAAI,CAAC,GAAG,SAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAiI7C;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAWxB,IAAI,IAAI,IAAI;IAOZ,qGAAqG;IACrG,OAAO,IAAI,MAAM;CAGlB"}

package/dist/git-fetch-scheduler.js

@@ -0,0 +1,249 @@
+/**
+ * @fileoverview Git fetch on an interval: the sessions the user turned on, fetched by a tick the server owns
+ * (`src/git-fetch-scheduler.ts`, wired in `src/web/server.ts`).
+ *
+ * The fetch module (src/git-fetch.ts) is the only git command the Git panel runs that writes, and on a timer
+ * it is the only one that can run without being asked (cloning and worktree management write too, but those
+ * happen when the user asks for them). Which is why the whole feature is off until the user turns it on, in
+ * Settings → Bottom bar, per session in Session Options → Git.
+ *
+ * The scheduler holds no timers of its own. The server ticks it (`GIT_FETCH_TICK_INTERVAL_MS`) and every
+ * tick reads the app setting FRESH, so a live toggle takes effect on the next tick instead of at boot, and
+ * turning the feature off actually stops the fetching. A session can override both the switch and the
+ * interval; a session with no override follows the app.
+ *
+ * Rules the code keeps and the tests pin:
+ *   - Nothing runs when nothing is on: no repository set is read and nothing is spawned, so a quiet
+ *     install costs one settings read per tick. A session that turned itself on still runs even while the
+ *     app-wide switch is off: that is what a per-session switch has to mean.
+ *   - Remote and Docker sessions are never fetched, exactly as the Git panel excludes them, and the Docker
+ *     workspace roots are checked again every tick, so a session whose case became a Docker case stops
+ *     fetching at the next tick. A Docker case list that cannot be read fails CLOSED: the tick fetches
+ *     nothing (a fetch runs a repository's hooks, and without the list nothing tells which folders a
+ *     container can write to), the folders it picked stay due for the next tick, and it is logged once
+ *     until a read succeeds again.
+ *   - A folder is fetched by at most one run at a time, and the run belongs to the FOLDER, not to one
+ *     session: two sessions open on the same folder are the same clone, so they share one run and both get
+ *     its result. State is keyed by `resolve(workingDir)`, deliberately not `realpath`, because `realpath`
+ *     is itself one of the unbounded fs calls rule #516 bounds; the bounded probe below is the fs read.
+ *     Every session open on a folder is remembered, so closing the one holding the override does not stop
+ *     the folder's fetching while another session is still on it. A folder is due when ANY session open on it
+ *     is due, and the tick decides that per folder in a second pass: the order the sessions were read cannot
+ *     change which interval wins, so a 30 s session on a folder a 3600 s session last fetched ten minutes ago
+ *     is fetched now. The folder is probed once, not once per session on it.
+ *   - Before anything is fetched, the folder is probed BOUNDED with the default options (rule #516): a case
+ *     on a mount that stopped answering is skipped, never touched, and a probe that answers `unknown` is not
+ *     read as "not a folder".
+ *   - A schedule is stamped at SELECTION, when a session goes into `due`, not when its run starts, so a
+ *     tick that is still running cannot pick the same folder again; and a tick is skipped while the previous
+ *     one is still going, so the bound below is the bound for the whole tick, not per tick.
+ *   - At most `FETCH_CONCURRENCY` git processes at a time across the whole tick, because each is a git
+ *     process: ONE bound is shared by every run of the tick, so `FETCH_CONCURRENCY` is the tick's ceiling
+ *     rather than each folder's own. The folders get their OWN bound (`mapLimited`), because one semaphore
+ *     cannot serve both levels: a folder that holds a slot and then waits for one for its own fetch is
+ *     waiting on itself, and the folders that fill the bound are exactly the ones blocking it.
+ *   - The interval is timed from the START of a run, so a run that takes three minutes does not push the
+ *     next one out by three minutes; it lands on the tick after its own interval elapses.
+ *   - The per-repository limit and the git timeout stay the module's defaults (`MAX_REPOS`,
+ *     `DEFAULT_GIT_TIMEOUT_MS`): both settings are per device and never reach the server, so the server
+ *     cannot know what a device chose.
+ *   - A failure is reported, not retried harder: the folder keeps its schedule and gets its next run at its
+ *     own interval. A settings read that fails skips this tick only, rather than deciding from defaults.
+ *     settings.json is replaced atomically, so such a failure is a file that does not parse (a hand edit) or
+ *     a real read error, which lasts until someone fixes it: it is logged once, and again only after a read
+ *     has succeeded in between, not every 15 s tick.
+ *
+ * @module git-fetch-scheduler
+ */
+import { resolve } from 'node:path';
+import { getErrorMessage } from './types.js';
+import { FETCH_CONCURRENCY, MAX_GIT_FETCH_INTERVAL_SECONDS, MIN_GIT_FETCH_INTERVAL_SECONDS, gitFetchStatusFrom, } from './git-fetch.js';
+import { clampInt, DEFAULT_GIT_TIMEOUT_MS, MAX_REPOS, createLimiter, mapLimited } from './git-workspace-status.js';
+/**
+ * What one session will actually do: its own override wins, otherwise the app-wide setting. The interval is
+ * clamped again here because a persisted value can predate the schema's bounds.
+ */
+export function effectiveGitFetch(view, settings) {
+    return {
+        enabled: view.gitFetchEnabled ?? settings.enabled,
+        intervalSeconds: clampInt(view.gitFetchIntervalSeconds ?? settings.intervalSeconds, MIN_GIT_FETCH_INTERVAL_SECONDS, MAX_GIT_FETCH_INTERVAL_SECONDS, MIN_GIT_FETCH_INTERVAL_SECONDS),
+    };
+}
+export class GitFetchScheduler {
+    ports;
+    /** When each FOLDER last started a run; timed from the start, not the end. */
+    lastRunAt = new Map();
+    inFlight = new Set();
+    /** Session → folder, so `remove()` can keep the folder's schedule while other sessions are still on it. */
+    folderOf = new Map();
+    running = false;
+    stopped = false;
+    /** The last settings read failed and was logged; cleared by the next read that succeeds. */
+    settingsUnreadable = false;
+    /** The same for the Docker case list. */
+    dockerCasesUnreadable = false;
+    constructor(ports) {
+        this.ports = ports;
+    }
+    /** One tick: fetch every folder whose sessions are on and due. Returns how many folders ran. */
+    async tick(now = Date.now()) {
+        if (this.stopped || this.running)
+            return 0;
+        this.running = true;
+        try {
+            let settings;
+            try {
+                settings = await this.ports.readSettings();
+            }
+            catch (err) {
+                // Writes are atomic, so this is a real read error or a file that does not parse (a hand edit), and it
+                // stays that way until it is fixed: logged once, not on every tick. The reader never puts the file's
+                // text in its error (readGitFetchSettings), since settings.json can hold an API key.
+                if (!this.settingsUnreadable) {
+                    this.settingsUnreadable = true;
+                    this.ports.log?.(`git fetch: settings unreadable, ticks skipped until it reads again: ${getErrorMessage(err)}`);
+                }
+                return 0;
+            }
+            this.settingsUnreadable = false;
+            // Pass 1: who is on what, before anything is decided. Every session open on a folder is recorded here,
+            // not only the one that would get picked, so `remove()` can still see who is open on it when the session
+            // holding the override is the one that closes.
+            const groups = new Map();
+            for (const id of this.ports.sessionIds()) {
+                const view = this.ports.getSession(id);
+                if (!view || view.remote || view.docker)
+                    continue;
+                const effective = effectiveGitFetch(view, settings);
+                if (!effective.enabled)
+                    continue;
+                const folder = resolve(view.workingDir);
+                this.folderOf.set(id, folder);
+                const group = groups.get(folder);
+                const member = { view, intervalSeconds: effective.intervalSeconds };
+                if (group)
+                    group.push(member);
+                else
+                    groups.set(folder, [member]);
+            }
+            // Pass 2: the folder's turn, decided from the whole group rather than from whichever session happened to
+            // be read first. A folder is due when ANY session open on it is due: a session on a 30 s interval on a
+            // folder a 3600 s session last fetched ten minutes ago has to be fetched now, because that same run
+            // satisfies the long interval too. Deciding in one pass means the session read first owns the clock: a
+            // group ordered [short, long] and a group ordered [long, short] would have behaved differently, and the
+            // run belongs to the folder, so no session in the group should.
+            const due = new Map();
+            // What each picked folder's clock said before this tick stamped it, so a tick that ends up fetching
+            // nothing (an unreadable Docker case list, below) can leave the folders due again.
+            const stampedOver = new Map();
+            for (const [folder, group] of groups) {
+                if (this.inFlight.has(folder))
+                    continue;
+                const started = this.lastRunAt.get(folder);
+                const isDue = started === undefined || group.some((m) => now - started >= m.intervalSeconds * 1000);
+                if (!isDue)
+                    continue;
+                // Bounded probe (rule #516), once per folder rather than once per session on it.
+                const kind = await this.ports.probePath(folder);
+                if (kind !== 'directory') {
+                    this.ports.log?.(`git fetch: ${folder} skipped, answered ${kind}`);
+                    continue;
+                }
+                this.inFlight.add(folder);
+                // The clock starts at the selection, so a slow folder does not shift its own schedule.
+                stampedOver.set(folder, started);
+                this.lastRunAt.set(folder, now);
+                due.set(folder, group);
+            }
+            if (!due.size)
+                return 0;
+            // Only now, because nothing above needs it: a quiet tick does not read the Docker case list.
+            let dockerWorkspaces;
+            try {
+                dockerWorkspaces = await this.ports.dockerWorkspaces();
+            }
+            catch (err) {
+                // Fail CLOSED: a fetch runs the repository's hooks, and without the list nothing tells which folders a
+                // container can write to. Nothing ran, so the picks are undone (a stamp a `remove()` already cleared
+                // stays cleared) and the folders are due again on the next tick instead of after their interval.
+                for (const [folder, started] of stampedOver) {
+                    this.inFlight.delete(folder);
+                    if (this.lastRunAt.get(folder) !== now)
+                        continue;
+                    if (started === undefined)
+                        this.lastRunAt.delete(folder);
+                    else
+                        this.lastRunAt.set(folder, started);
+                }
+                if (!this.dockerCasesUnreadable) {
+                    this.dockerCasesUnreadable = true;
+                    this.ports.log?.(`git fetch: Docker case list unreadable, nothing fetched until it reads again: ${getErrorMessage(err)}`);
+                }
+                return 0;
+            }
+            this.dockerCasesUnreadable = false;
+            // ONE bound for the git processes of the whole tick, handed to every run so no folder gets its own:
+            // each fetch is one git process, and a folder can hold up to `MAX_REPOS_LIMIT` of them, so a bound per
+            // run would let `FETCH_CONCURRENCY` folders × `MAX_REPOS_LIMIT` processes run at once.
+            const fetches = createLimiter(FETCH_CONCURRENCY);
+            // The folders get their OWN bound, because the same semaphore cannot serve both levels: a folder that
+            // holds a slot and then waits for a slot for its own fetch is waiting on itself: once
+            // `FETCH_CONCURRENCY` folders fill the bound, the ones holding slots are exactly the ones that can
+            // never get one back. Both bounds are `FETCH_CONCURRENCY`, so the tick still never runs more git
+            // processes than the module's ceiling.
+            await mapLimited([...due.entries()], FETCH_CONCURRENCY, async ([folder, group]) => {
+                try {
+                    const run = await this.ports.fetch(folder, {
+                        dockerWorkspaces,
+                        maxRepos: MAX_REPOS,
+                        timeoutMs: DEFAULT_GIT_TIMEOUT_MS,
+                        limiter: fetches,
+                    }, 'interval');
+                    // Every session on the folder gets the SAME run, with the trigger of the run that actually happened:
+                    // if this tick joined a run a click had already started, the row has to say it was a click, because
+                    // that is what fetched it.
+                    for (const member of group)
+                        this.ports.publish(member.view.id, gitFetchStatusFrom(run.report, run.trigger));
+                }
+                catch (err) {
+                    // The run that failed keeps its reason in the panel's own row; here only the folder-level failure is
+                    // worth a line, because nothing else would say a scheduled fetch could not run at all.
+                    this.ports.log?.(`git fetch: ${folder} could not run: ${getErrorMessage(err)}`);
+                }
+                finally {
+                    this.inFlight.delete(folder);
+                }
+            });
+            return due.size;
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    /**
+     * A session that closed or was detached: its schedule goes with it, but the FOLDER's stays while another
+     * session is still open on it: the run belongs to the clone, not to the session that asked for it.
+     */
+    remove(id) {
+        const folder = this.folderOf.get(id);
+        this.folderOf.delete(id);
+        if (!folder)
+            return;
+        const stillOpen = [...this.folderOf.values()].includes(folder);
+        if (!stillOpen) {
+            this.lastRunAt.delete(folder);
+            this.inFlight.delete(folder);
+        }
+    }
+    stop() {
+        this.stopped = true;
+        this.lastRunAt.clear();
+        this.inFlight.clear();
+        this.folderOf.clear();
+    }
+    /** Folders the scheduler still remembers a run for, so a test can see a `remove()` actually took. */
+    tracked() {
+        return new Set([...this.lastRunAt.keys(), ...this.inFlight]).size;
+    }
+}
+//# sourceMappingURL=git-fetch-scheduler.js.map

package/dist/git-fetch-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-fetch-scheduler.js","sourceRoot":"","sources":["../src/git-fetch-scheduler.ts"],"names":[],"mappings":"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"}

package/dist/git-fetch.d.ts

@@ -0,0 +1,241 @@
+/**
+ * @fileoverview `git fetch` for the repositories the Git panel shows, on the user's click
+ * (`POST /api/sessions/:id/git-fetch`) or on an interval the user turned on
+ * (`src/git-fetch-scheduler.ts`).
+ *
+ * The status module (src/git-workspace-status.ts) is deliberately offline: "behind" is as of the last
+ * fetch, so a number that is stale can only be made current by fetching. This is the only git command the
+ * Git panel runs that writes, and the only git command Codeman runs on a timer. Cloning a repository and
+ * managing worktrees write too, but those are things the user asked for at the moment they asked; this is
+ * the one that can happen later, by itself. Nothing here commits, checks out, merges or touches the working
+ * tree: `git fetch` updates remote-tracking
+ * refs and nothing else, and `FETCH_CONFIG_ARGS` keeps it from starting a gc in a repository an agent is
+ * already using. It is not harmless in the way a read is: a fetch holds git's ref lock, so an agent's own
+ * `git pull` in the same clone can collide with it (`cannot lock ref`), which is why one folder is fetched
+ * by at most one run at a time (`fetchWorkspaceOnce`).
+ *
+ * Same split as git-clone.ts: the pure half (`buildFetchArgs`, `describeFetchFailure`, `fetchEnvFor`,
+ * `gitFetchSettingsFrom`, `gitFetchStatusFrom`) holds every decision and tests without spawning, and the IO
+ * half runs one bounded `git fetch --quiet` per repository.
+ *
+ * Rules the code keeps and the tests pin:
+ *   - The repository set is `resolveWorkspaceRepos`, the single source the panel and the diff route
+ *     already use, so Fetch cannot reach a repository the panel would not show. The Docker rule is
+ *     checked before any git runs: a repository a container can write to is refused outright, because a
+ *     planted config would run on the host, and `git fetch` is exactly the command that can run a
+ *     repository's own hooks (`reference-transaction`, and `pre-auto-gc` through the automatic maintenance
+ *     that follows a fetch) and its config commands such as `credential.helper`, which is why a timer only
+ *     runs it after the user opts in.
+ *   - One run per folder at a time: `fetchWorkspaceOnce` joins a run already going for the same folder
+ *     instead of starting a second one, because two fetches in one clone collide on the ref lock.
+ *   - Bounded: the git timeout from Settings → Bottom bar per repository, `MAX_REPOS_LIMIT` repositories at
+ *     most, a hard wall-clock bound on each spawn, and `FETCH_CONCURRENCY` git processes at a time for the
+ *     whole run: one `Limiter`, shared by the scheduler's tick, not one bound per folder.
+ *   - Non-interactive: `GIT_TERMINAL_PROMPT=0` and BatchMode ssh, so a private repository that needs a
+ *     login fails fast instead of hanging the request on an invisible username prompt. Codeman collects
+ *     no credentials; a repository the user's own git is already signed in to works because that is the
+ *     user's existing setup, so unlike a clone no credential helper is disabled here. That BatchMode ssh is
+ *     a default, never an override: `fetchEnvFor` keeps whatever the repository's `core.sshCommand`, the
+ *     user's own `GIT_SSH_COMMAND` or a `GIT_SSH` already says, because on a machine with several ssh setups
+ *     that choice is usually the one that works. ⚠️ The default still leaves a record: `StrictHostKeyChecking=accept-new`
+ *     writes an unknown host key into `~/.ssh/known_hosts` without asking: BatchMode stops a prompt, not a
+ *     write.
+ *   - The timeout kills the PROCESS GROUP, not just the `git` parent. A fetch over http spawns
+ *     `git-remote-http` children, and `execFile`'s `timeout` signals the parent only, so the answer can go
+ *     out while a helper is still running, and on a timer that repeats every tick with nobody watching.
+ *     `spawn` with `detached: true` puts the tree in its own group so the escalation (SIGTERM, then SIGKILL
+ *     `FETCH_KILL_ESCALATION_MS` later) reaches the children too, which is why the negative pid is used
+ *     rather than `child.kill()`. Same shape as `runGit` in git-clone.ts, without that module's slot queue:
+ *     fetch is bounded by `FETCH_CONCURRENCY`, not by a clone queue.
+ *   - Failure text reaching a client is control-stripped and credential-redacted (`sanitizeGitOutput`),
+ *     and the browser writes it with `textContent` only.
+ *
+ * @module git-fetch
+ */
+import { type GitFailureCode } from './git-clone.js';
+import { type Limiter, type GitRunner } from './git-workspace-status.js';
+/**
+ * Git processes in flight at once, for one run, and for a whole scheduler tick, because the tick hands ONE
+ * bound to every run (see `createLimiter`): each fetch is one git process, and a folder can hold up to
+ * `MAX_REPOS_LIMIT`. The tick bounds its folders separately, because the same semaphore cannot serve both
+ * levels: a folder holding a slot would then wait for a slot its own fetch needs.
+ */
+export declare const FETCH_CONCURRENCY = 4;
+/**
+ * How long the process group gets to answer SIGTERM before the same escalation goes to SIGKILL. Kept as a
+ * const so a test can say how long it is willing to wait for the group to actually die.
+ */
+export declare const FETCH_KILL_ESCALATION_MS = 3000;
+/**
+ * Config overrides set ahead of the argv, so an unattended fetch cannot do more than move refs: no
+ * fsmonitor hook, and no automatic maintenance or gc. A fetch is the git command that can run a
+ * repository's own hooks (`reference-transaction`, and `pre-auto-gc` through the maintenance that follows a
+ * fetch), and a gc started by a timer in a repository an agent is working in is exactly the kind of extra
+ * write this module must not do. Kept as a const so a test can pin it without spawning git.
+ */
+export declare const FETCH_CONFIG_ARGS: string[];
+/** The interval the user can turn on (Settings → Bottom bar, and Session Options → Git): bounds and default. */
+export declare const DEFAULT_GIT_FETCH_INTERVAL_SECONDS = 300;
+export declare const MIN_GIT_FETCH_INTERVAL_SECONDS = 30;
+export declare const MAX_GIT_FETCH_INTERVAL_SECONDS = 3600;
+export interface GitFetchSettings {
+    enabled: boolean;
+    intervalSeconds: number;
+}
+/**
+ * A settings object as the scheduler should read it: absent means OFF, because nothing runs on a timer
+ * until the user turns this on, and a number outside the schema's bounds is clamped rather than trusted.
+ * Pure, so the reading itself is testable without a settings file.
+ */
+export declare function gitFetchSettingsFrom(settings: Record<string, unknown> | undefined): GitFetchSettings;
+/**
+ * The only git command this module runs. Kept as a function so a test can pin the verb: nothing here
+ * commits, checks out, merges or prunes, and no operand is interpolated: the repository is the process
+ * `cwd` and the argv is fixed.
+ */
+export declare function buildFetchArgs(): string[];
+/**
+ * The `git` process also gets the `FETCH_CONFIG_ARGS` overrides ahead of this argv; they are kept separate
+ * so pinning the verb here does not have to say anything about maintenance, and so both can be tested
+ * without spawning.
+ *
+ * A repository with no remote is a fact, not a fault. Git's wordings for it differ by version (2.47
+ * exits quietly and this code is never reached, older git says "no default remote repository"), so the
+ * branch is pinned on literal fixtures and the code the panel shows is the code this writes.
+ */
+export type FetchFailureCode = GitFailureCode | 'NO_REMOTE';
+export interface FetchFailure {
+    code: FetchFailureCode;
+    /** User-facing summary. */
+    message: string;
+    /** Tail of git's own stderr, control-stripped and credential-redacted. */
+    stderr: string;
+}
+/**
+ * A thrown git error as the panel should show it. `classifyGitFailure` (git-clone.ts) already knows the
+ * network reasons (auth, an unreachable host, a missing git), so they are reused here; only its timeout
+ * wording is written for clones, so the fetch path replaces it with what the user can actually do.
+ */
+export declare function describeFetchFailure(err: unknown): FetchFailure;
+/**
+ * The environment a fetch gets, as a pure decision so it can be pinned without spawning git.
+ *
+ * `gitNonInteractiveEnv` supplies the BatchMode default, and the default is only a default: git reads
+ * `GIT_SSH_COMMAND` from the environment ahead of the repository's `core.sshCommand`, so setting it would
+ * override a repository that already chose its own ssh (an alternative host, an identity file, a jump box)
+ * and break a setup that works today. The server's own `GIT_SSH` is the same kind of answer: git reads it
+ * after both of those (`GIT_SSH_COMMAND`, then `core.sshCommand`, then `GIT_SSH`), so a written default would
+ * hide it too. That is the only case where this module makes an ssh choice on the user's behalf, so it is the
+ * whole decision here: the caller supplies the value it read, and this decides between the user's
+ * environment and the repository's own answer.
+ */
+export declare function fetchEnvFor(base: NodeJS.ProcessEnv, repoSshCommand: string | null): NodeJS.ProcessEnv;
+/**
+ * The repository's own `core.sshCommand`, or null. One bounded, read-only `git config --get` per fetch:
+ * git would honour that config itself if we did not write `GIT_SSH_COMMAND` over it, so honouring it means
+ * not writing one. `--get` reads local and global config, which is the value git would have used, and no
+ * hook or filter runs on the way to it.
+ *
+ * The read happens inside the same slot and the same wall-clock bound as the fetch it serves, so it cannot
+ * add a fifth git process or push a fetch past the user's timeout: it spends part of it.
+ */
+export declare function readRepoSshCommand(cwd: string, timeoutMs: number): Promise<string | null>;
+/**
+ * Fetch is allowed to write refs, so this runner does not carry `--no-optional-locks`: fetch takes a
+ * required lock anyway.
+ *
+ * `spawn`, not `execFile`, because the bound has to reach the whole tree (see the fileoverview): the
+ * caller is answered at the timeout, and the SIGTERM → SIGKILL escalation is deliberately NOT cancelled
+ * when the answer goes out, because the promise is a promise about the answer while the group still has to
+ * die. That is the difference from `runGit` in git-clone.ts, which disarms the escalation at `finish` and so
+ * can leave a `git-remote-http` child running after a timed-out call.
+ *
+ * The thrown error keeps the shape `describeFetchFailure` reads: `stderr` for the reason, `message` for a
+ * spawn failure (`spawn git ENOENT` → GIT_MISSING), `killed` and `code` for the timeout. A non-zero exit
+ * rejects the way `execFile` would (`code` is then the exit code), because resolving it would report a real
+ * failure as a clean run with an empty reason.
+ *
+ * `timeoutMs` bounds the `core.sshCommand` read and the fetch TOGETHER: the spawn is armed with what the read
+ * left, so a `git` that never answers costs one timeout, not two. A read that used the whole bound answers
+ * as a timeout without starting the fetch.
+ */
+export declare const runFetch: GitRunner;
+export interface GitFetchEntry {
+    /** Folder name of the repository (its root's basename), as the panel names it. */
+    name: string;
+    /** The repository root relative to the working directory: `.`, `..`, `api`, `apps/web`. */
+    path: string;
+    ok: boolean;
+    failure?: FetchFailure;
+}
+export interface GitFetchReport {
+    /** `ok` when at least one repository was fetched (or attempted); the other states are as in the overview. */
+    state: 'ok' | 'not-a-repo' | 'unsupported' | 'error';
+    reason?: 'remote' | 'docker';
+    error?: string;
+    /** One entry per repository fetched, in the same order the panel lists them. */
+    repos: GitFetchEntry[];
+    /** More than `repoLimit` repositories were found; only the first were fetched. */
+    reposTruncated: boolean;
+    /** The most repositories this fetch would list (the caller's setting, or `MAX_REPOS`). */
+    repoLimit?: number;
+    /** When the last repository finished, so the panel can say what the "behind" number is now based on. */
+    fetchedAt: number;
+}
+/**
+ * What one run did, in the shape a session keeps and the Session Options Git row shows. `trigger` says
+ * whether the user clicked or the interval fired, because a number the user did not ask for should read
+ * differently from one they did.
+ */
+/** What a run was, and why it happened. */
+export type GitFetchTrigger = 'click' | 'interval';
+export interface GitFetchStatus {
+    ranAt: number;
+    trigger: GitFetchTrigger;
+    /** As in the report: `ok`, or the state that stopped the run. */
+    state: GitFetchReport['state'];
+    /** Repositories this run covered. */
+    repos: number;
+    /** How many of them could not be fetched. */
+    failed: number;
+    /** The first failure, named: enough for one row without reprinting the whole list. */
+    firstFailure?: {
+        name: string;
+        code: FetchFailureCode;
+    };
+}
+/**
+ * One run, with the trigger that caused it. A joiner gets the run already going, so what it reports is that
+ * run's trigger rather than the one that made it ask: a click that joins an interval run did not fetch
+ * anything itself, and the row the panel shows has to describe the fetch that actually happened.
+ */
+export interface GitFetchRun {
+    report: GitFetchReport;
+    trigger: GitFetchTrigger;
+}
+export declare function gitFetchStatusFrom(report: GitFetchReport, trigger: GitFetchTrigger): GitFetchStatus;
+/** Options for the fetch path: the same repository rules and limits as an overview, without its cache clock. */
+export interface GitFetchOptions {
+    git?: GitRunner;
+    home?: string;
+    dockerWorkspaces?: string[];
+    maxRepos?: number;
+    timeoutMs?: number;
+    /**
+     * The shared slot count for a whole scheduler tick. Passed in so `FETCH_CONCURRENCY` bounds the tick
+     * rather than each folder separately; without it, a tick over more than `FETCH_CONCURRENCY` folders could
+     * have that many git processes going at once inside each one.
+     */
+    limiter?: Limiter;
+}
+export declare const emptyReport: (state: GitFetchReport["state"], extra?: Partial<GitFetchReport>) => GitFetchReport;
+/**
+ * Fetch every repository the panel would show for `cwd`, through the same resolver so the two cannot
+ * disagree. A repository that failed keeps its row with the reason, exactly as an unreadable repository
+ * stays in the status list: the panel must show that something was not fetched rather than quietly skip it.
+ */
+export declare function fetchGitWorkspaceOverview(cwd: string, opts?: GitFetchOptions): Promise<GitFetchReport>;
+export declare function fetchWorkspaceOnce(folder: string, opts: GitFetchOptions | undefined, trigger: GitFetchTrigger): Promise<GitFetchRun>;
+/** Test seam: an in-memory lane is not cleared by stopping the scheduler, so a test has to clear it itself. */
+export declare function clearGitFetchLane(): void;
+//# sourceMappingURL=git-fetch.d.ts.map

package/dist/git-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-fetch.d.ts","sourceRoot":"","sources":["../src/git-fetch.ts"],"names":[],"mappings":"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"}