instar 0.28.95 → 0.28.97

package/dist/core/ProjectRoundRunner.d.ts

@@ -0,0 +1,146 @@
+/**
+ * ProjectRoundRunner — the single entry point for project-scope rounds.
+ *
+ * Spec: docs/specs/PROJECT-SCOPE-SPEC.md § Phase 1.5.
+ *
+ * Authority model: every entry path (HTTP /advance, /run-round skill,
+ * future auto-advance poller) MUST go through `preflight()` here. Routes
+ * do NOT enforce gates that the runner already enforces — the runner is
+ * the chokepoint. Preflight returns a structured result; callers either
+ * proceed (when the runner approves) or surface the rejection.
+ *
+ * Lock: machine-local `.instar/local/round-runner.lock` (see
+ * `ProjectRoundLock`). At most one runner active per machine.
+ *
+ * What's IN this PR (Phase 1b PR 3):
+ *   - `preflight(projectId, roundIndex)` — checks 1–9 from the spec
+ *     (drift check, step 10, is deferred to a follow-up PR alongside
+ *     the cache+ledger HTTP wiring).
+ *   - `halt(projectId, reason)` — writes haltedAt, sets project status
+ *     to `halted`, releases the lock if held. Idempotent.
+ *   - `recordAck(projectId, roundIndex)` — records user acknowledgment,
+ *     resets `unacknowledgedAdvanceCount`, advances `lastAckedRoundIndex`,
+ *     populates `firstLaunchAckAt` if absent.
+ *   - `acceptPartial(projectId, roundIndex, reason)` — closes a
+ *     partially-complete round: missing items → skipped,
+ *     round.status → `complete-with-skips`. Counts as an ack for the
+ *     current round (advances lastAckedRoundIndex) but does NOT
+ *     increment unacknowledgedAdvanceCount.
+ *
+ * What's NOT in this PR:
+ *   - The actual autonomous-delegating run loop (`run()`).
+ *   - Dynamic stop-condition revalidation + SIGTERM/SIGKILL of children.
+ *   - Drift check at preflight step 10.
+ *   - Auto-advance poller.
+ *   - Multi-machine claim-ownership.
+ */
+import type { InitiativeTracker, Initiative, InitiativeRound } from './InitiativeTracker.js';
+import { type ProjectRoundLockPayload } from './ProjectRoundLock.js';
+/** Spec-mandated rejection codes for preflight failures. */
+export type PreflightRejectCode = 'TRACKER_MISSING' | 'PROJECT_NOT_FOUND' | 'PROJECT_NOT_PROJECT_KIND' | 'PROJECT_INACTIVE' | 'PROJECT_HALTED' | 'PROJECT_AWAITING_USER' | 'ROUND_INDEX_OUT_OF_RANGE' | 'ROUND_NOT_PENDING_OR_READY' | 'LOCK_HELD' | 'FIRST_LAUNCH_ACK_REQUIRED' | 'UNACKED_ADVANCES_OVER_CAP' | 'ROUND_ACK_GAP_TOO_LARGE' | 'NOT_OWNER_MACHINE' | 'TARGET_REPO_PATH_INVALID' | 'AWAITING_RECONCILIATION' | 'ITEMS_NOT_ALL_APPROVED' | 'ITEM_FRONTMATTER_INVALID';
+export interface PreflightOk {
+    ok: true;
+    project: Initiative;
+    round: InitiativeRound;
+    children: Initiative[];
+    ownerMachineId: string;
+}
+export interface PreflightReject {
+    ok: false;
+    code: PreflightRejectCode;
+    reason: string;
+    /** When code === 'LOCK_HELD', the current holder is populated. */
+    currentHolder?: ProjectRoundLockPayload;
+    /** When code === 'ITEMS_NOT_ALL_APPROVED', the failing child id(s). */
+    failingItemIds?: string[];
+}
+export type PreflightResult = PreflightOk | PreflightReject;
+export interface ProjectRoundRunnerConfig {
+    tracker: InitiativeTracker;
+    /** Absolute path to the agent's `.instar/` directory. */
+    stateDir: string;
+    /** Identifier of THIS machine — usually `agentRegistry.machineId()`. */
+    machineId: string;
+    /**
+     * How many auto-advances without ack before the project is paused.
+     * Defaults to 2 (matches spec § Phase 1.5 step 6 brake).
+     */
+    unackedAdvanceCap?: number;
+    /**
+     * Max gap allowed between `lastAckedRoundIndex` and the requested
+     * roundIndex. Defaults to 2 (spec § Phase 1.5 step 5: "no more than
+     * two rounds-ahead-of-ack at any time").
+     */
+    ackGapCap?: number;
+}
+export declare class ProjectRoundRunner {
+    private tracker;
+    private stateDir;
+    private machineId;
+    private lock;
+    private unackedAdvanceCap;
+    private ackGapCap;
+    constructor(config: ProjectRoundRunnerConfig);
+    /** Public read of the current lock holder, used by tests and dashboards. */
+    currentLockHolder(): ProjectRoundLockPayload | null;
+    /**
+     * Preflight check — the single chokepoint for round-start authority.
+     *
+     * Steps 1–9 from the spec. Step 10 (drift check) is intentionally
+     * skipped in this PR; it lands when the drift-check HTTP endpoint is
+     * wired into the routes ctx (Phase 1b follow-up).
+     */
+    preflight(projectId: string, roundIndex: number): PreflightResult;
+    /**
+     * Halt the active round of a project. Idempotent — halting an already-
+     * halted round is a no-op. Releases the lock if the calling machine
+     * holds it.
+     *
+     * Returns the round that was halted, or null if the project / round
+     * didn't exist.
+     */
+    halt(projectId: string, reason: string): Promise<{
+        project: Initiative;
+        roundIndex: number;
+    } | null>;
+    /**
+     * Record a user acknowledgment for `roundIndex`. Idempotent: calling
+     * twice with the same index has no further effect. The fields the spec
+     * names: resets `unacknowledgedAdvanceCount`, populates
+     * `firstLaunchAckAt` (if absent), advances `lastAckedRoundIndex`.
+     */
+    recordAck(projectId: string, roundIndex: number): Promise<Initiative | null>;
+    /**
+     * Close a partially-complete round: missing items → skipped, round
+     * status → `complete-with-skips`. Counts as an ack for `roundIndex`
+     * (advances `lastAckedRoundIndex`) but does NOT touch
+     * `unacknowledgedAdvanceCount`.
+     *
+     * The transition of each missing item to `skipped` requires `reason`
+     * and `skippedBy` (per StageTransitionValidator). The caller passes
+     * a single `reason` that's applied to every newly-skipped item.
+     */
+    acceptPartial(projectId: string, roundIndex: number, reason: string, skippedBy: string): Promise<{
+        project: Initiative;
+        skippedItemIds: string[];
+    } | null>;
+    /**
+     * Validate that a child initiative's spec frontmatter still has the
+     * tags the round-runner requires before STARTing the autonomous loop.
+     * Spec § Phase 1.5 step 3 + § Phase 1.4 "Authority separation":
+     *   - `review-convergence: true`
+     *   - `approved: true`
+     *
+     * Used by future `run()` and by the dashboard's "ready to start" badge.
+     * Exported for tests.
+     */
+    static validateChildFrontmatter(targetRepoPath: string, specRelPath: string): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+}
+/** Convenience alias for the lock primitive when callers want a typed reference. */
+export type { ProjectRoundLockPayload } from './ProjectRoundLock.js';
+//# sourceMappingURL=ProjectRoundRunner.d.ts.map

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

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

