instar 0.28.95 → 0.28.97

package/dist/core/MachineHeartbeat.d.ts

@@ -0,0 +1,94 @@
+/**
+ * MachineHeartbeat — per-machine liveness signal for multi-machine
+ * project ownership.
+ *
+ * Spec: docs/specs/PROJECT-SCOPE-SPEC.md § P5 ("Machine ownership for
+ * multi-machine coherence").
+ *
+ * Each machine writes `.instar/machine-health/<machineId>.json` every
+ * heartbeat interval (default 30 minutes). The file is GIT-SYNCED, so
+ * other machines see fresh heartbeats from any peer that's online.
+ *
+ * Leader election (claim-ownership) treats a heartbeat older than
+ * `staleThresholdMs` (default 48 hours) as evidence that the recorded
+ * owner has gone offline and the claim should be allowed to proceed.
+ *
+ * What this class is NOT responsible for:
+ *   - The git-sync that pushes the heartbeat file (handled by the
+ *     existing GitSync layer).
+ *   - The 60-second wait-for-convergence that the spec requires of
+ *     a claimer. That's the caller's responsibility — the heartbeat
+ *     just provides the staleness query.
+ *
+ * File schema:
+ *   {
+ *     "machineId": "<stable id>",
+ *     "hostname": "<os.hostname()>",
+ *     "lastHeartbeatAt": "<ISO timestamp>",
+ *     "instarVersion": "<package.json version>"
+ *   }
+ *
+ * Corruption tolerance: a malformed heartbeat file is treated as a
+ * missing heartbeat (stale by definition). The next write overwrites
+ * it with a valid record.
+ */
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS: number;
+export declare const DEFAULT_STALE_THRESHOLD_MS: number;
+export interface HeartbeatRecord {
+    machineId: string;
+    hostname: string;
+    lastHeartbeatAt: string;
+    instarVersion?: string;
+}
+export interface MachineHeartbeatConfig {
+    /** Absolute path to the agent's `.instar/` directory. */
+    stateDir: string;
+    /** Stable machine id (usually the coordinator's machine id). */
+    machineId: string;
+    /** Defaults to 30 minutes; tests dial this down. */
+    heartbeatIntervalMs?: number;
+    /** Defaults to 48h. Tests dial this down. */
+    staleThresholdMs?: number;
+    /** Optional version string written into the heartbeat record. */
+    instarVersion?: string;
+    /** Optional clock override (tests). */
+    now?: () => Date;
+}
+export declare class MachineHeartbeat {
+    private stateDir;
+    private machineId;
+    private heartbeatIntervalMs;
+    private staleThresholdMs;
+    private instarVersion?;
+    private now;
+    private timer;
+    constructor(config: MachineHeartbeatConfig);
+    /** Identity of THIS machine (read-only for routes that need it). */
+    get id(): string;
+    /** Write a heartbeat immediately and start the periodic timer. */
+    start(): void;
+    /** Stop the periodic timer. */
+    stop(): void;
+    /** Write a single heartbeat. Public so server-startup paths can write
+     *  one before the first interval fires. */
+    writeOnce(): HeartbeatRecord;
+    /** Read the heartbeat for any machine. Returns null on missing or malformed. */
+    read(machineId: string): HeartbeatRecord | null;
+    /**
+     * Is the heartbeat for `machineId` stale?
+     *
+     * Returns true when:
+     *   - the heartbeat file is missing
+     *   - the heartbeat file is malformed (defense-in-depth)
+     *   - `lastHeartbeatAt` is older than `staleThresholdMs` ago
+     *
+     * Returns false when the heartbeat is within the threshold.
+     */
+    isStale(machineId: string): boolean;
+    /** List all known heartbeats (one per machine). */
+    listAll(): HeartbeatRecord[];
+    private ensureDir;
+    private dirPath;
+    private recordPath;
+}
+//# sourceMappingURL=MachineHeartbeat.d.ts.map

package/dist/core/MachineHeartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MachineHeartbeat.d.ts","sourceRoot":"","sources":["../../src/core/MachineHeartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH,eAAO,MAAM,6BAA6B,QAAiB,CAAC;AAC5D,eAAO,MAAM,0BAA0B,QAAsB,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,GAAG,CAAa;IACxB,OAAO,CAAC,KAAK,CAA+C;gBAEhD,MAAM,EAAE,sBAAsB;IAS1C,oEAAoE;IACpE,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,kEAAkE;IAClE,KAAK,IAAI,IAAI;IAQb,+BAA+B;IAC/B,IAAI,IAAI,IAAI;IAOZ;+CAC2C;IAC3C,SAAS,IAAI,eAAe;IAc5B,gFAAgF;IAChF,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAa/C;;;;;;;;;OASG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAQnC,mDAAmD;IACnD,OAAO,IAAI,eAAe,EAAE;IAW5B,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,UAAU;CAMnB"}

package/dist/core/MachineHeartbeat.js

@@ -0,0 +1,155 @@
+/**
+ * MachineHeartbeat — per-machine liveness signal for multi-machine
+ * project ownership.
+ *
+ * Spec: docs/specs/PROJECT-SCOPE-SPEC.md § P5 ("Machine ownership for
+ * multi-machine coherence").
+ *
+ * Each machine writes `.instar/machine-health/<machineId>.json` every
+ * heartbeat interval (default 30 minutes). The file is GIT-SYNCED, so
+ * other machines see fresh heartbeats from any peer that's online.
+ *
+ * Leader election (claim-ownership) treats a heartbeat older than
+ * `staleThresholdMs` (default 48 hours) as evidence that the recorded
+ * owner has gone offline and the claim should be allowed to proceed.
+ *
+ * What this class is NOT responsible for:
+ *   - The git-sync that pushes the heartbeat file (handled by the
+ *     existing GitSync layer).
+ *   - The 60-second wait-for-convergence that the spec requires of
+ *     a claimer. That's the caller's responsibility — the heartbeat
+ *     just provides the staleness query.
+ *
+ * File schema:
+ *   {
+ *     "machineId": "<stable id>",
+ *     "hostname": "<os.hostname()>",
+ *     "lastHeartbeatAt": "<ISO timestamp>",
+ *     "instarVersion": "<package.json version>"
+ *   }
+ *
+ * Corruption tolerance: a malformed heartbeat file is treated as a
+ * missing heartbeat (stale by definition). The next write overwrites
+ * it with a valid record.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30 * 60 * 1000; // 30 min
+export const DEFAULT_STALE_THRESHOLD_MS = 48 * 60 * 60 * 1000; // 48h
+export class MachineHeartbeat {
+    stateDir;
+    machineId;
+    heartbeatIntervalMs;
+    staleThresholdMs;
+    instarVersion;
+    now;
+    timer = null;
+    constructor(config) {
+        this.stateDir = config.stateDir;
+        this.machineId = config.machineId;
+        this.heartbeatIntervalMs = config.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+        this.staleThresholdMs = config.staleThresholdMs ?? DEFAULT_STALE_THRESHOLD_MS;
+        this.instarVersion = config.instarVersion;
+        this.now = config.now ?? (() => new Date());
+    }
+    /** Identity of THIS machine (read-only for routes that need it). */
+    get id() {
+        return this.machineId;
+    }
+    /** Write a heartbeat immediately and start the periodic timer. */
+    start() {
+        this.writeOnce();
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => this.writeOnce(), this.heartbeatIntervalMs);
+        // .unref() so heartbeat does not keep the process alive on shutdown.
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    /** Stop the periodic timer. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Write a single heartbeat. Public so server-startup paths can write
+     *  one before the first interval fires. */
+    writeOnce() {
+        this.ensureDir();
+        const record = {
+            machineId: this.machineId,
+            hostname: os.hostname(),
+            lastHeartbeatAt: this.now().toISOString(),
+            instarVersion: this.instarVersion,
+        };
+        const tmp = this.recordPath(this.machineId) + '.tmp';
+        fs.writeFileSync(tmp, JSON.stringify(record, null, 2), { mode: 0o644 });
+        fs.renameSync(tmp, this.recordPath(this.machineId));
+        return record;
+    }
+    /** Read the heartbeat for any machine. Returns null on missing or malformed. */
+    read(machineId) {
+        try {
+            const raw = fs.readFileSync(this.recordPath(machineId), 'utf-8');
+            const obj = JSON.parse(raw);
+            if (typeof obj.machineId !== 'string')
+                return null;
+            if (typeof obj.hostname !== 'string')
+                return null;
+            if (typeof obj.lastHeartbeatAt !== 'string')
+                return null;
+            return obj;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Is the heartbeat for `machineId` stale?
+     *
+     * Returns true when:
+     *   - the heartbeat file is missing
+     *   - the heartbeat file is malformed (defense-in-depth)
+     *   - `lastHeartbeatAt` is older than `staleThresholdMs` ago
+     *
+     * Returns false when the heartbeat is within the threshold.
+     */
+    isStale(machineId) {
+        const r = this.read(machineId);
+        if (!r)
+            return true;
+        const t = Date.parse(r.lastHeartbeatAt);
+        if (!Number.isFinite(t))
+            return true;
+        return this.now().getTime() - t > this.staleThresholdMs;
+    }
+    /** List all known heartbeats (one per machine). */
+    listAll() {
+        this.ensureDir();
+        const entries = fs.readdirSync(this.dirPath()).filter((n) => n.endsWith('.json'));
+        const out = [];
+        for (const name of entries) {
+            const r = this.read(name.replace(/\.json$/, ''));
+            if (r)
+                out.push(r);
+        }
+        return out;
+    }
+    ensureDir() {
+        const p = this.dirPath();
+        if (!fs.existsSync(p))
+            fs.mkdirSync(p, { recursive: true });
+    }
+    dirPath() {
+        return path.join(this.stateDir, 'machine-health');
+    }
+    recordPath(machineId) {
+        // Sanitize: only [A-Za-z0-9_-] allowed in file names. Anything else
+        // gets URL-encoded so a stray slash or `..` can't escape.
+        const safe = machineId.replace(/[^A-Za-z0-9_-]/g, (c) => `%${c.charCodeAt(0).toString(16).padStart(2, '0')}`);
+        return path.join(this.dirPath(), `${safe}.json`);
+    }
+}
+//# sourceMappingURL=MachineHeartbeat.js.map

package/dist/core/MachineHeartbeat.js.map

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

package/dist/core/ProjectAutoAdvancePoller.d.ts

@@ -0,0 +1,107 @@
+/**
+ * ProjectAutoAdvancePoller — periodic scan for project rounds whose
+ * `autoAdvanceAt` has elapsed and that pass the runner's preflight.
+ *
+ * Spec: docs/specs/PROJECT-SCOPE-SPEC.md § Phase 1.5 ("Auto-advance
+ * polling").
+ *
+ * Filter (server-side, NOT a full ledger scan):
+ *   - `kind: 'project'`
+ *   - `status: 'active'`
+ *   - has at least one round with `autoAdvanceAt <= now`
+ *   - `unacknowledgedAdvanceCount < 2` (cap brake)
+ *   - `ownerMachineId` matches OR is empty AND no other machine has
+ *     claimed (the heartbeat staleness check is the claim-flow's
+ *     responsibility, not the poller's)
+ *   - the project lock is not held
+ *
+ * On fire:
+ *   1. Run `ProjectRoundRunner.preflight(projectId, nextRoundIdx)`.
+ *   2. If preflight rejects, surface to telemetry + leave
+ *      `autoAdvanceAt` in place so a future scan can retry — UNLESS
+ *      the rejection is structural (`FIRST_LAUNCH_ACK_REQUIRED`,
+ *      `UNACKED_ADVANCES_OVER_CAP`, `PROJECT_INACTIVE`,
+ *      `PROJECT_HALTED`), in which case we clear `autoAdvanceAt`
+ *      (no point retrying) and increment a structural-skip counter.
+ *   3. If preflight passes, increment `unacknowledgedAdvanceCount` and
+ *      clear the current round's `autoAdvanceAt`. The autonomous
+ *      run loop (next PR) is the one that actually starts the round
+ *      work; for this PR, we record the bookkeeping move and rely on
+ *      a future `run()` consumer.
+ *
+ * Why we don't run the actual round here: the autonomous-delegating
+ * run loop with worktrees, dynamic stop revalidation, and SIGTERM
+ * handling ships separately. Splitting the poller out lets the bookkeeping
+ * move ship today and exercises the filter logic end-to-end.
+ *
+ * Polling cadence is caller-driven (the existing scheduler `nextCheckAt`
+ * tick or a direct `tick()` call from a test).
+ */
+import type { InitiativeTracker } from './InitiativeTracker.js';
+import type { ProjectRoundRunner } from './ProjectRoundRunner.js';
+export interface PollerTickResult {
+    scanned: number;
+    fired: string[];
+    rejected: Array<{
+        projectId: string;
+        code: string;
+        reason: string;
+    }>;
+    cleared: string[];
+    /** projectIds where the optional executor was launched (fire-and-forget). */
+    executed: string[];
+    /** Errors raised by the executor (settled async; one entry per failed launch). */
+    executorErrors: Array<{
+        projectId: string;
+        roundIndex: number;
+        error: string;
+    }>;
+}
+/**
+ * Optional fire-and-forget executor invoked after a successful preflight
+ * + bookkeeping move. When set, the poller launches the round run
+ * asynchronously. The executor is responsible for its own lock acquisition
+ * (`ProjectRoundLock`) so two ticks that both pass preflight cannot
+ * spawn two concurrent runs for the same project.
+ *
+ * The promise is NOT awaited inside `tick()` — the poller's job is
+ * scanning, not blocking on multi-minute runs. Errors from the executor
+ * are caught and surfaced via `result.executorErrors` so the next tick
+ * has a record of what happened.
+ */
+export type ProjectRoundExecutor = (input: {
+    projectId: string;
+    roundIndex: number;
+}) => Promise<void>;
+export interface ProjectAutoAdvancePollerConfig {
+    tracker: InitiativeTracker;
+    runner: ProjectRoundRunner;
+    /** Stable machine id (used for ownerMachineId comparison). */
+    machineId: string;
+    now?: () => Date;
+    /**
+     * Optional async executor that actually launches the round work. When
+     * omitted, the poller does bookkeeping only (PR-5-era behavior). When
+     * present, fire-and-forget invocation after `bookKeepFire`.
+     */
+    executor?: ProjectRoundExecutor;
+}
+export declare class ProjectAutoAdvancePoller {
+    private tracker;
+    private runner;
+    private machineId;
+    private now;
+    private executor?;
+    /** Tracks in-flight executor invocations so a slow run doesn't get relaunched on the next tick. */
+    private inFlight;
+    constructor(config: ProjectAutoAdvancePollerConfig);
+    /** Test/diagnostic helper: how many executor launches are still settling. */
+    inFlightCount(): number;
+    /** Run one pass over all eligible projects. */
+    tick(): Promise<PollerTickResult>;
+    /** Fire-and-forget executor launch. Errors are captured into `result.executorErrors`. */
+    private launchExecutor;
+    private clearAutoAdvance;
+    private bookKeepFire;
+}
+//# sourceMappingURL=ProjectAutoAdvancePoller.d.ts.map

package/dist/core/ProjectAutoAdvancePoller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectAutoAdvancePoller.d.ts","sourceRoot":"","sources":["../../src/core/ProjectAutoAdvancePoller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAc,MAAM,wBAAwB,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAmB,MAAM,yBAAyB,CAAC;AAEnF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,kFAAkF;IAClF,cAAc,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpB,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CACjC;AAcD,qBAAa,wBAAwB;IACnC,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,GAAG,CAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,CAAuB;IACxC,mGAAmG;IACnG,OAAO,CAAC,QAAQ,CAA0B;gBAE9B,MAAM,EAAE,8BAA8B;IAQlD,6EAA6E;IAC7E,aAAa,IAAI,MAAM;IAIvB,+CAA+C;IACzC,IAAI,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAsEvC,yFAAyF;IACzF,OAAO,CAAC,cAAc;YAgBR,gBAAgB;YAWhB,YAAY;CAe3B"}

package/dist/core/ProjectAutoAdvancePoller.js

@@ -0,0 +1,176 @@
+/**
+ * ProjectAutoAdvancePoller — periodic scan for project rounds whose
+ * `autoAdvanceAt` has elapsed and that pass the runner's preflight.
+ *
+ * Spec: docs/specs/PROJECT-SCOPE-SPEC.md § Phase 1.5 ("Auto-advance
+ * polling").
+ *
+ * Filter (server-side, NOT a full ledger scan):
+ *   - `kind: 'project'`
+ *   - `status: 'active'`
+ *   - has at least one round with `autoAdvanceAt <= now`
+ *   - `unacknowledgedAdvanceCount < 2` (cap brake)
+ *   - `ownerMachineId` matches OR is empty AND no other machine has
+ *     claimed (the heartbeat staleness check is the claim-flow's
+ *     responsibility, not the poller's)
+ *   - the project lock is not held
+ *
+ * On fire:
+ *   1. Run `ProjectRoundRunner.preflight(projectId, nextRoundIdx)`.
+ *   2. If preflight rejects, surface to telemetry + leave
+ *      `autoAdvanceAt` in place so a future scan can retry — UNLESS
+ *      the rejection is structural (`FIRST_LAUNCH_ACK_REQUIRED`,
+ *      `UNACKED_ADVANCES_OVER_CAP`, `PROJECT_INACTIVE`,
+ *      `PROJECT_HALTED`), in which case we clear `autoAdvanceAt`
+ *      (no point retrying) and increment a structural-skip counter.
+ *   3. If preflight passes, increment `unacknowledgedAdvanceCount` and
+ *      clear the current round's `autoAdvanceAt`. The autonomous
+ *      run loop (next PR) is the one that actually starts the round
+ *      work; for this PR, we record the bookkeeping move and rely on
+ *      a future `run()` consumer.
+ *
+ * Why we don't run the actual round here: the autonomous-delegating
+ * run loop with worktrees, dynamic stop revalidation, and SIGTERM
+ * handling ships separately. Splitting the poller out lets the bookkeeping
+ * move ship today and exercises the filter logic end-to-end.
+ *
+ * Polling cadence is caller-driven (the existing scheduler `nextCheckAt`
+ * tick or a direct `tick()` call from a test).
+ */
+/** Reject codes that mean "stop retrying" — clear autoAdvanceAt. */
+const STRUCTURAL_REJECTS = new Set([
+    'FIRST_LAUNCH_ACK_REQUIRED',
+    'UNACKED_ADVANCES_OVER_CAP',
+    'ROUND_ACK_GAP_TOO_LARGE',
+    'PROJECT_INACTIVE',
+    'PROJECT_HALTED',
+    'PROJECT_NOT_PROJECT_KIND',
+    'PROJECT_NOT_FOUND',
+    'TARGET_REPO_PATH_INVALID',
+]);
+export class ProjectAutoAdvancePoller {
+    tracker;
+    runner;
+    machineId;
+    now;
+    executor;
+    /** Tracks in-flight executor invocations so a slow run doesn't get relaunched on the next tick. */
+    inFlight = new Set();
+    constructor(config) {
+        this.tracker = config.tracker;
+        this.runner = config.runner;
+        this.machineId = config.machineId;
+        this.now = config.now ?? (() => new Date());
+        this.executor = config.executor;
+    }
+    /** Test/diagnostic helper: how many executor launches are still settling. */
+    inFlightCount() {
+        return this.inFlight.size;
+    }
+    /** Run one pass over all eligible projects. */
+    async tick() {
+        const result = {
+            scanned: 0,
+            fired: [],
+            rejected: [],
+            cleared: [],
+            executed: [],
+            executorErrors: [],
+        };
+        // Filter server-side: kind=project + status=active. (The tracker's
+        // `list` already supports the kind filter.)
+        const projects = this.tracker.list({ kind: 'project', status: 'active' });
+        const nowMs = this.now().getTime();
+        for (const project of projects) {
+            result.scanned++;
+            // Step 1: ownership filter — skip projects this machine doesn't own.
+            // Empty ownerMachineId is treated as "any machine can claim by
+            // running" — but for auto-advance we require explicit ownership
+            // so two machines don't race. Claim-ownership endpoint is the
+            // explicit takeover path.
+            if (project.ownerMachineId && project.ownerMachineId !== this.machineId)
+                continue;
+            // Step 2: cap brake — over-cap projects never auto-fire.
+            const unacked = project.unacknowledgedAdvanceCount ?? 0;
+            if (unacked >= 2)
+                continue;
+            // Step 3: find the first round with autoAdvanceAt elapsed.
+            const rounds = project.rounds ?? [];
+            const roundIdx = rounds.findIndex((r) => {
+                const t = r.autoAdvanceAt ? Date.parse(r.autoAdvanceAt) : 0;
+                return Number.isFinite(t) && t > 0 && t <= nowMs && (r.status ?? 'pending') === 'pending';
+            });
+            if (roundIdx === -1)
+                continue;
+            // Step 4: preflight via the runner.
+            const pre = this.runner.preflight(project.id, roundIdx);
+            if (!pre.ok) {
+                result.rejected.push({ projectId: project.id, code: pre.code, reason: pre.reason });
+                if (STRUCTURAL_REJECTS.has(pre.code)) {
+                    // Clear the timestamp; no point in retrying until structural
+                    // state changes (which will happen via a different code path —
+                    // user ack, halt-then-resume, etc.).
+                    await this.clearAutoAdvance(project, roundIdx);
+                    result.cleared.push(project.id);
+                }
+                continue;
+            }
+            // Step 5: bookkeeping move — increment unacked counter, clear
+            // current round's autoAdvanceAt so we don't re-fire on the next
+            // tick.
+            await this.bookKeepFire(project, roundIdx);
+            result.fired.push(project.id);
+            // Step 6: fire-and-forget executor launch (if configured).
+            // The executor (ProjectRoundExecution.runRound) acquires its own
+            // lock, so a duplicate-launch on a stuck tick would resolve to
+            // LOCK_HELD inside the runner. We additionally guard with
+            // `inFlight` so we don't even attempt while one is settling.
+            if (this.executor && !this.inFlight.has(project.id)) {
+                result.executed.push(project.id);
+                this.launchExecutor(project.id, roundIdx, result);
+            }
+        }
+        return result;
+    }
+    /** Fire-and-forget executor launch. Errors are captured into `result.executorErrors`. */
+    launchExecutor(projectId, roundIndex, result) {
+        if (!this.executor)
+            return;
+        this.inFlight.add(projectId);
+        void this.executor({ projectId, roundIndex })
+            .catch((err) => {
+            result.executorErrors.push({
+                projectId,
+                roundIndex,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        })
+            .finally(() => {
+            this.inFlight.delete(projectId);
+        });
+    }
+    async clearAutoAdvance(project, roundIdx) {
+        const rounds = (project.rounds ?? []).map((r, i) => i === roundIdx ? { ...r, autoAdvanceAt: undefined } : r);
+        try {
+            await this.tracker.update(project.id, { rounds, ifMatch: project.version });
+        }
+        catch {
+            // OCC race — another writer beat us. Next tick will see the new state.
+        }
+    }
+    async bookKeepFire(project, roundIdx) {
+        const rounds = (project.rounds ?? []).map((r, i) => i === roundIdx ? { ...r, autoAdvanceAt: undefined } : r);
+        const nextUnacked = (project.unacknowledgedAdvanceCount ?? 0) + 1;
+        try {
+            await this.tracker.update(project.id, {
+                rounds,
+                unacknowledgedAdvanceCount: nextUnacked,
+                ifMatch: project.version,
+            });
+        }
+        catch {
+            // OCC race — next tick will retry.
+        }
+    }
+}
+//# sourceMappingURL=ProjectAutoAdvancePoller.js.map

package/dist/core/ProjectAutoAdvancePoller.js.map

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