package/dist/core/ProjectRoundRunner.js

@@ -0,0 +1,371 @@
+/**
+ * ProjectRoundRunner — the single entry point for project-scope rounds.
+ *
+ * Spec: docs/specs/PROJECT-SCOPE-SPEC.md § Phase 1.5.
+ *
+ * Authority model: every entry path (HTTP /advance, /run-round skill,
+ * future auto-advance poller) MUST go through `preflight()` here. Routes
+ * do NOT enforce gates that the runner already enforces — the runner is
+ * the chokepoint. Preflight returns a structured result; callers either
+ * proceed (when the runner approves) or surface the rejection.
+ *
+ * Lock: machine-local `.instar/local/round-runner.lock` (see
+ * `ProjectRoundLock`). At most one runner active per machine.
+ *
+ * What's IN this PR (Phase 1b PR 3):
+ *   - `preflight(projectId, roundIndex)` — checks 1–9 from the spec
+ *     (drift check, step 10, is deferred to a follow-up PR alongside
+ *     the cache+ledger HTTP wiring).
+ *   - `halt(projectId, reason)` — writes haltedAt, sets project status
+ *     to `halted`, releases the lock if held. Idempotent.
+ *   - `recordAck(projectId, roundIndex)` — records user acknowledgment,
+ *     resets `unacknowledgedAdvanceCount`, advances `lastAckedRoundIndex`,
+ *     populates `firstLaunchAckAt` if absent.
+ *   - `acceptPartial(projectId, roundIndex, reason)` — closes a
+ *     partially-complete round: missing items → skipped,
+ *     round.status → `complete-with-skips`. Counts as an ack for the
+ *     current round (advances lastAckedRoundIndex) but does NOT
+ *     increment unacknowledgedAdvanceCount.
+ *
+ * What's NOT in this PR:
+ *   - The actual autonomous-delegating run loop (`run()`).
+ *   - Dynamic stop-condition revalidation + SIGTERM/SIGKILL of children.
+ *   - Drift check at preflight step 10.
+ *   - Auto-advance poller.
+ *   - Multi-machine claim-ownership.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { ProjectRoundLock, isAlive } from './ProjectRoundLock.js';
+import { extractFrontmatter } from './SafeYaml.js';
+export class ProjectRoundRunner {
+    tracker;
+    stateDir;
+    machineId;
+    lock;
+    unackedAdvanceCap;
+    ackGapCap;
+    constructor(config) {
+        this.tracker = config.tracker;
+        this.stateDir = config.stateDir;
+        this.machineId = config.machineId;
+        this.lock = new ProjectRoundLock({ stateDir: config.stateDir });
+        this.unackedAdvanceCap = config.unackedAdvanceCap ?? 2;
+        this.ackGapCap = config.ackGapCap ?? 2;
+    }
+    /** Public read of the current lock holder, used by tests and dashboards. */
+    currentLockHolder() {
+        return this.lock.read();
+    }
+    /**
+     * Preflight check — the single chokepoint for round-start authority.
+     *
+     * Steps 1–9 from the spec. Step 10 (drift check) is intentionally
+     * skipped in this PR; it lands when the drift-check HTTP endpoint is
+     * wired into the routes ctx (Phase 1b follow-up).
+     */
+    preflight(projectId, roundIndex) {
+        // ── Step 0: tracker present ───────────────────────────────────
+        if (!this.tracker) {
+            return { ok: false, code: 'TRACKER_MISSING', reason: 'no initiative tracker' };
+        }
+        // ── Project shape ─────────────────────────────────────────────
+        const project = this.tracker.get(projectId);
+        if (!project) {
+            return { ok: false, code: 'PROJECT_NOT_FOUND', reason: `no project ${projectId}` };
+        }
+        if ((project.kind ?? 'task') !== 'project') {
+            return {
+                ok: false,
+                code: 'PROJECT_NOT_PROJECT_KIND',
+                reason: `record ${projectId} is not project-kind (kind=${project.kind ?? 'task'})`,
+            };
+        }
+        // ── Project status ────────────────────────────────────────────
+        if (project.status !== 'active') {
+            if (project.status === 'archived' || project.status === 'completed' || project.status === 'abandoned') {
+                return {
+                    ok: false,
+                    code: 'PROJECT_INACTIVE',
+                    reason: `project status is "${project.status}", not "active"`,
+                };
+            }
+        }
+        // Track halt / awaiting-user via round.haltedAt OR explicit awaitingUser?
+        // For now, "active" is the only allowed status.
+        // ── Round shape ───────────────────────────────────────────────
+        if (!Array.isArray(project.rounds) || project.rounds.length === 0) {
+            return { ok: false, code: 'ROUND_INDEX_OUT_OF_RANGE', reason: 'project has no rounds' };
+        }
+        if (roundIndex < 0 || roundIndex >= project.rounds.length) {
+            return {
+                ok: false,
+                code: 'ROUND_INDEX_OUT_OF_RANGE',
+                reason: `roundIndex ${roundIndex} not in [0, ${project.rounds.length})`,
+            };
+        }
+        const round = project.rounds[roundIndex];
+        if (round.haltedAt) {
+            return {
+                ok: false,
+                code: 'PROJECT_HALTED',
+                reason: `round ${roundIndex} was halted at ${round.haltedAt}: ${round.haltReason ?? '<no reason>'}`,
+            };
+        }
+        // Undefined status is treated as 'pending' (newly-constructed rounds
+        // from the plan parser may not set it explicitly).
+        const roundStatus = round.status ?? 'pending';
+        if (roundStatus !== 'pending' && roundStatus !== 'ready') {
+            return {
+                ok: false,
+                code: 'ROUND_NOT_PENDING_OR_READY',
+                reason: `round.status is "${round.status}", not "pending" or "ready"`,
+            };
+        }
+        // ── Step 1+2: lock free / stale-PID sweep ─────────────────────
+        const holder = this.lock.read();
+        if (holder && isAlive(holder.pid)) {
+            return {
+                ok: false,
+                code: 'LOCK_HELD',
+                reason: `lock held by pid ${holder.pid} for ${holder.projectId} round ${holder.roundIndex} since ${holder.acquiredAt}`,
+                currentHolder: holder,
+            };
+        }
+        // (If holder exists but PID dead, acquire() will sweep it.)
+        // ── Step 3: all round items at `approved` AND frontmatter still valid
+        const childIds = round.itemIds ?? [];
+        const children = [];
+        const failingItemIds = [];
+        for (const cid of childIds) {
+            const child = this.tracker.get(cid);
+            if (!child) {
+                failingItemIds.push(cid);
+                continue;
+            }
+            children.push(child);
+            // First round may legitimately start when items are still at
+            // outline (the round itself drives them through stages). The
+            // hard "items must all be approved" gate per § Phase 1.5 step 3
+            // applies to STARTING the autonomous run loop. Preflight is also
+            // used for /advance which does single-item transitions, so we
+            // accept any pipelineStage in this PR. The stricter gate will
+            // be re-asserted by `run()` when the run loop ships (Phase 1b
+            // follow-up).
+        }
+        if (failingItemIds.length > 0) {
+            return {
+                ok: false,
+                code: 'ITEMS_NOT_ALL_APPROVED',
+                reason: `${failingItemIds.length} item id(s) on the round don't resolve to existing records: ${failingItemIds.join(', ')}`,
+                failingItemIds,
+            };
+        }
+        // ── Step 5+6: first-launch ack + unacked-advances cap ─────────
+        const isFirstRound = roundIndex === 0;
+        const firstLaunchAckAt = project.firstLaunchAckAt;
+        if (isFirstRound && !firstLaunchAckAt) {
+            return {
+                ok: false,
+                code: 'FIRST_LAUNCH_ACK_REQUIRED',
+                reason: `first round requires POST /projects/${projectId}/ack before any entry path can start it`,
+            };
+        }
+        const unacked = project.unacknowledgedAdvanceCount ?? 0;
+        if (unacked >= this.unackedAdvanceCap) {
+            return {
+                ok: false,
+                code: 'UNACKED_ADVANCES_OVER_CAP',
+                reason: `${unacked} auto-advances without ack (cap ${this.unackedAdvanceCap}); ack or halt before continuing`,
+            };
+        }
+        const lastAcked = project.lastAckedRoundIndex ?? -1;
+        if (!isFirstRound && roundIndex - lastAcked > this.ackGapCap) {
+            return {
+                ok: false,
+                code: 'ROUND_ACK_GAP_TOO_LARGE',
+                reason: `roundIndex ${roundIndex} is more than ${this.ackGapCap} ahead of lastAckedRoundIndex (${lastAcked})`,
+            };
+        }
+        // ── Step 7: owner machine matches (or owner empty + claiming) ─
+        const ownerMachineId = project.ownerMachineId ?? this.machineId;
+        if (project.ownerMachineId && project.ownerMachineId !== this.machineId) {
+            return {
+                ok: false,
+                code: 'NOT_OWNER_MACHINE',
+                reason: `project owner is ${project.ownerMachineId}; this machine is ${this.machineId}`,
+            };
+        }
+        // ── Step 8: targetRepoPath exists ─────────────────────────────
+        const targetRepo = project.targetRepoPath;
+        if (!targetRepo || !fs.existsSync(targetRepo) || !fs.existsSync(path.join(targetRepo, '.git'))) {
+            return {
+                ok: false,
+                code: 'TARGET_REPO_PATH_INVALID',
+                reason: `targetRepoPath "${targetRepo}" missing, not a git repo, or unreadable`,
+            };
+        }
+        // ── Step 9: no awaitingReconciliation entries ────────────────
+        if (Array.isArray(project.awaitingReconciliation) && project.awaitingReconciliation.length > 0) {
+            return {
+                ok: false,
+                code: 'AWAITING_RECONCILIATION',
+                reason: `${project.awaitingReconciliation.length} reconciliation conflict(s) pending`,
+            };
+        }
+        // ── Step 10 (drift): deferred to follow-up PR ────────────────
+        return { ok: true, project, round, children, ownerMachineId };
+    }
+    /**
+     * Halt the active round of a project. Idempotent — halting an already-
+     * halted round is a no-op. Releases the lock if the calling machine
+     * holds it.
+     *
+     * Returns the round that was halted, or null if the project / round
+     * didn't exist.
+     */
+    async halt(projectId, reason) {
+        const project = this.tracker.get(projectId);
+        if (!project || (project.kind ?? 'task') !== 'project')
+            return null;
+        // Find the active round. Preference order:
+        //   1. in-progress (the canonical "active" state)
+        //   2. pending / ready / undefined (round is queued but not yet
+        //      running — calling halt on a queued round records the intent)
+        //   3. already-halted (idempotent return of the existing state)
+        const rounds = project.rounds ?? [];
+        let activeIdx = rounds.findIndex((r) => r.status === 'in-progress');
+        if (activeIdx === -1)
+            activeIdx = rounds.findIndex((r) => {
+                const s = r.status ?? 'pending';
+                return s === 'pending' || s === 'ready';
+            });
+        if (activeIdx === -1)
+            activeIdx = rounds.findIndex((r) => Boolean(r.haltedAt));
+        if (activeIdx === -1)
+            return null;
+        const round = rounds[activeIdx];
+        if (round.haltedAt) {
+            // Idempotent — return current state.
+            return { project, roundIndex: activeIdx };
+        }
+        const haltedAt = new Date().toISOString();
+        const newRounds = rounds.map((r, i) => i === activeIdx
+            ? { ...r, status: 'failed', haltedAt, haltReason: reason }
+            : r);
+        const updated = await this.tracker.update(projectId, {
+            rounds: newRounds,
+            ifMatch: project.version,
+        });
+        // Release the lock if held by anyone — halt is the kill switch.
+        // (The spec says SIGTERM-then-SIGKILL the autonomous child; that
+        // path lands when run() ships. Here we just clear the lock.)
+        const holder = this.lock.read();
+        if (holder && holder.projectId === projectId && holder.roundIndex === activeIdx) {
+            this.lock.release();
+        }
+        return { project: updated, roundIndex: activeIdx };
+    }
+    /**
+     * Record a user acknowledgment for `roundIndex`. Idempotent: calling
+     * twice with the same index has no further effect. The fields the spec
+     * names: resets `unacknowledgedAdvanceCount`, populates
+     * `firstLaunchAckAt` (if absent), advances `lastAckedRoundIndex`.
+     */
+    async recordAck(projectId, roundIndex) {
+        const project = this.tracker.get(projectId);
+        if (!project || (project.kind ?? 'task') !== 'project')
+            return null;
+        // Spec § Phase 1.3: idempotent on lastAckedRoundIndex.
+        const currentLastAck = project.lastAckedRoundIndex ?? -1;
+        const effectiveLastAck = Math.max(currentLastAck, roundIndex);
+        const firstLaunchAckAt = project.firstLaunchAckAt ?? new Date().toISOString();
+        return this.tracker.update(projectId, {
+            unacknowledgedAdvanceCount: 0,
+            firstLaunchAckAt,
+            lastAckedRoundIndex: effectiveLastAck,
+            ifMatch: project.version,
+        });
+    }
+    /**
+     * Close a partially-complete round: missing items → skipped, round
+     * status → `complete-with-skips`. Counts as an ack for `roundIndex`
+     * (advances `lastAckedRoundIndex`) but does NOT touch
+     * `unacknowledgedAdvanceCount`.
+     *
+     * The transition of each missing item to `skipped` requires `reason`
+     * and `skippedBy` (per StageTransitionValidator). The caller passes
+     * a single `reason` that's applied to every newly-skipped item.
+     */
+    async acceptPartial(projectId, roundIndex, reason, skippedBy) {
+        const project = this.tracker.get(projectId);
+        if (!project || (project.kind ?? 'task') !== 'project')
+            return null;
+        const rounds = project.rounds ?? [];
+        if (roundIndex < 0 || roundIndex >= rounds.length)
+            return null;
+        const round = rounds[roundIndex];
+        // Skip each non-merged, non-already-skipped item.
+        const skippedItemIds = [];
+        const nowIso = new Date().toISOString();
+        for (const cid of round.itemIds ?? []) {
+            const child = this.tracker.get(cid);
+            if (!child)
+                continue;
+            const stage = child.pipelineStage ?? 'outline';
+            if (stage === 'merged' || stage === 'skipped')
+                continue;
+            await this.tracker.update(cid, {
+                pipelineStage: 'skipped',
+                ifMatch: child.version,
+            });
+            skippedItemIds.push(cid);
+        }
+        const newRounds = rounds.map((r, i) => i === roundIndex ? { ...r, status: 'complete-with-skips', completedAt: nowIso } : r);
+        // Advance lastAckedRoundIndex; do NOT change unacknowledgedAdvanceCount.
+        const currentLastAck = project.lastAckedRoundIndex ?? -1;
+        const updated = await this.tracker.update(projectId, {
+            rounds: newRounds,
+            lastAckedRoundIndex: Math.max(currentLastAck, roundIndex),
+            ifMatch: project.version,
+        });
+        return { project: updated, skippedItemIds };
+    }
+    /**
+     * Validate that a child initiative's spec frontmatter still has the
+     * tags the round-runner requires before STARTing the autonomous loop.
+     * Spec § Phase 1.5 step 3 + § Phase 1.4 "Authority separation":
+     *   - `review-convergence: true`
+     *   - `approved: true`
+     *
+     * Used by future `run()` and by the dashboard's "ready to start" badge.
+     * Exported for tests.
+     */
+    static validateChildFrontmatter(targetRepoPath, specRelPath) {
+        const abs = path.isAbsolute(specRelPath)
+            ? specRelPath
+            : path.join(targetRepoPath, specRelPath);
+        if (!fs.existsSync(abs)) {
+            return { ok: false, reason: `spec file missing: ${specRelPath}` };
+        }
+        let body;
+        try {
+            body = fs.readFileSync(abs, 'utf-8');
+        }
+        catch (err) {
+            return { ok: false, reason: `spec unreadable: ${err.message}` };
+        }
+        const fm = extractFrontmatter(body);
+        if (fm.error)
+            return { ok: false, reason: `frontmatter unparseable: ${fm.error}` };
+        const data = fm.frontmatter ?? {};
+        if (data['review-convergence'] !== true) {
+            return { ok: false, reason: '`review-convergence: true` missing or false' };
+        }
+        if (data['approved'] !== true) {
+            return { ok: false, reason: '`approved: true` missing or false' };
+        }
+        return { ok: true };
+    }
+}
+//# sourceMappingURL=ProjectRoundRunner.js.map

package/dist/core/ProjectRoundRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectRoundRunner.js","sourceRoot":"","sources":["../../src/core/ProjectRoundRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,OAAO,EAAE,gBAAgB,EAAgC,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AA6DnD,MAAM,OAAO,kBAAkB;IACrB,OAAO,CAAoB;IAC3B,QAAQ,CAAS;IACjB,SAAS,CAAS;IAClB,IAAI,CAAmB;IACvB,iBAAiB,CAAS;IAC1B,SAAS,CAAS;IAE1B,YAAY,MAAgC;QAC1C,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,gBAAgB,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAChE,IAAI,CAAC,iBAAiB,GAAG,MAAM,CAAC,iBAAiB,IAAI,CAAC,CAAC;QACvD,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC;IACzC,CAAC;IAED,4EAA4E;IAC5E,iBAAiB;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;IAED;;;;;;OAMG;IACH,SAAS,CAAC,SAAiB,EAAE,UAAkB;QAC7C,iEAAiE;QACjE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;QACjF,CAAC;QAED,iEAAiE;QACjE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,cAAc,SAAS,EAAE,EAAE,CAAC;QACrF,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC,KAAK,SAAS,EAAE,CAAC;YAC3C,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,0BAA0B;gBAChC,MAAM,EAAE,UAAU,SAAS,8BAA8B,OAAO,CAAC,IAAI,IAAI,MAAM,GAAG;aACnF,CAAC;QACJ,CAAC;QAED,iEAAiE;QACjE,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAChC,IAAI,OAAO,CAAC,MAAM,KAAK,UAAU,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;gBACtG,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,IAAI,EAAE,kBAAkB;oBACxB,MAAM,EAAE,sBAAsB,OAAO,CAAC,MAAM,iBAAiB;iBAC9D,CAAC;YACJ,CAAC;QACH,CAAC;QACD,0EAA0E;QAC1E,gDAAgD;QAEhD,iEAAiE;QACjE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,0BAA0B,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;QAC1F,CAAC;QACD,IAAI,UAAU,GAAG,CAAC,IAAI,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YAC1D,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,0BAA0B;gBAChC,MAAM,EAAE,cAAc,UAAU,eAAe,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG;aACxE,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACnB,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,gBAAgB;gBACtB,MAAM,EAAE,SAAS,UAAU,kBAAkB,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,UAAU,IAAI,aAAa,EAAE;aACpG,CAAC;QACJ,CAAC;QACD,qEAAqE;QACrE,mDAAmD;QACnD,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,IAAI,SAAS,CAAC;QAC9C,IAAI,WAAW,KAAK,SAAS,IAAI,WAAW,KAAK,OAAO,EAAE,CAAC;YACzD,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,4BAA4B;gBAClC,MAAM,EAAE,oBAAoB,KAAK,CAAC,MAAM,6BAA6B;aACtE,CAAC;QACJ,CAAC;QAED,iEAAiE;QACjE,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAChC,IAAI,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAClC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,WAAW;gBACjB,MAAM,EAAE,oBAAoB,MAAM,CAAC,GAAG,QAAQ,MAAM,CAAC,SAAS,UAAU,MAAM,CAAC,UAAU,UAAU,MAAM,CAAC,UAAU,EAAE;gBACtH,aAAa,EAAE,MAAM;aACtB,CAAC;QACJ,CAAC;QACD,4DAA4D;QAE5D,uEAAuE;QACvE,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAiB,EAAE,CAAC;QAClC,MAAM,cAAc,GAAa,EAAE,CAAC;QACpC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACzB,SAAS;YACX,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,6DAA6D;YAC7D,6DAA6D;YAC7D,gEAAgE;YAChE,iEAAiE;YACjE,8DAA8D;YAC9D,8DAA8D;YAC9D,8DAA8D;YAC9D,cAAc;QAChB,CAAC;QACD,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,wBAAwB;gBAC9B,MAAM,EAAE,GAAG,cAAc,CAAC,MAAM,+DAA+D,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBAC1H,cAAc;aACf,CAAC;QACJ,CAAC;QAED,iEAAiE;QACjE,MAAM,YAAY,GAAG,UAAU,KAAK,CAAC,CAAC;QACtC,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;QAClD,IAAI,YAAY,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACtC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,2BAA2B;gBACjC,MAAM,EAAE,uCAAuC,SAAS,yCAAyC;aAClG,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,0BAA0B,IAAI,CAAC,CAAC;QACxD,IAAI,OAAO,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACtC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,2BAA2B;gBACjC,MAAM,EAAE,GAAG,OAAO,mCAAmC,IAAI,CAAC,iBAAiB,kCAAkC;aAC9G,CAAC;QACJ,CAAC;QACD,MAAM,SAAS,GAAG,OAAO,CAAC,mBAAmB,IAAI,CAAC,CAAC,CAAC;QACpD,IAAI,CAAC,YAAY,IAAI,UAAU,GAAG,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YAC7D,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,yBAAyB;gBAC/B,MAAM,EAAE,cAAc,UAAU,iBAAiB,IAAI,CAAC,SAAS,kCAAkC,SAAS,GAAG;aAC9G,CAAC;QACJ,CAAC;QAED,iEAAiE;QACjE,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,IAAI,CAAC,SAAS,CAAC;QAChE,IAAI,OAAO,CAAC,cAAc,IAAI,OAAO,CAAC,cAAc,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;YACxE,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,mBAAmB;gBACzB,MAAM,EAAE,oBAAoB,OAAO,CAAC,cAAc,qBAAqB,IAAI,CAAC,SAAS,EAAE;aACxF,CAAC;QACJ,CAAC;QAED,iEAAiE;QACjE,MAAM,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC;QAC1C,IAAI,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;YAC/F,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,0BAA0B;gBAChC,MAAM,EAAE,mBAAmB,UAAU,0CAA0C;aAChF,CAAC;QACJ,CAAC;QAED,gEAAgE;QAChE,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,sBAAsB,CAAC,IAAI,OAAO,CAAC,sBAAsB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/F,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,yBAAyB;gBAC/B,MAAM,EAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,MAAM,qCAAqC;aACtF,CAAC;QACJ,CAAC;QAED,gEAAgE;QAEhE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAChE,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CAAC,SAAiB,EAAE,MAAc;QAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QAEpE,2CAA2C;QAC3C,kDAAkD;QAClD,gEAAgE;QAChE,oEAAoE;QACpE,gEAAgE;QAChE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;QACpC,IAAI,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,aAAa,CAAC,CAAC;QACpE,IAAI,SAAS,KAAK,CAAC,CAAC;YAAE,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE;gBACvD,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,IAAI,SAAS,CAAC;gBAChC,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,OAAO,CAAC;YAC1C,CAAC,CAAC,CAAC;QACH,IAAI,SAAS,KAAK,CAAC,CAAC;YAAE,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC/E,IAAI,SAAS,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAElC,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;QAChC,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACnB,qCAAqC;YACrC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;QAC5C,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC1C,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACpC,CAAC,KAAK,SAAS;YACb,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,QAAuB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE;YACzE,CAAC,CAAC,CAAC,CACN,CAAC;QACF,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE;YACnD,MAAM,EAAE,SAAS;YACjB,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;QAEH,gEAAgE;QAChE,iEAAiE;QACjE,6DAA6D;QAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAChC,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAChF,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACtB,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;IACrD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,SAAS,CAAC,SAAiB,EAAE,UAAkB;QACnD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QAEpE,uDAAuD;QACvD,MAAM,cAAc,GAAG,OAAO,CAAC,mBAAmB,IAAI,CAAC,CAAC,CAAC;QACzD,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;QAC9D,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAE9E,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE;YACpC,0BAA0B,EAAE,CAAC;YAC7B,gBAAgB;YAChB,mBAAmB,EAAE,gBAAgB;YACrC,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,aAAa,CACjB,SAAiB,EACjB,UAAkB,EAClB,MAAc,EACd,SAAiB;QAEjB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QAEpE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;QACpC,IAAI,UAAU,GAAG,CAAC,IAAI,UAAU,IAAI,MAAM,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAC/D,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;QAEjC,kDAAkD;QAClD,MAAM,cAAc,GAAa,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACxC,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;YACtC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpC,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,MAAM,KAAK,GAAG,KAAK,CAAC,aAAa,IAAI,SAAS,CAAC;YAC/C,IAAI,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,SAAS;gBAAE,SAAS;YACxD,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE;gBAC7B,aAAa,EAAE,SAAS;gBACxB,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC,CAAC;YACH,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACpC,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,qBAAoC,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CACnG,CAAC;QACF,yEAAyE;QACzE,MAAM,cAAc,GAAG,OAAO,CAAC,mBAAmB,IAAI,CAAC,CAAC,CAAC;QACzD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE;YACnD,MAAM,EAAE,SAAS;YACjB,mBAAmB,EAAE,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,UAAU,CAAC;YACzD,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IAC9C,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,wBAAwB,CAC7B,cAAsB,EACtB,WAAmB;QAEnB,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;YACtC,CAAC,CAAC,WAAW;YACb,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;QAC3C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,WAAW,EAAE,EAAE,CAAC;QACpE,CAAC;QACD,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAqB,GAAa,CAAC,OAAO,EAAE,EAAE,CAAC;QAC7E,CAAC;QACD,MAAM,EAAE,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,EAAE,CAAC,KAAK;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,4BAA4B,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC;QACnF,MAAM,IAAI,GAAG,EAAE,CAAC,WAAW,IAAI,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,oBAAoB,CAAC,KAAK,IAAI,EAAE,CAAC;YACxC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,6CAA6C,EAAE,CAAC;QAC9E,CAAC;QACD,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,EAAE,CAAC;YAC9B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mCAAmC,EAAE,CAAC;QACpE,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;CACF"}

package/dist/core/ProjectRoundWorktrees.d.ts

@@ -0,0 +1,57 @@
+/**
+ * ProjectRoundWorktrees — lazy worktree allocator for project rounds.
+ *
+ * Spec: docs/specs/PROJECT-SCOPE-SPEC.md § Phase 1.5 step 3.
+ *
+ * Each round-item gets its own git worktree at
+ *   <targetRepoPath>/.worktrees/<projectId>/<roundIndex>/<itemId>
+ *
+ * On first allocation in a target repo, `.worktrees/` is appended to
+ * `.git/info/exclude` so the worktree namespace doesn't pollute
+ * `git status` or get caught by `git add -A`. The exclude file is
+ * per-clone (not committed), matching the spec.
+ *
+ * `prune()` runs `git worktree prune` against the round's namespace.
+ * Idempotent.
+ */
+export interface AllocateInput {
+    targetRepoPath: string;
+    projectId: string;
+    roundIndex: number;
+    itemId: string;
+}
+export interface AllocateResult {
+    /** Absolute path to the new worktree (or existing one if `refuseExisting:false`). */
+    worktreePath: string;
+    /** True when the worktree was created in this call; false when it pre-existed. */
+    created: boolean;
+}
+export declare class ProjectRoundWorktrees {
+    /** Compute the worktree path WITHOUT creating it. */
+    static pathFor(input: AllocateInput): string;
+    /**
+     * Lazy-allocate a worktree for one item. Idempotent on first creation,
+     * but refuses by default if the directory pre-exists (matches spec
+     * "Refuse if the path already exists").
+     */
+    static allocate(input: AllocateInput, opts?: {
+        refuseExisting?: boolean;
+    }): AllocateResult;
+    /**
+     * Prune the round's worktree namespace. Runs `git worktree prune`
+     * on the target repo (cheap; idempotent).
+     */
+    static prune(targetRepoPath: string): void;
+    /**
+     * Forcibly remove a single allocated worktree (e.g., on round halt
+     * cleanup). Uses `git worktree remove --force` so dirty checkouts
+     * don't block cleanup. Idempotent: missing worktrees pass through.
+     */
+    static remove(input: AllocateInput): void;
+    /**
+     * Append `.worktrees/` to `.git/info/exclude` if not present.
+     * Idempotent. Per-clone (not committed).
+     */
+    static ensureExcludeEntry(targetRepoPath: string): void;
+}
+//# sourceMappingURL=ProjectRoundWorktrees.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectRoundWorktrees.d.ts","sourceRoot":"","sources":["../../src/core/ProjectRoundWorktrees.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,qFAAqF;IACrF,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,qBAAqB;IAChC,qDAAqD;IACrD,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM;IAU5C;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,GAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,cAAc;IAiB9F;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;IAO1C;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAczC;;;OAGG;IACH,MAAM,CAAC,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;CA0BxD"}